@excom/content-carousel 0.1.0

package/support/custom-elements.json

@@ -0,0 +1,398 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "content-carousel.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "ContentCarousel",
+          "customElement": true,
+          "tagName": "content-carousel",
+          "summary": "Slide rotator — auto-play, manual nav, slide or fade transition.",
+          "description": "Position of a `<content-carousel>` among its own slides.",
+          "attributes": [
+            {
+              "name": "auto-play",
+              "type": {
+                "text": "number"
+              },
+              "description": "Seconds between automatic slide advances. Unset disables auto-play.",
+              "fieldName": "autoPlay"
+            },
+            {
+              "name": "is-scrubbing",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Set when the element is being dragged. Used by CSS only to disable `transition`.",
+              "fieldName": "isScrubbing"
+            },
+            {
+              "name": "slide-animation",
+              "type": {
+                "text": "string"
+              },
+              "description": "Transition used when the active slide changes.",
+              "fieldName": "slideAnimation",
+              "default": "slide",
+              "values": [
+                "slide",
+                "fade"
+              ]
+            },
+            {
+              "name": "last-move",
+              "type": {
+                "text": "string"
+              },
+              "description": "Direction of the most recent slide change — drives the CSS animation direction.",
+              "fieldName": "lastMove",
+              "values": [
+                "forward",
+                "back"
+              ]
+            },
+            {
+              "name": "auto-play-stopped",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Set automatically after manual navigation, or when the element leaves the document (a DOM move keeps auto-play running), to pause auto-play. Set it directly to pause / resume auto-play programmatically.",
+              "fieldName": "autoPlayStopped"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "autoPlay",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Seconds between automatic slide advances. Unset disables auto-play.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isScrubbing",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Set when the element is being dragged. Used by CSS only to disable `transition`.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "slideAnimation",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Transition used when the active slide changes.",
+              "default": "slide",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "lastMove",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "Direction of the most recent slide change — drives the CSS animation direction.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "autoPlayStopped",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Set automatically after manual navigation, or when the element leaves the document (a DOM move keeps auto-play running), to pause auto-play. Set it directly to pause / resume auto-play programmatically.",
+              "_neutron": {
+                "surface": "hybrid"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "provision",
+              "type": {
+                "text": "ContentCarouselProvision",
+                "expanded": "{ index: number; count: number; lastMove: \"forward\" | \"back\" | null; }"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Position: `{ index, count, lastMove }` — the active slide's index among this carousel's own slides, how many there are, and the direction of the last move. Set on connect and after every slide change. Not reflected as an attribute.",
+              "_neutron": {
+                "surface": "option"
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "content-carousel-slide-changed",
+              "description": "After any slide change, manual or auto.",
+              "type": {
+                "text": "ContentCarouselSlideChangedEvent",
+                "expanded": "CustomEvent & { type: \"content-carousel-slide-changed\"; detail: { activeSlide: HTMLElement | null; previousSlide: HTMLElement | null; }; bubbles: true; cancelable: true; composed: true }"
+              }
+            }
+          ],
+          "_neutron": {
+            "provisions": [
+              {
+                "name": "provision",
+                "type": {
+                  "text": "ContentCarouselProvision",
+                  "expanded": "{ index: number; count: number; lastMove: \"forward\" | \"back\" | null; }"
+                },
+                "description": "Position: `{ index, count, lastMove }` — the active slide's index among this carousel's own slides, how many there are, and the direction of the last move. Set on connect and after every slide change. Not reflected as an attribute.",
+                "fieldName": "provision"
+              }
+            ],
+            "commands": [
+              {
+                "name": "--back",
+                "description": "Shows the previous slide (wraps to last). Stops auto-play."
+              },
+              {
+                "name": "--next",
+                "description": "Shows the next slide (wraps to first). Stops auto-play."
+              }
+            ],
+            "expectedChildren": [
+              {
+                "relationship": "descendant",
+                "selector": "content-carousel-slide",
+                "required": true,
+                "description": "Slides to rotate through. The first, or whichever has `is-active`, is shown initially."
+              }
+            ],
+            "cssClasses": [
+              {
+                "name": "tag-content-carousel-prev",
+                "description": "Positions a direct child with `rel=\"prev\"` (or `.tag-content-carousel-prev`) as the \"previous slide\" nav control."
+              },
+              {
+                "name": "tag-content-carousel-next",
+                "description": "Positions a direct child with `rel=\"next\"` (or `.tag-content-carousel-next`) as the \"next slide\" nav control."
+              }
+            ],
+            "cssAliases": [
+              {
+                "name": ":--content-carousel",
+                "selectors": [
+                  "content-carousel",
+                  ".tag-content-carousel"
+                ],
+                "kind": "element"
+              },
+              {
+                "name": ":--content-carousel--last-move",
+                "selectors": [
+                  "[last-move]",
+                  "[data-last-move]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--content-carousel--last-move-forward",
+                "selectors": [
+                  "[last-move=\"forward\"]",
+                  "[data-last-move=\"forward\"]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--content-carousel--last-move-back",
+                "selectors": [
+                  "[last-move=\"back\"]",
+                  "[data-last-move=\"back\"]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--content-carousel--slide-animation",
+                "selectors": [
+                  "[slide-animation]",
+                  "[data-slide-animation]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--content-carousel--slide-animation-slide",
+                "selectors": [
+                  "[slide-animation=\"slide\"]",
+                  "[data-slide-animation=\"slide\"]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--content-carousel--slide-animation-fade",
+                "selectors": [
+                  "[slide-animation=\"fade\"]",
+                  "[data-slide-animation=\"fade\"]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--content-carousel--slide-animation-track",
+                "selectors": [
+                  "[slide-animation=\"track\"]",
+                  "[data-slide-animation=\"track\"]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--content-carousel--is-scrubbing",
+                "selectors": [
+                  "[is-scrubbing]",
+                  "[data-scrubbing]"
+                ],
+                "kind": "state"
+              }
+            ]
+          },
+          "cssProperties": [
+            {
+              "name": "--content-carousel-slide-animation-duration",
+              "description": "Length of the slide / fade transition.",
+              "syntax": "<time>",
+              "default": "0.25s"
+            },
+            {
+              "name": "--content-carousel-transition-ease",
+              "description": "Easing used for the fade transition.",
+              "syntax": "<easing-function>",
+              "default": "ease-out"
+            },
+            {
+              "name": "--content-carousel-button-size",
+              "description": "Min-width of the nav buttons.",
+              "syntax": "<length>",
+              "default": "25px"
+            },
+            {
+              "name": "--content-carousel-progress",
+              "description": "`slide-animation=\"track\"` only: how far the track is dragged, in slide widths — `1` shows the next slide, `-1` the previous. While `is-scrubbing` it follows a wrapping `<gesture-handler>`'s inherited `--gesture-progress` unless set explicitly — swipeable carousels.",
+              "syntax": "<number>",
+              "default": "0"
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ContentCarousel",
+          "declaration": {
+            "name": "ContentCarousel",
+            "module": "content-carousel.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "content-carousel",
+          "declaration": {
+            "name": "ContentCarousel",
+            "module": "content-carousel.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "content-carousel-slide.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "ContentCarouselSlide",
+          "customElement": true,
+          "tagName": "content-carousel-slide",
+          "summary": "One rotating slide of a content-carousel.",
+          "description": "A single slide within `<content-carousel>`.",
+          "attributes": [
+            {
+              "name": "is-active",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Marks this as the currently shown slide. The parent `<content-carousel>` keeps exactly one slide active.",
+              "fieldName": "isActive"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "isActive",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Marks this as the currently shown slide. The parent `<content-carousel>` keeps exactly one slide active.",
+              "_neutron": {
+                "surface": "hybrid"
+              }
+            }
+          ],
+          "_neutron": {
+            "cssAliases": [
+              {
+                "name": ":--content-carousel-slide",
+                "selectors": [
+                  "content-carousel-slide",
+                  ".tag-content-carousel-slide"
+                ],
+                "kind": "element"
+              },
+              {
+                "name": ":--content-carousel-slide--is-active",
+                "selectors": [
+                  "[is-active]",
+                  "[aria-current]"
+                ],
+                "kind": "state"
+              }
+            ]
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ContentCarouselSlide",
+          "declaration": {
+            "name": "ContentCarouselSlide",
+            "module": "content-carousel-slide.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "content-carousel-slide",
+          "declaration": {
+            "name": "ContentCarouselSlide",
+            "module": "content-carousel-slide.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/demos/fade.html

@@ -0,0 +1,7 @@
+<section>
+  <content-carousel auto-play="1.5" slide-animation="fade">
+    <content-carousel-slide is-active><h2>One</h2></content-carousel-slide>
+    <content-carousel-slide><h2>Two</h2></content-carousel-slide>
+    <content-carousel-slide><h2>Three</h2></content-carousel-slide>
+  </content-carousel>
+</section>

package/support/demos/manual.html

@@ -0,0 +1,9 @@
+<section>
+  <content-carousel id="demo-carousel-manual">
+    <button type="button" rel="prev" command="--back" commandfor="demo-carousel-manual">‹</button>
+    <button type="button" rel="next" command="--next" commandfor="demo-carousel-manual">›</button>
+    <content-carousel-slide is-active><h2>One</h2></content-carousel-slide>
+    <content-carousel-slide><h2>Two</h2></content-carousel-slide>
+    <content-carousel-slide><h2>Three</h2></content-carousel-slide>
+  </content-carousel>
+</section>

package/support/demos/simple.html

@@ -0,0 +1,7 @@
+<section>
+  <content-carousel auto-play="1.5">
+    <content-carousel-slide is-active><h2>One</h2></content-carousel-slide>
+    <content-carousel-slide><h2>Two</h2></content-carousel-slide>
+    <content-carousel-slide><h2>Three</h2></content-carousel-slide>
+  </content-carousel>
+</section>

package/support/dist-docs/content-carousel-slide.md

@@ -0,0 +1,20 @@
+# `<content-carousel-slide>`
+
+> One rotating slide of a content-carousel.
+
+**Tag:** `<content-carousel-slide>`
+
+## API
+
+### Attributes
+
+| Name | Surface | Type | Default | Values | Description |
+| --- | --- | --- | --- | --- | --- |
+| `is-active` | hybrid | `boolean` |  |  | Marks this as the currently shown slide. The parent `<content-carousel>` keeps exactly one slide active. |
+
+### CSS Aliases
+
+| Alias | Kind | Matches | Description |
+| --- | --- | --- | --- |
+| `:--content-carousel-slide` | element | `content-carousel-slide`, `.tag-content-carousel-slide` |  |
+| `:--content-carousel-slide--is-active` | state | `[is-active]`, `[aria-current]` |  |

package/support/dist-docs/content-carousel.md

@@ -0,0 +1,184 @@
+# content-carousel
+
+Rotate slides on autopilot or on click — galleries, hero banners, walkthroughs.
+
+
+```html
+<section>
+  <content-carousel auto-play="1.5">
+    <content-carousel-slide is-active><h2>One</h2></content-carousel-slide>
+    <content-carousel-slide><h2>Two</h2></content-carousel-slide>
+    <content-carousel-slide><h2>Three</h2></content-carousel-slide>
+  </content-carousel>
+</section>
+```
+
+
+## Features
+
+- **Auto-play** Rotate on a timer via `auto-play`
+- **Manual nav** `--back` / `--next` commands from plain buttons; `rel="prev"` / `rel="next"` positions them
+- **Slide or fade** Choose the transition with `slide-animation`
+- **Swipeable** `slide-animation="track"` wrapped in [`gesture-handler`](/nucleus/packages/gesture-handler): drag and flick between slides
+- **Pauses itself** Manual navigation stops auto-play automatically
+- **Bindable position** `.provision` is `{ index, count, lastMove }` — a
+  progress readout is one Quark rule on `prop("provision")`
+
+## Installation
+
+
+`@excom/content-carousel` v0.1.0
+
+```bash
+pnpm add @excom/content-carousel
+```
+
+```bash
+npm install @excom/content-carousel
+```
+
+```bash
+yarn add @excom/content-carousel
+```
+
+### Import
+
+```ts
+import "@excom/content-carousel";
+```
+
+
+
+## Usage
+
+Wrap `<content-carousel-slide>` elements in a `<content-carousel>`. Mark one
+`is-active`, or leave it unset to default to the first.
+
+```html
+<content-carousel auto-play="5">
+  <content-carousel-slide is-active>One</content-carousel-slide>
+  <content-carousel-slide>Two</content-carousel-slide>
+  <content-carousel-slide>Three</content-carousel-slide>
+</content-carousel>
+```
+
+`.provision` is `{ index, count, lastMove }` — set on connect and after
+every move, counting only this carousel's own slides. A "2 / 3" readout:
+
+```quark
+content-carousel {
+  $slide: prop("provision").index + 1;
+  $count: prop("provision").count;
+  [bind-progress] { content: "#{$slide} / #{$count}"; }
+}
+```
+
+### API Reference
+
+
+#### Attributes
+
+| Name | Surface | Type | Default | Values | Description |
+| --- | --- | --- | --- | --- | --- |
+| `auto-play` | option | `number` |  |  | Seconds between automatic slide advances. Unset disables auto-play. |
+| `is-scrubbing` | option | `boolean` |  |  | Set when the element is being dragged. Used by CSS only to disable `transition`. |
+| `slide-animation` | option | `string` | `"slide"` | `"slide"` \| `"fade"` | Transition used when the active slide changes. |
+| `last-move` | state | `string` |  | `"forward"` \| `"back"` | Direction of the most recent slide change — drives the CSS animation direction. |
+| `auto-play-stopped` | hybrid | `boolean` |  |  | Set automatically after manual navigation, or when the element leaves the document (a DOM move keeps auto-play running), to pause auto-play. Set it directly to pause / resume auto-play programmatically. |
+
+#### Provision
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `provision` | `ContentCarouselProvision` (`{ index: number; count: number; lastMove: "forward" \| "back" \| null; }`) | Position: `{ index, count, lastMove }` — the active slide's index among this carousel's own slides, how many there are, and the direction of the last move. Set on connect and after every slide change. Not reflected as an attribute. |
+
+#### Recognized Elements
+
+| Relationship | Selector | Required | Description |
+| --- | --- | --- | --- |
+| `content-carousel-slide` | descendant | yes | Slides to rotate through. The first, or whichever has `is-active`, is shown initially. |
+
+#### Fires
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `content-carousel-slide-changed` | `ContentCarouselSlideChangedEvent` (`CustomEvent & { type: "content-carousel-slide-changed"; detail: { activeSlide: HTMLElement \| null; previousSlide: HTMLElement \| null; }; bubbles: true; cancelable: true; composed: true }`) | After any slide change, manual or auto. |
+
+#### Commands
+
+| Command | Action |
+| --- | --- |
+| `--back` | Shows the previous slide (wraps to last). Stops auto-play. |
+| `--next` | Shows the next slide (wraps to first). Stops auto-play. |
+
+#### CSS Custom Properties
+
+| Name | Syntax | Default | Description |
+| --- | --- | --- | --- |
+| `--content-carousel-slide-animation-duration` | `<time>` | `0.25s` | Length of the slide / fade transition. |
+| `--content-carousel-transition-ease` | `<easing-function>` | `ease-out` | Easing used for the fade transition. |
+| `--content-carousel-button-size` | `<length>` | `25px` | Min-width of the nav buttons. |
+| `--content-carousel-progress` | `<number>` | `0` | `slide-animation="track"` only: how far the track is dragged, in slide widths — `1` shows the next slide, `-1` the previous. While `is-scrubbing` it follows a wrapping `<gesture-handler>`'s inherited `--gesture-progress` unless set explicitly — swipeable carousels. |
+
+#### CSS Classes
+
+| Name | Description |
+| --- | --- |
+| `.tag-content-carousel-prev` | Positions a direct child with `rel="prev"` (or `.tag-content-carousel-prev`) as the "previous slide" nav control. |
+| `.tag-content-carousel-next` | Positions a direct child with `rel="next"` (or `.tag-content-carousel-next`) as the "next slide" nav control. |
+
+#### CSS Aliases
+
+| Alias | Kind | Matches | Description |
+| --- | --- | --- | --- |
+| `:--content-carousel` | element | `content-carousel`, `.tag-content-carousel` |  |
+| `:--content-carousel--last-move` | state | `[last-move]`, `[data-last-move]` |  |
+| `:--content-carousel--last-move-forward` | state | `[last-move="forward"]`, `[data-last-move="forward"]` |  |
+| `:--content-carousel--last-move-back` | state | `[last-move="back"]`, `[data-last-move="back"]` |  |
+| `:--content-carousel--slide-animation` | state | `[slide-animation]`, `[data-slide-animation]` |  |
+| `:--content-carousel--slide-animation-slide` | state | `[slide-animation="slide"]`, `[data-slide-animation="slide"]` |  |
+| `:--content-carousel--slide-animation-fade` | state | `[slide-animation="fade"]`, `[data-slide-animation="fade"]` |  |
+| `:--content-carousel--slide-animation-track` | state | `[slide-animation="track"]`, `[data-slide-animation="track"]` |  |
+| `:--content-carousel--is-scrubbing` | state | `[is-scrubbing]`, `[data-scrubbing]` |  |
+
+
+
+### Examples
+
+#### Manual navigation
+
+Invoke `--back` / `--next` from a `<button command commandfor>`. A direct
+child with `rel="prev"` / `rel="next"` (or
+`.tag-content-carousel-prev` / `.tag-content-carousel-next`) is
+positioned as the nav control for you. If you want swipeable slides, you
+must use the carousel in conjunction with the [<gesture-handler>](/nucleus/packages/gesture-handler).
+A demo exists on that page.
+
+
+```html
+<section>
+  <content-carousel id="demo-carousel-manual">
+    <button type="button" rel="prev" command="--back" commandfor="demo-carousel-manual">‹</button>
+    <button type="button" rel="next" command="--next" commandfor="demo-carousel-manual">›</button>
+    <content-carousel-slide is-active><h2>One</h2></content-carousel-slide>
+    <content-carousel-slide><h2>Two</h2></content-carousel-slide>
+    <content-carousel-slide><h2>Three</h2></content-carousel-slide>
+  </content-carousel>
+</section>
+```
+
+
+#### Fade transition
+
+`slide-animation="fade"` crossfades instead of sliding.
+
+
+```html
+<section>
+  <content-carousel auto-play="1.5" slide-animation="fade">
+    <content-carousel-slide is-active><h2>One</h2></content-carousel-slide>
+    <content-carousel-slide><h2>Two</h2></content-carousel-slide>
+    <content-carousel-slide><h2>Three</h2></content-carousel-slide>
+  </content-carousel>
+</section>
+```

package/support/docs/INTERNAL.md

@@ -0,0 +1,4 @@
+- Slide animation: switching direction (forward to back, or vice versa) in
+  quick succession briefly flashes the last slide, due to either z-index
+  ordering or the hard jump in `transform: translateX()` from 100% to
+  -100%.