@flux-ui/internals 3.0.0-next.6 → 3.0.0-next.60

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,68 @@
+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);
+
+    watch(elementRef, (_, __, onCleanup) => {
+        const element = unrefTemplateElement(elementRef);
+
+        if (!element) {
+            return;
+        }
+
+        const update = (): void => {
+            const {scrollTop, scrollHeight, clientHeight} = element;
+
+            isAtStart.value = scrollTop <= 0;
+            isAtEnd.value = Math.ceil(scrollTop + clientHeight) >= scrollHeight;
+        };
+
+        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
+    };
+}
+
+export type UseScrollEdgesReturn = {
+    readonly isAtStart: Ref<boolean>;
+    readonly isAtEnd: 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;

package/dist/composable/useComponentId.d.ts

@@ -1,2 +0,0 @@
-import type { ComputedRef } from "vue";
-export default function(): ComputedRef<number>;

package/dist/composable/useDebouncedRef.d.ts

@@ -1,2 +0,0 @@
-import type { Ref } from "vue";
-export default function<T>(initialValue: Ref<T> | T, delay: number, immediate?: boolean): Ref<T>;

package/dist/composable/useEventListener.d.ts

@@ -1,2 +0,0 @@
-import type { TemplateRef } from "../util";
-export default function<K extends keyof HTMLElementEventMap>(elementRef: TemplateRef<HTMLElement>, eventName: K, listener: (evt: HTMLElementEventMap[K]) => any, options?: AddEventListenerOptions): void;

package/dist/composable/useFocusTrap.d.ts

@@ -1,8 +0,0 @@
-import type { Ref } from "vue";
-import type { TemplateRef } from "../util";
-export default function(containerRef: TemplateRef<HTMLElement>, options?: UseFocusTrapOptions): void;
-type UseFocusTrapOptions = {
-	attachTo?: HTMLElement | Document
-	disable?: Ref<boolean>
-	disableReturn?: Ref<boolean>
-};

package/dist/composable/useFocusTrapLock.d.ts

@@ -1,2 +0,0 @@
-import type { Ref } from "vue";
-export default function(autoFocus?: boolean): Ref<boolean>;

package/dist/composable/useFocusTrapReturn.d.ts

@@ -1,2 +0,0 @@
-import type { Ref } from "vue";
-export default function(disabled: Ref<boolean>): void;

package/dist/composable/useFocusTrapSubscription.d.ts

@@ -1,2 +0,0 @@
-import type { FocusTrapListener } from "../util";
-export default function(listener: FocusTrapListener): void;

package/dist/composable/useFocusZone.d.ts

@@ -1,6 +0,0 @@
-import type { TemplateRef } from "../util";
-export default function<TElement extends HTMLElement>(containerRef: TemplateRef<TElement>, { cycle, direction }?: UseFocusZoneOptions): void;
-type UseFocusZoneOptions = {
-	readonly cycle?: boolean
-	readonly direction?: "bidirectional" | "horizontal" | "vertical"
-};

package/dist/composable/useInView.d.ts

@@ -1,6 +0,0 @@
-import type { Ref } from "vue";
-import type { TemplateRef } from "../util";
-export default function<TElement extends HTMLElement>(containerRef: TemplateRef<TElement>, options?: UseInViewOptions): Ref<boolean>;
-type UseInViewOptions = IntersectionObserverInit & {
-	readonly initial?: boolean
-};

package/dist/composable/useInterval.d.ts

@@ -1,2 +0,0 @@
-import type { Ref } from "vue";
-export default function(interval: Ref<number> | number, fn: Function): void;

package/dist/composable/useMutationObserver.d.ts

@@ -1,2 +0,0 @@
-import type { TemplateRef } from "../util";
-export default function<TElement extends HTMLElement>(elementRef: TemplateRef<TElement>, callback: MutationCallback, options?: MutationObserverInit): void;

package/dist/composable/useRemembered.d.ts

@@ -1,2 +0,0 @@
-import type { Ref } from "vue";
-export default function<T>(key: string, initialValue: T): Ref<T>;

package/dist/composable/useScrollPosition.d.ts

@@ -1,7 +0,0 @@
-import type { Ref } from "vue";
-import type { TemplateRef } from "../util";
-export default function<TElement extends HTMLElement>(elementRef?: TemplateRef<TElement>): UseScrollPositionReturn;
-export type UseScrollPositionReturn = {
-	readonly x: Ref<number>
-	readonly y: Ref<number>
-};