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

package/src/composable/private/index.ts

@@ -1,3 +1,10 @@
+export { default as useAsyncFilterOptions } from './useAsyncFilterOptions';
+export { default as useDateFlyout } from './useDateFlyout';
+export { default as useDropdownPopup, type UseDropdownPopupOptions, type UseDropdownPopupReturn } from './useDropdownPopup';
 export { default as useFormSelect } from './useFormSelect';
-export { default as useLoaded } from './useLoaded';
+export { useKanban } from './useKanban';
+export { useSplitView, type SplitViewPane, type UseSplitViewOptions, type UseSplitViewReturn } from './useSplitView';
 export { default as useTranslate } from './useTranslate';
+export { useCommandPalette, type CommandPaletteGroup, type CommandPaletteResultItem } from './useCommandPalette';
+export { useFilterOptionMulti, useFilterOptionSingle, type FilterOptionMulti, type FilterOptionSingle } from './useFilterOption';
+export { flattenAll, flattenVisible, getLevelColor, INITIAL_HIGHLIGHTED_INDEX, useTreeView, type TreeBaseOption, type TreeFlatNode } from './useTreeView';

package/src/composable/private/useAsyncFilterOptions.ts

@@ -0,0 +1,64 @@
+import { useDebouncedRef, useLoaded } from '@basmilius/common';
+import type { FluxFilterOptionRow, FluxFilterValue } from '@flux-ui/types';
+import { computed, ref, unref, watch, type ComputedRef, type ModelRef, type Ref } from 'vue';
+import { isFluxFilterOptionItem } from '~flux/components/util';
+
+type UseAsyncFilterOptionsParams = {
+    readonly currentValueIds: ComputedRef<FluxFilterValue[]>;
+    readonly modelSearch: ModelRef<string, string, string, string>;
+    fetchOptions(ids: FluxFilterValue[]): Promise<FluxFilterOptionRow[]>;
+    fetchRelevant(): Promise<FluxFilterOptionRow[]>;
+    fetchSearch(searchQuery: string): Promise<FluxFilterOptionRow[]>;
+};
+
+export default function (params: UseAsyncFilterOptionsParams) {
+    const {isLoading, loaded} = useLoaded();
+    const debouncedModelSearch = useDebouncedRef(params.modelSearch, 150) as unknown as Ref<string>;
+    const fetchOptions = computed(() => loaded(params.fetchOptions));
+    const fetchRelevant = computed(() => loaded(params.fetchRelevant));
+    const fetchSearch = computed(() => loaded(params.fetchSearch));
+
+    const selectedOptions = ref<FluxFilterOptionRow[]>([]);
+    const visibleOptions = ref<FluxFilterOptionRow[]>([]);
+
+    const options = computed(() => {
+        const options: FluxFilterOptionRow[] = [];
+        const search = unref(params.modelSearch);
+        const selected = unref(selectedOptions);
+        const visible = unref(visibleOptions);
+
+        visible.forEach(vo => options.push(vo));
+
+        selected.forEach(so => {
+            if (isFluxFilterOptionItem(so) && visible.find(vo => isFluxFilterOptionItem(vo) && vo.value === so.value)) {
+                return;
+            }
+
+            if (isFluxFilterOptionItem(so) && !so.label.toLowerCase().includes(search.toLowerCase())) {
+                return;
+            }
+
+            options.push(so);
+        });
+
+        return options;
+    });
+
+    watch(params.currentValueIds, async ids => {
+        if (ids.length === 0) {
+            return;
+        }
+
+        selectedOptions.value = await unref(fetchOptions)(ids);
+    }, {immediate: true});
+
+    watch(debouncedModelSearch, async searchQuery => {
+        if (searchQuery.length > 0) {
+            visibleOptions.value = await unref(fetchSearch)(searchQuery);
+        } else {
+            visibleOptions.value = await unref(fetchRelevant)();
+        }
+    }, {immediate: true});
+
+    return {isLoading, options};
+}

package/src/composable/private/useCommandPalette.ts

