docs(react): rebuild the React docs around the plane hooks by pbroom · Pull Request #248 · pbroom/color-kit

pbroom · 2026-10-09T02:49:09Z

Stack Context

Second of three (#247 → #248 → #249). Sits on #247, which adds the hooks. The docs move off the components before #249 removes them, so each PR builds on its own.

What?

The React docs now build pickers from the hooks and plain elements.

examples/react/plane-picker.tsx exports a reusable PlanePicker:
- A <canvas> painted by useColorPlaneRenderer.
- An <svg viewBox="0 0 100 100"> overlay drawn through a render prop. The demo draws two useGamutBoundary edges.
- A role="slider" thumb. Pointer input goes through the driver's createPointerDragController with normalizeColorAreaPointer and colorFromColorAreaPosition. Keyboard and ARIA come from colorFromColorAreaKey and getColorAreaValueText.
- useAdaptiveQuality feeds the renderer and the overlays.
Other examples:
- contrast-region.tsx and color-provider.tsx (controlled) reuse PlanePicker.
- New channel-inputs.tsx (on the guide page) shows native range inputs with getSliderGradientStyles rails, and a text field built on the driver's string helpers.
- color-area.tsx, color-slider.tsx and color-string-input.tsx are removed.
Narrative pages:
- Rewrote /api/react and /guides/react.
- New symbol notes for useColorPlaneRenderer and useContrastRegion; the component notes are removed.
- Updated cross-references in the performance, contrast-palette and headless-picker guides, the plane intro, and the entry summaries.
- The callout names control-kit's Plane / Slider as an optional host, without depending on it.
API sidebar: the react domains are now Color / Plane renderer / Plane geometry / Performance.
Scripts: retargeted the drag profiling scripts to the hook-based example. They are now profile:plane-picker and test:plane-picker-drag, and use the [data-picker-area] / [data-picker-thumb] selectors.

Why?

The components go away in #249. The docs must show the supported way to build a picker: hooks for rendering and geometry, the driver for input math, and your own elements.

Validation

pnpm lint, pnpm build (including DTS and the docs bundle budget), pnpm test (core 921, driver 157, react 256, docs 949), pnpm format:check, pnpm agents:check:strict, pnpm check:preprod and pnpm --filter @color-kit/docs typecheck all pass.
Bundle budget: the channel-inputs example moved to the guide page so the /api/react chunk stays under the 200 kB budget. It is 187 kB.
Browser check: on a production build served with vite preview, /api/react and /guides/react render the canvas and the overlays.
- A pointer drag moves the thumb continuously (21 distinct positions over 21 frames).
- The arrow keys step the focused thumb, and the hue slider repaints the WebGL plane.
- The contrast fill stays on screen while dragging, and the text field commits and reverts as described.
- No console errors from real interaction.

🤖 Generated with Claude Code

vercel · 2026-10-09T02:49:15Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
color-kit	Ready	Preview	Oct 10, 2026 2:41am UTC

chatgpt-codex-connector · 2026-10-09T02:49:19Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-09T02:54:15.709777Z	`a1f8229`	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

pbroom · 2026-10-09T02:50:17Z

This stack of pull requests is managed by Graphite. Learn more about stacking.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a1f822941e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

greptile-apps · 2026-10-09T02:56:49Z

Confidence Score: 3/5

[Low impact] Rebuilds documentation and examples for React hooks.

Fix the picker's disabled-drag and multiple-pointer behavior before merging.

Findings

Disabled picker still changes ▶
Two fingers break dragging ▶
Keyboard changes look like clicks ▶
Docs promise missing paths ▶
Reversed axes give invalid bounds ▶

Summary

Rebuilds the React docs around state and plane hooks.

React docs build color planes from hooks and plain elements.
Native sliders and a text field edit colors in the React examples.
The contrast example draws passing colors over the picker.

The picker needs fixes for disabling during a drag and multiple pointers. Smaller issues affect input-source reporting, reversed-axis ARIA bounds, and the overview's return-shape description.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Input["Pointer or keyboard"] --> Driver["Driver helpers"]
  Driver --> Setter["Color setter"]
  Setter --> State["Requested color"]
  State --> Renderer["useColorPlaneRenderer"]
  Renderer --> Canvas["Canvas"]
  State --> Geometry["Geometry hooks"]
  Geometry --> SVG["SVG overlays"]
  State --> Thumb["Thumb position and value text"]

_{Reviews (1) · Last reviewed commit: "docs(react): rebuild the React docs arou..." · Reviewed by Greptile}

pbroom · 2026-10-10T18:47:23Z

Merge activity

Oct 10, 6:47 PM UTC: A user started a stack merge that includes this pull request via Graphite.
Oct 10, 8:38 PM UTC: Graphite rebased this pull request as part of a merge.
Oct 10, 8:39 PM UTC: @pbroom merged this pull request with Graphite.

…247) ## Stack Context First of three PRs that cut `color-kit/react` down to state utilities and performance primitives (#247 → #248 → #249). This one sits on #246 (`docs/syntax-colors`) and is additive: the new hooks land next to the existing components, which now delegate to them. ## What? New headless hooks. They own no DOM and take one plane, `ColorPlaneSpec = { color, axes? }`, where `axes` is the driver's `ColorAreaAxes`. - **`useColorPlaneRenderer(plane, options)`** is the `ColorPlane` rasterizer reshaped into a hook. - It keeps the WebGL path, the CPU fallback, the context-loss / restore handling and GPU cleanup on unmount. - It keeps the render-key dedupe (moving along an axis channel does not repaint), the DPR × `resolutionScale` × quality-scaled backing store, and rAF + `ResizeObserver` redraws. - It returns a stable callback `ref`, a `canvasKey` and the active `renderer`. The caller must use `canvasKey` as the canvas `key`: a canvas is locked to its first context kind, so the GPU ↔ CPU swap needs a fresh element. The hook warns once if the key is dropped. - **Geometry hooks** return memoized points plus `toSvgPath` / `toSvgCompoundPath` data for a `0 0 100 100` viewBox. They keep the layers' sync-at-rest / worker-while-dragging behaviour. - `useGamutBoundary` and `useChromaBand`. `useChromaBand` takes core's `ChromaBandMode`: `'clamped'` / `'proportional'`. - `useContrastRegion` returns `path` (contours) and `fillPath` (closed fill polygons). It keeps frozen drag sampling, the stable-fill fallback, the boundary snapping and closure, and `onMetrics`. Its non-rendering geometry moved out of `contrast-region-layer.tsx` into `contrast-region-geometry.ts`. - `useFallbackPoints` returns the sRGB and Display P3 fallback points. - **`useAdaptiveQuality(profile)`** is `ColorArea`'s frame-cost quality controller, extracted. - `ColorPlane` and `ColorArea` now run on `useColorPlaneRenderer` and `useAdaptiveQuality`, so the existing component tests cover the hooks too. - New tests: `use-color-plane-renderer.test.tsx` and `plane-geometry-hooks.test.tsx` (39 cases). They port the WebGL lifecycle, CPU fallback and edge-behaviour cases, and the contrast fill-side, APCA polarity, sampling and worker-metrics cases. - A changeset (`'color-kit': minor`) for the new hooks. ## Why? Approved API reduction: `color-kit/react` keeps state and perf primitives, and UI components go. Landing the hooks first keeps every step green and lets #249 delete the components without losing the renderer or the overlay math. ## Validation - `pnpm lint`, `pnpm build` (including DTS and the docs build), `pnpm test` (core 921, driver 157, react 256, docs 938), `pnpm format:check`, `pnpm agents:check:strict`, `pnpm check:preprod` and `pnpm --filter @color-kit/docs typecheck` all pass. - `eval-dependencies.test.ts` passes locally on macOS. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Rewrite the color-kit/react narrative, the React guide and the examples so they build pickers from the hooks and plain elements instead of the ColorArea/ColorSlider/ColorStringInput components: - plane-picker.tsx: a canvas painted by useColorPlaneRenderer, an SVG with useGamutBoundary overlays and a role="slider" thumb, with pointer input through the driver's createPointerDragController and keyboard/ARIA from colorFromColorAreaKey and getColorAreaValueText. useAdaptiveQuality feeds the renderer and overlays. - contrast-region.tsx and color-provider.tsx reuse PlanePicker; channel-inputs.tsx (in the guide) shows native range inputs and a text field built on the driver's string helpers. - New symbol notes for useColorPlaneRenderer and useContrastRegion; drop the component notes. Mention control-kit's Plane/Slider as an optional host. - Retarget the drag profiling scripts to the hook-based example (profile:plane-picker, test:plane-picker-drag) and update entry summaries and guide cross-references. Co-Authored-By: Claude Opus 5.5 <[email protected]>

