@graphty/graphty-element 2.6.1 → 3.0.0

package/dist/src/session/visibility/VisibilityApi.d.ts

@@ -38,14 +38,23 @@
  * setting this same window and summarising what it left visible, and playback is a cursor over
  * that list calling `setWindow` per step. Nothing about the masks needs to change for either.
  *
+ * THE FILTER, THE WINDOW AND THE CONTEXT FLAG ARE PROJECT STATE; THE MASKS ARE NOT. The three
+ * values live in the session's `visibility` slice and change only through the `visibility.*`
+ * commands, so each change is one undoable step. The masks are derived from them and the graph,
+ * and are brought up to date on the derivation lane or on the next read, whichever is first.
+ * Undoing to a filter step whose masks were kept (a mask copy) puts the kept bytes back instead of
+ * evaluating the filter again. See design/undo/undo-design.md section 3.4.
+ *
  * Nothing here reaches Babylon.js, Lit or the DOM.
  */
 import { type GraphSnapshot } from "@graphty/graph-format";
 import type { EdgeId, NodeId, Path, Scope } from "../../catalog/types";
-import { type EngineVersions, type ResolvedScope, type Run, type RunOptions, type RunQueue } from "../runs";
+import { Dispatcher } from "../project/Dispatcher";
+import { type EngineVersions, type ResolvedScope, type Run, type RunOptions } from "../runs";
 import { type ScopeVisibilitySource } from "../scope/index";
 import { type DependencySources } from "../sets/dependencies";
 import type { SetWatch } from "../sets/notify";
+import type { HistoryCause } from "../types";
 import { type FilterSources, type RuleTree, type TimeWindow } from "./filter";
 /**
  * How much of the graph is showing, which is what a status bar reads.
@@ -101,6 +110,8 @@ export interface FilterResult {
 export interface VisibilityChange extends FilterResult {
     /** What produced this change. */
     readonly filterKind: string;
