@elabs-ai/components-ui 4.2.0 → 5.1.0

package/src/lib/compact-number.ts

@@ -13,9 +13,46 @@
  * disagreeing about what `1500` looks like.
  */
 
-/** How a numeric value is rendered. Mirrors the charts `ChartValueFormat`. */
+/** How a numeric value is rendered. Mirrors the charts `ChartValueFormatPreset`. */
 export type NumberFormatKind = "number" | "compact" | "currency" | "percent";
 
+/**
+ * The object form of {@link NumberFormat} (RM-109) — decimals, sign,
+ * prefix/suffix and abbreviation as independent knobs. Mirrors the charts
+ * `ChartValueFormatSpec` field-for-field; see that type's docblock
+ * (`packages/charts/src/charts/value-format.ts`) for the full contract of
+ * each field — this is the DELIBERATE TWIN, not a reinterpretation.
+ */
+export interface NumberFormatSpec {
+  style?: "number" | "currency" | "percent";
+  decimals?: number;
+  optionalDecimals?: boolean;
+  abbreviate?: boolean | "auto";
+  sign?: "auto" | "always" | "parens";
+  prefix?: string;
+  suffix?: string;
+  grouping?: boolean;
+  currency?: string;
+}
+
+/** A preset string or the {@link NumberFormatSpec} object form (RM-109). */
+export type NumberFormat = NumberFormatKind | NumberFormatSpec;
+
+/** The preset strings' shape, expressed as specs — the union's one resolved shape. */
+const PRESET_NUMBER_FORMAT_SPECS: Record<NumberFormatKind, NumberFormatSpec> = {
+  number: { style: "number", abbreviate: false },
+  compact: { style: "number", abbreviate: "auto" },
+  currency: { style: "currency", abbreviate: "auto" },
+  percent: { style: "percent", abbreviate: false },
+};
+
+/** Normalizes a preset string or a spec object to one {@link NumberFormatSpec} shape. */
+export function resolveNumberFormatSpec(format: NumberFormat): NumberFormatSpec {
+  return typeof format === "string"
+    ? (PRESET_NUMBER_FORMAT_SPECS[format] ?? PRESET_NUMBER_FORMAT_SPECS.compact)
+    : format;
+}
+
 /** Magnitude at or above which `compact`/`currency` switch to compact notation. */
 export const COMPACT_THRESHOLD = 1000;
 
@@ -25,37 +62,90 @@ export const DEFAULT_CURRENCY = "USD";
 /** One decimal keeps `1.5M` readable without implying precision it lacks. */
 export const DEFAULT_MAX_FRACTION_DIGITS = 1;
 
