@usefragments/ui 1.6.0 → 1.7.0

package/src/components/ThemeToggle/index.tsx

@@ -5,9 +5,14 @@ import { useResolvedControlSize } from "../ComponentDefaults";
 import { useTheme, type ThemeMode } from "../Theme/context";
 import styles from "./ThemeToggle.module.scss";
 
-export interface ThemeToggleProps extends React.HTMLAttributes<HTMLDivElement> {
+export interface ThemeToggleProps extends React.HTMLAttributes<HTMLElement> {
   /** Size of the toggle button */
   size?: "sm" | "md" | "lg";
+  /**
+   * `group` is the segmented light/dark control. `icon` is a single button
+   * that shows the current resolved theme and toggles light ↔ dark.
+   */
+  appearance?: "group" | "icon";
   /** Whether to include system mode option (default: false) */
   showSystem?: boolean;
   /** Controlled value for custom usage (bypasses theme context) */
@@ -71,6 +76,7 @@ function MonitorIcon({ size = 20 }: { size?: number }) {
  */
 export function ThemeToggle({
   size: sizeProp,
+  appearance = "group",
   showSystem = false,
   value: controlledValue,
   onValueChange,
@@ -79,10 +85,44 @@ export function ThemeToggle({
   ...htmlProps
 }: ThemeToggleProps) {
   const size = useResolvedControlSize(sizeProp);
-  const { mode: contextMode, setMode: setContextMode } = useTheme();
+  const {
+    mode: contextMode,
+    setMode: setContextMode,
+    resolvedMode,
+    toggleMode,
+  } = useTheme();
 
   const isControlled = controlledValue !== undefined;
   const currentMode = isControlled ? controlledValue : contextMode;
+  const sizeClass = styles[`size${size.charAt(0).toUpperCase() + size.slice(1)}`];
+
+  if (appearance === "icon") {
+    const resolved = isControlled ? controlledValue : resolvedMode;
+    const nextMode = resolved === "dark" ? "light" : "dark";
+    const iconClasses = [styles.toggleButton, styles.iconButton, sizeClass, className]
+      .filter(Boolean)
+      .join(" ");
+
+    return (
+      <button
+        {...(htmlProps as React.ButtonHTMLAttributes<HTMLButtonElement>)}
+        type="button"
+        className={iconClasses}
+        onClick={() => {
+          if (isControlled) {
+            onValueChange?.(nextMode);
+          } else {
+            toggleMode();
+          }
+        }}
+        aria-label={
+          ariaLabel ?? (resolved === "dark" ? "Switch to light mode" : "Switch to dark mode")
+        }
+      >
+        {resolved === "dark" ? <MoonIcon /> : <SunIcon />}
+      </button>
+    );
+  }
 
   const handleModeChange = (newMode: "light" | "dark") => {
     if (isControlled) {
@@ -92,11 +132,7 @@ export function ThemeToggle({
     }
   };
 
-  const groupClasses = [
-    styles.toggleGroup,
-    styles[`size${size.charAt(0).toUpperCase() + size.slice(1)}`],
-    className,
-  ]
+  const groupClasses = [styles.toggleGroup, sizeClass, className]
     .filter(Boolean)
     .join(" ");
 

package/src/components/ThinkingIndicator/ThinkingIndicator.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "ThinkingIndicator",
-  "description": "Animated indicator showing AI is processing",
+  "description": "Shows that an AI response is being generated.",
   "category": "ai",
-  "tags": [
-    "thinking",
-    "loading",
-    "ai",
-    "processing",
-    "indicator",
-    "animation"
-  ],
+  "tags": ["thinking", "loading", "ai", "processing", "indicator", "animation"],
   "status": "stable",
   "sourcePath": "src/components/ThinkingIndicator/index.tsx",
   "exportName": "ThinkingIndicator",
@@ -39,11 +32,7 @@
       "description": "Animation style",
       "default": "dots",
       "required": false,
-      "values": [
-        "dots",
-        "pulse",
-        "spinner"
-      ]
+      "values": ["dots", "pulse", "spinner"]
     },
     "showElapsed": {
       "type": "boolean",
@@ -59,21 +48,21 @@
   },
   "usage": {
     "when": [
-      "AI is processing a request and generating a response",
-      "Need visual feedback during async AI operations",
-      "Want to show multi-step progress for complex AI tasks",
-      "Indicating streaming is about to begin"
+      "A model is working on a request",
+      "Async AI work that would otherwise look frozen",
+      "Multi-stage tasks worth showing stage by stage",
+      "The moment before streaming starts"
     ],
     "whenNot": [
-      "Simple loading states (use Progress or Skeleton)",
-      "Form submission loading (use Button loading state)",
-      "Page-level loading (use Progress or Skeleton)"
+      "Ordinary loading (use Progress or Skeleton)",
+      "Form submission (use the Button loading state)",
+      "Whole-page loading (use Progress or Skeleton)"
     ],
     "guidelines": [
-      "Use active prop to control visibility",
-      "Choose variant based on context (dots for chat, spinner for actions)",
-      "Enable showElapsed for longer operations",
-      "Use steps for multi-step AI workflows (tool calls, research)"
+      "active controls whether it shows at all",
+      "dots suits chat; spinner suits a discrete action",
+      "Turn on showElapsed once waits run past a few seconds",
+      "Use steps for tool calls, research, and other staged work"
     ],
     "accessibility": [
       "Uses role=\"status\" and aria-live=\"polite\"",
@@ -85,37 +74,37 @@
   "examples": [
     {
       "name": "Dots (Default)",
-      "description": "Bouncing dots animation",
+      "description": "Three dots bounce in sequence; the quietest option.",
       "code": "<ThinkingIndicator variant=\"dots\" label=\"Thinking...\" />"
     },
     {
       "name": "Pulse",
-      "description": "Pulsing ring animation",
+      "description": "A single ring breathes in place.",
       "code": "<ThinkingIndicator variant=\"pulse\" label=\"Processing...\" />"
     },
     {
       "name": "Spinner",
-      "description": "Rotating spinner animation",
+      "description": "A rotating arc, for work with a definite end.",
       "code": "<ThinkingIndicator variant=\"spinner\" label=\"Loading...\" />"
     },
     {
       "name": "With Elapsed Time",
-      "description": "Shows time since started",
+      "description": "A live counter reassures the reader during long waits.",
       "code": "<ThinkingIndicator\n  variant=\"dots\"\n  label=\"Generating response...\"\n  showElapsed\n/>"
     },
     {
       "name": "Multi-Step Progress",
-      "description": "Shows progress through multiple steps",
+      "description": "Finished, running, and queued stages read at a glance.",
       "code": "<ThinkingIndicator\n  variant=\"spinner\"\n  label=\"Working...\"\n  steps={[\n    { id: '1', label: 'Analyzing request', status: 'complete' },\n    { id: '2', label: 'Searching knowledge base', status: 'active' },\n    { id: '3', label: 'Generating response', status: 'pending' },\n  ]}\n/>"
     },
     {
       "name": "With Error Step",
-      "description": "Shows a step that encountered an error",
+      "description": "A failed stage turns red while the next one retries.",
       "code": "<ThinkingIndicator\n  variant=\"spinner\"\n  label=\"Retrying...\"\n  steps={[\n    { id: '1', label: 'Connecting to API', status: 'complete' },\n    { id: '2', label: 'Fetching data', status: 'error' },\n    { id: '3', label: 'Retrying with fallback', status: 'active' },\n  ]}\n/>"
     },
     {
       "name": "Custom Label",
-      "description": "Custom status text",
+      "description": "Name the actual task instead of a generic status.",
       "code": "<ThinkingIndicator\n  variant=\"dots\"\n  label=\"Claude is writing code...\"\n/>"
     }
   ],
@@ -144,17 +133,11 @@
       "showElapsed: boolean - show elapsed time",
       "steps: ThinkingStep[] - multi-step progress"
     ],
-    "a11yRules": [
-      "A11Y_ARIA_LIVE",
-      "A11Y_MOTION_PREFERENCE"
-    ]
+    "a11yRules": ["A11Y_ARIA_LIVE", "A11Y_MOTION_PREFERENCE"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Steps",
-      "Step"
-    ]
+    "subComponents": ["Steps", "Step"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Toast/Toast.contract.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Toast",
-  "description": "Brief, non-blocking notification messages",
+  "description": "Briefly reports what just happened, without blocking the page.",
   "category": "feedback",
   "tags": ["notification", "alert", "message", "feedback"],
   "status": "stable",
@@ -70,62 +70,52 @@
   },
   "usage": {
     "when": [
-      "Providing feedback after an action",
-      "Showing success/error status of operations",
-      "Non-critical information that doesn't require action",
-      "Temporary messages that auto-dismiss"
+      "Confirming an action landed",
+      "Reporting whether an operation worked",
+      "News the user does not have to act on",
+      "Messages that can disappear on their own"
     ],
     "whenNot": [
-      "Critical errors requiring user action (use Dialog)",
-      "Persistent information (use Alert)",
-      "Inline validation (use form error states)",
-      "System-wide announcements (use Banner)"
+      "Errors the user must resolve — use Dialog",
+      "Anything that must stay on screen — use Alert",
+      "Field-level validation — use form error states",
+      "Site-wide notices — use a banner"
     ],
     "guidelines": [
-      "Keep messages brief and actionable",
-      "Use appropriate variant for the message type",
-      "Auto-dismiss after reasonable duration (3-5s)",
-      "Allow manual dismissal for longer messages",
-      "Limit number of simultaneous toasts",
-      "useToast() variant helpers accept either (title, description?) or an options object for action/duration/id"
+      "One sentence, plus a title if it helps",
+      "Match the variant to what actually happened",
+      "Auto-dismiss in three to five seconds",
+      "Anything with an action needs a manual dismiss too",
+      "Two or three on screen at once, no more",
+      "useToast() helpers take (title, description) or an options object for action, duration, and id"
     ],
     "accessibility": [
-      "Use role=\"alert\" for important messages",
-      "Ensure sufficient display time for reading",
-      "Don't rely solely on color for meaning",
-      "Provide dismiss button with accessible label"
+      "role=\"alert\" for anything the user must not miss",
+      "Leave enough time to read it",
+      "Never let colour be the only signal",
+      "Give the dismiss button a real label"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Interactive toast demo - click buttons to trigger toasts (includes helper object syntax example)",
-      "code": "<ToastDemoWrapper />"
+      "description": "Neutral message with a title and one line under it.",
+      "code": "<Toast\n  title=\"Draft saved\"\n  description=\"We will keep it until you publish.\"\n/>"
     },
     {
-      "name": "Success",
-      "description": "Success message variant",
-      "code": "<Toast\n  title=\"Success!\"\n  description=\"Your changes have been saved.\"\n  variant=\"success\"\n/>"
+      "name": "Variants",
+      "description": "Icon and colour together carry the outcome.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"column\" gap=\"sm\">\n  <Toast\n    title=\"Success!\"\n    description=\"Your changes have been saved.\"\n    variant=\"success\"\n  />\n  <Toast\n    title=\"Error\"\n    description=\"Failed to save changes. Please try again.\"\n    variant=\"error\"\n  />\n  <Toast\n    title=\"Warning\"\n    description=\"This action cannot be undone.\"\n    variant=\"warning\"\n  />\n  <Toast\n    title=\"New update\"\n    description=\"Version 2.0 is now available.\"\n    variant=\"info\"\n  />\n</Stack>"
     },
     {
-      "name": "Error",
-      "description": "Error message variant",
-      "code": "<Toast\n  title=\"Error\"\n  description=\"Failed to save changes. Please try again.\"\n  variant=\"error\"\n/>"
-    },
-    {
-      "name": "Warning",
-      "description": "Warning message variant",
-      "code": "<Toast\n  title=\"Warning\"\n  description=\"This action cannot be undone.\"\n  variant=\"warning\"\n/>"
-    },
-    {
-      "name": "Info",
-      "description": "Informational message variant",
-      "code": "<Toast\n  title=\"New Update\"\n  description=\"Version 2.0 is now available.\"\n  variant=\"info\"\n/>"
+      "name": "With Action",
+      "description": "One-tap way back from something destructive.",
+      "code": "<Toast\n  title=\"File deleted\"\n  description=\"The file has been moved to trash.\"\n  action={{\n    label: 'Undo',\n    onClick: () => {},\n  }}\n/>"
     },
     {
-      "name": "With Action",
-      "description": "Toast with an action button",
-      "code": "<Toast\n  title=\"File deleted\"\n  description=\"The file has been moved to trash.\"\n  action={{\n    label: 'Undo',\n    onClick: () => console.log('Undo clicked'),\n  }}\n/>"
+      "name": "Dismissible",
+      "description": "onDismiss adds a close button for longer messages.",
+      "code": "<Toast\n  title=\"Export running\"\n  description=\"We will email you when the file is ready.\"\n  variant=\"info\"\n  onDismiss={() => {}}\n/>"
     }
   ],
   "relations": [

package/src/components/Toast/Toast.module.scss

@@ -68,7 +68,7 @@
 @keyframes toastEnter {
   from {
     opacity: 0;
-    transform: translateY($fui-anim-offset-md) scale(0.96);
+    transform: translateY(var(--fui-anim-offset-md, #{$fui-anim-offset-md})) scale(0.95);
   }
 
   to {

package/src/components/ToggleGroup/ToggleGroup.contract.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "ToggleGroup",
-  "description": "A group of toggle buttons where only one can be selected at a time. Useful for switching between views, modes, or options.",
-  "category": "forms",
+  "description": "Picks exactly one option from a short row of toggle buttons.",
+  "category": "actions",
   "tags": ["toggle", "group", "fragmented", "control", "tabs", "switch"],
   "status": "stable",
   "sourcePath": "src/components/ToggleGroup/index.tsx",
@@ -75,64 +75,63 @@
   "usage": {
     "when": [
       "Switching between mutually exclusive views or modes",
-      "Selecting one option from a small set (2-5 options)",
-      "Fragmented controls like view switchers",
-      "Filter or sort options"
+      "Choosing one of two to five options",
+      "View switchers and segmented filters"
     ],
     "whenNot": [
-      "Multiple selections allowed (use Checkbox group)",
-      "Many options (use Select or RadioGroup)",
-      "Navigation between pages (use Tabs)",
-      "On/off toggle (use Switch component)"
+      "More than one can be picked — use a Checkbox group",
+      "More than five options — use Select or RadioGroup",
+      "Moving between pages — use Tabs",
+      "A single on/off — use Switch"
     ],
     "guidelines": [
-      "Keep options to 2-5 items for clarity",
-      "Use clear, concise labels",
-      "Consider icons for common actions (grid/list view)",
-      "Use default for an inset tonal rail, pills for an open filter cluster, and outline for connected bordered segments",
-      "Ensure adequate touch targets on mobile"
+      "Two to five items",
+      "Labels short enough to scan in one pass",
+      "Icons work for well-known modes like grid and list",
+      "default for an inset tonal rail, pills for an open filter cluster, outlined for connected segments",
+      "Keep targets at least 24px on touch"
     ],
     "accessibility": [
-      "Uses role=\"radiogroup\" for single-selection semantics",
-      "Each item has role=\"radio\" with aria-checked",
-      "Keyboard navigable with Tab and arrow keys",
-      "Focus visible on active item"
+      "The group is a radiogroup; each item is a radio with aria-checked",
+      "Arrow keys move between items, Tab enters and leaves the group",
+      "Icon-only items still need an aria-label",
+      "Focus stays visible on the selected item"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic toggle group",
+      "description": "Inset tonal rail; the selected segment lifts.",
       "code": "<ToggleGroup value={value} onChange={setValue}>\n  <ToggleGroup.Item value=\"left\">Left</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"center\">Center</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"right\">Right</ToggleGroup.Item>\n</ToggleGroup>"
     },
     {
-      "name": "Pills Variant",
-      "description": "Pill-shaped toggle buttons",
+      "name": "Pills",
+      "description": "Detached rounded buttons for open filter clusters.",
       "code": "<ToggleGroup value={value} onChange={setValue} variant=\"pills\">\n  <ToggleGroup.Item value=\"all\">All</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"active\">Active</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"completed\">Completed</ToggleGroup.Item>\n</ToggleGroup>"
     },
     {
-      "name": "Outline Variant",
-      "description": "Outlined toggle buttons",
+      "name": "Outlined",
+      "description": "Bordered segments sharing one continuous edge.",
       "code": "<ToggleGroup value={value} onChange={setValue} variant=\"outlined\">\n  <ToggleGroup.Item value=\"day\">Day</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"week\">Week</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"month\">Month</ToggleGroup.Item>\n</ToggleGroup>"
     },
     {
       "name": "Uncontrolled",
-      "description": "Use defaultValue for simple single-select state",
+      "description": "defaultValue when nothing outside needs the selection.",
       "code": "<ToggleGroup defaultValue=\"list\">\n  <ToggleGroup.Item value=\"grid\">Grid</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"list\">List</ToggleGroup.Item>\n</ToggleGroup>"
     },
     {
       "name": "Sizes",
-      "description": "Different size variants",
-      "code": "<ToggleGroup value={value} onChange={setValue} size=\"sm\">\n  <ToggleGroup.Item value=\"a\">Small</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"b\">Size</ToggleGroup.Item>\n</ToggleGroup>\n<ToggleGroup value={value} onChange={setValue} size=\"md\">\n  <ToggleGroup.Item value=\"a\">Medium</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"b\">Size</ToggleGroup.Item>\n</ToggleGroup>"
+      "description": "sm for toolbars, lg where the rail anchors a page.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"column\" gap=\"md\" align=\"start\">\n  <ToggleGroup defaultValue=\"a\" size=\"sm\">\n    <ToggleGroup.Item value=\"a\">Small</ToggleGroup.Item>\n    <ToggleGroup.Item value=\"b\">Rail</ToggleGroup.Item>\n  </ToggleGroup>\n  <ToggleGroup defaultValue=\"a\" size=\"md\">\n    <ToggleGroup.Item value=\"a\">Medium</ToggleGroup.Item>\n    <ToggleGroup.Item value=\"b\">Rail</ToggleGroup.Item>\n  </ToggleGroup>\n  <ToggleGroup defaultValue=\"a\" size=\"lg\">\n    <ToggleGroup.Item value=\"a\">Large</ToggleGroup.Item>\n    <ToggleGroup.Item value=\"b\">Rail</ToggleGroup.Item>\n  </ToggleGroup>\n</Stack>"
     },
     {
       "name": "View Switcher",
-      "description": "Common pattern for switching between views",
-      "code": "<ToggleGroup value={view} onChange={setView} size=\"sm\">\n  <ToggleGroup.Item value=\"grid\"><GridIcon /></ToggleGroup.Item>\n  <ToggleGroup.Item value=\"list\"><ListIcon /></ToggleGroup.Item>\n</ToggleGroup>"
+      "description": "Icon-only modes, each named for screen readers.",
+      "code": "import { SquaresFour as GridIcon, ListBullets as ListIcon } from '@phosphor-icons/react';\n\n<ToggleGroup value={view} onChange={setView} size=\"sm\">\n  <ToggleGroup.Item value=\"grid\" aria-label=\"Grid view\">\n    <GridIcon aria-hidden />\n  </ToggleGroup.Item>\n  <ToggleGroup.Item value=\"list\" aria-label=\"List view\">\n    <ListIcon aria-hidden />\n  </ToggleGroup.Item>\n</ToggleGroup>"
     },
     {
-      "name": "With Disabled Item",
-      "description": "Toggle group with a disabled option",
+      "name": "Disabled Item",
+      "description": "One option locked out; the rest stay reachable.",
       "code": "<ToggleGroup value={value} onChange={setValue}>\n  <ToggleGroup.Item value=\"basic\">Basic</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"pro\">Pro</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"enterprise\" disabled>Enterprise</ToggleGroup.Item>\n</ToggleGroup>"
     }
   ],

package/src/components/ToggleGroup/ToggleGroup.module.scss

@@ -34,7 +34,6 @@
   position: relative;
   border: 0;
   white-space: nowrap;
-  user-select: none;
   transition:
     background-color var(--fui-transition-fast, $fui-transition-fast),
     border-color var(--fui-transition-fast, $fui-transition-fast),
@@ -112,14 +111,36 @@
       var(--_fui-segmented-track) - var(--fui-raw-space-2, 2px) - var(--fui-raw-space-2, 2px)
     );
     background-color: transparent;
-    border-radius: var(--fui-radius-md, $fui-radius-md);
+    // Connected segments: only outer corners are rounded. Per-item full radius
+    // left a rail-colored notch between items that reads as a gap.
+    border-radius: 0;
+
+    &:first-child {
+      border-start-start-radius: var(--fui-radius-md, $fui-radius-md);
+      border-end-start-radius: var(--fui-radius-md, $fui-radius-md);
+    }
+
+    &:last-child {
+      border-start-end-radius: var(--fui-radius-md, $fui-radius-md);
+      border-end-end-radius: var(--fui-radius-md, $fui-radius-md);
+    }
+
+    &:only-child {
+      border-radius: var(--fui-radius-md, $fui-radius-md);
+    }
 
     &:hover:not(:disabled):not(.selected) {
       background-color: var(--fui-bg-hover, $fui-bg-hover);
     }
 
     &.selected {
-      background-color: var(--fui-toggle-group-selected-bg, var(--fui-selection-bg));
+      background-color: var(
+        --fui-toggle-group-selected-bg,
+        var(
+          --fui-control-selected-bg,
+          color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 9%, transparent)
+        )
+      );
       box-shadow:
         inset 0 0 0 var(--fui-stroke-hairline, 1px)
           var(--fui-toggle-group-selected-border, transparent),
@@ -143,7 +164,13 @@
     }
 
     &.selected {
-      background-color: var(--fui-toggle-group-selected-bg, var(--fui-selection-bg));
+      background-color: var(
+        --fui-toggle-group-selected-bg,
+        var(
+          --fui-control-selected-bg,
+          color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 9%, transparent)
+        )
+      );
       box-shadow:
         inset 0 0 0 var(--fui-stroke-hairline, 1px)
           var(--fui-toggle-group-selected-border, transparent),
@@ -197,7 +224,13 @@
     }
 
     &.selected {
-      background-color: var(--fui-toggle-group-selected-bg, var(--fui-selection-bg));
+      background-color: var(
+        --fui-toggle-group-selected-bg,
+        var(
+          --fui-control-selected-bg,
+          color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 9%, transparent)
+        )
+      );
       box-shadow:
         inset 0 0 0 var(--fui-stroke-hairline, 1px)
           var(--fui-toggle-group-selected-border, transparent),