@a4ui/core 0.1.1 → 0.3.0

package/dist/layout/AppShell.d.ts

@@ -1,4 +1,5 @@
 import { JSX, ParentProps } from 'solid-js';
+/** Props for {@link AppShell}. All slots are optional — pass only what your app needs. */
 interface AppShellProps extends ParentProps {
     /** Left column (e.g. a Sidebar). Rendered as a flex child; owns its own width. */
     sidebar?: JSX.Element;
@@ -11,8 +12,25 @@ interface AppShellProps extends ParentProps {
     background?: JSX.Element;
     /** Max content width for <main>. Default '1400px'. */
     maxWidth?: string;
-    /** Override the default error fallback shown when a route throws. */
+    /** Override the default error fallback shown when a route throws. Receives
+        the caught error and a `reset` callback that re-renders the ErrorBoundary's
+        children. */
     errorFallback?: (err: unknown, reset: () => void) => JSX.Element;
 }
+/**
+ * Generic app shell: a fixed {@link SpaceBackground} behind a flex layout of
+ * an optional sidebar slot plus a content column (optional banner + topbar +
+ * routed `<main>`). Slot-based and unopinionated about the sidebar — pass
+ * your own component via `sidebar` and it manages its own width/collapse.
+ * `<main>` is wrapped in `Suspense` + an `ErrorBoundary` (with a ~160ms page
+ * cross-fade) so a route chunk failing or still loading never blanks the shell.
+ *
+ * @example
+ * ```tsx
+ * <AppShell sidebar={<Sidebar />} topbar={<Topbar />}>
+ *   <Route />
+ * </AppShell>
+ * ```
+ */
 export declare function AppShell(props: ParentProps<AppShellProps>): JSX.Element;
 export {};

package/dist/layout/EffectsToggle.d.ts

@@ -1 +1,19 @@
-export declare function EffectsToggle(): import("solid-js").JSX.Element;
+/** Props for {@link EffectsToggle}. */
+interface EffectsToggleProps {
+    /** Accessible label / tooltip text. Defaults to `'Visual effects'`. */
+    label?: string;
+}
+/**
+ * Icon button that toggles the "visual effects" switch: pressed (default) is
+ * the full space-glass experience (translucent glass, starfield, animation);
+ * un-pressed is calm mode (opaque surfaces, no starfield, no motion) — useful
+ * for contrast, motion sensitivity, and low-power devices. Wraps
+ * {@link useEffects} + {@link setEffects}.
+ *
+ * @example
+ * ```tsx
+ * <EffectsToggle label="Toggle effects" />
+ * ```
+ */
+export declare function EffectsToggle(props: EffectsToggleProps): import("solid-js").JSX.Element;
+export {};

package/dist/layout/NavGroup.d.ts

@@ -1,6 +1,21 @@
 import { JSX, ParentProps } from 'solid-js';
+/** Props for {@link NavGroup}. */
 interface NavGroupProps extends ParentProps {
+    /** Category heading shown in the summary row (rendered uppercase). */
     title: string;
 }
+/**
+ * Collapsible sidebar nav category. Uses native `<details>`/`<summary>` (no
+ * JS state), with a chevron that rotates via a `group-[[open]]` CSS variant.
+ * Expanded by default; wrap a list of nav links as `children`.
+ *
+ * @example
+ * ```tsx
+ * <NavGroup title="Settings">
+ *   <NavLink href="/settings/profile">Profile</NavLink>
+ *   <NavLink href="/settings/billing">Billing</NavLink>
+ * </NavGroup>
+ * ```
+ */
 export declare function NavGroup(props: NavGroupProps): JSX.Element;
 export {};

package/dist/layout/SpaceBackground.d.ts

@@ -1 +1,14 @@
+/**
+ * The "space glass" backdrop: a fixed, `aria-hidden` layer (z-0) meant to sit
+ * behind all page content (this is {@link AppShell}'s default `background`).
+ * Renders a randomized starfield (with twinkle + occasional shooting stars,
+ * or rockets in light theme), static nebula/planets, gyroscope parallax on
+ * phones, and cursor-glow/magnetic-button effects. Takes no props; reacts to
+ * {@link useTheme} for star tints and to `motionReduced()` to skip all motion.
+ *
+ * @example
+ * ```tsx
+ * <SpaceBackground />
+ * ```
+ */
 export declare function SpaceBackground(): import("solid-js").JSX.Element;

package/dist/layout/ThemeToggle.d.ts

@@ -1,2 +1,18 @@
 import { JSX } from 'solid-js';
-export declare function ThemeToggle(): JSX.Element;
+/** Props for {@link ThemeToggle}. */
+interface ThemeToggleProps {
+    /** Accessible label / tooltip text. Defaults to `'Toggle theme'`. */
+    label?: string;
+}
+/**
+ * Icon button that flips between dark and light theme. The icon shows the
+ * CURRENT theme (moon when dark, sun when light), not the theme you'd switch
+ * to. Wraps {@link useTheme} + {@link toggleTheme}.
+ *
+ * @example
+ * ```tsx
+ * <ThemeToggle label="Switch theme" />
+ * ```
+ */
+export declare function ThemeToggle(props: ThemeToggleProps): JSX.Element;
+export {};

package/dist/lib/cn.d.ts

@@ -1,3 +1,13 @@
 import { ClassValue } from 'clsx';
-/** Merge Tailwind class lists, resolving conflicting utilities left-to-right. */
+/**
+ * Merge Tailwind class lists, resolving conflicting utilities left-to-right
+ * (via `tailwind-merge`) after flattening conditionals/arrays/objects (via `clsx`).
+ * Use this instead of template-string concatenation whenever a component
+ * accepts a `class` override that should win over its own defaults.
+ *
+ * @example
+ * ```ts
+ * cn('px-2 py-1 text-sm', isActive && 'bg-primary text-primary-foreground', props.class)
+ * ```
+ */
 export declare function cn(...inputs: ClassValue[]): string;

package/dist/lib/effects.d.ts

@@ -1,4 +1,25 @@
+/**
+ * Reactive accessor for the "visual effects" switch: `true` = full
+ * space-glass experience (glass, starfield, animation), `false` = calm mode.
+ * Backing signal shared module-wide, so every consumer (e.g.
+ * {@link EffectsToggle}) reads the same source of truth.
+ *
+ * @example
+ * ```ts
+ * const effectsOn = useEffects()
+ * console.log(effectsOn()) // true | false
+ * ```
+ */
 export declare function useEffects(): import('solid-js').Accessor<boolean>;
 /** True when visual effects are OFF (calm mode). Read by motion + charts. */
 export declare function isCalm(): boolean;
+/**
+ * Persist and apply the visual-effects switch: toggles `html.calm` (opaque
+ * surfaces, no starfield, no motion when off) and updates {@link useEffects}.
+ *
+ * @example
+ * ```ts
+ * setEffects(false) // enter calm mode
+ * ```
+ */
 export declare function setEffects(on: boolean): void;

package/dist/lib/media.d.ts

@@ -1 +1,13 @@
+/**
+ * Reactive `matchMedia` matcher: returns a signal accessor that updates when
+ * the query's match state changes, cleaning up its listener on unmount.
+ * Handy for rendering either a desktop or mobile layout instead of hiding one
+ * with CSS.
+ *
+ * @example
+ * ```tsx
+ * const isDesktop = useMediaQuery('(min-width: 768px)')
+ * return isDesktop() ? <DesktopTable /> : <MobileCards />
+ * ```
+ */
 export declare function useMediaQuery(query: string): () => boolean;

package/dist/lib/motion.d.ts

@@ -3,15 +3,46 @@ import { Accessor } from 'solid-js';
  * Snapshot of the user's reduced-motion preference at call time. Not
  * reactive to preference changes mid-session (matches theme.ts's one-shot
  * environment read) — reload picks up changes.
+ *
+ * @example
+ * ```ts
+ * if (prefersReducedMotion()) skipEntranceAnimation()
+ * ```
  */
 export declare function prefersReducedMotion(): boolean;
+/**
+ * Reactive accessor for the persisted "force full motion" opt-out (the ⚡
+ * MotionToggle) — `true` re-enables animation even when the OS requests
+ * reduced motion.
+ *
+ * @example
+ * ```ts
+ * const forced = useMotionForced()
+ * console.log(forced()) // true | false
+ * ```
+ */
 export declare function useMotionForced(): Accessor<boolean>;
+/**
+ * Persist the "force full motion" choice, toggle `html.force-motion`
+ * (which the reduced-motion `@media` block in styles.css keys off), and
+ * update {@link useMotionForced}.
+ *
+ * @example
+ * ```ts
+ * setMotionForced(true) // opt back into full motion despite OS setting
+ * ```
+ */
 export declare function setMotionForced(on: boolean): void;
 /**
  * Effective reduced-motion: reduced when calm mode (visual effects OFF) is on,
  * or when the OS asks for reduced motion and the user hasn't forced it. JS-driven
  * motion (SpaceBackground, count-up) gates on this rather than
  * prefersReducedMotion() directly.
+ *
+ * @example
+ * ```ts
+ * if (!motionReduced()) startParallaxLoop()
+ * ```
  */
 export declare function motionReduced(): boolean;
 /**
@@ -20,5 +51,11 @@ export declare function motionReduced(): boolean;
  * yet, and this needs to interpolate a plain number rather than a DOM
  * property, so it's a small hand-rolled WAAPI-adjacent tween for KPI count-up).
  * Jumps straight to the target under prefers-reduced-motion.
+ *
+ * @example
+ * ```tsx
+ * const animated = createCountUp(() => props.value, 800)
+ * return <span>{Math.round(animated())}</span>
+ * ```
  */
 export declare function createCountUp(target: Accessor<number>, durationMs?: number): Accessor<number>;

package/dist/lib/theme.d.ts

@@ -1,10 +1,59 @@
+/** The two supported color schemes. `'dark'` (the "night" palette) is the default. */
 export type Theme = 'dark' | 'light';
-/** The persisted choice, defaulting to dark when nothing is stored. */
+/**
+ * Read the persisted theme choice from `localStorage`, defaulting to `'dark'`
+ * when nothing is stored (or storage is unavailable).
+ *
+ * @example
+ * ```ts
+ * const initial = storedTheme() // 'dark' | 'light'
+ * ```
+ */
 export declare function storedTheme(): Theme;
-/** Reflect the theme onto <html data-theme>: dark is the default (no attribute). */
+/**
+ * Reflect a theme onto `<html data-theme>` without touching storage or the
+ * shared signal. Dark is the default (no attribute); light sets
+ * `data-theme="light"`. Prefer {@link setTheme} unless you specifically need
+ * to apply without persisting.
+ *
+ * @example
+ * ```ts
+ * applyTheme('light')
+ * ```
+ */
 export declare function applyTheme(theme: Theme): void;
-/** Persist and apply a theme choice. */
+/**
+ * Persist a theme choice to `localStorage` and apply it to `<html>`. Does not
+ * update the shared `useTheme()` signal directly — {@link toggleTheme} does
+ * that after calling this.
+ *
+ * @example
+ * ```ts
+ * setTheme('light')
+ * ```
+ */
 export declare function setTheme(theme: Theme): void;
+/**
+ * The opposite of the given theme. Pure helper (no signal/storage side effects)
+ * used by {@link toggleTheme}.
+ *
+ * @example
+ * ```ts
+ * toggled('dark') // 'light'
+ * ```
+ */
 export declare function toggled(theme: Theme): Theme;
+/**
+ * Reactive accessor for the current theme, shared module-wide so every
+ * consumer (e.g. {@link ThemeToggle}, `SpaceBackground`) reads the same
+ * source of truth.
+ *
+ * @example
+ * ```ts
+ * const theme = useTheme()
+ * console.log(theme()) // 'dark' | 'light'
+ * ```
+ */
 export declare function useTheme(): import('solid-js').Accessor<Theme>;
+/** Flip the current theme (dark↔light), persisting and applying the new value. */
 export declare function toggleTheme(): void;

package/dist/lib/virtual.d.ts

@@ -1,2 +1,18 @@
 import { Accessor } from 'solid-js';
+/**
+ * Works around a `@tanstack/solid-virtual` bug where the virtualizer measures
+ * a 0×0 viewport: it attaches its `ResizeObserver` during the render pass
+ * (when `getScrollElement` first returns the scroll container), before the
+ * container has been laid out, so it caches a 0×0 size and never renders any
+ * rows. Once layout settles, this detaches+reattaches the scroll element so
+ * the observer re-measures the real height. Call it right after wiring up
+ * the virtualizer, passing the scroll-element signal's getter and setter.
+ *
+ * @example
+ * ```ts
+ * const [scrollEl, setScrollEl] = createSignal<HTMLElement>()
+ * const virtualizer = createVirtualizer({ getScrollElement: scrollEl, ... })
+ * remeasureAfterLayout(scrollEl, setScrollEl)
+ * ```
+ */
 export declare function remeasureAfterLayout(scrollEl: Accessor<HTMLElement | undefined>, setScrollEl: (v: HTMLElement | undefined) => void): void;

package/dist/styles.css

@@ -18,11 +18,11 @@
   --muted-foreground: 215 25% 75%;
   --border: 217 30% 22%;
   --input: 217 30% 22%;
-  --primary: 217 91% 60%;
+  --primary: 217 91% 52%;
   --primary-foreground: 0 0% 100%;
   --accent: 199 89% 55%;
   --accent-foreground: 0 0% 100%;
-  --ring: 217 91% 60%;
+  --ring: 217 91% 52%;
   --destructive: 0 72% 55%;
   --destructive-foreground: 0 0% 100%;
 
@@ -54,11 +54,11 @@
   --muted-foreground: 215 22% 38%;
   --border: 214 24% 84%;
   --input: 214 32% 91%;
-  --primary: 217 91% 55%;
+  --primary: 217 91% 52%;
   --primary-foreground: 0 0% 100%;
   --accent: 199 89% 48%;
   --accent-foreground: 0 0% 100%;
-  --ring: 217 91% 55%;
+  --ring: 217 91% 52%;
   --destructive: 0 72% 51%;
   --destructive-foreground: 0 0% 100%;
 }

