@acornly/react 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Free Solo
+
+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

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @acornly/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React 18 and 19 bindings for the [Acornly SDK](../sdk): a provider that starts one instance after mount and destroys it on unmount, and hooks that read it. It renders no UI of its own; pass the SDK's `builtInUi` for pins, cards and the toolbar, or draw notes yourself.
+
+```tsx
+<AcornlyProvider
+  config={() => ({ adapter, scope: "app:my-site", user })}
+  deps={async () => ({ ui: (await import("@acornly/sdk/ui")).builtInUi })}
+>
+  <App />
+</AcornlyProvider>
+```
+
+- `useAcornly()` gives `{ status, ctx, error }`, with `status` `"loading"`, `"ready"` or `"error"`.
+- `useNotes(options)` returns `ctx.list(options)` and renders again as notes and anchors change; when the document switches, the old notes go at once and the new ones appear as they are anchored.
+
+`@acornly/sdk` and `react` are peer dependencies. With React Server Components, render the provider from your own `"use client"` component (its props hold functions); the module is marked `"use client"` so importing it from a server module works. Server rendering is safe: `config` and `deps` are read in an effect, so the server renders the loading state and never touches the DOM. Import the built-in UI inside `deps`, as above, since it needs a DOM as soon as it loads. See [React in the getting-started guide](../../docs/getting-started.md#react).

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+import { type ReactElement, type ReactNode } from "react";
+import { Acornly, type AcornlyConfig, type InitDeps, type ListedAnnotation, type ListOptions } from "@acornly/sdk";
+/** The provider's instance: `ctx` is set once `Acornly.init` has loaded the notes. */
+export type AcornlyState = {
+    status: "loading";
+    ctx: null;
+    error: null;
+} | {
+    status: "ready";
+    ctx: Acornly;
+    error: null;
+} | {
+    status: "error";
+    ctx: null;
+    error: unknown;
+};
+export interface AcornlyProviderProps {
+    /**
+     * The SDK config, or a function that returns it (or a promise of it). The provider reads it in
+     * the effect that starts the instance, after its first render in the browser, so a function can
+     * build the adapter there and read refs (`root: mainRef.current`), and on the server it is never
+     * called. Later changes are not picked up: give the provider a new `key` to start over with
+     * another config. The effect runs again, with the first render's values, only when React
+     * remounts it (StrictMode in development, or an `<Activity>` shown again). So `user` must read
+     * live state (the auth client, or a ref kept current), not a value captured at render.
+     */
+    config: AcornlyConfig | (() => AcornlyConfig | Promise<AcornlyConfig>);
+    /**
+     * `init`'s second argument, or a function that returns it (or a promise of it), read with
+     * `config`. The SDK's built-in UI needs a DOM as soon as it is imported, so a page that renders
+     * on the server imports it here: `deps={async () => ({ ui: (await import("@acornly/sdk/ui"))
+     * .builtInUi })}`. A client-only page can pass `{ ui: builtInUi }`.
+     */
+    deps?: InitDeps | (() => InitDeps | Promise<InitDeps>);
+    children?: ReactNode;
+}
+/**
+ * Starts one Acornly instance for the components under it and destroys it on unmount. It
+ * renders only its children: pass the SDK's `builtInUi` in `deps` for its own pins, cards and
+ * toolbar, or leave it out and draw notes with `useNotes`. Nothing touches the DOM during render,
+ * so it is safe in server rendering, where the state stays `loading`.
+ */
+export declare function AcornlyProvider({ config, deps, children }: AcornlyProviderProps): ReactElement;
+/**
+ * The provider's instance and whether it is ready. `ctx` is null while loading, on the server and
+ * when `init` failed (`error` says why); once ready it is the instance, for `add`, `focus`,
+ * `setPlacement` and the rest of the SDK's API.
+ */
+export declare function useAcornly(): AcornlyState;
+/**
+ * The current document's notes, as `ctx.list(options)` returns them, oldest first, and kept up to
+ * date: notes added, edited or removed here or by sync, and anchors found, lost or looked for
+ * again. When the document switches (navigation or `setDocument`) the old document's notes go at
+ * once and the new ones appear as they are anchored. A silent anchor refresh (the SDK re-saving
+ * where a note's text now is) does not render again. Empty until the instance is ready, and on the
+ * server.
+ */
+export declare function useNotes(options?: ListOptions): ListedAnnotation[];
+//# 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":"AAEA,OAAO,EAQL,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EACL,OAAO,EACP,KAAK,aAAa,EAElB,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AAEtB,sFAAsF;AACtF,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GAC7C;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GAC9C;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEnD,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,MAAM,EAAE,aAAa,GAAG,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;IACvE;;;;;OAKG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,CAAC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAwDD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,oBAAoB,GAAG,YAAY,CAqC9F;AAQD;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,YAAY,CAEzC;AAKD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,WAAgB,GAAG,gBAAgB,EAAE,CAsBtE"}

package/dist/index.js

@@ -0,0 +1,137 @@
+"use client";
+import { createContext, createElement, useContext, useEffect, useMemo, useState, useSyncExternalStore, } from "react";
+import { Acornly, } from "@acornly/sdk";
+const LOADING = { status: "loading", ctx: null, error: null };
+const HiveContext = createContext(null);
+HiveContext.displayName = "Acornly";
+/** Everything that can change what `list()` returns. */
+const NOTE_EVENTS = [
+    "annotation:created",
+    "annotation:updated",
+    "annotation:removed",
+    "anchor:resolved",
+    "anchor:orphaned",
+    "anchor:pending",
+    "document:loading",
+    "document:change",
+];
+/**
+ * Counts the instance's note changes, for `useSyncExternalStore`. It listens from the moment the
+ * instance is ready, before any component reads `list()`, so no change falls between a render and
+ * that component's subscription.
+ */
+class NoteVersions {
+    version = 0;
+    listeners = new Set();
+    stops;
+    constructor(ctx) {
+        this.stops = NOTE_EVENTS.map((event) => ctx.on(event, () => {
+            this.version++;
+            for (const fn of [...this.listeners])
+                fn();
+        }));
+    }
+    subscribe = (fn) => {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    };
+    getVersion = () => this.version;
+    stop() {
+        for (const stop of this.stops.splice(0))
+            stop();
+        this.listeners.clear();
+    }
+}
+/**
+ * Starts one Acornly instance for the components under it and destroys it on unmount. It
+ * renders only its children: pass the SDK's `builtInUi` in `deps` for its own pins, cards and
+ * toolbar, or leave it out and draw notes with `useNotes`. Nothing touches the DOM during render,
+ * so it is safe in server rendering, where the state stays `loading`.
+ */
+export function AcornlyProvider({ config, deps, children }) {
+    const [shared, setShared] = useState({ state: LOADING, notes: null });
+    // The first render's config and deps win, as documented, also when React remounts the effect.
+    const [initial] = useState(() => ({ config, deps }));
+    useEffect(() => {
+        const { config, deps } = initial;
+        let cancelled = false;
+        let ctx = null;
+        let notes = null;
+        (async () => {
+            const resolved = typeof config === "function" ? await config() : config;
+            if (cancelled)
+                return;
+            const parts = typeof deps === "function" ? await deps() : deps;
+            if (cancelled)
+                return;
+            const started = await Acornly.init(resolved, parts);
+            if (cancelled) {
+                started.destroy();
+                return;
+            }
+            ctx = started;
+            notes = new NoteVersions(started);
+            setShared({ state: { status: "ready", ctx: started, error: null }, notes });
+        })().catch((error) => {
+            if (!cancelled)
+                setShared({ state: { status: "error", ctx: null, error }, notes: null });
+        });
+        return () => {
+            cancelled = true;
+            notes?.stop();
+            ctx?.destroy();
+            // A remount that keeps state (an <Activity> shown again) starts over from loading, never
+            // with the destroyed instance or the last start's error.
+            setShared((s) => (s.state.status === "loading" ? s : { state: LOADING, notes: null }));
+        };
+    }, [initial]);
+    return createElement(HiveContext.Provider, { value: shared }, children);
+}
+function useShared(hook) {
+    const shared = useContext(HiveContext);
+    if (!shared)
+        throw new Error(`${hook} must be used inside <AcornlyProvider>`);
+    return shared;
+}
+/**
+ * The provider's instance and whether it is ready. `ctx` is null while loading, on the server and
+ * when `init` failed (`error` says why); once ready it is the instance, for `add`, `focus`,
+ * `setPlacement` and the rest of the SDK's API.
+ */
+export function useAcornly() {
+    return useShared("useAcornly").state;
+}
+const noSubscribe = () => () => { };
+const zero = () => 0;
+/**
+ * The current document's notes, as `ctx.list(options)` returns them, oldest first, and kept up to
+ * date: notes added, edited or removed here or by sync, and anchors found, lost or looked for
+ * again. When the document switches (navigation or `setDocument`) the old document's notes go at
+ * once and the new ones appear as they are anchored. A silent anchor refresh (the SDK re-saving
+ * where a note's text now is) does not render again. Empty until the instance is ready, and on the
+ * server.
+ */
+export function useNotes(options = {}) {
+    const { state, notes } = useShared("useNotes");
+    const version = useSyncExternalStore(notes?.subscribe ?? noSubscribe, notes?.getVersion ?? zero, zero);
+    const { ctx } = state;
+    const { motivation, tag } = options;
+    // `version` is not read inside, but it is what changes when the list does.
+    return useMemo(() => {
+        if (!ctx)
+            return [];
+        const filter = {};
+        if (motivation !== undefined)
+            filter.motivation = motivation;
+        if (tag !== undefined)
+            filter.tag = tag;
+        try {
+            return ctx.list(filter);
+        }
+        catch {
+            // Destroyed as the provider unmounts.
+            return [];
+        }
+    }, [ctx, version, motivation, tag]);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@acornly/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "React provider and hooks around the Acornly SDK, for React 18 and 19",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/postagilab/acornly.git",
+    "directory": "packages/react"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "@acornly/sdk": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "@acornly/core": "0.3.0",
+    "@acornly/sdk": "0.3.0",
+    "@acornly/adapter-memory": "0.2.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }