@sableui/react 0.6.2 → 0.7.1

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

@@ -0,0 +1,245 @@
+// src/components/bar-chart/bar-chart.meta.ts
+var barChartMeta = {
+  name: "BarChart",
+  summary: "Bars comparing amounts across categories: grouped, stacked or stacked to 100%, vertical columns or horizontal bars, with value labels, per-category colours and a separate tone for negative values. Bars rise from the baseline in sequence as the chart scrolls into view.",
+  keywords: [
+    "chart",
+    "bar",
+    "column",
+    "histogram",
+    "compare",
+    "stacked",
+    "grouped",
+    "horizontal",
+    "analytics",
+    "dashboard"
+  ],
+  usage: {
+    description: 'Use BarChart to compare amounts across categories \u2014 the default chart for "how much of each". Go horizontal (`orientation="horizontal"`) when category names are long or there are many of them; group series side by side to compare them, stack them to show a total. For parts of one whole, a stacked bar or PieChart; for a trend, AreaChart or LineChart.',
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Sort categories by value unless they have a natural order (months, steps)."
+      },
+      {
+        guidance: "do",
+        description: "Use negativeTone for diverging data (profit and loss), so a loss reads apart from a gain."
+      },
+      {
+        guidance: "dont",
+        description: "Group more than three series side by side \u2014 the bars get too thin to compare; stack them or split the chart."
+      },
+      {
+        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",
+      "PieChart",
+      "SegmentedBar",
+      "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: "orientation",
+      type: '"vertical" | "horizontal"',
+      default: '"vertical"',
+      description: "`vertical` columns rise from the bottom; `horizontal` bars run from the left, for long category names."
+    },
+    {
+      name: "stacked",
+      type: 'boolean | "expand"',
+      default: "false",
+      description: 'Stack the series in one bar, or `"expand"` to show each category as 100%. Unstacked series sit side by side.'
+    },
+    {
+      name: "labels",
+      type: 'boolean | "inside"',
+      default: "false",
+      description: 'Print each bar\'s value at its end, or (`"inside"`, horizontal) the category name inside the bar as well.'
+    },
+    {
+      name: "colorBy",
+      type: '"series" | "index"',
+      default: '"series"',
+      description: "Colour by series, or give each category its own tone (one series)."
+    },
+    {
+      name: "negativeTone",
+      type: '"edition" | "collectible" | "standard" | "info" | "warning" | "primary" | "neutral" | "success" | "destructive"',
+      description: "Colour negative values with this tone."
+    },
+    {
+      name: "radius",
+      type: "number",
+      default: "4",
+      description: "Corner radius of each bar's far end, in px. Stacks round only the outer segment."
+    },
+    {
+      name: "barWidth",
+      type: "number",
+      default: "24",
+      description: "Maximum thickness of a bar, in px: the band's leftover is air, not a fatter bar. Raise it for a bolder presentation look."
+    }
+  ],
+  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: "Bar",
+      why: "Once on screen, bars rise from the baseline in sequence on the emphasized easing (scale from the zero line) and their labels fade in. On the motion tokens; reduced motion shows the finished chart."
+    },
+    {
+      slot: "response",
+      recipe: "none",
+      part: "Cursor + tooltip",
+      why: "The hovered category gets a band behind it and the other bars dim at once \u2014 a lagging highlight reads as a slow chart."
+    },
+    {
+      slot: "transition",
+      recipe: "custom",
+      part: "Bar",
+      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: "BarChart",
+      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: "Grouped series",
+      code: '<BarChart\n	label="Visitors by device"\n	data={visitors}\n	index="month"\n	series={[\n		{ key: "desktop", label: "Desktop" },\n		{ key: "mobile", label: "Mobile" },\n	]}\n	indexFormatter={(m) => m.slice(0, 3)}\n/>'
+    },
+    {
+      label: "Horizontal, labelled inside",
+      code: 'const browsers = [\n	{ browser: "Chrome", visitors: 275 },\n	{ browser: "Safari", visitors: 200 },\n	{ browser: "Firefox", visitors: 187 },\n	{ browser: "Edge", visitors: 173 },\n]\n\n<BarChart\n	label="Visitors by browser"\n	data={browsers}\n	index="browser"\n	series={[{ key: "visitors", label: "Visitors" }]}\n	orientation="horizontal"\n	labels="inside"\n	yAxis={false}\n	grid={false}\n/>'
+    },
+    {
+      label: "Profit and loss",
+      code: '<BarChart\n	label="Net revenue by month"\n	data={[\n		{ month: "Jan", net: 186 },\n		{ month: "Feb", net: -95 },\n		{ month: "Mar", net: 137 },\n		{ month: "Apr", net: -60 },\n	]}\n	index="month"\n	series={[{ key: "net", label: "Net", tone: "success" }]}\n	negativeTone="destructive"\n	labels\n/>'
+    }
+  ]
+};
+export {
+  barChartMeta
+};

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

@@ -0,0 +1,7 @@
+// src/components/bar-chart/index.ts
+import { BarChart } from "./bar-chart.js";
+import { barChartMeta } from "./bar-chart.meta.js";
+export {
+  BarChart,
+  barChartMeta
+};

package/dist/components/bottom-nav/bottom-nav.js

@@ -0,0 +1,63 @@
+// src/components/bottom-nav/bottom-nav.tsx
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "../../lib/cn.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+function BottomNav({
+  className,
+  children,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    "nav",
+    {
+      className: cn(
+        "fixed inset-x-0 bottom-0 z-(--z-nav) border-t border-border bg-background/95 pb-[env(safe-area-inset-bottom,0px)] backdrop-blur-sm lg:hidden",
+        className
+      ),
+      ...props,
+      children: /* @__PURE__ */ jsx("div", { className: "flex h-[var(--nav-height,56px)] items-center justify-around px-2", children })
+    }
+  );
+}
+BottomNav.displayName = "BottomNav";
+function BottomNavItem({
+  icon,
+  label,
+  active,
+  badge,
+  showLabel = false,
+  render,
+  className,
+  ...props
+}) {
+  return useRender({
+    render: render ?? /* @__PURE__ */ jsx("button", { type: "button" }),
+    props: {
+      ...props,
+      "aria-label": label,
+      "data-active": active ? "" : void 0,
+      "aria-current": active ? "page" : void 0,
+      className: cn(
+        // design-lint-disable-next-line raw-control-height -- the WCAG 2.5.5 touch-target floor, deliberately density-independent: a compact register still owes a 44px hit area.
+        "relative flex min-h-[44px] min-w-[44px] flex-col items-center justify-center gap-0.5 rounded-lg text-muted-foreground motion-interactive hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring data-[active]:text-foreground",
+        className
+      ),
+      children: /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsxs("span", { className: "relative grid size-[1em] place-items-center text-2xl", children: [
+          icon,
+          badge ? (
+            // flex, not block: a block wrapper takes the icon's text-2xl line box and drops an inline dot to its baseline, off the corner.
+            /* @__PURE__ */ jsx("span", { className: "absolute -right-1 -top-1 flex", children: badge })
+          ) : null
+        ] }),
+        showLabel ? /* @__PURE__ */ jsx("span", { className: "text-label-sm", children: label }) : null
+      ] })
+    },
+    defaultTagName: "button"
+  });
+}
+BottomNavItem.displayName = "BottomNavItem";
+export {
+  BottomNav,
+  BottomNavItem
+};

package/dist/components/bottom-nav/bottom-nav.meta.js

