@zohofinance/commerce 1.0.0 → 1.0.1

package/ts-dist/mocks/init-theme/.cursor/rules/javascript.mdc

@@ -0,0 +1,85 @@
+---
+description: JavaScript rules — applies to all themes
+globs: ["assets/*.js"]
+---
+
+# JavaScript Rules — b2bizmart Theme
+
+## Core Principles
+- Vanilla JS only — NO jQuery, NO external UI frameworks
+- Use class-based Web Components (extend HTMLElement) for interactive section components
+- All async operations use `fetch()` with proper error handling
+- Dispatch custom events for cross-component communication
+
+---
+
+## Web Component Pattern
+```javascript
+class MyComponent extends HTMLElement {
+  connectedCallback() {
+    this.init();
+  }
+
+  init() {
+    // setup logic
+  }
+}
+
+customElements.define('my-component', MyComponent);
+```
+
+---
+
+## Custom Event Pattern
+```javascript
+// Dispatch
+this.dispatchEvent(new CustomEvent('my-component:updated', {
+  bubbles: true,
+  detail: { data: value }
+}));
+
+// Listen
+document.addEventListener('my-component:updated', (e) => {
+  const { data } = e.detail;
+});
+```
+
+---
+
+## Fetch Pattern
+```javascript
+async function fetchData(url) {
+  try {
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: { 'Content-Type': 'application/json' }
+    });
+    if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+    return await response.json();
+  } catch (error) {
+    console.error('Fetch error:', error);
+  }
+}
+```
+
+---
+
+## DOM Query Patterns
+```javascript
+// Prefer attribute selectors for component hooks
+const el = this.querySelector('[data-cart-count]');
+const items = this.querySelectorAll('[data-product-card]');
+
+// Use data attributes for JS hooks, not CSS classes
+// ✅ data-sidebar-overlay
+// ❌ .js-sidebar-overlay
+```
+
+---
+
+## Script Loading in Liquid
+```liquid
+<script src="{{ 'component.js' | asset_url }}" defer></script>
+```
+- Always `defer` — never `async` unless specifically needed
+- Load at top of the section `.liquid` file that uses the component

package/ts-dist/mocks/init-theme/.cursor/rules/liquid-no-hardcoded-strings.mdc

