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

package/dist/ui/tools/DesignSystemConfigurator/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Design System Configurator Types
+ *
+ * Type definitions for the Design System Configurator tool.
+ */
+import type { ColorRole } from '../../tokens/colors';
+import type { SpacingScale } from '../../tokens/spacing';
+import type { FontSize, FontWeight, LineHeight } from '../../tokens/typography';
+import type { ThemeMode } from '../../tokens';
+/**
+ * Token Configuration
+ */
+export interface TokenConfig {
+    colors: ColorTokenConfig;
+    spacing: SpacingTokenConfig;
+    typography: TypographyTokenConfig;
+    shadows: ShadowTokenConfig;
+    radius: RadiusTokenConfig;
+    borders: BorderTokenConfig;
+    animations: AnimationTokenConfig;
+}
+export interface ColorTokenConfig {
+    [role: string]: {
+        [shade: string]: {
+            hex: string;
+            rgb: string;
+            tailwind: string;
+        };
+    };
+}
+export interface SpacingTokenConfig {
+    [scale: string]: {
+        px: string;
+        rem: string;
+        tailwind: string;
+    };
+}
+export interface TypographyTokenConfig {
+    fontSizes: {
+        [size: string]: {
+            px: string;
+            rem: string;
+            tailwind: string;
+        };
+    };
+    fontWeights: {
+        [weight: string]: {
+            value: number;
+            tailwind: string;
+        };
+    };
+    lineHeights: {
+        [height: string]: {
+            value: number;
+            tailwind: string;
+        };
+    };
+}
+export interface ShadowTokenConfig {
+    [size: string]: {
+        value: string;
+        tailwind: string;
+    };
+}
+export interface RadiusTokenConfig {
+    [size: string]: {
+        px: string;
+        rem: string;
+        tailwind: string;
+    };
+}
+export interface BorderTokenConfig {
+    [width: string]: {
+        px: string;
+        tailwind: string;
+    };
+}
+export interface AnimationTokenConfig {
+    durations: {
+        [duration: string]: {
+            ms: number;
+            tailwind: string;
+        };
+    };
+    easings: {
+        [easing: string]: {
+            value: string;
+            tailwind: string;
+        };
+    };
+}
+/**
+ * Component Configuration
+ */
+export interface ComponentConfig {
+    name: string;
+    category: 'atom' | 'molecule' | 'organism' | 'template' | 'pattern' | 'layout';
+    variants?: string[];
+    sizes?: string[];
+    states?: string[];
+    tokens: {
+        colors?: ColorRole[];
+        spacing?: SpacingScale[];
+        typography?: {
+            sizes?: FontSize[];
+            weights?: FontWeight[];
+            lineHeights?: LineHeight[];
+        };
+    };
+    accessibility?: {
+        ariaLabel?: boolean;
+        keyboardNavigation?: boolean;
+        focusManagement?: boolean;
+    };
+}
+/**
+ * Theme Configuration
+ */
+export interface ThemeConfig {
+    name: string;
+    base: ThemeMode;
+    tokens: TokenConfig;
+    customProperties?: Record<string, string>;
+}
+/**
+ * CSS Generation Options
+ */
+export interface CSSGenerationOptions {
+    format: 'css' | 'tailwind' | 'scss' | 'less';
+    includeVariables?: boolean;
+    includeUtilities?: boolean;
+    minify?: boolean;
+}
+/**
+ * Export Format
+ */
+export type ExportFormat = 'json' | 'typescript' | 'css' | 'tailwind' | 'scss';
+/**
+ * Configurator State
+ */
+export interface ConfiguratorState {
+    tokens: TokenConfig;
+    components: ComponentConfig[];
+    themes: ThemeConfig[];
+    currentTheme?: string;
+    selectedComponent?: string;
+}

