@capillaryjs/capillary-ui 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -6,8 +6,115 @@ Versioning.
 
 ## Unreleased
 
+## 1.4.0 - 2026-09-19
+
+### Fixed
+
+- Keep DataTable header borders and column dividers visible while rows scroll,
+  and use the theme's table-header background and text tokens consistently.
+- Show both sort directions on unsorted table columns and render a
+  font-independent filter funnel that remains legible at compact header sizes.
+- Apply the Capillary theme's alternating table-row colors through the tokens
+  consumed by table rows.
+
+### Changed
+
+- Correct the changelog's package/version boundaries: distinguish historical
+  Fray releases and identify notes already shipped in Capillary UI 1.3.0.
+
+## 1.3.0 - 2026-09-18
+
+Historical correction: the following notes were shipped under `Unreleased` in
+the published 1.3.0 package. They include changes introduced in earlier
+Capillary UI releases; they are retained here as the shipped record, not as
+new changes in the next release.
+
+### Fixed
+
+- Set the default GroupBox content gap independently from island spacing, using
+  a compact 2px rhythm for controls inside a GroupBox.
+
+- Render unfilled required controls with a transparent negative ✲ marker:
+  inside native input surfaces and beside a pseudo-element checkable outline
+  extension that does not change the label's layout width.
+- Place checkbox and radio validation halos around the complete labelled
+  choice while retaining the error border on the painted shell.
+- Keep busy buttons visually normal and layer only the working animation over
+  their ordinary chrome. Gate ProgressBar's busy animation on an emitter-backed
+  `FetchState.Loading` state, applying the working texture to both determinate
+  and indeterminate bars so literal indeterminate values remain static.
+- Make ProgressBar fill its available inline width while remaining shrinkable
+  inside constrained layouts.
+- Omit island content padding on direct app-root headers, letting their navbar
+  and toolbar own spacing. Preserve nested headers, other islands, outer
+  gutters, borders, and shadows across themes and managed/legacy layouts.
+- Keep island borders and shadows visible through nested scrollports by using
+  existing gutter space inside the clipping boundary. Preserve surface
+  alignment, shared gaps, and split resizing without theme clearance tokens.
+  Add browser pixel checks for painted borders/shadows and clipping regressions.
+- Publish only the maintained Capillary, Shiny, Soft, White, and Minimal themes.
+  The former Glossy, Original, Java, Dark, and Sci-fi assets and picker entries
+  are removed from the package and applications.
+- Make named-theme surfaces, text, borders, and fills palette-derived. In
+  particular, Shiny progress chrome now follows the muted surface and primary
+  ramps instead of fixed Ice blue stops. Neutral black/white gloss and shadow
+  overlays remain intentionally literal.
+- Replace hue-named palette status primitives with semantic negative, positive,
+  and neutral status colors. Error and success aliases follow the negative and
+  positive colors; multi-state checkbox deny, require, and prefer chrome uses
+  negative, positive, and neutral respectively.
+- Derive shared chrome backgrounds from muted primary palette tones, so panels,
+  table headers, button gradients, and disabled surfaces follow palette changes.
+  Ice blue preserves exactly `#f5f7f8`, `#ebeff3`, and `#d7dee3`. The derivation
+  uses relative HSL colors and sRGB mixing; existing UI aliases remain overridable.
+- Add palette-level `--palette-primary-surface-saturation`: `0` removes primary
+  hue from the three chrome surfaces, `1` retains their calibrated default.
+- Keep unchanged DataTable headers out of row-update renders and avoid redundant
+  renderer marker, attribute, dataset, and style writes.
+- Preserve table-part names after minification and identify header cells by column.
+- Preserve table/header/body identities when loading/error messages or captions change.
+
+- `DataTable` filterable columns no longer keep a permanent document-level
+  click listener: the outside-click listener that closes the filter panel is
+  now attached only while the panel is open. Previously every click in the
+  document fired it, which also flooded event traces with a
+  "Table header cell: click" interaction per click. The listener uses the new
+  `Component.listenWhile`, so it stays on the normal traced native-event path
+  and coalesces with other listeners observing the same click.
+
 ### Added
 
