@janbox/storefront-builder 1.0.3 → 1.0.5

package/lib/box/README.md

@@ -0,0 +1,107 @@
+# BoxNode
+
+Block container đa năng (render ra `div`). Là canvas node — chứa bất kỳ node con nào. Dùng để nhóm các element, tạo section, hay làm wrapper có background/border.
+
+## Resolved name
+
+`Box` (displayName: `Block`)
+
+## Configurable props
+
+### Top-level props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `container` | `boolean` | Bật max-width container constraint |
+
+### `sx` props
+
+```ts
+sx?: {
+  // 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 { BoxNode } from '@janbox/storefront-builder';
+
+// Wrapper đơn giản
+<BoxNode sx={{ padding: 16 }}>
+  <TextNode>Hello</TextNode>
+</BoxNode>
+
+// Section có background
+<BoxNode
+  sx={{
+    backgroundColor: '#f5f5f5',
+    paddingTop: 48,
+    paddingBottom: 48,
+  }}
+>
+  ...
+</BoxNode>
+
+// Container với responsive padding
+<BoxNode
+  container
+  sx={{
+    paddingTop: 24,
+    paddingBottom: 24,
+    md: {
+      paddingTop: 48,
+      paddingBottom: 48,
+    },
+  }}
+>
+  ...
+</BoxNode>
+
+// Box ẩn trên mobile, hiện trên desktop — dùng DisplayOn (qua editor)
+// Có thể kết hợp với sx.width/height để tạo spacer cố định
+<BoxNode sx={{ width: '100%', height: 32, md: { height: 64 } }} />
+```
+
+## Rules
+
+- **Canvas**: yes — chứa bất kỳ node con nào.
+- **canMoveIn**: không giới hạn node type.

package/lib/button/README.md

@@ -0,0 +1,94 @@
+# ButtonNode
+
+CTA button node dùng component `Button` từ `@janbox/storefront-ui`. Có thể render như button thường hoặc link button qua prop `anchor`.
+
+## Resolved name
+
+`Button`
+
+## Configurable props
+
+### Top-level props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `dangerouslySetInnerHTML.__html` | `string` | Text hiển thị trong button |
+| `color` | `ColorVariant` | Màu theme của button |
+| `variant` | `ButtonVariant` | Kiểu hiển thị của button |
+| `size` | `ButtonSizeVariant` | Kích thước button |
+| `anchor.to` | `string \| { pathname: string }` | Link destination |
+| `anchor.target` | `'_self' \| '_blank' \| '_parent' \| '_top'` | Cách mở link |
+
+`size` hỗ trợ responsive: `size="sm"` xs, `md={{ size: 'lg' }}` desktop.
+
+**`ColorVariant`:** `'primary' | 'secondary' | 'green' | 'red' | 'orange' | 'blue' | 'neutral'`
+
+**`ButtonVariant`:** `'contained' | 'outlined' | 'text'`
+
+**`ButtonSizeVariant`:** `'sm' | 'md' | 'lg'`
+
+### `sx` props
+
+```ts
+sx?: {
+  // size
+  width?: number | string
+
+  // spacing (margin only)
+  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 { ButtonNode } from '@janbox/storefront-builder';
+
+// Button cơ bản
+<ButtonNode
+  color="primary"
+  variant="contained"
+  size="md"
+  dangerouslySetInnerHTML={{ __html: 'Buy now' }}
+/>
+
+// Link button
+<ButtonNode
+  color="primary"
+  variant="contained"
+  size="lg"
+  anchor={{ to: '/checkout', target: '_self' }}
+  dangerouslySetInnerHTML={{ __html: 'Checkout' }}
+/>
+
+// Responsive size + width
+<ButtonNode
+  color="orange"
+  variant="outlined"
+  size="sm"
+  md={{ size: 'lg' }}
+  sx={{
+    width: '100%',
+    marginTop: 16,
+    md: {
+      width: 'fit-content',
+      marginTop: 24,
+    },
+  }}
+  dangerouslySetInnerHTML={{ __html: 'View products' }}
+/>
+```
+
+## Rules
+
+- **Canvas**: no — không chứa node con.
+- Khi editor đang bật, `anchor` bị unset lúc render để tránh navigate trong canvas.
+- Nội dung button được chỉnh qua `dangerouslySetInnerHTML.__html` trong inspector.

package/lib/cell/README.md

