@onexapis/cli 1.1.38 → 1.1.40

package/templates/default/CLAUDE.md

@@ -2,6 +2,59 @@
 
 This file provides context to AI assistants (Claude, Cursor, Copilot) for developing OneX themes.
 
+## MANDATORY WORKFLOW — USE MCP TOOLS FIRST
+
+**You MUST use the `onexthm` MCP tools as your PRIMARY workflow for all theme development tasks. Do NOT write section files manually when a tool can generate them.**
+
+### Required tool usage
+
+| Task                               | MUST use                              | Why                                                                 |
+| ---------------------------------- | ------------------------------------- | ------------------------------------------------------------------- |
+| Create a new section               | `onexthm_create_section`              | Guarantees correct file structure, schema, data attributes, imports |
+| Convert HTML/React code to section | `onexthm_from_html`                   | Parses HTML elements and maps to OneX components automatically      |
+| Convert Figma design to section    | `onexthm_from_figma` + `figma` tools  | Extracts layout, colors, typography from design                     |
+| Generate schema from description   | `onexthm_generate_schema`             | Infers category, fields, blocks, data requirements                  |
+| Validate theme                     | `onexthm_validate`                    | Catches missing data attributes, wrong imports, structural errors   |
+| Look up hooks                      | `onexthm_list_hooks`                  | Shows all 44 hooks with params, returns, and examples               |
+| Look up components                 | Read `onexthm://components` resource  | Shows all component types, fields, slots                            |
+| Look up field types                | Read `onexthm://field-types` resource | Shows all 25 field types with options                               |
+| Look up rules                      | Read `onexthm://rules` resource       | Shows DOs/DON'Ts and patterns                                       |
+
+### Workflow for creating sections
+
+1. **From a description**: Use `onexthm_generate_schema` or `onexthm_create_section`
+2. **From HTML/React code**: Use `onexthm_from_html` — it parses headings, paragraphs, buttons, images, lists, etc. and maps them to OneX components
+3. **From Figma design**: Use `figma:get_metadata` → `onexthm_from_figma`
+4. **Always validate after**: Use `onexthm_validate`
+5. **Then customize**: Edit the generated files to refine layout and styling
+
+### When you have HTML/React code to convert
+
+If the user provides HTML, JSX, or a React component, ALWAYS use `onexthm_from_html` first:
+
+```
+onexthm_from_html({
+  htmlCode: "<the HTML/JSX code>",
+  sectionName: "section-name",
+  category: "hero"  // optional
+})
+```
+
+This automatically:
+
+- Maps `<h1>`-`<h6>` → heading components
+- Maps `<p>`, `<span>` → paragraph components
+- Maps `<button>`, `<a class="btn">` → button components
+- Maps `<img>` → image components
+- Maps `<svg>`, icons → icon components
+- Maps `<ul>/<ol>` → list components
+- Maps `<hr>` → divider components
+- Detects repeating patterns → block definitions
+- Extracts Tailwind classes → layout settings
+- Generates schema + component + index files
+
+---
+
 ## CRITICAL RULES — READ FIRST
 
 **IMPORTANT: When creating new sections, blocks, or modifying theme code, you MUST follow these rules. Violations will cause the editor and storefront to break.**
@@ -10,7 +63,7 @@ This file provides context to AI assistants (Claude, Cursor, Copilot) for develo
 
 Every section MUST use `ComponentRenderer` and `BlockRenderer` from `@onexapis/core` to render content. Sections define LAYOUT only — all content (text, images, buttons) is rendered through Blocks and Components.
 
-You can use `onexthm_create_section` MCP tool or `onexthm create:section` CLI to scaffold, but if writing manually, every section MUST have:
+Use `onexthm_create_section` MCP tool or `onexthm create:section` CLI to scaffold. If writing manually, every section MUST have:
 
 1. **`"use client"` directive** at the top
 2. **Import from `@onexapis/core/renderers`** — use `ComponentRenderer` and `BlockRenderer`
