@zohofinance/commerce 1.0.0 → 1.1.0

package/ts-dist/mocks/init-theme/.cursor/skills/page-json-contract.md

@@ -0,0 +1,87 @@
+# SKILL: Page JSON contract
+# Usage in chat: @page-json-contract
+
+How page JSON relates to section and block schemas. Use when running `/assemble-page` or `/validate-page`.
+
+---
+
+## Page JSON shape
+
+```json
+{
+  "layout": "theme",
+  "sections": {
+    "<section_key>": {
+      "type": "<section_filename_without_.liquid>",
+      "settings": { ... },
+      "blocks": { "<block_key>": { "type": "<block_type>", "settings": {} } },
+      "block_order": ["<block_key>", ...]
+    }
+  },
+  "order": ["<section_key_1>", "<section_key_2>", ...]
+}
+```
+
+- **section_key:** arbitrary key (e.g. `hero`, `product_details`). Must be unique in the page.
+- **type:** must exactly match a section file name under `sections/` (e.g. `product-details` for `product-details.liquid`).
+- **blocks:** only present if the section schema declares a `"blocks"` array. Each key in `blocks` is a block instance.
+- **block_order:** array of block keys; every key must exist in `blocks`. Order determines render order.
+- **order:** array of section keys; every key must exist in `sections`. Order determines section order on the page.
+
+---
+
+## Block types — local vs theme
+
+| Model | Page JSON `type` | Schema source |
+|-------|------------------|---------------|
+| **Local block** | bare name, e.g. `"badge"` | Section `{% schema %}` `blocks` entry with inline `settings` |
+| **Theme block** | `zc_theme__<name>`, e.g. `"zc_theme__text"` | `blocks/<name>.liquid` `{% schema %}` |
+
+A section opts into theme blocks in its schema:
+
+```jsonc
+"blocks": [
+  { "type": "@theme" },                              // all theme blocks
+  { "type": "zc_theme__text", "name": "t:blocks.text.name" },  // specific only
+  { "type": "badge", "name": "t:sections....", "settings": [ ... ] }  // local
+]
+```
+
+Only block types declared in the section schema are allowed in page JSON (enforced at render).
+
+Nested theme blocks: a parent block instance in page JSON may have its own `"blocks"` and `"block_order"` for children (up to nesting depth 5).
+
+---
+
+## Settings value formats (inline in page JSON)
+
+| Schema type   | Page JSON value format |
+|---------------|------------------------|
+| text          | string                 |
+| url           | `{ "display_name": "t:...", "handle": "/path" }` |
+| image_picker  | `{ "url": "file.webp", "enable_customisation": true }` |
+| media_picker  | `{ "url": "video.mp4", "is_video": true }` |
+| select        | `{ "display_name": "t:...", "value": "option-value" }` |
+| menu          | `{ "display_name": "t:...", "handle": "menu-handle" }` |
+| checkbox      | true / false            |
+| range/number  | number                  |
+| color         | hex string e.g. "#000000" |
+
+All user-facing strings use `t:` keys. Setting IDs in page JSON must match the schema for that level:
+- Section settings → section `{% schema %}`
+- Local block settings → section `{% schema %}` block entry
+- Theme block settings → `blocks/<name>.liquid` `{% schema %}`
+
+---
+
+## Validation (for /validate-page)
+
+- For each entry in `order`, the key exists in `sections`.
+- For each `sections.<key>.type`, the file `sections/<type>.liquid` exists.
+- For each section that has `blocks` and `block_order`, every entry in `block_order` exists in `blocks`.
+- For each `blocks.<key>.type`:
+  - **Local:** type is declared in the section schema `blocks` array (bare name with inline `settings`).
+  - **Theme (`zc_theme__<name>`):** `blocks/<name>.liquid` exists AND the section schema lists `@theme` or that specific `zc_theme__<name>` entry.
+- Recursively validate nested `blocks` / `block_order` on theme block instances against each parent block file's schema.
+
+Reference this skill when assembling or validating page JSON.

package/ts-dist/mocks/init-theme/.cursor/skills/qa-accessibility.md

