@usefragments/ui 1.6.0 → 1.7.0

package/src/components/Chart/index.tsx

@@ -3,6 +3,7 @@
 import * as React from "react";
 import { mergeAriaIds } from "../../utils/aria";
 import styles from "./Chart.module.scss";
+import { isDevelopmentBuild } from "../../utils/env";
 
 // ============================================
 // Types (self-owned — no external dependency for types)
@@ -74,7 +75,7 @@ function loadChartDeps(): Promise<void> {
         _RechartsLegend = rc.Legend as unknown as React.ComponentType<Record<string, unknown>>;
       } catch {
         _chartFailed = true;
-        if (process.env.NODE_ENV === "development") {
+        if (isDevelopmentBuild()) {
           console.warn(
             "[@usefragments/ui] Chart: recharts is not installed. " +
               "Install it with: npm install recharts"
@@ -132,6 +133,34 @@ export function ChartContainer({
   ...htmlProps
 }: ChartContainerProps) {
   const chartId = React.useId();
+  const frameRef = React.useRef<HTMLDivElement | null>(null);
+  // Recharts only lays a chart out once it knows a pixel box. Percentage
+  // sizing leaves the first paint blank until something else happens to
+  // resize the window, so the container measures its own frame and hands the
+  // chart real numbers — re-measured whenever the frame changes.
+  const [frame, setFrame] = React.useState<{ width: number; height: number } | null>(null);
+
+  React.useEffect(() => {
+    const element = frameRef.current;
+    if (!element || typeof ResizeObserver === "undefined") return;
+
+    const measure = () => {
+      const rect = element.getBoundingClientRect();
+      const width = Math.round(rect.width);
+      const height = Math.round(rect.height);
+      setFrame((current) =>
+        current && current.width === width && current.height === height
+          ? current
+          : { width, height }
+      );
+    };
+
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+
   const summaryId = summary ? `chart-summary-${chartId}` : undefined;
   const dataTableId = dataTable ? `chart-data-${chartId}` : undefined;
 
@@ -149,12 +178,12 @@ export function ChartContainer({
   // Inject sizing props into the chart child (recharts API).
   // Only pass `responsive` for custom component types to avoid leaking the
   // prop to intrinsic DOM nodes in test/demo usage.
-  const chartChildProps: Record<string, unknown> = {
-    width: "100%",
-    height: "100%",
-  };
+  const measured = frame !== null && frame.width > 0 && frame.height > 0;
+  const chartChildProps: Record<string, unknown> = measured
+    ? { width: frame.width, height: frame.height }
+    : { width: "100%", height: "100%" };
 
-  if (typeof children.type !== "string") {
+  if (!measured && typeof children.type !== "string") {
     chartChildProps.responsive = true;
   }
 
@@ -167,6 +196,7 @@ export function ChartContainer({
     <ChartConfigContext.Provider value={config}>
       <div
         {...htmlProps}
+        ref={frameRef}
         className={rootClasses}
         style={{ ...cssVars, ...style }}
         role="img"

package/src/components/Checkbox/Checkbox.contract.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Checkbox",
-  "description": "Binary toggle for form fields. Use for options that require explicit submission, unlike Switch which takes effect immediately.",
-  "category": "forms",
+  "description": "Selects options that take effect when a form is submitted.",
+  "category": "inputs",
   "tags": ["checkbox", "form", "boolean", "selection", "input"],
   "status": "stable",
   "sourcePath": "src/components/Checkbox/index.tsx",
@@ -139,63 +139,63 @@
   },
   "usage": {
     "when": [
-      "Form fields requiring explicit submission",
-      "Multi-select from a list of options",
-      "Terms and conditions acceptance",
-      "Filter or preference checklists"
+      "Choices that apply only once the form is submitted",
+      "Picking several items from a list",
+      "Accepting terms",
+      "Filter and preference lists"
     ],
     "whenNot": [
-      "Immediate effect settings (use Switch)",
-      "Single selection from options (use RadioGroup)",
-      "Selecting from many options (use Select)"
+      "Settings that apply instantly (use Switch)",
+      "One choice from a few (use RadioGroup)",
+      "Many options (use Select)"
     ],
     "guidelines": [
-      "Always include a visible label",
-      "Use helperText for additional context when needed",
-      "Group related checkboxes visually",
-      "Use indeterminate state for parent/child relationships"
+      "Always show a label",
+      "Add helperText when the consequence is not obvious",
+      "Keep related boxes together",
+      "Use indeterminate for a parent whose children are partly checked"
     ],
     "accessibility": [
-      "Proper label association",
-      "Keyboard accessible (Space to toggle)",
-      "Visible focus indicator",
-      "Indeterminate state properly announced"
+      "Label is tied to the box",
+      "Space toggles it",
+      "Focus ring stays visible",
+      "Indeterminate is announced as mixed"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic checkbox with label",
+      "description": "One box, one label, off to start.",
       "code": "<StatefulCheckbox label=\"Accept terms and conditions\" />"
     },
     {
       "name": "With Helper Text",
-      "description": "Checkbox with helper text",
+      "description": "Second line spells out what opting in does.",
       "code": "<StatefulCheckbox\n  label=\"Email notifications\"\n  helperText=\"Receive email updates about your account activity\"\n/>"
     },
     {
       "name": "Checked",
-      "description": "Pre-checked checkbox",
+      "description": "Starts on.",
       "code": "<StatefulCheckbox defaultChecked label=\"Subscribe to newsletter\" />"
     },
     {
       "name": "Indeterminate",
-      "description": "Partial selection state",
+      "description": "A dash on the parent means only some children are on.",
       "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Checkbox indeterminate label=\"Select all\" />\n  <div style={{ marginLeft: '24px', display: 'flex', flexDirection: 'column', gap: '8px' }}>\n    <StatefulCheckbox defaultChecked label=\"Option 1\" />\n    <StatefulCheckbox label=\"Option 2\" />\n    <StatefulCheckbox defaultChecked label=\"Option 3\" />\n  </div>\n</div>"
     },
     {
       "name": "Sizes",
-      "description": "Available size options",
+      "description": "Three box sizes: sm, md, lg.",
       "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <StatefulCheckbox size=\"sm\" label=\"Small checkbox\" />\n  <StatefulCheckbox size=\"md\" label=\"Medium checkbox\" />\n  <StatefulCheckbox size=\"lg\" label=\"Large checkbox\" />\n</div>"
     },
     {
       "name": "Disabled",
-      "description": "Non-interactive states",
+      "description": "Locked in both positions, on and off.",
       "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Checkbox disabled label=\"Disabled unchecked\" />\n  <Checkbox disabled checked label=\"Disabled checked\" />\n</div>"
     },
     {
       "name": "Custom Styling Targets",
-      "description": "Use explicit class targets for control vs content styling",
+      "description": "controlClassName styles the box, contentClassName the text.",
       "code": "<Checkbox\n  label=\"Styled checkbox\"\n  helperText=\"Control and content wrappers can be targeted independently\"\n  controlClassName=\"demo-checkbox-control\"\n  contentClassName=\"demo-checkbox-content\"\n/>"
     }
   ],

package/src/components/Checkbox/Checkbox.module.scss

@@ -49,21 +49,15 @@
 
   &[data-checked],
   &[data-indeterminate] {
-    background-color: var(--fui-button-primary-base, $fui-color-accent);
-    border-color: var(
-      --fui-button-primary-border,
-      var(--fui-button-primary-base, #{$fui-color-accent})
-    );
+    background-color: var(--fui-control-checked-bg, $fui-color-accent);
+    border-color: var(--fui-control-checked-border, $fui-color-accent);
     box-shadow: inset 0 1px 0 color-mix(in srgb, white 24%, transparent);
   }
 
   &[data-checked]:hover:not([data-disabled]),
   &[data-indeterminate]:hover:not([data-disabled]) {
-    background-color: var(--fui-button-primary-hover, $fui-color-accent);
-    border-color: var(
-      --fui-button-primary-border-hover,
-      var(--fui-button-primary-hover, #{$fui-color-accent})
-    );
+    background-color: var(--fui-control-checked-bg-hover, $fui-color-accent-hover);
+    border-color: var(--fui-control-checked-border-hover, $fui-color-accent-hover);
   }
 
   &[data-invalid] {
@@ -77,7 +71,6 @@
     box-shadow: inset 0 0 0 1px
       color-mix(in srgb, var(--fui-color-danger-text, #{$fui-color-danger-text}) 35%, transparent);
   }
-
 }
 
 // Size variants
@@ -99,24 +92,40 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  color: var(--fui-button-primary-color, #fff);
+  color: var(--fui-control-checked-color, $fui-color-on-accent);
 
   svg {
     width: var(--fui-icon-xs, $fui-icon-xs);
     height: var(--fui-icon-xs, $fui-icon-xs);
   }
 
-  // Animation
+  // Animation: the mark draws itself in (stroke-dashoffset over the
+  // pathLength-normalized glyphs) instead of popping. Opacity keeps the
+  // un-draw exit from lingering.
   opacity: 0;
-  transform: scale(0.8);
-  transition:
-    opacity var(--fui-transition-fast, $fui-transition-fast),
-    transform var(--fui-transition-fast, $fui-transition-fast);
+  transition: opacity var(--fui-transition-fast, $fui-transition-fast);
+
+  svg :is(polyline, line) {
+    stroke-dasharray: 24;
+    stroke-dashoffset: 24;
+    transition: stroke-dashoffset var(--fui-transition-normal, $fui-transition-normal);
+  }
 
   [data-checked] > &,
   [data-indeterminate] > & {
     opacity: 1;
-    transform: scale(1);
+
+    svg :is(polyline, line) {
+      stroke-dashoffset: 0;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+
+    svg :is(polyline, line) {
+      transition: none;
+    }
   }
 
   [data-invalid][data-checked] > &,
@@ -173,23 +182,23 @@
 
   &:focus-within:not([data-disabled]) {
     @include focus-ring;
-    border-color: var(--fui-button-primary-base, $fui-color-accent);
+    border-color: var(--fui-control-checked-border, $fui-color-accent);
   }
 
   &:has([data-checked]),
   &:has([data-indeterminate]) {
     background: color-mix(
       in srgb,
-      var(--fui-button-primary-base, #{$fui-color-accent}) 13%,
+      var(--fui-control-checked-bg, #{$fui-color-accent}) 13%,
       transparent
     );
     border-color: color-mix(
       in srgb,
-      var(--fui-button-primary-base, #{$fui-color-accent}) 62%,
+      var(--fui-control-checked-border, #{$fui-color-accent}) 62%,
       transparent
     );
     box-shadow: 0 0 0 1px
-      color-mix(in srgb, var(--fui-button-primary-base, #{$fui-color-accent}) 28%, transparent);
+      color-mix(in srgb, var(--fui-control-checked-border, #{$fui-color-accent}) 28%, transparent);
   }
 
   &[data-size="sm"] {
@@ -217,7 +226,7 @@
 
     &[data-checked],
     &[data-indeterminate] {
-      border-color: var(--fui-button-primary-base, $fui-color-accent);
+      border-color: var(--fui-control-checked-border, $fui-color-accent);
     }
 
     &[data-invalid] {

package/src/components/Checkbox/index.tsx

@@ -93,7 +93,9 @@ function CheckIcon() {
       strokeLinejoin="round"
       aria-hidden="true"
     >
-      <polyline points="20 6 9 17 4 12" />
+      {/* Point order = draw order: the mark draws short arm first, then the
+          long stroke. pathLength normalizes the dash budget for the CSS draw. */}
+      <polyline points="4 12 9 17 20 6" pathLength={24} />
     </svg>
   );
 }
@@ -110,7 +112,7 @@ function MinusIcon() {
       strokeLinejoin="round"
       aria-hidden="true"
     >
-      <line x1="5" y1="12" x2="19" y2="12" />
+      <line x1="5" y1="12" x2="19" y2="12" pathLength={24} />
     </svg>
   );
 }

package/src/components/Chip/Chip.contract.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Chip",
-  "description": "Interactive pill-shaped element for filtering, selecting, and tagging. Supports single and multi-select via Chip.Group.",
-  "category": "forms",
+  "description": "Pill control for filtering, multi-select, and removable tags.",
+  "category": "inputs",
   "tags": ["chip", "tag", "filter", "selection", "multi-select", "action"],
   "status": "stable",
   "sourcePath": "src/components/Chip/index.tsx",
@@ -79,77 +79,70 @@
   },
   "usage": {
     "when": [
-      "Filtering content by categories or tags",
-      "Multi-select scenarios like choosing interests or skills",
-      "Toggling options in a compact pill-shaped control",
-      "Displaying removable user-applied filters"
+      "Filtering a list by tag or category",
+      "Multi-select from a compact set",
+      "Showing filters the user can dismiss"
     ],
     "whenNot": [
-      "Display-only status labels (use Badge)",
-      "Navigation between views (use Tabs)",
-      "Binary on/off state (use Switch)",
-      "Primary call-to-action (use Button)"
+      "Read-only status — use Badge",
+      "Switching views — use Tabs",
+      "On/off state — use Switch",
+      "A main call to action — use Button"
     ],
     "guidelines": [
-      "Keep chip labels short (1-3 words)",
-      "Use Chip.Group for multi-select sets with shared state",
-      "Keep the default micro size for filters and tags; opt into a larger size only when the surrounding control track requires it",
-      "Use onRemove only when users should be able to dismiss the chip",
-      "Pair avatar chips with user-related selections (assignees, reviewers)",
-      "Provide an explicit value on Chip when using non-string/custom JSX children inside Chip.Group"
+      "One to three words per chip",
+      "Chip.Group when chips share selection state",
+      "Keep xs for filters and tags; size up only to match a taller control track",
+      "onRemove only when the chip is genuinely dismissible",
+      "Pass an explicit value when children are custom JSX"
     ],
     "accessibility": [
-      "Chips are buttons and use aria-pressed for selection state",
-      "Chip.Group is a grouping wrapper; add role/aria-label when needed for assistive context",
-      "Remove buttons include descriptive aria-label with chip text",
-      "Disabled chips are properly excluded from interaction"
+      "Chips are buttons; selection is reported via aria-pressed",
+      "Add role and aria-label to Chip.Group when the set needs a name",
+      "Remove buttons carry the chip text in their aria-label",
+      "Disabled chips are skipped by keyboard and pointer"
     ]
   },
   "examples": [
     {
-      "name": "Default",
-      "description": "Basic filled chip",
-      "code": "<Chip>Default</Chip>"
+      "name": "Variants",
+      "description": "Tinted, hairline, and accent-soft chrome.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Chip variant=\"filled\">Filled</Chip>\n  <Chip variant=\"outlined\">Outlined</Chip>\n  <Chip variant=\"soft\">Soft</Chip>\n</Stack>"
     },
     {
-      "name": "Outline",
-      "description": "Chip with border using the \"outline\" alias for \"outlined\"",
-      "code": "<div style={{ display: 'flex', gap: '8px' }}>\n  <Chip variant=\"outline\">Outline</Chip>\n  <Chip variant=\"outline\" selected>Outline Selected</Chip>\n</div>"
+      "name": "Sizes",
+      "description": "xs for filter rows; larger sizes match taller field tracks.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\" wrap>\n  <Chip variant=\"outlined\" size=\"xs\">Extra small</Chip>\n  <Chip variant=\"outlined\" size=\"sm\">Small</Chip>\n  <Chip variant=\"outlined\" size=\"md\">Medium</Chip>\n  <Chip variant=\"outlined\" size=\"lg\">Large</Chip>\n</Stack>"
     },
     {
       "name": "Selected",
-      "description": "Chip in selected state across variants",
-      "code": "<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Chip selected>Filled</Chip>\n  <Chip variant=\"outlined\" selected>Outlined</Chip>\n  <Chip variant=\"soft\" selected>Soft</Chip>\n</Stack>"
+      "description": "All three variants share one selection treatment.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Chip selected>Filled</Chip>\n  <Chip variant=\"outlined\" selected>Outlined</Chip>\n  <Chip variant=\"soft\" selected>Soft</Chip>\n</Stack>"
     },
     {
       "name": "With Avatar",
-      "description": "Chip with a leading avatar image",
+      "description": "Leading face, for people-shaped selections.",
       "code": "<Chip avatar={<img src=\"https://i.pravatar.cc/32?u=chip\" alt=\"\" />}>\n  Jane Doe\n</Chip>"
     },
     {
       "name": "With Remove",
-      "description": "Removable chip with dismiss button",
-      "code": "<div style={{ display: 'flex', gap: '8px' }}>\n  <Chip onRemove={() => {}}>React</Chip>\n  <Chip onRemove={() => {}}>TypeScript</Chip>\n  <Chip onRemove={() => {}}>SCSS</Chip>\n</div>"
-    },
-    {
-      "name": "Selected Removable",
-      "description": "Selected removable chips retain the shared selection treatment across variants",
-      "code": "<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Chip selected onRemove={() => {}}>Filled</Chip>\n  <Chip variant=\"outlined\" selected onRemove={() => {}}>Outlined</Chip>\n  <Chip variant=\"soft\" selected onRemove={() => {}}>Soft</Chip>\n</Stack>"
+      "description": "Trailing dismiss button clears the tag.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Chip variant=\"outlined\" onRemove={() => {}}>React</Chip>\n  <Chip variant=\"outlined\" selected onRemove={() => {}}>TypeScript</Chip>\n  <Chip variant=\"soft\" onRemove={() => {}}>SCSS</Chip>\n</Stack>"
     },
     {
       "name": "Chip Group",
-      "description": "Multi-select chip set with shared state",
+      "description": "Selection state is held by the group, not each chip.",
       "code": "<Chip.Group defaultValue={['react']}>\n  <Chip value=\"react\">React</Chip>\n  <Chip value=\"vue\">Vue</Chip>\n  <Chip value=\"angular\">Angular</Chip>\n  <Chip value=\"svelte\">Svelte</Chip>\n</Chip.Group>"
     },
     {
       "name": "Chip Group with Custom Labels",
-      "description": "Use explicit values when chip labels are custom JSX",
+      "description": "Custom JSX children need an explicit value.",
       "code": "<Chip.Group aria-label=\"Assignees\">\n  <Chip value=\"jane\">\n    <span>Jane Doe</span>\n  </Chip>\n  <Chip value=\"sam\">\n    <span>Sam Lee</span>\n  </Chip>\n</Chip.Group>"
     },
     {
       "name": "Disabled",
-      "description": "Chip in disabled state",
-      "code": "<div style={{ display: 'flex', gap: '8px' }}>\n  <Chip disabled>Disabled</Chip>\n  <Chip disabled selected>Disabled Selected</Chip>\n</div>"
+      "description": "Dimmed and unreachable, selected or not.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Chip variant=\"outlined\" disabled>Disabled</Chip>\n  <Chip variant=\"outlined\" disabled selected>Disabled selected</Chip>\n</Stack>"
     }
   ],
   "relations": [

package/src/components/Chip/Chip.module.scss

@@ -13,7 +13,8 @@
 
   &:active:not(:disabled) {
     background-color: var(--fui-field-selection-bg-hover, $fui-bg-hover);
-    box-shadow: inset 0 0 0 1px var(--fui-field-selection-border, $fui-border-strong);
+    box-shadow: inset 0 0 0 var(--fui-stroke-hairline, 1px)
+      var(--fui-field-selection-border, $fui-border-strong);
   }
 }
 
@@ -24,7 +25,6 @@
 
   border-radius: var(--fui-radius-full, $fui-radius-full);
   white-space: nowrap;
-  user-select: none;
 }
 
 .withRemove {

package/src/components/Chip/index.tsx

@@ -2,6 +2,7 @@
 
 import * as React from "react";
 import styles from "./Chip.module.scss";
+import { isProductionBuild } from "../../utils/env";
 
 /**
  * Chip for selections, filters, and tags. Use with Chip.Group for multi-select.
@@ -165,7 +166,7 @@ function ChipGroupInner(
           if (child.props.value != null) return child.props.value;
           if (typeof child.props.children === "string") return child.props.children;
           if (child.key != null) return String(child.key);
-          if (process.env.NODE_ENV !== "production") {
+          if (!isProductionBuild()) {
             // Non-string labels need an explicit value to avoid unstable group selection keys.
             console.warn(
               "Chip.Group: Chips with non-string children should provide a `value` prop."