# XWUIShellPart

The per-region primitive that XWUIShell is built from - each of the shell's five regions (header / first / body / last / footer) is one instance, but it also works standalone as a dockable, resizable, collapsible panel. Its behavior is controlled by independent, orthogonal axes rather than a flat enum: `presence` (visible / collapsed / expanded / hidden), `flow` (inline / floating / sliding / pinned), `divider` (none / draggable splitter on the inner edge), and `anchor` (the edge it docks against). Layer on a resize range (`minSize` / `maxSize` / `snap`), state persistence (`storageKey`), reveal triggers (`trigger` hotkey/edge/hover), focus trapping for overlays (`focusTrap`), drag-to-swap (`movable`), and capability buttons (`detachable` / `tabbable` / `splittable`) that emit events for the host to implement. Axis state is reflected onto `data-*` attributes so CSS reacts without re-rendering.

## Basic Usage

A single start-anchored panel beside a main area; hover reveals its controls strip (minimise / hide) and its inner edge is a draggable resize divider.

```example
file: examples/BasicUsage.ts
html: examples/BasicUsage.html
title: Basic Usage
description: A standalone dockable, resizable region anchored to the start edge.
```

## Capability Flags

Enables `splittable`, `tabbable`, and `detachable` so the controls strip renders split / new-tab / detach buttons that emit `onSplit` / `onTabbify` / `onDetach` events for the consumer to wire.

```example
file: examples/CapabilityFlags.ts
html: examples/CapabilityFlags.html
title: Capability Flags
description: Detach, new-tab, and split affordance buttons that emit events for the host to handle.
```

## Flow Modes

Switches the `flow` axis live via `setFlow()` between inline (pushes neighbours), floating (modal overlay + backdrop), sliding (non-modal drawer), and pinned (sticky to its edge).

```example
file: examples/FlowModes.ts
html: examples/FlowModes.html
title: Flow Modes
description: Toggle a part between inline, floating, sliding, and pinned flow.
```

## Focus Trap

A floating panel opened with `focusTrap: true` so focus moves inside, Tab is trapped within the panel, and focus returns to the opener button on close.

```example
file: examples/FocusTrap.ts
html: examples/FocusTrap.html
title: Focus Trap
description: A floating overlay that traps Tab focus and restores it to the opener on close.
```

## Movable

`movable: true` adds a grip to the controls strip; dragging one panel's grip onto another fires `onSwap` with the drop target, here wired to swap the two panels' contents.

```example
file: examples/Movable.ts
html: examples/Movable.html
title: Movable
description: Drag a part's grip onto another part to swap them via the onSwap callback.
```

## Persisted State

`storageKey` saves the part's presence and size to localStorage, so collapsing or resizing the panel and reloading the page restores it exactly.

```example
file: examples/PersistedState.ts
html: examples/PersistedState.html
title: Persisted State
description: Presence and size survive a page reload via localStorage, keyed by storageKey.
```

## Presence States

Drives the four presence states through the public API - `show()` / `collapse()` / `expand()` / `hide()` - updating the part's `data-presence` attribute.

```example
file: examples/PresenceStates.ts
html: examples/PresenceStates.html
title: Presence States
description: Move a part through visible, collapsed, expanded, and hidden presence states.
```

## Resize Reset

A draggable-divider panel where double-clicking the divider resets the part to its natural / default width.

```example
file: examples/ResizeReset.ts
html: examples/ResizeReset.html
title: Resize Reset
description: Drag the inner-edge divider to resize, then double-click it to reset to the default width.
```

## Resize Snap

`snap: [200, 280, 360, 480]` makes the resize divider click into detents (within ~12px), bounded by `minSize` / `maxSize`, like an IDE splitter.

```example
file: examples/ResizeSnap.ts
html: examples/ResizeSnap.html
title: Resize Snap
description: The resize divider snaps to fixed width detents while dragging.
```

## Reveal Trigger

Two hidden panels: one reveals on a hotkey (`trigger: 'hotkey'` + `triggerHotkey: 'ctrl+b'`), the other on hovering the screen edge (`trigger: 'edge'`).

```example
file: examples/RevealTrigger.ts
html: examples/RevealTrigger.html
title: Reveal Trigger
description: Reveal hidden panels via a keyboard hotkey or an edge-hover gesture.
```

## Sliding Drawer

`flow: 'sliding'` renders a non-modal, animated drawer anchored to the start edge that slides off-screen when hidden, toggled with `show()` / `hide()`.

```example
file: examples/SlidingDrawer.ts
html: examples/SlidingDrawer.html
title: Sliding Drawer
description: A non-modal drawer that slides off its edge when hidden, with no backdrop.
```

```api
```