@llmnative/react 1.0.0 → 1.2.0

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

@@ -90,6 +90,9 @@ export type AppProviderProps = {
     errorReportUrl?: string;
     /** Force debug mode in error boundaries (shows stack trace, component tree, browser context). Auto-enabled in DEV builds. */
     debug?: boolean;
+    /** Basename for BrowserRouter (e.g. '/llmnative-react/' for GH Pages). If set, only the
+     * pathname after this prefix is used for route matching. */
+    basename?: string;
 };
 /** Full App props: AppProviderProps + routing-specific config. */
 export type AppProps = AppProviderProps & {
@@ -116,7 +119,7 @@ export declare const getContextMenu: () => string[];
  * `App` uses `AppProvider` internally. Use `AppProvider` directly only when
  * you need the provider stack without the routing layer (e.g. tests, Storybook).
  */
-export declare function AppProvider({ contextProviders, providers, appName, scrapeConfig, iconProvider, themeProvider, i18n, children, errorReportUrl, debug, }: AppProviderProps): React.JSX.Element;
+export declare function AppProvider({ contextProviders, providers, appName, scrapeConfig, iconProvider, themeProvider, i18n, children, errorReportUrl, debug, basename, }: AppProviderProps): React.JSX.Element;
 declare function App({ importPage, LayoutDefault, menuConfig, children, ...providerProps }: AppProps): React.JSX.Element;
 export declare const useMenu: (type: string) => UseMenuItem[];
 export default App;

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

@@ -50,12 +50,16 @@ export interface I18nDict {
     };
     select: {
         placeholder: string;
+        loading: string;
     };
     modal: {
         save: string;
         delete: string;
         cancel: string;
         close: string;
+        ok: string;
+        yes: string;
+        no: string;
     };
     upload: {
         clickOrDrag: string;

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

@@ -25,6 +25,6 @@ declare class ErrorBoundary extends React.Component<ErrorBoundaryProps, State> {
     reset: () => void;
     copy: () => void;
     sendReport: () => void;
-    render(): string | number | boolean | Iterable<React.ReactNode> | React.JSX.Element | null | undefined;
+    render(): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
 }
 export default ErrorBoundary;

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

@@ -1,9 +1,14 @@
 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;
     wrapperClassName?: string;
     className?: string;

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

@@ -9,8 +9,10 @@ type CarouselProps = {
     showIndicators?: boolean;
     showControls?: boolean;
     showCaption?: boolean;
+    /** Use dark variant indicators/controls. */
     dark?: boolean;
     autoPlay?: AutoPlayOptions;
+    /** 0-based index of the initially visible slide. */
     initialSlide?: number;
     renderCaption?: (image: React.ReactElement) => React.ReactElement;
     onSlideClick?: (event: React.MouseEvent<HTMLDivElement, MouseEvent>) => void;

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

@@ -1,23 +1,32 @@
 import React from 'react';
 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 MotionUIProps {
+export interface DropdownProps extends MotionUIProps {
     children: React.ReactNode;
+    /** 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;
+    /** When `true`, the menu stays open regardless of interaction. */
     staticOpen?: boolean;
+    /** Horizontal alignment relative to the trigger. */
     position?: "start" | "end";
+    /** Drop direction. */
     placement?: "auto" | "top" | "bottom";
+    /** CSS positioning strategy. */
     strategy?: "fixed" | "absolute";
     triggerClassName?: string;
     badgeClassName?: string;
@@ -25,9 +34,30 @@ interface DropdownProps extends MotionUIProps {
     headerClassName?: string;
     footerClassName?: string;
 }
+export type AsyncDropdownLoader<TItem> = (query: string, signal: AbortSignal) => Promise<TItem[]>;
+export interface AsyncDropdownProps<TItem> extends Omit<DropdownProps, 'children' | 'header' | 'onOpenChange'> {
+    /** Loads results when the menu opens and whenever the query changes. */
+    loadItems: AsyncDropdownLoader<TItem>;
+    getItemId: (item: TItem) => string;
+    renderItem: (item: TItem) => React.ReactNode;
+    /** Return `false` to keep the menu open (for example after a declined confirmation). */
+    onSelect: (item: TItem) => void | boolean | Promise<void | boolean>;
+    selectedId?: string | null;
+    searchPlaceholder?: string;
+    emptyState?: React.ReactNode;
+    loadingState?: React.ReactNode;
+    errorState?: (error: unknown) => React.ReactNode;
+    debounceMs?: number;
+    closeOnSelect?: boolean;
+    inputClassName?: string;
+    selectedClassName?: string;
+    header?: React.ReactNode;
+    onOpenChange?: (open: boolean) => void;
+}
 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;
     badgeClassName?: string;
@@ -35,13 +65,15 @@ interface DropdownButtonProps extends Pick<MotionUIProps, 'motion'> {
     onToggle?: () => void;
     open?: boolean;
     menuId?: string;
-    buttonRef?: React.RefObject<HTMLButtonElement>;
+    buttonRef?: React.RefObject<HTMLButtonElement | null>;
 }
 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 {
@@ -52,6 +84,11 @@ interface DropdownDividerProps {
     className?: string;
 }
 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;
+/**
+ * Async/searchable extension of Dropdown. It owns only the interaction model; applications
+ * supply their own data reader and selection action (site, tenant, entity, or any resource).
+ */
+export declare function AsyncDropdown<TItem>({ loadItems, getItemId, renderItem, onSelect, selectedId, searchPlaceholder, emptyState, loadingState, errorState, debounceMs, closeOnSelect, inputClassName, selectedClassName, header, open: controlledOpen, defaultOpen, onOpenChange, footer, headerClassName, staticOpen, ...dropdownProps }: AsyncDropdownProps<TItem>): 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;

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

@@ -3,17 +3,24 @@ 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;

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

@@ -2,8 +2,10 @@ import React from 'react';
 import { BadgeType } from '../ui/Badge';
 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;

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

@@ -1,5 +1,6 @@
 import React from "react";
 import type { BadgeProps } from "../ui/Badge";
+import type { MotionReference } from "../../motion";
 interface NotificationItem {
     title: string;
     url: string;
@@ -14,7 +15,9 @@ interface NotificationsProps {
     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({ items, badge, seeAllUrl, onMarkAllRead, className, }: 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

@@ -11,6 +11,8 @@ export interface ProviderSwitcherItem {
 }
 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;
@@ -60,4 +62,4 @@ export interface ProviderSwitcherProps extends UIProps {
  * 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, 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;
+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,5 +1,6 @@
 import React from 'react';
 interface SearchProps {
+    /** Called on every keystroke with the current search input event. */
     onQueryChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
 }
 export declare const SearchButton: () => React.JSX.Element;

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

@@ -1,17 +1,21 @@
 import React from 'react';
-import type { UIProps } from '../types';
 export interface ThemeSwitcherThemeOption {
     label?: string;
     description?: string;
 }
-export interface ThemeSwitcherProps extends UIProps {
+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;

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

@@ -5,9 +5,13 @@ export interface ToolbarProps {
     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;

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

@@ -54,8 +54,8 @@ 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 } from './widgets/Form';
-export type { FormProps, FormDeleteArgs, FormDeleteHandler, FormFinallyArgs, FormFinallyHandler, FormSaveArgs, FormSaveHandler } from './widgets/Form';
+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';

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

@@ -2,6 +2,7 @@ import React from 'react';
 import { UIProps } from '../..';
 export type AlertProps = {
     children: string | React.ReactNode;
+    /** Semantic color variant. */
     variant?: "info" | "success" | "warning" | "danger" | "primary" | "secondary" | "light" | "dark";
     /** Visual shell:
      *  - `"default"` - full alert box with background and border (default)
@@ -15,9 +16,12 @@ export type AlertProps = {
      */
     placement?: "inline" | "fixed" | "sticky";
     /** Required when placement="sticky": the scrollable container to anchor to. */
-    anchorRef?: React.RefObject<HTMLElement>;
+    anchorRef?: React.RefObject<HTMLElement | null>;
+    /** 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;

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

@@ -11,17 +11,23 @@ export type BadgeProps = React.ReactNode | BadgeDescriptor;
 export declare function isBadgeDescriptor(value: BadgeProps | undefined): value is BadgeDescriptor;
 export declare function normalizeBadgeProps(value: BadgeProps | undefined, fallbackType?: BadgeType, fallbackClassName?: string): BadgeDescriptor | undefined;
 export type BadgeOverlayProps = {
+    /** Shorthand badge descriptor (content + variant). */
     badge?: BadgeProps;
+    /** Badge content when not using the `badge` shorthand. */
     content?: React.ReactNode;
+    /** Badge color variant. */
     variant?: BadgeType;
+    /** Fallback variant when none is specified. */
     defaultType?: BadgeType;
     className?: string;
+    /** When `true` and no badge is provided, renders children without wrapping. */
     descriptorOnly?: boolean;
     children?: React.ReactNode;
 };
 export declare const BadgeOverlay: ({ badge, content, variant, defaultType, className, descriptorOnly, children }: BadgeOverlayProps) => React.ReactNode;
 export type BadgeComponentProps = {
     children: string | React.ReactNode;
+    /** Semantic color variant. */
     variant?: BadgeType;
 } & UIProps;
 declare const Badge: ({ children, variant, before, after, wrapperClassName, className }: BadgeComponentProps) => React.JSX.Element;

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

@@ -3,13 +3,15 @@ import type { MotionUIProps, UIProps } from '../types';
 import { BadgeProps } from './Badge';
 export interface IButton extends MotionUIProps {
     onClick?: (e: React.MouseEvent<HTMLElement>) => unknown;
+    /** Icon name or path for a leading icon. */
     icon?: string;
     label?: string | React.ReactNode;
+    /** Badge descriptor shown as overlay on the button. */
     badge?: BadgeProps;
     title?: string;
+    /** Accessible label for screen readers. Required when the button is icon-only. */
     ariaLabel?: string;
     disabled?: boolean;
-    loading?: boolean;
     iconClassName?: string;
     style?: React.CSSProperties;
     variant?: "primary" | "secondary" | "danger" | "success" | "warning" | "info" | "light" | "dark" | "outline-primary" | "outline-secondary" | "outline-danger" | "outline-success" | "link";
@@ -21,6 +23,7 @@ export type SetMessagePayload = {
 };
 export interface LoadingButtonProps extends Omit<IButton, "onClick"> {
     onClick?: (e: React.MouseEvent<HTMLElement>, setMessage?: (payload: SetMessagePayload) => void) => Promise<unknown>;
+    loading?: boolean;
     loadingLabel?: string | React.ReactNode;
 }
 export declare const buttonBaseClass = "btn";
@@ -38,7 +41,7 @@ export declare const buttonOutlineDangerClass = "btn-outline-danger";
 export declare const buttonOutlineSuccessClass = "btn-outline-success";
 export declare const buttonLinkClass = "btn-link";
 export declare const LoadingButton: ({ onClick, icon, label, badge, title, ariaLabel, disabled, loading, before, after, wrapperClassName, className, iconClassName, style, loadingLabel, variant, motion: motionConfig }?: LoadingButtonProps) => React.JSX.Element;
-export declare const ActionButton: ({ onClick, icon, label, badge, title, disabled, before, after, wrapperClassName, className, iconClassName, style, variant, motion: motionConfig }?: IButton) => React.JSX.Element;
+export declare const ActionButton: ({ onClick, icon, label, badge, title, ariaLabel, disabled, before, after, wrapperClassName, className, iconClassName, style, variant, motion: motionConfig }?: IButton) => React.JSX.Element;
 interface BackLinkProps extends UIProps {
     label?: string;
 }

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

@@ -2,12 +2,15 @@ import React from 'react';
 import { UIProps } from '../..';
 export interface CardProps extends UIProps {
     children: React.ReactNode;
+    /** Card title shown in the header area. */
     title?: string;
+    /** Custom header content (replaces the default title row). */
     header?: string | React.ReactNode;
     footer?: string | React.ReactNode;
     headerClassName?: string;
     bodyClassName?: string;
     footerClassName?: string;
+    /** Show a loading skeleton instead of content. */
     loading?: boolean;
     before?: React.ReactNode;
     after?: React.ReactNode;

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

@@ -16,9 +16,13 @@ type PrismTheme = keyof typeof THEMES;
 export type PrismBackground = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'light' | 'dark' | 'white' | 'black' | 'transparent' | 'default';
 interface CodeProps extends UIProps {
     children: string;
+    /** Syntax highlight language (e.g. `"tsx"`, `"python"`). */
     language?: PrismLanguage;
+    /** Show a copy-to-clipboard button. */
     showCopy?: boolean;
+    /** Prism color theme. */
     theme?: PrismTheme;
+    /** Background style variant. */
     background?: PrismBackground;
 }
 declare const Code: ({ language, children, before, after, wrapperClassName, className, showCopy, theme, background, }: CodeProps) => React.JSX.Element;

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

@@ -26,6 +26,12 @@ export type GalleryOverlay = {
     render?: (item: GalleryRecord, index: number) => React.ReactNode;
     when?: GalleryOverlayFilter;
     className?: string;
+    /**
+     * Inline style overrides, merged on top of the position's own offset styles (and, for
+     * `width`/`maxWidth`, on top of the default overlay lane width — a single-line badge's
+     * width, too narrow for e.g. a multi-line description meant to span most of the card).
+     */
+    style?: React.CSSProperties;
 };
 export type GallerySelectionState = RecordSelectionState<GalleryRecord>;
 export type GallerySelectionChangeHandler = (selection: GallerySelectionState) => void;
@@ -33,13 +39,14 @@ export interface GalleryProps extends UIProps {
     records?: GalleryRecord[];
     header?: string | React.ReactNode;
     footer?: string | React.ReactNode;
+    /** Overlay badges rendered on each gallery item. */
     overlays?: GalleryOverlay[];
     onRowClick?: (record: GalleryRecord) => void;
     onSelectionChange?: GallerySelectionChangeHandler;
+    /** Enable sorting, optionally with a default sort config. */
     sortable?: boolean | OrderConfig;
     pagination?: PaginationParams;
-    scrollToTopOnChange?: boolean;
-    scrollBehavior?: ScrollBehavior;
+    /** Grid gap size (Tailwind spacing scale). */
     gap?: 0 | 1 | 2 | 3 | 4 | 5;
     columns?: 1 | 2 | 3 | 4 | 6;
     groupBy?: string | string[];

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

@@ -5,7 +5,10 @@ type ContainerProps = {
     style?: CSSProperties;
     onClick?: () => void;
 };
-type ColProps = ContainerProps & {
+type ColProps = {
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
     defaultSize?: number;
     xxl?: number | 'auto';
     xl?: number | 'auto';

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

@@ -1,12 +1,15 @@
 import React from 'react';
 import type { IconProviderAdapter } from '../../providers/icon/IconProvider';
 interface IconProps {
+    /** Icon name (provider-specific identifier). */
     name?: string;
+    /** Icon size in px. Defaults to `16`. */
     size?: number;
     className?: string;
     style?: React.CSSProperties;
     /** Override the global icon provider for this instance only */
     provider?: IconProviderAdapter;
+    /** Accessible label for screen readers. */
     label?: string;
     /** Provider-specific variant — e.g. PhosphorWeight: 'thin'|'light'|'regular'|'bold'|'fill'|'duotone'. Ignored by providers that don't support it. */
     weight?: string;

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

@@ -3,15 +3,21 @@ import { UIProps } from '../..';
 export type ImageFit = 'cover' | 'contain' | 'fill' | 'scale-down' | 'none';
 export type ImagePosition = 'center' | 'top' | 'bottom' | 'left' | 'right' | 'top left' | 'top right' | 'bottom left' | 'bottom right';
 type ImageProps = {
+    /** Image source URL. */
     src: string;
+    /** Placeholder image URL shown while loading. */
     placeholder?: string;
     label?: string;
     title?: string;
+    /** Object-fit style for the image. */
     fit?: ImageFit;
+    /** Object-position for the image. */
     position?: ImagePosition;
+    /** Feedback element shown below the image (e.g. caption, error). */
     feedback?: React.ReactNode;
     width?: number;
     height?: number;
+    /** Responsive srcset attribute. */
     srcset?: string;
     sizes?: string;
 } & UIProps;

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

@@ -3,12 +3,15 @@ import type { UIProps } from '../types';
 import type { BadgeDescriptor } from './Badge';
 export type AvatarFit = 'cover' | 'contain' | 'fill' | 'scale-down' | 'none';
 interface ImageAvatarProps extends UIProps {
+    /** Avatar image URL. */
     src: string;
     width?: number;
     height?: number;
     title?: string;
     alt?: string;
+    /** Object-fit style for the avatar image. */
     fit?: AvatarFit;
+    /** Badge descriptor shown as an overlay on the avatar. */
     badge?: BadgeDescriptor;
     feedback?: React.ReactNode;
 }

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

@@ -1,11 +1,13 @@
 import React from 'react';
 import { UIProps } from '../..';
 interface LoaderProps extends UIProps {
+    /** When `true`, renders the loading indicator instead of children. */
     show?: boolean;
     children: React.ReactNode;
+    /** Icon name for the loading indicator. */
     icon?: string;
     title?: string;
     description?: string;
 }
-declare function Loader({ children, show, icon, title, description, before, after, wrapperClassName, className }: LoaderProps): string | number | boolean | Iterable<React.ReactNode> | React.JSX.Element | null | undefined;
+declare function Loader({ children, show, icon, title, description, before, after, wrapperClassName, className }: LoaderProps): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
 export default Loader;

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

@@ -40,6 +40,15 @@ export interface ModalProps extends MotionUIProps {
     closeOnBackdrop?: boolean;
     /** CSS `z-index` override (useful when stacking modals). */
     zIndex?: number;
+    /**
+     * Px of screen space already reserved on the right edge (e.g. a persistent app-level
+     * side panel docked outside this Modal's own portal) — the backdrop/cover stop short of
+     * that space (so the reserved area stays undimmed and interactive) and, for
+     * `position="right"`, the dialog itself shifts left by the same amount instead of
+     * overlapping it. `0`/`undefined` = today's behaviour, flush against the real viewport
+     * edge.
+     */
+    rightInset?: number;
     /**
      * When `true` this modal is visually "behind" another modal stacked on top.
      * The panel becomes 10% wider (so its edge peeks out from behind the upper modal),
@@ -47,14 +56,27 @@ export interface ModalProps extends MotionUIProps {
      * modal's backdrop handles interaction blocking), and its cover becomes non-interactive.
      */
     stackedBehind?: boolean;
+    /**
+     * Replaces the default × close button with custom content, in the same header slot
+     * (still next to the fullscreen toggle, if any). Use this when the host app wants one
+     * consistent icon/action across every modal instead of the built-in ×  — e.g. an
+     * app-level "toggle side panel" icon that means the same thing whether a modal happens
+     * to be open or not. Backdrop click and Cancel/Save/Delete still call `onClose` as usual;
+     * this only swaps what's rendered in the × slot, not the close mechanics themselves.
+     */
+    closeSlot?: React.ReactNode;
 }
+/** Props for a confirm/deny modal dialog with Yes/No buttons. */
 export interface ModalYesNoProps {
     title?: React.ReactNode;
     children: React.ReactNode;
+    /** Async handler for the Yes button. Return `true` to close. */
     onYes?: (e: React.MouseEvent<HTMLElement>) => Promise<boolean>;
+    /** Async handler for the No button. Return `true` to close. */
     onNo?: (e: React.MouseEvent<HTMLElement>) => Promise<boolean>;
     onClose?: () => void;
 }
+/** Props for a simple acknowledgment modal with an OK button. */
 export interface ModalOkProps {
     children: React.ReactNode;
     title?: React.ReactNode;

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

@@ -22,7 +22,9 @@ export type PaginationParams = {
 };
 interface PaginationProps<T> extends UIProps, PaginationParams {
     records: T[];
+    /** Render function receiving paginated records and current page offset. */
     children: (pageRecords: T[], pageOffset: number) => React.ReactNode;
+    /** Portal target element — renders pagination bar outside the normal flow. */
     appendTo?: HTMLElement | null;
 }
 declare const Pagination: <T>({ records, children, limit, page, maxPageButtons, appendTo, before, after, className, wrapperClassName, scrollToTopOnChange, scrollBehavior, align, sticky }: PaginationProps<T>) => React.JSX.Element;

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

@@ -3,14 +3,23 @@ import { UIProps } from '../..';
 type ColorType = "info" | "success" | "warning" | "danger" | "primary" | "secondary" | "light" | "dark";
 type ShapeType = "bar" | "circle";
 interface PercentageProps extends UIProps {
+    /** Current value. */
     value?: number;
+    /** Maximum value (defaults to `100`). */
     max?: number;
+    /** Minimum value. */
     min?: number;
+    /** Visual shape: `"bar"` (default) or `"circle"`. */
     appearance?: ShapeType;
+    /** Progress bar color. */
     variant?: ColorType;
+    /** Track (background) color. */
     trackVariant?: ColorType;
+    /** Bar/circle thickness in px. */
     thickness?: number;
+    /** Show percentage text label. */
     showText?: boolean;
+    /** Circle diameter in px (circle mode only). */
     size?: number;
     fontSize?: number;
     label?: string;

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

@@ -10,7 +10,6 @@ export interface RepeatCallbackArgs {
 interface RepeatProps {
     name: string;
     children: React.ReactNode | ((args: RepeatCallbackArgs) => React.ReactNode);
-    value?: RecordProps[];
     onChange?: FieldOnChange;
     onAdd?: (value: RecordProps[]) => void;
     onRemove?: (index: number) => void;

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

@@ -41,7 +41,7 @@ interface TabProps extends MotionUIProps {
 export declare function getTabLayoutConfig(layout: TabPosition): TabLayoutConfig;
 export declare function getTabTriggerClassName(layout: TabPosition, active: boolean, className?: string): string;
 export declare function getTabPaneClassName(className?: string): string;
-export declare const TabLayouts: Record<TabPosition, (props: TabLayoutProps) => JSX.Element>;
+export declare const TabLayouts: Record<TabPosition, (props: TabLayoutProps) => React.ReactElement>;
 export declare const TabItem: React.FC<TabItemProps>;
 declare const Tab: React.FC<TabProps>;
 export default Tab;