@asheeui/puck 0.0.0-stage → 2.3.0

package/src/shared/fields.ts

@@ -0,0 +1,199 @@
+/**
+ * Reusable field definitions for the AsheeUI blocks.
+ *
+ * These builders are the boundary between a component's visual configuration and its
+ * React implementation: every option a block exposes is described here as a
+ * serializable field, so the value a consumer edits in the builder is a plain string,
+ * number or array that survives a save and a reload. Nothing in this file imports a
+ * component, and nothing it produces is a function, which is what lets the same
+ * definitions describe a block to the web editor and to the native renderer.
+ *
+ * The types come from `./types`, this package's own, rather than from the editor: the
+ * native entry has to load without a DOM editor, and a field is data either way.
+ */
+
+import type {
+  AsheeArrayField,
+  AsheeObjectField,
+  AsheeSelectField,
+  AsheeTextareaField,
+  AsheeTextField,
+} from "./types";
+
+/**
+ * Build a select field from the values a prop accepts.
+ *
+ * The options are derived from the same tuple the component's type uses, so a value
+ * the builder offers and a value the component accepts cannot drift.
+ *
+ * @param label - Label shown in the builder.
+ * @param options - The accepted values.
+ * @returns The field definition.
+ */
+export function selectField<T extends string>(
+  label: string,
+  options: readonly T[],
+): AsheeSelectField {
+  return {
+    type: "select",
+    label,
+    options: options.map((value) => ({ label: value, value })),
+  };
+}
+
+/**
+ * Build a single-line text field.
+ *
+ * @param label - Label shown in the builder.
+ * @param placeholder - Placeholder shown in the empty field.
+ * @returns The field definition.
+ */
+export function textField(label: string, placeholder?: string): AsheeTextField {
+  return { type: "text", label, placeholder };
+}
+
+/**
+ * Build a multi-line text field.
+ *
+ * @param label - Label shown in the builder.
+ * @param placeholder - Placeholder shown in the empty field.
+ * @returns The field definition.
+ */
+export function textareaField(
+  label: string,
+  placeholder?: string,
+): AsheeTextareaField {
+  return { type: "textarea", label, placeholder };
+}
+
+/**
+ * Alignment options shared by the patterns that can centre their content.
+ */
+export const ALIGNMENT_OPTIONS = ["start", "center"] as const;
+
+/**
+ * Vertical rhythm options shared by the section-level blocks.
+ */
+export const SPACING_OPTIONS = [
+  "none",
+  "xs",
+  "sm",
+  "md",
+  "lg",
+  "xl",
+  "2xl",
+] as const;
+
+/**
+ * Background treatments a section-level block can offer.
+ */
+export const BACKGROUND_OPTIONS = ["none", "muted", "tinted"] as const;
+
+/**
+ * Maximum content widths a block can offer.
+ */
+export const CONTAINER_SIZE_OPTIONS = ["sm", "md", "lg", "xl", "full"] as const;
+
+/**
+ * Column counts a grid block can offer.
+ */
+export const COLUMNS_OPTIONS = ["1", "2", "3", "4"] as const;
+
+/**
+ * Button variants a configured action can offer.
+ */
+export const ACTION_VARIANT_OPTIONS = [
+  "solid",
+  "faded",
+  "bordered",
+  "ghost",
+] as const;
+
+/**
+ * Fields of a configured action.
+ *
+ * The shape matches the framework's `ActionConfig` for the fields a builder can own:
+ * wording, destination and emphasis. An icon, a custom component and a click handler
+ * stay out, because none of them can be serialized.
+ */
+export const ACTION_FIELDS: AsheeObjectField = {
+  type: "object",
+  label: "Action",
+  objectFields: {
+    label: textField("Action label"),
+    href: textField("Action link", "/pricing"),
+    variant: selectField("Action emphasis", ACTION_VARIANT_OPTIONS),
+  },
+};
+
+/**
+ * A single feature inside a feature grid.
+ */
+export const FEATURE_ITEM_FIELD: AsheeArrayField<{
+  title: string;
+  description: string;
+}> = {
+  type: "array",
+  label: "Features",
+  arrayFields: {
+    title: textField("Feature title"),
+    description: textareaField("Feature description"),
+  },
+  defaultItemProps: { title: "New feature", description: "" },
+  getItemSummary: (item) => item.title,
+};
+
+/**
+ * A plan's feature line.
+ */
+export const PRICING_FEATURE_FIELD: AsheeArrayField<{
+  label: string;
+  included: boolean;
+}> = {
+  type: "array",
+  label: "Feature lines",
+  arrayFields: {
+    label: textField("Line"),
+    included: {
+      type: "radio",
+      label: "Included",
+      options: [
+        { label: "Included", value: true },
+        { label: "Not included", value: false },
+      ],
+    },
+  },
+  defaultItemProps: { label: "New line", included: true },
+  getItemSummary: (item) => item.label,
+};
+
+/**
+ * One navigation link.
+ */
+export const LINK_ITEM_FIELDS = {
+  label: textField("Link label"),
+  href: textField("Link", "/pricing"),
+} satisfies Record<string, AsheeTextField>;
+
+/**
+ * A testimonial quote.
+ */
+export const TESTIMONIAL_ITEM_FIELD: AsheeArrayField<{
+  quote: string;
+  name: string;
+  role: string;
+}> = {
+  type: "array",
+  label: "Quotes",
+  arrayFields: {
+    quote: textareaField("Quote"),
+    name: textField("Name"),
+    role: textField("Role"),
+  },
+  defaultItemProps: {
+    quote: "They send twice as fast as they used to.",
+    name: "New customer",
+    role: "",
+  },
+  getItemSummary: (item) => item.name,
+};

