@miragon/modeler-shell 0.1.0 → 0.2.0

package/dist/appearance-XX3JC3pI.d.cts

@@ -0,0 +1,323 @@
+import { d as ShellHost } from './toasts-Bp0REqdq.cjs';
+import { T as Theme } from './appearance-D3FUcbu6.cjs';
+
+/** The severity of one problem; the pill and the list show `circle-x` or `triangle-alert` (guide §5.10). */
+type ProblemSeverity = "error" | "warning";
+/** One row of the web app's problems list (guide §5.10). */
+interface ProblemItem {
+    severity: ProblemSeverity;
+    /** 13px `--cd-ui-text`: "Unknown sticky type “evnt”." */
+    message: string;
+    /** The place in 13px `--cd-ui-text-leise` below the message: "Line 12", "“Order Placed”". */
+    location?: string | undefined;
+    /** The diagram element a click on the row selects (`ProblemsOptions.onSelectItem`). */
+    elementId?: string | undefined;
+}
+/** `ShellHandle.setProblems` input built from the items: count, errors and the items themselves. */
+declare function problemSummary(items: readonly ProblemItem[]): {
+    count: number;
+    errors: number;
+    items: readonly ProblemItem[];
+};
+
+/** Why a drag cannot be dropped (guide §9 Drop forbidden); `messages.dropForbidden` words each one. */
+type DropForbiddenReason = "multiple" | "type" | "dialog";
+/** One entry of `DataTransfer.items` as a drag shows it (names are not readable before the drop). */
+interface DragItemLike {
+    kind: string;
+    type: string;
+}
+interface DragContext {
+    /** `DropZoneOptions.accept`: extensions (".storm") and MIME types ("application/json", "text/*"). */
+    accept: readonly string[];
+    /** `DropZoneOptions.multiple`. */
+    multiple: boolean;
+    /** A modal dialog is open (the shell's dialog test, as for the keys). */
+    dialogOpen: boolean;
+}
+/** What the drop zone shows for the drag over the page right now (guide §9). */
+type DragVerdict = {
+    state: "none";
+} | {
+    state: "over";
+} | {
+    state: "forbidden";
+    reason: DropForbiddenReason;
+};
+/**
+ * The drop zone's state for a drag (guide §9, Drag-over and Drop forbidden):
+ *
+ * - `none`: no item of kind `file` (a palette drag, selected text): the drop zone stays out of it.
+ * - `forbidden` / `dialog`: a modal dialog is open.
+ * - `forbidden` / `multiple`: more than one file and `multiple` is false.
+ * - `forbidden` / `type`: `accept` lists at least one MIME type and every file item carries a
+ *   non-empty type that none of them matches (`type/*` wildcards included). Extensions cannot be
+ *   checked before the drop, and an empty type (".storm" has none) never forbids.
+ * - `over` otherwise.
+ */
+declare function dragVerdict(items: readonly DragItemLike[], context: DragContext): DragVerdict;
+/**
+ * A dropped file matches `accept` like `<input accept>`: an entry starting with "." matches the
+ * end of the name (case-insensitive), an entry with "/" the MIME type exactly or as `type/*`; an
+ * empty `accept` matches every file.
+ */
+declare function acceptsFile(file: {
+    name: string;
+    type: string;
+}, accept: readonly string[]): boolean;
+
+/**
+ * Every text the shell shows or announces, in one table (guide §2, shared terms). English by
+ * default; a localized modeler overrides the whole table in its language, numbers arrive already
+ * formatted through `Intl` in that language.
+ */
+interface ShellMessages {
+    /** Menu trigger `aria-label` and tooltip, dropdown `aria-label`. */
+    menu: string;
+    /** Palette `aria-label`. */
+    tools: string;
+    /** `aria-label` of the focusable canvas `<svg>` (`role="application"`); a modeler names its notation. */
+    canvas: string;
+    /** Zoom panel `aria-label`. */
+    zoom: string;
+    zoomOut: string;
+    zoomIn: string;
+    /** Tooltip of the readout, e.g. `(percent) => "Zoom to " + percent` with percent "100%". */
+    zoomToActual(percent: string): string;
+    /** `aria-label` of the readout: "Zoom to 100% (now 86%)". */
+    zoomToActualNow(percent: string, now: string): string;
+    fit: string;
+    /** Legend title and the Model-group checkbox. */
+    legend: string;
+    closeLegend: string;
+    /** Pill text: "1 problem", "2 problems". */
+    problems(count: number, formattedCount: string): string;
+    /** Pill `aria-label`: "2 problems, 1 error", "2 problems, no errors". */
+    problemsLabel(count: number, errors: number, formattedCount: string, formattedErrors: string): string;
+    /** Pill tooltip in the IDE host. */
+    showProblems: string;
+    /** Empty-file hint (guide §13.5). */
+    emptyHint: string;
+    insertExample: string;
+    /** Status box for an invalid file; `diagram` names the notation ("Event Storming board"). */
+    invalidFile(diagram: string): string;
+    /** Key names in shortcut chips outside macOS (German: Strg, Umschalt, Plus, Minus). */
+    keyNames: {
+        ctrl: string;
+        shift: string;
+        plus: string;
+        minus: string;
+    };
+    /** Default label and `aria-label` of the primary action (web app, top right). */
+    share: string;
+    /** `aria-label` of the legal line's `<nav>`. "Impressum" and "Datenschutz" are never translated (guide §2). */
+    legal: string;
+    /** First entry of the legal line, linking the Miragon home page: "© 2026 Miragon GmbH". */
+    copyright(year: number): string;
+    /** The description of every legal link for screen readers: they open in a new tab. */
+    opensInNewTab: string;
+    /** File group (web app) and the empty state's primary button. */
+    newDiagram: string;
+    /** File group: "Open…" (U+2026, it opens the browser's file dialog). */
+    openFile: string;
+    /** File group and the empty state's ghost button. */
+    showExample: string;
+    /** File group: "Import…". */
+    importFile: string;
+    /** Heading and `aria-label` of the Appearance radio group (web app with dark only, guide §13.3). */
+    appearance: string;
+    appearanceSystem: string;
+    appearanceLight: string;
+    appearanceDark: string;
+    /** Title of the problems popover (web app). */
+    problemsTitle: string;
+    /** A row's severity for screen readers, the `aria-label` of its icon: "Error", "Warning". */
+    problemSeverity(severity: ProblemSeverity): string;
+    /** `aria-label` of a Close button (toasts). */
+    close: string;
+    /** Chip of the drop zone while a drag can be dropped (guide §9 Drag-over). */
+    dropFile: string;
+    /** Chip of the drop zone while the drag cannot be dropped (guide §9 Drop forbidden). */
+    dropForbidden(reason: DropForbiddenReason): string;
+    /** The empty state's drag-and-drop hint when the modeler has a drop zone. */
+    dropHint: string;
+    /** The text link after the empty state's hint that runs the File group's "Open…". */
+    openFileLink: string;
+    /**
+     * Danger toast for a dropped file outside `DropZoneOptions.accept`; `accepted` is the accept list
+     * joined by `Intl.ListFormat` (disjunction) in `lang`: ".storm, .json, or .txt".
+     */
+    cannotOpenFile(name: string, accepted: string): string;
+}
+/** Every key optional; an `undefined` value keeps the default (a conditional override). */
+type ShellMessageOverrides = {
+    [Key in Exclude<keyof ShellMessages, "keyNames">]?: ShellMessages[Key] | undefined;
+} & {
+    keyNames?: {
+        [Key in keyof ShellMessages["keyNames"]]?: string | undefined;
+    } | undefined;
+};
+declare const defaultMessages: ShellMessages;
+/** `defaultMessages` with `overrides` applied (`keyNames` merged key by key). */
+declare function resolveMessages(overrides?: ShellMessageOverrides | undefined): ShellMessages;
+
+/** The only keys the chrome handles (guide §5.8). */
+type ChromeKey = "zoomIn" | "zoomOut" | "zoomToActual" | "fit";
+/** The `KeyboardEvent` fields the keymap reads. */
+interface KeyLike {
+    key: string;
+    code: string;
+    metaKey: boolean;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+    isComposing?: boolean | undefined;
+}
+/**
+ * Which chrome key `event` is, ignoring where it was pressed:
+ * - `zoomIn`: Cmd/Ctrl + `+` or `=` (by `key`, with or without Shift), or `NumpadAdd` (by `code`);
+ * - `zoomOut`: Cmd/Ctrl + `-` or `_`, or `NumpadSubtract`;
+ * - `zoomToActual`: Cmd/Ctrl + `0`, or `Numpad0` (also with NumLock off);
+ * - `fit`: Shift + `Digit1` (by `code`, every layout) without Cmd, Ctrl or Alt.
+ * Cmd/Ctrl is `metaKey || ctrlKey` on every platform; nothing matches with `altKey` (AltGr).
+ */
+declare function matchChromeKey(event: KeyLike): ChromeKey | undefined;
+/**
+ * Cmd/Ctrl + Z, Cmd/Ctrl + Shift + Z or Cmd/Ctrl + Y, without Alt (by `key`, `code` as fallback).
+ * Cmd/Ctrl + Shift + Y is not redo (VS Code toggles its Debug Console with it).
+ */
+declare function isUndoRedoKey(event: KeyLike): boolean;
+/** A text field: every input, select list and editable text (label editor, inspector, dialogs). */
+declare const TEXT_FIELD_SELECTOR = "input, textarea, select, [contenteditable]:not([contenteditable='false'])";
+/** Where a key was pressed, as the shell's one `keydown` listener sees it. */
+interface KeyContext {
+    host: ShellHost;
+    /** The event target matches `TEXT_FIELD_SELECTOR` or is `isContentEditable`. */
+    inTextField: boolean;
+    /** The shell's menu dropdown is open. */
+    menuOpen: boolean;
+    /** A popover or dialog (`[role="dialog"]`, modal or not) is open. */
+    dialogOpen: boolean;
+    /** A modal dialog (`[role="dialog"][aria-modal="true"]`) is open: chrome keys do not act. */
+    modalOpen: boolean;
+    /** `event.defaultPrevented` when the listener ran: the canvas (or the modeler) handled the key. */
+    defaultPrevented: boolean;
+    /**
+     * The web app's start screen shows (`setEmptyState(true)`): there is no diagram to zoom, so the
+     * zoom keys and Shift+1 are left to the browser, which zooms the page.
+     */
+    startScreen?: boolean | undefined;
+}
+type KeyAction = ChromeKey | "closeMenu";
+interface KeyDecision {
+    /** What the shell executes; `undefined` = nothing. */
+    action?: KeyAction;
+    preventDefault: boolean;
+    stopPropagation: boolean;
+}
+/**
+ * The key rules of guide §5.8 and §13.5 in one place:
+ * 1. Escape with the menu open: `closeMenu`, prevented; in the IDE host stopped whenever the menu
+ *    or a dialog/popover is open. During IME composition Escape belongs to the IME: no `closeMenu`.
+ * 2. Zoom keys: executed and prevented unless composing, in a text field or with a modal dialog;
+ *    in the IDE host always stopped, also when not executed (VS Code must never zoom the window).
+ *    Behind the web app's start screen untouched: the browser zooms the page (WCAG 1.4.4).
+ * 3. Shift+1: `fit` under the same conditions; otherwise untouched (it types "!").
+ * 4. IDE host, text field, undo/redo key: stopped only (the field keeps its native undo).
+ * 5. IDE host, `defaultPrevented`: stopped (the canvas handled it; VS Code must not run it again).
+ * Everything else passes untouched. `stopPropagation` is only ever true in the IDE host.
+ */
+declare function decideKey(event: KeyLike, context: KeyContext): KeyDecision;
+/** The keyboard the user sits at; decides the shortcut labels (guide §5.8). */
+type Platform = "mac" | "other";
+/** The `navigator` fields `detectPlatform` reads. */
+interface NavigatorLike {
+    platform?: string | undefined;
+    userAgentData?: {
+        platform?: string | undefined;
+    } | undefined;
+}
+/**
+ * `mac` when `userAgentData.platform ?? platform` matches `/mac/i`, else `other`; `other` without a
+ * navigator. Read it in the webview or page itself, never from the extension host (VS Code Remote).
+ */
+declare function detectPlatform(navigator?: NavigatorLike | undefined): Platform;
+/**
+ * The tooltip chip text: macOS `⌘+`, `⌘−` (U+2212), `⌘0`, `⇧1`; elsewhere `Ctrl+Plus`,
+ * `Ctrl+Minus`, `Ctrl+0`, `Shift+1` with the key names of the messages table.
+ */
+declare function shortcutLabel(key: ChromeKey, platform: Platform, keyNames: ShellMessages["keyNames"]): string;
+/**
+ * The chip of a Cmd/Ctrl key a modeler binds itself (the web app's File entries, guide §5.4): macOS
+ * `⌘O`, elsewhere `Ctrl+O` with the key name of the messages table (`Strg+O`). `key` as printed on
+ * the key cap; pass the result to `FileMenuAction.shortcut` or `MenuActionEntry.shortcut`.
+ */
+declare function commandKeyLabel(key: string, platform: Platform, keyNames: Pick<ShellMessages["keyNames"], "ctrl">): string;
+/**
+ * The `aria-keyshortcuts` value (WAI-ARIA names): zoom in `Meta+= Meta+Plus`, zoom out `Meta+-`,
+ * 100 % `Meta+0`, fit `Shift+1`; outside macOS `Control` instead of `Meta`.
+ */
+declare function ariaKeyShortcuts(key: ChromeKey, platform: Platform): string;
+/**
+ * The `aria-keyshortcuts` value (WAI-ARIA names, guide §5.6) for a shortcut chip label: `"L"` →
+ * `"L"`, `"⇧L"` → `"Shift+L"`, `"⌘⇧Z"` → `"Meta+Shift+Z"`, `"Ctrl+Shift+E"` → `"Control+Shift+E"`,
+ * `"Del"` → `"Delete"`, `"Ctrl++"` → `"Control+Plus"`. `undefined` for a label that is not one key
+ * combination (`"G then D"`, `"1–9"`, empty).
+ */
+declare function ariaKeyShortcutsFromLabel(label: string): string | undefined;
+
+/** The web app's mode choice (guide §13.3): Appearance, System · Light · Dark. */
+type AppearanceChoice = "system" | "light" | "dark";
+/** Where the web app keeps the choice: `light` or `dark`; "System" removes the entry (guide §13.3). */
+declare const APPEARANCE_STORAGE_KEY = "miragon.darstellung";
+/**
+ * The two `theme-color` values (guide §11, §13.3): light is the app's own value (`#335DE5`, `fest`
+ * `--cd-blau` of the vendored `cd-tokens.generated.json`), dark `#1D1D1D` (`dunkel`
+ * `--cd-ui-grund`). The modeler reads both from its vendored JSON; the shell keeps no colour.
+ */
+interface ThemeColors {
+    light: string;
+    dark: string;
+}
+/** `"light"` and `"dark"` pass, everything else (a missing entry, a foreign value) is `"system"`. */
+declare function parseAppearanceChoice(stored: unknown): AppearanceChoice;
+/** What `<html>` and the meta tags carry for a choice. */
+interface DocumentMode {
+    /** `data-cd-theme` on `<html>`. */
+    theme: "system" | Theme;
+    /** `<meta name="color-scheme" content>`. */
+    colorScheme: "light dark" | Theme;
+    /** The `content` of the `theme-color` metas with `media="(prefers-color-scheme: light|dark)"`. */
+    themeColor: ThemeColors;
+}
+/**
+ * The document mode for `choice` (guide §13.3). A modeler that cannot show dark (`themes` without
+ * `"dark"`) is `light` whatever the choice: theme `light`, color-scheme `light`, both theme
+ * colours `colors.light`. Dark-capable: `system` → theme `system`, color-scheme `light dark`,
+ * `colors` as they are; `light`/`dark` → that theme and color-scheme, both theme colours the
+ * chosen mode's, so the browser bar matches a fixed choice under the other system mode.
+ */
+declare function documentMode(choice: AppearanceChoice, themes: readonly Theme[], colors: ThemeColors): DocumentMode;
+interface WebModeScriptOptions {
+    /** The modes the modeler can show, as passed to `mountShell`. */
+    themes: readonly Theme[];
+    themeColors: ThemeColors;
+}
+/**
+ * The body of the inline `<script>` in `<head>`, before the first stylesheet (guide §13.3). With
+ * `themes` including `"dark"`: the guide's script, which reads `APPEARANCE_STORAGE_KEY` inside
+ * `try`/`catch`, writes `data-cd-theme`, `color-scheme` and both `theme-color` metas for a fixed
+ * choice and sets `data-cd-kontrast="hoch"` under `(prefers-contrast: more)`. Light-only: the
+ * contrast line alone. Plain ES5 without the modeler's bundle, so it runs before the first paint.
+ */
+declare function webModeScript(options: WebModeScriptOptions): string;
+/**
+ * The `<head>` markup the web app's `index.html` carries for its mode, as one string (for a Vite
+ * `transformIndexHtml` hook or to paste): dark-capable `<meta name="color-scheme" content="light
+ * dark">`, two `theme-color` metas with `media` and the script; light-only one `theme-color`
+ * without `media` and the contrast script. `<html>` itself carries `lang` and
+ * `data-cd-theme="<documentMode("system", themes, colors).theme>"` statically.
+ */
+declare function webHeadMarkup(options: WebModeScriptOptions): string;
+
+export { APPEARANCE_STORAGE_KEY as A, shortcutLabel as B, type ChromeKey as C, type DocumentMode as D, webHeadMarkup as E, webModeScript as F, type KeyAction as K, type NavigatorLike as N, type Platform as P, type ShellMessageOverrides as S, TEXT_FIELD_SELECTOR as T, type WebModeScriptOptions as W, type AppearanceChoice as a, type DragContext as b, type DragItemLike as c, type DragVerdict as d, type DropForbiddenReason as e, type KeyContext as f, type KeyDecision as g, type KeyLike as h, type ProblemItem as i, type ProblemSeverity as j, type ShellMessages as k, type ThemeColors as l, acceptsFile as m, ariaKeyShortcuts as n, ariaKeyShortcutsFromLabel as o, commandKeyLabel as p, decideKey as q, defaultMessages as r, detectPlatform as s, documentMode as t, dragVerdict as u, isUndoRedoKey as v, matchChromeKey as w, parseAppearanceChoice as x, problemSummary as y, resolveMessages as z };