@fabio.caffarello/react-design-system 1.7.0 → 1.9.0

package/src/ui/tokens/tokens.factory.ts

@@ -9,6 +9,13 @@ import { SpacingTokenFactory, type SpacingScale, type SpacingToken } from './spa
 import { TypographyTokenFactory, type TypographyToken, type FontSize, type LineHeight, type FontWeight } from './typography';
 import { ColorTokenFactory, type ColorRole, type SemanticColor, LightColorStrategy, DarkColorStrategy } from './colors';
 import { BreakpointTokenFactory, type BreakpointName, type BreakpointToken } from './breakpoints';
+import { ShadowTokenFactory, type ShadowSize, type ShadowToken } from './shadows';
+import { RadiusTokenFactory, type RadiusSize, type RadiusToken } from './radius';
+import { BorderTokenFactory, type BorderWidth, type BorderToken } from './borders';
+import { AnimationTokenFactory, type AnimationDuration, type EasingFunction, type AnimationToken } from './animations';
+import { ZIndexTokenFactory, type ZIndexLayer, type ZIndexToken } from './z-index';
+import { OpacityTokenFactory, type OpacityValue, type OpacityToken } from './opacity';
+import { GradientTokenFactory, type GradientRole, type GradientDirection, type GradientToken } from './gradients';
 
 export type ThemeMode = 'light' | 'dark';
 
@@ -17,6 +24,13 @@ export interface TokenSet {
   typography: Record<string, TypographyToken>;
   colors: Record<ColorRole, SemanticColor>;
   breakpoints: Record<BreakpointName, BreakpointToken>;
+  shadows: Record<string, ShadowToken>;
+  radius: Record<string, RadiusToken>;
+  borders: Record<string, BorderToken>;
+  animations: Record<string, AnimationToken>;
+  zIndex: Record<string, ZIndexToken>;
+  opacity: Record<string, OpacityToken>;
+  gradients: Record<string, GradientToken>;
 }
 
 /**
@@ -59,6 +73,55 @@ export class TokensFactory {
     return BreakpointTokenFactory.create(name);
   }
 
+  /**
+   * Create shadow token
+   */
+  createShadow(size: ShadowSize): ShadowToken {
+    return ShadowTokenFactory.create(size);
+  }
+
+  /**
+   * Create radius token
+   */
+  createRadius(size: RadiusSize): RadiusToken {
+    return RadiusTokenFactory.create(size);
+  }
+
+  /**
+   * Create border token
+   */
+  createBorder(width: BorderWidth): BorderToken {
+    return BorderTokenFactory.create(width);
+  }
+
+  /**
+   * Create animation token
+   */
+  createAnimation(duration: AnimationDuration, easing?: EasingFunction): AnimationToken {
+    return AnimationTokenFactory.create(duration, easing);
+  }
+
+  /**
+   * Create z-index token
+   */
+  createZIndex(layer: ZIndexLayer): ZIndexToken {
+    return ZIndexTokenFactory.create(layer);
+  }
+
+  /**
+   * Create opacity token
+   */
+  createOpacity(value: OpacityValue): OpacityToken {
+    return OpacityTokenFactory.create(value);
+  }
+
+  /**
+   * Create gradient token
+   */
+  createGradient(role: GradientRole, direction?: GradientDirection): GradientToken {
+    return GradientTokenFactory.create(role, direction);
+  }
+
   /**
    * Create complete token set for a theme
    */
@@ -91,6 +154,67 @@ export class TokensFactory {
         xl: this.createBreakpoint('xl'),
         '2xl': this.createBreakpoint('2xl'),
       },
