@ghxstship/xos-ui 0.0.0-stage → 4.16.0

package/src/Editing/QuickAddChips.tsx

@@ -0,0 +1,180 @@
+import { useEffect, useState, type ReactElement } from "react";
+import { useLocale, useT } from "../lib/context.tsx";
+import { formatList } from "../lib/format.ts";
+import { Icon } from "../Icon/Icon.tsx";
+import { chipClass } from "../Chips/Chips.tsx";
+import { RecordKindGlyph } from "../Glyphs/Glyphs.tsx";
+import { isRecordKind } from "@xos/icons/glyphs";
+import {
+  finalizeQuickAdd,
+  quickAddKey,
+  quickAddSigil,
+  type QuickAddParse,
+  type QuickAddResolution,
+  type QuickAddToken,
+  type QuickAddTokenType,
+} from "./quickAddCore.ts";
+
+/**
+ * Sentences of a quick add line, from the app's own catalog. The shared `ui` catalog ships in every
+ * page's first JavaScript, so quick add adds none to it (ADR 0073); without these, chips are named as
+ * typed and the announcement lists the title and the chips.
+ */
+export interface QuickAddCopy {
+  /** Names a chip by what it sets, such as "Owner: Dana Kim". */
+  field?: (name: string, value: string) => string;
+  /** What is announced once typing pauses, such as "Hang truss, with Owner: Dana Kim". */
+  announce?: (title: string, fields: string) => string;
+  /** Names the list of an ambiguous token's candidates, such as "Choose a match for ~open". */
+  choose?: (token: string) => string;
+  /** The list's entry before a candidate is chosen, such as "Matches: 2". */
+  matches?: (count: number) => string;
+}
+
+export interface QuickAddChipsProps {
+  parse: QuickAddParse;
+  /** Resolutions by token key; without them every token shows as typed. */
+  resolutions?: Readonly<Record<string, QuickAddResolution>>;
+  /** Candidates chosen for ambiguous tokens, by token key. */
+  choices?: Readonly<Record<string, string>>;
+  /** Gives each chip a remove button that turns its token back into text. */
+  onDismiss?: (token: QuickAddToken) => void;
+  /** Called when the person picks one candidate of an ambiguous token. */
+  onChoose?: (token: QuickAddToken, id: string) => void;
+  /** What each kind of token sets, for chip names and the announcement, such as Owner or Due. */
+  labels?: Partial<Record<QuickAddTokenType, string>>;
+  copy?: QuickAddCopy;
+}
+
+/** A parsed day and time spoken in the person's language; the wall clock is formatted as is. */
+function spokenDate(locale: string, token: QuickAddToken): string {
+  const at = (iso: string, time?: string) => {
+    const [y = 1970, m = 1, d = 1] = iso.split("-").map(Number);
+    const [h = 0, mi = 0] = (time ?? "00:00").split(":").map(Number);
+    return new Date(Date.UTC(y, m - 1, d, h, mi));
+  };
+  const format = new Intl.DateTimeFormat(locale, {
+    weekday: "short",
+    month: "short",
+    day: "numeric",
+    timeZone: "UTC",
+    ...(token.time ? { hour: "numeric", minute: "2-digit" } : {}),
+  });
+  if (!token.iso) return token.value;
+  const start = at(token.iso, token.time);
+  return token.endIso
+    ? format.formatRange(start, at(token.endIso, token.endTime ?? token.time))
+    : format.format(start);
+}
+
+/**
+ * The chips of a quick add line (Section 11.7): the title as it will save, then one chip per token,
+ * named by what it sets. A token the app could not resolve stays in the title; one with several
+ * matches offers them in a list. Remove buttons and lists are reachable with Tab. A status region
+ * announces the result once typing pauses.
+ */
+export function QuickAddChips({
+  parse,
+  resolutions,
+  choices = {},
+  onDismiss,
+  onChoose,
+  labels = {},
+  copy = {},
+}: QuickAddChipsProps): ReactElement {
+  const t = useT();
+  const locale = useLocale();
+  // Tokens still waiting for an answer show as typed, so the title does not jump while it comes.
+  const shown: Record<string, QuickAddResolution> = {};
+  const chips = parse.tokens.filter((token) => {
+    if (token.type === "date" || resolutions === undefined) return true;
+    const key = quickAddKey(token);
+    const resolution = resolutions[key] ?? { status: "resolved", id: key, label: token.value };
+    shown[key] = resolution;
+    return resolution.status !== "unresolved";
+  });
+  const preview = finalizeQuickAdd(parse, resolutions === undefined ? undefined : shown, choices);
+  const title = preview.title || t("record.untitled");
+  const typed = (token: QuickAddToken) => `${quickAddSigil(token.type)}${token.value}`;
+  const valueOf = (token: QuickAddToken) =>
+    token.type === "date"
+      ? spokenDate(locale, token)
+      : (preview.tokens.find((p) => p.type === token.type)?.label ?? token.value);
+  /** A chip's name: what it sets and its value when the app names them, else its value as typed. */
+  const fieldOf = (token: QuickAddToken, value: string) => {
+    const name = labels[token.type];
+    if (name && copy.field) return copy.field(name, value);
+    return token.type === "date" || value !== token.value ? value : typed(token);
+  };
+
+  const summary = preview.tokens.map((token) => fieldOf(token, valueOf(token)));
+  const message =
+    summary.length === 0
+      ? title
+      : (copy.announce?.(title, formatList(locale, summary)) ??
+        formatList(locale, [title, ...summary]));
+  const [spoken, setSpoken] = useState("");
+  useEffect(() => {
+    const timer = setTimeout(() => setSpoken(message), 600);
+    return () => clearTimeout(timer);
+  }, [message]);
+
+  return (
+    <div className="flex flex-wrap items-center gap-4">
+      <span className="me-4 font-medium">{title}</span>
+      {chips.map((token) => {
+        const key = quickAddKey(token);
+        const resolution = shown[key];
+        const candidates = resolution?.status === "ambiguous" ? resolution.candidates : null;
+        const chosen = candidates?.find((c) => c.id === choices[key]);
+        const resolved = resolution?.status === "resolved" ? resolution : null;
+        const text =
+          chosen?.label ?? (resolved && resolved.id !== key ? resolved.label : token.value);
+        const kind = resolved && resolved.id !== key ? resolved.id : token.value;
+        const detail = token.type === "date" ? spokenDate(locale, token) : resolved?.detail;
+        return (
+          <span key={key} className={chipClass} {...(detail ? { title: detail } : {})}>
+            <Icon name={token.icon} size={12} color="var(--color-text-secondary)" />
+            {token.type === "kind" && isRecordKind(kind) ? (
+              <RecordKindGlyph kind={kind} size={12} />
+            ) : null}
+            {candidates && !chosen ? (
+              <select
+                aria-label={copy.choose?.(typed(token)) ?? typed(token)}
+                value=""
+                onChange={(e) => onChoose?.(token, e.target.value)}
+                className="xos-hit max-w-full border-0 bg-transparent text-inherit cursor-pointer"
+              >
+                <option value="">
+                  {copy.matches?.(candidates.length) ?? `${token.value} (${candidates.length})`}
+                </option>
+                {candidates.map((c) => (
+                  <option key={c.id} value={c.id}>
+                    {c.detail ? `${c.label} · ${c.detail}` : c.label}
+                  </option>
+                ))}
+              </select>
+            ) : (
+              text
+            )}
+            {onDismiss ? (
+              <button
+                type="button"
+                aria-label={t("chip.remove", {
+                  label: fieldOf(token, chosen?.label ?? valueOf(token)),
+                })}
+                onClick={() => onDismiss(token)}
+                className="xos-hit inline-grid place-items-center ms-2 p-0 border-0 bg-transparent text-text-tertiary hover:text-text-primary rounded-mark cursor-pointer"
+              >
+                <Icon name="X" size={12} />
+              </button>
+            ) : null}
+          </span>
+        );
+      })}
+      <span role="status" className="sr-only">
+        {spoken}
+      </span>
+    </div>
+  );
+}

