@a4ui/core 0.4.3 → 0.6.0

package/dist/layout/ChristmasBackground.d.ts

@@ -0,0 +1,8 @@
+import { JSX } from 'solid-js';
+/**
+ * Festive backdrop for the `christmas` theme: night sky, falling snow, a
+ * twinkling light garland, a pine tree, and Santa's sleigh flying across (ambient
+ * + on background click). Mount as {@link AppShell}'s `background`. Motion is
+ * skipped under `motionReduced()`.
+ */
+export declare function ChristmasBackground(): JSX.Element;

package/dist/layout/SnowScenery.d.ts

@@ -0,0 +1,7 @@
+import { JSX } from 'solid-js';
+/**
+ * Falling-snow backdrop for the `snow` theme: snowflakes drift down, a snow bank
+ * gathers at the bottom, and cards get a frosted cap. Mount as {@link AppShell}'s
+ * `background`. Motion is skipped under `motionReduced()`.
+ */
+export declare function SnowScenery(): JSX.Element;

package/dist/styles.css

@@ -623,3 +623,102 @@ body {
     animation: none !important;
   }
 }
+
+/* ---- Snow scenery (the "snow" theme) ------------------------------------ */
+#snow,
+#xmas {
+  position: fixed;
+  inset: 0;
+  z-index: 0;
+  pointer-events: none;
+  overflow: hidden;
+}
+#snow .snow-sky {
+  position: absolute;
+  inset: 0;
+  background:
+    radial-gradient(1200px 800px at 50% -12%, hsl(var(--primary) / 0.18), transparent 60%),
+    radial-gradient(900px 700px at 82% 8%, hsl(var(--accent) / 0.14), transparent 60%), hsl(var(--background));
+}
+/* Snowflakes (shared by snow + christmas). Each drifts down with a sideways sway. */
+#snow .flake,
+#xmas .flake {
+  position: absolute;
+  top: -12px;
+  border-radius: 50%;
+  background: #fff;
+  box-shadow: 0 0 4px rgba(255, 255, 255, 0.6);
+  will-change: transform;
+}
+[data-theme='light'] #snow .flake,
+[data-theme='light'] #xmas .flake {
+  background: hsl(205 45% 82%);
+  box-shadow: 0 0 3px hsl(205 45% 72% / 0.6);
+}
+@keyframes snowFall {
+  0% {
+    transform: translate(0, -12px);
+  }
+  100% {
+    transform: translate(var(--sway, 12px), 112vh);
+  }
+}
+/* Snow settling at the bottom + a frosted cap on cards (snow theme only). */
+#snow .snow-bank {
+  position: absolute;
+  inset: auto 0 0 0;
+  height: 9vh;
+  background: linear-gradient(to top, hsl(0 0% 100% / 0.5), transparent);
+  filter: blur(2px);
+}
+[data-theme='light'] #snow .snow-bank {
+  background: linear-gradient(to top, hsl(0 0% 100% / 0.95), transparent);
+}
+[data-scene='snow'] .card::after {
+  content: '';
+  position: absolute;
+  top: -3px;
+  left: 10px;
+  right: 10px;
+  height: 5px;
+  border-radius: 9999px;
+  background: hsl(0 0% 100% / 0.8);
+  filter: blur(1.5px);
+  pointer-events: none;
+}
+
+/* ---- Christmas scenery (the "christmas" theme) -------------------------- */
+#xmas .xmas-sky {
+  position: absolute;
+  inset: 0;
+  background:
+    radial-gradient(1000px 700px at 50% -12%, hsl(var(--primary) / 0.14), transparent 55%),
+    radial-gradient(900px 600px at 15% 16%, hsl(var(--accent) / 0.16), transparent 60%),
+    hsl(var(--background));
+}
+#xmas .light {
+  position: absolute;
+  top: 10px;
+  width: 9px;
+  height: 9px;
+  border-radius: 50%;
+  animation: twinkleLight 2.2s ease-in-out infinite;
+}
+@keyframes twinkleLight {
+  0%,
+  100% {
+    opacity: 1;
+    box-shadow: 0 0 9px currentColor;
+  }
+  50% {
+    opacity: 0.35;
+    box-shadow: 0 0 3px currentColor;
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  html:not(.force-motion) #snow .flake,
+  html:not(.force-motion) #xmas .flake,
+  html:not(.force-motion) #xmas .light {
+    animation: none !important;
+  }
+}

