@localess/react 3.0.1-dev.20260408183951 → 3.0.1-dev.20260410070330

package/README.md

@@ -34,6 +34,51 @@ pnpm add @localess/react
 
 ---
 
+## Choosing the Right Export
+
+`@localess/react` provides three different exports to suit different rendering strategies:
+
+| Export | Use Case | Live Editing | Static Export |
+|---|---|---|---|
+| `@localess/react` | Single Page Applications (SPA), client-side rendering | ✅ | ✅ |
+| `@localess/react/ssr` | SSR without live editing, Next.js static exports | ❌ | ✅ |
+| `@localess/react/rsc` | React Server Components with live editing | ✅ | ❌ |
+
+### When to Use Each Export
+
+**Use `@localess/react`** (default) for:
+- Single Page Applications (SPA) or fully client-rendered React apps
+- Apps where `localessInit` and components run entirely in the browser
+
+**Use `@localess/react/ssr`** for:
+- Next.js projects with `output: 'export'` (static site generation)
+- Server-side rendering where live editing is not required
+- Scenarios where bundle size matters and you want to exclude all browser-only sync code
+
+**Use `@localess/react/rsc`** for:
+- Next.js App Router with React Server Components
+- Apps that need live Visual Editor editing alongside server rendering
+- Modern Next.js apps with a server/client component split
+
+### Quick Comparison
+
+```ts
+// SPA — everything runs client-side
+import { localessInit, LocalessComponent, useLocaless } from "@localess/react";
+
+// SSR — server-safe, no live editing, no hooks
+import { localessInit, LocalessComponent } from "@localess/react/ssr";
+
+// RSC — server components + client components for live editing
+import { localessInit, LocalessComponent } from "@localess/react/rsc";          // server
+import { LocalessDocument, useLocaless, localessEditable } from "@localess/react/rsc"; // client
+```
+
+> [!NOTE]
+> When using Next.js with `output: 'export'`, always use `@localess/react/ssr`. The RSC export is not compatible with static exports.
+
+---
+
 ## Getting Started
 
 ### 1. Initialize the SDK
