@n-uf/placement 26.11.5 → 26.11.7

package/dist/targets-BEqoVKbF.d.ts

@@ -0,0 +1,432 @@
+import { S as Size, R as Rect, P as Point } from './geometry-mL-GTRti.js';
+
+/**
+ * The panels model: plain data and the pure changes on it.
+ *
+ * Panels have string ids. Each side holds full-height columns (outer edge first), each column one or more panels
+ * top to bottom and its own width. A panel may instead float, in page space (it moves with the page) or pinned in
+ * view space (it stays put). A logical clock per panel (opened, used) is what give-way reads; every change here that
+ * counts as a use moves it on. Nothing here reads a host clock: the next tick is one past the latest in the state.
+ */
+
+type Side = "left" | "right";
+declare const SIDES: readonly Side[];
+/**
+ * What a consumer says about a panel: its width limits docked, its size limits floating, and where it may go. No
+ * words: names and titles are the consumer's.
+ */
+interface PanelDef {
+    readonly id: string;
+    /** A docked column's width limits and its natural width. */
+    readonly width: {
+        readonly min: number;
+        readonly max: number;
+        readonly natural: number;
+    };
+    /** A float's size limits and natural size (default: its natural width, 360 px tall, no smaller than 160 × 120). */
+    readonly float?: {
+        readonly min: Size;
+        readonly natural: Size;
+    };
+    /** Where it may dock (default: both sides). */
+    readonly sides?: readonly Side[];
+    /** May it float (default: yes). */
+    readonly floats?: boolean;
+}
+/** A full-height column: its panels top to bottom, and its stored width (the layout clamps it to its panels' limits). */
+interface Column {
+    readonly panels: readonly string[];
+    readonly width: number;
+}
+/** A floating panel: `rect` in page space, or in view space when `pinned`. */
+interface FloatAt {
+    readonly id: string;
+    readonly rect: Rect;
+    readonly pinned?: boolean;
+}
+/** Logical times: when a panel was last opened, and last used (opened, focused, moved or unfolded). */
+interface Clock {
+    readonly opened: number;
+    readonly used: number;
+}
+interface PanelsState {
+    /** Each side's columns, from the outer edge inward. */
+    readonly sides: Readonly<Record<Side, readonly Column[]>>;
+    /** Floating panels; a later one is on top. */
+    readonly floats: readonly FloatAt[];
+    /** Folded by hand (give-way never writes this). */
+    readonly folded: readonly string[];
+    /** Docked panels kept open: their columns give way last. */
+    readonly kept: readonly string[];
+    /** Not shown at all (they keep their place, for when they open again). */
+    readonly closed: readonly string[];
+    readonly clock: Readonly<Record<string, Clock>>;
+}
+/** The page's offset and scale in the view: a page point p shows at `x + p.x * scale`, `y + p.y * scale`. */
+interface View {
+    readonly x: number;
+    readonly y: number;
+    readonly scale: number;
+}
+declare const IDENTITY_VIEW: View;
+/** Who gives way first: the oldest or the newest, by when they were last used or last opened. */
+interface GiveWay {
+    readonly order: "oldest" | "newest";
+    readonly by: "used" | "opened";
+}
+interface PanelsOptions {
+    /** Default: `{ order: "oldest", by: "used" }`, so the panel used longest ago gives way first. */
+    readonly giveWay: GiveWay;
+    /** "clamp" keeps floats in the view at layout time; "free" never moves them. Default "clamp". */
+    readonly floats: "clamp" | "free";
+    /** How much of a float wider than the view stays in it, px (default 48). */
+    readonly floatVisible: number;
+    /** The pages' minimum width (default 320). */
+    readonly pagesMin: number;
+    /** The page's offset and scale (default: identity). */
+    readonly view: View;
+    /** A title bar's height: a panel folded in a column, and the part of a float the clamp keeps in the view (default 28). */
+    readonly bar: number;
+    /** A rail's width (default 36). */
+    readonly rail: number;
+    /** A rail segment's height, and the gap above the first one (defaults 36 and 4). */
+    readonly segment: number;
+    readonly railInset: number;
+}
+declare const DEFAULT_PANELS_OPTIONS: PanelsOptions;
+/** A float's size when its def gives none: this tall, and never smaller than FLOAT_MIN. */
+declare const FLOAT_HEIGHT = 360;
+declare const FLOAT_MIN: Size;
+/** Where a panel is: a column (side and index), floating, or nowhere. */
+type Where = {
+    readonly kind: "column";
+    readonly side: Side;
+    readonly index: number;
+} | {
+    readonly kind: "float";
+    readonly float: FloatAt;
+} | {
+    readonly kind: "none";
+};
+declare function whereIs(state: PanelsState, id: string): Where;
+/** One past the latest logical time in the state. */
+declare const tick: (state: PanelsState) => number;
+declare const defOf: (defs: readonly PanelDef[], id: string) => PanelDef | undefined;
+/** A float's size limits and natural size from its def. */
+declare function floatSize(def: PanelDef | undefined): {
+    min: Size;
+    natural: Size;
+};
+/**
+ * A panel's own width, for a new column made for it: the width of the column it is in, clamped to its own limits;
+ * floating or nowhere, its natural width.
+ */
+declare function ownWidth(defs: readonly PanelDef[], state: PanelsState, id: string): number;
+interface PanelsStart {
+    /** Each side's columns from the outer edge inward, each a list of panel ids top to bottom. */
+    readonly left?: readonly (readonly string[])[];
+    readonly right?: readonly (readonly string[])[];
+    /** Floating panels: where (page space, or view space when pinned); the size defaults to the def's natural size. */
+    readonly floats?: readonly {
+        readonly id: string;
+        readonly x: number;
+        readonly y: number;
+        readonly width?: number;
+        readonly height?: number;
+        readonly pinned?: boolean;
+    }[];
+    readonly folded?: readonly string[];
+    readonly kept?: readonly string[];
+    readonly closed?: readonly string[];
+}
+/**
+ * A state from a plain start: each column as wide as the widest natural width of its panels (within their limits),
+ * each float its natural size. The clock counts up in the order the panels are listed (left, right, floats), so the
+ * last one listed is the newest.
+ */
+declare function createPanels(defs: readonly PanelDef[], start: PanelsStart): PanelsState;
+/** The state with `id` taken out of its column (an emptied column goes) or the floats. Nothing else changes. */
+declare function liftPanel(state: PanelsState, id: string): PanelsState;
+/**
+ * Open a panel: it shows again where it was, and it is the newest opened and used. A panel placed nowhere goes into
+ * a new innermost column on `at.side`, `at.width` wide; without `at` it stays placed nowhere.
+ */
+declare function open(state: PanelsState, id: string, at?: {
+    readonly side: Side;
+    readonly width: number;
+}): PanelsState;
+/** Close a panel: it isn't shown, keeps its place, and is no longer kept open. */
+declare const close: (state: PanelsState, id: string) => PanelsState;
+/** Focus a panel: it is the newest used; a float comes to the top. */
+declare function focus(state: PanelsState, id: string): PanelsState;
+/** Fold a panel to its title bar by hand, or unfold it (unfolding is a use). */
+declare function toggleFold(state: PanelsState, id: string): PanelsState;
+/** Keep a docked panel open (its column gives way last), or stop keeping it. A floating panel isn't kept. */
+declare function keep(state: PanelsState, id: string, on: boolean): PanelsState;
+interface DockOptions {
+    /** Stack into the column at `index` (at its bottom) instead of making a new column there. */
+    readonly into?: boolean;
+    /** A new column's width (default: the width of the column the panel leaves, else 0, which the layout clamps to the minimum). */
+    readonly width?: number;
+}
+/**
+ * Dock a panel on `side`: a new column at `index` (0 the outer edge; past the end, innermost), or with `into` at the
+ * bottom of the column at `index` (counted once the panel is lifted out). It shows, it is the newest used, and it
+ * keeps whether it is kept open.
+ */
+declare function dock(state: PanelsState, id: string, side: Side, index: number, options?: DockOptions): PanelsState;
+/**
+ * Float a panel at `rect` (page space; view space when pinned). A float stays pinned or not unless `pinned` says;
+ * a docked panel floats unpinned. It shows, it is the newest used and on top, and it is no longer kept open.
+ */
+declare function float(state: PanelsState, id: string, rect: Rect, pinned?: boolean): PanelsState;
+/** A page-space rect in view space, and back. */
+declare const toView: (r: Rect, v: View) => Rect;
+declare const toPage: (r: Rect, v: View) => Rect;
+/**
+ * Pin a float to the view, or unpin it to the page. `view` is where the page is now (default: identity): the float
+ * doesn't jump, its rect is converted between the two spaces. A float's size is never scaled.
+ *
+ * `shown` is where the float shows now, in view space (the layout's placed rect for it). When given, it is converted
+ * instead of the stored rect, so a float the clamp moved stays where it shows rather than jumping to its stored place.
+ */
+declare function pin(state: PanelsState, id: string, on: boolean, view?: View, shown?: Rect): PanelsState;
+/**
+ * Store a column's width (the layout clamps it to its panels' limits). Resizing is a use: the column's panels are
+ * the newest used, so give-way takes room from the other columns, not from the one being resized.
+ */
+declare function resizeColumn(state: PanelsState, side: Side, index: number, width: number): PanelsState;
+/** Store a float's rect (its own space). Resizing is a use. */
+declare function resizeFloat(state: PanelsState, id: string, rect: Rect): PanelsState;
+/** A column's width as the layout takes it: its stored width clamped to its panels' limits (with `defs`). */
+declare function columnWidth(defs: readonly PanelDef[] | undefined, col: Column): number;
+/**
+ * Two states place the panels the same (columns, their panels and widths, floats and their rects; the clock aside).
+ * With `defs`, widths compare as the layout takes them (clamped to the panels' limits), so a stored width past a
+ * column's max is the same place as that max.
+ */
+declare function samePlaces(a: PanelsState, b: PanelsState, defs?: readonly PanelDef[]): boolean;
+
+/**
+ * `layoutPanels`: the panels' state, a stage and options in; geometry and structure out: every panel's rect, layer
+ * and kind, the columns, the rails, the pages' rect, and coded notes on how it gave way. Pure: the same input always
+ * lays out the same. How anything looks is the consumer's.
+ *
+ * - A column is full height and as wide as its stored width, clamped to its panels' limits. Inside it, a panel
+ *   folded by hand is a title bar (`options.bar` tall) and the open ones share the rest of the height equally.
+ * - A column whose panels are all folded is railed: its panels become segments of its side's rail (one rail per
+ *   side, `options.rail` wide at the outer edge, segments in side order).
+ * - Give-way: when the open columns, the rails and `pagesMin` don't fit the stage width, columns shrink toward their
+ *   minimum, then whole columns fold to the rail, in the policy's order, until the pages fit. Columns holding a kept
+ *   panel come after every other column; if the pages still don't fit, they fold too (`kept-folded`). Folding by
+ *   give-way never writes `folded`, so a wider stage brings the column back.
+ * - Floats: "clamp" keeps a float in the view at layout time (the state keeps the stored rect, so a larger view
+ *   brings it back where it was); "free" never moves one. A float's size is never scaled. A pinned float is in view
+ *   space and clamped against the view; an unpinned one has its position in page space, clamped so that its screen
+ *   rect at pan 0 fits the view, then moved by the view's offset and scale, so it scrolls with the page.
+ */
+
+/**
+ * Where a panel is, structurally: an open part of a column, a folded title bar in a column, a segment of a rail
+ * (the panel itself isn't laid out), or a float.
+ */
+type PanelKind = "column" | "bar" | "segment" | "float";
+interface PlacedPanel {
+    /** Stage px; for a segment, the segment's rect in its rail. */
+    readonly rect: Rect;
+    readonly kind: PanelKind;
+    /** Columns and rails 0, floats 10 and up (a later float on top). */
+    readonly layer: number;
+    /** In a rail: there is no panel to lay out, only its segment. */
+    readonly hidden: boolean;
+    /** Folded by hand (a bar, or a segment of a column folded by hand), or by give-way (a segment). */
+    readonly folded: null | "hand" | "auto";
+    /** Kept open. */
+    readonly kept: boolean;
+    /** A pinned float. */
+    readonly pinned: boolean;
+    /** Docked: its side and column index (the state's). */
+    readonly side?: Side;
+    readonly column?: number;
+    /** A float the clamp moved or resized. */
+    readonly clamped?: boolean;
+}
+interface PlacedColumn {
+    readonly side: Side;
+    /** The column's index in the state. */
+    readonly index: number;
+    /** Its rect (zero wide when railed). */
+    readonly rect: Rect;
+    /** Its stored width clamped to its panels' limits, and those limits. */
+    readonly width: number;
+    readonly min: number;
+    readonly max: number;
+    /** null: open; "hand": all its panels folded by hand; "auto": folded by give-way. */
+    readonly folded: null | "hand" | "auto";
+    /** Shrunk by give-way below its width. */
+    readonly shrunk: boolean;
+    /** It holds a kept panel. */
+    readonly kept: boolean;
+    /** The shown panels, top to bottom. */
+    readonly panels: readonly string[];
+}
+interface PlacedRail {
+    readonly side: Side;
+    readonly rect: Rect;
+    readonly segments: readonly {
+        readonly id: string;
+        readonly rect: Rect;
+    }[];
+}
+type PanelsNoteCode = "column-shrunk" | "column-folded" | "kept-folded" | "pages-under-min" | "float-clamped" | "float-resized";
+/** One note on a layout: a code and its data. */
+type PanelsNote = {
+    readonly code: "column-shrunk";
+    readonly side: Side;
+    readonly column: number;
+    readonly items: readonly string[];
+    readonly from: number;
+    readonly to: number;
+} | {
+    readonly code: "column-folded" | "kept-folded";
+    readonly side: Side;
+    readonly column: number;
+    readonly items: readonly string[];
+} | {
+    readonly code: "pages-under-min";
+    readonly width: number;
+    readonly min: number;
+} | {
+    readonly code: "float-clamped" | "float-resized";
+    readonly items: readonly string[];
+};
+interface PanelsLayout {
+    readonly items: Map<string, PlacedPanel>;
+    /** The shown columns in side order (left outer → inner, then right outer → inner). */
+    readonly columns: readonly PlacedColumn[];
+    readonly rails: Partial<Record<Side, PlacedRail>>;
+    readonly notes: readonly PanelsNote[];
+    /** What is left for the documents. */
+    readonly pages: Rect;
+}
+/** The order columns give way in: unkept before kept, then the policy (oldest or newest), outer first, left first. */
+declare function giveWayOrder<C extends {
+    readonly side: Side;
+    readonly index: number;
+    readonly kept: boolean;
+    readonly age: number;
+}>(cols: readonly C[], order: "oldest" | "newest"): C[];
+declare function layoutPanels(defs: readonly PanelDef[], state: PanelsState, stage: Size, options?: Partial<PanelsOptions>): PanelsLayout;
+
+/**
+ * A drop target in the shape @n-uf/motion/drag takes: an id, a priority (1 most precise: a rail or a tab strip;
+ * 2 a slot; 3 a broad area such as floating anywhere), the zone the pointer hits, and optionally where the item
+ * lands, a label and whether it lands freely (no room is made for it).
+ */
+interface Target {
+    readonly id: string;
+    readonly priority: 1 | 2 | 3;
+    readonly hit: Rect;
+    readonly slot?: Rect;
+    readonly label?: string;
+    readonly free?: boolean;
+}
+
+/**
+ * The drop targets for dragging a panel, in the shape @n-uf/motion/drag takes (`{ id, priority, hit, slot?, free? }`),
+ * worked out from the state with the panel lifted out:
+ *
+ * - `column:<side>:<i>` (priority 2): a band across the line between two columns (or a side's edge): a new column
+ *   there, as wide as the panel's own width.
+ * - `into:<side>:<i>` (2): a column's area: the panel stacks at its bottom.
+ * - `rail:<side>` (1): the side's rail, or its outer edge: the panel docks folded.
+ * - `float` (3, free): anywhere; it floats where it is let go, kept in the view as the float option says.
+ *
+ * A place the panel may not take (its def's `sides` and `floats`, and `allows`) is no target, and neither is its own
+ * place (a drop there changes nothing). Targets carry a structured `place`, never words: the consumer names them.
+ */
+
+/** Where a drop puts a panel. `index` is a column index in the state with the panel lifted out. */
+type PanelPlace = {
+    readonly kind: "column";
+    readonly side: Side;
+    readonly index: number;
+} | {
+    readonly kind: "into";
+    readonly side: Side;
+    readonly index: number;
+} | {
+    readonly kind: "rail";
+    readonly side: Side;
+} | {
+    readonly kind: "float";
+};
+interface PanelTarget extends Target {
+    /** The panel dragged. */
+    readonly panel: string;
+    readonly place: PanelPlace;
+    /** Its rank in reading order (left to right across the stage, floating last). */
+    readonly order: number;
+    /** The state a drop here makes, with the pointer at `p` holding the panel at `grab` from its top-left corner. */
+    readonly make: (p: Point, grab: Point) => PanelsState;
+}
+interface PanelTargetInput {
+    readonly defs: readonly PanelDef[];
+    /** The state as it is, the panel still in its place. */
+    readonly state: PanelsState;
+    readonly id: string;
+    readonly stage: Size;
+    readonly options?: Partial<PanelsOptions>;
+    /** Places the panel may go beyond its def's rules (default: all of them). */
+    readonly allows?: (id: string, place: PanelPlace) => boolean;
+}
+/** How far a column band reaches on each side of its line, px; how wide a side's edge takes a rail drop when it has no rail. */
+declare const COLUMN_REACH = 22;
+declare const RAIL_EDGE = 10;
+/** A place's rank in reading order: the left side outer to inner, the right side inner to outer, floating last. */
+declare function placeRank(place: PanelPlace): number;
+/** Where a panel is now, as a place (a float, a column of its own, or stacked in one); null when placed nowhere. */
+declare function homePlace(state: PanelsState, id: string): PanelPlace | null;
+/** The targets for dragging `input.id`, in reading order. */
+declare function panelTargets(input: PanelTargetInput): PanelTarget[];
+/** A target's drop, laid out: where the panel lands. */
+interface PanelDrop {
+    readonly target: string;
+    readonly place: PanelPlace;
+    /** Same key, same place (a float's key carries where it lands). */
+    readonly key: string;
+    readonly state: PanelsState;
+    readonly layout: PanelsLayout;
+    /** Where the panel lands (its rail segment when it docks folded). */
+    readonly slot: Rect;
+    /** It lands in a rail. */
+    readonly hidden: boolean;
+    /** It floats where it is let go: no room is made for it. */
+    readonly free: boolean;
+}
+/** The drop on `target` with the pointer at `p` holding the panel at `grab`, laid out. */
+declare function panelDrop(input: PanelTargetInput, target: PanelTarget, p: Point, grab: Point): PanelDrop;
+interface PanelStop {
+    /** The target's id ("home" for the panel's own place). */
+    readonly id: string;
+    readonly place: PanelPlace;
+    /** The state a move here makes (the current one for home). */
+    readonly state: PanelsState;
+    readonly home: boolean;
+}
+interface PanelStopsOptions {
+    /** The panel's own place (`homePlace`) and the state as it is: a stop of its own in its reading-order position. */
+    readonly home?: {
+        readonly place: PanelPlace;
+        readonly state: PanelsState;
+    };
+    /** Floating as a stop at the end (default: left out); `at` and `grab` as for a drop (default: the stage's middle, the corner). */
+    readonly floats?: boolean | {
+        readonly at: Point;
+        readonly grab?: Point;
+    };
+}
+/** The panel's places in reading order, for the arrow keys and a "Move to" menu (`keyboardStops` calls this). */
+declare function panelStops(targets: readonly PanelTarget[], options?: PanelStopsOptions): PanelStop[];
+
+export { resizeFloat as $, dock as A, float as B, type Clock as C, DEFAULT_PANELS_OPTIONS as D, floatSize as E, FLOAT_HEIGHT as F, type GiveWay as G, focus as H, IDENTITY_VIEW as I, giveWayOrder as J, homePlace as K, keep as L, layoutPanels as M, liftPanel as N, open as O, type PanelsState as P, ownWidth as Q, RAIL_EDGE as R, type Side as S, panelDrop as T, panelStops as U, type View as V, type Where as W, panelTargets as X, pin as Y, placeRank as Z, resizeColumn as _, type PanelDef as a, samePlaces as a0, tick as a1, toPage as a2, toView as a3, toggleFold as a4, whereIs as a5, type Target as a6, COLUMN_REACH as b, type Column as c, type DockOptions as d, FLOAT_MIN as e, type FloatAt as f, type PanelDrop as g, type PanelKind as h, type PanelPlace as i, type PanelStop as j, type PanelStopsOptions as k, type PanelTarget as l, type PanelTargetInput as m, type PanelsLayout as n, type PanelsNote as o, type PanelsNoteCode as p, type PanelsOptions as q, type PanelsStart as r, type PlacedColumn as s, type PlacedPanel as t, type PlacedRail as u, SIDES as v, close as w, columnWidth as x, createPanels as y, defOf as z };

