@snowcone-app/ui 0.8.1 → 0.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/ui",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "React components for merchandise visualization and customization",
   "keywords": [
     "react",
@@ -103,7 +103,7 @@
     "react-instantsearch": "^7.15.5",
     "react-zoom-pan-pinch": "^3.6.4",
     "tailwind-merge": "^3.0.0",
-    "@snowcone-app/sdk": "0.24.0"
+    "@snowcone-app/sdk": "0.24.2"
   },
   "devDependencies": {
     "@chromatic-com/storybook": "^4.1.2",
@@ -121,7 +121,7 @@
     "@vitejs/plugin-react": "^4.7.0",
     "@vueless/storybook-dark-mode": "^10.0.3",
     "jsdom": "^24.1.0",
-    "next": "15.4.6",
+    "next": "15.5.24",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "rimraf": "^6.1.2",
@@ -130,7 +130,7 @@
     "tsup": "^8.0.1",
     "typescript": "^5.4.5",
     "vite": "^5.4.21",
-    "vitest": "^2.0.5",
+    "vitest": "^2.1.9",
     "@snowcone-app/brand": "0.1.0"
   },
   "scripts": {

package/src/composed/PlacementTabs.tsx

@@ -43,8 +43,41 @@ export interface PlacementTabsProps {
   toolbarSize?: number;
   /** Additional className for the container */
   className?: string;
+  /**
+   * Linked placements (ADR-0101): one design on every print area.
+   *
+   * - `true` — LINKED. Renders one non-interactive pill naming the set
+   *   ("Both sides" for two placements, "All N areas" otherwise; the labels
+   *   in its `title`) plus a single **Customize separately** action
+   *   (`onSplitAll`). No per-placement tabs: there is one design to edit.
+   * - `false` — SPLIT. Renders the per-placement tabs plus one
+   *   **Use one design for all** action (`onLinkAll`).
+   * - `undefined` (default) — no link model: plain tabs, exactly as before.
+   */
+  linked?: boolean;
+  /** Linked → split: every placement gets its own copy of the design. */
+  onSplitAll?: () => void;
+  /** Split → linked: drop the per-placement copies, back to one design. */
+  onLinkAll?: () => void;
+  /** Override the linked pill's copy (localisation). */
+  linkedLabel?: string;
+  /** Override the "Customize separately" action copy. */
+  splitAllLabel?: string;
+  /** Override the "Use one design for all" action copy. */
+  linkAllLabel?: string;
 }
 
+/** Default pill copy for a linked set of `count` placements. */
+export function linkedPlacementsLabel(count: number): string {
+  return count === 2 ? "Both sides" : `All ${count} areas`;
+}
+
+const ACTION_CLASS =
+  "transition-colors duration-200 cursor-pointer text-muted-foreground hover:text-foreground underline underline-offset-4 decoration-muted-foreground/40 hover:decoration-foreground";
+
+const PILL_CLASS =
+  "inline-flex items-center rounded-full bg-foreground/[0.08] px-3 py-1 font-medium text-foreground";
+
 /**
  * PlacementTabs - Renders placement tabs with optional floating toolbar placeholder.
  *
@@ -52,6 +85,11 @@ export interface PlacementTabsProps {
  * to flow around the toolbar placeholder. On desktop, renders simple tabs
  * without the toolbar placeholder (toolbar is typically in header).
  *
+ * The container carries `data-placement-tabs` and, when the link model is in
+ * play, `data-linked="true" | "false"`; the pill is `data-placement-pill`
+ * and the actions are `data-action="split-all" | "link-all"` so hosts and
+ * agents can assert the state instead of reading pixels.
+ *
  * @example
  * ```tsx
  * // Basic usage
@@ -71,6 +109,16 @@ export interface PlacementTabsProps {
  *   onPlacementChange={setSelected}
  *   isDesktop
  * />
+ *
+ * // Linked by default (ADR-0101): one design on every area
+ * <PlacementTabs
+ *   placements={placements}
+ *   selectedPlacement={selected}
+ *   onPlacementChange={setSelected}
+ *   linked={linked}
+ *   onSplitAll={splitAll}
+ *   onLinkAll={linkAll}
+ * />
  * ```
  */
 export function PlacementTabs({
@@ -81,6 +129,12 @@ export function PlacementTabs({
   toolbarPlaceholderId = "toolbar-placeholder",
   toolbarSize = 120,
   className = "",
+  linked,
+  onSplitAll,
+  onLinkAll,
+  linkedLabel,
+  splitAllLabel = "Customize separately",
+  linkAllLabel = "Use one design for all",
 }: PlacementTabsProps) {
   const containerRef = useRef<HTMLDivElement>(null);
   const [lineHeight, setLineHeight] = useState(24); // Default estimate
@@ -103,7 +157,7 @@ export function PlacementTabs({
       return null;
     }
     return (
-      <div className={`flex justify-end w-full ${className}`}>
+      <div className={`flex justify-end w-full ${className}`} data-placement-tabs>
         <span
           id={toolbarPlaceholderId}
           className="block"
@@ -113,15 +167,46 @@ export function PlacementTabs({
     );
   }
 
-  // Desktop: just render placement tabs without toolbar placeholder
-  if (isDesktop) {
+  const dataLinked = linked === undefined ? undefined : linked ? "true" : "false";
+  const labels = placements.map((p) => p.label);
+
+  // The row content is shared by the desktop and mobile layouts; only the
+  // toolbar-placeholder float around it differs.
+  const renderItems = (tabClass: string) => {
+    if (linked === true) {
+      return (
+        <>
+          <span
+            className={`${tabClass} ${PILL_CLASS}`}
+            data-placement-pill
+            title={labels.join(" · ")}
+            aria-label={`One design on ${labels.join(", ")}`}
+          >
+            {linkedLabel ?? linkedPlacementsLabel(placements.length)}
+          </span>
+          {onSplitAll && (
+            <button
+              type="button"
+              onClick={onSplitAll}
+              className={`${tabClass} ${ACTION_CLASS}`}
+              data-action="split-all"
+            >
+              {splitAllLabel}
+            </button>
+          )}
+        </>
+      );
+    }
     return (
-      <div className={`flex flex-wrap gap-x-3 text-sm leading-relaxed w-full ${className}`}>
+      <>
         {placements.map((p) => (
           <button
             key={p.label}
+            type="button"
             onClick={() => onPlacementChange(p.label)}
-            className={`transition-all duration-200 cursor-pointer border-b-2 ${
+            data-placement-tab={p.label}
+            aria-pressed={selectedPlacement === p.label}
+            className={`${tabClass} transition-all duration-200 cursor-pointer border-b-2 ${
               selectedPlacement === p.label
                 ? "text-foreground border-primary"
                 : "text-foreground/70 hover:text-foreground border-muted-foreground/20 hover:border-muted-foreground/40"
@@ -130,6 +215,29 @@ export function PlacementTabs({
             {p.label}
           </button>
         ))}
+        {linked === false && onLinkAll && (
+          <button
+            type="button"
+            onClick={onLinkAll}
+            className={`${tabClass} ${ACTION_CLASS}`}
+            data-action="link-all"
+          >
+            {linkAllLabel}
+          </button>
+        )}
+      </>
+    );
+  };
+
+  // Desktop: just render placement tabs without toolbar placeholder
+  if (isDesktop) {
+    return (
+      <div
+        className={`flex flex-wrap items-center gap-x-3 gap-y-1 text-sm leading-relaxed w-full ${className}`}
+        data-placement-tabs
+        data-linked={dataLinked}
+      >
+        {renderItems("")}
       </div>
     );
   }
@@ -144,6 +252,8 @@ export function PlacementTabs({
     <div
       ref={containerRef}
       className={`flex overflow-hidden text-sm leading-relaxed w-full ${className}`}
+      data-placement-tabs
+      data-linked={dataLinked}
     >
       <p className="m-0 w-full">
         <span
@@ -159,20 +269,8 @@ export function PlacementTabs({
           />
         </span>
 
-        {/* Placement tabs */}
-        {placements.map((p) => (
-          <button
-            key={p.label}
-            onClick={() => onPlacementChange(p.label)}
-            className={`inline transition-all duration-200 cursor-pointer mr-3 border-b-2 ${
-              selectedPlacement === p.label
-                ? "text-foreground border-primary"
-                : "text-foreground/70 hover:text-foreground border-muted-foreground/20 hover:border-muted-foreground/40"
-            }`}
-          >
-            {p.label}
-          </button>
-        ))}
+        {/* Placement tabs (or the linked pill + action) */}
+        {renderItems("inline mr-3")}
       </p>
     </div>
   );

package/src/composed/__tests__/PlacementTabs.linked.test.tsx

@@ -0,0 +1,144 @@
+/**
+ * PlacementTabs linked mode (ADR-0101 §4/§6).
+ *
+ * - `linked` undefined → today's tabs, no link actions (back-compat).
+ * - `linked: true`  → one non-interactive pill ("Both sides" / "All N areas")
+ *                     plus "Customize separately"; no per-placement tabs.
+ * - `linked: false` → the tabs plus "Use one design for all".
+ * - The container exposes `data-linked` so the state is assertable.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import React from "react";
+import { cleanup, fireEvent, render } from "@testing-library/react";
+import { PlacementTabs, linkedPlacementsLabel, type PlacementConfig } from "../PlacementTabs";
+
+afterEach(cleanup);
+
+const two: PlacementConfig[] = [
+  { label: "Left", type: "image", width: 1200, height: 1800 },
+  { label: "Right", type: "image", width: 1200, height: 1800 },
+];
+const four: PlacementConfig[] = [
+  ...two,
+  { label: "Front", type: "image", width: 1200, height: 1800 },
+  { label: "Back", type: "image", width: 1200, height: 1800 },
+];
+
+describe("linkedPlacementsLabel", () => {
+  it("names the set", () => {
+    expect(linkedPlacementsLabel(2)).toBe("Both sides");
+    expect(linkedPlacementsLabel(4)).toBe("All 4 areas");
+  });
+});
+
+describe.each([{ isDesktop: true }, { isDesktop: false }])(
+  "PlacementTabs (isDesktop=$isDesktop)",
+  ({ isDesktop }) => {
+    it("renders plain tabs with no link actions when `linked` is undefined", () => {
+      const { container, queryByText, getByText } = render(
+        <PlacementTabs
+          placements={two}
+          selectedPlacement="Left"
+          onPlacementChange={() => {}}
+          isDesktop={isDesktop}
+          onSplitAll={() => {}}
+          onLinkAll={() => {}}
+        />,
+      );
+      const root = container.querySelector("[data-placement-tabs]");
+      expect(root).not.toBeNull();
+      expect(root!.getAttribute("data-linked")).toBeNull();
+      expect(getByText("Left")).toBeTruthy();
+      expect(getByText("Right")).toBeTruthy();
+      expect(queryByText("Customize separately")).toBeNull();
+      expect(queryByText("Use one design for all")).toBeNull();
+    });
+
+    it("linked: shows one pill and the split action, no tabs", () => {
+      const onSplitAll = vi.fn();
+      const onPlacementChange = vi.fn();
+      const { container, queryByText, getByText } = render(
+        <PlacementTabs
+          placements={two}
+          selectedPlacement="Left"
+          onPlacementChange={onPlacementChange}
+          isDesktop={isDesktop}
+          linked
+          onSplitAll={onSplitAll}
+          onLinkAll={() => {}}
+        />,
+      );
+      const root = container.querySelector("[data-placement-tabs]")!;
+      expect(root.getAttribute("data-linked")).toBe("true");
+      const pill = container.querySelector("[data-placement-pill]")!;
+      expect(pill.textContent).toBe("Both sides");
+      expect(pill.getAttribute("title")).toBe("Left · Right");
+      expect(pill.tagName).not.toBe("BUTTON");
+      // No per-placement tabs while linked — there is one design to edit.
+      expect(container.querySelector("[data-placement-tab]")).toBeNull();
+      expect(queryByText("Use one design for all")).toBeNull();
+
+      fireEvent.click(getByText("Customize separately"));
+      expect(onSplitAll).toHaveBeenCalledTimes(1);
+      expect(onPlacementChange).not.toHaveBeenCalled();
+    });
+
+    it("linked with 4 placements says 'All 4 areas'", () => {
+      const { container } = render(
+        <PlacementTabs
+          placements={four}
+          selectedPlacement="Left"
+          onPlacementChange={() => {}}
+          isDesktop={isDesktop}
+          linked
+          onSplitAll={() => {}}
+        />,
+      );
+      expect(container.querySelector("[data-placement-pill]")!.textContent).toBe(
+        "All 4 areas",
+      );
+    });
+
+    it("split: shows the tabs plus the link action", () => {
+      const onLinkAll = vi.fn();
+      const onPlacementChange = vi.fn();
+      const { container, getByText, queryByText } = render(
+        <PlacementTabs
+          placements={two}
+          selectedPlacement="Left"
+          onPlacementChange={onPlacementChange}
+          isDesktop={isDesktop}
+          linked={false}
+          onSplitAll={() => {}}
+          onLinkAll={onLinkAll}
+        />,
+      );
+      const root = container.querySelector("[data-placement-tabs]")!;
+      expect(root.getAttribute("data-linked")).toBe("false");
+      expect(container.querySelectorAll("[data-placement-tab]")).toHaveLength(2);
+      expect(queryByText("Customize separately")).toBeNull();
+      expect(container.querySelector("[data-placement-pill]")).toBeNull();
+
+      fireEvent.click(getByText("Right"));
+      expect(onPlacementChange).toHaveBeenCalledWith("Right");
+
+      fireEvent.click(getByText("Use one design for all"));
+      expect(onLinkAll).toHaveBeenCalledTimes(1);
+    });
+
+    it("single placement renders no link model at all", () => {
+      const { container, queryByText } = render(
+        <PlacementTabs
+          placements={[two[0]]}
+          selectedPlacement="Left"
+          onPlacementChange={() => {}}
+          isDesktop={isDesktop}
+          linked
+          onSplitAll={() => {}}
+        />,
+      );
+      expect(container.querySelector("[data-placement-pill]")).toBeNull();
+      expect(queryByText("Customize separately")).toBeNull();
+    });
+  },
+);

package/src/patterns/RealtimeProvider.tsx

@@ -157,7 +157,7 @@ export interface RealtimeContextValue {
           {
             width: number;
             height: number;
-            pieces: Array<{ placement: string; x: number; y: number; width: number; height: number }>;
+            pieces: Array<{ placement: string; x: number; y: number; width: number; height: number; part?: { index: number; count: number } }>;
           }
         >
       | undefined
@@ -382,7 +382,7 @@ export function RealtimeProvider({
         {
           width: number;
           height: number;
-          pieces: Array<{ placement: string; x: number; y: number; width: number; height: number }>;
+          pieces: Array<{ placement: string; x: number; y: number; width: number; height: number; part?: { index: number; count: number } }>;
         }
       >
     | undefined
@@ -1173,7 +1173,7 @@ export function RealtimeProvider({
             {
               width: number;
               height: number;
-              pieces: Array<{ placement: string; x: number; y: number; width: number; height: number }>;
+              pieces: Array<{ placement: string; x: number; y: number; width: number; height: number; part?: { index: number; count: number } }>;
             }
           >
         | undefined