@axzydev/axzy_ui_system 1.4.7 → 1.5.0

package/src/showcases/portfolioUi.tsx

@@ -0,0 +1,153 @@
+/**
+ * Piezas propias del portafolio (`HomeShowcase` / `ProductoDetalle`).
+ *
+ * El kit base (tipografía de metadatos, superficies, CTA, etiquetas y controles
+ * de cabecera) vive en `src/sandbox/ui.tsx` y `src/sandbox/controls.tsx`, porque
+ * lo comparten el sandbox y el portafolio; aquí solo queda lo que es chrome de la
+ * hoja: progreso de lectura, salto al contenido y volver arriba.
+ *
+ * Vive en `src/showcases/` a propósito: es dev-only, nunca entra en `dist/`.
+ */
+
+import { useEffect, useState } from "react";
+import { FaArrowUp } from "react-icons/fa";
+import { useITTranslation } from "@/i18n";
+
+/**
+ * Se reexporta el kit compartido para que las páginas del portafolio tengan un
+ * único punto de importación (`./portfolioUi`).
+ */
+export {
+  BotonAccion,
+  CARD,
+  CARD_HOVER,
+  CHIP,
+  EnlaceBoton,
+  Etiqueta,
+  EYEBROW,
+  FILETE,
+  SectionHeading,
+  VARIANTE_CTA,
+} from "@/sandbox/ui";
+export type {
+  BotonAccionProps,
+  EnlaceBotonProps,
+  EtiquetaProps,
+  TamanoCta,
+  VarianteCta,
+} from "@/sandbox/ui";
+export { ControlesPortafolio, ControlSegmentado } from "@/sandbox/controls";
+
+/** Nombres antiguos del tamaño/variante de CTA, por compatibilidad. */
+export type { TamanoCta as TamanoEnlace, VarianteCta as VarianteEnlace } from "@/sandbox/ui";
+
+/**
+ * Línea de progreso de lectura: 2px de acento al pie de la cabecera sticky.
+ * Es chrome del portafolio, no un componente de la librería: `ITProgress` mide
+ * 4px y redondea, demasiado grueso para una regla de cabecera.
+ *
+ * @example
+ * ```tsx
+ * <header className="relative sticky top-0 …">
+ *   <PortfolioNav />
+ *   <BarraProgreso />
+ * </header>
+ * ```
+ */
+export const BarraProgreso = () => {
+  const [pct, setPct] = useState(0);
+
+  useEffect(() => {
+    const onScroll = () => {
+      const max = document.documentElement.scrollHeight - window.innerHeight;
+      setPct(max > 0 ? Math.min(100, Math.max(0, (window.scrollY / max) * 100)) : 0);
+    };
+    onScroll();
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("resize", onScroll);
+    return () => {
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", onScroll);
+    };
+  }, []);
+
+  return (
+    <div aria-hidden className="absolute inset-x-0 bottom-0 h-[2px] overflow-hidden">
+      <div
+        className="h-full bg-primary-700 transition-[width] duration-150 ease-out dark:bg-primary-500"
+        style={{ width: `${pct}%` }}
+      />
+    </div>
+  );
+};
+
+/** Props de `SaltarContenido`. */
+export interface SaltarContenidoProps {
+  /** Id (con `#`) del bloque principal. @default "#contenido" */
+  destino?: string;
+}
+
+/**
+ * Enlace de salto para teclado (WCAG 2.4.1): invisible hasta que recibe foco y
+ * entonces aparece sobre la cabecera sticky.
+ *
+ * @example
+ * ```tsx
+ * <SaltarContenido />
+ * <main id="contenido">…</main>
+ * ```
+ */
+export const SaltarContenido = ({ destino = "#contenido" }: SaltarContenidoProps) => {
+  const { t } = useITTranslation();
+
+  return (
+    <a
+      href={destino}
+      className="sr-only focus:not-sr-only focus:fixed focus:left-4 focus:top-4 focus:z-[300] focus:rounded-[10px] focus:bg-primary-700 focus:px-4 focus:py-2 focus:text-sm focus:font-semibold focus:text-white focus:shadow-lg"
+    >
+      {t("showcase.home.skipToContent")}
+    </a>
+  );
+};
+
+/**
+ * Botón flotante «volver arriba»: aparece tras desplazarse una pantalla y sube
+ * con scroll suave (o instantáneo si el sistema pide movimiento reducido).
+ * Mono y con borde de 1px, como el resto de los metadatos del portafolio.
+ *
+ * @example
+ * ```tsx
+ * <VolverArriba />
+ * ```
+ */
+export const VolverArriba = () => {
+  const { t } = useITTranslation();
+  const [visible, setVisible] = useState(false);
+
+  useEffect(() => {
+    const onScroll = () => setVisible(window.scrollY > 560);
+    onScroll();
+    window.addEventListener("scroll", onScroll, { passive: true });
+    return () => window.removeEventListener("scroll", onScroll);
+  }, []);
+
+  const subir = () => {
+    const reducido = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    window.scrollTo({ top: 0, behavior: reducido ? "auto" : "smooth" });
+  };
+
+  return (
+    <button
+      type="button"
+      onClick={subir}
+      tabIndex={visible ? 0 : -1}
+      aria-hidden={visible ? undefined : true}
+      className={`fixed bottom-6 right-6 z-[200] inline-flex items-center gap-2 rounded-[10px] border border-slate-200 bg-white/90 px-3.5 py-2 font-mono text-[11px] font-medium uppercase tracking-[0.12em] text-slate-600 backdrop-blur-md transition-all duration-200 hover:-translate-y-0.5 hover:border-primary-400 hover:text-primary-700 dark:border-slate-800 dark:bg-slate-900/90 dark:text-slate-300 dark:hover:border-primary-500 dark:hover:text-primary-500 ${
+        visible ? "opacity-100" : "pointer-events-none translate-y-2 opacity-0"
+      }`}
+    >
+      <FaArrowUp size={11} aria-hidden />
+      {t("showcase.home.backToTop")}
+    </button>
+  );
+};

