@superxd-studio/adptr 0.5.0

package/source/reusable/web/review/index.tsx

@@ -0,0 +1,506 @@
+import { CanvasSequence, CanvasStage } from "../../../components/canvas/index.js";
+import { canvasCopy } from "../../../components/canvas/copy.js";
+import {
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react";
+import { Checkbox, Disclosure, DisclosurePanel, Button as AriaButton } from "react-aria-components";
+import { Button } from "../../../components/button.js";
+import { Callout } from "../../../components/callout.js";
+import { Spinner } from "../../../components/spinner.js";
+import { IconCheck, IconChevronDown } from "../../../components/icons.js";
+import { FlowFrame, FlowStep, runFlow } from "../../../components/flow-motion.js";
+import { cn } from "../../../lib/cn.js";
+import type { ReviewChange, ReviewSnapshot } from "../../review/types.js";
+import type { ReviewController } from "../../review/controller.js";
+import { reviewCopy, type ReviewCopy } from "./copy.js";
+import { reviewFlow } from "./flow.js";
+export { reviewCopy } from "./copy.js";
+export type { ReviewCopy } from "./copy.js";
+export interface ReviewChangeCardProps {
+  change: ReviewChange;
+  isSelected?: boolean;
+  onSelectionChange?: (selected: boolean) => void;
+  isDisabled?: boolean;
+  isApplied?: boolean;
+  isExpanded?: boolean;
+  onExpandedChange?: (expanded: boolean) => void;
+  /** Side-by-side comparison on a roomy canvas. The content remains the same. */
+  comparison?: "columns" | "stacked";
+  copy?: ReviewCopy;
+}
+export function ReviewChangeCard({
+  change,
+  isSelected = false,
+  onSelectionChange,
+  isDisabled = false,
+  isApplied = false,
+  isExpanded = true,
+  onExpandedChange,
+  comparison = "stacked",
+  copy = reviewCopy,
+}: ReviewChangeCardProps) {
+  return (
+    <Disclosure
+      isExpanded={isExpanded}
+      onExpandedChange={onExpandedChange}
+      className={cn(
+        "min-w-0 overflow-hidden rounded-surface border bg-surface shadow-control",
+        isSelected ? "border-line-emphasis" : "border-line-subtle",
+      )}
+    >
+      <div className="flex min-w-0 items-center gap-3 px-5 py-4">
+        <Checkbox
+          isSelected={isApplied || isSelected}
+          onChange={onSelectionChange}
+          isDisabled={isDisabled || isApplied || !onSelectionChange}
+          aria-label={copy.selectChange(change.title)}
+          className="group flex min-h-control-md min-w-0 flex-1 cursor-pointer items-center gap-3 rounded-control type-label text-fg-emphasis outline-none data-disabled:cursor-default data-focus-visible:focus-ring"
+        >
+          <span
+            className={cn(
+              "grid size-5 shrink-0 place-items-center rounded-control border",
+              isSelected
+                ? "border-brand bg-brand text-on-brand"
+                : "border-line-emphasis bg-surface",
+              isApplied && "border-success-line bg-success-subtle text-success",
+            )}
+          >
+            {isApplied || isSelected ? <IconCheck className="size-3.5" /> : null}
+          </span>
+          <span className="min-w-0 break-words">{change.title}</span>
+        </Checkbox>
+        {isApplied ? (
+          <span className="rounded-pill bg-success-subtle px-2.5 py-1 type-caption text-success">
+            {copy.applied}
+          </span>
+        ) : null}
+        <AriaButton
+          slot="trigger"
+          aria-label={copy.viewChange(change.title)}
+          className="grid size-control-md shrink-0 place-items-center rounded-control text-fg-subtle outline-none data-focus-visible:focus-ring data-hovered:bg-surface-muted"
+        >
+          <IconChevronDown
+            className={cn(
+              "transition-transform duration-(--duration-fast) ease-standard",
+              isExpanded && "rotate-180",
+            )}
+          />
+        </AriaButton>
+      </div>
+      <DisclosurePanel className="border-t border-line-subtle">
+        <div className={cn("grid min-w-0", comparison === "columns" && "grid-cols-2")}>
+          <Comparison label={copy.before} muted>
+            {change.before}
+          </Comparison>
+          <Comparison label={copy.after}>{change.after}</Comparison>
+        </div>
+        <p className="border-t border-line-subtle px-5 py-3 type-caption text-fg-subtle">
+          <span className="sr-only">{copy.reason}: </span>
+          {change.reason}
+        </p>
+      </DisclosurePanel>
+    </Disclosure>
+  );
+}
+function Comparison({
+  label,
+  children,
+  muted = false,
+}: {
+  label: string;
+  children: ReactNode;
+  muted?: boolean;
+}) {
+  return (
+    <div className={cn("min-w-0 px-5 py-4", muted ? "bg-surface-muted" : "bg-surface")}>
+      <p className="mb-2 font-mono type-caption text-fg-subtle">{label}</p>
+      <p className="type-body break-words text-fg">{children}</p>
+    </div>
+  );
+}
+export interface ReviewDecisionPanelProps {
+  snapshot: ReviewSnapshot;
+  headingLevel?: 2 | 3;
+  onReview: () => void;
+  onDecline: () => void;
+  onConfirm: () => void;
+  onBack: () => void;
+  onRecover: () => void;
+  onReload: () => void;
+  copy?: ReviewCopy;
+}
+/** Provider-free decision display. The controller and the server, not this panel, own authority. */
+export function ReviewDecisionPanel({
+  snapshot: s,
+  headingLevel = 2,
+  onReview,
+  onDecline,
+  onConfirm,
+  onBack,
+  onRecover,
+  onReload,
+  copy = reviewCopy,
+}: ReviewDecisionPanelProps) {
+  const Heading = headingLevel === 2 ? "h2" : "h3";
+  const { record, decision, status } = s;
+  const selected = decision?.changeIds ?? s.selectedIds;
+  const total = record?.remainingIds.length ?? 0;
+  const confirming = status === "confirming" || status === "submitting";
+  const deny = decision?.choice === "deny";
+  const title = confirming
+    ? deny
+      ? record?.appliedIds.length
+        ? copy.declineRemainingTitle
+        : copy.denyConfirm
+      : copy.confirm
+    : status === "complete"
+      ? copy.complete(record?.appliedIds.length ?? 0)
+      : status === "denied"
+        ? copy.denied
+        : copy.summary;
+  const ready = status === "ready" || status === "partial";
+  const done = status === "complete";
+  // The panel's own steps: choosing, confirming, and the outcome. Moving between them inks
+  // the new content in while the panel resizes (see flow-motion.tsx).
+  const step = confirming ? "confirm" : done || status === "denied" ? "outcome" : "choose";
+  return (
+    <FlowFrame>
+      <section
+        aria-label={copy.summary}
+        className="min-w-0 rounded-surface border border-line-subtle bg-surface p-5"
+      >
+        <FlowStep key={step}>
+          <div className="flex min-w-0 flex-col gap-5">
+            <div className="flex items-center gap-3">
+              {/* Done earns SuperXD's ultramarine: the mark pops in, then the check lands */}
+              {done ? (
+                <span className="flex size-8 shrink-0 animate-done-in items-center justify-center rounded-pill bg-done text-on-done">
+                  <IconCheck className="animate-done-in [animation-delay:var(--duration-pop)]" />
+                </span>
+              ) : null}
+              <Heading
+                tabIndex={-1}
+                data-review-focus
+                className="type-heading text-fg-emphasis outline-none"
+              >
+                {title}
+              </Heading>
+            </div>
+            {record && !["complete", "denied"].includes(status) ? (
+              <div className="flex min-w-0 flex-col gap-1">
+                <p className="font-mono type-caption text-fg-subtle">{copy.target}</p>
+                <p className="type-label break-words text-fg-emphasis">
+                  {record.proposal.destination}
+                </p>
+              </div>
+            ) : null}
+            {ready || (confirming && !deny) ? (
+              <div className="flex flex-col gap-3">
+                <p className="type-label text-fg-emphasis">
+                  {copy.selected(selected.length, total)}
+                </p>
+                {selected.length ? (
+                  <ul className="flex flex-col gap-2 type-body text-fg">
+                    {record?.proposal.changes
+                      .filter((c) => selected.includes(c.id))
+                      .map((c) => (
+                        <li key={c.id} className="flex items-start gap-2">
+                          <IconCheck className="mt-0.5" />
+                          <span className="min-w-0 break-words">{c.title}</span>
+                        </li>
+                      ))}
+                  </ul>
+                ) : (
+                  <p className="type-body text-fg-subtle">{copy.noSelection}</p>
+                )}
+                {confirming ? (
+                  <p className="type-body text-fg-subtle">{copy.approvalNote}</p>
+                ) : null}
+              </div>
+            ) : null}
+            {confirming && deny ? (
+              <p className="type-body text-fg-subtle">
+                {record?.appliedIds.length ? copy.declineRemainingNote : copy.denyNote}
+              </p>
+            ) : null}
+            {s.issue === "not-applied" ? (
+              <Callout tone="attention" title={copy.notApplied}>
+                {copy.notAppliedNote}
+              </Callout>
+            ) : null}
+            {status === "uncertain" || status === "checking" ? (
+              <Callout tone="attention" title={copy.uncertain}>
+                {copy.uncertainNote}
+              </Callout>
+            ) : null}
+            {status === "conflict" ? (
+              <Callout tone="attention" title={copy.conflict}>
+                {copy.conflictNote}
+              </Callout>
+            ) : null}
+            {status === "blocked" ? (
+              <Callout title={copy.blocked}>{copy.blockedNote}</Callout>
+            ) : null}
+            {status === "partial" ? (
+              <Callout tone="attention" title={copy.partial(record?.appliedIds.length ?? 0, total)}>
+                {copy.partialNote}
+              </Callout>
+            ) : null}
+            {status === "complete" ? (
+              <Callout tone="success">
+                {copy.kept(
+                  (record?.proposal.changes.length ?? 0) - (record?.appliedIds.length ?? 0),
+                )}
+              </Callout>
+            ) : null}
+            {status === "denied" ? (
+              <p className="type-body text-fg-subtle">{copy.deniedNote}</p>
+            ) : null}
+            <div className="flex flex-col gap-2">
+              {ready ? (
+                <>
+                  <Button variant="primary" isDisabled={!s.selectedIds.length} onPress={onReview}>
+                    {copy.review(s.selectedIds.length)}
+                  </Button>
+                  <Button variant="ghost" onPress={onDecline}>
+                    {record?.appliedIds.length ? copy.declineRemaining : copy.deny}
+                  </Button>
+                </>
+              ) : null}
+              {confirming ? (
+                <>
+                  <Button
+                    variant="primary"
+                    isPending={status === "submitting"}
+                    pendingLabel={copy.applying}
+                    onPress={onConfirm}
+                  >
+                    {deny ? copy.denyAction : copy.apply(selected.length)}
+                  </Button>
+                  {s.issue === "not-applied" ? (
+                    <Button variant="secondary" onPress={onRecover}>
+                      {copy.check}
+                    </Button>
+                  ) : (
+                    <Button variant="ghost" isDisabled={status === "submitting"} onPress={onBack}>
+                      {copy.back}
+                    </Button>
+                  )}
+                </>
+              ) : null}
+              {status === "uncertain" || status === "checking" ? (
+                <Button
+                  isPending={status === "checking"}
+                  pendingLabel={copy.checking}
+                  onPress={onRecover}
+                >
+                  {copy.check}
+                </Button>
+              ) : null}
+              {status === "conflict" ? <Button onPress={onReload}>{copy.reload}</Button> : null}
+            </div>
+          </div>
+        </FlowStep>
+      </section>
+    </FlowFrame>
+  );
+}
+export function useReview(controller: ReviewController) {
+  const snapshot = useSyncExternalStore(
+    controller.subscribe,
+    controller.getSnapshot,
+    controller.getSnapshot,
+  );
+  useEffect(() => {
+    controller.load();
+  }, [controller]);
+  return snapshot;
+}
+export interface DraftReviewProps {
+  controller: ReviewController;
+  copy?: ReviewCopy;
+  className?: string;
+}
+/** The task survives container changes. A comparison becomes stacked disclosure on smaller canvases. */
+/**
+ * Like useReview, but a change of step runs as a flow transition. (A store read with
+ * useSyncExternalStore always updates at once, so it can't take part in one.)
+ */
+function useReviewFlow(controller: ReviewController) {
+  const [snapshot, setSnapshot] = useState(controller.getSnapshot);
+  useEffect(() => {
+    let last = controller.getSnapshot();
+    const update = () => {
+      const next = controller.getSnapshot();
+      const type = reviewFlow(last.status, next.status);
+      last = next;
+      runFlow(type, () => setSnapshot(next));
+    };
+    const unsubscribe = controller.subscribe(update);
+    update();
+    controller.load();
+    return unsubscribe;
+  }, [controller]);
+  return snapshot;
+}
+
+export function DraftReview(props: DraftReviewProps) {
+  return (
+    <CanvasSequence>
+      <ReviewSession {...props} />
+    </CanvasSequence>
+  );
+}
+function ReviewSession({ controller, copy = reviewCopy, className }: DraftReviewProps) {
+  const snapshot = useReviewFlow(controller);
+  const root = useRef<HTMLDivElement>(null);
+  const focusAfterAction = useRef(false);
+  const [roomy, setRoomy] = useState(false);
+  const [expanded, setExpanded] = useState<Readonly<Record<string, boolean>>>({});
+  const titleId = useId();
+  useEffect(() => {
+    if (!root.current) return;
+    const element = root.current;
+    const observer = new ResizeObserver(([entry]) => {
+      const rem = Number.parseFloat(getComputedStyle(document.documentElement).fontSize);
+      const breakpoint =
+        Number.parseFloat(getComputedStyle(element).getPropertyValue("--breakpoint-md")) || 48;
+      setRoomy((entry?.contentRect.width ?? 0) >= breakpoint * rem);
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+  useLayoutEffect(() => {
+    if (
+      focusAfterAction.current &&
+      !["submitting", "checking", "loading"].includes(snapshot.status)
+    ) {
+      // Restore within this task only; moving to another part of the page is respected.
+      if (
+        root.current?.contains(document.activeElement) ||
+        document.activeElement === document.body
+      )
+        root.current?.querySelector<HTMLElement>("[data-review-focus]")?.focus();
+      focusAfterAction.current = false;
+    }
+  }, [snapshot.status]);
+  function action(callback: () => boolean) {
+    if (callback()) focusAfterAction.current = true;
+  }
+  const { record, status } = snapshot;
+  // Loading, a failed load and the review itself are separate steps: the review inks in
+  const phase =
+    status === "idle" || status === "loading"
+      ? "loading"
+      : status === "load-error"
+        ? "error"
+        : "review";
+  const busy = ["idle", "loading", "submitting", "checking"].includes(status);
+  const label = {
+    idle: canvasCopy.loading,
+    loading: canvasCopy.loading,
+    ready: canvasCopy.review,
+    confirming: canvasCopy.confirm,
+    submitting: canvasCopy.applying,
+    checking: canvasCopy.checking,
+    "load-error": canvasCopy.failed,
+    uncertain: canvasCopy.uncertain,
+    conflict: canvasCopy.conflict,
+    blocked: canvasCopy.blocked,
+    partial: canvasCopy.partial,
+    complete: canvasCopy.complete,
+    denied: canvasCopy.denied,
+  }[status];
+  return (
+    <CanvasStage
+      phase={`review-${status}-${snapshot.issue ?? ""}`}
+
+      frameClassName={className}
+      label={label}
+      terminal={status === "complete" || status === "denied"}
+    >
+      <div
+        ref={root}
+        className={cn("@container w-full min-w-0 text-fg", className)}
+        aria-busy={busy}
+        data-review-status={status}
+      >
+        <p className="sr-only" role="status" aria-live="polite">
+          {copy.announcement[status]}
+        </p>
+        <header className="mb-6 flex flex-col gap-2">
+          <p className="font-mono type-caption text-fg-subtle">{copy.proposed}</p>
+          <h2 id={titleId} className="type-title text-fg-emphasis">
+            {record?.proposal.title ?? copy.loading}
+          </h2>
+        </header>
+        <FlowStep key={phase}>
+          <div className="min-w-0">
+            {status === "idle" || status === "loading" ? (
+              <div className="flex min-h-64 items-center justify-center gap-3 rounded-surface border border-line-subtle bg-surface">
+                <Spinner />
+                <p className="type-body text-fg-subtle">{copy.loadingNote}</p>
+              </div>
+            ) : status === "load-error" ? (
+              <Callout
+                tone="error"
+                title={copy.loadError}
+                actions={<Button onPress={() => action(controller.load)}>{copy.retry}</Button>}
+              >
+                {copy.loadErrorNote}
+              </Callout>
+            ) : record && !record.proposal.changes.length ? (
+              <Callout title={copy.empty}>{copy.emptyNote}</Callout>
+            ) : (
+              <div className="grid min-w-0 items-start gap-6 @3xl:grid-cols-3">
+                <div className="flex min-w-0 flex-col gap-3 @3xl:col-span-2">
+                  <ul aria-labelledby={titleId} className="flex min-w-0 flex-col gap-3">
+                    {record?.proposal.changes.map((change) => (
+                      <li key={`${record.proposal.id}-${change.id}`}>
+                        <ReviewChangeCard
+                          change={change}
+                          isSelected={snapshot.selectedIds.includes(change.id)}
+                          isApplied={record.appliedIds.includes(change.id)}
+                          isDisabled={
+                            !["ready", "partial"].includes(status) ||
+                            !record.remainingIds.includes(change.id)
+                          }
+                          onSelectionChange={(selected) => controller.select(change.id, selected)}
+                          isExpanded={expanded[change.id] ?? true}
+                          onExpandedChange={(open) =>
+                            setExpanded((value) => ({ ...value, [change.id]: open }))
+                          }
+                          comparison={roomy ? "columns" : "stacked"}
+                          copy={copy}
+                        />
+                      </li>
+                    ))}
+                  </ul>
+                </div>
+                <div className="min-w-0 @3xl:sticky @3xl:top-6">
+                  <ReviewDecisionPanel
+                    snapshot={snapshot}
+                    headingLevel={3}
+                    onReview={() => action(() => controller.prepare("approve"))}
+                    onDecline={() => action(() => controller.prepare("deny"))}
+                    onConfirm={() => action(controller.submit)}
+                    onBack={() => action(controller.back)}
+                    onRecover={() => action(controller.recover)}
+                    onReload={() => action(controller.load)}
+                    copy={copy}
+                  />
+                </div>
+              </div>
+            )}
+          </div>
+        </FlowStep>
+      </div>
+    </CanvasStage>
+  );
+}

package/source/reusable/web/styles.ts

@@ -0,0 +1,2 @@
+import "../../styles/library.css";
+import "./message/styles.css";