@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

package/docs/split-view.md

@@ -6,13 +6,31 @@ on compact ones. One of the opt-in app layouts (see
 [`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
 
 ```ts
-import { SplitView } from '@kerfjs/ui/split-view';
-import { deviceClass } from '@kerfjs/ui/device-class';
-import '@kerfjs/ui/split-view.css';
-// plus nav-stack.css when the compact path is reachable, and
-// wireResizableRegions / wireNavStack for the interactive behavior.
+import { SplitView } from "@kerfjs/ui/split-view";
+import { deviceClass } from "@kerfjs/ui/device-class";
+// plus wireResizableRegions / wireNavStack for the interactive behavior.
 ```
 
+In a browser bundler that honors the `browser` export condition (Vite, esbuild, and
+webpack do by default), the import above also
+loads SplitView's stylesheet and those of the components it renders internally
+(its compact `NavStack`, `ResizableRegion`, and the toolbar
+components). Without that condition, import the manual stylesheets instead:
+`@kerfjs/ui/split-view.css` plus those components' CSS, or `@kerfjs/ui/styles.css`.
+
+## Safe areas
+
+The list pane grows by the inline-start unsafe inset and pads for the edges it
+touches; the detail pads for its own outer edges. Neither is inset on the
+shared interior edge. A pane whose only child is a `Pane` lets that child own
+the insets, and the compact form hands them to its `NavStack`. See
+[Choosing an app layout › Safe areas](app-layouts.md#safe-areas).
+
+For a lowered list or detail background, render a `Pane` in that region with
+`appearance="sunken"`. SplitView arranges regions but does not own their
+vertical scroll; its compact NavStack form can use the view's or nested Pane's
+appearance. See [Lowered work surfaces](layout.md#lowered-work-surfaces).
+
 ## Responsive by device class
 
 `SplitView` is declarative; the app derives `compact` from the device class and
@@ -37,13 +55,84 @@ const selected = signal<string | null>(null);
 
 - **Roomy** (`compact: false`): both panes show. With `resizable`, the list sits
   in a `ResizableRegion` (wire it with `wireResizableRegions`); without it the
-  list takes a fixed `--kui-split-view-list-width` (default 320px) and the detail
-  fills the rest.
+  list takes a fixed width and the detail fills the rest. Set it with
+  `listWidth`: a number of CSS pixels (default 320), or `{ size, maxFraction }`
+  to cap the preferred size at that share of the SplitView's own width, so a
+  narrow container (a dialog, a small window) always leaves the detail in view —
+  `listWidth={{ size: 432, maxFraction: 0.5 }}` is 432px until the split is
+  narrower than 864px, then half of it. `listWidth` is for the fixed split; a
+  resizable list is sized by `resizable` (combining them throws). The
+  `--kui-split-view-list-width` token remains for theme-level defaults; the
+  prop wins over it.
 - **Compact** (`compact: true`): the split collapses to a `NavStack`. The list is
   the root; when `detailActive` is true the detail is pushed over it with an
   automatic back control (wire it with `wireNavStack`, whose `onBack` clears the
   app's selection). This is the portrait-tablet / handset presentation; as a
   dialog the compact form is a full-screen or large partial-cover modal.
 
+## Filling its container
+
+A SplitView fills its container's block size: give the container a definite
+height (a fixed or viewport-bounded `height`, a flex item that grows, a grid
+row) and the split stretches to it, with each `Pane` owning its own scrolling.
+That holds in a block box, a fixed-size native popover or dialog, a flex column
+below a header, and a grid; no app-side `display: grid` /
+`grid-template-rows: minmax(0, 1fr)` wrapper is needed. A container sized only
+by `max-height` has no height to fill, so the split takes its content height;
+give such a container a `height` instead.
+
+## Configuring the list region and the compact stack
+
+`resizable` forwards the list's `ResizableRegion` configuration alongside
+`size`, `min`, and `max`: `separator` (`"hidden"` keeps the resize hit target
+but paints no line), `handleIcon`, `contentOverflow`, and collapse —
+`collapsed`, `transitioning`, `collapseMotion`, `restoreControl`, and
+`restorePosition`. A collapsed list snaps to zero width, renders `inert` and
+`aria-hidden`, and the detail fills the split; the app owns the `collapsed`
+flag and renders the restore control (usually a `FloatingToolbar`). Omitted
+options keep the region's defaults.
+
+```tsx
+resizable={{
+  size: listWidth.value,
+  min: 220,
+  max: 480,
+  collapsed: listCollapsed.value,
+  restoreControl: <ShowThreadsToolbar />,
+}}
+```
+
+`compactStack` configures the compact `NavStack`: `toolbarConfig`, `backIcon`,
+`backText`, `hideToolbar`, the persistent `bottomToolbar`, and `chromeDividers`
+forward to the stack, and `list` / `detail` give each view its own structured
+top `toolbar` (`leading`, `center`, `trailing`) and `bottomToolbar`:
+
+```tsx
+compactStack={{
+  backText: "Threads",
+  toolbarConfig: { headingLevel: 1 },
+  list: { toolbar: { trailing: <ComposeGroup /> } },
+  detail: {
+    toolbar: { trailing: <ReplyGroup /> },
+    bottomToolbar: { label: "Message Actions", leading: <MessageActions /> },
+  },
+}}
+```
+
+The catalog's **Interactive Compact Drill-Down** example exercises this exact
+controlled flow: a list action sets the selected message, `detailActive` pushes
+its detail, and the wired Back action clears the selection to reveal the
+preserved list. It also forwards `compactStack`: a level-2 heading title over
+a bottom divider, a Compose group on the list view, and a Reply group plus a
+bottom toolbar on the detail. Use the same structure in application demos so
+compact examples show the interaction rather than rendering a disconnected
+detail state.
+
+The catalog's **Resizable, Collapsible List** example forwards `resizable`: a
+hidden separator that still resizes the list (its committed width comes back
+through `wireResizableRegions`' `onCommit` into the app's size signal), a Hide
+control in the list's own toolbar, and a `FloatingToolbar` restore control in
+the split's bottom-start corner.
+
 Compose the interactive wiring from the existing helpers — `SplitView` adds no
 wire of its own.

package/docs/sunken-panel.md

@@ -0,0 +1,106 @@
+# SunkenPanel
+
+`SunkenPanel` is a visually lowered application surface with one compact inset
+and a vertical content stack. Use it for a main work area or nested panel whose
+background should sit behind ordinary content, such as the primary stage in an
+issue tracker or component catalog.
+
+```tsx
+import { SunkenPanel } from '@kerfjs/ui/sunken-panel';
+
+<SunkenPanel ariaLabel="Release Workspace">
+  <ReleaseSummary />
+  <ReleaseChecks />
+</SunkenPanel>;
+```
+
+The default `shape="rounded"` uses the shared rounded-rectangle radius. Choose
+`shape="square"` for a flush or edge-to-edge area that needs `border-radius: 0`:
+
+```tsx
+<SunkenPanel shape="square">
+  <Workspace />
+</SunkenPanel>
+```
+
+## Filling a work area
+
+Set `fill` when the panel is the direct layout root of a parent with a definite
+height. Inside a flex column, use `flex` so it takes the remaining space and
+can shrink with its parent. Like `Grid`, `flex` accepts `true` (equivalent to
+`1 1 auto`), a CSS flex keyword, or a typed `CssFlex` value. The panel keeps
+`min-height: 0`, allowing its parent to own scrolling.
+
+```tsx
+<List fill>
+  <Toolbar label="Work Area" />
+  <SunkenPanel flex>
+    <WorkArea />
+  </SunkenPanel>
+</List>
+```
+
+Inside a `Pane`, the Pane's content remains the scroll owner. Place a
+`SunkenPanel fill` in a definite-height Pane content region when the surface
+itself needs to cover empty space, or use `flex` when a flex parent allocates
+the remaining space. The panel does not add another scroller.
+
+## Ownership
+
+The root owns its lowered background, 8px padding, and 8px vertical gap.
+Children own their borders and internal geometry. The application owns child
+order, responsive placement, and scrolling; `SunkenPanel` deliberately does not
+create another scroll container.
+
+Use `ariaLabel` only when the surface is a distinct region people need to find
+by name. With a label, the root receives `role="region"`; without one it remains
+a non-landmark grouping.
+
+Set `tabIndex={0}` to include the whole panel in the Tab order, or
+`tabIndex={-1}` for a programmatic focus target. Keyboard focus draws the
+standard focus ring. `outlined` keeps the same ring visible independently of
+focus, for example while the panel is a drop target. Give a focusable work area
+an `ariaLabel` when it is a distinct named region.
+
+Do not use `SunkenPanel` merely to add padding, as a substitute for pane
+header/content/footer anatomy, or around a child that already owns the same
+outer surface.
+
+For a lowered scrolling work area with Pane chrome, use
+[`Pane appearance="sunken"`](layout.md#lowered-work-surfaces). It paints the
+scroll viewport and empty space without adding a second scroller.
+
+## Public styling boundary
+
+Override the public properties at the composition boundary:
+
+- `--kui-sunken-panel-background`
+- `--kui-sunken-panel-foreground`
+- `--kui-sunken-panel-padding`
+- `--kui-sunken-panel-gap`
+- `--kui-sunken-panel-radius`
+
+The default background uses the shared translucent lowered-surface token.
+Nested panels composite naturally at every depth: darker in light mode and
+lighter in dark mode, without wrappers, depth classes, or per-instance token
+assignments. Pane and Web Awesome sunken surfaces use the same palette.
+See [Contextual transparency](./webawesome-theme.md#contextual-transparency).
+Keep ordinary composition on these defaults; public properties are theming
+escape hatches, not a reason to restyle each demo or nesting level.
+
+Every sunken surface — SunkenPanel, `Pane appearance="sunken"`, sunken
+Workbench regions and TabNavigator scenes, and Web Awesome
+`appearance="sunken"` — paints `--kui-sunken-surface`: a fine, monochrome
+grain (a seeded 100px tile at 4% maximum opacity) over the lowered color. The
+tile is drawn once per page, at runtime, by the first sunken surface that
+renders (nothing ships as an asset; server rendering paints the flat color
+until the browser renders one). Translucent children such as a `ValueTable`
+let the grain show through rather than adding their own. Set
+`--kui-sunken-texture: none` at `:root` for a flat lowered surface, or to
+another image; call `ensureSunkenTexture()` (exported from
+`@kerfjs/ui/sunken-panel`) on a page whose only sunken surfaces are Web Awesome
+elements.
+
+The public root class is `.kui-sunken-panel`. Prefer the properties above over
+styling descendants. The `square` shape deliberately overrides the radius
+property with zero; use `rounded` when customizing the radius token.