@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/ui/layout.d.ts

@@ -0,0 +1,356 @@
+/**
+ * Layout regions (D-041 Phase 2): a `LayoutSpec` names regions per form factor, the engine lays
+ * them out with one CSS grid inside the safe area of a CSS-px overlay, and widgets register once
+ * with a region per form factor. The layout moves them when the form factor changes (a phone
+ * turned upright) and reports `freeRect`, the space the UI leaves, for the scene's camera.
+ *
+ * Everything is in CSS px relative to the overlay root. The geometry is pure (`resolveLayout`)
+ * and the DOM grid uses the same resolved track sizes, so the rects the layout reports are the
+ * rects the browser draws.
+ */
+import type { CaptionCard } from './caption.js';
+import type { Rect } from './overlay.js';
+export type FormFactor = 'phone-landscape' | 'phone-portrait' | 'tablet' | 'desktop';
+export declare const FORM_FACTORS: readonly FormFactor[];
+/**
+ * - `top`, `bottom`, `left`, `right`: chrome bars and rails.
+ * - `cardLane`: a lane for transient cards (beside the world on wide screens, under it upright).
+ * - `captionLane`: where a docked caption card sits; it never overlaps another region.
+ * - `fill`: what is left. `freeRect` is this region; widgets put here sit over the world.
+ * - `modal`: the dialog plane (the safe area less a margin). Panels open inside it; it overlaps
+ *   the grid by design and is the one region that may.
+ */
+export type RegionName = 'top' | 'left' | 'right' | 'bottom' | 'cardLane' | 'captionLane' | 'modal' | 'fill';
+export declare const REGIONS: readonly RegionName[];
+export interface Insets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+export declare const NO_INSETS: Readonly<Insets>;
+/**
+ * A grid track: a fixed CSS px size, `'fill'` (shares what the other tracks leave), or a
+ * fraction of the safe area's length on that axis clamped to `[min, max]`. When the tracks do
+ * not fit, fractional tracks shrink toward their `min` before `fill` gives up space.
+ */
+export type Track = number | 'fill' | {
+    frac: number;
+    min?: number;
+    max?: number;
+};
+/**
+ * How the base UI is sized in a form factor (see `Overlay.units`): `frame` = design px scaled
+ * with the canvas frame, `css` = CSS px.
+ */
+export type Units = 'frame' | 'css';
+/**
+ * The chrome bars and side rails whose size can follow their content (`BarSize`): `top` and
+ * `bottom` by height (ws/ui-8), `left` and `right` by width (ws/ui-9).
+ */
+export type BarName = 'top' | 'bottom' | 'left' | 'right';
+/**
+ * How a bar or rail is sized. `'fixed'` (the default) keeps the form's track. `'content'` grows
+ * the outer track to the bar's tallest widget (`top`, `bottom`; ws/ui-8) or the rail's widest
+ * widget at its `max-content` width (`left`, `right`; ws/ui-9, ws/ui-10) plus the form's `pad` each side, never below the form's track
+ * and never above `max`; the layout re-flows (the world's `fill`, so `freeRect`, gives up the
+ * space). A widget larger than `max` allows still reports through `overflows()`.
+ *
+ * Corner rule (ws/ui-9): where a content bar and a content rail meet (the cell on the bar's outer
+ * row and the rail's outer column, held by one of them in `areas`), the cell goes to the one whose
+ * content wants the larger track (widget plus pad, clamped by `max`). A tie keeps the form's
+ * `areas`, and so does a swap that would leave either region not a rectangle.
+ */
+export interface BarSize {
+    size: 'fixed' | 'content';
+    /** Largest track for `content`, CSS px. Default no limit. */
+    max?: number;
+}
+export interface FormSpec {
+    /** One entry per column of `areas`. */
+    columns: Track[];
+    /** One entry per row of `areas`. */
+    rows: Track[];
+    /**
+     * `grid-template-areas`, one string per row, region names separated by spaces (`.` for an
+     * empty cell). Each region must be one rectangle. `modal` is not a grid area.
+     */
+    areas: string[];
+    /** Smallest hit area for base widgets, CSS px (`--tc-tap-min`). */
+    tapMin: number;
+    /** Smallest text, CSS px (`--tc-text-min`). 0 = no floor. */
+    textMin: number;
+    /** Padding inside each region and gap between its widgets, CSS px (`--tc-region-pad`). */
+    pad: number;
+    /** Margin between the safe area and the modal region, CSS px. */
+    modalMargin: number;
+    /**
+     * The base UI's units in this form (`Overlay.units`): `frame` scales the theme, panels and
+     * toasts with the canvas frame; `css` keeps them at CSS px over the whole overlay.
+     */
+    units: Units;
+    /**
+     * How the `top` and `bottom` bars (ws/ui-8) and the `left` and `right` rails (ws/ui-9) are
+     * sized. Default fixed (the form's track). Merged over `LayoutSpec.bars` bar by bar.
+     */
+    bars?: Partial<Record<BarName, BarSize>>;
+}
+export interface ClassifyInput {
+    /** Overlay size, CSS px. */
+    width: number;
+    height: number;
+    /** The primary pointer is coarse (a finger). */
+    coarsePointer: boolean;
+    /** The screen's shorter side, CSS px (0 if unknown). */
+    shortSide: number;
+}
+export interface LayoutSpec {
+    /** Per-form-factor overrides, merged over `defaultForms` field by field. */
+    forms?: Partial<Record<FormFactor, Partial<FormSpec>>>;
+    /** Pick the form factor. Default `classifyFormFactor`. */
+    classify?: (input: ClassifyInput) => FormFactor;
+    /**
+     * Safe-area insets of the viewport, CSS px. Default: read from `env(safe-area-inset-*)`
+     * (overridable per document with `--tc-safe-top/right/bottom/left`, for emulation).
+     */
+    safeArea?: Insets;
+    /** Collapse tracks whose regions hold no registered widget. Default true. */
+    collapseEmpty?: boolean;
+    /**
+     * Bar and rail sizing for every form factor (ws/ui-8, ws/ui-9), e.g.
+     * `{ bottom: { size: 'content', max: 200 } }`. A form's own `bars` wins bar by bar.
+     */
+    bars?: Partial<Record<BarName, BarSize>>;
+}
+/** A rect in overlay CSS px, for the `'free'` escape hatch. */
+export interface FreePlacement {
+    region: 'free';
+    /** CSS px relative to the overlay root, or computed from the current layout. */
+    rect: Rect | ((layout: LayoutState) => Rect);
+    /** Why no region fits. Logged once per registration (see `Layout.freeUses`). */
+    reason: string;
+}
+/** Where a widget goes in one form factor. `hidden` takes it out of the layout. */
+export type Placement = RegionName | 'hidden' | FreePlacement;
+export interface WidgetOptions {
+    /** Placement per form factor; `default` covers the ones not named. Unnamed = hidden. */
+    place: Partial<Record<FormFactor | 'default', Placement>>;
+    /** Order inside its region (CSS `order`). Default 0, then registration order. */
+    order?: number;
+    /** Name for logs and `freeUses`. Default the element's id or `widget-N`. */
+    id?: string;
+    /**
+     * Called on every re-layout with the form factor, before the layout measures its widgets
+     * (ws/ui-10), so a widget sized per form factor (`ui.meter({ size: { phone: 56, default: 96 } })`)
+     * is already that size when a content bar or rail measures it. Keep it cheap: write only what
+     * changed.
+     */
+    onForm?: (ff: FormFactor) => void;
+    /**
+     * Called after a re-layout that moved the widget's element (ws/ui-11): into another region,
+     * to another place among its region's widgets, into `free` or out of `hidden`, with where it is
+     * now. It runs once the layout has measured, before `onChange`. Moving a node cancels its CSS
+     * transitions, so a widget that animates with them restarts them here. A re-layout that leaves
+     * a widget where it was does not move its element (its transitions and focus are kept).
+     */
+    onMove?: (region: RegionName | 'free' | 'hidden') => void;
+}
+/**
+ * A length per form factor (ws/ui-10): `default` covers the forms not named, and `phone` covers
+ * both `phone-landscape` and `phone-portrait` (a form's own name wins over it).
+ */
+export type FormSizes = {
+    default: number;
+} & Partial<Record<FormFactor | 'phone', number>>;
+/** A length, or one per form factor (`FormSizes`). */
+export type FormSize = number | FormSizes;
+/** `size` in `ff`: the number itself, else the form's entry, `phone` on a phone, `default`. Pure. */
+export declare function formSize(size: FormSize, ff: FormFactor): number;
+export interface WidgetHandle {
+    readonly element: HTMLElement;
+    /** Where it is now: a region, `free` or `hidden`. */
+    readonly region: RegionName | 'free' | 'hidden';
+    /** Change the placement; the layout re-applies at once. */
+    setPlace(place: WidgetOptions['place']): void;
+    /**
+     * Take it out of the layout. An element that had a parent when it was added goes back there
+     * (before the sibling it had, if that is still there); one added detached is removed.
+     */
+    remove(): void;
+}
+/**
+ * A widget whose measured box is larger than its region's inner box (the region less its `pad`
+ * on each side) in the current form factor (`Layout.overflows`). CSS px.
+ */
+export interface LayoutOverflow {
+    /** The widget's id (`WidgetOptions.id`). */
+    id: string;
+    region: RegionName;
+    /** The widget's measured box. */
+    w: number;
+    h: number;
+    /** The region's inner box. */
+    rw: number;
+    rh: number;
+}
+/** The pure result of laying out one form factor at one size. */
+export interface LayoutState {
+    formFactor: FormFactor;
+    /** The form's `units`. */
+    units: Units;
+    /** Overlay size, CSS px. */
+    width: number;
+    height: number;
+    /** The effective insets inside the overlay (the viewport insets the overlay rect touches). */
+    safeArea: Insets;
+    /** Resolved track sizes, CSS px. */
+    columns: number[];
+    rows: number[];
+    /** Region rects in overlay CSS px; `null` when the form has no such area. Collapsed = 0 size. */
+    regions: Record<RegionName, Rect | null>;
+    /** The `fill` region: the space the UI leaves for the world. */
+    freeRect: Rect;
+}
+/** Largest short side (CSS px) a phone has; tablets start around 744. */
+export declare const PHONE_MAX_SHORT_SIDE = 600;
+/** A window whose short side is under this is phone-sized, whatever the pointer. */
+export declare const PHONE_MAX_VIEW_SHORT = 480;
+/**
+ * Default form-factor choice. A phone is a coarse-pointer screen whose short side is at most
+ * `PHONE_MAX_SHORT_SIDE` (the `deviceTraits().handheld` rule), or any window whose short side is
+ * under `PHONE_MAX_VIEW_SHORT` (a tiny desktop window gets phone chrome rather than clipped
+ * desktop chrome). Phones split by orientation. Other coarse pointers are tablets; the rest are
+ * desktops.
+ */
+export declare function classifyFormFactor(i: ClassifyInput): FormFactor;
+/**
+ * The default regions. They are deliberately sparse: empty tracks collapse, so a phone shows
+ * only the chrome a scene registers, and the world gets the rest.
+ *
+ * - **desktop / tablet**: full-width top and bottom bars; left and right rails; a card lane
+ *   beside the world on the right; the caption lane under the world.
+ * - **phone-landscape**: height is the scarce axis, so left and right are full-height rails
+ *   (56 px: a 44 px tap target plus padding) and top/bottom sit between them; the card lane is
+ *   beside the world; the caption lane is a short strip under it.
+ * - **phone-portrait**: width is scarce, so the rails are slim and the card lane and caption lane
+ *   are full-width strips stacked under the world, above the bottom bar.
+ */
+export declare const defaultForms: Readonly<Record<FormFactor, FormSpec>>;
+/** The spec for `ff` with `spec.forms[ff]` merged over the default. */
+export declare function formSpec(ff: FormFactor, spec?: LayoutSpec): FormSpec;
+/** Parses `areas` into a cell grid; throws on ragged rows, unknown names or non-rectangles. */
+export declare function parseAreas(areas: readonly string[]): string[][];
+/**
+ * Resolves track sizes on one axis. `collapsed[i]` forces track i to 0. Fixed and fractional
+ * tracks take their size; when they overflow, fractional tracks shrink toward `min`, then the
+ * fill tracks get what is left (at least 0), shared equally.
+ */
+export declare function resolveTracks(tracks: readonly Track[], length: number, collapsed?: readonly boolean[]): number[];
+/** The insets a rect at `rect` inside a `viewport` of the given size actually touches. */
+export declare function effectiveInsets(rect: Rect, viewport: {
+    width: number;
+    height: number;
+}, insets: Insets): Insets;
+/** The tallest widget per bar and the widest per rail, CSS px (`resolveLayout`'s `content`). */
+type BarContent = Readonly<Partial<Record<BarName, number>>>;
+/**
+ * Lays out one form at one size. `occupied` names the grid regions that hold widgets; with
+ * `collapseEmpty`, a track collapses when every region in it is empty or also spans another
+ * track on that axis (so a full-width bar never holds a side rail open). `fill` is never empty.
+ * `content` is the tallest widget per bar (`top`, `bottom`) and the widest per rail (`left`,
+ * `right`), CSS px, for the form's `content` bars and rails (`BarSize`, with its corner rule).
+ * Pure.
+ */
+export declare function resolveLayout(formFactor: FormFactor, form: FormSpec, width: number, height: number, safeArea?: Insets, occupied?: ReadonlySet<RegionName> | null, content?: BarContent | null): LayoutState;
+/** Where `place` puts a widget in `ff`. Pure. */
+export declare function placementFor(place: WidgetOptions['place'], ff: FormFactor): Placement;
+/** What `followSafeArea` reads: `Host.safeArea` (`HostSafeArea`), or anything with its shape. */
+export interface SafeAreaSource {
+    insets(): Readonly<Insets>;
+    watch(fn: (insets: Readonly<Insets>) => void): () => void;
+}
+/**
+ * Pads the layout's regions by a host's safe-area insets (ws/host-mobile): sets
+ * `layout.setSafeArea(source.insets())` now and again whenever `source` reports a change, so the
+ * `top` region starts below the notch and the `bottom` region ends above the home indicator.
+ * `createGame` calls it with `host.safeArea` when the host has one; without it the layout reads
+ * `env(safe-area-inset-*)` itself. Returns unsubscribe, which also hands the page's own insets
+ * back to the layout.
+ */
+export declare function followSafeArea(layout: Pick<Layout, 'setSafeArea'>, source: SafeAreaSource): () => void;
+/** CSS px safe-area insets of `doc`'s viewport (`env(safe-area-inset-*)`, or the `--tc-safe-*` overrides). */
+export declare function readSafeArea(doc?: Document): Insets;
+export interface Layout {
+    /** `.tc-layout`, the grid (in the overlay's `layout` layer). */
+    readonly element: HTMLElement;
+    readonly formFactor: FormFactor;
+    /** The latest resolved layout. */
+    readonly state: Readonly<LayoutState>;
+    /** The space the UI leaves (the `fill` region), overlay CSS px. Hand it to the scene's camera. */
+    readonly freeRect: Readonly<Rect>;
+    /** Effective safe-area insets inside the overlay, CSS px. */
+    readonly safeArea: Readonly<Insets>;
+    /** Every widget currently placed with `region: 'free'`: its id and reason. */
+    readonly freeUses: readonly {
+        id: string;
+        reason: string;
+    }[];
+    /** The element of a region (for styling; register widgets with `add`). */
+    region(name: RegionName): HTMLElement;
+    /**
+     * The widgets in a region whose measured box is larger than the region's inner box, as of the
+     * last re-layout (ws/ui-7). Measured on each re-layout (`add`, `setPlace`, a resize,
+     * `refresh`), never per frame; a widget whose content grows later is caught at the next one.
+     */
+    overflows(): readonly LayoutOverflow[];
+    /**
+     * Register a widget. It is moved into its region now and on every form-factor change. When
+     * its measured box is larger than its region's inner box, it warns once (`[layout] … overflows`,
+     * naming the widget, the region and both sizes; again after `setPlace`) and is listed in
+     * `overflows()`.
+     */
+    add(element: HTMLElement, opts: WidgetOptions): WidgetHandle;
+    /**
+     * Dock a caption card (`overlay.caption` by default) in a region, `captionLane` unless
+     * `place` says otherwise. Docked, it fills its region; `hidden` or `free` placements undock
+     * it to its corner on the frame. Returns the handle.
+     */
+    dockCaption(caption?: {
+        element: HTMLElement;
+        dock(host: HTMLElement | null): void;
+    }, place?: WidgetOptions['place']): WidgetHandle;
+    /** Override the safe-area insets (`null` = read them from the page again). */
+    setSafeArea(insets: Insets | null): void;
+    /**
+     * A scene's own tracks over the spec's, per form factor, field by field (`null` = the spec's
+     * again). For a scene whose regions follow its content (a board sized first, a column taking
+     * what is left): set on enter and on every resize that changes them, clear on exit.
+     * Re-lays out now.
+     */
+    setForms(forms: LayoutSpec['forms'] | null): void;
+    /** Recompute now (the layout already follows `overlay.setFrame`). */
+    refresh(): void;
+    /** Called after every re-layout with the new state. Returns unsubscribe. */
+    onChange(fn: (state: LayoutState) => void): () => void;
+    destroy(): void;
+}
+/** What the layout needs from its overlay (`createOverlay` builds the one layout). */
+export interface LayoutHost {
+    readonly root: HTMLElement;
+    readonly layers: {
+        readonly layout: HTMLElement;
+    };
+    readonly caption: Pick<CaptionCard, 'element' | 'dock'>;
+    /** The overlay's box, CSS px. */
+    readonly rect: Readonly<Rect>;
+    onResize(fn: () => void): () => void;
+}
+/**
+ * Lays out regions over the overlay (`createOverlay` calls it; read it as `overlay.layout`).
+ *
+ * The density tokens `--tc-tap-min` and `--tc-text-min` (from the form spec), `data-form-factor`
+ * and the form's `units` go on the overlay root, so the base widgets in the panels layer follow
+ * them too.
+ */
+export declare function createLayout(overlay: LayoutHost, spec?: LayoutSpec): Layout;
+export {};