@morphemecms/cms 0.0.0-stage → 0.1.0

package/theme/ui/NavigationBar.tsx

@@ -0,0 +1,62 @@
+// A navigation bar (m3.material.io/components/navigation-bar, .navigation-bar in ../styles/ui.css): the few main
+// destinations side by side at the bottom of a phone's screen (NavigationBar, a <nav> with its name, `label`), each
+// (NavigationBarItem) with its icon and its label, the open one (`selected`, aria-current) with the indicator behind its
+// icon, and evt. a badge on the icon (`badge`: true for a dot, else the number it shows; the theme's Badge). Where the
+// icon stands (`iconPosition`) is M3 Expressive's item configuration: `top`, the default, over the label (vertical
+// items, each as wide as the others), `start` beside it (horizontal items, as wide as their content, together in the
+// middle of the bar, the indicator behind both), or `auto`: over it while the bar is narrower than 600px (a phone) and
+// beside it from there (a tablet and wider), as Material recommends. Where it stands (fixed at the bottom of the screen)
+// is the component's own; how it looks is the theme's. Links are Link (on the site; in the editor only drawn); other
+// attributes go on them. An Astro component gives its elements the classes with navigationBarClass,
+// navigationBarClasses and navigationBarItemClass.
+import type { ReactNode } from 'react';
+import { Svg } from '@morphemecms/cms/src/icon';
+import { Link } from '@morphemecms/cms/src/standard/view';
+import Badge from '@theme/ui/Badge';
+
+export type NavigationBarIconPosition = 'top' | 'start' | 'auto';
+
+/** The bar's class, and a destination's. */
+export const navigationBarClass = 'navigation-bar';
+export const navigationBarItemClass = 'navigation-bar-item';
+
+/** The bar's classes with where its items' icons stand. */
+export const navigationBarClasses = (iconPosition: NavigationBarIconPosition = 'top') =>
+  iconPosition === 'top' ? navigationBarClass : `${navigationBarClass} navigation-bar-${iconPosition}`;
+
+export default function NavigationBar({
+  label,
+  iconPosition,
+  className,
+  children,
+  ...rest
+}: { label: string; iconPosition?: NavigationBarIconPosition; className?: string; children: ReactNode } & Record<string, unknown>) {
+  return (
+    <nav aria-label={label} className={[navigationBarClasses(iconPosition), className].filter(Boolean).join(' ')} {...rest}>
+      {children}
+    </nav>
+  );
+}
+
+/** A destination: its icon (a Phosphor name, the theme's icon) and its label, `selected` when it is the open page,
+ * and evt. a badge on the icon. */
+export function NavigationBarItem({
+  href,
+  icon,
+  label,
+  selected,
+  badge,
+  ...rest
+}: { href: string; icon: string; label: ReactNode; selected?: boolean; badge?: true | number } & Record<string, unknown>) {
+  return (
+    <Link href={href} className={navigationBarItemClass} aria-current={selected ? 'page' : undefined} {...rest}>
+      <span className="navigation-bar-indicator">
+        <span className="navigation-bar-icon">
+          <Svg name={icon} size={24} />
+          {badge !== undefined && <Badge count={badge === true ? undefined : badge} className="navigation-bar-badge" />}
+        </span>
+        <span className="navigation-bar-label">{label}</span>
+      </span>
+    </Link>
+  );
+}

package/theme/ui/NavigationDrawer.tsx

