Skip to main content
ReactZero · 2026engineering

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.

Open SourceDesign SystemAccessibilityTypeScript
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.

Selected JavaScript export versus all public JavaScript exports; package stylesheet shown separately.
Package / versionSelected JSAll exports JSStylesheet
@reactzero/combo0.1.15.30 kB7.52 kB2.95 kB
@reactzero/datepicker0.1.34.19 kB10.66 kB4.05 kB
@reactzero/flow0.1.01.94 kB9.89 kBNone
@reactzero/lattice0.1.05.07 kB7.34 kBNone
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.

useCombo — the prop-getter API
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>
  </>
);
The full ARIA 1.2 wiring — roles, aria-expanded, aria-activedescendant, live announcements — rides along inside the prop getters.

Accessibility deep-dive

  • ARIA 1.2: correct role="combobox" on the input, role="listbox" on the menu, automatic aria-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: finished promises always resolve, never reject. No try/catch needed. Every animation is interruptible.
useSequence — composed choreography
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 }),
]);
Two steps, one chain — Web Animations API on the compositor thread, zero React re-renders during playback.

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 state
  • reduce — faster, simpler version of the animation
  • crossfade — opacity-only transitions
  • respect — honor the OS prefers-reduced-motion setting

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.

Lattice — a row template, not a column config
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>
One <Grid.Row> template; the engine loops it over your data. Sorting is an opt-in plugin — leave it out and it never ships.

Plugin pipeline: pay for what you use

  • Base grid — see the versioned selected-export measurement above
  • Opt-in plugins — sortPlugin, filterPlugin, paginatePlugin are 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?

  1. Why zero dependencies?

    Smaller installs, no transitive vulnerability surface, no dependency conflicts, no abandoned upstream packages breaking my library.

  2. 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.

  3. 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.

  4. Why a state machine for combo?

    Complex interaction patterns are error-prone with ad-hoc state. A state machine makes transitions deterministic and testable.

  5. 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.

  6. 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.

Inspect the repository workflow snapshot

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 demo

How 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.

Other work

Explore more case studies