@janbox/storefront-builder 1.0.3 → 1.0.5

package/lib/grid/README.md

@@ -0,0 +1,133 @@
+# GridNode
+
+A CSS Grid container node. Accepts only `CellNode` children — the editor enforces this via `canMoveIn`.
+
+## Resolved name
+
+`Grid`
+
+## Configurable props
+
+Props mà user có thể chỉnh trong editor inspector. Tất cả đều hỗ trợ responsive trừ `container`.
+
+### Top-level props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `cols` | `number` | Số cột — generates `grid-template-columns: repeat(cols, minmax(0, 1fr))` |
+| `container` | `boolean` | Bật max-width container constraint |
+
+### `sx` props
+
+`sx` nhận `StyledCSS` với responsive keys `sm`, `md`, `lg` bên trong:
+
+```ts
+sx?: {
+  // layout
+  columnGap?: number
+  rowGap?: number
+  alignItems?: 'start' | 'center' | 'end' | 'stretch'
+  justifyItems?: 'start' | 'center' | 'end' | 'stretch'
+  width?: number | string
+  height?: 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 { GridNode, CellNode } from '@janbox/storefront-builder';
+
+// 2 cột cố định
+<GridNode cols={2}>
+  <CellNode>...</CellNode>
+  <CellNode>...</CellNode>
+</GridNode>
+
+// Responsive: 1 cột mobile, 3 cột desktop
+<GridNode cols={1} md={{ cols: 3 }}>
+  <CellNode>...</CellNode>
+  <CellNode>...</CellNode>
+  <CellNode>...</CellNode>
+</GridNode>
+
+// sx responsive: gap nhỏ trên mobile, lớn hơn trên desktop
+<GridNode
+  cols={1}
+  md={{ cols: 2 }}
+  sx={{
+    columnGap: 8,
+    rowGap: 8,
+    paddingTop: 16,
+    paddingBottom: 16,
+    md: {
+      columnGap: 24,
+      rowGap: 24,
+      paddingTop: 32,
+      paddingBottom: 32,
+    },
+  }}
+>
+  <CellNode>...</CellNode>
+  <CellNode>...</CellNode>
+</GridNode>
+
+// Container với background
+<GridNode
+  container
+  cols={2}
+  sx={{
+    backgroundColor: '#f5f5f5',
+    paddingTop: 32,
+    paddingBottom: 32,
+  }}
+>
+  <CellNode>...</CellNode>
+  <CellNode>...</CellNode>
+</GridNode>
+```
+
+## Rules
+
+- **Canvas**: yes — accepts dropped children.
+- **canMoveIn**: only `CellNode` children are allowed.
+
+## Related nodes
+
+- [`CellNode`](../cell/README.md) — the only valid direct child of `GridNode`

package/lib/heading/README.md

