@graphty/graphty-element 2.2.5 → 2.3.1

package/dist/src/session/styles/predicate.d.ts

@@ -115,6 +115,19 @@ export interface SelectorSource {
      * @returns The indices, or undefined when the column cannot be enumerated.
      */
     readonly measured?: (path: Path, target: SelectorTarget) => ArrayLike<number> | undefined;
+    /**
+     * The lowest value in the top `n` of one run column, cut only between tie groups (see
+     * `RunResult.top`), or undefined when nothing is taken or the column is not a ranked run
+     * field for this kind of element. Absent, a `{match:"top"}` selector is refused.
+     *
+     * Asked once per element, so it must answer from something already computed: a session
+     * reads it off the run's result, which keeps the answer per field and `n`.
+     * @param path - The column path, `results.<run>.<field>`.
+     * @param target - Whether the asking layer paints nodes or edges.
+     * @param n - The most elements the top may hold.
+     * @returns The cut, or undefined.
+     */
+    readonly topCut?: (path: Path, target: SelectorTarget, n: number) => number | undefined;
 }
 /**
  * One target's half of a {@link SelectorSource}, resolved once so the predicate never chooses.
@@ -160,7 +173,7 @@ export type ElementPredicate = (index: number) => boolean;
 /** A selector, reduced to the test a repaint runs and the columns that test reads. */
 export interface CompiledSelector {
     /** Which selector kind this was compiled from. */
-    readonly match: "everything" | "expression" | "has" | "ids";
+    readonly match: "everything" | "expression" | "has" | "ids" | "top";
     /** Which kind of element it speaks about. */
     readonly target: SelectorTarget;
     /**
@@ -231,6 +244,18 @@ export declare function hasPredicate(columns: ElementColumns, path: Path): Eleme
  * @returns The test.
  */
 export declare function idsPredicate(columns: ElementColumns, ids: ReadonlySet<EdgeId | NodeId>): ElementPredicate;
+/**
+ * The predicate for `{match:"top"}`: the element's value is at or above the top's cut.
+ *
+ * The cut is asked for per element rather than settled here, because a run that finishes or
+ * re-runs after the layer was added publishes a new ranking, and a cut captured now would go on
+ * painting the old top.
+ * @param columns - Where to read values.
+ * @param path - The column path.
+ * @param cutOf - The lowest value in the top, or undefined when nothing is in it.
+ * @returns The test.
+ */
+export declare function topPredicate(columns: ElementColumns, path: Path, cutOf: () => number | undefined): ElementPredicate;
 /**
  * Parse and compile `{match:"expression"}`.
  *

package/dist/src/session/styles/repaint.d.ts

@@ -211,6 +211,17 @@ export interface ElementPaint {
      * @returns A function that stops the notifications.
      */
     onPainted(listener: () => void): () => void;
+    /**
+     * Whether a pass has been asked for and has not finished yet.
+     *
+     * A pass YIELDS TO THE EVENT LOOP and waits behind the pass in front of it, so between the
+     * edit that asks for it and the announcement that ends it there are frames -- as many as the
+     * machine is slow. Nothing is in {@link ElementPaint.lastPainted} for those frames, and a
+     * renderer that asked only whether paint was waiting to be drawn would call the picture
+     * finished, and frame the camera on it, while a node's new size was still on its way.
+     * @returns True from the moment a pass is requested until it has announced what it painted.
+     */
+    painting(): boolean;
     /**
      * The layers the last pass could not paint, and why.
      * @returns The problems, emptied at the start of every pass.

package/dist/src/session/styles/selector.d.ts

@@ -68,6 +68,17 @@ export type Selector =
     readonly match: "ids";
     readonly nodes?: readonly NodeId[];
     readonly edges?: readonly EdgeId[];
+}
+/**
+ * The top `n` elements by one run field, `results.<run>.<field>`, cut only between tie
+ * groups: a group of equal values is painted whole, and only when all of it fits inside `n`.
+ * So a layer never paints more than `n` elements, and paints none on a graph whose highest
+ * value is shared by more than `n`. `RunResult.top` is the same cut with its reason.
+ */
+ | {
+    readonly match: "top";
+    readonly path: Path;
+    readonly n: number;
 };
 /**
  * Turn a selector into the predicate a repaint runs.
@@ -81,6 +92,7 @@ export type Selector =
  * @returns The compiled selector: its test, and the columns that test reads.
  * @throws A `GraphtyError` with code `E_BAD_SELECTOR` when the selector's shape or its
  *     expression is wrong, `E_SELECTOR_EMPTY` when a selector is empty, and `E_UNSUPPORTED`
- *     when an `ids` selector is offered to a session that cannot say which id sits at which row.
+ *     when an `ids` selector is offered to a session that cannot say which id sits at which row,
+ *     or a `top` selector to one that cannot rank a run's column.
  */
 export declare function compileSelector(selector: Selector, target: SelectorTarget, source: SelectorSource): CompiledSelector;

package/dist/src/session/styles/sources.d.ts

@@ -131,6 +131,15 @@ export interface SessionSelectorSource extends SelectorSource {
      * @returns The indices, ascending, or undefined when the column cannot be enumerated.
      */
     readonly measured: (path: Path, target: SelectorTarget) => ArrayLike<number> | undefined;
+    /**
+     * The lowest value in the top `n` of a run's column, from `RunResult.top`, which keeps it.
+     * @param path - The column path, `results.<run>.<field>`.
+     * @param target - Whether the asking layer paints nodes or edges.
+     * @param n - The most elements the top may hold.
+     * @returns The cut, or undefined when nothing is taken or the path names no numeric field of
+     *     this kind of element.
+     */
+    readonly topCut: (path: Path, target: SelectorTarget, n: number) => number | undefined;
 }
 /**
  * The id of the node at one end of an edge, for the attribute keys that name an endpoint.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/graphty-element",
-  "version": "2.2.5",
+  "version": "2.3.1",
   "description": "A Web Component library for 3D/2D graph visualization built with Lit and Babylon.js",
   "type": "module",
   "customElements": "./dist/custom-elements.json",

package/dist/chunks/Algorithm-RQ629NLb.js

@@ -1,494 +0,0 @@
-import { q as C } from "./GraphtyLogger-5KEttFUo.js";
-import { K as $, f as N } from "./types-B7bX5c0K.js";
-import { G as d } from "./GraphtyError-BwcnblTH.js";
-import { Graph as _, accelerated as y } from "@graphty/algorithms";
-import { INVALID_INDEX as w } from "@graphty/graph-format";
-const p = C({
-  kind: "camera",
-  idOf: (e) => e.descriptor.id,
-  descriptorOf: (e) => e.descriptor,
-  implementationOf: (e) => e.compute,
-  builtInIds: () => $
-});
-function K(e, t) {
-  const s = e.descriptor;
-  if (s === void 0 || typeof s != "object")
-    throw new d({
-      code: "E_BAD_COMMAND",
-      message: "registerCameraView takes a camera view with a descriptor",
-      source: "registry",
-      details: { kind: "camera", field: "descriptor" }
-    });
-  if (!Array.isArray(s.modes) || s.modes.length === 0)
-    throw new d({
-      code: "E_BAD_COMMAND",
-      message: `the camera view "${String(s.id)}" declares no drawing modes, so nothing could ever offer it: a view says where it works with \`modes\`, and the element refuses the rest`,
-      source: "registry",
-      details: { kind: "camera", name: String(s.id), field: "modes" }
-    });
-  if (!Array.isArray(s.options))
-    throw new d({
-      code: "E_BAD_COMMAND",
-      message: `the camera view "${String(s.id)}" declares no options list. A view that takes no configuration declares an empty one, so a form has something to render and the element has something to check a caller's values against`,
-      source: "registry",
-      details: { kind: "camera", name: String(s.id), field: "options" }
-    });
-  if (typeof e.compute != "function")
-    throw new d({
-      code: "E_BAD_COMMAND",
-      message: `the camera view "${String(s.id)}" was registered without a compute function`,
-      source: "registry",
-      details: { kind: "camera", name: String(s.id), field: "compute" }
-    });
-  p.register(e, t);
-}
-function z() {
-  return p.descriptors();
-}
-function W(e) {
-  return p.byId(e);
-}
-function Y() {
-  p.clearForTesting();
-}
-const I = ["forceAtlas2", "fruchtermanReingold", "springElectrical", "release"], k = [
-  "pageRank",
-  "sssp",
-  "breadthFirstSearch",
-  "connectedComponents",
-  "weaklyConnectedComponents",
-  "minimumSpanningTree"
-];
-function H(e) {
-  const t = {
-    kind: e.backend
-  };
-  for (const s of I) {
-    const r = e[s];
-    typeof r == "function" && (t[s] = r.bind(e));
-  }
-  return t;
-}
-function R(e) {
-  const t = {
-    kind: e.backend
-  };
-  for (const s of k) {
-    const r = e[s];
-    typeof r == "function" && (t[s] = r.bind(e));
-  }
-  return t;
-}
-const D = ["auto", "off", "required"], Z = "auto";
-function X(e) {
-  return typeof e == "string" && D.includes(e);
-}
-const M = "f64", J = "f32", Q = "acceleration.minNodes", ee = 0, g = C({
-  kind: "algorithm",
-  idOf: (e) => e.descriptor.key,
-  descriptorOf: (e) => e.descriptor,
-  implementationOf: (e) => e.descriptor,
-  builtInIds: () => N
-});
-function T(e, t) {
-  if (e.descriptor.key !== e.type)
-    throw new d({
-      code: "E_BAD_COMMAND",
-      message: `the algorithm registered as "${e.namespace}:${e.type}" publishes the catalogue key "${e.descriptor.key}". An algorithm has one name: make "descriptor.key" equal "static type".`,
-      source: "registry",
-      details: {
-        kind: "algorithm",
-        field: "descriptor.key",
-        key: e.descriptor.key,
-        type: e.type,
-        namespace: e.namespace
-      }
-    });
-  g.register(e, t);
-}
-function te() {
-  return g.descriptors();
-}
-function se(e) {
-  return g.byId(e);
-}
-function re() {
-  g.clearForTesting();
-}
-class a extends Error {
-  /**
-   * Creates an option validation error
-   * @param optionKey - The key of the option that failed validation
-   * @param message - The validation error message
-   */
-  constructor(t, s) {
-    super(`Option '${t}': ${s}`), this.optionKey = t, this.name = "OptionValidationError";
-  }
-}
-function v(e, t, s) {
-  if (t == null) {
-    if (s.required)
-      throw new a(e, "is required but was not provided");
-    return;
-  }
-  switch (s.type) {
-    case "number":
-      A(e, t, s, !1);
-      break;
-    case "integer":
-      A(e, t, s, !0);
-      break;
-    case "boolean":
-      if (typeof t != "boolean")
-        throw new a(e, `must be a boolean, got ${typeof t}`);
-      break;
-    case "string":
-      if (typeof t != "string")
-        throw new a(e, `must be a string, got ${typeof t}`);
-      break;
-    case "select":
-      L(e, t, s);
-      break;
-    case "nodeId":
-      if (typeof t != "string" && typeof t != "number")
-        throw new a(e, `must be a string or number (node ID), got ${typeof t}`);
-      break;
-    default:
-      throw new a(e, `has unknown type '${s.type}'`);
-  }
-}
-function A(e, t, s, r) {
-  if (typeof t != "number")
-    throw new a(e, `must be a number, got ${typeof t}`);
-  if (Number.isNaN(t))
-    throw new a(e, "must not be NaN");
-  if (!Number.isFinite(t))
-    throw new a(e, "must be finite");
-  if (r && !Number.isInteger(t))
-    throw new a(e, `must be an integer, got ${t}`);
-  if (s.min !== void 0 && t < s.min)
-    throw new a(e, `must be >= ${s.min}, got ${t}`);
-  if (s.max !== void 0 && t > s.max)
-    throw new a(e, `must be <= ${s.max}, got ${t}`);
-}
-function L(e, t, s) {
-  if (!s.options || s.options.length === 0)
-    throw new a(e, "is a select type but has no options defined");
-  if (!s.options.map((n) => n.value).includes(t)) {
-    const n = s.options.map((i) => `'${String(i.value)}'`).join(", ");
-    throw new a(e, `must be one of [${n}], got '${String(t)}'`);
-  }
-}
-function P(e, t) {
-  const s = {};
-  for (const [r, n] of Object.entries(e)) {
-    const c = t?.[r] ?? n.default;
-    v(r, c, n), s[r] = c;
-  }
-  return s;
-}
-function ne(e) {
-  return e;
-}
-function x(e, t) {
-  const s = e.getSnapshot(), r = t === "directed" ? s : e.undirected(s).snapshot, n = r.flags.multigraph ? r.simplified({ weights: "sum" }).snapshot : r;
-  return B(n, t);
-}
-function oe(e) {
-  const t = e.getSnapshot();
-  return t.flags.multigraph ? t.edgeCount - t.simplified({ weights: "sum" }).snapshot.edgeCount : 0;
-}
-function B(e, t) {
-  const s = new _({
-    directed: t !== "undirected"
-  }), { ids: r } = e;
-  for (let o = 0; o < e.nodeCount; o++)
-    s.addNode(r.idOf(o));
-  const { src: n, dst: i, weights: c } = e.edgeList();
-  for (let o = 0; o < e.edgeCount; o++) {
-    const u = r.idOf(n[o]), h = r.idOf(i[o]), l = c === null ? 1 : c[o];
-    s.addEdge(u, h, l);
-  }
-  return s;
-}
-const m = /* @__PURE__ */ new Map();
-function F(e, t) {
-  if (t === null)
-    return e;
-  if (e === null)
-    return t;
-  const s = new Uint32Array(e.length);
-  for (let r = 0; r < e.length; r++) {
-    const n = e[r];
-    s[r] = n === w ? w : t[n];
-  }
-  return s;
-}
-const O = class O {
-  /**
-   * Getter for schema options
-   *
-   * Algorithms that use the new schema-based options should access
-   * options via this getter.
-   * @returns The resolved schema options
-   */
-  get schemaOptions() {
-    return this._schemaOptions;
-  }
-  /**
-   * Creates a new algorithm instance
-   * @param g - The graph to run the algorithm on
-   * @param options - Optional configuration options (uses schema defaults if not provided)
-   */
-  constructor(t, s) {
-    this.graph = t, this._schemaOptions = this.resolveOptions(s);
-  }
-  /**
-   * The `@graphty/algorithms` Graph this run reads, built from the element's graph snapshot.
-   *
-   * This is the ONLY way an algorithm should obtain its input. The `Node` and `Edge` objects the
-   * data manager also holds are render objects -- each `Node` builds a Babylon mesh in its
-   * constructor -- and reading the graph out of them ties every algorithm to a renderer and to
-   * whatever part of a data load the scene has caught up with.
-   * @param mode - the shape this algorithm needs; see {@link AlgorithmGraphMode}
-   * @returns a freshly built Graph for the algorithm package
-   */
-  algorithmGraph(t) {
-    return x(this.graph.getDataManager(), t);
-  }
-  /**
-   * The route an algorithm with an accelerated implementation takes.
-   *
-   * It is the counterpart of {@link algorithmGraph} for the algorithms `@graphty/algorithms`
-   * can dispatch: instead of copying the snapshot into an object graph, the work runs over the
-   * snapshot itself, on the attached accelerator or on the index-based CPU port, and the adapter
-   * writes one loop over an index-aligned result either way.
-   *
-   * THE DECISION IS TAKEN ONCE, HERE, BEFORE ANY WORK STARTS. The controller answers "the policy
-   * is off", "no accelerator", "below `acceleration.minNodes`" or "this accelerator does not
-   * implement that" up front, and under `acceleration="required"` it throws `E_NO_ACCELERATOR`
-   * rather than answering quietly. After the work has started there is no second decision: a
-   * failure from the accelerator propagates with its code and fails the run, because a number
-   * that silently came from somewhere else is worse than no number.
-   * @param capability - The accelerator member this work would use, such as `"pageRank"`.
-   * @param mode - The shape this algorithm needs; see {@link AlgorithmGraphMode}. `"undirected"`
-   *   takes the snapshot's undirected view, which is what collapses a reciprocal pair into one
-   *   edge.
-   * @returns The snapshot, the edge map onto it, and the runner.
-   * @example
-   * ```ts
-   * const { snapshot, run } = this.accelerated("connectedComponents", "undirected");
-   * const { value, precision } = await run((dispatch, s) => dispatch.connectedComponents(s));
-   * const group = value.labels[snapshot.ids.indexOf(nodeId)];
-   * ```
-   */
-  accelerated(t, s) {
-    const r = this.graph.getDataManager(), n = r.getSnapshot(), i = s === "undirected" ? r.undirected(n) : null, c = i === null ? n : i.snapshot, o = c.flags.multigraph ? c.simplified({ weights: "sum" }) : null, u = o === null ? c : o.snapshot, h = this.graph.acceleration, l = { capability: t, nodeCount: u.nodeCount };
-    return {
-      snapshot: u,
-      edgeRemap: F(i?.edgeRemap ?? null, o?.edgeRemap ?? null),
-      run: async (b) => {
-        const f = await h.run(
-          l,
-          (S) => b(y(R(S)), u)
-        );
-        return f.accelerated ? { value: f.value, precision: f.precision } : { value: await b(y(null), u), precision: M };
-      }
-    };
-  }
-  /**
-   * The dense row of a node the reader named in an option.
-   *
-   * A search takes its source as an id and the snapshot answers in indices, so this is where the
-   * two meet -- and where an id that names no node in the graph is reported as what it is: an
-   * option whose value is outside the permitted range, carrying the option's name and what was
-   * passed, rather than a silent empty result or a search from row zero.
-   * @param snapshot - The graph the work runs over.
-   * @param option - The option the id came from, named in the error.
-   * @param id - The node id the reader gave.
-   * @returns The node's dense row.
-   * @throws A `GraphtyError` with `E_OPTION_RANGE` when the graph has no such node.
-   */
-  nodeIndex(t, s, r) {
-    const n = t.ids.indexOf(r);
-    if (n === w)
-      throw new d({
-        code: "E_OPTION_RANGE",
-        message: `the graph has no node "${String(r)}", so "${s}" names nothing to run from`,
-        source: "run",
-        details: { option: s, value: r }
-      });
-    return n;
-  }
-  /**
-   * Resolves and validates options against the schema
-   * @param options - User-provided options (partial)
-   * @returns Fully resolved options with defaults applied
-   */
-  resolveOptions(t) {
-    const s = this.constructor.optionsSchema;
-    return Object.keys(s).length === 0 ? {} : P(s, t);
-  }
-  /**
-   * Gets the algorithm type
-   * @returns The algorithm type identifier
-   */
-  get type() {
-    return this.constructor.type;
-  }
-  /**
-   * Gets the algorithm namespace
-   * @returns The algorithm namespace identifier
-   */
-  get namespace() {
-    return this.constructor.namespace;
-  }
-  /**
-   * Compute this algorithm and publish what it produced as a result object.
-   *
-   * This is the entry point the run machinery calls, and it is the one that makes an algorithm
-   * startable as a `Run`: it takes a signal it must throw from, a progress channel, a yield, and
-   * the run id the result is published under -- and it RETURNS the result rather than writing it
-   * somewhere a caller has to go looking for. `run()` is the 1.10 entry point beside it, which
-   * returns nothing and can be neither watched nor stopped.
-   *
-   * The default refuses, because an algorithm that has not been migrated genuinely cannot answer
-   * a run: it publishes through side effects under its own names and has no result object to
-   * hand back. Both shipped families -- a metric and a declared algorithm -- override it.
-   * @param _context - A signal, a progress channel and a yield.
-   * @param runId - The id the result is published under.
-   * @param _fields - The catalogue's descriptors for this algorithm's fields, when the caller
-   *   holds them.
-   * @returns The result, or undefined when there was nothing to compute.
-   * @throws A `GraphtyError` with code `E_UNSUPPORTED` when this algorithm has no result to
-   *   publish.
-   */
-  publishResult(t, s, r) {
-    return Promise.reject(
-      new d({
-        code: "E_UNSUPPORTED",
-        message: `The "${this.namespace}:${this.type}" algorithm writes its result through side effects and cannot be started as a run.`,
-        source: "run",
-        target: { kind: "run", id: s },
-        details: { algorithm: `${this.namespace}:${this.type}` }
-      })
-    );
-  }
-  /**
-   * Registers an algorithm class in the global registry
-   * @param cls - The algorithm class to register
-   * @returns The registered algorithm class
-   */
-  static register(t) {
-    const s = t, r = String(s.type), n = String(s.namespace), { descriptor: i, cost: c, version: o } = s;
-    return i !== void 0 && T({
-      descriptor: i,
-      namespace: n,
-      type: r,
-      ...c === void 0 ? {} : { cost: c },
-      ...o === void 0 ? {} : { version: o }
-    }), m.set(`${n}:${r}`, t), t;
-  }
-  /**
-   * Gets an algorithm instance from the registry
-   * @param g - The graph to run the algorithm on
-   * @param namespace - The algorithm namespace
-   * @param type - The algorithm type
-   * @param options - Optional algorithm-specific options to pass to constructor
-   * @returns A new instance of the algorithm, or null if not found
-   */
-  static get(t, s, r, n) {
-    const i = m.get(`${s}:${r}`);
-    return i ? new i(t, n) : null;
-  }
-  /**
-   * Gets an algorithm class from the registry
-   * @param namespace - The algorithm namespace
-   * @param type - The algorithm type
-   * @returns The algorithm class, or null if not found
-   */
-  static getClass(t, s) {
-    return m.get(`${t}:${s}`) ?? null;
-  }
-  /**
-   * Get the options schema for this algorithm
-   * @returns The options schema, or an empty object if no options defined
-   * @deprecated Use getZodOptionsSchema() instead
-   */
-  static getOptionsSchema() {
-    return this.optionsSchema;
-  }
-  /**
-   * Check if this algorithm has configurable options
-   * @returns true if the algorithm has at least one option defined
-   * @deprecated Use hasZodOptions() instead
-   */
-  static hasOptions() {
-    return Object.keys(this.optionsSchema).length > 0;
-  }
-  /**
-   * Get the Zod-based options schema for this algorithm.
-   * @returns The Zod options schema, or an empty object if no schema defined
-   */
-  static getZodOptionsSchema() {
-    return this.zodOptionsSchema ?? {};
-  }
-  /**
-   * Check if this algorithm has a Zod-based options schema.
-   * @returns true if the algorithm has a Zod options schema defined
-   */
-  static hasZodOptions() {
-    return this.zodOptionsSchema !== void 0 && Object.keys(this.zodOptionsSchema).length > 0;
-  }
-  /**
-   * Get all registered algorithm names.
-   * @param namespace - Optional namespace to filter by
-   * @returns Array of algorithm names in "namespace:type" format
-   */
-  static getRegisteredAlgorithms(t) {
-    const s = [];
-    for (const r of m.keys())
-      (!t || r.startsWith(`${t}:`)) && s.push(r);
-    return s.sort();
-  }
-  /**
-   * Get all registered algorithm types.
-   * This method is provided for API consistency with DataSource.
-   * @returns Array of algorithm keys in "namespace:type" format
-   * @since 1.5.0
-   * @example
-   * ```typescript
-   * const types = Algorithm.getRegisteredTypes();
-   * console.log('Available algorithms:', types);
-   * // ['graphty:betweenness', 'graphty:closeness', 'graphty:degree', ...]
-   * ```
-   */
-  static getRegisteredTypes() {
-    return this.getRegisteredAlgorithms();
-  }
-};
-O.optionsSchema = {};
-let E = O;
-export {
-  E as A,
-  M as C,
-  J as D,
-  a as O,
-  Y as a,
-  te as b,
-  re as c,
-  ne as d,
-  z as e,
-  P as f,
-  D as g,
-  Z as h,
-  X as i,
-  W as j,
-  ee as k,
-  Q as l,
-  se as m,
-  H as n,
-  oe as o,
-  K as r,
-  v
-};