@gusnips/react 0.1.0

package/src/ui/combobox.tsx

@@ -0,0 +1,242 @@
+import { Combobox as Primitive } from "@base-ui/react/combobox";
+import { useMemo, useState, type ReactNode } from "react";
+import { mergeClassName, type StateClassName } from "./class-name.ts";
+import { ChevronGlyph, CloseGlyph } from "./glyphs.tsx";
+
+// The parts, for a combobox this wrapper's shape cannot express — multi-select with chips,
+// groups, a virtualised list.
+export const ComboboxRoot = Primitive.Root;
+export const ComboboxInput = Primitive.Input;
+export const ComboboxInputGroup = Primitive.InputGroup;
+export const ComboboxTrigger = Primitive.Trigger;
+export const ComboboxClear = Primitive.Clear;
+export const ComboboxPortal = Primitive.Portal;
+export const ComboboxPositioner = Primitive.Positioner;
+export const ComboboxPopup = Primitive.Popup;
+export const ComboboxList = Primitive.List;
+export const ComboboxItem = Primitive.Item;
+export const ComboboxEmpty = Primitive.Empty;
+export const ComboboxGroup = Primitive.Group;
+export const ComboboxGroupLabel = Primitive.GroupLabel;
+
+/**
+ * What the input shows: the QUERY while the list is open, the selected item's LABEL while it
+ * is closed.
+ *
+ * The two are different strings and swapping them is the whole job. Show the label while
+ * typing and every keystroke is overwritten by the old selection; show the query while
+ * closed and the field goes blank the moment focus leaves, even though a value is set.
+ */
+export function comboboxInputValue<T>(
+  open: boolean,
+  query: string,
+  value: T | null,
+  getLabel: (item: T) => string,
+): string {
+  if (open) return query;
+  return value === null ? "" : getLabel(value);
+}
+
+/** A loading state needs the line that says so — there is no default, and no English. */
+type ComboboxLoadingState =
+  { loading: boolean; loadingHint: ReactNode } | { loading?: undefined; loadingHint?: undefined };
+
+export type ComboboxProps<T> = Omit<
+  Primitive.Root.Props<T, false, T>,
+  | "children"
+  | "items"
+  | "filteredItems"
+  | "filter"
+  | "value"
+  | "defaultValue"
+  | "multiple"
+  | "open"
+  | "defaultOpen"
+  | "inputValue"
+  | "defaultInputValue"
+  | "onInputValueChange"
+  | "itemToStringLabel"
+  | "isItemEqualToValue"
+> & {
+  value: T | null;
+  /**
+   * Items for the current query. Filtering is yours: this passes `filter={null}` to Base UI,
+   * so the list shows exactly what you return — a server search, a fuzzy match, a bounded
+   * page. Bound it here if it needs bounding; there is no cap in the wrapper, because a cap
+   * would quietly truncate a list a caller meant to show whole.
+   */
+  search: (query: string) => readonly T[];
+  /** Stable identity of an item: its React key, and how two items are compared. */
+  getKey: (item: T) => string;
+  /** The item's text — what the input shows once it is picked, and what typeahead matches. */
+  getLabel: (item: T) => string;
+  renderItem?: (item: T) => ReactNode;
+  /**
+   * Shown when the query matches nothing. Required: "no results" with no next step is a dead
+   * end, and this is the line that offers one.
+   */
+  emptyHint: ReactNode;
+  /** Label for the clear button. Required — it is a button with an icon and no text. */
+  clearLabel: string;
+  /** Label for the button that opens the list. Required, same reason. */
+  openLabel: string;
+  /** Accessible name for the input, when no visible label points at it. */
+  label?: string;
+  leadingIcon?: ReactNode;
+  /** Classes for the input itself. */
+  className?: StateClassName<Primitive.Input.State>;
+  popupClassName?: StateClassName<Primitive.Popup.State>;
+  inputProps?: Primitive.Input.Props;
+  /**
+   * Positioner props — `align`, `side`, `sideOffset`, `collisionPadding`, and the stacking
+   * order. The default `z-[60]` puts the list above the overlay layer (z-50: dialog, drawer);
+   * raise it with `positionerProps={{ className: "z-[80]" }}` if the app stacks something
+   * higher than a dialog above it.
+   */
+  positionerProps?: Primitive.Positioner.Props;
+} & ComboboxLoadingState;
+
+/**
+ * A text field that filters a list. `name`, `form`, `required`, `id` and `disabled` pass
+ * straight through to the root, so it submits inside a `<form>`.
+ *
+ * Controlled only: the wrapper owns `open` and the input value, because those two are what
+ * the label/query bridge is made of.
+ */
+export function Combobox<T>({
+  value,
+  search,
+  getKey,
+  getLabel,
+  renderItem,
+  emptyHint,
+  loading,
+  loadingHint,
+  clearLabel,
+  openLabel,
+  label,
+  leadingIcon,
+  className,
+  popupClassName,
+  inputProps,
+  positionerProps,
+  onOpenChange,
+  ...rest
+}: ComboboxProps<T>) {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const items = useMemo(() => search(query), [query, search]);
+
+  return (
+    <Primitive.Root<T, false, T>
+      value={value}
+      items={items}
+      open={open}
+      itemToStringLabel={getLabel}
+      isItemEqualToValue={(left, right) => getKey(left) === getKey(right)}
+      // `null` hands filtering to `search`. Base UI's own filter would run a SECOND pass over
+      // an already-filtered list, so a server that matched on something the label does not
+      // contain — an id, a phone number, an accent-stripped name — would return rows the
+      // client then threw away.
+      filter={null}
+      inputValue={comboboxInputValue(open, query, value, getLabel)}
+      onInputValueChange={(next) => {
+        setQuery(next);
+        if (!open) setOpen(true);
+      }}
+      onOpenChange={(next, details) => {
+        setOpen(next);
+        // A fresh open starts from the whole list, not from whatever was typed last time.
+        if (next) setQuery("");
+        onOpenChange?.(next, details);
+      }}
+      {...rest}
+    >
+      <Primitive.InputGroup className="relative">
+        {leadingIcon ? (
+          <span className="pointer-events-none absolute top-1/2 left-3 z-10 -translate-y-1/2 text-muted-foreground">
+            {leadingIcon}
+          </span>
+        ) : null}
+        <Primitive.Input
+          aria-label={label}
+          autoComplete="off"
+          {...inputProps}
+          className={mergeClassName(
+            [
+              // No focus style: the field keeps the app's one `:focus-visible` outline. Swapping
+              // it for a `ring-*` loses forced-colors mode, where a box-shadow is forced to none.
+              "w-full min-w-0 rounded-md border border-input bg-background py-2 pr-16 pl-3 text-base text-foreground placeholder:text-muted-foreground disabled:pointer-events-none disabled:opacity-50 md:text-sm",
+              leadingIcon && "pl-9",
+            ],
+            // The caller's classes land BEFORE the space reserved for the buttons is
+            // re-applied below, so a `px-*` of their own cannot swallow it.
+            className,
+          )}
+        />
+        <span className="absolute top-1/2 right-1.5 z-10 flex -translate-y-1/2 items-center gap-0.5">
+          {/* Base UI unmounts Clear on its own when there is nothing to clear, so this is not
+              wrapped in a `value &&`. The input keeps its right padding either way, so the
+              text does not reflow when a value appears. */}
+          <Primitive.Clear
+            aria-label={clearLabel}
+            className="inline-flex rounded-full p-1.5 text-muted-foreground"
+          >
+            <CloseGlyph />
+          </Primitive.Clear>
+          <Primitive.Trigger
+            aria-label={openLabel}
+            className="inline-flex rounded-full p-1.5 text-muted-foreground"
+          >
+            <ChevronGlyph />
+          </Primitive.Trigger>
+        </span>
+      </Primitive.InputGroup>
+      <Primitive.Portal>
+        {/* Above the overlay layer (z-50: dialog, drawer). The list portals to the body and
+            so does the dialog it may be sitting in, so nesting decides nothing and z decides
+            everything — one step lower and the list paints behind its own anchor. */}
+        <Primitive.Positioner
+          sideOffset={4}
+          {...positionerProps}
+          className={mergeClassName(
+            "z-[60] max-w-[var(--available-width)] outline-none",
+            positionerProps?.className,
+          )}
+        >
+          <Primitive.Popup
+            className={mergeClassName(
+              "w-[var(--anchor-width)] overflow-hidden border border-border bg-popover text-popover-foreground outline-none transition-[scale,opacity] data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0",
+              popupClassName,
+            )}
+          >
+            {/* Empty stays MOUNTED and swaps its children — it is the popup's live region,
+                and a live region a screen reader was never given cannot announce a change to
+                it. So it is not wrapped in a condition, and its padding sits on the child
+                instead: the part's own div is left in the DOM at zero height when there is
+                something in the list, rather than as a blank 40px strip above it. */}
+            <Primitive.Empty>
+              <div className="px-3 py-2 text-muted-foreground">
+                {loading ? loadingHint : emptyHint}
+              </div>
+            </Primitive.Empty>
+            {/* `--available-height` is the room the positioner measured between the anchor
+                and the edge of the viewport. Without it the list is unbounded and a long
+                result set runs off the bottom of the screen with no way to reach the end. */}
+            <Primitive.List className="max-h-[var(--available-height)] overflow-y-auto">
+              {(item: T) => (
+                <Primitive.Item
+                  key={getKey(item)}
+                  value={item}
+                  className="cursor-default px-3 py-2 outline-none data-highlighted:bg-accent data-highlighted:text-accent-foreground"
+                >
+                  {renderItem ? renderItem(item) : getLabel(item)}
+                </Primitive.Item>
+              )}
+            </Primitive.List>
+          </Primitive.Popup>
+        </Primitive.Positioner>
+      </Primitive.Portal>
+    </Primitive.Root>
+  );
+}

