@devpablocristo/platform-browser 0.1.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@devpablocristo/platform-browser",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./storage": "./src/storage.ts",
+    "./crud": "./src/crud/index.ts",
+    "./search": "./src/search/index.ts",
+    "./theme": "./src/theme.ts",
+    "./observability": "./src/observability.ts",
+    "./i18n": "./src/i18n/index.ts"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@types/node": "^25.7.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.6",
+    "jsdom": "^29.1.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/*.spec.tsx"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/confirm/index.tsx

@@ -0,0 +1,170 @@
+import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+
+export type ConfirmDialogTone = "primary" | "danger";
+
+export type ConfirmDialogOptions = {
+  title?: ReactNode;
+  description?: ReactNode;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  tone?: ConfirmDialogTone;
+  allowEscapeClose?: boolean;
+  allowBackdropClose?: boolean;
+};
+
+type ConfirmRequest = Required<
+  Pick<ConfirmDialogOptions, "confirmLabel" | "cancelLabel" | "tone" | "allowEscapeClose" | "allowBackdropClose">
+> &
+  Omit<ConfirmDialogOptions, "confirmLabel" | "cancelLabel" | "tone" | "allowEscapeClose" | "allowBackdropClose"> & {
+    id: number;
+    resolve: (confirmed: boolean) => void;
+  };
+
+type ConfirmOpenHandler = (options: ConfirmDialogOptions) => Promise<boolean>;
+
+let confirmOpenHandler: ConfirmOpenHandler | null = null;
+let confirmRequestId = 0;
+
+function normalizeConfirmOptions(options: ConfirmDialogOptions, resolve: (confirmed: boolean) => void): ConfirmRequest {
+  return {
+    id: ++confirmRequestId,
+    title: options.title,
+    description: options.description,
+    confirmLabel: options.confirmLabel ?? "Confirmar",
+    cancelLabel: options.cancelLabel ?? "Cancelar",
+    tone: options.tone ?? "primary",
+    allowEscapeClose: options.allowEscapeClose ?? true,
+    allowBackdropClose: options.allowBackdropClose ?? true,
+    resolve,
+  };
+}
+
+function fallbackConfirmMessage(options: ConfirmDialogOptions): string {
+  const title = typeof options.title === "string" ? options.title : "";
+  const description = typeof options.description === "string" ? options.description : "";
+  return [title, description].filter(Boolean).join("\n\n") || "¿Confirmar acción?";
+}
+
+export function confirmAction(options: ConfirmDialogOptions): Promise<boolean> {
+  if (confirmOpenHandler) {
+    return confirmOpenHandler(options);
+  }
+  if (typeof window !== "undefined" && typeof window.confirm === "function") {
+    return Promise.resolve(window.confirm(fallbackConfirmMessage(options)));
+  }
+  return Promise.resolve(false);
+}
+
+export function ConfirmDialogProvider({ children }: { children: ReactNode }) {
+  const [queue, setQueue] = useState<ConfirmRequest[]>([]);
+  const activeRequestRef = useRef<ConfirmRequest | null>(null);
+
+  const openConfirm = useCallback((options: ConfirmDialogOptions) => {
+    return new Promise<boolean>((resolve) => {
+      setQueue((current) => [...current, normalizeConfirmOptions(options, resolve)]);
+    });
+  }, []);
+
+  useEffect(() => {
+    confirmOpenHandler = openConfirm;
+    return () => {
+      if (confirmOpenHandler === openConfirm) {
+        confirmOpenHandler = null;
+      }
+    };
+  }, [openConfirm]);
+
+  const activeRequest = queue[0] ?? null;
+
+  useEffect(() => {
+    activeRequestRef.current = activeRequest;
+  }, [activeRequest]);
+
+  const settleActiveRequest = useCallback((confirmed: boolean) => {
+    const request = activeRequestRef.current;
+    if (!request) {
+      return;
+    }
+    activeRequestRef.current = null;
+    request.resolve(confirmed);
+    setQueue((current) => current.slice(1));
+  }, []);
+
+  useEffect(() => {
+    if (!activeRequest?.allowEscapeClose) {
+      return;
+    }
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Escape") {
+        return;
+      }
+      event.preventDefault();
+      settleActiveRequest(false);
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [activeRequest, settleActiveRequest]);
+
+  const dialog = useMemo(() => {
+    if (!activeRequest) {
+      return null;
+    }
+    const titleId = `confirm-dialog-title-${activeRequest.id}`;
+    const descriptionId = `confirm-dialog-description-${activeRequest.id}`;
+
+    return (
+      <div
+        className="confirm-dialog__backdrop"
+        role="presentation"
+        onMouseDown={(event) => {
+          if (event.target !== event.currentTarget || !activeRequest.allowBackdropClose) {
+            return;
+          }
+          settleActiveRequest(false);
+        }}
+      >
+        <section
+          className="confirm-dialog"
+          role="alertdialog"
+          aria-modal="true"
+          aria-labelledby={titleId}
+          aria-describedby={activeRequest.description != null ? descriptionId : undefined}
+          onMouseDown={(event) => event.stopPropagation()}
+        >
+          <div className="confirm-dialog__header">
+            <h2 id={titleId} className="confirm-dialog__title">
+              {activeRequest.title ?? "Confirmar acción"}
+            </h2>
+          </div>
+          {activeRequest.description != null ? (
+            <div className="confirm-dialog__body">
+              <p id={descriptionId} className="confirm-dialog__description">
+                {activeRequest.description}
+              </p>
+            </div>
+          ) : null}
+          <div className="confirm-dialog__footer">
+            <button type="button" className="btn-secondary btn-sm" onClick={() => settleActiveRequest(false)}>
+              {activeRequest.cancelLabel}
+            </button>
+            <button
+              type="button"
+              className={`${activeRequest.tone === "danger" ? "btn-danger" : "btn-primary"} btn-sm`}
+              onClick={() => settleActiveRequest(true)}
+            >
+              {activeRequest.confirmLabel}
+            </button>
+          </div>
+        </section>
+      </div>
+    );
+  }, [activeRequest, settleActiveRequest]);
+
+  return (
+    <>
+      {children}
+      {dialog && typeof document !== "undefined" ? createPortal(dialog, document.body) : dialog}
+    </>
+  );
+}

