@sableui/react 0.6.2 → 0.7.1

package/dist/components/sparkline/sparkline.meta.js

@@ -0,0 +1,147 @@
+// src/components/sparkline/sparkline.meta.ts
+var sparklineMeta = {
+  name: "Sparkline",
+  summary: "A word-sized trend with no axes \u2014 a line, a line over a soft fill, or columns \u2014 sized by its container, for stat cards, table cells and sentences. Draws on as it scrolls into view.",
+  keywords: [
+    "sparkline",
+    "trend",
+    "mini chart",
+    "inline chart",
+    "micro chart",
+    "kpi",
+    "stat"
+  ],
+  usage: {
+    description: "Use Sparkline next to a number to show where it has been \u2014 a KPI's last 30 days in a stat card, a row's trend in a table. It has no axes, tooltip or values to read off; when the reader needs those, use AreaChart or LineChart.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Pair it with the current value and its change in text; the sparkline shows only the shape."
+      },
+      {
+        guidance: "do",
+        description: "Give it a label that names the measure and the period \u2014 the spoken summary adds the range and latest value."
+      },
+      {
+        guidance: "dont",
+        description: "Put two sparklines on one shared axis to compare them \u2014 each scales to its own data; use LineChart."
+      },
+      {
+        guidance: "dont",
+        description: "Use it as the only place a number appears; a shape without a value cannot be read off."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "AreaChart",
+      "LineChart",
+      "Card",
+      "Table"
+    ]
+  },
+  status: "beta",
+  props: [
+    {
+      name: "data",
+      type: "number[]",
+      description: "The values, oldest first."
+    },
+    {
+      name: "label",
+      type: "string",
+      description: 'What the line tracks ("Revenue, last 30 days"). The spoken summary adds the first and last values, low and high.'
+    },
+    {
+      name: "variant",
+      type: '"line" | "area" | "bar"',
+      default: '"line"',
+      description: "A line, a line over a soft fill, or columns."
+    },
+    {
+      name: "tone",
+      type: '"edition" | "collectible" | "standard" | "info" | "warning" | "primary" | "neutral" | "success" | "destructive"',
+      default: '"primary"',
+      description: "Colour by role."
+    },
+    {
+      name: "className",
+      type: "string",
+      default: '"h-8 w-24"',
+      description: "Sizes it; the drawing stretches to fit."
+    },
+    {
+      name: "animate",
+      type: "boolean",
+      default: "true",
+      description: "Draw on (or rise) when it scrolls into view."
+    },
+    {
+      name: "locale",
+      type: "string",
+      default: "runtime locale",
+      description: "BCP 47 locale for default number and date formatting."
+    }
+  ],
+  variants: {
+    variant: [
+      "line",
+      "area",
+      "bar"
+    ]
+  },
+  tokensUsed: [
+    "primary",
+    "tone-edition",
+    "tone-collectible",
+    "tone-standard",
+    "tone-info",
+    "tone-warning",
+    "muted-foreground",
+    "success",
+    "destructive"
+  ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "custom",
+      part: "Line / bars",
+      why: "Once on screen the line draws on (or the bars rise, in sequence). On the motion tokens; reduced motion shows the finished drawing."
+    },
+    {
+      slot: "response",
+      recipe: "none",
+      part: "Sparkline",
+      why: "Not interactive: it has no tooltip or focus."
+    },
+    {
+      slot: "transition",
+      recipe: "none",
+      part: "Sparkline",
+      why: "New data redraws in place; a word-sized chart animating on every update would distract from the number beside it."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Sparkline",
+      why: "No indeterminate state."
+    }
+  ],
+  a11y: [
+    'Rendered role=img with an aria-label built from `label` and the data: "Revenue, last 30 days: from 120 to 184, low 96, high 190".',
+    "It is not focusable and has no tooltip, so the number it accompanies must be in text beside it."
+  ],
+  examples: [
+    {
+      label: "In a stat card",
+      code: '<Card>\n	<CardHeader>\n		<CardDescription>Revenue</CardDescription>\n		<CardTitle className="text-mono-xl">$18,240</CardTitle>\n		<CardAction>\n			<Sparkline label="Revenue, last 12 weeks" data={[12, 14, 13, 17, 16, 19, 18, 21, 20, 24, 23, 26]} variant="area" tone="success" />\n		</CardAction>\n	</CardHeader>\n</Card>'
+    },
+    {
+      label: "Columns in a table cell",
+      code: '<Sparkline label="Daily signups, last 14 days" data={[4, 6, 3, 8, 7, 9, 5, 6, 10, 8, 7, 11, 9, 12]} variant="bar" className="h-6 w-20" />'
+    }
+  ]
+};
+export {
+  sparklineMeta
+};

