@zohofinance/commerce 1.0.0 → 1.1.0

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

@@ -0,0 +1,424 @@
+---
+title: "Setup Guide"
+weight: 3
+---
+
+# Setup Guide
+
+Get your Zoho Commerce theme development environment ready in minutes.
+
+## Prerequisites
+
+Before starting, make sure you have:
+
+- A code editor (VS Code recommended)
+- Node.js (version 16 or higher)
+- A Zoho Commerce store (or test account)
+- Basic understanding of HTML/CSS
+- Familiarity with command line
+
+## Installing the CLI and Setting Up Your Theme
+
+The recommended way to develop themes is using our CLI tool for local preview and the build tool for deployment.
+
+### Step 1: Create Theme Folder Structure
+
+Set up your theme directory with the required folders:
+
+```bash
+mkdir my-theme && cd my-theme
+mkdir assets i18n layouts sections snippets settings pages
+```
+
+### Step 2: Start Development Server
+
+Run the development server using npx:
+
+```bash
+npx @zohofinance/commerce theme dev
+```
+
+This starts a local development server that:
+- Watches for file changes and reloads automatically
+- Renders your Liquid templates with mock data
+- Serves assets from the `assets/` folder
+- Provides a local preview of your storefront
+
+### Step 3: Connect to Live Store Data
+
+To preview your theme with real data from your Zoho Commerce store:
+
+```bash
+npx @zohofinance/commerce theme dev --storeUrl=https://yourstore.zohocommerce.com
+```
+
+This connects to the specified store and pulls live data — products, collections, customer information, pricing, and more.
+
+> **Tip — Inspect the live data shape:** Before writing Liquid for any page, visit that page on your store with `?format=json` appended to the URL (e.g., `https://yourstore.zohocommerce.com/products/my-product?format=json`). The response is the exact JSON node tree that the Liquid template receives, so you can see every available object, key, and nested property before writing a single `{{ }}` expression.
+
+## Understanding the Files
+
+Key files to examine first in your new theme:
+
+1. **`layouts/theme.liquid`** - Main HTML structure
+2. **`settings/schema.json`** - Theme-wide settings
+3. **`sections/header.liquid`** - Header component
+4. **`i18n/en.json`** - Translation strings
+5. **`assets/main.css`** - Main stylesheet
+
+### Making Your First Change
+
+Let's modify a section setting:
+
+1. Open `sections/header.liquid`
+2. Find the `{% schema %}` block at the bottom
+3. Locate a text setting and modify its default value:
+
+```json
+{
+  "type": "text",
+  "id": "announcement",
+  "label": "t:sections.header.settings.announcement.label",
+  "default": "Free shipping on orders over $50"
+}
+```
+
+4. Save the file — the dev server will automatically reload
+
+## Local Development Setup
+
+For a professional development workflow:
+
+### VS Code Setup (Recommended)
+
+1. **Install Liquid extension:**
+   - Open VS Code
+   - Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
+   - Search for "Liquid" 
+   - Install a Liquid language support extension
+
+2. **Open the theme folder:**
+   - File > Open Folder > select your theme folder
+
+## Theme Development Workflow
+
+### 1. Planning Your Theme
+
+Before coding, plan:
+
+- **Layout**: How will pages be organized?
+- **Colors**: What's your color scheme?
+- **Typography**: What fonts will you use?
+- **Components**: What sections do you need?
+- **Features**: What Zoho Commerce features will you use?
+
+### 2. Setting Up Structure
+
+```bash
+theme/
+├── assets/
+│   ├── style.css
+│   ├── main.css
+│   ├── theme-settings.css
+│   ├── signin.css
+│   ├── header.js
+│   ├── footer.js
+│   ├── add-to-cart.js
+│   ├── cart-items.js
+│   ├── product-images.js
+│   ├── search-bar.js
+│   └── fingerprint.json
+├── i18n/
+│   ├── en.json
+│   └── en.schema.json
+│   └── ...
+├── layouts/
+│   ├── theme.liquid
+│   ├── accounts.liquid
+│   └── sitemap.liquid
+├── pages/
+│   ├── index.json
+│   ├── product.json
+│   ├── collection.json
+│   └── ...
+├── sections/
+│   ├── header.liquid
+│   ├── header-group.json
+│   ├── footer.liquid
+│   ├── footer-group.json
+│   └── ...
+├── settings/
+│   ├── schema.json
+│   └── theme.json
+└── snippets/
+    ├── product-card.liquid
+    ├── pagination.liquid
+    └── ...
+```
+
+### 3. Creating Your First Section
+
+Create `sections/hero-banner.liquid`:
+
+```liquid
+{% assign settings = section.settings %}
+
+<section class="hero-banner" style="background: {{ settings.bg_color }}">
+  <div class="hero-content">
+    <h1>{{ settings.title }}</h1>
+    <p>{{ settings.subtitle }}</p>
+    <a href="{{ settings.button_url.handle }}" class="btn">{{ settings.button_text }}</a>
+  </div>
+</section>
+
+<style>
+  .hero-banner {
+    padding: {{ settings.desktop_padding }}px;
+    text-align: center;
+    color: {{ settings.text_color }};
+  }
+  
+  .btn {
+    background: {{ settings.button_color }};
+    color: white;
+    padding: 12px 30px;
+    text-decoration: none;
+    border-radius: 4px;
+    display: inline-block;
+  }
+</style>
+
+{% schema %}
+{
+  "name": "t:sections.hero_banner.name",
+  "category": "Banner",
+  "tag": "section",
+  "class": "section",
+  "available_in": {"templates": ["index", "category", "collection"]},
+  "settings": [
+    {
+      "type": "text",
+      "id": "title",
+      "label": "t:sections.hero_banner.settings.title.label",
+      "default": "Welcome"
+    },
+    {
+      "type": "text",
+      "id": "subtitle",
+      "label": "t:sections.hero_banner.settings.subtitle.label",
+      "default": "Your tagline here"
+    },
+    {
+      "type": "color",
+      "id": "bg_color",
+      "label": "t:sections.hero_banner.settings.bg_color.label",
+      "default": "#f5f5f5"
+    },
+    {
+      "type": "color",
+      "id": "text_color",
+      "label": "t:sections.hero_banner.settings.text_color.label",
+      "default": "#333333"
+    },
+    {
+      "type": "url",
+      "id": "button_url",
+      "label": "t:sections.hero_banner.settings.button_url.label",
+      "default": { "display_name": "t:sections.hero_banner.settings.button_url.default", "handle": "collections/all-products" }
+    },
+    {
+      "type": "text",
+      "id": "button_text",
+      "label": "t:sections.hero_banner.settings.button_text.label",
+      "default": "Learn More"
+    },
+    {
+      "type": "color",
+      "id": "button_color",
+      "label": "t:sections.hero_banner.settings.button_color.label",
+      "default": "#000000"
+    },
+    {
+      "type": "range",
+      "id": "desktop_padding",
+      "label": "t:sections.hero_banner.settings.padding.label",
+      "min": 0,
+      "max": 100,
+      "step": 10,
+      "unit": "px",
+      "default": 50,
+      "meta": "desktop"
+    },
+    {
+      "type": "range",
+      "id": "mobile_padding",
+      "label": "t:sections.hero_banner.settings.padding.label",
+      "min": 0,
+      "max": 60,
+      "step": 5,
+      "unit": "px",
+      "default": 30,
+      "meta": "mobile"
+    }
+  ]
+}
+{% endschema %}
+```
+
+### 4. Testing Your Theme
+
+Test your theme using the CLI with your store's live data:
+
+```bash
+npx @zohofinance/commerce theme dev --storeUrl=https://yourstore.zohocommerce.com
+```
+
+The dev server will show your theme preview at `http://localhost:3000`.
+
+Testing checklist:
+- Check the admin UI customization works
+- Test on mobile and desktop
+- Verify all translations appear
+- Test with real product data
+
+## Publishing Your Theme
+
+### Step 1: Prepare for Publishing
+
+Checklist:
+- ✅ All sections working correctly
+- ✅ No broken links or references
+- ✅ Mobile responsive design tested
+
+> Validation (Liquid, JS, translations, assets), asset fingerprinting, and minification are all handled automatically by the CLI build command — no manual steps needed.
+
+### Step 2: Build and Package Theme
+
+Run the build command:
+
+```bash
+npx @zohofinance/commerce theme build
+```
+
+The CLI validates all theme files, fingerprints assets, and produces a `theme.zip` ready for upload. If any issues are found, the build halts with a clear error report.
+
+For a production-ready package with minification and Brotli compression:
+
+```bash
+npx @zohofinance/commerce theme build --prod
+```
+
+### Step 3: Upload to Zoho Commerce
+
+1. Log in to Zoho Commerce admin
+2. Go to **Online Store** → **Themes**
+3. Click **Upload Custom Theme** or **Create From Template**
+4. Select your `theme.zip` file
+5. Click **Upload**
+6. Zoho will process and activate your theme
+
+### Step 4: Add to Marketplace (Optional)
+
+Once your theme is working:
+
+1. Polish and test thoroughly
+2. Create marketing screenshots
+3. Write description
+4. Contact Zoho Commerce team
+5. Submit for marketplace review
+
+## Troubleshooting
+
+### Common Issues
+
+**Sections not appearing:**
+- Check the page JSON includes the section
+- Verify section filename matches the type
+- Check for schema errors in the Liquid editor
+
+**Images not loading:**
+- Ensure using `asset_url` filter for theme assets
+- Use `image_url` filter for product images
+- Verify no typos in filenames
+- Check fingerprint.json has correct mappings
+
+**Translations missing:**
+- Check key exists in `i18n/en.json`
+- Verify key path (nested object structure)
+- Ensure key is used with `t` or `translate` filter
+
+**Styling not applied:**
+- Clear browser cache
+- Check CSS asset is in assets folder
+- Verify using `asset_url` filter properly
+- Check for CSS specificity conflicts
+
+**Schema not working:**
+- Validate JSON syntax (use JSON validator)
+- Ensure all IDs are unique within section
+- Check default values match setting type format
+- Verify translation key format (`t:` prefix)
+
+## Development Best Practices
+
+### Comments and Documentation
+
+```liquid
+{%- comment -%}
+Product card component
+Displays product image, title, price
+Parameters:
+- product: product object
+- show_price: boolean (default true)
+{%- endcomment -%}
+
+<article class="product-card">
+  <!-- Product image -->
+  <img src="{{ product.cover_media | image_url }}" alt="{{ product.title }}">
+  
+  <!-- Product info -->
+  <div class="product-info">
+    <h3>{{ product.title }}</h3>
+    {% if show_price %}
+      <p class="price">{{ product.price }}</p>
+    {% endif %}
+  </div>
+</article>
+```
+
+---
+
+## CLI Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `npx @zohofinance/commerce theme dev` | Start local dev server with mock data |
+| `npx @zohofinance/commerce theme dev --storeUrl=<url>` | Start dev server with live store data |
+| `npx @zohofinance/commerce theme build` | Fingerprint assets, validate all files, and create `theme.zip` |
+| `npx @zohofinance/commerce theme build --prod` | Same as above, plus minification and Brotli compression |
+
+---
+
+## Quick Start
+
+Set up your theme development environment:
+
+```bash
+# Create theme folder
+mkdir my-theme && cd my-theme
+mkdir assets i18n layouts sections snippets settings pages
+
+# Start development server
+npx @zohofinance/commerce theme dev
+
+# Connect to your store for live data
+npx @zohofinance/commerce theme dev --storeUrl=https://yourstore.zohocommerce.com
+
+# Build for deployment (fingerprints, validates, creates zip)
+npx @zohofinance/commerce theme build
+
+# Production build (also minifies + Brotli compresses)
+npx @zohofinance/commerce theme build --prod
+```
+
+

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

