@adgytec/adgytec-web-ui-components 2.3.0 → 2.4.0

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/index.js

@@ -1,2 +1 @@
-import { n as e, t } from "../../chunks/useSplash";
-export { e as Splash, t as useSplash };
+export { n as Splash, t as useSplash } from "../../chunks/useSplash";

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/Tab/index.js

@@ -1,2 +1 @@
-import { t as e } from "../../../chunks/Tab";
-export { e as Tab };
+export { t as Tab } from "../../../chunks/Tab";

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/TabList/index.js

@@ -1,2 +1 @@
-import { t as e } from "../../../chunks/TabList";
-export { e as TabList };
+export { t as TabList } from "../../../chunks/TabList";

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/TabPanel/index.js

@@ -1,2 +1 @@
-import { t as e } from "../../../chunks/TabPanel";
-export { e as TabPanel };
+export { t as TabPanel } from "../../../chunks/TabPanel";

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/TabPanels/index.js

@@ -1,2 +1 @@
-import { t as e } from "../../../chunks/TabPanels";
-export { e as TabPanels };
+export { t as TabPanels } from "../../../chunks/TabPanels";

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/Tabs/Tabs/index.js

@@ -1,2 +1 @@
-import { t as e } from "../../../chunks/Tabs";
-export { e as Tabs };
+export { t as Tabs } from "../../../chunks/Tabs";

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/index.js

@@ -1,2 +1 @@
-import { n as e, r as t, t as n } from "../../chunks/Tag";
-export { e as AvatarSize, n as Tag, t as TagIconSize };
+export { n as AvatarSize, t as Tag, r as TagIconSize } from "../../chunks/Tag";

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,58 @@
 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;
+    /**
+     * Whether the setting item is disabled (visually dimmed and non-interactive).
+     *
+     * @default false
+     */
+    isDisabled?: boolean;
+}
+/**
+ * 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, as well as disabled styling.
+ *
+ * @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>;

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

@@ -1,4 +1,31 @@
 import { ReactNode } from 'react';
-export declare const ThemeProvider: ({ children }: {
+/**
+ * Props for the {@link ThemeProvider} component.
+ */
+export interface ThemeProviderProps {
+    /**
+     * Application content to be rendered inside the provider.
+     */
     children?: ReactNode;
-}) => ReactNode;
+}
+/**
+ * Top-level provider component that synchronizes the application root with the current theme settings.
+ *
+ * Subscribes to the theme state via {@link useTheme} (mode, dark mode calculation,
+ * contrast level, and monochrome setting) and dynamically assigns the computed theme
+ * string to the `data-theme` attribute of `document.documentElement`.
+ *
+ * @example
+ * ```tsx
+ * import { ThemeProvider } from "@adgytec/web-ui-components";
+ *
+ * export function App() {
+ *     return (
+ *         <ThemeProvider>
+ *             <MainContent />
+ *         </ThemeProvider>
+ *     );
+ * }
+ * ```
+ */
+export declare const ThemeProvider: React.FC<ThemeProviderProps>;

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

@@ -1,2 +1,26 @@
 import { ThemeSelectorProps } from './types';
+/**
+ * Settings UI component for managing application theme appearance.
+ *
+ * Provides user controls for:
+ * - **Theme Mode**: Connected button group with `"System"`, `"Light"`, and `"Dark"` options, featuring dedicated icons.
+ * - **Theme Contrast**: Connected button group with `"Standard"`, `"Medium"`, and `"High"` options (disabled when monochrome is active).
+ * - **Monochrome Mode**: An interactive {@link ListItem} with {@link Switch} and {@link ListIcon} to toggle neutral grayscale styling.
+ *
+ * Directly connects to {@link useTheme} to read and update theme settings, which are
+ * persisted to local storage and applied to `document.documentElement` by {@link ThemeProvider}.
+ *
+ * @example
+ * ```tsx
+ * import { ThemeProvider, ThemeSelector } from "@adgytec/web-ui-components";
+ *
+ * export function SettingsMenu() {
+ *     return (
+ *         <ThemeProvider>
+ *             <ThemeSelector />
+ *         </ThemeProvider>
+ *     );
+ * }
+ * ```
+ */
 export declare const ThemeSelector: React.FC<ThemeSelectorProps>;