@cjlapao/ui-kit-vue 0.2.0 → 0.2.3

package/dist/types/common/connectionFlow/tones.d.ts

@@ -0,0 +1,79 @@
+import { type SurfaceVariant, type TrueColor } from "../theme/Theme";
+import { type LaidOutConnector } from "./types";
+/**
+ * Tailwind class strings for a node card, generated from `TRUE_COLORS` so a
+ * tone can never be missing. The hand-written table these replace had drifted
+ * three ways: `pink` was present but is not a `TrueColor`, `neutral` was
+ * absent and only worked by falling through to a separate constant, and
+ * `slate` was remapped to `neutral` by a 21-branch switch in which every other
+ * branch returned its own input.
+ */
+export interface ConnectionFlowToneClasses {
+    fill: string;
+    border: string;
+    heading: string;
+    body: string;
+    /** A brighter fill for the pulsing "in progress" overlay. */
+    pulse: string;
+    /**
+     * Stroke for the edge line. A class rather than a value: an SVG `stroke`
+     * attribute cannot carry a `dark:` variant, and a single shade that reads
+     * as a quiet line on white glares on near-black.
+     */
+    line: string;
+    /** Fill for a terminal's core dot and for the dots travelling the line. */
+    dot: string;
+    /** Fill for the card's silhouette path — the SVG twin of `fill`. */
+    shapeFill: string;
+    /** Stroke for that silhouette — the SVG twin of `border`. */
+    shapeStroke: string;
+    /** Stroke for the silhouette of the selected card. */
+    shapeStrokeSelected: string;
+}
+export declare const CONNECTION_FLOW_TONE_CLASSES: Record<TrueColor, ConnectionFlowToneClasses>;
+export declare const getToneClasses: (tone: TrueColor | undefined) => ConnectionFlowToneClasses;
+/**
+ * How one terminal is painted.
+ *
+ * Only the core dot: the bulge around it is part of the node's own outline
+ * path (`LaidOutNode.outline`), because a terminal is the card bulging rather
+ * than a marker laid on top of it — no chord across it, and the same fill
+ * inside. An earlier version drew a full ring here, which read as a separate
+ * disc stuck to the side of the card.
+ *
+ * The colour is a Tailwind class, not a value: an SVG `fill` attribute cannot
+ * carry a `dark:` variant. State is expressed by opacity rather than a second
+ * shade table.
+ */
+export interface ConnectorVisual {
+    /** Radius of the node's bulge around this port. */
+    radius: number;
+    /** Radius of the solid core dot the edge attaches to. */
+    dotRadius: number;
+    dotClass: string;
+    opacity: number;
+    /** The outline stays straight here — `ringSize: "fit"`. */
+    solid: boolean;
+}
+export declare const connectorVisual: (connector: LaidOutConnector) => ConnectorVisual;
+/**
+ * How a node card's silhouette is painted, per shared surface variant.
+ *
+ * These are the SVG twins of what `Panel` puts on a `<section>`: the same
+ * shades from the same table, with `bg-` becoming `fill-` and `border-`
+ * becoming `stroke-`. A card in a flow and a card beside it should not be two
+ * different greys, and they were — the node had one hand-picked pair while
+ * every other surface in the kit took `getPanelToneStyles`.
+ *
+ * The glass family keeps its translucent fill and light rim. `backdrop-filter`
+ * is not honoured on an SVG shape, so those variants read as tinted glass
+ * without the blur; everything else is pixel-identical to a Panel.
+ */
+export interface NodeSurface {
+    fill: string;
+    /** Empty for the variants that carry no rim. */
+    stroke: string;
+    /** Extra classes on the path — a drop shadow for `elevated`. */
+    effect: string;
+}
+export declare const getNodeSurface: (tone: TrueColor | undefined, variant: SurfaceVariant | undefined) => NodeSurface;

package/dist/types/common/connectionFlow/types.d.ts