@@ -0,0 +1,80 @@
+// A modal navigation drawer (m3.material.io/components/navigation-drawer, .navigation-drawer in ../styles/ui.css): the
+// site's pages in a panel over the page (components/MobileMenu.tsx, and a theme's own menu), over its scrim
+// (navigationDrawerScrimClass). Its pages are items (NavigationDrawerItem, `active`: the open page or the one holding
+// it), an item with sub-pages is a row (NavigationDrawerRow) with the button that unfolds them after it
+// (NavigationDrawerToggle, `expanded`), and a sub-page a subitem (NavigationDrawerSubitem). Where it comes from, how it
+// moves and what else is in it (the logo, the buttons) is the menu's own: it gives its own element (a motion.div) the
+// class with navigationDrawerClass; in a <dialog> (the editor's), the dialog has navigationDrawerDialogClass and its
+// scrim is the dialog's. Links are Link (on the site; in the editor's previews only drawn), an item without `href` a
+// button (the editor's: a part of a form); other attributes (onClick, aria-…) go on them.
+import type { ReactNode } from 'react';
+import { Svg } from '@morphemecms/cms/src/icon';
+import { Link } from '@morphemecms/cms/src/standard/view';
+
+/** The drawer's class, and its scrim's. */
+export const navigationDrawerClass = 'navigation-drawer';
+export const navigationDrawerScrimClass = 'navigation-drawer-scrim';
+/** The class of a <dialog> the drawer is in: at the end of the screen, as high as it, over its scrim. */
+export const navigationDrawerDialogClass = 'navigation-drawer-dialog';
+
+export function NavigationDrawer({ className, children, ...rest }: { className?: string; children: ReactNode } & Record<string, unknown>) {
+  return (
+    <div className={[navigationDrawerClass, className].filter(Boolean).join(' ')} {...rest}>
+      {children}
+    </div>
+  );
+}
+
+/** A page in the drawer, `active` when it is the open page or holds it; without `href` a button. */
+export function NavigationDrawerItem({
+  href,
+  active,
+  children,
+  ...rest
+}: { href?: string; active?: boolean; children: ReactNode } & Record<string, unknown>) {
+  return href === undefined ? (
+    <button type="button" className="navigation-drawer-item" data-active={active || undefined} {...rest}>
+      {children}
+    </button>
+  ) : (
+    <Link href={href} className="navigation-drawer-item" data-active={active || undefined} {...rest}>
+      {children}
+    </Link>
+  );
+}
+
+/** An item and what stands after it (the toggle of its sub-pages). */
+export function NavigationDrawerRow({
+  className,
+  children,
+  ...rest
+}: { className?: string; children: ReactNode } & Record<string, unknown>) {
+  return (
+    <div className={['navigation-drawer-row', className].filter(Boolean).join(' ')} {...rest}>
+      {children}
+    </div>
+  );
+}
+
+/** The button that unfolds an item's sub-pages: a caret, turned while they are open (`expanded`). */
+export function NavigationDrawerToggle({ label, expanded, ...rest }: { label: string; expanded: boolean } & Record<string, unknown>) {
+  return (
+    <button type="button" className="navigation-drawer-toggle" aria-expanded={expanded} aria-label={label} {...rest}>
+      <Svg name="caret-down" size={20} />
+    </button>
+  );
+}
+
+/** A sub-page, `active` when it is the open page. */
+export function NavigationDrawerSubitem({
+  href,
+  active,
+  children,
+  ...rest
+}: { href: string; active?: boolean; children: ReactNode } & Record<string, unknown>) {
+  return (
+    <Link href={href} className="navigation-drawer-subitem" data-active={active || undefined} {...rest}>
+      {children}
+    </Link>
+  );
+}

package/theme/ui/NavigationRail.tsx

