@asheeui/puck 0.0.0-stage → 2.3.0

package/src/shared/blocks/layout.ts

@@ -0,0 +1,82 @@
+/**
+ * The layout blocks, stated once for both renderers.
+ *
+ * A band with its own rhythm and background, and a two-column arrangement. These are
+ * the two blocks that hold other blocks, and they are also the two whose *props* differ
+ * between the platforms while their *fields* do not: the web hands a render function a
+ * drop-zone component to place, the platform hands it rendered children. So the fields
+ * and the defaults are stated here, once, and the prop type each renderer receives is
+ * declared beside it — which keeps a builder from offering two different drop zones for
+ * one block.
+ */
+
+import type { SectionBackground, Space } from "@asheeui/core";
+import { BACKGROUND_OPTIONS, SPACING_OPTIONS, selectField } from "../fields";
+import type { AsheeBlockSpec } from "../types";
+
+/**
+ * Ratio options a two-column block offers.
+ */
+export const COLUMN_RATIO_OPTIONS = ["50/50", "33/67", "67/33"] as const;
+
+/**
+ * Ratio of a two-column arrangement, from the `lg` breakpoint upwards.
+ */
+export type ColumnRatio = (typeof COLUMN_RATIO_OPTIONS)[number];
+
+/**
+ * The band options a section-level block carries, which is every part of its value that
+ * is not a drop zone.
+ */
+export type SectionBandProps = {
+  /** Vertical padding of the band. */
+  spacing?: Space;
+
+  /** Background treatment of the band. */
+  background?: SectionBackground;
+};
+
+/**
+ * A band with its own vertical rhythm and background.
+ */
+export const SECTION_SPEC: AsheeBlockSpec<SectionBandProps> = {
+  label: "Section",
+  fields: {
+    spacing: selectField("Vertical spacing", SPACING_OPTIONS),
+    background: selectField("Background", BACKGROUND_OPTIONS),
+    content: { type: "slot", label: "Content" },
+  },
+  defaultProps: { spacing: "lg", background: "none" },
+};
+
+/**
+ * Everything of the two-column block that is not a drop zone.
+ */
+export type ColumnsBandProps = SectionBandProps & {
+  /** Ratio of the two columns from the `lg` breakpoint upwards. */
+  ratio?: ColumnRatio;
+};
+
+/**
+ * Two columns that stack on a narrow screen.
+ */
+export const COLUMNS_SPEC: AsheeBlockSpec<ColumnsBandProps> = {
+  label: "Columns",
+  fields: {
+    ratio: selectField("Column ratio", COLUMN_RATIO_OPTIONS),
+    spacing: selectField("Vertical spacing", SPACING_OPTIONS),
+    start: { type: "slot", label: "First column" },
+    end: { type: "slot", label: "Second column" },
+  },
+  defaultProps: { ratio: "50/50", spacing: "lg" },
+};
+
+/**
+ * The grid columns each ratio resolves to, on the web.
+ * The strings are complete literals, so Tailwind emits them.
+ */
+export const COLUMN_RATIO_CLASS: Record<ColumnRatio, string> = {
+  "50/50": "lg:grid-cols-2",
+  "33/67": "lg:grid-cols-[1fr_2fr]",
+  "67/33": "lg:grid-cols-[2fr_1fr]",
+};

package/src/shared/blocks/navigation.ts

