@evanion/widget 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Mikael Pettersson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+[![npm version](https://img.shields.io/npm/v/@evanion/widget)](https://www.npmjs.com/package/@evanion/widget)
+[![npm downloads](https://img.shields.io/npm/dm/@evanion/widget)](https://www.npmjs.com/package/@evanion/widget)
+[![CI](https://github.com/Evanion/libraries/actions/workflows/ci.yml/badge.svg)](https://github.com/Evanion/libraries/actions/workflows/ci.yml)
+
+# Widget
+
+The framework-free half of a widget region: the item shape, the registry, and
+the validator. It renders nothing. A renderer is one package per framework, and
+each of them depends on this one:
+
+| Package                 | Renders                      |
+| ----------------------- | ---------------------------- |
+| `@evanion/react-widget` | React, Server Components too |
+| `@evanion/astro-widget` | Astro, at build time         |
+
+Install a renderer, not this. Every type below is re-exported from each of them,
+so a consumer who never names this package never installs it by hand.
+
+## What a widget region is
+
+A page described as data: a list of items, each naming a component by `type` and
+carrying the props it takes. The renderer resolves the type against a registry
+and renders it.
+
+```ts
+import { defineWidgets, validateItems } from '@evanion/widget';
+import type { AnyWidgetItem } from '@evanion/widget';
+
+const registry = defineWidgets({ hero: Hero, prose: Prose });
+
+const items: AnyWidgetItem[] = [
+  {
+    id: 'top',
+    type: 'hero',
+    props: { heading: 'Hello' },
+    meta: { width: 'full' },
+  },
+  { id: 'about', type: 'prose', props: { body: '…' } },
+];
+
+validateItems(items, registry, { hero: ['heading'] }); // -> []
+```
+
+The same array renders through every adapter and produces the same sequence of
+widgets.
+
+## Why this package exists
+
+Two renderers held two copies of these rules under two vocabularies, and the
+same prototype-chain bug had to be fixed in both. A third renderer would have
+been a third copy. The rules are the part that does not differ between
+frameworks; resolving a type to a component and putting children somewhere is
+the part that does.
+
+Nothing here imports a framework, so it also runs where no renderer does: a
+webhook that checks a CMS payload on its way in, a build script, a test.
+
+## Installation
+
+```bash
+npm install @evanion/widget
+```
+
+Or with yarn:
+
+```bash
+yarn add @evanion/widget
+```
+
+Or with pnpm:
+
+```bash
+pnpm add @evanion/widget
+```
+
+## The item
+
+```ts
+interface AnyWidgetItem<Type extends string = string, Props = object> {
+  id: string;
+  type: Type;
+  props: Props;
+  meta?: Record<string, unknown>;
+  children?: AnyWidgetItem[];
+}
+```
+
+`id` is required. It is the key a renderer lists the item under, the identity in
+a warning about a stale type, and what the duplicate-sibling check is about. A
+CMS with no per-section id has to supply one; an index-derived value is fine as
+long as it is stable across renders.
+
+`props` is a named field rather than "every key the renderer does not claim".
+The renderer's own fields would otherwise be reserved words in the CMS's
+vocabulary, and adding one later would take a prop away from every payload
+already written.
+
+It is required, and `validateItems` reports an item without it. A widget's data
+lives under that key and nowhere else, so an item missing it is one whose props
+the payload put somewhere no renderer reads — which is what a payload written
+against a flat item shape looks like, and what a renderer would draw as an empty
+widget with nothing logged.
+
+`meta` is placement: which column, what span, whether a rule sits above it. It
+goes to the region's chrome and never into the widget's own props, because where
+a widget sits is not something the widget should know.
+
+`children` is nested items. What a renderer does with them is the runtime's
+business — React renders them as the component's `children`, while an Astro
+component receives child content through `<slot />` and is handed them as data
+to open its own region over.
+
+## `defineWidgets(registry)`
+
+Returns the registry unchanged, typed as the literal object passed in.
+
+```ts
+const registry = defineWidgets({ hero: Hero, text: Text });
+//    ^? { hero: typeof Hero; text: typeof Text }
+```
+
+Annotating the same object as `WidgetRegistry` would widen its keys to `string`,
+and the key union is what an editor completes on and what a `required` map is
+checked against.
+
+## `validateItems(items, known, required?)`
+
+Checks a list against the set of known types and returns `WidgetProblem[]`.
+Problems rather than an exception, and accumulated rather than short-circuited,
+so a caller can print all of them at once.
+
+```ts
+validateItems([{ id: 'a', type: 'nope', props: {} }], ['news']);
+// -> [{ index: 0, id: 'a', type: 'nope', message: 'unknown widget type' }]
+```
+
+`known` is a registry or a plain list of names, so a CI script can validate a
+payload without importing components it will never render.
+
+`required` maps a type to the props that must be present and non-blank, where
+blank means `undefined`, `null` or whitespace only — which is what a CMS text
+field that was opened and left empty arrives as.
+
+```ts
+validateItems([{ id: 'a', type: 'hero', props: {} }], registry, {
+  hero: ['heading'],
+});
+// -> [{ index: 0, id: 'a', type: 'hero', message: 'missing field heading' }]
+```
+
+No renderer calls this. Each one stays defensive — an item it cannot render is
+skipped and warned about — and validation is the loud gate you run at ingestion
+or build time.
+
+A type is looked up as an own key of the registry, so a CMS item typed
+`constructor`, `toString` or `__proto__` is unknown rather than resolving to
+something off `Object.prototype`.
+
+## Exports
+
+`defineWidgets`, `validateItems`, `warnOnce`, `resetWarnings`,
+`ERROR_MESSAGES`, `VALIDATION_MESSAGES`, and the types `AnyWidgetItem`,
+`WidgetRegistry`, `WidgetMeta`, `WidgetProblem`, `KnownWidgetTypes`.
+
+`warnOnce` and `resetWarnings` are there for the adapters, which are separate
+packages and cannot reach a module this one does not publish. A consumer has no
+reason to call either.
+
+## License
+
+MIT

package/dist/constants.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Messages an adapter's renderer passes to {@link warnOnce}.
+ *
+ * Each one names the offending item's `id` and `type`, which is what lets
+ * `warnOnce` key on the message text and still report a second bad item
+ * separately.
+ *
+ * They live here rather than in each adapter so that a region rendered through
+ * React and the same region rendered through Astro report a stale CMS type in
+ * the same words.
+ */
+export declare const ERROR_MESSAGES: {
+    readonly UNKNOWN_WIDGET: (type: string, id: string) => string;
+    readonly UNKNOWN: "unknown";
+    readonly MALFORMED_ITEMS: "Malformed `items` prop: expected an array of widget items. Skipping render.";
+    readonly MALFORMED_ITEM: (id: string | undefined, type: unknown) => string;
+    readonly MALFORMED_CHILDREN: (id: string) => string;
+};
+/**
+ * Messages reported by {@link validateItems}.
+ *
+ * Exported so a caller can group or translate problems without matching on
+ * prose, and so the tests assert against the same strings the library emits.
+ */
+export declare const VALIDATION_MESSAGES: {
+    readonly NOT_A_LIST: "items is not a list";
+    readonly NOT_AN_OBJECT: "item is not an object";
+    readonly INVALID_ID: "item id is not a string";
+    readonly INVALID_TYPE: "item type is not a string";
+    readonly UNKNOWN_TYPE: "unknown widget type";
+    readonly INVALID_PROPS: "props is not an object";
+    readonly INVALID_CHILDREN: "children is not a list";
+    readonly DUPLICATE_ID: "duplicate sibling id";
+    /**
+     * A field the caller's `required` map demands is absent or blank.
+     *
+     * A function rather than a constant because the field name is the whole of
+     * the report: a CMS editor reads "missing field heading" and knows which box
+     * to fill.
+     */
+    readonly MISSING_FIELD: (field: string) => string;
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc;oCACF,MAAM,MAAM,MAAM;;;kCAKpB,MAAM,GAAG,SAAS,QAAQ,OAAO;sCAE7B,MAAM;CAEvB,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;IAS9B;;;;;;OAMG;oCACoB,MAAM;CACrB,CAAC"}

package/dist/constants.js

@@ -0,0 +1,42 @@
+/**
+ * Messages an adapter's renderer passes to {@link warnOnce}.
+ *
+ * Each one names the offending item's `id` and `type`, which is what lets
+ * `warnOnce` key on the message text and still report a second bad item
+ * separately.
+ *
+ * They live here rather than in each adapter so that a region rendered through
+ * React and the same region rendered through Astro report a stale CMS type in
+ * the same words.
+ */
+export const ERROR_MESSAGES = {
+    UNKNOWN_WIDGET: (type, id) => `Unknown widget type "${type}" for widget ID "${id}". Skipping render.`,
+    UNKNOWN: 'unknown',
+    MALFORMED_ITEMS: 'Malformed `items` prop: expected an array of widget items. Skipping render.',
+    MALFORMED_ITEM: (id, type) => `Malformed widget item (id="${id ?? 'unknown'}", type="${typeof type === 'string' ? type : 'unknown'}"). Skipping render.`,
+    MALFORMED_CHILDREN: (id) => `Malformed \`children\` on widget item (id="${id}"): expected an array. Rendering the widget without them.`,
+};
+/**
+ * Messages reported by {@link validateItems}.
+ *
+ * Exported so a caller can group or translate problems without matching on
+ * prose, and so the tests assert against the same strings the library emits.
+ */
+export const VALIDATION_MESSAGES = {
+    NOT_A_LIST: 'items is not a list',
+    NOT_AN_OBJECT: 'item is not an object',
+    INVALID_ID: 'item id is not a string',
+    INVALID_TYPE: 'item type is not a string',
+    UNKNOWN_TYPE: 'unknown widget type',
+    INVALID_PROPS: 'props is not an object',
+    INVALID_CHILDREN: 'children is not a list',
+    DUPLICATE_ID: 'duplicate sibling id',
+    /**
+     * A field the caller's `required` map demands is absent or blank.
+     *
+     * A function rather than a constant because the field name is the whole of
+     * the report: a CMS editor reads "missing field heading" and knows which box
+     * to fill.
+     */
+    MISSING_FIELD: (field) => `missing field ${field}`,
+};

package/dist/define-widgets.d.ts

@@ -0,0 +1,23 @@
+import type { WidgetRegistry } from './types.js';
+/**
+ * Returns the registry unchanged, typed as the literal object that was passed.
+ *
+ * The generic parameter is the whole point: annotating the same object as
+ * `WidgetRegistry` widens its keys to `string`, and the key union is what an
+ * editor completes on and what a caller narrows a `required` map against.
+ *
+ * In the core rather than in an adapter because every adapter needs it, and
+ * because a React consumer assembling a registry before handing it to
+ * `createWidgets` wants it too.
+ *
+ * @example
+ * ```ts
+ * import Hero from './Hero.astro';
+ * import Text from './Text.astro';
+ *
+ * const registry = defineWidgets({ hero: Hero, text: Text });
+ * //    ^? { hero: AstroComponentFactory; text: AstroComponentFactory }
+ * ```
+ */
+export declare function defineWidgets<R extends WidgetRegistry>(registry: R): R;
+//# sourceMappingURL=define-widgets.d.ts.map

package/dist/define-widgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-widgets.d.ts","sourceRoot":"","sources":["../src/define-widgets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,cAAc,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAEtE"}

package/dist/define-widgets.js

@@ -0,0 +1,23 @@
+/**
+ * Returns the registry unchanged, typed as the literal object that was passed.
+ *
+ * The generic parameter is the whole point: annotating the same object as
+ * `WidgetRegistry` widens its keys to `string`, and the key union is what an
+ * editor completes on and what a caller narrows a `required` map against.
+ *
+ * In the core rather than in an adapter because every adapter needs it, and
+ * because a React consumer assembling a registry before handing it to
+ * `createWidgets` wants it too.
+ *
+ * @example
+ * ```ts
+ * import Hero from './Hero.astro';
+ * import Text from './Text.astro';
+ *
+ * const registry = defineWidgets({ hero: Hero, text: Text });
+ * //    ^? { hero: AstroComponentFactory; text: AstroComponentFactory }
+ * ```
+ */
+export function defineWidgets(registry) {
+    return registry;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './constants.js';
+export * from './define-widgets.js';
+export * from './validate-items.js';
+export * from './warn.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+// The framework-free half of a widget region.
+//
+// Nothing here imports a framework, so this package is usable from a webhook
+// handler, a Nest service or a CI script that validates a CMS payload before
+// anything renders it. scripts/verify-packaging.mjs greps the packed `dist/`
+// for a framework import, because that promise breaks silently: the build
+// succeeds and every test passes.
+//
+// The renderers live one package per framework -- `@evanion/react-widget`,
+// `@evanion/astro-widget` -- and each re-exports what its consumers need from
+// here, so a consumer who never names this package never installs it by hand.
+export * from './types.js';
+export * from './constants.js';
+export * from './define-widgets.js';
+export * from './validate-items.js';
+export * from './warn.js';

package/dist/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Maps a widget type name to whatever the adapter resolves it to.
+ *
+ * `T` is the adapter's component type. `@evanion/react-widget` instantiates it
+ * as a `ComponentType`, which is what drives its compile-time prop check.
+ * `@evanion/astro-widget` leaves it at the default: an `.astro` module's
+ * default export is an `AstroComponentFactory` carrying no prop types at all --
+ * the props of a `.astro` file live in its frontmatter `Props` interface and
+ * are not reachable from the factory's type -- so there is nothing there to
+ * infer from and {@link validateItems} covers that ground at build time.
+ */
+export type WidgetRegistry<T = unknown> = Record<string, T>;
+/**
+ * The `meta` vocabulary of a widget set whose chrome declares none.
+ *
+ * Any object, so an item may carry whatever placement data it likes and a
+ * chrome that reads `meta` narrows it by hand.
+ */
+export type WidgetMeta = Record<string, unknown>;
+/**
+ * Loose item shape, for data built before a registry exists: a CMS payload, a
+ * fixture, a network response.
+ *
+ * This is the whole item model, and every adapter renders exactly this. A
+ * renderer that can type its components against the registry offers a checked
+ * counterpart -- `@evanion/react-widget`'s `WidgetItem<C>` -- and this is what
+ * that one widens to.
+ */
+export interface AnyWidgetItem<Type extends string = string, Props = object> {
+    /** Stable identity for this item, and the key a renderer lists it under. */
+    id: string;
+    /** Which component to render. Must be a key of the registry. */
+    type: Type;
+    /**
+     * Props for that component.
+     *
+     * A named field rather than "every key the renderer does not claim for
+     * itself". The renderer's own fields would otherwise be reserved words in
+     * the CMS's vocabulary, and adding one later would silently take a prop
+     * away from every payload already written.
+     */
+    props: Props;
+    /**
+     * Placement and presentation data for the item chrome: grid column, span,
+     * ordering, CMS edit affordances.
+     *
+     * Handed to the chrome and never spread into the widget's own props, because
+     * where a widget sits is not something the widget should know.
+     */
+    meta?: WidgetMeta;
+    /**
+     * Nested items.
+     *
+     * What a renderer does with them is the runtime's business, and the two
+     * runtimes genuinely differ: React renders them as the component's
+     * `children`, while an Astro component receives child content through
+     * `<slot />` and so is handed them as data to open its own region over.
+     */
+    children?: AnyWidgetItem[];
+}
+/** A problem found by {@link validateItems}. */
+export interface WidgetProblem {
+    /** Index within the item's own sibling list; -1 when the root is not a list. */
+    index: number;
+    /** The item's `id`, or `-` when it has none usable. */
+    id: string;
+    /** The item's `type`, or `-` when it has none usable. */
+    type: string;
+    message: string;
+}
+/**
+ * The set of widget types a list may use.
+ *
+ * A plain list of names is accepted alongside a registry so that a webhook
+ * handler or a CI script can validate CMS payloads without importing the
+ * components it will never render.
+ */
+export type KnownWidgetTypes = WidgetRegistry | readonly string[];
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAAE,KAAK,GAAG,MAAM;IACzE,4EAA4E;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,gEAAgE;IAChE,IAAI,EAAE,IAAI,CAAC;IACX;;;;;;;OAOG;IACH,KAAK,EAAE,KAAK,CAAC;IACb;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG,SAAS,MAAM,EAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,15 @@
+import { ReactNode } from 'react';
+import { AnyWidgetComponent, RenderableWidgetItem, WidgetItemComponent, WidgetSuspenseMode } from './types.js';
+/**
+ * Renders one item and, recursively, its nested items as that item's children.
+ *
+ * Internal: not re-exported from the package barrel, so the nesting mechanism
+ * stays free to change without a breaking release.
+ *
+ * The `<Suspense>` boundary lives here rather than in the item chrome, so a
+ * custom `chrome.item` cannot silently remove it. `suspense` decides whether
+ * there is one to remove; it comes from the chrome, which is the only place
+ * that knows whether the region's widgets suspend.
+ */
+export declare function renderWidget(item: RenderableWidgetItem, components: Record<string, AnyWidgetComponent>, ItemWrapper: WidgetItemComponent, ctx: Record<string, unknown> | undefined, suspenseFallback: ReactNode, suspense: WidgetSuspenseMode): ReactNode;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,oBAAoB,EAC1B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAC9C,WAAW,EAAE,mBAAmB,EAChC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACxC,gBAAgB,EAAE,SAAS,EAC3B,QAAQ,EAAE,kBAAkB,GAC3B,SAAS,CAqEX"}

package/dist/validate-items.d.ts

@@ -0,0 +1,29 @@
+import type { KnownWidgetTypes, WidgetProblem } from './types.js';
+/**
+ * Checks a widget item list against the set of known types, recursing into
+ * `children`.
+ *
+ * Returns problems rather than throwing, and accumulates rather than
+ * short-circuiting, so a caller can print all of them at once. No renderer
+ * calls this: an adapter stays defensive -- skip the item and warn -- and
+ * validation is the loud, explicit gate run at ingestion or build time.
+ *
+ * `required` maps a widget type to the prop names that must be present and
+ * non-blank on `item.props`, where blank means `undefined`, `null` or
+ * whitespace only. It is the only check an Astro widget's props get, because an
+ * `.astro` component exposes no prop types to infer from; a React consumer
+ * wants it for data that never met `WidgetItem<C>`.
+ *
+ * @example
+ * ```ts
+ * validateItems([{ id: 'a', type: 'nope', props: {} }], ['news']);
+ * // [{ index: 0, id: 'a', type: 'nope', message: 'unknown widget type' }]
+ *
+ * validateItems([{ id: 'a', type: 'hero', props: {} }], ['hero'], {
+ *   hero: ['heading'],
+ * });
+ * // [{ index: 0, id: 'a', type: 'hero', message: 'missing field heading' }]
+ * ```
+ */
+export declare function validateItems(items: unknown, known: KnownWidgetTypes, required?: Record<string, string[]>): WidgetProblem[];
+//# sourceMappingURL=validate-items.d.ts.map

package/dist/validate-items.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-items.d.ts","sourceRoot":"","sources":["../src/validate-items.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAmClE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,gBAAgB,EACvB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAM,GACtC,aAAa,EAAE,CAiHjB"}

package/dist/validate-items.js

@@ -0,0 +1,165 @@
+import { VALIDATION_MESSAGES } from './constants.js';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Own-key lookup against a caller-supplied object.
+ *
+ * `in` and a bare index both walk the prototype chain, so a type of
+ * `constructor`, `toString` or `__proto__` resolves against `Object.prototype`:
+ * the type passes as registered, and `required[type]` comes back as a function
+ * for the field loop to iterate. Items are CMS data, so any string is
+ * reachable.
+ */
+function hasOwn(target, key) {
+    return Object.prototype.hasOwnProperty.call(target, key);
+}
+function knows(known, type) {
+    if (Array.isArray(known))
+        return known.includes(type);
+    return hasOwn(known, type);
+}
+/**
+ * A value a CMS text field that was opened and left empty arrives as.
+ */
+function isBlank(value) {
+    return (value === undefined ||
+        value === null ||
+        (typeof value === 'string' && value.trim() === ''));
+}
+/**
+ * Checks a widget item list against the set of known types, recursing into
+ * `children`.
+ *
+ * Returns problems rather than throwing, and accumulates rather than
+ * short-circuiting, so a caller can print all of them at once. No renderer
+ * calls this: an adapter stays defensive -- skip the item and warn -- and
+ * validation is the loud, explicit gate run at ingestion or build time.
+ *
+ * `required` maps a widget type to the prop names that must be present and
+ * non-blank on `item.props`, where blank means `undefined`, `null` or
+ * whitespace only. It is the only check an Astro widget's props get, because an
+ * `.astro` component exposes no prop types to infer from; a React consumer
+ * wants it for data that never met `WidgetItem<C>`.
+ *
+ * @example
+ * ```ts
+ * validateItems([{ id: 'a', type: 'nope', props: {} }], ['news']);
+ * // [{ index: 0, id: 'a', type: 'nope', message: 'unknown widget type' }]
+ *
+ * validateItems([{ id: 'a', type: 'hero', props: {} }], ['hero'], {
+ *   hero: ['heading'],
+ * });
+ * // [{ index: 0, id: 'a', type: 'hero', message: 'missing field heading' }]
+ * ```
+ */
+export function validateItems(items, known, required = {}) {
+    if (!Array.isArray(items)) {
+        return [
+            {
+                index: -1,
+                id: '-',
+                type: '-',
+                message: VALIDATION_MESSAGES.NOT_A_LIST,
+            },
+        ];
+    }
+    const problems = [];
+    const seenIds = new Set();
+    items.forEach((item, index) => {
+        if (!isPlainObject(item)) {
+            problems.push({
+                index,
+                id: '-',
+                type: '-',
+                message: VALIDATION_MESSAGES.NOT_AN_OBJECT,
+            });
+            return;
+        }
+        const id = typeof item['id'] === 'string' ? item['id'] : '-';
+        const type = typeof item['type'] === 'string' ? item['type'] : '-';
+        if (id === '-') {
+            problems.push({
+                index,
+                id,
+                type,
+                message: VALIDATION_MESSAGES.INVALID_ID,
+            });
+        }
+        else if (seenIds.has(id)) {
+            // Only within one sibling list: a renderer scopes keys per list, so the
+            // same id at different depths is fine.
+            problems.push({
+                index,
+                id,
+                type,
+                message: VALIDATION_MESSAGES.DUPLICATE_ID,
+            });
+        }
+        else {
+            seenIds.add(id);
+        }
+        if (type === '-') {
+            problems.push({
+                index,
+                id,
+                type,
+                message: VALIDATION_MESSAGES.INVALID_TYPE,
+            });
+        }
+        else if (!knows(known, type)) {
+            problems.push({
+                index,
+                id,
+                type,
+                message: VALIDATION_MESSAGES.UNKNOWN_TYPE,
+            });
+        }
+        const props = item['props'];
+        // An absent `props` is a problem, not an empty one. A widget's data lives
+        // under that key and nowhere else, so an item without it is an item whose
+        // props the payload put somewhere the renderer does not read -- which is
+        // exactly what a payload written against a flat item shape looks like, and
+        // exactly what this check is the migration gate for. A renderer then draws
+        // the widget with nothing in it and nothing logged.
+        if (!isPlainObject(props)) {
+            problems.push({
+                index,
+                id,
+                type,
+                message: VALIDATION_MESSAGES.INVALID_PROPS,
+            });
+        }
+        else if (type !== '-' && knows(known, type) && hasOwn(required, type)) {
+            // Only for a type the registry declares. An unknown type has already
+            // been reported, and listing the fields it did not supply says nothing
+            // the first problem did not.
+            const fields = required[type] ?? [];
+            for (const field of fields) {
+                const value = hasOwn(props, field) ? props[field] : undefined;
+                if (isBlank(value)) {
+                    problems.push({
+                        index,
+                        id,
+                        type,
+                        message: VALIDATION_MESSAGES.MISSING_FIELD(field),
+                    });
+                }
+            }
+        }
+        if (item['children'] !== undefined) {
+            if (Array.isArray(item['children'])) {
+                problems.push(...validateItems(item['children'], known, required));
+            }
+            else {
+                problems.push({
+                    index,
+                    id,
+                    type,
+                    message: VALIDATION_MESSAGES.INVALID_CHILDREN,
+                });
+            }
+        }
+    });
+    return problems;
+}

package/dist/warn.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Dev-only console warning, emitted once per distinct message.
+ *
+ * A renderer warns from render, so one stale `type` in a CMS payload logs again
+ * on every re-render, and twice over for a page that renders on the server and
+ * then hydrates. Every message in {@link ERROR_MESSAGES} carries the offending
+ * item's `type` and `id`, which is what makes the message text a usable key:
+ * each bad item is reported once per process, and a second bad item is still
+ * reported separately.
+ *
+ * Nothing is logged when `NODE_ENV` is `production`. A bundler folds that
+ * comparison to `false` and drops the call, so a stale item never reaches an
+ * end user's console.
+ *
+ * Exported for the adapters. A consumer has no reason to call it, and an
+ * adapter cannot reach it any other way: the adapters are separate packages,
+ * and this one publishes a single entry point.
+ */
+export declare function warnOnce(message: string): void;
+/**
+ * Clears the set of already-reported messages.
+ *
+ * A set that lives as long as the process is what a dev server wants and what a
+ * test file cannot have: one case's warning would silence the next case that
+ * produces the same message. Each adapter's `test-setup` calls this before
+ * every test.
+ */
+export declare function resetWarnings(): void;
+//# sourceMappingURL=warn.d.ts.map

package/dist/warn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warn.d.ts","sourceRoot":"","sources":["../src/warn.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAK9C;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC"}

package/dist/warn.js

@@ -0,0 +1,39 @@
+/** Messages already reported, for the lifetime of the process. */
+const seen = new Set();
+/**
+ * Dev-only console warning, emitted once per distinct message.
+ *
+ * A renderer warns from render, so one stale `type` in a CMS payload logs again
+ * on every re-render, and twice over for a page that renders on the server and
+ * then hydrates. Every message in {@link ERROR_MESSAGES} carries the offending
+ * item's `type` and `id`, which is what makes the message text a usable key:
+ * each bad item is reported once per process, and a second bad item is still
+ * reported separately.
+ *
+ * Nothing is logged when `NODE_ENV` is `production`. A bundler folds that
+ * comparison to `false` and drops the call, so a stale item never reaches an
+ * end user's console.
+ *
+ * Exported for the adapters. A consumer has no reason to call it, and an
+ * adapter cannot reach it any other way: the adapters are separate packages,
+ * and this one publishes a single entry point.
+ */
+export function warnOnce(message) {
+    if (process.env.NODE_ENV === 'production')
+        return;
+    if (seen.has(message))
+        return;
+    seen.add(message);
+    console.warn(message);
+}
+/**
+ * Clears the set of already-reported messages.
+ *
+ * A set that lives as long as the process is what a dev server wants and what a
+ * test file cannot have: one case's warning would silence the next case that
+ * produces the same message. Each adapter's `test-setup` calls this before
+ * every test.
+ */
+export function resetWarnings() {
+    seen.clear();
+}

package/dist/widget.d.ts

@@ -0,0 +1,36 @@
+import { WidgetComponentMap, WidgetItem, WidgetItemProblem, WidgetMeta, WidgetsConfig, WidgetsProps } from './types.js';
+/**
+ * Builds a widget set from a component map.
+ *
+ * The map drives inference: each item's `type` must be a key of it, and that
+ * item's `props` must match the corresponding component's props.
+ *
+ * Call it once at module scope. There is no provider and no hook, because
+ * React's `react-server` export condition has neither `createContext` nor
+ * `useContext` and this package has to be importable from a Server Component.
+ *
+ * The item `meta` vocabulary is inferred from `chrome.item`. Annotate that
+ * component with the shape it reads and every item's `meta` is checked against
+ * it; leave it unannotated, or pass no chrome, and `meta` stays any object.
+ * There is no type argument to pass by hand: `chrome.item` is the only thing
+ * that reads `meta`, so a set with no such chrome has nothing to check against,
+ * and naming `M` explicitly would cost the inference of `C`.
+ *
+ * @example
+ * ```tsx
+ * const { Widgets } = createWidgets({
+ *   components: { news: NewsTeaser, profile: UserSidebar },
+ * });
+ *
+ * <Widgets items={[
+ *   { id: '1', type: 'news', props: { title: 'Hello' } },
+ *   { id: '2', type: 'nope', props: {} },  // ← compile error: unknown type
+ * ]} />
+ * ```
+ */
+export declare function createWidgets<const C extends WidgetComponentMap, M = WidgetMeta>(config: WidgetsConfig<C, M>): {
+    Widgets: import('react').MemoExoticComponent<({ items, components: instanceComponents, chrome, ctx, }: WidgetsProps<C, M>) => import("react").JSX.Element | null>;
+    defineItems: (items: WidgetItem<C, M>[]) => WidgetItem<C, M>[];
+    validateItems: (items: unknown) => WidgetItemProblem[];
+};
+//# sourceMappingURL=widget.d.ts.map

package/dist/widget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget.d.ts","sourceRoot":"","sources":["../src/widget.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,kBAAkB,EAClB,UAAU,EAEV,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,YAAY,EACb,MAAM,YAAY,CAAC;AAOpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAC3B,KAAK,CAAC,CAAC,SAAS,kBAAkB,EAClC,CAAC,GAAG,UAAU,EACd,MAAM,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC;2GAQxB,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC;yBAwDO,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE;2BAQhC,OAAO,KAAG,iBAAiB,EAAE;EAIjE"}

package/dist/widgets.d.ts

@@ -0,0 +1,25 @@
+import { HTMLProps } from 'react';
+/**
+ * Default chrome around the whole set: a `<section>` carrying whatever props it
+ * is handed.
+ *
+ * `<section>` rather than `<div>` because a named section maps to the `region`
+ * landmark role (HTML-AAM), so a caller who passes `aria-label` gets a widget
+ * region that is reachable by landmark navigation and one who does not is no
+ * worse off than with a `<div>`.
+ */
+export declare function DefaultWrapper(props: HTMLProps<HTMLDivElement>): import("react").JSX.Element;
+/**
+ * Default chrome around one widget: a `<div>` carrying the `data-widget-*`
+ * attributes that CMS click-to-edit overlays, analytics and E2E selectors key
+ * off.
+ *
+ * `meta` is dropped rather than forwarded. It is arbitrary consumer data with
+ * no meaning to the DOM, and React warns about an unknown attribute on every
+ * key of it that reaches an element. A custom `chrome.item` is where meta is
+ * read.
+ */
+export declare function DefaultItem({ meta: _meta, ...props }: HTMLProps<HTMLDivElement> & {
+    meta?: Record<string, unknown>;
+}): import("react").JSX.Element;
+//# sourceMappingURL=widgets.d.ts.map

package/dist/widgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widgets.d.ts","sourceRoot":"","sources":["../src/widgets.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,CAAC,cAAc,CAAC,+BAE9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,EAC1B,IAAI,EAAE,KAAK,EACX,GAAG,KAAK,EACT,EAAE,SAAS,CAAC,cAAc,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,+BAEhE"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@evanion/widget",
+  "version": "0.1.0",
+  "description": "The framework-free half of a widget region: the item shape, the registry, and the validator every @evanion widget renderer shares.",
+  "keywords": [
+    "widget",
+    "cms",
+    "blocks",
+    "registry",
+    "validation",
+    "typescript"
+  ],
+  "homepage": "https://github.com/Evanion/libraries/tree/main/libs/widget#readme",
+  "bugs": {
+    "url": "https://github.com/Evanion/libraries/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Evanion/libraries.git",
+    "directory": "libs/widget"
+  },
+  "license": "MIT",
+  "author": "Mikael Pettersson",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@evanion/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.tsbuildinfo",
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/*.test-d.*",
+    "!src/test-setup.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/constants.ts

@@ -0,0 +1,47 @@
+/**
+ * Messages an adapter's renderer passes to {@link warnOnce}.
+ *
+ * Each one names the offending item's `id` and `type`, which is what lets
+ * `warnOnce` key on the message text and still report a second bad item
+ * separately.
+ *
+ * They live here rather than in each adapter so that a region rendered through
+ * React and the same region rendered through Astro report a stale CMS type in
+ * the same words.
+ */
+export const ERROR_MESSAGES = {
+  UNKNOWN_WIDGET: (type: string, id: string) =>
+    `Unknown widget type "${type}" for widget ID "${id}". Skipping render.`,
+  UNKNOWN: 'unknown',
+  MALFORMED_ITEMS:
+    'Malformed `items` prop: expected an array of widget items. Skipping render.',
+  MALFORMED_ITEM: (id: string | undefined, type: unknown) =>
+    `Malformed widget item (id="${id ?? 'unknown'}", type="${typeof type === 'string' ? type : 'unknown'}"). Skipping render.`,
+  MALFORMED_CHILDREN: (id: string) =>
+    `Malformed \`children\` on widget item (id="${id}"): expected an array. Rendering the widget without them.`,
+} as const;
+
+/**
+ * Messages reported by {@link validateItems}.
+ *
+ * Exported so a caller can group or translate problems without matching on
+ * prose, and so the tests assert against the same strings the library emits.
+ */
+export const VALIDATION_MESSAGES = {
+  NOT_A_LIST: 'items is not a list',
+  NOT_AN_OBJECT: 'item is not an object',
+  INVALID_ID: 'item id is not a string',
+  INVALID_TYPE: 'item type is not a string',
+  UNKNOWN_TYPE: 'unknown widget type',
+  INVALID_PROPS: 'props is not an object',
+  INVALID_CHILDREN: 'children is not a list',
+  DUPLICATE_ID: 'duplicate sibling id',
+  /**
+   * A field the caller's `required` map demands is absent or blank.
+   *
+   * A function rather than a constant because the field name is the whole of
+   * the report: a CMS editor reads "missing field heading" and knows which box
+   * to fill.
+   */
+  MISSING_FIELD: (field: string) => `missing field ${field}`,
+} as const;

package/src/define-widgets.ts

@@ -0,0 +1,25 @@
+import type { WidgetRegistry } from './types.js';
+
+/**
+ * Returns the registry unchanged, typed as the literal object that was passed.
+ *
+ * The generic parameter is the whole point: annotating the same object as
+ * `WidgetRegistry` widens its keys to `string`, and the key union is what an
+ * editor completes on and what a caller narrows a `required` map against.
+ *
+ * In the core rather than in an adapter because every adapter needs it, and
+ * because a React consumer assembling a registry before handing it to
+ * `createWidgets` wants it too.
+ *
+ * @example
+ * ```ts
+ * import Hero from './Hero.astro';
+ * import Text from './Text.astro';
+ *
+ * const registry = defineWidgets({ hero: Hero, text: Text });
+ * //    ^? { hero: AstroComponentFactory; text: AstroComponentFactory }
+ * ```
+ */
+export function defineWidgets<R extends WidgetRegistry>(registry: R): R {
+  return registry;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// The framework-free half of a widget region.
+//
+// Nothing here imports a framework, so this package is usable from a webhook
+// handler, a Nest service or a CI script that validates a CMS payload before
+// anything renders it. scripts/verify-packaging.mjs greps the packed `dist/`
+// for a framework import, because that promise breaks silently: the build
+// succeeds and every test passes.
+//
+// The renderers live one package per framework -- `@evanion/react-widget`,
+// `@evanion/astro-widget` -- and each re-exports what its consumers need from
+// here, so a consumer who never names this package never installs it by hand.
+
+export * from './types.js';
+export * from './constants.js';
+export * from './define-widgets.js';
+export * from './validate-items.js';
+export * from './warn.js';

package/src/types.ts

@@ -0,0 +1,82 @@
+/**
+ * Maps a widget type name to whatever the adapter resolves it to.
+ *
+ * `T` is the adapter's component type. `@evanion/react-widget` instantiates it
+ * as a `ComponentType`, which is what drives its compile-time prop check.
+ * `@evanion/astro-widget` leaves it at the default: an `.astro` module's
+ * default export is an `AstroComponentFactory` carrying no prop types at all --
+ * the props of a `.astro` file live in its frontmatter `Props` interface and
+ * are not reachable from the factory's type -- so there is nothing there to
+ * infer from and {@link validateItems} covers that ground at build time.
+ */
+export type WidgetRegistry<T = unknown> = Record<string, T>;
+
+/**
+ * The `meta` vocabulary of a widget set whose chrome declares none.
+ *
+ * Any object, so an item may carry whatever placement data it likes and a
+ * chrome that reads `meta` narrows it by hand.
+ */
+export type WidgetMeta = Record<string, unknown>;
+
+/**
+ * Loose item shape, for data built before a registry exists: a CMS payload, a
+ * fixture, a network response.
+ *
+ * This is the whole item model, and every adapter renders exactly this. A
+ * renderer that can type its components against the registry offers a checked
+ * counterpart -- `@evanion/react-widget`'s `WidgetItem<C>` -- and this is what
+ * that one widens to.
+ */
+export interface AnyWidgetItem<Type extends string = string, Props = object> {
+  /** Stable identity for this item, and the key a renderer lists it under. */
+  id: string;
+  /** Which component to render. Must be a key of the registry. */
+  type: Type;
+  /**
+   * Props for that component.
+   *
+   * A named field rather than "every key the renderer does not claim for
+   * itself". The renderer's own fields would otherwise be reserved words in
+   * the CMS's vocabulary, and adding one later would silently take a prop
+   * away from every payload already written.
+   */
+  props: Props;
+  /**
+   * Placement and presentation data for the item chrome: grid column, span,
+   * ordering, CMS edit affordances.
+   *
+   * Handed to the chrome and never spread into the widget's own props, because
+   * where a widget sits is not something the widget should know.
+   */
+  meta?: WidgetMeta;
+  /**
+   * Nested items.
+   *
+   * What a renderer does with them is the runtime's business, and the two
+   * runtimes genuinely differ: React renders them as the component's
+   * `children`, while an Astro component receives child content through
+   * `<slot />` and so is handed them as data to open its own region over.
+   */
+  children?: AnyWidgetItem[];
+}
+
+/** A problem found by {@link validateItems}. */
+export interface WidgetProblem {
+  /** Index within the item's own sibling list; -1 when the root is not a list. */
+  index: number;
+  /** The item's `id`, or `-` when it has none usable. */
+  id: string;
+  /** The item's `type`, or `-` when it has none usable. */
+  type: string;
+  message: string;
+}
+
+/**
+ * The set of widget types a list may use.
+ *
+ * A plain list of names is accepted alongside a registry so that a webhook
+ * handler or a CI script can validate CMS payloads without importing the
+ * components it will never render.
+ */
+export type KnownWidgetTypes = WidgetRegistry | readonly string[];

package/src/validate-items.ts

@@ -0,0 +1,180 @@
+import { VALIDATION_MESSAGES } from './constants.js';
+import type { KnownWidgetTypes, WidgetProblem } from './types.js';
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Own-key lookup against a caller-supplied object.
+ *
+ * `in` and a bare index both walk the prototype chain, so a type of
+ * `constructor`, `toString` or `__proto__` resolves against `Object.prototype`:
+ * the type passes as registered, and `required[type]` comes back as a function
+ * for the field loop to iterate. Items are CMS data, so any string is
+ * reachable.
+ */
+function hasOwn(target: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(target, key);
+}
+
+function knows(known: KnownWidgetTypes, type: string): boolean {
+  if (Array.isArray(known)) return known.includes(type);
+  return hasOwn(known, type);
+}
+
+/**
+ * A value a CMS text field that was opened and left empty arrives as.
+ */
+function isBlank(value: unknown): boolean {
+  return (
+    value === undefined ||
+    value === null ||
+    (typeof value === 'string' && value.trim() === '')
+  );
+}
+
+/**
+ * Checks a widget item list against the set of known types, recursing into
+ * `children`.
+ *
+ * Returns problems rather than throwing, and accumulates rather than
+ * short-circuiting, so a caller can print all of them at once. No renderer
+ * calls this: an adapter stays defensive -- skip the item and warn -- and
+ * validation is the loud, explicit gate run at ingestion or build time.
+ *
+ * `required` maps a widget type to the prop names that must be present and
+ * non-blank on `item.props`, where blank means `undefined`, `null` or
+ * whitespace only. It is the only check an Astro widget's props get, because an
+ * `.astro` component exposes no prop types to infer from; a React consumer
+ * wants it for data that never met `WidgetItem<C>`.
+ *
+ * @example
+ * ```ts
+ * validateItems([{ id: 'a', type: 'nope', props: {} }], ['news']);
+ * // [{ index: 0, id: 'a', type: 'nope', message: 'unknown widget type' }]
+ *
+ * validateItems([{ id: 'a', type: 'hero', props: {} }], ['hero'], {
+ *   hero: ['heading'],
+ * });
+ * // [{ index: 0, id: 'a', type: 'hero', message: 'missing field heading' }]
+ * ```
+ */
+export function validateItems(
+  items: unknown,
+  known: KnownWidgetTypes,
+  required: Record<string, string[]> = {},
+): WidgetProblem[] {
+  if (!Array.isArray(items)) {
+    return [
+      {
+        index: -1,
+        id: '-',
+        type: '-',
+        message: VALIDATION_MESSAGES.NOT_A_LIST,
+      },
+    ];
+  }
+
+  const problems: WidgetProblem[] = [];
+  const seenIds = new Set<string>();
+
+  items.forEach((item: unknown, index) => {
+    if (!isPlainObject(item)) {
+      problems.push({
+        index,
+        id: '-',
+        type: '-',
+        message: VALIDATION_MESSAGES.NOT_AN_OBJECT,
+      });
+      return;
+    }
+
+    const id = typeof item['id'] === 'string' ? item['id'] : '-';
+    const type = typeof item['type'] === 'string' ? item['type'] : '-';
+
+    if (id === '-') {
+      problems.push({
+        index,
+        id,
+        type,
+        message: VALIDATION_MESSAGES.INVALID_ID,
+      });
+    } else if (seenIds.has(id)) {
+      // Only within one sibling list: a renderer scopes keys per list, so the
+      // same id at different depths is fine.
+      problems.push({
+        index,
+        id,
+        type,
+        message: VALIDATION_MESSAGES.DUPLICATE_ID,
+      });
+    } else {
+      seenIds.add(id);
+    }
+
+    if (type === '-') {
+      problems.push({
+        index,
+        id,
+        type,
+        message: VALIDATION_MESSAGES.INVALID_TYPE,
+      });
+    } else if (!knows(known, type)) {
+      problems.push({
+        index,
+        id,
+        type,
+        message: VALIDATION_MESSAGES.UNKNOWN_TYPE,
+      });
+    }
+
+    const props = item['props'];
+
+    // An absent `props` is a problem, not an empty one. A widget's data lives
+    // under that key and nowhere else, so an item without it is an item whose
+    // props the payload put somewhere the renderer does not read -- which is
+    // exactly what a payload written against a flat item shape looks like, and
+    // exactly what this check is the migration gate for. A renderer then draws
+    // the widget with nothing in it and nothing logged.
+    if (!isPlainObject(props)) {
+      problems.push({
+        index,
+        id,
+        type,
+        message: VALIDATION_MESSAGES.INVALID_PROPS,
+      });
+    } else if (type !== '-' && knows(known, type) && hasOwn(required, type)) {
+      // Only for a type the registry declares. An unknown type has already
+      // been reported, and listing the fields it did not supply says nothing
+      // the first problem did not.
+      const fields = required[type] ?? [];
+      for (const field of fields) {
+        const value = hasOwn(props, field) ? props[field] : undefined;
+        if (isBlank(value)) {
+          problems.push({
+            index,
+            id,
+            type,
+            message: VALIDATION_MESSAGES.MISSING_FIELD(field),
+          });
+        }
+      }
+    }
+
+    if (item['children'] !== undefined) {
+      if (Array.isArray(item['children'])) {
+        problems.push(...validateItems(item['children'], known, required));
+      } else {
+        problems.push({
+          index,
+          id,
+          type,
+          message: VALIDATION_MESSAGES.INVALID_CHILDREN,
+        });
+      }
+    }
+  });
+
+  return problems;
+}

package/src/warn.ts

@@ -0,0 +1,39 @@
+/** Messages already reported, for the lifetime of the process. */
+const seen = new Set<string>();
+
+/**
+ * Dev-only console warning, emitted once per distinct message.
+ *
+ * A renderer warns from render, so one stale `type` in a CMS payload logs again
+ * on every re-render, and twice over for a page that renders on the server and
+ * then hydrates. Every message in {@link ERROR_MESSAGES} carries the offending
+ * item's `type` and `id`, which is what makes the message text a usable key:
+ * each bad item is reported once per process, and a second bad item is still
+ * reported separately.
+ *
+ * Nothing is logged when `NODE_ENV` is `production`. A bundler folds that
+ * comparison to `false` and drops the call, so a stale item never reaches an
+ * end user's console.
+ *
+ * Exported for the adapters. A consumer has no reason to call it, and an
+ * adapter cannot reach it any other way: the adapters are separate packages,
+ * and this one publishes a single entry point.
+ */
+export function warnOnce(message: string): void {
+  if (process.env.NODE_ENV === 'production') return;
+  if (seen.has(message)) return;
+  seen.add(message);
+  console.warn(message);
+}
+
+/**
+ * Clears the set of already-reported messages.
+ *
+ * A set that lives as long as the process is what a dev server wants and what a
+ * test file cannot have: one case's warning would silence the next case that
+ * produces the same message. Each adapter's `test-setup` calls this before
+ * every test.
+ */
+export function resetWarnings(): void {
+  seen.clear();
+}