aem-eds-kit 0.4.9 → 0.4.16

package/CHANGELOG.md

@@ -6,7 +6,78 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-## [0.4.9] - 2026-10-08
+## [0.4.16] - 2026-10-08
+
+### Changed
+- **`eds template new` is now authoring-aware.** It detects the model from
+  `fstab.yaml` / project markers (or `--authoring da|gdrive|sharepoint|ue`) and
+  routes the generated page: **DA** push (existing), an **importable doc** for
+  **Google Docs / SharePoint**, and for **Universal Editor** it registers the
+  seeded blocks in `component-filters.json` (so authors can add them) and points
+  to the AEM editable template. Completes the per-model template paths shown as
+  an infographic on the docs page.
+
+### Added
+- **`eds template new <name>`** - generate EDS page **initial content** (the EDS
+  analog of an AEM template): a document of sections + chosen blocks + a metadata
+  block. Writes `templates/<name>.html` locally and, with `--push`, pushes it to
+  **DA (da.live)** via the source API (org/site from `.edsrc.json` or flags;
+  `DA_TOKEN` for protected projects). `--path`, `--title`, `--description`,
+  `--blocks`, `--area`. Also in the menu. (UE/crosswalk templates come next.)
+- Docs: a **"From zero to a published page"** step-by-step command path.
+
+## [0.4.14] - 2026-10-08
+
+### Added
+- **`eds schema block <name>` (JSON-LD)** - inject a schema.org structured-data
+  builder into a block's `decorate()`. Types: Article, FAQPage, BreadcrumbList,
+  Product, Organization, LocalBusiness, Event, VideoObject, Recipe, HowTo.
+  Idempotent, reads the block content via a `root` alias, appends a
+  `<script type="application/ld+json">` to the head. `--type`, interactive picker.
+- **`eds scaffold helpers`** - write `scripts/utils.js`, picking the helpers you
+  want in an interactive checkbox (dependencies pulled in automatically) or by
+  name: `toCamelCase`, `getPagePath` / `getLanguageRootPath`, `getSiteArea`
+  (top-level area, e.g. blog), `getEnvironment`, `getContentTopic`, `isUEEdit` /
+  `isUEPreview` / `isUE`, `getMetadata`. Also in the `eds scaffold` picker.
+
+## [0.4.13] - 2026-10-08
+
+### Added
+- **Model partials & helpers** - a library of reusable Universal Editor field
+  groups (heading, image, link, cta, cta-group, classes, eyebrow, richtext,
+  embed, teaser, card) built from typed field builders (correct `valueType` per
+  component), plus **`eds model add <block> [partials...]`** to compose them into
+  a block's `_<block>.json` (added by name, never duplicated). The from-design /
+  migrate prompt now lists the catalog so the agent reuses the standard groups
+  instead of inventing fields. Also in the menu.
+
+### Added
+- **Framer** as a design source for `block from-design` (alongside Figma, Google
+  Stitch, Canva and Sketch) - the agent reads the project through its Framer MCP
+  connection. Also added a copy-paste **AI-agent setup prompt** to the landing +
+  README (checks Node 20+, installs the CLI, verifies).
+
+### Changed
+- Landing version pill shows `v0.4` (minor) instead of chasing every patch.
+
+### Added
+- **`eds track block <name>`** - instrument a block's `decorate()` with dataLayer
+  tracking on demand: delegated `block_click` (links/buttons, label from
+  `data-track` or text) and `form_submit`, pushed via `trackEvent` from
+  `scripts/analytics.js`. Adds the import and injects at the top of decorate,
+  idempotent, keeps the real parameter name. `--no-click` / `--no-submit`. Also
+  offered right after `block from-design` and `migrate component`, and in the menu.
+
+## [0.4.10] - 2026-10-08
+
+### Changed
+- **`eds integrate gtm`** now emits a proper module instead of the inline IIFE:
+  `scripts/analytics.js` (exports `trackEvent` / `loadGTM`, **initialises the
+  dataLayer**, reads the id from `gtm-id` metadata with a configured fallback,
+  idempotent, `Date.now()`, no dead `<noscript>` iframe) and `scripts/page-meta.js`
+  (default-exported `pageMetaPush`). `delayed.js` imports both and pushes page
+  metadata before GTM initialises. Fixes the "dataLayer is undefined" crash of
+  the old snippet.
 
 ### Added
 - `eds migrate component` now pulls the component's **clientlib CSS** off disk
@@ -180,7 +251,14 @@ harness, gradient ANSI logo. Not published (superseded by 0.3.0).
 Initial CLI scaffold: `block create`, `block from-figma`, `block list`,
 `figma setup`, `doctor`, `preview`, `publish`. Not published.
 