package/dist/ui/tools/DesignSystemConfigurator/utils/configSerializer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Config Serializer
+ *
+ * Utilities for serializing and deserializing configurator state.
+ */
+import type { ConfiguratorState, ExportFormat } from '../types';
+/**
+ * Serialize state to JSON
+ */
+export declare function serializeState(state: ConfiguratorState): string;
+/**
+ * Deserialize state from JSON
+ */
+export declare function deserializeState(json: string): ConfiguratorState;
+/**
+ * Export state in specified format
+ */
+export declare function exportState(state: ConfiguratorState, format: ExportFormat): string;

package/dist/ui/tools/DeveloperJourney/ComponentAssistant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Component Assistant
+ *
+ * Interactive assistant for creating components.
+ */
+/**
+ * Component Assistant Component
+ *
+ * Wizard-style assistant for creating components step by step.
+ *
+ * @example
+ * ```tsx
+ * <ComponentAssistant />
+ * ```
+ */
+export declare function ComponentAssistant(): import("react/jsx-runtime").JSX.Element;

package/dist/ui/tools/DeveloperJourney/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Developer Journey Tools
+ *
+ * Exports for Developer Journey tools.
+ */
+export { ComponentAssistant } from './ComponentAssistant';

package/dist/ui/tools/ThemeBuilder.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Theme Builder Component
+ *
+ * Interactive tool for building custom themes with real-time preview.
+ * Allows adjusting colors, spacing, typography and exporting themes.
+ *
+ * @example
+ * ```tsx
+ * <ThemeBuilder />
+ * ```
+ */
+export declare function ThemeBuilderComponent(): import("react/jsx-runtime").JSX.Element;

package/dist/ui/tools/ThemeBuilder.stories.d.ts

@@ -0,0 +1,11 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeBuilderComponent } from './ThemeBuilder';
+declare const meta: Meta<typeof ThemeBuilderComponent>;
+export default meta;
+type Story = StoryObj<typeof ThemeBuilderComponent>;
+/**
+ * Default Theme Builder
+ *
+ * Interactive theme builder with all controls enabled.
+ */
+export declare const Default: Story;

package/dist/ui/tools/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tools
+ *
+ * Exports for all development tools.
+ */
+export { ThemeBuilderComponent } from './ThemeBuilder';
+export { DesignSystemConfigurator } from './DesignSystemConfigurator';
+export type { DesignSystemConfiguratorProps } from './DesignSystemConfigurator';
+export { CSSConfigurator } from './CSSConfigurator';
+export * from './DeveloperJourney';

package/dist/ui/utilities/Portal/Portal.d.ts

@@ -0,0 +1,30 @@
+import React from 'react';
+export interface PortalProps {
+    /**
+     * Content to render in the portal
+     */
+    children: React.ReactNode;
+    /**
+     * Container element ID. If not provided, creates a new div
+     * @default 'portal-root'
+     */
+    containerId?: string;
+    /**
+     * Whether to append to body directly
+     * @default false
+     */
+    appendToBody?: boolean;
+}
+/**
+ * Portal component for rendering content outside the DOM hierarchy
+ *
+ * Useful for modals, tooltips, dropdowns that need to escape parent overflow/stacking contexts.
+ *
+ * @example
+ * ```tsx
+ * <Portal>
+ *   <Modal>Content</Modal>
+ * </Portal>
+ * ```
+ */
+export declare function Portal({ children, containerId, appendToBody }: PortalProps): React.ReactPortal | null;

package/dist/ui/utilities/Portal/Portal.stories.d.ts

@@ -0,0 +1,12 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Portal } from './Portal';
+declare const meta: Meta<typeof Portal>;
+export default meta;
+type Story = StoryObj<typeof Portal>;
+export declare const Default: Story;
+export declare const CustomContainer: Story;
+export declare const AppendToBody: Story;
+export declare const DefaultState: Story;
+export declare const UnmountedState: Story;
+export declare const CustomContainerState: Story;
+export declare const AppendToBodyState: Story;

