@draftably/editor 0.3.0 → 0.5.0

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

@@ -0,0 +1,122 @@
+import type { Geometry } from './geometry';
+export type Severity = 'error' | 'warning' | 'info';
+export interface SourceLocation {
+    sourceId?: string;
+    line: number;
+    column?: number;
+}
+export interface Diagnostic {
+    code: string;
+    severity: Severity;
+    message: string;
+    location?: SourceLocation;
+    itemIds: readonly string[];
+    related?: readonly {
+        message: string;
+        location: SourceLocation;
+    }[];
+    nativeCode?: string;
+}
+export interface CompileLimits {
+    maxSourceChars: number;
+    maxSourceBytes: number;
+    maxObjects: number;
+    maxEdges: number;
+    maxDepth: number;
+}
+export interface RenderLimits extends CompileLimits {
+    maxOutputBytes: number;
+}
+export type LinkPolicy = {
+    mode: 'none';
+} | {
+    mode: 'safe';
+    baseUrl?: string;
+    target?: '_self' | '_blank';
+    resolve?: (request: {
+        itemId: string;
+        href: string;
+    }) => string | null;
+    cacheKey?: string;
+};
+export interface CommonRenderOptions {
+    title?: string;
+    description?: string;
+    includeSource?: boolean;
+    links?: LinkPolicy;
+    styleNonce?: string;
+    state?: string | null;
+    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';
+    idPrefix?: never;
+    fonts?: 'embed';
+} | {
+    target: 'inline';
+    idPrefix: string;
+    fonts?: 'embed' | 'host';
+});
+export interface ValidateOptions {
+    sourceId?: string;
+    signal?: AbortSignal;
+    limits?: Partial<CompileLimits>;
+}
+export interface ItemSummary {
+    id: string;
+    kind: 'node' | 'group' | 'edge';
+    label: string;
+    line: number;
+    from?: string;
+    to?: string;
+}
+export interface DiagramSummary {
+    title: string;
+    description?: string;
+    width: number;
+    height: number;
+    viewBox: readonly [number, number, number, number];
+    items: readonly ItemSummary[];
+    states: readonly {
+        id: string;
+        label: string;
+    }[];
+    activeState: string | null;
+}
+export interface RenderedDiagram extends DiagramSummary {
+    svg: string;
+    /**
+     * Where each node, group and edge is drawn, in the SVG's own units (its `viewBox`), in the graph
+     * API's shapes. `null` for `compare` and `states` drawings, which repeat items across panels.
+     */
+    geometry: Geometry | null;
+    provenance: {
+        runtimeVersion: string;
+        dslVersion: 1;
+        fontMetricsVersion: string;
+        renderContextVersion: string;
+    };
+}
+export type RenderFailure = {
+    ok: false;
+    reason: 'input' | 'limit' | 'aborted' | 'environment' | 'internal';
+    diagnostics: readonly Diagnostic[];
+};
+export type RenderResult = {
+    ok: true;
+    value: RenderedDiagram;
+    diagnostics: readonly Diagnostic[];
+} | RenderFailure;
+export type ValidationResult = {
+    ok: true;
+    diagnostics: readonly Diagnostic[];
+} | RenderFailure;

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

@@ -0,0 +1,2 @@
+export declare const runtimeVersion: string;
+export { fontMetricsVersion } from '../model/font-faces';

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

