@miragon/modeler-shell 0.0.0-stage → 0.2.0

package/dist/toasts-Bp0REqdq.d.cts

@@ -0,0 +1,142 @@
+/** A point in pixels or diagram coordinates, as the context says. */
+interface Point {
+    x: number;
+    y: number;
+}
+interface Size {
+    width: number;
+    height: number;
+}
+/** A rectangle; content bounds and viewboxes are in diagram coordinates. */
+interface Bounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A viewbox together with the scale diagram-js shows it at (`canvas.viewbox().scale`). */
+interface ScaledViewbox extends Bounds {
+    scale: number;
+}
+/** Distances in pixels from the edges of the modeler's container. */
+interface Insets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * The host column of guide §5.2: `ide` is a VS Code webview (later IntelliJ), `web` a Miragon web
+ * app that owns its page, `embedded` a modeler inside a foreign page (designIQ, modeler-api hosts).
+ */
+type ShellHost = "ide" | "web" | "embedded";
+/**
+ * The `data-chrome` names of the chrome (guide §5.2, §13.4). The web column adds `primary`, `legal`,
+ * `toasts`, `empty-state`, `drop-zone` and `problems-popover` (0.2); IDE and embedded hosts never
+ * show `primary`, `legal`, `empty-state` and `drop-zone`, the IDE host never `toasts` and
+ * `problems-popover`.
+ */
+type ChromeIsland = "menu" | "palette" | "primary" | "zoom" | "problems" | "legend" | "inspector" | "status" | "legal" | "toasts" | "empty-state" | "drop-zone" | "problems-popover";
+declare const CHROME_ISLANDS: readonly ChromeIsland[];
+/** Where the palette sits: in the top row, or in the second row below it (guide §5.15). */
+type PaletteRow = "top" | "second-row";
+/**
+ * What the zoom panel and the chrome keys act on. The diagram-js viewport implements it; the DOM
+ * shell only talks to this interface.
+ */
+interface ZoomTarget {
+    /** The current zoom, 1 = 100 % (diagram-js `canvas.zoom()`, rounded to three decimals). */
+    zoom(): number;
+    /** One step on the zoom raster around the container centre (diagram-js `zoomScroll.stepZoom`). */
+    stepZoom(direction: 1 | -1): void;
+    /** 100 % around the container centre. Counts as a user move. */
+    zoomToActual(): void;
+    /** Explicit fit (button, Shift+1, command): animated unless reduced motion, makes the view automatic. */
+    fit(): void;
+    /** False while there is nothing to fit (the content bounds are empty). */
+    canFit(): boolean;
+    /**
+     * Calls `listener` after every viewbox change and whenever `canFit()` may have changed, possibly
+     * several times per frame. Returns the unsubscribe function.
+     */
+    onChange(listener: () => void): () => void;
+}
+/** The persisted view (VS Code `setState`): JSON-serializable. */
+interface ViewportState {
+    viewbox: Bounds;
+    /** The user zoomed or panned since the last fit; a resize no longer refits. */
+    userMoved: boolean;
+}
+
+/** The statuses of guide §3.3 and §9; each colours bar and dot through `--cd-ui-<status>`. */
+type ToastStatus = "success" | "info" | "warning" | "danger";
+/** A ghost button before Close (guide §8); the toast then never closes by itself. */
+interface ToastAction {
+    label: string;
+    /** Runs after the toast closed. */
+    onSelect(): void;
+}
+interface ToastRequest {
+    status: ToastStatus;
+    /** What happened and what you can do (guide §2): "Link copied", "Couldn't read this file. …". */
+    text: string;
+    action?: ToastAction | undefined;
+    /** Only to give a long text more time than `TOAST_DURATION_MS`; ignored with an `action`. */
+    durationMs?: number | undefined;
+}
+/** At most three toasts at once, the newest at the bottom (guide §8). */
+declare const MAX_TOASTS = 3;
+/**
+ * How long a toast stays without hover or focus (guide §8: about 2.8 s, errors about 5 s). A
+ * warning asks you to read a sentence and act on it like an error, so it gets the error's 5 s.
+ */
+declare const TOAST_DURATION_MS: Readonly<Record<ToastStatus, number>>;
+/** The stack's widest toast: `min(480px, 100cqw − 24px)` (guide §8). */
+declare const TOAST_MAX_WIDTH = 480;
+/**
+ * Milliseconds until the toast closes by itself: `undefined` with an `action` (it never closes by
+ * itself, guide §8), else `max(TOAST_DURATION_MS[status], durationMs ?? 0)`.
+ */
+declare function toastLifetime(request: ToastRequest): number | undefined;
+/** A toast in the stack as the eviction sees it, oldest first. */
+interface ToastSlot {
+    id: number;
+    hasAction: boolean;
+    /** Hovered or holding the focus. */
+    engaged: boolean;
+}
+/**
+ * Which toast leaves when a fourth arrives (`MAX_TOASTS`): the oldest that is neither engaged nor
+ * has an action, else the oldest that is not engaged, else the oldest. `undefined` while the
+ * stack has room.
+ */
+declare function toastToEvict(stack: readonly ToastSlot[]): number | undefined;
+/** Something in the bottom row the toast stack must clear, relative to the shell root. */
+interface BottomObstacle {
+    left: number;
+    right: number;
+    /** Distance of its top edge from the container's bottom edge. */
+    top: number;
+}
+interface ToastStackInput {
+    containerWidth: number;
+    /** The visible zoom panel, legal line and problems pill (not the legend card). */
+    obstacles: readonly BottomObstacle[];
+    /**
+     * Measured width of the widest toast in the stack. The cards are sized to their text and centred
+     * in the stack, so only this column can touch an obstacle; absent = the whole `toastStackWidth`.
+     */
+    cardWidth?: number | undefined;
+}
+/** `min(TOAST_MAX_WIDTH, containerWidth − 2 · SHELL.edge)`. */
+declare function toastStackWidth(containerWidth: number): number;
+/**
+ * The stack's `bottom` in px. Guide §8 anchors it at `bottom: 12px`, centred; where the column of
+ * its widest card (`cardWidth`, at most `toastStackWidth`, centred) comes closer than `SHELL.gap`
+ * horizontally to an obstacle, the stack stands `SHELL.gap` above the highest such obstacle instead
+ * (above the legal line 40, above the zoom panel 60, above a raised zoom panel or the web pill 88).
+ * Guide §8 does not settle this collision of a narrow container; it is the shell's rule until it does.
+ */
+declare function toastStackBottom(input: ToastStackInput): number;
+
+export { type BottomObstacle as B, CHROME_ISLANDS as C, type Insets as I, MAX_TOASTS as M, type PaletteRow as P, type ScaledViewbox as S, TOAST_DURATION_MS as T, type ViewportState as V, type ZoomTarget as Z, type Bounds as a, type ChromeIsland as b, type Point as c, type ShellHost as d, type Size as e, TOAST_MAX_WIDTH as f, type ToastAction as g, type ToastRequest as h, type ToastSlot as i, type ToastStackInput as j, type ToastStatus as k, toastStackBottom as l, toastStackWidth as m, toastToEvict as n, toastLifetime as t };

