@a4ui/core 0.2.0 → 0.3.1

package/dist/ui/Badge.d.ts

@@ -1,8 +1,20 @@
 import { JSX, ParentProps } from 'solid-js';
+/** Semantic tone of a {@link Badge}; drives its background/text/ring color. */
 export type BadgeTone = 'neutral' | 'success' | 'warning' | 'danger' | 'info';
 interface BadgeProps extends ParentProps {
+    /** Visual/semantic tone. Defaults to `'neutral'`. */
     tone?: BadgeTone;
     class?: string;
 }
+/**
+ * Small rounded pill for status/labels, e.g. counts, states, or tags.
+ * Generic design-system primitive — app-specific tone mappers (e.g. mapping a
+ * business status to a {@link BadgeTone}) should live in the consuming app.
+ *
+ * @example
+ * ```tsx
+ * <Badge tone="success">Active</Badge>
+ * ```
+ */
 export declare function Badge(props: BadgeProps): JSX.Element;
 export {};

package/dist/ui/Breadcrumb.d.ts

@@ -1,11 +1,28 @@
 import { JSX } from 'solid-js';
+/** A single crumb rendered by {@link Breadcrumb}. */
 export interface BreadcrumbItem {
     label: string;
+    /** Link target. Omit (or leave undefined on the last item) to render plain text for the current page. */
     href?: string;
 }
 interface BreadcrumbProps {
+    /** Ordered trail from root to current page; the last item is treated as the current location. */
     items: BreadcrumbItem[];
     class?: string;
 }
+/**
+ * Navigation trail built on Kobalte's `Breadcrumbs` primitive. The last item
+ * in `items` is rendered as plain (non-link) text to indicate the current page.
+ *
+ * @example
+ * ```tsx
+ * <Breadcrumb
+ *   items={[
+ *     { label: 'Projects', href: '/projects' },
+ *     { label: 'A4ui' },
+ *   ]}
+ * />
+ * ```
+ */
 export declare function Breadcrumb(props: BreadcrumbProps): JSX.Element;
 export {};

package/dist/ui/Button.d.ts

@@ -1,10 +1,21 @@
 import { JSX, ParentProps } from 'solid-js';
+/** Visual style of a {@link Button}. Defaults to `'primary'`. */
 export type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost';
 interface ButtonProps extends ParentProps, Omit<JSX.ButtonHTMLAttributes<HTMLButtonElement>, 'type'> {
+    /** Visual style. Defaults to `'primary'`. */
     variant?: ButtonVariant;
     class?: string;
     /** Defaults to "button" so action buttons inside a form never submit it by accident. */
     type?: 'button' | 'submit' | 'reset';
 }
+/**
+ * Base button primitive: a plain `<button>` with A4ui's variants, focus ring,
+ * and press/hover transitions. Accepts all standard button HTML attributes.
+ *
+ * @example
+ * ```tsx
+ * <Button variant="outline" onClick={() => save()}>Save</Button>
+ * ```
+ */
 export declare function Button(props: ButtonProps): JSX.Element;
 export {};

package/dist/ui/Card.d.ts

@@ -11,8 +11,26 @@ interface CardProps extends DivProps {
      */
     glow?: boolean;
 }
+/**
+ * Container surface for grouping related content, with an optional frosted
+ * "space glass" look. Compose with {@link CardHeader}, {@link CardTitle}, and
+ * {@link CardContent}.
+ *
+ * @example
+ * ```tsx
+ * <Card glass>
+ *   <CardHeader>
+ *     <CardTitle>Usage</CardTitle>
+ *   </CardHeader>
+ *   <CardContent>1,204 requests today</CardContent>
+ * </Card>
+ * ```
+ */
 export declare function Card(props: CardProps): JSX.Element;
+/** Header region of a {@link Card}; typically wraps a {@link CardTitle}. */
 export declare function CardHeader(props: DivProps): JSX.Element;
+/** Heading text (rendered as an `<h2>`) for a {@link Card}. */
 export declare function CardTitle(props: DivProps): JSX.Element;
+/** Main body region of a {@link Card}, below the header. */
 export declare function CardContent(props: DivProps): JSX.Element;
 export {};

package/dist/ui/Checkbox.d.ts

