WEB-135 Refactor responsive Puck fields and shared published rendering paths

Author: wlenig

docs/STYLING.md

@@ -82,7 +82,7 @@ These helpers are for component logic — see [Rendering](#4-rendering) for how
 
 `defineProps` wires tokens to Puck editor fields (`src/lib/puck/define-props.ts`). It returns `{ fields, defaultProps }` to spread onto a `ComponentConfig`.
 
-There are four field builders:
+There are two builder namespaces:
 
 ```ts
 const props = defineProps({
@@ -94,7 +94,16 @@ const props = defineProps({
   layout:  field.radio(layout, { label: "Layout" }),
 
   // Responsive — per-breakpoint picker, also token-backed
-  padding: responsive.token(padding, { label: "Padding" }),
+  padding: responsive.select(padding, { label: "Padding" }),
+
+  // Responsive number — per-breakpoint numeric input
+  columns: responsive.number({
+    label: "Columns",
+    default: { base: 1, md: 2 },
+    min: 1,
+    max: 6,
+    step: 1,
+  }),
 
   // Raw — any Puck field descriptor, for things tokens don't cover
   url:     field.raw({ type: "text", label: "URL" }, ""),
@@ -104,8 +113,10 @@ const props = defineProps({
 **Defaults.** Every builder falls back to the token's first key if no `default` is given. You can override with a scalar or a full responsive object:
 
 ```ts
-responsive.token(columnCount, { label: "Columns", default: "3" })
-responsive.token(columnCount, { label: "Columns", default: { base: "1", md: "3" } })
+responsive.select(columnCount, { label: "Columns", default: "3" })
+responsive.select(columnCount, { label: "Columns", default: { base: "1", md: "3" } })
+responsive.number({ label: "Rows", default: 2, min: 1, max: 6, step: 1 })
+responsive.number({ label: "Rows", default: { base: 1, md: 3 } })
 ```
 
 **Slots** accept an optional allow/disallow list to restrict which child components can be dropped in:
@@ -115,7 +126,26 @@ field.slot({ allow: ["Card", "Button"] })
 field.slot({ disallow: ["Section"] })
 ```
 
-The same token definition works for both static and responsive use — only the field builder differs.
+The same token definition works for both static and responsive use. Numeric responsive fields do not need a token.
+
+### Responsive field architecture
+
+Responsive field descriptors are built on the server and rendered on the client, so the implementation is split intentionally:
+
+- Shared kind definitions live in `src/components/puck/fields/responsive-kinds/*/shared.ts`.
+- Client renderers live in `src/components/puck/fields/responsive-kinds/*/client.tsx`.
+- `src/components/puck/fields/responsive-field.tsx` is the server-safe wrapper that turns a serializable descriptor into a Puck custom field.
+- `src/components/puck/fields/responsive-field-client.tsx` is the client-only registry that maps `descriptor.kind` to the right renderer.
+- `src/components/puck/fields/responsive-field-frame.tsx` owns the shared breakpoint UI; kind-specific controls only deal with their own value format.
+
+This keeps the descriptor shape and the renderer associated by kind without pushing client code across the server boundary.
+
+To add a new responsive field kind:
+
+1. Add `shared.ts` and `client.tsx` under `src/components/puck/fields/responsive-kinds/<kind>/`.
+2. Export the descriptor factory and type from `src/components/puck/fields/responsive-kinds/index.ts`.
+3. Register the client component in `src/components/puck/fields/responsive-kinds/client-registry.tsx`.
+4. Optionally add a convenience builder in `src/lib/puck/define-props.ts`.
 
 ### 4. Rendering
 
@@ -143,6 +173,8 @@ const classes = cn(
 );
 ```
 
+Responsive numeric props stay as data. Use `resolveAt(...)` or your own component logic when they need to influence layout or behavior; they do not go through `resolveResponsive(...)`.
+
 ## Tailwind source hints
 
 Because `resolveResponsive` builds prefixed class names like `md:p-4` at runtime, Tailwind's scanner never sees them in source. Every responsive token needs a corresponding `@source inline(...)` directive in `src/app/styles.css`:
@@ -187,31 +219,37 @@ import { padding, bgColor, type Spacing, type Color } from "@/lib/puck/tokens";
 type CardProps = {
   content: Slot;
   padding: ResponsiveValue<Spacing>;
+  columns: ResponsiveValue<number>;
   bgColor: Color;
   title: string;
 };
 
 const props = defineProps({
   content: field.slot(),
-  padding: responsive.token(padding, { label: "Padding", default: "md" }),
+  padding: responsive.select(padding, { label: "Padding", default: "md" }),
+  columns: responsive.number({ label: "Columns", default: { base: 1, md: 2 }, min: 1, max: 4, step: 1 }),
   bgColor: field.select(bgColor, { label: "Background" }),
   title: field.raw({ type: "text", label: "Title" }, ""),
 });
 ```
 
 ### Step 3 — Export the component config
 
-Spread `props` onto the config and destructure in `render`. Use `resolveResponsive` for responsive props and direct `token.classes[value]` lookups for static ones:
+Spread `props` onto the config and destructure in `render`. Use `resolveResponsive` for responsive token props, `resolveAt` or component logic for responsive numeric props, and direct `token.classes[value]` lookups for static ones:
 
 ```ts
+import { resolveAt } from "@/lib/puck/responsive";
 import { resolveResponsive } from "@/lib/puck/responsive-tailwind";
 import { cn } from "@/lib/utils";
 
 export const Card: ComponentConfig<CardProps> = {
   label: "Card",
   ...props,
-  render: ({ content: Content, padding: pad, bgColor: bg, title }) => (
-    <div className={cn(bgColor.classes[bg], resolveResponsive(pad, padding.classes))}>
+  render: ({ content: Content, padding: pad, columns, bgColor: bg, title }) => (
+    <div
+      className={cn(bgColor.classes[bg], resolveResponsive(pad, padding.classes))}
+      style={{ columns: resolveAt(columns, "base") }}
+    >
       {title && <h3>{title}</h3>}
       {Content && <Content />}
     </div>

src/app/[[...puckPath]]/page.tsx

@@ -1,36 +1,30 @@
-import { notFound } from "next/navigation";
 import { Metadata } from "next";
-import { getDocumentByPath } from "../../lib/documents/queries";
-import { Render } from "@puckeditor/core";
-import { config } from "@/puck.config";
+import { notFound } from "next/navigation";
+import { PuckRender } from "@/components/puck/render";
+import { getPublishedDocument } from "./published-document";
 
 export async function generateMetadata({
   params,
 }: {
-  params: Promise<{ puckPath: string[] }>;
+  params: Promise<{ puckPath?: string[] }>;
 }): Promise<Metadata> {
-  const { puckPath = [] } = await params;
-  const path = `/${puckPath.join("/")}`;
-
   return {
-    title: (await getDocumentByPath(path))?.root.props?.title,
+    title: (await getPublishedDocument(params))?.root.props?.title,
   };
 }
 
 export default async function Page({
   params,
 }: {
-  params: Promise<{ puckPath: string[] }>;
+  params: Promise<{ puckPath?: string[] }>;
 }) {
-  const { puckPath = [] } = await params;
-  const path = `/${puckPath.join("/")}`;
-  const data = await getDocumentByPath(path);
+  const data = await getPublishedDocument(params);
 
   if (!data) {
     return notFound();
   }
 
-  return <Render config={config} data={data} />;
+  return <PuckRender data={data} />;
 }
 
 export const dynamic = "force-static";

src/app/[[...puckPath]]/published-document.ts

@@ -0,0 +1,14 @@
+import { cache } from "react";
+import { getDocumentByPath } from "../../lib/documents/queries";
+
+type PublishedRouteParams = Promise<{ puckPath?: string[] }>;
+
+export async function getPublishedDocument(params: PublishedRouteParams) {
+  return getPublishedDocumentByPath(getPublishedPath(await params));
+}
+
+function getPublishedPath({ puckPath = [] }: { puckPath?: string[] }) {
+  return `/${puckPath.join("/")}`;
+}
+
+const getPublishedDocumentByPath = cache(getDocumentByPath);

src/app/editor/[id]/[slug]/PreviewPage.tsx

@@ -1,9 +1,8 @@
 import { notFound } from "next/navigation";
+import { PuckRender } from "@/components/puck/render";
 import { getVersionContent } from "../../../../lib/documents/queries";
 import { resolvePreviewVersionId } from "./version-selection";
 import { loadDocument } from "./params";
-import { Render } from "@puckeditor/core";
-import { config } from "@/puck.config";
 
 export default async function PreviewPage({
   documentId,
@@ -30,5 +29,5 @@ export default async function PreviewPage({
   const data = await getVersionContent(targetVersionId);
   if (!data) notFound();
 
-  return <Render config={config} data={data} />;
+  return <PuckRender data={data} />;
 }

src/components/puck/columns.tsx

@@ -27,8 +27,8 @@ const columnSlotDefaults = Object.fromEntries(
 ) as Record<SlotKey, Slot>;
 
 const props = defineProps({
-  columns: responsive.token(columnCount, { label: "Columns", default: { base: "1", md: "2" } }),
-  gap: responsive.token(gap, { label: "Gap", default: "md" }),
+  columns: responsive.select(columnCount, { label: "Columns", default: { base: "1", md: "2" } }),
+  gap: responsive.select(gap, { label: "Gap", default: "md" }),
 });
 
 export const Columns: ComponentConfig<ColumnsProps> = {

src/components/puck/container.tsx

@@ -28,8 +28,8 @@ type ContainerProps = ContainerStyle & {
 const props = defineProps({
   content: field.slot(),
   layout: field.radio(layout, { label: "Layout" }),
-  padding: responsive.token(padding, { label: "Padding", default: "md" }),
-  gap: responsive.token(gap, { label: "Gap", default: "md" }),
+  padding: responsive.select(padding, { label: "Padding", default: "md" }),
+  gap: responsive.select(gap, { label: "Gap", default: "md" }),
   align: field.radio(crossAxisAlign, { label: "Align items" }),
   justify: field.radio(justify, { label: "Justify" }),
   width: field.select(width, { label: "Max width" }),

src/components/puck/fields/responsive-field-client.tsx

@@ -1,98 +1,15 @@
 "use client";
 
-import { AutoField, FieldLabel } from "@puckeditor/core";
+import type { ComponentType } from "react";
 import {
-  responsiveBreakpoints,
-  setAt,
-  type ResponsiveBreakpoint,
-  type ResponsiveValue,
-} from "@/lib/puck/responsive";
-import type { TokenOption } from "@/lib/puck/tokens";
-import type { ResponsiveFieldDescriptor } from "./responsive-field";
+  responsiveFieldClientRegistry,
+  type ResponsiveFieldClientProps,
+} from "./responsive-kinds/client-registry";
 
-const breakpointLabels: Record<ResponsiveBreakpoint, string> = {
-  base: "Base",
-  md: "Tablet",
-  lg: "Desktop",
-};
+export type { ResponsiveFieldClientProps } from "./responsive-kinds/client-registry";
 
-// Non-base breakpoints can clear their override and inherit from the smaller breakpoint.
-const inheritOption: TokenOption = { label: "–", value: "" };
+export function ResponsiveFieldClient(props: ResponsiveFieldClientProps) {
+  const FieldComponent = responsiveFieldClientRegistry[props.descriptor.kind] as ComponentType<any>;
 
-type ResponsiveFieldClientProps<T extends string> = {
-  label: string;
-  descriptor: ResponsiveFieldDescriptor<T>;
-  value: ResponsiveValue<T>;
-  onChange: (value: ResponsiveValue<T>) => void;
-  readOnly?: boolean;
-};
-
-function renderFieldControl<T extends string>({
-  descriptor,
-  isBase,
-  value,
-  onChange,
-  readOnly,
-}: {
-  descriptor: ResponsiveFieldDescriptor<T>;
-  isBase: boolean;
-  value: T | undefined;
-  onChange: (value: T | undefined) => void;
-  readOnly?: boolean;
-}) {
-  switch (descriptor.kind) {
-    case "select": {
-      const fieldOptions = isBase ? descriptor.options : [inheritOption, ...descriptor.options];
-      const isInheriting = !isBase && value === undefined;
-
-      return (
-        <div className={isInheriting ? "opacity-40" : undefined}>
-          <AutoField
-            field={{ type: "select", options: fieldOptions }}
-            onChange={(selected: string) => {
-              onChange(selected === "" ? undefined : (selected as T));
-            }}
-            value={value ?? ""}
-            readOnly={readOnly}
-          />
-        </div>
-      );
-    }
-  }
-}
-
-export function ResponsiveFieldClient<T extends string>({
-  label,
-  descriptor,
-  value,
-  onChange,
-  readOnly,
-}: ResponsiveFieldClientProps<T>) {
-  return (
-    <FieldLabel label={label} el="div" readOnly={readOnly}>
-      <div className="grid grid-cols-3 gap-1">
-        {responsiveBreakpoints.map((bp) => {
-          const isBase = bp === "base";
-          const currentValue = value[bp];
-
-          return (
-            <div key={bp} className="flex flex-col gap-1">
-              <span className="text-xs font-semibold text-muted-foreground">
-                {breakpointLabels[bp]}
-              </span>
-              {renderFieldControl({
-                descriptor,
-                isBase,
-                value: currentValue,
-                onChange: (nextValue) => {
-                  onChange(setAt(value, bp, nextValue));
-                },
-                readOnly,
-              })}
-            </div>
-          );
-        })}
-      </div>
-    </FieldLabel>
-  );
+  return <FieldComponent {...props} />;
 }

src/components/puck/fields/responsive-field-controls.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import {
+  fromResponsiveSelectValue,
+  toResponsiveSelectValue,
+} from "./responsive-select-control";
+import {
+  formatResponsiveNumberValue,
+  getResponsiveNumberChange,
+} from "./responsive-number-control";
+
+describe("responsive select control helpers", () => {
+  it("translates inherited select values at the UI boundary", () => {
+    expect(toResponsiveSelectValue(undefined)).toBe("");
+    expect(fromResponsiveSelectValue("")).toBeUndefined();
+    expect(fromResponsiveSelectValue("md")).toBe("md");
+  });
+});
+
+describe("responsive number control helpers", () => {
+  it("formats values for the number input", () => {
+    expect(formatResponsiveNumberValue(undefined)).toBe("");
+    expect(formatResponsiveNumberValue(3)).toBe("3");
+  });
+
+  it("clears inherited overrides, preserves base values, and validates numeric input", () => {
+    expect(getResponsiveNumberChange("", { isBase: false })).toEqual({
+      kind: "set",
+      value: undefined,
+    });
+    expect(getResponsiveNumberChange("", { isBase: true })).toEqual({
+      kind: "ignore",
+    });
+    expect(
+      getResponsiveNumberChange("4", { isBase: true, min: 1, max: 6 }),
+    ).toEqual({
+      kind: "set",
+      value: 4,
+    });
+    expect(
+      getResponsiveNumberChange("0", { isBase: true, min: 1, max: 6 }),
+    ).toEqual({
+      kind: "ignore",
+    });
+    expect(
+      getResponsiveNumberChange("9", { isBase: false, min: 1, max: 6 }),
+    ).toEqual({
+      kind: "ignore",
+    });
+  });
+});