@janbox/storefront-builder 1.0.3 → 1.0.5

package/README.md

@@ -0,0 +1,477 @@
+# @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.
+
+## Installation
+
+```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
+```
+
+## Package Exports
+
+| Import path | Contents |
+| --- | --- |
+| `@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 |
+
+---
+
+## 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).
+
+```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 type { Theme } from '@janbox/storefront-ui/theme';
+
+const myTheme: Theme = {
+  palette: {
+    primary: {
+      500: '#fa8c16',
+      600: '#d46b08',
+    },
+    // ... full theme
+  },
+  typography: {
+    base: { fontSize: '1rem', lineHeight: '1.5rem' },
+    // ...
+  },
+};
+
+export default function BuilderPage() {
+  return (
+    <Editor
+      theme={myTheme}
+      insert={{
+        elements: [LAYOUT_ELEMENT_GROUP, TEXT_ELEMENT_GROUP, MEDIA_ELEMENT_GROUP, INTERACTIVE_ELEMENT_GROUP],
+        sections: [HERO_SECTION_GROUP],
+      }}
+    />
+  );
+}
+```
+
+`Editor` occupies the full viewport (`100vw × 100vh`). It should be the root of a dedicated page/route.
+
+---
+
+## Quick Start — Render Only (No Editor UI)
+
+Use `Composer` + `Canvas` to render a saved page without the editor chrome. This is for the storefront-facing page.
+
+```tsx
+import '@janbox/storefront-builder/style.css';
+import { Composer, Canvas } from '@janbox/storefront-builder';
+import { RootNode } from '@janbox/storefront-builder';
+import type { SerializedNodes } from '@janbox/storefront-builder';
+
+const savedData: SerializedNodes = { /* JSON from editor */ };
+
+export default function StorefrontPage() {
+  return (
+    <Composer>
+      <Canvas data={savedData}>
+        <RootNode />
+      </Canvas>
+    </Composer>
+  );
+}
+```
+
+---
+
+## Core Concepts
+
+### Nodes
+
+Every element on the canvas is a **node** — a React component registered with CraftJS. The library ships 33 built-in nodes:
+
+| Category | Nodes |
+| --- | --- |
+| Layout | `RootNode`, `Box`, `Flexbox`, `FlexItem`, `Grid`, `Cell` |
+| Typography | `Text`, `Paragraph`, `Heading` |
+| Media | `Image`, `Video`, `Icon` |
+| Navigation | `Link`, `Button` |
+| Lists | `UnorderedList`, `ListItem` |
+| Tabs | `Tabs`, `TabList`, `Tab`, `TabContent`, `TabPanel` |
+| Accordion | `Accordion`, `AccordionGroup`, `AccordionSummary`, `AccordionContent` |
+| Carousel | `Swiper`, `SwiperSlide` |
+| Marquee | `Marquee`, `MarqueeItem` |
+| Utilities | `CountdownTimer` |
+| Internal | `UnknownNode` (fallback for unresolved nodes) |
+
+All nodes are exported from `@janbox/storefront-builder`.
+
+### Responsive Props
+
+All style props accept either a plain value or a responsive object keyed by breakpoint:
+
+```ts
+// Breakpoints: xs (390px), sm (768px), md (1280px), lg (1680px)
+
+// Plain value (applies at all breakpoints)
+{ fontSize: '16px' }
+
+// Responsive object (xs is the base; other keys override upward)
+{ fontSize: { xs: '14px', md: '18px' } }
+```
+
+The current breakpoint is controlled via the `?screen=xs|sm|md|lg` query param.
+
+### Serialized State
+
+The canvas state is plain JSON (`SerializedNodes` from `@craftjs/core`). Use `useComposer()` to read and serialize it:
+
+```tsx
+import { useComposer } from '@janbox/storefront-builder';
+
+function SaveButton() {
+  const { query } = useComposer();
+
+  const handleSave = () => {
+    const json = query.serialize(); // SerializedNodes as JSON string
+    // save to your backend
+  };
+
+  return <button onClick={handleSave}>Save</button>;
+}
+```
+
+---
+
+## Templates
+
+Templates are pre-configured drag-and-drop groups shown in the editor sidebar.
+
+### Element Groups (sidebar "Elements" tab)
+
+```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)
+
+```ts
+import {
+  HERO_SECTION_GROUP,
+  FAQS_SECTION_GROUP,
+  GUARANTEE_SECTION_GROUP,
+} from '@janbox/storefront-builder/templates';
+```
+
+Pass them to `Editor` via the `insert` prop:
+
+```tsx
+<Editor
+  theme={myTheme}
+  insert={{
+    elements: [LAYOUT_ELEMENT_GROUP, TEXT_ELEMENT_GROUP],
+    sections: [HERO_SECTION_GROUP],
+  }}
+/>
+```
+
+---
+
+## Custom Nodes
+
+### 1. Create a node component
+
+```tsx
+// my-badge.node.tsx
+import { defineNode } from '@janbox/storefront-builder';
+import { useNode } from '@janbox/storefront-builder';
+
+type MyBadgeProps = { label: string; color?: string };
+
+export const MyBadge = ({ label, color = '#fa8c16' }: MyBadgeProps) => {
+  const { connectors } = useNode();
+
+  return (
+    <span
+      ref={(el) => el && connectors.connect(el)}
+      style={{ background: color, padding: '2px 8px', borderRadius: 4 }}
+    >
+      {label}
+    </span>
+  );
+};
+
+defineNode(MyBadge, {
+  resolved: 'MyBadge',
+  isCanvas: false,
+  info: { displayName: 'Badge' },
+  defaultProps: { label: 'Badge', color: '#fa8c16' },
+});
+```
+
+### 2. Pass a resolver to the editor
+
+```tsx
+import { MyBadge } from './my-badge.node';
+
+<Editor
+  theme={myTheme}
+  resolver={{ MyBadge }}
+  insert={{ elements: [/* ... */], sections: [] }}
+/>
+```
+
+### 3. Add a toolbar (optional)
+
+```tsx
+// my-badge.toolbar.tsx
+import { useNodeProps } from '@janbox/storefront-builder';
+
+export function MyBadgeToolbar() {
+  const { nodeProps, setNodeProps } = useNodeProps<MyBadgeProps>();
+
+  return (
+    <div>
+      <label>Label</label>
+      <input
+        value={nodeProps.label}
+        onChange={(e) => setNodeProps({ label: e.target.value })}
+      />
+    </div>
+  );
+}
+```
+
+Register the toolbar in `defineNode`:
+
+```ts
+defineNode(MyBadge, {
+  resolved: 'MyBadge',
+  info: { displayName: 'Badge' },
+  related: { inspector: MyBadgeToolbar },
+});
+```
+
+---
+
+## Hooks
+
+All hooks must be called inside a `<Composer>` tree.
+
+### `useComposer(collector?)`
+
+Enhanced wrapper around CraftJS `useEditor`. Adds `actions.duplicate()` and `actions.move()`.
+
+```ts
+const { query, actions } = useComposer();
+
+// Serialize current canvas state
+const json = query.serialize();
+
+// Duplicate a node
+actions.duplicate(nodeId);
+
+// Move a 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.
+
+```ts
+const { nodeProps, setNodeProps, setNodeResponsiveProps } = useNodeProps<MyProps>();
+
+// Set a flat prop
+setNodeProps({ color: '#ff0000' });
+
+// Set a responsive prop for a specific breakpoint
+setNodeResponsiveProps({ fontSize: '18px' }, 'md');
+```
+
+### `useNode()`
+
+Direct access to the CraftJS node context (re-exported from `@craftjs/core`).
+
+```ts
+const { id, connectors, actions } = useNode();
+```
+
+---
+
+## TailwindCSS Integration
+
+The library uses TailwindCSS v4 internally with a `tw:` prefix. To extend it in your app:
+
+```ts
+// tailwind.config.ts
+import builderConfig from '@janbox/storefront-builder/tailwind.config';
+
+export default {
+  presets: [builderConfig],
+  // your overrides
+};
+```
+
+Import the stylesheet once at your app entry:
+
+```ts
+import '@janbox/storefront-builder/style.css';
+```
+
+---
+
+## Theme Shape
+
+The `theme` prop on `Editor` follows the `@janbox/storefront-ui` `Theme` type:
+
+```ts
+type Theme = {
+  palette: {
+    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 };
+    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;
+    lineHeight: string;
+  }>;
+};
+```
+
+---
+
+## TypeScript
+
+The package ships full `.d.ts` declarations. Key types:
+
+```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()
+  DisplayOnValue,    // responsive visibility: Partial<Record<Screen, boolean>>
+} from '@janbox/storefront-builder';
+```
+
+---
+
+## Node Reference
+
+Chi tiết props, usage và rules cho từng node:
+
+### Layout
+
+- [RootNode](lib/root/README.md) — top-level canvas container
+- [BoxNode](lib/box/README.md) — block container
+- [FlexboxNode](lib/flexbox/README.md) — flex container
+- [FlexItemNode](lib/flex-item/README.md) — flex item
+- [GridNode](lib/grid/README.md) — CSS grid container
+- [CellNode](lib/cell/README.md) — grid cell
+
+### Typography
+
+- [TextNode](lib/text/README.md) — inline/block text
+- [HeadingNode](lib/heading/README.md) — h1–h6 heading
+- [ParagraphNode](lib/paragraph/README.md) — paragraph
+
+### Media
+
+- [ImageNode](lib/image/README.md) — image
+- [VideoNode](lib/video/README.md) — video player
+- [IconNode](lib/icon/README.md) — inline SVG icon
+
+### Navigation
+
+- [LinkNode](lib/link/README.md) — anchor link
+- [ButtonNode](lib/button/README.md) — CTA button
+
+### Lists
+
+- [UnorderedListNode](lib/unordered-list/README.md) — list container
+- [ListItemNode](lib/list-item/README.md) — list item
+
+### Accordion
+
+- [AccordionGroupNode](lib/accordion-group/README.md) — accordion container
+- [AccordionNode](lib/accordion/README.md) — accordion item
+- [AccordionSummaryNode](lib/accordion-summary/README.md) — accordion header
+- [AccordionContentNode](lib/accordion-content/README.md) — accordion content
+
+### Tabs
+
+- [TabsNode](lib/tabs/README.md) — tabs container
+- [TabListNode](lib/tab-list/README.md) — tab headers container
+- [TabNode](lib/tab/README.md) — tab header button
+- [TabContentNode](lib/tab-content/README.md) — tab panels container
+- [TabPanelNode](lib/tab-panel/README.md) — tab panel content
+
+### Carousel
+
+- [SwiperNode](lib/swiper/README.md) — carousel container
+- [SwiperSlideNode](lib/swiper-slide/README.md) — carousel slide
+
+### Marquee
+
+- [MarqueeNode](lib/marquee/README.md) — auto-scrolling ticker
+- [MarqueeItemNode](lib/marquee-item/README.md) — ticker item
+
+### Utilities
+
+- [CountdownTimerNode](lib/countdown-timer/README.md) — countdown timer
+
+### Internal
+
+- [UnknownNode](lib/unknown/README.md) — fallback for unresolved nodes
+
+---
+
+## Monorepo Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start demo app (React Router 7)
+pnpm dev
+
+# Build the library
+pnpm build
+
+# Type check
+pnpm typecheck
+```
+
+Requires Node.js >= 20 and pnpm.

