@localess/react 3.0.1-dev.20260405190914 → 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/dist/index.d.mts

@@ -1,7 +1,14 @@
+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';
 import * as React from 'react';
 import React__default from 'react';
-import { LocalessClientOptions, Links, ContentLink, ContentData, References, 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';
+
+type LocalessComponentProps<T extends ContentData = ContentData> = {
+    data: T;
+    links?: Links;
+    references?: References;
+};
+declare const LocalessComponent: React.ForwardRefExoticComponent<LocalessComponentProps<ContentData> & React.RefAttributes<HTMLElement>>;
 
 type LocalessOptions = LocalessClientOptions & {
     /**
@@ -18,14 +25,10 @@ type LocalessOptions = LocalessClientOptions & {
     enableSync?: boolean;
 };
 
-declare function findLink(links: Links | undefined, link: ContentLink): string;
+type UseLocalessOptions = ContentFetchParams & {};
+declare const useLocaless: <T extends ContentData = ContentData>(slug: string | string[], options?: UseLocalessOptions) => Content<T> | undefined;
 
-type LocalessComponentProps<T extends ContentData = ContentData> = {
-    data: T;
-    links?: Links;
-    references?: References;
-};
-declare const LocalessComponent: React.ForwardRefExoticComponent<LocalessComponentProps<ContentData> & React.RefAttributes<HTMLElement>>;
+declare function findLink(links: Links | undefined, link: ContentLink): string;
 
 /**
  * Render Localess Rich Text content to React elements
@@ -88,4 +91,4 @@ declare function isSyncEnabled(): boolean;
  */
 declare function resolveAsset(asset: ContentAsset): string;
 
-export { LocalessComponent, type LocalessComponentProps, type LocalessOptions, findLink, getComponent, getFallbackComponent, getLocalessClient, isSyncEnabled, localessInit, registerComponent, renderRichTextToReact, resolveAsset, setComponents, setFallbackComponent, unregisterComponent };
+export { LocalessComponent, type LocalessComponentProps, type LocalessOptions, type UseLocalessOptions, findLink, getComponent, getFallbackComponent, getLocalessClient, isSyncEnabled, localessInit, registerComponent, renderRichTextToReact, resolveAsset, setComponents, setFallbackComponent, unregisterComponent, useLocaless };

package/dist/index.d.ts

@@ -1,7 +1,14 @@
+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';
 import * as React from 'react';
 import React__default from 'react';
-import { LocalessClientOptions, Links, ContentLink, ContentData, References, 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';
+
+type LocalessComponentProps<T extends ContentData = ContentData> = {
+    data: T;
+    links?: Links;
+    references?: References;
+};
+declare const LocalessComponent: React.ForwardRefExoticComponent<LocalessComponentProps<ContentData> & React.RefAttributes<HTMLElement>>;
 
 type LocalessOptions = LocalessClientOptions & {
     /**
@@ -18,14 +25,10 @@ type LocalessOptions = LocalessClientOptions & {
     enableSync?: boolean;
 };
 
-declare function findLink(links: Links | undefined, link: ContentLink): string;
+type UseLocalessOptions = ContentFetchParams & {};
+declare const useLocaless: <T extends ContentData = ContentData>(slug: string | string[], options?: UseLocalessOptions) => Content<T> | undefined;
 
-type LocalessComponentProps<T extends ContentData = ContentData> = {
-    data: T;
-    links?: Links;
-    references?: References;
-};
-declare const LocalessComponent: React.ForwardRefExoticComponent<LocalessComponentProps<ContentData> & React.RefAttributes<HTMLElement>>;
+declare function findLink(links: Links | undefined, link: ContentLink): string;
 
 /**
  * Render Localess Rich Text content to React elements
@@ -88,4 +91,4 @@ declare function isSyncEnabled(): boolean;
  */
 declare function resolveAsset(asset: ContentAsset): string;
 
-export { LocalessComponent, type LocalessComponentProps, type LocalessOptions, findLink, getComponent, getFallbackComponent, getLocalessClient, isSyncEnabled, localessInit, registerComponent, renderRichTextToReact, resolveAsset, setComponents, setFallbackComponent, unregisterComponent };
+export { LocalessComponent, type LocalessComponentProps, type LocalessOptions, type UseLocalessOptions, findLink, getComponent, getFallbackComponent, getLocalessClient, isSyncEnabled, localessInit, registerComponent, renderRichTextToReact, resolveAsset, setComponents, setFallbackComponent, unregisterComponent, useLocaless };

package/dist/index.js

@@ -25,54 +25,89 @@ __export(index_exports, {
   getComponent: () => getComponent,
   getFallbackComponent: () => getFallbackComponent,
   getLocalessClient: () => getLocalessClient,
-  isBrowser: () => import_client3.isBrowser,
-  isIframe: () => import_client3.isIframe,
-  isServer: () => import_client3.isServer,
+  isBrowser: () => import_client4.isBrowser,
+  isIframe: () => import_client4.isIframe,
+  isServer: () => import_client4.isServer,
   isSyncEnabled: () => isSyncEnabled,
-  localessEditable: () => import_client3.localessEditable,
-  localessEditableField: () => import_client3.localessEditableField,
+  localessEditable: () => import_client4.localessEditable,
+  localessEditableField: () => import_client4.localessEditableField,
   localessInit: () => localessInit,
   registerComponent: () => registerComponent,
   renderRichTextToReact: () => renderRichTextToReact,
   resolveAsset: () => resolveAsset,
   setComponents: () => setComponents,
   setFallbackComponent: () => setFallbackComponent,
-  unregisterComponent: () => unregisterComponent
+  unregisterComponent: () => unregisterComponent,
+  useLocaless: () => useLocaless
 });
 module.exports = __toCommonJS(index_exports);
+var import_client4 = require("@localess/client");
+
+// src/components/localess-component.tsx
+var import_react = require("react");
 var import_client2 = require("@localess/client");
 
 // src/console.ts
 var FONT_BOLD = "font-weight: bold";
 var FONT_NORMAL = "font-weight: normal";
 
-// src/index.ts
-var import_client3 = require("@localess/client");
-
-// src/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/state.ts
+var import_client = require("@localess/client");
+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 = (0, import_client.localessClient)(restOptions);
+  _assetPathPrefix = `${options.origin}/api/v1/spaces/${options.spaceId}/assets/`;
+  _components = components || {};
+  _fallbackComponent = fallbackComponent;
+  if (enableSync) {
+    _enableSync = true;
+    (0, import_client.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/localess-componenet.tsx
-var import_react = require("react");
-var import_client = require("@localess/client");
+// src/components/localess-component.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 var LocalessComponent = (0, import_react.forwardRef)(({ data, links, references, ...restProps }, ref) => {
   if (!data) {
@@ -85,7 +120,7 @@ var LocalessComponent = (0, import_react.forwardRef)(({ data, links, references,
   }
   const Comp = getComponent(data._schema);
   if (Comp) {
-    const attr = isSyncEnabled() ? (0, import_client.localessEditable)(data) : {};
+    const attr = isSyncEnabled() ? (0, import_client2.localessEditable)(data) : {};
     return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Comp, { ref, data, links, references, ...attr, ...restProps });
   }
   const FallbackComponent = getFallbackComponent();
@@ -102,8 +137,58 @@ var LocalessComponent = (0, import_react.forwardRef)(({ data, links, references,
   ] });
 });
 
+// src/hooks/use-localess.ts
+var import_react2 = require("react");
+var import_client3 = require("@localess/client");
+var useLocaless = (slug, options = {}) => {
+  const [document, setDocument] = (0, import_react2.useState)();
+  const client = getLocalessClient();
+  let normalizedSlug;
+  if (Array.isArray(slug)) {
+    normalizedSlug = slug.join("/");
+  } else {
+    normalizedSlug = slug;
+  }
+  (0, import_react2.useEffect)(() => {
+    async function loadDocument() {
+      const document2 = await client.getContentBySlug(normalizedSlug, options);
+      setDocument(document2);
+      if (isSyncEnabled() && (0, import_client3.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;
+};
+
+// src/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/richtext.ts
-var import_react2 = require("@tiptap/static-renderer/pm/react");
+var import_react3 = require("@tiptap/static-renderer/pm/react");
 var import_extension_document = require("@tiptap/extension-document");
 var import_extension_text = require("@tiptap/extension-text");
 var import_extension_paragraph = require("@tiptap/extension-paragraph");
@@ -120,7 +205,7 @@ var import_extension_code = require("@tiptap/extension-code");
 var import_extension_code_block_lowlight = require("@tiptap/extension-code-block-lowlight");
 var import_extension_link = require("@tiptap/extension-link");
 function renderRichTextToReact(content) {
-  return (0, import_react2.renderToReactElement)({
+  return (0, import_react3.renderToReactElement)({
     content,
     extensions: [
       import_extension_document.Document,
@@ -143,61 +228,6 @@ function renderRichTextToReact(content) {
     ]
   });
 }
-
-// src/index.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 = (0, import_client2.localessClient)(restOptions);
-  _assetPathPrefix = `${options.origin}/api/v1/spaces/${options.spaceId}/assets/`;
-  _components = components || {};
-  _fallbackComponent = fallbackComponent;
-  if (enableSync) {
-    _enableSync = true;
-    (0, import_client2.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}`;
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   LocalessComponent,
@@ -217,5 +247,6 @@ function resolveAsset(asset) {
   resolveAsset,
   setComponents,
   setFallbackComponent,
-  unregisterComponent
+  unregisterComponent,
+  useLocaless
 });

package/dist/index.mjs

@@ -1,37 +1,71 @@
 // src/index.ts
-import { loadLocalessSync, localessClient } from "@localess/client";
+import { localessEditable as localessEditable2, localessEditableField, isBrowser as isBrowser2, isServer, isIframe } from "@localess/client";
+
+// src/components/localess-component.tsx
+import { forwardRef } from "react";
+import { localessEditable } from "@localess/client";
 
 // src/console.ts
 var FONT_BOLD = "font-weight: bold";
 var FONT_NORMAL = "font-weight: normal";
 
-// src/index.ts
-import { localessEditable as localessEditable2, localessEditableField, isBrowser, isServer, isIframe } from "@localess/client";
-
-// src/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/state.ts
+import { loadLocalessSync, localessClient } from "@localess/client";
+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/localess-componenet.tsx
-import { forwardRef } from "react";
-import { localessEditable } from "@localess/client";
+// src/components/localess-component.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
 var LocalessComponent = forwardRef(({ data, links, references, ...restProps }, ref) => {
   if (!data) {
@@ -61,6 +95,56 @@ var LocalessComponent = forwardRef(({ data, links, references, ...restProps }, r
   ] });
 });
 
+// src/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;
+};
+
+// src/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/richtext.ts
 import { renderToReactElement } from "@tiptap/static-renderer/pm/react";
 import { Document } from "@tiptap/extension-document";
@@ -102,68 +186,13 @@ function renderRichTextToReact(content) {
     ]
   });
 }
-
-// src/index.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}`;
-}
 export {
   LocalessComponent,
   findLink,
   getComponent,
   getFallbackComponent,
   getLocalessClient,
-  isBrowser,
+  isBrowser2 as isBrowser,
   isIframe,
   isServer,
   isSyncEnabled,
@@ -175,5 +204,6 @@ export {
   resolveAsset,
   setComponents,
   setFallbackComponent,
-  unregisterComponent
+  unregisterComponent,
+  useLocaless
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localess/react",
-  "version": "3.0.1-dev.20260405190914",
+  "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.20260405190914",
+    "@localess/client": "3.0.1-dev.20260408172608",
     "@tiptap/static-renderer": "^3.20.1",
     "@tiptap/html": "^3.20.1",
     "@tiptap/extension-bold": "^3.20.1",