@sableui/react 0.6.2 → 0.7.0

package/dist/components/relative-time/relative-time.js

@@ -0,0 +1,47 @@
+// src/components/relative-time/relative-time.tsx
+import { format, formatDistanceToNow } from "date-fns";
+import { cn } from "../../lib/cn.js";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger
+} from "../tooltip/index.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function toDate(date) {
+  return date instanceof Date ? date : new Date(date);
+}
+function RelativeTime({ date, className, ...props }) {
+  const parsed = toDate(date);
+  const relative = formatDistanceToNow(parsed, { addSuffix: true });
+  const absolute = format(parsed, "PPpp");
+  return /* @__PURE__ */ jsxs(Tooltip, { children: [
+    /* @__PURE__ */ jsx(
+      TooltipTrigger,
+      {
+        render: (
+          // design-lint-disable-next-line static-interactive -- the only hover change is text-decoration, which motion-interactive does not list and CSS cannot tween: text-decoration-line is discrete, so the underline lands in one frame either way. Adding the recipe would declare a transition that animates nothing and imply the snap had been handled.
+          /* @__PURE__ */ jsx(
+            "time",
+            {
+              dateTime: parsed.toISOString(),
+              tabIndex: 0,
+              className: cn(
+                // No type size of its own: it inherits the line it sits in (a
+                // feed meta row, a message header), so it never jumps a tier.
+                "rounded-xs underline-offset-2 decoration-dotted hover:underline focus-visible:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                className
+              ),
+              ...props
+            }
+          )
+        ),
+        children: relative
+      }
+    ),
+    /* @__PURE__ */ jsx(TooltipContent, { children: absolute })
+  ] });
+}
+RelativeTime.displayName = "RelativeTime";
+export {
+  RelativeTime
+};

package/dist/components/relative-time/relative-time.meta.js

@@ -0,0 +1,77 @@
+// src/components/relative-time/relative-time.meta.ts
+var relativeTimeMeta = {
+  name: "RelativeTime",
+  summary: `A human relative timestamp (e.g. "3 minutes ago") that reveals the full absolute date/time on hover or focus. Renders a native <time> element wrapped in our Tooltip; the absolute time is formatted with date-fns format(date, 'PPpp') (e.g. "Apr 29, 2025, 4:05:12 PM").`,
+  status: "stable",
+  keywords: [
+    "relative time",
+    "timestamp",
+    "time ago",
+    "date"
+  ],
+  usage: {
+    description: "Use RelativeTime to show recent activity or timestamps in conversational relative language.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it for feeds, audit summaries, comments, and activity streams."
+      },
+      {
+        guidance: "do",
+        description: "Expose the exact timestamp when precision matters."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use RelativeTime as the only date format for legal, billing, or audit-critical records."
+      },
+      {
+        guidance: "dont",
+        description: `Do not render it during SSR without a stable absolute fallback. "2 minutes ago" computed on the server differs from the client's value, which is a hydration mismatch \u2014 and it silently drifts as the page sits open.`
+      }
+    ]
+  },
+  related: {
+    components: [
+      "InlineStatus",
+      "Table"
+    ]
+  },
+  props: [
+    {
+      name: "date",
+      type: "Date | string | number",
+      description: "The instant to render. Accepts a Date, an ISO/parseable string, or an epoch number (ms). Coerced to a Date for date-fns."
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Merged onto the <time> trigger element (the visible relative label)."
+    },
+    {
+      name: "...time props",
+      type: 'Omit<ComponentPropsWithRef<"time">, "dateTime" | "children">',
+      description: "Remaining native <time> attributes pass through to the trigger. dateTime is set automatically from the parsed ISO value."
+    }
+  ],
+  tokensUsed: ["popover", "popover-foreground", "border", "ring"],
+  a11y: [
+    "Renders a semantic <time> element with a machine-readable dateTime (ISO) attribute.",
+    "The <time> carries tabIndex=0 (it is not focusable natively), so the absolute time \u2014 exposed via Base UI's Tooltip, which opens on keyboard focus as well as hover and wires aria-describedby \u2014 is reachable from the keyboard.",
+    "It inherits the type size of the surrounding text rather than setting its own, so it sits inside a meta row or message header without changing tier.",
+    "Wrap the page or a group in <TooltipProvider> to share open/close delays.",
+    "Relative phrasing is supplementary; the dateTime attribute remains the canonical machine value."
+  ],
+  examples: [
+    {
+      label: "Basic",
+      code: "<TooltipProvider><RelativeTime date={new Date()} /></TooltipProvider>"
+    },
+    {
+      label: "From an ISO string",
+      code: '<TooltipProvider><RelativeTime date="2025-04-29T16:05:12Z" /></TooltipProvider>'
+    }
+  ]
+};
+export {
+  relativeTimeMeta
+};