package/dist/components/spinner/index.js

@@ -0,0 +1,7 @@
+// src/components/spinner/index.ts
+import { Spinner } from "./spinner.js";
+import { spinnerMeta } from "./spinner.meta.js";
+export {
+  Spinner,
+  spinnerMeta
+};

package/dist/components/spinner/spinner.js

@@ -0,0 +1,59 @@
+// src/components/spinner/spinner.tsx
+import { cn } from "../../lib/cn.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var RING_SIZE = { sm: "size-3.5", md: "size-4", lg: "size-6" };
+var DOT_SIZE = { sm: "size-1", md: "size-1.5", lg: "size-2" };
+var DOT_DELAYS = ["0ms", "150ms", "300ms"];
+function Spinner({ label = "Loading", appearance = "ring", size = "md", thickness = 2.5, className, ref, ...props }) {
+  if (appearance === "dots") {
+    return /* @__PURE__ */ jsx("span", { ref, role: "status", "aria-label": label, className: cn("inline-flex items-center gap-1", className), ...props, children: DOT_DELAYS.map((delay) => /* @__PURE__ */ jsx("span", { className: cn("shrink-0 rounded-full bg-current motion-dot-bounce", DOT_SIZE[size]), style: { animationDelay: delay } }, delay)) });
+  }
+  return /* @__PURE__ */ jsx(
+    "span",
+    {
+      ref,
+      role: "status",
+      "aria-label": label,
+      className: cn("inline-flex items-center justify-center", RING_SIZE[size], className),
+      ...props,
+      children: /* @__PURE__ */ jsxs(
+        "svg",
+        {
+          viewBox: "0 0 24 24",
+          fill: "none",
+          "aria-hidden": "true",
+          className: "size-full motion-spin",
+          children: [
+            /* @__PURE__ */ jsx(
+              "circle",
+              {
+                cx: "12",
+                cy: "12",
+                r: "9",
+                stroke: "currentColor",
+                strokeWidth: thickness,
+                className: "opacity-20"
+              }
+            ),
+            /* @__PURE__ */ jsx(
+              "circle",
+              {
+                cx: "12",
+                cy: "12",
+                r: "9",
+                stroke: "currentColor",
+                strokeWidth: thickness,
+                strokeLinecap: "round",
+                strokeDasharray: "15 42"
+              }
+            )
+          ]
+        }
+      )
+    }
+  );
+}
+Spinner.displayName = "Spinner";
+export {
+  Spinner
+};

package/dist/components/spinner/spinner.meta.js

