@miragon/modeler-shell 0.0.0-stage → 0.2.0

package/src/dom/element.ts

@@ -0,0 +1,51 @@
+type Child = Node | string | undefined | null | false;
+
+/** `document.createElement` with attributes and children; `undefined` attribute values are skipped. */
+export function createElement<K extends keyof HTMLElementTagNameMap>(
+  ownerDocument: Document,
+  tag: K,
+  attributes: Readonly<Record<string, string | undefined>> = {},
+  ...children: Child[]
+): HTMLElementTagNameMap[K] {
+  const element = ownerDocument.createElement(tag);
+  for (const [name, value] of Object.entries(attributes)) {
+    if (value !== undefined) element.setAttribute(name, value);
+  }
+  for (const child of children) {
+    if (child === undefined || child === null || child === false) continue;
+    element.append(child);
+  }
+  return element;
+}
+
+/** Sets an attribute, or removes it for `null`/`false`. */
+export function toggleAttribute(element: Element, name: string, value: string | null | false): void {
+  if (value === null || value === false) element.removeAttribute(name);
+  else element.setAttribute(name, value);
+}
+
+/** The element's box relative to the padding box of `root` (the containing block of the islands). */
+export function boxRelativeTo(element: Element, root: HTMLElement) {
+  const box = element.getBoundingClientRect();
+  const origin = root.getBoundingClientRect();
+  return {
+    x: box.left - origin.left - root.clientLeft,
+    y: box.top - origin.top - root.clientTop,
+    width: box.width,
+    height: box.height,
+  };
+}
+
+/** The accessible name a control shows without its tooltip: `aria-label`, else its text. */
+export function accessibleName(control: Element): string {
+  return (control.getAttribute("aria-label") ?? control.textContent ?? "").trim();
+}
+
+/** True for keyboard focus (`:focus-visible`); engines without the selector count every focus. */
+export function hasVisibleFocus(element: Element): boolean {
+  try {
+    return element.matches(":focus-visible");
+  } catch {
+    return true;
+  }
+}

package/src/dom/feedback/appearance.ts

