@sableui/react 0.6.2 → 0.7.1

package/dist/components/radial-chart/radial-chart.meta.js

@@ -0,0 +1,216 @@
+// src/components/radial-chart/radial-chart.meta.ts
+var radialChartMeta = {
+  name: "RadialChart",
+  summary: "Progress or share as rings: one ring per row against a muted track, a full circle or a gauge (`sweep`), one ring split between rows (`stacked`), ring labels and a value in the middle. Rings draw round as the chart scrolls into view.",
+  keywords: [
+    "chart",
+    "radial",
+    "ring",
+    "gauge",
+    "progress",
+    "goal",
+    "score",
+    "activity rings",
+    "donut"
+  ],
+  usage: {
+    description: "Use RadialChart for progress toward goals (several rings), a single score or usage gauge (`sweep={180}` with `centerLabel`), or a split of one total along a gauge (`stacked`). For one reading in a form or settings row, Meter's ring shape is lighter.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: 'Set max to the goal, so a full ring means "done".'
+      },
+      {
+        guidance: "do",
+        description: "Pair a gauge with centerLabel stating the value in words or units."
+      },
+      {
+        guidance: "dont",
+        description: "Compare more than four rings \u2014 inner rings are shorter for the same value, which misleads; use BarChart."
+      },
+      {
+        guidance: "dont",
+        description: "Use it for data-heavy views \u2014 streaming or real-time data, thousands of points, zoom and brushing, trading charts. Those belong on a charting library (Recharts, visx, ECharts); Sable's charts are for dashboards, landing pages and decks."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Meter",
+      "PieChart",
+      "Progress",
+      "Card"
+    ]
+  },
+  status: "beta",
+  props: [
+    {
+      name: "data",
+      type: "Record<string, unknown>[]",
+      description: "One row per ring, outermost first."
+    },
+    {
+      name: "index",
+      type: "string",
+      description: "The datum field naming each ring."
+    },
+    {
+      name: "valueKey",
+      type: "string",
+      description: "The datum field holding each ring's amount."
+    },
+    {
+      name: "label",
+      type: "string",
+      description: "What the chart shows. Its accessible name and the caption of the data table assistive tech reads."
+    },
+    {
+      name: "categories",
+      type: "Record<string, { label?: string; tone?: ChartTone; color?: string; icon?: string }>",
+      description: "Labels, tones and icons per ring, keyed by the ring's name."
+    },
+    {
+      name: "className",
+      type: "string",
+      default: '"h-64"',
+      description: "Sizes the chart. Set a height."
+    },
+    {
+      name: "max",
+      type: "number",
+      default: "the largest value (stacked: the total; labelled: the largest value \xF7 0.75, leaving room for the labels)",
+      description: "The value a full ring stands for."
+    },
+    {
+      name: "sweep",
+      type: "number",
+      default: "360",
+      description: "How far round a full ring runs, in degrees: 360 for a circle, 180 for a gauge."
+    },
+    {
+      name: "stacked",
+      type: "boolean",
+      default: "false",
+      description: "Split ONE ring between the rows instead of a ring each."
+    },
+    {
+      name: "track",
+      type: "boolean",
+      default: "true",
+      description: "Draw each ring's full track behind it."
+    },
+    {
+      name: "labels",
+      type: "boolean",
+      default: "false",
+      description: "Name each ring at its start."
+    },
+    {
+      name: "centerLabel",
+      type: "{ value: string | number; label?: string }",
+      description: 'A value and caption in the middle. On a full ring the value holds the centre and the caption hangs below it. A number is formatted for you: in full up to 9,999, compact from 10,000 (10.2K); pass a string for units ("7.2 GB", "72%").'
+    },
+    {
+      name: "legend",
+      type: "boolean",
+      default: "true unless rings are labelled",
+      description: "Show the legend."
+    },
+    {
+      name: "tooltip",
+      type: 'boolean | { indicator?: "dot" | "line" | "dashed" | "none"; hideLabel?: boolean; labelFormatter?: (label, datum) => ReactNode; showTotal?: boolean }',
+      default: "true",
+      description: "Show a tooltip on hover and keyboard focus, or configure it: the row marker, hiding the heading, rewriting it, adding a Total row."
+    },
+    {
+      name: "valueFormatter",
+      type: "(value: number) => string",
+      description: 'Format values everywhere (axis, labels, tooltip, table) \u2014 units like "$12,480". Default: compact on the axis, full elsewhere.'
+    },
+    {
+      name: "locale",
+      type: "string",
+      default: "runtime locale",
+      description: "BCP 47 locale for default number and date formatting."
+    },
+    {
+      name: "animate",
+      type: "boolean",
+      default: "true",
+      description: "Draw the rings round from their start when the chart scrolls into view."
+    },
+    {
+      name: "activeIndex",
+      type: "number | null",
+      description: "The highlighted row (controlled); `null` for none."
+    },
+    {
+      name: "defaultActiveIndex",
+      type: "number | null",
+      description: "The row highlighted at first \u2014 a tooltip already open before anyone hovers."
+    },
+    {
+      name: "onActiveIndexChange",
+      type: "(index: number | null) => void",
+      description: "Called as the pointer or keyboard moves between rows."
+    }
+  ],
+  tokensUsed: [
+    "tone-edition",
+    "tone-collectible",
+    "tone-standard",
+    "tone-info",
+    "tone-warning",
+    "primary",
+    "muted-foreground",
+    "border",
+    "popover",
+    "popover-foreground",
+    "foreground",
+    "background"
+  ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "custom",
+      part: "Ring",
+      why: "Once on screen each ring draws round from its start (stroke-dashoffset on a round-capped arc), staggered outside in. On the motion tokens; reduced motion shows the finished chart."
+    },
+    {
+      slot: "response",
+      recipe: "none",
+      part: "Active ring",
+      why: "The hovered ring stays full strength and the others dim at once."
+    },
+    {
+      slot: "transition",
+      recipe: "custom",
+      part: "Ring",
+      why: "Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "RadialChart",
+      why: "A chart has no indeterminate state; show a Skeleton while the data loads."
+    }
+  ],
+  a11y: [
+    "The drawing is aria-hidden; the same numbers are in a visually hidden data table (captioned by `label`) that the chart is aria-describedby, so assistive tech reads values, not shapes.",
+    'With a tooltip, the chart is one tab stop (role=group, aria-roledescription="chart"): arrow keys, Home and End step through the data, Escape clears, and each step is announced in a polite live region.',
+    "Colour is never the only key: series are named in the legend, tooltip and table."
+  ],
+  examples: [
+    {
+      label: "Goal rings",
+      code: '<RadialChart\n	label="Weekly goals"\n	data={[\n		{ goal: "Move", progress: 82 },\n		{ goal: "Exercise", progress: 64 },\n		{ goal: "Stand", progress: 91 },\n	]}\n	index="goal"\n	valueKey="progress"\n	max={100}\n	labels\n/>'
+    },
+    {
+      label: "Gauge with a value",
+      code: '<RadialChart\n	label="Plan usage"\n	data={[{ plan: "Used", gb: 7.2 }]}\n	index="plan"\n	valueKey="gb"\n	max={10}\n	sweep={180}\n	centerLabel={{ value: "7.2 GB", label: "of 10 GB" }}\n	legend={false}\n/>'
+    }
+  ]
+};
+export {
+  radialChartMeta
+};

