@usefragments/ui 1.6.0 → 2.0.0

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

@@ -1,4 +1,5 @@
 @use "../../tokens/variables" as *;
+@use "../../tokens/measurements.generated" as measurements;
 @use "../../recipes/prose" as prose;
 
 .markdown {
@@ -22,10 +23,10 @@
   a {
     @include prose.link;
 
-    color: var(--fui-color-accent, $fui-color-accent);
+    color: var(--fui-link-ink, #{$fui-link-ink});
 
     &:hover {
-      opacity: 0.8;
+      text-decoration: underline;
     }
   }
 
@@ -37,8 +38,46 @@
     @include prose.list("decimal");
   }
 
+  // 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;
+      }
+    }
+  }
+
   li + li {
-    margin-block-start: var(--fui-raw-space-4);
+    margin-block-start: var(--fui-raw-space-4, 4px);
+  }
+
+  // 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 {
@@ -52,7 +91,7 @@
     background-color: var(--fui-code-bg, $fui-code-bg);
 
     code {
-      padding: 0;
+      padding: var(--fui-raw-space-0, #{measurements.raw-space(0)});
       background: none;
       font: inherit;
       letter-spacing: inherit;
@@ -78,7 +117,7 @@
 
   th,
   td {
-    border: var(--fui-stroke-hairline) solid var(--fui-border, $fui-border);
+    border: var(--fui-stroke-hairline, $fui-stroke-hairline) solid var(--fui-border, $fui-border);
     text-align: start;
   }
 
@@ -93,7 +132,7 @@
   }
 
   input[type="checkbox"] {
-    margin-inline-end: var(--fui-raw-space-4);
+    margin-inline-end: var(--fui-raw-space-4, 4px);
   }
 
   strong {

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
@@ -80,8 +81,8 @@ function FallbackRenderer({ content }: { content: string }) {
   const paragraphs = content.split(/\n{2,}/);
   return (
     <>
-      {paragraphs.map((p) => (
-        <p key={p}>{p}</p>
+      {paragraphs.map((p, index) => (
+        <p key={index}>{p}</p>
       ))}
     </>
   );
@@ -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",
-      "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>"
+      "description": "Plain actions, one per row.",
+      "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"soft\">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",
-      "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>"
+      "description": "Trailing keys teach the faster path.",
+      "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"soft\">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",
-      "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>"
+      "description": "Labels separate unrelated actions.",
+      "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"soft\">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",
-      "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>"
+      "description": "Rows that stay open while you toggle them.",
+      "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"soft\">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",
-      "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>"
+      "description": "Secondary options nest one level deep.",
+      "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"soft\">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>"
     ]

package/src/components/Menu/Menu.module.scss

@@ -1,28 +1,44 @@
 @use "../../tokens/variables" as *;
+@use "../../tokens/measurements.generated" as measurements;
+@use "../../recipes/layout" as layout;
 @use "../../recipes/popup" as popup;
 @use "../../recipes/typography" as typography;
 
 .positioner {
-  z-index: var(--fui-overlay-layer-anchored, 52);
+  z-index: var(--fui-overlay-layer-anchored, #{$fui-overlay-layer-anchored});
   outline: none;
   pointer-events: auto;
+
+  // The popup is absolutely positioned inside the positioner whenever a
+  // Menu.Viewport is present (Base UI anchors it with top/bottom: 0). Without an
+  // explicit box the positioner collapses to zero height and any flipped
+  // (side="top") menu renders a full popup-height away from its trigger.
+  inline-size: var(--positioner-width);
+  block-size: var(--positioner-height);
 }
 
 .popup {
   @include popup.container;
 
-  min-inline-size: var(--fui-menu-min-inline, 192px);
-  margin: 0;
+  min-inline-size: layout.measure("menu-min");
+  margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
   list-style: none;
-  opacity: 1;
-  transform: none;
+  opacity: 0;
+  transform: scale(0.95);
   transform-origin: var(--transform-origin);
+  transition:
+    opacity var(--fui-transition-fast, $fui-transition-fast),
+    transform var(--fui-transition-fast, $fui-transition-fast);
+
+  &[data-open] {
+    opacity: 1;
+    transform: scale(1);
+  }
 
-  &[data-open],
   &[data-starting-style],
   &[data-ending-style] {
-    opacity: 1;
-    transform: none;
+    opacity: 0;
+    transform: scale(0.95);
   }
 }
 
@@ -59,8 +75,8 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  inline-size: var(--fui-popup-indicator-box);
-  block-size: var(--fui-popup-indicator-box);
+  inline-size: var(--fui-popup-indicator-box, var(--fui-raw-space-16, #{measurements.raw-space(16)}));
+  block-size: var(--fui-popup-indicator-box, var(--fui-raw-space-16, #{measurements.raw-space(16)}));
   flex: 0 0 auto;
 }
 
@@ -93,8 +109,8 @@
   color: var(--fui-color-accent, $fui-color-accent);
 
   svg {
-    inline-size: var(--fui-raw-space-12, 12px);
-    block-size: var(--fui-raw-space-12, 12px);
+    inline-size: var(--fui-raw-space-12, #{measurements.raw-space(12)});
+    block-size: var(--fui-raw-space-12, #{measurements.raw-space(12)});
   }
 }
 
@@ -102,8 +118,8 @@
   visibility: hidden;
 
   svg {
-    inline-size: var(--fui-raw-space-12, 12px);
-    block-size: var(--fui-raw-space-12, 12px);
+    inline-size: var(--fui-raw-space-12, #{measurements.raw-space(12)});
+    block-size: var(--fui-raw-space-12, #{measurements.raw-space(12)});
   }
 }
 
@@ -126,8 +142,8 @@
   block-size: 0;
   margin-inline-start: auto;
   border-style: solid;
-  border-width: var(--fui-menu-submenu-caret-block, 4px) 0 var(--fui-menu-submenu-caret-block, 4px)
-    var(--fui-menu-submenu-caret-inline, 6px);
+  border-width: var(--fui-raw-space-4, #{measurements.raw-space(4)}) 0 var(--fui-raw-space-4, #{measurements.raw-space(4)})
+    var(--fui-raw-space-6, #{measurements.raw-space(6)});
   border-color: transparent transparent transparent var(--fui-text-secondary, $fui-text-secondary);
 }