@@ -0,0 +1,154 @@
+// A navigation rail (m3.material.io/components/navigation-rail, M3 Expressive; .navigation-rail in ../styles/ui.css):
+// the main destinations down the side of a larger screen (NavigationRail, a <nav> with its name, `label`), collapsed
+// (each destination's icon over its label) or expanded (`expanded`: the icon and the label side by side), with its menu
+// button at the top (`menuLabel`, which expands and collapses it: on the site navigationRail.script.ts) and evt. the
+// screen's main action under it (`fab`: an extended FAB, ExtendedFab, with only its icon while the rail is collapsed).
+// Material's two configurations of the expanded rail: its modality (`modality`: `standard`, the default, beside the
+// content, which makes room for it, or `modal`, over the page with a scrim behind it, which closes it, as Escape does)
+// and its behaviour (`expandedBehavior`: `collapse`, the default, back into the collapsed rail, or `hide`, nothing while
+// it is collapsed; then a button elsewhere opens it: an icon button with data-navigation-rail-menu and aria-controls,
+// the rail's id). Each destination (NavigationRailItem) has its icon, its label, `selected` (aria-current) when it is
+// the open page, and evt. a badge on the icon (`badge`: true for a dot, else the number it shows; the theme's Badge) and,
+// while the rail is expanded, a text at its end (`trailingSupporting`: how many there are). The destinations can stand in
+// sections (NavigationRailSection, M3 Expressive's), each with its name over it while the rail is expanded and a line
+// between them while it is collapsed. Evt. something under the menu button while the rail is expanded (`header`: the
+// editor's logo and the site's name). With `onExpandedChange` the rail is expanded and collapsed by whoever draws it (the
+// editor) instead of by its script; a modal one without `scrim` has none (one that expands while the mouse is over it:
+// the editor's).
+// Where it stands (beside the content, in a row) is the component's own; how it looks is the theme's. Links are Link (on
+// the site; in the editor only drawn). An Astro component gives its elements the classes with navigationRailClass,
+// navigationRailClasses and navigationRailItemClass.
+import type { ReactNode } from 'react';
+import { Glyph, Svg, type IconRef } from '@morphemecms/cms/src/icon';
+import { Link } from '@morphemecms/cms/src/standard/view';
+import { ExtendedFab } from '@theme/ui/Fab';
+import { iconButtonClass } from '@theme/ui/IconButton';
+import Badge from '@theme/ui/Badge';
+
+export type NavigationRailModality = 'standard' | 'modal';
+export type NavigationRailExpandedBehavior = 'collapse' | 'hide';
+
+/** The rail's class, and a destination's. */
+export const navigationRailClass = 'navigation-rail';
+export const navigationRailItemClass = 'navigation-rail-item';
+
+/** The rail's classes with its expanded modality and behaviour. */
+export const navigationRailClasses = (
+  modality: NavigationRailModality = 'standard',
+  expandedBehavior: NavigationRailExpandedBehavior = 'collapse',
+) =>
+  [navigationRailClass, modality === 'modal' && 'navigation-rail-modal', expandedBehavior === 'hide' && 'navigation-rail-hide']
+    .filter(Boolean)
+    .join(' ');
+
+/** The scrim's class, behind a modal rail while it is expanded. */
+export const navigationRailScrimClass = 'navigation-rail-scrim';
+
+export default function NavigationRail({
+  label,
+  menuLabel,
+  expanded,
+  modality = 'standard',
+  expandedBehavior = 'collapse',
+  fab,
+  header,
+  scrim = true,
+  onExpandedChange,
+  className,
+  children,
+  ...rest
+}: {
+  label: string;
+  menuLabel: string;
+  expanded?: boolean;
+  modality?: NavigationRailModality;
+  expandedBehavior?: NavigationRailExpandedBehavior;
+  fab?: { icon: string; label: string; href?: string } & Record<string, unknown>;
+  header?: ReactNode;
+  scrim?: boolean;
+  onExpandedChange?: (expanded: boolean) => void;
+  className?: string;
+  children: ReactNode;
+} & Record<string, unknown>) {
+  const rail = (
+    <nav
+      aria-label={label}
+      className={[navigationRailClasses(modality, expandedBehavior), className].filter(Boolean).join(' ')}
+      data-navigation-rail=""
+      data-expanded={expanded || undefined}
+      {...rest}
+    >
+      <div className="navigation-rail-header">
+        <button
+          type="button"
+          className={`${iconButtonClass('standard')} navigation-rail-menu`}
+          aria-label={menuLabel}
+          aria-expanded={!!expanded}
+          data-navigation-rail-menu={onExpandedChange ? undefined : ''}
+          onClick={onExpandedChange && (() => onExpandedChange(!expanded))}
+        >
+          <Svg name="list" size={24} />
+          <Svg name="caret-left" size={24} />
+        </button>
+        {fab && <ExtendedFab {...fab} collapsed={!expanded} />}
+        {header != null && <div className="navigation-rail-header-content">{header}</div>}
+      </div>
+      <div className="navigation-rail-items">{children}</div>
+    </nav>
+  );
+  // A modal one's scrim just before it, over the page and under the rail (navigationRail.script.ts shows it).
+  return modality === 'modal' && scrim ? (
+    <>
+      <div className={navigationRailScrimClass} data-navigation-rail-scrim="" hidden={!expanded} />
+      {rail}
+    </>
+  ) : (
+    rail
+  );
+}
+
+/** Destinations under each other in a section, with its name (`label`) over them while the rail is expanded. */
+export function NavigationRailSection({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <div className="navigation-rail-section" role="group" aria-label={label}>
+      <span className="navigation-rail-section-label" aria-hidden="true">
+        {label}
+      </span>
+      {children}
+    </div>
+  );
+}
+
+/** A destination: its icon (a Phosphor name, the theme's icon, or an icon made: IconRef) and its label, `selected` when
+ * it is the open page, evt. a badge on the icon, and a text at its end while the rail is expanded. */
+export function NavigationRailItem({
+  href,
+  icon,
+  label,
+  selected,
+  badge,
+  trailingSupporting,
+  ...rest
+}: {
+  href: string;
+  icon: IconRef;
+  label: ReactNode;
+  selected?: boolean;
+  badge?: true | number;
+  trailingSupporting?: ReactNode;
+} & Record<string, unknown>) {
+  return (
+    <Link href={href} className={navigationRailItemClass} aria-current={selected ? 'page' : undefined} {...rest}>
+      <span className="navigation-rail-indicator">
+        <span className="navigation-rail-icon">
+          <Glyph icon={icon} size={24} />
+          {badge !== undefined && <Badge count={badge === true ? undefined : badge} className="navigation-rail-badge" />}
+        </span>
+        <span className="navigation-rail-label">{label}</span>
+        {trailingSupporting != null && trailingSupporting !== '' && (
+          <span className="navigation-rail-trailing-supporting">{trailingSupporting}</span>
+        )}
+      </span>
+    </Link>
+  );
+}

