chore: carousel examples

Author: segunadebayo

.claude/agents/component-example-creator.md

@@ -58,7 +58,10 @@ When creating examples for a component:
 
 6. **Update Documentation** (if applicable): Ensure the component's documentation includes:
    - Code snippets matching the new examples
-   - Clear descriptions of when to use each variant
+   - **Specific implementation details**: Which props go on which components, what methods to call
+   - **Use cases and benefits**: When and why to use each pattern
+   - **Built-in vs composition**: Clarify if features require composition or are built-in
+   - **State synchronization**: Explain bidirectional sync when relevant
    - Accessibility notes
    - Links to related components or patterns
 

.claude/commands/sync-docs.md

@@ -0,0 +1,49 @@
+---
+description: Update documentation and agent files based on learnings from recent component development work
+---
+
+Review the conversation history and identify patterns, best practices, and learnings from recent component development
+work. Then update the following files as needed:
+
+## Files to Update
+
+1. **`@.claude/docs/component_patterns.md`**
+   - Add new component patterns discovered
+   - Document common pitfalls and solutions
+   - Add best practices for component API usage
+   - Include documentation writing guidelines
+
+2. **`@.claude/agents/component-example-creator.md`**
+   - Update code quality standards based on learnings
+   - Add new documentation guidelines
+   - Include patterns for better example creation
+
+3. **`@CLAUDE.md`** (if needed)
+   - Update project-level guidance
+   - Add new principles or conventions
+
+## What to Include
+
+Focus on **generic, reusable patterns** that will help with future component development:
+
+- Component API access patterns (Context vs hooks)
+- Common styling requirements
+- Documentation writing best practices
+- State management patterns
+- Accessibility considerations
+- Cross-framework consistency guidelines
+
+## What to Exclude
+
+Skip component-specific implementations unless they represent a broader pattern that applies to multiple components.
+
+## Process
+
+1. Review recent work and identify patterns
+2. Read current documentation files to avoid duplication
+3. Add new sections or update existing ones with clear examples
+4. Use ✅ CORRECT / ❌ WRONG patterns for clarity
+5. Include rationale for why patterns are important
+6. Keep updates concise and actionable
+
+After updating, provide a summary of what was added and why it will help future development work.

.claude/docs/component_patterns.md

@@ -28,7 +28,8 @@ packages/{framework}/src/components/{component-name}/
 
 ## Creating New Examples
 
-**IMPORTANT: When adding examples, ALL steps below must be completed. Missing any step means the example is incomplete.**
+**IMPORTANT: When adding examples, ALL steps below must be completed. Missing any step means the example is
+incomplete.**
 
 When creating a new example for a component, you **MUST** update the following files:
 
