@n-uf/placement 26.11.11 → 26.11.13

package/CHANGELOG.md

@@ -3,6 +3,62 @@
 Versions are calendar versions, `YY.M.R` (year, month of the release, counter within the month), shared with
 `@n-uf/motion`: both packages carry the same version, and a release bumps both.
 
+## 26.11.13
+
+- `@n-uf/placement/stack`, floats (new exports; `fitStack`, `stackTargets` and the stack's stored form are unchanged, and
+  so are `./panels`, `./dock` and `./desk`). A float is an item above the pages, in the stage's own px (view space), so
+  the pages scrolling under it never move it; it has no pinned flag.
+  - `fitFloat(rect, stage, avoid?)`: the float's rect moved (never resized) inside the stage, then beside the docked
+    items it would cover, at the nearest clear place; `FloatFit` has `rect`, `clamped` (also when a position that wasn't a
+    number was replaced), `snapped`, `covers` (indexes into `avoid` it still covers; empty whenever a clear place exists,
+    which it finds, and not empty only when the stage has none) and `searchCapped`. A float larger than the stage keeps
+    its top-left corner on the stage's. The x's are tried nearest first and, for each, the stretches of y the rects
+    block are merged and skipped. Measured in a test run on a laptop: about 100 `avoid` rects 0.1 ms, 300 a few ms even
+    when no place is clear (6 ms median, 15 ms worst), 1,000 about 17 ms. A safety net stops the clear search after 3
+    million rect tests and sets `searchCapped` (the place found may then not be the nearest, or a clear place may exist that was not found); with no clear place
+    the least covered among the 2,048 nearest places is used.
+  - `stackFloatTarget({ id, stage, size, avoid?, label? })`: a free, priority 3 drop target in the shape
+    `@n-uf/motion/drag` takes, `kind: "float"`, id `float:<id>` (so it can't collide with `./desk`'s `"float"`; the
+    toolbar `floatTarget` in `./targets` keeps its name), whose `hit` covers the whole plane, so a pointer past the
+    stage's edge still hits it. `make(point, grab?)` gives the float's rect (clamped, clear of the docked items) for the
+    preview and for the drop: one answer, so a drop past the edge lands clamped and never cancels. A gap's `hit`
+    thinner than 8 px (twice the intent's 4 px breakthrough) can't take over from it.
+  - `storeFloats` / `readFloats`: `{ v: 1, floats: [{ id, x, y, width, height }] }` in stacking order; never throws,
+    drops what it can't use and lists it in `dropped`. `storeFloats` leaves out a float with a zero size or a bad number,
+    and of a repeated id keeps the last readable entry (the one on top); `readFloats` does the same and words a bad
+    version as the stack's reader does. It writes no `pinned`; one an old store has is read and ignored (listed as
+    `pinned:<id>`), and the float loads as a plain float.
+  - Exports: `fitFloat`, `stackFloatTarget`, `storeFloats`, `readFloats` and the types `StackFloat`, `FloatFit`,
+    `FloatTarget`, `StackFloatTargetInput`, `FloatDrop`, `StoredFloats`, `FloatsRead`.
+
+## 26.11.12
+
+- New entry `@n-uf/placement/stack`: the items along one edge of a stage (a column or a row), each a panel or a control
+  group with forms from largest to smallest. Pure, and not tied to `./panels` columns; `./panels`, `./dock` and `./desk`
+  are unchanged.
+  - `fitStack(input)`: one form, kind and rect per item. Every item starts in its largest form, or at `StackItem.from`.
+    While the smallest sizes don't fit the length, the item used longest ago (unkept before `kept`, the later in the
+    stack on a tie) takes its next form, panel `open` → `header` → `rail` → `menu`, group `row` → `stacked` → `icons`
+    → `menu`; it doesn't go into the menu when that only lengthens a stack nothing else can shorten (`overflow`).
+    Spare length goes to the forms that `grows`, shared by their natural sizes. The stack's cross size is the widest
+    form that `setsCross` (a panel's `open`, by default), clamped, else the rail width (30).
+  - Cross-fit: a form that doesn't set the cross size and whose `cross.min` (default `cross.natural`) is over the
+    stack's takes its next form: a group alone is a rail of icons, a column with nothing open shrinks to a rail, and a
+    header with a small `cross.min` stays in a narrower column. It never steps an item into the menu: the item keeps
+    its last drawn form and a `too-wide` note says so. An item with no forms is left out (`no-forms`).
+  - Result: `items` (`form` and `from`/`to` in notes are indexes into the item's forms), `cross`, `menu` (the » entry's
+    rect and the ids in it) and coded `notes` (`form-down`, `to-menu`, `too-wide`, `no-forms`, `overflow`).
+  - `stackTargets(input, dragged)`: a drop target for every gap (before each item and after the last; the dragged id is
+    lifted out of the input first), in the shape `@n-uf/motion/drag` takes: `gap:<k>`, priority 2, `place`, `hit` (split
+    at the items' middles, across as wide as the larger of the stack and the drop's fit), `slot`, `marker` and the full
+    `fit` of the stack with the item inserted, so the preview is exactly the rect after the drop. `place.at` counts the
+    input's items, not `fit.items` (which leaves out an item with no forms): look the dragged item up in it by id.
+  - `storeStack` / `readStack` (`{ v: 1, order, kept, closed, used, forms }`): never throws, drops what it can't use
+    (including the `__proto__` key in `forms`, an object with no prototype) and lists it; an id listed twice in `used`
+    counts at its last place.
+  - Exports: `fitStack`, `stackTargets`, `withItem`, `formSetsCross`, `storeStack`, `readStack`, `createStack`,
+    `DEFAULT_RAIL`, `DEFAULT_MENU` and their types (`StackAxis`, `StackForm`, `StackItem`, `StackInput`, `StackFit`, …).
+
 ## 26.11.11
 
 - `@n-uf/placement/panels`, drops into a stacked column at a position (opt-in; without it every target is what it was):

package/README.md

@@ -40,6 +40,11 @@ without importing each other: a target list from `@n-uf/placement/targets` is ex
   room kept clear for a toolbar the app draws; their drop targets; and a stored form.
 - **`/desk`**: desk presets (`docks`, `docksFull`, `dockTear`, `navigator`) as data on `/panels`: options and a
   start state.
+- **`/stack`**: the items along one edge, a column or a bar, each a panel or a control group with forms from largest to
+  smallest (open, header, rail icon, » menu; row, stacked, icons, » menu): one form and rect per item, giving way by
+  age, spare room to the panels that grow, a rail when nothing open sets the width; a drop target for every gap, each
+  with the exact solve a drop makes; a stored form; and floats (an item above the pages, in the stage's own px, kept
+  inside the stage and clear of the docked items, with its drop target and stored form). Not tied to `/panels`.
 
 Rendering stays in the app: it draws the rects, measures its groups, and feeds pointer samples to a drag intent.
 
@@ -402,6 +407,159 @@ console.log(targets.some((t) => t.id === "float")); // false
 the same way, offering only the places the preset allows (`presetInput` gives that input). `./dock` stays as it is for
 now.
 
+## Edge stacks
+
+`@n-uf/placement/stack` lays out the items along one edge of a stage: a column (`axis: "column"`, a side region) or a
+row (`"row"`, a bar). An item is a panel or a control group and declares its forms, largest first. Each form has a
+structural `kind` (a panel's `open`, `header`, `rail`, `menu`; a group's `row`, `stacked`, `icons`, `menu`), a `main`
+size along the stack (`min`, `natural`, `grows`) and a `cross` size. `fitStack(input)` picks one form per item and
+places them; it is not tied to `./panels` columns, and nothing in it is a word.
+
+- Every item starts in its largest form, or at `from` (an index into its forms; a panel the user folded by hand
+  starts at its header). While the smallest sizes don't fit the `length`, the item used longest ago (`used`: the
+  smaller, the older) takes its next form; unkept before `kept`, the later in the stack first on a tie. It keeps giving
+  way until its forms end, then the next item does. A `menu` form takes no room: the » entry does (`menu.main`,
+  default 28 px), while any item is in it; an item doesn't go into the menu when that only makes the stack longer and
+  nothing else can give way (`overflow`).
+- Spare length goes to the forms that `grows`, shared by their natural sizes. With none, the items keep their
+  natural sizes from the start of the stack.
+- The stack's cross size is the widest `cross.natural` among the forms that set it (a panel's `open`, by default;
+  `setsCross` overrides), clamped to `cross.min` and `max`. With none it is the rail, `cross.rail` (default 30 px).
+- Cross-fit: a form that doesn't set the cross size and whose `cross.min` (default its `natural`) is over the stack's
+  takes its next form, so a group alone is a rail of icons and a column with nothing open shrinks to a rail. Give a
+  header a small `cross.min` and it stays in a column an open panel made narrower. Cross size never puts an item in
+  the menu: an item that is still too wide in its last drawn form keeps it, and `too-wide` says so (the app clips it).
+  Cross-fit and give-way repeat until nothing changes, because a panel folding can narrow the column.
+- The solver has no open or closed state: it lays out the items it is given. An item with no forms is left out
+  (`no-forms`). Panel and group kinds may be mixed on one item; only `menu` and `open` mean anything to the solver.
+
+```ts
+import { fitStack, readStack, stackTargets, storeStack, type StackForm, type StackItem } from "@n-uf/placement/stack";
+
+const form = (kind: StackForm["kind"], min: number, natural: number, cross: number, grows = false, crossMin?: number): StackForm => ({
+  kind,
+  main: { min, natural, ...(grows ? { grows } : {}) },
+  cross: { natural: cross, ...(crossMin === undefined ? {} : { min: crossMin }) },
+});
+const panel = (id: string, used: number): StackItem => ({
+  id,
+  used,
+  forms: [form("open", 90, 160, 240, true), form("header", 28, 28, 240, false, 100), form("rail", 24, 24, 30), form("menu", 0, 0, 0)],
+});
+const tools: StackItem = { id: "tools", used: 3, forms: [form("row", 96, 96, 180), form("stacked", 78, 78, 84), form("icons", 72, 72, 28), form("menu", 0, 0, 0)] };
+const column = { axis: "column", length: 250, cross: { min: 120, max: 360 } } as const;
+
+const fit = fitStack({ ...column, items: [panel("pages", 1), panel("findings", 2), tools] });
+console.log(fit.items.map((p) => p.kind), fit.cross, fit.notes);
+// [ 'header', 'open', 'row' ] 240 [ { code: 'form-down', id: 'pages', from: 0, to: 1 } ]
+
+const alone = fitStack({ ...column, items: [tools] });
+console.log(alone.items[0]!.kind, alone.cross); // icons 30
+```
+
+The result has, per item, `form` (an index into its forms), `kind` and `rect` (stack-local px: the stack starts at
+0, 0); `cross`, the stack's size across; `menu` (the » entry's `rect` and the ids in it, or `null`; an item in the
+menu has the entry's rect; `menu.items` are exactly the items whose kind is `menu`); and coded `notes`: `form-down`
+(`id`, `from`, `to`: the item took a smaller form than the one it started in, by length or by cross size, as indexes
+into its forms), `to-menu` (`id`), `too-wide` (`id`), `no-forms` (`id`) and `overflow` (`over` px: no item can give
+more way and the stack is still too long; forms that don't end in a `menu` form can't give more).
+
+`stackTargets(input, dragged)` takes the stack (an item of it with the dragged id is lifted out first, so a reorder
+within a stack works) and gives a target for every gap, before each item and after the last, in the shape
+`@n-uf/motion/drag` takes: `id` `gap:<k>`, priority 2, `place` `{ kind: "gap", at: k }`, `hit` (the stack split at
+its items' middles, as wide across as the larger of the stack and the drop's fit; with every item in the menu only
+the last gap has any length) and `slot`, the rect the dragged item gets.
+`fit` is the full solve with the item inserted at k (`input` the stack that was solved), so the preview is exactly the
+rect after the drop; `marker` is the line where the item's leading edge lands (a rect with no thickness across the
+stack). The dragged item counts as just used, so the others give way before it, and a group lands in the form that
+fits.
+
+```ts
+const targets = stackTargets({ ...column, items: [panel("pages", 1), panel("findings", 2)] }, tools);
+console.log(targets.map((t) => t.id), targets[1]!.slot, targets[1]!.fit.items[1]!.kind);
+// [ 'gap:0', 'gap:1', 'gap:2' ] { x: 0, y: 28, width: 240, height: 96 } row (Pages folds to its header to make room)
+```
+
+`storeStack(state)` and `readStack(data, known?)` keep what the user chose, as `{ v: 1, … }`: `order`, `kept`,
+`closed`, `used` (the use order, oldest first, so a reload restores who gives way first) and `forms` (the largest form
+index each item may take, `StackItem.from`; stored only from 1). Reading never throws: anything but an object of
+version 1 is `{ ok: false, error }`; inside one, an id that isn't a string, repeats or (with `known`) isn't one the
+consumer has, a `kept`, `closed`, `used` or `forms` entry for an item not in `order`, a form that isn't a whole number
+from 1, the key `__proto__` in `forms` (`forms` is an object with no prototype; `constructor` and `prototype` are ids
+like any other), and a field this version doesn't know are dropped and listed in `dropped`. An id listed twice in
+`used` counts at its last place (the newest use wins).
+
+```ts
+const saved = JSON.stringify(storeStack({ order: ["pages", "tools"], kept: ["pages"], closed: [], used: ["pages", "tools"], forms: { tools: 1 } }));
+console.log(saved); // {"v":1,"order":["pages","tools"],"kept":["pages"],"closed":[],"used":["pages","tools"],"forms":{"tools":1}}
+console.log(readStack(JSON.parse(saved), ["pages", "tools", "findings"]).ok, readStack({ v: 2 }).ok); // true false
+```
+
+### Floats
+
+An item that isn't docked is a float. It lies above the pages in the stage's own px (view space), so the pages scrolling
+under it never move it, and it has no pinned flag: there is one kind of float, `{ id, rect }`. `./stack` keeps floats
+apart from the stacks (an item is in a stack's order or in the floats, the app's choice) and offers three parts, all
+pure.
+
+- `fitFloat(rect, stage, avoid?)` gives the rect a float gets: moved (never resized) to lie inside the `stage`, then
+  beside any of the `avoid` rects (the docked items' rects, and the » entries', in the same px) it would cover, at the
+  nearest place that is clear and inside the stage. A float larger than the stage keeps its top-left corner on the
+  stage's. A clear place is found whenever one exists, and then `covers` is empty. Only when the stage has no clear
+  place for it, the float stays where it covers the least (among the 2,048 nearest candidate places) and `covers` lists
+  the `avoid` indexes it still covers. `FloatFit`: `rect`, `clamped` (also true when a position that wasn't a number was
+  replaced), `snapped`, `covers`, `searchCapped`. Fit the floats again whenever the stacks or the stage change: a stack
+  that grew may lie under one.
+  Cost: the candidate x's (every edge of the stage and of an `avoid` rect) are tried nearest first; for each, the
+  stretches of y the rects block are merged and skipped, so no clear place is missed however many lie between, and the
+  search stops when no later x can be nearer. Measured in a test run on a laptop: about 100 `avoid` rects 0.1 ms, 300
+  a few ms even when no place is clear (6 ms median, 15 ms worst), 1,000 about 17 ms. A safety net stops the clear
+  search after 3 million rect tests (thousands of rects) and sets `searchCapped`: the place found may then not be the
+  nearest, or a clear place may exist that was not found. Keep `avoid` to the docked items, not to every pixel.
+- `stackFloatTarget({ id, stage, size, avoid?, label? })` is a drop target in the shape `@n-uf/motion/drag` takes: `id`
+  `float:<id>` (not `"float"`, which `./desk` uses) and `kind: "float"`, priority 3 (a stack's gaps, priority 2, win
+  where they are), `free` (no room is made for it) and a `hit` that covers the whole plane, so a pointer past the
+  stage's edge, above, below or beside it, still hits it and a float drop never cancels. `make(point, grab?)` is the one
+  answer for the preview and the drop: the float's rect with the pointer at `point` holding it at `grab` (its offset in
+  the float; default the middle), run through `fitFloat`. Draw `make(...).rect` as the preview, and land the float on
+  the same call at the release. The intent lets a higher priority target take over from the current one only when the
+  pointer is `breakthrough` px (4) inside it, so a gap zone thinner than 8 px (2 × the breakthrough) along either axis
+  can never take over from the float target: give the gaps' `hit` at least that much room (the lab widens a thin
+  stack's zone across, and the first and last gap's past the stack's ends).
+- `storeFloats(floats)` and `readFloats(data, known?)`: `{ v: 1, floats: [{ id, x, y, width, height }] }`, in stacking
+  order (the last is on top). It writes no `pinned`. `storeFloats` leaves out, silently, a float whose position isn't a
+  finite number or whose size isn't over 0, and keeps the last readable entry of a repeated id (the one on top, at its
+  own place in the order). Reading never throws: anything but an object of version 1 with a `floats` array is
+  `{ ok: false, error }` (the version worded as the stack's reader words it, a string quoted); inside one, a float that
+  isn't an object, has no string id, isn't one the consumer has (with `known`) or has a position that isn't a finite
+  number or a size that isn't over 0 is dropped and listed in `dropped` as `float:<id>`; of a repeated id the last
+  readable entry stays and the earlier ones are listed the same way; a field this version doesn't know is listed as
+  `"<field>"` (a float's own as `float:<id>:<field>`). A `pinned` key, which an older store may have, is read and
+  ignored: the float loads as a plain float, at the rect it was stored with, and `pinned:<id>` is listed.
+
+```ts
+import { fitFloat, readFloats, stackFloatTarget, storeFloats } from "@n-uf/placement/stack";
+
+const stage = { x: 0, y: 0, width: 900, height: 500 };
+const docked = [{ x: 0, y: 32, width: 240, height: 468 }]; // a column of docked items, in the stage's px
+
+const fit = fitFloat({ x: 100, y: 200, width: 200, height: 150 }, stage, docked);
+console.log(fit.rect, fit.snapped); // { x: 240, y: 200, width: 200, height: 150 } true
+
+const target = stackFloatTarget({ id: "notes", stage, size: { width: 200, height: 150 }, avoid: docked });
+const drop = target.make({ x: 500, y: -400 }, { x: 20, y: 10 }); // the pointer is above the stage
+console.log(drop.rect, drop.fit.clamped); // { x: 480, y: 0, width: 200, height: 150 } true
+
+console.log(JSON.stringify(storeFloats([{ id: "notes", rect: drop.rect }]))); // {"v":1,"floats":[{"id":"notes","x":480,"y":0,"width":200,"height":150}]}
+const old = readFloats({ v: 1, floats: [{ id: "notes", x: 480, y: 0, width: 200, height: 150, pinned: true }] });
+console.log(old.ok && old.dropped); // [ 'pinned:notes' ]
+```
+
+Freezing the layout needs nothing from the library: the freeze is the app's flag, and the app reads it once at the press.
+A press on a grip while frozen (and Alt not held) never becomes a drag, so no target is built and nothing is dropped;
+holding Alt shows the grips and everything works, a drag that began finishes. `fitStack` reads sizes, not what an item
+says, so a count or a phase that leaves its forms' sizes alone moves no other item.
+
 ## Pane zones
 
 `paneZone(rect, point, previous, options?)` says which of a pane's five zones a point is in: the centre rectangle

package/dist/desk.d.ts

@@ -1,5 +1,6 @@
-import { P as PanelsOptions, a as PanelDef, b as PanelsState, c as PanelTargetInput, d as PanelTarget, p as panelDrop, e as PanelDrop, l as layoutPanels, f as PanelsLayout } from './targets-B_U2Zf7x.js';
+import { P as PanelsOptions, a as PanelDef, b as PanelsState, c as PanelTargetInput, d as PanelTarget, p as panelDrop, e as PanelDrop, l as layoutPanels, f as PanelsLayout } from './targets-B6eLC-52.js';
 import './geometry-mL-GTRti.js';
+import './target-D3PiLg44.js';
 
 /**
  * @n-uf/placement/desk: desk presets as data on `@n-uf/placement/panels`. A preset is options for the panels engine

package/dist/panels.d.ts

@@ -1,6 +1,7 @@
-import { b as PanelsState, S as Side, E as Edge, C as Clock, a as PanelDef } from './targets-B_U2Zf7x.js';
-export { B as BAND_SIZE, g as Band, h as BandOption, i as COLUMN_REACH, j as Column, D as DEFAULT_PANELS_OPTIONS, k as DockOptions, m as EDGES, F as FLOAT_HEIGHT, n as FLOAT_MIN, o as FloatAt, G as GiveWay, I as IDENTITY_VIEW, e as PanelDrop, q as PanelKind, r as PanelPlace, s as PanelStop, t as PanelStopsOptions, d as PanelTarget, c as PanelTargetInput, f as PanelsLayout, u as PanelsNote, v as PanelsNoteCode, P as PanelsOptions, w as PanelsStart, x as Place, y as PlacedBand, z as PlacedColumn, A as PlacedPanel, H as PlacedRail, R as RAIL_EDGE, J as Reserve, K as ReserveEdge, L as SIDES, V as View, W as Where, M as activate, N as bandHeight, O as bandSize, Q as close, T as columnWidth, U as createPanels, X as defOf, Y as dock, Z as dockBand, _ as float, $ as floatSize, a0 as focus, a1 as giveWayOrder, a2 as homePlace, a3 as keep, l as layoutPanels, a4 as liftPanel, a5 as open, a6 as ownWidth, p as panelDrop, a7 as panelStops, a8 as panelTargets, a9 as pin, aa as placeRank, ab as resizeBand, ac as resizeColumn, ad as resizeFloat, ae as samePlaces, af as showTabs, ag as tick, ah as toPage, ai as toView, aj as toggleFold, ak as whereIs } from './targets-B_U2Zf7x.js';
+import { b as PanelsState, S as Side, E as Edge, C as Clock, a as PanelDef } from './targets-B6eLC-52.js';
+export { B as BAND_SIZE, g as Band, h as BandOption, i as COLUMN_REACH, j as Column, D as DEFAULT_PANELS_OPTIONS, k as DockOptions, m as EDGES, F as FLOAT_HEIGHT, n as FLOAT_MIN, o as FloatAt, G as GiveWay, I as IDENTITY_VIEW, e as PanelDrop, q as PanelKind, r as PanelPlace, s as PanelStop, t as PanelStopsOptions, d as PanelTarget, c as PanelTargetInput, f as PanelsLayout, u as PanelsNote, v as PanelsNoteCode, P as PanelsOptions, w as PanelsStart, x as Place, y as PlacedBand, z as PlacedColumn, A as PlacedPanel, H as PlacedRail, R as RAIL_EDGE, J as Reserve, K as ReserveEdge, L as SIDES, V as View, W as Where, M as activate, N as bandHeight, O as bandSize, Q as close, T as columnWidth, U as createPanels, X as defOf, Y as dock, Z as dockBand, _ as float, $ as floatSize, a0 as focus, a1 as giveWayOrder, a2 as homePlace, a3 as keep, l as layoutPanels, a4 as liftPanel, a5 as open, a6 as ownWidth, p as panelDrop, a7 as panelStops, a8 as panelTargets, a9 as pin, aa as placeRank, ab as resizeBand, ac as resizeColumn, ad as resizeFloat, ae as samePlaces, af as showTabs, ag as tick, ah as toPage, ai as toView, aj as toggleFold, ak as whereIs } from './targets-B6eLC-52.js';
 import { R as Rect } from './geometry-mL-GTRti.js';
+import './target-D3PiLg44.js';
 
 /**
  * The panels' stored form: `storePanels(state)` gives plain JSON-safe data (`{ v: 1, … }`); `readPanels(data, defs?)`

package/dist/stack.d.ts

@@ -0,0 +1,351 @@
+import { R as Rect, P as Point, S as Size } from './geometry-mL-GTRti.js';
+import { T as Target } from './target-D3PiLg44.js';
+
+/**
+ * The edge stack's shapes. A stack is the items along one edge of a stage: a column (vertical, a side region) or a
+ * row (horizontal, a bar). An item is a panel or a control group; it declares its forms, largest first, and the
+ * solver (`fitStack`) picks one per item. Plain data in and out: no words, no time, no DOM.
+ *
+ * The form kinds are structural labels the app draws by; the solver reads only `menu` (a form with no room of its own)
+ * and, for the cross size, `open`. Panel and group kinds may be mixed on one item.
+ */
+
+/** `"column"` runs the stack down (its main size is a height, its cross size a width); `"row"` runs it across. */
+type StackAxis = "column" | "row";
+/** How a panel draws: open (header and body), a header only, a rail icon, or an entry in the » menu. */
+type PanelFormKind = "open" | "header" | "rail" | "menu";
+/** How a control group draws: a row of words, the words stacked, icons only, or an entry in the » menu. */
+type GroupFormKind = "row" | "stacked" | "icons" | "menu";
+type StackFormKind = PanelFormKind | GroupFormKind;
+/** Along the stack: `min` is the least it can be drawn, `natural` what it asks for; `grows` takes spare length. */
+interface MainSize {
+    readonly min: number;
+    readonly natural: number;
+    readonly grows?: boolean;
+}
+/** One way to draw an item. A `menu` form takes no room in the stack (the » entry stands for it). */
+interface StackForm {
+    readonly kind: StackFormKind;
+    readonly main: MainSize;
+    /**
+     * Across the stack: `natural` is what this form asks for (it sets the stack's cross size when `setsCross`); `min`
+     * is the least it can be drawn across (default `natural`). A form that doesn't set the cross size takes its next
+     * form only when its `min` is over the stack's cross size, so a header stays in a column an open panel made
+     * narrow when it has a small `min`.
+     */
+    readonly cross: {
+        readonly natural: number;
+        readonly min?: number;
+    };
+    /**
+     * Whether this form sets the stack's cross size (the column's width, the bar's height). Default: true for a
+     * panel's `open`, false for everything else (a group never sets a column's width).
+     */
+    readonly setsCross?: boolean;
+}
+interface StackItem {
+    readonly id: string;
+    /** Largest first. The solver starts at `from` and steps down one at a time. An item with none is left out. */
+    readonly forms: readonly StackForm[];
+    /** How recently it was used: the smaller, the longer ago, the sooner it gives way. */
+    readonly used: number;
+    /** Kept: gives way after every item that isn't. */
+    readonly kept?: boolean;
+    /**
+     * The first form the item may take, an index into `forms` (default 0; a panel folded by hand starts at its header).
+     * The solver never goes above it. `form` in the result and in the notes are indexes into `forms`, not into what is
+     * left after `from`.
+     */
+    readonly from?: number;
+}
+/** The cross size a stack may take. With no form setting it, the stack is a `rail` wide (default {@link DEFAULT_RAIL}). */
+interface CrossLimits {
+    readonly min: number;
+    readonly max: number;
+    readonly rail?: number;
+}
+interface StackInput {
+    readonly axis: StackAxis;
+    /** The stack's length along the axis. */
+    readonly length: number;
+    readonly cross: CrossLimits;
+    /** In order, from the start of the stack. */
+    readonly items: readonly StackItem[];
+    /** The » menu entry's size along the stack, taken only while an item is in the menu (default {@link DEFAULT_MENU}). */
+    readonly menu?: {
+        readonly main: number;
+    };
+}
+/** The width of a stack nothing open holds, px. */
+declare const DEFAULT_RAIL = 30;
+/** The » menu entry's size along the stack, px. */
+declare const DEFAULT_MENU = 28;
+/** Whether a form sets the stack's cross size: its own say, else true for a panel's `open`. */
+declare const formSetsCross: (f: StackForm) => boolean;
+/** `input` with `item` inserted at index `at` (clamped to the items' range). */
+declare function withItem(input: StackInput, item: StackItem, at: number): StackInput;
+/** An item drawn: the form it took, its kind and its rect (stack-local px). One in the menu has the menu entry's rect. */
+interface PlacedStackItem {
+    readonly id: string;
+    /** Index into the item's `forms`. */
+    readonly form: number;
+    readonly kind: StackFormKind;
+    readonly rect: Rect;
+}
+interface StackMenu {
+    /** The » entry's rect. */
+    readonly rect: Rect;
+    /** The items in it, in the stack's order: exactly the items whose kind is `menu`. */
+    readonly items: readonly string[];
+}
+/**
+ * Why a stack looks as it does:
+ * - `form-down`: an item took a smaller form than the one it started in (`from`, an index into its forms), by length
+ *   or by cross size.
+ * - `to-menu`: an item is in the » menu.
+ * - `too-wide`: an item's form doesn't set the cross size and its `cross.min` is over the stack's. Cross size never
+ *   puts an item in the menu, so it keeps its last drawn form and the app clips it.
+ * - `no-forms`: an item with no forms, left out of `items`.
+ * - `overflow`: no item can give more way and the stack is still `over` px too long (forms that don't end in a `menu`
+ *   form can't give more; neither can a stack where going into the menu would only make it longer).
+ */
+type StackNote = {
+    readonly code: "form-down";
+    readonly id: string;
+    readonly from: number;
+    readonly to: number;
+} | {
+    readonly code: "to-menu";
+    readonly id: string;
+} | {
+    readonly code: "too-wide";
+    readonly id: string;
+} | {
+    readonly code: "no-forms";
+    readonly id: string;
+} | {
+    readonly code: "overflow";
+    readonly over: number;
+};
+type StackNoteCode = StackNote["code"];
+interface StackFit {
+    readonly axis: StackAxis;
+    readonly length: number;
+    /** The stack's size across: the widest `open` (clamped to the limits), or the rail. */
+    readonly cross: number;
+    /** One per input item that has forms, in order. */
+    readonly items: readonly PlacedStackItem[];
+    /** The » entry, or null while no item is in the menu. */
+    readonly menu: StackMenu | null;
+    /** `no-forms` first, then `form-down` per item in the order they gave way, `to-menu`, `too-wide`, and `overflow`. */
+    readonly notes: readonly StackNote[];
+}
+
+declare function fitStack(input: StackInput): StackFit;
+
+/**
+ * The drop targets for dragging an item into a stack, in the shape @n-uf/motion/drag takes. `stackTargets(input,
+ * dragged)` gives one target for every gap of the stack without the dragged item (an item of the input with its id
+ * is lifted out first, so a reorder within a stack works): before each item and after the last, so an empty stack has
+ * one. An item with no forms has no place of its own, but its gaps count.
+ *
+ * - `id` `gap:<k>`, priority 2, `place` `{ kind: "gap", at: k }` (k counts the input's items, the dragged one lifted
+ *   out, including any with no forms; it is not an index into `fit.items`, which leaves those out: look the dragged
+ *   item up there by its id, as `slot` already does).
+ * - `hit`: the gap's zone along the axis, the stack split at its items' middles (an item in the menu has no place of
+ *   its own: the gaps next to it split the stretch where the stack's drawn items end; with every item in the menu only
+ *   the last gap, "at the end", has any length, and the others are a point at the start). Across, it is the larger of
+ *   the stack's current size and the size the drop gives it, so the pointer over the preview is over the target.
+ * - `fit`: the full `fitStack` of the stack with the dragged item inserted at k, and `input` the stack that was
+ *   solved. The preview is `slot`, the dragged item's rect in `fit`: exactly the rect it gets after the drop, because
+ *   the drop is that same solve. `marker` is the line where its leading edge lands: a rect with no thickness across
+ *   the stack's cross size (the app draws it with one).
+ *
+ * The dragged item counts as just used: it is newer than every item in the stack, so the others give way before it.
+ * A group lands in the form that fits; a panel that would set a wider column makes room by that solve too. A dragged
+ * item with no forms has no targets.
+ */
+
+type StackPlace = {
+    readonly kind: "gap";
+    readonly at: number;
+};
+interface StackTarget extends Target {
+    readonly priority: 2;
+    /** The item dragged. */
+    readonly item: string;
+    readonly place: StackPlace;
+    /** The line where the dragged item's leading edge lands. */
+    readonly marker: Rect;
+    /** The stack with the dragged item inserted: what a drop here makes. */
+    readonly input: StackInput;
+    /** Its fit: the preview and the drop are both its rect for the dragged item. */
+    readonly fit: StackFit;
+}
+declare function stackTargets(input: StackInput, dragged: StackItem): StackTarget[];
+
+/**
+ * The stack's stored form: `storeStack(state)` gives plain JSON-safe data (`{ v: 1, order, kept, closed, used, forms
+ * }`); `readStack(data, known?)` reads parsed data back and never throws. Anything but an object of version 1 is
+ * `{ ok: false, error }`. Inside one it is lenient, as the panels' reader is: an id that isn't a string, is repeated
+ * or (with `known`) isn't one the consumer has is dropped and listed in `dropped`; a `kept`, `closed`, `used` or
+ * `forms` entry for an id that isn't in `order` is dropped; a form that isn't a whole number from 1 up is dropped;
+ * the key `__proto__` in `forms` is dropped (the other keys, `constructor` and `prototype` included, are ids like any
+ * other: `forms` is an object with no prototype, written and read); a field this version doesn't know is skipped and
+ * reported as `"<field>"`. An item the consumer has that the stored order lacks is no error: the consumer places it.
+ *
+ * - `kept`: items kept open (they give way last).
+ * - `closed`: items the user closed; their place in `order` is kept for when they open.
+ * - `used`: the use order, oldest to newest, so a reload restores who gives way first (an item's `used` is its index in
+ *   it; one the list lacks is older than all). An id listed twice counts at its last place: the newest use wins.
+ * - `forms`: the user's chosen form per item, the index of the largest form it may take (`StackItem.from`). 0, the
+ *   first, is not stored.
+ */
+interface StackState {
+    /** The items' order along the stack. */
+    readonly order: readonly string[];
+    /** Items kept open: they give way last. */
+    readonly kept: readonly string[];
+    /** Items the user closed. */
+    readonly closed: readonly string[];
+    /** The use order, oldest first. */
+    readonly used: readonly string[];
+    /** The form index the user chose per item (only those that chose one; absent means the first). */
+    readonly forms: Readonly<Record<string, number>>;
+}
+interface StoredStack {
+    readonly v: 1;
+    readonly order: string[];
+    readonly kept: string[];
+    readonly closed: string[];
+    readonly used: string[];
+    readonly forms: Record<string, number>;
+}
+type StackRead = {
+    readonly ok: true;
+    readonly state: StackState;
+    readonly dropped: readonly string[];
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** A state with these items in this order, none kept or closed, used in that order, every form the first. */
+declare const createStack: (order: readonly string[]) => StackState;
+declare function storeStack(state: StackState): StoredStack;
+declare function readStack(data: unknown, known?: readonly string[]): StackRead;
+
+/**
+ * Floats for the edge stack: an item that isn't docked lies above the pages in the stage's own px (view space), so the
+ * pages scrolling under it never move it. A float has no pinned flag: there is one kind of float, and it is in view
+ * space. Pure, like the rest of `./stack`.
+ *
+ * - `fitFloat(rect, stage, avoid)`: the rect a float gets. It is moved (never resized) to lie inside the stage, then
+ *   beside whatever docked content it would cover: the nearest place inside the stage that is clear of every `avoid`
+ *   rect (the docked items' rects, in the same px). One larger than the stage keeps its top-left corner on the
+ *   stage's; if no clear place exists the float stays where it covers the least and `covers` says which rects.
+ *   A clear place is found whenever one exists: the x's are tried nearest first and, for each, the blocked stretches of
+ *   y are merged and skipped, so no clear place is missed however many places lie between. Cost (measured in a test
+ *   run on a laptop): about 100 docked rects 0.1 ms, 300 a few ms even when no place is clear (6 ms median, 15 ms
+ *   worst), 1,000 about 17 ms; a safety net stops the clear search after 3 million rect tests and says so in
+ *   `searchCapped`; a stage with no clear place looks at the 2,048 nearest places for the least covered.
+ * - `stackFloatTarget(input)`: a drop target in the shape `@n-uf/motion/drag` takes, free (no room is made for it),
+ *   `kind` `"float"`, id `float:<item>`, whose `hit` covers the whole plane, so a pointer past the stage's edge still
+ *   hits it (a float drop never cancels), at priority 3 so a docked stack's gaps win where they are. `make(point,
+ *   grab)` is the one answer for the preview and the drop: the float's rect with the pointer holding it at `grab`,
+ *   clamped and clear of the docked content.
+ * - `storeFloats` / `readFloats`: the stored form, `{ v: 1, floats: [{ id, x, y, width, height }] }`, in stacking
+ *   order (the last is on top). It writes no `pinned`; one an old store has is read, ignored and listed.
+ */
+
+/** A float: the item's id and its rect in view space (the stage's px). */
+interface StackFloat {
+    readonly id: string;
+    readonly rect: Rect;
+}
+interface FloatFit {
+    /** The float's rect: inside the stage and clear of the docked content where a clear place exists. */
+    readonly rect: Rect;
+    /** It was moved to lie inside the stage. */
+    readonly clamped: boolean;
+    /** It was moved beside the docked content it would have covered. */
+    readonly snapped: boolean;
+    /**
+     * Indexes into `avoid` of the rects it still covers. Empty whenever a clear place was found, which is whenever one
+     * exists (unless `searchCapped`); not empty only when the stage has no clear place for the float, and then it stays
+     * where it covers the least among the 2,048 nearest candidate places.
+     */
+    readonly covers: readonly number[];
+    /** The safety net on the clear search was hit (thousands of rects): the place found may not be the nearest, or a clear place may exist that was not found. Normally false. */
+    readonly searchCapped: boolean;
+}
+declare function fitFloat(want: Rect, stage: Rect, avoid?: readonly Rect[]): FloatFit;
+/** What a float drop makes: the same answer for the preview and for the release. */
+interface FloatDrop {
+    /** The float's rect in view space. */
+    readonly rect: Rect;
+    readonly fit: FloatFit;
+}
+interface StackFloatTargetInput {
+    /** The item dragged. */
+    readonly id: string;
+    /** The stage, in view space. */
+    readonly stage: Rect;
+    /** The float's size: it is never resized. */
+    readonly size: Size;
+    /** The docked content to stay clear of: the docked items' rects (and the » entries'), in view space. */
+    readonly avoid?: readonly Rect[];
+    /** What the target is called (default "Float here"). */
+    readonly label?: string;
+}
+interface FloatTarget extends Target {
+    /** What kind of place it is, for a consumer that holds targets of several kinds. */
+    readonly kind: "float";
+    readonly priority: 3;
+    readonly free: true;
+    /** The item dragged. */
+    readonly item: string;
+    /**
+     * The drop with the pointer at `point` holding the float at `grab` (its offset from the float's top-left corner,
+     * default the middle): `rect` is the preview and the landing, clamped into the stage and clear of the docked content.
+     */
+    make(point: Point, grab?: Point): FloatDrop;
+}
+declare function stackFloatTarget(input: StackFloatTargetInput): FloatTarget;
+interface StoredFloats {
+    readonly v: 1;
+    readonly floats: {
+        id: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }[];
+}
+type FloatsRead = {
+    readonly ok: true;
+    readonly floats: StackFloat[];
+    readonly dropped: readonly string[];
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * The floats as plain JSON-safe data, in the order given (the stacking order, the last on top). Never a `pinned`.
+ * What it can't read back is left out, silently: a float whose position isn't a finite number or whose size isn't over
+ * 0 (a zero-size float), and an earlier entry of a repeated id (the last readable entry of an id is the one on top,
+ * so it stays, at its own place in the order).
+ */
+declare function storeFloats(floats: readonly StackFloat[]): StoredFloats;
+/**
+ * Reads parsed data back; never throws. Anything but an object of version 1 with a `floats` array is `{ ok: false,
+ * error }`. Inside one it is lenient: a float that isn't an object, has no string id, isn't one the
+ * consumer has (with `known`) or has a position or size that isn't a finite number (a size over 0) is dropped and
+ * listed in `dropped` as `float:<id>` (or `a <type> where a float goes`); a top-level field this version doesn't
+ * know is listed as `"<field>"`, and so is a float's own (`float:<id>:<field>`) while the float itself is kept.
+ * A `pinned` key (an old store's flag, whatever its value) is ignored: the float loads as a plain float, in view
+ * space as stored, and `pinned:<id>` is listed. A repeated id keeps its last readable entry (the list is in stacking
+ * order, the last on top); the earlier ones are dropped and listed as `float:<id>`.
+ */
+declare function readFloats(data: unknown, known?: readonly string[]): FloatsRead;
+
+export { type CrossLimits, DEFAULT_MENU, DEFAULT_RAIL, type FloatDrop, type FloatFit, type FloatTarget, type FloatsRead, type GroupFormKind, type MainSize, type PanelFormKind, type PlacedStackItem, type StackAxis, type StackFit, type StackFloat, type StackFloatTargetInput, type StackForm, type StackFormKind, type StackInput, type StackItem, type StackMenu, type StackNote, type StackNoteCode, type StackPlace, type StackRead, type StackState, type StackTarget, type StoredFloats, type StoredStack, createStack, fitFloat, fitStack, formSetsCross, readFloats, readStack, stackFloatTarget, stackTargets, storeFloats, storeStack, withItem };