@a4ui/core 0.5.0 → 0.7.0

package/dist/ui/CalendarHeatmap.d.ts

@@ -0,0 +1,26 @@
+import { JSX } from 'solid-js';
+/** A single day's activity count, keyed by an ISO `YYYY-MM-DD` date. */
+export interface HeatmapValue {
+    date: string;
+    count: number;
+}
+export interface CalendarHeatmapProps {
+    /** Activity counts to plot; dates outside the visible range are ignored. */
+    values: HeatmapValue[];
+    /** Number of week-columns to show, ending on today. Default 26. */
+    weeks?: number;
+    class?: string;
+}
+/**
+ * GitHub-contributions-style heatmap: a grid of the last `weeks` weeks ending
+ * today, laid out as columns (one per week) of 7 vertically-stacked day-cells
+ * (Sun→Sat). Each cell is shaded by its count into 5 intensity levels and shows
+ * a native tooltip like "3 on 2026-07-10". A "Less … More" legend sits below.
+ * Theme-agnostic (semantic tokens only).
+ *
+ * @example
+ * ```tsx
+ * <CalendarHeatmap values={[{ date: '2026-07-10', count: 3 }]} weeks={26} />
+ * ```
+ */
+export declare function CalendarHeatmap(props: CalendarHeatmapProps): 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/ColorPicker.d.ts

@@ -0,0 +1,22 @@
+import { JSX } from 'solid-js';
+export interface ColorPickerProps {
+    /** Current color as a `#rrggbb` hex string. */
+    value: string;
+    /** Called with a valid `#rrggbb` hex whenever the user picks a new color. */
+    onChange: (hex: string) => void;
+    /** Preset colors shown as clickable swatches. Defaults to a small palette. */
+    swatches?: string[];
+    class?: string;
+}
+/**
+ * Controlled color picker: a native color well, a hex text field, and a row of
+ * preset swatches. The text field validates against `#rrggbb` and only reports
+ * complete, valid hex values while letting you type freely in between.
+ *
+ * @example
+ * ```tsx
+ * const [color, setColor] = createSignal('#3b82f6')
+ * <ColorPicker value={color()} onChange={setColor} />
+ * ```
+ */
+export declare function ColorPicker(props: ColorPickerProps): JSX.Element;

package/dist/ui/Comment.d.ts

@@ -0,0 +1,42 @@
+import { JSX } from 'solid-js';
+/** A single comment node, optionally carrying its own nested `replies`. */
+export interface CommentData {
+    /** Unique identifier for the comment. */
+    id: string;
+    /** Display name of the comment's author. */
+    author: string;
+    /** Author avatar image URL; falls back to the author's initials. */
+    avatar?: string;
+    /** Human-readable timestamp shown next to the author. */
+    time?: string;
+    /** The comment body. */
+    content: JSX.Element;
+    /** Nested replies, rendered recursively below the comment. */
+    replies?: CommentData[];
+}
+export interface CommentProps {
+    comment: CommentData;
+    /** Renders an actions row (e.g. reply/like) for a given comment. */
+    actions?: (comment: CommentData) => JSX.Element;
+    class?: string;
+}
+/**
+ * Threaded comment layout: a left-aligned {@link Avatar} beside the author,
+ * timestamp, content, and an optional actions row. Any `replies` are rendered
+ * recursively in a left-indented, bordered thread, inheriting the same `actions`.
+ *
+ * @example
+ * ```tsx
+ * <Comment
+ *   comment={{
+ *     id: '1',
+ *     author: 'Jane Doe',
+ *     time: '2h ago',
+ *     content: <p>Great work on this!</p>,
+ *     replies: [{ id: '2', author: 'John Smith', content: <p>Agreed.</p> }],
+ *   }}
+ *   actions={(c) => <button>Reply to {c.author}</button>}
+ * />
+ * ```
+ */
+export declare function Comment(props: CommentProps): 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/Mentions.d.ts

@@ -0,0 +1,37 @@
+import { JSX } from 'solid-js';
+export interface MentionOption {
+    value: string;
+    label: string;
+}
+export interface MentionsProps {
+    value: string;
+    /** Called with the new string value on every input (not the raw DOM event). */
+    onChange: (value: string) => void;
+    /** Options offered while typing an `@mention`. */
+    options: MentionOption[];
+    placeholder?: string;
+    class?: string;
+}
+/**
+ * Controlled multi-line text field that shows an autocomplete dropdown while
+ * the user types an `@mention`. On each input, the text before the caret is
+ * checked for a trailing `@query`; matching {@link MentionOption}s (by `label`
+ * or `value`, case-insensitive) are offered in a panel. Selecting one replaces
+ * the `@query` with `@{label} `. Arrow keys move the highlight, Enter accepts,
+ * Escape dismisses.
+ *
+ * @example
+ * ```tsx
+ * const [body, setBody] = createSignal('')
+ * <Mentions
+ *   value={body()}
+ *   onChange={setBody}
+ *   options={[
+ *     { value: 'ada', label: 'Ada Lovelace' },
+ *     { value: 'alan', label: 'Alan Turing' },
+ *   ]}
+ *   placeholder="Write a note, use @ to mention someone"
+ * />
+ * ```
+ */
+export declare function Mentions(props: MentionsProps): JSX.Element;

