@dynamix-layout/core 1.2.0 → 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,519 @@
+/**
+ * Positions an absolutely positioned element. Adapters use this on their fast
+ * path (drags), so pointer moves never need a framework re-render.
+ * @param element - An absolutely positioned element inside the layout root.
+ * @param rect - Where to put it, in layout-root coordinates.
+ * @example
+ * layout.subscribe((s) => s.rects.tabsets.forEach((rect, id) => applyRect(panels.get(id)!, rect)))
+ */
+export declare function applyRect(element: HTMLElement, rect: Rect): void;
+
+/**
+ * Coalesces bursts of updates (pointer events can fire several times per
+ * frame) into at most one `onFlush` call per animation frame.
+ * @param onFlush - Called with the latest scheduled value, at most once per frame.
+ * @returns `schedule`, `flush` and `cancel`.
+ * @example
+ * const frame = createFrameScheduler((point: Point) => layout.updateDrag(point))
+ * element.addEventListener('pointermove', (e) => frame.schedule(toRootPoint(e)))
+ * element.addEventListener('pointerup', () => { frame.flush(); layout.endDrag() })
+ */
+export declare function createFrameScheduler<T>(onFlush: (value: T) => void): FrameScheduler<T>;
+
+/** Generates ids for new rows and tabsets. */
+export declare type CreateId = (kind: 'row' | 'tabset', hint?: string) => string;
+
+/**
+ * Creates a layout instance.
+ *
+ * @param options - Open tabs, an optional saved layout (v1 or v2), sizes and callbacks.
+ * @returns An instance that shares nothing with other instances. It never
+ * touches the DOM; call `setContainerRect` to give it a size.
+ * @throws {DynamixLayoutError} `INVALID_LAYOUT` or `UNSUPPORTED_VERSION` for a
+ * bad `initialLayout`; `DUPLICATE_TAB_ID` for duplicate tab ids in development.
+ * @example
+ * const layout = createLayout({
+ *   tabs: [{ id: 'editor' }, { id: 'terminal' }],
+ *   onLayoutChange: (json) => localStorage.setItem('layout', JSON.stringify(json)),
+ * })
+ * layout.subscribe((snapshot) => render(snapshot))
+ * layout.setContainerRect({ x: 0, y: 0, width: 1200, height: 800 })
+ */
+export declare function createLayout(options: LayoutOptions): Layout;
+
+/**
+ * Direction a row lays out its children in.
+ * `'horizontal'` places them side by side; `'vertical'` stacks them.
+ */
+export declare type Direction = 'horizontal' | 'vertical';
+
+/** What is being dragged. */
+export declare type DragSource = {
+    readonly type: 'tab';
+    readonly tabId: string;
+} | {
+    readonly type: 'tabset';
+    readonly tabsetId: string;
+} | {
+    readonly type: 'splitter';
+    readonly splitterId: string;
+};
+
+/** The current drag, if any. */
+export declare interface DragState {
+    readonly source: DragSource;
+    /** Where a tab or tabset would land; `null` over nothing valid. */
+    readonly target: DropTarget | null;
+    /** Rect of the drop indicator for `target`. */
+    readonly indicator: Rect | null;
+}
+
+/** Tab bar geometry the engine can't know (label widths), keyed by tabset id. */
+export declare interface DropMeasurements {
+    readonly tabBars: ReadonlyMap<string, TabBarMeasurement>;
+}
+
+/** Where a dragged tab or tabset is dropped. */
+export declare type DropTarget = {
+    readonly type: 'tabset';
+    readonly tabsetId: string;
+    readonly position: Side | 'center';
+} | {
+    readonly type: 'tab';
+    readonly tabId: string;
+    readonly position: 'before' | 'after';
+} | {
+    readonly type: 'root';
+    readonly position: Side;
+};
+
+/**
+ * Thrown for invalid input: malformed saved layouts, unsupported versions,
+ * and duplicate tab ids in development. Actions never throw.
+ * @example
+ * try {
+ *   layout.load(JSON.parse(stored))
+ * } catch (error) {
+ *   if (error instanceof DynamixLayoutError) console.warn(error.code, error.path)
+ *   else throw error
+ * }
+ */
+export declare class DynamixLayoutError extends Error {
+    readonly code: DynamixLayoutErrorCode;
+    /** Where in the input the problem is, e.g. `root.children[1].weight`. */
+    readonly path?: string;
+    constructor(code: DynamixLayoutErrorCode, message: string, path?: string);
+}
+
+/** Codes of errors thrown by the layout. */
+export declare type DynamixLayoutErrorCode = 'INVALID_LAYOUT' | 'UNSUPPORTED_VERSION' | 'DUPLICATE_TAB_ID';
+
+export declare interface FrameScheduler<T> {
+    /** Remember `value`; `onFlush` runs with the latest value on the next frame. */
+    schedule: (value: T) => void;
+    /** Run a pending flush now (e.g. on pointer up). */
+    flush: () => void;
+    /** Drop a pending flush (e.g. on unmount). */
+    cancel: () => void;
+}
+
+/**
+ * Rect of the drop zone on one edge of the layout, centred on that edge.
+ * @param container - The layout's container rect (`snapshot.rects.container`).
+ * @param side - The edge.
+ * @param options - Zone length (share of the edge) and thickness.
+ * @returns The zone rect, in layout-root coordinates.
+ * @example
+ * const zone = getRootDropZoneRect(snapshot.rects.container, 'left')
+ */
+export declare function getRootDropZoneRect(container: Rect, side: Side, options?: RootDropZoneOptions): Rect;
+
+/**
+ * @param tabset - The tabset's rect and state.
+ * @param tabBarHeight - Height of a horizontal tab bar.
+ * @returns The rect to give the tab bar element, and whether to rotate it.
+ * @example
+ * const { rect, isRotated } = getTabBarPlacement(snapshot.rects.tabsets.get(id)!, snapshot.tabsets.get(id)!, 40)
+ * applyRect(tabBar, rect)
+ * tabBar.style.transform = isRotated ? 'rotate(90deg)' : ''
+ */
+export declare function getTabBarPlacement(tabsetRect: Rect, tabset: {
+    readonly isFolded: boolean;
+    readonly parentDirection: Direction;
+}, tabBarHeight: number): TabBarPlacement;
+
+/**
+ * Area of a tabset below its tab bar; never negative when squeezed.
+ * @param tabsetRect - The tabset's rect.
+ * @param tabBarHeight - Height of its tab bar (0 without one).
+ * @returns The content area.
+ * @example
+ * applyRect(content, getTabContentRect(snapshot.rects.tabsets.get(tab.tabsetId)!, 40))
+ */
+export declare function getTabContentRect(tabsetRect: Rect, tabBarHeight: number): Rect;
+
+/**
+ * @returns `true` when `input` looks like a layout saved by v1.
+ * @param input - Anything, e.g. parsed JSON from storage.
+ * @example
+ * const saved = JSON.parse(localStorage.getItem('layout') ?? 'null')
+ * const layout = isLayoutV1(saved) ? migrateLayoutFromV1(saved) : saved
+ */
+export declare function isLayoutV1(input: unknown): input is LayoutTreeV1;
+
+/**
+ * A layout instance. Independent of every other instance; holds no timers and
+ * never touches the DOM. Actions return `true` when they changed the layout and
+ * `false` when they were refused or did nothing; they never throw.
+ */
+export declare interface Layout {
+    /** The current immutable snapshot. */
+    getSnapshot(): LayoutSnapshot;
+    /** Calls `listener` after every change. @returns A function that unsubscribes. */
+    subscribe(listener: (snapshot: LayoutSnapshot) => void): () => void;
+    /** Area to fill, in the coordinates every rect uses (`x`/`y` is usually the padding). */
+    setContainerRect(rect: Rect): void;
+    /** Replaces the open tabs: unlisted tabs are removed, new ones added and activated. */
+    setTabs(tabs: readonly TabInit[]): void;
+    /** Changes sizes without rebuilding anything. */
+    setOptions(options: LayoutSizeOptions): void;
+    moveTab(tabId: string, target: DropTarget): boolean;
+    moveTabset(tabsetId: string, target: DropTarget): boolean;
+    selectTab(tabId: string): boolean;
+    addTab(tab: TabInit, target?: DropTarget): boolean;
+    removeTab(tabId: string): boolean;
+    /** Moves a splitter so its centre is at `point`, clamped to the neighbours' minimum sizes. */
+    resizeSplitter(splitterId: string, point: Point): boolean;
+    /** Moves a splitter by `delta` px along its row (keyboard resizing). */
+    moveSplitterBy(splitterId: string, delta: number): boolean;
+    maximize(tabsetId: string): boolean;
+    restore(): boolean;
+    toggleMaximize(tabsetId: string): boolean;
+    fold(tabsetId: string): boolean;
+    unfold(tabsetId: string): boolean;
+    toggleFold(tabsetId: string): boolean;
+    /** Starts a pointer or keyboard drag. Tab and tabset drags leave maximized mode first. */
+    startDrag(source: DragSource): boolean;
+    /** Updates the drop target (tabs) or splitter position (splitters); never calls `onLayoutChange`. */
+    updateDrag(point: Point, measurements?: DropMeasurements): void;
+    /** Sets the drop target directly (keyboard move mode). */
+    setDragTarget(target: DropTarget | null, measurements?: DropMeasurements): void;
+    /** Commits the drag with one `onLayoutChange`. @returns Whether the layout changed. */
+    endDrag(): boolean;
+    /** Ends the drag and undoes any splitter movement. */
+    cancelDrag(): void;
+    getDropTarget(point: Point, source: DragSource, measurements?: DropMeasurements): DropTarget | null;
+    getDropIndicatorRect(target: DropTarget, measurements?: DropMeasurements): Rect | null;
+    /** Every valid target for `source`, in reading order. */
+    listDropTargets(source: DragSource): readonly DropTarget[];
+    /** For `aria-valuenow`, `aria-valuemin` and `aria-valuemax`. */
+    getSplitterBounds(splitterId: string): SplitterBounds | null;
+    /** Replaces the layout (v1 or v2) without calling `onLayoutChange`. */
+    load(layout: LayoutJSON | LayoutTreeV1): void;
+    /** Back to `initialLayout`, or the default layout of the current tabs. */
+    reset(): void;
+    /** The current layout. The same object is returned until the layout changes. */
+    toJSON(): LayoutJSON;
+    /** Removes every listener; later actions are ignored with a warning. */
+    destroy(): void;
+}
+
+/** Version written by {@link toLayoutJSON}. */
+export declare const LAYOUT_VERSION = 2;
+
+/** Why `onLayoutChange` was called. */
+export declare type LayoutChangeReason = 'move' | 'resize' | 'select' | 'fold' | 'maximize' | 'tabs' | 'reset';
+
+/** A saved layout. Splitters and pixel sizes are not stored. */
+export declare interface LayoutJSON {
+    version: 2;
+    root: RowJSON;
+    /** Id of the maximized tabset, if any. */
+    maximizedTabsetId?: string;
+}
+
+/** Any node of the layout tree. */
+export declare type LayoutNode = RowNode | TabsetNode | TabNode;
+
+/** Options for `createLayout`. */
+export declare interface LayoutOptions extends LayoutSizeOptions {
+    /** Open tabs. Their order only matters for the default layout. */
+    tabs: readonly TabInit[];
+    /**
+     * A saved layout (v2, or a v1 tree that is migrated automatically).
+     * @default the default layout built from `tabs`
+     */
+    initialLayout?: LayoutJSON | LayoutTreeV1 | null;
+    /**
+     * Id factory for rows and tabsets.
+     * @default deterministic per instance (`ts-<first tab>`, `row-<n>`)
+     */
+    createId?: CreateId;
+    /** Called after every committed change; never for drag frames or `load`. */
+    onLayoutChange?: (layout: LayoutJSON, reason: LayoutChangeReason) => void;
+    /** @default `console.warn` in development, silent in production */
+    onWarning?: WarningHandler;
+}
+
+/** Every rect of a layout, in layout-root coordinates. */
+export declare interface LayoutRects {
+    /** Area the layout fills; larger than the container when it can't fit. */
+    readonly container: Rect;
+    readonly rows: ReadonlyMap<string, Rect>;
+    /** As displayed: a maximized tabset gets the whole container. */
+    readonly tabsets: ReadonlyMap<string, Rect>;
+    readonly splitters: ReadonlyMap<string, Rect>;
+}
+
+/** Sizes that can change after creation. */
+export declare interface LayoutSizeOptions {
+    /** Smallest size of a tabset. @default { width: 40, height: 40 } */
+    minPanelSize?: {
+        width: number;
+        height: number;
+    };
+    /** Thickness of splitters. @default 10 */
+    splitterSize?: number;
+    /** Size of a folded tabset along its row. @default minPanelSize.height */
+    foldedSize?: number;
+}
+
+/**
+ * An immutable view of the layout. Every field keeps its previous reference
+ * unless it changed, and so does every entry of every map, so consumers can
+ * compare by reference at any depth.
+ */
+export declare interface LayoutSnapshot {
+    readonly root: RowNode;
+    readonly tabsets: ReadonlyMap<string, TabsetState>;
+    readonly splitters: ReadonlyMap<string, SplitterState>;
+    readonly tabs: ReadonlyMap<string, TabState>;
+    readonly rects: LayoutRects;
+    readonly maximizedTabsetId: string | null;
+    readonly drag: DragState | null;
+}
+
+/**
+ * A layout saved by v1 (`DynamixLayoutCore._root.toJSON()`). Accepted
+ * everywhere a {@link LayoutJSON} is, and migrated automatically.
+ */
+export declare interface LayoutTreeV1 {
+    typNode: 'row' | 'tabset' | 'tab' | 'bond';
+    nodName: string;
+    uidNode: string;
+    nodPart: number;
+    nodOpen?: string | boolean;
+    nodKids?: readonly LayoutTreeV1[];
+    nodFold?: boolean;
+    nodMaxd?: string;
+}
+
+/** A non-fatal problem, such as a repaired saved layout. */
+export declare interface LayoutWarning {
+    readonly code: LayoutWarningCode;
+    readonly message: string;
+    readonly path?: string;
+}
+
+/** Codes of non-fatal problems reported through `onWarning`. */
+export declare type LayoutWarningCode = 'MIGRATED_FROM_V1' | 'DUPLICATE_TAB_ID' | 'INVALID_ACTIVE_TAB' | 'INVALID_WEIGHT' | 'UNKNOWN_ID' | 'DESTROYED';
+
+/**
+ * Converts a layout saved by v1 to the v2 format, losslessly:
+ * - a tab's identity was its label (`nodName`), which becomes its `id`; v1
+ *   tab `uidNode`s were per-session and are dropped;
+ * - `nodPart` becomes `weight` (same meaning), so the layout renders
+ *   pixel-identically;
+ * - directions, implicit in v1 (the root is horizontal and every level flips),
+ *   become explicit;
+ * - `nodOpen`, `nodFold` and `nodMaxd` become `activeTabId`, `isFolded` and
+ *   `maximizedTabsetId`.
+ *
+ * Damaged input is repaired where possible (see the migration guide):
+ * duplicate tabs keep their first occurrence, unknown active tabs fall back to
+ * the first tab, empty tabsets and rows are removed, stray tabs are wrapped in
+ * a tabset, and the result is normalized.
+ *
+ * @param tree - The v1 layout (`DynamixLayoutCore._root.toJSON()`).
+ * @returns The equivalent v2 layout.
+ * @throws {DynamixLayoutError} `INVALID_LAYOUT` when `tree` is not a v1 layout.
+ * @example
+ * const saved = JSON.parse(localStorage.getItem('layout')!)
+ * const layout = isLayoutV1(saved) ? migrateLayoutFromV1(saved) : saved
+ */
+export declare function migrateLayoutFromV1(tree: LayoutTreeV1, options?: {
+    onWarning?: WarningHandler;
+}): LayoutJSON;
+
+/** A point in layout-root coordinates (the root's top-left corner is 0,0). */
+export declare interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+
+/** A rectangle in layout-root coordinates. */
+export declare interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+
+/** Size of the root-edge drop zones (v1 `RootSplitterHoverEl`). */
+export declare interface RootDropZoneOptions {
+    /** Share of the edge the zone covers. @default 0.25 */
+    readonly length?: number;
+    /** Thickness in px. @default 8 */
+    readonly thickness?: number;
+}
+
+/** A saved row. */
+export declare interface RowJSON {
+    type: 'row';
+    id: string;
+    /** Share of the parent's space above the minimum sizes (like CSS flex-grow). */
+    weight: number;
+    direction: Direction;
+    children: (RowJSON | TabsetJSON)[];
+}
+
+/** A row of tabsets and rows separated by splitters. */
+export declare interface RowNode {
+    readonly type: 'row';
+    readonly id: string;
+    /** See {@link TabsetNode.weight}. Ignored on the root. */
+    readonly weight: number;
+    readonly direction: Direction;
+    readonly children: readonly (RowNode | TabsetNode)[];
+}
+
+/** A side of a tabset or of the whole layout. */
+export declare type Side = 'top' | 'bottom' | 'left' | 'right';
+
+/** Splitter position and limits in px along its row. */
+export declare interface SplitterBounds {
+    /** Size of the panel before the splitter. */
+    readonly value: number;
+    readonly min: number;
+    readonly max: number;
+}
+
+/** Derived state of one splitter. */
+export declare interface SplitterState {
+    readonly id: string;
+    readonly rowId: string;
+    /** The row's direction: a `'horizontal'` row has a vertical splitter bar. */
+    readonly direction: Direction;
+    readonly beforeId: string;
+    readonly afterId: string;
+    /** Next to a folded tabset, so it can't be dragged. */
+    readonly isLocked: boolean;
+    readonly isHidden: boolean;
+}
+
+/** A tab bar and its tabs as rendered, in layout-root coordinates. */
+export declare interface TabBarMeasurement {
+    readonly rect: Rect;
+    /** Drawn as a rotated strip (a folded tabset in a side-by-side row). */
+    readonly isRotated?: boolean;
+    readonly tabs: readonly {
+        readonly id: string;
+        readonly rect: Rect;
+    }[];
+}
+
+/** Where a tabset's tab bar goes. */
+export declare interface TabBarPlacement {
+    /** Box to give the tab bar element before `isRotated` is applied. */
+    readonly rect: Rect;
+    /**
+     * A folded tabset in a side-by-side row shows its tab bar as a vertical
+     * strip: an element `height` wide and `width` tall, rotated 90° around its
+     * top-left corner and placed at the strip's right edge.
+     */
+    readonly isRotated: boolean;
+}
+
+/** A tab the layout should contain. */
+export declare interface TabInit {
+    /** Unique, stable id. It's also what saved layouts store. */
+    readonly id: string;
+    /** Where the tab goes the first time it appears. @default the last active tabset */
+    readonly target?: DropTarget;
+}
+
+/** A saved tab: only the id the application gave it. */
+export declare interface TabJSON {
+    type: 'tab';
+    id: string;
+}
+
+/** A tab. Its `id` is the id the application gave the tab. */
+export declare interface TabNode {
+    readonly type: 'tab';
+    readonly id: string;
+}
+
+/** A saved tabset. */
+export declare interface TabsetJSON {
+    type: 'tabset';
+    id: string;
+    weight: number;
+    activeTabId?: string;
+    /** Written only when true. */
+    isFolded?: boolean;
+    children: TabJSON[];
+}
+
+/** A group of tabs that shows one of them at a time. */
+export declare interface TabsetNode {
+    readonly type: 'tabset';
+    readonly id: string;
+    /**
+     * Share of the parent row's space above the minimum sizes, like CSS
+     * `flex-grow` with `flex-basis` set to the minimum size.
+     */
+    readonly weight: number;
+    /** Always the id of one of `children`. */
+    readonly activeTabId: string;
+    /** Folded to a strip along its row. */
+    readonly isFolded: boolean;
+    /** Never empty. */
+    readonly children: readonly TabNode[];
+}
+
+/** Derived state of one tabset. */
+export declare interface TabsetState {
+    readonly id: string;
+    readonly tabIds: readonly string[];
+    readonly activeTabId: string;
+    /** Direction of the row this tabset sits in. */
+    readonly parentDirection: Direction;
+    readonly isFolded: boolean;
+    readonly isMaximized: boolean;
+    /** Hidden because another tabset is maximized (its content stays mounted). */
+    readonly isHidden: boolean;
+    readonly canFold: boolean;
+    readonly canMaximize: boolean;
+}
+
+/** Derived state of one tab. */
+export declare interface TabState {
+    readonly id: string;
+    readonly tabsetId: string;
+    readonly isActive: boolean;
+    /** Active and its tabset neither folded nor hidden. */
+    readonly isVisible: boolean;
+}
+
+/**
+ * The version of this package, for debugging (replaces v1's console banner).
+ * @example
+ * console.info('dynamix-layout', version)
+ */
+export declare const version: string;
+
+/** Receives warnings. */
+export declare type WarningHandler = (warning: LayoutWarning) => void;
+
+export { }