@excom/content-carousel 0.1.0

package/.rush/temp/chunked-rush-logs/content-carousel.apply-exports.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/chunked-rush-logs/content-carousel.build_docs.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/chunked-rush-logs/content-carousel.build_package-metas.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/apply-exports/all.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/.rush/temp/operation/apply-exports/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/operation/apply-exports/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 35.694532999999865
+}

package/.rush/temp/operation/build_docs/all.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/.rush/temp/operation/build_docs/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/operation/build_docs/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 55.47787799999992
+}

package/.rush/temp/operation/build_package-metas/all.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/.rush/temp/operation/build_package-metas/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/build_package-metas/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 112.92609100000004
+}

package/.rush/temp/shrinkwrap-deps.json

@@ -0,0 +1,3 @@
+{
+  "../../packages/content-carousel": "../../packages/content-carousel:n8+/7TfT7BWuKysR6wAgrprpaS+oWYsVdAAvlNgBNcM=:"
+}

package/config/rig.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  "rigPackageName": "@excom/heft-rig",
+  "rigProfile": "default"
+}

package/content-carousel-slide.ts

@@ -0,0 +1,19 @@
+import { Neutron } from "@excom/neutron";
+
+/**
+ * A single slide within `<content-carousel>`.
+ *
+ * @summary One rotating slide of a content-carousel.
+ */
+export const ContentCarouselSlide = Neutron({
+  tag: "content-carousel-slide",
+  props: {
+    /**
+     * @option
+     * @state
+     * Marks this as the currently shown slide. The parent
+     * `<content-carousel>` keeps exactly one slide active.
+     */
+    isActive: Boolean,
+  },
+});

package/content-carousel.ts