@@ -0,0 +1,405 @@
+import { useDebouncedRef } from '@basmilius/common';
+import type { FluxCommandSource, FluxCommandSourceItem, FluxCommandSubAction } from '@flux-ui/types';
+import { computed, nextTick, ref, unref, watch, type Ref } from 'vue';
+
+export type CommandPaletteResultItem = {
+    readonly globalIndex: number;
+    readonly sourceKey: string;
+    readonly sourceLabel: string;
+    readonly item: FluxCommandSourceItem;
+};
+
+export type CommandPaletteGroup = {
+    readonly sourceKey: string;
+    readonly sourceLabel: string;
+    readonly startIndex: number;
+    readonly items: CommandPaletteResultItem[];
+};
+
+export function useCommandPalette(params: {
+    readonly sources: Ref<FluxCommandSource[]>;
+    readonly itemRefs: Readonly<Ref<Array<{ readonly $el: HTMLElement; }> | null | undefined>>;
+}): {
+    readonly search: Ref<string>;
+    readonly activeTab: Ref<string | null>;
+    readonly highlightedIndex: Ref<number>;
+    readonly isLoading: Ref<boolean>;
+    readonly isTransitioningBack: Ref<boolean>;
+    readonly subActionTarget: Ref<FluxCommandSourceItem | null>;
+    readonly filteredItems: Ref<CommandPaletteResultItem[]>;
+    readonly groupedItems: Ref<CommandPaletteGroup[]>;
+    readonly subActions: Ref<FluxCommandSubAction[]>;
+    readonly activeTabSource: Ref<FluxCommandSource | null>;
+    readonly tabs: Ref<FluxCommandSource[]>;
+    readonly totalItems: Ref<number>;
+    setSearch: (value: string) => void;
+    setActiveTab: (key: string | null) => void;
+    enterSubActions: (item: FluxCommandSourceItem) => void;
+    onKeyNavigate: (evt: KeyboardEvent, onClose: () => void, onActivate: (item: FluxCommandSourceItem) => void) => void;
+    reset: () => void;
+} {
+    const search = ref('');
+    const activeTab = ref<string | null>(null);
+    const highlightedIndex = ref(-1);
+    const subActionTarget = ref<FluxCommandSourceItem | null>(null);
+    const isKeyboardNav = ref(false);
+    const isLoading = ref(false);
+    const isTransitioningBack = ref(false);
+    const savedState = ref<{ readonly search: string; readonly highlightedIndex: number; } | null>(null);
+    const asyncResults = ref<Map<string, FluxCommandSourceItem[]>>(new Map());
+    const debouncedSearch = useDebouncedRef(search, 300) as unknown as Ref<string>;
+    let fetchGeneration = 0;
+
+    const filteredItems = computed<CommandPaletteResultItem[]>(() => {
+        const query = unref(search).toLowerCase().trim();
+        const tab = unref(activeTab);
+        const sources = unref(params.sources);
+        const asyncMap = unref(asyncResults);
+        const results: CommandPaletteResultItem[] = [];
+
+        for (const source of sources) {
+            if (tab && source.key !== tab) {
+                continue;
+            }
+
+            if (source.fetchSearch) {
+                const items = query ? asyncMap.get(source.key) : source.items;
+
+                if (items) {
+                    for (const item of items) {
+                        results.push({
+                            globalIndex: results.length,
+                            sourceKey: source.key,
+                            sourceLabel: source.label,
+                            item
+                        });
+                    }
+                }
+
+                continue;
+            }
+
+            for (const item of source.items) {
+                if (query && !item.label.toLowerCase().includes(query) && !(item.subLabel?.toLowerCase().includes(query) ?? false)) {
+                    continue;
+                }
+
+                results.push({
+                    globalIndex: results.length,
+                    sourceKey: source.key,
+                    sourceLabel: source.label,
+                    item
+                });
+            }
+        }
+
+        return results;
+    });
+
+    const groupedItems = computed<CommandPaletteGroup[]>(() => {
+        const items = unref(filteredItems);
+        const groups = new Map<string, CommandPaletteGroup>();
+
+        for (const result of items) {
+            if (!groups.has(result.sourceKey)) {
+                groups.set(result.sourceKey, {
+                    sourceKey: result.sourceKey,
+                    sourceLabel: result.sourceLabel,
+                    startIndex: result.globalIndex,
+                    items: []
+                });
+            }
+
+            (groups.get(result.sourceKey)!.items as CommandPaletteResultItem[]).push(result);
+        }
+
+        return Array.from(groups.values());
+    });
+
+    const tabs = computed(() => unref(params.sources).filter(source => source.tab));
+
+    const activeTabSource = computed<FluxCommandSource | null>(() => {
+        const tab = unref(activeTab);
+
+        if (!tab) {
+            return null;
+        }
+
+        return unref(tabs).find(source => source.key === tab) ?? null;
+    });
+
+    const subActions = computed(() => {
+        const actions = unref(subActionTarget)?.subActions ?? [];
+        const query = unref(search).toLowerCase().trim();
+
+        if (!query) {
+            return actions;
+        }
+
+        return actions.filter(action => action.label.toLowerCase().includes(query));
+    });
+
+    const totalItems = computed(() => {
+        if (unref(subActionTarget)) {
+            return unref(subActions).length;
+        }
+
+        return unref(filteredItems).length;
+    });
+
+    function setSearch(value: string): void {
+        search.value = value;
+        highlightedIndex.value = value.trim() ? 0 : -1;
+
+        if (value.trim() && !unref(subActionTarget) && unref(params.sources).some(s => s.fetchSearch)) {
+            isLoading.value = true;
+        } else {
+            isLoading.value = false;
+        }
+    }
+
+    function setActiveTab(key: string | null): void {
+        const allTabs = unref(tabs);
+        const tabKeys: (string | null)[] = [null, ...allTabs.map(t => t.key)];
+
+        isTransitioningBack.value = tabKeys.indexOf(key) < tabKeys.indexOf(unref(activeTab));
+        activeTab.value = key;
+        search.value = '';
+        highlightedIndex.value = -1;
+        subActionTarget.value = null;
+    }
+
+    function selectHighlighted(onClose: () => void, onActivate: (item: FluxCommandSourceItem) => void): void {
+        const index = unref(highlightedIndex);
+        const target = unref(subActionTarget);
+
+        if (target) {
+            const action = unref(subActions)[index];
+
+            if (action) {
+                action.onActivate();
+                onClose();
+            }
+
+            return;
+        }
+
+        const result = unref(filteredItems)[index];
+
+        if (!result) {
+            return;
+        }
+
+        if (result.item.subActions?.length) {
+            enterSubActions(result.item);
+        } else {
+            result.item.onActivate();
+            onActivate(result.item);
+        }
+    }
+
+    function enterSubActions(item: FluxCommandSourceItem): void {
+        savedState.value = {search: unref(search), highlightedIndex: unref(highlightedIndex)};
+        subActionTarget.value = item;
+        search.value = '';
+        highlightedIndex.value = 0;
+    }
+
+    function navigateTab(direction: number): void {
+        const allTabs = unref(tabs);
+
+        if (allTabs.length === 0) {
+            return;
+        }
+
+        const tabKeys: (string | null)[] = [null, ...allTabs.map(tab => tab.key)];
+        const currentIndex = tabKeys.indexOf(unref(activeTab));
+        const nextIndex = (currentIndex + direction + tabKeys.length) % tabKeys.length;
+
+        setActiveTab(tabKeys[nextIndex]);
+    }
+
+    function restoreState(): void {
+        subActionTarget.value = null;
+        const state = unref(savedState);
+
+        if (state) {
+            search.value = state.search;
+            isKeyboardNav.value = true;
+            highlightedIndex.value = state.highlightedIndex;
+            savedState.value = null;
+        } else {
+            highlightedIndex.value = -1;
+        }
+    }
+
+    function onKeyNavigate(evt: KeyboardEvent, onClose: () => void, onActivate: (item: FluxCommandSourceItem) => void): void {
+        const total = unref(totalItems);
+        const current = unref(highlightedIndex);
+
+        switch (evt.key) {
+            case 'ArrowDown':
+                evt.preventDefault();
+                isKeyboardNav.value = true;
+                highlightedIndex.value = Math.min(total - 1, current + 1);
+                break;
+
+            case 'ArrowUp':
+                evt.preventDefault();
+                isKeyboardNav.value = true;
+                highlightedIndex.value = total === 0 ? -1 : Math.max(0, current - 1);
+                break;
+
+            case 'ArrowLeft':
+                if (!unref(search) && !unref(subActionTarget)) {
+                    evt.preventDefault();
+                    navigateTab(-1);
+                }
+
+                break;
+
+            case 'ArrowRight':
+                if (!unref(search) && !unref(subActionTarget)) {
+                    evt.preventDefault();
+                    navigateTab(1);
+                }
+
+                break;
+
+            case 'Enter':
+                evt.preventDefault();
+                selectHighlighted(onClose, onActivate);
+                break;
+
+            case 'Escape':
+                evt.preventDefault();
+
+                if (unref(subActionTarget)) {
+                    restoreState();
+                } else {
+                    onClose();
+                }
+
+                break;
+
+            case 'Backspace':
+                if (!unref(search)) {
+                    if (unref(subActionTarget)) {
+                        evt.preventDefault();
+                        restoreState();
+                    } else if (unref(activeTab)) {
+                        evt.preventDefault();
+                        activeTab.value = null;
+                        highlightedIndex.value = -1;
+                    }
+                }
+
+                break;
+        }
+    }
+
+    function reset(): void {
+        search.value = '';
+        activeTab.value = null;
+        highlightedIndex.value = -1;
+        subActionTarget.value = null;
+        asyncResults.value = new Map();
+        isLoading.value = false;
+        fetchGeneration++;
+    }
+
+    watch(debouncedSearch, async (query) => {
+        if (unref(subActionTarget)) {
+            return;
+        }
+
+        const trimmed = query.trim();
+
+        if (!trimmed) {
+            asyncResults.value = new Map();
+            isLoading.value = false;
+            return;
+        }
+
+        const tab = unref(activeTab);
+        const sources = unref(params.sources);
+        const asyncSources = sources.filter(s => {
+            if (!s.fetchSearch) {
+                return false;
+            }
+
+            return !tab || s.key === tab;
+        });
+
+        if (asyncSources.length === 0) {
+            isLoading.value = false;
+            return;
+        }
+
+        const generation = ++fetchGeneration;
+        isLoading.value = true;
+
+        try {
+            const fetched = await Promise.all(
+                asyncSources.map(async (source) => ({
+                    key: source.key,
+                    items: await source.fetchSearch!(trimmed)
+                }))
+            );
+
+            if (generation !== fetchGeneration) {
+                return;
+            }
+
+            const map = new Map<string, FluxCommandSourceItem[]>();
+
+            for (const {key, items} of fetched) {
+                map.set(key, items);
+            }
+
+            asyncResults.value = map;
+        } finally {
+            if (generation === fetchGeneration) {
+                isLoading.value = false;
+            }
+        }
+    });
+
+    watch(highlightedIndex, (index) => {
+        if (index < 0 || !unref(isKeyboardNav)) {
+            return;
+        }
+
+        isKeyboardNav.value = false;
+
+        nextTick(() => unref(params.itemRefs)?.[index]?.$el?.scrollIntoView({block: 'nearest'}));
+    });
+
+    watch(totalItems, (total) => {
+        const current = unref(highlightedIndex);
+
+        if (current >= total) {
+            highlightedIndex.value = Math.max(-1, total - 1);
+        }
+    });
+
+    return {
+        search,
+        activeTab,
+        activeTabSource,
+        highlightedIndex,
+        isLoading,
+        isTransitioningBack,
+        subActionTarget,
+        filteredItems,
+        groupedItems,
+        subActions,
+        tabs,
+        totalItems,
+        setSearch,
+        setActiveTab,
+        enterSubActions,
+        onKeyNavigate,
+        reset
+    };
+}

