@axzydev/axzy_ui_system 1.3.0 → 1.3.2

package/src/components/molecules/masked-input/masked-input.doc.mdx

@@ -0,0 +1,78 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as StoriesData from './masked-input.stories';
+
+<Meta of={StoriesData} />
+
+# ITMaskedInput
+
+Input con máscara de formato: defines un patrón y el usuario solo escribe los caracteres útiles; los separadores se insertan solos y los huecos se pintan con un carácter de relleno.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | required | Nombre del campo para formularios. |
+| `mask` | `string` | required | Patrón: `9`=dígito, `A`=letra (mayúscula), `a`=letra, `x`=alfanumérico, `*`=cualquiera. Cualquier otro carácter es un separador literal auto-insertado. |
+| `value` | `string` | — | Valor limpio (raw): solo caracteres útiles, sin separadores ni relleno. |
+| `onChange` | `(e) => void` | required | `e.target.value` es el valor raw. |
+| `onBlur` | `(e) => void` | — | Blur del input. |
+| `onComplete` | `(value) => void` | — | Dispara cuando la máscara queda llena. |
+| `pattern` | `RegExp` | — | Regex validada con full-match contra el raw en blur; si no cumple muestra error. |
+| `placeholderChar` | `string` | `"_"` | Carácter pintado en slots vacíos. |
+| `variant` | `ColorsTypes` | `"primary"` | Color de acento del tema. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Tamaño del input. |
+| `label` | `string` | — | Etiqueta sobre el input. |
+| `disabled` | `boolean` | `false` | Desactiva el input. |
+| `required` | `boolean` | `false` | Marca el campo como requerido. |
+| `touched` | `boolean` | `false` | Indica si el campo fue tocado. |
+| `error` | `string \| boolean` | — | Estado de error. |
+| `className` | `string` | — | Clases del wrapper externo. |
+| `containerClassName` | `string` | — | Clases del contenedor del input. |
+| `iconLeft` / `iconRight` | `ReactNode` | — | Iconos laterales. |
+| `autoFocus` | `boolean` | `false` | Enfoca al montar. |
+
+## Tokens del mask
+
+| Token | Acepta |
+|-------|--------|
+| `9` | un dígito |
+| `A` | una letra (se guarda en mayúsculas) |
+| `a` | una letra (tal cual) |
+| `x` | un carácter alfanumérico |
+| `*` | cualquier carácter |
+| cualquier otro | literal insertado solo (p.ej. `-`, `/`, `(`, `)`, espacio) |
+
+## Usage
+
+```tsx
+import { ITMaskedInput } from '@axzydev/axzy_ui_system';
+
+// Código de activación
+<ITMaskedInput
+  name="code"
+  mask="xxxx-xxxx-xxxx"
+  label="Código"
+  onChange={(e) => setCode(e.target.value)}
+/>
+
+// Teléfono con validación regex sobre el valor limpio
+<ITMaskedInput
+  name="phone"
+  mask="(999) 999-9999"
+  pattern={/^\d{10}$/}
+  onChange={(e) => setPhone(e.target.value)}
+/>
+```
+
+## Notes
+
+- ¿El valor? **Solo caracteres útiles**: escribir `ABC1-2345-6789` devuelve `ABC123456789` en `onChange`.
+- El cursor salta a huecos vacíos con selección automática; borrar un separador lo vuelve a insertar.
+- `pattern` valida contra el raw completo (full-match); el mensaje de error genérico es "Formato inválido" salvo que pases `error` como string.
+- `onComplete` es ideal para tarjetas, CVV o códigos de un solo uso.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/molecules/masked-input/masked-input.props.ts

