@x1a0f3n9/dsh-client-ui-dockkit 0.1.5-rc.3

package/lib/types/engine/sequence.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Linear operation history over `applyOp`. Recording is total — every operation
+ * lands in the sequence, focus moves included — and grouped by intent: the
+ * operations one gesture or command produced form one entry, so stepping lands
+ * on a point the user actually stopped at. Stepping is coarser still across
+ * focus: a run of consecutive focus-only entries undoes and redoes as one step.
+ *
+ * Redoing re-applies the recorded operations; undoing applies the inverses that
+ * were captured when they ran, so both directions stay exact. A new entry after
+ * an undo drops the redo branch.
+ *
+ * Two shapes, one implementation. `record`/`stepBack`/`stepForward` are pure
+ * functions over a plain `History`, which is what an embedder holding its layout
+ * in an external store needs; `Sequencer` is a thin mutable wrapper over exactly
+ * those functions, for an embedder that would rather hold the state here.
+ */
+import type { LayoutOp, LayoutState } from '../contract/types.ts';
+/** One recorded intent: its operations, and the operations that undo them all. */
+export interface HistoryEntry {
+    readonly ops: readonly LayoutOp[];
+    /** Already ordered for application: the last operation's inverse comes first. */
+    readonly inverse: readonly LayoutOp[];
+}
+/** A recorded sequence and how much of it is applied. Plain data, safe to store. */
+export interface History {
+    readonly entries: readonly HistoryEntry[];
+    /** How many entries are applied; entries beyond it are the redo branch. */
+    readonly cursor: number;
+}
+/** A sequence that has recorded nothing. */
+export declare const EMPTY_HISTORY: History;
+/** A history and the state it produced, returned together so neither can drift. */
+export interface HistoryStep {
+    readonly history: History;
+    readonly state: LayoutState;
+}
+/**
+ * Whether an operation only moves focus, and so merges into its neighbours' undo step.
+ * @param op - the operation.
+ * @returns whether its type is a `FocusOpType`.
+ */
+export declare function isFocusOp(op: LayoutOp): boolean;
+/**
+ * Whether a step back exists.
+ * @param history - the sequence so far.
+ * @returns whether any entry is applied.
+ */
+export declare function canStepBack(history: History): boolean;
+/**
+ * Whether a step forward exists.
+ * @param history - the sequence so far.
+ * @returns whether a redo branch remains.
+ */
+export declare function canStepForward(history: History): boolean;
+/**
+ * The operations a sequence has recorded, redo branch included.
+ * @param history - the sequence so far.
+ * @returns every entry's operations, in recorded order.
+ */
+export declare function recordedOps(history: History): readonly LayoutOp[];
+/**
+ * Apply one intent's operations and record them as one entry, dropping any redo
+ * branch first. An intent with no operations records nothing.
+ * @param history - the sequence so far.
+ * @param state - the state the operations apply to.
+ * @param ops - the intent's operations, in application order.
+ * @returns the extended history and the state after the operations.
+ * @throws when an operation is invalid against the state it reaches; nothing is
+ *   recorded.
+ */
+export declare function record(history: History, state: LayoutState, ops: readonly LayoutOp[]): HistoryStep;
+/**
+ * Step back one intent, or one whole run of consecutive focus-only intents.
+ * @param history - the sequence so far.
+ * @param state - the current state.
+ * @returns the stepped-back pair, or `undefined` when nothing can be undone.
+ */
+export declare function stepBack(history: History, state: LayoutState): HistoryStep | undefined;
+/**
+ * Step forward over the intents the matching step back undid.
+ * @param history - the sequence so far.
+ * @param state - the current state.
+ * @returns the stepped-forward pair, or `undefined` when nothing can be redone.
+ */
+export declare function stepForward(history: History, state: LayoutState): HistoryStep | undefined;
+/** Layout state plus its history cursor, held here instead of by the embedder. */
+export declare class Sequencer {
+    private current;
+    private recorded;
+    /** @param initial - state the sequence replays from; never mutated. */
+    constructor(initial: LayoutState);
+    /** Current state. */
+    get state(): LayoutState;
+    /** The recorded sequence as plain data. */
+    get history(): History;
+    /** The whole recorded sequence, including a redo branch that is not applied. */
+    get ops(): readonly LayoutOp[];
+    /** How many recorded operations are currently applied. */
+    get cursor(): number;
+    /** Whether a step back exists. */
+    get canUndo(): boolean;
+    /** Whether a step forward exists. */
+    get canRedo(): boolean;
+    /**
+     * Apply and record one operation as its own entry, dropping any redo branch first.
+     * @param op - the operation to record.
+     * @returns the state after it.
+     * @throws when the operation is invalid against the current state; the
+     *   sequence is left untouched.
+     */
+    dispatch(op: LayoutOp): LayoutState;
+    /**
+     * Apply and record one intent's operations as one entry, dropping any redo
+     * branch first.
+     * @param ops - the intent's operations; none records nothing.
+     * @returns the state after them.
+     * @throws when an operation is invalid; the sequence is left untouched.
+     */
+    dispatchAll(ops: readonly LayoutOp[]): LayoutState;
+    /**
+     * Step back one intent, or one whole run of consecutive focus-only intents.
+     * @returns false when there is nothing to undo.
+     */
+    undo(): boolean;
+    /**
+     * Step forward over the intents the matching undo stepped back.
+     * @returns false when there is nothing to redo.
+     */
+    redo(): boolean;
+}
+//# sourceMappingURL=sequence.d.ts.map

