# XWUIShell The universal 5-region layout primitive - `header` / `[first | body | last]` / `footer` arranged as a CSS grid - and the foundation the entire `XWUIShell*` family (including XWUIShellApp and XWUIShellPage) is built on. Every region is an XWUIShellPart and is optional: empty regions collapse to zero space, so you only pay for what you pass. `first`/`last` are inline-direction edges (RTL-aware), and a rich config surface adds sticky headers/footers/rails, scroll behaviors (scroll-body, scroll-snap, stable gutter), header elevate/condense-on-scroll, container queries, density, region dividers (optionally draggable to resize), ARIA landmarks, safe-area insets, content max-width, and touch swipe gestures. ## Basic Usage The five regions wired into a grid, each region a coloured block, with the body growing to fill the space between the four edges. ```example file: examples/BasicUsage.ts html: examples/BasicUsage.html title: Basic Usage description: The 5-region grid shell - empty regions auto-collapse so you only pay for what you pass. ``` ## Body Scroll Snap The body scrolls horizontally through full-width slides that snap into place using `bodyScrollX` + `bodyScrollSnap: 'x'`. ```example file: examples/BodyScrollSnap.ts html: examples/BodyScrollSnap.html title: Body Scroll Snap description: Horizontal, scroll-snapping body slides driven by bodyScrollX and bodyScrollSnap. ``` ## Container Queries With `containerQueries`, the shell sizes off its own width: drag the wrapper smaller and the FIRST/LAST rails collapse below a 560px container width, independent of the viewport. ```example file: examples/ContainerQueries.ts html: examples/ContainerQueries.html title: Container Queries description: The shell adapts to its own width - side rails collapse below a 560px container width. ``` ## Content Max Width `contentMaxWidth` keeps the body band full-bleed while constraining and centring its content column (here `72ch`) for comfortable line lengths. ```example file: examples/ContentMaxWidth.ts html: examples/ContentMaxWidth.html title: Content Max Width description: Full-bleed body background with a centred, max-width readable content column. ``` ## Controls Reveal Demonstrates a part's controls strip (minimise / hide arrows) revealing in four modes - hover, edge, always, hidden - switched live via `setControls()` on the FIRST part. ```example file: examples/ControlsReveal.ts html: examples/ControlsReveal.html title: Controls Reveal description: Switch a sidebar part's control-arrow reveal mode between hover, edge, always, and hidden. ``` ## Density `density: 'compact'` tightens collapsed-rail sizes and exposes a `--xwui-shell-density` token, shown here alongside region dividers. ```example file: examples/Density.ts html: examples/Density.html title: Density description: Compact density tightens region padding and rail sizing. ``` ## Header Condense A tall hero header that shrinks to a compact bar once it sticks, via `stickyHeader` + `headerCondenseOnScroll` with the resting/condensed heights as CSS vars. ```example file: examples/HeaderCondense.ts html: examples/HeaderCondense.html title: Header Condense description: A 96px sticky hero header condenses to a 48px bar on scroll. ``` ## Header Elevate On Scroll A sticky header that stays flat at rest and raises a shadow only once it becomes stuck, via `stickyHeader` + `headerElevateOnScroll`. ```example file: examples/HeaderElevateOnScroll.ts html: examples/HeaderElevateOnScroll.html title: Header Elevate On Scroll description: A sticky header gains a drop shadow once the page scrolls under it. ``` ## Landmarks `landmarks` tags the regions with banner / main / complementary / contentinfo roles and injects a skip-to-content link that appears first on Tab. ```example file: examples/Landmarks.ts html: examples/Landmarks.html title: Landmarks description: ARIA landmark roles on each region plus an injected skip-to-content link. ``` ## Region Dividers `regionDividers` draws hairline separators, and `resizableFirst` / `resizableLast` turn a region's inner edge into a draggable splitter (double-click to reset, arrow keys to resize). ```example file: examples/RegionDividers.ts html: examples/RegionDividers.html title: Region Dividers description: Hairline separators between regions, with draggable splitters that resize the side rails. ``` ## Region Nav With `regionNavHotkey`, F6 cycles keyboard focus across the regions in order and Shift+F6 reverses. ```example file: examples/RegionNav.ts html: examples/RegionNav.html title: Region Nav description: F6 / Shift+F6 cycles focus between the five regions. ``` ## Region Toggle Every region can be shown or hidden at runtime via `showHeader` / `showFirst` / `showLast` / `showFooter`, with the body reclaiming the freed space. ```example file: examples/RegionToggle.ts html: examples/RegionToggle.html title: Region Toggle description: Toggle each region on and off at runtime; the body grows to fill hidden regions. ``` ## Rtl Direction `direction: 'rtl'` mirrors the body row so FIRST moves to the right edge and LAST to the left, matching the writing direction. ```example file: examples/RtlDirection.ts html: examples/RtlDirection.html title: Rtl Direction description: RTL mirrors the body row - FIRST to the right, LAST to the left. ``` ## Safe Area `safeArea` pads the header/footer (and side rails) with `env(safe-area-inset-*)` so chrome clears mobile notches and home bars. ```example file: examples/SafeArea.ts html: examples/SafeArea.html title: Safe Area description: Header and footer gain safe-area-inset padding for notch and home-bar clearance. ``` ## Scroll Body `scrollBody` keeps the header, footer, and side rails fixed while only the body scrolls, with the shell filling its host. ```example file: examples/ScrollBody.ts html: examples/ScrollBody.html title: Scroll Body description: Only the body scrolls; the four edge regions stay fixed. ``` ## Stable Scrollbar `stableScrollbar` reserves scrollbar-gutter space on the body so content doesn't shift sideways when the scrollbar appears. ```example file: examples/StableScrollbar.ts html: examples/StableScrollbar.html title: Stable Scrollbar description: The body reserves scrollbar gutter space to avoid horizontal content shift. ``` ## Sticky Footer `stickyFooter` pins the footer to the bottom of the scroll container as the page scrolls - e.g. a persistent action or status bar. ```example file: examples/StickyFooter.ts html: examples/StickyFooter.html title: Sticky Footer description: The footer stays pinned to the bottom while the page scrolls. ``` ## Sticky Header `stickyHeader` pins the header to the top of the scroll container while the page scrolls. ```example file: examples/StickyHeader.ts html: examples/StickyHeader.html title: Sticky Header description: The header stays pinned to the top while the page scrolls. ``` ## Sticky Part States Orthogonal visual looks for a sticky part - `frosted`, `transparent`, `shadow`, `elevated`, `bordered`, `minimized` - toggled live via the `xwui-shell-part-*` classes over colourful scrolling content. ```example file: examples/StickyPartStates.ts html: examples/StickyPartStates.html title: Sticky Part States description: Toggle a sticky header's frosted, shadow, elevated, bordered, and minimized looks. ``` ## Sticky Sidebars `stickyFirst` / `stickyLast` pin the FIRST and LAST columns to the top so the rails stay in view past long body content. ```example file: examples/StickySidebars.ts html: examples/StickySidebars.html title: Sticky Sidebars description: The FIRST and LAST rails stay pinned while the body scrolls. ``` ## Swipe Gestures `swipeGestures` lets touch users swipe inward from an edge to reveal a hidden region, tuned with `swipeThreshold` and `swipeEdgeZone`. ```example file: examples/SwipeGestures.ts html: examples/SwipeGestures.html title: Swipe Gestures description: Swipe in from any edge on touch devices to reveal a hidden rail. ``` ## Transparent Header `stickyHeader` + `transparentHeader` render a sticky frosted-glass header that scrolling content passes beneath. ```example file: examples/TransparentHeader.ts html: examples/TransparentHeader.html title: Transparent Header description: A translucent frosted header with content scrolling underneath. ``` ```api ```