package/src/showcases/techIcons.ts

@@ -40,6 +40,7 @@ const ICONS = {
   nodejs: { src: "/tech-icons/nodejs.svg" },
   flutter: { src: "/tech-icons/flutter.svg" },
   express: { src: "/tech-icons/express.svg", mono: true },
+  springboot: { src: "/tech-icons/springboot.svg" },
   electron: { src: "/tech-icons/electron.svg" },
   redux: { src: "/tech-icons/redux.svg" },
   // Markup, styles & data
@@ -48,8 +49,10 @@ const ICONS = {
   sass: { src: "/tech-icons/sass.svg" },
   mongodb: { src: "/tech-icons/mongodb.svg" },
   mysql: { src: "/tech-icons/mysql.svg" },
+  postgresql: { src: "/tech-icons/postgresql.svg" },
   // Mobile & platform
   android: { src: "/tech-icons/android.svg" },
+  appium: { src: "/tech-icons/appium.svg" },
   // Tooling & DevOps
   docker: { src: "/tech-icons/docker.svg" },
   git: { src: "/tech-icons/git.svg" },

package/src/types/table.types.ts

@@ -1,5 +1,115 @@
+import type { CSSProperties } from "react";
+
 export type TableVariants = "default" | "striped" | "bordered";
 
+/**
+ * A single, optional style slot for one region of a table. Both fields are
+ * merged *after* the component's built-in values.
+ */
+export interface TableDesignSlot {
+  /**
+   * Extra CSS classes merged after the built-in ones. Note that Tailwind
+   * resolves conflicts by utility order (not class order), so use inline
+   * `style` (or `!` modifiers) when a value must always win.
+   */
+  className?: string;
+  /** Inline CSS merged after the built-in values; wins over classes unless the global theme forces a value with `!important`. */
+  style?: CSSProperties;
+}
+
+/**
+ * Per-instance visual overrides for a table. Every region is optional and, when
+ * present, is applied on top of the built-in styles. The global
+ * `ITThemeProvider` colors (`--color-table-*`) still apply underneath, so use
+ * `TableColors` for this-instance color changes instead of `style`.
+ */
+export interface TableDesign {
+  /** Outermost wrapper (`space-y-4 w-full`). Prefer `containerClassName` for width/spacing. */
+  container?: TableDesignSlot;
+  /** The rounded card surface that wraps the toolbar, table and footer (border, radius, shadow, background). */
+  card?: TableDesignSlot;
+  /** Toolbar strip holding the title and/or the Table|Cards toggle. */
+  toolbar?: TableDesignSlot;
+  /** The `<thead>` row that carries the column titles. */
+  header?: TableDesignSlot;
+  /** Every `<th>` header cell. */
+  headerCell?: TableDesignSlot;
+  /** Every body `<tr>`. */
+  row?: TableDesignSlot;
+  /** Every body `<td>`. */
+  cell?: TableDesignSlot;
+  /** Scroll wrapper of the cards view (the responsive card list). */
+  cards?: TableDesignSlot;
+  /** Pagination footer strip. */
+  footer?: TableDesignSlot;
+}
+
+/**
+ * Per-instance color overrides. They are written as local `--color-table-*`
+ * variables on the table wrapper, so they beat the global theme for this
+ * instance only, without touching `ITThemeProvider`.
+ */
+export interface TableColors {
+  /** Header row background. Overrides the theme's `table.headerBg` for this instance. */
+  headerBg?: string;
+  /** Header text color. Overrides the theme's `table.headerText` for this instance. */
+  headerText?: string;
+  /** Body row background. Overrides the theme's `table.rowBg` for this instance. */
+  rowBg?: string;
+  /** Body text color. Overrides the theme's `table.rowText` for this instance. */
+  rowText?: string;
+  /** Body row hover background. Overrides the theme's `table.rowHover` for this instance. */
+  rowHover?: string;
+}
+
+/**
+ * Shared design props for ITTable and ITDataTable. `design` exposes every
+ * region as an object; the flat `*ClassName` / `*Style` shortcuts are merged
+ * after it, so the flat prop wins when both are provided.
+ */
+export interface TableDesignProps {
+  /** Whether to render the Table|Cards view switcher in the toolbar. Hiding it still honors `defaultView` and `autoCardBreakpoint`. @default true */
+  showViewToggle?: boolean;
+  /** Per-region visual overrides (classes + inline styles). */
+  design?: TableDesign;
+  /** Per-instance color overrides for header and rows, beating the global theme. */
+  colors?: TableColors;
+  /** Inline styles for the outermost wrapper. */
+  containerStyle?: CSSProperties;
+  /** Extra classes for the card surface (the rounded container). */
+  cardClassName?: string;
+  /** Inline styles for the card surface. */
+  cardStyle?: CSSProperties;
+  /** Extra classes for the toolbar strip (title + view toggle). */
+  toolbarClassName?: string;
+  /** Inline styles for the toolbar strip. */
+  toolbarStyle?: CSSProperties;
+  /** Extra classes for the header row. */
+  headerClassName?: string;
+  /** Inline styles for the header row. */
+  headerStyle?: CSSProperties;
+  /** Extra classes for every header cell. */
+  headerCellClassName?: string;
+  /** Inline styles for every header cell. */
+  headerCellStyle?: CSSProperties;
+  /** Extra classes for every body row. */
+  rowClassName?: string;
+  /** Inline styles for every body row. */
+  rowStyle?: CSSProperties;
+  /** Extra classes for every body cell. */
+  cellClassName?: string;
+  /** Inline styles for every body cell. */
+  cellStyle?: CSSProperties;
+  /** Extra classes for the cards-view scroll wrapper. */
+  cardsClassName?: string;
+  /** Inline styles for the cards-view scroll wrapper. */
+  cardsStyle?: CSSProperties;
+  /** Extra classes for the pagination footer strip. */
+  footerClassName?: string;
+  /** Inline styles for the pagination footer strip. */
+  footerStyle?: CSSProperties;
+}
+
 /**
  * Value stored for a single column filter.
  *

package/src/utils/table.utils.ts

@@ -1,5 +1,13 @@
-export const formatCurrencyMX = (value: number) => {
-  return value.toLocaleString("es-MX", {
+/**
+ * Formatea un número como moneda MXN.
+ *
+ * @param value - Importe a formatear.
+ * @param locale - Locale BCP-47 para `Intl.NumberFormat`. Por defecto `"es-MX"`
+ *   para mantener el comportamiento histórico; los componentes pasan la locale
+ *   activa del provider (`toIntlLocale(locale)`).
+ */
+export const formatCurrencyMX = (value: number, locale: string = "es-MX") => {
+  return value.toLocaleString(locale, {
     style: "currency",
     currency: "MXN",
   });

package/src/components/atoms/avatar/avatar.doc.mdx

@@ -1,48 +0,0 @@
-import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
-import * as StoriesData from './avatar.stories';
-
-<Meta of={StoriesData} />
-
-# ITAvatar
-
-Circular avatar component for displaying user profile pictures, initials, or generic placeholder content. Falls back to displaying initials when the image fails to load or is not provided. Supports five sizes and an optional badge overlay for status indicators.
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `src` | `string` | — | Image source URL for the avatar. |
-| `alt` | `string` | — | Alt text for the image. Also used as fallback initial when no `initials` or `src` is provided. |
-| `initials` | `string` | — | Initials to display when no image is available (max 2 characters recommended). |
-| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Avatar dimensions. |
-| `color` | `string` | `"bg-primary-500"` | Background color class for the initials fallback. |
-| `className` | `string` | — | Additional CSS class names for the avatar container. |
-| `badge` | `ReactNode` | — | React node rendered as a badge overlay at the bottom-right corner. |
-| `onClick` | `() => void` | — | Click handler. When provided, the avatar becomes interactive (`role="button"`). |
-
-## Usage
-
-```tsx
-import { ITAvatar } from '@axzydev/axzy_ui_system';
-
-<ITAvatar src="https://i.pravatar.cc/150" alt="User" size="md" />
-
-<ITAvatar initials="JD" size="lg" badge={<FaCircle className="text-emerald-500" />} />
-```
-
-## Variants / Notes
-
-- **xs** — Extra small (ideal for inline lists or compact UIs).
-- **sm** — Small (useful in table rows or sidebars).
-- **md** — Medium, the default size suitable for most use cases.
-- **lg** — Large (prominent display or profile pages).
-- **xl** — Extra large (hero sections or standalone profile views).
-- Shows initials text fallback when `src` is missing or the image fails (`onError`).
-- Badge slot positioned at bottom-right using absolute positioning.
-- Becomes interactive with click handler and hover cursor when `onClick` is provided.
-
-## Stories
-
-<Primary />
-<Controls />
-<Stories />

package/src/components/atoms/avatar/avatar.stories.tsx

@@ -1,64 +0,0 @@
-import type { Meta, StoryObj } from "@storybook/react";
-import ITAvatar from "@/components/atoms/avatar/avatar";
-import { FaCircle } from "react-icons/fa";
-
-const meta: Meta<typeof ITAvatar> = {
-  title: "Components/Data Display/ITAvatar",
-  component: ITAvatar,
-};
-
-export default meta;
-type Story = StoryObj<typeof ITAvatar>;
-
-export const WithImage: Story = {
-  args: {
-    src: "https://i.pravatar.cc/150?u=test",
-    alt: "User",
-    size: "md",
-  },
-};
-
-export const WithInitials: Story = {
-  args: {
-    initials: "JD",
-    size: "md",
-    color: "bg-primary-500",
-  },
-};
-
-export const WithBadge: Story = {
-  args: {
-    initials: "AG",
-    size: "lg",
-    badge: <FaCircle className="text-emerald-500 text-[10px]" />,
-  },
-};
-
-export const Sizes: Story = {
-  render: () => (
-    <div className="flex items-end gap-4">
-      {(["xs", "sm", "md", "lg", "xl"] as const).map((s) => (
-        <ITAvatar key={s} initials="A" size={s} />
-      ))}
-    </div>
-  ),
-};
-
-export const WithRawColor: Story = {
-  name: "Con color calculado en runtime",
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Cuando el color se calcula dinámicamente (por ejemplo, un hash por usuario o etiqueta), pasa un valor de color real en vez de una clase de Tailwind. Una clase de Tailwind arbitraria solo se ve si ya existe en el CSS pre-compilado de esta librería; un color inline siempre se aplica.",
-      },
-    },
-  },
-  render: () => (
-    <div className="flex items-center gap-4">
-      {["#3b82f6", "#a855f7", "#059669", "#f59e0b", "#ec4899"].map((hex) => (
-        <ITAvatar key={hex} initials="JD" size="md" color={hex} />
-      ))}
-    </div>
-  ),
-};

