@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Textarea/Textarea.contract.json

@@ -1,14 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Textarea",
-  "description": "Multi-line text input for longer form content",
-  "category": "forms",
-  "tags": [
-    "input",
-    "text",
-    "form",
-    "multiline"
-  ],
+  "description": "Collects multi-line text for longer form content.",
+  "category": "inputs",
+  "tags": ["input", "text", "form", "multiline"],
   "status": "stable",
   "sourcePath": "src/components/Textarea/index.tsx",
   "exportName": "Textarea",
@@ -78,23 +73,14 @@
       "description": "Resize behavior",
       "default": "vertical",
       "required": false,
-      "values": [
-        "none",
-        "vertical",
-        "horizontal",
-        "both"
-      ]
+      "values": ["none", "vertical", "horizontal", "both"]
     },
     "size": {
       "type": "enum",
       "description": "Size variant",
       "default": "md",
       "required": false,
-      "values": [
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["sm", "md", "lg"]
     },
     "disabled": {
       "type": "boolean",
@@ -209,61 +195,61 @@
       "Selecting from predefined options (use Select)"
     ],
     "guidelines": [
-      "Set appropriate rows for expected content length",
-      "Use placeholder to show example format",
-      "Show character count when maxLength is set",
-      "Consider auto-resize for better UX"
+      "Set rows to match the expected answer length",
+      "Placeholder shows an example, not the label",
+      "Pair maxLength with showCharCount so the limit is visible",
+      "Use resize=\"none\" only when the layout truly cannot flex"
     ],
     "accessibility": [
-      "Always provide a visible label",
-      "Use helperText for format hints",
-      "Error messages should be descriptive"
+      "Give every textarea a visible label",
+      "Put format hints in helperText, not the placeholder",
+      "Error text says what to fix, not just that it failed"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic textarea with label",
+      "description": "Three rows, draggable from the bottom-right corner.",
       "code": "<Textarea\n  label=\"Description\"\n  placeholder=\"Enter a description...\"\n/>"
     },
     {
       "name": "With Helper Text",
-      "description": "Textarea with additional guidance",
+      "description": "Supporting text sits under the box.",
       "code": "<Textarea\n  label=\"Bio\"\n  placeholder=\"Tell us about yourself...\"\n  helperText=\"Max 500 characters\"\n  maxLength={500}\n/>"
     },
     {
       "name": "Error State",
-      "description": "Textarea showing validation error",
+      "description": "Red border, and helperText becomes the reason.",
       "code": "<Textarea\n  label=\"Comments\"\n  placeholder=\"Add your comments...\"\n  error\n  helperText=\"This field is required\"\n/>"
     },
     {
       "name": "Disabled",
-      "description": "Non-interactive textarea",
+      "description": "Dimmed and unfocusable.",
       "code": "<Textarea\n  label=\"Notes\"\n  placeholder=\"Cannot edit...\"\n  disabled\n/>"
     },
     {
       "name": "Custom Rows",
-      "description": "Textarea with more visible rows",
+      "description": "rows={6} doubles the visible height before scrolling.",
       "code": "<Textarea\n  label=\"Long Description\"\n  placeholder=\"Enter detailed information...\"\n  rows={6}\n/>"
     },
     {
       "name": "Sizes",
-      "description": "Available size variants",
+      "description": "Three heights: sm, md, lg.",
       "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px', maxWidth: '400px' }}>\n  <Textarea label=\"Small\" size=\"sm\" placeholder=\"Small textarea\" />\n  <Textarea label=\"Medium\" size=\"md\" placeholder=\"Medium textarea\" />\n  <Textarea label=\"Large\" size=\"lg\" placeholder=\"Large textarea\" />\n</div>"
     },
     {
-      "name": "With Root Props",
-      "description": "Pass wrapper attributes/styling via rootProps",
-      "code": "<Textarea\n  label=\"Notes\"\n  placeholder=\"Add notes...\"\n  rootProps={{ 'data-demo': 'textarea-wrapper' }}\n/>"
+      "name": "Fixed Height",
+      "description": "resize=\"none\" removes the drag handle so the box stays put.",
+      "code": "<Textarea\n  label=\"Notes\"\n  placeholder=\"Add notes...\"\n  resize=\"none\"\n/>"
     },
     {
       "name": "Success State",
-      "description": "Textarea showing validated/success styling",
+      "description": "Green border confirms the value passed validation.",
       "code": "<Textarea\n  label=\"Bio\"\n  value=\"A short bio about myself.\"\n  success\n  helperText=\"Looks great!\"\n/>"
     },
     {
       "name": "With Character Counter",
-      "description": "Textarea with character count and maxLength",
+      "description": "Live count against maxLength sits below the box.",
       "code": "<Textarea\n  label=\"Bio\"\n  placeholder=\"Tell us about yourself...\"\n  maxLength={200}\n  showCharCount\n/>"
     }
   ],
