@uselab/vue-islands 1.0.0

package/README.md

@@ -0,0 +1,295 @@
+# vue-islands
+
+Progressively mount Vue components ("islands") into server-rendered semantic HTML, using
+`data-component` attributes to declare which elements should become Vue components.
+
+Components can be used as Vue islands as well as in the normal Vue way, so you can mix and match server-rendered HTML with client-side.
+
+## Install
+
+```bash
+npm install @uselab/vue-islands vue
+```
+
+`vue` (`^3.0.0`) is a peer dependency, so use whichever Vue 3 version your project already depends
+on. `zod` (`^4.0.0`) is also an optional peer dependency, only required if you use
+`validateRawProps`:
+
+```bash
+npm install zod
+```
+
+## Usage
+
+Mark up your server-rendered HTML with `data-component` (and optionally `data-props`)
+attributes:
+
+```html
+<div data-component="my-widget" data-title="Hello" data-count-json="3"></div>
+```
+
+Then, in your TypeScript entry point, register the matching Vue components and call
+`initiateVueIslands` once the DOM is ready:
+
+```ts
+import {
+    initiateVueIslands,
+    createVNodeFunction,
+    type GetVNode,
+} from '@uselab/vue-islands';
+import MyWidget from './MyWidget.vue';
+
+const components: Record<string, GetVNode> = {
+    'my-widget': createVNodeFunction(MyWidget),
+};
+
+initiateVueIslands(components, {
+    // Optional: enable dev-only console logging of which islands get mounted.
+    isDevMode: import.meta.env.DEV,
+});
+```
+
+Component names can be written in `camelCase` in the `components` map (as above); `data-component`
+attributes in the HTML are matched case-insensitively against the `kebab-case` form of these keys,
+so `menu`, `heavyChart`, and `imageCarousel` above match `data-component="menu"`,
+`data-component="heavy-chart"`, and `data-component="image-carousel"` respectively.
+
+Each matching element is replaced (or, with `data-keep-semantic-html`, appended into) with a
+mounted Vue app rendering the corresponding component, using `attributes`/`data-props` as props and
+child elements as slots.
+
+## Declaring components and props in HTML
+
+- `data-component="my-widget"` — marks an element for mounting; the value is matched
+  case-insensitively against the `kebab-case` form of the key in your `components` map.
+- `data-component-tag-name="div"` — overrides the tag name of the mounted root element (e.g.
+  `<ol data-component="my-widget" data-component-tag-name="div">` mounts into a `<div>` instead of
+  an `<ol>`). When omitted, the tag name of the original element is used.
+- `data-keep-semantic-html` — when truthy (`""`, `"true"`, or `"1"`), the original server-rendered
+  element is kept in the DOM and the mounted component is appended into it, instead of replacing
+  it. Useful when the original element must stay in place for SEO, accessibility, or CSS reasons
+  (e.g. an `<a>` that should keep behaving like a link until the island takes over).
+
+Props can be defined in several ways:
+
+- As plain attributes: `<div data-component="my-widget" title="Boo">`
+- As `data-{name}` attributes: `<div data-component="my-widget" data-title="Boo">`
+- As attributes ending in `-json` to pass parsed JSON data: `<div data-component="my-widget"
+  data-options-json='{"key":"value"}' data-show-json="true" data-counter-json="12">`
+- In `data-props`, as a query string mapping `propName=attributeName`: `<a
+  data-component="my-widget" href="/boo" data-props="link-url=href">` sets the `link-url` prop to
+  the element's `href` value.
+- In `data-props`, using `text-content` to read the element's text: `<div
+  data-component="my-widget" data-props="title=text-content">Boo</div>`
+- In `data-props`, JSON parsing applies when either side of the mapping ends in `-json`: `<div
+  data-component="my-widget" data-items-json="[1,2,3]" data-props="items=data-items-json">` and
+  `<div data-component="my-widget" data-props="items-json=text-content">[1,2,3]</div>` both parse
+  the value as JSON.
+- On any descendant element that has `data-props` but **not** `data-component` — useful for
+  composing a prop object from several child elements without introducing extra slot markup.
+
+Prop names in `data-props` support dot and bracket notation to build nested objects and arrays:
+
+```html
+<div data-component="my-widget">
+    <h2 data-props="title=text-content">Boo</h2>
+    <img data-props="image.src=src&amp;image.alt=alt" src="/image.jpg" alt="An image" />
+    <div data-props="cities[0]=text-content">Amsterdam</div>
+    <div data-props="cities[1]=text-content">Rotterdam</div>
+</div>
+```
+
+Descendant elements that **don't** have `data-props` (and aren't themselves `data-component`
+islands) are passed through as slots instead, grouped by their `slot` or `data-slot` attribute:
+
+```html
+<div data-component="my-widget">
+    <div slot="header">Boo</div>
+    <div slot="footer">Baa</div>
+</div>
+```
+
+A descendant element with its own `data-component` attribute is rendered as a normal Vue component
+within the parent island, so slot content can include other registered components:
+
+```html
+<div data-component="my-widget">
+    <div slot="header">
+        <span data-component="user-badge" data-name="Boo"></span>
+    </div>
+</div>
+```
+
+These nested components are **not** separate vue-islands — only the root `[data-component]`
+elements queried by `initiateVueIslands` are individually mounted as their own `App` instance and
+replace (or append into) their host element. A `data-component` found while walking a parent
+island's slot content is turned into a plain Vue vnode instead, rendered as part of that parent
+app. As a result, `data-keep-semantic-html` (and the replace-vs-append behavior it controls) only
+has an effect on root elements; setting it on a nested component has no effect.
+
+## Configuring each mounted app
+
+Every island is its own, independent Vue `App` instance — each `data-component` element gets its
+own `createApp(...)`/`mount(...)` call under the hood. Use the `configureApp` option to run setup
+logic against every one of these instances before it's mounted, e.g. to register an i18n plugin so
+translations are available inside every island, or a shared Pinia instance so islands can read from
+and write to the same store:
+
+```ts
+import { createPinia } from 'pinia';
+import { createI18n } from 'vue-i18n';
+import { initiateVueIslands } from '@uselab/vue-islands';
+
+const pinia = createPinia();
+const i18n = createI18n({ locale: 'en', messages });
+
+initiateVueIslands(components, {
+    configureApp: async (app) => {
+        app.use(pinia);
+        app.use(i18n);
+    },
+});
+```
+
+Because `configureApp` runs for every island, a shared Pinia instance or just a simple vue ref object lets independently mounted
+islands stay in sync with each other (and with the rest of the page), and a shared i18n instance
+means every island can use the same translations and locale without reconfiguring it per component.
+
+## Lazy loading components
+
+Because a `GetVNode` function is only invoked for elements that actually have a matching
+`data-component` attribute on the page, you can wrap the component import in Vue's
+`defineAsyncComponent`. This splits your code to code-split it into its own chunk that's only fetched when the island is
+actually mounted:
+
+```ts
+import {
+    initiateVueIslands,
+    createVNodeFunction,
+    type GetVNode,
+} from '@uselab/vue-islands';
+import { defineAsyncComponent } from 'vue';
+import MyWidget from './MyWidget.vue';
+
+const components: Record<string, GetVNode> = {
+    // Loaded eagerly, e.g. because it's needed on (almost) every page.
+    'my-widget': createVNodeFunction(MyWidget),
+
+    // Loaded lazily: the chunk for `HeavyChart.vue` is only downloaded when a
+    // `data-component="heavy-chart"` element is found and mounted.
+    'heavy-chart': createVNodeFunction(
+        defineAsyncComponent(() => import('./HeavyChart.vue'))
+    ),
+};
+
+initiateVueIslands(components);
+```
+
+This keeps the initial bundle small: pages without a `heavy-chart` island never download its code,
+while `defineAsyncComponent` still shows Vue's built-in loading/error states (via its
+`loadingComponent`/`errorComponent` options) while the chunk loads.
+
+## Organizing many components
+
+Projects with dozens of islands tend to converge on a small helper that wraps each component in a
+`GetVNode` function, so the `components` map stays a flat, readable list of imports.
+`createVNodeFunction` is exported for this purpose: it passes both the raw and the spread props to
+the component, so components can use `validateRawProps` to log helpful errors (including the
+original, unparsed props) when Zod validation fails:
+
+```ts
+import { defineAsyncComponent } from 'vue';
+import {
+    initiateVueIslands,
+    createVNodeFunction,
+    type GetVNode,
+} from '@uselab/vue-islands';
+import Menu from './features/menu.vue';
+import Header from './features/header.vue';
+import Footer from './features/footer.vue';
+
+const components: Record<string, GetVNode> = {
+    // Eagerly loaded components, e.g. because they're needed on (almost) every page.
+    menu: createVNodeFunction(Menu),
+    header: createVNodeFunction(Header),
+    footer: createVNodeFunction(Footer),
+
+    // Lazily loaded components: only fetched when a matching `data-component` element is found.
+    heavyChart: createVNodeFunction(
+        defineAsyncComponent(() => import('./features/heavy-chart.vue'))
+    ),
+    imageCarousel: createVNodeFunction(
+        defineAsyncComponent(() => import('./features/image-carousel.vue'))
+    ),
+
+    // ...more components
+};
+
+initiateVueIslands(components);
+```
+
+## Validating props with Zod
+
+Because props parsed from HTML attributes arrive untyped, pairing `validateRawProps` with a Zod
+schema catches malformed markup early and logs a clear console error — including the original,
+unparsed `rawProps` — instead of failing silently or crashing deep inside the component:
+
+```vue
+<script setup lang="ts">
+import * as z from 'zod';
+import { type WithRawProps, validateRawProps } from '@uselab/vue-islands';
+
+type Props = { items: { link?: string; title: string }[] } & WithRawProps;
+
+const props = defineProps<Props>();
+
+const validator = z.object({
+    items: z.array(
+        z.object({
+            link: z.string().optional(),
+            title: z.string(),
+        })
+    ),
+});
+
+validateRawProps<Props>(validator.safeParse(props.rawProps || props), props);
+</script>
+```
+## API
+
+- `initiateVueIslands(components, options?)` — scans the document (or `options.doc`) for
+  `[data-component]` elements and mounts the matching Vue components (see "Declaring components
+  and props in HTML" above for the supported `data-*` attributes).
+  - `options.isDevMode?: boolean` — enables verbose console logging for debugging (default
+    `false`).
+  - `options.configureApp?: (app: App) => Promise<void>` — called for each created Vue `App`
+    instance before mounting, useful for registering plugins/directives (see "Configuring each
+    mounted app" above).
+  - `options.doc?: Document` — alternate document to scan (default: global `document`).
+- `createVNodeFunction(component)` — helper that turns a Vue `Component` into a `GetVNode`
+  function, passing it both the raw and the spread props (as `WithRawProps`) plus slots. Useful
+  when registering many components (see "Organizing many components" above).
+- `validateRawProps(result, props)` — helper for logging Zod prop-validation errors together with
+  the raw (unparsed) props that were passed in. Requires `zod` (^4.0.0) to be installed.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run quality # runs typecheck, lint, and tests
+```
+
+`npm install` also sets up a `pre-push` git hook (via `simple-git-hooks`) that runs
+`npm run quality` (lint, typecheck, and tests) before every `git push`, aborting the push if any of
+them fail.
+
+## Publishing a new version
+
+1. `npm version patch` (or `minor` / `major`) — runs `npm run quality` first (aborting on failure),
+   then bumps `package.json`, commits, tags the commit `vX.Y.Z`, and pushes the commit and tag to
+   GitHub.
+2. Pushing the `vX.Y.Z` tag triggers the [CI workflow](.github/workflows/ci.yml), which re-runs
+   lint, typecheck, and the test suite on GitHub. Wait for it to pass.
+3. `npm publish` — builds `dist/` (via the `prepublishOnly` script) and publishes the package to
+   npm.

