@human-kit/svelte-components 1.0.0-alpha.1 → 1.0.0-alpha.2

package/dist/calendar/root/date-utils.d.ts

@@ -0,0 +1,17 @@
+export type CalendarDateValue = string;
+export declare function isValidCalendarDateValue(value: string): boolean;
+export declare function parseCalendarDate(value: CalendarDateValue): Date | null;
+export declare function formatCalendarDate(date: Date): CalendarDateValue;
+export declare function startOfMonth(date: Date): Date;
+export declare function addMonths(date: Date, amount: number): Date;
+export declare function addDays(date: Date, amount: number): Date;
+export declare function compareDates(a: Date, b: Date): number;
+export declare function getTodayUtcDate(): Date;
+export declare function getFirstDayOfWeek(locale: string): number;
+export declare function getWeekdayLabels(locale: string, firstDayOfWeek: number): string[];
+export type CalendarDayCell = {
+    date: CalendarDateValue;
+    isOutsideMonth: boolean;
+};
+export declare function buildMonthGrid(monthStart: Date, firstDayOfWeek: number): CalendarDayCell[][];
+export declare function formatMonthHeading(date: Date, locale: string): string;

package/dist/calendar/root/date-utils.js

@@ -0,0 +1,104 @@
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+export function isValidCalendarDateValue(value) {
+    const match = DATE_RE.exec(value);
+    if (!match)
+        return false;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    if (month < 1 || month > 12 || day < 1 || day > 31)
+        return false;
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return (date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day);
+}
+export function parseCalendarDate(value) {
+    if (!isValidCalendarDateValue(value))
+        return null;
+    const [year, month, day] = value.split('-').map(Number);
+    return new Date(Date.UTC(year, month - 1, day));
+}
+export function formatCalendarDate(date) {
+    const year = date.getUTCFullYear();
+    const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(date.getUTCDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+export function startOfMonth(date) {
+    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), 1));
+}
+function getDaysInMonthUtc(year, monthIndex) {
+    return new Date(Date.UTC(year, monthIndex + 1, 0)).getUTCDate();
+}
+export function addMonths(date, amount) {
+    const targetMonth = date.getUTCMonth() + amount;
+    const targetYear = date.getUTCFullYear() + Math.floor(targetMonth / 12);
+    const normalizedMonth = ((targetMonth % 12) + 12) % 12;
+    const targetDay = Math.min(date.getUTCDate(), getDaysInMonthUtc(targetYear, normalizedMonth));
+    return new Date(Date.UTC(targetYear, normalizedMonth, targetDay));
+}
+export function addDays(date, amount) {
+    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + amount));
+}
+export function compareDates(a, b) {
+    const at = a.getTime();
+    const bt = b.getTime();
+    if (at < bt)
+        return -1;
+    if (at > bt)
+        return 1;
+    return 0;
+}
+export function getTodayUtcDate() {
+    const now = new Date();
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+}
+export function getFirstDayOfWeek(locale) {
+    try {
+        const intlLocale = new Intl.Locale(locale);
+        const weekInfo = intlLocale.weekInfo;
+        if (weekInfo?.firstDay) {
+            return weekInfo.firstDay % 7;
+        }
+    }
+    catch {
+        // ignore and fallback to sunday
+    }
+    return 0;
+}
+export function getWeekdayLabels(locale, firstDayOfWeek) {
+    const formatter = new Intl.DateTimeFormat(locale, {
+        weekday: 'short',
+        timeZone: 'UTC'
+    });
+    const sunday = new Date(Date.UTC(2024, 0, 7));
+    return Array.from({ length: 7 }, (_, index) => {
+        const dayOffset = (firstDayOfWeek + index) % 7;
+        return formatter.format(addDays(sunday, dayOffset));
+    });
+}
+export function buildMonthGrid(monthStart, firstDayOfWeek) {
+    const firstOfMonth = startOfMonth(monthStart);
+    const firstWeekday = firstOfMonth.getUTCDay();
+    const startOffset = (firstWeekday - firstDayOfWeek + 7) % 7;
+    const gridStart = addDays(firstOfMonth, -startOffset);
+    const weeks = [];
+    for (let weekIndex = 0; weekIndex < 6; weekIndex++) {
+        const week = [];
+        for (let dayIndex = 0; dayIndex < 7; dayIndex++) {
+            const date = addDays(gridStart, weekIndex * 7 + dayIndex);
+            week.push({
+                date: formatCalendarDate(date),
+                isOutsideMonth: date.getUTCMonth() !== firstOfMonth.getUTCMonth()
+            });
+        }
+        weeks.push(week);
+    }
+    return weeks;
+}
+export function formatMonthHeading(date, locale) {
+    return new Intl.DateTimeFormat(locale, {
+        month: 'long',
+        year: 'numeric',
+        timeZone: 'UTC'
+    }).format(date);
+}

