akanjs 3.0.0-beta.8 → 3.0.0

package/vendor/@akanjs/native/plugins/dialog/src/desktop.ts

@@ -0,0 +1,80 @@
+
+
+import { type DesktopContext, defineDesktopPlugin } from "../../../packages/desktop/src/plugin.ts";
+import type { ActionSheetResult, DialogApi } from "./index.ts";
+import { normalizeActionSheet, normalizeAlert, normalizeConfirm, normalizePrompt } from "./options.ts";
+
+interface Button {
+  title: string;
+  style?: "default" | "cancel" | "destructive";
+}
+
+interface Answer {
+  /** Index of the button that ended the sheet; -1 when none did. */
+  button: number;
+  text?: string;
+}
+
+/**
+ * Shows the alert under a tag of its own; when the call's signal fires (the page gave up on it, or
+ * the page is gone) the shell takes it off the screen (`alert.dismiss`).
+ */
+const show = async (
+  ctx: DesktopContext,
+  args: { title: string; message: string; buttons: Button[]; input?: { text: string; placeholder: string } },
+) => {
+  const tag = crypto.randomUUID();
+  const dismiss = () =>
+    void ctx
+      .shell("alert.dismiss", { tag })
+      .catch((error: unknown) => console.warn("[akan-native] dialog: alert.dismiss failed", error));
+  ctx.signal?.addEventListener("abort", dismiss, { once: true });
+  try {
+    return (await ctx.shell("alert.show", { ...args, tag })) as Answer;
+  } finally {
+    ctx.signal?.removeEventListener("abort", dismiss);
+  }
+};
+
+export default defineDesktopPlugin<DialogApi>({
+  id: "dialog",
+  methods: {
+    async alert(args, ctx) {
+      const a = normalizeAlert(args);
+      await show(ctx, { title: a.title, message: a.message, buttons: [{ title: a.buttonTitle }] });
+    },
+    async confirm(args, ctx) {
+      const c = normalizeConfirm(args);
+      const { button } = await show(ctx, {
+        title: c.title,
+        message: c.message,
+        buttons: [{ title: c.okButtonTitle }, { title: c.cancelButtonTitle, style: "cancel" }],
+      });
+      return { value: button === 0 };
+    },
+    async prompt(args, ctx) {
+      const p = normalizePrompt(args);
+      const { button, text } = await show(ctx, {
+        title: p.title,
+        message: p.message,
+        buttons: [{ title: p.okButtonTitle }, { title: p.cancelButtonTitle, style: "cancel" }],
+        input: { text: p.inputText, placeholder: p.inputPlaceholder },
+      });
+      return button === 0 ? { value: text ?? "", cancelled: false } : { value: "", cancelled: true };
+    },
+    async actionSheet(args, ctx): Promise<ActionSheetResult> {
+      const a = normalizeActionSheet(args);
+      const order = a.options
+        .map((_, i) => i)
+        .sort((x, y) => Number(a.options[x]!.style === "cancel") - Number(a.options[y]!.style === "cancel"));
+      const { button } = await show(ctx, {
+        title: a.title,
+        message: a.message,
+        buttons: order.map((i) => ({ title: a.options[i]!.title, style: a.options[i]!.style })),
+      });
+      const index = order[button];
+      if (index === undefined || a.options[index]!.style === "cancel") return { index: -1, cancelled: true };
+      return { index, cancelled: false };
+    },
+  },
+});

package/vendor/@akanjs/native/plugins/dialog/src/index.ts

