@usefragments/ui 1.7.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefragments/ui",
-  "version": "1.7.0",
+  "version": "2.0.0",
   "license": "MIT",
   "description": "Customizable UI components built on Base UI headless primitives",
   "author": "Conan McNicholl",
@@ -240,7 +240,6 @@
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^4.3.0",
     "ajv": "8.17.1",
-    "chromatic": "^17.1.0",
     "date-fns": "^4.0.0",
     "jsdom": "^25.0.0",
     "react": "^19.0.0",
@@ -255,7 +254,7 @@
     "vite": "^6.0.0",
     "vitest": "^2.1.8",
     "vitest-axe": "^0.1.0",
-    "@usefragments/core": "1.11.0"
+    "@usefragments/core": "2.0.0"
   },
   "files": [
     "src",
@@ -270,14 +269,14 @@
     "!src/assets/*.svg",
     "!src/**/*.stories.tsx",
     "!src/**/*.ui-notes.md",
-    "!src/components/Cloud/",
+    "!src/storybook/",
     "dist",
-    "!dist/components/Cloud/",
     "fragments.json"
   ],
   "scripts": {
     "dev": "storybook dev -p 6006",
     "generate:measurements": "node scripts/generate-measurements.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
     "check:measurements": "node scripts/generate-measurements.mjs --check && node scripts/check-measurement-parity.mjs",
     "build": "pnpm run check:measurements && vite build && node ./scripts/emit-complete-styles.mjs && tsc -p tsconfig.build.json && pnpm run typecheck:fragments",
     "typecheck:fragments": "tsc -p tsconfig.fragments.json",
@@ -286,9 +285,7 @@
     "test:geometry": "node geometry/run.mjs",
     "test:geometry:self": "node --test geometry/__tests__/*.test.mjs",
     "test:geometry:types": "tsc -p geometry/tsconfig.json --noEmit",
-    "build-storybook": "storybook build",
-    "chromatic": "chromatic",
-    "chromatic:ci": "chromatic --build-script-name build-storybook"
+    "build-storybook": "storybook build"
   },
   "module": "dist/index.js"
 }

package/src/assets/nav-glyph.module.scss

