@axzydev/axzy_ui_system 1.2.6 → 1.2.8

package/src/components/sidebar/sidebar.doc.mdx

@@ -0,0 +1,86 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './sidebar.stories';
+
+<Meta of={Stories} />
+
+# ITSidebar
+
+Vertical navigation sidebar with collapsible submenus, tooltips when collapsed, active item highlighting, badge support, and themed glassmorphism styling. Designed for admin panels and dashboard layouts.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `navigationItems` | `ITNavigationItem[]` | — | Navigation structure: top-level items with optional sub-items. |
+| `isCollapsed` | `boolean` | `false` | Whether the sidebar is collapsed to icon-only mode. |
+| `onToggleCollapse` | `() => void` | — | Callback when the user toggles collapse via the toggle button. |
+| `visibleOnMobile` | `boolean` | `false` | Force sidebar visible on mobile breakpoints. |
+| `onItemClick` | `(item: ITNavigationItem) => void` | — | Callback when a top-level navigation item is clicked. |
+| `onSubItemClick` | `(subitem: ITNavigationSubItem) => void` | — | Callback when a sub-navigation item is clicked. |
+| `subitemConnector` | `"dot" \| "\|" \| "none"` | `"dot"` | Visual connector style for sub-items. |
+| `className` | `string` | — | Additional CSS classes on the sidebar `<aside>`. |
+
+### ITNavigationItem
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `string` | Unique identifier. |
+| `label` | `string` | Display label. |
+| `icon` | `ReactNode` | Icon rendered left of the label. |
+| `action` | `() => void` | Click handler for top-level items without submenus. |
+| `isActive` | `boolean` | Whether this item is active/highlighted. |
+| `subitems` | `ITNavigationSubItem[]` | Nested sub-navigation items. |
+| `badge` | `string` | Badge text (e.g. notification count). |
+
+### ITNavigationSubItem
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `string` | Unique identifier. |
+| `label` | `string` | Display label. |
+| `action` | `() => void` | Click handler. |
+| `isActive` | `boolean` | Whether this sub-item is active/highlighted. |
+
+## Usage
+
+```tsx
+import { ITSidebar } from '@axzydev/axzy_ui_system';
+import { FaHome, FaUsers, FaCog } from 'react-icons/fa';
+
+const items = [
+  { id: 'dashboard', label: 'Dashboard', icon: <FaHome />, isActive: true, action: () => {} },
+  {
+    id: 'users',
+    label: 'Users',
+    icon: <FaUsers />,
+    badge: '3',
+    subitems: [
+      { id: 'users-list', label: 'User List', action: () => {} },
+      { id: 'users-roles', label: 'Roles', action: () => {}, isActive: true },
+    ],
+  },
+];
+
+<ITSidebar
+  navigationItems={items}
+  isCollapsed={false}
+  onToggleCollapse={toggleCollapse}
+  subitemConnector="dot"
+/>
+```
+
+## Notes
+
+- Collapsed mode shrinks to icon-only; tooltips show labels on hover with glassmorphism style.
+- Submenus expand/collapse with smooth transitions when a parent item is clicked.
+- Active item highlighting uses a colored left-border accent and subtle background tint.
+- Badge support renders a notification-style counter on the item.
+- `subitemConnector` styles the visual link between parent and sub-items: `dot` (default), `|` (vertical bar), or `none`.
+- `visibleOnMobile` forces sidebar visibility on smaller screens for responsive layouts.
+- Themed via CSS variables for consistent colors, shadows, and glassmorphism effects across light and dark modes.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/sidebar/sidebar.props.ts

@@ -1,28 +1,50 @@
+/** A sub-navigation item nested under a parent menu. */
 export interface ITNavigationSubItem {
+  /** Unique identifier for the sub-item. */
   id: string;
+  /** Display label. */
   label: string;
+  /** Click handler. */
   action?: () => void;
+  /** Whether this sub-item is currently active/highlighted. */
   isActive?: boolean;
 }
 