@@ -0,0 +1,35 @@
+# SKILL: QA Accessibility
+# Usage in chat: @qa-accessibility
+
+Checklist for auditing section accessibility when running `/qa-section` or reviewing a section manually.
+
+---
+
+## Images
+- Every `<img>` has a non-empty `alt`. Use meaningful description (e.g. product name, CTA context); decorative images may use `alt=""`.
+- Avoid images of text for critical content; if used, `alt` must convey the same information.
+
+## Headings
+- Logical order: do not skip levels (e.g. h1 → h3). Use h1 once per section/page for main title.
+- Headings describe the content that follows.
+
+## Forms and controls
+- Every form control has an associated label: use `<label for="id">` or `aria-label` / `aria-labelledby`.
+- Groups of controls (e.g. variant options, sort options): use `<fieldset>` + `<legend>` or `role="group"` with `aria-labelledby` pointing to a visible label element (e.g. `<div id="...">`).
+- Required fields indicated (e.g. `aria-required="true"` or visible "required" text).
+
+## Focus and keyboard
+- No `outline: none` (or similar) without a visible focus style (e.g. `outline: 2px solid var(--color-primary)` or `ring-2`).
+- Interactive elements (links, buttons, custom controls) are focusable and have a visible focus indicator.
+- Focus order follows visual order where possible.
+
+## Buttons and links
+- Icon-only buttons/links have a descriptive `aria-label` (e.g. "Add to cart", "Close menu", "Previous slide").
+- Links that open in new tab: consider `target="_blank"` + `rel="noopener"` and optionally announce in `aria-label` for screen readers.
+
+## Landmarks
+- Section has a sensible structure; if it’s a main content region, consider `role="region"` and `aria-labelledby` for the section heading where it improves navigation.
+
+---
+
+Use this skill when running the ACCESSIBILITY row of `/qa-section` or when asked to review a section for a11y.

package/ts-dist/mocks/init-theme/.cursor/skills/reference-lookup.md

@@ -0,0 +1,88 @@
+# SKILL: Reference Lookup
+# Save this as a Cursor Notepad named: reference-lookup
+# Usage in chat: @reference-lookup
+
+How to find and use existing theme sections as references when building new sections.
+
+---
+
+## Step 1 — Find the Reference
+Look for an equivalent section within the current theme:
+```
+sections/    ← look for existing sections with similar purpose
+snippets/    ← look for reusable snippets
+```
+
+Match by purpose, not filename. Examples:
+| Building | Look for reference named |
+|----------|------------------------|
+| hero-banner | banner, hero, slider, masthead |
+| category-grid | category, collection-grid, product-listing |
+| featured-products | featured, products, product-grid |
+| testimonials | testimonials, reviews, quotes |
+| footer | footer |
+| header | header |
+
+---
+
+## Step 2 — What to Extract
+Open the reference file and extract ONLY these parts:
+
+### Keep exactly as-is
+- Schema field IDs (e.g. `heading`, `cta_url`, `bg_image`) 
+- Schema field types
+- `{% liquid %}` assign variable names
+- Loop variable names (e.g. `{% for product in products %}`)
+- `{% render %}` snippet calls (these are shared infrastructure)
+- JS web component tag names (e.g. `<product-card>`)
+- Conditional logic patterns
+
+### Adapt (keep structure, update values)
+- Schema labels → update `t:` key path to new section name
+- Schema defaults → update `t:` key path to new section name
+- CSS class names → replace with new Figma-based Tailwind classes
+- HTML structure → replace with new Figma layout
+
+### Discard
+- Inline hardcoded colors from old theme
+- Old theme's specific layout classes
+- Deprecated workarounds or comments marked as fixes
+
+---
+
+## Step 3 — When No Reference Exists
+If no matching section exists in this theme:
+1. Look for the closest partial match (e.g. use a card section as base for a different card layout)
+2. Build schema from scratch using schema.mdc rules
+3. Mark in your build notes: "NEW — no reference, built from schema.mdc"
+
+---
+
+## Quick Reference: Common Section Patterns
+
+### Settings every section should have
+```jsonc
+{ "type": "text", "id": "heading" }
+{ "type": "checkbox", "id": "show_section", "default": true }
+{ "type": "range", "id": "padding_top" }
+{ "type": "range", "id": "padding_bottom" }
+```
+
+### Settings for sections with images
+```jsonc
+{ "type": "image_picker", "id": "section_image", 
+  "default": { "url": "placeholder.webp", "enable_customisation": true } }
+```
+
+### Settings for sections with CTAs
+```jsonc
+{ "type": "text", "id": "cta_text" }
+{ "type": "url", "id": "cta_url",
+  "default": { "display_name": "t:...", "handle": "/" } }
+```
+
+### Settings for sections with menus
+```jsonc
+{ "type": "menu", "id": "section_menu",
+  "default": { "display_name": "t:...", "handle": "" } }
+```

package/ts-dist/mocks/init-theme/.cursor/skills/section-anatomy.md