package/src/ui/dialog.tsx

@@ -0,0 +1,87 @@
+import { Dialog as Primitive } from "@base-ui/react/dialog";
+import { mergeClassName, type StateClassName } from "./class-name.ts";
+import { CloseGlyph } from "./glyphs.tsx";
+
+// The parts, straight through. Base UI already does focus trap, escape, outside-dismiss,
+// scroll lock, focus return and the aria wiring, and a wrapper around any of these would only
+// add a class name — so they are re-exported, not re-implemented.
+export const Dialog = Primitive.Root;
+export const DialogTrigger = Primitive.Trigger;
+export const DialogTitle = Primitive.Title;
+export const DialogDescription = Primitive.Description;
+export const DialogClose = Primitive.Close;
+export const DialogPortal = Primitive.Portal;
+export const DialogBackdrop = Primitive.Backdrop;
+export const DialogPopup = Primitive.Popup;
+
+export type DialogContentProps = Primitive.Popup.Props & {
+  /**
+   * Accessible name, for a dialog with no visible `DialogTitle`. With a title, leave this
+   * out: Base UI points the popup's `aria-labelledby` at it, and an `aria-label` here would
+   * override the words the user can actually see.
+   */
+  label?: string;
+  /**
+   * Label for the built-in close button — REQUIRED to get one, which is the whole point:
+   * passing the label is the only way to render the button, so an unlabelled close button
+   * cannot be written. There is no default string, because a default would be English.
+   */
+  closeLabel?: string;
+  backdropClassName?: StateClassName<Primitive.Backdrop.State>;
+  /** Where the portal mounts. Defaults to `<body>`. */
+  container?: Primitive.Portal.Props["container"];
+};
+
+/**
+ * Portal + backdrop + popup as one part, so a scrimless dialog is not a thing a caller can
+ * ship by forgetting a line. The popup owns the scroll (`overflow-y-auto` plus
+ * `overscroll-contain`, so reaching the end of a long dialog does not start scrolling the
+ * page behind it) and is capped to the viewport, so a tall dialog is never taller than the
+ * screen it opens on.
+ *
+ * Everything else — padding, radius, shadow, type — is the product's. What is here is what
+ * makes the primitive work.
+ */
+export function DialogContent({
+  className,
+  backdropClassName,
+  container,
+  label,
+  closeLabel,
+  children,
+  ...rest
+}: DialogContentProps) {
+  return (
+    <Primitive.Portal container={container}>
+      <Primitive.Backdrop
+        className={mergeClassName(
+          "fixed inset-0 z-50 bg-scrim transition-opacity data-ending-style:opacity-0 data-starting-style:opacity-0",
+          backdropClassName,
+        )}
+      />
+      {/* `outline-none` belongs on a popup and almost nowhere else: this element takes
+          programmatic focus the moment it opens, and a focus ring is meant to answer a
+          keyboard, not to frame every dialog that appears. Controls inside keep theirs. */}
+      <Primitive.Popup
+        aria-label={label}
+        {...rest}
+        className={mergeClassName(
+          "fixed top-1/2 left-1/2 z-50 max-h-[calc(100dvh-2rem)] w-[calc(100%-2rem)] max-w-md -translate-x-1/2 -translate-y-1/2 overflow-y-auto overscroll-contain bg-popover text-popover-foreground outline-none transition-[scale,opacity] data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0",
+          className,
+        )}
+      >
+        {children}
+        {closeLabel === undefined ? null : (
+          <Primitive.Close
+            aria-label={closeLabel}
+            // 44px square: the close button is often the only way out on a phone, and a
+            // smaller target is one a thumb misses.
+            className="absolute top-0 right-0 inline-flex size-11 items-center justify-center text-muted-foreground"
+          >
+            <CloseGlyph />
+          </Primitive.Close>
+        )}
+      </Primitive.Popup>
+    </Primitive.Portal>
+  );
+}

