@dashfoo/core 1.0.0 → 1.1.1

package/README.md

@@ -24,12 +24,12 @@ slipped into `config` fails parsing instead of corrupting a saved layout.
 
 ```ts
 type Dashfoo = {
-  version: number;
+  version: 1;
   global: GlobalAttributes;
   layout: RowNode; // the root is always a row
   activeTabsetId?: string;
   maximizedTabsetId?: string;
-  floats?: FloatNode[]; // floating panels, each its own layout subtree
+  floats: FloatNode[]; // floating panels, each its own layout subtree
 };
 ```
 
@@ -164,7 +164,7 @@ tree canonical so downstream code never has to defend against degenerate shapes:
 - simplifies a single-child row by lifting its lone child (which inherits the
   lifted row's weight, so sizing is preserved)
 - absorbs a root that reduces to a single nested row
-- clamps every `selected` index into range
+- preserves schema-normalized selection and weights (`parseModel` supplies defaults and clamps selection)
 - forces `activeTabsetId` / `maximizedTabsetId` to point at a tabset that exists
   (falling back to the first tabset, or clearing)
 - heals each floating panel's own layout and drops a float once it empties
@@ -183,10 +183,10 @@ getFirstTabset(model): TabsetNode | undefined;
 findTabset(model, tabsetId): TabsetNode | undefined;
 findTab(model, tabId): TabLocation | undefined; // searches tabsets
 findFloat(model, floatId): FloatNode | undefined;
-findRow(row, rowId): RowNode | undefined;       // pass a root (model.layout or a float's layout)
+findRow(model, rowId): RowNode | undefined;
 findRootContaining(model, nodeId): RowNode | undefined; // which root holds a node
 findAttributedNode(model, id): AttributedNode | undefined; // row, tabset, or tab
-findTabsetParent(row, tabsetId): { index: number; parent: RowNode } | undefined;
+findTabsetParent(model, tabsetId): { index: number; parent: RowNode } | undefined;
 findDuplicateIds(model): Array<string>;         // ids used more than once
 ```
 
@@ -210,8 +210,8 @@ import { reducer } from "@dashfoo/core";
 const floated = reducer(model, { type: "floatTabset", tabsetId: "left" });
 floated.floats; // [{ type: "float", id, layout: RowNode, geometry }]
 
-// Dock it back into the active main tabset (center) and drop the float.
-const docked = reducer(floated, { type: "dockFloat", floatId: floated.floats![0].id });
+// Dock it back as its own panel and drop the float.
+const docked = reducer(floated, { type: "dockFloat", floatId: floated.floats[0].id });
 ```
 
 `normalize` runs over each float's layout too and drops a float once its last
@@ -225,14 +225,14 @@ indicator rect. The @dnd-kit adapter in `@dashfoo/react` feeds them rects; you c
 call them directly for custom drag logic.
 
 ```ts
-resolveDockTarget(pointer, rect, opts?): DockTarget;
+resolveDockTarget(pointer, rect, opts?): DockLocation;
 dockZonePolygons(rect, opts?): Array<DockZone>;
 zoneRect(rect, location): Rect;
 ```
 
-`resolveDockTarget` decides where a drag over a tabset should land: `{ kind: "tab" }`
-when the pointer is in the interior, or `{ kind: "split", edge }` when it is within
-an outer band of one of the four edges (default 22%; the closer edge wins in
+`resolveDockTarget` decides where a drag over a tabset should land: `"center"`
+when the pointer is in the interior, or `split-${edge}` when it is within an
+outer band of one of the four edges (default 22%; the closer edge wins in
 corners). It accepts `{ bandFraction }` to tune the band. `zoneRect` returns the
 region the dock indicator highlights for a `DockLocation`: the whole tabset for a
 `center` stack, the matching half for a split. `Point` and `Rect` are exported.
@@ -251,19 +251,26 @@ it stays framework-free; the React adapter maps rrp's id-keyed layout to/from
 these arrays and supplies the dragged boundary index.
 
 ```ts
-resolveSnapTargets(config: SnapConfig, panelCount: number): number[]; // grid positions inside 0..100
-snapSizes(sizes: number[], boundaryIndex: number, config: SnapConfig): { sizes: number[]; snapped: boolean };
-snapEnabled(config: SnapConfig | null): boolean;
+// resolveSnapGrid(config, panelCount).targets contains positions inside 0..100
+resolveSnapGrid(config: SnapConfig | null, panelCount: number): SnapGrid;
+snapSizes(sizes: number[], boundaryIndex: number, grid: SnapGrid): { sizes: number[]; snapped: boolean };
+snapEnabled(grid: SnapGrid): boolean;
 ```
 
-`resolveSnapTargets` builds the grid for a row from its config and panel count: the
+`resolveSnapGrid` builds the grid for a row from its config and panel count: the
 union of the `step` grid (multiples of a fixed percent) and the `divisions` grid
 (even splits: multiples of `100/d`, where `d` is the number or, for `"panels"`,
 the panel count). `snapSizes` snaps the boundary between panel `boundaryIndex` and
 the next onto the nearest target within `threshold` (default `4`), moving only that
 pair so siblings keep their size. It is a no-op when the grid is empty, the index
-is out of range, or the correction would drive a panel negative. `snapEnabled`
-reports whether a config produces any grid. `SnapConfig` is the
+is out of range, or the correction would drive a panel negative.
+
+`resolveSnapGrid` is the entry point: it resolves the targets once for a row and
+carries the threshold alongside them, and every other function takes that
+`SnapGrid`. `snapEnabled` is then just "does this grid have any target", which
+is why a config with no reachable target (`{ step: 100 }`, or
+`{ divisions: "panels" }` on a one-panel row) reports off rather than arming the
+per-move snap path. `SnapConfig` is the
 `{ step?, divisions?, threshold? }` shape carried by `global.snap` and
 `RowNode.snap`.
 
@@ -330,7 +337,7 @@ const current = actor.getSnapshot().context.history.present;
 ### dragDockMachine
 
 The drag/dock interaction lifecycle (`idle` → `dragging` → `idle`), driven by
-abstract events the dnd-kit adapter maps from pointer and keyboard input. It owns
+abstract events the dnd-kit adapter maps from pointer input. It owns
 transient drag state only and never touches the document. On a valid `DROP` it
 **emits** a `COMMIT` carrying a `moveNode` action (the drag subject is a tab), a
 `moveTabset` action (the subject is a whole tabset, dragged by its grip), or an
@@ -350,7 +357,7 @@ layout, carrying the `TabNode` to insert), which the React layer forwards to
 `schema`: `dashfooSchema`, `rowNodeSchema`, `tabsetNodeSchema`, `tabNodeSchema`,
 `floatNodeSchema`, `geometrySchema`, `dimensionSchema`, `snapSchema`, `edgeSchema`,
 `unitSchema`, `orientationSchema`, `globalAttributesSchema`,
-`jsonValueSchema`; types `Dashfoo`, `RowNode`, `TabsetNode`, `TabNode`,
+`jsonValueSchema`, `tabsetNodeObjectSchema`; types `Dashfoo`, `DashfooInput`, `RowNodeInput`, `RowNode`, `TabsetNode`, `TabNode`,
 `FloatNode`, `Geometry`, `Dimension`, `SnapConfig`, `Edge`, `Unit`, `Orientation`,
 `GlobalAttributes`, `Node`, `Json`.
 
@@ -370,10 +377,10 @@ layout, carrying the `TabNode` to insert), which the React layer forwards to
 types `AttributedNode`, `TabContainer`, `TabLocation`.
 
 `geometry`: `resolveDockTarget`, `dockZonePolygons`, `zoneRect`; types
-`DockTarget`, `DockZone`, `BandOptions`, `Point`, `Rect`.
+`DockZone`, `BandOptions`, `Point`, `Rect`.
 
-`snap`: `resolveSnapTargets`, `snapSizes`, `snapEnabled`, `DEFAULT_SNAP_THRESHOLD`;
-type `SnapResult`.
+`snap`: `resolveSnapGrid`, `decideSnap`, `settleSnap`, `snapSizes`, `snapEnabled`, `DEFAULT_SNAP_THRESHOLD`;
+types `SnapResult`, `SnapGrid`, `SnapDecision`.
 
 `history`: `createHistory`, `dispatch`, `undo`, `redo`, `canUndo`, `canRedo`;
 type `History`.
@@ -384,7 +391,7 @@ type `History`.
 tabsets, the building block for a narrow-screen breakpoint).
 
 `machines`: `dashfooMachine`, `dragDockMachine`; types `DashfooContext`,
-`DashfooEvent`, `DashfooInput`, `DragContext`, `DragEvent`, `DragSubject`,
+`DashfooEvent`, `DragContext`, `DragEvent`, `DragSubject`,
 `DragEmitted`.
 
 ## License