@axzydev/axzy_ui_system 1.2.16 → 1.3.0

package/src/components/molecules/dropdown-menu/dropdown-menu.props.ts

@@ -0,0 +1,41 @@
+import { ReactNode } from "react";
+
+/** A single action inside {@link ITDropdownMenuProps}. */
+export interface ITDropdownMenuItem {
+  /** Unique identifier for the item. */
+  id: string;
+  /** Item content (usually text). */
+  label: ReactNode;
+  /** Optional leading icon. */
+  icon?: ReactNode;
+  /** Optional shortcut hint rendered on the right (e.g. `"⌘K"`). */
+  shortcut?: string;
+  /** Click handler for the item. */
+  onClick?: () => void;
+  /** Disables the item. @default false */
+  disabled?: boolean;
+  /** Renders the item in the danger color (destructive actions). @default false */
+  danger?: boolean;
+  /** Draws a separator above this item. @default false */
+  divider?: boolean;
+}
+
+/** Props for the ITDropdownMenu component. */
+export interface ITDropdownMenuProps {
+  /** Menu actions. */
+  items: ITDropdownMenuItem[];
+  /** Custom trigger content. Defaults to a vertical ellipsis icon. */
+  trigger?: ReactNode;
+  /** Accessible label for the trigger button. @default "Abrir menú" */
+  triggerLabel?: string;
+  /** Placement of the menu relative to the trigger. Valid values: `"bottom-start"`, `"bottom-end"`, `"top-start"`, `"top-end"`. @default "bottom-end" */
+  placement?: "bottom-start" | "bottom-end" | "top-start" | "top-end";
+  /** Fired after an item is activated, with its id and definition. */
+  onSelect?: (id: string, item: ITDropdownMenuItem) => void;
+  /** Disables the trigger. @default false */
+  disabled?: boolean;
+  /** Additional CSS classes for the trigger button. */
+  className?: string;
+  /** Additional CSS classes for the menu panel. */
+  menuClassName?: string;
+}

package/src/components/molecules/dropdown-menu/dropdown-menu.stories.tsx

@@ -0,0 +1,41 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { FaEdit, FaCopy, FaTrash, FaDownload } from "react-icons/fa";
+import ITDropdownMenu from "@/components/molecules/dropdown-menu/dropdown-menu";
+import ITButton from "@/components/atoms/button/button";
+
+const meta: Meta<typeof ITDropdownMenu> = {
+  title: "Components/Navigation/ITDropdownMenu",
+  component: ITDropdownMenu,
+  parameters: { layout: "centered" },
+};
+
+export default meta;
+type Story = StoryObj<typeof ITDropdownMenu>;
+
+const items = [
+  { id: "edit", label: "Editar", icon: <FaEdit />, onClick: () => alert("Editar") },
+  { id: "copy", label: "Duplicar", icon: <FaCopy />, shortcut: "⌘D", onClick: () => alert("Duplicar") },
+  { id: "download", label: "Descargar", icon: <FaDownload />, disabled: true },
+  { id: "delete", label: "Eliminar", icon: <FaTrash />, danger: true, divider: true, onClick: () => alert("Eliminar") },
+];
+
+export const Default: Story = {
+  args: { items },
+};
+
+export const CustomTrigger: Story = {
+  args: {
+    items,
+    trigger: <span className="text-sm font-semibold px-1">Acciones</span>,
+    triggerLabel: "Acciones",
+  },
+};
+
+export const WithLabelButton: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <ITButton label="Guardar" variant="filled" color="primary" size="sm" />
+      <ITDropdownMenu items={items} />
+    </div>
+  ),
+};

package/src/components/molecules/dropdown-menu/dropdown-menu.tsx