package/src/crud/CrudPageShell.tsx

@@ -0,0 +1,79 @@
+import type { ReactNode } from "react";
+import { SearchInput } from "../search";
+
+/**
+ * Layout canónico de consola: cabecera (título + acciones), error, formulario,
+ * barra de herramientas (búsqueda / filtros) y cuerpo (spinner, vacío o tabla).
+ * Productos (Pymes u otros) montan datos y i18n encima; las clases CSS viven en el tema de la app.
+ * El host puede combinar `data-theme` y, si aplica, `data-admin-skin` en `<html>` para tokens adicionales.
+ */
+export type CrudPageShellProps = {
+  title: ReactNode;
+  subtitle?: ReactNode;
+  /** Bajo el subtítulo, columna izquierda (p. ej. filtros tipo píldora). */
+  headerLeadSlot?: ReactNode;
+  /** Buscador canónico del header. */
+  search?: {
+    value: string;
+    onChange: (value: string) => void;
+    placeholder?: string;
+    ariaLabel?: string;
+    inputClassName?: string;
+    clearLabel?: string;
+  };
+  /** Fila de acciones bajo el buscador compartido. */
+  headerActions?: ReactNode;
+  error?: ReactNode;
+  /** Tarjeta de formulario alta/edición */
+  form?: ReactNode;
+  /** Fila búsqueda + archivados u otros filtros */
+  toolbar?: ReactNode;
+  children: ReactNode;
+};
+
+export function CrudPageShell({
+  title,
+  subtitle,
+  headerLeadSlot,
+  search,
+  headerActions,
+  error,
+  form,
+  toolbar,
+  children,
+}: CrudPageShellProps) {
+  return (
+    <>
+      <div className="page-header crud-page-shell__header">
+        <div className="crud-page-shell__header-main">
+          <h1 className="crud-page-shell__title">{title}</h1>
+          {subtitle != null && subtitle !== false ? (
+            <p className="text-secondary">{subtitle}</p>
+          ) : null}
+          {headerLeadSlot != null ? headerLeadSlot : null}
+        </div>
+        {search != null || headerActions != null ? (
+          <div className="crud-page-shell__header-actions">
+            {search != null ? (
+              <div className="crud-list-header-search">
+                <SearchInput
+                  value={search.value}
+                  onChange={search.onChange}
+                  placeholder={search.placeholder ?? "Buscar..."}
+                  ariaLabel={search.ariaLabel}
+                  inputClassName={search.inputClassName}
+                  clearLabel={search.clearLabel}
+                />
+              </div>
+            ) : null}
+            {headerActions != null ? <div className="actions-row">{headerActions}</div> : null}
+          </div>
+        ) : null}
+      </div>
+      {error}
+      {form}
+      {toolbar}
+      {children}
+    </>
+  );
+}

package/src/crud/PageLayout.tsx

