@ghxstship/xos-ui 0.0.0-stage → 4.16.0

package/src/Templates/Templates.tsx

@@ -0,0 +1,29 @@
+export {
+  type TemplateCollectionProps,
+  type TemplateRecordProps,
+  type TemplateSplitViewProps,
+  type TemplateDashboardProps,
+  type DashboardTile,
+  type DashboardSpans,
+  type DashboardResize,
+  type TemplateSettingsProps,
+  type TemplateWizardProps,
+  type TemplateGridEditorProps,
+  type TemplateDocumentProps,
+  type TemplateAuthProps,
+  type TemplateGatewayShellProps,
+  type TemplateSystemProps,
+  type TemplateSystemLinkProps,
+} from "./Templates.types.ts";
+export { TemplateCollection } from "./TemplateCollection.tsx";
+export { TemplateRecord } from "./TemplateRecord.tsx";
+export { TemplateSplitView } from "./TemplateSplitView.tsx";
+export { TemplateDashboard, clampSpan, spansOf } from "./TemplateDashboard.tsx";
+export { TemplateSettings } from "./TemplateSettings.tsx";
+export { TemplateWizard } from "./TemplateWizard.tsx";
+export { TemplateGridEditor } from "./TemplateGridEditor.tsx";
+export { TemplateDocument } from "./TemplateDocument.tsx";
+export { TemplateAuth } from "./TemplateAuth.tsx";
+export { TemplateGatewayShell } from "./TemplateGatewayShell.tsx";
+export { TemplateSystem } from "./TemplateSystem.tsx";
+export { TemplateSystemLink } from "./TemplateSystemLink.tsx";

package/src/Templates/Templates.types.ts

