@multiplatform.one/components 6.1.0 → 6.4.0

package/src/actions/ActionBar.spec.tsx

@@ -0,0 +1,166 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { Button } from "@multiplatform.one/forms";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { fireEvent, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { DialogRegionContext } from "../surfaces";
+import { ActionBar } from "./ActionBar";
+import { __resetActionDevWarnSeen } from "./devWarn";
+
+/** Simulates rendering inside a `DialogContent` surface (DG-OVL-04 scope). */
+function inDialogRegion(ui: ReactNode) {
+  return (
+    <DialogRegionContext.Provider value={{ inDialogRegion: true }}>
+      {ui}
+    </DialogRegionContext.Provider>
+  );
+}
+
+describe("ActionBar", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    __resetActionDevWarnSeen();
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    __resetActionDevWarnSeen();
+  });
+
+  it("renders cancel → secondary → primary (trailing primary)", () => {
+    const { container } = renderWithProviders(
+      <ActionBar
+        id="save-bar"
+        cancel={<Button actionRole="chrome">Cancel</Button>}
+        secondary={<Button actionRole="secondary">Draft</Button>}
+        primary={<Button accent>Save</Button>}
+      />,
+    );
+    const texts = Array.from(container.querySelectorAll('[role="button"]')).map(
+      (el) => el.textContent,
+    );
+    expect(texts).toEqual(["Cancel", "Draft", "Save"]);
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("DEV warns when two accent/primary actions appear in one region", () => {
+    renderWithProviders(
+      <ActionBar id="dup">
+        <Button accent>Save</Button>
+        <Button accent>Publish</Button>
+      </ActionBar>,
+    );
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("two-primaries"));
+  });
+
+  it("does not warn for a single primary slot", () => {
+    renderWithProviders(
+      <ActionBar id="ok" primary={<Button accent verb="Save" noun="document" />} />,
+    );
+    expect(screen.getByText("Save document")).toBeInTheDocument();
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("strips disabled from the cancel slot and warns cancel-disabled (DG-ACT-05)", () => {
+    const onClick = vi.fn();
+    const { container } = renderWithProviders(
+      <ActionBar
+        id="strip"
+        cancel={
+          <button type="button" disabled onClick={onClick}>
+            Cancel
+          </button>
+        }
+        primary={<Button accent>Save</Button>}
+      />,
+    );
+    const cancelEl = container.querySelector("button") as HTMLButtonElement;
+    expect(cancelEl).toBeTruthy();
+    expect(cancelEl.disabled).toBe(false);
+    expect(cancelEl.getAttribute("data-mp-cancel-disabled-ignored")).toBe("true");
+    fireEvent.click(cancelEl);
+    expect(onClick).toHaveBeenCalledTimes(1);
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("cancel-disabled"));
+  });
+
+  it("cancel slot with a disabled house Button stays pressable (DG-ACT-05)", () => {
+    const onPress = vi.fn();
+    renderWithProviders(
+      <ActionBar
+        id="strip-house"
+        cancel={
+          <Button actionRole="chrome" disabled onPress={onPress}>
+            Cancel
+          </Button>
+        }
+      />,
+    );
+    const cancelEl = screen.getByText("Cancel");
+    fireEvent.click(cancelEl);
+    expect(onPress).toHaveBeenCalledTimes(1);
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("cancel-disabled"));
+    // Stripping happens before Button renders, so no bare-disabled either.
+    expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("bare-disabled"));
+  });
+
+  it("DEV warns dialog-too-many-actions for 3 actions inside a dialog region (DG-OVL-04)", () => {
+    renderWithProviders(
+      inDialogRegion(
+        <ActionBar
+          id="dlg-three"
+          cancel={<Button actionRole="chrome">Cancel</Button>}
+          secondary={<Button actionRole="secondary">Draft</Button>}
+          primary={<Button accent>Save</Button>}
+        />,
+      ),
+    );
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("dialog-too-many-actions"));
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("count=3"));
+  });
+
+  it("allowManyActions ejects the dialog action cap (DG-OVL-04)", () => {
+    renderWithProviders(
+      inDialogRegion(
+        <ActionBar
+          id="dlg-eject"
+          allowManyActions
+          cancel={<Button actionRole="chrome">Cancel</Button>}
+          secondary={<Button actionRole="secondary">Draft</Button>}
+          primary={<Button accent>Save</Button>}
+        />,
+      ),
+    );
+    expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("dialog-too-many-actions"));
+  });
+
+  it("cancel + primary inside a dialog region stays silent (DG-OVL-04 baseline)", () => {
+    renderWithProviders(
+      inDialogRegion(
+        <ActionBar
+          id="dlg-pair"
+          cancel={<Button actionRole="chrome">Cancel</Button>}
+          primary={<Button accent>Save</Button>}
+        />,
+      ),
+    );
+    expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("dialog-too-many-actions"));
+  });
+
+  it("3 actions outside a dialog region are not capped (page-level bars)", () => {
+    renderWithProviders(
+      <ActionBar
+        id="page-three"
+        cancel={<Button actionRole="chrome">Cancel</Button>}
+        secondary={<Button actionRole="secondary">Draft</Button>}
+        primary={<Button accent>Save</Button>}
+      />,
+    );
+    expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("dialog-too-many-actions"));
+  });
+});

