@multiplatform.one/components 6.1.0 → 6.4.0

package/src/layouts/toolbar.tsx

@@ -1,7 +1,8 @@
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { hairline, hairlineWidth, useResolvedKnobs } from "@multiplatform.one/theme";
 import type React from "react";
+import { useTranslation } from "react-i18next";
 import { Button } from "@multiplatform.one/forms";
-import { Group, Separator, XStack } from "tamagui";
+import { Group, Separator, XStack, isWeb } from "tamagui";
 
 export interface ToolbarAction {
   label: string;
@@ -9,7 +10,19 @@ export interface ToolbarAction {
   onPress: () => void;
   variant?: "default" | "primary" | "outlined" | "destructive";
   disabled?: boolean;
+  /**
+   * DG-ST-03 — explains why the action is disabled. Flows through the Button
+   * contract (visible reason, aria-describedby, stays focusable). A bare
+   * `disabled` without it DEV-warns `bare-disabled`.
+   */
+  disabledReason?: string;
   loading?: boolean;
+  /**
+   * When true, consecutive fused actions render as one segmented Group
+   * (true picker/segment semantics). Independent actions leave this unset
+   * and receive real gap (component.gallery Toolbar / Button-group consensus).
+   */
+  fused?: boolean;
 }
 
 export interface ToolbarProps {
@@ -20,28 +33,59 @@ export interface ToolbarProps {
   loadingLabel?: string;
 }
 
+type ActionCluster =
+  | { kind: "independent"; actions: ToolbarAction[] }
+  | { kind: "fused"; actions: ToolbarAction[] };
+
+function clusterActions(actions: ToolbarAction[]): ActionCluster[] {
+  const clusters: ActionCluster[] = [];
+  for (const action of actions) {
+    const prev = clusters[clusters.length - 1];
+    if (action.fused) {
+      if (prev?.kind === "fused") {
+        prev.actions.push(action);
+      } else {
+        clusters.push({ kind: "fused", actions: [action] });
+      }
+    } else if (prev?.kind === "independent") {
+      prev.actions.push(action);
+    } else {
+      clusters.push({ kind: "independent", actions: [action] });
+    }
+  }
+  return clusters;
+}
+
+function partitionByDestructive(actions: ToolbarAction[]) {
+  const neutral: ToolbarAction[] = [];
+  const destructive: ToolbarAction[] = [];
+  for (const action of actions) {
+    if (action.variant === "destructive") {
+      destructive.push(action);
+    } else {
+      neutral.push(action);
+    }
+  }
+  return { neutral, destructive };
+}
+
 export function Toolbar({
   primaryActions = [],
   secondaryActions = [],
   position = "top",
-  loadingLabel = "Loading...",
+  loadingLabel: loadingLabelProp,
 }: ToolbarProps) {
+  const { t } = useTranslation();
+  const loadingLabel = loadingLabelProp ?? t("Loading...");
   const { knobProps } = useResolvedKnobs();
 
-  const getButtonTheme = (variant?: string) => {
-    switch (variant) {
-      case "primary":
-        return "blue";
-      case "destructive":
-        return "red";
-      default:
-        return undefined;
-    }
-  };
-
-  const getButtonVariant = (variant?: string) => {
-    return variant === "outlined" ? "outlined" : undefined;
-  };
+  // Route emphasis through the intent system (accent/error) instead of
+  // hardcoded color themes, so toolbar actions share the app's one solid
+  // emphasis language (SB-D-05/SB-E-01).
+  const getButtonIntents = (variant?: string) => ({
+    accent: variant === "primary",
+    error: variant === "destructive",
+  });
 
   const renderAction = (action: ToolbarAction) => (
     <Button
@@ -49,40 +93,119 @@ export function Toolbar({
       size={knobProps.sizeToken}
       icon={action.icon as any}
       onPress={action.onPress}
-      disabled={action.disabled || action.loading}
-      theme={getButtonTheme(action.variant)}
-      variant={getButtonVariant(action.variant)}
+      disabled={action.disabled}
+      // Busy is derived state, not a bare disable — Button shows the spinner
+      // and skips the bare-disabled warn; loadingLabel stays for SRs.
+      loading={action.loading}
+      aria-label={action.loading ? loadingLabel : undefined}
+      // DG-ST-03: reason flows through the Button explain affordance.
+      disabledReason={action.disabledReason}
+      {...getButtonIntents(action.variant)}
+      // Axiom 13 ONE BODY: the Toolbar's `outlined` variant maps to the
+      // Button's canonical boolean `outlined` prop. Passing it as a string
+      // `variant` matched no styled-frame key and silently dissolved (DF-10).
+      outlined={action.variant === "outlined"}
     >
-      {action.loading ? loadingLabel : action.label}
+      {action.label}
     </Button>
   );
 
+  const renderClusters = (actions: ToolbarAction[], region: string) =>
+    clusterActions(actions).map((cluster, index) => {
+      if (cluster.kind === "fused") {
+        return (
+          <Group
+            key={`${region}-fused-${index}`}
+            orientation="horizontal"
+            data-toolbar-cluster="fused"
+            data-toolbar-region={region}
+          >
+            {cluster.actions.map((action) => (
+              <Group.Item key={action.label}>{renderAction(action)}</Group.Item>
+            ))}
+          </Group>
+        );
+      }
+      return (
+        <XStack
+          key={`${region}-independent-${index}`}
+          {...knobProps.gap}
+          alignItems="center"
+          flexWrap="wrap"
+          data-toolbar-cluster="independent"
+          data-toolbar-region={region}
+        >
+          {cluster.actions.map((action) => renderAction(action))}
+        </XStack>
+      );
+    });
+
+  const { neutral: secondaryNeutral, destructive: secondaryDestructive } =
+    partitionByDestructive(secondaryActions);
+  const hasTrailing = secondaryNeutral.length > 0 || secondaryDestructive.length > 0;
+
+  // Two bar children only (start cluster + trailing cluster). The separator
+  // lives INSIDE the trailing cluster between neutral and destructive so it
+  // cannot float mid-bar under space-between (SB-D-06 / SB-E-05).
   return (
     <XStack
-      {...knobProps.panelPadding}
+      // LC-39 EARNED-INSET (Axiom 16 ALIGNMENT): the bar paints no
+      // distinguishable surface — its fill is the page `$background` and its
+      // only chrome is the one-edge hairline divider, so it earns no
+      // horizontal inset. Actions sit flush on the page column's alignment
+      // line; vertical padding stays (rhythm against the divider edge the
+      // bar actually paints). If Toolbar ever grows a painted-panel variant,
+      // that variant re-earns `panelPadding` with its visible surface.
+      paddingVertical={knobProps.panelPadding.padding}
+      paddingHorizontal={0}
       {...knobProps.gap}
-      borderTopWidth={position === "bottom" ? 1 : 0}
-      borderBottomWidth={position === "top" ? 1 : 0}
+      // Bar edge is a divider (not a control border): hairline on high-DPI
+      // (Axiom 15). Only class the side that carries the rule so the low-DPI
+      // fallback cannot paint the other edge.
+      borderTopWidth={position === "bottom" ? hairlineWidth : 0}
+      borderBottomWidth={position === "top" ? hairlineWidth : 0}
+      {...(isWeb && {
+        className: position === "top" ? "mp-hairline-b" : "mp-hairline-t",
+      })}
       borderColor="$borderColor"
       {...{ backgroundColor: "$background" }}
       justifyContent="space-between"
       alignItems="center"
+      flexWrap="wrap"
+      data-testid="toolbar"
     >
-      <Group orientation="horizontal">
-        {primaryActions.map((action) => (
-          <Group.Item key={action.label}>{renderAction(action)}</Group.Item>
-        ))}
-      </Group>
+      <XStack
+        {...knobProps.gap}
+        alignItems="center"
+        flexWrap="wrap"
+        flexShrink={1}
+        data-toolbar-slot="start"
+      >
+        {renderClusters(primaryActions, "primary")}
+      </XStack>
 
-      {secondaryActions.length > 0 && (
-        <>
-          <Separator vertical height={knobProps.sizeToken} />
-          <Group orientation="horizontal">
-            {secondaryActions.map((action) => (
-              <Group.Item key={action.label}>{renderAction(action)}</Group.Item>
-            ))}
-          </Group>
-        </>
+      {hasTrailing && (
+        <XStack
+          {...knobProps.gap}
+          alignItems="center"
+          flexWrap="wrap"
+          flexShrink={1}
+          marginInlineStart="auto"
+          justifyContent="flex-end"
+          data-toolbar-slot="end"
+        >
+          {renderClusters(secondaryNeutral, "secondary")}
+          {secondaryNeutral.length > 0 && secondaryDestructive.length > 0 && (
+            <Separator
+              vertical
+              {...hairline.vline}
+              height={knobProps.sizeToken}
+              alignSelf="center"
+              data-toolbar-separator="destructive"
+            />
+          )}
+          {renderClusters(secondaryDestructive, "destructive")}
+        </XStack>
       )}
     </XStack>
   );

package/src/shared/actionScan.ts

@@ -0,0 +1,40 @@
+/**
+ * DG-OVL-04 DEV scan — count action-like elements (buttons / pressables) in a
+ * React tree so dialog action rows can enforce the max-2-actions cap.
+ *
+ * Heuristic, not exhaustive: explicit action markers, press/click handlers,
+ * and button roles/tags count; bare `href` links are treated as body copy,
+ * not actions.
+ */
+
+import { Children, isValidElement, type ReactNode } from "react";
+
+export function elementLooksLikeAction(node: ReactNode): boolean {
+  if (!isValidElement(node)) return false;
+  const props = node.props as Record<string, unknown>;
+  if (props["data-mp-action-role"] != null || props.actionRole != null) return true;
+  if (typeof props.onPress === "function" || typeof props.onClick === "function") return true;
+  if (props.role === "button" || node.type === "button") return true;
+  if (props.tag === "button") return true;
+  if (props.accent === true) return true;
+  return false;
+}
+
+/**
+ * Counts action-like elements recursively. Matched actions are not descended
+ * into — their children are label content, not further actions.
+ */
+export function countActionsInTree(nodes: ReactNode): number {
+  let count = 0;
+  Children.forEach(nodes, (child) => {
+    if (elementLooksLikeAction(child)) {
+      count += 1;
+      return;
+    }
+    if (isValidElement(child)) {
+      const kids = (child.props as { children?: ReactNode }).children;
+      if (kids != null) count += countActionsInTree(kids);
+    }
+  });
+  return count;
+}

package/src/shared/t.ts

@@ -0,0 +1,29 @@
+/**
+ * Apply `{{var}}` interpolation when react-i18next returns an untranslated key
+ * (no i18n instance in unit tests / headless DS).
+ */
+export function withInterp(
+  translated: string,
+  options: Record<string, string | number | undefined | null>,
+): string {
+  if (!translated.includes("{{")) return translated;
+  return translated.replace(/\{\{(\w+)\}\}/g, (_, key: string) =>
+    options[key] != null ? String(options[key]) : `{{${key}}}`,
+  );
+}
+
+/**
+ * First-strong bidi isolation — FSI…PDI (`\u2068…\u2069`), the string form of
+ * `<bdi>`. Formatted runs that interpolate numbers into latin copy ("1–5 of
+ * 5", "7 entries") reorder inside an RTL paragraph ("of 5 5–1") because the
+ * surrounding bidi context resolves each weak/latin segment independently.
+ * Isolating the WHOLE formatted run gives it its own base direction (from its
+ * first strong character), so untranslated latin copy renders LTR as a unit
+ * while translated RTL copy keeps rendering RTL — apply to visible
+ * count/range labels at the interpolation site (per-number isolation is not
+ * enough: a strong-LTR word like "of" still reorders).
+ */
+export function bidiIsolate(text: string): string {
+  if (!text) return text;
+  return `\u2068${text}\u2069`;
+}

package/src/shared/useReturnFocusOnClose.ts

@@ -0,0 +1,51 @@
+/**
+ * DG-A11Y-04 / Axiom 7 AGENCY — restore focus to the element that had it
+ * when a programmatically-opened overlay (`open` prop, no Dialog.Trigger)
+ * closes. Tamagui's focus scope only restores to a Dialog.Trigger mounted
+ * inside the Dialog; without one, close drops focus on <body>.
+ *
+ * Capture happens during RENDER, not in an effect: the Dialog focus scope
+ * (a child) runs its effects before this parent's, so an effect-time capture
+ * would read an element already inside the overlay. Reading
+ * document.activeElement in render is a side-effect-free read
+ * (StrictMode-safe — the double render sees the same value).
+ *
+ * Only restores when focus was actually dropped — a deliberate focus move
+ * (outside click onto another control) is preserved. Web-only, no-op on
+ * native. Mirror of the forms-package hook (packages stay independent).
+ */
+
+import { useEffect, useRef } from "react";
+import { isWeb } from "tamagui";
+
+const canUseDom = () => isWeb && typeof document !== "undefined";
+
+function focusIsDropped(): boolean {
+  const ae = document.activeElement;
+  return !ae || ae === document.body || ae === document.documentElement;
+}
+
+export function useReturnFocusOnClose(open: boolean) {
+  const prevRef = useRef<HTMLElement | null>(null);
+  const wasOpenRef = useRef(false);
+  if (canUseDom()) {
+    if (open && !wasOpenRef.current) {
+      prevRef.current = document.activeElement as HTMLElement | null;
+    }
+    wasOpenRef.current = open;
+  }
+  useEffect(() => {
+    if (!canUseDom() || !open) return;
+    return () => {
+      const restore = () => {
+        const target = prevRef.current;
+        if (!target || !target.isConnected) return;
+        if (focusIsDropped()) target.focus();
+      };
+      // Exit animations unmount the overlay a few frames later; retry after
+      // the typical exit window. Both calls are idempotent.
+      requestAnimationFrame(() => requestAnimationFrame(restore));
+      setTimeout(restore, 320);
+    };
+  }, [open]);
+}

package/src/surfaces.spec.tsx

@@ -0,0 +1,51 @@
+import { Card as TamaguiCard, Dialog, Popover, Sheet } from "tamagui";
+import { describe, expect, it } from "vitest";
+import * as pkg from "./index";
+import {
+  Card,
+  CardFooter,
+  CardHeader,
+  DialogContent,
+  KnobCard,
+  KnobDialogContent,
+  KnobPanel,
+  KnobPopoverContent,
+  KnobSheetFrame,
+  Panel,
+  PopoverContent,
+  SheetFrame,
+} from "./surfaces";
+
+describe("surfaces package exports", () => {
+  it("package Card is the themed surface, not the tamagui primitive", () => {
+    expect(pkg.Card).toBe(Card);
+    expect(pkg.Card).not.toBe(TamaguiCard);
+  });
+
+  it("package statics resolve to the themed header/footer", () => {
+    expect(pkg.Card.Header).toBe(CardHeader);
+    expect(pkg.Card.Footer).toBe(CardFooter);
+    expect(pkg.CardHeader).toBe(CardHeader);
+    expect(pkg.CardFooter).toBe(CardFooter);
+  });
+
+  it("package DialogContent/PopoverContent/SheetFrame/Panel are the themed surfaces", () => {
+    expect(pkg.DialogContent).toBe(DialogContent);
+    expect(pkg.DialogContent).not.toBe(Dialog.Content);
+    expect(pkg.PopoverContent).toBe(PopoverContent);
+    expect(pkg.PopoverContent).not.toBe(Popover.Content);
+    expect(pkg.SheetFrame).toBe(SheetFrame);
+    expect(pkg.SheetFrame).not.toBe(Sheet.Frame);
+    expect(pkg.Panel).toBe(Panel);
+  });
+
+  it("deprecated Knob* aliases still point at the renamed components", () => {
+    expect(KnobCard).toBe(Card);
+    expect(KnobDialogContent).toBe(DialogContent);
+    expect(KnobPopoverContent).toBe(PopoverContent);
+    expect(KnobSheetFrame).toBe(SheetFrame);
+    expect(KnobPanel).toBe(Panel);
+    expect(pkg.KnobCard).toBe(Card);
+    expect(pkg.KnobPanel).toBe(Panel);
+  });
+});