@w5-ui/react 0.2.1 → 0.5.0

package/src/components/FormRow.tsx

@@ -0,0 +1,19 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface FormRowProps extends HTMLAttributes<HTMLDivElement> {
+  children?: ReactNode
+}
+
+/**
+ * Two-column form grid: `1fr 1fr` with the canonical 14 px gap and 6 px top
+ * offset that every Settings card uses. Typed equivalent of
+ * `<div className="form-row">` from `@w5-ui/tokens/dashboard.css`. Use inside
+ * wider `<Card>` tiles for dense editors.
+ */
+export function FormRow({ className = '', children, ...rest }: FormRowProps) {
+  return (
+    <div className={`form-row ${className}`.trim()} {...rest}>
+      {children}
+    </div>
+  )
+}

package/src/components/Grid.tsx

@@ -0,0 +1,21 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface GridProps extends HTMLAttributes<HTMLDivElement> {
+  children?: ReactNode
+}
+
+/**
+ * The canonical 12-column page grid: `repeat(12, 1fr)` with a 12 px gap and
+ * `16px 24px` padding, reserving room for the bottom panel when present.
+ *
+ * Typed equivalent of `<div className="grid">` from `@w5-ui/tokens/dashboard.css`.
+ * Use as a direct child of the scrolling `.content` region; place `<Card>` /
+ * `<Stat>` tiles inside with `span={4 | 6 | 8 | 12}`.
+ */
+export function Grid({ className = '', children, ...rest }: GridProps) {
+  return (
+    <div className={`grid ${className}`.trim()} {...rest}>
+      {children}
+    </div>
+  )
+}

package/src/components/H1.tsx

@@ -0,0 +1,32 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface H1Props extends HTMLAttributes<HTMLHeadingElement> {
+  children?: ReactNode
+}
+
+/**
+ * Page title - the 38 px / bold / `--lh-snug` rhythm with
+ * `--tracking-display` (-0.02em) used for the top-of-page heading on
+ * marketing surfaces (login, onboarding splash, top-level landing).
+ * Renders `<h1 class="dash-ui-h1">` so the `.dash-ui-h1` rule in
+ * `@w5-ui/tokens/tokens.css` pins the canonical size, weight,
+ * line-height, letter-spacing, and `--text-1` colour. Stops userland
+ * reaching for a one-off `<h1 style={{ fontSize: 36 }}>` (or worse,
+ * leaving an unstyled browser default `<h1>` at 32 px / 700 / 1.2
+ * with no negative tracking, which is the documented "headings break
+ * awkwardly across two lines" drift fixed by `--tracking-display`).
+ *
+ * Typed equivalent of `<h1 className="dash-ui-h1">`. This is the
+ * userland-facing semantic class documented in **Foundations / Type**.
+ * Use `<H1>` for marketing-grade page titles. In-app pages should reach
+ * for `<PageHeader>` (which already styles the page title) and use
+ * `<H2>` for section heads, `<H3>` for sub-sections, `<H4>` for card
+ * titles.
+ */
+export function H1({ className = '', children, ...rest }: H1Props) {
+  return (
+    <h1 className={`dash-ui-h1 ${className}`.trim()} {...rest}>
+      {children}
+    </h1>
+  )
+}

package/src/components/H2.tsx

@@ -0,0 +1,32 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface H2Props extends HTMLAttributes<HTMLHeadingElement> {
+  children?: ReactNode
+}
+
+/**
+ * Page section heading - the 30 px / semibold / `--lh-snug` rhythm used
+ * for top-of-section labels on a dashboard page (above a grid of cards,
+ * above a table, above a settings group). Renders
+ * `<h2 class="dash-ui-h2">` so the `.dash-ui-h2` rule in
+ * `@w5-ui/tokens/tokens.css` pins the canonical size, weight,
+ * line-height, and `--text-1` colour. Stops userland reaching for a
+ * one-off `<h2 style={{ fontSize: 30, fontWeight: 600 }}>` (or worse,
+ * leaving an unstyled browser default `<h2>` at ~24 px with 700 weight
+ * and 1.2 line-height, which is the documented "section headings feel
+ * cramped on one line" drift).
+ *
+ * Typed equivalent of `<h2 className="dash-ui-h2">`. This is the
+ * userland-facing semantic class documented in **Foundations / Type**.
+ * Use `<H2>` for the page section head ("Devices", "Wi-Fi", "Settings")
+ * sitting above a content block. For card titles prefer `<H4>` (or just
+ * `<Card title="…">`, which injects `.dash-ui-h4` for you); for full
+ * page titles in marketing pages prefer `<H1>`.
+ */
+export function H2({ className = '', children, ...rest }: H2Props) {
+  return (
+    <h2 className={`dash-ui-h2 ${className}`.trim()} {...rest}>
+      {children}
+    </h2>
+  )
+}

