@flux-ui/internals 3.0.0-next.9 → 3.1.0

package/src/composable/useCalendarTimeGrid.ts

@@ -0,0 +1,103 @@
+import type { DateTime } from 'luxon';
+import { computed, type ComputedRef, type MaybeRefOrGetter, ref, type Ref, toValue, unref, watch } from 'vue';
+
+export type UseCalendarTimeGridDayCount = 1 | 2 | 7;
+
+export type UseCalendarTimeGridReturn = {
+    readonly isTransitioningToPast: Ref<boolean>;
+    readonly viewDate: Ref<DateTime>;
+    readonly viewDates: ComputedRef<DateTime[]>;
+    readonly rangeLabel: ComputedRef<string>;
+
+    setViewDate(date: DateTime): void;
+    next(): void;
+    previous(): void;
+};
+
+function getAnchor(date: DateTime, dayCount: UseCalendarTimeGridDayCount): DateTime {
+    return dayCount === 7 ? date.startOf('week') : date.startOf('day');
+}
+
+function stepDuration(dayCount: UseCalendarTimeGridDayCount): { day?: number; week?: number } {
+    if (dayCount === 7) {
+        return {week: 1};
+    }
+
+    if (dayCount === 2) {
+        return {day: 2};
+    }
+
+    return {day: 1};
+}
+
+export default function (
+    initialDate: DateTime,
+    dayCount: MaybeRefOrGetter<UseCalendarTimeGridDayCount>
+): UseCalendarTimeGridReturn {
+    const isTransitioningToPast = ref(false);
+    const viewDate = ref<DateTime>(getAnchor(initialDate, toValue(dayCount)));
+
+    // Re-anchor on dayCount change (e.g. switching from week to two-days view).
+    watch(() => toValue(dayCount), (count) => {
+        viewDate.value = getAnchor(unref(viewDate), count);
+    });
+
+    const viewDates = computed<DateTime[]>(() => {
+        const anchor = unref(viewDate);
+        const count = toValue(dayCount);
+        const out: DateTime[] = [];
+
+        for (let i = 0; i < count; ++i) {
+            out.push(anchor.plus({day: i}));
+        }
+
+        return out;
+    });
+
+    const rangeLabel = computed<string>(() => {
+        const dates = unref(viewDates);
+        const first = dates[0];
+        const last = dates[dates.length - 1];
+        const count = toValue(dayCount);
+
+        if (count === 1) {
+            return first.toLocaleString({weekday: 'long', day: 'numeric', month: 'long', year: 'numeric'});
+        }
+
+        const sameMonth = first.month === last.month;
+        const sameYear = first.year === last.year;
+
+        const firstFmt = first.toLocaleString(
+            sameMonth && sameYear
+                ? {weekday: 'short', day: 'numeric'}
+                : {weekday: 'short', day: 'numeric', month: 'short'}
+        );
+        const lastFmt = last.toLocaleString({weekday: 'short', day: 'numeric', month: 'short', year: sameYear ? undefined : 'numeric'});
+
+        return `${firstFmt} – ${lastFmt}`;
+    });
+
+    function setViewDate(date: DateTime): void {
+        const anchor = getAnchor(date, toValue(dayCount));
+        isTransitioningToPast.value = unref(viewDate) > anchor;
+        viewDate.value = anchor;
+    }
+
+    function next(): void {
+        setViewDate(unref(viewDate).plus(stepDuration(toValue(dayCount))));
+    }
+
+    function previous(): void {
+        setViewDate(unref(viewDate).minus(stepDuration(toValue(dayCount))));
+    }
+
+    return {
+        isTransitioningToPast,
+        viewDate,
+        viewDates,
+        rangeLabel,
+        setViewDate,
+        next,
+        previous
+    };
+}

package/src/composable/useCalendarYearSwitcher.ts

@@ -1,6 +1,5 @@
 import type { DateTime } from 'luxon';
