@flux-ui/components 3.1.0 → 3.1.3

package/src/component/primitive/AnchorPopup.vue

@@ -20,12 +20,14 @@
 
     const {
         anchor,
+        clampToViewport,
         direction = 'vertical',
         margin = 12,
         position,
         useAnchorWidth
     } = defineProps<{
         readonly anchor?: ComponentPublicInstance | HTMLElement | null;
+        readonly clampToViewport?: boolean;
         readonly direction?: FluxDirection;
         readonly margin?: number;
         readonly position?:
@@ -52,6 +54,9 @@
     onMounted(() => {
         window.addEventListener('resize', onResize, {passive: true});
         window.addEventListener('scroll', onScroll, {capture: true, passive: true});
+
+        resize();
+        reposition();
     });
 
     onUnmounted(() => {
@@ -161,6 +166,23 @@
                 break;
         }
 
+        if (clampToViewport) {
+            if (position?.startsWith('right') && px + popupWidth > innerWidth - margin) {
+                px = x - popupWidth - margin;
+            } else if (position?.startsWith('left') && px < margin) {
+                px = x + width + margin;
+            }
+
+            if (position?.startsWith('bottom') && py + popupHeight > innerHeight - margin) {
+                py = y - popupHeight - margin;
+            } else if (position?.startsWith('top') && py < margin) {
+                py = y + height + margin;
+            }
+
+            px = Math.min(Math.max(px, margin), Math.max(margin, innerWidth - popupWidth - margin));
+            py = Math.min(Math.max(py, margin), Math.max(margin, innerHeight - popupHeight - margin));
+        }
+
         state.x = px;
         state.y = py;
     }
@@ -185,6 +207,11 @@
         reposition();
     }
 
