491 lines
24 KiB
Plaintext
491 lines
24 KiB
Plaintext
page Carouselcomponent {
|
|
seo {
|
|
title = "Carousel component"
|
|
description = "Theme-aware, responsive carousel component."
|
|
}
|
|
|
|
view {
|
|
<div class="docs-shell">
|
|
<SkipLink label="Skip to content" href="#main" class="docs-skip-link" />
|
|
<header class="topbar">
|
|
<a class="brand" href="/"><span>W</span> WRNexusJS</a>
|
|
<nav aria-label="Primary"><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="/components">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a></nav>
|
|
<div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.5.0</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div>
|
|
</header>
|
|
<div class="mobile-doc-nav"><details><summary>Browse documentation</summary><nav><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="/components">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a><a href="/tutorial">Tutorial</a><a href="/guides/project-structure">Guides</a><a href="/examples">Examples</a><a href="/search">Search</a></nav></details></div>
|
|
<main class="portal-main docs-layout component-detail-page"><article id="main" class="documentation prose standalone"><nav class="breadcrumbs" aria-label="Breadcrumb"><a href="/">Home</a><span>/</span><a href="/components">Components</a><span>/</span><span aria-current="page">Carousel</span></nav><section class="doc-intro"><span class="eyebrow">base component</span><h1>Carousel</h1><p>Theme-aware, responsive carousel component.</p><div class="doc-meta"><span>@wrnexus/ui 0.5.0</span><span>22 props</span><span>1 slots</span><span>10 events</span></div></section><section id="usage"><h2>Usage</h2><p>Components are auto-discovered. Use the component directly in any <code>.wrn</code> view:</p><pre data-language="wrn"><code><Carousel
|
|
size="default"
|
|
color="primary"
|
|
title="title"
|
|
description="description"
|
|
items="[]"
|
|
/></code></pre><p>Legacy mount name: <code>data-component="Carousel"</code>.</p></section><section id="props"><h2>Props and attributes</h2><div class="table-wrap"><table><thead><tr><th>Prop</th><th>Type</th><th>Requirement</th><th>Default</th></tr></thead><tbody><tr><td><code>size</code></td><td><code>string</code></td><td>Optional</td><td><code>"default"</code></td></tr><tr><td><code>color</code></td><td><code>string</code></td><td>Optional</td><td><code>"primary"</code></td></tr><tr><td><code>title</code></td><td><code>string</code></td><td>Optional</td><td><code>""</code></td></tr><tr><td><code>description</code></td><td><code>string</code></td><td>Optional</td><td><code>""</code></td></tr><tr><td><code>items</code></td><td><code>string</code></td><td>Optional</td><td><code>[]</code></td></tr><tr><td><code>activeIndex</code></td><td><code>number</code></td><td>Optional</td><td><code>0</code></td></tr><tr><td><code>slidesPerView</code></td><td><code>number</code></td><td>Optional</td><td><code>1</code></td></tr><tr><td><code>gap</code></td><td><code>string</code></td><td>Optional</td><td><code>"0.75rem"</code></td></tr><tr><td><code>showPagination</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>isAutoPlay</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>autoplayInterval</code></td><td><code>number</code></td><td>Optional</td><td><code>4000</code></td></tr><tr><td><code>isInfiniteLoop</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>isRTL</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>isCentered</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>isDraggable</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>isAutoHeight</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>isSnap</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>showCounter</code></td><td><code>boolean</code></td><td>Optional</td><td><code>false</code></td></tr><tr><td><code>thumbnails</code></td><td><code>string</code></td><td>Optional</td><td><code>"none"</code></td></tr><tr><td><code>ariaLabel</code></td><td><code>string</code></td><td>Optional</td><td><code>"Content carousel"</code></td></tr><tr><td><code>variant</code></td><td><code>string</code></td><td>Optional</td><td><code>"default"</code></td></tr><tr><td><code>class</code></td><td><code>string</code></td><td>Optional</td><td><code>""</code></td></tr></tbody></table></div></section><section id="slots"><h2>Slots</h2><ul><li><code>default</code></li></ul></section><section id="events"><h2>Events</h2><ul><li><code>initialize</code></li><li><code>change</code></li><li><code>previous</code></li><li><code>next</code></li><li><code>play</code></li><li><code>pause</code></li><li><code>reachStart</code></li><li><code>reachEnd</code></li><li><code>dragStart</code></li><li><code>dragEnd</code></li></ul></section><section id="source"><h2>Source contract</h2><p>Installed source: <code>components/carousel.wrn</code></p><pre data-language="wrn"><code>// Interactive, hydration-safe content carousel.
|
|
component Carousel {
|
|
props {
|
|
@event initialize = function
|
|
@event change = function
|
|
@event previous = function
|
|
@event next = function
|
|
@event play = function
|
|
@event pause = function
|
|
@event reachStart = function
|
|
@event reachEnd = function
|
|
@event dragStart = function
|
|
@event dragEnd = function
|
|
size = "default"
|
|
color = "primary"
|
|
title = ""
|
|
description = ""
|
|
items = []
|
|
activeIndex = 0
|
|
slidesPerView = 1
|
|
gap = "0.75rem"
|
|
showPagination = false
|
|
isAutoPlay = false
|
|
autoplayInterval = 4000
|
|
isInfiniteLoop = false
|
|
isRTL = false
|
|
isCentered = false
|
|
isDraggable = false
|
|
isAutoHeight = false
|
|
isSnap = false
|
|
showCounter = false
|
|
thumbnails = "none"
|
|
ariaLabel = "Content carousel"
|
|
variant = "default"
|
|
class = ""
|
|
}
|
|
|
|
state currentIndex = activeIndex
|
|
state playing = false
|
|
state dragOrigin = null
|
|
state dragOffset = 0
|
|
state autoplayTimer = null
|
|
state carouselRoot = null
|
|
|
|
functions {
|
|
function slideCount() {
|
|
return items.length
|
|
}
|
|
|
|
function maximumIndex(count, visible) {
|
|
count = slideCount()
|
|
visible = Math.max(1, Number(slidesPerView) || 1)
|
|
if (isCentered || isSnap) {
|
|
return Math.max(0, count - 1)
|
|
}
|
|
return Math.max(0, count - visible)
|
|
}
|
|
|
|
function normalizedIndex(index, maximum) {
|
|
maximum = maximumIndex()
|
|
if (slideCount() === 0) {
|
|
return 0
|
|
}
|
|
if (isInfiniteLoop) {
|
|
if (index < 0) {
|
|
return maximum
|
|
}
|
|
if (index > maximum) {
|
|
return 0
|
|
}
|
|
}
|
|
return Math.max(0, Math.min(index, maximum))
|
|
}
|
|
|
|
function rememberRoot(sourceEvent, root) {
|
|
if (!sourceEvent || !sourceEvent.currentTarget) {
|
|
return
|
|
}
|
|
root = sourceEvent.currentTarget.closest(".wire-next--carousel")
|
|
if (root) {
|
|
carouselRoot = root
|
|
}
|
|
}
|
|
|
|
function syncNavigation(sourceEvent, index, root, viewport, slides, slide, thumbnails, thumbnail, rail) {
|
|
rememberRoot(sourceEvent)
|
|
root = carouselRoot
|
|
if (!root) {
|
|
return
|
|
}
|
|
if (isSnap) {
|
|
viewport = root.querySelector(".wire-next__carousel-viewport")
|
|
slides = root.querySelectorAll(".wire-next__carousel-slide")
|
|
slide = slides[index]
|
|
if (viewport && slide) {
|
|
viewport.scrollTo({
|
|
left: slide.offsetLeft - (viewport.clientWidth - slide.clientWidth) / 2,
|
|
behavior: "smooth"
|
|
})
|
|
}
|
|
}
|
|
thumbnails = root.querySelectorAll(".wire-next__carousel-thumbnails button")
|
|
if (thumbnails[index]) {
|
|
thumbnail = thumbnails[index]
|
|
rail = thumbnail.parentElement
|
|
rail.scrollTo({
|
|
left: thumbnail.offsetLeft - (rail.clientWidth - thumbnail.clientWidth) / 2,
|
|
top: thumbnail.offsetTop - (rail.clientHeight - thumbnail.clientHeight) / 2,
|
|
behavior: "smooth"
|
|
})
|
|
}
|
|
}
|
|
|
|
function handleSnapScroll(sourceEvent, slides, viewport, viewportCenter, closestIndex, closestDistance, slide, slideCenter, distance, previousIndex) {
|
|
if (!isSnap) {
|
|
return
|
|
}
|
|
rememberRoot(sourceEvent)
|
|
viewport = sourceEvent.currentTarget
|
|
slides = viewport.querySelectorAll(".wire-next__carousel-slide")
|
|
viewportCenter = viewport.scrollLeft + viewport.clientWidth / 2
|
|
closestIndex = currentIndex
|
|
closestDistance = 1000000000
|
|
slides.forEach(function (candidate, index) {
|
|
slideCenter = candidate.offsetLeft + candidate.clientWidth / 2
|
|
distance = Math.abs(slideCenter - viewportCenter)
|
|
if (distance < closestDistance) {
|
|
closestDistance = distance
|
|
closestIndex = index
|
|
}
|
|
})
|
|
closestIndex = normalizedIndex(closestIndex)
|
|
if (closestIndex !== currentIndex) {
|
|
previousIndex = currentIndex
|
|
currentIndex = closestIndex
|
|
$emit("change", {
|
|
index: currentIndex,
|
|
previousIndex: previousIndex,
|
|
item: items[currentIndex],
|
|
reason: "snap"
|
|
})
|
|
slides = carouselRoot.querySelectorAll(".wire-next__carousel-thumbnails button")
|
|
slide = slides[currentIndex]
|
|
if (slide) {
|
|
viewport = slide.parentElement
|
|
viewport.scrollTo({
|
|
left: slide.offsetLeft - (viewport.clientWidth - slide.clientWidth) / 2,
|
|
top: slide.offsetTop - (viewport.clientHeight - slide.clientHeight) / 2,
|
|
behavior: "smooth"
|
|
})
|
|
}
|
|
}
|
|
}
|
|
|
|
function selectSlide(index, reason, sourceEvent, previousIndex) {
|
|
if (slideCount() === 0) {
|
|
return
|
|
}
|
|
previousIndex = currentIndex
|
|
currentIndex = normalizedIndex(Number(index))
|
|
syncNavigation(sourceEvent, currentIndex)
|
|
if (previousIndex === currentIndex && reason !== "initialize") {
|
|
return
|
|
}
|
|
$emit("change", {
|
|
index: currentIndex,
|
|
previousIndex: previousIndex,
|
|
item: items[currentIndex],
|
|
reason: reason || "select"
|
|
})
|
|
if (currentIndex === 0) {
|
|
$emit("reachStart", { index: currentIndex })
|
|
}
|
|
if (currentIndex === maximumIndex()) {
|
|
$emit("reachEnd", { index: currentIndex })
|
|
}
|
|
}
|
|
|
|
function previousSlide(sourceEvent, previousIndex) {
|
|
previousIndex = currentIndex
|
|
selectSlide(currentIndex - 1, "previous", sourceEvent)
|
|
$emit("previous", {
|
|
index: currentIndex,
|
|
previousIndex: previousIndex,
|
|
item: items[currentIndex]
|
|
})
|
|
}
|
|
|
|
function nextSlide(sourceEvent, previousIndex) {
|
|
previousIndex = currentIndex
|
|
selectSlide(currentIndex + 1, "next", sourceEvent)
|
|
$emit("next", {
|
|
index: currentIndex,
|
|
previousIndex: previousIndex,
|
|
item: items[currentIndex]
|
|
})
|
|
}
|
|
|
|
function handleKeydown(sourceEvent) {
|
|
if (sourceEvent.key === "ArrowLeft") {
|
|
sourceEvent.preventDefault()
|
|
if (isRTL) {
|
|
nextSlide(sourceEvent)
|
|
} else {
|
|
previousSlide(sourceEvent)
|
|
}
|
|
}
|
|
if (sourceEvent.key === "ArrowRight") {
|
|
sourceEvent.preventDefault()
|
|
if (isRTL) {
|
|
previousSlide(sourceEvent)
|
|
} else {
|
|
nextSlide(sourceEvent)
|
|
}
|
|
}
|
|
if (sourceEvent.key === "Home") {
|
|
sourceEvent.preventDefault()
|
|
selectSlide(0, "keyboard", sourceEvent)
|
|
}
|
|
if (sourceEvent.key === "End") {
|
|
sourceEvent.preventDefault()
|
|
selectSlide(maximumIndex(), "keyboard", sourceEvent)
|
|
}
|
|
}
|
|
|
|
function beginDrag(sourceEvent) {
|
|
if (!isDraggable || isSnap) {
|
|
return
|
|
}
|
|
sourceEvent.preventDefault()
|
|
dragOrigin = sourceEvent.clientX
|
|
dragOffset = 0
|
|
sourceEvent.currentTarget.setPointerCapture(sourceEvent.pointerId)
|
|
$emit("dragStart", { index: currentIndex, x: dragOrigin })
|
|
}
|
|
|
|
function moveDrag(sourceEvent) {
|
|
if (!isDraggable || isSnap || dragOrigin === null) {
|
|
return
|
|
}
|
|
sourceEvent.preventDefault()
|
|
dragOffset = sourceEvent.clientX - dragOrigin
|
|
}
|
|
|
|
function cancelDrag() {
|
|
dragOrigin = null
|
|
dragOffset = 0
|
|
}
|
|
|
|
function endDrag(sourceEvent, distance) {
|
|
if (!isDraggable || isSnap || dragOrigin === null) {
|
|
return
|
|
}
|
|
sourceEvent.preventDefault()
|
|
distance = dragOffset || sourceEvent.clientX - dragOrigin
|
|
dragOrigin = null
|
|
dragOffset = 0
|
|
if (Math.abs(distance) > 20) {
|
|
if ((distance < 0 && !isRTL) || (distance > 0 && isRTL)) {
|
|
nextSlide(sourceEvent)
|
|
} else {
|
|
previousSlide(sourceEvent)
|
|
}
|
|
}
|
|
$emit("dragEnd", {
|
|
index: currentIndex,
|
|
distance: distance
|
|
})
|
|
}
|
|
|
|
function advanceAutoplay() {
|
|
if (currentIndex >= maximumIndex()) {
|
|
selectSlide(0, "autoplay")
|
|
} else {
|
|
selectSlide(currentIndex + 1, "autoplay")
|
|
}
|
|
}
|
|
|
|
function startAutoplay() {
|
|
if (!isAutoPlay || playing || slideCount() < 2) {
|
|
return
|
|
}
|
|
playing = true
|
|
autoplayTimer = setInterval(advanceAutoplay, Math.max(1000, Number(autoplayInterval)))
|
|
$emit("play", { index: currentIndex, interval: autoplayInterval })
|
|
}
|
|
|
|
function pauseAutoplay() {
|
|
if (autoplayTimer) {
|
|
clearInterval(autoplayTimer)
|
|
}
|
|
autoplayTimer = null
|
|
if (playing) {
|
|
$emit("pause", { index: currentIndex })
|
|
}
|
|
playing = false
|
|
}
|
|
|
|
}
|
|
|
|
lifecycle {
|
|
mount {
|
|
$emit("initialize", { index: currentIndex, count: slideCount() })
|
|
startAutoplay()
|
|
}
|
|
unmount {
|
|
if (autoplayTimer) {
|
|
clearInterval(autoplayTimer)
|
|
}
|
|
}
|
|
}
|
|
|
|
view {
|
|
<section
|
|
{...attrs}
|
|
class="wire-next wire-next--carousel wire-next--color-{color} wire-next--size-{size} wire-next--variant-{variant} {class}"
|
|
data-rtl="{isRTL}"
|
|
data-centered="{isCentered}"
|
|
data-draggable="{isDraggable && !isSnap}"
|
|
data-dragging="{dragOrigin !== null}"
|
|
data-auto-height="{isAutoHeight}"
|
|
data-snap="{isSnap}"
|
|
data-thumbnails="{thumbnails}"
|
|
dir="{isRTL ? 'rtl' : 'ltr'}"
|
|
role="region"
|
|
aria-roledescription="carousel"
|
|
aria-label="{ariaLabel}"
|
|
@keydown="handleKeydown(event)"
|
|
@mouseenter="rememberRoot(event); pauseAutoplay()"
|
|
@mouseleave="startAutoplay()"
|
|
@focusin="rememberRoot(event); pauseAutoplay()"
|
|
@focusout="startAutoplay()"
|
|
>
|
|
{#if title || description}
|
|
<header class="wire-next__carousel-header">
|
|
{#if title}<h3>{title}</h3>{/if}
|
|
{#if description}<p>{description}</p>{/if}
|
|
</header>
|
|
{/if}
|
|
|
|
<div class="wire-next__carousel-layout">
|
|
{#if thumbnails === "vertical"}
|
|
<div class="wire-next__carousel-thumbnails" aria-label="Choose a slide">
|
|
{#each items as item, index}
|
|
<button
|
|
type="button"
|
|
data-active="{index === currentIndex}"
|
|
aria-label="Show slide {index + 1}: {item.label || item.title}"
|
|
aria-current="{index === currentIndex ? 'true' : 'false'}"
|
|
@click="selectSlide(index, 'thumbnail', event)"
|
|
>
|
|
{#if item.thumbnail}<img src="{item.thumbnail}" alt="" />{/if}
|
|
<span>{item.label || item.title || "Slide " + (index + 1)}</span>
|
|
</button>
|
|
{/each}
|
|
</div>
|
|
{/if}
|
|
|
|
<div class="wire-next__carousel-main">
|
|
<div class="wire-next__carousel-stage">
|
|
<div
|
|
class="wire-next__carousel-viewport"
|
|
tabindex="0"
|
|
@scroll="handleSnapScroll(event)"
|
|
@pointerdown="beginDrag(event)"
|
|
@pointermove="moveDrag(event)"
|
|
@pointerup="endDrag(event)"
|
|
@pointercancel="cancelDrag()"
|
|
@lostpointercapture="cancelDrag()"
|
|
>
|
|
<div
|
|
class="wire-next__carousel-track"
|
|
style="--wire-carousel-index: {currentIndex}; --wire-carousel-per-view: {slidesPerView}; --wire-carousel-gap: {gap}; --wire-carousel-drag-offset: {dragOffset}px"
|
|
>
|
|
{#each items as item, index}
|
|
<article
|
|
class="wire-next__carousel-slide"
|
|
data-active="{index === currentIndex}"
|
|
role="group"
|
|
aria-roledescription="slide"
|
|
aria-label="{index + 1} of {items.length}"
|
|
aria-hidden="{index === currentIndex ? 'false' : 'true'}"
|
|
>
|
|
{#if item.imageSrc}
|
|
<img src="{item.imageSrc}" alt="{item.imageAlt || item.title || ''}" />
|
|
{/if}
|
|
<div class="wire-next__carousel-slide-content">
|
|
{#if item.eyebrow}<span>{item.eyebrow}</span>{/if}
|
|
{#if item.title || item.label}<h4>{item.title || item.label}</h4>{/if}
|
|
{#if item.description}<p>{item.description}</p>{/if}
|
|
{#if item.actionLabel}
|
|
<a href="{item.actionHref || '#'}">{item.actionLabel}</a>
|
|
{/if}
|
|
</div>
|
|
</article>
|
|
{/each}
|
|
<slot />
|
|
</div>
|
|
</div>
|
|
<button
|
|
class="wire-next__carousel-control wire-next__carousel-control--previous"
|
|
type="button"
|
|
aria-label="Previous slide"
|
|
disabled="{!isInfiniteLoop && currentIndex === 0}"
|
|
@click="previousSlide(event)"
|
|
>
|
|
<span class="icon-[lucide--chevron-left]" aria-hidden="true">
|
|
</span>
|
|
</button>
|
|
<button
|
|
class="wire-next__carousel-control wire-next__carousel-control--next"
|
|
type="button"
|
|
aria-label="Next slide"
|
|
disabled="{!isInfiniteLoop && currentIndex === maximumIndex()}"
|
|
@click="nextSlide(event)"
|
|
>
|
|
<span class="icon-[lucide--chevron-right]" aria-hidden="true">
|
|
</span>
|
|
</button>
|
|
|
|
{#if showCounter}
|
|
<output class="wire-next__carousel-counter" aria-live="polite">
|
|
{currentIndex + 1} / {items.length}
|
|
</output>
|
|
{/if}
|
|
</div>
|
|
|
|
{#if showPagination}
|
|
<div class="wire-next__carousel-pagination" aria-label="Choose a slide">
|
|
{#each items as item, index}
|
|
<button
|
|
type="button"
|
|
data-active="{index === currentIndex}"
|
|
aria-label="Show slide {index + 1}"
|
|
aria-current="{index === currentIndex ? 'true' : 'false'}"
|
|
@click="selectSlide(index, 'pagination', event)"
|
|
>
|
|
</button>
|
|
{/each}
|
|
</div>
|
|
{/if}
|
|
|
|
{#if thumbnails === "horizontal"}
|
|
<div class="wire-next__carousel-thumbnails" aria-label="Choose a slide">
|
|
{#each items as item, index}
|
|
<button
|
|
type="button"
|
|
data-active="{index === currentIndex}"
|
|
aria-label="Show slide {index + 1}: {item.label || item.title}"
|
|
aria-current="{index === currentIndex ? 'true' : 'false'}"
|
|
@click="selectSlide(index, 'thumbnail', event)"
|
|
>
|
|
{#if item.thumbnail}<img src="{item.thumbnail}" alt="" />{/if}
|
|
<span>{item.label || item.title || "Slide " + (index + 1)}</span>
|
|
</button>
|
|
{/each}
|
|
</div>
|
|
{/if}
|
|
</div>
|
|
</div>
|
|
</section>
|
|
}
|
|
}
|
|
</code></pre></section></article><aside class="on-this-page"><h2>On this page</h2><nav><a href="#usage">Usage</a><a href="#props">Props and attributes</a><a href="#slots">Slots</a><a href="#events">Events</a><a href="#source">Source contract</a></nav></aside></main>
|
|
<footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.5.0</strong><span>Complete API documentation generated from installed package declarations.</span></p></div><nav aria-label="Footer"><a href="/packages">All packages</a><a href="/getting-started">Get started</a><a href="/security">Security</a><a href="/support">Support</a><a href="/llms.txt">AI guide</a></nav><p class="footer-meta">Private Developer Preview · Bun-native</p></footer>
|
|
<BackToTop />
|
|
</div>
|
|
}
|
|
}
|