@hollware/vue 0.0.0 → 1.0.0-rc.0

package/README.md

@@ -1,3 +1,80 @@
 # @hollware/vue
 
-Reserved. The Vue integration of [Hollware](https://hollware.com) will be published from https://github.com/hollware/hollware.
+Read [Hollware](https://hollware.com) from a Vue 3 app that is not Nuxt (for Nuxt, use
+`@hollware/nuxt`): `<HollwareContent>` renders an entry's Comark document with your own Vue
+components, on the server and in the browser, and composables read published content from a
+browser-only app. It imports nothing of Cloudflare.
+
+```sh
+npm install @hollware/vue
+```
+
+## A browser-only app (a Vite SPA)
+
+The composables read over HTTP with a **read token** (`hw_read_`, from `hollware token create --read`).
+The token is in the page, so anyone can read it: it can only read published content, and nothing
+else. Hollware accepts it from a page whose origin is in the site's `cors.origins`, so add the
+origin of the app there (`http://localhost:5173` in development).
+
+```ts
+// main.ts
+import { createHollwarePlugin } from '@hollware/vue'
+createApp(App)
+  .use(
+    createHollwarePlugin({ site: 'my-site', url: 'https://cms.example.com', token: 'hw_read_…' }),
+  )
+  .mount('#app')
+```
+
+```vue
+<script setup lang="ts">
+import { HollwareContent, useHollwareEntry } from '@hollware/vue'
+const props = defineProps<{ slug: string }>()
+const { data, error, pending } = useHollwareEntry('blog', 'en', () => props.slug)
+</script>
+<template>
+  <p v-if="pending">Loading…</p>
+  <p v-else-if="error">{{ error.message }}</p>
+  <HollwareContent v-else-if="data" :entry="data" :components="{ callout: Callout }" />
+  <p v-else>Not found</p>
+</template>
+```
+
+| What                                         | Does                                                                                                |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `createHollwarePlugin({ site, url, token })` | The plugin that provides Hollware to the app; `provideHollware(app, options)` is the same           |
+| `useHollwareEntry(collection, locale, slug)` | `{ data, error, pending }` for one published entry; each argument may be a ref or a getter          |
+| `useHollwareEntries(collection, options?)`   | `{ data, error, pending }` for a page of entries, newest first (`locale`, `tag`, `limit`, `cursor`) |
+
+`data` is `undefined` while the first read loads and when the entry is not published (then
+`pending` is `false` and `error` is `undefined`). A read that fails sets `error` and clears `data`.
+When an argument changes, the composable reads again, keeps the previous `data` meanwhile, and
+drops the answer of a read that a newer one replaced.
+
+There is **no preview in the browser**: "Preview on the site" exchanges its link for a cookie that is
+`HttpOnly` on the site's server, so a page in the browser never holds the token. Previews need a
+server that renders the page.
+
+## A server that renders Vue (Vue SSR with Vite, Vike, any server)
+
+The server helpers are the same as `@hollware/react`'s: they are `@hollware/client`'s, re-exported.
+
+```ts
+import { createHollware, previewHeaders, previewRedirect } from '@hollware/vue'
+const hollware = createHollware({ site: 'my-site', url: HOLLWARE_URL, token: HOLLWARE_TOKEN })
+const redirect = previewRedirect(request) // the 303 that exchanges a preview link, or null
+const answer = await hollware.getEntry('blog', 'en', slug, { request }) // { entry, preview } | undefined
+const headers = previewHeaders(request) // `no-store` for a visitor who previews
+```
+
+Render `answer.entry` with `<HollwareContent :entry="answer.entry" />` and send the same entry to the
+browser to hydrate. `createHollware({ site, reader: () => hollwareBinding(env.HOLLWARE) })` reads over
+a Cloudflare service binding instead. See the README of `@hollware/react` for `listEntries`,
+`getTranslations` and the previews in full: they work the same.
+
+## Components
+
+`<HollwareContent :entry :components>` renders the Comark document Hollware stored when the entry
+was written, with `@comark/vue`. `components` maps the names of the components in the entry
+(`::callout` is `callout`) to your own Vue components; an element with no mapping renders as the
+plain tag. The page needs no Markdown parser: the document is already parsed.

package/dist/index.d.mts

@@ -0,0 +1,70 @@
+import { EntryAnswer, EntryPage, EntryPage as EntryPage$1, GetEntryOptions, Hollware, HollwareOptions, HollwareOptions as HollwareOptions$1, HollwareReader, ListEntriesOptions, ListEntriesOptions as ListEntriesOptions$1, PREVIEW_COOKIE, PageDocument, PageEntry, PageEntry as PageEntry$1, PageSummary, ReaderOptions, Translation, createHollware, hollwareBinding, isPreviewRequest, previewCookieClear, previewHeaders, previewRedirect } from "@hollware/client";
+import { App, MaybeRefOrGetter, Plugin, PropType, Ref } from "vue";
+//#region src/content.d.ts
+/**
+ * The body of an entry: the Comark document Hollware stored when it was written, rendered with
+ * `@comark/vue`, imported from its own subpath so no Markdown parser reaches the bundle. It
+ * renders on the server and hydrates in the browser from the same document. `components` maps
+ * the names of the components in the entry (`::callout` is `Callout`) to the site's own Vue
+ * components; an element with no mapping renders as the plain tag.
+ */
+export declare const HollwareContent: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+  /** An entry as `getEntry` or `useHollwareEntry` gives it, with its `document`. */
+  entry: {
+    type: PropType<{
+      readonly document?: unknown;
+    } | null | undefined>;
+    default: null;
+  };
+  components: {
+    type: PropType<Record<string, unknown>>;
+    default: () => {};
+  };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+  [key: string]: any;
+}> | null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+  /** An entry as `getEntry` or `useHollwareEntry` gives it, with its `document`. */
+  entry: {
+    type: PropType<{
+      readonly document?: unknown;
+    } | null | undefined>;
+    default: null;
+  };
+  components: {
+    type: PropType<Record<string, unknown>>;
+    default: () => {};
+  };
+}>> & Readonly<{}>, {
+  entry: {
+    readonly document?: unknown;
+  } | null | undefined;
+  components: Record<string, unknown>;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+//#endregion
+//#region src/composables.d.ts
+/** Makes `app` read Hollware for the composables below. */
+export declare function provideHollware(app: App, options: HollwareOptions$1): void;
+/** `provideHollware` as a plugin: `createApp(App).use(createHollwarePlugin({ site, url, token }))`. */
+export declare function createHollwarePlugin(options: HollwareOptions$1): Plugin;
+/**
+ * What a composable gives: the answer, the error of the last read, and whether a read is under
+ * way. `data` keeps the previous answer while the next one loads, and is `undefined` after an
+ * error.
+ */
+interface HollwareState<T> {
+  readonly data: Readonly<Ref<T | undefined>>;
+  readonly error: Readonly<Ref<Error | undefined>>;
+  readonly pending: Readonly<Ref<boolean>>;
+}
+/**
+ * A published entry with its Comark document, for `<HollwareContent>`. `data` is `undefined`
+ * while it loads and when the entry is not published (`pending` is `false` then, and `error` too).
+ */
+export declare function useHollwareEntry(collection: MaybeRefOrGetter<string>, locale: MaybeRefOrGetter<string>, slug: MaybeRefOrGetter<string>): HollwareState<PageEntry$1>;
+/** A page of the published entries of a collection, newest first. */
+export declare function useHollwareEntries(collection: MaybeRefOrGetter<string>, options?: MaybeRefOrGetter<ListEntriesOptions$1>): HollwareState<EntryPage$1>;
+//#endregion
+//#region src/index.d.ts
+export declare const name = "@hollware/vue";
+//#endregion
+export { type EntryAnswer, type EntryPage, type GetEntryOptions, type Hollware, type HollwareOptions, type HollwareReader, type HollwareState, type ListEntriesOptions, PREVIEW_COOKIE, type PageDocument, type PageEntry, type PageSummary, type ReaderOptions, type Translation, createHollware, hollwareBinding, isPreviewRequest, previewCookieClear, previewHeaders, previewRedirect };

package/dist/index.mjs

@@ -0,0 +1,110 @@
+import { PREVIEW_COOKIE, createHollware, createHollware as createHollware$1, hollwareBinding, isPreviewRequest, previewCookieClear, previewHeaders, previewRedirect } from "@hollware/client";
+import { MarkdownDocument } from "@comark/vue/components/MarkdownDocument";
+import { defineComponent, h, inject, ref, shallowReadonly, shallowRef, toValue, watchEffect } from "vue";
+//#region src/content.ts
+/**
+* The body of an entry: the Comark document Hollware stored when it was written, rendered with
+* `@comark/vue`, imported from its own subpath so no Markdown parser reaches the bundle. It
+* renders on the server and hydrates in the browser from the same document. `components` maps
+* the names of the components in the entry (`::callout` is `Callout`) to the site's own Vue
+* components; an element with no mapping renders as the plain tag.
+*/
+const HollwareContent = defineComponent({
+	name: "HollwareContent",
+	props: {
+		/** An entry as `getEntry` or `useHollwareEntry` gives it, with its `document`. */
+		entry: {
+			type: Object,
+			default: null
+		},
+		components: {
+			type: Object,
+			default: () => ({})
+		}
+	},
+	setup(props) {
+		return () => {
+			const document = props.entry?.document;
+			if (typeof document !== "object" || document === null || !Array.isArray(Reflect.get(document, "nodes"))) return null;
+			return h(MarkdownDocument, {
+				value: document,
+				components: props.components
+			});
+		};
+	}
+});
+//#endregion
+//#region src/composables.ts
+/**
+* Composables for a browser-only Vue app (a Vite SPA). They read published content over HTTP
+* with a read token (`hw_read_`), which the browser holds: Hollware allows it from a page whose
+* origin is in the site's `cors.origins`. A token in a page is public, so it must be a read
+* token, never a personal one. There is no preview here: the preview cookie is `HttpOnly` on the
+* site's server, so a browser never has the token to send. A site that renders on a server reads
+* with `createHollware` there.
+*/
+const HOLLWARE = Symbol("hollware");
+/** Makes `app` read Hollware for the composables below. */
+function provideHollware(app, options) {
+	app.provide(HOLLWARE, createHollware$1(options));
+}
+/** `provideHollware` as a plugin: `createApp(App).use(createHollwarePlugin({ site, url, token }))`. */
+function createHollwarePlugin(options) {
+	return { install: (app) => provideHollware(app, options) };
+}
+function hollwareOf() {
+	const hollware = inject(HOLLWARE, void 0);
+	if (hollware === void 0) throw new Error("Hollware: nothing provides it to this app: add `app.use(createHollwarePlugin({ site, url, token }))`.");
+	return hollware;
+}
+/**
+* Reads again whenever a ref that `read` reads changes, and drops the answer of a read that a
+* newer one has replaced. `read` runs synchronously, so the refs it reads are the ones tracked.
+*/
+function useRead(read) {
+	const hollware = hollwareOf();
+	const data = shallowRef();
+	const error = shallowRef();
+	const pending = ref(true);
+	watchEffect((onCleanup) => {
+		let stale = false;
+		onCleanup(() => {
+			stale = true;
+		});
+		pending.value = true;
+		new Promise((resolve) => resolve(read(hollware))).then((value) => {
+			if (stale) return;
+			data.value = value;
+			error.value = void 0;
+			pending.value = false;
+		}, (cause) => {
+			if (stale) return;
+			data.value = void 0;
+			error.value = cause instanceof Error ? cause : new Error(String(cause));
+			pending.value = false;
+		});
+	});
+	return {
+		data: shallowReadonly(data),
+		error: shallowReadonly(error),
+		pending: shallowReadonly(pending)
+	};
+}
+/**
+* A published entry with its Comark document, for `<HollwareContent>`. `data` is `undefined`
+* while it loads and when the entry is not published (`pending` is `false` then, and `error` too).
+*/
+function useHollwareEntry(collection, locale, slug) {
+	return useRead(async (hollware) => {
+		return (await hollware.getEntry(toValue(collection), toValue(locale), toValue(slug)))?.entry;
+	});
+}
+/** A page of the published entries of a collection, newest first. */
+function useHollwareEntries(collection, options = {}) {
+	return useRead((hollware) => hollware.listEntries(toValue(collection), toValue(options)));
+}
+//#endregion
+//#region src/index.ts
+const name = "@hollware/vue";
+//#endregion
+export { HollwareContent, PREVIEW_COOKIE, createHollware, createHollwarePlugin, hollwareBinding, isPreviewRequest, name, previewCookieClear, previewHeaders, previewRedirect, provideHollware, useHollwareEntries, useHollwareEntry };

package/package.json

@@ -1,13 +1,53 @@
 {
   "name": "@hollware/vue",
-  "version": "0.0.0",
-  "description": "Reserved for Hollware's Vue integration. The first release comes from the hollware/hollware repository.",
+  "version": "1.0.0-rc.0",
+  "description": "Read Hollware from any Vue 3 app that is not Nuxt: a component that renders an entry's Comark document, server helpers, and composables for a browser-only app.",
   "homepage": "https://hollware.com",
+  "bugs": {
+    "url": "https://github.com/hollware/hollware/issues"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/hollware/hollware.git",
     "directory": "packages/vue"
   },
-  "publishConfig": { "access": "public" }
-}
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@comark/vue": "0.7.0",
+    "@hollware/client": "1.0.0-rc.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "publint": "0.3.25",
+    "typescript": "7.0.2",
+    "vite-plus": "1.2.0",
+    "vue": "3.5.44"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "engines": {
+    "node": ">=24.11.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test",
+    "publint": "publint --strict"
+  }
+}