package/dist/vue-islands.d.ts

@@ -0,0 +1,36 @@
+import { App } from 'vue';
+import { Component } from 'vue';
+import { Slots } from 'vue';
+import { VNode } from 'vue';
+import { ZodSafeParseResult } from 'zod';
+
+export declare const createVNodeFunction: (component: Component) => GetVNode;
+
+export declare type GetVNode = (props: GetVNodeProps, slots?: Slots) => VNode;
+
+export declare type GetVNodeFunction = (name?: string) => GetVNode | undefined;
+
+declare type GetVNodeProps = Record<string, unknown>;
+
+export declare const initiateVueIslands: (components: Record<string, GetVNode>, options?: {
+    configureApp?: (app: App) => Promise<void>;
+    doc?: Document;
+    isDevMode?: boolean;
+}) => void;
+
+export declare const validateRawProps: <Props extends object & WithRawProps>(result: ZodSafeParseResult<Props>, props: Props) => void;
+
+export declare type WithRawProps<Props extends Record<string, unknown> = Record<string, unknown>> = {
+    rawProps?: Partial<Props>;
+};
+
+export { }
+
+
+declare global {
+    interface Window {
+        __vueIslands: {
+            mount: (names: string[], options?: MountOptions) => void;
+        };
+    }
+}