@@ -0,0 +1,60 @@
+import type { ReactNode } from 'react';
+import { CrudPageShell } from './CrudPageShell';
+import { usePageSearchShellControl } from '../search/PageSearchProvider';
+
+export type PageLayoutProps = {
+  /** Título principal (h1) */
+  title: ReactNode;
+  /** Párrafo lead bajo el título (opcional) */
+  lead?: ReactNode;
+  /** Botones / enlaces a la derecha; activa layout tipo split automáticamente */
+  actions?: ReactNode;
+  /** Contenido entre cabecera y body (alertas, avisos) */
+  banner?: ReactNode;
+  /** Clases extra en el contenedor (e.g. 'dash', 'gcal') */
+  className?: string;
+  /** Label del botón clear de búsqueda (default: 'Clear search') */
+  searchClearLabel?: string;
+  children: ReactNode;
+};
+
+function isPrimitiveLead(lead: ReactNode) {
+  return typeof lead === 'string' || typeof lead === 'number';
+}
+
+/**
+ * Layout estándar de página: wrapper sobre CrudPageShell con integración de PageSearch.
+ */
+export function PageLayout({ title, lead, actions, banner, className, searchClearLabel, children }: PageLayoutProps) {
+  const stackClass = ['page-stack', className].filter(Boolean).join(' ');
+  const pageSearch = usePageSearchShellControl();
+  const hasSearch = pageSearch.visible;
+  const primitiveLead = lead != null && lead !== false && isPrimitiveLead(lead) ? lead : undefined;
+  const richLead =
+    lead != null && lead !== false && !isPrimitiveLead(lead) ? <div className="text-page-lead">{lead}</div> : undefined;
+  return (
+    <div className={stackClass}>
+      <CrudPageShell
+        title={title}
+        subtitle={primitiveLead}
+        headerLeadSlot={richLead}
+        search={
+          hasSearch
+            ? {
+                value: pageSearch.query,
+                onChange: pageSearch.setQuery,
+                placeholder: pageSearch.placeholder,
+                clearLabel: searchClearLabel ?? 'Clear search',
+              }
+            : undefined
+        }
+        headerActions={actions}
+      >
+        <>
+          {banner}
+          {children}
+        </>
+      </CrudPageShell>
+    </div>
+  );
+}

package/src/crud/index.ts

@@ -0,0 +1,3 @@
+export { CrudPageShell, type CrudPageShellProps } from "./CrudPageShell";
+export { PageLayout, type PageLayoutProps } from "./PageLayout";
+export { parseListItemsFromResponse, parsePaginatedResponse, type PaginatedList } from "./listParsing";

package/src/crud/listParsing.ts

@@ -0,0 +1,94 @@
+type ListEnvelope<T> = {
+  items?: T[] | null | unknown;
+  data?: unknown;
+  hasMore?: boolean;
+  has_more?: boolean;
+  nextCursor?: string;
+  next_cursor?: string;
+};
+
+export type PaginatedList<T> = {
+  items: T[];
+  hasMore: boolean;
+  nextCursor: string;
+};
+
+/**
+ * Normaliza respuestas de listado tipo arreglo, `{ items }` o envelopes BFF anidados con `data`.
+ * Go suele serializar slices nil como `null`; cualquier rama sin arreglo termina en lista vacía.
+ */
+export function parseListItemsFromResponse<T>(input: unknown): T[] {
+  const queue: unknown[] = [input];
+  const seen = new Set<unknown>();
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (Array.isArray(current)) {
+      return current as T[];
+    }
+    if (current == null || typeof current !== "object" || seen.has(current)) {
+      continue;
+    }
+
+    seen.add(current);
+    const envelope = current as ListEnvelope<T>;
+
+    if (Array.isArray(envelope.items)) {
+      return envelope.items;
+    }
+
+    if ("data" in envelope) {
+      queue.push(envelope.data);
+    }
+    if ("items" in envelope) {
+      queue.push(envelope.items);
+    }
+  }
+
+  return [];
+}
+
+/**
+ * Como `parseListItemsFromResponse` pero conserva `has_more` y `next_cursor` del backend.
+ */
+export function parsePaginatedResponse<T>(input: unknown): PaginatedList<T> {
+  const items = parseListItemsFromResponse<T>(input);
+  let hasMore = false;
+  let nextCursor = "";
+  const envelope = findEnvelope(input);
+  if (envelope) {
+    hasMore = Boolean(envelope.hasMore ?? envelope.has_more);
+    nextCursor = String(envelope.nextCursor ?? envelope.next_cursor ?? "");
+  } else if (input != null && typeof input === "object" && !Array.isArray(input)) {
+    const envelope = input as ListEnvelope<T>;
+    hasMore = Boolean(envelope.hasMore ?? envelope.has_more);
+    nextCursor = String(envelope.nextCursor ?? envelope.next_cursor ?? "");
+  }
+  return { items, hasMore, nextCursor };
+}
+
+function findEnvelope<T>(input: unknown): ListEnvelope<T> | null {
+  const queue: unknown[] = [input];
+  const seen = new Set<unknown>();
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current == null || typeof current !== "object" || Array.isArray(current) || seen.has(current)) {
+      continue;
+    }
+    seen.add(current);
+    const envelope = current as ListEnvelope<T>;
+    if (
+      "hasMore" in envelope ||
+      "has_more" in envelope ||
+      "nextCursor" in envelope ||
+      "next_cursor" in envelope
+    ) {
+      return envelope;
+    }
+    if ("data" in envelope) queue.push(envelope.data);
+    if ("items" in envelope) queue.push(envelope.items);
+  }
+
+  return null;
+}

package/src/i18n/I18nProvider.tsx

