@karyl-chan/ui 0.4.0 → 0.5.0

package/src/components/AppTabsRouted.vue

@@ -15,16 +15,22 @@
  * which does NOT import vue-router and so doesn't pull it into your
  * plugin SPA's bundle.
  *
+ * Keyboard / ARIA behaviour matches AppTabs (roving tabindex, Arrow /
+ * Home / End navigation skipping disabled tabs, tabpanel wiring); a
+ * keyboard move updates the URL with `router.replace` so arrowing across
+ * tabs does not flood the history stack.
+ *
  * NB: separate component (vs an `routed` prop on AppTabs) so that
  * plugin SPAs that never use routed tabs don't transitively depend on
  * `vue-router`.
  */
-import { computed, ref, watch } from 'vue';
+import { computed, ref, useId, watch } from 'vue';
 import { useRoute, useRouter, RouterLink, type LocationQueryRaw } from 'vue-router';
 import { Icon } from '@iconify/vue';
 import { useBreakpoint } from '../composables/use-breakpoint';
 import AppSelectField, { type SelectOption } from './AppSelectField.vue';
 import type { TabDef } from './tab-types';
+import { onTablistKeydown, rovingTabKey } from './tab-keyboard';
 
 const props = withDefaults(defineProps<{
     modelValue: string;
@@ -133,6 +139,27 @@ function subLinkTo(key: string) {
     q[subKey.value] = key === defaultSub.value ? undefined : key;
     return { path: route.path, query: q };
 }
+
+// -- ARIA wiring (mirrors AppTabs) --------------------------------------
+const uid = useId();
+const panelId = `${uid}-panel`;
+const tabId = (i: number) => `${uid}-tab-${i}`;
+const subTabId = (i: number) => `${uid}-sub-${i}`;
+const primaryRoving = computed(() => rovingTabKey(props.tabs, props.modelValue));
+const subRoving = computed(() => rovingTabKey(props.subTabs, props.subModelValue));
+const panelLabelledBy = computed(() => {
+    if (hasSub.value) {
+        const si = props.subTabs.findIndex(t => t.key === props.subModelValue);
+        if (si !== -1) return subTabId(si);
+    }
+    const pi = props.tabs.findIndex(t => t.key === props.modelValue);
+    return pi !== -1 ? tabId(pi) : undefined;
+});
+function keyPrimary(key: string) { router.replace(tabLinkTo(key)); }
+function keySub(key: string) { router.replace(subLinkTo(key)); }
+function onPrimaryKeydown(e: KeyboardEvent) { onTablistKeydown(e, props.tabs, keyPrimary); }
+function onSubKeydown(e: KeyboardEvent) { onTablistKeydown(e, props.subTabs, keySub); }
+function onSubSideKeydown(e: KeyboardEvent) { onTablistKeydown(e, props.subTabs, keySub, 'vertical'); }
 </script>
 
 <template>
@@ -161,24 +188,32 @@ function subLinkTo(key: string) {
         v-else-if="!hasSub || subLayout === 'top'"
         :class="['tabs-root', 'desktop', 'top', { underline: variant === 'underline' }]"
     >
-        <nav class="primary-row" role="tablist">
-            <template v-for="t in tabs" :key="t.key">
+        <nav class="primary-row" role="tablist" @keydown="onPrimaryKeydown">
+            <template v-for="(t, i) in tabs" :key="t.key">
                 <RouterLink
                     v-if="!t.disabled"
+                    :id="tabId(i)"
                     :to="tabLinkTo(t.key)"
                     role="tab"
                     :class="['tab', { active: t.key === modelValue }]"
                     :aria-selected="t.key === modelValue"
+                    :aria-controls="panelId"
+                    :tabindex="t.key === primaryRoving ? 0 : -1"
+                    :data-tab-key="t.key"
                 >
                     <Icon v-if="t.icon" :icon="t.icon" width="16" height="16" />
                     <span>{{ t.label }}</span>
                 </RouterLink>
                 <button
                     v-else
+                    :id="tabId(i)"
                     type="button"
                     role="tab"
                     :class="['tab', { active: t.key === modelValue }]"
                     :aria-selected="t.key === modelValue"
+                    :aria-controls="panelId"
+                    tabindex="-1"
+                    :data-tab-key="t.key"
                     disabled
                 >
                     <Icon v-if="t.icon" :icon="t.icon" width="16" height="16" />
@@ -186,24 +221,32 @@ function subLinkTo(key: string) {
                 </button>
             </template>
         </nav>
-        <nav v-if="hasSub" class="sub-row" role="tablist">
-            <template v-for="t in subTabs" :key="t.key">
+        <nav v-if="hasSub" class="sub-row" role="tablist" @keydown="onSubKeydown">
+            <template v-for="(t, i) in subTabs" :key="t.key">
                 <RouterLink
                     v-if="!t.disabled"
+                    :id="subTabId(i)"
                     :to="subLinkTo(t.key)"
                     role="tab"
                     :class="['sub-tab', { active: t.key === subModelValue }]"
                     :aria-selected="t.key === subModelValue"
+                    :aria-controls="panelId"
+                    :tabindex="t.key === subRoving ? 0 : -1"
+                    :data-tab-key="t.key"
                 >
                     <Icon v-if="t.icon" :icon="t.icon" width="14" height="14" />
                     <span>{{ t.label }}</span>
                 </RouterLink>
                 <button
                     v-else
+                    :id="subTabId(i)"
                     type="button"
                     role="tab"
                     :class="['sub-tab', { active: t.key === subModelValue }]"
                     :aria-selected="t.key === subModelValue"
+                    :aria-controls="panelId"
+                    tabindex="-1"
+                    :data-tab-key="t.key"
                     disabled
                 >
                     <Icon v-if="t.icon" :icon="t.icon" width="14" height="14" />
@@ -211,31 +254,39 @@ function subLinkTo(key: string) {
                 </button>
             </template>
         </nav>
-        <div class="panel">
+        <div :id="panelId" class="panel" role="tabpanel" :aria-labelledby="panelLabelledBy">
             <slot />
         </div>
     </div>
 
     <!-- Desktop, sub-tabs as a vertical sidebar. -->
     <div v-else :class="['tabs-root', 'desktop', 'sidebar', { underline: variant === 'underline' }]">
-        <nav class="primary-row" role="tablist">
-            <template v-for="t in tabs" :key="t.key">
+        <nav class="primary-row" role="tablist" @keydown="onPrimaryKeydown">
+            <template v-for="(t, i) in tabs" :key="t.key">
                 <RouterLink
                     v-if="!t.disabled"
+                    :id="tabId(i)"
                     :to="tabLinkTo(t.key)"
                     role="tab"
                     :class="['tab', { active: t.key === modelValue }]"
                     :aria-selected="t.key === modelValue"
+                    :aria-controls="panelId"
+                    :tabindex="t.key === primaryRoving ? 0 : -1"
+                    :data-tab-key="t.key"
                 >
                     <Icon v-if="t.icon" :icon="t.icon" width="16" height="16" />
                     <span>{{ t.label }}</span>
                 </RouterLink>
                 <button
                     v-else
+                    :id="tabId(i)"
                     type="button"
                     role="tab"
                     :class="['tab', { active: t.key === modelValue }]"
                     :aria-selected="t.key === modelValue"
+                    :aria-controls="panelId"
+                    tabindex="-1"
+                    :data-tab-key="t.key"
                     disabled
                 >
                     <Icon v-if="t.icon" :icon="t.icon" width="16" height="16" />
@@ -244,24 +295,32 @@ function subLinkTo(key: string) {
             </template>
         </nav>
         <div class="split">
-            <nav class="sub-side" role="tablist">
-                <template v-for="t in subTabs" :key="t.key">
+            <nav class="sub-side" role="tablist" aria-orientation="vertical" @keydown="onSubSideKeydown">
+                <template v-for="(t, i) in subTabs" :key="t.key">
                     <RouterLink
                         v-if="!t.disabled"
+                        :id="subTabId(i)"
                         :to="subLinkTo(t.key)"
                         role="tab"
                         :class="['sub-side-tab', { active: t.key === subModelValue }]"
                         :aria-selected="t.key === subModelValue"
+                        :aria-controls="panelId"
+                        :tabindex="t.key === subRoving ? 0 : -1"
+                        :data-tab-key="t.key"
                     >
                         <Icon v-if="t.icon" :icon="t.icon" width="16" height="16" />
                         <span>{{ t.label }}</span>
                     </RouterLink>
                     <button
                         v-else
+                        :id="subTabId(i)"
                         type="button"
                         role="tab"
                         :class="['sub-side-tab', { active: t.key === subModelValue }]"
                         :aria-selected="t.key === subModelValue"
+                        :aria-controls="panelId"
+                        tabindex="-1"
+                        :data-tab-key="t.key"
                         disabled
                     >
                         <Icon v-if="t.icon" :icon="t.icon" width="16" height="16" />
@@ -269,7 +328,7 @@ function subLinkTo(key: string) {
                     </button>
                 </template>
             </nav>
-            <div class="panel side-panel">
+            <div :id="panelId" class="panel side-panel" role="tabpanel" :aria-labelledby="panelLabelledBy">
                 <slot />
             </div>
         </div>
@@ -282,6 +341,8 @@ function subLinkTo(key: string) {
     flex-direction: column;
     gap: 0.7rem;
     min-height: 0;
+    /* Span the parent's cross-axis - see AppTabs.vue. */
+    width: 100%;
     flex: 1;
 }
 
@@ -290,7 +351,10 @@ function subLinkTo(key: string) {
     gap: 0.4rem;
     border-bottom: 1px solid var(--border);
     padding-bottom: 0.5rem;
+    /* Horizontal scroll only; `overflow-y: hidden` stops the implicit
+       vertical scrollbar - see AppTabs.vue. */
     overflow-x: auto;
+    overflow-y: hidden;
     scrollbar-width: thin;
     flex-shrink: 0;
 }
@@ -348,6 +412,7 @@ function subLinkTo(key: string) {
     gap: 0.6rem;
     border-bottom: 1px solid var(--border);
     overflow-x: auto;
+    overflow-y: hidden;
     scrollbar-width: thin;
     margin-top: -0.3rem;
     flex-shrink: 0;

package/src/components/AppToast.vue

@@ -1,7 +1,35 @@
 <script setup lang="ts">
-import { useToastStore } from '../stores/toastStore';
+import { Icon } from '@iconify/vue';
+import { useToastStore, type ToastItem } from '../stores/toastStore';
+
+/**
+ * Toast host — mount once near the app root. Renders `useToastStore()`
+ * items bottom-right.
+ *
+ * - `error` / `warn` toasts are `role="alert"` (assertive); `info` /
+ *   `success` are `role="status"` + `aria-live="polite"`.
+ * - Timed toasts dismiss on click (as before); sticky toasts
+ *   (`duration: 0`) only via their close button, so a stray click
+ *   doesn't throw away a message the user is meant to act on.
+ */
+withDefaults(defineProps<{
+    /** Accessible label of a sticky toast's close button. */
+    closeLabel?: string;
+}>(), {
+    closeLabel: 'Dismiss'
+});
 
 const toast = useToastStore();
+
+function isSticky(item: ToastItem) {
+    return item.duration === 0;
+}
+function isAssertive(item: ToastItem) {
+    return item.type === 'error' || item.type === 'warn';
+}
+function onItemClick(item: ToastItem) {
+    if (!isSticky(item)) toast.dismiss(item.id);
+}
 </script>
 
 <template>
@@ -11,10 +39,21 @@ const toast = useToastStore();
                 v-for="item in toast.items"
                 :key="item.id"
                 class="toast-item"
-                :class="`toast-item--${item.type}`"
-                @click="toast.dismiss(item.id)"
+                :class="[`toast-item--${item.type}`, { 'toast-item--sticky': isSticky(item) }]"
+                :role="isAssertive(item) ? 'alert' : 'status'"
+                :aria-live="isAssertive(item) ? undefined : 'polite'"
+                @click="onItemClick(item)"
             >
-                {{ item.message }}
+                <span class="toast-message">{{ item.message }}</span>
+                <button
+                    v-if="isSticky(item)"
+                    type="button"
+                    class="toast-close"
+                    :aria-label="closeLabel"
+                    @click.stop="toast.dismiss(item.id)"
+                >
+                    <Icon icon="material-symbols:close-rounded" width="16" height="16" />
+                </button>
             </div>
         </TransitionGroup>
     </Teleport>
@@ -40,7 +79,34 @@ const toast = useToastStore();
     font-size: 0.82rem;
     line-height: 1.4;
     box-shadow: 0 4px 14px rgba(0, 0, 0, 0.25);
+    display: flex;
+    align-items: flex-start;
+    gap: 0.5rem;
+}
+.toast-item--sticky {
+    cursor: default;
+    padding-right: 0.35rem;
 }
+.toast-message {
+    flex: 1;
+    min-width: 0;
+    overflow-wrap: anywhere;
+}
+.toast-close {
+    flex-shrink: 0;
+    background: none;
+    border: none;
+    color: inherit;
+    opacity: 0.75;
+    cursor: pointer;
+    padding: 0.1rem;
+    margin: -0.1rem 0;
+    border-radius: var(--radius-sm, 4px);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+}
+.toast-close:hover { opacity: 1; }
 .toast-item--error {
     background: var(--danger, #ef4444);
     color: #fff;
@@ -50,6 +116,16 @@ const toast = useToastStore();
     color: var(--text, #cdd6f4);
     border: 1px solid var(--border, #45475a);
 }
+.toast-item--success {
+    background: var(--success-bg, #d1fae5);
+    color: var(--success-text, #065f46);
+    border: 1px solid var(--border, #45475a);
+}
+.toast-item--warn {
+    background: var(--warn-bg, #fef3c7);
+    color: var(--warn-text, #92400e);
+    border: 1px solid var(--border, #45475a);
+}
 .toast-enter-active,
 .toast-leave-active {
     transition: all 0.25s ease;
@@ -62,4 +138,14 @@ const toast = useToastStore();
     opacity: 0;
     transform: translateX(1rem);
 }
+@media (prefers-reduced-motion: reduce) {
+    .toast-enter-active,
+    .toast-leave-active {
+        transition: opacity 0.15s ease;
+    }
+    .toast-enter-from,
+    .toast-leave-to {
+        transform: none;
+    }
+}
 </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

@@ -31,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";
@@ -79,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";