@mkbabb/glass-ui 0.2.0

package/src/components/custom/dock/composables/useDockActionBar.ts

@@ -0,0 +1,33 @@
+/**
+ * Generic dock action bar system.
+ *
+ * Any view can provide a DockActionBar — a list of actions with icons,
+ * titles, and callbacks. The dock renders them as dock-icon-btn buttons.
+ */
+
+import type { Component, InjectionKey, Ref } from "vue";
+
+export interface DockAction {
+    key: string;
+    icon: Component;
+    title: string;
+    description: string;
+    rotateOnClick?: boolean;
+    iconClass?: string;
+    disabled?: boolean;
+    handler: () => void;
+}
+
+export interface DockActionBar {
+    /** The label shown next to the Tools toggle button */
+    label: string;
+    /** Icon for the Tools toggle */
+    icon: Component;
+    /** Accent color for the action bar */
+    accentColor?: string;
+    /** The actions to display in the dock */
+    actions: Ref<DockAction[]>;
+}
+
+export const DOCK_ACTION_BAR_KEY: InjectionKey<Ref<DockActionBar | null>> =
+    Symbol("dockActionBar");

package/src/components/custom/dock/composables/useDockState.ts

@@ -0,0 +1,301 @@
+import { ref, watch, onUnmounted, provide, inject } from "vue";
+import type { Ref } from "vue";
+import { isTeleportedTarget } from "./isTeleportedTarget";
+
+export interface UseDockStateOptions {
+    /** Delay before auto-collapse after mouse leaves (ms) */
+    collapseDelay?: number;
+    /** Root element ref — used for contains() checks */
+    rootEl: Ref<HTMLElement | null>;
+    /** Disable collapse behavior and keep the dock expanded. */
+    alwaysExpanded?: Ref<boolean> | boolean;
+    /** Called on every state transition */
+    onStateChange?: (newState: DockState, oldState: DockState) => void;
+}
+
+export type DockState = "collapsed" | "hover" | "pinned";
+
+/**
+ * Dock state machine with three states and ref-counted child holds.
+ *
+ * ```
+ * State Machine:
+ *   COLLAPSED ──(mouseenter/focusin)──→ HOVER
+ *   HOVER ──(mouseleave + timeout)──→ COLLAPSED
+ *   HOVER ──(clickCollapsed)──→ PINNED
+ *   PINNED ──(clickOutside)──→ COLLAPSED
+ *   Any ──(alwaysExpanded=true)──→ PINNED
+ *
+ * keepOpen/release ref-counting prevents TIMER-BASED collapse
+ * but NOT explicit click-away dismissal (onPointerDownOutside).
+ *
+ * Teleported targets (reka-ui portals, floating panels, dock popovers)
+ * are treated as "inside the dock" for mouse/focus/click-away purposes.
+ * ```
+ */
+export function useDockState(options: UseDockStateOptions) {
+    const { collapseDelay = 2500, rootEl, alwaysExpanded = false, onStateChange } = options;
+
+    const getAlwaysExpanded = () =>
+        typeof alwaysExpanded === "boolean" ? alwaysExpanded : alwaysExpanded.value;
+
+    const initiallyExpanded = getAlwaysExpanded();
+    const state = ref<DockState>(initiallyExpanded ? "pinned" : "collapsed");
+    const expanded = ref(initiallyExpanded);
+    const isPinned = ref(initiallyExpanded);
+
+    let collapseTimer: ReturnType<typeof setTimeout> | null = null;
+    let keepOpenCount = 0;
+    let removeClickAway: (() => void) | null = null;
+    let isCollapsing = false;
+
+    // Suppress events briefly after mount to avoid phantom triggers
+    let ignoreEvents = true;
+    setTimeout(() => {
+        ignoreEvents = false;
+    }, 600);
+
+    let prevState: DockState = state.value;
+    function syncDerived() {
+        if (getAlwaysExpanded()) {
+            state.value = "pinned";
+        }
+        expanded.value = state.value !== "collapsed";
+        isPinned.value = state.value === "pinned";
+        if (onStateChange && prevState !== state.value) {
+            onStateChange(state.value, prevState);
+        }
+        prevState = state.value;
+    }
+
+    function clearTimer() {
+        if (collapseTimer) {
+            clearTimeout(collapseTimer);
+            collapseTimer = null;
+        }
+    }
+
+    function scheduleCollapse() {
+        if (getAlwaysExpanded()) return;
+        if (keepOpenCount > 0) return;
+        clearTimer();
+        collapseTimer = setTimeout(() => {
+            dismissOpenOverlays();
+            state.value = "collapsed";
+            syncDerived();
+        }, collapseDelay);
+    }
+
+    function dismissOpenOverlays() {
+        // Close any open reka-ui portals by programmatically clicking the document body.
+        // This triggers reka-ui's native "dismiss on outside click" without interfering
+        // with keyboard shortcut listeners (Escape would stop animations, etc.).
+        const active = document.querySelector(
+            '[data-reka-menu-content][data-state="open"], ' +
+            '[data-reka-popper-content-wrapper]'
+        );
+        if (active) {
+            // Pointer event outside the portal triggers reka-ui's onPointerDownOutside
+            document.body.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, composed: true }));
+        }
+    }
+
+    function collapse() {
+        if (getAlwaysExpanded()) {
+            state.value = "pinned";
+            syncDerived();
+            return;
+        }
+        if (isCollapsing) return;
+        isCollapsing = true;
+        clearTimer();
+        dismissOpenOverlays();
+        state.value = "collapsed";
+        syncDerived();
+        isCollapsing = false;
+    }
+
+    function expand() {
+        if (getAlwaysExpanded()) {
+            state.value = "pinned";
+            syncDerived();
+            return;
+        }
+        if (ignoreEvents) return;
+        clearTimer();
+        state.value = "hover";
+        syncDerived();
+    }
+
+    // --- Mouse handlers ---
+
+    function onMouseEnter() {
+        if (getAlwaysExpanded()) return;
+        if (ignoreEvents) return;
+        clearTimer();
+        if (state.value === "collapsed") {
+            state.value = "hover";
+            syncDerived();
+        }
+        // If pinned, no-op (stays pinned)
+    }
+
+    function onMouseLeave(e?: MouseEvent) {
+        if (getAlwaysExpanded()) return;
+        if (state.value === "hover") {
+            // Something is explicitly holding the dock open (dropdown, edit, etc.)
+            if (keepOpenCount > 0) return;
+            // Mouse moved to a descendant or teleported child (dropdown, popover)
+            if (e) {
+                const root = rootEl.value;
+                if (
+                    root &&
+                    e.relatedTarget instanceof Node &&
+                    root.contains(e.relatedTarget)
+                )
+                    return;
+                if (isTeleportedTarget(e.relatedTarget)) return;
+            }
+            scheduleCollapse();
+        }
+        // If pinned, no-op (stays pinned)
+    }
+
+    // --- Focus handlers ---
+
+    function onFocusIn() {
+        if (getAlwaysExpanded()) return;
+        if (ignoreEvents) return;
+        clearTimer();
+        if (state.value === "collapsed") {
+            state.value = "hover";
+            syncDerived();
+        }
+    }
+
+    function onFocusOut(e: FocusEvent) {
+        if (getAlwaysExpanded()) return;
+        if (state.value !== "hover") return;
+        if (keepOpenCount > 0) return;
+        const root = e.currentTarget as HTMLElement;
+        if (e.relatedTarget && root.contains(e.relatedTarget as Node)) return;
+        // Focus moved to a teleported element (dropdown content, select, popover)
+        if (isTeleportedTarget(e.relatedTarget)) return;
+        scheduleCollapse();
+    }
+
+    // --- Click on collapsed layer → PINNED ---
+
+    function onClickCollapsed() {
+        if (getAlwaysExpanded()) {
+            state.value = "pinned";
+            syncDerived();
+            return;
+        }
+        clearTimer();
+        state.value = "pinned";
+        syncDerived();
+    }
+
+    // --- keepOpen / release (ref-counted child holds) ---
+
+    function keepOpen() {
+        keepOpenCount++;
+        clearTimer();
+    }
+
+    function release() {
+        keepOpenCount = Math.max(0, keepOpenCount - 1);
+        if (keepOpenCount === 0 && state.value === "hover") {
+            // Grace period: don't collapse immediately after a child releases
+            // (e.g., dialog dismissed via Escape). Give the user time to re-engage.
+            clearTimer();
+            collapseTimer = setTimeout(() => {
+                if (keepOpenCount === 0 && state.value === "hover") {
+                    scheduleCollapse();
+                }
+            }, Math.min(collapseDelay, 800));
+        }
+    }
+
+    // Provide for descendant components
+    provide("dockKeepOpen", keepOpen);
+    provide("dockRelease", release);
+    provide("dockExpanded", expanded);
+
+    // --- Click-away listener ---
+
+    function onPointerDownOutside(e: PointerEvent) {
+        if (getAlwaysExpanded()) return;
+        const root = rootEl.value;
+        if (!root || root.contains(e.target as Node)) return;
+        if (isTeleportedTarget(e.target)) return;
+
+        // Click outside → always collapse, even if keepOpenCount > 0
+        // (keepOpenCount prevents timer-based collapse, not explicit dismissal)
+        collapse();
+    }
+
+    watch(expanded, (isExpanded) => {
+        if (isExpanded) {
+            // Defer attachment past the current event's propagation.
+            // nextTick alone isn't enough — the opening pointerdown can still
+            // reach a capture-phase listener attached in the same microtask.
+            // requestAnimationFrame ensures we wait until the next frame.
+            requestAnimationFrame(() => {
+                document.addEventListener(
+                    "pointerdown",
+                    onPointerDownOutside,
+                    true,
+                );
+                removeClickAway = () => {
+                    document.removeEventListener(
+                        "pointerdown",
+                        onPointerDownOutside,
+                        true,
+                    );
+                    removeClickAway = null;
+                };
+            });
+        } else {
+            removeClickAway?.();
+        }
+    });
+
+    if (typeof alwaysExpanded !== "boolean") {
+        watch(alwaysExpanded, (forceOpen) => {
+            if (forceOpen) {
+                clearTimer();
+                state.value = "pinned";
+                syncDerived();
+                return;
+            }
+            state.value = "collapsed";
+            syncDerived();
+        }, { immediate: true });
+    } else if (alwaysExpanded) {
+        state.value = "pinned";
+        syncDerived();
+    }
+
+    // Cleanup
+    onUnmounted(() => {
+        clearTimer();
+        removeClickAway?.();
+    });
+
+    return {
+        state,
+        expanded,
+        isPinned,
+        onMouseEnter,
+        onMouseLeave,
+        onFocusIn,
+        onFocusOut,
+        onClickCollapsed,
+        keepOpen,
+        release,
+        expand,
+        collapse,
+    };
+}

