@miragon/modeler-shell 0.0.0-stage → 0.2.0

package/src/dom/web/empty-state.ts

@@ -0,0 +1,144 @@
+import { ariaKeyShortcutsFromLabel, type ShellMessages } from "../../core/index.js";
+import { createElement } from "../element.js";
+import type { EmptyStateOptions, FileMenuAction } from "../types.js";
+
+export interface EmptyStateContext {
+  ownerDocument: Document;
+  messages: ShellMessages;
+  options: EmptyStateOptions;
+  /** The drop hint under the buttons; `undefined` without a drop zone. */
+  dropHint: string | undefined;
+  /**
+   * The File group's "Open…": the hint offers it as a text link, the keyboard's way to a file
+   * while the start screen hides the menu and a drop needs a pointer. `undefined` without one.
+   */
+  open?: FileMenuAction | undefined;
+  /** `id` of the title, the section's `aria-labelledby`. */
+  titleId: string;
+  /** Runs before `onNewDiagram` / `onShowExample`: the shell hides the card and moves the focus. */
+  onLeave(): void;
+}
+
+export interface EmptyStateController {
+  /** The `<section data-chrome="empty-state">`. */
+  readonly element: HTMLElement;
+  isShown(): boolean;
+  setShown(shown: boolean): void;
+  /** Focuses "New diagram", the card's first button. */
+  focus(): void;
+  destroy(): void;
+}
+
+/** The Komet's size on the card (guide §8). */
+const KOMET_SIZE = "64";
+
+/**
+ * `<section class="cd-shell-empty-state" data-chrome="empty-state" aria-labelledby>` (guide §8):
+ * centred in the container, `min(400px, 100cqw − 24px)` wide, glass, `shadow-2`, radius `lg`,
+ * padding `32px 40px`, content centred with 16px gaps: `<img src=komet width=64 height=64
+ * alt="">`, `<h1>` title 21px/600, help 16px/1.6 `--cd-ui-text-leise`, then the buttons side by
+ * side with 8px gap, 36px high (`cd-shell-button`): primary "New diagram" first, ghost "Show
+ * example", then the drop hint 13px `--cd-ui-text-leise`. With the File group's "Open…" the hint
+ * ends in a text link `messages.openFileLink` in `--cd-ui-link` (and its shortcut chip in Geist
+ * Mono): not a third action, the keyboard's way to open a file. Opening keeps the card until the
+ * modeler leaves it (`setEmptyState(false)` after the file loaded). Layer 20, `hidden` until
+ * `setShown(true)`.
+ */
+export function createEmptyState(context: EmptyStateContext): EmptyStateController {
+  const { ownerDocument, messages, options, dropHint, open, titleId, onLeave } = context;
+
+  const button = (variant: "primary" | "ghost", label: string, run: () => void): HTMLButtonElement => {
+    const element = createElement(
+      ownerDocument,
+      "button",
+      { type: "button", class: "cd-shell-button", "data-variant": variant },
+      label,
+    );
+    element.addEventListener("click", () => {
+      onLeave();
+      run();
+    });
+    return element;
+  };
+
+  const onShowExample = options.onShowExample;
+  const newDiagram = button("primary", messages.newDiagram, () => options.onNewDiagram());
+  const element = createElement(
+    ownerDocument,
+    "section",
+    { class: "cd-shell-empty-state", "data-chrome": "empty-state", "aria-labelledby": titleId },
+    // Dragging the mark would start an image drag that some browsers carry as a file.
+    createElement(ownerDocument, "img", {
+      class: "cd-shell-empty-state-mark",
+      src: options.komet,
+      width: KOMET_SIZE,
+      height: KOMET_SIZE,
+      alt: "",
+      draggable: "false",
+    }),
+    createElement(ownerDocument, "h1", { class: "cd-shell-empty-state-title", id: titleId }, options.title),
+    createElement(ownerDocument, "p", { class: "cd-shell-empty-state-text" }, options.text),
+    createElement(
+      ownerDocument,
+      "div",
+      { class: "cd-shell-empty-state-actions" },
+      newDiagram,
+      onShowExample && button("ghost", messages.showExample, () => onShowExample()),
+    ),
+    hintParagraph(),
+  );
+
+  function hintParagraph(): HTMLElement | undefined {
+    const hasDropHint = dropHint !== undefined && dropHint !== "";
+    if (!hasDropHint && !open) return undefined;
+    const paragraph = createElement(ownerDocument, "p", { class: "cd-shell-empty-state-hint" });
+    if (hasDropHint) paragraph.append(dropHint);
+    if (!open) return paragraph;
+    const shortcut = open.shortcut?.trim();
+    const link = createElement(
+      ownerDocument,
+      "button",
+      {
+        type: "button",
+        class: "cd-shell-empty-state-open",
+        "aria-keyshortcuts": shortcut ? ariaKeyShortcutsFromLabel(shortcut) : undefined,
+        "aria-haspopup": open.dialog ? "dialog" : undefined,
+      },
+      messages.openFileLink,
+    );
+    link.addEventListener("click", () => open.onSelect());
+    if (hasDropHint) {
+      paragraph.append(" ", createElement(ownerDocument, "span", { "aria-hidden": "true" }, "·"), " ");
+    }
+    // The link and its chip wrap as one: a chip alone on a line names no action.
+    const openItem = createElement(ownerDocument, "span", { class: "cd-shell-empty-state-open-item" }, link);
+    if (shortcut) {
+      openItem.append(
+        " ",
+        createElement(
+          ownerDocument,
+          "kbd",
+          { class: "cd-shell-empty-state-key", "aria-hidden": "true" },
+          shortcut,
+        ),
+      );
+    }
+    paragraph.append(openItem);
+    return paragraph;
+  }
+  element.hidden = true;
+
+  return {
+    element,
+    isShown: () => !element.hidden,
+    setShown(shown) {
+      element.hidden = !shown;
+    },
+    focus() {
+      newDiagram.focus({ preventScroll: true });
+    },
+    destroy() {
+      element.remove();
+    },
+  };
+}