package/dist/themes/index.d.ts

@@ -1,6 +1,6 @@
 import { Palette, ThemeDefinition } from './palettes';
 export type { Palette, ThemeDefinition } from './palettes';
-export { themes, space, dino, doctor, scientist, soccer, TOKEN_ORDER } from './palettes';
+export { themes, space, dino, doctor, scientist, soccer, snow, christmas, TOKEN_ORDER } from './palettes';
 /**
  * Render a theme to the CSS you'd paste into your own stylesheet: a `:root`
  * block (dark) plus a `:root[data-theme='light']` block. Same output the docs

package/dist/themes/palettes.d.ts

@@ -38,5 +38,7 @@ export declare const dino: ThemeDefinition;
 export declare const doctor: ThemeDefinition;
 export declare const scientist: ThemeDefinition;
 export declare const soccer: ThemeDefinition;
+export declare const snow: ThemeDefinition;
+export declare const christmas: ThemeDefinition;
 /** All built-in themes, in picker order. Space is the default. */
 export declare const themes: ThemeDefinition[];

package/dist/ui/Affix.d.ts

@@ -0,0 +1,21 @@
+import { JSX, ParentProps } from 'solid-js';
+interface AffixProps extends ParentProps {
+    /** Distance in pixels from the top of the viewport to pin at once affixed. Defaults to `0`. */
+    offsetTop?: number;
+    class?: string;
+}
+/**
+ * Sticks its children to the top of the viewport once the user scrolls past the
+ * element's original position. While affixed, the children are rendered in a
+ * `position: fixed` container and a same-size spacer preserves the document flow
+ * so surrounding layout doesn't jump.
+ *
+ * @example
+ * ```tsx
+ * <Affix offsetTop={16}>
+ *   <nav class="rounded-md bg-card px-4 py-2 text-foreground">Sticky toolbar</nav>
+ * </Affix>
+ * ```
+ */
+export declare function Affix(props: AffixProps): JSX.Element;
+export {};

package/dist/ui/Anchor.d.ts

@@ -0,0 +1,28 @@
+import { JSX } from 'solid-js';
+export interface AnchorItem {
+    /** The `id` of the section element this link points to. */
+    id: string;
+    /** Text shown for the link. */
+    label: string;
+}
+export interface AnchorProps {
+    /** Ordered list of sections to build the table of contents from. */
+    items: AnchorItem[];
+    class?: string;
+}
+/**
+ * A vertical table-of-contents nav with scroll-spy. Each item links to a page
+ * section by `id`; the link whose section is topmost in the viewport is marked
+ * active. Clicking a link smooth-scrolls to its section.
+ *
+ * @example
+ * ```tsx
+ * <Anchor
+ *   items={[
+ *     { id: 'intro', label: 'Introduction' },
+ *     { id: 'usage', label: 'Usage' },
+ *   ]}
+ * />
+ * ```
+ */
+export declare function Anchor(props: AnchorProps): JSX.Element;

package/dist/ui/AvatarGroup.d.ts

@@ -0,0 +1,29 @@
+import { JSX } from 'solid-js';
+export interface AvatarGroupProps {
+    avatars: {
+        src?: string;
+        fallback: string;
+        alt?: string;
+    }[];
+    /** Maximum number of avatars to render before collapsing the rest into `+N`. */
+    max?: number;
+    class?: string;
+}
+/**
+ * Renders a row of overlapping {@link Avatar}s. When there are more avatars than
+ * `max` (default 4), the remainder collapse into a trailing `+N` counter.
+ *
+ * @example
+ * ```tsx
+ * <AvatarGroup
+ *   max={3}
+ *   avatars={[
+ *     { src: a.avatarUrl, alt: a.name, fallback: 'AA' },
+ *     { src: b.avatarUrl, alt: b.name, fallback: 'BB' },
+ *     { fallback: 'CC' },
+ *     { fallback: 'DD' },
+ *   ]}
+ * />
+ * ```
+ */
+export declare function AvatarGroup(props: AvatarGroupProps): JSX.Element;