package/src/composable/private/useDateFlyout.ts

@@ -0,0 +1,34 @@
+import { ref, unref, watch, type ModelRef, type Ref } from 'vue';
+
+type FlyoutLike = {
+    close(): void;
+};
+
+type UseDateFlyoutOptions<T> = {
+    compareKey?(value: T | null): string | number | null | undefined;
+    transformIn?(value: T | null): T | null;
+};
+
+export default function <T>(
+    modelValue: ModelRef<T | null>,
+    flyoutRef: Readonly<Ref<FlyoutLike | null>>,
+    options: UseDateFlyoutOptions<T> = {}
+): Ref<T | null> {
+    const localValue = ref<T | null>(null) as Ref<T | null>;
+
+    watch(modelValue, value => {
+        localValue.value = options.transformIn ? options.transformIn(value) : value;
+    }, {immediate: true});
+
+    watch(localValue, value => {
+        unref(flyoutRef)?.close();
+
+        if (options.compareKey && options.compareKey(modelValue.value) === options.compareKey(value)) {
+            return;
+        }
+
+        modelValue.value = value;
+    });
+
+    return localValue;
+}

package/src/composable/private/useDropdownPopup.ts

@@ -0,0 +1,99 @@
+import { useClickOutside } from '@basmilius/common';
+import { unrefTemplateElement } from '@flux-ui/internals';
+import { nextTick, ref, unref, watch, type ComponentPublicInstance, type Ref } from 'vue';
+
+export type UseDropdownPopupOptions = {
+    readonly anchorRef: Readonly<Ref<ComponentPublicInstance | null | undefined>>;
+    readonly popupRef: Readonly<Ref<ComponentPublicInstance | null | undefined>>;
+    readonly focusElement: Readonly<Ref<HTMLElement | null | undefined>>;
+    readonly disabled?: Readonly<Ref<boolean>>;
+    readonly readonly?: Readonly<Ref<boolean>>;
+    readonly onOpen?: () => void;
+    readonly onClose?: () => void;
+};
+
+export type UseDropdownPopupReturn = {
+    readonly isOpen: Ref<boolean>;
+    readonly open: () => void;
+    readonly close: () => void;
+    readonly toggle: () => void;
+    readonly focusAnchor: () => void;
+    readonly onKeyDownBase: (evt: KeyboardEvent) => boolean;
+};
+
+/**
+ * Shared dropdown-popup infrastructure for select-like components. Manages:
+ * - open/close state
+ * - click-outside (close when clicking outside popup + anchor)
+ * - focus-back-to-anchor on close
+ * - focus-the-inner-focus-element on open
+ * - Escape/Tab keyboard handling
+ */
+export default function useDropdownPopup(options: UseDropdownPopupOptions): UseDropdownPopupReturn {
+    const isOpen = ref(false);
+
+    function open(): void {
+        if (unref(options.disabled) || unref(options.readonly)) {
+            return;
+        }
+
+        isOpen.value = true;
+    }
+
+    function close(): void {
+        isOpen.value = false;
+    }
+
+    function toggle(): void {
+        if (unref(options.disabled) || unref(options.readonly)) {
+            return;
+        }
+
+        isOpen.value = !unref(isOpen);
+    }
+
+    function focusAnchor(): void {
+        nextTick(() => unrefTemplateElement(options.anchorRef)?.focus());
+    }
+
+    function onKeyDownBase(evt: KeyboardEvent): boolean {
+        if (evt.key === 'Escape' && unref(isOpen)) {
+            evt.preventDefault();
+            isOpen.value = false;
+            focusAnchor();
+            return true;
+        }
+
+        if (evt.key === 'Tab' && unref(isOpen)) {
+            isOpen.value = false;
+            return true;
+        }
+
+        return false;
+    }
+
+    if (typeof window !== 'undefined') {
+        useClickOutside([options.anchorRef, options.popupRef], isOpen, () => isOpen.value = false);
+        useClickOutside(options.anchorRef, isOpen, () => unref(options.focusElement)?.focus());
+    }
+
+    watch(isOpen, opened => {
+        if (!opened) {
+            options.onClose?.();
+            return;
+        }
+
+        nextTick(() => unref(options.focusElement)?.focus());
+
+        options.onOpen?.();
+    });
+
+    return {
+        isOpen,
+        open,
+        close,
+        toggle,
+        focusAnchor,
+        onKeyDownBase
+    };
+}

