@axzydev/axzy_ui_system 1.2.7 → 1.2.8

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;
 }

package/src/components/stack/stack.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
 import ITStack from "./stack";
 
 const meta: Meta<typeof ITStack> = {
@@ -9,19 +10,31 @@ const meta: Meta<typeof ITStack> = {
     direction: {
       control: "select",
       options: ["row", "column", "row-reverse", "column-reverse"],
+      description: "Flex direction. Default: column.",
+    },
+    spacing: {
+      control: { type: "range", min: 0, max: 16, step: 1 },
+      description: "Gap between children in 0.25rem units. Default: 0.",
     },
-    spacing: { control: { type: "range", min: 0, max: 16, step: 1 } },
     alignItems: {
       control: "select",
       options: [undefined, "start", "end", "center", "stretch", "baseline"],
+      description: "Cross-axis alignment.",
     },
     justifyContent: {
       control: "select",
       options: [undefined, "start", "end", "center", "between", "around", "evenly"],
+      description: "Main-axis justification.",
     },
     flexWrap: {
       control: "select",
       options: [undefined, "nowrap", "wrap", "wrap-reverse"],
+      description: "Flex wrap behavior.",
+    },
+    as: {
+      control: "select",
+      options: ["div", "section", "nav", "ul", "ol", "main", "article", "header", "footer", "aside", "form"],
+      description: "HTML element to render.",
     },
   },
 };