@@ -0,0 +1,53 @@
+# HeadingNode
+
+Text node dành cho tiêu đề. Dùng chung `TextInspector` với `TextNode` nhưng giới hạn tag trong `h1`–`h6` và `div`.
+
+## Resolved name
+
+`Heading`
+
+## Configurable props
+
+Giống hệt `TextNode`. Xem chi tiết tại [TextNode](../text/README.md#configurable-props).
+
+### Điểm khác biệt
+
+| Prop | Giá trị cho phép | Default |
+| --- | --- | --- |
+| `as` | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6' \| 'div'` | `'p'` (từ Text) |
+
+## Usage
+
+```tsx
+import { HeadingNode } from '@janbox/storefront-builder';
+
+// H1 mặc định
+<HeadingNode as="h1" sizeVariant="4xl">
+  Page Title
+</HeadingNode>
+
+// Responsive size
+<HeadingNode
+  as="h2"
+  sizeVariant="2xl"
+  md={{ sizeVariant: '4xl' }}
+  sx={{ color: '#111111', textAlign: 'center' }}
+>
+  Section Title
+</HeadingNode>
+
+// Dùng div khi không cần semantic heading nhưng muốn style heading
+<HeadingNode as="div" sizeVariant="xl" sx={{ fontWeight: 700 }}>
+  Display text
+</HeadingNode>
+```
+
+## Rules
+
+- **Canvas**: no — không chứa node con.
+- **Inline editing**: có thể double-click để chỉnh nội dung trong canvas.
+
+## Related nodes
+
+- [`TextNode`](../text/README.md) — base component dùng chung inspector
+- [`ParagraphNode`](../paragraph/README.md) — dành cho nội dung dạng đoạn văn

package/lib/icon/README.md

@@ -0,0 +1,98 @@
+# IconNode
+
+SVG icon node. Render inline SVG từ raw string hoặc URL.
+
+## Resolved name
+
+`Icon`
+
+## Configurable props
+
+### Top-level props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `source` | `string` | Raw SVG string hoặc URL tới file SVG |
+| `size` | `number` | Kích thước icon (px) — set cả `width` và `height` |
+
+`size` hỗ trợ responsive: `size={24}` xs, `md={{ size: 32 }}` desktop.
+
+### `sx` props
+
+```ts
+sx?: {
+  // color (áp dụng toàn breakpoint — không responsive)
+  color?: 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
+
+  // responsive overrides
+  sm?: { /* same keys above */ }
+  md?: { /* same keys above */ }
+  lg?: { /* same keys above */ }
+}
+```
+
+## Usage
+
+```tsx
+import { IconNode } from '@janbox/storefront-builder';
+
+// Icon từ raw SVG
+<IconNode
+  source='<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="..."/></svg>'
+  size={24}
+  sx={{ color: '#333333' }}
+/>
+
+// Responsive size
+<IconNode
+  source="https://example.com/icon.svg"
+  size={20}
+  md={{ size: 28 }}
+  sx={{ color: '#fa8c16' }}
+/>
+
+// Icon với background tròn
+<IconNode
+  source='<svg>...</svg>'
+  size={16}
+  sx={{
+    color: '#ffffff',
+    paddingTop: 8,
+    paddingBottom: 8,
+    paddingLeft: 8,
+    paddingRight: 8,
+    backgroundColor: '#fa8c16',
+    borderTopLeftRadius: '50%',
+    borderTopRightRadius: '50%',
+    borderBottomLeftRadius: '50%',
+    borderBottomRightRadius: '50%',
+  }}
+/>
+```
+
+## Rules
+
+- **Canvas**: no — không chứa node con.
+- `source` bắt buộc phải có — nếu không có, icon sẽ không hiển thị.

package/lib/image/README.md

@@ -0,0 +1,107 @@
+# ImageNode
+
+Image node render ra `<img>`. Không chứa node con.
+
+## Resolved name
+
+`Image`
+
+## Configurable props
+
+### Top-level props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `src` | `string` | URL ảnh |
+| `alt` | `string` | Alt text cho SEO và accessibility |
+| `loading` | `'eager' \| 'lazy'` | Preload: `'eager'` = tải ngay, `'lazy'` = lazy load (default) |
+
+### `sx` props
+
+```ts
+sx?: {
+  // size
+  width?: number | string
+  height?: number | string    // chỉ hiển thị khi aspectRatio là 'auto'
+
+  // aspect ratio
+  aspectRatio?: 'auto' | '1 / 1' | '16 / 9' | '9 / 16' | string  // ví dụ custom: '4 / 3'
+
+  // object fit (áp dụng toàn breakpoint — không responsive)
+  objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down'
+
+  // 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
+
+  // responsive overrides
+  sm?: { /* same keys above */ }
+  md?: { /* same keys above */ }
+  lg?: { /* same keys above */ }
+}
+```
+
+> Khi `aspectRatio` được set (khác `auto`), prop `height` bị ẩn trong inspector vì chiều cao tự tính từ ratio.
+
+## Usage
+
+```tsx
+import { ImageNode } from '@janbox/storefront-builder';
+
+// Ảnh cơ bản
+<ImageNode
+  src="https://example.com/photo.jpg"
+  alt="Product photo"
+  loading="lazy"
+  sx={{ width: '100%', objectFit: 'cover' }}
+/>
+
+// Tỉ lệ 16:9, full width
+<ImageNode
+  src="https://example.com/banner.jpg"
+  alt="Banner"
+  sx={{
+    width: '100%',
+    aspectRatio: '16 / 9',
+    objectFit: 'cover',
+  }}
+/>
+
+// Thumbnail vuông, responsive width
+<ImageNode
+  src="https://example.com/thumb.jpg"
+  alt="Thumbnail"
+  sx={{
+    width: 80,
+    aspectRatio: '1 / 1',
+    objectFit: 'cover',
+    borderTopLeftRadius: 8,
+    borderTopRightRadius: 8,
+    borderBottomLeftRadius: 8,
+    borderBottomRightRadius: 8,
+    md: { width: 120 },
+  }}
+/>
+```
+
+## Rules
+
+- **Canvas**: no — không chứa node con.

package/lib/link/README.md

@@ -0,0 +1,111 @@
+# LinkNode
+
+Anchor node render ra `<a>` qua React Router `Link`. Là canvas node — có thể chứa text hoặc các node con khác làm nội dung link.
+
+## Resolved name
+
+`Link`
+
+## Configurable props
+
+### Top-level props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `to` | `string \| { pathname: string }` | Đường dẫn điều hướng |
+| `target` | `'_self' \| '_blank' \| '_parent' \| '_top'` | Cách mở link |
+| `rel` | `string` | SEO attribute, ví dụ `'nofollow noreferrer'` |
+| `textVariant` | `TypographySizeVariant` | Preset typography size từ theme |
+
+`textVariant` hỗ trợ responsive: `textVariant="sm"` xs, `md={{ textVariant: 'base' }}` 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'
+
+  // 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
+
+  // responsive overrides
+  sm?: { /* same keys above */ }
+  md?: { /* same keys above */ }
+  lg?: { /* same keys above */ }
+}
+```
+
+## Usage
+
+```tsx
+import { LinkNode } from '@janbox/storefront-builder';
+
+// Link đơn giản
+<LinkNode to="/products">View all products</LinkNode>
+
+// Mở tab mới, no-follow
+<LinkNode to="https://example.com" target="_blank" rel="nofollow noreferrer">
+  External link
+</LinkNode>
+
+// Link dạng button (có border, padding)
+<LinkNode
+  to="/checkout"
+  sx={{
+    paddingTop: 12,
+    paddingBottom: 12,
+    paddingLeft: 24,
+    paddingRight: 24,
+    borderTopLeftRadius: 6,
+    borderTopRightRadius: 6,
+    borderBottomLeftRadius: 6,
+    borderBottomRightRadius: 6,
+    backgroundColor: '#fa8c16',
+    color: '#ffffff',
+  }}
+>
+  Checkout
+</LinkNode>
+
+// textVariant responsive
+<LinkNode to="/sale" textVariant="sm" md={{ textVariant: 'base' }}>
+  Sale items
+</LinkNode>
+```
+
+## Rules
+
+- **Canvas**: yes — chứa node con.
+- **canMoveIn**: bị block khi prop `dangerouslySetInnerHTML` đang được dùng.
+- Editor preview: click bị `preventDefault` khi editor đang bật để tránh navigate.
+
+## Related nodes
+
+- [`ButtonNode`](../button/README.md) — dùng khi cần CTA có style button từ theme

package/lib/list-item/README.md

@@ -0,0 +1,31 @@
+# ListItemNode
+
+Một item trong `UnorderedListNode` (`li`). Là canvas node — chứa bất kỳ node con nào.
+
+## Resolved name
+
+`ListItem`
+
+## Configurable props
+
+Không có props riêng. Styling được control qua parent `UnorderedListNode`.
+
+## Usage
+
+```tsx
+import { ListItemNode, TextNode } from '@janbox/storefront-builder';
+
+<ListItemNode>
+  <TextNode>Item content</TextNode>
+</ListItemNode>
+```
+
+## Rules
+
+- **Canvas**: yes — chứa bất kỳ node con nào.
+- **Selectable**: no — chỉnh sửa qua parent `UnorderedListNode` inspector.
+- **Parent**: phải là `UnorderedListNode`.
+
+## Related nodes
+
+- [`UnorderedListNode`](../unordered-list/README.md) — parent list container

package/lib/marquee/README.md

@@ -0,0 +1,111 @@
+# MarqueeNode
+
+Auto-scrolling ticker/marquee container dùng Embla Carousel Auto Scroll. Chỉ chấp nhận `MarqueeItemNode` children.
+
+## Resolved name
+
+`Marquee`
+
+## Configurable props
+
+### Top-level props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `spaceBetween` | `number` | Khoảng cách giữa các items (px) |
+| `autoScrollOptions` | `AutoScrollOptionsType` | Options từ embla-carousel-auto-scroll |
+| `separatorIcon.source` | `string` | Raw SVG string cho icon phân cách giữa các items |
+| `separatorIcon.size` | `number` | Kích thước separator icon (px) |
+| `separatorIcon.sx.color` | `string` | Màu separator icon |
+
+`spaceBetween` hỗ trợ responsive.
+
+> Editor tự động set `autoScrollOptions.playOnInit = false` khi đang trong edit mode để tránh scroll khi đang drag/drop.
+
+### `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 { MarqueeNode, MarqueeItemNode, ImageNode } from '@janbox/storefront-builder';
+
+// Marquee cơ bản, auto-scroll từ đầu
+<MarqueeNode
+  spaceBetween={32}
+  autoScrollOptions={{ speed: 1 }}
+>
+  <MarqueeItemNode><ImageNode src="..." alt="Logo 1" sx={{ width: 100 }} /></MarqueeItemNode>
+  <MarqueeItemNode><ImageNode src="..." alt="Logo 2" sx={{ width: 100 }} /></MarqueeItemNode>
+  <MarqueeItemNode><ImageNode src="..." alt="Logo 3" sx={{ width: 100 }} /></MarqueeItemNode>
+</MarqueeNode>
+
+// Với separator icon giữa các item
+<MarqueeNode
+  spaceBetween={24}
+  separatorIcon={{
+    source: '<svg>...</svg>',
+    size: 16,
+    sx: { color: '#fa8c16' },
+  }}
+>
+  <MarqueeItemNode>Item 1</MarqueeItemNode>
+  <MarqueeItemNode>Item 2</MarqueeItemNode>
+</MarqueeNode>
+
+// Responsive spacing
+<MarqueeNode
+  spaceBetween={16}
+  md={{ spaceBetween: 32 }}
+>
+  <MarqueeItemNode>...</MarqueeItemNode>
+</MarqueeNode>
+```
+
+## Rules
+
+- **Canvas**: yes — chứa `MarqueeItemNode` children.
+- **canMoveIn**: chỉ chấp nhận `MarqueeItemNode`.
+
+## Related nodes
+
+- [`MarqueeItemNode`](../marquee-item/README.md) — mỗi item trong marquee

package/lib/marquee-item/README.md

@@ -0,0 +1,31 @@
+# MarqueeItemNode
+
+Một item trong `MarqueeNode`. Là canvas node — chứa bất kỳ node con nào.
+
+## Resolved name
+
+`MarqueeItem`
+
+## Configurable props
+
+Không có props riêng. Styling được control qua parent `MarqueeNode`.
+
+## Usage
+
+```tsx
+import { MarqueeItemNode, ImageNode, TextNode } from '@janbox/storefront-builder';
+
+<MarqueeItemNode>
+  <ImageNode src="..." alt="Brand logo" sx={{ width: 80, height: 40, objectFit: 'contain' }} />
+</MarqueeItemNode>
+```
+
+## Rules
+
+- **Canvas**: yes — chứa bất kỳ node con nào.
+- **Selectable**: no — chỉnh sửa qua parent `MarqueeNode` inspector.
+- **Parent**: phải là `MarqueeNode`.
+
+## Related nodes
+
+- [`MarqueeNode`](../marquee/README.md) — parent scrolling container