package/dist/ui/Accordion.d.ts

@@ -1,13 +1,32 @@
 import { JSX } from 'solid-js';
+/** A single collapsible section rendered by {@link Accordion}. */
 export interface AccordionItem {
+    /** Unique identifier for the item; used to track expanded state. */
     value: string;
+    /** Text shown in the trigger row. */
     title: string;
+    /** Content revealed when the item is expanded. */
     content: JSX.Element;
 }
 interface AccordionProps {
     items: AccordionItem[];
+    /** Allow more than one item to be expanded at the same time. Defaults to `false` (single-open). */
     multiple?: boolean;
     class?: string;
 }
+/**
+ * Accessible, collapsible list of sections built on Kobalte's `Accordion` primitive.
+ * Each entry in `items` renders as a header/trigger row plus a content panel.
+ *
+ * @example
+ * ```tsx
+ * <Accordion
+ *   items={[
+ *     { value: 'a', title: 'What is A4ui?', content: <p>A SolidJS design system.</p> },
+ *     { value: 'b', title: 'How do I install it?', content: <p>npm install a4ui</p> },
+ *   ]}
+ * />
+ * ```
+ */
 export declare function Accordion(props: AccordionProps): JSX.Element;
 export {};

package/dist/ui/Alert.d.ts

@@ -1,9 +1,23 @@
 import { JSX, ParentProps } from 'solid-js';
