@draftably/runtime 0.4.0 → 0.6.0

package/dist/types/src/model/labels.d.ts

@@ -62,6 +62,12 @@ export interface NodeLabel {
 export declare function nodeLabel(doc: Diagram, id: string, title: string, r: Rect): NodeLabel;
 /** Bounds of a shape together with its label. */
 export declare function visualBounds(doc: Diagram, id: string, title: string, r: Rect): Rect;
+/** Text width a sequence phase's label wraps to, so a long one does not push the lanes right. */
+export declare const PHASE_WRAP = 96;
+/** Inset of a phase label from its band's top left corner. */
+export declare const PHASE_TAB = 8;
+/** A phase label's lines, in the annotation type. */
+export declare const phaseLabelLines: (label: string, r: ResolvedAppearance) => string[];
 /** Text width a sequence message's label wraps to; the gap between participants follows it. */
 export declare const MESSAGE_WRAP = 168;
 /**
@@ -93,6 +99,23 @@ export declare function edgeLabelSize(label: string, r?: ResolvedAppearance, mes
     w: number;
     h: number;
 };
+/**
+ * An activation bar: its width, how far a nested bar steps to the right, how far it runs past
+ * its first and last rows, and the length of a bar whose call gets no reply.
+ */
+export declare const ACTIVATION: {
+    w: number;
+    step: number;
+    over: number;
+    stub: number;
+};
+/** Room between a local action's label and its box, on each side. */
+export declare const ACTION_PAD = 5;
+/** The box of a local action: its label and `ACTION_PAD` round it, centred on the lifeline. */
+export declare function actionSize(label: string, r: ResolvedAppearance): {
+    w: number;
+    h: number;
+};
 /**
  * What a self-message draws, measured from where its row meets the lifeline: how far right, how
  * far above the row and how far below it.

package/dist/types/src/model/markers.d.ts

@@ -30,10 +30,17 @@ export declare const markerBox: (kind: Exclude<EndMarker, "none">, tail: boolean
 };
 /** The fill a marker takes on this line and surface. */
 export declare function markerFill(kind: Exclude<EndMarker, 'none'>, ink: string, surface: string): string;
+/**
+ * What `message=` accepts on a sequence message, plus `action`, which an `action` line makes.
+ * Each says what the author means; none is read from a line's style.
+ */
+export declare const MESSAGE_KINDS: readonly ["interaction", "call", "send", "reply", "outcome"];
+export type MessageKind = (typeof MESSAGE_KINDS)[number] | 'action';
 type Ends = {
     directed?: boolean;
     head?: EndMarker;
     tail?: EndMarker;
+    message?: MessageKind;
 };
 /** An undirected edge has no marks, whatever else it holds. */
 export declare const headOf: (e: Ends) => EndMarker;

package/dist/types/src/model/note.d.ts

@@ -46,13 +46,22 @@ export declare function noteBox(look: ResolvedAppearance, note: Note): PlacedNot
  * Spots in a sequence's side margins, by index in `notes`, for notes on the messages in `rows`.
  * `left` and `right` are the margins' inner edges and `top` the highest a note goes. A note is
  * level with its row, or pushed down clear of the note above it. The panel grows round these, so
- * no note here can cover the drawing.
+ * no note here can cover the drawing. A note on a message in a phase stays inside that phase's
+ * band (`bands`, by message), which `marginNoteRoom` makes tall enough for its notes.
  */
 export declare function marginNotes(look: ResolvedAppearance, notes: readonly Note[], rows: ReadonlyMap<string, number>, { left, right, top }: {
     left: number;
     right: number;
     top: number;
-}): (Rect | null)[];
+}, bands?: ReadonlyMap<string, {
+    y: number;
+    h: number;
+}>): (Rect | null)[];
+/**
+ * The height a phase band needs for the margin notes on its messages (`ids`): the taller of its
+ * two sides, each a stack of its notes.
+ */
+export declare function marginNoteRoom(look: ResolvedAppearance, notes: readonly Note[], ids: string[]): number;
 /**
  * Place every anchored note beside its object or message, clear of shapes, group borders, lines
  * and earlier notes when a nearby spot allows it. Frame notes, and notes whose object is not drawn,

package/dist/types/src/model/routes.d.ts

@@ -132,6 +132,8 @@ export declare function routeInput(doc: Diagram, vg: VisibleGraph, all: Map<stri
         tail?: import("./markers.js").EndMarker;
         emphasis: boolean;
         dashed: boolean;
+        message?: import("./markers.js").MessageKind;
+        replyTo?: string;
         status?: import("./status.js").Status;
         spot?: import("./status.js").Spot;
     }[];

package/dist/types/src/model/status.d.ts

@@ -82,3 +82,21 @@ export declare function withState(doc: Diagram, id: string): Diagram;
 export declare function usedStatuses(doc: Diagram): StatusCount[];
 /** The color key's rows: a diff draws no family colors, so it lists only its statuses. */
 export declare const drawnLegend: (doc: Diagram) => LegendEntry[];