+      shadows: {
+        none: this.createShadow('none'),
+        sm: this.createShadow('sm'),
+        md: this.createShadow('md'),
+        lg: this.createShadow('lg'),
+        xl: this.createShadow('xl'),
+        '2xl': this.createShadow('2xl'),
+        inner: this.createShadow('inner'),
+      },
+      radius: {
+        none: this.createRadius('none'),
+        sm: this.createRadius('sm'),
+        md: this.createRadius('md'),
+        lg: this.createRadius('lg'),
+        xl: this.createRadius('xl'),
+        '2xl': this.createRadius('2xl'),
+        '3xl': this.createRadius('3xl'),
+        full: this.createRadius('full'),
+      },
+      borders: {
+        none: this.createBorder('none'),
+        thin: this.createBorder('thin'),
+        base: this.createBorder('base'),
+        medium: this.createBorder('medium'),
+        thick: this.createBorder('thick'),
+      },
+      animations: {
+        fast: this.createAnimation('fast'),
+        base: this.createAnimation('base'),
+        slow: this.createAnimation('slow'),
+        slower: this.createAnimation('slower'),
+      },
+      zIndex: {
+        base: this.createZIndex('base'),
+        dropdown: this.createZIndex('dropdown'),
+        sticky: this.createZIndex('sticky'),
+        fixed: this.createZIndex('fixed'),
+        'modal-backdrop': this.createZIndex('modal-backdrop'),
+        modal: this.createZIndex('modal'),
+        popover: this.createZIndex('popover'),
+        tooltip: this.createZIndex('tooltip'),
+        toast: this.createZIndex('toast'),
+      },
+      opacity: {
+        transparent: this.createOpacity(0),
+        '5': this.createOpacity(5),
+        '10': this.createOpacity(10),
+        '25': this.createOpacity(25),
+        '50': this.createOpacity(50),
+        '75': this.createOpacity(75),
+        '90': this.createOpacity(90),
+        opaque: this.createOpacity(100),
+      },
+      gradients: {
+        primary: this.createGradient('primary'),
+        secondary: this.createGradient('secondary'),
+        success: this.createGradient('success'),
+        error: this.createGradient('error'),
+        info: this.createGradient('info'),
+        warning: this.createGradient('warning'),
+      },
     };
   }
 

package/src/ui/tokens/typography.ts

@@ -189,3 +189,40 @@ export function getTypographyClasses(variant: keyof typeof TYPOGRAPHY_TOKENS): s
   const token = TYPOGRAPHY_TOKENS[variant];
   return `${token.fontSize.tailwind} ${token.lineHeight.tailwind} ${token.fontWeight.tailwind}`;
 }
+
+/**
+ * Helper function to get only font size class
+ */
+export function getTypographySize(variant: keyof typeof TYPOGRAPHY_TOKENS): string {
+  return TYPOGRAPHY_TOKENS[variant].fontSize.tailwind;
+}
+
+/**
+ * Helper function to get font size class directly from FontSize
+ * This is a convenience function for when you just need a size, not a full typography variant
+ */
+export function getTypographySizeFromFontSize(size: FontSize): string {
+  return TypographyTokenFactory.createFontSize(size).tailwind;
+}
+
+/**
+ * Helper function to get only font weight class
+ */
+export function getTypographyWeight(variant: keyof typeof TYPOGRAPHY_TOKENS): string {
+  return TYPOGRAPHY_TOKENS[variant].fontWeight.tailwind;
+}
+
+/**
+ * Helper function to get font weight class directly from FontWeight
+ * This is a convenience function for when you just need a weight, not a full typography variant
+ */
+export function getTypographyWeightFromFontWeight(weight: FontWeight): string {
+  return TypographyTokenFactory.createFontWeight(weight).tailwind;
+}
+
+/**
+ * Helper function to get only line height class
+ */
+export function getTypographyLineHeight(variant: keyof typeof TYPOGRAPHY_TOKENS): string {
+  return TYPOGRAPHY_TOKENS[variant].lineHeight.tailwind;
+}

package/src/ui/tokens/versioning.ts

