@janbox/storefront-builder 1.0.4 → 1.0.5

package/dist/lib/flex-item/README.md

@@ -0,0 +1,111 @@
+# FlexItemNode
+
+Một item trong `FlexboxNode`. Kiểm soát kích thước, grow/shrink, thứ tự của từng item trong flex container.
+
+## Resolved name
+
+`FlexItem`
+
+## Configurable props
+
+Tất cả props nằm trong `sx`. Không có top-level prop riêng.
+
+### `sx` props
+
+```ts
+sx?: {
+  // flex item behavior
+  flexGrow?: number     // auto grow: 1 = bật, undefined = tắt
+  flexShrink?: number   // auto shrink: 0 = tắt, undefined = bật
+
+  // size
+  width?: number | string
+  height?: number | string
+
+  // order (thứ tự hiển thị)
+  order?: 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 { FlexboxNode, FlexItemNode } from '@janbox/storefront-builder';
+
+// Item cố định width, item còn lại grow để fill
+<FlexboxNode sx={{ flexDirection: 'row', columnGap: 16 }}>
+  <FlexItemNode sx={{ width: 200 }}>Sidebar</FlexItemNode>
+  <FlexItemNode sx={{ flexGrow: 1 }}>Main content</FlexItemNode>
+</FlexboxNode>
+
+// Item không shrink khi container hẹp
+<FlexboxNode sx={{ flexDirection: 'row' }}>
+  <FlexItemNode sx={{ flexShrink: 0, width: 120 }}>Fixed</FlexItemNode>
+  <FlexItemNode sx={{ flexGrow: 1 }}>Flexible</FlexItemNode>
+</FlexboxNode>
+
+// Responsive: full width mobile, 50% desktop
+<FlexboxNode sx={{ flexDirection: 'column', md: { flexDirection: 'row' } }}>
+  <FlexItemNode
+    sx={{
+      width: '100%',
+      md: { width: '50%' },
+    }}
+  >
+    Left
+  </FlexItemNode>
+  <FlexItemNode
+    sx={{
+      width: '100%',
+      md: { width: '50%' },
+    }}
+  >
+    Right
+  </FlexItemNode>
+</FlexboxNode>
+```
+
+## Rules
+
+- **Canvas**: yes — chứa bất kỳ node con nào.
+- **Parent**: phải là `FlexboxNode`.
+
+## Related nodes
+
+- [`FlexboxNode`](../flexbox/README.md) — parent bắt buộc của `FlexItemNode`

package/dist/lib/flexbox/README.md

@@ -0,0 +1,120 @@
+# FlexboxNode
+
+Flex container node (`display: flex`). Chỉ chấp nhận `FlexItemNode` làm con trực tiếp.
+
+## Resolved name
+
+`Flexbox`
+
+## Configurable props
+
+### Top-level props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `container` | `boolean` | Bật max-width container constraint |
+
+### `sx` props
+
+```ts
+sx?: {
+  // flex layout
+  flexDirection?: 'row' | 'column'
+  flexWrap?: 'nowrap' | 'wrap' | 'wrap-reverse'
+  justifyContent?: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly'
+  alignItems?: 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline'
+  rowGap?: number
+  columnGap?: number
+
+  // size
+  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 { FlexboxNode, FlexItemNode } from '@janbox/storefront-builder';
+
+// Row ngang, căn giữa dọc
+<FlexboxNode sx={{ flexDirection: 'row', alignItems: 'center', columnGap: 16 }}>
+  <FlexItemNode>Item A</FlexItemNode>
+  <FlexItemNode>Item B</FlexItemNode>
+</FlexboxNode>
+
+// Đổi direction theo breakpoint: column trên mobile, row trên desktop
+<FlexboxNode
+  sx={{
+    flexDirection: 'column',
+    rowGap: 12,
+    md: {
+      flexDirection: 'row',
+      columnGap: 24,
+      alignItems: 'center',
+    },
+  }}
+>
+  <FlexItemNode>Item A</FlexItemNode>
+  <FlexItemNode>Item B</FlexItemNode>
+</FlexboxNode>
+
+// Space-between, wrap
+<FlexboxNode
+  sx={{
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    justifyContent: 'space-between',
+    rowGap: 16,
+  }}
+>
+  <FlexItemNode>Item A</FlexItemNode>
+  <FlexItemNode>Item B</FlexItemNode>
+  <FlexItemNode>Item C</FlexItemNode>
+</FlexboxNode>
+```
+
+## Rules
+
+- **Canvas**: yes.
+- **canMoveIn**: chỉ chấp nhận `FlexItemNode`.
+
+## Related nodes
+
+- [`FlexItemNode`](../flex-item/README.md) — con trực tiếp duy nhất của `FlexboxNode`

package/dist/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/dist/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/dist/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/dist/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.