@@ -0,0 +1,123 @@
+import { type Camera, type CameraReason, type FrameOptions, type MoveResult } from './camera';
+import { type Anchor, type DraftSlot } from './anchors';
+import { type Geometry } from './geometry';
+import { fontMetricsVersion, runtimeVersion } from './version';
+import type { CommonRenderOptions, Diagnostic, LinkPolicy, RenderFailure, RenderResult } from './types';
+export { fontMetricsVersion, runtimeVersion };
+export type { Camera, CameraReason, FrameOptions, MoveResult } from './camera';
+export type { Box, EdgeOut, Geometry, PlacedBox } from './geometry';
+export type { Anchor, DraftSlot } from './anchors';
+export { ZOOM_MAX, ZOOM_MIN } from './camera';
+export type ViewerExecution = {
+    mode: 'worker';
+    createWorker?: () => Worker;
+    timeoutMs?: number;
+} | {
+    mode: 'main';
+};
+export type ViewerRenderOptions = Omit<CommonRenderOptions, 'signal' | 'state'> & {
+    fonts?: 'host' | 'embed';
+};
+export interface ViewerOptions {
+    label?: string;
+    toolbar?: boolean;
+    /**
+     * The keyboard and screen-reader list of items. `'hidden'` (default) keeps it for assistive tech
+     * and shows it while it holds focus; `'visible'` always shows it under the drawing.
+     */
+    outline?: 'visible' | 'hidden';
+    execution?: ViewerExecution;
+    /** `auto` (default) hides slot bodies and shows titles again below a zoom of 0.4. */
+    detail?: 'auto' | 'full';
+    render?: ViewerRenderOptions;
+}
+export interface UpdateOptions {
+    camera?: 'preserve' | 'fit';
+    state?: string | null;
+    signal?: AbortSignal;
+}
+export type UpdateResult = {
+    status: 'committed';
+    revision: number;
+    value: Extract<RenderResult, {
+        ok: true;
+    }>['value'];
+    diagnostics: readonly Diagnostic[];
+} | {
+    status: 'error';
+    revision: number;
+    error: RenderFailure;
+} | {
+    status: 'superseded' | 'destroyed' | 'aborted';
+    revision: number;
+};
+export interface ViewerEvents {
+    /** After each commit, after `anchor()`, and with `[]` before `destroy` detaches the targets. */
+    anchors: {
+        anchors: readonly Anchor[];
+    };
+    /** After each commit: the drawing, and where each item is (`null` for compare and states). */
+    render: {
+        revision: number;
+        value: Extract<RenderResult, {
+            ok: true;
+        }>['value'];
+        geometry: Geometry | null;
+    };
+    diagnostics: {
+        revision: number;
+        diagnostics: readonly Diagnostic[];
+        stale: boolean;
+    };
+    /** At most once per animation frame, with the latest reason. */
+    camera: {
+        camera: Camera;
+        reason: CameraReason;
+    };
+    itemactivate: {
+        id: string;
+        kind: 'node' | 'group' | 'edge';
+        input: 'pointer' | 'keyboard';
+        revision: number;
+    };
+    /** `preventDefault()` stops the viewer opening the link. */
+    link: {
+        itemId: string;
+        href: string;
+        target: '_self' | '_blank';
+        preventDefault(): void;
+    };
+    /** A right-click or the menu key; `id` is null on the background. `preventDefault()` stops the browser's menu. */
+    contextmenu: {
+        id: string | null;
+        kind?: ItemKind;
+        clientX: number;
+        clientY: number;
+        preventDefault(): void;
+    };
+}
+export type ItemKind = 'node' | 'group' | 'edge';
+export interface ViewerHandle {
+    /** Resolves after the first commit or failure; then after each later one. */
+    readonly ready: Promise<UpdateResult>;
+    update(source: string, options?: UpdateOptions): Promise<UpdateResult>;
+    /** Where each item is drawn, in world units. `null` before the first commit, and for compare and states. The same object for one revision. */
+    geometry(): Geometry | null;
+    on<K extends keyof ViewerEvents>(type: K, listener: (event: ViewerEvents[K]) => void): () => void;
+    getCamera(): Camera;
+    /** Zoom is clamped to `ZOOM_MIN`–`ZOOM_MAX`. */
+    setCamera(camera: Camera): void;
+    /** Frame these items, or the whole drawing without ids. At most actual size by default. */
+    fit(ids?: readonly string[], options?: FrameOptions): MoveResult;
+    /** The least move that shows the item; zooms out only if it does not fit. */
+    reveal(id: string, options?: FrameOptions): MoveResult;
+    focusItem(id: string): boolean;
+    /**
+     * Plain-DOM hosts only: keep a target for each slot (`body:<id>`, `overlay:<id>`). Targets come
+     * in the `anchors` event; put content in them. The elements set this from their marked children.
+     */
+    anchor(slots: readonly DraftSlot[]): void;
+    destroy(): void;
+}
+export declare function mountViewer(host: HTMLElement, options?: ViewerOptions): ViewerHandle;
+export type { LinkPolicy };

package/dist/types/src/state/active-session.d.ts

@@ -1,5 +1,6 @@
 import type { DiagramSession } from './session';
 export declare function activeSession(): DiagramSession;