@@ -0,0 +1,70 @@
+---
+title: "Snippets"
+weight: 6
+---
+
+# Snippets
+
+Snippets are reusable Liquid partials stored in the `snippets/` folder. Use them to avoid duplicating markup across sections and layouts.
+
+## Using Snippets
+
+Include a snippet with the `render` tag:
+
+```liquid
+{% render 'product-card', product: item %}
+```
+
+> The `.liquid` extension is omitted — `'product-card'` loads `snippets/product-card.liquid`.
+
+---
+
+## Passing Variables
+
+Variables must be explicitly passed to snippets. Snippets cannot access parent template variables directly.
+
+```liquid
+<!-- Pass a single variable -->
+{% render 'price-display', price: product.price %}
+
+<!-- Pass multiple variables -->
+{% render 'product-card', product: item, show_price: true, index: forloop.index %}
+```
+
+Inside the snippet, use the passed variable names directly:
+
+```liquid
+<!-- snippets/product-card.liquid -->
+<div class="product-card">
+  <h3>{{ product.title }}</h3>
+  {% if show_price %}
+    <span>{{ product.price }}</span>
+  {% endif %}
+</div>
+```
+
+---
+
+## Common Snippets
+
+| Snippet | Purpose |
+|---------|---------|
+| `product-card.liquid` | Product display card used in collections |
+| `pagination.liquid` | Page navigation for collections |
+| `product-variant-picker.liquid` | Variant selection UI (size, color, etc.) |
+| `icon-cart.liquid` | Cart icon SVG |
+| `icon-search.liquid` | Search icon SVG |
+| `theme-settings.liquid` | Injects dynamic CSS variables for theme settings |
+| `cookie-bar.liquid` | Cookie consent bar |
+| `message-bar.liquid` | Site-wide announcement/message bar |
+
+> **Note:** Header and footer are **sections** (in `sections/`), not snippets. They are rendered via the `{% sections 'header-group' %}` and `{% sections 'footer-group' %}` tags in the layout, not with `{% render %}`.
+
+---
+
+## Best Practices
+
+- **Keep snippets focused** — one snippet, one responsibility
+- **Always pass variables explicitly** — snippets have isolated scope
+- **Use descriptive filenames** — `product-card.liquid` not `pc.liquid`
+- **Avoid deeply nesting snippets** — one level of `render` inside another is fine; deeper nesting hurts readability