package/dist/toasts-Bp0REqdq.d.ts

@@ -0,0 +1,142 @@
+/** A point in pixels or diagram coordinates, as the context says. */
+interface Point {
+    x: number;
+    y: number;
+}
+interface Size {
+    width: number;
+    height: number;
+}
+/** A rectangle; content bounds and viewboxes are in diagram coordinates. */
+interface Bounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A viewbox together with the scale diagram-js shows it at (`canvas.viewbox().scale`). */
+interface ScaledViewbox extends Bounds {
+    scale: number;
+}
+/** Distances in pixels from the edges of the modeler's container. */
+interface Insets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * The host column of guide §5.2: `ide` is a VS Code webview (later IntelliJ), `web` a Miragon web
+ * app that owns its page, `embedded` a modeler inside a foreign page (designIQ, modeler-api hosts).
+ */
+type ShellHost = "ide" | "web" | "embedded";
+/**
+ * The `data-chrome` names of the chrome (guide §5.2, §13.4). The web column adds `primary`, `legal`,
+ * `toasts`, `empty-state`, `drop-zone` and `problems-popover` (0.2); IDE and embedded hosts never
+ * show `primary`, `legal`, `empty-state` and `drop-zone`, the IDE host never `toasts` and
+ * `problems-popover`.
+ */
+type ChromeIsland = "menu" | "palette" | "primary" | "zoom" | "problems" | "legend" | "inspector" | "status" | "legal" | "toasts" | "empty-state" | "drop-zone" | "problems-popover";
+declare const CHROME_ISLANDS: readonly ChromeIsland[];
+/** Where the palette sits: in the top row, or in the second row below it (guide §5.15). */
+type PaletteRow = "top" | "second-row";
+/**
+ * What the zoom panel and the chrome keys act on. The diagram-js viewport implements it; the DOM
+ * shell only talks to this interface.
+ */
+interface ZoomTarget {
+    /** The current zoom, 1 = 100 % (diagram-js `canvas.zoom()`, rounded to three decimals). */
+    zoom(): number;
+    /** One step on the zoom raster around the container centre (diagram-js `zoomScroll.stepZoom`). */
+    stepZoom(direction: 1 | -1): void;
+    /** 100 % around the container centre. Counts as a user move. */
+    zoomToActual(): void;
+    /** Explicit fit (button, Shift+1, command): animated unless reduced motion, makes the view automatic. */
+    fit(): void;
+    /** False while there is nothing to fit (the content bounds are empty). */
+    canFit(): boolean;
+    /**
+     * Calls `listener` after every viewbox change and whenever `canFit()` may have changed, possibly
+     * several times per frame. Returns the unsubscribe function.
+     */
+    onChange(listener: () => void): () => void;
+}
+/** The persisted view (VS Code `setState`): JSON-serializable. */
+interface ViewportState {
+    viewbox: Bounds;
+    /** The user zoomed or panned since the last fit; a resize no longer refits. */
+    userMoved: boolean;
+}
+
+/** The statuses of guide §3.3 and §9; each colours bar and dot through `--cd-ui-<status>`. */
+type ToastStatus = "success" | "info" | "warning" | "danger";
+/** A ghost button before Close (guide §8); the toast then never closes by itself. */
+interface ToastAction {
+    label: string;
+    /** Runs after the toast closed. */
+    onSelect(): void;
+}
+interface ToastRequest {
+    status: ToastStatus;
+    /** What happened and what you can do (guide §2): "Link copied", "Couldn't read this file. …". */
+    text: string;
+    action?: ToastAction | undefined;
+    /** Only to give a long text more time than `TOAST_DURATION_MS`; ignored with an `action`. */
+    durationMs?: number | undefined;
+}
+/** At most three toasts at once, the newest at the bottom (guide §8). */
+declare const MAX_TOASTS = 3;
+/**
+ * How long a toast stays without hover or focus (guide §8: about 2.8 s, errors about 5 s). A
+ * warning asks you to read a sentence and act on it like an error, so it gets the error's 5 s.
+ */
+declare const TOAST_DURATION_MS: Readonly<Record<ToastStatus, number>>;
+/** The stack's widest toast: `min(480px, 100cqw − 24px)` (guide §8). */
+declare const TOAST_MAX_WIDTH = 480;
+/**
+ * Milliseconds until the toast closes by itself: `undefined` with an `action` (it never closes by
+ * itself, guide §8), else `max(TOAST_DURATION_MS[status], durationMs ?? 0)`.
+ */
+declare function toastLifetime(request: ToastRequest): number | undefined;
+/** A toast in the stack as the eviction sees it, oldest first. */
+interface ToastSlot {
+    id: number;
+    hasAction: boolean;
+    /** Hovered or holding the focus. */
+    engaged: boolean;
+}
+/**
+ * Which toast leaves when a fourth arrives (`MAX_TOASTS`): the oldest that is neither engaged nor
+ * has an action, else the oldest that is not engaged, else the oldest. `undefined` while the
+ * stack has room.
+ */
+declare function toastToEvict(stack: readonly ToastSlot[]): number | undefined;
+/** Something in the bottom row the toast stack must clear, relative to the shell root. */
+interface BottomObstacle {
+    left: number;
+    right: number;
+    /** Distance of its top edge from the container's bottom edge. */
+    top: number;
+}
+interface ToastStackInput {
+    containerWidth: number;
+    /** The visible zoom panel, legal line and problems pill (not the legend card). */
+    obstacles: readonly BottomObstacle[];
+    /**
+     * Measured width of the widest toast in the stack. The cards are sized to their text and centred
+     * in the stack, so only this column can touch an obstacle; absent = the whole `toastStackWidth`.
+     */
+    cardWidth?: number | undefined;
+}
+/** `min(TOAST_MAX_WIDTH, containerWidth − 2 · SHELL.edge)`. */
+declare function toastStackWidth(containerWidth: number): number;
+/**
+ * The stack's `bottom` in px. Guide §8 anchors it at `bottom: 12px`, centred; where the column of
+ * its widest card (`cardWidth`, at most `toastStackWidth`, centred) comes closer than `SHELL.gap`
+ * horizontally to an obstacle, the stack stands `SHELL.gap` above the highest such obstacle instead
+ * (above the legal line 40, above the zoom panel 60, above a raised zoom panel or the web pill 88).
+ * Guide §8 does not settle this collision of a narrow container; it is the shell's rule until it does.
+ */
+declare function toastStackBottom(input: ToastStackInput): number;
+
+export { type BottomObstacle as B, CHROME_ISLANDS as C, type Insets as I, MAX_TOASTS as M, type PaletteRow as P, type ScaledViewbox as S, TOAST_DURATION_MS as T, type ViewportState as V, type ZoomTarget as Z, type Bounds as a, type ChromeIsland as b, type Point as c, type ShellHost as d, type Size as e, TOAST_MAX_WIDTH as f, type ToastAction as g, type ToastRequest as h, type ToastSlot as i, type ToastStackInput as j, type ToastStatus as k, toastStackBottom as l, toastStackWidth as m, toastToEvict as n, toastLifetime as t };