package/dist/components/radio/index.js

@@ -0,0 +1,8 @@
+// src/components/radio/index.ts
+import { Radio, RadioGroup } from "./radio.js";
+import { radioMeta } from "./radio.meta.js";
+export {
+  Radio,
+  RadioGroup,
+  radioMeta
+};

package/dist/components/radio/radio.js

@@ -0,0 +1,39 @@
+// src/components/radio/radio.tsx
+import { Radio as RadioBase } from "@base-ui/react/radio";
+import { RadioGroup as RadioGroupBase } from "@base-ui/react/radio-group";
+import { cn } from "../../lib/cn.js";
+import { RADIO_DOT, RADIO_RING } from "../../lib/selection-card.js";
+import { jsx } from "react/jsx-runtime";
+function RadioGroup({ className, ...props }) {
+  return /* @__PURE__ */ jsx(
+    RadioGroupBase,
+    {
+      className: cn("flex flex-col gap-2", className),
+      ...props
+    }
+  );
+}
+RadioGroup.displayName = "RadioGroup";
+function Radio({ className, ...props }) {
+  return /* @__PURE__ */ jsx(
+    RadioBase.Root,
+    {
+      render: /* @__PURE__ */ jsx("button", { type: "button" }),
+      nativeButton: true,
+      className: cn(
+        RADIO_RING,
+        "data-[checked]:border-primary",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        "disabled:cursor-not-allowed disabled:opacity-50",
+        className
+      ),
+      ...props,
+      children: /* @__PURE__ */ jsx(RadioBase.Indicator, { className: cn(RADIO_DOT, "bg-primary") })
+    }
+  );
+}
+Radio.displayName = "Radio";
+export {
+  Radio,
+  RadioGroup
+};