package/dist/calendar/trigger-next/calendar-trigger-next.svelte

@@ -0,0 +1,38 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLButtonAttributes } from 'svelte/elements';
+	import { useCalendarContext } from '../root/context';
+
+	type CalendarTriggerNextProps = Omit<HTMLButtonAttributes, 'children'> & {
+		children?: Snippet;
+	};
+
+	let { children, class: className = '', ...restProps }: CalendarTriggerNextProps = $props();
+
+	const calendar = useCalendarContext();
+	const layoutVersion = calendar.layoutVersion;
+	const isDisabled = $derived.by(() => {
+		void $layoutVersion;
+		return calendar.isDisabled;
+	});
+
+	function handleClick() {
+		if (isDisabled) return;
+		calendar.goToNextPage();
+	}
+</script>
+
+<button
+	type="button"
+	class={className}
+	aria-label="Next page"
+	disabled={isDisabled}
+	onclick={handleClick}
+	{...restProps}
+>
+	{#if children}
+		{@render children()}
+	{:else}
+		Next
+	{/if}
+</button>

package/dist/calendar/trigger-next/calendar-trigger-next.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Snippet } from 'svelte';
+import type { HTMLButtonAttributes } from 'svelte/elements';
+type CalendarTriggerNextProps = Omit<HTMLButtonAttributes, 'children'> & {
+    children?: Snippet;
+};
+declare const CalendarTriggerNext: import("svelte").Component<CalendarTriggerNextProps, {}, "">;
+type CalendarTriggerNext = ReturnType<typeof CalendarTriggerNext>;
+export default CalendarTriggerNext;

package/dist/calendar/trigger-previous/calendar-trigger-previous.svelte

@@ -0,0 +1,38 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLButtonAttributes } from 'svelte/elements';
+	import { useCalendarContext } from '../root/context';
+
+	type CalendarTriggerPreviousProps = Omit<HTMLButtonAttributes, 'children'> & {
+		children?: Snippet;
+	};
+
+	let { children, class: className = '', ...restProps }: CalendarTriggerPreviousProps = $props();
+
+	const calendar = useCalendarContext();
+	const layoutVersion = calendar.layoutVersion;
+	const isDisabled = $derived.by(() => {
+		void $layoutVersion;
+		return calendar.isDisabled;
+	});
+
+	function handleClick() {
+		if (isDisabled) return;
+		calendar.goToPreviousPage();
+	}
+</script>
+
+<button
+	type="button"
+	class={className}
+	aria-label="Previous page"
+	disabled={isDisabled}
+	onclick={handleClick}
+	{...restProps}
+>
+	{#if children}
+		{@render children()}
+	{:else}
+		Prev
+	{/if}
+</button>

package/dist/calendar/trigger-previous/calendar-trigger-previous.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Snippet } from 'svelte';
+import type { HTMLButtonAttributes } from 'svelte/elements';
+type CalendarTriggerPreviousProps = Omit<HTMLButtonAttributes, 'children'> & {
+    children?: Snippet;
+};
+declare const CalendarTriggerPrevious: import("svelte").Component<CalendarTriggerPreviousProps, {}, "">;
+type CalendarTriggerPrevious = ReturnType<typeof CalendarTriggerPrevious>;
+export default CalendarTriggerPrevious;