package/src/dom/web/legal.ts

@@ -0,0 +1,75 @@
+import type { ShellMessages } from "../../core/index.js";
+import { createElement } from "../element.js";
+import type { LegalLineOptions } from "../types.js";
+
+/** The Miragon legal pages (corporate-identity, skill docs-site, `miragon/legal.ts`). */
+export const MIRAGON_HOME = "https://www.miragon.io/";
+export const MIRAGON_IMPRESSUM = "https://www.miragon.io/impressum/";
+export const MIRAGON_DATENSCHUTZ = "https://www.miragon.io/datenschutz/";
+
+export interface LegalLineContext {
+  ownerDocument: Document;
+  messages: ShellMessages;
+  options: LegalLineOptions;
+  /** `cd-shell-legal-N`: the prefix of the id the links' `aria-describedby` names. */
+  idPrefix: string;
+}
+
+export interface LegalLineController {
+  /** The `<nav data-chrome="legal">`. */
+  readonly element: HTMLElement;
+  destroy(): void;
+}
+
+/**
+ * `<nav class="cd-shell-legal" data-chrome="legal" aria-label="Legal">` (guide §5.10, §2): one
+ * line, 13px, line height 20px, at `left: 12px; bottom: 12px`, glass without border and shadow,
+ * padding `0 8px`, radius `sm`, layer 20; in a container too narrow for it, it wraps between its
+ * entries and grows upwards. Links in `--cd-ui-link`, `target="_blank" rel="noopener noreferrer"`
+ * and `aria-describedby` a hidden `messages.opensInNewTab`, each after the first in a
+ * `<span class="cd-shell-legal-item">` with its separator `<span aria-hidden="true">·</span>`:
+ * `messages.copyright(year)` → `MIRAGON_HOME`, "Impressum" → `MIRAGON_IMPRESSUM` and "Datenschutz"
+ * → `MIRAGON_DATENSCHUTZ` (both `lang="de"`, never translated), then `options.links`.
+ */
+export function createLegalLine(context: LegalLineContext): LegalLineController {
+  const { ownerDocument, messages, options } = context;
+  const year = options.year ?? new Date().getFullYear();
+
+  // Every link opens a new tab; screen readers hear that from one shared description.
+  const newTabId = `${context.idPrefix}-new-tab`;
+  const link = (label: string, href: string, lang?: string): HTMLAnchorElement =>
+    createElement(
+      ownerDocument,
+      "a",
+      { href, lang, target: "_blank", rel: "noopener noreferrer", "aria-describedby": newTabId },
+      label,
+    );
+  const separator = (): HTMLElement => createElement(ownerDocument, "span", { "aria-hidden": "true" }, "·");
+  const item = (anchor: HTMLAnchorElement): HTMLElement =>
+    createElement(ownerDocument, "span", { class: "cd-shell-legal-item" }, separator(), anchor);
+
+  // The legal pages are German whatever the tool's language (guide §2), so their names are too.
+  const links = [
+    link(messages.copyright(year), MIRAGON_HOME),
+    link("Impressum", MIRAGON_IMPRESSUM, "de"),
+    link("Datenschutz", MIRAGON_DATENSCHUTZ, "de"),
+    ...(options.links ?? []).map((extra) => link(extra.label, extra.href, extra.lang)),
+  ];
+
+  const element = createElement(ownerDocument, "nav", {
+    class: "cd-shell-legal",
+    "data-chrome": "legal",
+    "aria-label": messages.legal,
+  });
+  element.append(
+    ...links.map((anchor, index) => (index === 0 ? anchor : item(anchor))),
+    createElement(ownerDocument, "span", { id: newTabId, hidden: "" }, messages.opensInNewTab),
+  );
+
+  return {
+    element,
+    destroy() {
+      element.remove();
+    },
+  };
+}