@@ -1,9 +1,20 @@
 import { JSX } from 'solid-js';
 interface CheckboxProps {
     checked: boolean;
+    /** Called with the new checked state whenever the input is toggled. */
     onChange: (checked: boolean) => void;
+    /** Visible label rendered next to the checkbox; also makes the whole row clickable. */
     label: string;
     class?: string;
 }
+/**
+ * Plain labeled checkbox (native `<input type="checkbox">`, not a Kobalte
+ * wrapper) for simple boolean toggles with a visible label.
+ *
+ * @example
+ * ```tsx
+ * <Checkbox checked={agreed()} onChange={setAgreed} label="I agree to the terms" />
+ * ```
+ */
 export declare function Checkbox(props: CheckboxProps): JSX.Element;
 export {};

package/dist/ui/Combobox.d.ts

@@ -1,10 +1,26 @@
 import { JSX } from 'solid-js';
 interface ComboboxProps {
+    /** Full list of selectable string options (filtered as the user types). */
     options: string[];
     value: string;
+    /** Called with the newly selected option, or `''` if the selection is cleared. */
     onChange: (value: string) => void;
     placeholder?: string;
     class?: string;
 }
+/**
+ * Searchable single-select dropdown for plain string options, built on
+ * Kobalte's `Combobox` primitive with a filterable text input and trigger.
+ *
+ * @example
+ * ```tsx
+ * <Combobox
+ *   options={['Draft', 'Active', 'Archived']}
+ *   value={status()}
+ *   onChange={setStatus}
+ *   placeholder="Select a status"
+ * />
+ * ```
+ */
 export declare function Combobox(props: ComboboxProps): JSX.Element;
 export {};

package/dist/ui/ContextMenu.d.ts

@@ -1,7 +1,10 @@
 import { JSX, ParentProps } from 'solid-js';
+/** A single actionable row rendered by {@link ContextMenu}. */
 export interface ContextMenuItem {
     label: string;
+    /** Called when the item is chosen (click or keyboard activation). */
     onSelect: () => void;
+    /** Styles the label as a destructive action (e.g. "Delete"). */
     destructive?: boolean;
     disabled?: boolean;
 }
@@ -9,5 +12,16 @@ interface ContextMenuProps extends ParentProps {
     items: ContextMenuItem[];
     class?: string;
 }
+/**
+ * Right-click (or long-press) menu built on Kobalte's `ContextMenu`
+ * primitive. `children` is the element that acts as the trigger/target area.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenu items={[{ label: 'Rename', onSelect: rename }, { label: 'Delete', onSelect: remove, destructive: true }]}>
+ *   <div class="rounded border p-4">Right-click me</div>
+ * </ContextMenu>
+ * ```
+ */
 export declare function ContextMenu(props: ContextMenuProps): JSX.Element;
 export {};

package/dist/ui/DateField.d.ts