package/dist/components/scroller/index.js

@@ -0,0 +1,7 @@
+// src/components/scroller/index.ts
+import { Scroller } from "./scroller.js";
+import { scrollerMeta } from "./scroller.meta.js";
+export {
+  Scroller,
+  scrollerMeta
+};

package/dist/components/scroller/scroller.js

@@ -0,0 +1,111 @@
+"use client";
+
+// src/components/scroller/scroller.tsx
+import { useCallback, useRef } from "react";
+import { cn } from "../../lib/cn.js";
+import { setRef } from "../../lib/refs.js";
+import { useEdgeFade } from "../../lib/use-edge-fade.js";
+import { useScrollActivity } from "../../lib/use-scroll-activity.js";
+import {
+  scrollRegionKeyDown,
+  useWheelToHorizontal
+} from "../../lib/use-wheel-to-horizontal.js";
+import { jsx } from "react/jsx-runtime";
+function Scroller({
+  orientation = "vertical",
+  wheelScroll = true,
+  label,
+  className,
+  viewportClassName,
+  children,
+  ref,
+  style,
+  onScroll,
+  onKeyDown,
+  ...props
+}) {
+  const regionRef = useRef(null);
+  const isHorizontal = orientation === "horizontal";
+  const trackActivity = useScrollActivity();
+  const trackWheel = useWheelToHorizontal(isHorizontal && wheelScroll);
+  const setRegion = useCallback(
+    (node) => {
+      setRef(ref, node);
+      trackActivity(node);
+      trackWheel(node);
+      regionRef.current = node;
+    },
+    [ref, trackActivity, trackWheel]
+  );
+  const handleKeyDown = useCallback(
+    (event) => {
+      onKeyDown?.(event);
+      if (event.defaultPrevented) return;
+      scrollRegionKeyDown(event, orientation);
+    },
+    [onKeyDown, orientation]
+  );
+  const { sync: syncFade, style: fadeStyle } = useEdgeFade(regionRef, orientation);
+  const handleScroll = useCallback(
+    (event) => {
+      syncFade();
+      onScroll?.(event);
+    },
+    [syncFade, onScroll]
+  );
+  const isVertical = orientation === "vertical";
+  return (
+    // The chrome box. Carries the consumer's border/background/radius and the
+    // sizing, and is NOT masked — which is the entire point of the split. A
+    // flex column so the scroller below can be `flex-1 min-h-0`, which bounds
+    // off `h-*`, `max-h-*` and `flex-1` alike with no percentage to resolve.
+    /* @__PURE__ */ jsx("div", { style, className: cn("flex flex-col", className), children: /* @__PURE__ */ jsx(
+      "div",
+      {
+        ref: setRegion,
+        onScroll: handleScroll,
+        onKeyDown: handleKeyDown,
+        tabIndex: 0,
+        role: "group",
+        "aria-label": label,
+        "data-orientation": orientation,
+        style: fadeStyle,
+        className: cn(
+          // Fill the chrome box without a percentage height. `min-h-0` /
+          // `min-w-0` because a flex item's default `min-size: auto` refuses to
+          // shrink below its content — which is exactly how a scroll region
+          // silently stops scrolling.
+          "min-h-0 min-w-0 flex-1",
+          // Inherit the wrapper's radius so content clips to the same curve the
+          // border draws; a scroll container already clips to its own padding
+          // box, so this needs no `overflow-hidden` fighting the scroll axis.
+          "rounded-[inherit]",
+          "motion-interactive focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          // Contained overscroll: a Scroller is almost always a bounded region
+          // inside a page or a popup, and a wheel gesture that reaches its end
+          // should stop rather than start scrolling whatever is behind it.
+          "overscroll-contain",
+          isVertical ? (
+            // Vertical: a thin bar, revealed while scrolling. The fade says
+            // "more below"; the bar says how much and where you are — a long
+            // list needs both.
+            "scrollbar-quiet overflow-y-auto overflow-x-hidden"
+          ) : (
+            // Horizontal: no bar at all. The edge fades this component already
+            // draws ARE the affordance, and they say the same thing better —
+            // which is the carousel read a media strip or chip row wants. A
+            // 4px rail under a row of tiles adds chrome and no information.
+            "scrollbar-hidden overflow-x-auto overflow-y-hidden"
+          ),
+          viewportClassName
+        ),
+        ...props,
+        children
+      }
+    ) })
+  );
+}
+Scroller.displayName = "Scroller";
+export {
+  Scroller
+};