-/** `Intl.NumberFormatOptions` for `format` at this magnitude. */
+/** Whether `value`'s magnitude earns compact notation. */
+export function shouldCompact(value: number): boolean {
+  return Number.isFinite(value) && Math.abs(value) >= COMPACT_THRESHOLD;
+}
+
+/**
+ * The full answer for `format` at this magnitude: `Intl.NumberFormatOptions`
+ * plus the two things Intl cannot express — literal `prefix`/`suffix` text
+ * and `sign: "parens"` (accounting-style negatives). Twin of
+ * `resolveChartValueFormat` (`value-format.ts`) — same fields, same rules.
+ */
+export interface ResolvedNumberFormat {
+  /** Pure `Intl.NumberFormatOptions` — everything Intl itself can render. */
+  options: Intl.NumberFormatOptions;
+  /** Literal text before the formatted number. */
+  prefix: string;
+  /** Literal text after the formatted number. */
+  suffix: string;
+  /** `true` when a negative value renders as `(…)` instead of a minus sign. */
+  parens: boolean;
+}
+
+export function resolveNumberFormat(
+  format: NumberFormat,
+  value: number,
+  currency: string = DEFAULT_CURRENCY,
+  maxFractionDigits?: number,
+): ResolvedNumberFormat {
+  const spec = resolveNumberFormatSpec(format);
+  const style = spec.style ?? "number";
+  const isPercent = style === "percent";
+  const options: Intl.NumberFormatOptions = {};
+
+  if (style === "currency") {
+    options.style = "currency";
+    options.currency = spec.currency ?? currency;
+  } else if (isPercent) {
+    options.style = "percent";
+  }
+
+  const wantsAbbreviate =
+    !isPercent && (spec.abbreviate === true || (spec.abbreviate !== false && shouldCompact(value)));
+  if (wantsAbbreviate) {
+    options.notation = "compact";
+    options.compactDisplay = "short";
+  }
+
+  const exactValueEscapeHatch = style === "number" && spec.abbreviate === false;
+  const digits =
+    spec.decimals ??
+    maxFractionDigits ??
+    (exactValueEscapeHatch ? undefined : DEFAULT_MAX_FRACTION_DIGITS);
+  if (digits !== undefined) {
+    options.maximumFractionDigits = digits;
+    if (spec.optionalDecimals === false) {
+      options.minimumFractionDigits = digits;
+    }
+  }
+
+  if (spec.grouping === false) {
+    options.useGrouping = false;
+  }
+
+  let parens = false;
+  if (spec.sign === "always") {
+    options.signDisplay = "always";
+  } else if (spec.sign === "parens") {
+    options.signDisplay = "never";
+    parens = true;
+  }
+
+  return { options, prefix: spec.prefix ?? "", suffix: spec.suffix ?? "", parens };
+}
+
+/**
+ * `Intl.NumberFormatOptions` for `format` at this magnitude — the pure-Intl
+ * subset of {@link resolveNumberFormat}, kept as its own export because it is
+ * the one every existing call site (and test) already depends on.
+ */
 export function numberFormatOptions(
   format: NumberFormatKind,
   value: number,
   currency: string = DEFAULT_CURRENCY,
   maxFractionDigits?: number,
 ): Intl.NumberFormatOptions {
-  const compact = Number.isFinite(value) && Math.abs(value) >= COMPACT_THRESHOLD;
-  // `"number"` is the exact-value escape hatch and keeps `Intl`'s own default
-  // (3 digits) unless the caller states one — capping it at the compact rung's
-  // single decimal would render 0.0512 as "0.1".
-  const digits = maxFractionDigits ?? DEFAULT_MAX_FRACTION_DIGITS;
-  switch (format) {
-    case "number":
-      return maxFractionDigits === undefined ? {} : { maximumFractionDigits: maxFractionDigits };
-    case "percent":
-      return { style: "percent", maximumFractionDigits: digits };
-    case "currency":
-      return compact
-        ? {
-            style: "currency",
-            currency,
-            notation: "compact",
-            compactDisplay: "short",
-            maximumFractionDigits: digits,
-          }
-        : { style: "currency", currency, maximumFractionDigits: digits };
-    case "compact":
-    default:
-      return compact
-        ? { notation: "compact", compactDisplay: "short", maximumFractionDigits: digits }
-        : { maximumFractionDigits: digits };
-  }
+  return resolveNumberFormat(format, value, currency, maxFractionDigits).options;
 }

package/src/lib/use-scroll-progress.ts

@@ -0,0 +1,103 @@
+"use client";
+
+import { useEffect, useRef, useState, type RefObject } from "react";
+
+/**
+ * The motion gate (`packages/tokens/src/themes.css`, MOTION GATE) sets `--motion-factor` to
+ * 0.0001 under a reduce request and 1 otherwise. Anything at or below this floor is "motion off".
+ */
+export const MOTION_FACTOR_FLOOR = 0.01;
+
+/** `--motion-factor` as seen by `el` (default: the document root); 1 when unset or on the server. */
+export function readMotionFactor(el?: Element | null): number {
+  if (typeof window === "undefined") return 1;
+  const target = el ?? document.documentElement;
+  const value = Number.parseFloat(getComputedStyle(target).getPropertyValue("--motion-factor"));
+  return Number.isFinite(value) ? value : 1;
+}
+
+/** True when the factor sits at the floor — the reader asked for reduced motion. */
+export function isMotionAtFloor(factor: number): boolean {
+  return factor <= MOTION_FACTOR_FLOOR;
+}
+
+/** True when the browser runs scroll-driven CSS animations (`animation-timeline: scroll()`). */
+export function supportsScrollTimeline(): boolean {
+  return (
+    typeof CSS !== "undefined" &&
+    typeof CSS.supports === "function" &&
+    CSS.supports("animation-timeline: scroll()")
+  );
+}
+
+/**
+ * How root scroll progress is delivered:
+ * - `static` — server render, before hydration, motion at the floor, or disabled: nothing moves.
+ * - `timeline` — the browser runs `animation-timeline: scroll()`; the caller's CSS does the work
+ *   on the compositor and no JavaScript listens to scroll.
+ * - `script` — no scroll timelines: `motion`'s `scroll()` (an optional peer, imported lazily
+ *   only here) calls `onScroll` every frame.
+ */
+export type ScrollProgressMode = "static" | "timeline" | "script";
+
+export interface ScrollProgressOptions {
+  /** Skip all work (e.g. a plane whose rate means it never moves). Default `true`. */
+  enabled?: boolean;
+  /** Read `--motion-factor` from this element (so a subtree can dial motion); default the root. */
+  target?: RefObject<Element | null>;
+}
+
+export interface ScrollProgress {
+  mode: ScrollProgressMode;
+  /** `--motion-factor` read once after mount (1 before hydration). */
+  factor: number;
+}
+
+/**
+ * Root scroll progress under the motion gate. The factor is read once, after hydration, so the
+ * server HTML and the first client render are identical (`static`). `onScroll(scrollY, progress)`
+ * fires only in `script` mode; it may change between renders without resubscribing.
+ */
+export function useScrollProgress(
+  onScroll?: (scrollY: number, progress: number) => void,
+  { enabled = true, target }: ScrollProgressOptions = {},
+): ScrollProgress {
+  const [state, setState] = useState<ScrollProgress>({ mode: "static", factor: 1 });
+  const onScrollRef = useRef(onScroll);
+
+  useEffect(() => {
+    onScrollRef.current = onScroll;
+  });
+
+  useEffect(() => {
+    const factor = readMotionFactor(target?.current);
+    if (!enabled || isMotionAtFloor(factor)) {
+      setState({ mode: "static", factor });
+      return;
+    }
+    if (supportsScrollTimeline()) {
+      setState({ mode: "timeline", factor });
+      return;
+    }
+    setState({ mode: "script", factor });
+    let cancelled = false;
+    let stop: (() => void) | undefined;
+    import("motion")
+      .then(({ scroll }) => {
+        if (cancelled) return;
+        stop = scroll((progress: number, info) => {
+          onScrollRef.current?.(info.y.current, progress);
+        });
+      })
+      .catch(() => {
+        // `motion` is an optional peer: without it the page simply does not move.
+        if (!cancelled) setState({ mode: "static", factor });
+      });
+    return () => {
+      cancelled = true;
+      stop?.();
+    };
+  }, [enabled, target]);
+
+  return state;
+}