@@ -0,0 +1,128 @@
+/* eslint-disable react-refresh/only-export-components -- provider + hook en mismo archivo */
+import { createContext, useContext, useEffect, useMemo, useState, type PropsWithChildren } from 'react';
+import { createBrowserStorageNamespace } from '../storage';
+import { formatMessage } from './formatMessage';
+import { localeTagForLanguage } from './localeTag';
+import { toSentenceCase } from './sentenceCase';
+import type { FlatMessages, LanguageCode, TranslationVariables, TranslationsByLanguage } from './types';
+
+export type I18nConfig = {
+  /** Namespace para persistir el idioma (e.g. 'pymes-ui') */
+  namespace: string;
+  /** Key de storage (e.g. 'app:language') */
+  storageKey?: string;
+  /** Idioma default (default: 'es') */
+  defaultLanguage?: LanguageCode;
+  /** Claves absolutas en localStorage (sin namespace) a leer una vez y migrar al storage con namespace */
+  legacyLanguageKeys?: string[];
+  /** Idiomas soportados con label keys */
+  supportedLanguages?: Array<{ code: LanguageCode; labelKey: string }>;
+  /** Mensajes agrupados por idioma */
+  messages: Record<LanguageCode, FlatMessages>;
+  /** Función opcional para localizar texto (e.g. vocabulary replacement) */
+  localizeText?: (text: string) => string;
+};
+
+export type I18nContextValue = {
+  language: LanguageCode;
+  setLanguage: (language: LanguageCode) => void;
+  t: (key: string, variables?: TranslationVariables) => string;
+  localizeText: (text: string) => string;
+  sentenceCase: (text: string) => string;
+  localizeUiText: (text: string) => string;
+  options: Array<{ code: LanguageCode; labelKey: string }>;
+};
+
+/**
+ * Merge de múltiples fuentes de traducciones.
+ */
+export function mergeMessages(...sources: TranslationsByLanguage[]): Record<LanguageCode, FlatMessages> {
+  return {
+    es: Object.assign({}, ...sources.map((s) => s.es)),
+    en: Object.assign({}, ...sources.map((s) => s.en)),
+  };
+}
+
+/**
+ * Crea un provider de i18n con storage persistente.
+ * Retorna { Provider, useI18n } para uso en la app.
+ */
+export function createI18nProvider(config: I18nConfig) {
+  const defaultLanguage = config.defaultLanguage ?? 'es';
+  const storageKey = config.storageKey ?? 'language';
+  const supportedLanguages = config.supportedLanguages ?? [
+    { code: 'es', labelKey: 'common.language.es' },
+    { code: 'en', labelKey: 'common.language.en' },
+  ];
+  const storage = createBrowserStorageNamespace({ namespace: config.namespace, hostAware: false });
+  const identity = (text: string) => text;
+  const localizeText = config.localizeText ?? identity;
+
+  function getMessage(language: LanguageCode, key: string, variables?: TranslationVariables): string {
+    return formatMessage(config.messages, language, defaultLanguage, key, variables);
+  }
+
+  function readStoredLanguage(): LanguageCode {
+    if (typeof window === 'undefined') return defaultLanguage;
+    for (const legacyKey of config.legacyLanguageKeys ?? []) {
+      try {
+        const raw = window.localStorage.getItem(legacyKey);
+        if (raw === 'en' || raw === 'es') {
+          window.localStorage.removeItem(legacyKey);
+          storage.setString(storageKey, raw);
+          return raw;
+        }
+      } catch {
+        /* private mode */
+      }
+    }
+    const stored = storage.getString(storageKey);
+    return stored === 'en' || stored === 'es' ? stored : defaultLanguage;
+  }
+
+  const defaultContext: I18nContextValue = {
+    language: defaultLanguage,
+    setLanguage: () => undefined,
+    t: (key, variables) => formatMessage(config.messages, defaultLanguage, defaultLanguage, key, variables),
+    localizeText,
+    sentenceCase: toSentenceCase,
+    localizeUiText: (text) => toSentenceCase(localizeText(text)),
+    options: supportedLanguages,
+  };
+
+  const I18nContext = createContext<I18nContextValue>(defaultContext);
+
+  function Provider({ children, initialLanguage }: PropsWithChildren<{ initialLanguage?: LanguageCode }>) {
+    const [language, setLanguageState] = useState<LanguageCode>(() => initialLanguage ?? readStoredLanguage());
+
+    useEffect(() => {
+      storage.setString(storageKey, language);
+      if (typeof document !== 'undefined') {
+        document.documentElement.lang = localeTagForLanguage(language);
+      }
+    }, [language]);
+
+    const value = useMemo<I18nContextValue>(
+      () => ({
+        language,
+        setLanguage: setLanguageState,
+        t: (key, variables) => getMessage(language, key, variables),
+        localizeText,
+        sentenceCase: toSentenceCase,
+        localizeUiText: (text) => toSentenceCase(localizeText(text)),
+        options: supportedLanguages,
+      }),
+      [language],
+    );
+
+    return <I18nContext.Provider value={value}>{children}</I18nContext.Provider>;
+  }
+
+  function useI18n(): I18nContextValue {
+    return useContext(I18nContext);
+  }
+
+  return { Provider, useI18n, toSentenceCase };
+}
+
+export { toSentenceCase };

package/src/i18n/flattenMessages.ts

