@alexgorbatchev/shadcn 0.0.19 → 0.0.20

package/llms/components/data-display/Carousel.md

@@ -0,0 +1,465 @@
+# Carousel
+
+Story: @alexgorbatchev/shadcn/components/data-display/Carousel
+Source: src/components/stories/data-display/Carousel.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/data-display/Carousel.stories.tsx)
+
+## Public imports
+
+```tsx
+import { type CarouselApi, Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious } from "@alexgorbatchev/shadcn/carousel";
+import { DirectionProvider, Input, Button } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import type { KeyboardEvent } from "react";
+import Autoplay from "embla-carousel-autoplay";
+import { useEffect, useState } from "react";
+```
+
+## Default component
+
+```tsx
+Carousel
+```
+
+## Story controls
+
+```tsx
+{ orientation: { control: "select", options: ["horizontal", "vertical"] } }
+```
+
+## Default args
+
+```tsx
+{ "aria-label": "Featured projects", onKeyDown: fn(), opts: { duration: 0 } }
+```
+
+## Default render
+
+```tsx
+function Render(args) {
+    const [api, setApi] = useState<CarouselApi>();
+    const [slide, setSlide] = useState(1);
+    useEffect(() => {
+        if (!api)
+            return;
+        const update = (): void => setSlide(api.selectedScrollSnap() + 1);
+        update();
+        api.on("select", update);
+        return () => {
+            api.off("select", update);
+        };
+    }, [api]);
+    return (<div className="flex flex-col gap-panel p-12">
+        <Carousel {...args} setApi={setApi} className="w-64">
+          <CarouselContent className={args.orientation === "vertical" ? "h-48" : undefined}>
+            {Array.from({ length: 3 }, (_, index) => (<CarouselItem key={index} aria-label={`${index + 1} of 3`}>
+                <div className="flex h-full min-h-40 flex-col items-center justify-center gap-control-gap border border-border p-panel">
+                  <span>Project {index + 1}</span>
+                  <Input aria-label={`Project ${index + 1} caption`} defaultValue="Caption"/>
+                </div>
+              </CarouselItem>))}
+          </CarouselContent>
+          <CarouselPrevious />
+          <CarouselNext />
+        </Carousel>
+        <output aria-label="Current slide">{slide} of 3</output>
+      </div>);
+}
+```
+
+## Examples
+
+Storybook CSF excerpts. Default args and render apply unless overridden. Local helpers, fixtures, decorators, and providers may be required; these are reference excerpts, not standalone consumer modules. Interaction tests are omitted.
+
+### Horizontal
+
+```tsx
+{}
+```
+
+### Vertical
+
+```tsx
+{
+    args: { orientation: "vertical" }
+}
+```
+
+### RightToLeft
+
+```tsx
+{
+    args: { opts: { direction: "rtl", duration: 0 } }
+}
+```
+
+### NestedControl
+
+```tsx
+{}
+```
+
+### KeyboardFocus
+
+```tsx
+{}
+```
+
+### KeyboardFocusRtl
+
+```tsx
+{
+    args: { opts: { direction: "rtl", duration: 0 } }
+}
+```
+
+### CancelledKeyboard
+
+```tsx
+{
+    args: { onKeyDown: fn((event: KeyboardEvent<HTMLDivElement>) => event.preventDefault()) }
+}
+```
+
+### Compact
+
+```tsx
+{
+    args: { density: "compact" }
+}
+```
+
+### Loop
+
+```tsx
+{
+    args: { opts: { loop: true, duration: 0 } }
+}
+```
+
+### VerticalRtl
+
+```tsx
+{
+    args: { orientation: "vertical" },
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <Story />
+      </DirectionProvider>),
+    ]
+}
+```
+
+### Sizes
+
+```tsx
+{
+    render: (args) => <CarouselGalleryExample {...args}/>
+}
+```
+
+### SizesRtl
+
+```tsx
+{
+    render: (args) => <CarouselGalleryExample {...args}/>,
+    decorators: VerticalRtl.decorators
+}
+```
+
+### ResponsiveSizes
+
+```tsx
+{
+    render: (args) => <CarouselGalleryExample {...args} hasResponsiveSizes/>
+}
+```
+
+### ResponsiveSizesRtl
+
+```tsx
+{
+    render: (args) => <CarouselGalleryExample {...args} hasResponsiveSizes/>,
+    decorators: VerticalRtl.decorators
+}
+```
+
+### Spacing
+
+```tsx
+{
+    render: (args) => <CarouselGalleryExample {...args} hasWideSpacing/>
+}
+```
+
+### SpacingRtl
+
+```tsx
+{
+    render: (args) => <CarouselGalleryExample {...args} hasWideSpacing/>,
+    decorators: VerticalRtl.decorators
+}
+```
+
+### CancelledNext
+
+```tsx
+{
+    render: (args) => <CarouselGalleryExample {...args} isNavigationCancelled/>
+}
+```
+
+### CancelledNextRtl
+
+```tsx
+{
+    render: (args) => <CarouselGalleryExample {...args} isNavigationCancelled/>,
+    decorators: VerticalRtl.decorators
+}
+```
+
+### Api
+
+```tsx
+{
+    render: function Render(args) {
+        const [api, setApi] = useState<CarouselApi>();
+        const [count, setCount] = useState(3);
+        const [snap, setSnap] = useState(1);
+        const [snaps, setSnaps] = useState(0);
+        useEffect(() => {
+            if (!api)
+                return;
+            const update = (): void => {
+                setSnap(api.selectedScrollSnap() + 1);
+                setSnaps(api.scrollSnapList().length);
+            };
+            update();
+            api.on("select", update);
+            api.on("reInit", update);
+            return () => {
+                api.off("select", update);
+                api.off("reInit", update);
+            };
+        }, [api]);
+        return (<div className="flex flex-col items-start gap-panel p-12">
+        <Carousel {...args} setApi={setApi} className="w-64">
+          <CarouselContent>
+            {Array.from({ length: count }, (_, index) => (<CarouselItem key={index} aria-label={`${index + 1} of ${count}`}>
+                <div className="flex min-h-40 items-center justify-center border border-border">
+                  Project {index + 1}
+                </div>
+              </CarouselItem>))}
+          </CarouselContent>
+          <CarouselPrevious />
+          <CarouselNext />
+        </Carousel>
+        <div className="flex gap-control-gap">
+          <Button disabled={!api} onClick={() => api?.scrollTo(snaps - 1, true)}>
+            Go to last project
+          </Button>
+          <Button onClick={() => setCount(count + 1)}>Add project</Button>
+        </div>
+        <output aria-label="API selection">
+          {snap} of {snaps}
+        </output>
+      </div>);
+    }
+}
+```
+
+### ApiRtl
+
+```tsx
+{
+    render: function Render(args) {
+        const [api, setApi] = useState<CarouselApi>();
+        const [count, setCount] = useState(3);
+        const [snap, setSnap] = useState(1);
+        const [snaps, setSnaps] = useState(0);
+        useEffect(() => {
+            if (!api)
+                return;
+            const update = (): void => {
+                setSnap(api.selectedScrollSnap() + 1);
+                setSnaps(api.scrollSnapList().length);
+            };
+            update();
+            api.on("select", update);
+            api.on("reInit", update);
+            return () => {
+                api.off("select", update);
+                api.off("reInit", update);
+            };
+        }, [api]);
+        return (<div className="flex flex-col items-start gap-panel p-12">
+        <Carousel {...args} setApi={setApi} className="w-64">
+          <CarouselContent>
+            {Array.from({ length: count }, (_, index) => (<CarouselItem key={index} aria-label={`${index + 1} of ${count}`}>
+                <div className="flex min-h-40 items-center justify-center border border-border">
+                  Project {index + 1}
+                </div>
+              </CarouselItem>))}
+          </CarouselContent>
+          <CarouselPrevious />
+          <CarouselNext />
+        </Carousel>
+        <div className="flex gap-control-gap">
+          <Button disabled={!api} onClick={() => api?.scrollTo(snaps - 1, true)}>
+            Go to last project
+          </Button>
+          <Button onClick={() => setCount(count + 1)}>Add project</Button>
+        </div>
+        <output aria-label="API selection">
+          {snap} of {snaps}
+        </output>
+      </div>);
+    },
+    decorators: VerticalRtl.decorators
+}
+```
+
+### AutoplayPlugin
+
+```tsx
+{
+    render: function Render(args) {
+        const [plugin] = useState(() => Autoplay({ playOnInit: false, delay: 1000, jump: true }));
+        const [api, setApi] = useState<CarouselApi>();
+        const [snap, setSnap] = useState(1);
+        const [isPlaying, setPlaying] = useState(false);
+        useEffect(() => {
+            if (!api)
+                return;
+            const select = (): void => setSnap(api.selectedScrollSnap() + 1);
+            const play = (): void => setPlaying(true), stop = (): void => setPlaying(false);
+            api.on("select", select);
+            api.on("autoplay:play", play);
+            api.on("autoplay:stop", stop);
+            return () => {
+                api.off("select", select);
+                api.off("autoplay:play", play);
+                api.off("autoplay:stop", stop);
+            };
+        }, [api]);
+        return (<div className="flex flex-col items-start gap-panel p-12">
+        <Carousel {...args} setApi={setApi} plugins={[plugin]} className="w-64">
+          <CarouselContent>
+            {Array.from({ length: 3 }, (_, index) => (<CarouselItem key={index} aria-label={`${index + 1} of 3`}>
+                <div className="flex min-h-40 flex-col items-center justify-center gap-panel border border-border p-panel">
+                  <span>Project {index + 1}</span>
+                  <Input aria-label={`Project ${index + 1} caption`}/>
+                </div>
+              </CarouselItem>))}
+          </CarouselContent>
+          <CarouselPrevious />
+          <CarouselNext />
+        </Carousel>
+        <div className="flex gap-control-gap">
+          <Button disabled={!api || isPlaying} onClick={() => plugin.play()}>
+            Start autoplay
+          </Button>
+          <Button disabled={!isPlaying} onClick={() => plugin.stop()}>
+            Stop autoplay
+          </Button>
+        </div>
+        <output aria-label="Autoplay state">{isPlaying ? "Playing" : "Paused"}</output>
+        <output aria-label="Autoplay slide">{snap}</output>
+      </div>);
+    }
+}
+```
+
+### AutoplayPluginRtl
+
+```tsx
+{
+    render: function Render(args) {
+        const [plugin] = useState(() => Autoplay({ playOnInit: false, delay: 1000, jump: true }));
+        const [api, setApi] = useState<CarouselApi>();
+        const [snap, setSnap] = useState(1);
+        const [isPlaying, setPlaying] = useState(false);
+        useEffect(() => {
+            if (!api)
+                return;
+            const select = (): void => setSnap(api.selectedScrollSnap() + 1);
+            const play = (): void => setPlaying(true), stop = (): void => setPlaying(false);
+            api.on("select", select);
+            api.on("autoplay:play", play);
+            api.on("autoplay:stop", stop);
+            return () => {
+                api.off("select", select);
+                api.off("autoplay:play", play);
+                api.off("autoplay:stop", stop);
+            };
+        }, [api]);
+        return (<div className="flex flex-col items-start gap-panel p-12">
+        <Carousel {...args} setApi={setApi} plugins={[plugin]} className="w-64">
+          <CarouselContent>
+            {Array.from({ length: 3 }, (_, index) => (<CarouselItem key={index} aria-label={`${index + 1} of 3`}>
+                <div className="flex min-h-40 flex-col items-center justify-center gap-panel border border-border p-panel">
+                  <span>Project {index + 1}</span>
+                  <Input aria-label={`Project ${index + 1} caption`}/>
+                </div>
+              </CarouselItem>))}
+          </CarouselContent>
+          <CarouselPrevious />
+          <CarouselNext />
+        </Carousel>
+        <div className="flex gap-control-gap">
+          <Button disabled={!api || isPlaying} onClick={() => plugin.play()}>
+            Start autoplay
+          </Button>
+          <Button disabled={!isPlaying} onClick={() => plugin.stop()}>
+            Stop autoplay
+          </Button>
+        </div>
+        <output aria-label="Autoplay state">{isPlaying ? "Playing" : "Paused"}</output>
+        <output aria-label="Autoplay slide">{snap}</output>
+      </div>);
+    },
+    decorators: VerticalRtl.decorators
+}
+```
+
+### CustomNavigation
+
+```tsx
+{
+    render: function Render(args) {
+        const [isLocked, setLocked] = useState(false);
+        const [isCancelled, setCancelled] = useState(true);
+        return (<div className="flex flex-col items-start gap-panel p-48">
+        <Carousel {...args} opts={{ duration: 0 }} className="w-64">
+          <CarouselContent>
+            {["First", "Second", "Third"].map((label) => (<CarouselItem key={label} aria-label={label}>
+                <div className="flex h-40 items-center justify-center border border-border">{label}</div>
+              </CarouselItem>))}
+          </CarouselContent>
+          <CarouselPrevious size="default" className={(state) => (state.disabled ? "w-40" : "w-32")} disabled={isLocked} onClick={(event) => {
+                if (isCancelled)
+                    event.preventDefault();
+            }}>
+            Earlier project
+          </CarouselPrevious>
+          <CarouselNext size="default" variant="secondary" className={() => "w-32"} disabled={isLocked}>
+            Later project
+          </CarouselNext>
+        </Carousel>
+        <Button onClick={() => setLocked(!isLocked)}>{isLocked ? "Unlock navigation" : "Lock navigation"}</Button>
+        <Button onClick={() => setCancelled(false)}>Allow earlier project</Button>
+      </div>);
+    }
+}
+```
+
+### UnhandledKeyboard
+
+```tsx
+{}
+```