@jmbarzee/force-graph 0.0.1

package/dist-lib/components/GraphView.d.ts

@@ -0,0 +1,213 @@
+import { default as React } from 'react';
+import { Graph, GraphNode } from '../graph/model';
+import { FilterState, AxisLocks } from '../filter/types';
+import { AxisId } from '../graph/axis';
+import { Theme } from '../graph/scheme';
+import { ThemeChoice } from './graph-view/useTheme';
+import { LayoutState } from '../graph/layout';
+import { Taxonomy } from '../graph/taxonomy';
+import { ActiveGroup, NodeGroup } from '../graph/groups';
+import { SearchState } from './FilterBar';
+import { FocusRequest } from './graph-view/focus';
+import { GraphDiagnostic } from '../graph/validate';
+export type { SearchState } from './FilterBar';
+export type { FocusRequest } from './graph-view/focus';
+/** A node's position in the layout, in world units. */
+export interface Position {
+    x: number;
+    y: number;
+}
+/** The host's action for a node, offered in the hover box: its label, and what it does with the host's own node. */
+export interface NodeAction {
+    label: string;
+    onSelect: (node: GraphNode) => void;
+}
+/** What `groupsControl` may ask of the view. */
+export interface GroupsControl {
+    /** Emphasise one group (a legend row under the pointer), or none; the view glows it stronger. */
+    emphasize(id: string | null): void;
+}
+/** Which parts of the pane's own chrome are offered; every part is on by default. */
+export interface GraphViewChrome {
+    /** The search control in the bar. */
+    search?: boolean;
+    /** The lock toggle on each axis. Default: only when the host controls `locks` with `onLocksChange` — a one-view host has nothing to lock against, and a value without its callback is read-only. */
+    locks?: boolean;
+    /** The Fit / theme / Play cluster and the node count. */
+    transport?: boolean;
+    /** The pane's own list of the graph's defects under the bar. */
+    diagnostics?: boolean;
+    /** The shortcuts panel and the `?` key that opens it. */
+    shortcuts?: boolean;
+    /** The control panel (the forces, the node scale). */
+    controls?: boolean;
+    /** The Auto / Light / Dark button. It sits in the transport cluster, so `transport: false` hides it too. */
+    themeToggle?: boolean;
+    /** The "dependencies / dependents" line in the hover box. */
+    directionLine?: boolean;
+    /** Centre and zoom to a node's neighbours on double-click. */
+    activateZoom?: boolean;
+}
+/**
+ * What a host may ask of a mounted view. `focusNode` is the whole focus
+ * recipe in one call: widen the filter just enough on the axes shown
+ * (overriding a lock, which flashes), centre on the node once the layout has
+ * settled, and select it.
+ */
+export interface GraphViewHandle {
+    /** Reveal, centre and select a node by id. False when the id is not in the graph or the filter cannot be widened to show it. */
+    focusNode(id: string): boolean;
+    /** Select a node, or clear the selection with null. An id the graph does not hold is ignored. */
+    select(id: string | null): void;
+    /** Frame the visible nodes. */
+    fit(): void;
+    /** Every node's position, by id — a layout the host may keep and hand back as `defaultPositions`. */
+    getPositions(): Map<string, Position>;
+    /** Move nodes to the given positions (pinned ones stay) and let the layout settle around them. */
+    setPositions(positions: ReadonlyMap<string, Position>): void;
+}
+/**
+ * The view's inputs. Only `graph` is required, with a taxonomy from either the
+ * `taxonomy` prop or an `TaxonomyContext.Provider` above. Every piece of state
+ * follows the React convention: pass the value and its callback to control it,
+ * or neither and the view keeps it; a callback alone still reports changes.
+ */
+export interface GraphViewProps {
+    /** The graph, built by the host from whatever it reads. Keep one object until its nodes or edges change. */
+    graph: Graph;
+    /** The taxonomy, when not supplied through `TaxonomyContext`. */
+    taxonomy?: Taxonomy;
+    /**
+     * Where the pane's shortcuts listen. `pane` (the default): the root is
+     * focusable and handles the keys that reach it, so a host page keeps Tab
+     * and Space for its own controls. `global`: the window — for a host whose
+     * whole page is this pane, or a tab shell's active tab. `none`: no
+     * shortcuts — a tab shell's hidden tab.
+     */
+    keyboard?: 'pane' | 'global' | 'none';
+    /** Where nodes start, by id — a layout the host kept (`getPositions`). Read whenever the simulation is built; a node the live layout already holds keeps its place. */
+    defaultPositions?: ReadonlyMap<string, Position>;
+    /** Chip badge counts per axis and value — the host's reading of its own data. Absent, the graph's entity counts (the copies of one `copyKey` once). */
+    counts?: ReadonlyMap<string, ReadonlyMap<string, number>>;
+    /** The host's findings bars, rendered under the filter chips. */
+    findings?: React.ReactNode;
+    /** Groups to glow, over the whole graph; the view restricts them to the visible set and colours them. */
+    groups?: readonly NodeGroup[];
+    /** The host's control for its groups (`GroupLegend`, or its own), rendered inside the pane — which sets `--gv-toolbar-height` on its root so a control can anchor under the bar — and handed the groups as drawn, colours included, and the view's `emphasize`. */
+    groupsControl?: (active: readonly ActiveGroup[], control: GroupsControl) => React.ReactNode;
+    /** Edges to mark, by id, with a dashed band behind their stroke; a graduated edge is marked when the edge it stands for is. */
+    markedEdges?: ReadonlySet<string>;
+    /** The host's action for a node, offered in the hover box: one for every node, or the host's answer per node (null for none). */
+    nodeAction?: NodeAction | ((node: GraphNode) => NodeAction | null);
+    /** Which parts of the pane's chrome are offered. Default: everything, the lock toggles only when `locks` is controlled with its callback. */
+    chrome?: GraphViewChrome;
+    /** The search control's title and placeholder, for a host with its own words. */
+    searchTitle?: string;
+    searchPlaceholder?: string;
+    /**
+     * The selected node, when the host controls the selection: the view shows
+     * this and nothing else while it is defined. A selection the user makes
+     * arrives through `onSelectionChange`; the host answers by setting this, or
+     * does not. Absent, the view keeps the selection itself.
+     */
+    selectedId?: string | null;
+    /** Where the view's own selection starts when the host does not control it. Read once. */
+    defaultSelectedId?: string | null;
+    /**
+     * A request to reveal, centre and select a node — the declarative form of
+     * the handle's `focusNode`. Compared by value: a new `id` or `key` is a new
+     * request. It waits until its node is in the graph, then `onFocusResult`
+     * reports whether the filter could show it. Null, or a newer request,
+     * withdraws a waiting one, unreported.
+     */
+    focus?: FocusRequest | null;
+    /** A focus request's outcome, once its node is in the graph: whether the node ended visible. A withdrawn request is not reported. */
+    onFocusResult?: (request: FocusRequest, shown: boolean) => void;
+    /** Added to the root's class list; the root keeps its own. */
+    className?: string;
+    /** Merged onto the root's style; the scheme's variables stay. */
+    style?: React.CSSProperties;
+    /**
+     * The selection per axis. Controlled while defined: the view shows it and
+     * never rewrites it — a host that controls the filter re-seeds it for a
+     * new graph itself (`reseedFilter`). Absent, the view keeps the filter:
+     * `defaultFilter`, or `initialFilter(taxonomy, graph)` re-seeded from each
+     * new graph on every axis still at the selection it opened with.
+     */
+    filter?: FilterState;
+    /**
+     * Every change to the filter — the user's and, when the view keeps the
+     * filter itself, its own re-seed on a graph change. `touched` names the
+     * axes the user changed in the bar; a write of the view's own (its re-seed,
+     * a focus's widening) names none — so a host that controls the filter can
+     * keep the set `reseedFilter` takes.
+     */
+    onFilterChange?: (next: FilterState, touched: readonly AxisId[]) => void;
+    /**
+     * Where the view's own filter starts when the host does not control it —
+     * a start that depends on the host's state, which a descriptor's
+     * `initialSelection` cannot see. Read once; a host that gives it has
+     * chosen its start, so a later graph re-seeds nothing.
+     */
+    defaultFilter?: FilterState;
+    /** Which axes are locked against a cross-view adoption. Default: `defaultLocks`, else none. Controlling it with `onLocksChange` shows the lock toggles. */
+    locks?: AxisLocks;
+    onLocksChange?: (next: AxisLocks) => void;
+    /** Where the view's own locks start when the host does not control them. Read once. */
+    defaultLocks?: AxisLocks;
+    /** The locks a host-side focus into this view overrode (`useLinkedViews`'s `switchTo`); flashed once, beside the view's own. */
+    overriddenLocks?: ReadonlySet<string>;
+    /** The axes shown, in order. Default: `defaultAxes`, else every declared filter axis. Editable in the bar unless controlled without a callback. */
+    axes?: readonly string[];
+    onAxesChange?: (next: readonly string[]) => void;
+    /** Where the view's own axes start when the host does not control them. Read once. */
+    defaultAxes?: readonly string[];
+    /** The search control. Default: `defaultSearch`, else closed and empty. */
+    search?: SearchState;
+    onSearchChange?: (next: SearchState) => void;
+    /** Where the view's own search starts when the host does not control it. Read once. */
+    defaultSearch?: SearchState;
+    /** The pane's theme choice. Default: `defaultTheme`, else `system`. */
+    theme?: ThemeChoice;
+    onThemeChange?: (next: ThemeChoice) => void;
+    /** Where the view's own theme choice starts when the host does not control it. Read once. */
+    defaultTheme?: ThemeChoice;
+    /** What `system` resolves to, for a host that knows its own theme. Given, the pane reads no ancestor's `data-theme` and no OS preference for it. */
+    systemTheme?: Theme;
+    /**
+     * The layout — the force tuning and the node scale, as the user set them.
+     * Controlled while defined: the view reads it, retunes it for the graph and
+     * taxonomy it faces (a tuning on an axis the graph no longer carries
+     * returns to the style axis, reported through `onLayoutChange`), and
+     * otherwise never writes it. Absent, the view keeps the layout:
+     * `defaultLayout`, else the taxonomy's defaults.
+     */
+    layout?: LayoutState;
+    /** Every change to the layout — the user's tuning in the control panel and the view's retune for a new graph or taxonomy. */
+    onLayoutChange?: (next: LayoutState) => void;
+    /** Where the view's own layout starts when the host does not control it — `layoutFromJSON`'s answer, say. Read once. */
+    defaultLayout?: LayoutState;
+    /**
+     * The selection the user made — a click, Enter, Escape, a search pick, a
+     * focus landing, the handle — as the host's own node, or null when they
+     * cleared it. Not called for a change the host made through `selectedId`.
+     * When the view keeps the selection itself, also null when the selected
+     * node leaves the graph.
+     */
+    onSelectionChange?: (node: GraphNode | null) => void;
+    /** The graph's diagnostics, whenever they are recomputed — the first graph's included, and an empty list is a call. */
+    onDiagnostics?: (diagnostics: readonly GraphDiagnostic[]) => void;
+    /** A node double-clicked. */
+    onNodeActivate?: (node: GraphNode) => void;
+    /** The node under the pointer, or null. */
+    onHover?: (node: GraphNode | null) => void;
+    /** The theme the pane resolved to draw in — the choice, or the host's for `system`. */
+    onThemeResolved?: (theme: Theme) => void;
+}
+/**
+ * The graph view: the host's `Graph`, laid out by forces, filtered by the
+ * bar, highlighted on hover and selection, tuned by the control panel and
+ * drawn on a canvas. Only `graph` and a taxonomy are required; every piece
+ * of state is controlled by the host or kept by the view.
+ */
+export declare const GraphView: React.ForwardRefExoticComponent<GraphViewProps & React.RefAttributes<GraphViewHandle>>;