@@ -0,0 +1,184 @@
+import {
+  APPEARANCE_STORAGE_KEY,
+  documentMode,
+  parseAppearanceChoice,
+  type AppearanceChoice,
+  type Theme,
+} from "../../core/index.js";
+import { createElement, toggleAttribute } from "../element.js";
+import type { AppearanceHandle, StorageLike, WebAppearanceOptions } from "../types.js";
+
+export interface WebAppearanceContext {
+  ownerDocument: Document;
+  themes: readonly Theme[];
+  /** Required when `themes` includes `"dark"`; read only then. */
+  options: WebAppearanceOptions | undefined;
+}
+
+export interface WebAppearanceController extends AppearanceHandle {
+  /** Stops following `prefers-contrast` and other tabs' `storage` events; leaves `<html>` as it is. */
+  destroy(): void;
+}
+
+/** On `<html>` for one frame of a mode switch (guide §7); shell-dom.css turns every transition off. */
+export const NO_TRANSITION_CLASS = "cd-shell-no-transition";
+
+const CONTRAST_QUERY = "(prefers-contrast: more)";
+const SCHEME_MEDIA: Readonly<Record<Theme, string>> = {
+  light: "(prefers-color-scheme: light)",
+  dark: "(prefers-color-scheme: dark)",
+};
+
+/** `change` on a media query list; Safari before 14 only has `addListener`. */
+function onMediaChange(query: MediaQueryList, listener: () => void): () => void {
+  if (typeof query.addEventListener === "function") {
+    query.addEventListener("change", listener);
+    return () => query.removeEventListener("change", listener);
+  }
+  query.addListener(listener);
+  return () => query.removeListener(listener);
+}
+
+/**
+ * The web host's mode at runtime (guide §13.3), after the head script (`webModeScript`) set it
+ * before the first paint. Always: mirrors `(prefers-contrast: more)` as `data-cd-kontrast="hoch"`
+ * on `<html>`, at once and on every change. With `"dark"` in `themes` (throws without `options`):
+ * `choice()` is the stored choice, read once through `parseAppearanceChoice` (a blocked storage
+ * reads `"system"`) and then kept by `setChoice` and other tabs' `storage` events, so a choice the
+ * storage refused still holds for the page. `setChoice` writes it (`"system"` removes the key; a
+ * throwing storage is ignored) and applies `documentMode` on `<html data-cd-theme>`,
+ * `<meta name="color-scheme">` and both `theme-color` metas (created where missing) in one task,
+ * with `cd-shell-no-transition` on `<html>` until a nested `requestAnimationFrame`; a `storage`
+ * event for the key applies the same way. Light-only: `choice()` is `"system"`, `setChoice` does
+ * nothing.
+ */
+export function connectWebAppearance(context: WebAppearanceContext): WebAppearanceController {
+  const { ownerDocument, themes, options } = context;
+  const darkCapable = themes.includes("dark");
+  if (darkCapable && !options) {
+    throw new Error(
+      '@miragon/modeler-shell: a web modeler whose themes include "dark" needs the appearance option ' +
+        "({ themeColors } from its vendored cd-tokens.generated.json)",
+    );
+  }
+  const html = ownerDocument.documentElement;
+  const view = ownerDocument.defaultView;
+  const cleanups: (() => void)[] = [];
+
+  const contrast = typeof view?.matchMedia === "function" ? view.matchMedia(CONTRAST_QUERY) : undefined;
+  if (contrast) {
+    const mirrorContrast = (): void => toggleAttribute(html, "data-cd-kontrast", contrast.matches && "hoch");
+    mirrorContrast();
+    cleanups.push(onMediaChange(contrast, mirrorContrast));
+  }
+
+  function destroy(): void {
+    for (const cleanup of cleanups.splice(0)) cleanup();
+  }
+
+  if (!darkCapable || !options) {
+    return { choice: () => "system", setChoice() {}, destroy };
+  }
+  const { themeColors } = options;
+
+  function storage(): StorageLike | undefined {
+    if (options?.storage) return options.storage;
+    try {
+      return globalThis.localStorage;
+    } catch {
+      return undefined;
+    }
+  }
+
+  function readStored(): AppearanceChoice {
+    try {
+      return parseAppearanceChoice(storage()?.getItem(APPEARANCE_STORAGE_KEY));
+    } catch {
+      return "system";
+    }
+  }
+
+  function store(choice: AppearanceChoice): void {
+    try {
+      const target = storage();
+      if (choice === "system") target?.removeItem(APPEARANCE_STORAGE_KEY);
+      else target?.setItem(APPEARANCE_STORAGE_KEY, choice);
+    } catch {
+      // Blocked or full: the choice still applies for this page.
+    }
+  }
+
+  function nextFrame(callback: () => void): () => void {
+    if (view && typeof view.requestAnimationFrame === "function") {
+      const frame = view.requestAnimationFrame(() => callback());
+      return () => view.cancelAnimationFrame(frame);
+    }
+    const timer = setTimeout(callback, 16);
+    return () => clearTimeout(timer);
+  }
+
+  let cancelTransitionFrame: (() => void) | undefined;
+  function allowTransitions(): void {
+    cancelTransitionFrame?.();
+    cancelTransitionFrame = undefined;
+    html.classList.remove(NO_TRANSITION_CLASS);
+  }
+  cleanups.push(() => {
+    if (cancelTransitionFrame) allowTransitions();
+  });
+
+  // The first frame still computes styles with the new colours; only after it may they fade again.
+  function suspendTransitions(): void {
+    cancelTransitionFrame?.();
+    html.classList.add(NO_TRANSITION_CLASS);
+    cancelTransitionFrame = nextFrame(() => {
+      cancelTransitionFrame = nextFrame(allowTransitions);
+    });
+  }
+
+  function metaFor(name: string, media?: string): HTMLMetaElement {
+    const normalize = (value: string | null): string => (value ?? "").replace(/\s+/g, "").toLowerCase();
+    const existing = [...ownerDocument.querySelectorAll<HTMLMetaElement>(`meta[name="${name}"]`)].find(
+      (meta) => (media === undefined ? true : normalize(meta.getAttribute("media")) === normalize(media)),
+    );
+    if (existing) return existing;
+    const created = createElement(ownerDocument, "meta", { name, media });
+    (ownerDocument.head ?? html).append(created);
+    return created;
+  }
+
+  function apply(choice: AppearanceChoice): void {
+    const mode = documentMode(choice, themes, themeColors);
+    suspendTransitions();
+    html.setAttribute("data-cd-theme", mode.theme);
+    metaFor("color-scheme").setAttribute("content", mode.colorScheme);
+    metaFor("theme-color", SCHEME_MEDIA.light).setAttribute("content", mode.themeColor.light);
+    metaFor("theme-color", SCHEME_MEDIA.dark).setAttribute("content", mode.themeColor.dark);
+  }
+
+  let current = readStored();
+
+  const onStorage = (event: StorageEvent): void => {
+    // A null key is a clear() of the whole storage: the choice is gone, so "system".
+    if (event.key !== null && event.key !== APPEARANCE_STORAGE_KEY) return;
+    const next = event.key === null ? "system" : parseAppearanceChoice(event.newValue);
+    if (next === current) return;
+    current = next;
+    apply(next);
+  };
+  if (view) {
+    view.addEventListener("storage", onStorage);
+    cleanups.push(() => view.removeEventListener("storage", onStorage));
+  }
+
+  return {
+    choice: () => current,
+    setChoice(choice) {
+      const next = parseAppearanceChoice(choice);
+      current = next;
+      store(next);
+      apply(next);
+    },
+    destroy,
+  };
+}

