@sableui/react 0.6.2 → 0.7.1

package/dist/components/kbd/kbd.js

@@ -0,0 +1,54 @@
+"use client";
+
+// src/components/kbd/kbd.tsx
+import { useSyncExternalStore } from "react";
+import { cn } from "../../lib/cn.js";
+import { jsx } from "react/jsx-runtime";
+function detectApple() {
+  if (typeof navigator === "undefined") return false;
+  const nav = navigator;
+  const platform = nav.userAgentData?.platform || nav.platform || nav.userAgent || "";
+  return /mac|iphone|ipad|ipod/i.test(platform);
+}
+var noopSubscribe = () => () => {
+};
+function useIsApple() {
+  return useSyncExternalStore(noopSubscribe, detectApple, () => false);
+}
+var KBD_VARIANTS = {
+  key: "rounded-xs border border-border border-b-border-strong bg-[var(--sable-surface-bg,var(--background))] text-muted-foreground shadow-[0_1px_0_0_var(--border)]",
+  ghost: "text-current opacity-70"
+};
+function Kbd({ mod = false, variant = "key", className, children, ...props }) {
+  const apple = useIsApple();
+  const content = mod ? apple ? "\u2318" : "Ctrl" : children;
+  return /* @__PURE__ */ jsx(
+    "kbd",
+    {
+      "data-slot": "kbd",
+      className: cn(
+        "inline-flex h-[1.6em] min-w-[1.6em] items-center justify-center px-[0.4em] align-middle font-sans text-[max(0.75rem,0.85em)] font-medium leading-none tabular-nums",
+        KBD_VARIANTS[variant],
+        className
+      ),
+      ...props,
+      children: content
+    }
+  );
+}
+Kbd.displayName = "Kbd";
+function KbdGroup({ className, ...props }) {
+  return /* @__PURE__ */ jsx(
+    "kbd",
+    {
+      "data-slot": "kbd-group",
+      className: cn("inline-flex items-center gap-[0.2em] align-middle", className),
+      ...props
+    }
+  );
+}
+KbdGroup.displayName = "KbdGroup";
+export {
+  Kbd,
+  KbdGroup
+};

package/dist/components/kbd/kbd.meta.js

@@ -0,0 +1,95 @@
+// src/components/kbd/kbd.meta.ts
+var kbdMeta = {
+  name: "Kbd",
+  summary: 'A keyboard key indicator. Renders a raised <kbd> key cap sized from the surrounding text, so one Kbd fits body copy, menus and tooltips; KbdGroup sets one cap per key for a combo. `mod` renders the platform modifier (\u2318 or Ctrl); `variant="ghost"` is the bare label for menu rows and tooltips.',
+  status: "stable",
+  keywords: [
+    "keyboard",
+    "shortcut",
+    "key",
+    "kbd"
+  ],
+  usage: {
+    description: "Use Kbd to display keyboard keys or shortcuts in help text, menus, and docs.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it only for literal keyboard input such as Cmd, Enter, or Esc."
+      },
+      {
+        guidance: "do",
+        description: "Show a combo as one cap per key inside KbdGroup \u2014 `<KbdGroup><Kbd mod /><Kbd>K</Kbd></KbdGroup>` \u2014 not several keys typed into one cap."
+      },
+      {
+        guidance: "do",
+        description: 'Use `variant="ghost"` where the shortcut sits on a surface of its own \u2014 a menu row\'s trailing slot, a tooltip \u2014 so it reads as a hint, not a second control.'
+      },
+      {
+        guidance: "dont",
+        description: "Do not use Kbd as a decorative badge or button replacement."
+      },
+      {
+        guidance: "dont",
+        description: "Do not set a text size on a Kbd. It sizes itself from the text around it."
+      },
+      {
+        guidance: "dont",
+        description: "Do not hardcode \u2318 or Ctrl. The modifier differs by platform; use `<Kbd mod />`, which renders \u2318 on macOS/iOS and Ctrl elsewhere, or Windows users read Mac keys."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Code",
+      "Menu",
+      "CommandMenu"
+    ]
+  },
+  props: [
+    {
+      name: "mod",
+      type: "boolean",
+      default: "false",
+      description: "Render the platform's shortcut modifier in place of children: \u2318 on macOS and iOS, Ctrl everywhere else. Server-rendered as Ctrl and corrected on hydration."
+    },
+    {
+      name: "variant",
+      type: '"key" | "ghost"',
+      default: '"key"',
+      description: "`key`: a raised cap on the surface it sits on, with a heavier bottom edge as the key's lip. `ghost`: the bare label, for menu rows, tooltips and other surfaces that are already a frame."
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Merge additional classes onto the key cap."
+    },
+    {
+      name: "...props",
+      type: 'ComponentPropsWithRef<"kbd">',
+      description: "All native <kbd> attributes (children, ref, etc.)."
+    }
+  ],
+  tokensUsed: ["border", "border-strong", "background", "muted-foreground"],
+  a11y: [
+    "Uses the semantic <kbd> element so assistive tech announces keyboard input.",
+    "KbdGroup is itself a <kbd> around the per-key caps \u2014 the HTML spelling of one key combination \u2014 so the combo is announced as a single piece of input.",
+    "Sized in em from the surrounding text, so it scales with the user's text size and never shrinks below 12px."
+  ],
+  examples: [
+    {
+      label: "Single keys",
+      code: "<Kbd>Esc</Kbd>"
+    },
+    {
+      label: "Combo",
+      code: "<KbdGroup><Kbd mod /><Kbd>K</Kbd></KbdGroup>"
+    },
+    {
+      label: "In a menu row",
+      code: '<MenuItem>Search<KbdGroup className="ms-auto"><Kbd variant="ghost" mod /><Kbd variant="ghost">K</Kbd></KbdGroup></MenuItem>'
+    }
+  ]
+};
+export {
+  kbdMeta
+};