package/src/components/custom/dock/composables/useDockTransition.ts

@@ -0,0 +1,146 @@
+import { ref, watch, nextTick, onUnmounted } from "vue";
+import type { Ref } from "vue";
+
+export interface UseDockTransitionOptions {
+    /** The logical expanded state (from useDockState) */
+    expanded: Ref<boolean>;
+    /** The dock root element ref — width is animated on this element */
+    rootEl: Ref<HTMLElement | null>;
+    /** Fade duration in ms before the layer swap (default: 60) */
+    fadeMs?: number;
+    /** When true, skip all width-pinning transitions (dock is always open) */
+    alwaysExpanded?: Ref<boolean>;
+}
+
+/**
+ * Orchestrates a deferred layer-swap transition for dock components.
+ *
+ * Both expand and collapse follow the same sequence:
+ *   fade out → swap layer → animate width → fade in
+ *
+ * Width animation is driven through a reactive ref (`transitionWidth`)
+ * so it cooperates with Vue's reactive :style bindings.
+ */
+export function useDockTransition(options: UseDockTransitionOptions) {
+    const { expanded, rootEl, fadeMs = 60, alwaysExpanded } = options;
+
+    const visualExpanded = ref(expanded.value);
+    const isTransitioning = ref(false);
+
+    /**
+     * Reactive width applied during transitions via :style.
+     * `null` means "no override — use natural sizing".
+     */
+    const transitionWidth = ref<string | null>(null);
+
+    /**
+     * When true, CSS transitions on the dock are suppressed.
+     * Used during the measure phase so width changes don't animate.
+     */
+    const suppressTransition = ref(false);
+
+    let fadeTimer: ReturnType<typeof setTimeout> | null = null;
+
+    function clearFadeTimer() {
+        if (fadeTimer) {
+            clearTimeout(fadeTimer);
+            fadeTimer = null;
+        }
+    }
+
+    let transitionId = 0;
+
+    watch(expanded, () => {
+        if (alwaysExpanded?.value) {
+            visualExpanded.value = expanded.value;
+            return;
+        }
+
+        const el = rootEl.value;
+        if (!el) return;
+
+        clearFadeTimer();
+        const id = ++transitionId;
+
+        // Capture current width before any changes
+        const from = el.getBoundingClientRect().width;
+
+        // Pin width so the layer swap can't cause a resize jump
+        suppressTransition.value = true;
+        transitionWidth.value = `${from}px`;
+
+        // Phase 1: fade out (visualExpanded still shows OLD layer)
+        isTransitioning.value = true;
+
+        // Phase 2: after fade completes, swap layer and animate width
+        fadeTimer = setTimeout(() => {
+            fadeTimer = null;
+            if (id !== transitionId) return;
+
+            // Swap layers while content is invisible
+            visualExpanded.value = expanded.value;
+
+            // Wait for Vue to flush the layer swap, then measure target width
+            nextTick(() => {
+                if (id !== transitionId) return;
+
+                // Release width to measure natural target (still no transitions)
+                transitionWidth.value = null;
+
+                nextTick(() => {
+                    if (id !== transitionId) return;
+
+                    const to = el.getBoundingClientRect().width;
+
+                    // If from ≈ to, no animation needed
+                    if (Math.abs(from - to) < 1) {
+                        suppressTransition.value = false;
+                        transitionWidth.value = null;
+                        isTransitioning.value = false;
+                        return;
+                    }
+
+                    // Pin back to old width (still suppressed)
+                    transitionWidth.value = `${from}px`;
+
+                    // Let Vue flush the pinned width, then enable transitions and animate
+                    nextTick(() => {
+                        if (id !== transitionId) return;
+
+                        // Force the browser to commit the from-width
+                        el.offsetWidth;
+
+                        // Re-enable CSS transitions and set target width
+                        suppressTransition.value = false;
+
+                        // rAF ensures the browser has painted the from-width
+                        // before we set the to-width, guaranteeing the transition fires
+                        requestAnimationFrame(() => {
+                            if (id !== transitionId) return;
+                            transitionWidth.value = `${to}px`;
+                        });
+                    });
+                });
+            });
+        }, fadeMs);
+    });
+
+    /** Call from @transitionend on the root element. */
+    function onTransitionEnd(e: TransitionEvent) {
+        if (e.target !== rootEl.value) return;
+        if (e.propertyName === "width") {
+            transitionWidth.value = null;
+            isTransitioning.value = false;
+        }
+    }
+
+    onUnmounted(clearFadeTimer);
+
+    return {
+        visualExpanded,
+        isTransitioning,
+        transitionWidth,
+        suppressTransition,
+        onTransitionEnd,
+    };
+}