package/dist/targets.d.ts

@@ -1,20 +1,7 @@
+import { a6 as Target, l as PanelTarget, k as PanelStopsOptions, j as PanelStop } from './targets-BEqoVKbF.js';
 import { R as Rect, P as Point, S as Size } from './geometry-mL-GTRti.js';
 import { D as DeskState, g as Layout, a as Construction, O as Options } from './constructions-VDK_mwmz.js';
-import { Arrangement, HostId, HostSpec, GroupSize, Place } from './toolbar.js';
-
-/**
- * A drop target in the shape @n-uf/motion/drag takes: an id, a priority (1 most precise: a rail or a tab strip;
- * 2 a slot; 3 a broad area such as floating anywhere), the zone the pointer hits, and optionally where the item
- * lands, a label and whether it lands freely (no room is made for it).
- */
-interface Target {
-    readonly id: string;
-    readonly priority: 1 | 2 | 3;
-    readonly hit: Rect;
-    readonly slot?: Rect;
-    readonly label?: string;
-    readonly free?: boolean;
-}
+import { Place, Arrangement, HostId, HostSpec, GroupSize } from './toolbar.js';
 
 /**
  * Each desk construction's drop targets, as pure functions: from the state with the dragged item lifted out, a list
@@ -73,7 +60,7 @@ declare function deskDrop(input: DeskTargetInput, target: DeskTarget, p: Point,
 /**
  * Toolbar group targets: a host's insertion points (lines between groups, priority 2) and empty zones (priority 1),
  * and floating over the content (priority 3). A group's own place is home, never a target: its stretch comes back
- * in `own`, for the consumer to join to the drag's home.
+ * in `own`, for the consumer to join to the drag's home. A place `allows` forbids is no host target either.
  */
 
 /** How far a line's hit reaches beyond the host's thickness on each side; an empty zone's. */