package/dist/combobox/README.md

@@ -0,0 +1,40 @@
+# ComboBox
+
+## Description
+
+`ComboBox` combines text input, popover, and listbox behavior into a single accessible selection pattern. It supports single and multiple selection, controlled and uncontrolled state, and keyboard-first interaction.
+
+## Usage guidelines
+
+- Wrap all parts in `ComboBox.Root`.
+- Use controlled props (`value`, `inputValue`, `isOpen`) only when external state management is needed.
+- Provide a stable `id` in SSR environments to keep ARIA ids deterministic.
+- Render `ComboBox.Tags`, `ComboBox.Tag`, and `ComboBox.TagRemove` in multiple mode to expose selected values.
+- Choose `trigger="focus"`, `trigger="input"`, or `trigger="press"` based on your opening behavior requirements.
+
+## Anatomy
+
+Import the component and compose its parts:
+
+```svelte
+<ComboBox.Root>
+	<ComboBox.Input />
+	<ComboBox.Button />
+	<ComboBox.Popover>
+		<ComboBox.List>
+			<ComboBox.Item id="1">Option 1</ComboBox.Item>
+		</ComboBox.List>
+	</ComboBox.Popover>
+</ComboBox.Root>
+```
+
+- `ComboBox.Root`
+- `ComboBox.Input`
+- `ComboBox.Button`
+- `ComboBox.Popover`
+- `ComboBox.List`
+- `ComboBox.Item`
+- `ComboBox.ItemIndicator`
+- `ComboBox.Tags`
+- `ComboBox.Tag`
+- `ComboBox.TagRemove`

package/dist/combobox/TODO.md

@@ -4,134 +4,134 @@ Comprehensive review based on: **Accessibility**, **Scalability**, **Performance
 
 ---
 
-## 🔊 Accesibilidad
+## Accessibility
 
-### Completado ✅
+### Completed (Accessibility)
 
-- [x] ARIA pattern: `aria-activedescendant` para virtual focus
-- [x] `aria-expanded`, `aria-haspopup`, `aria-controls` en input
-- [x] `aria-label` en ListBox
+- [x] ARIA pattern: `aria-activedescendant` for virtual focus
+- [x] `aria-expanded`, `aria-haspopup`, `aria-controls` on input
+- [x] `aria-label` on ListBox
 - [x] `role="combobox"`, `role="listbox"`, `role="option"`
-- [x] `aria-selected` en items seleccionados
-- [x] `aria-disabled` en items/placeholder deshabilitados
-- [x] Input soporta `aria-label` y `aria-labelledby` props
-- [x] ListBox tiene ID para que `aria-controls` funcione correctamente
-- [x] Button tiene `aria-controls` apuntando al listbox
-- [x] Wrapper group soporta `aria-label` y `aria-labelledby`
-- [x] Input soporta `aria-describedby` para instrucciones de uso
+- [x] `aria-selected` on selected items
+- [x] `aria-disabled` on disabled items/placeholder
+- [x] Input supports `aria-label` and `aria-labelledby` props
+- [x] ListBox has an ID so `aria-controls` works correctly
+- [x] Button has `aria-controls` pointing to the listbox
+- [x] Wrapper group supports `aria-label` and `aria-labelledby`
+- [x] Input supports `aria-describedby` for usage instructions
 
-### Pendiente
+### Pending (Accessibility)
 
-- [ ] **Live regions para conteo de resultados**
-  - Agregar `<div aria-live="polite">` que anuncie "{N} resultados disponibles" al filtrar
-  - Importante para screen readers que no ven el cambio visual
+- [ ] **Live regions for result count**
+  - Add `<div aria-live="polite">` to announce "{N} results available" while filtering
+  - Important for screen readers that cannot see visual updates
 