package/dist/components/scroller/scroller.meta.js

@@ -0,0 +1,118 @@
+// src/components/scroller/scroller.meta.ts
+var scrollerMeta = {
+  name: "Scroller",
+  summary: "Scroll container that fades its leading/trailing edges when content overflows. Tracks scroll position to toggle the fades.",
+  status: "stable",
+  keywords: [
+    "scroller",
+    "overflow",
+    "horizontal scroll",
+    "carousel"
+  ],
+  usage: {
+    description: "Use Scroller to create a contained overflow region for content that naturally extends beyond the viewport.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it for chip rows, media strips, or comparison sets where horizontal browsing is expected."
+      },
+      {
+        guidance: "do",
+        description: "Keep scroll affordances visible enough that overflow is discoverable."
+      },
+      {
+        guidance: "do",
+        description: "Put everything on `className` \u2014 sizing (`max-h-80`, `h-64`, `flex-1 min-h-0`) and chrome (`rounded-lg border`, `bg-card`) alike. It styles the Scroller's outer box, and the scrolling element inside it is `flex-1 min-h-0`, so a cap on the Scroller is still a cap on what scrolls."
+      },
+      {
+        guidance: "do",
+        description: 'Pass `label` on any Scroller with real content. It is a focusable region, and an unnamed one announces as a bare group \u2014 "Tags" or "Recent covers" costs a word and is the difference between navigable and not.'
+      },
+      {
+        guidance: "dont",
+        description: "Do not use Scroller to hide primary page layout or required controls."
+      },
+      {
+        guidance: "dont",
+        description: "Do not add your own wheel handler to make a horizontal strip mouse-scrollable \u2014 it already is. A second handler double-scrolls and usually loses the end-release, which traps the page."
+      },
+      {
+        guidance: "dont",
+        description: "Do not reach past it with a child selector (`[&>div]:snap-x`). The scrolling element is addressable by name: `viewportClassName`."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it to hide overflow you should have laid out. It exists to make an intentionally scrolling strip legible, not to contain content that overflowed by accident."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Carousel",
+      "Marquee"
+    ]
+  },
+  props: [
+    {
+      name: "orientation",
+      type: '"vertical" | "horizontal"',
+      default: '"vertical"',
+      description: '"vertical" scrolls and fades top/bottom; "horizontal" scrolls and fades left/right.'
+    },
+    {
+      name: "wheelScroll",
+      type: "boolean",
+      default: "true",
+      description: "On a horizontal Scroller, let a vertical mouse wheel scroll it sideways. Ignored when vertical. Turn it off only if the region is inside something that owns the wheel itself (a map, a canvas)."
+    },
+    {
+      name: "label",
+      type: "string",
+      description: "Accessible name for the scroll region. The region takes focus, so it should say what it contains; without one a screen reader announces an unnamed group."
+    },
+    {
+      name: "viewportClassName",
+      type: "string",
+      description: "Classes for the inner element that actually scrolls. Narrow on purpose \u2014 `className` is what you want almost always. This is for the few utilities that only mean something on the scrolling box: `snap-x`, `scroll-smooth`, `scroll-p-*`."
+    },
+    {
+      name: "...div props",
+      type: "ComponentPropsWithRef<'div'>",
+      description: "Everything except `className`/`style` spreads onto the SCROLLING element \u2014 `role`, `id`, `aria-*`, `data-*` and event handlers all describe the thing that scrolls, and CommandMenu relies on it to make this component its listbox. `ref` and `onScroll` likewise address the scroller, and compose with the component's own."
+    }
+  ],
+  variants: {
+    orientation: ["vertical", "horizontal"],
+    wheelScroll: ["true", "false"]
+  },
+  tokensUsed: ["ring"],
+  a11y: [
+    "The edge fades are a CSS mask-image on the scrolling element, not overlay elements \u2014 there is nothing in the DOM to intercept a pointer or be read by assistive tech, and the content under a fade stays fully interactive.",
+    'Two boxes: a chrome box carrying `className` (border, background, radius, sizing) and, inside it, the element that actually scrolls and carries the fade mask. They are split because a `mask-image` applies to its element\'s own border \u2014 so with both on one box, a bordered Scroller watched its frame dissolve at the scrolling edge. The axis is published as `data-orientation`, not `aria-orientation`, which is invalid on `role="group"`.',
+    "The scroll region uses native overflow and contains overscroll, so a gesture that runs out of content does not scroll the page behind it.",
+    'It is focusable (`tabIndex=0`, `role="group"`) and handles arrows, Home/End and PageUp/PageDown along its own axis. Chrome 128+ and Firefox make scrollable regions focusable on their own; Safari does not, so a strip with a hidden scrollbar and no focusable children is unreachable there. Declaring it makes the behaviour a property of the component, not of the reader\'s browser. Pass `label` to name it \u2014 an unnamed focusable region announces as a bare group.',
+    "On a horizontal Scroller, a vertical mouse wheel scrolls it sideways, because most mice have no horizontal wheel and the content past the fold is otherwise unreachable on them. The strip releases the wheel at both ends so it never traps the page, and leaves trackpad `deltaX` gestures and `shift+wheel` to the browser.",
+    "Cross-axis arrow keys are deliberately not captured, and a consumer can take the arrows entirely by calling `preventDefault()` in their own `onKeyDown` \u2014 a strip of interactive chips usually wants them for roving focus."
+  ],
+  examples: [
+    {
+      label: "Vertical with overflow",
+      code: '<Scroller label="Editions" className="h-64"><ul className="space-y-2 p-4">{items.map((item) => (<li key={item.id} className="text-body-sm">{item.title}</li>))}</ul></Scroller>'
+    },
+    {
+      label: "Capped, scrolls past the cap",
+      code: '<Scroller label="Versions" className="max-h-80 rounded-md border border-border"><ul className="divide-y divide-border">{versions.map((v) => (<li key={v.id} className="px-3 py-2 text-body-sm">{v.label}</li>))}</ul></Scroller>'
+    },
+    {
+      label: "Horizontal",
+      code: '<Scroller orientation="horizontal" label="Recent covers" className="w-full"><div className="flex gap-3 p-4">{covers.map((src) => (<img key={src} src={src} alt="" className="h-32 w-32 rounded-lg object-cover" />))}</div></Scroller>'
+    },
+    {
+      label: "Snap points on the scrolling box",
+      code: '<Scroller orientation="horizontal" label="Covers" className="w-full rounded-lg border border-border" viewportClassName="snap-x snap-mandatory scroll-smooth"><div className="flex gap-3 p-4">{covers.map((src) => (<img key={src} src={src} alt="" className="h-32 w-32 snap-start rounded-lg object-cover" />))}</div></Scroller>'
+    }
+  ]
+};
+export {
+  scrollerMeta
+};

