@sap/ux-specification 1.84.129 → 1.84.131

package/dist/specification/test/unit/decorators/validity-test-utils.d.ts

@@ -0,0 +1,274 @@
+/**
+ * @file Test utilities for validating @validity decorator behavior
+ *
+ * This module provides helper functions for:
+ * - Extracting validity metadata from decorated classes
+ * - Generating expected vs actual visibility tables
+ * - Comparing property visibility across UI5 versions
+ * - Formatting results as markdown for snapshot testing
+ */
+import type { Definition } from 'typescript-json-schema';
+/** Emoji indicator for a visible/available property */
+export declare const EMOJI_VISIBLE = "\u2705";
+/** Emoji indicator for a hidden/unavailable property */
+export declare const EMOJI_HIDDEN = "\uD83D\uDEAB";
+/** Emoji indicator for property not found in schema */
+export declare const EMOJI_NOT_FOUND = "\u2753";
+/**
+ * Enum to specify which type of visibility table to generate
+ */
+export declare enum SchemaResults {
+    /** Generate expected visibility based on @validity decorator metadata */
+    Expected = "expected",
+    /** Generate actual visibility from generated schemas */
+    Actual = "actual"
+}
+/**
+ * Information about a property with a @validity decorator
+ */
+export interface ValidityInfo {
+    /** The property name */
+    property: string;
+    /** The UI5 version since which the property is available */
+    since: string;
+}
+/**
+ * A row in the version visibility table showing property availability across versions
+ */
+export interface VersionVisibilityRow {
+    /** The property name */
+    property: string;
+    /** The UI5 version since which the property is available */
+    since: string;
+    /** Dynamic keys for each version (e.g., '1.84.0': '✅') */
+    [version: string]: string;
+}
+/**
+ * Function type for finding a specific definition within a schema
+ */
+export type DefinitionFinder = (schema: Definition) => Definition | undefined;
+/**
+ * Resolves a definition by following $ref chains in the schema
+ *
+ * @param schema - The JSON schema containing definitions
+ * @param definitionName - The name of the definition to resolve
+ * @returns The resolved definition, or undefined if not found
+ * @example
+ * const tableDef = resolveDefinition(schema, 'Table');
+ */
+export declare function resolveDefinition(schema: Definition, definitionName: string): Definition | undefined;
+/**
+ * Finds the definition containing table properties by searching common patterns
+ *
+ * Searches for definitions with names like 'TableSPV', 'LRTableView', 'Table',
+ * or any definition containing key table properties like 'condensedTableLayout'.
+ *
+ * @param schema - The JSON schema to search
+ * @returns The table definition, or undefined if not found
+ */
+export declare function findTableDefinition(schema: Definition): Definition | undefined;
+/**
+ * Creates a definition finder function for a specific definition name
+ *
+ * @param definitionName - The name of the definition to find
+ * @returns A function that finds the definition in a given schema
+ * @example
+ * const finder = findDefinitionByName('CustomHeaderAction');
+ * const def = finder(schema);
+ */
+export declare function findDefinitionByName(definitionName: string): DefinitionFinder;
+/**
+ * Gets all property names from a schema definition
+ *
+ * @param schema - The JSON schema containing definitions
+ * @param definitionName - The name of the definition to get properties from
+ * @returns Array of property names, or empty array if definition not found
+ */
+export declare function getSchemaPropertyNames(schema: Definition, definitionName: string): string[];
+/**
+ * Checks if a property exists in a schema definition
+ *
+ * @param schema - The JSON schema containing definitions
+ * @param definitionName - The name of the definition to check
+ * @param propertyName - The name of the property to check for
+ * @returns True if the property exists, false otherwise
+ */
+export declare function propertyExists(schema: Definition, definitionName: string, propertyName: string): boolean;
+/**
+ * Checks if a property is marked as hidden in a schema definition
+ *
+ * @param schema - The JSON schema containing definitions
+ * @param definitionName - The name of the definition to check
+ * @param propertyName - The name of the property to check
+ * @returns True if hidden, false if visible, undefined if property not found
+ */
+export declare function isPropertyHidden(schema: Definition, definitionName: string, propertyName: string): boolean | undefined;
+/** Special version string representing the latest/newest version */
+export declare const VERSION_LATEST = "latest";
+/**
+ * Compares two semantic version strings
+ *
+ * Handles the special 'latest' version which is always considered
+ * greater than any other version.
+ *
+ * @param a - First version string (e.g., '1.84.0' or 'latest')
+ * @param b - Second version string (e.g., '1.96.0' or 'latest')
+ * @returns Negative if a < b, positive if a > b, zero if equal
+ * @example
+ * compareVersions('1.84.0', '1.96.0') // returns negative
+ * compareVersions('1.96.0', '1.84.0') // returns positive
+ * compareVersions('1.84.0', '1.84.0') // returns 0
+ * compareVersions('1.142.0', 'latest') // returns negative
+ * compareVersions('latest', '1.84.0') // returns positive
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Extracts all properties from a class, including those with @validity decorator
+ *
+ * Walks the prototype chain to find all properties, then checks each
+ * for validity metadata. Properties without @validity are marked with since: '-'.
+ * Results are sorted by version (ascending), then alphabetically by property name.
+ *
+ * @param ClassConstructor - The class constructor to inspect
+ * @param schemaPropertyNames - Optional list of additional property names to check
+ * @param onlyWithValidity - If true, only return properties with @validity decorator (default: false)
+ * @returns Array of ValidityInfo objects sorted by version then name
+ * @example
+ * const validityProps = getValidityPropertiesFromClass(TableSettings, ['type', 'selectAll']);
+ * // Returns: [{ property: 'enableOnSelect', since: '-' }, { property: 'type', since: '1.84.0' }, ...]
+ */
+export declare function getValidityPropertiesFromClass(ClassConstructor: new () => object, schemaPropertyNames?: string[], onlyWithValidity?: boolean): ValidityInfo[];
+/**
+ * Generates expected visibility table based on @validity decorator metadata
+ *
+ * For each property, determines if it should be visible in each version
+ * based on comparing the version against the property's 'since' value.
+ * Properties with since: '-' (no @validity) are always visible.
+ *
+ * @param validityInfos - Array of properties with their validity info
+ * @param versions - Array of version strings to generate columns for
+ * @returns Array of rows with visibility status for each version
+ */
+export declare function generateExpectedVisibilityTable(validityInfos: ValidityInfo[], versions: string[]): VersionVisibilityRow[];
+/**
+ * Generates actual visibility table from generated schemas
+ *
+ * For each property and version, checks the actual generated schema
+ * to determine if the property is visible (not hidden).
+ *
+ * @param validityInfos - Array of properties with their validity info
+ * @param versions - Array of version strings to check
+ * @param schemaResults - Map of version strings to generated schemas
+ * @param findDefinition - Function to locate the definition within each schema
+ * @returns Array of rows with actual visibility status for each version
+ * @remarks
+ * Status symbols:
+ * - ✅ = property exists and is visible
+ * - 🚫 = property exists but is hidden
+ * - ? = schema or definition not found
+ * - - = property not found in definition
+ */
+export declare function generateActualVisibilityTable(validityInfos: ValidityInfo[], versions: string[], schemaResults: Map<string, Definition>, findDefinition: DefinitionFinder): VersionVisibilityRow[];
+/**
+ * Formats visibility table as a markdown string for snapshot testing
+ *
+ * Generates a properly aligned markdown table with:
+ * - Header row with Property, Since, and version columns
+ * - Separator row
+ * - Data rows with centered emoji indicators
+ * - Legend explaining the emoji meanings
+ *
+ * @param rows - Array of visibility rows to format
+ * @param versions - Array of version strings for column headers
+ * @returns Formatted markdown table string
+ * @example
+ * ```
+ * | Property | Since  | 1.84.0 | 1.96.0 |
+ * | -------- | ------ | ------ | ------ |
+ * | type     | 1.84.0 |   ✅   |   ✅   |
+ *
+ * Legend: ✅ = visible, 🚫 = hidden
+ * ```
+ */
+export declare function formatVisibilityTableMarkdown(rows: VersionVisibilityRow[], versions: string[]): string;
+/**
+ * Generates an app schema with a specific minUI5Version
+ *
+ * Creates a schema for the v4new test project with the specified
+ * UI5 version, using the provided generic schema as base.
+ *
+ * @param genericSchema - The generic schema to use as base
+ * @param minUI5Version - The minimum UI5 version to set (e.g., '1.84.0')
+ * @returns The generated app schema
+ */
+export declare function generateSchemaWithVersion(genericSchema: Definition, minUI5Version: string): Promise<Definition>;
+/**
+ * Generates schemas for multiple UI5 versions
+ *
+ * @param genericSchema - The generic schema to use as base for all versions
+ * @param versions - Array of version strings to generate schemas for
+ * @returns Map of version string to generated schema
+ * @example
+ * const schemas = await generateSchemasForVersions(genericSchema, ['1.84.0', '1.96.0']);
+ * const schema84 = schemas.get('1.84.0');
+ */
+export declare function generateSchemasForVersions(genericSchema: Definition, versions: string[]): Promise<Map<string, Definition>>;
+/**
+ * Gets validity properties for a class from a generic schema
+ *
+ * Combines schema property names with validity decorator metadata
+ * to get complete validity information for testing.
+ *
+ * @param genericSchema - The generic schema containing the definition
+ * @param classRef - The class constructor to extract validity metadata from
+ * @param schemaName - Optional schema definition name (defaults to class name)
+ * @returns Array of ValidityInfo objects
+ */
+export declare function getValidityProperties(genericSchema: Definition, classRef: new () => object, schemaName?: string): ValidityInfo[];
+/**
+ * Generates a markdown visibility table for a decorated class
+ *
+ * @param config - Configuration object with classRef and optional schemaName
+ * @param config.classRef - The class constructor containing @validity decorators
+ * @param config.schemaName - Optional schema definition name (defaults to class name)
+ * @param schemaType - Whether to generate expected or actual visibility
+ * @param context - Test context containing genericSchema, versions, and schemaResults
+ * @returns Formatted markdown table string
+ */
+export declare const getPropertiesWithValidity: ({ classRef, schemaName }: {
+    classRef: new () => object;
+    schemaName?: string;
+}, schemaType: SchemaResults, { genericSchema, versions, schemaResults }: {
+    genericSchema: any;
+    versions: any;
+    schemaResults: any;
+}) => string;
+/** Emoji indicator for a difference between expected and actual */
+export declare const EMOJI_DIFF = "\u26A0\uFE0F";
+/** Emoji indicator for match between expected and actual */
+export declare const EMOJI_MATCH = "\u2705";
+/**
+ * Generates a diff table comparing expected vs actual visibility
+ *
+ * For each property and version, compares expected (from @validity metadata)
+ * vs actual (from generated schema) and highlights differences.
+ *
+ * @param validityInfos - Array of properties with their validity info
+ * @param versions - Array of version strings to check
+ * @param schemaResults - Map of version strings to generated schemas
+ * @param findDefinition - Function to locate the definition within each schema
+ * @returns Array of rows showing expected vs actual comparison per version
+ */
+export declare function generateDiffVisibilityTable(validityInfos: ValidityInfo[], versions: string[], schemaResults: Map<string, Definition>, findDefinition: DefinitionFinder): VersionVisibilityRow[];
+/**
+ * Formats diff table as a markdown string for snapshot testing
+ *
+ * Shows which property/version combinations have mismatches between
+ * expected (decorator metadata) and actual (generated schema) visibility.
+ *
+ * @param rows - Array of diff rows to format
+ * @param versions - Array of version strings for column headers
+ * @returns Formatted markdown table string with diff indicators
+ */
+export declare function formatDiffTableMarkdown(rows: VersionVisibilityRow[], versions: string[]): string;
+//# sourceMappingURL=validity-test-utils.d.ts.map

package/dist/specification/test/unit/decorators/validity-test-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validity-test-utils.d.ts","sourceRoot":"","sources":["../../../../../test/unit/decorators/validity-test-utils.ts"],"names":[],"mappings":"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"}