+- Add a live `readOnly` state to Dropdown, checkbox variants, RadioButton,
+  RadioGroup, Toggle, and stylesheet pickers. Read-only value controls stay
+  focusable and readable, expose native `readonly` or `aria-readonly` as
+  appropriate, and reject attempted user changes without becoming disabled.
+- Add palette-derived base read-only chrome tokens for inputs, dropdowns,
+  checkables, and toggles. Themes can override the tokens but no longer need to
+  reproduce disabled styling to represent a fixed value.
+- Add inherited `islands` layout mode to `CapillaryUiApp` and `Layout`, with
+  native `cap-island-layout` / `cap-island-layout-off` traits. One outer inset
+  and shared gutters replace accumulated island margins inside opt-in scopes;
+  ordinary island content and legacy layouts keep their existing spacing.
+  The `--island-gap` and `--island-inset` tokens support theme/application
+  overrides, RouteOutlet carries the mode, and SplitView puts its accessible
+  separator in one gutter, including zero-gap and RTL resizing.
+- Add the light `capillary` theme: bright rounded cards, restrained neutral
+  elevation, compact controls, and palette-primary selected states.
+- Add an overridable instance diagnostic label and a named table-body consumer.
+  Consumer facts report render triggers/passes and own renderer DOM-write counts,
+  distinguishing execution from DOM work without changing update scheduling.
+- Add `Component.listenWhile(target, type, listener, options)`: like
+  `listen`, but returns a function that detaches the listener, for listeners
+  that are only active some of the time. It runs through the same traced
+  native-event coalescing as `listen` and is removed on destroy if still
+  attached.
+- Add a `filterable` column flag to `DataTable`: a column marked
+  `filterable` derives its header filter options from the field's distinct
+  values across the source's unfiltered rows, so options stay stable while
+  a filter is applied. Explicit `filterOptions` still take precedence.
+  Local and caller-query data sources expose their pre-filter rows through
+  the new `TableDataSource.sourceRows`; remote sources fall back to the
+  displayed rows.
 - Add diagnostic ownership scopes and stable diagnostic labels, automatic
   native interaction roots, component/read/watch and function-consumer facts,
   and reactive child, live-property, and native-binding endpoints. Synchronous
@@ -16,6 +123,29 @@ Versioning.
 
 ### Changed
 
+- Use flexbox for single-axis component stacks and simple centered chrome,
+  retaining grid only where its track model is needed. This does not change the
+  public DOM or layout contract.
+- Give all single-line controls the same minimum row footprint with symmetric
+  breathing room, including checkbox/radio variants, temporal inputs, and
+  ProgressBar. Add `--control-row-min-height` and `--control-row-padding-block`
+  without changing painted control shapes or Capillary's `6px 5px` padding.
+  Only OptionsBox retains compact rows and owns a fixed 2px vertical option
+  rhythm across themes; RadioGroup no longer adds a default gap on top of the
+  common row spacing elsewhere.
+- Empty required text, temporal, and dropdown controls now have a subtle
+  themeable dashed required-value outline. The same outline appears on an
+  unchecked two-state `Checkbox`; tri- and quad-state checkboxes intentionally
+  do not use native required validity because no single semantic state is the
+  required value.
+- Retained `Loading` results in `DataTable`, `ListView`, and `TreeView` now
+  show a non-blocking translucent animated working texture while their existing
+  rows remain visible.
+
+## 1.2.0 - 2026-09-15
+
+### Changed
+
 - Make DataTable, ListView, and TreeView shrink and own overflow before a
   bounded flex layout container must scroll. DataTable header cells now remain
   sticky within the table's scrollport.
@@ -42,8 +172,8 @@ Versioning.
   `cap-header:has(+ cap-toolbar)` shadow override together with its
   `--section-header-with-toolbar-shadow` variable.
 - Normalize line-control sizing and text centering in structural CSS: 24px
-  default textbox, dropdown, toggle, and button bodies at 12px UI text, with
-  compact checkbox/radio rows. Remove Shiny's label/select text offsets and
+  default textbox, dropdown, toggle, and button bodies at 12px UI text.
+  Remove Shiny's label/select text offsets and
   prevent toggle border/selection changes from shifting segment text.
 - Refine Shiny's input depth, toolbar/table-header chrome, navigation-to-toolbar
   seam, and loading BlockGraph treatment without moving structural layout
@@ -89,7 +219,13 @@ Versioning.
   CSS/data namespaces to the `cap-*` prefix. Existing released entries below
   retain their historical names.
 
-## 1.4.0 - 2026-09-13
+## Historical Fray releases
+
+The entries below describe released `@sylwellsoftware/fray` versions before the
+package was renamed to `@capillaryjs/capillary-ui`. They are retained as
+historical release notes and are not Capillary UI release versions.
+
+## Fray 1.4.0 - 2026-09-13
 
 ### Added
 
