@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Loading/index.tsx

@@ -1,14 +1,14 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import styles from './Loading.module.scss';
+import * as React from "react";
+import styles from "./Loading.module.scss";
 
 // ============================================
 // Types
 // ============================================
 
-export type LoadingSize = 'sm' | 'md' | 'lg' | 'xl';
-export type LoadingVariant = 'spinner' | 'dots' | 'pulse';
+export type LoadingSize = "sm" | "md" | "lg" | "xl";
+export type LoadingVariant = "spinner" | "dots" | "pulse";
 
 export interface LoadingProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Size of the loading indicator */
@@ -24,12 +24,12 @@ export interface LoadingProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Whether to show the loading indicator with a backdrop overlay */
   overlay?: boolean;
   /** Color variant - uses accent color by default, 'current' inherits text color */
-  color?: 'accent' | 'current' | 'muted';
+  color?: "accent" | "current" | "muted";
 }
 
 export interface LoadingInlineProps extends React.HTMLAttributes<HTMLSpanElement> {
   /** Size of the loading indicator */
-  size?: 'sm' | 'md';
+  size?: "sm" | "md";
   /** Accessible label */
   label?: string;
 }
@@ -90,90 +90,76 @@ function PulseAnimation({ className }: { className?: string }) {
 // Components
 // ============================================
 
-const LoadingRoot = React.forwardRef<HTMLDivElement, LoadingProps>(
-  function LoadingRoot(
-    {
-      size = 'md',
-      variant = 'spinner',
-      label = 'Loading...',
-      centered = false,
-      fill = false,
-      overlay = false,
-      color = 'accent',
-      className,
-      ...htmlProps
-    },
-    ref
-  ) {
-    const classes = [
-      styles.loading,
-      styles[size],
-      styles[variant],
-      styles[`color-${color}`],
-      centered && styles.centered,
-      fill && styles.fill,
-      overlay && styles.overlay,
-      className,
-    ]
-      .filter(Boolean)
-      .join(' ');
-
-    const animation = variant === 'dots'
-      ? <DotsAnimation className={styles.dots} />
-      : variant === 'pulse'
-        ? <PulseAnimation className={styles.pulse} />
-        : <SpinnerIcon className={styles.spinnerIcon} />;
-
-    const content = (
-      <div
-        ref={ref}
-        className={classes}
-        role="status"
-        aria-label={label}
-        aria-live="polite"
-        {...htmlProps}
-      >
-        {animation}
-      </div>
+const LoadingRoot = React.forwardRef<HTMLDivElement, LoadingProps>(function LoadingRoot(
+  {
+    size = "md",
+    variant = "spinner",
+    label = "Loading...",
+    centered = false,
+    fill = false,
+    overlay = false,
+    color = "accent",
+    className,
+    ...htmlProps
+  },
+  ref
+) {
+  const classes = [
+    styles.loading,
+    styles[size],
+    styles[variant],
+    styles[`color-${color}`],
+    centered && styles.centered,
+    fill && styles.fill,
+    overlay && styles.overlay,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const animation =
+    variant === "dots" ? (
+      <DotsAnimation className={styles.dotsTrack} />
+    ) : variant === "pulse" ? (
+      <PulseAnimation className={styles.pulseTrack} />
+    ) : (
+      <SpinnerIcon className={styles.spinnerIcon} />
     );
 
-    if (overlay) {
-      return (
-        <div className={styles.overlayBackdrop}>
-          {content}
-        </div>
-      );
-    }
+  const content = (
+    <div
+      ref={ref}
+      className={classes}
+      role="status"
+      aria-label={label}
+      aria-live="polite"
+      {...htmlProps}
+    >
+      {animation}
+    </div>
+  );
 
-    return content;
+  if (overlay) {
+    return <div className={styles.overlayBackdrop}>{content}</div>;
   }
-);
+
+  return content;
+});
 
 // ============================================
 // Loading.Inline - Inline text loading indicator
 // ============================================
 
 function LoadingInline({
-  size = 'sm',
-  label = 'Loading...',
+  size = "sm",
+  label = "Loading...",
   className,
   ...htmlProps
 }: LoadingInlineProps) {
-  const classes = [
-    styles.inline,
-    styles[`inline-${size}`],
-    className,
-  ]
-    .filter(Boolean)
-    .join(' ');
+  const classes = [styles.inline, styles[`inline-${size}`], className].filter(Boolean).join(" ");
 
   return (
-    <span
-      className={classes}
-      role="status"
-      aria-label={label}
-      {...htmlProps}
-    >
+    <span className={classes} role="status" aria-label={label} {...htmlProps}>
       <SpinnerIcon className={styles.inlineSpinner} />
     </span>
   );
@@ -184,28 +170,17 @@ function LoadingInline({
 // ============================================
 
 function LoadingScreen({
-  size = 'lg',
-  variant = 'spinner',
-  label = 'Loading...',
+  size = "lg",
+  variant = "spinner",
+  label = "Loading...",
   showLabel = false,
   className,
   ...htmlProps
 }: LoadingScreenProps) {
-  const classes = [
-    styles.screen,
-    className,
-  ]
-    .filter(Boolean)
-    .join(' ');
+  const classes = [styles.screen, className].filter(Boolean).join(" ");
 
   return (
-    <div
-      className={classes}
-      role="status"
-      aria-label={label}
-      aria-live="polite"
-      {...htmlProps}
-    >
+    <div className={classes} role="status" aria-label={label} aria-live="polite" {...htmlProps}>
       <LoadingRoot size={size} variant={variant} label={label} />
       {showLabel && <span className={styles.screenLabel}>{label}</span>}
     </div>
@@ -222,8 +197,4 @@ export const Loading = Object.assign(LoadingRoot, {
 });
 
 // Re-export individual components for tree-shaking
-export {
-  LoadingRoot,
-  LoadingInline,
-  LoadingScreen,
-};
+export { LoadingRoot, LoadingInline, LoadingScreen };

package/src/components/Main/Main.contract.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Main",
-  "description": "Canonical page composition owning gutter, measure, and vertical rhythm.",
+  "description": "Owns a page's gutters, reading measure, and vertical rhythm.",
   "category": "layout",
   "tags": ["main", "page", "layout", "compound"],
   "status": "stable",
@@ -45,11 +45,19 @@
     }
   },
   "usage": {
-    "when": ["Composing a page header, description, content, and footer"],
-    "whenNot": ["Application shell navigation (use AppShell)"],
+    "when": [
+      "Laying out a page's header, description, content, and footer",
+      "Giving a page one consistent gutter and measure"
+    ],
+    "whenNot": [
+      "Shell-level navigation chrome (use AppShell)",
+      "Arbitrary spacing inside a component (use Stack or Box)"
+    ],
     "guidelines": [
-      "Use one Main gutter owner per page",
-      "Compose page regions with Main.Header, Main.Description, Main.Content, and Main.Footer"
+      "One Main per page owns the gutters — do not nest them",
+      "measure=\"narrow\" caps content for reading; \"full\" uses the whole canvas",
+      "Compose regions with Main.Header, Main.Description, Main.Content, Main.Footer",
+      "Main.Description caps itself at 68ch regardless of measure"
     ],
     "accessibility": [
       "Use the default main element unless an existing shell already owns the main landmark"
@@ -58,13 +66,13 @@
   "examples": [
     {
       "name": "Full Measure",
-      "description": "Page composition that uses the full available canvas",
-      "code": "<Main measure=\"full\">\n  <Main.Header>Page statement</Main.Header>\n  <Main.Description>Supporting page context.</Main.Description>\n  <Main.Content>Page content</Main.Content>\n  <Main.Footer>Page actions</Main.Footer>\n</Main>"
+      "description": "Content fills the canvas, inset only by the page gutter.",
+      "code": "import { Box } from '@/components/Box';\nimport { Main } from '@/components/Main';\n\n<Box width=\"100%\" border rounded=\"md\">\n  <Main measure=\"full\">\n    <Main.Header>Findings</Main.Header>\n    <Main.Description>\n      Every governance finding raised against this repository, newest first.\n    </Main.Description>\n    <Main.Content>\n      Content stretches edge to edge, inset only by the page gutter.\n    </Main.Content>\n    <Main.Footer>Export report</Main.Footer>\n  </Main>\n</Box>"
     },
     {
       "name": "Narrow Measure",
-      "description": "Readable page composition constrained to the canonical 800px measure",
-      "code": "<Main measure=\"narrow\">\n  <Main.Header>Settings</Main.Header>\n  <Main.Description>Manage the workspace contract.</Main.Description>\n  <Main.Content>Settings content</Main.Content>\n  <Main.Footer>Save changes</Main.Footer>\n</Main>"
+      "description": "Caps content at the reading measure and centres it on wide screens.",
+      "code": "import { Box } from '@/components/Box';\nimport { Main } from '@/components/Main';\n\n<Box width=\"100%\" border rounded=\"md\">\n  <Main measure=\"narrow\">\n    <Main.Header>Settings</Main.Header>\n    <Main.Description>\n      Manage the workspace contract, canonical components, and token files.\n    </Main.Description>\n    <Main.Content>\n      Content is capped at the reading measure and centred, so long prose stays\n      comfortable to read on wide displays.\n    </Main.Content>\n    <Main.Footer>Save changes</Main.Footer>\n  </Main>\n</Box>"
     }
   ],
   "ai": {

package/src/components/Main/Main.module.scss

@@ -1,6 +1,4 @@
-@use "../../tokens/variables" as *;
-
-$fui-main-measure-narrow: 57.143rem !default;
+@use "../../recipes/layout";
 
 .root {
   box-sizing: border-box;
@@ -8,7 +6,7 @@ $fui-main-measure-narrow: 57.143rem !default;
   min-width: 0;
   min-height: 100%;
   margin-inline: auto;
-  padding: var(--fui-space-3, $fui-space-3);
+  padding: layout.page-gutter();
 }
 
 .full {
@@ -16,7 +14,7 @@ $fui-main-measure-narrow: 57.143rem !default;
 }
 
 .narrow {
-  max-width: $fui-main-measure-narrow;
+  max-width: layout.measure("page-narrow");
 }
 
 .header,

package/src/components/Markdown/Markdown.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Markdown",
-  "description": "Renders markdown strings as styled prose using react-markdown and remark-gfm. Supports headings, lists, tables, code blocks, blockquotes, and more.",
+  "description": "Turns a Markdown string into styled headings, lists, tables, code, and quotes.",
   "category": "display",
-  "tags": [
-    "markdown",
-    "prose",
-    "content",
-    "text",
-    "ai",
-    "chat"
-  ],
+  "tags": ["markdown", "prose", "content", "text", "ai", "chat"],
   "status": "stable",
   "dependencies": [
     {
@@ -26,11 +19,7 @@
   ],
   "sourcePath": "src/components/Markdown/index.tsx",
   "exportName": "Markdown",
-  "propsSummary": [
-    "content: string (required)",
-    "components: object",
-    "className: string"
-  ],
+  "propsSummary": ["content: string (required)", "components: object", "className: string"],
   "props": {
     "content": {
       "type": "string",
@@ -50,50 +39,45 @@
   },
   "usage": {
     "when": [
-      "Rendering AI/LLM response content",
-      "Displaying user-authored markdown text",
-      "Showing documentation or readme content",
-      "Rich text display without a WYSIWYG editor"
+      "Rendering an LLM reply",
+      "Showing text a user wrote in Markdown",
+      "Docs or readme content inside the app"
     ],
     "whenNot": [
-      "Plain text without formatting (use Text)",
-      "Editing markdown (use a markdown editor component)",
-      "Rendering trusted HTML directly (use dangerouslySetInnerHTML)"
+      "The string has no formatting (use Text)",
+      "The user needs to edit it (use an editor)"
     ],
     "guidelines": [
-      "Install react-markdown and remark-gfm as peer dependencies",
-      "Use the components prop to override default element rendering",
-      "Content is sanitized by react-markdown by default",
-      "The parser is loaded on demand, so the first render on a page is the plain-text fallback and parsed output arrives a tick later; call Markdown.preload() at startup to skip that frame",
-      "Falls back to plain text paragraphs if react-markdown is not installed",
-      "Standard div props (id, style, aria-*, data-*) are forwarded to the Markdown wrapper"
+      "react-markdown and remark-gfm are peer dependencies — install both",
+      "The parser loads on demand, so the first frame is plain text; call Markdown.preload() at startup to skip it",
+      "Without react-markdown installed it degrades to plain paragraphs",
+      "components overrides how any element renders",
+      "react-markdown sanitises the content for you"
     ],
     "accessibility": [
-      "Rendered HTML follows semantic structure (headings, lists, tables)",
-      "Links are rendered as proper anchor elements",
-      "Images include alt text from markdown syntax",
-      "Tables use proper th/td structure for screen readers"
+      "Output is real headings, lists, and tables",
+      "Links render as anchors, images keep their alt text"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic markdown with headings, paragraphs, inline code, lists, and blockquote",
+      "description": "Headings, emphasis, lists, and quotes all pick up the type scale.",
       "code": "<Markdown content={`# Hello World\n\nThis is a paragraph with **bold text** and *italic text*.\n\nHere is some \\`inline code\\` within a sentence.\n\n- First item\n- Second item\n- Third item\n\n> A blockquote for emphasis.\n`} />"
     },
     {
       "name": "GFM Table",
-      "description": "GitHub Flavored Markdown with tables and task lists",
+      "description": "remark-gfm adds tables and checkbox items on top of the basics.",
       "code": "<Markdown content={`## Data Overview\n\n| Feature    | Status    | Priority |\n|------------|-----------|----------|\n| Markdown   | Done      | High     |\n| Tables     | Done      | Medium   |\n| Task Lists | Planned   | Low      |\n\nNotes:\n- [x] Support GFM tables\n- [x] Support task lists\n- [ ] Syntax highlighting\n`} />"
     },
     {
       "name": "Code Block",
-      "description": "Markdown with fenced code blocks and inline code",
-      "code": "<Markdown content={`## Code Example\\n\\nHere is a JavaScript function:\\n\\n```js\\nfunction greet(name) {\\n  return \\`Hello, ${name}!\\`;\\n}\\n```\\n\\nAnd some inline code: \\`const x = 42;\\``} />"
+      "description": "Fenced blocks get the same code surface as CodeBlock.",
+      "code": "<Markdown content={`## Code Example\n\nHere is a JavaScript function:\n\n```js\nfunction greet(name) {\n  return 'Hello, ' + name;\n}\n```\n\nAnd some inline code: \\`const x = 42;\\``} />"
     },
     {
       "name": "Mixed Content",
-      "description": "Complex markdown mixing headings, lists, tables, blockquotes, and task lists",
+      "description": "A realistic document — the worst case worth checking.",
       "code": "<Markdown content={`# Project Update\n\n## Summary\n\nThe project is progressing well. Here are the **key highlights**:\n\n1. Completed the *design system* components\n2. Added markdown rendering support\n3. Integrated with the documentation site\n\n### Performance Metrics\n\n| Metric      | Before | After |\n|-------------|--------|-------|\n| Bundle Size | 142kb  | 98kb  |\n| Load Time   | 1.2s   | 0.8s  |\n| Lighthouse  | 72     | 95    |\n\n> These improvements were achieved through tree-shaking and code splitting.\n\n### Next Steps\n\n- [ ] Add syntax highlighting\n- [ ] Support custom themes\n- [x] GFM table support\n`} />"
     }
   ],
@@ -121,16 +105,11 @@
       "className: string - Additional CSS class",
       "Forwards standard HTML div attributes to the wrapper element"
     ],
-    "a11yRules": [
-      "A11Y_SEMANTIC_HTML"
-    ]
+    "a11yRules": ["A11Y_SEMANTIC_HTML"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root",
-      "preload"
-    ]
+    "subComponents": ["Root", "preload"]
   },
   "provenance": {
     "source": "migrated",