package/dist/components/radio/radio.meta.js

@@ -0,0 +1,104 @@
+// src/components/radio/radio.meta.ts
+var radioMeta = {
+  name: "Radio",
+  summary: "Single-select control over Base UI RadioGroup + Radio (roving focus, arrow-key nav, ARIA radiogroup wiring, form integration). RadioGroup + Radio.",
+  status: "stable",
+  keywords: [
+    "radio",
+    "radio group",
+    "single choice",
+    "form control"
+  ],
+  usage: {
+    description: "Use Radio when a user must choose exactly one option from a visible set.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it when all options should be visible for comparison."
+      },
+      {
+        guidance: "do",
+        description: "Keep option labels mutually exclusive and easy to understand."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use Radio for independent toggles or multiple selection; use Checkbox or Switch."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use a radio group with only one option, and do not omit the Fieldset. Without the fieldset the options share no accessible name, so a screen reader reads the choices with no question attached."
+      }
+    ],
+    anatomy: [
+      {
+        name: "RadioGroup",
+        required: true,
+        description: "The grouped set that manages one selected value."
+      },
+      {
+        name: "Radio",
+        required: true,
+        description: "One selectable option in the group."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Checkbox",
+      "RadioCard",
+      "Field",
+      "Fieldset",
+      "Select"
+    ]
+  },
+  props: [
+    {
+      name: "Radio",
+      type: "Base UI Radio.Root props (value, disabled, readOnly, required) + className",
+      description: "A single radio button. value pairs it with the group's selected value. Renders a native button with radio semantics, the ring and an inner Indicator dot. A custom non-button render must also set nativeButton={false}."
+    }
+  ],
+  subcomponents: [
+    {
+      name: "RadioGroup",
+      type: "Base UI RadioGroup props (value, defaultValue, onValueChange, name, disabled, readOnly, required) + className",
+      description: "The group container that wraps Radio items and shares selection state across them. Controlled via value + onValueChange; uncontrolled via defaultValue. Lays its Radio items out in a vertical stack."
+    }
+  ],
+  tokensUsed: ["input", "card", "primary", "ring"],
+  a11y: [
+    "Base UI provides the radiogroup/radio roles, aria-checked, hidden native inputs, and roving tabindex.",
+    "Arrow keys move and select between items; Space selects the focused item; Tab enters/leaves the group.",
+    "Checked state styling reads from the data-[checked] attribute; disabled items from the disabled state.",
+    'Focus-visible draws a 2px ring on the focused item. Wrap each Radio in <Field label orientation="horizontal"> so the label names it, is part of the hit target, sits on the first line, and dims with it when disabled \u2014 do not hand-build a <label> row.'
+  ],
+  examples: [
+    {
+      label: "Basic",
+      code: `<Fieldset>
+	<FieldsetLegend>Post type</FieldsetLegend>
+	<FieldsetContent>
+		<RadioGroup defaultValue="standard">
+			<Field label="Standard" orientation="horizontal"><Radio value="standard" /></Field>
+			<Field label="Edition" orientation="horizontal"><Radio value="edition" /></Field>
+		</RadioGroup>
+	</FieldsetContent>
+</Fieldset>`
+    },
+    {
+      label: "With a disabled option",
+      code: `<Fieldset>
+	<FieldsetLegend>Post type</FieldsetLegend>
+	<FieldsetContent>
+		<RadioGroup defaultValue="standard">
+			<Field label="Standard" orientation="horizontal"><Radio value="standard" /></Field>
+			<Field label="Edition" orientation="horizontal" disabled><Radio value="edition" /></Field>
+		</RadioGroup>
+	</FieldsetContent>
+</Fieldset>`
+    }
+  ]
+};
+export {
+  radioMeta
+};

