@flux-ui/internals 3.0.0-next.7 → 3.0.0-next.70

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/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, watch } from 'vue';
+import { getFocusableElements, isSSR, type TemplateRef, unrefTemplateElement, wrapFocus } from '../util';
 import useFocusTrapLock from './useFocusTrapLock';
 import useFocusTrapReturn from './useFocusTrapReturn';
 
@@ -13,7 +11,7 @@ export default function (containerRef: TemplateRef<HTMLElement>, options: UseFoc
     const {disable = ref(false), disableReturn = ref(false), attachTo = null} = options;
     const enabled = useFocusTrapLock(!disable);
 
-    useFocusTrapReturn(disableReturn);
+    useFocusTrapReturn(containerRef, disableReturn);
 
     watch(containerRef, (_, __, onCleanup) => {
         const container = unrefTemplateElement(containerRef);
@@ -63,21 +61,29 @@ 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(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();
+                } else {
+                    container.focus();
+                }
             }
         }
 

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,13 +1,14 @@
-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 } from '../util';
 
-export default function <TElement extends HTMLElement>(containerRef: TemplateRef<TElement>, {cycle = true, direction = 'bidirectional'}: UseFocusZoneOptions = {}): void {
+type EligibleElement = ComponentPublicInstance | HTMLElement;
+
+export default function <TElement extends EligibleElement>(containerRef: Ref<TElement>, {cycle = true, direction = 'bidirectional'}: UseFocusZoneOptions = {}): void {
     useMutationObserver(containerRef, () => updateFocus(findInitialIndex(), false));
 
     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'));
@@ -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,152 @@
+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;
+            }
+
+            return;
+        }
+
+        switch (evt.key) {
+            case 'ArrowUp':
+                evt.preventDefault();
+                options.onMove('up');
+                break;
+
+            case 'ArrowDown':
+                evt.preventDefault();
+                options.onMove('down');
+                break;
+
+            case 'ArrowLeft':
+                evt.preventDefault();
+                options.onMove('left');
+                break;
+
+            case 'ArrowRight':
+                evt.preventDefault();
+                options.onMove('right');
+                break;
+
+            case ' ':
+            case 'Enter': {
+                evt.preventDefault();
+                const o = origin.value;
+                origin.value = null;
+
+                if (o !== null) {
+                    options.onCommit(o);
+                }
+
+                break;
+            }
+
+            case 'Escape': {
+                evt.preventDefault();
+                const o = origin.value;
+                origin.value = null;
+
+                if (o !== null) {
+                    options.onCancel(o);
+                }
+
+                break;
+            }
+        }
+
+        // Suppress unused-warning when announce is unused inside the function.
+        void announce;
+    }
+
+    return {
+        isGrabbed,
+        handleKeyDown,
+        release
+    };
+}

package/src/composable/useRemembered.ts

@@ -1,6 +1,5 @@
 import { DateTime } from 'luxon';
-import type { Ref } from 'vue';
-import { ref, watch } from 'vue';
+import { ref, type Ref, watch } from 'vue';
 
 export default function <T>(key: string, initialValue: T): Ref<T> {
     const realKey = `flux/${key}`;

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,5 +1,4 @@
-import type { Ref } from 'vue';
-import { ref, unref } from 'vue';
+import { ref, type Ref, unref } from 'vue';
 import type { TemplateRef } from '../util';
 import useEventListener from './useEventListener';
 

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;
 

package/src/directive/heightTransition.ts

@@ -34,7 +34,7 @@ class HeightTransition {
         }
 
         getComputedStyle(this.#root);
-        requestAnimationFrame(() => requestAnimationFrame(() => this.#root.style.height = height));
+        requestAnimationFrame(() => this.#root.style.height = height);
     }
 }
 
@@ -49,7 +49,11 @@ export default {
         const heightTransition = new HeightTransition(elm);
         heightTransition.register();
         heightTransitions.set(elm, heightTransition);
+    },
+
+    getSSRProps(): Record<string, unknown> {
+        return {};
     }
-} satisfies Directive;
+} satisfies Directive as Directive;
 
 const heightTransitions: WeakMap<HTMLElement, HeightTransition> = new WeakMap();

package/src/directive/index.ts

@@ -4,4 +4,4 @@ import vHeightTransition from './heightTransition';
 export {
     vFocusTrap,
     vHeightTransition
-}
+};

package/src/util/animationFrameDebounce.ts

