@sableui/react 0.18.0 → 0.19.0

package/dist/components/avatar/avatar.meta.js

@@ -1,7 +1,7 @@
 // src/components/avatar/avatar.meta.ts
 var avatarMeta = {
   name: "Avatar",
-  summary: 'Circular profile image over Base UI Avatar \u2014 automatic image-load tracking with an initials/glyph fallback. Ergonomic Avatar plus low-level AvatarRoot/AvatarImage/AvatarFallback parts, and AvatarGroup for an overlapping stack with a "+N" overflow count.',
+  summary: 'Circular (or square) profile image over Base UI Avatar \u2014 automatic image-load tracking with an initials/glyph fallback. Ergonomic Avatar plus low-level AvatarRoot/AvatarImage/AvatarFallback parts, and AvatarGroup for an overlapping stack with a "+N" overflow count.',
   keywords: [
     "avatar",
     "profile",
@@ -14,7 +14,12 @@ var avatarMeta = {
     "stack",
     "overflow",
     "collaborators",
-    "facepile"
+    "facepile",
+    "monogram",
+    "project mark",
+    "workspace icon",
+    "org logo",
+    "assignee"
   ],
   usage: {
     description: 'Use Avatar to represent a person, team, or account with a compact visual identity. Wrap several in AvatarGroup for collaborators, assignees, or attendees \u2014 it overlaps them, rings each in the surface colour, and collapses the rest into a "+N" count; use the low-level parts only when you need custom image/fallback layout.',
@@ -33,12 +38,16 @@ var avatarMeta = {
       },
       {
         guidance: "do",
-        description: "Pick the size by the job: sm in dense rows and tables, md (the default) beside one line of text, lg in a row with a title and subtitle, xl (96px) for a profile header beside the person's name, 2xl (160px) for an artist or profile hero and roster portraits. Keep one size within a list or group."
+        description: "Pick the size by the job: 2xs (20px) or xs (24px) in a compact workspace row (an assignee in an issue list, a project mark in a nav item), sm in dense rows and tables, md (the default) beside one line of text, lg in a row with a title and subtitle, xl (96px) for a profile header beside the person's name, 2xl (160px) for an artist or profile hero and roster portraits. Keep one size within a list or group."
       },
       {
         guidance: "do",
         description: 'Use AvatarGroup for a stack of people, and give it an aria-label with the real count ("12 collaborators"). Set `surface` (or `--avatar-group-ring`) to whatever the group sits on, so the separating ring matches a card or popover, not the page. When it shares a row with actions, set `fit` so it gives up avatars to the "+N" count before the row has to wrap.'
       },
+      {
+        guidance: "do",
+        description: 'Use `shape="square"` for what is not a person (a workspace, a project, an org, a team), with `tone` set to a palette family so each one keeps its own colour: `<Avatar shape="square" tone="teal" fallback="N" alt="Northwind storefront" size="xs" />`. Circles mean people; keep that distinction across the app.'
+      },
       {
         guidance: "dont",
         description: 'Hand-build a stack with negative margins and per-avatar ring classes, or fake the overflow as an Avatar with "+4" initials \u2014 screen readers hear "plus 4" with no context. Use AvatarGroup\'s `max`/`total`, or AvatarGroupCount.'
@@ -53,7 +62,7 @@ var avatarMeta = {
       },
       {
         guidance: "dont",
-        description: 'Build a portrait by stretching an Avatar with size classes (`className="size-40"`) \u2014 the initials, the status indicator and the image fade stay at row scale. Use size="xl" or "2xl", which scale all three. Past 160px, or for a non-circular cover, it is media: an AspectBox, not an avatar.'
+        description: 'Resize an Avatar with size classes (`className="size-5"`, `className="size-40"`) \u2014 the initials, the status indicator and the image fade stay at the size they were drawn for. Use size="2xs"/"xs" for dense rows and size="xl"/"2xl" for portraits, which scale all three. Don\'t hand-build a tinted initials tile for a project or workspace mark either: that is Avatar shape="square" with a tone. Past 160px, or for a cover, it is media: an AspectBox, not an avatar.'
       }
     ],
     anatomy: [
@@ -118,9 +127,21 @@ var avatarMeta = {
     },
     {
       name: "size",
-      type: '"sm" | "md" | "lg" | "xl" | "2xl"',
+      type: '"2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"',
       default: '"md"',
-      description: "Square footprint: 32px / 40px / 48px for rows; 96px / 160px for portraits (a profile header, an artist hero, a roster tile). The initials, a status indicator and its cut-out ring scale with it, and at the portrait sizes the photo fades in over the resting surface."
+      description: "Square footprint: 20px / 24px for compact workspace rows; 32px / 40px / 48px for rows; 96px / 160px for portraits (a profile header, an artist hero, a roster tile). The initials, a status indicator and its cut-out ring scale with it, and at the portrait sizes the photo fades in over the resting surface."
+    },
+    {
+      name: "shape",
+      type: '"circle" | "square"',
+      default: '"circle"',
+      description: "The frame's corner. circle is a person. square is what is not a face \u2014 a workspace, a project, an org, a team \u2014 with a radius from the theme's steps that grows with the size (4px at 20\u201324px to 20px at 160px), so a square theme stays square. A status indicator sits on the square's corner."
+    },
+    {
+      name: "tone",
+      type: '"neutral" | "red" | "orange" | "yellow" | "green" | "teal" | "blue" | "purple" | "pink"',
+      default: '"neutral"',
+      description: `The fallback's colour. neutral is the muted surface; a palette family paints its wash behind the initials and its deep ink on them (a soft Badge's pair, held to contrast in every theme), for a category colour such as one per project. Ignored by variant="art", which colours by seed.`
     },
     {
       name: "variant",
@@ -137,7 +158,7 @@ var avatarMeta = {
   subcomponents: [
     {
       name: "AvatarRoot",
-      type: "Base UI Avatar.Root props + size + className",
+      type: "Base UI Avatar.Root props + size + shape + tone + className",
       description: "Low-level circular frame for full composition control \u2014 clips the image and holds the `size` axis. Wraps AvatarImage and AvatarFallback."
     },
     {
@@ -152,17 +173,18 @@ var avatarMeta = {
     },
     {
       name: "AvatarGroup",
-      type: '{ size?: "sm" | "md" | "lg"; surface?: "background" | "card" | "popover" | "muted"; max?: number; fit?: boolean; total?: number; countLabel?: (count: number) => string; "aria-label"?: string; className?: string; children: ReactNode }',
+      type: '{ size?: "2xs" | "xs" | "sm" | "md" | "lg"; surface?: "background" | "card" | "popover" | "muted"; max?: number; fit?: boolean; total?: number; countLabel?: (count: number) => string; "aria-label"?: string; className?: string; children: ReactNode }',
       description: 'Overlapping stack (role=group) \u2014 name it with aria-label ("12 collaborators"). `size` applies to every avatar inside. `max` shows that many and collapses the rest into a "+N" count; `total` is the real head-count when you only pass some people. `fit` shows only as many avatars as fit the width the group is given (it fills the space left in a flex row) and folds the rest into the count, so a tight row reads "MO SR +5" instead of wrapping. The separating ring reads the inherited `--avatar-group-ring` (default: the page background); `surface` sets it to card, popover, or muted.'
     },
     {
       name: "AvatarGroupCount",
-      type: '{ count: number; label?: string; size?: "sm" | "md" | "lg"; className?: string }',
+      type: '{ count: number; label?: string; size?: "2xs" | "xs" | "sm" | "md" | "lg"; className?: string }',
       description: 'The "+N" avatar. Shows "+4" and reads "and 4 more" (override with label). AvatarGroup renders it for you from max/total; use it directly only when composing the stack yourself.'
     }
   ],
   variants: {
-    size: ["sm", "md", "lg", "xl", "2xl"],
+    size: ["2xs", "xs", "sm", "md", "lg", "xl", "2xl"],
+    shape: ["circle", "square"],
     variant: ["neutral", "art"]
   },
   tokensUsed: ["muted", "muted-foreground", "background", "card", "popover", "overlay", "overlay-foreground"],
@@ -205,6 +227,17 @@ var avatarMeta = {
 		<p className="text-body-sm text-muted-foreground">1.2M monthly listeners</p>
 	</div>
 </div>`
+    },
+    {
+      label: "Dense row sizes",
+      code: `<Avatar fallback="EL" alt="Emma Lee" size="2xs" />
+<Avatar fallback="EL" alt="Emma Lee" size="xs" />`
+    },
+    {
+      label: "Project marks",
+      code: `<Avatar shape="square" tone="teal" size="xs" fallback="N" alt="Northwind storefront" />
+<Avatar shape="square" tone="orange" size="xs" fallback="H" alt="Harbor brand refresh" />
+<Avatar shape="square" tone="purple" size="xs" fallback="L" alt="Lumen editorial" />`
     },
     {
       label: "Low-level parts",

package/dist/components/avatar/avatar.variants.js

@@ -1,19 +1,40 @@
 // src/components/avatar/avatar.variants.ts
 import { cva } from "class-variance-authority";
+var AVATAR_SQUARE_RADIUS = {
+  "2xs": "rounded-xs",
+  xs: "rounded-xs",
+  sm: "rounded-sm",
+  md: "rounded-sm",
+  lg: "rounded-md",
+  xl: "rounded-lg",
+  "2xl": "rounded-xl"
+};
 var avatarVariants = cva(
-  "relative inline-flex shrink-0 select-none items-center justify-center overflow-hidden rounded-full bg-muted",
+  "relative inline-flex shrink-0 select-none items-center justify-center overflow-hidden bg-muted",
   {
     variants: {
       size: {
+        "2xs": "size-5 text-ui-micro",
+        xs: "size-6 text-label-xs",
         sm: "size-8 text-label-sm",
         md: "size-10 text-label-md",
         lg: "size-12 text-label-lg",
         xl: "size-24 text-heading-2",
         "2xl": "size-40 text-display-lg"
+      },
+      shape: {
+        circle: "rounded-full",
+        square: ""
       }
     },
+    compoundVariants: Object.entries(AVATAR_SQUARE_RADIUS).map(([size, className]) => ({
+      shape: "square",
+      size,
+      className
+    })),
     defaultVariants: {
-      size: "md"
+      size: "md",
+      shape: "circle"
     }
   }
 );
@@ -22,6 +43,8 @@ var avatarGroupVariants = cva(
   {
     variants: {
       size: {
+        "2xs": "*:not-first:-ms-1",
+        xs: "*:not-first:-ms-1",
         sm: "*:not-first:-ms-1",
         md: "*:not-first:-ms-1.5",
         lg: "*:not-first:-ms-2"
@@ -39,6 +62,7 @@ var avatarGroupVariants = cva(
   }
 );
 export {
+  AVATAR_SQUARE_RADIUS,
   avatarGroupVariants,
   avatarVariants
 };

package/dist/components/collapsible/collapsible.js

@@ -5,15 +5,16 @@ import { cn } from "../../lib/cn.js";
 import { jsx } from "react/jsx-runtime";
 var Collapsible = Base.Root;
 var CollapsibleTrigger = Base.Trigger;
-function CollapsibleIndicator({ className }) {
+var DIRECTION = {
+  down: "[[data-panel-open]_&]:rotate-180",
+  end: "-rotate-90 rtl:rotate-90 [[data-panel-open]_&]:rotate-0"
+};
+function CollapsibleIndicator({ direction = "down", className }) {
   return /* @__PURE__ */ jsx(
     Icon,
     {
       name: "chevron-down",
-      className: cn(
-        "text-xs text-muted-foreground motion-interactive group-data-[panel-open]/collapsible:rotate-180",
-        className
-      )
+      className: cn("text-xs text-muted-foreground motion-interactive", DIRECTION[direction], className)
     }
   );
 }

package/dist/components/collapsible/collapsible.meta.js

@@ -7,7 +7,12 @@ var collapsibleMeta = {
     "collapsible",
     "disclosure",
     "expand",
-    "collapse"
+    "collapse",
+    "chevron",
+    "caret",
+    "rotate",
+    "group header",
+    "section toggle"
   ],
   usage: {
     description: "Use Collapsible for a single piece of optional content that can expand in place.",
@@ -87,8 +92,8 @@ var collapsibleMeta = {
     },
     {
       name: "CollapsibleIndicator",
-      type: "{ className? }",
-      description: "Auto-rotating disclosure chevron. Place it inside the trigger content and add the `group/collapsible` class to the trigger so it flips 180\xB0 on open."
+      type: '{ direction?: "down" | "end"; className? }',
+      description: `Auto-rotating disclosure chevron. Place it anywhere inside the trigger content; it reads the trigger's open state itself, no class to add. direction="down" (default) flips 180\xB0 on open; direction="end" points to the inline end while closed and turns down on open \u2014 the caret for a grouped list's section header or a tree row. Use it instead of rotating your own chevron with CSS, which snaps with no transition.`
     }
   ],
   tokensUsed: ["foreground", "muted-foreground"],
@@ -115,7 +120,7 @@ var collapsibleMeta = {
       slot: "transition",
       recipe: "motion-interactive",
       part: "CollapsibleIndicator",
-      why: "The chevron turns with the panel rather than flipping in one frame: motion-interactive lists `rotate`, the property rotate-180 writes."
+      why: "The chevron turns with the panel rather than flipping in one frame: motion-interactive lists `rotate`, the property rotate-180 and rotate-0 write."
     },
     {
       slot: "activity",
@@ -141,7 +146,11 @@ var collapsibleMeta = {
     },
     {
       label: "With rotating chevron",
-      code: '<Collapsible><CollapsibleTrigger className="group/collapsible" render={<Button variant="ghost">Details <CollapsibleIndicator /></Button>} /><CollapsiblePanel><p className="pt-3">Revealed on toggle.</p></CollapsiblePanel></Collapsible>'
+      code: '<Collapsible><CollapsibleTrigger render={<Button variant="ghost">Details <CollapsibleIndicator /></Button>} /><CollapsiblePanel><p className="pt-3">Revealed on toggle.</p></CollapsiblePanel></Collapsible>'
+    },
+    {
+      label: "Group header with a side caret",
+      code: '<Collapsible defaultOpen><CollapsibleTrigger render={<Button variant="ghost" size="xs"><CollapsibleIndicator direction="end" />In progress <span className="text-ui-num text-muted-foreground">5</span></Button>} /><CollapsiblePanel><ul className="text-ui-body"><li>Refine product detail page</li><li>Build the ingredient library</li></ul></CollapsiblePanel></Collapsible>'
     }
   ]
 };

package/dist/components/data-table/data-table.js

@@ -1,7 +1,7 @@
 "use client";
 
 // src/components/data-table/data-table.tsx
-import { useMemo, useState } from "react";
+import { useId, useMemo, useState } from "react";
 import { Icon } from "../../icon/index.js";
 import { cn } from "../../lib/cn.js";
 import { Button } from "../button/button.js";
@@ -15,7 +15,7 @@ import {
   TableHeader,
   TableRow
 } from "../table/index.js";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 var ALIGN = {
   start: "text-start",
   center: "text-center",
@@ -36,9 +36,18 @@ function DataTable({
   defaultSort,
   empty = "No results.",
   caption,
+  groupBy,
+  groups,
+  collapsible = true,
+  expandedGroups,
+  onExpandedGroupsChange,
   className
 }) {
   const [sort, setSort] = useState(defaultSort ?? null);
+  const [closedGroups, setClosedGroups] = useState(
+    () => new Set((groups ?? []).filter((g) => g.defaultExpanded === false).map((g) => g.key))
+  );
+  const uid = useId();
   function toggleSort(key) {
     setSort((prev) => {
       if (prev?.key !== key) return { key, direction: "asc" };
@@ -63,13 +72,44 @@ function DataTable({
       return sort.direction === "asc" ? c : -c;
     });
   }, [data, sort, columns]);
+  const sections = useMemo(() => {
+    if (!groupBy) return null;
+    const byKey = /* @__PURE__ */ new Map();
+    for (const row of data) {
+      const key = groupBy(row);
+      if (!byKey.has(key)) byKey.set(key, []);
+    }
+    rows.forEach((row, index) => byKey.get(groupBy(row))?.push({ row, index }));
+    const listed = new Map((groups ?? []).map((g) => [g.key, g]));
+    const order = [...listed.keys(), ...[...byKey.keys()].filter((k) => !listed.has(k))];
+    return order.filter((key) => (byKey.get(key)?.length ?? 0) > 0).map((key) => ({ key, group: listed.get(key), items: byKey.get(key) ?? [] }));
+  }, [groupBy, groups, data, rows]);
+  const isExpanded = (key) => !collapsible || (expandedGroups ? expandedGroups.has(key) : !closedGroups.has(key));
+  function toggleGroup(key) {
+    const open = isExpanded(key);
+    if (!expandedGroups) {
+      setClosedGroups((prev) => {
+        const next = new Set(prev);
+        if (open) next.add(key);
+        else next.delete(key);
+        return next;
+      });
+    }
+    if (onExpandedGroupsChange) {
+      const next = new Set((sections ?? []).map((s) => s.key).filter(isExpanded));
+      if (open) next.delete(key);
+      else next.add(key);
+      onExpandedGroupsChange(next);
+    }
+  }
+  const shownRows = sections ? sections.flatMap((s) => isExpanded(s.key) ? s.items.map((it) => it.row) : []) : rows;
   const selectable = Boolean(onSelectedKeysChange);
   const dataIndex = selectable ? new Map(data.map((row, i) => [row, i])) : null;
   const keyOf = (row) => {
     const i = dataIndex?.get(row) ?? 0;
     return rowKey ? rowKey(row, i) : i;
   };
-  const shownKeys = selectable ? rows.map(keyOf) : [];
+  const shownKeys = selectable ? shownRows.map(keyOf) : [];
   const checkedCount = selectable ? shownKeys.filter((k) => selectedKeys?.has(k)).length : 0;
   const allChecked = shownKeys.length > 0 && checkedCount === shownKeys.length;
   function setChecked(keys, checked) {
@@ -80,6 +120,50 @@ function DataTable({
     }
     onSelectedKeysChange?.(next);
   }
+  const span = columns.length + (selectable ? 1 : 0);
+  function renderRow(row, i, hidden = false) {
+    const key = selectable ? keyOf(row) : i;
+    const checked = selectable && Boolean(selectedKeys?.has(key));
+    return /* @__PURE__ */ jsxs(
+      TableRow,
+      {
+        hidden: hidden || void 0,
+        "data-selected": checked || isRowSelected?.(row) ? "" : void 0,
+        onClick: onRowClick ? () => onRowClick(row) : void 0,
+        tabIndex: onRowClick ? 0 : void 0,
+        onKeyDown: onRowClick ? (e) => {
+          if (e.target !== e.currentTarget) return;
+          if (e.key !== "Enter" && e.key !== " ") return;
+          e.preventDefault();
+          onRowClick(row);
+        } : void 0,
+        className: onRowClick ? "cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring" : void 0,
+        children: [
+          selectable ? (
+            // A click on the box checks it; it never opens the row.
+            /* @__PURE__ */ jsx(TableCell, { className: "w-0", onClick: (e) => e.stopPropagation(), children: /* @__PURE__ */ jsx(
+              Checkbox,
+              {
+                "aria-label": rowSelectionLabel(row),
+                checked,
+                onCheckedChange: (next) => setChecked([key], next),
+                className: "align-middle"
+              }
+            ) })
+          ) : null,
+          columns.map((col) => /* @__PURE__ */ jsx(
+            TableCell,
+            {
+              className: cn(col.align && ALIGN[col.align], col.className),
+              children: col.cell ? col.cell(row) : row[col.key]
+            },
+            col.key
+          ))
+        ]
+      },
+      rowKey ? rowKey(row, i) : i
+    );
+  }
   return /* @__PURE__ */ jsxs(Table, { className, children: [
     caption ? /* @__PURE__ */ jsx(TableCaption, { children: caption }) : null,
     /* @__PURE__ */ jsx(TableHeader, { children: /* @__PURE__ */ jsxs(TableRow, { children: [
@@ -139,58 +223,61 @@ function DataTable({
         );
       })
     ] }) }),
-    /* @__PURE__ */ jsx(TableBody, { children: rows.length === 0 ? /* @__PURE__ */ jsx(TableRow, { children: /* @__PURE__ */ jsx(
+    rows.length === 0 ? /* @__PURE__ */ jsx(TableBody, { children: /* @__PURE__ */ jsx(TableRow, { children: /* @__PURE__ */ jsx(
       TableCell,
       {
-        colSpan: columns.length + (selectable ? 1 : 0),
+        colSpan: span,
         className: cn(
           "text-center text-muted-foreground",
           typeof empty === "string" && "py-8"
         ),
         children: empty
       }
-    ) }) : rows.map((row, i) => {
-      const key = selectable ? keyOf(row) : i;
-      const checked = selectable && Boolean(selectedKeys?.has(key));
-      return /* @__PURE__ */ jsxs(
-        TableRow,
-        {
-          "data-selected": checked || isRowSelected?.(row) ? "" : void 0,
-          onClick: onRowClick ? () => onRowClick(row) : void 0,
-          tabIndex: onRowClick ? 0 : void 0,
-          onKeyDown: onRowClick ? (e) => {
-            if (e.target !== e.currentTarget) return;
-            if (e.key !== "Enter" && e.key !== " ") return;
-            e.preventDefault();
-            onRowClick(row);
-          } : void 0,
-          className: onRowClick ? "cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring" : void 0,
-          children: [
-            selectable ? (
-              // A click on the box checks it; it never opens the row.
-              /* @__PURE__ */ jsx(TableCell, { className: "w-0", onClick: (e) => e.stopPropagation(), children: /* @__PURE__ */ jsx(
-                Checkbox,
-                {
-                  "aria-label": rowSelectionLabel(row),
-                  checked,
-                  onCheckedChange: (next) => setChecked([key], next),
-                  className: "align-middle"
-                }
-              ) })
-            ) : null,
-            columns.map((col) => /* @__PURE__ */ jsx(
-              TableCell,
+    ) }) }) : sections ? sections.map(({ key, group, items }, n) => {
+      const expanded = isExpanded(key);
+      const bodyId = `${uid}-group-${n}`;
+      const name = /* @__PURE__ */ jsxs(Fragment, { children: [
+        group?.icon,
+        /* @__PURE__ */ jsx("span", { children: group?.label ?? key }),
+        /* @__PURE__ */ jsx("span", { className: "tabular-nums text-muted-foreground", children: items.length })
+      ] });
+      return (
+        // One tbody per group: a row group to assistive tech, headed by its
+        // own header row, so the group rows are never read as data rows.
+        /* @__PURE__ */ jsxs(TableBody, { id: bodyId, "data-group": key, children: [
+          /* @__PURE__ */ jsx(TableRow, { "data-group-header": "", className: "border-t [tbody>&:hover]:bg-transparent", children: /* @__PURE__ */ jsx(TableHead, { scope: "rowgroup", colSpan: span, className: "h-auto bg-muted/50 py-1 text-foreground", children: /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 items-center justify-between gap-2", children: [
+            collapsible ? /* @__PURE__ */ jsxs(
+              Button,
               {
-                className: cn(col.align && ALIGN[col.align], col.className),
-                children: col.cell ? col.cell(row) : row[col.key]
-              },
-              col.key
-            ))
-          ]
-        },
-        rowKey ? rowKey(row, i) : i
+                variant: "ghost",
+                size: "xs",
+                bleed: "start",
+                "aria-expanded": expanded,
+                "aria-controls": bodyId,
+                onClick: () => toggleGroup(key),
+                className: "gap-2",
+                children: [
+                  /* @__PURE__ */ jsx(
+                    Icon,
+                    {
+                      name: "chevron-down",
+                      className: cn(
+                        "text-xs text-muted-foreground motion-interactive",
+                        // Closed, it points along the reading direction.
+                        !expanded && "-rotate-90 rtl:rotate-90"
+                      )
+                    }
+                  ),
+                  name
+                ]
+              }
+            ) : /* @__PURE__ */ jsx("span", { className: "flex min-w-0 items-center gap-2", children: name }),
+            group?.action ? /* @__PURE__ */ jsx("div", { className: "flex shrink-0 items-center gap-1", children: group.action }) : null
+          ] }) }) }),
+          items.map(({ row, index }) => renderRow(row, index, !expanded))
+        ] }, key)
       );
-    }) })
+    }) : /* @__PURE__ */ jsx(TableBody, { children: rows.map((row, i) => renderRow(row, i)) })
   ] });
 }
 DataTable.displayName = "DataTable";

package/dist/components/data-table/data-table.meta.js

@@ -1,7 +1,7 @@
 // src/components/data-table/data-table.meta.ts
 var dataTableMeta = {
   name: "DataTable",
-  summary: "A data-driven table over the Table primitives \u2014 a columns def + data array with built-in client-side sorting (click a sortable header to cycle asc \u2192 desc \u2192 none), optional row click / selection, and an empty state. For server data or paging, sort/page the data and pair with Pagination.",
+  summary: "A data-driven table over the Table primitives \u2014 a columns def + data array with built-in client-side sorting (click a sortable header to cycle asc \u2192 desc \u2192 none), optional row click / selection, rows grouped under collapsible header rows (groupBy), and an empty state. For server data or paging, sort/page the data and pair with Pagination.",
   keywords: [
     "data table",
     "table",
@@ -10,7 +10,14 @@ var dataTableMeta = {
     "rows",
     "empty state",
     "pagination",
-    "list"
+    "list",
+    "grouped",
+    "group by",
+    "sections",
+    "issue list",
+    "issue tracker",
+    "status groups",
+    "collapsible groups"
   ],
   usage: {
     description: "Use DataTable when a data array and column definition should render a sortable, semantic table with optional row actions and an empty state. Use the lower-level Table parts for hand-authored markup or highly custom row layouts.",
@@ -33,7 +40,11 @@ var dataTableMeta = {
       },
       {
         guidance: "do",
-        description: "Move to TanStack Table, rendered with Sable's Table parts, once the table needs server-side sorting or filtering, column visibility or resizing, grouping, or virtualised rows. DataTable stays dependency-free and does not grow into a data grid; `sable docs tables-with-tanstack` maps one onto the other."
+        description: "Group rows by status for an issue tracker (or by owner, by day) with groupBy + groups on ONE DataTable: every group shares the header and the column widths, each header row carries the group's count and an add action, and sorting applies within each group. Do not stack one DataTable per group inside Collapsibles; the header repeats and the columns stop lining up."
+      },
+      {
+        guidance: "do",
+        description: "Move to TanStack Table, rendered with Sable's Table parts, once the table needs server-side sorting or filtering, column visibility or resizing, nested or aggregated grouping, or virtualised rows. DataTable stays dependency-free and does not grow into a data grid; `sable docs tables-with-tanstack` maps one onto the other."
       },
       {
         guidance: "dont",
@@ -60,6 +71,11 @@ var dataTableMeta = {
         required: false,
         description: "Content spanning all columns when the row array is empty."
       },
+      {
+        name: "Group header row",
+        required: false,
+        description: "With groupBy: one row per group heading its own tbody (a th with scope=rowgroup across every column) holding the disclosure toggle, the group's icon, label and count, and an optional trailing action."
+      },
       {
         name: "Caption",
         required: false,
@@ -136,6 +152,32 @@ var dataTableMeta = {
       name: "caption",
       type: "ReactNode",
       description: "Bottom table caption."
+    },
+    {
+      name: "groupBy",
+      type: "(row) => string",
+      description: "Group the rows under header rows by the key this returns (a status, an owner, a day). One header serves every group, so the columns line up across them; sorting applies within each group."
+    },
+    {
+      name: "groups",
+      type: "{ key: string; label?: ReactNode; icon?: ReactNode; action?: ReactNode; defaultExpanded?: boolean }[]",
+      description: "Order and presentation of the groups, by key: the header row's label (defaults to the key), a leading icon such as a status mark, a trailing action such as an icon Button that adds a row to the group, and whether it starts open (default true). Groups groupBy returns that are not listed follow, in the order their first row appears in data. A listed group with no rows is not shown."
+    },
+    {
+      name: "collapsible",
+      type: "boolean",
+      default: "true",
+      description: "Whether each group's header row is a toggle that opens and closes the group. A closed group keeps its header row and count; its rows are hidden and select-all skips them."
+    },
+    {
+      name: "expandedGroups",
+      type: "ReadonlySet<string>",
+      description: "The open groups, by key (controlled). Without it each group starts at its defaultExpanded and the table holds the state."
+    },
+    {
+      name: "onExpandedGroupsChange",
+      type: "(keys: Set<string>) => void",
+      description: "Called with the new set of open group keys when a group header is toggled."
     }
   ],
   tokensUsed: ["muted-foreground", "foreground", "ring"],
@@ -164,6 +206,18 @@ var dataTableMeta = {
       part: "Row",
       why: "A checked row's fill eases in across its cells, so selecting by checkbox reads as the row being picked rather than a band stamped over it."
     },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Group chevron",
+      why: "A group's chevron turns from pointing along the reading direction (closed) to down (open), so the group reads as folding rather than a glyph being swapped."
+    },
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Group rows",
+      why: "Opening a group shows its rows at once: table rows cannot animate their height without leaving the table layout, and the rows are the content the reader asked for."
+    },
     {
       slot: "activity",
       recipe: "none",
@@ -174,7 +228,8 @@ var dataTableMeta = {
   a11y: [
     "Sorted columns set aria-sort=ascending/descending on the header cell.",
     "Sortable headers are real <button>s with a focus-visible ring, keyboard-operable.",
-    "Inherits the Table's scrollable frame and semantic <table>/<th>/<td> structure."
+    "Inherits the Table's scrollable frame and semantic <table>/<th>/<td> structure.",
+    'Grouped, each group is its own <tbody> (a rowgroup) headed by a <th scope="rowgroup"> spanning the columns, so group headers are never read as data rows; the toggle is a real button with aria-expanded and aria-controls naming that tbody.'
   ],
   examples: [
     {
@@ -197,6 +252,10 @@ var dataTableMeta = {
       label: "In a card, edge to edge",
       code: '<Card><CardHeader><CardTitle>Deployments</CardTitle></CardHeader><CardContent flush><DataTable data={deployments} rowKey={(row) => row.id} columns={[{ key: "project", header: "Project", sortable: true }, { key: "duration", header: "Duration", align: "end" }]} /></CardContent></Card>'
     },
+    {
+      label: "Issues grouped by status",
+      code: 'const STATUSES = [\n	{ key: "in-progress", label: "In progress", icon: <StatusDot tone="warning" /> },\n	{ key: "in-review", label: "In review", icon: <StatusDot tone="purple" /> },\n	{ key: "todo", label: "Todo", icon: <StatusDot /> },\n	{ key: "done", label: "Done", icon: <StatusDot tone="success" />, defaultExpanded: false },\n]\n\n<DataTable\n	data={issues}\n	rowKey={(t) => t.id}\n	groupBy={(t) => t.status}\n	groups={STATUSES.map((s) => ({ ...s, action: <Button variant="ghost" size="icon-xs" aria-label={`Add issue to ${s.label}`} onClick={() => create(s.key)}><Icon name="plus" /></Button> }))}\n	onRowClick={(t) => setSelectedId(t.id)}\n	isRowSelected={(t) => t.id === selectedId}\n	columns={[\n		{ key: "id", header: "ID", className: "w-20", cell: (t) => <span className="text-mono-caption text-muted-foreground">{t.id}</span> },\n		{ key: "title", header: "Issue", sortable: true },\n		{ key: "due", header: "Due", sortable: true, sortValue: (t) => t.due.getTime(), cell: (t) => formatDate(t.due) },\n	]}\n/>'
+    },
     {
       label: "Empty state",
       code: '<DataTable data={[]} columns={[{ key: "name", header: "Name" }, { key: "status", header: "Status" }]} empty={<EmptyState icon={<Icon name="search" />} title="No deployments" description="Try a different filter or create a deployment." action={<Button>Create deployment</Button>} />} />'