@@ -0,0 +1,219 @@
+import clsx from "clsx";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { FaEllipsisV } from "react-icons/fa";
+import { ITDropdownMenuProps } from "./dropdown-menu.props";
+import { useFloatingPanel } from "@/hooks/useFloatingPanel";
+import ITText from "@/components/atoms/text/text";
+
+/**
+ * Action menu with keyboard navigation and ARIA menu semantics.
+ *
+ * Renders the menu through a portal so it escapes `overflow: hidden` and
+ * transformed ancestors, and flips above the trigger when there is no room
+ * below.
+ *
+ * @example
+ * <ITDropdownMenu
+ *   items={[
+ *     { id: "edit", label: "Editar", icon: <FaEdit />, onClick: edit },
+ *     { id: "delete", label: "Eliminar", icon: <FaTrash />, danger: true, divider: true, onClick: remove },
+ *   ]}
+ * />
+ */
+export default function ITDropdownMenu({
+  items,
+  trigger,
+  triggerLabel = "Abrir menú",
+  placement = "bottom-end",
+  onSelect,
+  disabled = false,
+  className,
+  menuClassName,
+}: ITDropdownMenuProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(-1);
+
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const itemRefs = useRef<Array<HTMLButtonElement | null>>([]);
+
+  const { panelRef, style: panelStyle } = useFloatingPanel(triggerRef, isOpen, {
+    estimatedHeight: Math.max(items.length * 40, 120),
+    matchWidth: false,
+    align: placement.endsWith("end") ? "end" : "start",
+  });
+
+  const enabledIndexes = useMemo(
+    () => items.map((item, i) => (item.disabled ? -1 : i)).filter((i) => i >= 0),
+    [items]
+  );
+
+  useEffect(() => {
+    if (!isOpen) return;
+    function handleClickOutside(event: MouseEvent) {
+      const target = event.target as Node;
+      if (!triggerRef.current?.contains(target) && !panelRef.current?.contains(target)) {
+        setIsOpen(false);
+      }
+    }
+    document.addEventListener("mousedown", handleClickOutside);
+    return () => document.removeEventListener("mousedown", handleClickOutside);
+  }, [isOpen, panelRef]);
+
+  useEffect(() => {
+    if (isOpen) {
+      setActiveIndex(enabledIndexes[0] ?? -1);
+      requestAnimationFrame(() => {
+        if (enabledIndexes[0] !== undefined) itemRefs.current[enabledIndexes[0]]?.focus();
+      });
+    }
+  }, [isOpen, enabledIndexes]);
+
+  const open = () => {
+    if (disabled) return;
+    setIsOpen(true);
+  };
+
+  const close = (restoreFocus = true) => {
+    setIsOpen(false);
+    setActiveIndex(-1);
+    if (restoreFocus) triggerRef.current?.focus();
+  };
+
+  const activate = (index: number) => {
+    const item = items[index];
+    if (!item || item.disabled) return;
+    item.onClick?.();
+    onSelect?.(item.id, item);
+    close();
+  };
+
+  const moveActive = (dir: 1 | -1) => {
+    if (!enabledIndexes.length) return;
+    const currentPos = enabledIndexes.indexOf(activeIndex);
+    const nextPos =
+      currentPos === -1
+        ? dir === 1
+          ? 0
+          : enabledIndexes.length - 1
+        : (currentPos + dir + enabledIndexes.length) % enabledIndexes.length;
+    const next = enabledIndexes[nextPos];
+    setActiveIndex(next);
+    itemRefs.current[next]?.focus();
+  };
+
+  const handleTriggerKeyDown = (e: React.KeyboardEvent) => {
+    if (disabled) return;
+    if (e.key === "ArrowDown" || e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      if (!isOpen) open();
+      else moveActive(1);
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      if (!isOpen) open();
+      else moveActive(-1);
+    } else if (e.key === "Escape") {
+      close();
+    }
+  };
+
+  const handleMenuKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      moveActive(1);
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      moveActive(-1);
+    } else if (e.key === "Home") {
+      e.preventDefault();
+      if (enabledIndexes.length) {
+        const first = enabledIndexes[0];
+        setActiveIndex(first);
+        itemRefs.current[first]?.focus();
+      }
+    } else if (e.key === "End") {
+      e.preventDefault();
+      const last = enabledIndexes[enabledIndexes.length - 1];
+      if (last !== undefined) {
+        setActiveIndex(last);
+        itemRefs.current[last]?.focus();
+      }
+    } else if (e.key === "Escape") {
+      e.preventDefault();
+      close();
+    } else if (e.key === "Tab") {
+      close(false);
+    }
+  };
+
+  return (
+    <>
+      <button
+        ref={triggerRef}
+        type="button"
+        aria-haspopup="menu"
+        aria-expanded={isOpen}
+        aria-label={triggerLabel}
+        disabled={disabled}
+        onClick={() => (isOpen ? close() : open())}
+        onKeyDown={handleTriggerKeyDown}
+        className={clsx(
+          "inline-flex items-center justify-center rounded-lg p-2 text-secondary-500 transition-colors",
+          "hover:bg-secondary-100 hover:text-secondary-700 dark:hover:bg-slate-800 dark:hover:text-slate-200",
+          "focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-400",
+          disabled && "opacity-50 cursor-not-allowed",
+          className
+        )}
+      >
+        {trigger ?? <FaEllipsisV size={14} />}
+      </button>
+
+      {isOpen &&
+        createPortal(
+          <div
+            ref={panelRef}
+            role="menu"
+            aria-label={triggerLabel}
+            style={panelStyle}
+            onKeyDown={handleMenuKeyDown}
+            className={clsx(
+              "min-w-[180px] rounded-xl border border-secondary-200 dark:border-slate-700 bg-white dark:bg-slate-900 shadow-xl py-1 overflow-hidden",
+              menuClassName
+            )}
+          >
+            {items.map((item, index) => (
+              <div key={item.id}>
+                {item.divider && <div className="my-1 h-px bg-secondary-100 dark:bg-slate-800" />}
+                <button
+                  ref={(el) => { itemRefs.current[index] = el; }}
+                  type="button"
+                  role="menuitem"
+                  tabIndex={-1}
+                  disabled={item.disabled}
+                  onClick={() => activate(index)}
+                  onMouseEnter={() => !item.disabled && setActiveIndex(index)}
+                  className={clsx(
+                    "w-full flex items-center gap-3 px-3 py-2 text-left text-sm transition-colors",
+                    "focus:outline-none",
+                    item.disabled
+                      ? "opacity-50 cursor-not-allowed text-secondary-400"
+                      : item.danger
+                      ? "text-danger-600 hover:bg-danger-50 focus:bg-danger-50 dark:hover:bg-danger-950/30"
+                      : "text-secondary-700 dark:text-slate-200 hover:bg-secondary-50 focus:bg-secondary-50 dark:hover:bg-slate-800 dark:focus:bg-slate-800",
+                    activeIndex === index && !item.disabled && !item.danger && "bg-secondary-50 dark:bg-slate-800"
+                  )}
+                >
+                  {item.icon && <span className="shrink-0">{item.icon}</span>}
+                  <ITText as="span" className="flex-1 truncate">{item.label}</ITText>
+                  {item.shortcut && (
+                    <ITText as="span" className="text-xs text-secondary-400 font-mono">{item.shortcut}</ITText>
+                  )}
+                </button>
+              </div>
+            ))}
+          </div>,
+          document.body
+        )}
+    </>
+  );
+}

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