@@ -235,7 +371,7 @@ Versioning.
   `RadioGroup`, `DatePicker`, `DateTimePicker`, and `TimePicker`, which were
   missing from the stylesheet manifest.
 
-## 1.3.1 - 2026-09-08
+## Fray 1.3.1 - 2026-09-08
 
 ### Fixed
 
@@ -245,7 +381,7 @@ Versioning.
 - Published npm packages now include this changelog alongside their release
   history.
 
-## 1.3.0 - 2026-09-08
+## Fray 1.3.0 - 2026-09-08
 
 ### Added
 
@@ -269,7 +405,7 @@ Versioning.
 - Shiny now presents `NavigationBar` as a light, text-link navigation strip
   beneath application chrome instead of a dark action-bar surface.
 
-## 1.2.0 - 2026-09-08
+## Fray 1.2.0 - 2026-09-08
 
 ### Added
 
@@ -307,7 +443,7 @@ Versioning.
   the published text color as well as typography.
 - RadioGroup basic rendering adjusted
 
-## 1.1.1 - 2026-09-07
+## Fray 1.1.1 - 2026-09-07
 
 ### Changed
 
@@ -318,7 +454,7 @@ Versioning.
   semantics, meaningful HTML/CSS separation, and the complementary intent
   behind the Glue and Fray names.
 
-## 1.1.0 - 2026-09-07
+## Fray 1.1.0 - 2026-09-07
 
 ### Added
 
@@ -351,7 +487,7 @@ Versioning.
   `--font-size`, and `--line-height` tokens, preventing inherited controls and
   native content from falling back to the browser's serif defaults.
 
-## 1.0.0 - 2026-09-06
+## Fray 1.0.0 - 2026-09-06
 
 ### Added
 
@@ -433,7 +569,7 @@ Versioning.
 - Multi-state Checkbox variants synchronize the native checked property after
   every semantic transition.
 
-## 0.7.0 - 2026-09-04
+## Fray 0.7.0 - 2026-09-04
 
 ### Added
 
@@ -449,7 +585,7 @@ Versioning.
   inherit their mounted route lineage without changing Glue or unrouted
   component behavior.
 
-## 0.6.0 - 2026-09-04
+## Fray 0.6.0 - 2026-09-04
 
 ### Added
 
@@ -467,7 +603,7 @@ Versioning.
 - Theme/color root attributes and public custom properties are prefix-free;
   see the semantic-markup and theming migration guidance.
 
-## 0.5.0 - 2026-09-03
+## Fray 0.5.0 - 2026-09-03
 
 ### Changed
 
@@ -475,7 +611,7 @@ Versioning.
   the checked state, so native checkbox interactions remain correct for
   bindings such as `visible`/`hidden`.
 
-## 0.4.0 - 2026-09-03
+## Fray 0.4.0 - 2026-09-03
 
 ### Added
 
@@ -487,7 +623,7 @@ Versioning.
 - Application services are registered at the composition root and inherited by
   nested class components without service prop-drilling.
 
-## 0.3.0 - 2026-09-03
+## Fray 0.3.0 - 2026-09-03
 
 ### Added
 
@@ -507,7 +643,7 @@ Versioning.
 - `DataTable` uses one of `data`, `dataSource`, or `rest` instead of legacy
   query/REST props.
 
-## 0.2.0 - 2026-09-03
+## Fray 0.2.0 - 2026-09-03
 
 ### Added
 
@@ -520,7 +656,7 @@ Versioning.
   colors, and published package checks validate CSS subpaths.
 - Fray's Glue peer range follows the compatible Glue `0.2.x` line.
 
-## 0.1.0-alpha.1 - 2026-09-02
+## Fray 0.1.0-alpha.1 - 2026-09-02
 
 ### Added
 

package/README.md

@@ -149,6 +149,14 @@ A class component has explicit phases:
 `onCleanup()` registers listeners or other cleanup functions that Capillary UI invokes
 on destruction.
 
+Diagnostic labels default to static `diagnosticLabel`, `hostName`, then the class
+name. Override the instance `diagnosticLabel` getter when instances need distinct
+names; identity labels are captured at first observation. Table diagnostics expose
+`Table header`, column-specific header cells, and `Table body`. Unchanged header
+props skip parent-driven rendering, while sort/filter subscriptions remain active.
+Consumer events distinguish render passes from own renderer DOM writes; see the
+[diagnostics guide](../../docs/diagnostics.md) for the exact counting boundary.
+
 ```tsx
 class Counter extends Component {
     readonly count = new Emitter(0)
@@ -197,7 +205,7 @@ class Badge extends Component<BadgeProps> {
     static override hostName = 'badge'
     static override css = css`
         & { display: inline-flex; }