+/** A top-level navigation item, optionally with sub-items. */
 export interface ITNavigationItem {
+  /** Unique identifier. */
   id: string;
+  /** Display label. */
   label: string;
+  /** Icon component rendered left of the label. */
   icon?: React.ReactNode;
+  /** Click handler for top-level items without submenus. */
   action?: () => void;
+  /** Whether this item is currently active/highlighted. */
   isActive?: boolean;
+  /** Nested sub-navigation items (renders as expandable submenu). */
   subitems?: ITNavigationSubItem[];
+  /** Badge text displayed on the item (e.g. notification count). */
   badge?: string;
 }
 
+/** Props for the ITSidebar vertical navigation component. */
 export interface ITSidebarProps {
+  /** Navigation structure: top-level items with optional sub-items. */
   navigationItems: ITNavigationItem[];
+  /** Whether the sidebar is collapsed to icon-only mode. */
   isCollapsed?: boolean;
+  /** Callback when the user toggles collapse via the toggle button. */
   onToggleCollapse?: () => void;
+  /** Force sidebar visible on mobile breakpoints. */
   visibleOnMobile?: boolean; 
+  /** Callback when a top-level navigation item is clicked. Receives the item. */
   onItemClick?: (item: ITNavigationItem) => void;
+  /** Callback when a sub-navigation item is clicked. Receives the sub-item. */
   onSubItemClick?: (subitem: ITNavigationSubItem) => void;
+  /** Visual connector style for sub-items: "dot" | "|" | "none". Default: "dot". */
   subitemConnector?: 'dot' | '|' | 'none';
+  /** Additional CSS classes on the sidebar `<aside>`. */
   className?: string;
 }
 

package/src/components/sidebar/sidebar.tsx

@@ -3,6 +3,28 @@ import { FaChevronDown } from "react-icons/fa";
 import { ITNavigationItem, ITSidebarProps } from "./sidebar.props";
 import ITText from "@/components/text/text";
 