@@ -0,0 +1,87 @@
+import { definePlugin } from "../../../packages/core/src/index.ts";
+import { web } from "./web.ts";
+
+export interface AlertOptions {
+  title?: string;
+  /** Required; may be "" when there is a title. */
+  message: string;
+  /** Default: "OK" (the OS's localized OK on iOS and Android). */
+  buttonTitle?: string;
+}
+
+export interface ConfirmOptions {
+  title?: string;
+  message: string;
+  okButtonTitle?: string;
+  cancelButtonTitle?: string;
+}
+
+export interface ConfirmResult {
+  /** true only for the OK button. */
+  value: boolean;
+}
+
+export interface PromptOptions extends ConfirmOptions {
+  inputPlaceholder?: string;
+  /** Text the field starts with. */
+  inputText?: string;
+}
+
+export interface PromptResult {
+  /** The text as typed (not trimmed). "" when cancelled. */
+  value: string;
+  cancelled: boolean;
+}
+
+export type ActionSheetOptionStyle = "default" | "destructive" | "cancel";
+
+export interface ActionSheetOption {
+  title: string;
+  /**
+   * "destructive" is shown in red. At most one option may be "cancel": it is shown apart
+   * (iOS hides it on iPhone and iPad and cancels on a tap outside instead) and choosing it
+   * answers `{ index: -1, cancelled: true }` like any other dismissal.
+   */
+  style?: ActionSheetOptionStyle;
+}
+
+export interface ActionSheetOptions {
+  title?: string;
+  message?: string;
+  /** At least one. */
+  options: ActionSheetOption[];
+}
+
+export interface ActionSheetResult {
+  /** Index into `options` of the chosen option, or -1 when cancelled. */
+  index: number;
+  cancelled: boolean;
+}
+
+export interface DialogApi {
+  alert(options: AlertOptions): Promise<void>;
+  confirm(options: ConfirmOptions): Promise<ConfirmResult>;
+  prompt(options: PromptOptions): Promise<PromptResult>;
+  actionSheet(options: ActionSheetOptions): Promise<ActionSheetResult>;
+}
+
+export const dialog = definePlugin<DialogApi>("dialog", {
+  methods: ["alert", "confirm", "prompt", "actionSheet"],
+  web,
+});
+
+export interface UseDialog extends DialogApi {
+  supported: boolean;
+}
+
+const methods: DialogApi = {
+  alert: dialog.alert,
+  confirm: dialog.confirm,
+  prompt: dialog.prompt,
+  actionSheet: dialog.actionSheet,
+};
+
+/** The dialog functions for components. They hold no state, so they are stable across renders. */
+export function useDialog(): UseDialog {
+  return { supported: dialog.isSupported("alert"), ...methods };
+}

package/vendor/@akanjs/native/plugins/dialog/src/options.ts

@@ -0,0 +1,111 @@
+
+
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+import type {
+  ActionSheetOption,
+  ActionSheetOptionStyle,
+  ActionSheetOptions,
+  AlertOptions,
+  ConfirmOptions,
+  PromptOptions,
+} from "./index.ts";
+
+export const OPTION_STYLES: readonly ActionSheetOptionStyle[] = ["default", "destructive", "cancel"];
+
+/** Web defaults. The native hosts use the OS's localized OK / Cancel instead. */
+export const DEFAULT_OK = "OK";
+export const DEFAULT_CANCEL = "Cancel";
+
+export interface NormalizedAlert {
+  title: string;
+  message: string;
+  buttonTitle: string;
+}
+
+export interface NormalizedConfirm {
+  title: string;
+  message: string;
+  okButtonTitle: string;
+  cancelButtonTitle: string;
+}
+
+export interface NormalizedPrompt extends NormalizedConfirm {
+  inputPlaceholder: string;
+  inputText: string;
+}
+
+export interface NormalizedActionSheet {
+  title: string;
+  message: string;
+  options: Required<ActionSheetOption>[];
+}
+
+const invalid = (method: string, message: string) => new AkanNativeError("INVALID_ARGS", `${method}: ${message}`);
+
+function record(method: string, args: unknown): Record<string, unknown> {
+  if (args === undefined || args === null) return {};
+  if (typeof args !== "object" || Array.isArray(args)) throw invalid(method, "options must be an object");
+  return args as Record<string, unknown>;
+}
+
+function text(method: string, args: Record<string, unknown>, key: string): string | undefined {
+  const value = args[key];
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string") throw invalid(method, `${key} must be a string`);
+  return value;
+}
+
+function label(method: string, args: Record<string, unknown>, key: string, fallback: string): string {
+  return text(method, args, key) || fallback;
+}
+
+function titleAndMessage(method: string, args: Record<string, unknown>): { title: string; message: string } {
+  const message = text(method, args, "message");
+  if (message === undefined) throw invalid(method, "message must be a string");
+  const title = text(method, args, "title") ?? "";
+  if (!title && !message) throw invalid(method, "title or message must not be empty");
+  return { title, message };
+}
+
+export function normalizeAlert(args: AlertOptions | undefined): NormalizedAlert {
+  const a = record("alert", args);
+  return { ...titleAndMessage("alert", a), buttonTitle: label("alert", a, "buttonTitle", DEFAULT_OK) };
+}
+
+export function normalizeConfirm(args: ConfirmOptions | undefined, method = "confirm"): NormalizedConfirm {
+  const a = record(method, args);
+  return {
+    ...titleAndMessage(method, a),
+    okButtonTitle: label(method, a, "okButtonTitle", DEFAULT_OK),
+    cancelButtonTitle: label(method, a, "cancelButtonTitle", DEFAULT_CANCEL),
+  };
+}
+
+export function normalizePrompt(args: PromptOptions | undefined): NormalizedPrompt {
+  const a = record("prompt", args);
+  return {
+    ...normalizeConfirm(args, "prompt"),
+    inputPlaceholder: text("prompt", a, "inputPlaceholder") ?? "",
+    inputText: text("prompt", a, "inputText") ?? "",
+  };
+}
+
+export function normalizeActionSheet(args: ActionSheetOptions | undefined): NormalizedActionSheet {
+  const m = "actionSheet";
+  const a = record(m, args);
+  const raw = a.options;
+  if (!Array.isArray(raw) || raw.length === 0) throw invalid(m, "options must be a non-empty array");
+  const options = raw.map((option, i): Required<ActionSheetOption> => {
+    if (typeof option !== "object" || option === null || Array.isArray(option))
+      throw invalid(m, `options[${i}] must be an object`);
+    const o = option as Record<string, unknown>;
+    if (typeof o.title !== "string" || !o.title) throw invalid(m, `options[${i}].title must be a non-empty string`);
+    const style = o.style ?? "default";
+    if (!OPTION_STYLES.includes(style as ActionSheetOptionStyle))
+      throw invalid(m, `options[${i}].style must be default, destructive or cancel`);
+    return { title: o.title, style: style as ActionSheetOptionStyle };
+  });
+  if (options.filter((o) => o.style === "cancel").length > 1)
+    throw invalid(m, "only one option may have the cancel style");
+  return { title: text(m, a, "title") ?? "", message: text(m, a, "message") ?? "", options };
+}

