@blakesteve/roster 2.9.5 → 4.0.0

package/README.md

@@ -2,16 +2,16 @@
 
 A production-grade atomic component library built with **React 19**, **TypeScript**, **Tailwind CSS v4**, and **Vite**.
 
-Roster ships a curated set of accessible, theme-aware components organized around the Atomic Design methodology — atoms, molecules, and organisms — each with Storybook documentation and full test coverage.
+Roster ships a curated set of accessible, theme-aware components organized around the Atomic Design methodology (atoms, molecules, and organisms), each with Storybook documentation and full test coverage.
 
 ## Features
 
-- **Atomic Design** — components organized as atoms, molecules, and organisms
-- **TypeScript first** — fully typed props with exported variant types for maximum DX
-- **Adaptive dark mode** — class-based toggling (`.dark`) independent of OS preferences
-- **`"use client"` pre-bundled** — all outputs include the directive for seamless Next.js App Router integration
-- **Accessible** — interactive components powered by [`@headlessui/react`](https://headlessui.com) and [`@radix-ui`](https://radix-ui.com)
-- **Tree-shakeable** — import only what you need
+- **Atomic Design**: components organized as atoms, molecules, and organisms
+- **TypeScript first**: fully typed props with exported variant types for maximum DX
+- **Adaptive dark mode**: class-based toggling (`.dark`) independent of OS preferences
+- **`"use client"` pre-bundled**: all outputs include the directive for seamless Next.js App Router integration
+- **Accessible**: interactive components powered by [`@headlessui/react`](https://headlessui.com) and [`@radix-ui`](https://radix-ui.com)
+- **Tree-shakeable**: import only what you need
 
 ## Installation
 
@@ -19,7 +19,7 @@ Roster ships a curated set of accessible, theme-aware components organized aroun
 npm install @blakesteve/roster
 ```
 
-Roster ships pre-compiled CSS — you do not need Tailwind installed in your host app to use it.
+Roster ships pre-compiled CSS, so you do not need Tailwind installed in your host app to use it.
 
 ### Peer dependencies
 
@@ -30,12 +30,31 @@ Roster ships pre-compiled CSS — you do not need Tailwind installed in your hos
 }
 ```
 
+`DataTable` additionally needs TanStack Table v9, declared as an **optional**
+peer. It ships from its own entry point so that peer stays genuinely optional:
+importing anything from `@blakesteve/roster` never pulls TanStack in, because a
+bundler resolves imports before it tree-shakes. Install it only if you use
+`DataTable`; every other component works without it.
+
+```bash
+npm install @tanstack/react-table
+```
+
+```tsx
+import { DataTable, type RosterTableFeatures } from "@blakesteve/roster/data-table";
+```
+
+It is a peer rather than a bundled dependency because v9 types column
+definitions against the feature set that built the table. Two copies of the
+package would mean two incompatible sets of those types, so roster and your
+app have to resolve the same one.
+
 ## Setup
 
 Import Roster's CSS once at the root of your application (`layout.tsx`, `main.tsx`, or `App.tsx`):
 
 ```tsx
-// Compiled component styles — always required
+// Compiled component styles (always required)
 import "@blakesteve/roster/style.css";
 
 // Default design tokens (color palette, spacing, radius)
@@ -43,6 +62,54 @@ import "@blakesteve/roster/style.css";
 import "@blakesteve/roster/tokens.css";
 ```
 
+### Cascade layers
+
+Roster ships its styles inside a `roster` cascade layer and declares the full
+layer order in its own stylesheet, so importing it is normally enough:
+
+```css
+/* globals.css */
+@import "@blakesteve/roster/tokens.css";
+@import "@blakesteve/roster/style.css";
+@import "tailwindcss";
+```
+
+The order Roster declares is:
+
+```css
+@layer roster-preflight, theme, base, components, roster, utilities;
+```
+
+`roster` has to sit in that exact slot. **Above `base`**, because Tailwind's
+preflight resets `*{margin:0;padding:0;border:0 solid}` — put Roster below it
+and that reset outranks Roster's own spacing and border utilities, silently
+stripping padding off buttons and turning `border-transparent` into a visible
+1px line. **Below `utilities`**, so your app's classes and variants such as
+`dark:hidden` still win.
+
+Layers are ordered by *first registration*, so importing Roster before Tailwind
+is the reliable arrangement. If you would rather not depend on import order at
+all, declare the same line yourself at the top of your global stylesheet and it
+holds regardless.
+
+### The global reset is opt-in
+
+Roster ships **no** preflight. A component library has no business resetting
+its host's document, so importing Roster will not change your headings, lists,
+or box sizing.
+
+Roster's components do assume that normalization exists, though. If your app
+runs Tailwind, you already have it and there is nothing to do. If it does not,
+opt in, before the component styles:
+
+```tsx
+import "@blakesteve/roster/preflight.css";
+import "@blakesteve/roster/style.css";
+```
+
+Skip it and components render against browser defaults: serif type, bulleted
+lists, and `content-box` sizing.
+
 ## Quick start
 
 ```tsx
@@ -75,27 +142,30 @@ function App() {
 |---|---|
 | `Avatar` | User avatar with image, initials fallback, and optional popover |
 | `Badge` | Status label with semantic color schemes and fill variants |
-| `Button` | Primary interactive element — solid, soft, outline, ghost, link variants |
+| `Button` | Primary interactive element: solid, soft, outline, ghost, link variants |
 | `Card` | Bordered surface container |
 | `Checkbox` | Accessible checkbox with label support |
 | `Disclosure` | Show/hide toggle using HeadlessUI |
 | `Input` | Text input with label, error state, and icon slots |
 | `Link` | Styled anchor with variant support |
+| `PasswordInput` | Password field with a show/hide reveal toggle |
+| `Pill` | Inline phrase chrome: social proof, live state, applied filters |
 | `AvatarStrip` | Stacked avatar row with overflow chip, dismiss button, trailing slot, and label area |
 | `CollapsibleSection` | Clamps any content (prose, chips, image grids) to a fixed height with a fade and expand/collapse toggle |
-| `LiquidTabs` | Controlled tab strip with a liquid sliding pill indicator — pill and filled variants |
+| `LiquidTabs` | Controlled tab strip with a liquid sliding pill indicator: pill and filled variants |
 | `Select` | Dropdown selector |
 | `SegmentBar` | Proportional horizontal bar divided into colored segments with optional legend |
 | `Spinner` | Loading indicator |
 | `Switch` | Toggle switch |
 | `Textarea` | Multi-line text input |
-| `Tooltip` | Radix-powered tooltip — hover/focus on desktop, tap-to-toggle on mobile |
+| `Tooltip` | Radix-powered tooltip: hover/focus on desktop, tap-to-toggle on mobile |
 
 ### Molecules
 
 | Component | Description |
 |---|---|
 | `Accordion` | Collapsible content sections (single or multi-expand) |
+| `Alert` | Inline notice strip with optional title and dismiss |
 | `Breadcrumbs` | Navigation trail |
 | `CallToAction` | Prominent hero-style CTA block |
 | `EmptyState` | Zero-data placeholder with icon and action slot |
@@ -108,12 +178,39 @@ function App() {
 |---|---|
 | `ActionBar` | Sticky bottom action strip |
 | `Countdown` | Live countdown timer |
-| `DataTable` | Full-featured table with sorting and pagination via TanStack Table |
+| `DataTable` | Full-featured table with sorting and pagination via TanStack Table v9. Imported from `@blakesteve/roster/data-table` (see [DataTable columns](#datatable-columns)) |
 | `Dialog` | Modal dialog |
 | `Footer` | Site footer |
 | `Navbar` | Responsive navigation bar with mobile slide-out |
 | `Table` | Static data table |
 
+### DataTable columns
+
+TanStack Table v9 types column definitions against the feature set that built
+the table. `DataTable` registers sorting and pagination and exports that set as
+`RosterTableFeatures`, so your columns name it:
+
+```tsx
+import { DataTable, type RosterTableFeatures } from "@blakesteve/roster/data-table";
+import { createColumnHelper, type ColumnDef } from "@tanstack/react-table";
+
+type Player = { name: string; points: number };
+
+const columns: ColumnDef<RosterTableFeatures, Player>[] = [
+  { accessorKey: "name", header: "Player" },
+  { accessorKey: "points", header: "Points" },
+];
+
+// Or, to keep each column's value type:
+const helper = createColumnHelper<RosterTableFeatures, Player>();
+```
+
+Upgrading from roster 2.x: `ColumnDef<Player, unknown>` becomes
+`ColumnDef<RosterTableFeatures, Player>`, and `DataTableProps` takes one type
+argument instead of two. A columns array is heterogeneous, so v9 types each
+entry's value as `unknown` and recovers the real type per column through
+`createColumnHelper`.
+
 ### Hooks
 
 | Hook | Description |
@@ -155,8 +252,10 @@ Output in `dist/`:
 |---|---|
 | `roster.es.js` | ES module bundle |
 | `roster.umd.js` | UMD bundle |
-| `roster.css` | Compiled component styles |
+| `data-table.es.js` | DataTable entry, keeping the TanStack import out of the main bundle |
+| `roster.css` | Compiled component styles, in the `roster` cascade layer |
 | `tokens.css` | Design token CSS variables |
+| `preflight.css` | Optional global reset (see Setup) |
 | `index.d.ts` | TypeScript definitions |
 
 ## Contributing