@zohofinance/commerce 1.0.0 → 1.1.0

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/custom-scripts.md

@@ -0,0 +1,294 @@
+---
+title: "Custom Scripts"
+weight: 14
+---
+
+# Custom Scripts
+
+Zoho Commerce provides pre-built JavaScript libraries for common storefront functionality. These scripts are provided by Zoho Commerce and should be included in your theme to leverage built-in actions without boilerplate code.
+
+## Overview
+
+Instead of implementing cart operations, product interactions, and analytics tracking from scratch, theme developers can include Zoho-provided scripts and use the exported functions directly.
+
+## Available Scripts
+
+### 1. Storefront Actions Script
+
+The storefront actions script provides JavaScript functions for common e-commerce operations.
+
+**CDN URL:**
+```
+https://cdn.example.com/storefront-actions/latest/storefront-actions.js
+```
+
+**Inclusion:**
+```html
+<script src="https://cdn.example.com/storefront-actions/latest/storefront-actions.js" defer></script>
+```
+
+**Exported Functions:**
+
+#### addToCart(variantId, orgId, sectionName, quantity, productId)
+
+Add a product variant to cart and get updated section rendering.
+
+**Parameters:**
+- `variantId`: The variant ID to add
+- `orgId`: Organization ID 
+- `sectionName`: Section to re-render (e.g., "cart-summary")
+- `quantity`: Number of items
+- `productId`: Product ID (optional, for analytics)
+
+**Returns:** JSON with rendered section HTML
+
+**Example:**
+```javascript
+const result = await addToCart('var123', 'org456', 'cart-items', 1, 'prod789');
+console.log(result.sections.cartItems); // Updated HTML
+```
+
+#### quickViewProduct(productId, sectionName, listId, listTitle)
+
+Fetch and display quick view of a product.
+
+**Parameters:**
+- `productId`: ID of product to preview
+- `sectionName`: Section to display (e.g., "product-quick-view")
+- `listId`: List/collection ID (default: 'home-page')
+- `listTitle`: List/collection title (default: 'Home Page')
+
+**Returns:** JSON with rendered section HTML
+
+**Example:**
+```javascript
+const result = await quickViewProduct('prod123', 'product-modal', 'featured', 'Featured Products');
+document.getElementById('modal').innerHTML = result.sections.productModal;
+```
+
+#### removeFromCart(variantId, sectionName, productId)
+
+Remove a variant from cart and get updated sections.
+
+**Parameters:**
+- `variantId`: Variant to remove
+- `sectionName`: Section to re-render
+- `productId`: Product ID (optional, for analytics)
+
+**Returns:** JSON with updated section HTML
+
+**Example:**
+```javascript
+await removeFromCart('var123', 'cart-items', 'prod789');
+```
+
+#### updateCartQuantity(variantId, quantity, sectionName, productId)
+
+Update cart item quantity.
+
+**Parameters:**
+- `variantId`: Variant ID
+- `quantity`: New quantity (0 to remove)
+- `sectionName`: Section to re-render
+- `productId`: Product ID (optional)
+
+**Returns:** JSON with updated section HTML
+
+**Example:**
+```javascript
+await updateCartQuantity('var123', 3, 'cart-items', 'prod789');
+```
+
+#### postCheckoutAddress(body)
+
+Submit shipping/billing address during checkout.
+
+**Parameters:**
+- `body`: Object containing:
+  - `shipping_address`: Address object or ID
+  - `billing_address`: Address object or ID
+  - `is_consent_agreed`: Boolean
+
+**Returns:** JSON with response or error
+
+#### postShippingMethod(shippingMethodId)
+
+Select shipping method during checkout.
+
+**Parameters:**
+- `shippingMethodId`: ID of selected shipping method
+
+**Returns:** JSON response
+
+#### postPaymentMethod(paymentMethodId, body)
+
+Submit payment method during checkout.
+
+**Parameters:**
+- `paymentMethodId`: ID of payment method
+- `body`: Payment details object
+
+**Returns:** JSON response
+
+---
+
+### 2. Analytics Script
+
+The analytics script tracks user interactions for conversion tracking and marketing attribution.
+
+**CDN URL:**
+```
+https://cdn.example.com/analytics/latest/analytics.js
+```
+
+**Inclusion:**
+```html
+<script src="https://cdn.example.com/analytics/latest/analytics.js" defer></script>
+```
+
+**Exported Functions:**
+
+The analytics script automatically tracks page views and exports functions for custom events:
+
+#### pushAddToCartEventToAnalytics(variantId, quantity, productId)
+
+Track when user adds item to cart.
+
+**Example:**
+```javascript
+window.pushAddToCartEventToAnalytics('var123', 2, 'prod789');
+```
+
+#### pushRemoveFromCartToAnalytics(variantId, quantity, productId)
+
+Track item removal from cart.
+
+**Example:**
+```javascript
+window.pushRemoveFromCartToAnalytics('var123', 1, 'prod789');
+```
+
+#### pushSearchToAnalytics(searchQuery)
+
+Track search interactions.
+
+**Example:**
+```javascript
+window.pushSearchToAnalytics('summer dresses');
+```
+
+#### pushSelectListItemToAnalytics(productId, listData)
+
+Track product selection from list/collection.
+
+**Parameters:**
+- `productId`: Selected product
+- `listData`: Object with `id` and `title`
+
+**Example:**
+```javascript
+window.pushSelectListItemToAnalytics('prod123', {
+  id: 'featured',
+  title: 'Featured Products'
+});
+```
+
+#### pushViewProductDetailsToAnalytics(productId)
+
+Track product detail page views.
+
+**Example:**
+```javascript
+window.pushViewProductDetailsToAnalytics('prod123');
+```
+
+#### pushCheckOutBeginToAnalytics()
+
+Track checkout initiation.
+
+**Example:**
+```javascript
+window.pushCheckOutBeginToAnalytics();
+```
+
+#### pushShippingInfoToAnalytics()
+
+Track shipping method selection.
+
+**Example:**
+```javascript
+window.pushShippingInfoToAnalytics();
+```
+
+#### pushPaymentInfoToAnalytics()
+
+Track payment method selection.
+
+**Example:**
+```javascript
+window.pushPaymentInfoToAnalytics();
+```
+
+#### pushPurchaseInfoToAnalytics()
+
+Track successful purchase.
+
+**Example:**
+```javascript
+window.pushPurchaseInfoToAnalytics();
+```
+
+---
+
+## Integration Example
+
+Here's a typical pattern for integrating both scripts:
+
+```html
+<!-- Include both scripts -->
+<script src="https://cdn.example.com/storefront-actions/latest/storefront-actions.js" defer></script>
+<script src="https://cdn.example.com/analytics/latest/analytics.js" defer></script>
+
+<!-- Add to cart button -->
+<button onclick="handleAddToCart()">Add to Cart</button>
+
+<script>
+async function handleAddToCart() {
+  try {
+    // Call storefront action
+    const result = await addToCart(variantId, orgId, 'cart-items', 1, productId);
+    
+    // Update UI with response
+    document.getElementById('cart-section').innerHTML = result.sections.cartItems;
+    
+    // Analytics is automatically tracked if productId provided
+    // But can also explicitly call:
+    window.pushAddToCartEventToAnalytics(variantId, 1, productId);
+  } catch (error) {
+    console.error('Failed to add to cart:', error);
+  }
+}
+</script>
+```
+
+---
+
+## Benefits
+
+- **No Boilerplate**: Use pre-built functions instead of writing API calls
+- **Built-in Analytics**: Actions automatically integrate with Zoho Analytics
+- **Section Rendering**: Get live-updated section HTML from server
+- **Error Handling**: Consistent error responses across all functions
+- **Marketing Integration**: Track conversions for email, SMS, and ads
+
+---
+
+## Notes
+
+- Scripts are automatically versioned by Zoho Commerce
+- Always use `await` for async functions
+- Include both scripts for full functionality
+- Check browser console for errors during development
+- Scripts are available on Zoho Commerce CDN
+
+

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/i18n.md