package/vendor/@akanjs/native/plugins/dialog/src/web.ts

@@ -0,0 +1,296 @@
+import { AkanNativeError, defineWebPlugin } from "../../../packages/core/src/index.ts";
+import type { ActionSheetResult, ConfirmResult, DialogApi, PromptResult } from "./index.ts";
+import { normalizeActionSheet, normalizeAlert, normalizeConfirm, normalizePrompt } from "./options.ts";
+
+const P = "akan-native-dlg";
+
+const CSS = `
+dialog.${P}{--${P}-bg:#fff;--${P}-fg:#1c1c1e;--${P}-muted:#5f5f66;--${P}-line:rgba(60,60,67,.2);--${P}-hover:rgba(120,120,128,.12);--${P}-accent:#0a62d0;--${P}-danger:#d11a2a;--${P}-field:#fff;
+color-scheme:light;box-sizing:border-box;position:fixed;inset:0;margin:auto;padding:0;border:0;border-radius:14px;
+width:min(300px,calc(100% - 32px));max-width:none;max-height:calc(100% - 32px - env(safe-area-inset-top,0px) - env(safe-area-inset-bottom,0px));
+flex-direction:column;overflow:hidden;background:var(--${P}-bg);color:var(--${P}-fg);
+font:15px/1.4 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;text-align:center;
+box-shadow:0 10px 40px rgba(0,0,0,.25);animation:${P}-in .16s ease-out}
+dialog.${P}[open]{display:flex}
+dialog.${P}:focus{outline:none}
+dialog.${P}::backdrop{background:rgba(0,0,0,.35)}
+@media (prefers-color-scheme:dark){
+dialog.${P}{--${P}-bg:#2c2c2e;--${P}-fg:#f2f2f7;--${P}-muted:#aeaeb2;--${P}-line:rgba(235,235,245,.18);--${P}-hover:rgba(235,235,245,.08);--${P}-accent:#5aa9ff;--${P}-danger:#ff6961;--${P}-field:#1c1c1e;color-scheme:dark}
+dialog.${P}::backdrop{background:rgba(0,0,0,.55)}}
+.${P} .${P}-body{padding:20px 16px 16px;overflow:auto}
+.${P} .${P}-title,.${P} .${P}-msg,.${P} .${P}-input,.${P} .${P}-btn{all:unset;box-sizing:border-box;display:block}
+.${P} .${P}-title{font-size:17px;font-weight:600;line-height:1.3;overflow-wrap:anywhere}
+.${P} .${P}-msg{margin-top:4px;color:var(--${P}-muted);font-size:14px;white-space:pre-wrap;overflow-wrap:anywhere}
+.${P} .${P}-title+.${P}-msg{margin-top:4px}
+.${P} .${P}-msg:first-child{margin-top:0}
+.${P} .${P}-input{width:100%;margin-top:14px;padding:8px 10px;border:1px solid var(--${P}-line);border-radius:8px;background:var(--${P}-field);color:inherit;font-size:16px;text-align:start;cursor:text;user-select:text;-webkit-user-select:text}
+.${P} .${P}-input:focus{outline:2px solid var(--${P}-accent);outline-offset:-1px}
+.${P} .${P}-input::placeholder{color:var(--${P}-muted);opacity:.8}
+.${P} .${P}-actions{display:flex;flex-shrink:0;border-top:1px solid var(--${P}-line)}
+.${P} .${P}-btn{flex:1 1 0;min-width:0;min-height:44px;padding:10px 8px;color:var(--${P}-accent);font-size:16px;line-height:1.3;text-align:center;cursor:pointer;overflow-wrap:anywhere;-webkit-tap-highlight-color:transparent}
+.${P} .${P}-btn+.${P}-btn{border-inline-start:1px solid var(--${P}-line)}
+.${P} .${P}-btn:hover,.${P} .${P}-btn:active{background:var(--${P}-hover)}
+.${P} .${P}-btn:focus-visible{outline:2px solid var(--${P}-accent);outline-offset:-3px;border-radius:8px}
+.${P} .${P}-primary{font-weight:600}
+.${P} .${P}-danger{color:var(--${P}-danger)}
+dialog.${P}.${P}-sheet{width:min(420px,100%);max-height:100%;margin:auto auto 0;gap:8px;overflow:visible;border-radius:0;background:transparent;box-shadow:none;
+padding:0 max(8px,env(safe-area-inset-right,0px)) calc(8px + env(safe-area-inset-bottom,0px)) max(8px,env(safe-area-inset-left,0px));animation-name:${P}-up}
+.${P}-sheet .${P}-group{display:flex;flex-direction:column;min-height:0;overflow:auto;border-radius:14px;background:var(--${P}-bg);box-shadow:0 4px 24px rgba(0,0,0,.18)}
+.${P}-sheet .${P}-group:last-child{flex-shrink:0}
+.${P}-sheet .${P}-head{padding:14px 16px;border-bottom:1px solid var(--${P}-line)}
+.${P}-sheet .${P}-title{font-size:13px;color:var(--${P}-muted)}
+.${P}-sheet .${P}-msg{font-size:13px}
+.${P}-sheet .${P}-btn{flex:none;min-height:52px;padding:14px 16px;font-size:17px}
+.${P}-sheet .${P}-btn+.${P}-btn{border-inline-start:0;border-top:1px solid var(--${P}-line)}
+@media (min-width:640px){dialog.${P}.${P}-sheet{width:340px;margin:auto;padding:0;animation-name:${P}-in}}
+@keyframes ${P}-in{from{opacity:0;transform:scale(.96)}}
+@keyframes ${P}-up{from{opacity:0;transform:translateY(24px)}}
+@media (prefers-reduced-motion:reduce){dialog.${P}{animation:none}}
+`;
+
+let sheet: CSSStyleSheet | null = null;
+
+/**
+ * A constructed stylesheet: a strict CSP (style-src without 'unsafe-inline', SEC-4) blocks a
+ * <style> element added at runtime, but not adoptedStyleSheets. The <style> fallback is for
+ * engines without constructable stylesheets.
+ */
+function injectStyle(): void {
+  if (sheet || document.getElementById(`${P}-style`)) return;
+  if (typeof CSSStyleSheet === "function" && "adoptedStyleSheets" in document) {
+    try {
+      sheet = new CSSStyleSheet();
+      sheet.replaceSync(CSS);
+      document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+      return;
+    } catch {
+      sheet = null;
+    }
+  }
+  const style = document.createElement("style");
+  style.id = `${P}-style`;
+  style.textContent = CSS;
+  (document.head ?? document.documentElement).append(style);
+}
+
+function el<K extends keyof HTMLElementTagNameMap>(tag: K, className: string, text?: string): HTMLElementTagNameMap[K] {
+  const node = document.createElement(tag);
+  node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+interface Action<T> {
+  label: string;
+  /** Gets the prompt's text ("" without a field). */
+  result: (text: string) => T;
+  className?: string;
+}
+
+interface Spec<T> {
+  /** Action sheet: options stacked at the bottom (centered on wide screens), cancel apart. */
+  sheet?: boolean;
+  title: string;
+  message: string;
+  input?: { placeholder: string; text: string };
+  actions: Action<T>[];
+  /** The sheet's cancel option, in a group of its own (iOS style). */
+  cancelAction?: Action<T>;
+  /** The answer for Escape, and for a tap outside when `outsideDismisses`. */
+  dismissed: T;
+  /** Only action sheets close on a tap outside, as on iOS and Android; alerts never do on iOS. */
+  outsideDismisses?: boolean;
+  /** Index into `actions` of the button that gets focus and answers Enter. */
+  primary?: number;
+}
+
+let seq = 0;
+
+function show<T>(spec: Spec<T>): Promise<T> {
+  if (typeof document === "undefined") throw new AkanNativeError("UNSUPPORTED", "dialogs need a document");
+  const dialog = el("dialog", spec.sheet ? `${P} ${P}-sheet` : P);
+  if (typeof dialog.showModal !== "function")
+    throw new AkanNativeError("UNSUPPORTED", "<dialog> is not supported by this browser");
+  injectStyle();
+  const id = `${P}-${++seq}`;
+  dialog.tabIndex = -1;
+  dialog.setAttribute("role", spec.sheet ? "dialog" : "alertdialog");
+
+  const head = el("div", spec.sheet ? `${P}-head` : `${P}-body`);
+  if (spec.title) head.append(Object.assign(el("h2", `${P}-title`, spec.title), { id: `${id}-t` }));
+  if (spec.message) head.append(Object.assign(el("p", `${P}-msg`, spec.message), { id: `${id}-m` }));
+  
+  if (spec.title) dialog.setAttribute("aria-labelledby", `${id}-t`);
+  if (spec.message) dialog.setAttribute(spec.title ? "aria-describedby" : "aria-labelledby", `${id}-m`);
+
+  let input: HTMLInputElement | undefined;
+  if (spec.input) {
+    input = el("input", `${P}-input`);
+    input.type = "text";
+    input.placeholder = spec.input.placeholder;
+    input.value = spec.input.text;
+    input.enterKeyHint = "done";
+    input.setAttribute("aria-labelledby", spec.message ? `${id}-m` : `${id}-t`);
+    head.append(input);
+  }
+
+  let finish: (value: T) => void = () => {};
+  const button = (action: Action<T>, extra = "") => {
+    const node = el("button", `${P}-btn ${action.className ?? ""} ${extra}`.trim(), action.label);
+    node.type = "button";
+    node.addEventListener("click", () => finish(action.result(input?.value ?? "")));
+    return node;
+  };
+  const buttons = spec.actions.map((action, i) => button(action, i === spec.primary ? `${P}-primary` : ""));
+
+  if (spec.sheet) {
+    const group = el("div", `${P}-group`);
+    if (spec.title || spec.message) group.append(head);
+    group.append(...buttons);
+    dialog.append(group);
+    if (spec.cancelAction) {
+      const cancel = el("div", `${P}-group`);
+      cancel.append(button(spec.cancelAction, `${P}-primary`));
+      dialog.append(cancel);
+    }
+  } else {
+    const actions = el("div", `${P}-actions`);
+    actions.append(...buttons);
+    dialog.append(head, actions);
+  }
+
+  const focusables = () => Array.from(dialog.querySelectorAll<HTMLElement>("button, input"));
+  dialog.addEventListener("keydown", (e) => {
+    if (e.isComposing || e.keyCode === 229) return; 
+    if (e.key === "Tab") {
+      const items = focusables();
+      const first = items[0];
+      const last = items[items.length - 1];
+      if (!first || !last) return;
+      const active = document.activeElement;
+      if (e.shiftKey && (active === first || active === dialog)) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    } else if (spec.sheet && (e.key === "ArrowDown" || e.key === "ArrowUp")) {
+      const items = focusables();
+      if (items.length === 0) return;
+      e.preventDefault();
+      const at = items.indexOf(document.activeElement as HTMLElement);
+      const next = e.key === "ArrowDown" ? (at + 1) % items.length : (at <= 0 ? items.length : at) - 1;
+      items[next]?.focus();
+    } else if (e.key === "Enter" && e.target === input && spec.primary !== undefined) {
+      e.preventDefault();
+      buttons[spec.primary]?.click();
+    }
+  });
+  
+  dialog.addEventListener("cancel", (e) => {
+    e.preventDefault();
+    finish(spec.dismissed);
+  });
+  dialog.addEventListener("close", () => finish(spec.dismissed));
+  if (spec.outsideDismisses) {
+
+    let downOutside = false;
+    dialog.addEventListener("pointerdown", (e) => (downOutside = e.target === dialog));
+    dialog.addEventListener("click", (e) => {
+      if (downOutside && e.target === dialog) finish(spec.dismissed);
+      downOutside = false;
+    });
+  }
+
+  return new Promise<T>((resolve) => {
+    const previous = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    let settled = false;
+    finish = (value) => {
+      if (settled) return;
+      settled = true;
+      if (dialog.open) dialog.close();
+      dialog.remove();
+      if (previous?.isConnected && document.activeElement !== previous) previous.focus({ preventScroll: true });
+      resolve(value);
+    };
+    (document.body ?? document.documentElement).append(dialog);
+    dialog.showModal();
+    if (input) {
+      input.focus();
+      input.setSelectionRange(input.value.length, input.value.length); 
+    } else if (spec.primary !== undefined) {
+      buttons[spec.primary]?.focus();
+    } else {
+      dialog.focus(); 
+    }
+  });
+}
+
+export const web = defineWebPlugin<DialogApi>({
+  methods: {
+    alert(args) {
+      const o = normalizeAlert(args);
+      return show<void>({
+        title: o.title,
+        message: o.message,
+        actions: [{ label: o.buttonTitle, result: () => {} }],
+        dismissed: undefined,
+        primary: 0,
+      });
+    },
+    confirm(args) {
+      const o = normalizeConfirm(args);
+      return show<ConfirmResult>({
+        title: o.title,
+        message: o.message,
+        actions: [
+          { label: o.cancelButtonTitle, result: () => ({ value: false }) },
+          { label: o.okButtonTitle, result: () => ({ value: true }) },
+        ],
+        dismissed: { value: false },
+        primary: 1,
+      });
+    },
+    prompt(args) {
+      const o = normalizePrompt(args);
+      const cancelled: PromptResult = { value: "", cancelled: true };
+      return show<PromptResult>({
+        title: o.title,
+        message: o.message,
+        input: { placeholder: o.inputPlaceholder, text: o.inputText },
+        actions: [
+          { label: o.cancelButtonTitle, result: () => cancelled },
+          { label: o.okButtonTitle, result: (value) => ({ value, cancelled: false }) },
+        ],
+        dismissed: cancelled,
+        primary: 1,
+      });
+    },
+    actionSheet(args) {
+      const o = normalizeActionSheet(args);
+      const cancelled = (): ActionSheetResult => ({ index: -1, cancelled: true });
+      const cancelIndex = o.options.findIndex((option) => option.style === "cancel");
+      const cancelOption = o.options[cancelIndex];
+      return show<ActionSheetResult>({
+        sheet: true,
+        title: o.title,
+        message: o.message,
+        actions: o.options.flatMap((option, index) =>
+          option.style === "cancel"
+            ? []
+            : [
+                {
+                  label: option.title,
+                  result: () => ({ index, cancelled: false }),
+                  className: option.style === "destructive" ? `${P}-danger` : "",
+                },
+              ],
+        ),
+        cancelAction: cancelOption && { label: cancelOption.title, result: cancelled },
+        dismissed: cancelled(),
+        outsideDismisses: true,
+      });
+    },
+  },
+});

package/vendor/@akanjs/native/plugins/dock/native-plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "dock",
+  "apiVersion": 1,
+  "methods": ["setBadge", "setProgress", "setVisible", "getState"],
+  "events": [],
+  "web": null,
+  "desktop": "./src/desktop.ts",
+  "ios": null,
+  "android": null
+}