package/dist/components/label/index.js

@@ -0,0 +1,7 @@
+// src/components/label/index.ts
+import { Label } from "./label.js";
+import { labelMeta } from "./label.meta.js";
+export {
+  Label,
+  labelMeta
+};

package/dist/components/label/label.js

@@ -0,0 +1,51 @@
+// src/components/label/label.tsx
+import { cva } from "class-variance-authority";
+import { cn } from "../../lib/cn.js";
+import { SimpleTooltip } from "../tooltip/index.js";
+import { jsx } from "react/jsx-runtime";
+var labelVariants = cva(
+  "text-foreground select-none peer-disabled:cursor-not-allowed peer-disabled:opacity-50",
+  {
+    variants: {
+      size: {
+        xs: "text-label-xs",
+        sm: "text-label-sm",
+        md: "text-label-md",
+        lg: "text-label-lg"
+      }
+    },
+    defaultVariants: {
+      size: "lg"
+    }
+  }
+);
+function Label({
+  size,
+  eyebrow = false,
+  hint,
+  className,
+  tabIndex,
+  ...props
+}) {
+  const labelEl = /* @__PURE__ */ jsx(
+    "label",
+    {
+      tabIndex: hint != null ? tabIndex ?? 0 : tabIndex,
+      className: cn(
+        labelVariants({ size }),
+        eyebrow && "text-overline",
+        hint != null && "cursor-help border-b border-dotted border-muted-foreground/40",
+        className
+      ),
+      ...props
+    }
+  );
+  if (hint == null) {
+    return labelEl;
+  }
+  return /* @__PURE__ */ jsx(SimpleTooltip, { content: hint, children: labelEl });
+}
+Label.displayName = "Label";
+export {
+  Label
+};

package/dist/components/label/label.meta.js

@@ -0,0 +1,98 @@
+// src/components/label/label.meta.ts
+var labelMeta = {
+  name: "Label",
+  summary: "Styled native <label>. Paired label typography via a size step (xs / sm / md / lg, all sentence case) or an uppercase eyebrow (eyebrow), non-selectable, dims when its peer control is disabled. Optional hint adds a dotted-underline tooltip affordance.",
+  status: "stable",
+  keywords: [
+    "label",
+    "form label",
+    "control",
+    "accessibility"
+  ],
+  usage: {
+    description: "Use Label to name a form control and create a clear accessible relationship with that control.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use explicit, persistent labels for inputs, selects, textareas, and grouped controls."
+      },
+      {
+        guidance: "do",
+        description: "Place helper text separately so the label stays short and direct."
+      },
+      {
+        guidance: "dont",
+        description: "Do not rely on placeholder text as the only label for a control."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it as a bare styled span. A Label without htmlFor or a wrapped control looks like a label and does nothing \u2014 clicking it will not focus the field, which is the entire point."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Input",
+      "Textarea",
+      "Fieldset",
+      "Form",
+      "Field"
+    ]
+  },
+  props: [
+    {
+      name: "htmlFor",
+      type: "string",
+      description: "Associates the label with a control by its id (native <label for>)."
+    },
+    {
+      name: "size",
+      type: '"xs" | "sm" | "md" | "lg"',
+      default: '"lg"',
+      description: "Paired label typography step, all sentence case. xs is simply the smallest; for an uppercase eyebrow use eyebrow."
+    },
+    {
+      name: "eyebrow",
+      type: "boolean",
+      default: "false",
+      description: "Set the label as an eyebrow: the uppercase, letter-spaced text-overline tier (themeable to sentence case). Replaces size. For a kicker above a group, not an ordinary field label."
+    },
+    {
+      name: "hint",
+      type: "ReactNode",
+      description: "When set, the label gets a dotted-underline affordance and reveals this content in a tooltip on hover/focus."
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Merge or override classes via cn()."
+    }
+  ],
+  variants: {
+    size: ["xs", "sm", "md", "lg"]
+  },
+  tokensUsed: ["foreground", "muted-foreground"],
+  a11y: [
+    "Renders a native <label> \u2014 clicking it focuses/activates the associated control.",
+    "Associate with a control via htmlFor (matching the control's id) or by wrapping the control.",
+    "In a form, use Field: it renders this Label, wires htmlFor/id, and dims the label when the field is disabled. Hand-wired outside a Field, the label only dims via peer-disabled when the control carries `peer` AND precedes the Label in the DOM (Tailwind peer-* only matches a later sibling).",
+    "With `hint`, the label becomes focusable and the help text is announced via the tooltip's aria-describedby \u2014 so the affordance works for keyboard and screen-reader users, not just hover."
+  ],
+  examples: [
+    {
+      label: "With control",
+      code: '<Stack gap={1}><Label htmlFor="name">Display name</Label><Input id="name" /></Stack>'
+    },
+    {
+      label: "In a form",
+      code: '<Field label="Display name" disabled><Input /></Field>'
+    },
+    {
+      label: "With hint",
+      code: '<Label htmlFor="royalty" hint="A percentage of every resale, paid to you.">Royalty</Label>'
+    }
+  ]
+};
+export {
+  labelMeta
+};

