@superxd-studio/adptr 0.5.0

package/source/components/canvas/index.tsx

@@ -0,0 +1,257 @@
+import {
+  Children,
+  cloneElement,
+  isValidElement,
+  createContext,
+  useContext,
+  useId,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { canvasCopy as copy } from "./copy";
+import { createCanvasRecorder, type RecordableFrame } from "./recorder";
+import { cn } from "../../lib/cn";
+import { CanvasConnector } from "./connector";
+
+/** The visitor canvas opts in; exported product components keep their usual single screen. */
+export const CanvasModeContext = createContext(false);
+export const CanvasPastContext = createContext(false);
+/** null disables observation; false records quietly; true also displays the recorded states. */
+export const CanvasObservationContext = createContext<boolean | null>(null);
+export type CanvasFrame = RecordableFrame & {
+  label: string;
+  node: ReactNode;
+  /** The same width constraint as the component; caption and content share this frame. */
+  className?: string;
+};
+const RunContext = createContext<((frame: CanvasFrame) => void) | null>(null);
+const ObservationContext = createContext<((frame: CanvasFrame, source: string) => void) | null>(
+  null,
+);
+
+export function useCanvasObserver() {
+  const publish = useContext(ObservationContext);
+  const historical = useContext(CanvasPastContext);
+  return historical ? null : publish;
+}
+
+/** The live demo is mounted once. Recording never moves focus or executes historical actions. */
+function ObservationRun({ children }: { children: ReactNode }) {
+  const shown = useContext(CanvasObservationContext);
+  const [frames, setFrames] = useState<CanvasFrame[]>([]);
+  const [recorder] = useState(() => createCanvasRecorder<CanvasFrame>());
+  const [publish] = useState(() => (frame: CanvasFrame, source: string) => {
+    const next = recorder({ ...frame, node: historicalNode(frame.node) }, source);
+    if (next) setFrames(next);
+  });
+  return (
+    <div className="flex min-w-0 flex-col gap-20" data-observed-canvas>
+      <div
+        data-live-demo
+        data-canvas-current="true"
+        data-current="true"
+        className="min-w-0"
+        onPointerDownCapture={recorder.start}
+        onKeyDownCapture={recorder.start}
+        onClickCapture={recorder.start}
+      >
+        <ObservationContext.Provider value={publish}>{children}</ObservationContext.Provider>
+      </div>
+      <div
+        data-state-history
+        hidden={!shown || !frames.length}
+        className="flex min-w-0 flex-col gap-20 empty:hidden"
+      >
+        {frames.map((frame, index) => (
+          <div
+            key={index}
+            data-canvas-phase={frame.phase}
+            data-canvas-snapshot
+            data-canvas-current="false"
+            data-current="false"
+            data-generative-step={
+              frame.phase.startsWith("generative-") ? frame.phase.split("-")[1] : undefined
+            }
+            className={cn("relative mx-auto w-full min-w-0", frame.className)}
+          >
+            {index > 0 ? <CanvasConnector /> : null}
+            <Caption index={index} label={frame.label} previous={index < frames.length - 1} />
+            <div data-canvas-content inert aria-hidden="true">
+              <CanvasPastContext.Provider value={true}>{frame.node}</CanvasPastContext.Provider>
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export function CanvasSequence({ children }: { children: ReactNode }) {
+  const enabled = useContext(CanvasModeContext);
+  const parent = useContext(RunContext);
+  const observation = useContext(CanvasObservationContext);
+  const observing = useContext(ObservationContext);
+  const historical = useContext(CanvasPastContext);
+  if (observation !== null && !observing && !historical)
+    return <ObservationRun>{children}</ObservationRun>;
+  return enabled && !parent ? <Run>{children}</Run> : children;
+}
+
+function Run({ children }: { children: ReactNode }) {
+  const [past, setPast] = useState<CanvasFrame[]>([]);
+  const [current, setCurrent] = useState<Omit<CanvasFrame, "node"> | null>(null);
+  const last = useRef<CanvasFrame | null>(null);
+  const root = useRef<HTMLDivElement>(null);
+  const initiated = useRef(false);
+  const [publish] = useState(() => (frame: CanvasFrame) => {
+    const previous = last.current;
+    if (previous?.terminal) return;
+    if (previous && previous.phase !== frame.phase)
+      setPast((frames) => [...frames, { ...previous, node: historicalNode(previous.node) }]);
+    last.current = frame;
+    setCurrent((prior) =>
+      prior?.phase === frame.phase &&
+      prior.label === frame.label &&
+      prior.terminal === frame.terminal
+        ? prior
+        : { phase: frame.phase, label: frame.label, terminal: frame.terminal },
+    );
+  });
+  useEffect(() => {
+    if (!initiated.current || !current) return;
+    const active = root.current?.querySelector<HTMLElement>('[data-canvas-current="true"]');
+    if (!active) return;
+    // The live owner may already have focused its next field or confirmation heading.
+    if (!active.contains(document.activeElement)) active.focus({ preventScroll: true });
+    active.scrollIntoView({ block: "nearest", behavior: "instant" });
+  }, [current]);
+  return (
+    <div
+      ref={root}
+      data-canvas-sequence
+      className="flex w-full min-w-0 flex-col gap-20"
+      onPointerDownCapture={() => {
+        initiated.current = true;
+      }}
+      onKeyDownCapture={() => {
+        initiated.current = true;
+      }}
+    >
+      {past.map((frame, index) => (
+        <div
+          key={index}
+          data-canvas-phase={frame.phase}
+          data-canvas-current="false"
+          className={cn("relative mx-auto w-full min-w-0", frame.className)}
+        >
+          {index > 0 ? <CanvasConnector /> : null}
+          <Caption index={index} label={frame.label} previous />
+          <div inert aria-hidden="true">
+            <CanvasPastContext.Provider value={true}>{frame.node}</CanvasPastContext.Provider>
+          </div>
+        </div>
+      ))}
+      <div
+        data-canvas-phase={current?.phase}
+        data-canvas-current="true"
+        data-canvas-terminal={current?.terminal || undefined}
+        tabIndex={-1}
+        className="relative min-w-0 scroll-mt-6 outline-none"
+      >
+        {past.length > 0 ? <CanvasConnector /> : null}
+        {current ? <Caption index={past.length} label={current.label} /> : null}
+        <RunContext.Provider value={publish}>{children}</RunContext.Provider>
+      </div>
+    </div>
+  );
+}
+
+function Caption({ index, label, previous }: { index: number; label: string; previous?: boolean }) {
+  return (
+    <div
+      data-canvas-caption
+      className="mb-3 flex flex-wrap justify-between gap-2 font-mono type-caption text-system-blue"
+    >
+      <span>
+        {String(index + 1).padStart(2, "0")} {label}
+      </span>
+      {previous ? <span>{copy.previous}</span> : null}
+    </div>
+  );
+}
+
+/** Publish presentation only: historical frames never mount another controller or adapter. */
+export function CanvasStage({
+  phase,
+  label,
+  terminal = false,
+  frameClassName,
+  snapshot,
+  children,
+}: {
+  phase: string;
+  label: string;
+  terminal?: boolean;
+  frameClassName?: string;
+  /** Complete presentation for a snapshot when the live content inherits a parent surface. */
+  snapshot?: ReactNode;
+  children: ReactNode;
+}) {
+  const publish = useContext(RunContext);
+  const observe = useCanvasObserver();
+  const source = useId();
+  const historical = useContext(CanvasPastContext);
+  useLayoutEffect(() => {
+    if (!historical) publish?.({ phase, label, terminal, node: children });
+    observe?.(
+      { phase, label, terminal, className: frameClassName, node: snapshot ?? children },
+      source,
+    );
+  }, [
+    publish,
+    observe,
+    source,
+    historical,
+    phase,
+    label,
+    terminal,
+    frameClassName,
+    snapshot,
+    children,
+  ]);
+  return children;
+}
+
+export function historicalNode(node: ReactNode): ReactNode {
+  return Children.map(node, (child) => {
+    if (!isValidElement<Record<string, unknown>>(child)) return child;
+    // Shared DOM/measurement refs belong to the live view, never its retained presentation.
+    const props: Record<string, unknown> = {};
+    if ("ref" in child.props) props.ref = null;
+    for (const name of ["measureRef", "triggerRef", "eventTriggerRef"])
+      if (name in child.props) props[name] = undefined;
+    // Retained headings must not own IDs that the current view uses for its accessible name.
+    if (typeof child.type === "string") {
+      for (const name of ["id", "aria-labelledby", "aria-describedby", "htmlFor"])
+        if (name in child.props) props[name] = undefined;
+    }
+    if ("autoFocus" in child.props) props.autoFocus = false;
+    if ("children" in child.props)
+      props.children = historicalNode(child.props.children as ReactNode);
+    return cloneElement(child, props);
+  });
+}
+
+/** Let a host-owned destination add its local steps to the existing response canvas. */
+export function CanvasStageBridge({
+  publish,
+  children,
+}: {
+  publish: (frame: CanvasFrame) => void;
+  children: ReactNode;
+}) {
+  return <RunContext.Provider value={publish}>{children}</RunContext.Provider>;
+}

package/source/components/canvas/recorder.ts

@@ -0,0 +1,36 @@
+export interface RecordableFrame {
+  phase: string;
+  terminal: boolean;
+  /** A result with its own stages replaces this enclosing result with its first child stage. */
+  yieldToChild?: boolean;
+}
+
+/** Records transitions, never the initial demo or a second copy of a nested result. */
+export function createCanvasRecorder<T extends RecordableFrame>() {
+  let active = false;
+  let frames: T[] = [];
+  let latestSource: string | undefined;
+  const seen = new Map<string, string>();
+  const record = (frame: T, source: string): T[] | undefined => {
+    const last = frames.at(-1);
+    if (last?.terminal) return;
+    const samePhase = seen.get(source) === frame.phase;
+    // Background parents (for example the calendar behind an event) are not new steps.
+    if (samePhase && source !== latestSource) return;
+    seen.set(source, frame.phase);
+    // Mounting, loading fixtures and typing in the entry screen are not new steps.
+    if (!active || (!frames.length && samePhase)) {
+      latestSource = source;
+      return;
+    }
+    const replace = samePhase || (last?.yieldToChild && source !== latestSource);
+    latestSource = source;
+    frames = replace ? [...frames.slice(0, -1), frame] : [...frames, frame];
+    return frames;
+  };
+  return Object.assign(record, {
+    start: () => {
+      active = true;
+    },
+  });
+}

package/source/components/date-time-field.tsx

@@ -0,0 +1,77 @@
+import { parseDate, parseTime } from "@internationalized/date";
+import {
+  DateField,
+  DateInput,
+  DateSegment,
+  FieldError,
+  I18nProvider,
+  Label,
+  TimeField,
+} from "react-aria-components";
+import { cn } from "../lib/cn.js";
+
+export interface DateTimeFieldProps {
+  label: string;
+  value: string;
+  onChange: (value: string) => void;
+  error?: string;
+  isDisabled?: boolean;
+  kind: "date" | "time";
+  className?: string;
+}
+
+/** Segmented keyboard entry, using the same height, padding and focus treatment as text fields. */
+export function DateTimeField({
+  label,
+  value,
+  onChange,
+  error,
+  isDisabled,
+  kind,
+  className,
+}: DateTimeFieldProps) {
+  const children = (
+    <>
+      <Label className="type-label text-fg-emphasis">{label}</Label>
+      <DateInput className="flex h-control-md items-center rounded-control border border-line-input bg-surface px-control-md-x type-body text-fg-emphasis shadow-control outline-none data-disabled:bg-surface-muted data-disabled:text-fg-muted data-focus-within:border-brand data-focus-within:ring-2 data-focus-within:ring-brand/15 data-invalid:border-error">
+        {(segment) => (
+          <DateSegment
+            segment={segment}
+            className="rounded-cell px-0.5 numeric outline-none data-focused:bg-brand data-focused:text-on-brand data-placeholder:text-fg-subtle"
+          />
+        )}
+      </DateInput>
+      <FieldError className="type-caption text-error">{error}</FieldError>
+    </>
+  );
+  const props = {
+    isInvalid: Boolean(error),
+    isDisabled,
+    isRequired: true,
+    validationBehavior: "aria" as const,
+    className: cn("flex min-w-0 flex-col gap-1.5", className),
+  };
+  return (
+    <I18nProvider locale="en-AU">
+      {kind === "date" ? (
+        <DateField
+          {...props}
+          value={value ? parseDate(value) : null}
+          onChange={(date) => onChange(date?.toString() ?? "")}
+        >
+          {children}
+        </DateField>
+      ) : (
+        <TimeField
+          {...props}
+          hourCycle={24}
+          granularity="minute"
+          value={value ? parseTime(value) : null}
+          onChange={(time) => onChange(time ? time.toString().slice(0, 5) : "")}
+        >
+          {children}
+        </TimeField>
+      )}
+    </I18nProvider>
+  );
+}

package/source/components/flow-motion.tsx

@@ -0,0 +1,109 @@
+import {
+  addTransitionType,
+  createContext,
+  startTransition,
+  useContext,
+  useId,
+  ViewTransition,
+  type ReactNode,
+} from "react";
+
+/*
+ * How a flow moves between its steps (booking, reviewing a draft). Each step change runs as
+ * one view transition: the old step lifts away, the next one inks in from the top, the frame
+ * resizes to fit, and parts that carry over travel to their new place. The look lives in
+ * library.css ("Flow transitions"); this file says when a change is a step and which way it
+ * goes. Reduced motion gets the next step at once.
+ */
+
+/** The view transition types a step change is tagged with. */
+export const FLOW = {
+  forward: "flow-forward",
+  back: "flow-back",
+  swap: "flow-swap",
+} as const;
+export type FlowType = (typeof FLOW)[keyof typeof FLOW];
+
+/** Forward or back between two step positions, or null when the step stays the same. */
+export function flowDirection(from: number, to: number): FlowType | null {
+  return to > from ? FLOW.forward : to < from ? FLOW.back : null;
+}
+
+/**
+ * Runs a state update as a step transition of the given type, or at once when there's none.
+ * Pass the start function from useTransition to know while the step is still on its way.
+ */
+export function runFlow(
+  type: FlowType | null,
+  update: () => void,
+  start: (callback: () => void) => void = startTransition,
+) {
+  if (!type) return update();
+  start(() => {
+    addTransitionType(type);
+    update();
+  });
+}
+
+/** Class names per type: a step change inks in, a swap (a different view of the same step) fades. */
+const each = (step: string, swap: string) => ({
+  [FLOW.forward]: `flow-motion ${step}`,
+  [FLOW.back]: `flow-motion ${step}`,
+  [FLOW.swap]: `flow-motion ${swap}`,
+  default: "none",
+});
+
+/** The flow's frame: it resizes to the next step instead of jumping. Its child must be one element. */
+export function FlowFrame({ children }: { children: ReactNode }) {
+  return (
+    <ViewTransition default="none" update={each("flow-card", "flow-card")}>
+      {children}
+    </ViewTransition>
+  );
+}
+
+/** One step's content. Give it a key per step, so the new step enters and the old one leaves. */
+export function FlowStep({ children }: { children: ReactNode }) {
+  return (
+    <ViewTransition
+      default="none"
+      enter={each("flow-in", "flow-in-swap")}
+      exit={each("flow-out", "flow-out-swap")}
+    >
+      {children}
+    </ViewTransition>
+  );
+}
+
+const NamesContext = createContext<string | null>(null);
+
+/** Gives one flow its own names, so two flows on a page never claim the same moving part. */
+export function FlowNames({ children }: { children: ReactNode }) {
+  const id = useId().replace(/[^\w-]/g, "");
+  return <NamesContext value={`flow-${id}`}>{children}</NamesContext>;
+}
+
+/**
+ * A part that carries over from one step to the next. A part that travels (the chosen time,
+ * from the list into the summary) moves to its new place; the others (the host, the event's
+ * name) stay put while the rest changes. Its child must be one element. Outside FlowNames, it
+ * renders the child as it is.
+ */
+export function FlowShared({
+  part,
+  travel = false,
+  children,
+}: {
+  part: string;
+  travel?: boolean;
+  children: ReactNode;
+}) {
+  const prefix = useContext(NamesContext);
+  if (!prefix) return children;
+  const share = travel ? "flow-motion flow-travel" : "flow-motion flow-keep";
+  return (
+    <ViewTransition name={`${prefix}-${part}`} default="none" share={each(share, share)}>
+      {children}
+    </ViewTransition>
+  );
+}