@zeitonline/zon-carousel
v1.0.2
Published
Accessible <zon-carousel> web component with light-DOM slides, controls, dots and autoplay support. Single source of truth for the ZEIT Online carousel.
Downloads
1,051
Maintainers
Readme
@zeitonline/zon-carousel
Accessible <zon-carousel> web component for ZEIT Online. A dependency-free custom
element that progressively enhances server-rendered markup with direction buttons, dot
controls, autoplay and a gallery pager, following the
ARIA APG carousel pattern.
The DOM, CSS and event contract is versioned in CONTRACT.md — read it
before changing anything consumers rely on.
Install
npm install @zeitonline/zon-carouselPeer dependency: @zeitonline/design-system
(>=0.4.0 <1), which provides the --z-ds-* tokens the styles use.
Usage
Importing the package registers the element (guarded, safe to import twice):
import '@zeitonline/zon-carousel';The import does not load CSS. Use either the compiled stylesheet or the SCSS source:
import '@zeitonline/zon-carousel/styles.css';// needs the node package importer (dart-sass ≥ 1.71, `--pkg-importer=node`)
@use 'pkg:@zeitonline/zon-carousel/styles.scss';
// or, with a plain load path
@use '../node_modules/@zeitonline/zon-carousel/src/zon-carousel';Markup requires a .zon-carousel__scroll-container; its direct children become slides
(wrapped in .zon-carousel__slide unless already wrapped). Canonical markup per variant
is in tests/fixtures/.
<zon-carousel>
<div class="zon-carousel__scroll-container">
<a href="/a">Slide 1</a>
<a href="/b">Slide 2</a>
<a href="/c">Slide 3</a>
</div>
</zon-carousel>Load the JS and CSS once per page, from the page that embeds the carousel. HTML/ESI fragments must not ship their own copy: double registration is guarded, duplicate CSS is not.
Attributes
| Attribute | Effect |
| ------------------- | -------------------------------------------------------------------------- |
| wrapping | Loop navigation around at the first/last slide |
| autoplay | Auto-advance with a play/pause control (paused on hover/focus) |
| view-mode | continuous advances two at a time and omits dots; single is full-width |
| variant | kiosk, shop, merkl, gallery styling/behaviour variants |
| overlay-controls | Render direction buttons over the slides |
| slide-description | Label noun for slides (default Seite) |
Events (scrolled, autoplay-started, inbound scaling_ready) and the JS-generated
classes are documented in CONTRACT.md.
Development
Run nvm use first (.nvmrc is the Node version for development and CI;
engines is the looser floor for consumers).
npm install # also builds via the prepare hook
npm run dev # rebuild dist/ on change
npm run demo # interactive demo for manual visual checks
npm run test:install # one-time: install the Playwright browser
npm test # Playwright contract tests, smoke test, tarball contents
npm run format # PrettierSources: src/zon-carousel.js and src/zon-carousel.scss. The src/_*.scss partials
are vendored helpers — re-sync them, don't edit locally (CONTRACT.md §5).
Demo
demo/index.html renders the carousel with real zeit.web CSS and markup, committed under
demo/vendor/ and demo/partials/ so it runs without a zeit.web checkout. With a
checkout ($ZEITWEB_PATH or ../zeit.web) the dev server recompiles live.
npm run demo:sync # refresh styles and markup from zeit.web
npm run demo:sync-styles # styles only (`-- --check` to verify, as CI does)
npm run demo:sync-markup # markup onlydemo/vendor/ is generated — never edit it; review PROVENANCE.json instead.
demo/poster.html loads the package in isolation. src/poster.css and
src/audio-player.js are demo-only and not published.
Testing in a consumer
npm link ../zon-carousel --no-save # run in the consumer
npm run dev # run here; consumers import dist/Any npm install in the consumer removes the link. Use npm pack to test the exact
published tarball.
Releasing
- Merge PRs with a Conventional Commits title:
fix:→ patch,feat:→ minor,feat!:→ major. Any change toCONTRACT.mdis a major. - release-please keeps a release PR open; merging it bumps the version, updates
CHANGELOG.md, tags a release and publishes to npm via trusted publishing (no secrets), gated on the tests. - Renovate opens bump PRs in consumers. Recommended rule:
{
"matchPackageNames": ["@zeitonline/zon-carousel"],
"matchUpdateTypes": ["minor", "patch"],
"groupName": "zon-carousel",
"schedule": ["at any time"],
"minimumReleaseAge": null,
"automerge": true
}