@@ -0,0 +1,58 @@
+import { ColorsTypes } from "@/types/colors.types";
+import { SizesTypes } from "@/types/sizes.types";
+import { ReactNode } from "react";
+
+export interface ITMaskedInputProps {
+  /** Unique name attribute for the underlying input element. */
+  name: string;
+  /**
+   * Mask pattern. Tokens are filled by the user and everything else is an
+   * auto-inserted literal.
+   * - `9` — digit
+   * - `A` — letter (stored uppercase)
+   * - `a` — letter
+   * - `x` — alphanumeric
+   * - `*` — any character
+   * - any other character ( `-`, `/`, `(`, `)`, ` `, `.` ) is a literal separator
+   * @example "xxxx-xxxx-xxxx"
+   * @example "(999) 999-9999"
+   * @example "9999-9999-9999-9999"
+   */
+  mask: string;
+  /** Clean value containing only the useful characters (no separators, no placeholders). */
+  value?: string;
+  /** Called when the masked value changes. `event.target.value` is the raw value without separators. */
+  onChange: (event: { target: { name: string; value: string } }) => void;
+  /** Called when the input loses focus. */
+  onBlur?: (event: React.FocusEvent<HTMLInputElement>) => void;
+  /** Fired when all token slots are filled with valid characters. */
+  onComplete?: (value: string) => void;
+  /** Optional regex full-matched against the raw value to validate the field (e.g. `/^\\d{16}$/`). */
+  pattern?: RegExp;
+  /** Character shown for empty token slots. @default "_" */
+  placeholderChar?: string;
+  /** Color variant matching the design system (ColorsTypes). @default "primary" */
+  variant?: ColorsTypes;
+  /** Size preset: "sm" | "md" | "lg". @default "md" */
+  size?: SizesTypes;
+  /** Label displayed above the input. */
+  label?: string;
+  /** Disables the input. @default false */
+  disabled?: boolean;
+  /** Marks the field as required. */
+  required?: boolean;
+  /** Visually indicates the field has been interacted with. */
+  touched?: boolean;
+  /** Error state — pass a string message or `true` for default styling. */
+  error?: string | boolean;
+  /** Additional CSS classes for the outer wrapper element. */
+  className?: string;
+  /** Additional CSS classes for the underlying input container. */
+  containerClassName?: string;
+  /** Icon element rendered on the left side of the input. */
+  iconLeft?: ReactNode;
+  /** Icon element rendered on the right side of the input. */
+  iconRight?: ReactNode;
+  /** Auto-focus the input on mount. @default false */
+  autoFocus?: boolean;
+}

package/src/components/molecules/masked-input/masked-input.stories.tsx

@@ -0,0 +1,126 @@
+import type { Meta } from '@storybook/react';
+import { useState } from 'react';
+import ITMaskedInput from './masked-input';
+
+const meta = {
+  title: 'Components/Form Elements/ITMaskedInput',
+  component: ITMaskedInput,
+  parameters: { layout: 'padded' },
+  argTypes: {
+    mask: { control: 'text' },
+    placeholderChar: { control: 'text' },
+    onChange: { action: 'changed' },
+    onComplete: { action: 'completed' },
+    disabled: { control: 'boolean' },
+    error: { control: 'text' },
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'success', 'danger', 'warning', 'info', 'purple', 'gray'],
+    },
+    size: { control: 'select', options: ['sm', 'md', 'lg'] },
+  },
+} satisfies Meta<typeof ITMaskedInput>;
+
+export default meta;
+
+function CodeMaskedWrapper(args: any) {
+  const [value, setValue] = useState<string>('');
+  return (
+    <div className="w-full max-w-xs">
+      <ITMaskedInput
+        {...args}
+        value={value}
+        onChange={(e) => {
+          setValue(e.target.value);
+          args.onChange(e);
+        }}
+      />
+      <p className="mt-2 text-xs font-mono text-slate-500">
+        raw: {value || '(vacío)'}
+      </p>
+    </div>
+  );
+}
+
+export const Alphanumeric: any = {
+  render: CodeMaskedWrapper,
+  args: {
+    name: 'code',
+    label: 'Código único',
+    mask: 'xxxx-xxxx-xxxx',
+  },
+};
+
+export const Phone: any = {
+  render: CodeMaskedWrapper,
+  args: {
+    name: 'phone',
+    label: 'Teléfono',
+    mask: '(999) 999-9999',
+  },
+};
+
+export const CreditCard: any = {
+  render: CodeMaskedWrapper,
+  args: {
+    name: 'card',
+    label: 'Número de tarjeta',
+    mask: '9999-9999-9999-9999',
+    onComplete: undefined,
+  },
+};
+
+const PhoneValidatedWrapper = (args: any) => {
+  const [value, setValue] = useState<string>('5512345678');
+  const [complete, setComplete] = useState<string | null>(null);
+  return (
+    <div className="w-full max-w-xs">
+      <ITMaskedInput
+        {...args}
+        value={value}
+        onChange={(e) => {
+          setValue(e.target.value);
+          args.onChange(e);
+          setComplete(null);
+        }}
+        onComplete={(v) => setComplete(v)}
+      />
+      {complete && (
+        <p className="mt-2 text-xs font-mono text-emerald-600">
+          ¡Completo! raw: {complete}
+        </p>
+      )}
+    </div>
+  );
+};
+
+export const WithPattern: any = {
+  render: PhoneValidatedWrapper,
+  args: {
+    name: 'validated_phone',
+    label: 'Teléfono válido (regex)',
+    mask: '999-999-9999',
+    pattern: /^\d{9}$/,
+  },
+};
+
+export const Sizes: any = {
+  render: () => (
+    <div className="flex flex-col gap-4 w-full max-w-xs">
+      <ITMaskedInput name="sz_sm" label="Small" mask="xxxx-xxxx" size="sm" onChange={() => {}} />
+      <ITMaskedInput name="sz_md" label="Medium" mask="xxxx-xxxx" size="md" onChange={() => {}} />
+      <ITMaskedInput name="sz_lg" label="Large" mask="xxxx-xxxx" size="lg" onChange={() => {}} />
+    </div>
+  ),
+};
+
+export const Disabled: any = {
+  args: {
+    name: 'disabled_code',
+    label: 'Deshabilitado',
+    mask: 'xxxx-xxxx',
+    value: 'abcd',
+    disabled: true,
+    onChange: () => {},
+  },
+};