@@ -0,0 +1,42 @@
+---
+description: No hardcoded user-facing strings in Liquid files — always use i18n translation keys
+globs: **/*.liquid
+alwaysApply: true
+---
+
+# No Hardcoded Strings in Liquid Templates
+
+Every user-facing string in a `.liquid` file **must** come from the i18n locale files (`i18n/en.default.json` or `i18n/en.default.schema.json`). Never write raw text directly in the markup.
+
+## Rules
+
+1. Use `{{ 'key.path' | t }}` for runtime translations (`en.default.json`).
+2. Use `"t:key.path"` inside `{% schema %}` blocks for editor labels/defaults (`en.default.schema.json`).
+3. If the required key does not exist yet, **add it** to the appropriate locale JSON file and then reference it.
+4. HTML attributes that render visible text (`alt`, `title`, `placeholder`, `aria-label`, button text, headings, paragraphs, etc.) must all use translation filters/keys.
+
+## Examples
+
+```liquid
+❌ BAD — hardcoded string
+<h2>Shop by Category</h2>
+<input placeholder="Search products">
+<button>Add to Cart</button>
+
+✅ GOOD — translated
+<h2>{{ 'category.heading' | t }}</h2>
+<input placeholder="{{ 'header.blocks.header_search.search_placeholder' | t }}">
+<button>{{ 'product.add_to_cart' | t }}</button>
+```
+
+```liquid
+❌ BAD — hardcoded schema label
+{% schema %}
+{ "settings": [{ "label": "Background color" }] }
+{% endschema %}
+
+✅ GOOD — translated schema label
+{% schema %}
+{ "settings": [{ "label": "t:sections.banner.settings.bg_color.label" }] }
+{% endschema %}
+```

package/ts-dist/mocks/init-theme/.cursor/rules/liquid.mdc

@@ -0,0 +1,171 @@
+---
+description: Liquid templating rules — applies to all themes
+globs: ["**/*.liquid"]
+---
+
+# Liquid Rules — b2bizmart Theme
+
+## Core Principles
+- This is a CUSTOM Liquid system, not standard Shopify
+- NEVER assume standard Shopify objects like `shop`, `product`, `collection`, `cart` behave identically
+- Always use `{% render 'snippet-name' %}` — NEVER `{% include %}`
+- Always escape user-generated output: `{{ value | escape }}`
+
+---
+
+## Global Objects Available
+```liquid
+{{ organization.organizationName }}     → store name
+{{ organization.logo.url }}             → logo image URL
+{{ organization.email }}
+{{ organization.phone }}
+{{ organization.social_media_list }}    → array of social links
+{{ organization.customer_accounts_enabled }} → boolean
+{{ pageinfo.origin }}                 → base URL for internal links (e.g. /home, /cart)
+{{ default_menu.menuItems }}            → array of nav items
+{{ cart.item_count }}                   → cart item count
+```
+
+---
+
+## Asset References
+```liquid
+{{ 'filename.js' | asset_url }}         → JS file URL
+{{ 'filename.css' | asset_url }}        → CSS file URL
+{{ 'filename.svg' | asset_url }}        → SVG/image file URL
+```
+
+---
+
+## Internal Links
+Always prefix internal URLs with `{{ pageinfo.origin }}`:
+```liquid
+<a href="{{ pageinfo.origin }}/home">Home</a>
+<a href="{{ pageinfo.origin }}/cart">Cart</a>
+<a href="{{ pageinfo.origin }}/wishlists">Wishlist</a>
+```
+
+---
+
+## Accessing Settings in Liquid
+```liquid
+{{ section.settings.field_id }}                    → text, range, color, checkbox
+{{ section.settings.url_field.handle }}            → url type: the path
+{{ section.settings.url_field.display_name }}      → url type: the label
+{{ section.settings.select_field.value }}          → select type: the value
+{{ section.settings.select_field.display_name }}   → select type: the label
+{{ section.settings.image_field.url }}             → image_picker type: the filename/url
+{{ section.settings.video_media.url }}             → media_picker type: video filename/url
+{{ section.settings.video_media.is_video }}        → media_picker type: boolean flag
+{{ section.settings.menu_field.handle }}           → menu type: the handle
+{{ section.settings.menu_field.display_name }}     → menu type: the label
+```
+
+---
+
+## Rendering Snippets
+```liquid
+{% render 'snippet-name' %}
+{% render 'snippet-name', variable: value %}
+{% render 'snippet-name', section: section %}
+```
+
+---
+
+## Loop Patterns
+Always handle empty states in loops:
+```liquid
+{% if items.size > 0 %}
+  {% for item in items %}
+    ...
+  {% endfor %}
+{% else %}
+  <p>No items found.</p>
+{% endif %}
+```
+
+---
+
+## Navigation Menu Loop
+```liquid
+{% for menuItem in default_menu.menuItems %}
+  <a href="{{ menuItem.url }}">{{ menuItem.name }}</a>
+{% endfor %}
+```
+
+---
+
+## CSS Patterns
+Use Tailwind utility classes + CSS custom properties together:
+```liquid
+<div class="flex items-center gap-4" style="color: var(--color-heading); background-color: var(--color-background);">
+```
+
+### Available CSS Custom Properties
+```
+--color-primary
+--color-on-primary
+--color-heading
+--color-background
+--color-border
+--color-header-bg
+--section-padding-x
+```
+
+---
+
+## Image Rendering
+```liquid
+<img
+  src="{{ section.settings.image_field.url }}"
+  alt="{{ section.settings.alt_text | escape }}"
+  width="800"
+  height="600"
+  loading="lazy"
+>
+```
+- Always include `width`, `height`, `alt`, and `loading` attributes
+- Use `loading="eager"` only for above-the-fold images (hero, header logo)
+- ❌ NEVER use `{{ image | img_url }}` — that is standard Shopify syntax
+
+---
+
+## Script Loading
+```liquid
+<script src="{{ 'component.js' | asset_url }}" defer></script>
+```
+- Always use `defer` for non-critical scripts
+- Load scripts at the top of the section file that needs them
+
+---
+
+## Section Tag
+```liquid
+<section class="section-name" id="section-{{ section.id }}">
+  ...
+</section>
+```
+
+---
+
+## Liquid Assign Block Pattern
+Use `{% liquid %}` for multiple assignments:
+```liquid
+{% liquid
+  assign field_one = section.settings.field_one
+  assign field_two = section.settings.field_two.value
+  assign show_item = section.settings.show_item
+%}
+```
+
+---
+
+## Style Block for Dynamic CSS
+```liquid
+{% style %}
+  #section-{{ section.id }} {
+    padding-top: {{ section.settings.padding_top }}px;
+    padding-bottom: {{ section.settings.padding_bottom }}px;
+  }
+{% endstyle %}
+```