package/vendor/@akanjs/native/plugins/dock/src/desktop.ts

@@ -0,0 +1,34 @@
+
+
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+import { defineDesktopPlugin } from "../../../packages/desktop/src/plugin.ts";
+import type { DockApi, DockState } from "./index.ts";
+
+const STATES = ["normal", "paused", "error"];
+
+export default defineDesktopPlugin<DockApi>({
+  id: "dock",
+  methods: {
+    setBadge: (args, ctx) => {
+      const label = args?.label ?? null;
+      if (label !== null && typeof label !== "string")
+        throw new AkanNativeError("INVALID_ARGS", "label must be a string or null");
+      return ctx.shell("dock.setBadge", { label }) as Promise<DockState>;
+    },
+    setProgress: (args, ctx) => {
+      const progress = args?.progress ?? null;
+      if (progress !== null && (typeof progress !== "number" || !(progress >= 0 && progress <= 1))) {
+        throw new AkanNativeError("INVALID_ARGS", "progress must be a number from 0 to 1, or null");
+      }
+      const state = args?.state ?? "normal";
+      if (!STATES.includes(state))
+        throw new AkanNativeError("INVALID_ARGS", `state must be one of ${STATES.join(", ")}`);
+      return ctx.shell("dock.setProgress", { progress, state }) as Promise<DockState>;
+    },
+    setVisible: (args, ctx) => {
+      if (typeof args?.visible !== "boolean") throw new AkanNativeError("INVALID_ARGS", "visible must be a boolean");
+      return ctx.shell("dock.setVisible", { visible: args.visible }) as Promise<DockState>;
+    },
+    getState: (_args, ctx) => ctx.shell("dock.getState") as Promise<DockState>,
+  },
+});

