@mapled/react 0.0.1 → 0.1.0

package/README.md

@@ -1,10 +1,221 @@
 # @mapled/react
 
-React helpers for [Mapled](https://mapled.io), the hosted headless CMS for sites built with AI: published content in a React single-page app (Vite and the like).
+React helpers for [Mapled](https://mapled.io), the hosted headless CMS for sites built with AI: published content in a React single-page app — Vite, Create React App, anything that renders in the browser. One provider, three hooks. Built on [`@mapled/client`](https://www.npmjs.com/package/@mapled/client); a Next.js site uses [`@mapled/next`](https://www.npmjs.com/package/@mapled/next) instead.
 
-**This version holds no code yet.** 0.0.1 exists so that the releases that follow can be published from CI; the first release is 0.1.0.
+## Install
 
-Until then:
+```bash
+npm install @mapled/react
+```
 
-- a Next.js site uses [`@mapled/next`](https://www.npmjs.com/package/@mapled/next);
-- any other site reads the Delivery API over HTTP — «Without Next.js: the HTTP API» in the [`@mapled/next` README](https://www.npmjs.com/package/@mapled/next).
+`@mapled/client` comes with it. Put the project's **delivery key** (Mapled: Integrations → Your site) in `.env`:
+
+```bash
+VITE_MAPLED_KEY=mk_live_…
+```
+
+It is bundled into the page, which is fine for this key and for no other: it reads published content only. A server key or a webhook signing secret never goes under a `VITE_` name.
+
+## Wire it up
+
+```tsx
+// src/mapled.ts
+import { createClient } from "@mapled/client";
+import { typedHooks } from "@mapled/react";
+import type { MapledSchema } from "./mapled-types";
+
+export const mapled = createClient<MapledSchema>({ key: import.meta.env.VITE_MAPLED_KEY });
+export const { useSingle, useRecords, useRecord } = typedHooks<MapledSchema>();
+```
+
+```tsx
+// src/main.tsx
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { MapledProvider } from "@mapled/react";
+import { mapled } from "./mapled";
+import { App } from "./App";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <MapledProvider client={mapled}>
+      <App />
+    </MapledProvider>
+  </StrictMode>,
+);
+```
+
+`mapled-types.ts` is written by `npx @mapled/cli types generate`; with `typedHooks<MapledSchema>()` keys are checked and `data` has each collection's own type. Without types, import `useSingle`, `useRecords` and `useRecord` straight from `@mapled/react`.
+
+## Read content
+
+Every hook answers `{ data, loading, error, refetch }`.
+
+```tsx
+// src/pages/Home.tsx
+import Markdown from "react-markdown";
+import { assetUrl } from "@mapled/client";
+import { useSingle } from "../mapled";
+
+export function Home() {
+  const { data: home, loading, error } = useSingle("homepage");
+  if (loading) return <p>Loading…</p>;
+  if (error || !home) return <p>Nothing here yet.</p>;
+  return (
+    <main>
+      <h1>{home.data.headline}</h1>
+      {home.data.hero ? <img src={assetUrl(home.data.hero, { width: 1200 })} alt="" /> : null}
+      <Markdown>{home.data.intro ?? ""}</Markdown>
+    </main>
+  );
+}
+```
+
+```tsx
+// src/pages/Blog.tsx
+import { Link } from "react-router-dom";
+import { useRecords } from "../mapled";
+
+export function Blog() {
+  const { data, loading } = useRecords("posts", { sort: "-date", limit: 20, fields: ["title", "slug", "date"] });
+  if (loading && !data) return <p>Loading…</p>;
+  return (
+    <ul>
+      {data?.records.map((post) => (
+        <li key={post.id}>
+          <Link to={`/blog/${post.data.slug}`}>{post.data.title}</Link>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+```tsx
+// src/pages/Post.tsx
+import Markdown from "react-markdown";
+import { useParams } from "react-router-dom";
+import { useRecord } from "../mapled";
+
+export function Post() {
+  const { slug } = useParams();
+  const { data: post, loading } = useRecord("posts", slug ? { slug } : null);
+  if (loading) return <p>Loading…</p>;
+  if (!post) return <p>This post doesn't exist.</p>;
+  return (
+    <article>
+      <h1>{post.data.title}</h1>
+      <Markdown>{post.data.body}</Markdown>
+    </article>
+  );
+}
+```
+
+- `useSingle(key, options?)` — `data` is the single's record, or `null` while it is empty.
+- `useRecords(collection, options?)` — `data` is `{ records, total, release }`; options are the client's: `filter`, `sort`, `limit`, `offset`, `fields`, `expand`.
+- `useRecord(collection, { slug } | { id } | null, options?)` — `data` is `null` when the record isn't published; `null` instead of a reference reads nothing (a router param that hasn't arrived).
+- Components that ask for the same thing share one request; an inline options object is the same read on every render.
+- Rich text values are Markdown — render them with a Markdown component, never as raw HTML.
+- `useMapled()` hands out the client for a read the hooks don't cover.
+
+## Preview
+
+Nothing to add: when someone opens **Preview** in Mapled, the page opens with a one-time token in its address, the client trades it for a draft session, and the hooks show drafts in that tab. Say so on the page:
+
+```tsx
+// src/PreviewBar.tsx
+import { usePreview } from "@mapled/react";
+
+export function PreviewBar() {
+  const preview = usePreview();
+  if (!preview.active) return null;
+  return (
+    <p role="status">
+      You are looking at a preview. <button onClick={preview.exit}>Back to the published site</button>
+    </p>
+  );
+}
+```
+
+Mapled has to know where the site lives and that it renders in the browser: the site manifest's `framework` is `"react-spa"` (`npx @mapled/cli scan --write`, `bindings push` — or your AI agent's `push_site_manifest`), and **Production domain** in Project settings holds the site's public address (an agent sets it with `set_site_url`). There is no webhook to configure and no route to mount.
+
+## Live updates
+
+A publish shows when the page is loaded again. To follow it while the page is open:
+
+```tsx
+// src/LiveApp.tsx
+import { MapledProvider } from "@mapled/react";
+import { mapled } from "./mapled";
+import { App } from "./App";
+
+export function LiveApp() {
+  return (
+    <MapledProvider client={mapled} live>
+      <App />
+    </MapledProvider>
+  );
+}
+```
+
+Each open tab then asks Mapled for the release pointer once a minute (`live={{ interval: 30 }}` for thirty seconds, never under fifteen) while it is visible, and the hooks read again — pinned to the new release — when it moves; what was on screen stays there until the new answer arrives. It is off by default because every check is a request of the delivery key's budget (1,200 a minute).
+
+## Forms
+
+`submitForm` from `@mapled/client` posts a visitor's submission:
+
+```tsx
+// src/ContactForm.tsx
+import { useState, type FormEvent } from "react";
+import { submitForm } from "@mapled/client";
+
+const CONSENT = "I agree to be contacted about my request.";
+
+export function ContactForm() {
+  const [state, setState] = useState<"idle" | "sending" | "sent" | "failed">("idle");
+
+  async function submit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const form = event.currentTarget;
+    setState("sending");
+    const answer = await submitForm("contact", form, {
+      key: import.meta.env.VITE_MAPLED_KEY,
+      consent: new FormData(form).get("consent") ? CONSENT : undefined,
+    });
+    setState(answer.ok ? "sent" : "failed");
+  }
+
+  if (state === "sent") return <p>Thank you — we'll be in touch.</p>;
+  return (
+    <form onSubmit={submit}>
+      <input name="name" required />
+      <input name="email" type="email" required />
+      <textarea name="message" required />
+      <input name="_gotcha" tabIndex={-1} autoComplete="off" aria-hidden="true" style={{ display: "none" }} />
+      <label>
+        <input name="consent" type="checkbox" required /> {CONSENT}
+      </label>
+      <button disabled={state === "sending"}>Send</button>
+      {state === "failed" ? <p>That didn't go through. Try again in a minute.</p> : null}
+    </form>
+  );
+}
+```
+
+## Check the integration
+
+```bash
+npx @mapled/cli doctor
+```
+
+doctor knows a single-page app: it wants `VITE_MAPLED_KEY` and no webhook secret, reads ○ «Not needed» for the webhook and the routes, and fails an env file that puts a server key or a signing secret under a public prefix.
+
+## API
+
+| Export | |
+| --- | --- |
+| `MapledProvider` | `client`, `live?` (`true` or `{ interval }`) |
+| `useSingle`, `useRecords`, `useRecord` | `{ data, loading, error, refetch }` |
+| `typedHooks<MapledSchema>()` | The same three hooks, typed by the generated schema |
+| `usePreview()` | `{ active, exit }` |
+| `useMapled()` | The provider's client |

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+/** React helpers for Mapled: published content in a React single-page
+    app. One provider holds the client; the hooks read through it, share
+    a read between the components that ask for the same thing, show
+    drafts when the page was opened from Mapled's Preview, and — with
+    `live` — follow a publish while the page is open. The reads, the
+    preview link and the release watch are "@mapled/client"'s. */
+import { type ReactNode } from "react";
+import { type ContentSchema, type ListOptions, type ListResult, type MapledClient, type MapledRecord, type ReadOptions } from "@mapled/client";
+/** What a hook answers: `data` is null until the first answer (and for
+    a record that isn't published). When the same read is asked again —
+    `refetch`, a publish the page heard — the previous answer stays in
+    `data` until the next one arrives. */
+export type ReadState<T> = {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+    /** Ask again, past anything the page remembers. */
+    refetch: () => void;
+};
+type Entry = {
+    status: "loading" | "done" | "error";
+    data?: unknown;
+    error?: Error;
+};
+/** Reads by key: one request however many components ask, the answer
+    kept for the ones that mount later. */
+declare class ReadStore {
+    private entries;
+    private listeners;
+    private generation;
+    get(key: string): Entry | undefined;
+    subscribe(key: string, listener: () => void): () => void;
+    private set;
+    /** Starts the read unless it is known or on its way; `force` asks again. */
+    ensure(key: string, read: () => Promise<unknown>, force?: boolean): void;
+}
+type Live = boolean | {
+    interval?: number;
+};
+type ContextValue = {
+    client: MapledClient;
+    store: ReadStore;
+    /** the release the page follows once a publish was heard; undefined = the latest */
+    release: number | undefined;
+    /** null until the client has looked for a preview link: nothing is read
+        before that, so a preview never starts with published content */
+    preview: boolean | null;
+};
+export type MapledProviderProps = {
+    /** `createClient({ key })` from "@mapled/client" — make it once, outside the component. */
+    client: MapledClient<any>;
+    /** Follow publishes while the page is open: Mapled is asked for the
+        release pointer — once a minute by default, only in a visible tab —
+        and the hooks read again when it moves. Off by default: every check
+        is a request of the delivery key's budget. */
+    live?: Live;
+    children?: ReactNode;
+};
+export declare function MapledProvider({ client, live, children }: MapledProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<ContextValue | null>>;
+/** The client the provider holds — for a read the hooks don't cover. */
+export declare function useMapled<S extends ContentSchema = ContentSchema>(): MapledClient<S>;
+/** Whether the page shows drafts (it was opened from Mapled's Preview),
+    and the way out: back to published content, read again. */
+export declare function usePreview(): {
+    active: boolean;
+    exit: () => void;
+};
+type Data = Record<string, unknown>;
+type HookReadOptions = Omit<ReadOptions, "signal" | "release">;
+type HookListOptions = Omit<ListOptions, "signal" | "release">;
+/** How one record is named: by the collection's slug field, or by id.
+    Null (no slug in the address yet) reads nothing. */
+export type RecordRef = {
+    slug: string;
+} | {
+    id: string;
+} | null | undefined;
+/** A single — "homepage", "settings". `data` is its record, or null while it is empty. */
+export declare function useSingle<T = Data>(key: string, options?: HookReadOptions): ReadState<MapledRecord<T>>;
+/** Published records of a collection: `data` is `{ records, total, release }`. */
+export declare function useRecords<T = Data>(collection: string, options?: HookListOptions): ReadState<ListResult<T>>;
+/** One record, by `{ slug }` or `{ id }`; `data` is null when it isn't published. */
+export declare function useRecord<T = Data>(collection: string, ref: RecordRef, options?: HookReadOptions): ReadState<MapledRecord<T>>;
+type CollectionsOf<S extends ContentSchema> = S["collections"] extends object ? S["collections"] : Record<string, Data>;
+type SinglesOf<S extends ContentSchema> = S["singles"] extends object ? S["singles"] : Record<string, Data>;
+/** The same hooks, typed by the `MapledSchema` that `mapled types
+    generate` writes: `export const { useSingle, useRecords, useRecord } =
+    typedHooks<MapledSchema>()` — keys are checked, `data` has the
+    collection's own type. */
+export declare function typedHooks<S extends ContentSchema>(): {
+    useSingle: <K extends keyof SinglesOf<S> & string>(key: K, options?: HookReadOptions) => ReadState<MapledRecord<SinglesOf<S>[K]>>;
+    useRecords: <K extends keyof CollectionsOf<S> & string>(collection: K, options?: HookListOptions) => ReadState<ListResult<CollectionsOf<S>[K]>>;
+    useRecord: <K extends keyof CollectionsOf<S> & string>(collection: K, ref: RecordRef, options?: HookReadOptions) => ReadState<MapledRecord<CollectionsOf<S>[K]>>;
+};
+export {};

package/dist/index.js

@@ -0,0 +1,167 @@
+"use client";
+/** React helpers for Mapled: published content in a React single-page
+    app. One provider holds the client; the hooks read through it, share
+    a read between the components that ask for the same thing, show
+    drafts when the page was opened from Mapled's Preview, and — with
+    `live` — follow a publish while the page is open. The reads, the
+    preview link and the release watch are "@mapled/client"'s. */
+import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { endPreview } from "@mapled/client";
+const MAX_ENTRIES = 300;
+const LOADING = { status: "loading" };
+/** Reads by key: one request however many components ask, the answer
+    kept for the ones that mount later. */
+class ReadStore {
+    entries = new Map();
+    listeners = new Map();
+    generation = new Map();
+    get(key) {
+        return this.entries.get(key);
+    }
+    subscribe(key, listener) {
+        let set = this.listeners.get(key);
+        if (!set)
+            this.listeners.set(key, (set = new Set()));
+        set.add(listener);
+        return () => {
+            set.delete(listener);
+            if (set.size === 0)
+                this.listeners.delete(key);
+        };
+    }
+    set(key, entry) {
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        if (this.entries.size > MAX_ENTRIES) {
+            // oldest first, never one a mounted component is looking at
+            for (const old of this.entries.keys()) {
+                if (this.entries.size <= MAX_ENTRIES)
+                    break;
+                if (!this.listeners.has(old))
+                    this.entries.delete(old);
+            }
+        }
+        for (const listener of this.listeners.get(key) ?? [])
+            listener();
+    }
+    /** Starts the read unless it is known or on its way; `force` asks again. */
+    ensure(key, read, force = false) {
+        const known = this.entries.get(key);
+        if (known && !force)
+            return;
+        const mine = (this.generation.get(key) ?? 0) + 1;
+        this.generation.set(key, mine);
+        // a forced read keeps showing what it had
+        this.set(key, known && force ? { ...known, status: "loading" } : LOADING);
+        read().then((data) => {
+            if (this.generation.get(key) === mine)
+                this.set(key, { status: "done", data });
+        }, (error) => {
+            if (this.generation.get(key) === mine) {
+                this.set(key, { status: "error", error: error instanceof Error ? error : new Error(String(error)) });
+            }
+        });
+    }
+}
+const MapledContext = createContext(null);
+export function MapledProvider({ client, live = false, children }) {
+    const store = useMemo(() => new ReadStore(), [client]);
+    const [release, setRelease] = useState(undefined);
+    const [preview, setPreview] = useState(null);
+    useEffect(() => {
+        let mounted = true;
+        setRelease(undefined);
+        setPreview(null);
+        client.isPreview().then((on) => mounted && setPreview(on), () => mounted && setPreview(false));
+        return () => {
+            mounted = false;
+        };
+    }, [client]);
+    const interval = typeof live === "object" ? live.interval : undefined;
+    const watching = Boolean(live) && preview === false;
+    useEffect(() => {
+        // drafts have no releases to follow
+        if (!watching)
+            return;
+        return client.watch((next) => setRelease(next.release), { interval });
+    }, [client, watching, interval]);
+    const value = useMemo(() => ({ client, store, release, preview }), [client, store, release, preview]);
+    return createElement(MapledContext.Provider, { value }, children);
+}
+function useMapledContext() {
+    const value = useContext(MapledContext);
+    if (!value)
+        throw new Error("Mapled: wrap the app in <MapledProvider client={…}> before using its hooks.");
+    return value;
+}
+/** The client the provider holds — for a read the hooks don't cover. */
+export function useMapled() {
+    return useMapledContext().client;
+}
+/** Whether the page shows drafts (it was opened from Mapled's Preview),
+    and the way out: back to published content, read again. */
+export function usePreview() {
+    const preview = useMapledContext().preview === true;
+    const exit = useCallback(() => {
+        endPreview();
+        if (typeof window !== "undefined")
+            window.location.reload();
+    }, []);
+    return { active: preview, exit };
+}
+const noop = () => { };
+function useRead(id, read) {
+    const { store, release, preview } = useMapledContext();
+    // drafts are unversioned; a followed release is part of what is asked
+    const pin = preview ? undefined : release;
+    const key = id === null || preview === null ? null : `${preview ? "draft" : (pin ?? "latest")}|${id}`;
+    const readRef = useRef(read);
+    readRef.current = read;
+    const entry = useSyncExternalStore(useCallback((listener) => (key === null ? noop : store.subscribe(key, listener)), [store, key]), () => (key === null ? undefined : store.get(key)), () => undefined);
+    useEffect(() => {
+        if (key !== null)
+            store.ensure(key, () => readRef.current(pin === undefined ? {} : { release: pin }));
+    }, [store, key, pin]);
+    const refetch = useCallback(() => {
+        if (key !== null)
+            store.ensure(key, () => readRef.current(pin === undefined ? {} : { release: pin }), true);
+    }, [store, key, pin]);
+    // the same read under a new release (a publish was heard) or asked again:
+    // what was on screen stays there until the next answer. Another read —
+    // another slug, other options — starts from nothing.
+    const last = useRef(null);
+    if (id !== null && entry?.status === "done")
+        last.current = { id, data: (entry.data ?? null) };
+    return {
+        data: entry?.status === "done" ? (entry.data ?? null) : last.current?.id === id ? last.current.data : null,
+        loading: id !== null && (key === null || !entry || entry.status === "loading"),
+        error: entry?.status === "error" ? (entry.error ?? null) : null,
+        refetch,
+    };
+}
+/** A single — "homepage", "settings". `data` is its record, or null while it is empty. */
+export function useSingle(key, options = {}) {
+    const { client } = useMapledContext();
+    return useRead(`single|${key}|${JSON.stringify(options)}`, (pin) => client.getSingle(key, { ...options, ...pin }));
+}
+/** Published records of a collection: `data` is `{ records, total, release }`. */
+export function useRecords(collection, options = {}) {
+    const { client } = useMapledContext();
+    return useRead(`records|${collection}|${JSON.stringify(options)}`, (pin) => client.getRecords(collection, { ...options, ...pin }));
+}
+/** One record, by `{ slug }` or `{ id }`; `data` is null when it isn't published. */
+export function useRecord(collection, ref, options = {}) {
+    const { client } = useMapledContext();
+    const by = !ref ? null : "slug" in ref ? (ref.slug ? `slug:${ref.slug}` : null) : ref.id ? `id:${ref.id}` : null;
+    return useRead(by === null ? null : `record|${collection}|${by}|${JSON.stringify(options)}`, (pin) => {
+        const opts = { ...options, ...pin };
+        return (ref && "slug" in ref ? client.getRecordBySlug(collection, ref.slug, opts) : client.getRecord(collection, ref.id, opts));
+    });
+}
+/** The same hooks, typed by the `MapledSchema` that `mapled types
+    generate` writes: `export const { useSingle, useRecords, useRecord } =
+    typedHooks<MapledSchema>()` — keys are checked, `data` has the
+    collection's own type. */
+export function typedHooks() {
+    return { useSingle, useRecords, useRecord };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mapled/react",
-  "version": "0.0.1",
-  "description": "React helpers for Mapled, the hosted headless CMS for sites built with AI — published content in a React single-page app. 0.0.1 holds no code yet; 0.1.0 is the first release.",
+  "version": "0.1.0",
+  "description": "React helpers for Mapled — published content in a React single-page app (Vite and the like): a provider and hooks over @mapled/client, with preview and publish notifications.",
   "license": "MIT",
   "homepage": "https://mapled.io",
   "keywords": [
@@ -9,6 +9,7 @@
     "cms",
     "headless-cms",
     "react",
+    "hooks",
     "spa",
     "vite"
   ],
@@ -26,7 +27,7 @@
     }
   },
   "files": [
-    "README.md"
+    "dist"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -35,7 +36,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@mapled/client": "^0.0.1"
+    "@mapled/client": "^0.1.0"
   },
   "peerDependencies": {
     "react": ">=18"