@karyl-chan/ui 0.1.0

package/src/components/UserCard.vue

@@ -0,0 +1,274 @@
+<script setup lang="ts">
+/**
+ * UserCard — full user profile card with banner, animated avatar,
+ * display name, tag line, and slot-driven extras.
+ *
+ * Pure presentation. Mirror of the bot's DiscordUserCard chrome but
+ * with no store / router / api coupling — caller passes the resolved
+ * values directly.
+ *
+ * Animation defaults to `always` (banner + avatar) because the card
+ * is typically opened from a deliberate click — the user wants to
+ * see the animated asset they came here for. Override per-instance
+ * with `avatarAnimate` / `bannerAnimate`.
+ *
+ * Slots:
+ * - `#facts`: key/value rows under the name. Use a `<dl class="facts">`
+ *   inside, or anything you want.
+ * - `#actions`: a row of buttons under the facts (e.g. "Send DM").
+ * - `#default`: free-form content area appended to the body, useful
+ *   for plugin-specific extras (recent activity, last seen, etc.).
+ */
+import { computed } from 'vue';
+import { animatedAvatarUrl, isAnimatedBanner } from '../lib/avatar';
+import UserAvatar from './UserAvatar.vue';
+
+const props = withDefaults(defineProps<{
+    name: string;
+    /** Optional secondary display line (server-profile vs. global name divergence). */
+    nickname?: string | null;
+    /** `@username` (no `@` needed — the component renders the prefix). */
+    username?: string | null;
+    /** Discriminator (`#1234`). Rendered alongside `username` if set. */
+    discriminator?: string | null;
+    /** Avatar URL — animated detection auto-handled by UserAvatar. */
+    avatarUrl?: string | null;
+    /** Banner URL — animated detection auto-handled here. */
+    bannerUrl?: string | null;
+    /** Discord accent colour (24-bit integer). Used when there's no banner. */
+    accentColor?: number | null;
+    /** Renders a 'BOT' tag next to the name. */
+    isBot?: boolean;
+    /** Avatar animation mode. Default `always`. */
+    avatarAnimate?: 'never' | 'hover' | 'always';
+    /** Banner animation mode. Default `always`. */
+    bannerAnimate?: 'never' | 'hover' | 'always';
+    /** Skeleton mode — shows shimmer placeholders for name / facts. */
+    loading?: boolean;
+    /** Optional inline error message. */
+    error?: string | null;
+}>(), {
+    nickname: null,
+    username: null,
+    discriminator: null,
+    avatarUrl: null,
+    bannerUrl: null,
+    accentColor: null,
+    isBot: false,
+    avatarAnimate: 'always',
+    bannerAnimate: 'always',
+    loading: false,
+    error: null,
+});
+
+defineSlots<{
+    facts?: (props: Record<string, never>) => unknown;
+    actions?: (props: Record<string, never>) => unknown;
+    default?: (props: Record<string, never>) => unknown;
+}>();
+
+const bannerStyle = computed(() => {
+    if (props.loading) return { backgroundColor: 'var(--bg-surface-2)' };
+    if (props.bannerUrl) {
+        const animated =
+            props.bannerAnimate === 'always' && isAnimatedBanner(props.bannerUrl);
+        const url = animated ? animatedAvatarUrl(props.bannerUrl) : props.bannerUrl;
+        return { backgroundImage: `url(${url})` };
+    }
+    if (typeof props.accentColor === 'number') {
+        return {
+            backgroundColor: `#${props.accentColor.toString(16).padStart(6, '0')}`,
+        };
+    }
+    return { backgroundColor: 'var(--accent)' };
+});
+
+const showNicknameLine = computed(
+    () =>
+        !!props.nickname &&
+        !!props.username &&
+        props.nickname !== props.username &&
+        props.nickname !== props.name,
+);
+</script>
+
+<template>
+    <div :class="['user-card', { 'is-loading': loading }]">
+        <div :class="['banner', { 'skeleton-block': loading }]" :style="bannerStyle"></div>
+
+        <div class="avatar-wrap">
+            <UserAvatar
+                :src="avatarUrl"
+                :name="name"
+                :size="72"
+                :animate="avatarAnimate"
+                class="avatar-ring"
+            />
+        </div>
+
+        <div class="body">
+            <template v-if="loading">
+                <div class="skeleton-line skeleton-block skeleton-name"></div>
+                <div class="skeleton-line skeleton-block skeleton-tag"></div>
+                <div class="skeleton-line skeleton-block skeleton-facts"></div>
+            </template>
+
+            <template v-else>
+                <p v-if="error" class="error">{{ error }}</p>
+
+                <div class="headline">
+                    <span class="display-name">{{ name }}</span>
+                    <span v-if="isBot" class="bot-tag">BOT</span>
+                </div>
+
+                <div v-if="showNicknameLine" class="nickname">
+                    {{ nickname }}
+                </div>
+
+                <div v-if="username" class="tagline">
+                    <span class="tag">@{{ username }}<span v-if="discriminator">#{{ discriminator }}</span></span>
+                </div>
+
+                <div v-if="$slots.facts" class="facts-slot">
+                    <slot name="facts" />
+                </div>
+
+                <div v-if="$slots.actions" class="actions">
+                    <slot name="actions" />
+                </div>
+
+                <div v-if="$slots.default" class="extra">
+                    <slot />
+                </div>
+            </template>
+        </div>
+    </div>
+</template>
+
+<style scoped>
+.user-card {
+    width: 300px;
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-lg);
+    box-shadow: 0 6px 24px rgba(0, 0, 0, 0.25);
+    overflow: hidden;
+}
+@media (max-width: 768px) {
+    .user-card {
+        width: 100%;
+        border: none;
+        border-radius: 0;
+        box-shadow: none;
+    }
+}
+
+.banner {
+    height: 102px;
+    background-size: cover;
+    background-position: center;
+    background-color: var(--accent);
+}
+
+.avatar-wrap {
+    position: relative;
+    margin-top: -32px;
+    margin-left: 14px;
+    width: 72px;
+    height: 72px;
+}
+:deep(.avatar-ring) {
+    border: 4px solid var(--bg-surface);
+    background: var(--bg-surface-2);
+    /* The 4px ring is part of the visual; UserAvatar's own background
+       is overridden so the ring colour doesn't bleed through on the
+       letter-fallback path. */
+}
+
+.body {
+    padding: 0.2rem 0.9rem 0.9rem;
+    display: flex;
+    flex-direction: column;
+    gap: 0.4rem;
+}
+
+.headline {
+    display: flex;
+    align-items: center;
+    gap: 0.4rem;
+    flex-wrap: wrap;
+}
+.display-name {
+    font-weight: 700;
+    font-size: 1.05rem;
+    color: var(--text-strong);
+    overflow-wrap: anywhere;
+}
+.bot-tag {
+    background: var(--accent);
+    color: var(--text-on-accent);
+    font-size: 0.65rem;
+    font-weight: 700;
+    padding: 1px 5px;
+    border-radius: 3px;
+    line-height: 1.2;
+}
+.nickname {
+    color: var(--text);
+    font-size: 0.9rem;
+    margin-top: -0.2rem;
+}
+.tagline {
+    color: var(--text-muted);
+    font-size: 0.85rem;
+}
+.tag {
+    overflow-wrap: anywhere;
+}
+
+.facts-slot {
+    margin-top: 0.3rem;
+}
+.actions {
+    margin-top: 0.5rem;
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.4rem;
+}
+.extra {
+    margin-top: 0.4rem;
+    border-top: 1px solid var(--border);
+    padding-top: 0.5rem;
+    color: var(--text);
+    font-size: 0.85rem;
+}
+
+.skeleton-block {
+    background-color: var(--bg-surface-2);
+    background-image: linear-gradient(
+        90deg,
+        var(--bg-surface-2) 0%,
+        var(--bg-surface-hover, rgba(255, 255, 255, 0.08)) 50%,
+        var(--bg-surface-2) 100%
+    );
+    background-size: 200% 100%;
+    animation: skeleton-shimmer 1.2s linear infinite;
+}
+@keyframes skeleton-shimmer {
+    0% { background-position: 100% 0; }
+    100% { background-position: -100% 0; }
+}
+.skeleton-line {
+    height: 0.9rem;
+    border-radius: var(--radius-sm);
+}
+.skeleton-name { width: 55%; margin-top: 0.3rem; }
+.skeleton-tag { width: 35%; }
+.skeleton-facts { width: 70%; margin-top: 0.4rem; }
+
+.error {
+    color: var(--danger);
+    margin: 0.3rem 0;
+    font-size: 0.85rem;
+}
+</style>