-[Unreleased]: https://github.com/piotrgodycki/aem-eds-kit/compare/v0.4.9...HEAD
+[Unreleased]: https://github.com/piotrgodycki/aem-eds-kit/compare/v0.4.16...HEAD
+[0.4.16]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.16
+[0.4.15]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.15
+[0.4.14]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.14
+[0.4.13]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.13
+[0.4.12]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.12
+[0.4.11]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.11
+[0.4.10]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.10
 [0.4.9]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.9
 [0.4.8]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.8
 [0.4.7]: https://github.com/piotrgodycki/aem-eds-kit/releases/tag/v0.4.7

package/README.md

@@ -10,7 +10,7 @@
 
 **Turn a design into an EDS block** - JS, CSS and a Universal Editor model - without leaving your terminal.
 
-`aem-eds-kit` gives you the `eds` command. Paste a design link - Figma, Google Stitch, Canva or Sketch - and it hands the design to the AI agent you already use (Claude Code, Cursor or Codex); the agent reads it through MCP and writes production-ready code straight into your repo. It also scaffolds blocks, previews them in your browser, and keeps your project healthy with a few quick audits.
+`aem-eds-kit` gives you the `eds` command. Paste a design link - Figma, Google Stitch, Canva, Sketch or Framer - and it hands the design to the AI agent you already use (Claude Code, Cursor or Codex); the agent reads it through MCP and writes production-ready code straight into your repo. It also scaffolds blocks, previews them in your browser, and keeps your project healthy with a few quick audits.
 
 It lives next to `@adobe/aem-cli` (your local dev server) and handles everything around it.
 
@@ -20,6 +20,32 @@ It lives next to `@adobe/aem-cli` (your local dev server) and handles everything
 npm install -g aem-eds-kit
 ```
 
+<details>
+<summary><strong>Or let your AI agent install it</strong> (copy-paste prompt)</summary>
+
+```text
+Goal:
+Ensure Node.js v20 or newer is installed, then install the aem-eds-kit CLI and verify it.
+
+Check first: run `node --version`. If the major version is 20 or higher, do not install or modify Node.js.
+If Node.js is missing or older than v20, install an official Node.js release (major version 20 or higher).
+
+Install policy: use an existing package manager only if it is already installed. Do not install Homebrew,
+winget, Chocolatey, Scoop, nvm, fnm, or another package manager just for this task.
+- macOS: Homebrew if already installed, otherwise the official Node.js `.pkg` installer.
+- Windows: winget if already installed, otherwise the official Node.js `.msi` installer.
+- Linux: the system package manager if it can install v20+, otherwise NodeSource (Debian/Ubuntu, RHEL/Fedora)
+  or the official Node.js standalone Linux binary. Downloads: https://nodejs.org/download/release/latest/
+
+Verify Node: run `node --version` again; only continue if the major version is 20 or higher.
+Install the CLI: run `npm install -g aem-eds-kit`. Verify: run `eds --version`.
+
+Final step: from inside an EDS project (a folder with fstab.yaml, head.html, or scripts/scripts.js), run `eds`
+for the interactive menu, or `eds init` to set up a freshly cloned Adobe EDS boilerplate.
+```
+
+</details>
+
 Node.js 20 or newer. That's all the setup there is - `eds` now works in **any folder**. Step into your EDS project (anywhere with a `fstab.yaml`) and the CLI finds the project root for you:
 
 ```bash
@@ -32,7 +58,7 @@ eds block from-design "<figma-url>" --name hero
 
 ## Interactive mode
 
-Run `eds` with no command and it opens an **interactive menu** that walks you through every feature (generate a block from a design, scaffold, create a block, add an integration, preview, Admin API, audits, Figma setup). Most commands are also interactive on their own when you omit arguments - e.g. `eds block from-design` (wizard), `eds scaffold`, `eds integrate`, `eds preview`. Flags and subcommands still work for CI / power users.
+Run `eds` with no command and it opens an **interactive menu** that walks you through every feature (set up the project, generate a block from a design, migrate a classic AEM component, scaffold, create a block, add an integration, preview, Admin API, audits, Figma setup). Most commands are also interactive on their own when you omit arguments - e.g. `eds init`, `eds block from-design` (wizard), `eds migrate component`, `eds scaffold`, `eds integrate`, `eds preview`. Flags and subcommands still work for CI / power users.
 
 A full A-Z reference of every command lives on the docs page: **https://piotrgodycki.github.io/aem-eds-kit/docs.html**
 
