@steveencues/starter-react-ui 0.0.0-stage → 1.0.1

package/dist/libs/domain/interface/theme.interface.d.ts

@@ -0,0 +1,204 @@
+import { ThemeName } from '..';
+import { ReactNode } from 'react';
+/**
+ * @description Contrato publico del contexto de temas.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface IThemeContextValue {
+    readonly theme: AppTheme;
+    readonly themeName: ThemeName;
+    readonly themes: readonly AppTheme[];
+    readonly setTheme: (theme: ThemeName) => void;
+}
+/**
+ * @description Propiedades del proveedor de temas.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface IThemeProviderProps {
+    readonly themes: readonly AppTheme[];
+    readonly initialTheme: ThemeName;
+    readonly themeEncryptionKey: string;
+    readonly children: ReactNode;
+}
+/**
+ * @description Colores del contenido textual.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface ThemeTextColors {
+    readonly primary: string;
+    readonly secondary: string;
+    readonly muted: string;
+    readonly disabled: string;
+    readonly inverse: string;
+    readonly link: string;
+    readonly linkHover: string;
+}
+/**
+ * @description Colores utilizados por las superficies.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface ThemeSurfaceColors {
+    readonly background: string;
+    readonly surface: string;
+    readonly surfaceElevated: string;
+    readonly surfaceHover: string;
+    readonly surfaceActive: string;
+    readonly surfaceDisabled: string;
+}
+/**
+ * @description Colores de los estados semanticos.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface ThemeStateColors {
+    readonly success: string;
+    readonly successBackground: string;
+    readonly warning: string;
+    readonly warningBackground: string;
+    readonly error: string;
+    readonly errorBackground: string;
+    readonly info: string;
+    readonly infoBackground: string;
+}
+/**
+ * @description Colores de identidad visual de la aplicacion.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface ThemeBrandColors {
+    readonly primary: string;
+    readonly primaryHover: string;
+    readonly primaryActive: string;
+    readonly primaryContrast: string;
+    readonly secondary: string;
+    readonly secondaryHover: string;
+    readonly secondaryActive: string;
+    readonly secondaryContrast: string;
+    readonly accent: string;
+    readonly accentHover: string;
+    readonly accentContrast: string;
+}
+/**
+ * @description Colores para bordes e indicadores de interaccion.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface ThemeBorderColors {
+    readonly default: string;
+    readonly subtle: string;
+    readonly strong: string;
+    readonly focus: string;
+    readonly hover: string;
+    readonly active: string;
+    readonly disabled: string;
+}
+/**
+ * @description Configuracion de las sombras.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface ThemeShadowColors {
+    readonly color: string;
+    readonly subtle: string;
+    readonly small: string;
+    readonly medium: string;
+    readonly large: string;
+    readonly glow: string;
+}
+/**
+ * @description Configuracion de efectos visuales.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface ThemeEffects {
+    readonly overlay: string;
+    readonly backdrop: string;
+    readonly blur: string;
+    readonly blurStrong: string;
+    readonly glassBackground: string;
+    readonly glassBorder: string;
+}
+/**
+ * @description Configuracion tipografica del tema.
+ * Sus valores pueden representar colores o tokens CSS.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface ThemeTypography {
+    readonly heading: {
+        readonly primary: string;
+        readonly secondary: string;
+        readonly muted: string;
+    };
+    readonly body: {
+        readonly primary: string;
+        readonly secondary: string;
+        readonly muted: string;
+    };
+    readonly label: {
+        readonly primary: string;
+        readonly secondary: string;
+        readonly muted: string;
+    };
+    readonly button: {
+        readonly primary: string;
+        readonly secondary: string;
+    };
+}
+/**
+ * @description Paleta completa de tokens visuales del tema.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface ThemeColors {
+    readonly surface: ThemeSurfaceColors;
+    readonly text: ThemeTextColors;
+    readonly brand: ThemeBrandColors;
+    readonly state: ThemeStateColors;
+    readonly border: ThemeBorderColors;
+    readonly shadow: ThemeShadowColors;
+    readonly effects: ThemeEffects;
+    readonly typography: ThemeTypography;
+}
+/**
+ * @description Configuracion visual completa de un tema.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface AppTheme {
+    readonly name: ThemeName;
+    readonly colors: ThemeColors;
+}
+/**
+ * @description Defines the configuration required to manage theme preferences.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface ThemePreferenceConfiguration {
+    readonly themes: IThemeProviderProps["themes"];
+    readonly initialTheme: IThemeProviderProps["initialTheme"];
+    readonly themeEncryptionKey: IThemeProviderProps["themeEncryptionKey"];
+}
+/**
+ * @description Represents the current theme preference state and its configuration.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface ThemePreferenceState extends ThemePreferenceConfiguration {
+    readonly themeName: ThemeName;
+    readonly isLoaded: boolean;
+}
+/**
+ * @description Defines the result returned by the theme preference hook.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface ThemePreferenceResult {
+    readonly themeName: ThemeName;
+    readonly isPreferenceLoaded: boolean;
+    readonly setThemeName: (nextTheme: ThemeName) => void;
+}

package/dist/libs/domain/interface/translation.interface.d.ts

@@ -0,0 +1,56 @@
+import { TranslationCatalog, TranslationParams } from '../..';
+import { ReactNode } from 'react';
+/**
+ * @description Estado publico del contexto de traducciones.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface ILanguageContextValue {
+    readonly language: string;
+    readonly languages: readonly string[];
+    readonly setLanguage: (language: string) => void;
+    readonly t: (key: string, params?: TranslationParams) => string;
+}
+/**
+ * @description Propiedades del proveedor de traducciones.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface ITranslateProviderProps {
+    readonly translations: TranslationCatalog;
+    readonly initialLanguage: string;
+    readonly fallbackLanguage?: string;
+    readonly children: ReactNode;
+    readonly languageEncryptionKey: string;
+}
+/**
+ * @description Defines the configuration required to manage language preferences.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface LanguagePreferenceConfiguration {
+    readonly translations: ITranslateProviderProps["translations"];
+    readonly initialLanguage: ITranslateProviderProps["initialLanguage"];
+    readonly fallbackLanguage: string;
+    readonly languageEncryptionKey: ITranslateProviderProps["languageEncryptionKey"];
+    readonly languages: readonly string[];
+}
+/**
+ * @description Represents the current language preference state and configuration.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface LanguagePreferenceState extends LanguagePreferenceConfiguration {
+    readonly selectedLanguage: string;
+    readonly isLoaded: boolean;
+}
+/**
+ * @description Defines the result returned by the language preference hook.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface LanguagePreferenceResult {
+    readonly language: string;
+    readonly isLoaded: boolean;
+    readonly setLanguage: (language: string) => void;
+}

package/dist/libs/domain/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './translation.types';
+export * from './theme.types';
+export * from './theme-name.types';

package/dist/libs/domain/types/theme-name.types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @description Identificadores de los temas disponibles.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export type ThemeName = "light" | "dark" | "magenta" | "semi-dark";

package/dist/libs/domain/types/theme.types.d.ts

@@ -0,0 +1,64 @@
+import { ThemePreferenceState } from '..';
+import { CSSProperties, Dispatch, SetStateAction } from 'react';
+/**
+ * @description Defines custom CSS variables supported by the library.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export type ThemeCssVariables = CSSProperties & {
+    [property: `--rui-${string}`]: string;
+};
+/**
+ * @description Defines CSS variables for surface colors.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export type SurfaceVariables = Pick<ThemeCssVariables, "--rui-surface-background" | "--rui-surface-surface" | "--rui-surface-surface-elevated" | "--rui-surface-surface-hover" | "--rui-surface-surface-active" | "--rui-surface-surface-disabled">;
+/**
+ * @description Defines CSS variables for text colors.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export type TextVariables = Pick<ThemeCssVariables, "--rui-text-primary" | "--rui-text-secondary" | "--rui-text-muted" | "--rui-text-disabled" | "--rui-text-inverse" | "--rui-text-link" | "--rui-text-link-hover">;
+/**
+ * @description Defines CSS variables for brand colors.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export type BrandVariables = Pick<ThemeCssVariables, "--rui-brand-primary" | "--rui-brand-primary-hover" | "--rui-brand-primary-active" | "--rui-brand-primary-contrast" | "--rui-brand-secondary" | "--rui-brand-secondary-hover" | "--rui-brand-secondary-active" | "--rui-brand-secondary-contrast" | "--rui-brand-accent" | "--rui-brand-accent-hover" | "--rui-brand-accent-contrast">;
+/**
+ * @description Defines CSS variables for status colors.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export type StateVariables = Pick<ThemeCssVariables, "--rui-state-success" | "--rui-state-success-background" | "--rui-state-warning" | "--rui-state-warning-background" | "--rui-state-error" | "--rui-state-error-background" | "--rui-state-info" | "--rui-state-info-background">;
+/**
+ * @description Defines CSS variables for border styles and colors.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export type BorderVariables = Pick<ThemeCssVariables, "--rui-border-default" | "--rui-border-subtle" | "--rui-border-strong" | "--rui-border-focus" | "--rui-border-hover" | "--rui-border-active" | "--rui-border-disabled">;
+/**
+ * @description Defines CSS variables for shadows.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export type ShadowVariables = Pick<ThemeCssVariables, "--rui-shadow-color" | "--rui-shadow-subtle" | "--rui-shadow-small" | "--rui-shadow-medium" | "--rui-shadow-large" | "--rui-shadow-glow">;
+/**
+ * @description Defines CSS variables for visual effects.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export type EffectVariables = Pick<ThemeCssVariables, "--rui-effects-overlay" | "--rui-effects-backdrop" | "--rui-effects-blur" | "--rui-effects-blur-strong" | "--rui-effects-glass-background" | "--rui-effects-glass-border">;
+/**
+ * @description Defines CSS variables for typography colors.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export type TypographyVariables = Pick<ThemeCssVariables, "--rui-typography-heading-primary" | "--rui-typography-heading-secondary" | "--rui-typography-heading-muted" | "--rui-typography-body-primary" | "--rui-typography-body-secondary" | "--rui-typography-body-muted" | "--rui-typography-label-primary" | "--rui-typography-label-secondary" | "--rui-typography-label-muted" | "--rui-typography-button-primary" | "--rui-typography-button-secondary">;
+/**
+ * @description Defines the React state dispatcher for theme preference updates.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export type SetThemePreferenceState = Dispatch<SetStateAction<ThemePreferenceState>>;

package/dist/libs/domain/types/translation.types.d.ts

@@ -0,0 +1,33 @@
+import { LanguagePreferenceState } from '..';
+/**
+ * @description Valores admitidos en un catalogo de traducciones.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export type TranslationValue = string | TranslationDictionary;
+/**
+ * @description Diccionario de traducciones que admite claves anidadas.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export interface TranslationDictionary {
+    readonly [key: string]: TranslationValue;
+}
+/**
+ * @description Catalogo de traducciones identificado por idioma.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export type TranslationCatalog = Readonly<Record<string, TranslationDictionary>>;
+/**
+ * @description Parametros para interpolar variables en una traduccion.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export type TranslationParams = Readonly<Record<string, string | number>>;
+/**
+ * @description Defines the React state dispatcher for language preference updates.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export type SetLanguagePreferenceState = React.Dispatch<React.SetStateAction<LanguagePreferenceState>>;

package/dist/libs/index.d.ts

@@ -0,0 +1,4 @@
+export * from './aplicacion';
+export * from './components';
+export * from './domain';
+export * from './infraestructura';

package/dist/libs/infraestructura/index.d.ts

@@ -0,0 +1 @@
+export * from './storage';

package/dist/libs/infraestructura/storage/encrypted-preference.storage.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @description Encrypts and saves a preference in localStorage.
+ * @param storageKey Storage key.
+ * @param value Value to store.
+ * @param encryptionKey Encryption secret.
+ * @returns Promise resolved after the save attempt.
+ * @author Steveen Cues
+ * @version 3.0.0
+ */
+export declare function saveEncryptedPreference(storageKey: string, value: string, encryptionKey: string): Promise<void>;
+/**
+ * @description Loads and decrypts a preference from localStorage.
+ * @param storageKey Storage key.
+ * @param encryptionKey Encryption secret.
+ * @returns Decrypted preference or undefined when unavailable.
+ * @author Steveen Cues
+ * @version 3.0.0
+ */
+export declare function loadEncryptedPreference(storageKey: string, encryptionKey: string): Promise<string | undefined>;

