@asheeui/puck 0.0.0-stage → 2.3.0

package/src/native/blocks/sections.tsx

@@ -0,0 +1,174 @@
+/**
+ * The platform marketing section blocks.
+ *
+ * Each one is a thin adapter over the framework component of the same name, so the
+ * builder edits the component's own props rather than a parallel model of them — and it
+ * edits them once, for both platforms: the label, the fields and the defaults come from
+ * `src/shared`, and what is written here is only how the component is drawn on a device.
+ */
+
+import {
+  CTA,
+  FeatureGrid,
+  Hero,
+  PricingCard,
+  Testimonials,
+} from "@asheeui/native";
+import type {
+  AsheeBlock,
+  CtaBlockProps,
+  FeatureGridBlockProps,
+  HeroBlockProps,
+  PricingCardBlockProps,
+  TestimonialsBlockProps,
+} from "../../shared";
+import {
+  CTA_SPEC,
+  FEATURE_GRID_SPEC,
+  HERO_SPEC,
+  PRICING_CARD_SPEC,
+  TESTIMONIALS_SPEC,
+  toAction,
+  toColumns,
+} from "../../shared";
+
+/**
+ * The leading statement of a page.
+ */
+export const heroBlock: AsheeBlock<HeroBlockProps> = {
+  ...HERO_SPEC,
+  render: ({
+    eyebrow,
+    title,
+    description,
+    primaryAction,
+    secondaryAction,
+    align,
+    background,
+    contentWidth,
+  }) => (
+    <Hero
+      eyebrow={eyebrow || undefined}
+      title={title ?? ""}
+      description={description || undefined}
+      primaryAction={toAction(primaryAction)}
+      secondaryAction={toAction(secondaryAction)}
+      align={align ?? "start"}
+      background={background ?? "none"}
+      containerSize={contentWidth ?? "lg"}
+    />
+  ),
+};
+
+/**
+ * The closing call to action of a page.
+ */
+export const ctaBlock: AsheeBlock<CtaBlockProps> = {
+  ...CTA_SPEC,
+  render: ({
+    eyebrow,
+    title,
+    description,
+    primaryAction,
+    secondaryAction,
+    align,
+    background,
+    panel,
+  }) => (
+    <CTA
+      eyebrow={eyebrow || undefined}
+      title={title ?? ""}
+      description={description || undefined}
+      primaryAction={toAction(primaryAction)}
+      secondaryAction={toAction(secondaryAction)}
+      align={align ?? "center"}
+      background={background ?? "none"}
+      panel={panel ?? "bordered"}
+    />
+  ),
+};
+
+/**
+ * A band of features laid out in a responsive grid.
+ */
+export const featureGridBlock: AsheeBlock<FeatureGridBlockProps> = {
+  ...FEATURE_GRID_SPEC,
+  render: ({
+    eyebrow,
+    title,
+    description,
+    items,
+    columnsMd,
+    columnsLg,
+    align,
+    background,
+  }) => (
+    <FeatureGrid
+      eyebrow={eyebrow || undefined}
+      title={title || undefined}
+      description={description || undefined}
+      align={align ?? "center"}
+      background={background ?? "none"}
+      columnsMd={toColumns(columnsMd)}
+      columnsLg={toColumns(columnsLg)}
+      items={(items ?? []).map((item, index) => ({
+        id: index,
+        title: item.title ?? "",
+        description: item.description || undefined,
+      }))}
+    />
+  ),
+};
+
+/**
+ * A band of attributed customer quotes.
+ */
+export const testimonialsBlock: AsheeBlock<TestimonialsBlockProps> = {
+  ...TESTIMONIALS_SPEC,
+  render: ({ eyebrow, title, description, items, align }) => (
+    <Testimonials
+      eyebrow={eyebrow || undefined}
+      title={title || undefined}
+      description={description || undefined}
+      align={align ?? "center"}
+      items={(items ?? []).map((item, index) => ({
+        id: index,
+        quote: item.quote ?? "",
+        name: item.name ?? "",
+        role: item.role || undefined,
+      }))}
+    />
+  ),
+};
+
+/**
+ * One plan in a pricing table.
+ */
+export const pricingCardBlock: AsheeBlock<PricingCardBlockProps> = {
+  ...PRICING_CARD_SPEC,
+  render: ({
+    badge,
+    name,
+    price,
+    period,
+    description,
+    features,
+    highlighted,
+    primaryAction,
+  }) => (
+    <PricingCard
+      badge={badge || undefined}
+      name={name ?? ""}
+      price={price ?? ""}
+      period={period || undefined}
+      description={description || undefined}
+      highlighted={highlighted ?? false}
+      features={(features ?? []).map((feature, index) => ({
+        id: index,
+        label: feature.label ?? "",
+        included: feature.included !== false,
+      }))}
+      primaryAction={toAction(primaryAction)}
+    />
+  ),
+};

