@blakesteve/roster 5.1.0 → 5.2.0

package/README.md

@@ -491,6 +491,9 @@ the sweep stops and the highlight parks off-frame. The highlight is deliberately
 exempt from that bar: it is a specular pass on screen for a fraction of a second
 per glyph, and holding it to 3:1 would flatten the effect.
 
+`Spinner` holds still under reduced motion: the arc still reads as loading, and
+its `label` (default "loading") says so.
+
 ### Scrollbars
 
 `custom-scrollbar` gives any scrollable surface a slim themed scrollbar.
@@ -1104,6 +1107,47 @@ escape the box. Lay the options out across with `orientation` rather than
 through `optionsClassName`, for the same reason: the horizontal spacing that
 keeps two radios 44px apart rides on that prop.
 
+### Carousel
+
+A sideways row: a row of cards, a selection strip, or a gallery of one per
+view. It is a real scroll container with CSS scroll snap, so touch, trackpad,
+Shift with the wheel and keyboard focus all scroll it without script, and every
+item is in the server render. No clones, no virtualization, no loop, and
+nothing moves on its own.
+
+```tsx
+<Carousel aria-label="Songs" itemWidth={240} gap={12} gutter={16}>
+  {songs.map((song) => <SongCard key={song.id} song={song} />)}
+</Carousel>
+```
+
+Each child is one item, wrapped in the `li` the row snaps to. Size the items
+with `itemWidth` (fixed) or `perView` (fluid: `{ base: 1.3, md: 2.5 }`, where
+the fraction is the peek of the next item). `gutter` is both the inline padding
+and the scroll padding, so a snapped item lines up with the text above it, and
+`bleed` pulls the row out by one gutter to run edge to edge.
+
+Script adds what a mouse is missing:
+
+- **Drag.** A mouse drags the row one to one and it settles on the nearest
+  item. A drag past 6px drops the one click that ends it, and nothing else.
+  Touch and pen keep native scrolling.
+- **Arrows.** Previous and next page by as many items as are wholly in view,
+  measured each time, and land on an item's edge. At an end the arrow is
+  `disabled`, out of the tab order. They show where a pointer can hover, on a
+  line above the row by default (`arrowPlacement="overlay"` floats them over
+  the ends; `renderArrows` puts them anywhere, such as a heading line). They
+  are 44px, drawn with inline SVG, and named "Next" plus the row's label.
+- **Keyboard focus** snaps its item into place at once. If no item can take
+  focus, the list itself is the tab stop.
+
+A vertical wheel over the row scrolls the page, and sideways overscroll is
+contained. Under reduced motion every scroll the component makes is instant.
+`ref` gives `scrollToIndex(i)`, `scrollPrev()` and `scrollNext()`;
+`onIndexChange` reports the first item wholly in view. For a gallery,
+`showPosition` shows "2 of 5", which is also each item's name and is announced
+politely when it changes.
+
 ### Components that render links
 
 `Breadcrumbs` renders a plain `<a>` by default, which is right for a static
