@onexapis/cli 1.1.27 → 1.1.29

package/dist/preview/preview-app.tsx

@@ -13,7 +13,6 @@ import * as coreContexts from "@onexapis/core/contexts";
 import * as coreComponents from "@onexapis/core/components";
 import * as coreRegistry from "@onexapis/core/registry";
 import * as coreCommerce from "@onexapis/core/commerce";
-import * as coreHooks from "@onexapis/core/hooks";
 import * as coreCommerceHooks from "@onexapis/core/commerce/hooks";
 import * as coreAuth from "@onexapis/core/auth";
 import * as coreCart from "@onexapis/core/cart";
@@ -23,9 +22,26 @@ import * as coreBlog from "@onexapis/core/blog";
 import * as coreFinance from "@onexapis/core/finance";
 import * as coreInternal from "@onexapis/core/internal";
 import * as coreTypes from "@onexapis/core/types";
-import { CartProvider } from "@onexapis/core/contexts";
+import { CartProvider, FlyToCartProvider } from "@onexapis/core/contexts";
 import { LocaleProvider } from "@onexapis/core/contexts";
 
+// Compose @onexapis/core/hooks from published subpaths
+// Only include use* hook functions — spreading entire modules includes
+// Zustand stores and React providers that cause "selector is not a function" errors.
+const coreHooks = {
+  ...coreCommerceHooks,
+};
+// Add context/state hooks individually (avoid spreading full modules)
+for (const mod of [coreContexts, coreAuth, coreOrders, coreCart] as any[]) {
+  if (mod && typeof mod === "object") {
+    for (const [k, v] of Object.entries(mod)) {
+      if (typeof v === "function" && k.startsWith("use") && !(k in coreHooks)) {
+        (coreHooks as any)[k] = v;
+      }
+    }
+  }
+}
+
 // Set React globals
 (globalThis as any).__ONEX_REACT__ = React;
 (globalThis as any).__ONEX_REACT_DOM__ = { createRoot };
