@sableui/react 0.6.2 → 0.7.1

package/dist/components/overflow-menu/overflow-menu.meta.js

@@ -0,0 +1,100 @@
+// src/components/overflow-menu/overflow-menu.meta.ts
+var overflowMenuMeta = {
+  name: "OverflowMenu",
+  summary: "An overflow ellipsis icon button that opens a Menu. Composes our Menu + Button + Icon \u2014 pass MenuItems as children and it wires the ghost icon trigger, accessible label, and portal-rendered content. All keyboard, focus, and dismissal behavior comes through Menu.",
+  status: "stable",
+  keywords: [
+    "dots menu",
+    "more actions",
+    "ellipsis",
+    "kebab"
+  ],
+  usage: {
+    description: "Use OverflowMenu for compact overflow actions when the primary action is already visible elsewhere.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it for secondary commands that belong to a row, card, or toolbar item."
+      },
+      {
+        guidance: "do",
+        description: "Keep labels explicit so the icon-only trigger does not obscure the command meaning."
+      },
+      {
+        guidance: "dont",
+        description: "Do not hide the most important or most frequent action inside OverflowMenu."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it as the only affordance on a touch surface. It is revealed on hover in most layouts, and hover does not exist on touch \u2014 pair it with a visible action or make it always-visible there."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Menu",
+      "ContextMenu"
+    ]
+  },
+  props: [
+    {
+      name: "children",
+      type: "ReactNode",
+      default: "\u2014",
+      description: "The menu rows \u2014 MenuItem / MenuSeparator / MenuGroup, etc. Rendered inside MenuContent."
+    },
+    {
+      name: "align",
+      type: "'start' | 'center' | 'end'",
+      default: "end",
+      description: "Alignment of the popup along its side. Overflow menus typically right-align under the trigger; 'start' anchors the popup's left edge to the trigger instead."
+    },
+    {
+      name: "label",
+      type: "string",
+      default: "More actions",
+      description: "Accessible label (aria-label) for the icon-only trigger button."
+    },
+    {
+      name: "icon",
+      type: "string",
+      default: "ellipsis",
+      description: "Semantic icon name rendered in the trigger, always at the solid weight."
+    },
+    {
+      name: "size",
+      type: "'icon' | 'icon-sm' | 'icon-xs'",
+      default: "icon",
+      description: "The trigger's rung on the icon-button ladder. 'icon' for a card or page header; 'icon-sm' or 'icon-xs' in a list row or dense toolbar, so the trigger does not set the row height."
+    }
+  ],
+  variants: {
+    size: ["icon", "icon-sm", "icon-xs"]
+  },
+  tokensUsed: [
+    "popover",
+    "popover-foreground",
+    "border",
+    "accent",
+    "accent-foreground",
+    "muted-foreground"
+  ],
+  a11y: [
+    "The icon-only trigger is labeled via aria-label (label prop, default 'More actions').",
+    "Menu provides role=menu/menuitem, roving tabindex, arrow-key navigation, and typeahead via Base UI.",
+    "Esc and outside-press dismiss; focus returns to the trigger on close."
+  ],
+  examples: [
+    {
+      label: "Basic",
+      code: '<OverflowMenu label="Post actions"><MenuItem>Edit</MenuItem><MenuItem>Share</MenuItem><MenuSeparator /><MenuItem variant="destructive">Delete</MenuItem></OverflowMenu>'
+    },
+    {
+      label: "With leading icons",
+      code: '<OverflowMenu><MenuItem><Icon name="check" className="text-sm" />Mark as read</MenuItem><MenuSeparator /><MenuItem variant="destructive"><Icon name="xmark" className="text-sm" />Delete</MenuItem></OverflowMenu>'
+    }
+  ]
+};
+export {
+  overflowMenuMeta
+};

package/dist/components/page-header/index.js

@@ -0,0 +1,7 @@
+// src/components/page-header/index.ts
+import { PageHeader } from "./page-header.js";
+import { pageHeaderMeta } from "./page-header.meta.js";
+export {
+  PageHeader,
+  pageHeaderMeta
+};

package/dist/components/page-header/page-header.js