+/** What every sequence says under its drawing. */
+export declare const SEQUENCE_CAPTION = "Rows show order, not elapsed time.";
+/**
+ * The events that belong with one event of a sequence: a message, the reply that answers it,
+ * and the message a reply answers. Only pairs the file states, never a guess from direction.
+ */
+export declare function replyPair(doc: Diagram, id: string): string[];
+/**
+ * A sequence in words, for a reader who cannot see it: the participants, then each event in
+ * order with its kind. An exported SVG carries it as its description unless the host gives one.
+ */
+export declare function sequenceDescription(doc: Diagram): string | undefined;
+/**
+ * The key a sequence draws for its kinds of message: one row for each mark in use, so a reader
+ * never has to guess what a solid head or a box means. Nothing unless a message has a kind. A
+ * plain message and a shown result draw the same arrow, so they share a row.
+ */
+export declare function messageKey(doc: Diagram): LegendEntry[];

package/dist/types/src/model/types.d.ts

@@ -13,7 +13,7 @@ export type PortSide = Side | 'auto';
 export type Direction = 'RIGHT' | 'DOWN';
 export type Theme = 'light' | 'dark';
 import type { DiagramAppearance, Shade } from './appearance.js';
-import type { EndMarker } from './markers.js';
+import type { EndMarker, MessageKind } from './markers.js';
 import type { Spot, Status } from './status.js';
 export type ShapeKind = 'box' | 'pill' | 'circle' | 'diamond' | 'text' | 'icon' | 'image'
 /** A seam between two cells of a `cells` group. */
