@ghxstship/xos-ui 0.0.0-stage → 4.16.0

package/src/Pickers/Pickers.shared.tsx

@@ -0,0 +1,337 @@
+import { useEffect, useMemo, useRef, useState, type KeyboardEvent } from "react";
+import { Direction, Popover as RPopover } from "radix-ui";
+import type { Option } from "../types/reference";
+import { cx } from "../lib/cx.ts";
+import { useLocale, usePreferences, useT } from "../lib/context.tsx";
+import { monthCells, monthTitle, parseIso, toIso, weekStart, weekdayNames } from "../lib/format.ts";
+import { Icon } from "../Icon/Icon.tsx";
+import { iconButtonClass } from "../Button/Button.tsx";
+import { controlClass } from "../Field/Field.tsx";
+import { popoverPanelClass } from "../Overlays/Overlays.tsx";
+import { type GridProps, type ListState } from "./Pickers.types.ts";
+import { rankOptions } from "./rankOptions.tsx";
+
+// A picker's list opens above whatever holds the field, a dialog or a side peek among them (z-dialog, z-peek), or it
+// shows behind its own dialog and no option can be pressed.
+export const listboxClass = cx(
+  popoverPanelClass,
+  "z-command p-4 max-h-(--ui-listbox-max) overflow-y-auto w-(--radix-popover-trigger-width)",
+);
+
+export const optionClass = cx(
+  "flex items-center gap-8 min-h-control-lg px-8 py-4 rounded-control cursor-pointer",
+  "aria-selected:font-medium data-[active=true]:bg-bg-hover hover:bg-bg-hover pointer-coarse:min-h-target-coarse",
+);
+
+export function OptionBody({ option, selected }: { option: Option; selected: boolean }) {
+  return (
+    <>
+      {option.icon ? <Icon name={option.icon} size={14} /> : null}
+      <span className="flex-1 min-w-0">{option.label}</span>
+      {option.code ? (
+        <span className="flex-none font-mono text-text-12 text-text-secondary">{option.code}</span>
+      ) : null}
+      {selected ? (
+        <span className="text-accent">
+          <Icon name="Check" size={14} />
+        </span>
+      ) : null}
+    </>
+  );
+}
+
+export function useList(options: Option[], defaultOpen: boolean | undefined): ListState {
+  const [query, setQuery] = useState("");
+  const [open, setOpen] = useState(Boolean(defaultOpen));
+  const [active, setActive] = useState(0);
+  const list = useMemo(() => rankOptions(options, query), [options, query]);
+  return {
+    query,
+    setQuery,
+    open,
+    setOpen,
+    active: Math.min(active, Math.max(0, list.length - 1)),
+    setActive,
+    list,
+  };
+}
+
+export function listKeys(
+  e: KeyboardEvent<HTMLInputElement>,
+  s: ListState,
+  pick: (o: Option) => void,
+): boolean {
+  if (e.key === "ArrowDown") {
+    e.preventDefault();
+    if (!s.open) s.setOpen(true);
+    else s.setActive(Math.min(s.active + 1, s.list.length - 1));
+    return true;
+  }
+  if (e.key === "ArrowUp") {
+    e.preventDefault();
+    s.setActive(Math.max(s.active - 1, 0));
+    return true;
+  }
+  if (e.key === "Home" && s.open) {
+    e.preventDefault();
+    s.setActive(0);
+    return true;
+  }
+  if (e.key === "End" && s.open) {
+    e.preventDefault();
+    s.setActive(s.list.length - 1);
+    return true;
+  }
+  if (e.key === "Enter" && s.open) {
+    const option = s.list[s.active];
+    if (option) {
+      e.preventDefault();
+      pick(option);
+    }
+    return true;
+  }
+  if (e.key === "Escape" && s.open) {
+    e.preventDefault();
+    s.setOpen(false);
+    return true;
+  }
+  return false;
+}
+
+export function Listbox({
+  id,
+  state,
+  isSelected,
+  pick,
+  multiselectable = false,
+  noMatch,
+}: {
+  id: string;
+  state: ListState;
+  isSelected: (o: Option) => boolean;
+  pick: (o: Option) => void;
+  multiselectable?: boolean;
+  noMatch: string;
+}) {
+  return (
+    <RPopover.Portal>
+      <RPopover.Content
+        sideOffset={4}
+        align="start"
+        collisionPadding={16}
+        onOpenAutoFocus={(e) => e.preventDefault()}
+        onCloseAutoFocus={(e) => e.preventDefault()}
+        onInteractOutside={(e) => {
+          if ((e.target as HTMLElement | null)?.closest?.(`[data-combobox="${id}"]`))
+            e.preventDefault();
+        }}
+        role="presentation"
+        className={listboxClass}
+      >
+        <div role="listbox" id={`${id}-list`} aria-multiselectable={multiselectable || undefined}>
+          {state.list.map((o, i) => (
+            <div
+              key={o.value}
+              id={`${id}-opt-${i}`}
+              role="option"
+              aria-selected={isSelected(o)}
+              data-active={i === state.active}
+              onMouseDown={(e) => {
+                e.preventDefault();
+                pick(o);
+              }}
+              onMouseEnter={() => state.setActive(i)}
+              className={optionClass}
+            >
+              <OptionBody option={o} selected={isSelected(o)} />
+            </div>
+          ))}
+        </div>
+        {state.list.length === 0 ? (
+          <p className="m-0 px-8 py-8 text-text-secondary">{noMatch}</p>
+        ) : null}
+      </RPopover.Content>
+    </RPopover.Portal>
+  );
+}
+
+export function shiftIso(iso: string, days: number): string {
+  const { y, m, d } = parseIso(iso);
+  const date = new Date(y, m, d + days);
+  return toIso(date.getFullYear(), date.getMonth(), date.getDate());
+}
+
+export function shiftMonth(iso: string, months: number): string {
+  const { y, m, d } = parseIso(iso);
+  const last = new Date(y, m + months + 1, 0).getDate();
+  const date = new Date(y, m + months, Math.min(d, last));
+  return toIso(date.getFullYear(), date.getMonth(), date.getDate());
+}
+
+/**
+ * The date grid of the APG date picker dialog: arrows move a day or a week, Page Up and Page Down a
+ * month, Home and End the week, Enter or Space picks.
+ */
+export function MonthGrid({ year, month, focused, onFocusDate, onPick, mark }: GridProps) {
+  const locale = useLocale();
+  const { weekStart: firstDay } = usePreferences();
+  const dir = Direction.useDirection();
+  const refs = useRef(new Map<string, HTMLButtonElement>());
+  const title = monthTitle(locale, year, month);
+  useEffect(() => {
+    refs.current.get(focused)?.focus();
+  }, [focused]);
+  const onKeyDown = (e: KeyboardEvent<HTMLButtonElement>, iso: string) => {
+    const ahead = dir === "rtl" ? "ArrowLeft" : "ArrowRight";
+    const behind = dir === "rtl" ? "ArrowRight" : "ArrowLeft";
+    const { y, m, d } = parseIso(iso);
+    const dow = (new Date(y, m, d).getDay() - weekStart(locale, firstDay) + 7) % 7;
+    const next =
+      e.key === ahead
+        ? shiftIso(iso, 1)
+        : e.key === behind
+          ? shiftIso(iso, -1)
+          : e.key === "ArrowDown"
+            ? shiftIso(iso, 7)
+            : e.key === "ArrowUp"
+              ? shiftIso(iso, -7)
+              : e.key === "PageDown"
+                ? shiftMonth(iso, e.shiftKey ? 12 : 1)
+                : e.key === "PageUp"
+                  ? shiftMonth(iso, e.shiftKey ? -12 : -1)
+                  : e.key === "Home"
+                    ? shiftIso(iso, -dow)
+                    : e.key === "End"
+                      ? shiftIso(iso, 6 - dow)
+                      : null;
+    if (next) {
+      e.preventDefault();
+      onFocusDate(next);
+    }
+  };
+  return (
+    <table role="grid" aria-label={title} className="border-collapse">
+      <thead>
+        <tr>
+          {weekdayNames(locale, firstDay).map((d) => (
+            <th
+              key={d}
+              scope="col"
+              className="h-control-sm text-text-11 font-medium text-text-tertiary"
+            >
+              {d}
+            </th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {monthCells(locale, year, month, firstDay).map((week, wi) => (
+          <tr key={wi}>
+            {week.map((d, di) => {
+              if (d === null) return <td key={di} />;
+              const iso = toIso(year, month, d);
+              const state = mark(iso);
+              return (
+                <td key={di} className="p-0 text-center">
+                  <button
+                    ref={(el) => {
+                      if (el) refs.current.set(iso, el);
+                      else refs.current.delete(iso);
+                    }}
+                    type="button"
+                    tabIndex={iso === focused ? 0 : -1}
+                    aria-pressed={state === "selected" || state === "edge"}
+                    aria-current={state === "today" ? "date" : undefined}
+                    onClick={() => onPick(iso)}
+                    onKeyDown={(e) => onKeyDown(e, iso)}
+                    className={cx(
+                      "w-(--ui-day-inline) h-(--ui-day-block) rounded-control border-0 bg-transparent cursor-pointer tabular-nums text-text-13",
+                      "hover:bg-bg-hover pointer-coarse:min-h-target-coarse",
+                      state === "today" &&
+                        "ring-(length:--stroke-width-hairline) ring-inset ring-border-strong",
+                      (state === "selected" || state === "edge") &&
+                        "bg-accent text-accent-text-on font-semibold hover:bg-accent",
+                      state === "range" && "bg-bg-hover rounded-none",
+                    )}
+                  >
+                    {d}
+                  </button>
+                </td>
+              );
+            })}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+export function CalendarPanel({
+  label,
+  initial,
+  mark,
+  onPick,
+}: {
+  label: string;
+  initial: string;
+  mark: GridProps["mark"];
+  onPick: (iso: string) => void;
+}) {
+  const t = useT();
+  const locale = useLocale();
+  const [focused, setFocused] = useState(initial);
+  const { y, m } = parseIso(focused);
+  return (
+    <RPopover.Portal>
+      <RPopover.Content
+        role="dialog"
+        aria-label={label}
+        sideOffset={4}
+        align="start"
+        collisionPadding={16}
+        onOpenAutoFocus={(e) => e.preventDefault()}
+        className={cx(popoverPanelClass, "z-popover p-8")}
+      >
+        <div className="flex items-center justify-between gap-8 pb-8">
+          <button
+            type="button"
+            className={iconButtonClass()}
+            aria-label={t("date.prevMonth")}
+            onClick={() => setFocused(shiftMonth(focused, -1))}
+          >
+            <Icon name="ChevronLeft" />
+          </button>
+          <strong className="font-semibold" aria-live="polite">
+            {monthTitle(locale, y, m)}
+          </strong>
+          <button
+            type="button"
+            className={iconButtonClass()}
+            aria-label={t("date.nextMonth")}
+            onClick={() => setFocused(shiftMonth(focused, 1))}
+          >
+            <Icon name="ChevronRight" />
+          </button>
+        </div>
+        <MonthGrid
+          year={y}
+          month={m}
+          focused={focused}
+          onFocusDate={setFocused}
+          onPick={onPick}
+          mark={mark}
+        />
+      </RPopover.Content>
+    </RPopover.Portal>
+  );
+}
+
+export const triggerClass = cx(
+  controlClass,
+  "flex items-center gap-8 w-full text-start cursor-pointer [&_svg]:text-text-secondary",
+);
+
+export function todayIso(): string {
+  const now = new Date();
+  return toIso(now.getFullYear(), now.getMonth(), now.getDate());
+}

package/src/Pickers/Pickers.tsx

@@ -0,0 +1,17 @@
+export {
+  type ComboboxProps,
+  type MultiSelectProps,
+  type SliderProps,
+  type DatePickerProps,
+  type DateRangePickerProps,
+  type TimePickerProps,
+  type FileDropProps,
+} from "./Pickers.types.ts";
+export { rankOptions } from "./rankOptions.tsx";
+export { Combobox } from "./Combobox.tsx";
+export { MultiSelect } from "./MultiSelect.tsx";
+export { Slider } from "./Slider.tsx";
+export { DatePicker } from "./DatePicker.tsx";
+export { DateRangePicker } from "./DateRangePicker.tsx";
+export { TimePicker } from "./TimePicker.tsx";
+export { FileDrop } from "./FileDrop.tsx";

package/src/Pickers/Pickers.types.ts

@@ -0,0 +1,47 @@
+import type {
+  ComboboxProps as ReferenceComboboxProps,
+  DatePickerProps as ReferenceDatePickerProps,
+  DateRangePickerProps as ReferenceDateRangePickerProps,
+  FileDropProps as ReferenceFileDropProps,
+  MultiSelectProps as ReferenceMultiSelectProps,
+  Option,
+  SliderProps as ReferenceSliderProps,
+  TimePickerProps as ReferenceTimePickerProps,
+} from "../types/reference";
+
+export type ComboboxProps = ReferenceComboboxProps & {
+  id?: string;
+  /** Called with each typed query, for a list searched on the server (the options then follow the results). */
+  onQueryChange?: (query: string) => void;
+};
+
+export type MultiSelectProps = ReferenceMultiSelectProps & { id?: string };
+
+export type SliderProps = ReferenceSliderProps & { id?: string };
+
+export type DatePickerProps = ReferenceDatePickerProps & { id?: string };
+
+export type DateRangePickerProps = ReferenceDateRangePickerProps & { id?: string };
+
+export type TimePickerProps = ReferenceTimePickerProps & { id?: string; name?: string };
+
+export type FileDropProps = ReferenceFileDropProps & { id?: string };
+
+export interface ListState {
+  query: string;
+  setQuery: (q: string) => void;
+  open: boolean;
+  setOpen: (o: boolean) => void;
+  active: number;
+  setActive: (n: number) => void;
+  list: Option[];
+}
+
+export interface GridProps {
+  year: number;
+  month: number;
+  focused: string;
+  onFocusDate: (iso: string) => void;
+  onPick: (iso: string) => void;
+  mark: (iso: string) => "selected" | "edge" | "range" | "today" | null;
+}

package/src/Pickers/Slider.tsx

@@ -0,0 +1,59 @@
+import { useState, type ReactElement } from "react";
+import { Slider as RSlider } from "radix-ui";
+import { useFormat, useT } from "../lib/context.tsx";
+import { fieldClass, labelClass, useFieldId } from "../Field/Field.tsx";
+import { type SliderProps } from "./Pickers.types.ts";
+
+/** A value in a bounded range on Radix Slider, always showing the current value beside its label. */
+export function Slider({
+  label,
+  min,
+  max,
+  step = 1,
+  value,
+  unit,
+  onChange,
+  id,
+}: SliderProps): ReactElement {
+  const t = useT();
+  const fieldId = useFieldId(id);
+  const fmt = useFormat();
+  const [current, setCurrent] = useState(value);
+  const shown = unit
+    ? t("slider.value", { value: fmt.number(current), unit })
+    : fmt.number(current);
+  return (
+    <div className={fieldClass}>
+      <div className="flex justify-between text-text-12">
+        <span id={`${fieldId}-label`} className={labelClass}>
+          {label}
+        </span>
+        <output htmlFor={fieldId} className="tabular-nums text-text-secondary">
+          {shown}
+        </output>
+      </div>
+      <RSlider.Root
+        min={min}
+        max={max}
+        step={step}
+        value={[current]}
+        onValueChange={([v]) => {
+          if (v === undefined) return;
+          setCurrent(v);
+          onChange?.(v);
+        }}
+        className="relative flex items-center h-control-md touch-none select-none pointer-coarse:min-h-target-coarse"
+      >
+        <RSlider.Track className="relative grow h-(--space-4) rounded-pill bg-bg-hover overflow-hidden">
+          <RSlider.Range className="absolute h-full bg-accent" />
+        </RSlider.Track>
+        <RSlider.Thumb
+          id={fieldId}
+          aria-labelledby={`${fieldId}-label`}
+          aria-valuetext={shown}
+          className="block size-(--space-16) rounded-full bg-text-primary ring-(length:--stroke-width-focus) ring-bg-canvas cursor-grab"
+        />
+      </RSlider.Root>
+    </div>
+  );
+}

package/src/Pickers/TimePicker.tsx

@@ -0,0 +1,68 @@
+import { useMemo, type ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { useLocale } from "../lib/context.tsx";
+import { formatTimeOfDay } from "../lib/format.ts";
+import { Icon } from "../Icon/Icon.tsx";
+import { chipClass } from "../Chips/Chips.tsx";
+import { Field, controlClass, useFieldId } from "../Field/Field.tsx";
+import { type TimePickerProps } from "./Pickers.types.ts";
+
+/**
+ * A time of day with the venue time zone always beside it. The contract keeps a native select change
+ * event; times read in the locale's format (12-hour with AM and PM in en-US).
+ */
+export function TimePicker({
+  label,
+  help,
+  value,
+  step = 15,
+  timeZone,
+  zoneLabel,
+  onChange,
+  id,
+  name,
+}: TimePickerProps): ReactElement {
+  const locale = useLocale();
+  const fieldId = useFieldId(id);
+  const options = useMemo(() => {
+    const out: { value: string; label: string }[] = [];
+    for (let mins = 0; mins < 1440; mins += step) {
+      const h = Math.floor(mins / 60);
+      const m = mins % 60;
+      out.push({
+        value: `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}`,
+        label: formatTimeOfDay(locale, h, m),
+      });
+    }
+    return out;
+  }, [locale, step]);
+  return (
+    <Field id={fieldId} label={label} help={help}>
+      <div className="flex items-center gap-6">
+        <div className="relative flex-1">
+          <select
+            id={fieldId}
+            name={name}
+            defaultValue={value}
+            onChange={onChange}
+            aria-describedby={`${fieldId}-zone${help ? ` ${fieldId}-help` : ""}`}
+            className={cx(controlClass, "appearance-none w-full pe-24")}
+          >
+            {options.map((o) => (
+              <option key={o.value} value={o.value}>
+                {o.label}
+              </option>
+            ))}
+          </select>
+          <span className="pointer-events-none absolute inset-y-0 end-8 flex items-center text-text-tertiary">
+            <Icon name="Clock" size={14} />
+          </span>
+        </div>
+        <span id={`${fieldId}-zone`} title={timeZone} className={chipClass}>
+          <Icon name="Globe" size={12} />
+          {zoneLabel}
+        </span>
+      </div>
+    </Field>
+  );
+}

package/src/Pickers/rankOptions.tsx

@@ -0,0 +1,12 @@
+import { defaultFilter } from "cmdk";
+import type { Option } from "../types/reference";
+
+/** Ranks options against a query with cmdk's fuzzy score; an empty query keeps the given order. */
+export function rankOptions(options: Option[], query: string): Option[] {
+  if (!query.trim()) return options;
+  return options
+    .map((o) => ({ o, score: defaultFilter(`${o.label} ${o.code ?? ""}`, query) }))
+    .filter((r) => r.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .map((r) => r.o);
+}

package/src/Popover/README.md

@@ -0,0 +1,3 @@
+# Popover
+
+Popover holds more than one sentence of help, with a Learn more link; tooltips stay one sentence.

package/src/PresenceIndicator/README.md

@@ -0,0 +1,3 @@
+# PresenceIndicator
+
+PresenceIndicator shows who is viewing or editing a record live.

package/src/PriceDisplay/README.md

@@ -0,0 +1,7 @@
+# PriceDisplay
+
+PriceDisplay prints one price with its billing period and tax label.
+
+Amounts format with the page locale and currency, with no decimals on whole amounts. `taxMode` prints the tax label for the visitor's region: exclusive for United States business pricing, inclusive where consumer price rules require the total. A plan sold by quote passes `from` with its starting price.
+
+The silence rule holds: a `null` amount is unpriced and renders Quoted, never zero. Zero is a claim, used only for a plan that is free.

package/src/PricingTable/README.md

@@ -0,0 +1,9 @@
+# PricingTable
+
+PricingTable shows the plans side by side with a monthly and annual billing toggle.
+
+The toggle is a SegmentedControl, and a polite live region announces each change. Prices render through PriceDisplay, so tax labels and the silence rule apply. `terms` prints renewal, trial and cancellation terms with the plans, before anyone leaves the page. One plan may be marked `recommended`; nothing is preselected or pre-checked, and no countdown or scarcity copy belongs here.
+
+From bp-lg the plans sit in one row. Below it they become a snapped horizontal list, with each plan's button reachable by keyboard.
+
+The consumer provides plans from the plan registry (`packages/schemas/plans.yaml`); prices never come from anywhere else. Show only currencies of open territories.

package/src/ProfileEditor/README.md

@@ -0,0 +1,3 @@
+# ProfileEditor
+
+ProfileEditor sets each field's visibility: Private, Shared on application (On Apply) or Public, with a profile strength meter naming the next step.

package/src/ProgressBar/README.md

@@ -0,0 +1,3 @@
+# ProgressBar
+
+ProgressBar shows determinate progress with its percentage in tabular numerals.

package/src/ProofStatStrip/README.md

@@ -0,0 +1,7 @@
+# ProofStatStrip
+
+ProofStatStrip shows a row of verifiable figures, each linked to the file that proves it.
+
+Figures use tabular numerals and format with the page locale. Every figure on a public page comes from the repository or the canon and carries a `source`, so a reader or an answer engine can check it. Use three to five figures; they sit in one row from bp-lg, two columns from bp-sm and one column below.
+
+The consumer provides the value, a short label and the source link. Never use a figure that has no source.

package/src/PropertyChip/README.md

@@ -0,0 +1,3 @@
+# PropertyChip
+
+PropertyChip shows one record property inline and edits it in place when clickable.

package/src/ProvenanceBadge/README.md

@@ -0,0 +1,3 @@
+# ProvenanceBadge
+
+ProvenanceBadge shows who wrote a canon field and the provenance rank (human 100, operator 80, imported 60, agent 40, provider 20).

package/src/QRCode/README.md

@@ -0,0 +1,6 @@
+# QRCode
+
+QRCode renders a scannable code as SVG, always dark on a light quiet zone so scanners read it in every theme.
+
+- Used by CredentialBadge and the Continue on another device handoff.
+- Generated by qrcode-generator 1.4.4 (MIT), shipped in `components/lib`.

package/src/QuickAdd/README.md

@@ -0,0 +1,5 @@
+# QuickAdd
+
+QuickAdd parses date phrases, @person, #tag, /kind and ~scope into chips before saving.
+
+- `XOS.parseQuickAdd(text)` exposes the same parser.

package/src/QuickIncidentSheet/README.md

@@ -0,0 +1,3 @@
+# QuickIncidentSheet
+
+QuickIncidentSheet is step one of the three-step incident report: type, confirmed location, then photos or voice note.

package/src/Radio/README.md

@@ -0,0 +1,3 @@
+# Radio
+
+Radio picks exactly one of two to five visible options; use Select for more.

package/src/RadioChannelTable/README.md

@@ -0,0 +1,7 @@
+# RadioChannelTable
+
+RadioChannelTable lists the radio plan by zone and channel, available offline in Compass.
+
+- Rows always sort by zone, then channel, in numeric order; the component enforces this.
+- Content comes from the org's copy of the XOS Standard Library Radio Channels. The preview shows six of its 32 rows verbatim.
+- Notes wrap so the plan reads on a phone without sideways scrolling.

package/src/RatingDialog/README.md

@@ -0,0 +1,3 @@
+# RatingDialog
+
+RatingDialog collects a two-sided rating after close-out; both ratings release together.

package/src/ReconciliationTable/README.md

@@ -0,0 +1,3 @@
+# ReconciliationTable
+
+ReconciliationTable compares requirements with venue capability as Met, Gap or Unknown; an Unknown against a critical requirement is a gap at Gate 3.

package/src/RecordKindChip/README.md

@@ -0,0 +1,3 @@
+# RecordKindChip
+
+RecordKindChip shows a record kind as its glyph and name.