@@ -0,0 +1,43 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as StoriesData from './field.stories';
+
+<Meta of={StoriesData} />
+
+# ITField
+
+Form-field wrapper that standardizes label, required marker, helper text, and error message around any control.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | — | Label above the control. |
+| `htmlFor` | `string` | — | `id` the label points to. |
+| `required` | `boolean` | `false` | Shows a red asterisk. |
+| `error` | `string \| boolean` | — | Error message, or `true` for the generic message. |
+| `helpText` | `string` | — | Helper text shown when there is no error. |
+| `children` | `ReactNode` | — | The form control. |
+| `className` | `string` | — | Extra CSS classes for the wrapper. |
+| `labelClassName` | `string` | — | Extra CSS classes for the label. |
+| `contentClassName` | `string` | — | Extra CSS classes for the control container. |
+
+## Usage
+
+```tsx
+import { ITField, ITInput } from '@axzydev/axzy_ui_system';
+
+<ITField label="Email" htmlFor="email" required error={errors.email} helpText="We never share it.">
+  <ITInput name="email" value={email} onChange={onChange} />
+</ITField>
+```
+
+## Notes
+
+- Error text takes precedence over `helpText`; only one is shown at a time.
+- `error={true}` renders the generic "Este campo es requerido" message.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/molecules/field/field.props.ts