@@ -0,0 +1,166 @@
+@use "../tokens/variables" as *;
+
+// ================================================================
+// NavGlyph motion — one small verb per glyph, played when the row the
+// glyph sits in is hovered or focused. Nothing moves at rest; the verb
+// answers the pointer and returns the glyph to its drawn state. Keyframe
+// names are referenced statically so CSS Modules rewrites reference and
+// definition together.
+// ================================================================
+
+.glyph {
+  display: block;
+  overflow: visible;
+}
+
+// fragments-allow FUI2015: per-element motion parameters set by the glyph, not design tokens
+$_beat: 420ms;
+$_step: 70ms;
+$_ease: cubic-bezier(0.4, 0, 0.2, 1);
+
+@mixin verb($name, $duration: $_beat, $ease: $_ease) {
+  :is(a, button):is(:hover, :focus-visible) & {
+    animation-name: $name;
+    animation-duration: $duration;
+    animation-timing-function: $ease;
+    // fragments-allow FUI2015: stagger between sibling parts of one glyph
+    animation-delay: calc(var(--i, 0) * #{$_step});
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .motion {
+    transform-box: fill-box;
+    transform-origin: center;
+  }
+
+  // Overview: the four tiles dip in turn.
+  .tile {
+    @include verb(hop, 360ms);
+  }
+
+  // Repository: the spine cracks open a hair.
+  .spine {
+    @include verb(open);
+  }
+
+  // Pull request: the branch draws into the base, then its head pops.
+  .branch {
+    @include verb(draw);
+  }
+
+  .head {
+    @include verb(pop, 240ms);
+  }
+
+  // Finding: the fly waves once on the pole.
+  .fly {
+    transform-origin: 0 0;
+
+    @include verb(wave, 520ms);
+  }
+
+  // Contract: the signature lines write themselves.
+  .line {
+    @include verb(draw, 320ms);
+  }
+
+  // Adoption: the bars rise from the baseline.
+  .bar {
+    transform-origin: 50% 100%;
+
+    @include verb(rise, 360ms);
+  }
+
+  // Component: the cube's inner edges redraw.
+  .edge {
+    @include verb(draw, 320ms);
+  }
+
+  // Setup: the prompt nudges and the cursor blinks.
+  .caret {
+    @include verb(nudge);
+  }
+
+  .cursor {
+    @include verb(blink, 600ms, steps(1, end));
+  }
+
+  // Settings: each knob slides along its rail and settles back.
+  .knob {
+    @include verb(slide);
+  }
+}
+
+@keyframes hop {
+  50% {
+    transform: scale(0.72);
+  }
+}
+
+@keyframes open {
+  50% {
+    transform: translateX(1.5px);
+  }
+}
+
+@keyframes draw {
+  from {
+    stroke-dasharray: 1;
+    stroke-dashoffset: 1;
+  }
+
+  to {
+    stroke-dasharray: 1;
+    stroke-dashoffset: 0;
+  }
+}
+
+@keyframes pop {
+  from {
+    transform: scale(0);
+  }
+
+  60% {
+    transform: scale(1.25);
+  }
+
+  to {
+    transform: scale(1);
+  }
+}
+
+@keyframes wave {
+  30% {
+    transform: rotate(-9deg);
+  }
+
+  65% {
+    transform: rotate(5deg);
+  }
+}
+
+@keyframes rise {
+  from {
+    transform: scaleY(0);
+  }
+}
+
+@keyframes nudge {
+  50% {
+    transform: translateX(1.5px);
+  }
+}
+
+@keyframes blink {
+  25%,
+  75% {
+    opacity: 0;
+  }
+}
+
+@keyframes slide {
+  50% {
+    transform: translateX(var(--dx, 2px));
+  }
+}

package/src/assets/nav-glyph.tsx

@@ -0,0 +1,188 @@
+import * as React from "react";
+import styles from "./nav-glyph.module.scss";
+
+/**
+ * The navigation glyph set: one 16px stroke glyph per governance destination.
+ * Drawn on a 16-unit grid with a 1.5 stroke, round caps and joins, and
+ * `currentColor` ink, so a glyph takes the colour of the row it sits in. The
+ * component glyph is the isometric cube the illustrated cards use, so the
+ * sidebar and the cards share one object language.
+ *
+ * Each glyph has one motion verb (see the module stylesheet) that plays when
+ * the link or button it sits in is hovered or focused. Parts that move carry
+ * `motion` plus their verb class; `--i` staggers siblings.
+ */
+export type NavGlyphName =
+  | "overview"
+  | "repository"
+  | "pullRequest"
+  | "finding"
+  | "contract"
+  | "adoption"
+  | "component"
+  | "setup"
+  | "settings";
+
+type Part = { className: string; style?: React.CSSProperties };
+
+/** A moving part: `motion` plus its verb class, and its stagger index. */
+function part(verb: string, index?: number, vars?: Record<string, string>): Part {
+  const style =
+    index === undefined && !vars
+      ? undefined
+      : ({ ...(index === undefined ? {} : { "--i": index }), ...vars } as React.CSSProperties);
+  return { className: [styles.motion, styles[verb]].join(" "), style };
+}
+
+/** A stroke that draws itself: normalised length so the verb is one keyframe. */
+function stroke(verb: string, index?: number): Part & { pathLength: number } {
+  return { ...part(verb, index), pathLength: 1 };
+}
+
+const GLYPHS: Record<NavGlyphName, React.ReactNode> = {
+  // Four tiles; the first is inked — the place you are standing.
+  overview: (
+    <>
+      <rect
+        x="2.5"
+        y="2.5"
+        width="4.5"
+        height="4.5"
+        rx="1"
+        fill="currentColor"
+        stroke="none"
+        {...part("tile", 0)}
+      />
+      <rect x="9" y="2.5" width="4.5" height="4.5" rx="1" {...part("tile", 1)} />
+      <rect x="9" y="9" width="4.5" height="4.5" rx="1" {...part("tile", 2)} />
+      <rect x="2.5" y="9" width="4.5" height="4.5" rx="1" {...part("tile", 3)} />
+    </>
+  ),
+  // A bound volume with its spine.
+  repository: (
+    <>
+      <rect x="3" y="2.5" width="10" height="11" rx="1.5" />
+      <path d="M6 2.5v11" {...part("spine")} />
+    </>
+  ),
+  // Two commits on the base branch, one on the branch merging in.
+  pullRequest: (
+    <>
+      <circle cx="4.5" cy="4" r="1.75" />
+      <circle cx="4.5" cy="12" r="1.75" />
+      <path d="M4.5 5.75v4.5" />
+      <path d="M8 4h1.75A1.75 1.75 0 0 1 11.5 5.75v4.5" {...stroke("branch")} />
+      <circle cx="11.5" cy="12" r="1.75" {...part("head", 4)} />
+    </>
+  ),
+  // A planted flag with a notched fly.
+  finding: (
+    <>
+      <path d="M4 14V2.5" />
+      <path d="M4 3h7.5l-1.75 2.5L11.5 8H4" {...part("fly")} />
+    </>
+  ),
+  // A signed sheet with a folded corner.
+  contract: (
+    <>
+      <path d="M4.5 2.5h5l3 3v7.5a1 1 0 0 1-1 1h-7a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1z" />
+      <path d="M9.5 2.5v3h3" />
+      <path d="M6.5 8.5h3" {...stroke("line", 0)} />
+      <path d="M6.5 11h3.5" {...stroke("line", 2)} />
+    </>
+  ),
+  // Three bars climbing.
+  adoption: (
+    <>
+      <path d="M2.25 13.5h11.5" />
+      <path d="M4 13.5V9.5" {...part("bar", 0)} />
+      <path d="M8 13.5V6" {...part("bar", 1)} />
+      <path d="M12 13.5V2.75" {...part("bar", 2)} />
+    </>
+  ),
+  // The isometric cube from the card art.
+  component: (
+    <>
+      <path d="M8 1.75l5.5 3.15v6.2L8 14.25l-5.5-3.15v-6.2z" />
+      <path d="M8 8.05l5.5-3.15" {...stroke("edge", 0)} />
+      <path d="M8 8.05L2.5 4.9" {...stroke("edge", 1)} />
+      <path d="M8 8.05v6.2" {...stroke("edge", 2)} />
+    </>
+  ),
+  // A terminal with its prompt.
+  setup: (
+    <>
+      <rect x="2" y="3" width="12" height="10" rx="1.5" />
+      <path d="M5 6.75l2 1.5-2 1.5" {...part("caret")} />
+      <path d="M8.75 10.25h2.5" {...part("cursor")} />
+    </>
+  ),
+  // Three sliders, each knob somewhere different.
+  settings: (
+    <>
+      <path d="M2.5 4.5h11" />
+      <circle
+        cx="10"
+        cy="4.5"
+        r="1.5"
+        fill="currentColor"
+        stroke="none"
+        {...part("knob", 0, { "--dx": "2px" })}
+      />
+      <path d="M2.5 8h11" />
+      <circle
+        cx="6"
+        cy="8"
+        r="1.5"
+        fill="currentColor"
+        stroke="none"
+        {...part("knob", 1, { "--dx": "-2px" })}
+      />
+      <path d="M2.5 11.5h11" />
+      <circle
+        cx="9.5"
+        cy="11.5"
+        r="1.5"
+        fill="currentColor"
+        stroke="none"
+        {...part("knob", 2, { "--dx": "1.5px" })}
+      />
+    </>
+  ),
+};
+
+export const NAV_GLYPH_NAMES = Object.keys(GLYPHS) as NavGlyphName[];
+
+export interface NavGlyphProps extends Omit<React.SVGAttributes<SVGSVGElement>, "name"> {
+  /** Which glyph to draw. */
+  name: NavGlyphName;
+  /** Rendered box in px; the glyph inherits `currentColor`. */
+  size?: number | string;
+}
+
+/**
+ * A navigation glyph. Decorative by default (`aria-hidden`): the label beside
+ * it names the destination. Pass `aria-label` and `role="img"` when the glyph
+ * stands alone. Its verb plays when the enclosing link or button is hovered
+ * or focused, and never under `prefers-reduced-motion: reduce`.
+ */
+export function NavGlyph({ name, size = 16, className, ...rest }: NavGlyphProps) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      focusable="false"
+      className={[styles.glyph, className].filter(Boolean).join(" ")}
+      {...rest}
+    >
+      {GLYPHS[name]}
+    </svg>
+  );
+}