@@ -337,24 +353,91 @@ function discoverPageConfigs(
 
 // ===== 8. PREVIEW APP COMPONENT =====
 
+/**
+ * Match a URL path against a route pattern with [param] segments.
+ * Returns extracted params if matched, null otherwise.
+ * E.g. matchDynamicPath("/products/[slug]", "/products/my-product") → { slug: "my-product" }
+ */
+function matchDynamicPath(
+  pattern: string,
+  pathname: string
+): Record<string, string> | null {
+  const patternParts = pattern.replace(/^\/+|\/+$/g, "").split("/");
+  const pathParts = pathname.replace(/^\/+|\/+$/g, "").split("/");
+  if (patternParts.length !== pathParts.length) return null;
+  const params: Record<string, string> = {};
+  for (let i = 0; i < patternParts.length; i++) {
+    const segMatch = patternParts[i].match(/^\[(\w+)\]$/);
+    if (segMatch) {
+      params[segMatch[1]] = pathParts[i];
+    } else if (patternParts[i].toLowerCase() !== pathParts[i].toLowerCase()) {
+      return null;
+    }
+  }
+  return params;
+}
+
+const PREVIEW_SUPPORTED_LOCALES = ["vi", "en"];
+
+/**
+ * Extract locale prefix from URL pathname.
+ * "/vi/san-pham/slug" → { locale: "vi", rest: "/san-pham/slug" }
+ * "/products/slug" → { locale: "en", rest: "/products/slug" }
+ */
+function extractLocaleFromUrl(pathname: string): { locale: string; rest: string } {
+  const parts = pathname.replace(/^\/+/, "").split("/");
+  if (parts[0] && PREVIEW_SUPPORTED_LOCALES.includes(parts[0])) {
+    return { locale: parts[0], rest: "/" + parts.slice(1).join("/") };
+  }
+  return { locale: "en", rest: pathname };
+}
+
+/**
+ * Get the effective path for a page in a given locale.
+ * Uses localizedPaths[locale] if available, falls back to path.
+ */
+function getPagePathForLocale(config: any, locale: string): string | undefined {
+  return config?.localizedPaths?.[locale] || config?.path;
+}
+
 /**
  * Match URL pathname to a page index.
- * "/" or "/home" → home page, "/showcase" → showcase page, etc.
+ * Supports: static pages, dynamic routes, locale-prefixed URLs, and localizedPaths.
  */
 function getInitialPageFromURL(
-  pages: Array<{ key: string; label: string; config: any }>
+  pages: Array<{ key: string; label: string; config: any }>,
+  locale: string,
+  restPath: string
 ): number {
-  const pathname = window.location.pathname
-    .replace(/^\/+|\/+$/g, "")
-    .toLowerCase();
-  if (!pathname || pathname === "home") return 0; // home is always first after sorting
+  const pathname = restPath.replace(/^\/+|\/+$/g, "").toLowerCase();
+  if (!pathname || pathname === "home") return 0;
 
-  const idx = pages.findIndex((p) => {
+  // 1. Try exact static match (by label or key)
+  let idx = pages.findIndex((p) => {
     const pageSlug = p.label.toLowerCase().replace(/\s+/g, "-");
     const pageKey = p.key.replace("PageConfig", "").toLowerCase();
     return pageSlug === pathname || pageKey === pathname;
   });
-  return idx >= 0 ? idx : -2; // -2 = page not found
+  if (idx >= 0) return idx;
+
+  // 2. Try matching against localizedPaths[locale] or fallback path
+  for (let i = 0; i < pages.length; i++) {
+    const config = pages[i].config;
+    const effectivePath = getPagePathForLocale(config, locale);
+    if (!effectivePath) continue;
+
+    // Static locale path match (e.g., /gioi-thieu matches localizedPaths.vi: "/gioi-thieu")
+    const normalizedEffective = effectivePath.replace(/^\/+|\/+$/g, "").toLowerCase();
+    if (normalizedEffective === pathname) return i;
+
+    // Dynamic locale path match (e.g., /san-pham/my-slug matches localizedPaths.vi: "/san-pham/[slug]")
+    if (config?.isDynamic) {
+      const params = matchDynamicPath(effectivePath, `/${pathname}`);
+      if (params) return i;
+    }
+  }
+
+  return -2; // page not found
 }
 
 function PreviewApp() {
@@ -459,9 +542,16 @@ function PreviewApp() {
   const pages = discoverPageConfigs(themeExports);
   const sectionRegistry = buildSectionRegistry(themeExports);
 
+  // Extract locale from URL (e.g., /vi/san-pham/slug → locale="vi", rest="/san-pham/slug")
+  const { locale: urlLocale, rest: urlRestPath } = extractLocaleFromUrl(
+    window.location.pathname
+  );
+
   // Resolve initial page from URL path (once pages are discovered)
   const resolvedPage =
-    selectedPage === -1 ? getInitialPageFromURL(pages) : selectedPage;
+    selectedPage === -1
+      ? getInitialPageFromURL(pages, urlLocale, urlRestPath)
+      : selectedPage;
 
   // Page not found (-2)
   if (resolvedPage === -2) {
@@ -538,13 +628,25 @@ function PreviewApp() {
     );
   }
 
-  // Build section data (Gap 4)
+  // Extract route params for dynamic pages using locale-aware path
+  let routeParams: Record<string, string> = {};
+  if (currentPage.config?.isDynamic) {
+    const effectivePath = getPagePathForLocale(currentPage.config, urlLocale);
+    if (effectivePath) {
+      const params = matchDynamicPath(effectivePath, urlRestPath);
+      if (params) routeParams = params;
+    }
+  }
+
+  // Build section data
   const sectionData = {
     theme: themeExports.themeConfig || {},
     page: currentPage.config,
     products: [],
     blogs: [],
     settings: {},
+    routeParams,
+    locale: urlLocale,
   };
 
   // Resolve layout sections (Gap 1)
@@ -630,12 +732,17 @@ const queryClient = new QueryClient({
   },
 });
 
+// Detect locale from URL for the root provider
+const _rootLocale = extractLocaleFromUrl(window.location.pathname).locale;
+
 const root = createRoot(document.getElementById("onex-preview-root")!);
 root.render(
   <QueryClientProvider client={queryClient}>
-    <LocaleProvider locale="en">
+    <LocaleProvider locale={_rootLocale as any}>
       <CartProvider>
-        <PreviewApp />
+        <FlyToCartProvider>
+          <PreviewApp />
+        </FlyToCartProvider>
       </CartProvider>
     </LocaleProvider>
   </QueryClientProvider>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onexapis/cli",
-  "version": "1.1.27",
+  "version": "1.1.29",
   "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.2",
+    "@onexapis/core": "workspace:*",
     "@tanstack/react-query": "^5.90.16",
     "adm-zip": "^0.5.16",
     "archiver": "^7.0.1",

package/templates/default/.mcp.json

@@ -6,7 +6,12 @@
     },
     "figma": {
       "command": "npx",
-      "args": ["-y", "figma-developer-mcp", "--figma-api-key=__FIGMA_API_KEY__", "--stdio"]
+      "args": [
+        "-y",
+        "figma-developer-mcp",
+        "--figma-api-key=__FIGMA_API_KEY__",
+        "--stdio"
+      ]
     }
   }
 }

package/templates/default/CLAUDE.md

@@ -595,6 +595,98 @@ When `dataRequirements.products = true`:
 - Use `useCommerceData(data)` to access it
 - Falls back to client-side `useProducts()` if not pre-fetched
 
+## Dynamic Pages (Product Detail, Blog Detail)
+
+Dynamic pages use URL parameters like `/products/[slug]` to render detail views.
+
+### Define a dynamic page in `pages/`
+
+```typescript
+// pages/product-detail.ts
+import type { PageConfig } from "@onexapis/core/types";
+
+export const productDetailPageConfig: Omit<PageConfig, "id" | "createdAt" | "updatedAt"> = {
+  title: "Product Detail",
+  handle: "product-detail",
+  path: "/products/[slug]",       // Dynamic segment in brackets
+  isDynamic: true,                // Flag as dynamic
+  dynamicSegments: ["slug"],      // Parameter names
+  type: "product",
+  renderMode: "sections",
+  themeId: "my-theme",
+  editable: true,
+  published: true,
+  sections: [
+    {
+      id: "product-detail-1",
+      type: "my-product-detail",
+      template: "default",
+      order: 0,
+      enabled: true,
+      settings: {},
+      components: [],
+      blocks: [],
+    },
+  ],
+};
+export default productDetailPageConfig;
+```
+
+Export in `bundle-entry.ts`:
+```typescript
+export { default as productDetailPageConfig } from "./pages/product-detail";
+```
+
+### Access route params in sections
+
+Sections receive `data.routeParams` with the extracted URL parameters:
+
+```tsx
+export function ProductDetail({ section, schema, isEditing, data }: SectionComponentProps) {
+  const routeParams = (data?.routeParams || {}) as Record<string, string>;
+  const slug = routeParams.slug || "";  // "blue-shirt" from /products/blue-shirt
+
+  const { data: product, isLoading } = useProductBySlug(slug, !!slug);
+  // ...
+}
+```
+
+### Locale-aware paths
+
+Use `localizedPaths` to define different URL slugs per locale:
+
+```typescript
+export const productDetailPageConfig = {
+  handle: "product-detail",
+  path: "/products/[slug]",           // Default/fallback
+  isDynamic: true,
+  dynamicSegments: ["slug"],
+  localizedPaths: {                    // Locale-specific paths (typed by Locale enum)
+    vi: "/san-pham/[slug]",            // /vi/san-pham/blue-shirt
+    en: "/products/[slug]",            // /en/products/blue-shirt
+  },
+  type: "product",
+  // ...
+};
+```
+
+The `Locale` type (`"vi" | "en"`) is from `@onexapis/core/types` — gives autocomplete.
+
+Sections also receive `data.locale` to know the current locale:
+```tsx
+const locale = data?.locale as string;  // "vi" or "en"
+```
+
+### Key conventions
+
+- `path` uses bracket syntax: `/products/[slug]`, `/blog/[slug]`
+- `localizedPaths` maps `Locale` → path for locale-specific URLs
+- `dynamicSegments` lists parameter names extracted from the path
+- `type: "product"` or `"blog"` indicates what kind of detail page
+- Sections access params via `data.routeParams.slug` (or whatever parameter name)
+- Sections access locale via `data.locale` or `useLocale()` hook
+- Use `useProductBySlug()` / `useBlogBySlug()` hooks to fetch detail data
+
 ## Product & Blog Types
 
 ### Product
@@ -909,6 +1001,123 @@ export function ProductGrid({
 export default ProductGrid;
 ```
 
+## Cart & Fly-to-Cart Animation
+
+The cart system uses `useCart()` for state and a flexible fly-to-cart animation triggered by `data-fly-to-cart-target`.
+
+### Cart State
+
+```tsx
+import { useCart } from "@onexapis/core/hooks";
+
+const { items, addItem, removeItem, updateQuantity, clearCart, itemCount, subtotal } = useCart();
+
+// Add to cart
+addItem({
+  productId: product.id,
+  name: product.title,
+  image: product.image,
+  price: product.salePrice,
+  slug: product.slug,
+});
+```
+
+### Fly-to-Cart Animation
+
+When a user clicks "Add to Cart", the product thumbnail flies from the button to the cart icon in the header.
+
+**Step 1: Mark any element as the cart target** (in header section):
+
+```tsx
+// Option A: Use any element — just add the data attribute
+<div data-fly-to-cart-target className="my-cart-icon">
+  <ShoppingCartIcon />
+  <span>{itemCount}</span>
+</div>
+
+// Option B: Use CartIcon convenience component (auto-adds data-fly-to-cart-target)
+import { CartIcon } from "@onexapis/core/components";
+<CartIcon count={itemCount} onClick={() => openCartDrawer()} />
+```
+
+**Step 2: ProductCard triggers animation automatically** — just pass `onAddToCart`:
+
+```tsx
+<ProductCard
+  product={product}
+  onAddToCart={(p) => addItem({ productId: p.id, name: p.title, image: p.image, price: p.salePrice })}
+/>
+```
+
+**Step 3: Custom trigger** (for buttons that aren't ProductCard):
+
+```tsx
+import { useFlyToCart } from "@onexapis/core/hooks";
+
+const { flyToCart } = useFlyToCart();
+
+<button onClick={(e) => {
+  flyToCart(e.currentTarget, product.image); // animation
+  addItem({ ... }); // cart logic
+}}>
+  Buy Now
+</button>
+```
+
+### How it works
+
+- `data-fly-to-cart-target` on any element → animation lands there (detected via `querySelector`)
+- `FlyToCartProvider` renders a portal with the flying thumbnail (CSS transition)
+- No refs or context wiring needed — just add the data attribute
+- Without `data-fly-to-cart-target` → cart still works, no animation
+
+## Server-Side APIs
+
+Server-side data fetching is available from `@onexapis/core/server`. Use in Next.js server components, server actions, or API routes.
+
+```tsx
+import {
+  fetchProducts,
+  fetchBlogs,
+  fetchSettings,
+  fetchCompany,
+  fetchTheme,
+  fetchPage,
+  prefetchSectionData,
+} from "@onexapis/core/server";
+
+// Fetch products (server-side with ISR caching)
+const { data: products, pagination } = await fetchProducts(companyId, { limit: 12 });
+
+// Fetch website settings
+const settings = await fetchSettings(companyId);
+
+// Smart prefetch — scans sections for dataRequirements, fetches in parallel
+const data = await prefetchSectionData({
+  companyId,
+  sections: allSections,
+  dataRequirements: manifest.dataRequirements,
+});
+// data.products, data.blogs, data.settings
+```
+
+### Advanced: Custom server client
+
+```tsx
+import { CommerceServerClient, noopCacheAdapter } from "@onexapis/core/server";
+
+const client = new CommerceServerClient({
+  apiUrl: "https://api.example.com",
+  companyId: "xxx",
+  cacheAdapter: noopCacheAdapter, // For non-Next.js environments
+});
+
+const products = await client.getProducts({ limit: 8 });
+const blog = await client.getBlogBySlug("my-post");
+```
+
+Environment variables auto-detected: `NEXT_PUBLIC_COMMERCE_API_URL`, `NEXT_PUBLIC_API_URL`.
+
 ## MCP Servers
 
 This project has THREE MCP servers. Do NOT confuse them:
@@ -924,11 +1133,13 @@ Registered in `.mcp.json` in this project. Provides theme-specific tools:
 - `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
 
 Prompts (guided workflows):
+
 - `create_section` — Guided section creation workflow
 - `review_theme` — Review theme for issues
 - `figma_to_section` — Full Figma-to-OneX conversion pipeline
@@ -944,6 +1155,7 @@ Registered in `.mcp.json`. Reads Figma designs for design-to-code conversion:
 - `search_design_system` — Search components, variables, styles from libraries
 
 **Setup**: Requires Figma API key in `.mcp.json`:
+
 ```json
 {
   "figma": {
@@ -952,6 +1164,7 @@ Registered in `.mcp.json`. Reads Figma designs for design-to-code conversion:
   }
 }
 ```
+
 Get your key: Figma → Settings → Account → Personal access tokens.
 
 ### `onex-platform` MCP (Backend Services) — DO NOT USE FOR THEMES
@@ -964,17 +1177,17 @@ This is for managing microservices on the OneXEOS platform. Its tools are:
 
 ### When to use which
 
-| Task                              | MCP to use                                |
-| --------------------------------- | ----------------------------------------- |
-| Create a new section              | `onexthm_create_section`                  |
-| Convert Figma design to section   | `onexthm_from_figma` + `figma` tools      |
-| 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)              |
-| Check service health              | `onex_status` (platform MCP)              |
+| Task                             | MCP to use                           |
+| -------------------------------- | ------------------------------------ |
+| Create a new section             | `onexthm_create_section`             |
+| Convert Figma design to section  | `onexthm_from_figma` + `figma` tools |
+| 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)         |
+| Check service health             | `onex_status` (platform MCP)         |
 
 ## Figma → OneX Conversion
 
@@ -983,6 +1196,7 @@ Convert Figma designs directly to OneX theme sections using the combined Figma +
 ### Quick Start
 
 Use the `figma_to_section` prompt for a guided workflow:
+
 ```
 "Convert the selected Figma frame to a section called 'hero'"
 ```