package/dist/ui/BackToTop.d.ts

@@ -0,0 +1,17 @@
+import { JSX } from 'solid-js';
+export interface BackToTopProps {
+    /** Scroll distance (px) after which the button appears. Defaults to `300`. */
+    threshold?: number;
+    class?: string;
+}
+/**
+ * A floating "scroll to top" button, fixed to the bottom-right of the viewport.
+ * It fades in once the user scrolls past `threshold` and smooth-scrolls back up
+ * on click.
+ *
+ * @example
+ * ```tsx
+ * <BackToTop threshold={500} />
+ * ```
+ */
+export declare function BackToTop(props: BackToTopProps): JSX.Element;

package/dist/ui/BottomNavigation.d.ts

@@ -0,0 +1,33 @@
+import { JSX } from 'solid-js';
+/** A single destination within a {@link BottomNavigation}. */
+export interface BottomNavItem {
+    value: string;
+    label: string;
+    icon: JSX.Element;
+}
+export interface BottomNavigationProps {
+    items: BottomNavItem[];
+    value: string;
+    onChange: (value: string) => void;
+    class?: string;
+}
+/**
+ * Horizontal bar of equal-width navigation items, each stacking an icon above
+ * a short label. The active item (matching `value`) is highlighted and marked
+ * with `aria-current="page"`. Renders inline where placed — the consumer is
+ * responsible for positioning (e.g. `fixed inset-x-0 bottom-0`).
+ *
+ * @example
+ * ```tsx
+ * <BottomNavigation
+ *   value={tab()}
+ *   onChange={setTab}
+ *   items={[
+ *     { value: 'home', label: 'Home', icon: <HomeIcon /> },
+ *     { value: 'search', label: 'Search', icon: <SearchIcon /> },
+ *     { value: 'profile', label: 'Profile', icon: <UserIcon /> },
+ *   ]}
+ * />
+ * ```
+ */
+export declare function BottomNavigation(props: BottomNavigationProps): JSX.Element;

package/dist/ui/Calendar.d.ts

@@ -0,0 +1,21 @@
+import { JSX } from 'solid-js';
+export interface CalendarProps {
+    /** Currently selected day. */
+    value?: Date;
+    /** Called with the newly picked day. */
+    onChange?: (date: Date) => void;
+    class?: string;
+}
+/**
+ * Full-month calendar: a header with the month/year and prev/next navigation, a
+ * row of weekday labels, and a 6×7 grid of day buttons. Days outside the shown
+ * month are muted; the selected day is filled and "today" gets a ring. Clicking a
+ * day calls `onChange`. Theme-agnostic (semantic tokens only), always visible.
+ *
+ * @example
+ * ```tsx
+ * const [date, setDate] = createSignal(new Date())
+ * <Calendar value={date()} onChange={setDate} />
+ * ```
+ */
+export declare function Calendar(props: CalendarProps): JSX.Element;

package/dist/ui/Carousel.d.ts

@@ -0,0 +1,23 @@
+import { JSX } from 'solid-js';
+export interface CarouselProps {
+    /** Slides to page through, one visible at a time. */
+    slides: JSX.Element[];
+    /** Auto-advance interval in ms. Omit to disable autoplay (also skipped under reduced motion / hover). */
+    autoplayMs?: number;
+    class?: string;
+}
+/**
+ * Horizontally-sliding carousel that shows one slide at a time inside a rounded,
+ * overflow-hidden viewport. Includes wrapping prev/next arrow buttons, a row of
+ * dot indicators, Left/Right arrow-key navigation when focused, and optional
+ * autoplay that pauses on hover and is disabled under `prefers-reduced-motion`.
+ *
+ * @example
+ * ```tsx
+ * <Carousel
+ *   autoplayMs={4000}
+ *   slides={[<img src="/a.jpg" />, <img src="/b.jpg" />, <img src="/c.jpg" />]}
+ * />
+ * ```
+ */
+export declare function Carousel(props: CarouselProps): JSX.Element;

package/dist/ui/Cascader.d.ts