@@ -0,0 +1,394 @@
+import type { ControlSize, SurfaceCorner, TrueColor } from "../theme/Theme";
+import type { PortSide } from "./router";
+/**
+ * How an edge is behaving. `flowing` animates, `stopped` is a solid traversed
+ * edge, `disabled` is a dashed not-yet-reached one.
+ */
+export declare const CONNECTION_STATES: readonly ["flowing", "stopped", "disabled"];
+export type ConnectionState = (typeof CONNECTION_STATES)[number];
+/** Shape of the edge drawn between two nodes. */
+export declare const CONNECTION_FLOW_EDGE_STYLES: readonly ["orthogonal", "curved", "straight"];
+export type ConnectionFlowEdgeStyle = (typeof CONNECTION_FLOW_EDGE_STYLES)[number];
+/**
+ * How the whole component reports that it is loading.
+ *
+ * `skeleton` is the default because it is the only one that holds the card's
+ * shape: a spinner or a bar collapses the frame and the layout jumps when the
+ * real graph arrives.
+ */
+export declare const CONNECTION_FLOW_LOADERS: readonly ["skeleton", "spinner", "progress"];
+export type ConnectionFlowLoader = (typeof CONNECTION_FLOW_LOADERS)[number];
+/** What the in-progress indicator looks like. Only one is ever shown. */
+export declare const CONNECTION_FLOW_PROGRESS_TYPES: readonly ["none", "bar", "spinner"];
+export type ConnectionFlowProgressType = (typeof CONNECTION_FLOW_PROGRESS_TYPES)[number];
+/**
+ * How a node relates to the one before it — the "connection type" borrowed
+ * from `TreeView`, so a flow can express structure as well as sequence.
+ */
+export declare const CONNECTION_FLOW_NODE_KINDS: readonly ["step", "parallel", "child", "branch"];
+export type ConnectionFlowNodeKind = (typeof CONNECTION_FLOW_NODE_KINDS)[number];
+/**
+ * Size of the bulge a node's border takes around a connector. `fit` drops the
+ * bulge entirely, leaving the core dot alone on the border. The rest are the
+ * shared control scale, so a terminal and the controls beside it are described
+ * in one language.
+ */
+export declare const CONNECTION_FLOW_RING_SIZES: readonly ["xs", "sm", "md", "lg", "xl", "fit"];
+export type ConnectionFlowRingSize = (typeof CONNECTION_FLOW_RING_SIZES)[number];
+/**
+ * Radius of the border's bulge, in px, per ring size.
+ *
+ * A terminal is the node's border detouring around the port — a half-circle
+ * springing from the border line — with a solid core dot at the centre that
+ * the edge attaches to. The two radii are related rather than independent so
+ * the proportion holds at every size.
+ */
+export declare const CONNECTOR_RING_RADIUS: Record<ConnectionFlowRingSize, number>;
+/** Radius of the solid core dot for a given bulge radius. */
+export declare const connectorDotRadius: (ringRadius: number) => number;
+/**
+ * Below this the bulge is indistinguishable from the dot sitting in it, so the
+ * outline stays straight and only the dot is drawn. This is what `fit` means.
+ */
+export declare const CONNECTOR_BULGE_MIN = 2.5;
+export interface ConnectionFlowConnectorConfig {
+    state?: ConnectionState;
+    animated?: boolean;
+    /** Size of the border bulge on both ends of this edge. */
+    ringSize?: ConnectionFlowRingSize;
+    /** Edge shape override for this one edge. */
+    edgeStyle?: ConnectionFlowEdgeStyle;
+    /** Force the source-side tone instead of inheriting it from the source node. */
+    sourceTone?: TrueColor;
+    /** Force the target-side tone instead of inheriting it from this node. */
+    targetTone?: TrueColor;
+    /** Draw travelling dots on a `stopped` edge as well as a `flowing` one. */
+    animateCompleted?: boolean;
+    /** Caption rendered along the edge. */
+    label?: string;
+}
+/**
+ * What happened to a step, as opposed to what colour it is.
+ *
+ * A flow almost always has a status per node already; before this it had to be
+ * hand-translated into a tone at every call site, which is how a demo ends up
+ * with `red` on one card and `rose` on the next. `tone` still wins when it is
+ * set, so a status is a default rather than a constraint.
+ */
+export declare const CONNECTION_FLOW_STATUSES: readonly ["succeeded", "running", "failed", "pending", "skipped"];
+export type ConnectionFlowStatus = (typeof CONNECTION_FLOW_STATUSES)[number];
+export declare const STATUS_TONE: Record<ConnectionFlowStatus, TrueColor>;
+/**
+ * Glyph for a status, used only when the node names no icon of its own.
+ *
+ * A status that showed as colour alone would be invisible to anyone who
+ * cannot separate emerald from rose, and `pending` and `skipped` share a tone
+ * outright — the same reason `MultiSelectPills` offers a check mark.
+ */
+export declare const STATUS_ICON: Record<ConnectionFlowStatus, string>;
+/** Alias used where a tone is threaded through helpers. */
+export type TrueColorLike = TrueColor;
+/** How an item shows its progress. */
+export declare const CONNECTION_FLOW_ITEM_PROGRESS: readonly ["none", "bar", "spinner"];
+export type ConnectionFlowItemProgress = (typeof CONNECTION_FLOW_ITEM_PROGRESS)[number];
+/**
+ * One row inside a node card.
+ *
+ * Deliberately a fixed shape rather than free content: the layout is pure, so
+ * a card's height has to be arithmetic, and a list of known parts can be
+ * measured where a caller-supplied template cannot. A node that needs
+ * arbitrary content uses the template slot and declares its own `height`.
+ */
+export interface ConnectionFlowNodeItem {
+    id: string;
+    title: string;
+    subtitle?: string;
+    /** Registry icon name. A spinner takes this slot while progress is running. */
+    icon?: string;
+    /** Picks the tone and, with no icon, the glyph — as it does on a node. */
+    status?: ConnectionFlowStatus;
+    tone?: TrueColor;
+    /** 0–1. */
+    progress?: number;
+    /** Where that progress is drawn. Defaults to the node's `itemProgress`. */
+    progressType?: ConnectionFlowItemProgress;
+}
+export interface ConnectionFlowNode {
+    id: string;
+    title?: string;
+    subtitle?: string;
+    description?: string;
+    /** Registry icon name. A node icon in canvas mode must be a name, not a node. */
+    icon?: string;
+    /**
+     * What happened to this step. Picks the tone and, when the node names no
+     * icon, the glyph — and implies `active` for `running` and `skipped` for
+     * `skipped`, so the semantics are stated once rather than three times.
+     */
+    status?: ConnectionFlowStatus;
+    /** Overrides whatever tone `status` would have chosen. */
+    tone?: TrueColor;
+    /** Currently executing — drives the flow animation and the pulse. */
+    active?: boolean;
+    /** 0–1. Draws the node's own progress indicator. */
+    progress?: number;
+    /** Overrides the flow-level progress indicator for this node. */
+    progressType?: ConnectionFlowProgressType;
+    /** Bypassed — a arc is drawn over it from its last live predecessor. */
+    skipped?: boolean;
+    /** Emits no edge to the following node. */
+    terminal?: boolean;
+    /** How this node attaches to the flow. @default "step" */
+    kind?: ConnectionFlowNodeKind;
+    /**
+     * Which parallel column this lane belongs to.
+     *
+     * Consecutive `parallel` nodes form one column, which left no way to put two
+     * multi-lane columns next to each other — five lanes in a row became one
+     * column of five rather than three lanes feeding two. A change of `group`
+     * starts a new column. Nodes that do not set it all share the same
+     * (undefined) group, so a single run behaves exactly as before.
+     */
+    group?: string;
+    /**
+     * Rows inside the card, below the title and subtitle.
+     *
+     * Measurable, unlike the template slot — which is why they are a fixed shape
+     * and why a card built from them needs no declared height.
+     */
+    items?: ConnectionFlowNodeItem[];
+    /** Where an item's progress is drawn, unless the item overrides it. */
+    itemProgress?: ConnectionFlowItemProgress;
+    /**
+     * Rows shown before the "show more" row appears. Overrides the flow's
+     * `maxVisibleItems`.
+     */
+    maxItems?: number;
+    /** Nodes hanging vertically below this one. */
+    children?: ConnectionFlowNode[];
+    /** Config for the edge leading *into* this node. */
+    connector?: ConnectionFlowConnectorConfig;
+    /**
+     * Exact card height, in px.
+     *
+     * A caller-supplied body cannot be measured — the layout is pure, and the
+     * card's silhouette has to exist before the first paint — so a templated
+     * node says how much room it needs and its content scrolls inside that.
+     * Ignored for a node whose body is built from `items`, which is measurable.
+     */
+    height?: number;
+    /**
+     * Caps the card's height and scrolls the body past it.
+     *
+     * A measurable body (`items`, or a title and subtitle) can outgrow the room
+     * you want to give it; this is how you say so without having to work out the
+     * exact height yourself. Ignored when `height` is set, which is already
+     * exact.
+     */
+    maxHeight?: number;
+    /**
+     * Whether the body scrolls. Defaults to true when the card is capped —
+     * a cap with no scroll is content you have hidden rather than contained.
+     */
+    scrollable?: boolean;
+    /** Excluded from hit-testing, hover and selection. */
+    disabled?: boolean;
+    /** Arbitrary payload handed back on click and hover. */
+    data?: unknown;
+}
+export interface LaidOutNode {
+    id: string;
+    node: ConnectionFlowNode;
+    /**
+     * The card's silhouette: a rounded rectangle detouring around each of its
+     * ports. The card is painted from this path rather than from a CSS border,
+     * because a terminal is the node bulging — no chord across it, and the same
+     * fill inside — which no border can express.
+     */
+    outline: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Y of the horizontal connection point, relative to the node's own top. */
+    anchorY: number;
+    /** Column index on the main track. */
+    column: number;
+    /** Depth below the main track: 0 for the track itself. */
+    depth: number;
+    tone: TrueColor;
+    /**
+     * Whether this card's body scrolls. Resolved in the layout, because the
+     * answer depends on the height it was measured to — not something a
+     * renderer should work out for itself, twice.
+     */
+    scrollable: boolean;
+}
+export interface LaidOutEdge {
+    id: string;
+    fromId: string | null;
+    toId: string;
+    state: ConnectionState;
+    /** Waypoints in layout space, for label placement and measurement. */
+    points: {
+        x: number;
+        y: number;
+    }[];
+    /**
+     * The SVG path. The travelling dots follow this same string, so the dots
+     * and the line they sit on can never disagree about the route.
+     */
+    d: string;
+    sourceTone: TrueColor;
+    targetTone: TrueColor;
+    /** A bypass arc travels *over* skipped nodes rather than between neighbours. */
+    bypass: boolean;
+    /**
+     * Position in its source's emission round-robin, and how many edges share
+     * that round-robin.
+     *
+     * A source releases one dot at a time — to its first target, then its
+     * second, and so on before coming round again — so a fan reads as a source
+     * feeding its targets in turn rather than as a swarm of independent streams.
+     * Only animated edges take a slot.
+     */
+    emitIndex: number;
+    emitCount: number;
+    /**
+     * The longest route in that round-robin, in px.
+     *
+     * The cycle is a property of the *group*, not of one edge: derive it from
+     * each edge's own length and a group containing one long route falls out of
+     * step with itself. Sizing it to the longest route keeps the rhythm shared
+     * and every dot at the same speed — the emitter simply waits for its
+     * furthest target.
+     */
+    emitSpan: number;
+    animated: boolean;
+    label?: string;
+}
+/**
+ * A terminal where one or more edges meet a node.
+ *
+ * These are layout output rather than something each edge draws for itself.
+ * When three edges fan out of one card they share a single port, and an edge
+ * that painted its own endpoints stamped three identical rings on that one
+ * spot — which the highlight then dimmed three times over, so a "dimmed"
+ * connector came out darker than a lit one.
+ */
+export interface LaidOutConnector {
+    id: string;
+    /** The node this connector sits on. */
+    nodeId: string;
+    x: number;
+    y: number;
+    /** Which border of the node it sits on. */
+    side: PortSide;
+    tone: TrueColor;
+    /** The liveliest state among the edges meeting here. */
+    state: ConnectionState;
+    /** Something is flowing through this terminal. */
+    active: boolean;
+    /** Edges meeting here, so the path highlight dims a connector with them. */
+    edgeIds: string[];
+    /** Radius of the border's bulge, in px. */
+    radius: number;
+}
+export interface ConnectionFlowLayout {
+    nodes: LaidOutNode[];
+    edges: LaidOutEdge[];
+    connectors: LaidOutConnector[];
+    width: number;
+    height: number;
+    /**
+     * How far the content overhangs the origin, as a negative number or zero.
+     * A bypass arc lifts above `y = 0`, so a renderer that starts drawing at the
+     * origin clips it; shifting by this puts the whole graph back in view.
+     */
+    offsetX: number;
+    offsetY: number;
+}
+/**
+ * Every number the node body is built from, per shared control size.
+ *
+ * One table, read by both the arithmetic and the CSS. The previous version
+ * declared `padding`, `title` and `body` and nothing read them: the renderers
+ * hardcoded `padding: 10`, `text-[13px]` and `text-[11px]`, so an `xs` flow and
+ * an `xl` flow had identical type and inset while only the box changed size.
+ * That was cosmetic while a card held two fixed lines. It is structural the
+ * moment a card holds a measured list, because the height the layout computes
+ * and the height the DOM renders have to be the same number.
+ */
+export interface NodeMetrics {
+    width: number;
+    /** Inset on all four sides. */
+    padding: number;
+    /** Title type size and the line box it occupies. */
+    title: number;
+    titleLine: number;
+    /** Subtitle and description type size, and their line box. */
+    body: number;
+    bodyLine: number;
+    /** Space between the header, the item list and a progress bar. */
+    gap: number;
+    /** Space between one item and the next. */
+    itemGap: number;
+    /** The leading glyph box — an icon, or the spinner that replaces it. */
+    glyph: number;
+    /**
+     * Control size for that glyph. Restricted to the range where `CustomIcon`
+     * and `ProgressSpinner` render the same px (16 / 20 / 24), so a spinner can
+     * take the icon's place without the row shifting under it.
+     */
+    glyphSize: ControlSize;
+    /** Control size for a progress bar, and the height it actually renders at. */
+    barSize: ControlSize;
+    barHeight: number;
+    /** The "show more" row. */
+    moreRow: number;
+    /** A card holding a title and a subtitle and nothing else. Derived. */
+    height: number;
+}
+export declare const NODE_METRICS: Record<ControlSize, NodeMetrics>;
+export interface ConnectionFlowLayoutOptions {
+    /**
+     * Everything the card body is built from. Held whole rather than copied
+     * field by field, so the layout and the renderers measure from one table.
+     */
+    metrics: NodeMetrics;
+    connectorWidth: number;
+    /** Vertical gap between stacked parallel nodes. */
+    laneGap: number;
+    /** Vertical gap between a node and its children. */
+    childGap: number;
+    /** Horizontal indent for child nodes. */
+    childIndent: number;
+    edgeStyle: ConnectionFlowEdgeStyle;
+    /** Corner radius on an orthogonal edge. */
+    cornerRadius: number;
+    /** How far above everything in the way a bypass arc travels. */
+    bypassLift: number;
+    /** Default size of the border bulge where an edge meets a node. */
+    ringSize: ConnectionFlowRingSize;
+    /** Rows a card shows before the rest collapse behind "show more". */
+    maxVisibleItems: number;
+    /** Where an item draws its progress, unless the item or its node says. */
+    itemProgress: ConnectionFlowItemProgress;
+    /** Corner radius of a node card, in px. Drives the outline path. */
+    nodeCornerRadius: number;
+    padding: number;
+}
+export declare const DEFAULT_LAYOUT_OPTIONS: ConnectionFlowLayoutOptions;
+export declare const NODE_CORNER_RADIUS: Record<SurfaceCorner, number>;
+/** The node's tone: its own if set, else its status's, else neutral. */
+export declare const nodeTone: (node: ConnectionFlowNode | undefined) => TrueColor;
+/** The node's glyph: its own if set, else its status's. */
+export declare const nodeIcon: (node: ConnectionFlowNode | undefined) => string | undefined;
+/** Whether the node is executing. `status: "running"` implies it. */
+export declare const nodeIsActive: (node: ConnectionFlowNode | undefined) => boolean;
+/**
+ * Whether the node is bypassed. Tri-state on purpose: `undefined` means "no
+ * opinion", which is what lets `autoState` infer it, while an explicit
+ * `skipped: false` overrides even `status: "skipped"`.
+ */
+export declare const nodeIsSkipped: (node: ConnectionFlowNode | undefined) => boolean | undefined;