-        &[data-tone="positive"] { color: var(--palette-green); }
+        &[data-tone="positive"] { color: var(--palette-status-positive); }
     `
 }
 ```
@@ -313,11 +321,11 @@ the tables below denotes that TypeScript type parameter.
 | `Toolbar` | Named action group | `label`, `orientation` |
 | `Label` | Native label for rich or live text | `text`, `htmlFor`; live: `text` |
 | `Textbox` | Labelled native text input with validation | `label`, `valueEmitter`, `defaultValue`, `type`, `name`, `placeholder`, `disabled`, `required`, `readOnly`, `busy`, `error`, native text constraints, `inputRef`, `onInput`, `onChange`; live: availability, `busy`, and `error` |
-| `Dropdown<T>` | Labelled native select | `options`, `label`, `valueEmitter`, `defaultValue`, `placeholder`, `disabled`, `required`, `busy`, `error`, `onChange`; `options` may be static or a readable emitter whose fetch state supplies loading/error feedback |
-| `RadioButton` | Standalone native radio and label | `label`, `name`, `value`, `checked`, `disabled`, `required`, `busy`, `error`, `onChange`; live: state, availability, `busy`, `error` |
-| `RadioGroup<T>` | Named native-radio fieldset owning one value | `options` as `[value, label]` tuples, `label`, `valueEmitter`, `defaultValue`, `disabled`, `required`, `busy`, `error`, `onChange`; options are ordinary render data |
-| `Toggle<T>` | ARIA radio group rendered as toggle buttons | `options` as `[value, label]` tuples, `label`, `valueEmitter`, `defaultValue`, `disabled`, `required`, `busy`, `error`, `onChange` |
-| `Checkbox<T>` | Configurable keyboard-operable semantic state cycle | `symbols` as `[content, value]` tuples, `label`/`ariaLabel`, `valueEmitter`, `defaultValue`, `disabled`, `required`, `busy`, `error`, `onChange` |
+| `Dropdown<T>` | Labelled native select | `options`, `label`, `valueEmitter`, `defaultValue`, `placeholder`, `disabled`, `required`, `readOnly`, `busy`, `error`, `onChange`; `readOnly` retains focusability and restores the selected value after attempted changes; `options` may be static or a readable emitter whose fetch state supplies loading/error feedback |
+| `RadioButton` | Standalone native radio and label | `label`, `name`, `value`, `checked`, `disabled`, `required`, `readOnly`, `busy`, `error`, `onChange`; live: state, availability, `busy`, `error` |
+| `RadioGroup<T>` | Named native-radio fieldset owning one value | `options` as `[value, label]` tuples, `label`, `valueEmitter`, `defaultValue`, `disabled`, `required`, `readOnly`, `busy`, `error`, `onChange`; options are ordinary render data |
+| `Toggle<T>` | ARIA radio group rendered as toggle buttons | `options` as `[value, label]` tuples, `label`, `valueEmitter`, `defaultValue`, `disabled`, `required`, `readOnly`, `busy`, `error`, `onChange` |
+| `Checkbox<T>` | Configurable keyboard-operable semantic state cycle | `symbols` as `[content, value]` tuples, `label`/`ariaLabel`, `valueEmitter`, `defaultValue`, `disabled`, `required`, `readOnly`, `busy`, `error`, `onChange` |
 | `TriCheckbox` | Neutral/prefer/deny `FilterMode` cycle | Same public props as `Checkbox`, except fixed symbols |
 | `QuadCheckbox` | Neutral/prefer/require/deny `FilterMode` cycle | Same public props as `Checkbox`, except fixed symbols |
 | `DatePicker` (experimental) | Native `<input type="date">` | `CivilDate` value props, `label`/`ariaLabel`, `name`, `autoComplete`, `disabled`, `required`, `readOnly`, `busy`, `error`, `min`/`max`/`step`, `inputRef`, input/change callbacks |
@@ -330,7 +338,12 @@ the native forward cycle.
 
 `busy` is presentational state: it sets native/ARIA busy semantics and paints
 the theme's moving working texture without disabling an input or choice.