-import type { Ref } from 'vue';
-import { computed, ref, unref, watch } from 'vue';
+import { computed, ref, type Ref, unref, watch } from 'vue';
 
 export default function (currentDate: Ref<DateTime>, limit: number = 10): UseCalendarYearSwitcherReturn {
     const index = ref(0);

package/src/composable/useEventListener.ts

@@ -1,14 +1,16 @@
 import { watch } from 'vue';
-import type { TemplateRef } from '../util';
+import { type TemplateRef, unrefTemplateElement } from '../util';
 
 export default function <K extends keyof HTMLElementEventMap>(elementRef: TemplateRef<HTMLElement>, eventName: K, listener: (evt: HTMLElementEventMap[K]) => any, options: AddEventListenerOptions = {passive: true}): void {
-    watch(elementRef, (element: HTMLElement, _, onCleanup) => {
+    watch(elementRef, (value, _, onCleanup) => {
+        const element: EventTarget | null = unrefTemplateElement(elementRef) ?? (value instanceof EventTarget ? value : null);
+
         if (!element) {
             return;
         }
 
-        element.addEventListener(eventName, listener, options);
+        element.addEventListener(eventName, listener as EventListener, options);
 
-        onCleanup(() => element.removeEventListener(eventName, listener));
+        onCleanup(() => element.removeEventListener(eventName, listener as EventListener, options));
     }, {immediate: true});
 }

package/src/composable/useFocusTrap.ts

@@ -1,7 +1,5 @@
-import type { Ref } from 'vue';
-import { ref, watch } from 'vue';
-import type { TemplateRef } from '../util';
-import { getFocusableElements, isSSR, unrefTemplateElement, wrapFocus } from '../util';
+import { ref, type Ref, unref, watch } from 'vue';
+import { getFocusableElements, isActiveElement, isSSR, type TemplateRef, unrefTemplateElement, wrapFocus } from '../util';
 import useFocusTrapLock from './useFocusTrapLock';
 import useFocusTrapReturn from './useFocusTrapReturn';
 
@@ -11,9 +9,9 @@ export default function (containerRef: TemplateRef<HTMLElement>, options: UseFoc
     }
 
     const {disable = ref(false), disableReturn = ref(false), attachTo = null} = options;
-    const enabled = useFocusTrapLock(!disable);
+    const enabled = useFocusTrapLock(!unref(disable));
 
-    useFocusTrapReturn(disableReturn);
+    useFocusTrapReturn(containerRef, disableReturn);
 
     watch(containerRef, (_, __, onCleanup) => {
         const container = unrefTemplateElement(containerRef);
@@ -63,21 +61,27 @@ export default function (containerRef: TemplateRef<HTMLElement>, options: UseFoc
         attach.addEventListener('focusout', onFocusOut as EventListener, {capture: true});
 
         if (container) {
-            const elements = getFocusableElements(container);
-            const isActiveIndex = elements.findIndex(e => e.classList.contains('is-active'));
-            const notDisabledIndex = elements.findIndex(e => !e.hasAttribute('aria-disabled'));
-            let element = elements[0];
-
-            if (isActiveIndex > -1) {
-                element = elements[isActiveIndex];
-            }
-
-            if (notDisabledIndex > -1) {
-                element = elements[notDisabledIndex];
-            }
-
-            if (element) {
-                element.focus();
+            const autofocusElement = container.querySelector<HTMLElement>('[autofocus]');
+
+            if (autofocusElement) {
+                autofocusElement.focus();
+            } else {
+                const elements = getFocusableElements(container);
+                const isActiveIndex = elements.findIndex(elm => isActiveElement(elm) && !elm.hasAttribute('aria-disabled'));
+                const notDisabledIndex = elements.findIndex(elm => !elm.hasAttribute('aria-disabled'));
+                let element = elements[0];
+
+                if (isActiveIndex > -1) {
+                    element = elements[isActiveIndex];
+                } else if (notDisabledIndex > -1) {
+                    element = elements[notDisabledIndex];
+                }
+
+                if (element) {
+                    element.focus();
+                } else {
+                    container.focus();
+                }
             }
         }
 
@@ -87,11 +91,11 @@ export default function (containerRef: TemplateRef<HTMLElement>, options: UseFoc
         });
     }, {immediate: true});
 
-    watch(() => disable, () => {
+    watch(disable, disabled => {
         const container = unrefTemplateElement(containerRef);
-        enabled.value = !disable;
+        enabled.value = !disabled;
 
-        if (disable || !container) {
+        if (disabled || !container) {
             return;
         }
 

package/src/composable/useFocusTrapLock.ts

@@ -1,5 +1,4 @@
-import type { Ref } from 'vue';
-import { onMounted, onUnmounted, ref, unref } from 'vue';
+import { onMounted, onUnmounted, ref, type Ref, unref } from 'vue';
 import { FOCUS_TRAP_LOCKS } from '../util';
 
 let lockId = 0;

package/src/composable/useFocusTrapReturn.ts

@@ -1,14 +1,18 @@
-import type { Ref } from 'vue';
-import { onUnmounted, ref, unref } from 'vue';
+import { type Ref, unref, watch } from 'vue';
+import { type TemplateRef, unrefTemplateElement } from '../util';
 
-export default function (disabled: Ref<boolean>): void {
-    const target = ref<HTMLElement | null>(document.activeElement as HTMLElement | null);
+export default function (containerRef: TemplateRef<HTMLElement>, disabled: Ref<boolean>): void {
+    watch(containerRef, (_, __, onCleanup) => {
+        const container = unrefTemplateElement(containerRef);
 
-    onUnmounted(() => {
-        if (unref(disabled)) {
+        if (!container || unref(disabled)) {
             return;
         }
 
-        requestAnimationFrame(() => unref(target)?.focus());
+        const previousTarget = document.activeElement as HTMLElement | null;
+
+        onCleanup(() => {
+            requestAnimationFrame(() => previousTarget?.focus());
+        });
     });
 }

package/src/composable/useFocusTrapSubscription.ts

@@ -1,6 +1,5 @@
 import { onMounted, onUnmounted, ref } from 'vue';
-import type { FocusTrapListener } from '../util';
-import { FOCUS_TRAP_LOCKS } from '../util';
+import { FOCUS_TRAP_LOCKS, type FocusTrapListener } from '../util';
 
 export default function (listener: FocusTrapListener): void {
     const unsubscribe = ref<Function | null>(null);

package/src/composable/useFocusZone.ts

@@ -1,16 +1,17 @@
-import { watch } from 'vue';
-import type { TemplateRef } from '../util';
-import { getBidirectionalFocusElement, getFocusableElement, getFocusableElements, unrefTemplateElement } from '../util';
-import useMutationObserver from './useMutationObserver';
+import { unwrapElement, useMutationObserver } from '@basmilius/common';
+import { type ComponentPublicInstance, type Ref, watch } from 'vue';
+import { getBidirectionalFocusElement, getFocusableElement, getFocusableElements, isActiveElement } from '../util';
 
-export default function <TElement extends HTMLElement>(containerRef: TemplateRef<TElement>, {cycle = true, direction = 'bidirectional'}: UseFocusZoneOptions = {}): void {
-    useMutationObserver(containerRef, () => updateFocus(findInitialIndex(), false));
+type EligibleElement = ComponentPublicInstance | HTMLElement;
+
+export default function <TElement extends EligibleElement>(containerRef: Ref<TElement>, {cycle = true, direction = 'bidirectional'}: UseFocusZoneOptions = {}): void {
+    useMutationObserver(containerRef, () => updateFocus(findInitialIndex(), false), {childList: true, subtree: true});
 
     function findInitialIndex(): number {
-        const container = unrefTemplateElement(containerRef)!;
+        const container = unwrapElement(containerRef);
         const elements = getFocusableElements(container);
-        const isActiveIndex = elements.findIndex(e => e.classList.contains('is-active'));
-        const notDisabledIndex = elements.findIndex(e => !e.hasAttribute('aria-disabled'));
+        const isActiveIndex = elements.findIndex(elm => isActiveElement(elm) && !elm.hasAttribute('aria-disabled'));
+        const notDisabledIndex = elements.findIndex(elm => !elm.hasAttribute('aria-disabled'));
 
         if (isActiveIndex > -1) {
             return isActiveIndex;
@@ -24,7 +25,7 @@ export default function <TElement extends HTMLElement>(containerRef: TemplateRef
     }
 
     function updateFocus(elementIndex: number, doFocus: boolean = true): void {
-        const container = unrefTemplateElement(containerRef)!;
+        const container = unwrapElement(containerRef)!;
         const elements = getFocusableElements(container);
         elements.forEach((elm, index) => elm.tabIndex = index === elementIndex ? 0 : -1);
 
@@ -32,7 +33,7 @@ export default function <TElement extends HTMLElement>(containerRef: TemplateRef
     }
 
     function onKeyDown(evt: KeyboardEvent): void {
-        const container = unrefTemplateElement(containerRef)!;
+        const container = unwrapElement(containerRef)!;
         const elements = getFocusableElements(container);
 
         if (['Enter', ' '].includes(evt.key)) {
@@ -52,7 +53,7 @@ export default function <TElement extends HTMLElement>(containerRef: TemplateRef
     }
 
     watch(containerRef, (_, __, onCleanup) => {
-        const container = unrefTemplateElement(containerRef);
+        const container = unwrapElement(containerRef);
 
         if (!container) {
             return;

package/src/composable/useInView.ts

@@ -1,7 +1,5 @@
-import type { Ref } from 'vue';
-import { ref, watch } from 'vue';
-import type { TemplateRef } from '../util';
-import { unrefTemplateElement } from '../util';
+import { ref, type Ref, watch } from 'vue';
+import { type TemplateRef, unrefTemplateElement } from '../util';
 
 export default function <TElement extends HTMLElement>(containerRef: TemplateRef<TElement>, options: UseInViewOptions = {}): Ref<boolean> {
     const inView = ref(options.initial ?? false);

package/src/composable/useKeyboardGrab.ts

@@ -0,0 +1,156 @@
+import { computed, type ComputedRef, ref, type Ref, unref } from 'vue';
+
+export type KeyboardGrabDirection = 'up' | 'down' | 'left' | 'right';
+
+export type UseKeyboardGrabOptions<TPos> = {
+    readonly isDraggable: Ref<boolean>;
+    readonly itemId: Ref<string | number | null | undefined>;
+    readonly grabbedId: Ref<string | number | null>;
+    onGrab(): TPos;
+    onMove(direction: KeyboardGrabDirection): void;
+    onCommit(origin: TPos): void;
+    onCancel(origin: TPos): void;
+    announce?(message: string): void;
+};
+
+export type UseKeyboardGrabReturn = {
+    readonly isGrabbed: ComputedRef<boolean>;
+    handleKeyDown(evt: KeyboardEvent): void;
+    release(): void;
+};
+
+let liveRegion: HTMLElement | null = null;
+
+function ensureLiveRegion(): HTMLElement {
+    if (liveRegion) {
+        return liveRegion;
+    }
+
+    if (typeof document === 'undefined') {
+        return null as unknown as HTMLElement;
+    }
+
+    const region = document.createElement('div');
+    region.setAttribute('role', 'status');
+    region.setAttribute('aria-live', 'polite');
+    region.setAttribute('aria-atomic', 'true');
+    region.style.cssText = 'position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0';
+    document.body.appendChild(region);
+    liveRegion = region;
+    return region;
+}
+
+export function defaultAnnounce(message: string): void {
+    const region = ensureLiveRegion();
+
+    if (!region) {
+        return;
+    }
+
+    region.textContent = '';
+    requestAnimationFrame(() => {
+        region.textContent = message;
+    });
+}
+
+/**
+ * Generic keyboard-grab state machine. Maps Space/Enter/Escape/Arrow keys
+ * onto grab/commit/cancel/move callbacks. The actual movement logic is
+ * delegated to `onMove` since it depends on the host component's topology.
+ */
+export default function useKeyboardGrab<TPos>(options: UseKeyboardGrabOptions<TPos>): UseKeyboardGrabReturn {
+    const origin = ref<TPos | null>(null);
+    const announce = options.announce ?? defaultAnnounce;
+
+    const isGrabbed = computed<boolean>(() => {
+        const id = unref(options.itemId);
+        const grabbed = unref(options.grabbedId);
+
+        return id != null && grabbed === id;
+    });
+
+    function release(): void {
+        origin.value = null;
+    }
+
+    function handleKeyDown(evt: KeyboardEvent): void {
+        if (!unref(options.isDraggable)) {
+            return;
+        }
+
+        const id = unref(options.itemId);
+
+        if (id == null) {
+            return;
+        }
+
+        if (!isGrabbed.value) {
+            if (evt.key === ' ' || evt.key === 'Enter') {
+                evt.preventDefault();
+                origin.value = options.onGrab() as TPos;
+                announce('Grabbed, use arrow keys to move');
+            }
+
+            return;
+        }
+
+        switch (evt.key) {
+            case 'ArrowUp':
+                evt.preventDefault();
+                options.onMove('up');
+                announce('Moved up');
+                break;
+
+            case 'ArrowDown':
+                evt.preventDefault();
+                options.onMove('down');
+                announce('Moved down');
+                break;
+
+            case 'ArrowLeft':
+                evt.preventDefault();
+                options.onMove('left');
+                announce('Moved left');
+                break;
+
+            case 'ArrowRight':
+                evt.preventDefault();
+                options.onMove('right');
+                announce('Moved right');
+                break;
+
+            case ' ':
+            case 'Enter': {
+                evt.preventDefault();
+                const originValue = origin.value;
+                origin.value = null;
+
+                if (originValue !== null) {
+                    options.onCommit(originValue);
+                    announce('Dropped');
+                }
+
+                break;
+            }
+
+            case 'Escape': {
+                evt.preventDefault();
+                const originValue = origin.value;
+                origin.value = null;
+
+                if (originValue !== null) {
+                    options.onCancel(originValue);
+                    announce('Cancelled');
+                }
+
+                break;
+            }
+        }
+    }
+
+    return {
+        isGrabbed,
+        handleKeyDown,
+        release
+    };
+}

package/src/composable/useRemembered.ts

@@ -1,23 +1,33 @@
 import { DateTime } from 'luxon';
-import type { Ref } from 'vue';
-import { ref, watch } from 'vue';
+import { ref, type Ref, watch } from 'vue';
+import { isSSR } from '../util';
 
 export default function <T>(key: string, initialValue: T): Ref<T> {
+    if (isSSR) {
+        return ref(initialValue) as Ref<T>;
+    }
+
     const realKey = `flux/${key}`;
     const value = ref<T>(get() ?? initialValue);
 
     function get(): T | null {
-        if (realKey in localStorage) {
-            let storageValue = JSON.parse(localStorage.getItem(realKey)!);
+        const storedValue = localStorage.getItem(realKey);
+
+        if (storedValue === null) {
+            return null;
+        }
+
+        try {
+            let storageValue = JSON.parse(storedValue);
 
             if (Array.isArray(storageValue) && storageValue[0] === 'DateTime') {
                 storageValue = DateTime.fromISO(storageValue[1]);
             }
 
             return storageValue;
+        } catch {
+            return null;
         }
-
-        return null;
     }
 
     watch(value, value => {
@@ -30,7 +40,11 @@ export default function <T>(key: string, initialValue: T): Ref<T> {
             })] as unknown as T;
         }
 
-        localStorage.setItem(realKey, JSON.stringify(_value));
+        try {
+            localStorage.setItem(realKey, JSON.stringify(_value));
+        } catch {
+            // Storage can be unavailable or full (e.g. private browsing); remembering is best-effort.
+        }
     });
 
     return value as Ref<T>;

package/src/composable/useScrollEdges.ts

@@ -0,0 +1,76 @@
+import { ref, type Ref, watch } from 'vue';
+import { type TemplateRef, unrefTemplateElement } from '../util';
+
+export default function <TElement extends HTMLElement>(elementRef: TemplateRef<TElement>): UseScrollEdgesReturn {
+    const isAtStart = ref(true);
+    const isAtEnd = ref(true);
+    const isAtLeft = ref(true);
+    const isAtRight = ref(true);
+
+    watch(elementRef, (_, __, onCleanup) => {
+        const element = unrefTemplateElement(elementRef);
+
+        if (!element) {
+            return;
+        }
+
+        const update = (): void => {
+            const {scrollTop, scrollHeight, clientHeight, scrollLeft, scrollWidth, clientWidth} = element;
+
+            isAtStart.value = scrollTop <= 0;
+            isAtEnd.value = Math.ceil(scrollTop + clientHeight) >= scrollHeight;
+            isAtLeft.value = scrollLeft <= 0;
+            isAtRight.value = Math.ceil(scrollLeft + clientWidth) >= scrollWidth;
+        };
+
+        const resizeObserver = new ResizeObserver(update);
+        resizeObserver.observe(element);
+
+        for (const child of Array.from(element.children)) {
+            resizeObserver.observe(child);
+        }
+
+        const mutationObserver = new MutationObserver(mutations => {
+            for (const mutation of mutations) {
+                for (const node of Array.from(mutation.addedNodes)) {
+                    if (node instanceof Element) {
+                        resizeObserver.observe(node);
+                    }
+                }
+
+                for (const node of Array.from(mutation.removedNodes)) {
+                    if (node instanceof Element) {
+                        resizeObserver.unobserve(node);
+                    }
+                }
+            }
+
+            update();
+        });
+
+        mutationObserver.observe(element, {childList: true});
+        element.addEventListener('scroll', update, {passive: true});
+
+        update();
+
+        onCleanup(() => {
+            element.removeEventListener('scroll', update);
+            resizeObserver.disconnect();
+            mutationObserver.disconnect();
+        });
+    }, {immediate: true});
+
+    return {
+        isAtStart,
+        isAtEnd,
+        isAtLeft,
+        isAtRight
+    };
+}
+
+export type UseScrollEdgesReturn = {
+    readonly isAtStart: Ref<boolean>;
+    readonly isAtEnd: Ref<boolean>;
+    readonly isAtLeft: Ref<boolean>;
+    readonly isAtRight: Ref<boolean>;
+};

package/src/composable/useScrollPosition.ts

@@ -1,18 +1,22 @@
-import type { Ref } from 'vue';
-import { ref, unref } from 'vue';
-import type { TemplateRef } from '../util';
+import { ref, type Ref, unref, watch } from 'vue';
+import { isSSR, type TemplateRef } from '../util';
 import useEventListener from './useEventListener';
 
 export default function <TElement extends HTMLElement>(elementRef?: TemplateRef<TElement>): UseScrollPositionReturn {
     const x = ref(0);
     const y = ref(0);
 
-    if (!elementRef) {
-        elementRef = ref(document);
+    if (isSSR) {
+        return {
+            x,
+            y
+        };
     }
 
-    useEventListener(elementRef, 'scroll', () => {
-        let element = unref(elementRef);
+    const targetRef = elementRef ?? ref(document);
+
+    const update = (): void => {
+        let element = unref(targetRef);
 
         if (element instanceof Document) {
             element = element.scrollingElement;
@@ -20,7 +24,11 @@ export default function <TElement extends HTMLElement>(elementRef?: TemplateRef<
 
         x.value = element?.scrollLeft ?? 0;
         y.value = element?.scrollTop ?? 0;
-    });
+    };
+
+    useEventListener(targetRef, 'scroll', update);
+
+    watch(targetRef, () => update(), {immediate: true});
 
     return {
         x,

package/src/directive/focusTrap.ts

@@ -71,6 +71,10 @@ export default {
         const focusTrap = new FocusTrap(elm);
         focusTrap.register();
         focusTraps.set(elm, focusTrap);
+    },
+
+    getSSRProps(): Record<string, unknown> {
+        return {};
     }
 } satisfies Directive;