Blocks reference

<!-- Generated by pnpm docs:build (docs-reference) from packages/blocks/src/config.tsx and meta.ts. Do not edit by hand; edit the source and run the command. -->

Every block of @spillway-cms/blocks with its editor fields, options and default props. Blocks are Puck components: the admin shows the fields in the right-hand panel and the server renders the props with @puckeditor/core/rsc. Props marked resolved are attached by the server at render time and never stored. The narrative guide is blocks.md.

Summary

Layout

Columns

Two to four side-by-side columns, each a slot that holds other blocks. Stacks on small screens.

AI hint: Use to place blocks side by side, for example an Image next to a Text. Each entry in "columns" has a "content" array of child blocks. Keep to 2 or 3 columns for readability.

Spacer

Vertical space (s, m, l, xl).

AI hint: Use sparingly to add breathing room between sections. Blocks already have padding.

Divider

A horizontal rule.

AI hint: Use to separate unrelated sections. Do not place directly after a Spacer.

Content

Heading

A standalone heading (h1 to h4) with alignment.

AI hint: Use to start a section. Prefer h2 for sections and h3 for sub-sections; the Hero already provides the h1. Keep headings short and specific.

Text

Body copy. Plain text split into paragraphs on blank lines, or raw HTML.

AI hint: Use for prose. Prefer format "paragraphs" and separate paragraphs with a blank line. Use "lead" size for a single intro paragraph. Only use "html" when markup such as lists or links is required.

Image

A single image with required alt text, optional caption and width (normal, wide, full).

AI hint: Use only with a real image URL from the media library (/media/...). Always write descriptive alt text; use an empty alt only for purely decorative images.

Embed

Raw embed HTML (for example a YouTube iframe) in a responsive 16:9 frame.

AI hint: Use only when the user provides embed code or a known embeddable URL. Put the full iframe markup in "html". Never invent video IDs.

Button

A single button with alignment; its emphasis (primary, secondary or a text link) comes from its style.

AI hint: Use for a standalone link styled as a button. Label is a verb phrase; href is a site path or full URL.

Marketing

Hero

Large opening section with an eyebrow, title, subtitle, up to two buttons and an optional background image.

AI hint: Use once, at the top of a landing page. Title under 10 words, subtitle one or two sentences. Primary button is the main action; secondary is optional. Leave backgroundImage empty unless a real image URL is known.

CallToAction

Label in the editor: Call to action.

A title, short text and one button; its style (a colored band, a bordered card or one the site defines) comes from Brand → Styles.

AI hint: Use near the end of a page to ask for one action. Title under 8 words, text one sentence, a specific button label such as "Book a demo" rather than "Submit".

Cards

A grid of cards with title, text, optional link and image, in 2 to 4 columns.

AI hint: Use for features, benefits, services or a list of related pages. Three cards with parallel phrasing read best. Leave href empty when there is no target page.

Collection

A saved query (collection) of entities rendered as cards, a list or a grid, optionally with visitor filters (keyword, taxonomy, select, date range) and a pager; items are filled in by the server at render time.

AI hint: Use for "latest posts", "case studies" or any list that should update itself. Set collectionId to the key of an existing collection (ask or leave empty if unknown); never invent items, the server supplies them.

Calendar

A month grid or date list of the event occurrences in a collection, with a link to its iCal feed; filled in by the server at render time.

AI hint: Use on an events page. Set collectionId to the key of an existing collection of a type with a daterange field (ask or leave empty if unknown); view "month" for a grid, "list" for upcoming dates.

Form

A lead-capture form defined under Forms in the admin, referenced by key. Fields, labels and the success message come from the definition.

AI hint: Use for contact, demo or newsletter forms. Set formKey to the key of an existing form (leave it empty if none is known); never invent fields here. Add a short title and a one-sentence intro.

Shared

Label in the editor: Shared block.

A block saved in the component library (Shared blocks in the admin), referenced by key and rendered by the server; edit it once, update everywhere.

