fluent-styles 1.61.0 → 1.62.1

package/README.md

@@ -20,7 +20,8 @@ A comprehensive, TypeScript-first React Native UI library providing production-r
   - [StyledCard](#styledcard)
   - [StyledBadge / BadgeWithIcon](#styledbadge--badgewithicon)
   - [StyledImage / StyledImageBackground](#styledimage--styledimagebackground)
-  - [StyledHeader / FullHeader](#styledheader--fullheader)
+  - [StyledHeader](#styledheader)
+  - [StyledForm](#styledform)
   - [StyledDropdown / StyledMultiSelectDropdown](#styleddropdown--styledmultiselectdropdown)
   - [Popup](#popup)
   - [Drawer](#drawer)
@@ -33,7 +34,7 @@ A comprehensive, TypeScript-first React Native UI library providing production-r
   - [StyledPressable](#styledpressable)
   - [StyledPage / StyledScrollView](#styledpage--styledscrollview)
   - [StyledSafeAreaView](#styledsafeareaview)
-  - [Spacer](#spacer)
+  - [Spacer / StyledSpacer](#spacer--styledspacer)
   - [StyledShape](#styledshape)
   - [Loader](#loader)
   - [StyledCircularProgress](#styledcircularprogress)
@@ -44,6 +45,7 @@ A comprehensive, TypeScript-first React Native UI library providing production-r
   - [StyledProgressBar](#styledprogressbar)
   - [StyledSlider](#styledslider)
   - [StyledDatePicker](#styleddatepicker)
+  - [StyledTable](#styledtable)
 - [Hooks](#hooks)
   - [useToast](#usetoast)
   - [useNotification](#usenotification)
@@ -586,43 +588,129 @@ import { StyledImage, StyledImageBackground } from 'fluent-styles'
 
 ---
 
-### StyledHeader / FullHeader
+### StyledHeader
 
-A pre-built navigation header with optional status bar management.
+A composable navigation header with status bar management, slot-based layout, and a `StyledHeader.Full` escape hatch for fully custom content.
 
 ```tsx
-import { StyledHeader, FullHeader } from 'fluent-styles'
+import { StyledHeader } from 'fluent-styles'
 
+// ── Basic title alignments ───────────────────────────────────────────────────
+<StyledHeader title="Left aligned"   titleAlignment="left"   showStatusBar={false} />
+<StyledHeader title="Center aligned" titleAlignment="center" showStatusBar={false} />
+<StyledHeader title="Right aligned"  titleAlignment="right"  showStatusBar={false} />
+
+// ── Back arrow ───────────────────────────────────────────────────────────────
+<StyledHeader
+  title="Go back"
+  showBackArrow
+  onBackPress={() => navigation.goBack()}
+/>
+
+// Custom back arrow colour + size
+<StyledHeader
+  title="Profile"
+  titleAlignment="center"
+  showBackArrow
+  backArrowProps={{ size: 20, color: '#6366f1' }}
+  onBackPress={() => navigation.goBack()}
+/>
+
+// ── Right / left icons ───────────────────────────────────────────────────────
 <StyledHeader
-  title="Settings"
+  title="Notifications"
   titleAlignment="center"
   showBackArrow
   onBackPress={() => navigation.goBack()}
   rightIcon={<SettingsIcon />}
 />
 
-// Custom back button styling
+// Multiple right icons
 <StyledHeader
-  title="Profile"
+  title="Photos"
+  titleAlignment="center"
   showBackArrow
-  backArrowProps={{ size: 20, color: '#6366f1', onPress: () => navigation.goBack() }}
+  onBackPress={() => navigation.goBack()}
+  rightIcon={
+    <Stack horizontal gap={8}>
+      <SearchIconBtn />
+      <MoreIconBtn />
+    </Stack>
+  }
 />
 
-// Full header — manages status bar spacer automatically
-<FullHeader statusBarProps={{ barStyle: 'dark-content' }}>
-  <MyCustomHeaderContent />
-</FullHeader>
+// Logo + action on the right (no back arrow)
+<StyledHeader
+  titleAlignment="left"
+  leftIcon={
+    <Stack horizontal gap={6} alignItems="center">
+      <BrandLogo />
+      <StyledText fontSize={16} fontWeight="800">fluent</StyledText>
+    </Stack>
+  }
+  rightIcon={<CartIconBtn />}
+/>
+
+// ── Themed background ────────────────────────────────────────────────────────
+<StyledHeader
+  title="Dark header"
+  titleAlignment="center"
+  showBackArrow
+  onBackPress={() => navigation.goBack()}
+  backgroundColor={theme.colors.gray[900]}
+  titleProps={{ color: '#fff', fontWeight: '700' }}
+  backArrowProps={{ color: '#fff' }}
+/>
+
+// ── StyledHeader.Full — fully custom children ────────────────────────────────
+// Renders children directly inside the container; skips the built-in layout slots.
+// Useful for search bars, tab strips, chat headers, etc.
+<StyledHeader showStatusBar={false} backgroundColor={palettes.white}>
+  <StyledHeader.Full>
+    <Stack flex={1} horizontal alignItems="center" paddingHorizontal={12} gap={10}>
+      <BackBtn />
+      <SearchBar />
+      <CancelBtn />
+    </Stack>
+  </StyledHeader.Full>
+</StyledHeader>
+
+// Chat-style header with avatar + call buttons
+<StyledHeader showStatusBar={false} backgroundColor={palettes.white}>
+  <StyledHeader.Full>
+    <Stack flex={1} horizontal alignItems="center" paddingHorizontal={12} gap={10}>
+      <BackBtn />
+      <Avatar uri={avatarUri} size={36} />
+      <Stack flex={1} gap={1}>
+        <StyledText fontSize={14} fontWeight="700">Priya Kapoor</StyledText>
+        <StyledText fontSize={11} color={palettes.teal[500]}>Active now</StyledText>
+      </Stack>
+      <CallBtn />
+      <VideoBtn />
+    </Stack>
+  </StyledHeader.Full>
+</StyledHeader>
 ```
 
-| Prop | Type | Description |
-|---|---|---|
-| `title` | `string` | Header title |
-| `titleAlignment` | `left \| center \| right` | Title alignment |
-| `showBackArrow` | `boolean` | Renders a back arrow |
-| `onBackPress` | `() => void` | Back arrow handler |
-| `leftIcon / rightIcon` | `ReactNode` | Custom icon slots |
-| `backArrowProps` | `BackArrowProps` | Size, colour, custom press handler |
-| `showStatusBar` | `boolean` | Include status bar spacer |
+#### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | — | Header title |
+| `titleAlignment` | `left \| center \| right` | `left` | Title position |
+| `titleProps` | `StyledTextProps` | — | Font/colour overrides for the title |
+| `showBackArrow` | `boolean` | `false` | Renders a chevron back arrow |
+| `onBackPress` | `() => void` | — | Tapped when the back arrow is pressed |
+| `backArrowProps` | `BackArrowProps` | — | `size`, `color`, `strokeWidth` overrides |
+| `leftIcon` | `ReactNode` | — | Custom left-slot content (replaces back arrow) |
+| `rightIcon` | `ReactNode` | — | Custom right-slot content |
+| `showStatusBar` | `boolean` | `true` | Include status bar spacer above the header |
+| `statusBarProps` | `StatusBarProps` | — | Forwarded to the internal `StatusBar` component |
+| `skipStatusBarOnAndroid` | `boolean` | `true` | Skip spacer on Android |
+| `skipStatusBarOnIOS` | `boolean` | `true` | Skip spacer on iOS |
+| `children` | `ReactNode` | — | When present (via `StyledHeader.Full`), replaces built-in slot layout |
+
+All flat `ViewStyle` props (`backgroundColor`, `paddingHorizontal`, `borderRadius`, …) are forwarded to the container.
 
 ---
 
@@ -1127,18 +1215,42 @@ import { StyledPressable } from 'fluent-styles'
 
 ### StyledPage / StyledScrollView
 
-Base layout containers.
+`StyledPage` is the recommended **top-level layout wrapper for every screen**. It wraps `StyledSafeAreaView` so safe area insets are handled automatically, and accepts all `ViewStyle` props for quick background colour, padding, and flex tweaks. Pair it with `StyledScrollView` for scrollable screens or nest a `StyledHeader` + content directly inside for fixed-layout screens.
 
 ```tsx
-import { StyledPage, StyledScrollView } from 'fluent-styles'
+import { StyledPage, StyledScrollView, StyledHeader } from 'fluent-styles'
+
+// ── Scrollable screen (most screens) ────────────────────────────────────────
+export default function SettingsScreen() {
+  return (
+    <StyledPage flex={1} backgroundColor="#f8f8f8">
+      <StyledHeader title="Settings" titleAlignment="left" showStatusBar={false} />
+      <StyledScrollView contentContainerStyle={{ padding: 16, paddingBottom: 40 }}>
+        {/* screen content */}
+      </StyledScrollView>
+    </StyledPage>
+  )
+}
+
+// ── Fixed layout screen (e.g. chat, camera) ──────────────────────────────────
+export default function ChatScreen() {
+  return (
+    <StyledPage flex={1} backgroundColor="#fff">
+      <StyledHeader title="Priya Kapoor" showBackArrow onBackPress={() => navigation.goBack()} />
+      <MessageList style={{ flex: 1 }} />
+      <MessageComposer />
+    </StyledPage>
+  )
+}
 
-<StyledPage flex={1} backgroundColor="#f8f8f8">
-  <StyledScrollView contentContainerStyle={{ padding: 16 }}>
-    <MyContent />
-  </StyledScrollView>
+// ── Custom background / padding ──────────────────────────────────────────────
+<StyledPage flex={1} backgroundColor={theme.colors.gray[50]} paddingHorizontal={16}>
+  {/* content */}
 </StyledPage>
 ```
 
+Accepts all `SafeAreaViewProps` and flat `ViewStyle` props.
+
 ---
 
 ### StyledSafeAreaView
@@ -1155,17 +1267,31 @@ import { StyledSafeAreaView } from 'fluent-styles'
 
 ---
 
-### Spacer
+### Spacer / StyledSpacer
 
-Inserts fixed or flexible whitespace.
+Inserts fixed or flexible whitespace between elements.
 
 ```tsx
-import { Spacer } from 'fluent-styles'
+import { StyledSpacer } from 'fluent-styles'
+
+// Fixed height gap
+<StyledSpacer height={16} />
+
+// Flexible — fills remaining space (like a CSS flex spacer)
+<StyledSpacer flex={1} />
 
-<Spacer height={16} />
-<Spacer flex={1} />  {/* fills remaining space */}
+// Horizontal gap inside a row
+<Stack horizontal alignItems="center">
+  <Icon />
+  <StyledSpacer width={8} />
+  <StyledText>Label</StyledText>
+  <StyledSpacer flex={1} />
+  <ChevronIcon />
+</Stack>
 ```
 
+**Props:** `height`, `width`, `flex`, `margin`, `marginTop`, `marginBottom`, `marginHorizontal`, `marginVertical`, `backgroundColor`
+
 ---
 
 ### StyledShape
@@ -2677,6 +2803,439 @@ const DURATION = 243
 
 ---
 
+### StyledForm
+
+A composable form wrapper that propagates `disabled` / `loading` state to all sub-components via React context, with optional keyboard avoidance and scroll wrapping.
+
+```tsx
+import { StyledForm } from 'fluent-styles'
+```
+
+#### Sub-components
+
+| Component | Wraps | Description |
+|---|---|---|
+| `StyledForm.Row` | `Stack horizontal` | Side-by-side inputs |
+| `StyledForm.Section` | — | Grouped block with title, subtitle, and optional divider |
+| `StyledForm.Actions` | `Stack` | Slot for submit/cancel buttons |
+| `StyledForm.Input` | `StyledTextInput` | Text input that inherits form `disabled` / `loading` |
+| `StyledForm.Checkbox` | `StyledCheckBox` | Checkbox that inherits form `disabled` |
+| `StyledForm.Switch` | `Switch` | Toggle that inherits form `disabled` / `loading` |
+| `StyledForm.Select` | `StyledDropdown` | Dropdown picker that inherits form `disabled` |
+| `StyledForm.Radio` | `StyledRadioGroup` | Radio group |
+| `StyledForm.DatePicker` | `StyledDatePicker` | Date/time picker that inherits form `disabled` |
+| `StyledForm.Slider` | `StyledSlider` | Slider that inherits form `disabled` |
+
+#### `StyledForm` root props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `disabled` | `boolean` | `false` | Disables all sub-components via context |
+| `loading` | `boolean` | `false` | Sets loading state on compatible sub-components |
+| `gap` | `number` | `16` | Vertical gap between form fields |
+| `avoidKeyboard` | `boolean` | `true` | Wraps content in `KeyboardAvoidingView` |
+| `scrollable` | `boolean` | `false` | Wraps content in a `ScrollView` |
+| `scrollPadding` | `number` | `40` | Bottom padding inside the scroll view |
+
+#### Usage
+
+```tsx
+import { StyledForm, StyledButton, StyledText, StyledDivider, Stack, theme, palettes } from 'fluent-styles'
+
+// ── 1. Sign-up form — inputs, checkbox, inline validation ────────────────────
+const [email, setEmail]       = useState('')
+const [password, setPassword] = useState('')
+const [agreed, setAgreed]     = useState(false)
+const [loading, setLoading]   = useState(false)
+
+const errors = {
+  email:    email.length > 0 && !email.includes('@') ? 'Enter a valid email' : undefined,
+  password: password.length > 0 && password.length < 8 ? 'At least 8 characters' : undefined,
+}
+
+<StyledForm gap={16} avoidKeyboard={false} disabled={loading}>
+  <StyledForm.Input
+    label="Email address"
+    required
+    variant="outline"
+    placeholder="you@example.com"
+    keyboardType="email-address"
+    autoCapitalize="none"
+    value={email}
+    onChangeText={setEmail}
+    error={!!errors.email}
+    errorMessage={errors.email}
+  />
+
+  <StyledForm.Input
+    label="Password"
+    required
+    variant="outline"
+    placeholder="8+ characters"
+    secureTextEntry
+    value={password}
+    onChangeText={setPassword}
+    error={!!errors.password}
+    errorMessage={errors.password}
+  />
+
+  <StyledDivider borderBottomColor={theme.colors.gray[100]} />
+
+  <Stack horizontal alignItems="center" gap={12}>
+    <StyledForm.Checkbox checked={agreed} onCheck={setAgreed} />
+    <StyledText fontSize={13}>I agree to the Terms of Service</StyledText>
+  </Stack>
+
+  <StyledForm.Actions>
+    <StyledButton block loading={loading} onPress={handleSubmit}
+      backgroundColor={palettes.indigo[600]}>
+      <StyledText color="#fff" fontSize={15} fontWeight="700">
+        {loading ? 'Creating account…' : 'Create account'}
+      </StyledText>
+    </StyledButton>
+  </StyledForm.Actions>
+</StyledForm>
+
+// ── 2. Profile form — Row, Section, Select, DatePicker, Switch ───────────────
+<StyledForm gap={20} avoidKeyboard={false}>
+  <StyledForm.Section title="Personal details" subtitle="How you appear to others">
+    <StyledForm.Row>
+      <StyledForm.Input label="First name" flex={1} variant="outline"
+        value={firstName} onChangeText={setFirstName} />
+      <StyledForm.Input label="Last name"  flex={1} variant="outline"
+        value={lastName}  onChangeText={setLastName}  />
+    </StyledForm.Row>
+
+    <StyledForm.Input
+      label="Bio" variant="outline" multiline showCounter maxLength={160}
+      value={bio} onChangeText={setBio} helperText="Shown on your public profile"
+    />
+
+    {/* StyledForm.Select uses the `data` prop (same as StyledDropdown) */}
+    <StyledForm.Select
+      label="Country"
+      variant="outline"
+      data={COUNTRY_OPTIONS}
+      value={country}
+      onChange={(item) => setCountry(item.value)}
+      placeholder="Select country"
+    />
+
+    <StyledForm.DatePicker
+      label="Date of birth" mode="date" variant="input"
+      value={dob} onChange={setDob} onConfirm={setDob}
+    />
+  </StyledForm.Section>
+
+  <StyledForm.Section title="Notifications">
+    <Stack horizontal alignItems="center" justifyContent="space-between">
+      <StyledText fontSize={14} fontWeight="600">Newsletter</StyledText>
+      <StyledForm.Switch value={newsletter} onChange={setNewsletter}
+        activeColor={palettes.indigo[600]} />
+    </Stack>
+  </StyledForm.Section>
+
+  <StyledForm.Actions horizontal gap={10}>
+    <StyledButton outline compact flex={1} onPress={discard}>
+      <StyledText fontSize={14} fontWeight="600">Discard</StyledText>
+    </StyledButton>
+    <StyledButton primary compact flex={1}
+      backgroundColor={palettes.indigo[600]} onPress={save}>
+      <StyledText fontSize={14} fontWeight="700" color="#fff">Save</StyledText>
+    </StyledButton>
+  </StyledForm.Actions>
+</StyledForm>
+
+// ── 3. Subscription form — Radio, Slider, form-level disabled context ─────────
+// Setting `disabled` on <StyledForm> propagates down to every sub-component.
+<StyledForm gap={20} avoidKeyboard={false} disabled={locked}>
+  <StyledForm.Section title="Choose a plan">
+    <StyledForm.Radio
+      options={PLAN_OPTIONS}
+      value={plan}
+      onChange={setPlan}
+      variant="list"
+      colors={{ active: palettes.indigo[600] }}
+    />
+  </StyledForm.Section>
+
+  <StyledForm.Section title="Team size">
+    <StyledForm.Slider
+      value={seats}
+      min={2} max={50} step={1}
+      onValueChange={setSeats}
+      formatLabel={(v) => `${v} seats`}
+      colors={{ fill: palettes.indigo[600] }}
+    />
+  </StyledForm.Section>
+
+  <StyledForm.Actions>
+    <StyledButton primary block onPress={() => setLocked((v) => !v)}
+      backgroundColor={locked ? theme.colors.gray[300] : palettes.indigo[600]}>
+      <StyledText fontSize={15} fontWeight="700" color="#fff">
+        {locked ? '🔒 Disabled (tap to re-enable)' : 'Subscribe'}
+      </StyledText>
+    </StyledButton>
+  </StyledForm.Actions>
+</StyledForm>
+
+// ── 4. Filter panel — compact, no sections ───────────────────────────────────
+<StyledForm gap={14} avoidKeyboard={false}>
+  <StyledForm.Input
+    variant="filled" placeholder="Search products…"
+    value={query} onChangeText={setQuery} clearable
+  />
+
+  <StyledForm.Select
+    label="Region" variant="outline" size="sm"
+    data={COUNTRY_OPTIONS} value={country}
+    onChange={(item) => setCountry(item.value)}
+    placeholder="All regions"
+  />
+
+  <StyledForm.Slider
+    variant="range"
+    value={minPrice} valueHigh={maxPrice}
+    min={0} max={1000} step={10}
+    onRangeChange={(lo, hi) => { setMinPrice(lo); setMaxPrice(hi) }}
+    formatLabel={(v) => `$${v}`}
+  />
+
+  <Stack horizontal alignItems="center" justifyContent="space-between">
+    <StyledText fontSize={14} fontWeight="600">In stock only</StyledText>
+    <StyledForm.Switch value={inStock} onChange={setInStock} size="sm" />
+  </Stack>
+
+  <StyledForm.Actions horizontal gap={10}>
+    <StyledButton outline compact flex={1} onPress={resetFilters}>
+      <StyledText fontSize={13} fontWeight="600">Reset</StyledText>
+    </StyledButton>
+    <StyledButton primary compact flex={2}
+      backgroundColor={theme.colors.gray[900]}>
+      <StyledText fontSize={13} fontWeight="700" color="#fff">Apply filters</StyledText>
+    </StyledButton>
+  </StyledForm.Actions>
+</StyledForm>
+```
+
+> **Note:** `StyledForm.Select` wraps `StyledDropdown` and therefore uses the `data` prop (not `options`). `StyledForm.Radio` wraps `StyledRadioGroup` and uses the `options` prop.
+
+---
+
+### StyledTable
+
+A responsive data table with client-side and server-side pagination, sortable columns, row selection, striped / dark variants, and an automatic card layout on narrow screens.
+
+```tsx
+import { StyledTable, type TableColumn, usePaginatedQuery } from 'fluent-styles'
+```
+
+#### `TableColumn<T>` definition
+
+| Field | Type | Description |
+|---|---|---|
+| `key` | `string` | Must match a key of the row data object |
+| `title` | `string` | Column header label |
+| `width` | `number` | Fixed column width in px. Omit to stretch (flex: 1) |
+| `align` | `left \| center \| right` | Text alignment (default `left`) |
+| `sortable` | `boolean` | Allow tapping the header to sort |
+| `render` | `(value, row, index) => ReactNode` | Custom cell renderer |
+
+#### `StyledTable` props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `columns` | `TableColumn<T>[]` | — | Column definitions |
+| `data` | `T[]` | — | Row data (each row must have a unique `id` field) |
+| `selectable` | `boolean` | `false` | Show checkboxes for row selection |
+| `selectedIds` | `(string \| number)[]` | — | Controlled selection |
+| `onSelectionChange` | `(ids) => void` | — | Selection change callback |
+| `sortKey` | `string \| null` | — | Controlled sort column |
+| `sortDirection` | `asc \| desc \| null` | — | Controlled sort direction |
+| `onSort` | `(key, direction) => void` | — | Sort change callback |
+| `pagination` | `boolean` | `false` | Enable internal (client-side) pagination |
+| `pageSize` | `number` | `10` | Rows per page (internal pagination) |
+| `externalPagination` | `boolean` | `false` | Render `data` as-is — parent manages pages |
+| `currentPage` | `number` | — | 0-based current page (controlled) |
+| `totalPages` | `number` | — | Total pages from the datasource |
+| `totalCount` | `number` | — | Total record count |
+| `onPageChange` | `(page: number) => void` | — | Page change callback |
+| `loading` | `boolean` | `false` | Show loading skeleton over rows |
+| `virtualized` | `boolean` | auto | Use `FlatList` renderer (auto-enabled for >50 rows) |
+| `striped` | `boolean` | `false` | Alternating row background |
+| `showDivider` | `boolean` | `false` | Horizontal divider between rows |
+| `scrollable` | `boolean` | `false` | Horizontal scroll when content overflows |
+| `emptyText` | `string` | — | Text shown when `data` is empty |
+| `emptyNode` | `ReactNode` | — | Custom empty state node |
+| `colors` | `Partial<TableColors>` | — | Color token overrides |
+| `borderRadius` | `number` | `16` | Outer container border radius |
+| `bordered` | `boolean` | `true` | Show outer card border |
+| `cardBreakpoint` | `number` | `768` | Width threshold below which rows switch to card layout |
+| `forceTable` | `boolean` | `false` | Always render table rows regardless of screen width |
+| `forceCards` | `boolean` | `false` | Always render card layout regardless of screen width |
+| `cardRender` | `(row, index, selected, onToggle?) => ReactNode` | — | Custom card renderer for narrow screens |
+| `onRowPress` | `(row, index) => void` | — | Row tap callback |
+
+#### Usage
+
+```tsx
+import { StyledTable, type TableColumn, theme, palettes } from 'fluent-styles'
+
+// ── 1. Minimal — static data, no pagination ────────────────────────────────
+interface UserRow { id: number; name: string; email: string; role: string }
+
+const USER_COLS: TableColumn<UserRow>[] = [
+  { key: 'name',  title: 'Name',  render: (v) => <StyledText fontWeight="700">{v}</StyledText> },
+  { key: 'email', title: 'Email', render: (v) => <StyledText color={theme.colors.gray[500]}>{v}</StyledText> },
+  { key: 'role',  title: 'Role',  width: 90, align: 'center' },
+]
+
+<StyledTable columns={USER_COLS} data={users} showDivider />
+
+// ── 2. Sortable + selectable ───────────────────────────────────────────────
+const [sel, setSel] = useState<(string | number)[]>([])
+
+const PRODUCT_COLS: TableColumn<ProductRow>[] = [
+  { key: 'name',  title: 'Product' },
+  { key: 'price', title: 'Price',  width: 80, align: 'right', sortable: true,
+    render: (v) => <StyledText fontWeight="700">${v}</StyledText> },
+  { key: 'stock', title: 'Stock',  width: 80, align: 'center', sortable: true },
+  { key: 'status', title: 'Status', width: 110, align: 'center',
+    render: (v) => <StatusBadge label={v} /> },
+]
+
+<StyledTable
+  columns={PRODUCT_COLS}
+  data={products}
+  selectable
+  selectedIds={sel}
+  onSelectionChange={setSel}
+  showDivider
+  pagination
+  pageSize={8}
+/>
+
+// ── 3. Client-side pagination ──────────────────────────────────────────────
+<StyledTable
+  columns={ORDER_COLS}
+  data={orders}          // pass the full dataset
+  pagination             // StyledTable slices it internally
+  pageSize={10}
+  showDivider
+  bordered
+/>
+
+// ── 4. External pagination (REST API) ─────────────────────────────────────
+// Use the `usePaginatedQuery` hook to manage page state, sorting, search,
+// and loading — then spread `table.tableProps` onto StyledTable.
+const table = usePaginatedQuery<Order>({
+  pageSize: 10,
+  fetcher: async ({ page, pageSize, sortKey, sortDir, search, filters }) => {
+    const res = await api.get('/orders', { params: { page, pageSize, sortKey, sortDir, search, ...filters } })
+    return { data: res.data.items, totalCount: res.data.total }
+  },
+  initialSortKey: 'date',
+  initialSortDir: 'desc',
+})
+
+<StyledTable
+  columns={ORDER_COLS}
+  {...table.tableProps}   // wires data, loading, pagination state, sort, onSort, onPageChange
+  showDivider
+  bordered
+/>
+
+// ── 5. Realm / SQLite (synchronous) ───────────────────────────────────────
+const table = usePaginatedQuery<Employee>({
+  pageSize: 15,
+  realmQuery: ({ page, pageSize, sortKey, sortDir, search }) => {
+    const results = realm.objects('Employee').sorted(sortKey ?? 'name', sortDir === 'desc')
+    return { data: Array.from(results).slice(page * pageSize, (page + 1) * pageSize), totalCount: results.length }
+  },
+})
+
+<StyledTable columns={EMP_COLS} {...table.tableProps} showDivider bordered />
+
+// ── 6. Custom card layout (narrow screens) ────────────────────────────────
+// `forceCards` renders the custom card renderer regardless of screen width.
+// `forceTable` always renders the table.
+// Default: auto-switches at the `cardBreakpoint` (768 px).
+<StyledTable
+  columns={PRODUCT_COLS}
+  data={products}
+  pagination
+  pageSize={6}
+  forceCards
+  bordered={false}
+  cardRender={(row, index, isSelected, onToggle) => (
+    <ProductCard row={row} isSelected={isSelected} onToggle={onToggle} />
+  )}
+/>
+
+// ── 7. Striped + dark theme ────────────────────────────────────────────────
+// Striped
+<StyledTable columns={USER_COLS} data={users} striped showDivider={false} />
+
+// Dark theme via color overrides
+<StyledTable
+  columns={USER_COLS}
+  data={users}
+  showDivider
+  colors={{
+    background:     theme.colors.gray[900],
+    headerBg:       theme.colors.gray[800],
+    headerText:     theme.colors.gray[400],
+    rowBg:          theme.colors.gray[900],
+    border:         theme.colors.gray[700],
+    divider:        theme.colors.gray[700],
+    text:           theme.colors.gray[100],
+    sortActive:     theme.colors.gray[100],
+    sortInactive:   theme.colors.gray[600],
+    selectedBg:     palettes.indigo[900],
+    selectedBorder: palettes.indigo[500],
+  }}
+/>
+
+// ── 8. Custom empty state ─────────────────────────────────────────────────
+<StyledTable
+  columns={USER_COLS}
+  data={[]}
+  emptyNode={
+    <Stack alignItems="center" gap={8}>
+      <StyledText fontSize={32}>🗂️</StyledText>
+      <StyledText fontSize={15} fontWeight="700">No users yet</StyledText>
+      <StyledText fontSize={13} color={theme.colors.gray[400]}>Invite someone to get started.</StyledText>
+    </Stack>
+  }
+/>
+```
+
+#### `usePaginatedQuery` hook
+
+Manages page, sort, search, filters, loading, and error for external data sources. Returns `table.tableProps` which can be spread directly onto `StyledTable`.
+
+```tsx
+const table = usePaginatedQuery<T>(options)
+
+// Spread onto StyledTable:
+<StyledTable columns={COLS} {...table.tableProps} />
+```
+
+| Option | Type | Description |
+|---|---|---|
+| `pageSize` | `number` | Rows per page |
+| `fetcher` | `async (params) => { data, totalCount }` | Async REST / GraphQL fetcher |
+| `realmQuery` | `(params) => { data, totalCount }` | Synchronous Realm / SQLite query |
+| `initialSortKey` | `string` | Initial sort column |
+| `initialSortDir` | `asc \| desc \| null` | Initial sort direction |
+| `initialSearch` | `string` | Initial search string |
+| `initialFilters` | `Record<string, any>` | Initial filter values |
+| `searchDebounce` | `number` | Search debounce ms (default 300) |
+
+`table` return value exposes: `data`, `loading`, `error`, `totalCount`, `totalPages`, `page`, `setPage`, `sortKey`, `sortDir`, `setSort`, `search`, `setSearch`, `filters`, `setFilters`, `refresh`, and `tableProps` (ready to spread).
+
+---
+
 ## Hooks
 
 All hooks require a `PortalManager` ancestor.