package/src/shared/index.ts

@@ -0,0 +1,14 @@
+/**
+ * The shared layer of the Puck integration.
+ *
+ * Everything in this module is true on both platforms: the field vocabulary, the block
+ * specs, the adapters that turn a builder value into a component prop, and the contract
+ * a stored page is read through. It imports no renderer and nothing from the editor, so
+ * it is the same code in a browser bundle and on a device — which is the whole reason
+ * the package is split this way.
+ */
+
+export * from "./adapters";
+export * from "./blocks";
+export * from "./fields";
+export * from "./types";

package/src/shared/types.ts

@@ -0,0 +1,278 @@
+/**
+ * The vocabulary the two halves of the Puck integration share.
+ *
+ * A page composed in a visual builder has to mean the same thing on the web and on a
+ * device. What makes that true is that the two renderers read one description of a
+ * block: the same fields, the same default values, the same label and the same
+ * category. Those descriptions live here, and the types in this module are what the
+ * shared block specs and both renderers are written against.
+ *
+ * The module is deliberately free of two dependencies rather than one. It imports no
+ * renderer — that is what makes it shared — and it imports nothing from
+ * `@puckeditor/core`, because that package is a DOM editor and the native entry has to
+ * be loadable, and type-checkable, without it. The field types below are this
+ * package's own, structurally the field types a builder understands: `type` is the
+ * discriminator and the rest is the data a form control needs. The web registry
+ * asserts once, where it assembles its `Config`, that they describe the same fields —
+ * which is the single place the two descriptions meet.
+ */
+
+import type { ReactNode } from "react";
+
+/**
+ * A single line of text.
+ */
+export interface AsheeTextField {
+  /** The builder draws this as a text input. */
+  type: "text";
+
+  /** Label shown in the builder. */
+  label: string;
+
+  /** Placeholder shown in the empty field. */
+  placeholder?: string;
+}
+
+/**
+ * Several lines of text.
+ */
+export interface AsheeTextareaField {
+  /** The builder draws this as a text area. */
+  type: "textarea";
+
+  /** Label shown in the builder. */
+  label: string;
+
+  /** Placeholder shown in the empty field. */
+  placeholder?: string;
+}
+
+/**
+ * One of a fixed set of values.
+ */
+export interface AsheeSelectField {
+  /** The builder draws this as a select control. */
+  type: "select";
+
+  /** Label shown in the builder. */
+  label: string;
+
+  /** The values the field offers. */
+  options: Array<{ label: string; value: string }>;
+}
+
+/**
+ * One of a small set of values, drawn as a radio group.
+ *
+ * A radio field is what a boolean is expressed with, because a builder's radio
+ * control holds the value itself rather than a string spelling of it.
+ */
+export interface AsheeRadioField {
+  /** The builder draws this as a radio group. */
+  type: "radio";
+
+  /** Label shown in the builder. */
+  label: string;
+
+  /** The values the field offers. */
+  options: Array<{ label: string; value: string | number | boolean }>;
+}
+
+/**
+ * A drop zone: where the builder lets a reader put other blocks.
+ */
+export interface AsheeSlotField {
+  /** The builder draws this as a drop zone. */
+  type: "slot";
+
+  /** Label shown in the builder. */
+  label: string;
+}
+
+/**
+ * A repeatable list of items, with its item type erased.
+ *
+ * This is the form the field union holds: a registry keeps fields of different item
+ * shapes in one object, so the collection's type has to state what every list has in
+ * common — the nested fields, the starting row and the summary — without naming an item.
+ * `AsheeArrayField` is the form a block writes, where the item type is known.
+ */
+export interface AsheeArrayFieldBase {
+  /** The builder draws this as a list with an add control. */
+  type: "array";
+
+  /** Label shown in the builder. */
+  label: string;
+
+  /** The fields of one item. */
+  arrayFields: Record<string, AsheeField>;
+
+  /** The item a new row starts as. */
+  defaultItemProps?: unknown;
+
+  /** The one line that summarises an item in the closed list. */
+  getItemSummary?: (item: never) => string;
+}
+
+/**
+ * A repeatable list of items.
+ *
+ * @typeParam Item - The shape of one item, which `arrayFields` describes field by
+ * field.
+ */
+export interface AsheeArrayField<Item = Record<string, unknown>>
+  extends Omit<AsheeArrayFieldBase, "defaultItemProps" | "getItemSummary"> {
+  /** The item a new row starts as. */
+  defaultItemProps?: Partial<Item>;
+
+  /** The one line that summarises an item in the closed list. */
+  getItemSummary?: (item: Item) => string;
+}
+
+/**
+ * A fixed group of fields.
+ */
+export interface AsheeObjectField {
+  /** The builder draws this as a nested group of controls. */
+  type: "object";
+
+  /** Label shown in the builder. */
+  label: string;
+
+  /** The fields of the group. */
+  objectFields: Record<string, AsheeField>;
+}
+
+/**
+ * Every field type the AsheeUI blocks use.
+ */
+export type AsheeField =
+  | AsheeTextField
+  | AsheeTextareaField
+  | AsheeSelectField
+  | AsheeRadioField
+  | AsheeSlotField
+  | AsheeArrayFieldBase
+  | AsheeObjectField;
+
+/**
+ * A block's visual configuration, stated once for both renderers.
+ *
+ * The three members are exactly the part of a block that cannot differ between
+ * platforms: a label a builder shows, the fields it fills in, and the value it starts
+ * with. The render function is deliberately absent — that is the one part the platform
+ * owns — and the two platform registries add it.
+ *
+ * `fields` is keyed by name rather than tied to the prop type. A drop zone names a key
+ * whose value is not part of the component's own props on either platform (the web
+ * passes a `SlotComponent`, the platform passes rendered children), so the linked form
+ * would be untruthful for exactly the blocks where the two differ most.
+ *
+ * @typeParam TProps - The props the block's render function receives.
+ */
+export interface AsheeBlockSpec<TProps> {
+  /** Name of the block in the builder's block list. */
+  label: string;
+
+  /** The fields the builder fills in. */
+  fields: Record<string, AsheeField>;
+
+  /** The value a new block starts with. */
+  defaultProps: Partial<TProps>;
+}
+
+/**
+ * A block as a renderer sees it.
+ *
+ * The render function returns a plain React node rather than a builder's render
+ * result, because the same shape has to describe a block to two renderers: the web
+ * draws it into a DOM inside the editor's preview and inside a published page, and the
+ * platform draws it into a native view when it renders a stored page. On the platform
+ * it is handed the block's props with every drop zone already resolved to a rendered
+ * node, because a native screen has no editor to resolve one for it.
+ *
+ * @typeParam TProps - The props the render function receives.
+ */
+export interface AsheeBlock<TProps> {
+  /** Name of the block in the builder's block list. */
+  label: string;
+
+  /** The fields the block declares, read to find its drop zones. */
+  fields: Record<string, AsheeField>;
+
+  /** The value the block resolves when a stored page omits a key. */
+  defaultProps?: Partial<TProps>;
+
+  /** Draw the block. */
+  render: (props: TProps) => ReactNode;
+}
+
+/**
+ * One category of the builder's block list.
+ */
+export interface AsheePuckCategoryDefinition {
+  /** Heading the builder shows for the category. */
+  title: string;
+
+  /** The blocks filed under it. */
+  components: string[];
+}
+
+/**
+ * The categories a block can be filed under, by key.
+ */
+export type AsheePuckCategories = Record<string, AsheePuckCategoryDefinition>;
+
+/**
+ * The page shell a stored page renders into.
+ */
+export interface AsheePuckRootProps {
+  /** The page the builder composed. */
+  children?: ReactNode;
+}
+
+/**
+ * The native registry: every block, the categories they are filed under, and the page
+ * shell a stored page renders into.
+ */
+export interface AsheeNativePuckConfig {
+  /** The blocks, by the name a stored page names them with. */
+  components: Record<string, AsheeBlock<never>>;
+
+  /** The categories the blocks are filed under. */
+  categories: AsheePuckCategories;
+
+  /** The page shell every stored page renders into. */
+  root: AsheeBlock<AsheePuckRootProps>;
+}
+
+/**
+ * One block in a stored page.
+ *
+ * The shape is the builder's own serialized document, and it is described here rather
+ * than imported so that reading a stored page needs nothing from the editor. A drop
+ * zone's children are stored under the zone's own key in `props`, which is why `props`
+ * is an open record: the renderer reads a zone by name.
+ */
+export interface AsheePuckBlockData {
+  /** The block's name, which is the key it is registered under. */
+  type: string;
+
+  /** The value the editor stored for the block, including its drop zones. */
+  props: Record<string, unknown>;
+}
+
+/**
+ * A stored page, as the editor publishes it.
+ *
+ * Only the members a renderer reads are stated. A published document carries more — a
+ * history, a set of zones — and a renderer that ignored them would be right to: this
+ * is the contract a page is *rendered* from.
+ */
+export interface AsheePuckData {
+  /** The page's outer value, which the page shell may read. */
+  root?: { props?: Record<string, unknown> };
+
+  /** The blocks of the page, in order. */
+  content: AsheePuckBlockData[];
+}

