@safe-ugc-ui/validator 0.6.0 → 1.0.0

package/dist/index.d.ts

@@ -14,7 +14,7 @@ import { UGCCard } from '@safe-ugc-ui/types';
 /**
  * Machine-readable error codes for every validation failure type.
  */
-type ValidationErrorCode = 'INVALID_JSON' | 'MISSING_FIELD' | 'INVALID_TYPE' | 'INVALID_VALUE' | 'UNKNOWN_NODE_TYPE' | 'SCHEMA_ERROR' | 'REF_NOT_ALLOWED' | 'DYNAMIC_NOT_ALLOWED' | 'FORBIDDEN_STYLE_PROPERTY' | 'STYLE_VALUE_OUT_OF_RANGE' | 'FORBIDDEN_CSS_FUNCTION' | 'INVALID_COLOR' | 'INVALID_LENGTH' | 'FORBIDDEN_OVERFLOW_VALUE' | 'TRANSFORM_SKEW_FORBIDDEN' | 'EXTERNAL_URL' | 'POSITION_FIXED_FORBIDDEN' | 'POSITION_STICKY_FORBIDDEN' | 'POSITION_ABSOLUTE_NOT_IN_STACK' | 'ASSET_PATH_TRAVERSAL' | 'INVALID_ASSET_PATH' | 'PROTOTYPE_POLLUTION' | 'CARD_SIZE_EXCEEDED' | 'TEXT_CONTENT_SIZE_EXCEEDED' | 'STYLE_SIZE_EXCEEDED' | 'NODE_COUNT_EXCEEDED' | 'LOOP_ITERATIONS_EXCEEDED' | 'NESTED_LOOPS_EXCEEDED' | 'OVERFLOW_AUTO_COUNT_EXCEEDED' | 'OVERFLOW_AUTO_NESTED' | 'STACK_NESTING_EXCEEDED' | 'LOOP_SOURCE_NOT_ARRAY' | 'LOOP_SOURCE_MISSING' | 'STYLE_CIRCULAR_REF' | 'STYLE_REF_NOT_FOUND' | 'INVALID_STYLE_REF' | 'INVALID_STYLE_NAME' | 'INVALID_HOVER_STYLE' | 'HOVER_STYLE_NESTED' | 'TRANSITION_RAW_STRING' | 'TRANSITION_COUNT_EXCEEDED' | 'TRANSITION_PROPERTY_FORBIDDEN';
+type ValidationErrorCode = 'INVALID_JSON' | 'MISSING_FIELD' | 'INVALID_TYPE' | 'INVALID_VALUE' | 'UNKNOWN_NODE_TYPE' | 'SCHEMA_ERROR' | 'REF_NOT_ALLOWED' | 'DYNAMIC_NOT_ALLOWED' | 'FORBIDDEN_STYLE_PROPERTY' | 'STYLE_VALUE_OUT_OF_RANGE' | 'FORBIDDEN_CSS_FUNCTION' | 'INVALID_COLOR' | 'INVALID_LENGTH' | 'FORBIDDEN_OVERFLOW_VALUE' | 'TRANSFORM_SKEW_FORBIDDEN' | 'EXTERNAL_URL' | 'POSITION_FIXED_FORBIDDEN' | 'POSITION_STICKY_FORBIDDEN' | 'POSITION_ABSOLUTE_NOT_IN_STACK' | 'ASSET_PATH_TRAVERSAL' | 'INVALID_ASSET_PATH' | 'PROTOTYPE_POLLUTION' | 'CARD_SIZE_EXCEEDED' | 'TEXT_CONTENT_SIZE_EXCEEDED' | 'STYLE_SIZE_EXCEEDED' | 'NODE_COUNT_EXCEEDED' | 'LOOP_ITERATIONS_EXCEEDED' | 'NESTED_LOOPS_EXCEEDED' | 'OVERFLOW_AUTO_COUNT_EXCEEDED' | 'OVERFLOW_AUTO_NESTED' | 'STACK_NESTING_EXCEEDED' | 'LOOP_SOURCE_NOT_ARRAY' | 'LOOP_SOURCE_MISSING' | 'STYLE_CIRCULAR_REF' | 'STYLE_REF_NOT_FOUND' | 'INVALID_STYLE_REF' | 'INVALID_STYLE_NAME' | 'FRAGMENT_REF_NOT_FOUND' | 'FRAGMENT_NESTED_USE' | 'INVALID_FRAGMENT_NAME' | 'INVALID_HOVER_STYLE' | 'HOVER_STYLE_NESTED' | 'TRANSITION_RAW_STRING' | 'TRANSITION_COUNT_EXCEEDED' | 'TRANSITION_PROPERTY_FORBIDDEN' | 'CONDITION_DEPTH_EXCEEDED';
 /**
  * A single validation error with location and diagnostic info.
  */