- PlanePicker follows only the pointer that started the drag, so a second finger can neither restart, move nor end it. - Disabling it mid-drag cancels the drag controller and drops pending updates; commits are ignored while disabled. - The thumb is painted with the state's displayed color (new 'displayed' prop), so the sRGB preview applies to it too. - aria-valuemin/aria-valuemax use the smaller and larger end of the x range, so descending axes stay valid. - Native range inputs report interaction 'keyboard' for key changes and 'pointer' for drags instead of always 'pointer'. - The /api/react overview says which hooks return paths (boundary, band, contrast region), points (fallback points) or a canvas handle (renderer), and scopes 'renders no elements' to the hooks, not the whole package. Co-Authored-By: Claude Opus 5.5 <[email protected]>

The PlanePicker fixes pushed the /api/react page chunk past the docs bundle budget (202.6 kB of 200 kB). The controlled Color example now lives in the guide's Controlled section, and the API page links to it. Co-Authored-By: Claude Opus 5.5 <[email protected]>

vercel · 2026-10-10T20:37:45Z

Deployment failed for project color-kit with the following error:

Resource is limited - try again in 24 hours (more than 100, code: "api-deployments-free-per-day").

Learn More: https://vercel.com/pbrooms-projects?upgradeToPro=build-rate-limit