@@ -289,15 +275,11 @@
       "rootProps: HTMLAttributes<HTMLDivElement> - wrapper element props",
       "...native textarea attributes are supported (readOnly, autoComplete, maxLength, onKeyDown, etc.)"
     ],
-    "a11yRules": [
-      "A11Y_LABEL_REQUIRED"
-    ]
+    "a11yRules": ["A11Y_LABEL_REQUIRED"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Textarea/Textarea.module.scss

@@ -1,64 +1,85 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../tokens/measurements.generated" as measurements;
+@use "../../recipes/field";
+@use "../../recipes/layout";
+@use "../../recipes/typography";
 
-// Form field wrapper (label + helper + error)
-@include form-field-wrapper;
+.wrapper {
+  @include field.wrapper;
+}
+
+.label {
+  @include field.label;
+}
+
+.required {
+  margin-inline-start: var(--fui-raw-space-2, #{measurements.raw-space(2)});
+  color: var(--fui-color-danger-text, $fui-color-danger-text);
+}
+
+.helper {
+  @include field.helper;
+}
+
+.helperError,
+.errorMessage {
+  @include field.error;
+}
 
 .textarea {
-  @include text-base;
   @include interactive-base;
-  @include field-shell;
+  @include field.shell;
 
   display: block;
   width: 100%;
-  min-height: var(--fui-input-height, $fui-input-height);
-  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
-  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
-  font-family: inherit;
+  min-block-size: max(
+    var(--_fui-field-track),
+    calc(
+      var(--_fui-textarea-min-rows) * 1lh + 2 * var(--_fui-textarea-block-inset) + 2 *
+        var(--_fui-field-stroke)
+    )
+  );
+  max-block-size: calc(
+    var(--_fui-textarea-max-rows) * 1lh + 2 * var(--_fui-textarea-block-inset) + 2 *
+      var(--_fui-field-stroke)
+  );
+  padding-block: var(--_fui-textarea-block-inset);
 
   &::placeholder {
     color: var(--fui-text-tertiary, $fui-text-tertiary);
   }
 
   &:focus-visible {
-    @include field-shell-focus;
+    @include field.focus-state;
   }
 
+  // Single-line: same track as Input — height lock, horizontal pad only.
   &[rows="1"] {
-    height: var(--fui-input-height, $fui-input-height);
-    min-height: var(--fui-input-height, $fui-input-height);
-    padding-block: var(--fui-space-2, $fui-space-2);
+    block-size: var(--_fui-field-track);
+    min-block-size: var(--_fui-field-track);
+    padding-block: calc((var(--_fui-field-track) - 1lh - 2 * var(--_fui-field-stroke)) / 2);
     overflow-y: hidden;
   }
 }
 
 // Size variants
 .sm {
-  min-height: var(--fui-input-height-sm, $fui-input-height-sm);
-  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $fui-space-2);
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  @include field.size("sm");
 
-  &[rows="1"] {
-    height: var(--fui-input-height-sm, $fui-input-height-sm);
-    min-height: var(--fui-input-height-sm, $fui-input-height-sm);
-    padding-block: var(--fui-space-1, $fui-space-1);
-  }
+  --_fui-textarea-block-inset: var(--fui-raw-space-6, #{measurements.raw-space(6)});
 }
 
 .md {
-  // Default size
+  @include field.size("md");
+
+  --_fui-textarea-block-inset: var(--fui-raw-space-8, #{measurements.raw-space(8)});
 }
 
 .lg {
-  min-height: var(--fui-input-height-lg, $fui-input-height-lg);
-  padding: var(--fui-space-3, $fui-space-3) var(--fui-space-4, $fui-space-4);
-  font-size: var(--fui-font-size-base, $fui-font-size-base);
+  @include field.size("lg");
 
-  &[rows="1"] {
-    height: var(--fui-input-height-lg, $fui-input-height-lg);
-    min-height: var(--fui-input-height-lg, $fui-input-height-lg);
-    padding-block: var(--fui-space-2, $fui-space-2);
-  }
+  --_fui-textarea-block-inset: var(--fui-raw-space-10, #{measurements.raw-space(10)});
 }
 
 // Resize variants
@@ -81,7 +102,7 @@
 // Error state via aria-invalid attribute (replaces JS class toggle: `error && styles.error`)
 .error,
 .textarea[aria-invalid] {
-  border-color: var(--fui-color-danger-text, $fui-color-danger-text);
+  @include field.invalid-state;
 
   &:focus-visible {
     border-color: var(--fui-color-danger-text, $fui-color-danger-text);
@@ -115,12 +136,8 @@
   display: flex;
   justify-content: space-between;
   align-items: baseline;
-  gap: var(--fui-space-2, $fui-space-2);
-  min-height: calc(
-    var(--fui-font-size-xs, #{$fui-font-size-xs}) *
-      var(--fui-line-height-normal, #{$fui-line-height-normal}) +
-      var(--fui-space-1, #{$fui-space-1})
-  );
+  gap: layout.gap("sm");
+  min-block-size: typography.line-height("caption");
 
   &:empty {
     display: none;
@@ -129,9 +146,10 @@
 
 // Character counter
 .charCount {
-  @include helper-text;
-  margin-top: var(--fui-space-1, $fui-space-1);
-  margin-left: auto;
+  @include typography.role("caption");
+
+  margin-block-start: var(--fui-field-message-gap);
+  margin-inline-start: auto;
   font-family: var(--fui-font-mono, $fui-font-mono);
   white-space: nowrap;
 }
@@ -146,7 +164,7 @@
 
 @media (prefers-contrast: more) {
   .textarea {
-    border-width: 2px;
+    border-width: var(--fui-stroke-default, 2px);
     border-color: var(--fui-text-primary, $fui-text-primary);
 
     &:focus-visible {

package/src/components/Textarea/index.tsx

@@ -127,17 +127,10 @@ const TextareaRoot = React.forwardRef<HTMLTextAreaElement, TextareaProps>(functi
     .filter(Boolean)
     .join(" ");
 
-  // Calculate min/max height based on rows: N text lines (line-height-normal)
-  // plus the field's vertical padding (space-3 total ≈ 1.5rem at the 14px root).
-  const rowLine = "var(--fui-line-height-normal, 1.5) * 1em";
-  const rowPad = "var(--fui-space-3, 1.5rem)";
-  const textareaInlineStyle: React.CSSProperties = {};
-  if (minRows) {
-    textareaInlineStyle.minHeight = `calc(${minRows} * ${rowLine} + ${rowPad})`;
-  }
-  if (maxRows) {
-    textareaInlineStyle.maxHeight = `calc(${maxRows} * ${rowLine} + ${rowPad})`;
-  }
+  const textareaInlineStyle = {
+    "--_fui-textarea-min-rows": minRows ?? 1,
+    "--_fui-textarea-max-rows": maxRows ?? 9999,
+  } as React.CSSProperties;
 
   return (
     <div
@@ -177,7 +170,7 @@ const TextareaRoot = React.forwardRef<HTMLTextAreaElement, TextareaProps>(functi
         onBlur={(e) => onBlur?.(e)}
         onFocus={(e) => onFocus?.(e)}
         className={textareaClasses}
-        style={Object.keys(textareaInlineStyle).length > 0 ? textareaInlineStyle : undefined}
+        style={textareaInlineStyle}
       />
       <div className={styles.footer}>
         {helperText && (

package/src/components/Theme/Theme.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Theme",
-  "description": "Theme management system with provider, toggle, and hook pattern. Supports light, dark, and system modes with localStorage persistence.",
-  "category": "navigation",
-  "tags": [
-    "theme",
-    "dark-mode",
-    "light-mode",
-    "provider",
-    "toggle"
-  ],
+  "description": "Gives every component below it a light, dark, or system color mode, and remembers the choice.",
+  "category": "utilities",
+  "tags": ["theme", "dark-mode", "light-mode", "provider", "toggle"],
   "status": "stable",
   "sourcePath": "src/components/Theme/index.tsx",
   "exportName": "ThemeProvider",
@@ -20,7 +14,8 @@
     "mode: light|dark|system",
     "onModeChange: function",
     "storageKey: string (default: fui-theme)",
-    "attribute: data-theme|class (default: data-theme)"
+    "attribute: data-theme|class (default: data-theme)",
+    "ThemeToggle appearance: group|icon (default: group)"
   ],
   "props": {
     "children": {
@@ -33,31 +28,19 @@
       "description": "Default theme mode for uncontrolled usage",
       "default": "system",
       "required": false,
-      "values": [
-        "light",
-        "dark",
-        "system"
-      ]
+      "values": ["light", "dark", "system"]
     },
     "defaultTheme": {
       "type": "enum",
       "description": "",
       "required": false,
-      "values": [
-        "light",
-        "dark",
-        "system"
-      ]
+      "values": ["light", "dark", "system"]
     },
     "mode": {
       "type": "enum",
       "description": "Controlled theme mode",
       "required": false,
-      "values": [
-        "light",
-        "dark",
-        "system"
-      ]
+      "values": ["light", "dark", "system"]
     },
     "onModeChange": {
       "type": "function",
@@ -75,52 +58,51 @@
       "description": "How to apply theme to DOM",
       "default": "data-theme",
       "required": false,
-      "values": [
-        "data-theme",
-        "class"
-      ]
+      "values": ["data-theme", "class"]
     }
   },
   "usage": {
     "when": [
-      "Providing theme context to an application",
-      "Toggling between light and dark modes",
-      "Respecting system color scheme preference",
-      "Persisting theme preference across sessions"
+      "An app needs light and dark modes",
+      "The user's choice should survive a reload",
+      "You want to honour the OS setting by default"
     ],
     "whenNot": [
-      "Simple one-off color changes (use CSS variables)",
-      "Component-level theming (use component props)"
+      "Recoloring one component (use its props)",
+      "A single one-off color swap (use a CSS variable)"
     ],
     "guidelines": [
-      "Wrap your app with ThemeProvider at the root level",
-      "Use useTheme hook to access theme state in components",
-      "ThemeToggle cycles through light → dark → system",
-      "Use storageKey to customize localStorage key",
-      "Set attribute=\"class\" if your CSS uses .dark class instead of data-theme",
-      "ThemeToggle forwards DOM props (id, data-*, className, handlers) to the toggle group"
+      "ThemeProvider goes at the root, once",
+      "useTheme reads and sets the mode anywhere below it",
+      "storageKey renames the localStorage entry",
+      "attribute=\"class\" if your CSS keys off .dark instead of data-theme",
+      "appearance=\"icon\" for tight toolbars; the default group shows both modes"
     ],
     "accessibility": [
-      "ThemeToggle button has accessible label indicating current mode",
-      "Theme changes are applied via CSS custom properties for smooth transitions",
-      "System preference is detected via prefers-color-scheme media query"
+      "The toggle's label names the mode it is in",
+      "System mode follows prefers-color-scheme"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "ThemeProvider with system default",
-      "code": "<ThemeProvider defaultMode=\"system\">\n  <ThemeDemo />\n</ThemeProvider>"
+      "description": "Wrap the app once; every token below resolves to the active mode.",
+      "code": "<ThemeProvider defaultMode=\"system\">\n  <div\n    style={{\n      padding: '16px',\n      borderRadius: '8px',\n      background: 'var(--fui-bg-elevated)',\n      color: 'var(--fui-text-primary)',\n    }}\n  >\n    Everything inside follows the system color scheme.\n  </div>\n</ThemeProvider>"
     },
     {
       "name": "With Toggle",
-      "description": "ThemeProvider with toggle button",
+      "description": "The toggle cycles light, dark, then back to system.",
       "code": "<ThemeProvider defaultMode=\"light\">\n  <div style={{ display: 'flex', alignItems: 'center', gap: '16px' }}>\n    <ThemeToggle />\n    <span>Click to cycle themes</span>\n  </div>\n</ThemeProvider>"
     },
     {
       "name": "Toggle Sizes",
-      "description": "ThemeToggle in different sizes",
+      "description": "Three sizes so the control fits whatever bar holds it.",
       "code": "<ThemeProvider defaultMode=\"light\">\n  <div style={{ display: 'flex', alignItems: 'center', gap: '16px' }}>\n    <ThemeToggle size=\"sm\" />\n    <ThemeToggle size=\"md\" />\n    <ThemeToggle size=\"lg\" />\n  </div>\n</ThemeProvider>"
+    },
+    {
+      "name": "Icon Toggle",
+      "description": "A single icon button for toolbars with no room to spare.",
+      "code": "<ThemeProvider defaultMode=\"system\">\n  <ThemeToggle appearance=\"icon\" aria-label=\"Switch color mode\" />\n</ThemeProvider>"
     }
   ],
   "relations": [
@@ -137,11 +119,10 @@
       "onModeChange: (mode) => void - change handler",
       "attribute: data-theme|class - DOM theme attribute",
       "ThemeToggle size: sm|md|lg - toggle button size",
+      "ThemeToggle appearance: group|icon - segmented or compact icon control (default: group)",
       "ThemeToggle forwards div DOM props to the button group root"
     ],
-    "a11yRules": [
-      "A11Y_TARGET_SIZE_MIN"
-    ]
+    "a11yRules": ["A11Y_TARGET_SIZE_MIN"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Theme/context.ts

@@ -0,0 +1,42 @@
+"use client";
+
+import * as React from "react";
+
+export type ThemeMode = "light" | "dark" | "system";
+
+export interface UseThemeReturn {
+  /** Current theme mode setting */
+  mode: ThemeMode;
+  /** Set the theme mode */
+  setMode: (mode: ThemeMode) => void;
+  /** Resolved mode (never 'system', always 'light' or 'dark') */
+  resolvedMode: "light" | "dark";
+  /** System preference detected from prefers-color-scheme */
+  systemPreference: "light" | "dark";
+  /** Toggle between light and dark (skips system) */
+  toggleMode: () => void;
+}
+
+export type ThemeContextValue = UseThemeReturn;
+
+export const ThemeContext = React.createContext<ThemeContextValue | null>(null);
+
+/**
+ * Hook to access theme context.
+ */
+export function useTheme(): UseThemeReturn {
+  const context = React.useContext(ThemeContext);
+
+  if (!context) {
+    // Return safe defaults when used outside provider.
+    return {
+      mode: "system",
+      setMode: () => {},
+      resolvedMode: "light",
+      systemPreference: "light",
+      toggleMode: () => {},
+    };
+  }
+
+  return context;
+}