Components

Components are per site. A site ships the renderers its design uses and nothing else; the platform contains no designs. A renderer is an Astro component that receives a stored component’s props and emits anchored HTML.

The reference component

The template’s Hero is the shape to copy:

---
import { sanitizeHtml } from "@sp-stage/sdk";
import { stageAttrs, stagePath } from "../../lib/stage-anchors";
import Media from "../global/Media.astro";

interface Props {
  title?: string;
  body?: string;
  image?: string;        // CDN image, external URL, or ""
  imageVideo?: string;   // raw mux:{id}, video URL, or ""  (paired with image)
  index?: number;
  _stageId?: string;
  _stageType?: string;
}
const { title, body, image, imageVideo, index = 0, _stageId, _stageType } = Astro.props;
---

<section class="…" id={`hero-${index}`} {...stageAttrs(_stageId, _stageType)}>
  {title && <h1 class="…" {...stagePath("props.title")}>{title}</h1>}
  {body && <div class="…" set:html={sanitizeHtml(body)} {...stagePath("props.body", { rich: true })} />}
  <Media image={image} video={imageVideo} path="props.image" alt="" class="…" sizes="…" />
</section>

Four things make it work:

Typed props for every editable field, plus _stageId, _stageType and index, which the page passes in.
Anchors: stageAttrs on the wrapper, stagePath on each field, { rich: true } for HTML.
Tokens-first styling: utilities against the site’s design tokens, no scoped styles. Re-skinning is a token change.
Media through <Media>, never a hand-written <img>. The slot renders even when empty so it stays a clickable picker in the admin.

The registry

lib/components.ts maps a stored component type to its renderer. The page templates look each component up here; unknown types render nothing.

const registry = {
  hero: Hero,
  "article-list": ArticleList,
  prose: Prose,
  "question-short-text": ShortText,
  // …
};

Keys are typed against the SDK’s component type union, so a key that is not a current type is a compile error rather than an orphaned string. Site globals such as the header and footer render from the base layout and stay out of the registry.

What is editable with no schema

Anything anchored. A field with data-e-path is editable the moment it renders. Lists render their items with stageArray on the container and stageField on the item fields, and each item is editable in place. Adding, reordering and removing items needs a schema.

Media slots

An image slot is a pair of sibling props: an image key and a video key (default ${imageKey}Video). Exactly one is set. The admin’s combined picker fills one and clears the other, so the renderer never reconciles both. <Media> decides the element:

video set: <video autoplay muted loop playsinline preload="metadata"> with a poster
else: <img> with a CDN srcset and focal-point object-position, or a transparent placeholder when empty

Props reach renderers raw; <Media> expands mux: ids at the last moment through the SDK, so the same stored value works in public and in the admin. Converting an existing slot is a markup-only change. See Media.

Shared content

A field can declare that its canonical value lives on another row: a component prop on another page, a field on an article (row-level or inside its body), or a path into a global. It is routing, not new storage.

<span {...stageRef({ kind: "article", key: mission.id, path: "client_specific.status" })}>{status}</span>
<p    {...stageRef({ kind: "page", key: "pricing", id: cardsId, path: "props.cards.0.price" })}>{price}</p>
<h3   {...stageRef({ kind: "global", key: "footer", path: "headline" })}>{headline}</h3>

kind is page, article or global. key is the page slug, the article id, or the global key. id is the component id inside the row’s stream, required for pages, omitted for row-level article fields and globals. In an editing session every render of the same ref repaints live, and on publish one versioned write goes to each home row through that row’s own save path. Current limits: page sessions only, single fields not whole lists, live repaint within the current page.

Stateful components

A carousel or tabs stays in its live state while editing. It stamps data-e-current on the active item so the settings cog and inline edits act on it, and it handles the custom events the edit notch dispatches to page through items.

Start

Making content editable

Making content addable

Media

Next.js

Analytics SDK

Platform reference

The reference component

The registry

What is editable with no schema

Media slots

Shared content

Stateful components

Next steps

Page schemas

Media

​The reference component

​The registry

​What is editable with no schema

​Media slots

​Shared content

​Stateful components

​Next steps

Page schemas

Media

The reference component

The registry

What is editable with no schema

Media slots

Shared content

Stateful components

Next steps