@arach/arc-viewer 0.4.4

package/dist/index.d.ts

@@ -0,0 +1,639 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, CSSProperties, ComponentType } from 'react';
+
+type ThemeId = 'default' | 'warm' | 'cool' | 'mono';
+interface ColorPalette {
+    violet: {
+        border: string;
+        bg: string;
+        icon: string;
+        stroke: string;
+    };
+    emerald: {
+        border: string;
+        bg: string;
+        icon: string;
+        stroke: string;
+    };
+    blue: {
+        border: string;
+        bg: string;
+        icon: string;
+        stroke: string;
+    };
+    amber: {
+        border: string;
+        bg: string;
+        icon: string;
+        stroke: string;
+    };
+    sky: {
+        border: string;
+        bg: string;
+        icon: string;
+        stroke: string;
+    };
+    zinc: {
+        border: string;
+        bg: string;
+        icon: string;
+        stroke: string;
+    };
+    rose: {
+        border: string;
+        bg: string;
+        icon: string;
+        stroke: string;
+    };
+    orange: {
+        border: string;
+        bg: string;
+        icon: string;
+        stroke: string;
+    };
+}
+interface ThemeBackground {
+    container: string;
+    grid: {
+        color: string;
+        opacity: number;
+        size: number;
+    };
+}
+interface Theme {
+    id: ThemeId;
+    name: string;
+    description: string;
+    light: {
+        palette: ColorPalette;
+        background: ThemeBackground;
+        text: {
+            primary: string;
+            secondary: string;
+            muted: string;
+        };
+    };
+    dark: {
+        palette: ColorPalette;
+        background: ThemeBackground;
+        text: {
+            primary: string;
+            secondary: string;
+            muted: string;
+        };
+    };
+}
+declare const THEMES: Record<ThemeId, Theme>;
+declare const DEFAULT_THEME: ThemeId;
+declare function getTheme(id: ThemeId): Theme;
+declare function getThemeList(): {
+    id: ThemeId;
+    name: string;
+    description: string;
+}[];
+
+type NodeSize = 'xs' | 's' | 'm' | 'l';
+type AnchorPosition = 'left' | 'right' | 'top' | 'bottom' | 'bottomLeft' | 'bottomRight' | 'topLeft' | 'topRight';
+type DiagramColor = 'violet' | 'emerald' | 'blue' | 'amber' | 'sky' | 'zinc' | 'rose' | 'orange';
+interface NodePosition {
+    x: number;
+    y: number;
+    size: NodeSize;
+}
+interface NodeData {
+    icon: string;
+    name: string;
+    subtitle?: string;
+    description?: string;
+    color: DiagramColor;
+}
+interface Connector {
+    from: string;
+    to: string;
+    fromAnchor: AnchorPosition;
+    toAnchor: AnchorPosition;
+    style: string;
+    curve?: 'natural' | 'step';
+}
+type LabelAlign = 'left' | 'right' | 'center';
+interface ConnectorStyle {
+    color: DiagramColor;
+    strokeWidth: number;
+    label?: string;
+    labelAlign?: LabelAlign;
+    dashed?: boolean;
+}
+interface DiagramLayout {
+    width: number;
+    height: number;
+}
+interface ArcDiagramData {
+    id?: string;
+    layout: DiagramLayout;
+    nodes: Record<string, NodePosition>;
+    nodeData: Record<string, NodeData>;
+    connectors: Connector[];
+    connectorStyles: Record<string, ConnectorStyle>;
+}
+interface HoverEffectsConfig {
+    /** Dim unrelated nodes/connectors. Default: true */
+    dim?: boolean;
+    /** 0–1 opacity for dimmed nodes. Connectors dim to ~56% of this. Default: 0.45 */
+    dimOpacity?: number;
+    /** Lift hovered node up 2px. Default: true */
+    lift?: boolean;
+    /** Colored glow shadow on hover. Default: true */
+    glow?: boolean;
+    /** Thicken connected edges. Default: true */
+    highlightEdges?: boolean;
+}
+type DiagramMode = 'dark' | 'light';
+
+interface ArcDiagramProps {
+    data: ArcDiagramData;
+    className?: string;
+    interactive?: boolean;
+    mode?: DiagramMode;
+    theme?: ThemeId;
+    /** Show the source toggle button. Default: true */
+    showArcToggle?: boolean;
+    /** Show the auto-layout button. Default: false */
+    showAutoLayout?: boolean;
+    /** Enable drag-to-reposition nodes. Default: false */
+    editable?: boolean;
+    /** URL of the Arc editor. When set with editable, shows an "Edit" button. */
+    editorUrl?: string;
+    /** Metadata to pass to the editor (viewport size, theme, mode). */
+    editorMeta?: {
+        viewport?: {
+            width: number;
+            height: number;
+        };
+        theme?: string;
+        mode?: string;
+    };
+    /** Control hover behavior. true = all effects (default), false = none, object = granular control */
+    hoverEffects?: boolean | HoverEffectsConfig;
+    /** Called when a node is hovered/clicked (nodeId) or released (null) */
+    onNodeHover?: (nodeId: string | null) => void;
+}
+declare function ArcDiagram({ data, className, interactive, mode, theme, showArcToggle, showAutoLayout, editable, editorUrl, editorMeta, hoverEffects, onNodeHover }: ArcDiagramProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Auto-layout engine for Arc diagrams
+ *
+ * Layered DAG layout (Sugiyama) with grid-wrapping:
+ * when the natural LR layout exceeds the target width,
+ * layers wrap into rows — LR within each row, TB between rows.
+ * This uses the full 2D canvas instead of a single axis.
+ */
+
+interface LayoutOptions {
+    /** Horizontal gap between columns */
+    columnGap?: number;
+    /** Vertical gap between nodes within a column */
+    nodeGap?: number;
+    /** Vertical gap between wrapped rows */
+    rowGap?: number;
+    /** Padding around the entire diagram */
+    padding?: number;
+}
+/**
+ * Auto-layout an ArcDiagramData.
+ *
+ * Uses LR flow within rows. When layers exceed the target width,
+ * wraps into multiple rows — combining LR and TB to maximize
+ * use of the available 2D space.
+ */
+declare function autoLayout(data: ArcDiagramData, options?: LayoutOptions): ArcDiagramData;
+/**
+ * Generate a diagram from minimal input — no positions or anchors needed.
+ */
+interface AutoDiagramInput {
+    nodeData: ArcDiagramData['nodeData'];
+    connectors: Array<Omit<Connector, 'fromAnchor' | 'toAnchor'> & {
+        fromAnchor?: AnchorPosition;
+        toAnchor?: AnchorPosition;
+    }>;
+    connectorStyles: ArcDiagramData['connectorStyles'];
+    layout?: LayoutOptions;
+}
+declare function createAutoLayout(input: AutoDiagramInput): ArcDiagramData;
+
+/**
+ * Sequence renderer presentation + extensibility contracts.
+ */
+
+interface SequenceLayoutMetrics {
+    width: number;
+    height: number;
+    paddingX: number;
+    paddingY: number;
+    headerHeight: number;
+    participantGap: number;
+    /** Center X for each participant id */
+    participantX: Record<string, number>;
+    rowTops: number[];
+    rowHeights: number[];
+}
+interface SequenceLaidOutMessage {
+    event: SequenceMessageEvent;
+    y: number;
+    fromX: number;
+    toX: number;
+    self: boolean;
+}
+interface SequenceLaidOutNote {
+    event: SequenceNoteEvent;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface SequenceLaidOutFragmentLane {
+    label?: string;
+    y: number;
+    height: number;
+    /** Event orders (inclusive) covered by this lane body */
+    startOrder: number;
+    endOrder: number;
+}
+interface SequenceLaidOutFragment {
+    id: string;
+    kind: string;
+    label?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    depth: number;
+    lanes: SequenceLaidOutFragmentLane[];
+}
+interface SequenceLayout {
+    metrics: SequenceLayoutMetrics;
+    messages: SequenceLaidOutMessage[];
+    notes: SequenceLaidOutNote[];
+    fragments: SequenceLaidOutFragment[];
+}
+interface SequenceThemeTokens {
+    background: string;
+    surface: string;
+    border: string;
+    text: string;
+    textSecondary: string;
+    textMuted: string;
+    lifeline: string;
+    messageSolid: string;
+    messageDashed: string;
+    messageLabel: string;
+    actorFill: string;
+    actorStroke: string;
+    actorText: string;
+    participantFill: string;
+    participantStroke: string;
+    participantText: string;
+    noteFill: string;
+    noteStroke: string;
+    noteText: string;
+    /** Cool/green family — local control plane */
+    localFill: string;
+    localStroke: string;
+    localText: string;
+    /** Warm/amber family — model inference */
+    modelFill: string;
+    modelStroke: string;
+    modelText: string;
+    fragmentFill: string;
+    fragmentStroke: string;
+    fragmentLabelBg: string;
+    fragmentLabelText: string;
+    fragmentDivider: string;
+    highlight: string;
+    dimOpacity: number;
+}
+interface SequencePartContext {
+    /** Per-renderer id namespace for SVG markers and accessibility ids. */
+    idPrefix: string;
+    mode: 'light' | 'dark';
+    themeId: ThemeId;
+    tokens: SequenceThemeTokens;
+    layout: SequenceLayout;
+    document: ArcSequenceDocument;
+    interactive: boolean;
+    highlightedParticipantId: string | null;
+    dimmed: boolean;
+    noteAccent: (event: SequenceNoteEvent) => 'local' | 'model' | 'default';
+}
+interface ActorHeaderProps {
+    participant: SequenceParticipant;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    context: SequencePartContext;
+    emphasized: boolean;
+    onPointerEnter?: () => void;
+    onPointerLeave?: () => void;
+    onFocus?: () => void;
+    onBlur?: () => void;
+    onClick?: () => void;
+}
+interface ParticipantHeaderProps {
+    participant: SequenceParticipant;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    context: SequencePartContext;
+    emphasized: boolean;
+    onPointerEnter?: () => void;
+    onPointerLeave?: () => void;
+    onFocus?: () => void;
+    onBlur?: () => void;
+    onClick?: () => void;
+}
+interface LifelineProps {
+    participant: SequenceParticipant;
+    x: number;
+    y1: number;
+    y2: number;
+    context: SequencePartContext;
+    emphasized: boolean;
+}
+interface MessagePartProps {
+    laidOut: SequenceLaidOutMessage;
+    context: SequencePartContext;
+    emphasized: boolean;
+    onPointerEnter?: () => void;
+    onPointerLeave?: () => void;
+    onActivate?: () => void;
+}
+interface NotePartProps {
+    laidOut: SequenceLaidOutNote;
+    context: SequencePartContext;
+    emphasized: boolean;
+}
+interface FragmentPartProps {
+    laidOut: SequenceLaidOutFragment;
+    context: SequencePartContext;
+}
+/** Pluggable part components for sequence rendering */
+interface SequenceRendererParts {
+    ActorHeader?: (props: ActorHeaderProps) => ReactNode;
+    ParticipantHeader?: (props: ParticipantHeaderProps) => ReactNode;
+    Lifeline?: (props: LifelineProps) => ReactNode;
+    Message?: (props: MessagePartProps) => ReactNode;
+    Note?: (props: NotePartProps) => ReactNode;
+    Fragment?: (props: FragmentPartProps) => ReactNode;
+}
+/** Player / interaction hooks — never required for static export fidelity */
+interface SequencePlayerInteractions {
+    onParticipantHover?: (participantId: string | null) => void;
+    onParticipantFocus?: (participantId: string | null) => void;
+    onParticipantActivate?: (participantId: string) => void;
+    onMessageHover?: (messageId: string | null) => void;
+    onMessageActivate?: (messageId: string) => void;
+    /** Controlled highlight; when omitted, internal hover/focus state is used */
+    highlightedParticipantId?: string | null;
+    /** Controlled message emphasis used by timeline players. */
+    activeMessageId?: string | null;
+    /** Dim unrelated lifelines/messages when a participant is highlighted. Default true when interactive */
+    dimUnrelated?: boolean;
+}
+interface SequencePresentationOptions {
+    /** Target width; height grows with content. Default 960 */
+    width?: number;
+    /** Visual scale applied after layout. Default 1. */
+    scale?: number;
+    /** Max message label width before wrap. Default 160 */
+    maxLabelWidth?: number;
+    /** Override theme tokens partially */
+    tokens?: Partial<SequenceThemeTokens>;
+    /** Replace individual part renderers */
+    parts?: SequenceRendererParts;
+    /** Map authored note semantics to a presentation role. Defaults to neutral. */
+    noteAccent?: (event: SequenceNoteEvent) => 'local' | 'model' | 'default';
+    /** Interaction hooks */
+    interactions?: SequencePlayerInteractions;
+    /** Inline style on root */
+    style?: CSSProperties;
+}
+
+/**
+ * Native Mermaid semantic document model.
+ *
+ * Sequence diagrams are first-class here — not projected through ArcDiagramData.
+ */
+type MermaidFamily = 'flowchart' | 'sequence' | 'state';
+type MermaidDiagnosticSeverity = 'error' | 'warning' | 'unsupported';
+interface MermaidSourceRange {
+    /** 1-based line number in the normalized source */
+    startLine: number;
+    endLine: number;
+    startColumn?: number;
+    endColumn?: number;
+}
+interface MermaidDiagnostic {
+    severity: MermaidDiagnosticSeverity;
+    code: string;
+    message: string;
+    /** Capability name for unsupported features (de-duplicated in consumers) */
+    capability?: string;
+    range?: MermaidSourceRange;
+}
+interface ArcMermaidDocumentBase {
+    family: MermaidFamily;
+    /** Original declaration token, e.g. sequenceDiagram */
+    declaration: string;
+}
+type SequenceParticipantKind = 'actor' | 'participant';
+interface SequenceParticipant {
+    id: string;
+    label: string;
+    kind: SequenceParticipantKind;
+    /** Source order, 0-based */
+    order: number;
+    range?: MermaidSourceRange;
+}
+type SequenceMessageLine = 'solid' | 'dashed';
+type SequenceArrowHead = 'filled' | 'open';
+interface SequenceMessageEvent {
+    type: 'message';
+    id: string;
+    from: string;
+    to: string;
+    /** Structured label lines (from <br> splits) */
+    label: string[];
+    line: SequenceMessageLine;
+    arrow: SequenceArrowHead;
+    /** Activation markers present on the arrow (+/-) are recorded but not yet rendered */
+    activateTarget?: boolean;
+    deactivateTarget?: boolean;
+    order: number;
+    range?: MermaidSourceRange;
+}
+type SequenceNotePlacement = 'left' | 'right' | 'over';
+interface SequenceNoteEvent {
+    type: 'note';
+    id: string;
+    placement: SequenceNotePlacement;
+    /** One or more participant ids; range notes list [from, to] in source order */
+    participants: string[];
+    /** Structured text lines */
+    text: string[];
+    order: number;
+    range?: MermaidSourceRange;
+}
+/** Supported fragment kinds for the first native slice */
+type SequenceFragmentKind = 'alt' | 'else' | 'opt' | 'loop' | 'par' | 'critical' | 'break' | 'rect';
+interface SequenceFragmentStartEvent {
+    type: 'fragmentStart';
+    id: string;
+    kind: SequenceFragmentKind;
+    /** Lane / branch label after the keyword */
+    label?: string;
+    depth: number;
+    order: number;
+    range?: MermaidSourceRange;
+}
+interface SequenceFragmentElseEvent {
+    type: 'fragmentElse';
+    id: string;
+    /** Matches the opening fragment id */
+    fragmentId: string;
+    label?: string;
+    depth: number;
+    order: number;
+    range?: MermaidSourceRange;
+}
+interface SequenceFragmentEndEvent {
+    type: 'fragmentEnd';
+    id: string;
+    fragmentId: string;
+    depth: number;
+    order: number;
+    range?: MermaidSourceRange;
+}
+type SequenceEvent = SequenceMessageEvent | SequenceNoteEvent | SequenceFragmentStartEvent | SequenceFragmentElseEvent | SequenceFragmentEndEvent;
+interface ArcSequenceDocument extends ArcMermaidDocumentBase {
+    family: 'sequence';
+    participants: SequenceParticipant[];
+    events: SequenceEvent[];
+}
+interface ArcFlowchartDocument extends ArcMermaidDocumentBase {
+    family: 'flowchart';
+    /** Raw declaration body retained for future native rendering */
+    raw: string;
+}
+interface ArcStateDocument extends ArcMermaidDocumentBase {
+    family: 'state';
+    raw: string;
+}
+type ArcMermaidDocument = ArcFlowchartDocument | ArcSequenceDocument | ArcStateDocument;
+interface ArcMermaidParseResult {
+    document: ArcMermaidDocument | null;
+    diagnostics: MermaidDiagnostic[];
+    /** Normalized source (LF line endings) retained for editing */
+    source: string;
+}
+interface ArcMermaidProps {
+    source?: string;
+    document?: ArcMermaidDocument;
+    mode?: 'light' | 'dark';
+    theme?: ThemeId;
+    interactive?: boolean;
+    className?: string;
+    title?: string;
+    description?: string;
+    /** Sequence-only presentation overrides */
+    sequence?: SequencePresentationOptions;
+}
+
+/**
+ * parseMermaid — native Mermaid → typed ArcMermaidDocument
+ */
+
+/**
+ * Parse Mermaid source into a typed native document.
+ * Does not project into ArcDiagramData.
+ */
+declare function parseMermaid(source: string): ArcMermaidParseResult;
+
+declare function ArcMermaid({ source, document: documentProp, mode, theme, interactive, className, title, description, sequence, }: ArcMermaidProps): react_jsx_runtime.JSX.Element;
+
+interface ArcMermaidPlayerProps extends ArcMermaidProps {
+    defaultZoom?: number | 'fit';
+    minZoom?: number;
+    maxZoom?: number;
+    zoomStep?: number;
+    showControls?: boolean;
+    showPlayback?: boolean;
+    autoplayMs?: number;
+    onStepChange?: (step: number, eventId: string | null) => void;
+}
+declare function ArcMermaidPlayer({ source, document, mode, theme, className, title, description, sequence, defaultZoom, minZoom, maxZoom, zoomStep, showControls, showPlayback, autoplayMs, onStepChange, }: ArcMermaidPlayerProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Family → renderer registry.
+ * Adding a Mermaid family registers here; UI code must not grow type conditionals.
+ */
+
+interface MermaidRendererProps {
+    document: ArcMermaidDocument;
+    mode?: 'light' | 'dark';
+    theme?: ThemeId;
+    interactive?: boolean;
+    className?: string;
+    title?: string;
+    description?: string;
+    sequence?: SequencePresentationOptions;
+}
+type MermaidFamilyRenderer = ComponentType<MermaidRendererProps>;
+declare function registerMermaidRenderer(family: MermaidFamily, renderer: MermaidFamilyRenderer): void;
+declare function getMermaidRenderer(family: MermaidFamily): MermaidFamilyRenderer | undefined;
+declare function listMermaidRenderers(): MermaidFamily[];
+
+interface SequenceRendererProps {
+    document: ArcSequenceDocument;
+    mode?: 'light' | 'dark';
+    theme?: ThemeId;
+    interactive?: boolean;
+    className?: string;
+    title?: string;
+    description?: string;
+    presentation?: SequencePresentationOptions;
+}
+declare function SequenceRenderer({ document, mode, theme, interactive, className, title, description, presentation, }: SequenceRendererProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Deterministic sequence layout — pure functions, no DOM measurement.
+ * Long labels wrap within maxLabelWidth and grow their row height.
+ */
+
+interface SequenceLayoutOptions {
+    width?: number;
+    maxLabelWidth?: number;
+}
+declare function layoutSequence(document: ArcSequenceDocument, options?: SequenceLayoutOptions): SequenceLayout;
+
+/**
+ * Native sequenceDiagram parser → ArcSequenceDocument
+ */
+
+interface ParseSequenceResult {
+    document: ArcSequenceDocument;
+    diagnostics: MermaidDiagnostic[];
+}
+/**
+ * Parse a sequenceDiagram body (including the declaration line).
+ * `baseLine` is the 1-based line number of the declaration in the full source.
+ */
+declare function parseSequenceSource(source: string, baseLine?: number): ParseSequenceResult;
+
+declare function getSequenceThemeTokens(mode: 'light' | 'dark', themeId?: ThemeId): SequenceThemeTokens;
+/** Classify note text for cool (local) vs warm (model) accent */
+declare function classifyNoteAccent(text: string[]): 'local' | 'model' | 'default';
+
+declare const defaultSequenceParts: Required<SequenceRendererParts>;
+
+export { type ActorHeaderProps, type AnchorPosition, ArcDiagram, type ArcDiagramData, type ArcDiagramProps, type ArcFlowchartDocument, ArcMermaid, type ArcMermaidDocument, type ArcMermaidParseResult, ArcMermaidPlayer, type ArcMermaidPlayerProps, type ArcMermaidProps, type ArcSequenceDocument, type ArcStateDocument, type AutoDiagramInput, type ColorPalette, type Connector, type ConnectorStyle, DEFAULT_THEME, type DiagramColor, type DiagramLayout, type DiagramMode, type FragmentPartProps, type HoverEffectsConfig, type LabelAlign, type LayoutOptions, type LifelineProps, type MermaidDiagnostic, type MermaidDiagnosticSeverity, type MermaidFamily, type MermaidFamilyRenderer, type MermaidRendererProps, type MermaidSourceRange, type MessagePartProps, type NodeData, type NodePosition, type NodeSize, type NotePartProps, type ParticipantHeaderProps, type SequenceArrowHead, type SequenceEvent, type SequenceFragmentElseEvent, type SequenceFragmentEndEvent, type SequenceFragmentKind, type SequenceFragmentStartEvent, type SequenceLayout, type SequenceMessageEvent, type SequenceMessageLine, type SequenceNoteEvent, type SequenceNotePlacement, type SequenceParticipant, type SequenceParticipantKind, type SequencePlayerInteractions, type SequencePresentationOptions, SequenceRenderer, type SequenceRendererParts, type SequenceRendererProps, type SequenceThemeTokens, THEMES, type Theme, type ThemeBackground, type ThemeId, autoLayout, classifyNoteAccent, createAutoLayout, ArcDiagram as default, defaultSequenceParts, getMermaidRenderer, getSequenceThemeTokens, getTheme, getThemeList, layoutSequence, listMermaidRenderers, parseMermaid, parseSequenceSource, registerMermaidRenderer };