package/dist/components/scrub-field/index.js

@@ -0,0 +1,7 @@
+// src/components/scrub-field/index.ts
+import { ScrubField } from "./scrub-field.js";
+import { scrubFieldMeta } from "./scrub-field.meta.js";
+export {
+  ScrubField,
+  scrubFieldMeta
+};

package/dist/components/scrub-field/scrub-field.js

@@ -0,0 +1,124 @@
+"use client";
+
+// src/components/scrub-field/scrub-field.tsx
+import { useRef, useState } from "react";
+import { Icon } from "../../icon/index.js";
+import { cn } from "../../lib/cn.js";
+import { FIELD_SHELL_XS } from "../../lib/field-shell.js";
+import { beginScrub } from "../../lib/scrub-gesture.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function ScrubField({
+  value,
+  onValueChange,
+  min,
+  max,
+  step = 1,
+  label,
+  icon,
+  prefix,
+  suffix,
+  onGestureStart,
+  onGestureEnd,
+  disabled,
+  id,
+  className
+}) {
+  const [draft, setDraft] = useState(null);
+  const inputRef = useRef(null);
+  const decimals = step < 1 ? String(step).split(".")[1]?.length ?? 0 : 0;
+  function clamp(n) {
+    let out = n;
+    if (min !== void 0) out = Math.max(min, out);
+    if (max !== void 0) out = Math.min(max, out);
+    return Number(out.toFixed(decimals));
+  }
+  const display = draft ?? value.toFixed(decimals);
+  function commitDraft() {
+    if (draft === null) return;
+    const parsed = Number.parseFloat(draft);
+    if (Number.isFinite(parsed)) onValueChange?.(clamp(parsed));
+    setDraft(null);
+  }
+  function onKeyDown(e) {
+    if (e.key === "Enter") {
+      e.preventDefault();
+      commitDraft();
+      inputRef.current?.blur();
+      return;
+    }
+    if (e.key === "Escape") {
+      e.preventDefault();
+      setDraft(null);
+      inputRef.current?.blur();
+      return;
+    }
+    if (e.key === "ArrowUp" || e.key === "ArrowDown") {
+      e.preventDefault();
+      const magnitude = step * (e.shiftKey ? 10 : 1);
+      const base = draft !== null ? Number.parseFloat(draft) : value;
+      if (!Number.isFinite(base)) return;
+      onValueChange?.(clamp(base + (e.key === "ArrowUp" ? magnitude : -magnitude)));
+      setDraft(null);
+    }
+  }
+  function onScrubDown(e) {
+    beginScrub(e, {
+      value,
+      step,
+      clamp,
+      onValueChange,
+      onGestureStart,
+      onGestureEnd,
+      disabled
+    });
+  }
+  const hasHandle = Boolean(icon || prefix);
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cn(
+        "group flex h-(--control-xs) items-center gap-1 px-1.5 motion-interactive",
+        FIELD_SHELL_XS,
+        "focus-within:ring-2 focus-within:ring-ring",
+        disabled && "pointer-events-none opacity-50",
+        className ?? "w-full"
+      ),
+      children: [
+        hasHandle ? /* @__PURE__ */ jsx(
+          "span",
+          {
+            "aria-hidden": true,
+            title: `Drag to change ${label}`,
+            onPointerDown: onScrubDown,
+            className: "flex shrink-0 cursor-ew-resize select-none items-center text-muted-foreground motion-interactive group-hover:text-foreground",
+            children: icon ? /* @__PURE__ */ jsx(Icon, { name: icon, className: "text-xs" }) : /* @__PURE__ */ jsx("span", { className: "text-ui-num", children: prefix })
+          }
+        ) : null,
+        /* @__PURE__ */ jsx(
+          "input",
+          {
+            ref: inputRef,
+            id,
+            type: "text",
+            inputMode: "decimal",
+            "aria-label": label,
+            disabled,
+            value: display,
+            onChange: (e) => setDraft(e.target.value),
+            onBlur: commitDraft,
+            onKeyDown,
+            onFocus: (e) => e.currentTarget.select(),
+            style: { width: `${Math.max(display.length, 2) + 0.5}ch` },
+            className: "min-w-0 shrink-0 bg-transparent text-ui-num text-foreground outline-none"
+          }
+        ),
+        suffix ? /* @__PURE__ */ jsx("span", { className: "shrink-0 text-ui-num text-muted-foreground", children: suffix }) : null,
+        /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: "min-w-0 flex-1" })
+      ]
+    }
+  );
+}
+ScrubField.displayName = "ScrubField";
+export {
+  ScrubField
+};