package/dist/vue-islands.js

@@ -0,0 +1,85 @@
+import { Comment as e, Text as t, createApp as n, defineComponent as r, getCurrentInstance as i, h as a } from "vue";
+import o from "lodash/kebabCase";
+import { memoize as s } from "lodash";
+import c from "lodash/groupBy";
+import l from "lodash/camelCase";
+import u from "lodash/merge";
+import d from "lodash/set";
+//#region src/dom-props.ts
+var f = (e, ...t) => t.reduce((e, t) => u(e, t), e), p = (e) => e.nodeType === Node.ELEMENT_NODE, m = (e) => o(e).endsWith("-json"), h = (e) => JSON.parse(e.replace(/^True$/, "true").replace(/^False$/, "false")), g = (e, t) => {
+	if (t !== void 0) return m(e) ? h(t) : t;
+}, _ = (e, t) => g(t, e.getAttribute(t) ?? void 0), v = (e) => e === "" || e?.toLowerCase() === "true" || e === "1", y = (e) => {
+	let t = (e, t) => Array.from(new URLSearchParams(e || "").entries()).reduce((e, [n, r]) => o(r) === "text-content" ? f(e, d({}, n, g(n, (t.textContent || "").trim()))) : f(e, d({}, n, _(t, r))), {}), n = ((e, n) => e.reduce((e, r) => [
+		"v-cloak",
+		"data-v-cloak",
+		"data-component"
+	].includes(o(r.name)) ? e : r.name.toLowerCase() === "data-props" ? f(e, t(r.value, n)) : f(e, d({}, r.name, m(r.name) ? h(r.value) : r.value)), {}))(Array.from(e.attributes), e), r = (e, t = []) => {
+		let n = e.nextNode();
+		return n === null ? t : r(e, [...t, n]);
+	}, i = r(document.createTreeWalker(e, NodeFilter.SHOW_ELEMENT, { acceptNode: (e) => !p(e) || e.dataset.component ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT })).filter((e) => p(e) && e.dataset.props).reduce((e, n) => f(e, p(n) ? t(n.dataset.props, n) : {}), n), a = (e) => {
+		let t = o(e), n = /^(data-)?(.*?)(-json)?$/i.exec(t);
+		return n ? l(n[2]) : t;
+	};
+	return Object.entries(i).reduce((e, [t, n]) => ({
+		...e,
+		[a(t)]: n
+	}), {});
+}, b = (n, r, i) => {
+	let o = n.dataset.component, s = r(o);
+	o && !s && console.error(`Component ${o} not found.`);
+	let l = (n) => n.reduce((n, o) => o.nodeType === Node.TEXT_NODE && o.textContent ? [...n, a(t, o.textContent)] : o.nodeType === Node.COMMENT_NODE && o.textContent ? [...n, a(e, o.textContent)] : p(o) ? (o.dataset.component && o.dataset.keepSemanticHtml !== void 0 && i.isDevMode && console.warn(`[semantic-html-to-vue] data-keep-semantic-html has no effect on nested component "${o.dataset.component}" — it only applies to root data-component elements.`), [...n, b(o, r, i)]) : n, []), u = (e) => {
+		let t = Object.entries(c(e, (e) => p(e) && (e.getAttribute("slot") || e.dataset.slot) || "default")).map(([e, t]) => [e, l(t)]);
+		return Object.fromEntries(t.map(([e, t]) => [e, () => t]));
+	};
+	if (s) return i.isDevMode && console.info(`[semantic-html-to-vue] Rendering component: ${o}`), s(y(n), u(Array.from(n.children).filter((e) => p(e) && (!e.dataset.props || e.dataset.component))));
+	let d = l(Array.from(n.childNodes)), f = Object.fromEntries(Array.from(n.attributes).map(({ name: e, value: t }) => [e, t]));
+	return a(n.tagName, f, d);
+}, x = (e, t, n) => {
+	let r = /* @__PURE__ */ new Set([
+		"id",
+		"class",
+		"style",
+		"role"
+	]);
+	Array.from(e.attributes).forEach(({ name: e, value: n }) => {
+		let i = e.toLowerCase();
+		(r.has(i) || i.startsWith("aria-")) && t.setAttribute(e, n);
+	}), e.parentElement.insertBefore(t, e.nextSibling), n.mount(t), e.replaceWith(t), delete e.dataset.vCloak;
+}, S = (e, t, n) => {
+	Array.from(e.childNodes).filter((e) => e.nodeType === Node.TEXT_NODE).forEach((e) => e.remove()), e.removeAttribute("href"), e.appendChild(t), n.mount(t), delete e.dataset.vCloak;
+}, C = (e) => (t, n) => a(e, {
+	rawProps: t,
+	...t
+}, n), w = (e, t) => {
+	let { configureApp: i, doc: a = document, isDevMode: c = !1 } = t || {}, l = Object.entries(e).map(([e, t]) => [o(e), t]), u = s((e) => {
+		if (!e) return;
+		let t = o(e), [, n] = l.find(([e]) => e === t) || [];
+		return n;
+	});
+	Array.from(a.querySelectorAll("[data-component]")).filter((e) => !e.parentElement.closest("[data-component]")).reduce((e, t) => {
+		let n = o(t.dataset.component);
+		return u(n) ? [...e, {
+			element: t,
+			vNode: b(t, u, { isDevMode: c })
+		}] : (console.error(`Component ${n} not found.`), e);
+	}, []).forEach(({ element: e, vNode: t }) => {
+		(async () => {
+			let a = e.dataset.componentTagName ?? e.nodeName.toLowerCase() ?? "div";
+			try {
+				let o = document.createElement(a);
+				o.dataset.mountElement = "";
+				let s = n(r(() => () => t));
+				i && await i(s), v(e.dataset.keepSemanticHtml) ? S(e, o, s) : x(e, o, s);
+			} catch (t) {
+				console.error(`[semantic-html-to-vue] Failed to mount component: ${e.dataset.component}`, t);
+			}
+		})();
+	});
+}, T = (e, t) => {
+	if (!e.success) {
+		let n = i();
+		console.error(`Props validation error in component "${n?.type.__name}": ${e.error.message}\n\nRaw props:`, t.rawProps);
+	}
+};
+//#endregion
+export { C as createVNodeFunction, w as initiateVueIslands, T as validateRawProps };