@@ -0,0 +1,118 @@
+// src/components/spinner/spinner.meta.ts
+var spinnerMeta = {
+  name: "Spinner",
+  summary: "Pure SVG activity indicator. No Base UI, no icon dependency \u2014 a role=status ring (faint track + rounded-cap arc) that inherits the current text color. Size with the size prop (sm / md / lg), color with text-*.",
+  status: "stable",
+  keywords: [
+    "spinner",
+    "loading",
+    "pending",
+    "indeterminate"
+  ],
+  usage: {
+    description: "Use Spinner for short indeterminate waits where the user cannot know exact progress.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it in compact panels or places where layout is already stable. In a button, use Button's loading prop rather than placing a Spinner by hand \u2014 it disables the button, sets aria-busy and sizes the spinner to the button's icon."
+      },
+      {
+        guidance: "do",
+        description: "Pair it with accessible loading text when the surrounding label is not enough."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use Spinner as the only content for long waits or full page loading."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it without an accessible name or a nearby status message. A spinning icon is invisible to a screen reader, so the wait is announced as nothing at all."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Skeleton",
+      "Progress"
+    ]
+  },
+  props: [
+    {
+      name: "label",
+      type: "string",
+      default: '"Loading"',
+      description: "Accessible label announced by screen readers while visible (sets aria-label on the role=status element)."
+    },
+    {
+      name: "appearance",
+      type: '"ring" | "dots"',
+      default: '"ring"',
+      description: "ring is the default indicator; dots are three bouncing dots, softer, for chat and inline text."
+    },
+    {
+      name: "size",
+      type: '"sm" | "md" | "lg"',
+      default: '"md"',
+      description: "One scale for both appearances: ring 14 / 16 / 24px, dots 4 / 6 / 8px."
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Color (text-*); the ring's strokes use currentColor, so it follows the text color. Size with the size prop \u2014 a size-* class still overrides the ring for an off-scale context (Button sizes its own spinner this way), but is not the way to pick a size."
+    }
+  ],
+  tokensUsed: ["foreground", "muted-foreground", "primary-foreground"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "A spinner already signals a wait. Fading it in delays the signal for exactly as long as the user most needs it."
+    },
+    {
+      slot: "response",
+      recipe: "none",
+      part: "Root",
+      why: "It is a status indicator, not a control."
+    },
+    {
+      slot: "transition",
+      recipe: "none",
+      part: "Root",
+      why: "One state. Whatever replaces it on completion owns that change."
+    },
+    {
+      slot: "activity",
+      recipe: "motion-spin",
+      part: "Root",
+      why: "The rotation is the whole component \u2014 it is the only thing distinguishing 'working' from 'frozen'. motion-spin rather than Tailwind's animate-spin because the built-in ignores --motion-scale, so the reduced-motion policy cannot freeze it."
+    }
+  ],
+  a11y: [
+    "Wrapped in role=status, a polite live region, with an aria-label (default 'Loading').",
+    "Color comes from currentColor; pair with a text-* token for adequate contrast.",
+    "Spins with the motion-spin utility, which follows --motion-scale, so it slows and stops with the motion setting and reduced-motion."
+  ],
+  variants: {
+    appearance: ["ring", "dots"],
+    size: ["sm", "md", "lg"]
+  },
+  examples: [
+    {
+      label: "Dots",
+      code: '<Spinner appearance="dots" label="Assistant is typing" className="text-muted-foreground" />'
+    },
+    { label: "Default", code: "<Spinner />" },
+    {
+      label: "Sized + tinted",
+      code: '<Spinner size="lg" className="text-muted-foreground" />'
+    },
+    {
+      label: "Inside a button (Button owns it \u2014 use loading)",
+      code: "<Button loading>Collecting</Button>"
+    }
+  ]
+};
+export {
+  spinnerMeta
+};

package/dist/components/status-bar/index.js

@@ -0,0 +1,9 @@
+// src/components/status-bar/index.ts
+import { StatusBar, StatusBarGroup, StatusBarSeparator } from "./status-bar.js";
+import { statusBarMeta } from "./status-bar.meta.js";
+export {
+  StatusBar,
+  StatusBarGroup,
+  StatusBarSeparator,
+  statusBarMeta
+};

package/dist/components/status-bar/status-bar.js

@@ -0,0 +1,40 @@
+"use client";
+
+// src/components/status-bar/status-bar.tsx
+import { cn } from "../../lib/cn.js";
+import { jsx } from "react/jsx-runtime";
+function StatusBar({ className, children, ...props }) {
+  return /* @__PURE__ */ jsx(
+    "footer",
+    {
+      className: cn(
+        "flex h-(--status-bar-height) shrink-0 items-center gap-3 border-t border-hairline bg-panel px-2",
+        "text-ui-micro text-muted-foreground",
+        className
+      ),
+      ...props,
+      children
+    }
+  );
+}
+StatusBar.displayName = "StatusBar";
+function StatusBarGroup({ align = "start", className, children, ...props }) {
+  return /* @__PURE__ */ jsx(
+    "span",
+    {
+      className: cn("flex items-center gap-3", align === "end" && "ms-auto", className),
+      ...props,
+      children
+    }
+  );
+}
+StatusBarGroup.displayName = "StatusBarGroup";
+function StatusBarSeparator({ className, ...props }) {
+  return /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: cn("text-hairline-strong", className), ...props, children: "\xB7" });
+}
+StatusBarSeparator.displayName = "StatusBarSeparator";
+export {
+  StatusBar,
+  StatusBarGroup,
+  StatusBarSeparator
+};

package/dist/components/status-bar/status-bar.meta.js