AI hint: Use only when the user names an existing shared block key (a promo, a contact card). Never invent keys; leave sharedKey empty if none is known.

Personalize

Two slots, Default and Variant; visitors who match an audience (Audiences in the admin) see the variant. The server decides per visitor after the page loads, so pages stay cached.

AI hint: Use only when the user names an existing audience key. Put the content for everyone in "default" and the audience version in "variant"; keep both the same shape (a Hero in each, for example). Never invent audience keys.

Experiment

An A/B test: slots a (control), b and optional c; visitors of a running experiment (Experiments in the admin) are assigned a variant by weight and the results screen reports conversions per variant.

AI hint: Use only when the user names an existing experiment key. Put the current content in "a" and the challenger in "b"; leave "c" empty unless asked. Never invent experiment keys.

RegistryBrowse

Label in the editor: Registry browse.

Search and browse the package registry (modules, themes, kits): a GET search form, kind tabs, a sort, result cards with badges and a pager; filled in by the registry service from the page URL. Placeholder on instances that do not host the registry.

AI hint: Use once on the /registry page of the project site. Keep the defaults; set kind to "theme" or "kit" only for a page dedicated to that kind. Needs no other props; the server supplies the results.

RegistryPackage

Label in the editor: Registry package.

The detail page of one registry package, resolved from the last segment of the page path (/registry/<name>): header with badges, install command with a copy button, publisher and links, capability sheet, compatibility, versions, advisories, deprecation notice, README, changelog and a "For agents" section linking manifest.json.

AI hint: Use once on the /registry/<name> catch-all page of the project site. The package comes from the URL; there is nothing to fill in besides the section toggles.

RegistryStats

Label in the editor: Registry stats.

The registry totals: packages by kind, publishers and downloads, as a row of figures.

AI hint: Use on the registry landing or home page of the project site to show how much is published. Leave the title empty when a Heading precedes it.

ThemeGallery

Label in the editor: Theme gallery.

The theme directory: registry kits of kind "theme" as cards with a screenshot, description, publisher and Preview and Details links.

AI hint: Use on a /themes page of the project site. Set limit to the number of cards wanted; the server supplies the themes.

PublisherProfile

Label in the editor: Publisher profile.

A publisher’s public profile (handle, name, verified badge, bio, website, maintainers) and their packages; the handle comes from the page path (/registry/publishers/<handle>) or the handle prop.

AI hint: Use once on the /registry/publishers/<handle> catch-all page of the project site, with handle left empty. Set handle only for a page about one known publisher.

OrgProfile

Label in the editor: Organization profile.

An organization’s public profile (handle, name, verified badge, website, members with their roles, the namespaces it owns) and the packages published under those namespaces; the handle comes from the page path (/registry/orgs/<handle>) or the handle prop.

AI hint: Use once on the /registry/orgs/<handle> catch-all page of the project site, with handle left empty. Set handle only for a page about one known organization.

DocsFeedback

Label in the editor: Docs feedback.

"Was this page helpful?" with Yes and No buttons and an optional comment, posted to a form (docs_feedback by default) with the page path and the documented version as hidden fields; works without JavaScript and asks for no personal data.

AI hint: Put it last on a documentation page. Keep formKey at docs_feedback unless the site defines another feedback form; the docs kit creates that form and places this block on every doc page.

StatusBoard

Label in the editor: Status board.

A list of Spillway instances with their state (up, degraded or down), version, when each was last checked and a 90-day uptime bar; the server fetches every instance’s /status.json (3 s timeout, cached for a minute) and reads the history the probe step records every five minutes.

AI hint: Use on a /status page of the project site. Fill instances with a name and the instance’s public URL (https://...); never invent URLs. Keep showUptime on unless asked.

Modules

ModuleBlock

Label in the editor: Module block.

A block an installed module provides (module name, block key and the block’s own props); rendered by the module on the server, with a placeholder when the module is disabled or missing.

AI hint: Only use with a module and block key that GET /api/builder/config lists; never invent one. Fill props from that block’s field definitions.

Spillway 0.1.0 · Edit this page on GitHub