package/src/web/blocks/content.tsx

@@ -0,0 +1,55 @@
+"use client";
+
+/**
+ * The web content blocks.
+ *
+ * Each block is the framework component plus the shared spec: the label, the fields and
+ * the defaults come from `src/shared`, and only the drawing is written here. That is
+ * what keeps the editor's promise — a block cannot describe one thing and render
+ * another — while letting each platform draw with its own components.
+ */
+
+import { Section, Typography } from "@asheeui/web";
+import { SectionHeading } from "@asheeui/web/section-kit";
+import type {
+  AsheeBlock,
+  HeadingBlockProps,
+  TextBlockProps,
+} from "../../shared";
+import { HEADING_SPEC, TEXT_SPEC } from "../../shared";
+
+/**
+ * A section heading with an optional eyebrow and description.
+ */
+export const headingBlock: AsheeBlock<HeadingBlockProps> = {
+  ...HEADING_SPEC,
+  render: ({ eyebrow, title, description, align }) => (
+    <Section spacing="md" contained>
+      <SectionHeading
+        eyebrow={eyebrow || undefined}
+        title={title || undefined}
+        description={description || undefined}
+        align={align ?? "start"}
+        size="lg"
+      />
+    </Section>
+  ),
+};
+
+/**
+ * A paragraph of body text.
+ */
+export const textBlock: AsheeBlock<TextBlockProps> = {
+  ...TEXT_SPEC,
+  render: ({ text, align }) => (
+    <Section spacing="sm" contained>
+      <Typography
+        role="body-lg"
+        className={
+          align === "center" ? "mx-auto max-w-2xl text-center" : "max-w-2xl"
+        }>
+        {text}
+      </Typography>
+    </Section>
+  ),
+};