package/ts-dist/mocks/init-theme/.cursor/rules/mobile-desktop-setting-meta.mdc

@@ -0,0 +1,34 @@
+---
+description: Schema settings tied to mobile or desktop breakpoints — meta and neutral labels
+globs: **/*.liquid,**/i18n/**/*.json
+alwaysApply: false
+---
+
+# Mobile / desktop settings in section & block schema
+
+## When to set `meta`
+
+- If a setting **only applies to one breakpoint** (small screen vs `md`+ / large screen), or is the **mobile-specific** or **desktop-specific** member of a pair, it **must** include `"meta"`.
+- Use **only**:
+  - **`"meta": "mobile"`** — small-screen / default (pre-`md`) behavior.
+  - **`"meta": "desktop"`** — large-screen / `md`+ behavior.
+- Settings that are **truly global** (same value at all breakpoints) **do not** need `mobile` / `desktop` meta.
+
+This applies to **any** setting type: `image_picker`, `select`, `text`, `richtext`, `color`, `range`, `checkbox`, etc.—not only font-size controls.
+
+## Neutral naming (labels)
+
+- **Do not** put the words *mobile* or *desktop* in the merchant-facing **label** or locale schema `label` when `meta` already encodes the breakpoint.
+- Use a **generic, semantic** label that describes **what** the setting controls (e.g. “Image”, “Font size”, “Padding”, “Background color”), repeated for both members of a pair if appropriate—the editor groups them by `meta`.
+- Prefer setting **ids** that encode breakpoint when paired: `*_mobile` / `*_desktop` (or `mobile_*` / `desktop_*` if that matches existing conventions), so Liquid and JSON stay clear without relying on label text.
+
+## Implementation notes
+
+- **Pairs:** Two settings, same conceptual label text, different `id` and `meta` (e.g. two “Image” pickers with `meta: "mobile"` and `meta: "desktop"`—same pattern as separate banner images).
+- **Font size:** Use two `select`s (mobile + desktop), base Tailwind classes for mobile and `md:` / `lg:` for desktop; optionally fall back in Liquid to a legacy single key for older saved data.
+- **Locale files:** Mirror labels under the same `t:` paths the schema references; keep breakpoint out of visible copy.
+
+## Do not
+
+- Use invented meta values (e.g. `"all"`, `"typography"`) for breakpoint-specific controls unless the product’s schema spec explicitly defines them.
+- Duplicate breakpoint words in labels when `meta` is present.

package/ts-dist/mocks/init-theme/.cursor/rules/naming-convention.mdc

