/** * CSS class resolution utilities for composing class definitions. * * Provides the `resolve_composes` helper to recursively resolve class names * to their combined CSS declarations. * * @internal * * @module */ import { levenshtein_distance } from '@fuzdev/fuz_util/string.ts'; import type { InterpreterDiagnostic } from './diagnostics.ts'; import type { CssClassDefinition, CssClassDefinitionStatic } from './css_class_definitions.ts'; import { try_resolve_literal, extract_segments, extract_and_validate_modifiers, has_extracted_modifiers, suggest_modifier } from './css_literal.ts'; /** * Result from resolving a `composes` array to combined declarations. */ export type ResolveComposesResult = | { ok: true; declaration: string; warnings: Array | null } | { ok: false; error: InterpreterDiagnostic }; /** * Resolves a class definition's declaration, handling `composes` composition. * * If the definition has a `composes` property, resolves those classes recursively * and combines with any explicit `declaration`. If no `composes`, returns the * explicit `declaration` directly. * * @param def - the class definition to resolve * @param class_name - the name of the class being resolved (for error messages) * @param definitions - record of all known class definitions * @param css_properties - set of valid CSS properties for literal validation, or null to skip * @returns combined declaration or an error */ export const resolve_class_definition = ( def: CssClassDefinitionStatic, class_name: string, definitions: Record, css_properties: Set | null = null ): ResolveComposesResult => { let warnings: Array | null = null; // Handle composes-based definitions if ('composes' in def && def.composes) { const result = resolve_composes( def.composes, definitions, new Set([class_name]), new Set(), class_name, css_properties ); if (!result.ok) return result; // Combine resolved declarations with explicit declaration (if present) let combined = result.declaration; if ('declaration' in def) { const trimmed = def.declaration?.trim(); if (trimmed) { combined = combined ? `${combined} ${trimmed}` : trimmed; } else if (def.declaration !== undefined) { // Warn about empty declaration warnings = result.warnings ? [...result.warnings] : []; warnings.push({ code: 'class_declaration_empty', level: 'warning', identifier: class_name, message: `Class "${class_name}" has an empty declaration`, suggestion: 'Remove the empty declaration property or add CSS' }); } } if (!warnings && result.warnings) { warnings = result.warnings; } return { ok: true, declaration: combined, warnings }; } // Handle declaration-only definitions if ('declaration' in def) { const trimmed = def.declaration?.trim(); if (!trimmed && def.declaration !== undefined) { warnings = [ { code: 'class_declaration_empty', level: 'warning', identifier: class_name, message: `Class "${class_name}" has an empty declaration`, suggestion: 'Remove the empty declaration property or add CSS' } ]; } return { ok: true, declaration: trimmed ?? '', warnings }; } // Ruleset definitions don't have a single declaration return { ok: true, declaration: '', warnings: null }; }; /** * Resolves an array of class names to their combined CSS declarations. * * Recursively resolves nested `composes` arrays and combines all declarations. * Validates that referenced classes exist and are resolvable (not rulesets or interpreters). * Supports unmodified CSS literals (e.g., `text-align:center`) in the composes array. * * Deduplication behavior: * - Diamond dependencies (class reached via different composition branches) are silently skipped * - Redundant listings (class already included by an earlier sibling in this array) emit a warning * * @param class_names - array of class names to resolve * @param definitions - record of all known class definitions * @param resolution_stack - set of class names currently being resolved (for cycle detection) * @param visited - set of all class names already resolved (for deduplication) * @param original_class_name - the class name being defined (for error messages) * @param css_properties - set of valid CSS properties for literal validation, or null to skip * @returns combined declarations or an error * @mutates `resolution_stack` - temporarily adds/removes names during recursion * @mutates `visited` - adds resolved class names for deduplication */ export const resolve_composes = ( class_names: Array, definitions: Record, resolution_stack: Set, visited: Set, original_class_name: string, css_properties: Set | null = null ): ResolveComposesResult => { const declarations: Array = []; let warnings: Array | null = null; // Snapshot of visited at start - classes added during this array's processing are redundant const visited_at_start: ReadonlySet = new Set(visited); for (const name of class_names) { // Cycle detection (current path) if (resolution_stack.has(name)) { const cycle_path = [...resolution_stack, name].join(' → '); return { ok: false, error: { code: 'class_composes_cycle', level: 'error', identifier: original_class_name, message: `Circular reference detected: ${cycle_path}`, suggestion: 'Remove the circular dependency from composes arrays' } }; } // Deduplication - skip if already resolved if (visited.has(name)) { // Warn if redundant (added during this array's processing), not diamond (was already there) if (!visited_at_start.has(name)) { warnings ??= []; warnings.push({ code: 'class_composes_redundant', level: 'warning', identifier: original_class_name, message: `Class "${name}" is redundant`, suggestion: 'Already included by another class in this definition' }); } continue; } const def = definitions[name]; if (!def) { // Check if this looks like a modified class (hover:box, md:p_lg) const segments = extract_segments(name); if (segments.length >= 2) { const mod_result = extract_and_validate_modifiers(segments, name); if ( mod_result.ok && mod_result.remaining.length === 1 && has_extracted_modifiers(mod_result.modifiers) ) { const base_name = mod_result.remaining[0]!; const base_def = definitions[base_name]; if (base_def) { // Modified existing class - can't compose return { ok: false, error: { code: 'class_composes_modified', level: 'error', identifier: original_class_name, message: `Modified class "${name}" cannot be used in composes array`, suggestion: 'Apply modified classes directly in markup, not in composes arrays' } }; } else { // Looks like modifier:unknown - report the unknown base return { ok: false, error: { code: 'class_composes_unknown', level: 'error', identifier: original_class_name, message: `Unknown class "${base_name}" in composes array`, suggestion: `Check that "${base_name}" is defined in class_definitions` } }; } } } // Try parsing as CSS literal const literal_result = try_resolve_literal(name, css_properties, original_class_name); if (literal_result.ok) { visited.add(name); declarations.push(literal_result.declaration); if (literal_result.warnings) { warnings ??= []; warnings.push(...literal_result.warnings); } continue; } // If literal parsing returned an error, check for modifier typo pattern if (literal_result.error) { // Check for typo'd modifier where last segment is a known class // Handles: hovr:box, md:hovr:box, etc. const prop_match = /Unknown CSS property "([^"]+)"/.exec(literal_result.error.message); if (prop_match) { const failed_prop = prop_match[1]!; const suggested = suggest_modifier(failed_prop); // Only suggest if it's a close typo (edit distance 1) if (suggested && levenshtein_distance(failed_prop, suggested) === 1) { // Check if the last segment is a known class const last_colon = name.lastIndexOf(':'); const potential_class = name.slice(last_colon + 1); if (definitions[potential_class]) { // Reconstruct the corrected class name const corrected = name.slice(0, name.lastIndexOf(failed_prop)) + suggested + ':' + potential_class; return { ok: false, error: { code: 'class_modifier_unknown', level: 'error', identifier: original_class_name, message: `Unknown modifier "${failed_prop}" with class "${potential_class}"`, suggestion: `Did you mean "${ corrected }"? Note: modified classes cannot be used in composes` } }; } } } return { ok: false, error: literal_result.error }; } // Not a literal - fall through to original "unknown class" error return { ok: false, error: { code: 'class_composes_unknown', level: 'error', identifier: original_class_name, message: `Unknown class "${name}" in composes array`, suggestion: `Check that "${name}" is defined in class_definitions` } }; } // Only static definitions allowed (not interpreters) if ('pattern' in def) { return { ok: false, error: { code: 'class_composes_interpreter', level: 'error', identifier: original_class_name, message: `Cannot reference interpreter pattern "${name}" in composes array`, suggestion: 'Only static class definitions can be referenced' } }; } // Ruleset not allowed in composes if ('ruleset' in def && def.ruleset) { return { ok: false, error: { code: 'class_composes_ruleset', level: 'error', identifier: original_class_name, message: `Cannot reference ruleset class "${name}" in composes array`, suggestion: 'Ruleset classes have multiple selectors and cannot be inlined' } }; } // Mark as visited before processing (for deduplication) visited.add(name); // Recursive resolution for nested composes if ('composes' in def && def.composes) { resolution_stack.add(name); const nested = resolve_composes( def.composes, definitions, resolution_stack, visited, original_class_name, css_properties ); resolution_stack.delete(name); if (!nested.ok) return nested; // Propagate error if (nested.declaration) { declarations.push(nested.declaration); } if (nested.warnings) { warnings ??= []; warnings.push(...nested.warnings); } } // Add the declaration if present (trimmed) if ('declaration' in def) { const trimmed = def.declaration?.trim(); if (trimmed) { declarations.push(trimmed); } else if (def.declaration !== undefined) { // Warn about empty declaration warnings ??= []; warnings.push({ code: 'class_declaration_empty', level: 'warning', identifier: name, message: `Class "${name}" has an empty declaration`, suggestion: 'Remove the empty declaration property or add CSS' }); } } } return { ok: true, declaration: declarations.join(' '), warnings }; };