@@ -0,0 +1,218 @@
+import type { ContentCarouselSlide } from "./content-carousel-slide";
+import { ConstructorType, Neutron, TEvent } from "@excom/neutron";
+
+type T_HTMLContentCarouselSlideElement =
+  typeof ContentCarouselSlide.CustomElement;
+
+export type ContentCarouselSlideChangedDetail = {
+  activeSlide: HTMLElement | null;
+  previousSlide: HTMLElement | null;
+};
+
+export type ContentCarouselSlideChangedEvent = TEvent & {
+  type: "content-carousel-slide-changed";
+  detail: ContentCarouselSlideChangedDetail;
+};
+
+/** Position of a `<content-carousel>` among its own slides. */
+export interface ContentCarouselProvision {
+  /** Index of the active slide; `-1` when there are no slides. */
+  index: number;
+  /** Number of own slides (a nested carousel's slides are not counted). */
+  count: number;
+  /** Direction of the most recent move; `null` until the first move. */
+  lastMove: "forward" | "back" | null;
+}
+
+/**
+ * Rotates a set of slides — swipe-free, command-driven, auto-play optional.
+ * Nav buttons are plain `<button command="--next" commandfor="…">`; fires a
+ * change event other elements can react to.
+ *
+ * `.provision` holds the position (`{ index, count, lastMove }`) so a
+ * progress readout can bind to it with `prop("provision")`.
+ *
+ * @summary Slide rotator — auto-play, manual nav, slide or fade transition.
+ *
+ * @descendant content-carousel-slide - Slides to rotate through. The first,
+ *   or whichever has `is-active`, is shown initially.
+ *
+ * @command --back - Shows the previous slide (wraps to last). Stops
+ *   auto-play.
+ * @command --next - Shows the next slide (wraps to first). Stops auto-play.
+ *
+ * @fires content-carousel-slide-changed - After any slide change, manual or
+ *   auto.
+ * @type ContentCarouselSlideChangedEvent
+ *
+ * @example
+ * <content-carousel auto-play="5">
+ *   <content-carousel-slide is-active>One</content-carousel-slide>
+ *   <content-carousel-slide>Two</content-carousel-slide>
+ * </content-carousel>
+ */
+export const ContentCarousel = Neutron({
+  tag: "content-carousel",
+  props: {
+    /**
+     * @option
+     * Seconds between automatic slide advances. Unset disables auto-play.
+     */
+    autoPlay: Number,
+    /**
+     * @option
+     * Set when the element is being dragged. Used by CSS only to disable `transition`.
+     */
+    isScrubbing: Boolean,
+    /**
+     * @option
+     * Transition used when the active slide changes.
+     * @values slide | fade
+     * @default slide
+     */
+    slideAnimation: String,
+    /**
+     * @state
+     * Direction of the most recent slide change — drives the CSS
+     * animation direction.
+     * @values forward | back
+     */
+    lastMove: String,
+    /**
+     * @option
+     * @state
+     * 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.
+     */
+    autoPlayStopped: Boolean,
+    /**
+     * @provision
+     * 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.
+     * @type ContentCarouselProvision
+     */
+    provision: Object as unknown as ConstructorType<ContentCarouselProvision>,
+    // private state
+    autoPlayIntervalId: Object as unknown as ConstructorType<
+      ReturnType<typeof setInterval>
+    >,
+  },
+})
+  .defineMethods({
+    intervalCallback: () => ({ _move: [false, false] }),
+    /** Show the previous / next slide; a manual move stops auto-play. */
+    // `any`: `getActiveSlide` is declared in this same call (circular type)
+    _move: (element: any, isBack: boolean, isManual: boolean) => {
+      const { getActiveSlide, autoPlay } = element;
+      const activeSlide =
+        getActiveSlide() as T_HTMLContentCarouselSlideElement | null;
+      const nextSlide = findSlide(element, activeSlide, isBack);
+      nextSlide?.setAttribute?.("is-active", "");
+      activeSlide?.removeAttribute("is-active");
+      const lastMove = isBack ? "back" : "forward";
+      return {
+        lastMove,
+        ...(isManual && autoPlay ? { autoPlayStopped: true } : {}),
+        provision: readProvision(element, lastMove),
+        emit: [
+          "content-carousel-slide-changed",
+          { detail: { activeSlide: nextSlide, previousSlide: activeSlide } },
+        ] as any,
+      };
+    },
+    getActiveSlide: (element) => {
+      const slides = getOwnSlides(element);
+      return {
+        // Explicit type: inference hits a circular type issue here
+        returns: (slides.find((slide) => slide.hasAttribute("is-active")) ||
+          slides[0] ||
+          null) as unknown as T_HTMLContentCarouselSlideElement | null,
+      };
+    },
+    /** The current `{ index, count, lastMove }`, read from the DOM. */
+    _readProvision: (element) => ({
+      returns: readProvision(element, element.lastMove),
+    }),
+  })
+  .onConnected(({ _readProvision }) => ({
+    provision: _readProvision() as ContentCarouselProvision,
+  }))
+  .onPropChanged(
+    "autoPlay",
+    (
+      { autoPlay, autoPlayIntervalId, intervalCallback, autoPlayStopped },
+      previous
+    ) => {
+      if (previous.autoPlay && autoPlayIntervalId) {
+        clearInterval(autoPlayIntervalId);
+      }
+      return {
+        autoPlayIntervalId:
+          autoPlay && !autoPlayStopped
+            ? setInterval(intervalCallback, autoPlay * 1000)
+            : null,
+      };
+    }
+  )
+  .onDisconnected(
+    // A DOM move keeps the interval running; only a real removal stops auto-play
+    ({ autoPlay, isMoving }) =>
+      !isMoving &&
+      autoPlay && {
+        autoPlayStopped: true,
+      }
+  )
+  .onPropSet("autoPlayStopped", ({ autoPlayIntervalId }) => {
+    if (autoPlayIntervalId || autoPlayIntervalId === 0) {
+      clearInterval(autoPlayIntervalId);
+      return {
+        autoPlayIntervalId: null,
+      };
+    }
+  })
+  .onCommand("--back", () => ({ _move: [true, true] }))
+  .onCommand("--next", () => ({ _move: [false, true] }));
+
+/** A fresh provision object from the carousel's own slides. */
+function readProvision(
+  element: HTMLElement,
+  lastMove: string | null | undefined
+): ContentCarouselProvision {
+  const slides = getOwnSlides(element);
+  const active =
+    slides.find((slide) => slide.hasAttribute("is-active")) || slides[0];
+  return {
+    index: active ? slides.indexOf(active) : -1,
+    count: slides.length,
+    lastMove: lastMove === "forward" || lastMove === "back" ? lastMove : null,
+  };
+}
+
+/**
+ * Slides this carousel owns, in document order. A nested carousel keeps
+ * its own slides, excluded here the same way `<content-tabs>` scopes
+ * headers / bodies.
+ */
+function getOwnSlides(element: HTMLElement): HTMLElement[] {
+  return [...element.querySelectorAll("content-carousel-slide")].filter(
+    (slide) => slide.closest("content-carousel") === element
+  ) as HTMLElement[];
+}
+
+function findSlide(
+  element: HTMLElement,
+  currentSlide: T_HTMLContentCarouselSlideElement | null,
+  isPrevious: boolean
+): T_HTMLContentCarouselSlideElement | null {
+  if (!currentSlide) return null;
+  const slides = getOwnSlides(element);
+  const currentIndex = slides.indexOf(currentSlide as unknown as HTMLElement);
+  if (currentIndex < 0) return null;
+  const nextIndex =
+    (currentIndex + (isPrevious ? -1 : 1) + slides.length) % slides.length;
+  return slides[nextIndex] as unknown as T_HTMLContentCarouselSlideElement;
+}

