@mkbabb/glass-ui 0.2.0

package/src/composables/interaction/useTouchGate.ts

@@ -0,0 +1,207 @@
+import { ref, onUnmounted } from "vue";
+
+/**
+ * Shared global touchstart listener registry.
+ * Instead of each useTouchGate() instance adding its own global listener,
+ * all instances register a proxy with a single shared listener.
+ */
+interface GateProxy {
+    isActive: () => boolean;
+    controlEl: () => HTMLElement | null;
+    deactivate: () => void;
+}
+
+const gateRegistry = new Set<GateProxy>();
+let sharedListenerInstalled = false;
+
+function onGlobalTouchStartShared(e: TouchEvent) {
+    for (const proxy of gateRegistry) {
+        if (!proxy.isActive()) continue;
+        const el = proxy.controlEl();
+        if (el && !el.contains(e.target as Node)) {
+            proxy.deactivate();
+        }
+    }
+}
+
+function installSharedListener() {
+    if (sharedListenerInstalled) return;
+    document.addEventListener("touchstart", onGlobalTouchStartShared, { passive: true });
+    sharedListenerInstalled = true;
+}
+
+function uninstallSharedListener() {
+    if (gateRegistry.size > 0 || !sharedListenerInstalled) return;
+    document.removeEventListener("touchstart", onGlobalTouchStartShared);
+    sharedListenerInstalled = false;
+}
+
+/**
+ * Per-control tap-to-activate pattern for mobile touch.
+ *
+ * - Desktop (no `ontouchstart`): always active — no gating.
+ * - Mobile first touch: starts a 150ms pending window. If the user scrolls
+ *   (vertical delta > 10px) during that window, activation is cancelled.
+ *   If no scroll is detected, activates after 150ms.
+ * - Mobile subsequent touch while active: interaction passes through.
+ * - After `deactivateDelayMs` of no touch, deactivates.
+ * - Tapping outside the control deactivates (shared global `touchstart` listener).
+ */
+export function useTouchGate(deactivateDelayMs = 3000) {
+    const isActive = ref(false);
+    const isTouchDevice = typeof window !== "undefined" && "ontouchstart" in window;
+
+    let deactivateTimer: ReturnType<typeof setTimeout> | null = null;
+    let pendingTimer: ReturnType<typeof setTimeout> | null = null;
+    let controlEl: HTMLElement | null = null;
+    let initialTouchY: number | null = null;
+    let isPending = false;
+    let suppressDeactivation = false;
+
+    function clearDeactivateTimer() {
+        if (deactivateTimer !== null) {
+            clearTimeout(deactivateTimer);
+            deactivateTimer = null;
+        }
+    }
+
+    function clearPendingTimer() {
+        if (pendingTimer !== null) {
+            clearTimeout(pendingTimer);
+            pendingTimer = null;
+        }
+        isPending = false;
+        initialTouchY = null;
+    }
+
+    function resetTimer() {
+        clearDeactivateTimer();
+        deactivateTimer = setTimeout(() => {
+            deactivate();
+        }, deactivateDelayMs);
+    }
+
+    function activate(el: HTMLElement) {
+        isActive.value = true;
+        el.style.touchAction = "none";
+        resetTimer();
+    }
+
+    function suppressDeactivate(suppress: boolean) {
+        suppressDeactivation = suppress;
+        if (suppress) {
+            clearDeactivateTimer();
+        } else {
+            resetTimer();
+        }
+    }
+
+    function deactivate() {
+        if (suppressDeactivation) return;
+        clearDeactivateTimer();
+        clearPendingTimer();
+        isActive.value = false;
+        if (controlEl) {
+            controlEl.style.touchAction = "";
+            controlEl = null;
+        }
+    }
+
+    /**
+     * Call on touchstart / pointerdown of the gated control.
+     * On mobile, the first touch starts a 150ms pending window.
+     * Returns `true` if the control is already active and interaction should proceed.
+     */
+    function handleTouchStart(el: HTMLElement, clientY: number): boolean {
+        if (!isTouchDevice) return true;
+
+        controlEl = el;
+
+        if (isActive.value) {
+            resetTimer();
+            return true; // already active — process the interaction
+        }
+
+        // Clear any previous pending timer, then start new pending window
+        clearPendingTimer();
+        isPending = true;
+        initialTouchY = clientY;
+
+        pendingTimer = setTimeout(() => {
+            // No scroll detected within the window — activate
+            if (isPending) {
+                isPending = false;
+                initialTouchY = null;
+                activate(el);
+            }
+        }, 150);
+
+        return false; // activation pending — don't process yet
+    }
+
+    /**
+     * Call on touchmove. If still in the pending window and vertical delta
+     * exceeds 10px, cancel activation (user is scrolling).
+     */
+    function handleScrollCheck(event: TouchEvent): void {
+        if (!isTouchDevice || !isPending || initialTouchY === null) return;
+
+        const currentY = event.touches[0]?.clientY ?? 0;
+        const delta = Math.abs(currentY - initialTouchY);
+
+        if (delta > 10) {
+            // User is scrolling — cancel activation
+            clearPendingTimer();
+        }
+    }
+
+    function handleTouchEnd(): void {
+        if (!isTouchDevice) return;
+        if (isPending && controlEl) {
+            // Finger lifted during pending window without scrolling —
+            // this is a genuine tap. Activate immediately.
+            clearPendingTimer();
+            activate(controlEl);
+            return;
+        }
+        if (isActive.value) {
+            resetTimer();
+        }
+    }
+
+    // Register with shared global listener instead of adding our own
+    const proxy: GateProxy = {
+        isActive: () => isActive.value,
+        controlEl: () => controlEl,
+        deactivate,
+    };
+
+    if (isTouchDevice) {
+        gateRegistry.add(proxy);
+        installSharedListener();
+    }
+
+    onUnmounted(() => {
+        clearDeactivateTimer();
+        clearPendingTimer();
+        if (isTouchDevice) {
+            gateRegistry.delete(proxy);
+            uninstallSharedListener();
+        }
+        if (controlEl) {
+            controlEl.style.touchAction = "";
+            controlEl = null;
+        }
+    });
+
+    return {
+        isActive,
+        isTouchDevice,
+        handleTouchStart,
+        handleScrollCheck,
+        handleTouchEnd,
+        resetTimer,
+        deactivate,
+        suppressDeactivate,
+    };
+}