package/package.json

@@ -0,0 +1,78 @@
+{
+    "name": "@uselab/vue-islands",
+    "version": "1.0.0",
+    "description": "Progressively mount Vue components (\"islands\") into server-rendered semantic HTML using data attributes.",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/uselab/vue-islands.git"
+    },
+    "keywords": [
+        "vue",
+        "islands",
+        "islands-architecture",
+        "progressive-enhancement",
+        "ssr"
+    ],
+    "type": "module",
+    "main": "./dist/vue-islands.js",
+    "module": "./dist/vue-islands.js",
+    "types": "./dist/vue-islands.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/vue-islands.d.ts",
+            "import": "./dist/vue-islands.js"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "sideEffects": false,
+    "scripts": {
+        "build": "vite build",
+        "quality": "npm run lint && npm run typecheck && npm test",
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix",
+        "typecheck": "tsc --noEmit",
+        "test": "playwright test",
+        "test:ui": "playwright test --ui",
+        "prepublishOnly": "npm run build",
+        "prepare": "simple-git-hooks",
+        "preversion": "npm run quality",
+        "postversion": "git push --follow-tags"
+    },
+    "simple-git-hooks": {
+        "pre-push": "npm run quality"
+    },
+    "peerDependencies": {
+        "vue": "^3.0.0",
+        "zod": "^4.0.0"
+    },
+    "peerDependenciesMeta": {
+        "zod": {
+            "optional": true
+        }
+    },
+    "dependencies": {
+        "lodash": "^4.18.1"
+    },
+    "devDependencies": {
+        "@eslint/js": "^10.0.1",
+        "@microsoft/api-extractor": "^7.59.0",
+        "@playwright/test": "^1.62.1",
+        "@types/lodash": "^4.17.25",
+        "@types/node": "^26.4.0",
+        "eslint": "^10.9.1",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-prettier": "^5.5.6",
+        "globals": "^17.11.0",
+        "prettier": "^3.9.6",
+        "simple-git-hooks": "^2.13.1",
+        "typescript": "^6.0.3",
+        "typescript-eslint": "^8.68.0",
+        "vite": "^8.2.2",
+        "vite-plugin-dts": "^5.0.3",
+        "vue": "^3.5.42",
+        "zod": "^4.4.3"
+    }
+}