@onexapis/cli 1.1.37 → 1.1.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onexapis/cli",
-  "version": "1.1.37",
+  "version": "1.1.39",
   "description": "CLI tool for OneX theme development - scaffolds themes using @onexapis/core",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -50,7 +50,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.470.0",
-    "@onexapis/core": "^1.0.6",
+    "@onexapis/core": "^1.0.7",
     "@tanstack/react-query": "^5.90.16",
     "adm-zip": "^0.5.16",
     "archiver": "^7.0.1",
@@ -69,9 +69,10 @@
     "node-fetch": "^3.3.2",
     "open": "^10.1.0",
     "ora": "^8.0.1",
-    "ws": "^8.18.0",
+    "postcss": "^8.4.0",
+    "semver": "^7.7.4",
     "tailwindcss": "^3.4.0",
-    "postcss": "^8.4.0"
+    "ws": "^8.18.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.7",
@@ -80,6 +81,7 @@
     "@types/fs-extra": "^11.0.4",
     "@types/inquirer": "^9.0.7",
     "@types/node-fetch": "^2.6.13",
+    "@types/semver": "^7.7.1",
     "@types/ws": "^8.5.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"

package/templates/default/CLAUDE.md

@@ -369,7 +369,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 +408,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 +1028,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()`:

package/templates/default/esbuild.config.js

@@ -0,0 +1,20 @@
+const { build } = require("esbuild");
+const path = require("path");
+
+build({
+  entryPoints: [path.resolve(__dirname, "bundle-entry.ts")],
+  bundle: true,
+  outfile: path.resolve(__dirname, "dist/bundle.mjs"),
+  format: "esm",
+  target: "es2020",
+  platform: "browser",
+  jsx: "automatic",
+  external: ["react", "react-dom", "@onexapis/core", "@onexapis/core/*"],
+  sourcemap: true,
+  minify: process.env.NODE_ENV === "production",
+  define: {
+    "process.env.NODE_ENV": JSON.stringify(
+      process.env.NODE_ENV || "development"
+    ),
+  },
+}).catch(() => process.exit(1));

package/templates/default/pages/about.ts

@@ -27,7 +27,7 @@ export const aboutPageConfig: Omit<
   sections: [
     {
       id: "about-1",
-      type: "my-simple-about",
+      type: "about",
       template: "default",
       order: 0,
       enabled: true,
@@ -47,7 +47,7 @@ export const aboutPageConfig: Omit<
     },
     {
       id: "testimonials-1",
-      type: "my-simple-testimonials",
+      type: "testimonials",
       template: "default",
       order: 1,
       enabled: true,

package/templates/default/pages/forgot-password.ts

@@ -16,8 +16,6 @@ export const forgotPasswordPageConfig: Omit<
   themeId: "my-simple",
   editable: true,
   published: true,
-  hideHeader: true,
-  hideFooter: true,
 
   seo: {
     title: "Forgot Password",
@@ -27,7 +25,7 @@ export const forgotPasswordPageConfig: Omit<
   sections: [
     {
       id: "auth-forgot-password-1",
-      type: "my-simple-auth-forgot-password",
+      type: "auth-forgot-password",
       template: "default",
       order: 0,
       enabled: true,

package/templates/default/pages/home.ts

@@ -27,7 +27,7 @@ export const homePageConfig: Omit<
   sections: [
     {
       id: "hero-1",
-      type: "my-simple-hero",
+      type: "hero",
       template: "default",
       order: 0,
       enabled: true,
@@ -47,7 +47,7 @@ export const homePageConfig: Omit<
     },
     {
       id: "features-1",
-      type: "my-simple-features",
+      type: "features",
       template: "default",
       order: 1,
       enabled: true,
@@ -62,7 +62,7 @@ export const homePageConfig: Omit<
     },
     {
       id: "stats-1",
-      type: "my-simple-stats",
+      type: "stats",
       template: "default",
       order: 2,
       enabled: true,
@@ -76,7 +76,7 @@ export const homePageConfig: Omit<
     },
     {
       id: "cta-1",
-      type: "my-simple-cta",
+      type: "cta",
       template: "default",
       order: 3,
       enabled: true,

package/templates/default/pages/login.ts

@@ -16,8 +16,6 @@ export const loginPageConfig: Omit<
   themeId: "my-simple",
   editable: true,
   published: true,
-  hideHeader: true,
-  hideFooter: true,
 
   seo: {
     title: "Sign In",
@@ -27,7 +25,7 @@ export const loginPageConfig: Omit<
   sections: [
     {
       id: "auth-login-1",
-      type: "my-simple-auth-login",
+      type: "auth-login",
       template: "default",
       order: 0,
       enabled: true,

package/templates/default/pages/profile.ts

@@ -11,7 +11,7 @@ export const profilePageConfig: Omit<
   title: "Profile",
   handle: "profile",
   path: "/profile",
-  type: "account",
+  type: "profile",
   renderMode: "sections",
   themeId: "my-simple",
   editable: true,
@@ -25,7 +25,7 @@ export const profilePageConfig: Omit<
   sections: [
     {
       id: "profile-1",
-      type: "my-simple-profile",
+      type: "profile",
       template: "default",
       order: 0,
       enabled: true,

package/templates/default/pages/register.ts

@@ -16,8 +16,6 @@ export const registerPageConfig: Omit<
   themeId: "my-simple",
   editable: true,
   published: true,
-  hideHeader: true,
-  hideFooter: true,
 
   seo: {
     title: "Create Account",
@@ -27,7 +25,7 @@ export const registerPageConfig: Omit<
   sections: [
     {
       id: "auth-register-1",
-      type: "my-simple-auth-register",
+      type: "auth-register",
       template: "default",
       order: 0,
       enabled: true,

package/templates/default/pages/showcase.ts

@@ -27,7 +27,7 @@ export const showcasePageConfig: Omit<
   sections: [
     {
       id: "showcase-hero",
-      type: "my-simple-hero",
+      type: "hero",
       template: "default",
       order: 0,
       enabled: true,
@@ -48,7 +48,7 @@ export const showcasePageConfig: Omit<
     },
     {
       id: "showcase-features",
-      type: "my-simple-features",
+      type: "features",
       template: "default",
       order: 1,
       enabled: true,
@@ -63,7 +63,7 @@ export const showcasePageConfig: Omit<
     },
     {
       id: "showcase-stats",
-      type: "my-simple-stats",
+      type: "stats",
       template: "default",
       order: 2,
       enabled: true,
@@ -77,7 +77,7 @@ export const showcasePageConfig: Omit<
     },
     {
       id: "showcase-about",
-      type: "my-simple-about",
+      type: "about",
       template: "default",
       order: 3,
       enabled: true,
@@ -97,7 +97,7 @@ export const showcasePageConfig: Omit<
     },
     {
       id: "showcase-testimonials",
-      type: "my-simple-testimonials",
+      type: "testimonials",
       template: "default",
       order: 4,
       enabled: true,
@@ -113,7 +113,7 @@ export const showcasePageConfig: Omit<
     },
     {
       id: "showcase-gallery",
-      type: "my-simple-gallery",
+      type: "gallery",
       template: "default",
       order: 5,
       enabled: true,
@@ -129,7 +129,7 @@ export const showcasePageConfig: Omit<
     },
     {
       id: "showcase-cta",
-      type: "my-simple-cta",
+      type: "cta",
       template: "default",
       order: 6,
       enabled: true,

package/templates/default/pages/verify-code.ts

@@ -16,8 +16,6 @@ export const verifyCodePageConfig: Omit<
   themeId: "my-simple",
   editable: true,
   published: true,
-  hideHeader: true,
-  hideFooter: true,
 
   seo: {
     title: "Verify Your Account",
@@ -27,7 +25,7 @@ export const verifyCodePageConfig: Omit<
   sections: [
     {
       id: "auth-verify-code-1",
-      type: "my-simple-auth-verify-code",
+      type: "auth-verify-code",
       template: "default",
       order: 0,
       enabled: true,

package/templates/default/sections/about/about.schema.ts

@@ -56,7 +56,7 @@ const commonSettings: FieldDefinition[] = [
 ];
 
 export const aboutSchema: SectionSchema = {
-  type: "my-simple-about",
+  type: "about",
   name: "Simple About",
   description:
     "About section with badge, heading, subheading, descriptions, divider, and image",

package/templates/default/sections/auth-forgot-password/auth-forgot-password.schema.ts

@@ -112,7 +112,7 @@ const commonSettings: FieldDefinition[] = [
 ];
 
 export const authForgotPasswordSchema: SectionSchema = {
-  type: "my-simple-auth-forgot-password",
+  type: "auth-forgot-password",
   name: "Auth Forgot Password",
   description: "Forgot password form with email/username input",
   category: "auth",

package/templates/default/sections/auth-login/auth-login.schema.ts

@@ -130,7 +130,7 @@ const commonSettings: FieldDefinition[] = [
 ];
 
 export const authLoginSchema: SectionSchema = {
-  type: "my-simple-auth-login",
+  type: "auth-login",
   name: "Auth Login",
   description: "Login form with username and password",
   category: "auth",

package/templates/default/sections/auth-register/auth-register.schema.ts

@@ -143,7 +143,7 @@ const commonSettings: FieldDefinition[] = [
 ];
 
 export const authRegisterSchema: SectionSchema = {
-  type: "my-simple-auth-register",
+  type: "auth-register",
   name: "Auth Register",
   description: "Registration form with email, username, and password",
   category: "auth",

package/templates/default/sections/auth-verify-code/auth-verify-code.schema.ts

@@ -112,7 +112,7 @@ const commonSettings: FieldDefinition[] = [
 ];
 
 export const authVerifyCodeSchema: SectionSchema = {
-  type: "my-simple-auth-verify-code",
+  type: "auth-verify-code",
   name: "Auth Verify Code",
   description: "OTP verification form with 6-digit code input",
   category: "auth",

package/templates/default/sections/cta/cta.schema.ts

@@ -20,7 +20,7 @@ const commonSettings: FieldDefinition[] = [
 ];
 
 export const ctaSchema: SectionSchema = {
-  type: "my-simple-cta",
+  type: "cta",
   name: "Simple CTA",
   description:
     "Call-to-action section with badge, heading, text, buttons, and optional image",