@ghxstship/xos-ui 0.0.0-stage → 4.16.0

package/src/Charts/categories.ts

@@ -0,0 +1,21 @@
+import { cx } from "../lib/cx.ts";
+import type { TimelineCategory } from "./Charts.types.ts";
+
+/**
+ * Categorical colour steps of day-type tags and row segments (viz-cat-1 to viz-cat-7, B4). A small module of its
+ * own so the Calendar, the Timeline and the day sheet share it without loading each other.
+ */
+export const TL_CATEGORY: Readonly<Record<number, string>> = {
+  1: cx("bg-viz-cat-1"),
+  2: cx("bg-viz-cat-2"),
+  3: cx("bg-viz-cat-3"),
+  4: cx("bg-viz-cat-4"),
+  5: cx("bg-viz-cat-5"),
+  6: cx("bg-viz-cat-6"),
+  7: cx("bg-viz-cat-7"),
+};
+
+/** A day's or a segment's categories as text, for the table alternative and announcements. */
+export function categoryText(tags: readonly TimelineCategory[] | undefined): string {
+  return (tags ?? []).map((tag) => tag.label).join(", ");
+}

package/src/Charts/timeline-plan.ts

@@ -0,0 +1,191 @@
+import type { TimelineChange, TimelineLink, TimelineMove } from "../types/reference";
+
+/** A bar's first and last day, by day index (the last day inclusive). */
+interface Span {
+  readonly start: number;
+  readonly end: number;
+  /** A milestone: one instant on its day, so it starts and finishes at the same point. */
+  readonly point?: boolean;
+}
+
+/** The dependency preview of a pending change, worked out on the day grid. */
+export interface TimelinePlan {
+  /** Rows other than the changed one that the change pushes, with their new days. */
+  readonly moves: readonly TimelineMove[];
+  /** Rows the change would move that are locked, the changed row first. */
+  readonly locked: readonly number[];
+  /** Rows on the critical path before and after the change. */
+  readonly criticalBefore: readonly number[];
+  readonly criticalAfter: readonly number[];
+  /** Days the last finish moves (negative for earlier). */
+  readonly finishShift: number;
+}
+
+const EPSILON = 1e-9;
+
+/** Where a bar finishes on the day grid: the end of its last day, or a milestone's own day. */
+function finishOf(s: Span): number {
+  return s.point ? s.start : s.end + 1;
+}
+
+/*
+ * Bars occupy half-open day ranges [start, end + 1), so a Finish to Start successor may start the
+ * day after its predecessor's last day. A milestone is one instant, as app.reschedule_record reads
+ * a one-date record, so it starts and finishes on its day. Each type compares one side of each
+ * bar: the predecessor's start or finish, plus lag, against the successor's start or finish.
+ */
+function gap(link: TimelineLink, from: Span, to: Span): number {
+  const type = link.type ?? "Finish to Start";
+  const fromFinish = type === "Finish to Start" || type === "Finish to Finish";
+  const toStart = type === "Finish to Start" || type === "Start to Start";
+  const required = (fromFinish ? finishOf(from) : from.start) + (link.lagDays ?? 0);
+  const actual = toStart ? to.start : finishOf(to);
+  return required - actual;
+}
+
+/** True when a dependency path from the row comes back to a row already on it. */
+function cyclic(links: readonly TimelineLink[], row: number): boolean {
+  const out = new Map<number, number[]>();
+  for (const l of links) out.set(l.from, [...(out.get(l.from) ?? []), l.to]);
+  const done = new Set<number>();
+  const path = new Set<number>();
+  const visit = (i: number): boolean => {
+    if (path.has(i)) return true;
+    if (done.has(i)) return false;
+    path.add(i);
+    const found = (out.get(i) ?? []).some(visit);
+    path.delete(i);
+    done.add(i);
+    return found;
+  };
+  return visit(row);
+}
+
+/**
+ * Pushes the successors of a changed row by the whole days their dependencies need, round by round
+ * through the chain, as app.reschedule_record does on the server (ADR 0111): a successor moves only
+ * by what the change adds to its dependency's gap, so a gap already broken stays as it was and
+ * moving a row earlier pulls nothing. Returns null for a cycle.
+ */
+export function pushSuccessors(
+  spans: readonly Span[],
+  links: readonly TimelineLink[],
+  change: TimelineChange,
+): Span[] | null {
+  if (cyclic(links, change.row)) return null;
+  const now: Span[] = spans.map((s) => ({ ...s }));
+  now[change.row] = { ...spans[change.row], start: change.start, end: change.end };
+  const allowed = links.map((l) => {
+    const from = spans[l.from];
+    const to = spans[l.to];
+    return from && to ? Math.max(0, gap(l, from, to)) : 0;
+  });
+  const moved = (i: number) => now[i]?.start !== spans[i]?.start || now[i]?.end !== spans[i]?.end;
+  for (let round = 0; round <= spans.length; round += 1) {
+    const push = new Map<number, number>();
+    links.forEach((l, k) => {
+      const from = now[l.from];
+      const to = now[l.to];
+      if (!from || !to || l.to === change.row || !moved(l.from)) return;
+      const need = gap(l, from, to) - (allowed[k] ?? 0);
+      if (need > EPSILON) push.set(l.to, Math.max(push.get(l.to) ?? 0, Math.ceil(need - EPSILON)));
+    });
+    if (push.size === 0) return now;
+    for (const [i, days] of push) {
+      const s = now[i];
+      if (s) now[i] = { ...s, start: s.start + days, end: s.end + days };
+    }
+  }
+  return null;
+}
+
+/**
+ * Rows with no float: those whose slip, followed through their successors' slack, moves the last
+ * finish. A row with no successor has the days between its finish and the last finish as float.
+ */
+export function criticalRows(spans: readonly Span[], links: readonly TimelineLink[]): number[] {
+  if (spans.length === 0) return [];
+  const finish = Math.max(...spans.map(finishOf));
+  const out = new Map<number, TimelineLink[]>();
+  for (const l of links) out.set(l.from, [...(out.get(l.from) ?? []), l]);
+  const memo = new Map<number, number>();
+  const visiting = new Set<number>();
+  const float = (i: number): number => {
+    const known = memo.get(i);
+    if (known !== undefined) return known;
+    const s = spans[i];
+    if (!s || visiting.has(i)) return Number.POSITIVE_INFINITY;
+    visiting.add(i);
+    let value = finish - finishOf(s);
+    for (const l of out.get(i) ?? []) {
+      const to = spans[l.to];
+      if (to) value = Math.min(value, -gap(l, s, to) + float(l.to));
+    }
+    visiting.delete(i);
+    memo.set(i, value);
+    return value;
+  };
+  return spans.flatMap((_, i) => (float(i) <= EPSILON ? [i] : []));
+}
+
+/** The preview of one change: the rows it pushes, the locked rows it would move, and the critical path. */
+export function planChange(
+  spans: readonly Span[],
+  links: readonly TimelineLink[],
+  change: TimelineChange,
+  isLocked: (row: number) => boolean,
+): TimelinePlan | null {
+  const after = pushSuccessors(spans, links, change);
+  if (!after) return null;
+  const moves: TimelineMove[] = [];
+  after.forEach((s, i) => {
+    const was = spans[i];
+    if (i !== change.row && was && (s.start !== was.start || s.end !== was.end)) {
+      moves.push({ row: i, start: s.start, end: s.end });
+    }
+  });
+  return withMoves(spans, links, change, moves, isLocked);
+}
+
+/** The preview of a change whose pushed rows are already known (the page's own preview). */
+export function withMoves(
+  spans: readonly Span[],
+  links: readonly TimelineLink[],
+  change: TimelineChange,
+  moves: readonly TimelineMove[],
+  isLocked: (row: number) => boolean,
+): TimelinePlan {
+  const after = spans.map((s) => ({ ...s }));
+  after[change.row] = { ...spans[change.row], start: change.start, end: change.end };
+  for (const m of moves) after[m.row] = { ...spans[m.row], start: m.start, end: m.end };
+  const was = spans[change.row];
+  const targetMoved = !!was && (was.start !== change.start || was.end !== change.end);
+  const lastFinish = (list: readonly Span[]) => Math.max(...list.map(finishOf));
+  return {
+    moves,
+    locked: [
+      ...(targetMoved && isLocked(change.row) ? [change.row] : []),
+      ...moves.filter((m) => isLocked(m.row)).map((m) => m.row),
+    ],
+    criticalBefore: criticalRows(spans, links),
+    criticalAfter: criticalRows(after, links),
+    finishShift: spans.length > 0 ? lastFinish(after) - lastFinish(spans) : 0,
+  };
+}
+
+/** Same rows in both lists, in any order. */
+export function sameRows(a: readonly number[], b: readonly number[]): boolean {
+  if (a.length !== b.length) return false;
+  const set = new Set(a);
+  return b.every((i) => set.has(i));
+}
+
+/** The same rows moved to the same days, in any order. */
+export function sameMoves(a: readonly TimelineMove[], b: readonly TimelineMove[]): boolean {
+  if (a.length !== b.length) return false;
+  const at = new Map(a.map((m) => [m.row, m]));
+  return b.every((m) => {
+    const other = at.get(m.row);
+    return !!other && other.start === m.start && other.end === m.end;
+  });
+}

