@axzydev/axzy_ui_system 1.4.8 → 1.5.0

package/src/sandbox/icons.tsx

@@ -0,0 +1,25 @@
+/**
+ * Íconos de las familias del catálogo, compartidos por la barra lateral
+ * (`App.tsx`) y la landing (`LandingShowcase`) para que la misma familia se vea
+ * igual en los dos sitios.
+ */
+
+import type { ReactNode } from "react";
+import {
+  FaBell,
+  FaCreditCard,
+  FaHome,
+  FaKeyboard,
+  FaSlidersH,
+  FaTable,
+} from "react-icons/fa";
+
+/** Ícono por id de grupo (`navigation.ts`). */
+export const GROUP_ICONS: Record<string, ReactNode> = {
+  general: <FaHome />,
+  struc: <FaCreditCard />,
+  forms: <FaKeyboard />,
+  data: <FaTable />,
+  nav: <FaSlidersH />,
+  feed: <FaBell />,
+};

package/src/sandbox/locale.tsx

@@ -0,0 +1,72 @@
+/**
+ * Idioma del sandbox, compartido entre el chrome (ITTopBar) y las páginas del
+ * portafolio.
+ *
+ * La preferencia vivía solo en `App`, así que el portafolio no podía cambiarla:
+ * ahora se expone por contexto para que el selector del header del portafolio y
+ * el de la barra del sandbox muevan el mismo estado (y persistan en
+ * `localStorage`).
+ */
+
+import { createContext, useContext, useEffect, useState, type ReactNode } from "react";
+import type { ITLocale } from "@/i18n";
+
+/** Valor del contexto de idioma del sandbox. */
+export interface SandboxLocaleValue {
+  /** Idioma activo. */
+  locale: ITLocale;
+  /** Cambia el idioma y lo persiste. */
+  setLocale: (locale: ITLocale) => void;
+}
+
+/** Clave de `localStorage` donde se recuerda la preferencia. */
+const STORAGE_KEY = "it-locale";
+
+const SandboxLocaleContext = createContext<SandboxLocaleValue | undefined>(undefined);
+
+/**
+ * Lee la preferencia guardada. Cualquier valor distinto de `"en"` cae en `"es"`,
+ * que es el idioma por defecto del sandbox.
+ */
+function readStoredLocale(): ITLocale {
+  if (typeof window === "undefined") return "es";
+  return window.localStorage.getItem(STORAGE_KEY) === "en" ? "en" : "es";
+}
+
+/**
+ * Provee el idioma del sandbox a todo el árbol (chrome + páginas).
+ *
+ * @example
+ * ```tsx
+ * <SandboxLocaleProvider>
+ *   <ITI18nProvider locale={locale} messages={sandboxMessages}>…</ITI18nProvider>
+ * </SandboxLocaleProvider>
+ * ```
+ */
+export function SandboxLocaleProvider({ children }: { children: ReactNode }) {
+  const [locale, setLocale] = useState<ITLocale>(readStoredLocale);
+
+  useEffect(() => {
+    window.localStorage.setItem(STORAGE_KEY, locale);
+  }, [locale]);
+
+  return (
+    <SandboxLocaleContext.Provider value={{ locale, setLocale }}>
+      {children}
+    </SandboxLocaleContext.Provider>
+  );
+}
+
+/**
+ * Acceso al idioma del sandbox. Fuera del provider devuelve español y un cambio
+ * de idioma sin efecto, para que una página se pueda renderizar aislada (tests,
+ * Storybook futuro) sin explotar.
+ */
+export function useSandboxLocale(): SandboxLocaleValue {
+  return (
+    useContext(SandboxLocaleContext) ?? {
+      locale: "es",
+      setLocale: () => undefined,
+    }
+  );
+}

package/src/sandbox/ui.tsx