package/src/components/custom/dock/composables/useLayerTransition.ts

@@ -0,0 +1,135 @@
+import { ref, watch, nextTick, onUnmounted } from "vue";
+import type { Ref } from "vue";
+
+export interface UseLayerTransitionOptions {
+    /** The container element (must have `.dock-layer-grid` class) */
+    containerEl: Ref<HTMLElement | null>;
+    /** The currently active layer id */
+    activeLayer: Ref<string>;
+}
+
+export interface UseLayerTransitionReturn {
+    /** Returns class array + inert for a given layer id */
+    layerProps(id: string): { class: string[]; inert: true | undefined };
+    /** Attach to @transitionend on the container */
+    onTransitionEnd(e: TransitionEvent): void;
+}
+
+/**
+ * Coordinates simultaneous crossfade + FLIP width animation for
+ * grid-stacked layer containers. Reusable at any nesting level.
+ *
+ * Algorithm on activeLayer change:
+ * 1. Capture current container width
+ * 2. Pin container to that width
+ * 3. Swap classes: old layer → leaving (absolute, fading out),
+ *    new layer → active (relative, fading in)
+ * 4. nextTick: measure new natural width, re-pin to old
+ * 5. Animate to new width via CSS transition
+ * 6. On transitionend(width), clear inline width
+ */
+export function useLayerTransition(
+    options: UseLayerTransitionOptions,
+): UseLayerTransitionReturn {
+    const { containerEl, activeLayer } = options;
+
+    const currentLayer = ref(activeLayer.value);
+    const leavingLayer = ref<string | null>(null);
+    let transitionId = 0;
+    let cleanupTimer: ReturnType<typeof setTimeout> | null = null;
+
+    function clearCleanup() {
+        if (cleanupTimer) {
+            clearTimeout(cleanupTimer);
+            cleanupTimer = null;
+        }
+    }
+
+    watch(activeLayer, (newLayer, oldLayer) => {
+        if (newLayer === oldLayer) return;
+
+        const el = containerEl.value;
+        if (!el) {
+            currentLayer.value = newLayer;
+            leavingLayer.value = null;
+            return;
+        }
+
+        clearCleanup();
+        const id = ++transitionId;
+
+        // 1. Capture current width
+        const fromWidth = el.getBoundingClientRect().width;
+
+        // 2. Pin width (prevents snap during class swap)
+        el.style.width = `${fromWidth}px`;
+
+        // 3. Swap: mark old as leaving, new as active
+        leavingLayer.value = oldLayer;
+        currentLayer.value = newLayer;
+
+        // 4. Measure new natural width on next tick
+        nextTick(() => {
+            if (id !== transitionId) return;
+            if (!el) return;
+
+            // Temporarily unpin to measure
+            el.style.transition = "none";
+            el.style.width = "";
+            const toWidth = el.getBoundingClientRect().width;
+
+            // Re-pin to old width
+            el.style.width = `${fromWidth}px`;
+            // Force reflow so the browser registers the old width
+            void el.offsetWidth;
+            // Restore CSS transitions
+            el.style.transition = "";
+
+            // 5. Animate to new width
+            requestAnimationFrame(() => {
+                if (id !== transitionId) return;
+                el.style.width = `${toWidth}px`;
+            });
+
+            // Safety: clear inline width after max duration in case transitionend
+            // doesn't fire (e.g. width didn't actually change)
+            cleanupTimer = setTimeout(() => {
+                if (id !== transitionId) return;
+                el.style.width = "";
+                leavingLayer.value = null;
+            }, 400);
+        });
+    });
+
+    function onTransitionEnd(e: TransitionEvent) {
+        const el = containerEl.value;
+        if (!el) return;
+        if (e.target !== el) return;
+        if (e.propertyName !== "width") return;
+
+        clearCleanup();
+        el.style.width = "";
+        leavingLayer.value = null;
+    }
+
+    function layerProps(id: string): {
+        class: string[];
+        inert: true | undefined;
+    } {
+        const isActive = currentLayer.value === id;
+        const isLeaving = leavingLayer.value === id;
+
+        const classes = ["dock-layer-item"];
+        if (isActive) classes.push("dock-layer-active");
+        if (isLeaving) classes.push("dock-layer-leaving");
+
+        return {
+            class: classes,
+            inert: isActive ? undefined : true,
+        };
+    }
+
+    onUnmounted(clearCleanup);
+
+    return { layerProps, onTransitionEnd };
+}

