@trinityui/design-system 1.0.3 → 1.0.5

package/dist/form.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Trinity Form Utilities
+ * Helpers for building consistent, accessible forms
+ *
+ * @module form
+ */
+import React from 'react';
+export type ValidationRule<T = unknown> = {
+    /** Validation function - return true if valid, false or error message if invalid */
+    validate: (value: T) => boolean | string;
+    /** Error message if validate returns false */
+    message?: string;
+};
+export type FieldState = {
+    /** Current field value */
+    value: unknown;
+    /** Whether field has been touched/interacted with */
+    touched: boolean;
+    /** Whether field is currently being edited */
+    dirty: boolean;
+    /** Current error message (if any) */
+    error: string | null;
+    /** Whether field is currently validating (async) */
+    validating: boolean;
+};
+export type FieldConfig<T = unknown> = {
+    /** Initial value */
+    initialValue?: T;
+    /** Validation rules */
+    rules?: ValidationRule<T>[];
+    /** Whether to validate on change */
+    validateOnChange?: boolean;
+    /** Whether to validate on blur */
+    validateOnBlur?: boolean;
+    /** Custom transform function for value */
+    transform?: (value: T) => T;
+};
+export type FormState = {
+    /** All field states */
+    fields: Record<string, FieldState>;
+    /** Whether form is submitting */
+    isSubmitting: boolean;
+    /** Whether form is valid */
+    isValid: boolean;
+    /** Whether form has been submitted */
+    isSubmitted: boolean;
+    /** Whether any field has been touched */
+    isTouched: boolean;
+    /** Whether any field is dirty */
+    isDirty: boolean;
+};
+export type FormContextValue = {
+    /** Form state */
+    state: FormState;
+    /** Register a field */
+    registerField: (name: string, config?: FieldConfig) => void;
+    /** Unregister a field */
+    unregisterField: (name: string) => void;
+    /** Get field state */
+    getFieldState: (name: string) => FieldState | undefined;
+    /** Set field value */
+    setFieldValue: (name: string, value: unknown) => void;
+    /** Set field touched */
+    setFieldTouched: (name: string, touched?: boolean) => void;
+    /** Set field error */
+    setFieldError: (name: string, error: string | null) => void;
+    /** Validate a field */
+    validateField: (name: string) => Promise<boolean>;
+    /** Validate all fields */
+    validateForm: () => Promise<boolean>;
+    /** Reset form to initial values */
+    resetForm: () => void;
+    /** Submit handler */
+    handleSubmit: (onSubmit: (values: Record<string, unknown>) => void | Promise<void>) => (e?: React.FormEvent) => Promise<void>;
+    /** Get all form values */
+    getValues: () => Record<string, unknown>;
+};
+export interface FormProviderProps {
+    /** Form content */
+    children: React.ReactNode;
+    /** Initial form values */
+    initialValues?: Record<string, unknown>;
+    /** Called when form is submitted successfully */
+    onSubmit?: (values: Record<string, unknown>) => void | Promise<void>;
+    /** Called when validation fails */
+    onValidationError?: (errors: Record<string, string>) => void;
+    /** Whether to validate all fields on submit */
+    validateOnSubmit?: boolean;
+}
+/**
+ * FormProvider - Provides form context to child components.
+ * Manages form state, validation, and submission.
+ *
+ * @example
+ * ```tsx
+ * <FormProvider
+ *   initialValues={{ email: '', password: '' }}
+ *   onSubmit={(values) => console.log(values)}
+ * >
+ *   <FormField name="email" label="Email" rules={[required()]} />
+ *   <FormField name="password" label="Password" rules={[required()]} />
+ *   <button type="submit">Submit</button>
+ * </FormProvider>
+ * ```
+ */
+export declare const FormProvider: React.FC<FormProviderProps>;
+/**
+ * Hook to access form context.
+ * Must be used within a FormProvider.
+ */
+export declare const useForm: () => FormContextValue;
+export interface UseFormFieldOptions<T = unknown> {
+    /** Field name (required) */
+    name: string;
+    /** Initial value */
+    initialValue?: T;
+    /** Validation rules */
+    rules?: ValidationRule<T>[];
+    /** Whether to validate on change */
+    validateOnChange?: boolean;
+    /** Whether to validate on blur */
+    validateOnBlur?: boolean;
+    /** Custom transform function */
+    transform?: (value: T) => T;
+}
+export interface UseFormFieldReturn<T = unknown> {
+    /** Field value */
+    value: T;
+    /** Field error */
+    error: string | null;
+    /** Whether field has been touched */
+    touched: boolean;
+    /** Whether field is dirty */
+    dirty: boolean;
+    /** Whether field is validating */
+    validating: boolean;
+    /** Whether field has an error and has been touched */
+    showError: boolean;
+    /** Input props to spread */
+    inputProps: {
+        name: string;
+        value: T;
+        onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement> | T) => void;
+        onBlur: () => void;
+        'aria-invalid': boolean;
+        'aria-describedby': string | undefined;
+    };
+    /** Error message ID for aria-describedby */
+    errorId: string;
+    /** Set field value directly */
+    setValue: (value: T) => void;
+    /** Set touched state */
+    setTouched: (touched?: boolean) => void;
+    /** Validate field */
+    validate: () => Promise<boolean>;
+}
+/**
+ * Hook for connecting a form field to FormProvider.
+ * Handles registration, validation, and state management.
+ *
+ * @example
+ * ```tsx
+ * const EmailInput = () => {
+ *   const { inputProps, error, showError } = useFormField({
+ *     name: 'email',
+ *     rules: [required(), email()],
+ *   });
+ *
+ *   return (
+ *     <TextField
+ *       {...inputProps}
+ *       error={showError}
+ *       helperText={showError ? error : undefined}
+ *     />
+ *   );
+ * };
+ * ```
+ */
+export declare const useFormField: <T = unknown>({ name, initialValue, rules, validateOnChange, validateOnBlur, transform, }: UseFormFieldOptions<T>) => UseFormFieldReturn<T>;
+/**
+ * Required field validation rule.
+ */
+export declare const required: (message?: string) => ValidationRule;
+/**
+ * Email validation rule.
+ */
+export declare const email: (message?: string) => ValidationRule<string>;
+/**
+ * Minimum length validation rule.
+ */
+export declare const minLength: (min: number, message?: string) => ValidationRule<string>;
+/**
+ * Maximum length validation rule.
+ */
+export declare const maxLength: (max: number, message?: string) => ValidationRule<string>;
+/**
+ * Pattern validation rule.
+ */
+export declare const pattern: (regex: RegExp, message?: string) => ValidationRule<string>;
+/**
+ * Minimum number validation rule.
+ */
+export declare const min: (minValue: number, message?: string) => ValidationRule<number>;
+/**
+ * Maximum number validation rule.
+ */
+export declare const max: (maxValue: number, message?: string) => ValidationRule<number>;
+/**
+ * Custom validation rule.
+ */
+export declare const custom: <T>(validateFn: (value: T) => boolean | string, message?: string) => ValidationRule<T>;
+//# sourceMappingURL=form.d.ts.map

