@sableui/react 0.8.0 → 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,29 @@
 # 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`
+  don't fail the check, so a passing check printed none of them. They now list
+  under the doctor line, and when the app still scans all of Sable, the finish
+  steps add one: trim the CSS with `sable sources` to the components the app
+  imports. The skill says to act on check's notes, and the install recipe
+  (`registry.json` → `consume.cssSources`) and `sable docs getting-started`
+  mention `sable sources` beside the whole-package `@source`.
+
 ## 0.8.0
 
 The same support-workspace app was built twice, on Sable and on shadcn, and this

package/bin/sable.mjs

@@ -1472,6 +1472,9 @@ function cmdCheck() {
 		status: doctorFailures.length ? "fail" : "pass",
 		summary: doctorFailures.length ? `${doctorFailures.length} wiring failure(s): ${doctorFailures.map((c) => c.name).join(", ")}` : "wiring holds",
 		details: doctorFailures.map((c) => `${c.name}: ${c.detail}${c.fix ? ` → ${c.fix}` : ""}`),
+		// Warnings and notes don't fail the check, but they are things to act on,
+		// and a passing check that printed nothing else hid them from the agent.
+		notes: doctor.checks.filter((c) => c.status === "warn" || c.status === "info").map((c) => `${c.name}: ${c.detail}${c.fix ? ` → ${c.fix}` : ""}`),
 		data: doctor,
 	})
 
@@ -1529,7 +1532,12 @@ function cmdCheck() {
 	const inventory = grade && grade.type !== "error" ? (grade.inventory ?? null) : null
 
 	const failed = checks.filter((c) => c.status !== "pass").map((c) => c.name)
-	const data = { paths, passed: !failed.length, failed, checks, inventory, manualReview: MANUAL_REVIEW }
+	// A build that still scans all of Sable ships every component's classes;
+	// trimming it is a finish step, because sources are only final once the app is.
+	const manual = doctor.checks.some((c) => c.name === "css:size")
+		? [...MANUAL_REVIEW, { step: "Ship only the CSS you use", how: "sable sources --write src/sable-sources.css, then @import it in place of the whole-package @source (about 32 KB of CSS gzipped down to what the app imports). Re-run it whenever you import something new from Sable; sable check fails while it is stale." }]
+		: MANUAL_REVIEW
+	const data = { paths, passed: !failed.length, failed, checks, inventory, manualReview: manual }
 	const MARK = { pass: "✓", fail: "✗", error: "✗" }
 	const MAX_DETAILS = 12
 	const summaryText = () =>
@@ -1539,6 +1547,7 @@ function cmdCheck() {
 				`  ${MARK[c.status]} ${c.name.padEnd(7)}${c.summary}`,
 				...c.details.slice(0, MAX_DETAILS).map((d) => `      ${d}`),
 				...(c.details.length > MAX_DETAILS ? [`      … ${c.details.length - MAX_DETAILS} more: sable ${c.name}${c.name === "doctor" ? "" : ` ${paths.join(" ")}`}`] : []),
+				...(c.notes ?? []).map((n) => `      note — ${n}`),
 			]),
 			"",
 			failed.length ? `[sable check] ✗ ${failed.join(", ")} failed. Fix these and run sable check again.` : "[sable check] ✓ doctor, lint and grade pass.",
@@ -1558,7 +1567,7 @@ function cmdCheck() {
 		[
 			"",
 			"Automated checks cannot judge the design. Before calling it done:",
-			...MANUAL_REVIEW.map((m, i) => `  ${i + 1}. ${m.step}: ${m.how}`),
+			...manual.map((m, i) => `  ${i + 1}. ${m.step}: ${m.how}`),
 		].join("\n")
 
 	/* Stop-hook mode (Claude Code): exit 2 blocks the agent from ending its turn

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": "34d4245102900a9d",
-	"dist/index.js": "e085b07d561eb6cd",
+	"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.0";
+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.0";
+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
@@ -20,8 +26,11 @@ For `src/styles.css` with `node_modules` at the project root:
 @source "../node_modules/@sableui/react/dist/**/*.{js,mjs}";
 ```
 
-Adjust the relative `@source` path to your stylesheet's location. Import this
-stylesheet from your app entry. For Vite, preserve your plugins and add
+Adjust the relative `@source` path to your stylesheet's location. It makes
+Tailwind generate every Sable component's classes; once the app is built,
+`sable sources --write src/sable-sources.css` lists just the ones it imports, to
+`@import` in its place (`sable check` notes this). Import this stylesheet from
+your app entry. For Vite, preserve your plugins and add
 `resolve: { dedupe: ["react", "react-dom"] }` to its configuration. Load Figtree
 and DM Mono through your font setup, or customize the font tokens.
 

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
@@ -1807,8 +1813,11 @@ For `src/styles.css` with `node_modules` at the project root:
 @source "../node_modules/@sableui/react/dist/**/*.{js,mjs}";
 ```
 
-Adjust the relative `@source` path to your stylesheet's location. Import this
-stylesheet from your app entry. For Vite, preserve your plugins and add
+Adjust the relative `@source` path to your stylesheet's location. It makes
+Tailwind generate every Sable component's classes; once the app is built,
+`sable sources --write src/sable-sources.css` lists just the ones it imports, to
+`@import` in its place (`sable check` notes this). Import this stylesheet from
+your app entry. For Vite, preserve your plugins and add
 `resolve: { dedupe: ["react", "react-dom"] }` to its configuration. Load Figtree
 and DM Mono through your font setup, or customize the font tokens.
 
@@ -2315,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
@@ -12728,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.0",
+  "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.0",
+  "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,8 @@
       "@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",
       "mono": "DM Mono",
@@ -7470,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

@@ -13,7 +13,9 @@ References inform an original direction. A reference or preset is optional.
 
 1. Run `sable check <source paths>` (default `src`). It runs `sable doctor`,
    `sable lint`, and `sable grade` and exits 1 if any fails. Repair the findings
-   instead of suppressing them, then run it again until it passes. Also run the
+   instead of suppressing them, then run it again until it passes. Act on its
+   notes too: they don't fail the check but name real work, such as trimming the
+   CSS to the components the app imports (`sable sources`). Also run the
    project's own build and type checks.
 2. Review the rendered design: `sable docs reviewing-a-design`. Capture desktop and
    mobile in every promised colour mode, and judge brief fit, composition,
@@ -34,7 +36,7 @@ References inform an original direction. A reference or preset is optional.
    lessons with evidence; never fabricate human approval or preference records.
 
 Steps 2–7 are what no tool can verify; `sable check` prints them after its
-results. A passing check is a contract result, not design approval.
+results, plus any step its notes call for. A passing check is a contract result, not design approval.
 
 ## Route the request
 
@@ -91,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.