@adgytec/adgytec-web-ui-components 2.2.0 → 2.3.1

package/dist/components/Sheets/SideSheetModal/types.d.ts

@@ -1,7 +1,56 @@
 import { Modal } from 'react-aria-components';
 import { SheetLayout } from '../core';
+/**
+ * Alignment edge for a side sheet on the screen.
+ *
+ * - `"start"`: Anchors to the inline-start edge of the viewport (left in LTR, right in RTL).
+ * - `"end"`: Anchors to the inline-end edge of the viewport (right in LTR, left in RTL).
+ */
 export type SideSheetAlignment = "start" | "end";
+/**
+ * Props for the {@link SideSheetModal} component.
+ * Extends React Aria Components `Modal` props with side-sheet layout and alignment configurations.
+ *
+ * @example
+ * ```tsx
+ * import { DialogTrigger } from "react-aria-components";
+ * import {
+ *     Button,
+ *     ModalOverlay,
+ *     SideSheet,
+ *     SideSheetModal,
+ * } from "@adgytec/web-ui-components";
+ *
+ * export function Example() {
+ *     return (
+ *         <DialogTrigger>
+ *             <Button label="Open Sheet" />
+ *             <ModalOverlay>
+ *                 <SideSheetModal alignment="end" layout="standard">
+ *                     <SideSheet headline="Details">
+ *                         <p>Side sheet content.</p>
+ *                     </SideSheet>
+ *                 </SideSheetModal>
+ *             </ModalOverlay>
+ *         </DialogTrigger>
+ *     );
+ * }
+ * ```
+ */
 export interface SideSheetModalProps extends React.ComponentPropsWithRef<typeof Modal> {
+    /**
+     * Side of the screen where the side sheet appears.
+     *
+     * @default "end"
+     */
     alignment?: SideSheetAlignment;
+    /**
+     * Layout style of the side sheet.
+     *
+     * - `"standard"`: Attached to the screen edge.
+     * - `"detached"`: Floating with margin and rounded corners on all edges.
+     *
+     * @default "standard"
+     */
     layout?: SheetLayout;
 }

package/dist/components/Sheets/core/layout.d.ts

@@ -1 +1,12 @@
+/**
+ * Layout styles for Material 3 sheets (`SideSheet` and `BottomSheet`).
+ *
+ * - `"standard"`: The sheet is attached directly to the edge(s) of the viewport (no outer margins; corners on the attachment edge are square).
+ * - `"detached"`: The sheet has outer margins separating it from the viewport edges and features rounded corners on all sides, appearing as a floating container.
+ *
+ * @example
+ * ```tsx
+ * const layout: SheetLayout = "detached";
+ * ```
+ */
 export type SheetLayout = "standard" | "detached";

package/dist/components/Snackbar/SnackbarRegion.d.ts

@@ -1,2 +1,52 @@
 import { SnackbarRegionProps } from './types';
+/**
+ * Root region component for managing and rendering [Material 3 Snackbars](https://m3.material.io/components/snackbar/overview).
+ *
+ * Wraps your application or a section of it to provide a snackbar context via {@link SnackbarQueueContext}.
+ * Renders an underlying React Aria `ToastRegion` fixed at the bottom center of the viewport (elevated with
+ * high z-index), displaying queued snackbar notifications with supporting text, optional actions,
+ * and an optional dismiss button.
+ *
+ * Configurable CSS tokens:
+ * - `--md-snackbar-background`: Background color of the snackbar (`var(--md-sys-color-inverse-surface)`).
+ * - `--md-snackbar-color`: Text and icon color of the snackbar (`var(--md-sys-color-inverse-on-surface)`).
+ * - `--md-snackbar-action-color`: Text color of the action button (`var(--md-sys-color-inverse-primary)`).
+ *
+ * @example
+ * ```tsx
+ * import {
+ *     Button,
+ *     SnackbarRegion,
+ *     useSnackbarQueue,
+ * } from "@adgytec/web-ui-components";
+ *
+ * function NotificationTrigger() {
+ *     const queue = useSnackbarQueue();
+ *
+ *     const showNotification = () => {
+ *         queue.add(
+ *             {
+ *                 supportingText: "File uploaded successfully.",
+ *                 action: (
+ *                     <Button color="text" onPress={() => console.log("View")}>
+ *                         View
+ *                     </Button>
+ *                 ),
+ *             },
+ *             { timeout: 5000 }
+ *         );
+ *     };
+ *
+ *     return <Button onPress={showNotification}>Upload</Button>;
+ * }
+ *
+ * export function App() {
+ *     return (
+ *         <SnackbarRegion maxVisibleSnackbars={1}>
+ *             <NotificationTrigger />
+ *         </SnackbarRegion>
+ *     );
+ * }
+ * ```
+ */
 export declare const SnackbarRegion: React.FC<SnackbarRegionProps>;

package/dist/components/Snackbar/context.d.ts

@@ -1,4 +1,42 @@
 import { UNSTABLE_ToastQueue as ToastQueue } from 'react-aria-components';
 import { SnackbarContent } from './types';
+/**
+ * React context holding the active `ToastQueue` instance for snackbars,
+ * or `null` if accessed outside a {@link SnackbarRegion}.
+ */
 export declare const SnackbarQueueContext: import('react').Context<ToastQueue<SnackbarContent> | null>;
+/**
+ * Hook to access the active snackbar queue from any child component within a {@link SnackbarRegion}.
+ *
+ * Returns the underlying React Aria `ToastQueue` instance, allowing components
+ * to enqueue new snackbars, dismiss existing ones, or inspect the queue.
+ *
+ * @throws {Error} If called outside of a {@link SnackbarRegion}.
+ *
+ * @example
+ * ```tsx
+ * import { Button, useSnackbarQueue } from "@adgytec/web-ui-components";
+ *
+ * export function CopyButton({ text }: { text: string }) {
+ *     const snackbarQueue = useSnackbarQueue();
+ *
+ *     const handleCopy = async () => {
+ *         await navigator.clipboard.writeText(text);
+ *         snackbarQueue.add(
+ *             {
+ *                 supportingText: "Copied to clipboard",
+ *                 action: (
+ *                     <Button color="text" onPress={() => console.log("Undo")}>
+ *                         Undo
+ *                     </Button>
+ *                 ),
+ *             },
+ *             { timeout: 4000 }
+ *         );
+ *     };
+ *
+ *     return <Button onPress={handleCopy}>Copy</Button>;
+ * }
+ * ```
+ */
 export declare function useSnackbarQueue(): ToastQueue<SnackbarContent>;

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

@@ -1,10 +1,79 @@
 import { ReactNode } from 'react';
+/**
+ * Content payload and options for a snackbar item in the queue.
+ * Passed to `queue.add(content, options)`.
+ *
+ * @example
+ * ```tsx
+ * const queue = useSnackbarQueue();
+ *
+ * queue.add(
+ *     {
+ *         supportingText: "Message sent successfully.",
+ *         action: (
+ *             <Button color="text" onPress={() => console.log("Undo")}>
+ *                 Undo
+ *             </Button>
+ *         ),
+ *         hideCloseAction: false,
+ *     },
+ *     { timeout: 5000 }
+ * );
+ * ```
+ */
 export type SnackbarContent = {
+    /**
+     * Whether to hide the default close ("X") icon button.
+     * When `false` or omitted, a close icon button is automatically rendered.
+     *
+     * @default false
+     */
     hideCloseAction?: boolean;
+    /**
+     * Main message or descriptive text for the snackbar.
+     * Styled using Material 3 `typography.bodyMedium`.
+     */
     supportingText: ReactNode;
+    /**
+     * Optional action element (such as a text button) rendered alongside the supporting text.
+     *
+     * @example
+     * ```tsx
+     * action: <Button color="text" onPress={handleUndo}>Undo</Button>
+     * ```
+     */
     action?: ReactNode;
 };
