@dimina-kit/electron-deck 0.1.0-dev.20260616024534 → 0.1.0-dev.20260616102751

package/README.md

@@ -14,6 +14,8 @@ Dimina devtools 的 host 集成地基。提供：连接层（per-webContents 的
 | `defineEvent` / `DeckConfig` 等类型 | `@dimina-kit/electron-deck` |
 | preload bridge `exposeDeckBridge()` | `@dimina-kit/electron-deck/preload` |
 | renderer client `createDeckClient<HS, EV>()` | `@dimina-kit/electron-deck/client` |
+| layout-as-data 引擎（`SplitNode`/`TabGroupNode` 树、`movePanel`/`splitPanel`/`closePanel`/`setActive`/`setSizes` 等 mutation、`serializeLayout`/`parseLayout`/`validateTree`、`createLayoutModel` 单写者可观察模型、panel registry） | `@dimina-kit/electron-deck/layout` |
+| `<DockView>` React 渲染器（把 layout 树渲染成可拖拽 re-dock / tab / 分屏的 docking UI） | `@dimina-kit/electron-deck/dock-react` |
 
 ## 最小例子
 

package/dist/dock-react/dock-view.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `<DockView>` — React renderer for a layout-as-data tree.
+ *
+ * Pure function of the current model snapshot (+ registry + the two host
+ * callbacks). It owns NO layout state: it subscribes to the `LayoutModel`,
+ * keeps the latest tree in component state, and re-renders on every emission.
+ * All structural targeting is via STABLE `data-*` attributes — see the
+ * contract doc-block in `dock-view.test.tsx`.
+ *
+ * This file lives under `src/dock-react/` (NOT `src/layout/`), so importing
+ * react here does not violate the pure-TS layout boundary.
+ */
+import { type ReactNode } from 'react';
+import type { LayoutModel, PanelRegistry } from '../layout/index.js';
+export interface DockViewProps {
+    model: LayoutModel;
+    registry: PanelRegistry;
+    /**
+     * Render a DOM panel's body. `opts.active` is `true` iff `panelId` is its tab
+     * group's currently-active panel. Under DOM-panel keepalive every DOM panel in
+     * a group is rendered (the inactive ones hidden), so this callback is invoked
+     * for ALL of them and `opts.active` is RE-EVALUATED on every activation change
+     * WITHOUT remounting the kept-alive subtree — letting a host run on-activation
+     * side effects (e.g. data refresh) off the false→true `active` edge.
+     */
+    renderDomPanel: (panelId: string, opts: {
+        active: boolean;
+    }) => ReactNode;
+    bindNativeSlot: (panelId: string, el: HTMLElement | null) => void;
+}
+/**
+ * Compute the `defaultSize` percentage for each FLEXIBLE (unconstrained) child,
+ * keyed by its ORIGINAL child index. Fixed (px-pinned) children are excluded
+ * from the pool entirely so their weight never pollutes the flexible siblings'
+ * normalization (FIX E1). `constraints[i]` non-null ⇒ child i is fixed and is
+ * absent from the returned map.
+ */
+export declare function computeFlexiblePercentages(sizes: readonly number[], constraints: readonly ({
+    fixedPx: number;
+} | null)[] | undefined): Map<number, number>;
+export declare function DockView(props: DockViewProps): ReactNode;
+/** Are two panelId→percentage maps equivalent within `epsilon` percentage
+ * points? Both maps must cover EXACTLY the `ids` key set — a missing key OR an
+ * extra key (a key present in `a`/`b` but absent from `ids`) counts as NOT
+ * equivalent so the sync is not falsely suppressed. A non-finite value
+ * (NaN/±Infinity) is likewise NOT equivalent — `typeof NaN === 'number'` and
+ * `Math.abs(NaN - x) > eps` is `false`, so without the `Number.isFinite` guard a
+ * NaN would slip through as "equivalent" and wrongly suppress a legitimate
+ * sync/write-back (N1). EXPORTED (pure) for direct unit coverage. */
+export declare function layoutsEquivalent(a: Record<string, number>, b: Record<string, number>, ids: readonly string[], epsilon?: number): boolean;
+//# sourceMappingURL=dock-view.d.ts.map

package/dist/dock-react/dock-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dock-view.d.ts","sourceRoot":"","sources":["../../src/dock-react/dock-view.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAON,KAAK,SAAS,EACd,MAAM,OAAO,CAAA;AAId,OAAO,KAAK,EACX,WAAW,EAGX,aAAa,EAIb,MAAM,oBAAoB,CAAA;AAgB3B,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,WAAW,CAAA;IAClB,QAAQ,EAAE,aAAa,CAAA;IACvB;;;;;;;OAOG;IACH,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,KAAK,SAAS,CAAA;IACzE,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAA;CACjE;AAaD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACzC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,WAAW,EAAE,SAAS,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,EAAE,GAAG,SAAS,GAC9D,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAUrB;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CA6GxD;AA4GD;;;;;;;qEAOqE;AACrE,wBAAgB,iBAAiB,CAChC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACzB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACzB,GAAG,EAAE,SAAS,MAAM,EAAE,EACtB,OAAO,GAAE,MAAuB,GAC9B,OAAO,CAaT"}

package/dist/dock-react/drag-redock.d.ts