package/src/ui/drawer.tsx

@@ -0,0 +1,161 @@
+import { Drawer as Primitive } from "@base-ui/react/drawer";
+import type { ReactNode } from "react";
+import { mergeClassName, type StateClassName } from "./class-name.ts";
+
+// The parts, for a drawer that needs a shape this wrapper does not give it.
+export const DrawerRoot = Primitive.Root;
+export const DrawerTrigger = Primitive.Trigger;
+export const DrawerPortal = Primitive.Portal;
+export const DrawerBackdrop = Primitive.Backdrop;
+export const DrawerViewport = Primitive.Viewport;
+export const DrawerPopup = Primitive.Popup;
+export const DrawerContent = Primitive.Content;
+export const DrawerHandle = Primitive.Handle;
+export const DrawerSwipeArea = Primitive.SwipeArea;
+export const DrawerTitle = Primitive.Title;
+export const DrawerDescription = Primitive.Description;
+export const DrawerClose = Primitive.Close;
+
+export type DrawerSide = "left" | "right" | "bottom";
+
+const viewportSide: Record<DrawerSide, string> = {
+  left: "items-stretch justify-start",
+  right: "items-stretch justify-end",
+  bottom: "items-end",
+};
+
+// The translate pair is what Base UI animates between: `data-starting-style` is the frame
+// before it opens, `data-ending-style` the frame it leaves on. Same class both ways, so the
+// drawer goes back out the side it came in.
+const popupSide: Record<DrawerSide, string> = {
+  left: "w-[min(24rem,calc(100vw-1rem))] data-ending-style:-translate-x-full data-starting-style:-translate-x-full",
+  right:
+    "w-[min(24rem,calc(100vw-1rem))] data-ending-style:translate-x-full data-starting-style:translate-x-full",
+  bottom:
+    "max-h-[90svh] w-full data-ending-style:translate-y-full data-starting-style:translate-y-full",
+};
+
+/**
+ * Where the portal mounts, and whether the drawer covers the page or a box inside it.
+ *
+ * A scoped drawer positions itself `absolute` against a container instead of `fixed` against
+ * the viewport — so it MUST be given that container, or it lands in `<body>` and positions
+ * against a box that is not there. The two travel together in the type.
+ *
+ * The container also needs a positioning context of its own (`relative`): `absolute` walks up
+ * to the nearest positioned ancestor, so a static container hands the drawer the whole page
+ * and the "scoped" part quietly does not happen.
+ */
+type DrawerPortalTarget =
+  | { scoped: true; container: NonNullable<Primitive.Portal.Props["container"]> }
+  | { scoped?: false; container?: Primitive.Portal.Props["container"] };
+
+export type DrawerProps<Payload = unknown> = Omit<
+  Primitive.Root.Props<Payload>,
+  "children" | "swipeDirection"
+> &
+  DrawerPortalTarget & {
+    /**
+     * Which edge it comes from. This also sets `swipeDirection` on the root — the two must
+     * agree, and a mismatch is silent: the drawer looks right and dismisses on a swipe
+     * towards the screen it is attached to.
+     */
+    side?: DrawerSide;
+    /** Accessible name, for a drawer with no visible `DrawerTitle`. */
+    label?: string;
+    children?: ReactNode;
+    /** Classes for the popup — the panel itself. */
+    className?: StateClassName<Primitive.Popup.State>;
+    backdropClassName?: StateClassName<Primitive.Backdrop.State>;
+    viewportClassName?: StateClassName<Primitive.Viewport.State>;
+    contentClassName?: StateClassName<Primitive.Content.State>;
+    /** Popup-level props the wrapper does not own — `initialFocus`, `finalFocus`, `data-*`. */
+    popupProps?: Primitive.Popup.Props;
+  };
+
+/**
+ * A panel that slides in from an edge. Root → portal → backdrop → viewport → popup → content,
+ * composed once here because the parts have to be arranged in exactly this order to work at
+ * all, and because two of the four rules below cost someone a bug that no test would catch.
+ *
+ * Everything the root takes — `open`, `onOpenChange`, `modal`, `snapPoints`, `actionsRef`,
+ * `data-*` — passes straight through.
+ */
+export function Drawer<Payload = unknown>({
+  side = "right",
+  label,
+  scoped = false,
+  container,
+  className,
+  backdropClassName,
+  viewportClassName,
+  contentClassName,
+  popupProps,
+  children,
+  ...rest
+}: DrawerProps<Payload>) {
+  return (
+    <Primitive.Root swipeDirection={side === "bottom" ? "down" : side} {...rest}>
+      {/* Base UI throws (error #26) if any drawer part sits outside a Portal, so the scoped
+          variant does not skip the portal — it portals INTO its container and positions
+          absolutely there. */}
+      <Primitive.Portal container={container}>
+        <Primitive.Backdrop
+          className={mergeClassName(
+            [
+              scoped ? "absolute" : "fixed",
+              "inset-0 z-40 bg-scrim transition-opacity data-ending-style:opacity-0 data-starting-style:opacity-0",
+            ],
+            backdropClassName,
+          )}
+        />
+        {/* The z-index lives on the VIEWPORT, not on the popup. `position: fixed` always
+            creates a stacking context, so a z on the popup would only rank it inside the
+            viewport's own `z-auto` context — which paints under every positioned z-30+
+            element on the page (header, sidebar, floating buttons) however high that z is.
+
+            It is z-50, which TIES the dialog layer rather than clearing it, on purpose. A
+            drawer hosts whole app surfaces — a mobile nav carries the entire sidebar — and
+            those surfaces open dialogs. Rank the drawer above the dialog layer and it paints
+            over every modal opened from inside it: the user taps, nothing appears. At a tie
+            the dialog wins on DOM order, because it portals to the body after the drawer
+            that opened it. */}
+        <Primitive.Viewport
+          className={mergeClassName(
+            [scoped ? "absolute" : "fixed", "inset-0 z-50 flex", viewportSide[side]],
+            viewportClassName,
+          )}
+        >
+          <Primitive.Popup
+            aria-label={label}
+            {...popupProps}
+            className={mergeClassName(
+              [
+                "pointer-events-auto flex flex-col overflow-y-auto overscroll-contain bg-background text-foreground outline-none transition-transform",
+                popupSide[side],
+              ],
+              className,
+            )}
+          >
+            <Primitive.Content
+              className={mergeClassName(
+                [
+                  "flex w-full flex-1 flex-col",
+                  // A side drawer has a definite height (the viewport's), so cap the content
+                  // to it. Without `min-h-0` a child with its own scroll region grows the
+                  // popup instead of scrolling inside it, and the footer that was meant to
+                  // stay pinned ends up at the bottom of one long page scroll. A bottom
+                  // drawer sizes from its content, so it keeps the default `min-height: auto`.
+                  side !== "bottom" && "min-h-0",
+                ],
+                contentClassName,
+              )}
+            >
+              {children}
+            </Primitive.Content>
+          </Primitive.Popup>
+        </Primitive.Viewport>
+      </Primitive.Portal>
+    </Primitive.Root>
+  );
+}