@@ -1,7 +1,10 @@
 import { JSX } from 'solid-js';
 interface DateFieldProps {
+    /** Selected date as `YYYY-MM-DD` (local, no timezone shift), or `''` for none. */
     value: string;
+    /** Called with the newly picked date as `YYYY-MM-DD`. */
     onChange: (value: string) => void;
+    /** Placeholder shown on the trigger when `value` is empty. */
     label?: string;
     disabled?: boolean;
     class?: string;
@@ -10,5 +13,16 @@ interface DateFieldProps {
     /** Weekday headers, Monday-first (7 entries). */
     weekdays?: string[];
 }
+/**
+ * Compact hand-rolled month-grid date picker (no Kobalte primitive covers this yet).
+ * Trigger button opens a portaled popover calendar; closes on outside click, Escape,
+ * scroll, or resize. Speaks plain `YYYY-MM-DD` strings, never `Date`/`toISOString`.
+ *
+ * @example
+ * ```tsx
+ * const [date, setDate] = createSignal('2026-07-14')
+ * <DateField value={date()} onChange={setDate} label="Due date" />
+ * ```
+ */
 export declare function DateField(props: DateFieldProps): JSX.Element;
 export {};

package/dist/ui/Drawer.d.ts

@@ -2,10 +2,26 @@ import { JSX, ParentProps } from 'solid-js';
 interface DrawerProps extends ParentProps {
     open: boolean;
     onOpenChange: (open: boolean) => void;
+    /** Sticky glass header title. Omit to render fully custom header content in `children`. */
     title?: string;
+    /** Small muted line under `title`; only shown when `title` is also set. */
     subtitle?: string;
     class?: string;
+    /** Accessible label for the close button. @default 'Close' */
     closeLabel?: string;
 }
+/**
+ * Right-anchored slide-over panel built on Kobalte's `Dialog` (focus trap, portal,
+ * and open/close presence handled for you). Use for create/edit forms or detail
+ * panels that need more room than a centered `Modal`.
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = createSignal(false)
+ * <Drawer open={open()} onOpenChange={setOpen} title="Edit invoice">
+ *   <p>Drawer content…</p>
+ * </Drawer>
+ * ```
+ */
 export declare function Drawer(props: DrawerProps): JSX.Element;
 export {};

package/dist/ui/Dropdown.d.ts

@@ -1,7 +1,9 @@
 import { JSX, ParentProps } from 'solid-js';
+/** A single selectable row in a {@link Dropdown} menu. */
 export interface DropdownItem {
     label: string;
     onSelect: () => void;
+    /** Styles the label in the destructive color (e.g. "Delete"). */
     destructive?: boolean;
     disabled?: boolean;
 }
@@ -12,6 +14,21 @@ interface DropdownProps extends ParentProps {
         inside — the Trigger IS the button, so its children must be non-interactive. */
     label?: string;
 }
-/** `props.children` is the trigger's (non-interactive) content. */
+/**
+ * Accessible dropdown/context menu on Kobalte's `DropdownMenu` primitive.
+ * `props.children` is the trigger's (non-interactive) content — the Trigger
+ * itself renders as the button, so don't nest another `<button>` inside it.
+ * Unlike a Dialog, it does not lock page scroll while open.
+ *
+ * @example
+ * ```tsx
+ * <Dropdown label="Row actions" items={[
+ *   { label: 'Edit', onSelect: () => edit(row) },
+ *   { label: 'Delete', destructive: true, onSelect: () => remove(row) },
+ * ]}>
+ *   <MoreVertical class="h-4 w-4" />
+ * </Dropdown>
+ * ```
+ */
 export declare function Dropdown(props: DropdownProps): JSX.Element;
 export {};

package/dist/ui/Dropzone.d.ts

@@ -1,5 +1,6 @@
 import { JSX } from 'solid-js';
 interface DropzoneProps {
+    /** Called with the dropped or browsed files; the caller owns upload/validation. */
     onFiles: (files: File[]) => void;
     /** `accept` attribute for the hidden input, e.g. ".xml,.zip". */
     accept?: string;
@@ -9,5 +10,15 @@ interface DropzoneProps {
     hint?: string;
     label?: string;
 }
+/**
+ * Presentational drag-and-drop (or click-to-browse) file dropzone. Not a Kobalte
+ * wrapper — just a styled `role="button"` region plus a hidden `<input type="file">`.
+ * It only collects `File[]` via `onFiles`; it does not upload or store anything.
+ *
+ * @example
+ * ```tsx
+ * <Dropzone accept=".xml,.zip" multiple onFiles={(files) => upload(files)} />
+ * ```
+ */
 export declare function Dropzone(props: DropzoneProps): JSX.Element;
 export {};

package/dist/ui/HoverCard.d.ts

@@ -1,7 +1,20 @@
 import { JSX, ParentProps } from 'solid-js';
 interface HoverCardProps extends ParentProps {
+    /** Content that opens the card on hover/focus. */
     trigger: JSX.Element;
     class?: string;
 }
+/**
+ * Floating panel that appears on hover (or focus) of a trigger element, built on
+ * Kobalte's `HoverCard` primitive. Good for previews/tooltips with richer content
+ * than a plain `title` attribute — e.g. a user avatar preview card.
+ *
+ * @example
+ * ```tsx
+ * <HoverCard trigger={<Avatar src={user.avatar} />}>
+ *   <p>{user.name}</p>
+ * </HoverCard>
+ * ```
+ */
 export declare function HoverCard(props: HoverCardProps): JSX.Element;
 export {};

package/dist/ui/Input.d.ts

@@ -1,8 +1,20 @@
 import { JSX } from 'solid-js';
 interface InputProps extends Omit<JSX.InputHTMLAttributes<HTMLInputElement>, 'value' | 'onInput'> {
     value: string;
+    /** Called with the raw string value on every input event (controlled). */
     onInput: (value: string) => void;
     class?: string;
 }
+/**
+ * Themed text input with a value/onInput controlled-string API (instead of raw
+ * DOM events). All other native `<input>` attributes pass through, so `type`,
+ * `disabled`, `placeholder`, etc. work as usual.
+ *
+ * @example
+ * ```tsx
+ * const [name, setName] = createSignal('')
+ * <Input value={name()} onInput={setName} placeholder="Full name" />
+ * ```
+ */
 export declare function Input(props: InputProps): JSX.Element;
 export {};

package/dist/ui/Meter.d.ts

@@ -1,9 +1,21 @@
 import { JSX } from 'solid-js';
 interface MeterProps {
     value: number;
+    /** @default 100 */
     max?: number;
+    /** Label shown above the track, paired with an auto-formatted value label. */
     label?: string;
     class?: string;
 }
+/**
+ * Static measurement gauge (e.g. disk/quota usage) on Kobalte's `Meter` primitive.
+ * Unlike a progress bar, a meter represents a fixed measurement against a range,
+ * not an in-flight operation.
+ *
+ * @example
+ * ```tsx
+ * <Meter value={72} max={100} label="Storage used" />
+ * ```
+ */
 export declare function Meter(props: MeterProps): JSX.Element;
 export {};

package/dist/ui/Modal.d.ts

@@ -2,10 +2,31 @@ import { JSX, ParentProps } from 'solid-js';
 interface ModalProps extends ParentProps {
     open: boolean;
     onOpenChange: (open: boolean) => void;
+    /** Header title; omitting it hides the whole header bar. */
     title?: string;
+    /**
+     * `'drawer'` (default): right-anchored slide-over, more room, less jarring —
+     * use for forms/detail panels. `'center'`: classic centered modal — use for
+     * short confirmations (e.g. destructive yes/no).
+     * @default 'drawer'
+     */
     variant?: 'drawer' | 'center';
     class?: string;
+    /** Accessible label for the close button. @default 'Close' */
     closeLabel?: string;
 }
+/**
+ * Dialog on Kobalte's `Dialog` primitive (focus trap, portal, presence handled
+ * for you), rendered as either a slide-over drawer or a centered modal depending
+ * on `variant`.
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = createSignal(false)
+ * <Modal open={open()} onOpenChange={setOpen} variant="center" title="Delete item?">
+ *   <p>This action cannot be undone.</p>
+ * </Modal>
+ * ```
+ */
 export declare function Modal(props: ModalProps): JSX.Element;
 export {};

package/dist/ui/NumberInput.d.ts

@@ -2,9 +2,21 @@ import { JSX } from 'solid-js';
 interface NumberInputProps {
     value: number;
     onChange: (value: number) => void;
+    /** Lower bound; the decrement trigger disables itself at this value. */
     min?: number;
+    /** Upper bound; the increment trigger disables itself at this value. */
     max?: number;
     class?: string;
 }
+/**
+ * Numeric field with −/+ stepper buttons, built on Kobalte's `NumberField` primitive.
+ * Use for bounded numeric input (quantities, counts) where clicking to nudge the
+ * value is preferable to typing alone.
+ *
+ * @example
+ * ```tsx
+ * <NumberInput value={qty()} onChange={setQty} min={0} max={99} />
+ * ```
+ */
 export declare function NumberInput(props: NumberInputProps): JSX.Element;
 export {};

package/dist/ui/PageHeader.d.ts

@@ -2,8 +2,25 @@ import { JSX } from 'solid-js';
 interface PageHeaderProps {
     title: string;
     subtitle?: string;
+    /** Trail of crumb labels, in order; the last one is rendered highlighted as the current page. */
     breadcrumb?: string[];
+    /** Right-aligned slot for page-level actions (buttons, menus, etc.). */
     actions?: JSX.Element;
 }
+/**
+ * Consistent top-of-page header: optional breadcrumb trail, title, subtitle,
+ * and a right-aligned actions slot. Use at the top of a route/page for a
+ * uniform layout across the app.
+ *
+ * @example
+ * ```tsx
+ * <PageHeader
+ *   title="Invoices"
+ *   subtitle="Manage billing documents"
+ *   breadcrumb={['Home', 'Billing', 'Invoices']}
+ *   actions={<Button>New invoice</Button>}
+ * />
+ * ```
+ */
 export declare function PageHeader(props: PageHeaderProps): JSX.Element;
 export {};

package/dist/ui/Pagination.d.ts

@@ -1,14 +1,28 @@
 import { JSX } from 'solid-js';
 interface PaginationProps {
+    /** Current page, 1-indexed. */
     page: number;
     totalPages: number;
     onChange: (page: number) => void;
+    /** Left-aligned slot, e.g. a row-count summary like "1,234 registros · 1–50". */
     summary?: JSX.Element;
+    /** Override default English labels/text for i18n. */
     labels?: {
         previous?: string;
         next?: string;
+        /** Formats the center label; default is `` `Page ${page} of ${total}` ``. */
         page?: (page: number, total: number) => string;
     };
 }
+/**
+ * Prev/next pager with a "Page X of Y" label and an optional summary slot.
+ * Purely client-side and controlled — the parent owns the `page` signal and
+ * is responsible for slicing its own data to match.
+ *
+ * @example
+ * ```tsx
+ * <Pagination page={page()} totalPages={totalPages()} onChange={setPage} />
+ * ```
+ */
 export declare function Pagination(props: PaginationProps): JSX.Element;
 export {};

package/dist/ui/Popover.d.ts

@@ -1,7 +1,20 @@
 import { JSX, ParentProps } from 'solid-js';
 interface PopoverProps extends ParentProps {
+    /** Element that opens the popover on click; wrapped in an inline-flex trigger. */
     trigger: JSX.Element;
     class?: string;
 }
+/**
+ * Click-triggered floating panel, built on Kobalte's `Popover` primitive
+ * (handles positioning, focus, dismiss, and portaling). Use for contextual
+ * content anchored to a trigger element, such as a filter panel or menu.
+ *
+ * @example
+ * ```tsx
+ * <Popover trigger={<Button>Filters</Button>}>
+ *   <p>Panel content</p>
+ * </Popover>
+ * ```
+ */
 export declare function Popover(props: PopoverProps): JSX.Element;
 export {};

package/dist/ui/Progress.d.ts

@@ -1,9 +1,20 @@
 import { JSX } from 'solid-js';
 interface ProgressProps {
     value: number;
+    /** Upper bound of `value`. Default: 100. */
     max?: number;
+    /** Label shown above the bar, paired with an auto-generated value label (e.g. "50%"). */
     label?: string;
     class?: string;
 }
+/**
+ * Determinate progress bar, built on Kobalte's `Progress` primitive. Use to
+ * show completion of a known-length task (upload, multi-step form, etc.).
+ *
+ * @example
+ * ```tsx
+ * <Progress value={uploaded()} max={totalBytes()} label="Uploading" />
+ * ```
+ */
 export declare function Progress(props: ProgressProps): JSX.Element;
 export {};

package/dist/ui/RadioGroup.d.ts

@@ -1,4 +1,5 @@
 import { JSX } from 'solid-js';
+/** A single selectable choice within a {@link RadioGroup}. */
 export interface RadioOption {
     value: string;
     label: string;
@@ -8,8 +9,27 @@ interface RadioGroupProps {
     value: string;
     onChange: (value: string) => void;
     options: RadioOption[];
+    /** Group label rendered above the options. */
     label?: string;
     class?: string;
 }
+/**
+ * Accessible single-choice group, built on Kobalte's `RadioGroup` primitive
+ * (arrow-key navigation, ARIA roles). Use when all options should stay
+ * visible at once, unlike {@link Select} which hides options until opened.
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup
+ *   label="Plan"
+ *   value={plan()}
+ *   onChange={setPlan}
+ *   options={[
+ *     { value: 'free', label: 'Free' },
+ *     { value: 'pro', label: 'Pro' },
+ *   ]}
+ * />
+ * ```
+ */
 export declare function RadioGroup(props: RadioGroupProps): JSX.Element;
 export {};

package/dist/ui/SegmentedControl.d.ts

@@ -1,4 +1,5 @@
 import { JSX } from 'solid-js';
+/** A single selectable choice within a {@link SegmentedControl}. */
 export interface SegmentedOption {
     value: string;
     label: string;
@@ -9,5 +10,23 @@ interface SegmentedControlProps {
     options: SegmentedOption[];
     class?: string;
 }
+/**
+ * Single-choice segmented control with an animated indicator that slides
+ * under the selected item, built on Kobalte's `SegmentedControl` primitive.
+ * Use for a small, always-visible set of mutually exclusive options (e.g.
+ * view toggles) as a more compact alternative to {@link RadioGroup}.
+ *
+ * @example
+ * ```tsx
+ * <SegmentedControl
+ *   value={view()}
+ *   onChange={setView}
+ *   options={[
+ *     { value: 'list', label: 'List' },
+ *     { value: 'grid', label: 'Grid' },
+ *   ]}
+ * />
+ * ```
+ */
 export declare function SegmentedControl(props: SegmentedControlProps): JSX.Element;
 export {};

package/dist/ui/Select.d.ts

@@ -4,5 +4,19 @@ interface SelectProps extends ParentProps, Omit<JSX.SelectHTMLAttributes<HTMLSel
     onChange: (value: string) => void;
     class?: string;
 }
+/**
+ * Controlled native `<select>`, styled to match the design system. Pass
+ * `<option>` elements as children. Not a Kobalte primitive — for a
+ * non-native, fully custom dropdown consider building on Kobalte's `Select`
+ * directly.
+ *
+ * @example
+ * ```tsx
+ * <Select value={country()} onChange={setCountry}>
+ *   <option value="mx">Mexico</option>
+ *   <option value="us">United States</option>
+ * </Select>
+ * ```
+ */
 export declare function Select(props: SelectProps): JSX.Element;
 export {};

package/dist/ui/Separator.d.ts

@@ -1,7 +1,18 @@
 import { JSX } from 'solid-js';
 interface SeparatorProps {
+    /** Default: `'horizontal'`. */
     orientation?: 'horizontal' | 'vertical';
     class?: string;
 }
+/**
+ * Visual/semantic divider, built on Kobalte's `Separator` primitive (renders
+ * with the correct ARIA role for the given orientation). Use to separate
+ * groups of content, e.g. inside a menu or between toolbar sections.
+ *
+ * @example
+ * ```tsx
+ * <Separator orientation="vertical" />
+ * ```
+ */
 export declare function Separator(props: SeparatorProps): JSX.Element;
 export {};

package/dist/ui/Skeleton.d.ts

@@ -1,6 +1,17 @@
 import { JSX } from 'solid-js';
 interface SkeletonProps {
+    /** Size/shape the placeholder to match the content it stands in for, e.g. `"h-4 w-32 rounded-full"`. */
     class?: string;
 }
+/**
+ * Pulsing placeholder block for content that is still loading. Plain `div`,
+ * no Kobalte primitive — size it via `class` to match the shape of the real
+ * content (text line, avatar, card, etc.).
+ *
+ * @example
+ * ```tsx
+ * <Skeleton class="h-4 w-48" />
+ * ```
+ */
 export declare function Skeleton(props: SkeletonProps): JSX.Element;
 export {};

package/dist/ui/Slider.d.ts

@@ -2,11 +2,25 @@ import { JSX } from 'solid-js';
 interface SliderProps {
     value: number;
     onChange: (value: number) => void;
+    /** Default: 0. */
     min?: number;
+    /** Default: 100. */
     max?: number;
+    /** Increment step. Default: 1. */
     step?: number;
+    /** Label shown above the track, paired with an auto-generated value label. */
     label?: string;
     class?: string;
 }
+/**
+ * Single-value range slider, built on Kobalte's `Slider` primitive (which
+ * natively supports multiple thumbs). This wrapper accepts and emits a plain
+ * `number` instead of an array, for a simpler single-thumb API.
+ *
+ * @example
+ * ```tsx
+ * <Slider label="Volume" value={volume()} onChange={setVolume} min={0} max={100} />
+ * ```
+ */
 export declare function Slider(props: SliderProps): JSX.Element;
 export {};