@@ -0,0 +1,34 @@
+// src/components/page-header/page-header.tsx
+import { cn } from "../../lib/cn.js";
+import { HeadingRow } from "../../lib/heading-row.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function PageHeader({
+  title,
+  description,
+  back,
+  actions,
+  titleAs: Title = "h1",
+  className,
+  children,
+  ...props
+}) {
+  return /* @__PURE__ */ jsxs("div", { className: cn("flex flex-col gap-1 pb-4", className), ...props, children: [
+    /* @__PURE__ */ jsx(
+      HeadingRow,
+      {
+        as: Title,
+        title,
+        titleClassName: "text-heading-2",
+        band: "flex min-h-(--control-md) items-center",
+        leading: back,
+        actions
+      }
+    ),
+    description ? /* @__PURE__ */ jsx("p", { className: "text-body-sm text-muted-foreground", children: description }) : null,
+    children
+  ] });
+}
+PageHeader.displayName = "PageHeader";
+export {
+  PageHeader
+};

package/dist/components/page-header/page-header.meta.js

@@ -0,0 +1,104 @@
+// src/components/page-header/page-header.meta.ts
+var pageHeaderMeta = {
+  name: "PageHeader",
+  summary: "In-flow page heading block: a title row (optional back control + actions) over an optional description, with room for children (filters, tabs) below.",
+  status: "stable",
+  keywords: [
+    "page header",
+    "title",
+    "lede",
+    "page actions"
+  ],
+  usage: {
+    description: "Use PageHeader to establish a page's title, supporting description, and primary page actions.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use one PageHeader per major page or route."
+      },
+      {
+        guidance: "do",
+        description: "Keep the title literal and put explanation in the lede or nearby content."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use PageHeader inside repeated cards, dialogs, or compact panels."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use a second PageHeader for a section of the page. It is the route's one h1; each section below it takes a SectionHeader (an h2 with the same title row, description and actions)."
+      },
+      {
+        guidance: "dont",
+        description: "Do not put it outside the Region that holds the page content. It then sits at a different measure from what it introduces, and the page reads as two documents."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "AppHeader",
+      "SectionHeader",
+      "Breadcrumbs",
+      "Button"
+    ]
+  },
+  props: [
+    { name: "title", type: "ReactNode", description: "The page title (renders an <h1>)." },
+    {
+      name: "description",
+      type: "ReactNode",
+      description: "Supporting copy beneath the title."
+    },
+    {
+      name: "back",
+      type: "ReactNode",
+      description: 'Leading element before the title \u2014 typically a back control on drill-in routes. Keep it a ghost icon Button (size="icon", variant="ghost", aria-label="Back") so it stays quieter than the title. A ghost back control bleeds by its inset at the start, so its glyph lines up with the content edge below (Button bleed="none" opts out).'
+    },
+    {
+      name: "actions",
+      type: "ReactNode",
+      description: "Trailing actions aligned to the title row's end. They drop under the title when the row runs out of room, and the title wraps rather than truncating. A ghost or link Button at either end of the group bleeds by its own padding, so its label meets the content edge (the end on the title row, the start once wrapped); filled buttons keep their edge on the line. Direct children only."
+    },
+    {
+      name: "titleAs",
+      type: '"h1" | "h2"',
+      default: '"h1"',
+      description: "The title's heading element. Keep h1 \u2014 the route's one h1. Use h2 only when something above already owns the h1: a shell that renders the route title, or a page showing a PageHeader as an example."
+    }
+  ],
+  a11y: [
+    "Renders the title as an <h1>; use one PageHeader per page.",
+    "Its title renders the route's `h1`. Do not render another `h1` elsewhere on the page: heading navigation would report two documents, and the outline a screen-reader user builds from it stops matching the page."
+  ],
+  tokensUsed: ["foreground", "muted-foreground"],
+  examples: [
+    {
+      label: "With actions",
+      code: '<PageHeader title="Storage credits" description="Fund permanent storage." actions={<Button>Top up</Button>} />'
+    },
+    {
+      label: "One per page, inside the region",
+      code: `// PageHeader introduces the current route: title, optional description, and the
+// actions that act on THIS page.
+
+<Region max="content">
+  <PageHeader
+    title="Invoices"
+    description="Every charge on this account."
+    actions={<Button>Export</Button>}
+  />
+  <p className="text-body-md text-muted-foreground">Page content.</p>
+</Region>
+
+// \u2717 Outside the Region. The header then sits at a different measure from the
+//   content it introduces, and the page reads as two documents.
+// \u2717 Two on one page. A second one is a section heading: a SectionHeader
+//   (an h2 on text-heading-3, same title row and actions), not another PageHeader.
+// \u2717 Global actions in it (account, search). Those persist across routes and
+//   belong in AppHeader.`
+    }
+  ]
+};
+export {
+  pageHeaderMeta
+};

