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

package/dist/utils/scroll/scroll.d.ts

@@ -1,10 +1,73 @@
-export declare function getScrollProgress({ scrollHeight, scrollTop, clientHeight, }: {
+/**
+ * Options for calculating normalized scroll progress.
+ */
+export interface ScrollProgressOptions {
+    /**
+     * Current vertical scroll position of the container in pixels (`element.scrollTop`).
+     */
     scrollTop: number;
+    /**
+     * Total scrollable height of the container content in pixels (`element.scrollHeight`).
+     */
     scrollHeight: number;
+    /**
+     * Inner height of the container viewport in pixels (`element.clientHeight`).
+     */
     clientHeight: number;
-}): number;
-export declare function getScrollTopFromProgress({ scrollHeight, progress, clientHeight, }: {
+}
+/**
+ * Calculates normalized vertical scroll progress as a ratio between `0` (top) and `1` (bottom).
+ *
+ * Automatically clamped between `0` and `1` to prevent out-of-bounds values caused by
+ * elastic over-scrolling / rubber-banding on mobile (iOS/Safari) and trackpads.
+ * If the container content is not scrollable (i.e. `scrollHeight <= clientHeight`), returns `0`.
+ *
+ * @param options - Container dimension and scroll position values.
+ * @returns Normalized scroll progress clamped between `0` and `1`.
+ *
+ * @example
+ * ```ts
+ * const progress = getScrollProgress({
+ *     scrollTop: element.scrollTop,
+ *     scrollHeight: element.scrollHeight,
+ *     clientHeight: element.clientHeight,
+ * });
+ * ```
+ */
+export declare function getScrollProgress({ scrollHeight, scrollTop, clientHeight, }: ScrollProgressOptions): number;
+/**
+ * Options for calculating vertical scroll position from a normalized progress ratio.
+ */
+export interface ScrollTopFromProgressOptions {
+    /**
+     * Normalized scroll progress ratio between `0` and `1`.
+     */
     progress: number;
+    /**
+     * Total scrollable height of the container content in pixels (`element.scrollHeight`).
+     */
     scrollHeight: number;
+    /**
+     * Inner height of the container viewport in pixels (`element.clientHeight`).
+     */
     clientHeight: number;
-}): number;
+}
+/**
+ * Calculates the target `scrollTop` in pixels from a normalized scroll progress ratio (`0` to `1`).
+ *
+ * Commonly used to restore saved scroll positions across renders, layout changes, or navigation state updates.
+ * Guarantees a non-negative return value (`>= 0`), and clamps input progress to `[0, 1]`.
+ *
+ * @param options - Container dimensions and normalized progress value.
+ * @returns The vertical scroll offset in pixels (`scrollTop`), guaranteed to be `>= 0`.
+ *
+ * @example
+ * ```ts
+ * element.scrollTop = getScrollTopFromProgress({
+ *     progress: 0.5,
+ *     scrollHeight: element.scrollHeight,
+ *     clientHeight: element.clientHeight,
+ * });
+ * ```
+ */
+export declare function getScrollTopFromProgress({ scrollHeight, progress, clientHeight, }: ScrollTopFromProgressOptions): number;

package/dist/utils/tapTarget/tapTarget.d.ts

@@ -1,2 +1,59 @@
+/**
+ * CSS class name that ensures an element meets the minimum accessible touch target size (48x48px / 48dp)
+ * using an invisible centered `::after` pseudo-element.
+ *
+ * Implements WCAG Target Size recommendations (48x48px minimum touch area) for small or compact
+ * interactive elements without affecting the visual layout or dimensions of the element itself.
+ *
+ * Automatically collapses to `0px` when the element has the `[data-disabled]` attribute.
+ *
+ * Extensively used across interactive controls including buttons, icon buttons, checkboxes,
+ * radio buttons, switches, and avatar triggers.
+ *
+ * @remarks
+ * If the element or an ancestor container applies `overflow: hidden` or `contain: paint`,
+ * the pseudo-element's expanded hit area will be clipped to that boundary.
+ *
+ * @example
+ * ```tsx
+ * import { TapTarget } from "@/utils";
+ * import clsx from "clsx";
+ *
+ * function CustomIconButton({ icon: Icon, onClick }) {
+ *     return (
+ *         <button type="button" className={clsx("icon-button", TapTarget)} onClick={onClick}>
+ *             <Icon />
+ *         </button>
+ *     );
+ * }
+ * ```
+ */
 export declare const TapTarget: string;