@@ -0,0 +1,17 @@
+import type { FlatMessages } from "./types";
+
+/**
+ * Aplana un árbol de mensajes anidados a claves con punto (p. ej. `common.loading`).
+ */
+export function flattenNestedMessages(obj: Record<string, unknown>, prefix = ""): FlatMessages {
+  const out: FlatMessages = {};
+  for (const [k, v] of Object.entries(obj)) {
+    const key = prefix ? `${prefix}.${k}` : k;
+    if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+      Object.assign(out, flattenNestedMessages(v as Record<string, unknown>, key));
+    } else if (typeof v === "string") {
+      out[key] = v;
+    }
+  }
+  return out;
+}

package/src/i18n/formatMessage.ts

@@ -0,0 +1,23 @@
+import type { FlatMessages, LanguageCode, TranslationVariables } from "./types";
+
+/**
+ * Soporta `{var}` y `{{var}}` (compat con plantillas tipo i18next).
+ */
+export function interpolate(template: string, variables?: TranslationVariables): string {
+  const normalized = template.replace(/\{\{(\w+)\}\}/g, "{$1}");
+  if (!variables) {
+    return normalized;
+  }
+  return normalized.replace(/\{(\w+)\}/g, (_match, key: string) => String(variables[key] ?? ""));
+}
+
+export function formatMessage(
+  messages: Record<LanguageCode, FlatMessages>,
+  language: LanguageCode,
+  defaultLanguage: LanguageCode,
+  key: string,
+  variables?: TranslationVariables,
+): string {
+  const template = messages[language]?.[key] ?? messages[defaultLanguage]?.[key] ?? key;
+  return interpolate(template, variables);
+}

package/src/i18n/index.ts

@@ -0,0 +1,5 @@
+export { createI18nProvider, mergeMessages, toSentenceCase, type I18nConfig, type I18nContextValue } from './I18nProvider';
+export { flattenNestedMessages } from './flattenMessages';
+export { formatMessage, interpolate } from './formatMessage';
+export { localeTagForLanguage } from './localeTag';
+export type { LanguageCode, FlatMessages, TranslationVariables, TranslationsByLanguage } from './types';

package/src/i18n/localeTag.ts

@@ -0,0 +1,6 @@
+import type { LanguageCode } from "./types";
+
+/** Tag BCP-47 recomendado para `toLocaleString` según idioma de UI. */
+export function localeTagForLanguage(code: LanguageCode): string {
+  return code === "es" ? "es-AR" : "en-US";
+}

package/src/i18n/sentenceCase.ts

@@ -0,0 +1,35 @@
+function hasLettersOrDigits(token: string): boolean {
+  return /[\p{L}\p{N}]/u.test(token);
+}
+
+function isUppercaseAcronym(token: string): boolean {
+  const alphanumeric = token.replace(/[^\p{L}\p{N}]/gu, '');
+  return alphanumeric.length >= 2 && /^[A-Z0-9]+$/u.test(alphanumeric);
+}
+
+function capitalizeFirstLetter(token: string): string {
+  return token.replace(/\p{L}/u, (char) => char.toLocaleUpperCase());
+}
+
+/**
+ * Convierte texto a sentence case, preservando acrónimos (API, CRUD, etc.).
+ */
+export function toSentenceCase(text: string): string {
+  let seenFirstWord = false;
+  return text
+    .split(/(\s+)/)
+    .map((token) => {
+      if (/^\s+$/u.test(token) || !hasLettersOrDigits(token)) return token;
+      if (isUppercaseAcronym(token)) {
+        seenFirstWord = true;
+        return token;
+      }
+      const normalized = token.toLocaleLowerCase();
+      if (!seenFirstWord) {
+        seenFirstWord = true;
+        return capitalizeFirstLetter(normalized);
+      }
+      return normalized;
+    })
+    .join('');
+}

package/src/i18n/types.ts

@@ -0,0 +1,4 @@
+export type LanguageCode = 'es' | 'en';
+export type TranslationVariables = Record<string, string | number>;
+export type FlatMessages = Record<string, string>;
+export type TranslationsByLanguage = Record<LanguageCode, FlatMessages>;

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./mergeRecords";
+export * from "./storage";
+export * from "./search";
+export * from "./confirm";
+export * from "./theme";
+export * from "./observability";

package/src/mergeRecords.ts

@@ -0,0 +1,20 @@
+/**
+ * Combina dos mapas por clave string: se conservan primero las entradas de `base`
+ * cuya clave no existe en `override`; luego se añaden (o reemplazan) todas las de `override`.
+ * El orden de iteración queda alineado con el merge histórico de catálogos estáticos + CRUD.
+ */
+export function mergeRecordsPreferOverride<T>(
+  base: Record<string, T>,
+  override: Record<string, T>,
+): Record<string, T> {
+  const out: Record<string, T> = {};
+  for (const key of Object.keys(base)) {
+    if (!Object.prototype.hasOwnProperty.call(override, key)) {
+      out[key] = base[key] as T;
+    }
+  }
+  for (const key of Object.keys(override)) {
+    out[key] = override[key] as T;
+  }
+  return out;
+}

package/src/observability.ts

