@cl-light-ds/ui 0.4.0 → 0.6.0

package/src/components/command-search/CommandSearch.astro

@@ -0,0 +1,594 @@
+---
+/**
+ * @component CommandSearch
+ * @title Command Search
+ * @description A "Search everything…" button that opens a command palette (also with ⌘K, or Ctrl K off a Mac): a large search field with a Search button, results in groups, keyboard hints and a "Nothing matches" state. Searches run on Enter, not as you type.
+ *
+ * @preview
+ *
+ * <CommandSearch>
+ *   <CommandSearchGroup heading="Workspaces">
+ *     <CommandSearchItem label="Acme Finance" href="/workspaces/finance" />
+ *     <CommandSearchItem label="Acme HR" href="/workspaces/hr" />
+ *   </CommandSearchGroup>
+ *   <CommandSearchGroup heading="Recordings">
+ *     <CommandSearchItem label="Run the monthly payroll" value="rec-1">
+ *       <span slot="meta">in Acme HR</span>
+ *     </CommandSearchItem>
+ *   </CommandSearchGroup>
+ * </CommandSearch>
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { CommandSearch, CommandSearchGroup, CommandSearchItem } from '@cl-light-ds/ui/components/command-search';
+ * ---
+ *
+ * <!-- mode="filter" (default): your items, filtered in the page when a search runs -->
+ * <CommandSearch id="search">
+ *   <CommandSearchGroup heading="Workspaces">
+ *     <CommandSearchItem label="Acme Finance" href="/workspaces/finance" />
+ *   </CommandSearchGroup>
+ * </CommandSearch>
+ *
+ * <!-- mode="remote": you search and hand back the results -->
+ * <CommandSearch id="remote-search" mode="remote" />
+ * <script>
+ *   import { setCommandSearchResults } from '@cl-light-ds/ui/lib/command-search';
+ *   const palette = document.getElementById('remote-search');
+ *   palette.addEventListener('command-search:search', async (e) => {
+ *     setCommandSearchResults(palette, await search(e.detail.query), { query: e.detail.query });
+ *   });
+ * </script>
+ * ```
+ *
+ * @api
+ *
+ * ### Events (on the CommandSearch root, the element with `id`)
+ *
+ * | Event | Detail | Description |
+ * |-------|--------|-------------|
+ * | `command-search:search` | `{ query }` | A search ran (Enter or Search). In `remote` mode, answer with `setCommandSearchResults` |
+ * | `command-search:results` (in) | `{ groups?, query? }` | Results for `remote` mode; what `setCommandSearchResults` sends |
+ * | `command-search:select` | `{ value, label, href, query }` | An item was chosen. Cancelable: `preventDefault()` keeps the palette open and skips `href` |
+ * | `dialog:set` (in) / `dialog:change` | `{ open }` | Open or close it; see `Dialog` |
+ *
+ * ### JS (`@cl-light-ds/ui/lib/command-search`)
+ *
+ * `openCommandSearch(target?)`, `closeCommandSearch(target?)`, `setCommandSearchResults(target, groups?, { query })`.
+ */
+import { CornerDownLeft, Search } from "@lucide/astro";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+import Button from "../button/Button.astro";
+import Dialog from "../dialog/Dialog.astro";
+import DialogContent from "../dialog/DialogContent.astro";
+import DialogTitle from "../dialog/DialogTitle.astro";
+import DialogTrigger from "../dialog/DialogTrigger.astro";
+import InputGroup from "../input-group/InputGroup.astro";
+import InputGroupAddon from "../input-group/InputGroupAddon.astro";
+import InputGroupButton from "../input-group/InputGroupButton.astro";
+import InputGroupInput from "../input-group/InputGroupInput.astro";
+import Kbd from "../kbd/Kbd.astro";
+import Separator from "../separator/Separator.astro";
+import Spinner from "../spinner/Spinner.astro";
+import nothingMatches from "./nothing-matches.svg";
+
+interface Props extends HTMLAttributes<"div"> {
+  /**
+   * `filter`: the items you put in are filtered in the page (label and
+   * keywords). `remote`: you search on `command-search:search` and answer with
+   * `setCommandSearchResults`.
+   */
+  mode?: "filter" | "remote";
+  /** In `filter` mode, how long "Searching everything…" shows first (ms). */
+  delay?: number;
+  /** Open it with ⌘K (Mac) or Ctrl K. Only the first CommandSearch on a page takes the shortcut. */
+  shortcut?: boolean;
+  /** Render it open. */
+  open?: boolean;
+  /** Hide the trigger button (open it from your own control or the shortcut). */
+  hideTrigger?: boolean;
+  triggerLabel?: string;
+  /** Accessible name of the trigger. Defaults to `triggerLabel`. */
+  triggerAriaLabel?: string;
+  /** Visually hidden dialog title. */
+  title?: string;
+  placeholder?: string;
+  searchLabel?: string;
+  /** Shown before any search. */
+  hint?: string;
+  loadingText?: string;
+  emptyTitle?: string;
+  emptyDescription?: string;
+  /** Announced after a search; `{count}` is the number of matches (all of them, not only the rows a `limit` shows). */
+  resultsAnnouncement?: string;
+  /**
+   * Show at most this many matches in each group (D67: 5); the count beside
+   * the heading still says how many match. A group's own `limit` wins. No
+   * limit when unset or 0.
+   */
+  limit?: number;
+  /** Classes for the trigger button. */
+  triggerClass?: string;
+  /** Classes for the dialog panel. */
+  contentClass?: string;
+  class?: string;
+}
+
+const {
+  mode = "filter",
+  delay = 0,
+  shortcut = true,
+  open = false,
+  hideTrigger = false,
+  triggerLabel = "Search everything…",
+  triggerAriaLabel,
+  title = "Search",
+  placeholder = "Search…",
+  searchLabel = "Search",
+  hint = "Type a search term and press Enter, or click Search.",
+  loadingText = "Searching everything…",
+  emptyTitle = "Nothing matches",
+  emptyDescription = "Check the spelling, or try another word.",
+  resultsAnnouncement = "{count} results",
+  limit,
+  triggerClass = "",
+  contentClass = "",
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+
+/** Each state's part shows only in that state (`data-status` on the palette). */
+const show = {
+  idle: "hidden group-data-[status=idle]/command-search:flex",
+  loading: "hidden group-data-[status=loading]/command-search:flex",
+  results: "hidden group-data-[status=results]/command-search:flex",
+};
+---
+
+<Dialog
+  defaultOpen={open}
+  data-command-search
+  data-mode={mode}
+  data-delay={delay}
+  data-shortcut={shortcut ? "true" : "false"}
+  data-results-announcement={resultsAnnouncement}
+  data-limit={limit && limit > 0 ? limit : undefined}
+  data-loading-text={loadingText}
+  data-empty-title={emptyTitle}
+  class={className}
+  {...rest}
+>
+  {
+    !hideTrigger && (
+      <DialogTrigger asChild>
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          class={cn("text-muted-foreground w-56 justify-start", triggerClass)}
+          aria-label={triggerAriaLabel ?? triggerLabel}
+          aria-keyshortcuts={shortcut ? "Meta+K Control+K" : undefined}
+        >
+          <Search slot="lead-icon" />
+          <span class="flex-1 truncate text-start">{triggerLabel}</span>
+          {shortcut && <Kbd data-command-search-shortcut>⌘K</Kbd>}
+        </Button>
+      </DialogTrigger>
+    )
+  }
+
+  <DialogContent
+    showCloseButton={false}
+    class={cn("gap-0 p-0 sm:max-w-2xl [&>div]:gap-0 [&>div]:p-0", contentClass)}
+  >
+    <DialogTitle class="sr-only">{title}</DialogTitle>
+
+    <div
+      data-slot="command"
+      data-label={title}
+      data-status="idle"
+      data-should-filter={mode === "filter" ? "true" : "false"}
+      data-vim-bindings="false"
+      class="group/command-search flex min-w-0 flex-col"
+    >
+      <div class="p-2">
+        {/* D122 — searches on Enter or the Search button, not as you type. */}
+        <InputGroup
+          size="lg"
+          class="has-[[data-slot=command-input]:focus-visible]:border-ring has-[[data-slot=command-input]:focus-visible]:ring-ring/50 border-0 shadow-none has-[[data-slot=command-input]:focus-visible]:ring-3"
+        >
+          <InputGroupAddon align="inline-start">
+            <Search />
+          </InputGroupAddon>
+          <InputGroupInput
+            data-slot="command-input"
+            data-input-group-control
+            type="search"
+            placeholder={placeholder}
+            aria-label={placeholder}
+            autocomplete="off"
+            autofocus
+            enterkeyhint="search"
+          />
+          <InputGroupAddon align="inline-end">
+            <InputGroupButton size="sm" variant="secondary" data-command-search-submit>
+              {searchLabel}
+            </InputGroupButton>
+          </InputGroupAddon>
+        </InputGroup>
+      </div>
+
+      <Separator />
+
+      <div class="flex max-h-96 flex-col gap-3 overflow-y-auto p-2">
+        {/* D116 — before a search: a hint, no lists. */}
+        <p class={cn(show.idle, "text-muted-foreground px-6 py-8 text-center text-sm")}>
+          {hint}
+        </p>
+
+        {/* D142 — while a search runs. */}
+        <div class={cn(show.loading, "flex-col items-center gap-3 px-6 py-10 text-center")}>
+          <Spinner class="size-6" aria-hidden="true" role="presentation" />
+          <p class="text-muted-foreground text-sm">{loadingText}</p>
+        </div>
+
+        <div
+          data-slot="command-list"
+          aria-label={title}
+          class={cn(show.results, "flex-col gap-3")}
+        >
+          <slot />
+          {/* D187 — the designer's illustration (184×124). */}
+          <div
+            data-slot="command-empty"
+            hidden
+            class="flex flex-col items-center gap-2 px-6 py-10 text-center"
+          >
+            <img src={nothingMatches.src} alt="" width="184" height="124" class="-my-3" />
+            <p class="text-sm font-medium">{emptyTitle}</p>
+            <p class="text-muted-foreground text-xs">{emptyDescription}</p>
+          </div>
+        </div>
+      </div>
+
+      <p class="sr-only" role="status" aria-live="polite" data-command-search-status></p>
+
+      <Separator />
+
+      <div class="text-muted-foreground flex flex-wrap items-center gap-4 p-3 text-xs">
+        <slot name="footer">
+          <span class="flex items-center gap-1"><Kbd>↑</Kbd><Kbd>↓</Kbd> to move</span>
+          <span class="flex items-center gap-1">
+            <Kbd><CornerDownLeft class="size-3" /></Kbd> to open
+          </span>
+          <span class="flex items-center gap-1"><Kbd>esc</Kbd> to close</span>
+        </slot>
+      </div>
+    </div>
+  </DialogContent>
+</Dialog>
+
+<script>
+  import { createCommand } from "@data-slot/command";
+
+  import type { CommandSearchResultGroup } from "../../lib/command-search";
+  import {
+    commandSearchCountClasses,
+    commandSearchGroupClasses,
+    commandSearchHeadingClasses,
+    commandSearchItemClasses,
+    commandSearchLabelClasses,
+    commandSearchMetaClasses,
+  } from "./classes";
+
+  const isMac = /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent);
+  const wait = (ms: number) => new Promise((resolve) => window.setTimeout(resolve, ms));
+  const el = <K extends keyof HTMLElementTagNameMap>(tag: K, className: string, text?: string) => {
+    const node = document.createElement(tag);
+    node.className = className;
+    if (text !== undefined) node.textContent = text;
+    return node;
+  };
+
+  const openers: Array<() => void> = [];
+
+  document.querySelectorAll<HTMLElement>("[data-command-search]").forEach((root) => {
+    if (root.dataset.wired === "true") return;
+    root.dataset.wired = "true";
+
+    // Found now: the dialog's content is moved to <body> while open.
+    const command = root.querySelector<HTMLElement>('[data-slot="command"]');
+    const input = command?.querySelector<HTMLInputElement>('[data-slot="command-input"]');
+    const list = command?.querySelector<HTMLElement>('[data-slot="command-list"]');
+    const empty = list?.querySelector<HTMLElement>('[data-slot="command-empty"]');
+    const submit = command?.querySelector<HTMLElement>("[data-command-search-submit]");
+    const live = command?.querySelector<HTMLElement>("[data-command-search-status]");
+    if (!command || !input || !list) return;
+
+    const remote = root.dataset.mode === "remote";
+    const delay = Number(root.dataset.delay) || 0;
+    const defaultLimit = Number(root.dataset.limit) || 0;
+
+    for (const key of root.querySelectorAll<HTMLElement>("[data-command-search-shortcut]"))
+      key.textContent = isMac ? "⌘K" : "Ctrl K";
+
+    /** The last search that ran; typing alone changes nothing (D122). */
+    let applied = "";
+    let run = 0;
+    const setStatus = (status: "idle" | "loading" | "results") => {
+      command.dataset.status = status;
+    };
+    const announce = (text: string) => {
+      if (live) live.textContent = text;
+    };
+    const items = () => [...list.querySelectorAll<HTMLElement>('[data-slot="command-item"]')];
+    const shown = () =>
+      items().filter((item) => !item.hidden && !item.closest<HTMLElement>('[data-slot="command-group"]')?.hidden);
+
+    // Match the label and keywords anywhere, case-insensitively, and keep the
+    // order the items were given in (every match ranks the same).
+    let labels = new Map<string, string>();
+    const readLabels = () => {
+      labels = new Map(items().map((item) => [item.dataset.value ?? "", item.dataset.label ?? item.textContent ?? ""]));
+    };
+    const filter = (value: string, search: string, keywords?: string[]) => {
+      const q = search.trim().toLowerCase();
+      if (!q) return 1;
+      // Rows added since the search ran (the runtime re-filters them) aren't read yet.
+      if (!labels.has(value)) readLabels();
+      const text = (labels.get(value) ?? value).toLowerCase();
+      return text.includes(q) || (keywords ?? []).some((k) => k.toLowerCase().includes(q)) ? 1 : 0;
+    };
+
+    // Registered before the runtime binds, so it runs first and keeps the
+    // runtime from filtering as you type.
+    input.addEventListener("input", (event) => {
+      event.stopImmediatePropagation();
+      // Emptying the field goes back to the hint at once.
+      if (!input.value.trim() && applied) void search();
+    });
+    // Capture on the palette, also before the runtime's own keydown handler.
+    command.addEventListener(
+      "keydown",
+      (event) => {
+        if (event.key !== "Enter" || event.isComposing) return;
+        const fromInput = event.target === input;
+        // A new term runs the search; Enter again chooses the highlighted item
+        // (only once results are showing).
+        if (fromInput && input.value.trim() !== applied) {
+          event.preventDefault();
+          event.stopImmediatePropagation();
+          void search();
+        } else if (command.dataset.status !== "results") {
+          event.preventDefault();
+          event.stopImmediatePropagation();
+          if (fromInput) void search();
+        }
+      },
+      true,
+    );
+
+    const choose = (value: string) => {
+      const item = items().find((node) => node.dataset.value === value);
+      const detail = { value, label: item?.dataset.label ?? value, href: item?.dataset.href, query: applied };
+      const proceed = root.dispatchEvent(
+        new CustomEvent("command-search:select", { detail, cancelable: true }),
+      );
+      if (!proceed) return;
+      root.dispatchEvent(new CustomEvent("dialog:set", { detail: { open: false } }));
+      if (detail.href) window.location.assign(detail.href);
+    };
+
+    const controller = createCommand(command, {
+      label: command.dataset.label,
+      shouldFilter: !remote,
+      vimBindings: false,
+      filter,
+      onSelect: choose,
+    });
+
+    // Per-group limit (D67, C30). The runtime decides what matches and sets
+    // `hidden` on every item each time it filters, which happens again
+    // whenever the list's content changes (its own MutationObserver), so a
+    // cap applied once would be undone. Instead the cap is applied after
+    // every filter pass: an observer on `hidden` re-applies it (it only
+    // writes what differs, so it settles at once). Capped items are `hidden`,
+    // so arrow keys, hover and Enter skip them like any non-match.
+    const groups = () => [...list.querySelectorAll<HTMLElement>('[data-slot="command-group"]')];
+    const groupItems = (group: HTMLElement) =>
+      [...group.querySelectorAll<HTMLElement>('[data-slot="command-item"]')];
+    const limitOf = (group: HTMLElement) => {
+      const own = group.dataset.limit;
+      return own !== undefined && own !== "" ? Number(own) || 0 : defaultLimit;
+    };
+    const keywordsOf = (item: HTMLElement) =>
+      (item.dataset.keywords ?? "").split(/[,\n]/).map((k) => k.trim()).filter(Boolean);
+    /** Whether the runtime shows this item for the current search (same rule it uses). */
+    const matches = (item: HTMLElement) => {
+      if (remote || item.dataset.forceMount === "true") return true;
+      const query = controller.search;
+      if (!query.trim()) return true;
+      return filter(item.dataset.value ?? item.dataset.label ?? "", query, keywordsOf(item)) > 0;
+    };
+    const applyLimit = () => {
+      for (const group of groups()) {
+        const limit = limitOf(group);
+        let shownCount = 0;
+        for (const item of groupItems(group)) {
+          const over = item.hasAttribute("data-over-limit");
+          if (!matches(item)) {
+            if (over) item.removeAttribute("data-over-limit"); // the runtime hides it
+            continue;
+          }
+          shownCount += 1;
+          if (limit > 0 && shownCount > limit) {
+            if (!over) item.setAttribute("data-over-limit", "");
+            if (!item.hidden) item.hidden = true;
+          } else if (over) {
+            item.removeAttribute("data-over-limit");
+            item.hidden = false;
+          }
+        }
+      }
+      // Keep the highlight on something you can see.
+      const active = controller.value;
+      const visible = shown();
+      if (active !== null && !visible.some((item) => item.dataset.value === active))
+        controller.select(visible.find((item) => item.getAttribute("aria-disabled") !== "true")?.dataset.value ?? null);
+    };
+
+    const updateCounts = () => {
+      for (const group of groups()) {
+        const count = group.querySelector<HTMLElement>('[data-slot="command-search-count"]');
+        if (!count || count.dataset.fixed === "true") continue;
+        // Every match, including those past the limit.
+        const n = groupItems(group).filter(matches).length;
+        if (count.textContent !== String(n)) count.textContent = String(n);
+      }
+    };
+
+    new MutationObserver(() => {
+      if (command.dataset.status !== "results") return;
+      applyLimit();
+      updateCounts();
+    }).observe(list, { subtree: true, attributes: true, attributeFilter: ["hidden"] });
+
+    const showResults = () => {
+      applyLimit();
+      updateCounts();
+      const visible = shown();
+      if (empty) empty.hidden = visible.length > 0;
+      controller.select(visible.find((item) => item.getAttribute("aria-disabled") !== "true")?.dataset.value ?? null);
+      setStatus("results");
+      // Announce every match, not just the rows a per-group limit leaves showing:
+      // the sum of the group counts (which include a remote search's own counts).
+      const counted = groups().reduce((sum, group) => {
+        const label = group.querySelector('[data-slot="command-search-count"]')?.textContent;
+        const n = label ? Number(label) : NaN;
+        return sum + (Number.isFinite(n) ? n : groupItems(group).filter(matches).length);
+      }, 0);
+      const total = Math.max(counted, visible.length);
+      const template = root.dataset.resultsAnnouncement ?? "{count} results";
+      announce(visible.length ? template.replace("{count}", String(total)) : (root.dataset.emptyTitle ?? ""));
+    };
+
+    const clearRendered = () => {
+      for (const node of list.querySelectorAll("[data-command-search-rendered]")) node.remove();
+    };
+
+    const render = (groups: CommandSearchResultGroup[]) => {
+      clearRendered();
+      for (const group of groups) {
+        const wrap = el("div", commandSearchGroupClasses);
+        wrap.dataset.slot = "command-group";
+        wrap.dataset.commandSearchRendered = "";
+        if (group.limit !== undefined) wrap.dataset.limit = String(group.limit);
+        const heading = el("div", commandSearchHeadingClasses, group.heading);
+        heading.dataset.slot = "command-group-heading";
+        const count = el("span", commandSearchCountClasses, String(group.count ?? group.items.length));
+        count.dataset.slot = "command-search-count";
+        count.dataset.fixed = "true";
+        heading.append(count);
+        wrap.append(heading);
+        for (const result of group.items) {
+          const row = el("div", commandSearchItemClasses);
+          row.dataset.slot = "command-item";
+          row.dataset.value = result.value;
+          row.dataset.label = result.label;
+          if (result.href) row.dataset.href = result.href;
+          if (result.disabled) row.dataset.disabled = "true";
+          row.append(el("span", commandSearchLabelClasses, result.label));
+          if (result.description) row.append(el("span", commandSearchMetaClasses, result.description));
+          wrap.append(row);
+        }
+        list.insertBefore(wrap, empty ?? null);
+      }
+    };
+
+    /** D142 — a search shows "Searching everything…", then the results. */
+    const search = async () => {
+      const query = input.value.trim();
+      applied = query;
+      const id = ++run;
+      if (!query) {
+        controller.setSearch("");
+        if (remote) clearRendered();
+        setStatus("idle");
+        announce("");
+        return;
+      }
+      setStatus("loading");
+      announce(root.dataset.loadingText ?? "");
+      root.dispatchEvent(new CustomEvent("command-search:search", { detail: { query } }));
+      if (remote) return; // waits for command-search:results
+      if (delay) await wait(delay);
+      if (id !== run) return; // another search started since
+      readLabels();
+      controller.setSearch(input.value);
+      showResults();
+    };
+
+    root.addEventListener("command-search:results", (event) => {
+      if (!remote) return;
+      const { groups, query } = (event as CustomEvent<{ groups?: CommandSearchResultGroup[]; query?: string }>).detail ?? {};
+      if (query !== undefined && query !== applied) return; // stale
+      if (!applied) return;
+      if (groups) render(groups);
+      // Let the runtime pick up the new rows first.
+      requestAnimationFrame(showResults);
+    });
+
+    submit?.addEventListener("click", () => {
+      void search();
+      input.focus();
+    });
+
+    const reset = () => {
+      input.value = "";
+      applied = "";
+      run += 1;
+      controller.setSearch("");
+      if (remote) clearRendered();
+      setStatus("idle");
+      announce("");
+    };
+
+    root.addEventListener("dialog:change", (event) => {
+      if (!(event as CustomEvent<{ open: boolean }>).detail.open) return;
+      reset();
+      // After the dialog's own initial focus.
+      requestAnimationFrame(() => input.focus());
+      window.setTimeout(() => {
+        if (!command.contains(document.activeElement) || document.activeElement === command) input.focus();
+      }, 50);
+    });
+
+    if (root.dataset.shortcut === "true") {
+      openers.push(() => {
+        // Closed, the dialog content (and so the palette) is `hidden`.
+        if (!command.closest("[hidden]")) {
+          // Already open: back to the field.
+          input.focus();
+          input.select();
+          return;
+        }
+        root.dispatchEvent(new CustomEvent("dialog:set", { detail: { open: true } }));
+      });
+    }
+  });
+
+  // D63 — ⌘K on a Mac, Ctrl K elsewhere, opens the first palette that takes the shortcut.
+  if (openers.length && !document.documentElement.dataset.commandSearchShortcut) {
+    document.documentElement.dataset.commandSearchShortcut = "true";
+    document.addEventListener("keydown", (event) => {
+      const combo = isMac ? event.metaKey : event.ctrlKey;
+      if (!combo || event.altKey || event.shiftKey || event.key.toLowerCase() !== "k") return;
+      event.preventDefault();
+      openers[0]?.();
+    });
+  }
+</script>

