bits-ui 2.5.0 → 2.6.1

package/dist/bits/command/command.svelte.d.ts

@@ -1,12 +1,20 @@
 import type { CommandState } from "./types.js";
 import type { BitsKeyboardEvent, BitsMouseEvent, BitsPointerEvent, WithRefProps } from "../../internal/types.js";
 import type { ReadableBoxedValues, WritableBoxedValues } from "../../internal/box.svelte.js";
+type GridItem = {
+    index: number;
+    firstRowOfGroup: boolean;
+    ref: HTMLElement;
+};
+type ItemsGrid = GridItem[][];
 type CommandRootStateProps = WithRefProps<ReadableBoxedValues<{
     filter: (value: string, search: string, keywords?: string[]) => number;
     shouldFilter: boolean;
     loop: boolean;
     vimBindings: boolean;
+    columns: number | null;
     disablePointerSelection: boolean;
+    disableInitialScroll: boolean;
     onStateChange?: (state: Readonly<CommandState>) => void;
 }> & WritableBoxedValues<{
     value: string;
@@ -28,7 +36,7 @@ declare class CommandRootState {
     labelNode: HTMLElement | null;
     commandState: CommandState;
     _commandState: CommandState;
-    setState<K extends keyof CommandState>(key: K, value: CommandState[K], opts?: boolean): void;
+    setState<K extends keyof CommandState>(key: K, value: CommandState[K], preventScroll?: boolean): void;
     constructor(opts: CommandRootStateProps);
     /**
      * Sets current value and triggers re-render if cleared.
@@ -43,6 +51,20 @@ declare class CommandRootState {
      * @remarks Exposed for direct item access and bound checking
      */
     getValidItems(): HTMLElement[];
+    /**
+     * Gets all visible command items.
+     *
+     * @returns Array of valid item elements
+     * @remarks Exposed for direct item access and bound checking
+     */
+    getVisibleItems(): HTMLElement[];
+    /** Returns all visible items in a matrix structure
+     *
+     * @remarks Returns empty if the command isn't configured as a grid
+     *
+     * @returns
+     */
+    get itemsGrid(): ItemsGrid;
     /**
      * Sets selection to item at specified index in valid items array.
      * If index is out of bounds, does nothing.
@@ -80,7 +102,7 @@ declare class CommandRootState {
      * // get all valid items
      * const items = getValidItems()
      */
-    updateSelectedByItem(change: 1 | -1): void;
+    updateSelectedByItem(change: number): void;
     /**
      * Moves selection to the first valid item in the next/previous group.
      * If no group is found, falls back to selecting the next/previous item globally.
@@ -120,6 +142,7 @@ declare class CommandRootState {
      * @returns Cleanup function
      */
     registerGroup(id: string): () => void;
+    get isGrid(): boolean;
     onkeydown(e: BitsKeyboardEvent): void;
     props: {
         readonly id: string;
@@ -230,6 +253,7 @@ declare class CommandItemState {
         readonly "data-disabled": "" | undefined;
         readonly "data-selected": "" | undefined;
         readonly "data-value": string;
+        readonly "data-group": string | undefined;
         readonly role: "option";
         readonly onpointermove: (_: BitsPointerEvent) => void;
         readonly onclick: (_: BitsMouseEvent) => void;

package/dist/bits/command/command.svelte.js

@@ -50,6 +50,7 @@ const defaultState = {
 class CommandRootState {
     opts;
     #updateScheduled = false;
+    #isInitialMount = true;
     sortAfterTick = false;
     sortAndFilterAfterTick = false;
     allItems = new Set();
@@ -81,7 +82,7 @@ class CommandRootState {
             }
         });
     }
-    setState(key, value, opts) {
+    setState(key, value, preventScroll) {
         if (Object.is(this._commandState[key], value))
             return;
         this._commandState[key] = value;
@@ -91,11 +92,8 @@ class CommandRootState {
             this.#sort();
         }
         else if (key === "value") {
-            // opts is a boolean referring to whether it should NOT be scrolled into view
-            if (!opts) {
-                // Scroll the selected item into view
+            if (!preventScroll)
                 this.#scrollSelectedIntoView();
-            }
         }
         this.#scheduleUpdate();
     }
@@ -128,9 +126,6 @@ class CommandRootState {
         if (!this._commandState.search || this.opts.shouldFilter.current === false) {
             // If no search and no selection yet, select first item
             this.#selectFirstItem();
-            // if (!this.commandState.value) {
-            // this.#selectFirstItem();
-            // }
             return;
         }
         const scores = this._commandState.filtered.items;
@@ -208,7 +203,9 @@ class CommandRootState {
         afterTick(() => {
             const item = this.getValidItems().find((item) => item.getAttribute("aria-disabled") !== "true");
             const value = item?.getAttribute(COMMAND_VALUE_ATTR);
-            this.setValue(value || "");
+            const shouldPreventScroll = this.#isInitialMount && this.opts.disableInitialScroll.current;
+            this.setValue(value ?? "", shouldPreventScroll);
+            this.#isInitialMount = false;
         });
     }
     /**
@@ -257,6 +254,59 @@ class CommandRootState {
         const validItems = Array.from(node.querySelectorAll(COMMAND_VALID_ITEM_SELECTOR)).filter((el) => !!el);
         return validItems;
     }
+    /**
+     * Gets all visible command items.
+     *
+     * @returns Array of valid item elements
+     * @remarks Exposed for direct item access and bound checking
+     */
+    getVisibleItems() {
+        const node = this.opts.ref.current;
+        if (!node)
+            return [];
+        const visibleItems = Array.from(node.querySelectorAll(COMMAND_ITEM_SELECTOR)).filter((el) => !!el);
+        return visibleItems;
+    }
+    /** Returns all visible items in a matrix structure
+     *
+     * @remarks Returns empty if the command isn't configured as a grid
+     *
+     * @returns
+     */
+    get itemsGrid() {
+        if (!this.isGrid)
+            return [];
+        const columns = this.opts.columns.current ?? 1;
+        const items = this.getVisibleItems();
+        const grid = [[]];
+        let currentGroup = items[0]?.getAttribute("data-group");
+        let column = 0;
+        let row = 0;
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            const itemGroup = item?.getAttribute("data-group");
+            if (currentGroup !== itemGroup) {
+                currentGroup = itemGroup;
+                column = 1;
+                row++;
+                grid.push([{ index: i, firstRowOfGroup: true, ref: item }]);
+            }
+            else {
+                column++;
+                if (column > columns) {
+                    row++;
+                    column = 1;
+                    grid.push([]);
+                }
+                grid[row]?.push({
+                    index: i,
+                    firstRowOfGroup: grid[row]?.[0]?.firstRowOfGroup ?? i === 0,
+                    ref: item,
+                });
+            }
+        }
+        return grid;
+    }
     /**
      * Gets currently selected command item.
      *
@@ -283,17 +333,47 @@ class CommandRootState {
             const grandparent = item.parentElement?.parentElement;
             if (!grandparent)
                 return;
-            const firstChildOfParent = getFirstNonCommentChild(grandparent);
-            if (firstChildOfParent && firstChildOfParent.dataset?.value === item.dataset?.value) {
-                const closestGroupHeader = item
-                    ?.closest(COMMAND_GROUP_SELECTOR)
-                    ?.querySelector(COMMAND_GROUP_HEADING_SELECTOR);
-                closestGroupHeader?.scrollIntoView({ block: "nearest" });
-                return;
+            if (this.isGrid) {
+                const isFirstRowOfGroup = this.#itemIsFirstRowOfGroup(item);
+                if (isFirstRowOfGroup) {
+                    const closestGroupHeader = item
+                        ?.closest(COMMAND_GROUP_SELECTOR)
+                        ?.querySelector(COMMAND_GROUP_HEADING_SELECTOR);
+                    closestGroupHeader?.scrollIntoView({ block: "nearest" });
+                    return;
+                }
+            }
+            else {
+                const firstChildOfParent = getFirstNonCommentChild(grandparent);
+                if (firstChildOfParent &&
+                    firstChildOfParent.dataset?.value === item.dataset?.value) {
+                    const closestGroupHeader = item
+                        ?.closest(COMMAND_GROUP_SELECTOR)
+                        ?.querySelector(COMMAND_GROUP_HEADING_SELECTOR);
+                    closestGroupHeader?.scrollIntoView({ block: "nearest" });
+                    return;
+                }
             }
             item.scrollIntoView({ block: "nearest" });
         });
     }
+    #itemIsFirstRowOfGroup(item) {
+        const grid = this.itemsGrid;
+        if (grid.length === 0)
+            return false;
+        for (let r = 0; r < grid.length; r++) {
+            const row = grid[r];
+            if (row === undefined)
+                continue;
+            for (let c = 0; c < row.length; c++) {
+                const column = row[c];
+                if (column === undefined || column.ref !== item)
+                    continue;
+                return column.firstRowOfGroup;
+            }
+        }
+        return false;
+    }
     /**
      * Sets selection to item at specified index in valid items array.
      * If index is out of bounds, does nothing.
@@ -311,11 +391,10 @@ class CommandRootState {
      * }
      */
     updateSelectedToIndex(index) {
-        const items = this.getValidItems();
-        const item = items[index];
-        if (item) {
-            this.setValue(item.getAttribute(COMMAND_VALUE_ATTR) ?? "");
-        }
+        const item = this.getValidItems()[index];
+        if (!item)
+            return;
+        this.setValue(item.getAttribute(COMMAND_VALUE_ATTR) ?? "");
     }
     /**
      * Updates selected item by moving up/down relative to current selection.
@@ -469,6 +548,9 @@ class CommandRootState {
             this.allGroups.delete(id);
         };
     }
+    get isGrid() {
+        return this.opts.columns.current !== null;
+    }
     /**
      * Selects last valid item.
      */
@@ -495,6 +577,224 @@ class CommandRootState {
             this.updateSelectedByItem(1);
         }
     }
+    #down(e) {
+        if (this.opts.columns.current === null)
+            return;
+        e.preventDefault();
+        if (e.metaKey) {
+            this.updateSelectedByGroup(1);
+        }
+        else {
+            this.updateSelectedByItem(this.#nextRowColumnOffset(e));
+        }
+    }
+    #getColumn(item, grid) {
+        if (grid.length === 0)
+            return null;
+        for (let r = 0; r < grid.length; r++) {
+            const row = grid[r];
+            if (row === undefined)
+                continue;
+            for (let c = 0; c < row.length; c++) {
+                const column = row[c];
+                if (column === undefined || column.ref !== item)
+                    continue;
+                return { columnIndex: c, rowIndex: r };
+            }
+        }
+        return null;
+    }
+    #nextRowColumnOffset(e) {
+        const grid = this.itemsGrid;
+        const selected = this.#getSelectedItem();
+        if (!selected)
+            return 0;
+        const column = this.#getColumn(selected, grid);
+        if (!column)
+            return 0;
+        let newItem = null;
+        const skipRows = e.altKey ? 1 : 0;
+        // if this is the second to last row then we need to go to the last row when skipping and not in loop mode
+        if (e.altKey && column.rowIndex === grid.length - 2 && !this.opts.loop.current) {
+            newItem = this.#findNextNonDisabledItem({
+                start: grid.length - 1,
+                end: grid.length,
+                expectedColumnIndex: column.columnIndex,
+                grid,
+            });
+        }
+        else if (column.rowIndex === grid.length - 1) {
+            // if this is the last row we apply the loop logic
+            if (!this.opts.loop.current)
+                return 0;
+            newItem = this.#findNextNonDisabledItem({
+                start: 0 + skipRows,
+                end: column.rowIndex,
+                expectedColumnIndex: column.columnIndex,
+                grid,
+            });
+        }
+        else {
+            newItem = this.#findNextNonDisabledItem({
+                start: column.rowIndex + 1 + skipRows,
+                end: grid.length,
+                expectedColumnIndex: column.columnIndex,
+                grid,
+            });
+            // this happens if there were no non-disabled columns below the current column
+            // we can now try starting from the beginning to find the right column
+            if (newItem === null && this.opts.loop.current) {
+                newItem = this.#findNextNonDisabledItem({
+                    start: 0,
+                    end: column.rowIndex,
+                    expectedColumnIndex: column.columnIndex,
+                    grid,
+                });
+            }
+        }
+        return this.#calculateOffset(selected, newItem);
+    }
+    /** Attempts to find the next non-disabled column that matches the expected column.
+     *
+     * @remarks
+     * - Skips over disabled columns
+     * - When a row is shorter than the expected column it defaults to the last item in the row
+     *
+     * @param param0
+     * @returns
+     */
+    #findNextNonDisabledItem({ start, end, grid, expectedColumnIndex, }) {
+        let newItem = null;
+        for (let r = start; r < end; r++) {
+            const row = grid[r];
+            // try to get the next column
+            newItem = row[expectedColumnIndex]?.ref ?? null;
+            // skip over disabled items
+            if (newItem !== null && itemIsDisabled(newItem)) {
+                newItem = null;
+                continue;
+            }
+            // if that column doesn't exist default to the next highest column
+            if (newItem === null) {
+                // try and find the next highest non-disabled item in the row
+                // if there aren't any non-disabled items we just give up and return null
+                for (let i = row.length - 1; i >= 0; i--) {
+                    const item = row[row.length - 1];
+                    if (item === undefined || itemIsDisabled(item.ref))
+                        continue;
+                    newItem = item.ref;
+                    break;
+                }
+            }
+            break;
+        }
+        return newItem;
+    }
+    #calculateOffset(selected, newSelected) {
+        if (newSelected === null)
+            return 0;
+        const items = this.getValidItems();
+        const ogIndex = items.findIndex((item) => item === selected);
+        const newIndex = items.findIndex((item) => item === newSelected);
+        return newIndex - ogIndex;
+    }
+    #up(e) {
+        if (this.opts.columns.current === null)
+            return;
+        e.preventDefault();
+        if (e.metaKey) {
+            this.updateSelectedByGroup(-1);
+        }
+        else {
+            this.updateSelectedByItem(this.#previousRowColumnOffset(e));
+        }
+    }
+    #previousRowColumnOffset(e) {
+        const grid = this.itemsGrid;
+        const selected = this.#getSelectedItem();
+        if (selected === undefined)
+            return 0;
+        const column = this.#getColumn(selected, grid);
+        if (column === null)
+            return 0;
+        let newItem = null;
+        const skipRows = e.altKey ? 1 : 0;
+        // if this is the second row then we need to go to the top when skipping and not in loop mode
+        if (e.altKey && column.rowIndex === 1 && this.opts.loop.current === false) {
+            newItem = this.#findNextNonDisabledItemDesc({
+                start: 0,
+                end: 0,
+                expectedColumnIndex: column.columnIndex,
+                grid,
+            });
+        }
+        else if (column.rowIndex === 0) {
+            // if this is the last row we apply the loop logic
+            if (this.opts.loop.current === false)
+                return 0;
+            newItem = this.#findNextNonDisabledItemDesc({
+                start: grid.length - 1 - skipRows,
+                end: column.rowIndex + 1,
+                expectedColumnIndex: column.columnIndex,
+                grid,
+            });
+        }
+        else {
+            newItem = this.#findNextNonDisabledItemDesc({
+                start: column.rowIndex - 1 - skipRows,
+                end: 0,
+                expectedColumnIndex: column.columnIndex,
+                grid,
+            });
+            // this happens if there were no non-disabled columns below the current column
+            // we can now try starting from the beginning to find the right column
+            if (newItem === null && this.opts.loop.current) {
+                newItem = this.#findNextNonDisabledItemDesc({
+                    start: grid.length - 1,
+                    end: column.rowIndex + 1,
+                    expectedColumnIndex: column.columnIndex,
+                    grid,
+                });
+            }
+        }
+        return this.#calculateOffset(selected, newItem);
+    }
+    /**
+     * Attempts to find the next non-disabled column that matches the expected column.
+     *
+     * @remarks
+     * - Skips over disabled columns
+     * - When a row is shorter than the expected column it defaults to the last item in the row
+     */
+    #findNextNonDisabledItemDesc({ start, end, grid, expectedColumnIndex, }) {
+        let newItem = null;
+        for (let r = start; r >= end; r--) {
+            const row = grid[r];
+            if (row === undefined)
+                continue;
+            // try to get the next column
+            newItem = row[expectedColumnIndex]?.ref ?? null;
+            // skip over disabled items
+            if (newItem !== null && itemIsDisabled(newItem)) {
+                newItem = null;
+                continue;
+            }
+            // if that column doesn't exist default to the next highest column
+            if (newItem === null) {
+                // try and find the next highest non-disabled item in the row
+                // if there aren't any non-disabled items we just give up and return null
+                for (let i = row.length - 1; i >= 0; i--) {
+                    const item = row[row.length - 1];
+                    if (item === undefined || itemIsDisabled(item.ref))
+                        continue;
+                    newItem = item.ref;
+                    break;
+                }
+            }
+            break;
+        }
+        return newItem;
+    }
     /**
      * Handles previous item selection:
      * - Meta: Jump to first
@@ -519,27 +819,74 @@ class CommandRootState {
         }
     }
     onkeydown(e) {
+        const isVim = this.opts.vimBindings.current && e.ctrlKey;
         switch (e.key) {
             case kbd.n:
             case kbd.j: {
                 // vim down
-                if (this.opts.vimBindings.current && e.ctrlKey) {
-                    this.#next(e);
+                if (isVim) {
+                    if (this.isGrid) {
+                        this.#down(e);
+                    }
+                    else {
+                        this.#next(e);
+                    }
+                }
+                break;
+            }
+            case kbd.l: {
+                // vim right
+                if (isVim) {
+                    if (this.isGrid) {
+                        this.#next(e);
+                    }
                 }
                 break;
             }
             case kbd.ARROW_DOWN:
+                if (this.isGrid) {
+                    this.#down(e);
+                }
+                else {
+                    this.#next(e);
+                }
+                break;
+            case kbd.ARROW_RIGHT:
+                if (!this.isGrid)
+                    break;
                 this.#next(e);
                 break;
             case kbd.p:
             case kbd.k: {
                 // vim up
-                if (this.opts.vimBindings.current && e.ctrlKey) {
+                if (isVim) {
+                    if (this.isGrid) {
+                        this.#up(e);
+                    }
+                    else {
+                        this.#prev(e);
+                    }
+                }
+                break;
+            }
+            case kbd.h: {
+                // vim left
+                if (isVim && this.isGrid) {
                     this.#prev(e);
                 }
                 break;
             }
             case kbd.ARROW_UP:
+                if (this.isGrid) {
+                    this.#up(e);
+                }
+                else {
+                    this.#prev(e);
+                }
+                break;
+            case kbd.ARROW_LEFT:
+                if (!this.isGrid)
+                    break;
                 this.#prev(e);
                 break;
             case kbd.HOME:
@@ -578,6 +925,9 @@ class CommandRootState {
         ...attachRef(this.opts.ref),
     }));
 }
+function itemIsDisabled(item) {
+    return item.getAttribute("aria-disabled") === "true";
+}
 class CommandEmptyState {
     opts;
     root;
@@ -678,9 +1028,9 @@ class CommandInputState {
     root;
     #selectedItemId = $derived.by(() => {
         const item = this.root.viewportNode?.querySelector(`${COMMAND_ITEM_SELECTOR}[${COMMAND_VALUE_ATTR}="${cssesc(this.root.opts.value.current)}"]`);
-        if (!item)
+        if (item === undefined || item === null)
             return;
-        return item?.getAttribute("id") ?? undefined;
+        return item.getAttribute("id") ?? undefined;
     });
     constructor(opts, root) {
         this.opts = opts;
@@ -787,6 +1137,7 @@ class CommandItemState {
         "data-disabled": getDataDisabled(this.opts.disabled.current),
         "data-selected": getDataSelected(this.isSelected),
         "data-value": this.trueValue,
+        "data-group": this.#group?.trueValue,
         [commandAttrs.item]: "",
         role: "option",
         onpointermove: this.onpointermove,
@@ -865,7 +1216,7 @@ class CommandViewportState {
         $effect(() => {
             const node = this.opts.ref.current;
             const listNode = this.list.opts.ref.current;
-            if (!node || !listNode)
+            if (node === null || listNode === null)
                 return;
             let aF;
             const observer = new ResizeObserver(() => {

package/dist/bits/command/components/command.svelte

@@ -21,6 +21,8 @@
 		label = "",
 		vimBindings = true,
 		disablePointerSelection = false,
+		disableInitialScroll = false,
+		columns = null,
 		children,
 		child,
 		...restProps
@@ -46,7 +48,9 @@
 		),
 		vimBindings: box.with(() => vimBindings),
 		disablePointerSelection: box.with(() => disablePointerSelection),
+		disableInitialScroll: box.with(() => disableInitialScroll),
 		onStateChange: box.with(() => onStateChange),
+		columns: box.with(() => columns),
 	});
 
 	// Imperative APIs - DO NOT REMOVE OR RENAME

package/dist/bits/command/components/command.svelte.d.ts

@@ -47,7 +47,7 @@ declare const Command: import("svelte").Component<CommandRootProps, {
          *
          * // get all valid items
          * const items = getValidItems()
-         */ updateSelectedByItem: (change: 1 | -1) => void;
+         */ updateSelectedByItem: (change: number) => void;
     /**
          * Gets all non-disabled, visible command items.
          *

package/dist/bits/command/types.d.ts

@@ -61,9 +61,23 @@ export type CommandRootPropsWithoutHTML = WithChild<{
     /**
      * Set this prop to `false` to disable the option to use ctrl+n/j/p/k (vim style) navigation.
      *
-     * @defaultValue true
+     * @default true
      */
     vimBindings?: boolean;