package/vendor/@akanjs/native/plugins/dock/src/index.ts

@@ -0,0 +1,46 @@
+import { definePlugin } from "../../../packages/core/src/index.ts";
+
+/**
+ * The app's Dock icon on macOS, its taskbar buttons on Windows and its launcher entry on Linux
+ * (plugins.md §5): a badge, a progress bar, and whether the app has a Dock icon at all.
+ *
+ * - Everything is app-wide and outlives the page: after a reload, read it back with getState().
+ * - setBadge: any short text ("3", "!", "new"); null or "" removes it. Numbers read best.
+ * - setProgress: 0..1, drawn as a bar over the icon in whole percents; null hides it. `state`
+ *   colors it: normal (blue), paused (yellow), error (red). There is no indeterminate bar on macOS.
+ * - setVisible(false): no Dock icon, not in Cmd+Tab, no menu bar (keyboard shortcuts of the app
+ *   menu still work); windows stay open. For apps that live in the menu bar (tray plugin).
+ *   `policy` also reports "prohibited", the state `akan-native test` starts the app in.
+ * - Windows: every window's taskbar button. setBadge draws the label on a red disc as the overlay
+ *   icon (counts over 99 as "99+", other labels longer than 2 characters as a plain disc),
+ *   setProgress is the button's progress bar in the same three colors, setVisible(false) takes
+ *   the buttons away (policy "accessory"; the windows stay in Alt+Tab).
+ * - Linux: the launcher entry of the desktop file "<app id>.desktop" (the Unity LauncherEntry
+ *   API, which Ubuntu's dock, Dash to Dock and KDE Plasma show): setBadge takes whole numbers
+ *   only (other labels reject UNSUPPORTED), setProgress draws paused and error like normal, and
+ *   setVisible(false) sets the windows' skip-taskbar hint. Nothing shows until the app is
+ *   installed with a desktop file of that name; the state is kept meanwhile.
+ * - Web, iOS and Android: UNSUPPORTED.
+ */
+export type DockProgressState = "normal" | "paused" | "error";
+
+export interface DockState {
+  /** The app has a Dock icon (activation policy "regular"). */
+  visible: boolean;
+  policy: "regular" | "accessory" | "prohibited";
+  badge: string | null;
+  /** 0..1 as last set, or null when no bar is shown. */
+  progress: number | null;
+  progressState: DockProgressState | null;
+}
+
+export interface DockApi {
+  setBadge(args: { label: string | null }): Promise<DockState>;
+  setProgress(args: { progress: number | null; state?: DockProgressState }): Promise<DockState>;
+  setVisible(args: { visible: boolean }): Promise<DockState>;
+  getState(): Promise<DockState>;
+}
+
+export const dock = definePlugin<DockApi>("dock", {
+  methods: ["setBadge", "setProgress", "setVisible", "getState"],
+});