-- [ ] **Anuncio de selección**
-  - Anunciar "Item seleccionado: {label}" cuando se selecciona
-  - Usar `aria-live="assertive"` para cambios importantes
+- [ ] **Selection announcement**
+  - Announce "Selected item: {label}" when an item is selected
+  - Use `aria-live="assertive"` for important changes
 
-- [ ] **Soporte para grupos (sections)**
-  - Implementar `role="group"` con `aria-labelledby` para secciones
-  - Agregar `ComboBox.Section` component
+- [ ] **Support for groups (sections)**
+  - Implement `role="group"` with `aria-labelledby` for sections
+  - Add `ComboBox.Section` component
 
 ---
 
-## 📈 Escalabilidad
+## Scalability
 
-### Completado ✅
+### Completed (Scalability)
 
-- [x] Hook `useVirtualFocus` reutilizable
+- [x] Reusable `useVirtualFocus` hook
 - [x] Controlled/uncontrolled mode
-- [x] Filtrado automático en items
-- [x] `emptyPlaceholder` reactivo
+- [x] Automatic item filtering
+- [x] Reactive `emptyPlaceholder`
 
-### Pendiente
+### Pending (Scalability)
 
-- [ ] **`filterFn` prop customizable**
-  - Actualmente filtrado es case-insensitive includes
-  - Permitir: fuzzy search, startsWith, exact match, async search
+- [ ] **Customizable `filterFn` prop**
+  - Filtering is currently case-insensitive includes
+  - Allow: fuzzy search, startsWith, exact match, async search
 
 - [ ] **`allowCreate` prop**
-  - Permitir crear nuevos items cuando no hay match
+  - Allow creating new items when there is no match
   - Callback `onCreate?: (value: string) => void`
 
 - [x] **Multiple selection UI**
-  - Chips/tags para items seleccionados ✅ `ComboBox.Tags`, `ComboBox.Tag`, `ComboBox.TagRemove`
-  - Clear all button (disponible via `clearSelection()` en context)
-  - Contador de seleccionados (disponible via `selectedValue.size`)
-  - Navegación de tags con teclado (ArrowLeft/Right, Delete/Backspace)
-  - `ComboBox.ItemIndicator` para mostrar checks en items seleccionados
+  - Chips/tags for selected items: `ComboBox.Tags`, `ComboBox.Tag`, `ComboBox.TagRemove`
+  - Clear-all button (available via `clearSelection()` in context)
+  - Selected-count indicator (available via `selectedValue.size`)
+  - Keyboard tag navigation (ArrowLeft/Right, Delete/Backspace)
+  - `ComboBox.ItemIndicator` to show checks for selected items
 
 - [ ] **Form integration**
-  - `name` prop para `<form>` nativo
-  - Hidden input con valor serializado
-  - Validación con `required`, `aria-invalid`
+  - `name` prop for native `<form>`
+  - Hidden input with serialized value
+  - Validation with `required`, `aria-invalid`
 
 - [ ] **Async data support**
   - Props: `isLoading`, `loadingPlaceholder`
-  - Callback: `onLoadMore` para infinite scroll
-  - Debounce integrado para búsqueda async
+  - Callback: `onLoadMore` for infinite scroll
+  - Built-in debounce for async search
 
 - [ ] **Virtualization**
-  - Para listas grandes (>100 items)
-  - Integrar con `@tanstack/virtual` o similar
+  - For large lists (>100 items)
+  - Integrate with `@tanstack/virtual` or similar
 
 ---
 
-## ⚡ Performance
+## Performance
 
-### Completado ✅
+### Completed (Performance)
 
-- [x] Cache de DOM queries con invalidación (`cachedItemOrder`)
-- [x] `untrack()` para evitar loops infinitos en effects
-- [x] Subscription pattern para `itemCount` reactivo
+- [x] DOM query cache with invalidation (`cachedItemOrder`)
+- [x] `untrack()` to avoid infinite effect loops
+- [x] Subscription pattern for reactive `itemCount`
 - [x] Scoped queries via `containerRef`
 