-`Button` remains the exception: a busy action is unavailable until it settles.
+`Button` remains the exception: a busy action is unavailable until it settles,
+but keeps its normal button colors, border, and elevation with the working
+texture layered on top. `ProgressBar` only paints that working texture when it
+has a `valueEmitter` whose fetch state is `Loading`; this applies to both
+determinate and indeterminate bars. A literal `value={null}` is simply an
+unfilled indeterminate bar.
 When `error` is also present, error presentation wins over the animation.
 Every error-bearing control describes its native surface with a focusable
 `role="alert"` overlay. Its icon and initially hidden message are absolutely
@@ -355,12 +368,12 @@ const view = new Emitter<'list' | 'grid'>('list')
 
 | Component | Purpose | Key props and state |
 | --- | --- | --- |
-| `CapillaryUiApp` | Fixed `cap-app` application shell and theme-text boundary | `sizing`: `embedded`/viewport axes; `layout`: `horizontal`/`vertical`; `landmark`: `main`/`none`; content or overridden `renderContent()` |
+| `CapillaryUiApp` | Fixed `cap-app` application shell and theme-text boundary | `sizing`: `embedded`/viewport axes; `layout`: `horizontal`/`vertical`; `islands`: inherited surface spacing; `landmark`: `main`/`none`; content or overridden `renderContent()` |
 | `Header` | Styled native heading surface | `level` (1–6), `headingId`, content |
-| `GroupBox` | Labelled group; defaults to a bordered vertical-header group and may be a section or column | required `header`, content; optional `variant`: `section` or `column` |
-| `OptionGroup` | Labelled native fieldset for related controls | `label`/`ariaLabel`, `OptionGroupHeaderEnd` and ordinary content children, `disabled`, `required`, `busy`, `error`; state props are live |
-| `OptionsBox` | GroupBox specialization arranging option groups | required `header`, `OptionGroup` content |
-| `Layout` | Presentation-only arrangement of arbitrary children | exactly one of `horizontal`/`vertical`; `allocation`, `scroll`, optional accessible-region configuration |
+| `GroupBox` | Labelled group; defaults to a bordered vertical-header group and may be a section or column | required `header`, direct content arranged vertically (`section` arranges direct content horizontally); optional `variant`: `section` or `column` |
+| `OptionGroup` | Labelled native fieldset for related controls | `label`/`ariaLabel`, `OptionGroupHeaderEnd` and ordinary content children, `disabled`, `required`, `busy`, `error`; state props are live. Use for related direct checkboxes or multiple distinct controls. |
+| `OptionsBox` | GroupBox specialization arranging compact choice groups | required `header`, direct `OptionGroup` and/or `RadioGroup` content |
+| `Layout` | Presentation-only arrangement of arbitrary children | exactly one of `horizontal`/`vertical`; `allocation`, `scroll`, inherited `islands` spacing, optional accessible-region configuration |
 | `Panel` | Optional labelled, themed region composed over a Layout body | `header`, `horizontal`/`vertical`, `allocation`, `scroll`, `disabled`; `PanelToolbar` and ordinary content children; live: `disabled` |
 | `Sidebar` | Labelled complementary region with fixed header/toolbar and scrolling content | `header`, `ariaLabel`; `SidebarToolbar` and ordinary content children |
 | `SplitView` | Resizable two-pane layout | required `SplitPrimary` and `SplitSecondary` Layout panes; `horizontal`/`vertical`, `allocation`, initial/minimum sizes, separator label, `onResize` |
@@ -475,12 +488,13 @@ range while retaining selections outside that range.
 On an initial snapshot, or a loading snapshot with no result, all three
 collection views render deterministic, `aria-hidden` placeholder rows;
 `placeholderCount` selects their count. A loading snapshot with retained rows
-keeps those rows in place and marks the collection busy, avoiding flicker during
-sort and filter refinements. Application renderers never receive dummy values,
-and refreshes preserve valid keyed selections and expansions. Error snapshots
-retain any available rows, add an error edge and overlay detail icon, and stop
-the loading animation. A `DataTable` data source with `retry` also renders its
-localized retry action.
+keeps those rows in place, marks the collection busy, and displays a thin
+animated translucent working texture, avoiding flicker during sort and filter
+refinements.
+Application renderers never receive dummy values, and refreshes preserve valid
+keyed selections and expansions. Error snapshots retain any available rows,
+add an error edge and overlay detail icon, and stop the loading animation. A
+`DataTable` data source with `retry` also renders its localized retry action.
 
 Advanced compositions may use `BaseSelectionHandler`,
 `SingleSelectionHandler`, `MultiSelectionHandler`, and
