@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Markdown/Markdown.module.scss

@@ -1,250 +1,140 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
-
-// ============================================
-// Markdown Prose Container
-// ============================================
+@use "../../tokens/variables" as *;
+@use "../../recipes/prose" as prose;
 
 .markdown {
-  @include text-base;
-  word-wrap: break-word;
-  // Prose colour is a hook, not a constant. Markdown is routinely rendered on a
-  // surface that carries its own foreground — a Message bubble on the accent
-  // fill, an Alert, a Callout — and a fixed grey there is unreadable rather than
-  // quiet. Those surfaces point the hook at `currentColor`; on a plain page it
-  // still resolves to the secondary ramp prose has always used.
-  color: var(--fui-markdown-text, var(--fui-text-secondary, #{$fui-text-secondary}));
-  font-size: var(--fui-font-size-md, $fui-font-size-md);
-  line-height: var(--fui-line-height-prose, $fui-line-height-prose);
-
-  // Outer spacing belongs to whatever holds the prose — a Message bubble's
-  // padding, a Card's, a page's rhythm. The block's own first and last margins
-  // would add to it, or collapse through it, and either way the container ends
-  // up looking mis-padded through no fault of its own.
-  > :first-child {
-    margin-top: 0;
-  }
-
-  > :last-child {
-    margin-bottom: 0;
-  }
-
-  // ----------------------------------------
-  // Headings
-  // ----------------------------------------
-
-  h1,
-  h2,
-  h3,
-  h4,
-  h5,
-  h6 {
-    margin-top: var(--fui-space-4, $fui-space-4);
-    margin-bottom: var(--fui-space-2, $fui-space-2);
-    font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
-    line-height: var(--fui-line-height-tight, $fui-line-height-tight);
-    color: var(--fui-text-primary, $fui-text-primary);
-
-    &:first-child {
-      margin-top: 0;
-    }
-  }
-
-  h1 {
-    font-size: var(--fui-font-size-3xl, $fui-font-size-3xl);
-    line-height: var(--fui-line-height-display, $fui-line-height-display);
-    letter-spacing: var(--fui-letter-spacing-display, $fui-letter-spacing-display);
-  }
-
-  h2 {
-    font-size: var(--fui-font-size-xl, $fui-font-size-xl);
-    letter-spacing: var(--fui-letter-spacing-tight, $fui-letter-spacing-tight);
-    margin-top: var(--fui-space-8, $fui-space-8);
-  }
+  @include prose.root;
 
-  h3 {
-    font-size: var(--fui-font-size-lg, $fui-font-size-lg);
-    letter-spacing: var(--fui-letter-spacing-tight, $fui-letter-spacing-tight);
-    line-height: var(--fui-line-height-tight, $fui-line-height-tight);
-  }
-
-  h4 {
-    font-size: var(--fui-font-size-md, $fui-font-size-md);
-  }
+  overflow-wrap: anywhere;
+  color: var(--fui-markdown-text, var(--fui-text-secondary, #{$fui-text-secondary}));
 
-  h5,
-  h6 {
-    font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  p {
+    @include prose.paragraph;
   }
 
-  // ----------------------------------------
-  // Paragraphs
-  // ----------------------------------------
-
-  p {
-    margin: 0;
-    line-height: var(--fui-line-height-prose, $fui-line-height-prose);
+  @for $level from 1 through 6 {
+    h#{$level} {
+      @include prose.heading($level);
 
-    & + p {
-      margin-top: var(--fui-space-3, $fui-space-3);
+      color: var(--fui-text-primary, $fui-text-primary);
     }
   }
 
-  // ----------------------------------------
-  // Links
-  // ----------------------------------------
-
   a {
-    color: var(--fui-color-accent, $fui-color-accent);
-    text-decoration: underline;
-    text-underline-offset: 2px;
+    @include prose.link;
+
+    color: var(--fui-link-ink, #{$fui-link-ink});
 
     &:hover {
-      opacity: 0.8;
+      text-decoration: underline;
     }
   }
 
-  // ----------------------------------------
-  // Lists
-  // ----------------------------------------
+  ul {
+    @include prose.list("disc");
+  }
 
-  ul,
   ol {
-    margin: var(--fui-space-2, $fui-space-2) 0;
-    padding-left: var(--fui-space-4, $fui-space-4);
+    @include prose.list("decimal");
   }
 
-  li {
-    margin-bottom: var(--fui-space-1, $fui-space-1);
-    line-height: var(--fui-line-height-prose, $fui-line-height-prose);
-
-    &:last-child {
-      margin-bottom: 0;
+  // Markdown's tight list items carry one inline run of text + <strong> +
+  // <code>. The prose recipe's per-item subgrid fragments that run: every
+  // element child becomes its own grid row and the bare text auto-places into
+  // the marker column. Markdown lists therefore fall back to block items with
+  // a hanging absolute marker (the recipe still supplies the marker content
+  // and counter).
+  ul,
+  ol {
+    display: block;
+    padding-inline-start: calc(var(--fui-raw-space-20, 20px) + var(--fui-raw-space-8, 8px));
+
+    > li {
+      position: relative;
+      display: block;
+      min-inline-size: 0;
+
+      &::before {
+        position: absolute;
+        inset-inline-start: calc(
+          -1 * (var(--fui-raw-space-20, 20px) + var(--fui-raw-space-8, 8px))
+        );
+        inline-size: var(--fui-raw-space-20, 20px);
+        text-align: end;
+      }
     }
   }
 
-  // Nested lists
-  li > ul,
-  li > ol {
-    margin-top: var(--fui-space-1, $fui-space-1);
-    margin-bottom: 0;
+  li + li {
+    margin-block-start: var(--fui-raw-space-4, 4px);
   }
 
-  // ----------------------------------------
-  // Inline Code
-  // ----------------------------------------
+  // GFM task items are `<li><input type="checkbox"> label text</li>`. The
+  // checkbox replaces the bullet; block items already keep it inline with the
+  // label. `task-list-item` is remark-gfm's runtime class, so the selector
+  // must stay global — a module-scoped `.task-list-item` gets hashed and
+  // never matches.
+  li:global(.task-list-item) {
+    &::before {
+      content: none;
+    }
+  }
 
   code {
-    font-family: var(--fui-font-mono, $fui-font-mono);
-    font-size: 0.9em;
-    padding: 0.125em 0.375em;
-    border-radius: var(--fui-radius-sm, $fui-radius-sm);
-    background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+    @include prose.inline-code;
   }
 
-  // ----------------------------------------
-  // Code Blocks
-  // ----------------------------------------
-
   pre {
-    margin: var(--fui-space-2, $fui-space-2) 0;
-    padding: var(--fui-space-2);
+    @include prose.code-block("default");
+
     border-radius: var(--fui-radius-md, $fui-radius-md);
     background-color: var(--fui-code-bg, $fui-code-bg);
-    overflow-x: auto;
 
     code {
       padding: 0;
       background: none;
-      font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+      font: inherit;
+      letter-spacing: inherit;
     }
   }
 
-  // Only target the immediate parent wrapper of a <pre> block
-  div:has(> div > div > pre) {
-    margin: var(--fui-space-3, $fui-space-3) 0;
-  }
-
-  // ----------------------------------------
-  // Blockquotes
-  // ----------------------------------------
-
   blockquote {
-    margin: var(--fui-space-2, $fui-space-2) 0;
-    padding: var(--fui-space-1) var(--fui-space-3);
-    border-left: 3px solid var(--fui-border, $fui-border);
-    color: var(--fui-text-secondary, $fui-text-secondary);
+    @include prose.blockquote;
 
-    p {
-      margin: 0;
-    }
+    color: var(--fui-text-secondary, $fui-text-secondary);
   }
 
-  // ----------------------------------------
-  // Horizontal Rule
-  // ----------------------------------------
-
   hr {
-    margin: var(--fui-space-4, $fui-space-4) 0;
-    border: none;
-    border-top: 1px solid var(--fui-border, $fui-border);
+    @include prose.rule;
   }
 
-  // ----------------------------------------
-  // Tables (GFM)
-  // ----------------------------------------
-
   table {
-    width: 100%;
-    margin: var(--fui-space-2, $fui-space-2) 0;
+    @include prose.table;
+
+    inline-size: 100%;
     border-collapse: collapse;
-    font-size: var(--fui-font-size-sm, $fui-font-size-sm);
   }
 
   th,
   td {
-    padding: var(--fui-space-1) var(--fui-space-2);
-    border: 1px solid var(--fui-border, $fui-border);
-    text-align: left;
+    border: var(--fui-stroke-hairline, $fui-stroke-hairline) solid var(--fui-border, $fui-border);
+    text-align: start;
   }
 
   th {
-    font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
     background-color: var(--fui-bg-secondary, $fui-bg-secondary);
   }
 
-  // ----------------------------------------
-  // Images
-  // ----------------------------------------
-
   img {
-    max-width: 100%;
-    height: auto;
+    @include prose.media;
+
     border-radius: var(--fui-radius-md, $fui-radius-md);
   }
 
-  // ----------------------------------------
-  // Task Lists (GFM)
-  // ----------------------------------------
-
-  input[type='checkbox'] {
-    margin-right: var(--fui-space-1, $fui-space-1);
+  input[type="checkbox"] {
+    margin-inline-end: var(--fui-raw-space-4, 4px);
   }
 
-  // ----------------------------------------
-  // Strong & Emphasis
-  // ----------------------------------------
-
   strong {
     font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
   }
-
-  // Remove top margin from first child and bottom margin from last child
-  > *:first-child {
-    margin-top: 0;
-  }
-
-  > *:last-child {
-    margin-bottom: 0;
-  }
 }

package/src/components/Markdown/index.tsx

@@ -1,7 +1,8 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import styles from './Markdown.module.scss';
+import * as React from "react";
+import styles from "./Markdown.module.scss";
+import { isDevelopmentBuild } from "../../utils/env";
 
 // ============================================
 // Types
@@ -10,7 +11,7 @@ import styles from './Markdown.module.scss';
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type MarkdownComponentMap = Record<string, React.ComponentType<any>>;
 
-export interface MarkdownProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+export interface MarkdownProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
   /** Markdown string to render */
   content: string;
   /** Override map for markdown element components */
@@ -47,22 +48,22 @@ function loadDeps(): Promise<void> {
   if (!loadPromise) {
     loadPromise = (async () => {
       try {
-        const mod = await import('react-markdown');
+        const mod = await import("react-markdown");
         ReactMarkdown = ((mod as { default?: ReactMarkdownType }).default ??
           mod) as ReactMarkdownType;
       } catch {
         loadFailed = true;
-        if (process.env.NODE_ENV === 'development') {
+        if (isDevelopmentBuild()) {
           console.warn(
-            '[@usefragments/ui] Markdown: react-markdown is not installed. ' +
-            'Install it with: npm install react-markdown remark-gfm'
+            "[@usefragments/ui] Markdown: react-markdown is not installed. " +
+              "Install it with: npm install react-markdown remark-gfm"
           );
         }
         return;
       }
 
       try {
-        const mod = await import('remark-gfm');
+        const mod = await import("remark-gfm");
         remarkGfm = (mod as { default?: unknown }).default ?? mod;
       } catch {
         // remark-gfm is optional; markdown still works without it
@@ -79,11 +80,11 @@ function loadDeps(): Promise<void> {
 function FallbackRenderer({ content }: { content: string }) {
   const paragraphs = content.split(/\n{2,}/);
   return (
-    <div>
-      {paragraphs.map((p) => (
-        <p key={p}>{p}</p>
+    <>
+      {paragraphs.map((p, index) => (
+        <p key={index}>{p}</p>
       ))}
-    </div>
+    </>
   );
 }
 
@@ -91,49 +92,47 @@ function FallbackRenderer({ content }: { content: string }) {
 // Component
 // ============================================
 
-const MarkdownRoot = React.forwardRef<HTMLDivElement, MarkdownProps>(
-  function Markdown({ content, components: componentOverrides, className, ...htmlProps }, ref) {
-    // The parser resolves asynchronously, so the first mount on a page renders
-    // the fallback and then swaps. Both module-level results are cached, so
-    // every later mount is synchronous; an app that knows prose is coming can
-    // skip even the first swap by calling Markdown.preload() up front.
-    const [, rerender] = React.useReducer((n: number) => n + 1, 0);
-
-    React.useEffect(() => {
-      if (ReactMarkdown || loadFailed) return;
-      let active = true;
-      void loadDeps().then(() => {
-        if (active) rerender();
-      });
-      return () => {
-        active = false;
-      };
-    }, []);
-
-    const classes = [styles.markdown, className].filter(Boolean).join(' ');
-
-    if (!ReactMarkdown) {
-      return (
-        <div ref={ref} {...htmlProps} className={classes}>
-          <FallbackRenderer content={content} />
-        </div>
-      );
-    }
-
-    const plugins = remarkGfm ? [remarkGfm] : [];
-
+const MarkdownRoot = React.forwardRef<HTMLDivElement, MarkdownProps>(function Markdown(
+  { content, components: componentOverrides, className, ...htmlProps },
+  ref
+) {
+  // The parser resolves asynchronously, so the first mount on a page renders
+  // the fallback and then swaps. Both module-level results are cached, so
+  // every later mount is synchronous; an app that knows prose is coming can
+  // skip even the first swap by calling Markdown.preload() up front.
+  const [, rerender] = React.useReducer((n: number) => n + 1, 0);
+
+  React.useEffect(() => {
+    if (ReactMarkdown || loadFailed) return;
+    let active = true;
+    void loadDeps().then(() => {
+      if (active) rerender();
+    });
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  const classes = [styles.markdown, className].filter(Boolean).join(" ");
+
+  if (!ReactMarkdown) {
     return (
       <div ref={ref} {...htmlProps} className={classes}>
-        <ReactMarkdown
-          remarkPlugins={plugins}
-          components={componentOverrides}
-        >
-          {content}
-        </ReactMarkdown>
+        <FallbackRenderer content={content} />
       </div>
     );
   }
-);
+
+  const plugins = remarkGfm ? [remarkGfm] : [];
+
+  return (
+    <div ref={ref} {...htmlProps} className={classes}>
+      <ReactMarkdown remarkPlugins={plugins} components={componentOverrides}>
+        {content}
+      </ReactMarkdown>
+    </div>
+  );
+});
 
 export const Markdown = Object.assign(MarkdownRoot, {
   Root: MarkdownRoot,

package/src/components/Menu/Menu.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Menu",
-  "description": "Dropdown menu for actions and commands. Supports submenus, check items, radio groups, and keyboard shortcuts.",
-  "category": "feedback",
-  "tags": [
-    "menu",
-    "dropdown",
-    "actions",
-    "context-menu",
-    "commands",
-    "submenu"
-  ],
+  "description": "Drops a list of actions below a trigger, driveable entirely by keyboard.",
+  "category": "overlays",
+  "tags": ["menu", "dropdown", "actions", "context-menu", "commands", "submenu"],
   "status": "stable",
   "sourcePath": "src/components/Menu/index.tsx",
   "exportName": "Menu",
@@ -52,26 +45,23 @@
   },
   "usage": {
     "when": [
-      "Overflow actions that dont fit in the toolbar",
-      "Context menus (right-click)",
-      "User account menus",
-      "Grouped actions with separators",
-      "Nested menus with submenus"
+      "Actions that do not fit in the toolbar",
+      "Right-click context actions",
+      "Account and profile actions",
+      "Related actions that read better grouped"
     ],
     "whenNot": [
-      "Selecting from options (use Select)",
-      "Navigation (use Tabs or navigation components)",
-      "Form selection (use Select or RadioGroup)"
+      "Picking a value for a form (use Select)",
+      "Moving between pages or views (use Tabs or NavigationMenu)",
+      "One of a few visible choices (use RadioGroup)"
     ],
     "guidelines": [
-      "Group related actions with Menu.Group",
-      "Use separators to divide action categories",
-      "Include keyboard shortcuts where applicable",
-      "Use danger variant for destructive actions",
-      "Keep menu items under 10-12 for usability",
-      "Use checked prop on Menu.Item for simple selection state",
-      "Use Menu.Submenu for nested secondary options",
-      "Menu.Trigger supports asChild for links/router-link components (single valid element child required)"
+      "Group related actions and separate the rest",
+      "Show the keyboard shortcut where one exists",
+      "Mark destructive actions with the danger variant",
+      "Past a dozen rows, reach for Command instead",
+      "Nest at most one level of submenu",
+      "asChild on Trigger needs a single element child"
     ],
     "accessibility": [
       "Full keyboard navigation with arrow keys",
@@ -84,37 +74,37 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic dropdown menu",
+      "description": "Plain actions, one per row.",
       "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"secondary\">Actions</Button>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.Item onSelect={() => {}}>Edit</Menu.Item>\n    <Menu.Item onSelect={() => {}}>Duplicate</Menu.Item>\n    <Menu.Separator />\n    <Menu.Item danger onSelect={() => {}}>Delete</Menu.Item>\n  </Menu.Content>\n</Menu>"
     },
     {
       "name": "With Shortcuts",
-      "description": "Menu items with keyboard shortcuts",
+      "description": "Trailing keys teach the faster path.",
       "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"secondary\">Edit</Button>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.Item shortcut=\"Ctrl+Z\" onSelect={() => {}}>Undo</Menu.Item>\n    <Menu.Item shortcut=\"Ctrl+Y\" onSelect={() => {}}>Redo</Menu.Item>\n    <Menu.Separator />\n    <Menu.Item shortcut=\"Ctrl+C\" onSelect={() => {}}>Copy</Menu.Item>\n    <Menu.Item shortcut=\"Ctrl+V\" onSelect={() => {}}>Paste</Menu.Item>\n  </Menu.Content>\n</Menu>"
     },
     {
       "name": "With Groups",
-      "description": "Menu with labeled groups",
+      "description": "Labels separate unrelated actions.",
       "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"secondary\">Options</Button>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.Group>\n      <Menu.GroupLabel>View</Menu.GroupLabel>\n      <Menu.Item onSelect={() => {}}>Zoom In</Menu.Item>\n      <Menu.Item onSelect={() => {}}>Zoom Out</Menu.Item>\n    </Menu.Group>\n    <Menu.Separator />\n    <Menu.Group>\n      <Menu.GroupLabel>Layout</Menu.GroupLabel>\n      <Menu.Item onSelect={() => {}}>Grid View</Menu.Item>\n      <Menu.Item onSelect={() => {}}>List View</Menu.Item>\n    </Menu.Group>\n  </Menu.Content>\n</Menu>"
     },
     {
       "name": "With Checkboxes",
-      "description": "Menu with toggleable checkbox options",
+      "description": "Rows that stay open while you toggle them.",
       "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"secondary\">Display</Button>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.CheckboxItem defaultChecked>Show Grid</Menu.CheckboxItem>\n    <Menu.CheckboxItem defaultChecked>Show Rulers</Menu.CheckboxItem>\n    <Menu.CheckboxItem>Show Guides</Menu.CheckboxItem>\n  </Menu.Content>\n</Menu>"
     },
     {
       "name": "With Checked Items",
-      "description": "Filter menu with check marks indicating active selections",
+      "description": "Ticks mark which filters are on.",
       "code": "<CheckedItemsMenuDemo />"
     },
     {
       "name": "With Submenu",
-      "description": "Menu with nested submenu for grouped secondary options",
+      "description": "Secondary options nest one level deep.",
       "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"secondary\">File</Button>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.Item onSelect={() => {}}>New File</Menu.Item>\n    <Menu.Item onSelect={() => {}}>Open</Menu.Item>\n    <Menu.Separator />\n    <Menu.Submenu>\n      <Menu.SubmenuTrigger>Export As</Menu.SubmenuTrigger>\n      <Menu.Content side=\"right\" align=\"start\">\n        <Menu.Item onSelect={() => {}}>PNG</Menu.Item>\n        <Menu.Item onSelect={() => {}}>SVG</Menu.Item>\n        <Menu.Item onSelect={() => {}}>PDF</Menu.Item>\n      </Menu.Content>\n    </Menu.Submenu>\n    <Menu.Separator />\n    <Menu.Item danger onSelect={() => {}}>Delete</Menu.Item>\n  </Menu.Content>\n</Menu>"
     },
     {
       "name": "Link Trigger",
-      "description": "Use asChild with a non-button trigger element",
+      "description": "asChild lets a link open it.",
       "code": "<Menu>\n  <Menu.Trigger asChild>\n    <a href=\"#menu-actions\">Open menu</a>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.Item onSelect={() => {}}>Inspect</Menu.Item>\n    <Menu.Item onSelect={() => {}}>Rename</Menu.Item>\n  </Menu.Content>\n</Menu>"
     }
   ],
@@ -140,10 +130,7 @@
       "Menu.Item shortcut: string - keyboard shortcut text",
       "Menu.Item checked: boolean - check indicator for selection state"
     ],
-    "a11yRules": [
-      "A11Y_MENU_KEYBOARD",
-      "A11Y_MENU_ROLE"
-    ]
+    "a11yRules": ["A11Y_MENU_KEYBOARD", "A11Y_MENU_ROLE"]
   },
   "ai": {
     "compositionPattern": "compound",
@@ -160,10 +147,7 @@
       "Submenu",
       "SubmenuTrigger"
     ],
-    "requiredChildren": [
-      "Trigger",
-      "Content"
-    ],
+    "requiredChildren": ["Trigger", "Content"],
     "commonPatterns": [
       "<Menu><Menu.Trigger asChild><Button>Actions</Button></Menu.Trigger><Menu.Content><Menu.Item>{action1}</Menu.Item><Menu.Separator /><Menu.Item danger>{delete}</Menu.Item></Menu.Content></Menu>"
     ]