package/index.css

@@ -0,0 +1,5 @@
+@import "./src/content-carousel.css";
+
+@layer {
+  @mixin module-content-carousel;
+}

package/index.ts

@@ -0,0 +1,24 @@
+import { ContentCarousel } from "./content-carousel";
+import { ContentCarouselSlide } from "./content-carousel-slide";
+
+ContentCarousel.define();
+ContentCarouselSlide.define();
+
+export { ContentCarousel, ContentCarouselSlide };
+
+type T_HTMLContentCarouselElement = typeof ContentCarousel.CustomElement;
+type T_HTMLContentCarouselSlideElement =
+  typeof ContentCarouselSlide.CustomElement;
+declare global {
+  interface HTMLContentCarouselElement extends T_HTMLContentCarouselElement {}
+  interface HTMLContentCarouselSlideElement extends T_HTMLContentCarouselSlideElement {}
+  interface Window {
+    HTMLContentCarouselElement: HTMLContentCarouselElement;
+    HTMLContentCarouselSlideElement: HTMLContentCarouselSlideElement;
+  }
+  interface HTMLElementTagNameMap {
+    "content-carousel": HTMLContentCarouselElement;
+    "content-carousel-slide": HTMLContentCarouselSlideElement;
+  }
+}
+export type { HTMLContentCarouselElement, HTMLContentCarouselSlideElement };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@excom/content-carousel",
+  "version": "0.1.0",
+  "description": "<content-carousel> custom element",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@excom/kit-utils": "^0.1.0",
+    "@excom/neutron": "^0.1.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/content-carousel"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/content-carousel/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "content-carousel",
+    "neutron",
+    "custom-elements"
+  ],
+  "excom": {
+    "packageType": "kit-element"
+  },
+  "scripts": {
+    "build": "node node_modules/@excom/heft-rig/scripts/vite-build.mjs",
+    "build:watch": "node node_modules/@excom/heft-rig/scripts/vite-build-watch.mjs",
+    "format": "node node_modules/@excom/heft-rig/scripts/format.mjs",
+    "test": "node node_modules/@excom/heft-rig/scripts/vitest.mjs",
+    "coverage": "node node_modules/@excom/heft-rig/scripts/coverage.mjs",
+    "dev": "node node_modules/@excom/heft-rig/scripts/vite-dev.mjs",
+    "preview": "node node_modules/@excom/heft-rig/scripts/vite-preview.mjs",
+    "build:package-metas": "node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs",
+    "build:docs": "node node_modules/@excom/heft-rig/scripts/build-docs.mjs"
+  }
+}

package/rush-logs/content-carousel.apply-exports.cache.log

