@excom/content-carousel 0.1.0

package/support/docs/README.md

@@ -0,0 +1,66 @@
+# content-carousel
+
+Rotate slides on autopilot or on click — galleries, hero banners, walkthroughs.
+
+<include-content data-demo="simple"></include-content>
+
+## 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
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## 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
+
+<include-content is-active template-ref="/views/api-reference/api-reference.html"></include-content>
+
+### 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.
+
+<include-content data-demo="manual"></include-content>
+
+#### Fade transition
+
+`slide-animation="fade"` crossfades instead of sliding.
+
+<include-content data-demo="fade"></include-content>

package/support/package-meta.json

@@ -0,0 +1,287 @@
+{
+  "shortName": "content-carousel",
+  "package": {
+    "name": "@excom/content-carousel",
+    "version": "0.1.0",
+    "description": "<content-carousel> custom element",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "fade": "<section>\n  <content-carousel auto-play=\"1.5\" slide-animation=\"fade\">\n    <content-carousel-slide is-active><h2>One</h2></content-carousel-slide>\n    <content-carousel-slide><h2>Two</h2></content-carousel-slide>\n    <content-carousel-slide><h2>Three</h2></content-carousel-slide>\n  </content-carousel>\n</section>\n",
+    "manual": "<section>\n  <content-carousel id=\"demo-carousel-manual\">\n    <button type=\"button\" rel=\"prev\" command=\"--back\" commandfor=\"demo-carousel-manual\">‹</button>\n    <button type=\"button\" rel=\"next\" command=\"--next\" commandfor=\"demo-carousel-manual\">›</button>\n    <content-carousel-slide is-active><h2>One</h2></content-carousel-slide>\n    <content-carousel-slide><h2>Two</h2></content-carousel-slide>\n    <content-carousel-slide><h2>Three</h2></content-carousel-slide>\n  </content-carousel>\n</section>\n",
+    "simple": "<section>\n  <content-carousel auto-play=\"1.5\">\n    <content-carousel-slide is-active><h2>One</h2></content-carousel-slide>\n    <content-carousel-slide><h2>Two</h2></content-carousel-slide>\n    <content-carousel-slide><h2>Three</h2></content-carousel-slide>\n  </content-carousel>\n</section>"
+  },
+  "readme": "<h1 id=\"md-content-carousel\">content-carousel</h1>\n<p>Rotate slides on autopilot or on click — galleries, hero banners, walkthroughs.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Auto-play</strong> Rotate on a timer via <code>auto-play</code></li>\n<li><strong>Manual nav</strong> <code>--back</code> / <code>--next</code> commands from plain buttons; <code>rel=&quot;prev&quot;</code> / <code>rel=&quot;next&quot;</code> positions them</li>\n<li><strong>Slide or fade</strong> Choose the transition with <code>slide-animation</code></li>\n<li><strong>Swipeable</strong> <code>slide-animation=&quot;track&quot;</code> wrapped in <spa-a route-href=\"/nucleus/packages/gesture-handler\" role=\"link\"><code>gesture-handler</code></spa-a>: drag and flick between slides</li>\n<li><strong>Pauses itself</strong> Manual navigation stops auto-play automatically</li>\n<li><strong>Bindable position</strong> <code>.provision</code> is <code>{ index, count, lastMove }</code> — a\nprogress readout is one Quark rule on <code>prop(&quot;provision&quot;)</code></li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Wrap <code>&lt;content-carousel-slide&gt;</code> elements in a <code>&lt;content-carousel&gt;</code>. Mark one\n<code>is-active</code>, or leave it unset to default to the first.</p>\n<include-content data-language=\"html\"><template>&lt;content-carousel auto-play=\"5\"&gt;\n  &lt;content-carousel-slide is-active&gt;One&lt;/content-carousel-slide&gt;\n  &lt;content-carousel-slide&gt;Two&lt;/content-carousel-slide&gt;\n  &lt;content-carousel-slide&gt;Three&lt;/content-carousel-slide&gt;\n&lt;/content-carousel&gt;</template></include-content>\n<p><code>.provision</code> is <code>{ index, count, lastMove }</code> — set on connect and after\nevery move, counting only this carousel&#39;s own slides. A &quot;2 / 3&quot; readout:</p>\n<include-content data-language=\"quark\"><template>content-carousel {\n  $slide: prop(\"provision\").index + 1;\n  $count: prop(\"provision\").count;\n  [bind-progress] { content: \"#{$slide} / #{$count}\"; }\n}</template></include-content>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-manual-navigation\">Manual navigation</h4>\n<p>Invoke <code>--back</code> / <code>--next</code> from a <code>&lt;button command commandfor&gt;</code>. A direct\nchild with <code>rel=&quot;prev&quot;</code> / <code>rel=&quot;next&quot;</code> (or\n<code>.tag-content-carousel-prev</code> / <code>.tag-content-carousel-next</code>) is\npositioned as the nav control for you. If you want swipeable slides, you\nmust use the carousel in conjunction with the <spa-a route-href=\"/nucleus/packages/gesture-handler\" role=\"link\"><gesture-handler></spa-a>.\nA demo exists on that page.</p>\n<p><include-content data-demo=\"manual\"></include-content></p>\n<h4 id=\"md-fade-transition\">Fade transition</h4>\n<p><code>slide-animation=&quot;fade&quot;</code> crossfades instead of sliding.</p>\n<p><include-content data-demo=\"fade\"></include-content></p>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-content-carousel\">content-carousel</h1>\n<p>Rotate slides on autopilot or on click — galleries, hero banners, walkthroughs.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Auto-play</strong> Rotate on a timer via <code>auto-play</code></li>\n<li><strong>Manual nav</strong> <code>--back</code> / <code>--next</code> commands from plain buttons; <code>rel=&quot;prev&quot;</code> / <code>rel=&quot;next&quot;</code> positions them</li>\n<li><strong>Slide or fade</strong> Choose the transition with <code>slide-animation</code></li>\n<li><strong>Swipeable</strong> <code>slide-animation=&quot;track&quot;</code> wrapped in <spa-a route-href=\"/nucleus/packages/gesture-handler\" role=\"link\"><code>gesture-handler</code></spa-a>: drag and flick between slides</li>\n<li><strong>Pauses itself</strong> Manual navigation stops auto-play automatically</li>\n<li><strong>Bindable position</strong> <code>.provision</code> is <code>{ index, count, lastMove }</code> — a\nprogress readout is one Quark rule on <code>prop(&quot;provision&quot;)</code></li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Wrap <code>&lt;content-carousel-slide&gt;</code> elements in a <code>&lt;content-carousel&gt;</code>. Mark one\n<code>is-active</code>, or leave it unset to default to the first.</p>\n<include-content data-language=\"html\"><template>&lt;content-carousel auto-play=\"5\"&gt;\n  &lt;content-carousel-slide is-active&gt;One&lt;/content-carousel-slide&gt;\n  &lt;content-carousel-slide&gt;Two&lt;/content-carousel-slide&gt;\n  &lt;content-carousel-slide&gt;Three&lt;/content-carousel-slide&gt;\n&lt;/content-carousel&gt;</template></include-content>\n<p><code>.provision</code> is <code>{ index, count, lastMove }</code> — set on connect and after\nevery move, counting only this carousel&#39;s own slides. A &quot;2 / 3&quot; readout:</p>\n<include-content data-language=\"quark\"><template>content-carousel {\n  $slide: prop(\"provision\").index + 1;\n  $count: prop(\"provision\").count;\n  [bind-progress] { content: \"#{$slide} / #{$count}\"; }\n}</template></include-content>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-manual-navigation\">Manual navigation</h4>\n<p>Invoke <code>--back</code> / <code>--next</code> from a <code>&lt;button command commandfor&gt;</code>. A direct\nchild with <code>rel=&quot;prev&quot;</code> / <code>rel=&quot;next&quot;</code> (or\n<code>.tag-content-carousel-prev</code> / <code>.tag-content-carousel-next</code>) is\npositioned as the nav control for you. If you want swipeable slides, you\nmust use the carousel in conjunction with the <spa-a route-href=\"/nucleus/packages/gesture-handler\" role=\"link\"><gesture-handler></spa-a>.\nA demo exists on that page.</p>\n<p><include-content data-demo=\"manual\"></include-content></p>\n<h4 id=\"md-fade-transition\">Fade transition</h4>\n<p><code>slide-animation=&quot;fade&quot;</code> crossfades instead of sliding.</p>\n<p><include-content data-demo=\"fade\"></include-content></p>\n"
+  },
+  "installation": {
+    "name": "@excom/content-carousel",
+    "shortName": "content-carousel",
+    "version": "0.1.0",
+    "description": "<content-carousel> custom element",
+    "packageType": "kit-element",
+    "cdn": "<script src=\"https://unpkg.com/@excom/kit-utils/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/neutron/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/content-carousel@0.1.0/dist/index.umd.min.js\"></script>\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@excom/content-carousel@0.1.0/dist/index.css\">",
+    "install": {
+      "npm": "npm install @excom/content-carousel"
+    },
+    "imports": {
+      "js": "import \"@excom/content-carousel\";",
+      "css": "@import \"@excom/content-carousel\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/content-carousel\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/content-carousel\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "content-carousel",
+      "summary": "Slide rotator — auto-play, manual nav, slide or fade transition.",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "auto-play",
+          "type": "number",
+          "description": "Seconds between automatic slide advances. Unset disables auto-play.",
+          "fieldName": "autoPlay",
+          "surface": "option"
+        },
+        {
+          "name": "is-scrubbing",
+          "type": "boolean",
+          "description": "Set when the element is being dragged. Used by CSS only to disable <code>transition</code>.",
+          "fieldName": "isScrubbing",
+          "surface": "option"
+        },
+        {
+          "name": "slide-animation",
+          "type": "string",
+          "description": "Transition used when the active slide changes.",
+          "fieldName": "slideAnimation",
+          "surface": "option",
+          "default": "\"slide\"",
+          "values": "\"slide\" | \"fade\""
+        },
+        {
+          "name": "auto-play-stopped",
+          "type": "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",
+          "surface": "hybrid"
+        },
+        {
+          "name": "last-move",
+          "type": "string",
+          "description": "Direction of the most recent slide change — drives the CSS animation direction.",
+          "fieldName": "lastMove",
+          "surface": "state",
+          "values": "\"forward\" | \"back\""
+        }
+      ],
+      "events": [
+        {
+          "name": "content-carousel-slide-changed",
+          "description": "After any slide change, manual or auto.",
+          "type": "ContentCarouselSlideChangedEvent",
+          "typeExpanded": "CustomEvent & { type: \"content-carousel-slide-changed\"; detail: { activeSlide: HTMLElement | null; previousSlide: HTMLElement | null; }; bubbles: true; cancelable: true; composed: true }"
+        }
+      ],
+      "slots": [],
+      "cssProperties": [
+        {
+          "name": "--content-carousel-button-size",
+          "description": "Min-width of the nav buttons.",
+          "syntax": "<length>",
+          "default": "25px"
+        },
+        {
+          "name": "--content-carousel-progress",
+          "description": "<code>slide-animation=&quot;track&quot;</code> only: how far the track is dragged, in slide widths — <code>1</code> shows the next slide, <code>-1</code> the previous. While <code>is-scrubbing</code> it follows a wrapping <code>&lt;gesture-handler&gt;</code>&#39;s inherited <code>--gesture-progress</code> unless set explicitly — swipeable carousels.",
+          "syntax": "<number>",
+          "default": "0"
+        },
+        {
+          "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"
+        }
+      ],
+      "cssClasses": [
+        {
+          "name": "tag-content-carousel-next",
+          "description": "Positions a direct child with <code>rel=&quot;next&quot;</code> (or <code>.tag-content-carousel-next</code>) as the &quot;next slide&quot; nav control."
+        },
+        {
+          "name": "tag-content-carousel-prev",
+          "description": "Positions a direct child with <code>rel=&quot;prev&quot;</code> (or <code>.tag-content-carousel-prev</code>) as the &quot;previous slide&quot; nav control."
+        }
+      ],
+      "cssAliases": [
+        {
+          "name": ":--content-carousel",
+          "selectors": [
+            "content-carousel",
+            ".tag-content-carousel"
+          ],
+          "kind": "element",
+          "description": ""
+        },
+        {
+          "name": ":--content-carousel--is-scrubbing",
+          "selectors": [
+            "[is-scrubbing]",
+            "[data-scrubbing]"
+          ],
+          "kind": "state",
+          "description": ""
+        },
+        {
+          "name": ":--content-carousel--last-move",
+          "selectors": [
+            "[last-move]",
+            "[data-last-move]"
+          ],
+          "kind": "state",
+          "description": ""
+        },
+        {
+          "name": ":--content-carousel--last-move-back",
+          "selectors": [
+            "[last-move=\"back\"]",
+            "[data-last-move=\"back\"]"
+          ],
+          "kind": "state",
+          "description": ""
+        },
+        {
+          "name": ":--content-carousel--last-move-forward",
+          "selectors": [
+            "[last-move=\"forward\"]",
+            "[data-last-move=\"forward\"]"
+          ],
+          "kind": "state",
+          "description": ""
+        },
+        {
+          "name": ":--content-carousel--slide-animation",
+          "selectors": [
+            "[slide-animation]",
+            "[data-slide-animation]"
+          ],
+          "kind": "state",
+          "description": ""
+        },
+        {
+          "name": ":--content-carousel--slide-animation-fade",
+          "selectors": [
+            "[slide-animation=\"fade\"]",
+            "[data-slide-animation=\"fade\"]"
+          ],
+          "kind": "state",
+          "description": ""
+        },
+        {
+          "name": ":--content-carousel--slide-animation-slide",
+          "selectors": [
+            "[slide-animation=\"slide\"]",
+            "[data-slide-animation=\"slide\"]"
+          ],
+          "kind": "state",
+          "description": ""
+        },
+        {
+          "name": ":--content-carousel--slide-animation-track",
+          "selectors": [
+            "[slide-animation=\"track\"]",
+            "[data-slide-animation=\"track\"]"
+          ],
+          "kind": "state",
+          "description": ""
+        }
+      ],
+      "listens": [],
+      "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."
+        }
+      ],
+      "defaultActions": [],
+      "expectedChildren": [
+        {
+          "name": "descendant:content-carousel-slide",
+          "relationship": "descendant",
+          "selector": "content-carousel-slide",
+          "required": true,
+          "description": "Slides to rotate through. The first, or whichever has <code>is-active</code>, is shown initially."
+        }
+      ],
+      "provisions": [
+        {
+          "name": "provision",
+          "type": "ContentCarouselProvision",
+          "typeExpanded": "{ index: number; count: number; lastMove: \"forward\" | \"back\" | null; }",
+          "description": "Position: <code>{ index, count, lastMove }</code> — the active slide&#39;s index among this carousel&#39;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"
+        }
+      ]
+    },
+    {
+      "tag": "content-carousel-slide",
+      "summary": "One rotating slide of a content-carousel.",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "is-active",
+          "type": "boolean",
+          "description": "Marks this as the currently shown slide. The parent <code>&lt;content-carousel&gt;</code> keeps exactly one slide active.",
+          "fieldName": "isActive",
+          "surface": "hybrid"
+        }
+      ],
+      "events": [],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [],
+      "cssAliases": [
+        {
+          "name": ":--content-carousel-slide",
+          "selectors": [
+            "content-carousel-slide",
+            ".tag-content-carousel-slide"
+          ],
+          "kind": "element",
+          "description": ""
+        },
+        {
+          "name": ":--content-carousel-slide--is-active",
+          "selectors": [
+            "[is-active]",
+            "[aria-current]"
+          ],
+          "kind": "state",
+          "description": ""
+        }
+      ],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": []
+    }
+  ],
+  "exportedFiles": {}
+}