draftify-react 0.1.3 → 0.1.5

package/README.md

@@ -5,7 +5,7 @@
 `draftify-react` is a **fully styled, production-ready React editor** powered by the `draftify` core engine. It provides an out-of-the-box editing experience while preserving the structured, schema-driven philosophy of Draftify.
 
 This package focuses purely on **UI and interaction**.
-All document logic lives in `draftify`.
+All document logic, schemas, validation, and export utilities live in `draftify`.
 
 ---
 
@@ -13,14 +13,15 @@ All document logic lives in `draftify`.
 
 `draftify-react` **does not work on its own**.
 
-It requires the core engine:
+It requires the Draftify core engine:
 
 ```bash
 npm install draftify
 npm install draftify-react
 ```
 
-`draftify-react` consumes and manipulates Draftify documents internally, so both packages must be installed.
+Both packages must be installed.
+`draftify-react` renders and manipulates **Draftify documents**, but it does not define the document model itself.
 
 ---
 
@@ -34,6 +35,7 @@ npm install draftify-react
 - ✅ Document metadata handling
 - ✅ Preview & editor modes
 - ✅ Clipboard, export & formatting support
+- ✅ Reader component for rendering documents
 - ✅ Zero configuration required to start
 
 ---
@@ -46,22 +48,77 @@ npm install draftify draftify-react
 
 ---
 
-## Basic Usage
+## ❗ Controlled Editor (Very Important)
 
-```jsx
-import DraftifyReact from "draftify-react";
+`draftify-react` is a **controlled editor**.
+
+This means:
+
+- **You own the document state**
+- The editor **does not store blocks internally**
+- You must declare and manage the blocks array yourself
+
+This design is intentional. It allows:
+
+- Full control over persistence (database, localStorage, APIs)
+- Multiple views of the same document (editor + reader)
+- Easy integration with frameworks and state managers
+- Predictable, debuggable data flow
+
+---
+
+## Minimal Usage (Required Pattern)
+
+This is the **correct and complete** way to use `draftify-react`.
+
+```tsx
+import { useState } from "react";
+import type { DraftifyBlock } from "draftify";
+import DraftifyReact, { Reader } from "draftify-react";
 import "draftify-react/styles.css";
 
 export default function App() {
+  const [blocksData, modifyBlocks] = useState<DraftifyBlock[]>([]);
+
   return (
-    <div>
-      <DraftifyReact />
-    </div>
+    <>
+      <DraftifyReact blocksData={blocksData} modifyBlocks={modifyBlocks} />
+
+      {/* Render the same document anywhere */}
+      <Reader blocksData={blocksData} />
+    </>
   );
 }
 ```
 
-That’s all you need for a working editor.
+### What’s happening here
+
+- `blocksData` holds the Draftify document
+- `modifyBlocks` is passed to the editor
+- The editor updates state via `modifyBlocks`
+- `Reader` consumes the **same data** to render content
+
+There is **one source of truth** for your document.
+
+---
+
+## TypeScript Users (Recommended)
+
+Draftify exposes its schema types via the core package.
+
+You should always type your state explicitly:
+
+```ts
+import type { DraftifyBlock } from "draftify";
+
+const [blocksData, modifyBlocks] = useState<DraftifyBlock[]>([]);
+```
+
+This ensures:
+
+- Full IntelliSense
+- Compile-time validation
+- Safer integration with APIs and storage layers
 
 ---
 
@@ -75,29 +132,41 @@ You must import it **once** in your app:
 @import "draftify-react/styles.css";
 ```
 
+or in JavaScript:
+
+```ts
+import "draftify-react/styles.css";
+```
+
 ### Tailwind v4 Users
 
-If your project uses Tailwind v4, no extra configuration is required.
+No configuration required.
 All Draftify styles are already compiled and scoped.
 
 ---
 
-## Editor Behavior
+## Reader Component
+
+`draftify-react` exports a `Reader` component for rendering documents without editing.
+
+```tsx
+import { Reader } from "draftify-react";
+
+<Reader blocksData={blocksData} />;
+```
 
-The editor supports:
+Use cases:
 
-- Multiple block types
-- Inline editing
-- Drag & drop ordering
-- Preview vs edit mode
-- Copy / export helpers
-- Metadata prompts (title, description, author)
+- Read-only previews
+- Blog posts
+- Exported documents
+- Public-facing content
 
-All content is internally represented using Draftify’s schema.
+The `Reader` component **never mutates data**.
 
 ---
 
-## Hooks API
+## Hooks API (Advanced)
 
 ### `useDraftifyReact`
 
@@ -107,13 +176,47 @@ import { useDraftifyReact } from "draftify-react";
 
 This hook powers the editor internally and exposes:
 
-- Document state
-- Block data
-- Block creation & modification helpers
+- Document state helpers
+- Block creation & modification functions
 - Drag & drop handlers
-- UI state helpers
+- View and animation state
 
-> Advanced users can build **custom editors or wrappers** using this hook.
+This is intended for:
+
+- Custom editors
+- Headless integrations
+- Advanced UI wrappers
+
+Most users **do not need this hook**.
+
+---
+
+## Collaboration Between Packages
+
+Draftify is intentionally split into two layers:
+
+### `draftify`
+
+- Schema definitions
+- Block types
+- Validation
+- Normalization
+- Clipboard & export helpers
+- Framework-agnostic logic
+
+### `draftify-react`
+
+- React components
+- UI interactions
+- Animations
+- Styling
+- Editor and Reader views
+
+Because of this separation:
+
+- `draftify` can be used in **any framework**
+- `draftify-react` can evolve independently
+- You can build alternative UIs without rewriting logic
 
 ---
 
@@ -131,7 +234,7 @@ draftify-react/
 └─ README.md
 ```
 
-The distributed package contains only what is required at runtime.
+Only runtime-required files are shipped.
 
 ---
 
@@ -139,7 +242,7 @@ The distributed package contains only what is required at runtime.
 
 ```ts
 import DraftifyReact from "draftify-react";
-import { useDraftifyReact } from "draftify-react";
+import { Reader, useDraftifyReact } from "draftify-react";
 ```
 
 Styles:
@@ -150,36 +253,23 @@ Styles:
 
 ---
 
-## Why This Package Exists
-
-Draftify was designed with separation of concerns in mind.
-
-- `draftify` → **logic, schema, validation, export**
-- `draftify-react` → **UI, interactions, visuals**
-
-This allows:
-
-- Custom editors without UI constraints
-- Backend usage of Draftify
-- Independent evolution of UI and logic
-
----
-
 ## When to Use `draftify-react`
 
 Use this package if you want:
 
-- A complete editor without building UI
-- Fast integration into a React project
-- A clean abstraction over Draftify’s internals
+- A complete editor UI
+- Fast React integration
+- Full control over document state
+- A clean abstraction over Draftify internals
 
-If you want to build your own editor UI, use `draftify` directly.
+If you want to build your own editor UI or use Draftify outside React, use `draftify` directly.
 
 ---
 
 ## Compatibility
 
 - React ≥ 18
+- TypeScript supported
 - Tailwind v4 supported
 - ESM & UMD builds included