@@ -99,15 +99,21 @@ interface TraversalContext {
  */
 interface TraversableNode {
     type: string;
-    children?: TraversableNode[] | ForLoopLike;
+    children?: TraversableRenderable[] | ForLoopLike;
     style?: Record<string, unknown>;
     responsive?: Record<string, unknown>;
     [key: string]: unknown;
 }
+interface FragmentUseLike {
+    $use: string;
+    $if?: unknown;
+    [key: string]: unknown;
+}
+type TraversableRenderable = TraversableNode | FragmentUseLike;
 interface ForLoopLike {
     for: string;
     in: string;
-    template: TraversableNode;
+    template: TraversableRenderable;
 }
 /**
  * A visitor function called for every node in the tree.
@@ -118,14 +124,14 @@ type StyleResolver = (node: TraversableNode) => Record<string, unknown> | undefi
 /**
  * Recursively traverse a single node and its descendants.
  */
-declare function traverseNode(node: TraversableNode, context: TraversalContext, visitor: NodeVisitor, styleResolver?: StyleResolver): void;
+declare function traverseNode(node: TraversableRenderable, context: TraversalContext, visitor: NodeVisitor, styleResolver?: StyleResolver, fragments?: Record<string, unknown>, fragmentStack?: string[]): void;
 /**
  * Traverse all nodes in every view of a card.
  *
  * @param views - The `views` object from a UGCCard (mapping view names to root nodes).
  * @param visitor - Called for every node in every view.
  */
-declare function traverseCard(views: Record<string, unknown>, visitor: NodeVisitor, styleResolver?: StyleResolver): void;
+declare function traverseCard(views: Record<string, unknown>, visitor: NodeVisitor, styleResolver?: StyleResolver, fragments?: Record<string, unknown>, pathPrefix?: string): void;
 
 /**
  * @safe-ugc-ui/validator — Schema (Structural) Validation
@@ -156,6 +162,14 @@ declare function validateSchema(input: unknown): ValidationResult;
  */
 declare function parseCard(input: unknown): UGCCard | null;
 
+/**
+ * @safe-ugc-ui/validator — Fragment Validator
+ *
+ * Validates fragment references and the non-recursive fragment rules for v0.9.
+ */
+
+declare function validateFragments(views: Record<string, unknown>, fragments?: Record<string, unknown>): ValidationError[];
+
 /**
  * @safe-ugc-ui/validator — Node Validator
  *
@@ -178,7 +192,16 @@ declare function parseCard(input: unknown): UGCCard | null;
  * @param views - The `views` object from a UGCCard.
  * @returns An array of validation errors (empty if all nodes are valid).
  */
-declare function validateNodes(views: Record<string, unknown>): ValidationError[];
+declare function validateNodes(views: Record<string, unknown>, fragments?: Record<string, unknown>): ValidationError[];
+
+/**
+ * @safe-ugc-ui/validator — Condition Validator
+ *
+ * Validates node-level `$if` conditions that are structurally accepted by the
+ * schema but still need semantic guardrails such as maximum nesting depth.
+ */
+
+declare function validateConditions(views: Record<string, unknown>, fragments?: Record<string, unknown>): ValidationError[];
 
 /**
  * @safe-ugc-ui/validator — Value Type Validation
@@ -210,7 +233,7 @@ declare function validateNodes(views: Record<string, unknown>): ValidationError[
  * @param views - The `views` object from a UGCCard.
  * @returns An array of validation errors (empty if all values are valid).
  */
-declare function validateValueTypes(views: Record<string, unknown>): ValidationError[];
+declare function validateValueTypes(views: Record<string, unknown>, fragments?: Record<string, unknown>): ValidationError[];
 
 /**
  * @safe-ugc-ui/validator — Style Validator
@@ -243,7 +266,7 @@ declare function validateValueTypes(views: Record<string, unknown>): ValidationE
  *   9. Range checks on string length values
  *  10. $style reference validation and merging
  */
-declare function validateStyles(views: Record<string, unknown>, cardStyles?: Record<string, Record<string, unknown>>): ValidationError[];
+declare function validateStyles(views: Record<string, unknown>, cardStyles?: Record<string, Record<string, unknown>>, fragments?: Record<string, unknown>): ValidationError[];
 
 /**
  * @safe-ugc-ui/validator — Security Validation
@@ -278,6 +301,7 @@ declare function validateSecurity(card: {
     state?: Record<string, unknown>;
     cardAssets?: Record<string, string>;
     cardStyles?: Record<string, Record<string, unknown>>;
+    fragments?: Record<string, unknown>;
 }): ValidationError[];
 
 /**
@@ -310,6 +334,7 @@ declare function validateLimits(card: {
     state?: Record<string, unknown>;
     views: Record<string, unknown>;
     cardStyles?: Record<string, Record<string, unknown>>;
+    fragments?: Record<string, unknown>;
 }): ValidationError[];
 
 /**
@@ -362,4 +387,4 @@ declare function validate(input: unknown): ValidationResult;
  */
 declare function validateRaw(rawJson: string): ValidationResult;
 
-export { type NodeVisitor, type StyleResolver, type TraversableNode, type TraversalContext, type ValidationError, type ValidationErrorCode, type ValidationResult, createError, invalidResult, merge, parseCard, toResult, traverseCard, traverseNode, validResult, validate, validateLimits, validateNodes, validateRaw, validateSchema, validateSecurity, validateStyles, validateValueTypes };
+export { type NodeVisitor, type StyleResolver, type TraversableNode, type TraversalContext, type ValidationError, type ValidationErrorCode, type ValidationResult, createError, invalidResult, merge, parseCard, toResult, traverseCard, traverseNode, validResult, validate, validateConditions, validateFragments, validateLimits, validateNodes, validateRaw, validateSchema, validateSecurity, validateStyles, validateValueTypes };