@@ -421,9 +466,9 @@ export function PageClient({ initialContent }: { initialContent: Content<Page> }
 
 ---
 
-## Full Example (Next.js 16.2 App Router)
+## Full Example — SPA / Default (`@localess/react`)
 
-The recommended Next.js pattern is to **preload data server-side** and pass it to the Client Component. This avoids a loading flash — the page renders immediately with server data, then Visual Editor sync kicks in if active.
+For SPAs or fully client-rendered React apps. All imports use the default `@localess/react` export.
 
 ### Setup — `app/layout.tsx`
 
@@ -570,15 +615,152 @@ export function PageClientManual({
 
 ---
 
-## Re-exported from `@localess/client`
+## Full Example — Next.js Static Export (`@localess/react/ssr`)
+
+Use `@localess/react/ssr` when your Next.js project uses `output: 'export'` for static site generation. Live editing is not available in this mode.
+
+### `next.config.js`
+
+```js
+/** @type {import('next').NextConfig} */
+module.exports = { output: 'export' };
+```
+
+### Setup — `lib/localess.ts`
+
+```ts
+import { localessInit } from "@localess/react/ssr";
+import { Page, Header, Teaser } from "@/components";
+
+export const getClient = localessInit({
+  origin: process.env.LOCALESS_ORIGIN!,
+  spaceId: process.env.LOCALESS_SPACE_ID!,
+  token: process.env.LOCALESS_TOKEN!,
+  // enableSync is not applicable in static export — omit or set to false
+  components: { Page, Header, Teaser },
+});
+```
+
+### Page — `app/page.tsx`
+
+```tsx
+import { LocalessComponent } from "@localess/react/ssr";
+import { getLocalessClient } from "@localess/react/ssr";
+import "@/lib/localess"; // ensure init runs
+
+export default async function Home() {
+  const client = getLocalessClient();
+  const content = await client.getContentBySlug("home", { locale: "en" });
+  return (
+    <main>
+      <LocalessComponent data={content.data} links={content.links} references={content.references} />
+    </main>
+  );
+}
+```
+
+---
+
+## Full Example — Next.js App Router with RSC (`@localess/react/rsc`)
+
+Use `@localess/react/rsc` when you want React Server Components and Visual Editor live editing together.
+
+### Setup — `app/layout.tsx`
+
+```tsx
+// Server Component — safe to use API token here
+import { localessInit } from "@localess/react/rsc";
+import { Page, Header, Teaser, Footer } from "@/components";
+
+localessInit({
+  origin: process.env.LOCALESS_ORIGIN!,
+  spaceId: process.env.LOCALESS_SPACE_ID!,
+  token: process.env.LOCALESS_TOKEN!,
+  enableSync: process.env.NODE_ENV !== 'production',
+  components: { Page, Header, Teaser, Footer },
+});
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return <html><body>{children}</body></html>;
+}
+```
+
+### Server Component — `app/[locale]/page.tsx`
+
+```tsx
+import { getLocalessClient } from "@localess/react/rsc";
+import PageClient from "./page-client";
+
+export default async function Home({ params }: { params: { locale: string } }) {
+  const { locale } = await params;
+  const content = await getLocalessClient().getContentBySlug("home", { locale });
+  return <PageClient initialContent={content} locale={locale} />;
+}
+```
+
+### Client Component — `app/[locale]/page-client.tsx`
 
-The following are re-exported for convenience so you only need to import from `@localess/react`:
+Use `LocalessDocument` for a zero-boilerplate live-editing integration, or `useLocaless` for more control:
 
-**Types:** `Content`, `ContentData`, `ContentMetadata`, `ContentDataSchema`, `ContentDataField`, `ContentAsset`, `ContentRichText`, `ContentLink`, `ContentReference`, `Links`, `References`, `Translations`, `LocalessClient`, `LocalessSync`, `EventToApp`, `EventCallback`, `EventToAppType`
+**Option A — `LocalessDocument` (recommended):**
 
-**Functions:** `localessEditable`, `localessEditableField`, `llEditable` *(deprecated)*, `llEditableField` *(deprecated)*, `isBrowser`, `isServer`, `isIframe`, `resolveAsset`, `findLink`, `useLocaless`, `renderRichTextToReact`, `localessInit`, `getLocalessClient`, `registerComponent`, `unregisterComponent`, `setComponents`, `getComponent`, `setFallbackComponent`, `getFallbackComponent`, `isSyncEnabled`
+```tsx
+'use client';
+import { LocalessDocument } from "@localess/react/rsc";
+
+export default function PageClient({ initialContent }) {
+  return (
+    <LocalessDocument
+      data={initialContent.data}
+      links={initialContent.links}
+      references={initialContent.references}
+    />
+  );
+}
+```
+
+**Option B — `useLocaless` hook:**
+
+```tsx
+'use client';
+import { useLocaless, LocalessComponent, localessEditable } from "@localess/react/rsc";
+
+export default function PageClient({ initialContent, locale }) {
+  const content = useLocaless("home", { locale }) ?? initialContent;
+  return (
+    <main {...localessEditable(content.data)}>
+      {content.data?.body?.map(item => (
+        <LocalessComponent key={item._id} data={item} links={content.links} references={content.references} />
+      ))}
+    </main>
+  );
+}
+```
+
+---
 
-**Components:** `LocalessComponent`, `LocalessDocument`
+## Export Reference
+
+The table below shows which symbols are available in each export.
+
+| Symbol | `@localess/react` | `@localess/react/ssr` | `@localess/react/rsc` |
+|---|:---:|:---:|:---:|
+| `localessInit` | ✅ | ✅ | ✅ |
+| `getLocalessClient` | ✅ | ✅ | ✅ |
+| `registerComponent` / `setComponents` / `getComponent` | ✅ | ✅ | ✅ |
+| `setFallbackComponent` / `getFallbackComponent` | ✅ | ✅ | ✅ |
+| `resolveAsset` | ✅ | ✅ | ✅ |
+| `LocalessComponent` | ✅ | ✅ | ✅ |
+| `renderRichTextToReact` | ✅ | ✅ | ✅ |
+| `findLink` | ✅ | ✅ | ✅ |
+| `isServer` | ✅ | ✅ | ✅ |
+| All content types | ✅ | ✅ | ✅ |
+| `LocalessDocument` | ✅ | ❌ | ✅ |
+| `useLocaless` | ✅ | ❌ | ✅ |
+| `localessEditable` / `localessEditableField` | ✅ | ❌ | ✅ |
+| `isBrowser` / `isIframe` | ✅ | ❌ | ✅ |
+| `isSyncEnabled` | ✅ | ❌ | ✅ |
+| Sync event types (`LocalessSync`, `EventToApp`, …) | ✅ | ❌ | ✅ |
 
 ---
 

package/dist/chunk-AJP75NRT.mjs

@@ -0,0 +1,56 @@
+import {
+  FONT_BOLD,
+  FONT_NORMAL,
+  getComponent,
+  getFallbackComponent
+} from "./chunk-ETSLIILF.mjs";
+
+// src/ssr/localess-component.tsx
+import { forwardRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+var LocalessServerComponent = forwardRef(({ data, links, references, ...restProps }, ref) => {
+  if (!data) {
+    console.error("LocalessServerComponent property %cdata%c is not provided.", FONT_BOLD, FONT_NORMAL);
+    return /* @__PURE__ */ jsxs("div", { children: [
+      "LocalessServerComponent property ",
+      /* @__PURE__ */ jsx("b", { children: "data" }),
+      " is not provided."
+    ] });
+  }
+  const Comp = getComponent(data._schema);
+  if (Comp) {
+    return /* @__PURE__ */ jsx(Comp, { ref, data, links, references, ...restProps });
+  }
+  const FallbackComponent = getFallbackComponent();
+  if (FallbackComponent) {
+    return /* @__PURE__ */ jsx(FallbackComponent, { ref, data, links, references, ...restProps });
+  }
+  return /* @__PURE__ */ jsxs("p", { children: [
+    /* @__PURE__ */ jsx("b", { children: "LocalessServerComponent" }),
+    " could not found component with key ",
+    /* @__PURE__ */ jsx("b", { children: data._schema }),
+    ". ",
+    /* @__PURE__ */ jsx("br", {}),
+    "Please check if your configuration is correct."
+  ] });
+});
+
+// src/ssr/localess-document.tsx
+import { forwardRef as forwardRef2 } from "react";
+import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+var LocalessServerDocument = forwardRef2(({ document }, ref) => {
+  if (!document || !document.data) {
+    console.error("LocalessServerDocument property %cdocument.data%c is not provided.", FONT_BOLD, FONT_NORMAL);
+    return /* @__PURE__ */ jsxs2("div", { children: [
+      "LocalessServerDocument property ",
+      /* @__PURE__ */ jsx2("b", { children: "document.data" }),
+      " is not provided."
+    ] });
+  }
+  return /* @__PURE__ */ jsx2(LocalessServerComponent, { ref, data: document.data, links: document.links, references: document.references });
+});
+
+export {
+  LocalessServerComponent,
+  LocalessServerDocument
+};

package/dist/chunk-ETSLIILF.mjs

@@ -0,0 +1,149 @@
+// src/core/state.ts
+import { loadLocalessSync, localessClient } from "@localess/client";
+
+// src/console.ts
+var FONT_BOLD = "font-weight: bold";
+var FONT_NORMAL = "font-weight: normal";
+
+// src/core/state.ts
+var _client = void 0;
+var _components = {};
+var _fallbackComponent = void 0;
+var _enableSync = false;
+var _assetPathPrefix = "";
+function localessInit(options) {
+  console.log("localessInit", options);
+  const { components, fallbackComponent, enableSync, ...restOptions } = options;
+  _client = localessClient(restOptions);
+  _assetPathPrefix = `${options.origin}/api/v1/spaces/${options.spaceId}/assets/`;
+  _components = components || {};
+  _fallbackComponent = fallbackComponent;
+  if (enableSync) {
+    _enableSync = true;
+    loadLocalessSync(restOptions.origin);
+  }
+  return _client;
+}
+function getLocalessClient() {
+  if (!_client) {
+    console.error("[Localess] No client found. Please check if the Localess is initialized.");
+    throw new Error("[Localess] No client found.");
+  }
+  return _client;
+}
+function registerComponent(key, component) {
+  _components[key] = component;
+}
+function unregisterComponent(key) {
+  delete _components[key];
+}
+function setComponents(components) {
+  _components = components;
+}
+function getComponent(key) {
+  if (Object.hasOwn(_components, key)) {
+    return _components[key];
+  }
+  console.error(`[Localess] component %c${key}%c can't be found.`, FONT_BOLD, FONT_NORMAL);
+  return void 0;
+}
+function setFallbackComponent(fallbackComponent) {
+  _fallbackComponent = fallbackComponent;
+}
+function getFallbackComponent() {
+  return _fallbackComponent;
+}
+function isSyncEnabled() {
+  return _enableSync;
+}
+function resolveAsset(asset) {
+  return `${_assetPathPrefix}${asset.uri}`;
+}
+
+// src/core/utils/link.util.ts
+function findLink(links, link) {
+  switch (link.type) {
+    case "content": {
+      if (links) {
+        const path = links[link.uri];
+        if (path) {
+          return "/" + path.fullSlug;
+        } else {
+          return "/not-found";
+        }
+      }
+      return "/not-found";
+    }
+    case "url":
+      return link.uri;
+    default:
+      return "no-type";
+  }
+}
+
+// src/core/utils/index.ts
+import { localessEditable, localessEditableField, isBrowser, isServer, isIframe } from "@localess/client";
+
+// src/core/richtext.ts
+import { renderToReactElement } from "@tiptap/static-renderer/pm/react";
+import { Document } from "@tiptap/extension-document";
+import { Text } from "@tiptap/extension-text";
+import { Paragraph } from "@tiptap/extension-paragraph";
+import { Heading } from "@tiptap/extension-heading";
+import { Bold } from "@tiptap/extension-bold";
+import { Italic } from "@tiptap/extension-italic";
+import { Strike } from "@tiptap/extension-strike";
+import { Underline } from "@tiptap/extension-underline";
+import { History } from "@tiptap/extension-history";
+import { ListItem } from "@tiptap/extension-list-item";
+import { OrderedList } from "@tiptap/extension-ordered-list";
+import { BulletList } from "@tiptap/extension-bullet-list";
+import { Code } from "@tiptap/extension-code";
+import { CodeBlockLowlight } from "@tiptap/extension-code-block-lowlight";
+import { Link } from "@tiptap/extension-link";
+function renderRichTextToReact(content) {
+  return renderToReactElement({
+    content,
+    extensions: [
+      Document,
+      Text,
+      Paragraph,
+      Heading.configure({
+        levels: [1, 2, 3, 4, 5, 6]
+      }),
+      Bold,
+      Italic,
+      Strike,
+      Underline,
+      History,
+      ListItem,
+      OrderedList,
+      BulletList,
+      Code,
+      CodeBlockLowlight,
+      Link
+    ]
+  });
+}
+
+export {
+  FONT_BOLD,
+  FONT_NORMAL,
+  localessInit,
+  getLocalessClient,
+  registerComponent,
+  unregisterComponent,
+  setComponents,
+  getComponent,
+  setFallbackComponent,
+  getFallbackComponent,
+  isSyncEnabled,
+  resolveAsset,
+  findLink,
+  localessEditable,
+  localessEditableField,
+  isBrowser,
+  isServer,
+  isIframe,
+  renderRichTextToReact
+};

package/dist/chunk-V6JSXN66.mjs

@@ -0,0 +1,76 @@
+import {
+  FONT_BOLD,
+  FONT_NORMAL,
+  getComponent,
+  getFallbackComponent,
+  getLocalessClient,
+  isSyncEnabled,
+  localessEditable
+} from "./chunk-ETSLIILF.mjs";
+
+// src/core/components/localess-component.tsx
+import { forwardRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+var LocalessComponent = forwardRef(
+  ({ data, links, references, ...restProps }, ref) => {
+    if (!data) {
+      console.error("LocalessComponent property %cdata%c is not provided.", FONT_BOLD, FONT_NORMAL);
+      return /* @__PURE__ */ jsxs("div", { children: [
+        "LocalessComponent property ",
+        /* @__PURE__ */ jsx("b", { children: "data" }),
+        " is not provided."
+      ] });
+    }
+    const Comp = getComponent(data._schema);
+    if (Comp) {
+      const attr = isSyncEnabled() ? localessEditable(data) : {};
+      return /* @__PURE__ */ jsx(Comp, { ref, data, links, references, ...attr, ...restProps });
+    }
+    const FallbackComponent = getFallbackComponent();
+    if (FallbackComponent) {
+      return /* @__PURE__ */ jsx(FallbackComponent, { ref, data, links, references, ...restProps });
+    }
+    return /* @__PURE__ */ jsxs("p", { children: [
+      /* @__PURE__ */ jsx("b", { children: "LocalessComponent" }),
+      " could not found component with key ",
+      /* @__PURE__ */ jsx("b", { children: data._schema }),
+      ". ",
+      /* @__PURE__ */ jsx("br", {}),
+      "Please check if your configuration is correct."
+    ] });
+  }
+);
+
+// src/core/hooks/use-localess.ts
+import { useEffect, useState } from "react";
+import { isBrowser } from "@localess/client";
+var useLocaless = (slug, options = {}) => {
+  const [document, setDocument] = useState();
+  const client = getLocalessClient();
+  let normalizedSlug;
+  if (Array.isArray(slug)) {
+    normalizedSlug = slug.join("/");
+  } else {
+    normalizedSlug = slug;
+  }
+  useEffect(() => {
+    async function loadDocument() {
+      const document2 = await client.getContentBySlug(normalizedSlug, options);
+      setDocument(document2);
+      if (isSyncEnabled() && isBrowser()) {
+        window.localess?.on(["input", "change"], (event) => {
+          if (event.type === "change" || event.type === "input") {
+            setDocument({ ...document2, data: event.data });
+          }
+        });
+      }
+    }
+    loadDocument();
+  }, [slug, options, client]);
+  return document;
+};
+
+export {
+  LocalessComponent,
+  useLocaless
+};

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { ContentData, Links, References, LocalessClientOptions, ContentFetchParams, Content, ContentLink, ContentRichText, LocalessClient, ContentAsset } from '@localess/client';
-export { Content, ContentAsset, ContentData, ContentDataField, ContentDataSchema, ContentLink, ContentMetadata, ContentReference, ContentRichText, EventCallback, EventToApp, EventToAppType, Links, LocalessClient, LocalessSync, References, Translations, isBrowser, isIframe, isServer, localessEditable, localessEditableField } from '@localess/client';
+export { L as LocalessOptions, f as findLink, g as getComponent, a as getFallbackComponent, b as getLocalessClient, i as isSyncEnabled, l as localessInit, r as registerComponent, c as renderRichTextToReact, d as resolveAsset, s as setComponents, e as setFallbackComponent, u as unregisterComponent } from './richtext-XH7pH80J.mjs';
 import * as React from 'react';
-import React__default from 'react';
+import { ContentData, Links, References, ContentFetchParams, Content } from '@localess/client';
+export { Content, ContentAsset, ContentData, ContentDataField, ContentDataSchema, ContentLink, ContentMetadata, ContentReference, ContentRichText, EventCallback, EventToApp, EventToAppType, Links, LocalessClient, LocalessSync, References, Translations, isBrowser, isIframe, isServer, localessEditable, localessEditableField } from '@localess/client';
 
 type LocalessComponentProps<T extends ContentData = ContentData> = {
     data: T;
@@ -10,92 +10,7 @@ type LocalessComponentProps<T extends ContentData = ContentData> = {
 };
 declare const LocalessComponent: React.ForwardRefExoticComponent<LocalessComponentProps<ContentData> & React.RefAttributes<HTMLElement>>;
 
-type LocalessDocumentProps<T extends ContentData = ContentData> = {
-    data: T;
-    links?: Links;
-    references?: References;
-};
-declare const LocalessDocument: React.ForwardRefExoticComponent<LocalessDocumentProps<ContentData> & React.RefAttributes<HTMLElement>>;
-
-type LocalessOptions = LocalessClientOptions & {
-    /**
-     * Components mapping for Localess Component integration
-     */
-    components?: Record<string, React__default.ElementType>;
-    /**
-     * Component used if expected key didn't return anything
-     */
-    fallbackComponent?: React__default.ElementType;
-    /**
-     * Load Sync Script, for Visual Editor integration
-     */
-    enableSync?: boolean;
-};
-
 type UseLocalessOptions = ContentFetchParams & {};
 declare const useLocaless: <T extends ContentData = ContentData>(slug: string | string[], options?: UseLocalessOptions) => Content<T> | undefined;
 
-declare function findLink(links: Links | undefined, link: ContentLink): string;
-
-/**
- * Render Localess Rich Text content to React elements
- * @param content - The Rich Text content to render
- * @returns React.ReactNode - The rendered React elements
- */
-declare function renderRichTextToReact(content: ContentRichText): React__default.ReactNode;
-
-/**
- * Initialize Localess Client
- * @param options
- * @returns LocalessClient
- */
-declare function localessInit(options: LocalessOptions): LocalessClient;
-/**
- * Get Localess Client
- * @returns LocalessClient
- */
-declare function getLocalessClient(): LocalessClient;
-/**
- * Register Component
- * @param key - component key
- * @param component - React Component
- */
-declare function registerComponent(key: string, component: React__default.ElementType): void;
-/**
- * Unregister Component
- * @param key - component key
- */
-declare function unregisterComponent(key: string): void;
-/**
- * Set Components
- * @param components - Record of components
- */
-declare function setComponents(components: Record<string, React__default.ElementType>): void;
-/**
- * Get Component
- * @param key - component key
- * @returns React Component
- */
-declare function getComponent(key: string): React__default.ElementType | undefined;
-/**
- * Set Fallback Component
- * @param fallbackComponent
- */
-declare function setFallbackComponent(fallbackComponent: React__default.ElementType): void;
-/**
- * Get Fallback Component
- * @returns React Component
- */
-declare function getFallbackComponent(): React__default.ElementType | undefined;
-/**
- * Check if Sync is enabled
- */
-declare function isSyncEnabled(): boolean;
-/**
- * Resolve Asset URL
- * @param asset - ContentAsset
- * @returns Asset URL
- */
-declare function resolveAsset(asset: ContentAsset): string;
-
-export { LocalessComponent, type LocalessComponentProps, LocalessDocument, type LocalessDocumentProps, type LocalessOptions, type UseLocalessOptions, findLink, getComponent, getFallbackComponent, getLocalessClient, isSyncEnabled, localessInit, registerComponent, renderRichTextToReact, resolveAsset, setComponents, setFallbackComponent, unregisterComponent, useLocaless };
+export { LocalessComponent, type LocalessComponentProps, type UseLocalessOptions, useLocaless };