package/src/components/H3.tsx

@@ -0,0 +1,32 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface H3Props extends HTMLAttributes<HTMLHeadingElement> {
+  children?: ReactNode
+}
+
+/**
+ * Sub-section heading - the 24 px / semibold / `--lh-snug` rhythm used
+ * for sub-section labels on a dashboard page (a heading inside a card
+ * region, a settings sub-group, a divider above a secondary table).
+ * Renders `<h3 class="dash-ui-h3">` so the `.dash-ui-h3` rule in
+ * `@w5-ui/tokens/tokens.css` pins the canonical size, weight,
+ * line-height, and `--text-1` colour. Stops userland reaching for a
+ * one-off `<h3 style={{ fontSize: 24, fontWeight: 600 }}>` (or worse,
+ * leaving an unstyled browser default `<h3>` at ~18.7 px with 700
+ * weight and 1.2 line-height, which is the documented "sub-section
+ * headings drift away from the reference" case).
+ *
+ * Typed equivalent of `<h3 className="dash-ui-h3">`. This is the
+ * userland-facing semantic class documented in **Foundations / Type**.
+ * Use `<H3>` for a sub-section head sitting below an `<H2>` page
+ * section head. For card titles prefer `<H4>` (or just
+ * `<Card title="…">`, which injects `.dash-ui-h4` for you); for page
+ * section heads prefer `<H2>`.
+ */
+export function H3({ className = '', children, ...rest }: H3Props) {
+  return (
+    <h3 className={`dash-ui-h3 ${className}`.trim()} {...rest}>
+      {children}
+    </h3>
+  )
+}

package/src/components/H4.tsx

@@ -0,0 +1,31 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface H4Props extends HTMLAttributes<HTMLHeadingElement> {
+  children?: ReactNode
+}
+
+/**
+ * Card / tile title - the 18 px / semibold / `--lh-snug` rhythm used
+ * for the heading that sits inside a card, a stat tile, or a settings
+ * sub-panel. Renders `<h4 class="dash-ui-h4">` so the `.dash-ui-h4`
+ * rule in `@w5-ui/tokens/tokens.css` pins the canonical size, weight,
+ * line-height, and `--text-1` colour. Stops userland reaching for a
+ * one-off `<h3 style={{ fontSize: 20 }}>` or `text-xl` (the documented
+ * "card title size doesn't match the reference" case), and stops them
+ * leaving an unstyled browser default `<h4>` at ~13.3 px / 700 / 1.2
+ * which reads as caption text instead of a title.
+ *
+ * Typed equivalent of `<h4 className="dash-ui-h4">`. This is the
+ * userland-facing semantic class documented in **Foundations / Type**.
+ * Use `<H4>` when you build a card-like tile by hand and need the
+ * canonical 18 / 600 title. If you reach for `<Card title="…">` you
+ * get the same class injected for you - prefer that. For page section
+ * heads prefer `<H2>`; for sub-section heads prefer `<H3>`.
+ */
+export function H4({ className = '', children, ...rest }: H4Props) {
+  return (
+    <h4 className={`dash-ui-h4 ${className}`.trim()} {...rest}>
+      {children}
+    </h4>
+  )
+}

package/src/components/Label.tsx