@@ -0,0 +1,95 @@
+// src/components/bottom-nav/bottom-nav.meta.ts
+var bottomNavMeta = {
+  name: "BottomNav",
+  summary: "Mobile bottom tab bar (fixed, hidden at lg), with home-indicator safe-area padding and evenly distributed BottomNavItem tabs. Items are router-agnostic via `render`.",
+  status: "stable",
+  keywords: [
+    "bottom nav",
+    "mobile nav",
+    "tabs",
+    "app navigation"
+  ],
+  usage: {
+    description: "Use BottomNav for a small set of top-level mobile destinations that should remain reachable with one thumb. Mount it through `<AppShell bottomNav={\u2026}>` so the content area reserves matching bottom space; it hides at lg, where the Sidebar takes over.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Limit the nav to the primary destinations users switch between often."
+      },
+      {
+        guidance: "do",
+        description: "Give every item a clear label (it is the accessible name), and turn on showLabel when the icons alone are not obvious."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use BottomNav for desktop navigation, dense menus, or page-local actions."
+      },
+      {
+        guidance: "dont",
+        description: "Do not omit the safe-area padding by overriding its padding-bottom. On a device with a home indicator the last row of targets ends up under the gesture area, where taps dismiss the app instead."
+      }
+    ],
+    anatomy: [
+      {
+        name: "BottomNav",
+        required: true,
+        description: "The fixed or anchored navigation container."
+      },
+      {
+        name: "BottomNavItem",
+        required: true,
+        description: "One destination with label, icon, and active state."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Sidebar",
+      "SideNav",
+      "AppHeader"
+    ]
+  },
+  props: [],
+  subcomponents: [
+    {
+      name: "BottomNavItem",
+      type: "{ label: string; icon?: ReactNode; active?: boolean; badge?: ReactNode; showLabel?: boolean; render?: useRender.RenderProp } + button props",
+      description: 'A single tab, placed as a child of BottomNav. `label` is the accessible name (aria-label) and optional visible label; `icon` is the glyph node (consumer swaps fill weight for the active state); `active` marks the current route (active ink + aria-current); `badge` overlays a corner dot/count on the icon; `showLabel` shows the label text beneath the icon \u2014 defaults to false (icon-only); turn it on when the icons alone are not self-evident; `render` renders as another element, e.g. render={<Link to="/x" />}.'
+    }
+  ],
+  a11y: [
+    "BottomNav renders a <nav> landmark.",
+    "Each tab is a 44px minimum touch target with an aria-label.",
+    'Active tab carries aria-current="page".'
+  ],
+  tokensUsed: ["background", "border", "muted-foreground", "foreground", "ring"],
+  examples: [
+    {
+      label: "Tab bar",
+      code: '<BottomNav><BottomNavItem icon={<Icon name="home" />} label="Home" active render={<Link to="/" />} /><BottomNavItem icon={<Icon name="bell" />} label="Notifications" badge={<NotificationBadge dot />} render={<Link to="/notifications" />} /></BottomNav>'
+    },
+    {
+      label: "When NOT to use it",
+      code: `// BottomNav is for 3\u20135 PEER destinations on a small viewport \u2014 the mobile
+// counterpart to SideNav, not an action bar.
+
+// \u2717 Actions. A bottom bar of verbs (Save / Share / Delete) is a toolbar; it
+//   competes with the OS gesture area and has no "current" state to show.
+// \u2717 More than five items. Past that, labels truncate and targets shrink below
+//   the 44px floor \u2014 use a "More" destination that opens a Sheet.
+// \u2717 Nested navigation. BottomNav switches top-level sections only; drilling in
+//   happens inside the section, with Breadcrumbs or a back affordance.
+
+<AppShell bottomNav={<BottomNav>
+  <BottomNavItem label="Home" icon={<Icon name="home" />} active />
+  <BottomNavItem label="Search" icon={<Icon name="search" />} />
+  <BottomNavItem label="Account" icon={<Icon name="user" />} />
+</BottomNav>}>
+  <Region max="feed">Route content</Region>
+</AppShell>`
+    }
+  ]
+};
+export {
+  bottomNavMeta
+};

package/dist/components/bottom-nav/index.js

@@ -0,0 +1,11 @@
+// src/components/bottom-nav/index.ts
+import {
+  BottomNav,
+  BottomNavItem
+} from "./bottom-nav.js";
+import { bottomNavMeta } from "./bottom-nav.meta.js";
+export {
+  BottomNav,
+  BottomNavItem,
+  bottomNavMeta
+};

package/dist/components/breadcrumbs/breadcrumbs.js

