@pine-ds/core 4.3.0 → 4.4.0

package/dist/collection/components/pds-combobox/grouped-options-panel.js

@@ -0,0 +1,262 @@
+import { autoUpdate, computePosition, flip, hide, offset, shift, size } from "@floating-ui/dom";
+/** The optgroup an option sits in, or null for an ungrouped option. */
+export function parentOptgroupOf(option) {
+    const parent = option === null || option === void 0 ? void 0 : option.parentElement;
+    return parent !== null && parent !== undefined && parent.tagName === 'OPTGROUP' ? parent : null;
+}
+/** A Pine icon name: letters, digits and hyphens, such as `hashtag`. Never a URL or file path. */
+const PINE_ICON_NAME = /^[a-z0-9-]+$/i;
+/**
+ * An optgroup's `data-icon` when it's a Pine icon name, or null. One definition of a usable group
+ * icon for every mode, checked here rather than trusting `pds-icon` to reject anything else; it is
+ * only ever passed to `pds-icon` as `name`.
+ */
+export function groupIconOf(optgroup) {
+    const icon = optgroup.getAttribute('data-icon');
+    return icon !== null && PINE_ICON_NAME.test(icon) ? icon : null;
+}
+/** An option is disabled by its own `disabled` or its optgroup's, as in a native select. */
+export function isOptionDisabled(option) {
+    var _a;
+    if (option === null || option === undefined)
+        return false;
+    return option.hasAttribute('disabled') || ((_a = parentOptgroupOf(option)) === null || _a === void 0 ? void 0 : _a.hasAttribute('disabled')) === true;
+}
+/** A group with no option left to choose. It still opens, so its options can be seen. */
+export function isGroupDisabled(group) {
+    return group.options.every(({ option }) => isOptionDisabled(option));
+}
+/**
+ * Groups the combobox's filtered items for the panel: each optgroup becomes one entry holding its
+ * options, and ungrouped options stay where they are. Indexes count options in list order, the
+ * same as the inline listbox, so `data-option-index` means the same thing in every mode.
+ */
+export function buildPanelEntries(items) {
+    const entries = [];
+    const groups = new Map();
+    let index = 0;
+    items.forEach(item => {
+        if (item.tagName !== 'OPTION')
+            return;
+        const option = item;
+        const optgroup = parentOptgroupOf(option);
+        if (optgroup !== null) {
+            let group = groups.get(optgroup);
+            if (!group) {
+                group = { optgroup, label: optgroup.label, icon: groupIconOf(optgroup), options: [] };
+                groups.set(optgroup, group);
+                entries.push({ kind: 'group', group });
+            }
+            group.options.push({ option, index: index++ });
+        }
+        else {
+            entries.push({ kind: 'option', option, index: index++ });
+        }
+    });
+    return entries;
+}
+/** The label of the optgroup an option sits in, or null for an ungrouped option. */
+export function groupLabelOf(option) {
+    var _a, _b;
+    return (_b = (_a = parentOptgroupOf(option)) === null || _a === void 0 ? void 0 : _a.label) !== null && _b !== void 0 ? _b : null;
+}
+/**
+ * The items Up and Down move through from `current`, one tree level at a time: the panel's rows
+ * (groups and ungrouped options), or the open group's options. Drilled into a group, its row
+ * (drawn as the row back) comes first, above its options, as a tree draws a parent above its children.
+ * Disabled options and groups stay in it, as the APG listbox and tree patterns advise, so they're
+ * announced as unavailable rather than hidden from the keyboard.
+ */
+export function panelColumn(entries, openGroup, current, drilledIn) {
+    const open = openGroup === null ? undefined : findGroup(entries, openGroup);
+    if (open !== undefined) {
+        const options = open.options.map(({ index }) => index);
+        if (drilledIn)
+            return [open.optgroup, ...options];
+        if (typeof current === 'number' && options.includes(current))
+            return options;
+    }
+    return entries.map(entry => (entry.kind === 'group' ? entry.group.optgroup : entry.index));
+}
+/** The panel's group for an optgroup, if it's showing. */
+export function findGroup(entries, optgroup) {
+    for (const entry of entries) {
+        if (entry.kind === 'group' && entry.group.optgroup === optgroup)
+            return entry.group;
+    }
+    return undefined;
+}
+/** Moving from one group row to another waits this long, so a diagonal trip into the flyout doesn't switch groups. */
+const SWITCH_DELAY_MS = 120;
+/** Leaving a group (into the gap beside its flyout, say) waits this long before closing it. */
+const CLOSE_DELAY_MS = 200;
+/** Space between the panel's edge and the flyout: --pine-dimension-050 (4px), per the Figma frames. */
+const FLYOUT_GAP_PX = 4;
+/** How close the flyout may come to the viewport edge: --pine-dimension-100 (8px). */
+const VIEWPORT_PADDING_PX = 8;
+/** A flyout never shrinks below roughly three rows, even when little space is left. */
+const MIN_FLYOUT_HEIGHT_PX = 120;
+/**
+ * Opens and closes a group's flyout with hover intent, and keeps the open flyout positioned beside
+ * its group row. The flyout renders inside the row, so moving the pointer into it never leaves
+ * the row; the delays cover the gap between panel and flyout and diagonal moves across rows.
+ */
+/**
+ * Scrolls `el` into view inside `container` only. A flyout option needs this: the flyout is `fixed`
+ * beside the panel but sits inside it in the DOM, so `scrollIntoView` would also scroll the panel
+ * and the page, moving the flyout's row out from under it.
+ */
+export function scrollIntoViewWithin(container, el) {
+    const bounds = container.getBoundingClientRect();
+    const rect = el.getBoundingClientRect();
+    if (rect.top < bounds.top) {
+        container.scrollTop -= bounds.top - rect.top;
+    }
+    else if (rect.bottom > bounds.bottom) {
+        container.scrollTop += rect.bottom - bounds.bottom;
+    }
+}
+export class FlyoutController {
+    constructor(getOpenGroup, setOpenGroup) {
+        this.getOpenGroup = getOpenGroup;
+        this.setOpenGroup = setOpenGroup;
+    }
+    /** Pointer entered a group row (or its flyout, which sits inside it). */
+    enter(label) {
+        this.clearClose();
+        const open = this.getOpenGroup();
+        if (open === label) {
+            this.clearSwitch();
+            return;
+        }
+        if (open === null) {
+            this.setOpenGroup(label);
+            return;
+        }
+        this.clearSwitch();
+        this.switchTimer = setTimeout(() => {
+            this.switchTimer = undefined;
+            this.setOpenGroup(label);
+        }, SWITCH_DELAY_MS);
+    }
+    /** Pointer left a group row and its flyout. */
+    leave(label) {
+        this.clearSwitch();
+        if (this.getOpenGroup() !== label)
+            return;
+        this.clearClose();
+        this.closeTimer = setTimeout(() => {
+            this.closeTimer = undefined;
+            if (this.getOpenGroup() === label)
+                this.setOpenGroup(null);
+        }, CLOSE_DELAY_MS);
+    }
+    /**
+     * A click or tap on a group row opens it. It never closes it: on desktop the hover that preceded
+     * the click has already opened it, and touch browsers fire an emulated mouseenter and then click
+     * in the same tap. Closing happens on leaving the row or closing the panel.
+     */
+    open(label) {
+        this.clearTimers();
+        this.setOpenGroup(label);
+    }
+    /**
+     * Keeps `flyout` beside `row`: horizontally against the panel's edge, vertically so its first
+     * option lines up with the row. `fixed` positioning so the panel's scrolling can't clip it,
+     * including when the panel is portaled into a dialog.
+     */
+    position(row, panel, flyout) {
+        if (this.positionedFlyout === flyout && this.stopAutoUpdate)
+            return;
+        this.stopPositioning();
+        this.positionedFlyout = flyout;
+        const reference = {
+            getBoundingClientRect: () => {
+                const panelRect = panel.getBoundingClientRect();
+                const rowRect = row.getBoundingClientRect();
+                return {
+                    x: panelRect.x,
+                    y: rowRect.y,
+                    left: panelRect.left,
+                    right: panelRect.right,
+                    top: rowRect.top,
+                    bottom: rowRect.bottom,
+                    width: panelRect.width,
+                    height: rowRect.height,
+                };
+            },
+            contextElement: row,
+        };
+        // The flyout's own top padding, so its first option, not its edge, lines up with the row.
+        const flyoutPaddingTop = parseFloat(getComputedStyle(flyout).paddingTop) || 0;
+        const update = () => computePosition(reference, flyout, {
+            placement: 'right-start',
+            strategy: 'fixed',
+            middleware: [
+                offset({ mainAxis: FLYOUT_GAP_PX, crossAxis: -flyoutPaddingTop }),
+                flip({ fallbackPlacements: ['left-start'] }),
+                shift({ padding: VIEWPORT_PADDING_PX }),
+                // A long group scrolls inside the flyout instead of running off the viewport.
+                size({
+                    padding: VIEWPORT_PADDING_PX,
+                    apply({ availableHeight }) {
+                        flyout.style.maxHeight = `${Math.max(availableHeight, MIN_FLYOUT_HEIGHT_PX)}px`;
+                    },
+                }),
+                // Hidden with its row when the panel scrolls the row out of view.
+                hide({ strategy: 'referenceHidden' }),
+            ],
+        }).then(({ x, y, middlewareData }) => {
+            var _a;
+            // It starts hidden (see the stylesheet) so it never flashes in the row before it's placed.
+            Object.assign(flyout.style, {
+                position: 'fixed',
+                left: `${x}px`,
+                top: `${y}px`,
+                visibility: ((_a = middlewareData.hide) === null || _a === void 0 ? void 0 : _a.referenceHidden) === true ? 'hidden' : 'visible',
+            });
+            const reveal = this.pendingReveal;
+            this.pendingReveal = undefined;
+            if (reveal !== undefined && flyout.contains(reveal))
+                scrollIntoViewWithin(flyout, reveal);
+        });
+        this.stopAutoUpdate = autoUpdate(reference, flyout, () => {
+            void update();
+        });
+    }
+    /**
+     * Scrolls `option` into view inside its flyout. Before the flyout's first placement its height
+     * isn't capped yet, so the option looks visible; it's revealed again once the placement lands.
+     */
+    reveal(flyout, option) {
+        scrollIntoViewWithin(flyout, option);
+        if (flyout.style.maxHeight === '')
+            this.pendingReveal = option;
+    }
+    stopPositioning() {
+        var _a;
+        (_a = this.stopAutoUpdate) === null || _a === void 0 ? void 0 : _a.call(this);
+        this.stopAutoUpdate = undefined;
+        this.positionedFlyout = undefined;
+        this.pendingReveal = undefined;
+    }
+    /** The panel closed or the component left the page. */
+    reset() {
+        this.clearTimers();
+        this.stopPositioning();
+    }
+    clearTimers() {
+        this.clearSwitch();
+        this.clearClose();
+    }
+    clearSwitch() {
+        if (this.switchTimer !== undefined)
+            clearTimeout(this.switchTimer);
+        this.switchTimer = undefined;
+    }
+    clearClose() {
+        if (this.closeTimer !== undefined)
+            clearTimeout(this.closeTimer);
+        this.closeTimer = undefined;
+    }
+}