package/src/composables/pagination/index.ts

@@ -0,0 +1,2 @@
+export { useOffsetPagination } from "./useOffsetPagination";
+export type { OffsetPaginationOptions } from "./useOffsetPagination";

package/src/composables/pagination/useOffsetPagination.ts

@@ -0,0 +1,70 @@
+import { ref, computed, type Ref } from "vue";
+
+export interface OffsetPaginationOptions<T> {
+    fetchFn: (limit: number, offset: number) => Promise<{ data: T[]; total: number }>;
+    pageSize?: number;
+}
+
+/**
+ * Composable for offset-based pagination with page navigation.
+ * Suitable for admin views that need jump-to-page and stable positions.
+ */
+export function useOffsetPagination<T>(options: OffsetPaginationOptions<T>) {
+    const items = ref<T[]>([]) as Ref<T[]>;
+    const total = ref(0);
+    const page = ref(1);
+    const pageSize = ref(options.pageSize ?? 20);
+    const loading = ref(false);
+    const error = ref<string | null>(null);
+
+    const pageCount = computed(() => Math.max(1, Math.ceil(total.value / pageSize.value)));
+    const offset = computed(() => (page.value - 1) * pageSize.value);
+    const hasNext = computed(() => page.value < pageCount.value);
+    const hasPrev = computed(() => page.value > 1);
+
+    async function loadPage(p?: number) {
+        if (p != null) page.value = Math.max(1, Math.min(p, pageCount.value || 1));
+        loading.value = true;
+        error.value = null;
+
+        try {
+            const res = await options.fetchFn(pageSize.value, offset.value);
+            items.value = res.data;
+            total.value = res.total;
+        } catch (e) {
+            error.value = e instanceof Error ? e.message : "Failed to load";
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    function nextPage() {
+        if (hasNext.value) loadPage(page.value + 1);
+    }
+
+    function prevPage() {
+        if (hasPrev.value) loadPage(page.value - 1);
+    }
+
+    function reset() {
+        page.value = 1;
+        items.value = [];
+        total.value = 0;
+    }
+
+    return {
+        items,
+        total,
+        page,
+        pageSize,
+        pageCount,
+        loading,
+        error,
+        hasNext,
+        hasPrev,
+        loadPage,
+        nextPage,
+        prevPage,
+        reset,
+    };
+}

package/src/composables/prng.ts

@@ -0,0 +1,32 @@
+/** Mulberry32 — fast 32-bit seeded PRNG */
+export function mulberry32(seed: number) {
+    return () => {
+        seed |= 0;
+        seed = (seed + 0x6d2b79f5) | 0;
+        let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+
+/** Simple string->u32 hash (djb2) */
+export function hashString(str: string): number {
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+        hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0;
+    }
+    return hash >>> 0;
+}
+
+/** Generate 8 random border-radius values in [lo, hi] using the given PRNG */
+export function randomRadii(rng: () => number, lo: number, hi: number): number[] {
+    const out: number[] = [];
+    for (let i = 0; i < 8; i++) {
+        out.push(lo + rng() * (hi - lo));
+    }
+    return out;
+}
+
+export function radiiToCSS(r: number[]): string {
+    return `${r[0]}% ${r[1]}% ${r[2]}% ${r[3]}% / ${r[4]}% ${r[5]}% ${r[6]}% ${r[7]}%`;
+}

package/src/composables/useCharSplit.ts

@@ -0,0 +1,31 @@
+import { computed, type MaybeRef, toValue } from "vue";
+
+/**
+ * Splits text into per-character `<span>` elements with `--char-index` CSS custom
+ * properties for staggered animation. Use with the `.char-stagger` CSS class.
+ *
+ * @example
+ * ```vue
+ * <template>
+ *   <h1 class="char-stagger" v-html="chars" />
+ * </template>
+ * <script setup>
+ * const chars = useCharSplit('Hello World');
+ * </script>
+ * ```
+ */
+export function useCharSplit(text: MaybeRef<string>) {
+    return computed(() => {
+        const str = toValue(text);
+        return Array.from(str)
+            .map((char, i) => {
+                if (char === " ") return " ";
+                const escaped = char
+                    .replace(/&/g, "&amp;")
+                    .replace(/</g, "&lt;")
+                    .replace(/>/g, "&gt;");
+                return `<span class="char" style="--char-index:${i}">${escaped}</span>`;
+            })
+            .join("");
+    });
+}

package/src/composables/useClipboard.ts

@@ -0,0 +1,46 @@
+/**
+ * Fallback clipboard copy using a temporary textarea.
+ * Works on iOS Safari where navigator.clipboard may not be available.
+ */
+function copyViaTextarea(text: string): boolean {
+    const textarea = document.createElement("textarea");
+    textarea.value = text;
+    textarea.style.position = "fixed";
+    textarea.style.left = "-9999px";
+    textarea.style.top = "-9999px";
+    textarea.style.opacity = "0";
+    document.body.appendChild(textarea);
+    textarea.focus();
+    textarea.setSelectionRange(0, text.length);
+    let ok = false;
+    try {
+        ok = document.execCommand("copy");
+    } catch {
+        ok = false;
+    }
+    document.body.removeChild(textarea);
+    return ok;
+}
+
+/**
+ * Copy text to clipboard.
+ * Uses navigator.clipboard.writeText with textarea fallback for mobile.
+ * Returns true on success, false on failure.
+ */
+export async function copyToClipboard(text: string, _label?: string): Promise<boolean> {
+    if (!text) return false;
+
+    try {
+        if (navigator.clipboard?.writeText) {
+            await navigator.clipboard.writeText(text);
+        } else if (!copyViaTextarea(text)) {
+            throw new Error("execCommand failed");
+        }
+        return true;
+    } catch {
+        if (copyViaTextarea(text)) {
+            return true;
+        }
+        return false;
+    }
+}

package/src/composables/useGlobalDark.ts

@@ -0,0 +1,61 @@
+import { createGlobalState, useDark, useToggle } from "@vueuse/core";
+import { ref, watch } from "vue";
+
+export interface UseGlobalDarkOptions {
+    /**
+     * When true, temporarily adds `no-transition` class to `<html>` during
+     * dark mode toggle to prevent CSS transition jank on pages with many
+     * transitioned elements.
+     *
+     * Requires the `.no-transition` utility rule in glass-ui's utilities.css.
+     * @default false
+     */
+    disableTransitions?: boolean;
+}
+
+/** Single shared dark mode instance — avoids multiple useDark() watchers racing on classList. */
+export const useGlobalDark = createGlobalState(() => {
+    const isDark = useDark({ disableTransition: false });
+    const _toggle = useToggle(isDark);
+    const disableTransitions = ref(false);
+
+    /**
+     * Toggle dark mode. When `disableTransitions` is enabled (via
+     * `setDisableTransitions`), CSS transitions are suppressed for the
+     * duration of the toggle to avoid visual jank.
+     */
+    function toggleDark() {
+        if (disableTransitions.value) {
+            document.documentElement.classList.add("no-transition");
+            // Force reflow so the class takes effect before the toggle
+            void document.documentElement.offsetHeight;
+        }
+
+        _toggle();
+
+        if (disableTransitions.value) {
+            requestAnimationFrame(() => {
+                document.documentElement.classList.remove("no-transition");
+            });
+        }
+    }
+
+    /** Configure whether transitions are suppressed during dark mode toggle. */
+    function setDisableTransitions(value: boolean) {
+        disableTransitions.value = value;
+    }
+
+    // Safari: force style recalculation after .dark class toggle.
+    // WebKit doesn't always invalidate CSS custom properties when an ancestor
+    // class changes. Mirroring color-scheme as an inline style on <html> forces
+    // a full cascade recalculation.
+    watch(
+        isDark,
+        (dark) => {
+            document.documentElement.style.colorScheme = dark ? "dark" : "light";
+        },
+        { immediate: true },
+    );
+
+    return { isDark, toggleDark, disableTransitions, setDisableTransitions };
+});

package/src/composables/useKeyboardShortcuts.ts

@@ -0,0 +1,205 @@
+import { createGlobalState, useEventListener } from "@vueuse/core";
+import { computed, onScopeDispose, ref } from "vue";
+
+export interface ShortcutOptions {
+    /** Fire even when focus is in input/textarea/contenteditable. Default: false */
+    allowInInput?: boolean;
+    /** Call preventDefault on the event. Default: false */
+    preventDefault?: boolean;
+    /** Human-readable label for the shortcuts modal */
+    label?: string;
+    /** Group name for display (e.g. "Playback", "Navigation") */
+    group?: string;
+}
+
+export interface RegisteredShortcut {
+    combo: ParsedCombo;
+    raw: string;
+    handler: (e: KeyboardEvent) => void;
+    options: ShortcutOptions;
+}
+
+interface ParsedCombo {
+    key: string;
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+    alt: boolean;
+    mod: boolean; // Mod = Meta on mac, Ctrl elsewhere
+}
+
+export const isMac =
+    typeof navigator !== "undefined" &&
+    /Mac|iPhone|iPad|iPod/.test(navigator.platform);
+
+function parseCombo(combo: string): ParsedCombo {
+    const parts = combo.split("+").map((p) => p.trim());
+    const parsed: ParsedCombo = {
+        key: "",
+        ctrl: false,
+        meta: false,
+        shift: false,
+        alt: false,
+        mod: false,
+    };
+
+    for (const part of parts) {
+        const lower = part.toLowerCase();
+        if (lower === "mod") parsed.mod = true;
+        else if (lower === "ctrl" || lower === "control") parsed.ctrl = true;
+        else if (lower === "meta" || lower === "cmd" || lower === "command")
+            parsed.meta = true;
+        else if (lower === "shift") parsed.shift = true;
+        else if (lower === "alt" || lower === "option") parsed.alt = true;
+        else parsed.key = part; // Preserve original case for e.key matching
+    }
+
+    return parsed;
+}
+
+/** Normalize key aliases so registrations like "Space" or "Delete" work cross-platform. */
+const KEY_ALIASES: Record<string, string[]> = {
+    space: [" "],
+    delete: ["backspace", "delete"],
+    enter: ["enter", "return"],
+    escape: ["escape", "esc"],
+};
+
+function matchesCombo(e: KeyboardEvent, combo: ParsedCombo): boolean {
+    // Check modifiers
+    const wantCtrl = combo.ctrl || (combo.mod && !isMac);
+    const wantMeta = combo.meta || (combo.mod && isMac);
+
+    if (e.ctrlKey !== wantCtrl) return false;
+    if (e.metaKey !== wantMeta) return false;
+    if (e.altKey !== combo.alt) return false;
+
+    // For printable chars that inherently require shift (e.g. "?", "!", "+"),
+    // don't enforce shift match unless shift was explicitly in the combo.
+    const isPrintableShifted = e.key.length === 1 && e.shiftKey && !combo.shift;
+    if (!isPrintableShifted && e.shiftKey !== combo.shift) return false;
+
+    const comboKeyLower = combo.key.toLowerCase();
+    const eventKeyLower = e.key.toLowerCase();
+
+    // Direct match
+    if (eventKeyLower === comboKeyLower) return true;
+
+    // Alias match (e.g. combo "Space" matches e.key " ")
+    const aliases = KEY_ALIASES[comboKeyLower];
+    if (aliases && aliases.some((a) => a.toLowerCase() === eventKeyLower)) return true;
+
+    // Also match against e.code (e.g. "Space", "Delete", "Backspace")
+    if (e.code.toLowerCase() === comboKeyLower) return true;
+
+    return false;
+}
+
+function isEditableTarget(el: Element | null): boolean {
+    if (!el) return false;
+    const tag = (el as HTMLElement).tagName;
+    if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return true;
+    if ((el as HTMLElement).isContentEditable) return true;
+    if (el.closest(".monaco-editor")) return true;
+    return false;
+}
+
+/** Format a single combo part to its display symbol. */
+function formatPart(p: string): string {
+    const lower = p.trim().toLowerCase();
+    if (lower === "mod") return isMac ? "\u2318" : "Ctrl";
+    if (lower === "shift") return isMac ? "\u21E7" : "Shift";
+    if (lower === "alt" || lower === "option") return isMac ? "\u2325" : "Alt";
+    if (lower === "ctrl" || lower === "control") return isMac ? "\u2303" : "Ctrl";
+    if (lower === "meta" || lower === "cmd") return "\u2318";
+    if (lower === "space") return isMac ? "\u2423" : "Space";
+    if (lower === "arrowleft") return "\u2190";
+    if (lower === "arrowright") return "\u2192";
+    if (lower === "arrowup") return "\u2191";
+    if (lower === "arrowdown") return "\u2193";
+    if (lower === "delete") return isMac ? "\u232B" : "Del";
+    if (lower === "escape") return "Esc";
+    if (lower === "enter") return "\u23CE";
+    if (lower === "home") return "Home";
+    if (lower === "end") return "End";
+    return p.trim();
+}
+
+/** Format a combo string into individual display parts (for rendering as separate <kbd> elements). */
+export function formatComboParts(raw: string): string[] {
+    return raw.split("+").map(formatPart);
+}
+
+/** Format a combo string for display (resolve Mod to platform symbol). */
+export function formatCombo(raw: string): string {
+    return formatComboParts(raw).join(isMac ? "" : "+");
+}
+
+const useShortcutRegistry = createGlobalState(() => {
+    const shortcuts = new Set<RegisteredShortcut>();
+    const version = ref(0);
+
+    useEventListener(window, "keydown", (e: KeyboardEvent) => {
+        for (const shortcut of shortcuts) {
+            if (!matchesCombo(e, shortcut.combo)) continue;
+
+            if (
+                !shortcut.options.allowInInput &&
+                isEditableTarget(e.target as Element)
+            ) {
+                continue;
+            }
+
+            if (shortcut.options.preventDefault) {
+                e.preventDefault();
+            }
+
+            shortcut.handler(e);
+            return; // First match wins
+        }
+    });
+
+    const labeled = computed(() => {
+        version.value;
+        return [...shortcuts].filter((s) => s.options.label);
+    });
+
+    return { shortcuts, version, labeled };
+});
+
+/**
+ * Register a keyboard shortcut. Returns cleanup function.
+ * Auto-disposed when the current effect scope is disposed.
+ */
+export function registerShortcut(
+    combo: string,
+    handler: (e: KeyboardEvent) => void,
+    options: ShortcutOptions = {},
+): () => void {
+    const { shortcuts, version } = useShortcutRegistry();
+
+    const entry: RegisteredShortcut = {
+        combo: parseCombo(combo),
+        raw: combo,
+        handler,
+        options,
+    };
+
+    shortcuts.add(entry);
+    version.value++;
+
+    const cleanup = () => {
+        shortcuts.delete(entry);
+        version.value++;
+    };
+
+    onScopeDispose(cleanup);
+
+    return cleanup;
+}
+
+/** Get all labeled shortcuts (reactive). */
+export function useRegisteredShortcuts() {
+    const { labeled } = useShortcutRegistry();
+    return labeled;
+}