@localess/react 3.0.1-dev.20260408170501 → 3.0.1-dev.20260408172608

package/README.md

@@ -249,40 +249,92 @@ const Image = ({ data }) => (
 
 ---
 
+## `useLocaless` Hook
+
+`useLocaless<T>` fetches content by slug in a Client Component and automatically subscribes to Visual Editor live updates when `enableSync` is active.
+
+```tsx
+'use client';
+
+import { useLocaless, LocalessComponent } from "@localess/react";
+import type { Page } from "./.localess/localess";
+
+export function PageView({ slug }: { slug: string }) {
+  const content = useLocaless<Page>(slug, { locale: 'en' });
+
+  if (!content) return <div>Loading…</div>;
+
+  return (
+    <main>
+      {content.data.body.map(item => (
+        <LocalessComponent key={item._id} data={item} links={content.links} />
+      ))}
+    </main>
+  );
+}
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `slug` | `string \| string[]` | ✅ | Content slug. Arrays are joined with `/` — e.g. `['blog', 'post']` → `'blog/post'` |
+| `options` | `ContentFetchParams` | ❌ | Same fetch options as `getContentBySlug` (locale, version, resolveReference, resolveLink) |
+
+Returns `Content<T> | undefined` — `undefined` while the initial fetch is in progress.
+
+When `enableSync` is active and the page is rendered inside the Localess Visual Editor iframe, the hook automatically subscribes to `input` / `change` events and updates the returned content in place.
+
+---
+
+## Link Utilities
+
+### `findLink(links, link)`
+
+Resolves a `ContentLink` field to a URL string. Use it to build `href` values from Localess content links.
+
+```tsx
+import { findLink } from "@localess/react";
+
+// type: 'content' → '/' + fullSlug, or '/not-found' if not in map
+// type: 'url'     → raw URI unchanged
+const href = findLink(content.links, data.ctaLink);
+
+const NavLink = ({ data, links }) => (
+  <a href={findLink(links, data.link)}>{data.label}</a>
+);
+```
+
+---
+
 ## Visual Editor Events
 
-When your application is opened inside the Localess Visual Editor, subscribe to live-editing events via `window.localess`.
+When `enableSync: true` is set in `localessInit`, Visual Editor live-editing is handled **automatically** by the `useLocaless` hook — no manual event wiring needed.
 
 ```tsx
 'use client';
 
-import { useEffect, useState } from "react";
-import { getLocalessClient } from "@localess/react";
-import type { Content } from "@localess/react";
+import { useLocaless, LocalessComponent, localessEditable } from "@localess/react";
+import type { Page } from "./.localess/localess";
 
-export function PageClient({ initialData }: { initialData: Content<Page> }) {
-  const [pageData, setPageData] = useState(initialData.data);
+export function PageView({ slug, locale }: { slug: string; locale?: string }) {
+  // Automatically subscribes to Visual Editor input/change events when enableSync is active
+  const content = useLocaless<Page>(slug, { locale });
 
-  useEffect(() => {
-    if (window.localess) {
-      window.localess.on(['input', 'change'], (event) => {
-        if (event.type === 'input' || event.type === 'change') {
-          setPageData(event.data);
-        }
-      });
-    }
-  }, []);
+  if (!content) return null;
 
   return (
-    <main {...localessEditable(pageData)}>
-      {pageData.body.map(item => (
-        <LocalessComponent key={item._id} data={item} />
+    <main {...localessEditable(content.data)}>
+      {content.data?.body.map(item => (
+        <LocalessComponent key={item._id} data={item} links={content.links} references={content.references} />
       ))}
     </main>
   );
 }
 ```
 
+> `useLocaless` handles the full cycle: initial fetch + live sync updates when inside the editor iframe.
+
 ---
 
 ## Full Example (Next.js 15 App Router)
@@ -296,7 +348,7 @@ localessInit({
   origin: process.env.LOCALESS_ORIGIN!,
   spaceId: process.env.LOCALESS_SPACE_ID!,
   token: process.env.LOCALESS_TOKEN!,
-  enableSync: process.env.NODE_ENV === 'development',
+  enableSync: process.env.NODE_ENV !== 'production',
   components: { Page, Header, Teaser, Footer },
 });
 
@@ -306,19 +358,41 @@ export default function RootLayout({ children }) {
 ```
 
 ```tsx
-// app/page.tsx (Server Component)
-import { getLocalessClient, LocalessComponent, localessEditable } from "@localess/react";
+// app/[locale]/page.tsx (Server Component — fetches initial data)
+import { getLocalessClient } from "@localess/react";
+import { PageClient } from "./page-client";
 import type { Page } from "./.localess/localess";
 
 export default async function HomePage({
-  searchParams,
+  params,
 }: {
-  searchParams: Promise<{ locale?: string }>;
+  params: Promise<{ locale?: string }>;
 }) {
-  const { locale } = await searchParams;
+  const { locale } = await params;
   const client = getLocalessClient();
   const content = await client.getContentBySlug<Page>('home', { locale });
 
+  return <PageClient initialContent={content} locale={locale} />;
+}
+```
+
+```tsx
+// app/[locale]/page-client.tsx (Client Component — renders + auto-syncs with Visual Editor)
+'use client';
+
+import { useLocaless, LocalessComponent, localessEditable } from "@localess/react";
+import type { Content, Page } from "./.localess/localess";
+
+export function PageClient({
+  initialContent,
+  locale,
+}: {
+  initialContent: Content<Page>;
+  locale?: string;
+}) {
+  // Handles initial fetch and Visual Editor live updates automatically
+  const content = useLocaless<Page>('home', { locale }) ?? initialContent;
+
   return (
     <main {...localessEditable(content.data)}>
       {content.data?.body.map(item => (
@@ -342,7 +416,7 @@ The following are re-exported for convenience so you only need to import from `@
 
 **Types:** `Content`, `ContentData`, `ContentMetadata`, `ContentDataSchema`, `ContentDataField`, `ContentAsset`, `ContentRichText`, `ContentLink`, `ContentReference`, `Links`, `References`, `Translations`, `LocalessClient`, `LocalessSync`, `EventToApp`, `EventCallback`, `EventToAppType`
 
-**Functions:** `localessEditable`, `localessEditableField`, `llEditable` *(deprecated)*, `llEditableField` *(deprecated)*, `isBrowser`, `isServer`, `isIframe`
+**Functions:** `localessEditable`, `localessEditableField`, `llEditable` *(deprecated)*, `llEditableField` *(deprecated)*, `isBrowser`, `isServer`, `isIframe`, `resolveAsset`, `findLink`, `useLocaless`, `renderRichTextToReact`, `localessInit`, `getLocalessClient`, `registerComponent`, `unregisterComponent`, `setComponents`, `getComponent`, `setFallbackComponent`, `getFallbackComponent`, `isSyncEnabled`
 
 ---
 

package/SKILL.md

@@ -176,37 +176,26 @@ localessInit({
 
 ### Receiving Real-time Editor Events
 
-Once the sync script is loaded, `window.localess` becomes available inside the iframe. Subscribe to it in a Client Component to apply live updates:
+Use the `useLocaless` hook in a Client Component — it **automatically subscribes** to `input` / `change` events when `enableSync` is active. No manual `window.localess.on()` wiring needed.
 
 ```tsx
 'use client';
 
-import { useEffect, useState } from "react";
-import { LocalessComponent, localessEditable } from "@localess/react";
+import { useLocaless, LocalessComponent, localessEditable } from "@localess/react";
 import type { Content, Page } from "./.localess/localess";
 
-export function PageClient({ initialContent }: { initialContent: Content<Page> }) {
-  const [pageData, setPageData] = useState(initialContent.data);
-
-  useEffect(() => {
-    if (window.localess) {
-      window.localess.on(['input', 'change'], (event) => {
-        if (event.type === 'input' || event.type === 'change') {
-          setPageData(event.data);
-        }
-      });
-    }
-    // No cleanup needed: window.localess has no .off() method
-  }, []);
+export function PageClient({ initialContent, locale }: { initialContent: Content<Page>; locale?: string }) {
+  // Fetches content and auto-syncs with Visual Editor live updates
+  const content = useLocaless<Page>('home', { locale }) ?? initialContent;
 
   return (
-    <main {...localessEditable(pageData)}>
-      {pageData?.body?.map(item => (
+    <main {...localessEditable(content.data)}>
+      {content.data?.body?.map(item => (
         <LocalessComponent
           key={item._id}
           data={item}
-          links={initialContent.links}
-          references={initialContent.references}
+          links={content.links}
+          references={content.references}
         />
       ))}
     </main>
@@ -214,7 +203,7 @@ export function PageClient({ initialContent }: { initialContent: Content<Page> }
 }
 ```
 
-**Available events via `window.localess.on()`:**
+**Available events (handled internally by `useLocaless`):**
 
 | Event         | When                                          |
 |---------------|-----------------------------------------------|
@@ -230,56 +219,45 @@ export function PageClient({ initialContent }: { initialContent: Content<Page> }
 
 ### Pattern: Split Server/Client Components (Next.js App Router)
 
-The recommended pattern keeps data fetching server-side while the Client Component handles live sync:
+Keep data fetching server-side and delegate rendering + sync to a Client Component using `useLocaless`:
 
 ```tsx
-// app/[locale]/page.tsx — Server Component: fetches data, no sync logic
+// app/[locale]/page.tsx — Server Component: fetches initial data
 import { getLocalessClient } from "@localess/react";
 import { PageClient } from "./page-client";
 import type { Page } from "./.localess/localess";
 
 export default async function HomePage({
-  searchParams,
+  params,
 }: {
-  searchParams: Promise<{ locale?: string }>;
+  params: Promise<{ locale?: string }>;
 }) {
-  const { locale } = await searchParams;
+  const { locale } = await params;
   const client = getLocalessClient();
   const content = await client.getContentBySlug<Page>('home', { locale });
 
-  return <PageClient initialContent={content} />;
+  return <PageClient initialContent={content} locale={locale} />;
 }
 ```
 
 ```tsx
-// app/[locale]/page-client.tsx — Client Component: renders + handles live edits
+// app/[locale]/page-client.tsx — Client Component: renders + auto-syncs
 'use client';
 
-import { useEffect, useState } from "react";
-import { LocalessComponent, localessEditable } from "@localess/react";
+import { useLocaless, LocalessComponent, localessEditable } from "@localess/react";
 import type { Content, Page } from "./.localess/localess";
 
-export function PageClient({ initialContent }: { initialContent: Content<Page> }) {
-  const [pageData, setPageData] = useState(initialContent.data);
-
-  useEffect(() => {
-    if (window.localess) {
-      window.localess.on(['input', 'change'], (event) => {
-        if (event.type === 'input' || event.type === 'change') {
-          setPageData(event.data);
-        }
-      });
-    }
-  }, []);
+export function PageClient({ initialContent, locale }: { initialContent: Content<Page>; locale?: string }) {
+  const content = useLocaless<Page>('home', { locale }) ?? initialContent;
 
   return (
-    <main {...localessEditable(pageData)}>
-      {pageData?.body?.map(item => (
+    <main {...localessEditable(content.data)}>
+      {content.data?.body?.map(item => (
         <LocalessComponent
           key={item._id}
           data={item}
-          links={initialContent.links}
-          references={initialContent.references}
+          links={content.links}
+          references={content.references}
         />
       ))}
     </main>
@@ -289,6 +267,67 @@ export function PageClient({ initialContent }: { initialContent: Content<Page> }
 
 ---
 
+## `useLocaless` Hook
+
+`useLocaless<T>` fetches content by slug on the client side and automatically wires up Visual Editor live updates when `enableSync` is active.
+
+```tsx
+'use client';
+
+import { useLocaless } from "@localess/react";
+import type { Page } from "./.localess/localess";
+
+export function PageView({ slug }: { slug: string }) {
+  const content = useLocaless<Page>(slug, { locale: 'en' });
+
+  if (!content) return <div>Loading…</div>;
+
+  return (
+    <main>
+      {content.data.body.map(item => (
+        <LocalessComponent key={item._id} data={item} links={content.links} />
+      ))}
+    </main>
+  );
+}
+```
+
+### Signature
+
+```typescript
+useLocaless<T extends ContentData = ContentData>(
+  slug: string | string[],  // string[] is joined with '/' — e.g. ['blog', 'post'] → 'blog/post'
+  options?: ContentFetchParams
+): Content<T> | undefined
+```
+
+- Returns `undefined` while the initial fetch is in flight.
+- When `enableSync` is active and the page is inside the Localess Visual Editor, automatically subscribes to `input` / `change` events and updates the returned value in place.
+
+---
+
+## Link Utilities
+
+### `findLink(links, link)`
+
+Resolves a `ContentLink` to a URL string. Use this to convert link fields from Localess content into href values.
+
+```typescript
+import { findLink } from "@localess/react";
+
+const href = findLink(content.links, data.ctaLink);
+// type: 'content' → '/' + fullSlug (e.g. '/blog/my-post'), or '/not-found' if not in links map
+// type: 'url'     → raw URI (e.g. 'https://example.com')
+```
+
+```tsx
+const NavLink = ({ data, links }) => (
+  <a href={findLink(links, data.link)}>{data.label}</a>
+);
+```
+
+---
+
 ## Rich Text Rendering
 
 Converts Localess `ContentRichText` (Tiptap JSON) to a React node tree.
@@ -440,6 +479,12 @@ export { LocalessComponent }        // Dynamic schema-to-component renderer
 export { renderRichTextToReact }    // Rich text → React nodes
 export { resolveAsset }             // ContentAsset → full URL
 
+// Hooks
+export { useLocaless }              // Client-side content fetching with sync support
+
+// Utilities
+export { findLink }                 // ContentLink → URL string
+
 // Visual editor (re-exported from @localess/client)
 export { localessEditable, localessEditableField }
 export { llEditable, llEditableField }  // Deprecated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localess/react",
-  "version": "3.0.1-dev.20260408170501",
+  "version": "3.0.1-dev.20260408172608",
   "description": "ReactJS JavaScript/TypeScript SDK for Localess's API.",
   "keywords": [
     "localess",
@@ -46,7 +46,7 @@
     "react-dom": "^17 || ^18 || ^19"
   },
   "dependencies": {
-    "@localess/client": "3.0.1-dev.20260408170501",
+    "@localess/client": "3.0.1-dev.20260408172608",
     "@tiptap/static-renderer": "^3.20.1",
     "@tiptap/html": "^3.20.1",
     "@tiptap/extension-bold": "^3.20.1",