package/src/components/atoms/badget/badget.doc.mdx

@@ -1,46 +0,0 @@
-import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
-import * as StoriesData from './badget.stories';
-
-<Meta of={StoriesData} />
-
-# ITBadget
-
-Small status tags and labels for highlighting metadata, categories, or states. Offers filled and outlined visual variants across all semantic color themes. Accepts either a simple label string or custom React children for complex content.
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `label` | `string` | — | Text label displayed inside the badge. Overridden if `children` is provided. |
-| `children` | `ReactNode` | — | Custom content rendered inside the badge. Takes precedence over `label`. |
-| `color` | `ColorsTypes` | `"primary"` | Color theme key (`"primary"`, `"secondary"`, `"success"`, `"danger"`, `"warning"`, `"purple"`, `"info"`). |
-| `size` | `SizesTypes` | `"md"` | Badge size (`"sm"`, `"md"`, `"lg"`). |
-| `variant` | `"filled" \| "outlined"` | `"filled"` | Visual style — solid background or transparent with colored border. |
-| `className` | `string` | — | Additional CSS class names for the badge element. |
-
-## Usage
-
-```tsx
-import { ITBadget } from '@axzydev/axzy_ui_system';
-
-<ITBadget label="Active" color="success" variant="filled" />
-
-<ITBadget color="danger" variant="outlined" size="sm">
-  <span className="flex items-center gap-1">3 new</span>
-</ITBadget>
-```
-
-## Variants / Notes
-
-- **filled** — Solid background with contrasting text (default for most theme colors).
-- **outlined** — Transparent background with a colored border and darker text.
-- Colors include `primary`, `secondary`, `success`, `danger`, `warning`, `purple`, and `info`.
-- Border radius defaults to fully rounded (`borderRadius: 9999px`), giving a pill shape.
-- Styles are fully theme-driven via the centralized theme configuration.
-- Custom children override the `label` prop entirely.
-
-## Stories
-
-<Primary />
-<Controls />
-<Stories />