@@ -61,6 +87,41 @@ eds integrate
 eds doctor
 ```
 
+## From zero to a published page
+
+The full path, command by command. This example targets **DA (da.live)** authoring.
+
+```bash
+# 1. Install the CLI
+npm i -g aem-eds-kit
+
+# 2. Set up the project (pick DA, enter org + site). Writes fstab + CI + naming.
+eds init --authoring da --org my-org --site my-site
+
+# 3. Scaffold the Universal Editor config + helper functions
+eds scaffold ue
+eds scaffold helpers
+
+# 4. Build blocks - from a design, from scratch, or migrated from classic AEM
+eds block from-design            # paste a Figma/Stitch/Canva/Sketch/Framer link
+# eds block create hero
+# eds migrate component ./components/hero
+
+# 5. Enrich a block (optional)
+eds model add hero teaser        # add reusable field-group partials
+eds schema block hero --type Article   # JSON-LD structured data
+eds track block hero             # dataLayer click + form-submit tracking
+
+# 6. Generate the page (initial content) and push it to DA
+eds template new homepage --blocks hero,cards --push --org my-org --site my-site
+
+# 7. Preview, then publish
+eds preview /templates/homepage
+eds publish /templates/homepage
+```
+
+Every step is also interactive when you omit the flags - run `eds` for the menu.
+
 ## Commands
 
 ### `eds init`
@@ -81,6 +142,25 @@ eds init --name my-site --authoring da --org my-org --site my-site --yes
 | `--no-ci` | Skip the GitHub Actions workflow |
 | `--yes` | Skip prompts; apply with flags/defaults |
 
+### `eds template new <name>`
+
+Generate EDS page **initial content** - the EDS analog of an AEM template: a document of sections + chosen blocks + a metadata block. It always writes `templates/<name>.html`, then **routes by your authoring model** (detected from `fstab.yaml` / project markers, or `--authoring`): **DA** → push to da.live (`--push`, org/site from `.edsrc.json`/flags, `DA_TOKEN` for protected projects); **Google Docs / SharePoint** → importable doc + the external steps; **Universal Editor** → registers the seeded blocks in `component-filters.json` and points you to the AEM editable template. Interactive when flags are omitted.
+
+```bash
+eds template new homepage                         # interactive (blocks, DA push)
+eds template new homepage --blocks hero,cards --push --org my-org --site my-site
+```
+
+| Flag | Description |
+|---|---|
+| `--blocks <list>` | Comma-separated block ids to seed |
+| `--title` / `--description` / `--area` | Page title, description, metadata label |
+| `--path <path>` | Content path (default `/templates/<name>`) |
+| `--authoring <model>` | Force `da` \| `gdrive` \| `sharepoint` \| `ue` (else detected) |
+| `--push` | Push to DA (da.live) |
+| `--org` / `--site` | DA org / site (else from `.edsrc.json`) |
+| `--yes` | Skip prompts |
+
 ### `eds migrate component [dir]`
 
 Start migrating a **classic AEM component** to EDS. Phase 1 is deterministic (no agent, no network): it parses the component's Touch UI dialog (`_cq_dialog/.content.xml`) and maps its Granite/Coral fields onto the **17 Universal Editor field types** - selects keep their options, multifields become repeatable containers, tabs are preserved - then writes `blocks/<name>/` with a UE model (`_<name>.json`), a `decorate()` stub (port the HTL logic), and a scoped CSS file to fill from the component's clientlib or its rendered page.
@@ -94,6 +174,36 @@ eds migrate component ./components/hero --name hero --clientlib ./ui.apps/.../he
 
 Dialogs map cleanly because Granite's `sling:resourceType` set is finite. The most faithful CSS actually comes from the **rendered page** (resolves LESS vars + cascade) - that capture lands in a later phase; for now the clientlib source gets you most of the way.
 
+### `eds track block <name>`
+
+Instrument a block's `decorate()` with **dataLayer** tracking on demand: a delegated `block_click` (links/buttons, label from `data-track` or the element text) and `form_submit`, both pushed through `trackEvent` from `scripts/analytics.js` (created by `eds integrate gtm`). It adds the import, injects at the top of `decorate()`, is idempotent, and keeps the real parameter name. You're also offered it right after `block from-design` and `migrate component`.
+
+```bash
+eds track block hero
+eds track block hero --no-submit        # clicks only
+```
+
+### `eds model add <block> [partials...]`
+
+Compose **reusable field groups (partials)** into a block's Universal Editor model (`_<block>.json`) instead of hand-writing fields. Fields are added **by name**, so re-running never duplicates. Partials are built from typed field helpers (each sets the right `valueType`), and the same catalog is referenced in the `from-design` / `migrate` prompt so the agent reuses the standard groups.
+
+```bash
+eds model add hero teaser              # image + eyebrow + title + text + cta
+eds model add cards card cta-group     # pick several
+eds model add hero                     # interactive checkbox picker
+```
+
+Built-in partials: `heading`, `eyebrow`, `image`, `richtext`, `link`, `cta`, `cta-group`, `classes` (section styles), `embed`, `teaser`, `card`.
+
+### `eds schema block <name>`
+
+Inject a **JSON-LD (schema.org) structured-data** builder into a block's `decorate()` for SEO / rich results. Pick a type - `Article`, `FAQPage`, `BreadcrumbList`, `Product`, `Organization`, `LocalBusiness`, `Event`, `VideoObject`, `Recipe`, `HowTo` - and it appends a `<script type="application/ld+json">` to the head, built from the block's content (aliased to `root`, so it's independent of the parameter name). Idempotent; some fields are heuristic or `TODO`, so review and validate with Google's Rich Results test.
+
+```bash
+eds schema block faq --type FAQPage
+eds schema block article              # interactive type picker
+```
+
 ### `eds block create <name>`
 
 Scaffolds `blocks/<name>/` with `<name>.js`, `<name>.css`, **and a Universal Editor model `_<name>.json` by default** - so the block is authorable in UE the moment it's created. Validates kebab-case naming and checks for collisions.
@@ -107,7 +217,7 @@ The generated `_<name>.json` uses the EDS block-plugin (xwalk) format (`definiti
 
 ### `eds block from-design [design-url]`
 