package/src/web/blocks/layout.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+/**
+ * The web layout blocks.
+ *
+ * A band and a two-column arrangement. Both are the only blocks whose props hold a
+ * drop zone, so both are written against the builder's own `SlotComponent`: the
+ * editor drops a component into the field and the block places it. The fields and the
+ * defaults still come from `src/shared`, so the platform offers the same two zones.
+ */
+
+import { cn } from "@asheeui/core";
+import { Section } from "@asheeui/web";
+import type { SlotComponent } from "@puckeditor/core";
+import type {
+  AsheeBlock,
+  ColumnsBandProps,
+  SectionBandProps,
+} from "../../shared";
+import { COLUMN_RATIO_CLASS, COLUMNS_SPEC, SECTION_SPEC } from "../../shared";
+
+/**
+ * The props of the band block.
+ */
+export type SectionBlockProps = SectionBandProps & {
+  /** Content dropped into the band. */
+  content?: SlotComponent;
+};
+
+/**
+ * A band with its own vertical rhythm and background.
+ */
+export const sectionBlock: AsheeBlock<SectionBlockProps> = {
+  ...SECTION_SPEC,
+  render: ({ spacing, background, content: Content }) => (
+    <Section
+      spacing={spacing ?? "lg"}
+      background={background ?? "none"}
+      contained>
+      {Content ? <Content /> : null}
+    </Section>
+  ),
+};
+
+/**
+ * The props of the two-column block.
+ */
+export type ColumnsBlockProps = ColumnsBandProps & {
+  /** Content of the first column. */
+  start?: SlotComponent;
+
+  /** Content of the second column. */
+  end?: SlotComponent;
+};
+
+/**
+ * Two columns that stack on a narrow screen.
+ */
+export const columnsBlock: AsheeBlock<ColumnsBlockProps> = {
+  ...COLUMNS_SPEC,
+  render: ({ ratio, spacing, start: Start, end: End }) => (
+    <Section spacing={spacing ?? "lg"} contained>
+      <div
+        className={cn(
+          "grid grid-cols-1 gap-8",
+          COLUMN_RATIO_CLASS[ratio ?? "50/50"],
+        )}>
+        <div className="min-w-0">{Start ? <Start /> : null}</div>
+        <div className="min-w-0">{End ? <End /> : null}</div>
+      </div>
+    </Section>
+  ),
+};