+/**
+ * Vertical navigation sidebar with submenu expand/collapse, hover tooltips in collapsed mode,
+ * and glassmorphism styling.
+ *
+ * @example
+ * ```tsx
+ * <ITSidebar
+ *   navigationItems={[
+ *     { id: "dashboard", label: "Dashboard", icon: <FaHome />, isActive: true },
+ *     {
+ *       id: "settings", label: "Settings", icon: <FaCog />,
+ *       subitems: [
+ *         { id: "profile", label: "Profile", action: () => navigate("/profile") },
+ *         { id: "billing", label: "Billing", isActive: true },
+ *       ],
+ *     },
+ *   ]}
+ *   isCollapsed={collapsed}
+ *   onToggleCollapse={() => setCollapsed(!collapsed)}
+ * />
+ * ```
+ */
 export default function ITSidebar({
   navigationItems = [],
   isCollapsed = false,

package/src/components/skeleton/skeleton.doc.mdx

@@ -0,0 +1,43 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './skeleton.stories';
+
+<Meta of={Stories} />
+
+# ITSkeleton
+
+Content placeholder loaders used during data loading to indicate upcoming content.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'text' \| 'circular' \| 'rectangular' \| 'rounded'` | `'text'` | Shape of the skeleton placeholder |
+| `animation` | `'pulse' \| 'wave' \| 'none'` | `'pulse'` | Animation style |
+| `width` | `number \| string` | — | Width of the skeleton |
+| `height` | `number \| string` | — | Height of the skeleton |
+| `count` | `number` | `1` | Number of skeleton items to render |
+
+## Usage
+
+```tsx
+import { ITSkeleton } from '@axzydev/axzy_ui_system';
+
+<ITSkeleton />
+<ITSkeleton variant="circular" width={40} height={40} />
+<ITSkeleton variant="rectangular" width="100%" height={200} animation="wave" />
+<ITSkeleton variant="text" count={3} />
+```
+
+## Notes
+
+- Use during data loading to reduce perceived wait time
+- `count` prop repeats the skeleton for placeholder lists or paragraphs
+- `rectangular` variant suits image or card placeholders
+- `circular` variant suits avatar or icon placeholders
+- Set `animation="none"` for static placeholders
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/skeleton/skeleton.props.ts

@@ -1,12 +1,20 @@
 import { CSSProperties } from "react";
 
+/** Skeleton shape variant: "text" (line) | "circular" (avatar/icon) | "rectangular" (card/image). */
 export type SkeletonVariant = "text" | "circular" | "rectangular";
 
+/** Props for the ITSkeleton content placeholder loader component. */
 export interface ITSkeletonProps {
+  /** Skeleton shape: "text" | "circular" | "rectangular". Default: "text". */
   variant?: SkeletonVariant;
+  /** Explicit width (CSS value or number in px). Text variant defaults to random 60%-90%. */
   width?: string | number;
+  /** Explicit height (CSS value or number in px). */
   height?: string | number;
+  /** Number of skeleton items to render. Default: 1. */
   count?: number;
+  /** Additional CSS classes on each skeleton item. */
   className?: string;
+  /** Inline style object applied to each skeleton item. */
   style?: CSSProperties;
 }

package/src/components/skeleton/skeleton.tsx

@@ -7,6 +7,16 @@ const variantClasses: Record<SkeletonVariant, string> = {
   rectangular: "rounded-lg",
 };
 
+/**
+ * Content placeholder loader with pulse animation for text, circles, and rectangles.
+ *
+ * @example
+ * ```tsx
+ * <ITSkeleton variant="circular" width={40} height={40} />
+ * <ITSkeleton variant="text" count={3} />
+ * <ITSkeleton variant="rectangular" width="100%" height={200} />
+ * ```
+ */
 export default function ITSkeleton({
   variant = "text",
   width,

package/src/components/slide/slide.doc.mdx

@@ -0,0 +1,46 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './slide.stories';
+
+<Meta of={Stories} />
+
+# ITSlideToggle
+
+iOS-style toggle switch for boolean settings. Supports controlled and uncontrolled modes.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `checked` | `boolean` | — | Controlled checked state |
+| `defaultChecked` | `boolean` | `false` | Uncontrolled default state |
+| `onChange` | `(checked: boolean) => void` | — | Change handler |
+| `label` | `string` | — | Label text |
+| `labelPosition` | `'left' \| 'right'` | `'right'` | Label placement |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Toggle size |
+| `color` | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'danger' \| 'info' \| 'neutral'` | `'primary'` | Color theme when checked |
+| `disabled` | `boolean` | `false` | Disables the toggle |
+
+## Usage
+
+```tsx
+import { ITSlideToggle } from '@axzydev/axzy_ui_system';
+
+<ITSlideToggle />
+<ITSlideToggle label="Enable notifications" defaultChecked />
+<ITSlideToggle label="Dark mode" labelPosition="left" size="sm" color="success" />
+<ITSlideToggle disabled label="Locked" />
+```
+
+## Notes
+
+- Controlled mode via `checked` + `onChange`
+- Uncontrolled mode via `defaultChecked`
+- Label renders alongside the toggle with configurable position
+- Seven semantic color themes available
+- Three sizes: sm (small), md (medium), lg (large)
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/slide/slide.props.ts

@@ -1,45 +1,32 @@
+/** Props for the ITSlideToggle iOS-style toggle switch. */
 export interface ITSlideToggleProps {
-  /**
-   * Callback executed when the switch is toggled. Receives the new state.
-   */
+  /** Callback executed when the switch is toggled. Receives the new boolean state. */
   onToggle?: (value: boolean) => void;
 
-  /**
-   * Controlled state. Use this to completely control the component externally.
-   */
+  /** Controlled state. Use this to fully control the component externally. */
   isOn?: boolean;
 
-  /**
-   * Initial state for uncontrolled usage.
-   * Default: false
-   */
+  /** Initial state for uncontrolled usage. Default: false. */
   initialState?: boolean;
 
   /**
-   * Semantic theme color when activated (e.g., 'primary', 'success').
-   * Default: 'success'
+   * Semantic theme color when activated (e.g. "primary", "success", "danger").
+   * Can also be a hex value. Default: "success".
    */
   activeColor?: string;
 
   /**
-   * Semantic theme color or hex when deactivated.
-   * Default: '#9ca3af' (gray-400)
+   * Semantic theme color or hex value when deactivated.
+   * Default: '#9ca3af' (gray-400).
    */
   inactiveColor?: string;
 
-  /**
-   * Whether the switch is disabled.
-   */
+  /** Whether the switch is disabled. */
   disabled?: boolean;
 
-  /**
-   * Size of the switch: sm, md, lg.
-   * Default: md
-   */
+  /** Size of the switch: "sm" | "md" | "lg". Default: "md". */
   size?: "sm" | "md" | "lg";
 
-  /**
-   * Additional container classes.
-   */
+  /** Additional CSS classes on the container. */
   className?: string;
 }

package/src/components/slide/slide.tsx

@@ -4,8 +4,17 @@ import { ITSlideToggleProps } from "./slide.props";
 import { theme } from "@/theme/theme";
 
 /**
- * Slide toggle switch component.
+ * iOS-style toggle switch with theme color support.
  * Supports fully controlled (`isOn`) or uncontrolled (`initialState`) modes.
+ *
+ * @example
+ * ```tsx
+ * // Controlled
+ * <ITSlideToggle isOn={enabled} onToggle={setEnabled} activeColor="primary" />
+ *
+ * // Uncontrolled with initial state
+ * <ITSlideToggle initialState onToggle={(v) => console.log(v)} />
+ * ```
  */
 export default function ITSlideToggle({
   onToggle,

package/src/components/slider/slider.doc.mdx

@@ -0,0 +1,49 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './slider.stories';
+
+<Meta of={Stories} />
+
+# ITSlider
+
+Range slider with configurable min, max, and step values. Displays the current value.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number` | — | Current slider value |
+| `defaultValue` | `number` | — | Default uncontrolled value |
+| `min` | `number` | `0` | Minimum value |
+| `max` | `number` | `100` | Maximum value |
+| `step` | `number` | `1` | Step increment |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Slider orientation |
+| `showValue` | `boolean` | `true` | Show current value label |
+| `ticks` | `boolean` | `false` | Show tick marks |
+| `tickLabels` | `string[]` | — | Custom labels for tick marks |
+| `color` | `string` | `'primary'` | Semantic color theme |
+| `disabled` | `boolean` | `false` | Disables the slider |
+
+## Usage
+
+```tsx
+import { ITSlider } from '@axzydev/axzy_ui_system';
+
+<ITSlider />
+<ITSlider min={0} max={100} step={10} defaultValue={50} />
+<ITSlider orientation="vertical" showValue ticks color="success" />
+<ITSlider tickLabels={['Low', 'Mid', 'High']} step={50} max={100} />
+```
+
+## Notes
+
+- Current value displayed by default; set `showValue={false}` to hide
+- `ticks` renders tick marks at each step interval
+- `tickLabels` provides custom string labels for tick positions
+- Orientation supports horizontal and vertical layouts
+- All semantic color themes supported
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/slider/slider.props.ts

@@ -1,10 +1,19 @@
+/** Props for the ITSlider range slider component. */
 export interface ITSliderProps {
+  /** Current slider value (controlled). */
   value: number;
+  /** Callback fired when the value changes. Receives the new numeric value. */
   onChange: (value: number) => void;
+  /** Minimum allowed value. Default: 0. */
   min?: number;
+  /** Maximum allowed value. Default: 100. */
   max?: number;
+  /** Step increment. Default: 1. */
   step?: number;
+  /** Label displayed above the slider. Also shows the current value. */
   label?: string;
+  /** Whether the slider is disabled. */
   disabled?: boolean;
+  /** Additional CSS classes on the container. */
   className?: string;
 }

package/src/components/slider/slider.tsx

@@ -2,6 +2,21 @@ import clsx from "clsx";
 import { ITSliderProps } from "./slider.props";
 import ITText from "@/components/text/text";
 
+/**
+ * Range slider control with min/max/step and optional label displaying the current value.
+ *
+ * @example
+ * ```tsx
+ * <ITSlider
+ *   label="Volume"
+ *   value={volume}
+ *   onChange={setVolume}
+ *   min={0}
+ *   max={100}
+ *   step={5}
+ * />
+ * ```
+ */
 export default function ITSlider({
   value,
   onChange,

package/src/components/stack/stack.doc.mdx

@@ -0,0 +1,126 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './stack.stories';
+
+<Meta of={Stories} />
+
+# ITStack
+
+ITStack is a simplified flexbox layout primitive for consistent spacing and alignment. It controls direction, gap, cross-axis alignment, main-axis justification, and flex wrapping in a single component, with optional dividers between children.
+
+ITStack powers most internal layouts across the AXZY UI System — from button toolbars and form rows to card lists and centered hero sections.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | — | Stack children elements. |
+| `direction` | `"column" \| "row" \| "row-reverse" \| "column-reverse"` | `"column"` | Flex direction. |
+| `spacing` | `number` (0–12) | `0` | Gap between children in `0.25rem` units. `spacing={4}` = `1rem` gap. |
+| `alignItems` | `"start" \| "end" \| "center" \| "stretch" \| "baseline"` | — | Cross-axis alignment: vertical in row, horizontal in column. |
+| `justifyContent` | `"start" \| "end" \| "center" \| "between" \| "around" \| "evenly"` | — | Main-axis distribution of children. |
+| `flexWrap` | `"nowrap" \| "wrap" \| "wrap-reverse"` | — | Whether children wrap to the next line. |
+| `divider` | `ReactNode` | — | Optional element rendered between each pair of children via `cloneElement`. |
+| `className` | `string` | — | Additional CSS classes on the container. |
+| `style` | `CSSProperties` | — | Inline styles on the container. |
+| `as` | `ElementType` | `"div"` | HTML element to render as — `"section"`, `"nav"`, `"ul"`, `"form"`, etc. |
+
+## Usage
+
+```tsx
+import { ITStack } from '@axzydev/axzy_ui_system';
+
+// ── Vertical (default) ──
+<ITStack spacing={4}>
+  <h2>Section Title</h2>
+  <p>Section content goes here.</p>
+</ITStack>
+
+// ── Horizontal toolbar ──
+<ITStack direction="row" spacing={2} alignItems="center" justifyContent="between">
+  <ITButton>Cancel</ITButton>
+  <ITButton color="primary">Save</ITButton>
+</ITStack>
+
+// ── Form row with wrap ──
+<ITStack direction="row" spacing={3} flexWrap="wrap">
+  <ITInput name="first" label="First Name" />
+  <ITInput name="last" label="Last Name" />
+  <ITInput name="email" label="Email" />
+</ITStack>
+
+// ── Card list with dividers ──
+<ITStack spacing={0} divider={<hr />}>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</ITStack>
+
+// ── Tag cloud ──
+<ITStack direction="row" spacing={1} flexWrap="wrap">
+  {tags.map((t) => <ITBadget key={t} label={t} />)}
+</ITStack>
+
+// ── Centered hero ──
+<ITStack spacing={4} alignItems="center" justifyContent="center" className="h-64">
+  <h1>Hero Title</h1>
+  <p>Subtitle text</p>
+  <ITButton label="CTA" />
+</ITStack>
+
+// ── Semantic list (as="ul") ──
+<ITStack as="ul" spacing={2}>
+  <li>First item</li>
+  <li>Second item</li>
+</ITStack>
+```
+
+## Variants & Patterns
+
+### Direction
+- **column** — default; stacks children vertically.
+- **row** — stacks children horizontally (toolbars, button groups).
+- **row-reverse** / **column-reverse** — reverse the visual order.
+
+### Spacing
+- Measured in 0.25rem units (Tailwind spacing scale).
+- `spacing={0}` = no gap (compact).
+- `spacing={4}` = 1rem (comfortable).
+- `spacing={8}` = 2rem (breathing room).
+
+### Justify Content (main axis)
+- **start** — children packed at the start.
+- **center** — children centered.
+- **end** — children packed at the end.
+- **between** — first/last at edges, others spaced evenly.
+- **around** — equal space around each child.
+- **evenly** — equal space between all items and edges.
+
+### Align Items (cross axis)
+- **start** — align to the start of the cross axis.
+- **center** — center on the cross axis.
+- **end** — align to the end.
+- **stretch** — stretch to fill (default CSS flex behavior).
+- **baseline** — align text baselines.
+
+### Wrap
+- **nowrap** — default; overflow if needed.
+- **wrap** — children wrap to the next line when out of space (great for tags, chips).
+- **wrap-reverse** — wrap in reverse order.
+
+### Divider
+- Takes a single React element, cloned between each pair of children.
+- Common dividers: `<hr />`, `<div className="h-px bg-slate-200" />`, vertical bars for row direction.
+
+## Notes
+
+- ITStack is **always** `display: flex` — use `direction` to switch between vertical/horizontal.
+- For complex multi-axis layouts (direction + wrap + alignment simultaneously), prefer **ITFlex**.
+- For CSS Grid layouts (columns), use **ITGrid**.
+- Spacing is applied via the CSS `gap` property, cleanly separating layout from children.
+- Set `as="ul"` and wrap children in `<li>` for semantic list rendering.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/stack/stack.props.ts

@@ -1,19 +1,37 @@
 import { ReactNode, CSSProperties, ElementType } from "react";
 
+/** Flex direction: "row" | "column" | "row-reverse" | "column-reverse". */
 export type StackDirection = "row" | "column" | "row-reverse" | "column-reverse";
+
+/** Cross-axis alignment: "start" | "end" | "center" | "stretch" | "baseline". */
 export type StackAlignment = "start" | "end" | "center" | "stretch" | "baseline";
+
+/** Main-axis justification: "start" | "end" | "center" | "between" | "around" | "evenly". */
 export type StackJustify = "start" | "end" | "center" | "between" | "around" | "evenly";
+
+/** Flex wrap behaviour: "nowrap" | "wrap" | "wrap-reverse". */
 export type StackWrap = "nowrap" | "wrap" | "wrap-reverse";
 
+/** Props for the ITStack flex layout component. */
 export interface ITStackProps {
+  /** Stack children elements. */
   children?: ReactNode;
+  /** Flex direction. Default: "column". */
   direction?: StackDirection;
+  /** Spacing between children in 0.25rem units (0–12). Default: 0. */
   spacing?: number;
+  /** Cross-axis alignment. */
   alignItems?: StackAlignment;
+  /** Main-axis justification. */
   justifyContent?: StackJustify;
+  /** Whether children should wrap. */
   flexWrap?: StackWrap;
+  /** Optional divider element inserted between children. */
   divider?: ReactNode;
+  /** Additional CSS classes on the container. */
   className?: string;
+  /** Inline styles on the container. */
   style?: CSSProperties;
+  /** HTML element type to render as. Default: "div". */
   as?: ElementType;
 }