@@ -0,0 +1,23 @@
+import { ReactNode } from "react";
+
+/** Props for the ITField form-field wrapper. */
+export interface ITFieldProps {
+  /** Label rendered above the control. */
+  label?: string;
+  /** `id` of the control the label points to (`htmlFor`). */
+  htmlFor?: string;
+  /** Shows a red asterisk next to the label. @default false */
+  required?: boolean;
+  /** Validation error. Pass `true` for the generic message or a string for a custom one. */
+  error?: string | boolean;
+  /** Helper text shown below the control when there is no error. */
+  helpText?: string;
+  /** The form control (ITInput, ITSelect, ITTextarea, …). */
+  children: ReactNode;
+  /** Additional CSS classes for the wrapper. */
+  className?: string;
+  /** Additional CSS classes for the label. */
+  labelClassName?: string;
+  /** Additional CSS classes for the control container. */
+  contentClassName?: string;
+}

package/src/components/molecules/field/field.stories.tsx

@@ -0,0 +1,42 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import ITField from "@/components/molecules/field/field";
+import ITInput from "@/components/atoms/input/input";
+
+const meta: Meta<typeof ITField> = {
+  title: "Components/Form Elements/ITField",
+  component: ITField,
+  parameters: { layout: "centered" },
+};
+
+export default meta;
+type Story = StoryObj<typeof ITField>;
+
+export const Default: Story = {
+  render: () => (
+    <div className="w-[360px]">
+      <ITField label="Nombre completo" htmlFor="name" required helpText="Como aparece en tu identificación.">
+        <ITInput name="name" value="" onChange={() => {}} onBlur={() => {}} />
+      </ITField>
+    </div>
+  ),
+};
+
+export const WithError: Story = {
+  render: () => (
+    <div className="w-[360px]">
+      <ITField label="Correo" htmlFor="email" required error="Ingresa un correo válido.">
+        <ITInput name="email" value="correo-malo" onChange={() => {}} onBlur={() => {}} />
+      </ITField>
+    </div>
+  ),
+};
+
+export const GenericError: Story = {
+  render: () => (
+    <div className="w-[360px]">
+      <ITField label="RFC" htmlFor="rfc" required error>
+        <ITInput name="rfc" value="" onChange={() => {}} onBlur={() => {}} />
+      </ITField>
+    </div>
+  ),
+};

package/src/components/molecules/field/field.tsx