package/src/Editing/contrastRatio.tsx

@@ -0,0 +1,11 @@
+import { composite, ratio } from "@xos/tokens/ratio";
+
+/** WCAG 2.2 contrast ratio between two hex colors: the @xos/tokens contrast gate arithmetic itself. */
+export function contrastRatio(a: string, b: string): number {
+  return ratio(a, b);
+}
+
+/** A fill with an overlay over it (a hover or pressed state), composited as the contrast gate does. */
+export function overlaid(fill: string, overlay: string, opacity: number): string {
+  return composite(fill, overlay, opacity);
+}

package/src/Editing/parseQuickAdd.tsx

@@ -0,0 +1,187 @@
+import * as en from "chrono-node/en";
+import * as es from "chrono-node/es";
+import {
+  addDays,
+  quickAddKey,
+  tidyTitle,
+  wallClockAt,
+  zoneOffsetMinutes,
+  type QuickAddParse,
+  type QuickAddSpan,
+  type QuickAddTokenType,
+} from "./quickAddCore.ts";
+
+export interface QuickAddOptions {
+  /** The moment relative phrases count from ("tomorrow", "next Friday"); now by default. */
+  referenceDate?: Date;
+  /** The language of the date phrases: Spanish for `es-*` (chrono's Spanish parser), English otherwise. */
+  locale?: string;
+  /** The IANA zone whose calendar and clock the phrases are read on; the device's by default. */
+  timeZone?: string;
+  /** Keys (`quickAddKey`) of tokens the person turned back into text. */
+  dismissed?: readonly string[];
+}
+
+const ICONS: Readonly<Record<QuickAddTokenType, string>> = {
+  person: "User",
+  tag: "Hash",
+  kind: "Shapes",
+  scope: "MapPin",
+  date: "Calendar",
+};
+
+const SIGIL_TYPES: Readonly<Record<string, QuickAddTokenType>> = {
+  "@": "person",
+  "#": "tag",
+  "/": "kind",
+  "~": "scope",
+};
+
+// A token starts the line or follows white space, so dana@example.com, and/or and w/crew stay text.
+const TOKEN = /(^|\s)([@#/~])([\p{L}\p{N}][\p{L}\p{N}_.-]*)/gu;
+const URID = /^\d{4}\.\d{2}\.\d{2}$/;
+
+/** Whether a sigil's text names something of its type: people, tags and kinds start with a letter. */
+function accepts(type: QuickAddTokenType, body: string): boolean {
+  if (body === "") return false;
+  if (type === "tag") return /^\p{L}/u.test(body) || URID.test(body);
+  if (type === "kind") return /^\p{L}[\p{L}-]*$/u.test(body);
+  if (type === "person") return /^\p{L}/u.test(body);
+  return true;
+}
+
+// Short words chrono reads as days or months that are ordinary words too ("Sun stage wash",
+// "sat down", "limpiar mar"): alone they stay text; "Sun 8am" or "mar 3" still parse.
+const AMBIGUOUS: Readonly<Record<"en" | "es", ReadonlySet<string>>> = {
+  en: new Set([
+    ...["sun", "sat", "wed", "mar", "jan", "april", "may", "june", "august"],
+    ...["morning", "afternoon", "evening", "night"],
+  ]),
+  es: new Set(["mar", "dom", "sol", "mayo"]),
+};
+
+// The word just before a date that only joins it to the title ("Hang truss by Friday", "el viernes").
+const CONNECTORS: Readonly<Record<"en" | "es", ReadonlySet<string>>> = {
+  en: new Set(["at", "on", "by", "due", "for", "from"]),
+  es: new Set(["el", "la", "a", "al", "para", "de", "del", "en", "desde"]),
+};
+
+// Phrases chrono stops short of: it reads only the last word, a day early.
+const DAY_AFTER: Readonly<Record<"en" | "es", RegExp>> = {
+  en: /\bday after\s+$/i,
+  es: /(^|\s)pasado\s+$/i,
+};
+
+interface DatePart {
+  iso: string;
+  time?: string;
+}
+
+interface ChronoComponents {
+  get(component: "year" | "month" | "day" | "hour" | "minute"): number | null;
+  isCertain(component: "hour" | "timezoneOffset"): boolean;
+  date(): Date;
+}
+
+function pad(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+/** The day, and the time when one was named, on the zone's calendar. */
+function datePart(c: ChronoComponents, zone: string): DatePart {
+  if (c.isCertain("timezoneOffset")) {
+    // "9pm EST" names its own zone: read the instant on the line's zone instead.
+    const w = wallClockAt(c.date(), zone);
+    return { iso: `${w.y}-${pad(w.m)}-${pad(w.d)}`, time: `${pad(w.h)}:${pad(w.mi)}` };
+  }
+  const iso = `${c.get("year")}-${pad(c.get("month") ?? 1)}-${pad(c.get("day") ?? 1)}`;
+  return c.isCertain("hour")
+    ? { iso, time: `${pad(c.get("hour") ?? 0)}:${pad(c.get("minute") ?? 0)}` }
+    : { iso };
+}
+
+/** A numeric date written in the other locale's order (24/10 in English, 10/24 in Spanish), or 24/7. */
+function wrongOrder(text: string, lang: "en" | "es"): boolean {
+  if (/^24\s*\/\s*7$/.test(text)) return true;
+  const numeric = /^(\d{1,2})[/.-](\d{1,2})(?:[/.-]\d{2,4})?$/.exec(text);
+  if (!numeric) return false;
+  const [first, second] = [Number(numeric[1]), Number(numeric[2])];
+  return lang === "en" ? first > 12 : second > 12;
+}
+
+function blank(text: string, index: number, length: number): string {
+  return text.slice(0, index) + " ".repeat(length) + text.slice(index + length);
+}
+
+/**
+ * Parses @person, #tag, /kind and ~scope tokens, then a date phrase with chrono-node ("tomorrow at
+ * 3pm", "next Friday", "viernes 8am"), read in the given language on the given zone's calendar. What
+ * remains is the title. A line sets one of each: a second person, tag, kind, scope or date stays in
+ * the title as typed, as does any token the person dismissed.
+ */
+export function parseQuickAdd(text: string, options: Date | QuickAddOptions = {}): QuickAddParse {
+  const opts: QuickAddOptions = options instanceof Date ? { referenceDate: options } : options;
+  const reference = opts.referenceDate ?? new Date();
+  const zone = opts.timeZone ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const lang: "en" | "es" = opts.locale?.toLowerCase().startsWith("es") ? "es" : "en";
+  const dismissed = new Set(opts.dismissed ?? []);
+  const tokens: QuickAddSpan[] = [];
+  const taken = new Set<QuickAddTokenType>();
+  // Every token's text is hidden from chrono, so ~friday is a scope and never a date.
+  let masked = text;
+  for (const match of text.matchAll(TOKEN)) {
+    const type = SIGIL_TYPES[match[2] ?? ""];
+    const body = (match[3] ?? "").replace(/[._-]+$/u, "");
+    if (type === undefined || !accepts(type, body)) continue;
+    const index = (match.index ?? 0) + (match[1] ?? "").length;
+    masked = blank(masked, index, body.length + 1);
+    const token = { type, value: body, icon: ICONS[type] };
+    if (taken.has(type) || dismissed.has(quickAddKey(token))) continue;
+    taken.add(type);
+    tokens.push({ ...token, index, length: body.length + 1 });
+  }
+
+  const chrono = lang === "es" ? es.casual : en.casual;
+  const at = { instant: reference, timezone: zoneOffsetMinutes(reference, zone) };
+  for (const result of chrono.parse(masked, at, { forwardDate: true })) {
+    let index = result.index;
+    let phrase = result.text;
+    let start = datePart(result.start, zone);
+    const before = DAY_AFTER[lang].exec(masked.slice(0, index));
+    if (before && /^(tomorrow|mañana)\b/i.test(phrase)) {
+      const extra = before[0].trimStart();
+      index -= extra.length;
+      phrase = text.slice(index, result.index + result.text.length);
+      start = { ...start, iso: addDays(start.iso, 1) };
+    }
+    if (wrongOrder(phrase.trim(), lang)) continue;
+    if (AMBIGUOUS[lang].has(phrase.trim().toLocaleLowerCase("en-US"))) continue;
+    const token = { type: "date" as const, value: phrase, icon: ICONS.date };
+    if (dismissed.has(quickAddKey(token))) continue;
+    const end = result.end ? datePart(result.end, zone) : null;
+    if (end && start.time && end.time && `${end.iso}T${end.time}` <= `${start.iso}T${start.time}`) {
+      // "10pm-6am" ends the next morning.
+      end.iso = addDays(start.iso, 1);
+    }
+    const lead = /(\S+)\s+$/u.exec(text.slice(0, index));
+    const connector = lead?.[1] && CONNECTORS[lang].has(lead[1].toLocaleLowerCase("en-US"));
+    const cut = connector && lead ? index - lead[0].length : index;
+    tokens.push({
+      ...token,
+      iso: start.iso,
+      ...(start.time ? { time: start.time } : {}),
+      ...(end ? { endIso: end.iso } : {}),
+      ...(end?.time ? { endTime: end.time } : {}),
+      index: cut,
+      length: index + phrase.length - cut,
+    });
+    break;
+  }
+
+  tokens.sort((a, b) => a.index - b.index);
+  let title = text;
+  for (const t of [...tokens].reverse()) {
+    title = `${title.slice(0, t.index)} ${title.slice(t.index + t.length)}`;
+  }
+  return { text, title: tidyTitle(title), tokens };
+}

package/src/Editing/quickAddCore.ts

@@ -0,0 +1,204 @@
+/**
+ * The parts of quick add (Section 11.7) that run anywhere, servers included: the token and result
+ * shapes, the key a resolution is filed under, folding the tokens an app could not resolve back into
+ * the title, and reading a wall-clock time in an IANA zone. `parseQuickAdd` (chrono-node) is the
+ * browser half; `@xos/ui/quick-add` exports only this file, so a server action never loads chrono.
+ */
+
+export type QuickAddTokenType = "person" | "tag" | "kind" | "scope" | "date";
+
+export interface QuickAddToken {
+  type: QuickAddTokenType;
+  /** The value without its sigil (`dana` for `@dana`); for a date, the phrase as typed. */
+  value: string;
+  icon: string;
+  /** For dates: the day as an ISO date, on the calendar of the zone the line was parsed in. */
+  iso?: string;
+  /** For dates that name a time of day: the time as HH:MM, 24-hour. */
+  time?: string;
+  /** For a range such as "Friday 8am-4pm": the day it ends. */
+  endIso?: string;
+  /** For a range that names its end time: the time as HH:MM, 24-hour. */
+  endTime?: string;
+  /** For a token the app resolved: the id of the person, tag, kind or scope it names. */
+  id?: string;
+  /** For a token the app resolved: the name to show. */
+  label?: string;
+}
+
+/** A token with where it sits in the typed line, so it can be cut out or left in place. */
+export interface QuickAddSpan extends QuickAddToken {
+  /** Offset of the text the token removes from the title, its leading "by" or "el" included. */
+  index: number;
+  length: number;
+}
+
+export interface QuickAddResult {
+  /** The line without the tokens it set; tokens nothing resolved stay in it as typed. */
+  title: string;
+  tokens: QuickAddToken[];
+}
+
+/** What `parseQuickAdd` reads from a line, before any token is resolved. */
+export interface QuickAddParse extends QuickAddResult {
+  text: string;
+  tokens: QuickAddSpan[];
+}
+
+export interface QuickAddCandidate {
+  id: string;
+  label: string;
+  /** Tells candidates with the same name apart, for example the project a scope belongs to. */
+  detail?: string;
+}
+
+/** How an app resolved one token: to one thing, to several it cannot choose between, or to nothing. */
+export type QuickAddResolution =
+  | { status: "resolved"; id: string; label: string; detail?: string }
+  | { status: "ambiguous"; candidates: QuickAddCandidate[] }
+  | { status: "unresolved" };
+
+/**
+ * Resolves people, tags, kinds and scopes against what the person may see, keyed by `quickAddKey`.
+ * A key the answer leaves out counts as unresolved.
+ */
+export type QuickAddResolver = (
+  tokens: readonly QuickAddToken[],
+) => Promise<Readonly<Record<string, QuickAddResolution>>>;
+
+const SIGILS: Readonly<Record<Exclude<QuickAddTokenType, "date">, string>> = {
+  person: "@",
+  tag: "#",
+  kind: "/",
+  scope: "~",
+};
+
+/** The sigil a token is typed with; dates have none. */
+export function quickAddSigil(type: QuickAddTokenType): string {
+  return type === "date" ? "" : SIGILS[type];
+}
+
+/** The key a token's resolution is filed under: its type and value, case and accents as typed folded. */
+export function quickAddKey(token: Pick<QuickAddToken, "type" | "value">): string {
+  return `${token.type}:${token.value.normalize("NFC").toLocaleLowerCase("en-US")}`;
+}
+
+/** A token without its place in the line. */
+function tokenOf(span: QuickAddSpan): QuickAddToken {
+  return Object.fromEntries(
+    Object.entries(span).filter(([key]) => key !== "index" && key !== "length"),
+  ) as unknown as QuickAddToken;
+}
+
+/** One space between words, none before punctuation a removed token left behind. */
+export function tidyTitle(text: string): string {
+  return text
+    .replace(/\s+/g, " ")
+    .replace(/\s+([,.;:!?])/g, "$1")
+    .replace(/^[,.;:!?]\s*/, "")
+    .trim();
+}
+
+/**
+ * The line a person typed as the app should save it. Dates always apply. Without resolutions every
+ * token applies; with them, a token applies when it resolved or the person chose one of its
+ * candidates, and any other token stays in the title exactly where it was typed.
+ */
+export function finalizeQuickAdd(
+  parse: QuickAddParse,
+  resolutions?: Readonly<Record<string, QuickAddResolution>>,
+  choices: Readonly<Record<string, string>> = {},
+): QuickAddResult {
+  const applied: { span: QuickAddSpan; token: QuickAddToken }[] = [];
+  for (const span of parse.tokens) {
+    const token = tokenOf(span);
+    if (token.type === "date" || resolutions === undefined) {
+      applied.push({ span, token });
+      continue;
+    }
+    const key = quickAddKey(token);
+    const resolution = resolutions[key];
+    if (resolution?.status === "resolved") {
+      applied.push({ span, token: { ...token, id: resolution.id, label: resolution.label } });
+    } else if (resolution?.status === "ambiguous") {
+      const chosen = resolution.candidates.find((c) => c.id === choices[key]);
+      if (chosen) applied.push({ span, token: { ...token, id: chosen.id, label: chosen.label } });
+    }
+  }
+  let title = parse.text;
+  for (const { span } of [...applied].sort((a, b) => b.span.index - a.span.index)) {
+    title = `${title.slice(0, span.index)} ${title.slice(span.index + span.length)}`;
+  }
+  return {
+    title: tidyTitle(title),
+    tokens: applied.sort((a, b) => a.span.index - b.span.index).map((a) => a.token),
+  };
+}
+
+interface WallClock {
+  y: number;
+  m: number;
+  d: number;
+  h: number;
+  mi: number;
+}
+
+const wallFormats = new Map<string, Intl.DateTimeFormat>();
+
+/** The wall clock in a zone at an instant. */
+export function wallClockAt(at: Date | number, zone: string): WallClock {
+  let format = wallFormats.get(zone);
+  if (format === undefined) {
+    format = new Intl.DateTimeFormat("en-US", {
+      timeZone: zone,
+      hourCycle: "h23",
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+    });
+    wallFormats.set(zone, format);
+  }
+  const parts = format.formatToParts(at);
+  const get = (type: string) => Number(parts.find((p) => p.type === type)?.value ?? 0);
+  return { y: get("year"), m: get("month"), d: get("day"), h: get("hour") % 24, mi: get("minute") };
+}
+
+/** Minutes the zone runs ahead of UTC at an instant (-240 for New York in summer). */
+export function zoneOffsetMinutes(at: Date | number, zone: string): number {
+  const ms = typeof at === "number" ? at : at.getTime();
+  const w = wallClockAt(ms, zone);
+  return Math.round(
+    (Date.UTC(w.y, w.m - 1, w.d, w.h, w.mi) - Math.floor(ms / 60_000) * 60_000) / 60_000,
+  );
+}
+
+/**
+ * The instant a wall-clock day and time name in a zone, as ISO. A time skipped by a daylight saving
+ * change reads as the same time after the change (2:30 on the spring-forward night is 3:30), and a
+ * time the fall-back night repeats reads as its first occurrence.
+ */
+export function zonedInstant(day: string, time: string, zone: string): string {
+  const [y = 1970, m = 1, d = 1] = day.split("-").map(Number);
+  const [h = 0, mi = 0] = time.split(":").map(Number);
+  const guess = Date.UTC(y, m - 1, d, h, mi);
+  const first = guess - zoneOffsetMinutes(guess, zone) * 60_000;
+  const second = guess - zoneOffsetMinutes(first, zone) * 60_000;
+  const wall = wallClockAt(second, zone);
+  return new Date(wall.h === h && wall.mi === mi ? second : first).toISOString();
+}
+
+/** A calendar day moved by whole days, as an ISO date. */
+export function addDays(day: string, days: number): string {
+  const [y = 1970, m = 1, d = 1] = day.split("-").map(Number);
+  return new Date(Date.UTC(y, m - 1, d + days)).toISOString().slice(0, 10);
+}
+
+// The schedule grid's time shorthand (B4) travels with quick add, so `@xos/ui/quick-add` carries both halves.
+export {
+  parseDuration,
+  parseTimeShorthand,
+  type TimeShorthand,
+  type TimeShorthandOptions,
+} from "./timeShorthand.ts";