@@ -0,0 +1,168 @@
+/**
+ * The navigation blocks, stated once for both renderers.
+ *
+ * A builder usually owns the header and the footer of a site once, at the page level,
+ * so these blocks expose the framework's bar and footer with the navigation as data:
+ * link lists a non-developer can edit, and no application state. The link lists are
+ * described here, once, so the two platforms offer the same editor for them.
+ */
+
+import {
+  ACTION_FIELDS,
+  LINK_ITEM_FIELDS,
+  selectField,
+  textareaField,
+  textField,
+} from "../fields";
+import type { AsheeArrayField, AsheeBlockSpec } from "../types";
+
+/**
+ * One navigation link.
+ */
+export type LinkItemProps = {
+  /** Visible name of the link. */
+  label: string;
+
+  /** Destination of the link. */
+  href: string;
+};
+
+/**
+ * One column of footer navigation.
+ */
+export type FooterGroupProps = {
+  /** Title of the column. */
+  title: string;
+
+  /** The links in the column. */
+  links: LinkItemProps[];
+};
+
+/**
+ * The links of one column.
+ */
+const COLUMN_LINK_ARRAY: AsheeArrayField<LinkItemProps> = {
+  type: "array",
+  label: "Links",
+  arrayFields: LINK_ITEM_FIELDS,
+  defaultItemProps: { label: "New link", href: "/" },
+  getItemSummary: (item) => item.label ?? "Link",
+};
+
+/**
+ * The link list of the bar.
+ */
+const NAVBAR_LINK_ARRAY: AsheeArrayField<LinkItemProps> = COLUMN_LINK_ARRAY;
+
+/**
+ * The columns of the footer.
+ */
+const FOOTER_GROUP_ARRAY: AsheeArrayField<FooterGroupProps> = {
+  type: "array",
+  label: "Columns",
+  arrayFields: {
+    title: textField("Column title"),
+    links: COLUMN_LINK_ARRAY,
+  },
+  defaultItemProps: { title: "New column", links: [] },
+  getItemSummary: (item) => item.title ?? "Column",
+};
+
+/**
+ * The props of the navigation bar block.
+ */
+export type NavbarBlockProps = {
+  /** Brand content, typically the product name. */
+  brand?: string;
+
+  /** Destination of the brand. */
+  brandHref?: string;
+
+  /** Where the links sit in the bar, from the `md` breakpoint upwards. */
+  align?: "start" | "center" | "end";
+
+  /** The navigation links. */
+  links?: LinkItemProps[];
+
+  /** The emphasised action of the bar. */
+  primaryAction?: {
+    label: string;
+    href: string;
+    variant: string;
+  };
+
+  /** The supporting action of the bar. */
+  secondaryAction?: {
+    label: string;
+    href: string;
+    variant: string;
+  };
+};
+
+/**
+ * The navigation bar of a page.
+ */
+export const NAVBAR_SPEC: AsheeBlockSpec<NavbarBlockProps> = {
+  label: "Navbar",
+  fields: {
+    brand: textField("Brand", "Ashee"),
+    brandHref: textField("Brand link", "/"),
+    align: selectField("Link alignment", ["start", "center", "end"] as const),
+    links: NAVBAR_LINK_ARRAY,
+    primaryAction: ACTION_FIELDS,
+    secondaryAction: ACTION_FIELDS,
+  },
+  defaultProps: {
+    brand: "Ashee",
+    brandHref: "/",
+    align: "center",
+    links: [
+      { label: "Product", href: "/product" },
+      { label: "Pricing", href: "/pricing" },
+    ],
+  },
+};
+
+/**
+ * The props of the footer block.
+ */
+export type FooterBlockProps = {
+  /** Brand content. */
+  brand?: string;
+
+  /** Short description under the brand. */
+  description?: string;
+
+  /** The navigation columns. */
+  groups?: FooterGroupProps[];
+
+  /** The copyright line. */
+  copyright?: string;
+};
+
+/**
+ * The footer of a page.
+ */
+export const FOOTER_SPEC: AsheeBlockSpec<FooterBlockProps> = {
+  label: "Footer",
+  fields: {
+    brand: textField("Brand", "Ashee"),
+    description: textareaField("Description"),
+    groups: FOOTER_GROUP_ARRAY,
+    copyright: textField("Copyright", "Ashee Softworks"),
+  },
+  defaultProps: {
+    brand: "Ashee",
+    description: "Campaign messaging for growing teams.",
+    groups: [
+      {
+        title: "Product",
+        links: [
+          { label: "Campaigns", href: "/campaigns" },
+          { label: "Pricing", href: "/pricing" },
+        ],
+      },
+    ],
+    copyright: "Ashee Softworks",
+  },
+};