package/src/components/UserItem.vue

@@ -0,0 +1,167 @@
+<script setup lang="ts">
+/**
+ * UserItem — compact user row (avatar + primary + secondary text +
+ * optional trailing content).
+ *
+ * Pure presentation: caller passes the data and handles `@click`
+ * themselves. Avatar defaults to hover-animation (Discord DM-list
+ * convention); pass `avatar-animate="always"` or `"never"` to override.
+ *
+ * Use the `#trailing` slot for timestamps, unread pills, action
+ * buttons, or anything that should sit on the right edge of the row.
+ * `#sub` overrides the default subtitle slot rendering when you want
+ * richer secondary content (chips, status icons, …).
+ */
+import { computed } from 'vue';
+import UserAvatar from './UserAvatar.vue';
+
+const props = withDefaults(defineProps<{
+    userId?: string;
+    avatarUrl?: string | null;
+    name: string;
+    /** Optional secondary line (username, status, last message preview, …). */
+    subtitle?: string | null;
+    /** Renders a 'BOT' tag next to the name. */
+    isBot?: boolean;
+    /** Avatar pixel size. Default 40. */
+    avatarSize?: number;
+    /** When to animate the avatar (default `hover`). */
+    avatarAnimate?: 'never' | 'hover' | 'always';
+    /** Whether the row is currently selected (e.g. active conversation). */
+    active?: boolean;
+    /** Disables interactions + dims the row. */
+    disabled?: boolean;
+    /** Tag elements as `<button>` for keyboard navigation. Default `<div>`. */
+    interactive?: boolean;
+}>(), {
+    userId: undefined,
+    avatarUrl: null,
+    subtitle: null,
+    isBot: false,
+    avatarSize: 40,
+    avatarAnimate: 'hover',
+    active: false,
+    disabled: false,
+    interactive: false,
+});
+
+defineEmits<{
+    (e: 'click'): void;
+}>();
+
+defineSlots<{
+    sub?: (props: Record<string, never>) => unknown;
+    trailing?: (props: Record<string, never>) => unknown;
+}>();
+
+const tag = computed(() => (props.interactive ? 'button' : 'div'));
+</script>
+
+<template>
+    <component
+        :is="tag"
+        :class="['user-item', { active, disabled, interactive }]"
+        :type="interactive ? 'button' : undefined"
+        :disabled="interactive && disabled ? true : undefined"
+        @click="!disabled && $emit('click')"
+    >
+        <UserAvatar
+            :src="avatarUrl"
+            :name="name"
+            :size="avatarSize"
+            :animate="avatarAnimate"
+        />
+        <div class="text">
+            <div class="row">
+                <span class="name">{{ name }}</span>
+                <span v-if="isBot" class="bot-tag">BOT</span>
+            </div>
+            <div v-if="$slots.sub || subtitle" class="sub">
+                <slot name="sub">{{ subtitle }}</slot>
+            </div>
+        </div>
+        <div v-if="$slots.trailing" class="trailing">
+            <slot name="trailing" />
+        </div>
+    </component>
+</template>
+
+<style scoped>
+.user-item {
+    display: flex;
+    align-items: center;
+    gap: 0.6rem;
+    padding: 0.45rem 0.7rem;
+    border-radius: var(--radius-base);
+    background: transparent;
+    color: var(--text);
+    width: 100%;
+    text-align: left;
+    /* button-tag defaults reset */
+    border: none;
+    font: inherit;
+}
+.user-item.interactive {
+    cursor: pointer;
+}
+.user-item.interactive:hover:not(.disabled) {
+    background: var(--bg-surface-hover);
+}
+.user-item.active {
+    background: var(--bg-surface-active);
+}
+.user-item.disabled {
+    opacity: 0.55;
+    cursor: not-allowed;
+}
+
+.text {
+    flex: 1;
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 0.05rem;
+}
+.row {
+    display: flex;
+    align-items: center;
+    gap: 0.35rem;
+    min-width: 0;
+}
+.name {
+    font-weight: 500;
+    font-size: 0.92rem;
+    color: var(--text);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    min-width: 0;
+}
+.bot-tag {
+    background: var(--accent);
+    color: var(--text-on-accent);
+    font-size: 0.6rem;
+    font-weight: 700;
+    padding: 1px 5px;
+    border-radius: 3px;
+    line-height: 1.2;
+    flex-shrink: 0;
+}
+.sub {
+    color: var(--text-muted);
+    font-size: 0.78rem;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    min-width: 0;
+}
+
+.trailing {
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    gap: 0.4rem;
+    color: var(--text-muted);
+    font-size: 0.78rem;
+}
+</style>

