@llmnative/react 0.1.1 → 1.1.0

package/dist/types/src/components/blocks/Brand.d.ts

@@ -1,14 +1,19 @@
 import React from 'react';
 type BrandProps = {
+    /** Link target URL for the brand. */
     url?: string;
+    /** Brand text label. */
     label?: string;
+    /** Logo image URL. */
     logo?: string;
+    /** Logo image width. */
     width?: number;
+    /** Logo image height. Defaults to `36`. */
     height?: number;
-    wrapClass?: string;
+    wrapperClassName?: string;
     className?: string;
-    logoClass?: string;
-    labelClass?: string;
+    logoClassName?: string;
+    labelClassName?: string;
 };
-declare const Brand: ({ url, label, logo, width, height, wrapClass, className, logoClass, labelClass }: BrandProps) => React.JSX.Element;
+declare const Brand: ({ url, label, logo, width, height, wrapperClassName, className, logoClassName, labelClassName }: BrandProps) => React.JSX.Element;
 export default Brand;

package/dist/types/src/components/blocks/Breadcrumbs.d.ts

@@ -1,8 +1,54 @@
 import React from 'react';
-type BreadcrumbsProps = {
-    path?: string;
-    pre?: React.ReactNode;
+/**
+ * A single breadcrumb item.
+ * - Provide `href` to render as a clickable link.
+ * - Omit `href` on the last item to mark it as the current page (not a link).
+ */
+export type BreadcrumbItem = {
+    label: string;
+    href?: string;
+    node?: React.ReactNode;
+};
+export type BreadcrumbsProps = {
+    /**
+     * The breadcrumb trail to render.
+     * - Pass a URL string to auto-parse into segments (e.g. "/products/shoes") - falls back to the current route when omitted.
+     * - Pass a BreadcrumbItem[] for explicit control over labels and links.
+     */
+    trail?: string | BreadcrumbItem[];
+    /**
+     * Optional anchor item rendered before the trail (e.g. the site root).
+     * Pass a string for a plain label (e.g. "Home") or a BreadcrumbItem to also add a link (e.g. { label: "Home", href: "/" }).
+     */
+    rootItem?: string | BreadcrumbItem;
+    /** Character or icon rendered between items. Use "chevron" for an SVG arrow. Default: "/" */
+    separator?: '/' | '>' | 'chevron' | string;
+    /** When true, renders a <script type="application/ld+json"> BreadcrumbList schema.org tag. Default: false */
+    jsonLd?: boolean;
+    /** Base URL prepended to item hrefs in the JSON-LD output only (e.g. "https://example.com"). Does not affect the visual links. Defaults to window.location.origin. */
+    baseUrl?: string;
     className?: string;
 };
-export declare const Breadcrumbs: ({ path, pre, className }: BreadcrumbsProps) => React.JSX.Element;
+/** Options for buildBreadcrumbSchema. */
+export type BreadcrumbSchemaOptions = {
+    /** The breadcrumb item list. Items with `href` get an absolute URL in the schema; items without `href` (current page) do not. */
+    items: BreadcrumbItem[];
+    /** Optional anchor item prepended before the list (same shape as BreadcrumbItem - e.g. { label: "Home", href: "/" }). */
+    rootItem?: BreadcrumbItem;
+    /** Base URL prepended to all hrefs to produce the absolute URLs required by schema.org (e.g. "https://example.com"). */
+    baseUrl: string;
+    /** When true, returns a JSON string ready for `dangerouslySetInnerHTML` - no manual JSON.stringify needed. Default: false */
+    stringify?: boolean;
+};
+/**
+ * Builds a schema.org BreadcrumbList.
+ * Returns a plain object by default, or a ready-to-inject JSON string when `stringify: true`.
+ */
+export declare function buildBreadcrumbSchema(options: BreadcrumbSchemaOptions & {
+    stringify: true;
+}): string;
+export declare function buildBreadcrumbSchema(options: BreadcrumbSchemaOptions & {
+    stringify?: false;
+}): object;
+export declare const Breadcrumbs: ({ trail, rootItem, separator, jsonLd, baseUrl, className, }: BreadcrumbsProps) => React.JSX.Element | null;
 export default Breadcrumbs;

package/dist/types/src/components/blocks/Carousel.d.ts

@@ -9,11 +9,13 @@ type CarouselProps = {
     showIndicators?: boolean;
     showControls?: boolean;
     showCaption?: boolean;
-    layoutDark?: boolean;
+    /** Use dark variant indicators/controls. */
+    dark?: boolean;
     autoPlay?: AutoPlayOptions;
-    startSlide?: number;
-    onParseCaption?: (image: React.ReactElement) => React.ReactElement;
-    onClick?: (event: React.MouseEvent<HTMLDivElement, MouseEvent>) => void;
+    /** 0-based index of the initially visible slide. */
+    initialSlide?: number;
+    renderCaption?: (image: React.ReactElement) => React.ReactElement;
+    onSlideClick?: (event: React.MouseEvent<HTMLDivElement, MouseEvent>) => void;
 };
-declare const Carousel: ({ children, showIndicators, showControls, showCaption, layoutDark, autoPlay, startSlide, onParseCaption, onClick, }: CarouselProps) => React.JSX.Element;
+declare const Carousel: ({ children, showIndicators, showControls, showCaption, dark, autoPlay, initialSlide, renderCaption, onSlideClick, }: CarouselProps) => React.JSX.Element | null;
 export default Carousel;

package/dist/types/src/components/blocks/Dropdown.d.ts

@@ -1,44 +1,59 @@
 import React from 'react';
-import { BadgeProps } from "../ui/Badge";
+import { BadgeProps, BadgeType } from "../ui/Badge";
 import type { MotionUIProps } from '../types';
+/** Shorthand config for the dropdown trigger when it renders as a button + icon. */
 interface DropdownTogglerProps {
     icon?: string;
     text?: string;
+    title?: string;
 }
-interface DropdownProps extends Pick<MotionUIProps, 'motion'> {
+interface DropdownProps extends MotionUIProps {
     children: React.ReactNode;
-    toggleButton?: string | React.ReactNode | DropdownTogglerProps;
+    /** Dropdown trigger: string (label), React element, or `DropdownTogglerProps` object. */
+    trigger?: string | React.ReactNode | DropdownTogglerProps;
     badge?: BadgeProps;
+    /** Fixed header rendered inside the dropdown menu. */
     header?: React.ReactNode;
     footer?: React.ReactNode;
+    /** Uncontrolled open state default. */
     defaultOpen?: boolean;
+    /** Controlled open state. */
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
-    alwaysOpen?: boolean;
+    /** When `true`, the menu stays open regardless of interaction. */
+    staticOpen?: boolean;
+    /** Horizontal alignment relative to the trigger. */
     position?: "start" | "end";
-    wrapClass?: string;
-    className?: string;
-    buttonClass?: string;
-    badgeClass?: string;
-    menuClass?: string;
-    headerClass?: string;
-    footerClass?: string;
+    /** Drop direction. */
+    placement?: "auto" | "top" | "bottom";
+    /** CSS positioning strategy. */
+    strategy?: "fixed" | "absolute";
+    triggerClassName?: string;
+    badgeClassName?: string;
+    menuClassName?: string;
+    headerClassName?: string;
+    footerClassName?: string;
 }
 interface DropdownButtonProps extends Pick<MotionUIProps, 'motion'> {
     children: React.ReactNode;
     badge?: BadgeProps;
+    /** `"static"` — always visible; `"dynamic"` — shows/hides with the menu. */
     display?: "static" | "dynamic";
     className?: string;
-    badgeClass?: string;
+    badgeClassName?: string;
+    title?: string;
     onToggle?: () => void;
     open?: boolean;
     menuId?: string;
+    buttonRef?: React.RefObject<HTMLButtonElement>;
 }
 interface DropdownItemProps {
+    /** Link URL. When set, renders as `<a>`, otherwise as `<button>`. */
     url?: string;
     onClick?: React.MouseEventHandler<HTMLAnchorElement | HTMLButtonElement>;
     className?: string;
     children: React.ReactNode;
+    /** Leading icon name. */
     icon?: string;
 }
 interface DropdownHeaderProps {
@@ -48,17 +63,20 @@ interface DropdownHeaderProps {
 interface DropdownDividerProps {
     className?: string;
 }
-export declare const Dropdown: ({ children, toggleButton, badge, header, footer, defaultOpen, open: controlledOpen, onOpenChange, alwaysOpen, position, wrapClass, className, buttonClass, menuClass, badgeClass, headerClass, footerClass, motion: motionConfig, }: DropdownProps) => React.JSX.Element;
-export declare const DropdownButton: ({ children, badge, display, className, badgeClass, motion: motionConfig, onToggle, open, menuId }: DropdownButtonProps) => React.JSX.Element;
+export declare const Dropdown: ({ children, trigger, badge, header, footer, defaultOpen, open: controlledOpen, onOpenChange, staticOpen, position, placement, strategy, wrapperClassName, className, before, after, triggerClassName, menuClassName, badgeClassName, headerClassName, footerClassName, motion: motionConfig, }: DropdownProps) => React.JSX.Element;
+export declare const DropdownButton: ({ children, badge, display, className, badgeClassName, motion: motionConfig, title, onToggle, open, menuId, buttonRef }: DropdownButtonProps) => React.JSX.Element;
 export declare const DropdownItem: ({ children, url, onClick, icon, className }: DropdownItemProps) => React.JSX.Element;
 export declare const DropdownHeader: ({ children, className }: DropdownHeaderProps) => React.JSX.Element;
 export declare const DropdownDivider: ({ className }: DropdownDividerProps) => React.JSX.Element;
 interface DropdownMenuProps {
-    context: string;
-    Type?: 'ul' | 'ol';
-    badges?: Record<string, any>;
-    pre?: React.ReactNode;
-    post?: React.ReactNode;
+    menuKey: string;
+    as?: 'ul' | 'ol';
+    badges?: Record<string, {
+        type?: BadgeType;
+        children: string;
+    }>;
+    before?: React.ReactNode;
+    after?: React.ReactNode;
 }
-export declare const DropdownMenu: ({ context, Type, badges, pre, post }: DropdownMenuProps) => React.JSX.Element;
+export declare const DropdownMenu: ({ menuKey, as, badges, before, after }: DropdownMenuProps) => React.JSX.Element;
 export {};

package/dist/types/src/components/blocks/ListCard.d.ts

@@ -0,0 +1,38 @@
+import React from 'react';
+import type { MotionUIProps } from '../types';
+export interface ListCardProps extends MotionUIProps {
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    /** Metadata displayed below the description. */
+    meta?: React.ReactNode;
+    badge?: React.ReactNode;
+    /** Leading icon or custom element. */
+    icon?: string | React.ReactNode;
+    /** Element displayed on the trailing edge. */
+    trailing?: React.ReactNode;
+    footer?: React.ReactNode;
+    children?: React.ReactNode;
+    /** Navigate to this URL on click. */
+    href?: string;
+    /** Open link in a new tab. */
+    external?: boolean;
+    active?: boolean;
+    disabled?: boolean;
+    /** Show a dashed border style. */
+    dashed?: boolean;
+    /** Compact layout with less padding. */
+    compact?: boolean;
+    align?: 'start' | 'center';
+    style?: React.CSSProperties;
+    onClick?: (e: React.MouseEvent<HTMLElement>) => void;
+    titleClassName?: string;
+    descriptionClassName?: string;
+    metaClassName?: string;
+    badgeClassName?: string;
+    leadingClassName?: string;
+    bodyClassName?: string;
+    headerClassName?: string;
+    trailingClassName?: string;
+    footerClassName?: string;
+}
+export default function ListCard({ title, description, meta, badge, icon, trailing, footer, children, href, external, active, disabled, dashed, compact, align, onClick, before, after, wrapperClassName, className, titleClassName, descriptionClassName, metaClassName, badgeClassName, leadingClassName, bodyClassName, headerClassName, trailingClassName, footerClassName, style, motion: motionConfig, }: ListCardProps): React.JSX.Element;

package/dist/types/src/components/blocks/Menu.d.ts

@@ -1,24 +1,23 @@
 import React from 'react';
 import { BadgeType } from '../ui/Badge';
-interface MenuProps {
-    context: string;
-    Type?: 'ul' | 'ol';
+import type { UIProps } from '../types';
+interface MenuProps extends UIProps {
+    /** Registry key used to look up menu items from `useMenu()`. */
+    menuKey: string;
+    as?: 'ul' | 'ol';
+    /** Badge overrides keyed by menu item ID. */
     badges?: Record<string, {
         type?: BadgeType;
         children: string;
     }>;
-    pre?: React.ReactNode;
-    post?: React.ReactNode;
-    wrapClass?: string;
-    className?: string;
-    headerClass?: string;
-    itemClass?: string;
-    linkClass?: string;
-    iconClass?: string;
-    textClass?: string;
-    badgeClass?: string;
-    arrowClass?: string;
-    submenuClass?: string;
+    headerClassName?: string;
+    itemClassName?: string;
+    linkClassName?: string;
+    iconClassName?: string;
+    textClassName?: string;
+    badgeClassName?: string;
+    arrowClassName?: string;
+    submenuClassName?: string;
 }
-declare const Menu: ({ context, Type, badges, pre, post, wrapClass, className, headerClass, itemClass, linkClass, iconClass, textClass, badgeClass, arrowClass, submenuClass, }: MenuProps) => React.JSX.Element;
+declare const Menu: ({ menuKey, as, badges, before, after, wrapperClassName, className, headerClassName, itemClassName, linkClassName, iconClassName, textClassName, badgeClassName, arrowClassName, submenuClassName, }: MenuProps) => React.JSX.Element;
 export default Menu;

package/dist/types/src/components/blocks/Notifications.d.ts

@@ -1,15 +1,23 @@
 import React from "react";
 import type { BadgeProps } from "../ui/Badge";
+import type { MotionReference } from "../../motion";
 interface NotificationItem {
     title: string;
     url: string;
     time: string;
     icon: string;
+    read?: boolean;
 }
 interface NotificationsProps {
-    children?: NotificationItem[];
+    items?: NotificationItem[];
     badge?: BadgeProps;
-    wrapClass?: string;
+    /** URL to a full notifications page — shown in the footer only when there are items */
+    seeAllUrl?: string;
+    /** Callback for "mark all as read" — shown in the header only when there are items */
+    onMarkAllRead?: () => void;
+    /** Named motion preset for notification items appearance. */
+    motion?: MotionReference;
+    className?: string;
 }
-declare function Notifications({ children, badge, wrapClass }: NotificationsProps): React.JSX.Element;
+declare function Notifications({ items, badge, seeAllUrl, onMarkAllRead, motion, className, }: NotificationsProps): React.JSX.Element;
 export default Notifications;

package/dist/types/src/components/blocks/ProviderSwitcher.d.ts

@@ -0,0 +1,65 @@
+import React from 'react';
+import type { UIProps } from '../types';
+import type { ProviderSessionResponse } from '../../providers/ProviderSession';
+export interface ProviderSwitcherItem {
+    id: string;
+    label: string;
+    /** Rendered on the trailing side of the row, e.g. a role or a status. */
+    meta?: React.ReactNode;
+    /** Icon name (resolved via the icon provider) or a ready-made node. Falls back to the switcher's own `icon`. */
+    icon?: string | React.ReactNode;
+}
+export interface ProviderSwitcherProps extends UIProps {
+    items: ProviderSwitcherItem[];
+    /** True while `items` itself is still being fetched — distinct from the switch-in-progress state. Shows a spinner in the trigger and disables opening the list, instead of rendering as if there were genuinely zero items. */
+    itemsLoading?: boolean;
+    activeId?: string | null;
+    /** Fires once the switch has actually succeeded — never optimistically on click. */
+    onSelect?: (id: string) => void;
+    /** Fires when the endpoint call or the provider switch itself throws. */
+    onError?: (id: string, error: unknown) => void;
+    /** Inspect or transform the raw session response before it's applied — e.g. inject an extra category, filter one out, forward it to an audit log. */
+    onResponse?: (response: ProviderSessionResponse) => ProviderSessionResponse | Promise<ProviderSessionResponse>;
+    /**
+     * URL of the session endpoint (POSTed with `requestBody(id)` on selection), or a
+     * resolver called directly with the picked id — e.g. a mock/dev session provider,
+     * or a Firebase Callable Function invocation. No fetch happens in the resolver case.
+     */
+    endpoint: string | ((id: string) => Promise<ProviderSessionResponse>);
+    /**
+     * Overrides the credential sent with the request. By default, ProviderSwitcher calls
+     * getAccessToken() on the app's own registered auth provider — the identity the user
+     * already negotiated at login — so most apps never need to set this. A function is
+     * called fresh on every switch, which matters because tokens expire/rotate.
+     */
+    authorization?: string | (() => string | Promise<string>);
+    /** Builds the POST body for a string `endpoint`. Defaults to `{ id }`. */
+    requestBody?: (id: string) => unknown;
+    /** HTTP method for a string `endpoint`. Default: 'POST'. */
+    method?: string;
+    /** Leading icon shown in the trigger and as the default per-item icon. Name resolved via the icon provider, or a ready-made node. */
+    icon?: string | React.ReactNode;
+    /** Small caption under the active item's label in the trigger (e.g. "Workspace"). Also used as the list header unless `listLabel` is set. */
+    caption?: React.ReactNode;
+    /** Header shown above the item list. Defaults to `caption`. */
+    listLabel?: React.ReactNode;
+    /** Shown in the trigger when `activeId` matches nothing in `items`. Defaults to the framework's generic "Select..." string. */
+    placeholder?: React.ReactNode;
+    disabled?: boolean;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Rendered below the item list, inside the dropdown — e.g. a "manage" action. Omit for a plain list. */
+    footer?: React.ReactNode;
+    triggerClassName?: string;
+    listClassName?: string;
+    itemClassName?: string;
+}
+/**
+ * Generic named-item switcher — no domain vocabulary (tenant, workspace, session, ...).
+ * Given `items` and one `endpoint`, it performs the whole switch itself on selection:
+ * resolves a credential (the app's own auth provider by default), calls the endpoint
+ * for the picked id, and applies the response via useProviderSession().switchSession().
+ * The caller only finds out once it's actually done (`onSelect`) or failed (`onError`) —
+ * it never has to wire the request/loading/error plumbing itself.
+ */
+export default function ProviderSwitcher({ items, itemsLoading, activeId, onSelect, onError, onResponse, endpoint, authorization, requestBody, method, icon, caption, listLabel, placeholder, disabled, open, onOpenChange, footer, before, after, wrapperClassName, className, triggerClassName, listClassName, itemClassName, }: ProviderSwitcherProps): React.JSX.Element;

package/dist/types/src/components/blocks/Search.d.ts

@@ -1,7 +1,8 @@
 import React from 'react';
 interface SearchProps {
-    handleSearch?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    /** Called on every keystroke with the current search input event. */
+    onQueryChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
 }
 export declare const SearchButton: () => React.JSX.Element;
-declare function Search({ handleSearch }: SearchProps): React.JSX.Element;
+declare function Search({ onQueryChange }: SearchProps): React.JSX.Element;
 export default Search;

package/dist/types/src/components/blocks/SideNav.d.ts

@@ -0,0 +1,45 @@
+/**
+ * SideNav — collapsible sidebar block.
+ *
+ * Accepts either `menuKey` (reads from App menuConfig via useMenu) or explicit `items`.
+ * Features: collapse to icon-only, hover-expand overlay, groups, active state, animated sub-menu, badges.
+ *
+ * Active state is computed manually via useLocation (not NavLink.isActive) to avoid
+ * React Router quirks with the "/" root path and the `end` flag.
+ */
+import React from 'react';
+export interface SideNavItemDef {
+    path: string;
+    title?: string;
+    icon?: string;
+    group?: string;
+    /** Match exact path only (needed for "/" to avoid matching everything). Default: false. */
+    end?: boolean;
+    /** Badge label shown next to the item title. Collapsed: dot indicator. */
+    badge?: string | number;
+    children?: SideNavItemDef[];
+}
+export interface SideNavProps {
+    /** Menu key registered in App menuConfig — calls useMenu() internally */
+    menuKey?: string;
+    /** Explicit items — alternative to menuKey */
+    items?: SideNavItemDef[];
+    defaultCollapsed?: boolean;
+    /** Show icon slot. Default true. */
+    showIcons?: boolean;
+    /** Show collapse/expand toggle button in the footer. Default true. */
+    showCollapseButton?: boolean;
+    /** Optional content rendered in the footer alongside the collapse button. */
+    footer?: React.ReactNode;
+    /**
+     * Optional content rendered in a pinned header at the top of the sidebar.
+     * Hidden when empty (default).
+     */
+    header?: React.ReactNode;
+    /**
+     * Embedded mode — renders only the nav items without the sidebar shell
+     * (no sticky wrapper, no collapse button). Use inside drawers or panels.
+     */
+    embedded?: boolean;
+}
+export default function SideNav({ menuKey, items: itemsProp, defaultCollapsed, showIcons, showCollapseButton, footer, header, embedded, }: SideNavProps): React.JSX.Element | null;

package/dist/types/src/components/blocks/ThemeSwitcher.d.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+export interface ThemeSwitcherThemeOption {
+    label?: string;
+    description?: string;
+}
+export interface ThemeSwitcherProps {
+    /** Show the switcher panel. */
+    open?: boolean;
+    className?: string;
+    wrapperClassName?: string;
+    onClose?: () => void;
+    /** Render as a flat panel or inside a Modal. */
+    surface?: 'flat' | 'modal';
+    showHeader?: boolean;
+    title?: React.ReactNode;
+    subtitle?: React.ReactNode;
+    headerActions?: React.ReactNode;
+    /** Per-theme label/description overrides. */
+    themeOptions?: Record<string, ThemeSwitcherThemeOption>;
+    showModeSection?: boolean;
+    showPrimarySection?: boolean;
+    showRadiusSection?: boolean;
+    showFontSection?: boolean;
+    showStatusSection?: boolean;
+    showThemeSection?: boolean;
+    showIconLibrarySection?: boolean;
+}
+export default function ThemeSwitcher({ open, onClose, surface, showHeader, title, subtitle, headerActions, themeOptions, showModeSection, showPrimarySection, showRadiusSection, showFontSection, showStatusSection, showThemeSection, showIconLibrarySection, className, wrapperClassName, }: ThemeSwitcherProps): React.JSX.Element | null;

package/dist/types/src/components/blocks/Toolbar.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+type ScrollTarget = Window | HTMLElement | null | undefined | React.RefObject<HTMLElement | null>;
+export interface ToolbarProps {
+    leading?: React.ReactNode;
+    center?: React.ReactNode;
+    trailing?: React.ReactNode;
+    children?: React.ReactNode;
+    /** Stick the toolbar to the top of the viewport on scroll. */
+    sticky?: boolean;
+    /** Add shadow on scroll when `sticky` is enabled. */
+    elevateOnScroll?: boolean;
+    /** Scroll container to observe for sticky threshold. Defaults to `window`. */
+    scrollTarget?: ScrollTarget;
+    /** Px threshold before sticky/elevate activates. */
+    scrollThreshold?: number;
+    className?: string;
+    innerClassName?: string;
+    leadingClassName?: string;
+    centerClassName?: string;
+    trailingClassName?: string;
+}
+export default function Toolbar({ leading, center, trailing, children, sticky, elevateOnScroll, scrollTarget, scrollThreshold, className, innerClassName, leadingClassName, centerClassName, trailingClassName, }: ToolbarProps): React.JSX.Element;
+export {};

package/dist/types/src/components/index.d.ts

@@ -1,15 +1,24 @@
 export type { MotionUIProps, UIProps } from './types';
 export { default as Brand } from './blocks/Brand';
-export { default as Breadcrumbs } from './blocks/Breadcrumbs';
+export { default as Breadcrumbs, buildBreadcrumbSchema } from './blocks/Breadcrumbs';
+export type { BreadcrumbItem, BreadcrumbsProps, BreadcrumbSchemaOptions } from './blocks/Breadcrumbs';
 export { default as Carousel } from './blocks/Carousel';
 export * from './blocks/Dropdown';
 export { default as Notifications } from './blocks/Notifications';
 export { default as Search } from './blocks/Search';
+export { default as Toolbar } from './blocks/Toolbar';
+export type { ToolbarProps } from './blocks/Toolbar';
+export { default as ThemeSwitcher } from './blocks/ThemeSwitcher';
+export type { ThemeSwitcherProps, ThemeSwitcherThemeOption } from './blocks/ThemeSwitcher';
+export { default as ProviderSwitcher } from './blocks/ProviderSwitcher';
+export type { ProviderSwitcherProps, ProviderSwitcherItem } from './blocks/ProviderSwitcher';
 export { default as Alert } from './ui/Alert';
+export type { AlertProps } from './ui/Alert';
 export { default as Badge } from './ui/Badge';
 export * from './ui/Badge';
 export * from './ui/Buttons';
 export { default as Card } from './ui/Card';
+export type { CardProps } from './ui/Card';
 export { default as Code } from './ui/Code';
 export { default as Gallery } from './ui/Gallery';
 export * from './ui/Gallery';
@@ -18,14 +27,17 @@ export * from './ui/GridSystem';
 export { default as Image } from './ui/Image';
 export { default as ImageAvatar } from './ui/ImageAvatar';
 export { default as Loader } from './ui/Loader';
+export { default as LocaleSwitcher } from './ui/LocaleSwitcher';
+export type { LocaleSwitcherProps } from './ui/LocaleSwitcher';
 export { default as Modal } from './ui/Modal';
 export * from './ui/Modal';
+export { default as Pagination } from './ui/Pagination';
 export { default as Percentage } from './ui/Percentage';
 export { default as Repeat } from './ui/Repeat';
 export { default as Tab } from './ui/Tab';
 export * from './ui/Tab';
 export { default as Table } from './ui/Table';
-export type { TableHeaderProp, TableReorderHandler, TableReorderMeta, TableSelectionChangeHandler, TableSelectionState } from './ui/Table';
+export type { TableProps, TableHeaderProp, TableReorderHandler, TableReorderMeta, TableSelectionChangeHandler, TableSelectionState } from './ui/Table';
 export { default as Icon } from './ui/Icon';
 export { LayoutBuilder } from './ui/LayoutBuilder';
 export * from './ui/fields/Input';
@@ -33,11 +45,19 @@ export * from './ui/fields/Select';
 export * from './ui/fields/Upload';
 export * from './ui/fields/Crop';
 export * from './ui/fields/UploadCSV';
-export * from './ui/fields/ImageUrl';
-export { default as AssistantAI } from './ui/fields/AssistantAI';
+export * from './ui/fields/ImageField';
+export * from './ui/fields/RichText';
+export * from './ui/fields/CodeEditor';
+export * from './ui/fields/ContextMenu';
 export { default as Menu } from './blocks/Menu';
-export { default as Form } from './widgets/Form';
-export type { FormDeleteArgs, FormDeleteHandler, FormFinallyArgs, FormFinallyHandler, FormSaveArgs, FormSaveHandler, SavePathProps } from './widgets/Form';
+export { default as ListCard } from './blocks/ListCard';
+export type { ListCardProps } from './blocks/ListCard';
+export { default as SideNav } from './blocks/SideNav';
+export type { SideNavProps, SideNavItemDef } from './blocks/SideNav';
+export { default as Form, useFormContext } from './widgets/Form';
+export type { FormProps, FormDeleteArgs, FormDeleteHandler, FormFinallyArgs, FormFinallyHandler, FormSaveArgs, FormSaveHandler, ChangeHandler, FieldOnChange } from './widgets/Form';
+export { FormControllerContext, useFormActions, useFormController } from './widgets/form-controller';
+export type { FormActionEvent, FormController, FormControllerActions, FormControllerState, FormDraftStatus } from './widgets/form-controller';
 export { default as Grid } from './widgets/Grid';
 export { GridArray, GridCore, GridDB, GridGalleryView, GridTableView } from './widgets/grid-core';
 export type { GridAction, GridActions, GridAfterActionArgs, GridAfterActionHandler, GridArrayProps, GridColumn, GridCoreProps, GridDBQuery, GridDBProps, GridFooterContext, GridFormContext, GridGalleryViewProps, GridHeaderContext, GridLayout, GridMutationDeleteArgs, GridMutationDeleteHandler, GridMutationSaveArgs, GridMutationSaveHandler, GridReorderHandler, GridReorderMeta, GridRecordKey, GridProps, GridSelectionChangeHandler, GridSelectionMode, GridSelectionState, GridSticky, GridTableViewProps, } from './widgets/Grid';
@@ -48,5 +68,6 @@ export * from './widgets/Prompt';
 export { default as TabDynamic } from './widgets/TabDynamic';
 export { default as Component } from './Component';
 export { ComponentBlock } from './Component';
-export * from './Template';
+export type { FieldAdapter, FieldFactory, ModelProps, FormTree } from './Component';
+export type { ComponentFormSchemaMap } from '../types/FormSchema';
 export type { ModalDeleteHandler, ModalSaveHandler } from './ui/Modal';

package/dist/types/src/components/types.d.ts

@@ -1,11 +1,18 @@
 import type React from 'react';
 import type { MotionReference } from '../motion';
+/** Slot and class props shared by every UI component. */
 export interface UIProps {
-    pre?: React.ReactNode;
-    post?: React.ReactNode;
-    wrapClass?: string;
+    /** Content rendered immediately before the component's root element. */
+    before?: React.ReactNode;
+    /** Content rendered immediately after the component's root element. */
+    after?: React.ReactNode;
+    /** CSS classes applied to the outermost wrapper element. */
+    wrapperClassName?: string;
+    /** CSS classes applied to the component's primary element. */
     className?: string;
 }
+/** UIProps extended with an optional motion animation reference. */
 export interface MotionUIProps extends UIProps {
+    /** Named motion preset or inline MotionProps override. */
     motion?: MotionReference;
 }

package/dist/types/src/components/ui/Alert.d.ts

@@ -1,13 +1,29 @@
 import React from 'react';
 import { UIProps } from '../..';
-type AlertProps = {
+export type AlertProps = {
     children: string | React.ReactNode;
-    type?: "info" | "success" | "warning" | "danger" | "primary" | "secondary" | "light" | "dark";
-    isFixed?: "top" | "bottom";
+    /** Semantic color variant. */
+    variant?: "info" | "success" | "warning" | "danger" | "primary" | "secondary" | "light" | "dark";
+    /** Visual shell:
+     *  - `"default"` - full alert box with background and border (default)
+     *  - `"text"` - no background, no border, width fits content; ideal for inline status indicators
+     */
+    appearance?: "default" | "text";
+    /** Rendering mode:
+     *  - `"inline"` (default) - renders where declared, normal document flow
+     *  - `"fixed"` - portal to document.body, viewport-fixed above all other content
+     *  - `"sticky"` - portal prepended to `anchorRef`, sticky at the top of that container
+     */
+    placement?: "inline" | "fixed" | "sticky";
+    /** Required when placement="sticky": the scrollable container to anchor to. */
+    anchorRef?: React.RefObject<HTMLElement>;
+    /** Auto-dismiss timeout in ms. */
     timeout?: number;
+    /** Called when the alert is dismissed. */
     onClose?: () => void;
+    /** Icon name, or `true` to show the default variant icon, or `false` to hide. */
     icon?: string | boolean;
     className?: string;
 } & UIProps;
-declare const Alert: ({ children, type, isFixed, timeout, onClose, icon, pre, post, wrapClass, className }: AlertProps) => React.JSX.Element;
+declare const Alert: ({ children, variant, appearance, placement, anchorRef, timeout, onClose, icon, before, after, wrapperClassName, className }: AlertProps) => React.JSX.Element | null;
 export default Alert;