@@ -0,0 +1,199 @@
+/**
+ * Design Tokens Versioning System
+ * 
+ * Provides versioning and migration support for design tokens.
+ * Allows tracking changes, detecting breaking changes, and generating migration guides.
+ */
+
+export interface TokenVersion {
+  version: string;
+  timestamp: string;
+  changes: TokenChange[];
+  breakingChanges: BreakingChange[];
+}
+
+export interface TokenChange {
+  type: 'added' | 'modified' | 'removed' | 'deprecated';
+  category: string;
+  token: string;
+  oldValue?: unknown;
+  newValue?: unknown;
+  description?: string;
+}
+
+export interface BreakingChange {
+  category: string;
+  token: string;
+  reason: string;
+  migration: string;
+  severity: 'major' | 'minor' | 'patch';
+}
+
+/**
+ * Current tokens version
+ */
+export const CURRENT_TOKENS_VERSION = '1.8.0';
+
+/**
+ * Token version history
+ */
+export const TOKEN_VERSIONS: TokenVersion[] = [
+  {
+    version: '1.8.0',
+    timestamp: new Date().toISOString(),
+    changes: [],
+    breakingChanges: [],
+  },
+  // Add previous versions as needed
+];
+
+/**
+ * Get version information
+ */
+export function getTokenVersion(version: string): TokenVersion | undefined {
+  return TOKEN_VERSIONS.find((v) => v.version === version);
+}
+
+/**
+ * Get all changes between two versions
+ */
+export function getChangesBetweenVersions(
+  fromVersion: string,
+  toVersion: string
+): TokenChange[] {
+  const from = getTokenVersion(fromVersion);
+  const to = getTokenVersion(toVersion);
+
+  if (!from || !to) {
+    return [];
+  }
+
+  // Combine changes from all versions between from and to
+  const changes: TokenChange[] = [];
+  const fromIndex = TOKEN_VERSIONS.findIndex((v) => v.version === fromVersion);
+  const toIndex = TOKEN_VERSIONS.findIndex((v) => v.version === toVersion);
+
+  if (fromIndex === -1 || toIndex === -1) {
+    return [];
+  }
+
+  for (let i = fromIndex + 1; i <= toIndex; i++) {
+    changes.push(...TOKEN_VERSIONS[i].changes);
+  }
+
+  return changes;
+}
+
+/**
+ * Get breaking changes between two versions
+ */
+export function getBreakingChangesBetweenVersions(
+  fromVersion: string,
+  toVersion: string
+): BreakingChange[] {
+  const from = getTokenVersion(fromVersion);
+  const to = getTokenVersion(toVersion);
+
+  if (!from || !to) {
+    return [];
+  }
+
+  const breakingChanges: BreakingChange[] = [];
+  const fromIndex = TOKEN_VERSIONS.findIndex((v) => v.version === fromVersion);
+  const toIndex = TOKEN_VERSIONS.findIndex((v) => v.version === toVersion);
+
+  if (fromIndex === -1 || toIndex === -1) {
+    return [];
+  }
+
+  for (let i = fromIndex + 1; i <= toIndex; i++) {
+    breakingChanges.push(...TOKEN_VERSIONS[i].breakingChanges);
+  }
+
+  return breakingChanges;
+}
+
+/**
+ * Check if migration is needed
+ */
+export function needsMigration(currentVersion: string, targetVersion: string): boolean {
+  const breakingChanges = getBreakingChangesBetweenVersions(currentVersion, targetVersion);
+  return breakingChanges.length > 0;
+}
+
+/**
+ * Generate migration guide
+ */
+export function generateMigrationGuide(
+  fromVersion: string,
+  toVersion: string
+): string {
+  const changes = getChangesBetweenVersions(fromVersion, toVersion);
+  const breakingChanges = getBreakingChangesBetweenVersions(fromVersion, toVersion);
+
+  let guide = `# Migration Guide: Tokens ${fromVersion} → ${toVersion}\n\n`;
+
+  if (breakingChanges.length === 0) {
+    guide += '✅ No breaking changes. Safe to upgrade.\n\n';
+  } else {
+    guide += `⚠️ **${breakingChanges.length} breaking change(s) detected**\n\n`;
+    guide += `## Breaking Changes\n\n`;
+
+    breakingChanges.forEach((change) => {
+      guide += `### ${change.category}.${change.token}\n\n`;
+      guide += `**Severity**: ${change.severity}\n\n`;
+      guide += `**Reason**: ${change.reason}\n\n`;
+      guide += `**Migration**:\n\n\`\`\`typescript\n${change.migration}\n\`\`\`\n\n`;
+    });
+  }
+
+  if (changes.length > 0) {
+    guide += `## All Changes\n\n`;
+
+    const byType = changes.reduce((acc, change) => {
+      if (!acc[change.type]) {
+        acc[change.type] = [];
+      }
+      acc[change.type].push(change);
+      return acc;
+    }, {} as Record<string, TokenChange[]>);
+
+    Object.entries(byType).forEach(([type, changes]) => {
+      guide += `### ${type.charAt(0).toUpperCase() + type.slice(1)}\n\n`;
+      changes.forEach((change) => {
+        guide += `- **${change.category}.${change.token}**`;
+        if (change.description) {
+          guide += `: ${change.description}`;
+        }
+        guide += `\n`;
+      });
+      guide += `\n`;
+    });
+  }
+
+  return guide;
+}
+
+/**
+ * Validate token compatibility
+ */
+export function validateTokenCompatibility(
+  token: string,
+  category: string,
+  version: string
+): boolean {
+  const versionInfo = getTokenVersion(version);
+  if (!versionInfo) {
+    return false;
+  }
+
+  // Check if token was removed or deprecated in this version
+  const removed = versionInfo.changes.some(
+    (change) =>
+      change.category === category &&
+      change.token === token &&
+      (change.type === 'removed' || change.type === 'deprecated')
+  );
+
+  return !removed;
+}

