npm - @nordwerk/scroll-carousel - Versions diffs - 0.1.1 → 0.1.3 - Mend

@nordwerk/scroll-carousel 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/AGENTS.md CHANGED Viewed

@@ -39,6 +39,18 @@ JavaScript, never move slides with transforms, never clone slides.
 9. Text: pass `labels` for dots and the live region in the page's language, and give the arrow
    buttons their own `aria-label`s ("Previous products", "Next products").
 10. Do not add `disabled` to the arrows yourself; the script manages `aria-disabled`.
+11. Tailwind CSS: `@import "@nordwerk/scroll-carousel/carousel.css" layer(components);`, layout as
+    arbitrary properties (`[--sc-per-view:2]`, `@3xl:[--sc-per-view:4]` on `.sc-track`), own
+    controls styled from the state attributes (`group-data-[sc-overflow]/row:grid`,
+    `aria-disabled:opacity-30`). Copyable example: the `#tailwind` section of the docs site.
+12. Next.js App Router: import `<Carousel>` from `@nordwerk/scroll-carousel/react` in a Server
+    Component as is; the entry carries `'use client'`.
+13. shadcn/ui projects: `npx shadcn@latest add studio-nordwerk/scroll-carousel/scroll-carousel`, or a
+    block (`product-row`, `brand-teasers`, `hero-autoplay`, `image-gallery`, `logo-belt`). Compose
+    `ScrollCarousel` > `ScrollCarouselContent` > `ScrollCarouselItem`, with `ScrollCarouselPrevious`,
+    `ScrollCarouselNext`, `ScrollCarouselDots` and `ScrollCarouselPlay` inside `ScrollCarousel`;
+    layout as custom properties on the content. Pass plugins made outside the component, and mark
+    the file `"use client"` when it creates them.
 ### Recipes (CSS on the root or track, options in attach)
@@ -77,11 +89,23 @@ JavaScript, never move slides with transforms, never clone slides.
 - `src/adapter.ts`: the React and Preact adapter, written once against a small `Framework`
   interface; `src/react.ts` and `src/preact.ts` only bind it.
 - `src/astro/Carousel.astro`: shipped as source.
-- `src/carousel.css`: all layout and the default controls.
+- `src/carousel.css`: all layout and the default controls. The build also writes
+  `carousel.layer.css`, the same rules inside Tailwind's components layer.
+- `registry.json` and `registry/`: the shadcn registry, read by the shadcn CLI straight from this
+  public repository (`studio-nordwerk/scroll-carousel/<item>`). `registry/ui` is the component,
+  `registry/blocks` the blocks, `registry/shims` stand-ins that only exist for the type check.
+  `node scripts/shadcn-smoke.mjs` installs everything into a fresh shadcn project, builds and
+  renders it; CI runs it on every push.
 - `site/`: the documentation site (`generate.mjs` writes `_site/`), including the wireframe
   patterns in `wireframes.mjs`. Content there is fictional. CI publishes it to GitHub Pages;
   www.nordwerk.studio/oss/scroll-carousel serves the same files through a proxy that rewrites
-  `<base href>`, so every link in the site must stay relative to `<base>`.
+  `<base href>`, so every link in the site must stay relative to `<base>`. The proxy also puts the
+  studio site's own header and footer in place of `<!--nw:header-->` (first child of `.sheet`)
+  and `<!--nw:footer-->` (right after `.sheet`); keep both, keep `<html lang="en">` and `<body>`
+  free of other attributes, keep `data-hero` on the introduction, and never style the studio's
+  class names (band, pill, brand, brand-mark, links, link, cta, foot, grid, brand-col, tag, label,
+  base) or set `--wrap` in the site CSS. Locally and on GitHub Pages the site has no header or
+  footer.
 - `test/unit/`: node's test runner on the TypeScript sources.
 - `test/e2e/`: Playwright against `_site/` and the adapter fixtures from `scripts/fixtures.mjs`.

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,21 @@
 # Changelog
+## 0.1.3 (2026-09-22)
+- `carousel.layer.css`: the stylesheet inside Tailwind's components layer, with Tailwind's layer
+  order declared, so utilities override it and preflight never does, whatever the load order.
+- shadcn/ui registry in the repository: the `scroll-carousel` component (the structure of shadcn's
+  Carousel, on native scrolling) and five blocks, `product-row`, `brand-teasers`,
+  `hero-autoplay`, `image-gallery` and `logo-belt`. Install with
+  `npx shadcn@latest add studio-nordwerk/scroll-carousel/<item>`.
+## 0.1.2 (2026-09-22)
+- React entry marked `'use client'`: `<Carousel>` now works in Next.js App Router Server
+  Components (it failed to prerender before, as the hooks are not available on the server).
+- Documentation: a copy-and-paste Tailwind CSS v4 example with a live preview compiled by
+  Tailwind, and notes for Tailwind and Next.js.
 ## 0.1.1 (2026-09-21)
 - Astro and `templateLabels`: `statusSingle` template for when only one slide is visible, so a