package/dist/components/line-chart/index.js

@@ -0,0 +1,7 @@
+// src/components/line-chart/index.ts
+import { LineChart } from "./line-chart.js";
+import { lineChartMeta } from "./line-chart.meta.js";
+export {
+  LineChart,
+  lineChartMeta
+};

package/dist/components/line-chart/line-chart.js

@@ -0,0 +1,10 @@
+// src/components/line-chart/line-chart.tsx
+import { CartesianChart } from "../../lib/chart/cartesian.js";
+import { jsx } from "react/jsx-runtime";
+function LineChart(props) {
+  return /* @__PURE__ */ jsx(CartesianChart, { kind: "line", ...props });
+}
+LineChart.displayName = "LineChart";
+export {
+  LineChart
+};

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

@@ -0,0 +1,222 @@
+// src/components/line-chart/line-chart.meta.ts
+var lineChartMeta = {
+  name: "LineChart",
+  summary: "Lines over a sequence \u2014 for comparing how measures move. Smooth, linear or step curves, optional dots (coloured by series or by category) and value labels. Lines draw on as the chart scrolls into view.",
+  keywords: [
+    "chart",
+    "line",
+    "trend",
+    "time series",
+    "graph",
+    "compare",
+    "analytics",
+    "dashboard"
+  ],
+  usage: {
+    description: "Use LineChart to compare how two or more measures change over the same sequence, or to show one trend precisely (with dots and labels). Unlike AreaChart, its value axis is fitted to the data rather than forced to zero, so small movements stay visible \u2014 say so if the axis is shown.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Turn on dots and labels for six or fewer points, when the exact values are the story."
+      },
+      {
+        guidance: "do",
+        description: 'Use curve="step" for values that hold until they change \u2014 prices, plan tiers, headcount.'
+      },
+      {
+        guidance: "dont",
+        description: "Plot unordered categories (channels, products) as a line \u2014 the line implies a path between them; 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: [
+      "AreaChart",
+      "BarChart",
+      "Sparkline",
+      "Card"
+    ]
+  },
+  status: "beta",
+  props: [
+    {
+      name: "data",
+      type: "Record<string, unknown>[]",
+      description: "The rows, in order along the category axis."
+    },
+    {
+      name: "index",
+      type: "string",
+      description: "The datum field naming each row's category (a month, a day, a channel)."
+    },
+    {
+      name: "series",
+      type: "{ key: string; label: string; tone?: ChartTone; color?: string; icon?: string }[]",
+      description: "The measures to plot: the datum field, its name in the legend/tooltip/table, and its colour (a tone by role, or any CSS colour). Omitted, series take the chart palette in order: --chart-1 \u2026 --chart-8, validated for colour-blind separation in light and dark; a theme may override the set."
+    },
+    {
+      name: "label",
+      type: "string",
+      description: "What the chart shows. Its accessible name and the caption of the data table assistive tech reads."
+    },
+    {
+      name: "className",
+      type: "string",
+      default: '"h-60"',
+      description: "Sizes the chart (plot + legend). Set a height: `h-72`, `aspect-video h-auto`."
+    },
+    {
+      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: "indexFormatter",
+      type: "(value: string) => string",
+      description: 'Shorten category labels on the axis ("January" \u2192 "Jan"); the tooltip keeps the full value.'
+    },
+    {
+      name: "locale",
+      type: "string",
+      default: "runtime locale",
+      description: "BCP 47 locale for default number and date formatting."
+    },
+    {
+      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: "legend",
+      type: "boolean",
+      default: "true when there is more than one series",
+      description: "Show the legend under the chart."
+    },
+    {
+      name: "grid",
+      type: "boolean",
+      default: "true (false for horizontal bars)",
+      description: "Hairline gridlines along the value axis."
+    },
+    {
+      name: "xAxis",
+      type: "boolean",
+      default: "true for columns; false for horizontal bars",
+      description: "The horizontal axis."
+    },
+    {
+      name: "yAxis",
+      type: "boolean",
+      default: "false for columns; true for horizontal bars",
+      description: "The vertical axis."
+    },
+    {
+      name: "animate",
+      type: "boolean",
+      default: "true",
+      description: "Play the arrival once the chart scrolls into view. Reduced motion shows the finished chart."
+    },
+    {
+      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."
+    },
+    {
+      name: "curve",
+      type: '"smooth" | "linear" | "step"',
+      default: '"smooth"',
+      description: "How the line runs between points. `smooth` is monotone: it never overshoots a value the data does not contain."
+    },
+    {
+      name: "dots",
+      type: "boolean",
+      default: "false",
+      description: "Mark every data point with a dot."
+    },
+    {
+      name: "colorBy",
+      type: '"series" | "index"',
+      default: '"series"',
+      description: "Colour the dots by series, or each by its category."
+    },
+    {
+      name: "labels",
+      type: "boolean",
+      default: "false",
+      description: "Print each point's value above it."
+    }
+  ],
+  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: "Line",
+      why: "Once on screen each line draws on from the first point (stroke-dashoffset), series staggered, then the dots and labels fade in. On the motion tokens; reduced motion shows the finished chart."
+    },
+    {
+      slot: "response",
+      recipe: "none",
+      part: "Cursor + tooltip",
+      why: "Hover and focus move the cursor and tooltip instantly \u2014 a lagging cursor reads as a slow chart."
+    },
+    {
+      slot: "transition",
+      recipe: "custom",
+      part: "Line + dots",
+      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: "LineChart",
+      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: "Compare two series",
+      code: '<LineChart\n	label="Desktop and mobile visitors"\n	data={visitors}\n	index="month"\n	series={[\n		{ key: "desktop", label: "Desktop", tone: "primary" },\n		{ key: "mobile", label: "Mobile", tone: "info" },\n	]}\n	indexFormatter={(m) => m.slice(0, 3)}\n/>'
+    },
+    {
+      label: "Dots and labels",
+      code: '<LineChart\n	label="Desktop visitors"\n	data={visitors}\n	index="month"\n	series={[{ key: "desktop", label: "Desktop" }]}\n	curve="linear"\n	dots\n	labels\n	grid={false}\n/>'
+    }
+  ]
+};
+export {
+  lineChartMeta
+};

