@domicile-desktop/component-library 0.0.0-alpha-32449d3c53bb → 0.0.0-alpha-a2def76ec0b8

package/package.json

@@ -2,8 +2,8 @@
   "dependencies": {
     "@base-ui/react": "^1.8.0",
     "@cprussin/option-result": "^2.0.1",
-    "@domicile-desktop/sdk": "0.0.0-alpha-32449d3c53bb",
-    "@domicile-desktop/system-apps": "0.0.0-alpha-32449d3c53bb",
+    "@domicile-desktop/sdk": "0.0.0-alpha-a2def76ec0b8",
+    "@domicile-desktop/system-apps": "0.0.0-alpha-a2def76ec0b8",
     "@pandacss/dev": "^1.12.1",
     "@phosphor-icons/react": "^2.1.10"
   },
@@ -87,6 +87,7 @@
     "./ListRow": "./src/ListRow/ListRow.tsx",
     "./Loading": "./src/Loading/Loading.tsx",
     "./list-walk": "./src/list-walk.ts",
+    "./Marked": "./src/ResultList/Marked.tsx",
     "./ModalDialog": "./src/ModalDialog/ModalDialog.tsx",
     "./media-theme-source": "./src/ThemeSwitch/media-theme-source.ts",
     "./Notice": "./src/Notice/Notice.tsx",
@@ -102,6 +103,8 @@
     "./pandacss-preset": "./src/pandacss-preset.ts",
     "./QuickTile": "./src/QuickTile/QuickTile.tsx",
     "./QuickToggle": "./src/QuickToggle/QuickToggle.tsx",
+    "./ResultList": "./src/ResultList/ResultList.tsx",
+    "./RowTile": "./src/ResultList/RowTile.tsx",
     "./Screen": "./src/Screen/Screen.tsx",
     "./Select": "./src/Select/Select.tsx",
     "./SlideOver": "./src/SlideOver/SlideOver.tsx",
@@ -159,5 +162,5 @@
     "test:unit": "bun test"
   },
   "type": "module",
-  "version": "0.0.0-alpha-32449d3c53bb"
+  "version": "0.0.0-alpha-a2def76ec0b8"
 }

package/src/ResultList/Marked.tsx

@@ -0,0 +1,38 @@
+import { Fragment } from "react";
+
+import { css } from "../../styled-system/css";
+import { marked } from "./match-runs";
+
+type Props = {
+  query: string;
+  text: string;
+};
+
+/**
+ * A row's text with what `query` matched in bold, so users see why it
+ * matched. Uses `mark` for its semantics, which screen readers understand.
+ */
+export const Marked = ({ query, text }: Props) => (
+  <>
+    {marked(text, query).map((run, at) =>
+      run.matched ? (
+        // Runs have no identity beyond their position.
+        <mark className={markStyles} key={at}>
+          {run.text}
+        </mark>
+      ) : (
+        <Fragment key={at}>{run.text}</Fragment>
+      ),
+    )}
+  </>
+);
+
+// In the row's own color instead of `mark`'s yellow. Emboldened with a
+// stroke rather than font weight, which would widen letters and shift the
+// row on every key. `paint-order: stroke` keeps letter holes open.
+const markStyles = css({
+  backgroundColor: "transparent",
+  color: "inherit",
+  paintOrder: "stroke",
+  WebkitTextStroke: "{borderWidths.fauxBold} currentColor",
+});

package/src/ResultList/ResultList.tsx