@@ -70,6 +70,13 @@ export interface DiagramEdge {
     tail?: EndMarker;
     emphasis: boolean;
     dashed: boolean;
+    /**
+     * A sequence message's meaning, from `message=`, or `action` for work one participant does
+     * (an `action` line; `from` and `to` are that participant). Unset for a plain message.
+     */
+    message?: MessageKind;
+    /** With `message: 'reply'`: the earlier message this one answers, from `answers=`. */
+    replyTo?: string;
     /** How it differs between two versions of the diagram. */
     status?: Status;
     /** How the drawn emphasis state treats it; see `withState`. */
@@ -93,6 +100,8 @@ export interface EdgeLayout {
     toOffset?: number;
     /** A sequence message: drawn straight between the two lifelines at this height, not routed. */
     row?: number;
+    /** A message between distant lanes: the middle of the gap between lifelines its label sits in. */
+    labelX?: number;
     /**
      * Set by the compiler for a forward line in a `flow` scope: its route planned from the ranks.
      * The quick router takes it as it is when it clears every box.
@@ -274,8 +283,18 @@ export interface SequenceLayout {
         rows: Record<string, number>;
         phases: SequencePhase[];
         grow: number;
+        activations?: Activation[];
     };
+    /** With `activations=on`: the bars on the lifelines of participants at work on a call. */
+    activations?: Activation[];
+    /** The `activations=on` switch itself, which the Inspector turns on and off. */
+    bars?: true;
 }
+/** One activation bar: its participant, the call that opened it, and its box. */
+export type Activation = Rect & {
+    node: string;
+    call: string;
+};
 export type SequencePhase = {
     id: string;
     label: string;

package/dist/types/src/runtime/color-scheme.d.ts

@@ -0,0 +1,15 @@
+/** Watches one host's scheme. `check` reads it again now; `stop` ends the watch. */
+export interface SchemeWatch {
+    check(): void;
+    stop(): void;
+}
+/**
+ * Calls `onChange(dark)` now and whenever the scheme in `host` changes: an element, or a shadow
+ * root, whose children inherit the element's scheme. A hidden probe in `host` has a `light-dark()`
+ * color, so a scheme change anywhere above it (a class flip on the page, a style) starts a
+ * transition there; the media query covers a change of system setting under `light dark`. A
+ * transition cannot run while the host has no box (a hidden tab, a closed `<details>`, a detached
+ * mount), so a resize observer on the host reads the scheme again when it gets one. Callers also
+ * call `check` after each commit.
+ */
+export declare function watchColorScheme(host: Element | ShadowRoot, onChange: (dark: boolean) => void): SchemeWatch;

package/dist/types/src/runtime/host.d.ts

@@ -3,6 +3,7 @@
  * packages loop over `HOST_EVENTS`, so a new event adds no lines to any of them.
  * This module has no side effects and no runtime imports.
  */
+import type { RenderFailure } from './types.js';
 import type { UpdateResult, ViewerEvents } from './viewer.js';
 export type { Camera, CameraReason, FrameOptions, MoveResult } from './camera.js';
 export type { Box, EdgeOut, Geometry, PlacedBox } from './geometry.js';
@@ -10,8 +11,11 @@ export type { Anchor, DraftSlot } from './anchors.js';
 export interface HostEvents {
     /** After each commit, after the marked children change, and with `[]` before destroy. */
     anchors: ViewerEvents['anchors'];
-    /** Each update's result: committed, error or a cancellation. */
-    update: UpdateResult;
+    /**
+     * Each update's result, from the first source on: committed, error or a cancellation. The
+     * editor's commit has no `value` or `diagnostics` (see `EditorUpdate`).
+     */
+    update: UpdateResult | EditorUpdate;
     render: ViewerEvents['render'];
     diagnostics: ViewerEvents['diagnostics'];
     camera: ViewerEvents['camera'];
@@ -30,11 +34,39 @@ export interface HostEvents {
         source: string;
     };
 }
+/**
+ * `<draft-editor>`'s update. The editor draws in its own session, not as one SVG, so a commit
+ * has no `value` and no `diagnostics`: the `diagnostics` event has them. A source that does not
+ * parse is an `error` with a `DRAFT_PARSE` diagnostic; the editor keeps the text and shows it.
+ */
+export type EditorUpdate = {
+    status: 'committed';
+    revision: number;
+    value?: never;
+    diagnostics?: never;
+} | {
+    status: 'error';
+    revision: number;
+    error: RenderFailure;
+} | {
+    status: 'destroyed';
+    revision: number;
+};
 export type HostEventName = keyof HostEvents;
 /** Every event, in one list. Each element dispatches these as bubbling `draft-<name>` events. */
 export declare const HOST_EVENTS: readonly ["anchors", "update", "render", "diagnostics", "camera", "itemactivate", "link", "contextmenu", "select", "change"];
 /** Events a host can cancel with `preventDefault()`. */
+export type CancelableEventName = 'link' | 'contextmenu';
 export declare const CANCELABLE_EVENTS: readonly HostEventName[];
+/**
+ * What a framework event prop receives: the event's `detail`, and on a cancelable event a
+ * `preventDefault()` that cancels the DOM event, so `onLink={e => e.preventDefault()}` works.
+ */
+export type HostEventDetail<K extends HostEventName> = K extends CancelableEventName ? HostEvents[K] & {
+    preventDefault(): void;
+} : HostEvents[K];
+/** The value a framework event prop receives for a `draft-<name>` event. */
+export declare function hostDetail(event: Event): unknown;
 export type DraftEventMap = {
     [K in HostEventName as `draft-${K}`]: CustomEvent<HostEvents[K]>;
 };

package/dist/types/src/runtime/page-shared.d.ts

@@ -4,7 +4,7 @@
  */
 import type { RenderOptions, RenderResult } from './types.js';
 /** Names the worker and the usual fix, so "worker failed" is not a dead end. */
-export declare const WORKER_HELP = "The worker is the module next to @draftably/runtime's viewer. With Vite, add optimizeDeps: { exclude: ['@draftably/runtime', '@draftably/editor'] } to vite.config.";
+export declare const WORKER_HELP = "The worker is the module next to @draftably/runtime's viewer. With Vite 5\u20137, add optimizeDeps: { exclude: ['@draftably/runtime', '@draftably/editor'] } to vite.config.";
 /**
  * Render in the page's worker pool. Jobs queue on the main thread; an aborted job leaves the
  * queue before a worker sees it. A job that runs past `timeoutMs` stops its worker only.

package/dist/types/src/runtime/schemes.d.ts

@@ -0,0 +1,2 @@
+/** Both drawings as one, or null when they differ in more than color. */
+export declare function mergeSchemes(light: string, dark: string): string | null;

package/dist/types/src/runtime/svg-renderer.d.ts

@@ -3,6 +3,7 @@
  * same appearance, shapes and title wrapping as the canvas and embeds the fonts it uses.
  */
 import { type ResolvedAppearance } from '../model/appearance.js';
+import { PHASE_TAB } from '../model/labels.js';
 import { computeRoutes } from '../model/routes.js';
 import type { Diagram, Rect } from '../model/types.js';
 /** How an object's `href` is written into the file; as written unless the caller says. */
@@ -26,21 +27,25 @@ export interface SvgOptions {
         rects: Map<string, Rect>;
         routes: Route[];
     }) => void;
+    /**
+     * The routes `onDrawn` gave for this document, so drawing it again in other colors routes
+     * nothing again (not for compare or states).
+     */
+    routes?: Route[];
 }
 export declare class SvgLimitError extends Error {
 }
