@charcuterie/ui 4.25.0 → 4.26.1

package/src/CommandPalette/commandPalette.storyHelpers.tsx

@@ -0,0 +1,248 @@
+import type { ReactNode } from "react"
+
+import {
+  ImageIcon,
+  InboxIcon,
+  LinkIcon,
+  MonitorIcon,
+  PlayIcon,
+  SearchIcon,
+  SettingsIcon,
+  SunIcon,
+} from "../icons.storyHelpers.tsx"
+import type {
+  CommandPaletteGroup,
+  CommandPaletteItem,
+  CommandPalettePrefix,
+} from "./commandPaletteSections.ts"
+
+/**
+ * A generic household launcher: apps, the members of two folders,
+ * and a few bookmarks. Every host is `example.com` — this repo is
+ * public, and the fixture stands in for a real start page. Each opens
+ * in a new tab, so following one from Storybook does not replace the
+ * story.
+ */
+export const LAUNCHER_ITEMS: readonly CommandPaletteItem[] =
+  [
+    {
+      description: "Home",
+      group: "Apps",
+      hint: "App",
+      href: "https://automation.example.com/",
+      icon: <SettingsIcon />,
+      key: "home-automation",
+      keywords: ["lights", "thermostat"],
+      target: "_blank",
+      title: "Home Automation",
+      weight: 40,
+    },
+    {
+      description: "Home Theater",
+      group: "Apps",
+      hint: "App",
+      href: "https://media.example.com/",
+      icon: <PlayIcon />,
+      key: "media-server",
+      keywords: ["movies", "shows"],
+      target: "_blank",
+      title: "Media Server",
+      weight: 25,
+    },
+    {
+      description: "Household",
+      group: "Apps",
+      hint: "App",
+      href: "https://photos.example.com/",
+      icon: <ImageIcon />,
+      key: "photo-library",
+      target: "_blank",
+      title: "Photo Library",
+      weight: 12,
+    },
+    {
+      description: "Household",
+      group: "Apps",
+      hint: "App",
+      href: "https://tasks.example.com/",
+      icon: <InboxIcon />,
+      key: "task-board",
+      keywords: ["todo", "chores"],
+      target: "_blank",
+      title: "Task Board",
+      weight: 18,
+    },
+    {
+      description: "Network & Admin",
+      group: "Apps",
+      hint: "App",
+      href: "https://proxy.example.com/",
+      icon: <SettingsIcon />,
+      key: "reverse-proxy-manager",
+      target: "_blank",
+      title: "Reverse Proxy Manager",
+      weight: 3,
+    },
+    {
+      description: "Network & Admin",
+      group: "Apps",
+      hint: "App",
+      href: "https://storage.example.com/",
+      icon: <MonitorIcon />,
+      key: "storage-server",
+      keywords: ["nas", "pools"],
+      target: "_blank",
+      title: "Storage Server",
+      weight: 9,
+    },
+    {
+      description: "Remotes",
+      group: "Apps",
+      hint: "App",
+      href: "https://remote-living.example.com/",
+      icon: <MonitorIcon />,
+      key: "living-room-remote",
+      target: "_blank",
+      title: "Living Room Remote",
+    },
+    {
+      description: "Remotes",
+      group: "Apps",
+      hint: "App",
+      href: "https://remote-bedroom.example.com/",
+      icon: <MonitorIcon />,
+      key: "bedroom-remote",
+      target: "_blank",
+      title: "Bedroom Remote",
+    },
+    {
+      description: "Speed Tests",
+      group: "Apps",
+      hint: "App",
+      href: "https://speed.example.com/",
+      icon: <MonitorIcon />,
+      key: "speed-test",
+      target: "_blank",
+      title: "Speed Test",
+    },
+    {
+      description: "Bookmarks",
+      group: "Bookmarks",
+      hint: "Bookmark",
+      href: "https://weather.example.com/",
+      icon: <SunIcon />,
+      key: "weather-forecast",
+      keywords: ["rain"],
+      target: "_blank",
+      title: "Weather Forecast",
+    },
+    {
+      description: "Bookmarks",
+      group: "Bookmarks",
+      hint: "Bookmark",
+      href: "https://parcels.example.com/",
+      icon: <LinkIcon />,
+      key: "package-tracking",
+      keywords: ["shipping", "parcels"],
+      target: "_blank",
+      title: "Package Tracking",
+    },
+    {
+      description: "Bookmarks",
+      group: "Bookmarks",
+      hint: "Bookmark",
+      href: "https://recipes.example.com/",
+      icon: <LinkIcon />,
+      key: "recipe-box",
+      keywords: ["cooking", "meals"],
+      target: "_blank",
+      title: "Recipe Box",
+    },
+  ]
+
+const byKey = (key: string): CommandPaletteItem => {
+  const item = LAUNCHER_ITEMS.find(
+    (candidate) => candidate.key === key,
+  )
+
+  if (item === undefined) {
+    throw new Error(`No fixture item "${key}"`)
+  }
+
+  return item
+}
+
+export const LAUNCHER_SUGGESTIONS: readonly CommandPaletteGroup[] =
+  [
+    {
+      items: [
+        byKey("home-automation"),
+        byKey("media-server"),
+        byKey("task-board"),
+      ],
+      key: "pinned",
+      label: "Pinned",
+    },
+    {
+      items: [
+        {
+          ...byKey("weather-forecast"),
+          hint: "2 hours ago",
+        },
+        { ...byKey("storage-server"), hint: "Yesterday" },
+        { ...byKey("photo-library"), hint: "3 days ago" },
+      ],
+      key: "recent",
+      label: "Recently opened",
+    },
+  ]
+
+const searchHref =
+  (host: string) =>
+  (query: string): string =>
+    `https://${host}.example.com/search?q=${encodeURIComponent(query)}`
+
+export const LAUNCHER_PREFIXES: readonly CommandPalettePrefix[] =
+  [
+    {
+      getHref: searchHref("auction"),
+      icon: <SearchIcon />,
+      label: "Auction Site",
+      prefix: "au",
+    },
+    {
+      getHref: searchHref("shop"),
+      icon: <SearchIcon />,
+      label: "Shopping Site",
+      prefix: "sh",
+    },
+    {
+      getHref: searchHref("video"),
+      icon: <SearchIcon />,
+      label: "Video Site",
+      prefix: "vi",
+    },
+  ]
+
+export const getWebSearchItem = (
+  query: string,
+): CommandPaletteItem => ({
+  group: "The web",
+  hint: "Search",
+  href: searchHref("web")(query),
+  icon: <SearchIcon />,
+  key: "web-search",
+  target: "_blank",
+  title: `Search the web for “${query}”`,
+})
+
+/** The bordered box an inline panel sits in on a board, standing in for the dialog's own. */
+export const PanelFrame = ({
+  children,
+}: {
+  children: ReactNode
+}): ReactNode => (
+  <div className="flex max-h-[28rem] w-full flex-col overflow-hidden rounded-lg border border-border-default bg-surface-overlay text-content-primary shadow-high">
+    {children}
+  </div>
+)

