@usefragments/ui 1.0.0

package/src/components/Textarea/index.tsx

@@ -0,0 +1,205 @@
+import * as React from "react";
+import { useResolvedControlSize } from "../ComponentDefaults";
+import { mergeAriaIds } from "../../utils/aria";
+import styles from "./Textarea.module.scss";
+
+export interface TextareaProps extends Omit<
+  React.TextareaHTMLAttributes<HTMLTextAreaElement>,
+  "onChange" | "onBlur" | "onFocus" | "className" | "style" | "size"
+> {
+  /** Controlled value */
+  value?: string;
+  /** Default value for uncontrolled usage */
+  defaultValue?: string;
+  /** Placeholder text */
+  placeholder?: string;
+  /** Number of visible text rows */
+  rows?: number;
+  /** Minimum number of rows (for auto-resize) */
+  minRows?: number;
+  /** Maximum number of rows (for auto-resize) */
+  maxRows?: number;
+  /** Allow user to resize the textarea */
+  resize?: "none" | "vertical" | "horizontal" | "both";
+  /** Size variant.
+   * @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Disabled state */
+  disabled?: boolean;
+  /** Error state */
+  error?: boolean;
+  /** Success state */
+  success?: boolean;
+  /** Show character count when maxLength is set */
+  showCharCount?: boolean;
+  /** Label text above the textarea */
+  label?: string;
+  /** Helper text below the textarea */
+  helperText?: string;
+  /** Called when value changes */
+  onChange?: (value: string) => void;
+  /** Alias for onChange (value-first callback) */
+  onValueChange?: (value: string) => void;
+  /** Called when textarea loses focus */
+  onBlur?: React.FocusEventHandler<HTMLTextAreaElement>;
+  /** Called when textarea receives focus */
+  onFocus?: React.FocusEventHandler<HTMLTextAreaElement>;
+  /** Form field name */
+  name?: string;
+  /** Maximum character length */
+  maxLength?: number;
+  /** Required field */
+  required?: boolean;
+  /** Accessible label for no-visible-label usage */
+  "aria-label"?: string;
+  /** Accessible labelled-by relationship */
+  "aria-labelledby"?: string;
+  /** Accessible described-by relationship */
+  "aria-describedby"?: string;
+  /** Props applied to the wrapper element */
+  rootProps?: React.HTMLAttributes<HTMLDivElement>;
+  /** Wrapper class name */
+  className?: string;
+  /** Wrapper styles */
+  style?: React.CSSProperties;
+}
+
+const TextareaRoot = React.forwardRef<HTMLTextAreaElement, TextareaProps>(function Textarea(
+  {
+    value,
+    defaultValue,
+    placeholder,
+    rows = 3,
+    minRows,
+    maxRows,
+    resize = "vertical",
+    size: sizeProp,
+    disabled = false,
+    error = false,
+    success = false,
+    showCharCount = false,
+    label,
+    helperText,
+    onChange,
+    onValueChange,
+    onBlur,
+    onFocus,
+    rootProps,
+    className,
+    style: wrapperStyle,
+    ...textareaProps
+  },
+  ref
+) {
+  const size = useResolvedControlSize(sizeProp);
+  const generatedId = React.useId();
+  const {
+    id,
+    name,
+    maxLength,
+    required = false,
+    "aria-label": ariaLabel,
+    "aria-labelledby": ariaLabelledBy,
+    "aria-describedby": ariaDescribedBy,
+    ...nativeTextareaProps
+  } = textareaProps;
+  const textareaId = id || generatedId;
+  const labelId = label ? `${textareaId}-label` : undefined;
+  const helperId = `${textareaId}-helper`;
+
+  const [charCount, setCharCount] = React.useState(() => (value ?? defaultValue ?? "").length);
+
+  const textareaClasses = [
+    styles.textarea,
+    styles[size],
+    error && styles.error,
+    success && styles.success,
+    styles[`resize-${resize}`],
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const helperClasses = [
+    styles.helper,
+    error && styles.helperError,
+    success && styles.helperSuccess,
+  ]
+    .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})`;
+  }
+
+  return (
+    <div
+      {...rootProps}
+      data-success={success || undefined}
+      className={[styles.wrapper, rootProps?.className, className].filter(Boolean).join(" ")}
+      style={{ ...(rootProps?.style ?? {}), ...(wrapperStyle ?? {}) }}
+    >
+      {label && (
+        <label id={labelId} htmlFor={textareaId} className={styles.label}>
+          {label}
+          {required && <span className={styles.required}>*</span>}
+        </label>
+      )}
+      <textarea
+        ref={ref}
+        id={textareaId}
+        value={value}
+        defaultValue={defaultValue}
+        placeholder={placeholder}
+        rows={rows}
+        {...nativeTextareaProps}
+        name={name}
+        maxLength={maxLength}
+        disabled={disabled}
+        required={required}
+        aria-label={ariaLabel}
+        aria-labelledby={mergeAriaIds(ariaLabelledBy, labelId)}
+        aria-invalid={error || undefined}
+        aria-describedby={mergeAriaIds(ariaDescribedBy, helperText ? helperId : undefined)}
+        onChange={(e) => {
+          const val = e.target.value;
+          setCharCount(val.length);
+          onChange?.(val);
+          onValueChange?.(val);
+        }}
+        onBlur={(e) => onBlur?.(e)}
+        onFocus={(e) => onFocus?.(e)}
+        className={textareaClasses}
+        style={Object.keys(textareaInlineStyle).length > 0 ? textareaInlineStyle : undefined}
+      />
+      <div className={styles.footer}>
+        {helperText && (
+          <span id={helperId} className={helperClasses}>
+            {helperText}
+          </span>
+        )}
+        {showCharCount && maxLength != null && (
+          <span
+            className={[styles.charCount, charCount > maxLength && styles.charCountOver]
+              .filter(Boolean)
+              .join(" ")}
+            aria-live="polite"
+          >
+            {charCount}/{maxLength}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+});
+
+export const Textarea = Object.assign(TextareaRoot, {
+  Root: TextareaRoot,
+});

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

@@ -0,0 +1,152 @@
+{
+  "$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"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Theme/index.tsx",
+  "exportName": "ThemeProvider",
+  "propsSummary": [
+    "children: node (required)",
+    "defaultMode: light|dark|system",
+    "defaultTheme: light|dark|system",
+    "mode: light|dark|system",
+    "onModeChange: function",
+    "storageKey: string (default: fui-theme)",
+    "attribute: data-theme|class (default: data-theme)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Application content",
+      "required": true
+    },
+    "defaultMode": {
+      "type": "enum",
+      "description": "Default theme mode for uncontrolled usage",
+      "default": "system",
+      "required": false,
+      "values": [
+        "light",
+        "dark",
+        "system"
+      ]
+    },
+    "defaultTheme": {
+      "type": "enum",
+      "description": "",
+      "required": false,
+      "values": [
+        "light",
+        "dark",
+        "system"
+      ]
+    },
+    "mode": {
+      "type": "enum",
+      "description": "Controlled theme mode",
+      "required": false,
+      "values": [
+        "light",
+        "dark",
+        "system"
+      ]
+    },
+    "onModeChange": {
+      "type": "function",
+      "description": "Callback when mode changes",
+      "required": false
+    },
+    "storageKey": {
+      "type": "string",
+      "description": "localStorage key for persistence",
+      "default": "fui-theme",
+      "required": false
+    },
+    "attribute": {
+      "type": "enum",
+      "description": "How to apply theme to DOM",
+      "default": "data-theme",
+      "required": false,
+      "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"
+    ],
+    "whenNot": [
+      "Simple one-off color changes (use CSS variables)",
+      "Component-level theming (use component props)"
+    ],
+    "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"
+    ],
+    "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"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "ThemeProvider with system default",
+      "code": "<ThemeProvider defaultMode=\"system\">\n  <ThemeDemo />\n</ThemeProvider>"
+    },
+    {
+      "name": "With Toggle",
+      "description": "ThemeProvider with toggle button",
+      "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",
+      "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>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "AppShell",
+      "relationship": "sibling",
+      "note": "ThemeProvider typically wraps AppShell"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "defaultMode: light|dark|system - initial theme mode",
+      "mode: light|dark|system - controlled mode",
+      "onModeChange: (mode) => void - change handler",
+      "attribute: data-theme|class - DOM theme attribute",
+      "ThemeToggle size: sm|md|lg - toggle button size",
+      "ThemeToggle forwards div DOM props to the button group root"
+    ],
+    "a11yRules": [
+      "A11Y_TARGET_SIZE_MIN"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:05.406Z"
+  }
+}

package/src/components/Theme/Theme.stories.tsx

@@ -0,0 +1,95 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, ThemeToggle } from '.';
+
+/**
+ * ThemeProvider is the canonical theme-management primitive. Wrap your app with
+ * it once at the root to supply light/dark/system mode via CSS custom
+ * properties, with localStorage persistence — agents should use it (paired with
+ * `useTheme` and `ThemeToggle`) rather than wiring up bespoke theme state.
+ */
+const meta = {
+  title: 'Navigation/ThemeProvider',
+  component: ThemeProvider,
+  tags: ['autodocs', 'canonical'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Theme context provider supporting light, dark, and system modes with localStorage persistence. Prefer this over hand-rolled theme state.',
+      },
+    },
+  },
+  argTypes: {
+    defaultMode: {
+      control: 'select',
+      options: ['light', 'dark', 'system'],
+      description: 'Default theme mode for uncontrolled usage',
+    },
+    mode: {
+      control: 'select',
+      options: ['light', 'dark', 'system'],
+      description: 'Controlled theme mode',
+    },
+    attribute: {
+      control: 'select',
+      options: ['data-theme', 'class'],
+      description: 'How to apply the theme to the DOM',
+    },
+    storageKey: { control: 'text', description: 'localStorage key for persistence' },
+  },
+  args: {
+    defaultMode: 'system',
+    children: (
+      <div style={{ display: 'flex', alignItems: 'center', gap: '16px' }}>
+        <ThemeToggle />
+        <span>Click to cycle themes</span>
+      </div>
+    ),
+  },
+} satisfies Meta<typeof ThemeProvider>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <ThemeProvider {...args}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: '16px' }}>
+        <ThemeToggle />
+        <span>Click to cycle themes</span>
+      </div>
+    </ThemeProvider>
+  ),
+};
+
+export const WithToggle: Story = {
+  args: { defaultMode: 'light' },
+  render: (args) => (
+    <ThemeProvider {...args}>
+      <ThemeToggle />
+    </ThemeProvider>
+  ),
+};
+
+export const ToggleSizes: Story = {
+  args: { defaultMode: 'light' },
+  render: (args) => (
+    <ThemeProvider {...args}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: '16px' }}>
+        <ThemeToggle size="sm" />
+        <ThemeToggle size="md" />
+        <ThemeToggle size="lg" />
+      </div>
+    </ThemeProvider>
+  ),
+};
+
+export const DarkDefault: Story = {
+  args: { defaultMode: 'dark' },
+  render: (args) => (
+    <ThemeProvider {...args}>
+      <ThemeToggle showSystem />
+    </ThemeProvider>
+  ),
+};

package/src/components/Theme/ThemeToggle.module.scss

@@ -0,0 +1,91 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+// Local component tokens
+$fui-theme-toggle-sm-width: 32px !default;
+$fui-theme-toggle-sm-height: 32px !default;
+$fui-theme-toggle-sm-icon: 12px !default;
+$fui-theme-toggle-md-width: 32px !default;
+$fui-theme-toggle-md-height: 32px !default;
+$fui-theme-toggle-md-icon: 14px !default;
+$fui-theme-toggle-lg-width: 40px !default;
+$fui-theme-toggle-lg-height: 40px !default;
+$fui-theme-toggle-lg-icon: 18px !default;
+
+// ============================================
+// Theme Toggle - Fragmented Button Group
+// ============================================
+
+.toggleGroup {
+  display: inline-flex;
+  align-items: stretch;
+  gap: 0;
+  padding: 0;
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+}
+
+.toggleButton {
+  @include button-reset;
+  @include interactive-base;
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  background-color: transparent;
+
+  &:hover:not(.toggleButtonActive) {
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  // Keyboard focus ring is supplied by @include interactive-base.
+
+  svg {
+    flex-shrink: 0;
+  }
+}
+
+.toggleButtonActive {
+  background-color: var(--fui-bg-elevated, $fui-bg-elevated);
+  color: var(--fui-text-primary, $fui-text-primary);
+  box-shadow: var(--fui-shadow-sm, $fui-shadow-sm);
+}
+
+// Size variants
+.sizeSm {
+  .toggleButton {
+    width: var(--fui-theme-toggle-sm-width, $fui-theme-toggle-sm-width);
+    height: var(--fui-theme-toggle-sm-height, $fui-theme-toggle-sm-height);
+
+    svg {
+      width: var(--fui-theme-toggle-sm-icon, $fui-theme-toggle-sm-icon);
+      height: var(--fui-theme-toggle-sm-icon, $fui-theme-toggle-sm-icon);
+    }
+  }
+}
+
+.sizeMd {
+  .toggleButton {
+    width: var(--fui-theme-toggle-md-width, $fui-theme-toggle-md-width);
+    height: var(--fui-theme-toggle-md-height, $fui-theme-toggle-md-height);
+
+    svg {
+      width: var(--fui-theme-toggle-md-icon, $fui-theme-toggle-md-icon);
+      height: var(--fui-theme-toggle-md-icon, $fui-theme-toggle-md-icon);
+    }
+  }
+}
+
+.sizeLg {
+  .toggleButton {
+    width: var(--fui-theme-toggle-lg-width, $fui-theme-toggle-lg-width);
+    height: var(--fui-theme-toggle-lg-height, $fui-theme-toggle-lg-height);
+
+    svg {
+      width: var(--fui-theme-toggle-lg-icon, $fui-theme-toggle-lg-icon);
+      height: var(--fui-theme-toggle-lg-icon, $fui-theme-toggle-lg-icon);
+    }
+  }
+}