@@ -0,0 +1,55 @@
+/**
+ * Interfaz genérica para error tracking (Sentry, Datadog, LogRocket, etc.).
+ * El producto inyecta su implementación concreta.
+ */
+export type ErrorReporter = {
+  init: () => void;
+  captureException: (error: unknown, context?: Record<string, string>) => void;
+};
+
+let reporter: ErrorReporter | null = null;
+
+/**
+ * Registra un error reporter. Llamar una sola vez al inicio de la app.
+ */
+export function registerErrorReporter(r: ErrorReporter): void {
+  reporter = r;
+  reporter.init();
+}
+
+/**
+ * Captura un error. No-op si no hay reporter registrado.
+ */
+export function captureError(error: unknown, context?: Record<string, string>): void {
+  reporter?.captureException(error, context);
+}
+
+/**
+ * Crea un error reporter para Sentry a partir de un DSN.
+ * Retorna null si el DSN está vacío (desarrollo local).
+ * El caller debe pasar el módulo @sentry/* para evitar la dependencia en core.
+ */
+export function createSentryReporter(
+  dsn: string | undefined,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- interfaz genérica compatible con cualquier SDK de error tracking
+  sentry: { init: (...args: any[]) => any; captureException: (...args: any[]) => any },
+  environment: string,
+): ErrorReporter | null {
+  if (!dsn) return null;
+  return {
+    init: () =>
+      sentry.init({
+        dsn,
+        environment,
+        tracesSampleRate: 0,
+        beforeSend: (event: unknown) => {
+          const e = event as { exception?: { values?: Array<{ value?: string }> } };
+          const message = e?.exception?.values?.[0]?.value ?? '';
+          if (message.includes('401') || message.includes('NetworkError')) return null;
+          return event;
+        },
+      }),
+    captureException: (error, context) =>
+      sentry.captureException(error, context ? { tags: context } : undefined),
+  };
+}

package/src/search/PageSearchProvider.tsx

@@ -0,0 +1,78 @@
+/* eslint-disable react-refresh/only-export-components -- hooks acoplados al Context del mismo archivo */
+import { createContext, useCallback, useContext, useEffect, useRef, useState, type PropsWithChildren } from 'react';
+
+type PageSearchContextValue = {
+  query: string;
+  setQuery: (value: string) => void;
+  register: () => () => void;
+  visible: boolean;
+  placeholder: string;
+};
+
+const PageSearchContext = createContext<PageSearchContextValue>({
+  query: '',
+  setQuery: () => {},
+  register: () => () => {},
+  visible: false,
+  placeholder: 'Search...',
+});
+
+const PageSearchShellContext = createContext(false);
+
+/**
+ * Hook que registra la página como consumidora del search y devuelve el query.
+ * Al desmontar, des-registra y el input desaparece.
+ */
+export function usePageSearch(): string {
+  const { query, register } = useContext(PageSearchContext);
+  useEffect(() => register(), [register]);
+  return query;
+}
+
+/**
+ * Hook para el Shell: controla visibilidad y query del search input.
+ */
+export function usePageSearchShellControl() {
+  const { query, setQuery, visible, placeholder } = useContext(PageSearchContext);
+  return {
+    query,
+    visible,
+    placeholder,
+    setQuery,
+    clear: () => setQuery(''),
+  };
+}
+
+/**
+ * Provider del buscador de página. Se monta una vez en el Shell.
+ * Las páginas se registran con usePageSearch() — cuando hay al menos una registrada, el input es visible.
+ */
+export function PageSearchProvider({
+  children,
+  placeholder = 'Search...',
+}: PropsWithChildren<{ placeholder?: string }>) {
+  const [query, setQuery] = useState('');
+  const countRef = useRef(0);
+  const [visible, setVisible] = useState(false);
+
+  const register = useCallback(() => {
+    countRef.current += 1;
+    setVisible(true);
+    return () => {
+      countRef.current -= 1;
+      if (countRef.current <= 0) {
+        countRef.current = 0;
+        setVisible(false);
+        setQuery('');
+      }
+    };
+  }, []);
+
+  return (
+    <PageSearchShellContext.Provider value>
+      <PageSearchContext.Provider value={{ query, setQuery, register, visible, placeholder }}>
+        {children}
+      </PageSearchContext.Provider>
+    </PageSearchShellContext.Provider>
+  );
+}

package/src/search/SearchInput.tsx

@@ -0,0 +1,55 @@
+import type { ChangeEventHandler } from "react";
+
+export type SearchInputProps = {
+  value: string;
+  onChange: (value: string) => void;
+  placeholder: string;
+  ariaLabel?: string;
+  autoComplete?: string;
+  rootClassName?: string;
+  inputClassName?: string;
+  clearLabel?: string;
+};
+
+/**
+ * Input canónico de búsqueda para consola.
+ * La app host aporta el CSS del tema sobre las clases `page-search*`.
+ */
+export function SearchInput({
+  value,
+  onChange,
+  placeholder,
+  ariaLabel,
+  autoComplete = "off",
+  rootClassName,
+  inputClassName,
+  clearLabel = "Limpiar búsqueda",
+}: SearchInputProps) {
+  const handleChange: ChangeEventHandler<HTMLInputElement> = (event) => {
+    onChange(event.target.value);
+  };
+
+  return (
+    <div className={["page-search", rootClassName].filter(Boolean).join(" ").trim()}>
+      <input
+        type="search"
+        className={["page-search__input", inputClassName].filter(Boolean).join(" ").trim()}
+        placeholder={placeholder}
+        autoComplete={autoComplete}
+        value={value}
+        onChange={handleChange}
+        aria-label={ariaLabel ?? placeholder}
+      />
+      {value.length > 0 ? (
+        <button
+          className="page-search__clear"
+          onClick={() => onChange("")}
+          aria-label={clearLabel}
+          type="button"
+        >
+          ×
+        </button>
+      ) : null}
+    </div>
+  );
+}