+/**
+ * CSS class name that ensures an element meets the minimum accessible touch target size (48x48px / 48dp)
+ * using an invisible centered `::before` pseudo-element.
+ *
+ * Alternative to {@link TapTarget} for components where the `::after` pseudo-element is already reserved
+ * or in use (such as for focus rings, badges, or ripples).
+ *
+ * Automatically collapses to `0px` when the element has the `[data-disabled]` attribute.
+ *
+ * @remarks
+ * If the element or an ancestor container applies `overflow: hidden` or `contain: paint`,
+ * the pseudo-element's expanded hit area will be clipped to that boundary.
+ *
+ * @example
+ * ```tsx
+ * import { TapTargetBefore } from "@/utils";
+ * import clsx from "clsx";
+ *
+ * function CustomAction({ onClick, children }) {
+ *     return (
+ *         <button type="button" className={clsx("custom-action", TapTargetBefore)} onClick={onClick}>
+ *             {children}
+ *         </button>
+ *     );
+ * }
+ * ```
+ */
 export declare const TapTargetBefore: string;

package/dist/utils/theme/build.d.ts

@@ -1,2 +1,26 @@
 import { ThemeBuildOptions } from './types';
+/**
+ * Generates the theme string suffix or identifier based on current theme settings.
+ *
+ * This identifier corresponds to the theme definition classes and data attributes
+ * (such as `data-theme="..."`) applied to the root element (`document.documentElement` or body).
+ *
+ * - Monochrome modes produce `"monochrome-dark"` or `"monochrome-light"`.
+ * - Standard contrast modes produce `"dark"` or `"light"`.
+ * - Elevated contrast modes produce `"dark-medium-contrast"`, `"dark-high-contrast"`,
+ *   `"light-medium-contrast"`, or `"light-high-contrast"`.
+ *
+ * @param options - Theme configuration flags (dark mode, monochrome, contrast).
+ * @returns Formatted theme string (e.g. `"dark"`, `"light-high-contrast"`, `"monochrome-dark"`).
+ *
+ * @example
+ * ```ts
+ * const themeString = buildThemeString({
+ *     isDarkMode: true,
+ *     isMonochrome: false,
+ *     contrast: "high",
+ * });
+ * // returns "dark-high-contrast"
+ * ```
+ */
 export declare const buildThemeString: ({ isDarkMode, isMonochrome, contrast, }: ThemeBuildOptions) => string;

package/dist/utils/theme/types.d.ts

@@ -1,25 +1,95 @@
+/**
+ * Supported theme modes:
+ * - `"system"`: Follows the operating system / browser `(prefers-color-scheme: dark)` preference.
+ * - `"dark"`: Forces dark theme mode.
+ * - `"light"`: Forces light theme mode.
+ */
 export type ThemeMode = "system" | "dark" | "light";
+/**
+ * Supported theme contrast levels:
+ * - `"standard"`: Default Material You contrast level.
+ * - `"medium"`: Increased contrast for improved legibility.
+ * - `"high"`: Highest contrast level for maximum accessibility.
+ */
 export type ThemeContrast = "standard" | "medium" | "high";