package/src/components/molecules/masked-input/masked-input.tsx

@@ -0,0 +1,244 @@
+import React, { useRef, useState, useMemo } from "react";
+import clsx from "clsx";
+import ITInput from "@/components/atoms/input/input";
+import { ITMaskedInputProps } from "./masked-input.props";
+
+type Token = "9" | "A" | "a" | "x" | "*";
+
+type MaskRule =
+  | { type: "token"; token: Token }
+  | { type: "literal"; char: string };
+
+const TOKEN_SET = /[9Aax*]/;
+
+function parseMask(mask: string): MaskRule[] {
+  return mask.split("").map((ch) =>
+    TOKEN_SET.test(ch)
+      ? { type: "token", token: ch as Token }
+      : { type: "literal", char: ch }
+  );
+}
+
+function matchToken(token: Token, ch: string): boolean {
+  switch (token) {
+    case "9":
+      return /\d/.test(ch);
+    case "A":
+    case "a":
+      return /[A-Za-z]/.test(ch);
+    case "x":
+      return /[A-Za-z0-9]/.test(ch);
+    case "*":
+      return ch.length > 0;
+    default:
+      return false;
+  }
+}
+
+function extract(input: string, rules: MaskRule[], maskChar: string): string {
+  let raw = "";
+  let slot = 0;
+  for (const ch of input) {
+    while (slot < rules.length && rules[slot].type === "literal") slot++;
+    if (slot >= rules.length) break;
+    const rule = rules[slot];
+    if (
+      rule.type === "token" &&
+      ch !== maskChar &&
+      matchToken(rule.token, ch)
+    ) {
+      raw += rule.token === "A" ? ch.toUpperCase() : ch;
+      slot++;
+    }
+  }
+  return raw;
+}
+
+function format(raw: string, rules: MaskRule[], maskChar: string): string {
+  let out = "";
+  let idx = 0;
+  for (const rule of rules) {
+    if (rule.type === "literal") {
+      out += rule.char;
+    } else {
+      const ch = raw[idx];
+      out += ch !== undefined ? ch : maskChar;
+      idx++;
+    }
+  }
+  return out;
+}
+
+function countConsumed(input: string, rules: MaskRule[], upto: number, maskChar: string): number {
+  let slot = 0;
+  let n = 0;
+  for (let i = 0; i < upto && i < input.length; i++) {
+    const ch = input[i];
+    while (slot < rules.length && rules[slot].type === "literal") slot++;
+    if (slot >= rules.length) break;
+    const rule = rules[slot];
+    if (rule.type === "token" && ch !== maskChar && matchToken(rule.token, ch)) {
+      n++;
+      slot++;
+    }
+  }
+  return n;
+}
+
+function caretAfter(n: number, rules: MaskRule[]): number {
+  let pos = 0;
+  let consumed = 0;
+  for (const rule of rules) {
+    if (rule.type === "token") {
+      consumed++;
+      if (consumed > n) break;
+    }
+    pos++;
+  }
+  return pos;
+}
+
+/**
+ * Text input that applies a formatting mask while the user types, exposing only
+ * the clean (raw) value through `onChange`.
+ *
+ * The mask is defined by a pattern string. Tokens are filled by the user and
+ * any other character acts as an auto-inserted literal separator. Empty slots
+ * are painted with `placeholderChar`, so the mask is always visible.
+ *
+ * @example
+ * ```tsx
+ * <ITMaskedInput
+ *   name="code"
+ *   mask="xxxx-xxxx-xxxx"
+ *   label="Código"
+ *   onChange={(e) => setCode(e.target.value)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <ITMaskedInput
+ *   name="phone"
+ *   mask="(999) 999-9999"
+ *   pattern={/^\d{10}$/}
+ *   onChange={(e) => setPhone(e.target.value)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <ITMaskedInput
+ *   name="card"
+ *   mask="9999-9999-9999-9999"
+ *   onComplete={(card) => validateCard(card)}
+ * />
+ * ```
+ */
+export default function ITMaskedInput({
+  name,
+  mask,
+  value,
+  onChange,
+  onBlur,
+  onComplete,
+  pattern,
+  placeholderChar = "_",
+  variant = "primary",
+  size = "md",
+  label,
+  disabled = false,
+  required,
+  touched,
+  error,
+  className,
+  containerClassName,
+  iconLeft,
+  iconRight,
+  autoFocus = false,
+}: ITMaskedInputProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const rawRef = useRef<string>(value ?? "");
+  const isControlled = value !== undefined;
+
+  const [internalRaw, setInternalRaw] = useState<string>(value ?? "");
+  const [invalidPattern, setInvalidPattern] = useState(false);
+
+  const rules = useMemo(() => parseMask(mask), [mask]);
+  const tokenCount = useMemo(() => rules.filter((r) => r.type === "token").length, [rules]);
+
+  const raw = isControlled ? (value ?? "") : internalRaw;
+  const display = useMemo(() => format(raw, rules, placeholderChar), [raw, rules, placeholderChar]);
+
+  const scheduleCaret = (caret: number) => {
+    const inputEl = containerRef.current?.querySelector("input");
+    if (!inputEl) return;
+    requestAnimationFrame(() => {
+      if (document.activeElement === inputEl) {
+        const pos = Math.min(caret, inputEl.value.length);
+        inputEl.setSelectionRange(pos, pos);
+      }
+    });
+  };
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const el = e.target as HTMLInputElement;
+    const inputVal = el.value ?? "";
+    const caretBefore = el.selectionStart ?? inputVal.length;
+
+    const nextRaw = extract(inputVal, rules, placeholderChar);
+    const targetCaret = caretAfter(
+      countConsumed(inputVal, rules, caretBefore, placeholderChar),
+      rules
+    );
+
+    if (nextRaw !== rawRef.current) {
+      rawRef.current = nextRaw;
+      setInternalRaw(nextRaw);
+      onChange?.({ target: { name, value: nextRaw } });
+      if (nextRaw.length === tokenCount && nextRaw.length > 0) {
+        onComplete?.(nextRaw);
+      }
+      if (invalidPattern) setInvalidPattern(false);
+    }
+
+    scheduleCaret(targetCaret);
+  };
+
+  const handleBlur = (e: React.FocusEvent<HTMLInputElement>) => {
+    if (pattern && rawRef.current.length > 0 && !pattern.test(rawRef.current)) {
+      setInvalidPattern(true);
+    }
+    onBlur?.(e);
+  };
+
+  const resolvedError = invalidPattern
+    ? typeof error === "string"
+      ? error
+      : "Formato inválido"
+    : error;
+
+  return (
+    <div ref={containerRef} className={clsx("w-full", className)}>
+      <ITInput
+        name={name}
+        type="text"
+        label={label}
+        value={display}
+        onChange={handleChange}
+        onBlur={(e) => handleBlur(e as React.FocusEvent<HTMLInputElement>)}
+        maxLength={mask.length}
+        variant={variant}
+        size={size}
+        disabled={disabled}
+        required={required}
+        touched={touched}
+        error={resolvedError}
+        containerClassName={containerClassName}
+        iconLeft={iconLeft}
+        iconRight={iconRight}
+        autoFocus={autoFocus}
+      />
+    </div>
+  );
+}

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

