@karyl-chan/ui 0.1.0

package/src/components/AppModal.vue

@@ -0,0 +1,257 @@
+<script setup lang="ts">
+import { computed, onMounted, onUnmounted, toRef, useId } from 'vue';
+import { Icon } from '@iconify/vue';
+import { useBreakpoint } from '../composables/use-breakpoint';
+import { useDrawer } from '../composables/use-drawer';
+
+/**
+ * Viewport-aware modal:
+ * - Desktop → centered card with a translucent backdrop, fade transition.
+ * - Mobile  → bottom drawer using the shared `useDrawer` styles, slide-up
+ *   transition, drag-handle visual cue, safe-area inset.
+ *
+ * The caller owns everything inside the slot — typical usage is to drop
+ * a `<form @submit.prevent>` containing fields + an actions footer
+ * directly into the default slot. AppModal supplies the chrome (backdrop,
+ * panel, optional title header, close button) only.
+ *
+ * `closeOnBackdrop` / `closeOnEscape` default to true. Escape closure on
+ * desktop is wired locally; on mobile it's handled by useDrawer's escape
+ * stack. Backdrop click emits `close` either way.
+ */
+const props = withDefaults(defineProps<{
+    visible: boolean;
+    /** Heading rendered in the panel's header. Hidden when blank. */
+    title?: string;
+    closeOnBackdrop?: boolean;
+    closeOnEscape?: boolean;
+    /** Width of the desktop panel; mobile drawer ignores this. */
+    width?: string;
+}>(), {
+    title: '',
+    closeOnBackdrop: true,
+    closeOnEscape: true,
+    width: 'min(440px, 92vw)'
+});
+
+const emit = defineEmits<{
+    (e: 'close'): void;
+}>();
+
+const { isMobile } = useBreakpoint();
+const visibleRef = toRef(props, 'visible');
+const desktopVisible = computed(() => props.visible && !isMobile.value);
+const drawerVisible = computed(() => props.visible && isMobile.value);
+
+const titleId = useId();
+
+// Desktop Escape handler — useDrawer already covers the mobile branch
+// via its escape stack, so we only listen when the popover branch is
+// active. Listening unconditionally would let a single Escape close two
+// stacked drawers (e.g. user-context-menu drawer over a modal drawer).
+function onWindowKey(event: KeyboardEvent) {
+    if (!visibleRef.value || !props.closeOnEscape || isMobile.value) return;
+    if (event.key === 'Escape') {
+        event.preventDefault();
+        emit('close');
+    }
+}
+onMounted(() => window.addEventListener('keydown', onWindowKey));
+onUnmounted(() => window.removeEventListener('keydown', onWindowKey));
+
+const { backdropClass, panelClass, backdropTransition, panelTransition } = useDrawer({
+    visible: drawerVisible,
+    placement: 'bottom',
+    closeOnEscape: props.closeOnEscape,
+    onClose: () => emit('close')
+});
+
+function onBackdropClick() {
+    if (props.closeOnBackdrop) emit('close');
+}
+</script>
+
+<template>
+    <Teleport to="body">
+        <!-- Desktop branch — centered card. -->
+        <Transition name="app-modal-fade">
+            <div
+                v-if="desktopVisible"
+                class="app-modal-backdrop"
+                @click.self="onBackdropClick"
+            >
+                <div
+                    class="app-modal-panel"
+                    role="dialog"
+                    aria-modal="true"
+                    :style="{ width }"
+                    :aria-labelledby="title || $slots.header ? titleId : undefined"
+                    :aria-label="title || $slots.header ? undefined : title || undefined"
+                >
+                    <header v-if="title || $slots.header" class="app-modal-head">
+                        <span :id="titleId" class="app-modal-title">
+                            <slot name="header">{{ title }}</slot>
+                        </span>
+                        <button
+                            type="button"
+                            class="app-modal-close"
+                            :aria-label="'Close'"
+                            @click="emit('close')"
+                        >
+                            <Icon icon="material-symbols:close-rounded" width="18" height="18" />
+                        </button>
+                    </header>
+                    <div class="app-modal-body">
+                        <slot />
+                    </div>
+                </div>
+            </div>
+        </Transition>
+    </Teleport>
+
+    <!-- Mobile drawer branch — slides up from the bottom edge. -->
+    <Teleport to="body">
+        <Transition :name="backdropTransition">
+            <div
+                v-if="drawerVisible"
+                :class="[backdropClass, 'app-modal-drawer-backdrop']"
+                @click="onBackdropClick"
+            />
+        </Transition>
+        <Transition :name="panelTransition">
+            <div
+                v-if="drawerVisible"
+                :class="[panelClass, 'app-modal-drawer-panel']"
+                data-placement="bottom"
+                role="dialog"
+                aria-modal="true"
+                :aria-labelledby="title || $slots.header ? titleId : undefined"
+                :aria-label="title || $slots.header ? undefined : title || undefined"
+            >
+                <header v-if="title || $slots.header" class="app-modal-drawer-head">
+                    <span :id="titleId" class="app-modal-title">
+                        <slot name="header">{{ title }}</slot>
+                    </span>
+                    <button
+                        type="button"
+                        class="app-modal-close"
+                        :aria-label="'Close'"
+                        @click="emit('close')"
+                    >
+                        <Icon icon="material-symbols:close-rounded" width="18" height="18" />
+                    </button>
+                </header>
+                <div class="app-modal-drawer-body">
+                    <slot />
+                </div>
+            </div>
+        </Transition>
+    </Teleport>
+</template>
+
+<style scoped>
+/* ── Desktop ────────────────────────────────────────────────────── */
+.app-modal-backdrop {
+    position: fixed;
+    inset: 0;
+    background: rgba(0, 0, 0, 0.45);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    z-index: 1500;
+}
+.app-modal-panel {
+    max-height: 88vh;
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-lg);
+    box-shadow: 0 12px 36px rgba(0, 0, 0, 0.32);
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+}
+.app-modal-head {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.6rem 0.9rem;
+    border-bottom: 1px solid var(--border);
+    flex-shrink: 0;
+}
+.app-modal-title {
+    flex: 1;
+    font-weight: 600;
+    color: var(--text-strong);
+}
+.app-modal-close {
+    background: none;
+    border: none;
+    color: var(--text-muted);
+    cursor: pointer;
+    padding: 0.5rem;
+    min-width: 44px;
+    min-height: 44px;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+}
+.app-modal-close:hover { color: var(--text); }
+
+.app-modal-fade-enter-active,
+.app-modal-fade-leave-active { transition: opacity 0.18s ease; }
+.app-modal-fade-enter-from,
+.app-modal-fade-leave-to { opacity: 0; }
+
+/* ── Mobile drawer ──────────────────────────────────────────────── */
+/* useDrawer injects .drawer-backdrop / .drawer-panel positioning &
+   transitions; this layer adds the modal-specific chrome (rounded top,
+   shadow, max-height, safe-area inset, drag-handle). */
+.app-modal-drawer-backdrop {
+    z-index: 1500;
+}
+.app-modal-drawer-panel {
+    z-index: 1501;
+    border-top: 1px solid var(--border);
+    border-radius: 14px 14px 0 0;
+    box-shadow: 0 -8px 24px rgba(0, 0, 0, 0.28);
+    max-height: 88vh;
+    padding-bottom: env(safe-area-inset-bottom, 0px);
+}
+.app-modal-drawer-panel::before {
+    content: '';
+    display: block;
+    width: 36px;
+    height: 4px;
+    border-radius: 2px;
+    background: var(--text-muted);
+    opacity: 0.35;
+    margin: 0.4rem auto 0;
+    flex-shrink: 0;
+}
+.app-modal-drawer-head {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.5rem 0.9rem 0.6rem;
+    border-bottom: 1px solid var(--border);
+    flex-shrink: 0;
+}
+.app-modal-drawer-body {
+    flex: 1;
+    min-height: 0;
+    overflow-y: auto;
+    overflow-x: hidden;
+}
+
+/* ── Desktop body wrapper ───────────────────────────────────────── */
+/* Structural wrapper that matches the mobile .app-modal-drawer-body.
+   Padding is intentionally 0 — callers are responsible for spacing
+   their slot content. AppConfirmDialog and similar leaf components
+   supply their own inner padding. */
+.app-modal-body {
+    flex: 1;
+    min-height: 0;
+    overflow-y: auto;
+    overflow-x: hidden;
+}
+</style>