@@ -0,0 +1,153 @@
+import type { ReactNode } from "react";
+
+/*
+ * Page templates (design reference, Templates group). Each is a layout with named slots; the screens
+ * compose components into the slots. Every template collapses to one column on small screens, and
+ * the order of the source is the reading order.
+ */
+
+export interface TemplateCollectionProps {
+  /** PageHeader: title, count, view switcher and the one primary action. */
+  header: ReactNode;
+  /** FilterBuilder or saved filters. */
+  filters?: ReactNode;
+  /** The view body: RecordList, DataTable, Board, Timeline or Calendar. */
+  children: ReactNode;
+  /** A SidePeek for the selected record. */
+  peek?: ReactNode;
+  /** BulkActionBar while records are selected. */
+  bulk?: ReactNode;
+}
+
+export interface TemplateRecordProps {
+  /** Title row: key, kind, state and actions. */
+  header: ReactNode;
+  /** Content and activity. */
+  children: ReactNode;
+  /** The 320 px property column. */
+  properties: ReactNode;
+  related?: ReactNode;
+  /** Names the property column for assistive technology. */
+  propertiesLabel?: string;
+}
+
+export interface TemplateSplitViewProps {
+  list: ReactNode;
+  detail: ReactNode;
+  /** List width in pixels; resizable between 240 and 480. */
+  listWidth?: number;
+  listLabel?: string;
+}
+
+/** One tile on the dashboard grid. */
+export interface DashboardTile {
+  /** Stable id; a saved layout names tiles by it. */
+  id: string;
+  /** Names the tile for its resize handle and announcements. */
+  label: string;
+  /** Columns of the 12-column grid the tile spans by default. */
+  span: number;
+  /** The fewest columns it may shrink to; 3 by default. */
+  minSpan?: number;
+  /** StatTile, Chart or Card content. */
+  content: ReactNode;
+}
+
+/** Spans by tile id, as a person arranged them. */
+export type DashboardSpans = Readonly<Record<string, number>>;
+
+/**
+ * Resizing in grid units. Copy arrives from the app, so the library ships no strings for it; without
+ * this prop tiles keep their spans.
+ */
+export interface DashboardResize {
+  /** The handle's name, such as "Resize Alerts". */
+  label: (tile: string) => string;
+  /** What a screen reader hears after a change, such as "Alerts, 6 of 12 columns". */
+  describe: (tile: string, span: number) => string;
+  /** Called with every tile's span once a drag ends or a key changes one. */
+  onChange: (spans: DashboardSpans) => void;
+}
+
+export interface TemplateDashboardProps {
+  /** PageHeader with the title. */
+  header: ReactNode;
+  /** The date range and scope picker, at the end of the header row. */
+  controls?: ReactNode;
+  /** Tiles on the 12-column grid, in reading order. */
+  tiles?: readonly DashboardTile[];
+  /** The person's saved spans; a tile without one keeps its default. */
+  spans?: DashboardSpans;
+  resize?: DashboardResize;
+  /** Names the grid for assistive technology. */
+  label?: string;
+  /** Free content on the grid; each child spans 4 columns at lg. */
+  children?: ReactNode;
+}
+
+export interface TemplateSettingsProps {
+  /** The section list. */
+  sections: ReactNode;
+  /** The form column, 640 px at most. */
+  children: ReactNode;
+  /** A sticky save bar shown while there are unsaved changes. */
+  saveBar?: ReactNode;
+}
+
+export interface TemplateWizardProps {
+  steps: string[];
+  current: number;
+  title: ReactNode;
+  children: ReactNode;
+  onBack?: () => void;
+  onNext?: () => void;
+  /** Label of the last step's button; Done by default. */
+  finishLabel?: string;
+  nextDisabled?: boolean;
+}
+
+export interface TemplateGridEditorProps {
+  header: ReactNode;
+  /** SpreadsheetGrid, BudgetGrid or AccessGridMatrix. */
+  children: ReactNode;
+  toolbar?: ReactNode;
+}
+
+export interface TemplateDocumentProps {
+  /** The outline, hidden below lg. */
+  outline: ReactNode;
+  children: ReactNode;
+  /** Required acknowledgments at the end of the document. */
+  acknowledgments?: ReactNode;
+}
+
+export interface TemplateAuthProps {
+  brand?: ReactNode;
+  children: ReactNode;
+}
+
+export interface TemplateGatewayShellProps {
+  /** TopNav on desktop. */
+  topNav: ReactNode;
+  /** Up Next and the side column, beside the feed on desktop. */
+  aside?: ReactNode;
+  children: ReactNode;
+  /** TabBar below md. */
+  tabBar?: ReactNode;
+}
+
+export interface TemplateSystemProps {
+  icon: string;
+  title: string;
+  sentence: string;
+  actionLabel: string;
+  onAction?: () => void;
+  /** A support reference such as an error id. */
+  reference?: string;
+}
+
+/** TemplateSystem whose action is a link, for server components (`@xos/ui/static`). */
+export interface TemplateSystemLinkProps extends Omit<TemplateSystemProps, "onAction"> {
+  /** Where the action goes. */
+  href: string;
+}

package/src/Testimonial/README.md

@@ -0,0 +1,7 @@
+# Testimonial
+
+Testimonial shows a customer's words with a required disclosure line.
+
+`disclosure` is required and states the speaker's connection to the publisher: a customer, a partner, or someone who received anything of value. A testimonial runs only when a real customer said it and consented in writing; nothing here is invented, bought or written by staff. Until such a statement exists, the page ships without this component.
+
+The preview uses the fictional tenant Northwind Live, as every XOS preview does, and its disclosure line says so.

package/src/Textarea/README.md

@@ -0,0 +1,3 @@
+# Textarea
+
+Textarea takes multi-line text with the same label, help and error pattern as Input.

package/src/TimePicker/README.md

@@ -0,0 +1,5 @@
+# TimePicker
+
+TimePicker is zone-aware: the venue time zone is always shown beside the time.
+
+- Times display in 12-hour format with AM and PM; storage is UTC.

package/src/Timeline/README.md

@@ -0,0 +1,6 @@
+# Timeline
+
+Timeline is the Gantt view: bars by state, baselines underneath, dependencies, gate markers, today and the critical path.
+
+- Dragging previews dependent shifts before release.
+- Has an accessible table alternative.

package/src/Toast/README.md

@@ -0,0 +1,3 @@
+# Toast
+
+Toast confirms a completed action; destructive actions show an Undo toast for 8 seconds.

package/src/Tooltip/README.md