package/src/ui/focus.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Two structural rules for every wrapper in this folder, checked against the source rather
+ * than a render — because both failures look correct in a browser and only show up for the
+ * people least able to report them.
+ *
+ * Neither is a style opinion. Each is a rule from AGENTS.md with a mechanism behind it, and
+ * both were live in this folder before this file existed.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+// `fileURLToPath`, never `import.meta.dir` — invariant 11: the latter is bun-only, and this
+// suite has to run under vitest on plain Node too.
+const here = dirname(fileURLToPath(import.meta.url));
+
+const sources = readdirSync(here)
+  .filter((name) => name.endsWith(".tsx") || (name.endsWith(".ts") && !name.includes(".test.")))
+  .map((name) => ({ name, text: readFileSync(join(here, name), "utf8") }));
+
+/**
+ * Every class string is on one line here, so a line is the right unit to quote back.
+ *
+ * Comment lines are skipped, and that is load-bearing rather than tidy: each of these rules is
+ * worth a sentence saying why, and the sentence has to be free to name the thing it forbids. A
+ * guard that fails on its own explanation teaches people to delete the explanation.
+ */
+function linesMatching(text: string, pattern: RegExp): number[] {
+  // Block comments are BLANKED, not deleted: removing them would collapse lines and every number
+  // reported after one would point at the wrong place. (That is also why this cannot share
+  // `menu.test.ts`'s `codeOf`, which strips outright because it only ever counts occurrences.)
+  // Blanking also means a wrapped comment line is ignored whether or not it opens with a `*`.
+  const code = text.replace(/\/\*[\s\S]*?\*\//g, (block) => block.replace(/[^\n]/g, " "));
+  return code
+    .split("\n")
+    .map((line, i) => (!line.trim().startsWith("//") && pattern.test(line) ? i + 1 : 0))
+    .filter(Boolean);
+}
+
+describe("the wrappers do not draw their own focus ring", () => {
+  // Invariant 19. A control that writes `outline-none focus-visible:ring-2` looks identical to
+  // the base outline in every normal browser and disappears under `forced-colors: active`,
+  // where the UA forces `box-shadow` to `none` and leaves `outline` painted in a system colour.
+  // So the swap deletes the keyboard focus indicator for Windows High Contrast users only.
+  // The app's one ring lives in `@gusnips/tokens`' base layer and needs no help from here.
+  it.each(sources)("$name has no focus-visible ring", ({ text }) => {
+    expect(linesMatching(text, /focus-visible:ring|focus:ring/)).toEqual([]);
+  });
+
+  // The other half: `outline-none` is legitimate on a container that takes focus
+  // programmatically (a Popup, its Positioner, a highlighted Item), and nowhere else. It is
+  // only a bug when it removes the outline without the primitive putting focus somewhere that
+  // still shows one — which is what the rule above now makes impossible, since there is no
+  // replacement ring left to write. This asserts the reset stayed inside the popup parts.
+  it.each(sources)("$name resets the outline only on popup parts", ({ text }) => {
+    const offenders = linesMatching(text, /outline-none/).filter((line) => {
+      // ponytail: "the nearest Primitive tag above" approximated as a 12-line lookback, which
+      // clears every part in this folder today with room to spare. The ceiling is a part whose
+      // props run longer than that, which would read as a violation while being correct. If that
+      // happens, parse the enclosing JSX element instead of counting lines — do not just raise 12.
+      const context = text
+        .split("\n")
+        .slice(Math.max(0, line - 12), line)
+        .join("\n");
+      return !/<Primitive\.(Popup|Positioner|Item|ItemsEmpty|Backdrop|Viewport)\b/.test(context);
+    });
+    expect(offenders).toEqual([]);
+  });
+});
+
+describe("the wrappers never hardcode a colour", () => {
+  // Invariant 21. `text-white` on a primary fill is correct in one donor's dark theme and
+  // unreadable in the other's, because `--color-primary-foreground` is `#ffffff` in one and a
+  // near-black in the other. A shared control cannot know which it is running in, so it always
+  // reads the token.
+  it.each(sources)("$name uses tokens, not literal colours", ({ text }) => {
+    const literal =
+      /\b(?:text|bg|border|fill|stroke|ring|shadow)-(?:white|black|slate|gray|zinc|neutral|stone|red|blue|green|amber|yellow)\b|#[0-9a-fA-F]{3,8}\b/;
+    expect(linesMatching(text, literal)).toEqual([]);
+  });
+});

package/src/ui/glyphs.tsx

@@ -0,0 +1,35 @@
+// The three affordance marks the wrappers draw by default: the chevron that says "this
+// opens", the check that says "this one is picked", the cross that says "this closes".
+//
+// They are `currentColor` stroke on a 24-grid so a product's own icon set drops in without
+// a size or colour change. Every component that draws one takes it as a prop — these are the
+// zero-config default, never the only option.
+
+function Glyph({ d }: { d: string }) {
+  return (
+    <svg
+      className="size-4"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d={d} />
+    </svg>
+  );
+}
+
+export function ChevronGlyph() {
+  return <Glyph d="m6 9 6 6 6-6" />;
+}
+
+export function CheckGlyph() {
+  return <Glyph d="m5 13 4 4 10-10" />;
+}
+
+export function CloseGlyph() {
+  return <Glyph d="M18 6 6 18M6 6l12 12" />;
+}