package/src/components/AppPopover.vue

@@ -0,0 +1,275 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue';
+import { useBreakpoint } from '../composables/use-breakpoint';
+import { usePopover, type Placement } from '../composables/use-popover';
+import { useDrawer, type DrawerPlacement } from '../composables/use-drawer';
+
+/**
+ * Viewport-aware popover:
+ * - Desktop → popover anchored to the trigger via usePopover.
+ * - Mobile  → bottom drawer via useDrawer. Backdrop + panel z-index
+ *   raised to 2000/2001 so a popover opened from inside the mobile
+ *   hamburger nav (which sits at 1001) still renders on top.
+ *
+ * Two ways to wire the trigger:
+ *   1. `#trigger` slot — the slot is wrapped in a `display: contents`
+ *      span so the wrapper doesn't affect the caller's layout. Clicks
+ *      anywhere on the wrapped content toggle open/close.
+ *   2. `referenceEl` prop — for cases where the trigger can't live
+ *      inside this component (e.g., per-row react buttons in a list
+ *      that share a single popover instance). No click wiring; the
+ *      caller drives open state directly.
+ *
+ * If both are provided, `referenceEl` wins.
+ *
+ * Open state is `v-model:open`; if the caller doesn't bind, the
+ * component manages it internally.
+ */
+const props = withDefaults(defineProps<{
+    /** External reference element. Overrides the #trigger slot if set. */
+    referenceEl?: HTMLElement | null;
+    /** Controlled open state; two-way via v-model:open. Optional. */
+    open?: boolean;
+    placement?: Placement;
+    offset?: [number, number];
+    drawerPlacement?: DrawerPlacement;
+    /** Optional heading rendered at the top of the mobile drawer. */
+    drawerTitle?: string;
+    closeOnClickOutside?: boolean;
+    closeOnEscape?: boolean;
+    /** Close after any click inside the content (menu items etc). */
+    closeOnContentClick?: boolean;
+    /** Make the desktop popover match the trigger's width. */
+    sameWidth?: boolean;
+}>(), {
+    referenceEl: null,
+    placement: 'bottom-start',
+    offset: () => [0, 8],
+    drawerPlacement: 'bottom',
+    closeOnClickOutside: true,
+    closeOnEscape: true,
+    closeOnContentClick: false,
+    sameWidth: false
+});
+
+const emit = defineEmits<{
+    (e: 'update:open', value: boolean): void;
+}>();
+
+const { isMobile } = useBreakpoint();
+
+const internalOpen = ref(false);
+const isOpen = computed<boolean>({
+    get: () => props.open ?? internalOpen.value,
+    set: (v) => {
+        internalOpen.value = v;
+        emit('update:open', v);
+    }
+});
+
+const triggerWrapRef = ref<HTMLElement | null>(null);
+const contentEl = ref<HTMLElement | null>(null);
+
+// Resolve the popover's anchor: caller's external prop wins; otherwise
+// take the first real child of the slot wrapper. The wrapper itself uses
+// display: contents, which means its getBoundingClientRect is unreliable
+// (some browsers return zero) — reading firstElementChild gives Popper
+// a real laid-out element to position against.
+//
+// Named `anchorRef` so it doesn't shadow the `referenceEl` prop in the
+// template: `v-if="!referenceEl"` reads the prop, not this computed,
+// which avoids a mount → unmount loop when the slot wrapper's presence
+// feeds back into its own v-if condition.
+const anchorRef = computed<HTMLElement | null>(() => {
+    if (props.referenceEl) return props.referenceEl;
+    const wrap = triggerWrapRef.value;
+    if (!wrap) return null;
+    return (wrap.firstElementChild as HTMLElement | null) ?? wrap;
+});
+
+// Visibility is purely derived: desktop popover shows iff we're open
+// AND on a wide enough viewport (mobile switches to the drawer branch
+// below). Keeping this a computed — rather than a ref with three sync
+// watchers — means there's exactly one source of truth (`isOpen`) and
+// `usePopover` just reflects it.
+const popoverVisible = computed(() => !isMobile.value && isOpen.value);
+const drawerVisible = computed(() => isMobile.value && isOpen.value);
+
+usePopover(anchorRef, contentEl, {
+    placement: props.placement,
+    trigger: 'manual',
+    offset: props.offset,
+    teleportTo: 'body',
+    visible: popoverVisible,
+    closeOnClickOutside: props.closeOnClickOutside,
+    closeOnEscape: props.closeOnEscape,
+    closeOnContentClick: props.closeOnContentClick,
+    sameWidth: props.sameWidth,
+    // Surface self-close (click-outside / Escape / content click) back
+    // onto `isOpen` so the caller's v-model observes it. We only flip
+    // when `popoverVisible` is still truthy — the false branch means
+    // we're already mid-close (caller set open=false, or a mobile
+    // switch recomputed popoverVisible), and re-emitting would be
+    // redundant at best and a cycle at worst.
+    onHide: () => {
+        if (popoverVisible.value) isOpen.value = false;
+    }
+});
+
+const { placement: drawerPlace, backdropClass, panelClass, backdropTransition, panelTransition } = useDrawer({
+    visible: drawerVisible,
+    placement: props.drawerPlacement,
+    closeOnEscape: props.closeOnEscape,
+    onClose: () => { isOpen.value = false; }
+});
+
+function toggle() { isOpen.value = !isOpen.value; }
+function open() { isOpen.value = true; }
+function close() { isOpen.value = false; }
+
+// Viewport-breakpoint flip while a popover is open: usePopover's hide()
+// runs an async leave animation, so the desktop content keeps painting
+// for ~150ms while the mobile drawer is already up — both surfaces
+// visible in the same frame. Cut the leave short by zeroing the inline
+// style usePopover manages, so only the drawer is on screen.
+watch(isMobile, (mobile) => {
+    if (mobile && contentEl.value) {
+        contentEl.value.style.display = 'none';
+        contentEl.value.removeAttribute('data-show');
+    }
+});
+function onContentClick() {
+    if (props.closeOnContentClick) close();
+}
+</script>
+
+<template>
+    <!-- Trigger wrapper. display: contents makes the span layout-invisible
+         so the slot children sit directly in the caller's flex/grid flow.
+         The span still exists in the event tree, so a click anywhere inside
+         bubbles up and toggles the popover. Suppressed entirely when the
+         caller supplies an external `referenceEl`. -->
+    <span
+        v-if="!referenceEl"
+        ref="triggerWrapRef"
+        class="app-popover-trigger"
+        @click="toggle"
+    >
+        <slot name="trigger" :is-open="isOpen" :toggle="toggle" :open="open" :close="close" />
+    </span>
+
+    <!-- Desktop popover content. Always rendered so usePopover can bind on
+         mount; visibility gated by popoverVisible. -->
+    <div
+        ref="contentEl"
+        class="app-popover-content app-popover-content--hidden"
+        @click="onContentClick"
+    >
+        <slot :close="close" :is-open="isOpen" />
+    </div>
+
+    <!-- Mobile drawer. -->
+    <Teleport v-if="isMobile" to="body">
+        <Transition :name="backdropTransition">
+            <div
+                v-if="drawerVisible"
+                :class="[backdropClass, 'app-popover-drawer-backdrop']"
+                :style="{ zIndex: 2000 }"
+                @click="close"
+            />
+        </Transition>
+        <Transition :name="panelTransition">
+            <div
+                v-if="drawerVisible"
+                :class="[panelClass, 'app-popover-drawer-panel']"
+                :data-placement="drawerPlace"
+                :style="{ zIndex: 2001 }"
+                role="dialog"
+                aria-modal="true"
+                @click="onContentClick"
+            >
+                <header v-if="drawerTitle" class="app-popover-drawer-title">{{ drawerTitle }}</header>
+                <div class="app-popover-drawer-body">
+                    <slot :close="close" :is-open="isOpen" />
+                </div>
+            </div>
+        </Transition>
+    </Teleport>
+</template>
+
+<style scoped>
+.app-popover-trigger {
+    display: contents;
+}
+.app-popover-content {
+    /* Above AppModal's backdrop (1500) — popovers opened from inside a
+       modal (e.g. the forward picker's destination AppSelect) need to
+       float above the modal's surface, not behind it. The mobile drawer
+       branch below already sits at 2000/2001 for the same reason. */
+    z-index: 1600;
+}
+/* .app-popover-content--hidden no longer sets display:none — visibility is
+   managed exclusively via inline style by use-popover (see use-popover.ts).
+   Keeping the class for semantic HTML only. */
+.app-popover-drawer-panel {
+    max-height: 70vh;
+    background: var(--bg-surface);
+    border-top: 1px solid var(--border);
+    border-radius: 12px 12px 0 0;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+}
+/* Drag-handle visual cue at the screen-touching edge — mirrors AppModal's
+   bottom drawer so picker/menu drawers feel consistent with the rest of
+   the mobile chrome. Only emitted for top/bottom placements; side
+   drawers don't carry a handle. */
+.app-popover-drawer-panel[data-placement="bottom"]::before,
+.app-popover-drawer-panel[data-placement="top"]::after {
+    content: '';
+    display: block;
+    width: 36px;
+    height: 4px;
+    border-radius: 2px;
+    background: var(--text-muted);
+    opacity: 0.35;
+    flex-shrink: 0;
+}
+.app-popover-drawer-panel[data-placement="bottom"]::before {
+    margin: 0.4rem auto 0;
+}
+.app-popover-drawer-panel[data-placement="top"] {
+    border-top: none;
+    border-bottom: 1px solid var(--border);
+    border-radius: 0 0 12px 12px;
+}
+.app-popover-drawer-panel[data-placement="top"]::after {
+    margin: 0 auto 0.4rem;
+}
+.app-popover-drawer-panel[data-placement="left"],
+.app-popover-drawer-panel[data-placement="right"] {
+    max-height: 100vh;
+    border-top: none;
+    border-radius: 0;
+    max-width: 85vw;
+    width: 360px;
+}
+.app-popover-drawer-title {
+    padding: 0.75rem 1rem;
+    font-weight: 600;
+    font-size: 0.95rem;
+    color: var(--text-strong);
+    border-bottom: 1px solid var(--border);
+    flex-shrink: 0;
+}
+.app-popover-drawer-body {
+    flex: 1;
+    min-height: 0;
+    overflow-y: auto;
+    /* Belt-and-braces: fixed-width content (e.g., MediaPicker's 420px
+       picker) shouldn't ever force horizontal overflow past the drawer
+       edge. Drawer panel already has overflow: hidden but body is the
+       scrolling region. */
+    overflow-x: hidden;
+}
+</style>

