diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..c56456a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,70 @@ +name: Bug report +description: Report a reproducible Spark theme issue. +title: "[Bug]: " +labels: + - bug +body: + - type: markdown + attributes: + value: | + Thanks for reporting a Spark issue. Do not include API keys, customer data, merchant credentials, or exploit details. + - type: input + id: version + attributes: + label: Spark version or commit + description: Use the README version, Git tag, or commit SHA. + placeholder: "1.1.1 or add24e9" + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What should have happened? + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + description: What happened instead? + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + description: Include the smallest safe reproduction you can share. + placeholder: | + 1. Clone Spark at ... + 2. Configure ... + 3. Run ... + 4. See ... + validations: + required: true + - type: dropdown + id: surface + attributes: + label: Affected surface + options: + - Theme Settings + - Homepage section partial + - Product detail page + - Cart or side cart + - Web Component + - App hook + - CSS build or compatibility + - Documentation + - Other + validations: + required: true + - type: textarea + id: checks + attributes: + label: Verification + description: Paste relevant local command output. + placeholder: | + python3 -m unittest discover -s tests + python3 scripts/sass-compat.py --check assets/main.css + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..40cfacf --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Store-specific support + url: https://github.com/NextCommerceCo/spark/blob/main/CONTRIBUTING.md#public-issues-and-support + about: Use your normal Next Commerce support channel for merchant-specific store issues. + - name: Security reports + url: https://github.com/NextCommerceCo/spark/security/advisories/new + about: Report vulnerabilities privately. Do not open public issues with exploit details or secrets. diff --git a/.github/ISSUE_TEMPLATE/dx_feedback.yml b/.github/ISSUE_TEMPLATE/dx_feedback.yml new file mode 100644 index 0000000..0af738b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/dx_feedback.yml @@ -0,0 +1,49 @@ +name: Developer experience feedback +description: Share friction from installing, extending, debugging, or contributing to Spark. +title: "[DX]: " +labels: + - dx +body: + - type: markdown + attributes: + value: | + Use this for onboarding friction, unclear docs, confusing errors, missing examples, or extension pain. Do not include secrets or merchant-specific private data. + - type: dropdown + id: journey_stage + attributes: + label: Journey stage + options: + - Discover + - Install + - Local verification + - Store install + - Extending the theme + - Debugging + - Upgrade or release + - Contributing + validations: + required: true + - type: textarea + id: attempted + attributes: + label: What were you trying to do? + description: Describe your goal and the docs, commands, or files you used. + validations: + required: true + - type: textarea + id: friction + attributes: + label: Where did you lose time? + description: Include confusing copy, missing next steps, unclear errors, or decisions the docs forced you to guess. + validations: + required: true + - type: textarea + id: better + attributes: + label: What would have helped? + description: A command, example, screenshot, doc page, warning, or default behavior. + - type: input + id: time_lost + attributes: + label: Time lost + placeholder: "e.g., about 10 minutes" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..16fd501 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,62 @@ +name: CI + +on: + pull_request: + push: + branches: + - main + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + verify: + name: Verify theme tooling + runs-on: ubuntu-latest + + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + + - name: Set up Node + uses: actions/setup-node@v4 + with: + node-version: "22" + + - name: Install CI dependencies + run: | + python -m pip install --upgrade pip + python -m pip install pyyaml + + - name: Validate GitHub YAML + run: | + python - <<'PY' + from pathlib import Path + import yaml + + for path in sorted(Path(".github").glob("**/*.yml")): + with path.open() as handle: + yaml.safe_load(handle) + print(f"OK: {path}") + PY + + - name: Run tests + run: python -m unittest discover -s tests + + - name: Run JavaScript module tests + run: | + for test_file in tests/js/*.test.js; do + node "$test_file" + done + + - name: Check committed CSS compatibility + run: python scripts/sass-compat.py --check assets/main.css diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..3dc113a --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,26 @@ +# Changelog + +All notable public Spark changes should be recorded here. + +Spark follows human-readable release notes rather than a strict package-manager version contract. The current public version is shown in [README.md](README.md). When releasing a new version, update the README version, add a dated changelog section, and publish a Git tag or GitHub release when the repo is ready for external consumers to pin versions. + +## 1.1.2 - Unreleased + +- Clarified the first-run path for local inspection versus installing Spark on a real Next Commerce store. +- Added contribution guidance, issue templates, CI checks, and an extension guide for theme developers. + +## 1.1.1 - 2026-06-17 + +- Added metadata-driven membership pricing presentation for product cards, PDP surfaces, and sticky add-to-cart pricing. +- Refreshed public-facing docs around components, app hooks, and public readiness. + +## 1.1.0 - 2026-04-28 + +- Expanded homepage section partials and Theme Settings coverage. +- Documented the Figma section library path, performance load order, cart events, PDP variant state, and theme settings partials. +- Committed compiled `assets/main.css` so Spark can be installed without a local Tailwind build. + +## 1.0.0 - 2026-03-20 + +- Initial public Spark starter theme for Next Commerce. +- Introduced Tailwind CSS v4, vanilla JavaScript, Web Components, committed storefront templates, and zero jQuery or Bootstrap dependency. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f58d3fe --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,62 @@ +# Contributing To Spark + +Spark is a public starter theme for Next Commerce storefronts. Contributions should keep the theme easy to inspect, install, customize, and safely extend. + +## Before You Start + +- Read [README.md](README.md) for the current setup and verification commands. +- Read [DESIGN.md](DESIGN.md) before changing storefront UI. +- Read [docs/extending-spark.md](docs/extending-spark.md) before adding settings, partials, app hooks, or Web Components. +- Keep `config.yml`, API keys, store domains, merchant data, and local tool state out of commits. + +## Local Verification + +Run the checks that match your change: + +```bash +python3 -m unittest discover -s tests +python3 scripts/sass-compat.py --check assets/main.css +``` + +The standard local checks do not need extra Python packages. CI also validates GitHub workflow and issue-template YAML with PyYAML; install `pyyaml` first if you run that optional check locally. + +If you change `css/input.css`, rebuild and check the generated CSS: + +```bash +make css-check +``` + +If you do not already have the Tailwind standalone binary, install it first: + +```bash +make install-tailwind +``` + +When a CSS source change is ready to commit, run: + +```bash +make release +``` + +That rebuilds and stages `assets/main.css`. Commit the source CSS and generated CSS together. + +## Pull Request Checklist + +- Explain the user-facing or theme-developer impact. +- Name the relevant [PLAN.md](PLAN.md) workstream when it applies; otherwise explain the public DX or user impact in plain language. +- Include screenshots for storefront UI changes at desktop and mobile widths. +- Include the exact commands you ran and their results. +- Update docs when behavior, settings, events, public APIs, or release steps change. +- Keep pull requests focused. Separate docs polish, platform behavior, and storefront UI when they can land independently. + +## Public Issues And Support + +Use the GitHub issue templates for reproducible bugs and developer-experience feedback. Include reproduction steps, expected behavior, actual behavior, and the Spark version or commit. If issue creation is unavailable for your account or the topic is store-specific, use your normal Next Commerce support channel. + +For security reports, do not open a public issue. Follow [SECURITY.md](SECURITY.md). + +For store-specific support, use your normal Next Commerce support channel and never post API keys, customer data, merchant configuration, or exploit details publicly. + +## Branching + +NextCommerceCo repositories use branch and pull request flow. Do not push directly to `main`. Keep generated artifacts such as `assets/main.css` in the same pull request as the source change that produced them. diff --git a/PLAN.md b/PLAN.md index 1a33f87..45ddd96 100644 --- a/PLAN.md +++ b/PLAN.md @@ -108,7 +108,7 @@ Spark should be ready if NEXT adds platform-level theme sections, but current Sp The public repository should stay easy for theme developers to understand, audit, and extend. - Keep `README.md`, `CLAUDE.md`, `PLAN.md`, and `docs/` accurate as Spark evolves. -- Add an "Extending Spark" guide for settings, partials, app hooks, and Web Components. +- Keep the "Extending Spark" guide current as settings, partials, app hooks, and Web Components evolve. - Keep Web Component events, attributes, slots, and public APIs documented in `docs/cart-events.md`, `docs/cart-rewards.md`, `docs/cart-drawer-architecture.md`, and future extension docs. - Add a DTL pattern catalog for Spark-specific gotchas. - Decide the marketplace/self-serve release package shape. diff --git a/README.md b/README.md index 534b24e..26dd92a 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,26 @@ A modern starter theme for Next Commerce. Tailwind CSS v4, vanilla JS + Web Comp ## Quick Start -The compiled `assets/main.css` is committed to the repo, so NEXT developers can install Spark on a store without a local Tailwind toolchain. Clone the repo, point `ntk` at a store you control, and push. +The compiled `assets/main.css` is committed to the repo, so NEXT developers can inspect or install Spark without a local Tailwind toolchain. Choose the path that matches what you have available. -1. Install ntk and configure your store: +### Inspect Spark Locally + +Use this path when you want to evaluate the theme structure, docs, and generated CSS before connecting a store. + +```bash +git clone https://github.com/NextCommerceCo/spark.git +cd spark +python3 -m unittest discover -s tests +python3 scripts/sass-compat.py --check assets/main.css +``` + +Expected time: under 2 minutes after clone on a typical laptop. This verifies the committed CSS artifact and local tooling tests. It does not render a live storefront because Spark templates run inside the Next Commerce theme runtime. + +### Install On A Store + +Use this path when you have a Next Commerce store, API key, and theme id. + +1. Install `ntk` and configure your store: ```bash pip install next-theme-kit ntk init @@ -28,6 +45,8 @@ The compiled `assets/main.css` is committed to the repo, so NEXT developers can ntk push ``` +Expected time: 5-10 minutes if you already have store credentials. If `ntk` cannot find credentials, create `config.yml` with `ntk init`, copy `config.example.yml`, or pass credentials through the CLI options shown by `ntk --help`. + For day-to-day development (editing CSS sources), set up Tailwind locally: ```bash @@ -67,8 +86,10 @@ Known risky generated CSS includes `@supports`, `@property`, `@layer`, `oklch()` Avoid dynamic Tailwind class construction in templates. Tailwind scans source files at build time, so classes like `bg-{{ settings.primary_color }}` are never emitted. Use CSS custom properties (`bg-[var(--primary-color)]`) or static conditional classes instead. -Troubleshooting quick read: +## Troubleshooting +- Credential errors from `ntk`: confirm `config.yml` has the API key, store domain, and theme id for a store you control. +- Python runtime warnings before `ntk` output: retry from a current Python virtual environment. These warnings usually come from local Python packaging, not Spark. - Local Tailwind/build failure: `make css` fails before `assets/main.css` is written. Fix `css/input.css`, missing Tailwind binary, or local command setup. - Platform Sass/compiler failure: local build passes but upload/storefront errors mention CSS parsing. Run `make css-check` and inspect any unsupported construct it reports. - Missing uploaded compiled CSS: templates changed but styling did not. Rebuild with `make css-check`, then push `assets/main.css` explicitly. @@ -129,6 +150,8 @@ Tracked theme documentation starts at [docs/README.md](docs/README.md). Current See [docs/theme-settings-partials.md](docs/theme-settings-partials.md) for the design-team catalog of Theme Settings partials and homepage section partials, [docs/figma-section-library-plan.md](docs/figma-section-library-plan.md) for the Spark Figma section library plan, [docs/performance-load-order.md](docs/performance-load-order.md) for the critical-path loading convention, [docs/pdp-customization.md](docs/pdp-customization.md) for the PDP redesign preservation checklist and QA runbook, [docs/pdp-variant-state.md](docs/pdp-variant-state.md) for the PDP variant state Interface, [docs/cart-events.md](docs/cart-events.md) for the cart event Interface, [docs/cart-rewards.md](docs/cart-rewards.md) for side-cart rewards and upsell rules, [docs/cart-drawer-architecture.md](docs/cart-drawer-architecture.md) for the drawer Module split, [docs/intro-bootstrap-comparison.md](docs/intro-bootstrap-comparison.md) for the Intro Bootstrap comparison, [docs/design-block-authoring.md](docs/design-block-authoring.md) for design-block authoring guidance, [docs/terminology.md](docs/terminology.md) for NEXT-native naming guardrails, and [docs/sections-architecture-proposal.md](docs/sections-architecture-proposal.md) for the future theme sections platform proposal. +Start with [docs/extending-spark.md](docs/extending-spark.md) when adding Theme Settings, homepage section partials, app hooks, Web Components, or public storefront behavior. + ## Design System All visual decisions are documented in [DESIGN.md](DESIGN.md) — typography, colors, spacing, motion, interaction states, accessibility, and anti-slop rules. Read it before making any UI change. @@ -137,7 +160,7 @@ All visual decisions are documented in [DESIGN.md](DESIGN.md) — typography, co The `.gitignore` file is intentionally committed. It documents local files that must stay out of the public repository, including store-specific `config.yml`, downloaded Tailwind binaries, tool session state, OS files, and editor settings. -See [SECURITY.md](SECURITY.md) for private vulnerability reporting and secrets-handling guidance. +See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflow, [CHANGELOG.md](CHANGELOG.md) for release notes, and [SECURITY.md](SECURITY.md) for private vulnerability reporting and secrets-handling guidance. ## License diff --git a/docs/README.md b/docs/README.md index ec72e3e..b19058f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,7 @@ This directory contains Spark's theme-developer, design-team, and architecture d | Doc | Audience | Purpose | | --- | --- | --- | +| [extending-spark.md](extending-spark.md) | Theme developers, app developers | Supported extension surfaces for settings, partials, app hooks, events, and Web Components. | | [theme-settings-partials.md](theme-settings-partials.md) | Designers, theme developers | Catalog of Theme Settings-backed partials and template surfaces. | | [figma-section-library-plan.md](figma-section-library-plan.md) | Design team, theme developers | Plan for mapping Figma section components to Spark section authoring units. | | [section-specs/](section-specs/) | Design team, theme developers | Per-section specs for the current homepage section partials. | diff --git a/docs/extending-spark.md b/docs/extending-spark.md new file mode 100644 index 0000000..7835845 --- /dev/null +++ b/docs/extending-spark.md @@ -0,0 +1,97 @@ +# Extending Spark + +Spark is meant to be extended without forking the whole theme. This guide points to the supported extension surfaces and the files to update when you add one. + +## Choose The Right Extension Surface + +| Goal | Prefer | Start Here | +| --- | --- | --- | +| Add or change a homepage design block | Homepage section partial plus Theme Settings | `docs/design-block-authoring.md` | +| Add merchant-configurable theme behavior | `configs/settings_schema.json` and `configs/settings_data.json` | `docs/theme-settings-partials.md` | +| Integrate an app into storefront markup | `{% app_hook %}` slots | `docs/terminology.md`, `docs/performance-load-order.md` | +| Coordinate cart UI behavior | DOM events through `SparkEvents` | `docs/cart-events.md` | +| Change PDP variant picker UI | Real controls named `attr_*` plus `SparkVariantState` | `docs/pdp-variant-state.md`, `docs/pdp-customization.md` | +| Add custom client-side behavior | Focused vanilla JS module or Web Component | Existing files in `assets/js/` | +| Change load order or head assets | Template blocks in `layouts/base.html` | `docs/performance-load-order.md` | + +## Theme Settings Extensions + +Theme Settings are global today and exposed to templates as `settings.*`. + +When adding a setting-backed surface: + +1. Add the setting to `configs/settings_schema.json`. +2. Add a default to `configs/settings_data.json`. +3. Use a stable prefix for related settings. For example, the featured products section keeps its toggle, content, and style controls under `show_featured_products` and `featured_products_*`; see [configs/settings_schema.json](../configs/settings_schema.json) and [partials/section_featured_products.html](../partials/section_featured_products.html). +4. Render the setting from a focused partial or template surface. +5. Update `docs/theme-settings-partials.md`. +6. Run the standard local checks. If your branch adds a schema validation script, add it to [CONTRIBUTING.md](../CONTRIBUTING.md) and CI before referencing it here. + +Keep future theme sections in mind. Settings that belong to one repeated section should be easy to move from `settings.foo` to future `section.settings.foo`. + +## Homepage Section Partials + +Homepage section partials are the current Spark design-block unit. They live in `partials/section_*.html` and are included from `templates/index.html` in a fixed order. + +Each public section should have: + +- A `show_*` toggle. +- Clear empty states for missing products, categories, images, links, or headings. +- Mobile-safe layout and copy behavior. +- A row in `docs/theme-settings-partials.md`. +- A spec under `docs/section-specs/` when the section is part of the maintained design library. + +Use shared helpers where possible: + +- `partials/section_heading.html` +- `partials/product_grid.html` +- `partials/cta_button.html` + +## App Hooks + +Spark exposes app integration points with `{% app_hook %}`. Apps should target those slots instead of editing theme files or reaching into private Web Component internals. + +Current hook examples live in product cards, PDP reviews, collection feeds, product detail surfaces, and global tracking points. Search for `{% app_hook %}` before adding a new hook. + +When adding a hook: + +1. Choose a stable, descriptive name. +2. Put the hook as close as possible to the DOM it extends. +3. Document the intended payload or surrounding markup contract. +4. Avoid names tied to one temporary app unless the hook is intentionally app-specific. + +## Cart And PDP Events + +Use events for behavior that crosses modules. + +Cart events are documented in `docs/cart-events.md`. Theme and app code should listen for `spark:cart:updated`, `spark:cart:added`, and `spark:cart:toggle` rather than mutating drawer internals. + +PDP selected variant behavior is documented in `docs/pdp-variant-state.md`. Custom picker designs should update real form controls named `attr_*` and listen for `spark:variant:changed` when they need to adapt gallery, price, or add-to-cart behavior. + +## JavaScript Modules And Web Components + +Spark JavaScript is vanilla, browser-loaded, and intentionally small. There is no bundler. + +When adding client-side code: + +- Keep modules focused and expose only the smallest useful public API on `window`. +- Prefer progressive enhancement. The page should still have useful server-rendered markup. +- Keep JS asset files ASCII-only; see [CLAUDE.md](../CLAUDE.md#critical-js-asset-files). The platform processes JS through DTL, so `{%`, `{{`, Unicode punctuation, and non-ASCII symbols can be parsed as template syntax or trigger CDN 500s. +- Add tests when logic can be isolated without a full storefront runtime. + +## CSS And Generated Artifacts + +Author CSS in `css/input.css`. The storefront consumes `assets/main.css`. + +Before handoff: + +```bash +make css-check +python3 -m unittest discover -s tests +``` + +If you changed CSS sources, run `make release` and commit `assets/main.css` with the source change. + +## Release Notes + +Public-facing behavior changes should update [CHANGELOG.md](../CHANGELOG.md). Mention new settings, hooks, events, migration steps, and compatibility notes. A theme developer should be able to skim the changelog and understand whether their derived theme needs action.