package/dist-lib/components/GroupLegend.d.ts

@@ -0,0 +1,25 @@
+import { ActiveGroup } from '../graph/groups';
+/** The legend's inputs: the items, the groups as drawn, and the host's toggle and emphasis. */
+export interface GroupLegendProps {
+    /** Every group the host offers, in order, with its label. */
+    items: readonly {
+        id: string;
+        label: string;
+    }[];
+    /** The groups as drawn, from `groupsControl` — their colours. An item on but not among them has no node the view draws. */
+    active: readonly ActiveGroup[];
+    /** Which items are on. Absent: every item is on; the toggles follow `onToggle`. */
+    enabled?: ReadonlySet<string>;
+    /** Turn an item on or off; shown as a checkbox when given. */
+    onToggle?: (id: string) => void;
+    /** Hover emphasis — hand it `groupsControl`'s `emphasize`. */
+    onEmphasize?: (id: string | null) => void;
+    title?: string;
+    className?: string;
+}
+/**
+ * A legend for the group overlay: every group the host offers with the colour
+ * the view drew it in, a checkbox when the host lets the user turn groups on
+ * and off, and hover emphasis through the view's own `emphasize`.
+ */
+export declare function GroupLegend({ items, active, enabled, onToggle, onEmphasize, title, className }: GroupLegendProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/graph-view/focus.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A request to reveal, centre and select a node — the declarative form of the
+ * handle's `focusNode`, for a host whose pane mounts lazily or whose data
+ * arrives after the request. Compared by value: a new `id` or `key` is a new
+ * request, the same pair on a re-render is not, so a host repeats a request
+ * for one node by changing `key`. A request waits until its node is in the
+ * graph; then the view runs the focus recipe once and `onFocusResult` says
+ * whether the filter could show the node. `null`, or a newer request,
+ * withdraws a waiting one; a withdrawn request is not reported.
+ */
+export interface FocusRequest {
+    id: string;
+    key?: number | string;
+}
+/** Whether two requests are the same ask: both absent, or the same id and key. */
+export declare function sameFocusRequest(a: FocusRequest | null, b: FocusRequest | null): boolean;

package/dist-lib/components/graph-view/useFocusRequest.d.ts

@@ -0,0 +1,9 @@
+import { FocusRequest } from './focus';
+/**
+ * A focus request and the function that raises one: `requestFocus(id)` is a
+ * new request every time, for the same node too, so the view acts on each
+ * ask; `requestFocus(null)` withdraws a waiting one. Pass the request as the
+ * view's `focus`. A host with two views through `useLinkedViews` has this in
+ * `linked.focus(view, node)` and needs none of its own.
+ */
+export declare function useFocusRequest(): [FocusRequest | null, (id: string | null) => void];

package/dist-lib/components/graph-view/useLinkedViews.d.ts

@@ -0,0 +1,85 @@
+import { AxisId } from '../../graph/axis';
+import { Graph, GraphNode } from '../../graph/model';
+import { Taxonomy } from '../../graph/taxonomy';
+import { LinkedViewState } from '../../filter/linked';
+import { AxisLocks, FilterState, ReconcileResult, ViewTransition } from '../../filter/types';
+import { SearchState } from '../FilterBar';
+import { FocusRequest } from './focus';
+export type { LinkedViewState } from '../../filter/linked';
+/** The state props of one linked view — spread onto its `GraphView` or `FilterBar`. */
+export interface LinkedViewProps {
+    filter: FilterState;
+    /** A change to the filter; `touched` names the axes the user changed (the bar's and the pane's writes name them), which a later graph then leaves alone. */
+    onFilterChange: (next: FilterState, touched?: readonly AxisId[]) => void;
+    locks: AxisLocks;
+    onLocksChange: (next: AxisLocks) => void;
+    axes: readonly AxisId[];
+    onAxesChange: (next: readonly AxisId[]) => void;
+    /** The locks the last switch into this view overrode — a focus's, which the bar flashes once per set; a manual switch clears it. */
+    overriddenLocks: ReadonlySet<AxisId>;
+    /** The search the views share: the same value and callback in every view's props. */
+    search: SearchState;
+    onSearchChange: (next: SearchState) => void;
+    /** The focus `linked.focus` asked of this view, until the pane reports it; a `FilterBar` ignores it. */
+    focus: FocusRequest | null;
+    onFocusResult: (request: FocusRequest, shown: boolean) => void;
+}
+/** What `useLinkedViews` is given: the taxonomy, the views by name, where each starts, the graph the default filter is seeded from, and the view shown first. */
+export interface LinkedViewsOptions<V extends string> {
+    taxonomy: Taxonomy;
+    /** The views, by the names the host switches between. Read once. */
+    views: readonly V[];
+    /** Where each view starts; a part left out defaults — the taxonomy's default filter over `graph`, no locks, every declared axis. Read once. A filter given here counts as the user's on every axis where it differs from that default. */
+    initial?: (view: V) => {
+        filter?: FilterState;
+        locks?: AxisLocks;
+        axes?: readonly AxisId[];
+    } | undefined;
+    /** The graph the views show: the default filter is seeded from it, a later one re-seeds every view on the axes the user has not touched, and a focus widens by its whole chips. */
+    graph?: Pick<Graph, 'nodes'>;
+    /** The view shown first. Default: the first of `views`. Read once. */
+    start?: V;
+    /** Where the shared search starts — a persisted query, say. Default: closed and empty. Read once. */
+    initialSearch?: SearchState;
+}
+/** The state two or more views share through one bar: each view's props, the view shown, the switch and the focus between views, and the whole for persistence. */
+export interface LinkedViews<V extends string> {
+    /** One view's state props. Throws for a view not in `views`. */
+    of(view: V): LinkedViewProps;
+    /** The view shown: `start`, then the last `switchTo` or `focus`. */
+    readonly active: V;
+    /**
+     * Switch to `to` from the active view and make it active: a manual switch
+     * (the default) adopts the active view's selections on the destination's
+     * axes except where locked; a focus widens the destination to show the
+     * target and flashes the locks it overrode. Returns the destination's new
+     * filter and the overridden locks.
+     */
+    switchTo(to: V, transition?: ViewTransition): ReconcileResult;
+    /**
+     * Show `node` in `view`: a focus switch to it, and — for a `GraphView` —
+     * a request in `of(view).focus` that centres on and selects the node once
+     * it is in the graph, cleared when the pane reports it.
+     */
+    focus(view: V, node: GraphNode): ReconcileResult;
+    /** Rewrite one view's filter from its current value — a host rule that follows one view's data. */
+    updateFilter(view: V, fn: (filter: FilterState) => FilterState): void;
+    /** Rewrite every view's filter at once — a stale value pruned when the data changes. */
+    updateFilters(fn: (filter: FilterState, view: V) => FilterState): void;
+    /** The search the views share. */
+    readonly search: SearchState;
+    /** Every view's filter, locks and axes, for a host that persists them (with `active` and `search`). */
+    readonly state: Readonly<Record<V, LinkedViewState>>;
+}
+/**
+ * One record per view — filter, locks, axes, the locks the last focus into it
+ * overrode, the focus asked of it — with each view's props (`of`), the view
+ * shown (`active`), `switchTo` and `focus`, a per-view or all-views filter
+ * rewrite, the shared `search`, and the whole as `state`. `views`, `initial`,
+ * `start` and `initialSearch` are read once. A later `graph` re-seeds every
+ * view on the axes the user has not touched — the ones no write through
+ * `onFilterChange` named, and on which a filter `initial` gave did not differ
+ * from the default — so a host that mounts empty is not left blank and the
+ * user's own selections stand.
+ */
+export declare function useLinkedViews<V extends string>({ taxonomy, views, initial, graph, start, initialSearch }: LinkedViewsOptions<V>): LinkedViews<V>;

package/dist-lib/components/graph-view/useRecentlyChanged.d.ts

@@ -0,0 +1,5 @@
+import { FilterState } from '../../filter/types';
+/** The values that just turned on, per axis. */
+export type RecentlyChanged = ReadonlyMap<string, ReadonlySet<string>>;
+/** The values that just turned on in a filter, per axis, for about 450 ms — the bar's chip flash — derived from the filter alone. */
+export declare function useRecentlyChanged(rawFilter: FilterState): RecentlyChanged;

package/dist-lib/components/graph-view/useTaxonomy.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+import { Taxonomy } from '../../graph/taxonomy';
+/** The taxonomy for every view and bar below the provider, so a host passes it once. */
+export declare const TaxonomyContext: React.Context<Taxonomy | null>;
+/**
+ * The taxonomy in scope.
+ *
+ * Throws when no provider is above the caller. That is the point: a wrong
+ * taxonomy is invisible, a missing one should not be.
+ */
+export declare function useTaxonomy(): Taxonomy;

package/dist-lib/components/graph-view/useTheme.d.ts

@@ -0,0 +1,26 @@
+import { default as React } from 'react';
+import { Theme } from '../../graph/scheme';
+/** A theme choice: `system` follows the host, `light` and `dark` are fixed. */
+export type ThemeChoice = 'system' | Theme;
+/** The three choices, in the order the pane's button cycles them. */
+export declare const THEME_CHOICES: readonly ThemeChoice[];
+/** A persisted or host-supplied choice, or system for anything outside the three: discard the field, not the state. */
+export declare function themeChoiceOf(value: unknown): ThemeChoice;
+/** What an element that marks a theme says: its `data-theme`. */
+export interface ThemeMarker {
+    getAttribute(name: string): string | null;
+}
+/** The one attribute the library reads a host's theme from. */
+export declare const THEME_MARKER_SELECTOR = "[data-theme]";
+/** The theme a marker declares; a `data-theme` outside light and dark declares nothing. */
+export declare function themeOfMarker(marker: ThemeMarker | null): Theme | undefined;
+/** What the host has decided ABOVE `el`: the nearest marking ancestor, else the OS. */
+export declare function hostTheme(el: Element | null): Theme;
+/**
+ * The host's theme for the element at `ref`, re-read when any ancestor's
+ * `data-theme` changes and when the OS preference changes. With `enabled`
+ * false nothing is read or observed, and the answer is light.
+ */
+export declare function useHostTheme(ref: React.RefObject<HTMLElement | null>, enabled?: boolean): Theme;
+/** The resolved theme for the pane rooted at `ref`, given the user's choice and, for `system`, what the host says it means — else what its ancestors and the OS say. */
+export declare function useTheme(ref: React.RefObject<HTMLElement | null>, choice: ThemeChoice, systemTheme?: Theme): Theme;

package/dist-lib/filter/linked.d.ts

@@ -0,0 +1,26 @@
+import { AxisId } from '../graph/axis';
+import { Graph } from '../graph/model';
+import { Taxonomy } from '../graph/taxonomy';
+import { AxisLocks, FilterState, ReconcileResult, ViewTransition } from './types';
+/** One view's share of the linked state: what it filters on, what it holds against adoption, and what the last focus into it overrode. */
+export interface LinkedViewState {
+    filter: FilterState;
+    locks: AxisLocks;
+    /** The axes this view shows, in order — the ones a switch reconciles. */
+    axes: readonly AxisId[];
+    /** The locks the last switch into this view overrode: a focus's, a new set per focus so a bar flashes them once; a manual switch overrides none and clears it. */
+    overriddenLocks: ReadonlySet<AxisId>;
+}
+/** The one empty set every view starts from, so an unchanged state keeps its identity. */
+export declare const NO_LOCKS: ReadonlySet<AxisId>;
+/**
+ * Switch to `to` from `from`: on a manual switch `to` adopts `from`'s
+ * selections on the axes it shows, except where locked; on a focus `to`
+ * widens just enough to show the target — to the whole chip holding its
+ * value when `graph` is given — overriding locks (recorded). The same state
+ * object comes back when nothing changed.
+ */
+export declare function linkedSwitch<V extends string>(state: Readonly<Record<V, LinkedViewState>>, taxonomy: Pick<Taxonomy, 'axisFor'>, to: V, from: V, transition: ViewTransition, graph?: Pick<Graph, 'nodes'>): {
+    state: Readonly<Record<V, LinkedViewState>>;
+    result: ReconcileResult;
+};

package/dist-lib/filter/reconcile.d.ts

@@ -0,0 +1,38 @@
+import { FilterState, AxisLocks, ViewTransition, ReconcileResult } from './types';
+import { AxisId } from '../graph/axis';
+import { Graph } from '../graph/model';
+import { Taxonomy } from '../graph/taxonomy';
+/** What a reconciliation reads: the destination view's filter, locks and the axes it shows, the source view's filter, the transition, and the graph when a focus should widen by whole chips. */
+export interface ReconcileInput {
+    /** The view being switched to: its filter as it stands. */
+    destination: FilterState;
+    /** The view being switched from. Read on a manual switch; a focus reads only the destination. */
+    source: FilterState;
+    /** The destination's locks. */
+    locks: AxisLocks;
+    transition: ViewTransition;
+    /** Resolves the axes' policies. */
+    taxonomy: Pick<Taxonomy, 'axisFor'>;
+    /**
+     * The axes the destination view SHOWS, by id — not every declared axis:
+     * an axis the user removed from the bar is not filtering there, and
+     * adopting a selection on it would revive what they reset. One the
+     * taxonomy does not declare is skipped.
+     */
+    axes: readonly AxisId[];
+    /**
+     * The graph the destination shows. Given, a focus widens to the WHOLE
+     * chip holding the target's value — the bar toggles a chip as a unit, so
+     * a selection that split one would read as on with half its nodes hidden,
+     * and the first click would turn the chip off. Absent, the value alone.
+     */
+    graph?: Pick<Graph, 'nodes'>;
+}
+/**
+ * The destination view's filter after a switch: on a manual switch it adopts
+ * the source's selections on the axes it shows, except where locked; on a
+ * focus it widens just enough to show the target, overriding locks, which
+ * come back in `overriddenLocks` for the bar to flash. The same filter object
+ * comes back when nothing changed.
+ */
+export declare function reconcileFilter({ destination, source, locks, transition, taxonomy, axes, graph }: ReconcileInput): ReconcileResult;

package/dist-lib/filter/toggle.d.ts

@@ -0,0 +1,12 @@
+import { AxisId } from '../graph/axis';
+import { FilterState } from './types';
+/** Toggle one value on one axis. */
+export declare function toggleValue(filter: FilterState, axis: AxisId, value: string): FilterState;
+/**
+ * Toggle a group of values on one axis as a unit.
+ *
+ * A chip may cover several values — one covers three. "Any on" turns the whole
+ * group off; otherwise the whole group goes on, so a partially-on group has a
+ * single unambiguous next state.
+ */
+export declare function toggleGroup(filter: FilterState, axis: AxisId, values: readonly string[]): FilterState;

package/dist-lib/filter/types.d.ts

@@ -0,0 +1,162 @@
+import { AxisId, AxisValues, ResolvedAxisDescriptor } from '../graph/axis';
+import { Graph } from '../graph/model';
+import { Taxonomy } from '../graph/taxonomy';
+/** The chosen values on one axis. Empty means what the axis's descriptor says. */
+export type AxisSelection = ReadonlySet<string>;
+/**
+ * A selection per axis. A `Map`, not a `Record`: an axis the host did not
+ * declare has no key, so a misspelt axis is a miss the type sees rather than
+ * an `undefined` every downstream `.has` reads as "nothing selected".
+ */
+export type FilterState = ReadonlyMap<AxisId, AxisSelection>;
+/**
+ * Which axes are locked. A locked axis keeps its selection when a `manual`
+ * switch adopts the source view's; a focus widens it anyway and reports it.
+ */
+export type AxisLocks = ReadonlyMap<AxisId, boolean>;
+/**
+ * The selection on one axis, or an empty one.
+ *
+ * Always returns the *same* empty Set, so an absent axis does not change
+ * identity between reads — a fresh `new Set()` per call would defeat exactly the
+ * memoisation this module exists to protect.
+ */
+export declare function selectionFor(state: FilterState, axis: AxisId): AxisSelection;
+/** Every axis the state carries a selection for. */
+export declare function axesOf(state: FilterState): AxisId[];
+/** Whether two selections hold the same values. */
+export declare function selectionsEqual(a: AxisSelection, b: AxisSelection): boolean;
+/**
+ * Replace one axis's selection, copy-on-write.
+ *
+ * Returns `state` **itself** when the new selection is content-equal to the old
+ * one, so a no-op edit changes no identity anywhere. Otherwise only the edited
+ * axis gets a new Set; every other axis is carried over by reference.
+ */
+export declare function withSelection(state: FilterState, axis: AxisId, next: AxisSelection): FilterState;
+/** Structural equality across every axis either state mentions. */
+export declare function filterStatesEqual(a: FilterState, b: FilterState): boolean;
+/** Structural equality of two lock maps. */
+export declare function locksEqual(a: AxisLocks, b: AxisLocks): boolean;
+/** Element-wise equality of two lists of ids. */
+export declare function listEqual(a: readonly string[], b: readonly string[]): boolean;
+/** Set one axis's lock, copy-on-write. */
+export declare function withLock(locks: AxisLocks, axis: AxisId, locked: boolean): AxisLocks;
+/** Whether an axis is locked against adoption. */
+export declare function lockedFor(locks: AxisLocks, axis: AxisId): boolean;
+/**
+ * Where a focus transition wants to land: the target's value per axis. An
+ * axis the target says nothing about is absent, which the reconciler reads
+ * as "no expansion needed". A host that also needs the target's name for a
+ * view of its own carries it in a type of its own.
+ */
+export type FocusTarget = {
+    values: Readonly<Record<AxisId, string | undefined>>;
+};
+/** How a view is being switched to: by the user (`manual`: adopt the source's selections) or to show a node (`focus`: widen for its values). */
+export type ViewTransition = {
+    kind: 'manual';
+} | {
+    kind: 'focus';
+    target: FocusTarget;
+};
+/**
+ * A reconciled filter, and which locked axes a focus had to widen to show its
+ * target — the ones the destination's bar flashes.
+ */
+export type ReconcileResult = {
+    filter: FilterState;
+    overriddenLocks: ReadonlySet<AxisId>;
+};
+/**
+ * The filter a view starts from: on every filter axis, what its descriptor's
+ * `initialSelection` chooses from the values the graph presents there —
+ * every value on an allow-list, none on a narrowing axis, or the host's own
+ * choice.
+ */
+export declare function initialFilter(taxonomy: Pick<Taxonomy, 'filterAxes'>, graph: Pick<Graph, 'nodes'>): FilterState;
+/**
+ * A filter re-seeded for a graph that changed: every filter axis the user has
+ * not touched takes its opening selection on `graph` (`initialFilter`'s), so
+ * a host that mounts empty while its data loads is not left blank and a value
+ * first seen later is not born hidden; an axis in `touched` keeps its
+ * selection. Which axes the user touched is state, not an inference — the
+ * bar names the axis of every change it makes (`onFilterChange`'s second
+ * argument), the view and `useLinkedViews` keep the set, and a host that
+ * controls its filter keeps its own and passes it here from its data effect.
+ * Absent, every axis follows the graph. The same object when nothing moves.
+ */
+export declare function reseedFilter(filter: FilterState, taxonomy: Pick<Taxonomy, 'filterAxes'>, graph: Pick<Graph, 'nodes'>, touched?: ReadonlySet<AxisId>): FilterState;
+/** The axes whose selection differs between two filters — what a write touched. */
+export declare function changedAxes(a: FilterState, b: FilterState): AxisId[];
+/** A filter as plain data — each axis's selected values in an array — for a URL, a store or a saved layout. */
+export declare function filterToJSON(filter: FilterState): Record<AxisId, string[]>;
+/**
+ * The filter `filterToJSON` wrote, or undefined when `value` is not that
+ * shape — stored data is not trusted to be, and a host falls back to its
+ * default rather than to a filter that means something else.
+ */
+export declare function filterFromJSON(value: unknown): FilterState | undefined;
+/** Locks as plain data — a boolean per axis — beside `filterToJSON`. */
+export declare function locksToJSON(locks: AxisLocks): Record<AxisId, boolean>;
+/** The locks `locksToJSON` wrote, or undefined when `value` is not that shape. */
+export declare function locksFromJSON(value: unknown): AxisLocks | undefined;
+/** Whether a node answers to a focus target: every value the target names. */
+export declare function matchesFocus(node: {
+    values: Readonly<Record<string, string>>;
+}, target: FocusTarget): boolean;
+/** What `passesSelection` reads. */
+export interface PassesSelectionInput<N> {
+    filter: FilterState;
+    taxonomy: Pick<Taxonomy, 'axisFor'>;
+    /** The axes the view shows — the only ones that filter. One the taxonomy does not declare filters nothing. */
+    axes: readonly AxisId[];
+    /** The record judged: a graph node, or any record of the host's. */
+    node: N;
+    /** The record's value on an axis, for a record that carries its values under other names. Default: its `values`, when it has them. */
+    valueOn?: (node: N, axis: AxisId) => string | undefined;
+}
+/**
+ * Does a record pass the selection on the axes a view shows? The policy —
+ * what an empty selection means, what an absent value means — is read from
+ * each axis's descriptor, once, here, so a host's second view and the pane
+ * agree on what the filter means.
+ */
+export declare function passesSelection<N>({ filter, taxonomy, axes, node, valueOn }: PassesSelectionInput<N>): boolean;
+/** `passesSelection` over descriptors already resolved — the view's hot path, which resolves them once per render. */
+export declare function passesDescriptors(filter: FilterState, axes: readonly ResolvedAxisDescriptor[], valueOn: (axis: string) => string | undefined): boolean;
+/** Search matches split by the filter: the visible ones, and the hidden ones tallied on the chip hiding each. */
+export interface HiddenMatches {
+    /** The ids of the matching nodes the filter shows. */
+    visible: ReadonlySet<string>;
+    /** How many matching nodes the filter hides. */
+    hiddenCount: number;
+    /** The hidden matches per axis and value — on the first of the axes shown that each node fails, under its value there. */
+    hiddenByAxis: ReadonlyMap<AxisId, ReadonlyMap<string, number>>;
+}
+/** What `hiddenMatchesOf` reads. */
+export interface HiddenMatchesInput<N extends {
+    id: string;
+    values?: AxisValues;
+}> {
+    /** Every node the search ran over, visible or not. */
+    nodes: Iterable<N>;
+    filter: FilterState;
+    taxonomy: Pick<Taxonomy, 'axisFor'>;
+    /** The axes the view shows, in order: the first one a hidden match fails is the chip it is counted on. */
+    axes: readonly AxisId[];
+    visibleIds: ReadonlySet<string>;
+    matches: (node: N) => boolean;
+    /** A node's value on an axis. Default: its `values`. */
+    valueOn?: (node: N, axis: AxisId) => string | undefined;
+}
+/**
+ * Split a search's matches by the filter, the way the pane does under its
+ * own bar: a match the filter shows lights up, a match it hides is counted
+ * on the chip hiding it — the first axis in `axes` the node fails, under the
+ * node's value there — so a host's second bar can wear the same badges.
+ */
+export declare function hiddenMatchesOf<N extends {
+    id: string;
+    values?: AxisValues;
+}>({ nodes, filter, taxonomy, axes, visibleIds, matches, valueOn }: HiddenMatchesInput<N>): HiddenMatches;