+    /** Whether an edit, an undo, a redo, a restore or a rolled-back transaction made it. */
+    readonly cause: HistoryCause;
 }
 /** Hiding part of the graph, and saying how much is left. */
 export interface VisibilityApi {
@@ -151,17 +162,20 @@ export interface VisibilityApi {
     /**
      * Apply a filter, or clear it with null.
      *
-     * A `Run`, so a filter over a large graph reports progress and can be cancelled. Starting one
-     * CANCELS whatever visibility pass is already in flight: dragging a slider must not leave
-     * five walks queued behind each other, and only the latest instruction's answer matters. A
-     * cancelled pass changes nothing at all -- the masks are written in one step at the end.
+     * One undoable step: the filter is recorded at once (`filter` reads it as soon as this
+     * returns), and the masks are evaluated on the next pass against whatever filter is in force
+     * then, so a slider dragged through sixty values evaluates the last one, not all sixty, and
+     * the drag is one step. The run settles once that pass has run, with the counts it left.
+     *
+     * A signal already aborted when this is called writes nothing. A `cancel()` or an abort after
+     * the call does NOT take the filter back -- it has been recorded, and may have merged into a
+     * larger step -- so `session.undo()` is the way back.
      *
      * The time window is untouched. The two compose.
      *
-     * Of the run options, `signal` and `onProgress` are honoured; `queue` is not, because the
-     * coalescing above decides the order instead, and `dryRun` is REFUSED rather than ignored --
-     * `plan({ op: "visibility.set", filter })` is the call that answers "what would this leave
-     * showing" without doing it.
+     * Of the run options, `signal` and `onProgress` are honoured; `queue` is not, and `dryRun` is
+     * REFUSED rather than ignored -- `plan({ op: "visibility.set", filter })` is the call that
+     * answers "what would this leave showing" without doing it.
      * @param filter - What to keep, or null to stop filtering.
      * @param options - A signal to cancel with, and a progress handler.
      * @returns The run, which resolves with the counts.
@@ -169,7 +183,8 @@ export interface VisibilityApi {
      */
     set(filter: RuleTree | null, options?: RunOptions): Run<FilterResult>;
     /**
-     * Apply a time window, or clear it with null.
+     * Apply a time window, or clear it with null: one undoable step, on the same terms as
+     * {@link VisibilityApi.set}.
      *
      * The SAME masks as {@link VisibilityApi.set}, produced the same way, composed with whatever
      * filter is in force. Moving the window never re-layouts, rebuilds or removes data, which is
@@ -188,7 +203,8 @@ export interface VisibilityApi {
      * hid. The flag is owned here because it is part of what "visible" means to a consumer, and
      * it is honoured by the renderer, which draws the hidden nodes as a low-alpha point layer.
      * Turning it on changes NOTHING about the masks: a context node is still hidden, still
-     * outside every run's default scope, and still absent from `nodes`.
+     * outside every run's default scope, and still absent from `nodes`. Changing it is one
+     * undoable step.
      */
     showContext: boolean;
 }
@@ -201,7 +217,10 @@ export interface VisibilityApi {
  * anything.
  */
 export interface SessionVisibilityApi extends VisibilityApi {
-    /** The live masks, for the scope resolver. */
+    /**
+     * The masks, for the scope resolver and the renderer: read-only copies carrying the live
+     * masks' `version`, one per membership, so nothing holding one can change what is visible.
+     */
     readonly masks: ScopeVisibilitySource;
 }
 /** Everything the visibility model is built from. */
@@ -217,11 +236,10 @@ export interface VisibilitySources extends FilterSources {
      */
     snapshot(): GraphSnapshot;
     /**
-     * The queue a pass takes its turn in. Absent builds a sequential one of its own, which is
-     * right for a headless session and wrong for a rendered graph -- a rendered graph hands in
-     * the element's own operation queue so that a filter does not interleave with a load.
+     * The dispatcher whose `visibility` slice holds the filter, the window and the context flag.
+     * Absent, the model makes one of its own.
      */
-    readonly queue?: RunQueue;
+    readonly dispatcher?: Dispatcher;
     /**
      * Resolve a scope specification, so a pass can record what it looked at.
      *
@@ -234,7 +252,9 @@ export interface VisibilitySources extends FilterSources {
     /** Which versions are producing the numbers. Defaults to the element's own. */
     readonly engine?: EngineVersions;
     /**
-     * Called whenever what is visible changes, so a host can mirror it onto an event.
+     * Called whenever what is visible changes, so a host can mirror it onto an event: once the
+     * pass deriving the change has run, one call per edit, and one per step an undo, a redo or a
+     * restore passes.
      *
      * One hook for every producer -- a filter, a window and the context flag all arrive here --
      * because a status bar reading "showing X of Y" has to update for all three and must not
@@ -291,7 +311,7 @@ interface FilterWatchSources {
  * what makes the mask version a usable cache key for everything downstream: a new mask object
  * would start its revision at zero, and a reader keyed on it could not tell a fresh empty mask
  * from the one it had already seen.
- * @param sources - The snapshot, the queue, and the capabilities a filter needs.
+ * @param sources - The snapshot, the dispatcher, and the capabilities a filter needs.
  * @returns The visibility model, including the masks the scope resolver reads.
  */
 export declare function createVisibilityApi(sources: VisibilitySources): SessionVisibilityApi;

package/dist/src/session/visibility/filter.d.ts

@@ -219,6 +219,16 @@ export interface CompiledVisibility {
  * @throws A `GraphtyError` when either is malformed.
  */
 export declare function assertVisibility(filter: RuleTree | null, window: TimeWindow | null, dependencies?: DependencySources): void;
+/**
+ * Refuse a filter or a window this session could not evaluate, without evaluating it: the checks
+ * {@link compileVisibility} makes before it walks anything, so a filter is refused before it is
+ * recorded rather than on every later evaluation.
+ * @param filter - The filter, or null for none.
+ * @param window - The time window, or null for none.
+ * @param sources - What this session can evaluate with.
+ * @throws A `GraphtyError` when either is malformed or needs a capability this session lacks.
+ */
+export declare function assertEvaluable(filter: RuleTree | null, window: TimeWindow | null, sources: FilterSources): void;
 /** One filter's two halves, before they are folded together. */
 export interface CompiledHalves {
     /** The node test, or null when this filter says nothing about nodes. */

package/dist/src/simple/defineAlgorithm.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file `defineAlgorithm`: the simple tier's algorithm verb.
+ *
+ * One plain definition -- an id, options in short form, and ONE function (`node`, `edge`, `nodes`
+ * or `groups`) -- becomes an ordinary `DeclaredAlgorithm` subclass registered through
+ * `DeclaredAlgorithm.register`. Everything the element does for an advanced algorithm (the
+ * catalogue entry, option validation, the run record, derived rankings and styles, progress,
+ * cancellation, the cost estimate) it therefore does for this one, and parity holds by
+ * construction.
+ *
+ * What the element fills in: the descriptor (key, names, category "custom", shape and fields from
+ * the function), the loop over the nodes or edges with progress, yielding and cancellation, the
+ * id mapping, the output, unmeasured values, caveats and the cost model.
+ */
+import type { RegisterOptions } from "../catalog/pluginRegistry";
+import type { AlgorithmDefinition, OptionsShorthand } from "./types";
+/** A definition with no options, the default of the verb's generic. */
+type NoOptions = Readonly<Record<never, never>>;
+/**
+ * Register an algorithm from a plain definition object.
+ * @param definition - The id, the options in short form and ONE of `node`, `edge`, `nodes` or
+ *   `groups`.
+ * @param options - Whether a different algorithm under an id already taken throws instead of
+ *   replacing it.
+ * @throws A GraphtyError E_BAD_COMMAND for a malformed definition, before anything is registered.
+ */
+export declare function defineAlgorithm<const O extends OptionsShorthand = NoOptions>(definition: AlgorithmDefinition<O>, options?: RegisterOptions): void;
+export {};

package/dist/src/simple/defineLayout.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @file `defineLayout`: the simple tier's layout verb.
+ *
+ * A definition is an id, options in short form and `place(graph, context)`, which returns a map
+ * from node id to `[x, y]` or `[x, y, z]` in scene units. `defineLayout` checks the definition,
+ * fills in every catalogue member, and files an ordinary layout engine through the one layout
+ * registration there is, `LayoutEngine.register` -- so a simple layout IS an advanced one once
+ * registered: same catalogue entry shape, same option checks, same registry, same `setLayout`.
+ *
+ * What the element does for the author, so the definition never has to:
+ * - hands `place` the graph view over the whole graph and checks "attribute" and "node" options
+ *   against it first, so a misspelt column is refused with the columns the nodes do carry;
+ * - positions are scene units, with no hidden multiplier; a 2D position in a 3D view gets z = 0 and
+ *   a 3D position in a 2D view loses its z;
+ * - a node left out of the map, or given null or a non-finite number, is left unplaced;
+ * - a pinned or held node stays where it is (the element's position array refuses the write), and
+ *   `context.fixed(id)` says where it is;
+ * - `context.random()` is seeded; `random: true` declares a "seed" option and draws one when the
+ *   reader gives none;
+ * - `context.progress()` yields to the page and rejects once the layout is replaced;
+ * - a throw from `place` is `E_EXTENSION_FAILED`, and a map keyed by the wrong kind of id is
+ *   refused instead of silently placing nothing.
+ */
+import type { RegisterOptions } from "../catalog/pluginRegistry";
+import type { LayoutDefinition, OptionsShorthand } from "./types";
+/** A definition with no options, the default of the verb's generic. */
+type NoOptions = Readonly<Record<never, never>>;
+/**
+ * Register a layout from a plain definition object.
+ * @param definition - The id, the options in short form, and `place`.
+ * @param options - How to register it; `strict` refuses replacing a different layout under the id.
+ * @throws A GraphtyError E_BAD_COMMAND for a malformed definition, before anything is registered.
+ */
+export declare function defineLayout<const O extends OptionsShorthand = NoOptions>(definition: LayoutDefinition<O>, options?: RegisterOptions): void;
+export {};

package/dist/src/simple/defineLogDestination.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @file `defineLogDestination`: the simple tier's log destination verb.
+ *
+ * It builds an ordinary `LogSinkRegistration` -- a descriptor derived from the definition and a
+ * `create` that returns a `Sink` -- and hands it to `registerLogSink`, the advanced tier's own
+ * verb, so the registry cannot tell which tier produced it. Then it attaches one sink under the
+ * id, unless the definition says `attach: false`.
+ *
+ * WHAT THE WRAPPED SINK ADDS. The author's `write` receives a `PlainLogRecord` (the level as a
+ * word, the category as one dotted string, the error as plain data). A `write` that returns a
+ * promise is queued: records go out one at a time and in order, a rejection or a `Response`
+ * whose `ok` is false is retried after 1, 2 and 4 seconds (never a 4xx other than 408 or 429),
+ * at most 1000 records wait, `flush` awaits the queue and `dispose` drains it with a timeout.
+ * A `write` that returns nothing is called synchronously, exactly as an advanced sink is.
+ *
+ * THE DELIVERY RULE IS EVERY DESTINATION'S: the destination sits behind the same global gate as
+ * every other sink, so while logging is off (the default) it receives nothing.
+ * `GraphtyLogger.addSink` and advanced sinks are unchanged: the queue lives in this wrapper only.
+ */
+import type { RegisterOptions } from "../catalog/pluginRegistry";
+import type { LogDestinationDefinition } from "./types";
+/**
+ * Register a log destination from a plain definition object, and attach it unless it says
+ * `attach: false`.
+ * @param definition - The id, the level and categories it takes, and `write`.
+ * @param options - Whether a collision with an existing registration throws instead of replacing.
+ * @returns A function that detaches the destination.
+ * @throws A GraphtyError `E_BAD_COMMAND` naming the member at fault, or `E_DUPLICATE_PLUGIN` for
+ * an id the element keeps for its own destinations.
+ */
+export declare function defineLogDestination(definition: LogDestinationDefinition, options?: RegisterOptions): () => void;

package/dist/src/simple/definePalette.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file `definePalette`: the simple tier's palette verb.
+ *
+ * It builds an ordinary palette registration and hands it to `registerPalette`, so there is one
+ * validation path and one registry: a palette defined here and the same palette registered
+ * through the advanced tier are the same catalogue entry. What the element fills in is the plain
+ * name (from `name`, else the id in sentence case); `registerPalette` already derives the
+ * capacity, normalises every colour to six-digit hex and turns a missing colour-vision claim into
+ * no claim.
+ *
+ * The checks made HERE, before `registerPalette` sees the definition, are the ones whose message
+ * a beginner needs worded for the call they wrote: every refusal starts `definePalette("id"): `,
+ * and a `var(...)` colour or an empty string (a design token read before its stylesheet loaded)
+ * is refused with the line that reads the token first.
+ */
+import type { RegisterOptions } from "../catalog/pluginRegistry";
+import type { PaletteDefinition } from "./types";
+/**
+ * Register a palette from a kind and a list of colours.
+ * @param definition - The id, the kind, the colours, and optionally a name, a description and a
+ *   colour-vision claim.
+ * @param options - Whether a collision with an existing registration throws instead of replacing.
+ * @throws A `GraphtyError` with `E_BAD_COMMAND` naming the member at fault, or with
+ *   `E_DUPLICATE_PLUGIN` when the id is one of the element's own palettes.
+ */
+export declare function definePalette(definition: PaletteDefinition, options?: RegisterOptions): void;

package/dist/src/simple/definition.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @file What every `define*` function of the simple tier shares: checking the definition object
+ * before anything is registered, the names the element derives from an id, and the errors a
+ * beginner reads (design/extensions/simple-tier.md sections 2.1 and 2.4).
+ *
+ * A person following the guide reads the first line of an error and searches for it, so every
+ * message here starts with the call and the id (`defineLayout("acme-tiers"): ...`) or the id and
+ * the member at fault (`acme-tiers: place() threw for node 42 ...`), says what was expected in
+ * the words of the definition the author wrote, and names no internal concept.
+ *
+ * Nothing here reaches Babylon.js, Lit or the DOM.
+ */
+import { GraphtyError, type GraphtyErrorSource } from "../errors";
+/** The four verbs of the simple tier graphty-element builds. */
+export type SimpleVerb = "defineAlgorithm" | "defineLayout" | "definePalette" | "defineLogDestination";
+/**
+ * A value as a message describes it: what the author actually passed.
+ * @param value - The value.
+ * @returns A few words, such as `undefined`, `the number 3` or `a function`.
+ */
+export declare function describeValue(value: unknown): string;
+/**
+ * The refusal of a malformed definition: `E_BAD_COMMAND`, thrown by the `define*` call itself.
+ * @param verb - The call, such as "defineLayout".
+ * @param id - The definition's id, when it has a usable one.
+ * @param field - The member at fault, such as "place" or "options.tier".
+ * @param message - What was expected and what was given, as a sentence.
+ * @returns The error.
+ */
+export declare function badDefinition(verb: SimpleVerb, id: string | undefined, field: string, message: string): GraphtyError;
+/** A definition that has passed the shared checks: an object with a usable id. */
+type CheckedDefinition = Readonly<Record<string, unknown>> & {
+    readonly id: string;
+};
+/**
+ * Check what every definition shares: it is an object, and its id is a usable permanent id.
+ * The optional `name`, `description` and `version`, when present, must be strings.
+ * @param verb - The call.
+ * @param definition - What the author passed.
+ * @returns The definition, narrowed.
+ */
+export declare function checkDefinition(verb: SimpleVerb, definition: unknown): CheckedDefinition;
+/**
+ * Refuse a member that is not a function.
+ * @param verb - The call.
+ * @param definition - The checked definition.
+ * @param field - The member.
+ */
+export declare function requireFunction(verb: SimpleVerb, definition: CheckedDefinition, field: string): void;
+/**
+ * Refuse a member that is present and not one of a list of values.
+ * @param verb - The call.
+ * @param definition - The checked definition.
+ * @param field - The member.
+ * @param allowed - The values it may take.
+ */
+export declare function optionalOneOf(verb: SimpleVerb, definition: CheckedDefinition, field: string, allowed: readonly (string | number | boolean)[]): void;
+/**
+ * A key or an id in sentence case, for a name nobody wrote: "tierAttribute" reads "Tier
+ * attribute", "acme-hop-reach" reads "Acme hop reach".
+ * @param key - The key or id.
+ * @returns The words.
+ */
+export declare function sentenceCase(key: string): string;
+/**
+ * What pickers show for a definition: its `name`, or its id in sentence case.
+ * @param definition - The checked definition.
+ * @returns The name.
+ */
+export declare function displayName(definition: CheckedDefinition): string;
+/** Who was running when the author's own function threw. */
+interface AuthorCall {
+    /** The extension's id. */
+    readonly id: string;
+    /** The member of the definition that was called, such as "edge" or "place". */
+    readonly member: string;
+    /** What it was called for, worded for the message: `node 42`, `edge "17"`. Optional. */
+    readonly subject?: string;
+    /** Which area of the element the failure belongs to. */
+    readonly source: GraphtyErrorSource;
+}
+/**
+ * The error a throw from the author's own function becomes: `E_EXTENSION_FAILED`, never
+ * `E_INTERNAL`, which would tell the reader to file an issue against graphty-element.
+ * @param call - Who was running.
+ * @param cause - What the function threw.
+ * @returns The error, carrying the original as `cause`.
+ */
+export declare function extensionFailed(call: AuthorCall, cause: unknown): GraphtyError;
+/**
+ * Call the author's function, turning a throw into `E_EXTENSION_FAILED`. A `GraphtyError` passes
+ * through unchanged: it is already coded, and it may be the element's own refusal raised from
+ * inside the call (a path nothing carries, a directed accessor on an undirected view).
+ * @param call - Who is running.
+ * @param work - The call.
+ * @returns What the function returned.
+ */
+export declare function callAuthor<T>(call: AuthorCall, work: () => T): T;
+/**
+ * {@link callAuthor} for a function that may return a promise.
+ * @param call - Who is running.
+ * @param work - The call.
+ * @returns What the function returned, awaited.
+ */
+export declare function callAuthorAsync<T>(call: AuthorCall, work: () => T | Promise<T>): Promise<T>;
+export {};

package/dist/src/simple/options.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file Options in short form, and the checks a run or a layout makes on them before the author's
+ * code runs (design/extensions/simple-tier.md section 2.2).
+ *
+ * `options: { tier: { type: "attribute", default: "tier" }, spacing: 2 }` is expanded into the
+ * ordinary `OptionDescriptor[]` every advanced extension declares, so the reader's form, the
+ * validation, the defaults and the catalogue entry work exactly as for a built-in.
+ *
+ * Nothing here reaches Babylon.js, Lit or the DOM.
+ */
+import { type OptionDescriptor } from "../catalog/types";
+import { type GraphtyErrorSource } from "../errors";
+import { type SimpleVerb } from "./definition";
+import type { GraphView } from "./types";
+/**
+ * Expand a definition's `options` into option descriptors, refusing a malformed entry.
+ * @param verb - The call, for the refusal.
+ * @param id - The definition's id.
+ * @param options - What the definition carried under `options`.
+ * @returns The descriptors, in key order.
+ */
+export declare function expandOptions(verb: SimpleVerb, id: string, options: unknown): OptionDescriptor[];
+/**
+ * Check the resolved options of one run or layout against the graph before the author's code
+ * runs: an "attribute" option must name an attribute some element carries, and a "node-id" or
+ * "node-set" option must name nodes the graph has. An unbound option (undefined) is not checked.
+ * @param view - The graph view the code will read.
+ * @param id - The extension's id.
+ * @param descriptors - The declared options.
+ * @param values - The resolved values.
+ * @param source - Which area of the element a refusal names.
+ */
+export declare function checkViewOptions(view: GraphView, id: string, descriptors: readonly OptionDescriptor[], values: Readonly<Record<string, unknown>>, source?: GraphtyErrorSource): void;

package/dist/src/simple/source.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @file What a simple-tier graph view is built from: the current snapshot, and the one reader a
+ * style selector reads values through.
+ *
+ * `node.attr(path)` promises to resolve a path "exactly as a style selector resolves it"
+ * (design/extensions/simple-tier.md section 2.3 rule 3). The only way to keep that promise is to
+ * read through the same code, so this builds the view's reader with `createSelectorSource` -- the
+ * factory the session's style stack, query engine and selection all read through -- over the
+ * session's own records and results. A `results.<run>.<field>` path therefore reads a finished
+ * run's published values exactly as a style layer bound to it does.
+ *
+ * Nothing here reaches Babylon.js, Lit or the DOM.
+ */
+import type { GraphSnapshot } from "@graphty/graph-format";
+import type { GraphSession } from "../session/types";
+/** Which kind of element a path is read on. */
+export type ViewTarget = "node" | "edge";
+/** Everything a graph view reads. */
+export interface ViewSource {
+    /** The graph, frozen: the view is built once over it and never follows a later freeze. */
+    readonly snapshot: GraphSnapshot;
+    /**
+     * One node's value at a path.
+     * @param row - The node's row in `snapshot`.
+     * @param path - The path, as a style selector spells it.
+     * @returns The value, or undefined when the node carries none.
+     */
+    nodeValue(row: number, path: string): unknown;
+    /**
+     * One edge's value at a path.
+     * @param row - The edge's row in `snapshot`.
+     * @param path - The path.
+     * @returns The value, or undefined when the edge carries none.
+     */
+    edgeValue(row: number, path: string): unknown;
+    /**
+     * The attribute names one kind of element carries, for a refusal that lists them. Optional: a
+     * refusal without it says only what was not found.
+     * @param target - Nodes or edges.
+     * @returns The names, in a stable order.
+     */
+    attributeNames?(target: ViewTarget): readonly string[];
+}
+/**
+ * The view source over a session's graph as it stands now.
+ * @param session - The session: an element's (`graph.getSession()`) or a headless one.
+ * @returns The source, pinned to the current snapshot.
+ */
+export declare function viewSourceOf(session: GraphSession): ViewSource;