package/dist/components/page-loader/index.js

@@ -0,0 +1,7 @@
+// src/components/page-loader/index.ts
+import { PageLoader } from "./page-loader.js";
+import { pageLoaderMeta } from "./page-loader.meta.js";
+export {
+  PageLoader,
+  pageLoaderMeta
+};

package/dist/components/page-loader/page-loader.js

@@ -0,0 +1,37 @@
+// src/components/page-loader/page-loader.tsx
+import { cn } from "../../lib/cn.js";
+import { Progress } from "../progress/progress.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function PageLoader({
+  children,
+  label = "Loading",
+  fullscreen = true,
+  hideBar = false,
+  className,
+  ref,
+  ...props
+}) {
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref,
+      role: "status",
+      "aria-label": label,
+      className: cn(
+        fullscreen ? "fixed inset-0" : "absolute inset-0",
+        "z-(--z-overlay) flex flex-col items-center justify-center gap-6 bg-background animate-fade-in",
+        className
+      ),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx("div", { className: "motion-pulse", children: children ?? /* @__PURE__ */ jsx("span", { className: "block size-12 rounded-xl bg-foreground/90", "aria-hidden": true }) }),
+        label ? /* @__PURE__ */ jsx("p", { className: "text-label-md text-muted-foreground", children: label }) : null,
+        hideBar ? null : /* @__PURE__ */ jsx(Progress, { "aria-hidden": true, size: "sm", className: "w-24" })
+      ]
+    }
+  );
+}
+PageLoader.displayName = "PageLoader";
+export {
+  PageLoader
+};

package/dist/components/page-loader/page-loader.meta.js

@@ -0,0 +1,85 @@
+// src/components/page-loader/page-loader.meta.ts
+var pageLoaderMeta = {
+  name: "PageLoader",
+  summary: "Full-screen branded loading splash: the screen fades in, the mark breathes, and an indeterminate Progress bar pulses beneath it. All motion is token-driven, so it freezes to a calm static screen when motion is off/reduced.",
+  status: "stable",
+  keywords: [
+    "page loader",
+    "loading",
+    "route",
+    "pending"
+  ],
+  usage: {
+    description: "Use PageLoader for full-route or full-page pending states where the entire view is not ready yet.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it during route transitions, auth checks, or initial data loading."
+      },
+      {
+        guidance: "do",
+        description: "Prefer a clear page-level message when the wait may take noticeable time."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use PageLoader for small inline waits; use Spinner, an indeterminate Progress, or Skeleton."
+      },
+      {
+        guidance: "dont",
+        description: "Do not leave it mounted if the route's data can fail. It covers the whole viewport, so a PageLoader that never resolves is indistinguishable from a hung application \u2014 always give it a failure path."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Spinner",
+      "Skeleton",
+      "Progress"
+    ]
+  },
+  props: [
+    {
+      name: "children",
+      type: "ReactNode",
+      description: "Brand mark / logo shown at center. Falls back to a neutral pulsing mark."
+    },
+    {
+      name: "label",
+      type: "string",
+      default: '"Loading"',
+      description: "Caption beneath the mark; also the accessible label on the role=status region."
+    },
+    {
+      name: "fullscreen",
+      type: "boolean",
+      default: "true",
+      description: "Cover the viewport (fixed) vs fill the nearest positioned parent (absolute)."
+    },
+    {
+      name: "hideBar",
+      type: "boolean",
+      default: "false",
+      description: "Hide the indeterminate Progress bar under the mark."
+    }
+  ],
+  tokensUsed: ["background", "foreground", "secondary", "primary", "muted-foreground"],
+  a11y: [
+    "role=status with an aria-label (the label prop) announces the loading state politely.",
+    "Decorative mark and bar are aria-hidden.",
+    "Motion respects the policy: under off/reduced the pulses hold their first frame (static)."
+  ],
+  examples: [
+    { label: "Default", code: '<PageLoader label="Loading Studio" />' },
+    {
+      label: "With a logo",
+      code: '<PageLoader label="Loading"><img src="/logo.svg" alt="" className="h-10 w-auto" /></PageLoader>'
+    },
+    {
+      label: "Contained (fills parent)",
+      code: '<div className="relative h-80"><PageLoader fullscreen={false} hideBar /></div>'
+    }
+  ]
+};
+export {
+  pageLoaderMeta
+};

package/dist/components/pagination/index.js