package/theme/ui/ProgressIndicator.tsx

@@ -0,0 +1,162 @@
+// Progress indicators (m3.material.io/components/progress-indicators, .linear-progress-indicator and
+// .circular-progress-indicator in ../styles/ui.css): how far something has come (`value`, 0 to 1: determinate), as a
+// line that fills up (LinearProgressIndicator) or a ring (CircularProgressIndicator, where there is no room for a
+// line), the active indicator on its track; without `value` (indeterminate), that it is on its way, as stretches that
+// run along the line or round the ring. M3 Expressive's shape (`shape`: flat, the default, or wavy, the active
+// indicator a wave that flows along it) and its thick track (`thick`) are Material's names; how they look is the
+// theme's (--linear-progress-indicator-*, --circular-progress-indicator-*). The wave is drawn here as an SVG path (a
+// line, not an icon), Material's: 3px high and 40px long on a line (24px while indeterminate), nine waves round a ring
+// (six round a thick one).
+// Screen readers read a progress bar named by `label`, with its value in percent when it is known. With reduced motion
+// the indeterminate ones move slowly, the wave stands still and a value changes at once. The value is the custom
+// property --progress on the element, so a script can change it (with aria-valuenow).
+import type { CSSProperties } from 'react';
+
+/** A progress indicator's shapes, as M3 Expressive names them. */
+export type ProgressIndicatorShape = 'flat' | 'wavy';
+
+const clamp = (v: number) => Math.min(1, Math.max(0, v));
+
+// What a progress bar is to screen readers, and its value for the CSS (with the wave's measures for a wavy one).
+function progressbar(value: number | undefined, label: string, wave?: Record<string, string | number>) {
+  const known = value !== undefined;
+  const style = { ...(known ? { '--progress': clamp(value) } : {}), ...wave } as CSSProperties;
+  return {
+    role: 'progressbar',
+    'aria-label': label,
+    'aria-valuemin': 0,
+    'aria-valuemax': 100,
+    'aria-valuenow': known ? Math.round(clamp(value) * 100) : undefined,
+    style: Object.keys(style).length ? style : undefined,
+  };
+}
+
+const classes = (part: string, indeterminate?: boolean, shape: ProgressIndicatorShape = 'flat', thick = false) =>
+  [part, indeterminate && `${part}-indeterminate`, shape === 'wavy' && `${part}-wavy`, thick && `${part}-thick`].filter(Boolean).join(' ');
+
+/** A linear progress indicator's classes: determinate or not, its shape and a thick track. */
+export const linearProgressIndicatorClass = (indeterminate?: boolean, shape?: ProgressIndicatorShape, thick?: boolean) =>
+  classes('linear-progress-indicator', indeterminate, shape, thick);
+/** A circular progress indicator's classes: determinate or not, its shape and a thick track. */
+export const circularProgressIndicatorClass = (indeterminate?: boolean, shape?: ProgressIndicatorShape, thick?: boolean) =>
+  classes('circular-progress-indicator', indeterminate, shape, thick);
+
+// The line's wave, in px: its height (amplitude) and length (wavelength), and a path of it long enough for any line,
+// from one wavelength before its start (where it flows in from), in quadratic curves, a peak and a trough each.
+const AMPLITUDE = 3;
+const WAVELENGTH = { determinate: 40, indeterminate: 24 };
+const LENGTH = 4096;
+function linePath(wavelength: number) {
+  const half = wavelength / 2;
+  const turns = Math.ceil((LENGTH + wavelength) / half);
+  return `M${-wavelength} 0q${half / 2} ${-2 * AMPLITUDE} ${half} 0${` t${half} 0`.repeat(turns - 1)}`;
+}
+// How much longer the wave is than the line it runs along (for its dashes, which CSS measures along the path).
+function stretch(wavelength: number) {
+  const half = wavelength / 2;
+  let length = 0;
+  let last = [0, 0];
+  for (let i = 1; i <= 64; i++) {
+    const t = i / 64;
+    const point = [2 * (1 - t) * t * (half / 2) + t * t * half, 2 * (1 - t) * t * -2 * AMPLITUDE];
+    length += Math.hypot(point[0] - last[0], point[1] - last[1]);
+    last = point;
+  }
+  return length / half;
+}
+const lines = {
+  determinate: { d: linePath(WAVELENGTH.determinate), stretch: stretch(WAVELENGTH.determinate) },
+  indeterminate: { d: linePath(WAVELENGTH.indeterminate), stretch: stretch(WAVELENGTH.indeterminate) },
+};
+
+// The ring's wave in its 48 wide box: nine waves round it (a thick one six, longer for its thicker line), its radius
+// in from the box's edge for its height and thickness, as a path of points (pathLength 100, as the ring's).
+function ringPath(r: number, amplitude: number, waves: number) {
+  const points = Array.from({ length: 180 }, (_, i) => {
+    const angle = (i / 180) * 2 * Math.PI;
+    const at = r + amplitude * Math.sin(waves * angle);
+    return `${(24 + at * Math.cos(angle)).toFixed(2)} ${(24 + at * Math.sin(angle)).toFixed(2)}`;
+  });
+  return `M${points.join('L')}Z`;
+}
+const rings = { wavy: ringPath(19, 1.25, 9), wavyThick: ringPath(17.5, 1.5, 6) };
+
+export function LinearProgressIndicator({
+  value,
+  label,
+  shape = 'flat',
+  thick,
+  className,
+  ...rest
+}: { value?: number; label: string; shape?: ProgressIndicatorShape; thick?: boolean; className?: string } & Record<string, unknown>) {
+  const indeterminate = value === undefined;
+  const wavy = shape === 'wavy';
+  const line = lines[indeterminate ? 'indeterminate' : 'determinate'];
+  const wave = wavy
+    ? {
+        '--linear-progress-indicator-amplitude': `${AMPLITUDE}px`,
+        '--linear-progress-indicator-wavelength': `${WAVELENGTH[indeterminate ? 'indeterminate' : 'determinate']}px`,
+        '--linear-progress-indicator-stretch': line.stretch.toFixed(4),
+      }
+    : undefined;
+  return (
+    <div
+      className={[linearProgressIndicatorClass(indeterminate, shape, thick), className].filter(Boolean).join(' ')}
+      {...progressbar(value, label, wave)}
+      {...rest}
+    >
+      {wavy ? (
+        <>
+          {!indeterminate && <span className="linear-progress-indicator-track"></span>}
+          <svg className="linear-progress-indicator-wave" aria-hidden="true">
+            <path className="linear-progress-indicator-active" d={line.d} />
+            {indeterminate && <path className="linear-progress-indicator-active" d={line.d} />}
+          </svg>
+          {!indeterminate && <span className="linear-progress-indicator-stop"></span>}
+        </>
+      ) : indeterminate ? (
+        <>
+          <span className="linear-progress-indicator-active"></span>
+          <span className="linear-progress-indicator-active"></span>
+        </>
+      ) : (
+        <>
+          <span className="linear-progress-indicator-active"></span>
+          <span className="linear-progress-indicator-track"></span>
+          <span className="linear-progress-indicator-stop"></span>
+        </>
+      )}
+    </div>
+  );
+}
+
+export function CircularProgressIndicator({
+  value,
+  label,
+  shape = 'flat',
+  thick,
+  className,
+  ...rest
+}: { value?: number; label: string; shape?: ProgressIndicatorShape; thick?: boolean; className?: string } & Record<string, unknown>) {
+  const indeterminate = value === undefined;
+  const wavy = shape === 'wavy';
+  // A ring 48 wide, its stroke inside it (a thick or wavy one further in); the lengths along it in percent
+  // (pathLength).
+  const ring = { cx: 24, cy: 24, r: wavy ? (thick ? 17.5 : 19) : thick ? 19 : 20, pathLength: 100, fill: 'none' };
+  return (
+    <span
+      className={[circularProgressIndicatorClass(indeterminate, shape, thick), className].filter(Boolean).join(' ')}
+      {...progressbar(value, label)}
+      {...rest}
+    >
+      <svg viewBox="0 0 48 48" aria-hidden="true">
+        {!indeterminate && <circle className="circular-progress-indicator-track" {...ring} />}
+        {wavy ? (
+          <path className="circular-progress-indicator-active" d={thick ? rings.wavyThick : rings.wavy} pathLength={100} fill="none" />
+        ) : (
+          <circle className="circular-progress-indicator-active" {...ring} />
+        )}
+      </svg>
+    </span>
+  );
+}