package/dist/components/radio-card/index.js

@@ -0,0 +1,7 @@
+// src/components/radio-card/index.ts
+import { RadioCard } from "./radio-card.js";
+import { radioCardMeta } from "./radio-card.meta.js";
+export {
+  RadioCard,
+  radioCardMeta
+};

package/dist/components/radio-card/radio-card.js

@@ -0,0 +1,81 @@
+// src/components/radio-card/radio-card.tsx
+import { Radio as RadioBase } from "@base-ui/react/radio";
+import { cn } from "../../lib/cn.js";
+import {
+  RADIO_DOT,
+  RADIO_RING,
+  SELECTION_CARD_GLYPH,
+  SELECTION_CARD_LAYOUT,
+  SELECTION_CARD_SHELL,
+  SELECTION_CARD_TILE_HEAD
+} from "../../lib/selection-card.js";
+import { radioCardToneClasses } from "./radio-card.variants.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+function RadioCard({
+  className,
+  title,
+  description,
+  icon,
+  tone = "neutral",
+  titleClassName,
+  descriptionClassName,
+  ...props
+}) {
+  const t = radioCardToneClasses[tone];
+  const marker = /* @__PURE__ */ jsx(
+    "span",
+    {
+      className: cn(
+        RADIO_RING,
+        t.marker
+      ),
+      children: /* @__PURE__ */ jsx(
+        RadioBase.Indicator,
+        {
+          className: cn(
+            RADIO_DOT,
+            t.dot
+          )
+        }
+      )
+    }
+  );
+  const content = /* @__PURE__ */ jsxs("span", { className: "flex min-w-0 flex-col gap-0.5", children: [
+    /* @__PURE__ */ jsx("span", { className: cn("text-title-sm", titleClassName), children: title }),
+    description ? /* @__PURE__ */ jsx(
+      "span",
+      {
+        className: cn("text-body-sm text-muted-foreground", descriptionClassName),
+        children: description
+      }
+    ) : null
+  ] });
+  return /* @__PURE__ */ jsx(
+    RadioBase.Root,
+    {
+      render: /* @__PURE__ */ jsx("button", { type: "button" }),
+      nativeButton: true,
+      className: cn(
+        SELECTION_CARD_SHELL,
+        t.card,
+        icon != null ? SELECTION_CARD_LAYOUT.tile : SELECTION_CARD_LAYOUT.row,
+        className
+      ),
+      ...props,
+      children: icon != null ? /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsxs("span", { className: SELECTION_CARD_TILE_HEAD, children: [
+          /* @__PURE__ */ jsx("span", { className: cn(SELECTION_CARD_GLYPH, t.glyph), children: icon }),
+          marker
+        ] }),
+        content
+      ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx("span", { className: cn("flex h-[1lh] shrink-0 items-center text-title-sm", titleClassName), children: marker }),
+        content
+      ] })
+    }
+  );
+}
+RadioCard.displayName = "RadioCard";
+export {
+  RadioCard
+};