@@ -0,0 +1,7 @@
+// src/components/pagination/index.ts
+import { Pagination } from "./pagination.js";
+import { paginationMeta } from "./pagination.meta.js";
+export {
+  Pagination,
+  paginationMeta
+};

package/dist/components/pagination/pagination.js

@@ -0,0 +1,105 @@
+"use client";
+
+// src/components/pagination/pagination.tsx
+import { cn } from "../../lib/cn.js";
+import { Button } from "../button/button.js";
+import { Icon } from "../../icon/Icon.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var ELLIPSIS = "ellipsis";
+function buildRange(page, total, siblingCount) {
+  const totalSlots = siblingCount * 2 + 5;
+  if (total <= totalSlots) {
+    return Array.from({ length: total }, (_, i) => i + 1);
+  }
+  const range = (from, to) => Array.from({ length: to - from + 1 }, (_, i) => from + i);
+  const left = Math.max(page - siblingCount, 1);
+  const right = Math.min(page + siblingCount, total);
+  const showLeftEllipsis = left > 2;
+  const showRightEllipsis = right < total - 1;
+  const endRun = totalSlots - 2;
+  if (!showLeftEllipsis) {
+    return [...range(1, endRun), ELLIPSIS, total];
+  }
+  if (!showRightEllipsis) {
+    return [1, ELLIPSIS, ...range(total - endRun + 1, total)];
+  }
+  return [1, ELLIPSIS, ...range(left, right), ELLIPSIS, total];
+}
+function Pagination({
+  page,
+  total,
+  onPageChange,
+  siblingCount = 1,
+  label = "Pagination",
+  className,
+  ref,
+  ...props
+}) {
+  const safeTotal = Math.max(total, 1);
+  const current = Math.min(Math.max(page, 1), safeTotal);
+  const items = buildRange(current, safeTotal, siblingCount);
+  const goTo = (next) => {
+    if (next < 1 || next > safeTotal || next === current) return;
+    onPageChange(next);
+  };
+  return /* @__PURE__ */ jsxs(
+    "nav",
+    {
+      ref,
+      "aria-label": label,
+      className: cn("flex items-center gap-1", className),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx(
+          Button,
+          {
+            variant: "ghost",
+            size: "icon-sm",
+            "aria-label": "Previous page",
+            disabled: current <= 1,
+            onClick: () => goTo(current - 1),
+            children: /* @__PURE__ */ jsx(Icon, { name: "chevron-left", className: "text-base" })
+          }
+        ),
+        /* @__PURE__ */ jsx("ul", { className: "flex items-center gap-1", children: items.map(
+          (item, index) => item === ELLIPSIS ? /* @__PURE__ */ jsx(
+            "li",
+            {
+              "aria-hidden": "true",
+              className: "flex h-(--control-sm) w-(--control-sm) items-center justify-center text-muted-foreground",
+              children: /* @__PURE__ */ jsx(Icon, { name: "ellipsis", className: "text-base" })
+            },
+            `ellipsis-${index}`
+          ) : /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsx(
+            Button,
+            {
+              variant: item === current ? "secondary" : "ghost",
+              size: "icon-sm",
+              className: "w-auto min-w-(--control-sm) px-1 tabular-nums",
+              "aria-label": `Page ${item}`,
+              "aria-current": item === current ? "page" : void 0,
+              onClick: () => goTo(item),
+              children: item
+            }
+          ) }, item)
+        ) }),
+        /* @__PURE__ */ jsx(
+          Button,
+          {
+            variant: "ghost",
+            size: "icon-sm",
+            "aria-label": "Next page",
+            disabled: current >= safeTotal,
+            onClick: () => goTo(current + 1),
+            children: /* @__PURE__ */ jsx(Icon, { name: "chevron-right", className: "text-base" })
+          }
+        )
+      ]
+    }
+  );
+}
+Pagination.displayName = "Pagination";
+export {
+  Pagination,
+  buildRange
+};

package/dist/components/pagination/pagination.meta.js

