@svelte-atoms/core 1.0.0-alpha.23 → 1.0.0-alpha.25

package/dist/utils/variant.js

@@ -0,0 +1,137 @@
+/**
+ * Variant System for @svelte-atoms/core
+ *
+ * A simple, single-function approach to defining component variants.
+ * Define variants once, use everywhere with full type safety and bond state access.
+ *
+ * Goals:
+ * 1. Single function returns all variants for a component
+ * 2. Access internal component state (via bond) for reactive variants
+ * 3. Return both classes AND other attributes (aria, data, etc.)
+ * 4. Type-safe with autocompletion
+ * 5. No context, no complexity
+ */
+/**
+ * Define variants for a component
+ * Returns a function that takes variant props and returns classes + attributes
+ *
+ * @example
+ * ```ts
+ * // Option 1: Static config (no bond access needed)
+ * const buttonVariants = defineVariants({
+ *   class: 'rounded-md font-medium transition-colors',
+ *   variants: {
+ *     variant: {
+ *       primary: 'bg-blue-500 text-white hover:bg-blue-600',
+ *       secondary: 'bg-gray-500 text-white hover:bg-gray-600'
+ *     },
+ *     size: {
+ *       sm: 'px-2 py-1 text-sm',
+ *       md: 'px-4 py-2 text-base',
+ *       lg: 'px-6 py-3 text-lg'
+ *     }
+ *   },
+ *   compounds: [
+ *     {
+ *       variant: 'primary',
+ *       size: 'lg',
+ *       class: 'shadow-lg'
+ *     }
+ *   ],
+ *   defaults: {
+ *     variant: 'primary',
+ *     size: 'md'
+ *   }
+ * });
+ *
+ * // Option 2: Dynamic config (with bond access)
+ * const buttonVariants = defineVariants((bond) => ({
+ *   class: 'rounded-md font-medium transition-colors',
+ *   variants: {
+ *     variant: {
+ *       primary: 'bg-blue-500 text-white hover:bg-blue-600',
+ *       secondary: 'bg-gray-500 text-white hover:bg-gray-600',
+ *       danger: bond?.state?.disabled
+ *         ? 'bg-red-300 text-white'
+ *         : 'bg-red-500 text-white hover:bg-red-600'
+ *     },
+ *     size: {
+ *       sm: 'px-2 py-1 text-sm',
+ *       md: 'px-4 py-2 text-base',
+ *       lg: 'px-6 py-3 text-lg'
+ *     }
+ *   },
+ *   compounds: [
+ *     {
+ *       variant: 'primary',
+ *       size: 'lg',
+ *       class: 'shadow-lg'
+ *     }
+ *   ],
+ *   defaults: {
+ *     variant: 'primary',
+ *     size: 'md'
+ *   }
+ * }));
+ *
+ * // Usage in component:
+ * const props = buttonVariants({ variant: 'primary', size: 'lg', bond });
+ * // Returns: { class: '...' }
+ * ```
+ */
+export function defineVariants(config) {
+    return (bond, props) => {
+        // Get config (either static or dynamic based on bond)
+        const resolvedConfig = typeof config === 'function' ? config(bond) : config;
+        // Merge with defaults
+        const finalProps = { ...resolvedConfig.defaults, ...props };
+        // Collect classes and attributes
+        const classes = [];
+        const attributes = {};
+        // Add base class
+        if (resolvedConfig.class)
+            classes.push(resolvedConfig.class);
+        // Add variant classes and attributes
+        for (const [key, value] of Object.entries(finalProps)) {
+            const variantValue = resolvedConfig.variants?.[key]?.[value];
+            if (variantValue !== undefined) {
+                const resolved = typeof variantValue === 'function' ? variantValue(bond) : variantValue;
+                if (typeof resolved === 'string') {
+                    classes.push(resolved);
+                }
+                else if (typeof resolved === 'object' && resolved !== null) {
+                    if ('class' in resolved) {
+                        classes.push(resolved.class);
+                    }
+                    // Add other attributes (aria-*, data-*, etc.)
+                    Object.entries(resolved).forEach(([k, v]) => {
+                        if (k !== 'class') {
+                            attributes[k] = v;
+                        }
+                    });
+                }
+            }
+        }
+        // Add compound variants
+        if (resolvedConfig.compounds) {
+            for (const compound of resolvedConfig.compounds) {
+                const { class: compoundClass, ...compoundProps } = compound;
+                const matches = Object.entries(compoundProps).every(([key, value]) => finalProps[key] === value);
+                if (matches) {
+                    if (compoundClass)
+                        classes.push(compoundClass);
+                    // Add compound attributes
+                    Object.entries(compound).forEach(([k, v]) => {
+                        if (k !== 'class' && !Object.keys(compoundProps).includes(k)) {
+                            attributes[k] = v;
+                        }
+                    });
+                }
+            }
+        }
+        return {
+            class: classes,
+            ...attributes
+        };
+    };
+}