package/dist/ui/utilities/Portal/index.d.ts

@@ -0,0 +1 @@
+export { Portal, type PortalProps } from './Portal';

package/dist/ui/utilities/index.d.ts

@@ -0,0 +1 @@
+export { Portal, type PortalProps } from './Portal';

package/dist/ui/utils/cn.d.ts

@@ -0,0 +1,40 @@
+/**
+ * CN Utility - ClassName Merge
+ *
+ * Utility function for merging classNames with Tailwind conflict resolution.
+ * Combines clsx for conditional classes and tailwind-merge for conflict resolution.
+ *
+ * @example
+ * ```tsx
+ * cn('base-class', condition && 'conditional-class', className)
+ * cn(['class1', 'class2'], { 'class3': true })
+ * ```
+ */
+import { type ClassValue } from 'clsx';
+/**
+ * Merges classNames and resolves Tailwind class conflicts.
+ *
+ * Uses clsx for conditional class handling and tailwind-merge
+ * to intelligently merge Tailwind classes, resolving conflicts
+ * (e.g., 'p-2' and 'p-4' -> 'p-4').
+ *
+ * @param inputs - Class values to merge (strings, arrays, objects)
+ * @returns Merged className string with conflicts resolved
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * cn('base-class', 'another-class') // 'base-class another-class'
+ *
+ * // Conditional classes
+ * cn('base', isActive && 'active', className)
+ *
+ * // Arrays and objects
+ * cn(['class1', 'class2'], { 'class3': true, 'class4': false })
+ *
+ * // Tailwind conflict resolution
+ * cn('p-2', 'p-4') // 'p-4' (p-2 is overridden)
+ * cn('text-red-500', 'text-blue-500') // 'text-blue-500'
+ * ```
+ */
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/ui/utils/css-variables.d.ts

@@ -0,0 +1,55 @@
+/**
+ * CSS Variables System
+ *
+ * Utility functions for working with CSS custom properties (variables).
+ * Provides type-safe access to design tokens as CSS variables.
+ */
+/**
+ * Get CSS variable name for a design token
+ *
+ * @example
+ * ```tsx
+ * cssVar('color', 'primary', 'DEFAULT') // '--color-primary-DEFAULT'
+ * cssVar('spacing', 'md') // '--spacing-md'
+ * ```
+ */
+export declare function cssVar(category: string, ...parts: string[]): string;
+/**
+ * Get CSS variable value as inline style
+ *
+ * @example
+ * ```tsx
+ * style={{ [cssVarValue('color', 'primary', 'DEFAULT')]: '#3b82f6' }}
+ * ```
+ */
+export declare function cssVarValue(category: string, ...parts: string[]): string;
+/**
+ * Create CSS variable object for inline styles
+ *
+ * @example
+ * ```tsx
+ * <div style={createCSSVars({
+ *   color: { primary: { DEFAULT: '#3b82f6' } },
+ *   spacing: { md: '12px' }
+ * })} />
+ * ```
+ */
+export declare function createCSSVars(vars: Record<string, Record<string, unknown>>): React.CSSProperties;
+/**
+ * Common CSS variable names for design tokens
+ */
+export declare const CSS_VARS: {
+    readonly color: {
+        readonly primary: (shade: string) => string;
+        readonly secondary: (shade: string) => string;
+        readonly success: (shade: string) => string;
+        readonly warning: (shade: string) => string;
+        readonly error: (shade: string) => string;
+        readonly info: (shade: string) => string;
+        readonly neutral: (shade: string) => string;
+    };
+    readonly spacing: (scale: string) => string;
+    readonly typography: (variant: string) => string;
+    readonly radius: (size: string) => string;
+    readonly shadow: (size: string) => string;
+};

package/dist/ui/utils/cva.d.ts

