libpetri 1.8.5 → 2.1.0

package/dist/viewer/index.d.ts

@@ -0,0 +1,227 @@
+import panzoom from 'panzoom';
+
+/**
+ * Pan/zoom wrapper for the canonical libpetri viewer.
+ *
+ * Delegates to the `panzoom` library (no hand-rolled wheel handlers — we
+ * intentionally drop the IIFE/javadoc version's bespoke math in favour of
+ * a single battle-tested implementation). Defaults match the old debug-ui
+ * and dev-preview values so the canonical viewer feels identical to what
+ * users had before.
+ *
+ * @module viewer/pan-zoom
+ */
+
+type PanzoomInstance = ReturnType<typeof panzoom>;
+type PanzoomOptions = Parameters<typeof panzoom>[1];
+/**
+ * Default panzoom configuration shared across all viewer surfaces.
+ *
+ * - `maxZoom: 1000` — effectively unlimited; lets users dive into ~150-node
+ *   diagrams without hitting an artificial ceiling.
+ * - `minZoom: 0.02` — allows fitting very large nets in a small viewport.
+ * - `smoothScroll: false` — sharper interactive feel.
+ * - `zoomDoubleClickSpeed: 1` — single-click double-zoom toggle.
+ */
+declare const DEFAULT_PANZOOM_OPTS: {
+    readonly smoothScroll: false;
+    readonly zoomDoubleClickSpeed: 1;
+    readonly maxZoom: 1000;
+    readonly minZoom: 0.02;
+};
+
+/**
+ * Cluster overlay for the canonical libpetri viewer.
+ *
+ * Post-processes a rendered SVG to surface subnet structure visually:
+ *  1. Discover `<g class="cluster">` subgraphs, derive each prefix from the
+ *     contained `<title>` (Graphviz emits `cluster_<sanitizedPrefix>`).
+ *  2. Tag every contained `<g class="node">` with `data-instance="<prefix>"`
+ *     so filtering can target it via attribute selectors.
+ *  3. Assign each cluster a deterministic HSL colour (FNV-1a hash + golden
+ *     ratio hue increment) and paint its border.
+ *  4. Provide collapse/expand and "show only <prefix>" filtering.
+ *
+ * Unlike the previous debug-ui cluster-overlay, this module is instance-
+ * based: every `mount()` call gets its own `ClusterOverlay` so multiple
+ * viewers on the same page don't share collapse/isolate state.
+ *
+ * @module viewer/cluster-overlay
+ */
+/** A discovered cluster with its DOM group, node count, and palette colour. */
+interface ClusterDescriptor {
+    readonly prefix: string;
+    readonly group: SVGGElement;
+    readonly nodeCount: number;
+    readonly color: string;
+}
+/**
+ * Walk the SVG, find every `<g class="cluster">`, derive the prefix from
+ * each cluster's `<title>` (`cluster_<sanitized>`), and tag every cluster-
+ * interior `<g class="node">` with `data-instance="<prefix>"`. Returns one
+ * descriptor per cluster.
+ *
+ * Graphviz emits cluster nodes as SIBLINGS of the cluster `<g>`, not as
+ * children — `<g class="cluster">` only carries title, polygon border, and
+ * the cluster's text label. To recover cluster membership we match each
+ * node's `<title>` (the original graph id) against libpetri's prefixing
+ * convention: interior places are emitted as `p_<prefix>_<name>`,
+ * transitions as `t_<prefix>_<name>`, and junctions as `j_<prefix>_<name>`.
+ *
+ * Does not split nested-cluster prefixes (`outer_inner` could mean either
+ * `outer/inner` or a flat `outer_inner` prefix — Graphviz sanitisation is
+ * lossy). We treat every cluster as its own top-level entry, matching the
+ * doclet's pragmatism.
+ */
+declare function discoverClusters(svg: SVGSVGElement): Map<string, ClusterDescriptor>;
+/**
+ * Deterministic HSL palette. FNV-1a-ish hash of the prefix, multiplied by
+ * the golden-ratio fraction (0.61803...) to spread adjacent prefixes
+ * visually. Saturation/lightness are fixed (60% / 45%) so the palette
+ * stays readable on both the doc background and the dark debug UI.
+ */
+declare function colorForPrefix(prefix: string): string;
+
+interface VisibilityState {
+    /** Cluster short names currently visible. */
+    readonly visibleClusters: ReadonlySet<string>;
+    /**
+     * When false, hide every replica/shared place (`g.node.petri-replica`)
+     * regardless of which cluster it belongs to. The corresponding sidebar
+     * checkbox is labelled "Shared places".
+     */
+    readonly includeSharedPlaces: boolean;
+}
+
+/**
+ * CSS custom properties exposed by the canonical viewer stylesheet.
+ *
+ * Each property has a default in `viewer.css`. Consumers can override any of
+ * them at any scope (the viewer container, the document root, etc.) to
+ * theme the viewer without touching the canonical CSS.
+ *
+ * Names are listed here as a reference + so the IIFE bundle can expose them
+ * on `window.LibpetriViewer.cssVariables`. The list is informational — the
+ * stylesheet is still the source of truth.
+ *
+ * @module viewer/styles
+ */
+/** CSS custom property names that the canonical stylesheet honours. */
+declare const VIEWER_CSS_VARIABLES: readonly ["--lpv-bg", "--lpv-header-bg", "--lpv-border", "--lpv-text", "--lpv-muted", "--lpv-cluster-bg", "--lpv-cluster-bg-collapsed", "--lpv-cluster-stroke-width", "--lpv-cluster-stroke-dash", "--lpv-cluster-fill-tint", "--lpv-dim-opacity", "--lpv-active-filter-outline", "--lpv-legend-bg", "--lpv-chip-bg", "--lpv-chip-active-bg", "--lpv-sidebar-bg", "--lpv-sidebar-border", "--lpv-sidebar-text", "--lpv-sidebar-muted", "--lpv-sidebar-chip-bg", "--lpv-sidebar-chip-hover-bg", "--lpv-sidebar-chip-off-opacity", "--lpv-shared-glyph-color", "--lpv-replica-fill", "--lpv-replica-stroke", "--lpv-highlight-stroke", "--lpv-highlight-glow", "--lpv-neighbor-stroke", "--lpv-faded-node-opacity", "--lpv-faded-edge-opacity", "--lpv-faded-cluster-opacity"];
+
+/**
+ * Canonical libpetri Petri-net diagram viewer.
+ *
+ * Single source of truth for DOT → SVG rendering + cluster overlay across
+ * all four surfaces:
+ *  - debug-ui (live debugger)
+ *  - dev-preview (Vite app)
+ *  - Javadoc taglet (Java doclet)
+ *  - Rustdoc embed (libpetri-docgen)
+ *  - TypeDoc / typescript doclet
+ *
+ * Build outputs:
+ *  - ESM: `dist/viewer/index.js` — consumed by Vite/Webpack/Node bundlers.
+ *  - IIFE: `dist/viewer/viewer.iife.js` — self-contained, exposes
+ *    `window.LibpetriViewer = { mount, ... }`. Used by the doc taglets
+ *    that ship pre-rendered HTML pages without a bundler.
+ *  - CSS: `dist/viewer/viewer.css` — canonical stylesheet (copied from
+ *    `src/viewer/resources/viewer.css`).
+ *
+ * Edits to viewer behaviour MUST happen here. The three resource directories
+ * under `java/`, `rust/`, and `typescript/src/doclet/` are **build outputs**
+ * populated by `scripts/build-viewer.sh` and must not be hand-edited.
+ *
+ * @module viewer
+ */
+
+/** Handle returned by {@link mount}. */
+interface ViewerHandle {
+    /** The rendered root `<svg>` element. */
+    readonly svg: SVGSVGElement;
+    /** The panzoom instance attached to the SVG. */
+    readonly panzoom: PanzoomInstance;
+    /** Map of cluster prefix → descriptor for the current SVG. */
+    readonly clusters: ReadonlyMap<string, ClusterDescriptor>;
+    /** Prefixes currently marked collapsed on this handle. */
+    readonly collapsedPrefixes: ReadonlySet<string>;
+    /** Currently active "show only <prefix>" filter, or null. */
+    readonly activeFilter: string | null;
+    /** Collapse a single cluster by prefix. No-op if unknown. */
+    collapse(prefix: string): void;
+    /** Expand a single cluster by prefix. No-op if unknown. */
+    expand(prefix: string): void;
+    /** Collapse every discovered cluster. */
+    collapseAll(): void;
+    /** Expand every collapsed cluster. */
+    expandAll(): void;
+    /** Apply the "show only <prefix>" filter; pass `null` to clear. */
+    filter(prefix: string | null): void;
+    /** Reset pan/zoom to the identity transform. */
+    resetZoom(): void;
+    /** Scale and translate so the full diagram fits the host viewport. */
+    fit(): void;
+    /** Reports whether `graphId` is inside a currently-collapsed cluster. */
+    isInsideCollapsedCluster(graphId: string): boolean;
+    /**
+     * Highlight a node and every DOM copy of the same logical place; walk
+     * junctions to surface real neighbors. Pass `null` to clear. C0-only.
+     */
+    highlight(nodeId: string | null): void;
+    /** The node id currently highlighted, or `null`. */
+    readonly highlightedNodeId: string | null;
+    /**
+     * Set the cluster-visibility state: which clusters render, and whether
+     * directed-reachable orphans render. C0-only.
+     */
+    setVisibility(state: VisibilityState): void;
+    /** Tear down: dispose panzoom and detach listeners. */
+    dispose(): void;
+}
+/** Options accepted by {@link mount}. */
+interface MountOptions {
+    /**
+     * Previous handle to dispose before mounting. Pass the handle returned
+     * by a prior `mount()` call so callers don't need to track it separately.
+     * Cluster collapse / filter state from `previousHandle` is preserved
+     * across the re-render so the user's intent survives a live re-draw.
+     */
+    readonly previousHandle?: ViewerHandle | null;
+    /** Per-call panzoom overrides; merged on top of {@link DEFAULT_PANZOOM_OPTS}. */
+    readonly panzoom?: PanzoomOptions;
+    /** Fired after a cluster's collapsed state changes via the handle API. */
+    readonly onClusterCollapse?: (prefix: string, collapsed: boolean) => void;
+    /** Fired after `filter()` runs, with the new filter prefix or null. */
+    readonly onClusterFilter?: (prefix: string | null) => void;
+    /** When true, append a legend sidebar + filter chip strip inside `container`. */
+    readonly chrome?: boolean;
+    /**
+     * Layout strategy. `'elk'` (default) runs the C0 pipeline — parse → fold
+     * → replicate → ELK → Graphviz `neato` pin mode — and tags replica
+     * nodes for the click-all-copies + ⇄ overlay. `'graphviz'` runs the
+     * plain Graphviz `dot` engine and skips replica tagging. The result is
+     * cached on the DOT hash; re-mounts on identical DOT skip the pipeline.
+     */
+    readonly layout?: 'elk' | 'graphviz';
+}
+/**
+ * Render a DOT source, mount the resulting SVG into `container`, wire pan/zoom,
+ * and surface cluster overlay controls.
+ *
+ * The container's existing children are removed before the new SVG is
+ * appended (the same teardown behaviour `renderDotToContainer` used to provide).
+ *
+ * Pass `dotSource === null` to adopt an SVG already present as a direct child
+ * of `container` (pre-rendered SVG path — e.g. the Java javadoc taglet emits
+ * `dot -Tsvg` at build time). In that mode the viewer never imports the
+ * runtime DOT renderer, which lets the static IIFE bundle drop `@viz-js/viz`
+ * entirely.
+ *
+ * NOTE: when shipping a pre-rendered SVG (`dotSource === null`), do NOT also
+ * pass `previousHandle` — the handle's `dispose()` runs before SVG detection
+ * and would orphan the host. The Java taglet mounts once per page so this is
+ * a non-issue in practice.
+ */
+declare function mount(dotSource: string | null, container: HTMLElement, opts?: MountOptions): Promise<ViewerHandle>;
+
+export { type ClusterDescriptor, DEFAULT_PANZOOM_OPTS, type MountOptions, type PanzoomInstance, type PanzoomOptions, VIEWER_CSS_VARIABLES, type ViewerHandle, colorForPrefix, discoverClusters, mount };