package/lib/types/engine/tree.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Pure tree helpers over `LayoutState`. Every reader throws on a dangling id
+ * (the operation vocabulary is closed, so a miss is a caller defect), and every
+ * writer returns a new state that keeps untouched nodes at their old identity.
+ */
+import type { FloatRect, LayoutNode, LayoutState, NodeId, PaneId, PaneNode, SplitNode, TabId, TabRecord } from '../contract/types.ts';
+/**
+ * Reject an unhandled discriminant at the end of a closed switch.
+ * @param value - the discriminant the switch did not handle.
+ * @param what - the union being switched on, for the message.
+ * @returns never; it throws.
+ */
+export declare function assertNever(value: never, what: string): never;
+/**
+ * Read any node.
+ * @param state - current layout.
+ * @param id - the node.
+ * @returns the split or pane.
+ * @throws when `id` is not in the tree.
+ */
+export declare function getNode(state: LayoutState, id: NodeId): LayoutNode;
+/**
+ * Read a pane.
+ * @param state - current layout.
+ * @param id - the pane.
+ * @returns the pane node.
+ * @throws when `id` is missing or names a split.
+ */
+export declare function getPane(state: LayoutState, id: NodeId): PaneNode;
+/**
+ * Read a split.
+ * @param state - current layout.
+ * @param id - the split.
+ * @returns the split node.
+ * @throws when `id` is missing or names a pane.
+ */
+export declare function getSplit(state: LayoutState, id: NodeId): SplitNode;
+/**
+ * Read a tab record.
+ * @param state - current layout.
+ * @param id - the tab.
+ * @returns the record.
+ * @throws when `id` is not open.
+ */
+export declare function getTab(state: LayoutState, id: TabId): TabRecord;
+/**
+ * A floating pane's rectangle.
+ * @param pane - the pane.
+ * @returns its viewport rectangle.
+ * @throws when `pane` is docked.
+ */
+export declare function floatRect(pane: PaneNode): FloatRect;
+/**
+ * A floating pane's position in the z order.
+ * @param state - current layout.
+ * @param id - the floating pane.
+ * @returns its index in `floats`, bottom first.
+ * @throws when `id` is not listed in `floats`.
+ */
+export declare function floatIndex(state: LayoutState, id: PaneId): number;
+/**
+ * The one tab a pane holds.
+ * @param pane - the pane.
+ * @returns its tab's id.
+ * @throws when `pane` holds any other number of tabs.
+ */
+export declare function onlyTabId(pane: PaneNode): TabId;
+/**
+ * The split holding a node.
+ * @param state - current layout.
+ * @param id - the node.
+ * @returns its parent split, or `undefined` for the docked root and floating panes.
+ */
+export declare function findParent(state: LayoutState, id: NodeId): SplitNode | undefined;
+/**
+ * The pane holding a tab.
+ * @param state - current layout.
+ * @param tabId - the tab.
+ * @returns the pane whose strip lists it.
+ * @throws when no pane lists it.
+ */
+export declare function findTabPane(state: LayoutState, tabId: TabId): PaneNode;
+/**
+ * Docked pane ids in visual order (depth-first through the split tree).
+ * @param state - current layout.
+ * @returns every docked pane's id; floating panes are absent.
+ */
+export declare function dockPaneIds(state: LayoutState): PaneId[];
+/**
+ * Scale `sizes` so they sum to 1. Input that already sums to 1 is copied
+ * unchanged, so restoring recorded sizes never drifts.
+ * @param sizes - fractions or any positive weights.
+ * @returns the fractions, summing to 1.
+ * @throws when the input cannot be normalized.
+ */
+export declare function normalizeSizes(sizes: readonly number[]): number[];
+/**
+ * `Object.entries` keeping the record's own key type: the keys were written from
+ * ids, so reading them back as ids is exact.
+ * @param record - an id-keyed record.
+ * @returns its entries with typed keys.
+ */
+export declare function entriesOf<K extends string, V>(record: Readonly<Record<K, V>>): readonly (readonly [K, V])[];
+/**
+ * `Object.keys` keeping the record's own key type; see {@link entriesOf}.
+ * @param record - an id-keyed record.
+ * @returns its keys, typed.
+ */
+export declare function keysOf<K extends string>(record: Readonly<Record<K, unknown>>): readonly K[];
+/**
+ * Replace or delete nodes.
+ * @param state - current layout.
+ * @param updates - nodes by id; a `null` update deletes that id.
+ * @returns the layout with those nodes replaced; untouched nodes keep their identity.
+ */
+export declare function withNodes(state: LayoutState, updates: Readonly<Record<NodeId, LayoutNode | null>>): LayoutState;
+/**
+ * Replace or delete tab records.
+ * @param state - current layout.
+ * @param updates - records by id; a `null` update deletes that id.
+ * @returns the layout with those records replaced; untouched records keep their identity.
+ */
+export declare function withTabs(state: LayoutState, updates: Readonly<Record<TabId, TabRecord | null>>): LayoutState;
+/**
+ * Insert a value into a list.
+ * @param items - the list.
+ * @param index - the slot, clamped to the list's bounds.
+ * @param value - what to insert.
+ * @returns a new list with the value at the slot.
+ */
+export declare function insertAt<T>(items: readonly T[], index: number, value: T): T[];
+/**
+ * Remove one entry from a list.
+ * @param items - the list.
+ * @param index - the entry to drop.
+ * @returns a new list without it.
+ */
+export declare function removeAt<T>(items: readonly T[], index: number): T[];
+/**
+ * Which tab a pane focuses after one leaves it.
+ * @param tabs - the strip before the removal.
+ * @param removedIndex - the leaving tab's slot.
+ * @returns the previous neighbour when one exists, otherwise the next, otherwise `undefined`.
+ */
+export declare function neighbourTabId(tabs: readonly TabId[], removedIndex: number): TabId | undefined;
+/**
+ * Copy a pane with a new tab list.
+ * @param pane - the pane.
+ * @param tabs - its new strip.
+ * @param activeTabId - the active tab, which the caller keeps consistent with `tabs`.
+ * @returns the copied pane.
+ */
+export declare function paneWithTabs(pane: PaneNode, tabs: readonly TabId[], activeTabId: TabId | undefined): PaneNode;
+/**
+ * Swap a node for another in its parent's slot, or make the replacement the docked root.
+ * @param state - current layout.
+ * @param targetId - the node to swap out.
+ * @param replacementId - the node taking its slot.
+ * @returns the layout with the slot rewritten.
+ * @throws when `targetId` is neither rooted nor parented.
+ */
+export declare function replaceInParent(state: LayoutState, targetId: NodeId, replacementId: NodeId): LayoutState;
+/**
+ * The first docked pane in visual order: the docked root, or the first leaf
+ * under it. Focus falls back here when the focused pane is removed, and a new
+ * tab lands here when the focused pane floats.
+ * @param state - current layout.
+ * @returns the first docked pane's id.
+ */
+export declare function firstDockPaneId(state: LayoutState): PaneId;
+/**
+ * The docked pane in the top-right corner: from the root, the last child of
+ * every row split and the first child of every column split. Its tab strip is
+ * where an embedder's surface-wide controls sit, so they read as the surface's
+ * own top-right corner however the tree is divided.
+ * @param state - current layout.
+ * @returns the top-right docked pane's id.
+ */
+export declare function topRightPaneId(state: LayoutState): PaneId;
+//# sourceMappingURL=tree.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A docking layout kit: a split tree of tabbed panes with invertible operations,
+ * and the React components that render and drive it.
+ *
+ * Two layers, and the boundary between them is the point of the package. The
+ * engine (`applyOp`, `Sequencer`, `DockController`) is pure TypeScript with no
+ * React, no DOM, and no host concepts; replaying a recorded sequence over the
+ * same initial state reproduces the same tree, because every operation carries
+ * the ids it creates. The components render a layout snapshot and report settled
+ * intents — one per gesture, never a drag frame — so the embedder's sequence
+ * stays the single source of truth.
+ *
+ * Nothing host-specific lives here: rendered strings arrive as `DockLabels`, tab
+ * bodies as a `TabRenderer`, and a tab's `kind` is an opaque string this kit
+ * never interprets.
+ *
+ * @module
+ */
+export type { ApplyResult, DockMode, DockZone, FloatRect, LayoutNode, LayoutOp, LayoutState, NodeId, PaneAttachment, PaneHost, PaneId, PaneNode, SplitAxis, SplitDirection, SplitId, SplitNode, TabId, TabRecord, } from './contract/types.ts';
+export { applyOp, replay } from './engine/operations.ts';
+export { canStepBack, canStepForward, EMPTY_HISTORY, isFocusOp, record, recordedOps, Sequencer, stepBack, stepForward, } from './engine/sequence.ts';
+export type { History, HistoryEntry, HistoryStep } from './engine/sequence.ts';
+export { dockPaneIds, findParent, findTabPane, getNode, getPane, getSplit, getTab, topRightPaneId, } from './engine/tree.ts';
+export { canSplit, clampSizes, DOCK_EDGE_FRACTION, DOCK_ZONES, dockPaneCount, FLOAT_DEFAULT_SIZE, FLOAT_MIN_SIZE, MAX_DOCK_PANES, MIN_PANE_FRACTION, zoneAt, zoneSplit, } from './engine/constraints.ts';
+export { containsPoint, dividerSizes, DRAG_THRESHOLD, floatRectAt, halvesFit, insertionIndex, movedRect, passedThreshold, resizedRect, SPLIT_MINIMUMS, zoneInRect, } from './engine/geometry.ts';
+export type { DropTarget, HalvesFit, PaneMeasure, Rect, Size, SplitMinimums } from './engine/geometry.ts';
+export { activeDockPaneId, findContentTab, findPaneContentTab, planAddTab, planDropTab, planDuplicateTab, planFloatTab, planOpenContent, planPlaceTab, planResizeSplit, planSetExpanded, planSetMode, planSettle, planSplitPane, planUnfloatPane, } from './engine/planner.ts';
+export type { Mint, OpenContentInput, PlannedTab } from './engine/planner.ts';
+export { DockController } from './engine/controller.ts';
+export type { DockControllerOptions, DockSnapshot } from './engine/controller.ts';
+export { createIdMinter, createInitialState } from './engine/initial.ts';
+export type { IdMinter, TabFactory } from './engine/initial.ts';
+export type { DockIntents, DockLabels, TabMenuExtras, TabRenderer } from './contract/adapter.ts';
+export { DockSurface } from './components/DockSurface.tsx';
+export type { DockSurfaceProps } from './components/DockSurface.tsx';
+export { FloatLayer } from './components/FloatLayer.tsx';
+export type { FloatLayerProps } from './components/FloatLayer.tsx';
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@x1a0f3n9/dsh-client-ui-dockkit",
+  "description": "Docking layout kit: split-tree engine with invertible operations, and the React components that render and drive it (zero cordis)",
+  "version": "0.1.5-rc.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-dockkit"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "react-dom": "^18.2.0",
+    "react": "^18.2.0",
+    "clsx": "^2.0.0",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@x1a0f3n9/dsh-brand": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-client-ui-primitives": "^0.1.5-rc.3"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/**/*.css",
+    "lib/types/**/*.d.ts"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  }
+}