API reference

The item model — AnyWidgetItem, WidgetRegistry, WidgetProblem, WidgetMeta, KnownWidgetTypes, defineWidgets, validateItems, ERROR_MESSAGES, VALIDATION_MESSAGES — comes from @evanion/widget and is re-exported here. The specifier does not change and neither does the install: this package pins the core exactly and depends on it. The widget core’s API reference is where each of those is written down. What follows Widgets.astro is what those names mean on this side.

Widgets.astro

---
import Widgets from '@evanion/astro-widget/components/Widgets.astro';
---
 
<Widgets items={items} registry={registry} ctx={ctx} chrome={{ item: Section }} />

Published as source, not as compiled output: an .astro module has to be compiled by Astro’s own Vite plugin, which runs in the consuming project.

What each widget receives:

<Component {...props} id={id} ctx={ctx} children={children} />

The chrome, when there is one, receives type, id and meta, and wraps that element in its slot. It never receives props: a widget’s data is the widget’s business, and placement is the chrome’s.

A non-array items renders nothing and warns. A type that is not an own key of the registry is skipped, with a dev-only console.warn naming the type and the id.

There is no chrome.wrapper. The region’s container is whatever element you put <Widgets> inside, and a wrapper the library supplied would be markup you did not ask for.

defineWidgets(registry)

Re-exported unchanged from @evanion/widget, which is where its entry is. It returns the registry it was handed and keeps the keys literal.

Only the keys are read, so a registry of .astro modules and a plain list of names do the same job here.

validateItems(items, known, required?)

Re-exported unchanged from @evanion/widget, which carries the signature and every message it returns.

Validation is where to run it from in an Astro project, and why it matters more here than it does in React: an .astro component exposes no prop types to infer from, so this call is the only check a widget’s props get.

Types

AnyWidgetItem

The item shape, from @evanion/widget, which carries the interface and teaches the four fields on Getting started.

React’s WidgetItem<C> is the checked counterpart, inferred from a component map. There is no Astro equivalent, because an .astro component exposes no prop types to infer from, so validateItems is the check on this side.

WidgetRegistry

From @evanion/widget, and its entry has the type. Here the values stay unknown. An .astro module’s default export is an AstroComponentFactory, which carries no prop types — the props of a .astro file live in its frontmatter Props interface and are not reachable from the factory’s type. So a narrower value type would buy nothing, which is why validateItems exists.

WidgetProblem

One line of the report validateItems returns, from @evanion/widget; its entry has the fields and What it reports walks them.

id is a usable handle now that every item has one, which is what tells apart two problems reporting the same index at different depths.