package/src/composable/private/useFilterOption.ts

@@ -0,0 +1,59 @@
+import type { FluxFilterValue, FluxFilterValueSingle } from '@flux-ui/types';
+import { computed, unref, type ComputedRef } from 'vue';
+import { useFilterInjection } from '~flux/components/composable';
+
+export type FilterOptionSingle = {
+    readonly currentValue: ComputedRef<FluxFilterValueSingle>;
+    onSelect(value: FluxFilterValue): void;
+};
+
+export type FilterOptionMulti = {
+    readonly currentValue: ComputedRef<FluxFilterValueSingle[]>;
+    onSelect(value: FluxFilterValueSingle): void;
+};
+
+export function useFilterOptionSingle(name: string): FilterOptionSingle {
+    const {back, state, setValue} = useFilterInjection();
+
+    const currentValue = computed(() => unref(state)[name] as FluxFilterValueSingle);
+
+    function onSelect(value: FluxFilterValue): void {
+        if (unref(currentValue) === value) {
+            setValue(name, null);
+        } else {
+            setValue(name, value);
+        }
+
+        back();
+    }
+
+    return {currentValue, onSelect};
+}
+
+export function useFilterOptionMulti(name: string): FilterOptionMulti {
+    const {state, setValue} = useFilterInjection();
+
+    const currentValue = computed<FluxFilterValueSingle[]>(() => {
+        const value = unref(state)[name];
+
+        if (Array.isArray(value)) {
+            return value;
+        }
+
+        return [];
+    });
+
+    function onSelect(value: FluxFilterValueSingle): void {
+        let values = Array.from(unref(currentValue));
+
+        if (values.includes(value)) {
+            values = values.filter(v => v !== value);
+        } else {
+            values.push(value);
+        }
+
+        setValue(name, values.length > 0 ? values : null);
+    }
+
+    return {currentValue, onSelect};
+}