package/src/components/AppSelect.vue

@@ -0,0 +1,89 @@
+<script setup lang="ts">
+import AppPopover from './AppPopover.vue';
+import type { Placement } from '../composables/use-popover';
+import type { DrawerPlacement } from '../composables/use-drawer';
+
+/**
+ * Dropdown-select layer on top of AppPopover. Same viewport split
+ * (popover desktop / drawer mobile) and the same trigger-slot + v-model
+ * control surface, plus:
+ * - A styled content wrapper (surface background, border, shadow) so
+ *   the dropdown doesn't render transparent.
+ * - `sameWidth` defaults to true so the menu matches the trigger's
+ *   width, which is the usual expectation for a <select>-style picker.
+ * - Closes on item click by default.
+ *
+ * This component is a pure wrapper — `v-model:open` and all trigger /
+ * content slots pass straight through to AppPopover, so we don't have
+ * a second copy of the open-state dance to keep in sync.
+ *
+ * AppPopover stays the underlying primitive for cases where the caller
+ * wants to style the content themselves (e.g., MediaPicker with its
+ * own surface) or doesn't want the same-width behavior.
+ */
+withDefaults(defineProps<{
+    open?: boolean;
+    placement?: Placement;
+    drawerPlacement?: DrawerPlacement;
+    drawerTitle?: string;
+    /** Close the dropdown after any click inside the menu. Default: true. */
+    closeOnItemClick?: boolean;
+    /** Make the popup width match the trigger's width. Default: true. */
+    sameWidth?: boolean;
+}>(), {
+    placement: 'bottom-start',
+    drawerPlacement: 'bottom',
+    closeOnItemClick: true,
+    sameWidth: true
+});
+
+defineEmits<{
+    (e: 'update:open', value: boolean): void;
+}>();
+</script>
+
+<template>
+    <AppPopover
+        :open="open"
+        :placement="placement"
+        :drawer-placement="drawerPlacement"
+        :drawer-title="drawerTitle"
+        :close-on-content-click="closeOnItemClick"
+        :same-width="sameWidth"
+        @update:open="(v: boolean) => $emit('update:open', v)"
+    >
+        <template #trigger="triggerScope">
+            <slot name="trigger" v-bind="triggerScope" />
+        </template>
+        <template #default="contentScope">
+            <div class="app-select-dropdown">
+                <slot v-bind="contentScope" />
+            </div>
+        </template>
+    </AppPopover>
+</template>
+
+<style scoped>
+.app-select-dropdown {
+    min-width: 180px;
+    padding: 0.25rem 0;
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-base);
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.2);
+    color: var(--text);
+    /* On mobile the dropdown renders inside AppPopover's drawer body
+       (which already provides its own surface). Flatten the local
+       chrome there so we don't double-box it. */
+}
+@media (max-width: 768px) {
+    .app-select-dropdown {
+        min-width: 0;
+        padding: 0;
+        background: transparent;
+        border: none;
+        border-radius: 0;
+        box-shadow: none;
+    }
+}
+</style>