package/src/components/command-search/CommandSearchGroup.astro

@@ -0,0 +1,43 @@
+---
+/**
+ * A group of results in a `CommandSearch`: a small caps heading with the
+ * number of matches beside it, then its `CommandSearchItem`s. Hidden while
+ * none of its items match. With `limit`, only the first matches show; the
+ * count beside the heading still counts them all.
+ */
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+import {
+  commandSearchCountClasses,
+  commandSearchGroupClasses,
+  commandSearchHeadingClasses,
+} from "./classes";
+
+interface Props extends HTMLAttributes<"div"> {
+  heading: string;
+  /** Show how many items match beside the heading (D67). */
+  showCount?: boolean;
+  /**
+   * Show at most this many matches (D67: 5); the count still says how many
+   * match. Overrides `CommandSearch`'s `limit`; 0 for no limit.
+   */
+  limit?: number;
+  class?: string;
+}
+
+const { heading, showCount = true, limit, class: className = "", ...rest } = Astro.props as Props;
+---
+
+<div
+  data-slot="command-group"
+  data-limit={limit !== undefined ? limit : undefined}
+  class={cn(commandSearchGroupClasses, className)}
+  {...rest}
+>
+  <div data-slot="command-group-heading" class={commandSearchHeadingClasses}>
+    {heading}
+    {showCount && <span data-slot="command-search-count" class={commandSearchCountClasses}></span>}
+  </div>
+  <slot />
+</div>