@sableui/react 0.8.1 → 0.8.2

package/AGENTS.md

@@ -55,7 +55,7 @@ Pick a theme as a starting point, then override tokens on top of it. Every token
 
 The machine-readable version of this section is the `consume` block in `registry.json`.
 
-1. **Install** from npm: `pnpm add @sableui/react` (or the project's package manager). No registry configuration or token is needed.
+1. **Install** from npm: `pnpm add @sableui/react` (or the project's package manager). No registry configuration or token is needed. Sable depends on no router, data or form library, and keeps whatever the project already uses: links, menus and nav items take any router's link through `render` (`render={<Link to="/inbox" />}` is TanStack Router's or React Router's `Link` alike). For a blank-slate app, the suggested stack is Vite + TypeScript with TanStack Router, TanStack Query, TanStack Form for forms with validation logic, and TanStack Table once a table outgrows `DataTable` (`sable docs tables-with-tanstack`).
 2. **Dedupe React** in the bundler (`resolve.dedupe: ["react","react-dom"]`) — Base UI must not resolve a second React, or you get an "invalid hook call" blank page.
 3. **CSS, in order:** `@import "tailwindcss";` → `@import "@sableui/react/styles.css";` → `@source "<node_modules>/@sableui/react/dist/**/*.{js,mjs}";` so Tailwind scans the package's classes. That ships every component's classes (about 32 KB gzipped); before shipping, `sable sources --write src/sable-sources.css` lists just the modules the app imports, imported in place of that `@source`, and `sable check` fails when it goes stale.
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # What's new
 
+## 0.8.2
+
+- **A suggested stack for blank-slate apps.** Sable still depends on no router,
+  data or form library, and an app keeps the ones it has. Starting from
+  nothing, the skill, `AGENTS.md`, `sable docs getting-started` and the install
+  recipe (`registry.json` → `consume.stack`) now suggest Vite + TypeScript with
+  TanStack Router, TanStack Query, TanStack Form for forms with validation
+  logic, and TanStack Table once a table outgrows `DataTable`.
+- **`sable docs tables-with-tanstack`:** when to move from `DataTable` to
+  TanStack Table (server-side data, column visibility or resizing, grouping,
+  virtualised rows), and how to render it with Sable's `Table` parts,
+  `Checkbox`, `Button` and `Pagination`, with server data through TanStack
+  Query and bulk-action selection. `DataTable` stays dependency-free.
+
 ## 0.8.1
 
 - **`sable check` shows doctor's notes.** Warnings and notes from `sable doctor`

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

@@ -31,6 +31,10 @@ var dataTableMeta = {
         guidance: "do",
         description: "Pair server-side datasets with Pagination and pass already-sorted/paged rows."
       },
+      {
+        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."
+      },
       {
         guidance: "dont",
         description: "Make every row clickable and also fill it with competing buttons. Choose a clear row interaction model."

package/dist/file-hashes.json

@@ -179,7 +179,7 @@
 	"dist/components/context-menu/context-menu.meta.js": "6915409a31be6ef0",
 	"dist/components/context-menu/index.js": "b4a609ee13e4bdd5",
 	"dist/components/data-table/data-table.js": "3d7492b8ac0447b4",
-	"dist/components/data-table/data-table.meta.js": "fa409c60c480aabc",
+	"dist/components/data-table/data-table.meta.js": "0aa598b375e5bfeb",
 	"dist/components/data-table/index.js": "181835d5e3b6c366",
 	"dist/components/date-picker/date-picker.js": "7dd1d41202bede97",
 	"dist/components/date-picker/date-picker.meta.js": "a56f356cf633d7e8",
@@ -470,8 +470,8 @@
 	"dist/icon-sets/brands.js": "9a37d8739f14f2a9",
 	"dist/icon-sets/reicon.d.ts": "52f6e41dc8137b4e",
 	"dist/icon-sets/reicon.js": "89a930f17cc90cde",
-	"dist/index.d.ts": "50432e5848c126c0",
-	"dist/index.js": "e23dc24b22fa7d6f",
+	"dist/index.d.ts": "5412b556b1d05aa9",
+	"dist/index.js": "3f9d4da26572073f",
 	"dist/ios/chrome.css": "a7ca9e3735d8658e",
 	"dist/ios/chrome.js": "37091fef7b68bd28",
 	"dist/ios/frame.css": "dd2703c944ce575a",

package/dist/index.d.ts

@@ -8291,6 +8291,6 @@ interface UseCopyResult {
  */
 declare function useCopy(text: string, { timeout }?: UseCopyOptions): UseCopyResult;
 
-declare const SABLE_UI_VERSION: "0.8.1";
+declare const SABLE_UI_VERSION: "0.8.2";
 
 export { Accordion, AccordionItem, AccordionPanel, AccordionTrigger, AlertDialog, AlertDialogClose, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogTitle, AlertDialogTrigger, AppHeader, type AppHeaderProps, AppShell, type AppShellProps, AreaChart, type AreaChartProps, type ArtTone, Attachment, type AttachmentProps, Avatar, AvatarFallback, AvatarGroup, AvatarGroupCount, type AvatarGroupCountProps, type AvatarGroupProps, AvatarImage, type AvatarProps, AvatarRoot, BADGE_APPEARANCES, BADGE_TONES, Badge, type BadgeAppearance, type BadgeProps, type BadgeTone, Banner, type BannerProps, BarChart, type BarChartProps, BottomNav, BottomNavItem, type BottomNavItemProps, BreadcrumbItem, type BreadcrumbItemProps, BreadcrumbLink, type BreadcrumbLinkProps, BreadcrumbPage, type BreadcrumbPageProps, BreadcrumbSeparator, type BreadcrumbSeparatorProps, Breadcrumbs, type BreadcrumbsProps, Browser, type BrowserProps, Bubble, type BubbleProps, BubbleReaction, type BubbleReactionProps, BubbleReactions, type BubbleReactionsProps, Button, type ButtonBleed, type ButtonProps, CHART_SERIES_COUNT, COMPONENT_GROUPS, COMPONENT_TAXONOMY, Calendar, type CalendarProps, Card, CardAction, CardContent, type CardContentProps, CardDescription, CardFooter, type CardFooterProps, CardHeader, CardList, type CardProps, CardTitle, type CardTitleProps, Carousel, type CarouselProps, type CarouselSlidesToShow, type ChartCategories, type ChartCenterLabel, type ChartCurve, type ChartDatum, type ChartSeries, type ChartTone, type ChartTooltipIndicator, type ChartTooltipOptions, type ChartValueFormatter, ChatComposer, type ChatComposerProps, Checkbox, CheckboxCard, type CheckboxCardProps, type CheckboxCardTone, CheckboxGroup, type CheckboxGroupProps, Code, CodeBlock, type CodeBlockProps, CodeHighlightProvider, type CodeHighlighter, type CodeProps, Collapsible, CollapsibleIndicator, CollapsiblePanel, CollapsibleTrigger, ColorField, type ColorFieldProps, Combobox, ComboboxChips, ComboboxClear, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, ComboboxItem, type ComboboxItemGroup, ComboboxItemIndicator, ComboboxList, ComboboxPortal, type ComboboxProps, ComboboxValue, ComboboxVirtualList, type ComboboxVirtualListProps, type CommandFilter, type CommandItem, CommandMenu, CommandMenuGroup, type CommandMenuGroupProps, CommandMenuItem, type CommandMenuItemProps, CommandMenuPanel, type CommandMenuPanelProps, type CommandMenuProps, CommandMenuTrigger, type CommandMenuTriggerProps, type ComponentGroup, type ComponentGuidance, ComponentMeta, type ComponentRegister, type ConstraintFlag, ContextCard, ContextCardArrow, ContextCardContent, ContextCardPortal, ContextCardTrigger, ContextMenu, ContextMenuContent, ContextMenuGroup, ContextMenuGroupLabel, ContextMenuItem, ContextMenuPortal, ContextMenuSeparator, ContextMenuTrigger, DataTable, type DataTableColumn, type DataTableProps, type DataTableRowKey, DatePicker, type DatePickerProps, DateTile, type DateTileProps, Density, DensityProvider, Density as DensityValue, DestructiveActionModal, type DestructiveActionModalProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, type DialogSize, DialogTitle, DialogTrigger, DisclosurePicker, DisclosurePickerEmpty, DisclosurePickerList, type DisclosurePickerListProps, DisclosurePickerOption, type DisclosurePickerOptionProps, DisclosurePickerPanel, type DisclosurePickerPanelProps, type DisclosurePickerProps, type DisclosurePickerSearch, DisclosurePickerTrigger, type DisclosurePickerTriggerProps, EmptyState, type EmptyStateProps, Entity, type EntityProps, Feedback, type FeedbackData, type FeedbackProps, type FeedbackRating, Field, type FieldProps, Fieldset, FieldsetContent, FieldsetDescription, FieldsetFooter, FieldsetLegend, FileDropzone, type FileDropzoneProps, type FileRejection, type FileRejectionCode, FontPicker, type FontPickerFont, type FontPickerOption, type FontPickerProps, Form, type FormProps, GlidingHighlight, type GlidingHighlightProps, GradientArt, type GradientArtProps, type Hsv, InlineStatus, type InlineStatusProps, type StatusTone as InlineTone, Input, type InputProps$1 as InputProps, Kbd, KbdGroup, type KbdGroupProps, type KbdProps, Label, type LabelProps$2 as LabelProps, LineChart, type LineChartProps, Marker, type MarkerProps, Marquee, type MarqueeProps, MediaImage, type MediaImageProps, MediaTile, type MediaTileProps, Menu, MenuCheckboxItem, MenuContent, MenuGroup, MenuGroupLabel, MenuItem, MenuPortal, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuSubmenu, MenuSubmenuTrigger, MenuTrigger, Message, type MessageProps, MessageScroller, type MessageScrollerHandle, type MessageScrollerProps, Meter, MeterIndicator, MeterLabel, type MeterSize, type MeterTone, MeterTrack, MeterValue, MiddleTruncate, type MiddleTruncateProps, type MotionPolicy, MotionProvider, type MotionProviderProps, Note, type NoteAction, type NoteProps, NotificationBadge, type NotificationBadgeProps, NumberField, type NumberFieldProps, type OrbMode, type OrbSize, OtpField, type OtpFieldProps, OverflowMenu, type OverflowMenuProps, PageHeader, type PageHeaderProps, PageLoader, type PageLoaderProps, Pagination, type PaginationProps, Panel, PanelGroup, PanelResizer, type PanelResizerProps, PanelSection, type PanelWidthBounds, Phone, type PhoneProps, PieChart, type PieChartProps, Pill, type PillProps, Popover, PopoverArrow, PopoverClose, PopoverContent, PopoverDescription, PopoverPortal, PopoverTitle, PopoverTrigger, Presence, type PresenceProps, type Presentation, PresentationProvider, Progress, ProgressIndicator, ProgressLabel, type ProgressSize, ProgressTrack, ProgressValue, PropertyPair, PropertyRow, RadarChart, type RadarChartProps, RadialChart, type RadialChartProps, Radio, RadioCard, type RadioCardProps, type RadioCardTone, RadioGroup, RelativeTime, type RelativeTimeProps, Reveal, type RevealProps, type Rgb, SABLE_UI_VERSION, SEGMENTED_BAR_TONES, STATUS_TONES, STATUS_TONE_ICON, type ScrollCommandOptions, Scroller, type ScrollerProps, ScrubField, type ScrubFieldProps, SearchInput, type SearchInputProps, SectionHeader, type SectionHeaderProps, SegmentedBar, type SegmentedBarProps, type SegmentedBarSegment, type SegmentedBarTone, Select, SelectContent, SelectGroup, SelectGroupLabel, SelectItem, SelectPortal, SelectSeparator, SelectTrigger, SelectValue, Separator, type SeparatorProps$3 as SeparatorProps, SettingsMenu, type SettingsMenuProps, SettingsRow, type SettingsRowProps, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetList, SheetPortal, SheetTitle, SheetTrigger, ShowMore, type ShowMoreProps, SideNav, type SideNavActiveVariant, SideNavGroup, type SideNavGroupProps, SideNavItem, type SideNavItemProps, type SideNavProps, type SideNavSize, Sidebar, SidebarBrand, type SidebarBrandProps, SidebarFooter, SidebarHeader, SidebarItem, type SidebarItemProps, SidebarNav, type SidebarProps, SimpleTooltip, Skeleton, Slider, SliderControl, SliderIndicator, SliderRoot, SliderThumb, SliderTrack, SliderValue, Sparkline, type SparklineProps, Spinner, type SpinnerProps, StatusBar, StatusBarGroup, StatusBarSeparator, StatusDot, type StatusDotProps, type StatusTone, type StepStatus, Stepper, StepperItem, type StepperItemProps, type StepperOrientation, type StepperProps, StreamingText, type StreamingTextProps, Switch, TRANSPARENT, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsPanel as TabsContent, TabsList, TabsPanel, TabsTrigger, TextReveal, type TextRevealProps, Textarea, type TextareaProps, ThemeId, ThemeManifest, ThemeMode$1 as ThemeManifestMode, type ThemeMode, ThemePreview, type ThemePreviewProps, ThemeSelector, type ThemeSelectorProps, ThemeSwitcher, type ThemeSwitcherProps, ThinkingOrb, type ThinkingOrbProps, ToastAction, type ToastApi, ToastClose, ToastContent, ToastDescription, type ToastManagerApi, type ToastOptions, type ToastPosition, ToastProvider, type ToastProviderProps, ToastRoot, ToastTitle, type ToastType, ToastViewport, Toggle, ToggleGroup, type ToggleGroupAppearance, Toggle as ToggleGroupItem, Toolbar, ToolbarButton, type ToolbarButtonProps, ToolbarGroup, type ToolbarGroupProps, ToolbarInput, type ToolbarInputProps, ToolbarLink, type ToolbarLinkProps, type ToolbarProps, ToolbarSeparator, type ToolbarSeparatorProps, Tooltip, TooltipArrow, TooltipContent, TooltipPortal, TooltipProvider, TooltipTrigger, Tree, TreeAddRow, TreeEmpty, TreeRow, TreeSection, type UseCopyOptions, type UseCopyResult, type UseInViewOptions, type UsePanelWidthOptions, Video, type VideoProps, ViewTransitionName, type ViewTransitionNameProps, Workspace, WorkspaceBar, WorkspaceCanvas, accordionMeta, appHeaderMeta, appShellMeta, areaChartMeta, attachmentMeta, avatarGroupVariants, avatarMeta, avatarVariants, badgeMeta, badgeVariants, bannerMeta, bannerVariants, barChartMeta, bottomNavMeta, breadcrumbsMeta, browserMeta, bubbleMeta, buttonMeta, buttonVariants, calendarMeta, cardMeta, carouselMeta, chartColor, toneColor as chartToneColor, chatComposerMeta, checkboxCardMeta, checkboxMeta, cn, codeBlockMeta, codeMeta, collapsibleMeta, colorFieldMeta, comboboxMeta, commandMenuMeta, componentGuidance, componentLabel, componentSlug, componentsInGroup, contextCardMeta, contextMenuMeta, dataTableMeta, datePickerMeta, dateTileMeta, destructiveActionModalMeta, dialogMeta, disclosurePickerMeta, emptyStateMeta, entityMeta, feedbackMeta, fieldsetMeta, fileDropzoneMeta, fileDropzoneVariants, fontPickerMeta, formMeta, formatFileSize, formatHex, glidingHighlightMeta, gradientArtMeta, hsvToRgb, hueColor, inlineStatusMeta, inputMeta, isTransparent, kbdMeta, labelMeta, lineChartMeta, markerMeta, marqueeMeta, mediaImageMeta, mediaTileMeta, menuMeta, messageMeta, messageScrollerMeta, meterIndicatorVariants, meterMeta, meterTrackVariants, middleTruncateMeta, noteMeta, noteVariants, notificationBadgeMeta, notificationCountVariants, notificationDotVariants, numberFieldMeta, otpFieldMeta, overflowMenuMeta, pageHeaderMeta, pageLoaderMeta, paginationMeta, panelGroupMeta, panelSectionMeta, parseHex, phoneMeta, pieChartMeta, pillMeta, pillVariants, popoverMeta, progressMeta, progressTrackVariants, radarChartMeta, radialChartMeta, radioCardMeta, radioMeta, relativeTimeMeta, rgbToHsv, scrollerMeta, scrubFieldMeta, searchInputMeta, sectionHeaderMeta, segmentedBarMeta, segmentedBarSegmentVariants, segmentedBarVariants, selectMeta, separatorMeta, settingsMenuMeta, sheetMeta, sheetVariants, showMoreMeta, sideNavMeta, sidebarMeta, skeletonMeta, sliderMeta, sparklineMeta, spinnerMeta, startViewTransition, statusBarMeta, statusDotMeta, statusDotVariants, stepperConnectorVariants, stepperIndicatorVariants, stepperMeta, streamingTextMeta, supportsViewTransitions, switchMeta, tableMeta, tabsMeta, textareaMeta, themeSelectorMeta, themeSwitcherMeta, thinkingOrbMeta, toast, toastMeta, toggleMeta, toolbarGroupVariants, toolbarMeta, toolbarSeparatorVariants, toolbarVariants, tooltipMeta, treeIndent, treeMeta, useAnchoredDensity, useComboboxFilteredItems, useCommandMenuShortcut, useCopy, useDensity, useDisclosurePicker, useInView, useMotion, usePanelWidth, usePresentation, useReducedMotion, useScrollActivity, useSidebar, useToast, useToastManager, useTypeTier, videoMeta, workspaceMeta };

package/dist/index.js

@@ -160,7 +160,7 @@ import { PresentationProvider, usePresentation } from "./lib/presentation.js";
 import { useScrollActivity } from "./lib/use-scroll-activity.js";
 import { useCopy } from "./lib/use-copy.js";
 import { STATUS_TONES, STATUS_TONE_ICON } from "./lib/status-tone.js";
-var SABLE_UI_VERSION = "0.8.1";
+var SABLE_UI_VERSION = "0.8.2";
 export {
   ART_TOKENS,
   CHART_SERIES_COUNT,

package/llms/components/data-table.md

@@ -16,6 +16,7 @@ Use DataTable when a data array and column definition should render a sortable,
 - Do: Provide stable rowKey values for dynamic data so selection and sorting do not jump.
 - Do: Use sortable only on columns where ordering is obvious and useful.
 - Do: Pair server-side datasets with Pagination and pass already-sorted/paged rows.
+- Do: 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.
 - Don't: Make every row clickable and also fill it with competing buttons. Choose a clear row interaction model.
 - Don't: Use DataTable for heterogeneous cards or timeline content. A list or card layout will scan better.
 

package/llms/tasks/getting-started.md

@@ -4,6 +4,12 @@ Sable is on npm as `@sableui/react`. The installed version's `registry.json`
 consume block has the exact recipe. Requirements: React 19, React DOM 19, and
 Tailwind CSS 4 integrated into your build.
 
+Sable works in any React 19 app and depends on no router, data or form
+library. Starting from a blank slate, its suggested stack is React with
+TypeScript on Vite, TanStack Router, TanStack Query, TanStack Form for forms with
+validation logic, and TanStack Table once a table outgrows `DataTable`
+(`sable docs tables-with-tanstack`). An existing app keeps its own.
+
 ## Install
 
 ```bash

package/llms/tasks/tables-with-tanstack.md

@@ -0,0 +1,157 @@
+# Task: tables with TanStack Table
+
+`DataTable` is Sable's own table: a column list and a data array, with
+client-side sorting, row click, checkbox selection and an empty state, and no
+dependency. Use it until the table needs what it doesn't do:
+
+- server-side sorting, filtering or paging over a large data set;
+- column visibility, ordering, resizing or pinning;
+- grouping, expanding rows, faceted filters;
+- thousands of rows that need virtualising.
+
+Then use **TanStack Table** (`@tanstack/react-table`) for the table's logic and
+render it with Sable's `Table` parts, so it still looks and behaves like every
+other Sable table: the same row hover, selected fill, edge insets in a flush
+`Card`, and numeric columns. Sable doesn't depend on TanStack; this is the
+pairing it suggests, and any headless table library renders the same way.
+
+## The pairing
+
+TanStack owns state (sorting, selection, pagination); Sable owns markup. Map them
+one to one:
+
+| TanStack | Sable |
+|---|---|
+| `getHeaderGroups()` → header row | `TableHeader` › `TableRow` › `TableHead` |
+| `getRowModel().rows` | `TableBody` › `TableRow` › `TableCell` |
+| `row.getIsSelected()` | `data-selected` on the `TableRow` (the selected fill) |
+| `column.getToggleSortingHandler()` | a ghost `Button size="xs"` in the head, `aria-sort` on the `TableHead` |
+| selection column | `Checkbox` per row (named after the row) and in the head (`indeterminate` when some are checked) |
+| `getPageCount()`, `setPageIndex()` | `Pagination` (1-based) |
+
+```tsx
+import {
+	type ColumnDef,
+	type RowSelectionState,
+	type SortingState,
+	flexRender,
+	getCoreRowModel,
+	getPaginationRowModel,
+	getSortedRowModel,
+	useReactTable,
+} from "@tanstack/react-table"
+import { Button, Checkbox, Icon, Pagination, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@sableui/react"
+import { useState } from "react"
+
+type Ticket = { id: string; subject: string; customer: string; updated: Date }
+
+const columns: ColumnDef<Ticket>[] = [
+	{
+		id: "select",
+		enableSorting: false,
+		header: ({ table }) => (
+			<Checkbox
+				aria-label={`Select all ${table.getRowModel().rows.length} tickets shown`}
+				checked={table.getIsAllPageRowsSelected()}
+				indeterminate={table.getIsSomePageRowsSelected()}
+				onCheckedChange={(checked) => table.toggleAllPageRowsSelected(checked)}
+			/>
+		),
+		cell: ({ row }) => (
+			<Checkbox
+				aria-label={`Select ${row.original.subject}`}
+				checked={row.getIsSelected()}
+				onCheckedChange={(checked) => row.toggleSelected(checked)}
+			/>
+		),
+	},
+	{ accessorKey: "subject", header: "Subject" },
+	{ accessorKey: "customer", header: "Customer" },
+	{ accessorKey: "updated", header: "Updated", cell: ({ getValue }) => getValue<Date>().toLocaleDateString() },
+]
+
+export function TicketTable({ data }: { data: Ticket[] }) {
+	const [sorting, setSorting] = useState<SortingState>([])
+	const [rowSelection, setRowSelection] = useState<RowSelectionState>({})
+	const table = useReactTable({
+		data,
+		columns,
+		getRowId: (ticket) => ticket.id,
+		state: { sorting, rowSelection },
+		onSortingChange: setSorting,
+		onRowSelectionChange: setRowSelection,
+		getCoreRowModel: getCoreRowModel(),
+		getSortedRowModel: getSortedRowModel(),
+		getPaginationRowModel: getPaginationRowModel(),
+	})
+
+	return (
+		<>
+			<Table>
+				<TableHeader>
+					{table.getHeaderGroups().map((group) => (
+						<TableRow key={group.id}>
+							{group.headers.map((header) => {
+								const sorted = header.column.getIsSorted()
+								const label = flexRender(header.column.columnDef.header, header.getContext())
+								return (
+									<TableHead
+										key={header.id}
+										className={header.column.id === "select" ? "w-0" : undefined}
+										aria-sort={sorted === "asc" ? "ascending" : sorted === "desc" ? "descending" : undefined}
+									>
+										{header.column.getCanSort() ? (
+											<Button variant="ghost" size="xs" bleed="start" onClick={header.column.getToggleSortingHandler()}>
+												{label}
+												<Icon name={sorted === "desc" ? "chevron-down" : "chevron-up"} className={sorted ? undefined : "opacity-60"} />
+											</Button>
+										) : (
+											label
+										)}
+									</TableHead>
+								)
+							})}
+						</TableRow>
+					))}
+				</TableHeader>
+				<TableBody>
+					{table.getRowModel().rows.map((row) => (
+						<TableRow key={row.id} data-selected={row.getIsSelected() ? "" : undefined}>
+							{row.getVisibleCells().map((cell) => (
+								<TableCell key={cell.id} className={cell.column.id === "select" ? "w-0" : undefined}>
+									{flexRender(cell.column.columnDef.cell, cell.getContext())}
+								</TableCell>
+							))}
+						</TableRow>
+					))}
+				</TableBody>
+			</Table>
+			<Pagination
+				page={table.getState().pagination.pageIndex + 1}
+				total={table.getPageCount()}
+				onPageChange={(page) => table.setPageIndex(page - 1)}
+			/>
+		</>
+	)
+}
+```
+
+Inside a card, put the `Table` in `<CardContent flush>`, as with `DataTable`.
+Mark a numeric column with `numeric` on its `TableHead` and `TableCell`s.
+
+## Server-side data
+
+Set `manualSorting`, `manualPagination` (and `manualFiltering`) with
+`pageCount` or `rowCount`, and fetch with the table's state as the query key.
+In a blank-slate app that is TanStack Query:
+`useQuery({ queryKey: ["tickets", sorting, pagination], queryFn })`, passing
+`data ?? []` to the table. Show `Skeleton` rows while the first page loads and
+keep the previous page on screen while the next one does.
+
+## Selection and bulk actions
+
+Selection belongs to the rows shown: clear `rowSelection` when the filter or
+view changes the data set. Above the table, render the bulk actions only while
+something is selected, and keep a `role="status"` element mounted from the start
+that says "3 of 25 selected", so a screen reader hears each change. The
+`DataTable` docs show the same bar (`sable component DataTable --examples`).

package/llms-full.txt

@@ -1791,6 +1791,12 @@ Sable is on npm as `@sableui/react`. The installed version's `registry.json`
 consume block has the exact recipe. Requirements: React 19, React DOM 19, and
 Tailwind CSS 4 integrated into your build.
 
+Sable works in any React 19 app and depends on no router, data or form
+library. Starting from a blank slate, its suggested stack is React with
+TypeScript on Vite, TanStack Router, TanStack Query, TanStack Form for forms with
+validation logic, and TanStack Table once a table outgrows `DataTable`
+(`sable docs tables-with-tanstack`). An existing app keeps its own.
+
 ## Install
 
 ```bash
@@ -2318,6 +2324,166 @@ lesson only within the contexts the observation supports.
 
 ---
 
+# Task: tables with TanStack Table
+
+`DataTable` is Sable's own table: a column list and a data array, with
+client-side sorting, row click, checkbox selection and an empty state, and no
+dependency. Use it until the table needs what it doesn't do:
+
+- server-side sorting, filtering or paging over a large data set;
+- column visibility, ordering, resizing or pinning;
+- grouping, expanding rows, faceted filters;
+- thousands of rows that need virtualising.
+
+Then use **TanStack Table** (`@tanstack/react-table`) for the table's logic and
+render it with Sable's `Table` parts, so it still looks and behaves like every
+other Sable table: the same row hover, selected fill, edge insets in a flush
+`Card`, and numeric columns. Sable doesn't depend on TanStack; this is the
+pairing it suggests, and any headless table library renders the same way.
+
+## The pairing
+
+TanStack owns state (sorting, selection, pagination); Sable owns markup. Map them
+one to one:
+
+| TanStack | Sable |
+|---|---|
+| `getHeaderGroups()` → header row | `TableHeader` › `TableRow` › `TableHead` |
+| `getRowModel().rows` | `TableBody` › `TableRow` › `TableCell` |
+| `row.getIsSelected()` | `data-selected` on the `TableRow` (the selected fill) |
+| `column.getToggleSortingHandler()` | a ghost `Button size="xs"` in the head, `aria-sort` on the `TableHead` |
+| selection column | `Checkbox` per row (named after the row) and in the head (`indeterminate` when some are checked) |
+| `getPageCount()`, `setPageIndex()` | `Pagination` (1-based) |
+
+```tsx
+import {
+	type ColumnDef,
+	type RowSelectionState,
+	type SortingState,
+	flexRender,
+	getCoreRowModel,
+	getPaginationRowModel,
+	getSortedRowModel,
+	useReactTable,
+} from "@tanstack/react-table"
+import { Button, Checkbox, Icon, Pagination, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@sableui/react"
+import { useState } from "react"
+
+type Ticket = { id: string; subject: string; customer: string; updated: Date }
+
+const columns: ColumnDef<Ticket>[] = [
+	{
+		id: "select",
+		enableSorting: false,
+		header: ({ table }) => (
+			<Checkbox
+				aria-label={`Select all ${table.getRowModel().rows.length} tickets shown`}
+				checked={table.getIsAllPageRowsSelected()}
+				indeterminate={table.getIsSomePageRowsSelected()}
+				onCheckedChange={(checked) => table.toggleAllPageRowsSelected(checked)}
+			/>
+		),
+		cell: ({ row }) => (
+			<Checkbox
+				aria-label={`Select ${row.original.subject}`}
+				checked={row.getIsSelected()}
+				onCheckedChange={(checked) => row.toggleSelected(checked)}
+			/>
+		),
+	},
+	{ accessorKey: "subject", header: "Subject" },
+	{ accessorKey: "customer", header: "Customer" },
+	{ accessorKey: "updated", header: "Updated", cell: ({ getValue }) => getValue<Date>().toLocaleDateString() },
+]
+
+export function TicketTable({ data }: { data: Ticket[] }) {
+	const [sorting, setSorting] = useState<SortingState>([])
+	const [rowSelection, setRowSelection] = useState<RowSelectionState>({})
+	const table = useReactTable({
+		data,
+		columns,
+		getRowId: (ticket) => ticket.id,
+		state: { sorting, rowSelection },
+		onSortingChange: setSorting,
+		onRowSelectionChange: setRowSelection,
+		getCoreRowModel: getCoreRowModel(),
+		getSortedRowModel: getSortedRowModel(),
+		getPaginationRowModel: getPaginationRowModel(),
+	})
+
+	return (
+		<>
+			<Table>
+				<TableHeader>
+					{table.getHeaderGroups().map((group) => (
+						<TableRow key={group.id}>
+							{group.headers.map((header) => {
+								const sorted = header.column.getIsSorted()
+								const label = flexRender(header.column.columnDef.header, header.getContext())
+								return (
+									<TableHead
+										key={header.id}
+										className={header.column.id === "select" ? "w-0" : undefined}
+										aria-sort={sorted === "asc" ? "ascending" : sorted === "desc" ? "descending" : undefined}
+									>
+										{header.column.getCanSort() ? (
+											<Button variant="ghost" size="xs" bleed="start" onClick={header.column.getToggleSortingHandler()}>
+												{label}
+												<Icon name={sorted === "desc" ? "chevron-down" : "chevron-up"} className={sorted ? undefined : "opacity-60"} />
+											</Button>
+										) : (
+											label
+										)}
+									</TableHead>
+								)
+							})}
+						</TableRow>
+					))}
+				</TableHeader>
+				<TableBody>
+					{table.getRowModel().rows.map((row) => (
+						<TableRow key={row.id} data-selected={row.getIsSelected() ? "" : undefined}>
+							{row.getVisibleCells().map((cell) => (
+								<TableCell key={cell.id} className={cell.column.id === "select" ? "w-0" : undefined}>
+									{flexRender(cell.column.columnDef.cell, cell.getContext())}
+								</TableCell>
+							))}
+						</TableRow>
+					))}
+				</TableBody>
+			</Table>
+			<Pagination
+				page={table.getState().pagination.pageIndex + 1}
+				total={table.getPageCount()}
+				onPageChange={(page) => table.setPageIndex(page - 1)}
+			/>
+		</>
+	)
+}
+```
+
+Inside a card, put the `Table` in `<CardContent flush>`, as with `DataTable`.
+Mark a numeric column with `numeric` on its `TableHead` and `TableCell`s.
+
+## Server-side data
+
+Set `manualSorting`, `manualPagination` (and `manualFiltering`) with
+`pageCount` or `rowCount`, and fetch with the table's state as the query key.
+In a blank-slate app that is TanStack Query:
+`useQuery({ queryKey: ["tickets", sorting, pagination], queryFn })`, passing
+`data ?? []` to the table. Show `Skeleton` rows while the first page loads and
+keep the previous page on screen while the next one does.
+
+## Selection and bulk actions
+
+Selection belongs to the rows shown: clear `rowSelection` when the filter or
+view changes the data set. Above the table, render the bulk actions only while
+something is selected, and keep a `role="status"` element mounted from the start
+that says "3 of 25 selected", so a screen reader hears each change. The
+`DataTable` docs show the same bar (`sable component DataTable --examples`).
+
+---
+
 # Task: use a portable preset
 
 Bundled presets are maintained with Sable. Personal presets are app-owned JSON
@@ -12731,6 +12897,7 @@ Use DataTable when a data array and column definition should render a sortable,
 - Do: Provide stable rowKey values for dynamic data so selection and sorting do not jump.
 - Do: Use sortable only on columns where ordering is obvious and useful.
 - Do: Pair server-side datasets with Pagination and pass already-sorted/paged rows.
+- Do: 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.
 - Don't: Make every row clickable and also fill it with competing buttons. Choose a clear row interaction model.
 - Don't: Use DataTable for heterogeneous cards or timeline content. A list or card layout will scan better.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sableui/react",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Sable: themeable React components, layout patterns, and tools for coding agents.",
   "type": "module",
   "sideEffects": [

package/registry.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://sable.design/registry.schema.json",
   "name": "@sableui/react",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Themeable React components, semantic tokens, layout patterns, presets, and package-owned agent skills. Default theme: Sable.",
   "engine": {
     "behavior": "@base-ui/react",
@@ -28,6 +28,7 @@
       "@import \"@sableui/react/styles.css\";",
       "@source \"<node_modules>/@sableui/react/dist/**/*.{js,mjs}\";"
     ],
+    "stack": "Sable depends on no router, data or form library; an existing app keeps its own, and links take any router's Link through render. For a blank-slate app the suggested stack is Vite + TypeScript, TanStack Router, TanStack Query, TanStack Form for forms with validation logic, and TanStack Table once a table outgrows DataTable (sable docs tables-with-tanstack).",
     "cssSources": "That @source ships every component's classes (about 32 KB gzipped). Once the app is built, `sable sources --write src/sable-sources.css` lists just the modules it imports; @import that file in place of the @source. sable check fails while it is stale.",
     "fonts": {
       "sans": "Figtree",
@@ -7471,6 +7472,10 @@
             "guidance": "do",
             "description": "Pair server-side datasets with Pagination and pass already-sorted/paged rows."
           },
+          {
+            "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."
+          },
           {
             "guidance": "dont",
             "description": "Make every row clickable and also fill it with competing buttons. Choose a clear row interaction model."

package/skills/sable/SKILL.md

@@ -93,6 +93,15 @@ and registry `consume` block. Install from npm with the project's package
 manager, for example `pnpm add @sableui/react`; no registry setup or token is
 needed. Do not substitute an unrelated package with a similar name.
 
+A project that already has a router, data layer or form library keeps it: Sable
+depends on none, and its links, menus and nav take any router's link through
+`render`. For a blank-slate app, start from Sable's suggested stack: React with
+TypeScript on Vite, **TanStack Router** for routes and links, **TanStack Query**
+for server data, **TanStack Form** when a form needs validation logic, and
+**TanStack Table** once a table outgrows `DataTable` (`sable docs
+tables-with-tanstack`). Say so in the brief, and use something else only when the
+user or the product asks for it.
+
 Complete setup before implementing UI:
 
 - Match the installed package's React, React DOM, Tailwind, and Node requirements.