@jmbarzee/force-graph 0.1.0 → 0.2.0

package/README.md

@@ -9,7 +9,8 @@ their values on those axes, and mounts `GraphView`. The view lays the graph out
 pull on any axis the nodes carry, two layout axes keyed on an axis or a
 computed scalar), filters it on any declared axis, highlights it, and lets the
 user tune the forces — without knowing what any node or edge means. The host's
-vocabulary never enters this package.
+vocabulary never enters this package. What the user sees and does is
+[SPEC.md](SPEC.md).
 
 ## Install
 
@@ -143,7 +144,7 @@ never by spreading the built object.
   and no icon elsewhere, the abbreviation from the label, no tooltip),
   `initialSelection(values)` is the first open's selection (default every
   value on an allow-list, none on a narrowing axis), `presentation` is
-  `chip` or `tag`.
+  `chip` or `tag`, and `reads: 'tags'` makes it a tag axis (see The graph).
 - **Scalars and hooks.** `scalars` adds computed axes (`id`, `label` and
   `tooltip` — defaults the id and the label — and `compute(graph)` answering a
   number per node; `normalize` maps
@@ -179,7 +180,14 @@ engine compares them and never parses one.
   the parent, and
   `validateGraph` names one that contradicts `parentId`. A host adds axes of
   its own to edges and nodes alike through `values`; any axis the nodes
-  carry can be pushed, pulled and laid out on.
+  carry a value on can be pushed, pulled and laid out on.
+- **Tags.** A node's `tags` map an axis to a list — its assignees, its
+  labels — read by a filter axis declared `reads: 'tags'`: a node passes it
+  when any of its tags does, and each tag's chip counts the node once. A tag
+  axis only filters — push, pull, a layout axis and colour never key on it —
+  and `validateGraph` warns of tags on any other axis. `valuesOn` and
+  `countsOn` read a tag axis when handed its descriptor
+  (`taxonomy.axisFor(id)`).
 - **Adornments.** A node may carry `badges` (short texts drawn as chips above
   it) and a `ring` (`dashed`, for a node set apart).
 - **Identity.** Keep one `graph` object until something in it changes: a new
@@ -295,15 +303,14 @@ the console. Everything else is optional.
   refused; with `classifyEdge` given, its answer stands. Derived containment
   edges are `in:<id>` (numbered on a collision) and reach `highlight` and
   `collapse`. An error diagnostic drops the edge, or the later node of a
-  duplicated id, or clears the `parentId`, it names. The search dropdown lists visible matches; hidden ones badge the
-  chip hiding them. The pane's theme observer watches every `data-theme` in
-  the document unless `systemTheme` is given.
+  duplicated id, or clears the `parentId`, it names. The pane's theme
+  observer watches every `data-theme` in the document unless `systemTheme` is
+  given.
 - **Keyboard.** `keyboard` scopes the shortcuts: `pane` (the default — the
   focusable root handles the keys that reach it, so a page keeps Tab and
   Space for its own controls), `global` (the window — a page that is the
-  pane, or a tab shell's active tab) or `none` (a hidden tab). Tab cycles
-  nodes, Enter selects, Escape closes, arrows pan, `+`/`-` zoom, F fits, `/`
-  opens search (while the search is offered), Space pauses, `?` lists them.
+  pane, or a tab shell's active tab) or `none` (a hidden tab). The keys are
+  [SPEC § Keyboard](SPEC.md#keyboard).
 
 ## Two views sharing a bar
 
@@ -342,9 +349,8 @@ last `linked.focus` asked of it with `onFocusResult` (a `FilterBar` ignores
 those two); it throws for a view the hook was not given (`views` is read
 once). `linked.active` is the view shown.
 `linked.switchTo(to, transition?)` switches from the active view and makes
-`to` active: a manual switch (the default) adopts the active view's
-selections except where locked, a focus widens the destination to show its
-target. `linked.focus(view, node)` is the focus switch and the request in one.
+`to` active, reconciling as [SPEC § Linked views](SPEC.md#linked-views) says
+(a manual switch is the default). `linked.focus(view, node)` is the focus switch and the request in one.
 `linked.updateFilter(view, fn)` rewrites one view's filter and
 `linked.updateFilters(fn)` every view's (a stale value pruned when the data
 changes — `reseedFilter` is the rule the hook itself applies to every view
@@ -353,17 +359,19 @@ when `graph` changes, on the axes the user has not touched); `linked.state`,
 for a host that persists them. The bar carries its own theme and scheme
 (`theme`, default `system`; `systemTheme` says what that means), so it needs
 no wrapper; give it the `graph` (or the `values` per axis — `valuesOn(records,
-axis)` reads them off any subjects carrying `values`) and, if the host reads
+axis)` reads them off any subjects carrying `values`, or their `tags` given the
+axis's descriptor) and, if the host reads
 its own data, the `counts`. The lock toggles appear only when `locks` is
 controlled with its callback — `useLinkedViews` does — or `chrome.locks` asks.
 The bar tracks the values that just turned on for its chip flash
 (`RecentlyChanged`, a set per axis); a host with its own rule passes
-`recentlyChanged`.
+`recentlyChanged`. `refreshFlash` flashes the bar each time the host bumps
+it.
 
 What the pane computes for its own bar is exported for the second view:
 `passesSelection({ filter, taxonomy, axes, node })` decides visibility on the
 axes the view shows (`valueOn(node, axis)` for a record that carries its
-values under other names), `countsOn(nodes, axes)` the badges,
+values or tags under other names), `countsOn(nodes, axes)` the badges,
 `hiddenMatchesOf({ nodes, filter, taxonomy, axes, visibleIds, matches })` the
 search's hidden-match badges. `reconcileFilter({ destination, source, locks,
 transition, taxonomy, axes, graph })` is the switch the hook makes; `axes`
@@ -381,14 +389,17 @@ The pane resolves its theme from its own choice (Auto / Light / Dark) or, for
 `system`, from `systemTheme` when the host gives it, else the nearest
 ancestor's `data-theme` and then the OS — `useHostTheme(ref)` is that same
 read, for a host's own chrome, and `themeChoiceOf(value)` reads a stored
-choice back (`system` for anything else). Every
+choice back (`system` for anything else). A server render knows neither
+ancestors nor OS, so a server-rendered pane paints light until it hydrates; a
+host that wants no flash resolves the theme on the server (a cookie, say) and
+passes `systemTheme`. Every
 token the components read is a `--gv-*` custom property declared in the
 stylesheet per theme (`--gv-color-bg`, `--gv-color-text`, `--gv-accent`,
 `--gv-font-sans`, …), and every class is `gv-*`; a host overrides a token by
 redeclaring it on an ancestor. Each style value's fill and border are
 published on the pane under the name `taxonomy.colorVar(value)` answers —
-`--gv-node-` and the value id in kebab case (`nexusEndpoint` →
-`--gv-node-nexus-endpoint`), or a numbered name when the id kebab-cases to
+`--gv-node-` and the value id in kebab case (a value id such as
+`teachingLab` → `--gv-node-teaching-lab`), or a numbered name when the id kebab-cases to
 nothing or to another value's — and `-border` for the border. A host's own
 chrome beside the pane reads the same tints through `schemeVars(taxonomy,
 theme)` inline, or `schemeStylesheet(taxonomy, darkSelector?)` mounted once
@@ -410,15 +421,46 @@ draw in lanes.
 ## Limits
 
 The charge force is O(n²) over the visible nodes: a few hundred draw
-smoothly, a few thousand do not. The push/pull and layout controls bound their
-tokens by a ceiling (an axis with more values than the ceiling is offered but
-cannot be tuned on, and a tuning that outgrows it returns to the style axis).
-What is not built is filed as issues: colour by another axis
-([#9](https://github.com/jmbarzee/force-graph/issues/9)), an opaque `Taxonomy`
-([#10](https://github.com/jmbarzee/force-graph/issues/10)), undirected edges
-([#11](https://github.com/jmbarzee/force-graph/issues/11)), per-edge weight
-([#12](https://github.com/jmbarzee/force-graph/issues/12)), the pane's strings
-in other languages ([#13](https://github.com/jmbarzee/force-graph/issues/13)),
-the React 19 types gate ([#14](https://github.com/jmbarzee/force-graph/issues/14)).
+smoothly, a few thousand do not (Barnes-Hut,
+[#30](https://github.com/jmbarzee/force-graph/issues/30)). The push/pull and
+layout controls bound their tokens by a ceiling
+([SPEC § The control panel](SPEC.md#the-control-panel)).
+What is not built is filed as issues:
+
+- **The graph and taxonomy** — colour by another axis
+  ([#9](https://github.com/jmbarzee/force-graph/issues/9)), an opaque
+  `Taxonomy` ([#10](https://github.com/jmbarzee/force-graph/issues/10)),
+  undirected edges ([#11](https://github.com/jmbarzee/force-graph/issues/11)),
+  per-edge weight ([#12](https://github.com/jmbarzee/force-graph/issues/12)),
+  an edge time series played back
+  ([#33](https://github.com/jmbarzee/force-graph/issues/33)), host-declared
+  pair-axis mappings ([#32](https://github.com/jmbarzee/force-graph/issues/32)),
+  a node drawn as a stack of ghosts
+  ([#19](https://github.com/jmbarzee/force-graph/issues/19)).
+- **Groups** — structural colouring, a metric channel and a cohesion pull
+  ([#27](https://github.com/jmbarzee/force-graph/issues/27)); hiding through
+  the legend, one emphasis path, colours validated on arrival
+  ([#17](https://github.com/jmbarzee/force-graph/issues/17)).
+- **Interaction** — selecting several nodes
+  ([#28](https://github.com/jmbarzee/force-graph/issues/28)), edge hover and
+  its outputs ([#16](https://github.com/jmbarzee/force-graph/issues/16)), a
+  focus that frames the neighbourhood
+  ([#21](https://github.com/jmbarzee/force-graph/issues/21)), a neighbourhood
+  frame that leaves hidden neighbours out
+  ([#26](https://github.com/jmbarzee/force-graph/issues/26)), the keyboard and
+  accessibility model ([#7](https://github.com/jmbarzee/force-graph/issues/7)),
+  positions, viewport and selection kept across a live reload
+  ([#5](https://github.com/jmbarzee/force-graph/issues/5)), animated reveals
+  ([#8](https://github.com/jmbarzee/force-graph/issues/8)), an empty state
+  when the filter hides every node
+  ([#6](https://github.com/jmbarzee/force-graph/issues/6)).
+- **The control panel** — named presets
+  ([#29](https://github.com/jmbarzee/force-graph/issues/29)), grouping a ladder
+  of values and the Misc tab's read-outs
+  ([#31](https://github.com/jmbarzee/force-graph/issues/31)), a force tab with
+  nothing visible ([#4](https://github.com/jmbarzee/force-graph/issues/4)).
+- **The package** — the pane's strings in other languages
+  ([#13](https://github.com/jmbarzee/force-graph/issues/13)), the React 19
+  types gate ([#14](https://github.com/jmbarzee/force-graph/issues/14)).
 
 `src/index.ts` names the whole surface.

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

@@ -80,6 +80,18 @@ interface FilterBarBaseProps {
     /** Flash the whole bar once whenever this value changes to something truthy — a counter a host bumps when its data reloads. */
     refreshFlash?: boolean | number;
 }
+/** The first line of a row's items, laid out at these offsets from its top: its height, and how many items wrap past it. */
+export declare function firstLine(items: readonly {
+    top: number;
+    bottom: number;
+}[]): {
+    height: number;
+    rest: number;
+};
+/** The axes a change of filter opens: those whose selection changed, but for the ones it leaves as they are. */
+export declare function axesOpenedBy(prev: FilterState, next: FilterState, leftAsIs: readonly AxisId[]): AxisId[];
+/** The axes a filter re-seeded: their presented values changed between two readings, and the filter selects their seed. */
+export declare function axesReseeded(taxonomy: Taxonomy, prev: ReadonlyMap<string, readonly string[]>, next: ReadonlyMap<string, readonly string[]>, filter: FilterState): AxisId[];
 /**
  * The shared filter bar: a section of chips per axis shown with its lock and
  * remove controls, the add-axis control, the search control, and the host's

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

@@ -18,9 +18,12 @@ export declare function themeOfMarker(marker: ThemeMarker | null): Theme | undef
 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.
+ * `data-theme` changes and when the OS preference changes. Light until read,
+ * the server's answer, so a hydrating render matches it; with `enabled`
+ * false nothing is read or observed, and the answer stays 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. */
+/** The pane's resolved theme, undefined until the host is read. */
+export declare function useResolvedTheme(ref: React.RefObject<HTMLElement | null>, choice: ThemeChoice, systemTheme?: Theme): Theme | undefined;
+/** The theme the pane rooted at `ref` draws in: the resolved theme, light until read. */
 export declare function useTheme(ref: React.RefObject<HTMLElement | null>, choice: ThemeChoice, systemTheme?: Theme): Theme;

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

@@ -1,4 +1,4 @@
-import { AxisId, AxisValues, ResolvedAxisDescriptor } from '../graph/axis';
+import { AxisId, AxisValue, 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. */
@@ -45,13 +45,14 @@ export declare function withLock(locks: AxisLocks, axis: AxisId, locked: boolean
 /** 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.
+ * Where a focus transition wants to land: the target's value per axis, and
+ * its tags per tag 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>>;
+    tags?: Readonly<Record<AxisId, readonly 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 = {
@@ -75,6 +76,8 @@ export type ReconcileResult = {
  * choice.
  */
 export declare function initialFilter(taxonomy: Pick<Taxonomy, 'filterAxes'>, graph: Pick<Graph, 'nodes'>): FilterState;
+/** One axis's opening selection on the values the graph presents there: `initialFilter`'s, axis by axis. */
+export declare function seedSelection(taxonomy: Pick<Taxonomy, 'filterAxes'>, d: ResolvedAxisDescriptor, values: readonly string[]): AxisSelection;
 /**
  * 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
@@ -113,8 +116,8 @@ export interface PassesSelectionInput<N> {
     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;
+    /** The record's value on an axis — its tags, on a tag axis — for a record that carries them under other names. Default: its `values` and `tags`, when it has them. */
+    valueOn?: (node: N, axis: AxisId) => AxisValue | readonly AxisValue[] | undefined;
 }
 /**
  * Does a record pass the selection on the axes a view shows? The policy —
@@ -124,20 +127,19 @@ export interface PassesSelectionInput<N> {
  */
 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;
+export declare function passesDescriptors(filter: FilterState, axes: readonly ResolvedAxisDescriptor[], valuesOf: (axis: ResolvedAxisDescriptor) => readonly AxisValue[]): 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. */
+    /** The hidden matches per axis and value — on the first of the axes shown that each node fails, under its value there (on a tag axis, its first tag whose chip is off). */
     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>;
@@ -147,16 +149,16 @@ export interface HiddenMatchesInput<N extends {
     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;
+    /** A node's value on an axis — its tags, on a tag axis. Default: its `values` and `tags`. */
+    valueOn?: (node: N, axis: AxisId) => AxisValue | readonly AxisValue[] | 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.
+ * node's value there, or its first tag whose chip is off — 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;

package/dist-lib/graph/axis.d.ts

@@ -7,6 +7,17 @@ export type AxisId = string;
 export type AxisValue = string;
 /** Where a node sits on every axis it has a value for. */
 export type AxisValues = Readonly<Record<AxisId, AxisValue>>;
+/** The tags a node carries, on each tag axis it has any on. */
+export type AxisTags = Readonly<Record<AxisId, readonly AxisValue[]>>;
+/** How an axis is read off a node: its one value, or its tags. */
+export type AxisReading = Pick<ResolvedAxisDescriptor, 'id' | 'reads'>;
+/** What a node, a focus target or a host's record carries: its values and its tags, either possibly absent. */
+export interface AxisSubject {
+    values?: Readonly<Record<AxisId, AxisValue | undefined>>;
+    tags?: Readonly<Record<AxisId, readonly AxisValue[] | undefined>>;
+}
+/** What a subject carries on an axis: its tags on a tag axis, else its one value; none when it carries nothing there. */
+export declare function readAxis(subject: AxisSubject, axis: AxisReading): readonly AxisValue[];
 /**
  * Fold anything into a stable value key.
  *
@@ -136,6 +147,13 @@ export interface AxisDescriptor {
      * `emptyMeans: 'all'` axis.
      */
     presentation?: 'chip' | 'tag';
+    /**
+     * What a node carries on this axis: its one value in `values` (the
+     * default), or a list in `tags` — its assignees, its labels. A node passes
+     * a tag axis when any of its tags does. A tag axis only filters: push,
+     * pull, a layout axis and colour never key on it.
+     */
+    reads?: 'values' | 'tags';
 }
 /** A filter axis with every policy filled in — what `Taxonomy.filterAxes` carries. */
 export interface ResolvedAxisDescriptor extends AxisNamer {
@@ -151,6 +169,7 @@ export interface ResolvedAxisDescriptor extends AxisNamer {
     chipsFor(values: readonly AxisValue[]): readonly FilterChip[];
     initialSelection(values: readonly AxisValue[]): readonly AxisValue[];
     presentation: 'chip' | 'tag';
+    reads: 'values' | 'tags';
 }
 /** How the style axis names and adorns its values, for a descriptor's defaults. */
 export interface StyleNamer {
@@ -231,23 +250,22 @@ export declare function isIdentityMapping(mapping: AxisMapping): boolean;
  * The distinct values a set of subjects carries on one axis, in first-encounter
  * order. The domain of an axis is whatever the graph presents on it — the
  * engine declares no value vocabulary of its own — so this is how a control
- * surface or a filter learns what an axis can take.
+ * surface or a filter learns what an axis can take. An axis given by id reads
+ * values; given by its descriptor, a tag axis reads tags.
  */
-export declare function valuesOn(subjects: Iterable<{
-    values: AxisValues;
-}>, axis: AxisId): AxisValue[];
+export declare function valuesOn(subjects: Iterable<AxisSubject>, axis: AxisId | AxisReading): AxisValue[];
 /**
  * How many entities carry each value on each of the given axes — the chip
  * badges' numbers when a host does not supply its own reading. The copies of
- * one entity (`copyKey`) count once; a subject with neither key nor id counts
- * as itself. An axis no subject has a value on gets an empty map, never a
- * missing one.
+ * one entity (`copyKey`) count once, and so does each of an entity's tags; a
+ * subject with neither key nor id counts as itself. An axis is read as
+ * `valuesOn` reads it, and one no subject carries anything on gets an empty
+ * map, never a missing one.
  */
-export declare function countsOn(subjects: Iterable<{
-    values: AxisValues;
+export declare function countsOn(subjects: Iterable<AxisSubject & {
     id?: string;
     copyKey?: string;
-}>, axes: readonly AxisId[]): ReadonlyMap<AxisId, ReadonlyMap<AxisValue, number>>;
+}>, axes: readonly (AxisId | AxisReading)[]): ReadonlyMap<AxisId, ReadonlyMap<AxisValue, number>>;
 /**
  * Does this table declare `key` itself, rather than inheriting it?
  *

package/dist-lib/graph/model.d.ts

@@ -1,5 +1,5 @@
-import { AxisValues, Relation } from './axis';
-/** A node of the host's graph: an opaque id, a name, its values on the host's axes, and an optional parent, copy key, ring, badges and payload. */
+import { AxisTags, AxisValues, Relation } from './axis';
+/** A node of the host's graph: an opaque id, a name, its values on the host's axes, and an optional parent, copy key, ring, badges, tags and payload. */
 export interface GraphNode {
     /**
      * Stable identity, owned by whoever produced the graph.
@@ -16,6 +16,11 @@ export interface GraphNode {
      * one axis each and read it from here; nothing composes across axes.
      */
     values: AxisValues;
+    /**
+     * Several values on one axis — its assignees, its labels — on each axis
+     * the taxonomy declares to read tags. Read by the filter only.
+     */
+    tags?: AxisTags;
     name: string;
     /**
      * Metadata the host owns and the library does not interpret.

package/dist-lib/graph/taxonomy.d.ts

@@ -29,10 +29,10 @@ export type ContextLine = ReactNode | readonly ReactNode[];
  * policy and host hook through. Built once by `createTaxonomy`; derive a
  * variant from the spec, never by spreading this object.
  *
- * What a host reads: `filterAxes`, `axisFor` and `valueOn` to filter its own
- * records the way the view does; `styleOf`, `styleValues` and `colorVar` for
- * chrome of its own in the scheme's colours; `edgeTypes` for a legend;
- * `searchText` to match as the view matches. The rest is the engine's
+ * What a host reads: `filterAxes` and `axisFor` to filter its own records the
+ * way the view does, through `passesSelection`; `styleOf`, `styleValues` and
+ * `colorVar` for chrome of its own in the scheme's colours; `edgeTypes` for a
+ * legend; `searchText` to match as the view matches. The rest is the engine's
  * interface — resolution for the draw loop — and a host has no call to read
  * it.
  */
@@ -63,13 +63,6 @@ export interface Taxonomy {
     readonly filterAxes: readonly ResolvedAxisDescriptor[];
     /** One axis's policies, or undefined if the host does not declare it. */
     axisFor(axis: AxisId): ResolvedAxisDescriptor | undefined;
-    /**
-     * The value a subject presents on one axis — read off its values, for
-     * every axis alike. An axis that is a projection of another is materialized
-     * by the host when it builds the node, so nothing here knows which axes are
-     * derived.
-     */
-    valueOn(subject: StyleSubject, axis: AxisId): AxisValue | undefined;
     /** Every style value, in declaration order (top of the hierarchy first). */
     readonly styleValues: readonly AxisValue[];
     /** Every edge type, in control-panel order, its defaults filled in. */
@@ -205,3 +198,5 @@ export interface TaxonomySpec {
  * fields.
  */
 export declare function createTaxonomy(spec: TaxonomySpec): Taxonomy;
+/** The axes a taxonomy declares to read tags, which only filter. */
+export declare function tagAxesOf(taxonomy: Pick<Taxonomy, 'filterAxes'>): AxisId[];

package/dist-lib/graph/validate.d.ts

@@ -5,11 +5,12 @@ import { Taxonomy } from './taxonomy';
  * an edge whose endpoint is not in the graph, an unknown relation, a type
  * whose relation is not the edge's, a rule that threw, a parent not in the
  * graph. Warnings: an edge no type claims, a style value the taxonomy does
- * not declare, containment edges that contradict `parentId`, derived
+ * not declare, tags on an axis the taxonomy does not declare to read them,
+ * containment edges that contradict `parentId`, derived
  * containment edges no type claims (`containment-untyped`, from
  * `derivedContainmentDiagnostics`).
  */
-export type GraphDiagnosticCode = 'edge-id-duplicate' | 'edge-endpoint-missing' | 'edge-relation-unknown' | 'edge-type-rule-threw' | 'edge-type-unclassified' | 'edge-type-relation-mismatch' | 'parent-missing' | 'containment-parent-mismatch' | 'node-value-undeclared' | 'node-id-duplicate' | 'containment-untyped';
+export type GraphDiagnosticCode = 'edge-id-duplicate' | 'edge-endpoint-missing' | 'edge-relation-unknown' | 'edge-type-rule-threw' | 'edge-type-unclassified' | 'edge-type-relation-mismatch' | 'parent-missing' | 'containment-parent-mismatch' | 'node-value-undeclared' | 'node-tags-undeclared' | 'node-id-duplicate' | 'containment-untyped';
 /** One defect in a host's graph, as data: its severity, its code, a message, and the node or edge it names. */
 export interface GraphDiagnostic {
     /** An error names something the view cannot draw as given; a warning, something it draws but the host should know. */
@@ -24,9 +25,9 @@ export interface GraphDiagnostic {
  * draw as given (a duplicated node id, a dangling endpoint, an unknown
  * relation, a type whose relation is not the edge's, a parent not in the
  * graph) and warnings for what it draws but the host should know (an
- * unclassified edge, an undeclared style value, containment edges that
- * contradict `parentId`). Pure; the same graph and taxonomy give the same
- * list, in graph order.
+ * unclassified edge, an undeclared style value, tags no axis reads,
+ * containment edges that contradict `parentId`). Pure; the same graph and
+ * taxonomy give the same list, in graph order.
  */
 export declare function validateGraph(graph: Graph, taxonomy: Taxonomy): GraphDiagnostic[];
 /**

package/dist-lib/index.d.ts

@@ -18,7 +18,7 @@ export { toggleGroup, toggleValue } from './filter/toggle';
 export { initialFilter, filterFromJSON, filterStatesEqual, filterToJSON, hiddenMatchesOf, locksFromJSON, locksToJSON, matchesFocus, passesSelection, reseedFilter, lockedFor, selectionFor, withLock, withSelection } from './filter/types';
 export type { FilterState, FocusTarget, HiddenMatches, HiddenMatchesInput, AxisLocks, PassesSelectionInput, ReconcileResult, AxisSelection, ViewTransition } from './filter/types';
 export { countsOn, valuesOn } from './graph/axis';
-export type { AxisDescriptor, AxisId, AxisNamer, AxisValues, AxisValue, FilterChip, Relation, ResolvedAxisDescriptor } from './graph/axis';
+export type { AxisDescriptor, AxisId, AxisNamer, AxisTags, AxisValues, AxisValue, FilterChip, Relation, ResolvedAxisDescriptor } from './graph/axis';
 export type { ActiveGroup, NodeGroup } from './graph/groups';
 export { copyGroups, isContainment, nodesById, payloadNumber, payloadString } from './graph/model';
 export type { Graph, GraphEdge, GraphNode, ReadableGraph } from './graph/model';