package/src/shared/blocks/sections.ts

@@ -0,0 +1,322 @@
+/**
+ * The marketing section blocks, stated once for both renderers.
+ *
+ * These are the sections a page is assembled from: a hero, a feature grid, a
+ * testimonial wall, a pricing card and a closing call to action. What is stated here is
+ * the editor's half of each — its label, its fields and its starting value — so the two
+ * platforms offer one editor and one default, and differ only in how each draws the
+ * component it names.
+ */
+
+import type { ContainerSize, CtaPanel, SectionBackground } from "@asheeui/core";
+import type { BuilderAction } from "../adapters";
+import {
+  ACTION_FIELDS,
+  ALIGNMENT_OPTIONS,
+  BACKGROUND_OPTIONS,
+  COLUMNS_OPTIONS,
+  CONTAINER_SIZE_OPTIONS,
+  FEATURE_ITEM_FIELD,
+  PRICING_FEATURE_FIELD,
+  selectField,
+  TESTIMONIAL_ITEM_FIELD,
+  textareaField,
+  textField,
+} from "../fields";
+import type { AsheeBlockSpec } from "../types";
+
+/**
+ * The props of the hero block.
+ */
+export type HeroBlockProps = {
+  /** Short label above the headline. */
+  eyebrow?: string;
+
+  /** The headline. */
+  title?: string;
+
+  /** Supporting sentence under the headline. */
+  description?: string;
+
+  /** The emphasised action. */
+  primaryAction?: BuilderAction;
+
+  /** The supporting action. */
+  secondaryAction?: BuilderAction;
+
+  /** Alignment of the text column. */
+  align?: "start" | "center";
+
+  /** Background treatment of the band. */
+  background?: SectionBackground;
+
+  /** Maximum content width of the band. */
+  contentWidth?: ContainerSize;
+};
+
+/**
+ * The leading statement of a page.
+ */
+export const HERO_SPEC: AsheeBlockSpec<HeroBlockProps> = {
+  label: "Hero",
+  fields: {
+    eyebrow: textField("Eyebrow"),
+    title: textField("Headline", "Run your campaigns from one place"),
+    description: textareaField("Description"),
+    primaryAction: ACTION_FIELDS,
+    secondaryAction: ACTION_FIELDS,
+    align: selectField("Alignment", ALIGNMENT_OPTIONS),
+    background: selectField("Background", BACKGROUND_OPTIONS),
+    contentWidth: selectField("Content width", CONTAINER_SIZE_OPTIONS),
+  },
+  defaultProps: {
+    eyebrow: "",
+    title: "Run your campaigns from one place",
+    description: "Messages, templates and results, without switching tools.",
+    primaryAction: { label: "Start free", href: "/signup", variant: "solid" },
+    secondaryAction: {
+      label: "Book a demo",
+      href: "/demo",
+      variant: "bordered",
+    },
+    align: "start",
+    background: "none",
+    contentWidth: "lg",
+  },
+};
+
+/**
+ * The props of the call-to-action block.
+ */
+export type CtaBlockProps = {
+  /** Short label above the headline. */
+  eyebrow?: string;
+
+  /** The headline of the band. */
+  title?: string;
+
+  /** Supporting sentence under the headline. */
+  description?: string;
+
+  /** The emphasised action. */
+  primaryAction?: BuilderAction;
+
+  /** The supporting action. */
+  secondaryAction?: BuilderAction;
+
+  /** Alignment of the content. */
+  align?: "start" | "center";
+
+  /** Background treatment of the band. */
+  background?: SectionBackground;
+
+  /** Panel treatment of the content. */
+  panel?: CtaPanel;
+};
+
+/**
+ * The closing call to action of a page.
+ */
+export const CTA_SPEC: AsheeBlockSpec<CtaBlockProps> = {
+  label: "Call to action",
+  fields: {
+    eyebrow: textField("Eyebrow"),
+    title: textField("Headline", "Send your first campaign today"),
+    description: textareaField("Description"),
+    primaryAction: ACTION_FIELDS,
+    secondaryAction: ACTION_FIELDS,
+    align: selectField("Alignment", ALIGNMENT_OPTIONS),
+    background: selectField("Background", BACKGROUND_OPTIONS),
+    panel: selectField("Panel", ["bordered", "muted", "plain"] as const),
+  },
+  defaultProps: {
+    eyebrow: "",
+    title: "Send your first campaign today",
+    description: "No card required, and no setup call.",
+    primaryAction: {
+      label: "Create an account",
+      href: "/signup",
+      variant: "solid",
+    },
+    align: "center",
+    background: "none",
+    panel: "bordered",
+  },
+};
+
+/**
+ * The props of the feature grid block.
+ */
+export type FeatureGridBlockProps = {
+  /** Short label above the heading. */
+  eyebrow?: string;
+
+  /** Heading of the band. */
+  title?: string;
+
+  /** Supporting sentence under the heading. */
+  description?: string;
+
+  /** The features to show. */
+  items?: Array<{ title: string; description: string }>;
+
+  /** Columns from the `md` breakpoint upwards. */
+  columnsMd?: string;
+
+  /** Columns from the `lg` breakpoint upwards. */
+  columnsLg?: string;
+
+  /** Alignment of the heading. */
+  align?: "start" | "center";
+
+  /** Background treatment of the band. */
+  background?: SectionBackground;
+};
+
+/**
+ * A band of features laid out in a responsive grid.
+ */
+export const FEATURE_GRID_SPEC: AsheeBlockSpec<FeatureGridBlockProps> = {
+  label: "Feature grid",
+  fields: {
+    eyebrow: textField("Eyebrow"),
+    title: textField("Heading", "Everything the campaign needs"),
+    description: textareaField("Description"),
+    items: FEATURE_ITEM_FIELD,
+    columnsMd: selectField("Columns on tablet", COLUMNS_OPTIONS),
+    columnsLg: selectField("Columns on desktop", COLUMNS_OPTIONS),
+    align: selectField("Heading alignment", ALIGNMENT_OPTIONS),
+    background: selectField("Background", BACKGROUND_OPTIONS),
+  },
+  defaultProps: {
+    eyebrow: "",
+    title: "Everything the campaign needs",
+    description: "",
+    items: [
+      { title: "Templates", description: "Reusable messages." },
+      { title: "Scheduling", description: "Send at the right time." },
+      { title: "Reporting", description: "See what landed." },
+    ],
+    columnsMd: "2",
+    columnsLg: "3",
+    align: "center",
+    background: "none",
+  },
+};
+
+/**
+ * The props of the testimonials block.
+ */
+export type TestimonialsBlockProps = {
+  /** Short label above the heading. */
+  eyebrow?: string;
+
+  /** Heading of the band. */
+  title?: string;
+
+  /** Supporting sentence under the heading. */
+  description?: string;
+
+  /** The quotes to show. */
+  items?: Array<{ quote: string; name: string; role: string }>;
+
+  /** Alignment of the heading. */
+  align?: "start" | "center";
+};
+
+/**
+ * A band of attributed customer quotes.
+ */
+export const TESTIMONIALS_SPEC: AsheeBlockSpec<TestimonialsBlockProps> = {
+  label: "Testimonials",
+  fields: {
+    eyebrow: textField("Eyebrow"),
+    title: textField("Heading", "Teams send more with Ashee"),
+    description: textareaField("Description"),
+    items: TESTIMONIAL_ITEM_FIELD,
+    align: selectField("Heading alignment", ALIGNMENT_OPTIONS),
+  },
+  defaultProps: {
+    eyebrow: "",
+    title: "Teams send more with Ashee",
+    description: "",
+    items: [
+      {
+        quote: "We cut campaign setup from hours to minutes.",
+        name: "Ama Boateng",
+        role: "Head of Growth, Kora Retail",
+      },
+    ],
+    align: "center",
+  },
+};
+
+/**
+ * The props of the pricing card block.
+ */
+export type PricingCardBlockProps = {
+  /** Name of the plan. */
+  name?: string;
+
+  /** The amount. */
+  price?: string;
+
+  /** Billing period shown beside the amount. */
+  period?: string;
+
+  /** One sentence about the plan. */
+  description?: string;
+
+  /** Short label above the plan name. */
+  badge?: string;
+
+  /** The plan's feature lines. */
+  features?: Array<{ label: string; included: boolean }>;
+
+  /** Whether the plan is the recommended one. */
+  highlighted?: boolean;
+
+  /** The emphasised action. */
+  primaryAction?: BuilderAction;
+};
+
+/**
+ * One plan in a pricing table.
+ */
+export const PRICING_CARD_SPEC: AsheeBlockSpec<PricingCardBlockProps> = {
+  label: "Pricing card",
+  fields: {
+    badge: textField("Badge", "Most popular"),
+    name: textField("Plan", "Growth"),
+    price: textField("Price", "$29"),
+    period: textField("Period", "/month"),
+    description: textareaField("Description"),
+    features: PRICING_FEATURE_FIELD,
+    highlighted: {
+      type: "radio",
+      label: "Recommended plan",
+      options: [
+        { label: "Yes", value: true },
+        { label: "No", value: false },
+      ],
+    },
+    primaryAction: ACTION_FIELDS,
+  },
+  defaultProps: {
+    badge: "",
+    name: "Growth",
+    price: "$29",
+    period: "/month",
+    description: "For teams sending their first campaigns.",
+    features: [
+      { label: "10,000 messages", included: true },
+      { label: "Audit log", included: false },
+    ],
+    highlighted: false,
+    primaryAction: {
+      label: "Choose Growth",
+      href: "/signup",
+      variant: "solid",
+    },
+  },
+};