package/src/composable/private/useFormSelect.ts

@@ -1,9 +1,8 @@
 import type { FluxFormSelectEntry, FluxFormSelectOption, FluxFormSelectOptions, FluxFormSelectValue } from '@flux-ui/types';
-import type { MaybeRef, Ref } from 'vue';
-import { computed, unref } from 'vue';
-import { isFluxFormSelectGroup, isFluxFormSelectOption } from '$flux/data';
+import { computed, unref, type Ref } from 'vue';
+import { isFluxFormSelectGroup, isFluxFormSelectOption } from '~flux/components/data';
 
-export default function (modelValue: Ref<FluxFormSelectValue>, isMultiple: boolean, options: MaybeRef<FluxFormSelectEntry[]>, searchQuery?: Ref<string>) {
+export default function (modelValue: Ref<FluxFormSelectValue>, isMultiple: boolean, options: Ref<FluxFormSelectEntry[]>, searchQuery?: Ref<string>) {
     const values = computed(() => {
         const model = unref(modelValue);
         return Array.isArray(model) ? model : [model];
@@ -14,8 +13,8 @@ export default function (modelValue: Ref<FluxFormSelectValue>, isMultiple: boole
         const search = unref(searchQuery)?.trim().toLowerCase();
 
         const available = unref(options)
-            .filter(o => !('value' in o) || (!search || o.label.toLowerCase().includes(search)))
-            .filter(o => !('value' in o) || !isMultiple || !unref(selected).find(s => s.value === o.value));
+            .filter(o => isFluxFormSelectGroup(o) || (!search || o.label.toLowerCase().includes(search)))
+            .filter(o => isFluxFormSelectGroup(o) || !isMultiple || !unref(selected).find(s => s.value === o.value));
 
         if (available.length === 0) {
             return [];