@onexapis/cli 1.1.38 → 1.1.39

package/dist/preview/preview-app.tsx

@@ -455,6 +455,14 @@ function PreviewApp() {
   >("disconnected");
   const [error, setError] = useState<string | null>(null);
   const wsRef = useRef<WebSocket | null>(null);
+  const [isEditing, setIsEditing] = useState(() => {
+    if (typeof window !== "undefined") {
+      return (
+        new URLSearchParams(window.location.search).get("editing") === "true"
+      );
+    }
+    return false;
+  });
 
   // Load theme bundle
   const loadTheme = useCallback(async (timestamp?: number) => {
@@ -701,7 +709,7 @@ function PreviewApp() {
         section={section}
         schema={schema}
         template={template}
-        isEditing={false}
+        isEditing={isEditing}
         data={sectionData}
       />
     );
@@ -712,16 +720,16 @@ function PreviewApp() {
       {/* Inject theme CSS variables (Gap 2) */}
       {themeCSS && <style dangerouslySetInnerHTML={{ __html: themeCSS }} />}
 
-      {/* Header (Gap 1) */}
-      {headerSections.length > 0 && (
+      {/* Header — hidden if page config sets hideHeader: true */}
+      {headerSections.length > 0 && !currentPage.config?.hideHeader && (
         <header>{headerSections.map(renderSection)}</header>
       )}
 
       {/* Page sections */}
       <main>{pageSections.map(renderSection)}</main>
 
-      {/* Footer (Gap 1) */}
-      {footerSections.length > 0 && (
+      {/* Footer — hidden if page config sets hideFooter: true */}
+      {footerSections.length > 0 && !currentPage.config?.hideFooter && (
         <footer>{footerSections.map(renderSection)}</footer>
       )}
     </>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onexapis/cli",
-  "version": "1.1.38",
+  "version": "1.1.39",
   "description": "CLI tool for OneX theme development - scaffolds themes using @onexapis/core",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -57,7 +57,6 @@
     "chalk": "^5.3.0",
     "chokidar": "^4.0.0",
     "commander": "^12.1.0",
-    "cross-spawn": "^7.0.6",
     "dotenv": "^17.3.1",
     "ejs": "^3.1.10",
     "esbuild": "^0.25.0",
@@ -78,7 +77,6 @@
   "devDependencies": {
     "@types/adm-zip": "^0.5.7",
     "@types/archiver": "^7.0.0",
-    "@types/cross-spawn": "^6.0.6",
     "@types/ejs": "^3.1.5",
     "@types/fs-extra": "^11.0.4",
     "@types/inquirer": "^9.0.7",

package/templates/default/AUTH_AND_PROFILE.md

@@ -0,0 +1,167 @@
+# Authentication & Profile — Default Theme
+
+This document covers the built-in authentication and profile sections included in the default theme template.
+
+## Overview
+
+When you initialize a theme with `onexthm init`, it comes with 5 auth/profile sections and their corresponding hooks ready to use:
+
+| Section              | Path               | Description                                  |
+| -------------------- | ------------------ | -------------------------------------------- |
+| Auth Login           | `/login`           | Username/email + password sign-in            |
+| Auth Register        | `/register`        | Email, username, password, confirm password  |
+| Auth Forgot Password | `/forgot-password` | Request verification code via email/username |
+| Auth Verify Code     | `/verify-code`     | 6-digit OTP input with resend + countdown    |
+| Profile              | `/profile`         | View/edit profile + change password          |
+
+## Architecture
+
+```
+Theme Section (UI only)
+  └── Theme Hook (form state, validation)
+        └── useAuth() from @onexapis/core/hooks (Zustand store)
+              └── AuthService (API calls)
+                    └── ApiClient (HTTP client with token management)
+```
+
+### Hooks
+
+All hooks live in `hooks/` and use `useAuth` from `@onexapis/core/hooks`:
+
+| Hook                    | Uses                                                          | Manages                                              |
+| ----------------------- | ------------------------------------------------------------- | ---------------------------------------------------- |
+| `useLoginForm`          | `useAuth().login()`                                           | Username, password, show/hide toggle, validation     |
+| `useRegisterForm`       | `useAuth().signup()`                                          | Email, username, password, confirm, validation       |
+| `useForgotPasswordForm` | `useAuth().forgotPassword()`                                  | Username/email input, validation                     |
+| `useVerifyCodeForm`     | `useAuth().verifyCode()`, `verifyCodeReset()`, `resendCode()` | 6-digit OTP, auto-focus, paste, countdown            |
+| `useProfileForm`        | `useAuth().updateProfile()`, `changePassword()`, `logout()`   | Profile fields, dirty tracking, change password form |
+
+### API Endpoints
+
+The `AuthService` in `@onexapis/core` handles all API calls:
+
+| Action              | Method | Endpoint                            |
+| ------------------- | ------ | ----------------------------------- |
+| Login               | POST   | `/auth/login`                       |
+| Register            | POST   | `/auth/register`                    |
+| Forgot Password     | POST   | `/auth/forgot`                      |
+| Verify Code         | POST   | `/auth/confirm`                     |
+| Verify Code (reset) | POST   | `/auth/confirm_reset_password_code` |
+| Resend Code         | POST   | `/auth/resend_code`                 |
+| Reset Password      | POST   | `/auth/new_password`                |
+| Change Password     | POST   | `/auth/change_password`             |
+| Get User Info       | GET    | `/auth/user_info`                   |
+| Update Profile      | POST   | `/auth/user_info`                   |
+
+### Token Handling
+
+- **IdToken** → `Authorization: Bearer {IdToken}` header
+- **AccessToken** → `?access_token={AccessToken}` query parameter
+- **Tokens stored** in `localStorage` under key `auth_tokens`
+- **Signup** auto-injects `company_id` (from `initializeOnex()` config) and `is_customer: true`
+
+## Editable Settings
+
+All sections expose these layout settings via the editor sidebar:
+
+| Setting            | Type   | Default   | Description                          |
+| ------------------ | ------ | --------- | ------------------------------------ |
+| `backgroundColor`  | color  | `#F9FAFB` | Page background                      |
+| `cardBackground`   | color  | `#FFFFFF` | Card/form container background       |
+| `primaryColor`     | color  | `#2563EB` | Buttons and links                    |
+| `textColor`        | color  | `#111827` | Heading text color                   |
+| `cardBorderRadius` | select | `2xl`     | Card corner rounding (lg/xl/2xl/3xl) |
+
+Plus all text labels, placeholders, button text, and URLs are customizable per section.
+
+## Auth Flow
+
+```
+Register → Verify Code → Login → Profile
+                ↑                    │
+Forgot Password → Verify Code (reset) → Reset Password
+```
+
+1. **Register**: User fills email, username, password → `signup()` → redirects to `/verify-code?username=...`
+2. **Verify Code**: User enters 6-digit OTP → `verifyCode()` → redirects to `/login`
+3. **Login**: User signs in → `login()` → tokens stored → redirects to `/`
+4. **Forgot Password**: User enters email → `forgotPassword()` → redirects to `/verify-code?mode=reset&username=...`
+5. **Verify Code (reset)**: OTP → `verifyCodeReset()` → returns session → redirects to `/reset-password?session=...`
+6. **Profile**: View/edit name, phone, address → `updateProfile()`. Change password → `changePassword()`
+
+## Configuration
+
+### Required Environment Variables
+
+```env
+NEXT_PUBLIC_API_URL=https://api-dev.onexeos.com
+NEXT_PUBLIC_COMPANY_ID=your-company-id
+```
+
+These are read by `initializeOnex()` which creates the `AuthService` and registers it with the `useAuth` Zustand store.
+
+## Testing Locally
+
+### Preview mode (UI only)
+
+```bash
+onexthm dev
+# Visit http://localhost:3456/login
+```
+
+### Preview with editing mode
+
+```bash
+onexthm dev
+# Visit http://localhost:3456/login?editing=true
+```
+
+### Preview with real API (requires .env)
+
+Create `.env` in your theme directory:
+
+```env
+NEXT_PUBLIC_API_URL=https://api-dev.onexeos.com
+NEXT_PUBLIC_COMPANY_ID=your-company-id
+```
+
+Then run `onexthm dev` — login/register/verify will make real API calls.
+
+## File Structure
+
+```
+hooks/
+  index.ts
+  use-login-form.ts
+  use-register-form.ts
+  use-forgot-password-form.ts
+  use-verify-code-form.ts
+  use-profile-form.ts
+sections/
+  auth-login/
+    auth-login-default.tsx    # Login form UI
+    auth-login.schema.ts      # Editable settings
+    index.ts
+  auth-register/
+    auth-register-default.tsx
+    auth-register.schema.ts
+    index.ts
+  auth-forgot-password/
+    auth-forgot-password-default.tsx
+    auth-forgot-password.schema.ts
+    index.ts
+  auth-verify-code/
+    auth-verify-code-default.tsx
+    auth-verify-code.schema.ts
+    index.ts
+  profile/
+    profile-default.tsx
+    profile.schema.ts
+    index.ts
+pages/
+  login.ts
+  register.ts
+  forgot-password.ts
+  verify-code.ts
+  profile.ts
+```

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()`: