@evanion/astro-widget 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+## 0.1.0 (2026-08-30)
+
+### 🚀 Features
+
+- **astro-widget:** Add Widgets renderer ([e10b840](https://github.com/Evanion/libraries/commit/e10b840))
+- **astro-widget:** Add validateBlocks ([8280820](https://github.com/Evanion/libraries/commit/8280820))
+- **astro-widget:** Add block types and defineBlocks ([8cceba9](https://github.com/Evanion/libraries/commit/8cceba9))
+
+### 🩹 Fixes
+
+- **astro-widget:** Fix six pre-publish packaging and packaging-adjacent findings ([09be4c2](https://github.com/Evanion/libraries/commit/09be4c2))
+- **astro-widget:** Correct children and chrome.item docs ([5ffd5e6](https://github.com/Evanion/libraries/commit/5ffd5e6))
+- **astro-widget:** Move key-union assertion into a type-checked test-d file ([1e300d2](https://github.com/Evanion/libraries/commit/1e300d2))
+
+### ❤️ Thank You
+
+- Mikael Pettersson @Evanion

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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,113 @@
+# @evanion/astro-widget
+
+Render CMS-driven Astro sections from structured block data. Build-time only —
+no runtime, no hydration, nothing shipped to the browser.
+
+The Astro counterpart to [`@evanion/react-widget`](../widget).
+
+## Install
+
+```bash
+npm install @evanion/astro-widget
+```
+
+Astro `>=5` is a peer dependency.
+
+## Use
+
+```ts
+// src/registry.ts
+import { defineBlocks } from '@evanion/astro-widget';
+import Hero from './blocks/Hero.astro';
+import Cards from './blocks/Cards.astro';
+
+export const registry = defineBlocks({ hero: Hero, cards: Cards });
+```
+
+```astro
+---
+import Widgets from '@evanion/astro-widget/components/Widgets.astro';
+import { registry } from '../registry';
+import page from '../data/page.json';
+---
+<Widgets items={page.sections} registry={registry} ctx={{ site: 'example.com' }} />
+```
+
+Where `page.json` is whatever your CMS writes:
+
+```json
+{ "sections": [{ "type": "hero", "heading": "Hello" }] }
+```
+
+## Data shape
+
+```ts
+interface BlockItem {
+  type: string;          // must be a key in the registry
+  id?: string;           // optional, useful as a DOM anchor
+  children?: BlockItem[];
+  [key: string]: unknown; // everything else becomes props
+}
+```
+
+## Validation
+
+`Widgets` **skips unknown block types silently** so a bad CMS save can never
+break a render. Catch them loudly at build time instead:
+
+```js
+import { validateBlocks } from '@evanion/astro-widget';
+
+const problems = validateBlocks(page.sections, registry, { hero: ['heading'] });
+if (problems.length) {
+  for (const p of problems) console.error(`section ${p.index} (${p.type}): ${p.message}`);
+  process.exit(1);
+}
+```
+
+`index` is scoped to whatever level of the tree it was found at: a problem in
+a top-level section and a problem in one of its `children` can both report
+`index: 0`, meaning different things. Use `type` and `message` together with
+`index` to disambiguate, or walk `children` yourself if you need an
+unambiguous path to the offending block.
+
+## Chrome
+
+Wrap every block without each block reimplementing section markup:
+
+```astro
+<Widgets items={items} registry={registry} chrome={{ item: Section }} />
+```
+
+`Section` receives the block's `type` and props, and **must render
+`<slot />`**. If it doesn't, Astro silently drops the wrapped block — no
+error, no warning, the section just vanishes from the page.
+
+## Nesting
+
+The renderer does **not** recurse. `children` on a `BlockItem` is forwarded
+to its block as ordinary prop data, nothing more — Astro projects child
+content through `<slot />`, never through a `children` prop. A block that
+wants to render its own nested sections must do so itself:
+
+```astro
+---
+// Cards.astro
+import Widgets from '@evanion/astro-widget/components/Widgets.astro';
+import { registry } from '../registry';
+const { children } = Astro.props;
+---
+<Widgets items={children} registry={registry} />
+```
+
+## Differences from @evanion/react-widget
+
+| | react-widget | astro-widget |
+|---|---|---|
+| Provider / `useWidgets` | yes | **no** — build-time rendering has nothing to provide; use `ctx` |
+| Prop type inference | inferred from the component map | **no** — Astro components are opaque at the type level. Use `validateBlocks` |
+| Nested `children` | `<Output />` outlet | **no recursion** — a block must render `<Widgets items={children} registry={registry} />` itself |
+
+## Licence
+
+MIT

package/dist/define-blocks.d.ts

@@ -0,0 +1,7 @@
+import { BlockRegistry } from './types';
+/**
+ * Identity function that pins the registry's key union for editors and for
+ * `validateBlocks`. It does no work at runtime by design.
+ */
+export declare function defineBlocks<M extends BlockRegistry>(map: M): M;
+//# sourceMappingURL=define-blocks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define-blocks.d.ts","sourceRoot":"","sources":["../src/define-blocks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,aAAa,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAE/D"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { defineBlocks } from './define-blocks';
+export { validateBlocks } from './validate-blocks';
+export type { BlockItem, BlockRegistry, BlockProblem } from './types';
+//# 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":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,33 @@
+//#region src/define-blocks.ts
+function e(e) {
+	return e;
+}
+//#endregion
+//#region src/validate-blocks.ts
+function t(e, n, r = {}) {
+	if (!Array.isArray(e)) return [{
+		index: -1,
+		type: "-",
+		message: "sektionslistan är inte en lista"
+	}];
+	let i = [];
+	return e.forEach((e, a) => {
+		let o = typeof e?.type == "string" ? e.type : "-";
+		if (!(o in n)) i.push({
+			index: a,
+			type: o,
+			message: "okänd blocktyp"
+		});
+		else for (let t of r[o] ?? []) {
+			let n = e[t];
+			(n == null || typeof n == "string" && n.trim() === "") && i.push({
+				index: a,
+				type: o,
+				message: `saknar fältet ${t}`
+			});
+		}
+		Array.isArray(e?.children) && i.push(...t(e.children, n, r));
+	}), i;
+}
+//#endregion
+export { e as defineBlocks, t as validateBlocks };

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+/** One section, as written by the CMS. */
+export interface BlockItem {
+    /** Discriminator; must be a key in the registry. */
+    type: string;
+    /** Optional stable id, useful as a DOM anchor. */
+    id?: string;
+    /** Nested blocks, forwarded to the component as ordinary prop data.
+        The renderer does NOT recurse — Astro projects child content through
+        <slot />, not through a `children` prop. A block that wants nesting
+        renders <Widgets items={children} registry={registry} /> itself. */
+    children?: BlockItem[];
+    /** Everything else is passed to the component as props. */
+    [key: string]: unknown;
+}
+/**
+ * Maps a block type to an Astro component.
+ *
+ * Values are deliberately `unknown`: Astro components are opaque at the type
+ * level, so unlike @evanion/react-widget we cannot infer each block's props
+ * from the component. `validateBlocks` covers that ground at build time.
+ */
+export type BlockRegistry = Record<string, unknown>;
+/** A problem found by `validateBlocks`. */
+export interface BlockProblem {
+    index: number;
+    type: string;
+    message: 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,0CAA0C;AAC1C,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;2EAGuE;IACvE,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;IACvB,2DAA2D;IAC3D,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/validate-blocks.d.ts

@@ -0,0 +1,10 @@
+import { BlockItem, BlockProblem, BlockRegistry } from './types';
+/**
+ * Checks a block list against a registry. Returns problems rather than
+ * throwing, so a caller can print all of them at once.
+ *
+ * `required` maps a block type to the field names that must be present and
+ * non-blank.
+ */
+export declare function validateBlocks(items: BlockItem[], registry: BlockRegistry, required?: Record<string, string[]>): BlockProblem[];
+//# sourceMappingURL=validate-blocks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate-blocks.d.ts","sourceRoot":"","sources":["../src/validate-blocks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEtE;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,EAAE,EAClB,QAAQ,EAAE,aAAa,EACvB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAM,GACtC,YAAY,EAAE,CA+BhB"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@evanion/astro-widget",
+  "version": "0.1.0",
+  "description": "Render CMS-driven Astro sections from structured block data. Build-time, zero runtime.",
+  "keywords": [
+    "astro",
+    "widget",
+    "cms",
+    "blocks",
+    "sections",
+    "registry",
+    "typescript"
+  ],
+  "homepage": "https://github.com/Evanion/libraries/tree/main/libs/astro-widget#readme",
+  "bugs": {
+    "url": "https://github.com/Evanion/libraries/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Evanion/libraries.git",
+    "directory": "libs/astro-widget"
+  },
+  "license": "MIT",
+  "author": "Mikael Pettersson",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "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"
+    },
+    "./components/*": "./src/components/*"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.tsbuildinfo",
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/*.test-d.*",
+    "!src/test-setup.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "astro": ">=5"
+  }
+}

package/src/components/Widgets.astro

@@ -0,0 +1,42 @@
+---
+/**
+ * Renders a list of CMS blocks.
+ *
+ * Deliberately defensive: an unknown type is skipped rather than thrown on, so
+ * a gap in build-time validation can never take a page down mid-render.
+ * `validateBlocks` is the loud gate; this is the safety net.
+ */
+import type { BlockItem, BlockRegistry } from '../types';
+
+interface Props {
+  items: BlockItem[];
+  registry: BlockRegistry;
+  /** Page-level data passed to every block. Astro renders at build time, so
+      there is no context provider to do this for us — and none is needed. */
+  ctx?: Record<string, unknown>;
+  /** Optional wrapper rendered around every block, e.g. for CMS edit affordances.
+      `chrome.item` MUST render <slot /> — if it doesn't, Astro silently drops
+      the wrapped block and it will not appear on the page. No error is thrown. */
+  chrome?: { item?: unknown };
+}
+
+const { items, registry, ctx, chrome } = Astro.props;
+const list = Array.isArray(items) ? items : [];
+const Item = chrome?.item as never;
+---
+{
+  list.map((item) => {
+    const Component = registry[item?.type] as never;
+    if (!Component) return null;
+
+    const { type, id, children, ...props } = item;
+
+    return Item ? (
+      <Item type={type} id={id} {...props}>
+        <Component {...props} id={id} ctx={ctx} children={children} />
+      </Item>
+    ) : (
+      <Component {...props} id={id} ctx={ctx} children={children} />
+    );
+  })
+}

package/src/define-blocks.ts

@@ -0,0 +1,9 @@
+import type { BlockRegistry } from './types';
+
+/**
+ * Identity function that pins the registry's key union for editors and for
+ * `validateBlocks`. It does no work at runtime by design.
+ */
+export function defineBlocks<M extends BlockRegistry>(map: M): M {
+  return map;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { defineBlocks } from './define-blocks';
+export { validateBlocks } from './validate-blocks';
+export type { BlockItem, BlockRegistry, BlockProblem } from './types';

package/src/types.ts

@@ -0,0 +1,30 @@
+/** One section, as written by the CMS. */
+export interface BlockItem {
+  /** Discriminator; must be a key in the registry. */
+  type: string;
+  /** Optional stable id, useful as a DOM anchor. */
+  id?: string;
+  /** Nested blocks, forwarded to the component as ordinary prop data.
+      The renderer does NOT recurse — Astro projects child content through
+      <slot />, not through a `children` prop. A block that wants nesting
+      renders <Widgets items={children} registry={registry} /> itself. */
+  children?: BlockItem[];
+  /** Everything else is passed to the component as props. */
+  [key: string]: unknown;
+}
+
+/**
+ * Maps a block type to an Astro component.
+ *
+ * Values are deliberately `unknown`: Astro components are opaque at the type
+ * level, so unlike @evanion/react-widget we cannot infer each block's props
+ * from the component. `validateBlocks` covers that ground at build time.
+ */
+export type BlockRegistry = Record<string, unknown>;
+
+/** A problem found by `validateBlocks`. */
+export interface BlockProblem {
+  index: number;
+  type: string;
+  message: string;
+}

package/src/validate-blocks.ts

@@ -0,0 +1,45 @@
+import type { BlockItem, BlockProblem, BlockRegistry } from './types';
+
+/**
+ * Checks a block list against a registry. Returns problems rather than
+ * throwing, so a caller can print all of them at once.
+ *
+ * `required` maps a block type to the field names that must be present and
+ * non-blank.
+ */
+export function validateBlocks(
+  items: BlockItem[],
+  registry: BlockRegistry,
+  required: Record<string, string[]> = {}
+): BlockProblem[] {
+  if (!Array.isArray(items)) {
+    return [{ index: -1, type: '-', message: 'sektionslistan är inte en lista' }];
+  }
+
+  const problems: BlockProblem[] = [];
+
+  items.forEach((item, index) => {
+    const type = typeof item?.type === 'string' ? item.type : '-';
+
+    if (!(type in registry)) {
+      problems.push({ index, type, message: 'okänd blocktyp' });
+    } else {
+      for (const field of required[type] ?? []) {
+        const value = item[field];
+        const blank =
+          value === undefined ||
+          value === null ||
+          (typeof value === 'string' && value.trim() === '');
+        if (blank) {
+          problems.push({ index, type, message: `saknar fältet ${field}` });
+        }
+      }
+    }
+
+    if (Array.isArray(item?.children)) {
+      problems.push(...validateBlocks(item.children, registry, required));
+    }
+  });
+
+  return problems;
+}