@karyl-chan/ui 0.3.0 → 0.5.0

package/src/components/Spacer.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+/**
+ * Spacer — an empty flex-grow filler that pushes its siblings apart
+ * inside a Stack / Cluster (or any flex container), replacing the
+ * one-off `margin-left:auto` / `margin-top:auto` idiom:
+ *
+ *   <Cluster>
+ *     <Title />
+ *     <Spacer />   <!-- eats the free space -->
+ *     <Actions />
+ *   </Cluster>
+ *
+ * Purely presentational, so it's hidden from the accessibility tree.
+ */
+</script>
+
+<template>
+  <div class="ui-spacer" aria-hidden="true"></div>
+</template>
+
+<style scoped>
+.ui-spacer { flex: 1 1 auto; }
+</style>

package/src/components/Stack.vue

@@ -0,0 +1,70 @@
+<script setup lang="ts">
+/**
+ * Stack — a flex layout that OWNS the gap between its children.
+ *
+ * Reach for this instead of hand-authoring `display:flex; flex-direction:
+ * column; gap:…` (or per-element margins) in a view's scoped CSS — that
+ * pattern appears hundreds of times across the app and is exactly the
+ * responsibility a layout primitive should carry, not each component.
+ * Because the parent Stack owns the spacing, the components inside it
+ * never need (or should have) outer margins of their own.
+ *
+ *   <Stack gap="4">           vertical, 1rem gaps (--space-4)
+ *     <VoiceCard />
+ *     <AppTabs ... />
+ *     <section>…</section>
+ *   </Stack>
+ *
+ * `gap` takes a spacing-scale step (0–8 → --space-*) or a raw CSS length.
+ */
+import { computed, type CSSProperties } from "vue";
+import {
+  resolveSpace,
+  ALIGN_ITEMS,
+  JUSTIFY_CONTENT,
+  type Align,
+  type Justify,
+} from "../lib/space";
+
+const props = withDefaults(
+  defineProps<{
+    /** Gap between children: a scale step (0–8) or a raw CSS length. */
+    gap?: string | number;
+    /** Main-axis direction. Default vertical. */
+    direction?: "column" | "row";
+    align?: Align;
+    justify?: Justify;
+    /** Allow children to wrap onto multiple lines. */
+    wrap?: boolean;
+    /** Render as inline-flex (shrink-to-content) instead of flex. */
+    inline?: boolean;
+  }>(),
+  {
+    gap: 4,
+    direction: "column",
+    align: "stretch",
+    justify: "start",
+    wrap: false,
+    inline: false,
+  },
+);
+
+const style = computed<CSSProperties>(() => ({
+  display: props.inline ? "inline-flex" : "flex",
+  flexDirection: props.direction,
+  gap: resolveSpace(props.gap),
+  alignItems: ALIGN_ITEMS[props.align],
+  justifyContent: JUSTIFY_CONTENT[props.justify],
+  flexWrap: props.wrap ? "wrap" : "nowrap",
+}));
+</script>
+
+<template>
+  <div class="ui-stack" :style="style"><slot /></div>
+</template>
+
+<style scoped>
+/* min-width:0 lets a column stack's children (e.g. text) truncate instead
+   of forcing the stack wider than its parent. */
+.ui-stack { min-width: 0; }
+</style>