-Translates a design - **Figma, Google Stitch, Canva or Sketch** - into an EDS block. Run with **no URL** for a step-by-step wizard (design source, name, link, content source, UE model, screenshot, run mode). It builds a prompt with EDS conventions + your project's design tokens and hands it to your AI agent (Claude Code, Cursor, or Codex). *(This was `from-figma` before it went design-agnostic; Figma is the most battle-tested source and stays pixel-perfect.)*
+Translates a design - **Figma, Google Stitch, Canva, Sketch or Framer** - into an EDS block. Run with **no URL** for a step-by-step wizard (design source, name, link, content source, UE model, screenshot, run mode). It builds a prompt with EDS conventions + your project's design tokens and hands it to your AI agent (Claude Code, Cursor, or Codex). *(This was `from-figma` before it went design-agnostic; Figma is the most battle-tested source and stays pixel-perfect.)*
 
 The agent reads the design through its MCP connection (for Figma: `get_design_context`, `get_variable_defs`, `get_screenshot`), generates pixel-perfect code (JS + CSS) **and its Universal Editor model** by default, uses lightweight **placeholders** for not-yet-authored content (so the block is visible before Universal Editor takes over), then self-verifies. You see a **live, colour-coded log** with per-phase timings, and on success the **live preview starts automatically**.
 
@@ -168,6 +278,14 @@ Scaffold Universal Editor components deterministically (no agent). `eds scaffold
 ```bash
 eds scaffold ue
 eds scaffold blocks            # all, or: eds scaffold blocks hero cards
+eds scaffold helpers           # scripts/utils.js with common EDS helpers
+```
+
+`eds scaffold helpers` writes `scripts/utils.js` - **tick the helpers you want** in an interactive checkbox (dependencies are pulled in automatically), or pass names. Available: `toCamelCase`, `getPagePath` / `getLanguageRootPath`, `getSiteArea` (top-level area like `blog`), `getEnvironment`, `getContentTopic`, `isUEEdit` / `isUEPreview` / `isUE`, and `getMetadata`.
+
+```bash
+eds scaffold helpers                    # interactive picker
+eds scaffold helpers getSiteArea getEnvironment
 ```
 
 ### `eds scaffold ci`
@@ -180,7 +298,7 @@ eds scaffold ci
 
 ### `eds integrate [type]`
 
-Add a third-party service to `scripts/delayed.js` (the EDS-correct place - delayed phase, after LCP, zero CWV impact). Chat widgets use the facade pattern.
+Add a third-party service to `scripts/delayed.js` (the EDS-correct place - delayed phase, after LCP, zero CWV impact). Chat widgets use the facade pattern. **GTM** gets a `scripts/analytics.js` module (exports `trackEvent` / `loadGTM`, initialises the dataLayer, reads the container id from the `gtm-id` metadata) plus a `scripts/page-meta.js` (default-exported `pageMetaPush`); `delayed.js` imports both and pushes page metadata before GTM initialises.
 
 ```bash
 eds integrate                  # interactive