package/src/search/index.ts

@@ -0,0 +1,5 @@
+export { normalize } from "./normalize";
+export { trigrams, similarity } from "./trigram";
+export { search, type SearchEntry, type SearchResult, type SearchOptions } from "./search";
+export { SearchInput, type SearchInputProps } from "./SearchInput";
+export { PageSearchProvider, usePageSearch, usePageSearchShellControl } from "./PageSearchProvider";

package/src/search/normalize.ts

@@ -0,0 +1,8 @@
+/** Normaliza texto: minúsculas, sin acentos, trim. */
+export function normalize(text: string): string {
+  return text
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .trim();
+}

package/src/search/search.ts

@@ -0,0 +1,85 @@
+/**
+ * Función principal de búsqueda fuzzy client-side.
+ *
+ * Combina word-level prefix/substring match + trigram similarity
+ * para dar resultados relevantes con tolerancia a typos y acentos.
+ */
+
+import { normalize } from "./normalize";
+import { similarity } from "./trigram";
+
+export type SearchEntry<T> = {
+  item: T;
+  text: string;
+};
+
+export type SearchResult<T> = {
+  item: T;
+  score: number;
+};
+
+export type SearchOptions = {
+  /** Umbral mínimo para resultados trigram-only (sin prefix/substring). Default: 0.55 */
+  trigramThreshold?: number;
+  /** Máximo resultados devueltos. Default: sin límite. */
+  limit?: number;
+};
+
+const DEFAULT_TRIGRAM_THRESHOLD = 0.55;
+const PREFIX_BOOST = 0.5;
+const SUBSTRING_BOOST = 0.35;
+
+/**
+ * Busca entries por similitud con el query.
+ *
+ * Estrategia de scoring (por entry):
+ * 1. Si alguna palabra del texto empieza con el query → baseSim + 0.5
+ * 2. Si el query es substring del texto → baseSim + 0.35
+ * 3. Solo trigramas → requiere similitud ≥ trigramThreshold (default 0.55)
+ *
+ * baseSim = max(similitud vs texto completo, mejor similitud vs palabra individual)
+ *
+ * Resultados ordenados por score descendente.
+ */
+export function search<T>(
+  query: string,
+  entries: SearchEntry<T>[],
+  options?: SearchOptions,
+): SearchResult<T>[] {
+  const q = normalize(query);
+  if (q.length === 0) return [];
+
+  const threshold = options?.trigramThreshold ?? DEFAULT_TRIGRAM_THRESHOLD;
+  const results: SearchResult<T>[] = [];
+
+  for (const entry of entries) {
+    const norm = normalize(entry.text);
+    const words = norm.split(/\s+/).filter(Boolean);
+
+    const hasSubstring = norm.includes(q);
+    const hasWordPrefix = words.some((w) => w.startsWith(q));
+
+    let bestWordSim = 0;
+    for (const w of words) {
+      const s = similarity(q, w);
+      if (s > bestWordSim) bestWordSim = s;
+    }
+
+    const fullSim = similarity(query, entry.text);
+    const baseSim = Math.max(fullSim, bestWordSim);
+
+    if (hasWordPrefix || hasSubstring) {
+      const boost = hasWordPrefix ? PREFIX_BOOST : SUBSTRING_BOOST;
+      results.push({ item: entry.item, score: Math.min(1, baseSim + boost) });
+    } else if (baseSim >= threshold) {
+      results.push({ item: entry.item, score: baseSim });
+    }
+  }
+
+  results.sort((a, b) => b.score - a.score);
+
+  if (options?.limit && results.length > options.limit) {
+    return results.slice(0, options.limit);
+  }
+  return results;
+}

package/src/search/trigram.ts

@@ -0,0 +1,31 @@
+/**
+ * Generación de trigramas y similitud (Dice coefficient).
+ *
+ * Funciones puras — no tienen conocimiento de UI ni de búsqueda.
+ */
+
+import { normalize } from "./normalize";
+
+/** Extrae trigramas de un string (normalizado internamente). */
+export function trigrams(text: string): Set<string> {
+  const norm = normalize(text);
+  const padded = `  ${norm} `;
+  const result = new Set<string>();
+  for (let i = 0; i <= padded.length - 3; i++) {
+    result.add(padded.slice(i, i + 3));
+  }
+  return result;
+}
+
+/** Coeficiente de Dice: 2 * |A ∩ B| / (|A| + |B|). Rango [0, 1]. */
+export function similarity(a: string, b: string): number {
+  const ta = trigrams(a);
+  const tb = trigrams(b);
+  if (ta.size === 0 && tb.size === 0) return 1;
+  if (ta.size === 0 || tb.size === 0) return 0;
+  let intersection = 0;
+  for (const t of ta) {
+    if (tb.has(t)) intersection++;
+  }
+  return (2 * intersection) / (ta.size + tb.size);
+}