package/dist/libs/infraestructura/storage/index.d.ts

@@ -0,0 +1,3 @@
+export * from './encrypted-preference.storage';
+export * from './language-preference.storage';
+export * from './theme-preference.storage';

package/dist/libs/infraestructura/storage/language-preference.storage.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @description Guarda el idioma activo de forma cifrada.
+ * @param language Codigo del idioma activo.
+ * @param encryptionKey Clave de cifrado proporcionada por el consumidor.
+ * @returns Promesa completada al finalizar el intento de guardado.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export declare function saveLanguagePreference(language: string, encryptionKey: string): Promise<void>;
+/**
+ * @description Recupera el idioma guardado y verifica que siga disponible.
+ * @param availableLanguages Idiomas admitidos por el proyecto.
+ * @param encryptionKey Clave de cifrado proporcionada por el consumidor.
+ * @returns Idioma recuperado o undefined si no existe o no es valido.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export declare function loadLanguagePreference(availableLanguages: readonly string[], encryptionKey: string): Promise<string | undefined>;

package/dist/libs/infraestructura/storage/theme-preference.storage.d.ts

@@ -0,0 +1,19 @@
+import { AppTheme, ThemeName } from '../../domain';
+/**
+ * @description Guarda el nombre del tema activo de forma cifrada.
+ * @param themeName Nombre del tema.
+ * @param encryptionKey Clave de cifrado proporcionada por el consumidor.
+ * @returns Promesa completada al finalizar el intento de guardado.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export declare function saveThemePreference(themeName: ThemeName, encryptionKey: string): Promise<void>;
+/**
+ * @description Recupera el tema guardado si existe entre los temas admitidos.
+ * @param themes Temas definidos por el proyecto consumidor.
+ * @param encryptionKey Clave de cifrado proporcionada por el consumidor.
+ * @returns Nombre del tema recuperado o undefined.
+ * @author Steveen Cues
+ * @version 1.0.0
+ */
+export declare function loadThemePreference(themes: readonly AppTheme[], encryptionKey: string): Promise<ThemeName | undefined>;

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@steveencues/starter-react-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.1",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "build:lib": "tsc -b && vite build",
+    "package:lib": "npm run format && npm run lint && node scripts/package-library.mjs",
+    "build": "npm run lint && npm run format:check && npm run build:lib && npm run package:lib",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.2.4",
+    "@commitlint/config-conventional": "^21.2.4",
+    "@eslint/js": "^10.0.1",
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "eslint": "^10.10.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jsdoc": "^65.3.8",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.6",
+    "eslint-plugin-unicorn": "^78.0.0",
+    "globals": "^17.12.0",
+    "husky": "^9.1.7",
+    "prettier": "^3.9.10",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "tailwindcss": "^4.3.3",
+    "typescript": "~6.0.2",
+    "typescript-eslint": "^8.69.0",
+    "unplugin-dts": "^1.1.2",
+    "vite": "^8.3.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  }
 }