package/src/Checkbox/README.md

@@ -0,0 +1,6 @@
+# Checkbox
+
+Checkbox toggles one independent option in a form or checklist row.
+
+- Checklist items are rows, never array positions.
+- 16 px box, `radius-chip`, accent fill when checked.

package/src/ChecklistRunner/README.md

@@ -0,0 +1,3 @@
+# ChecklistRunner
+
+ChecklistRunner shows one inspection item per card with large Pass and Fail buttons; Fail asks for a photo and a note.

package/src/Chips/Badge.tsx

@@ -0,0 +1,27 @@
+import type { ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { type BadgeProps } from "./Chips.types.ts";
+
+const BADGE_TONE: Record<NonNullable<BadgeProps["tone"]>, string> = {
+  neutral: cx("bg-bg-hover text-text-secondary"),
+  accent: cx("bg-accent text-accent-text-on"),
+  danger: cx("bg-danger text-danger-text-on"),
+};
+
+/** A count pill; above 99 it reads 99+. `label` names the count for assistive technology. */
+export function Badge({ count, tone = "neutral", label, className }: BadgeProps): ReactElement {
+  const text = count > 99 ? "99+" : String(count);
+  return (
+    <span
+      className={cx(
+        "inline-grid place-items-center min-w-(--ui-kbd) h-(--ui-kbd) px-6 rounded-pill",
+        "text-text-11 font-semibold tabular-nums",
+        BADGE_TONE[tone],
+        className,
+      )}
+      {...(label ? { role: "img", "aria-label": label } : {})}
+    >
+      {text}
+    </span>
+  );
+}

package/src/Chips/Chips.shared.tsx

@@ -0,0 +1,34 @@
+import type { ReactNode } from "react";
+import { cx } from "../lib/cx.ts";
+import { chipClass } from "./chipClass.tsx";
+
+/* Pressed holds the hover fill: a brightness filter took small chip text under 4.5:1 (A24-004). */
+export const buttonChipClass = cx("xos-hit cursor-pointer hover:bg-bg-hover active:bg-bg-hover");
+
+export function Chip({
+  onClick,
+  title,
+  children,
+}: {
+  onClick?: (() => void) | undefined;
+  title?: string;
+  children: ReactNode;
+}) {
+  if (onClick) {
+    return (
+      <button
+        type="button"
+        className={cx(chipClass, buttonChipClass)}
+        onClick={onClick}
+        title={title}
+      >
+        {children}
+      </button>
+    );
+  }
+  return (
+    <span className={chipClass} title={title}>
+      {children}
+    </span>
+  );
+}

package/src/Chips/Chips.tsx

@@ -0,0 +1,21 @@
+export {
+  type StateChipProps,
+  type PhaseChipProps,
+  type DepartmentChipProps,
+  type URIDChipProps,
+  type RecordKindChipProps,
+  type PropertyChipProps,
+  type TagProps,
+  type TagSwatch,
+  type BadgeProps,
+} from "./Chips.types.ts";
+export { chipClass } from "./chipClass.tsx";
+export { codeClass } from "./codeClass.tsx";
+export { StateChip } from "./StateChip.tsx";
+export { PhaseChip } from "./PhaseChip.tsx";
+export { DepartmentChip } from "./DepartmentChip.tsx";
+export { URIDChip } from "./URIDChip.tsx";
+export { RecordKindChip } from "./RecordKindChip.tsx";
+export { PropertyChip } from "./PropertyChip.tsx";
+export { Tag } from "./Tag.tsx";
+export { Badge } from "./Badge.tsx";

package/src/Chips/Chips.types.ts

@@ -0,0 +1,35 @@
+import type {
+  BadgeProps as ReferenceBadgeProps,
+  DepartmentChipProps as ReferenceDepartmentChipProps,
+  PhaseChipProps as ReferencePhaseChipProps,
+  PropertyChipProps as ReferencePropertyChipProps,
+  RecordKindChipProps as ReferenceRecordKindChipProps,
+  StateChipProps as ReferenceStateChipProps,
+  TagProps as ReferenceTagProps,
+  URIDChipProps as ReferenceURIDChipProps,
+} from "../types/reference";
+
+export type StateChipProps = ReferenceStateChipProps;
+
+export type PhaseChipProps = ReferencePhaseChipProps;
+
+export type DepartmentChipProps = ReferenceDepartmentChipProps;
+
+export type URIDChipProps = ReferenceURIDChipProps;
+
+export type RecordKindChipProps = ReferenceRecordKindChipProps;
+
+export type PropertyChipProps = ReferencePropertyChipProps;
+
+/** One of the seven themed categorical colors (color.viz.cat-1..7), as a Tag's dot (ADR 0142). */
+export type TagSwatch = "cat-1" | "cat-2" | "cat-3" | "cat-4" | "cat-5" | "cat-6" | "cat-7";
+
+export type TagProps = ReferenceTagProps & {
+  /**
+   * A categorical color for the dot instead of the tone's, for user-defined choices and segments. The label
+   * always shows beside it, so color is never the only signal.
+   */
+  swatch?: TagSwatch;
+};
+
+export type BadgeProps = ReferenceBadgeProps & { className?: string };

package/src/Chips/DepartmentChip.tsx

@@ -0,0 +1,16 @@
+import type { ReactElement } from "react";
+import { DepartmentGlyph } from "../Glyphs/Glyphs.tsx";
+import { Chip } from "./Chips.shared.tsx";
+import { type DepartmentChipProps } from "./Chips.types.ts";
+import { codeClass } from "./codeClass.tsx";
+
+/** Department name with its code in a mono chip. */
+export function DepartmentChip({ name, code }: DepartmentChipProps): ReactElement {
+  return (
+    <Chip>
+      <DepartmentGlyph code={code} size={14} color="var(--color-text-secondary)" />
+      <span>{name}</span>
+      <span className={codeClass}>{code}</span>
+    </Chip>
+  );
+}

package/src/Chips/PhaseChip.tsx

@@ -0,0 +1,16 @@
+import type { ReactElement } from "react";
+import { useT } from "../lib/context.tsx";
+import { PhaseGlyph } from "../Glyphs/Glyphs.tsx";
+import { Chip } from "./Chips.shared.tsx";
+import { type PhaseChipProps } from "./Chips.types.ts";
+
+/** Gate number and phase name (`Gate 3 · Advance`); the code is never shown alone. */
+export function PhaseChip({ gate, name, code }: PhaseChipProps): ReactElement {
+  const t = useT();
+  return (
+    <Chip title={code}>
+      <PhaseGlyph code={code} size={14} color="var(--color-text-secondary)" />
+      <span>{t("phase.gateName", { n: gate, name })}</span>
+    </Chip>
+  );
+}

package/src/Chips/PropertyChip.tsx

@@ -0,0 +1,15 @@
+import type { ReactElement } from "react";
+import { Icon } from "../Icon/Icon.tsx";
+import { Chip } from "./Chips.shared.tsx";
+import { type PropertyChipProps } from "./Chips.types.ts";
+
+/** An inline property that edits in place when clickable. */
+export function PropertyChip({ label, value, icon, onClick }: PropertyChipProps): ReactElement {
+  return (
+    <Chip onClick={onClick}>
+      {icon ? <Icon name={icon} size={14} color="var(--color-text-secondary)" /> : null}
+      {label ? <span className="text-text-secondary">{label}</span> : null}
+      <span>{value}</span>
+    </Chip>
+  );
+}

package/src/Chips/RecordKindChip.tsx

@@ -0,0 +1,14 @@
+import type { ReactElement } from "react";
+import { RecordKindGlyph } from "../Glyphs/Glyphs.tsx";
+import { Chip } from "./Chips.shared.tsx";
+import { type RecordKindChipProps } from "./Chips.types.ts";
+
+/** Record kind glyph and name. */
+export function RecordKindChip({ kind, label }: RecordKindChipProps): ReactElement {
+  return (
+    <Chip>
+      <RecordKindGlyph kind={kind} size={14} color="var(--color-text-secondary)" />
+      <span>{label ?? kind}</span>
+    </Chip>
+  );
+}

package/src/Chips/StateChip.tsx

@@ -0,0 +1,19 @@
+import type { ReactElement } from "react";
+import { StateIcon } from "../StateIcon/StateIcon.tsx";
+import { Chip } from "./Chips.shared.tsx";
+import { type StateChipProps } from "./Chips.types.ts";
+
+/** Record state as icon plus label; clickable chips open the state menu. `compact` keeps the label for assistive technology only. */
+export function StateChip({
+  state,
+  label,
+  compact = false,
+  onClick,
+}: StateChipProps): ReactElement {
+  return (
+    <Chip onClick={onClick}>
+      <StateIcon state={state} />
+      <span className={compact ? "sr-only" : undefined}>{label}</span>
+    </Chip>
+  );
+}

package/src/Chips/Tag.tsx

@@ -0,0 +1,47 @@
+import type { ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { type TagProps, type TagSwatch } from "./Chips.types.ts";
+
+const TAG_DOT: Record<NonNullable<TagProps["tone"]>, string> = {
+  neutral: cx("bg-text-tertiary"),
+  accent: cx("bg-accent"),
+  success: cx("bg-success"),
+  warning: cx("bg-warning"),
+  danger: cx("bg-danger"),
+};
+
+const TAG_SWATCH: Record<TagSwatch, string> = {
+  "cat-1": cx("bg-viz-cat-1"),
+  "cat-2": cx("bg-viz-cat-2"),
+  "cat-3": cx("bg-viz-cat-3"),
+  "cat-4": cx("bg-viz-cat-4"),
+  "cat-5": cx("bg-viz-cat-5"),
+  "cat-6": cx("bg-viz-cat-6"),
+  "cat-7": cx("bg-viz-cat-7"),
+};
+
+/**
+ * A status word with a colored dot; the word carries the meaning. A swatch colors the dot with a themed
+ * categorical token (light, dark and sunlight) for a user-defined choice; in forced colors the dot takes the text
+ * color and the tag keeps its border.
+ */
+export function Tag({ tone = "neutral", swatch, children }: TagProps): ReactElement {
+  return (
+    <span
+      className={cx(
+        "inline-flex items-center gap-4 h-(--ui-tag) px-6 rounded-chip bg-bg-hover text-text-secondary",
+        "text-text-12 font-medium whitespace-nowrap forced-colors:border",
+      )}
+    >
+      <span
+        aria-hidden="true"
+        data-swatch={swatch}
+        className={cx(
+          "size-(--ui-dot) rounded-full flex-none",
+          swatch ? cx(TAG_SWATCH[swatch], "forced-colors:bg-[CanvasText]") : TAG_DOT[tone],
+        )}
+      />
+      {children}
+    </span>
+  );
+}

package/src/Chips/URIDChip.tsx

@@ -0,0 +1,14 @@
+import type { ReactElement } from "react";
+import { Chip } from "./Chips.shared.tsx";
+import { type URIDChipProps } from "./Chips.types.ts";
+import { codeClass } from "./codeClass.tsx";
+
+/** Catalog element name with its URID in a mono chip. */
+export function URIDChip({ name, urid }: URIDChipProps): ReactElement {
+  return (
+    <Chip>
+      <span>{name}</span>
+      <span className={codeClass}>{urid}</span>
+    </Chip>
+  );
+}

package/src/Chips/chipClass.tsx

@@ -0,0 +1,8 @@
+import { cx } from "../lib/cx.ts";
+
+/** The chip shape shared by every chip and property: 22 px, hairline border, surface ground. */
+export const chipClass = cx(
+  "inline-flex items-center gap-4 h-(--ui-chip) px-6 rounded-chip border border-border-subtle",
+  "bg-bg-surface text-text-primary font-sans text-text-12 whitespace-nowrap",
+  "transition-colors duration-fast ease-standard forced-colors:border-[CanvasText]",
+);

package/src/Chips/codeClass.tsx

@@ -0,0 +1,6 @@
+import { cx } from "../lib/cx.ts";
+
+/** The mono code beside a plain name; codes never appear alone. */
+export const codeClass = cx(
+  "font-mono text-text-11 text-text-secondary px-4 rounded-chip bg-bg-hover",
+);

package/src/ClockButton/README.md

@@ -0,0 +1,6 @@
+# ClockButton
+
+ClockButton is the Compass Today screen's single primary control, changing with the person's state.
+
+- States: `out` (Clock In), `on` (timer), `break`, `blocked` (outside geofence).
+- Minimum 96 px tall, well above the 48 pt `touch-min`; haptic on press.

package/src/CodeSample/README.md

@@ -0,0 +1,7 @@
+# CodeSample
+
+CodeSample shows a short command or snippet with a copy button.
+
+The block is keyboard focusable so it scrolls without a pointer, and Copy confirms through a polite live region. Keep samples to commands a reader can run as written; package names and endpoints come from the repository.
+
+The consumer provides a label and the code.

package/src/ColorPicker/README.md

@@ -0,0 +1,5 @@
+# ColorPicker
+
+ColorPicker checks contrast live and blocks any tenant color that fails WCAG 2.2 AA.
+
+- `XOS.contrastRatio(a, b)` exposes the same calculation.

package/src/Combobox/README.md

@@ -0,0 +1,7 @@
+# Combobox
+
+Combobox searches a long list as the person types; arrow keys move, Enter picks, Escape closes.
+
+- Coded options show the plain name first and the code in mono, in numeric order.
+- Options come from reference tables; the preview lists the ten department classes.
+- No match shows one sentence telling the person what to try.