@@ -503,13 +517,21 @@ expander needs a reusable presentation trait such as `colored`.
 For reusable sources, use `createLocalTableDataSource`,
 `createQueryTableDataSource`, `createHandlerTableDataSource`, or
 `createRestTableDataSource`. Sources expose `query`, `sortEmitter`,
-`filtersEmitter`, optional `retry`, and `dispose()`. Both direct data and
-query-shaped sources pass their rows through an emitter-derived local table
-view, so their sort and filter state always changes the rendered rows.
+`filtersEmitter`, optional `retry`, optional `sourceRows`, and `dispose()`.
+Both direct data and query-shaped sources pass their rows through an
+emitter-derived local table view, so their sort and filter state always
+changes the rendered rows. `sourceRows` exposes the rows before local
+sort/filter when the source can provide them — local and caller-query
+sources do; remote sources leave it absent because filtering is
+server-side.
 
 `TableColumn` definitions own display and local comparison/filter functions.
 When a column's visible `label` is rich content, supply its textual
 `ariaLabel` for Capillary UI-generated sort and filter control names.
+Set a column's `filterable` flag to derive its header filter options from
+the field's distinct values across `sourceRows` (or the displayed rows when
+the source cannot expose them), so the options stay stable while a filter
+is applied. Explicit `filterOptions` take precedence over `filterable`.
 The pure `applyLocalTableState`, `serializeTableQuery`, and related table-query
 helpers keep local behavior and remote encoding explicit. Pagination,
 virtualization, and server-specific wire policy remain application concerns.
@@ -519,7 +541,7 @@ virtualization, and server-specific wire policy remain application concerns.
 | Component | Purpose | Key props and state |
 | --- | --- | --- |
 | `Dialog` | Controlled native modal with focus containment and restoration | `title`, `description`, `DialogActions` and ordinary content children, `valueEmitter`/`defaultValue`, `closeLabel`, `showCloseButton`, `initialFocusRef`, `onClose` |
-| `ProgressBar` | Labelled native progress with visual track | required `label`, `value` or `valueEmitter`, `max`, `valueText`; `null` is indeterminate |
+| `ProgressBar` | Labelled native progress with visual track | required `label`, `value` or `valueEmitter`, `max`, `valueText`; fills its available width; `null` is indeterminate; emitter-backed busy chrome (including determinate bars) requires `FetchState.Loading` |
 | `ThemePicker` | Select and replace a Capillary UI theme link | value props, `options`, `label`/`ariaLabel`, `disabled`, `targetDocument`, `onChange` |
 | `ColorPicker` | Select and replace a Capillary UI color link | same contract as `ThemePicker` |
 
@@ -738,6 +760,14 @@ component selectors. Color files provide anchors and endpoints. Component
 `static css` owns selectors, layout, pseudo-elements, native states, and
 interaction mechanics.
 