@@ -0,0 +1,68 @@
+/**
+ * CVA Utility - Class Variance Authority
+ *
+ * Type-safe utility for creating component variants with compound variants support.
+ * Based on class-variance-authority but integrated with our design system.
+ *
+ * @example
+ * ```tsx
+ * const buttonVariants = cva('base-class', {
+ *   variants: {
+ *     variant: { primary: 'bg-blue-500', secondary: 'bg-gray-500' },
+ *     size: { sm: 'text-sm', md: 'text-base' }
+ *   },
+ *   defaultVariants: { variant: 'primary', size: 'md' }
+ * })
+ * ```
+ */
+import { type VariantProps, cva as cvaLib } from 'class-variance-authority';
+/**
+ * Re-export VariantProps for type inference
+ */
+export type { VariantProps };
+/**
+ * Creates a type-safe variant function with compound variants support.
+ *
+ * Integrates with our cn() utility for proper Tailwind conflict resolution.
+ *
+ * @param base - Base classes that always apply
+ * @param config - Variant configuration with variants, compoundVariants, and defaultVariants
+ * @returns Function that returns className based on variant props
+ *
+ * @example
+ * ```tsx
+ * // Simple variants
+ * const buttonVariants = cva('base-class', {
+ *   variants: {
+ *     variant: {
+ *       primary: 'bg-blue-500 text-white',
+ *       secondary: 'bg-gray-500 text-white'
+ *     },
+ *     size: {
+ *       sm: 'px-2 py-1 text-sm',
+ *       md: 'px-4 py-2 text-base'
+ *     }
+ *   },
+ *   defaultVariants: {
+ *     variant: 'primary',
+ *     size: 'md'
+ *   }
+ * });
+ *
+ * // Usage
+ * buttonVariants({ variant: 'primary', size: 'sm' })
+ *
+ * // Compound variants
+ * const badgeVariants = cva('base', {
+ *   variants: {
+ *     variant: { success: '', error: '' },
+ *     style: { solid: '', outline: '' }
+ *   },
+ *   compoundVariants: [
+ *     { variant: 'success', style: 'solid', class: 'bg-green-500' },
+ *     { variant: 'error', style: 'outline', class: 'border-red-500' }
+ *   ]
+ * });
+ * ```
+ */
+export declare function cva(base: string, config?: Parameters<typeof cvaLib>[1]): (props?: Parameters<(props?: import("class-variance-authority/types").ClassProp | undefined) => string>[0]) => string;

package/dist/ui/utils/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Utils Module
+ *
+ * Shared utilities and helper functions for the design system.
+ */
+export { cn } from './cn';
+export { cva, type VariantProps } from './cva';
+export { variant, size, state, responsive, typography, radius, combine, } from './variants';

package/dist/ui/utils/tailwind-safelist.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Tailwind Safelist Generator
+ *
+ * Generates safelist patterns for dynamically generated Tailwind classes.
+ * This ensures that classes generated by design tokens are not purged.
+ *
+ * Note: Tailwind v4 uses @theme in CSS instead of config files.
+ * This file documents the classes that need to be preserved.
+ */
+/**
+ * Color classes that are dynamically generated
+ * These patterns ensure all color variants are preserved
+ */
+export declare const COLOR_SAFELIST_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
+/**
+ * Spacing classes that might be dynamically generated
+ */
+export declare const SPACING_SAFELIST_PATTERNS: readonly [RegExp];
+/**
+ * Typography classes
+ */
+export declare const TYPOGRAPHY_SAFELIST_PATTERNS: readonly [RegExp, RegExp, RegExp];
+/**
+ * Radius classes
+ */
+export declare const RADIUS_SAFELIST_PATTERNS: readonly [RegExp, RegExp];
+/**
+ * All safelist patterns combined
+ */
+export declare const TAILWIND_SAFELIST: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
+/**
+ * Documentation for Tailwind v4 configuration
+ *
+ * In Tailwind v4, safelist is configured via CSS using @theme or @source directives.
+ * Since we're using @tailwindcss/postcss, we can add safelist in the CSS file.
+ *
+ * For dynamic classes, we should ensure they're:
+ * 1. Used in component code (so Tailwind detects them)
+ * 2. Documented here for reference
+ * 3. Added to safelist if absolutely necessary
+ *
+ * See style.css for @source directive configuration.
+ */