package/src/shared/blocks/utility.ts

@@ -0,0 +1,65 @@
+/**
+ * The utility blocks, stated once for both renderers.
+ *
+ * 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. Its fields are stated here so the two platforms offer
+ * the same editor for it.
+ */
+
+import type { EmptyStateType } from "@asheeui/core";
+import type { BuilderAction } from "../adapters";
+import {
+  ACTION_FIELDS,
+  selectField,
+  textareaField,
+  textField,
+} from "../fields";
+import type { AsheeBlockSpec } from "../types";
+
+/**
+ * The props of the empty state block.
+ */
+export type EmptyStateBlockProps = {
+  /** What the region is. */
+  title?: string;
+
+  /** What the reader can do about it. */
+  description?: string;
+
+  /** Tone of the state. */
+  type?: EmptyStateType;
+
+  /** Whether the state is drawn as a panel. */
+  panel?: boolean;
+
+  /** The emphasised action. */
+  primaryAction?: BuilderAction;
+};
+
+/**
+ * A region with nothing in it.
+ */
+export const EMPTY_STATE_SPEC: AsheeBlockSpec<EmptyStateBlockProps> = {
+  label: "Empty state",
+  fields: {
+    title: textField("Heading", "Nothing here yet"),
+    description: textareaField("Description"),
+    type: selectField("Tone", ["info", "success", "warning", "error"] as const),
+    panel: {
+      type: "radio",
+      label: "Panel",
+      options: [
+        { label: "Yes", value: true },
+        { label: "No", value: false },
+      ],
+    },
+    primaryAction: ACTION_FIELDS,
+  },
+  defaultProps: {
+    title: "Nothing here yet",
+    description: "Create the first item to see it here.",
+    type: "info",
+    panel: true,
+  },
+};