+/** Semantic tone of an {@link Alert}; drives the border/background tint and icon. */
 export type AlertTone = 'info' | 'success' | 'warning' | 'danger';
 interface AlertProps extends ParentProps {
+    /** Visual/semantic tone. Defaults to `'info'`. */
     tone?: AlertTone;
+    /** Optional bold heading shown above the body text. */
     title?: string;
     class?: string;
 }
+/**
+ * Inline status banner (not a toast/dialog) built on Kobalte's `Alert` primitive,
+ * for surfacing info/success/warning/danger messages inline in the page.
+ *
+ * @example
+ * ```tsx
+ * <Alert tone="warning" title="Heads up">
+ *   Your session will expire in 5 minutes.
+ * </Alert>
+ * ```
+ */
 export declare function Alert(props: AlertProps): JSX.Element;
 export {};

package/dist/ui/AlertDialog.d.ts

@@ -1,9 +1,24 @@
 import { JSX, ParentProps } from 'solid-js';
 interface AlertDialogProps extends ParentProps {
+    /** Whether the dialog is currently visible. */
     open: boolean;
+    /** Called when the dialog requests to open/close (overlay click, Escape, etc). */
     onOpenChange: (open: boolean) => void;
+    /** Optional heading rendered above the description. */
     title?: string;
     class?: string;
 }