@@ -35,8 +48,10 @@ const Box = ({ children, className = "" }: { children: string; className?: strin
   </div>
 );
 
+// ── Basic direction examples ──
+
 export const Vertical: Story = {
-  args: { direction: "column", spacing: 2, children: null },
+  args: { direction: "column", spacing: 2 },
   render: (args) => (
     <ITStack {...args}>
       <Box>Item 1</Box>
@@ -47,7 +62,7 @@ export const Vertical: Story = {
 };
 
 export const Horizontal: Story = {
-  args: { direction: "row", spacing: 2, children: null },
+  args: { direction: "row", spacing: 2 },
   render: (args) => (
     <ITStack {...args}>
       <Box>Item 1</Box>
@@ -57,23 +72,213 @@ export const Horizontal: Story = {
   ),
 };
 
-export const WithDivider: Story = {
-  args: { direction: "row", spacing: 2, divider: <div className="w-px bg-gray-300 self-stretch" /> },
-  render: (args) => (
-    <ITStack {...args}>
-      <Box>Item 1</Box>
-      <Box>Item 2</Box>
-      <Box>Item 3</Box>
+// ── All direction variants ──
+
+export const AllDirections: Story = {
+  render: () => (
+    <ITStack spacing={6}>
+      {(["column", "row", "column-reverse", "row-reverse"] as const).map((dir) => (
+        <div key={dir}>
+          <p className="text-xs font-semibold text-slate-400 mb-1.5 uppercase tracking-wider">{dir}</p>
+          <div className="bg-slate-50 dark:bg-slate-900/50 rounded-xl p-4 border border-dashed border-slate-200 dark:border-slate-700">
+            <ITStack direction={dir} spacing={2}>
+              <Box>First</Box>
+              <Box>Second</Box>
+              <Box>Third</Box>
+            </ITStack>
+          </div>
+        </div>
+      ))}
     </ITStack>
   ),
 };
 
-export const Centered: Story = {
-  args: { direction: "row", spacing: 4, alignItems: "center", justifyContent: "center", className: "h-40 bg-gray-50 rounded-xl" },
-  render: (args) => (
-    <ITStack {...args}>
-      <Box>Center</Box>
-      <Box>Middle</Box>
+// ── Spacing variants ──
+
+export const SpacingVariants: Story = {
+  render: () => (
+    <ITStack spacing={4}>
+      {[0, 1, 2, 4, 6, 8, 10, 12].map((gap) => (
+        <div key={gap}>
+          <p className="text-xs font-semibold text-slate-400 mb-1.5">spacing={gap} — {gap * 0.25}rem</p>
+          <div className="bg-slate-50 dark:bg-slate-900/50 rounded-xl p-4">
+            <ITStack direction="row" spacing={gap}>
+              <Box>Item 1</Box>
+              <Box>Item 2</Box>
+              <Box>Item 3</Box>
+            </ITStack>
+          </div>
+        </div>
+      ))}
+    </ITStack>
+  ),
+};
+
+// ── Justify Content showcase ──
+
+export const JustifyContent: Story = {
+  render: () => (
+    <ITStack spacing={2}>
+      {(["start", "center", "end", "between", "around", "evenly"] as const).map((j) => (
+        <div key={j}>
+          <p className="text-xs font-semibold text-slate-400 mb-1.5">{j}</p>
+          <div className="bg-slate-50 dark:bg-slate-900/50 rounded-xl p-4">
+            <ITStack direction="row" spacing={2} justifyContent={j} className="w-full">
+              <div className="w-10 h-10 rounded-lg bg-primary-400/60" />
+              <div className="w-10 h-10 rounded-lg bg-cyan-400/60" />
+              <div className="w-10 h-10 rounded-lg bg-violet-400/60" />
+            </ITStack>
+          </div>
+        </div>
+      ))}
+    </ITStack>
+  ),
+};
+
+// ── Align Items showcase ──
+
+export const AlignItems: Story = {
+  render: () => (
+    <ITStack spacing={2}>
+      {(["start", "center", "end", "stretch", "baseline"] as const).map((a) => (
+        <div key={a}>
+          <p className="text-xs font-semibold text-slate-400 mb-1.5">{a}</p>
+          <div className="bg-slate-50 dark:bg-slate-900/50 rounded-xl p-4">
+            <ITStack direction="row" spacing={2} alignItems={a} className="h-20 border border-dashed border-slate-300 dark:border-slate-600 rounded-lg">
+              <div className="w-10 h-6 rounded bg-primary-400/60" />
+              <div className="w-10 h-12 rounded bg-cyan-400/60" />
+              <div className="w-10 h-8 rounded bg-violet-400/60" />
+            </ITStack>
+          </div>
+        </div>
+      ))}
+    </ITStack>
+  ),
+};
+
+// ── With interactive controls ──
+
+export const Playground: Story = {
+  render: function PlaygroundStory() {
+    const [direction, setDirection] = useState<"row" | "column">("column");
+    const [spacing, setSpacing] = useState(3);
+    const [showDivider, setShowDivider] = useState(false);
+
+    return (
+      <ITStack spacing={6}>
+        <ITStack direction="row" spacing={3} flexWrap="wrap">
+          <label className="flex items-center gap-2 text-sm">
+            <span className="text-slate-500">Direction:</span>
+            <select value={direction} onChange={(e) => setDirection(e.target.value as any)} className="rounded border px-2 py-1 text-sm bg-white dark:bg-slate-800">
+              <option value="column">Column</option>
+              <option value="row">Row</option>
+            </select>
+          </label>
+          <label className="flex items-center gap-2 text-sm">
+            <span className="text-slate-500">Spacing:</span>
+            <input type="range" min={0} max={12} value={spacing} onChange={(e) => setSpacing(Number(e.target.value))} className="w-24" />
+            <span className="text-xs font-mono">{spacing}</span>
+          </label>
+          <label className="flex items-center gap-2 text-sm">
+            <input type="checkbox" checked={showDivider} onChange={(e) => setShowDivider(e.target.checked)} />
+            <span className="text-slate-500">Divider</span>
+          </label>
+        </ITStack>
+        <div className="bg-slate-50 dark:bg-slate-900/50 rounded-xl p-6 border border-dashed border-slate-200 dark:border-slate-700">
+          <ITStack
+            direction={direction}
+            spacing={spacing}
+            divider={showDivider ? <div className={`${direction === "row" ? "w-px h-8" : "h-px w-full"} bg-slate-300 dark:bg-slate-600 self-center`} /> : undefined}
+          >
+            <Box>Item 1</Box>
+            <Box>Item 2</Box>
+            <Box>Item 3</Box>
+          </ITStack>
+        </div>
+        <pre className="text-xs bg-slate-950 text-slate-200 rounded-lg p-3 overflow-x-auto">
+{`<ITStack direction="${direction}" spacing={${spacing}}${showDivider ? `\n  divider={${direction === "row" ? '<div className="w-px h-8" />' : '<div className="h-px w-full" />'}}` : ""}>
+  <Box>Item 1</Box>
+  <Box>Item 2</Box>
+  <Box>Item 3</Box>
+</ITStack>`}
+        </pre>
+      </ITStack>
+    );
+  },
+};
+
+// ── Real-world examples ──
+
+export const ToolbarExample: Story = {
+  render: () => (
+    <div className="bg-white dark:bg-slate-800 rounded-xl border border-slate-200 dark:border-slate-700 p-4 w-full max-w-lg">
+      <ITStack direction="row" spacing={2} justifyContent="between" alignItems="center">
+        <ITStack direction="row" spacing={1} alignItems="center">
+          <p className="text-sm font-bold text-slate-700 dark:text-slate-200">Document</p>
+          <span className="text-xs text-slate-400">• Saved</span>
+        </ITStack>
+        <ITStack direction="row" spacing={1}>
+          <div className="px-3 py-1.5 rounded-md bg-primary-500 text-white text-xs font-medium cursor-pointer">Save</div>
+          <div className="px-3 py-1.5 rounded-md bg-slate-100 dark:bg-slate-700 text-slate-600 dark:text-slate-300 text-xs cursor-pointer">Cancel</div>
+        </ITStack>
+      </ITStack>
+    </div>
+  ),
+};
+
+export const FormRowExample: Story = {
+  render: () => (
+    <div className="bg-white dark:bg-slate-800 rounded-xl border border-slate-200 dark:border-slate-700 p-4 w-full max-w-xl">
+      <ITStack direction="row" spacing={3} flexWrap="wrap">
+        {["First Name", "Last Name", "Email"].map((label) => (
+          <div key={label} className="flex-1 min-w-[140px]">
+            <p className="text-xs font-semibold text-slate-500 mb-1">{label}</p>
+            <input className="w-full h-9 rounded-md border border-slate-200 dark:border-slate-600 bg-slate-50 dark:bg-slate-800/50 px-3 text-sm" placeholder={label} readOnly />
+          </div>
+        ))}
+      </ITStack>
+    </div>
+  ),
+};
+
+export const TagCloudExample: Story = {
+  render: () => {
+    const tags = ["React", "TypeScript", "Tailwind CSS", "Vite", "Storybook", "CSS Variables", "Flexbox", "Accessibility", "Dark Mode", "Theming", "Responsive"];
+    return (
+      <div className="bg-white dark:bg-slate-800 rounded-xl border border-slate-200 dark:border-slate-700 p-4 w-full max-w-lg">
+        <ITStack direction="row" spacing={1} flexWrap="wrap">
+          {tags.map((tag) => (
+            <span key={tag} className="px-2.5 py-1 rounded-full text-xs font-medium bg-primary-50 text-primary-700 dark:bg-primary-900/30 dark:text-primary-400 border border-primary-200 dark:border-primary-800">
+              {tag}
+            </span>
+          ))}
+        </ITStack>
+      </div>
+    );
+  },
+};
+
+export const SectionWithDividers: Story = {
+  render: () => (
+    <div className="bg-white dark:bg-slate-800 rounded-xl border border-slate-200 dark:border-slate-700 w-full max-w-sm">
+      <ITStack spacing={0} divider={<div className="h-px bg-slate-100 dark:bg-slate-700" />}>
+        {["Profile Settings", "Security & Privacy", "Notifications", "Billing & Plans", "API Keys"].map((item, i) => (
+          <div key={item} className="flex items-center justify-between py-3 px-4 hover:bg-slate-50 dark:hover:bg-slate-800/50 cursor-pointer transition-colors">
+            <span className="text-sm text-slate-700 dark:text-slate-200">{item}</span>
+            <span className="text-slate-300 dark:text-slate-600">→</span>
+          </div>
+        ))}
+      </ITStack>
+    </div>
+  ),
+};
+
+export const CenteredHero: Story = {
+  render: () => (
+    <ITStack spacing={4} alignItems="center" justifyContent="center" className="h-64 bg-slate-50 dark:bg-slate-900/50 rounded-xl border border-dashed border-slate-200 dark:border-slate-700">
+      <h2 className="text-2xl font-bold text-slate-800 dark:text-white">Welcome back</h2>
+      <p className="text-slate-500 dark:text-slate-400 text-sm">Select a workspace to continue</p>
+      <div className="px-4 py-2 rounded-lg bg-primary-500 text-white text-sm font-medium cursor-pointer">Get Started</div>
     </ITStack>
   ),
 };

package/src/components/stack/stack.tsx

@@ -32,6 +32,27 @@ const wrapMap: Record<StackWrap, string> = {
   "wrap-reverse": "flex-wrap-reverse",
 };
 
+/**
+ * Simplified flex stack with consistent spacing (gap) for arranging children in a row or column.
+ * Supports an optional divider element between children.
+ *
+ * @example
+ * ```tsx
+ * <ITStack direction="row" spacing={4} alignItems="center">
+ *   <ITButton>Cancel</ITButton>
+ *   <ITButton variant="primary">Save</ITButton>
+ * </ITStack>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <ITStack direction="column" spacing={2} divider={<hr />}>
+ *   <p>Item 1</p>
+ *   <p>Item 2</p>
+ *   <p>Item 3</p>
+ * </ITStack>
+ * ```
+ */
 export default function ITStack({
   children,
   direction = "column",

package/src/components/stat-card/stat-card.doc.mdx

@@ -0,0 +1,48 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './stat-card.stories';
+
+<Meta of={Stories} />
+
+# ITStatCard
+
+Metric card displaying a label, value, and optional trend indicator with color theme.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | — | Card label |
+| `value` | `string \| number` | — | Primary metric value |
+| `trend` | `'up' \| 'down' \| 'neutral'` | — | Trend direction |
+| `trendValue` | `string \| number` | — | Trend percentage or value |
+| `icon` | `ReactNode` | — | Icon displayed on the card |
+| `color` | `string` | — | Color theme |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Card size variant |
+| `subtitle` | `string` | — | Secondary descriptive text |
+| `loading` | `boolean` | `false` | Show loading skeleton |
+| `onClick` | `() => void` | — | Click handler |
+
+## Usage
+
+```tsx
+import { ITStatCard } from '@axzydev/axzy_ui_system';
+
+<ITStatCard label="Revenue" value="$12,430" trend="up" trendValue="12.5%" color="success" />
+<ITStatCard label="Users" value="1,024" icon={<UsersIcon />} size="lg" />
+<ITStatCard label="Bounce Rate" value="42%" trend="down" trendValue="3.1%" color="danger" subtitle="vs last week" />
+<ITStatCard label="Loading" loading />
+```
+
+## Notes
+
+- `trend` direction renders an arrow indicator with formatted `trendValue`
+- `loading` shows a skeleton placeholder for async data
+- Three sizes: sm, md, lg
+- Clickable via `onClick` for drill-down dashboards
+- `subtitle` provides supporting context below the value
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/stat-card/stat-card.props.ts

@@ -1,13 +1,22 @@
 import { ReactNode, CSSProperties } from "react";
 
 export interface ITStatCardProps {
+  /** The metric label displayed above the value. */
   label: string;
+  /** The primary numeric or string value shown in the card. */
   value: string | number;
+  /** Optional trend indicator text (e.g. "+12%", "-3"). */
   trend?: string;
+  /** Direction of the trend, used to color the trend badge. */
   trendDirection?: "up" | "down" | "neutral";
+  /** Icon element rendered next to the label in the top-right corner. */
   icon?: ReactNode;
+  /** Background color class for the card (e.g. "bg-primary-50 dark:bg-primary-950/20"). */
   color?: string;
+  /** Additional CSS classes for the outermost wrapper. */
   className?: string;
+  /** Inline styles applied to the card container. */
   style?: CSSProperties;
+  /** Click handler — when provided the card gains button semantics. */
   onClick?: () => void;
 }

package/src/components/stat-card/stat-card.tsx

@@ -8,6 +8,16 @@ const trendColors = {
   neutral: "text-slate-500 bg-slate-100 dark:text-slate-400 dark:bg-slate-800",
 };
 
+/**
+ * A metric card displaying a value with an optional trend indicator and icon.
+ * Automatically detects trend direction from the trend string prefix.
+ *
+ * @example
+ * <ITStatCard label="Revenue" value="$12,430" trend="+12%" trendDirection="up" icon={<FaDollarSign />} />
+ *
+ * @example
+ * <ITStatCard label="Users" value={1042} trend="-3%" trendDirection="down" onClick={() => navigate("/users")} />
+ */
 export default function ITStatCard({
   label,
   value,

package/src/components/stepper/stepper.doc.mdx

@@ -0,0 +1,54 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './stepper.stories';
+
+<Meta of={Stories} />
+
+# ITStepper
+
+Step-by-step wizard indicator for multi-step workflows with configurable layout and icons.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `steps` | `{ label: string; description?: string; icon?: ReactNode }[]` | — | Step definitions |
+| `activeStep` | `number` | `0` | Zero-indexed active step |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout orientation |
+| `variant` | `'default' \| 'dot' \| 'icon'` | `'default'` | Visual style variant |
+| `clickable` | `boolean` | `false` | Allow clicking steps to navigate |
+| `onStepClick` | `(index: number) => void` | — | Click handler for step navigation |
+| `color` | `string` | — | Color theme |
+
+## Usage
+
+```tsx
+import { ITStepper } from '@axzydev/axzy_ui_system';
+
+const steps = [
+  { label: 'Details', description: 'Enter your info' },
+  { label: 'Payment', description: 'Choose method' },
+  { label: 'Confirm', description: 'Review and submit' },
+];
+
+<ITStepper steps={steps} activeStep={0} />
+<ITStepper steps={steps} activeStep={1} variant="dot" orientation="vertical" />
+<ITStepper steps={[
+  { label: 'Upload', icon: <UploadIcon /> },
+  { label: 'Review', icon: <CheckIcon /> },
+]} variant="icon" />
+<ITStepper steps={steps} clickable onStepClick={(i) => console.log(i)} />
+```
+
+## Notes
+
+- `variant="default"` shows numbered step circles
+- `variant="dot"` shows minimal dot indicators
+- `variant="icon"` uses custom icons per step instead of numbers
+- `clickable` + `onStepClick` enables step-based navigation
+- Optional `description` renders below each step label
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/stepper/stepper.props.ts

@@ -9,18 +9,28 @@ export interface Step {
 }
 
 export interface ITStepperProps {
+  /** Array of step objects defining label, content, and optional icon. */
   steps: Step[];
+  /** Zero-based index of the currently active step. */
   currentStep: number;
+  /** Called when the user clicks "Finish" on the last step. */
   onFinish?: () => void;
+  /** Called whenever the active step changes, receiving the new index. */
   onStepChange?: (step: number) => void;
+  /** Whether clicking on completed or current step indicators jumps to that step. */
   allowClickToJump?: boolean;
+  /** When true, renders step icons (if provided) instead of numeric indicators. */
   useIcons?: boolean;
+  /** Disables the "Next" / "Finish" button. */
   disableNext?: boolean;
+  /** Additional CSS classes for the outermost wrapper. */
   containerClassName?: string;
+  /** Additional CSS classes for the content panel. */
   stepClassName?: string;
+  /** Makes the step content area vertically scrollable. */
   scrollableContent?: boolean;
+  /** Maximum height of the scrollable content area (CSS value, e.g. "400px"). */
   maxContentHeight?: string;
-  
   /**
    * Semantic theme color for active steps and buttons.
    * Default: 'primary'

package/src/components/stepper/stepper.tsx

@@ -6,6 +6,21 @@ import ITButton from "../button/button";
 import { FaChevronLeft, FaChevronRight, FaCheck } from "react-icons/fa";
 import ITText from "@/components/text/text";
 
+/**
+ * A step-by-step wizard / progress indicator with animated content transitions,
+ * clickable step navigation, and configurable icons.
+ *
+ * @example
+ * <ITStepper
+ *   steps={[
+ *     { label: "Details", content: <StepOneForm /> },
+ *     { label: "Review", content: <StepTwoReview />, icon: <FaClipboardCheck /> },
+ *   ]}
+ *   currentStep={0}
+ *   onStepChange={setStep}
+ *   onFinish={() => alert("Done!")}
+ * />
+ */
 export default function ITStepper({
   steps,
   currentStep,

package/src/components/table/table.doc.mdx

@@ -0,0 +1,58 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './table.stories';
+
+<Meta of={Stories} />
+
+# ITTable
+
+Basic data table with column definitions, sorting, and configurable visual variants.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `{ key: string; label: string; render?: (value, row) => ReactNode; sortable?: boolean; width?: string }[]` | — | Column definitions |
+| `data` | `Record<string, any>[]` | — | Row data array |
+| `variant` | `'default' \| 'striped' \| 'bordered'` | `'default'` | Visual style variant |
+| `sortKey` | `string` | — | Current sort column key |
+| `sortDirection` | `'asc' \| 'desc'` | — | Current sort direction |
+| `onSort` | `(key: string, direction: 'asc' \| 'desc') => void` | — | Sort handler |
+| `onRowClick` | `(row: Record<string, any>) => void` | — | Row click handler |
+| `loading` | `boolean` | `false` | Show loading state |
+| `emptyMessage` | `string` | `'No data'` | Empty state message |
+
+## Usage
+
+```tsx
+import { ITTable } from '@axzydev/axzy_ui_system';
+
+const columns = [
+  { key: 'name', label: 'Name', sortable: true },
+  { key: 'role', label: 'Role' },
+  { key: 'status', label: 'Status', render: (v) => <ITBadge>{v}</ITBadge> },
+];
+const data = [
+  { name: 'Alice', role: 'Admin', status: 'Active' },
+  { name: 'Bob', role: 'Editor', status: 'Inactive' },
+];
+
+<ITTable columns={columns} data={data} />
+<ITTable columns={columns} data={data} variant="striped" sortKey="name" sortDirection="asc" />
+<ITTable columns={columns} data={data} variant="bordered" onRowClick={(row) => console.log(row)} />
+<ITTable columns={columns} data={[]} emptyMessage="No records found" />
+<ITTable columns={columns} data={data} loading />
+```
+
+## Notes
+
+- `columns[].render` provides custom cell rendering via render function
+- `columns[].sortable` enables column header sort toggles
+- Sorting controlled via `sortKey`, `sortDirection`, and `onSort`
+- `onRowClick` fires with the row data on click
+- Three visual variants: default (no borders), striped (alternating rows), bordered (full grid)
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/table/table.props.ts

@@ -31,13 +31,30 @@ export interface Column<T = any> {
 }
 
 export interface ITTableProps<T> {
+  /** Column definitions: key, label, type, sortable behavior, filters, and custom rendering. */
   columns: Column<T>[];
+  /** Additional CSS classes for the outermost container. */
   containerClassName?: string;
+  /** The data array to render in the table body. */
   data: T[];
+  /** Visual variant: "default", "striped", "bordered", "borderless". */
   variant?: TableVariants;
+  /** Additional CSS classes for the root table wrapper. */
   className?: string;
+  /** Row size preset: "sm" | "md" | "lg". */
   size?: TableSize;
+  /** Available options for the per-page selector (e.g. [5, 10, 20]). */
   itemsPerPageOptions?: Array<number>;
+  /** Default number of rows shown per page. */
   defaultItemsPerPage?: number;
+  /** Optional title rendered above the table in the header section. */
   title?: string;
+  /** Custom card renderer for mobile/tablet responsive view. Receives the row data. */
+  renderCard?: (row: T) => React.ReactNode;
+  /** Initial view mode. Defaults to "table". */
+  defaultView?: "table" | "cards";
+  /** Whether to show vertical borders between columns. Defaults to true. */
+  showVerticalBorder?: boolean;
+  /** Custom class for vertical borders (overrides the default subtle gray). */
+  verticalBorderClassname?: string;
 }