@@ -0,0 +1,377 @@
+/**
+ * Kit de UI de las superficies dev (sandbox `#ui-system` + portafolio `/`).
+ *
+ * Son las piezas que **no** se usan de la librería publicada porque esta no
+ * garantiza contraste AA con la paleta por defecto: `ITButton` relleno queda en
+ * 2.4:1, `ITButton color="secondary"` en 3.7:1, `ITBadget` outlined en 2.6:1 y
+ * `ITSegmentedControl` en 4.34:1. Aquí el acento se usa en `primary-700`
+ * (claro) / `primary-500` (oscuro), que sí pasan.
+ *
+ * Vive en `src/sandbox/` a propósito: es dev-only y nunca entra en `dist/`.
+ * Sigue `DESIGN.md` (AXZY Console): superficies planas con borde de 1px,
+ * metadatos en mono, filetes para separar y sombra solo al hover.
+ */
+
+import { useState, type ReactNode } from "react";
+import { FaCheck, FaCopy } from "react-icons/fa";
+import { useITTranslation } from "@/i18n";
+
+/** Eyebrow mono apagado: encabezados de sección y etiquetas de metadato. */
+export const EYEBROW =
+  "font-mono !text-[11px] !font-medium uppercase !tracking-[0.14em] text-slate-500 dark:text-slate-400";
+
+/** Filete de 1px: la separación entre bloques. */
+export const FILETE = "border-slate-200 dark:border-slate-800";
+
+/** Superficie de tarjeta: borde 1px, radio 14px, sin sombra en reposo. */
+export const CARD =
+  "rounded-[14px] border border-slate-200 bg-white transition-all duration-200 dark:border-slate-800 dark:bg-slate-900";
+
+/** Refuerzo al hover de las tarjetas: borde acento, lift de 2px y sombra suave. */
+export const CARD_HOVER =
+  "hover:-translate-y-0.5 hover:border-primary-400 hover:shadow-[0_8px_30px_-12px_rgba(15,23,42,0.25)] dark:hover:border-primary-500";
+
+/** Chip mono chico para stack y metadatos. */
+export const CHIP =
+  "rounded-[6px] border border-slate-200 bg-slate-50 px-2 py-0.5 font-mono text-[10px] text-slate-500 dark:border-slate-800 dark:bg-slate-950 dark:text-slate-400";
+
+/**
+ * Variantes visuales de los CTA. `outlined` es el borde de acento (segundo CTA
+ * de un bloque) y `neutral` el ghost de tinta para acciones que no compiten
+ * (volver, cerrar).
+ */
+export type VarianteCta = "filled" | "outlined" | "neutral" | "text";
+
+/** Tamaños de los CTA (mismos paddings y tipografía que `ITButton`). */
+export type TamanoCta = "sm" | "md" | "lg";
+
+/** Padding y tipografía por tamaño (idénticos a `ITButton`). */
+export const TAMANO_CTA: Record<TamanoCta, string> = {
+  sm: "text-xs px-2.5 py-1",
+  md: "text-[13px] px-3.5 py-1.5",
+  lg: "text-sm px-4 py-2",
+};
+
+/**
+ * Color por variante. El relleno usa `primary-700` (5.05:1 con blanco) porque
+ * el `primary-600` de la paleta resuelta se queda en 3.3:1.
+ */
+export const VARIANTE_CTA: Record<VarianteCta, string> = {
+  filled:
+    "border border-transparent bg-primary-700 text-white shadow-sm hover:bg-primary-800",
+  outlined:
+    "border border-primary-700 text-primary-700 hover:bg-primary-700/10 dark:border-primary-500 dark:text-primary-500",
+  neutral:
+    "border border-slate-300 text-slate-700 hover:bg-slate-100 dark:border-slate-700 dark:text-slate-200 dark:hover:bg-slate-800",
+  text: "border border-transparent text-primary-700 hover:bg-primary-700/10 dark:text-primary-500",
+};
+
+/** Foco compartido por todos los CTA (anillo del acento, offset del lienzo). */
+export const FOCO_CTA =
+  "focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500/60 focus-visible:ring-offset-2 focus-visible:ring-offset-[#fafafa] dark:focus-visible:ring-offset-[#0b0d10]";
+
+/** Props de `EnlaceBoton`. */
+export interface EnlaceBotonProps {
+  /** Destino. Interno (`#...`, `/...`) o externo (`https://...`). */
+  href: string;
+  /** Texto visible del enlace. */
+  children: ReactNode;
+  /** Estilo visual. @default "filled" */
+  variante?: VarianteCta;
+  /** Tamaño. @default "md" */
+  tamano?: TamanoCta;
+  /** Ícono a la izquierda del texto. */
+  icono?: ReactNode;
+  /** Fuerza abrir en pestaña nueva. Por defecto se deduce de `href`. */
+  externo?: boolean;
+  /** Marca la descarga (`download`) para archivos propios. */
+  descargar?: boolean;
+  /** Clases extra. */
+  className?: string;
+  /** Nombre accesible cuando el texto visible no alcanza. */
+  ariaLabel?: string;
+}
+
+/**
+ * CTA que **es un enlace de verdad**: `ITButton` renderiza un `<button>`, así que
+ * envolverlo en `<a>` producía interactivos anidados (HTML inválido y fallo
+ * `nested-interactive` en axe). Esta pieza conserva el aspecto del botón, pero
+ * mantiene la semántica de enlace: clic central, "abrir en pestaña nueva", menú
+ * contextual y URL en la barra de estado.
+ *
+ * @example
+ * ```tsx
+ * <EnlaceBoton href={GITHUB_URL} variante="outlined" icono={<FaGithub size={12} />}>
+ *   GitHub
+ * </EnlaceBoton>
+ * ```
+ */
+export const EnlaceBoton = ({
+  href,
+  children,
+  variante = "filled",
+  tamano = "md",
+  icono,
+  externo,
+  descargar = false,
+  className = "",
+  ariaLabel,
+}: EnlaceBotonProps) => {
+  const esExterno = externo ?? /^https?:\/\//.test(href);
+
+  return (
+    <a
+      href={href}
+      {...(esExterno ? { target: "_blank", rel: "noopener noreferrer" } : {})}
+      {...(descargar ? { download: "" } : {})}
+      aria-label={ariaLabel}
+      className={`inline-flex shrink-0 items-center justify-center gap-1.5 rounded-[10px] font-semibold transition-colors duration-200 ${FOCO_CTA} ${TAMANO_CTA[tamano]} ${VARIANTE_CTA[variante]} ${className}`}
+    >
+      {icono && <span className="flex-shrink-0">{icono}</span>}
+      <span>{children}</span>
+    </a>
+  );
+};
+
+/** Props de `BotonAccion`. */
+export interface BotonAccionProps {
+  /** Acción al pulsar. */
+  onClick: () => void;
+  /** Texto visible. */
+  children: ReactNode;
+  /** Estilo visual. @default "neutral" */
+  variante?: VarianteCta;
+  /** Tamaño. @default "md" */
+  tamano?: TamanoCta;
+  /** Ícono a la izquierda. */
+  icono?: ReactNode;
+  /** Clases extra. */
+  className?: string;
+}
+
+/**
+ * Acción que **no** navega (volver, abrir una pestaña interna): mismo aspecto que
+ * `EnlaceBoton` pero con semántica de botón.
+ *
+ * @example
+ * ```tsx
+ * <BotonAccion onClick={onBack} icono={<FaArrowLeft size={12} />}>Volver</BotonAccion>
+ * ```
+ */
+export const BotonAccion = ({
+  onClick,
+  children,
+  variante = "neutral",
+  tamano = "md",
+  icono,
+  className = "",
+}: BotonAccionProps) => (
+  <button
+    type="button"
+    onClick={onClick}
+    className={`inline-flex shrink-0 items-center justify-center gap-1.5 rounded-[10px] font-semibold transition-colors duration-200 ${FOCO_CTA} ${TAMANO_CTA[tamano]} ${VARIANTE_CTA[variante]} ${className}`}
+  >
+    {icono && <span className="flex-shrink-0">{icono}</span>}
+    <span>{children}</span>
+  </button>
+);
+
+/** Props de `Etiqueta`. */
+export interface EtiquetaProps {
+  /** Texto de la etiqueta (tipo, estado…). */
+  children: ReactNode;
+  /** Clases extra. */
+  className?: string;
+}
+
+/**
+ * Píldora de metadato con el acento del proyecto.
+ *
+ * Sustituye a `ITBadget`: el badge del tema resuelve su color desde la paleta y
+ * con la paleta por defecto queda en 2.6:1 sobre las tarjetas oscuras.
+ *
+ * @example
+ * ```tsx
+ * <Etiqueta>Librería</Etiqueta>
+ * ```
+ */
+export const Etiqueta = ({ children, className = "" }: EtiquetaProps) => (
+  <span
+    className={`shrink-0 rounded-full border border-primary-800/45 px-2 py-[3px] text-[11px] font-semibold text-primary-800 dark:border-primary-500/45 dark:text-primary-500 ${className}`}
+  >
+    {children}
+  </span>
+);
+
+/**
+ * Encabezado de sección de la hoja: `NN — ETIQUETA`, título display y apoyo,
+ * con acciones opcionales a la derecha.
+ *
+ * @example
+ * ```tsx
+ * <SectionHeading index={2} label="Catálogo" title="Explora por familia" subtitle="…" />
+ * ```
+ */
+export const SectionHeading = ({
+  index,
+  label,
+  title,
+  subtitle,
+  actions,
+  className = "",
+}: {
+  /** Índice de sección (0-based; se pinta con dos dígitos). */
+  index: number;
+  /** Etiqueta mono corta. */
+  label: string;
+  /** Título display. */
+  title: string;
+  /** Frase de apoyo. */
+  subtitle?: string;
+  /** Contenido alineado a la derecha. */
+  actions?: ReactNode;
+  /** Clases extra. */
+  className?: string;
+}) => (
+  <div
+    className={`flex flex-col gap-5 md:flex-row md:items-end md:justify-between ${className}`}
+  >
+    <div className="min-w-0">
+      <p className={EYEBROW}>
+        <span className="tabular-nums">{String(index + 1).padStart(2, "0")}</span>
+        {` — ${label}`}
+      </p>
+      <h2 className="mt-2.5 font-display text-[26px] font-bold tracking-[-0.02em] text-slate-900 dark:text-white sm:text-[32px]">
+        {title}
+      </h2>
+      {subtitle && (
+        <p className="mt-2 max-w-[62ch] text-[15px] leading-relaxed text-slate-500 dark:text-slate-400">
+          {subtitle}
+        </p>
+      )}
+    </div>
+    {actions && <div className="shrink-0">{actions}</div>}
+  </div>
+);
+
+/**
+ * Enlace externo mono en línea (GitHub, npm, docs). Mantiene el acento AA y se
+ * subraya al hover.
+ *
+ * @example
+ * ```tsx
+ * <EnlaceMono href={GITHUB_URL} icono={<FaGithub size={11} />}>GitHub</EnlaceMono>
+ * ```
+ */
+export const EnlaceMono = ({
+  href,
+  children,
+  icono,
+  className = "",
+}: {
+  /** Destino (normalmente externo). */
+  href: string;
+  /** Texto visible. */
+  children: ReactNode;
+  /** Ícono a la izquierda. */
+  icono?: ReactNode;
+  /** Clases extra. */
+  className?: string;
+}) => (
+  <a
+    href={href}
+    {...(/^https?:\/\//.test(href) ? { target: "_blank", rel: "noopener noreferrer" } : {})}
+    className={`inline-flex items-center gap-1.5 font-mono !text-[11px] uppercase !tracking-[0.14em] !text-primary-700 transition-colors hover:underline dark:!text-primary-500 ${className}`}
+  >
+    {icono}
+    {children}
+  </a>
+);
+
+/**
+ * Botón mono de «copiar al portapapeles» con confirmación de dos segundos.
+ *
+ * @example
+ * ```tsx
+ * <BotonCopiar texto="pnpm add @axzydev/axzy_ui_system" />
+ * ```
+ */
+export const BotonCopiar = ({
+  texto,
+  className = "",
+}: {
+  /** Texto que se copia. */
+  texto: string;
+  /** Clases extra. */
+  className?: string;
+}) => {
+  const { t } = useITTranslation();
+  const [copiado, setCopiado] = useState(false);
+
+  const copiar = () => {
+    navigator.clipboard?.writeText(texto);
+    setCopiado(true);
+    window.setTimeout(() => setCopiado(false), 2000);
+  };
+
+  return (
+    <button
+      type="button"
+      onClick={copiar}
+      className={`inline-flex items-center gap-1.5 rounded-[8px] px-2.5 py-1 font-mono text-[10px] uppercase tracking-[0.12em] text-slate-500 transition-colors hover:bg-slate-100 hover:text-slate-900 focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500/60 dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-white ${className}`}
+    >
+      {copiado ? (
+        <FaCheck size={10} className="text-primary-700 dark:text-primary-500" />
+      ) : (
+        <FaCopy size={10} />
+      )}
+      {copiado ? t("showcase.layout.copied") : t("showcase.layout.copy")}
+    </button>
+  );
+};
+
+/**
+ * Bloque de código: fondo tinta, mono, etiqueta del archivo y botón de copiar.
+ * El acento de señal (`cyan-400`) solo se usa aquí, como manda el spec.
+ *
+ * @example
+ * ```tsx
+ * <BloqueCodigo filename="vite.config.ts" code={`export default defineConfig({})`} />
+ * ```
+ */
+export const BloqueCodigo = ({
+  code,
+  filename,
+  compact = false,
+  className = "",
+}: {
+  /** Código a mostrar. */
+  code: string;
+  /** Etiqueta mono de la esquina (archivo o lenguaje). */
+  filename?: string;
+  /** Limita la altura con scroll vertical. */
+  compact?: boolean;
+  /** Clases extra. */
+  className?: string;
+}) => (
+  <div
+    className={`overflow-hidden rounded-[10px] border border-slate-800 bg-slate-950 ${className}`}
+  >
+    <div className="flex items-center justify-between gap-3 border-b border-slate-800 px-4 py-2.5">
+      <span className="font-mono text-[10px] uppercase tracking-[0.14em] text-cyan-400">
+        {filename ?? "code"}
+      </span>
+      <BotonCopiar
+        texto={code}
+        className="text-slate-400 hover:bg-slate-800 hover:text-white dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-white"
+      />
+    </div>
+    <pre
+      className={`overflow-x-auto whitespace-pre-wrap p-4 font-mono text-xs leading-relaxed text-slate-200 ${
+        compact ? "max-h-[420px] overflow-y-auto" : ""
+      }`}
+    >
+      <code>{code}</code>
+    </pre>
+  </div>
+);

package/src/sandbox/useHashRoute.ts

@@ -1,8 +1,9 @@
 import { useCallback, useEffect, useState } from "react";
 import { GROUP_SLUGS, groupBySlug, isValidItem } from "./navigation";
+import { PRODUCTOS } from "../showcases/productos";
 
-/** Top-level sandbox views. `home` is the untouched portfolio. */
-export type SandboxView = "home" | "ui-system";
+/** Top-level sandbox views. `home` is the portfolio, `producto` a project detail page. */
+export type SandboxView = "home" | "ui-system" | "producto";
 
 /** Parsed representation of `window.location.hash`. */
 export interface HashRoute {
@@ -12,20 +13,28 @@ export interface HashRoute {
   group: string | null;
   /** Item id (`input`, `table`, …) or `null` for a group-only route. */
   item: string | null;
+  /** Product id when `view === "producto"`. */
+  producto: string | null;
   /** Raw hash exactly as read from the URL (used by the 404 page). */
   raw: string;
   /** Whether the route resolved to a real page. `false` → render 404. */
   valid: boolean;
 }
 
+/** Whether a product id exists in the portfolio catalog. */
+function isValidProducto(id: string): boolean {
+  return PRODUCTOS.some((producto) => producto.id === id);
+}
+
 /**
  * Parse a location hash into a `HashRoute`.
  *
  * Rules:
- * - empty / first segment !== `ui-system` → portfolio (`home`).
+ * - empty / first segment not in `{ui-system, proyecto}` → portfolio (`home`).
  * - `#ui-system` → landing.
  * - `#ui-system/<group-slug>` → group landing (valid, `item` null).
  * - `#ui-system/<group-slug>/<item-id>` → page (valid) or 404 when unknown.
+ * - `#proyecto/<product-id>` → project detail page (valid) or 404 when unknown.
  * - more than 3 segments → 404.
  */
 export function parseHash(hash: string): HashRoute {
@@ -33,20 +42,32 @@ export function parseHash(hash: string): HashRoute {
   const clean = hash.startsWith("#") ? hash.slice(1) : hash;
   const parts = clean.split("/").filter(Boolean);
 
+  if (parts[0] === "proyecto") {
+    const producto = parts[1] ?? null;
+    return {
+      view: "producto",
+      group: null,
+      item: null,
+      producto,
+      raw,
+      valid: Boolean(producto) && isValidProducto(producto as string),
+    };
+  }
+
   if (parts.length === 0 || parts[0] !== "ui-system") {
-    return { view: "home", group: null, item: null, raw, valid: true };
+    return { view: "home", group: null, item: null, producto: null, raw, valid: true };
   }
 
   if (parts.length === 1) {
-    return { view: "ui-system", group: null, item: null, raw, valid: true };
+    return { view: "ui-system", group: null, item: null, producto: null, raw, valid: true };
   }
 
   if (parts.length === 2) {
     const group = groupBySlug(parts[1]);
     if (!group) {
-      return { view: "ui-system", group: null, item: null, raw, valid: false };
+      return { view: "ui-system", group: null, item: null, producto: null, raw, valid: false };
     }
-    return { view: "ui-system", group: group.id, item: null, raw, valid: true };
+    return { view: "ui-system", group: group.id, item: null, producto: null, raw, valid: true };
   }
 
   if (parts.length === 3) {
@@ -56,14 +77,15 @@ export function parseHash(hash: string): HashRoute {
         view: "ui-system",
         group: group?.id ?? null,
         item: null,
+        producto: null,
         raw,
         valid: false,
       };
     }
-    return { view: "ui-system", group: group.id, item: parts[2], raw, valid: true };
+    return { view: "ui-system", group: group.id, item: parts[2], producto: null, raw, valid: true };
   }
 
-  return { view: "ui-system", group: null, item: null, raw, valid: false };
+  return { view: "ui-system", group: null, item: null, producto: null, raw, valid: false };
 }
 
 /** Build a hash for a group/item pair, translating the group id to its slug. */
@@ -72,6 +94,11 @@ export function buildHash(group: string, item?: string): string {
   return item ? `#ui-system/${slug}/${item}` : `#ui-system/${slug}`;
 }
 
+/** Build the hash of a project detail page. */
+export function buildProductoHash(id: string): string {
+  return `#proyecto/${id}`;
+}
+
 /** Navigation options shared by every `goTo*` helper. */
 export interface GoToOptions {
   /** Replace the current history entry instead of pushing a new one. */
@@ -86,6 +113,8 @@ export interface UseHashRouteResult {
   goToItem: (group: string, item: string, options?: GoToOptions) => void;
   /** Navigate to the `#ui-system` landing. */
   goToLanding: (options?: GoToOptions) => void;
+  /** Navigate to a project detail page. */
+  goToProducto: (id: string, options?: GoToOptions) => void;
   /** Navigate back to the portfolio (strips the hash). */
   goToPortfolio: (options?: GoToOptions) => void;
 }
@@ -135,6 +164,13 @@ export function useHashRoute(): UseHashRouteResult {
     [navigate],
   );
 
+  const goToProducto = useCallback(
+    (id: string, options?: GoToOptions) => {
+      navigate(buildProductoHash(id), options);
+    },
+    [navigate],
+  );
+
   const goToPortfolio = useCallback((options?: GoToOptions) => {
     const url = `${window.location.pathname}${window.location.search}`;
     if (options?.replace) {
@@ -145,5 +181,5 @@ export function useHashRoute(): UseHashRouteResult {
     setRoute(parseHash(""));
   }, []);
 
-  return { route, goToItem, goToLanding, goToPortfolio };
+  return { route, goToItem, goToLanding, goToProducto, goToPortfolio };
 }