@@ -11,15 +11,37 @@ Basic data table with column definitions, sorting, and configurable visual varia
 
 | 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 |
+| `columns` | `Column<T>[]` | — | Column definitions: key, label, type, sortable, filter, render, actions, plus layout fields `width` (`number` px or CSS `string`), `minWidth` (px), `align` (`"left" \| "center" \| "right"`), and `truncate` (ellipsis + native `title`). |
+| `data` | `T[]` | `[]` | Row data array. |
+| `variant` | `"default" \| "striped" \| "bordered"` | `"default"` | Visual style variant. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Font-size preset (does not change padding). |
+| `containerClassName` | `string` | — | CSS classes for the outermost container. |
+| `className` | `string` | — | Declared for API compatibility but **currently not applied** by ITTable. Use `containerClassName` for the outer wrapper. |
+| `itemsPerPageOptions` | `number[]` | `[5, 10, 20]` | Page-size options shown in the paginator. |
+| `defaultItemsPerPage` | `number` | `10` | Initial rows per page. |
+| `title` | `string` | — | Optional heading rendered above the table. |
+| `renderCard` | `(row: T) => ReactNode` | — | Custom card renderer for the cards view. |
+| `defaultView` | `"table" \| "cards"` | `"table"` | Initial view mode. |
+| `showVerticalBorder` | `boolean` | `true` | Show vertical borders between columns. |
+| `verticalBorderClassname` | `string` | — | Custom class for the vertical borders. |
+| `onRowClick` | `(row: T, event: MouseEvent<HTMLElement> \| KeyboardEvent<HTMLElement>) => void` | — | Row/card activation. `MouseEvent` for pointer, `KeyboardEvent` for Enter/Space. Skipped when the interaction starts inside an interactive child. |
+| `layout` | `"auto" \| "fixed"` | `"auto"` | Table layout algorithm. `"fixed"` honors column `width` values and drops the `min-w-max` / `min-w-[150px]` floors so content no longer forces horizontal scrolling. |
+| `density` | `"compact" \| "normal" \| "comfortable"` | `"normal"` | Cell padding / row-height preset. Independent of `size`, which only controls font-size. |
+| `autoCardBreakpoint` | `number` | `0` | Container width (px) below which the table automatically falls back to the cards view. `0` disables the fallback. |
+| `virtualized` | `boolean` | `false` | Renders only the visible row window with spacer rows preserving scroll height. Table view only; cards view is never virtualized. |
+| `virtualizedMaxHeight` | `number` | `400` | Max height (px) of the virtualized scroll container. Only used when `virtualized` is true. |
+| `rowHeight` | `number` | `getRowHeight(size, density)` | Assumed uniform row height (px). Size-aware: `size="md"` baseline is 33 / 45 / 53 for compact / normal / comfortable; `size` shifts it by the font-size line box (sm 16px / md 20px / lg 28px). |
+| `overscan` | `number` | `5` | Extra rows rendered above and below the viewport to avoid blank gaps. |
+| `stickyHeader` | `boolean` | `false` | Keeps header cells sticky while the virtualized body scrolls. Only effective when `virtualized` is true. |
+
+### Column fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `width` | `number \| string` | — | Fixed column width. `number` = px, `string` = any CSS length (e.g. `"20%"`). A `<colgroup>` is only emitted when at least one column sets it. |
+| `minWidth` | `number` | — | Minimum column width in px, applied to header and body cells via inline style. |
+| `align` | `"left" \| "center" \| "right"` | `"left"` | Horizontal alignment of the column's header and cells. |
+| `truncate` | `boolean` | `false` | Truncates overflowing cell content with an ellipsis and exposes the raw string/number via the native `title` attribute. |
 
 ## Usage
 