@@ -0,0 +1,38 @@
+import { JSX } from 'solid-js';
+/** A node in a {@link Cascader} tree. `children` makes it a branch column. */
+export interface CascaderOption {
+    value: string;
+    label: string;
+    children?: CascaderOption[];
+}
+export interface CascaderProps {
+    options: CascaderOption[];
+    /** The currently selected value-path (root → leaf). */
+    value?: string[];
+    /** Fired when a leaf is chosen, with the full value-path and label-path. */
+    onChange: (path: string[], labels: string[]) => void;
+    placeholder?: string;
+    class?: string;
+}
+/**
+ * Cascading multi-level select. Renders a Select-styled trigger showing the
+ * selected path (labels joined with " / "); clicking opens a floating panel of
+ * side-by-side columns. Hovering an option with children reveals the next
+ * column; clicking a leaf commits the selection and closes the panel.
+ *
+ * @example
+ * ```tsx
+ * <Cascader
+ *   options={[
+ *     { value: 'mx', label: 'Mexico', children: [
+ *       { value: 'son', label: 'Sonora' },
+ *       { value: 'jal', label: 'Jalisco' },
+ *     ] },
+ *   ]}
+ *   value={path()}
+ *   onChange={(p, labels) => { setPath(p); console.log(labels.join(' / ')) }}
+ *   placeholder="Select a region"
+ * />
+ * ```
+ */
+export declare function Cascader(props: CascaderProps): JSX.Element;

package/dist/ui/Collapse.d.ts

@@ -0,0 +1,24 @@
+import { JSX, ParentProps } from 'solid-js';
+interface CollapseProps extends ParentProps {
+    /** Whether the panel is currently expanded. */
+    open: boolean;
+    /** Called with the next open state when the header is toggled. */
+    onOpenChange: (open: boolean) => void;
+    /** Text shown in the header button. */
+    title: string;
+    class?: string;
+}
+/**
+ * A single controlled collapsible region: a header button that toggles a panel
+ * of arbitrary children. State is owned by the caller via `open`/`onOpenChange`.
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = createSignal(false)
+ * <Collapse open={open()} onOpenChange={setOpen} title="Details">
+ *   <p>Hidden content revealed on toggle.</p>
+ * </Collapse>
+ * ```
+ */
+export declare function Collapse(props: CollapseProps): JSX.Element;
+export {};

package/dist/ui/Command.d.ts

@@ -0,0 +1,40 @@
+import { JSX } from 'solid-js';
+/** A single selectable row in the palette. */
+export interface CommandItem {
+    /** Primary text shown on the left of the row. */
+    label: string;
+    /** Optional secondary text shown muted on the right. */
+    hint?: string;
+    /** Optional group name; rows sharing a group render under one header. */
+    group?: string;
+    /** Invoked when the row is picked (click or Enter). */
+    onSelect: () => void;
+}
+export interface CommandProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Flat list of commands; filtered live against the search query. */
+    items: CommandItem[];
+    /** Search input placeholder. @default 'Type a command…' */
+    placeholder?: string;
+}
+/**
+ * A ⌘K command palette: a centered, top-anchored dialog with a search input and
+ * a filtered, keyboard-navigable list of commands. Filtering is a
+ * case-insensitive substring match over each item's `label + hint + group`.
+ * Picking a row runs its `onSelect`, closes the palette, and clears the query.
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = createSignal(false)
+ * <Command
+ *   open={open()}
+ *   onOpenChange={setOpen}
+ *   items={[
+ *     { label: 'New file', hint: '⌘N', group: 'File', onSelect: () => createFile() },
+ *     { label: 'Toggle theme', group: 'View', onSelect: () => toggleTheme() },
+ *   ]}
+ * />
+ * ```
+ */
+export declare function Command(props: CommandProps): JSX.Element;

package/dist/ui/Countdown.d.ts

@@ -0,0 +1,19 @@
+import { JSX } from 'solid-js';
+export interface CountdownProps {
+    /** Target moment the countdown runs toward. */
+    to: Date;
+    /** Called once, the moment the countdown reaches zero. */
+    onComplete?: () => void;
+    class?: string;
+}
+/**
+ * Live countdown to `props.to`, shown as four cells (Days / Hours / Mins /
+ * Secs). Updates every second and calls `props.onComplete` once when it hits
+ * zero. Hours, minutes, and seconds are zero-padded to two digits.
+ *
+ * @example
+ * ```tsx
+ * <Countdown to={new Date(Date.now() + 86_400_000)} onComplete={() => launch()} />
+ * ```
+ */
+export declare function Countdown(props: CountdownProps): JSX.Element;

