@flux-ui/components 3.1.2 → 3.1.4

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;
+    }
+}

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

@@ -1134,3 +1134,54 @@
     transition: 210ms var(--swift-out);
     transition-property: background, border-color, color, opacity, scale, translate, mixin.focus-ring-transition-properties();
 }
+
+.formTagsInput {
+    composes: formInput;
+
+    display: flex;
+    height: unset;
+    min-height: 42px;
+    padding: 4px 6px;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 6px;
+    cursor: text;
+
+    &:not(.formTagsInputDisabled) {
+        @include mixin.focus-ring(-1px, true);
+    }
+}
+
+.formTagsInputEnabled {
+    composes: formTagsInput;
+}
+
+.formTagsInputDisabled {
+    composes: formTagsInput;
+
+    background: var(--gray-100);
+    cursor: not-allowed;
+}
+
+.formTagsInputField {
+    height: 30px;
+    min-width: 60px;
+    flex: 1 1 60px;
+    background: none;
+    border: 0;
+    color: inherit;
+    font: inherit;
+    outline: 0;
+
+    &::placeholder {
+        color: var(--foreground-secondary);
+    }
+
+    &:disabled {
+        cursor: not-allowed;
+    }
+}
+
+.formTagsInputPopup {
+    composes: formSelectPopup;
+}

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

@@ -0,0 +1,47 @@
+@use '~flux/components/css/mixin';
+
+.formRating {
+    display: inline-flex;
+    gap: .15em;
+    font-size: 24px;
+    line-height: 1;
+    border-radius: 4px;
+
+    @include mixin.focus-ring(4px);
+
+    &.isDisabled {
+        opacity: .6;
+    }
+}
+
+.formRatingStar {
+    position: relative;
+    display: inline-flex;
+    padding: 0;
+    border: 0;
+    background: none;
+    line-height: 0;
+    cursor: pointer;
+
+    &:disabled {
+        cursor: default;
+    }
+}
+
+.formRatingStarEmpty {
+    color: var(--gray-300);
+}
+
+.formRatingStarFull {
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    left: 0;
+    color: var(--warning-400);
+    clip-path: inset(0 calc((1 - var(--fill, 0)) * 100%) 0 0);
+    pointer-events: none;
+}
+
+.isInvalid .formRatingStarEmpty {
+    color: var(--danger-200);
+}

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

@@ -0,0 +1,45 @@
+@use '~flux/components/css/mixin';
+
+.inlineEdit {
+    display: flex;
+    gap: 6px;
+    align-items: flex-start;
+}
+
+.inlineEditField {
+    min-width: 0;
+    flex: 1 1 auto;
+}
+
+.inlineEditActions {
+    display: flex;
+    gap: 6px;
+    align-items: center;
+    flex-shrink: 0;
+}
+
+.inlineEditDisplay {
+    display: inline-flex;
+    min-height: 30px;
+    padding: 3px 6px;
+    align-items: center;
+    border-radius: 6px;
+    color: var(--foreground);
+    line-height: 21px;
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+
+    &.isInteractive {
+        cursor: text;
+
+        @include mixin.focus-ring(2px);
+
+        @include mixin.hover {
+            background: var(--surface-hover);
+        }
+    }
+
+    &.isPlaceholder {
+        color: var(--foreground-secondary);
+    }
+}