package/dist/collection/components/pds-combobox/pds-combobox.css

@@ -156,6 +156,22 @@
   background: var(--pine-color-background-muted);
 }
 
+.pds-combobox__option--disabled,
+.pds-combobox__group-row--disabled > .pds-combobox__group-row-trigger,
+.pds-combobox__group-back--disabled > .pds-combobox__group-back-trigger,
+.pds-combobox__group--disabled > .pds-combobox__group-label {
+  color: var(--pine-color-text-disabled);
+}
+
+.pds-combobox__option--disabled {
+  cursor: not-allowed;
+}
+
+.pds-combobox__option--disabled .pds-combobox__option-chip,
+.pds-combobox__option--disabled .pds-combobox__option-layout-wrapper {
+  opacity: 0.5;
+}
+
 .pds-combobox__option-check {
   color: currentColor;
   font-size: var(--pine-dimension-150);
@@ -175,6 +191,232 @@
   margin-block-start: 0;
 }
 
+.pds-combobox__group {
+  list-style: none;
+  margin-block-start: var(--pine-dimension-150);
+}
+.pds-combobox__group:first-child {
+  margin-block-start: 0;
+}
+
+.pds-combobox__group-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.pds-combobox__listbox--grouped .pds-combobox__group-list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--pine-dimension-2xs);
+}
+
+.pds-combobox__group-label--with-icon {
+  align-items: center;
+  display: flex;
+  gap: var(--pine-dimension-xs);
+}
+
+.pds-combobox__group-icon {
+  flex-shrink: 0;
+}
+
+.pds-combobox__group-row {
+  list-style: none;
+  position: relative;
+}
+
+.pds-combobox__group-row-trigger {
+  align-items: center;
+  border-radius: var(--pine-dimension-125);
+  color: var(--pine-color-text-secondary);
+  cursor: pointer;
+  display: flex;
+  font: var(--pine-typography-body-medium);
+  gap: var(--pine-dimension-xs);
+  justify-content: space-between;
+  padding: var(--pine-dimension-xs) var(--pine-dimension-sm);
+  /* stylelint-disable-next-line pine-design-system/no-hardcoded-motion -- matches .pds-combobox__option's 0.15s micro-transition */
+  transition: background 0.15s;
+}
+
+.pds-combobox__group-row--open > .pds-combobox__group-row-trigger,
+.pds-combobox__group-row--has-selection > .pds-combobox__group-row-trigger,
+.pds-combobox__group-row--highlighted > .pds-combobox__group-row-trigger,
+.pds-combobox__group-back--highlighted > .pds-combobox__group-row-trigger,
+.pds-combobox__group-row-trigger:hover {
+  background: var(--pine-color-background-muted);
+}
+
+.pds-combobox__listbox--drill-in,
+.pds-combobox__listbox--drill-out {
+  overflow-x: hidden;
+}
+
+.pds-combobox__listbox--drill-in > .pds-combobox__group-back {
+  animation: pds-combobox-drill-from-end var(--pine-motion-duration-base) var(--pine-motion-easing-out);
+}
+
+.pds-combobox__listbox--drill-out > li {
+  animation: pds-combobox-drill-from-start var(--pine-motion-duration-base) var(--pine-motion-easing-out);
+}
+
+@keyframes pds-combobox-drill-from-end {
+  from {
+    opacity: 0;
+    transform: translateX(var(--pine-dimension-sm));
+  }
+}
+@keyframes pds-combobox-drill-from-start {
+  from {
+    opacity: 0;
+    transform: translateX(calc(var(--pine-dimension-sm) * -1));
+  }
+}
+.pds-combobox__group-row--keyboard > .pds-combobox__group-row-trigger,
+.pds-combobox__group-back--keyboard > .pds-combobox__group-row-trigger {
+  outline: var(--pine-outline-focus);
+  outline-offset: calc(var(--pine-border-width) * -2);
+}
+
+.pds-combobox__group-row-label {
+  align-items: center;
+  display: flex;
+  gap: var(--pine-dimension-xs);
+  min-width: 0;
+}
+
+.pds-combobox__group-row-caret {
+  flex-shrink: 0;
+}
+
+.pds-combobox__listbox--grouped,
+.pds-combobox__flyout {
+  display: flex;
+  flex-direction: column;
+  gap: var(--pine-dimension-2xs);
+  padding: var(--pine-dimension-2xs);
+}
+
+.pds-combobox__flyout {
+  background: var(--pine-color-background-overlay);
+  border-radius: var(--pine-dimension-125);
+  box-shadow: var(--pine-box-shadow);
+  list-style: none;
+  margin: 0;
+  overflow-y: auto;
+  position: fixed;
+  visibility: hidden;
+  width: max-content;
+  z-index: 1;
+}
+
+.pds-combobox__listbox--with-search {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  padding: 0;
+}
+
+.pds-combobox__listbox-options {
+  flex: 1;
+  list-style: none;
+  margin: 0;
+  min-height: 0;
+  overflow-y: auto;
+  padding: var(--pine-dimension-xs);
+}
+
+.pds-combobox__listbox-options.pds-combobox__listbox--grouped {
+  padding: var(--pine-dimension-2xs);
+}
+
+.pds-combobox__panel-search {
+  align-items: center;
+  border-block-end: var(--pine-border);
+  border-block-end-color: var(--pine-color-border-subtle);
+  display: flex;
+  flex-shrink: 0;
+  gap: var(--pine-dimension-xs);
+  padding: var(--pine-dimension-xs) var(--pine-dimension-sm);
+}
+.pds-combobox__panel-search pds-icon {
+  color: var(--pine-color-text-muted);
+  flex-shrink: 0;
+}
+.pds-combobox__panel-search:focus-within {
+  border-block-end-color: var(--pine-color-border-active);
+}
+
+.pds-combobox__panel-search-input {
+  background: transparent;
+  border: 0;
+  color: var(--pine-color-text-strong);
+  flex: 1;
+  font: var(--pine-typography-body);
+  letter-spacing: var(--pine-letter-spacing);
+  min-width: 0;
+  outline: none;
+}
+.pds-combobox__panel-search-input::placeholder {
+  color: var(--pine-color-text-placeholder);
+}
+
+.pds-combobox__group-back {
+  display: flex;
+  flex-direction: column;
+  gap: var(--pine-dimension-2xs);
+  list-style: none;
+}
+
+.pds-combobox__group-back-trigger {
+  justify-content: flex-start;
+}
+
+.pds-combobox__listbox-options--drilled-in.pds-combobox__listbox--grouped {
+  padding-block-start: 0;
+}
+
+.pds-combobox__listbox-options--drilled-in:focus {
+  outline: none;
+}
+.pds-combobox__listbox-options--drilled-in:focus .pds-combobox__group-back-trigger {
+  border-block-end-color: var(--pine-color-border-active);
+}
+
+:where(.pds-combobox__listbox-options--drilled-in) .pds-combobox__group-back-trigger {
+  background-color: var(--pine-color-background-overlay);
+  border-block-end: var(--pine-border);
+  border-block-end-color: var(--pine-color-border-subtle);
+  border-radius: 0;
+  inset-block-start: 0;
+  margin-inline: calc(var(--pine-dimension-2xs) * -1);
+  position: sticky;
+  z-index: 1;
+}
+
+.pds-combobox__drill-in-options {
+  display: flex;
+  flex-direction: column;
+  gap: var(--pine-dimension-2xs);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.visually-hidden {
+  border: 0;
+  clip: rect(0 0 0 0);
+  clip-path: polygon(0 0, 0 0, 0 0);
+  height: 1px;
+  margin: -1px;
+  overflow: hidden;
+  padding: 0;
+  position: absolute;
+  white-space: nowrap;
+  width: 1px;
+}
+
 .pds-combobox__loading {
   align-items: center;
   display: flex;
@@ -311,19 +553,6 @@
   --color-outline: var(--pine-color-focus-ring-danger);
 }
 
-.visually-hidden {
-  border: 0;
-  clip: rect(0 0 0 0);
-  clip-path: polygon(0 0, 0 0, 0 0);
-  height: 1px;
-  margin: -1px;
-  overflow: hidden;
-  padding: 0;
-  position: absolute;
-  white-space: nowrap;
-  width: 1px;
-}
-
 [data-layout] {
   border-radius: var(--pine-dimension-125);
   padding-block: var(--pine-dimension-xs);