package/theme/ui/RadioButton.tsx

@@ -0,0 +1,50 @@
+// A radio button (m3.material.io/components/radio-button, .radio-button in ../styles/ui.css): one of a few choices,
+// of which only one can be chosen. As the checkbox (Checkbox.tsx): the round button, its name (`label`) beside it and
+// a line under the name (`supporting`), all of it one <label>, so a click anywhere chooses it. The buttons of one
+// choice have the same `name` (on the <input>, with its `value`) and stand in a RadioGroup, the choice's name
+// (`label`) over them: native radio buttons, so the arrow keys move between them and Tab moves past the group.
+// `checked`: chosen from the start; `disabled`: it cannot be chosen. The browser draws the button in the accent; a
+// theme that draws it itself (appearance: none) draws its dot too. Other attributes (`name`, `value`, data-…) go on
+// the <input>, and `className` on the label. An Astro component gives an element the same classes with
+// radioButtonClass and radioGroupClass.
+import type { ReactNode } from 'react';
+
+/** A radio button's classes, and a group's. */
+export const radioButtonClass = () => 'radio-button';
+export const radioGroupClass = () => 'radio-group';
+
+export default function RadioButton({
+  label,
+  supporting,
+  checked,
+  className,
+  ...rest
+}: { label: string; supporting?: string; checked?: boolean; className?: string } & Record<string, unknown>) {
+  return (
+    <label className={[radioButtonClass(), className].filter(Boolean).join(' ')}>
+      <span className="radio-button-box">
+        <input type="radio" className="radio-button-input" defaultChecked={checked} {...rest} />
+      </span>
+      <span className="radio-button-text">
+        <span className="radio-button-label">{label}</span>
+        {supporting && <span className="radio-button-supporting">{supporting}</span>}
+      </span>
+    </label>
+  );
+}
+
+/** The radio buttons of one choice under its name (`label`): a <fieldset> with its <legend>. Other attributes go on
+ * the <fieldset>, and `className` after its own class. */
+export function RadioGroup({
+  label,
+  className,
+  children,
+  ...rest
+}: { label: string; className?: string; children: ReactNode } & Record<string, unknown>) {
+  return (
+    <fieldset className={[radioGroupClass(), className].filter(Boolean).join(' ')} {...rest}>
+      <legend className="radio-group-label">{label}</legend>
+      {children}
+    </fieldset>
+  );
+}

