create-inox-app 0.1.0

package/dist/templates/claude-config/app/.agents/skills/building-components/references/as-child.mdx

@@ -0,0 +1,324 @@
+---
+title: asChild
+description: How to use the `asChild` prop to render a custom element within the component.
+type: reference
+summary: Using the asChild prop to replace default markup with custom elements while preserving component functionality and event handlers.
+prerequisites:
+  - /composition
+  - /types
+related:
+  - /polymorphism
+  - /state
+---
+
+The `asChild` prop is a powerful pattern in modern React component libraries. Popularized by [Radix UI](https://www.radix-ui.com/primitives/docs/guides/composition) and adopted by [shadcn/ui](https://ui.shadcn.com), this pattern allows you to replace default markup with custom elements while maintaining the component's functionality.
+
+## Understanding `asChild`
+
+At its core, `asChild` changes how a component renders. When set to `true`, instead of rendering its default DOM element, the component merges its props, behaviors, and event handlers with its immediate child element.
+
+### Without `asChild`
+
+```tsx
+<Dialog.Trigger>
+  <button>Open Dialog</button>
+</Dialog.Trigger>
+```
+
+This renders nested elements:
+
+```html
+<button data-state="closed">
+  <button>Open Dialog</button>
+</button>
+```
+
+### With `asChild`
+
+```tsx
+<Dialog.Trigger asChild>
+  <button>Open Dialog</button>
+</Dialog.Trigger>
+```
+
+This renders a single, merged element:
+
+```html
+<button data-state="closed">Open Dialog</button>
+```
+
+The Dialog.Trigger's functionality is composed onto your button, eliminating unnecessary wrapper elements.
+
+## How It Works
+
+Under the hood, `asChild` uses React's composition capabilities to merge components:
+
+```tsx
+// Simplified implementation
+function Component({ asChild, children, ...props }) {
+  if (asChild) {
+    // Clone child and merge props
+    return React.cloneElement(children, {
+      ...props,
+      ...children.props,
+      // Merge event handlers
+      onClick: (e) => {
+        props.onClick?.(e);
+        children.props.onClick?.(e);
+      },
+    });
+  }
+
+  // Render default element
+  return <button {...props}>{children}</button>;
+}
+```
+
+The component:
+
+1. Checks if `asChild` is true
+2. Clones the child element
+3. Merges props from both parent and child
+4. Combines event handlers
+5. Returns the enhanced child
+
+## Key Benefits
+
+### 1. Semantic HTML
+
+`asChild` lets you use the most appropriate HTML element for your use case:
+
+```tsx
+// Use a link for navigation
+<AlertDialog.Trigger asChild>
+  <a href="/delete">Delete Account</a>
+</AlertDialog.Trigger>
+
+// Use a custom button component
+<Tooltip.Trigger asChild>
+  <IconButton icon={<InfoIcon />} />
+</Tooltip.Trigger>
+```
+
+### 2. Clean DOM Structure
+
+Traditional composition often creates deeply nested DOM structures. `asChild` eliminates this "wrapper hell":
+
+```tsx
+// Without asChild: Nested wrappers
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger>
+      <button>
+        <span>Hover me</span>
+      </button>
+    </TooltipTrigger>
+  </Tooltip>
+</TooltipProvider>
+
+// With asChild: Clean structure
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <button>Hover me</button>
+    </TooltipTrigger>
+  </Tooltip>
+</TooltipProvider>
+```
+
+### 3. Design System Integration
+
+`asChild` enables seamless integration with your existing design system components:
+
+```tsx
+import { Button } from "@/components/ui/button";
+
+<DropdownMenu.Trigger asChild>
+  <Button variant="outline" size="icon">
+    <MoreVertical className="h-4 w-4" />
+  </Button>
+</DropdownMenu.Trigger>;
+```
+
+Your Button component receives all the necessary dropdown trigger behavior without modification.
+
+### 4. Component Composition
+
+You can compose multiple behaviors onto a single element:
+
+```tsx
+<Dialog.Trigger asChild>
+  <Tooltip.Trigger asChild>
+    <button>Open dialog (with tooltip)</button>
+  </Tooltip.Trigger>
+</Dialog.Trigger>
+```
+
+This creates a button that both opens a dialog and shows a tooltip on hover.
+
+## Common Use Cases
+
+### Custom Trigger Elements
+
+Replace default triggers with custom components:
+
+```tsx
+// Custom link trigger
+<Collapsible.Trigger asChild>
+  <a href="#" className="text-blue-600 underline">
+    Toggle Details
+  </a>
+</Collapsible.Trigger>
+
+// Icon-only trigger
+<Popover.Trigger asChild>
+  <IconButton>
+    <Settings className="h-4 w-4" />
+  </IconButton>
+</Popover.Trigger>
+```
+
+### Accessible Navigation
+
+Maintain proper semantics for navigation elements:
+
+```tsx
+<NavigationMenu.Link asChild>
+  <Link href="/products" className="nav-link">
+    Products
+  </Link>
+</NavigationMenu.Link>
+```
+
+### Form Integration
+
+Integrate with form libraries while preserving functionality:
+
+```tsx
+<FormField
+  control={form.control}
+  name="acceptTerms"
+  render={({ field }) => (
+    <FormItem>
+      <Checkbox.Root asChild>
+        <input type="checkbox" {...field} className="sr-only" />
+      </Checkbox.Root>
+    </FormItem>
+  )}
+/>
+```
+
+## Best Practices
+
+### 1. Maintain Accessibility
+
+When changing element types, ensure accessibility is preserved:
+
+```tsx
+// ✅ Good - maintains button semantics
+<Dialog.Trigger asChild>
+  <button type="button">Open</button>
+</Dialog.Trigger>
+
+// ⚠️ Caution - ensure proper ARIA attributes
+<Dialog.Trigger asChild>
+  <div role="button" tabIndex={0}>Open</div>
+</Dialog.Trigger>
+```
+
+### 2. Document Component Requirements
+
+Clearly document when components support `asChild`:
+
+```tsx
+interface TriggerProps {
+  /**
+   * Change the default rendered element for the one passed as a child,
+   * merging their props and behavior.
+   *
+   * @default false
+   */
+  asChild?: boolean;
+  children: React.ReactNode;
+}
+```
+
+### 3. Test Child Components
+
+Verify that custom components work correctly with `asChild`:
+
+```tsx
+// Test that props are properly forwarded
+const TestButton = (props) => {
+  console.log("Received props:", props);
+  return <button {...props} />;
+};
+
+<Tooltip.Trigger asChild>
+  <TestButton>Test</TestButton>
+</Tooltip.Trigger>;
+```
+
+### 4. Handle Edge Cases
+
+Consider edge cases like conditional rendering:
+
+```tsx
+// Handle conditional children
+<Dialog.Trigger asChild>
+  {isLoading ? (
+    <Skeleton className="h-10 w-20" />
+  ) : (
+    <Button>Open Dialog</Button>
+  )}
+</Dialog.Trigger>
+```
+
+## Common Pitfalls
+
+### Not Spreading Props
+
+As discussed in [Types](/docs/types), you should always spread props to the underlying element.
+
+```tsx
+// ❌ Won't receive trigger behavior
+const BadButton = ({ children }) => <button>{children}</button>;
+
+// ✅ Properly receives all props
+const GoodButton = ({ children, ...props }) => (
+  <button {...props}>{children}</button>
+);
+```
+
+### Multiple Children
+
+Don't pass multiple children to a component that supports `asChild`. This will cause an error as the component will not know which child to use.
+
+```tsx
+// ❌ Error - asChild expects single child
+<Trigger asChild>
+  <button>One</button>
+  <button>Two</button>
+</Trigger>
+
+// ✅ Single child element
+<Trigger asChild>
+  <button>Single Button</button>
+</Trigger>
+```
+
+### Fragment Children
+
+Don't pass a fragment to a component that supports `asChild`. This will cause an error as fragments are not valid elements.
+
+```tsx
+// ❌ Fragment is not a valid element
+<Trigger asChild>
+  <>Button</>
+</Trigger>
+
+// ✅ Actual element
+<Trigger asChild>
+  <button>Button</button>
+</Trigger>
+```

package/dist/templates/claude-config/app/.agents/skills/building-components/references/composition.mdx

@@ -0,0 +1,239 @@
+---
+title: Composition
+description: The foundation of building modern UI components.
+type: conceptual
+summary: How to break monolithic components into smaller, focused subcomponents using the compound component pattern and naming conventions.
+prerequisites:
+  - /definitions
+related:
+  - /types
+  - /state
+  - /as-child
+  - /polymorphism
+---
+
+Composition, or composability, is the foundation of building modern UI components. It is one of the most powerful techniques for creating flexible, reusable components that can handle complex requirements without sacrificing API clarity.
+
+Instead of cramming all functionality into a single component with dozens of props, composition distributes responsibility across multiple cooperating components.
+
+Fernando gave a great talk about this at React Universe Conf 2025, where he shared his approach to rebuilding Slack's Message Composer as a composable component.
+
+
+## Making a component composable
+
+To make a component composable, you need to break it down into smaller, more focused components. For example, let's take this Accordion component:
+
+```tsx title="accordion.tsx"
+import { Accordion } from "@/components/ui/accordion";
+
+const data = [
+  {
+    title: "Accordion 1",
+    content: "Accordion 1 content",
+  },
+  {
+    title: "Accordion 2",
+    content: "Accordion 2 content",
+  },
+  {
+    title: "Accordion 3",
+    content: "Accordion 3 content",
+  },
+];
+
+return <Accordion data={data} />;
+```
+
+While this Accordion component might seem simple, it's handling too many responsibilities. It's responsible for rendering the container, trigger and content; as well as handling the accordion state and data.
+
+Customizing the styling of this component is difficult because it's tightly coupled. It likely requires global CSS overrides. Additionally, adding new functionality or tweaking the behavior requires modifying the component source code.
+
+To solve this, we can break this down into smaller, more focused components.
+
+### 1. Root Component
+
+First, let's focus on the container - the component that holds everything together i.e. the trigger and content. This container doesn't need to know about the data, but it does need to keep track of the open state.
+
+However, we also want this state to be accessible by child components. So, let's use the Context API to create a context for the open state.
+
+Finally, to allow for modification of the `div` element, we'll extend the default HTML attributes.
+
+We'll call this component the "Root" component.
+
+```tsx title="@/components/ui/accordion.tsx"
+type AccordionProps = React.ComponentProps<"div"> & {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+};
+
+const AccordionContext = createContext<AccordionProps>({
+  open: false,
+  setOpen: () => {},
+});
+
+export type AccordionRootProps = React.ComponentProps<"div"> & {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+};
+
+export const Root = ({
+  children,
+  open,
+  setOpen,
+  ...props
+}: AccordionRootProps) => (
+  <AccordionContext.Provider value={{ open, setOpen }}>
+    <div {...props}>{children}</div>
+  </AccordionContext.Provider>
+);
+```
+
+### 2. Item Component
+
+The Item component is the element that contains the accordion item. It is simply a wrapper for each item in the accordion.
+
+```tsx title="@/components/ui/accordion.tsx"
+export type AccordionItemProps = React.ComponentProps<"div">;
+
+export const Item = (props: AccordionItemProps) => <div {...props} />;
+```
+
+### 3. Trigger Component
+
+The Trigger component is the element that opens the accordion when activated. It is responsible for:
+
+- Rendering as a button by default (can be customized with `asChild`)
+- Handling click events to open the accordion
+- Managing focus when accordion closes
+- Providing proper ARIA attributes
+
+Let's add this component to our Accordion component.
+
+```tsx title="@/components/ui/accordion.tsx"
+export type AccordionTriggerProps = React.ComponentProps<"button"> & {
+  asChild?: boolean;
+};
+
+export const Trigger = ({ asChild, ...props }: AccordionTriggerProps) => (
+  <AccordionContext.Consumer>
+    {({ open, setOpen }) => (
+      <button onClick={() => setOpen(!open)} {...props} />
+    )}
+  </AccordionContext.Consumer>
+);
+```
+
+### 4. Content Component
+
+The Content component is the element that contains the accordion content. It is responsible for:
+
+- Rendering the content when the accordion is open
+- Providing proper ARIA attributes
+
+Let's add this component to our Accordion component.
+
+```tsx title="@/components/ui/accordion.tsx"
+export type AccordionContentProps = React.ComponentProps<"div"> & {
+  asChild?: boolean;
+};
+
+export const Content = ({ asChild, ...props }: AccordionContentProps) => (
+  <AccordionContext.Consumer>
+    {({ open }) => <div {...props} />}
+  </AccordionContext.Consumer>
+);
+```
+
+### 5. Putting it all together
+
+Now that we have all the components, we can put them together in our original file.
+
+```tsx title="accordion.tsx"
+import * as Accordion from "@/components/ui/accordion";
+
+const data = [
+  {
+    title: "Accordion 1",
+    content: "Accordion 1 content",
+  },
+  {
+    title: "Accordion 2",
+    content: "Accordion 2 content",
+  },
+  {
+    title: "Accordion 3",
+    content: "Accordion 3 content",
+  },
+];
+
+return (
+  <Accordion.Root open={false} setOpen={() => {}}>
+    {data.map((item) => (
+      <Accordion.Item key={item.title}>
+        <Accordion.Trigger>{item.title}</Accordion.Trigger>
+        <Accordion.Content>{item.content}</Accordion.Content>
+      </Accordion.Item>
+    ))}
+  </Accordion.Root>
+);
+```
+
+## Naming Conventions
+
+When building composable components, consistent naming conventions are crucial for creating intuitive and predictable APIs. Both shadcn/ui and Radix UI follow established patterns that have become the de facto standard in the React ecosystem.
+
+### Root Components
+
+The `Root` component serves as the main container that wraps all other sub-components. It typically manages shared state and context by providing a context to all child components.
+
+```tsx
+<AccordionRoot>{/* Child components */}</AccordionRoot>
+```
+
+### Interactive Elements
+
+Interactive components that trigger actions or toggle states use descriptive names:
+
+- `Trigger` - The element that initiates an action (opening, closing, toggling)
+- `Content` - The element that contains the main content being shown/hidden
+
+```tsx
+<CollapsibleTrigger>Click to expand</CollapsibleTrigger>
+<CollapsibleContent>
+  Hidden content revealed here
+</CollapsibleContent>
+```
+
+### Content Structure
+
+For components with structured content areas, use semantic names that describe their purpose:
+
+- `Header` - Top section containing titles or controls
+- `Body` - Main content area
+- `Footer` - Bottom section for actions or metadata
+
+```tsx
+<DialogHeader>
+  {/* Dialog title */}
+</DialogHeader>
+<DialogBody>
+  {/* Dialog content */}
+</DialogBody>
+<DialogFooter>
+  {/* Dialog footer */}
+</DialogFooter>
+```
+
+### Informational Components
+
+Components that provide information or context use descriptive suffixes:
+
+- `Title` - Primary heading or label
+- `Description` - Supporting text or explanatory content
+
+```tsx
+<CardTitle>Project Statistics</CardTitle>
+<CardDescription>
+  View your project's performance over time
+</CardDescription>
+```