@xenosystem/blocks 0.22.0 → 0.23.0

package/dist/corpus/index.d.ts

@@ -0,0 +1,449 @@
+import { PanelModule, PanelManifest, BlockDeclaration } from '@xenosystem/block-sdk';
+import { X as XenoGraphScaleState } from '../scale-XiQwxiFA.js';
+import { ReactNode } from 'react';
+
+/**
+ * The wire contract of `xeno.corpus.shape` — what a host hands the panel and what it gets back.
+ *
+ * The shapes are the subset of XENO Corpus's `/api/v1/model` that the canvas draws (corpus-model.mjs,
+ * mirrored in xeno-corpus `app/src/types.ts`). The panel computes NO verdict: every `state` arrives
+ * from the host, and the panel only decides where to draw it and how loudly.
+ *
+ * @module
+ */
+/** A tenet's verdict as the host computed it. `unobserved` and `never-run` are both UNKNOWN, never held. */
+type XenoCorpusState = 'held' | 'lapsed' | 'unobserved' | 'never-run' | 'attested' | (string & {});
+/** What a card is. */
+type XenoCorpusNodeKind = 'tenet' | 'ref' | 'rule' | 'doc' | 'proposal' | 'missing' | 'uncovered';
+/** One cell of a tenet's recent-verdict strip, oldest first. */
+interface XenoCorpusStripCell {
+    at: string;
+    state: string;
+    observed?: string | null;
+}
+/** A card. `key` is unique across the whole model; `lane` names the lane it sits in. */
+interface XenoCorpusNode {
+    key: string;
+    lane: string;
+    kind: XenoCorpusNodeKind;
+    label: string;
+    state: XenoCorpusState;
+    sub?: string;
+    expect?: string;
+    observed?: string | null;
+    attested?: boolean;
+    binding?: boolean;
+    cadence?: string | null;
+    strip?: XenoCorpusStripCell[];
+}
+/** A relation between two cards. */
+interface XenoCorpusEdge {
+    from: string;
+    to: string;
+    type: 'ref' | 'dep' | 'breach' | 'pointer' | 'super';
+    label: string;
+}
+/** A lane: one corpus in the estate (org, ancestor, product), an orphan, or the unmanaged repositories. */
+interface XenoCorpusLane {
+    id: string;
+    name: string;
+    role: 'org' | 'ancestor' | 'product' | 'orphan' | 'uncovered';
+    root?: string;
+    flag?: string | null;
+    inherits?: number;
+    counts?: {
+        tenets?: number;
+        lapsed?: number;
+        unknown?: number;
+        attested?: number;
+        held?: number;
+    };
+    uncovered?: {
+        total?: number;
+    };
+}
+/** The whole picture. A higher `rev` is a newer picture; the panel never edits it. */
+interface XenoCorpusModel {
+    rev?: number;
+    lanes: XenoCorpusLane[];
+    nodes: XenoCorpusNode[];
+    edges: XenoCorpusEdge[];
+}
+/** The question the canvas answers. */
+type XenoCorpusLens = 'all' | 'lapsed' | 'unchecked';
+/**
+ * Emphasis by state, from a host's filter rail. These DIM and never hide: emphasis changes how loudly a
+ * card speaks inside the whole picture; a lens (a question) is what hides non-answers.
+ */
+interface XenoCorpusEmphasis {
+    lapsed?: boolean;
+    held?: boolean;
+    unobserved?: boolean;
+    rule?: boolean;
+    none?: boolean;
+}
+/** What the panel emits on `intent`. Requests only — the host decides. */
+type XenoCorpusShapeIntent = 
+/** Open this card's detail (an inspector, a document). Double-click or Enter. */
+{
+    kind: 'open';
+    key: string;
+};
+/** Is this value a model the panel can draw? A mis-wire is a normal event, so this checks shape, never trusts a cast. */
+declare function isCorpusModel(v: unknown): v is XenoCorpusModel;
+
+/**
+ * What the Shape canvas shows and where — pure, framework-free, testable in Node.
+ *
+ * Moved from xeno-corpus `app/src/views/shapeLogic.ts` and the layout in `Shape.tsx`, unchanged in
+ * behaviour. The design record is xeno-corpus `docs/design/SHAPE-CANVAS.md`; the three ideas, each from
+ * what users of graph tools ask for:
+ *   - LENSES: open on a question ("what is false right now?"), not on the whole graph.
+ *   - FOCUS DEPTH: a local view N links around the selection, both directions.
+ *   - SEMANTIC ZOOM: below a zoom threshold a card shows its state and one label large enough to read.
+ *
+ * @module
+ */
+
+/** Card size and lane geometry in WORLD units. The layout comes from the data: nothing is stored, nothing drifts. */
+declare const NODE_W = 210;
+declare const NODE_H = 74;
+/** The questions. `empty` is what the canvas says when nothing answers: an empty canvas is otherwise indistinguishable from a broken one. */
+declare const LENSES: readonly {
+    id: XenoCorpusLens;
+    label: string;
+    question: string;
+    empty: string;
+}[];
+declare const isLens: (v: unknown) => v is XenoCorpusLens;
+/** Focus depths offered. Capped at 3: past three links a claim map is the whole corpus again. */
+declare const DEPTHS: readonly [0, 1, 2, 3];
+declare const isDepth: (v: unknown) => v is number;
+/** Does a card answer the lens's question? */
+declare function inLens(n: Pick<XenoCorpusNode, 'kind' | 'state'>, lens: XenoCorpusLens): boolean;
+/** Keys within `depth` links of `start`, ignoring direction. depth 0 = no focus (null). */
+declare function neighbourhood(edges: readonly Pick<XenoCorpusEdge, 'from' | 'to'>[], start: string | null, depth: number): Set<string> | null;
+/**
+ * The visible set: lens AND focus. The selected card always stays visible — hiding what the person just
+ * clicked is the one thing a filter must never do. When focus is on it outranks the lens.
+ */
+declare function visibleKeys(nodes: readonly Pick<XenoCorpusNode, 'key' | 'kind' | 'state'>[], edges: readonly Pick<XenoCorpusEdge, 'from' | 'to'>[], lens: XenoCorpusLens, selected: string | null, depth: number): Set<string>;
+/** Below this zoom a card switches to its compact, readable form. */
+declare const COMPACT_BELOW = 0.5;
+/** Compact label size in WORLD units so it reads at ~12 px on screen, capped (44) so one line fits a card. */
+declare const compactFont: (zoom: number) => number;
+/** A placed card. */
+interface Placed extends XenoCorpusNode {
+    x: number;
+    y: number;
+}
+/** A placed lane. */
+interface LaneBox {
+    lane: XenoCorpusLane;
+    x: number;
+    w: number;
+    h: number;
+}
+/**
+ * Lanes left to right; an org lane is two columns wide (claims, then doctrine, documents and gaps).
+ * Pure: the same model always lays out the same way, so nothing moves between visits.
+ */
+declare function layout(lanes: readonly XenoCorpusLane[], nodes: readonly XenoCorpusNode[]): {
+    boxes: LaneBox[];
+    placed: Placed[];
+    width: number;
+    height: number;
+};
+/** Which emphasis switch governs a card. */
+declare function emphasisKey(n: Pick<XenoCorpusNode, 'kind' | 'state'>): keyof XenoCorpusEmphasis;
+/** A state chip. D181: unknown is a hollow ring and attested the monochrome wash — never mistakable for held. */
+interface Chip {
+    label: string;
+    bg: string;
+    ink: string;
+    ring: string;
+}
+declare function chipFor(state: string, opts?: {
+    attested?: boolean;
+    binding?: boolean;
+}): Chip;
+/** The chip a CARD wears: a tenet shows its verdict; an unmanaged repository has no check. */
+declare const cardChip: (n: XenoCorpusNode) => Chip;
+/** One verdict cell's fill. Unknown is hollow; nothing unknown is ever filled green. */
+declare function cellFill(state: string): {
+    bg: string;
+    ring: string;
+};
+/** The small caption above a card's title. */
+declare function kindLabel(n: XenoCorpusNode): string;
+/** The line under a card's title. A tenet says what it expects and what it got, or that it is unknown. */
+declare function subLine(n: XenoCorpusNode): string;
+/** A lane's caption ("Org corpus") and its sub-line. */
+declare function laneCaption(lane: XenoCorpusLane): {
+    role: string;
+    sub: string;
+};
+/** Edge styles: colour, dash, width, legend label. */
+declare const EDGE_STYLE: Readonly<Record<XenoCorpusEdge['type'], readonly [string, string, number, string]>>;
+
+/**
+ * The Shape controller — framework-free, testable in Node.
+ *
+ * Owns the VIEW state (camera, selection, question, focus depth, emphasis) and nothing else. The model
+ * is the host's: the panel draws it and emits two things — `selection` (what the person picked) and
+ * `intent` (`open` a card). It never computes a verdict and never writes the corpus.
+ *
+ * Camera math is the node graph's (`XenoGraphScale`, `zoomAboutCursor`, `fitToBounds`): one converter
+ * between screen and world for every canvas in the package.
+ *
+ * @module
+ */
+
+/** Zoom limits. 20% is far enough to see a large estate; at 200% a card's strip is legible. */
+declare const SHAPE_ZOOM: {
+    readonly min: 0.2;
+    readonly max: 2;
+};
+/** The host seam. */
+interface ShapeHostBridge {
+    emit(portId: string, value: unknown): void;
+}
+/** Everything the view reads. */
+interface ShapeState {
+    model: XenoCorpusModel | null;
+    boxes: LaneBox[];
+    placed: Placed[];
+    width: number;
+    height: number;
+    /** Cards that answer the question (and the focus). Always contains the selection. */
+    visible: ReadonlySet<string>;
+    shown: Placed[];
+    selected: string | null;
+    lens: XenoCorpusLens;
+    depth: number;
+    emphasis: Required<XenoCorpusEmphasis>;
+    camera: XenoGraphScaleState;
+    size: {
+        w: number;
+        h: number;
+    };
+    /** Below `COMPACT_BELOW` cards switch to their compact, readable form. */
+    compact: boolean;
+    /** The next camera change should animate (a fit, a focus); a wheel or a drag never does. */
+    animate: boolean;
+    edgeLabels: boolean;
+    /** The plain-language answer when the question has no answer; null otherwise. */
+    emptyAnswer: string | null;
+    /** Focus is on but nothing is selected: the canvas says what to do. */
+    focusHint: boolean;
+}
+/** Construction options. */
+interface ShapeControllerOptions {
+    host: ShapeHostBridge;
+    lens?: XenoCorpusLens;
+    depth?: number;
+}
+declare class ShapeController {
+    private host;
+    private listeners;
+    private s;
+    private fitted;
+    constructor(options: ShapeControllerOptions);
+    /** Bound, so `useSyncExternalStore(controller.subscribe, controller.getState)` works as written. */
+    getState: () => Readonly<ShapeState>;
+    subscribe: (fn: () => void) => (() => void);
+    private set;
+    private derive;
+    /** A new picture. Anything that is not a model is ignored: a mis-wire must not blank the canvas. */
+    setModel(value: unknown): void;
+    /** Selection driven from outside (an inspector, a search). Does not echo back on `selection`. */
+    setSelection(value: unknown): void;
+    /** Emphasis from a host's filter rail. Unknown keys are ignored; missing keys stay on. */
+    setEmphasis(value: unknown): void;
+    select(key: string | null): void;
+    open(key: string): void;
+    setLens(lens: unknown): void;
+    setDepth(depth: unknown): void;
+    toggleEdgeLabels(): void;
+    /** Arrow keys move the selection spatially: nearest card in that direction, off-axis distance weighed double. */
+    moveSelection(dir: 'left' | 'right' | 'up' | 'down'): void;
+    resize(w: number, h: number): void;
+    private scale;
+    get viewport(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    private camera;
+    /** Zoom about a screen point. Never animated: it follows the wheel. A non-positive or non-finite factor is a no-op (zoomAboutCursor). */
+    zoomAt(px: number, py: number, factor: number): void;
+    zoomBy(factor: number): void;
+    /** Pan by a screen-pixel delta. */
+    pan(dxPx: number, dyPx: number): void;
+    /** Centre the camera on a world point (the minimap). */
+    centreOn(wx: number, wy: number): void;
+    /** Fit everything. */
+    fit(animate?: boolean): void;
+    /** Fit what is SHOWN: a question or focus that leaves its answer off-screen is no answer. */
+    fitShown(animate?: boolean): void;
+    /** `F`: fit what answers when narrowed, everything otherwise. */
+    fitNow(): void;
+    private narrowed;
+    private refit;
+    private afterSelect;
+    /** The question and the depth are the viewer's: remembered so they do not reset on every open. */
+    serialize(): {
+        lens: XenoCorpusLens;
+        depth: number;
+        edgeLabels: boolean;
+    };
+    deserialize(state: unknown): void;
+    dispose(): void;
+}
+
+/**
+ * The `PanelModule` — what a host registers and mounts.
+ *
+ * @module
+ */
+
+/** Everything a renderer needs: the controller plus the resolved config. */
+interface CorpusShapeRenderContext {
+    controller: ShapeController;
+    config: {
+        minimap: boolean;
+        legend: boolean;
+    };
+}
+/** Options for {@link createCorpusShapePanel}. */
+interface CreateCorpusShapePanelOptions {
+    /** Override the view. Rarely needed. */
+    render?: (root: HTMLElement, context: CorpusShapeRenderContext) => () => void;
+}
+/**
+ * Build the Corpus Shape panel module.
+ *
+ * @param options - An optional renderer override.
+ * @returns The module.
+ */
+declare function createCorpusShapePanel(options?: CreateCorpusShapePanelOptions): PanelModule;
+/** The default Corpus Shape panel module. Register THIS. */
+declare const corpusShapePanel: PanelModule;
+
+/**
+ * The `xeno.corpus.shape` manifest.
+ *
+ * `storage.local` and nothing else. The canvas draws a picture it is handed; it reads no file, calls no
+ * server and runs no check. Whatever can run a check (a pulse) belongs to the host.
+ *
+ * @module
+ */
+
+/** The canonical manifest id. */
+declare const CORPUS_SHAPE_PANEL_ID = "xeno.corpus.shape";
+/** The `xeno.corpus.shape` manifest. */
+declare const corpusShapeManifest: PanelManifest;
+
+declare const SURFACE_TOKENS: Readonly<Record<string, string>>;
+
+/**
+ * The Corpus Shape panel AS A DECLARATION — the chrome is data (the question, the focus depth, the
+ * zoom and fit controls, the empty state, the status line) and the SURFACE is one runtime unit
+ * (`corpus/ShapeSurface`) bound to the controller: lanes, cards, relations, the minimap and legend,
+ * the empty-answer sentence. `CorpusShapePanelView` is the code view of the same model; the
+ * equivalence suite holds the two byte-identical.
+ *
+ * Presentation contract: input `view` (a {@link CorpusShapeViewModel}), output `ui` (a
+ * {@link CorpusShapeUiIntent}) applied by the runtime to the controller's own methods.
+ *
+ * @module
+ */
+
+/** The half of a renderer's config the view reads. */
+interface CorpusShapeViewOptions {
+    minimap?: boolean;
+    legend?: boolean;
+}
+interface CorpusShapeViewModel {
+    /** No model has arrived. */
+    empty: boolean;
+    /** A model is here: draw the surface. */
+    drawn: boolean;
+    lens: string;
+    lenses: {
+        value: string;
+        label: string;
+        title: string;
+    }[];
+    depth: string;
+    depths: {
+        value: string;
+        label: string;
+        title: string;
+    }[];
+    zoomLabel: string;
+    countLabel: string;
+}
+type CorpusShapeUiIntent = {
+    kind: 'lens';
+    lens: string;
+} | {
+    kind: 'depth';
+    depth: string;
+} | {
+    kind: 'zoomIn';
+} | {
+    kind: 'zoomOut';
+} | {
+    kind: 'fit';
+};
+/** Derive the view model from the live controller — the runtime calls this on every draw. */
+declare function corpusShapeViewState(c: ShapeController, _options?: CorpusShapeViewOptions): CorpusShapeViewModel;
+/** Apply a `ui` intent to the controller — the runtime's half of the contract. */
+declare function applyCorpusShapeUi(c: ShapeController, intent: CorpusShapeUiIntent): void;
+/**
+ * The presentation manifest: the block's REAL manifest (a delivered block is mounted from THIS, so it
+ * must be complete) with the declaration's own two ports, and no capability claim: a declaration has no code.
+ */
+declare const corpusShapeViewManifest: PanelManifest;
+declare const BEHAVIOURS: {
+    'corpus/shapePanelView': (inputs: Record<string, unknown>) => CorpusShapeViewModel;
+};
+/** The runtime-bound unit: the drawn canvas. */
+declare const CORPUS_SHAPE_RUNTIME_UNITS: readonly ["corpus/ShapeSurface"];
+declare const CORPUS_SHAPE_DECLARATION: BlockDeclaration;
+
+/**
+ * The Corpus Shape view — the CODE VIEW of `CORPUS_SHAPE_DECLARATION`, drawing the same
+ * {@link CorpusShapeViewModel} byte-identical (the equivalence suite holds the two together). The one
+ * runtime-bound unit is the SURFACE (`corpus/ShapeSurface`); the chrome intents go through
+ * `applyCorpusShapeUi`.
+ *
+ * Composes `@xenosystem/components/chrome`. **The host must call `ensurePanelPrimitivesInjected()` from
+ * `@xenosystem/components/chrome`** or this renders unstyled with no error.
+ *
+ * Monochrome per `DESIGN_SYSTEM.md`; colour only for status (held, lapsed, a gap). Every status mark is a
+ * rounded square — no circles.
+ *
+ * @module
+ */
+
+/** Props for {@link CorpusShapePanelView}. */
+interface CorpusShapePanelViewProps extends CorpusShapeViewOptions {
+    controller: ShapeController;
+}
+/** The Corpus Shape panel view. */
+declare function CorpusShapePanelView({ controller, ...options }: CorpusShapePanelViewProps): ReactNode;
+/** The runtime units, bound to a controller — what a declaration renderer registers. */
+declare function corpusShapeRuntimeComponents(controller: ShapeController, options?: CorpusShapeViewOptions): Record<(typeof CORPUS_SHAPE_RUNTIME_UNITS)[number], React.ComponentType<any>>;
+/**
+ * The surface — `corpus/ShapeSurface`, bound to the controller: lanes, relation lines, cards (full or
+ * compact by zoom), the selected card's relation labels, the empty-answer sentence, the legend and the
+ * minimap. Drag pans, the wheel zooms about the cursor, arrows move the selection, Enter opens, F fits.
+ */
+declare function CorpusShapeSurface({ controller, minimap, legend }: {
+    controller: ShapeController;
+} & CorpusShapeViewOptions): ReactNode;
+
+export { COMPACT_BELOW, BEHAVIOURS as CORPUS_SHAPE_BEHAVIOURS, CORPUS_SHAPE_DECLARATION, CORPUS_SHAPE_PANEL_ID, CORPUS_SHAPE_RUNTIME_UNITS, type Chip, CorpusShapePanelView, type CorpusShapePanelViewProps, type CorpusShapeRenderContext, CorpusShapeSurface, type CorpusShapeUiIntent, type CorpusShapeViewModel, type CorpusShapeViewOptions, type CreateCorpusShapePanelOptions, DEPTHS, EDGE_STYLE, LENSES, type LaneBox, NODE_H, NODE_W, type Placed, SHAPE_ZOOM, SURFACE_TOKENS, ShapeController, type ShapeControllerOptions, type ShapeHostBridge, type ShapeState, type XenoCorpusEdge, type XenoCorpusEmphasis, type XenoCorpusLane, type XenoCorpusLens, type XenoCorpusModel, type XenoCorpusNode, type XenoCorpusNodeKind, type XenoCorpusShapeIntent, type XenoCorpusState, type XenoCorpusStripCell, applyCorpusShapeUi, cardChip, cellFill, chipFor, compactFont, corpusShapeManifest, corpusShapePanel, corpusShapeRuntimeComponents, corpusShapeViewManifest, corpusShapeViewState, createCorpusShapePanel, emphasisKey, inLens, isCorpusModel, isDepth, isLens, kindLabel, laneCaption, layout, neighbourhood, subLine, visibleKeys };