package/src/components/atoms/badget/badget.stories.tsx

@@ -1,75 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react';
-import ITBadget from '@/components/atoms/badget/badget';
-
-const meta = {
-  title: 'Components/Data Display/ITBadge',
-  component: ITBadget,
-  parameters: {
-    layout: 'centered',
-  },
-  argTypes: {
-    color: {
-      control: 'select',
-      options: ['primary', 'secondary', 'success', 'danger', 'warning', 'purple', 'info'],
-    },
-    variant: {
-        control: 'select',
-        options: ['filled', 'outlined'],
-    },
-    size: {
-        control: 'select',
-        options: ['small', 'medium', 'large'],
-    },
-  },
-} satisfies Meta<typeof ITBadget>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-// 1. Filled (Default)
-export const Filled: Story = {
-  args: {
-    label: 'Filled Badge',
-    color: 'primary',
-    variant: 'filled',
-  },
-};
-
-// 2. Outlined
-export const Outlined: Story = {
-  args: {
-    label: 'Outlined Badge',
-    color: 'primary',
-    variant: 'outlined',
-  },
-};
-
-// 3. All Combinations (Matrix)
-export const AllCombinations: Story = {
-  render: (args) => {
-    const colors = ['primary', 'secondary', 'success', 'danger', 'warning', 'purple', 'info'];
-    const variants = ['filled', 'outlined'];
-
-    return (
-      <div className="flex flex-col gap-8">
-        {variants.map((variant) => (
-          <div key={variant} className="flex flex-col gap-2">
-            <h3 className="text-sm font-bold uppercase text-gray-400">{variant}</h3>
-            <div className="flex flex-wrap gap-4 items-center">
-              {colors.map((color) => (
-                <ITBadget
-                  key={`${variant}-${color}`}
-                  {...args}
-                  color={color as any}
-                  variant={variant as any}
-                  label={color.charAt(0).toUpperCase() + color.slice(1)}
-                />
-              ))}
-            </div>
-          </div>
-        ))}
-      </div>
-    );
-  },
-  args: {},
-};