package/dist/components/marker/index.js

@@ -0,0 +1,7 @@
+// src/components/marker/index.ts
+import { Marker } from "./marker.js";
+import { markerMeta } from "./marker.meta.js";
+export {
+  Marker,
+  markerMeta
+};

package/dist/components/marker/marker.js

@@ -0,0 +1,39 @@
+// src/components/marker/marker.tsx
+import { Icon } from "../../icon/index.js";
+import { cn } from "../../lib/cn.js";
+import { useTypeTier } from "../../lib/density.js";
+import { Separator } from "../separator/separator.js";
+import { markerRuleVariants, markerVariants } from "./marker.variants.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function Marker({
+  variant = "status",
+  icon,
+  spin = false,
+  shimmer = false,
+  live,
+  className,
+  children,
+  ...props
+}) {
+  const announce = live ?? variant === "status";
+  const tier = useTypeTier();
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      role: announce ? "status" : void 0,
+      "aria-live": announce ? "polite" : void 0,
+      className: cn(markerVariants({ variant }), tier.secondary, className),
+      ...props,
+      children: [
+        variant === "separator" ? /* @__PURE__ */ jsx(Separator, { "aria-hidden": true, className: markerRuleVariants() }) : null,
+        icon ? /* @__PURE__ */ jsx(Icon, { name: icon, spin, className: "shrink-0 text-[1.15em]" }) : null,
+        /* @__PURE__ */ jsx("span", { className: cn("min-w-0", shimmer && "motion-text-shimmer"), children }),
+        variant === "separator" ? /* @__PURE__ */ jsx(Separator, { "aria-hidden": true, className: markerRuleVariants() }) : null
+      ]
+    }
+  );
+}
+Marker.displayName = "Marker";
+export {
+  Marker
+};