package/src/CommandPalette/commandPaletteSections.test.ts

@@ -0,0 +1,156 @@
+import { expect, test } from "vitest"
+
+import {
+  buildCommandPaletteSections,
+  type CommandPaletteItem,
+  type CommandPaletteSectionsOptions,
+} from "./commandPaletteSections.ts"
+
+const ITEMS: readonly CommandPaletteItem[] = [
+  { group: "Apps", key: "photos", title: "Photo Server" },
+  {
+    group: "Apps",
+    key: "media",
+    title: "Media Server",
+    weight: 5,
+  },
+  {
+    group: "Bookmarks",
+    key: "servers",
+    title: "Server Room Camera",
+  },
+  { group: "Apps", key: "spare", title: "Spare Server" },
+  { key: "loose", title: "Serving Sizes" },
+]
+
+const build = (
+  overrides: Partial<CommandPaletteSectionsOptions>,
+) =>
+  buildCommandPaletteSections({
+    formatPrefixTitle: (label, query) =>
+      `${label}: ${query}`,
+    items: ITEMS,
+    prefixGroupLabel: "Search a site",
+    prefixes: [
+      {
+        getHref: (query) =>
+          `https://auction.example.com/?q=${query}`,
+        label: "Auction Site",
+        prefix: "au",
+      },
+    ],
+    query: "",
+    suggestions: [],
+    ungroupedLabel: "Results",
+    ...overrides,
+  })
+
+const summarize = (
+  sections: ReturnType<typeof buildCommandPaletteSections>,
+) =>
+  sections.map(({ label, rows }) => [
+    label,
+    rows.map(({ item }) => item.title),
+  ])
+
+test("nothing typed lists the suggestions, skipping an empty group", () => {
+  const sections = build({
+    query: "   ",
+    suggestions: [
+      {
+        items: [ITEMS[0] as CommandPaletteItem],
+        key: "pinned",
+        label: "Pinned",
+      },
+      {
+        items: [],
+        key: "recent",
+        label: "Recently opened",
+      },
+    ],
+  })
+
+  expect(summarize(sections)).toStrictEqual([
+    ["Pinned", ["Photo Server"]],
+  ])
+})
+
+test("groups are ordered by their best member, so the first row is the best match", () => {
+  // `Server Room Camera` starts with the query, so its group leads even
+  // though `Apps` comes first in the list.
+  expect(summarize(build({ query: "ser" }))).toStrictEqual([
+    ["Bookmarks", ["Server Room Camera"]],
+    ["Results", ["Serving Sizes"]],
+    [
+      "Apps",
+      ["Media Server", "Photo Server", "Spare Server"],
+    ],
+  ])
+})
+
+test("maxResultsPerGroup caps each heading separately", () => {
+  expect(
+    summarize(
+      build({ maxResultsPerGroup: 1, query: "server" }),
+    ),
+  ).toStrictEqual([
+    ["Bookmarks", ["Server Room Camera"]],
+    ["Apps", ["Media Server"]],
+  ])
+})
+
+test("the fallback row comes last, under its own group, with the trimmed query", () => {
+  const sections = build({
+    getFallbackItem: (query) => ({
+      group: "The web",
+      key: "web",
+      title: `Search the web for ${query}`,
+    }),
+    query: "  zebra  ",
+  })
+
+  expect(summarize(sections)).toStrictEqual([
+    ["The web", ["Search the web for zebra"]],
+  ])
+})
+
+test("a prefix command is the only row, and its link and onSelect get the rest of the query", () => {
+  const chosen: string[] = []
+
+  const sections = build({
+    getFallbackItem: () => ({
+      key: "web",
+      title: "never shown",
+    }),
+    prefixes: [
+      {
+        getHref: (query) =>
+          `https://auction.example.com/?q=${query}`,
+        label: "Auction Site",
+        onSelect: (query) => chosen.push(query),
+        prefix: "au",
+      },
+    ],
+    query: "AU lego set",
+  })
+
+  expect(summarize(sections)).toStrictEqual([
+    ["Search a site", ["Auction Site: lego set"]],
+  ])
+
+  const item = sections[0]?.rows[0]?.item
+
+  expect(item?.href).toBe(
+    "https://auction.example.com/?q=lego set",
+  )
+
+  item?.onSelect?.()
+
+  expect(chosen).toStrictEqual(["lego set"])
+})
+
+test("a prefix with nothing after it is searched as text", () => {
+  expect(summarize(build({ query: "au " }))).toStrictEqual(
+    [],
+  )
+})