package/dist/ui/DataGrid.d.ts

@@ -0,0 +1,40 @@
+import { JSX } from 'solid-js';
+/** A single column definition for {@link DataGrid}. */
+export interface DataGridColumn {
+    /** Row property this column reads (also used as the sort key). */
+    key: string;
+    /** Column heading text. */
+    header: string;
+    /** When true, the header becomes a button that cycles asc → desc → none. */
+    sortable?: boolean;
+    /** Custom cell renderer; falls back to `String(row[key])` when omitted. */
+    render?: (row: Record<string, unknown>) => JSX.Element;
+}
+/** Props for {@link DataGrid}. */
+export interface DataGridProps {
+    columns: DataGridColumn[];
+    rows: Record<string, unknown>[];
+    /** Rows per page. Defaults to 10. */
+    pageSize?: number;
+    /** Show the global text filter above the table. Defaults to true. */
+    filterable?: boolean;
+    class?: string;
+}
+/**
+ * Sortable + filterable table. Provide `columns` and `rows`; the grid handles
+ * global text filtering, per-column sorting (click a sortable header to cycle
+ * ascending → descending → unsorted), and pagination on its own.
+ *
+ * @example
+ * ```tsx
+ * <DataGrid
+ *   columns={[
+ *     { key: 'name', header: 'Name', sortable: true },
+ *     { key: 'age', header: 'Age', sortable: true },
+ *   ]}
+ *   rows={[{ name: 'Alfredo', age: 30 }, { name: 'Sonora', age: 12 }]}
+ *   pageSize={25}
+ * />
+ * ```
+ */
+export declare function DataGrid(props: DataGridProps): JSX.Element;

package/dist/ui/Descriptions.d.ts

@@ -0,0 +1,28 @@
+import { JSX } from 'solid-js';
+/** A single label/value row in a {@link Descriptions} list. */
+export interface DescriptionItem {
+    label: string;
+    value: JSX.Element;
+}
+export interface DescriptionsProps {
+    items: DescriptionItem[];
+    /** Number of columns on `sm`+ screens (1, 2, or 3). Default: 1. */
+    columns?: number;
+    class?: string;
+}
+/**
+ * Renders a set of label/value pairs as a semantic `<dl>` in a responsive grid.
+ * Use `columns` to fan the pairs out into 2 or 3 columns on wider screens.
+ *
+ * @example
+ * ```tsx
+ * <Descriptions
+ *   columns={2}
+ *   items={[
+ *     { label: 'Status', value: <Badge tone="success">Active</Badge> },
+ *     { label: 'Owner', value: 'Ada Lovelace' },
+ *   ]}
+ * />
+ * ```
+ */
+export declare function Descriptions(props: DescriptionsProps): JSX.Element;

package/dist/ui/Empty.d.ts

@@ -0,0 +1,27 @@
+import { JSX } from 'solid-js';
+export interface EmptyProps {
+    /** Bold headline describing the empty state. */
+    title: string;
+    /** Optional supporting line under the title. */
+    description?: string;
+    /** Optional custom icon; falls back to a lucide-solid `Inbox`. */
+    icon?: JSX.Element;
+    /** Optional action slot (e.g. a Button) rendered below the text. */
+    action?: JSX.Element;
+    class?: string;
+}
+/**
+ * Empty-state placeholder — a centered icon, title, optional description, and an
+ * optional action slot — for lists, search results, or first-run views that have
+ * nothing to show yet. Falls back to an `Inbox` icon when none is provided.
+ *
+ * @example
+ * ```tsx
+ * <Empty
+ *   title="No projects yet"
+ *   description="Create your first project to get started."
+ *   action={<Button>New project</Button>}
+ * />
+ * ```
+ */
+export declare function Empty(props: EmptyProps): JSX.Element;