@@ -27,28 +49,49 @@ Basic data table with column definitions, sorting, and configurable visual varia
 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> },
+  { key: 'name', label: 'Name', type: 'string', sortable: true, filter: true },
+  { key: 'role', label: 'Role', type: 'string', filter: 'catalog', catalogOptions: { data: roles } },
+  { key: 'status', label: 'Status', type: 'boolean', filter: true },
 ];
 const data = [
-  { name: 'Alice', role: 'Admin', status: 'Active' },
-  { name: 'Bob', role: 'Editor', status: 'Inactive' },
+  { name: 'Alice', role: 'ADMIN', status: true },
+  { name: 'Bob', role: 'EDITOR', status: false },
+];
+
+<ITTable columns={columns} data={data} title="Users" />
+<ITTable columns={columns} data={data} variant="striped" size="sm" defaultItemsPerPage={5} />
+<ITTable
+  columns={columns}
+  data={data}
+  defaultView="cards"
+  onRowClick={(row, event) => console.log(row, event.type)}
+/>
+
+// No horizontal scroll: fixed layout + per-column widths + truncation
+const fixedColumns = [
+  { key: 'name',  label: 'Name',  type: 'string', width: '30%', truncate: true },
+  { key: 'email', label: 'Email', type: 'string', width: 220,    truncate: true },
+  { key: 'role',  label: 'Role',  type: 'string', width: 140,    align: 'center' },
 ];
 
