@blakesteve/roster 3.0.0 → 4.1.0

package/README.md

@@ -31,13 +31,19 @@ Roster ships pre-compiled CSS, so you do not need Tailwind installed in your hos
 ```
 
 `DataTable` additionally needs TanStack Table v9, declared as an **optional**
-peer. Install it only if you use `DataTable`; every other component works
-without it.
+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
@@ -56,9 +62,10 @@ import "@blakesteve/roster/style.css";
 import "@blakesteve/roster/tokens.css";
 ```
 
-### Import Roster before Tailwind
+### Cascade layers
 
-If your app uses Tailwind, import Roster's CSS **before** it:
+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 */
@@ -67,11 +74,23 @@ If your app uses Tailwind, import Roster's CSS **before** it:
 @import "tailwindcss";
 ```
 
-Roster ships its styles inside a `roster` cascade layer, and CSS orders layers
-by *first registration*. Importing Roster first places its layer beneath your
-app's own utilities, so your styles always win. Import it second and the
-opposite happens: Roster's `.block` starts beating your `dark:hidden`, and
-variants fail silently with the rule present in the stylesheet.
+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
 
@@ -91,6 +110,39 @@ import "@blakesteve/roster/style.css";
 Skip it and components render against browser defaults: serif type, bulleted
 lists, and `content-box` sizing.
 
+### Dark mode
+
+Every component reads a `.dark` class on an ancestor, so dark mode is whatever
+puts that class on your document root. `ThemeToggle` is the component that does
+it, and it persists the choice to `localStorage`:
+
+```tsx
+import { ThemeToggle } from "@blakesteve/roster";
+
+<ThemeToggle />;
+```
+
+A toggle alone cannot prevent a flash of the wrong theme on first paint, because
+the class has to be on `<html>` before React runs. Add a blocking script to your
+document head:
+
+```html
+<script>
+  try {
+    var s = localStorage.getItem("roster-theme");
+    var dark = s ? s === "dark" : matchMedia("(prefers-color-scheme: dark)").matches;
+    if (dark) document.documentElement.classList.add("dark");
+  } catch (e) {}
+</script>
+```
+
+If you pass a custom `storageKey`, change the script to match — a mismatch means
+the script and the toggle disagree, which shows up as a flash on every reload.
+
+`Navbar`'s `themeMode` prop is a different thing: it describes what palette the
+bar paints *itself* with. Pair them with `themeMode="auto"` and the nav follows
+whatever `ThemeToggle` sets.
+
 ## Quick start
 
 ```tsx
@@ -127,7 +179,10 @@ function App() {
 | `Card` | Bordered surface container |
 | `Checkbox` | Accessible checkbox with label support |
 | `Disclosure` | Show/hide toggle using HeadlessUI |
+| `Eyebrow` | Small tracked-out uppercase label above a heading or beside a rule |
+| `InlineCode` | Inline `<code>` for identifiers in running prose |
 | `Input` | Text input with label, error state, and icon slots |
+| `LabeledDivider` | Horizontal rule carrying a label, with an optional trailing count |
 | `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 |
@@ -136,9 +191,11 @@ function App() {
 | `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 |
+| `Stat` | A single figure with its label and, optionally, where the figure came from |
 | `Spinner` | Loading indicator |
 | `Switch` | Toggle switch |
 | `Textarea` | Multi-line text input |
+| `ThemeToggle` | Flips class-based dark mode on the document root and remembers the choice |
 | `Tooltip` | Radix-powered tooltip: hover/focus on desktop, tap-to-toggle on mobile |
 
 ### Molecules
@@ -149,9 +206,11 @@ function App() {
 | `Alert` | Inline notice strip with optional title and dismiss |
 | `Breadcrumbs` | Navigation trail |
 | `CallToAction` | Prominent hero-style CTA block |
+| `DescriptionList` | Label and value pairs as a real `<dl>`: inline, stacked, or split |
 | `EmptyState` | Zero-data placeholder with icon and action slot |
 | `ErrorState` | Error display with retry action |
 | `MatchupCard` | Head-to-head comparison card |
+| `Pullquote` | A line lifted out of prose, as `<figure>` + `<blockquote>` + `<figcaption>` |
 
 ### Organisms
 
@@ -159,7 +218,7 @@ function App() {
 |---|---|
 | `ActionBar` | Sticky bottom action strip |
 | `Countdown` | Live countdown timer |
-| `DataTable` | Full-featured table with sorting and pagination via TanStack Table v9 (see [DataTable columns](#datatable-columns)) |
+| `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 |
@@ -172,7 +231,7 @@ 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";
+import { DataTable, type RosterTableFeatures } from "@blakesteve/roster/data-table";
 import { createColumnHelper, type ColumnDef } from "@tanstack/react-table";
 
 type Player = { name: string; points: number };
@@ -197,6 +256,7 @@ entry's value as `unknown` and recovers the real type per column through
 | Hook | Description |
 |---|---|
 | `useCountdown` | Countdown timer logic without the UI |
+| `useKeySequence` | Fires a callback when a sequence of keys is typed in order. Ships `KONAMI_CODE` |
 
 ## Development
 
@@ -233,6 +293,7 @@ Output in `dist/`:
 |---|---|
 | `roster.es.js` | ES module bundle |
 | `roster.umd.js` | UMD bundle |
+| `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) |