@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Listbox/Listbox.module.scss

@@ -1,20 +1,13 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
-
-// ============================================
-// Listbox container
-// ============================================
+@use "../../recipes/popup" as popup;
+@use "../../recipes/typography" as typography;
 
 .listbox {
-  @include surface-elevated;
-  @include popup-container;
-
-  @include popup-scroll-viewport;
+  @include popup.container;
+  @include popup.viewport;
 
-  min-width: 12rem;
-  // Show N items + half-peek scroll hint (default 4.5 items).
-  max-height: var(--_popup-scroll-max-h);
-  overflow-y: auto;
+  min-inline-size: var(--fui-listbox-min-inline, 192px);
   border-color: var(--fui-form-group-border, $fui-border);
 
   &:focus-visible {
@@ -22,85 +15,64 @@
   }
 }
 
-// ============================================
-// Listbox item
-// ============================================
-
 .item {
-  @include popup-item;
+  @include popup.row;
 
-  text-align: left;
+  text-align: start;
 
-  // Pointer-hover and keyboard-active share the one neutral highlight (see _mixins).
   &:hover,
   &[data-highlighted] {
-    @include popup-item-highlight;
+    @include popup.highlight-state;
   }
 
-  // Listbox items are individually focusable, so keep the keyboard ring on top.
   &:focus-visible {
     @include focus-ring;
   }
 }
 
-.itemSelected {
-  @include popup-item-selected;
-}
-
 .itemActive {
-  &:not(.itemSelected) {
-    @include popup-item-highlight;
-  }
+  @include popup.highlight-state;
 }
 