+/**
+ * Configuration options for the {@link useTheme} hook.
+ */
 export type ThemeOptions = {
+    /**
+     * Initial theme mode. Defaults to `"system"`.
+     */
     defaultThemeMode?: ThemeMode;
+    /**
+     * Initial contrast level. Defaults to `"standard"`.
+     */
     defaultContrast?: ThemeContrast;
+    /**
+     * Whether monochrome mode is initially enabled. Defaults to `false`.
+     */
     isMonochrome?: boolean;
+    /**
+     * Key used to persist theme settings in `localStorage`. Defaults to `"application-theme"`.
+     */
     localStorageKey?: string;
+    /**
+     * Whether to initialize state with the stored `localStorage` / media query value during hydration. Defaults to `true`.
+     */
     initializeWithValue?: boolean;
 };
+/**
+ * Persisted theme state stored in `localStorage`.
+ */
 export type ThemeStorage = {
+    /**
+     * Configured theme mode (`"system"`, `"dark"`, or `"light"`).
+     */
     mode: ThemeMode;
+    /**
+     * Configured contrast level (`"standard"`, `"medium"`, or `"high"`).
+     */
     contrast: ThemeContrast;
+    /**
+     * Whether monochrome mode is enabled.
+     */
     isMonochrome: boolean;
 };
+/**
+ * Object returned by the {@link useTheme} hook providing theme state and updater functions.
+ */
 export type ThemeReturn = ThemeStorage & {
+    /**
+     * Resolved boolean indicating whether dark mode is currently active
+     * (evaluates the OS preference when `mode === "system"`).
+     */
     isDarkMode: boolean;
+    /**
+     * Updates the theme mode (`"system"`, `"dark"`, or `"light"`).
+     */
     setMode: (mode: ThemeMode) => void;
+    /**
+     * Updates the contrast level (`"standard"`, `"medium"`, or `"high"`).
+     */
     setContrast: (contrast: ThemeContrast) => void;
+    /**
+     * Toggles monochrome mode on or off.
+     */
     setMonochrome: (isMonochrome: boolean) => void;
 };
+/**
+ * Options passed to {@link buildThemeString} to generate the theme identifier.
+ */
 export type ThemeBuildOptions = {
+    /**
+     * Contrast level (`"standard"`, `"medium"`, or `"high"`).
+     */
     contrast: ThemeContrast;
+    /**
+     * Whether dark mode is active.
+     */
     isDarkMode: boolean;
+    /**
+     * Whether monochrome mode is active.
+     */
     isMonochrome: boolean;
 };

package/dist/utils/theme/useTheme.d.ts

@@ -1,2 +1,42 @@
 import { ThemeOptions, ThemeReturn } from './types';
+/**
+ * React hook that manages the application theme state with `localStorage` persistence
+ * and automatic synchronization with system preferences.
+ *
+ * Tracks theme mode (`"system"`, `"dark"`, `"light"`), contrast level (`"standard"`,
+ * `"medium"`, `"high"`), and monochrome mode. When `mode` is set to `"system"`,
+ * `isDarkMode` dynamically listens to the OS `(prefers-color-scheme: dark)` media query.
+ *
+ * All setter callbacks (`setMode`, `setContrast`, `setMonochrome`) are referentially stable
+ * via `useCallback`.
+ *
+ * @param options - Configuration options for initial defaults and storage key.
+ * @returns Current theme state and updater functions.
+ *
+ * @example
+ * ```tsx
+ * import { useTheme, buildThemeString } from '@adgytec/web-ui-components';
+ * import { useEffect } from 'react';
+ *
+ * function App() {
+ *     const theme = useTheme();
+ *
+ *     useEffect(() => {
+ *         const themeString = buildThemeString({
+ *             isDarkMode: theme.isDarkMode,
+ *             isMonochrome: theme.isMonochrome,
+ *             contrast: theme.contrast,
+ *         });
+ *         document.documentElement.setAttribute('data-theme', themeString);
+ *     }, [theme.isDarkMode, theme.isMonochrome, theme.contrast]);
+ *
+ *     return (
+ *         <div>
+ *             <button onClick={() => theme.setMode('dark')}>Dark Mode</button>
+ *             <button onClick={() => theme.setContrast('high')}>High Contrast</button>
+ *         </div>
+ *     );
+ * }
+ * ```
+ */
 export declare function useTheme({ defaultThemeMode, defaultContrast, isMonochrome, localStorageKey, initializeWithValue, }?: ThemeOptions): ThemeReturn;