package/dist/ui/NotificationCenter.d.ts

@@ -0,0 +1,32 @@
+import { JSX } from 'solid-js';
+/** A single entry rendered by {@link NotificationCenter}. */
+export interface NotificationItem {
+    id: string;
+    title: string;
+    description?: string;
+    time?: string;
+    read?: boolean;
+}
+export interface NotificationCenterProps {
+    /** Notifications to display, newest first. */
+    items: NotificationItem[];
+    /** Called with an item's id when its dismiss button is clicked. */
+    onDismiss?: (id: string) => void;
+    /** Called when the "Mark all read" action is clicked. */
+    onMarkAllRead?: () => void;
+    class?: string;
+}
+/**
+ * Bell button that opens a popover listing notifications, with an unread count
+ * badge, per-item dismiss, and a "mark all read" action. Built on {@link Popover}.
+ *
+ * @example
+ * ```tsx
+ * <NotificationCenter
+ *   items={items}
+ *   onDismiss={(id) => remove(id)}
+ *   onMarkAllRead={() => markAll()}
+ * />
+ * ```
+ */
+export declare function NotificationCenter(props: NotificationCenterProps): JSX.Element;

package/dist/ui/Portal.d.ts

@@ -0,0 +1,22 @@
+import { JSX } from 'solid-js';
+/** Props for {@link Portal}. */
+export interface PortalProps {
+    /** Where to mount. Defaults to `document.body`. */
+    mount?: Node;
+    /** Use a Shadow DOM root for the portal container. */
+    useShadow?: boolean;
+    children: JSX.Element;
+}
+/**
+ * Renders its children into a different place in the DOM (by default
+ * `document.body`), so overlays aren't clipped by an ancestor's `overflow` or
+ * transformed stacking context. Built on Solid's `Portal`.
+ *
+ * @example
+ * ```tsx
+ * <Portal>
+ *   <div class="fixed inset-0 grid place-items-center">Floating layer</div>
+ * </Portal>
+ * ```
+ */
+export declare function Portal(props: PortalProps): JSX.Element;

package/dist/ui/Tour.d.ts

@@ -0,0 +1,35 @@
+import { JSX } from 'solid-js';
+/** A single stop in a {@link Tour}. */
+export interface TourStep {
+    /** CSS selector for the element to highlight. */
+    target: string;
+    title: string;
+    description?: string;
+}
+export interface TourProps {
+    steps: TourStep[];
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Called after the last step's "Done" (in addition to `onOpenChange(false)`). */
+    onFinish?: () => void;
+}
+/**
+ * Guided coachmark tour: walks the user through a sequence of on-page targets,
+ * spotlighting each one and explaining it in a floating tooltip. Theme-agnostic —
+ * the dimmer uses `--background` so it adapts to light/dark automatically.
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = createSignal(false)
+ * <Tour
+ *   open={open()}
+ *   onOpenChange={setOpen}
+ *   onFinish={() => markTourSeen()}
+ *   steps={[
+ *     { target: '#new-btn', title: 'Create', description: 'Start a new record here.' },
+ *     { target: '#search', title: 'Search', description: 'Find anything fast.' },
+ *   ]}
+ * />
+ * ```
+ */
+export declare function Tour(props: TourProps): JSX.Element;

package/dist/ui/TreeSelect.d.ts

@@ -0,0 +1,40 @@
+import { JSX } from 'solid-js';
+import { TreeNode } from './Tree';
+export interface TreeSelectProps {
+    /** Hierarchical options; the same shape consumed by {@link Tree}. */
+    nodes: TreeNode[];
+    /** Id of the currently selected leaf node. */
+    value?: string;
+    /** Fired when a leaf is picked, with its id and the node itself. */
+    onChange: (value: string, node: TreeNode) => void;
+    /** Text shown when no value is selected. */
+    placeholder?: string;
+    class?: string;
+}
+/**
+ * A dropdown that pairs a {@link Select}-styled trigger with a {@link Tree} in a
+ * popover panel. Clicking a branch toggles its subtree; clicking a leaf calls
+ * `onChange` and closes the panel. The trigger shows the selected leaf's label
+ * (found by walking `nodes`) or a muted `placeholder`. Closes on outside click.
+ *
+ * @example
+ * ```tsx
+ * const [dept, setDept] = createSignal<string>()
+ * <TreeSelect
+ *   placeholder="Pick a team"
+ *   value={dept()}
+ *   onChange={(id) => setDept(id)}
+ *   nodes={[
+ *     {
+ *       id: 'eng',
+ *       label: 'Engineering',
+ *       children: [
+ *         { id: 'fe', label: 'Frontend' },
+ *         { id: 'be', label: 'Backend' },
+ *       ],
+ *     },
+ *   ]}
+ * />
+ * ```
+ */
+export declare function TreeSelect(props: TreeSelectProps): JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a4ui/core",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "A4ui — Spatial Glass design system & component library for SolidJS (Kobalte behavior + Tailwind glass tokens + motion).",
   "type": "module",
   "license": "MIT",