package/src/dom/feedback/feedback.css

@@ -0,0 +1,435 @@
+/*
+ * Feedback of @miragon/modeler-shell (owned by src/dom/feedback): the toast stack and the problems
+ * popover (guide §5.10, §8, §9). Colours only from var(--cd-ui-*), sizes from var(--cd-shell-*).
+ * Toasts render in the web and embedded hosts, so their rules also reset what a foreign page's
+ * element rules would set (font, colour, letter spacing, text transform), like shell-dom.css.
+ * The toast action is a .cd-shell-button (buttons.css), which resets itself and is left out here.
+ * Private helper properties are named --modeler-shell-*, never --cd-*.
+ */
+
+/* ---- Foreign-page reset --------------------------------------------------------------------- */
+
+:where(.cd-shell)
+  :is(
+    .cd-shell-toasts,
+    .cd-shell-toast,
+    .cd-shell-toast-text,
+    .cd-shell-toast-close,
+    .cd-shell-problems-popover,
+    .cd-shell-problems-popover-title,
+    .cd-shell-problems-list,
+    .cd-shell-problem,
+    .cd-shell-problem-message,
+    .cd-shell-problem-location
+  ) {
+  color: inherit;
+  font: inherit;
+  letter-spacing: normal;
+  word-spacing: normal;
+  text-transform: none;
+  text-indent: 0;
+  text-shadow: none;
+}
+
+/* ---- Toast stack (guide §8, §9) ------------------------------------------------------------- */
+
+/*
+ * Centred column at the bottom; the script sets `bottom` (toastStackBottom). In the web host it is
+ * a manual popover in the top layer, so the UA's popover box (fixed, centred, bordered, padded,
+ * Canvas colours) is reset; in the embedded host it is absolute in the root at layer 60.
+ */
+.cd-shell-toasts {
+  position: absolute;
+  top: auto;
+  right: 0;
+  bottom: var(--cd-shell-rand);
+  left: 0;
+  z-index: var(--cd-shell-ebene-toast);
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--cd-shell-luecke);
+  width: min(480px, 100cqw - 2 * var(--cd-shell-rand));
+  height: auto;
+  min-height: 0;
+  max-height: none;
+  margin: 0 auto;
+  padding: 0;
+  overflow: visible;
+  color: var(--cd-ui-text);
+  background: transparent;
+  border: 0;
+  pointer-events: none;
+}
+
+/* Always in the DOM, no box while empty (data-chrome="toasts" measures nothing then). */
+.cd-shell-toasts:empty {
+  display: none;
+}
+
+/* The author display above would otherwise show a closed popover; engines without it drop the rule. */
+.cd-shell-toasts[popover]:not(:popover-open) {
+  display: none;
+}
+
+.cd-shell-toast {
+  --modeler-shell-toast-status: var(--cd-ui-info);
+  position: relative;
+  box-sizing: border-box;
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: var(--cd-shell-luecke);
+  max-width: 100%;
+  min-height: var(--cd-shell-zeile);
+  margin: 0;
+  padding: 4px 4px 4px 16px;
+  overflow: hidden;
+  color: var(--cd-ui-text);
+  font-size: 13px;
+  font-weight: 400;
+  line-height: 1.5;
+  text-align: left;
+  background: var(--cd-ui-flaeche-hoch);
+  border: 1px solid var(--cd-ui-linie);
+  border-radius: var(--cd-radius-md);
+  box-shadow: var(--cd-shadow-3);
+  pointer-events: auto;
+  user-select: none;
+  -webkit-user-select: none;
+  animation: cd-shell-toast-in var(--cd-motion-base) var(--cd-ease-out);
+}
+
+.cd-shell-toast[data-status="success"] {
+  --modeler-shell-toast-status: var(--cd-ui-success);
+}
+
+.cd-shell-toast[data-status="warning"] {
+  --modeler-shell-toast-status: var(--cd-ui-warning);
+}
+
+.cd-shell-toast[data-status="danger"] {
+  --modeler-shell-toast-status: var(--cd-ui-danger);
+}
+
+/* Its own element, clipped by the card: a border-left would follow the radius into a crescent. */
+.cd-shell-toast::before {
+  content: "";
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  width: 4px;
+  background: var(--modeler-shell-toast-status);
+}
+
+.cd-shell-toast-dot {
+  flex: none;
+  width: 8px;
+  height: 8px;
+  background: var(--modeler-shell-toast-status);
+  border-radius: var(--cd-radius-pill);
+}
+
+.cd-shell-toast-text {
+  flex: 1 1 auto;
+  min-width: 0;
+  margin: 0;
+  padding: 6px 0;
+  color: var(--cd-ui-text);
+  font-size: 13px;
+  line-height: 1.5;
+  overflow-wrap: anywhere;
+}
+
+/* A 32px ghost button (buttons.css), before Close. */
+.cd-shell-toast .cd-shell-toast-action {
+  height: var(--cd-shell-ziel);
+}
+
+.cd-shell-toast-close {
+  box-sizing: border-box;
+  display: inline-grid;
+  flex: none;
+  place-items: center;
+  width: var(--cd-shell-ziel);
+  height: var(--cd-shell-ziel);
+  margin: 0;
+  padding: 0;
+  color: var(--cd-ui-text);
+  background: transparent;
+  border: 0;
+  border-radius: var(--cd-radius-sm);
+  cursor: pointer;
+  transition:
+    background-color var(--cd-motion-fast) var(--cd-ease),
+    color var(--cd-motion-fast) var(--cd-ease);
+}
+
+.cd-shell-toast-close:hover {
+  color: var(--cd-ui-interaktion);
+  background: var(--cd-ui-hover);
+}
+
+.cd-shell-toast-close svg {
+  display: block;
+  flex: none;
+}
+
+.cd-shell-toast[data-leaving] {
+  pointer-events: none;
+  animation: cd-shell-toast-out var(--cd-motion-base) var(--cd-ease) forwards;
+}
+
+@keyframes cd-shell-toast-in {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+}
+
+@keyframes cd-shell-toast-out {
+  to {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+}
+
+/* The toasts' live regions: in the accessibility tree at all times, never on screen. */
+.cd-shell-live {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+  pointer-events: none;
+}
+
+/* ---- Problems popover (guide §5.10) --------------------------------------------------------- */
+
+/* Left-aligned with the pill, its bottom 8px above the pill's top: 12 + 40 + 8, web 12 + 20 + 8 + 40 + 8. */
+.cd-shell-problems-popover {
+  --modeler-shell-problems-bottom: calc(
+    var(--cd-shell-rand) + var(--cd-shell-zeile) + var(--cd-shell-luecke)
+  );
+  position: absolute;
+  left: var(--cd-shell-rand);
+  bottom: var(--modeler-shell-problems-bottom);
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  width: min(320px, 100cqw - 2 * var(--cd-shell-rand));
+  max-height: min(320px, 100cqh - var(--modeler-shell-problems-bottom) - var(--cd-shell-rand));
+  margin: 0;
+  padding: 6px;
+  color: var(--cd-ui-text);
+  font-size: 13px;
+  font-weight: 400;
+  line-height: 1.5;
+  background: var(--cd-ui-flaeche-hoch);
+  border: 1px solid var(--cd-ui-linie);
+  border-radius: var(--cd-radius-md);
+  box-shadow: var(--cd-shadow-3);
+  pointer-events: auto;
+  user-select: none;
+  -webkit-user-select: none;
+  animation: cd-shell-problems-in var(--cd-motion-fast) var(--cd-ease-out);
+}
+
+.cd-shell[data-cd-shell-host="web"] .cd-shell-problems-popover {
+  --modeler-shell-problems-bottom: calc(
+    var(--cd-shell-rand) + var(--modeler-shell-legal-height, 20px) + var(--cd-shell-luecke) +
+      var(--cd-shell-zeile) + var(--cd-shell-luecke)
+  );
+}
+
+.cd-shell-problems-popover[hidden] {
+  display: none;
+}
+
+/* Focus lands on the dialog itself only when it has no row to take it; inside, as in a scroller. */
+.cd-shell-problems-popover:focus {
+  outline: none;
+}
+
+.cd-shell-problems-popover:focus-visible {
+  outline: 2px solid var(--cd-ui-fokus);
+  outline-offset: -2px;
+}
+
+.cd-shell-problems-popover-title {
+  flex: none;
+  margin: 0;
+  padding: 8px 12px 4px;
+  color: var(--cd-ui-text);
+  font-size: 13px;
+  font-weight: 600;
+  line-height: 1.5;
+}
+
+.cd-shell-problems-list {
+  flex: 1 1 auto;
+  min-height: 0;
+  margin: 0;
+  padding: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  list-style: none;
+}
+
+.cd-shell-problems-list > li {
+  display: block;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.cd-shell-problem {
+  box-sizing: border-box;
+  display: grid;
+  grid-template-columns: 16px minmax(0, 1fr);
+  column-gap: 12px;
+  align-items: start;
+  width: 100%;
+  min-height: var(--cd-shell-eintrag);
+  margin: 0;
+  padding: 8px 12px;
+  color: var(--cd-ui-text);
+  font-size: 13px;
+  font-weight: 400;
+  line-height: 1.5;
+  text-align: left;
+  background: transparent;
+  border: 0;
+  border-radius: var(--cd-radius-sm);
+}
+
+button.cd-shell-problem {
+  cursor: pointer;
+  transition: background-color var(--cd-motion-fast) var(--cd-ease);
+}
+
+button.cd-shell-problem:hover,
+button.cd-shell-problem:focus-visible {
+  background: var(--cd-ui-hover);
+}
+
+/* The pill's icon, centred on the message's first line (19.5px). */
+.cd-shell-problem-icon {
+  display: grid;
+  grid-row: 1 / span 2;
+  place-items: center;
+  width: 16px;
+  height: 16px;
+  margin-top: 2px;
+}
+
+.cd-shell-problem-icon svg {
+  display: block;
+  flex: none;
+}
+
+.cd-shell-problem[data-severity="error"] .cd-shell-problem-icon {
+  color: var(--cd-ui-danger);
+}
+
+.cd-shell-problem[data-severity="warning"] .cd-shell-problem-icon {
+  color: var(--cd-ui-warning);
+}
+
+.cd-shell-problem-message {
+  grid-column: 2;
+  color: var(--cd-ui-text);
+  overflow-wrap: anywhere;
+}
+
+.cd-shell-problem-location {
+  grid-column: 2;
+  color: var(--cd-ui-text-leise);
+  overflow-wrap: anywhere;
+}
+
+@keyframes cd-shell-problems-in {
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+}
+
+/* ---- Focus (guide §8): inside the dense toast and the scrolling list ------------------------ */
+
+.cd-shell :is(.cd-shell-toast-close, .cd-shell-problem):focus {
+  outline: none;
+}
+
+.cd-shell :is(.cd-shell-toast-close, .cd-shell-toast-action, .cd-shell-problem):focus-visible {
+  outline: 2px solid var(--cd-ui-fokus);
+  outline-offset: -2px;
+}
+
+/* ---- High contrast (guide §5.3): no shadows, 3px focus -------------------------------------- */
+
+.cd-shell:is([data-cd-kontrast="hoch"], [data-cd-kontrast="hoch"] *)
+  :is(.cd-shell-toast, .cd-shell-problems-popover) {
+  box-shadow: none;
+}
+
+.cd-shell:is([data-cd-kontrast="hoch"], [data-cd-kontrast="hoch"] *)
+  :is(
+    .cd-shell-toast-close,
+    .cd-shell-toast-action,
+    .cd-shell-problem,
+    .cd-shell-problems-popover
+  ):focus-visible {
+  outline-width: 3px;
+  outline-offset: -3px;
+}
+
+/* ---- Forced colours (guide §5.14): nothing disappears --------------------------------------- */
+
+@media (forced-colors: active) {
+  .cd-shell :is(.cd-shell-toast, .cd-shell-problems-popover) {
+    border-color: CanvasText;
+  }
+
+  /* Bar and dot keep their shape; the text carries the status. */
+  .cd-shell .cd-shell-toast::before,
+  .cd-shell .cd-shell-toast-dot {
+    forced-color-adjust: none;
+    background: CanvasText;
+  }
+
+  .cd-shell
+    :is(
+      .cd-shell-toast-close,
+      .cd-shell-toast-action,
+      .cd-shell-problem,
+      .cd-shell-problems-popover
+    ):focus-visible {
+    outline-color: Highlight;
+  }
+
+  /* The hover fill is forced away; a thin ring shows which row the pointer is on. */
+  .cd-shell button.cd-shell-problem:hover:not(:focus-visible) {
+    outline: 1px solid Highlight;
+    outline-offset: -1px;
+  }
+}
+
+/* ---- Reduced motion (guide §7): no slide, no pop-in ----------------------------------------- */
+
+@media (prefers-reduced-motion: reduce) {
+  .cd-shell :is(.cd-shell-toast, .cd-shell-problems-popover) {
+    animation: none;
+  }
+}
+
+/* The host asks for it although the OS does not: VS Code's workbench.reduceMotion. */
+html.cd-shell-reduce-motion .cd-shell :is(.cd-shell-toast, .cd-shell-problems-popover) {
+  animation: none;
+}