@sableui/react 0.6.2 → 0.7.1

package/dist/components/skeleton/index.js

@@ -0,0 +1,7 @@
+// src/components/skeleton/index.ts
+import { Skeleton } from "./skeleton.js";
+import { skeletonMeta } from "./skeleton.meta.js";
+export {
+  Skeleton,
+  skeletonMeta
+};

package/dist/components/skeleton/skeleton.js

@@ -0,0 +1,16 @@
+// src/components/skeleton/skeleton.tsx
+import { cn } from "../../lib/cn.js";
+import { jsx } from "react/jsx-runtime";
+function Skeleton({ className, ...props }) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: cn("motion-shimmer rounded-md bg-muted", className),
+      ...props
+    }
+  );
+}
+Skeleton.displayName = "Skeleton";
+export {
+  Skeleton
+};

package/dist/components/skeleton/skeleton.meta.js

@@ -0,0 +1,90 @@
+// src/components/skeleton/skeleton.meta.ts
+var skeletonMeta = {
+  name: "Skeleton",
+  summary: "Loading placeholder \u2014 a muted, shimmering block (rounded-md bg-muted motion-shimmer). Shape it with utility classes; rounded-full for circles.",
+  status: "stable",
+  keywords: [
+    "skeleton",
+    "loading",
+    "placeholder",
+    "pending"
+  ],
+  usage: {
+    description: "Use Skeleton to reserve space and hint at the shape of content while data is loading.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Match the approximate size and rhythm of the eventual content."
+      },
+      {
+        guidance: "do",
+        description: "Use it for content regions where layout stability matters during loading."
+      },
+      {
+        guidance: "dont",
+        description: "Do not leave Skeleton visible after an error or empty state; switch to EmptyState (tone='destructive' for an error)."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use a skeleton whose shape differs from the content that replaces it. A mismatched placeholder causes a visible jump, which is worse than a brief spinner."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Spinner",
+      "PageLoader"
+    ]
+  },
+  props: [
+    {
+      name: "...props",
+      type: 'ComponentPropsWithRef<"div">',
+      description: "All native div props plus className. Size and shape the placeholder with utilities (h-*, w-*, size-*, rounded-full)."
+    }
+  ],
+  tokensUsed: ["muted"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "A skeleton stands in for content that has not arrived; fading the placeholder in adds a wait before the wait."
+    },
+    {
+      slot: "response",
+      recipe: "none",
+      part: "Root",
+      why: "Nothing here is interactive. A skeleton that reacted to the pointer would invite a click on a thing that cannot be clicked."
+    },
+    {
+      slot: "transition",
+      recipe: "none",
+      part: "Root",
+      why: "The skeleton has one state. Swapping it for real content is the parent's job, and the parent decides whether that swap is animated."
+    },
+    {
+      slot: "activity",
+      recipe: "motion-shimmer",
+      part: "Root",
+      why: "The sweep is the entire point of the component: it is what separates 'still loading' from 'loaded, and empty'. A static grey block is indistinguishable from a broken layout, which is why users reload the page. It is one band of light against the viewport, so every skeleton in a loading layout lights in sequence as a single wave rather than each block flashing at its own speed; each pass eases in, glides and settles, then rests off-screen before the next."
+    }
+  ],
+  a11y: [
+    "Purely presentational; the shimmer sweep is decorative, and it stops under reduced motion because motion-shimmer follows --motion-scale.",
+    'Mark the loading region with aria-busy="true" on a parent, and swap in real content (with the same layout) once loaded to avoid shift.'
+  ],
+  examples: [
+    {
+      label: "Shapes",
+      code: '<Skeleton className="h-4 w-40" /><Skeleton className="size-10 rounded-full" /><Skeleton className="h-40 w-full" />'
+    },
+    {
+      label: "Post-card composition",
+      code: '<div className="flex items-center gap-3"><Skeleton className="size-10 rounded-full" /><div className="space-y-2"><Skeleton className="h-3 w-32" /><Skeleton className="h-3 w-20" /></div></div>'
+    }
+  ]
+};
+export {
+  skeletonMeta
+};

package/dist/components/slider/index.js

