@udixio/ui-react 2.9.9 → 2.9.10

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

@@ -41,7 +41,7 @@ export declare const toolStyle: (states: ({
     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;
@@ -65,7 +65,7 @@ export declare const useToolTipStyle: (states: ({
     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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udixio/ui-react",
-  "version": "2.9.9",
+  "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

@@ -12,6 +12,10 @@ 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,

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,11 +1,10 @@
 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';
 
 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',

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',

package/src/lib/components/Tooltip.tsx

@@ -1,4 +1,4 @@
-import { cloneElement, isValidElement, useRef } from 'react';
+import { cloneElement, isValidElement, useEffect, useRef } from 'react';
 import { MotionProps } from '../utils';
 import { Button } from './Button';
 import { ToolTipInterface } from '../interfaces';
@@ -11,6 +11,11 @@ import { useTooltipTrigger, useTooltipPosition } from '../hooks';
  * Tooltips display brief labels or messages
  * @status beta
  * @category Communication
+ * @devx
+ * - `content` overrides `title`/`text`/`buttons` for fully custom content.
+ * - Supports controlled `isOpen` plus `openDelay`/`closeDelay`.
+ * @a11y
+ * - Provides `role="tooltip"` and `aria-describedby` when open.
  */
 export const Tooltip = ({
   variant = 'plain',
@@ -99,6 +104,46 @@ export const Tooltip = ({
         } as any)
       : children;
 
+  // Attach trigger handlers when using targetRef (no direct child to clone)
+  useEffect(() => {
+    if (!targetRef) return;
+    const element = targetRef.current;
+    if (!element) return;
+
+    const handleMouseEnter = () => triggerProps.onMouseEnter();
+    const handleMouseLeave = () => triggerProps.onMouseLeave();
+    const handleFocus = () => triggerProps.onFocus();
+    const handleBlur = () => triggerProps.onBlur();
+    const handleClick = () => triggerProps.onClick();
+    const handleKeyDown = (event: KeyboardEvent) =>
+      triggerProps.onKeyDown(event as unknown as React.KeyboardEvent);
+
+    element.addEventListener('mouseenter', handleMouseEnter);
+    element.addEventListener('mouseleave', handleMouseLeave);
+    element.addEventListener('focus', handleFocus, true);
+    element.addEventListener('blur', handleBlur, true);
+    element.addEventListener('click', handleClick);
+    element.addEventListener('keydown', handleKeyDown);
+
+    if (triggerProps['aria-describedby']) {
+      element.setAttribute(
+        'aria-describedby',
+        triggerProps['aria-describedby'],
+      );
+    } else {
+      element.removeAttribute('aria-describedby');
+    }
+
+    return () => {
+      element.removeEventListener('mouseenter', handleMouseEnter);
+      element.removeEventListener('mouseleave', handleMouseLeave);
+      element.removeEventListener('focus', handleFocus, true);
+      element.removeEventListener('blur', handleBlur, true);
+      element.removeEventListener('click', handleClick);
+      element.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [targetRef, triggerProps]);
+
   const styles = useToolTipStyle({
     variant,
     buttons,

package/src/lib/interfaces/fab.interface.ts

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