package/dist/form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.d.ts","sourceRoot":"","sources":["../src/form.tsx"],"names":[],"mappings":"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"}

package/dist/hierarchy.d.ts

@@ -0,0 +1,371 @@
+import { hierarchy, elevationHierarchy, typographicHierarchy, attentionHierarchy, scaleHierarchy, contrastHierarchy, interactiveHierarchy, spacingHierarchy, getElevation, getTypography, getAttentionColor, getHierarchySpacing } from './tokens';
+export { hierarchy, elevationHierarchy, typographicHierarchy, attentionHierarchy, scaleHierarchy, contrastHierarchy, interactiveHierarchy, spacingHierarchy, getElevation, getTypography, getAttentionColor, getHierarchySpacing, };
+export type ElevationLevel = keyof typeof elevationHierarchy;
+export type AttentionLevel = keyof typeof attentionHierarchy;
+export type TypographyCategory = keyof typeof typographicHierarchy;
+export type SpacingCategory = keyof typeof spacingHierarchy;
+export type ContrastLevel = keyof typeof contrastHierarchy;
+export type InteractiveState = keyof typeof interactiveHierarchy;
+export interface HierarchyStyles {
+    elevation?: ElevationLevel;
+    attention?: AttentionLevel;
+    typography?: {
+        category: TypographyCategory;
+        variant: string;
+    };
+    spacing?: {
+        category: SpacingCategory;
+        size: number;
+    };
+}
+/**
+ * Get CSS properties for an elevation level
+ * @param level - Elevation level name
+ * @returns Object with zIndex and boxShadow CSS properties
+ */
+export declare function getElevationStyles(level: ElevationLevel): {
+    zIndex: number | string;
+    boxShadow: string;
+    position?: string;
+};
+/**
+ * Get elevation for common UI patterns
+ */
+export declare const uiElevation: {
+    /** For sunken/recessed areas like code blocks, wells */
+    sunken: () => {
+        zIndex: number | string;
+        boxShadow: string;
+        position?: string;
+    };
+    /** For standard cards at rest */
+    card: () => {
+        zIndex: number | string;
+        boxShadow: string;
+        position?: string;
+    };
+    /** For hovered/focused cards */
+    cardHover: () => {
+        zIndex: number | string;
+        boxShadow: string;
+        position?: string;
+    };
+    /** For dropdown menus */
+    dropdown: () => {
+        zIndex: number | string;
+        boxShadow: string;
+        position?: string;
+    };
+    /** For sticky headers */
+    header: () => {
+        zIndex: number | string;
+        boxShadow: string;
+        position?: string;
+    };
+    /** For modal backdrops */
+    backdrop: () => {
+        zIndex: number | string;
+        boxShadow: string;
+        position?: string;
+    };
+    /** For modal dialogs */
+    modal: () => {
+        zIndex: number | string;
+        boxShadow: string;
+        position?: string;
+    };
+    /** For popovers */
+    popover: () => {
+        zIndex: number | string;
+        boxShadow: string;
+        position?: string;
+    };
+    /** For tooltips */
+    tooltip: () => {
+        zIndex: number | string;
+        boxShadow: string;
+        position?: string;
+    };
+};
+/**
+ * Get typography CSS properties
+ * @param category - Typography category (display, heading, body, label, caption, overline)
+ * @param variant - Variant within the category
+ * @returns CSS properties object
+ */
+export declare function getTypographyStyles(category: TypographyCategory, variant: string): Record<string, string | number> | null;
+/**
+ * Commonly used typography presets
+ */
+export declare const typographyPresets: {
+    heroTitle: () => Record<string, string | number> | null;
+    pageTitle: () => Record<string, string | number> | null;
+    sectionTitle: () => Record<string, string | number> | null;
+    h1: () => Record<string, string | number> | null;
+    h2: () => Record<string, string | number> | null;
+    h3: () => Record<string, string | number> | null;
+    h4: () => Record<string, string | number> | null;
+    h5: () => Record<string, string | number> | null;
+    h6: () => Record<string, string | number> | null;
+    bodyLarge: () => Record<string, string | number> | null;
+    body: () => Record<string, string | number> | null;
+    bodySmall: () => Record<string, string | number> | null;
+    labelLarge: () => Record<string, string | number> | null;
+    label: () => Record<string, string | number> | null;
+    labelSmall: () => Record<string, string | number> | null;
+    caption: () => Record<string, string | number> | null;
+    captionEmphasis: () => Record<string, string | number> | null;
+    overline: () => Record<string, string | number> | null;
+};
+/**
+ * Get color for attention level
+ * @param level - Attention level
+ * @param mode - Light or dark mode
+ * @returns Color value
+ */
+export declare function getAttentionStyles(level: AttentionLevel, mode?: 'light' | 'dark'): {
+    color: string;
+    opacity?: number;
+};
+/**
+ * Apply attention-based styling to content
+ */
+export declare const attentionStyles: {
+    /** Primary importance - CTAs, titles, critical info */
+    primary: (mode?: "light" | "dark") => {
+        color: string;
+        fontWeight: number;
+    };
+    /** Secondary importance - section headers, key info */
+    secondary: (mode?: "light" | "dark") => {
+        color: string;
+        fontWeight: number;
+    };
+    /** Tertiary - body text, regular content */
+    tertiary: (mode?: "light" | "dark") => {
+        color: string;
+        fontWeight: number;
+    };
+    /** Muted - helper text, metadata */
+    muted: (mode?: "light" | "dark") => {
+        color: string;
+        fontWeight: number;
+    };
+    /** Disabled - unavailable items */
+    disabled: (mode?: "light" | "dark") => {
+        color: string;
+        fontWeight: number;
+        opacity: number;
+        cursor: string;
+    };
+};
+/**
+ * Get spacing value from hierarchy
+ */
+export declare function getSpacing(category: SpacingCategory, size: number): number | null;
+/**
+ * Spacing presets for common use cases
+ */
+export declare const spacing: {
+    inline: 4;
+    inlineRelaxed: 8;
+    componentTight: 12;
+    component: 16;
+    componentRelaxed: 20;
+    sectionTight: 24;
+    section: 32;
+    sectionRelaxed: 40;
+    layoutTight: 48;
+    layout: 64;
+    layoutRelaxed: 96;
+    layoutHero: 128;
+};
+/**
+ * Get scaled size based on base value and scale step
+ */
+export declare function getScaledSize(base: number, step: keyof typeof scaleHierarchy.sizes): number;
+/**
+ * Get icon size
+ */
+export declare function getIconSize(size: keyof typeof scaleHierarchy.icons): number;
+/**
+ * Ensure touch target meets accessibility requirements
+ */
+export declare function ensureTouchTarget(size: number, level?: 'minimum' | 'comfortable' | 'spacious'): number;
+/**
+ * Get interactive state styles
+ */
+export declare function getInteractiveStyles(state: InteractiveState): Record<string, string | number>;
+/**
+ * Get focus ring styles for accessibility
+ */
+export declare function getFocusRingStyles(color?: string): Record<string, string | number>;
+/**
+ * CSS for interactive hover effects
+ */
+export declare const hoverEffect: {
+    /** Subtle lift effect */
+    lift: {
+        transition: string;
+        '&:hover': {
+            transform: string;
+            boxShadow: "0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)";
+        };
+    };
+    /** Scale effect */
+    scale: {
+        transition: string;
+        '&:hover': {
+            transform: string;
+        };
+    };
+    /** Highlight effect */
+    highlight: {
+        transition: string;
+        '&:hover': {
+            backgroundColor: string;
+        };
+    };
+};
+/**
+ * Get contrast pair colors
+ */
+export declare function getContrastColors(level: ContrastLevel): {
+    foreground: string;
+    background: string;
+    ratio: number;
+};
+/**
+ * Check if a contrast ratio meets WCAG requirements
+ */
+export declare function meetsWCAG(ratio: number, level?: 'AA' | 'AAA', isLargeText?: boolean): boolean;
+/**
+ * Apply multiple hierarchy aspects at once
+ */
+export declare function applyHierarchy(config: HierarchyStyles): Record<string, unknown>;
+/**
+ * Get presets for common UI patterns
+ */
+export declare const uiPatterns: {
+    /** Card with hover effect */
+    interactiveCard: () => {
+        borderRadius: number;
+        transition: string;
+        cursor: string;
+        '&:hover': {
+            transform: string;
+            zIndex: number | string;
+            boxShadow: string;
+            position?: string;
+        };
+        '&:focus-visible': Record<string, string | number>;
+        zIndex: number | string;
+        boxShadow: string;
+        position?: string;
+    };
+    /** Modal dialog */
+    modal: () => {
+        borderRadius: number;
+        padding: 32;
+        zIndex: number | string;
+        boxShadow: string;
+        position?: string;
+    };
+    /** Dropdown menu */
+    dropdown: () => {
+        borderRadius: number;
+        padding: 4;
+        zIndex: number | string;
+        boxShadow: string;
+        position?: string;
+    };
+    /** Tooltip */
+    tooltip: () => {
+        borderRadius: number;
+        padding: string;
+        zIndex: number | string;
+        boxShadow: string;
+        position?: string;
+    };
+    /** Primary button */
+    primaryButton: () => {
+        padding: string;
+        borderRadius: number;
+        fontWeight: number;
+        transition: string;
+        '&:hover': {
+            transform: string;
+        };
+        '&:active': {
+            transform: string;
+        };
+        '&:focus-visible': Record<string, string | number>;
+    };
+    /** Section container */
+    section: () => {
+        paddingTop: 32;
+        paddingBottom: 32;
+        display: string;
+        flexDirection: "column";
+        gap: 20;
+    };
+    /** Page container */
+    page: () => {
+        maxWidth: number;
+        margin: string;
+        padding: 32;
+        display: string;
+        flexDirection: "column";
+        gap: 64;
+    };
+};
+/**
+ * Design System Architecture Reference
+ *
+ * Layer 1: FOUNDATIONS (baseTokens)
+ * - Color palettes (navy, purple, coral, azure, gray)
+ * - Typography scales (font sizes, weights, line heights)
+ * - Spacing scale (0-32, in 4px increments)
+ * - Border radius scale (none through full)
+ * - Shadow definitions
+ * - Motion/animation values
+ *
+ * Layer 2: DESIGN TOKENS (semanticTokens)
+ * - Semantic color mappings (brand, text, background, border, status)
+ * - Typography presets (display, heading, body, label)
+ * - Semantic spacing (component, layout)
+ * - Semantic borders and shadows
+ *
+ * Layer 3: COMPONENT TOKENS (componentTokens)
+ * - Button sizes, colors, radii
+ * - Input specifications
+ * - Card tokens
+ * - Avatar, badge, chip tokens
+ * - Modal, tooltip tokens
+ * - Navigation tokens
+ *
+ * Layer 4: HIERARCHY (hierarchy)
+ * - Attention hierarchy (primary → disabled)
+ * - Typography hierarchy (display → overline)
+ * - Elevation hierarchy (ground → tooltip)
+ * - Scale hierarchy (size ratios)
+ * - Contrast hierarchy (accessibility)
+ * - Interactive hierarchy (states)
+ * - Spacing hierarchy (micro → layout)
+ *
+ * Layer 5: PATTERNS (uiPatterns)
+ * - Interactive card pattern
+ * - Modal pattern
+ * - Dropdown pattern
+ * - Button patterns
+ * - Section/page layouts
+ */
+export declare const architectureLayers: {
+    readonly foundations: "Layer 1: Raw design primitives (colors, spacing, typography scales)";
+    readonly tokens: "Layer 2: Semantic mappings of foundations to use cases";
+    readonly components: "Layer 3: UI component specifications";
+    readonly hierarchy: "Layer 4: Visual hierarchy rules for consistent importance";
+    readonly patterns: "Layer 5: Composed solutions for common UI tasks";
+};
+export default hierarchy;
+//# sourceMappingURL=hierarchy.d.ts.map

