@safe-ugc-ui/validator 0.3.1 → 0.5.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' | 'EXPR_NOT_ALLOWED' | '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' | 'EXPR_TOO_LONG' | 'REF_TOO_LONG' | 'EXPR_TOO_MANY_TOKENS' | 'EXPR_NESTING_TOO_DEEP' | 'EXPR_CONDITION_NESTING_TOO_DEEP' | 'EXPR_REF_DEPTH_EXCEEDED' | 'EXPR_ARRAY_INDEX_EXCEEDED' | 'EXPR_STRING_LITERAL_TOO_LONG' | 'EXPR_FORBIDDEN_TOKEN' | 'EXPR_FUNCTION_CALL' | 'EXPR_INVALID_TOKEN' | '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' | 'INVALID_HOVER_STYLE' | 'HOVER_STYLE_NESTED' | 'TRANSITION_RAW_STRING' | 'TRANSITION_COUNT_EXCEEDED' | 'TRANSITION_PROPERTY_FORBIDDEN';
 /**
  * A single validation error with location and diagnostic info.
  */
@@ -101,7 +101,6 @@ interface TraversableNode {
     type: string;
     children?: TraversableNode[] | ForLoopLike;
     style?: Record<string, unknown>;
-    condition?: unknown;
     [key: string]: unknown;
 }
 interface ForLoopLike {
@@ -182,29 +181,29 @@ declare function validateNodes(views: Record<string, unknown>): ValidationError[
 /**
  * @safe-ugc-ui/validator — Value Type Validation
  *
- * Validates per-property $ref / $expr permission rules based on spec
+ * Validates per-property $ref permission rules based on spec
  * section 4.5 value type table.
  *
- * | Property Type     | Literal | $ref | $expr |
- * |-------------------|---------|------|-------|
- * | Image.src         |   yes   | yes  |  no   |
- * | Avatar.src        |   yes   | yes  |  no   |
- * | Icon.name         |   yes   |  no  |  no   |
- * | Text.content      |   yes   | yes  | yes   |
- * | Color properties  |   yes   | yes  | yes   |
- * | Size properties   |   yes   | yes  | yes   |
- * | position          |   yes   |  no  |  no   |
- * | transform         |   yes   |  no  |  no   |
- * | gradient          |   yes   |  no  |  no   |
- *
- * Additionally, several style properties must always be static
- * (no $ref or $expr): overflow, border*, boxShadow, zIndex,
- * and position offset properties (top/right/bottom/left).
+ * | Property Type     | Literal | $ref |
+ * |-------------------|---------|------|
+ * | Image.src         |   yes   | yes  |
+ * | Avatar.src        |   yes   | yes  |
+ * | Icon.name         |   yes   | yes  |
+ * | Text.content      |   yes   | yes  |
+ * | Color properties  |   yes   | yes  |
+ * | Size properties   |   yes   | yes  |
+ * | position          |   yes   |  no  |
+ * | overflow          |   yes   |  no  |
+ * | zIndex            |   yes   |  no  |
+ * | structured style objects | object literal | top-level $ref no |
+ *
+ * Structured style objects such as border/transform/boxShadow/textShadow/backgroundGradient
+ * must remain object literals, but selected leaf fields inside them may use $ref.
  */
 
 /**
  * Walk all nodes in the card and validate that each field's value
- * respects its allowed value types ($ref / $expr permissions).
+ * respects its allowed value types ($ref permissions).
  *
  * @param views - The `views` object from a UGCCard.
  * @returns An array of validation errors (empty if all values are valid).
@@ -217,6 +216,7 @@ declare function validateValueTypes(views: Record<string, unknown>): ValidationE
  * Validates style properties according to the spec's style restrictions:
  *   - Forbidden CSS properties (spec 3.8)
  *   - Numeric range limits (spec 6.4)
+ *   - Text-shadow count and value limits
  *   - Box-shadow count and value limits
  *   - Transform skew prohibition
  *   - Dangerous CSS function injection detection
@@ -310,28 +310,6 @@ declare function validateLimits(card: {
     cardStyles?: Record<string, Record<string, unknown>>;
 }): ValidationError[];
 
-/**
- * @safe-ugc-ui/validator -- Expression & Reference Constraint Validation
- *
- * Validates $expr and $ref values found in the card tree against the
- * constraints defined in the spec's "expression constraint" section (6.3).
- *
- * A simple tokenizer splits expression strings into typed tokens so that
- * structural limits (nesting, token count, forbidden operators) can be
- * checked without executing the expression.
- */
-
-/**
- * Validates all $expr and $ref values found in the card's views.
- *
- * Uses tree traversal to visit every node, then deep-scans each node's
- * flattened node fields and `style` (and `condition`) for dynamic values.
- *
- * @param views - The `views` object from a UGCCard.
- * @returns An array of validation errors (empty if all constraints pass).
- */
-declare function validateExprConstraints(views: Record<string, unknown>): ValidationError[];
-
 /**
  * @safe-ugc-ui/validator — Public API
  *
@@ -349,7 +327,7 @@ declare function validateExprConstraints(views: Record<string, unknown>): Valida
  *   2. (validateRaw only) JSON.parse — parse error → ValidationResult
  *   3. Schema validation → fail → early return
  *   4. All remaining checks run, errors accumulated:
- *      node → value-types → style → security → limits → expr-constraints
+ *      node → value-types → style → security → limits
  */
 
 /**
@@ -359,7 +337,7 @@ declare function validateExprConstraints(views: Record<string, unknown>): Valida
  *
  * Pipeline:
  *   1. Schema validation → fail → early return
- *   2. All remaining checks (node, value-types, style, security, limits, expr)
+ *   2. All remaining checks (node, value-types, style, security, limits)
  *
  * @param input - An unknown value (typically parsed JSON).
  * @returns A ValidationResult — safe to render only if `valid` is true.
@@ -382,4 +360,4 @@ declare function validate(input: unknown): ValidationResult;
  */
 declare function validateRaw(rawJson: string): ValidationResult;
 
-export { type NodeVisitor, type TraversableNode, type TraversalContext, type ValidationError, type ValidationErrorCode, type ValidationResult, createError, invalidResult, merge, parseCard, toResult, traverseCard, traverseNode, validResult, validate, validateExprConstraints, validateLimits, validateNodes, validateRaw, validateSchema, validateSecurity, validateStyles, validateValueTypes };
+export { type NodeVisitor, 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 };