@@ -369,7 +422,7 @@ import {
 | **State** (3)     | `useCart`, `useAuth`, `useOrders`                                                                                                                                                                  |
 | **Checkout** (8)  | `useCheckout`, `usePayment`, `useOrderLookup`, `useOrderStatus`, `useOrderSuccess`, `useOrderSummary`, `useFinance`, `saveBuyNowItem`                                                              |
 | **Products** (3)  | `useSearchProducts`, `useAddToCart`, `useProductDetail`                                                                                                                                            |
-| **Theme** (8)     | `useDesignSystem`, `useCommerceData`, `useThemeMode`, `useLocale`, `useViewport`, `usePageData`, `useWebsiteSettings`, `useMotion`                                                                 |
+| **Theme** (9)     | `useDesignSystem`, `usePageBackground`, `useCommerceData`, `useThemeMode`, `useLocale`, `useViewport`, `usePageData`, `useWebsiteSettings`, `useMotion`                                            |
 | **Utilities** (7) | `useDebounce`, `useMediaQuery`, `useIsMobile`, `useIsTablet`, `useIsDesktop`, `useContactForm`, `useCopyToClipboard`, `useFormatPrice`, `formatVndPrice`                                           |
 | **Animation** (1) | `useFlyToCart`                                                                                                                                                                                     |
 | **Server** (4)    | `fetchProducts`, `fetchBlogs`, `fetchSettings`, `prefetchSectionData`                                                                                                                              |
@@ -408,6 +461,198 @@ const { formatPrice } = useFormatPrice();
 formatPrice(1250000); // "1.250.000đ"
 ```
 
+### Orders & Payment Hooks
+
+These hooks cover the full order lifecycle: creating orders, looking up orders, processing payments, and displaying order history.
+
+#### `useOrders` — Order state management (Zustand)
+
+```tsx
+import { useOrders } from "@onexapis/core/hooks";
+
+const {
+  orders, // Order[] — list of orders
+  currentOrder, // Order | null — single order detail
+  isLoading,
+  error,
+  total,
+  totalPages,
+  currentPage,
+
+  // Actions
+  createOrder, // (data: CreateOrderData) => Promise<Order>
+  createPrivateOrder, // (data: CreateOrderData) => Promise<Order> — requires auth
+  fetchOrders, // (params?) => Promise<void> — public order list
+  fetchOrderHistory, // (params?) => Promise<void> — authenticated user's orders
+  fetchOrderById, // (orderId: string) => Promise<void>
+  fetchOrderByNumber, // (orderNumber: string) => Promise<void>
+  updateOrderStatus, // (orderId, status) => Promise<void>
+  cancelOrder, // (orderId) => Promise<void>
+  payOrder, // (orderId, paymentData?) => Promise<Order> — returns updated order
+  clearError,
+  clearCurrentOrder,
+} = useOrders();
+```
+
+**`payOrder` returns the updated `Order`** — always check `order.status` and `order.payment_status` before navigating to success. Do NOT blindly redirect after calling `payOrder`.
+
+#### `useOrderLookup` — Search/track order by number or ID
+
+```tsx
+import { useOrderLookup } from "@onexapis/core/hooks";
+
+// Basic — manual search via input
+const lookup = useOrderLookup();
+
+// With auto-fetch from URL route param (for dynamic pages like /order-lookup/[orderId])
+const routeParams = (data?.routeParams || {}) as Record<string, string>;
+const lookup = useOrderLookup({
+  initialOrderId: routeParams.orderId, // auto-fetches on mount
+});
+
+// lookup.orderNumber        — input value (string)
+// lookup.setOrderNumber     — update input
+// lookup.handleTrackOrder   — search (auto-detects UUID vs order number)
+// lookup.handleClear        — reset search
+// lookup.order              — Order | null (result)
+// lookup.isSearching        — boolean
+// lookup.errorMessage       — string | null
+// lookup.getStatusLabel     — (status: string) => Vietnamese label
+// lookup.formatCurrency     — (amount: number) => "1.250.000đ"
+```
+
+**Dynamic page setup** for `/order-lookup/[orderId]`:
+
+```typescript
+// pages/order-lookup.ts
+export const orderLookupPageConfig = {
+  handle: "order-lookup",
+  path: "/order-lookup/[orderId]",
+  isDynamic: true,
+  dynamicSegments: ["orderId"],
+  type: "custom",
+  // ...sections
+};
+```
+
+#### `usePayment` — QR code payment with bank transfer
+
+```tsx
+import { usePayment } from "@onexapis/core/hooks";
+
+const payment = usePayment({
+  successRedirectUrl: "/order-success", // default
+  checkoutRedirectUrl: "/checkout", // default — redirect if no order info
+  isEditing: false,
+});
+
+// payment.orderId, payment.orderNumber, payment.total
+// payment.qrCodeImage       — data URI for QR code
+// payment.qrNote            — transfer note (e.g. "DH4X7K2M")
+// payment.bankTransferData  — { accountNumber, accountName, bankName }
+// payment.isLoading, payment.isProcessing, payment.error
+// payment.handleConfirmPayment  — calls payOrder API, checks response, then redirects
+// payment.handleCancel          — clears order info, redirects to checkout
+```
+
+**`handleConfirmPayment` validates the API response:**
+
+- Checks `order.status` — blocks redirect if `failed`, `cancelled`, or `refunded`
+- Checks `order.payment_status` — blocks redirect if `failed`
+- Only navigates to success page when payment is valid
+- Shows error message from API on failure
+
+#### `useOrderSuccess` — Post-purchase success page
+
+```tsx
+import { useOrderSuccess } from "@onexapis/core/hooks";
+
+const success = useOrderSuccess();
+// success.orderId, success.orderNumber, success.displayOrderNumber
+// success.trackOrderUrl     — link to order lookup page
+// success.hasOrder          — boolean (false if no order in URL params)
+```
+
+#### `useOrderSummary` — Calculate order totals
+
+```tsx
+import { useOrderSummary, calculateOrderTotal } from "@onexapis/core/hooks";
+
+const summary = useOrderSummary({
+  vatRate: 0.1,
+  shippingFee: 30000,
+  discount: 0,
+  freeShippingThreshold: 500000,
+});
+// summary.subtotal, summary.discount, summary.shipping, summary.vat, summary.total
+// summary.formatPrice(amount)
+
+// Standalone helper (no hook needed)
+const total = calculateOrderTotal(items, { vatRate: 0.1, shippingFee: 30000 });
+```
+
+#### `useOrderStatus` — Status label translation
+
+```tsx
+import { useOrderStatus, getOrderStatusLabel } from "@onexapis/core/hooks";
+
+const { getLabel, getPaymentLabel } = useOrderStatus();
+getLabel("shipping"); // "Đang giao hàng"
+getLabel("completed"); // "Hoàn thành"
+getPaymentLabel("paid"); // "Đã thanh toán"
+
+// Or use the standalone function
+getOrderStatusLabel("pending"); // "Chờ xử lý"
+```
+
+#### `useOrderListPage` — Order history page
+
+```tsx
+import { useOrderListPage } from "@onexapis/core/hooks";
+
+const orderList = useOrderListPage({ autoFetch: true, collapsedItemCount: 2 });
+// orderList.orders          — Order[]
+// orderList.isLoading, orderList.error
+// orderList.toggleOrder     — expand/collapse order items
+// orderList.refresh         — re-fetch orders
+// orderList.getDisplayItems — get visible items (respects collapsed state)
+// orderList.hasMoreItems    — check if order has hidden items
+// orderList.formatCurrency, orderList.formatDate
+```
+
+#### Order Type Reference
+
+```typescript
+interface Order {
+  id: string;
+  order_number: string;
+  status: string; // pending | confirmed | processing | packing | shipping | completed | cancelled | failed | refunded
+  payment_status?: string; // paid | unpaid | failed
+  payment_method?: string;
+  total: number;
+  sub_total?: number;
+  tax?: number;
+  shipping_fee?: number;
+  discount?: number;
+  order_line_items?: OrderLineItem[];
+  shipping_address?: OrderAddress;
+  note?: string;
+  created_at: string;
+  updated_at?: string;
+}
+
+interface OrderLineItem {
+  name: string;
+  unit_price: number;
+  quantity: number;
+  product_id: string;
+  variant_name?: string;
+  image_url?: string;
+  sku?: string;
+  location?: { id: string; name: string };
+}
+```
+
 ## Color System
 
 Colors in OneX themes work with **two approaches** (both are valid):
@@ -836,6 +1081,147 @@ export function MySection({ section, isEditing }: SectionComponentProps) {
 }
 ```
 
+## Page Background System
+
+Every page has a background that comes from the theme by default, overridable per-page. This is a **page-level** feature (not section-level) — it wraps all sections on the page.
+
+### How it works
+
+Background is resolved with priority:
+
+1. **Per-page override** (`PageConfig.background`) — set via editor or page config
+2. **Theme default** (`ThemeDesignSystem.pageBackground`) — set in `theme.layout.ts`
+3. **Fallback** — solid white `#FFFFFF`
+
+### Setting the theme default
+
+In `theme.layout.ts`, add `pageBackground` inside `designSystem`:
+
+```typescript
+export const layoutConfig: ThemeLayoutConfig = {
+  // ...headerSections, footerSections...
+  designSystem: {
+    colors: {
+      primaryColor: "#3B82F6",
+      secondaryColor: "#8B5CF6",
+      colorMode: "light",
+    },
+    typography: { headingFont: "system-ui", bodyFont: "system-ui" },
+    layout: { spacing: "comfortable" },
+    pageBackground: {
+      type: "solid", // "solid" | "gradient" | "image" | "pattern" | "none"
+      color: "#FFFFFF", // Base background color
+    },
+  },
+};
+```
+
+### Background types
+
+| Type       | Fields                                                                  | Example                                                                       |
+| ---------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `solid`    | `color`                                                                 | `{ type: "solid", color: "#FFF8F0" }`                                         |
+| `gradient` | `gradient`, `color` (fallback)                                          | `{ type: "gradient", gradient: "linear-gradient(135deg, #667eea, #764ba2)" }` |
+| `image`    | `image`, `imageSize`, `imagePosition`, `imageFixed`, `color` (fallback) | `{ type: "image", image: "/bg.jpg", imageSize: "cover", imageFixed: true }`   |
+| `pattern`  | `pattern`, `color`, `opacity`, `overlayColor`                           | `{ type: "pattern", pattern: "dots", color: "#FAFAFA", opacity: 0.05 }`       |
+| `none`     | —                                                                       | `{ type: "none" }` (transparent, no wrapper)                                  |
+
+### Built-in CSS patterns
+
+These work out of the box with `type: "pattern"`:
+
+- `dots` — dot grid
+- `grid` — line grid
+- `diagonal-lines` — 45-degree stripes
+- `cross-dots` — offset dot grid
+- `noise` — fractal noise texture
+
+### Custom animated patterns
+
+Themes can provide custom pattern renderers (e.g., SVG-based animated backgrounds). Export the component from `bundle-entry.ts`:
+
+```typescript
+// In bundle-entry.ts
+export { SenBackground } from "./assets/sen-background";
+```
+
+The storefront will pick up exported `*Background` components and match them to pattern names. For example, `SenBackground` maps to `pattern: "sen"`.
+
+Custom pattern components receive these props:
+
+```typescript
+interface PatternProps {
+  opacity?: number; // Pattern opacity (default: 0.05)
+  color?: string; // Overlay color
+  className?: string; // Additional CSS classes
+}
+```
+
+### Per-page override
+
+In a page config (e.g., `pages/about.ts`), set `background`:
+
+```typescript
+export const aboutPageConfig = {
+  title: "About",
+  handle: "about",
+  // ...other config...
+  background: {
+    type: "gradient",
+    gradient: "linear-gradient(180deg, #EEF2FF 0%, #FFFFFF 50%)",
+  },
+};
+```
+
+### Accessing in sections via hook
+
+Use `usePageBackground()` to read the resolved background in section components:
+
+```tsx
+import { usePageBackground } from "@onexapis/core/hooks";
+
+export function MySection({ section }: SectionComponentProps) {
+  const { config, styles, hasPattern, pattern, patternOpacity } =
+    usePageBackground();
+  // config.type — "solid" | "gradient" | "image" | "pattern" | "none"
+  // config.color — base color
+  // styles — React.CSSProperties derived from config
+  // hasPattern — boolean, true if type === "pattern" && pattern is set
+  // pattern — pattern name (e.g., "sen", "dots")
+  // patternOpacity — number (0-1)
+}
+```
+
+### PageBackgroundConfig type reference
+
+```typescript
+interface PageBackgroundConfig {
+  type: "solid" | "gradient" | "image" | "pattern" | "none";
+  color?: string; // Base background color (hex/CSS)
+  gradient?: string; // CSS gradient value
+  image?: string; // Background image URL
+  imageSize?: "cover" | "contain" | "auto";
+  imagePosition?: string; // CSS background-position (default: "center")
+  imageFixed?: boolean; // Fixed background attachment
+  pattern?: string; // Pattern identifier
+  opacity?: number; // Pattern/overlay opacity (0-1, default: 0.05)
+  overlayColor?: string; // Pattern overlay color
+  className?: string; // Additional CSS classes
+}
+```
+
+### CSS variables
+
+The storefront injects these CSS variables when a page background is configured:
+
+- `--page-bg-color` — base color
+- `--page-bg-gradient` — gradient value
+- `--page-bg-pattern` — pattern name
+- `--page-bg-pattern-opacity` — opacity value
+- `--page-bg-overlay-color` — overlay color
+
+Use these in custom CSS if needed: `background-color: var(--page-bg-color);`
+
 ## Dark/Light Mode
 
 Themes support light, dark, and system color modes via `useThemeMode()`:
@@ -1204,22 +1590,26 @@ This project has THREE MCP servers. Do NOT confuse them:
 Registered in `.mcp.json` in this project. Provides theme-specific tools:
 
 - `onexthm_create_section` — Generate section files (component + schema + index) from structured input
+- `onexthm_from_html` — **Convert HTML/React/JSX code to OneX section** (parses elements, maps to components, detects blocks)
+- `onexthm_from_figma` — **Convert Figma design to OneX section** (see Figma Integration below)
+- `onexthm_generate_schema` — Generate schema from natural language description
 - `onexthm_validate` — Validate theme structure (7 checks: entry file, config, sections, blocks, code quality, registry)
 - `onexthm_list_hooks` — List available hooks with usage examples
-- `onexthm_generate_schema` — Generate schema from natural language description
-- `onexthm_from_figma` — **Convert Figma design to OneX section** (see Figma Integration below)
 
 Resources (auto-loaded context):
 
 - `onexthm://rules` — Theme development rules (DOs/DON'Ts)
 - `onexthm://field-types` — All available field types and categories
 - `onexthm://hooks` — Hooks reference with examples
+- `onexthm://components` — All component types with fields, slots, examples
+- `onexthm://blocks` — Block system patterns and data attributes
 
 Prompts (guided workflows):
 
 - `create_section` — Guided section creation workflow
-- `review_theme` — Review theme for issues
+- `html_to_section` — Convert HTML/React code to OneX section
 - `figma_to_section` — Full Figma-to-OneX conversion pipeline
+- `review_theme` — Review theme for issues
 
 ### `figma` MCP (Figma Design) — USE WITH `onexthm`
 
@@ -1257,10 +1647,11 @@ This is for managing microservices on the OneXEOS platform. Its tools are:
 | Task                             | MCP to use                           |
 | -------------------------------- | ------------------------------------ |
 | Create a new section             | `onexthm_create_section`             |
+| Convert HTML/React to section    | `onexthm_from_html`                  |
 | Convert Figma design to section  | `onexthm_from_figma` + `figma` tools |
+| Generate schema from description | `onexthm_generate_schema`            |
 | Validate theme structure         | `onexthm_validate`                   |
 | Look up available hooks          | `onexthm_list_hooks`                 |
-| Generate schema from description | `onexthm_generate_schema`            |
 | Read Figma design layers         | `figma:get_metadata`                 |
 | Get Figma design tokens          | `figma:get_variable_defs`            |
 | Deploy a backend service         | `onex_deploy` (platform MCP)         |
@@ -1326,6 +1717,44 @@ Auto Layout gap                 →   gap-N (Tailwind)
 
 Returns generated files: `{name}.schema.ts`, `{name}-default.tsx`, `index.ts`, plus registry entry.
 
+### `onexthm_from_html` Tool Parameters
+
+```typescript
+{
+  htmlCode: string,       // Required: Raw HTML or React/JSX code
+  sectionName: string,    // Required: kebab-case name (e.g., "hero-banner")
+  category?: string,      // Optional: section category
+  themePrefix?: string,   // Optional: type prefix (e.g., "my-simple")
+}
+```
+
+Returns generated files: `{name}.schema.ts`, `{name}-default.tsx`, `index.ts`, plus registry entry.
+
+### How HTML Elements Map to OneX
+
+```
+HTML Element                        →   OneX Component
+────────────────────────────────────────────────────
+<h1>-<h6>                          →   heading (with tag h1-h6)
+<p>, <span>                        →   paragraph
+<button>, <a class="btn/cta">      →   button
+<a>                                →   link
+<img>                              →   image
+<svg>, icon components             →   icon
+<ul>/<ol>                          →   list
+<hr>                               →   divider
+<blockquote>                       →   quote
+<input>, <textarea>, <select>      →   input/textarea/select
+<video>                            →   video
+<table>                            →   table
+<div>, <section>, <article>        →   layout containers (recurse)
+Repeating sibling structures       →   block definitions
+Tailwind flex/grid classes         →   layout settings
+Tailwind bg-* classes              →   backgroundColor setting
+Tailwind text-* classes            →   fontSize/textAlign
+React <Button>, <Card>, etc.       →   resolved to HTML equivalents
+```
+
 ### Pixel → Tailwind Reference
 
 ```