@allternit/gizzi-code 1.0.0 → 1.0.1

package/src/runtime/brand/brand.ts

@@ -1,667 +0,0 @@
-/**
- * @fileoverview Branding utilities and configuration for gizzi-code
- * @module runtime/brand/brand
- *
- * Provides centralized brand constants, color schemes, and theming
- * configuration for the gizzi-code runtime environment.
- */
-
-/**
- * Brand name constants
- * @constant {Readonly<{FULL: string; SHORT: string; CODE: string; PACKAGE: string}>}
- */
-export const Brand = {
-  /** Full brand name */
-  FULL: 'gizzi-code',
-
-  /** Short brand name */
-  SHORT: 'gizzi',
-
-  /** Code identifier */
-  CODE: 'gizzi-code',
-
-  /** Package name */
-  PACKAGE: '@gizzi/code',
-} as const;
-
-/**
- * Brand version information
- * @constant {Readonly<{MAJOR: number; MINOR: number; PATCH: number; STRING: string}>}
- */
-export const BrandVersion = {
-  /** Major version */
-  MAJOR: 0,
-
-  /** Minor version */
-  MINOR: 1,
-
-  /** Patch version */
-  PATCH: 0,
-
-  /** Full version string */
-  STRING: '0.1.0',
-} as const;
-
-/**
- * Color hex value type
- * @typedef {`#${string}`} HexColor
- */
-export type HexColor = `#${string}`;
-
-/**
- * RGB color values
- * @interface RGBColor
- */
-export interface RGBColor {
-  readonly r: number;
-  readonly g: number;
-  readonly b: number;
-}
-
-/**
- * RGBA color values with alpha
- * @interface RGBAColor
- */
-export interface RGBAColor extends RGBColor {
-  readonly a: number;
-}
-
-/**
- * Complete color palette for a theme variant
- * @interface BrandColorPalette
- */
-export interface BrandColorPalette {
-  /** Primary brand color */
-  readonly primary: HexColor;
-
-  /** Secondary brand color */
-  readonly secondary: HexColor;
-
-  /** Accent color for highlights */
-  readonly accent: HexColor;
-
-  /** Background color */
-  readonly background: HexColor;
-
-  /** Surface color for cards/elevated elements */
-  readonly surface: HexColor;
-
-  /** Primary text color */
-  readonly text: HexColor;
-
-  /** Secondary/muted text color */
-  readonly textMuted: HexColor;
-
-  /** Error color */
-  readonly error: HexColor;
-
-  /** Warning color */
-  readonly warning: HexColor;
-
-  /** Success color */
-  readonly success: HexColor;
-
-  /** Info color */
-  readonly info: HexColor;
-
-  /** Border color */
-  readonly border: HexColor;
-
-  /** Divider color */
-  readonly divider: HexColor;
-}
-
-/**
- * Complete brand color scheme with all theme variants
- * @interface BrandColorScheme
- */
-export interface BrandColorScheme {
-  /** Light theme colors */
-  readonly light: BrandColorPalette;
-
-  /** Dark theme colors */
-  readonly dark: BrandColorPalette;
-
-  /** High contrast theme colors */
-  readonly highContrast: BrandColorPalette;
-}
-
-/**
- * Theme mode options
- * @typedef {'light' | 'dark' | 'high-contrast' | 'auto'} ThemeMode
- */
-export type ThemeMode = 'light' | 'dark' | 'high-contrast' | 'auto';
-
-/**
- * Default light theme color palette
- * @constant {Readonly<BrandColorPalette>}
- */
-export const LightColors: BrandColorPalette = {
-  primary: '#2563eb',
-  secondary: '#64748b',
-  accent: '#8b5cf6',
-  background: '#ffffff',
-  surface: '#f8fafc',
-  text: '#0f172a',
-  textMuted: '#64748b',
-  error: '#ef4444',
-  warning: '#f59e0b',
-  success: '#10b981',
-  info: '#3b82f6',
-  border: '#e2e8f0',
-  divider: '#cbd5e1',
-} as const;
-
-/**
- * Default dark theme color palette
- * @constant {Readonly<BrandColorPalette>}
- */
-export const DarkColors: BrandColorPalette = {
-  primary: '#3b82f6',
-  secondary: '#94a3b8',
-  accent: '#a78bfa',
-  background: '#0f172a',
-  surface: '#1e293b',
-  text: '#f8fafc',
-  textMuted: '#94a3b8',
-  error: '#f87171',
-  warning: '#fbbf24',
-  success: '#34d399',
-  info: '#60a5fa',
-  border: '#334155',
-  divider: '#475569',
-} as const;
-
-/**
- * High contrast theme for accessibility
- * @constant {Readonly<BrandColorPalette>}
- */
-export const HighContrastColors: BrandColorPalette = {
-  primary: '#005fcc',
-  secondary: '#404040',
-  accent: '#6622cc',
-  background: '#000000',
-  surface: '#0a0a0a',
-  text: '#ffffff',
-  textMuted: '#cccccc',
-  error: '#ff3333',
-  warning: '#ffaa00',
-  success: '#00cc66',
-  info: '#0099ff',
-  border: '#666666',
-  divider: '#555555',
-} as const;
-
-/**
- * Complete brand color scheme
- * @constant {Readonly<BrandColorScheme>}
- */
-export const BrandColors: BrandColorScheme = {
-  light: LightColors,
-  dark: DarkColors,
-  highContrast: HighContrastColors,
-} as const;
-
-/**
- * Brand typography configuration
- * @interface BrandTypography
- */
-export interface BrandTypography {
-  /** Font family stack */
-  readonly fontFamily: string;
-
-  /** Monospace font family for code */
-  readonly fontFamilyMono: string;
-
-  /** Base font size in pixels */
-  readonly baseSize: number;
-
-  /** Line height ratio */
-  readonly lineHeight: number;
-
-  /** Font weights */
-  readonly weights: {
-    readonly normal: number;
-    readonly medium: number;
-    readonly semibold: number;
-    readonly bold: number;
-  };
-
-  /** Type scale sizes */
-  readonly scale: {
-    readonly xs: number;
-    readonly sm: number;
-    readonly base: number;
-    readonly lg: number;
-    readonly xl: number;
-    readonly '2xl': number;
-    readonly '3xl': number;
-    readonly '4xl': number;
-  };
-}
-
-/**
- * Default brand typography
- * @constant {Readonly<BrandTypography>}
- */
-export const BrandTypography: BrandTypography = {
-  fontFamily:
-    '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
-  fontFamilyMono:
-    'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace',
-  baseSize: 16,
-  lineHeight: 1.5,
-  weights: {
-    normal: 400,
-    medium: 500,
-    semibold: 600,
-    bold: 700,
-  },
-  scale: {
-    xs: 0.75,    // 12px
-    sm: 0.875,   // 14px
-    base: 1,     // 16px
-    lg: 1.125,   // 18px
-    xl: 1.25,    // 20px
-    '2xl': 1.5,  // 24px
-    '3xl': 1.875,// 30px
-    '4xl': 2.25, // 36px
-  },
-} as const;
-
-/**
- * Brand spacing configuration (in rem units base)
- * @constant {Readonly<Record<string, number>>}
- */
-export const BrandSpacing = {
-  none: 0,
-  xs: 0.25,    // 4px
-  sm: 0.5,     // 8px
-  md: 1,       // 16px
-  lg: 1.5,     // 24px
-  xl: 2,       // 32px
-  '2xl': 3,    // 48px
-  '3xl': 4,    // 64px
-  '4xl': 6,    // 96px
-  '5xl': 8,    // 128px
-} as const;
-
-/**
- * Brand border radius values
- * @constant {Readonly<Record<string, string>>}
- */
-export const BrandBorderRadius = {
-  none: '0',
-  sm: '0.125rem',   // 2px
-  md: '0.25rem',    // 4px
-  lg: '0.5rem',     // 8px
-  xl: '0.75rem',    // 12px
-  '2xl': '1rem',    // 16px
-  full: '9999px',
-} as const;
-
-/**
- * Brand shadow values
- * @constant {Readonly<Record<string, string>>}
- */
-export const BrandShadows = {
-  none: 'none',
-  sm: '0 1px 2px 0 rgb(0 0 0 / 0.05)',
-  md: '0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)',
-  lg: '0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)',
-  xl: '0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)',
-  '2xl': '0 25px 50px -12px rgb(0 0 0 / 0.25)',
-  inner: 'inset 0 2px 4px 0 rgb(0 0 0 / 0.05)',
-} as const;
-
-/**
- * Brand breakpoints for responsive design
- * @constant {Readonly<Record<string, number>>}
- */
-export const BrandBreakpoints = {
-  xs: 0,
-  sm: 640,
-  md: 768,
-  lg: 1024,
-  xl: 1280,
-  '2xl': 1536,
-} as const;
-
-/**
- * Animation timing values
- * @constant {Readonly<Record<string, number>>}
- */
-export const BrandAnimation = {
-  instant: 0,
-  fast: 100,
-  normal: 200,
-  slow: 300,
-  slower: 500,
-} as const;
-
-/**
- * Easing functions
- * @constant {Readonly<Record<string, string>>}
- */
-export const BrandEasing = {
-  linear: 'linear',
-  ease: 'ease',
-  easeIn: 'ease-in',
-  easeOut: 'ease-out',
-  easeInOut: 'ease-in-out',
-  spring: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
-} as const;
-
-/**
- * Complete brand configuration object
- * @interface BrandConfig
- */
-export interface BrandConfig {
-  readonly name: typeof Brand;
-  readonly version: typeof BrandVersion;
-  readonly colors: BrandColorScheme;
-  readonly typography: BrandTypography;
-  readonly spacing: typeof BrandSpacing;
-  readonly borderRadius: typeof BrandBorderRadius;
-  readonly shadows: typeof BrandShadows;
-  readonly breakpoints: typeof BrandBreakpoints;
-  readonly animation: typeof BrandAnimation;
-  readonly easing: typeof BrandEasing;
-}
-
-/**
- * Complete brand configuration
- * @constant {Readonly<BrandConfig>}
- */
-export const BrandConfig: BrandConfig = {
-  name: Brand,
-  version: BrandVersion,
-  colors: BrandColors,
-  typography: BrandTypography,
-  spacing: BrandSpacing,
-  borderRadius: BrandBorderRadius,
-  shadows: BrandShadows,
-  breakpoints: BrandBreakpoints,
-  animation: BrandAnimation,
-  easing: BrandEasing,
-} as const;
-
-/**
- * Get brand colors for a specific theme mode
- *
- * @param {ThemeMode} mode - Theme mode to get colors for
- * @param {BrandColorScheme} colors - Color scheme to use (defaults to BrandColors)
- * @returns {BrandColorPalette} Color palette for the specified mode
- *
- * @example
- * ```typescript
- * const darkColors = getBrandColors('dark');
- * console.log(darkColors.background); // '#0f172a'
- * ```
- */
-export function getBrandColors(
-  mode: ThemeMode,
-  colors: BrandColorScheme = BrandColors
-): BrandColorPalette {
-  switch (mode) {
-    case 'light':
-      return colors.light;
-    case 'dark':
-      return colors.dark;
-    case 'high-contrast':
-      return colors.highContrast;
-    case 'auto':
-      // Auto-detect based on system preference
-      if (typeof window !== 'undefined' && window.matchMedia) {
-        const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
-        return prefersDark ? colors.dark : colors.light;
-      }
-      return colors.light;
-    default:
-      return colors.light;
-  }
-}
-
-/**
- * Convert hex color to RGB values
- *
- * @param {HexColor} hex - Hex color value
- * @returns {RGBColor | null} RGB values or null if invalid
- *
- * @example
- * ```typescript
- * const rgb = hexToRgb('#2563eb');
- * console.log(rgb); // { r: 37, g: 99, b: 235 }
- * ```
- */
-export function hexToRgb(hex: HexColor): RGBColor | null {
-  const cleanHex = hex.replace('#', '');
-
-  if (!/^[0-9a-fA-F]{6}$/.test(cleanHex)) {
-    return null;
-  }
-
-  const r = parseInt(cleanHex.substring(0, 2), 16);
-  const g = parseInt(cleanHex.substring(2, 4), 16);
-  const b = parseInt(cleanHex.substring(4, 6), 16);
-
-  return { r, g, b };
-}
-
-/**
- * Convert RGB values to hex color
- *
- * @param {number} r - Red value (0-255)
- * @param {number} g - Green value (0-255)
- * @param {number} b - Blue value (0-255)
- * @returns {HexColor} Hex color value
- *
- * @example
- * ```typescript
- * const hex = rgbToHex(37, 99, 235);
- * console.log(hex); // '#2563eb'
- * ```
- */
-export function rgbToHex(r: number, g: number, b: number): HexColor {
-  const clamp = (n: number) => Math.max(0, Math.min(255, n));
-  const toHex = (n: number) => clamp(n).toString(16).padStart(2, '0');
-
-  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
-}
-
-/**
- * Convert hex color to RGBA with alpha
- *
- * @param {HexColor} hex - Hex color value
- * @param {number} alpha - Alpha value (0-1)
- * @returns {string} RGBA color string
- *
- * @example
- * ```typescript
- * const rgba = hexToRgba('#2563eb', 0.5);
- * console.log(rgba); // 'rgba(37, 99, 235, 0.5)'
- * ```
- */
-export function hexToRgba(hex: HexColor, alpha: number): string {
-  const rgb = hexToRgb(hex);
-  if (!rgb) {
-    throw new Error(`Invalid hex color: ${hex}`);
-  }
-  return `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${Math.max(0, Math.min(1, alpha))})`;
-}
-
-/**
- * Lighten a hex color by a percentage
- *
- * @param {HexColor} hex - Hex color value
- * @param {number} percent - Percentage to lighten (0-100)
- * @returns {HexColor} Lightened hex color
- *
- * @example
- * ```typescript
- * const lightBlue = lightenColor('#2563eb', 20);
- * ```
- */
-export function lightenColor(hex: HexColor, percent: number): HexColor {
-  const rgb = hexToRgb(hex);
-  if (!rgb) {
-    throw new Error(`Invalid hex color: ${hex}`);
-  }
-
-  const amount = Math.floor((255 * percent) / 100);
-
-  return rgbToHex(
-    rgb.r + amount,
-    rgb.g + amount,
-    rgb.b + amount
-  );
-}
-
-/**
- * Darken a hex color by a percentage
- *
- * @param {HexColor} hex - Hex color value
- * @param {number} percent - Percentage to darken (0-100)
- * @returns {HexColor} Darkened hex color
- *
- * @example
- * ```typescript
- * const darkBlue = darkenColor('#2563eb', 20);
- * ```
- */
-export function darkenColor(hex: HexColor, percent: number): HexColor {
-  const rgb = hexToRgb(hex);
-  if (!rgb) {
-    throw new Error(`Invalid hex color: ${hex}`);
-  }
-
-  const amount = Math.floor((255 * percent) / 100);
-
-  return rgbToHex(
-    rgb.r - amount,
-    rgb.g - amount,
-    rgb.b - amount
-  );
-}
-
-/**
- * Check if a color is light (for determining text contrast)
- *
- * @param {HexColor} hex - Hex color value
- * @returns {boolean} True if the color is light
- *
- * @example
- * ```typescript
- * const isLight = isLightColor('#ffffff'); // true
- * const isDark = isLightColor('#000000');  // false
- * ```
- */
-export function isLightColor(hex: HexColor): boolean {
-  const rgb = hexToRgb(hex);
-  if (!rgb) {
-    return false;
-  }
-
-  // Calculate relative luminance
-  const luminance = (0.299 * rgb.r + 0.587 * rgb.g + 0.114 * rgb.b) / 255;
-
-  return luminance > 0.5;
-}
-
-/**
- * Get the appropriate text color (light or dark) for contrast against a background
- *
- * @param {HexColor} backgroundColor - Background hex color
- * @returns {{ light: HexColor; dark: HexColor }} Text colors for contrast
- *
- * @example
- * ```typescript
- * const textColors = getContrastText('#2563eb');
- * console.log(textColors.light); // '#ffffff' (use this for dark backgrounds)
- * ```
- */
-export function getContrastText(backgroundColor: HexColor): {
-  light: HexColor;
-  dark: HexColor;
-} {
-  return {
-    light: '#ffffff',
-    dark: '#0f172a',
-  };
-}
-
-/**
- * Get the best text color for contrast against a background
- *
- * @param {HexColor} backgroundColor - Background hex color
- * @returns {HexColor} Best text color for contrast
- *
- * @example
- * ```typescript
- * const textColor = getBestContrastText('#0f172a'); // '#ffffff'
- * ```
- */
-export function getBestContrastText(backgroundColor: HexColor): HexColor {
-  return isLightColor(backgroundColor) ? '#0f172a' : '#ffffff';
-}
-
-/**
- * CSS custom properties (variables) generator for brand colors
- *
- * @param {ThemeMode} mode - Theme mode
- * @returns {Record<string, string>} CSS variable names and values
- *
- * @example
- * ```typescript
- * const cssVars = generateCSSVariables('dark');
- * // { '--gizzi-primary': '#3b82f6', ... }
- * ```
- */
-export function generateCSSVariables(mode: ThemeMode): Record<string, string> {
-  const colors = getBrandColors(mode);
-  const prefix = '--gizzi';
-
-  return {
-    [`${prefix}-primary`]: colors.primary,
-    [`${prefix}-secondary`]: colors.secondary,
-    [`${prefix}-accent`]: colors.accent,
-    [`${prefix}-background`]: colors.background,
-    [`${prefix}-surface`]: colors.surface,
-    [`${prefix}-text`]: colors.text,
-    [`${prefix}-text-muted`]: colors.textMuted,
-    [`${prefix}-error`]: colors.error,
-    [`${prefix}-warning`]: colors.warning,
-    [`${prefix}-success`]: colors.success,
-    [`${prefix}-info`]: colors.info,
-    [`${prefix}-border`]: colors.border,
-    [`${prefix}-divider`]: colors.divider,
-  };
-}
-
-// Default export
-export default {
-  Brand,
-  BrandVersion,
-  BrandColors,
-  BrandConfig,
-  LightColors,
-  DarkColors,
-  HighContrastColors,
-  BrandTypography,
-  BrandSpacing,
-  BrandBorderRadius,
-  BrandShadows,
-  BrandBreakpoints,
-  BrandAnimation,
-  BrandEasing,
-  getBrandColors,
-  hexToRgb,
-  rgbToHex,
-  hexToRgba,
-  lightenColor,
-  darkenColor,
-  isLightColor,
-  getContrastText,
-  getBestContrastText,
-  generateCSSVariables,
-};