package/theme/ui/Search.tsx

@@ -0,0 +1,129 @@
+// A search (m3.material.io/components/search, .search in ../styles/ui.css): the search bar (its leading icon,
+// `leadingIcon`, the theme's magnifying glass if it has none, the placeholder, `label`, and what stands after it,
+// `trailing`: icon buttons, an avatar) and the search view it opens (a <dialog>: over the whole screen on a phone, docked
+// where the bar is from 48rem), with the button back (`backLabel`), the field (a role="combobox"), the button that
+// empties it (`clearLabel`), and the results (`results`, the theme's list, List and ListItem, as a role="listbox" of
+// links, each its headline, evt. its supporting text and its icon) or, when none fits, `emptyText`. On the site
+// search.script.ts opens and closes it (the back button, Escape, a tap outside), narrows the results to what is
+// written, and moves through them with the arrow keys (Enter follows the one it is on). In the editor only drawn:
+// `open` draws the view (as docked) with `query` in the field instead of the bar. How it looks is the theme's.
+import { useId, type ReactNode } from 'react';
+import { Svg } from '@morphemecms/cms/src/icon';
+import IconButton from '@theme/ui/IconButton';
+import List, { ListItem } from '@theme/ui/List';
+
+export type SearchResult = { href: string; headline: ReactNode; supporting?: ReactNode; icon?: string };
+
+/** The class of a search (the bar and its view). */
+export const searchClass = 'search';
+
+export default function Search({
+  label,
+  backLabel,
+  clearLabel,
+  emptyText,
+  results,
+  leadingIcon = 'magnifying-glass',
+  trailing,
+  open,
+  query,
+  className,
+  ...rest
+}: {
+  label: string;
+  backLabel: string;
+  clearLabel: string;
+  emptyText: string;
+  results: SearchResult[];
+  leadingIcon?: string;
+  trailing?: ReactNode;
+  open?: boolean;
+  query?: string;
+  className?: string;
+} & Record<string, unknown>) {
+  const id = useId();
+  const view = `${id}-view`;
+  const list = `${id}-results`;
+  return (
+    <div className={[searchClass, className].filter(Boolean).join(' ')} data-search="" {...rest}>
+      {!open && (
+        <div className="search-bar">
+          <button
+            type="button"
+            className="search-bar-field"
+            aria-haspopup="dialog"
+            aria-expanded="false"
+            aria-controls={view}
+            data-search-open=""
+          >
+            <span className="search-bar-leading">
+              <Svg name={leadingIcon} size={24} />
+            </span>
+            <span className="search-bar-placeholder">{label}</span>
+          </button>
+          {trailing && <span className="search-bar-trailing">{trailing}</span>}
+        </div>
+      )}
+      <dialog id={view} className="search-view" aria-label={label} open={open} data-search-view="">
+        <div className="search-view-header">
+          <IconButton icon="arrow-left" label={backLabel} data-search-close="" />
+          <input
+            type="search"
+            className="search-view-input"
+            role="combobox"
+            aria-label={label}
+            aria-expanded="true"
+            aria-controls={list}
+            aria-autocomplete="list"
+            autoComplete="off"
+            enterKeyHint="search"
+            placeholder={label}
+            defaultValue={query}
+            data-search-input=""
+          />
+          <IconButton icon="x" label={clearLabel} className="search-view-clear" data-search-clear="" />
+        </div>
+        <List id={list} role="listbox" aria-label={label} className="search-view-results">
+          {results.map((r, i) => (
+            <ListItem
+              key={i}
+              href={r.href}
+              leading={r.icon ? <Svg name={r.icon} size={24} /> : undefined}
+              headline={r.headline}
+              supporting={r.supporting}
+              presentation
+              role="option"
+              id={`${list}-${i}`}
+              aria-selected="false"
+              data-search-option=""
+            />
+          ))}
+        </List>
+        <p className="search-view-empty" hidden data-search-empty="">
+          {emptyText}
+        </p>
+      </dialog>
+    </div>
+  );
+}
+
+/** The search bar alone, searching in place (the editor's lists, narrowed as it is written in): the bar with its
+ * leading icon and a field (an <input type="search">, `label` its name and placeholder) instead of the button that opens
+ * the view. Other attributes (`value`, `onChange`, `ref`) go on the <input>, and `className` on the bar. */
+export function SearchBar({
+  label,
+  leadingIcon = 'magnifying-glass',
+  className,
+  ...rest
+}: { label: string; leadingIcon?: string; className?: string } & Record<string, unknown>) {
+  return (
+    <label className={['search-bar', className].filter(Boolean).join(' ')}>
+      <span className="search-bar-field">
+        <span className="search-bar-leading">
+          <Svg name={leadingIcon} size={24} />
+        </span>
+        <input type="search" className="search-bar-input" aria-label={label} placeholder={label} {...rest} />
+      </span>
+    </label>
+  );
+}