+The three chrome backgrounds (`--ui-primary-bg-color`, `--ui-medium-bg-color`,
+and `--ui-dark-bg-color`) alias muted primary surface tones derived from the
+palette's primary anchor and light endpoint. Ice blue retains the exact legacy
+colors `#f5f7f8`, `#ebeff3`, and `#d7dee3`; other palettes recolor these surfaces.
+See the [palette contract](colors/README.md#muted-primary-surfaces) for the
+relative-HSL/sRGB calibration, including the `0`–`1`
+`--palette-primary-surface-saturation` palette control and override points.
+
 Theme files provide intentional overrides. Custom properties are the primary
 instrument and belong on `:root` inside `@layer theme`, with `color-scheme` as
 the only ordinary property in that block. A theme may also write ordinary CSS
@@ -746,6 +776,11 @@ be placed after the `@layer theme` block: component CSS is injected as an
 unlayered `<style>` element prepended to `<head>`, so unlayered theme rules win
 by document order while layered ones would always lose.
 
+The built-in theme options are Capillary, Shiny, Soft, White, and Minimal.
+Capillary is a bright, compact card treatment with restrained elevation and
+palette-primary selections. Minimal is adaptive; the other options are fixed
+light treatments.
+
 `capillaryUiThemeVariableCatalog` describes the supported palette and semantic
 variable hierarchy. `findCapillaryUiStylesheetOption`, `replaceCapillaryUiStylesheet`,
 `setCapillaryUiAppearance`, and `getCapillaryUiAppearance` support application-controlled
@@ -753,10 +788,23 @@ runtime selection.
 
 ### Line-control sizing
 
-Textbox, Dropdown, Toggle, and Button use `--control-min-height: 2em` by
-default: a 24px border-box minimum at the default 12px `--ui-font-size`.
-This minimum is independent of general UI padding and the text line height.
-Their labels and native controls inherit the font family and share a unitless
+All single-line controls reserve the same vertical row space: Textbox,
+Dropdown (including theme/color pickers), Toggle, Button, checkbox variants,
+RadioButton, date/time controls, and ProgressBar. Their existing painted
+bodies remain centered within that row; small checkbox/radio shapes do not
+grow to look like text fields.
+
+`--control-min-height: 2em` sets the body minimum (24px at the default 12px
+`--ui-font-size`). The row uses the greater of that minimum and
+`--control-row-min-height` (default `0px`), plus
+`--control-row-padding-block: .25em` on each side. Default rows are therefore
+30px with 3px above and below the body. Capillary supplies a `2.75em` row
+floor (39px including padding) to accommodate its roomier chrome and native
+temporal inputs while retaining its `6px 5px` control padding. Additional
+layout `gap` is optional and adds to this built-in breathing room.
+
+These are minimum sizes: multiline/rich content can grow without clipping.
+Labels and native controls inherit the font family and share a unitless
 1.2 authored text line height. Native single-line inputs may clamp the used
 line-height to platform font metrics (notably Firefox on Linux); their bodies
 and text remain centered. Larger content can increase the minimum-sized body.
@@ -765,6 +813,29 @@ minimum-width/shrinking behavior. Field and button inline padding is 5px;
 toggle segments use 6px. General `--space-xs`/`--space-sm` no longer determine
 these line controls' padding.
 
+`OptionsBox` deliberately keeps compact descendants, including through nested
+`OptionGroup` and `Layout` wrappers: it removes the shared row floor and
+block padding while retaining each control's natural body size. Its checkbox
+and radio rows are normally 1.2em, or the theme's larger painted-shell size.
+OptionsBox owns a fixed 2px vertical option rhythm—between nested groups,
+checkboxes, and radio options—regardless of theme. Ordinary GroupBox and
+Toolbar do not opt into compact spacing. RadioGroup elsewhere adds no
+inter-option gap by default, so the same number of radio and checkbox rows
+occupies the same height (excluding any group legend). Set
+`--radio-group-gap` to add spacing explicitly outside OptionsBox.
+
+An `OptionGroup` and a labelled `RadioGroup` both produce a native
+`fieldset`/`legend`. For one mutually exclusive choice, put the `RadioGroup`
+directly in an `OptionsBox` and give it the one visible label. Use an
+`OptionGroup` for a collection of direct checkboxes (or when its legend adds a
+separate, meaningful concept around several controls). Do not wrap a single
+labelled `RadioGroup` in an `OptionGroup` merely for layout; that creates
+redundant legends and nested fieldsets.
+
+Maintained themes add chrome without text offsets. Shadows do not participate
+in centering. Toggle borders and selected overlap are painted independently
+of segment layout, so selection does not move text.
+
 Horizontal form `GroupBox` children use their natural content size: GroupBox
 does not contribute a synthetic preferred width or an artificial size floor.
 Intrinsic label/body tracks distinguish preferred field widths from the
@@ -794,14 +865,6 @@ their normal inset. In this composition, omit a `DataTable` `caption`: the
 labelled Panel header supplies the surrounding data-region name. Application
 data-surface components can opt in by declaring the same static trait.
 
-Checkbox variants and RadioButton retain compact 1.2em label rows with 1em
-squares/circles. They center within stretched horizontal hosts without making
-vertical lists as tall as text fields. Date/time controls consume the same
-shared sizing rules. Themes may deliberately override the minimum (Java does),
-but Shiny uses the structural defaults and adds chrome without text offsets.
-Shadows do not participate in centering. Toggle borders and selected overlap
-are painted independently of segment layout, so selection does not move text.
-
 ### Root sizing and typography
 
 `CapillaryUiApp` is block-level and always applies `--application-background`,
@@ -837,7 +900,7 @@ semantics.
 Applications may explicitly opt native elements into Capillary UI presentation and
 layout contracts by applying public Capillary UI traits such as `island`,
 `cap-layout-horizontal`, `cap-layout-vertical`, `cap-size-natural`,
-`cap-size-flexible`, and `cap-scroll`. These traits are intentionally
+`cap-size-flexible`, `cap-scroll`, and `cap-island-layout`. These traits are intentionally
 element-agnostic and may style application-owned native markup as well as
 Capillary UI-owned hosts.
 
@@ -893,6 +956,85 @@ provide breakpoint variants.
 native markup. Capillary UI rejects nested component islands; application markup must
 preserve the same one-layer invariant.
 
+### Composing islands without margin doubling
+
+Enable `islands` once on the app or the Layout that contains the composition:
+
+```tsx
+<CapillaryUiApp sizing="viewport" islands>
+    <Header island>Application header</Header>
+    <Layout horizontal allocation="flexible">
+        <Sidebar island header="Navigation">...</Sidebar>
+        <Layout vertical allocation="flexible">
+            <Panel island header="Overview">...</Panel>
+            <Panel island header="Results" allocation="flexible">...</Panel>
+        </Layout>
+    </Layout>
+    <footer className="island cap-size-natural">Status</footer>
+</CapillaryUiApp>
+```
+
+`islands` is a **layout mode**; `island` still marks each **surface**. The
+outermost enabled container gets one perimeter inset. Participating layouts
+then place a single shared gutter between their children, with no island
+margins to add up. Nested Layouts inherit the mode automatically, including
+through ordinary wrappers and `RouteOutlet`. Repeating `islands` on an already
+enabled nested Layout does not add another inset. An app with `islands` and no
+explicit `layout` defaults to vertical; Layout still requires an axis.
+
+The public `CapillaryUiIslandLayoutProps` contract is static `islands?: boolean`:
+
+- `true` enables managed composition;
+- omitted or `undefined` inherits the surrounding mode;
+- `false` stops inheritance and restores legacy spacing in that subtree.
+
+Surface boundaries stop managed layout gaps from reaching controls inside
+them. Panel padding, toolbar gaps, and other internal spacing keep their own
+contracts. A later explicit enabled scope below an opt-out starts a fresh
+perimeter inset. Neither this mode nor nested layouts permit nested islands.
+
+Use `--island-gap` for gutters and `--island-inset` for the outer inset. Base
+defaults both to `1rem`; White uses zero. Override these on the composition,
+and optionally `--island-gap` on a nested Layout for a local gutter.
+`--island-padding` remains the padding **inside** each surface, except a direct
+app-root header: `cap-app > header.island` and `cap-app > cap-header.island`
+have zero padding. These shell headers delegate internal spacing to their
+navbar, toolbar, and branding rows. Their border, shadow, outer inset, and
+gutter remain unchanged. Nested headers and non-island headings are unaffected;
+this rule also applies outside managed island mode. Use a native `<header
+className="island">` for a shell containing navigation/toolbars; `Header`
+remains the component for a native heading.
+
+`SplitView`
+inherits the mode and places its separator in one shared gutter; a zero gutter
+retains an overlapping drag target and keyboard resizing.
+
+Scrolling layouts automatically include surrounding gutter space in their
+scrollport, so an island's border and shadow can paint there. Equal padding
+and negative margin extend the clip by half a gutter without moving the
+surfaces or increasing their separation. Nested scrollports reuse this space;
+RouteOutlet and SplitView leave clipping to their content/panes. Themes only
+declare their ordinary borders and shadows: no clearance token is required.
+Surface contents and opt-outs retain ordinary scrolling behavior. A zero
+gutter deliberately leaves no paint space between adjacent surfaces.
+
+Native markup can use `cap-island-layout` and `cap-island-layout-off`. Combine
+them with a direction trait, or with your own `display: grid` rules. A wrapper
+around one region needs no new trait. A native wrapper arranging multiple
+regions must opt into a layout: inheritance does not turn arbitrary elements
+into flex/grid containers. Axes, dimensions, responsive wrapping, allocation,
+and scroll ownership remain explicit application choices.
+
+Migration is opt-in. Existing layouts outside managed scopes keep
+`--island-margin` and their former behavior. When enabling a scope, remove
+margin-cancellation selectors and redundant gap rules, and move any intended
+spacing override to `--island-gap`/`--island-inset` on the layout. A direct CSS
+`margin` or `gap` override still wins through the normal cascade; the framework
+does not measure or rewrite application styles. `islands={false}` can isolate
+a legacy region during incremental migration.
+
+### Semantic category color
+
 `colored` consumes an explicit `--c1`, `--c2`, `--c3` triplet for the shared
 gradient and `--colored-shadow` treatment. It does not choose semantic colors
 for the application.