react-prism-carousel 0.0.0-stage → 0.1.0

package/FOR-AI.md

@@ -0,0 +1,240 @@
+# react-prism-carousel: reference for AI coding assistants
+
+This file is for AI assistants writing code that **uses** this component in another project. Read all of it before writing or changing a `<Carousel>`. The human-oriented docs are in `README.md`.
+
+## What it is
+
+`Carousel` is a React 19 component that renders its children as the faces of a regular 3D prism, using pure CSS (`preserve-3d`, `sin()`/`cos()`, container query units, `sibling-index()`).
+
+**It draws; it does not control.** It has no internal state, no autoplay, no buttons, no keyboard or drag handling. The consuming code owns `currentFace` in its own state and changes it in response to input.
+
+## Install and import
+
+`npm install react-prism-carousel`. The package is ESM-only, has a peer dependency on `react@^19`, and ships its own types.
+
+```ts
+import Carousel from "react-prism-carousel";               // or: import { Carousel } from …
+import type { CarouselProps, FaceProps, PrismProps } from "react-prism-carousel";
+import "react-prism-carousel/style.css";                    // REQUIRED, once per app (e.g. in the root component or entry file)
+```
+
+## Minimal correct usage
+
+```tsx
+const [face, setFace] = useState(0);
+
+<div style={{ height: 320 }}>                     {/* REQUIRED: a parent with a definite height */}
+  <Carousel
+    orientation="horizontal"                      // required
+    noChildrenElem={<p>No items</p>}              // required (null is allowed)
+    aria-label="Featured products"                // always pass a label
+    currentFace={face}
+    transition="transform 0.6s ease"              // optional; the default is no animation
+  >
+    {items.map((item) => <Slide key={item.id} {...item} />)}
+  </Carousel>
+</div>
+<button onClick={() => setFace((f) => f + 1)}>Next</button>
+```
+
+## Props
+
+| Prop | Type | Default | Exact semantics |
+|---|---|---|---|
+| `orientation` | `"horizontal" \| "vertical"` | required | Horizontal spins around the Y axis (faces side by side, each 100% of the root's height). Vertical spins around the X axis (faces stacked, each 100% of the root's width). |
+| `noChildrenElem` | `ReactNode` | required | Rendered, flat and full size, when there are 0 children. |
+| `children` | `ReactNode` | | Processed with `Children.toArray`: arrays are flattened, `null`/`undefined`/booleans are dropped, a Fragment is ONE face. Each child becomes one face. Keys are preserved. |
+| `currentFace` | `number` | `0` | Rotation in face units. Unbounded: with 6 faces, `6` shows face 0 and `-1` shows face 5. Fractions rotate partway. If `numEmptyFaces > 0`, clamped to `[0, childCount − 1]`. |
+| `numEmptyFaces` | `number` | `0` | Extra invisible sides (rounded down, minimum 0). Total sides `n = childCount + numEmptyFaces`. Used to make an arc or scroller. |
+| `faceSize` | `string` | | A CSS length: face width (horizontal) or height (vertical). The radius becomes `faceSize / (2·sin(180°/n))`. Use `px`, `rem`, `cqw` or `cqh`. **Never `%`**: it breaks the depth and triggers a dev warning. |
+| `concave` | `boolean` | `false` | Faces point inward. The on-screen rotation direction is mirrored compared with convex. |
+| `cameraOffset` | `string` | | A CSS length. Translates the prism along Z: **positive moves the camera closer**, negative moves it away. |
+| `transition` | `string` | none | A CSS `transition` value applied to the prism. Rotation animates `transform`; `cameraOffset` animates `translate`. Forced to `none` under `prefers-reduced-motion: reduce`. |
+| `centerpieceElem` | `ReactNode` | | Rendered on the prism's axis and counter-rotated so it always faces the viewer. Its wrapper fills the root's box: centre the content yourself. |
+| `faceProps` | `FaceProps \| (index: number, isFront: boolean) => FaceProps` | | Spread onto every face wrapper `<span>`, AFTER the default `role`/`aria-*`, so it can override them. `isFront` = this face is the one nearest the front (`currentFace` rounded and wrapped). |
+| `prismProps` | `PrismProps` | | Spread onto the prism `<div>`. `className` is merged. `style` is merged, but the component's CSS variables win. The `data-*` attributes can't be overridden. |
+| other props | `HTMLAttributes<HTMLDivElement>` | | Spread onto the root `<div>`. `className` is merged; `style` passes through as is. Put `tabIndex`, `onKeyDown`, pointer handlers, `aria-label`, `perspective` and `perspectiveOrigin` here. |
+
+## DOM structure
+
+```
+div.root     role=region aria-roledescription=carousel  {...rest props}   container-type:size; perspective:1000px; contain:paint
+  div.prism  {...prismProps} data-orientation …                           preserve-3d; rotated by currentFace
+    span     role=group aria-roledescription=slide aria-label="i+1 of N" {...faceProps(i, isFront)}
+      child
+    …one span per child…
+    div.centerpiece
+      centerpieceElem
+```
+
+## Hard rules
+
+0. **Import `react-prism-carousel/style.css` once.** Without it, the faces render as plain stacked elements with no 3D.
+1. **The root needs a definite size.** It is `width: 100%; height: 100%` with `container-type: size`, so its content never sizes it. Put it in a parent with a height, or set `height`/`minHeight` on it with `style` or `className`. A carousel with no visible output is almost always 0px tall.
+2. **To advance, increment or decrement; never wrap `currentFace` yourself.** Use `f + 1`, not `(f + 1) % n`. Wrapping makes the prism spin backwards through every face when the transition is on. The component wraps internally for `isFront`. Exception: with `numEmptyFaces > 0` the value is clamped, so clamp it in your own state too (`Math.min(Math.max(f, 0), count - 1)`), or "next" will appear stuck at the ends.
+3. **Turn the transition off while dragging** (`transition={dragging ? undefined : "transform 0.4s ease-out"}`), feed a fractional `currentFace` during the drag, and `Math.round` it on release.
+4. **The camera lens is CSS, not a prop.** Set `style={{ perspective: "600px" }}` and/or `perspectiveOrigin` on the root. There is no `lens` or `cameraOrigin` prop.
+5. **Never `%` in `faceSize`.** Use `cqw` (horizontal) or `cqh` (vertical) for sizes relative to the carousel.
+6. **Don't override geometry.** On the prism or face wrappers, don't set `position`, `inset`, `margin`, `transform`, `rotate`, `translate`, `transform-origin` or `transform-style`. On face wrappers, also leave the width (horizontal) or height (vertical) alone. Safe to change: face `height` (horizontal) or `width` (vertical), `padding`, `cursor`, colours, classes.
+7. **Don't flatten 3D.** Don't put `overflow` (other than `visible`), `opacity < 1`, `filter`, `clip-path`, `mask`, `mix-blend-mode` or `isolation: isolate` on the prism; any of these collapses the carousel. For effects like dimming, style the slide inside the wrapper (`.dimmed > * { filter: … }`), not the wrapper.
+8. **The component's CSS is in `@layer react-prism-carousel.components`.** Any unlayered consumer CSS beats it, including CSS that breaks rules 6–7.
+9. **Always pass `aria-label`** (or `aria-labelledby`) on the root.
+10. **The `--prism-*` custom properties are internal.** Don't read or set them.
+
+## Geometry
+
+- `n = childCount + numEmptyFaces`, `θ = 360° / n`.
+- Default radius `r` = 50% of the root's width (horizontal) or height (vertical); with `faceSize`, `r = faceSize / (2·sin(θ/2))`.
+- Face size = `2r·sin(θ/2)`. Defaults: 6 faces are each 50% of the width, 4 faces about 70.7%, 8 faces about 38.3%.
+- Apothem (axis-to-face distance) `a = r·cos(θ/2)`.
+- Camera on the axis: **convex** `cameraOffset = perspective + a`; **concave** `cameraOffset = perspective − a`.
+- From outside, a convex prism shows its near half and a concave prism shows the inside of its far half. From inside, only the field of view in front of the camera is drawn (set by `perspective`; smaller = wider), and nothing behind the camera.
+
+## Behaviour to rely on
+
+- **0 children:** `noChildrenElem`, flat, full size.
+- **1 child and no empty faces:** flat, full size, no rotation.
+- **2 children:** a two-sided card at full size, back to back; each step flips it 180°.
+- **Clicks and painting** are limited to the root's box (`contain: paint`). Faces outside it never overlap or block neighbouring elements.
+- **Faces are not made `inert`** when turned away. If only the front face should be interactive or reachable by screen readers: `faceProps={(i, isFront) => ({ inert: !isFront })}`.
+- **Backfaces are visible (mirrored) by default.** Hide them with `backface-visibility: hidden` on the slide.
+- Inside slides, `cqw`/`cqh` resolve against the carousel root.
+- `prefers-reduced-motion` disables the `transition` prop. An inline `prismProps.style.transition` still overrides that.
+
+## Known issues (0.1.0)
+
+Check the installed version in `node_modules/react-prism-carousel/package.json`. This section describes 0.1.0, and later versions of this file say which issues are fixed.
+
+- **Clicks can reach the wrong element.** In a concave prism, a click on a visible face lands on the wrapper of the face opposite it, so the wrong `faceProps` handler runs. In a convex prism, clicks on faces other than the front one can land on the prism element instead. **Whenever faces have click handlers, or concave mode is used with interactive content, apply this workaround.** The CSS must be unlayered:
+
+  ```tsx
+  <Carousel prismProps={{ className: "prism-hit-fix" }} … />
+  ```
+
+  ```css
+  .prism-hit-fix { pointer-events: none; }
+  .prism-hit-fix > * { pointer-events: auto; backface-visibility: hidden; }
+  .prism-hit-fix > :last-child { pointer-events: none; }           /* the centerpiece wrapper is always the last child */
+  .prism-hit-fix > :last-child > * { pointer-events: auto; }
+  @media (prefers-reduced-motion: reduce) { .prism-hit-fix > :last-child { transition: none; } }  /* next issue */
+  ```
+
+- **Under `prefers-reduced-motion`, the centerpiece still animates** its counter-rotation. The last rule above fixes it.
+- **With exactly one face and no empty faces**, changing `currentFace` while a transition is set spins the centerpiece a full turn. Keep `currentFace` at 0 when there's only one face.
+
+## Recipes
+
+### Keyboard
+
+```tsx
+<Carousel
+  tabIndex={0}
+  onKeyDown={(e) => {
+    if (e.key === "ArrowRight") setFace((f) => f + 1);
+    if (e.key === "ArrowLeft") setFace((f) => f - 1);
+  }}
+  …
+/>
+```
+
+### Drag
+
+```tsx
+const [pos, setPos] = useState(0);
+const [dragging, setDragging] = useState(false);
+const start = useRef<{ x: number; pos: number } | null>(null);
+const end = () => { start.current = null; setDragging(false); setPos((p) => Math.round(p)); };
+
+<Carousel
+  currentFace={pos}
+  transition={dragging ? undefined : "transform 0.4s ease-out"}
+  style={{ touchAction: "pan-y" }}
+  onPointerDown={(e) => { e.currentTarget.setPointerCapture(e.pointerId); start.current = { x: e.clientX, pos }; setDragging(true); }}
+  onPointerMove={(e) => {
+    if (!start.current) return;
+    // n = total sides. With default sizing, face width = width·sin(180°/n)
+    const facePx = e.currentTarget.clientWidth * Math.sin(Math.PI / n);
+    setPos(start.current.pos - (e.clientX - start.current.x) / facePx);
+  }}
+  onPointerUp={end}
+  onPointerCancel={end}
+  …
+/>
+```
+
+### Arc or scroller with clickable faces
+
+```tsx
+<Carousel
+  orientation="horizontal"
+  aria-label="Products"
+  noChildrenElem={null}
+  prismProps={{ className: "prism-hit-fix" }}  // 0.1.0: see "Known issues"
+  currentFace={face}               // keep 0 … items.length − 1
+  numEmptyFaces={9}
+  faceSize="30cqw"                 // keeps faces the same size whatever numEmptyFaces is
+  transition="transform 0.5s ease"
+  faceProps={(i, isFront) => ({
+    onClick: () => setFace(i),
+    className: isFront ? "front" : "dimmed",
+    style: { cursor: "pointer", paddingInline: 6 },  // padding = gap between faces
+  })}
+>
+  {items.map((it) => <Card key={it.id} {...it} />)}
+</Carousel>
+```
+
+### Per-face accessible names
+
+```tsx
+faceProps={(i) => ({ "aria-label": items[i].title })}
+```
+
+### Card backs (background from both sides, content only from the front)
+
+```css
+.card { transform-style: preserve-3d; }
+.card-content { backface-visibility: hidden; }
+```
+
+```tsx
+<div className="card"><span className="card-content">{title}</span></div>
+```
+
+### Logo in the middle
+
+```tsx
+<Carousel
+  faceSize="22cqw"
+  style={{ perspectiveOrigin: "50% -40%" }}        // view from slightly above
+  faceProps={{ style: { height: "40%" } }}          // shorter faces reveal the centerpiece
+  centerpieceElem={
+    <div style={{ display: "flex", alignItems: "center", justifyContent: "center", height: "100%" }}>
+      <Logo />
+    </div>
+  }
+  …
+/>
+```
+
+### Camera inside the prism
+
+```tsx
+// 8 faces on a 918px-wide root: r = 459, a = 459·cos(22.5°) ≈ 424
+<Carousel concave style={{ perspective: "300px" }} cameraOffset="-124px" … />  // 300 − 424
+```
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Nothing renders | The root is 0px tall | Give the parent (or the root) a height. |
+| Faces are piled up flat, with no 3D | The stylesheet isn't imported | `import "react-prism-carousel/style.css"` once. |
+| A click runs the wrong face's handler, or side faces ignore clicks | The 0.1.0 hit-testing issue | Apply the workaround in "Known issues". |
+| Prism collapses or looks flat | `%` in `faceSize`, or a 3D-flattening property on the prism | Use `cqw`/`cqh`/`px`; move effects onto the slides. |
+| It spins backwards through every face at the end | `currentFace` wrapped with `%` | Keep incrementing. |
+| "Next" seems stuck in an arc | Value clamped by `numEmptyFaces` while your state keeps growing | Clamp your state too. |
+| Mirrored text on the back faces | Backfaces are visible by default | `backface-visibility: hidden` on the slide, or the card-back recipe. |
+| Front face is huge | Large `faceSize` brings the front face near the camera | Negative `cameraOffset`, or a larger `perspective`. |
+| Dragging feels laggy | Transition still on during the drag | `transition={dragging ? undefined : …}`. |
+| Only one face is visible from inside | Narrow field of view | A smaller `perspective` (e.g. `300px`). |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BlueWebber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,460 @@
-# Temporary Holding Version
+# react-prism-carousel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A 3D prism carousel for React. Every child becomes one face of a regular prism, and the geometry is done entirely in CSS: no measuring, no animation loop, no JavaScript per frame.
+
+The component only **draws** the prism. Deciding which face is in front, and when and how it turns (buttons, keys, drag, autoplay), is up to you.
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [How it works](#how-it-works)
+- [Props](#props)
+- [Sizing](#sizing)
+- [Rotation and animation](#rotation-and-animation)
+- [Camera](#camera)
+- [Styling faces](#styling-faces)
+- [Centerpiece](#centerpiece)
+- [Clicks, focus and accessibility](#clicks-focus-and-accessibility)
+- [Edge cases](#edge-cases)
+- [Overriding styles](#overriding-styles)
+- [TypeScript](#typescript)
+- [Known issues](#known-issues)
+- [Developing](#developing)
+
+## Requirements
+
+- React 19.
+- A bundler that supports CSS Modules (Vite, Next.js, webpack with `css-loader`, …).
+- A browser that supports `sibling-index()`, `sin()`/`cos()`, container queries (`container-type`, `cqw`/`cqh`), CSS nesting, `@layer`, and the individual `translate`/`rotate` properties. `sibling-index()` is the newest of these, so check its support first.
+
+## Installation
+
+```sh
+npm install react-prism-carousel
+```
+
+Import the component, and import the stylesheet once anywhere in your app (next to your root component, for example):
+
+```tsx
+import Carousel from "react-prism-carousel";
+import "react-prism-carousel/style.css";
+```
+
+The package is ESM-only.
+
+### Using an AI coding assistant
+
+The package includes a reference written for AI assistants, at `node_modules/react-prism-carousel/FOR-AI.md`, which always matches the version you installed. Assistants don't look inside `node_modules` on their own, so add this line to your project's agent instructions (`AGENTS.md`, `CLAUDE.md`, Cursor rules, …):
+
+```md
+Before writing code that uses react-prism-carousel, read node_modules/react-prism-carousel/FOR-AI.md.
+```
+
+It's also online at <https://unpkg.com/react-prism-carousel/FOR-AI.md>.
+
+## Quick start
+
+```tsx
+import { useState } from "react";
+import Carousel from "react-prism-carousel";
+import "react-prism-carousel/style.css";
+
+function Featured({ slides }) {
+  const [face, setFace] = useState(0);
+
+  return (
+    <>
+      {/* The carousel fills its parent, so the parent needs a height. */}
+      <div style={{ height: 320 }}>
+        <Carousel
+          orientation="horizontal"
+          aria-label="Featured products"
+          noChildrenElem={<p>Nothing to show yet.</p>}
+          currentFace={face}
+          transition="transform 0.6s ease"
+        >
+          {slides.map((slide) => (
+            <Slide key={slide.id} {...slide} />
+          ))}
+        </Carousel>
+      </div>
+
+      <button onClick={() => setFace((f) => f - 1)}>Previous</button>
+      <button onClick={() => setFace((f) => f + 1)}>Next</button>
+    </>
+  );
+}
+```
+
+There are two things to remember:
+
+1. **Give it a height.** The carousel is `100%` of its parent's width and height and doesn't grow with its content.
+2. **You own the rotation.** Change `currentFace` however you like. The component turns the prism to match.
+
+## How it works
+
+With `n` sides (your children plus any `numEmptyFaces`), each child is wrapped in a `<span>` and placed on one side of a regular `n`-sided prism:
+
+- **`orientation="horizontal"`** spins around the vertical axis. Faces sit side by side, each as tall as the carousel.
+- **`orientation="vertical"`** spins around the horizontal axis. Faces are stacked, each as wide as the carousel.
+
+By default the prism's corners touch the carousel's edges: the radius is half the carousel's width (or height, when vertical), so each face is `width × sin(180° / n)` wide. With 6 faces, each face is half the carousel's width; with 4, about 71%.
+
+`currentFace` turns the whole prism so that face is at the front.
+
+The rendered DOM:
+
+```
+div   role="region" aria-roledescription="carousel"   ← the root: your other props go here
+  div                                                 ← the prism: prismProps go here
+    span  role="group" aria-roledescription="slide"   ← face wrapper: faceProps go here
+      {your child}
+    span …
+    div                                               ← centerpiece wrapper
+      {centerpieceElem}
+```
+
+## Props
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `orientation` | `"horizontal" \| "vertical"` | **required** | Which axis the prism spins around. |
+| `noChildrenElem` | `ReactNode` | **required** | Shown, full size, when there are no children. |
+| `children` | `ReactNode` | | One face per child. |
+| `currentFace` | `number` | `0` | The face to bring to the front. Fractions and out-of-range values are allowed (see [Rotation](#rotation-and-animation)). |
+| `numEmptyFaces` | `number` | `0` | Adds empty sides, turning the closed prism into an arc. Rounded down; negative values count as 0. |
+| `faceSize` | `string` (CSS length) | | Each face's width (horizontal) or height (vertical). Sets the prism's radius instead of the default. |
+| `concave` | `boolean` | `false` | Faces point inward, as if you were inside the prism. |
+| `cameraOffset` | `string` (CSS length) | | Moves the camera: positive values bring it closer, negative values move it away. |
+| `transition` | `string` | none | A CSS `transition` value for the prism. |
+| `centerpieceElem` | `ReactNode` | | Content placed on the prism's axis, which the faces circle around. |
+| `faceProps` | `FaceProps` or `(index, isFront) => FaceProps` | | HTML attributes for every face wrapper. |
+| `prismProps` | `PrismProps` | | HTML attributes for the prism element. |
+| any other prop | `HTMLAttributes<HTMLDivElement>` | | Passed to the root element. |
+
+**Children.** Arrays are flattened. `null`, `undefined` and booleans are skipped, so `{cond && <Slide/>}` doesn't leave an empty face. A Fragment counts as one face. Children's `key`s are kept.
+
+**Root props.** `className` is added to the component's own class. `style`, event handlers, `tabIndex`, `aria-*` and the rest are passed through unchanged. This is where CSS `perspective` and `perspective-origin` go (see [Camera](#camera)).
+
+**`prismProps`.** `className` is merged. `style` is merged too, but the component's own CSS variables are applied after yours.
+
+**`faceProps`.** Applied after the component's default `role`, `aria-roledescription` and `aria-label`, so you can override them. As a function, it receives the face's index and `isFront`: whether that face is the one at the front right now.
+
+## Sizing
+
+The carousel is `100%` of its parent's width and height and uses `container-type: size`, which means **its size never depends on its content**. If its parent has no height, the carousel is 0px tall.
+
+To make it a specific size, set `width`, `height`, `min-width` or `min-height` on the root with `style` or `className`. It can be bigger than its parent.
+
+**`faceSize`** fixes the size of each face instead. The radius is then calculated from it: `radius = faceSize / (2 × sin(180° / n))`. Use it when faces must stay the same size however many sides there are (for example in an [arc](#arcs-and-scrollers)).
+
+- Use any length: `px`, `rem`, or `cqw`/`cqh` to size relative to the carousel (`30cqw` is 30% of the carousel's width).
+- **Don't use `%`.** The prism's depth is set with `transform-origin`, which doesn't accept percentages for Z, so the prism collapses. In development, the component warns about it in the console.
+- A big `faceSize` makes a big prism, whose front face can come very close to the camera. Pull the camera back with a negative `cameraOffset`.
+
+Anything outside the carousel's box is clipped (`contain: paint`). To show more of a large prism, make the carousel bigger.
+
+**Gaps between faces:** add padding through `faceProps`. The wrappers use `box-sizing: border-box`, so padding shrinks your content, not the geometry.
+
+```tsx
+faceProps={{ style: { paddingInline: 8 } }}
+```
+
+## Rotation and animation
+
+### `currentFace`
+
+- **It isn't wrapped.** With 6 faces, `currentFace={6}` shows face 0 again and `-1` shows face 5. To loop smoothly, keep counting up (`f + 1`) instead of resetting to 0. Going from 5 back to 0 would spin the prism backwards through every face.
+- **Fractions work.** `2.5` shows the prism halfway between faces 2 and 3, which is what you want for dragging (see below).
+- **With `numEmptyFaces`, it's clamped** to `0 … children − 1`, so an empty side can never come to the front.
+- `isFront` in `faceProps` uses the nearest whole face, wrapped into range.
+
+### `transition`
+
+A plain CSS `transition` value, applied to the prism. The rotation is its `transform` and `cameraOffset` is its `translate`:
+
+```tsx
+transition="transform 0.6s ease"
+transition="transform 0.6s ease, translate 0.3s ease"
+```
+
+The default is no transition: changes are instant.
+
+For users with `prefers-reduced-motion: reduce`, the transition is switched off. A `transition` you set yourself in `prismProps.style` still applies; that's treated as your explicit choice.
+
+### Dragging
+
+Drive `currentFace` with a fraction while dragging, turn the transition off during the drag, and round on release:
+
+```tsx
+const [position, setPosition] = useState(0);
+const [dragging, setDragging] = useState(false);
+const start = useRef(null);
+
+<Carousel
+  orientation="horizontal"
+  aria-label="Draggable carousel"
+  noChildrenElem={null}
+  currentFace={position}
+  transition={dragging ? undefined : "transform 0.4s ease-out"}
+  style={{ touchAction: "pan-y" }}
+  onPointerDown={(e) => {
+    e.currentTarget.setPointerCapture(e.pointerId);
+    start.current = { x: e.clientX, position };
+    setDragging(true);
+  }}
+  onPointerMove={(e) => {
+    if (!start.current) return;
+    const faceWidth = e.currentTarget.clientWidth / 2; // 6 faces: half the width
+    setPosition(start.current.position - (e.clientX - start.current.x) / faceWidth);
+  }}
+  onPointerUp={() => {
+    start.current = null;
+    setDragging(false);
+    setPosition((p) => Math.round(p));
+  }}
+>
+  {slides}
+</Carousel>
+```
+
+### Arcs and scrollers
+
+`numEmptyFaces` adds invisible sides. A few real faces on a prism with many sides form a gentle arc, which works as a scroller with several faces visible at once. Set `faceSize` too, so the faces don't shrink as you add sides:
+
+```tsx
+<Carousel
+  orientation="horizontal"
+  aria-label="Products"
+  noChildrenElem={null}
+  currentFace={face}
+  numEmptyFaces={9}
+  faceSize="30cqw"
+  transition="transform 0.5s ease"
+  faceProps={(i) => ({ onClick: () => setFace(i) })}
+>
+  {products}
+</Carousel>
+```
+
+## Camera
+
+Three settings control what the viewer sees. Two of them are plain CSS on the root:
+
+| | Set with | |
+|---|---|---|
+| Lens (field of view) | CSS `perspective` on the root | Default `1000px`. Smaller values give a wider view and stronger distortion. |
+| Camera position, sideways and up/down | CSS `perspective-origin` on the root | Default `50% 50%`. `"50% -40%"` looks down on the prism from above. |
+| Camera distance | the `cameraOffset` prop | Positive values bring the camera closer, negative values move it away. |
+
+```tsx
+<Carousel
+  style={{ perspective: "600px", perspectiveOrigin: "50% -40%" }}
+  cameraOffset="-200px"
+  …
+/>
+```
+
+`perspective-origin` moves the camera, but it keeps looking straight ahead, like a shifted lens. It doesn't turn to aim at the prism.
+
+### What the camera can see
+
+- **From outside a convex prism**, you see the near half. The far half is turned away from you.
+- **From outside a concave prism**, you see the inside of the far half. The near half is turned away from you.
+- **From inside**, you only see what's in front of the camera. How much of the ring that is depends on `perspective`: at `1000px` on a carousel about 900px wide, the view is about 50° wide, roughly one face out of eight. Anything behind the camera isn't drawn.
+
+Faces turned away from the camera are still drawn, mirrored, unless you hide their backs (see [Backfaces](#backfaces-and-card-backs)).
+
+### Putting the camera inside the prism
+
+With `n` sides and radius `r` (half the carousel's width by default), the distance from the axis to each face is `a = r × cos(180° / n)`. To put the camera exactly on the axis:
+
+- **convex:** `cameraOffset = perspective + a`
+- **concave:** `cameraOffset = perspective − a`
+
+For example, take 8 concave faces on a 918px-wide carousel: `r = 459px` and `a ≈ 424px`. With `perspective: 300px`, `cameraOffset="-124px"` puts the camera on the axis. A small `perspective` like that gives a wide enough view to see several faces around you.
+
+### Concave mode
+
+`concave` turns every face inward. Because you're now looking at the inside of the ring, increasing `currentFace` turns the prism the other way on screen than in convex mode.
+
+## Styling faces
+
+`faceProps` sets attributes on every face wrapper. Use an object for all faces, or a function for per-face values:
+
+```tsx
+faceProps={(i, isFront) => ({
+  className: isFront ? "front" : "behind",
+  "aria-label": slides[i].title,
+  onClick: () => setFace(i),
+})}
+```
+
+**Dimming faces that aren't at the front:**
+
+```css
+.behind > * {
+  filter: brightness(0.45);
+}
+```
+
+This styles your slide inside the wrapper rather than the wrapper itself. That matters for slides that use 3D themselves (card backs): `filter`, `opacity` and similar properties flatten 3D on the element they're applied to.
+
+**Face height** (horizontal) or **width** (vertical) isn't part of the geometry, so you can change it. Faces stay centred:
+
+```tsx
+faceProps={{ style: { height: "40%" } }}
+```
+
+### Backfaces and card backs
+
+The browser draws faces that are turned away as their mirror image. You have three options:
+
+- **Hide them completely:** set `backface-visibility: hidden` on your slide.
+- **Show them mirrored:** do nothing.
+- **Show a "card back"**, where the slide's background shows from both sides but its content only from the front. Set `transform-style: preserve-3d` on the slide and `backface-visibility: hidden` on its content:
+
+  ```css
+  .card {
+    transform-style: preserve-3d;
+  }
+  .card-content {
+    backface-visibility: hidden;
+  }
+  ```
+
+  ```tsx
+  <div className="card">
+    <span className="card-content">{title}</span>
+  </div>
+  ```
+
+## Centerpiece
+
+`centerpieceElem` is placed on the prism's axis, with the faces circling around it. It turns against the prism's rotation, so it always faces the viewer. Faces in front of it cover it, and it covers faces behind it.
+
+Its wrapper spans the carousel's whole box, so centre your content yourself:
+
+```tsx
+<Carousel
+  orientation="horizontal"
+  aria-label="Products around a logo"
+  noChildrenElem={null}
+  currentFace={face}
+  faceSize="22cqw"
+  style={{ perspectiveOrigin: "50% -40%" }}
+  faceProps={{ style: { height: "40%" } }}
+  centerpieceElem={
+    <div style={{ display: "flex", alignItems: "center", justifyContent: "center", height: "100%" }}>
+      <Logo />
+    </div>
+  }
+>
+  {products}
+</Carousel>
+```
+
+Shorter faces and a raised camera, as in this example, let the centerpiece show above and below the ring.
+
+## Clicks, focus and accessibility
+
+### Clicks
+
+Only what's inside the carousel's box is drawn and clickable (`contain: paint`). Faces that stick out of the box never cover or block neighbouring elements on the page.
+
+Faces turned away from the viewer aren't made inert: in a scroller, several faces can be visible and clickable at once. (In 0.1.0, see [Known issues](#known-issues) for clicks that reach the wrong face.) If only the front face should be interactive and focusable:
+
+```tsx
+faceProps={(i, isFront) => ({ inert: !isFront })}
+```
+
+### Keyboard
+
+There's no built-in keyboard handling. Add it on the root:
+
+```tsx
+<Carousel
+  tabIndex={0}
+  onKeyDown={(e) => {
+    if (e.key === "ArrowRight") setFace((f) => f + 1);
+    if (e.key === "ArrowLeft") setFace((f) => f - 1);
+  }}
+  …
+/>
+```
+
+### ARIA
+
+The component follows the WAI-ARIA carousel pattern:
+
+- The root has `role="region"` and `aria-roledescription="carousel"`. **Pass an `aria-label`** (or `aria-labelledby`) naming the carousel.
+- Each face wrapper has `role="group"`, `aria-roledescription="slide"` and `aria-label="1 of 6"`. Override any of them through `faceProps`, for example to use the slide's title as its label.
+
+All faces stay in the accessibility tree. Use the `inert` example above to hide all but the front face from screen readers too.
+
+## Edge cases
+
+| Children | `numEmptyFaces` | Result |
+|---|---|---|
+| 0 | any | `noChildrenElem`, flat and full size. |
+| 1 | 0 | The single face, flat and full size, with no rotation. |
+| 1 | > 0 | One face on an arc. |
+| 2 | 0 | A two-sided card: both faces are full size, back to back, and each turn flips it 180°. Hide backfaces so you don't see the other face mirrored. |
+
+## Overriding styles
+
+The component's CSS lives in the cascade layer `react-prism-carousel.components`, so any CSS of yours that isn't in a layer overrides it. That includes CSS that breaks the prism. Avoid setting these:
+
+- **On the prism and the face wrappers:** `position`, `inset`, `margin`, `transform`, `rotate`, `translate`, `transform-origin`, `transform-style`. On the face wrappers, also the width (horizontal) or height (vertical).
+- **Properties that flatten 3D**, applied to the prism or the face wrappers: `overflow` other than `visible`, `opacity` below 1, `filter`, `clip-path`, `mask`, `mix-blend-mode`, `isolation: isolate`. On the prism, they flatten the whole carousel. On a face wrapper, they only affect slides that use 3D themselves. Put these effects on your slides instead.
+
+Inside your slides, `cqw` and `cqh` refer to the carousel's root, since it's the nearest size container.
+
+The `--prism-*` custom properties are internal and may change.
+
+## TypeScript
+
+Types ship with the package:
+
+```ts
+import Carousel, { type CarouselProps, type FaceProps, type PrismProps } from "react-prism-carousel";
+// or the named export: import { Carousel } from "react-prism-carousel";
+```
+
+- `CarouselProps`: every prop above, plus the root's HTML attributes.
+- `FaceProps`: `React.HTMLAttributes<HTMLSpanElement>`.
+- `PrismProps`: `React.HTMLAttributes<HTMLDivElement>`.
+
+Every prop has a doc comment, so your editor shows its description on hover.
+
+## Known issues
+
+These are known in 0.1.0 and will be fixed in a later version.
+
+- **Clicks can reach the wrong face.** In a concave prism, a click on a visible face lands on the wrapper of the face opposite it, so that face's `faceProps` handlers run instead. In a convex prism, clicks on faces angled away from the viewer (every face but the front one) can land on the prism element instead. Clicks on the front face of a convex prism work. As a workaround, give the prism a class and add this unlayered CSS:
+
+  ```tsx
+  <Carousel prismProps={{ className: "prism-hit-fix" }} … />
+  ```
+
+  ```css
+  .prism-hit-fix { pointer-events: none; }
+  .prism-hit-fix > * { pointer-events: auto; backface-visibility: hidden; }
+  /* the centerpiece wrapper is always the prism's last child */
+  .prism-hit-fix > :last-child { pointer-events: none; }
+  .prism-hit-fix > :last-child > * { pointer-events: auto; }
+  ```
+
+  `backface-visibility` here applies only to the face wrappers, not to your slides, so it doesn't change what you see.
+- **With `prefers-reduced-motion`, the centerpiece still animates** its turn while the prism changes instantly. Workaround, with the class above: `@media (prefers-reduced-motion: reduce) { .prism-hit-fix > :last-child { transition: none; } }`.
+- **With exactly one face** (and no `numEmptyFaces`), changing `currentFace` with a transition spins the centerpiece a full turn. Keep `currentFace` at 0 when there's only one face.
+
+## Developing
+
+```sh
+npm install --legacy-peer-deps   # typescript-eslint doesn't accept TypeScript 7 as a peer yet
+npm run dev                      # the demo page
+npm run build                    # the package, into dist/
+```
+
+The demo page in `demos/` has one section per feature: horizontal and vertical prisms, an arc scroller, dragging, `faceProps`, concave mode and the camera, card backs, the centerpiece, and the 0-, 1- and 2-face edge cases.

package/dist/Carousel.d.ts

@@ -0,0 +1,79 @@
+import React from "react";
+/** HTML attributes for each face's wrapper `<span>`. */
+export type FaceProps = React.HTMLAttributes<HTMLSpanElement>;
+/** HTML attributes for the prism `<div>`. */
+export type PrismProps = React.HTMLAttributes<HTMLDivElement>;
+/**
+ * Props for {@link Carousel}. Any other HTML attribute is passed to the root `<div>`
+ * (`className` is merged, `style` is passed as is): put `aria-label`, `tabIndex`,
+ * event handlers, and the CSS `perspective` / `perspectiveOrigin` there.
+ */
+export interface CarouselProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * One face per child. Arrays are flattened, `null` / `undefined` / booleans are
+     * skipped, and a Fragment counts as one face.
+     */
+    children?: React.ReactNode;
+    /**
+     * `"horizontal"` spins around the vertical axis (faces side by side, each as tall
+     * as the carousel); `"vertical"` spins around the horizontal axis.
+     */
+    orientation: "horizontal" | "vertical";
+    /** Shown, flat and full size, when there are no children. `null` is allowed. */
+    noChildrenElem: React.ReactNode;
+    /**
+     * Content on the prism's axis, turned so it always faces the viewer. Its wrapper
+     * fills the carousel's box, so centre the content yourself.
+     */
+    centerpieceElem?: React.ReactNode;
+    /**
+     * The face to bring to the front. Default 0. Not wrapped: with 6 faces, 6 shows
+     * face 0 again, so keep incrementing to loop smoothly. Fractions rotate partway
+     * (for dragging). Clamped to the real faces when `numEmptyFaces` > 0.
+     */
+    currentFace?: number;
+    /**
+     * Extra empty sides, which turn the closed prism into an arc. Default 0.
+     * Rounded down; negative values count as 0.
+     */
+    numEmptyFaces?: number;
+    /**
+     * Attributes for every face's wrapper `<span>`: one object for all faces, or a
+     * function for per-face values. Applied after the default ARIA attributes, so it
+     * can override them. `isFront`: this face is the one nearest the front.
+     */
+    faceProps?: FaceProps | ((index: number, isFront: boolean) => FaceProps);
+    /** Attributes for the prism `<div>`. `className` and `style` are merged. */
+    prismProps?: PrismProps;
+    /**
+     * Width (horizontal) or height (vertical) of each face, as a CSS length. The
+     * radius is calculated from it. Use px, rem, cqw or cqh, never % (the depth
+     * can't use %, so the prism collapses).
+     */
+    faceSize?: string;
+    /** Faces point inward, as if seen from inside the prism. Default false. */
+    concave?: boolean;
+    /**
+     * Moves the camera, as a CSS length: positive values bring it closer (eventually
+     * inside the prism), negative values move it away.
+     */
+    cameraOffset?: string;
+    /**
+     * CSS `transition` for the prism: rotation is `transform`, `cameraOffset` is
+     * `translate`. Default none. Switched off under `prefers-reduced-motion`.
+     */
+    transition?: string;
+}
+/**
+ * A 3D prism carousel: every child is one face. The component only draws the
+ * prism; keep `currentFace` in your own state and change it to turn it.
+ *
+ * The parent must have a height: the carousel fills it and never grows with its
+ * content. Import `react-prism-carousel/style.css` once.
+ *
+ * @see https://unpkg.com/react-prism-carousel/FOR-AI.md for AI coding assistants,
+ * also at node_modules/react-prism-carousel/FOR-AI.md
+ * @see https://github.com/BlueWebber/react-prism-carousel#readme
+ */
+declare function Carousel({ children, orientation, noChildrenElem, centerpieceElem, faceProps, prismProps, currentFace, numEmptyFaces, faceSize, concave, cameraOffset, transition, ...props }: CarouselProps): React.JSX.Element;
+export default Carousel;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { default, default as Carousel } from "./Carousel.js";
+export type { CarouselProps, FaceProps, PrismProps } from "./Carousel.js";

package/dist/index.js

@@ -0,0 +1,61 @@
+import e from "react";
+import { jsx as t, jsxs as n } from "react/jsx-runtime";
+var r = {
+	carouselContainer: "_carouselContainer_1ax8l_4",
+	carousel: "_carousel_1ax8l_4",
+	centerpiece: "_centerpiece_1ax8l_36"
+};
+// src/Carousel.tsx
+function i() {
+	try {
+		return process.env.NODE_ENV !== "production";
+	} catch {
+		return !1;
+	}
+}
+function a({ children: a, orientation: o, noChildrenElem: s, centerpieceElem: c, faceProps: l, prismProps: u, currentFace: d = 0, numEmptyFaces: f = 0, faceSize: p, concave: m = !1, cameraOffset: h, transition: g, ..._ }) {
+	e.useEffect(() => {
+		i() && p?.trim().endsWith("%") && console.warn(`Carousel: faceSize "${p}" uses %, which the 3D depth (transform-origin Z) doesn't accept. Use cqw (horizontal) or cqh (vertical) for sizes relative to the carousel.`);
+	}, [p]);
+	let v = e.Children.toArray(a), y = v.length, b = Number.isFinite(f) ? Math.max(0, Math.floor(f)) : 0, x = y === 0 || y + b === 1, S = d;
+	b && y > 0 && (S = Math.min(Math.max(d, 0), y - 1));
+	let C = y + b, w = -1;
+	if (y > 0 && Number.isFinite(S)) {
+		let e = (Math.round(S) % C + C) % C;
+		w = e < y ? e : -1;
+	}
+	return /* @__PURE__ */ t("div", {
+		role: "region",
+		"aria-roledescription": "carousel",
+		..._,
+		className: [r.carouselContainer, _.className].filter(Boolean).join(" "),
+		children: /* @__PURE__ */ n("div", {
+			...u,
+			"data-orientation": o,
+			"data-flat": x || void 0,
+			"data-facesize": p ? "manual" : void 0,
+			"data-concave": m || void 0,
+			style: {
+				...u?.style,
+				"--prism-current-face": S,
+				"--prism-face-count": y,
+				"--prism-num-empty-faces": b,
+				"--prism-face-size": p,
+				"--prism-camera-offset": h,
+				"--prism-transition": g
+			},
+			className: [r.carousel, u?.className].filter(Boolean).join(" "),
+			children: [y === 0 ? s : v.map((n, r) => /* @__PURE__ */ t("span", {
+				role: "group",
+				"aria-roledescription": "slide",
+				"aria-label": `${r + 1} of ${y}`,
+				...typeof l == "function" ? l(r, r === w) : l,
+				children: n
+			}, e.isValidElement(n) && n.key != null ? n.key : r)), /* @__PURE__ */ t("div", {
+				className: r.centerpiece,
+				children: c
+			})]
+		})
+	});
+}
+export { a as Carousel, a as default };

package/dist/style.css

@@ -0,0 +1,2 @@
+@layer react-prism-carousel.components{._carouselContainer_1ax8l_4,._carousel_1ax8l_4,._carousel_1ax8l_4>*{box-sizing:border-box}._carouselContainer_1ax8l_4{perspective:1000px;contain:paint;width:100%;height:100%;display:flex;position:relative;container-type:size}._carousel_1ax8l_4[data-orientation=vertical]{--prism-radius:50cqh;--prism-rotate-deg:calc(360deg / (var(--prism-face-count) + var(--prism-num-empty-faces)));--prism-face-height:calc(sin(var(--prism-rotate-deg) / 2) * var(--prism-radius) * 2);--prism-origin-depth:calc(cos(var(--prism-rotate-deg) / 2) * var(--prism-radius) * var(--prism-depth-sign));transform:rotateX(calc(var(--prism-current-face) * var(--prism-rotate-deg) * -1))}._carousel_1ax8l_4[data-orientation=vertical]>:not(._centerpiece_1ax8l_36){height:var(--prism-face-height);width:100%;rotate:x calc((var(--prism-rotate-deg) * (sibling-index() - 1)))}._carousel_1ax8l_4[data-orientation=vertical]>._centerpiece_1ax8l_36{transform:rotateX(calc(var(--prism-current-face) * var(--prism-rotate-deg)))}._carousel_1ax8l_4[data-orientation=horizontal]{--prism-radius:50cqw;--prism-rotate-deg:calc(360deg / (var(--prism-face-count) + var(--prism-num-empty-faces)));--prism-face-width:calc(sin(var(--prism-rotate-deg) / 2) * var(--prism-radius) * 2);--prism-origin-depth:calc(cos(var(--prism-rotate-deg) / 2) * var(--prism-radius) * var(--prism-depth-sign));transform:rotateY(calc(var(--prism-current-face) * var(--prism-rotate-deg) * -1))}._carousel_1ax8l_4[data-orientation=horizontal]>:not(._centerpiece_1ax8l_36){width:var(--prism-face-width);height:100%;rotate:y calc((var(--prism-rotate-deg) * (sibling-index() - 1)))}._carousel_1ax8l_4[data-orientation=horizontal]>._centerpiece_1ax8l_36{transform:rotateY(calc(var(--prism-current-face) * var(--prism-rotate-deg)))}._carousel_1ax8l_4[data-facesize=manual]{--prism-radius:calc(var(--prism-face-size) / (2 * sin(var(--prism-rotate-deg) / 2)))}._carousel_1ax8l_4[data-concave]{--prism-depth-sign:1}._carousel_1ax8l_4[data-flat]{transform:none}._carousel_1ax8l_4[data-flat]>:not(._centerpiece_1ax8l_36){transform-origin:50%;width:100%;height:100%;rotate:none}._carousel_1ax8l_4{--prism-depth-sign:-1;width:100%;height:100%;transform-style:preserve-3d;transform-origin:50% 50% var(--prism-origin-depth);translate:0px 0px calc(var(--prism-camera-offset));transition:var(--prism-transition,none);display:flex;position:relative}._carousel_1ax8l_4>:not(._centerpiece_1ax8l_36){transform-origin:50% 50% var(--prism-origin-depth);transform-style:preserve-3d;margin:auto;position:absolute;inset:0}._centerpiece_1ax8l_36{transform-style:preserve-3d;translate:0px 0px var(--prism-origin-depth);transition:var(--prism-transition);margin:auto;position:absolute;inset:0}@media (prefers-reduced-motion:reduce){._carousel_1ax8l_4{transition:none}}}
+/*$vite$:1*/

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "react-prism-carousel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A 3D prism carousel for React, drawn entirely in CSS. You control the rotation.",
+  "keywords": [
+    "react",
+    "carousel",
+    "3d",
+    "prism",
+    "css",
+    "slider",
+    "component"
+  ],
+  "license": "MIT",
+  "author": "BlueWebber",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BlueWebber/react-prism-carousel.git"
+  },
+  "homepage": "https://github.com/BlueWebber/react-prism-carousel#readme",
+  "bugs": {
+    "url": "https://github.com/BlueWebber/react-prism-carousel/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./style.css": "./dist/style.css",
+    "./FOR-AI.md": "./FOR-AI.md",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "FOR-AI.md"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "llms": "./FOR-AI.md",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build && tsc -p tsconfig.lib.json",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.19.2",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "eslint": "^10.13.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.7",
+    "globals": "^17.13.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "typescript": "~7.0.2",
+    "typescript-eslint": "^8.72.0",
+    "vite": "^8.3.5"
+  }
+}