@@ -0,0 +1,64 @@
+---
+description: Naming convention for Liquid variables, CSS classes, and HTML IDs across all template files.
+alwaysApply: true
+---
+
+# Naming Convention
+
+## 1. Liquid Variables — `snake_case`
+
+All Liquid variables (assigned with `assign`, `capture`, loop variables, etc.) must use `snake_case`.
+
+```liquid
+❌ BAD
+{% assign colorClass = 'text-red' %}
+{% assign color-class = 'text-red' %}
+
+✅ GOOD
+{% assign color_class = 'text-red' %}
+{% assign heading_font_size = 'text-2xl' %}
+{% assign outer_section_classes = 'pt-5 pb-6' %}
+```
+
+---
+
+## 2. CSS Classes — `kebab-case`
+
+All class names (Tailwind utility overrides, custom classes, data attributes used as class hooks) must use `kebab-case`.
+
+```liquid
+❌ BAD
+<div class="colorClass sectionWrapper">
+<div class="color_class section_wrapper">
+
+✅ GOOD
+<div class="color-class section-wrapper">
+<div class="page-max-width no-scrollbar scroll-smooth">
+```
+
+---
+
+## 3. HTML IDs — `camelCase`
+
+All `id` attributes on HTML elements must use `camelCase`.
+
+```liquid
+❌ BAD
+<div id="color_class">
+<div id="color-class">
+
+✅ GOOD
+<div id="colorClass">
+<input id="searchInput">
+<section id="blogPageHero">
+```
+
+---
+
+## Quick Reference
+
+| Context | Convention | Example |
+|---|---|---|
+| Liquid `assign` / `capture` / loop var | `snake_case` | `title_font_scale_mobile` |
+| HTML `class` attribute | `kebab-case` | `blog-card-wrapper` |
+| HTML `id` attribute | `camelCase` | `blogCardWrapper` |

package/ts-dist/mocks/init-theme/.cursor/rules/pages.mdc

@@ -0,0 +1,120 @@
+---
+description: Page JSON template rules — applies to all themes
+globs: ["pages/*.json"]
+---
+
+# Page JSON Rules — b2bizmart Theme
+
+## Structure
+Every page JSON file follows this structure:
+```jsonc
+{
+  "layout": "theme",
+  "sections": {
+    "section-key": {
+      "type": "section-file-name",   // matches filename in sections/ (no .liquid)
+      "settings": {
+        // direct settings for the section
+      },
+      "blocks": {
+        "block-key": {
+          "type": "block-type-name",       // local: bare name; theme: zc_theme__<name>
+          "settings": {
+            // block-level settings
+          },
+          "blocks": {},                    // optional — nested theme block children
+          "block_order": []                // optional — nested child order
+        }
+      },
+      "block_order": ["block-key"]   // controls render order
+    }
+  },
+  "order": ["section-key"]           // controls section render order
+}
+```
+
+---
+
+## Settings Values in Page JSON
+When writing settings values in page JSON, always use the correct type format:
+
+### Select
+```jsonc
+"layout_type": { "display_name": "Left Alignment", "value": "left-alignment" }
+```
+
+### URL
+```jsonc
+"my_url": { "display_name": "Home", "handle": "/home" }
+```
+
+### Image
+```jsonc
+"background_image": { "url": "filename.webp", "enable_customisation": true }
+```
+
+### Menu
+```jsonc
+"footer_menu": { "display_name": "Footer Menu", "handle": "footer-menu" }
+```
+
+### Checkbox
+```jsonc
+"show_banner": false
+```
+
+### Range / Number
+```jsonc
+"overlay_opacity": 50
+```
+
+### Color
+```jsonc
+"overlay_color": "#000000"
+```
+
+### Text
+```jsonc
+"heading": "My Heading Text"
+```
+
+---
+
+## Special Page Settings
+Some pages have reserved settings:
+```jsonc
+// category pages
+"page_type": "category",
+"isCategoryPage": true
+```
+
+---
+
+## Available Page Files
+```
+pages/404.json
+pages/blog.json
+pages/cart.json
+pages/categories.json
+pages/checkout.json
+pages/collection.json
+pages/index.json
+pages/orders.json
+pages/page.json
+pages/payment.json
+pages/product.json
+pages/sitemap.json
+```
+
+---
+
+## Rules
+- `"layout"` is always `"theme"` unless using `"accounts"` or `"sitemap"` layouts
+- `"order"` array controls top-to-bottom section render order — always keep in sync with `"sections"` keys
+- `"block_order"` array controls block render order — always keep in sync with `"blocks"` keys
+- Section `"type"` must exactly match the filename in `sections/` (without `.liquid`)
+- Block `"type"` must be allowed by the section's schema:
+  - **Local block:** bare name defined inline in the section schema `blocks` array
+  - **Theme block:** `zc_theme__<name>` where `blocks/<name>.liquid` exists and the section schema lists `@theme` or that specific type
+- Nested theme blocks may have their own `"blocks"` and `"block_order"` inside a parent block instance
+- ❌ NEVER use standard Shopify `"template"` wrapper objects