@@ -0,0 +1,3 @@
+# Tooltip
+
+Tooltip shows an icon control's label and shortcut after 500 ms hover or on focus; never interactive content.

package/src/TopNav/README.md

@@ -0,0 +1,5 @@
+# TopNav
+
+TopNav is the Gateway shell's top bar on desktop: brand, the five destinations, search, help and the avatar menu.
+
+- On an org's custom domain the brand is that org's; on the platform domain it is the platform's, through BrandMark.

package/src/TreeView/README.md

@@ -0,0 +1,3 @@
+# TreeView
+
+TreeView shows the scope tree: engagement root, standing venues and shows, with keyboard expand and collapse.

package/src/URIDChip/README.md

@@ -0,0 +1,5 @@
+# URIDChip
+
+URIDChip pairs a plain name with its URID in JetBrains Mono, at discipline or category grain.
+
+- Canon disciplines and categories hold .01 to .49; adopter extensions hold .50 to .99 and are scoped to their org. The preview's second chip, Northwind Line Array Kit (5000.01.50), is a Northwind Live extension under canon discipline Audio (5000.01).

package/src/UndoToast/README.md

@@ -0,0 +1,3 @@
+# UndoToast
+
+UndoToast replaces confirmations for reversible actions; it stays 8 seconds with a visible timer and Cmd or Ctrl+Z.

package/src/UpNextCard/README.md

@@ -0,0 +1,6 @@
+# UpNextCard
+
+UpNextCard leads Gateway Home with the person's next shift, set time, delivery or deadline: countdown, call time, address, parking, contact and what to bring.
+
+- Directions, Add to Calendar and Add to Wallet are one tap each.
+- Every engagement detail is reachable from Home in one tap.

package/src/Views/ActivityFeedItem.tsx