+/**
+ * Props for the {@link SnackbarRegion} component.
+ *
+ * Configurable CSS tokens:
+ * - `--md-snackbar-background`: Background color of the snackbar (`var(--md-sys-color-inverse-surface)`).
+ * - `--md-snackbar-color`: Text and icon color of the snackbar (`var(--md-sys-color-inverse-on-surface)`).
+ * - `--md-snackbar-action-color`: Text color of the action button (`var(--md-sys-color-inverse-primary)`).
+ *
+ * @example
+ * ```tsx
+ * import { SnackbarRegion } from "@adgytec/web-ui-components";
+ *
+ * export function RootLayout({ children }: { children: React.ReactNode }) {
+ *     return (
+ *         <SnackbarRegion maxVisibleSnackbars={1}>
+ *             {children}
+ *         </SnackbarRegion>
+ *     );
+ * }
+ * ```
+ */
 export interface SnackbarRegionProps {
+    /**
+     * Application content wrapped by the snackbar region.
+     */
     children?: ReactNode;
+    /**
+     * The maximum number of snackbars displayed simultaneously in the region.
+     *
+     * @default 1
+     */
     maxVisibleSnackbars?: number;
 }

package/dist/components/Splash/Splash.d.ts

@@ -1,2 +1,8 @@
 import { SplashProps } from './types';
+/**
+ * Material Design ripple splash animation element.
+ *
+ * Rendered absolutely inside an `overflow: clip` container at the press position coordinates `(x, y)`
+ * and expands outward, dissolving when the CSS keyframe animation completes.
+ */
 export declare const Splash: React.FC<SplashProps>;

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

@@ -1,8 +1,18 @@
+/**
+ * State object representing an active ripple splash animation.
+ */
 export interface SplashState {
+    /** Unique incremental identifier for keying the ripple animation instance. */
     id: number;
+    /** Horizontal position (in pixels) of the pointer interaction relative to the element. */
     x: number;
+    /** Vertical position (in pixels) of the pointer interaction relative to the element. */
     y: number;
+    /** Callback triggered when the ripple CSS animation finishes, cleaning up state. */
     onAnimationEnd: () => void;
 }
+/**
+ * Props for the {@link Splash} component.
+ */
 export interface SplashProps extends SplashState {
 }

package/dist/components/Splash/useSplash.d.ts

@@ -1,5 +1,26 @@
 import { PressEvent } from 'react-aria-components';
 import { SplashState } from './types';