+/**
+ * Centered, focus-trapped confirmation modal built on Kobalte's `AlertDialog`
+ * primitive. Use for interruptive confirmations (e.g. "Delete this item?")
+ * rather than for general-purpose dialogs.
+ *
+ * @example
+ * ```tsx
+ * <AlertDialog open={confirmOpen()} onOpenChange={setConfirmOpen} title="Delete project?">
+ *   This action cannot be undone.
+ * </AlertDialog>
+ * ```
+ */
 export declare function AlertDialog(props: AlertDialogProps): JSX.Element;
 export {};

package/dist/ui/Avatar.d.ts

@@ -1,9 +1,20 @@
 import { JSX } from 'solid-js';
 interface AvatarProps {
+    /** Image URL. If it fails to load (or is omitted), `fallback` is shown instead. */
     src?: string;
     alt?: string;
+    /** Text shown when there is no image or it fails to load (typically initials). */
     fallback: string;
     class?: string;
 }
+/**
+ * Circular user avatar built on Kobalte's `Image` primitive; automatically
+ * falls back to initials/text when the image is missing or fails to load.
+ *
+ * @example
+ * ```tsx
+ * <Avatar src={user.avatarUrl} alt={user.name} fallback="JD" />
+ * ```
+ */
 export declare function Avatar(props: AvatarProps): JSX.Element;
 export {};

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,10 +1,28 @@
 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;
+    /** Full month names, January … December order (12 entries). */
+    months?: string[];
+    /** 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 {};