@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Stack/index.tsx

@@ -1,8 +1,9 @@
-import * as React from 'react';
-import styles from './Stack.module.scss';
+import * as React from "react";
+import { resolveLayoutGap } from "../../utils/layout-spacing";
+import styles from "./Stack.module.scss";
 
-type Direction = 'row' | 'column';
-type GapToken = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type Direction = "row" | "column";
+type GapToken = "none" | "xs" | "sm" | "md" | "lg" | "xl";
 /** Gap accepts string tokens or numbers (1-8) mapping to the spacing scale */
 type GapScale = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
 type Gap = GapToken | GapScale;
@@ -39,7 +40,10 @@ export interface ResponsiveGap {
  * Flexbox layout component for vertical or horizontal stacking with consistent spacing.
  * @see https://usefragments.com/components/stack
  */
-export interface StackProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children' | 'style' | 'className'> {
+export interface StackProps extends Omit<
+  React.HTMLAttributes<HTMLElement>,
+  "children" | "style" | "className"
+> {
   children: React.ReactNode;
   /**
    * Stack direction.
@@ -53,8 +57,8 @@ export interface StackProps extends Omit<React.HTMLAttributes<HTMLElement>, 'chi
    * - An object for responsive gap: `{ base: "sm", md: "lg" }`
    */
   gap?: Gap | ResponsiveGap;
-  align?: 'start' | 'center' | 'end' | 'stretch' | 'baseline';
-  justify?: 'start' | 'center' | 'end' | 'between';
+  align?: "start" | "center" | "end" | "stretch" | "baseline";
+  justify?: "start" | "center" | "end" | "between";
   wrap?: boolean;
   /**
    * Render a separator between each child.
@@ -62,145 +66,171 @@ export interface StackProps extends Omit<React.HTMLAttributes<HTMLElement>, 'chi
    * - A ReactNode renders custom content between children
    */
   separator?: boolean | React.ReactNode;
-  as?: 'div' | 'section' | 'nav' | 'article' | 'aside' | 'header' | 'footer' | 'main' | 'ul' | 'ol';
+  as?: "div" | "section" | "nav" | "article" | "aside" | "header" | "footer" | "main" | "ul" | "ol";
   className?: string;
   style?: React.CSSProperties;
 }
 
 function isResponsiveDirection(
-  direction: StackProps['direction']
+  direction: StackProps["direction"]
 ): direction is ResponsiveDirection {
-  return typeof direction === 'object' && direction !== null;
+  return typeof direction === "object" && direction !== null;
 }
 
-function isResponsiveGap(gap: StackProps['gap']): gap is ResponsiveGap {
-  return typeof gap === 'object' && gap !== null;
+function isResponsiveGap(gap: StackProps["gap"]): gap is ResponsiveGap {
+  return typeof gap === "object" && gap !== null;
 }
 
-function isNumericGap(gap: StackProps['gap']): gap is GapScale {
-  return typeof gap === 'number';
+function isNumericGap(gap: StackProps["gap"]): gap is GapScale {
+  return typeof gap === "number";
 }
 
-const StackRoot = React.forwardRef<HTMLElement, StackProps>(
-  function Stack(
-    {
-      children,
-      direction = 'column',
-      gap = 'md',
-      align,
-      justify,
-      wrap = false,
-      separator,
-      as: Component = 'div',
-      className,
-      style,
-      ...htmlProps
-    },
-    ref
-  ) {
-    let directionClass: string;
-    let gapClass: string | false;
-    let inlineStyle: React.CSSProperties | undefined;
-
-    // Handle responsive direction
-    if (isResponsiveDirection(direction)) {
-      directionClass = styles.directionResponsive;
-      const vars: Record<string, string> = {};
-      if (direction.base) vars['--fui-stack-direction'] = direction.base;
-      if (direction.sm) vars['--fui-stack-direction-sm'] = direction.sm;
-      if (direction.md) vars['--fui-stack-direction-md'] = direction.md;
-      if (direction.lg) vars['--fui-stack-direction-lg'] = direction.lg;
-      if (direction.xl) vars['--fui-stack-direction-xl'] = direction.xl;
-      inlineStyle = vars as unknown as React.CSSProperties;
-    } else {
-      directionClass = styles[direction];
-    }
+const StackRoot = React.forwardRef<HTMLElement, StackProps>(function Stack(
+  {
+    children,
+    direction = "column",
+    gap = "md",
+    align,
+    justify,
+    wrap = false,
+    separator,
+    as: Component = "div",
+    className,
+    style,
+    ...htmlProps
+  },
+  ref
+) {
+  let directionClass: string;
+  let gapClass: string | false;
+  let inlineStyle: React.CSSProperties | undefined;
+
+  // Handle responsive direction
+  if (isResponsiveDirection(direction)) {
+    directionClass = styles.directionResponsive ?? "";
+    const vars: Record<string, string> = {};
+    const baseDirection = direction.base ?? "column";
+    const smDirection = direction.sm ?? baseDirection;
+    const mdDirection = direction.md ?? smDirection;
+    const lgDirection = direction.lg ?? mdDirection;
+    const xlDirection = direction.xl ?? lgDirection;
+    vars["--fui-stack-direction"] = baseDirection;
+    vars["--fui-stack-direction-sm"] = smDirection;
+    vars["--fui-stack-direction-md"] = mdDirection;
+    vars["--fui-stack-direction-lg"] = lgDirection;
+    vars["--fui-stack-direction-xl"] = xlDirection;
+    inlineStyle = vars as unknown as React.CSSProperties;
+  } else {
+    directionClass = styles[direction] ?? "";
+  }
 
-    // Handle responsive gap
-    if (isResponsiveGap(gap)) {
-      gapClass = styles.gapResponsive;
-      const gapVars: Record<string, string> = {};
-      if (gap.base && gap.base !== 'none') gapVars['--fui-stack-gap'] = `var(--fui-space-${gapToSpace(gap.base)})`;
-      if (gap.sm && gap.sm !== 'none') gapVars['--fui-stack-gap-sm'] = `var(--fui-space-${gapToSpace(gap.sm)})`;
-      if (gap.md && gap.md !== 'none') gapVars['--fui-stack-gap-md'] = `var(--fui-space-${gapToSpace(gap.md)})`;
-      if (gap.lg && gap.lg !== 'none') gapVars['--fui-stack-gap-lg'] = `var(--fui-space-${gapToSpace(gap.lg)})`;
-      if (gap.xl && gap.xl !== 'none') gapVars['--fui-stack-gap-xl'] = `var(--fui-space-${gapToSpace(gap.xl)})`;
-      inlineStyle = { ...inlineStyle, ...gapVars } as React.CSSProperties;
-    } else if (isNumericGap(gap)) {
-      // Numeric gap: maps to space scale tokens (e.g. gap={2} → var(--fui-space-2))
-      gapClass = false;
-      inlineStyle = { ...inlineStyle, gap: `var(--fui-space-${gap})` } as React.CSSProperties;
-    } else {
-      gapClass = gap !== 'none' && styles[`gap-${gap}`];
-    }
+  // Handle responsive gap
+  if (isResponsiveGap(gap)) {
+    gapClass = styles.gapResponsive ?? false;
+    const gapVars: Record<string, string> = {};
+    if (gap.base) gapVars["--fui-stack-gap"] = resolveLayoutGap(gap.base);
+    if (gap.sm) gapVars["--fui-stack-gap-sm"] = resolveLayoutGap(gap.sm);
+    if (gap.md) gapVars["--fui-stack-gap-md"] = resolveLayoutGap(gap.md);
+    if (gap.lg) gapVars["--fui-stack-gap-lg"] = resolveLayoutGap(gap.lg);
+    if (gap.xl) gapVars["--fui-stack-gap-xl"] = resolveLayoutGap(gap.xl);
+    inlineStyle = { ...inlineStyle, ...gapVars } as React.CSSProperties;
+  } else if (isNumericGap(gap)) {
+    gapClass = false;
+    inlineStyle = {
+      ...inlineStyle,
+      "--fui-stack-gap": resolveLayoutGap(gap),
+    } as React.CSSProperties;
+  } else {
+    gapClass = false;
+    inlineStyle = {
+      ...inlineStyle,
+      "--fui-stack-gap": resolveLayoutGap(gap),
+    } as React.CSSProperties;
+  }
 
-    const classes = [
-      styles.stack,
-      directionClass,
-      gapClass,
-      align && styles[`align-${align}`],
-      justify && styles[`justify-${justify}`],
-      wrap && styles.wrap,
-      className,
-    ]
-      .filter(Boolean)
-      .join(' ');
-
-    const mergedStyle = inlineStyle ? { ...inlineStyle, ...style } : style;
-
-    // Interleave separator between children when provided
-    let content: React.ReactNode = children;
-    if (separator) {
-      const validChildren = React.Children.toArray(children).filter(Boolean);
-      if (validChildren.length > 1) {
-        const resolvedDir = isResponsiveDirection(direction) ? (direction.base ?? 'column') : direction;
-        const separatorEl = separator === true ? (
+  const classes = [
+    styles.stack,
+    directionClass,
+    gapClass,
+    align && styles[`align-${align}`],
+    justify && styles[`justify-${justify}`],
+    wrap && styles.wrap,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const mergedStyle = inlineStyle ? { ...inlineStyle, ...style } : style;
+
+  // Interleave separator between children when provided
+  let content: React.ReactNode = children;
+  if (separator) {
+    const validChildren = React.Children.toArray(children).filter(Boolean);
+    if (validChildren.length > 1) {
+      const responsiveDirection = isResponsiveDirection(direction);
+      const resolvedDir = responsiveDirection ? (direction.base ?? "column") : direction;
+      const separatorEl =
+        separator === true ? (
           <div
             className={styles.separator}
-            data-orientation={resolvedDir === 'row' ? 'vertical' : 'horizontal'}
-            role="separator"
+            data-orientation={resolvedDir === "row" ? "vertical" : "horizontal"}
+            role={responsiveDirection ? undefined : "separator"}
+            aria-hidden={responsiveDirection ? true : undefined}
           />
-        ) : separator;
-
-        const items: React.ReactNode[] = [];
-        validChildren.forEach((child, idx) => {
-          items.push(child);
-          if (idx < validChildren.length - 1) {
-            const childKey = React.isValidElement(child) && child.key != null ? child.key : `idx-${idx}`;
-            items.push(
-              <React.Fragment key={`sep-${childKey}`}>{separatorEl}</React.Fragment>
-            );
-          }
-        });
-        content = items;
-      }
+        ) : (
+          separator
+        );
+
+      const items: React.ReactNode[] = [];
+      validChildren.forEach((child, idx) => {
+        items.push(child);
+        if (idx < validChildren.length - 1) {
+          const childKey =
+            React.isValidElement(child) && child.key != null ? child.key : `idx-${idx}`;
+          items.push(<React.Fragment key={`sep-${childKey}`}>{separatorEl}</React.Fragment>);
+        }
+      });
+      content = items;
     }
-
-    return (
-      <Component
-        {...htmlProps}
-        ref={ref as React.Ref<never>}
-        className={classes}
-        style={mergedStyle}
-      >
-        {content}
-      </Component>
-    );
   }
-);
-
-// Map gap prop values to space variable numbers
-function gapToSpace(gap: GapToken): string {
-  const map: Record<GapToken, string> = {
-    none: '0',
-    xs: '1',
-    sm: '2',
-    md: '3',
-    lg: '4',
-    xl: '6',
-  };
-  return map[gap];
-}
+
+  return (
+    <Component
+      {...htmlProps}
+      ref={ref as React.Ref<never>}
+      className={classes}
+      style={mergedStyle}
+      data-direction-base={
+        isResponsiveDirection(direction) ? (direction.base ?? "column") : direction
+      }
+      data-direction-sm={
+        isResponsiveDirection(direction) ? (direction.sm ?? direction.base ?? "column") : direction
+      }
+      data-direction-md={
+        isResponsiveDirection(direction)
+          ? (direction.md ?? direction.sm ?? direction.base ?? "column")
+          : direction
+      }
+      data-direction-lg={
+        isResponsiveDirection(direction)
+          ? (direction.lg ?? direction.md ?? direction.sm ?? direction.base ?? "column")
+          : direction
+      }
+      data-direction-xl={
+        isResponsiveDirection(direction)
+          ? (direction.xl ??
+            direction.lg ??
+            direction.md ??
+            direction.sm ??
+            direction.base ??
+            "column")
+          : direction
+      }
+    >
+      {content}
+    </Component>
+  );
+});
 
 export const Stack = Object.assign(StackRoot, {
   Root: StackRoot,

package/src/components/{Toggle/Toggle.contract.json → Switch/Switch.contract.json}

@@ -1,17 +1,11 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Switch",
-  "description": "Binary on/off switch for settings and preferences. Provides immediate visual feedback and is ideal for options that take effect instantly.",
-  "category": "forms",
-  "tags": [
-    "switch",
-    "toggle",
-    "boolean",
-    "settings",
-    "preference"
-  ],
+  "description": "Toggles a setting that takes effect immediately.",
+  "category": "inputs",
+  "tags": ["switch", "toggle", "boolean", "settings", "preference"],
   "status": "stable",
-  "sourcePath": "src/components/Toggle/index.tsx",
+  "sourcePath": "src/components/Switch/index.tsx",
   "exportName": "Switch",
   "propsSummary": [
     "checked: boolean",
@@ -78,11 +72,7 @@
       "description": "Switch track size",
       "default": "md",
       "required": false,
-      "values": [
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["sm", "md", "lg"]
     },
     "className": {
       "type": "string",
@@ -117,35 +107,34 @@
   },
   "usage": {
     "when": [
-      "Binary settings that take effect immediately (e.g., dark mode, notifications)",
-      "Enabling/disabling features in a settings panel",
-      "Options where the result is immediately visible",
-      "Mobile-friendly boolean inputs"
+      "Settings that apply the moment they change",
+      "Turning a feature on or off in a settings panel",
+      "The result is visible straight away"
     ],
     "whenNot": [
-      "Multiple options in a group (use checkbox group)",
-      "Selection requires form submission to take effect (use checkbox)",
-      "Yes/No questions in forms (use radio buttons)",
-      "Complex multi-state options (use select or radio)"
+      "Choices that only apply on submit (use Checkbox)",
+      "Several options at once (use a Checkbox group)",
+      "Yes/no questions in a form (use RadioGroup)",
+      "More than two states (use Select or RadioGroup)"
     ],
     "guidelines": [
-      "Switch should always have a visible label explaining what it controls",
-      "The \"on\" state should be the positive/enabling action",
-      "Changes should take effect immediately - no save button needed",
-      "Include helperText for switches whose effect isn't obvious from the label",
-      "Group related switches visually in settings panels"
+      "The label names what is being turned on",
+      "On always means enabled, never the reverse",
+      "Apply the change immediately — no save button",
+      "Add helperText when the label alone is ambiguous",
+      "Stack related switches together"
     ],
     "accessibility": [
-      "Uses role=\"switch\" with aria-checked for proper semantics",
-      "Must have an accessible label (visible or aria-label)",
-      "Focus indicator must be clearly visible",
-      "State change must be announced by screen readers"
+      "role=\"switch\" with aria-checked",
+      "Every switch has a label, visible or aria-label",
+      "Focus ring stays visible",
+      "Flipping it is announced"
     ]
   },
   "examples": [
     {
       "name": "Default Off",
-      "description": "Switch in the off state",
+      "description": "Nothing happens until the user flips it.",
       "code": "<StatefulSwitch label=\"Email notifications\" />",
       "args": {
         "label": "Email notifications"
@@ -153,37 +142,37 @@
     },
     {
       "name": "Checked",
-      "description": "Switch in the on state",
-      "code": "<StatefulSwitch checked label=\"Dark mode\" />",
+      "description": "Starts on; the track fills with the accent colour.",
+      "code": "<StatefulSwitch defaultChecked label=\"Dark mode\" />",
       "args": {
-        "checked": true,
+        "defaultChecked": true,
         "label": "Dark mode"
       }
     },
     {
       "name": "With Helper Text",
-      "description": "Switch with explanatory helper text",
-      "code": "<StatefulSwitch\n  checked\n  label=\"Auto-save\"\n  helperText=\"Automatically save changes as you type\"\n/>",
+      "description": "Second line says what the setting actually does.",
+      "code": "<StatefulSwitch\n  defaultChecked\n  label=\"Auto-save\"\n  helperText=\"Automatically save changes as you type\"\n/>",
       "args": {
-        "checked": true,
+        "defaultChecked": true,
         "label": "Auto-save",
         "helperText": "Automatically save changes as you type"
       }
     },
     {
       "name": "Sizes",
-      "description": "Available size variants",
-      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <StatefulSwitch size=\"sm\" checked label=\"Small switch\" />\n  <StatefulSwitch size=\"md\" checked label=\"Medium switch (default)\" />\n  <StatefulSwitch size=\"lg\" checked label=\"Large switch\" />\n</div>"
+      "description": "Three track sizes: sm, md, lg.",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <StatefulSwitch size=\"sm\" defaultChecked label=\"Small switch\" />\n  <StatefulSwitch size=\"md\" defaultChecked label=\"Medium switch (default)\" />\n  <StatefulSwitch size=\"lg\" defaultChecked label=\"Large switch\" />\n</div>"
     },
     {
       "name": "Disabled States",
-      "description": "Non-interactive switches showing both states",
+      "description": "Locked off and locked on, both dimmed.",
       "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <Switch disabled label=\"Premium feature (upgrade required)\" />\n  <Switch disabled checked label=\"System managed (read-only)\" />\n</div>"
     },
     {
       "name": "Settings Panel",
-      "description": "Multiple switches in a realistic settings layout",
-      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '320px' }}>\n  <StatefulSwitch\n    checked\n    label=\"Push notifications\"\n    helperText=\"Receive push notifications on your device\"\n  />\n  <StatefulSwitch\n    checked\n    label=\"Email digest\"\n    helperText=\"Weekly summary of your activity\"\n  />\n  <StatefulSwitch\n    label=\"Marketing emails\"\n    helperText=\"Product updates and promotional offers\"\n  />\n</div>"
+      "description": "Stacked switches sharing one rhythm and helper column.",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '320px' }}>\n  <StatefulSwitch\n    defaultChecked\n    label=\"Push notifications\"\n    helperText=\"Receive push notifications on your device\"\n  />\n  <StatefulSwitch\n    defaultChecked\n    label=\"Email digest\"\n    helperText=\"Weekly summary of your activity\"\n  />\n  <StatefulSwitch\n    label=\"Marketing emails\"\n    helperText=\"Product updates and promotional offers\"\n  />\n</div>"
     }
   ],
   "relations": [
@@ -218,9 +207,7 @@
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",