package/dist/components/scrub-field/scrub-field.meta.js

@@ -0,0 +1,139 @@
+// src/components/scrub-field/scrub-field.meta.ts
+var scrubFieldMeta = {
+  name: "ScrubField",
+  summary: "The compact numeric field a property grid is built from: a leading glyph inside the field that doubles as a drag-to-scrub handle, the value, and an optional unit.",
+  keywords: [
+    "scrub",
+    "numeric",
+    "number",
+    "field",
+    "property",
+    "inspector",
+    "drag",
+    "workspace",
+    "tool",
+    "unit"
+  ],
+  usage: {
+    description: "Use ScrubField for numeric properties in tool chrome \u2014 an inspector, a property grid, a panel. The leading icon or letter says what the number is and is also the thing you drag, which is why a value like opacity needs no slider. Reach for NumberField instead in page-register forms: it has steppers and locale formatting, and it renders at page-register height. Those two steppers put a ~112px floor on a control that needs to be about 44px in a property grid, which is why ScrubField exists rather than a NumberField size variant. The input is sized in ch, so each field is as wide as its longest value and a grid of them lines up without per-field tuning.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Give the field an icon or prefix when it stands alone, so the row has a drag affordance and the value has an identity."
+      },
+      {
+        guidance: "do",
+        description: "Pass the unit as `suffix` rather than baking it into the label \u2014 it renders against the number the way reference tools show 100%."
+      },
+      {
+        guidance: "do",
+        description: "Bracket undo with onGestureStart/onGestureEnd. A scrub fires per frame, so without it one undo rewinds a single pixel of the drag."
+      },
+      {
+        guidance: "do",
+        description: "Set `step` to the real precision (0.01 for a normalised threshold). Display precision follows it, so a seed shows 1234 and never 1,234."
+      },
+      {
+        guidance: "dont",
+        description: "Add a separate drag gripper beside the glyph. The icon or prefix already is the scrub handle; a second one is the same affordance twice and costs width a 240px panel does not have."
+      },
+      {
+        guidance: "dont",
+        description: "Pair it with a Slider AND give it a glyph. The slider is already the drag affordance; two on one row is the same gesture twice. Omit icon/prefix when there's a slider."
+      },
+      {
+        guidance: "dont",
+        description: "Use it in a page form. It is chrome-sized and has no label, description, or error slots \u2014 that's Field plus Input or NumberField."
+      }
+    ]
+  },
+  related: {
+    components: ["NumberField", "Slider", "PanelSection", "Workspace", "Input"]
+  },
+  status: "stable",
+  props: [
+    { name: "value", type: "number", description: "The current value (controlled)." },
+    {
+      name: "onValueChange",
+      type: "(next: number) => void",
+      description: "Fires on commit, arrow-key step, and every frame of a scrub."
+    },
+    { name: "min", type: "number", description: "Lower clamp, applied to typing and scrubbing." },
+    { name: "max", type: "number", description: "Upper clamp, applied to typing and scrubbing." },
+    {
+      name: "step",
+      type: "number",
+      default: "1",
+      description: "Arrow-key and scrub increment, and the source of display precision. Shift multiplies arrows by 10 and divides scrubbing by 10."
+    },
+    {
+      name: "label",
+      type: "string",
+      description: "Accessible name for the input. Required \u2014 the visible glyph is decorative."
+    },
+    {
+      name: "icon",
+      type: "string",
+      description: "Semantic icon name rendered inside the field; doubles as the scrub handle. Any name the app's IconProvider resolves works \u2014 image tools typically supply their own checkerboard glyph for opacity, which is a domain icon rather than one Sable's contract carries."
+    },
+    {
+      name: "prefix",
+      type: "ReactNode",
+      description: 'Short text used instead of an icon (e.g. "X" / "Y"), with the same scrub role.'
+    },
+    {
+      name: "suffix",
+      type: "ReactNode",
+      description: 'Unit rendered after the value inside the field (e.g. "%", "px").'
+    },
+    {
+      name: "onGestureStart",
+      type: "() => void",
+      description: "Fires once when a scrub drag begins \u2014 open an undo transaction here, and drop expensive downstream work (e.g. a GPU renderer) to a cheap preview quality; without it a pipeline re-renders at full quality on every pointer move and the drag stutters."
+    },
+    {
+      name: "onGestureEnd",
+      type: "() => void",
+      description: "Fires when a scrub drag ends \u2014 close the undo transaction here and restore full render quality."
+    },
+    { name: "disabled", type: "boolean", description: "Disables typing and scrubbing." },
+    { name: "id", type: "string", description: "Input id, for a PropertyRow's htmlFor." }
+  ],
+  a11y: [
+    "The input carries the accessible name via `label`; the glyph is aria-hidden because it is decorative.",
+    "Every scrub gesture is reachable from the keyboard: ArrowUp/ArrowDown step by `step`, Shift+Arrow by ten steps.",
+    "Enter commits, Escape reverts to the last committed value, and blur commits \u2014 so a partial edit is never silently kept."
+  ],
+  tokensUsed: ["foreground", "muted-foreground", "ring", "panel-field", "panel-field-hover"],
+  examples: [
+    {
+      label: "Opacity with a glyph handle",
+      code: '<ScrubField label="Opacity" icon="grid" suffix="%" value={60} min={0} max={100} onValueChange={(v) => setOpacity(v)} />'
+    },
+    {
+      label: "X/Y offset pair (PropertyPair puts two fields on one scan line)",
+      code: `<PropertyPair labels={["Offset X", "Offset Y"]}>
+  <ScrubField label="Offset X" prefix="X" value={x} min={-128} max={128} onValueChange={setX} />
+  <ScrubField label="Offset Y" prefix="Y" value={y} min={-128} max={128} onValueChange={setY} />
+</PropertyPair>`
+    },
+    {
+      label: "No glyph \u2014 the property name is the handle",
+      code: `<PropertyRow label="Block size" scrub={{ value: size, onValueChange: setSize, min: 2, max: 256 }}>
+  <ScrubField label="Block size" value={size} min={2} max={256} suffix="px" onValueChange={setSize} />
+</PropertyRow>`
+    },
+    {
+      label: "Paired with a slider (no glyph \u2014 one drag affordance per row)",
+      code: `<PropertyRow label="Block size" stacked>
+  <div className="flex items-center gap-2">
+    <Slider value={32} min={4} max={256} className="min-w-0 flex-1" />
+    <ScrubField label="Block size" value={32} min={4} max={256} step={1} suffix="px" className="w-16 shrink-0" onValueChange={(v) => setBlockSize(v)} />
+  </div>
+</PropertyRow>`
+    }
+  ]
+};
+export {
+  scrubFieldMeta
+};

package/dist/components/search-input/index.js

@@ -0,0 +1,7 @@
+// src/components/search-input/index.ts
+import { SearchInput } from "./search-input.js";
+import { searchInputMeta } from "./search-input.meta.js";
+export {
+  SearchInput,
+  searchInputMeta
+};