package/README.md CHANGED Viewed

@@ -102,6 +102,53 @@ import Carousel from '@nordwerk/scroll-carousel/astro';
 Slides go in the default slot, one element each. Drag and autoplay are loaded only on pages that
 use them. Labels take templates: `labels={{ page: 'Slide {n} of {count}' }}`.
+### Tailwind CSS
+Import the stylesheet into the components layer, so utilities on your markup can override it, and
+set the layout with arbitrary properties and container-query variants:
+```css
+@import "tailwindcss";
+@import "@nordwerk/scroll-carousel/carousel.css" layer(components);
+```
+```html
+<div class="sc group/row relative [--sc-gap:1rem]">
+  <ul data-sc-track tabindex="0" aria-label="New arrivals"
+    class="sc-track [--sc-group:page] [--sc-per-view:1.3] @md:[--sc-per-view:2] @3xl:[--sc-per-view:4]">
+    <li>…</li>
+  </ul>
+  <button data-sc-next aria-label="Next products"
+    class="absolute end-3 top-1/3 hidden group-data-[sc-overflow]/row:grid aria-disabled:opacity-30">›</button>
+</div>
+```
+The complete example to copy, with a live preview compiled by Tailwind, is on the
+[documentation site](https://www.nordwerk.studio/oss/scroll-carousel#tailwind).
+### shadcn/ui
+A component with the structure of shadcn's Carousel, on native scrolling, and five blocks
+(product row, brand teasers, hero with autoplay, image gallery, logo belt), straight from this
+repository:
+```sh
+npx shadcn@latest add studio-nordwerk/scroll-carousel/scroll-carousel
+npx shadcn@latest add studio-nordwerk/scroll-carousel/product-row
+```
+`ScrollCarousel`, `ScrollCarouselContent`, `ScrollCarouselItem`, `ScrollCarouselPrevious` and
+`ScrollCarouselNext` match shadcn's names with the `Scroll` prefix, plus `ScrollCarouselDots`,
+`ScrollCarouselPlay` and `useScrollCarousel()`. Size slides with `[--sc-per-view:3]` on the content
+(or `basis-*` on items); spacing comes from `--sc-gap`, so the `-ml-4`/`pl-4` pair of the Embla
+version is not needed. The component imports `@nordwerk/scroll-carousel/carousel.layer.css`, the
+stylesheet inside Tailwind's components layer.
+### Next.js
+The React entry is marked `'use client'`, so `<Carousel>` can be used directly in Server
+Components of the App Router; it renders on the server and attaches in the browser.
 ## Markup
 | Element | Required | Purpose |

package/dist/carousel.css CHANGED Viewed

@@ -1,5 +1,5 @@
 /*
- * scroll-carousel, prototype stylesheet.
+ * scroll-carousel stylesheet.
  *
  * The layout is complete without JavaScript: the server-rendered markup is already the final
  * layout, and the script only adds controls. Everything is configured with custom properties,

package/dist/carousel.layer.css ADDED Viewed

@@ -0,0 +1,263 @@
+@layer theme, base, components, utilities;
+@layer components {
+/*
+ * scroll-carousel stylesheet.
+ *
+ * The layout is complete without JavaScript: the server-rendered markup is already the final
+ * layout, and the script only adds controls. Everything is configured with custom properties,
+ * which can be set anywhere above the track and changed in media or container queries. The root
+ * is the query container, so inside `@container sc (...)` set them on .sc-track.
+ *
+ *   --sc-per-view       slides per view; a fraction shows part of the next slide. Default 1.
+ *   --sc-slide-size     a fixed slide size, or auto for the content width. Wins over per-view.
+ *   --sc-gap            space between slides. Default 1rem.
+ *   --sc-offset-before  space before the first slide; snapped slides line up with it. Default 0.
+ *   --sc-offset-after   space after the last slide. Default 0.
+ *   --sc-snap           mandatory, proximity or none. Default mandatory.
+ *   --sc-align          start or center. Default start.
+ *   --sc-centered       1 pads both ends so the first and last slide can reach the centre.
+ *                       Derived from --sc-per-view, so it does not combine with --sc-slide-size.
+ *   --sc-count          the number of slides, when known; per-view never exceeds it.
+ *   --sc-group          slides per step of next and previous: a number, or page. Read by the script.
+ *   --sc-controls       none hides the arrows, dots and play button, e.g. for free mode on phones.
+ *
+ * Theme, all optional: --sc-control-bg, --sc-control-fg, --sc-control-border,
+ * --sc-control-size, --sc-control-radius, --sc-control-shadow, --sc-nav-top, --sc-nav-inset,
+ * --sc-dot, --sc-dot-size, --sc-dot-height, --sc-dot-active-size, --sc-dot-radius, --sc-dot-idle,
+ * --sc-focus.
+ */
+.sc {
+  container: sc / inline-size;
+  position: relative;
+}
+.sc-track {
+  --_n: min(var(--sc-per-view, 1), var(--sc-count, 1000));
+  --_gap: var(--sc-gap, 1rem);
+  --_size: calc(
+    (100cqi - var(--sc-offset-before, 0px) - var(--sc-offset-after, 0px) - (var(--_n) - 1) * var(--_gap)) /
+      var(--_n)
+  );
+  --_edge: calc((100cqi - var(--_size)) / 2 * var(--sc-centered, 0));
+  /* Also the containing block for anything absolutely positioned inside the slides, which the
+     scroller then clips instead of letting it widen the page. */
+  position: relative;
+  display: flex;
+  gap: var(--_gap);
+  margin: 0;
+  padding-block: 0;
+  padding-inline: calc(var(--sc-offset-before, 0px) + var(--_edge)) calc(var(--sc-offset-after, 0px) + var(--_edge));
+  list-style: none;
+  overflow-x: auto;
+  overflow-y: hidden;
+  overscroll-behavior-x: contain;
+  /* `x none` is invalid, which makes the property fall back to its initial value, none. */
+  scroll-snap-type: x var(--sc-snap, mandatory);
+  scroll-padding-inline: var(--sc-offset-before, 0px) var(--sc-offset-after, 0px);
+  scrollbar-width: none;
+  transition: opacity 0.16s ease;
+}
+.sc-track::-webkit-scrollbar {
+  display: none;
+}
+/* Zero specificity, so a host can size its own slides without a fight. */
+:where(.sc-track > *) {
+  flex: 0 0 var(--sc-slide-size, var(--_size));
+  min-width: 0;
+  scroll-snap-align: var(--sc-align, start);
+}
+:where(.sc-track > [data-sc-snap-off]) {
+  scroll-snap-align: none;
+}
+/* A row too short to scroll sits in the middle; auto margins collapse to 0 once it overflows. */
+.sc--center-few :where(.sc-track > :first-child) {
+  margin-inline-start: auto;
+}
+.sc--center-few :where(.sc-track > :last-child) {
+  margin-inline-end: auto;
+}
+.sc-track:focus-visible {
+  outline: 2px solid var(--sc-focus, Highlight);
+  outline-offset: -2px;
+}
+.sc[data-sc-drag][data-sc-overflow] .sc-track {
+  cursor: grab;
+}
+.sc[data-sc-drag] .sc-track :is(img, a) {
+  -webkit-user-drag: none;
+}
+.sc-track[data-sc-dragging] {
+  cursor: grabbing;
+  scroll-snap-type: none;
+  -webkit-user-select: none;
+  user-select: none;
+}
+.sc-track[data-sc-fading] {
+  opacity: 0;
+}
+/* Default controls. All optional: a host can bring its own and bind them to the API. */
+.sc-nav,
+.sc-play {
+  display: var(--sc-controls, grid);
+  place-items: center;
+  box-sizing: border-box;
+  inline-size: var(--sc-control-size, 2.75rem);
+  block-size: var(--sc-control-size, 2.75rem);
+  padding: 0;
+  border: 1px solid var(--sc-control-border, color-mix(in srgb, currentColor 22%, transparent));
+  border-radius: var(--sc-control-radius, 50%);
+  background: var(--sc-control-bg, Canvas);
+  box-shadow: var(--sc-control-shadow, none);
+  color: var(--sc-control-fg, CanvasText);
+  font: inherit;
+  cursor: pointer;
+}
+.sc-nav {
+  position: absolute;
+  z-index: 1;
+  inset-block-start: var(--sc-nav-top, 50%);
+  translate: 0 -50%;
+}
+.sc-prev {
+  inset-inline-start: var(--sc-nav-inset, 0.5rem);
+}
+.sc-next {
+  inset-inline-end: var(--sc-nav-inset, 0.5rem);
+}
+.sc-nav svg,
+.sc-play svg {
+  inline-size: 1.25rem;
+  block-size: 1.25rem;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+.sc-nav:dir(rtl) svg {
+  scale: -1 1;
+}
+.sc-nav[aria-disabled='true'] {
+  opacity: 0.35;
+  cursor: default;
+}
+.sc-play .sc-icon-pause,
+.sc[data-sc-playing] .sc-play .sc-icon-play {
+  display: none;
+}
+.sc[data-sc-playing] .sc-play .sc-icon-pause {
+  display: block;
+}
+.sc-dots {
+  display: var(--sc-controls, flex);
+  flex-wrap: wrap;
+  justify-content: center;
+  min-block-size: 1.5rem;
+}
+.sc-dot {
+  display: grid;
+  place-items: center;
+  inline-size: 1.5rem;
+  block-size: 1.5rem;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--sc-dot, currentColor);
+  cursor: pointer;
+}
+.sc-dot::before {
+  content: '';
+  inline-size: var(--sc-dot-size, 0.5rem);
+  block-size: var(--sc-dot-height, var(--sc-dot-size, 0.5rem));
+  border-radius: var(--sc-dot-radius, 1rem);
+  background: currentColor;
+  opacity: var(--sc-dot-idle, 0.35);
+  transition: inline-size 0.2s ease, opacity 0.2s ease;
+}
+.sc-dot[aria-current]::before {
+  inline-size: var(--sc-dot-active-size, 1.25rem);
+  opacity: 1;
+}
+/* While autoplay runs, the current dot fills up until the next move. */
+.sc[data-sc-playing] .sc-dot[aria-current]::before {
+  background:
+    linear-gradient(currentColor, currentColor) 0 0 / 0 100% no-repeat,
+    color-mix(in srgb, currentColor 35%, transparent);
+  animation: sc-progress var(--sc-autoplay-delay, 5s) linear forwards;
+}
+.sc[data-sc-playing] .sc-dot[aria-current]:dir(rtl)::before {
+  background-position: 100% 0;
+}
+.sc[data-sc-paused] .sc-dot::before {
+  animation-play-state: paused;
+}
+@keyframes sc-progress {
+  to {
+    background-size: 100% 100%;
+  }
+}
+:is(.sc-nav, .sc-play, .sc-dot):focus-visible {
+  outline: 2px solid var(--sc-focus, Highlight);
+  outline-offset: 2px;
+}
+/* Without the script, or without overflow, controls are absent: never focusable and dead.
+   Arrows float over the track and can simply go; dots and the play button keep their space,
+   so attaching the script cannot shift the layout around them. */
+.sc:not([data-sc-ready][data-sc-overflow]) .sc-nav {
+  display: none;
+}
+.sc:not([data-sc-ready][data-sc-overflow]) :is(.sc-dots, .sc-play) {
+  visibility: hidden;
+}
+.sc-status,
+.sc-skip:not(:focus) {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+@media (prefers-reduced-motion: reduce) {
+  .sc-track,
+  .sc-dot::before {
+    transition: none;
+  }
+}
+}

package/dist/react.js CHANGED Viewed

@@ -1,3 +1,4 @@
+'use client';
 import {
   createAdapter
 } from "./shared/chunk-I3QEUR7L.js";

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@nordwerk/scroll-carousel",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "A dependency-free carousel on native scrolling: CSS scroll snap first, arrows, dots, paging and an API as progressive enhancement.",
   "license": "MIT",
   "type": "module",
@@ -49,6 +49,7 @@
     },
     "./astro": "./src/astro/Carousel.astro",
     "./carousel.css": "./dist/carousel.css",
+    "./carousel.layer.css": "./dist/carousel.layer.css",
     "./package.json": "./package.json"
   },
   "files": [
@@ -63,7 +64,7 @@
   },
   "scripts": {
     "build": "node scripts/build.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p registry/tsconfig.json",
     "test": "node --test \"test/unit/*.test.ts\"",
     "size": "node scripts/size.mjs",
     "site": "node scripts/build.mjs && node site/generate.mjs",
@@ -89,6 +90,7 @@
     "@axe-core/playwright": "4.13.0",
     "@fontsource-variable/geist": "^5.3.0",
     "@playwright/test": "1.61.1",
+    "@tailwindcss/cli": "4.3.3",
     "@types/node": "^24.0.0",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
@@ -98,6 +100,8 @@
     "preact-render-to-string": "6.7.0",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
+    "shadcn": "4.21.0",
+    "tailwindcss": "4.3.3",
     "typescript": "^7.0.2"
   },
   "engines": {