+export declare const hasActiveSession: () => boolean;
 export declare const setActiveSession: (session: DiagramSession) => {
     dispose: () => void;
 } & {
@@ -46,7 +47,8 @@ export declare const setActiveSession: (session: DiagramSession) => {
     redo: () => void;
     canUndo: () => boolean;
     canRedo: () => boolean;
-    setCamera: (camera: import("../model/types").Camera) => void;
+    setCamera: (camera: import("../model/types").Camera, reason?: import("../runtime/camera").CameraReason) => void;
+    onCamera: (listener: (reason: import("../runtime/camera").CameraReason) => void) => () => boolean;
     disableBrowserStorage: () => boolean;
     setPersistenceBlocked: (blocked: boolean) => void;
     persist: () => void;
@@ -267,6 +269,9 @@ export declare const setActiveSession: (session: DiagramSession) => {
     showState: (id: string | null) => void;
     stepState: (by: 1 | -1) => boolean;
     drawnDoc: () => import("../model/types").Diagram;
+    dark: import("solid-js").Accessor<boolean>;
+    setDark: import("solid-js").Setter<boolean>;
+    drawnAppearance: () => import("../model/appearance").DiagramAppearance;
 } & {
     tool: import("solid-js").Accessor<import("./session/editor").Tool>;
     setToolSignal: import("solid-js").Setter<import("./session/editor").Tool>;
@@ -476,4 +481,8 @@ export declare const setActiveSession: (session: DiagramSession) => {
     onDoubleClick: (e: MouseEvent) => void;
     selectForContextMenu: (e: MouseEvent) => void;
     dragKind: () => string | undefined;
+} & {
+    describeLink: (href: string) => string;
 };
+/** A destroyed session stops being the target of shortcuts and commands. */
+export declare const releaseActiveSession: (session: DiagramSession) => void;

package/dist/types/src/state/dom-root.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Lookups that work when the editor renders inside a shadow root. A page-level listener sees an
+ * event retargeted to the shadow host, and `document` lookups cannot see inside a shadow root.
+ */
+/** The document or shadow root that holds `node`. */
+export declare const rootOf: (node: Node) => Document | ShadowRoot;
+/** The element the event started on, inside any shadow root. */
+export declare const eventTarget: (e: Event) => EventTarget | null;

package/dist/types/src/state/session/document.d.ts

@@ -1,4 +1,5 @@
 import type { Camera, Diagram } from '../../model/types';
+import type { CameraReason } from '../../runtime/camera';
 import type { CanvasTextPart } from './canvas-text';
 import type { SessionOptions } from '.';
 export interface HistoryEntry {
@@ -69,7 +70,8 @@ export declare function createDocument(s: CanvasTextPart, options: SessionOption
     redo: () => void;
     canUndo: () => boolean;
     canRedo: () => boolean;
-    setCamera: (camera: Camera) => void;
+    setCamera: (camera: Camera, reason?: CameraReason) => void;
+    onCamera: (listener: (reason: CameraReason) => void) => () => boolean;
     disableBrowserStorage: () => boolean;
     setPersistenceBlocked: (blocked: boolean) => void;
     persist: () => void;

package/dist/types/src/state/session/editor.d.ts

@@ -25,8 +25,9 @@ export interface DragFeedback {
         near?: string;
     };
 }
-export declare const MIN_ZOOM = 0.08;
-export declare const MAX_ZOOM = 4;
+/** The zoom range both handles share: `ZOOM_MIN`–`ZOOM_MAX` in `runtime/camera.ts`. */
+export declare const MIN_ZOOM = 0.02;
+export declare const MAX_ZOOM = 8;
 export { NodeGeometry };
 export declare function createEditor(s: DocumentPart & ScenePart): {
     tool: import("solid-js").Accessor<Tool>;

package/dist/types/src/state/session/emphasis.d.ts

@@ -7,5 +7,8 @@ export declare function createEmphasis(s: DocumentPart): {
     showState: (id: string | null) => void;
     stepState: (by: 1 | -1) => boolean;
     drawnDoc: () => import("../../model/types").Diagram;
+    dark: import("solid-js").Accessor<boolean>;
+    setDark: import("solid-js").Setter<boolean>;
+    drawnAppearance: () => import("../../model/appearance").DiagramAppearance;
 };
 export type EmphasisPart = ReturnType<typeof createEmphasis>;

package/dist/types/src/state/session/index.d.ts

@@ -15,6 +15,11 @@ export interface SessionOptions {
     openLink?: (href: string) => void;
     /** The user started a gesture or a tool on the canvas; a host closes its menus here. */
     onInteract?: () => void;
+    /** A link was pressed, before it opens. Return true to stop it opening. */
+    onLink?: (link: {
+        href: string;
+        itemId: string | undefined;
+    }) => boolean;
 }
 export declare function createDiagramSession(options?: SessionOptions): {
     dispose: () => void;
@@ -62,7 +67,8 @@ export declare function createDiagramSession(options?: SessionOptions): {
     redo: () => void;
     canUndo: () => boolean;
     canRedo: () => boolean;
-    setCamera: (camera: import("../../model/types").Camera) => void;
+    setCamera: (camera: import("../../model/types").Camera, reason?: import("../../runtime/camera").CameraReason) => void;
+    onCamera: (listener: (reason: import("../../runtime/camera").CameraReason) => void) => () => boolean;
     disableBrowserStorage: () => boolean;
     setPersistenceBlocked: (blocked: boolean) => void;
     persist: () => void;
@@ -283,6 +289,9 @@ export declare function createDiagramSession(options?: SessionOptions): {
     showState: (id: string | null) => void;
     stepState: (by: 1 | -1) => boolean;
     drawnDoc: () => import("../../model/types").Diagram;
+    dark: import("solid-js").Accessor<boolean>;
+    setDark: import("solid-js").Setter<boolean>;
+    drawnAppearance: () => import("../../model/appearance").DiagramAppearance;
 } & {
     tool: import("solid-js").Accessor<import("./editor").Tool>;
     setToolSignal: import("solid-js").Setter<import("./editor").Tool>;
@@ -492,5 +501,8 @@ export declare function createDiagramSession(options?: SessionOptions): {
     onDoubleClick: (e: MouseEvent) => void;
     selectForContextMenu: (e: MouseEvent) => void;
     dragKind: () => string | undefined;
+} & {
+    /** What opening `href` does, for a link mark's label. */
+    describeLink: (href: string) => string;
 };
 export type DiagramSession = ReturnType<typeof createDiagramSession>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@draftably/editor",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "The Draftably diagram editor: drag boxes and lines, and get the .draft source back.",
   "license": "MIT",
   "type": "module",