@@ -0,0 +1,15 @@
+import type { FluxMaybePromise } from '@flux-ui/types';
+
+export default function <T extends () => FluxMaybePromise<void>>(fn: T): T {
+    if (typeof requestAnimationFrame === 'undefined') {
+        return (() => {
+        }) as T;
+    }
+
+    let animationFrame = 0;
+
+    return (() => {
+        cancelAnimationFrame(animationFrame);
+        animationFrame = requestAnimationFrame(fn);
+    }) as T;
+}

package/src/util/flattenVNodeTree.ts

@@ -1,5 +1,4 @@
-import type { VNode } from 'vue';
-import { Fragment } from 'vue';
+import { Fragment, type VNode } from 'vue';
 
 export default function (vnodes: VNode[]): VNode[] {
     const flattened: VNode[] = [];

package/src/util/focusTrap.ts

@@ -59,4 +59,5 @@ interface FocusTrap {
 
 export type FocusTrapListener = (isEnabled: boolean, focusTraps: FocusTrap[]) => void;
 
-export default new FocusTrapLockStack();
+const _default: FocusTrapLockStack = new FocusTrapLockStack();
+export default _default;

package/src/util/index.ts

@@ -1,3 +1,4 @@
+export { default as animationFrameDebounce } from './animationFrameDebounce';
 export { default as flattenVNodeTree } from './flattenVNodeTree';
 export { default as getBidirectionalFocusElement } from './getBidirectionalFocusElement';
 export { default as getComponentName } from './getComponentName';
@@ -12,4 +13,4 @@ export { default as wrapFocus } from './wrapFocus';
 
 export { default as FOCUS_TRAP_LOCKS, type FocusTrapListener } from './focusTrap';
 
-export const isSSR = !globalThis.document;
+export const isSSR: boolean = !globalThis.document;

package/src/util/unrefTemplateElement.ts

@@ -1,5 +1,5 @@
 import { isHtmlElement } from '@basmilius/utils';
-import { ComponentPublicInstance, ShallowRef, unref } from 'vue';
+import { type ComponentPublicInstance, type ShallowRef, unref } from 'vue';
 
 export type TemplateElement<TElement extends HTMLElement> = ComponentPublicInstance<any, any, any, any, any, any, any, any, any, any, any, any, any, any, TElement> | TElement | null;
 export type TemplateRef<TElement extends HTMLElement> = Readonly<ShallowRef<TemplateElement<TElement>>>;

package/dist/composable/useCalendar.d.ts

@@ -1,20 +0,0 @@
-import type { DateTime } from "luxon";
-import { type Ref } from "vue";
-export default function(initialDate: DateTime, options?: UseCalendarOptions): UseCalendarReturn;
-type UseCalendarOptions = {
-	readonly monthLength?: "short" | "long"
-	readonly weekDayLength?: "short" | "long"
-};
-type UseCalendarReturn = {
-	readonly isTransitioningToPast: Ref<boolean>
-	readonly viewDate: Ref<DateTime>
-	readonly viewDateNext: Ref<DateTime>
-	readonly viewDatePrevious: Ref<DateTime>
-	readonly viewMonth: Ref<string>
-	readonly viewYear: Ref<string>
-	readonly dates: Ref<DateTime[]>
-	readonly days: Ref<string[]>
-	setViewDate(date: DateTime): void
-	nextMonth(): void
-	previousMonth(): void
-};

package/dist/composable/useCalendarMonthSwitcher.d.ts

@@ -1,10 +0,0 @@
-import type { DateTime } from "luxon";
-import type { Ref } from "vue";
-export default function(currentDate: Ref<DateTime>, displayLength: "short" | "long"): UseCalendarMonthSwitcherReturn;
-type MonthEntry = {
-	readonly date: DateTime
-	readonly label: string
-};
-type UseCalendarMonthSwitcherReturn = {
-	readonly months: Ref<MonthEntry[]>
-};

package/dist/composable/useCalendarYearSwitcher.d.ts

@@ -1,8 +0,0 @@
-import type { DateTime } from "luxon";
-import type { Ref } from "vue";
-export default function(currentDate: Ref<DateTime>, limit?: number): UseCalendarYearSwitcherReturn;
-type UseCalendarYearSwitcherReturn = {
-	readonly years: Ref<number[]>
-	next(): void
-	previous(): void
-};

package/dist/composable/useClickOutside.d.ts

@@ -1,4 +0,0 @@
-import type { Ref } from "vue";
-import type { TemplateRef } from "../util";
-type Handler = ((evt: PointerEvent) => void) | ((evt: PointerEvent) => Promise<void>);
-export default function<TElement extends HTMLElement>(elementRefs: TemplateRef<TElement> | TemplateRef<TElement>[], enabled: boolean | Ref<boolean>, onOutsideClick: Handler): void;