…ly (#249) ## Stack Context Third of three (#247 → #248 → #249). Sits on #248. The hooks (#247) and the docs (#248) are already in place, so this PR only removes code. ## What? `color-kit/react` now exports state hooks and plane hooks only. - **Removed outright (not moved to another package):** `ColorArea`, `Thumb`, `ColorPlane`, `OutOfGamutLayer`, `Layer`, `Background`, `Line`, `Point`, `GamutBoundaryLayer`, `ChromaBandLayer`, `ContrastRegionLayer` / `ContrastRegionFill`, `FallbackPointsLayer`, `ColorSlider`, `SliderMarker`, `ChromaMarkers`, `ColorStringInput` and `ColorInput`. Their props and metrics types, their tests, and the internal helpers only they used (`assign-ref`, `use-focus-visible`, `use-measured-element-size`) go too. - **Dependencies:** - Dropped the optional `@color-kit/control-kit` peer and dev dependency, the `./color-input` subpath and its tsup entry, and the `onlyBuiltDependencies` allowance. - Dropped the dev dependencies no longer used, `axe-core` and `@testing-library/user-event`. - The lockfile update is removals only: 75 packages, control-kit and its radix tree. - **Renames (hard cut-over):** - `ColorAreaPerformanceProfile` → `ColorPlanePerformanceProfile`; `ColorAreaQualityLevel` → `ColorPlaneQualityLevel`. - `ColorPlaneRenderer` loses the deprecated `'canvas2d'` alias. - The root re-exports only the driver types used by the remaining signatures. - **Facade:** `build.mjs` no longer excludes the color-input files. `check-artifacts.mjs` drops the color-input guard. `test-exports.mjs` asserts the hooks exist (ESM and CJS) and the removed components stay absent. - **Size limits:** new `.size-limit.json` budgets for `color-kit/react` imports: - `Color + useColor`: 19.1 kB, budget 20 kB. - `useColorPlaneRenderer`: 16.1 kB, budget 17 kB. - The geometry hooks: 38.1 kB, budget 40 kB. - **Benches:** `color-area-interaction-bench` becomes `plane-interaction-bench` (`bench:plane-interaction`); the README is updated. The renderer bench is unchanged. - **Docs and repo text:** - README, the facade README, DESIGN §4–§5 and §8, and the backlog: IB-012 is closed as superseded, and the open `ContrastRegionLayer` follow-up now points at `useContrastRegion`. - Wording in driver doc comments (no API change). - The docs config (`@color-kit/react/color-input` alias, stale domain aliases) and the declarations test now cover `Color`, the hooks and `ColorContext`. - **Changeset:** `'color-kit': minor`, written as a breaking change per the pre-1.0 convention, with migration notes. **Export count:** 105 root exports (24 values) plus the `color-input` subpath on the base, down to 60 (13 values). ## Why? Approved decision: `color-kit/react` keeps state utilities and performance primitives. Generic UI controls are not color-specific; apps compose the hooks with their own elements or with control-kit, which has no color math and no color-kit dependency. Pre-1.0, so this is a hard cut-over. ## Validation - `pnpm lint`, `pnpm build` (including DTS), `pnpm test` (core 921, driver 157, react 104, docs 906), `pnpm format:check`, `pnpm agents:check:strict`, `pnpm --filter @color-kit/docs typecheck`, `pnpm check:preprod`, `pnpm size` and `pnpm check:artifacts:metadata` (publint + attw) all pass. - The browser check from #248 was repeated on this branch's production build. The `/api/react` picker drags continuously, the arrow keys step it, and `/guides/react` works, with no console errors. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

chatgpt-codex-connector Bot reviewed Oct 9, 2026

View reviewed changes

vercel Bot deployed to Preview October 9, 2026 02:55

View deployment

greptile-apps Bot reviewed Oct 9, 2026

View reviewed changes

pbroom force-pushed the docs/react-hooks-guide branch from a1f8229 to 3fc7e3f Compare October 10, 2026 02:12

vercel Bot deployed to Preview October 10, 2026 02:15

View deployment

pbroom force-pushed the docs/react-hooks-guide branch from 3fc7e3f to f35e674 Compare October 10, 2026 02:39

pbroom force-pushed the feat/react-plane-hooks branch from 0552531 to c04b068 Compare October 10, 2026 02:39

vercel Bot deployed to Preview October 10, 2026 02:41

View deployment

pbroom changed the base branch from feat/react-plane-hooks to graphite-base/248 October 10, 2026 20:34

pbroom changed the base branch from graphite-base/248 to main October 10, 2026 20:36

pbroom and others added 3 commits October 10, 2026 20:37

pbroom force-pushed the docs/react-hooks-guide branch from f35e674 to 2b8114f Compare October 10, 2026 20:37

pbroom merged commit 9fabbd2 into main Oct 10, 2026
5 of 6 checks passed

pbroom deleted the docs/react-hooks-guide branch October 10, 2026 20:39

Navigation Menu

Repository navigation

docs(react): rebuild the React docs around the plane hooks - #248

docs(react): rebuild the React docs around the plane hooks#248
pbroom merged 3 commits into
mainfrom
docs/react-hooks-guide

pbroom commented Oct 9, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Oct 9, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot commented Oct 9, 2026 •

edited

Loading

Uh oh!

pbroom commented Oct 9, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot commented Oct 9, 2026 •

edited

Loading

Diagram

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pbroom commented Oct 10, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Oct 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

pbroom commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Stack Context

What?

Why?

Validation

Uh oh!

vercel Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex Review Summary

Uh oh!

pbroom commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 3/5

Findings

Summary

Diagram

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pbroom commented Oct 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

vercel Bot commented Oct 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

pbroom commented Oct 9, 2026 •

edited

Loading

vercel Bot commented Oct 9, 2026 •

edited

Loading

chatgpt-codex-connector Bot commented Oct 9, 2026 •

edited

Loading

pbroom commented Oct 9, 2026 •

edited

Loading

greptile-apps Bot commented Oct 9, 2026 •

edited

Loading

pbroom commented Oct 10, 2026 •

edited

Loading