package/src/CommandPalette/commandPaletteSections.ts

@@ -0,0 +1,219 @@
+import {
+  parsePrefixCommand,
+  rankWordPrefixMatches,
+  type TextMatchRange,
+} from "@charcuterie/logic"
+import type { ReactNode } from "react"
+
+/**
+ * One thing the palette can open or run.
+ *
+ * A folder's members are items like any other: the caller flattens
+ * them into `items`, and puts the folder's name in `description` so a
+ * hit inside a folder still says where it lives.
+ */
+export type CommandPaletteItem = {
+  /** Secondary text after the title — a folder, a section, a host. Matched, never highlighted. */
+  description?: string
+  /** Shown under this heading when the palette lists matches. Items without one share `ungroupedLabel`. */
+  group?: string
+  /** Opens as a link: a real `<a href>`, routed through `RouterLinkProvider`. */
+  href?: string
+  /** The app's own glyph or image. Decorative; the title is the name. */
+  icon?: ReactNode
+  /** Matched as extra words and never shown: an old name, an abbreviation, a product the app hosts. */
+  keywords?: readonly string[]
+  /** Unique within the list it is in. */
+  key: string
+  /** Trailing text at the end of the row: a kind ("Bookmark") or a status. */
+  hint?: ReactNode
+  /** Runs on choice. With an `href` too, it runs as well as the navigation — a place to record a visit. */
+  onSelect?: () => void
+  /** Passed to the link. `_blank` opens a new tab on a plain Enter or click. */
+  target?: string
+  /** What is typed for and highlighted. */
+  title: string
+  /** Breaks a tie inside a match tier, higher first: an open count, say. */
+  weight?: number
+}
+
+/** A heading and its items, shown before anything is typed. */
+export type CommandPaletteGroup = {
+  items: readonly CommandPaletteItem[]
+  key: string
+  label: string
+}
+
+/**
+ * A short prefix that sends the rest of the query to one target:
+ * `{ prefix: "au", label: "Auction Site", getHref: (query) => … }`
+ * turns `au lego` into one row that searches that site.
+ */
+export type CommandPalettePrefix = {
+  /** The link the row opens, given what follows the prefix. */
+  getHref?: (query: string) => string
+  icon?: ReactNode
+  /** The target's name, in the row's title and in the footer. */
+  label: string
+  /** Runs instead of, or as well as, the link. */
+  onSelect?: (query: string) => void
+  /** What is typed before the space: `au`. Matched without case. */
+  prefix: string
+}
+
+export type CommandPaletteRow = {
+  item: CommandPaletteItem
+  /** Where the query matched the title; empty for a suggestion. */
+  titleRanges: readonly TextMatchRange[]
+}
+
+export type CommandPaletteSection = {
+  key: string
+  label: string
+  rows: readonly CommandPaletteRow[]
+}
+
+export type CommandPaletteSectionsOptions = {
+  formatPrefixTitle: (
+    label: string,
+    query: string,
+  ) => string
+  getFallbackItem?: (
+    query: string,
+  ) => CommandPaletteItem | null | undefined
+  items: readonly CommandPaletteItem[]
+  maxResultsPerGroup?: number
+  prefixGroupLabel: string
+  prefixes: readonly CommandPalettePrefix[]
+  query: string
+  suggestions: readonly CommandPaletteGroup[]
+  ungroupedLabel: string
+}
+
+/**
+ * What the palette lists for a query, as headed sections in order.
+ *
+ * Three cases, decided in this order:
+ *
+ * 1. **A prefix command** (`au lego`) lists one row, for that target.
+ * 2. **Nothing typed** lists the caller's `suggestions` — the shape
+ *    the palette exists for: something to choose the moment it opens.
+ * 3. **Anything else** lists the word-prefix matches from `items`,
+ *    under each item's `group`, and then the caller's fallback row.
+ *
+ * Matched groups are ordered by their best member, so the first row
+ * — the one Enter opens — is always the best match, whichever group
+ * it belongs to.
+ */
+export const buildCommandPaletteSections = ({
+  formatPrefixTitle,
+  getFallbackItem,
+  items,
+  maxResultsPerGroup,
+  prefixGroupLabel,
+  prefixes,
+  query,
+  suggestions,
+  ungroupedLabel,
+}: CommandPaletteSectionsOptions): CommandPaletteSection[] => {
+  const command = parsePrefixCommand(query, prefixes)
+
+  if (command !== null) {
+    const { query: commandQuery, target } = command
+
+    return [
+      {
+        key: "prefix",
+        label: prefixGroupLabel,
+        rows: [
+          {
+            item: {
+              href: target.getHref?.(commandQuery),
+              icon: target.icon,
+              key: `prefix-${target.prefix}`,
+              onSelect:
+                target.onSelect === undefined
+                  ? undefined
+                  : () => target.onSelect?.(commandQuery),
+              title: formatPrefixTitle(
+                target.label,
+                commandQuery,
+              ),
+            },
+            titleRanges: [],
+          },
+        ],
+      },
+    ]
+  }
+
+  const trimmedQuery = query.trim()
+
+  if (trimmedQuery.length === 0) {
+    return suggestions
+      .filter((group) => group.items.length > 0)
+      .map((group) => ({
+        key: `suggestion-${group.key}`,
+        label: group.label,
+        rows: group.items.map((item) => ({
+          item,
+          titleRanges: [],
+        })),
+      }))
+  }
+
+  const ranked = rankWordPrefixMatches(
+    items,
+    trimmedQuery,
+    (item) => ({
+      extra: [
+        ...(item.description === undefined
+          ? []
+          : [item.description]),
+        ...(item.keywords ?? []),
+      ],
+      title: item.title,
+      weight: item.weight,
+    }),
+  )
+
+  const sectionsByLabel = new Map<
+    string,
+    CommandPaletteRow[]
+  >()
+
+  for (const { item, match } of ranked) {
+    const label = item.group ?? ungroupedLabel
+    const rows = sectionsByLabel.get(label) ?? []
+
+    if (
+      maxResultsPerGroup === undefined ||
+      rows.length < maxResultsPerGroup
+    ) {
+      rows.push({ item, titleRanges: match.titleRanges })
+    }
+
+    sectionsByLabel.set(label, rows)
+  }
+
+  const sections: CommandPaletteSection[] = [
+    ...sectionsByLabel,
+  ].map(([label, rows]) => ({
+    key: `group-${label}`,
+    label,
+    rows,
+  }))
+
+  const fallbackItem = getFallbackItem?.(trimmedQuery)
+
+  return fallbackItem == null
+    ? sections
+    : [
+        ...sections,
+        {
+          key: "fallback",
+          label: fallbackItem.group ?? ungroupedLabel,
+          rows: [{ item: fallbackItem, titleRanges: [] }],
+        },
+      ]
+}