-### Pendiente
+### Pending (Performance)
 
-- [ ] **Memoización de `isVisible` en ListBoxItem**
-  - Actualmente se recalcula en cada render
-  - Considerar memoizar con `$derived` más granular
+- [ ] **`isVisible` memoization in ListBoxItem**
+  - It is currently recomputed on each render
+  - Consider more granular memoization with `$derived`
 
 - [ ] **Batch registration**
-  - `registerItem` se llama por cada item individualmente
-  - Para listas grandes, batch notifications
+  - `registerItem` runs once per individual item
+  - For large lists, consider batched notifications
 
-- [ ] **Lazy itemLabels**
-  - El Map `itemLabels` crece con cada item
-  - Limpiar en unmount está implementado, pero considerar WeakMap
+- [ ] **Lazy `itemLabels`**
+  - The `itemLabels` map grows with each item
+  - Cleanup on unmount is implemented, but consider `WeakMap`
 
 - [ ] **Effect cleanup optimizations**
-  - Revisar effects que podrían consolidarse
-  - `combobox-listboxitem.svelte` tiene 2 effects que podrían ser 1
+  - Review effects that could be consolidated
+  - `combobox-listboxitem.svelte` has 2 effects that might become 1
 
 ---
 
-## 🔧 Svelte 5 Runes Best Practices
+## Svelte 5 Runes Best Practices
 
-### Completado ✅
+### Completed (Runes)
 
-- [x] `$state` para estado reactivo
-- [x] `$derived` para valores computados
-- [x] `$effect` con cleanup functions
-- [x] `$bindable` para two-way binding
-- [x] `$props()` para destructuring
-- [x] `untrack()` para evitar re-runs innecesarios
-- [x] `$derived(expression)` en vez de `$derived(() => ...)` - Simplificado en `combobox-listboxitem.svelte`
-- [x] Effects consolidados - Usando 1 `$effect` + `onDestroy` en vez de 2 effects
+- [x] `$state` for reactive state
+- [x] `$derived` for computed values
+- [x] `$effect` with cleanup functions
+- [x] `$bindable` for two-way binding
+- [x] `$props()` for destructuring
+- [x] `untrack()` to avoid unnecessary re-runs
+- [x] `$derived(expression)` instead of `$derived(() => ...)` - simplified in `combobox-listboxitem.svelte`
+- [x] Consolidated effects - using 1 `$effect` + `onDestroy` instead of 2 effects
 
-### Revisado - No requiere cambios
+### Reviewed - No Changes Required
 
-- [x] **`$effect.pre`**: Revisado - no hay race conditions que lo requieran
-- [x] **Context typing**: El type único es apropiado - tree-shaking no aplica a context objects
+- [x] **`$effect.pre`**: Reviewed - no race conditions requiring it
+- [x] **Context typing**: Single shared type is appropriate - tree-shaking does not apply to context objects
 
 ---
 
-## 🧪 Testing
+## Testing
 
-### Completado ✅
+### Completed (Testing)
 
-- [x] 291 tests unitarios pasando
+- [x] 291 passing unit tests
 - [x] Keyboard navigation tests
 - [x] Selection tests
 - [x] Filtering tests
@@ -143,33 +143,33 @@ Comprehensive review based on: **Accessibility**, **Scalability**, **Performance
 - [x] Selection behavior (Enter, click, Escape restoration)
 - [x] Multi-select tests (12 tests)
 - [x] Tags component tests (4 tests)
-- [x] Tag component tests (13 tests) - incluye navegación por teclado
+- [x] Tag component tests (13 tests) - includes keyboard navigation
 - [x] TagRemove component tests (6 tests)
 - [x] ItemIndicator component tests (5 tests)
 
-### Pendiente
+### Pending (Testing)
 
-- [ ] **Tests con muchos items (100+)** - performance tests
-- [ ] **Visual regression tests** - screenshots de estados
+- [ ] **Tests with many items (100+)** - performance tests
+- [ ] **Visual regression tests** - state screenshots
 
 ---
 