@@ -0,0 +1,117 @@
+// src/components/status-bar/status-bar.meta.ts
+var statusBarMeta = {
+  name: "StatusBar",
+  summary: "The bottom chrome strip of a Workspace: ambient document facts \u2014 dimensions, counts, sync state \u2014 in the micro type tier.",
+  keywords: [
+    "status bar",
+    "status",
+    "footer",
+    "chrome",
+    "workspace",
+    "tool",
+    "ambient",
+    "counts",
+    "document"
+  ],
+  usage: {
+    description: "Use StatusBar for the persistent facts about a document that otherwise have nowhere to live: size, counts, selection state, sync or connection status. Everything in it is ambient \u2014 it reports, it does not command. Pair it with Workspace's statusBar slot.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Put document-scoped facts here \u2014 dimensions, layer or record counts, saved/sync state \u2014 so panels stop competing for that space."
+      },
+      {
+        guidance: "do",
+        description: 'Use StatusBarGroup with align="end" for the trailing cluster, and StatusBarSeparator between related facts.'
+      },
+      {
+        guidance: "do",
+        description: "Render numeric facts in the UI num tier so a changing value doesn't shift the strip's layout."
+      },
+      {
+        guidance: "dont",
+        description: "Make it the only route to an action. It's ambient chrome at the micro tier \u2014 anything essential needs a real control elsewhere too."
+      },
+      {
+        guidance: "dont",
+        description: "Put zoom here. Anchor zoom to the canvas it acts on, which is where every reference tool puts it."
+      },
+      {
+        guidance: "dont",
+        description: "Use it for transient feedback like a save confirmation \u2014 that's Toast. A status bar states what is true, not what just happened."
+      },
+      {
+        guidance: "dont",
+        description: "Derive a fact here separately from the surface that shows it, or from something expensive to recompute. The strip re-renders with the document, so read the same value the canvas or panel uses: a status bar that reports max(asset sizes) while the canvas reports something else is a bug types cannot catch, because both are numbers."
+      }
+    ],
+    anatomy: [
+      {
+        name: "StatusBarGroup",
+        required: false,
+        description: 'A cluster of items; align="end" pins it to the trailing edge.'
+      },
+      {
+        name: "StatusBarSeparator",
+        required: false,
+        description: "A decorative dot between related facts; aria-hidden."
+      }
+    ]
+  },
+  related: {
+    components: ["Workspace", "PanelGroup", "InlineStatus", "Toast", "Banner"]
+  },
+  status: "stable",
+  props: [],
+  subcomponents: [
+    {
+      name: "StatusBarGroup",
+      type: "{ align?: 'start' | 'end' }",
+      description: "A cluster of status items; `end` pushes it to the trailing edge."
+    },
+    {
+      name: "StatusBarSeparator",
+      type: "ComponentProps<'span'>",
+      description: "A decorative middle dot between facts. aria-hidden, since order conveys grouping."
+    }
+  ],
+  a11y: [
+    "Renders a <footer>, so the strip is a discoverable region rather than an anonymous row of text.",
+    "Separators are aria-hidden \u2014 a screen reader announcing 'middle dot' between every fact is noise.",
+    "Micro-tier text is small by design; never put information here that exists nowhere else."
+  ],
+  tokensUsed: ["muted-foreground", "panel", "hairline", "hairline-strong"],
+  examples: [
+    {
+      label: "Document facts with a trailing cluster",
+      code: `<StatusBar>
+  <span className="text-ui-num">1024 \xD7 768</span>
+  <StatusBarSeparator />
+  <span>3 layers</span>
+  <StatusBarGroup align="end">
+    <span>Saved</span>
+  </StatusBarGroup>
+</StatusBar>`
+    },
+    {
+      label: "With a warning tone",
+      code: `<StatusBar>
+  <span>Offline \u2014 edits are queued</span>
+  <StatusBarGroup align="end">
+    <span className="text-tone-warning">2 unsynced</span>
+  </StatusBarGroup>
+</StatusBar>`
+    },
+    {
+      label: "In a Workspace",
+      code: `<Workspace statusBar={<StatusBar><span>Connected</span></StatusBar>}>
+  <PanelGroup>
+    <WorkspaceCanvas />
+  </PanelGroup>
+</Workspace>`
+    }
+  ]
+};
+export {
+  statusBarMeta
+};

package/dist/components/status-dot/index.js

@@ -0,0 +1,9 @@
+// src/components/status-dot/index.ts
+import { StatusDot } from "./status-dot.js";
+import { statusDotVariants } from "./status-dot.variants.js";
+import { statusDotMeta } from "./status-dot.meta.js";
+export {
+  StatusDot,
+  statusDotMeta,
+  statusDotVariants
+};

package/dist/components/status-dot/status-dot.js