@@ -0,0 +1 @@
+Caching has been disabled for this project's "apply-exports" command.

package/rush-logs/content-carousel.apply-exports.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/rush-logs/content-carousel.build_docs.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:docs" command, so caching has been disabled.

package/rush-logs/content-carousel.build_docs.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/rush-logs/content-carousel.build_package-metas.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:package-metas" command, so caching has been disabled.

package/rush-logs/content-carousel.build_package-metas.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/src/content-carousel.css

@@ -0,0 +1,239 @@
+/**
+ * Styles for `<content-carousel>`.
+ * @element content-carousel
+ */
+
+/* Aliases */
+@custom-selector :--content-carousel content-carousel, .tag-content-carousel;
+@custom-selector :--content-carousel--last-move [last-move], [data-last-move];
+@custom-selector :--content-carousel--last-move-forward [last-move="forward"], [data-last-move="forward"];
+@custom-selector :--content-carousel--last-move-back [last-move="back"], [data-last-move="back"];
+@custom-selector :--content-carousel--slide-animation [slide-animation], [data-slide-animation];
+@custom-selector :--content-carousel--slide-animation-slide [slide-animation="slide"], [data-slide-animation="slide"];
+@custom-selector :--content-carousel--slide-animation-fade [slide-animation="fade"], [data-slide-animation="fade"];
+@custom-selector :--content-carousel--slide-animation-track [slide-animation="track"], [data-slide-animation="track"];
+@custom-selector :--content-carousel--is-scrubbing [is-scrubbing], [data-scrubbing];
+@custom-selector :--content-carousel-slide content-carousel-slide, .tag-content-carousel-slide;
+@custom-selector :--content-carousel-slide--is-active [is-active], [aria-current];
+
+@define-mixin module-content-carousel {
+  :root {
+    /**
+     * Length of the slide / fade transition.
+     * @cssproperty
+     * @syntax <time>
+     * @default 0.25s
+     */
+    --content-carousel-slide-animation-duration: var(
+      --v-transition-duration-standard,
+      0.25s
+    );
+    /**
+     * Easing used for the fade transition.
+     * @cssproperty
+     * @syntax <easing-function>
+     * @default ease-out
+     */
+    --content-carousel-transition-ease: var(--v-transition-ease-out, ease-out);
+    /**
+     * Min-width of the nav buttons.
+     * @cssproperty
+     * @syntax <length>
+     * @default 25px
+     */
+    --content-carousel-button-size: 25px;
+  }
+
+  :--content-carousel {
+    /**
+     * `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.
+     * @cssproperty
+     * @syntax <number>
+     * @default 0
+     */
+    --content-carousel-progress: 0;
+    display: block;
+    position: relative;
+    overflow: hidden;
+    width: 100%;
+    height: auto;
+    white-space: nowrap;
+
+    > [rel="prev"],
+    .tag-content-carousel-prev,
+    > [rel="next"],
+    .tag-content-carousel-next {
+      position: absolute;
+      top: calc(50% - calc(var(--content-carousel-button-size) / 2));
+      min-width: var(--content-carousel-button-size);
+      z-index: 3;
+      text-align: center;
+      cursor: pointer;
+    }
+
+    /**
+     * Positions a direct child with `rel="prev"` (or
+     * `.tag-content-carousel-prev`) as the "previous slide" nav control.
+     * @cssclass tag-content-carousel-prev
+     */
+    > [rel="prev"],
+    .tag-content-carousel-prev {
+      left: 0;
+    }
+    /**
+     * Positions a direct child with `rel="next"` (or
+     * `.tag-content-carousel-next`) as the "next slide" nav control.
+     * @cssclass tag-content-carousel-next
+     */
+    > [rel="next"],
+    .tag-content-carousel-next {
+      right: 0;
+    }
+
+    :--content-carousel-slide {
+      position: absolute;
+      top: 0;
+      left: 0;
+      width: 100%;
+      height: auto;
+      display: block;
+    }
+
+    /* slide / default */
+    &:not(:--content-carousel--slide-animation),
+    &:--content-carousel--slide-animation-slide {
+      :--content-carousel-slide {
+        animation-duration: var(--content-carousel-slide-animation-duration);
+        animation-fill-mode: forwards;
+        z-index: -1;
+      }
+      /* Initial state. No animation. */
+      &:not(:--content-carousel--last-move) :--content-carousel-slide {
+        &:--content-carousel-slide--is-active {
+          transform: translateX(0);
+          z-index: 2;
+        }
+        &:not(:--content-carousel-slide--is-active) {
+          opacity: 0;
+          z-index: 1;
+        }
+      }
+      &:--content-carousel--last-move-forward :--content-carousel-slide {
+        &:--content-carousel-slide--is-active {
+          animation-name: right-to-center;
+          z-index: 2;
+        }
+        &:not(:--content-carousel-slide--is-active):has(
+            + :--content-carousel-slide--is-active
+          ),
+        &:first-of-type:--content-carousel-slide--is-active ~ :last-of-type {
+          animation-name: center-to-left;
+          z-index: 1;
+        }
+      }
+      &:--content-carousel--last-move-back :--content-carousel-slide {
+        &:--content-carousel-slide--is-active {
+          animation-name: left-to-center;
+          z-index: 2;
+        }
+        &:--content-carousel-slide--is-active
+          + :not(:--content-carousel-slide--is-active),
+        &:first-of-type:not(:--content-carousel-slide--is-active):has(
+            ~ :last-of-type:--content-carousel-slide--is-active
+          ) {
+          animation-name: center-to-right;
+          z-index: 1;
+        }
+      }
+    }
+
+    /* fade */
+    &:--content-carousel--slide-animation-fade {
+      :--content-carousel-slide {
+        opacity: 0;
+        z-index: 1;
+        transition: opacity var(--content-carousel-transition-ease);
+        transition-duration: var(--content-carousel-slide-animation-duration);
+        &:--content-carousel-slide--is-active {
+          opacity: 1;
+          z-index: 2;
+        }
+        &:not(:--content-carousel-slide--is-active) {
+          opacity: 0;
+          z-index: 1;
+        }
+      }
+    }
+
+    /* track: the active slide sits at 0, neighbours at ±100%, all shifted by
+       `--content-carousel-progress`. Transitions animate a slide change;
+       none while `is-scrubbing`, when a finger drives the offset. */
+    &:--content-carousel--slide-animation-track {
+      :--content-carousel-slide {
+        --content-carousel-slot: 1;
+        transform: translateX(
+          calc(
+            (var(--content-carousel-slot) - var(--content-carousel-progress)) *
+              100%
+          )
+        );
+        transition: transform var(--content-carousel-slide-animation-duration)
+          var(--content-carousel-transition-ease);
+        &:--content-carousel-slide--is-active {
+          --content-carousel-slot: 0;
+          z-index: 2;
+        }
+        &:has(~ :--content-carousel-slide--is-active) {
+          --content-carousel-slot: -1;
+        }
+        &:is(&:--content-carousel-slide--is-active + & + &),
+        &:has(+ & + &:--content-carousel-slide--is-active) {
+          /* hide slides that are two slides away */
+          display: none !important;
+        }
+      }
+      &:--content-carousel--is-scrubbing {
+        --content-carousel-progress: var(--gesture-progress, 0);
+        :--content-carousel-slide {
+          transition: none;
+        }
+      }
+    }
+  }
+
+  @keyframes right-to-center {
+    0% {
+      transform: translateX(100%);
+    }
+    100% {
+      transform: translateX(0);
+    }
+  }
+  @keyframes center-to-left {
+    0% {
+      transform: translateX(0);
+    }
+    100% {
+      transform: translateX(-100%);
+    }
+  }
+  @keyframes left-to-center {
+    0% {
+      transform: translateX(-100%);
+    }
+    100% {
+      transform: translateX(0);
+    }
+  }
+  @keyframes center-to-right {
+    0% {
+      transform: translateX(0);
+    }
+    100% {
+      transform: translateX(100%);
+    }
+  }
+}