@@ -0,0 +1,100 @@
+import type { ReactNode } from "react";
+
+import { flex, hstack } from "../../styled-system/patterns";
+import { keepInView } from "../list-walk";
+
+type Props<Item> = {
+  /** Draws an item's row, such as a `RowTile` and its name. */
+  children: (item: Item) => ReactNode;
+  /** The row lit by the keyboard or the pointer, if any. */
+  highlighted: number | undefined;
+  /** The listbox's ID, which the combobox that drives it names. */
+  id: string;
+  items: readonly Item[];
+  keyOf: (item: Item) => string;
+  /** Names the list, when no combobox names it. */
+  label?: string | undefined;
+  onChoose: (item: Item) => void;
+  /** The pointer moved over the row at `at`. */
+  onHighlight: (at: number) => void;
+};
+
+/**
+ * The rows under a search box, as in the launcher: one highlight, which the
+ * keyboard and the pointer both move, and a click to choose.
+ *
+ * A listbox driven by `aria-activedescendant`, so focus stays in the box.
+ * The box moves the highlight on keys; see `list-walk`. Name the highlighted
+ * row with {@link resultId}.
+ */
+export const ResultList = <Item,>({
+  children,
+  highlighted,
+  id,
+  items,
+  keyOf,
+  label,
+  onChoose,
+  onHighlight,
+}: Props<Item>) => (
+  // Divs rather than `ul`/`li`, because lint rejects interactive roles on
+  // list elements.
+  <div aria-label={label} className={listStyles} id={id} role="listbox">
+    {items.map((item, at) => (
+      // biome-ignore lint/a11y/useKeyWithClickEvents: the combobox that names this list owns the keyboard for these rows, which is the whole point of `aria-activedescendant`
+      <div
+        aria-selected={at === highlighted}
+        className={rowStyles}
+        data-highlighted={at === highlighted ? "" : undefined}
+        id={resultId(id, at)}
+        key={keyOf(item)}
+        onClick={() => {
+          onChoose(item);
+        }}
+        // Keeps focus in the box.
+        onMouseDown={(event) => {
+          event.preventDefault();
+        }}
+        // Pointer move rather than enter, so rows scrolling under a still
+        // pointer don't take the highlight.
+        onPointerMove={() => {
+          onHighlight(at);
+        }}
+        // A stable function on the highlighted row only, so React calls it
+        // only when the highlight moves.
+        ref={at === highlighted ? keepInView : undefined}
+        role="option"
+        // Out of the tab order; focus stays in the box.
+        tabIndex={-1}
+      >
+        {children(item)}
+      </div>
+    ))}
+  </div>
+);
+
+const listStyles = flex({
+  direction: "column",
+  gap: 0.5,
+});
+
+const rowStyles = hstack({
+  // A neutral wash, so color is left for what needs attention. There is no
+  // separate hover style; the pointer moves the highlight.
+  "&[data-highlighted]": {
+    backgroundColor:
+      "color-mix(in oklab, {colors.foreground} 10%, transparent)",
+  },
+  borderRadius: "md",
+  color: "foreground",
+  cursor: "pointer",
+  fontSize: "sm",
+  gap: 2.5,
+  paddingBlock: 1.5,
+  paddingInline: 2,
+  transition: "background-color {durations.fast} {easings.out}",
+});
+
+/** The row at `at`'s element ID, for `aria-activedescendant`. */
+export const resultId = (listId: string, at: number): string =>
+  `${listId}-${at.toString()}`;

package/src/ResultList/RowTile.tsx