-.itemActive.itemSelected {
-  @include popup-item-selected;
+.itemSelected {
+  @include popup.selected-state;
 }
 
 .itemDisabled {
-  @include popup-item-disabled;
+  @include popup.disabled-state;
 }
 
-// ============================================
-// Group
-// ============================================
+.group:not(:first-child)::before {
+  @include popup.group-separator;
 
-.group {
-  &:not(:first-child) {
-    margin-top: var(--fui-space-1, $fui-space-1);
-    padding-top: var(--fui-space-1, $fui-space-1);
-    border-top: 1px solid var(--fui-border, $fui-border);
-  }
+  content: "";
+  display: block;
 }
 
 .groupLabel {
-  @include popup-group-label;
+  @include popup.group-label;
 }
 
-// ============================================
-// Empty state
-// ============================================
-
 .empty {
-  @include text-base;
+  @include typography.role("body-compact");
 
-  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
+  padding-block: var(--fui-popup-row-block-inset);
+  padding-inline: var(--fui-popup-row-inline-inset);
   color: var(--fui-text-tertiary, $fui-text-tertiary);
   text-align: center;
 }
 
-// ============================================
-// Accessibility: High Contrast Mode
-// ============================================
-
 @media (prefers-contrast: more) {
   .listbox {
-    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+    outline: var(--fui-stroke-hairline, 1px) solid var(--fui-text-primary, $fui-text-primary);
+    outline-offset: calc(-1 * var(--fui-stroke-default, 2px));
   }
 
   .itemSelected,
   .itemActive {
-    outline: 2px solid var(--fui-color-accent, $fui-color-accent);
-    outline-offset: -2px;
+    outline: var(--fui-focus-ring-width, $fui-focus-ring-width) solid
+      var(--fui-color-accent, $fui-color-accent);
+    outline-offset: calc(-1 * var(--fui-focus-ring-width, $fui-focus-ring-width));
   }
 }

package/src/components/Loading/Loading.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Loading",
-  "description": "Versatile loading indicator with multiple variants for showing progress or waiting states",
+  "description": "Signals that something is happening when you cannot say how long it will take.",
   "category": "feedback",
-  "tags": [
-    "loading",
-    "spinner",
-    "progress",
-    "feedback",
-    "indicator",
-    "async"
-  ],
+  "tags": ["loading", "spinner", "progress", "feedback", "indicator", "async"],
   "status": "stable",
   "sourcePath": "src/components/Loading/index.tsx",
   "exportName": "Loading",
@@ -29,23 +22,14 @@
       "description": "Size of the loading indicator",
       "default": "md",
       "required": false,
-      "values": [
-        "sm",
-        "md",
-        "lg",
-        "xl"
-      ]
+      "values": ["sm", "md", "lg", "xl"]
     },
     "variant": {
       "type": "enum",
       "description": "Visual style of the loading animation",
       "default": "spinner",
       "required": false,
-      "values": [
-        "spinner",
-        "dots",
-        "pulse"
-      ]
+      "values": ["spinner", "dots", "pulse"]
     },
     "label": {
       "type": "string",
@@ -76,87 +60,79 @@
       "description": "Color variant - accent uses theme color, current inherits text color",
       "default": "accent",
       "required": false,
-      "values": [
-        "accent",
-        "current",
-        "muted"
-      ]
+      "values": ["accent", "current", "muted"]
     }
   },
   "usage": {
     "when": [
-      "Indicating content is being fetched or processed",
-      "Showing a pending state while waiting for an async operation",
-      "Displaying loading state for buttons, forms, or page sections",
-      "Full-screen loading during initial app/page load"
+      "Fetching or processing content",
+      "Waiting on an async action to come back",
+      "Buttons, forms, and page sections mid-request",
+      "The first paint of an app or page"
     ],
     "whenNot": [
-      "For showing determinate progress - use Progress component instead",
-      "For showing skeleton placeholders - use Skeleton component instead",
-      "For AI-specific thinking states - use ThinkingIndicator instead"
+      "You know the percentage — use Progress",
+      "You know the page shape — use Skeleton",
+      "AI reasoning states — use ThinkingIndicator"
     ],
     "guidelines": [
-      "Use spinner variant for general loading states",
-      "Use dots variant for chat/messaging contexts",
-      "Use pulse variant for subtle, ambient loading",
-      "Always provide a meaningful label for screen readers",
-      "Consider using Loading.Screen for initial page loads",
-      "Use Loading.Inline when loading indicator should flow with text"
+      "spinner for general waits",
+      "dots for chat and messaging",
+      "pulse for quiet ambient waiting",
+      "Always pass a label describing what is loading",
+      "Loading.Screen for first page load, Loading.Inline to sit inside a sentence"
     ],
     "accessibility": [
-      "Component uses role=\"status\" and aria-live=\"polite\"",
-      "Always provide descriptive label prop for screen readers",
-      "Animations respect prefers-reduced-motion preference"
+      "Announced through role=\"status\" with aria-live=\"polite\"",
+      "label is what a screen reader reads — make it specific",
+      "Animation stops for prefers-reduced-motion"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Default spinner loading indicator",
-      "code": "<Loading />"
+      "description": "Spinner at medium size, accent coloured.",
+      "code": "<Loading label=\"Loading content\" />"
     },
     {
       "name": "Sizes",
-      "description": "Loading indicators in different sizes",
-      "code": "<div style={{ display: 'flex', alignItems: 'center', gap: '24px' }}>\n  <Loading size=\"sm\" />\n  <Loading size=\"md\" />\n  <Loading size=\"lg\" />\n  <Loading size=\"xl\" />\n</div>"
+      "description": "sm inside controls, xl for a whole page.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"lg\" align=\"center\">\n  <Loading size=\"sm\" label=\"Loading\" />\n  <Loading size=\"md\" label=\"Loading\" />\n  <Loading size=\"lg\" label=\"Loading\" />\n  <Loading size=\"xl\" label=\"Loading\" />\n</Stack>"
     },
     {
       "name": "Dots",
-      "description": "Bouncing dots animation",
-      "code": "<Loading variant=\"dots\" />"
+      "description": "Three bouncing dots, at home in a message thread.",
+      "code": "<Loading variant=\"dots\" label=\"Sending message\" />"
     },
     {
       "name": "Pulse",
-      "description": "Pulsing circle animation",
-      "code": "<Loading variant=\"pulse\" />"
+      "description": "One breathing dot for ambient background work.",
+      "code": "<Loading variant=\"pulse\" label=\"Syncing\" />"
     },
     {
       "name": "Colors",
-      "description": "Different color variants",
-      "code": "<div style={{ display: 'flex', alignItems: 'center', gap: '24px' }}>\n  <Loading color=\"accent\" />\n  <Loading color=\"muted\" />\n  <span style={{ color: '#3b82f6' }}>\n    <Loading color=\"current\" />\n  </span>\n</div>"
+      "description": "Accent, muted, or whatever the surrounding text is.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"lg\" align=\"center\">\n  <Loading color=\"accent\" label=\"Loading\" />\n  <Loading color=\"muted\" label=\"Loading\" />\n  <span style={{ color: 'var(--fui-color-info)' }}>\n    <Loading color=\"current\" label=\"Loading\" />\n  </span>\n</Stack>"
     },
     {
       "name": "Inline",
-      "description": "Inline loading indicator that flows with text",
-      "code": "<p style={{ margin: 0 }}>\n  Processing your request <Loading.Inline /> please wait...\n</p>"
+      "description": "Sits on the text baseline mid-sentence.",
+      "code": "<p style={{ margin: 0 }}>\n  Processing your request <Loading.Inline label=\"Processing\" /> please wait…\n</p>"
     },
     {
       "name": "Centered",
-      "description": "Centered in container",
-      "code": "<div style={{ width: '200px', height: '100px', border: '1px dashed #ccc', borderRadius: '8px' }}>\n  <Loading centered fill />\n</div>"
+      "description": "Fills its container and centres in it.",
+      "code": "<div\n  style={{\n    width: '200px',\n    height: '100px',\n    border: '1px dashed var(--fui-border)',\n    borderRadius: 'var(--fui-radius-md)',\n  }}\n>\n  <Loading centered fill label=\"Loading section\" />\n</div>"
     },
     {
       "name": "Screen",
-      "description": "Full-screen loading state with optional label",
-      "code": "<div style={{ position: 'relative', width: '300px', height: '200px', border: '1px solid #ccc', borderRadius: '8px', overflow: 'hidden', transform: 'scale(1)' }}>\n  <Loading.Screen size=\"lg\" label=\"Loading application...\" showLabel />\n</div>"
+      "description": "Covers the surface it sits on and names the wait.",
+      "code": "<div\n  style={{\n    position: 'relative',\n    contain: 'layout',\n    width: '300px',\n    height: '200px',\n    border: '1px solid var(--fui-border)',\n    borderRadius: 'var(--fui-radius-md)',\n    overflow: 'hidden',\n  }}\n>\n  <Loading.Screen size=\"lg\" label=\"Loading application…\" showLabel />\n</div>"
     }
   ],
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Inline",
-      "Screen"
-    ]
+    "subComponents": ["Inline", "Screen"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Loading/Loading.module.scss

@@ -1,5 +1,6 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../recipes/representation" as representation;
+@use "../../recipes/typography" as typography;
 
 // ============================================
 // Loading Base
@@ -9,30 +10,17 @@
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  flex-shrink: 0;
+  flex: 0 0 auto;
 }
 
 // ============================================
 // Sizes
 // ============================================
 