@@ -0,0 +1,52 @@
+import { type ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { Icon } from "../Icon/Icon.tsx";
+import { Avatar } from "../Avatar/Avatar.tsx";
+import { chipClass } from "../Chips/Chips.tsx";
+import { type ActivityFeedItemProps } from "./Views.types.ts";
+
+/** One event or comment in a feed; reactions are glyph buttons with their counts. */
+export function ActivityFeedItem({
+  actor,
+  action,
+  target,
+  time,
+  comment,
+  reactions,
+  onReact,
+}: ActivityFeedItemProps): ReactElement {
+  return (
+    <article className="flex items-start gap-12 max-w-(--layout-peek)">
+      <Avatar name={actor} />
+      <div className="flex flex-1 flex-col gap-4 min-w-0">
+        <p className="m-0">
+          <strong className="font-semibold">{actor}</strong>{" "}
+          <span className="text-text-secondary">{action}</span>{" "}
+          {target ? <span className="font-mono text-text-12">{target}</span> : null}{" "}
+          <time className="text-text-secondary">{time}</time>
+        </p>
+        {comment ? (
+          <div className="px-12 py-8 rounded-card border border-border-subtle bg-bg-surface">
+            {comment}
+          </div>
+        ) : null}
+        {reactions ? (
+          <div className="flex flex-wrap gap-4">
+            {reactions.map((r) => (
+              <button
+                key={r.label}
+                type="button"
+                aria-label={`${r.label} ${r.count}`}
+                onClick={() => onReact?.(r.label)}
+                className={cx(chipClass, "xos-hit cursor-pointer hover:bg-bg-hover")}
+              >
+                <Icon name={r.icon} size={12} />
+                <span className="tabular-nums">{r.count}</span>
+              </button>
+            ))}
+          </div>
+        ) : null}
+      </div>
+    </article>
+  );
+}

package/src/Views/Board.tsx

@@ -0,0 +1,229 @@
+import { useRef, useState, type DragEvent, type KeyboardEvent, type ReactElement } from "react";
+import { Direction } from "radix-ui";
+import { cx } from "../lib/cx.ts";
+import { useFormat, useT } from "../lib/context.tsx";
+import { isMenuKey, useItemSelection } from "../lib/selection.ts";
+import { Icon } from "../Icon/Icon.tsx";
+import { buttonClass } from "../Button/Button.tsx";
+import { Avatar } from "../Avatar/Avatar.tsx";
+import { PropertyChip, RecordKindChip } from "../Chips/Chips.tsx";
+import { StateIcon } from "../StateIcon/StateIcon.tsx";
+import { ScrollRegion } from "../Layout/ScrollRegion.tsx";
+import { type BoardProps, type Card } from "./Views.types.ts";
+
+/** How the selection and menus name a card. */
+const idOf = (card: Card) => card.id ?? card.key;
+
+/**
+ * Records grouped into columns by state. Cards move by drag or by keyboard: Space picks a card up,
+ * Arrow Left and Right carry it across columns, Space drops it and Esc puts it back. With
+ * `selection`, cards select as rows of a list do (X and Shift+X, Cmd or Ctrl+click, Shift+click,
+ * Cmd or Ctrl+A, Esc), in reading order down each column. Right-click, Shift+F10 or the Context Menu
+ * key on a card calls `onItemContextMenu`. A card's key and title carry `data-column`, and the card
+ * its `data-item` id, so a page can preview them (hover cards).
+ */
+export function Board({
+  addLabel,
+  readOnly = false,
+  columns,
+  selection,
+  onItemContextMenu,
+  onMove,
+  onAdd,
+  onOpen,
+}: BoardProps): ReactElement {
+  const t = useT();
+  const fmt = useFormat();
+  const dir = Direction.useDirection();
+  const [cols, setCols] = useState(columns);
+  const [held, setHeld] = useState<{ key: string; origin: number; at: number } | null>(null);
+  const [announcement, setAnnouncement] = useState("");
+  const cardRefs = useRef(new Map<string, HTMLElement>());
+  const ids = () => cols.flatMap((col) => col.cards.map(idOf));
+  const select = useItemSelection(selection, ids);
+  const selectedCount = selection ? ids().filter(select.isSelected).length : 0;
+
+  const move = (key: string, from: number, to: number) => {
+    if (from === to) return;
+    setCols((current) => {
+      const card = current[from]?.cards.find((c) => c.key === key);
+      if (!card) return current;
+      return current.map((col, i) =>
+        i === from
+          ? { ...col, cards: col.cards.filter((c) => c.key !== key) }
+          : i === to
+            ? { ...col, cards: [...col.cards, card] }
+            : col,
+      );
+    });
+    requestAnimationFrame(() => cardRefs.current.get(key)?.focus());
+  };
+
+  const onCardKey = (e: KeyboardEvent<HTMLElement>, card: Card, colIndex: number) => {
+    if (held === null && e.target === e.currentTarget) {
+      if (onItemContextMenu && isMenuKey(e)) {
+        e.preventDefault();
+        onItemContextMenu(idOf(card), null, e.currentTarget);
+        return;
+      }
+      if (select.onKey(e, idOf(card))) return;
+    }
+    if (readOnly) {
+      if (e.key === "Enter") onOpen?.(card.key);
+      return;
+    }
+    const forward = dir === "rtl" ? "ArrowLeft" : "ArrowRight";
+    const back = dir === "rtl" ? "ArrowRight" : "ArrowLeft";
+    if (e.key === " ") {
+      e.preventDefault();
+      if (held === null) {
+        setHeld({ key: card.key, origin: colIndex, at: colIndex });
+        setAnnouncement(
+          t("board.picked", { title: card.title, column: cols[colIndex]?.label ?? "" }),
+        );
+      } else {
+        const from = cols[held.origin]?.state;
+        const to = cols[held.at]?.state;
+        if (from && to && held.origin !== held.at) onMove?.(held.key, from, to);
+        setAnnouncement(
+          t("board.dropped", { title: card.title, column: cols[held.at]?.label ?? "" }),
+        );
+        setHeld(null);
+      }
+    } else if (held && (e.key === forward || e.key === back)) {
+      e.preventDefault();
+      const to = Math.max(0, Math.min(cols.length - 1, held.at + (e.key === forward ? 1 : -1)));
+      move(held.key, held.at, to);
+      setHeld({ ...held, at: to });
+      setAnnouncement(t("board.moved", { title: card.title, column: cols[to]?.label ?? "" }));
+    } else if (held && e.key === "Escape") {
+      e.preventDefault();
+      move(held.key, held.at, held.origin);
+      setAnnouncement(
+        t("board.returned", { title: card.title, column: cols[held.origin]?.label ?? "" }),
+      );
+      setHeld(null);
+    } else if (e.key === "Enter" && !held) {
+      onOpen?.(card.key);
+    }
+  };
+
+  const onDrop = (e: DragEvent<HTMLElement>, to: number) => {
+    e.preventDefault();
+    const [key, fromText] = e.dataTransfer.getData("text/plain").split("|");
+    const from = Number(fromText);
+    if (!key || Number.isNaN(from)) return;
+    move(key, from, to);
+    const fromState = cols[from]?.state;
+    const toState = cols[to]?.state;
+    if (fromState && toState && from !== to) onMove?.(key, fromState, toState);
+  };
+
+  // Columns that do not fit scroll sideways in a region whose cut-off edge fades (A59-012).
+  return (
+    <ScrollRegion label={t("scroll.region")}>
+      <div className="flex items-start gap-12 w-max min-w-full">
+        {cols.map((col, ci) => (
+          <section
+            key={col.state}
+            aria-label={col.label}
+            onDragOver={readOnly ? undefined : (e) => e.preventDefault()}
+            onDrop={readOnly ? undefined : (e) => onDrop(e, ci)}
+            className="flex flex-none flex-col gap-8 w-(--ui-board-col) p-8 rounded-card bg-bg-surface"
+          >
+            <header className="flex items-center gap-6 p-4">
+              <StateIcon state={col.state} />
+              <h2 className="m-0 text-text-13 font-semibold">{col.label}</h2>
+              <span className="text-text-secondary tabular-nums">{col.cards.length}</span>
+            </header>
+            {col.cards.map((card) => {
+              const selected = select.isSelected(idOf(card));
+              return (
+                <div
+                  key={card.key}
+                  ref={(el) => {
+                    if (el) cardRefs.current.set(card.key, el);
+                    else cardRefs.current.delete(card.key);
+                  }}
+                  role="button"
+                  tabIndex={0}
+                  aria-pressed={held?.key === card.key ? true : undefined}
+                  data-item={idOf(card)}
+                  data-selected={selected ? "" : undefined}
+                  draggable={!readOnly}
+                  onDragStart={(e) => e.dataTransfer.setData("text/plain", `${card.key}|${ci}`)}
+                  onKeyDown={(e) => onCardKey(e, card, ci)}
+                  onDoubleClick={() => onOpen?.(card.key)}
+                  {...(selection
+                    ? {
+                        onClick: (e) => select.onClick(e, idOf(card)),
+                        onMouseDown: (e) => {
+                          // Shift+click selects a range, not the text between.
+                          if (e.shiftKey) e.preventDefault();
+                        },
+                      }
+                    : {})}
+                  {...(onItemContextMenu
+                    ? {
+                        onContextMenu: (e) => {
+                          e.preventDefault();
+                          onItemContextMenu(
+                            idOf(card),
+                            { x: e.clientX, y: e.clientY },
+                            e.currentTarget,
+                          );
+                        },
+                      }
+                    : {})}
+                  className={cx(
+                    "flex flex-col gap-8 p-12 rounded-card border border-border-subtle bg-bg-raised",
+                    "hover:border-border-strong aria-pressed:border-accent aria-pressed:ring-(length:--stroke-width-focus) aria-pressed:ring-accent",
+                    "data-selected:border-accent data-selected:bg-bg-hover",
+                    readOnly ? "cursor-pointer" : "cursor-grab",
+                    "forced-colors:border-[CanvasText]",
+                  )}
+                >
+                  <div className="flex items-center justify-between gap-6">
+                    <span data-column="key" className="font-mono text-text-12 text-text-secondary">
+                      {card.key}
+                    </span>
+                    {card.owner ? <Avatar name={card.owner} /> : null}
+                  </div>
+                  <span data-column="title">{card.title}</span>
+                  {selected ? <span className="sr-only">{t("bulk.itemSelected")}</span> : null}
+                  {card.meta ? (
+                    <span className="text-text-12 text-text-secondary">{card.meta}</span>
+                  ) : null}
+                  {card.kind || card.due ? (
+                    <div className="flex flex-wrap items-center gap-4">
+                      {card.kind ? <RecordKindChip kind={card.kind} /> : null}
+                      {card.due ? <PropertyChip icon="Calendar" value={card.due} /> : null}
+                    </div>
+                  ) : null}
+                </div>
+              );
+            })}
+            {readOnly ? null : (
+              <button
+                type="button"
+                onClick={() => onAdd?.(col.state)}
+                className={cx(buttonClass("ghost"), "justify-start")}
+              >
+                <Icon name="Plus" size={14} />
+                {addLabel ?? t("board.add")}
+              </button>
+            )}
+          </section>
+        ))}
+      </div>
+      <span aria-live="assertive" className="sr-only">
+        {announcement}
+      </span>
+      {selection ? (
+        <span role="status" className="sr-only">
+          {selectedCount > 0 ? t("bulk.selected", { n: fmt.number(selectedCount) }) : ""}
+        </span>
+      ) : null}
+    </ScrollRegion>
+  );
+}

package/src/Views/BulkActionBar.tsx

@@ -0,0 +1,76 @@
+import { type ReactElement } from "react";
+import { Toolbar as RToolbar } from "radix-ui";
+import { cx } from "../lib/cx.ts";
+import { useFormat, useT } from "../lib/context.tsx";
+import { Icon } from "../Icon/Icon.tsx";
+import { buttonClass, iconButtonClass } from "../Button/Button.tsx";
+import { Keys } from "../Kbd/Kbd.tsx";
+import { type BulkActionBarProps } from "./Views.types.ts";
+
+/**
+ * Appears with a selection: the count and at most five actions every selected item allows. A
+ * toolbar: arrow keys move between actions, Esc clears the selection.
+ */
+export function BulkActionBar({
+  count,
+  actions,
+  onClear,
+  onMore,
+  announce = true,
+}: BulkActionBarProps): ReactElement {
+  const t = useT();
+  const fmt = useFormat();
+  return (
+    <RToolbar.Root
+      aria-label={t("bulk.label")}
+      onKeyDown={(e) => {
+        if (e.key === "Escape" && onClear) {
+          e.preventDefault();
+          onClear();
+        }
+      }}
+      className={cx(
+        "xos-anim-fade inline-flex flex-wrap items-center gap-4 max-w-full py-4 ps-12 pe-4",
+        "rounded-card bg-bg-raised shadow-menu print:hidden forced-colors:border",
+      )}
+    >
+      <span className="tabular-nums" {...(announce ? { "aria-live": "polite" as const } : {})}>
+        {t("bulk.selected", { n: fmt.number(count) })}
+      </span>
+      <RToolbar.Separator className="w-(--stroke-width-hairline) h-(--space-16) mx-4 bg-border-strong" />
+      {actions.slice(0, 5).map((action) => (
+        <RToolbar.Button
+          key={action.label}
+          className={buttonClass("ghost", "sm")}
+          onClick={action.onSelect}
+        >
+          {action.icon ? <Icon name={action.icon} size={14} /> : null}
+          {action.label}
+          {action.shortcut ? (
+            <span className="ms-4 inline-flex">
+              <Keys keys={action.shortcut} />
+            </span>
+          ) : null}
+        </RToolbar.Button>
+      ))}
+      {onMore ? (
+        <RToolbar.Button
+          className={iconButtonClass()}
+          aria-label={t("menu.more")}
+          title={t("menu.more")}
+          onClick={onMore}
+        >
+          <Icon name="Ellipsis" />
+        </RToolbar.Button>
+      ) : null}
+      <RToolbar.Button
+        className={iconButtonClass()}
+        aria-label={t("bulk.clear")}
+        title={t("tooltip.withShortcut", { label: t("bulk.clear"), shortcut: t("key.esc") })}
+        onClick={onClear}
+      >
+        <Icon name="X" />
+      </RToolbar.Button>
+    </RToolbar.Root>
+  );
+}