package/src/ui/tokens/z-index.ts

@@ -0,0 +1,113 @@
+/**
+ * Z-Index Tokens
+ * 
+ * Centralized z-index system for consistent layering.
+ * Uses Factory Pattern for type-safe token creation.
+ */
+
+export type ZIndexLayer = 
+  | 'base' 
+  | 'dropdown' 
+  | 'sticky' 
+  | 'fixed' 
+  | 'modal-backdrop' 
+  | 'modal' 
+  | 'popover' 
+  | 'tooltip' 
+  | 'toast';
+
+export interface ZIndexToken {
+  value: number;
+  tailwind: string;
+  description: string;
+}
+
+/**
+ * Z-Index Token Factory
+ * Creates z-index tokens with consistent layering
+ */
+export class ZIndexTokenFactory {
+  /**
+   * Create a z-index token
+   */
+  static create(layer: ZIndexLayer): ZIndexToken {
+    const layerMap: Record<ZIndexLayer, { value: number; tailwind: string; description: string }> = {
+      base: {
+        value: 0,
+        tailwind: 'z-0',
+        description: 'Base layer for normal content',
+      },
+      dropdown: {
+        value: 1000,
+        tailwind: 'z-[1000]',
+        description: 'Dropdown menus and select options',
+      },
+      sticky: {
+        value: 1020,
+        tailwind: 'z-[1020]',
+        description: 'Sticky headers and navigation',
+      },
+      fixed: {
+        value: 1030,
+        tailwind: 'z-[1030]',
+        description: 'Fixed position elements',
+      },
+      'modal-backdrop': {
+        value: 1040,
+        tailwind: 'z-[1040]',
+        description: 'Modal backdrop/overlay',
+      },
+      modal: {
+        value: 1050,
+        tailwind: 'z-[1050]',
+        description: 'Modal dialogs and drawers',
+      },
+      popover: {
+        value: 1060,
+        tailwind: 'z-[1060]',
+        description: 'Popovers and tooltips',
+      },
+      tooltip: {
+        value: 1070,
+        tailwind: 'z-[1070]',
+        description: 'Tooltips (highest priority)',
+      },
+      toast: {
+        value: 1080,
+        tailwind: 'z-[1080]',
+        description: 'Toast notifications (highest priority)',
+      },
+    };
+
+    return layerMap[layer];
+  }
+}
+
+/**
+ * Pre-defined z-index tokens
+ */
+export const Z_INDEX_TOKENS = {
+  base: ZIndexTokenFactory.create('base'),
+  dropdown: ZIndexTokenFactory.create('dropdown'),
+  sticky: ZIndexTokenFactory.create('sticky'),
+  fixed: ZIndexTokenFactory.create('fixed'),
+  'modal-backdrop': ZIndexTokenFactory.create('modal-backdrop'),
+  modal: ZIndexTokenFactory.create('modal'),
+  popover: ZIndexTokenFactory.create('popover'),
+  tooltip: ZIndexTokenFactory.create('tooltip'),
+  toast: ZIndexTokenFactory.create('toast'),
+} as const;
+
+/**
+ * Helper function to get z-index token
+ */
+export function getZIndex(layer: ZIndexLayer): ZIndexToken {
+  return ZIndexTokenFactory.create(layer);
+}
+
+/**
+ * Helper function to get z-index as Tailwind class
+ */
+export function getZIndexClass(layer: ZIndexLayer): string {
+  return ZIndexTokenFactory.create(layer).tailwind;
+}