-// Sizes ride the shared `--fui-icon-*` ladder. The step names are offset by one
-// (sm→icon-sm, md→icon-lg, lg→icon-xl, xl→icon-2xl), intentionally skipping
-// icon-md so the rendered px stays 14/20/24/32 for existing consumers.
-.sm {
-  --loading-size: var(--fui-icon-sm, #{$fui-icon-sm});  // 14px
-}
-
-.md {
-  --loading-size: var(--fui-icon-lg, #{$fui-icon-lg});  // 20px
-}
-
-.lg {
-  --loading-size: var(--fui-icon-xl, #{$fui-icon-xl});  // 24px
-}
-
-.xl {
-  --loading-size: var(--fui-icon-2xl, #{$fui-icon-2xl});  // 32px
+@each $size in ("sm", "md", "lg", "xl") {
+  .#{$size} {
+    @include representation.activity($size);
+  }
 }
 
 // ============================================
@@ -62,8 +50,8 @@
 }
 
 .fill {
-  width: 100%;
-  height: 100%;
+  inline-size: 100%;
+  block-size: 100%;
   display: flex;
   align-items: center;
   justify-content: center;
@@ -74,9 +62,9 @@
 // ============================================
 
 .spinnerIcon {
-  width: var(--loading-size);
-  height: var(--loading-size);
-  animation: spin 0.8s linear infinite;
+  inline-size: 100%;
+  block-size: 100%;
+  animation: spin var(--fui-duration-spin, $fui-duration-spin) linear infinite;
 
   @media (prefers-reduced-motion: reduce) {
     animation: none;
@@ -97,18 +85,23 @@
 // Dots Variant
 // ============================================
 
-.dots {
+// `.dots`/`.pulse` on the root are variant hooks only — sizing lives on the
+// inner track. Sharing one class between root and track let the track's
+// 100% × 100% override the root's fixed activity footprint (rendered 0 × 0).
+.dotsTrack {
   display: flex;
   align-items: center;
-  gap: calc(var(--loading-size) * 0.3);
+  justify-content: space-between;
+  inline-size: 100%;
+  block-size: 100%;
 }
 
 .dot {
-  width: calc(var(--loading-size) * 0.35);
-  height: calc(var(--loading-size) * 0.35);
+  inline-size: 25%;
+  block-size: 25%;
   border-radius: var(--fui-radius-full, $fui-radius-full);
   background-color: currentColor;
-  animation: bounce 1.4s ease-in-out infinite;
+  animation: bounce var(--fui-duration-pulse, $fui-duration-pulse) ease-in-out infinite;
 
   &:nth-child(1) {
     animation-delay: 0s;
@@ -145,10 +138,10 @@
 // Pulse Variant
 // ============================================
 
-.pulse {
+.pulseTrack {
   position: relative;
-  width: var(--loading-size);
-  height: var(--loading-size);
+  inline-size: 100%;
+  block-size: 100%;
   display: flex;
   align-items: center;
   justify-content: center;
@@ -161,7 +154,7 @@
   border-radius: var(--fui-radius-full, $fui-radius-full);
   background-color: currentColor;
   opacity: 0.3;
-  animation: pulseRing 1.5s ease-out infinite;
+  animation: pulseRing var(--fui-duration-pulse, $fui-duration-pulse) ease-out infinite;
 
   @media (prefers-reduced-motion: reduce) {
     animation: none;
@@ -199,7 +192,7 @@
   align-items: center;
   justify-content: center;
   background-color: var(--fui-backdrop, $fui-backdrop);
-  z-index: 50;
+  z-index: var(--fui-overlay-layer-backdrop, 50);
 }
 
 .overlay {
@@ -217,7 +210,7 @@
 }
 
 .inline-sm {
-  --inline-size: 0.875em;  // Relative to surrounding text
+  --inline-size: 0.875em; // Relative to surrounding text
 }
 
 .inline-md {
@@ -227,7 +220,7 @@
 .inlineSpinner {
   width: var(--inline-size);
   height: var(--inline-size);
-  animation: spin 0.8s linear infinite;
+  animation: spin var(--fui-duration-spin, $fui-duration-spin) linear infinite;
   color: currentColor;
 
   @media (prefers-reduced-motion: reduce) {
@@ -247,13 +240,13 @@
   flex-direction: column;
   align-items: center;
   justify-content: center;
-  gap: var(--fui-space-3, $fui-space-3);
+  gap: var(--fui-raw-space-12, 12px);
   background-color: var(--fui-bg-primary, $fui-bg-primary);
   z-index: 100;
 }
 
 .screenLabel {
-  @include text-base;
-  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  @include typography.role("body-compact");
+
   color: var(--fui-text-secondary, $fui-text-secondary);
 }