@@ -0,0 +1,155 @@
+---
+title: "Internationalization"
+weight: 9
+---
+
+# i18n
+
+Zoho Commerce themes support multiple languages through translation files stored in the `i18n/` folder.
+
+## Translation Files
+
+The `i18n/` folder contains translation files. Two files are required in every theme; additional language files are added when targeting multiple languages:
+
+```
+i18n/
+├── en.json        # English (default fallback)
+├── en.schema.json # Schema label translations for the theme editor UI
+├── ar.json        # Arabic
+├── de.json        # German
+├── es.json        # Spanish
+├── fr.json        # French
+├── id.json        # Indonesian
+├── ja.json        # Japanese
+├── ko.json        # Korean
+├── pt.json        # Portuguese
+├── th.json        # Thai
+├── vi.json        # Vietnamese
+├── zh.json        # Chinese (Simplified)
+└── zh_tw.json     # Chinese (Traditional)
+```
+
+### File Format
+
+`en.json` uses nested keys grouped by component:
+
+```json
+{
+  "common": {
+    "home": "Home",
+    "loader": "Loading"
+  },
+  "header": {
+    "sign_in": "Sign In",
+    "sign_up": "Sign Up",
+    "sign_out": "Sign Out",
+    "my_profile": "My Profile",
+    "my_orders": "My Orders",
+    "my_wishlist": "My Wishlist"
+  },
+  "product_details": {
+    "sold_out": "Sold Out",
+    "on_sale": "On sale"
+  },
+  "pagination": {
+    "previous_btn": "<",
+    "next_btn": ">",
+    "per_page": "per page"
+  }
+}
+```
+
+---
+
+## Using Translations
+
+Use the `t` (translate) filter in templates:
+
+```liquid
+<!-- Simple key -->
+<button>{{ "header.sign_in" | t }}</button>
+```
+**Output:** `Sign In`
+
+```liquid
+<!-- Nested keys use dot notation -->
+<span>{{ "header.my_orders" | t }}</span>
+<p>{{ "product_details.sold_out" | t }}</p>
+```
+**Output:** `My Orders` / `Sold Out`
+
+### Output
+
+The `t` filter looks up the key in the current locale's JSON file and returns the translated string. If the key is missing in the current locale, it falls back to `en.json`. If the key is missing there too, it returns the key itself as a fallback.
+
+---
+
+## Schema Label Translations
+
+Section schema labels can reference translation keys using the `t:` prefix:
+
+```json
+{
+  "type": "text",
+  "id": "heading",
+  "label": "t:sections.hero.settings.heading.label",
+  "default": "Welcome"
+}
+```
+
+This makes the theme editor UI appear in the merchant's language.
+
+Schema translations are stored in `i18n/en.schema.json`:
+
+```json
+{
+  "sections": {
+    "hero": {
+      "name": "Hero Banner",
+      "settings": {
+        "heading": {
+          "label": "Heading Text"
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Adding a New Language
+
+1. Create a new JSON file in `i18n/` using a locale code (e.g., `fr.json` for French)
+2. Copy the structure from `en.json`
+3. Translate all values
+4. Configure the language in the Zoho Commerce admin
+
+Example `i18n/fr.json`:
+
+```json
+{
+  "header": {
+    "sign_in": "Se connecter",
+    "sign_up": "S'inscrire",
+    "sign_out": "Se déconnecter",
+    "my_profile": "Mon profil",
+    "my_orders": "Mes commandes"
+  },
+  "product_details": {
+    "sold_out": "Épuisé",
+    "on_sale": "En solde"
+  }
+}
+```
+
+---
+
+## Best Practices
+
+- **Use `en.json` as the source of truth** — all other languages should translate from it
+- **Use descriptive, nested keys** — `product_details.sold_out` not `btn1`
+- **Never hardcode user-facing text** — always use the `t` filter
+- **Group keys by component** — `header.*`, `footer.*`, `product_details.*`
+- **Keep translations consistent** — use the same terminology throughout
+- **Test all languages** — verify translations render correctly in RTL languages like Arabic

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/introduction.md

@@ -0,0 +1,91 @@
+---
+title: "Overview"
+weight: 1
+---
+
+# Overview
+
+Welcome to the Zoho Commerce Liquid theme development documentation. This guide covers everything you need to build, customize, and deploy themes.
+
+## What This Covers
+
+- **Theme Structure** — Required folders, files, and naming conventions
+- **Liquid Templating** — Variables, filters, tags, and control flow
+- **Sections & Blocks** — Admin-customizable components with schema
+- **Zoho Extensions** — Platform-specific filters, objects, and scripts
+- **Best Practices** — Performance, security, and accessibility patterns
+
+---
+
+<details open>
+<summary><strong>What is Liquid?</strong></summary>
+
+Liquid is an open-source templating language designed for safe, customer-facing template rendering. It separates presentation from logic, making themes secure and maintainable.
+
+### Core Concepts
+
+**Variables** — Display dynamic data:
+```liquid
+{{ product.title }}
+{{ store.name }}
+```
+
+**Filters** — Transform output:
+```liquid
+{{ product.title | upcase }}
+{{ product.price | divided_by: 100 }}
+{{ "hero.jpg" | asset_url }}
+```
+
+**Tags** — Control logic and flow:
+```liquid
+{% if product.available %}
+  <button>{{ "product.add_to_cart" | t }}</button>
+{% endif %}
+
+{% for item in collection.products %}
+  {{ item.title }}
+{% endfor %}
+```
+
+**Comments** — Notes without output:
+```liquid
+{% comment %} This won't render {% endcomment %}
+```
+
+### Why Liquid?
+
+| Aspect | Liquid | Traditional Code |
+|--------|--------|-----------------|
+| Security | Safe by design — no arbitrary code execution | Requires careful sanitization |
+| Learning curve | Gentle — HTML + simple tags | Steeper |
+| Use case | Templates only | General-purpose |
+| Performance | Optimized for rendering | More overhead |
+
+### Zoho Commerce Extensions
+
+Beyond standard Liquid, Zoho Commerce adds:
+
+- `asset_url` — Versioned asset URLs with cache busting
+- `image_url` — Dynamic image URLs with optional dimension parameters
+- `color_component` — Extract RGB/HSL values from colors
+- `t` — Multi-language translation from i18n files
+- Global objects for store, product, collection, and customer data
+- Schema system for admin-customizable settings
+
+**Reference:** [Liquid official documentation](https://shopify.github.io/liquid/)
+
+</details>
+
+---
+
+## Quick Start
+
+1. Read [Theme Structure](/theme-structure/) to understand the required folder layout
+2. Follow [Setup Guide](/setup-guide/) to configure your development environment
+3. Build sections using [Sections](/sections/) and [Schema Types](/reference/schema-types/)
+4. Use [Filters](/reference/filters/) and [Tags](/reference/tags/) for template logic
+5. Review [Best Practices](/best-practices/) before publishing
+
+**For experienced developers:** Start from [Filters](/reference/filters/) and work through the reference pages — [Tags](/reference/tags/), [Schema Types](/reference/schema-types/), and [Global Objects](/reference/global-objects/) — as each may contain Zoho-specific additions.
+

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/layouts.md

@@ -0,0 +1,158 @@
+---
+title: "Layouts"
+weight: 4
+---
+
+# Layouts
+
+Layouts are the outermost HTML wrapper for every page. They define the document structure, inject site-wide scripts/styles, and render page content.
+
+## Required Files
+
+| File | Purpose |
+|------|---------|
+| `theme.liquid` | Default layout for all store pages |
+| `accounts.liquid` | Layout for authentication and account pages (sign-in, sign-up, profile, orders, addresses) |
+| `sitemap.liquid` | XML sitemap for search engine crawlers |
+
+---
+
+## theme.liquid
+
+The main layout wrapping every page:
+
+```liquid
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <title>{{ page_title }}</title>
+    {{ content_for_header }}
+  </head>
+  <body>
+    {% sections 'header-group' %}
+    
+    <main>
+      {{ content_for_layout }}
+    </main>
+    
+    {% sections 'footer-group' %}
+    {{ content_for_footer }}
+  </body>
+</html>
+```
+
+### Layout Variables
+
+| Variable | Placement | Description |
+|----------|-----------|-------------|
+| `content_for_header` | Inside `<head>` | Server-injected platform scripts, meta tags, stylesheets, and analytics from Zoho Commerce admin |
+| `content_for_layout` | Inside `<body>` | Renders the page-specific content (sections, blocks) |
+| `content_for_footer` | Before `</body>` | Injects scripts that must load after DOM |
+
+> **Note:** The `{{ content_for_header }}` variable outputs code that the server builds from Zoho Commerce admin settings. Along with meta tags and other head assets, **analytics scripts are included here when configured**—you do not need to add or integrate analytics explicitly in the theme; including this variable in `<head>` is enough.
+
+---
+
+## Section Groups
+
+`{% sections 'header-group' %}` and `{% sections 'footer-group' %}` are **Zoho Commerce-specific tags** — they are not part of standard Liquid. They render a named section group, which is defined by a `.json` file in the `sections/` folder.
+
+### What is a Section Group?
+
+A section group is a JSON file that defines a fixed set of sections rendered together as a unit (like the header or footer). Unlike page JSON files where admins can freely add/remove sections, section groups have a fixed structure configured by the theme.
+
+```
+sections/
+├── header-group.json    # defines the header group
+├── footer-group.json    # defines the footer group
+```
+
+### Group JSON Structure
+
+```json
+{
+  "name": "Header",
+  "type": "header",
+  "sections": {
+    "header": {
+      "type": "header",
+      "settings": {
+        "menu_type": { "display_name": "Drill Down", "value": "1" }
+      }
+    }
+  },
+  "order": ["header"]
+}
+```
+
+| Property | Description |
+|----------|-------------|
+| `name` | Display name for the group |
+| `type` | Group type identifier (`"header"` or `"footer"`) |
+| `sections` | Map of section instances keyed by ID |
+| `order` | Array of section IDs in render order |
+
+Each entry in `sections` is a section instance with `type` (matching a `.liquid` file in `sections/`) and `settings`. The `order` array controls which sections render and in what order.
+
+### Usage in theme.liquid
+
+```liquid
+{% sections 'header-group' %}   {%- comment -%} Zoho Commerce-specific tag {%- endcomment -%}
+
+<main>
+  {{ content_for_layout }}
+</main>
+
+{% sections 'footer-group' %}
+```
+
+---
+
+## accounts.liquid
+
+Used for both authentication pages (sign-in, sign-up, forgot password) and all account pages (profile, orders, addresses). Selected by adding `"layout": "accounts"` in a page JSON file — see [Pages](/pages/) for details.
+
+This layout does not use `{% sections 'header-group' %}` or `{% sections 'footer-group' %}`. Instead it renders the `accounts-header` snippet directly, which handles the before/after-signin header states for account pages. It also loads the Zoho accounts portal scripts required for authentication to function.
+
+```liquid
+<!DOCTYPE html>
+<html lang="en-us">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="shortcut icon" href="{{ store.favicon.url }}">
+    <link rel="stylesheet" href="{{ "style.css" | asset_url }}">
+    <link rel="stylesheet" href="{{ "signin.css" | asset_url }}">
+    <link rel="stylesheet" href="{{ "theme-settings.css" | asset_url }}">
+    <script src="{{ "portal-signup.js" | asset_url }}" defer></script>
+    <script src="{{ routes.signup_url }}" defer></script>
+    <title>
+      {{ page_title }}
+      {% unless page_title contains store.name %}
+        &ndash; {{ store.name }}
+      {% endunless %}
+    </title>
+  </head>
+  <body>
+    {% render "accounts-header", store: store %}
+    {{ content_for_layout }}
+    {% render "theme-settings" %}
+  </body>
+</html>
+```
+
+> The `accounts_signup_url` script is the Zoho accounts portal JS bundle. It is required for sign-in, sign-up, and password reset flows to work.
+
+
+---
+
+## sitemap.liquid
+
+Renders the XML sitemap at `/sitemap.xml`. The sitemap content is generated by Zoho Commerce and injected via `content_for_layout`:
+
+```liquid
+{{ content_for_layout }}
+```
+
+Zoho Commerce automatically generates and serves the sitemap XML — the layout just provides the wrapper for the platform to inject it.