package/src/dom/web/menu-groups.ts

@@ -0,0 +1,69 @@
+import { parseAppearanceChoice, type ShellMessages } from "../../core/index.js";
+import type { ShellIconName } from "../icons.js";
+import type { AppearanceHandle, FileMenuAction, FileMenuOptions, MenuEntry } from "../types.js";
+
+interface FileEntrySpec {
+  option: keyof FileMenuOptions;
+  id: string;
+  label: string;
+  icon: ShellIconName | undefined;
+}
+
+function fileEntry(spec: FileEntrySpec, action: FileMenuAction): MenuEntry {
+  const common = {
+    id: spec.id,
+    label: spec.label,
+    ...(spec.icon ? { icon: spec.icon } : {}),
+    ...(action.disabled ? { disabled: action.disabled } : {}),
+    ...(action.shortcut ? { shortcut: action.shortcut } : {}),
+    onSelect: () => action.onSelect(),
+  };
+  return action.dialog ? { kind: "dialog", ...common } : { kind: "action", ...common };
+}
+
+/**
+ * The File group (guide §5.4, §2), first in the menu: "New diagram" (`file-plus`, id
+ * `new-diagram`), "Open…" (`folder-open`, `open`), "Show example" (no icon, `show-example`),
+ * "Import…" (`import`, `import`), in this order and only those `options` gives. `action` entries
+ * (`dialog` with `FileMenuAction.dialog`) with the action's `shortcut` and `disabled`. Never
+ * locked on a read-only canvas.
+ */
+export function fileMenuEntries(options: FileMenuOptions, messages: ShellMessages): readonly MenuEntry[] {
+  const specs: readonly FileEntrySpec[] = [
+    { option: "newDiagram", id: "new-diagram", label: messages.newDiagram, icon: "file-plus" },
+    { option: "open", id: "open", label: messages.openFile, icon: "folder-open" },
+    // §5.14 gives "Show example" no icon.
+    { option: "showExample", id: "show-example", label: messages.showExample, icon: undefined },
+    { option: "import", id: "import", label: messages.importFile, icon: "import" },
+  ];
+  return specs.flatMap((spec) => {
+    const action = options[spec.option];
+    return action ? [fileEntry(spec, action)] : [];
+  });
+}
+
+/**
+ * The Appearance group (guide §5.4, §13.3) between Export and Help: one radio group, id
+ * `appearance`, label `messages.appearance`, options `system`, `light`, `dark` labelled
+ * `messages.appearanceSystem` / `Light` / `Dark`, value `appearance.choice()`, selecting calls
+ * `appearance.setChoice`. Never locked. The shell asks for it only when `themes` includes `"dark"`.
+ */
+export function appearanceMenuEntries(
+  appearance: AppearanceHandle,
+  messages: ShellMessages,
+): readonly MenuEntry[] {
+  return [
+    {
+      kind: "radio",
+      id: "appearance",
+      label: messages.appearance,
+      options: [
+        { value: "system", label: messages.appearanceSystem },
+        { value: "light", label: messages.appearanceLight },
+        { value: "dark", label: messages.appearanceDark },
+      ],
+      value: () => appearance.choice(),
+      onSelect: (value) => appearance.setChoice(parseAppearanceChoice(value)),
+    },
+  ];
+}

package/src/dom/web/primary.ts

