@janbox/storefront-builder 1.0.9 → 2.0.0

package/README.md

@@ -1,46 +1,38 @@
 # @janbox/storefront-builder
 
-A standalone visual page builder library built on [CraftJS](https://craft.js.org/). Provides drag-and-drop storefront creation with a full editor UI, 33 pre-built node components, and responsive design support.
+Thư viện visual page builder độc lập, xây dựng trên [CraftJS](https://craft.js.org/). Hỗ trợ kéo-thả tạo storefront với giao diện editor đầy đủ, 33 node component có sẵn và responsive design theo breakpoint.
 
-## Installation
+## Cài đặt
 
 ```bash
-npm install @janbox/storefront-builder
-# or
 pnpm add @janbox/storefront-builder
 ```
 
 ### Peer dependencies
 
 ```bash
-npm install react@^19 react-dom@^19 @janbox/storefront-ui@>=2
+pnpm add react@^19 react-dom@^19 @janbox/storefront-ui@>=2
 ```
 
 ## Package Exports
 
-| Import path | Contents |
+| Import path | Nội dung |
 | --- | --- |
-| `@janbox/storefront-builder` | Node components (all 33 nodes) |
-| `@janbox/storefront-builder/editor` | Full editor UI (`Editor` component + toolbars) |
-| `@janbox/storefront-builder/templates` | Pre-built element groups and section templates |
-| `@janbox/storefront-builder/style.css` | Required CSS bundle |
+| `@janbox/storefront-builder` | Node components (33 nodes) |
+| `@janbox/storefront-builder/editor` | Giao diện editor đầy đủ (`Editor` component + toolbars) |
+| `@janbox/storefront-builder/templates` | Element groups và section templates có sẵn |
+| `@janbox/storefront-builder/style.css` | CSS bundle (bắt buộc import) |
 
 ---
 
 ## Quick Start — Full Editor
 
-The `Editor` component from `/editor` renders the complete visual builder UI (header toolbar, sidebar with component library, drag-and-drop canvas).
+Component `Editor` render giao diện visual builder hoàn chỉnh: header toolbar, sidebar thư viện component, canvas kéo-thả.
 
 ```tsx
 import '@janbox/storefront-builder/style.css';
 import { Editor } from '@janbox/storefront-builder/editor';
-import {
-  LAYOUT_ELEMENT_GROUP,
-  TEXT_ELEMENT_GROUP,
-  MEDIA_ELEMENT_GROUP,
-  INTERACTIVE_ELEMENT_GROUP,
-  HERO_SECTION_GROUP,
-} from '@janbox/storefront-builder/templates';
+import { HERO_SECTION_GROUP, FAQS_SECTION_GROUP } from '@janbox/storefront-builder/templates';
 import type { Theme } from '@janbox/storefront-ui/theme';
 
 const myTheme: Theme = {
@@ -48,8 +40,9 @@ const myTheme: Theme = {
     primary: {
       500: '#fa8c16',
       600: '#d46b08',
+      // ...
     },
-    // ... full theme
+    // ...
   },
   typography: {
     base: { fontSize: '1rem', lineHeight: '1.5rem' },
@@ -62,34 +55,36 @@ export default function BuilderPage() {
     <Editor
       theme={myTheme}
       handlers={{
-        upload: async () => '',
-        submit: (_data) => {},
-        close: () => {},
+        upload: async (file) => URL.createObjectURL(file),
+        submit: async (data) => {
+          await savePage(data);
+        },
+        close: () => navigateBack(),
       }}
       insert={{
-        elements: [LAYOUT_ELEMENT_GROUP, TEXT_ELEMENT_GROUP, MEDIA_ELEMENT_GROUP, INTERACTIVE_ELEMENT_GROUP],
-        sections: [HERO_SECTION_GROUP],
+        groups: [HERO_SECTION_GROUP, FAQS_SECTION_GROUP],
       }}
     />
   );
 }
 ```
 
-`Editor` occupies the full viewport (`100vw × 100vh`). It should be the root of a dedicated page/route.
+`Editor` chiếm toàn bộ viewport (`100vw × 100vh`), nên đặt ở một route/page riêng.
+
+> Chi tiết đầy đủ về `Editor` xem tại [editor/lib/README.md](editor/lib/README.md).
 
 ---
 
-## Quick Start — Render Only (No Editor UI)
+## Quick Start — Render Only (không có editor UI)
 
-Use `Composer` + `Canvas` to render a saved page without the editor chrome. This is for the storefront-facing page.
+Dùng `Composer` + `Canvas` để render một trang đã lưu, không cần giao diện editor. Đây là cách dùng cho phía storefront hiển thị cho người mua.
 
 ```tsx
 import '@janbox/storefront-builder/style.css';
-import { Composer, Canvas } from '@janbox/storefront-builder';
-import { RootNode } from '@janbox/storefront-builder';
+import { Composer, Canvas, RootNode } from '@janbox/storefront-builder';
 import type { SerializedNodes } from '@janbox/storefront-builder';
 
-const savedData: SerializedNodes = { /* JSON from editor */ };
+const savedData: SerializedNodes = { /* JSON từ editor */ };
 
 export default function StorefrontPage() {
   return (
@@ -104,13 +99,13 @@ export default function StorefrontPage() {
 
 ---
 
-## Core Concepts
+## Khái niệm cơ bản
 
 ### Nodes
 
-Every element on the canvas is a **node** — a React component registered with CraftJS. The library ships 33 built-in nodes:
+Mỗi phần tử trên canvas là một **node** — React component được đăng ký với CraftJS. Thư viện có 33 node có sẵn:
 
-| Category | Nodes |
+| Nhóm | Nodes |
 | --- | --- |
 | Layout | `RootNode`, `Box`, `Flexbox`, `FlexItem`, `Grid`, `Cell` |
 | Typography | `Text`, `Paragraph`, `Heading` |
@@ -122,29 +117,29 @@ Every element on the canvas is a **node** — a React component registered with
 | Carousel | `Swiper`, `SwiperSlide` |
 | Marquee | `Marquee`, `MarqueeItem` |
 | Utilities | `CountdownTimer` |
-| Internal | `UnknownNode` (fallback for unresolved nodes) |
+| Internal | `UnknownNode` (fallback cho node không resolve được) |
 
-All nodes are exported from `@janbox/storefront-builder`.
+Tất cả đều được export từ `@janbox/storefront-builder`.
 
 ### Responsive Props
 
-All style props accept either a plain value or a responsive object keyed by breakpoint:
+Tất cả style prop đều nhận plain value hoặc responsive object theo breakpoint:
 
 ```ts
 // Breakpoints: xs (390px), sm (768px), md (1280px), lg (1680px)
 
-// Plain value (applies at all breakpoints)
+// Plain value (áp dụng tại mọi breakpoint)
 { fontSize: '16px' }
 
-// Responsive object (xs is the base; other keys override upward)
+// Responsive object (xs là base; các key khác override theo hướng tăng dần)
 { fontSize: { xs: '14px', md: '18px' } }
 ```
 
-The current breakpoint is controlled via the `?screen=xs|sm|md|lg` query param.
+Breakpoint hiện tại được điều khiển qua query param `?screen=xs|sm|md|lg`.
 
 ### Serialized State
 
-The canvas state is plain JSON (`SerializedNodes` from `@craftjs/core`). Use `useComposer()` to read and serialize it:
+Trạng thái canvas là plain JSON (`SerializedNodes`). Dùng `useComposer()` để đọc và serialize:
 
 ```tsx
 import { useComposer } from '@janbox/storefront-builder';
@@ -153,11 +148,11 @@ function SaveButton() {
   const { query } = useComposer();
 
   const handleSave = () => {
-    const json = query.serialize(); // SerializedNodes as JSON string
-    // save to your backend
+    const json = query.serialize(); // JSON string dạng SerializedNodes
+    // lưu vào backend
   };
 
-  return <button onClick={handleSave}>Save</button>;
+  return <button onClick={handleSave}>Lưu</button>;
 }
 ```
 
@@ -165,22 +160,11 @@ function SaveButton() {
 
 ## Templates
 
-Templates are pre-configured drag-and-drop groups shown in the editor sidebar.
+Templates là các nhóm kéo-thả có sẵn trong sidebar editor.
 
-### Element Groups (sidebar "Elements" tab)
+Sidebar **Basics** được tích hợp sẵn trong editor và chứa toàn bộ element cơ bản. Consumer không cần import hay truyền các nhóm này.
 
-```ts
-import {
-  LAYOUT_ELEMENT_GROUP,       // Box, Flexbox, Grid
-  TEXT_ELEMENT_GROUP,         // Text, Heading, Paragraph
-  MEDIA_ELEMENT_GROUP,        // Image, Video, Icon
-  INTERACTIVE_ELEMENT_GROUP,  // Button, Link, Accordion, Tabs
-  CONTENT_LIST_ELEMENT_GROUP, // UnorderedList, Marquee, Swiper
-  UTILITIES_ELEMENT_GROUP,    // CountdownTimer
-} from '@janbox/storefront-builder/templates';
-```
-
-### Section Groups (sidebar "Sections" tab)
+### Section Groups
 
 ```ts
 import {
@@ -190,7 +174,7 @@ import {
 } from '@janbox/storefront-builder/templates';
 ```
 
-Pass them to `Editor` via the `insert` prop:
+Truyền vào `Editor` qua prop `insert.groups`:
 
 ```tsx
 <Editor
@@ -201,8 +185,7 @@ Pass them to `Editor` via the `insert` prop:
     close: () => {},
   }}
   insert={{
-    elements: [LAYOUT_ELEMENT_GROUP, TEXT_ELEMENT_GROUP],
-    sections: [HERO_SECTION_GROUP],
+    groups: [HERO_SECTION_GROUP, FAQS_SECTION_GROUP],
   }}
 />
 ```
@@ -211,12 +194,11 @@ Pass them to `Editor` via the `insert` prop:
 
 ## Custom Nodes
 
-### 1. Create a node component
+### 1. Tạo node component
 
 ```tsx
 // my-badge.node.tsx
-import { defineNode } from '@janbox/storefront-builder';
-import { useNode } from '@janbox/storefront-builder';
+import { defineNode, useNode } from '@janbox/storefront-builder';
 
 type MyBadgeProps = { label: string; color?: string };
 
@@ -241,24 +223,20 @@ defineNode(MyBadge, {
 });
 ```
 
-### 2. Pass a resolver to the editor
+### 2. Truyền resolver vào editor
 
 ```tsx
 import { MyBadge } from './my-badge.node';
 
 <Editor
   theme={myTheme}
-  handlers={{
-    upload: async () => '',
-    submit: () => {},
-    close: () => {},
-  }}
+  handlers={{ upload: async () => '', submit: () => {}, close: () => {} }}
   resolver={{ MyBadge }}
-  insert={{ elements: [/* ... */], sections: [] }}
+  insert={{ groups: [] }}
 />
 ```
 
-### 3. Add a toolbar (optional)
+### 3. Thêm toolbar (tùy chọn)
 
 ```tsx
 // my-badge.toolbar.tsx
@@ -279,7 +257,7 @@ export function MyBadgeToolbar() {
 }
 ```
 
-Register the toolbar in `defineNode`:
+Đăng ký toolbar trong `defineNode`:
 
 ```ts
 defineNode(MyBadge, {
@@ -293,42 +271,42 @@ defineNode(MyBadge, {
 
 ## Hooks
 
-All hooks must be called inside a `<Composer>` tree.
+Tất cả hooks phải được gọi bên trong cây `<Composer>`.
 
 ### `useComposer(collector?)`
 
-Enhanced wrapper around CraftJS `useEditor`. Adds `actions.duplicate()` and `actions.move()`.
+Wrapper nâng cao của CraftJS `useEditor`. Bổ sung thêm `actions.duplicate()` và `actions.move()`.
 
 ```ts
 const { query, actions } = useComposer();
 
-// Serialize current canvas state
+// Serialize trạng thái canvas hiện tại
 const json = query.serialize();
 
-// Duplicate a node
+// Duplicate một node
 actions.duplicate(nodeId);
 
-// Move a node
+// Di chuyển một node
 actions.move({ nodeId, sourceIndex: 0, destinationIndex: 2 });
 ```
 
 ### `useNodeProps<P>(options?)`
 
-Read and write props for the current node (or a specific node via `options.nodeId`). Supports responsive updates.
+Đọc và ghi props của node hiện tại (hoặc node chỉ định qua `options.nodeId`). Hỗ trợ cập nhật responsive.
 
 ```ts
 const { nodeProps, setNodeProps, setNodeResponsiveProps } = useNodeProps<MyProps>();
 
-// Set a flat prop
+// Set prop thường
 setNodeProps({ color: '#ff0000' });
 
-// Set a responsive prop for a specific breakpoint
+// Set responsive prop cho breakpoint cụ thể
 setNodeResponsiveProps({ fontSize: '18px' }, 'md');
 ```
 
 ### `useNode()`
 
-Direct access to the CraftJS node context (re-exported from `@craftjs/core`).
+Truy cập trực tiếp CraftJS node context (re-export từ `@craftjs/core`).
 
 ```ts
 const { id, connectors, actions } = useNode();
@@ -336,9 +314,9 @@ const { id, connectors, actions } = useNode();
 
 ---
 
-## TailwindCSS Integration
+## TailwindCSS
 
-The library uses TailwindCSS v4 internally with a `tw:` prefix. Import the stylesheet once at your app entry:
+Thư viện dùng TailwindCSS v4 nội bộ với prefix `tw:`. Import stylesheet một lần ở entry của app:
 
 ```ts
 import '@janbox/storefront-builder/style.css';
@@ -348,7 +326,7 @@ import '@janbox/storefront-builder/style.css';
 
 ## Theme Shape
 
-The `theme` prop on `Editor` follows the `@janbox/storefront-ui` `Theme` type:
+Prop `theme` của `Editor` tuân theo kiểu `Theme` của `@janbox/storefront-ui`:
 
 ```ts
 type Theme = {
@@ -356,14 +334,9 @@ type Theme = {
     primary: Record<100 | 200 | 300 | 400 | 500 | 600 | 700 | 800, string>;
     secondary: Record<...>;
     red, orange, yellow, green, blue, violet, neutral: Record<...>;
-    black: string;
-    white: string;
-    background: { subtle, default, emphasis: string };
+    background: { subtle: string; default: string; emphasis: string };
     surface: { default: string };
     border: { default: string };
-    inherit: string;
-    current: string;
-    transparent: string;
   };
   typography: Record<'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl', {
     fontSize: string;
@@ -376,15 +349,15 @@ type Theme = {
 
 ## TypeScript
 
-The package ships full `.d.ts` declarations. Key types:
+Package đi kèm đầy đủ file `.d.ts`. Các type chính:
 
 ```ts
 import type {
-  SerializedNodes,   // canvas JSON state
-  NodeId,            // string node identifier
-  NodeTree,          // tree of nodes
-  Resolver,          // map of resolvedName → component
-  NodeConfig,        // config passed to defineNode()
+  SerializedNodes,   // JSON state của canvas
+  NodeId,            // string định danh node
+  NodeTree,          // cây node
+  Resolver,          // map resolvedName → component
+  NodeConfig,        // config truyền vào defineNode()
   DisplayOnValue,    // responsive visibility: Partial<Record<Screen, boolean>>
 } from '@janbox/storefront-builder';
 ```
@@ -397,7 +370,7 @@ Chi tiết props, usage và rules cho từng node:
 
 ### Layout
 
-- [RootNode](dist/lib/root/README.md) — top-level canvas container
+- [RootNode](dist/lib/root/README.md) — container gốc của canvas
 - [BoxNode](dist/lib/box/README.md) — block container
 - [FlexboxNode](dist/lib/flexbox/README.md) — flex container
 - [FlexItemNode](dist/lib/flex-item/README.md) — flex item
@@ -412,7 +385,7 @@ Chi tiết props, usage và rules cho từng node:
 
 ### Media
 
-- [ImageNode](dist/lib/image/README.md) — image
+- [ImageNode](dist/lib/image/README.md) — hình ảnh
 - [VideoNode](dist/lib/video/README.md) — video player
 - [IconNode](dist/lib/icon/README.md) — inline SVG icon
 
@@ -423,8 +396,8 @@ Chi tiết props, usage và rules cho từng node:
 
 ### Lists
 
-- [UnorderedListNode](dist/lib/unordered-list/README.md) — list container
-- [ListItemNode](dist/lib/list-item/README.md) — list item
+- [UnorderedListNode](dist/lib/unordered-list/README.md) — danh sách không thứ tự
+- [ListItemNode](dist/lib/list-item/README.md) — item trong danh sách
 
 ### Accordion
 
@@ -436,10 +409,10 @@ Chi tiết props, usage và rules cho từng node:
 ### Tabs
 
 - [TabsNode](dist/lib/tabs/README.md) — tabs container
-- [TabListNode](dist/lib/tab-list/README.md) — tab headers container
+- [TabListNode](dist/lib/tab-list/README.md) — container chứa tab headers
 - [TabNode](dist/lib/tab/README.md) — tab header button
-- [TabContentNode](dist/lib/tab-content/README.md) — tab panels container
-- [TabPanelNode](dist/lib/tab-panel/README.md) — tab panel content
+- [TabContentNode](dist/lib/tab-content/README.md) — container chứa tab panels
+- [TabPanelNode](dist/lib/tab-panel/README.md) — nội dung tab panel
 
 ### Carousel
 
@@ -453,28 +426,28 @@ Chi tiết props, usage và rules cho từng node:
 
 ### Utilities
 
-- [CountdownTimerNode](dist/lib/countdown-timer/README.md) — countdown timer
+- [CountdownTimerNode](dist/lib/countdown-timer/README.md) — đồng hồ đếm ngược
 
 ### Internal
 
-- [UnknownNode](dist/lib/unknown/README.md) — fallback for unresolved nodes
+- [UnknownNode](dist/lib/unknown/README.md) — fallback cho node không resolve được
 
 ---
 
-## Monorepo Development
+## Phát triển Monorepo
 
 ```bash
-# Install dependencies
+# Cài đặt dependencies
 pnpm install
 
-# Start demo app (React Router 7)
+# Chạy demo app (React Router 7)
 pnpm dev
 
-# Build the library
+# Build thư viện
 pnpm build
 
 # Type check
 pnpm typecheck
 ```
 
-Requires Node.js >= 20 and pnpm.
+Yêu cầu Node.js >= 20 và pnpm.