package/ts-dist/mocks/init-theme/.cursor/rules/performance.mdc

@@ -0,0 +1,51 @@
+---
+description: Performance standards for theme sections and templates
+globs: **
+alwaysApply: true
+---
+
+# Performance Guidelines
+
+Apply these rules when building or editing any Liquid section/snippet/template.
+
+## Images & Media (LCP / CLS)
+- Prefer `width` and `height` on every `<img>` to prevent layout shift (CLS)
+- Use `loading="eager"` only for above-the-fold/LCP candidates; otherwise `loading="lazy"`
+- Avoid huge source images relative to display size; flag oversized dimensions and prefer appropriately sized assets where possible
+- Always use the platform image object URL (`{{ field.url }}` / `{{ section.settings.image.url }}`) rather than legacy filters like `| img_url`
+- Avoid background images for critical content images; prefer `<img>` so the browser can optimize loading
+- If motion is prominent (auto-playing/looping), provide a way to pause/stop and keep motion subtle
+
+## CSS (render cost / maintainability)
+- Prefer Tailwind utility classes for static styling; keep `{% style %}` for:
+  - dynamic values from settings (e.g. `{{ section.settings.padding_top }}px`)
+  - CSS custom properties / theme variables
+  - stateful/complex selectors scoped to `#section-{{ section.id }}`
+- Scope any `{% style %}` rules to `#section-{{ section.id }}` to avoid global style recalculation and collisions
+- Avoid expensive selectors (deep descendant chains, overly broad `*`, heavy attribute selectors) unless necessary
+- Don’t animate layout properties (`width`, `height`, `top/left`, `margin`); prefer `transform` and `opacity`
+
+## JavaScript (main-thread / TTI)
+- Only load JS when the section actually needs it (don’t include scripts “just in case”)
+- Use `defer` on section scripts; do not block rendering with synchronous scripts
+- Bind events via delegation when possible; avoid adding many per-item listeners in loops
+- Avoid layout thrashing (repeated `getBoundingClientRect` + style writes); batch reads then writes
+- Respect reduced motion: avoid forcing animations when `prefers-reduced-motion` is set
+
+## Liquid / HTML (server + DOM cost)
+- Guard loops with empty states (`{% else %}`) or `size > 0` checks to avoid rendering large empty scaffolds
+- Avoid repeated heavy computations/filters inside loops; pre-assign in a top `{% liquid %}` block when possible
+- Keep DOM shallow: avoid unnecessary wrappers and deeply nested markup
+- Avoid duplicating identical SVG markup many times; prefer a snippet render if reused
+
+## Fonts & Text
+- Avoid defining custom fonts per-section; rely on theme-level font loading
+- Prefer system-safe fallbacks and avoid large icon-font files for small icon sets
+
+## What to report in QA
+- Mark **PERFORMANCE ⚠️ REVIEW** when you see:
+  - above-the-fold images not eager / missing dimensions
+  - oversized images for their rendered size
+  - large `{% style %}` blocks full of static rules that should be Tailwind
+  - non-deferred scripts or unnecessary JS on initial load
+  - excessive DOM nesting or repeated heavy Liquid work in loops