React Components, From API to Interaction
Four published React packages for comboboxes, dates, motion, and data grids. Explore the API decisions, a working example, and reproducible bundle measurements.
- The problem
- Make component behavior and integration cost explicit.
- My contribution
- Library API design, interaction models, TypeScript implementation, and documentation.
- A key decision
- Offer a headless path and small feature boundaries while owning the maintenance tradeoffs.
Current evidence: 4 published packages with no declared runtime dependencies; React is a peer. Size and verification scope are documented per release.
Measured package cost
Released versions · 2026-11-09 · decimal kB, gzip. React and ReactDOM are external. CSS is compressed separately.
| Package / version | Selected JS | All exports JS | Stylesheet |
|---|---|---|---|
| @reactzero/combo0.1.1 | 5.30 kB | 7.52 kB | 2.95 kB |
| @reactzero/datepicker0.1.3 | 4.19 kB | 10.66 kB | 4.05 kB |
| @reactzero/flow0.1.0 | 1.94 kB | 9.89 kB | None |
| @reactzero/lattice0.1.0 | 5.07 kB | 7.34 kB | None |
Method, imports, and verification scope
esbuild bundle + minification, ESM, browser, ES2020; React/ReactDOM external. Gzip JS and CSS separately. Public exports preserve all exported APIs; selected-export preserves the named export. CSS includes the package stylesheet when supplied. Not an application bundle benchmark.
export { useCombo } from '@reactzero/combo/hook';export { DatePicker } from '@reactzero/datepicker';export { useTimeline } from '@reactzero/flow';export { Grid } from '@reactzero/lattice';
The selected headless Combo export can be styled without the supplied stylesheet. These measurements preserve exported APIs; they are not a complete application bundle or a claim that every integration has this cost.
Measurement data · Reproduction script · Portfolio verification scope
The problem
Control over APIs, interactions, and integration cost
I built four React packages to explore a specific set of constraints: direct component APIs, explicit interaction behavior, and no additional runtime dependencies beyond React peers.
Each package explores a different boundary: animation orchestration with browser APIs, date interfaces using native internationalization, a combobox with a headless integration path, and a grid composed from cells. Established libraries remain useful choices; these projects let me own the behavior and understand its maintenance costs.
ReactZero emerged from a single philosophy: zero dependencies, accessibility-first, headless + styled, small bundles. Four libraries, all on npm.
Design philosophy — the zero principles
Zero runtime dependencies
Native browser APIs only — Web Animations API, Intl, DOM positioning. No date-fns, Floating UI, or lodash.
Accessibility is default
WCAG baked into the architecture, not bolted on. Keyboard nav, ARIA roles, focus management, live regions.
Headless + styled dual API
Use the headless hook for full control, or the pre-built component for quick wins. Developers pick their abstraction.
CSS custom properties for theming
No CSS-in-JS runtime. Pure CSS variables cascading naturally, overridable at any scope.
Tree-shakeable entry points
Import only what you use. Combo ships 7 separate entry points. Dead code elimination built in.
AI-readable
Each library ships an `ai-reference.md` so AI coding assistants can work with the components accurately.
@reactzero/combo — the accessible combobox
Comboboxes are one of the most complex ARIA patterns: text input, listbox, keyboard nav, focus management, and live-region announcements all in one component. ARIA 1.2 changed the pattern significantly, and most libraries still haven't caught up.
Architecture: state machine + prop getters
The core of combo is a pure reducer in core/stateMachine.ts: no side effects, deterministic transitions, testable in isolation. On top of that, useCombo returns prop getters (getInputProps, getMenuProps, getItemProps) that spread ARIA attributes automatically. You cannot forget aria-expanded. It's physically impossible to drop it.
const {
isOpen, filteredItems, highlightedIndex,
getLabelProps, getInputProps, getMenuProps, getItemProps,
} = useCombo({ items });
return (
<>
<label {...getLabelProps()}>Fruit</label>
<input {...getInputProps({ placeholder: 'Search…' })} />
<ul {...getMenuProps()}>
{isOpen &&
filteredItems.map((item, index) => (
<li key={index} {...getItemProps({ item, index })}>
{String(item)}
</li>
))}
</ul>
</>
);Accessibility deep-dive
- ARIA 1.2: correct
role="combobox"on the input,role="listbox"on the menu, automaticaria-expanded,aria-activedescendant,aria-selected,aria-disabled - Live region: announces selection changes and filtered result counts to screen readers
- 12+ keybindings: ArrowDown/Up, Enter, Escape, Home/End, PageDown/PageUp, Tab, Backspace for chip removal, Space for the select variant
- Focus management: focus returns to the input on menu close; active descendant highlighting without moving DOM focus
- High-contrast theme: a stronger-contrast appearance shipped alongside default and dark
Theming system
Combo exposes 40+ CSS custom properties organized by scope: input, popover, items, labels, errors, icons, chips, checkboxes, radios, groups, footer, tabs, custom items. Three built-in themes (default, dark, high-contrast), plus theme="system" for OS dark-mode auto-detection. The CSS variables are the design tokens, flowing from theme → component → element.
@reactzero/datepicker — the design system showcase
The datepicker is a mini design system: 7 components (DatePicker, TimePicker, DateRangePicker, DateTimePicker, CalendarGrid, FieldWrapper, TimeInput) and 4 headless hooks. Components build on each other, share tokens, and expose both styled and headless APIs.
Tokens and theming in practice
- 10 built-in themes: light, dark, minimal, ocean, rose, purple, amber, slate, glass, and high-contrast
- 3 density modes: compact, comfortable, default
- 5 trigger styles: default, icon, minimal, pill, ghost
- CSS custom properties:
--dp-accent,--dp-bg,--dp-text,--dp-cell-size
This is the most tangible design tokens in practice artifact in the portfolio.
Internationalization via native APIs
The datepicker uses Intl.DateTimeFormat and Date. No date-fns, no moment.js. Locale-aware formatting, RTL support, configurable first day of week. Why add 30 kB of date library when the browser already speaks every language?
Developer experience pipeline
- Storybook: interactive component documentation, published on Chromatic
- size-limit: declared package budgets per entry point
- CI: the Datepicker workflow runs typecheck, lint, tests, and an accessibility suite
@reactzero/flow — motion as a system
Flow is an animation library with one specific constraint: zero React re-renders. All animations run on the browser's compositor thread via the Web Animations API. The React layer is a thin hook surface that never touches state during playback.
Composition API
- Primitives:
animate(),delay(),sequence(),parallel(),stagger(),timeline() - Operators:
race(),repeat(),timeout()— composition over configuration - True cancellation:
finishedpromises always resolve, never reject. No try/catch needed. Every animation is interruptible.
import { useSequence, animate } from '@reactzero/flow';
const { play, state } = useSequence([
() => animate(box.current!, [{ opacity: 0 }, { opacity: 1 }], { duration: 300 }),
() => animate(box.current!, [{ transform: 'scale(0.8)' }, { transform: 'scale(1)' }], { duration: 200 }),
]);Reduced motion as first-class
Most animation libraries give you a boolean toggle for reduced motion. Flow gives you four policies via <ReducedMotionProvider>:
skip— instant jump to end statereduce— faster, simpler version of the animationcrossfade— opacity-only transitionsrespect— honor the OSprefers-reduced-motionsetting
Accessibility isn't only about screen readers. Motion sensitivity affects real users, and they deserve more than an on/off switch.
Adaptive performance
enableAdaptivePerformance() does runtime device tier detection and FPS monitoring. Animations are tagged by priority (critical, normal, decorative), and under frame pressure the system degrades gracefully: decorative animations skip entirely, normal animations speed up, critical animations stay at full fidelity. I haven't seen another animation library do runtime adaptive degradation.
@reactzero/lattice — the cell-first data grid
Every other React table library makes you define columns as a config object: a list of { accessorKey, header, cell } entries. That was the wrong default. In JSX, tables want to be declared the way they render: a row template, cells as children, the engine loops it over your data. Lattice is that. It's also the most direct product of my history with data-dense B2B tools — the dispatcher dashboards and financial documents elsewhere in this portfolio are exactly the surfaces a grid like this exists to serve.
Architecture: JSX shape, not config objects
The core primitives are <Grid>, <Row>, and <Cell columnKey="field">. You write one <Row> template and the engine renders it per record. Cells read their value from row context, so they work at any nesting depth (inside divs, conditionals, layout wrappers). No cloneElement, no column-config arrays, no render-prop gymnastics. The typed GridInstance<TData> means columnKey autocompletes to your actual data keys and errors on typos.
import { Grid } from '@reactzero/lattice/react';
import { sortPlugin } from '@reactzero/lattice/sort';
<Grid data={rows} plugins={[sortPlugin()]}>
<Grid.Header>
<Grid.HeaderCell columnKey="name">Name</Grid.HeaderCell>
<Grid.HeaderCell columnKey="role">Role</Grid.HeaderCell>
</Grid.Header>
<Grid.Body>
<Grid.Row>
<Grid.Cell columnKey="name" />
<Grid.Cell columnKey="role" />
</Grid.Row>
</Grid.Body>
</Grid>Plugin pipeline: pay for what you use
- Base grid — see the versioned selected-export measurement above
- Opt-in plugins —
sortPlugin,filterPlugin,paginatePluginare separate subpath exports. Import only what the table needs; the others are tree-shaken out. - Ordered pipeline — plugins compose as
sort → filter → paginate, each with its own typed API (toggleSort,setFilter,goToPage). Order determines behavior; the pipeline is explicit. - Zero dependencies — core engine is pure TypeScript. React 18+ is the only peer.
Styling via data attributes
No className merging, no CSS-in-JS runtime. Lattice exposes state through data-* attributes: data-lattice-row, data-lattice-cell, data-sorted-direction="asc", data-pinned="left". Style them with plain CSS. Same philosophy as the rest of ReactZero — the browser already has a selector engine. Don't ship another one.
Engineering decisions — why zero dependencies?
Why zero dependencies?
Smaller installs, no transitive vulnerability surface, no dependency conflicts, no abandoned upstream packages breaking my library.
Why Web Animations API over Framer Motion?
Compositor thread = no React re-renders = no jank. WAAPI is a web standard, not a library API that can break.
Why build positioning instead of using Floating UI?
One less dependency. Flip and shift logic is simple — it does not need a 15 kB library.
Why a state machine for combo?
Complex interaction patterns are error-prone with ad-hoc state. A state machine makes transitions deterministic and testable.
Why ARIA 1.2, not 1.1?
ARIA 1.2 changed the combobox pattern significantly. Implementing the old pattern means shipping incorrect accessibility. Better to be correct from the start.
Why `ai-reference.md`?
AI coding assistants are part of the workflow now. Making a library machine-readable is an adoption accelerator — AI-native developer experience.
Dead ends worth keeping
The "why" list above reads cleaner than the road to it. These are the versions that lost:
A headless API that didn't survive composition
Combo's first hook design worked for simple cases and collapsed when consumers needed to combine behaviors on one element. The prop-getter API is the rewrite that survived.
Everything in the core
Lattice's earliest design pulled sorting, filtering, and pagination into the engine — and the bundle cost made "tiny" a lie for anyone who wanted a read-only grid. Opt-in plugins keep feature cost explicit for integrations that only need a base grid.
A single reduced-motion kill switch
The obvious first answer — skip all animation when the OS flag is set — silently breaks UI that uses motion to convey state. That is why flow treats reduced motion as a per-animation policy (skip / reduce / crossfade / respect), not a global boolean.
Ten themes to prove a point
Datepicker's theme count shows the token system off, but the long tail costs more in visual-regression upkeep than it returns. Today I'd ship four themes and a theming guide.
Links and artifacts
Evidence scope: Datepicker and Flow run test and quality gates in CI; Combo and Lattice currently run build and deploy workflows. The snapshot below records the public workflow definitions and recent runs as of the review date. The portfolio’s own tests and package measurements are reported separately.
Release-specific measurements are shown at the top of this study. The fixture separates selected exports, the full public export surface, and CSS, with React externalized.
@reactzero/combo
npm — @reactzero/comboGitHubLive demo@reactzero/datepicker
npm — @reactzero/datepickerGitHubLive demoPublished Storybook@reactzero/flow
npm — @reactzero/flowGitHubLive demo@reactzero/lattice
npm — @reactzero/latticeGitHubLive demoHow AI accelerated this project
The ReactZero libraries were built with AI-assisted development throughout — and they also ship a feature designed for AI: the ai-reference.md pattern.
ai-reference.md — AI-native developer experience
Each library ships an `ai-reference.md` — structured documentation written for AI coding assistants. When a developer uses Claude Code, Copilot, or Cursor to integrate a ReactZero component, the AI has a reliable reference to generate correct, accessible code. This is what AI-native developer experience looks like in practice.
State machine scaffolding
I used Claude Code to scaffold the combo state machine, then manually verified every ARIA attribute against the WAI-ARIA 1.2 specification. The machine runs correctly; accessibility correctness required human verification against the spec.
Bundle optimization strategy
AI assistance surfaced tree-shakeable entry points and subpath export patterns early in the architecture. Flow’s reviewed CI includes size-limit checks. Automation varies by package; the published measurement fixture makes the portfolio’s size claims independently reproducible.
Manual accessibility verification
Keyboard navigation, announcements, and focus management are checked against the implemented interaction: automated browser checks in this portfolio plus the repository tests. Screen-reader passes remain a manual step.
Tools: Claude Code · Codex · GitHub Copilot · Cursor — the full workflow, with the delegation boundaries spelled out, is documented at How I build with AI.
Explore more case studies
Independent · Primer ReactAgent Review Desk
An independent Primer React prototype for inspecting agent work, resolving a scoped permission request, and recovering from failure. Try the complete simulated workflow.
Primer React · Interactive prototype
Waco3.ioAI Client Workspace
A working client workspace for documents, signatures, intake, trackers, and pipeline—with AI inside the workflow. Built end to end and still evolving.
Live product · Ongoing development
Dispatcher Dashboard Redesign
Reorganized a dense logistics dashboard around how dispatchers scan lanes, statuses, and actions. Workflow research informed a responsive card-based layout.
Workflow research · Interface design