+    /**
+     * The number of columns in a grid layout.
+     *
+     * @default null
+     */
+    columns?: number | null;
+    /**
+     * Whether to disable scrolling the selected item into view on initial mount.
+     * When `true`, prevents automatic scrolling when the command menu first renders
+     * and selects its first item, but still allows scrolling on subsequent selections.
+     *
+     * @default false
+     */
+    disableInitialScroll?: boolean;
 }>;
 export type CommandRootProps = CommandRootPropsWithoutHTML & Without<BitsPrimitiveDivAttributes, CommandRootPropsWithoutHTML>;
 export type CommandEmptyPropsWithoutHTML = WithChild<{
@@ -94,7 +108,7 @@ export type CommandItemPropsWithoutHTML = WithChild<{
     /**
      * Whether the item is disabled.
      *
-     * @defaultValue false
+     * @default false
      */
     disabled?: boolean;
     /**

package/dist/bits/tabs/tabs.svelte.d.ts

@@ -85,6 +85,7 @@ declare class TabsContentState {
         readonly "data-value": string;
         readonly "data-state": "active" | "inactive";
         readonly "aria-labelledby": string | undefined;
+        readonly "data-orientation": "horizontal" | "vertical";
     };
 }
 export declare function useTabsRoot(props: TabsRootStateProps): TabsRootState;

package/dist/bits/tabs/tabs.svelte.js

@@ -159,6 +159,7 @@ class TabsContentState {
         "data-value": this.opts.value.current,
         "data-state": getTabDataState(this.#isActive),
         "aria-labelledby": this.#ariaLabelledBy,
+        "data-orientation": getDataOrientation(this.root.opts.orientation.current),
         [tabsAttrs.content]: "",
         ...attachRef(this.opts.ref),
     }));

package/dist/internal/floating-svelte/use-floating.svelte.js

@@ -16,7 +16,9 @@ export function useFloating(options) {
     let x = $state(0);
     let y = $state(0);
     const floating = box(null);
+    // svelte-ignore state_referenced_locally
     let strategy = $state(strategyOption);
+    // svelte-ignore state_referenced_locally
     let placement = $state(placementOption);
     let middlewareData = $state({});
     let isPositioned = $state(false);

package/dist/internal/kbd-constants.d.ts

@@ -38,3 +38,5 @@ export declare const p = "p";
 export declare const n = "n";
 export declare const j = "j";
 export declare const k = "k";
+export declare const h = "h";
+export declare const l = "l";

package/dist/internal/kbd-constants.js

@@ -38,3 +38,5 @@ export const p = "p";
 export const n = "n";
 export const j = "j";
 export const k = "k";
+export const h = "h";
+export const l = "l";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bits-ui",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "license": "MIT",
   "repository": "github:huntabyte/bits-ui",
   "funding": "https://github.com/sponsors/huntabyte",