@@ -1171,7 +1215,7 @@ function App() {
 | `Disclosure`         | Show/hide toggle using HeadlessUI                                                                            |
 | `Eyebrow`            | Small tracked-out uppercase label above a heading or beside a rule; polymorphic via `as`                     |
 | `InlineCode`         | Inline `<code>` for identifiers in running prose                                                             |
-| `Input`              | Text input with label, error state, icon slots, and a size scale matching `Button`                           |
+| `Input`              | Text input with label, error state, icon slots, and a size scale matching `Button`; keeps a passed `aria-invalid` |
 | `LabeledDivider`     | Horizontal rule carrying a label, with an optional trailing count                                            |
 | `Link`               | Styled anchor with variant support                                                                           |
 | `MultiSelect`        | A `Select` that holds more than one value: dismissible chips, same panel                                     |
@@ -1197,8 +1241,9 @@ function App() {
 | `Breadcrumbs`     | Navigation trail; pass `linkComponent` to keep navigation client-side       |
 | `CheckboxGroup`   | Checkbox set reporting one `string[]`; groups, columns, scroll, error       |
 | `CallToAction`    | Prominent hero-style CTA block                                              |
+| `Carousel`        | Sideways row of items on native scroll snap; mouse drag, paging arrows, no autoplay |
 | `DescriptionList` | Label and value pairs as a real `<dl>`: inline, stacked, or split           |
-| `EmptyState`      | Zero-data placeholder with icon and action slot                             |
+| `EmptyState`      | Zero-data placeholder with icon and action slot; `headingLevel` sets its title's `h1` to `h6` |
 | `ErrorState`      | Error display with retry action                                             |
 | `LiquidNav`       | `LiquidTabs`' strip as a `nav` of links; takes a router's link component    |
 | `LiquidTabs`      | Tab strip with a sliding pill; arrow keys, roving focus, 44px `lg` size     |
@@ -1217,7 +1262,7 @@ function App() {
 | `Dialog`    | Modal dialog                                                                                                                                                       |
 | `Footer`    | Site footer                                                                                                                                                        |
 | `Navbar`    | Responsive navigation bar with mobile slide-out                                                                                                                    |
-| `Sheet`     | Bottom sheet: drag, Escape or backdrop to dismiss; only its content scrolls; returns focus, even from a deep link                                                  |
+| `Sheet`     | Bottom sheet: drag, Escape or backdrop to dismiss; only its content scrolls; returns focus, even from a deep link; the title may be a node |
 | `Table`     | Static data table                                                                                                                                                  |
 
 ### DataTable columns
@@ -1370,6 +1415,15 @@ reason and the build goes green on the state it inherited while still failing on
 anything new. It also fails when a listed class starts emitting, so a fix cannot
 leave a stale entry behind. Run it with `--verbose` to print the list.
 
+Story tests that need the user's own input, a wheel or a mouse drag, get it
+from `.storybook/real-input.ts`: Vitest browser commands that drive
+Playwright's mouse, whose events are trusted. A synthetic wheel or pointer
+event never scrolls anything, so "a vertical wheel scrolls the page, not the
+row" can't be tested without them. The commands fail loudly when the pointer
+isn't over their target, rather than letting a wheel land on the page and a
+test pass for the wrong reason. Storybook's own UI has no such input, so those
+steps are skipped there.
+
 `src/lib/utils.test.ts` pins `cn`. `tailwind-merge` has to be configured with the
 prefix or it stops recognising Roster's classes as utilities and silently
 degrades to concatenation: conflicting classes both survive and the winner falls

package/dist/components/atoms/Input/Input.cjs

@@ -1 +1 @@
-"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("react/jsx-runtime"),b=require("react"),h=require("../../../node_modules/@headlessui/react/dist/components/description/description.cjs"),y=require("../../../node_modules/@headlessui/react/dist/components/field/field.cjs"),g=require("../../../node_modules/@headlessui/react/dist/components/input/input.cjs"),v=require("../../../node_modules/@headlessui/react/dist/components/label/label.cjs"),t=require("../../../lib/utils.cjs"),a=require("./input-variants.cjs"),m=b.forwardRef(({className:x,type:p,label:o,helperText:u,errorMessage:e,variant:i,size:n,error:f,startIcon:c,endIcon:l,disabled:d,inputClassName:j,...q},N)=>{const s=!!e||f;return r.jsxs(y.Field,{disabled:d,className:t.cn("rst:w-full",x),children:[o&&r.jsx(v.Label,{className:t.cn("rst:block rst:text-sm rst:font-medium rst:leading-none rst:text-left rst:mb-1.5 rst:transition-colors","rst:text-[var(--roster-control-text)]","rst:peer-disabled:cursor-not-allowed rst:peer-disabled:opacity-70"),children:o}),r.jsxs("div",{className:"rst:relative",children:[c&&r.jsx("div",{className:t.cn(a.iconVariants({variant:i,error:s}),"rst:left-3"),children:c}),r.jsx(g.Input,{ref:N,type:p,disabled:d,className:t.cn(a.inputVariants({variant:i,size:n,error:s}),c&&(n==="sm"?"rst:pl-9":"rst:pl-10"),l&&(n==="sm"?"rst:pr-9":"rst:pr-10"),j),...q}),l&&r.jsx("div",{className:t.cn(a.iconVariants({variant:i,error:s}),"rst:right-3"),children:l})]}),(u||e)&&r.jsx(h.Description,{className:t.cn("rst:text-xs rst:text-left rst:mt-1.5",s?"rst:text-error-600 rst:dark:text-error-400 rst:font-medium":"rst:text-gray-500 rst:dark:text-gray-400"),children:e||u})]})});m.displayName="Input";exports.Input=m;
+"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("react/jsx-runtime"),g=require("react"),V=require("../../../node_modules/@headlessui/react/dist/components/description/description.cjs"),k=require("../../../node_modules/@headlessui/react/dist/components/field/field.cjs"),w=require("../../../node_modules/@headlessui/react/dist/components/input/input.cjs"),P=require("../../../node_modules/@headlessui/react/dist/components/label/label.cjs"),t=require("../../../lib/utils.cjs"),o=require("./input-variants.cjs"),m=g.forwardRef(({className:x,type:f,label:d,helperText:u,errorMessage:e,variant:i,size:n,error:v,startIcon:a,endIcon:l,disabled:p,inputClassName:j,...q},N)=>{const s=!!e||v,{"aria-invalid":c,invalid:b,...h}=q,y=!!b||c!==void 0&&c!==!1&&c!=="false";return r.jsxs(k.Field,{disabled:p,className:t.cn("rst:w-full",x),children:[d&&r.jsx(P.Label,{className:t.cn("rst:block rst:text-sm rst:font-medium rst:leading-none rst:text-left rst:mb-1.5 rst:transition-colors","rst:text-[var(--roster-control-text)]","rst:peer-disabled:cursor-not-allowed rst:peer-disabled:opacity-70"),children:d}),r.jsxs("div",{className:"rst:relative",children:[a&&r.jsx("div",{className:t.cn(o.iconVariants({variant:i,error:s}),"rst:left-3"),children:a}),r.jsx(w.Input,{ref:N,type:f,disabled:p,className:t.cn(o.inputVariants({variant:i,size:n,error:s}),a&&(n==="sm"?"rst:pl-9":"rst:pl-10"),l&&(n==="sm"?"rst:pr-9":"rst:pr-10"),j),...h,invalid:y}),l&&r.jsx("div",{className:t.cn(o.iconVariants({variant:i,error:s}),"rst:right-3"),children:l})]}),(u||e)&&r.jsx(V.Description,{className:t.cn("rst:text-xs rst:text-left rst:mt-1.5",s?"rst:text-error-600 rst:dark:text-error-400 rst:font-medium":"rst:text-gray-500 rst:dark:text-gray-400"),children:e||u})]})});m.displayName="Input";exports.Input=m;

package/dist/components/atoms/Input/Input.js

@@ -1,29 +1,33 @@
 "use client";
-import { jsxs as n, jsx as t } from "react/jsx-runtime";
-import b from "react";
-import { Description as k } from "../../../node_modules/@headlessui/react/dist/components/description/description.js";
-import { Field as v } from "../../../node_modules/@headlessui/react/dist/components/field/field.js";
-import { Input as w } from "../../../node_modules/@headlessui/react/dist/components/input/input.js";
-import { Label as g } from "../../../node_modules/@headlessui/react/dist/components/label/label.js";
+import { jsxs as c, jsx as t } from "react/jsx-runtime";
+import g from "react";
+import { Description as j } from "../../../node_modules/@headlessui/react/dist/components/description/description.js";
+import { Field as P } from "../../../node_modules/@headlessui/react/dist/components/field/field.js";
+import { Input as R } from "../../../node_modules/@headlessui/react/dist/components/input/input.js";
+import { Label as V } from "../../../node_modules/@headlessui/react/dist/components/label/label.js";
 import { cn as r } from "../../../lib/utils.js";
-import { iconVariants as d, inputVariants as j } from "./input-variants.js";
-const R = b.forwardRef(
+import { iconVariants as f, inputVariants as _ } from "./input-variants.js";
+const D = g.forwardRef(
   ({
-    className: f,
-    type: x,
-    label: l,
-    helperText: c,
-    errorMessage: e,
-    variant: o,
-    size: m,
-    error: u,
-    startIcon: a,
-    endIcon: i,
+    className: x,
+    type: u,
+    label: n,
+    helperText: d,
+    errorMessage: i,
+    variant: e,
+    size: a,
+    error: v,
+    startIcon: o,
+    endIcon: l,
     disabled: p,
     inputClassName: N,
     ...h
   }, y) => {
-    const s = !!e || u;
+    const s = !!i || v, {
+      "aria-invalid": m,
+      invalid: b,
+      ...k
+    } = h, w = !!b || m !== void 0 && m !== !1 && m !== "false";
     return (
       /* No `space-y-*` here, deliberately. Headless UI's Field appends a
           hidden zero-height <span> after the control, and Tailwind v4 applies
@@ -38,72 +42,73 @@ const R = b.forwardRef(
          DisabledProvider stays false and the Label and Description never dim.
          Fixed in both rather than one, because a form with a disabled Input
          and a disabled Select that grey differently is worse than neither. */
-      /* @__PURE__ */ n(v, { disabled: p, className: r("rst:w-full", f), children: [
-        l && /* @__PURE__ */ t(
-          g,
+      /* @__PURE__ */ c(P, { disabled: p, className: r("rst:w-full", x), children: [
+        n && /* @__PURE__ */ t(
+          V,
           {
             className: r(
               "rst:block rst:text-sm rst:font-medium rst:leading-none rst:text-left rst:mb-1.5 rst:transition-colors",
               "rst:text-[var(--roster-control-text)]",
               "rst:peer-disabled:cursor-not-allowed rst:peer-disabled:opacity-70"
             ),
-            children: l
+            children: n
           }
         ),
-        /* @__PURE__ */ n("div", { className: "rst:relative", children: [
-          a && /* @__PURE__ */ t(
+        /* @__PURE__ */ c("div", { className: "rst:relative", children: [
+          o && /* @__PURE__ */ t(
             "div",
             {
               className: r(
-                d({ variant: o, error: s }),
+                f({ variant: e, error: s }),
                 "rst:left-3"
               ),
-              children: a
+              children: o
             }
           ),
           /* @__PURE__ */ t(
-            w,
+            R,
             {
               ref: y,
-              type: x,
+              type: u,
               disabled: p,
               className: r(
-                j({ variant: o, size: m, error: s }),
+                _({ variant: e, size: a, error: s }),
                 /* Icon inset tracks the size's own padding: sm is px-3, so it
                    needs one step less clearance than the 16px sizes. */
-                a && (m === "sm" ? "rst:pl-9" : "rst:pl-10"),
-                i && (m === "sm" ? "rst:pr-9" : "rst:pr-10"),
+                o && (a === "sm" ? "rst:pl-9" : "rst:pl-10"),
+                l && (a === "sm" ? "rst:pr-9" : "rst:pr-10"),
                 N
               ),
-              ...h
+              ...k,
+              invalid: w
             }
           ),
-          i && /* @__PURE__ */ t(
+          l && /* @__PURE__ */ t(
             "div",
             {
               className: r(
-                d({ variant: o, error: s }),
+                f({ variant: e, error: s }),
                 "rst:right-3"
               ),
-              children: i
+              children: l
             }
           )
         ] }),
-        (c || e) && /* @__PURE__ */ t(
-          k,
+        (d || i) && /* @__PURE__ */ t(
+          j,
           {
             className: r(
               "rst:text-xs rst:text-left rst:mt-1.5",
               s ? "rst:text-error-600 rst:dark:text-error-400 rst:font-medium" : "rst:text-gray-500 rst:dark:text-gray-400"
             ),
-            children: e || c
+            children: i || d
           }
         )
       ] })
     );
   }
 );
-R.displayName = "Input";
+D.displayName = "Input";
 export {
-  R as Input
+  D as Input
 };

package/dist/components/atoms/Spinner/Spinner.cjs

@@ -1 +1 @@
-"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const a=require("react/jsx-runtime"),n=require("../../../node_modules/class-variance-authority/dist/index.cjs"),d=require("../../../lib/utils.cjs"),o=n.cva("rst:animate-spin rst:rounded-full rst:transition-colors",{variants:{variant:{primary:"rst:border-primary-600 rst:dark:border-primary-500",neutral:"rst:border-gray-600 rst:dark:border-gray-400",danger:"rst:border-error-600 rst:dark:border-error-500",white:"rst:border-white",current:"rst:border-current"},size:{sm:"rst:h-4 rst:w-4 rst:border-2",md:"rst:h-6 rst:w-6 rst:border-[3px]",lg:"rst:h-8 rst:w-8 rst:border-4"},animation:{classic:"rst:border-solid rst:border-r-transparent rst:dark:border-r-transparent",half:"rst:border-solid rst:border-r-transparent rst:border-b-transparent rst:dark:border-r-transparent rst:dark:border-b-transparent",dashed:"rst:border-dashed",dotted:"rst:border-dotted rst:border-r-transparent rst:dark:border-r-transparent"}},defaultVariants:{variant:"primary",size:"md",animation:"classic"}}),i=({variant:r,size:t,animation:s,className:e})=>a.jsx("div",{className:d.cn(o({variant:r,size:t,animation:s}),e),role:"status","aria-label":"loading"});exports.Spinner=i;
+"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("react/jsx-runtime"),d=require("../../../node_modules/class-variance-authority/dist/index.cjs"),o=require("../../../lib/utils.cjs"),i=d.cva("rst:animate-spin rst:motion-reduce:animate-none rst:rounded-full rst:transition-colors",{variants:{variant:{primary:"rst:border-primary-600 rst:dark:border-primary-500",neutral:"rst:border-gray-600 rst:dark:border-gray-400",danger:"rst:border-error-600 rst:dark:border-error-500",white:"rst:border-white",current:"rst:border-current"},size:{sm:"rst:h-4 rst:w-4 rst:border-2",md:"rst:h-6 rst:w-6 rst:border-[3px]",lg:"rst:h-8 rst:w-8 rst:border-4"},animation:{classic:"rst:border-solid rst:border-r-transparent rst:dark:border-r-transparent",half:"rst:border-solid rst:border-r-transparent rst:border-b-transparent rst:dark:border-r-transparent rst:dark:border-b-transparent",dashed:"rst:border-dashed",dotted:"rst:border-dotted rst:border-r-transparent rst:dark:border-r-transparent"}},defaultVariants:{variant:"primary",size:"md",animation:"classic"}}),b=({variant:r,size:t,animation:e,className:s,label:a="loading"})=>n.jsx("div",{className:o.cn(i({variant:r,size:t,animation:e}),s),role:"status","aria-label":a});exports.Spinner=b;

package/dist/components/atoms/Spinner/Spinner.d.ts

@@ -6,6 +6,11 @@ declare const spinnerVariants: (props?: ({
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export interface SpinnerProps extends VariantProps<typeof spinnerVariants> {
     className?: string;
+    /**
+     * What a screen reader hears: "loading" by default. Say what is loading
+     * ("Loading results") when there is more than one on screen.
+     */
+    label?: string;
 }
-export declare const Spinner: ({ variant, size, animation, className, }: SpinnerProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Spinner: ({ variant, size, animation, className, label, }: SpinnerProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/atoms/Spinner/Spinner.js

@@ -1,8 +1,8 @@
 "use client";
-import { jsx as e } from "react/jsx-runtime";
-import { cva as d } from "../../../node_modules/class-variance-authority/dist/index.js";
-import { cn as o } from "../../../lib/utils.js";
-const n = /* @__PURE__ */ d("rst:animate-spin rst:rounded-full rst:transition-colors", {
+import { jsx as d } from "react/jsx-runtime";
+import { cva as o } from "../../../node_modules/class-variance-authority/dist/index.js";
+import { cn as n } from "../../../lib/utils.js";
+const i = /* @__PURE__ */ o("rst:animate-spin rst:motion-reduce:animate-none rst:rounded-full rst:transition-colors", {
   variants: {
     variant: {
       primary: "rst:border-primary-600 rst:dark:border-primary-500",
@@ -36,13 +36,14 @@ const n = /* @__PURE__ */ d("rst:animate-spin rst:rounded-full rst:transition-co
   variant: r,
   size: t,
   animation: s,
-  className: a
-}) => /* @__PURE__ */ e(
+  className: a,
+  label: e = "loading"
+}) => /* @__PURE__ */ d(
   "div",
   {
-    className: o(n({ variant: r, size: t, animation: s }), a),
+    className: n(i({ variant: r, size: t, animation: s }), a),
     role: "status",
-    "aria-label": "loading"
+    "aria-label": e
   }
 );
 export {

package/dist/components/molecules/Carousel/Carousel.cjs

@@ -0,0 +1 @@
+"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("react/jsx-runtime"),Fe=require("react"),qe=require("../../atoms/Button/Button.cjs"),T=require("../../../lib/utils.cjs"),$e=require("../../../internal/motion.cjs"),u=require("./carousel-math.cjs"),U=require("./carousel-layout.cjs");function Be(a){const i=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(a){for(const d in a)if(d!=="default"){const b=Object.getOwnPropertyDescriptor(a,d);Object.defineProperty(i,d,b.get?b:{enumerable:!0,get:()=>a[d]})}}return i.default=a,Object.freeze(i)}const n=Be(Fe),ze=a=>Math.min(3e3,500+a*.35),He='a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]), [contenteditable]:not([contenteditable="false"])',V=a=>typeof a=="number"?`${a}px`:a;function ne(a){const i=parseFloat(a);return Number.isFinite(i)?i:0}const Ue="rst:hidden rst:[@media(any-hover:hover)]:inline-flex",Ve="rst:hidden rst:[@media(any-hover:hover)]:flex";function se({direction:a}){return l.jsx("svg",{"aria-hidden":"true",focusable:"false",viewBox:"0 0 20 20",className:"rst:h-5 rst:w-5",fill:"none",stroke:"currentColor",strokeWidth:"2",strokeLinecap:"round",strokeLinejoin:"round",children:l.jsx("path",{d:a==="prev"?"M12.5 4.5 7 10l5.5 5.5":"M7.5 4.5 13 10l-5.5 5.5"})})}const oe={overflowing:null,canScrollPrev:!1,canScrollNext:!1,index:0},We=n.forwardRef(function({"aria-label":i,"aria-labelledby":d,children:b,itemWidth:I,perView:k,gap:W=12,gutter:X=16,bleed:le=!1,snap:L="start",snapStrictness:ce="mandatory",oneAtATime:ae=!1,arrows:j="hover",arrowPlacement:M="controls",renderArrows:P,prevLabel:ie,nextLabel:ue,prevIcon:de,nextIcon:fe,arrowButtonProps:ge,fade:ve=!1,scrollbar:pe=!1,showPosition:G=!1,onIndexChange:J,onScrollStateChange:K,itemClassName:me,listClassName:xe,className:be,style:he,...Se},ye){const v=n.useRef(null),Q=`${n.useId()}-list`,Y=n.Children.toArray(b),E=Y.length,[o,we]=n.useState(oe),Z=n.useRef(oe),[Ne,Te]=n.useState(""),[Ie,Pe]=n.useState(!1),O=n.useRef({onIndexChange:J,onScrollStateChange:K});n.useEffect(()=>{O.current={onIndexChange:J,onScrollStateChange:K}});const f=n.useCallback(()=>{const e=v.current;if(!e)return null;const t=e.getBoundingClientRect(),r=getComputedStyle(e),s=t.left+e.clientLeft-e.scrollLeft;return{items:Array.from(e.children).map(g=>{const x=g.getBoundingClientRect();return{start:x.left-s,end:x.right-s}}),scrollLeft:e.scrollLeft,clientWidth:e.clientWidth,scrollWidth:e.scrollWidth,paddingStart:ne(r.scrollPaddingInlineStart||r.scrollPaddingLeft),paddingEnd:ne(r.scrollPaddingInlineEnd||r.scrollPaddingRight),align:L}},[L]),h=n.useCallback(()=>{const e=f();if(!e)return;const t={overflowing:u.overflows(e),canScrollPrev:u.canScrollPrev(e),canScrollNext:u.canScrollNext(e),index:e.items.length?u.currentIndex(e):0},r=Z.current;r.overflowing===t.overflowing&&r.canScrollPrev===t.canScrollPrev&&r.canScrollNext===t.canScrollNext&&r.index===t.index||(Z.current=t,we(t),r.index!==t.index&&O.current.onIndexChange?.(t.index),(r.canScrollPrev!==t.canScrollPrev||r.canScrollNext!==t.canScrollNext)&&O.current.onScrollStateChange?.({canScrollPrev:t.canScrollPrev,canScrollNext:t.canScrollNext}))},[f]),Ee=JSON.stringify([W,X,I,k]);n.useLayoutEffect(()=>{const e=v.current;if(!e)return;h();let t=0;const r=()=>{t||(t=requestAnimationFrame(()=>{t=0,h()}))};e.addEventListener("scroll",r,{passive:!0});const s=typeof ResizeObserver>"u"?null:new ResizeObserver(()=>h()),c=()=>{s?.observe(e),Array.from(e.children).forEach(x=>s?.observe(x))};c();const g=typeof MutationObserver>"u"?null:new MutationObserver(()=>{c(),h()});return g?.observe(e,{childList:!0}),()=>{e.removeEventListener("scroll",r),s?.disconnect(),g?.disconnect(),t&&cancelAnimationFrame(t)}},[h,E,Ee]),n.useLayoutEffect(()=>{const e=v.current;if(e&&(Pe(!e.querySelector(He)),d)){const t=d.split(/\s+/).map(r=>document.getElementById(r)?.textContent?.trim()??"").filter(Boolean).join(" ");Te(t)}},[b,d]);const S=n.useRef(null),p=n.useCallback(()=>{const e=v.current,t=S.current;t&&(S.current=null,window.clearTimeout(t.timer),e?.removeEventListener("scrollend",t.done),e&&(e.style.scrollSnapType="",delete e.dataset.settling))},[]),m=n.useCallback((e,t)=>{const r=v.current;if(!r)return;if(p(),t!=="smooth"||$e.prefersReducedMotion()||Math.abs(r.scrollLeft-e)<1){r.style.scrollSnapType="none",r.scrollTo({left:e,behavior:"instant"}),r.style.scrollSnapType="";return}r.style.scrollSnapType="none",r.dataset.settling="";const c=()=>p();S.current={timer:window.setTimeout(c,ze(Math.abs(r.scrollLeft-e))),done:c,target:e},r.addEventListener("scrollend",c,{once:!0}),r.scrollTo({left:e,behavior:"smooth"})},[p]),C=n.useCallback(e=>{const t=f();if(!t)return;const r=S.current?{...t,scrollLeft:S.current.target}:t;m(u.pageTarget(r,e),"smooth")},[f,m]);n.useImperativeHandle(ye,()=>({scrollToIndex:(e,t)=>{const r=f();if(!r||!r.items.length)return;const s=Math.min(Math.max(0,Math.round(e)),r.items.length-1);m(u.snapPosition(r,s),t?.behavior??"smooth")},scrollPrev:()=>C(-1),scrollNext:()=>C(1)}),[f,C,m]),n.useEffect(()=>p,[p]);const D=n.useRef(null),_=n.useRef(null),A=n.useRef(null);n.useLayoutEffect(()=>{const e=A.current;if(!e)return;const t=e==="prev"?D.current:_.current,r=e==="prev"?_.current:D.current,s=e==="prev"?!o.canScrollPrev:!o.canScrollNext,c=document.activeElement;s&&(c!==t&&c!==document.body&&c!==null||r&&!r.disabled&&r.focus())},[o.canScrollPrev,o.canScrollNext]);const y=n.useRef(null),w=n.useRef(!1),Ce=e=>{e.pointerType!=="mouse"||e.button!==0||o.overflowing&&(p(),w.current=!1,y.current={pointerId:e.pointerId,x0:e.clientX,scroll0:e.currentTarget.scrollLeft,dragging:!1})},Re=e=>{const t=y.current;if(!t||e.pointerId!==t.pointerId)return;const r=e.currentTarget,s=e.clientX-t.x0;if(!t.dragging){if(Math.abs(s)<=u.CAROUSEL_DRAG_THRESHOLD)return;t.dragging=!0,r.dataset.dragging="",r.style.scrollSnapType="none",window.getSelection?.()?.removeAllRanges();try{r.setPointerCapture(e.pointerId)}catch{}}r.scrollLeft=t.scroll0-s},F=e=>{const t=y.current;if(!t||e.pointerId!==t.pointerId||(y.current=null,!t.dragging))return;const r=e.currentTarget;delete r.dataset.dragging,w.current=e.type==="pointerup",window.setTimeout(()=>{w.current=!1},0);const s=f();s?m(u.snapPosition(s,u.nearestIndex(s)),"smooth"):r.style.scrollSnapType=""},ke=e=>{!w.current||e.detail===0||(w.current=!1,e.preventDefault(),e.stopPropagation())},Le=e=>{o.overflowing&&e.preventDefault()},je=e=>{const t=e.currentTarget,r=e.target;if(r===t||y.current?.dragging)return;let s=!1;try{s=r.matches(":focus-visible")}catch{s=!1}if(!s)return;const c=r.closest("[data-carousel-item]");if(!c||c.parentElement!==t)return;const g=f();if(!g)return;const x=Array.prototype.indexOf.call(t.children,c);m(u.snapPosition(g,x),"instant")},[Me,Oe]=n.useState(0);n.useEffect(()=>{const e=window.setTimeout(()=>Oe(o.index),150);return()=>window.clearTimeout(e)},[o.index]);const ee=i??Ne,te=e=>ee?`${e} ${ee}`:e,q=j!=="none"&&o.overflowing!==!1,De=j==="hover"?Ue:"rst:inline-flex",re=e=>{const t=e==="prev",{className:r,...s}=ge??{};return l.jsx(qe.Button,{type:"button",variant:"outline",colorScheme:"neutral",size:"icon",...s,"aria-label":t?ie??te("Previous"):ue??te("Next"),"aria-controls":Q,disabled:t?!o.canScrollPrev:!o.canScrollNext,onClick:()=>C(t?-1:1),ref:t?D:_,onFocus:()=>{A.current=e},onBlur:c=>{c.relatedTarget&&(A.current=null)},"data-carousel-arrow":e,className:T.cn("rst:size-11 rst:shrink-0 rst:rounded-full",M==="overlay"&&!P&&"rst:bg-[var(--roster-popover-bg)] rst:elevation-raised rst:hover:bg-[var(--roster-popover-bg)] rst:disabled:invisible",De,r),children:t?de??l.jsx(se,{direction:"prev"}):fe??l.jsx(se,{direction:"next"})})},R=q?re("prev"):null,$=q?re("next"):null,N=G&&E?l.jsxs("p",{"aria-live":"polite",className:"rst:font-ui rst:m-0 rst:text-sm rst:tabular-nums rst:opacity-75","data-carousel-position":"",children:[Me+1," of ",E]}):null;let B=null;P?B=P({prev:R,next:$,position:N}):M==="controls"&&(R||N)&&(B=l.jsxs("div",{className:T.cn("rst:mb-2 rst:items-center rst:justify-end rst:gap-2",!N&&j==="hover"?Ve:"rst:flex"),"data-carousel-controls":"",children:[N&&l.jsx("div",{className:"rst:mr-auto",children:N}),R,$]}));const z=ve&&o.overflowing&&(o.canScrollPrev||o.canScrollNext)?`linear-gradient(to right, ${o.canScrollPrev?"transparent, black 48px":"black"}, ${o.canScrollNext?"black calc(100% - 48px), transparent":"black"})`:void 0,H=I===void 0&&k!==void 0,_e={"--rst-cv-gap":V(W),"--rst-cv-gutter":V(X),...H?U.perViewVars(k):{},...z?{maskImage:z,WebkitMaskImage:z}:{}},Ae=I!==void 0?{width:V(I)}:H?{width:U.FLUID_ITEM_WIDTH}:void 0;return l.jsxs("div",{className:T.cn("rst:min-w-0",be),style:he,...Se,children:[B,l.jsxs("div",{className:"rst:relative",children:[l.jsx("ul",{ref:v,id:Q,role:"list","aria-label":i,"aria-labelledby":i?void 0:d,tabIndex:Ie&&o.overflowing?0:void 0,"data-overflowing":o.overflowing?"":void 0,onPointerDown:Ce,onPointerMove:Re,onPointerUp:F,onPointerCancel:F,onLostPointerCapture:F,onClickCapture:ke,onDragStart:Le,onFocus:je,style:_e,className:T.cn("rst:m-0 rst:flex rst:list-none rst:overflow-x-auto rst:overflow-y-hidden","rst:gap-(--rst-cv-gap) rst:px-(--rst-cv-gutter) rst:py-1 rst:scroll-px-(--rst-cv-gutter)","rst:overscroll-x-contain",ce==="mandatory"?"rst:snap-x rst:snap-mandatory":"rst:snap-x rst:snap-proximity",le&&"rst:-mx-(--rst-cv-gutter)",!pe&&"rst:[scrollbar-width:none] rst:[&::-webkit-scrollbar]:hidden",H&&U.FLUID_CLASSES,"rst:data-overflowing:cursor-grab rst:data-dragging:cursor-grabbing rst:data-dragging:select-none","rst:focus-visible:outline-hidden rst:focus-visible:ring-2 rst:focus-visible:ring-ring rst:focus-visible:ring-inset",xe),children:Y.map((e,t)=>l.jsx("li",{"data-carousel-item":"","aria-label":G?`${t+1} of ${E}`:void 0,style:Ae,className:T.cn("rst:shrink-0",L==="start"?"rst:snap-start":"rst:snap-center",ae&&"rst:snap-always",me),children:e},n.isValidElement(e)&&e.key!=null?e.key:t))}),!P&&M==="overlay"&&q&&l.jsxs(l.Fragment,{children:[l.jsx("div",{className:"rst:pointer-events-none rst:absolute rst:inset-y-0 rst:start-1 rst:flex rst:items-center",children:l.jsx("div",{className:"rst:pointer-events-auto",children:R})}),l.jsx("div",{className:"rst:pointer-events-none rst:absolute rst:inset-y-0 rst:end-1 rst:flex rst:items-center",children:l.jsx("div",{className:"rst:pointer-events-auto",children:$})})]})]})]})});exports.Carousel=We;

package/dist/components/molecules/Carousel/Carousel.d.ts

@@ -0,0 +1,146 @@
+import { ButtonProps } from '../../atoms/Button/Button';
+import * as React from "react";
+/** Items per view at each width, from Roster's breakpoints up. */
+export interface CarouselPerView {
+    base: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+}
+export interface CarouselHandle {
+    /** Snaps item `i` into place. Instant under reduced motion, whatever is asked. */
+    scrollToIndex: (index: number, options?: {
+        behavior?: ScrollBehavior;
+    }) => void;
+    /** What the previous arrow does: back one page. */
+    scrollPrev: () => void;
+    /** What the next arrow does: on one page. */
+    scrollNext: () => void;
+}
+export interface CarouselArrowsRender {
+    /** The previous arrow, or `null` while the row fits and there is nothing to page. */
+    prev: React.ReactNode;
+    next: React.ReactNode;
+    /** The "2 of 5" readout when `showPosition` is on, otherwise `null`. */
+    position: React.ReactNode;
+}
+export interface CarouselProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "aria-label" | "aria-labelledby"> {
+    /** The row's name. One of this or `aria-labelledby` is required. */
+    "aria-label"?: string;
+    /** The id of the heading that names the row. */
+    "aria-labelledby"?: string;
+    /** One child per item. Each is wrapped in the list item the row snaps to. */
+    children: React.ReactNode;
+    /**
+     * Fixed mode: every item is this wide (a number is px). The row overflows
+     * once the items and gaps outgrow the box, and the next item peeks from then
+     * on.
+     */
+    itemWidth?: number | string;
+    /**
+     * Fluid mode: how many items are in view at each width, and the component
+     * sizes them. A fraction is the peek: `1.3` is one item and a third of the
+     * next. Ignored when `itemWidth` is set.
+     */
+    perView?: number | CarouselPerView;
+    /** Space between items. A number is px. */
+    gap?: number | string;
+    /**
+     * The inline padding at each end, and the scroll padding a snapped item
+     * lines up with. Match the page's own gutter so a snapped item sits under
+     * the text above it. A number is px.
+     */
+    gutter?: number | string;
+    /**
+     * Pulls the row out by one gutter on each side, so it runs to the edges of
+     * its container while the first item still lines up with the text.
+     */
+    bleed?: boolean;
+    /** Where an item settles. */
+    snap?: "start" | "center";
+    /** `mandatory` always settles on an item; `proximity` only near one. */
+    snapStrictness?: "mandatory" | "proximity";
+    /** One item per swipe, for a gallery of one per view (`scroll-snap-stop: always`). */
+    oneAtATime?: boolean;
+    /**
+     * When the arrows show. `hover`, the default, is wherever a pointer can
+     * hover: a touch-only screen swipes instead, and gets no arrows to aim at.
+     */
+    arrows?: "hover" | "always" | "none";
+    /**
+     * `controls`, the default, puts the arrows on a line of their own above the
+     * row, where they never cover an item or the peek and never fight a drag.
+     * `overlay` floats them over the row's two ends and takes no space.
+     * `renderArrows` overrides both.
+     */
+    arrowPlacement?: "controls" | "overlay";
+    /**
+     * Put the arrows (and the position readout) anywhere: a heading line beside
+     * a "See all" link, say. What it returns replaces the default controls line,
+     * so a heading rendered here sits above the row as before.
+     */
+    renderArrows?: (parts: CarouselArrowsRender) => React.ReactNode;
+    /** The previous arrow's accessible name. Defaults to "Previous" and the row's label. */
+    prevLabel?: string;
+    /** The next arrow's accessible name. Defaults to "Next" and the row's label. */
+    nextLabel?: string;
+    /** Replaces the previous arrow's chevron. */
+    prevIcon?: React.ReactNode;
+    /** Replaces the next arrow's chevron. */
+    nextIcon?: React.ReactNode;
+    /** Passed to both arrow buttons, over the defaults. */
+    arrowButtonProps?: Omit<ButtonProps, "onClick" | "disabled" | "children" | "aria-label">;
+    /**
+     * Fades the edge on a side with more to see. Never at an end, so the last
+     * item is never faded.
+     */
+    fade?: boolean;
+    /** Shows the native scrollbar. Hidden by default; the arrows and the mouse drag stand in for it. */
+    scrollbar?: boolean;
+    /**
+     * Shows "2 of 5", for a gallery of one item per view. It is also each item's
+     * name, and a change is announced politely.
+     */
+    showPosition?: boolean;
+    /** The first item wholly in view, whenever it changes. */
+    onIndexChange?: (index: number) => void;
+    /** Whether the row can move each way, whenever that changes. */
+    onScrollStateChange?: (state: {
+        canScrollPrev: boolean;
+        canScrollNext: boolean;
+    }) => void;
+    /** Classes for each list item. */
+    itemClassName?: string;
+    /** Classes for the scrolling list. `className` is the outer wrapper. */
+    listClassName?: string;
+}
+/**
+ * A sideways row of items: a row of cards, a selection strip, a gallery of one
+ * per view.
+ *
+ * Native first. The row is a real scroll container with CSS scroll snap, so
+ * touch, trackpad, Shift with the wheel and focus all scroll it without
+ * script, and every item is in the server render: no clones, no
+ * virtualization, no loop, and nothing moves on its own.
+ *
+ * Script adds what a mouse is missing. Pressing and dragging moves the row one
+ * to one and settles it on the nearest item; a drag past 6px drops the one
+ * click that ends it and nothing else. Previous and next arrows page by as
+ * many items as are wholly in view, measured each time, and are `disabled`,
+ * out of the tab order, at an end. A vertical wheel over the row scrolls the
+ * page, and sideways overscroll is contained so a swipe at an end can't go
+ * back a page.
+ *
+ * Keyboard focus moving onto an item snaps that item into place at once. If
+ * no item can take focus, the list itself is the tab stop, so a keyboard can
+ * still scroll it.
+ *
+ * Under reduced motion every programmatic scroll is instant: the arrows, the
+ * settle after a drag, and `scrollToIndex`.
+ *
+ * Renders a `ul` named by `aria-label` or `aria-labelledby`, one `li` per
+ * child. There is no carousel role and no slide role: nothing rotates.
+ */
+declare const Carousel: React.ForwardRefExoticComponent<CarouselProps & React.RefAttributes<CarouselHandle>>;
+export { Carousel };