@@ -0,0 +1,124 @@
+import { SHELL, type PrimaryWidths, type ShellMessages } from "../../core/index.js";
+import { createElement, toggleAttribute } from "../element.js";
+import { iconElement } from "../icons.js";
+import type { TooltipController } from "../tooltip.js";
+import type { PrimaryActionHandle, PrimaryActionOptions } from "../types.js";
+
+export interface PrimaryActionContext {
+  ownerDocument: Document;
+  messages: ShellMessages;
+  tooltip: TooltipController;
+  options: PrimaryActionOptions;
+}
+
+export interface PrimaryActionController extends PrimaryActionHandle {
+  /**
+   * Border-box widths with and without the label for `decideTopRow`, measured also while the label
+   * is collapsed (the label's width does not change with the state), cached until `refresh()`.
+   */
+  widths(): PrimaryWidths;
+  /** Icon only (`true`) or icon and label; the `aria-label` stays, the tooltip shows only while collapsed. */
+  setCollapsed(collapsed: boolean): void;
+  destroy(): void;
+}
+
+/** On the button while it shows its icon only: the stylesheet's 40 × 40 (the root mirrors it as `data-primary`). */
+const COLLAPSED_ATTRIBUTE = "data-collapsed";
+
+/**
+ * `<button type="button" class="cd-shell-primary cd-shell-button" data-variant="primary"
+ * data-chrome="primary" aria-label="Share">` with the 16px icon and `<span
+ * class="cd-shell-primary-label">` (guide §5.7): 40px high at `top: 12px; right: 12px`, layer 30,
+ * blue (`dom/buttons.css`), hover lift. Collapsed: 40 × 40, label hidden, chrome tooltip with the
+ * label (no `aria-describedby`, it repeats the name). `disabled()` → `aria-disabled`, no action.
+ */
+export function createPrimaryAction(context: PrimaryActionContext): PrimaryActionController {
+  const { ownerDocument, messages, tooltip, options } = context;
+  const label = options.label ?? messages.share;
+  const labelElement = createElement(ownerDocument, "span", { class: "cd-shell-primary-label" }, label);
+  const element = createElement(
+    ownerDocument,
+    "button",
+    {
+      type: "button",
+      class: "cd-shell-primary cd-shell-button",
+      "data-variant": "primary",
+      "data-chrome": "primary",
+      "aria-label": label,
+    },
+    iconElement(options.icon ?? "share-2"),
+    labelElement,
+  );
+
+  let collapsed = false;
+  let disabled = false;
+  let labelledWidth: number | undefined;
+
+  function readDisabled(): void {
+    disabled = options.disabled?.() ?? false;
+    toggleAttribute(element, "aria-disabled", disabled ? "true" : null);
+  }
+
+  function showCollapsed(state: boolean): void {
+    labelElement.hidden = state;
+    toggleAttribute(element, COLLAPSED_ATTRIBUTE, state ? "" : null);
+  }
+
+  /** The labelled width; while collapsed the label shows for one synchronous layout, never painted. */
+  function measureLabelledWidth(): number {
+    if (!collapsed) return element.offsetWidth;
+    showCollapsed(false);
+    const width = element.offsetWidth;
+    showCollapsed(true);
+    return width;
+  }
+
+  function isEngaged(): boolean {
+    if (ownerDocument.activeElement === element) return true;
+    try {
+      return element.matches(":hover");
+    } catch {
+      return false;
+    }
+  }
+
+  const onClick = (event: MouseEvent): void => {
+    if (disabled) {
+      event.preventDefault();
+      return;
+    }
+    options.onSelect();
+  };
+  element.addEventListener("click", onClick);
+  const detachTooltip = tooltip.attach(element, () => (collapsed ? { label } : null));
+  readDisabled();
+
+  return {
+    element,
+    isCollapsed: () => collapsed,
+    refresh() {
+      readDisabled();
+      labelledWidth = undefined;
+    },
+    widths() {
+      // Measured fresh while the label shows (a late web font widens it), from the cache while collapsed.
+      if (!collapsed || labelledWidth === undefined) {
+        const measured = measureLabelledWidth();
+        if (measured > 0) labelledWidth = measured;
+      }
+      return { withLabel: labelledWidth ?? 0, iconOnly: SHELL.row };
+    },
+    setCollapsed(next) {
+      if (next === collapsed) return;
+      collapsed = next;
+      showCollapsed(next);
+      // An expanded button names itself; a tooltip still showing for it would only repeat the label.
+      if (!next && isEngaged()) tooltip.hide();
+    },
+    destroy() {
+      detachTooltip();
+      element.removeEventListener("click", onClick);
+      element.remove();
+    },
+  };
+}