@@ -0,0 +1,54 @@
+import clsx from "clsx";
+import { ITFieldProps } from "./field.props";
+import { inputError, inputLabel } from "@/utils/styles";
+import ITText from "@/components/atoms/text/text";
+
+/**
+ * Form-field wrapper that standardizes label, required marker, helper text,
+ * and error message around any control.
+ *
+ * Keeps spacing and error styling consistent across forms so each control
+ * does not re-implement label/error logic.
+ *
+ * @example
+ * <ITField label="Email" htmlFor="email" required error={errors.email} helpText="We never share it.">
+ *   <ITInput name="email" value={email} onChange={onChange} />
+ * </ITField>
+ */
+export default function ITField({
+  label,
+  htmlFor,
+  required = false,
+  error,
+  helpText,
+  children,
+  className,
+  labelClassName,
+  contentClassName,
+}: ITFieldProps) {
+  const hasError = Boolean(error);
+  const message = typeof error === "string" ? error : hasError ? "Este campo es requerido" : undefined;
+
+  return (
+    <div className={clsx("flex flex-col gap-1.5", className)}>
+      {label && (
+        <label htmlFor={htmlFor} className={clsx(inputLabel(hasError), labelClassName)}>
+          <ITText as="span">{label}</ITText>
+          {required && (
+            <ITText as="span" className="text-danger-500 ml-1">
+              *
+            </ITText>
+          )}
+        </label>
+      )}
+
+      <div className={clsx(contentClassName)}>{children}</div>
+
+      {hasError ? (
+        <ITText as="p" className={inputError}>{message}</ITText>
+      ) : helpText ? (
+        <ITText as="p" className="text-xs text-secondary-500 dark:text-secondary-400">{helpText}</ITText>
+      ) : null}
+    </div>
+  );
+}

package/src/components/molecules/multi-select/multi-select.doc.mdx