package/dist/components/radio-card/radio-card.meta.js

@@ -0,0 +1,144 @@
+// src/components/radio-card/radio-card.meta.ts
+var radioCardMeta = {
+  name: "RadioCard",
+  summary: "A selectable card option (radio-card) over Base UI RadioGroup + Radio. RadioGroup shares selection state; each RadioCard is a card with a radio indicator, title, and description. Add an icon to switch to the richer two-dimensional card, and a tone to give the selected state a semantic colour identity.",
+  status: "stable",
+  keywords: [
+    "radio-card",
+    "choice card",
+    "selection",
+    "option card"
+  ],
+  usage: {
+    description: "Use RadioCard for visual choice cards when users compare a small set of named options.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it when labels, descriptions, or icons make options easier to understand."
+      },
+      {
+        guidance: "do",
+        description: "Make the selected state explicit and preserve keyboard access through the group."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use RadioCard for dense menus, long lists, or simple yes/no settings."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use a single RadioCard on its own. It is a radio, so one option cannot be deselected \u2014 a lone one is a switch, and should be a Switch."
+      }
+    ],
+    anatomy: [
+      {
+        name: "RadioCard",
+        required: true,
+        description: "One selectable option card."
+      },
+      {
+        name: "RadioGroup",
+        required: false,
+        description: "A grouped set of related choice cards."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Radio",
+      "CheckboxCard",
+      "Select"
+    ]
+  },
+  props: [
+    {
+      name: "value",
+      type: "string",
+      description: "The unique value that pairs this card with the group's selected value."
+    },
+    {
+      name: "title",
+      type: "ReactNode",
+      description: "The card's primary label (rendered as text-title-sm)."
+    },
+    {
+      name: "description",
+      type: "ReactNode",
+      description: "Optional supporting copy beneath the title (text-body-sm, muted)."
+    },
+    {
+      name: "icon",
+      type: "ReactNode",
+      description: "Leading icon (e.g. a solid <Icon>). Its presence switches to the two-dimensional card \u2014 icon top-left, indicator top-right, copy below \u2014 and the glyph is rendered as a solid-fill icon in the tone colour."
+    },
+    {
+      name: "tone",
+      type: '"neutral" | "standard" | "collectible" | "edition" | "info" | "warning"',
+      default: '"neutral"',
+      description: "Semantic colour the selected state carries across the border, radio, and icon glyph. Neutral uses the primary ring with a muted wash."
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      default: "false",
+      description: "Dims the card and blocks selection. The group skips it during keyboard navigation."
+    },
+    {
+      name: "titleClassName",
+      type: "string",
+      description: "Merged onto the title span (default text-title-sm) \u2014 e.g. to tighten copy in a two-column layout."
+    },
+    {
+      name: "descriptionClassName",
+      type: "string",
+      description: "Merged onto the description span (default text-body-sm text-muted-foreground)."
+    }
+  ],
+  subcomponents: [
+    {
+      name: "RadioGroup",
+      type: "Base UI RadioGroup props (value, defaultValue, onValueChange, name, disabled, readOnly, required) + className",
+      description: "The group container that wraps the RadioCard cards and shares their selection state. Controlled via value + onValueChange; uncontrolled via defaultValue. Lays its cards out in a single column by default; override with className (e.g. 'grid sm:grid-cols-3') for a grid \u2014 the group is a flex column, so a grid-cols-* class alone does nothing."
+    }
+  ],
+  variants: {
+    tone: ["neutral", "standard", "collectible", "edition", "info", "warning"]
+  },
+  tokensUsed: [
+    "input",
+    "card",
+    "foreground",
+    "primary",
+    "muted",
+    "ring",
+    "muted-foreground",
+    "tone-standard",
+    "tone-collectible",
+    "tone-edition",
+    "tone-info",
+    "tone-warning"
+  ],
+  a11y: [
+    "Base UI provides the radiogroup/radio roles, aria-checked, hidden native inputs, and roving tabindex.",
+    "Arrow keys move and select between cards; Space selects the focused card; Tab enters/leaves the group.",
+    "Checked state styling reads from the data-[checked] attribute; disabled cards from data-disabled.",
+    "focus-within draws a 2px ring on the focused card; the whole card is the hit target.",
+    "The icon is decorative \u2014 the title labels the card \u2014 so selection meaning never relies on colour alone (the border ring and the filled radio both shift; the neutral tone adds a muted fill)."
+  ],
+  examples: [
+    {
+      label: "Post type (tone + icon)",
+      code: '<RadioGroup defaultValue="post" className="grid sm:grid-cols-3"><RadioCard value="post" tone="standard" icon={<Icon name="plus" />} title="Standard" description="Share without minting" /><RadioCard value="collectible" tone="collectible" icon={<Icon name="gem" />} title="Collectible" description="Free to collect as NFT" /><RadioCard value="edition" tone="edition" icon={<Icon name="image-stack" />} title="Edition" description="Sell as NFT editions" /></RadioGroup>'
+    },
+    {
+      label: "Plan picker (plain)",
+      code: '<RadioGroup defaultValue="pro"><RadioCard value="free" title="Free" description="For trying things out." /><RadioCard value="pro" title="Pro" description="For growing teams." /><RadioCard value="enterprise" title="Enterprise" description="Custom limits and support." /></RadioGroup>'
+    },
+    {
+      label: "With a disabled option",
+      code: '<RadioGroup defaultValue="free"><RadioCard value="free" title="Free" description="For trying things out." /><RadioCard value="enterprise" title="Enterprise" description="Contact sales to enable." disabled /></RadioGroup>'
+    }
+  ]
+};
+export {
+  radioCardMeta
+};

