@graview/layout 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,404 @@
+export type Plane = 0 | 1 | 2;
+/**
+ * An aggregate node is first-class, not a scale fallback. "People" is a
+ * legitimate view of a kind, which is why grouping and semantic zoom are one
+ * mechanism running in both directions.
+ */
+export interface Aggregate {
+    readonly kind: string;
+    readonly memberIds: readonly string[];
+    /** Plural label from the kind's declaration, e.g. "People". */
+    readonly label: string;
+    /**
+     * How many members sit BEHIND the horizon — retired under their kind's
+     * declared lifecycle and not in memberIds while the view is on "now".
+     * Advertised, never hidden: archived must not mean invisible-and-
+     * forgotten.
+     */
+    readonly retired?: number;
+    /**
+     * Where pressing it goes, for an aggregate the relation band drew because
+     * not all could stand (docs/scale.md): a group opens in place, through the
+     * `expanded` stop; "+N more" opens the kind's picture, filtered by the
+     * relation. Absent on a kind's own group, which travels as it always did.
+     */
+    readonly opens?: Opens;
+}
+/** Where pressing a band aggregate goes: open in place, or through to the kind's picture. */
+export type Opens = {
+    readonly in: "place";
+} | {
+    readonly in: "picture";
+    readonly focus: string;
+    readonly within: Readonly<Record<string, string>>;
+};
+/**
+ * Why a node is on plane 1 at all: the edge that reached it, in the schema's
+ * own words.
+ *
+ * Every edge declaration already carries a description — "who does the run",
+ * "a nap that must not be interrupted" — and until now nothing in the
+ * interface ever showed it. Carrying it through the layout means a raised
+ * node can say what its relationship to the focus IS, rather than merely
+ * sitting near it and leaving the reader to guess.
+ */
+export interface Via {
+    readonly edgeKind: string;
+    readonly direction: "out" | "in";
+    /**
+     * How the relation reads FROM THE FOCUS: the declaration's `description`
+     * along an outgoing edge, its `inverse` along an incoming one. Absent when
+     * the declaration has no words for this direction.
+     */
+    readonly description?: string;
+}
+export interface LayoutNode {
+    /** A real node id, or `aggregate:<kind>` for a group. */
+    readonly id: string;
+    readonly kind: string;
+    readonly plane: Plane;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    /** Set when this node stands in for a group rather than one graph node. */
+    readonly aggregate?: Aggregate;
+    /**
+     * The size this view should LAY ITSELF OUT at, when that differs from the
+     * size it is drawn at.
+     *
+     * A view asked to lay out at a third of its intended width has no reason
+     * to work, and none of the lenses was written to: the coverage matrix
+     * piles its rotated headers into a corner and clips its rows. Shrinking
+     * should mean the same picture, smaller — render at the natural size and
+     * scale the result, which is what a captured texture would do anyway.
+     */
+    readonly natural?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /**
+     * How far back this node sits WITHIN its plane. 1 is fully at the plane's
+     * depth, 0 is pulled forward toward the one in front of it.
+     *
+     * The planes are discrete because the model is discrete, but a row of ten
+     * cards all at exactly plane 2 reads as a flat strip pinned to the bottom
+     * of the screen. Giving each a depth of its own turns the row into an arc
+     * curving away, and turns the thing in focus into something you are
+     * standing in front of.
+     */
+    readonly depth?: number;
+    /** Set on plane 1 when this node was reached by following an edge. */
+    readonly via?: Via;
+    /**
+     * A group whose members are currently raised onto plane 1.
+     *
+     * It stays where it was, emptied, so the eye can tie the relation plane
+     * back to where it came from. Without it the only evidence of what is
+     * raised is the breadcrumb, and a spatial interface should not need to be
+     * read.
+     */
+    readonly raised?: boolean;
+    /**
+     * How near this kind is to the one in focus: one declared edge away, or
+     * further.
+     *
+     * Nine kinds as nine identical thumbnails says nothing about which of them
+     * matter. The rank comes from the SCHEMA rather than the graph, so an
+     * unrelated edit can never promote a kind and shuffle the strip.
+     */
+    readonly rank?: "primary" | "secondary";
+    /**
+     * The kind card this one hangs off, when it is reachable only THROUGH that
+     * one. A nested relationship should read as nested rather than being
+     * flattened into a sibling.
+     */
+    readonly nestedUnder?: string;
+    /**
+     * The kinds this card STANDS FOR, when the row could not hold them all at
+     * a width their names can be read at.
+     *
+     * A district is read, not glanced at, so the row never squeezes a name
+     * below a word: past what it can hold it keeps the ones that fit and hands
+     * the rest to one card that names them. Not a kind of its own — it has no
+     * members and no figure — which is why it is said here rather than by
+     * giving it a kind nobody declared.
+     */
+    readonly beyond?: readonly string[];
+    /**
+     * A group standing for the kind currently in focus.
+     *
+     * It stays on the kinds plane rather than being removed, so the strip is a
+     * constant map and you can see that the picture above IS this kind.
+     */
+    readonly focused?: boolean;
+    /**
+     * An aggregate card OPENED IN PLACE — from altitude, a district showing
+     * its members without dissolving into them. Inside the stack an expanded
+     * aggregate dissolves instead; up on the ring dissolving would re-flow
+     * every stop and break the map.
+     */
+    readonly opened?: boolean;
+    /**
+     * HOW MANY ROWS OF MEMBERS an opened district has room for: what the
+     * layout reserved under its nameplate, in rows of `ROSTER_ROW`. The view
+     * lists that many and counts the rest, so the roster ends where the room
+     * does rather than running under the district below.
+     */
+    readonly openedRows?: number;
+    /**
+     * A card in a CROWDED band: drawn as a chip whatever its slot's size. Its
+     * row is sized for a group card's two lines, which is short of a record's
+     * summary, and a summary cut to its title and a sliver read as broken.
+     */
+    readonly compact?: boolean;
+    /**
+     * WHERE THIS DISTRICT STANDS IN THE CITY, in lattice cells — its address.
+     *
+     * Set on a kind card at altitude, from the declaration's own map
+     * (`cityMap`), never from the data: the corner a person remembers is the
+     * corner they get back. `side` is how many cells it takes today.
+     */
+    readonly plot?: {
+        readonly col: number;
+        readonly row: number;
+        readonly side: number;
+    };
+    /**
+     * THE SCREEN OF A DRIVE-IN: this plane-0 node is a kind's own picture,
+     * standing on that kind's plot from altitude rather than floating in the
+     * middle. Names the kind, so the audience strip in front of it can be
+     * found (`whereIs("screen:<kind>")`) and the tween can carry it.
+     */
+    readonly screenOf?: string;
+    /** True when the user pinned this position rather than the layout choosing it. */
+    readonly pinned: boolean;
+}
+export interface Connector {
+    readonly id: string;
+    /** The edge kind, so stroke treatment can carry meaning. */
+    readonly kind: string;
+    /**
+     * Both ends resolve to the same drawn thing — "a task waits for a task".
+     *
+     * Real and worth drawing: it is a fact about the domain, and the one place
+     * you would look for it is the picture of the whole domain. Drawn as a loop
+     * rather than as a line of zero length.
+     */
+    readonly loop?: boolean;
+    /**
+     * The ONE graph edge this line stands for, when it stands for exactly
+     * one — both drawn endpoints are the real nodes. A line into a group
+     * bundles many edges and says "some of these"; only a single line is an
+     * honest thing to select and act on.
+     */
+    readonly single?: {
+        readonly from: string;
+        readonly to: string;
+    };
+    /**
+     * EVERY graph edge this line stands for, in the order the walk met them.
+     *
+     * A line into a group is a bundle, and a bundle that only knew its count
+     * could not be unpicked: the week's panel draws each session as its own
+     * span, and a renderer that can see the span wants to start the session's
+     * line THERE rather than at the panel's centre. That needs the real ends
+     * of each edge, not just the drawn ends of the line. `single` is the
+     * one-edge case of this, kept because a line that stands for one edge is
+     * the only honest thing to select.
+     */
+    readonly edges: readonly {
+        readonly from: string;
+        readonly to: string;
+    }[];
+    readonly from: string;
+    readonly to: string;
+    /** Endpoints in layout space, centre to centre. */
+    readonly x1: number;
+    readonly y1: number;
+    readonly x2: number;
+    readonly y2: number;
+}
+/**
+ * THE LATTICE THE CITY WAS DRAWN ON, so the ground can draw the same one
+ * and the camera can know how far the city reaches. `cell` is one lattice
+ * cell's width in pixels (its height is half); `originX/Y` is where cell
+ * (0,0) meets the canvas before the pan. `extent` is the city's bounding
+ * box in canvas pixels, unpanned.
+ */
+export interface CityFrame {
+    readonly cell: number;
+    readonly originX: number;
+    readonly originY: number;
+    /**
+     * THE PAN THIS CITY WAS PLACED WITH, so the ground can ride the same
+     * tween its cards do.
+     *
+     * The pan is baked into every card's coordinates at layout time, which
+     * is what lets two layouts be interpolated into motion. The lattice and
+     * the plots under them were drawn from the LIVE pan instead — so the
+     * ground snapped to its destination on the frame the view changed while
+     * the cards were still on their way, which reads as the picture flashing
+     * to the new place and the buildings catching up.
+     */
+    readonly pan: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly extent: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+    /** How much of an opened district's roster the city kept room for: 1 is all of it. */
+    readonly openedShare?: number;
+}
+export interface Layout {
+    readonly nodes: readonly LayoutNode[];
+    readonly connectors: readonly Connector[];
+    readonly width: number;
+    readonly height: number;
+    /** Present at altitude: the lattice the districts were placed on. */
+    readonly city?: CityFrame;
+}
+export interface LayoutOptions {
+    readonly width?: number;
+    readonly height?: number;
+    /** Size of the focus view at plane 0. */
+    readonly focusSize?: {
+        width: number;
+        height: number;
+    };
+    readonly relationSize?: {
+        width: number;
+        height: number;
+    };
+    readonly contextSize?: {
+        width: number;
+        height: number;
+    };
+    readonly gap?: number;
+    /**
+     * WHAT ONE `rem` IS WORTH, IN PIXELS — the reader's own text size.
+     *
+     * The cards in this layout hold text, and that text is sized in `rem` so
+     * a reader who asks for bigger words gets them everywhere. The cards were
+     * sized in pixels off the stage, so they did not hear about it: at 200%
+     * every name in the city doubled inside a district card that stayed
+     * exactly 230×97, and the picture came apart — a headline in a glyph.
+     *
+     * Sizing them in this unit instead makes the city grow WITH the reader.
+     * It grows until the ring is full and then stops, because a card is only
+     * worth making bigger while it still has somewhere to stand.
+     *
+     * 16 is the browser's own default and therefore the no-op: every existing
+     * caller lays out exactly as it did.
+     */
+    readonly unit?: number;
+    /** Plural labels by kind, from the schema. */
+    readonly plurals?: Readonly<Record<string, string>>;
+    /**
+     * The day the horizon is judged against (ISO date). Injectable so a test
+     * or a pinned survey judges a different day; defaults to the real one.
+     */
+    readonly today?: string;
+    /**
+     * Node kinds this installation has turned OFF — a workspace's disabled
+     * modules, projected once by the store. Their nodes stay in the graph and
+     * simply are not drawn: no kind card, no membership, no raised plane.
+     * Turning a module back on is the whole undo.
+     */
+    readonly hiddenKinds?: readonly string[];
+    /**
+     * WHAT A NODE JUDGES, by its id: the nodes its current violations name.
+     * A rule has no edges, so a focused rule used to raise nothing — or,
+     * with a relation named, every node of that kind wholesale — and its
+     * card said nothing was connected while the picture showed twelve. What
+     * a rule is about is derivable from its violations; the scene supplies
+     * them here so the layout can draw them as its neighbourhood.
+     */
+    readonly judged?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * WHAT STANDS AS ITSELF when a relation does not fit the band: the
+     * selection and its reach, the search's hits, the flagged, the recently
+     * written. The scene knows them; the layout only ranks by them.
+     */
+    readonly relevance?: {
+        readonly chosen?: ReadonlySet<string>;
+        readonly hits?: ReadonlySet<string>;
+        readonly flagged?: ReadonlySet<string>;
+        readonly touched?: ReadonlyMap<string, number>;
+    };
+    /**
+     * Room the picture must leave for chrome that lives ON the scene — the
+     * left rail at altitude, where the relation key and the inspector sit.
+     * The ring and the focused card centre within what is left, so a
+     * district is never drawn under a pane. Nothing is reserved by default.
+     */
+    readonly inset?: {
+        readonly left?: number;
+        readonly right?: number;
+    };
+    /**
+     * Kinds whose group is shown by the framework's own list rather than a
+     * view the app wrote. From altitude a focused group of such a kind is its
+     * district, opened — drawing the list scaled in the middle AND the same
+     * names in the district was the same thing twice. A group with a real
+     * view — a week, a board — keeps its scaled card, since that picture is
+     * the thing you were standing in.
+     */
+    readonly plainGroups?: readonly string[];
+    /**
+     * THE ORDER A BLANK INSTALLATION FILLS ITS KINDS — `beginning(app).order`
+     * — which is the order the city is walked in. Sorted ids otherwise, which
+     * is deterministic too, only less meaningful.
+     */
+    readonly cityOrder?: readonly string[];
+    /** Hand-laid plots by kind, from a brand kit; a kind's own `plot` wins first. */
+    readonly plots?: Readonly<Record<string, {
+        readonly col: number;
+        readonly row: number;
+    }>>;
+    /**
+     * THE SHOWINGS each kind has — its named Places — so a focused picture
+     * from altitude can stand on its kind's plot as a screen, and a picture
+     * over two kinds (`across`) on the road between them. A kind with none
+     * has no drive-in: its group opens in place, as it always did.
+     */
+    readonly screens?: Readonly<Record<string, readonly {
+        readonly as: string;
+        readonly title: string;
+        readonly across?: string;
+    }[]>>;
+    /**
+     * FLY CLOSER. A factor on the city's cell from altitude — 1 is the whole
+     * map fitted to the window; 1.5 is the camera brought in toward the
+     * picture a person chose, plots and villages and roads all bigger, the
+     * city allowed past the window's edge (the camera pans to reach it).
+     */
+    readonly cityZoom?: number;
+    /**
+     * HOW TALL THE PICTURE ON THE BILLBOARD ACTUALLY DRAWS, in the lens's own
+     * natural pixels, measured by whoever renders it. A lens is laid out in a
+     * box as tall as the window so it never scrolls, but a short lens fills
+     * only the top of it — and a billboard sized to the whole box stood its
+     * picture a village's height above the kerb, floating over the next
+     * district with empty room beneath. Cut to what is drawn, the picture's
+     * foot is on the kerb. Absent (or not yet measured): the whole box.
+     */
+    readonly screenHeight?: number;
+}
+/**
+ * Three bands, chosen so the planes never overlap at their own scales.
+ *
+ * Sizes are in layout units; the plane's scale shrinks the drawn box in
+ * place, so a band's height is its size times that scale.
+ */
+/**
+ * Sizes here are CAPS, not fixed boxes: a band fits its contents across the
+ * canvas and never exceeds the cap. Heights come from the band proportions in
+ * `layout()`, which is what keeps the composition together at any size.
+ */
+export declare const DEFAULT_OPTIONS: Required<Omit<LayoutOptions, "plurals" | "today" | "hiddenKinds" | "inset" | "plainGroups" | "judged" | "relevance" | "cityOrder" | "plots" | "screens" | "cityZoom" | "screenHeight">>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,27 @@
+/**
+ * Three bands, chosen so the planes never overlap at their own scales.
+ *
+ * Sizes are in layout units; the plane's scale shrinks the drawn box in
+ * place, so a band's height is its size times that scale.
+ */
+/**
+ * Sizes here are CAPS, not fixed boxes: a band fits its contents across the
+ * canvas and never exceeds the cap. Heights come from the band proportions in
+ * `layout()`, which is what keeps the composition together at any size.
+ */
+export const DEFAULT_OPTIONS = {
+    width: 1200,
+    height: 760,
+    focusSize: { width: 1200, height: 420 },
+    relationSize: { width: 240, height: 140 },
+    /*
+     * A kind card is a GLYPH: a name, a count, and how much of it is in
+     * trouble. At 150 it was sized for two clamped lines of prose that have
+     * since moved to the tooltip, and the band it sits in took a fifth of the
+     * window to hold cards covering a tenth of it.
+     */
+    contextSize: { width: 300, height: 104 },
+    gap: 16,
+    unit: 16,
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAoWA;;;;;GAKG;AACH;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAA4L;IACtN,KAAK,EAAE,IAAI;IACX,MAAM,EAAE,GAAG;IACX,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;IACvC,YAAY,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE;IACzC;;;;;OAKG;IACH,WAAW,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE;IACxC,GAAG,EAAE,EAAE;IACP,IAAI,EAAE,EAAE;CACT,CAAC"}

package/dist/view-state.d.ts

@@ -0,0 +1,189 @@
+/**
+ * A view state is a stop. Every stop is a URL, so the back button returns to
+ * exactly the view you left — no free orbit, nothing unnameable.
+ */
+export interface Pin {
+    readonly x: number;
+    readonly y: number;
+}
+export interface ViewState {
+    /** The node at plane 0, live and editable. Null means the default view. */
+    readonly focusId: string | null;
+    /**
+     * What plane 1 shows: an edge kind to follow from the focus, or a node kind
+     * to raise. Null leaves plane 1 empty.
+     */
+    readonly relation: string | null;
+    /** Aggregates the user has opened, by aggregate id. */
+    readonly expanded: readonly string[];
+    /** User positions that override the computed ones. */
+    readonly pins: Readonly<Record<string, Pin>>;
+    /**
+     * Where the camera has been dragged, in canvas pixels.
+     *
+     * A stop, like everything else here: it goes in the URL, it interpolates,
+     * and the same address gives the same picture. A pan held outside the view
+     * state would be the one thing about the scene you could not share, link to
+     * or go back to.
+     */
+    readonly pan?: Pin;
+    /**
+     * Looking at the whole graph from outside the plane stack.
+     *
+     * A view state rather than a mode, because it has to INTERPOLATE from
+     * wherever you were: the kinds already on screen fly from their row into a
+     * ring, and the thing you were looking at recedes into the middle. A
+     * separate surface could only cut, and cutting loses the one thing an
+     * overview is for.
+     */
+    readonly overview?: boolean;
+    /**
+     * The HORIZON widened: retired nodes shown alongside current ones.
+     *
+     * A stop like every other — a URL, a back-button entry, tweenable — so
+     * "show me the retired agreements" is a place you go and come back from,
+     * not a setting you forget you flipped.
+     */
+    readonly past?: boolean;
+    /**
+     * Modules drawn only for those who administer them, SHOWN at this stop:
+     * the installation's own users and invitations raised beside the domain.
+     * A stop like any other — in the URL, so an embed can open on it and Back
+     * knows the way out — and never on for a seat that may not see them; the
+     * provider keeps what it may not show out of the picture whatever the
+     * address says.
+     */
+    readonly shown?: readonly string[];
+    /**
+     * What is SELECTED, as part of the stop.
+     *
+     * Selection used to live only in component state, which broke the central
+     * promise twice over: back/forward restored the view but stranded the
+     * selection — the inspector kept talking about a thing from a stop you had
+     * already left — and a shared link could name the place but not the thing.
+     * If the pane on the left depends on it, it is part of where you are.
+     */
+    readonly selection?: readonly string[];
+    /**
+     * Zoomed in close: the focus takes most of the scene — most, not all —
+     * and the kinds shelf and any raised relation recede rather than vanish.
+     *
+     * A view state rather than a page, because jacking in used to JUMP: a
+     * modal document over the scene, isolated from every relation the thing
+     * has. A stop interpolates from wherever you were, so going deeper reads
+     * as zooming in and leaving as zooming out, and the back button knows it.
+     */
+    readonly zoom?: boolean;
+    /**
+     * WHERE A VIEW IS INSIDE ITSELF.
+     *
+     * A calendar showing October is somewhere, and it is somewhere a person
+     * can be sent, come back to and press Back out of. Everything else about
+     * a stop is the framework's own vocabulary — a focus, a relation, an
+     * altitude — and a view that arranges its own dimension has nowhere to
+     * say so, which is why the week grid could only ever show one week.
+     *
+     * A flat map of short keys, written into the fragment as `in.<key>`,
+     * owned by whichever view is drawing. The framework never reads a key; it
+     * only carries it, so that "the month I was looking at" is a URL like
+     * every other place in this system rather than component state that the
+     * back button silently loses.
+     */
+    readonly within?: Readonly<Record<string, string>>;
+    /**
+     * WHAT IS BEING LOOKED FOR, over the whole picture.
+     *
+     * A search is a stop: `#q=van` lights what the words find and dims the
+     * rest wherever you are looking, a link carries it, and Back returns to
+     * it. Not a key of `within`, because it is not one view's business — it
+     * applies to every district at once — and it outlives a change of focus,
+     * so descending into a lit district keeps the rest of the city lit
+     * behind you. Typing is an ADJUSTMENT of the stop, like a pan: the
+     * address is replaced on each keystroke rather than pushed.
+     */
+    readonly q?: string;
+}
+export declare const EMPTY_VIEW: ViewState;
+/**
+ * Serialises a view to a URL fragment. Keys are sorted and lists are sorted,
+ * so the same view always produces the same string — which is what makes
+ * "did the view change?" a string comparison and history entries stable.
+ */
+export declare function toUrl(state: ViewState): string;
+export declare function fromUrl(url: string): ViewState;
+/** Two views are the same stop when they serialise the same. */
+export declare function sameView(a: ViewState, b: ViewState): boolean;
+/**
+ * A RELATION in the selection: `edge:<kind>:<from>:<to>`, each part escaped.
+ *
+ * Lines joined the selection model after nodes did, and for the same
+ * reason the selection is in the URL at all — an inspector about a thing
+ * you cannot name is an inspector you cannot share or return to.
+ *
+ * THE SEPARATOR CANNOT BE A CHARACTER AN ID MAY CONTAIN. This used to say
+ * that node ids never hold a ":" and leave it there, and the framework's own
+ * `ctx.freshId(label, kind)` mints "item:buy-milk" — so in every scaffolded
+ * app the three-part split came back with five parts, `edgeOfSelection`
+ * returned null, and a selected line fell through to the inspector's
+ * "nothing can be done with this mix of kinds" while the strip's title was
+ * the raw selection string. Escaping each part is the fix that does not
+ * depend on what an app calls things.
+ */
+export declare const EDGE_SELECTION_PREFIX = "edge:";
+export declare function edgeSelectionId(kind: string, from: string, to: string): string;
+export interface EdgeRef {
+    readonly kind: string;
+    readonly from: string;
+    readonly to: string;
+}
+/** The edge a selection entry names, or null when it names a node. */
+export declare function edgeOfSelection(id: string): EdgeRef | null;
+export declare function withFocus(state: ViewState, focusId: string | null): ViewState;
+export declare function withRelation(state: ViewState, relation: string | null): ViewState;
+/**
+ * Moves a view along its own dimension — the month a calendar is showing,
+ * the range it is showing it in.
+ *
+ * A stop like any other: it goes in the address, Back returns to it, and a
+ * link carries it. `null` clears the key rather than writing an empty one,
+ * so "no answer" and "the answer is empty" stay different things.
+ */
+export declare function withWithin(state: ViewState, key: string, value: string | null): ViewState;
+export declare function withOverview(state: ViewState, overview: boolean): ViewState;
+/** Show or hide a module drawn only for those who administer it. */
+export declare function withShown(state: ViewState, module: string, shown: boolean): ViewState;
+/** Look for words across the picture, or stop looking. Blank is no search. */
+export declare function withQuery(state: ViewState, q: string | null): ViewState;
+/**
+ * Stop looking: the search, and the words it carried into the district it
+ * lit. A row's own words — typed there, different from the search — stay.
+ */
+export declare function withoutSearch(state: ViewState): ViewState;
+/** Widen the horizon to include the past, or narrow it back to now. */
+export declare function withPast(state: ViewState, past: boolean): ViewState;
+/**
+ * Change what is selected. An empty selection leaves no key behind — the
+ * default state serialises to the default URL.
+ */
+export declare function withSelection(state: ViewState, selection: readonly string[]): ViewState;
+/** Zoom the focus in close, or back out. */
+export declare function withZoom(state: ViewState, zoom: boolean): ViewState;
+/**
+ * Expanding an aggregate and collapsing it are the same operation in two
+ * directions — one code path, so semantic zoom and grouping cannot drift
+ * apart.
+ */
+export declare function toggleExpanded(state: ViewState, aggregateId: string): ViewState;
+/**
+ * Move the camera. `null` puts it back.
+ *
+ * Panning is an ADJUSTMENT of the stop you are on rather than a new stop —
+ * the same reason a pin is. `useUrlSync` replaces rather than pushes for both,
+ * so one drag is one history entry rather than sixty, and Back still means
+ * "the place I was before", not "one pixel ago".
+ */
+export declare function withPan(state: ViewState, pan: Pin | null): ViewState;
+/** Put everything the user moved back where the layout wanted it. */
+export declare function withoutMoves(state: ViewState): ViewState;
+export declare function withPin(state: ViewState, id: string, pin: Pin | null): ViewState;
+//# sourceMappingURL=view-state.d.ts.map

package/dist/view-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-state.d.ts","sourceRoot":"","sources":["../src/view-state.ts"],"names":[],"mappings":"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"}