package/dist/utils/typography/base.d.ts

@@ -1,33 +1,101 @@
+/**
+ * Standard typography variants based on Material Design 3 guidelines.
+ *
+ * Maps typography roles to pre-defined CSS class names configuring font-family,
+ * font-size, line-height, letter-spacing, and font-weight.
+ *
+ * Each role is available in two forms:
+ * - **Standard**: The default type scale definition.
+ * - **Emphasized**: A heavier font-weight variant (e.g., medium/semi-bold/bold) for emphasis.
+ *
+ * ### Categories:
+ * - **Display**: Large, expressive short text (e.g. hero stats, numbers).
+ * - **Headline**: High-emphasis titles for main screens or sections.
+ * - **Title**: Medium-emphasis headers for cards, dialogs, and list items.
+ * - **Body**: Longer passages, descriptive copy, and form inputs.
+ * - **Label**: Compact utility styles for buttons, chips, tabs, and form field captions.
+ *
+ * @example
+ * ```tsx
+ * import { typography } from '@adgytec/web-ui-components';
+ * import clsx from 'clsx';
+ *
+ * function Heading() {
+ *     return (
+ *         <h1 className={clsx(typography.headlineLarge)}>
+ *             Dashboard Overview
+ *         </h1>
+ *     );
+ * }
+ * ```
+ */
 export declare const typography: {
+    /** Large display style (57px) for high-impact, short hero text. */
     readonly displayLarge: "typography-display-large";
+    /** Emphasized (heavier weight) variant of `displayLarge`. */
     readonly displayLargeEmphasized: "typography-display-large-emphasized";
+    /** Medium display style (45px) for prominent short text. */
     readonly displayMedium: "typography-display-medium";
+    /** Emphasized (heavier weight) variant of `displayMedium`. */
     readonly displayMediumEmphasized: "typography-display-medium-emphasized";
+    /** Small display style (36px) for compact hero headings. */
     readonly displaySmall: "typography-display-small";
+    /** Emphasized (heavier weight) variant of `displaySmall`. */
     readonly displaySmallEmphasized: "typography-display-small-emphasized";
+    /** Large headline style (32px) for primary screen and section titles. */
     readonly headlineLarge: "typography-headline-large";
+    /** Emphasized (heavier weight) variant of `headlineLarge`. */
     readonly headlineLargeEmphasized: "typography-headline-large-emphasized";
+    /** Medium headline style (28px) for secondary screen titles. */
     readonly headlineMedium: "typography-headline-medium";
+    /** Emphasized (heavier weight) variant of `headlineMedium`. */
     readonly headlineMediumEmphasized: "typography-headline-medium-emphasized";
+    /** Small headline style (24px) for tertiary screen titles. */
     readonly headlineSmall: "typography-headline-small";
+    /** Emphasized (heavier weight) variant of `headlineSmall`. */
     readonly headlineSmallEmphasized: "typography-headline-small-emphasized";
+    /** Large title style (22px) for top-level card titles, app bars, and dialog headers. */
     readonly titleLarge: "typography-title-large";
+    /** Emphasized (heavier weight) variant of `titleLarge`. */
     readonly titleLargeEmphasized: "typography-title-large-emphasized";
+    /** Medium title style (16px) for section headers and prominent list items. */
     readonly titleMedium: "typography-title-medium";
+    /** Emphasized (heavier weight) variant of `titleMedium`. */
     readonly titleMediumEmphasized: "typography-title-medium-emphasized";
+    /** Small title style (14px) for compact card headers, subheads, and tabs. */
     readonly titleSmall: "typography-title-small";
+    /** Emphasized (heavier weight) variant of `titleSmall`. */
     readonly titleSmallEmphasized: "typography-title-small-emphasized";
+    /** Large body style (16px) for primary body text, article paragraphs, and form inputs. */
     readonly bodyLarge: "typography-body-large";
+    /** Emphasized (heavier weight) variant of `bodyLarge`. */
     readonly bodyLargeEmphasized: "typography-body-large-emphasized";
+    /** Medium body style (14px) for secondary descriptions and supporting text. */
     readonly bodyMedium: "typography-body-medium";
+    /** Emphasized (heavier weight) variant of `bodyMedium`. */
     readonly bodyMediumEmphasized: "typography-body-medium-emphasized";
+    /** Small body style (12px) for compact descriptions, disclaimers, and legal text. */
     readonly bodySmall: "typography-body-small";
+    /** Emphasized (heavier weight) variant of `bodySmall`. */
     readonly bodySmallEmphasized: "typography-body-small-emphasized";
+    /** Large label style (14px) for buttons, navigation items, chips, and field labels. */
     readonly labelLarge: "typography-label-large";
+    /** Emphasized (heavier weight) variant of `labelLarge`. */
     readonly labelLargeEmphasized: "typography-label-large-emphasized";
+    /** Medium label style (12px) for helper text, tooltips, tags, and character counts. */
     readonly labelMedium: "typography-label-medium";
+    /** Emphasized (heavier weight) variant of `labelMedium`. */
     readonly labelMediumEmphasized: "typography-label-medium-emphasized";
+    /** Small label style (11px) for overline text, timestamps, and compact metadata. */
     readonly labelSmall: "typography-label-small";
+    /** Emphasized (heavier weight) variant of `labelSmall`. */
     readonly labelSmallEmphasized: "typography-label-small-emphasized";
 };