@@ -41,33 +42,41 @@ When creating a new example for a component, you **MUST** update the following f
 2. **Update Storybook stories for all frameworks** (REQUIRED - examples won't appear without this):
    - `packages/react/src/components/{component}/{component}.stories.tsx` - Add export in alphabetical order
    - `packages/solid/src/components/{component}/{component}.stories.tsx` - Add export in alphabetical order
-   - `packages/vue/src/components/{component}/{component}.stories.vue` - Add import and `<Variant>` in alphabetical order
-   - `packages/svelte/src/lib/components/{component}/{component}.stories.ts` - Add import and export in alphabetical order
+   - `packages/vue/src/components/{component}/{component}.stories.vue` - Add import and `<Variant>` in alphabetical
+     order
+   - `packages/svelte/src/lib/components/{component}/{component}.stories.ts` - Add import and export in alphabetical
+     order
 
 3. **Update component documentation** (if applicable):
    - `website/src/content/pages/components/{component}.mdx` - Add `<Example id="{example-name}" />` with description
 
-**Note**: Steps 1 and 2 are MANDATORY. Without updating the stories files, the examples will not be visible in Storybook.
+**Note**: Steps 1 and 2 are MANDATORY. Without updating the stories files, the examples will not be visible in
+Storybook.
 
 ### Example Workflow
 
 For a new "links" example on the Menu component:
 
 1. Create example files in all four frameworks
 2. Update stories:
+
    ```tsx
    // React/Solid: Add to exports
    export { Links } from './examples/links'
 
    // Vue: Add to imports and template
    import Links from './examples/links.vue'
-   <Variant title="Links"><Links /></Variant>
+   ;<Variant title="Links">
+     <Links />
+   </Variant>
 
    // Svelte: Add import and export
    import LinksExample from './examples/links.svelte'
    export const Links = { render: () => ({ Component: LinksExample }) }
    ```
+
 3. Update MDX documentation:
+
    ```mdx
    ### Menu with links
 
@@ -206,13 +215,15 @@ Every component should include these example patterns where applicable:
 
 ## Root Provider Pattern (Critical)
 
-**The `root-provider` example is essential for most components** as it demonstrates external state management using component hooks.
+**The `root-provider` example is essential for most components** as it demonstrates external state management using
+component hooks.
 
 ### Two Approaches: Choose One
 
 There are two ways to use components - pick one approach, never mix them:
 
 **Approach 1: Component.Root (Declarative)**
+
 - Pass props directly to `Component.Root`
 - Component manages its own internal state
 - Limited access to state and methods
@@ -226,6 +237,7 @@ There are two ways to use components - pick one approach, never mix them:
 ```
 
 **Approach 2: useComponent + RootProvider (Programmatic)**
+
 - Call `useComponent(props)` to get the component API/store
 - Pass the store to `Component.RootProvider`
 - Full access to state properties and methods (`.setOpen()`, `.open`, etc.)
@@ -245,16 +257,20 @@ return (
 ```
 
 **❌ NEVER mix both approaches:**
+
 ```tsx
 // ❌ WRONG - Don't use Root inside RootProvider
 <Dialog.RootProvider value={dialog}>
-  <Dialog.Root> {/* This is incorrect! */}
+  <Dialog.Root>
+    {' '}
+    {/* This is incorrect! */}
     <Dialog.Content />
   </Dialog.Root>
 </Dialog.RootProvider>
 ```
 
-The benefit of `useComponent + RootProvider` is direct access to the component's state and methods, enabling programmatic control from anywhere in your component.
+The benefit of `useComponent + RootProvider` is direct access to the component's state and methods, enabling
+programmatic control from anywhere in your component.
 
 ### React Pattern
 
@@ -297,9 +313,7 @@ export const Example = () => {
   return (
     <Dialog.RootProvider value={dialog}>
       <Dialog.Trigger>Open</Dialog.Trigger>
-      <Dialog.Content>
-        {/* Content */}
-      </Dialog.Content>
+      <Dialog.Content>{/* Content */}</Dialog.Content>
     </Dialog.RootProvider>
   )
 }
@@ -342,9 +356,7 @@ export const Example = () => {
   return (
     <Dialog.RootProvider value={dialog}>
       <Dialog.Trigger>Open</Dialog.Trigger>
-      <Dialog.Content>
-        {/* Content */}
-      </Dialog.Content>
+      <Dialog.Content>{/* Content */}</Dialog.Content>
     </Dialog.RootProvider>
   )
 }
@@ -584,15 +596,15 @@ import { Teleport } from 'vue'
 ```ts
 // React/Svelte Portal Props
 interface PortalProps {
-  disabled?: boolean        // Renders inline when true
-  container?: HTMLElement   // Custom mount point
-  children: ReactNode       // Content to portal
+  disabled?: boolean // Renders inline when true
+  container?: HTMLElement // Custom mount point
+  children: ReactNode // Content to portal
 }
 
 // Vue Teleport Props
 interface TeleportProps {
-  to: string | Element      // Target selector or element
-  disabled?: boolean        // Renders inline when true
+  to: string | Element // Target selector or element
+  disabled?: boolean // Renders inline when true
 }
 ```
 
@@ -608,6 +620,7 @@ interface TeleportProps {
 ### Accessibility Testing
 
 **vitest-axe Integration:**
+
 ```ts
 import { axe } from 'vitest-axe'
 import { render } from '@testing-library/react' // or framework equivalent
@@ -620,6 +633,7 @@ test('should not have accessibility violations', async () => {
 ```
 
 **Keyboard Navigation Testing:**
+
 ```ts
 import { fireEvent } from '@testing-library/react'
 
@@ -641,6 +655,7 @@ test('should handle keyboard navigation', async () => {
 ```
 
 **ARIA Attributes Testing:**
+
 ```ts
 test('should have correct ARIA attributes', () => {
   render(<Component expanded={true} />)
@@ -654,29 +669,34 @@ test('should have correct ARIA attributes', () => {
 ### Cross-Framework Testing Patterns
 
 **React Testing:**
+
 ```ts
 import { render, screen } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 ```
 
 **Solid Testing:**
+
 ```ts
 import { render, screen } from '@solidjs/testing-library'
 ```
 
 **Vue Testing:**
+
 ```ts
 import { render, screen } from '@testing-library/vue'
 ```
 
 **Svelte Testing:**
+
 ```ts
 import { render, screen } from '@testing-library/svelte'
 ```
 
 ### Component State Testing
 
 **Controlled vs Uncontrolled:**
+
 ```ts
 test('controlled component', () => {
   const onValueChange = vi.fn()
@@ -699,6 +719,7 @@ test('uncontrolled component', () => {
 ### Screen Reader Compatibility
 
 **Announcement Testing:**
+
 ```ts
 test('should announce state changes', async () => {
   render(<Component />)
@@ -714,6 +735,7 @@ test('should announce state changes', async () => {
 ```
 
 **Focus Management:**
+
 ```ts
 test('should manage focus correctly', () => {
   render(<Dialog />)
@@ -749,4 +771,9 @@ test('should manage focus correctly', () => {
 - Minimize re-renders with proper memoization
 - Use lazy mounting for heavy components (`lazy-mount.tsx`)
 - Implement proper cleanup in unmount handlers
-- Follow framework-specific performance patterns
+- Follow framework-specific performance patterns
+
+### When to Use Each Approach
+
+- **Use `Component.Context`**: When you need to access the API for composition within the component tree
+- **Use `useComponent + RootProvider`**: When you need external control and state management outside the component

.storybook/styles/carousel.css

@@ -66,8 +66,8 @@
   border: none;
   justify-content: center;
   align-items: center;
-  height: 12px;
-  width: 12px;
+  min-height: 12px;
+  min-width: 12px;
   border-radius: 6px;
   cursor: pointer;
   background-color: lightgray;

packages/react/src/components/carousel/carousel.stories.tsx

@@ -9,4 +9,10 @@ export default meta
 export { Autoplay } from './examples/autoplay'
 export { Basic } from './examples/basic'
 export { Controlled } from './examples/controlled'
+export { CustomIndicator } from './examples/custom-indicator'
+export { DynamicSlides } from './examples/dynamic-slides'
+export { PauseOnHover } from './examples/pause-on-hover'
 export { RootProvider } from './examples/root-provider'
+export { ScrollTo } from './examples/scroll-to'
+export { SlidesPerPage } from './examples/slides-per-page'
+export { Vertical } from './examples/vertical'

packages/react/src/components/carousel/examples/custom-indicator.tsx

@@ -0,0 +1,45 @@
+import { Carousel } from '@ark-ui/react/carousel'
+
+export const CustomIndicator = () => {
+  const images = Array.from({ length: 5 }, (_, i) => `https://picsum.photos/seed/${i + 1}/500/300`)
+
+  return (
+    <Carousel.Root defaultPage={0} slideCount={images.length}>
+      <Carousel.Control>
+        <Carousel.PrevTrigger>Previous</Carousel.PrevTrigger>
+        <Carousel.NextTrigger>Next</Carousel.NextTrigger>
+      </Carousel.Control>
+      <Carousel.ItemGroup>
+        {images.map((image, index) => (
+          <Carousel.Item key={index} index={index}>
+            <img src={image} alt={`Slide ${index}`} style={{ width: '100%', height: '300px', objectFit: 'cover' }} />
+          </Carousel.Item>
+        ))}
+      </Carousel.ItemGroup>
+      <Carousel.Context>
+        {(api) => (
+          <Carousel.IndicatorGroup style={{ display: 'flex', gap: '8px', marginTop: '16px' }}>
+            {images.map((image, index) => (
+              <Carousel.Indicator key={index} index={index}>
+                <img
+                  src={image}
+                  alt={`Thumbnail ${index}`}
+                  style={{
+                    width: '60px',
+                    height: '40px',
+                    objectFit: 'cover',
+                    cursor: 'pointer',
+                    border: api.page === index ? '2px solid #0066ff' : '2px solid transparent',
+                    borderRadius: '4px',
+                    opacity: api.page === index ? 1 : 0.6,
+                    transition: 'all 0.2s',
+                  }}
+                />
+              </Carousel.Indicator>
+            ))}
+          </Carousel.IndicatorGroup>
+        )}
+      </Carousel.Context>
+    </Carousel.Root>
+  )
+}