package/llm/composition.md

@@ -0,0 +1,395 @@
+# Component Composition in @svelte-atoms/core
+
+## Overview
+
+@svelte-atoms/core components are designed to be **composable** — you can combine them to extend both behavior and UI, creating powerful component combinations. This is achieved through three main patterns:
+
+1. **Base Prop Composition** - Replace a component's root element with another component
+2. **Bond Pattern** - Access and share component state across nested components
+3. **Nested Children** - Compose components as siblings/parents for complex UIs
+
+## 1. Base Prop Composition
+
+The `base=` prop allows you to replace a component's root element with another component, **inheriting all the base component's behavior** while adding new functionality.
+
+### Basic Pattern
+
+```svelte
+<Tooltip.Trigger base={Button}>Open Tooltip</Tooltip.Trigger>
+```
+
+The `Tooltip.Trigger` now **behaves as both** a Tooltip trigger AND a Button:
+
+- Gets Button's styling, hover states, click handling
+- Gets Tooltip.Trigger's `aria-*` attributes, open/close logic, positioning
+
+### Form Field Composition
+
+The most powerful example is `Field.Control`, which adapts to any input component:
+
+```svelte
+<!-- Text Input -->
+<Field.Control base={Input.Value} placeholder="Enter name" />
+
+<!-- Checkbox -->
+<Field.Control base={Checkbox} />
+
+<!-- Radio Group -->
+<Field.Control base={RadioGroup}>
+	<Radio value="yes" />
+	<Radio value="no" />
+</Field.Control>
+```
+
+`Field.Control` automatically:
+
+- Connects the base component to form validation
+- Syncs the input value with field state
+- Handles validation on blur/change
+- Links labels via `aria-labelledby`
+
+### DataGrid Cell Composition
+
+Compose table cells with interactive components:
+
+```svelte
+<DataGrid.Td base={Dropdown.Root} placement="bottom-end">
+	<Dropdown.Trigger>
+		<Icon src={MoreVerticalIcon} />
+	</Dropdown.Trigger>
+	<Dropdown.List>
+		<Dropdown.Item value="edit">Edit</Dropdown.Item>
+		<Dropdown.Item value="delete">Delete</Dropdown.Item>
+	</Dropdown.List>
+</DataGrid.Td>
+```
+
+The `DataGrid.Td` now:
+
+- Maintains table cell semantics and styling
+- Adds Dropdown positioning, open/close state
+- Handles keyboard navigation and focus management
+
+### Menu & Dropdown Triggers
+
+```svelte
+<Menu.Root>
+	<Menu.Trigger base={Button}>Select Language</Menu.Trigger>
+	<Menu.List>
+		<Menu.Item>English</Menu.Item>
+		<Menu.Item>Spanish</Menu.Item>
+	</Menu.List>
+</Menu.Root>
+```
+
+`Menu.Trigger` with `base={Button}`:
+
+- Button appearance and interaction
+- Menu trigger accessibility (`aria-haspopup`, `aria-expanded`)
+- Menu open/close toggle on click
+
+### How Base Prop Works
+
+When you write:
+
+```svelte
+<Component base={BaseComponent} {...props}>
+	{children}
+</Component>
+```
+
+Internally, the component renders:
+
+```svelte
+<BaseComponent {...props} {...componentSpecificProps}>
+	{children}
+</BaseComponent>
+```
+
+All props are forwarded, and the component adds its own behavior (event handlers, ARIA attributes, state bindings) to the base component.
+
+## 2. Bond Pattern (State Sharing)
+
+Components expose their internal state via a **bond** object through the `{#snippet children({ bond })}` pattern. This allows parent components to access and control child component state.
+
+### Accessing Component State
+
+```svelte
+<Popover.Root>
+	{#snippet children({ popover })}
+		<Popover.Trigger base={Button}>
+			<div>Open Popover</div>
+			<!-- Access popover state to show indicator -->
+			<Popover.Indicator />
+		</Popover.Trigger>
+
+		<Popover.Content>
+			<!-- Can access popover.state.isOpen, popover.state.close(), etc. -->
+		</Popover.Content>
+	{/snippet}
+</Popover.Root>
+```
+
+The `popover` bond provides:
+
+- `popover.state.isOpen` - Current open state
+- `popover.state.close()` - Close the popover programmatically
+- `popover.state.toggle()` - Toggle open/close state
+
+### Field Validation Access
+
+```svelte
+<Field.Root name="firstName" schema={nameSchema}>
+	{#snippet children({ field })}
+		<Field.Label>First Name</Field.Label>
+
+		<Input.Root>
+			<Field.Control
+				base={Input.Value}
+				onblur={() => {
+					const results = field?.state.validate();
+					console.log(results);
+				}}
+			/>
+		</Input.Root>
+
+		<!-- Access validation errors -->
+		{#if field?.state?.errors?.length > 0}
+			<div class="text-xs text-red-600">
+				{#each field.state.errors as error}
+					<div>{error.message}</div>
+				{/each}
+			</div>
+		{/if}
+	{/snippet}
+</Field.Root>
+```
+
+The `field` bond provides:
+
+- `field.state.validate()` - Trigger validation manually
+- `field.state.errors` - Array of validation errors
+- `field.state.value` - Current field value
+
+### Collapsible State Control
+
+```svelte
+<Collapsible.Root>
+	{#snippet children({ collapsible })}
+		<Collapsible.Trigger base={Button}>Toggle Content</Collapsible.Trigger>
+
+		<Collapsible.Content>
+			<div>Collapsible content here</div>
+
+			<!-- Nested button that can control parent collapsible -->
+			<Button onclick={() => collapsible.state.close()}>Close from inside</Button>
+		</Collapsible.Content>
+	{/snippet}
+</Collapsible.Root>
+```
+
+### Dropdown State Inspection
+
+```svelte
+<Dropdown.Root>
+	{#snippet children({ dropdown })}
+		<Dropdown.Trigger base={Button}>Select Option</Dropdown.Trigger>
+
+		<Dropdown.List>
+			<Dropdown.Item value="option1">Option 1</Dropdown.Item>
+			<Dropdown.Item value="option2">Option 2</Dropdown.Item>
+		</Dropdown.List>
+
+		<!-- Display selected value outside dropdown -->
+		<div>Selected: {dropdown.state.value || 'None'}</div>
+	{/snippet}
+</Dropdown.Root>
+```
+
+### How Bond Pattern Works
+
+Components create a **Bond** instance that holds state and methods:
+
+```typescript
+// Inside component implementation
+const bond = new PopoverBond();
+bond.state.isOpen = $state(false);
+bond.state.close = () => {
+	bond.state.isOpen = false;
+};
+```
+
+The bond is passed to children via snippet props, allowing descendants to access and modify component state.
+
+## 3. Nested Component Composition
+
+Components can be nested as siblings or parent-child to create complex interactions.
+
+### Dialog with Nested Dropdown
+
+```svelte
+<Dialog.Root>
+	{#snippet children({ dialog })}
+		<Dialog.Trigger base={Button}>Open Dialog</Dialog.Trigger>
+
+		<Dialog.Content>
+			<Dialog.Header>
+				<Dialog.Title>Select an option</Dialog.Title>
+			</Dialog.Header>
+
+			<!-- Dropdown inside Dialog -->
+			<Dropdown.Root>
+				{#snippet children({ dropdown })}
+					<Dropdown.Trigger base={Button}>Choose Language</Dropdown.Trigger>
+					<Dropdown.List>
+						<Dropdown.Item value="en">English</Dropdown.Item>
+						<Dropdown.Item value="es">Spanish</Dropdown.Item>
+					</Dropdown.List>
+				{/snippet}
+			</Dropdown.Root>
+
+			<Dialog.Footer>
+				<Button onclick={() => dialog.state.close()}>Close</Button>
+			</Dialog.Footer>
+		</Dialog.Content>
+	{/snippet}
+</Dialog.Root>
+```
+
+Each component manages its own state independently, but both bonds are accessible for coordination.
+
+### Scrollable with Nested Content
+
+```svelte
+<Scrollable.Root>
+	{#snippet children({ scrollable })}
+		<Scrollable.Content>
+			<!-- Access scroll position -->
+			<div>Scroll Y: {scrollable.state.scrollTop}</div>
+
+			<!-- Nested interactive components -->
+			<Accordion.Root>
+				<Accordion.Item value="item1">
+					<Accordion.Trigger>Section 1</Accordion.Trigger>
+					<Accordion.Content>Content 1</Accordion.Content>
+				</Accordion.Item>
+			</Accordion.Root>
+		</Scrollable.Content>
+	{/snippet}
+</Scrollable.Root>
+```
+
+### Combobox with Custom Trigger
+
+```svelte
+<Combobox.Root>
+	{#snippet children({ combobox })}
+		<Combobox.Trigger base={Input.Root}>
+			<Input.Value placeholder="Search..." />
+			<Input.Icon src={SearchIcon} />
+		</Combobox.Trigger>
+
+		<Combobox.List>
+			<Combobox.Item value="option1">Option 1</Combobox.Item>
+			<Combobox.Item value="option2">Option 2</Combobox.Item>
+		</Combobox.List>
+	{/snippet}
+</Combobox.Root>
+```
+
+The `Input.Root` is composed into the trigger, bringing input styling and icon support to the combobox.
+
+## Key Principles
+
+1. **Base Prop = Behavior Inheritance**: Use `base=` to layer component behaviors (Button + Menu.Trigger = clickable menu opener)
+
+2. **Bond = State Access**: Use `{#snippet children({ bond })}` to access component state and methods for coordination
+
+3. **Nesting = UI Composition**: Nest components as needed; each maintains independent state while bonds allow communication
+
+4. **Forward Everything**: Components forward all props and classes to their base, enabling full customization
+
+5. **Type Safety**: TypeScript infers correct props when using `base=`, providing autocompletion for both the component and the base
+
+## Common Patterns
+
+### Interactive Table Cell
+
+```svelte
+<DataGrid.Td base={Dropdown.Root}>
+	<Dropdown.Trigger base={Button} variant="ghost" size="sm">Actions</Dropdown.Trigger>
+	<Dropdown.List>
+		<Dropdown.Item>Edit</Dropdown.Item>
+		<Dropdown.Item>Delete</Dropdown.Item>
+	</Dropdown.List>
+</DataGrid.Td>
+```
+
+**Combines**: Table cell + Dropdown + Button
+
+### Validated Form Field
+
+```svelte
+<Field.Root name="email" schema={emailSchema}>
+	{#snippet children({ field })}
+		<Field.Label>Email</Field.Label>
+		<Field.Control
+			base={Input.Value}
+			type="email"
+			placeholder="you@example.com"
+			onblur={() => field?.state.validate()}
+		/>
+		{#if field?.state?.errors}
+			<Field.Error />
+		{/if}
+	{/snippet}
+</Field.Root>
+```
+
+**Combines**: Form validation + Input + Label + Error display
+
+### Tooltip Button
+
+```svelte
+<Tooltip.Root>
+	<Tooltip.Trigger base={Button} variant="outline">Delete</Tooltip.Trigger>
+	<Tooltip.Content>This action cannot be undone</Tooltip.Content>
+</Tooltip.Root>
+```
+
+**Combines**: Tooltip positioning + Button interaction
+
+### Controlled Popover with Custom Content
+
+```svelte
+<Popover.Root bind:open>
+	{#snippet children({ popover })}
+		<Popover.Trigger base={Button}>
+			Open {popover.state.isOpen ? '(Open)' : '(Closed)'}
+		</Popover.Trigger>
+
+		<Popover.Content class="w-80">
+			<Card>
+				<Card.Header>
+					<Card.Title>Settings</Card.Title>
+				</Card.Header>
+				<Card.Content>
+					<!-- Form fields here -->
+				</Card.Content>
+				<Card.Footer>
+					<Button onclick={() => popover.state.close()}>Close</Button>
+				</Card.Footer>
+			</Card>
+		</Popover.Content>
+	{/snippet}
+</Popover.Root>
+```
+
+**Combines**: Popover positioning + Button trigger + Card layout + Form
+
+## Summary
+
+- **`base=` prop**: Inherit behavior from another component (Trigger + Button = clickable trigger)
+- **`{#snippet children({ bond })}`**: Access component state for coordination
+- **Nesting**: Compose complex UIs by nesting components as needed
+- **Composition > Configuration**: Combine simple components instead of creating complex ones with many props