package/src/actions/ActionBar.tsx

@@ -0,0 +1,207 @@
+/**
+ * DG-ACT-01 / DG-ACT-04 — one primary per region; trailing default for dialogs/toolbars.
+ * DG-ACT-05 — the cancel slot never renders disabled (disabled is stripped + DEV warn).
+ * DG-OVL-04 — inside a dialog region, more than 2 actions DEV-warns unless
+ * `allowManyActions` ejects.
+ *
+ * Slots keep primary singular by construction. Free `children` are scanned in DEV
+ * for `[data-mp-action-role="primary"]` / accent markers (two-primaries warn).
+ */
+
+import {
+  Children,
+  cloneElement,
+  isValidElement,
+  useEffect,
+  useId,
+  useRef,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { XStack, type GetProps } from "tamagui";
+import { countActionsInTree } from "../shared/actionScan";
+import { useIsInDialogRegion } from "../surfaces";
+import { actionDevWarn, warnCancelDisabled, warnDialogTooManyActions } from "./devWarn";
+
+export type ActionBarAlign = "start" | "end" | "between";
+
+export type ActionBarProps = Omit<GetProps<typeof XStack>, "children"> & {
+  /** Singular primary action (filled / accent). */
+  primary?: ReactNode;
+  /** Secondary actions (outlined / chromeless). */
+  secondary?: ReactNode | ReactNode[];
+  /** Cancel / dismiss — never danger tone (DG-ACT-05 companion). */
+  cancel?: ReactNode;
+  /** Free composition; DEV-counted for extra primaries. */
+  children?: ReactNode;
+  /** Trailing default (dialogs/toolbars); `start` for page-level forms. */
+  align?: ActionBarAlign;
+  /**
+   * DG-OVL-04 eject — acknowledges more than 2 actions in a dialog action
+   * row and silences the `dialog-too-many-actions` DEV warn. Has no effect
+   * outside dialog regions (page-level bars are not capped).
+   */
+  allowManyActions?: boolean;
+  /** Stable id for DEV warn dedupe. */
+  id?: string;
+};
+
+const ALIGN_JUSTIFY: Record<ActionBarAlign, GetProps<typeof XStack>["justifyContent"]> = {
+  start: "flex-start",
+  end: "flex-end",
+  between: "space-between",
+};
+
+function asArray(node: ReactNode | ReactNode[] | undefined): ReactNode[] {
+  if (node == null || node === false) return [];
+  return Array.isArray(node) ? node : [node];
+}
+
+function elementLooksPrimary(node: ReactNode): boolean {
+  if (!isValidElement(node)) return false;
+  const props = node.props as Record<string, unknown>;
+  if (props["data-mp-action-role"] === "primary") return true;
+  if (props.actionRole === "primary") return true;
+  if (props.accent === true) return true;
+  return false;
+}
+
+function countPrimariesInTree(nodes: ReactNode): number {
+  let count = 0;
+  Children.forEach(nodes, (child) => {
+    if (elementLooksPrimary(child)) count += 1;
+    if (isValidElement(child)) {
+      const kids = (child.props as { children?: ReactNode }).children;
+      if (kids != null) count += countPrimariesInTree(kids);
+    }
+  });
+  return count;
+}
+
+function nodeRendersDisabled(node: ReactNode): boolean {
+  if (!isValidElement(node)) return false;
+  const props = node.props as Record<string, unknown>;
+  return (
+    props.disabled === true || props["aria-disabled"] === true || props["aria-disabled"] === "true"
+  );
+}
+
+export function ActionBar({
+  primary,
+  secondary,
+  cancel,
+  children,
+  align = "end",
+  allowManyActions = false,
+  id: idProp,
+  gap = "$2",
+  ...stackProps
+}: ActionBarProps) {
+  const reactId = useId();
+  const regionId = idProp ?? reactId;
+  const rootRef = useRef<HTMLElement | null>(null);
+  const inDialogRegion = useIsInDialogRegion();
+
+  const secondaryItems = asArray(secondary);
+  const hasSlots = primary != null || secondaryItems.length > 0 || cancel != null;
+
+  // DG-ACT-05: the cancel/dismiss slot never renders disabled. Strip the
+  // prop (top-level slot elements) and DEV-warn `cancel-disabled`.
+  let cancelDisabledStripped = false;
+  const cancelItems =
+    cancel == null || cancel === false
+      ? null
+      : Children.map(cancel, (node) => {
+          if (!nodeRendersDisabled(node)) return node;
+          cancelDisabledStripped = true;
+          return cloneElement(
+            node as ReactElement,
+            {
+              disabled: undefined,
+              "aria-disabled": undefined,
+              "data-mp-cancel-disabled-ignored": "true",
+            } as never,
+          );
+        });
+
+  useEffect(() => {
+    let total = 0;
+    if (primary != null) total += 1;
+    // Slot primary is singular; also count free children + accidental accent in secondary/cancel.
+    total += countPrimariesInTree(children);
+    total += countPrimariesInTree(secondary);
+    total += countPrimariesInTree(cancel);
+
+    if (total > 1) {
+      actionDevWarn("two-primaries", {
+        component: "ActionBar",
+        id: regionId,
+        count: total,
+      });
+    }
+
+    if (cancelDisabledStripped) {
+      warnCancelDisabled({ disabled: true, component: "ActionBar", id: regionId });
+    }
+
+    // DG-OVL-04: dialog action rows cap at 2 actions (cancel counts). Slots
+    // count by construction; free children are counted heuristically.
+    if (inDialogRegion) {
+      const actionTotal =
+        (primary != null ? 1 : 0) +
+        secondaryItems.filter((node) => node != null && node !== false).length +
+        (cancel != null && cancel !== false ? 1 : 0) +
+        countActionsInTree(children);
+      warnDialogTooManyActions({
+        count: actionTotal,
+        allowManyActions,
+        component: "ActionBar",
+        id: regionId,
+      });
+    }
+
+    // DOM fallback for composed markup that set data attrs without React props.
+    const el = rootRef.current;
+    if (el && typeof el.querySelectorAll === "function") {
+      const domCount = el.querySelectorAll('[data-mp-action-role="primary"]').length;
+      if (domCount > 1) {
+        actionDevWarn("two-primaries", {
+          component: "ActionBar",
+          id: `${regionId}:dom`,
+          count: domCount,
+        });
+      }
+    }
+  }, [
+    allowManyActions,
+    cancel,
+    cancelDisabledStripped,
+    children,
+    inDialogRegion,
+    primary,
+    regionId,
+    secondary,
+  ]);
+
+  return (
+    <XStack
+      ref={rootRef as never}
+      data-mp-action-bar={regionId}
+      gap={gap}
+      flexWrap="wrap"
+      alignItems="center"
+      justifyContent={ALIGN_JUSTIFY[align]}
+      width="100%"
+      {...stackProps}
+    >
+      {hasSlots ? (
+        <>
+          {cancelItems}
+          {secondaryItems}
+          {primary}
+        </>
+      ) : null}
+      {children}
+    </XStack>
+  );
+}

package/src/actions/DestructiveAction.spec.tsx

@@ -0,0 +1,254 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { fireEvent, screen, waitFor } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { DestructiveAction, type DestructiveConfirmContext } from "./DestructiveAction";
+import { __resetActionDevWarnSeen } from "./devWarn";
+import {
+  resolveDestructiveSeverity,
+  severityRequiresConfirm,
+  severityUsesDangerTone,
+} from "./severity";
+
+/** Dialog portals into document.body — query there, not the RTL container. */
+function root(): HTMLElement {
+  return document.body;
+}
+
+function alertdialog(): Element | null {
+  return root().querySelector('[role="alertdialog"]');
+}
+
+function dialogButtonByLabel(label: string): Element {
+  const scope = alertdialog() ?? root();
+  const buttons = Array.from(scope.querySelectorAll('[role="button"]'));
+  const exact = buttons.find((b) => b.textContent?.trim() === label);
+  if (exact) return exact;
+  const match = buttons.find((b) => b.textContent?.includes(label));
+  if (!match) throw new Error(`No dialog button with label "${label}"`);
+  return match;
+}
+
+describe("resolveDestructiveSeverity", () => {
+  it("defaults to medium when no hints", () => {
+    expect(resolveDestructiveSeverity()).toBe("medium");
+  });
+
+  it("derives high from cascades / bulk+irreversible", () => {
+    expect(resolveDestructiveSeverity({ cascades: true })).toBe("high");
+    expect(resolveDestructiveSeverity({ bulk: true, irreversible: true })).toBe("high");
+  });
+
+  it("honors explicit severity over hints", () => {
+    expect(resolveDestructiveSeverity({ severity: "low", cascades: true })).toBe("low");
+  });
+
+  it("maps tiers to confirm + danger", () => {
+    expect(severityRequiresConfirm("low")).toBe(false);
+    expect(severityRequiresConfirm("medium")).toBe(true);
+    expect(severityUsesDangerTone("low")).toBe(false);
+    expect(severityUsesDangerTone("high")).toBe(true);
+  });
+});
+
+describe("DestructiveAction", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    __resetActionDevWarnSeen();
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    __resetActionDevWarnSeen();
+  });
+
+  it("renders verb+noun label and danger tone by default (medium)", () => {
+    renderWithProviders(
+      <DestructiveAction
+        verb="Delete"
+        noun="pipeline"
+        confirm={async () => false}
+        onAction={() => {}}
+      />,
+    );
+    expect(screen.getByText("Delete pipeline")).toBeInTheDocument();
+  });
+
+  it("default path opens ConfirmDialog; cancel does not call onAction", async () => {
+    const onAction = vi.fn();
+    renderWithProviders(<DestructiveAction verb="Delete" noun="pipeline" onAction={onAction} />);
+    fireEvent.click(screen.getByText("Delete pipeline"));
+    await waitFor(() => expect(alertdialog()).toBeTruthy());
+    expect(root().textContent).toContain("Delete pipeline?");
+    expect(alertdialog()?.getAttribute("data-tone")).toBe("destructive");
+    expect(dialogButtonByLabel("Delete")).toBeTruthy();
+    fireEvent.click(dialogButtonByLabel("Cancel"));
+    await waitFor(() => expect(alertdialog()).toBeNull());
+    expect(onAction).not.toHaveBeenCalled();
+    expect(warnSpy).not.toHaveBeenCalledWith(
+      expect.stringContaining("bare-destructive-without-confirm"),
+    );
+  });
+
+  it("default ConfirmDialog confirm runs onAction", async () => {
+    const onAction = vi.fn();
+    renderWithProviders(
+      <DestructiveAction
+        verb="Delete"
+        noun="pipeline"
+        consequence="This cannot be undone."
+        onAction={onAction}
+      />,
+    );
+    fireEvent.click(screen.getByText("Delete pipeline"));
+    await waitFor(() => expect(alertdialog()).toBeTruthy());
+    expect(root().textContent).toContain("This cannot be undone.");
+    fireEvent.click(dialogButtonByLabel("Delete"));
+    await waitFor(() => expect(onAction).toHaveBeenCalledTimes(1));
+    await waitFor(() => expect(alertdialog()).toBeNull());
+  });
+
+  it("calls onAction only after confirm returns true", async () => {
+    const onAction = vi.fn();
+    const confirm = vi.fn(async (_ctx: DestructiveConfirmContext) => true);
+    renderWithProviders(
+      <DestructiveAction verb="Delete" noun="row" confirm={confirm} onAction={onAction} />,
+    );
+    fireEvent.click(screen.getByText("Delete row"));
+    await waitFor(() => expect(confirm).toHaveBeenCalledTimes(1));
+    expect(confirm.mock.calls[0][0].confirmLabel).toBe("Delete");
+    expect(confirm.mock.calls[0][0].actionLabel).toBe("Delete row");
+    await waitFor(() => expect(onAction).toHaveBeenCalledTimes(1));
+    expect(alertdialog()).toBeNull();
+  });
+
+  it("does not call onAction when confirm returns false", async () => {
+    const onAction = vi.fn();
+    renderWithProviders(
+      <DestructiveAction verb="Delete" confirm={async () => false} onAction={onAction} />,
+    );
+    fireEvent.click(screen.getByText("Delete"));
+    await waitFor(() => expect(onAction).not.toHaveBeenCalled());
+  });
+
+  it("low severity skips confirm and danger tone", async () => {
+    const onAction = vi.fn();
+    const confirm = vi.fn(async () => true);
+    renderWithProviders(
+      <DestructiveAction severity="low" verb="Remove" confirm={confirm} onAction={onAction} />,
+    );
+    fireEvent.click(screen.getByText("Remove"));
+    await waitFor(() => expect(onAction).toHaveBeenCalledTimes(1));
+    expect(confirm).not.toHaveBeenCalled();
+    expect(alertdialog()).toBeNull();
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("high severity passes expectedText into confirm context", async () => {
+    const confirm = vi.fn(async (_ctx: DestructiveConfirmContext) => false);
+    renderWithProviders(
+      <DestructiveAction
+        severity="high"
+        verb="Delete"
+        noun="acme"
+        confirmationText="acme"
+        confirm={confirm}
+        onAction={() => {}}
+      />,
+    );
+    fireEvent.click(screen.getByText("Delete acme"));
+    await waitFor(() => expect(confirm).toHaveBeenCalled());
+    expect(confirm.mock.calls[0][0].expectedText).toBe("acme");
+    expect(confirm.mock.calls[0][0].severity).toBe("high");
+  });
+
+  it("high default path requires typed expectedText before confirm", async () => {
+    const onAction = vi.fn();
+    renderWithProviders(
+      <DestructiveAction
+        severity="high"
+        verb="Delete"
+        noun="project"
+        confirmationText="my-project"
+        consequence="Permanent."
+        onAction={onAction}
+      />,
+    );
+    fireEvent.click(screen.getByText("Delete project"));
+    await waitFor(() => expect(alertdialog()).toBeTruthy());
+    expect(root().textContent).toContain('Type "my-project" to confirm.');
+    expect(dialogButtonByLabel("Delete").getAttribute("data-mp-confirm-disabled")).toBe("true");
+    fireEvent.click(dialogButtonByLabel("Delete"));
+    expect(onAction).not.toHaveBeenCalled();
+
+    const input =
+      (alertdialog()?.querySelector("[data-mp-confirm-expected]") as HTMLElement | null) ??
+      (alertdialog()?.querySelector("input") as HTMLElement | null);
+    expect(input).toBeTruthy();
+    fireEvent.change(input!, { target: { value: "my-project" } });
+
+    await waitFor(() => {
+      expect(dialogButtonByLabel("Delete").getAttribute("data-mp-confirm-disabled")).not.toBe(
+        "true",
+      );
+    });
+    fireEvent.click(dialogButtonByLabel("Delete"));
+    await waitFor(() => expect(onAction).toHaveBeenCalledTimes(1));
+  });
+
+  it("disabledReason blocks action and sets aria-disabled", () => {
+    const onAction = vi.fn();
+    renderWithProviders(
+      <DestructiveAction
+        verb="Delete"
+        confirm={async () => true}
+        onAction={onAction}
+        disabledReason="Only owners can remove this"
+      />,
+    );
+    const btn = screen.getByText("Delete");
+    const frame = btn.closest('[aria-disabled="true"]');
+    expect(frame).toBeTruthy();
+    // DG-ST-03: the reason renders as visible text wired via aria-describedby.
+    expect(screen.getByText("Only owners can remove this")).toBeInTheDocument();
+    expect(frame?.getAttribute("aria-describedby")).toBeTruthy();
+    fireEvent.click(btn);
+    expect(onAction).not.toHaveBeenCalled();
+  });
+
+  it("typed-confirm gate explains the disabled confirm (DG-ST-03)", async () => {
+    const onAction = vi.fn();
+    renderWithProviders(
+      <DestructiveAction
+        severity="high"
+        verb="Delete"
+        noun="project"
+        confirmationText="my-project"
+        onAction={onAction}
+      />,
+    );
+    fireEvent.click(screen.getByText("Delete project"));
+    await waitFor(() => expect(alertdialog()).toBeTruthy());
+
+    const confirm = dialogButtonByLabel("Delete");
+    expect(confirm.getAttribute("aria-disabled")).toBe("true");
+    expect(confirm.getAttribute("aria-describedby")).toBeTruthy();
+    const reason = alertdialog()?.querySelector("[data-mp-disabled-reason]");
+    expect(reason?.textContent).toContain('Type "my-project" to confirm.');
+    expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("bare-disabled"));
+
+    // Typing the expected text clears the gate and the reason affordance.
+    const input = alertdialog()?.querySelector("input") as HTMLElement;
+    fireEvent.change(input, { target: { value: "my-project" } });
+    await waitFor(() => {
+      expect(alertdialog()?.querySelector("[data-mp-disabled-reason]")).toBeNull();
+    });
+    fireEvent.click(dialogButtonByLabel("Delete"));
+    await waitFor(() => expect(onAction).toHaveBeenCalledTimes(1));
+  });
+});