@@ -0,0 +1,30 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface LabelProps extends HTMLAttributes<HTMLSpanElement> {
+  children?: ReactNode
+}
+
+/**
+ * Small categorical label - the line above a KPI number ("Active devices"),
+ * the cell heading on a hand-rolled form row, the tag on a definition list
+ * term, anywhere a 13 px / medium-weight tag belongs without the full form
+ * field machinery. Renders `<span class="dash-ui-label">` so the
+ * `.dash-ui-label` rule in `@w5-ui/tokens/tokens.css` applies the canonical
+ * 13 px / 500 weight, 1.25 line-height, and `--text-2` colour. Stops
+ * userland reaching for a one-off `font-size: 13px; font-weight: 500;` duo
+ * on every KPI label or hand-rolled form caption.
+ *
+ * Typed equivalent of `<span className="dash-ui-label">`. This is the
+ * userland-facing semantic class documented in **Foundations / Type**.
+ * For real form fields prefer `<Field label="…">` - it wires `htmlFor`,
+ * required, hint, and error semantics for you. For KPI tiles prefer the
+ * `<Stat>` label slot. Reach for `<Label>` only when hand-rolling a tile
+ * or row where the higher-level component doesn't fit.
+ */
+export function Label({ className = '', children, ...rest }: LabelProps) {
+  return (
+    <span className={`dash-ui-label ${className}`.trim()} {...rest}>
+      {children}
+    </span>
+  )
+}

package/src/components/Mac.tsx

@@ -0,0 +1,25 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface MacProps extends HTMLAttributes<HTMLSpanElement> {
+  children?: ReactNode
+}
+
+/**
+ * Inline monospace label for MAC addresses, IPs, SKUs, serial numbers and
+ * other fixed-width identifiers that read inside a table cell or a property
+ * row. Renders a `<span class="mac">` so the `.mac` rule in
+ * `@w5-ui/tokens/dashboard.css` applies the canonical JetBrains Mono family,
+ * 12 px size, and muted colour. Stops userland reaching for inline
+ * `font-family` / `font-size` overrides on bare identifiers.
+ *
+ * Typed equivalent of `<span className="mac">` (and `<td className="mac">`
+ * inside a table — apply the class directly to the `<td>` there, or wrap the
+ * cell contents with `<Mac>` when the cell carries other markup too).
+ */
+export function Mac({ className = '', children, ...rest }: MacProps) {
+  return (
+    <span className={`mac ${className}`.trim()} {...rest}>
+      {children}
+    </span>
+  )
+}

package/src/components/Modal.tsx

@@ -2,18 +2,32 @@ import { useEffect, useId, useRef, type ReactNode } from 'react'
 import { CloseIcon } from '../icons.js'
 import { IconButton } from './Button.js'
 
+export type ModalSize = 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+
 export interface ModalProps {
   open: boolean
   title: string
+  /** Panel width. `md` (520px) is the default; larger sizes suit
+   *  data-dense or editor-style dialogs. Always capped at 90vw. */
+  size?: ModalSize
   onClose: () => void
   children?: ReactNode
   footer?: ReactNode
 }
 
+/** Width modifier appended to `.modal`; `md` is the base rule. */
+const MODAL_SIZE: Record<ModalSize, string> = {
+  sm: 'modal--sm',
+  md: '',
+  lg: 'modal--lg',
+  xl: 'modal--xl',
+  '2xl': 'modal--2xl',
+}
+
 const FOCUSABLE =
   'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])'
 