package/src/components/Accordion/Accordion.module.scss

@@ -1,4 +1,5 @@
 @use "../../tokens/variables" as *;
+@use "../../tokens/measurements.generated" as measurements;
 @use "../../tokens/mixins" as *;
 @use "../../recipes/feedback" as feedback;
 
@@ -6,7 +7,7 @@
   width: 100%;
 
   > * {
-    border-bottom: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
+    border-bottom: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid var(--fui-border, $fui-border);
 
     &:last-child {
       border-bottom: none;
@@ -15,12 +16,13 @@
 }
 
 .item[data-disabled] {
-  opacity: 0.5;
+  @include disabled-state;
+
   pointer-events: none;
 }
 
 .heading {
-  margin: 0;
+  margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
   font: inherit;
 }
 

package/src/components/Alert/Alert.contract.json

@@ -9,7 +9,7 @@
   "exportName": "Alert",
   "propsSummary": [
     "children: node (required)",
-    "severity: info|success|warning|error (default: info)",
+    "tone: info|success|warning|danger (default: info)",
     "emphasis: tint|surface (default: tint)"
   ],
   "props": {
@@ -18,16 +18,16 @@
       "description": "Alert content - use Alert.Icon, Alert.Body, Alert.Title, Alert.Content, Alert.Actions, Alert.Close sub-components",
       "required": true
     },
-    "severity": {
+    "tone": {
       "type": "enum",
-      "description": "Visual severity level",
+      "description": "Tone; controls colour, icon and live-region role",
       "default": "info",
       "required": false,
-      "values": ["info", "success", "warning", "error"]
+      "values": ["info", "success", "warning", "danger"]
     },
     "emphasis": {
       "type": "enum",
-      "description": "How much surface the severity claims. `tint` washes the card in the severity colour; `surface` keeps the page background and colours only the hairline and title.",
+      "description": "How much surface the tone claims. `tint` washes the card in the tone colour; `surface` keeps the page background and colours only the hairline and title.",
       "default": "tint",
       "required": false,
       "values": ["tint", "surface"]
@@ -46,8 +46,8 @@
       "A decision the user must make first (use Dialog)"
     ],
     "guidelines": [
-      "Match severity to real stakes \u2014 an error that is not an error trains people to ignore you",
-      "Every error alert says what to do next",
+      "Match tone to real stakes \u2014 an error that is not an error trains people to ignore you",
+      "Every danger alert says what to do next",
       "Add Alert.Title only when the message needs two lines",
       "One action per alert",
       "Only dismissible when losing the message costs nothing",
@@ -57,39 +57,39 @@
     "accessibility": [
       "role=\"alert\" means assistive tech announces it on arrival",
       "Alert.Close needs its own label",
-      "Icon plus wording carry the severity \u2014 never color alone"
+      "Icon plus wording carry the tone \u2014 never color alone"
     ]
   },
   "examples": [
     {
       "name": "Info",
       "description": "Neutral context \u2014 nothing went wrong, nothing needs doing.",
-      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"info\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Content>\n      Your session will expire in 15 minutes. Save your work to avoid losing changes.\n    </Alert.Content>\n  </Alert.Body>\n</Alert>"
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert tone=\"info\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Content>\n      Your session will expire in 15 minutes. Save your work to avoid losing changes.\n    </Alert.Content>\n  </Alert.Body>\n</Alert>"
     },
     {
       "name": "Success",
       "description": "Confirms the thing the user just did actually landed.",
-      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"success\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Title>Payment processed</Alert.Title>\n    <Alert.Content>\n      Your order #12345 has been confirmed. You will receive a confirmation email shortly.\n    </Alert.Content>\n  </Alert.Body>\n</Alert>"
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert tone=\"success\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Title>Payment processed</Alert.Title>\n    <Alert.Content>\n      Your order #12345 has been confirmed. You will receive a confirmation email shortly.\n    </Alert.Content>\n  </Alert.Body>\n</Alert>"
     },
     {
       "name": "Warning",
       "description": "Nothing is broken yet \u2014 act before it is.",
-      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"warning\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Title>Storage almost full</Alert.Title>\n    <Alert.Content>\n      You have used 90% of your storage quota. Consider deleting unused files.\n    </Alert.Content>\n  </Alert.Body>\n</Alert>"
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert tone=\"warning\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Title>Storage almost full</Alert.Title>\n    <Alert.Content>\n      You have used 90% of your storage quota. Consider deleting unused files.\n    </Alert.Content>\n  </Alert.Body>\n</Alert>"
     },
     {
       "name": "Error",
       "description": "Something failed; say what to do about it.",
-      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"error\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Title>Upload failed</Alert.Title>\n    <Alert.Content>\n      The file could not be uploaded. Check your connection and try again.\n    </Alert.Content>\n  </Alert.Body>\n</Alert>"
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert tone=\"danger\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Title>Upload failed</Alert.Title>\n    <Alert.Content>\n      The file could not be uploaded. Check your connection and try again.\n    </Alert.Content>\n  </Alert.Body>\n</Alert>"
     },
     {
       "name": "With Action",
       "description": "One button, one job \u2014 more than one stalls the reader.",
-      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"warning\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Title>Update available</Alert.Title>\n    <Alert.Content>\n      A new version is available with important security fixes.\n    </Alert.Content>\n    <Alert.Actions>\n      <Alert.Action onClick={() => {}}>Update now</Alert.Action>\n    </Alert.Actions>\n  </Alert.Body>\n</Alert>"
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert tone=\"warning\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Title>Update available</Alert.Title>\n    <Alert.Content>\n      A new version is available with important security fixes.\n    </Alert.Content>\n    <Alert.Actions>\n      <Alert.Action onClick={() => {}}>Update now</Alert.Action>\n    </Alert.Actions>\n  </Alert.Body>\n</Alert>"
     },
     {
       "name": "Dismissible",
       "description": "A close button suits news the user can safely ignore.",
-      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"info\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Content>\n      You can customize your notification preferences in Settings.\n    </Alert.Content>\n  </Alert.Body>\n  <Alert.Close />\n</Alert>"
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert tone=\"info\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Content>\n      You can customize your notification preferences in Settings.\n    </Alert.Content>\n  </Alert.Body>\n  <Alert.Close />\n</Alert>"
     }
   ],
   "relations": [
@@ -111,7 +111,7 @@
   ],
   "contract": {
     "propsSummary": [
-      "severity: info|success|warning|error - visual severity",
+      "tone: info|success|warning|danger - colour, icon and live-region role",
       "Sub-components: Alert.Icon, Alert.Body, Alert.Title, Alert.Content, Alert.Actions, Alert.Action, Alert.Close",
       "Alert.Action / Alert.Close accept button props and default type=\"button\""
     ],
@@ -127,9 +127,9 @@
     "subComponents": ["Icon", "Body", "Title", "Content", "Actions", "Action", "Close"],
     "requiredChildren": ["Body"],
     "commonPatterns": [
-      "<Alert severity=\"info\"><Alert.Icon /><Alert.Body><Alert.Content>{message}</Alert.Content></Alert.Body></Alert>",
-      "<Alert severity=\"warning\"><Alert.Icon /><Alert.Body><Alert.Title>{title}</Alert.Title><Alert.Content>{message}</Alert.Content></Alert.Body></Alert>",
-      "<Alert severity=\"error\"><Alert.Icon /><Alert.Body><Alert.Title>{title}</Alert.Title><Alert.Content>{message}</Alert.Content></Alert.Body><Alert.Close /></Alert>"
+      "<Alert tone=\"info\"><Alert.Icon /><Alert.Body><Alert.Content>{message}</Alert.Content></Alert.Body></Alert>",
+      "<Alert tone=\"warning\"><Alert.Icon /><Alert.Body><Alert.Title>{title}</Alert.Title><Alert.Content>{message}</Alert.Content></Alert.Body></Alert>",
+      "<Alert tone=\"danger\"><Alert.Icon /><Alert.Body><Alert.Title>{title}</Alert.Title><Alert.Content>{message}</Alert.Content></Alert.Body><Alert.Close /></Alert>"
     ]
   },
   "provenance": {