@udixio/ui-react 2.9.8 → 2.9.10

package/dist/lib/interfaces/fab.interface.d.ts

@@ -1,11 +1,12 @@
 import { ActionOrLink } from '../utils/component';
 import { Transition } from 'motion';
 import { Icon } from '../icon';
+import { ReactNode } from 'react';
 export type FabVariant = 'primary' | 'secondary' | 'tertiary' | 'primaryContainer' | 'secondaryContainer' | 'tertiaryContainer';
 type Props = {
     variant?: FabVariant;
     label?: string;
-    children?: string;
+    children?: ReactNode;
     icon: Icon;
     size?: 'small' | 'medium' | 'large';
     extended?: boolean;

package/dist/lib/interfaces/fab.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fab.interface.d.ts","sourceRoot":"","sources":["../../../src/lib/interfaces/fab.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,WAAW,GACX,UAAU,GACV,kBAAkB,GAClB,oBAAoB,GACpB,mBAAmB,CAAC;AACxB,KAAK,KAAK,GAAG;IACX,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9D,MAAM,MAAM,YAAY,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG;IAC/C,QAAQ,EAAE,QAAQ,CAAC;CACpB,CAAC"}
+{"version":3,"file":"fab.interface.d.ts","sourceRoot":"","sources":["../../../src/lib/interfaces/fab.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAElC,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,WAAW,GACX,UAAU,GACV,kBAAkB,GAClB,oBAAoB,GACpB,mBAAmB,CAAC;AACxB,KAAK,KAAK,GAAG;IACX,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9D,MAAM,MAAM,YAAY,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG;IAC/C,QAAQ,EAAE,QAAQ,CAAC;CACpB,CAAC"}

package/dist/lib/interfaces/tooltip.interface.d.ts

@@ -8,11 +8,26 @@ export type ToolTipInterface<T extends HTMLElement = any> = {
     props: {
         variant?: 'plain' | 'rich';
         title?: string;
-        text: string;
+        /** Supporting text for the tooltip. Optional when using `content` prop. */
+        text?: string;
+        /** Custom content slot that replaces title/text/buttons when provided */
+        content?: ReactNode;
         buttons?: ReactProps<ButtonInterface> | ReactProps<ButtonInterface>[];
         position?: 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
         trigger?: Trigger | Trigger[];
         transition?: Transition;
+        /** Delay in milliseconds before showing the tooltip. Default: 400ms */
+        openDelay?: number;
+        /** Delay in milliseconds before hiding the tooltip. Default: 150ms */
+        closeDelay?: number;
+        /** Controlled mode: explicitly control whether the tooltip is open */
+        isOpen?: boolean;
+        /** Uncontrolled mode: default open state */
+        defaultOpen?: boolean;
+        /** Callback when the open state changes */
+        onOpenChange?: (open: boolean) => void;
+        /** Custom ID for accessibility linking. Auto-generated if not provided. */
+        id?: string;
     } & ({
         children?: never;
         targetRef: RefObject<T>;
@@ -20,7 +35,14 @@ export type ToolTipInterface<T extends HTMLElement = any> = {
         children: ReactNode;
         targetRef?: never;
     });
-    elements: ['toolTip', 'container', 'subHead', 'supportingText', 'actions'];
+    elements: [
+        'toolTip',
+        'container',
+        'subHead',
+        'supportingText',
+        'actions',
+        'content'
+    ];
 };
 export {};
 //# sourceMappingURL=tooltip.interface.d.ts.map

package/dist/lib/interfaces/tooltip.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tooltip.interface.d.ts","sourceRoot":"","sources":["../../../src/lib/interfaces/tooltip.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC,KAAK,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,IAAI,CAAC;AAElD,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,WAAW,GAAG,GAAG,IAAI;IAC1D,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE;QACL,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;QAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,UAAU,CAAC,eAAe,CAAC,GAAG,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACtE,QAAQ,CAAC,EACL,KAAK,GACL,QAAQ,GACR,MAAM,GACN,OAAO,GACP,UAAU,GACV,WAAW,GACX,aAAa,GACb,cAAc,CAAC;QACnB,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,EAAE,CAAC;QAC9B,UAAU,CAAC,EAAE,UAAU,CAAC;KACzB,GAAG,CACA;QACE,QAAQ,CAAC,EAAE,KAAK,CAAC;QACjB,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;KACzB,GACD;QACE,QAAQ,EAAE,SAAS,CAAC;QACpB,SAAS,CAAC,EAAE,KAAK,CAAC;KACnB,CACJ,CAAC;IACF,QAAQ,EAAE,CAAC,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,gBAAgB,EAAE,SAAS,CAAC,CAAC;CAC5E,CAAC"}
+{"version":3,"file":"tooltip.interface.d.ts","sourceRoot":"","sources":["../../../src/lib/interfaces/tooltip.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC,KAAK,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,IAAI,CAAC;AAElD,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,WAAW,GAAG,GAAG,IAAI;IAC1D,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE;QACL,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;QAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,2EAA2E;QAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,yEAAyE;QACzE,OAAO,CAAC,EAAE,SAAS,CAAC;QACpB,OAAO,CAAC,EAAE,UAAU,CAAC,eAAe,CAAC,GAAG,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACtE,QAAQ,CAAC,EACL,KAAK,GACL,QAAQ,GACR,MAAM,GACN,OAAO,GACP,UAAU,GACV,WAAW,GACX,aAAa,GACb,cAAc,CAAC;QACnB,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,EAAE,CAAC;QAC9B,UAAU,CAAC,EAAE,UAAU,CAAC;QACxB,uEAAuE;QACvE,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,sEAAsE;QACtE,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,sEAAsE;QACtE,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,4CAA4C;QAC5C,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,2CAA2C;QAC3C,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;QACvC,2EAA2E;QAC3E,EAAE,CAAC,EAAE,MAAM,CAAC;KACb,GAAG,CACA;QACE,QAAQ,CAAC,EAAE,KAAK,CAAC;QACjB,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;KACzB,GACD;QACE,QAAQ,EAAE,SAAS,CAAC;QACpB,SAAS,CAAC,EAAE,KAAK,CAAC;KACnB,CACJ,CAAC;IACF,QAAQ,EAAE;QACR,SAAS;QACT,WAAW;QACX,SAAS;QACT,gBAAgB;QAChB,SAAS;QACT,SAAS;KACV,CAAC;CACH,CAAC"}

package/dist/lib/styles/fab-menu.style.d.ts

@@ -27,7 +27,7 @@ export declare const fabMenuStyle: (states: ({
 }) & (((({
     variant?: import('..').FabVariant;
     label?: string;
-    children?: string;
+    children?: import('react').ReactNode;
     icon: import('..').Icon;
     size?: "small" | "medium" | "large";
     extended?: boolean;
@@ -37,7 +37,7 @@ export declare const fabMenuStyle: (states: ({
 }) | ({
     variant?: import('..').FabVariant;
     label?: string;
-    children?: string;
+    children?: import('react').ReactNode;
     icon: import('..').Icon;
     size?: "small" | "medium" | "large";
     extended?: boolean;
@@ -55,7 +55,7 @@ export declare const fabMenuStyle: (states: ({
 export declare const useFabMenuStyle: (states: ((({
     variant?: import('..').FabVariant;
     label?: string;
-    children?: string;
+    children?: import('react').ReactNode;
     icon: import('..').Icon;
     size?: "small" | "medium" | "large";
     extended?: boolean;
@@ -65,7 +65,7 @@ export declare const useFabMenuStyle: (states: ((({
 }) | ({
     variant?: import('..').FabVariant;
     label?: string;
-    children?: string;
+    children?: import('react').ReactNode;
     icon: import('..').Icon;
     size?: "small" | "medium" | "large";
     extended?: boolean;

package/dist/lib/styles/fab.style.d.ts

@@ -21,7 +21,7 @@ export declare const fabStyle: (states: ({
 }) & ((({
     variant?: import('..').FabVariant;
     label?: string;
-    children?: string;
+    children?: import('react').ReactNode;
     icon: import('..').Icon;
     size?: "small" | "medium" | "large";
     extended?: boolean;
@@ -31,7 +31,7 @@ export declare const fabStyle: (states: ({
 }) | ({
     variant?: import('..').FabVariant;
     label?: string;
-    children?: string;
+    children?: import('react').ReactNode;
     icon: import('..').Icon;
     size?: "small" | "medium" | "large";
     extended?: boolean;
@@ -44,7 +44,7 @@ export declare const fabStyle: (states: ({
 export declare const useFabStyle: (states: (({
     variant?: import('..').FabVariant;
     label?: string;
-    children?: string;
+    children?: import('react').ReactNode;
     icon: import('..').Icon;
     size?: "small" | "medium" | "large";
     extended?: boolean;
@@ -54,7 +54,7 @@ export declare const useFabStyle: (states: (({
 }) | ({
     variant?: import('..').FabVariant;
     label?: string;
-    children?: string;
+    children?: import('react').ReactNode;
     icon: import('..').Icon;
     size?: "small" | "medium" | "large";
     extended?: boolean;

package/dist/lib/styles/icon-button.style.d.ts

@@ -64,7 +64,7 @@ export declare const iconButtonStyle: (states: (({
     href?: never;
 }))) & import('..').IconButtonStates & {
     className: string | ClassNameComponent<IconButtonInterface> | undefined;
-}) => Record<"icon" | "stateLayer" | "iconButton" | "touchTarget", string>;
+}) => Record<"icon" | "stateLayer" | "touchTarget" | "iconButton", string>;
 export declare const useIconButtonStyle: (states: import('..').IconButtonStates & ((({
     label?: string;
     children?: string;
@@ -99,5 +99,5 @@ export declare const useIconButtonStyle: (states: import('..').IconButtonStates
     href?: never;
 })) & {
     className?: string | ClassNameComponent<IconButtonInterface> | undefined;
-})) => Record<"icon" | "stateLayer" | "iconButton" | "touchTarget", string>;
+})) => Record<"icon" | "stateLayer" | "touchTarget" | "iconButton", string>;
 //# sourceMappingURL=icon-button.style.d.ts.map

package/dist/lib/styles/tooltip.style.d.ts

@@ -4,30 +4,51 @@ export declare const toolStyle: (states: ({
     variant: any;
     title: any;
     text: any;
+    content: any;
     buttons: any;
     position: any;
     trigger: any;
     transition: any;
+    openDelay: any;
+    closeDelay: any;
+    isOpen: any;
+    defaultOpen: any;
+    onOpenChange: any;
+    id: any;
     children: any;
     targetRef: any;
 } | {
     variant: any;
     title: any;
     text: any;
+    content: any;
     buttons: any;
     position: any;
     trigger: any;
     transition: any;
+    openDelay: any;
+    closeDelay: any;
+    isOpen: any;
+    defaultOpen: any;
+    onOpenChange: any;
+    id: any;
     children: any;
     targetRef: any;
 }) & (({
     variant?: "plain" | "rich";
     title?: string;
-    text: string;
+    text?: string;
+    content?: import('react').ReactNode;
     buttons?: import('..').ReactProps<import('..').ButtonInterface> | import('..').ReactProps<import('..').ButtonInterface>[];
     position?: "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
-    trigger?: ("click" | "focus" | "hover" | null) | ("click" | "focus" | "hover" | null)[];
+    trigger?: ("hover" | "click" | "focus" | null) | ("hover" | "click" | "focus" | null)[];
     transition?: import('motion').Transition;
+    openDelay?: number;
+    closeDelay?: number;
+    isOpen?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    id?: string;
 } & ({
     children: import('react').ReactNode;
     targetRef?: never;
@@ -36,15 +57,22 @@ export declare const toolStyle: (states: ({
     targetRef: import('react').RefObject<any>;
 })) & {
     className: string | ClassNameComponent<ToolTipInterface> | undefined;
-})) => Record<"container" | "actions" | "supportingText" | "toolTip" | "subHead", string>;
+})) => Record<"container" | "content" | "actions" | "supportingText" | "toolTip" | "subHead", string>;
 export declare const useToolTipStyle: (states: ({
     variant?: "plain" | "rich";
     title?: string;
-    text: string;
+    text?: string;
+    content?: import('react').ReactNode;
     buttons?: import('..').ReactProps<import('..').ButtonInterface> | import('..').ReactProps<import('..').ButtonInterface>[];
     position?: "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
-    trigger?: ("click" | "focus" | "hover" | null) | ("click" | "focus" | "hover" | null)[];
+    trigger?: ("hover" | "click" | "focus" | null) | ("hover" | "click" | "focus" | null)[];
     transition?: import('motion').Transition;
+    openDelay?: number;
+    closeDelay?: number;
+    isOpen?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    id?: string;
 } & ({
     children: import('react').ReactNode;
     targetRef?: never;
@@ -53,5 +81,5 @@ export declare const useToolTipStyle: (states: ({
     targetRef: import('react').RefObject<any>;
 })) & {
     className?: string | ClassNameComponent<ToolTipInterface> | undefined;
-}) => Record<"container" | "actions" | "supportingText" | "toolTip" | "subHead", string>;
+}) => Record<"container" | "content" | "actions" | "supportingText" | "toolTip" | "subHead", string>;
 //# sourceMappingURL=tooltip.style.d.ts.map

package/dist/lib/styles/tooltip.style.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tooltip.style.d.ts","sourceRoot":"","sources":["../../../src/lib/styles/tooltip.style.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EAIxB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAgCjD,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yFAGrB,CAAC;AAEF,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;wFAG3B,CAAC"}
+{"version":3,"file":"tooltip.style.d.ts","sourceRoot":"","sources":["../../../src/lib/styles/tooltip.style.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EAIxB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAiCjD,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qGAGrB,CAAC;AAEF,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;oGAG3B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udixio/ui-react",
-  "version": "2.9.8",
+  "version": "2.9.10",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/lib/components/Button.tsx

@@ -38,6 +38,12 @@ function resolveVariantAlias(
  * Buttons prompt most actions in a UI
  * @status beta
  * @category Action
+ * @devx
+ * - Requires `label` or children; used for visible text and a11y.
+ * - `onToggle` uses internal state; pair with `activated` for controlled usage.
+ * @limitations
+ * - No explicit `type` prop; HTML button defaults may submit in forms.
+ * - When `href` is set, `disabled` is visual only (no `aria-disabled`).
  */
 export const Button = ({
   variant = 'filled',

package/src/lib/components/Card.tsx

@@ -8,6 +8,10 @@ import { State } from '../effects';
  * Cards display content and actions about a single subject
  * @status beta
  * @category Layout
+ * @devx
+ * - `isInteractive` only adds a state layer; add your own click/role semantics.
+ * @limitations
+ * - No built-in header/actions slots; layout is fully custom via children.
  */
 export const Card = ({
   variant = 'outlined',

package/src/lib/components/Carousel.tsx

@@ -16,9 +16,13 @@ function clamp(v: number, min: number, max: number) {
  *
  * @status beta
  * @category Layout
+ * @devx
+ * - Only `CarouselItem` children are rendered; other children are ignored.
+ * - Use `index` for controlled positioning; otherwise relies on internal scroll state.
  * @limitations
  * - Responsive behavior on mobile is not supported.
  * - Only the default (hero) variant is supported.
+ * - No keyboard navigation or focus management.
  */
 export const Carousel = ({
   variant = 'hero',

package/src/lib/components/CarouselItem.tsx

@@ -21,6 +21,10 @@ export const normalize = (
 /**
  * @status beta
  * @parent Carousel
+ * @devx
+ * - Intended for use inside `Carousel`; width and outputRange drive sizing.
+ * @limitations
+ * - Requires `outputRange` for min/max sizing; missing values can break layout.
  */
 export const CarouselItem = ({
   className,

package/src/lib/components/Chip.tsx

@@ -10,6 +10,13 @@ import { faCheck, faXmark } from '@fortawesome/free-solid-svg-icons';
  * Chips prompt most actions in a UI
  * @status beta
  * @category Action
+ * @devx
+ * - `editable` relies on contentEditable; label should be a string.
+ * - `onToggle` uses internal state; pair with `activated` for controlled usage.
+ * @a11y
+ * - Uses `aria-pressed` only when togglable.
+ * @limitations
+ * - Edit mode starts after a 1s focus delay (no prop to customize).
  */
 export const Chip = ({
   variant = 'outlined',

package/src/lib/components/Chips.tsx

@@ -6,6 +6,16 @@ import { Chip } from './Chip';
 import { Divider } from './Divider';
 import { v4 } from 'uuid';
 
+/**
+ * Chips group for input or selection lists
+ * @status beta
+ * @category Input
+ * @devx
+ * - Works best as controlled: pass `items` + `onItemsChange`.
+ * - Internal ids are derived from object identity; replace items carefully.
+ * @limitations
+ * - No virtualization; very large lists can be slow.
+ */
 export const Chips = ({
   variant = 'input',
   className,

package/src/lib/components/Divider.tsx

@@ -6,6 +6,8 @@ import { ReactProps } from '../utils';
  * Dividers are thin lines that group content in lists or other containers
  * @status beta
  * @category Layout
+ * @devx
+ * - Renders a semantic `<hr>`; use `orientation` for vertical dividers.
  */
 export const Divider = ({
   orientation = 'horizontal',

package/src/lib/components/Fab.tsx

@@ -5,13 +5,17 @@ import { FabInterface } from '../interfaces/fab.interface';
 import { useFabStyle } from '../styles/fab.style';
 import { classNames } from '../utils';
 import { ReactProps } from '../utils/component';
-import { ToolTip } from './ToolTip';
+import { Tooltip } from './Tooltip';
 import { State } from '../effects';
 
 /**
  * Floating action buttons (FABs) help people take primary actions
  * @status beta
  * @category Action
+ * @devx
+ * - Requires `label` or children; icon-only still needs a label for a11y.
+ * @limitations
+ * - No built-in positioning; placement is handled by the layout.
  */
 export const Fab = ({
   className,
@@ -86,7 +90,7 @@ export const Fab = ({
       aria-label={extended ? undefined : label}
       className={styles.fab}
     >
-      <ToolTip
+      <Tooltip
         trigger={extended ? null : undefined}
         text={label}
         targetRef={resolvedRef}

package/src/lib/components/FabMenu.tsx

@@ -15,6 +15,13 @@ import { v4 } from 'uuid';
  * Floating action buttons (FABs) help people take primary actions
  * @status beta
  * @category Action
+ * @devx
+ * - Only `Button` children are rendered as actions.
+ * - Controlled via `open`/`onOpenChange` or `defaultOpen`.
+ * @a11y
+ * - No focus trap or Escape handling when open.
+ * @limitations
+ * - No outside-click handling; close uses the explicit close button.
  */
 export const FabMenu = ({
   className,

package/src/lib/components/IconButton.tsx

@@ -1,12 +1,11 @@
 import React, { useEffect, useRef } from 'react';
 
-import { Icon } from '../icon/icon';
-import { IconButtonInterface } from '../interfaces/icon-button.interface';
-import { useIconButtonStyle } from '../styles/icon-button.style';
-import { ReactProps } from '../utils/component';
+import { Icon } from '../icon';
+import { IconButtonInterface } from '../interfaces';
+import { useIconButtonStyle } from '../styles';
+import { classNames, ReactProps } from '../utils';
 import { State } from '../effects';
-import { classNames } from '../utils';
-import { ToolTip } from './ToolTip';
+import { Tooltip } from './Tooltip';
 
 export type IconButtonVariant = 'standard' | 'filled' | 'tonal' | 'outlined';
 
@@ -14,6 +13,11 @@ export type IconButtonVariant = 'standard' | 'filled' | 'tonal' | 'outlined';
  * Icon buttons help people take minor actions with one tap
  * @status beta
  * @category Action
+ * @devx
+ * - Requires `label` or children to provide an aria-label.
+ * - Uses `title` as tooltip text; native title attribute is suppressed.
+ * @limitations
+ * - Tooltip is always rendered (no explicit opt-out).
  */
 export const IconButton = ({
   variant = 'standard',
@@ -104,11 +108,11 @@ export const IconButton = ({
       onClick={handleClick}
       ref={resolvedRef}
     >
-      <ToolTip
+      <Tooltip
         targetRef={resolvedRef}
         trigger={disabled ? null : undefined}
         text={title}
-      ></ToolTip>
+      ></Tooltip>
 
       <div className={styles.touchTarget} />
       <State

package/src/lib/components/NavigationRail.tsx

@@ -26,6 +26,12 @@ import { IconButton } from './IconButton';
  * Navigation rails let people switch between UI views on mid-sized devices
  * @status beta
  * @category Navigation
+ * @devx
+ * - Treats `NavigationRailItem`, `NavigationRailSection`, and `Fab` specially.
+ * - Selection is index-based; provide `selectedItem` for controlled usage.
+ * @limitations
+ * - `extended` is not fully controlled (prop changes after mount aren’t synced).
+ * - Keyboard navigation/roving tabindex is not implemented.
  */
 export const NavigationRail = ({
   variant = 'standard',

package/src/lib/components/NavigationRailItem.tsx

@@ -10,6 +10,8 @@ import { State } from '../effects';
 /**
  * @status beta
  * @parent NavigationRail
+ * @devx
+ * - Section labels only render when the rail is extended.
  */
 export const NavigationRailSection = ({ label }: { label: string }) => {
   return (
@@ -22,6 +24,11 @@ export const NavigationRailSection = ({ label }: { label: string }) => {
 /**
  * @status beta
  * @parent NavigationRail
+ * @devx
+ * - Selection is index-based and provided by the parent rail.
+ * - `extendedOnly` hides items when the rail is collapsed.
+ * @a11y
+ * - Uses `role="tab"` but no roving tabindex or aria-controls wiring.
  */
 export const NavigationRailItem = ({
   className,

package/src/lib/components/ProgressIndicator.tsx

@@ -8,6 +8,12 @@ import { ReactProps } from '../utils/component';
 /**
  * @status beta
  * @category Communication
+ * @devx
+ * - `value` is clamped to 0–100; indeterminate variants ignore it.
+ * @a11y
+ * - Missing `role="progressbar"` and aria-* attributes.
+ * @limitations
+ * - Visibility auto-hides at 100% (no controlled open prop).
  */
 export const ProgressIndicator = ({
   variant = 'linear-determinate',

package/src/lib/components/SideSheet.tsx

@@ -13,6 +13,13 @@ import { sideSheetStyle } from '../styles';
  * Side sheets show secondary content anchored to the side of the screen
  * @status beta
  * @category Layout
+ * @devx
+ * - Controlled via `extended`/`onExtendedChange` or internal state.
+ * - `variant="modal"` renders into a portal on `document.body`.
+ * @a11y
+ * - No focus trap, Escape handling, or `aria-modal` attributes.
+ * @limitations
+ * - No body scroll lock when open.
  */
 export const SideSheet = ({
   variant = 'standard',

package/src/lib/components/Slider.tsx

@@ -8,6 +8,11 @@ import { useEffect, useRef, useState } from 'react';
  * Sliders let users make selections from a range of values
  * @status beta
  * @category Input
+ * @devx
+ * - `value` is treated as the initial value; component is uncontrolled after mount.
+ * - `onChange` receives the numeric value (not the DOM event).
+ * @a11y
+ * - Provides slider role/aria values, but no label prop.
  */
 export const Slider = ({
   className,

package/src/lib/components/Snackbar.tsx

@@ -11,6 +11,12 @@ import { IconButton } from './IconButton';
  * Snackbars show short updates about app processes at the bottom of the screen
  * @status beta
  * @category Communication
+ * @devx
+ * - Uncontrolled visibility; use `duration` to auto-dismiss.
+ * @a11y
+ * - No `role="status"`/`alert` announcements.
+ * @limitations
+ * - No queue/stacking and no controlled open prop.
  */
 export const Snackbar = ({
   message,

package/src/lib/components/Switch.tsx

@@ -10,6 +10,10 @@ import { MotionProps } from '../utils/component';
  * Switches toggle the selection of an item on or off
  * @status beta
  * @category Input
+ * @devx
+ * - `selected` is used as initial state only; prop changes won’t sync.
+ * @a11y
+ * - Uses `role="switch"` but no label prop is exposed here.
  */
 export const Switch = ({
   selected = false,

package/src/lib/components/Tab.tsx

@@ -10,6 +10,11 @@ import { State } from '../effects';
 /**
  * @status beta
  * @parent Tabs
+ * @devx
+ * - `label` can come from string children; selection is index-based.
+ * - Use `TabGroup` to sync selection with panels/animations.
+ * @a11y
+ * - No keyboard navigation or `aria-controls` wiring.
  */
 export const Tab = ({
   className,

package/src/lib/components/TabGroup.tsx

@@ -8,6 +8,10 @@ import { ReactProps } from '../utils/component';
  * TabGroup provides shared state for Tabs and TabPanels
  * @status beta
  * @category Navigation
+ * @devx
+ * - Provides selection + slide direction for Tabs/TabPanels.
+ * @limitations
+ * - No URL/hash syncing or persistence built in.
  */
 export const TabGroup = ({
   children,

package/src/lib/components/TabGroupContext.tsx

@@ -1,5 +1,10 @@
 import { createContext, Dispatch, SetStateAction } from 'react';
 
+/**
+ * Shared state container for Tabs and TabPanels.
+ * @internal
+ */
+
 export interface TabGroupContextValue {
   selectedTab: number | null;
   setSelectedTab: Dispatch<SetStateAction<number | null>>;
@@ -8,4 +13,4 @@ export interface TabGroupContextValue {
   tabsId: string;
 }
 
-export const TabGroupContext = createContext<TabGroupContextValue | null>(null);
+export const TabGroupContext = createContext<TabGroupContextValue | null>(null);

package/src/lib/components/TabPanel.tsx

@@ -8,6 +8,8 @@ import { useTabPanelStyle } from '../styles/tab-panels.style';
  * Must be used within TabPanels
  * @status beta
  * @category Navigation
+ * @devx
+ * - Should be rendered inside `TabPanels` for animations and aria wiring.
  */
 export const TabPanel = ({
   children,

package/src/lib/components/TabPanels.tsx

@@ -11,6 +11,10 @@ import { TabPanel } from './TabPanel';
  * Must be used within a TabGroup
  * @status beta
  * @category Navigation
+ * @devx
+ * - Requires `TabGroup` context; otherwise it renders nothing.
+ * @limitations
+ * - Only renders the active panel (no offscreen preservation).
  */
 export const TabPanels = ({
   children,

package/src/lib/components/Tabs.tsx

@@ -12,6 +12,10 @@ import { TabGroupContext } from './TabGroupContext';
  * Tabs organize content across different screens and views
  * @status beta
  * @category Navigation
+ * @devx
+ * - Can be controlled via `selectedTab`/`setSelectedTab` or through `TabGroup`.
+ * @a11y
+ * - No keyboard navigation or roving tabindex.
  */
 export const Tabs = ({
   variant = 'primary',

package/src/lib/components/TextField.tsx

@@ -14,6 +14,11 @@ import { TextFieldInterface } from '../interfaces/text-field.interface';
  * Text fields let users enter text into a UI
  * @status beta
  * @category Input
+ * @devx
+ * - `onChange` receives the string value (not the DOM event).
+ * - `value` syncs internal state; not a fully controlled input.
+ * @a11y
+ * - Uses `label` for `aria-label`; no `aria-describedby` for supporting text.
  */
 export const TextField = ({
   variant = 'filled',