feat(splitter): add resizable two-pane Splitter component

[misama-ct]

Summary

Adds Splitter to @commercetools/nimbus — a user-resizable two-pane layout (e.g. a sidebar next to a content area) built on the W3C window splitter pattern. It supports pointer and keyboard resizing, collapsible panes, per-pane minimum sizes, both orientations, and storage-agnostic layout persistence.

Motivation

We need a reusable, accessible primitive for resizable split layouts. The component is intentionally scoped to exactly two panes: a two-pane layout is a single boundary position (the second pane is always the complement of the first), which keeps the resize math and the accessibility contract simple and predictable. Layouts with three or more regions are composed by nesting a Splitter inside a Splitter.Pane.

API at a glance

<Splitter.Root
  defaultSizes={{ nav: 30, main: 70 }}   // single init path, full float precision
  onSizesChangeEnd={persist}             // settled value → persistence seam (no debounce)
  collapsedPane={collapsed}              // controlled collapse (one pane at a time)
  onCollapsedPaneChange={setCollapsed}
  panes={{ nav: { minSize: 10, collapsible: true }, main: { minSize: 20 } }}
  isDisabled={false}
>
  <Splitter.Pane id="nav">…</Splitter.Pane>
  <Splitter.Handle />
  <Splitter.Pane id="main">…</Splitter.Pane>
</Splitter.Root>

What changed

• Component — Splitter.Root / Splitter.Pane / Splitter.Handle compound component with id-keyed panes config (minSize, collapsible, collapsedSize), drag + keyboard resize, both orientations, a documented size variant, and an internationalized default handle label. Recipe + slots registered in the theme.
• Sizes are uncontrolled for drag performance: defaultSizes (read once, normalized, full float precision) + onSizesChange (live) + onSizesChangeEnd (fires once per settled interaction — the persistence seam).
• Collapse is controllable state, not an imperative API: collapsedPane / defaultCollapsedPane / onCollapsedPaneChange. A button anywhere in the app can collapse a pane with plain useState; Enter on the focused handle toggles it too.
• Persistence is consumer-wired with any storage (localStorage, cookies, server, …) — hydrate defaultSizes, write back on onSizesChangeEnd, persist collapse via its controlled state. No bespoke hook.
• isDisabled on Root makes the whole splitter non-interactive (handle out of tab order, aria-disabled).
• Single boundary model — one minSize per pane; the upper bound is derived (100 − partner.minSize), so there is no redundant maxSize. Double-click restores the mount-time sizes.
• Architecture — follows the Nimbus file-type guidelines: components/, hooks/, utils/ with barrels; a thin Splitter.Root delegating to useSplitterState; pure sizing helpers in utils/ with sibling unit specs.
• Docs & specs — OpenSpec proposal/design/spec, Storybook stories with play functions, and a11y / developer / consumer documentation.

How it works

The handle is built on react-aria primitives (useSeparator, useMove, useFocusRing) and exposes role="separator" with aria-orientation, aria-valuenow/min/max derived from per-pane minSize, aria-valuetext, and aria-controls. Sizes are percentages summing to 100 with full float precision preserved end-to-end (only aria-valuenow is rounded, for AT — layout is unaffected), so consumers can hit exact pixels at a known container width.

Note on the API

This branch underwent a pre-release coherence reshape (no consumers shipped). The earlier useSplitterLayout hook, per-pane maxSize/defaultSize/disabled, and the imperative __layoutRef wiring were removed in favor of the smaller, convention-aligned surface above. See the OpenSpec change "Revision" sections for the rationale.

Test plan

• Unit (JSDOM): sizing utilities + collapse-target selection + float-precision — 20 passing
• Storybook play functions: drag, keyboard (arrows / Home / End), Enter collapse, controlled collapse from an external button, persistence hydration, double-click restore (incl. a 0% default), isDisabled, nesting, float precision — 14 passing
• Consumer docs spec — 4 passing
• typecheck and lint clean; openspec validate passes

Screenshots / recordings

Closes FEC-977

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
nimbus-documentation	Ready	Preview, Comment	May 29, 2026 12:34pm
nimbus-storybook	Ready	Preview, Comment	May 29, 2026 12:34pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 28e89d7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@commercetools/nimbus	Minor
@commercetools/nimbus-tokens	Minor
@commercetools/nimbus-icons	Minor
@commercetools/nimbus-design-token-ts-plugin	Minor
@commercetools/nimbus-mcp	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Localization reminder: This PR adds or modifies `.i18n.ts` files.

Please create a Jira ticket for the localization manager to initiate translation of any new or updated strings in Transifex. See LOC-1766 as an example.

[github-actions]

Bundle Size Report

_{Last updated: 2026-05-29 12:33:57 UTC}

Package	Format	Current	Baseline	Delta	Status
@commercetools/nimbus	dist	15878.3 KB	15682.8 KB	+1.2%	✅ ok
@commercetools/nimbus-icons	dist	4787.6 KB	4787.6 KB	+0.0%	✅ ok
@commercetools/nimbus-tokens	dist	408.1 KB	408.1 KB	+0.0%	✅ ok

Baseline source: comment-chain