sliderpro-agentic-skills-etch 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sliderpro-agentic-skills-etch",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Installs the Slider Pro for Etch AI Connector skills files and component docs into any project",
   "type": "module",
   "bin": {

package/skills-package/slider-skills/slider-pro-skills-reference.md

@@ -444,19 +444,28 @@ handler inside `ready()`: the slider mounted before your code ran, so it has alr
 Before configuring an unfamiliar slider, check whether it is a premade template. If it is, use
 that template's documented knobs rather than inventing new CSS.
 
-| Template | Identify by | Script | Guide |
-| --- | --- | --- | --- |
-| Slider Zeon | `.slider-zeon`, `.main-slider-zeon` | no | `https://design-with-cracka.gitbook.io/etchsliderpro/premade-templates` |
-| Slider Chronos | `.slider-chronos` | no | `https://design-with-cracka.gitbook.io/etchsliderpro/premade-templates` |
-| Slider Flow | `.slider-flow` | no | `https://design-with-cracka.gitbook.io/etchsliderpro/premade-templates` |
-| Slider Team | `.slider-team` | no | `https://design-with-cracka.gitbook.io/etchsliderpro/premade-templates` |
-| Slider Stack | `.slider-stack`, `.slider-stack__card` | no | `https://design-with-cracka.gitbook.io/etchsliderpro/card-stack-templates` |
-| Slider Marquee | no class prefix. Identify by the combination: Infinite Scroll on, Edge Fade on, Slide Auto Width on, two wrappers whose rows scroll in opposite directions | no | `https://design-with-cracka.gitbook.io/etchsliderpro/premade-templates` |
-| Deck Featured | `.deck-stack-featured`, `.deck-card-featured` | yes | `https://design-with-cracka.gitbook.io/etchsliderpro/card-stack-templates` |
-| Deck Testimonial | `.deck-stack-testimonial`, `.deck-card-testimonial` | yes | `https://design-with-cracka.gitbook.io/etchsliderpro/card-stack-templates` |
-| Fall | `.fall-stack`, `.fall-card` | yes | `https://design-with-cracka.gitbook.io/etchsliderpro/card-stack-templates` |
-
-All nine use Sync Custom Element.
+Every template names its Wrapper, so one class on the Wrapper identifies all nine. Check that
+first; the second column is confirmation.
+
+| Template | Wrapper class | Also present | Script | Guide |
+| --- | --- | --- | --- | --- |
+| Slider Zeon | `.slider-zeon-wrapper` | `.slider-zeon__bg-thumb`, `.main-slider-zeon__content` | no | `https://design-with-cracka.gitbook.io/etchsliderpro/premade-templates` |
+| Slider Chronos | `.slider-chronos-wrapper` | `.slider-chronos__slide`, `.slider-chronos__year` | no | `https://design-with-cracka.gitbook.io/etchsliderpro/premade-templates` |
+| Slider Flow | `.slider-flow-wrapper` | `.slider-flow__slide`, `.slider-flow__slide-bg-media` | no | `https://design-with-cracka.gitbook.io/etchsliderpro/premade-templates` |
+| Slider Team | `.slider-team-wrapper` | `.slider-team__grid`, `.slider-team__sync` | no | `https://design-with-cracka.gitbook.io/etchsliderpro/premade-templates` |
+| Slider Stack | `.slider-stack-wrapper` | `.slider-stack__card`, `.slider-stack__card-lift` | no | `https://design-with-cracka.gitbook.io/etchsliderpro/card-stack-templates` |
+| Slider Marquee | `.slider-marquee-wrapper` | two rows, Infinite Scroll on, Edge Fade on the Wrapper | no | `https://design-with-cracka.gitbook.io/etchsliderpro/premade-templates` |
+| Deck Featured | `.slider-wrapper-deck-featured` | `.deck-stack-featured`, `.deck-card-featured` | yes | `https://design-with-cracka.gitbook.io/etchsliderpro/card-stack-templates` |
+| Deck Testimonial | `.slider-wrapper-deck-testimonial` | `.deck-stack-testimonial`, `.deck-card-testimonial` | yes | `https://design-with-cracka.gitbook.io/etchsliderpro/card-stack-templates` |
+| Fall | `.slider-wrapper-fall` | `.fall-stack`, `.fall-card` | yes | `https://design-with-cracka.gitbook.io/etchsliderpro/card-stack-templates` |
+
+Note the two naming schemes: the six slider templates suffix the name (`.slider-flow-wrapper`),
+the three card stacks infix it (`.slider-wrapper-fall`).
+
+Five of the nine sync elements outside the track, and they do not all use the same prop. Team and
+Stack set `sliderSetup.syncCustomElement` on the Slider; the three card stacks set
+`sliderlessSync.customElement` on the Wrapper. Zeon pairs sliders by `sliderSetup.sliderRole`
+instead, and Chronos, Flow and Marquee sync nothing.
 
 The three that carry a script expose named constants at the top of it. On the two Deck templates,
 `MAX_TIERS` is the deepest ring the CSS defines and `NAV_RINGS` is how many rings stay clickable.

package/skills-package/slider-skills/slider-pro-skills.md

@@ -142,25 +142,106 @@ etch.blocks.create(json, parentId?, index?)  // returns new id
 etch.components.list()                       // [{ id, name }, ...]
 etch.components.getJson(id)                  // .properties and .blocks
 etch.styles.list()                           // [{ id, selector, type, collection, css }]
+etch.styles.create(selector, css)            // returns a STYLE ID; pass it to a class prop
+etch.blocks.addClass(blockId, name)          // plain elements only; throws on a component
+etch.blocks.getJson(id).script               // { code }, the JavaScript code block
 await etch.saveAsync()
 ```
 
 ### Component instances are the unit of work
 
-A Slider Pro build is a tree of `etch/component` blocks, each carrying `ref` (the component id) and
-a flat `attributes` map of prop values:
+A Slider Pro build is a tree of `etch/component` blocks, each naming a component and carrying a
+flat `attributes` map of prop values. **Two different shapes describe the same tree, and mixing
+them up is the first thing that goes wrong in a session.**
+
+**The live shape**, which `etch.blocks.getTree()` returns and `etch.blocks.create()` accepts:
 
 ```json
 {
-  "blockName": "etch/component",
-  "attrs": {
-    "metadata": { "name": "-  Flow" },
-    "ref": 6455,
-    "attributes": { "wrapperHeight": "350px", "spaceBetweenSliders": "50px" }
-  }
+  "type": "etch/component",
+  "version": 1,
+  "context": {},
+  "children": [],
+  "componentId": 6455,
+  "attributes": { "wrapperHeight": "350px", "spaceBetweenSliders": "50px" }
 }
 ```
 
+`version`, `context` and `children` are required. Block ids are strings (`"ot2wnef"`), not numbers.
+
+**The export shape**, which you only ever see inside a premade template `.json` file, uses
+`blockName`, nests under `attrs`, and calls the component id `ref`:
+
+```json
+{ "blockName": "etch/component", "attrs": { "ref": 6455, "attributes": {} }, "innerBlocks": [] }
+```
+
+Never pass the export shape to `create()`. It is rejected with
+`Invalid block JSON: expected string, received undefined` at `path: ["type"]`. To put a template on
+the page, hand its whole `gutenbergBlock` to `etch.blocks.pasteAsync()` instead.
+
+### Children go in a slot, never directly on the component
+
+A component's children must be wrapped in an `etch/slot-content` node naming the slot they fill.
+Putting a Slider straight inside a Wrapper's `children` renders nothing.
+
+```json
+{ "type": "etch/slot-content", "version": 1, "context": {}, "children": [], "slotName": "Slides" }
+```
+
+| Component | Slots |
+| --- | --- |
+| DWC Slider Wrapper | `Sliders_and_Controls` |
+| DWC Slider | `Top__Controls`, `Slides`, `Bottom__Controls` |
+| DWC Slide | `Content` |
+| DWC Slider Pagination | `PaginationButtons` |
+| DWC Slider Nav Button | `Nav_Btn_Content` |
+| DWC Slider Progress, DWC Slider Play-Pause | none |
+
+Controls are siblings of the Slider inside `Sliders_and_Controls`, or children of the Slider's own
+`Top__Controls` / `Bottom__Controls`. Both work, because controls find their own slider.
+
+### Classes: two different mechanisms
+
+Adding a class to a plain element and adding one to a component are **not the same operation**, and
+the component path is the one that matters here, because everything Slider Pro ships is a component.
+
+**On a component**, `addClass` throws `Block "<id>" is not an HTML block.` Classes go through the
+component's own class-typed prop, and the value is the **style id**, not the class name:
+
+```js
+const styleId = etch.styles.create('.flow-demo', 'border-radius: 1rem;');  // returns an id
+etch.blocks.setAttribute(wrapperId, 'customClass', styleId);
+```
+
+Etch resolves the id to the selector name when it renders, so the page gets
+`class="dwc-slider-wrapper flow-demo"`. The id never appears in the output. Store the id, not the
+name, so the class survives being renamed in the Etch UI.
+
+The class-typed props, one per component:
+
+| Component | Prop |
+| --- | --- |
+| DWC Slider Wrapper | `customClass` |
+| DWC Slider | `sliderClass` |
+| DWC Slide, Progress, Play-Pause, Pagination | `class` |
+| DWC Slider Nav Button | `buttonClass`, `buttonWrapperClass` |
+
+**On a plain element**, use `addClass` with the bare class name, no dot and no id:
+
+```js
+const id = etch.blocks.create(el('article', {}, []));
+etch.blocks.addClass(id, 'fall-card');
+```
+
+Passing a style id here does not resolve. It is treated as a literal name and sanitised, so
+`30xsolr` silently becomes the class `xsolr`. Creating the element with `attributes: { class: '...' }`
+works too and is fine when you are building a subtree in one call.
+
+Either way the CSS rule itself is `etch.styles.create('.fall-card', '...')`, which is what the
+selector has to match.
+
+
 ### Group props and the one-extra-brace rule
 
 Most Slider props live in groups (`layout`, `motion`, `slides`, `autoplay`, ...). A group is stored
@@ -305,9 +386,9 @@ unit. `props.pauseSlidersOnHover` on the Wrapper pauses both rows together.
 
 Infinite Scroll needs the Auto-Scroll extension enabled in admin settings, which is the default.
 
-### Synced elements (Zeon, Chronos, Team)
+### Synced elements (Team, Stack)
 
-The pattern behind the full-bleed hero, the timeline and the staff showcase is one prop.
+Driving arbitrary elements on the page from the slider is one prop.
 
 ```js
 setGroup(sliderId, 'sliderSetup', { syncCustomElement: '.timeline-node',
@@ -319,8 +400,23 @@ moves, and with nav on, clicking one jumps the slider to it. **You write the CSS
 states.** The elements do not need to be inside the slider and do not need to match the slide
 count.
 
+The selector takes a comma-separated list, so one slider can drive several groups at once. Team
+uses `'.slider-team__sync, .slider-team__sync-heading'` to move a portrait and a heading together.
+
 Grep `## 3. Sync Custom Element` in the reference for multiple selectors and the overlap caveat.
 
+### Main and thumbnails in one wrapper (Zeon)
+
+A full-bleed hero with a thumbnail strip needs no sync prop at all, just roles:
+
+```js
+setGroup(mainId,  'sliderSetup', { sliderRole: 'main',       transitionType: 'Fade' });
+setGroup(thumbId, 'sliderSetup', { sliderRole: 'thumbnails', transitionType: 'Loop' });
+```
+
+Both inside the same Wrapper and they pair automatically. A Wrapper can hold more than one
+thumbnail slider, which is how Zeon runs a background layer and a strip off the same main.
+
 ### Carousel on mobile, grid on desktop
 
 ```js
@@ -345,25 +441,89 @@ setGroup(wrapperId, 'sliderlessSync', {
 
 CSS handles the front card and its two neighbours from `is-active` / `is-prev` / `is-next`. What
 CSS cannot do is know that a given card is *three* back, so the rows behind, the z-index ladder and
-the click targets need a script. That is case 1 of the native-first gate. The shipped script does
-exactly three things:
+the click targets need a script. That is case 1 of the native-first gate.
+
+The contract between that script and the CSS is one attribute, **`data-pos`**, which the script
+derives from `is-active` and writes on every card. It is a **signed** offset from the active card,
+so the CSS can fan the left and right sides in opposite directions:
+
+```css
+.deck-stack-featured &:is([data-pos='2'], [data-pos='-2']) { /* ring 2, both sides */ }
+```
+
+The stack container carries **`data-tiers`**, how many rings are actually in play. It is computed,
+not fixed: a looping deck needs spare cards to hide the wrap behind, so the script reduces the
+tiers when there are too few cards.
+
+Writing an unsigned rank, or naming the attribute anything else, produces a flat pile: the rules
+above simply never match. The shipped script does this:
 
 ```js
 // 1. make a custom property interpolable, so a blur can animate (case 2)
 CSS.registerProperty({ name: '--stack-focus', syntax: '<number>',
                        inherits: true, initialValue: '0' });
 
-// 2. per card: distance from the active one, capped at the deepest tier the CSS defines
-var rank = Math.abs(distanceFromActive);
-card.setAttribute('data-tier', Math.min(rank, MAX_TIERS));
+// 2. how many rings this deck can afford, given looping and the card count
+var mayLoop = wrap.dataset.loop === 'true' && total >= MIN_LOOP;
+stack.dataset.tiers = mayLoop ? Math.min(MAX_TIERS, Math.floor((total - 3) / 2)) : MAX_TIERS;
 
-// 3. hit-testing: stack order by rank, and clicks off beyond the clickable rings
+// 3. per card: SIGNED offset from the active card. On a looping deck the offset
+//    wraps, so the far end of the list reads as the near side, not as distance 8.
+var d = n - active;
+if (mayLoop) {
+  if (d >  total / 2) d -= total;
+  if (d < -total / 2) d += total;
+}
+card.dataset.pos = d;
+
+// 4. hit-testing: stack order by distance, and clicks off beyond the clickable rings
+var rank = Math.abs(d);
 card.style.zIndex = String(total - rank);
 lift.style.pointerEvents = rank <= NAV_RINGS ? 'auto' : 'none';
 ```
 
-Step 3 is not optional. Stacked cards are coplanar, so the browser hit-tests them by DOM order and
-a click near the front card can land on one three positions away.
+Do not clamp `data-pos` to the tier count. Cards past the deepest ring should match no rule and
+stay stacked at the back; clamping piles them onto the last visible ring instead.
+
+Both decks also set `--i` on each line of card content so the CSS can stagger it:
+
+```js
+card.querySelectorAll('.deck-card-featured__content > *')
+    .forEach(function (line, j) { line.style.setProperty('--i', j); });
+```
+
+Step 4 is Deck only. **Fall's script is much smaller**: it sets `--i` and a signed `data-pos`, and
+nothing else. Fall never loops, so there is no wrap to fold and no z-index ladder to maintain,
+because the cards fall past each other rather than fanning around a front card.
+
+Recompute on every change: watch the stack with a `MutationObserver` filtered to `class`, since
+`is-active` moving is the only signal you get.
+
+### Where a script goes
+
+**Not in a `<script>` element.** Etch silently drops one from the render, so the page looks right
+in the builder and ships with no behaviour at all.
+
+Every block has an optional `script` field (`EtchBlockScript`), which is Etch's JavaScript code
+block. Put the code on the **component instance that owns the markup**, which for a card stack is
+the Wrapper:
+
+```js
+const wrapperId = etch.blocks.create({
+  type: 'etch/component', version: 1, context: {}, children: [ /* ... */ ],
+  componentId: C['DWC Slider Wrapper'], attributes: {},
+  script: { code: "(function () { /* ... */ })();" }
+});
+```
+
+`code` is **plain source** over the API. The base64 you see in a premade template `.json` is only
+how the export serialises it; do not encode it yourself.
+
+Etch renders it as `<script type="module" defer>`, so it runs after parsing and top-level `await`
+is available. Read it back with `etch.blocks.getJson(id).script`.
+
+Component scripts are also the reason a card deck keeps working: the bridge leaves Sync Without
+Slider wrappers unreconstructed precisely so an author's script keeps observing the original nodes.
 
 Card counts for a looping deck: three are always visible (front plus two), and a loop needs a
 hidden slot at each end, so **five is the minimum** and nine gives the full three-row fan. Fall
@@ -392,19 +552,30 @@ function setGroup(id, key, patch) {
   etch.blocks.setAttribute(id, key, '{' + JSON.stringify(next) + '}');
 }
 
-function component(ref, attributes, children) {
-  return {
-    blockName: 'etch/component',
-    attrs: { ref: ref, attributes: attributes || {} },
-    innerBlocks: children || []
-  };
+function node(extra, children) {
+  return Object.assign({ version: 1, context: {}, children: children || [] }, extra);
 }
 
-function findByRef(nodes, ref, out) {
+function component(componentId, attributes, children) {
+  return node({ type: 'etch/component', componentId: componentId,
+                attributes: attributes || {} }, children);
+}
+
+function slot(slotName, children) {
+  return node({ type: 'etch/slot-content', slotName: slotName }, children);
+}
+
+function el(tag, attributes, children) {
+  return node({ type: 'etch/element', tag: tag, attributes: attributes || {} }, children);
+}
+
+function text(t) { return node({ type: 'etch/text', text: t }); }
+
+function findByRef(nodes, componentId, out) {
   out = out || [];
   for (const n of nodes || []) {
-    if (n.componentId === ref || (n.attrs && n.attrs.ref === ref)) out.push(n);
-    findByRef(n.children || n.innerBlocks || [], ref, out);
+    if (n.componentId === componentId) out.push(n);
+    findByRef(n.children, componentId, out);
   }
   return out;
 }
@@ -415,18 +586,27 @@ function findByRef(nodes, ref, out) {
 ```js
 const C = comps();
 const slides = [];
-for (let i = 0; i < 5; i++) slides.push(component(C['DWC Slide'], {}));
+for (let i = 0; i < 5; i++) {
+  slides.push(component(C['DWC Slide'], {}, [
+    slot('Content', [ el('div', {}, [ text('Slide ' + (i + 1)) ]) ])
+  ]));
+}
 
 const id = etch.blocks.create(
   component(C['DWC Slider Wrapper'], {}, [
-    component(C['DWC Slider'], {}, slides),
-    component(C['DWC Slider Nav Button'], {}),
-    component(C['DWC Slider Pagination'], {})
+    slot('Sliders_and_Controls', [
+      component(C['DWC Slider'], {}, [ slot('Slides', slides) ]),
+      component(C['DWC Slider Nav Button'], {}),
+      component(C['DWC Slider Pagination'], {})
+    ])
   ])
 );
 return id;
 ```
 
+An empty Slide has no content and so no height. Give slides something to size before wondering why
+the slider is a flat line.
+
 Build **one** first, screenshot it, then scale to the full count. Do not generate twenty slides
 before you have seen one render.