-## 📝 Documentación
+## Documentation
 
-- [ ] **JSDoc completo**
-  - Documentar todas las props públicas
-  - Ejemplos de uso en comments
+- [ ] **Complete JSDoc**
+  - Document all public props
+  - Add usage examples in comments
 
 - [ ] **Storybook/Demo page**
-  - Ejemplos interactivos de todos los casos de uso
-  - Estados: loading, error, disabled, readonly
+  - Interactive examples for all use cases
+  - States: loading, error, disabled, readonly
 
 ---
 
-## 🎯 Próximos Pasos Priorizados
+## Prioritized Next Steps
 
-1. **Live regions** (accessibility - alto impacto)
-2. **Form integration** (usabilidad - casos comunes)
-3. **`filterFn` customizable** (escalabilidad)
-4. **Consolidar effects** (performance/best practices)
-5. **Async data support** (escalabilidad)
+1. **Live regions** (accessibility - high impact)
+2. **Form integration** (usability - common cases)
+3. **Customizable `filterFn`** (scalability)
+4. **Consolidate effects** (performance/best practices)
+5. **Async data support** (scalability)

package/dist/combobox/button/README.md

@@ -0,0 +1,15 @@
+# ComboBox Button
+
+## API reference
+
+### ComboBox.Button
+
+Name: `ComboBox.Button`  
+Description: Optional trigger button that toggles the combobox popover without stealing focus from the input.
+
+| Prop           | Type                   | Default     | Description                                                     |
+| -------------- | ---------------------- | ----------- | --------------------------------------------------------------- |
+| `class`        | `string`               | `undefined` | CSS class names for the button element.                         |
+| `children`     | `Snippet`              | `undefined` | Custom trigger content. If omitted, a chevron icon is rendered. |
+| `tabindex`     | `number`               | `-1`        | Tab index applied to the button.                                |
+| `...restProps` | `HTMLButtonAttributes` | `-`         | Additional native button attributes.                            |

package/dist/combobox/input/README.md

@@ -0,0 +1,16 @@
+# ComboBox Input
+
+## API reference
+
+### ComboBox.Input
+
+Name: `ComboBox.Input`  
+Description: Text input with `role="combobox"` that syncs typed value, active descendant, and keyboard handling with `ComboBox.Root`.
+
+| Prop               | Type                  | Default     | Description                                     |
+| ------------------ | --------------------- | ----------- | ----------------------------------------------- |
+| `aria-label`       | `string`              | `undefined` | Accessible label applied directly to the input. |
+| `aria-labelledby`  | `string`              | `undefined` | Element id that labels the input.               |
+| `aria-describedby` | `string`              | `undefined` | Element id that describes the input behavior.   |
+| `class`            | `string`              | `undefined` | CSS class names for the input element.          |
+| `...restProps`     | `HTMLInputAttributes` | `-`         | Additional native input attributes.             |

package/dist/combobox/item/README.md

@@ -0,0 +1,27 @@
+# ComboBox Item
+
+## API reference
+
+### ComboBox.Item
+
+Name: `ComboBox.Item`  
+Description: Selectable option item with combobox-specific filtering, virtual focus, and registration logic.
+
+| Prop           | Type                             | Default        | Description                                                    |
+| -------------- | -------------------------------- | -------------- | -------------------------------------------------------------- |
+| `id`           | `string \| number`               | `required`     | Unique item id used for selection and ARIA relationships.      |
+| `textValue`    | `string`                         | `content text` | Text used for filtering and fallback label resolution.         |
+| `disabled`     | `boolean`                        | `false`        | Marks the item as disabled and non-selectable.                 |
+| `class`        | `string`                         | `undefined`    | CSS class names for the item.                                  |
+| `children`     | `Snippet`                        | `undefined`    | Rendered item content.                                         |
+| `...restProps` | `HTMLAttributes<HTMLDivElement>` | `-`            | Additional attributes passed to the underlying option element. |
+
+### Item context utility
+
+Name: `COMBOBOX_ITEM_CONTEXT_KEY` / `ComboBoxItemContext`  
+Description: Internal context consumed by `ComboBox.ItemIndicator` to read the parent item id.
+
+| Prop                        | Type               | Default                       | Description                               |
+| --------------------------- | ------------------ | ----------------------------- | ----------------------------------------- |
+| `COMBOBOX_ITEM_CONTEXT_KEY` | `symbol`           | `Symbol.for('combobox-item')` | Context key shared by item and indicator. |
+| `id`                        | `string \| number` | `required`                    | Current item id exposed through context.  |