@@ -0,0 +1,40 @@
+// src/components/status-dot/status-dot.tsx
+import { cn } from "../../lib/cn.js";
+import { statusDotVariants } from "./status-dot.variants.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function StatusDot({
+  tone,
+  size,
+  pulse = false,
+  className,
+  ...props
+}) {
+  const dot = statusDotVariants({ tone, size });
+  if (pulse) {
+    return /* @__PURE__ */ jsxs(
+      "span",
+      {
+        "aria-hidden": "true",
+        className: cn("relative inline-flex shrink-0", className),
+        ...props,
+        children: [
+          /* @__PURE__ */ jsx(
+            "span",
+            {
+              className: cn(
+                dot,
+                "absolute inset-0 motion-ping opacity-75"
+              )
+            }
+          ),
+          /* @__PURE__ */ jsx("span", { className: cn(dot, "relative") })
+        ]
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx("span", { "aria-hidden": "true", className: cn(dot, className), ...props });
+}
+StatusDot.displayName = "StatusDot";
+export {
+  StatusDot
+};

package/dist/components/status-dot/status-dot.meta.js

@@ -0,0 +1,113 @@
+// src/components/status-dot/status-dot.meta.ts
+var statusDotMeta = {
+  name: "StatusDot",
+  summary: "A small colored status dot. Tone variants encode state via semantic tone tokens; sizes scale the diameter. Decorative (aria-hidden) \u2014 pair with text. Optional pulse adds a live ping ring.",
+  keywords: [
+    "status",
+    "dot",
+    "presence",
+    "health",
+    "state",
+    "online",
+    "live",
+    "indicator"
+  ],
+  usage: {
+    description: 'Use StatusDot as a compact visual state cue next to text, avatars, rows, or labels. It is decorative by design, so pair it with visible text or use `<Badge appearance="plain" dot>` when the label and dot should travel together \u2014 that is the labelled status line, not a hand-built row.',
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Place StatusDot beside a readable state label, person name, or row title."
+      },
+      {
+        guidance: "do",
+        description: "Use pulse only for live or in-progress states that are actively changing."
+      },
+      {
+        guidance: "dont",
+        description: "Use the dot as the only status indicator; it is aria-hidden and color alone is not enough."
+      },
+      {
+        guidance: "dont",
+        description: "Mix many dot sizes in the same list. Keep row indicators visually consistent."
+      }
+    ],
+    anatomy: [
+      {
+        name: "Dot",
+        required: true,
+        description: "The small tone-colored circle. It is decorative and hidden from assistive tech."
+      },
+      {
+        name: "Pulse ring",
+        required: false,
+        description: "Optional motion ring for in-progress or live states."
+      }
+    ]
+  },
+  related: {
+    components: ["Badge", "Avatar", "InlineStatus"],
+    patterns: ["DashboardPage", "ListDetailPage"]
+  },
+  status: "stable",
+  props: [
+    {
+      name: "tone",
+      type: '"neutral" | "standard" | "success" | "warning" | "info" | "edition" | "collectible" | "destructive"',
+      default: '"neutral"',
+      description: "Semantic color of the dot."
+    },
+    {
+      name: "size",
+      type: '"sm" | "md" | "lg"',
+      default: '"md"',
+      description: "Dot diameter."
+    },
+    {
+      name: "pulse",
+      type: "boolean",
+      default: "false",
+      description: "Wrap the dot in an animated ping ring to signal a live state."
+    }
+  ],
+  variants: {
+    tone: [
+      "neutral",
+      "standard",
+      "success",
+      "warning",
+      "info",
+      "edition",
+      "collectible",
+      "destructive"
+    ],
+    size: ["sm", "md", "lg"]
+  },
+  tokensUsed: [
+    "muted-foreground",
+    "tone-standard",
+    "success",
+    "tone-warning",
+    "tone-info",
+    "tone-edition",
+    "tone-collectible",
+    "destructive"
+  ],
+  a11y: [
+    "Rendered aria-hidden \u2014 purely decorative. Convey status in adjacent text, not color alone.",
+    "A dot conveys state through colour alone, which fails for colour-blind users and announces as nothing. It must always sit beside text that states the same thing, or carry its own accessible name."
+  ],
+  examples: [
+    {
+      label: "Tones",
+      code: '<Row gap={2}><StatusDot tone="standard" /><StatusDot tone="info" /><StatusDot tone="warning" /><StatusDot tone="destructive" /></Row>'
+    },
+    {
+      label: "With label \u2014 use Badge",
+      code: '<Badge appearance="plain" tone="success" dot pulse>Live</Badge>'
+    }
+  ]
+};
+export {
+  statusDotMeta
+};