package/src/components/tab-types.ts

@@ -0,0 +1,9 @@
+/** Single source of truth for the `TabDef` shape consumed by both
+ *  `AppTabs` (button-only) and `AppTabsRouted` (vue-router-aware). */
+export interface TabDef {
+  key: string;
+  label: string;
+  /** Optional iconify icon name shown next to the label. */
+  icon?: string;
+  disabled?: boolean;
+}

package/src/composables/use-app-shell.ts

@@ -0,0 +1,65 @@
+import { computed, inject, onBeforeUnmount, provide, ref, type InjectionKey, type Ref } from 'vue';
+
+export type OverlayView = 'nav' | 'extras';
+
+export interface AppShellContext {
+    overlayOpen: Ref<boolean>;
+    openOverlay(): void;
+    closeOverlay(): void;
+    flushMain: Ref<boolean>;
+    setFlushMain(value: boolean): void;
+    hasExtras: Ref<boolean>;
+    overlayView: Ref<OverlayView>;
+    toggleOverlayView(): void;
+    registerExtras(): void;
+    unregisterExtras(): void;
+}
+
+const key: InjectionKey<AppShellContext> = Symbol('app-shell');
+
+export function provideAppShell(): AppShellContext {
+    const overlayOpen = ref(false);
+    const flushMain = ref(false);
+    const extrasCount = ref(0);
+    const hasExtras = computed(() => extrasCount.value > 0);
+    const overlayView = ref<OverlayView>('nav');
+
+    const ctx: AppShellContext = {
+        overlayOpen,
+        openOverlay: () => {
+            overlayOpen.value = true;
+            overlayView.value = hasExtras.value ? 'extras' : 'nav';
+        },
+        closeOverlay: () => { overlayOpen.value = false; },
+        flushMain,
+        setFlushMain: (v: boolean) => { flushMain.value = v; },
+        hasExtras,
+        overlayView,
+        toggleOverlayView: () => {
+            overlayView.value = overlayView.value === 'nav' ? 'extras' : 'nav';
+        },
+        registerExtras: () => { extrasCount.value++; },
+        unregisterExtras: () => { extrasCount.value = Math.max(0, extrasCount.value - 1); }
+    };
+
+    provide(key, ctx);
+    return ctx;
+}
+
+export function useAppShell(): AppShellContext {
+    const ctx = inject(key);
+    if (!ctx) throw new Error('useAppShell must be called within App shell');
+    return ctx;
+}
+
+export function useFlushMain(): void {
+    const { setFlushMain } = useAppShell();
+    setFlushMain(true);
+    onBeforeUnmount(() => setFlushMain(false));
+}
+
+export function useOverlayExtras(): void {
+    const { registerExtras, unregisterExtras } = useAppShell();
+    registerExtras();
+    onBeforeUnmount(unregisterExtras);
+}