@@ -0,0 +1,21 @@
+// src/components/slider/index.ts
+import {
+  Slider,
+  SliderRoot,
+  SliderControl,
+  SliderTrack,
+  SliderIndicator,
+  SliderThumb,
+  SliderValue
+} from "./slider.js";
+import { sliderMeta } from "./slider.meta.js";
+export {
+  Slider,
+  SliderControl,
+  SliderIndicator,
+  SliderRoot,
+  SliderThumb,
+  SliderTrack,
+  SliderValue,
+  sliderMeta
+};

package/dist/components/slider/slider.js

@@ -0,0 +1,115 @@
+"use client";
+
+// src/components/slider/slider.tsx
+import { Slider as Base } from "@base-ui/react/slider";
+import { cn } from "../../lib/cn.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var SliderRoot = Base.Root;
+var SliderValue = Base.Value;
+function SliderControl({ className, ...props }) {
+  return /* @__PURE__ */ jsx(
+    Base.Control,
+    {
+      className: cn(
+        "relative flex h-5 w-full items-center data-[disabled]:opacity-50",
+        // Vertical: the same lane turned on its side. Give the slider a
+        // height (h-40, flex-1) — a vertical track has no intrinsic length.
+        "data-[orientation=vertical]:h-full data-[orientation=vertical]:w-5 data-[orientation=vertical]:justify-center",
+        className
+      ),
+      ...props
+    }
+  );
+}
+function SliderTrack({ className, ...props }) {
+  return /* @__PURE__ */ jsx(
+    Base.Track,
+    {
+      className: cn("h-1.5 w-full rounded-full bg-secondary data-[orientation=vertical]:h-full data-[orientation=vertical]:w-1.5", className),
+      ...props
+    }
+  );
+}
+function SliderIndicator({ className, ...props }) {
+  return /* @__PURE__ */ jsx(
+    Base.Indicator,
+    {
+      className: cn("h-full rounded-full bg-primary data-[orientation=vertical]:w-full", className),
+      ...props
+    }
+  );
+}
+function SliderThumb({ className, children, ...props }) {
+  return /* @__PURE__ */ jsxs(
+    Base.Thumb,
+    {
+      className: cn(
+        // The hit target: fixed box, no paint, no transform. Never resize this.
+        "group/thumb size-4 rounded-full motion-interactive",
+        "has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-ring",
+        "data-[disabled]:pointer-events-none",
+        className
+      ),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx(
+          "span",
+          {
+            "aria-hidden": true,
+            className: cn(
+              "pointer-events-none absolute inset-0 rounded-full border-2 border-primary bg-background shadow-(--knob-shadow)",
+              // The only thing that resizes. Scale (not width/height) so the box
+              // metrics — and the row height around them — never move.
+              "scale-75 motion-interactive ease-spring",
+              "group-hover/thumb:scale-100 group-has-[:focus-visible]/thumb:scale-100",
+              "group-data-[dragging]/thumb:scale-110"
+            )
+          }
+        ),
+        children
+      ]
+    }
+  );
+}
+function Slider({
+  className,
+  "aria-label": ariaLabel,
+  getAriaLabel,
+  getAriaValueText,
+  ...props
+}) {
+  const current = props.value ?? props.defaultValue;
+  const thumbCount = Array.isArray(current) ? current.length : 1;
+  const range = thumbCount > 1;
+  return /* @__PURE__ */ jsx(
+    Base.Root,
+    {
+      className: cn("w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-auto", className),
+      "aria-label": range ? ariaLabel : void 0,
+      ...props,
+      children: /* @__PURE__ */ jsx(SliderControl, { children: /* @__PURE__ */ jsxs(SliderTrack, { children: [
+        /* @__PURE__ */ jsx(SliderIndicator, {}),
+        Array.from({ length: thumbCount }, (_, i) => /* @__PURE__ */ jsx(
+          SliderThumb,
+          {
+            index: range ? i : void 0,
+            "aria-label": ariaLabel,
+            getAriaLabel,
+            getAriaValueText
+          },
+          i
+        ))
+      ] }) })
+    }
+  );
+}
+Slider.displayName = "Slider";
+export {
+  Slider,
+  SliderControl,
+  SliderIndicator,
+  SliderRoot,
+  SliderThumb,
+  SliderTrack,
+  SliderValue
+};