-<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 />
+<ITTable columns={fixedColumns} data={data} layout="fixed" density="compact" />
 ```
 
 ## 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
+- `onRowClick` fires in **both** the table and cards views. The event is a `MouseEvent` for pointer interaction and a `KeyboardEvent` for Enter/Space activation.
+- Clicks/keys that start inside an interactive child (`button`, `a`, `input`, `select`, `textarea`, `[role="button"]`, `[role="link"]`, `[data-row-click-ignore]`) do **not** trigger `onRowClick`.
+- When `onRowClick` is omitted no `cursor-pointer`, focus ring, `tabIndex`, or `role` is added.
+- `density` controls padding/row height (`compact` 33px / `normal` 45px / `comfortable` 53px at `size="md"`); `size` changes font-size and shifts the row height by the line box (sm 16px / md 20px / lg 28px).
+- **Anti horizontal scroll recipe:** `layout="fixed"` + a `width` on every column + `truncate` on long text + `density="compact"`. `width` accepts a `number` (px) or any CSS length string (`"20%"`, `"12rem"`). A `<colgroup>` is only emitted when at least one column defines a `width`.
+- With the default `layout="auto"`, `min-w-max` stays active so column widths can still reflow as different cell content enters the window during vertical scroll. Use `layout="fixed"` + column `width` for stable widths.
+- `autoCardBreakpoint` swaps to the cards view when the container (not the viewport) is narrower than the given px value; the Table toggle is disabled while forced, the Cards toggle stays enabled.
+- **Virtualization** applies to the **table view only** — the cards view is never virtualized. It only pays off with a large page size: raise `defaultItemsPerPage` and `itemsPerPageOptions` (defaults are `10` and `[5, 10, 20]`). Rows are assumed to have a uniform `rowHeight`; use `truncate` + `layout="fixed"` for predictable heights.
+- Scroll resets to the top on page or items-per-page change, but **not** on filter change (known limitation). `aria-rowcount` reflects the current page (+1), not the whole dataset, because pagination is independent.
+- `virtualizedMaxHeight`, `rowHeight`, `overscan`, and `stickyHeader` only take effect when `virtualized` is true. `stickyHeader` makes each `<th>` sticky using the `--color-table-headerBg` token (fallback `#f8fafc`).
+- `TableDensity` is exported from the package. `ITSearchTable` does **not** support `layout`, `density`, `autoCardBreakpoint`, `virtualized`, or per-column `width` — do not assume parity.
 - Three visual variants: default (no borders), striped (alternating rows), bordered (full grid)
 
 ## Stories