package/src/components/atoms/button/button.doc.mdx

@@ -1,59 +0,0 @@
-import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
-import * as StoriesData from './button.stories';
-
-<Meta of={StoriesData} />
-
-# ITButton
-
-The primary action component for triggering user interactions. Supports 8 distinct visual variants, 7 semantic color themes, and 3 sizes. Can render with an icon alongside a label, as an icon-only control, as a text link, or with custom children for flexible content.
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `label` | `string` | — | Button text label. Overridden if `children` is provided. |
-| `children` | `ReactNode` | — | Custom content rendered inside the button. Takes precedence over `label`. |
-| `icon` | `ReactNode` | — | Icon element rendered before the label. |
-| `onClick` | `() => void` | — | Click handler for the button. |
-| `color` | `ColorsTypes` | `"primary"` | Color theme key (`"primary"`, `"secondary"`, `"success"`, `"danger"`, `"warning"`, `"purple"`, `"info"`). |
-| `size` | `SizesTypes` | `"md"` | Button size (`"sm"`, `"md"`, `"lg"`). |
-| `variant` | `"filled" \| "outlined" \| "raised" \| "rounded" \| "text" \| "raised-text" \| "icon-only" \| "link"` | `"filled"` | Visual style variant. |
-| `disabled` | `boolean` | `false` | Disables interaction and applies reduced opacity. |
-| `className` | `string` | — | Additional CSS class names for the button element. |
-| `type` | `"submit" \| "reset" \| "button"` | `"button"` | HTML button type attribute. |
-| `ariaLabel` | `string` | — | Accessible label for screen readers. Falls back to `label`. |
-| `title` | `string` | — | HTML title attribute for native tooltip. |
-
-## Usage
-
-```tsx
-import { ITButton } from '@axzydev/axzy_ui_system';
-
-<ITButton label="Guardar" color="primary" variant="filled" />
-
-<ITButton label="Descargar" color="success" variant="outlined" icon={<FaDownload />} />
-
-<ITButton color="danger" variant="icon-only" ariaLabel="Eliminar">
-  <FaTrash />
-</ITButton>
-```
-
-## Variants / Notes
-
-- **filled** — Solid background with shadow, the default and most prominent variant.
-- **outlined** — Transparent background with a colored border.
-- **raised** — Solid background with a pronounced box shadow for depth.
-- **rounded** — Like filled but with fully rounded (`rounded-full`) corners.
-- **text** — Minimal transparent background with hover highlight, suitable for toolbars.
-- **raised-text** — White background with subtle border and shadow, elevated appearance.
-- **icon-only** — Square aspect ratio with centered icon, no text label.
-- **link** — Renders as an inline text link with underline on hover.
-- Seven color themes: `primary`, `secondary`, `success`, `danger`, `warning`, `purple`, `info`.
-- When `disabled`, the button becomes non-interactive with reduced opacity.
-- Set `type="submit"` for form submission behavior.
-
-## Stories
-
-<Primary />
-<Controls />
-<Stories />