package/src/native/blocks/utility.tsx

@@ -0,0 +1,27 @@
+/**
+ * The platform utility blocks.
+ *
+ * The empty state is the one utility block a marketing or application page needs from a
+ * builder: a region that has nothing in it yet, which a non-developer can word and
+ * justify without touching code. The fields and the defaults come from `src/shared`.
+ */
+
+import { EmptyState } from "@asheeui/native";
+import type { AsheeBlock, EmptyStateBlockProps } from "../../shared";
+import { EMPTY_STATE_SPEC, toAction } from "../../shared";
+
+/**
+ * A region with nothing in it.
+ */
+export const emptyStateBlock: AsheeBlock<EmptyStateBlockProps> = {
+  ...EMPTY_STATE_SPEC,
+  render: ({ title, description, type, panel, primaryAction }) => (
+    <EmptyState
+      title={title ?? ""}
+      description={description || undefined}
+      type={type ?? "info"}
+      panel={panel ?? false}
+      primaryAction={toAction(primaryAction)}
+    />
+  ),
+};

package/src/native/config.tsx

@@ -0,0 +1,66 @@
+/**
+ * The AsheeUI registry, on the platform.
+ *
+ * The native twin of the web configuration: every block a stored page can name, the
+ * categories they are filed under, and the page shell a stored page renders into. It
+ * exists so that a device renders the page the editor composed — not a second page
+ * model of it — and so that adding a block is one addition in `src/shared` plus one
+ * drawing per platform.
+ *
+ * The category map and the block labels come from `src/shared`, which is what keeps the
+ * two registries honest: neither can offer a category the other does not, and neither
+ * can offer a block the other has not.
+ */
+
+import type { AsheeNativePuckConfig } from "../shared";
+import { PUCK_CATEGORIES } from "../shared";
+import { headingBlock, textBlock } from "./blocks/content";
+import { columnsBlock, sectionBlock } from "./blocks/layout";
+import { footerBlock, navbarBlock } from "./blocks/navigation";
+import {
+  ctaBlock,
+  featureGridBlock,
+  heroBlock,
+  pricingCardBlock,
+  testimonialsBlock,
+} from "./blocks/sections";
+import { emptyStateBlock } from "./blocks/utility";
+import { PuckRoot } from "./root";
+
+/**
+ * The blocks a stored page can name.
+ *
+ * The assertion is deliberate and it is the one place this package asserts rather than
+ * checks: a registry holds blocks of different props, so the collection's type is the
+ * open one, while each entry keeps its own type where it is declared. The package's own
+ * tests assert the two properties that matter here — that every block in the registry
+ * renders, and that the category map names exactly the blocks that exist.
+ */
+const components = {
+  Section: sectionBlock,
+  Columns: columnsBlock,
+  Heading: headingBlock,
+  Text: textBlock,
+  Navbar: navbarBlock,
+  Footer: footerBlock,
+  Hero: heroBlock,
+  CTA: ctaBlock,
+  FeatureGrid: featureGridBlock,
+  Testimonials: testimonialsBlock,
+  PricingCard: pricingCardBlock,
+  EmptyState: emptyStateBlock,
+} as unknown as AsheeNativePuckConfig["components"];
+
+/**
+ * The native registry a stored page is rendered with.
+ */
+export const asheeNativePuckConfig: AsheeNativePuckConfig = {
+  components,
+  categories: PUCK_CATEGORIES,
+  root: {
+    label: "Page",
+    fields: {},
+    defaultProps: {},
+    render: ({ children }) => <PuckRoot>{children}</PuckRoot>,
+  },
+};

package/src/native/index.ts

@@ -0,0 +1,18 @@
+/**
+ * The platform half of the Puck integration.
+ *
+ * It is the shared layer plus this platform's drawings, and the renderer that turns a
+ * stored page into a screen. Nothing here imports React DOM, Tailwind or the editor: a
+ * device reaches this file without loading a single byte of the web edition, which is
+ * the property the whole split exists for.
+ */
+
+export * from "../shared";
+export * from "./blocks/content";
+export * from "./blocks/layout";
+export * from "./blocks/navigation";
+export * from "./blocks/sections";
+export * from "./blocks/utility";
+export * from "./config";
+export * from "./render";
+export * from "./root";

package/src/native/render.tsx

