@axzydev/axzy_ui_system 1.2.16 → 1.3.1

package/src/components/molecules/date-picker/datePicker.tsx

@@ -1,10 +1,12 @@
 import clsx from "clsx";
 import React, { useEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
 import { FaCalendarAlt } from "react-icons/fa";
 import { isBefore } from "date-fns";
 import ITCalendar from "@/components/molecules/calendar/calendar";
 import ITInput from "@/components/atoms/input/input";
 import { ITDatePickerProps } from "./date-picker.props";
+import { useFloatingPanel } from "@/hooks/useFloatingPanel";
 import { theme } from "@/theme/theme";
 
 /**
@@ -64,7 +66,12 @@ export default function ITDatePicker({
   const [internalRange, setInternalRange] = useState<[Date | null, Date | null]>([null, null]);
 
   const wrapperRef = useRef<HTMLDivElement>(null);
-  const [calendarPosition, setCalendarPosition] = useState({ top: 0, left: 0 });
+
+  // Calendar position (rendered in a portal so it escapes overflow/transform ancestors).
+  const { panelRef, style: panelStyle } = useFloatingPanel(wrapperRef, isOpen, {
+    estimatedHeight: 360,
+    matchWidth: false,
+  });
 
   // Normalize single vs range values
   const dateRange = React.useMemo(() => {
@@ -97,10 +104,10 @@ export default function ITDatePicker({
 
   useEffect(() => {
     const handleClickOutside = (event: MouseEvent) => {
-      if (
-        wrapperRef.current &&
-        !wrapperRef.current.contains(event.target as Node)
-      ) {
+      const target = event.target as Node;
+      const inWrapper = wrapperRef.current?.contains(target);
+      const inPanel = panelRef.current?.contains(target);
+      if (!inWrapper && !inPanel) {
         setIsOpen(false);
       }
     };
@@ -108,24 +115,6 @@ export default function ITDatePicker({
     return () => document.removeEventListener("mousedown", handleClickOutside);
   }, []);
 
-  const calculateCalendarPosition = () => {
-    if (wrapperRef.current) {
-      const inputRect = wrapperRef.current.getBoundingClientRect();
-      const calendarHeight = 300;
-      const viewportHeight = window.innerHeight;
-
-      let top = inputRect.bottom + 4;
-      if (inputRect.bottom + calendarHeight > viewportHeight) {
-        top = inputRect.top - calendarHeight - 4;
-      }
-
-      setCalendarPosition({
-        top,
-        left: inputRect.left,
-      });
-    }
-  };
-
   const handleDateChange = (date: Date) => {
     if (range) {
       let newRange: [Date | null, Date | null];
@@ -177,7 +166,6 @@ export default function ITDatePicker({
 
   const handleIconClick = () => {
     if (!disabled) {
-      calculateCalendarPosition();
       setIsOpen(!isOpen);
     }
   };
@@ -300,38 +288,39 @@ export default function ITDatePicker({
         onClick={handleIconClick}
       />
 
-      {isOpen && (
-        <div
-          className={clsx(
-            "fixed z-[70]",
-            calendarClassName,
-            range ? "w-[320px]" : "w-[280px]"
-          )}
-          style={{
-            top: `${calendarPosition.top}px`,
-            left: `${calendarPosition.left}px`,
-             backgroundColor: theme.card.backgroundColor,
-             borderColor: theme.card.borderColor,
-             borderWidth: '1px',
-             borderStyle: 'solid',
-             borderRadius: theme.card.borderRadius,
-             boxShadow: theme.card.shadow,
-             padding: '0.5rem',
-          }}
-        >
-          <ITCalendar
-            value={!range ? (startDate as Date) : undefined}
-            startDate={startDate as Date}
-            endDate={endDate as Date}
-            selectionMode={range ? 'range' : 'single'}
-            onChange={handleDateChange}
-            minDate={minDate}
-            maxDate={maxDate}
-            variant={variant}
-            className="h-auto border-none shadow-none w-full"
-          />
-        </div>
-      )}
+      {isOpen &&
+        createPortal(
+          <div
+            ref={panelRef}
+            className={clsx(
+              calendarClassName,
+              range ? "w-[320px]" : "w-[280px]"
+            )}
+            style={{
+              ...panelStyle,
+              backgroundColor: theme.card.backgroundColor,
+              borderColor: theme.card.borderColor,
+              borderWidth: "1px",
+              borderStyle: "solid",
+              borderRadius: theme.card.borderRadius,
+              boxShadow: theme.card.shadow,
+              padding: "0.5rem",
+            }}
+          >
+            <ITCalendar
+              value={!range ? (startDate as Date) : undefined}
+              startDate={startDate as Date}
+              endDate={endDate as Date}
+              selectionMode={range ? 'range' : 'single'}
+              onChange={handleDateChange}
+              minDate={minDate}
+              maxDate={maxDate}
+              variant={variant}
+              className="h-auto border-none shadow-none w-full"
+            />
+          </div>,
+          document.body
+        )}
     </div>
   );
 }

package/src/components/molecules/dropdown-menu/dropdown-menu.doc.mdx

@@ -0,0 +1,46 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as StoriesData from './dropdown-menu.stories';
+
+<Meta of={StoriesData} />
+
+# ITDropdownMenu
+
+Action menu with keyboard navigation and ARIA menu semantics. Rendered through a portal, so it is not clipped by cards or `overflow: hidden` ancestors.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `ITDropdownMenuItem[]` | — | Actions: `{ id, label, icon?, shortcut?, onClick?, disabled?, danger?, divider? }`. |
+| `trigger` | `ReactNode` | ellipsis icon | Custom trigger content. |
+| `triggerLabel` | `string` | `"Abrir menú"` | Accessible label for the trigger. |
+| `placement` | `"bottom-start" \| "bottom-end" \| "top-start" \| "top-end"` | `"bottom-end"` | Menu placement. |
+| `onSelect` | `(id, item) => void` | — | Fired after an item is activated. |
+| `disabled` | `boolean` | `false` | Disables the trigger. |
+| `className` | `string` | — | Extra CSS classes for the trigger. |
+| `menuClassName` | `string` | — | Extra CSS classes for the menu. |
+
+## Usage
+
+```tsx
+import { ITDropdownMenu } from '@axzydev/axzy_ui_system';
+
+<ITDropdownMenu
+  items={[
+    { id: "edit", label: "Editar", icon: <FaEdit />, onClick: edit },
+    { id: "delete", label: "Eliminar", icon: <FaTrash />, danger: true, divider: true, onClick: remove },
+  ]}
+/>
+```
+
+## Notes
+
+- Keyboard: `ArrowUp`/`ArrowDown` navigate, `Enter`/`Space` activate, `Esc` closes, `Home`/`End` jump.
+- Uses `role="menu"` / `role="menuitem"` and `aria-haspopup` / `aria-expanded` on the trigger.
+- The panel flips above the trigger automatically when there is no room below.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

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