package/src/web/blocks/navigation.tsx

@@ -0,0 +1,72 @@
+"use client";
+
+/**
+ * The web navigation blocks.
+ *
+ * A bar and a footer, with the navigation as data: link lists a non-developer can edit
+ * and no application state. The bar's action region is the framework's own action
+ * group, so a configured action renders exactly as a hand-written button does and
+ * inherits the same cascade. The fields and the defaults come from `src/shared`.
+ */
+
+import { Footer, Navbar } from "@asheeui/web";
+import { ActionGroup } from "@asheeui/web/section-kit";
+import type {
+  AsheeBlock,
+  FooterBlockProps,
+  NavbarBlockProps,
+} from "../../shared";
+import { FOOTER_SPEC, NAVBAR_SPEC, toAction } from "../../shared";
+
+/**
+ * The navigation bar of a page.
+ */
+export const navbarBlock: AsheeBlock<NavbarBlockProps> = {
+  ...NAVBAR_SPEC,
+  render: ({
+    brand,
+    brandHref,
+    align,
+    links,
+    primaryAction,
+    secondaryAction,
+  }) => (
+    <Navbar
+      brand={brand || undefined}
+      brandHref={brandHref || undefined}
+      align={align ?? "center"}
+      links={(links ?? []).map((link) => ({
+        label: link.label ?? "",
+        href: link.href,
+      }))}
+      actions={
+        <ActionGroup
+          primaryAction={toAction(primaryAction)}
+          secondaryAction={toAction(secondaryAction)}
+        />
+      }
+    />
+  ),
+};
+
+/**
+ * The footer of a page.
+ */
+export const footerBlock: AsheeBlock<FooterBlockProps> = {
+  ...FOOTER_SPEC,
+  render: ({ brand, description, groups, copyright }) => (
+    <Footer
+      brand={brand || undefined}
+      description={description || undefined}
+      copyright={copyright || undefined}
+      groups={(groups ?? []).map((group, index) => ({
+        id: index,
+        title: group.title ?? "Links",
+        links: (group.links ?? []).map((item) => ({
+          label: item.label ?? "",
+          href: item.href,
+        })),
+      }))}
+    />
+  ),
+};