@@ -0,0 +1,113 @@
+/**
+ * Rendering a stored page, on the platform.
+ *
+ * A device has no editor, so what it needs from a published document is a renderer:
+ * walk the blocks the editor stored, resolve each drop zone into the nodes that belong
+ * there, and draw each block through the registry the two platforms share. That is all
+ * this is — the platform's counterpart of the editor's own `Render`, which is why the
+ * two entries export a component of the same name and an application calls one.
+ *
+ * Two properties are worth stating. A block the registry does not know is dropped rather
+ * than thrown on, because a page saved by a newer editor should not crash an older
+ * application. And a key the document omits resolves to the block's default value, so a
+ * partial payload — a page saved before a field existed — renders the same way the
+ * editor would have shown it.
+ */
+
+import { Fragment, type ReactNode } from "react";
+import type {
+  AsheeBlock,
+  AsheeNativePuckConfig,
+  AsheePuckBlockData,
+  AsheePuckData,
+} from "../shared";
+import { asheeNativePuckConfig } from "./config";
+
+/**
+ * Render a list of blocks.
+ *
+ * @param content - The blocks, in order.
+ * @param config - The registry to render them with.
+ * @param keyPrefix - A prefix that keeps a nested block's key unique among its siblings.
+ * @returns The rendered blocks.
+ */
+function renderBlocks(
+  content: AsheePuckBlockData[],
+  config: AsheeNativePuckConfig,
+  keyPrefix: string,
+): ReactNode[] {
+  return content.map((item, index) =>
+    renderBlock(item, config, `${keyPrefix}-${index}`),
+  );
+}
+
+/**
+ * Render one block, resolving its drop zones first.
+ *
+ * @param item - The block as the document stored it.
+ * @param config - The registry to render it with.
+ * @param key - A key unique among the block's siblings.
+ * @returns The rendered block, or null when the registry does not know its type.
+ */
+function renderBlock(
+  item: AsheePuckBlockData,
+  config: AsheeNativePuckConfig,
+  key: string,
+): ReactNode {
+  const block = config.components[item.type] as
+    | AsheeBlock<Record<string, unknown>>
+    | undefined;
+
+  if (!block) return null;
+
+  const props: Record<string, unknown> = {
+    ...block.defaultProps,
+    ...item.props,
+  };
+
+  // A drop zone's children are stored under the zone's own key, so the fields are what
+  // says which keys hold blocks rather than values.
+  for (const [name, field] of Object.entries(block.fields ?? {})) {
+    if (field?.type !== "slot") continue;
+
+    const children = item.props?.[name];
+    props[name] = renderBlocks(
+      Array.isArray(children) ? (children as AsheePuckBlockData[]) : [],
+      config,
+      `${key}-${name}`,
+    );
+  }
+
+  return <Fragment key={key}>{block.render(props)}</Fragment>;
+}
+
+/**
+ * Props of {@link PuckPage}.
+ */
+export interface PuckPageProps {
+  /** The page the builder published. */
+  data: AsheePuckData;
+
+  /** The registry to render it with. Defaults to the AsheeUI configuration. */
+  config?: AsheeNativePuckConfig;
+}
+
+/**
+ * Render a stored page.
+ *
+ * @param props - The stored page, and optionally the registry to render it with.
+ * @returns The rendered page.
+ *
+ * @example
+ * ```tsx
+ * <PuckPage data={page} />
+ * ```
+ */
+export function PuckPage({
+  data,
+  config = asheeNativePuckConfig,
+}: PuckPageProps): ReactNode {
+  const children = renderBlocks(data.content ?? [], config, "root");
+
+  return config.root.render({ children });
+}

package/src/native/root.tsx

@@ -0,0 +1,35 @@
+/**
+ * The page shell a stored page renders into, on the platform.
+ *
+ * A block resolves its theme through the framework provider, so the shell supplies one
+ * when the application has not. An existing provider is respected rather than nested, so
+ * an application's own configuration keeps applying to a built page — a second provider
+ * would replace the resolved configuration with the framework's own defaults.
+ *
+ * The shell is the platform's own view rather than a re-implementation of the web's
+ * `<div>`: a page fills the screen it is drawn in, and the background it paints is the
+ * framework's background role.
+ */
+
+import { AsheeNativeConfigContext, AsheeNativeProvider } from "@asheeui/native";
+import { useContext } from "react";
+import { View } from "react-native";
+import type { AsheePuckRootProps } from "../shared";
+
+/**
+ * The published page's root.
+ *
+ * @param props - The page the builder composed.
+ * @returns The page, inside the framework's provider when the application has none.
+ */
+export function PuckRoot({ children }: AsheePuckRootProps) {
+  const existingConfig = useContext(AsheeNativeConfigContext);
+
+  const page = <View className="bg-background flex-1 w-full">{children}</View>;
+
+  return existingConfig ? (
+    page
+  ) : (
+    <AsheeNativeProvider>{page}</AsheeNativeProvider>
+  );
+}