+/**
+ * Union of all standard typography CSS class name values in {@link typography}.
+ */
 export type TypographyVariant = (typeof typography)[keyof typeof typography];
+/**
+ * Union of all standard typography role keys in {@link typography}.
+ */
+export type TypographyKey = keyof typeof typography;

package/dist/utils/typography/core.d.ts

@@ -1,3 +1,19 @@
 import { TypographyVariant } from './base';
 import { FluidTypographyVariant } from './fluid';
+/**
+ * Universal typography type representing any valid typography CSS class name in the design system.
+ *
+ * Combines both standard Material Design 3 variants ({@link TypographyVariant}) and responsive fluid variants ({@link FluidTypographyVariant}).
+ * Commonly used across component props that allow customizable typography styling (e.g. `labelTypography`, `titleTypography`, `panelTypography`).
+ *
+ * @example
+ * ```tsx
+ * import type { Typography } from '@/utils';
+ *
+ * interface CustomHeaderProps {
+ *     title: string;
+ *     titleTypography?: Typography;
+ * }
+ * ```
+ */
 export type Typography = TypographyVariant | FluidTypographyVariant;

package/dist/utils/typography/fluid.d.ts

@@ -1,9 +1,45 @@
+/**
+ * Fluid typography variants that scale smoothly between minimum and maximum viewport sizes.
+ *
+ * Implemented using CSS `clamp()` to dynamically interpolate font size and line height
+ * according to screen width without jarring breakpoint jumps.
+ *
+ * Available for Display and Headline roles where responsive scaling produces the most
+ * impactful visual balance across mobile, tablet, and desktop viewports.
+ *
+ * @example
+ * ```tsx
+ * import { fluidTypography } from '@adgytec/web-ui-components';
+ * import clsx from 'clsx';
+ *
+ * function HeroBanner() {
+ *     return (
+ *         <h1 className={clsx(fluidTypography.displayLarge)}>
+ *             Fluid Responsive Title
+ *         </h1>
+ *     );
+ * }
+ * ```
+ */
 export declare const fluidTypography: {
+    /** Large fluid display style smoothly scaling with viewport width. */
     readonly displayLarge: "typography-display-large-fluid";
+    /** Medium fluid display style smoothly scaling with viewport width. */
     readonly displayMedium: "typography-display-medium-fluid";
+    /** Small fluid display style smoothly scaling with viewport width. */
     readonly displaySmall: "typography-display-small-fluid";
+    /** Large fluid headline style smoothly scaling with viewport width. */
     readonly headlineLarge: "typography-headline-large-fluid";
+    /** Medium fluid headline style smoothly scaling with viewport width. */
     readonly headlineMedium: "typography-headline-medium-fluid";
+    /** Small fluid headline style smoothly scaling with viewport width. */
     readonly headlineSmall: "typography-headline-small-fluid";
 };