package/dist/ui/FloatingActionButton.d.ts

@@ -0,0 +1,22 @@
+import { JSX } from 'solid-js';
+/** Screen corner a {@link FloatingActionButton} anchors to. Defaults to `'bottom-right'`. */
+export type FloatingActionButtonPosition = 'bottom-right' | 'bottom-left';
+export interface FloatingActionButtonProps {
+    /** Icon rendered centered inside the button. */
+    icon: JSX.Element;
+    /** Accessible label; surfaced via `aria-label`. */
+    label: string;
+    onClick?: () => void;
+    /** Screen corner to anchor to. Defaults to `'bottom-right'`. */
+    position?: FloatingActionButtonPosition;
+    class?: string;
+}
+/**
+ * A fixed circular primary action button pinned to a screen corner.
+ *
+ * @example
+ * ```tsx
+ * <FloatingActionButton icon={<PlusIcon />} label="New item" onClick={() => create()} />
+ * ```
+ */
+export declare function FloatingActionButton(props: FloatingActionButtonProps): JSX.Element;

package/dist/ui/Highlight.d.ts

@@ -0,0 +1,18 @@
+import { JSX } from 'solid-js';
+export interface HighlightProps {
+    /** Full text to render. */
+    text: string;
+    /** Substring to highlight; every case-insensitive occurrence is marked. */
+    query: string;
+    class?: string;
+}
+/**
+ * Highlights every case-insensitive occurrence of `query` within `text`.
+ * When `query` is empty the text renders unchanged.
+ *
+ * @example
+ * ```tsx
+ * <Highlight text="Sonora Precision" query="prec" />
+ * ```
+ */
+export declare function Highlight(props: HighlightProps): JSX.Element;

package/dist/ui/Image.d.ts

@@ -0,0 +1,20 @@
+import { JSX } from 'solid-js';
+export interface ImageProps {
+    src: string;
+    alt: string;
+    class?: string;
+    /** When true, clicking the image opens a zoomable lightbox. @default true */
+    preview?: boolean;
+}
+/**
+ * Lazy-loaded content image. Unless `preview` is disabled, the thumbnail is a
+ * zoom-in button that opens a centered lightbox (dimmed overlay + close button)
+ * on Kobalte's `Dialog` primitive.
+ *
+ * @example
+ * ```tsx
+ * <Image src="/photo.jpg" alt="A scenic view" />
+ * <Image src="/logo.svg" alt="Logo" preview={false} />
+ * ```
+ */
+export declare function Image(props: ImageProps): JSX.Element;

package/dist/ui/Kbd.d.ts

@@ -0,0 +1,14 @@
+import { JSX, ParentProps } from 'solid-js';
+interface KbdProps extends ParentProps {
+    class?: string;
+}
+/**
+ * Keycap-styled indicator for a keyboard key or shortcut token.
+ *
+ * @example
+ * ```tsx
+ * <Kbd>⌘</Kbd><Kbd>K</Kbd>
+ * ```
+ */
+export declare function Kbd(props: KbdProps): JSX.Element;
+export {};

package/dist/ui/List.d.ts

@@ -0,0 +1,36 @@
+import { JSX } from 'solid-js';
+/** A single row in a {@link List}. */
+export interface ListItem {
+    title: string;
+    description?: string;
+    avatar?: JSX.Element;
+    meta?: JSX.Element;
+    actions?: JSX.Element;
+}
+interface ListProps {
+    items: ListItem[];
+    class?: string;
+}
+export type { ListProps };
+/**
+ * Vertical list of rows inside a rounded, bordered container with divider
+ * lines between items. Each item shows an optional leading `avatar`, a
+ * `title` with optional `description`, and an optional trailing `meta` /
+ * `actions` slot.
+ *
+ * @example
+ * ```tsx
+ * <List
+ *   items={[
+ *     {
+ *       title: 'Alfredo Rivera',
+ *       description: 'Owner',
+ *       avatar: <Avatar name="Alfredo" />,
+ *       meta: <span>2h ago</span>,
+ *       actions: <Button size="sm">Edit</Button>,
+ *     },
+ *   ]}
+ * />
+ * ```
+ */
+export declare function List(props: ListProps): JSX.Element;