package/dist/editor/lib/index.d.ts

@@ -3,8 +3,8 @@ import { SidebarProps } from './sidebar';
 import { Resolver } from '../../types';
 export type EditorProps = {
     theme: Theme;
-    insert: SidebarProps['insert'];
-    resolver: Resolver;
+    insert?: SidebarProps['insert'];
+    resolver?: Resolver;
 };
 export type { InsertElementGroup, InsertSectionGroup } from './sidebar/insert-action';
-export declare const Editor: ({ theme, insert }: EditorProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const Editor: ({ theme, insert, resolver }: EditorProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/editor/lib/sidebar/index.d.ts

@@ -1,5 +1,5 @@
 import { InsertActionProps } from './insert-action';
 export type SidebarProps = {
-    insert: InsertActionProps;
+    insert?: InsertActionProps;
 };
 export declare const Sidebar: ({ insert }: SidebarProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/editor/lib/sidebar/insert-action.d.ts

@@ -20,8 +20,8 @@ export type InsertSectionGroup = {
     }[];
 };
 export interface InsertActionProps {
-    elements: InsertElementGroup[];
-    sections: InsertSectionGroup[];
+    elements?: InsertElementGroup[];
+    sections?: InsertSectionGroup[];
 }
 export declare const InsertAction: ({ elements, sections }: InsertActionProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export declare const SectionInsertionGroup: ({ group }: {

package/dist/editor/ui/dialog/dialog/helpers.d.ts

@@ -1 +1 @@
-export declare const useDialogContext: () => import('../../floating').WbFloatingContextValue;
+export declare const useDialogContext: () => import('../..').WbFloatingContextValue;

package/dist/editor/ui/dialog/dialog-close/dialog-close.d.ts

@@ -1 +1 @@
-export declare const WbDialogClose: import('react').ForwardRefExoticComponent<Omit<import('../../floating').WbFloatingCloseProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
+export declare const WbDialogClose: import('react').ForwardRefExoticComponent<Omit<import('../..').WbFloatingCloseProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;