@@ -0,0 +1,69 @@
+import type { Icon } from "@phosphor-icons/react";
+
+import { css, cva } from "../../styled-system/css";
+
+/** The glyph's size in its tile. */
+const ICON_SIZE = 16;
+
+type Props = {
+  icon: Icon;
+};
+
+/**
+ * A row's glyph in a framed tile, at the start of a {@link ResultList} row.
+ * The tile aligns every row's text and lights with the row.
+ *
+ * Draws the outline and fill weights and shows one, since CSS can't change a
+ * Phosphor glyph's weight. Same approach as `_control/PrefixIconStack`.
+ */
+export const RowTile = ({ icon: Glyph }: Props) => (
+  <span aria-hidden className={tileStyles} data-row-tile="">
+    <span className={glyphStyles({ weight: "regular" })}>
+      <Glyph size={ICON_SIZE} />
+    </span>
+    <span className={glyphStyles({ weight: "fill" })}>
+      <Glyph size={ICON_SIZE} weight="fill" />
+    </span>
+  </span>
+);
+
+const tileStyles = css({
+  // Lit with a filled glyph on the highlighted row, since an outline glyph
+  // loses contrast on the lighter background.
+  "[data-highlighted] > &": {
+    backgroundColor:
+      "color-mix(in oklab, {colors.foreground} 10%, transparent)",
+    borderColor: "color-mix(in oklab, {colors.foreground} 20%, transparent)",
+    color: "foreground",
+  },
+  blockSize: 7,
+  border: "1px solid color-mix(in oklab, {colors.foreground} 8%, transparent)",
+  borderRadius: "sm",
+  color: "muted",
+  display: "grid",
+  flexShrink: 0,
+  inlineSize: 7,
+  placeItems: "center",
+  transition:
+    "background-color {durations.fast} {easings.out}, border-color {durations.fast} {easings.out}, color {durations.fast} {easings.out}",
+});
+
+// Both weights share one grid cell, so swapping doesn't shift layout.
+const glyphStyles = cva({
+  base: {
+    display: "inline-flex",
+    gridArea: "1 / 1",
+    transition: "opacity {durations.fast} {easings.out}",
+  },
+  variants: {
+    weight: {
+      fill: {
+        "[data-highlighted] > [data-row-tile] > &": { opacity: 1 },
+        opacity: 0,
+      },
+      regular: {
+        "[data-highlighted] > [data-row-tile] > &": { opacity: 0 },
+      },
+    },
+  },
+});

package/src/ResultList/match-runs.ts

@@ -0,0 +1,69 @@
+// Marks the letters of a row that match the query, so users see why it matched.
+// Matches as the launcher's file search does (`domicile_host::file_search`):
+// every query word, ignoring case. Every occurrence of any word is marked.
+
+/** A run of a row's text, and whether it matched the query. */
+export type Mark = {
+  matched: boolean;
+  text: string;
+};
+
+/** Split `text` into matched and unmatched runs for `query`. */
+export const marked = (text: string, query: string): readonly Mark[] => {
+  const lowered = text.toLowerCase();
+  const words = query
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((word) => word !== "");
+  const runs = merged(
+    words
+      .flatMap((word) => occurrences(lowered, word))
+      .sort((one, other) => one.at - other.at),
+  );
+  return cut(text, runs);
+};
+
+/** A matched span of a row's text. */
+type Run = { at: number; to: number };
+
+const occurrences = (lowered: string, word: string): readonly Run[] => {
+  const found: Run[] = [];
+  // `indexOf` rather than a regexp, so `a.b` and `c++` match literally
+  // without escaping.
+  for (
+    let at = lowered.indexOf(word);
+    at !== -1;
+    at = lowered.indexOf(word, at + 1)
+  ) {
+    found.push({ at, to: at + word.length });
+  }
+  return found;
+};
+
+/**
+ * Merge touching or overlapping runs.
+ *
+ * Words can overlap (`note notes`), and unmerged runs would show a seam.
+ */
+const merged = (runs: readonly Run[]): readonly Run[] =>
+  runs.reduce<Run[]>((folded, run) => {
+    const last = folded.at(-1);
+    if (last !== undefined && run.at <= last.to) {
+      return [
+        ...folded.slice(0, -1),
+        { at: last.at, to: Math.max(last.to, run.to) },
+      ];
+    } else {
+      return [...folded, run];
+    }
+  }, []);
+
+/** Split `text` at the edges of `runs` into marked pieces. */
+const cut = (text: string, runs: readonly Run[]): readonly Mark[] => {
+  const pieces = runs.flatMap((run, index) => [
+    { matched: false, text: text.slice(runs[index - 1]?.to ?? 0, run.at) },
+    { matched: true, text: text.slice(run.at, run.to) },
+  ]);
+  const rest = { matched: false, text: text.slice(runs.at(-1)?.to ?? 0) };
+  return [...pieces, rest].filter((piece) => piece.text !== "");
+};