package/src/components/tab-keyboard.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared WAI-ARIA tabs keyboard model for `AppTabs` and `AppTabsRouted`:
+ * roving tabindex + ArrowLeft/ArrowRight (ArrowUp/ArrowDown on vertical
+ * lists) / Home / End, skipping disabled tabs and wrapping at the ends.
+ * Activation is automatic — moving focus selects the tab.
+ */
+import type { TabDef } from "./tab-types";
+
+export type TabOrientation = "horizontal" | "vertical";
+
+/** Key of the tab that should be in the Tab sequence (tabindex=0). */
+export function rovingTabKey(
+  tabs: readonly TabDef[],
+  selected: string | undefined,
+): string | undefined {
+  if (selected !== undefined && tabs.some((t) => t.key === selected && !t.disabled)) {
+    return selected;
+  }
+  return tabs.find((t) => !t.disabled)?.key;
+}
+
+/**
+ * Key of the tab a navigation key moves to, or null when the key isn't a
+ * tab-navigation key (or there is nowhere to go).
+ */
+export function nextTabKey(
+  tabs: readonly TabDef[],
+  current: string | undefined,
+  key: string,
+  orientation: TabOrientation = "horizontal",
+): string | null {
+  const enabled = tabs.filter((t) => !t.disabled);
+  if (enabled.length === 0) return null;
+
+  const forward =
+    key === "ArrowRight" || (orientation === "vertical" && key === "ArrowDown");
+  const backward =
+    key === "ArrowLeft" || (orientation === "vertical" && key === "ArrowUp");
+
+  if (key === "Home") return enabled[0].key;
+  if (key === "End") return enabled[enabled.length - 1].key;
+  if (!forward && !backward) return null;
+
+  const idx = enabled.findIndex((t) => t.key === current);
+  if (idx === -1) return forward ? enabled[0].key : enabled[enabled.length - 1].key;
+  const step = forward ? 1 : -1;
+  return enabled[(idx + step + enabled.length) % enabled.length].key;
+}
+
+/**
+ * keydown handler for a `role="tablist"` element whose tabs carry
+ * `data-tab-key`. Moves focus to the target tab and calls `activate`.
+ */
+export function onTablistKeydown(
+  event: KeyboardEvent,
+  tabs: readonly TabDef[],
+  activate: (key: string) => void,
+  orientation: TabOrientation = "horizontal",
+): void {
+  if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
+  const tabEl = (event.target as HTMLElement | null)?.closest<HTMLElement>(
+    '[role="tab"]',
+  );
+  if (!tabEl) return;
+  const current = tabEl.dataset.tabKey;
+  const next = nextTabKey(tabs, current, event.key, orientation);
+  if (next === null) return;
+  event.preventDefault();
+  const list = event.currentTarget as HTMLElement;
+  const target = Array.from(
+    list.querySelectorAll<HTMLElement>('[role="tab"]'),
+  ).find((el) => el.dataset.tabKey === next);
+  target?.focus();
+  if (next !== current) activate(next);
+}

package/src/composables/use-confirm.ts

@@ -18,7 +18,12 @@ const pending = ref<PendingConfirm | null>(null);
 export function useConfirm() {
   function confirm(opts: ConfirmOptions): Promise<boolean> {
     return new Promise<boolean>((resolve) => {
+      // Only one global confirm can be on screen. A newer request
+      // supersedes the old one — settle the old promise as "not
+      // confirmed" so its awaiter doesn't hang forever.
+      const superseded = pending.value;
       pending.value = { options: opts, resolve };
+      superseded?.resolve(false);
     });
   }
 

package/src/composables/use-popover.ts

@@ -201,8 +201,22 @@ const DEFAULT_OPTIONS: Required<
   transition: true,
 };
 