-type Route = ReturnType<typeof computeRoutes>['routes'][number];
+export type Route = ReturnType<typeof computeRoutes>['routes'][number];
 /**
  * A sequence diagram's panel, a light surface with a border that bounds the exchange, and a row
  * band for each phase with its label in a tab at the left edge. Drawn under everything else.
  */
 export declare function sequenceBackdrop(doc: Diagram, look: ResolvedAppearance): {
     panel: string[];
+    bars: string[];
     phases: string[];
 };
-/** Inset of a phase label from its band's top left corner. */
-export declare const PHASE_TAB = 8;
+export { PHASE_TAB };
 /** A thin stripe across the top of a box, inside its rounded corners. */
 export declare function accentPath(r: Rect, radius: number): string;
 export declare function renderSvg(doc: Diagram, opts?: SvgOptions): string;
-export {};

package/dist/types/src/runtime/types.d.ts

@@ -49,6 +49,13 @@ export interface CommonRenderOptions {
     sourceId?: string;
     signal?: AbortSignal;
     limits?: Partial<RenderLimits>;
+    /**
+     * `light` (default) draws the file's own colors. `dark` draws a file without a `theme` line in
+     * the default theme's dark variant. `auto` writes both as `light-dark()` colors, so the page's
+     * `color-scheme` picks one; the viewer and `<draft-diagram>` use it. A file's own theme line
+     * always wins.
+     */
+    colorScheme?: 'light' | 'dark' | 'auto';
 }
 export type RenderOptions = CommonRenderOptions & ({
     target?: 'image';

package/dist/version-D7YCY2pU.js

@@ -0,0 +1,4 @@
+const n = "0.6.0", o = n;
+export {
+  o as r
+};

package/dist/viewer.css

@@ -3,13 +3,14 @@
  * They inherit through the shadow root; the defaults below apply only when unset.
  */
 .draft-viewer {
-  --dv-border: var(--draft-border, #cbd5e1);
-  --dv-ink: var(--draft-ink, #1e293b);
-  --dv-bg: var(--draft-bg, #fff);
-  --dv-focus: var(--draft-focus, #2563eb);
-  --dv-shadow: var(--draft-shadow, rgb(15 23 42 / 0.12));
-  --dv-warning-ink: var(--draft-warning-ink, #9a3412);
-  --dv-warning-bg: var(--draft-warning-bg, #fff7ed);
+  /* The viewer sets color-scheme from the page; each default has a dark value. */
+  --dv-border: var(--draft-border, light-dark(#cbd5e1, #3d4450));
+  --dv-ink: var(--draft-ink, light-dark(#1e293b, #e7eaef));
+  --dv-bg: var(--draft-bg, light-dark(#fff, #16191e));
+  --dv-focus: var(--draft-focus, light-dark(#2563eb, #7fa4e6));
+  --dv-shadow: var(--draft-shadow, light-dark(rgb(15 23 42 / 0.12), rgb(0 0 0 / 0.4)));
+  --dv-warning-ink: var(--draft-warning-ink, light-dark(#9a3412, #fdba74));
+  --dv-warning-bg: var(--draft-warning-bg, light-dark(#fff7ed, #431407));
   position: relative;
   display: grid;
   grid-template-rows: auto minmax(8rem, 1fr) auto auto;
@@ -126,7 +127,7 @@
 }
 
 /* The anchor layer: slot targets above the drawing. Slot content takes no pointer input unless
-   it is marked data-draft-input (host.css). */
+   it is marked data-draft-input. */
 .draft-anchors {
   position: absolute;
   inset: 0;
@@ -150,6 +151,11 @@
   box-sizing: border-box;
   pointer-events: none;
 }
+/* Marked content in a mountViewer target, in the page's DOM. The element's slotted content gets the
+   same rule from host.css, because these selectors do not reach into slots. */
+.draft-anchor [data-draft-input] {
+  pointer-events: auto;
+}
 .draft-anchor--body {
   overflow: clip;
 }