+    defineExpose({
+        reposition,
+        resize
+    });
+
     watchEffect(() => {
         if (!anchor || (!isHtmlElement(anchor) && !anchor.$el)) {
             return;

package/src/component/primitive/SelectBase.vue

@@ -80,11 +80,19 @@
                     :placeholder="translate('flux.search')"
                     @keydown="onKeyDown"/>
 
-                <FluxMenu v-if="!isLoading && options.length === 0">
+                <FluxMenu v-if="canCreate">
+                    <FluxMenuItem
+                        icon-leading="plus"
+                        :label="translate('flux.createOption', {value: trimmedSearch})"
+                        type="button"
+                        @click="create()"/>
+                </FluxMenu>
+
+                <FluxMenu v-if="!isLoading && options.length === 0 && !canCreate">
                     <FluxMenuSubHeader :label="translate('flux.noItems')"/>
                 </FluxMenu>
 
-                <FluxMenu v-else>
+                <FluxMenu v-else-if="options.length > 0">
                     <template
                         v-for="([item, subItems], index) of options"
                         :key="`group-${index}`">
@@ -162,6 +170,7 @@
         keyDown: [KeyboardEvent];
         deselect: [string | number | null];
         select: [string | number | null];
+        create: [string];
         search: [string];
         close: [];
         open: [];
@@ -177,11 +186,13 @@
 
     const {
         disabled: componentDisabled,
+        isCreatable,
         isMultiple,
         options,
         selected
     } = defineProps<{
         readonly disabled?: boolean;
+        readonly isCreatable?: boolean;
         readonly isLoading?: boolean;
         readonly isMultiple?: boolean;
         readonly isSearchable?: boolean;
@@ -205,6 +216,15 @@
     const focusElement = computed(() => unrefTemplateElement(searchInputElementRef) ?? unrefTemplateElement(anchorRef));
     const highlightedId = computed(() => unref(rawOptions)[unref(highlightedIndex)]?.value);
     const rawOptions = computed(() => options.map(group => group[1]).flat());
+    const trimmedSearch = computed(() => unref(modelSearch).trim());
+    const canCreate = computed(() => {
+        if (!isCreatable || trimmedSearch.value === '') {
+            return false;
+        }
+
+        const query = trimmedSearch.value.toLowerCase();
+        return !unref(rawOptions).some(o => o.label.toLowerCase() === query);
+    });
 
     const {
         isOpen: isPopupOpen,
@@ -236,6 +256,19 @@
         nextTick(() => unref(focusElement)?.focus());
     }
 
+    function create(): void {
+        emit('create', trimmedSearch.value);
+
+        if (!isMultiple) {
+            isPopupOpen.value = false;
+        }
+
+        highlightedIndex.value = INITIAL_HIGHLIGHTED_INDEX;
+        modelSearch.value = '';
+
+        nextTick(() => unref(focusElement)?.focus());
+    }
+
     function onKeyDown(evt: KeyboardEvent): void {
         emit('keyDown', evt);
 
@@ -284,6 +317,8 @@
 
                 if (id !== undefined) {
                     select(id);
+                } else if (unref(canCreate)) {
+                    create();
                 }
                 break;
 

package/src/composable/private/index.ts

@@ -4,6 +4,7 @@ export { default as useDateFlyout } from './useDateFlyout';
 export { default as useDropdownPopup, type UseDropdownPopupOptions, type UseDropdownPopupReturn } from './useDropdownPopup';
 export { default as useFormSelect } from './useFormSelect';
 export { useKanban } from './useKanban';
+export { default as useMenuFlyout, useMenuFlyoutContext, useMenuFlyoutProvider, type UseMenuFlyoutOptions, type UseMenuFlyoutProviderOptions, type UseMenuFlyoutReturn } from './useMenuFlyout';
 export { useSplitView, type SplitViewPane, type UseSplitViewOptions, type UseSplitViewReturn } from './useSplitView';
 export { default as useTranslate } from './useTranslate';
 export { useCommandPalette, type CommandPaletteGroup, type CommandPaletteResultItem } from './useCommandPalette';

package/src/composable/private/useMenuFlyout.ts

@@ -0,0 +1,417 @@
+import { animationFrameDebounce, isSSR } from '@flux-ui/internals';
+import { inject, nextTick, onMounted, onUnmounted, provide, ref, type ComponentPublicInstance, type Ref, watch } from 'vue';
+import { FluxMenuFlyoutInjectionKey, type FluxMenuFlyoutCone, type FluxMenuFlyoutEntry, type FluxMenuFlyoutInjection, type FluxMenuFlyoutPointer } from '~flux/components/data';
+
+let flyoutId = 0;
+
+export type UseMenuFlyoutProviderOptions = {
+    readonly debugCone: Ref<boolean>;
+    readonly onCloseAll?: () => void;
+};
+
+export type UseMenuFlyoutOptions = {
+    readonly triggerRef: Ref<ComponentPublicInstance | HTMLElement | null>;
+    readonly popupRef: Ref<ComponentPublicInstance | HTMLElement | null>;
+    readonly disabled?: Ref<boolean>;
+};
+
+export type UseMenuFlyoutReturn = {
+    readonly context: FluxMenuFlyoutInjection | null;
+    readonly cone: Ref<FluxMenuFlyoutCone | null>;
+    readonly isOpen: Ref<boolean>;
+    closeAll(): void;
+    focusTrigger(): void;
+    onPopupKeydown(evt: KeyboardEvent): void;
+    onTriggerClick(evt: MouseEvent): void;
+    onTriggerKeydown(evt: KeyboardEvent): void;
+};
+
+/**
+ * Creates and provides the shared menu-flyout context for an entire open menu tree. Used by the
+ * outermost menu surface (FluxContextMenu, or a standalone root FluxMenu). Tracks the pointer, the
+ * active prediction cone, the keyboard-trap stack and the set of teleported flyout popups so that
+ * click-outside and close-all can reason about the whole tree.
+ */
+export function useMenuFlyoutProvider(options: UseMenuFlyoutProviderOptions): FluxMenuFlyoutInjection {
+    const {debugCone, onCloseAll} = options;
+    const entries = new Set<FluxMenuFlyoutEntry>();
+
+    const pointer = ref<FluxMenuFlyoutPointer>({x: 0, y: 0, px: 0, py: 0});
+    const activeCone = ref<FluxMenuFlyoutCone | null>(null);
+    const keyboardStack = ref<number[]>([]);
+
+    let pointerX = 0;
+    let pointerY = 0;
+
+    // pointermove can fire several times per frame (high-poll-rate mice), and every flyout entry
+    // reacts to the pointer ref with synchronous getBoundingClientRect reads. Coalesce updates to
+    // one per animation frame so those layout reads happen at most once per frame instead of per event.
+    const flushPointer = animationFrameDebounce(() => {
+        const previous = pointer.value;
+        pointer.value = {x: pointerX, y: pointerY, px: previous.x, py: previous.y};
+    });
+
+    function onPointerMove(evt: PointerEvent): void {
+        pointerX = evt.clientX;
+        pointerY = evt.clientY;
+        flushPointer();
+    }
+
+    function startTracking(): void {
+        if (isSSR) {
+            return;
+        }
+
+        window.addEventListener('pointermove', onPointerMove, {capture: true, passive: true});
+    }
+
+    function stopTracking(): void {
+        if (isSSR) {
+            return;
+        }
+
+        window.removeEventListener('pointermove', onPointerMove, {capture: true});
+    }
+
+    const context: FluxMenuFlyoutInjection = {
+        debugCone,
+        pointer,
+        activeCone,
+        keyboardStack,
+
+        register(entry: FluxMenuFlyoutEntry): void {
+            if (entries.size === 0) {
+                startTracking();
+            }
+
+            entries.add(entry);
+        },
+
+        unregister(entry: FluxMenuFlyoutEntry): void {
+            entries.delete(entry);
+
+            if (entries.size === 0) {
+                stopTracking();
+                activeCone.value = null;
+            }
+        },
+
+        closeOthers(self: FluxMenuFlyoutEntry): void {
+            const trigger = self.getTrigger();
+
+            for (const entry of entries) {
+                if (entry === self || !entry.isOpen.value) {
+                    continue;
+                }
+
+                const popup = entry.getPopup();
+
+                if (popup && trigger && popup.contains(trigger)) {
+                    continue;
+                }
+
+                entry.close();
+            }
+        },
+
+        hasOpenDescendant(self: FluxMenuFlyoutEntry): boolean {
+            const popup = self.getPopup();
+
+            if (!popup) {
+                return false;
+            }
+
+            for (const entry of entries) {
+                if (entry === self || !entry.isOpen.value) {
+                    continue;
+                }
+
+                const trigger = entry.getTrigger();
+
+                if (trigger && popup.contains(trigger)) {
+                    return true;
+                }
+            }
+
+            return false;
+        },
+
+        isAimingAtOpenSubmenu(): boolean {
+            const {x, y, px, py} = pointer.value;
+
+            for (const entry of entries) {
+                if (!entry.isOpen.value) {
+                    continue;
+                }
+
+                const trigger = entry.getTrigger();
+                const popup = entry.getPopup();
+
+                if (!trigger || !popup) {
+                    continue;
+                }
+
+                const t = trigger.getBoundingClientRect();
+                const r = popup.getBoundingClientRect();
+                const edgeX = r.left >= t.right ? r.left : (r.right <= t.left ? r.right : r.left);
+
+                if (pointInTriangle(x, y, px, py, edgeX, r.top, edgeX, r.bottom)) {
+                    return true;
+                }
+            }
+
+            return false;
+        },
+
+        isInsidePopups(target: Node | null): boolean {
+            if (!target) {
+                return false;
+            }
+
+            for (const entry of entries) {
+                const popup = entry.getPopup();
+
+                if (popup && popup.contains(target)) {
+                    return true;
+                }
+            }
+
+            return false;
+        },
+
+        closeAll(): void {
+            if (onCloseAll) {
+                onCloseAll();
+                return;
+            }
+
+            for (const entry of entries) {
+                entry.close();
+            }
+        }
+    };
+
+    onUnmounted(stopTracking);
+
+    provide(FluxMenuFlyoutInjectionKey, context);
+
+    return context;
+}
+
+/**
+ * Returns the shared menu-flyout context, creating (and providing) a new root context when none
+ * exists higher up the tree. Used by FluxMenu so that a standalone menu becomes the root while a
+ * menu nested inside a FluxContextMenu or another flyout inherits the existing context.
+ */
+export function useMenuFlyoutContext(options: UseMenuFlyoutProviderOptions): FluxMenuFlyoutInjection {
+    const parent = inject(FluxMenuFlyoutInjectionKey, null);
+
+    if (parent) {
+        return parent;
+    }
+
+    return useMenuFlyoutProvider(options);
+}
+
+/**
+ * Per-flyout open/close and prediction-cone behaviour for FluxMenuFlyout. Submenus open instantly
+ * on hover and close instantly once the pointer is neither over the trigger/popup (or an open
+ * descendant) nor aiming at the submenu through the prediction cone (the safe triangle). There are
+ * no open/close delays — the cone is the only thing that keeps a submenu open during a diagonal
+ * move, which is also why the debug cone only shows while it actually applies.
+ */
+export default function useMenuFlyout(options: UseMenuFlyoutOptions): UseMenuFlyoutReturn {
+    const {triggerRef, popupRef, disabled} = options;
+    const context = inject(FluxMenuFlyoutInjectionKey, null);
+
+    const id = ++flyoutId;
+    const isOpen = ref(false);
+    const openSource = ref<'pointer' | 'keyboard'>('pointer');
+    const cone = ref<FluxMenuFlyoutCone | null>(null);
+
+    const entry: FluxMenuFlyoutEntry = {
+        getTrigger: () => elementOf(triggerRef.value),
+        getPopup: () => elementOf(popupRef.value),
+        isOpen,
+        close: () => doClose()
+    };
+
+    function open(source: 'pointer' | 'keyboard'): void {
+        if (disabled?.value) {
+            return;
+        }
+
+        openSource.value = source;
+
+        if (context && source === 'keyboard' && !context.keyboardStack.value.includes(id)) {
+            context.keyboardStack.value = [...context.keyboardStack.value, id];
+        }
+
+        if (!isOpen.value) {
+            isOpen.value = true;
+            context?.closeOthers(entry);
+        }
+
+        if (source === 'keyboard') {
+            nextTick(focusFirstItem);
+        }
+    }
+
+    function doClose(): void {
+        if (!isOpen.value) {
+            return;
+        }
+
+        isOpen.value = false;
+        cone.value = null;
+
+        if (context) {
+            if (context.activeCone.value?.id === id) {
+                context.activeCone.value = null;
+            }
+
+            context.keyboardStack.value = context.keyboardStack.value.filter(value => value !== id);
+        }
+    }
+
+    function focusTrigger(): void {
+        elementOf(triggerRef.value)?.focus();
+    }
+
+    function focusFirstItem(): void {
+        const popup = elementOf(popupRef.value);
+
+        if (!popup) {
+            return;
+        }
+
+        const focusable = popup.querySelector<HTMLElement>('[tabindex="0"]') ?? popup.querySelector<HTMLElement>('a[href], button:not([disabled])');
+        focusable?.focus();
+    }
+
+    function onTriggerClick(evt: MouseEvent): void {
+        evt.stopPropagation();
+
+        // evt.detail === 0 means the click came from the keyboard (Enter/Space), in which case we
+        // move focus into the submenu. A real pointer click keeps focus where it is.
+        open(evt.detail === 0 ? 'keyboard' : 'pointer');
+    }
+
+    function onTriggerKeydown(evt: KeyboardEvent): void {
+        if (evt.key === 'ArrowRight') {
+            evt.preventDefault();
+            evt.stopPropagation();
+            open('keyboard');
+        }
+    }
+
+    function onPopupKeydown(evt: KeyboardEvent): void {
+        if (evt.key === 'ArrowLeft' || evt.key === 'Escape') {
+            evt.preventDefault();
+            evt.stopPropagation();
+            doClose();
+            focusTrigger();
+        }
+    }
+
+    if (context && !isSSR) {
+        watch(context.pointer, () => {
+            const trigger = elementOf(triggerRef.value);
+
+            if (!trigger) {
+                return;
+            }
+
+            const {x, y, px, py} = context.pointer.value;
+            const t = trigger.getBoundingClientRect();
+            const overTrigger = x >= t.left && x <= t.right && y >= t.top && y <= t.bottom;
+
+            if (!isOpen.value) {
+                if (overTrigger && !context.isAimingAtOpenSubmenu()) {
+                    open('pointer');
+                }
+
+                return;
+            }
+
+            const popup = elementOf(popupRef.value);
+
+            if (!popup) {
+                return;
+            }
+
+            const r = popup.getBoundingClientRect();
+            const overPopup = x >= r.left && x <= r.right && y >= r.top && y <= r.bottom;
+
+            if (overTrigger || overPopup || context.hasOpenDescendant(entry)) {
+                cone.value = null;
+
+                if (context.activeCone.value?.id === id) {
+                    context.activeCone.value = null;
+                }
+
+                return;
+            }
+
+            const edgeX = r.left >= t.right ? r.left : (r.right <= t.left ? r.right : r.left);
+            const candidate: FluxMenuFlyoutCone = {id, ax: x, ay: y, bx: edgeX, by: r.top, cx: edgeX, cy: r.bottom};
+
+            if (pointInTriangle(x, y, px, py, edgeX, r.top, edgeX, r.bottom)) {
+                cone.value = candidate;
+                context.activeCone.value = candidate;
+            } else {
+                cone.value = null;
+
+                if (context.activeCone.value?.id === id) {
+                    context.activeCone.value = null;
+                }
+
+                doClose();
+            }
+        });
+    }
+
+    onMounted(() => context?.register(entry));
+
+    onUnmounted(() => {
+        doClose();
+        context?.unregister(entry);
+    });
+
+    return {
+        context,
+        cone,
+        isOpen,
+        closeAll: () => context?.closeAll(),
+        focusTrigger,
+        onPopupKeydown,
+        onTriggerClick,
+        onTriggerKeydown
+    };
+}
+
+function elementOf(value: ComponentPublicInstance | HTMLElement | null | undefined): HTMLElement | null {
+    if (!value) {
+        return null;
+    }
+
+    if (value instanceof HTMLElement) {
+        return value;
+    }
+
+    return (value.$el as HTMLElement | null) ?? null;
+}
+
+function pointInTriangle(px: number, py: number, ax: number, ay: number, bx: number, by: number, cx: number, cy: number): boolean {
+    const d1 = sign(px, py, ax, ay, bx, by);
+    const d2 = sign(px, py, bx, by, cx, cy);
+    const d3 = sign(px, py, cx, cy, ax, ay);
+    const hasNegative = d1 < 0 || d2 < 0 || d3 < 0;
+    const hasPositive = d1 > 0 || d2 > 0 || d3 > 0;
+
+    return !(hasNegative && hasPositive);
+}
+
+function sign(px: number, py: number, ax: number, ay: number, bx: number, by: number): number {
+    return (px - bx) * (ay - by) - (ax - bx) * (py - by);
+}

package/src/css/component/AvatarGroup.module.scss

@@ -0,0 +1,22 @@
+.avatarGroup {
+    display: inline-flex;
+    align-items: center;
+    flex-flow: row nowrap;
+}
+
+.avatarGroupItem {
+    position: relative;
+    display: inline-flex;
+    margin-left: calc(var(--overlap, .3) * -1em);
+    border-radius: .3em;
+    box-shadow: 0 0 0 .125em var(--gray-25);
+    transition: translate .2s var(--swift-out);
+
+    &:first-child {
+        margin-left: 0;
+    }
+
+    &:hover {
+        z-index: 1;
+    }
+}

package/src/css/component/ContextMenu.module.scss

@@ -0,0 +1,17 @@
+.contextMenu {
+    display: contents;
+}
+
+.contextMenuPopup {
+    composes: basePane from './base/Pane.module.scss';
+
+    position: fixed;
+    top: 0;
+    left: 0;
+    min-width: 270px;
+    max-height: max(330px, 50dvh);
+    overflow: auto;
+    box-shadow: var(--shadow-md);
+    translate: var(--x) var(--y);
+    z-index: 10000;
+}

package/src/css/component/DescriptionList.module.scss

@@ -0,0 +1,98 @@
+.descriptionList {
+    display: flex;
+    flex-flow: column;
+    gap: 12px;
+}
+
+.descriptionListHeader {
+    color: var(--foreground-secondary);
+    font-size: 14px;
+    font-weight: 500;
+}
+
+.descriptionListItems {
+    display: flex;
+    margin: 0;
+    flex-flow: column;
+    gap: 12px;
+}
+
+.descriptionItem {
+    display: flex;
+    gap: 12px;
+    align-items: center;
+}
+
+.descriptionItem.isStacked {
+    gap: 2px;
+    align-items: stretch;
+    flex-flow: column;
+}
+
+.descriptionItem.isStacked .descriptionItemValue {
+    margin-left: 0;
+    justify-content: flex-start;
+    text-align: left;
+}
+
+.descriptionItemTerm {
+    display: flex;
+    gap: 9px;
+    align-items: center;
+    color: var(--foreground);
+    font-size: 15px;
+}
+
+.descriptionItemIcon {
+    flex-shrink: 0;
+    color: var(--foreground);
+    font-size: 16px;
+}
+
+.descriptionItemLabel {
+    overflow-wrap: anywhere;
+}
+
+.descriptionItemValue {
+    display: flex;
+    margin: 0;
+    margin-left: auto;
+    gap: 6px;
+    align-items: center;
+    color: var(--foreground-prominent);
+    font-size: 15px;
+    font-weight: 600;
+    text-align: right;
+    overflow-wrap: anywhere;
+}
+
+.descriptionListItems.isHorizontal {
+    gap: 0;
+    flex-flow: row;
+
+    .descriptionItem {
+        gap: 6px;
+        align-items: stretch;
+        flex: 1 1 0;
+        flex-flow: column;
+        padding-right: 24px;
+        padding-left: 24px;
+        border-left: 1px solid var(--gray-100);
+    }
+
+    .descriptionItem:first-child {
+        padding-left: 0;
+        border-left: 0;
+    }
+
+    .descriptionItemTerm {
+        font-size: 14px;
+    }
+
+    .descriptionItemValue {
+        margin-left: 0;
+        justify-content: flex-start;
+        font-weight: 500;
+        text-align: left;
+    }
+}