-export function createVirtualElement(x: number, y: number): VirtualElement {
+/**
+ * Build a Popper `VirtualElement` anchored at a viewport point — pass it
+ * as `AppPopover`'s `referenceEl` (or to `usePopover`) to position a
+ * popover at a cursor / canvas coordinate instead of a DOM element.
+ *
+ * `contextElement` (optional) tells Popper which element's scroll
+ * containers to track, so the popover follows the anchor while that
+ * region scrolls.
+ */
+export function createVirtualElement(
+  x: number,
+  y: number,
+  contextElement?: Element,
+): VirtualElement {
   return {
+    contextElement,
     getBoundingClientRect: () => ({
       width: 0,
       height: 0,
@@ -223,6 +237,11 @@ export function createVirtualElementFromEvent(
   return createVirtualElement(event.clientX, event.clientY);
 }
 
+/** True when `ref` is a real DOM element rather than a Popper VirtualElement. */
+export function isDomElement(ref: unknown): ref is Element {
+  return typeof Element !== "undefined" && ref instanceof Element;
+}
+
 export function getScrollParent(element: HTMLElement): HTMLElement | Window {
   if (!element) return window;
 
@@ -865,7 +884,6 @@ export function createPopover(
    * 設置關閉相關的事件監聽器
    */
   function setupCloseListeners() {
-    const referenceEl = reference as HTMLElement;
 
     if (mergedOptions.closeOnContentClick) {
       const handleContentClick = () => hide();
@@ -876,7 +894,15 @@ export function createPopover(
     }
 
     if (mergedOptions.hideOnScroll) {
-      const scrollParents = getScrollParents(referenceEl);
+      // A VirtualElement has no DOM ancestry — getComputedStyle() on it
+      // throws. Fall back to its contextElement, else just the window.
+      const scrollRoot = isDomElement(reference)
+        ? reference
+        : reference.contextElement;
+      const scrollParents: (HTMLElement | Window)[] =
+        scrollRoot instanceof HTMLElement
+          ? getScrollParents(scrollRoot)
+          : [window];
       const handleScroll = () => {
         if (isVisible) hide();
       };
@@ -1165,7 +1191,10 @@ export function usePopover(
         const c = unref(contentRef);
         const r = unref(referenceRef);
         if (c && c.contains(target)) return true;
-        if (r && (r as HTMLElement).contains?.(target)) return true;
+        // Only a real element can "contain" the click; a VirtualElement
+        // anchor (point / range) has no DOM extent, so any click outside
+        // the content counts as outside.
+        if (r && isDomElement(r) && r.contains(target)) return true;
         return false;
       },
       close: () => instance.value?.hide(),

package/src/composables/use-scroll-lock.ts

@@ -0,0 +1,61 @@
+import { onBeforeUnmount, watch, type Ref } from "vue";
+
+/**
+ * Ref-counted `<body>` scroll lock shared by every overlay that wants the
+ * page behind it frozen (AppModal today). Stacked modals each take a
+ * lock; the body is only restored when the LAST holder releases, so
+ * closing the top modal of two doesn't unfreeze the page under the one
+ * still open.
+ *
+ * While locked, `overflow: hidden` is set on <body> and the vanished
+ * scrollbar's width is added to its right padding so content doesn't
+ * jump sideways. The original inline values are restored on release.
+ */
+let holders = 0;
+let savedOverflow = "";
+let savedPaddingRight = "";
+
+function acquire() {
+  if (typeof document === "undefined") return;
+  holders++;
+  if (holders > 1) return;
+  const body = document.body;
+  savedOverflow = body.style.overflow;
+  savedPaddingRight = body.style.paddingRight;
+  const scrollbar =
+    window.innerWidth - document.documentElement.clientWidth;
+  if (scrollbar > 0) {
+    const current = parseFloat(getComputedStyle(body).paddingRight) || 0;
+    body.style.paddingRight = `${current + scrollbar}px`;
+  }
+  body.style.overflow = "hidden";
+}
+
+function release() {
+  if (typeof document === "undefined" || holders === 0) return;
+  holders--;
+  if (holders > 0) return;
+  document.body.style.overflow = savedOverflow;
+  document.body.style.paddingRight = savedPaddingRight;
+}
+
+/**
+ * Hold a body scroll lock while `active` is true. Released automatically
+ * when `active` turns false or the owning component unmounts.
+ */
+export function useBodyScrollLock(active: Ref<boolean>): void {
+  let held = false;
+  const set = (on: boolean) => {
+    if (on === held) return;
+    held = on;
+    if (on) acquire();
+    else release();
+  };
+  watch(active, set, { immediate: true });
+  onBeforeUnmount(() => set(false));
+}
+
+/** Test-only: current number of lock holders. */
+export function _scrollLockHolders(): number {
+  return holders;
+}

package/src/index.ts

@@ -7,6 +7,19 @@
 //   import "@karyl-chan/ui/use-drawer.css";
 //   import "@karyl-chan/ui/use-popover.css";
 
+// ── Layout primitives ────────────────────────────────────────────────────
+// Own the space BETWEEN elements so views (and the components inside them)
+// don't hand-author flex+gap or per-element margins. See lib/space.ts for
+// the `gap` scale.
+export { default as Stack } from "./components/Stack.vue";
+export { default as Cluster } from "./components/Cluster.vue";
+export { default as Spacer } from "./components/Spacer.vue";
+export {
+  resolveSpace,
+  type Align,
+  type Justify,
+} from "./lib/space";
+
 // ── Components ───────────────────────────────────────────────────────────
 export { default as AppBadge } from "./components/AppBadge.vue";
 export type { BadgeSize, BadgeTone, BadgeVariant } from "./components/AppBadge.vue";
@@ -18,6 +31,8 @@ export { default as AppMenu } from "./components/AppMenu.vue";
 export { default as AppMenuItem } from "./components/AppMenuItem.vue";
 export { default as AppModal } from "./components/AppModal.vue";
 export { default as AppPopover } from "./components/AppPopover.vue";
+export { default as AppProgress } from "./components/AppProgress.vue";
+export type { ProgressSize, ProgressTone } from "./components/AppProgress.vue";
 export { default as AppSelect } from "./components/AppSelect.vue";
 export { default as AppSelectField } from "./components/AppSelectField.vue";
 export type { SelectOption } from "./components/AppSelectField.vue";
@@ -66,10 +81,18 @@ export { useEscapeStack } from "./composables/use-escape-stack";
 export { useFileDrop } from "./composables/use-file-drop";
 export type { FileDropHandlers } from "./composables/use-file-drop";
 export { useLongPress } from "./composables/use-long-press";
-export { usePopover } from "./composables/use-popover";
-export type { Placement, UsePopoverOptions } from "./composables/use-popover";
+export {
+  usePopover,
+  createVirtualElement,
+  createVirtualElementFromEvent,
+} from "./composables/use-popover";
+export type {
+  Placement,
+  UsePopoverOptions,
+  VirtualElement,
+} from "./composables/use-popover";
 export { useShiftKey } from "./composables/use-shift-key";
 
 // ── Stores ───────────────────────────────────────────────────────────────
-export { useToastStore } from "./stores/toastStore";
-export type { ToastItem } from "./stores/toastStore";
+export { useToastStore, DEFAULT_TOAST_DURATION } from "./stores/toastStore";
+export type { ToastItem, ToastType, ToastOptions } from "./stores/toastStore";

package/src/lib/focus.ts

@@ -0,0 +1,67 @@
+/**
+ * Focus helpers for dialog-style overlays (focus-in on open, Tab trap,
+ * focus restore on close).
+ */
+
+const FOCUSABLE_SELECTOR = [
+  "a[href]",
+  "area[href]",
+  "button:not([disabled])",
+  'input:not([disabled]):not([type="hidden"])',
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  "iframe",
+  "audio[controls]",
+  "video[controls]",
+  "summary",
+  '[contenteditable]:not([contenteditable="false"])',
+  "[tabindex]",
+].join(",");
+
+function isVisible(el: HTMLElement): boolean {
+  if (el.closest("[hidden], [inert]")) return false;
+  // `checkVisibility` covers display:none / visibility:hidden ancestors.
+  // Environments without it (older engines, jsdom) count it as visible.
+  const check = (el as HTMLElement & { checkVisibility?: () => boolean })
+    .checkVisibility;
+  return typeof check === "function" ? check.call(el) : true;
+}
+
+/** Tabbable descendants of `container`, in DOM order. */
+export function getFocusable(container: HTMLElement): HTMLElement[] {
+  return Array.from(
+    container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+  ).filter((el) => el.tabIndex >= 0 && isVisible(el));
+}
+
+/**
+ * Keep Tab / Shift+Tab cycling inside `container`. Call from the
+ * container's keydown handler; returns true when it handled the key.
+ */
+export function trapTabKey(event: KeyboardEvent, container: HTMLElement): boolean {
+  if (event.key !== "Tab" || event.altKey || event.ctrlKey || event.metaKey) {
+    return false;
+  }
+  const items = getFocusable(container);
+  if (items.length === 0) {
+    event.preventDefault();
+    container.focus();
+    return true;
+  }
+  const first = items[0];
+  const last = items[items.length - 1];
+  const active = document.activeElement as HTMLElement | null;
+  const inside = !!active && container.contains(active);
+  if (event.shiftKey) {
+    if (!inside || active === first || active === container) {
+      event.preventDefault();
+      last.focus();
+      return true;
+    }
+  } else if (!inside || active === last) {
+    event.preventDefault();
+    first.focus();
+    return true;
+  }
+  return false;
+}

package/src/lib/space.ts

@@ -0,0 +1,44 @@
+/**
+ * Spacing helpers for the layout primitives (Stack / Cluster / Spacer).
+ *
+ * `gap` and friends take a spacing-scale STEP (0–8, as a number or
+ * string) which maps to the corresponding `--space-*` token defined in
+ * tokens.css, or a raw CSS length (e.g. `"2px"`, `"1.5rem"`) as an
+ * escape hatch. Keeping the scale in tokens.css means the whole app
+ * shares one rhythm instead of 200 hand-picked gap values.
+ */
+
+/** Steps that exist as `--space-N` tokens in tokens.css. */
+const STEPS = new Set(["0", "1", "2", "3", "4", "5", "6", "7", "8"]);
+
+/** Resolve a gap/space prop to a CSS length: a scale step → `var(--space-N)`,
+ *  anything else → the value verbatim (raw CSS length escape hatch). */
+export function resolveSpace(
+  value: string | number | undefined,
+  fallback = "0",
+): string {
+  if (value === undefined || value === null || value === "") return fallback;
+  const s = String(value);
+  return STEPS.has(s) ? `var(--space-${s})` : s;
+}
+
+export type Align = "start" | "center" | "end" | "stretch" | "baseline";
+export type Justify = "start" | "center" | "end" | "between" | "around";
+
+/** Friendly `align` prop → CSS `align-items` value. */
+export const ALIGN_ITEMS: Record<Align, string> = {
+  start: "flex-start",
+  center: "center",
+  end: "flex-end",
+  stretch: "stretch",
+  baseline: "baseline",
+};
+
+/** Friendly `justify` prop → CSS `justify-content` value. */
+export const JUSTIFY_CONTENT: Record<Justify, string> = {
+  start: "flex-start",
+  center: "center",
+  end: "flex-end",
+  between: "space-between",
+  around: "space-around",
+};

package/src/stores/toastStore.ts

@@ -1,24 +1,62 @@
 import { defineStore } from "pinia";
 import { ref } from "vue";
 
+/**
+ * Toast severity. `error` / `warn` are announced assertively
+ * (role="alert"); `info` / `success` politely (role="status").
+ */
+export type ToastType = "error" | "warn" | "info" | "success";
+
+export interface ToastOptions {
+  /**
+   * Auto-dismiss delay in ms. Default 4000. `0` makes the toast sticky:
+   * it stays until the user closes it (close button) or `dismiss(id)`.
+   */
+  duration?: number;
+}
+
 export interface ToastItem {
   id: number;
   message: string;
-  type: "error" | "info";
+  type: ToastType;
+  /** Auto-dismiss delay in ms; `0` = sticky. Always set by `show()`. */
+  duration?: number;
 }
 
+/** Default auto-dismiss delay, unchanged from the original store. */
+export const DEFAULT_TOAST_DURATION = 4000;
+
 let nextId = 0;
 
 export const useToastStore = defineStore("toast", () => {
   const items = ref<ToastItem[]>([]);
+  const timers = new Map<number, ReturnType<typeof setTimeout>>();
 
-  function show(message: string, type: ToastItem["type"] = "error") {
+  /**
+   * Show a toast. `type` defaults to `'error'` (the original behaviour).
+   * Returns the toast id, usable with `dismiss(id)`.
+   */
+  function show(
+    message: string,
+    type: ToastType = "error",
+    options: ToastOptions = {},
+  ): number {
     const id = nextId++;
-    items.value = [...items.value, { id, message, type }];
-    setTimeout(() => dismiss(id), 4000);
+    const raw = options.duration ?? DEFAULT_TOAST_DURATION;
+    const duration = Number.isFinite(raw) && raw > 0 ? raw : 0;
+    items.value = [...items.value, { id, message, type, duration }];
+    if (duration > 0) {
+      timers.set(id, setTimeout(() => dismiss(id), duration));
+    }
+    return id;
   }
 
   function dismiss(id: number) {
+    const timer = timers.get(id);
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timers.delete(id);
+    }
     items.value = items.value.filter((t) => t.id !== id);
   }
 

package/src/tokens.css

@@ -57,6 +57,12 @@
 
     --pill-bg: #f3f4f6;
 
+    /* Unread / mention indicator (UnreadPill etc.). Same in both themes. */
+    --unread-accent: #f23f43;
+
+    /* Monospaced stack for IDs, keys, code-ish values. */
+    --font-mono: ui-monospace, SFMono-Regular, Consolas, "Liberation Mono", monospace;
+
     --transition-fast: 0.12s;
     --transition-base: 0.15s;
     --transition-slow: 0.2s;
@@ -66,6 +72,21 @@
     --radius-lg: 8px;
     --radius-xl: 12px;
     --radius-pill: 999px;
+
+    /* Spacing scale — the single source of truth for gaps between
+     * elements. Consume via the <Stack> / <Cluster> layout primitives
+     * (gap="4") rather than hand-authoring margins/gaps per view, so
+     * inter-element rhythm is owned by the layout layer, not by each
+     * component. Theme-independent (spacing doesn't change light/dark). */
+    --space-0: 0;
+    --space-1: 0.25rem;
+    --space-2: 0.5rem;
+    --space-3: 0.75rem;
+    --space-4: 1rem;
+    --space-5: 1.5rem;
+    --space-6: 2rem;
+    --space-7: 3rem;
+    --space-8: 4rem;
 }
 
 /* Pin the UA-side color-scheme hint so native widgets (form controls,