package/src/shared/adapters.ts

@@ -0,0 +1,82 @@
+/**
+ * Adapters between builder values and framework props.
+ *
+ * A builder holds plain strings, because that is what a form control produces. The
+ * framework's props are unions of named tokens. These adapters are the single place
+ * where one becomes the other, so a block's render function stays a mapping of names
+ * rather than a parsing exercise, and a value that is not accepted by the component
+ * resolves to undefined rather than to a wrong class.
+ *
+ * Both renderers use them, which is why they live with the specs rather than with
+ * either platform: a value the web accepts and the platform rejects would be two
+ * different pages built from one document.
+ */
+
+import type { GridColumns, Variant } from "@asheeui/core";
+
+/**
+ * One action as a builder holds it.
+ *
+ * The keys are required because a field set is a form the builder fills in, and
+ * `defaultProps` supplies a complete value for every block that offers one. A
+ * published payload can still arrive with a key missing, which is why the adapter that
+ * reads it accepts a partial value.
+ */
+export type BuilderAction = {
+  /** Wording of the action. */
+  label: string;
+
+  /** Destination of the action. */
+  href: string;
+
+  /** Emphasis of the action. */
+  variant: string;
+};
+
+/** The variants an action accepts, used to validate a builder value. */
+const ACTION_VARIANTS: readonly string[] = [
+  "solid",
+  "faded",
+  "bordered",
+  "ghost",
+  "underlined",
+];
+
+/**
+ * Turn a builder action into a configured action.
+ *
+ * @param action - The action the builder holds, which may be missing a key when it
+ * comes from a stored page rather than from the editor.
+ * @returns The action the framework renders, or undefined when it has no wording,
+ * because an action without a name cannot be read or clicked.
+ */
+export function toAction(action: Partial<BuilderAction> | undefined) {
+  if (!action?.label) {
+    return undefined;
+  }
+
+  return {
+    label: action.label,
+    href: action.href,
+    variant:
+      action.variant && ACTION_VARIANTS.includes(action.variant)
+        ? (action.variant as Variant)
+        : undefined,
+  };
+}
+
+/**
+ * Turn a builder column count into a grid column count.
+ *
+ * @param value - The column count as a string, which is what a select field holds.
+ * @returns The numeric column count, or undefined when the value is not one the grid
+ * accepts.
+ */
+export function toColumns(value: string | undefined): GridColumns | undefined {
+  if (!value) return undefined;
+
+  const parsed = Number(value);
+  if (![1, 2, 3, 4, 6, 12].includes(parsed)) return undefined;
+
+  return parsed as GridColumns;
+}

package/src/shared/blocks/content.ts

@@ -0,0 +1,80 @@
+/**
+ * The content blocks, stated once for both renderers.
+ *
+ * These are the blocks that place words on a page: a section heading and a paragraph.
+ * What is stated here is everything but the drawing — the label a builder shows, the
+ * fields it fills in and the value each starts as — because the drawing is the one part
+ * that is the platform's: the web composes a `Section` and a `Typography`, the platform
+ * composes its own two. Everything else would otherwise be stated twice and could
+ * drift.
+ */
+
+import {
+  ALIGNMENT_OPTIONS,
+  selectField,
+  textareaField,
+  textField,
+} from "../fields";
+import type { AsheeBlockSpec } from "../types";
+
+/**
+ * The props of the heading block.
+ */
+export type HeadingBlockProps = {
+  /** Short label above the heading. */
+  eyebrow?: string;
+
+  /** The heading itself. */
+  title?: string;
+
+  /** Supporting sentence under the heading. */
+  description?: string;
+
+  /** Horizontal alignment of the block. */
+  align?: "start" | "center";
+};
+
+/**
+ * A section heading with an optional eyebrow and description.
+ */
+export const HEADING_SPEC: AsheeBlockSpec<HeadingBlockProps> = {
+  label: "Heading",
+  fields: {
+    eyebrow: textField("Eyebrow", "Why teams switch"),
+    title: textField("Heading", "Everything in one place"),
+    description: textareaField("Description"),
+    align: selectField("Alignment", ALIGNMENT_OPTIONS),
+  },
+  defaultProps: {
+    eyebrow: "",
+    title: "Everything in one place",
+    description: "",
+    align: "start",
+  },
+};
+
+/**
+ * The props of the text block.
+ */
+export type TextBlockProps = {
+  /** The paragraph. */
+  text?: string;
+
+  /** Alignment of the paragraph. */
+  align?: "start" | "center";
+};
+
+/**
+ * A paragraph of body text.
+ */
+export const TEXT_SPEC: AsheeBlockSpec<TextBlockProps> = {
+  label: "Text",
+  fields: {
+    text: textareaField("Text", "Write the paragraph here."),
+    align: selectField("Alignment", ALIGNMENT_OPTIONS),
+  },
+  defaultProps: {
+    text: "Write the paragraph here.",
+    align: "start",
+  },
+};

