@janbox/storefront-builder 1.0.3 → 1.0.5

package/lib/paragraph/README.md

@@ -0,0 +1,82 @@
+# ParagraphNode
+
+Text node dành cho đoạn văn bản. Dùng chung `TextInspector` với `TextNode` nhưng không cho phép đổi tag — luôn render ra `p`.
+
+## Resolved name
+
+`Paragraph`
+
+## Configurable props
+
+Giống hệt `TextNode` ngoại trừ prop `as` bị loại bỏ. Xem chi tiết tại [TextNode](../text/README.md#configurable-props).
+
+### `sx` props
+
+```ts
+sx?: {
+  // typography (áp dụng toàn breakpoint — không responsive)
+  color?: string
+  fontStyle?: 'normal' | 'italic'
+  fontWeight?: number | string
+  textDecorationLine?: 'none' | 'underline' | 'line-through'
+  textAlign?: 'left' | 'center' | 'right' | 'justify'
+  textTransform?: 'none' | 'uppercase' | 'lowercase' | 'capitalize'
+
+  // size
+  width?: number | string
+
+  // spacing
+  paddingTop?: number
+  paddingRight?: number
+  paddingBottom?: number
+  paddingLeft?: number
+  marginTop?: number
+  marginRight?: number
+  marginBottom?: number
+  marginLeft?: number
+
+  // responsive overrides
+  sm?: { /* same keys above */ }
+  md?: { /* same keys above */ }
+  lg?: { /* same keys above */ }
+}
+```
+
+## Usage
+
+```tsx
+import { ParagraphNode } from '@janbox/storefront-builder';
+
+// Đoạn văn đơn giản
+<ParagraphNode>
+  Lorem ipsum dolor sit amet.
+</ParagraphNode>
+
+// Với sizeVariant responsive
+<ParagraphNode sizeVariant="sm" md={{ sizeVariant: 'base' }}>
+  Body copy text
+</ParagraphNode>
+
+// Styled
+<ParagraphNode
+  sx={{
+    color: '#555555',
+    textAlign: 'center',
+    marginTop: 8,
+    marginBottom: 8,
+  }}
+>
+  Centered paragraph
+</ParagraphNode>
+```
+
+## Rules
+
+- **Canvas**: no — không chứa node con.
+- **Inline editing**: có thể double-click để chỉnh nội dung trong canvas.
+- **Tag**: cố định là `p`, không thể đổi.
+
+## Related nodes
+
+- [`TextNode`](../text/README.md) — base component dùng chung inspector
+- [`HeadingNode`](../heading/README.md) — dành cho tiêu đề với tag `h1`–`h6`

package/lib/root/README.md

@@ -0,0 +1,33 @@
+# RootNode
+
+Top-level canvas container của toàn bộ trang. Luôn là node gốc trong `Canvas` — không thể xóa hay di chuyển.
+
+## Resolved name
+
+`Root`
+
+## Configurable props
+
+Không có props. Chỉ nhận `children`.
+
+## Usage
+
+```tsx
+import { Composer, Canvas } from '@janbox/storefront-builder';
+import { RootNode } from '@janbox/storefront-builder';
+
+// Render mode (storefront)
+<Composer>
+  <Canvas data={savedNodes}>
+    <RootNode />
+  </Canvas>
+</Composer>
+
+// Editor mode — RootNode được Editor tự mount, không cần khai báo thủ công
+```
+
+## Notes
+
+- Khi editor bật (`enabled: true`): render `div` với `minHeight: 100vh` và padding mặc định để tạo không gian kéo thả.
+- Khi editor tắt (render mode): render `Fragment` — không thêm DOM wrapper.
+- `RootNode` phải là node root duy nhất trong `Canvas`. Không được nest `RootNode` bên trong node khác.

package/lib/swiper/README.md

@@ -0,0 +1,108 @@
+# SwiperNode
+
+Carousel/slider container dùng Embla Carousel. Chỉ chấp nhận `SwiperSlideNode` children.
+
+## Resolved name
+
+`Swiper` (displayName: `Carousel`)
+
+## Configurable props
+
+### Top-level props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `slidesPerView` | `number \| 'auto'` | Số slides hiển thị cùng lúc |
+| `spaceBetween` | `number` | Khoảng cách giữa các slides (px) |
+| `autoplayOptions.active` | `boolean` | Bật autoplay |
+| `autoplayOptions.delay` | `number` | Delay giữa các lần chuyển slide (ms) |
+| `autoplayOptions.stopOnLastSnap` | `boolean` | `false` = loop, `true` = dừng ở slide cuối |
+
+`slidesPerView` và `spaceBetween` hỗ trợ responsive.
+
+### `sx` props
+
+```ts
+sx?: {
+  // spacing
+  paddingTop?: number
+  paddingRight?: number
+  paddingBottom?: number
+  paddingLeft?: number
+  marginTop?: number
+  marginRight?: number
+  marginBottom?: number
+  marginLeft?: number
+
+  // border
+  borderStyle?: string
+  borderColor?: string
+  borderTopWidth?: number
+  borderRightWidth?: number
+  borderBottomWidth?: number
+  borderLeftWidth?: number
+  borderTopLeftRadius?: number | string
+  borderTopRightRadius?: number | string
+  borderBottomRightRadius?: number | string
+  borderBottomLeftRadius?: number | string
+
+  // background
+  backgroundColor?: string
+  backgroundImage?: string
+  backgroundPosition?: string
+  backgroundRepeat?: string
+  backgroundSize?: string
+  backgroundAttachment?: string
+  background?: string
+
+  // responsive overrides
+  sm?: { /* same keys above */ }
+  md?: { /* same keys above */ }
+  lg?: { /* same keys above */ }
+}
+```
+
+## Usage
+
+```tsx
+import { SwiperNode, SwiperSlideNode } from '@janbox/storefront-builder';
+
+// 3 slides hiển thị, autoplay với loop
+<SwiperNode
+  slidesPerView={3}
+  spaceBetween={16}
+  autoplayOptions={{
+    active: true,
+    delay: 3000,
+    stopOnLastSnap: false, // loop
+  }}
+>
+  <SwiperSlideNode>Slide 1</SwiperSlideNode>
+  <SwiperSlideNode>Slide 2</SwiperSlideNode>
+  <SwiperSlideNode>Slide 3</SwiperSlideNode>
+</SwiperNode>
+
+// Responsive: 1 slide mobile, 3 slides desktop
+<SwiperNode
+  slidesPerView={1}
+  spaceBetween={8}
+  md={{ slidesPerView: 3, spaceBetween: 24 }}
+  sx={{
+    paddingTop: 16,
+    paddingBottom: 16,
+  }}
+>
+  <SwiperSlideNode>...</SwiperSlideNode>
+  <SwiperSlideNode>...</SwiperSlideNode>
+  <SwiperSlideNode>...</SwiperSlideNode>
+</SwiperNode>
+```
+
+## Rules
+
+- **Canvas**: yes — chứa `SwiperSlideNode` children.
+- **canMoveIn**: chỉ chấp nhận `SwiperSlideNode`.
+
+## Related nodes
+
+- [`SwiperSlideNode`](../swiper-slide/README.md) — mỗi slide item

package/lib/swiper-slide/README.md

@@ -0,0 +1,32 @@
+# SwiperSlideNode
+
+Một slide trong `SwiperNode`. Là canvas node — chứa bất kỳ node con nào.
+
+## Resolved name
+
+`SwiperSlide`
+
+## Configurable props
+
+Không có props riêng. Styling được control qua parent `SwiperNode`.
+
+## Usage
+
+```tsx
+import { SwiperSlideNode, ImageNode, TextNode } from '@janbox/storefront-builder';
+
+<SwiperSlideNode>
+  <ImageNode src="..." alt="..." sx={{ width: '100%' }} />
+  <TextNode>Slide caption</TextNode>
+</SwiperSlideNode>
+```
+
+## Rules
+
+- **Canvas**: yes — chứa bất kỳ node con nào.
+- **Selectable**: no — chỉnh sửa qua parent `SwiperNode` inspector.
+- **Parent**: phải là `SwiperNode`.
+
+## Related nodes
+
+- [`SwiperNode`](../swiper/README.md) — parent carousel container

package/lib/tab/README.md

@@ -0,0 +1,35 @@
+# TabNode
+
+Tab header button — click để switch giữa các panels.
+
+## Resolved name
+
+`Tab`
+
+## Configurable props
+
+### Top-level props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `dangerouslySetInnerHTML.__html` | `string` | Text hiển thị trong tab button |
+
+## Usage
+
+```tsx
+import { TabNode } from '@janbox/storefront-builder';
+
+<TabNode dangerouslySetInnerHTML={{ __html: 'Overview' }} />
+```
+
+## Rules
+
+- **Canvas**: no.
+- **Selectable**: no — chỉnh sửa qua parent `TabsNode` inspector.
+- **Parent**: phải là `TabListNode`.
+
+## Related nodes
+
+- [`TabsNode`](../tabs/README.md) — root container
+- [`TabListNode`](../tab-list/README.md) — parent container
+- [`TabPanelNode`](../tab-panel/README.md) — panel tương ứng

package/lib/tab-content/README.md

@@ -0,0 +1,35 @@
+# TabContentNode
+
+Container cho danh sách tab panels. Chỉ chấp nhận `TabPanelNode` children.
+
+## Resolved name
+
+`TabContent`
+
+## Configurable props
+
+Không có props riêng. Styling được control qua parent `TabsNode`.
+
+## Usage
+
+```tsx
+import { TabContentNode, TabPanelNode } from '@janbox/storefront-builder';
+
+<TabContentNode>
+  <TabPanelNode>Panel 1 content</TabPanelNode>
+  <TabPanelNode>Panel 2 content</TabPanelNode>
+  <TabPanelNode>Panel 3 content</TabPanelNode>
+</TabContentNode>
+```
+
+## Rules
+
+- **Canvas**: yes — chứa `TabPanelNode` children.
+- **Selectable**: no.
+- **canMoveIn**: chỉ chấp nhận `TabPanelNode`.
+- **Parent**: phải là `TabsNode`.
+
+## Related nodes
+
+- [`TabsNode`](../tabs/README.md) — root container
+- [`TabPanelNode`](../tab-panel/README.md) — mỗi panel content

package/lib/tab-list/README.md

@@ -0,0 +1,35 @@
+# TabListNode
+
+Container cho danh sách tab headers. Chỉ chấp nhận `TabNode` children.
+
+## Resolved name
+
+`TabList`
+
+## Configurable props
+
+Không có props riêng. Styling được control qua parent `TabsNode`.
+
+## Usage
+
+```tsx
+import { TabListNode, TabNode } from '@janbox/storefront-builder';
+
+<TabListNode>
+  <TabNode dangerouslySetInnerHTML={{ __html: 'Tab 1' }} />
+  <TabNode dangerouslySetInnerHTML={{ __html: 'Tab 2' }} />
+  <TabNode dangerouslySetInnerHTML={{ __html: 'Tab 3' }} />
+</TabListNode>
+```
+
+## Rules
+
+- **Canvas**: yes — chứa `TabNode` children.
+- **Selectable**: no.
+- **canMoveIn**: chỉ chấp nhận `TabNode`.
+- **Parent**: phải là `TabsNode`.
+
+## Related nodes
+
+- [`TabsNode`](../tabs/README.md) — root container
+- [`TabNode`](../tab/README.md) — tab header button

package/lib/tab-panel/README.md

@@ -0,0 +1,35 @@
+# TabPanelNode
+
+Nội dung của một tab — hiển thị khi tab tương ứng được active. Là canvas node — chứa bất kỳ node con nào.
+
+## Resolved name
+
+`TabPanel`
+
+## Configurable props
+
+Không có props riêng.
+
+## Usage
+
+```tsx
+import { TabPanelNode, ParagraphNode } from '@janbox/storefront-builder';
+
+<TabPanelNode>
+  <ParagraphNode>
+    Tab panel content goes here. Can contain any nodes.
+  </ParagraphNode>
+</TabPanelNode>
+```
+
+## Rules
+
+- **Canvas**: yes — chứa bất kỳ node con nào.
+- **Selectable**: no.
+- **Parent**: phải là `TabContentNode`.
+
+## Related nodes
+
+- [`TabsNode`](../tabs/README.md) — root container
+- [`TabContentNode`](../tab-content/README.md) — parent container
+- [`TabNode`](../tab/README.md) — tab header tương ứng

package/lib/tabs/README.md

@@ -0,0 +1,90 @@
+# TabsNode
+
+Root container cho tabs component. Quản lý active state và chứa `TabListNode` (headers) + `TabContentNode` (panels).
+
+## Resolved name
+
+`Tabs`
+
+## Configurable props
+
+### Top-level props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `defaultActiveIndex` | `number` | Index của tab active mặc định (0-based) |
+
+### `sx` props
+
+```ts
+sx?: {
+  // size
+  width?: number | string
+
+  // spacing
+  paddingTop?: number
+  paddingRight?: number
+  paddingBottom?: number
+  paddingLeft?: number
+  marginTop?: number
+  marginRight?: number
+  marginBottom?: number
+  marginLeft?: number
+
+  // border
+  borderStyle?: string
+  borderColor?: string
+  borderTopWidth?: number
+  borderRightWidth?: number
+  borderBottomWidth?: number
+  borderLeftWidth?: number
+  borderTopLeftRadius?: number | string
+  borderTopRightRadius?: number | string
+  borderBottomRightRadius?: number | string
+  borderBottomLeftRadius?: number | string
+
+  // background
+  backgroundColor?: string
+  backgroundImage?: string
+  backgroundPosition?: string
+  backgroundRepeat?: string
+  backgroundSize?: string
+  backgroundAttachment?: string
+  background?: string
+
+  // responsive overrides
+  sm?: { /* same keys above */ }
+  md?: { /* same keys above */ }
+  lg?: { /* same keys above */ }
+}
+```
+
+## Usage
+
+```tsx
+import { TabsNode } from '@janbox/storefront-builder';
+
+<TabsNode
+  defaultActiveIndex={0}
+  sx={{
+    width: '100%',
+    paddingTop: 16,
+    paddingBottom: 16,
+  }}
+>
+  {/* TabListNode và TabContentNode tự động được thêm bởi editor */}
+</TabsNode>
+```
+
+## Rules
+
+- **Canvas**: no.
+- **Children**: phải có `TabListNode` và `TabContentNode`.
+- Inspector có "Items management" để add/remove/reorder tabs — sync giữa `TabNode` và `TabPanelNode`.
+
+## Related nodes
+
+- [`TabListNode`](../tab-list/README.md) — container cho tab headers
+- [`TabNode`](../tab/README.md) — mỗi tab header button
+- [`TabContentNode`](../tab-content/README.md) — container cho tab panels
+- [`TabPanelNode`](../tab-panel/README.md) — nội dung của mỗi tab

package/lib/text/README.md

@@ -0,0 +1,90 @@
+# TextNode
+
+Inline/block text node có thể chỉnh typography. Render ra bất kỳ HTML tag nào qua prop `as`. Hỗ trợ inline editing trong canvas.
+
+## Resolved name
+
+`Text`
+
+## Configurable props
+
+### Top-level props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `as` | `HTMLElementType` | HTML tag render ra (mặc định `p`) |
+| `sizeVariant` | `TypographySizeVariant` | Preset typography size từ theme |
+
+`sizeVariant` hỗ trợ responsive: `sizeVariant="base"` xs, `md={{ sizeVariant: 'lg' }}` desktop.
+
+**`TypographySizeVariant`:** `'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl'`
+
+### `sx` props
+
+```ts
+sx?: {
+  // typography (áp dụng toàn breakpoint — không responsive)
+  color?: string
+  fontStyle?: 'normal' | 'italic'
+  fontWeight?: number | string
+  textDecorationLine?: 'none' | 'underline' | 'line-through'
+  textAlign?: 'left' | 'center' | 'right' | 'justify'
+  textTransform?: 'none' | 'uppercase' | 'lowercase' | 'capitalize'
+
+  // size
+  width?: number | string
+
+  // spacing
+  paddingTop?: number
+  paddingRight?: number
+  paddingBottom?: number
+  paddingLeft?: number
+  marginTop?: number
+  marginRight?: number
+  marginBottom?: number
+  marginLeft?: number
+
+  // responsive overrides
+  sm?: { /* same keys above */ }
+  md?: { /* same keys above */ }
+  lg?: { /* same keys above */ }
+}
+```
+
+> `color`, `fontStyle`, `textDecorationLine`, `textAlign`, `textTransform` được editor set ở breakpoint `xs` (áp dụng toàn bộ). `fontWeight` và `sizeVariant` hỗ trợ responsive.
+
+## Usage
+
+```tsx
+import { TextNode } from '@janbox/storefront-builder';
+
+// Text đơn giản
+<TextNode>Hello world</TextNode>
+
+// Đổi tag, size variant
+<TextNode as="span" sizeVariant="sm">
+  Small label
+</TextNode>
+
+// sizeVariant responsive
+<TextNode sizeVariant="base" md={{ sizeVariant: 'lg' }}>
+  Body text
+</TextNode>
+
+// Màu, căn giữa, font weight responsive
+<TextNode
+  sx={{
+    color: '#333333',
+    textAlign: 'center',
+    fontWeight: 400,
+    md: { fontWeight: 600 },
+  }}
+>
+  Styled text
+</TextNode>
+```
+
+## Rules
+
+- **Canvas**: no — không chứa node con.
+- **Inline editing**: có thể double-click để chỉnh nội dung trực tiếp trong canvas.

package/lib/unknown/README.md

@@ -0,0 +1,48 @@
+# UnknownNode
+
+Fallback node hiển thị khi một node trong serialized data có `resolvedName` không tồn tại trong resolver.
+
+## Resolved name
+
+`Unknown`
+
+## Configurable props
+
+Không có props.
+
+## Behavior
+
+- **Render mode** (`enabled: false`): render nothing — hoàn toàn invisible.
+- **Editor mode** (`enabled: true`): hiển thị placeholder "Section is not available" kèm nút **Remove** để xóa node.
+
+## Khi nào xảy ra
+
+`Canvas` tự động thay thế node bằng `UnknownNode` khi load `SerializedNodes` mà `resolvedName` không có trong resolver:
+
+```ts
+// Trong Canvas component
+const resolvedNode = resolver[resolvedName];
+if (!resolvedNode) {
+  value.type = { resolvedName: CoreNodeResolvedEnum.Unknown };
+}
+```
+
+Thường xảy ra khi:
+- Custom node bị xóa khỏi codebase nhưng data cũ vẫn còn lưu
+- Resolver không được pass đầy đủ node types
+
+## Usage
+
+Không cần dùng trực tiếp. Được xử lý tự động bởi `Canvas`.
+
+Nếu muốn tránh `UnknownNode` xuất hiện, đảm bảo truyền đầy đủ resolver khi mount `Composer`:
+
+```tsx
+import { MyCustomNode } from './my-custom-node';
+
+<Composer resolver={{ MyCustomNode }}>
+  <Canvas data={savedNodes}>
+    <RootNode />
+  </Canvas>
+</Composer>
+```