-export function Modal({ open, title, onClose, children, footer }: ModalProps) {
+export function Modal({ open, title, size = 'md', onClose, children, footer }: ModalProps) {
   const titleId = useId()
   const modalRef = useRef<HTMLDivElement>(null)
   const downOnBackdropRef = useRef(false)
@@ -67,7 +81,7 @@ export function Modal({ open, title, onClose, children, footer }: ModalProps) {
     >
       <div
         ref={modalRef}
-        className="modal"
+        className={`modal ${MODAL_SIZE[size]}`.trim()}
         role="dialog"
         aria-modal="true"
         aria-labelledby={titleId}

package/src/components/Mono.tsx

@@ -0,0 +1,31 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface MonoProps extends HTMLAttributes<HTMLSpanElement> {
+  children?: ReactNode
+}
+
+/**
+ * Inline monospace identifier for MAC addresses, IPs, hex IDs, ports,
+ * firmware versions, config keys, and other machine-shaped values that
+ * read inside body copy or a property row. Renders a
+ * `<span class="dash-ui-mono">` so the `.dash-ui-mono` rule in
+ * `@w5-ui/tokens/tokens.css` applies the canonical JetBrains Mono family,
+ * 13 px size, regular weight, 1.4 line-height, and `--text-2` colour. The
+ * class also enables `font-variant-numeric: tabular-nums` so a column of
+ * MACs / IPs / versions aligns vertically. Stops userland reaching for
+ * bare `font-family: monospace` (which falls back to a serif Courier with
+ * proportional digits) or one-off `font-size` overrides on identifiers.
+ *
+ * Typed equivalent of `<span className="dash-ui-mono">`. This is the
+ * userland-facing semantic class documented in **Foundations / Type**.
+ * Prefer `<Mono>` for new userland code. Reach for `<Mac>` only when you
+ * need the dashboard's denser 12 px `.mac` variant (table cells in the
+ * reference Devices / Clients pages).
+ */
+export function Mono({ className = '', children, ...rest }: MonoProps) {
+  return (
+    <span className={`dash-ui-mono ${className}`.trim()} {...rest}>
+      {children}
+    </span>
+  )
+}

package/src/components/Muted.tsx

@@ -0,0 +1,27 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface MutedProps extends HTMLAttributes<HTMLSpanElement> {
+  children?: ReactNode
+}
+
+/**
+ * Inline span that drops a phrase to the tertiary text colour
+ * (`--text-3`). Renders `<span class="t-muted">` so the `.t-muted` rule in
+ * `@w5-ui/tokens/dashboard.css` applies the canonical muted colour used by
+ * `.submeta`, `.stat .unit` and the `.card h3` title chrome. Use for
+ * "X active" counters next to an icon, caption-style metadata sitting
+ * beside a primary label, or any sub-line that would otherwise tempt
+ * userland to reach for a one-off `color: #...` override.
+ *
+ * Typed equivalent of `<span className="t-muted">`. The contrast pair is
+ * AA against every motif background (verified for `--text-3` over
+ * `--depthBg-0`/`--depthBg-1`/`--depthBg-2` in both dark and light
+ * motifs).
+ */
+export function Muted({ className = '', children, ...rest }: MutedProps) {
+  return (
+    <span className={`t-muted ${className}`.trim()} {...rest}>
+      {children}
+    </span>
+  )
+}

package/src/components/NameCell.tsx

@@ -0,0 +1,45 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface NameCellProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Square 28 px avatar / initial that sits to the left of the name. Pass a
+   * letter (`r[0]`), an emoji, or a small SVG. Rendered inside a
+   * `<span class="nc-thumb">` so the canonical thumbnail rule applies.
+   * Omit if the row has no leading affordance.
+   */
+  thumb?: ReactNode
+  /**
+   * Extra `className` for the inner `.nc-thumb` (e.g. `'cam'` for the
+   * camera gradient variant). Ignored when `thumb` is not supplied.
+   */
+  thumbClassName?: string
+  children?: ReactNode
+}
+
+/**
+ * First-column row in a list / table: a 28 px square thumbnail or initial
+ * followed by the device / client / alert name. Renders the canonical
+ * `<div class="name-cell"><span class="nc-thumb">…</span>…</div>` markup so
+ * the `.name-cell` and `.nc-thumb` rules from `@w5-ui/tokens/dashboard.css`
+ * apply (28 px thumb, 10 px gap, white name colour, JetBrains Mono initial).
+ * Stops userland reaching for ad-hoc flex / padding / colour overrides on the
+ * first column.
+ *
+ * Typed equivalent of the manual `<div className="name-cell"><span
+ * className="nc-thumb">{x}</span>{name}</div>` pattern used across the
+ * Dashboard, Devices, Wi-Fi, and Alarms reference pages.
+ */
+export function NameCell({
+  className = '',
+  thumb,
+  thumbClassName = '',
+  children,
+  ...rest
+}: NameCellProps) {
+  return (
+    <div className={`name-cell ${className}`.trim()} {...rest}>
+      {thumb !== undefined && <span className={`nc-thumb ${thumbClassName}`.trim()}>{thumb}</span>}
+      {children}
+    </div>
+  )
+}

package/src/components/NotifDot.tsx

@@ -0,0 +1,24 @@
+import type { HTMLAttributes } from 'react'
+
+export interface NotifDotProps extends HTMLAttributes<HTMLSpanElement> {}
+
+/**
+ * Tiny red dot that sits on top of a bell / mail / inbox icon to flag unread
+ * activity. Renders `<span aria-hidden class="topbar-notif-dot">` so the
+ * `.topbar-notif-dot` rule in `@w5-ui/tokens/dashboard.css` paints the canonical
+ * 6 px circle with the danger colour and a neutral-10 ring (the ring is what
+ * keeps the dot legible over the deep topbar background).
+ *
+ * The dot is presentational — wrap your bell `<IconButton>` and put the live
+ * count in its `aria-label` (e.g. `aria-label="Notifications, 3 new"`) so
+ * screen readers announce the number while sighted users see the indicator.
+ * The hosting button must be `position: relative` for the dot to anchor in the
+ * top-right corner.
+ *
+ * Typed equivalent of `<span aria-hidden className="topbar-notif-dot" />`.
+ * Use when userland slots a custom `<Topbar actions>` block and needs to keep
+ * the unread indicator wired up without copying the class name.
+ */
+export function NotifDot({ className = '', ...rest }: NotifDotProps) {
+  return <span aria-hidden="true" className={`topbar-notif-dot ${className}`.trim()} {...rest} />
+}

package/src/components/PageHeader.tsx

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react'
+
+export interface PageHeaderProps {
+  title: ReactNode
+  actions?: ReactNode
+  sticky?: boolean
+  className?: string
+}
+
+export function PageHeader({ title, actions, sticky = true, className = '' }: PageHeaderProps) {
+  return (
+    <div
+      className={`ph-bar ${className}`.trim()}
+      style={sticky ? undefined : { position: 'static' }}
+    >
+      <h2 className="ph-title">{title}</h2>
+      {actions && <div className="ph-actions">{actions}</div>}
+    </div>
+  )
+}

package/src/components/SrOnly.tsx

@@ -0,0 +1,25 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface SrOnlyProps extends HTMLAttributes<HTMLSpanElement> {
+  children?: ReactNode
+}
+
+/**
+ * Visually-hidden text that stays available to assistive tech. Renders a
+ * `<span class="sr-only">` so the `.sr-only` rule in
+ * `@w5-ui/tokens/dashboard.css` clips it from the visual layout while keeping
+ * it announceable by screen readers. Use it to name regions that the design
+ * intentionally leaves unlabelled, the way the reference Tables recipe wires
+ * `<caption className="sr-only">` onto every `<table>` (WCAG 1.3.1).
+ *
+ * Typed equivalent of `<span className="sr-only">`. Apply the class directly
+ * to a `<caption>` / `<label>` when the whole element is the hidden text, or
+ * wrap an inline phrase with `<SrOnly>` when it sits alongside visible markup.
+ */
+export function SrOnly({ className = '', children, ...rest }: SrOnlyProps) {
+  return (
+    <span className={`sr-only ${className}`.trim()} {...rest}>
+      {children}
+    </span>
+  )
+}

package/src/components/StatNumber.tsx

@@ -0,0 +1,25 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface StatNumberProps extends HTMLAttributes<HTMLDivElement> {
+  children?: ReactNode
+}
+
+/**
+ * Hero-number row inside a `<Card>`: the big tabular-nums value (optionally
+ * followed by a trailing `<Unit>`). Renders a `<div class="stat">` so the
+ * `.stat` rule in `@w5-ui/tokens/dashboard.css` sets the canonical 30 px size,
+ * semibold weight, tabular figures, and primary text colour. Stops userland
+ * reaching for inline `font-size` / `font-weight` overrides on bare numbers.
+ *
+ * Typed equivalent of `<div className="stat">`; pair with `<Unit>` for the
+ * suffix label, and `<Submeta>` for the muted line underneath. `<Stat>`
+ * already wires all three internally — reach for `<StatNumber>` when you
+ * compose `.stat` by hand (e.g. number above a chart inside a `<Card>`).
+ */
+export function StatNumber({ className = '', children, ...rest }: StatNumberProps) {
+  return (
+    <div className={`stat ${className}`.trim()} {...rest}>
+      {children}
+    </div>
+  )
+}

package/src/components/StatusRing.tsx

@@ -0,0 +1,38 @@
+import type { HTMLAttributes } from 'react'
+
+export type StatusRingStatus = 'ok' | 'warn' | 'danger' | 'neutral'
+
+export interface StatusRingProps extends HTMLAttributes<HTMLSpanElement> {
+  /** Health colour of the ring. Defaults to `'ok'` (success green). */
+  status?: StatusRingStatus
+}
+
+const MODIFIER: Record<StatusRingStatus, string> = {
+  ok: '',
+  warn: 'status-ring--warn',
+  danger: 'status-ring--danger',
+  neutral: 'status-ring--neutral',
+}
+
+/**
+ * Pulsing status indicator: a soft translucent ring around a solid coloured
+ * inner dot. Renders `<span aria-hidden class="status-ring">` so the
+ * `.status-ring` rule in `@w5-ui/tokens/dashboard.css` paints the canonical
+ * 18 px ring + 8 px inner dot without userland having to hand-roll the two
+ * layers.
+ *
+ * The `status` prop swaps the ring + dot colour: `'ok'` (default, success
+ * green), `'warn'` (amber), `'danger'` (red), `'neutral'` (grey). Use it to
+ * drive a live-health signal next to the site name in `<Topbar>` or on a
+ * tunnel / session / device row.
+ *
+ * Decorative — the wrapper sets `aria-hidden`; pair with a label so screen
+ * readers announce the state. Typed equivalent of
+ * `<span aria-hidden className="status-ring status-ring--<status>" />`. Stops
+ * userland copying the class name into bespoke status rows and silently
+ * drifting when the ring colour / size tokens change.
+ */
+export function StatusRing({ className = '', status = 'ok', ...rest }: StatusRingProps) {
+  const cls = ['status-ring', MODIFIER[status], className].filter(Boolean).join(' ')
+  return <span aria-hidden="true" className={cls} {...rest} />
+}

package/src/components/Submeta.tsx

@@ -0,0 +1,23 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface SubmetaProps extends HTMLAttributes<HTMLDivElement> {
+  children?: ReactNode
+}
+
+/**
+ * Secondary one-line caption inside a `<Card>` tile: the muted row that sits
+ * under the headline `.stat` number and carries supporting metrics, deltas, or
+ * status. Carries the canonical 12 px font size, `--text-2` colour, and the
+ * `↑` / `↓` separator rhythm the Dashboard reference tiles use.
+ *
+ * Typed equivalent of `<div className="submeta">` from
+ * `@w5-ui/tokens/dashboard.css`. Pair with `.delta-up` / `.delta-down` spans
+ * for trend text so screen readers announce the direction.
+ */
+export function Submeta({ className = '', children, ...rest }: SubmetaProps) {
+  return (
+    <div className={`submeta ${className}`.trim()} {...rest}>
+      {children}
+    </div>
+  )
+}

package/src/components/TablePager.tsx

@@ -0,0 +1,27 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface TablePagerProps extends HTMLAttributes<HTMLDivElement> {
+  children?: ReactNode
+}
+
+/**
+ * Sibling row that sits directly under a `<TableShell>` (or
+ * `<div className="table-shell">`) and carries the rows-per-page control on
+ * the left and the `<Pagination>` nav on the right. Renders the canonical
+ * `<div class="table-pager">` markup so the flex / space-between / 12 px top
+ * margin from `@w5-ui/tokens/dashboard.css` applies and userland drops the
+ * inline `style={{ display: 'flex', justifyContent: 'space-between', … }}`
+ * wrapper that every reference page used to ship.
+ *
+ * Typed equivalent of the manual `<div className="table-pager">` pattern
+ * documented in **Foundations / Tables**. Render it as a sibling of
+ * `<TableShell>` — never inside it — so the focus rings on the pager buttons
+ * are not clipped by `overflow: hidden`.
+ */
+export function TablePager({ className = '', children, ...rest }: TablePagerProps) {
+  return (
+    <div className={`table-pager ${className}`.trim()} {...rest}>
+      {children}
+    </div>
+  )
+}

package/src/components/TableShell.tsx

@@ -0,0 +1,23 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+export interface TableShellProps extends HTMLAttributes<HTMLDivElement> {
+  children?: ReactNode
+}
+
+/**
+ * Rounded, bordered wrapper for any full-width `<table>` on a page. Carries the
+ * 8 px radius, `--neutral-09` background, single 1 px border and `overflow:
+ * hidden` clip so userland tables read like the reference Devices / Clients
+ * pages without inline `border` / `borderRadius` styles.
+ *
+ * Typed equivalent of `<div className="table-shell">` from
+ * `@w5-ui/tokens/dashboard.css`. Render the `<Pagination>` row as a sibling
+ * below, not inside, so its focus rings aren't clipped.
+ */
+export function TableShell({ className = '', children, ...rest }: TableShellProps) {
+  return (
+    <div className={`table-shell ${className}`.trim()} {...rest}>
+      {children}
+    </div>
+  )
+}