@@ -0,0 +1,119 @@
+# CellNode
+
+Một ô (column) trong `GridNode`. Hỗ trợ `colSpan` để chiếm nhiều cột. Là canvas node — chứa bất kỳ node con nào.
+
+## Resolved name
+
+`Cell`
+
+## Configurable props
+
+### Top-level props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `colSpan` | `number` | Số cột mà cell chiếm (`grid-column: span colSpan`) |
+
+`colSpan` hỗ trợ responsive: `colSpan={1}` cho mobile, `md={{ colSpan: 2 }}` cho desktop.
+
+### `sx` props
+
+```ts
+sx?: {
+  // size
+  height?: number | string
+
+  // order (thứ tự hiển thị trong grid)
+  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 { GridNode, CellNode } from '@janbox/storefront-builder';
+
+// Cell mặc định (1 cột)
+<GridNode cols={3}>
+  <CellNode>Content A</CellNode>
+  <CellNode>Content B</CellNode>
+  <CellNode>Content C</CellNode>
+</GridNode>
+
+// colSpan: cell chiếm 2/3 cột, cell còn lại chiếm 1/3
+<GridNode cols={3}>
+  <CellNode colSpan={2}>Wide content</CellNode>
+  <CellNode colSpan={1}>Narrow content</CellNode>
+</GridNode>
+
+// colSpan responsive: full-width mobile, 2 cột trên desktop
+<GridNode cols={1} md={{ cols: 3 }}>
+  <CellNode colSpan={1} md={{ colSpan: 2 }}>
+    Wide on desktop
+  </CellNode>
+  <CellNode colSpan={1}>
+    Normal
+  </CellNode>
+</GridNode>
+
+// sx responsive
+<CellNode
+  colSpan={1}
+  sx={{
+    paddingTop: 12,
+    paddingBottom: 12,
+    backgroundColor: '#fff',
+    md: {
+      paddingTop: 24,
+      paddingBottom: 24,
+    },
+  }}
+>
+  ...
+</CellNode>
+```
+
+## Rules
+
+- **Canvas**: yes — chứa bất kỳ node con nào.
+- **Parent**: phải là `GridNode`.
+
+## Related nodes
+
+- [`GridNode`](../grid/README.md) — parent bắt buộc của `CellNode`

package/lib/countdown-timer/README.md

@@ -0,0 +1,157 @@
+# CountdownTimerNode
+
+Đồng hồ đếm ngược đến một mốc thời gian. Hiển thị các time units (days, hours, minutes, seconds...) kèm caption.
+
+## Resolved name
+
+`CountdownTimer`
+
+## Configurable props
+
+### Top-level props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `date` | `Date` | Thời điểm đích để đếm ngược đến |
+| `units` | `{ value: TimeUnit; caption?: string }[]` | Danh sách time units hiển thị, theo thứ tự |
+| `hideAfterExpired` | `boolean` | Ẩn toàn bộ component sau khi hết giờ |
+
+**`TimeUnit`:** `'months' | 'weeks' | 'days' | 'hours' | 'minutes' | 'seconds'`
+
+### `unitItemProps.sx` — Styling cho mỗi unit box
+
+```ts
+unitItemProps?: {
+  sx?: {
+    width?: number | string
+    rowGap?: number           // khoảng cách giữa số và caption
+    paddingTop?: number
+    paddingRight?: number
+    paddingBottom?: number
+    paddingLeft?: number
+    backgroundColor?: string
+    borderTopLeftRadius?: number | string
+    borderTopRightRadius?: number | string
+    borderBottomLeftRadius?: number | string
+    borderBottomRightRadius?: number | string
+  }
+}
+```
+
+### `timeProps` — Styling cho số đếm
+
+```ts
+timeProps?: {
+  sizeVariant?: TypographySizeVariant   // responsive
+  sx?: {
+    color?: string
+    fontWeight?: number | string
+    fontStyle?: 'normal' | 'italic'
+    textDecorationLine?: 'none' | 'underline' | 'line-through'
+  }
+}
+```
+
+### `captionProps` — Styling cho caption (label dưới số)
+
+```ts
+captionProps?: {
+  sizeVariant?: TypographySizeVariant   // responsive
+  sx?: {
+    color?: string
+    fontWeight?: number | string
+    fontStyle?: 'normal' | 'italic'
+    textDecorationLine?: 'none' | 'underline' | 'line-through'
+    textTransform?: 'none' | 'uppercase' | 'lowercase' | 'capitalize'
+  }
+}
+```
+
+### `sx` props (outer container)
+
+```ts
+sx?: {
+  width?: number | string
+  flexWrap?: 'nowrap' | 'wrap' | 'wrap-reverse'
+
+  // 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 { CountdownTimerNode } from '@janbox/storefront-builder';
+
+// Đếm ngược đến ngày sale
+<CountdownTimerNode
+  date={new Date('2026-12-31T23:59:59')}
+  units={[
+    { value: 'days',    caption: 'Days' },
+    { value: 'hours',   caption: 'Hours' },
+    { value: 'minutes', caption: 'Mins' },
+    { value: 'seconds', caption: 'Secs' },
+  ]}
+  hideAfterExpired={false}
+  sx={{ columnGap: 8 }}
+  unitItemProps={{
+    sx: {
+      width: 64,
+      paddingTop: 8,
+      paddingBottom: 8,
+      backgroundColor: '#fa8c16',
+      borderTopLeftRadius: 8,
+      borderTopRightRadius: 8,
+      borderBottomLeftRadius: 8,
+      borderBottomRightRadius: 8,
+    },
+  }}
+  timeProps={{
+    sizeVariant: '2xl',
+    sx: { color: '#ffffff', fontWeight: 700 },
+  }}
+  captionProps={{
+    sizeVariant: 'xs',
+    sx: { color: '#ffffff', textTransform: 'uppercase' },
+  }}
+/>
+```
+
+## Rules
+
+- **Canvas**: no — không chứa node con.
+- Khi editor đang bật, component hiển thị placeholder nếu `units` rỗng hoặc đã hết giờ với `hideAfterExpired: true`.

package/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/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`