package/src/motion.stories.tsx

@@ -180,6 +180,7 @@ export const GateFullMotion: Story = {
  * transitionend and would strand Radix's unmount-suspension).
  */
 export const GateReducedMotion: Story = {
+  tags: ["!dev"],
   render: () => <MotionDemo />,
   play: async ({ canvasElement }) => {
     const root = document.documentElement;

package/src/templates-object-detail-hub.stories.tsx

@@ -251,8 +251,8 @@ function RunPipelineDialog({ pipeline }: { pipeline: Pipeline }) {
           </DialogDescription>
         </DialogHeader>
 
-        <div className="space-y-3">
-          <div className="space-y-1.5">
+        <div className="flex flex-col gap-3">
+          <div className="flex flex-col gap-1.5">
             <Label htmlFor="run-window">Backfill window (optional)</Label>
             <Input id="run-window" placeholder="e.g. last 24 hours" autoComplete="off" />
           </div>
@@ -323,7 +323,7 @@ function PipelineHub({ pipeline }: { pipeline: Pipeline }) {
           </TabsList>
 
           {/* Overview — summary first: KPIs, then attributes, then children */}
-          <TabsContent value="overview" className="space-y-6">
+          <TabsContent value="overview" className="flex flex-col gap-6">
             <div className="grid grid-cols-1 gap-4 sm:grid-cols-3">
               <MetricCard
                 label="Rows (24h)"
@@ -357,17 +357,17 @@ function PipelineHub({ pipeline }: { pipeline: Pipeline }) {
           </TabsContent>
 
           {/* Activity — the related child list in full */}
-          <TabsContent value="activity" className="space-y-4">
+          <TabsContent value="activity" className="flex flex-col gap-4">
             <RunList runs={pipeline.runs} />
           </TabsContent>
 
           {/* Settings — a couple of editable fields */}
-          <TabsContent value="settings" className="max-w-lg space-y-5">
-            <div className="space-y-1.5">
+          <TabsContent value="settings" className="max-w-lg flex flex-col gap-5">
+            <div className="flex flex-col gap-1.5">
               <Label htmlFor="hub-name">Pipeline name</Label>
               <Input id="hub-name" defaultValue={pipeline.name} autoComplete="off" />
             </div>
-            <div className="space-y-1.5">
+            <div className="flex flex-col gap-1.5">
               <Label htmlFor="hub-schedule">Schedule</Label>
               <Input id="hub-schedule" defaultValue={pipeline.schedule} autoComplete="off" />
             </div>
@@ -442,7 +442,7 @@ function ObjectDetailHub({ startSelected = "rev" }: { startSelected?: string | n
 /* -------------------------------------------------------------------------- */
 
 const meta = {
-  title: "Patterns/Templates/Object Detail Hub",
+  title: "Patterns/Templates/Starters/Object Detail Hub",
   component: ObjectDetailHub,
   parameters: {
     layout: "fullscreen",

package/src/templates-screen-states.stories.tsx

@@ -266,7 +266,7 @@ function CustomersScreen({ state = "ready" }: { state?: ScreenState }) {
 /* -------------------------------------------------------------------------- */
 
 const meta = {
-  title: "Patterns/Templates/Screen States",
+  title: "Patterns/Templates/Starters/Screen States",
   component: CustomersScreen,
   parameters: {
     layout: "fullscreen",

package/src/templates-settings.stories.tsx

@@ -18,9 +18,11 @@ import {
   DescriptionsItem,
   Input,
   Label,
+  NavUser,
   Separator,
   Sidebar,
   SidebarContent,
+  SidebarFooter,
   SidebarGroup,
   SidebarGroupContent,
   SidebarHeader,
@@ -33,8 +35,8 @@ import {
   Wizard,
   WizardNav,
   WizardStep,
-  WizardSteps,
   type WizardStepMeta,
+  WizardSteps,
 } from "./index";
 import { Bell, Home, Shield, User } from "lucide-react";
 
@@ -222,9 +224,12 @@ function SettingsTemplate() {
             </SidebarGroupContent>
           </SidebarGroup>
         </SidebarContent>
+        <SidebarFooter>
+          <NavUser user={{ name: "Avery Rao", email: "avery@example.com" }} />
+        </SidebarFooter>
       </Sidebar>
       <SidebarInset>
-        <header className="flex h-14 items-center gap-2 border-b px-4">
+        <header className="flex h-header items-center gap-2 border-b px-4">
           <SidebarTrigger />
           <h1 className="text-body font-medium capitalize">{active}</h1>
         </header>
@@ -235,7 +240,7 @@ function SettingsTemplate() {
 }
 
 const meta = {
-  title: "Patterns/Templates/Settings",
+  title: "Patterns/Templates/Starters/Settings",
   parameters: { layout: "fullscreen" },
   tags: ["autodocs"],
 } satisfies Meta;

package/dist/chunk-FCH4ZN6G.js

@@ -1,57 +0,0 @@
-"use client";
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-
-// src/lib/cn.ts
-import { clsx } from "clsx";
-import { extendTailwindMerge } from "tailwind-merge";
-var TEXT_ROLES = ["display", "title", "subtitle", "body", "caption", "meta", "kpi", "code"];
-var twMerge = extendTailwindMerge({
-  extend: {
-    classGroups: {
-      "font-size": [{ text: TEXT_ROLES }],
-      // `font-display` is the display-face seam (sibling of font-mono, #187).
-      "font-family": [{ font: ["display"] }],
-      // Theme-driven control/table knobs (themes.css § CONTROL UTILITIES and the
-      // `@theme inline` bridge) — so a caller's `h-8` / `rounded-none` /
-      // `font-bold` / `shadow-none` still replaces the token default.
-      "font-weight": [{ font: ["control", "table-header"] }],
-      rounded: [{ rounded: ["control"] }],
-      shadow: [{ shadow: ["input"] }],
-      h: [{ h: ["control", "control-sm", "control-lg", "header"] }],
-      size: [{ size: ["control", "control-sm", "control-lg"] }],
-      "min-w": [{ "min-w": ["control", "control-sm", "control-lg"] }]
-    }
-  }
-});
-function cn(...inputs) {
-  return twMerge(clsx(inputs));
-}
-
-// src/components/label/label.tsx
-import { forwardRef } from "react";
-import * as LabelPrimitive from "@radix-ui/react-label";
-import { jsx } from "react/jsx-runtime";
-var Label = forwardRef(function Label2({ className, ...props }, ref) {
-  return /* @__PURE__ */ jsx(
-    LabelPrimitive.Root,
-    {
-      ref,
-      className: cn(
-        "text-body font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70",
-        className
-      ),
-      ...props
-    }
-  );
-});
-
-export {
-  __export,
-  cn,
-  Label
-};
-//# sourceMappingURL=chunk-FCH4ZN6G.js.map

package/dist/chunk-FCH4ZN6G.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/lib/cn.ts","../src/components/label/label.tsx"],"sourcesContent":["import { clsx, type ClassValue } from \"clsx\";\nimport { extendTailwindMerge } from \"tailwind-merge\";\n\n/**\n * The semantic type roles (`--text-<role>` tokens → `text-<role>` utilities, #187).\n * tailwind-merge doesn't know custom theme keys, so without registration it\n * classifies `text-title` as a text COLOR — and `cn(\"text-kpi\", \"text-foreground\")`\n * would silently drop the role. Registering the roles in the `font-size` class\n * group makes role-vs-role and role-vs-raw-size conflicts resolve correctly while\n * keeping role + color independent.\n */\nconst TEXT_ROLES = [\"display\", \"title\", \"subtitle\", \"body\", \"caption\", \"meta\", \"kpi\", \"code\"];\n\nconst twMerge = extendTailwindMerge({\n  extend: {\n    classGroups: {\n      \"font-size\": [{ text: TEXT_ROLES }],\n      // `font-display` is the display-face seam (sibling of font-mono, #187).\n      \"font-family\": [{ font: [\"display\"] }],\n      // Theme-driven control/table knobs (themes.css § CONTROL UTILITIES and the\n      // `@theme inline` bridge) — so a caller's `h-8` / `rounded-none` /\n      // `font-bold` / `shadow-none` still replaces the token default.\n      \"font-weight\": [{ font: [\"control\", \"table-header\"] }],\n      rounded: [{ rounded: [\"control\"] }],\n      shadow: [{ shadow: [\"input\"] }],\n      h: [{ h: [\"control\", \"control-sm\", \"control-lg\", \"header\"] }],\n      size: [{ size: [\"control\", \"control-sm\", \"control-lg\"] }],\n      \"min-w\": [{ \"min-w\": [\"control\", \"control-sm\", \"control-lg\"] }],\n    },\n  },\n});\n\n/**\n * Merge class names with conflict resolution. `clsx` handles conditionals;\n * `tailwind-merge` ensures later Tailwind utilities win (e.g. `p-2 p-4` -> `p-4`).\n * Use this in every component that accepts a `className` prop.\n */\nexport function cn(...inputs: ClassValue[]): string {\n  return twMerge(clsx(inputs));\n}\n","import { forwardRef, type ComponentPropsWithoutRef, type ElementRef } from \"react\";\nimport * as LabelPrimitive from \"@radix-ui/react-label\";\nimport { cn } from \"../../lib/cn\";\n\nexport const Label = forwardRef<\n  ElementRef<typeof LabelPrimitive.Root>,\n  ComponentPropsWithoutRef<typeof LabelPrimitive.Root>\n>(function Label({ className, ...props }, ref) {\n  return (\n    <LabelPrimitive.Root\n      ref={ref}\n      className={cn(\n        \"text-body font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70\",\n        className,\n      )}\n      {...props}\n    />\n  );\n});\n"],"mappings":";;;;;;;;AAAA,SAAS,YAA6B;AACtC,SAAS,2BAA2B;AAUpC,IAAM,aAAa,CAAC,WAAW,SAAS,YAAY,QAAQ,WAAW,QAAQ,OAAO,MAAM;AAE5F,IAAM,UAAU,oBAAoB;AAAA,EAClC,QAAQ;AAAA,IACN,aAAa;AAAA,MACX,aAAa,CAAC,EAAE,MAAM,WAAW,CAAC;AAAA;AAAA,MAElC,eAAe,CAAC,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;AAAA;AAAA;AAAA;AAAA,MAIrC,eAAe,CAAC,EAAE,MAAM,CAAC,WAAW,cAAc,EAAE,CAAC;AAAA,MACrD,SAAS,CAAC,EAAE,SAAS,CAAC,SAAS,EAAE,CAAC;AAAA,MAClC,QAAQ,CAAC,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;AAAA,MAC9B,GAAG,CAAC,EAAE,GAAG,CAAC,WAAW,cAAc,cAAc,QAAQ,EAAE,CAAC;AAAA,MAC5D,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,cAAc,YAAY,EAAE,CAAC;AAAA,MACxD,SAAS,CAAC,EAAE,SAAS,CAAC,WAAW,cAAc,YAAY,EAAE,CAAC;AAAA,IAChE;AAAA,EACF;AACF,CAAC;AAOM,SAAS,MAAM,QAA8B;AAClD,SAAO,QAAQ,KAAK,MAAM,CAAC;AAC7B;;;ACvCA,SAAS,kBAAkE;AAC3E,YAAY,oBAAoB;AAQ5B;AALG,IAAM,QAAQ,WAGnB,SAASA,OAAM,EAAE,WAAW,GAAG,MAAM,GAAG,KAAK;AAC7C,SACE;AAAA,IAAgB;AAAA,IAAf;AAAA,MACC;AAAA,MACA,WAAW;AAAA,QACT;AAAA,QACA;AAAA,MACF;AAAA,MACC,GAAG;AAAA;AAAA,EACN;AAEJ,CAAC;","names":["Label"]}