package/src/composables/use-breakpoint.ts

@@ -0,0 +1,14 @@
+import { onBeforeUnmount, ref } from 'vue';
+
+const MOBILE_QUERY = '(max-width: 768px)';
+
+export function useBreakpoint() {
+    const mq = window.matchMedia(MOBILE_QUERY);
+    const isMobile = ref(mq.matches);
+    const update = (e: MediaQueryListEvent) => {
+        isMobile.value = e.matches;
+    };
+    mq.addEventListener('change', update);
+    onBeforeUnmount(() => mq.removeEventListener('change', update));
+    return { isMobile };
+}

package/src/composables/use-click-outside-stack.ts

@@ -0,0 +1,67 @@
+import { nanoid } from 'nanoid'
+
+interface StackEntry {
+    id: string
+    shouldIgnore: () => boolean
+    isInside: (target: Node) => boolean
+    close: () => void
+}
+
+const stack: StackEntry[] = []
+let listenerInstalled = false
+
+function ensureListener() {
+    if (listenerInstalled || typeof document === 'undefined') return
+    listenerInstalled = true
+
+    document.addEventListener(
+        'click',
+        (e) => {
+            const target = e.target as Node | null
+            if (!target || !document.body.contains(target)) return
+
+            // 由頂端往下走：
+            // - shouldIgnore：跳過此層繼續檢查下一層（例如同一個 click 剛觸發了 show）
+            // - isInside：停止。點擊落在這一層，該層與其下所有層都保留
+            // - 其餘：關閉此層，繼續檢查下一層，達成巢狀同時關閉
+            for (let i = stack.length - 1; i >= 0; i--) {
+                const entry = stack[i]
+                if (entry.shouldIgnore()) continue
+                if (entry.isInside(target)) break
+                entry.close()
+            }
+        },
+        true,
+    )
+}
+
+/**
+ * 統一的 overlay click-outside 管理
+ *
+ * 所有 usePopover 共用同一個 stack，點擊外部時依開啟順序（top-down）檢查：
+ * - 點擊落在某一層上 → 該層與底下保留
+ * - 點擊落在某一層外 → 關閉該層並繼續往下
+ *
+ * 這讓巢狀 popover（例如 Popover 內含 Select）在點擊真正外部時能同時關閉多層。
+ */
+export const useClickOutsideStack = () => {
+    const id = nanoid()
+
+    const register = (handlers: Omit<StackEntry, 'id'>) => {
+        // 先移除舊的（若存在），讓重新 register 時能移到 stack 頂端
+        const idx = stack.findIndex(e => e.id === id)
+        if (idx !== -1) stack.splice(idx, 1)
+        stack.push({ id, ...handlers })
+        ensureListener()
+    }
+
+    const unregister = () => {
+        const idx = stack.findIndex(e => e.id === id)
+        if (idx !== -1) stack.splice(idx, 1)
+    }
+
+    return {
+        register,
+        unregister,
+    }
+}