@@ -0,0 +1,95 @@
+/**
+ * `drag-redock` — PURE geometry + descriptor layer for tab drag-to-redock.
+ *
+ * This module is intentionally REACT-FREE and ELECTRON-FREE so it can run under
+ * the node `vitest.config.ts` suite (its spec is `drag-redock.test.ts`). It owns
+ * two responsibilities, both pure functions of their inputs:
+ *
+ *   1. GEOMETRY — `computeDropZone(rect, point)` maps a pointer position over a
+ *      group's rectangle to one of five drop zones (the four edge bands plus the
+ *      interior `center`). This is the only place edge-band math lives; the React
+ *      layer feeds it real `getBoundingClientRect` numbers during dragover.
+ *
+ *   2. DESCRIPTOR — `dropZoneToMutation(zone, dragged, target)` translates a zone
+ *      into an engine-NEUTRAL `RedockMutation` intent (`move` | `split`). The
+ *      descriptor only NAMES the intent; the React layer realizes it against the
+ *      real tree (a split of an EXISTING panel needs extract-then-split, because
+ *      `splitPanel` throws if the new panel already exists — see the caller).
+ *
+ * Keeping this split (geometry/descriptor here, engine application in React)
+ * means the geometry is exhaustively unit-testable without a DOM, and the React
+ * layer stays a thin gesture binding.
+ */
+/** The five drop zones: four edge bands + the tab-joining interior. */
+export type DropZone = 'left' | 'right' | 'top' | 'bottom' | 'center';
+/**
+ * Engine-neutral re-dock INTENT. `move` joins the dragged panel into a tab
+ * group; `split` puts it adjacent to a target panel in a new split. This is a
+ * pure descriptor — it does NOT itself touch a tree (the caller applies it,
+ * extract-then-split'ing for an existing panel).
+ */
+export type RedockMutation = {
+    kind: 'move';
+    panelId: string;
+    destGroupId: string;
+} | {
+    kind: 'split';
+    atPanelId: string;
+    dir: 'row' | 'column';
+    side: 'before' | 'after';
+    newPanelId: string;
+};
+/**
+ * Classify a pointer position (RELATIVE to the rect's top-left; `(0,0)` is the
+ * corner) into a drop zone.
+ *
+ * Band thickness = `edgeFraction * min(width, height)` — a single symmetric band
+ * width derived from the SHORTER side so a wide/short panel doesn't get an
+ * absurdly fat horizontal band. A point in NO band is `center` (the tab-join
+ * interior). A point in TWO bands (a corner) tie-breaks by NORMALIZED distance
+ * to each active edge; on an exact tie HORIZONTAL wins. A point OUTSIDE the rect
+ * clamps to the nearest edge zone (per-axis; diagonal corners pick the larger
+ * overshoot, horizontal breaking ties).
+ */
+export declare function computeDropZone(rect: {
+    width: number;
+    height: number;
+}, point: {
+    x: number;
+    y: number;
+}, edgeFraction?: number): DropZone;
+/**
+ * Translate a drop zone into an engine-neutral re-dock descriptor.
+ *
+ *   center => move the dragged panel into the target's tab group.
+ *   left/right => split the target panel horizontally (row), dragged before/after.
+ *   top/bottom => split the target panel vertically (column), dragged before/after.
+ */
+export declare function dropZoneToMutation(zone: DropZone, dragged: string, target: {
+    groupId: string;
+    panelId: string;
+}): RedockMutation;
+/**
+ * A re-dock is a NO-OP when it would not change the tree:
+ *
+ *   1. The drop targets the dragged panel ITSELF (`dragged === target.panelId`),
+ *      in ANY zone — you can neither tab a panel onto its own tab nor split a
+ *      panel around itself. Crucially this also guards the SPLIT case: without
+ *      it, `extractPanel(dragged)` then `splitPanel(atPanelId = dragged)` removes
+ *      the very anchor it then splits at and THROWS (the self-collapse / single-
+ *      panel-self-split bug).
+ *   2. A `center` drop into a group the dragged panel ALREADY lives in
+ *      (`draggedGroupId === target.groupId`) — `movePanel` would re-append it and
+ *      bump the revision for no visible change (churn).
+ *
+ * A SPLIT onto a DIFFERENT panel of the dragged panel's own group is still a real
+ * re-dock (it splits the group around that sibling), so it is NOT a no-op.
+ *
+ * `draggedGroupId` is the id of the tab group currently holding `dragged`
+ * (`undefined` if it is not in the tree).
+ */
+export declare function isNoopRedock(dragged: string, draggedGroupId: string | undefined, target: {
+    groupId: string;
+    panelId: string;
+}, zone: DropZone): boolean;
+//# sourceMappingURL=drag-redock.d.ts.map

package/dist/dock-react/drag-redock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drag-redock.d.ts","sourceRoot":"","sources":["../../src/dock-react/drag-redock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,uEAAuE;AACvE,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAErE;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACtD;IACD,IAAI,EAAE,OAAO,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,GAAG,EAAE,KAAK,GAAG,QAAQ,CAAA;IACrB,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;CAClB,CAAA;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC9B,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EACvC,KAAK,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAC/B,YAAY,SAAO,GACjB,QAAQ,CAmEV;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC1C,cAAc,CAOhB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC3B,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAC5C,IAAI,EAAE,QAAQ,GACZ,OAAO,CAMT"}

package/dist/dock-react/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * dock-react public entry.
+ *
+ * `<DockView>` renders a docking layout from a `LayoutModel` (observable) +
+ * `PanelRegistry` (panelId -> descriptor). See `dock-view.test.tsx` for the
+ * `data-*` contract.
+ */
+export { DockView, computeFlexiblePercentages, layoutsEquivalent } from './dock-view.js';
+export type { DockViewProps } from './dock-view.js';
+export { computeDropZone, dropZoneToMutation, isNoopRedock } from './drag-redock.js';
+export type { DropZone, RedockMutation } from './drag-redock.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/dock-react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dock-react/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,QAAQ,EAAE,0BAA0B,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AACxF,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAInD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpF,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA"}