@ghxstship/xos-ui 0.0.0-stage → 4.16.0

package/src/Feedback/RegionBoundary.tsx

@@ -0,0 +1,102 @@
+import { Component, type ErrorInfo, type ReactElement, type ReactNode } from "react";
+import { useT } from "../lib/context.tsx";
+import { Icon } from "../Icon/Icon.tsx";
+import { Button } from "../Button/Button.tsx";
+import { TONE_ICON, TONE_ICON_CLASS, alertClass } from "./Feedback.shared.tsx";
+
+export interface RegionBoundaryProps {
+  children: ReactNode;
+  /** Replaces the default title ("This section did not load"), for example with the tile's name. */
+  title?: string;
+  /** Called once per caught error, for the app's error reporting. Pass-through errors are not reported. */
+  onError?: (error: unknown, info: ErrorInfo) => void;
+  /**
+   * Retry calls this with `reset`, so the app can fetch the region again and clear the error in one
+   * step (a router refresh and `reset` in one transition). Without it, Retry calls `reset` alone.
+   */
+  onRetry?: (reset: () => void) => void;
+  /**
+   * Errors that are control flow, not failures (a framework's redirect or not found), which the
+   * boundary throws on to the boundaries above it instead of showing Retry.
+   */
+  passThrough?: (error: unknown) => boolean;
+  /** The error clears when this changes, such as the route's path after a navigation. */
+  resetKey?: unknown;
+}
+
+interface State {
+  failed: boolean;
+  error: unknown;
+  resetKey: unknown;
+}
+
+/**
+ * One region of a page (a dashboard tile, a record panel, a peek section) that fails on its own: an
+ * error thrown while it renders replaces the region with a short alert and Retry, reported through
+ * `onError`, and the rest of the page keeps working. Retry renders the region again.
+ */
+export class RegionBoundary extends Component<RegionBoundaryProps, State> {
+  override state: State = { failed: false, error: null, resetKey: this.props.resetKey };
+
+  static getDerivedStateFromError(error: unknown): Partial<State> {
+    return { failed: true, error };
+  }
+
+  static getDerivedStateFromProps(props: RegionBoundaryProps, state: State): Partial<State> | null {
+    if (Object.is(props.resetKey, state.resetKey)) return null;
+    return { failed: false, error: null, resetKey: props.resetKey };
+  }
+
+  override componentDidCatch(error: unknown, info: ErrorInfo): void {
+    if (this.props.passThrough?.(error)) return;
+    this.props.onError?.(error, info);
+  }
+
+  reset = (): void => {
+    this.setState({ failed: false, error: null });
+  };
+
+  retry = (): void => {
+    if (this.props.onRetry) this.props.onRetry(this.reset);
+    else this.reset();
+  };
+
+  override render(): ReactNode {
+    if (!this.state.failed) return this.props.children;
+    // Thrown from render, so the nearest boundary above this one catches it.
+    if (this.props.passThrough?.(this.state.error)) throw this.state.error;
+    return (
+      <RegionError
+        {...(this.props.title ? { title: this.props.title } : {})}
+        onRetry={this.retry}
+      />
+    );
+  }
+}
+
+/** What a failed region shows: the danger icon, what happened, that the page still works, and Retry. */
+export function RegionError({
+  title,
+  onRetry,
+}: {
+  title?: string;
+  onRetry: () => void;
+}): ReactElement {
+  const t = useT();
+  return (
+    <div className={alertClass} role="alert">
+      <span className={TONE_ICON_CLASS.danger}>
+        <Icon name={TONE_ICON.danger} />
+      </span>
+      <div className="flex flex-col items-start gap-8">
+        <div className="flex flex-col gap-2">
+          <div className="font-semibold">{title ?? t("region.title")}</div>
+          <div className="text-text-secondary">{t("region.body")}</div>
+        </div>
+        <Button size="sm" icon="RefreshCw" onClick={onRetry}>
+          {t("action.retry")}
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/Feedback/Toast.tsx

@@ -0,0 +1,31 @@
+import { useContext, type ReactElement } from "react";
+import { Button } from "../Button/Button.tsx";
+import { InToastRegion, toastClass } from "./Feedback.shared.tsx";
+import { type ToastProps } from "./Feedback.types.ts";
+
+/** Confirms a completed action, with an optional action and its shortcut. Announced politely. */
+export function Toast({
+  message,
+  actionLabel,
+  actionIcon,
+  shortcut,
+  onAction,
+}: ToastProps): ReactElement {
+  const inRegion = useContext(InToastRegion);
+  return (
+    <div className={toastClass} {...(inRegion ? {} : { role: "status" })}>
+      <span>{message}</span>
+      {actionLabel ? (
+        <Button
+          size="sm"
+          variant="ghost"
+          onClick={onAction}
+          {...(actionIcon ? { icon: actionIcon } : {})}
+          {...(shortcut ? { shortcut } : {})}
+        >
+          {actionLabel}
+        </Button>
+      ) : null}
+    </div>
+  );
+}

package/src/Feedback/ToastRegion.tsx

@@ -0,0 +1,26 @@
+import { type ReactElement, type ReactNode } from "react";
+import { InToastRegion } from "./Feedback.shared.tsx";
+
+/**
+ * A polite live region that stacks toasts at the bottom of the viewport. Mount it for the life of
+ * the page and render toasts into it: a live region added together with its content is often not
+ * announced.
+ */
+export function ToastRegion({
+  label,
+  children,
+}: {
+  label: string;
+  children?: ReactNode;
+}): ReactElement {
+  return (
+    <section
+      aria-label={label}
+      aria-live="polite"
+      aria-atomic="false"
+      className="fixed bottom-16 end-16 z-toast flex flex-col items-end gap-8 max-w-[calc(100vw-var(--space-32))]"
+    >
+      <InToastRegion.Provider value={true}>{children}</InToastRegion.Provider>
+    </section>
+  );
+}

package/src/Feedback/UndoToast.tsx

@@ -0,0 +1,97 @@
+import {
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactElement,
+} from "react";
+import { useT } from "../lib/context.tsx";
+import { Button } from "../Button/Button.tsx";
+import { InToastRegion, toastClass } from "./Feedback.shared.tsx";
+import { type UndoToastProps } from "./Feedback.types.ts";
+
+/**
+ * Replaces a confirmation for a reversible action: 8 seconds with a visible timer, Undo on the
+ * button and on Cmd or Ctrl+Z. Shift+Cmd or Ctrl+Z is redo, not undo, and inside a text field the
+ * keys stay the field's own. The timer pauses while the pointer is over the toast or focus is in it
+ * (WCAG 2.2.1, Timing Adjustable), and resumes with the time that was left.
+ */
+export function UndoToast({
+  message,
+  seconds = 8,
+  onUndo,
+  onExpire,
+  undoLabel,
+}: UndoToastProps): ReactElement {
+  const t = useT();
+  const inRegion = useContext(InToastRegion);
+  const [done, setDone] = useState(false);
+  const [paused, setPaused] = useState(false);
+  // Milliseconds still left on the timer, kept across pauses.
+  const left = useRef(seconds * 1000);
+  useEffect(() => {
+    if (done || paused) return undefined;
+    const started = Date.now();
+    const timer = setTimeout(() => {
+      setDone(true);
+      onExpire?.();
+    }, left.current);
+    const onKey = (e: KeyboardEvent) => {
+      if (
+        (e.metaKey || e.ctrlKey) &&
+        !e.shiftKey &&
+        e.key.toLowerCase() === "z" &&
+        // In a text field (anything editable: :read-write) the keys stay the field's own undo.
+        !(e.target as Element).matches?.(":read-write")
+      ) {
+        e.preventDefault();
+        setDone(true);
+        onUndo?.();
+      }
+    };
+    document.addEventListener("keydown", onKey);
+    return () => {
+      clearTimeout(timer);
+      left.current = Math.max(0, left.current - (Date.now() - started));
+      document.removeEventListener("keydown", onKey);
+    };
+  }, [done, paused, onUndo, onExpire]);
+  return (
+    <div
+      className={toastClass}
+      {...(inRegion ? {} : { role: "status" })}
+      onPointerEnter={() => setPaused(true)}
+      onPointerLeave={() => setPaused(false)}
+      onFocus={() => setPaused(true)}
+      onBlur={(e) => {
+        if (!e.currentTarget.contains(e.relatedTarget as Node | null)) setPaused(false);
+      }}
+    >
+      <span>{message}</span>
+      <Button
+        size="sm"
+        variant="ghost"
+        icon="Undo2"
+        shortcut="⌘Z"
+        disabled={done}
+        onClick={() => {
+          setDone(true);
+          onUndo?.();
+        }}
+      >
+        {undoLabel ?? t("action.undo")}
+      </Button>
+      <span
+        aria-hidden="true"
+        className="xos-anim-drain absolute start-0 bottom-0 h-(--stroke-width-focus) w-full bg-accent"
+        style={
+          {
+            "--xos-seconds": seconds,
+            animationPlayState: paused ? "paused" : "running",
+          } as CSSProperties
+        }
+      />
+    </div>
+  );
+}

package/src/FeedbackWidget/README.md

@@ -0,0 +1,3 @@
+# FeedbackWidget
+
+FeedbackWidget sends a message and an optional screenshot to the platform team and never captures anything the person did not approve.

package/src/Field/Field.tsx

@@ -0,0 +1,81 @@
+import { useId, type CSSProperties, type ReactElement, type ReactNode } from "react";
+import { cx } from "../lib/cx.ts";
+import { Icon } from "../Icon/Icon.tsx";
+
+/** Label, control and help or error, shared by every form field. */
+export const fieldClass = cx("flex flex-col gap-4 w-(--ui-field) max-w-full box-border");
+export const labelClass = cx("text-text-12 font-medium text-text-secondary");
+export const helpClass = cx("text-text-12 text-text-secondary max-w-full");
+export const errorClass = cx("flex items-center gap-4 text-text-12 text-danger-text");
+
+/** The bordered control box shared by inputs, selects and triggers. */
+export const controlClass = cx(
+  "h-control-md px-8 rounded-control border border-border-control bg-bg-surface text-text-primary",
+  "font-sans text-text-13 placeholder:text-text-tertiary",
+  "hover:not-focus-visible:border-text-tertiary focus-visible:border-transparent",
+  "aria-invalid:border-danger disabled:opacity-disabled disabled:cursor-not-allowed",
+  "pointer-coarse:min-h-target-coarse forced-colors:border-[CanvasText]",
+  "in-data-[theme=sunlight]:border-stroke-focus",
+);
+
+export function useFieldId(id: string | undefined): string {
+  const generated = useId();
+  return id ?? `xos-${generated.replace(/:/g, "")}`;
+}
+
+/** Ids for the help or error line that a control's aria-describedby points to. */
+export function describedBy(id: string, help: string | undefined, error: string | undefined) {
+  return error ? `${id}-err` : help ? `${id}-help` : undefined;
+}
+
+export function widthStyle(width: number | string | undefined): CSSProperties | undefined {
+  return width === undefined ? undefined : { inlineSize: width };
+}
+
+export interface FieldProps {
+  id: string;
+  label?: ReactNode | undefined;
+  help?: ReactNode | undefined;
+  error?: ReactNode | undefined;
+  width?: number | string | undefined;
+  /** Renders the label as a plain caption when the control is not labelable (a group). */
+  labelFor?: boolean;
+  children: ReactNode;
+}
+
+export function Field({
+  id,
+  label,
+  help,
+  error,
+  width,
+  labelFor = true,
+  children,
+}: FieldProps): ReactElement {
+  return (
+    <div className={fieldClass} style={widthStyle(width)}>
+      {label ? (
+        labelFor ? (
+          <label className={labelClass} htmlFor={id} id={`${id}-label`}>
+            {label}
+          </label>
+        ) : (
+          <span className={labelClass} id={`${id}-label`}>
+            {label}
+          </span>
+        )
+      ) : null}
+      {children}
+      {error ? (
+        <div className={errorClass} id={`${id}-err`}>
+          <Icon name="alert" size={12} />
+          {error}
+        </div>
+      ) : help ? (
+        <div className={helpClass} id={`${id}-help`}>
+          {help}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/FileDrop/README.md

@@ -0,0 +1,3 @@
+# FileDrop
+
+FileDrop accepts files by drag or browse, with a keyboard-reachable input and a list of what was added.

package/src/FilePreviewer/README.md

@@ -0,0 +1,3 @@
+# FilePreviewer
+
+FilePreviewer shows PDF, image, video and Office files (through server conversion) with page thumbnails, zoom and download.

package/src/FilterBuilder/README.md

@@ -0,0 +1,3 @@
+# FilterBuilder
+
+FilterBuilder adds, edits and removes filters as chips and saves the result as a view.

package/src/ForceUpdateScreen/README.md

@@ -0,0 +1,3 @@
+# ForceUpdateScreen
+
+ForceUpdateScreen blocks only when the installed version can no longer sync, and keeps the offline queue.

package/src/Forms/Checkbox.tsx

@@ -0,0 +1,14 @@
+import { type ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { checkLabelClass } from "./Forms.shared.tsx";
+import { type CheckboxProps } from "./Forms.types.ts";
+
+/** A native checkbox with its label; the whole label is the target. */
+export function Checkbox({ label, className, ...rest }: CheckboxProps): ReactElement {
+  return (
+    <label className={cx(checkLabelClass, className)}>
+      <input type="checkbox" {...rest} className="xos-check-input" />
+      {label}
+    </label>
+  );
+}

package/src/Forms/CurrencyInput.tsx

@@ -0,0 +1,40 @@
+import { useState, type ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { useT } from "../lib/context.tsx";
+import { Field, controlClass, describedBy, useFieldId } from "../Field/Field.tsx";
+import { type CurrencyInputProps } from "./Forms.types.ts";
+
+/** A NULL-aware amount field: blank is unpriced and never coerced to 0. */
+export function CurrencyInput({
+  label,
+  value,
+  currency = "USD",
+  help,
+  unpricedLabel,
+  id,
+  onChange,
+}: CurrencyInputProps): ReactElement {
+  const t = useT();
+  const fieldId = useFieldId(id);
+  const [blank, setBlank] = useState(value === null || value === undefined);
+  const helpText = help ?? (blank ? t("money.blankHelp") : undefined);
+  return (
+    <Field id={fieldId} label={label} help={helpText}>
+      <div className="flex items-center gap-6">
+        <input
+          id={fieldId}
+          className={cx(controlClass, "flex-1 min-w-0 text-end tabular-nums")}
+          inputMode="decimal"
+          placeholder={unpricedLabel ?? t("money.unpriced")}
+          defaultValue={value === null || value === undefined ? "" : String(value)}
+          aria-describedby={describedBy(fieldId, helpText, undefined)}
+          onChange={(e) => {
+            setBlank(e.target.value.trim() === "");
+            onChange?.(e);
+          }}
+        />
+        <span className="text-text-12 text-text-tertiary">{currency}</span>
+      </div>
+    </Field>
+  );
+}

package/src/Forms/Forms.shared.tsx

@@ -0,0 +1,5 @@
+import { cx } from "../lib/cx.ts";
+
+export const checkLabelClass = cx(
+  "xos-check inline-flex items-center gap-8 cursor-pointer text-text-13",
+);

package/src/Forms/Forms.tsx

@@ -0,0 +1,20 @@
+export {
+  type InputProps,
+  type TextareaProps,
+  type SelectProps,
+  type CheckboxProps,
+  type SwitchProps,
+  type RadioProps,
+  type NumberInputProps,
+  type CurrencyInputProps,
+  type MoneyProps,
+} from "./Forms.types.ts";
+export { Input } from "./Input.tsx";
+export { Textarea } from "./Textarea.tsx";
+export { Select } from "./Select.tsx";
+export { Checkbox } from "./Checkbox.tsx";
+export { Switch } from "./Switch.tsx";
+export { Radio } from "./Radio.tsx";
+export { NumberInput } from "./NumberInput.tsx";
+export { Money } from "./Money.tsx";
+export { CurrencyInput } from "./CurrencyInput.tsx";

package/src/Forms/Forms.types.ts

@@ -0,0 +1,33 @@
+import type {
+  CheckboxProps as ReferenceCheckboxProps,
+  CurrencyInputProps as ReferenceCurrencyInputProps,
+  InputProps as ReferenceInputProps,
+  MoneyProps as ReferenceMoneyProps,
+  NumberInputProps as ReferenceNumberInputProps,
+  RadioProps as ReferenceRadioProps,
+  SelectProps as ReferenceSelectProps,
+  SwitchProps as ReferenceSwitchProps,
+  TextareaProps as ReferenceTextareaProps,
+} from "../types/reference";
+
+export type InputProps = ReferenceInputProps;
+
+export type TextareaProps = ReferenceTextareaProps;
+
+export type SelectProps = ReferenceSelectProps & { id?: string; name?: string };
+
+export type CheckboxProps = ReferenceCheckboxProps;
+
+export type SwitchProps = ReferenceSwitchProps;
+
+export type RadioProps = ReferenceRadioProps;
+
+export type NumberInputProps = ReferenceNumberInputProps & {
+  id?: string;
+  min?: number;
+  max?: number;
+};
+
+export type CurrencyInputProps = ReferenceCurrencyInputProps;
+
+export type MoneyProps = ReferenceMoneyProps;

package/src/Forms/Input.tsx

@@ -0,0 +1,28 @@
+import { type ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { Field, controlClass, describedBy, useFieldId } from "../Field/Field.tsx";
+import { type InputProps } from "./Forms.types.ts";
+
+/** A labeled single-line field with help text or an inline error naming the field, problem and fix. */
+export function Input({
+  label,
+  help,
+  error,
+  id,
+  width,
+  className,
+  ...rest
+}: InputProps): ReactElement {
+  const fieldId = useFieldId(id);
+  return (
+    <Field id={fieldId} label={label} help={help} error={error} width={width}>
+      <input
+        id={fieldId}
+        aria-invalid={error ? true : undefined}
+        aria-describedby={describedBy(fieldId, help, error)}
+        {...rest}
+        className={cx(controlClass, className)}
+      />
+    </Field>
+  );
+}

package/src/Forms/Money.tsx

@@ -0,0 +1,15 @@
+import { type ReactElement } from "react";
+import { useFormat, useT } from "../lib/context.tsx";
+import { type MoneyProps } from "./Forms.types.ts";
+
+/** An amount with tabular numerals, or Unpriced when null. A blank price is Unpriced; a zero is a claim. */
+export function Money({ amount, currency, unpricedLabel }: MoneyProps): ReactElement {
+  const t = useT();
+  const fmt = useFormat();
+  if (amount === null || amount === undefined) {
+    return (
+      <span className="text-text-secondary not-italic">{unpricedLabel ?? t("money.unpriced")}</span>
+    );
+  }
+  return <span className="tabular-nums">{fmt.currency(amount, currency)}</span>;
+}

package/src/Forms/NumberInput.tsx

@@ -0,0 +1,85 @@
+import { useState, type ChangeEvent, type ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { useT } from "../lib/context.tsx";
+import { Icon } from "../Icon/Icon.tsx";
+import { iconButtonClass } from "../Button/Button.tsx";
+import { Field, controlClass, describedBy, useFieldId } from "../Field/Field.tsx";
+import { type NumberInputProps } from "./Forms.types.ts";
+
+function parseNumber(text: string): number | null {
+  if (text.trim() === "") return null;
+  const n = Number(text);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** A number with units and steppers. Blank stays null, never 0; Arrow Up and Down step. */
+export function NumberInput({
+  label,
+  help,
+  value,
+  unit,
+  step = 1,
+  placeholder: hint,
+  onChange,
+  id,
+  min,
+  max,
+}: NumberInputProps): ReactElement {
+  const t = useT();
+  const fieldId = useFieldId(id);
+  const [current, setCurrent] = useState<number | null>(value ?? null);
+  const [text, setText] = useState(value === null || value === undefined ? "" : String(value));
+  const clamp = (n: number) => Math.min(max ?? Infinity, Math.max(min ?? -Infinity, n));
+  const set = (n: number | null) => {
+    const next = n === null ? null : clamp(n);
+    setCurrent(next);
+    setText(next === null ? "" : String(next));
+    onChange?.(next);
+  };
+  return (
+    <Field id={fieldId} label={label} help={help}>
+      <div className="flex items-center gap-4">
+        <button
+          type="button"
+          className={iconButtonClass()}
+          aria-label={t("number.decrease")}
+          onClick={() => set((current ?? 0) - step)}
+        >
+          <Icon name="Minus" size={14} />
+        </button>
+        <input
+          id={fieldId}
+          className={cx(controlClass, "flex-1 min-w-0 text-end tabular-nums")}
+          inputMode="decimal"
+          value={text}
+          placeholder={hint}
+          aria-describedby={describedBy(fieldId, help, undefined)}
+          onChange={(e: ChangeEvent<HTMLInputElement>) => {
+            setText(e.target.value);
+            const n = parseNumber(e.target.value);
+            setCurrent(n);
+            onChange?.(n);
+          }}
+          onKeyDown={(e) => {
+            if (e.key === "ArrowUp") {
+              e.preventDefault();
+              set((current ?? 0) + step);
+            } else if (e.key === "ArrowDown") {
+              e.preventDefault();
+              set((current ?? 0) - step);
+            }
+          }}
+        />
+        {unit ? <span className="text-text-12 text-text-tertiary">{unit}</span> : null}
+        <button
+          type="button"
+          className={iconButtonClass()}
+          aria-label={t("number.increase")}
+          onClick={() => set((current ?? 0) + step)}
+        >
+          <Icon name="Plus" size={14} />
+        </button>
+      </div>
+    </Field>
+  );
+}

package/src/Forms/Radio.tsx

@@ -0,0 +1,31 @@
+import { type ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { helpClass, labelClass, useFieldId } from "../Field/Field.tsx";
+import { checkLabelClass } from "./Forms.shared.tsx";
+import { type RadioProps } from "./Forms.types.ts";
+
+/** A group of native radios in a fieldset; arrow keys move between options as the platform does. */
+export function Radio({ label, name, value, options, onChange }: RadioProps): ReactElement {
+  const groupName = useFieldId(name);
+  return (
+    <fieldset className="flex flex-col gap-8 m-0 p-0 border-0">
+      <legend className={cx(labelClass, "mb-8")}>{label}</legend>
+      {options.map((o) => (
+        <label key={o.value} className={cx(checkLabelClass, "items-start")}>
+          <input
+            type="radio"
+            name={groupName}
+            value={o.value}
+            defaultChecked={value === o.value}
+            onChange={onChange}
+            className="xos-check-input"
+          />
+          <span className="flex flex-col">
+            <span>{o.label}</span>
+            {o.help ? <span className={helpClass}>{o.help}</span> : null}
+          </span>
+        </label>
+      ))}
+    </fieldset>
+  );
+}