package/src/composables/use-color-scheme.ts

@@ -0,0 +1,75 @@
+import { ref, watch } from 'vue';
+
+/**
+ * Global colour-scheme controller.
+ *
+ * Tri-state, matching what most apps expose to users:
+ *   - `light`  — force light tokens, regardless of system.
+ *   - `dark`   — force dark tokens, regardless of system.
+ *   - `system` — follow `prefers-color-scheme` (the default).
+ *
+ * Wired up via a `data-theme` attribute on `<html>`. The token sheet
+ * (`tokens.css`) reads that attribute alongside the `prefers-color-scheme`
+ * media query, so:
+ *   - no attribute → media query decides
+ *   - `light` → light tokens win, even under system dark
+ *   - `dark` → dark tokens win, even under system light
+ *
+ * Persisted to localStorage so the choice survives reloads. Storage is a
+ * best-effort side channel — failures (privacy mode, quota, SSR) are
+ * swallowed and the in-memory state still works for the current session.
+ *
+ * Singleton: the ref is module-scoped, so every consumer sees the same
+ * value and a write from one component fans out to all of them.
+ */
+
+export type ColorScheme = 'light' | 'dark' | 'system';
+
+const STORAGE_KEY = 'karyl:color-scheme';
+
+function readStored(): ColorScheme {
+    if (typeof window === 'undefined') return 'system';
+    try {
+        const v = window.localStorage.getItem(STORAGE_KEY);
+        if (v === 'light' || v === 'dark' || v === 'system') return v;
+    } catch {
+        // localStorage may be unavailable (privacy mode, SSR-ish env).
+    }
+    return 'system';
+}
+
+function apply(scheme: ColorScheme): void {
+    if (typeof document === 'undefined') return;
+    const root = document.documentElement;
+    if (scheme === 'system') root.removeAttribute('data-theme');
+    else root.setAttribute('data-theme', scheme);
+}
+
+const current = ref<ColorScheme>(readStored());
+
+let initialized = false;
+function init(): void {
+    if (initialized) return;
+    initialized = true;
+    apply(current.value);
+    watch(current, (v) => {
+        apply(v);
+        if (typeof window === 'undefined') return;
+        try {
+            if (v === 'system') window.localStorage.removeItem(STORAGE_KEY);
+            else window.localStorage.setItem(STORAGE_KEY, v);
+        } catch {
+            // best-effort; in-memory state still wins for this session.
+        }
+    });
+}
+
+export function useColorScheme() {
+    init();
+    return {
+        colorScheme: current,
+        setColorScheme(v: ColorScheme): void {
+            current.value = v;
+        },
+    };
+}