package/dist/components/slider/slider.meta.js

@@ -0,0 +1,214 @@
+// src/components/slider/slider.meta.ts
+var sliderMeta = {
+  name: "Slider",
+  summary: "Slider over Base UI Slider \u2014 pointer + keyboard control, ARIA slider wiring, and range support via multiple thumbs. The default export composes Root + Control + Track + Indicator + Thumb; pass an array value for a range.",
+  status: "stable",
+  keywords: [
+    "slider",
+    "range",
+    "value",
+    "input"
+  ],
+  usage: {
+    description: "Use Slider for bounded numeric choices where approximate adjustment is faster than typing.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use visible labels, min/max context, and value output when precision matters."
+      },
+      {
+        guidance: "do",
+        description: "Choose steps that match the real granularity of the setting."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use Slider when users must enter an exact arbitrary number; use NumberField."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it without showing the value. A slider with no numeric readout makes any precise choice guesswork \u2014 pair it with a ScrubField or a NumberField."
+      },
+      {
+        guidance: "dont",
+        description: "Do not resize the thumb's box on hover, focus, or drag. The thumb is a fixed-size hit target wrapping a decorative dot; only the dot scales. A target that grows under the cursor is a target nobody can learn, and WCAG 2.5.8 measures target size at rest. Restyle the dot, not the box."
+      }
+    ],
+    anatomy: [
+      {
+        name: "SliderRoot",
+        required: true,
+        description: "The controlled slider wrapper."
+      },
+      {
+        name: "SliderControl",
+        required: true,
+        description: "The interactive slider control region."
+      },
+      {
+        name: "SliderTrack",
+        required: true,
+        description: "The visible value range."
+      },
+      {
+        name: "SliderIndicator",
+        required: false,
+        description: "The filled portion of the track."
+      },
+      {
+        name: "SliderThumb",
+        required: true,
+        description: "The draggable handle."
+      },
+      {
+        name: "SliderValue",
+        required: false,
+        description: "A readable value display."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "NumberField",
+      "Progress"
+    ]
+  },
+  props: [
+    {
+      name: "value",
+      type: "number | number[]",
+      default: "\u2014",
+      description: "Controlled value. An array renders a range slider with one thumb per entry."
+    },
+    {
+      name: "defaultValue",
+      type: "number | number[]",
+      default: "\u2014",
+      description: "Uncontrolled initial value. An array renders a range slider."
+    },
+    {
+      name: "onValueChange",
+      type: "(value, eventDetails) => void",
+      default: "\u2014",
+      description: "Fires on every value change. value is a number (or number[] for a range)."
+    },
+    {
+      name: "min",
+      type: "number",
+      default: "0",
+      description: "Minimum allowed value."
+    },
+    {
+      name: "max",
+      type: "number",
+      default: "100",
+      description: "Maximum allowed value."
+    },
+    {
+      name: "step",
+      type: "number",
+      default: "1",
+      description: "Granularity the slider steps through. Snaps to multiples."
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      default: "false",
+      description: "Ignore user interaction and dim the control."
+    },
+    {
+      name: "orientation",
+      type: "'horizontal' | 'vertical'",
+      default: "horizontal",
+      description: "Axis the slider tracks along. A vertical slider has no intrinsic length \u2014 give it a height (h-40, or flex-1 in a column)."
+    },
+    {
+      name: "aria-label",
+      type: "string",
+      default: "\u2014",
+      description: "Accessible name, applied to each thumb's input (the element with role=slider). A range also names its group with it."
+    },
+    {
+      name: "getAriaLabel",
+      type: "(index) => string",
+      default: "\u2014",
+      description: 'Per-thumb name for a range ("Minimum price" / "Maximum price"). Wins over aria-label on the thumbs.'
+    },
+    {
+      name: "getAriaValueText",
+      type: "(formattedValue, value, index) => string",
+      default: "\u2014",
+      description: 'What a screen reader announces for the value when the number alone is wrong \u2014 a seek bar\'s "1:23 of 3:45". For units or percent, `format` (Intl.NumberFormatOptions) is enough.'
+    }
+  ],
+  subcomponents: [
+    {
+      name: "SliderRoot",
+      type: "Base UI Slider.Root props",
+      description: "The unstyled Base UI Root for custom composition \u2014 owns the value state and forwards value / defaultValue / onValueChange / min / max / step. Drag state surfaces via data-[dragging]. The default Slider export wires all the parts for you."
+    },
+    {
+      name: "SliderControl",
+      type: "Base UI Control props + className",
+      description: "The interactive track lane \u2014 the positioning context the indicator and thumbs sit in; dims when disabled."
+    },
+    {
+      name: "SliderTrack",
+      type: "Base UI Track props + className",
+      description: "The full-range rail beneath the indicator."
+    },
+    {
+      name: "SliderIndicator",
+      type: "Base UI Indicator props + className",
+      description: "The filled portion from min (or the lower thumb) to the current value."
+    },
+    {
+      name: "SliderThumb",
+      type: "Base UI Thumb props + className",
+      description: "A draggable handle: a fixed-size hit target wrapping a decorative dot. The dot rests small and scales to full size on hover, keyboard focus, and drag; the box never changes, so row metrics and the tap target hold. Range sliders render one per value; pass index for SSR. Interaction state surfaces via data-[dragging]."
+    },
+    {
+      name: "SliderValue",
+      type: "Base UI Value props",
+      description: "Formatted value readout for custom compositions (e.g. a live number beside the control)."
+    }
+  ],
+  tokensUsed: ["secondary", "primary", "background", "ring"],
+  a11y: [
+    "Base UI provides role=slider, aria-valuemin/max/now, and arrow-key / Page Up-Down / Home-End control.",
+    "Each thumb is a focusable input[type=range] nested in the thumb element; keyboard focus raises a 2px ring on the thumb via has-[:focus-visible] (a bare focus-visible: on the thumb never fires, since the div itself is not focusable).",
+    "The thumb's hit area is a fixed 16px box at every state. Only the decorative inner dot resizes \u2014 rest 12px, full 16px on hover, keyboard focus, and drag \u2014 so the target a pointer or finger must land on never moves or changes size. Keyboard users, who never hover, get the enlarged dot from focus-visible.",
+    "The rest-to-full transition uses the motion duration/easing tokens, so it collapses to an instant state change under prefers-reduced-motion or MotionProvider off. The size change itself still happens: it reports interaction state, it is not decoration.",
+    "Range sliders get one thumb per value with minStepsBetweenValues honored.",
+    "Pass aria-label (or getAriaLabel for a range) so each handle has an accessible name. On Slider it reaches the thumb inputs; on a bare SliderRoot it only names the role=group \u2014 when composing, put aria-label / getAriaLabel on each SliderThumb, or label the Root with aria-labelledby or a Field, which Base UI does carry to the thumbs.",
+    "getAriaValueText sets aria-valuetext for values a number misreads (time, named steps)."
+  ],
+  examples: [
+    {
+      label: "Single value",
+      code: '<Slider defaultValue={50} aria-label="Volume" />'
+    },
+    {
+      label: "Range",
+      code: 'const [range, setRange] = useState([20, 60])\n<Slider value={range} onValueChange={setRange} aria-label="Price range" getAriaLabel={(i) => (i ? "Maximum price" : "Minimum price")} />'
+    },
+    {
+      label: "Seek bar with spoken time",
+      code: '<Slider value={position} max={duration} onValueChange={seek} aria-label="Seek" getAriaValueText={(_, v) => `${formatTime(v)} of ${formatTime(duration)}`} />'
+    },
+    {
+      label: "Stepped",
+      code: "<Slider defaultValue={40} min={0} max={100} step={10} />"
+    },
+    {
+      label: "Vertical",
+      code: '<div className="h-40"><Slider orientation="vertical" defaultValue={40} aria-label="Level" /></div>'
+    },
+    {
+      label: "Composed with a value readout",
+      code: '<Field label="Volume"><SliderRoot defaultValue={40} className="flex items-center gap-3"><SliderControl><SliderTrack><SliderIndicator /><SliderThumb /></SliderTrack></SliderControl><SliderValue className="text-mono-sm" /></SliderRoot></Field>'
+    }
+  ]
+};
+export {
+  sliderMeta
+};