package/src/shared/blocks/index.ts

@@ -0,0 +1,100 @@
+/**
+ * The block specs, gathered.
+ *
+ * One module states the set: the names a stored page uses, the order a builder lists
+ * them in, and the categories they are filed under. A block that is added without a
+ * category, or a category that names a block nobody implemented, is caught by the
+ * package's own tests rather than by an editor that silently shows nothing — which is
+ * why the name list and the category map live beside the specs rather than in either
+ * renderer.
+ */
+
+import type { AsheeBlockSpec, AsheePuckCategories } from "../types";
+import { HEADING_SPEC, TEXT_SPEC } from "./content";
+import { COLUMNS_SPEC, SECTION_SPEC } from "./layout";
+import { FOOTER_SPEC, NAVBAR_SPEC } from "./navigation";
+import {
+  CTA_SPEC,
+  FEATURE_GRID_SPEC,
+  HERO_SPEC,
+  PRICING_CARD_SPEC,
+  TESTIMONIALS_SPEC,
+} from "./sections";
+import { EMPTY_STATE_SPEC } from "./utility";
+
+export * from "./content";
+export * from "./layout";
+export * from "./navigation";
+export * from "./sections";
+export * from "./utility";
+
+/**
+ * The blocks a stored page can name, in the order a builder lists them.
+ */
+export const PUCK_BLOCK_NAMES = [
+  "Section",
+  "Columns",
+  "Heading",
+  "Text",
+  "Navbar",
+  "Footer",
+  "Hero",
+  "CTA",
+  "FeatureGrid",
+  "Testimonials",
+  "PricingCard",
+  "EmptyState",
+] as const;
+
+/**
+ * The name of one block, which is also its key in a page's content.
+ */
+export type PuckBlockName = (typeof PUCK_BLOCK_NAMES)[number];
+
+/**
+ * The specs, by block name.
+ *
+ * This is the one place the set is complete: a name without a spec, or a spec without a
+ * name, is a compile error rather than an editor that silently shows nothing, and both
+ * registries read their labels and fields from what is here. A consumer building its own
+ * registry — an application that wants a subset of the blocks, or one of its own beside
+ * them — can start from the same specs rather than restating the fields.
+ */
+export const PUCK_SPECS: Record<
+  PuckBlockName,
+  AsheeBlockSpec<Record<string, unknown>>
+> = {
+  Section: SECTION_SPEC,
+  Columns: COLUMNS_SPEC,
+  Heading: HEADING_SPEC,
+  Text: TEXT_SPEC,
+  Navbar: NAVBAR_SPEC,
+  Footer: FOOTER_SPEC,
+  Hero: HERO_SPEC,
+  CTA: CTA_SPEC,
+  FeatureGrid: FEATURE_GRID_SPEC,
+  Testimonials: TESTIMONIALS_SPEC,
+  PricingCard: PRICING_CARD_SPEC,
+  EmptyState: EMPTY_STATE_SPEC,
+};
+
+/**
+ * The categories a block can be filed under.
+ *
+ * A block that appears in none of them is listed by the builder's own fallback
+ * category, which is why the list stays explicit rather than complete by accident.
+ */
+export const PUCK_CATEGORIES: AsheePuckCategories = {
+  Layout: { title: "Layout", components: ["Section", "Columns"] },
+  Navigation: { title: "Navigation", components: ["Navbar", "Footer"] },
+  Hero: { title: "Hero", components: ["Hero"] },
+  Content: { title: "Content", components: ["Heading", "Text"] },
+  Features: { title: "Features", components: ["FeatureGrid"] },
+  CTA: { title: "CTA", components: ["CTA"] },
+  Pricing: { title: "Pricing", components: ["PricingCard"] },
+  Testimonials: {
+    title: "Testimonials",
+    components: ["Testimonials"],
+  },
+  Utility: { title: "Utility", components: ["EmptyState"] },
+};