package/src/components/custom/dock/composables/usePopupMutex.ts

@@ -0,0 +1,83 @@
+import { ref, computed, onUnmounted } from "vue";
+import type { Ref, WritableComputedRef } from "vue";
+
+export interface UsePopupMutexOptions {
+    /** Delay when swapping between popups to prevent jarring transitions (ms, default: 180) */
+    swapDelay?: number;
+}
+
+export interface UsePopupMutexReturn<K extends string> {
+    /** Currently open popup key, or null */
+    current: Ref<K | null>;
+    /** Whether any popup is open or mid-swap */
+    isAnyOpen: Ref<boolean>;
+    /** Create a writable computed get/set for a specific popup key */
+    popupModel(key: K): WritableComputedRef<boolean>;
+}
+
+/**
+ * Mutex for dock popups / dropdowns: only one open at a time,
+ * with a brief delay when swapping to prevent jarring transitions.
+ */
+export function usePopupMutex<K extends string>(
+    options?: UsePopupMutexOptions,
+): UsePopupMutexReturn<K> {
+    const { swapDelay = 180 } = options ?? {};
+
+    const current = ref<K | null>(null) as Ref<K | null>;
+    const pending = ref<K | null>(null) as Ref<K | null>;
+    let swapTimer: ReturnType<typeof setTimeout> | null = null;
+
+    function clearSwapTimer() {
+        if (swapTimer) {
+            clearTimeout(swapTimer);
+            swapTimer = null;
+        }
+    }
+
+    function update(key: K, open: boolean) {
+        if (open) {
+            if (current.value === key) return;
+            clearSwapTimer();
+
+            // Swapping: close current, delay, then open new
+            if (current.value && current.value !== key) {
+                pending.value = key;
+                current.value = null;
+                swapTimer = setTimeout(() => {
+                    current.value = pending.value;
+                    pending.value = null;
+                    swapTimer = null;
+                }, swapDelay);
+                return;
+            }
+
+            pending.value = null;
+            current.value = key;
+            return;
+        }
+
+        // Closing
+        if (pending.value === key) {
+            pending.value = null;
+        }
+        if (current.value === key) {
+            current.value = null;
+        }
+    }
+
+    const isAnyOpen = computed(
+        () => current.value !== null || pending.value !== null,
+    );
+
+    function popupModel(key: K): WritableComputedRef<boolean> {
+        return computed({
+            get: () => current.value === key,
+            set: (open: boolean) => update(key, open),
+        });
+    }
+
+    onUnmounted(clearSwapTimer);
+
+    return { current, isAnyOpen, popupModel };
+}