@safe-ugc-ui/validator 0.3.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Safe UGC UI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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/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).
@@ -310,28 +309,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 +326,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 +336,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 +359,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 };