package/src/CommandPalette/useCommandPalette.ts

@@ -0,0 +1,75 @@
+import { useVisibility } from "@charcuterie/logic"
+import { useCallback, useState } from "react"
+
+import {
+  type CommandPaletteHotkeysOptions,
+  useCommandPaletteHotkeys,
+} from "./useCommandPaletteHotkeys.ts"
+
+export type UseCommandPaletteOptions = Pick<
+  CommandPaletteHotkeysOptions,
+  "isOpenedByTyping"
+> & {
+  /** Register the global keys (`useCommandPaletteHotkeys`). Default `true`. */
+  hasHotkeys?: boolean
+}
+
+export type UseCommandPaletteResult = {
+  close: () => void
+  isVisible: boolean
+  /** Open it, optionally with text already in the field. */
+  open: (initialQuery?: string) => void
+  /** Spread onto `CommandPalette`. */
+  paletteProps: {
+    defaultQuery: string
+    isVisible: boolean
+    onClose: () => void
+  }
+}
+
+/**
+ * The open state for one `CommandPalette`, and its global keys.
+ *
+ * ```tsx
+ * const palette = useCommandPalette()
+ *
+ * <Button onClick={() => palette.open()}>Search</Button>
+ * <CommandPalette {...palette.paletteProps} items={items} />
+ * ```
+ *
+ * The keys are off while it is open, so a second `Ctrl K` does not
+ * reset what has been typed.
+ */
+export const useCommandPalette = ({
+  hasHotkeys = true,
+  isOpenedByTyping,
+}: UseCommandPaletteOptions = {}): UseCommandPaletteResult => {
+  const { hide, isVisible, show } = useVisibility()
+
+  const [initialQuery, setInitialQuery] = useState("")
+
+  const open = useCallback(
+    (nextInitialQuery = "") => {
+      setInitialQuery(nextInitialQuery)
+      show()
+    },
+    [show],
+  )
+
+  useCommandPaletteHotkeys({
+    isEnabled: hasHotkeys && !isVisible,
+    isOpenedByTyping,
+    onOpen: open,
+  })
+
+  return {
+    close: hide,
+    isVisible,
+    open,
+    paletteProps: {
+      defaultQuery: initialQuery,
+      isVisible,
+      onClose: hide,
+    },
+  }
+}