@@ -0,0 +1,141 @@
+// src/components/pagination/pagination.meta.ts
+var paginationMeta = {
+  name: "Pagination",
+  summary: "Page navigation built from our own Button + Icon (no Base UI). A <nav aria-label='Pagination'> with prev/next icon buttons that disable at the bounds and numbered page buttons; the current page is a secondary button marked aria-current. Collapses to first/last/current plus a sibling window, bridging skipped runs with an ellipsis.",
+  keywords: [
+    "pagination",
+    "pager",
+    "pages",
+    "table",
+    "results",
+    "navigation",
+    "next",
+    "previous"
+  ],
+  usage: {
+    description: "Use Pagination when a result set is split into discrete pages and the user needs predictable movement through them. Pair it with DataTable, list results, or server-paged views; use a load-more Button or infinite scroll when page numbers are not meaningful.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Keep page state controlled by the parent route or data layer so URL, filters, and result fetches stay in sync."
+      },
+      {
+        guidance: "do",
+        description: 'Use a specific label when multiple pagers appear on a page, such as "Collector pages".'
+      },
+      {
+        guidance: "do",
+        description: "Reset to page 1 when filters or search terms materially change the result set."
+      },
+      {
+        guidance: "dont",
+        description: "Use Pagination for tiny lists where all items fit comfortably on one page."
+      },
+      {
+        guidance: "dont",
+        description: "Hide disabled previous/next buttons at the bounds; disabled controls make the current position clearer."
+      }
+    ],
+    anatomy: [
+      {
+        name: "Nav",
+        required: true,
+        description: "The labelled pagination landmark."
+      },
+      {
+        name: "Previous/next",
+        required: true,
+        description: "Icon buttons for adjacent page movement, disabled at the bounds."
+      },
+      {
+        name: "Page buttons",
+        required: true,
+        description: "Numbered buttons with aria-current on the active page."
+      },
+      {
+        name: "Ellipsis",
+        required: false,
+        description: "Non-interactive marker for skipped page ranges."
+      }
+    ]
+  },
+  related: {
+    components: ["DataTable", "Table", "Button"],
+    patterns: ["ListDetailPage", "DashboardPage"]
+  },
+  status: "stable",
+  props: [
+    {
+      name: "page",
+      type: "number",
+      default: "\u2014",
+      description: "The active page (1-based). Clamped into the valid range."
+    },
+    {
+      name: "total",
+      type: "number",
+      default: "\u2014",
+      description: "Total number of pages."
+    },
+    {
+      name: "onPageChange",
+      type: "(page: number) => void",
+      default: "\u2014",
+      description: "Called with the next page when a control is activated. No-op for out-of-range or unchanged values."
+    },
+    {
+      name: "siblingCount",
+      type: "number",
+      default: "1",
+      description: "Page buttons shown on each side of the current page before the list collapses into ellipses. First and last pages are always shown."
+    },
+    {
+      name: "label",
+      type: "string",
+      default: "Pagination",
+      description: "Accessible label applied to the surrounding nav element."
+    },
+    {
+      name: "className",
+      type: "string",
+      default: "\u2014",
+      description: "Extra classes merged onto the nav."
+    }
+  ],
+  tokensUsed: [
+    "secondary",
+    "secondary-foreground",
+    "accent",
+    "accent-foreground",
+    "foreground",
+    "muted-foreground",
+    "ring"
+  ],
+  a11y: [
+    "Renders a landmark <nav> with aria-label so assistive tech can jump to the pager.",
+    "The current page button carries aria-current='page'.",
+    "Prev/next buttons are real <button>s with aria-label and become disabled at the bounds.",
+    "Ellipsis slots are aria-hidden \u2014 they convey no navigable target."
+  ],
+  examples: [
+    {
+      label: "Controlled",
+      code: "const [page, setPage] = useState(1)\n<Pagination page={page} total={10} onPageChange={setPage} />"
+    },
+    {
+      label: "Many pages (ellipsis)",
+      code: "const [page, setPage] = useState(8)\n<Pagination page={page} total={20} onPageChange={setPage} />"
+    },
+    {
+      label: "Table results footer",
+      code: '<Stack gap={2}><DataTable data={rows} columns={columns} rowKey={(row) => row.id} /><Pagination label="Collector pages" page={page} total={12} onPageChange={setPage} /></Stack>'
+    },
+    {
+      label: "Server query state",
+      code: "const [page, setPage] = useState(searchParams.page ?? 1)\n<Pagination page={page} total={pageCount} onPageChange={(next) => { setPage(next); loadPage(next) }} />"
+    }
+  ]
+};
+export {
+  paginationMeta
+};

package/dist/components/panel-group/index.js

@@ -0,0 +1,10 @@
+// src/components/panel-group/index.ts
+import { Panel, PanelGroup, PanelResizer, usePanelWidth } from "./panel-group.js";
+import { panelGroupMeta } from "./panel-group.meta.js";
+export {
+  Panel,
+  PanelGroup,
+  PanelResizer,
+  panelGroupMeta,
+  usePanelWidth
+};