@usefragments/ui 1.3.3 → 1.4.0

package/src/components/Editor/Editor.contract.json

@@ -13,6 +13,23 @@
     "content"
   ],
   "status": "stable",
+  "dependencies": [
+    {
+      "name": "@tiptap/react",
+      "version": ">=2.0.0",
+      "reason": "Optional — enables rich-text mode; without TipTap the editor falls back to a markdown textarea."
+    },
+    {
+      "name": "@tiptap/starter-kit",
+      "version": ">=2.0.0",
+      "reason": "Optional — TipTap extension bundle used by rich-text mode."
+    },
+    {
+      "name": "@tiptap/extension-link",
+      "version": ">=2.0.0",
+      "reason": "Optional — link formatting in rich-text mode."
+    }
+  ],
   "sourcePath": "src/components/Editor/index.tsx",
   "exportName": "Editor",
   "propsSummary": [
@@ -251,7 +268,8 @@
       "Separator",
       "StatusIndicator",
       "Content",
-      "StatusBar"
+      "StatusBar",
+      "preload"
     ]
   },
   "provenance": {

package/src/components/Editor/index.tsx

@@ -27,27 +27,63 @@ let _useEditor: ((config: Record<string, unknown>) => unknown) | null = null;
 let _EditorContent: React.ComponentType<Record<string, unknown>> | null = null;
 let _StarterKit: unknown = null;
 let _LinkExtension: unknown = null;
-let _tiptapLoaded = false;
+let _tiptapLoadPromise: Promise<void> | null = null;
 let _tiptapFailed = false;
 
-function loadTipTapDeps() {
-  if (_tiptapLoaded) return;
-  _tiptapLoaded = true;
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const tiptapReact = require('@tiptap/react');
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const starterKit = require('@tiptap/starter-kit');
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const linkExt = require('@tiptap/extension-link');
-
-    _useEditor = tiptapReact.useEditor;
-    _EditorContent = tiptapReact.EditorContent;
-    _StarterKit = starterKit.default ?? starterKit.StarterKit ?? starterKit;
-    _LinkExtension = linkExt.default ?? linkExt.Link ?? linkExt;
-  } catch {
-    _tiptapFailed = true;
+// Resolved with import() rather than require(): browser ESM bundles have no
+// `require`, so the synchronous shape forced markdown mode even with TipTap installed.
+function loadTipTapDeps(): Promise<void> {
+  if (!_tiptapLoadPromise) {
+    _tiptapLoadPromise = (async () => {
+      try {
+        const [tiptapReact, starterKit, linkExt] = await Promise.all([
+          import('@tiptap/react'),
+          import('@tiptap/starter-kit'),
+          import('@tiptap/extension-link'),
+        ]);
+
+        _useEditor = tiptapReact.useEditor as unknown as (
+          config: Record<string, unknown>,
+        ) => unknown;
+        _EditorContent = tiptapReact.EditorContent as unknown as React.ComponentType<
+          Record<string, unknown>
+        >;
+        _StarterKit =
+          (starterKit as { default?: unknown; StarterKit?: unknown }).default ??
+          (starterKit as { StarterKit?: unknown }).StarterKit ??
+          starterKit;
+        _LinkExtension =
+          (linkExt as { default?: unknown; Link?: unknown }).default ??
+          (linkExt as { Link?: unknown }).Link ??
+          linkExt;
+      } catch {
+        _tiptapFailed = true;
+        if (process.env.NODE_ENV === 'development') {
+          console.warn(
+            '[@usefragments/ui] Editor: TipTap is not installed; falling back to markdown mode. ' +
+            'Install it with: npm install @tiptap/react @tiptap/starter-kit @tiptap/extension-link'
+          );
+        }
+      }
+    })();
   }
+  return _tiptapLoadPromise;
+}
+
+/** Kick off the lazy TipTap load on mount and re-render once it settles. */
+function useTipTapDeps(): boolean {
+  const [, rerender] = React.useReducer((n: number) => n + 1, 0);
+  React.useEffect(() => {
+    if ((_useEditor && _EditorContent && _StarterKit) || _tiptapFailed) return;
+    let active = true;
+    void loadTipTapDeps().then(() => {
+      if (active) rerender();
+    });
+    return () => {
+      active = false;
+    };
+  }, []);
+  return !_tiptapFailed && !!_useEditor && !!_EditorContent && !!_StarterKit;
 }
 
 // ============================================
@@ -376,7 +412,16 @@ function countWords(text: string): number {
 // Components
 // ============================================
 
-function EditorRoot({
+function EditorRoot(props: EditorProps) {
+  const hasTipTap = useTipTapDeps();
+  // The rich implementation calls TipTap's useEditor hook, so an instance's
+  // mode must never change mid-lifetime. Keying by mode remounts the
+  // implementation exactly once, when the lazy TipTap load resolves.
+  return <EditorImpl key={hasTipTap ? 'rich' : 'markdown'} hasTipTap={hasTipTap} {...props} />;
+}
+
+function EditorImpl({
+  hasTipTap,
   children,
   value: controlledValue,
   defaultValue = '',
@@ -394,7 +439,7 @@ function EditorRoot({
   toolbarIcons,
   className,
   ...htmlProps
-}: EditorProps) {
+}: EditorProps & { hasTipTap: boolean }) {
   const contentRef = React.useRef<HTMLTextAreaElement>(null);
 
   const [value, setValue] = useControllableState(
@@ -405,9 +450,6 @@ function EditorRoot({
 
   const [saveStatus, setSaveStatus] = React.useState<EditorSaveStatus>('idle');
 
-  // Try loading TipTap
-  loadTipTapDeps();
-  const hasTipTap = !_tiptapFailed && _useEditor && _EditorContent && _StarterKit;
   const mode: EditorMode = hasTipTap ? 'rich' : 'markdown';
 
   // TipTap editor instance (only when available)
@@ -843,6 +885,8 @@ function EditorStatusBar({ showWordCount = true, showCharCount = true, className
 // ============================================
 
 export const Editor = Object.assign(EditorRoot, {
+  /** Start resolving TipTap before first render (optional). */
+  preload: loadTipTapDeps,
   Toolbar: EditorToolbar,
   ToolbarGroup: EditorToolbarGroup,
   ToolbarButton: EditorToolbarButton,

package/src/components/Listbox/Listbox.module.scss

@@ -9,19 +9,11 @@
   @include surface-elevated;
   @include popup-container;
 
-  // Item height derived from text-base font + vertical padding (matches Select/Combobox)
-  --_listbox-item-h: calc(
-    var(--fui-font-size-sm, #{$fui-font-size-sm}) *
-      var(--fui-line-height-normal, #{$fui-line-height-normal}) +
-      var(--fui-space-2, #{$fui-space-2}) * 2
-  );
+  @include popup-scroll-viewport;
 
   min-width: 12rem;
-  // Show N items + half-peek scroll hint (default 4.5 items)
-  max-height: calc(
-    var(--_listbox-item-h) * var(--fui-select-max-items, 4.5) +
-      var(--fui-space-1, #{$fui-space-1}) * 2
-  );
+  // Show N items + half-peek scroll hint (default 4.5 items).
+  max-height: var(--_popup-scroll-max-h);
   overflow-y: auto;
   border-color: var(--fui-form-group-border, $fui-border);
 

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

@@ -12,6 +12,18 @@
     "chat"
   ],
   "status": "stable",
+  "dependencies": [
+    {
+      "name": "react-markdown",
+      "version": ">=9.0.0",
+      "reason": "Optional — parses markdown; without it content renders as plain paragraphs."
+    },
+    {
+      "name": "remark-gfm",
+      "version": ">=4.0.0",
+      "reason": "Optional — adds GitHub-flavored markdown (tables, strikethrough, task lists)."
+    }
+  ],
   "sourcePath": "src/components/Markdown/index.tsx",
   "exportName": "Markdown",
   "propsSummary": [
@@ -52,6 +64,7 @@
       "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"
     ],
@@ -115,7 +128,8 @@
   "ai": {
     "compositionPattern": "compound",
     "subComponents": [
-      "Root"
+      "Root",
+      "preload"
     ]
   },
   "provenance": {

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

@@ -8,10 +8,27 @@
 .markdown {
   @include text-base;
   word-wrap: break-word;
-  color: var(--fui-text-secondary, $fui-text-secondary);
+  // 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
   // ----------------------------------------

package/src/components/Markdown/index.tsx

@@ -31,26 +31,45 @@ type ReactMarkdownType = React.ComponentType<{
 
 let ReactMarkdown: ReactMarkdownType | null = null;
 let remarkGfm: unknown = null;
-let loadAttempted = false;
+let loadPromise: Promise<void> | null = null;
 let loadFailed = false;
 
-function loadDeps() {
-  if (loadAttempted) return;
-  loadAttempted = true;
-
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    ReactMarkdown = require('react-markdown').default || require('react-markdown');
-  } catch {
-    loadFailed = true;
-  }
+/**
+ * Resolve react-markdown, once per page.
+ *
+ * `import()` rather than `require()`: this component is bundled into browser
+ * apps, where `require` is not defined, so a synchronous require throws a
+ * ReferenceError that this function's own catch would swallow — turning every
+ * render into the plain-text fallback with no way to tell that from a genuinely
+ * missing dependency. The same lazy-ESM shape as CodeBlock's shiki loader.
+ */
+function loadDeps(): Promise<void> {
+  if (!loadPromise) {
+    loadPromise = (async () => {
+      try {
+        const mod = await import('react-markdown');
+        ReactMarkdown = ((mod as { default?: ReactMarkdownType }).default ??
+          mod) as ReactMarkdownType;
+      } catch {
+        loadFailed = true;
+        if (process.env.NODE_ENV === 'development') {
+          console.warn(
+            '[@usefragments/ui] Markdown: react-markdown is not installed. ' +
+            'Install it with: npm install react-markdown remark-gfm'
+          );
+        }
+        return;
+      }
 
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    remarkGfm = require('remark-gfm').default || require('remark-gfm');
-  } catch {
-    // remark-gfm is optional; markdown still works without it
+      try {
+        const mod = await import('remark-gfm');
+        remarkGfm = (mod as { default?: unknown }).default ?? mod;
+      } catch {
+        // remark-gfm is optional; markdown still works without it
+      }
+    })();
   }
+  return loadPromise;
 }
 
 // ============================================
@@ -74,17 +93,26 @@ function FallbackRenderer({ content }: { content: string }) {
 
 const MarkdownRoot = React.forwardRef<HTMLDivElement, MarkdownProps>(
   function Markdown({ content, components: componentOverrides, className, ...htmlProps }, ref) {
-    loadDeps();
+    // 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 (loadFailed || !ReactMarkdown) {
-      if (loadFailed && process.env.NODE_ENV === 'development') {
-        console.warn(
-          '[@usefragments/ui] Markdown: react-markdown is not installed. ' +
-          'Install it with: npm install react-markdown remark-gfm'
-        );
-      }
+    if (!ReactMarkdown) {
       return (
         <div ref={ref} {...htmlProps} className={classes}>
           <FallbackRenderer content={content} />
@@ -109,4 +137,10 @@ const MarkdownRoot = React.forwardRef<HTMLDivElement, MarkdownProps>(
 
 export const Markdown = Object.assign(MarkdownRoot, {
   Root: MarkdownRoot,
+  /**
+   * Start resolving the markdown parser before anything renders. Optional —
+   * for apps that know prose is imminent (a chat transcript, a docs route) and
+   * would rather not show the plain-text fallback for a frame.
+   */
+  preload: loadDeps,
 });

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

@@ -100,14 +100,24 @@ $fui-arrow-size: 10px !default;
 }
 
 // Check indicator (checkmark icon for checked items)
+//
+// Sized to the text it sits beside rather than to a 16px icon slot. Every item
+// in a checkable menu reserves this column so labels stay aligned whether or not
+// they are checked — which means its width is pure indent on every unchecked
+// row, and at 1rem against 12px text it read as a margin rather than a marker.
 .checkIndicator {
   display: flex;
   align-items: center;
   justify-content: center;
-  width: 1rem;
-  height: 1rem;
+  width: 0.75rem;
+  height: 0.75rem;
   flex-shrink: 0;
   color: var(--fui-color-accent, $fui-color-accent);
+
+  svg {
+    width: 100%;
+    height: 100%;
+  }
 }
 
 // Checkbox item

package/src/components/Message/Message.contract.json

@@ -80,6 +80,9 @@
     "guidelines": [
       "Always provide a role prop to determine styling",
       "Use status prop to show message state (sending, streaming, error)",
+      "Pass avatar={null}, or set showAvatars={false} on the parent ConversationList, to hide avatars; avatarless assistant content is flush while the user's own bubble keeps compact space-1/space-2 padding",
+      "User message bubbles are capped at 80% of the available inline measure so they remain visually distinct from assistant responses",
+      "User and assistant message chrome uses neutral surface tokens with the primary text foreground; reserve brand accent for actions or semantic state",
       "Consider showing timestamps for longer conversations",
       "Provide hover actions for assistant messages (copy, regenerate)"
     ],

package/src/components/Message/Message.module.scss

@@ -25,6 +25,25 @@
   }
 }
 
+.withoutAvatar {
+  padding-inline: 0;
+
+  // Avatarless assistant prose is part of the transcript rather than a bubble,
+  // so it should sit flush with the shared measure. The user's own turn remains
+  // a compact bubble to preserve authorship and alignment at a glance.
+  &.assistant {
+    .content {
+      padding: 0;
+    }
+  }
+
+  &.user {
+    .content {
+      padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $fui-space-2);
+    }
+  }
+}
+
 // Role-based styles
 .user {
   flex-direction: row-reverse;
@@ -34,9 +53,13 @@
     align-items: flex-end;
   }
 
+  // Alignment, measure and the neutral surface distinguish the user's turn.
+  // Brand accent is reserved for actions and semantic state, not transcript
+  // chrome.
   .content {
-    background-color: var(--fui-color-accent, $fui-color-accent);
-    color: var(--fui-color-on-accent, $fui-color-on-accent);
+    max-inline-size: 80%;
+    background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+    color: var(--fui-text-primary, $fui-text-primary);
   }
 }
 
@@ -98,8 +121,8 @@
 }
 
 .avatarUser {
-  background-color: var(--fui-color-accent, $fui-color-accent);
-  color: var(--fui-color-on-accent, $fui-color-on-accent);
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  color: var(--fui-text-primary, $fui-text-primary);
 }
 
 .avatarAssistant {
@@ -146,6 +169,12 @@
   line-height: var(--fui-line-height-normal, $fui-line-height-normal);
   word-wrap: break-word;
 
+  // A bubble sets its own foreground per role — primary text for the user, the
+  // danger ramp for an error. Anything rendered inside it has to take that
+  // colour rather than the page's, so a Markdown body dropped in here inherits
+  // instead of holding on to the prose grey.
+  --fui-markdown-text: currentColor;
+
   // Prose styling for markdown content
   p {
     margin: 0;

package/src/components/Message/index.tsx

@@ -2,6 +2,7 @@
 
 import * as React from 'react';
 import styles from './Message.module.scss';
+import { useOptionalConversationList } from '../ConversationList';
 import { Markdown } from '../Markdown';
 
 // ============================================
@@ -239,6 +240,10 @@ function MessageRoot({
   className,
   ...htmlProps
 }: MessageProps) {
+  const conversationList = useOptionalConversationList();
+  const showAvatar = conversationList?.showAvatars !== false
+    && avatar !== null
+    && avatar !== false;
   const contextValue: MessageContextValue = {
     role,
     status,
@@ -250,6 +255,7 @@ function MessageRoot({
     styles[role],
     status === 'error' && styles.error,
     status === 'sending' && styles.sending,
+    !showAvatar && styles.withoutAvatar,
     className,
   ].filter(Boolean).join(' ');
 
@@ -261,7 +267,7 @@ function MessageRoot({
         data-role={role}
         data-status={status}
       >
-        {avatar !== undefined ? avatar : <MessageAvatar />}
+        {showAvatar && (avatar !== undefined ? avatar : <MessageAvatar />)}
         <div className={styles.body}>
           {children}
           {actions && <MessageActions>{actions}</MessageActions>}

package/src/components/Pagination/Pagination.contract.json

@@ -79,6 +79,7 @@
       "Use edgeCount to always show first/last pages",
       "Use siblingCount to control how many pages surround the current page",
       "Pair with Table component for data table pagination",
+      "Keep page labels on the body foreground; the current page uses a neutral active surface rather than brand accent",
       "Pagination forwards standard nav props (id, aria-*, data-*, event handlers) to the root <nav>",
       "Previous/Next/Item buttons compose your onClick handlers; call event.preventDefault() to stop the page change"
     ],

package/src/components/Pagination/Pagination.module.scss

@@ -58,11 +58,12 @@
 
 // Active page
 .itemActive {
-  background-color: var(--fui-color-accent, $fui-color-accent);
-  color: var(--fui-color-on-accent, $fui-color-on-accent);
+  background-color: var(--fui-bg-active, $fui-bg-active);
+  color: var(--fui-text-primary, $fui-text-primary);
+  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
 
   &:hover:not(:disabled) {
-    background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+    background-color: var(--fui-bg-active, $fui-bg-active);
   }
 }
 
@@ -105,7 +106,7 @@
 
 @media (prefers-contrast: more) {
   .itemActive {
-    outline: 2px solid var(--fui-color-accent, $fui-color-accent);
+    outline: 2px solid var(--fui-text-primary, $fui-text-primary);
     outline-offset: -2px;
   }
 }

package/src/components/Prompt/Prompt.contract.json

@@ -27,7 +27,10 @@
     "maxRows: number (default: 8)",
     "autoResize: boolean (default: true)",
     "submitOnEnter: boolean (default: true)",
-    "variant: default|fixed|sticky (default: default)"
+    "variant: default|fixed|sticky (default: default)",
+    "appearance: panel|seamless (default: panel)",
+    "onFiles: function",
+    "accept: string"
   ],
   "props": {
     "children": {
@@ -108,6 +111,26 @@
         "fixed",
         "sticky"
       ]
+    },
+    "onFiles": {
+      "type": "function",
+      "description": "Called with files added by the attach button, a paste, or a drop anywhere on the card. Providing it enables all three.",
+      "required": false
+    },
+    "accept": {
+      "type": "string",
+      "description": "accept filter for the attach button's picker, e.g. \"image/*\"",
+      "required": false
+    },
+    "appearance": {
+      "type": "enum",
+      "description": "How the card is divided up. \"panel\" keeps the toolbar as a filled footer under a rule; \"seamless\" makes the whole card one writing surface with the controls floating on it.",
+      "default": "panel",
+      "required": false,
+      "values": [
+        "panel",
+        "seamless"
+      ]
     }
   },
   "usage": {
@@ -126,6 +149,14 @@
       "Use loading state during API calls",
       "Prompt.Textarea forwards native textarea props (autoComplete, inputMode, aria-*, data-*, handlers)",
       "Prompt.Textarea composes your onChange/onKeyDown handlers with built-in submit and auto-resize behavior",
+      "Use appearance=\"seamless\" for agent composers where the controls should float on the writing surface rather than sit in a footer",
+      "Seamless controls share the dense 32px token scale with body-sized labels and standard glyphs so mixed Prompt.Select, Prompt.Attach and Prompt.Submit rows remain optically aligned",
+      "Seamless secondary controls keep transparent hover and open states so they read as inline tools; only Prompt.Submit carries a persistent filled shape",
+      "Seamless Prompt.Submit mirrors the trailing ink gutter established by Prompt.Attach at the leading edge",
+      "Prompt.Submit uses a neutral inverse surface by default so the primary action stays visible without consuming semantic brand color",
+      "Use Prompt.ModeButton for a setting you toggle and Prompt.Select for one you pick from a list",
+      "Wire onFiles once: the attach button, pasting a screenshot and dropping on the card all go through it",
+      "Render Prompt.Attachments above Prompt.Textarea — attachments are part of the message, not a setting on it",
       "Consider showing usage/token limits for AI contexts"
     ],
     "accessibility": [
@@ -150,6 +181,11 @@
       "description": "Shows token usage indicator",
       "code": "<Prompt onSubmit={(value) => console.log(value)}>\n  <Prompt.Textarea />\n  <Prompt.Toolbar>\n    <Prompt.Actions>\n      <Prompt.ActionButton aria-label=\"Add attachment\">\n        +\n      </Prompt.ActionButton>\n      <Prompt.ModeButton active>Auto</Prompt.ModeButton>\n    </Prompt.Actions>\n    <Prompt.Info>\n      <Prompt.Usage>52% used</Prompt.Usage>\n      <Prompt.Submit />\n    </Prompt.Info>\n  </Prompt.Toolbar>\n</Prompt>"
     },
+    {
+      "name": "Agent Composer",
+      "description": "Seamless surface with the scope of the run chosen on the toolbar",
+      "code": "<Prompt\n  appearance=\"seamless\"\n  submitOnEnter={false}\n  minRows={3}\n  onSubmit={(value) => console.log(value)}\n>\n  <Prompt.Textarea placeholder=\"What should be true when this is done?\" />\n  <Prompt.Toolbar>\n    <Prompt.Actions>\n      <Prompt.Select\n        aria-label=\"Model\"\n        defaultValue=\"claude-opus-4-8\"\n        options={[{ value: 'claude-opus-4-8', label: 'Opus 4.8' }, { value: 'claude-sonnet-5', label: 'Sonnet 5' }]}\n      />\n      <Prompt.ModeButton>Plan</Prompt.ModeButton>\n    </Prompt.Actions>\n    <Prompt.Info>\n      <Prompt.Submit />\n    </Prompt.Info>\n  </Prompt.Toolbar>\n</Prompt>"
+    },
     {
       "name": "Loading State",
       "description": "During API submission",
@@ -200,6 +236,9 @@
       "Info",
       "ActionButton",
       "ModeButton",
+      "Select",
+      "Attach",
+      "Attachments",
       "Usage",
       "Submit"
     ]