Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 | /**
* @fds-uif/core - Type Definitions
*
* Shared types for UIF processing utilities.
*/
import type { MARKER_AFTER, MARKER_BEFORE, MARKER_REMOVE, MARKER_WRAP } from './constants.js';
/** A plain JavaScript object */
export type PlainObject = Record<string, unknown>;
/** Item with a $remove marker */
export interface RemoveMarkerItem {
[MARKER_REMOVE]: true;
[key: string]: unknown;
}
/** Item with a $before marker */
export interface BeforeMarkerItem {
[MARKER_BEFORE]: string;
[key: string]: unknown;
}
/** Item with an $after marker */
export interface AfterMarkerItem {
[MARKER_AFTER]: string;
[key: string]: unknown;
}
/** Item with a $wrap marker — wraps named siblings inside this node */
export interface WrapMarkerItem {
[MARKER_WRAP]: string[];
[key: string]: unknown;
}
/** Union of all marker item types */
export type MarkerItem = RemoveMarkerItem | BeforeMarkerItem | AfterMarkerItem | WrapMarkerItem;
/** UIF definition with potential extends property */
export interface UifWithExtends {
extends?: string;
[key: string]: unknown;
}
/**
* Warning handler function signature.
* Called when non-fatal issues occur during processing.
*/
export type WarningHandler = (message: string, context: WarningContext) => void;
/** Context provided to warning handlers */
export interface WarningContext {
/** The type of warning */
type: 'positional-marker-not-found' | 'unknown';
/** Path to the location of the issue */
path: string;
/** Additional details */
details?: Record<string, unknown>;
}
/**
* Options for merge operations.
*/
export interface MergeOptions {
/**
* Handler for warnings during merge.
* If not provided, warnings are silently ignored.
* For development, you can use `console.warn` as the handler.
*
* @example
* ```ts
* merge(base, ext, { onWarning: console.warn });
* ```
*/
onWarning?: WarningHandler;
}
/**
* Options for resolving UIF extensions.
*/
export interface ResolveOptions extends MergeOptions {
/**
* Custom file loader function.
* Defaults to using Node.js fs module.
* Useful for testing, caching, or custom file resolution.
*/
loadFile?: (path: string) => Promise<string>;
/**
* Base directory for resolving relative paths.
* Required when the input is an object rather than a file path.
*/
basePath?: string;
/**
* Enable caching of resolved files.
* When true, files that have already been loaded and parsed
* will be reused from cache.
* @default false
*/
cache?: boolean | Map<string, PlainObject>;
}
// ============================================================================
// Validation Types
// ============================================================================
/**
* Individual validation error.
*/
export interface ValidationError {
/** Error code for programmatic handling */
code: string;
/** Human-readable error message */
message: string;
/** JSON path where the error occurred */
path: string;
/** Severity level */
severity: 'error' | 'warning';
/** Optional suggestions for fixing the error */
suggestion?: string;
/** Additional context data */
details?: Record<string, unknown>;
}
/**
* Result of comprehensive UIF validation.
*/
export interface ValidationResult {
/** Whether validation passed (no errors, warnings may exist) */
valid: boolean;
/** Validation errors (must be fixed) */
errors: ValidationError[];
/** Validation warnings (should be reviewed) */
warnings: ValidationError[];
}
/**
* Options for UIF validation.
*/
export interface ValidationOptions {
/**
* Whether to check state references in stateClasses.
* @default true
*/
checkStateReferences?: boolean;
/**
* Whether to check for variant conflicts.
* @default true
*/
checkVariantConflicts?: boolean;
/**
* Whether to check for duplicate identifiers.
* @default true
*/
checkIdentifiers?: boolean;
/**
* Whether to include warnings in the result.
* @default true
*/
includeWarnings?: boolean;
/**
* Whether to validate `extensions` structural integrity.
* @default true
*/
checkExtensions?: boolean;
}
// ============================================================================
// Variant Types for Validation
// ============================================================================
// These types are intentionally defined here (not imported from @fds-uif/schema)
// because validation operates on unknown input and needs flexible types with
// index signatures. The schema types are stricter and meant for resolved UIFs.
/**
* Type for variant options that may include structural changes.
* Used during validation of unknown input.
*/
export interface VariantOption {
value: string;
class?: string;
children?: Array<VariantChildChange>;
slots?: Record<string, boolean>;
restrict?: string[];
[key: string]: unknown;
}
/**
* Child modification in a variant option.
* Used during validation of unknown input.
*/
export interface VariantChildChange {
name: string;
restrict?: string[];
slots?: Record<string, boolean>;
[key: string]: unknown;
}
/**
* Variant definition with options.
* Used during validation of unknown input.
*/
export interface Variant {
name: string;
options: VariantOption[];
[key: string]: unknown;
}
|