package/dist/hierarchy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchy.d.ts","sourceRoot":"","sources":["../src/hierarchy.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useTrinityPalette.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Trinity Theme Utilities
+ *
+ * These hooks provide access to Trinity's extended palette in a type-safe way.
+ * Use these instead of importing tokens directly when you need colors that
+ * should respond to light/dark mode.
+ */
+import { Theme } from '@mui/material';
+/**
+ * Trinity palette types
+ */
+export interface TrinityStatusColor {
+    text: string;
+    background: string;
+    border: string;
+}
+export interface TrinityInteractive {
+    default: string;
+    hover: string;
+    active: string;
+    disabled: string;
+    focus: string;
+}
+export interface TrinityBorder {
+    default: string;
+    subtle: string;
+    strong: string;
+}
+export interface TrinityPalette {
+    interactive: TrinityInteractive;
+    status: {
+        success: TrinityStatusColor;
+        warning: TrinityStatusColor;
+        error: TrinityStatusColor;
+        info: TrinityStatusColor;
+    };
+    border: TrinityBorder;
+}
+/**
+ * Hook to access Trinity's semantic colors from the theme.
+ * Returns mode-aware colors that automatically adjust for light/dark mode.
+ *
+ * @example
+ * ```tsx
+ * const trinity = useTrinityPalette();
+ * <Box color={trinity.status.success.text} />
+ * ```
+ */
+export declare function useTrinityPalette(): TrinityPalette;
+/**
+ * Get Trinity palette from a theme object (for use outside React components)
+ */
+export declare function getTrinityPalette(theme: Theme): TrinityPalette;
+//# sourceMappingURL=useTrinityPalette.d.ts.map

package/dist/hooks/useTrinityPalette.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTrinityPalette.d.ts","sourceRoot":"","sources":["../../src/hooks/useTrinityPalette.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAY,KAAK,EAAE,MAAM,eAAe,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,kBAAkB,CAAC;IAChC,MAAM,EAAE;QACN,OAAO,EAAE,kBAAkB,CAAC;QAC5B,OAAO,EAAE,kBAAkB,CAAC;QAC5B,KAAK,EAAE,kBAAkB,CAAC;QAC1B,IAAI,EAAE,kBAAkB,CAAC;KAC1B,CAAC;IACF,MAAM,EAAE,aAAa,CAAC;CACvB;AAoCD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CASlD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,cAAc,CAO9D"}