@usefragments/ui 1.3.2 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefragments/ui",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "license": "MIT",
   "description": "Customizable UI components built on Base UI headless primitives",
   "author": "Conan McNicholl",
@@ -241,7 +241,7 @@
     "vite": "^6.0.0",
     "vitest": "^2.1.8",
     "vitest-axe": "^0.1.0",
-    "@usefragments/core": "1.4.0"
+    "@usefragments/core": "1.7.1"
   },
   "files": [
     "src",

package/src/components/Badge/Badge.contract.json

@@ -9,10 +9,13 @@
   "exportName": "Badge",
   "propsSummary": [
     "children: node (required)",
-    "variant: default|success|warning|error|info|outline (default: default)",
+    "variant: default|success|warning|error|info|outline|label|dim (default: default)",
     "size: sm|md|lg (default: md)",
     "dot: boolean (default: false)",
+    "dotPulse: boolean (default: false)",
+    "dotColor: string",
     "icon: node",
+    "active: boolean (default: false)",
     "onRemove: function",
     "announce: boolean (default: false)",
     "role: union"
@@ -25,10 +28,10 @@
     },
     "variant": {
       "type": "enum",
-      "description": "Visual style indicating severity or category",
+      "description": "Visual style indicating severity or category. `label` is a hairline-bordered metadata pill (pair with dotColor); `dim` is transparent filter-pill chrome (pair with active).",
       "default": "default",
       "required": false,
-      "values": ["default", "success", "warning", "error", "info", "outline"]
+      "values": ["default", "success", "warning", "error", "info", "outline", "label", "dim"]
     },
     "size": {
       "type": "enum",
@@ -43,11 +46,28 @@
       "default": "false",
       "required": false
     },
+    "dotPulse": {
+      "type": "boolean",
+      "description": "Breathe the status dot, for a state that is still happening rather than one that has settled. Opacity only, and honours prefers-reduced-motion",
+      "default": "false",
+      "required": false
+    },
+    "dotColor": {
+      "type": "string",
+      "description": "Color for the leading status dot. Applies to variant=\"label\" (and the generic dot prop). Accepts any CSS color including CSS custom properties.",
+      "required": false
+    },
     "icon": {
       "type": "node",
       "description": "Optional icon element before the text",
       "required": false
     },
+    "active": {
+      "type": "boolean",
+      "description": "Marks variant=\"dim\" as the currently selected filter. Has no effect on other variants.",
+      "default": "false",
+      "required": false
+    },
     "onRemove": {
       "type": "function",
       "description": "Makes the badge removable. Called when X is clicked.",
@@ -149,9 +169,12 @@
   "contract": {
     "propsSummary": [
       "children: ReactNode - badge label (required)",
-      "variant: default|success|warning|error|info|outline - visual style",
-      "size: sm|md - badge size",
+      "variant: default|success|warning|error|info|outline|label|dim - visual style",
+      "size: sm|md|lg - badge size",
       "dot: boolean - show status dot indicator",
+      "dotPulse: boolean - breathe the dot for an in-progress state (respects prefers-reduced-motion)",
+      "dotColor: string - color for the leading status dot",
+      "active: boolean - marks variant=\"dim\" as the selected filter",
       "onRemove: () => void - makes badge removable",
       "announce: boolean - opt into role=\"status\" + auto status aria-label"
     ],

package/src/components/Badge/Badge.module.scss

@@ -116,6 +116,27 @@ $fui-badge-dot-md: 6px !default;
   }
 }
 
+// "Still happening", as distinct from "is in this state". A live badge and a
+// settled one are otherwise the same object, and the difference between them is
+// the one thing a status board is scanned for — so it is carried by the only
+// motion the component has. Opacity only: nothing reflows, and a reader who has
+// asked for less motion loses the breathing and keeps the badge.
+.dotPulse {
+  animation: fui-badge-dot-pulse 1.6s ease-in-out infinite;
+}
+
+@keyframes fui-badge-dot-pulse {
+  50% {
+    opacity: 0.35;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .dotPulse {
+    animation: none;
+  }
+}
+
 .icon {
   display: flex;
   align-items: center;

package/src/components/Badge/index.tsx

@@ -26,6 +26,9 @@ export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
   size?: "sm" | "md" | "lg";
   /** Show a status dot before the label */
   dot?: boolean;
+  /** Breathe the status dot, for a state that is still happening rather than
+   * one that has settled. Respects `prefers-reduced-motion`. */
+  dotPulse?: boolean;
   /** Color for the leading status dot. Applies to `variant="label"` (and the
    * generic `dot` prop). Accepts any CSS color including CSS custom properties. */
   dotColor?: string;
@@ -47,6 +50,7 @@ const BadgeRoot = React.forwardRef<HTMLSpanElement, BadgeProps>(function Badge(
     variant = "default",
     size = "md",
     dot = false,
+    dotPulse = false,
     dotColor,
     icon,
     active = false,
@@ -90,7 +94,12 @@ const BadgeRoot = React.forwardRef<HTMLSpanElement, BadgeProps>(function Badge(
       role={role ?? (announce ? "status" : undefined)}
       aria-label={effectiveAriaLabel}
     >
-      {dot && <span className={styles.dot} aria-hidden="true" />}
+      {dot && (
+        <span
+          className={[styles.dot, dotPulse && styles.dotPulse].filter(Boolean).join(" ")}
+          aria-hidden="true"
+        />
+      )}
       {icon && (
         <span className={styles.icon} aria-hidden="true">
           {icon}

package/src/components/Button/Button.contract.json

@@ -15,7 +15,7 @@
   "propsSummary": [
     "as: button|a",
     "children: node (required)",
-    "variant: primary|secondary|ghost|link|danger|outlined|outline|icon (default: \"primary\")",
+    "variant: primary|secondary|ghost|link|quiet|danger|outlined|outline|icon (default: \"primary\")",
     "size: xs|sm|md|lg (default: \"md\")",
     "icon: boolean",
     "fullWidth: boolean",
@@ -39,7 +39,7 @@
     },
     "variant": {
       "type": "enum",
-      "description": "Visual style variant (\"icon\" is a convenience alias for outlined + icon-only layout, \"link\" is accent-coloured + transparent for tertiary CTAs)",
+      "description": "Visual style variant (\"icon\" is a convenience alias for outlined + icon-only layout, \"link\" is accent-coloured + transparent for tertiary CTAs, \"quiet\" is a neutral text button with no box and no height floor for meta lines and footnotes)",
       "default": "\"primary\"",
       "required": false,
       "values": [
@@ -47,6 +47,7 @@
         "secondary",
         "ghost",
         "link",
+        "quiet",
         "danger",
         "outlined",
         "outline",
@@ -134,6 +135,11 @@
       "description": "Accent-coloured transparent button for tertiary CTAs",
       "code": "<Button variant=\"link\">View all →</Button>"
     },
+    {
+      "name": "Quiet",
+      "description": "Neutral text button with no box and no height floor, for meta lines and footnotes",
+      "code": "<Button variant=\"quiet\" size=\"xs\">main</Button>"
+    },
     {
       "name": "Danger",
       "description": "Destructive action requiring attention",
@@ -184,7 +190,7 @@
   ],
   "contract": {
     "propsSummary": [
-      "variant: primary|secondary|ghost|link|danger|outlined|outline|icon (default: primary, icon = outlined + icon-only, link = accent transparent)",
+      "variant: primary|secondary|ghost|link|quiet|danger|outlined|outline|icon (default: primary, icon = outlined + icon-only, link = accent transparent, quiet = neutral text button, no box)",
       "size: xs|sm|md|lg (default: md, xs for inline row-action controls)",
       "disabled: boolean - disables interaction",
       "type: button|submit|reset (default: button)",

package/src/components/Button/Button.module.scss

@@ -180,6 +180,40 @@
   --_button-shadow-active: none;
 }
 
+// Quiet: a button that reads as text. The neutral sibling of `link` — nothing
+// but the foreground changes on hover, because in a meta line, a breadcrumb or
+// a footnote a box would be the loudest thing on the row for the least
+// important one. It is also the one variant that drops the interactive height
+// floor: there is no box to hold open, so it sits on the line it is in and
+// takes its hit target from the text and the row's own padding. That makes it
+// the wrong choice for a standalone action — reach for `ghost` there.
+.quiet {
+  --_button-bg: transparent;
+  --_button-bg-hover: transparent;
+  --_button-bg-active: transparent;
+  --_button-border: transparent;
+  --_button-border-hover: transparent;
+  --_button-color: var(--fui-text-tertiary, #{$fui-text-tertiary});
+  --_button-shadow: none;
+  --_button-shadow-hover: none;
+  --_button-shadow-active: none;
+
+  min-height: 0;
+  padding: 0;
+  font-weight: var(--fui-font-weight-normal, $fui-font-weight-normal);
+
+  // Only the custom property is restated: `color` reads it on .button, so the
+  // foreground follows without a second `color` declaration to keep in step.
+  &:hover:not(:disabled):not([data-disabled]) {
+    --_button-color: var(--fui-text-secondary, #{$fui-text-secondary});
+  }
+
+  &:active:not(:disabled):not([data-disabled]),
+  &[data-pressed] {
+    --_button-color: var(--fui-text-primary, #{$fui-text-primary});
+  }
+}
+
 .danger {
   // Flat danger fill — no gradient. Hover/active darken the solid colour.
   --_button-bg: var(--fui-color-danger, #{$fui-color-danger});

package/src/components/Button/index.tsx

@@ -29,9 +29,19 @@ type ButtonBaseProps = {
    * @see https://usefragments.com/components/button#variants
    * @remarks
    * - `"link"` — accent-coloured, transparent; for tertiary CTAs like "View all →"
+   * - `"quiet"` — neutral text button with no box and no height floor; for meta lines and footnotes
    * - `"icon"` — convenience alias for outlined + icon-only layout
    * - `"outline"` — alias for `"outlined"` */
-  variant?: "primary" | "secondary" | "ghost" | "link" | "danger" | "outlined" | "outline" | "icon";
+  variant?:
+    | "primary"
+    | "secondary"
+    | "ghost"
+    | "link"
+    | "quiet"
+    | "danger"
+    | "outlined"
+    | "outline"
+    | "icon";
   /** Button size. `"xs"` is for inline row-action controls (accept/dismiss, table-row icons) where `"sm"` is too tall.
    * @default "md"
    * @see https://usefragments.com/components/button#sizes */

package/src/components/Chart/Chart.contract.json

@@ -10,6 +10,13 @@
     "recharts"
   ],
   "status": "stable",
+  "dependencies": [
+    {
+      "name": "recharts",
+      "version": ">=2.0.0 || >=3.0.0",
+      "reason": "Optional — powers Chart.Tooltip and Chart.Legend; both render nothing until it is installed."
+    }
+  ],
   "sourcePath": "src/components/Chart/index.tsx",
   "exportName": "ChartContainer",
   "propsSummary": [

package/src/components/Chart/index.tsx

@@ -60,20 +60,46 @@ type RechartsLegendProps = Record<string, unknown>;
 
 let _RechartsTooltip: React.ComponentType<Record<string, unknown>> | null = null;
 let _RechartsLegend: React.ComponentType<Record<string, unknown>> | null = null;
-let _chartLoaded = false;
+let _chartLoadPromise: Promise<void> | null = null;
 let _chartFailed = false;
 
-function loadChartDeps() {
-  if (_chartLoaded) return;
-  _chartLoaded = true;
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const rc = require('recharts');
-    _RechartsTooltip = rc.Tooltip as React.ComponentType<Record<string, unknown>>;
-    _RechartsLegend = rc.Legend as React.ComponentType<Record<string, unknown>>;
-  } catch {
-    _chartFailed = true;
+// Resolved with import() rather than require(): browser ESM bundles have no
+// `require`, so the synchronous shape disabled recharts even when installed.
+function loadChartDeps(): Promise<void> {
+  if (!_chartLoadPromise) {
+    _chartLoadPromise = (async () => {
+      try {
+        const rc = await import('recharts');
+        _RechartsTooltip = rc.Tooltip as unknown as React.ComponentType<Record<string, unknown>>;
+        _RechartsLegend = rc.Legend as unknown as React.ComponentType<Record<string, unknown>>;
+      } catch {
+        _chartFailed = true;
+        if (process.env.NODE_ENV === 'development') {
+          console.warn(
+            '[@usefragments/ui] Chart: recharts is not installed. ' +
+            'Install it with: npm install recharts'
+          );
+        }
+      }
+    })();
   }
+  return _chartLoadPromise;
+}
+
+/** Kick off the lazy recharts load on mount and re-render once it settles. */
+function useChartDeps(): boolean {
+  const [, rerender] = React.useReducer((n: number) => n + 1, 0);
+  React.useEffect(() => {
+    if (_RechartsTooltip || _chartFailed) return;
+    let active = true;
+    void loadChartDeps().then(() => {
+      if (active) rerender();
+    });
+    return () => {
+      active = false;
+    };
+  }, []);
+  return _RechartsTooltip !== null;
 }
 
 
@@ -252,7 +278,7 @@ export function ChartTooltip({
   content,
   ...props
 }: ChartTooltipProps) {
-  loadChartDeps();
+  const chartReady = useChartDeps();
 
   const defaultContent = React.useCallback(
 
@@ -269,13 +295,8 @@ export function ChartTooltip({
     [indicator, hideLabel, hideIndicator, labelFormatter, valueFormatter],
   );
 
-  if (_chartFailed || !_RechartsTooltip) {
-    if (_chartFailed && process.env.NODE_ENV === 'development') {
-      console.warn(
-        '[@usefragments/ui] Chart: recharts is not installed. ' +
-        'Install it with: npm install recharts'
-      );
-    }
+  // Nothing until recharts resolves; nothing at all if it is not installed.
+  if (!chartReady || !_RechartsTooltip) {
     return null;
   }
 
@@ -330,19 +351,13 @@ type ChartLegendProps = RechartsLegendProps & {
 };
 
 export function ChartLegend({ content, ...props }: ChartLegendProps) {
-  loadChartDeps();
+  const chartReady = useChartDeps();
 
   const defaultContent = (legendProps: Record<string, unknown>) => (
     <ChartLegendContent {...(legendProps as ChartLegendContentProps)} />
   );
 
-  if (_chartFailed || !_RechartsLegend) {
-    if (_chartFailed && process.env.NODE_ENV === 'development') {
-      console.warn(
-        '[@usefragments/ui] Chart: recharts is not installed. ' +
-        'Install it with: npm install recharts'
-      );
-    }
+  if (!chartReady || !_RechartsLegend) {
     return null;
   }
 
@@ -362,4 +377,6 @@ export const Chart = Object.assign(ChartContainer, {
   TooltipContent: ChartTooltipContent,
   Legend: ChartLegend,
   LegendContent: ChartLegendContent,
+  /** Start resolving recharts before first render (optional). */
+  preload: loadChartDeps,
 });

package/src/components/CodeBlock/CodeBlock.contract.json

@@ -12,6 +12,13 @@
     "diff"
   ],
   "status": "stable",
+  "dependencies": [
+    {
+      "name": "shiki",
+      "version": ">=1.0.0",
+      "reason": "Optional — provides syntax highlighting; without it code renders unhighlighted."
+    }
+  ],
   "sourcePath": "src/components/CodeBlock/index.tsx",
   "exportName": "CodeBlock",
   "propsSummary": [

package/src/components/CodeBlock/CodeBlock.module.scss

@@ -318,9 +318,14 @@ $fui-code-scrollbar-thumb-hover: rgba(255, 255, 255, 0.2) !default;
     word-break: break-word;
   }
 
+  // `display: block` here would double-space every wrapped block: shiki emits a
+  // newline between each `.line`, and under `pre-wrap` that newline becomes a
+  // line box of its own the moment the lines stop being inline. The base rule's
+  // `inline-block` keeps it in the inline flow, and a full-width inline-block
+  // still wraps and still grows taller, which is all this variant needs.
   :global(.line) {
-    display: block;
-    width: auto;
+    display: inline-block;
+    width: 100%;
   }
 }
 

package/src/components/CodeBlock/index.tsx

@@ -249,24 +249,56 @@ function dedent(str: string): string {
   return lines.map((line) => line.slice(minIndent)).join("\n");
 }
 
+/**
+ * Languages where leading whitespace carries meaning, so the first line has to
+ * take part in the common-indent calculation like any other.
+ */
+const INDENTATION_SIGNIFICANT_LANGUAGES = new Set<CodeBlockLanguage>([
+  "yaml",
+  "yml",
+  "json",
+  "python",
+  "py",
+]);
+
 /**
  * Normalize indentation while handling JSX where first line is already at column 0.
+ *
+ * The JSX case this exists for is a snippet authored inline, where the body
+ * carries the source file's indentation but the opening tag does not:
+ *
+ *     code={`<Card>
+ *           <Card.Header>Title</Card.Header>
+ *         </Card>`}
+ *
+ * Excluding line 0 from the minimum is what renders that correctly. But
+ * `normalizeCode` trims first, so line 0 has always had its indentation removed
+ * by the time we get here — which means the same rule strips one real level off
+ * any snippet with a single root and an indented body:
+ *
+ *     job:              job:
+ *       image: node  →  image: node   (now a sibling key, not a child)
+ *
+ * For YAML, JSON and Python that is not cosmetic: the rendered snippet is
+ * invalid, and copying it gives you a broken file. Those languages count line 0,
+ * which is plain dedent. Everything else keeps the JSX-friendly heuristic.
  */
-function normalizeIndentation(str: string): string {
+function normalizeIndentation(str: string, language: CodeBlockLanguage): string {
   const lines = str.split("\n");
   if (lines.length <= 1) return str;
 
+  const firstLineCounts = INDENTATION_SIGNIFICANT_LANGUAGES.has(language);
   let minIndent = Infinity;
   const firstLineIndent = lines[0].match(/^(\s*)/)?.[1].length ?? 0;
 
-  for (let i = 1; i < lines.length; i += 1) {
+  for (let i = firstLineCounts ? 0 : 1; i < lines.length; i += 1) {
     const line = lines[i];
     if (line.trim().length === 0) continue;
     const indent = line.match(/^(\s*)/)?.[1].length ?? 0;
     minIndent = Math.min(minIndent, indent);
   }
 
-  if (firstLineIndent > 0) {
+  if (!firstLineCounts && firstLineIndent > 0) {
     minIndent = Math.min(minIndent, firstLineIndent);
   }
 
@@ -431,11 +463,11 @@ function formatLongJsxTags(code: string): string {
     .join("\n");
 }
 
-function normalizeCode(code: string): string {
+function normalizeCode(code: string, language: CodeBlockLanguage): string {
   const trimmed = code.trim();
   if (trimmed.length === 0) return "";
 
-  const normalized = normalizeIndentation(trimmed);
+  const normalized = normalizeIndentation(trimmed, language);
   const dedented = dedent(normalized);
   const withoutTrailingWhitespace = trimTrailingWhitespace(dedented);
   return formatLongJsxTags(withoutTrailingWhitespace);
@@ -562,7 +594,7 @@ const CodeBlockBase = React.forwardRef<HTMLDivElement, CodeBlockProps>(function
   const [highlight, setHighlight] = useState<{ html: string; loading: boolean }>({ html: '', loading: true });
   const [isCollapsed, setIsCollapsed] = useState(defaultCollapsed);
 
-  const trimmedCode = useMemo(() => normalizeCode(code), [code]);
+  const trimmedCode = useMemo(() => normalizeCode(code, language), [code, language]);
   const codeLines = trimmedCode.split("\n");
   const totalLines = codeLines.length;
   const shouldShowCollapse = collapsible && totalLines > collapsedLines;

package/src/components/ColorPicker/ColorPicker.contract.json

@@ -12,6 +12,13 @@
     "theme"
   ],
   "status": "stable",
+  "dependencies": [
+    {
+      "name": "react-colorful",
+      "version": ">=5.0.0",
+      "reason": "Optional — renders the visual picker surface; the swatch and hex input work without it."
+    }
+  ],
   "sourcePath": "src/components/ColorPicker/index.tsx",
   "exportName": "ColorPicker",
   "propsSummary": [
@@ -200,7 +207,8 @@
   "ai": {
     "compositionPattern": "compound",
     "subComponents": [
-      "Root"
+      "Root",
+      "preload"
     ]
   },
   "provenance": {

package/src/components/ColorPicker/index.tsx

@@ -7,20 +7,48 @@ import { Popover as BasePopover } from "@base-ui/react/popover";
 // Lazy-loaded dependency (react-colorful)
 // ============================================
 
-let _HexColorPicker: any = null;
-let _colorfulLoaded = false;
+let _HexColorPicker: React.ComponentType<{
+  color: string;
+  onChange: (color: string) => void;
+}> | null = null;
+let _colorfulLoadPromise: Promise<void> | null = null;
 let _colorfulFailed = false;
 
-function loadColorfulDeps() {
-  if (_colorfulLoaded) return;
-  _colorfulLoaded = true;
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const rc = require("react-colorful");
-    _HexColorPicker = rc.HexColorPicker;
-  } catch {
-    _colorfulFailed = true;
+// Resolved with import() rather than require(): browser ESM bundles have no
+// `require`, so the synchronous shape hid the picker even when installed.
+function loadColorfulDeps(): Promise<void> {
+  if (!_colorfulLoadPromise) {
+    _colorfulLoadPromise = (async () => {
+      try {
+        const rc = await import("react-colorful");
+        _HexColorPicker = rc.HexColorPicker;
+      } catch {
+        _colorfulFailed = true;
+        if (process.env.NODE_ENV === "development") {
+          console.warn(
+            "[@usefragments/ui] ColorPicker: react-colorful is not installed. " +
+              "Install it with: npm install react-colorful"
+          );
+        }
+      }
+    })();
   }
+  return _colorfulLoadPromise;
+}
+
+/** Kick off the lazy react-colorful load on mount and re-render once it settles. */
+function useColorfulDeps(): void {
+  const [, rerender] = React.useReducer((n: number) => n + 1, 0);
+  React.useEffect(() => {
+    if (_HexColorPicker || _colorfulFailed) return;
+    let active = true;
+    void loadColorfulDeps().then(() => {
+      if (active) rerender();
+    });
+    return () => {
+      active = false;
+    };
+  }, []);
 }
 import { Field } from "@base-ui/react/field";
 import { useResolvedControlSize } from "../ComponentDefaults";
@@ -75,7 +103,7 @@ const ColorPickerRoot = React.forwardRef<HTMLDivElement, ColorPickerProps>(funct
 ) {
   const size = useResolvedControlSize(sizeProp);
   const resolvedHelperText = helperText ?? description;
-  loadColorfulDeps();
+  useColorfulDeps();
   const [internalValue, setInternalValue] = React.useState(defaultValue);
   const [inputValue, setInputValue] = React.useState(value ?? defaultValue);
   const displayValue = value !== undefined ? value : internalValue;
@@ -179,4 +207,6 @@ const ColorPickerRoot = React.forwardRef<HTMLDivElement, ColorPickerProps>(funct
 
 export const ColorPicker = Object.assign(ColorPickerRoot, {
   Root: ColorPickerRoot,
+  /** Start resolving react-colorful before first render (optional). */
+  preload: loadColorfulDeps,
 });

package/src/components/Combobox/Combobox.module.scss

@@ -194,22 +194,13 @@
   @include surface-elevated;
   @include popup-container;
 
-  border-color: var(--fui-form-group-border, $fui-border);
-
-  // Item height derived from text-base font + vertical padding
-  --_combobox-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;
 
+  border-color: var(--fui-form-group-border, $fui-border);
   min-width: var(--anchor-width);
-  // Show N items + half-peek scroll hint (default 4.5 items)
+  // Show N items + half-peek scroll hint (default 4.5 items).
   // !important needed to override Base UI's inline max-height: 100%
-  max-height: calc(
-    var(--_combobox-item-h) * var(--fui-select-max-items, 4.5) +
-      var(--fui-space-1, #{$fui-space-1}) * 2
-  ) !important;
+  max-height: var(--_popup-scroll-max-h) !important;
   overflow-y: auto !important;
 
   // Animation