package/dist/components/radio-card/radio-card.variants.js

@@ -0,0 +1,43 @@
+// src/components/radio-card/radio-card.variants.ts
+import { SELECTION_CARD_CHECKED } from "../../lib/selection-card.js";
+var radioCardToneClasses = {
+  neutral: {
+    card: SELECTION_CARD_CHECKED.neutral,
+    marker: "group-data-[checked]:border-primary",
+    dot: "bg-primary",
+    glyph: "text-foreground"
+  },
+  standard: {
+    card: SELECTION_CARD_CHECKED.standard,
+    marker: "group-data-[checked]:border-tone-standard",
+    dot: "bg-tone-standard",
+    glyph: "text-tone-standard"
+  },
+  collectible: {
+    card: SELECTION_CARD_CHECKED.collectible,
+    marker: "group-data-[checked]:border-tone-collectible",
+    dot: "bg-tone-collectible",
+    glyph: "text-tone-collectible"
+  },
+  edition: {
+    card: SELECTION_CARD_CHECKED.edition,
+    marker: "group-data-[checked]:border-tone-edition",
+    dot: "bg-tone-edition",
+    glyph: "text-tone-edition"
+  },
+  info: {
+    card: SELECTION_CARD_CHECKED.info,
+    marker: "group-data-[checked]:border-tone-info",
+    dot: "bg-tone-info",
+    glyph: "text-tone-info"
+  },
+  warning: {
+    card: SELECTION_CARD_CHECKED.warning,
+    marker: "group-data-[checked]:border-tone-warning",
+    dot: "bg-tone-warning",
+    glyph: "text-tone-warning"
+  }
+};
+export {
+  radioCardToneClasses
+};

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

@@ -0,0 +1,7 @@
+// src/components/relative-time/index.ts
+import { RelativeTime } from "./relative-time.js";
+import { relativeTimeMeta } from "./relative-time.meta.js";
+export {
+  RelativeTime,
+  relativeTimeMeta
+};