+/**
+ * Custom hook that coordinates Material Design ripple splash animation state on pointer press.
+ *
+ * Captures press coordinates from React Aria's {@link PressEvent} and generates active {@link SplashState},
+ * automatically cleaning up the ripple element once the CSS expansion animation finishes.
+ *
+ * @param onPress - Optional consumer press handler invoked alongside splash creation.
+ * @returns Object containing `splashInfo` (active ripple data or `null`) and stable `handlePress` callback.
+ *
+ * @example
+ * ```tsx
+ * const { splashInfo, handlePress } = useSplash(onPress);
+ *
+ * return (
+ *     <AriaButton onPress={handlePress}>
+ *         {splashInfo && <Splash {...splashInfo} />}
+ *         Label
+ *     </AriaButton>
+ * );
+ * ```
+ */
 export declare const useSplash: (onPress?: (e: PressEvent) => void) => {
     splashInfo: SplashState | null;
     handlePress: (e: PressEvent) => void;

package/dist/components/Tabs/Tab/Tab.d.ts

@@ -1,7 +1,38 @@
 import { LucideIcon } from 'lucide-react';
 import { ReactNode } from 'react';
 import { Tab as AriaTab } from 'react-aria-components';
-export declare const Tab: React.FC<Omit<React.ComponentPropsWithRef<typeof AriaTab>, "children"> & {
+/**
+ * Props for the {@link Tab} component.
+ * Extends React Aria Components `Tab` props (omitting raw `children` in favor of `label` and `icon`).
+ */
+export interface TabProps extends Omit<React.ComponentPropsWithRef<typeof AriaTab>, "children"> {
+    /**
+     * Text label to display inside the tab.
+     */
     label?: ReactNode;
+    /**
+     * Optional icon displayed alongside the tab label.
+     */
     icon?: LucideIcon;
-}>;
+}
+/**
+ * An individual interactive tab button within a {@link TabList}, conforming to
+ * [Material 3 Tabs](https://m3.material.io/components/tabs/overview).
+ *
+ * Extends React Aria Components `Tab` with Material 3 styling, supporting:
+ * - A text `label` and an optional `icon` (rendered via {@link Icon}).
+ * - Interactive ripple feedback via {@link Splash}.
+ * - An animated {@link SelectionIndicator} that underlines or highlights the active tab.
+ * - State layer feedback on hover, focus-visible, and pressed states.
+ *
+ * @example
+ * ```tsx
+ * import { Tab } from "@adgytec/web-ui-components";
+ * import { Home } from "lucide-react";
+ *
+ * export function Example() {
+ *     return <Tab id="home" label="Home" icon={Home} />;
+ * }
+ * ```
+ */
+export declare const Tab: React.FC<TabProps>;

package/dist/components/Tabs/TabList/TabList.d.ts

@@ -1,2 +1,43 @@
 import { TabList as AriaTabList } from 'react-aria-components';
-export declare const TabList: <T extends object>({ className, ...props }: React.ComponentPropsWithRef<typeof AriaTabList<T>>) => import("react").JSX.Element;
+/**
+ * Props for the {@link TabList} component.
+ * Extends React Aria Components `TabList` props.
+ *
+ * Configurable CSS tokens:
+ * - `--md-tabs-color`: Text and icon color for inactive tabs (`var(--md-sys-color-on-surface-variant)`).
+ * - `--md-tabs-active-color`: Text and icon color for the active tab (`var(--md-sys-color-on-surface)`).
+ * - `--md-tabs-active-indicator-color`: Color of the selection indicator line (`var(--md-sys-color-primary)`).
+ * - `--md-tab-list-divider-color`: Color of the divider line below or beside the tab list (`var(--md-sys-color-surface-variant)`).
+ */
+export interface TabListProps<T extends object = object> extends React.ComponentPropsWithRef<typeof AriaTabList<T>> {
+}
+/**
+ * Container for interactive {@link Tab} elements, conforming to
+ * [Material 3 Tabs](https://m3.material.io/components/tabs/overview).
+ *
+ * Extends React Aria Components `TabList` with Material 3 styling, active selection
+ * indicator positioning, and divider styling for horizontal and vertical orientations.
+ *
+ * Configurable CSS tokens:
+ * - `--md-tabs-color`: Text and icon color for inactive tabs (`var(--md-sys-color-on-surface-variant)`).
+ * - `--md-tabs-active-color`: Text and icon color for the active tab (`var(--md-sys-color-on-surface)`).
+ * - `--md-tabs-active-indicator-color`: Color of the selection indicator line (`var(--md-sys-color-primary)`).
+ * - `--md-tab-list-divider-color`: Color of the divider line below or beside the tab list (`var(--md-sys-color-surface-variant)`).
+ *
+ * @example
+ * ```tsx
+ * import { Tab, TabList } from "@adgytec/web-ui-components";
+ * import { Home, Settings, User } from "lucide-react";
+ *
+ * export function NavigationTabList() {
+ *     return (
+ *         <TabList aria-label="Account Tabs">
+ *             <Tab id="home" label="Home" icon={Home} />
+ *             <Tab id="profile" label="Profile" icon={User} />
+ *             <Tab id="settings" label="Settings" icon={Settings} />
+ *         </TabList>
+ *     );
+ * }
+ * ```
+ */
+export declare const TabList: <T extends object>({ className, ...props }: TabListProps<T>) => import('react').JSX.Element;

package/dist/components/Tabs/TabPanel/TabPanel.d.ts

@@ -1,2 +1,29 @@
 import { TabPanel as AriaTabPanel } from 'react-aria-components';
-export declare const TabPanel: React.FC<React.ComponentPropsWithRef<typeof AriaTabPanel>>;
+/**
+ * Props for the {@link TabPanel} component.
+ * Extends React Aria Components `TabPanel` props.
+ */
+export interface TabPanelProps extends React.ComponentPropsWithRef<typeof AriaTabPanel> {
+}
+/**
+ * Content panel associated with a specific {@link Tab}, conforming to
+ * [Material 3 Tabs](https://m3.material.io/components/tabs/overview).
+ *
+ * Extends React Aria Components `TabPanel` with Material 3 styling and smooth
+ * fade entrance animations when the tab becomes active.
+ *
+ * @example
+ * ```tsx
+ * import { TabPanel } from "@adgytec/web-ui-components";
+ *
+ * export function PanelExample() {
+ *     return (
+ *         <TabPanel id="profile">
+ *             <h3>User Profile</h3>
+ *             <p>Manage user profile information here.</p>
+ *         </TabPanel>
+ *     );
+ * }
+ * ```
+ */
+export declare const TabPanel: React.FC<TabPanelProps>;

package/dist/components/Tabs/TabPanels/TabPanels.d.ts

@@ -1,2 +1,29 @@
 import { TabPanels as AriaTabPanels } from 'react-aria-components';
-export declare const TabPanels: <T extends object>({ className, ...props }: React.ComponentPropsWithRef<typeof AriaTabPanels<T>>) => import("react").JSX.Element;
+/**
+ * Props for the {@link TabPanels} component.
+ * Extends React Aria Components `TabPanels` props.
+ */
+export interface TabPanelsProps<T extends object = object> extends React.ComponentPropsWithRef<typeof AriaTabPanels<T>> {
+}
+/**
+ * Container for {@link TabPanel} elements in a {@link Tabs} structure, conforming to
+ * [Material 3 Tabs](https://m3.material.io/components/tabs/overview).
+ *
+ * Extends React Aria Components `TabPanels` and provides coordinated smooth height transitions
+ * when switching between tab panels.
+ *
+ * @example
+ * ```tsx
+ * import { TabPanel, TabPanels } from "@adgytec/web-ui-components";
+ *
+ * export function PanelsExample() {
+ *     return (
+ *         <TabPanels>
+ *             <TabPanel id="account">Account settings content</TabPanel>
+ *             <TabPanel id="security">Security settings content</TabPanel>
+ *         </TabPanels>
+ *     );
+ * }
+ * ```
+ */
+export declare const TabPanels: <T extends object>({ className, ...props }: TabPanelsProps<T>) => import('react').JSX.Element;

package/dist/components/Tabs/Tabs/Tabs.d.ts

@@ -1,2 +1,44 @@
 import { Tabs as AriaTabs } from 'react-aria-components';
-export declare const Tabs: React.FC<React.ComponentPropsWithRef<typeof AriaTabs>>;
+/**
+ * Props for the {@link Tabs} component.
+ * Extends React Aria Components `Tabs` props.
+ */
+export interface TabsProps extends React.ComponentPropsWithRef<typeof AriaTabs> {
+}
+/**
+ * Main container for organizing content into high-level categories based on
+ * [Material 3 Tabs](https://m3.material.io/components/tabs/overview).
+ *
+ * Extends React Aria Components `Tabs` to manage tab selection state, keyboard navigation,
+ * and layout orientation (horizontal or vertical).
+ *
+ * @example
+ * ```tsx
+ * import {
+ *     Tab,
+ *     TabList,
+ *     TabPanel,
+ *     TabPanels,
+ *     Tabs,
+ * } from "@adgytec/web-ui-components";
+ * import { Home, Settings, User } from "lucide-react";
+ *
+ * export function Example() {
+ *     return (
+ *         <Tabs defaultSelectedKey="home">
+ *             <TabList aria-label="Navigation">
+ *                 <Tab id="home" label="Home" icon={Home} />
+ *                 <Tab id="profile" label="Profile" icon={User} />
+ *                 <Tab id="settings" label="Settings" icon={Settings} />
+ *             </TabList>
+ *             <TabPanels>
+ *                 <TabPanel id="home">Home content goes here.</TabPanel>
+ *                 <TabPanel id="profile">Profile content goes here.</TabPanel>
+ *                 <TabPanel id="settings">Settings content goes here.</TabPanel>
+ *             </TabPanels>
+ *         </Tabs>
+ *     );
+ * }
+ * ```
+ */
+export declare const Tabs: React.FC<TabsProps>;

package/dist/components/Tag/Tag.d.ts

@@ -1,2 +1,39 @@
 import { TagProps } from './types';
+/**
+ * Compact interactive element representing an attribute, entity, or action, based on
+ * [Material 3 Chips](https://m3.material.io/components/chips/overview).
+ *
+ * Extends React Aria Components `Tag` with Material 3 styling and interactive behaviors:
+ * - Renders a text `label` using `typography.labelLarge`.
+ * - Supports an optional leading `icon` or circular `avatar`.
+ * - When selected, dynamically displays a checkmark icon unless an avatar is present.
+ * - Supports removable tags by rendering a built-in remove icon button (`X`) when `allowsRemoving` is true.
+ * - Interactive ripple feedback via {@link Splash}.
+ *
+ * Configurable CSS tokens:
+ * - `--md-chip-background-color`: Background color of the tag (`var(--md-sys-color-surface-container-low)`).
+ * - `--md-chip-selected-background-color`: Background color when selected (`var(--md-sys-color-secondary-container)`).
+ * - `--md-chip-icon-color`: Color of the leading icon (`var(--md-sys-color-primary)`).
+ * - `--md-chip-selected-icon-color`: Color of the icon when selected (`var(--md-sys-color-on-secondary-container)`).
+ * - `--md-chip-label-color`: Text color of the label (`var(--md-sys-color-on-surface-variant)`).
+ * - `--md-chip-selected-label-color`: Text color when selected (`var(--md-sys-color-on-secondary-container)`).
+ *
+ * @example
+ * ```tsx
+ * import { Tag } from "@adgytec/web-ui-components";
+ * import { TagGroup, TagList } from "react-aria-components";
+ * import { PlaneTakeoff, ShoppingCart } from "lucide-react";
+ *
+ * export function Example() {
+ *     return (
+ *         <TagGroup aria-label="Categories" selectionMode="multiple">
+ *             <TagList>
+ *                 <Tag id="travel" label="Travel" icon={PlaneTakeoff} />
+ *                 <Tag id="shopping" label="Shopping" icon={ShoppingCart} />
+ *             </TagList>
+ *         </TagGroup>
+ *     );
+ * }
+ * ```
+ */
 export declare const Tag: React.FC<TagProps>;

package/dist/components/Tag/core.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Default icon size (in pixels) rendered inside a {@link Tag}.
+ */
 export declare const TagIconSize = 18;
+/**
+ * Diameter (in pixels) for avatar elements rendered inside a {@link Tag}.
+ */
 export declare const AvatarSize = 24;

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

@@ -1,8 +1,54 @@
 import { LucideIcon } from 'lucide-react';
-import { ReactElement } from 'react';
+import { ReactNode } from 'react';
 import { Tag } from 'react-aria-components';
+/**
+ * Props for the {@link Tag} component.
+ * Extends React Aria Components `Tag` props (omitting raw `children` in favor of structured `label`, `icon`, and `avatar`).
+ *
+ * Configurable CSS tokens:
+ * - `--md-chip-background-color`: Background color of the tag in its default state (`var(--md-sys-color-surface-container-low)`).
+ * - `--md-chip-selected-background-color`: Background color of the tag when selected (`var(--md-sys-color-secondary-container)`).
+ * - `--md-chip-icon-color`: Color of the icon in its default state (`var(--md-sys-color-primary)`).
+ * - `--md-chip-selected-icon-color`: Color of the icon when selected (`var(--md-sys-color-on-secondary-container)`).
+ * - `--md-chip-label-color`: Color of the label text in its default state (`var(--md-sys-color-on-surface-variant)`).
+ * - `--md-chip-selected-label-color`: Color of the label text when selected (`var(--md-sys-color-on-secondary-container)`).
+ *
+ * @example
+ * ```tsx
+ * import { Tag } from "@adgytec/web-ui-components";
+ * import { User } from "lucide-react";
+ *
+ * export function Example() {
+ *     return (
+ *         <Tag
+ *             id="user-profile"
+ *             label="Profile"
+ *             icon={User}
+ *         />
+ *     );
+ * }
+ * ```
+ */
 export interface TagProps extends Omit<React.ComponentPropsWithRef<typeof Tag>, "children"> {
+    /**
+     * Text content displayed within the tag.
+     */
     label: string;
+    /**
+     * Optional icon displayed at the start of the tag.
+     * When the tag is selected in a selection group, this icon is automatically replaced by a checkmark.
+     * If both `icon` and `avatar` are provided, `avatar` takes precedence.
+     */
     icon?: LucideIcon;
-    avatar?: ReactElement;
+    /**
+     * Optional avatar element displayed at the start of the tag.
+     * Rendered inside a circular constraint container (`24px`).
+     * Takes precedence over `icon` when both are provided.
+     *
+     * @example
+     * ```tsx
+     * avatar={<img src="/avatar.png" alt="Jane" />}
+     * ```
+     */
+    avatar?: ReactNode;
 }

package/dist/components/ThemeSelector/ThemeItem.d.ts

@@ -1,8 +1,52 @@
 import { ReactNode } from 'react';
-export declare const ThemeItem: ({ heading, description, children, className, useInline, }: {
+/**
+ * Props for the {@link ThemeItem} component.
+ */
+export interface ThemeItemProps {
+    /**
+     * Section title heading text.
+     */
     heading: string;
+    /**
+     * Optional explanatory text describing the setting.
+     */
     description?: string;
+    /**
+     * Interactive control element(s) (e.g. connected button groups or switches) associated with the item.
+     */
     children?: ReactNode;
+    /**
+     * Optional custom CSS class name applied to the container.
+     */
     className?: string;
+    /**
+     * Whether to render inline `span` elements instead of block `div` elements.
+     * Useful when nesting inside a label or interactive component like `Switch`.
+     *
+     * @default false
+     */
     useInline?: boolean;
-}) => import("react").JSX.Element;
+}
+/**
+ * Layout helper component for a single setting item within {@link ThemeSelector}.
+ *
+ * Renders a styled heading (`typography.titleMedium`), an optional description (`typography.bodyMedium`),
+ * and the child controls. Supports both block rendering and inline `span` rendering.
+ *
+ * @example
+ * ```tsx
+ * import { ThemeItem } from "@adgytec/web-ui-components";
+ *
+ * export function SettingRow() {
+ *     return (
+ *         <ThemeItem
+ *             heading="Appearance"
+ *             description="Select your preferred color mode."
+ *         >
+ *             <Controls />
+ *         </ThemeItem>
+ *     );
+ * }
+ * ```
+ */
+export declare const ThemeItem: React.FC<ThemeItemProps>;