@@ -0,0 +1,55 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as StoriesData from './multi-select.stories';
+
+<Meta of={StoriesData} />
+
+# ITMultiSelect
+
+Multi-value select with searchable dropdown, removable chips, and keyboard navigation.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options` | `ITMultiSelectOption[]` | — | Available options `{ label, value, ...custom }`. |
+| `value` | `(string \| number)[]` | — | Selected values (controlled). |
+| `onChange` | `(values, options) => void` | — | Fired with the next selected values. |
+| `label` | `string` | — | Label above the control. |
+| `placeholder` | `string` | `"Selecciona opciones"` | Placeholder when empty. |
+| `valueField` | `string` | `"value"` | Field used as the option value. |
+| `labelField` | `string` | `"label"` | Field used as the option label. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Control size. |
+| `maxVisibleChips` | `number` | `3` | Chips shown before collapsing into `+N`. |
+| `clearable` | `boolean` | `true` | Shows a clear-all (X) button. |
+| `searchable` | `boolean` | `true` | Enables the search input. |
+| `onSearch` | `(query) => void` | — | Server-side search callback. |
+| `isLoading` | `boolean` | `false` | Loading state for remote options. |
+| `noResultsMessage` | `string` | `"No se encontraron resultados"` | Empty-results message. |
+| `renderOption` | `(option, { isSelected, searchTerm }) => ReactNode` | — | Custom option template. |
+| `disabled` / `readOnly` / `required` / `touched` / `error` | — | — | Standard form states. |
+
+## Usage
+
+```tsx
+import { ITMultiSelect } from '@axzydev/axzy_ui_system';
+
+<ITMultiSelect
+  label="Skills"
+  options={skills}
+  value={selected}
+  onChange={(values) => setSelected(values)}
+  maxVisibleChips={3}
+/>
+```
+
+## Notes
+
+- Keyboard: `ArrowUp`/`ArrowDown` navigate, `Enter` toggles, `Backspace` removes the last chip, `Esc` closes.
+- `role="combobox"` + `role="listbox"` (`aria-multiselectable`) for accessibility.
+- The dropdown is portaled, so it is not clipped inside cards or `overflow: hidden` ancestors.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/molecules/multi-select/multi-select.props.ts

@@ -0,0 +1,65 @@
+import { ReactNode } from "react";
+import { SizesTypes } from "@/types/sizes.types";
+
+/** Represents an option in the multi-select dropdown. */
+export interface ITMultiSelectOption {
+  /** Display label for the option. */
+  label: string;
+  /** Value associated with the option. */
+  value: string | number;
+  /** Additional custom fields can be attached. */
+  [key: string]: any;
+}
+
+/** Props for the ITMultiSelect component. */
+export interface ITMultiSelectProps {
+  /** Name attribute for form integrations. */
+  name?: string;
+  /** Label displayed above the control. */
+  label?: string;
+  /** Placeholder shown when no value is selected. @default "Selecciona opciones" */
+  placeholder?: string;
+  /** Available options. */
+  options: ITMultiSelectOption[];
+  /** Selected values (controlled). */
+  value: (string | number)[];
+  /** Fired with the next selected values and their option objects. */
+  onChange?: (values: (string | number)[], options: ITMultiSelectOption[]) => void;
+  /** Fired when the control loses focus. */
+  onBlur?: (e: React.FocusEvent<HTMLInputElement>) => void;
+  /** Field used as the option value. @default "value" */
+  valueField?: string;
+  /** Field used as the option display label. @default "label" */
+  labelField?: string;
+  /** Disables the control. @default false */
+  disabled?: boolean;
+  /** Read-only mode: chips shown, no editing. @default false */
+  readOnly?: boolean;
+  /** Marks the field as required (red asterisk). @default false */
+  required?: boolean;
+  /** Whether the field has been touched (form validation). */
+  touched?: boolean;
+  /** Error message or boolean indicating an error state. */
+  error?: string | boolean;
+  /** Control size. Valid values: `"sm"`, `"md"`, `"lg"`. @default "md" */
+  size?: SizesTypes;
+  /** Maximum number of chips shown before collapsing into "+N". @default 3 */
+  maxVisibleChips?: number;
+  /** Shows a clear-all (X) button. @default true */
+  clearable?: boolean;
+  /** Enables the search input inside the control. @default true */
+  searchable?: boolean;
+  /** Callback for server-side search. Receives the query string. */
+  onSearch?: (query: string) => void;
+  /** Whether options are loading from an external source. @default false */
+  isLoading?: boolean;
+  /** Message shown when no options match. @default "No se encontraron resultados" */
+  noResultsMessage?: string;
+  /** Custom template for each dropdown option. */
+  renderOption?: (
+    option: ITMultiSelectOption,
+    state: { isSelected: boolean; searchTerm: string }
+  ) => ReactNode;
+  /** Additional CSS classes for the container. */
+  className?: string;
+}

package/src/components/molecules/multi-select/multi-select.stories.tsx

@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import ITMultiSelect from "@/components/molecules/multi-select/multi-select";
+import { ITMultiSelectOption } from "./multi-select.props";
+
+const meta: Meta<typeof ITMultiSelect> = {
+  title: "Components/Form Elements/ITMultiSelect",
+  component: ITMultiSelect,
+  parameters: { layout: "centered" },
+};
+
+export default meta;
+type Story = StoryObj<typeof ITMultiSelect>;
+
+const options: ITMultiSelectOption[] = [
+  { value: "mx", label: "México" },
+  { value: "es", label: "España" },
+  { value: "co", label: "Colombia" },
+  { value: "ar", label: "Argentina" },
+  { value: "pe", label: "Perú" },
+  { value: "cl", label: "Chile" },
+];
+
+const Wrapper = (args: any) => {
+  const [value, setValue] = useState<(string | number)[]>(args.value ?? []);
+  return (
+    <div className="w-[400px]">
+      <ITMultiSelect {...args} value={value} onChange={(v) => setValue(v)} />
+    </div>
+  );
+};
+
+export const Default: Story = {
+  render: (args) => <Wrapper {...args} />,
+  args: { name: "countries", label: "Países", options, value: [] },
+};
+
+export const WithPreselected: Story = {
+  render: (args) => <Wrapper {...args} />,
+  args: { name: "countries", label: "Países", options, value: ["mx", "es", "co", "ar"] },
+};
+
+export const WithError: Story = {
+  render: (args) => <Wrapper {...args} />,
+  args: {
+    name: "countries",
+    label: "Países",
+    options,
+    value: [],
+    required: true,
+    touched: true,
+    error: true,
+  },
+};
+
+export const Disabled: Story = {
+  render: (args) => <Wrapper {...args} />,
+  args: { name: "countries", label: "Países", options, value: ["mx"], disabled: true },
+};