@@ -0,0 +1,90 @@
+// src/components/breadcrumbs/breadcrumbs.tsx
+import { Icon } from "../../icon/index.js";
+import { cn } from "../../lib/cn.js";
+import { jsx } from "react/jsx-runtime";
+function Breadcrumbs({
+  className,
+  children,
+  ref,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx("nav", { "aria-label": "Breadcrumb", ref, className, ...props, children: /* @__PURE__ */ jsx("ol", { className: "flex flex-wrap items-center gap-1.5 text-body-sm", children }) });
+}
+Breadcrumbs.displayName = "Breadcrumbs";
+function BreadcrumbItem({
+  className,
+  ref,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    "li",
+    {
+      ref,
+      className: cn("inline-flex items-center gap-1.5", className),
+      ...props
+    }
+  );
+}
+BreadcrumbItem.displayName = "BreadcrumbItem";
+function BreadcrumbLink({
+  className,
+  ref,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    "a",
+    {
+      ref,
+      className: cn(
+        "rounded-sm text-muted-foreground motion-interactive hover:text-foreground focus-visible:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        className
+      ),
+      ...props
+    }
+  );
+}
+BreadcrumbLink.displayName = "BreadcrumbLink";
+function BreadcrumbPage({
+  className,
+  ref,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    "span",
+    {
+      ref,
+      "aria-current": "page",
+      className: cn("text-foreground", className),
+      ...props
+    }
+  );
+}
+BreadcrumbPage.displayName = "BreadcrumbPage";
+function BreadcrumbSeparator({
+  className,
+  children,
+  ref,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    "li",
+    {
+      ref,
+      "aria-hidden": "true",
+      className: cn(
+        "inline-flex select-none items-center text-muted-foreground",
+        className
+      ),
+      ...props,
+      children: children ?? /* @__PURE__ */ jsx(Icon, { name: "chevron-right", className: "text-xs" })
+    }
+  );
+}
+BreadcrumbSeparator.displayName = "BreadcrumbSeparator";
+export {
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  Breadcrumbs
+};

package/dist/components/breadcrumbs/breadcrumbs.meta.js

@@ -0,0 +1,111 @@
+// src/components/breadcrumbs/breadcrumbs.meta.ts
+var breadcrumbsMeta = {
+  name: "Breadcrumbs",
+  summary: "Navigation trail showing the path to the current page. A labelled <nav> wraps an inline <ol> of crumbs \u2014 interactive ancestor links, separators, and a non-interactive current page. No Base UI.",
+  status: "stable",
+  keywords: [
+    "breadcrumbs",
+    "hierarchy",
+    "path",
+    "navigation"
+  ],
+  usage: {
+    description: "Use Breadcrumbs to show the user's location inside a hierarchy and provide lightweight parent navigation.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use breadcrumbs when users can arrive deep in a nested structure."
+      },
+      {
+        guidance: "do",
+        description: "Keep the current page as text so it reads as location, not another link."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use breadcrumbs as a substitute for primary navigation or step progress."
+      },
+      {
+        guidance: "dont",
+        description: "Do not make the last crumb a link. It points at the page you are already on, and screen readers announce it as a destination; render it as the current page with aria-current."
+      }
+    ],
+    anatomy: [
+      {
+        name: "BreadcrumbItem",
+        required: true,
+        description: "A single step in the path."
+      },
+      {
+        name: "BreadcrumbLink",
+        required: false,
+        description: "A linked ancestor destination."
+      },
+      {
+        name: "BreadcrumbPage",
+        required: true,
+        description: "The current non-linked page."
+      },
+      {
+        name: "BreadcrumbSeparator",
+        required: false,
+        description: "The visual separator between steps."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "SideNav",
+      "PageHeader"
+    ]
+  },
+  props: [
+    {
+      name: "Breadcrumbs",
+      type: "ComponentPropsWithRef<'nav'>",
+      default: "\u2014",
+      description: 'The trail root. Renders <nav aria-label="Breadcrumb"> around a flex <ol>. Pass the crumb parts as children.'
+    }
+  ],
+  subcomponents: [
+    {
+      name: "BreadcrumbItem",
+      type: "ComponentPropsWithRef<'li'>",
+      description: "A single crumb slot (<li>) holding a link or the current page."
+    },
+    {
+      name: "BreadcrumbLink",
+      type: "ComponentPropsWithRef<'a'>",
+      description: "An interactive ancestor crumb (<a>). Muted by default, brightens to foreground on hover/focus."
+    },
+    {
+      name: "BreadcrumbPage",
+      type: "ComponentPropsWithRef<'span'>",
+      description: 'The current-page crumb (<span aria-current="page">). Non-interactive, full-contrast.'
+    },
+    {
+      name: "BreadcrumbSeparator",
+      type: "ComponentPropsWithRef<'li'> + { children? }",
+      description: "Decorative divider (<li aria-hidden>) between crumbs. Defaults to a chevron-right icon; pass children to swap the glyph."
+    }
+  ],
+  tokensUsed: ["muted-foreground", "foreground"],
+  a11y: [
+    'The <nav> carries aria-label="Breadcrumb" so assistive tech announces the landmark.',
+    "Crumbs sit in an ordered list (<ol>) to convey hierarchy and position.",
+    'The current page uses aria-current="page" and is rendered as plain text, not a link.',
+    "Separators are aria-hidden so the chevron glyph is not announced."
+  ],
+  examples: [
+    {
+      label: "Three-level trail",
+      code: '<Breadcrumbs><BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem><BreadcrumbSeparator /><BreadcrumbItem><BreadcrumbLink href="/library">Library</BreadcrumbLink></BreadcrumbItem><BreadcrumbSeparator /><BreadcrumbItem><BreadcrumbPage>Editions</BreadcrumbPage></BreadcrumbItem></Breadcrumbs>'
+    },
+    {
+      label: "Custom separator",
+      code: '<Breadcrumbs><BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem><BreadcrumbSeparator>/</BreadcrumbSeparator><BreadcrumbItem><BreadcrumbPage>Settings</BreadcrumbPage></BreadcrumbItem></Breadcrumbs>'
+    }
+  ]
+};
+export {
+  breadcrumbsMeta
+};

package/dist/components/breadcrumbs/index.js

@@ -0,0 +1,17 @@
+// src/components/breadcrumbs/index.ts
+import {
+  Breadcrumbs,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator
+} from "./breadcrumbs.js";
+import { breadcrumbsMeta } from "./breadcrumbs.meta.js";
+export {
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  Breadcrumbs,
+  breadcrumbsMeta
+};