@@ -87,9 +74,17 @@ interface ToolbarTarget<G extends string = string> extends Target {
     readonly vertical: boolean;
     /** The insertion line (3 px, inset 4 px from the host's sides) in stage coordinates; for an empty zone, at its middle. */
     readonly line: Rect;
+    /** Where the group lands, in stage coordinates: its rect in the host once the drop is made. */
+    readonly slot: Rect;
     /** The arrangement a drop here makes. */
     readonly arrangement: Arrangement<G>;
 }
+/**
+ * Where a group may go: a host's place, or floating. `hostTargets` leaves out a place it refuses; for floating, the
+ * consumer adds `floatTarget` only when `allows(group, "float")`, so one rule covers both. `place.index` counts the
+ * groups in that zone without the dragged one (as `insertGroup` does): 0 is before all of the others.
+ */
+type Allows<G extends string> = (group: G, place: Place | "float") => boolean;
 interface HostTargetsInput<G extends string> {
     readonly group: G;
     /** The arrangement as it is, the group still in its place. */
@@ -97,10 +92,20 @@ interface HostTargetsInput<G extends string> {
     readonly host: HostId;
     /** The host's top-left corner in stage coordinates. */
     readonly origin: Point;
-    readonly spec: HostSpec;
+    readonly spec: HostSpec<G>;
     readonly size: GroupSize<G>;
     /** A group's name in the labels (default: its id). */
     readonly label?: (g: G) => string;
+    /** Where the group may go (default: anywhere). A place it may not go is left out. */
+    readonly allows?: Allows<G>;
+    /**
+     * Where this host is, and how long, once a drop has made `arrangement` (a host may grow or appear when it gets a
+     * group); default: where it is now. The targets' `slot`s are laid out there.
+     */
+    readonly hostAfter?: (arrangement: Arrangement<G>) => {
+        readonly origin: Point;
+        readonly spec: HostSpec<G>;
+    };
 }
 /** The targets a host offers a dragged group, zone by zone in order, and the stretches that are its own place. */
 declare function hostTargets<G extends string>(input: HostTargetsInput<G>): {
@@ -113,14 +118,67 @@ interface ToolbarFloatTarget<G extends string = string> extends Target {
     /** The group's top-left corner relative to the stage, and the arrangement, for a drop with the pointer at `p`. */
     readonly make: (p: Point, grab: Point) => Arrangement<G>;
 }
-/** Floating over the content (`stage`, in stage coordinates): the group's top-left corner kept on the stage. */
-declare function floatTarget<G extends string>(input: {
+interface FloatTargetInput<G extends string> {
     readonly group: G;
     readonly arrangement: Arrangement<G>;
+    /** The content the group floats over, in stage coordinates. */
     readonly stage: Rect;
+    /** The group's size as it floats. */
     readonly width: number;
     readonly height: number;
-}): ToolbarFloatTarget<G>;
+}
+/**
+ * Floating over the content (`stage`, in stage coordinates): the group's top-left corner kept on the stage. A
+ * group that may not float simply gets no float target: add it only when your rule allows it, with the same
+ * `allows` you give `hostTargets`: `...(allows(group, "float") ? [floatTarget(input)] : [])`.
+ */
+declare function floatTarget<G extends string>(input: FloatTargetInput<G>): ToolbarFloatTarget<G>;
+
+/**
+ * Keyboard stops: every place a toolbar group can go, in one list in reading order, for the arrow keys and a
+ * "Move to" menu alike. A consumer steps through the list; it never parses target ids.
+ */
+
+/** The hosts in reading order: the title bar, the top bar, the left edge, the right edge, the bottom bar. */
+declare const HOST_READING_ORDER: readonly HostId[];
+interface KeyboardStop<G extends string = string> {
+    /** The target's id ("home" for the group's own place). */
+    readonly id: string;
+    readonly label: string;
+    /** Where in a host it is; null for floating. */
+    readonly place: Place | null;
+    /** The arrangement a move here makes (the current one for home). */
+    readonly arrangement: Arrangement<G>;
+    /** The group's own place: where the keyboard starts, and a move there changes nothing. */
+    readonly home: boolean;
+}
+interface KeyboardStopsOptions<G extends string> {
+    /** The group's own place, as a stop of its own in its reading-order position (the targets leave it out). */
+    readonly home?: {
+        readonly place: Place;
+        readonly arrangement: Arrangement<G>;
+        readonly label?: string;
+    };
+    /**
+     * Floating targets as stops at the end (default: left out). `at` is where the pointer would drop it and `grab`
+     * where it holds the group (default: the float target's middle, the group's top-left corner).
+     */
+    readonly floats?: boolean | {
+        readonly at: Point;
+        readonly grab?: Point;
+    };
+}
+/**
+ * The places a group can go, in reading order: hosts title → top → left → right → bottom, zones start → centre →
+ * end, then each insertion point in order; the group's own place among them when `home` is given; floating targets
+ * at the end only when `floats` asks for them. One list serves the arrow keys and a "Move to" menu.
+ *
+ * Given panel targets (`@n-uf/placement/panels`' `panelTargets`), the same for a panel: left to right across the
+ * stage (the left rail, the left side's lines and columns outer to inner, the right side's inner to outer, the right
+ * rail), floating last when asked; each stop carries the state a move there makes (`panelStops`).
+ */
+declare function keyboardStops(targets: readonly PanelTarget[], options?: PanelStopsOptions): PanelStop[];
+declare function keyboardStops<G extends string>(targets: readonly (ToolbarTarget<G> | ToolbarFloatTarget<G>)[], options?: KeyboardStopsOptions<G>): KeyboardStop<G>[];
 
 /**
  * A pane's drop zones: a centre rectangle (put it in the pane's place, merge or swap) and four edge trapezoids (put
@@ -165,4 +223,4 @@ declare function paneCentre(size: Size, options?: PaneZoneOptions): PaneCentre;
  */
 declare function paneZone(rect: Rect, point: Point, previous?: PaneZone | null, options?: PaneZoneOptions): PaneZone;
 
-export { type DeskDrop, type DeskTarget, type DeskTargetInput, type HostTargetsInput, LINE_REACH, type Made, PANE_EDGES, PANE_ZONE_DEFAULTS, type PaneCentre, type PaneZone, type PaneZoneOptions, SNAP, type Target, type ToolbarFloatTarget, type ToolbarTarget, ZONE_REACH, deskDrop, deskTargets, floatTarget, hostTargets, paneCentre, paneZone };
+export { type Allows, type DeskDrop, type DeskTarget, type DeskTargetInput, type FloatTargetInput, HOST_READING_ORDER, type HostTargetsInput, type KeyboardStop, type KeyboardStopsOptions, LINE_REACH, type Made, PANE_EDGES, PANE_ZONE_DEFAULTS, type PaneCentre, type PaneZone, type PaneZoneOptions, SNAP, Target, type ToolbarFloatTarget, type ToolbarTarget, ZONE_REACH, deskDrop, deskTargets, floatTarget, hostTargets, keyboardStops, paneCentre, paneZone };