package/dist/combobox/item-indicator/README.md

@@ -0,0 +1,15 @@
+# ComboBox Item Indicator
+
+## API reference
+
+### ComboBox.ItemIndicator
+
+Name: `ComboBox.ItemIndicator`  
+Description: Visual selection indicator rendered inside `ComboBox.Item`.
+
+| Prop           | Type                              | Default      | Description                                          |
+| -------------- | --------------------------------- | ------------ | ---------------------------------------------------- |
+| `children`     | `Snippet`                         | `check icon` | Custom indicator content.                            |
+| `forceMount`   | `boolean`                         | `false`      | Forces rendering even when the item is not selected. |
+| `class`        | `string`                          | `undefined`  | CSS class names for the indicator wrapper.           |
+| `...restProps` | `HTMLAttributes<HTMLSpanElement>` | `-`          | Additional attributes passed to the wrapper span.    |

package/dist/combobox/list/README.md

@@ -0,0 +1,27 @@
+# ComboBox List
+
+## API reference
+
+### ComboBox.List
+
+Name: `ComboBox.List`  
+Description: Listbox bridge for combobox options. It delegates selection state and mode to `ComboBox.Root`.
+
+| Prop              | Type                                                | Default     | Description                                                                     |
+| ----------------- | --------------------------------------------------- | ----------- | ------------------------------------------------------------------------------- |
+| `aria-label`      | `string`                                            | `'Options'` | Accessible label for the internal listbox.                                      |
+| `items`           | `Iterable<T>`                                       | `ctx.items` | Dynamic data source. If omitted, uses items from root context.                  |
+| `children`        | `Snippet<[T]> \| Snippet`                           | `undefined` | Dynamic item renderer or static list content.                                   |
+| `...listBoxProps` | `Omit<ComponentProps<ListBoxRoot>, internal props>` | `-`         | Additional listbox props such as `class`, `emptyPlaceholder`, or `disabledIds`. |
+
+### Internally controlled props
+
+Name: Controlled by `ComboBox.Root`  
+Description: The following values are set by `ComboBox.List` and should not be overridden directly.
+
+| Prop            | Type                     | Default                          | Description                                           |
+| --------------- | ------------------------ | -------------------------------- | ----------------------------------------------------- |
+| `selectionMode` | `'single' \| 'multiple'` | `ctx.selectionMode`              | Selection mode inherited from root.                   |
+| `value`         | `Set<string \| number>`  | `ctx.selectedValue`              | Current combobox selection state.                     |
+| `onChange`      | `(selection) => void`    | `internal handler`               | Delegates selected item handling to combobox context. |
+| `id`            | `string`                 | `combobox-listbox-${instanceId}` | Auto-generated listbox id for ARIA wiring.            |

package/dist/combobox/popover/README.md

@@ -0,0 +1,13 @@
+# ComboBox Popover
+
+## API reference
+
+### ComboBox.Popover
+
+Name: `ComboBox.Popover`  
+Description: Floating container for combobox options. Internally composes `Popover.Root` and `Popover.Content` in non-modal mode.
+
+| Prop       | Type      | Default     | Description                                 |
+| ---------- | --------- | ----------- | ------------------------------------------- |
+| `class`    | `string`  | `''`        | CSS class names for the floating panel.     |
+| `children` | `Snippet` | `undefined` | Popover content, typically `ComboBox.List`. |