package/dist/components/sparkline/index.js

@@ -0,0 +1,7 @@
+// src/components/sparkline/index.ts
+import { Sparkline } from "./sparkline.js";
+import { sparklineMeta } from "./sparkline.meta.js";
+export {
+  Sparkline,
+  sparklineMeta
+};

package/dist/components/sparkline/sparkline.js

@@ -0,0 +1,84 @@
+"use client";
+
+// src/components/sparkline/sparkline.tsx
+import { areaPath, linePath } from "../../lib/chart/geometry.js";
+import { drawTransition, riseTransition, stagger } from "../../lib/chart/motion.js";
+import { toneColor } from "../../lib/chart/types.js";
+import { cn } from "../../lib/cn.js";
+import { useMotion } from "../../motion/MotionProvider.js";
+import { useArrival } from "../../lib/chart/use-arrival.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var W = 100;
+var H = 32;
+function Sparkline({ data, label, variant = "line", tone = "primary", animate = true, locale, className, ...props }) {
+  const { enabled } = useMotion();
+  const [ref, inView] = useArrival();
+  const shown = !animate || !enabled || inView;
+  const color = toneColor(tone);
+  const min = data.length ? Math.min(...data) : 0;
+  const max = data.length ? Math.max(...data) : 1;
+  const [lo, hi] = variant === "bar" ? [Math.min(0, min), Math.max(max, Math.min(0, min) + 1)] : min === max ? [min - 1, max + 1] : [min, max];
+  const y = (v) => H - 2 - (v - lo) / (hi - lo) * (H - 4);
+  const nf = new Intl.NumberFormat(locale, { maximumFractionDigits: 2 });
+  const summary = data.length ? `${label}: from ${nf.format(data[0])} to ${nf.format(data[data.length - 1])}, low ${nf.format(Math.min(...data))}, high ${nf.format(Math.max(...data))}` : label;
+  let marks = null;
+  if (variant === "bar") {
+    const step = W / Math.max(1, data.length);
+    marks = data.map((v, i) => /* @__PURE__ */ jsx(
+      "rect",
+      {
+        x: i * step + step * 0.15,
+        width: step * 0.7,
+        y: Math.min(y(v), y(0)),
+        height: Math.max(0.5, Math.abs(y(0) - y(v))),
+        className: "[[data-reveal=out]_&]:scale-y-0",
+        style: { fill: color, transformOrigin: `0px ${y(0)}px`, transition: riseTransition(stagger(i, 20)) }
+      },
+      i
+    ));
+  } else {
+    const pts = data.map((v, i) => [data.length > 1 ? i / (data.length - 1) * W : W / 2, y(v)]);
+    marks = /* @__PURE__ */ jsxs(Fragment, { children: [
+      variant === "area" ? /* @__PURE__ */ jsx(
+        "path",
+        {
+          d: areaPath(pts, pts.map(([x]) => [x, H])),
+          className: "[[data-reveal=out]_&]:opacity-0",
+          style: { fill: color, fillOpacity: 0.16, transition: riseTransition("var(--motion-duration-slow)") }
+        }
+      ) : null,
+      /* @__PURE__ */ jsx(
+        "path",
+        {
+          d: linePath(pts),
+          pathLength: 1,
+          fill: "none",
+          strokeWidth: 1.5,
+          strokeLinecap: "round",
+          strokeLinejoin: "round",
+          vectorEffect: "non-scaling-stroke",
+          className: "[stroke-dasharray:1] [stroke-dashoffset:0] [[data-reveal=out]_&]:[stroke-dashoffset:1]",
+          style: { stroke: color, transition: drawTransition() }
+        }
+      )
+    ] });
+  }
+  return /* @__PURE__ */ jsx(
+    "svg",
+    {
+      ref,
+      role: "img",
+      "aria-label": summary,
+      viewBox: `0 0 ${W} ${H}`,
+      preserveAspectRatio: "none",
+      "data-reveal": shown ? "in" : "out",
+      className: cn("inline-block h-8 w-24 shrink-0 overflow-visible align-middle", className),
+      ...props,
+      children: marks
+    }
+  );
+}
+Sparkline.displayName = "Sparkline";
+export {
+  Sparkline
+};