+/**
+ * Union of all fluid typography CSS class name values in {@link fluidTypography}.
+ */
 export type FluidTypographyVariant = (typeof fluidTypography)[keyof typeof fluidTypography];
+/**
+ * Union of all fluid typography role keys in {@link fluidTypography}.
+ */
+export type FluidTypographyKey = keyof typeof fluidTypography;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@adgytec/adgytec-web-ui-components",
     "private": false,
-    "version": "2.3.0",
+    "version": "2.3.1",
     "type": "module",
     "sideEffects": [
         "**/*.css"
@@ -48,39 +48,37 @@
         "react-aria-components": ">=1.17.0",
         "react-dom": ">=19.2.3",
         "react-transition-group": "^4.4.5",
-        "usehooks-ts": ">=3.1.1",
-        "zod": ">=4.3.5"
+        "usehooks-ts": ">=3.1.1"
     },
     "devDependencies": {
-        "@biomejs/biome": "^2.5.2",
-        "@internationalized/date": "^3.12.2",
-        "@rolldown/plugin-babel": "^0.2.3",
-        "@types/node": "^26.1.0",
-        "@types/react": "^19.2.17",
-        "@types/react-dom": "^19.2.3",
+        "@biomejs/biome": "^2.5.15",
+        "@internationalized/date": "^3.12.4",
+        "@rolldown/plugin-babel": "^0.2.4",
+        "@types/node": "^26.6.4",
+        "@types/react": "^19.3.0",
+        "@types/react-dom": "^19.3.0",
         "@types/react-transition-group": "^4.4.12",
-        "@vitejs/plugin-react": "^6.0.3",
-        "autoprefixer": "^10.5.2",
+        "@typescript/typescript6": "^6.0.2",
+        "@vitejs/plugin-react": "^6.1.1",
+        "autoprefixer": "^10.6.1",
         "babel-plugin-react-compiler": "^1.0.0",
         "clsx": "^2.1.1",
         "glob": "^13.0.6",
-        "globals": "^17.7.0",
-        "lightningcss": "^1.32.0",
-        "lucide-react": "^1.23.0",
-        "postcss-nesting": "^14.0.0",
-        "react": "^19.2.7",
-        "react-aria": "^3.50.0",
-        "react-aria-components": "^1.19.0",
-        "react-dom": "^19.2.7",
+        "globals": "^17.13.0",
+        "lightningcss": "^1.33.0",
+        "lucide-react": "^1.51.0",
+        "postcss-nesting": "^14.0.2",
+        "react": "^19.3.0",
+        "react-aria": "^3.52.1",
+        "react-aria-components": "^1.21.1",
+        "react-dom": "^19.3.0",
         "react-transition-group": "^4.4.5",
         "sonda": "^0.14.0",
-        "typescript": "~6.0.3",
+        "typescript": "~7.0.2",
+        "unplugin-dts": "^1.1.2",
         "usehooks-ts": "^3.1.1",
-        "vite": "^8.1.3",
-        "vite-plugin-dts": "^5.0.3",
-        "vite-plugin-lib-inject-css": "^2.2.2",
-        "vite-plugin-static-copy": "^4.1.1",
-        "zod": "^4.4.3"
+        "vite": "^8.3.2",
+        "vite-plugin-lib-inject-css": "^2.2.2"
     },
     "author": {
         "name": "Adgytec",