@@ -0,0 +1,173 @@
+# SKILL: Section Anatomy
+# Save this as a Cursor Notepad named: section-anatomy
+# Usage in chat: @section-anatomy
+
+Every section file must follow this exact anatomy. Use this as the structural checklist.
+
+---
+
+## Complete Section File Structure (top to bottom)
+
+```liquid
+{{-- 1. SCRIPT TAGS (if JS component needed) --}}
+<script src="{{ 'component-name.js' | asset_url }}" defer></script>
+
+{{-- 2. STYLE BLOCK (dynamic CSS scoped to this section) --}}
+{% style %}
+  #section-{{ section.id }} {
+    padding-top: {{ section.settings.padding_top }}px;
+    padding-bottom: {{ section.settings.padding_bottom }}px;
+  }
+{% endstyle %}
+
+{{-- 3. LIQUID ASSIGNS (all settings extracted at top) --}}
+{% liquid
+  assign heading        = section.settings.heading
+  assign sub_heading    = section.settings.sub_heading
+  assign cta_text       = section.settings.cta_text
+  assign cta_url        = section.settings.cta_url
+  assign bg_image       = section.settings.bg_image
+  assign show_section   = section.settings.show_section
+%}
+
+{{-- 4. CONDITIONAL VISIBILITY --}}
+{% if show_section %}
+
+{{-- 5. SECTION WRAPPER --}}
+<section id="section-{{ section.id }}" class="section-name w-full">
+  <div class="max-w-container-theme mx-auto" style="padding-left: var(--section-padding-x, 16px); padding-right: var(--section-padding-x, 16px);">
+
+    {{-- 6. SECTION CONTENT --}}
+    {% if heading != blank %}
+      <h2 class="text-4xl font-bold" style="color: var(--color-heading);">{{ heading | escape }}</h2>
+    {% endif %}
+
+    {{-- 7. LOOPS WITH EMPTY STATE --}}
+    {% if items.size > 0 %}
+      {% for item in items %}
+        {{-- item markup --}}
+      {% endfor %}
+    {% else %}
+      <p class="text-center" style="color: var(--color-heading);">No items found.</p>
+    {% endif %}
+
+  </div>
+</section>
+
+{% endif %}
+
+{{-- 8. SCHEMA (always at the very bottom) --}}
+{% schema %}
+{
+  "name": "t:sections.<name>.name",
+  "tag": "section",
+  "class": "section",
+  "settings": [
+    {
+      "type": "text",
+      "id": "heading",
+      "label": "t:sections.<name>.settings.heading.label",
+      "default": "t:sections.<name>.settings.heading.default"
+    },
+    {
+      "type": "checkbox",
+      "id": "show_section",
+      "label": "t:sections.<name>.settings.show_section.label",
+      "default": true
+    },
+    {
+      "type": "range",
+      "id": "padding_top",
+      "min": 0, "max": 100, "step": 4, "unit": "px", "default": 40,
+      "label": "t:sections.<name>.settings.padding_top.label"
+    },
+    {
+      "type": "range",
+      "id": "padding_bottom",
+      "min": 0, "max": 100, "step": 4, "unit": "px", "default": 40,
+      "label": "t:sections.<name>.settings.padding_bottom.label"
+    }
+  ],
+  "blocks": [],
+  "presets": [
+    { "name": "t:sections.<name>.presets.default.name" }
+  ]
+}
+{% endschema %}
+```
+
+---
+
+## Rules
+- Script tags → TOP of file
+- Style block → after scripts, before assigns
+- All assigns → in one `{% liquid %}` block at top
+- Conditional visibility → wrap entire section if needed
+- Schema → ALWAYS last, never in the middle
+- Padding settings → ALWAYS included in every section
+- Every loop → MUST have empty state
+- Every heading/text → check `!= blank` before rendering
+- **Heading fields → `text` only** (render with `| escape`); **body/description → `richtext`** (render with `| raw`). Never use `richtext` for heading blocks.
+
+---
+
+## Theme block file anatomy (`blocks/<name>.liquid`)
+
+Reusable blocks live in `blocks/`, not `sections/`. Each file has its own schema and optional snippet render.
+
+```liquid
+{% render 'theme-text-block', block: block %}
+
+{% schema %}
+{
+  "name": "t:blocks.text.name",
+  "settings": [ ... ],
+  "blocks": [
+    { "type": "zc_theme__button" }
+  ],
+  "presets": [
+    { "name": "t:blocks.text.presets.default.name", "settings": { ... } }
+  ]
+}
+{% endschema %}
+```
+
+- i18n: `t:blocks.<name>.*` (not `t:sections.*.blocks.*`)
+- `"presets"` required — without it the block won't appear in the editor picker
+- Render children: `{% render_blocks %}` inside the block file (nesting up to depth 5)
+- Scope dynamic CSS to `#theme-block-<name>-{{ block.id }}` (or a snippet equivalent)
+- Access settings: `block.settings.<id>`; output `{{ block.zcommerce_attributes }}` on the wrapper for editor chrome
+
+---
+
+## Section patterns for theme blocks
+
+**Pure theme-block section** — schema lists `@theme` or specific `zc_theme__*` types; body uses `{% render_blocks %}`:
+
+```liquid
+<div class="heading-area">
+  {% render_blocks %}
+</div>
+```
+
+**Mixed section** — local blocks inline, theme blocks delegated:
+
+```liquid
+{% for block in section.blocks %}
+  {% case block.type %}
+    {% when 'badge' %}
+      {%- comment -%} local block markup {%- endcomment -%}
+    {% else %}
+      {% render block %}
+  {% endcase %}
+{% endfor %}
+```
+
+Section schema for mixed:
+
+```jsonc
+"blocks": [
+  { "type": "zc_theme__text", "name": "t:blocks.text.name" },
+  { "type": "badge", "name": "t:sections.my_section.blocks.badge.name", "settings": [ ... ] }
+]
+```