package/dist/ui/utils/variants.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Variant Helpers
+ *
+ * Helper functions for common Tailwind variant patterns.
+ * Integrates with design tokens for consistency.
+ */
+/**
+ * Creates variant classes based on color role and shade
+ *
+ * @example
+ * ```tsx
+ * variant('primary', 'DEFAULT', 'bg') // 'bg-indigo-500'
+ * variant('error', 'light', 'text') // 'text-red-100'
+ * ```
+ */
+export declare function variant(role: 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' | 'neutral', shade?: 'light' | 'DEFAULT' | 'dark' | 'contrast', type?: 'text' | 'bg' | 'border'): string;
+/**
+ * Creates size classes based on spacing tokens
+ *
+ * @example
+ * ```tsx
+ * size('sm', 'px') // 'px-2'
+ * size('md', 'py') // 'py-3'
+ * size('md', 'gap') // 'gap-4'
+ * ```
+ */
+export declare function size(scale: 'xs' | 'sm' | 'md' | 'base' | 'lg' | 'xl' | '2xl', direction?: 'p' | 'px' | 'py' | 'pt' | 'pr' | 'pb' | 'pl' | 'm' | 'mx' | 'my' | 'mt' | 'mr' | 'mb' | 'ml' | 'gap' | 'space-x' | 'space-y'): string;
+/**
+ * Creates state classes (hover, focus, active, disabled)
+ *
+ * @example
+ * ```tsx
+ * state('hover', 'primary', 'light', 'bg') // 'hover:bg-indigo-100'
+ * state('focus', 'error', 'DEFAULT', 'border') // 'focus:border-red-500'
+ * ```
+ */
+export declare function state(stateType: 'hover' | 'focus' | 'active' | 'disabled', role: 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' | 'neutral', shade?: 'light' | 'DEFAULT' | 'dark' | 'contrast', type?: 'text' | 'bg' | 'border'): string;
+/**
+ * Creates responsive classes based on breakpoints
+ *
+ * @example
+ * ```tsx
+ * responsive('md', 'flex', 'hidden') // 'hidden md:flex'
+ * responsive('lg', 'text-lg', 'text-sm') // 'text-sm lg:text-lg'
+ * ```
+ */
+export declare function responsive(breakpoint: 'sm' | 'md' | 'lg' | 'xl' | '2xl', classes: string, baseClasses?: string): string;
+/**
+ * Creates typography variant classes
+ *
+ * @example
+ * ```tsx
+ * typography('body') // 'text-base leading-relaxed font-normal'
+ * typography('h1') // 'text-4xl leading-tight font-bold'
+ * ```
+ */
+export declare function typography(variant: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'body' | 'bodySmall' | 'bodyLarge' | 'label' | 'caption' | 'button', options?: {
+    sizeOnly?: boolean;
+    weightOnly?: boolean;
+}): string;
+/**
+ * Creates radius classes
+ *
+ * @example
+ * ```tsx
+ * radius('md') // 'rounded-md'
+ * radius('full') // 'rounded-full'
+ * ```
+ */
+export declare function radius(size: 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'): string;
+/**
+ * Combines multiple variant helpers
+ *
+ * @example
+ * ```tsx
+ * combine(
+ *   variant('primary', 'DEFAULT', 'bg'),
+ *   size('md', 'px'),
+ *   state('hover', 'primary', 'light', 'bg')
+ * )
+ * ```
+ */
+export declare function combine(...classes: (string | undefined | null | false)[]): string;