package/src/storage.ts

@@ -0,0 +1,110 @@
+export interface BrowserStorageNamespaceOptions {
+  namespace: string;
+  storage?: Storage;
+  hostAware?: boolean;
+  legacyKeys?: string[];
+}
+
+export interface BrowserStorageNamespace {
+  key(name: string): string;
+  getString(name: string): string | null;
+  setString(name: string, value: string): void;
+  remove(name: string): void;
+  getJSON<T>(name: string): T | null;
+  setJSON(name: string, value: unknown | null | undefined): void;
+  clear(): void;
+}
+
+function resolveStorage(custom?: Storage): Storage | null {
+  if (custom) {
+    return custom;
+  }
+  if (typeof window === "undefined") {
+    return null;
+  }
+  return window.localStorage;
+}
+
+function resolvePrefix(namespace: string, hostAware: boolean): string {
+  const cleanNamespace = namespace.trim();
+  if (!hostAware || typeof window === "undefined") {
+    return `${cleanNamespace}:`;
+  }
+  return `${cleanNamespace}:${window.location.host}:`;
+}
+
+export function createBrowserStorageNamespace(
+  options: BrowserStorageNamespaceOptions,
+): BrowserStorageNamespace {
+  const storage = resolveStorage(options.storage);
+  const hostAware = options.hostAware ?? true;
+  const legacyKeys = options.legacyKeys ?? [];
+
+  function prefix(): string {
+    return resolvePrefix(options.namespace, hostAware);
+  }
+
+  function key(name: string): string {
+    return `${prefix()}${name}`;
+  }
+
+  function getString(name: string): string | null {
+    return storage?.getItem(key(name)) ?? null;
+  }
+
+  function setString(name: string, value: string): void {
+    storage?.setItem(key(name), value);
+  }
+
+  function remove(name: string): void {
+    storage?.removeItem(key(name));
+  }
+
+  function getJSON<T>(name: string): T | null {
+    const raw = getString(name);
+    if (!raw) {
+      return null;
+    }
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      return null;
+    }
+  }
+
+  function setJSON(name: string, value: unknown | null | undefined): void {
+    if (value === null || value === undefined) {
+      remove(name);
+      return;
+    }
+    setString(name, JSON.stringify(value));
+  }
+
+  function clear(): void {
+    if (!storage) {
+      return;
+    }
+
+    legacyKeys.forEach((legacyKey) => storage.removeItem(legacyKey));
+
+    const prefixValue = prefix();
+    const toRemove: string[] = [];
+    for (let index = 0; index < storage.length; index += 1) {
+      const itemKey = storage.key(index);
+      if (itemKey && itemKey.startsWith(prefixValue)) {
+        toRemove.push(itemKey);
+      }
+    }
+    toRemove.forEach((itemKey) => storage.removeItem(itemKey));
+  }
+
+  return {
+    key,
+    getString,
+    setString,
+    remove,
+    getJSON,
+    setJSON,
+    clear,
+  };
+}

package/src/theme.ts

@@ -0,0 +1,51 @@
+import { createBrowserStorageNamespace } from './storage';
+
+export type Theme = 'light' | 'dark';
+
+export type ThemeConfig = {
+  /** Namespace para el storage (e.g. 'pymes-ui') */
+  namespace: string;
+  /** Key dentro del namespace (e.g. 'app:theme') */
+  storageKey?: string;
+  /** Atributo HTML donde se aplica el tema (default: 'data-theme') */
+  attribute?: string;
+};
+
+export type ThemeManager = {
+  get: () => Theme;
+  toggle: () => Theme;
+  apply: (theme?: Theme) => void;
+};
+
+/**
+ * Crea un theme manager con storage persistente y detección de preferencia del sistema.
+ */
+export function createThemeManager(config: ThemeConfig): ThemeManager {
+  const storageKey = config.storageKey ?? 'theme';
+  const attribute = config.attribute ?? 'data-theme';
+  const storage = createBrowserStorageNamespace({ namespace: config.namespace, hostAware: false });
+
+  function get(): Theme {
+    const stored = storage.getString(storageKey);
+    if (stored === 'dark' || stored === 'light') return stored;
+    return typeof window !== 'undefined' && window.matchMedia('(prefers-color-scheme: dark)').matches
+      ? 'dark'
+      : 'light';
+  }
+
+  function apply(theme?: Theme): void {
+    const t = theme ?? get();
+    if (typeof document !== 'undefined') {
+      document.documentElement.setAttribute(attribute, t);
+    }
+  }
+
+  function toggle(): Theme {
+    const next = get() === 'dark' ? 'light' : 'dark';
+    storage.setString(storageKey, next);
+    apply(next);
+    return next;
+  }
+
+  return { get, toggle, apply };
+}