qdr.app.tools/UILayoutDefinitionFormat

UI Layout Definition Format

Version: 1.4
Documentation Version: 1.4
Author: Dalibor Votruba
URL: quadarax.com/ui-layout-def

A comprehensive XML-based format for describing user interface layouts with inheritance, pattern definitions, view organization, external includes, platform-specific extensions, and advanced validation. This format enables cross-platform UI generation with strict validation, modular component libraries, and modern development practices.

Table of Contents

• Overview
• What's New in v1.4
• Core Concepts
• Document Structure
• View Definitions
• Pattern Definitions
• Wireframe Inheritance
• Window Definitions
• External Includes
• Window Includes
• Validation System
• Platform Support
• Advanced Features
• Examples
• Best Practices
• Migration Guide

Overview

The UI Layout Definition Format provides a standardized way to define user interfaces that can be translated to various platforms (Windows Forms, WPF, Avalonia, Qt, Web, Mobile). It emphasizes:

• View-Based Organization: Logical grouping of related UI components by business function
• Separation of Concerns: Pattern definitions separate from usage
• Inheritance: Base wireframes and views with specific overrides
• External Includes: Modular design with external pattern, view, validation, and window files
• Advanced Validation: Comprehensive rule system with custom validators and profiles
• Cross-Platform: Platform-specific control libraries with unified abstractions
• Modern Features: State management, accessibility, performance optimization, testing support

What's New in v1.4

Major Enhancements

1. Advanced State Management

   • Redux and MobX pattern support
   • Hierarchical and concurrent state machines
   • Persistence strategies (session, local, remote, distributed)
   • State transitions with conditions and actions

2. Comprehensive Accessibility Framework

   • WCAG 2.1 AA/AAA compliance tracking
   • Section 508 and ADA support
   • Screen reader optimization
   • Voice control and eye-tracking integration
   • High contrast and magnification support

3. Performance Optimization System

   • Performance metrics and targets
   • Lazy loading and virtualization
   • Memory and CPU monitoring
   • Auto-optimization suggestions
   • Frame rate optimization

4. Security and Data Protection

   • GDPR compliance features
   • Vulnerability protection patterns
   • Data encryption and anonymization
   • Permission-based access control
   • Security audit trails

5. Enhanced Testing Framework

   • Automated test generation
   • Multiple testing strategies (unit, integration, UI, e2e)
   • Accessibility testing automation
   • Performance testing integration
   • Cross-browser compatibility testing

6. Advanced Localization

   • RTL (Right-to-Left) language support
   • Cultural adaptation features
   • Resource bundle management
   • Dynamic language switching
   • Localization quality tracking

7. Modern UI Controls

   • Advanced Avalonia 11.0+ controls
   • Enhanced WinForms .NET 6+ support
   • New Gallery control for customizable item displays with box templates
   • Touch and gesture support
   • Animation and transition systems
   • Responsive design patterns

8. Validation System 2.0

   • Custom validator framework
   • Validation profiles and inheritance
   • Auto-fix suggestions
   • Performance-optimized validation
   • Integration testing for rules

Breaking Changes from v1.2

• Enhanced schema validation requires updates to custom validators
• Some deprecated attributes removed (see migration guide)
• New required accessibility attributes for certain control types
• Updated namespace declarations for external schemas

Schema Validation Status

✅ All schema files and definitions are validated and consistent

• All XSD schema files pass validation
• Pattern definitions (abstract-controls.xml) validate successfully against schemas
• Gallery control integration is fully validated
• Namespace declarations are correct and consistent across all files

Core Concepts

1. View-First Design

Views represent logical business functions (ProductView, OrderView) that group related windows and define shared data context, state management, and behaviors.

2. Patterns-First Design

All controls and structures must be defined in the <patterns> section before use in windows, with comprehensive validation and platform-specific extensions.

3. External Includes

Modular design allows splitting definitions across multiple files:

• Pattern includes for control libraries
• View includes for business logic organization
• Validation includes for rule sets
• Window includes for UI definitions

4. Advanced State Management

Support for modern state management patterns including Redux, MobX, and state machines with persistence and synchronization.

5. Accessibility-First Design

Built-in support for WCAG compliance, screen readers, voice control, and adaptive technologies.

6. Performance Optimization

Integrated performance monitoring, lazy loading, virtualization, and optimization suggestions.

7. Security by Design

Comprehensive security framework with vulnerability protection, data encryption, and audit trails.

Document Structure

<?xml version="1.0" encoding="UTF-8"?>
<ui-layout-def xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="ui-layout-definition ui-layout-def.xsd"
               version="1.4"
               schema-version="1.4"
               target-platform="avalonia"
               accessibility-compliance="wcag-aa">
  
  <!-- Enhanced validation rules with custom validators -->
  <validation-rules>
    <validation-include src="wcag-validation.xml" important="true" />
    <validation-include src="performance-rules.xml" important="true" />
    <validation-include src="security-rules.xml" important="true" />
    <custom-validator name="BusinessRuleValidator">...</custom-validator>
    <validation-profile name="ProductionProfile">...</validation-profile>
  </validation-rules>
  
  <!-- Enhanced pattern definitions -->
  <patterns>
    <pattern-include src="avalonia-controls.xml" important="true" platform="avalonia" />
    <pattern-include src="accessibility-controls.xml" important="true" />
    <pattern-include src="performance-controls.xml" important="false" />
  </patterns>
  
  <!-- Advanced view definitions -->
  <views>
    <view-include src="business-views.xml" important="true" />
    <view name="EnhancedView" type="ai-assisted" category="ai-enhanced">
      <state-management pattern="redux" persistence="distributed" />
      <accessibility level="aaa" tested="true" />
      <performance target-load-time="1000" memory-limit="100MB" />
      <security level="high" audit-required="true" />
      <localization default-culture="en-US" rtl-support="true" />
      <testing coverage-target="95" strategy="e2e" />
    </view>
  </views>
  
  <!-- Window includes with conditional loading -->
  <window-includes>
    <window-include src="main-windows.xml" important="true" />
    <window-include src="accessibility-windows.xml" important="false" />
  </window-includes>
  
  <!-- Enhanced window definitions -->
  <window name="ModernWindow" title="Enhanced Application" 
          target-platform="avalonia" schema-version="1.4">
    <data-binding>
      <data-context source="ModernViewModel" mode="TwoWay" />
    </data-binding>
    <accessibility compliance-level="wcag-aa">
      <screen-reader window-title="Modern Application" />
      <keyboard-navigation focus-trap="true" />
    </accessibility>
    <!-- Window content with modern controls -->
  </window>
  
</ui-layout-def>

Advanced Features

State Management

<view name="ReactiveView" type="real-time" category="analytics">
  <state-management pattern="redux" persistence="distributed">
    <state name="loading" initial="true" data-snapshot="LoadingState" />
    <state name="loaded" final="false" data-snapshot="LoadedState" />
    <transition from="loading" to="loaded" trigger="data-received" 
                condition="data.isValid" action="processData" />
  </state-management>
</view>

Accessibility Framework

<accessibility compliance-level="wcag-aa">
  <compliance standard="wcag" level="aa" verified="true" />
  <feature name="screen-reader" type="screen-reader" required="true" />
  <feature name="voice-control" type="voice-control" required="false" />
  <feature name="high-contrast" type="high-contrast" required="true" />
</accessibility>

Performance Optimization

<performance target-load-time="1000" memory-limit="100MB">
  <metric name="first-contentful-paint" type="load-time" target="800ms" critical="true" />
  <optimization technique="lazy-loading" impact="high" />
  <optimization technique="virtualization" impact="medium" />
</performance>

Security Framework

<security level="high" audit-required="true">
  <permission name="data-read" type="read" required="true" scope="view" />
  <permission name="data-write" type="write" required="false" scope="data" />
  <vulnerability-protection type="xss" protection="input-sanitization" severity="high" />
  <data-protection encryption="true" gdpr-compliant="true" />
</security>

Testing Integration

<testing coverage-target="95" strategy="e2e">
  <test-scenario name="user-login" type="functional" priority="high" automated="true">
    <step action="enter-username" expected="username-field-filled" />
    <step action="enter-password" expected="password-field-filled" />
    <step action="click-login" expected="dashboard-displayed" />
  </test-scenario>
  <automation framework="playwright" selector-strategy="accessibility" />
</testing>

Localization Support

<localization default-culture="en-US" rtl-support="true">
  <supported-culture code="ar-SA" name="Arabic (Saudi Arabia)" completion="85" />
  <supported-culture code="he-IL" name="Hebrew (Israel)" completion="90" />
  <resource-bundle name="MainResources" path="Resources/Main" type="resx" />
</localization>

Platform Support

Enhanced Platform Integration

Avalonia UI 11.0+

• Full Avalonia 11 control set with modern features
• Advanced theming and styling support
• Cross-platform graphics and animations
• Touch and gesture recognition
• Performance optimizations and virtualization

Windows Forms .NET 6+

• Modern .NET 6+ WinForms support
• High DPI awareness and scaling
• Accessibility improvements
• Enhanced data binding
• WebView2 integration

Web Technologies

• Progressive Web App (PWA) support
• Modern CSS Grid and Flexbox layouts
• Web Components architecture
• Accessibility standards compliance
• Performance optimization techniques

Mobile Platforms

• Responsive design patterns
• Touch-first interactions
• Platform-specific optimizations
• Native control integration
• Performance monitoring

Migration Guide

From Version 1.3 to 1.4

Automatic Migration Support

Version 1.4 includes an automatic migration tool that can upgrade most 1.3 documents:

ui-layout-migrate --from 1.3 --to 1.4 --input myapp.xml --output myapp-v14.xml

Required Changes

1. Update Schema References

   <!-- Old -->
   <ui-layout-def version="1.2">
      
   <!-- New -->
   <ui-layout-def version="1.4" schema-version="1.4">
   

2. Add Accessibility Compliance

   <ui-layout-def accessibility-compliance="wcag-aa">
   

3. Update Control Declarations

   • Add schema-version="1.4" to custom controls
   • Update deprecated attribute names
   • Add accessibility attributes where required

4. Enhanced Validation Rules

   • Custom validators need implementation updates
   • New validation profiles should be configured
   • Performance and security rules are now included

Optional Enhancements

1. Add State Management

   <state-management pattern="redux" persistence="session">
   

2. Enable Performance Monitoring

   <performance target-load-time="2000" memory-limit="200MB">
   

3. Configure Testing

   <testing coverage-target="80" strategy="integration">
   

4. Add Localization Support

   <localization default-culture="en-US">
   

Compatibility Matrix

Feature	v1.3	v1.4	Migration Required
Basic Controls	✓	✓	No
Window Includes	✓	✓	No
View Definitions	✓	✓	Optional
State Management	✗	✓	New Feature
Accessibility	Basic	Enhanced	Recommended
Performance	✗	✓	New Feature
Security	Basic	Enhanced	Recommended
Testing	✗	✓	New Feature
Localization	Basic	Enhanced	Optional

Breaking Changes

1. Removed Deprecated Attributes

   • legacy-mode attribute removed
   • compatibility-level replaced with schema-version

2. Enhanced Validation Requirements

   • Accessibility attributes now required for interactive controls
   • Performance targets recommended for data-heavy views

3. Updated Namespace Requirements

   • New namespace imports required for advanced features
   • External schema references updated

Best Practices for Migration

1. Incremental Migration

   • Migrate core functionality first
   • Add advanced features incrementally
   • Test each migration step thoroughly

2. Validation First

   • Run validation before and after migration
   • Address all validation errors before proceeding
   • Use validation profiles for consistent results

3. Testing Integration

   • Add basic test scenarios during migration
   • Implement accessibility testing early
   • Use automated migration testing tools

4. Performance Optimization

   • Profile application performance before migration
   • Set realistic performance targets
   • Monitor improvements after migration

Pattern Definitions

New Gallery Control

The Gallery control is a specialized list control for displaying collections of items in customizable boxes with templates:

<patterns>
  <control name="Gallery" type="list" category="basic" inherits="CommonControl">
    <description>Gallery control for displaying collection of items in customizable boxes with templates</description>
    <constraints>
      <allowed-parents>Panel,SplitPanel,PopupPanel,TabPage</allowed-parents>
      <allowed-children>GalleryItem</allowed-children>
      <container>true</container>
      <requires-structure>gallery-items,box-template</requires-structure>
    </constraints>
    <attributes>
      <!-- Gallery-specific attributes -->
      <attribute name="image-width" type="int" min="16" max="512" default="64" />
      <attribute name="image-height" type="int" min="16" max="512" default="64" />
      <attribute name="box-width" type="int" min="32" max="1024" default="120" />
      <attribute name="box-height" type="int" min="32" max="1024" default="120" />
      <attribute name="paging-enabled" type="bool" default="false" />
      <attribute name="paging-page-size" type="int" min="1" max="1000" default="50" />
    </attributes>
    <structure>
      <gallery-items max-count="unbounded" />
      <box-template required="true" />
    </structure>
  </control>
</patterns>

Gallery Usage Example

<Gallery name="ProductGallery" box-width="150" box-height="180" paging-enabled="true">
  <box-template name="ProductTemplate" width="140" height="170">
    <template-elements>
      <element name="ProductImage" type="image" x="10" y="10" width="120" height="80" data-binding="Image" />
      <element name="ProductName" type="text" x="10" y="100" width="120" height="20" data-binding="Name" font-style="bold" />
      <element name="ProductPrice" type="text" x="10" y="125" width="120" height="15" data-binding="Price" format-string="C2" />
    </template-elements>
  </box-template>
  <items>
    <GalleryItem text="Product 1" image="product1.jpg">
      <data-fields>
        <field name="Name" value="Premium Widget" />
        <field name="Price" value="29.99" />
        <field name="Image" value="images/widget.jpg" />
      </data-fields>
    </GalleryItem>
  </items>
</Gallery>

Enhanced Control Definitions

<patterns>
  <control name="EnhancedTextBox" type="input" category="basic" schema-version="1.4">
    <description>Enhanced text input with validation and accessibility</description>
    <constraints>
      <allowed-parents>Panel,FormField</allowed-parents>
      <allowed-children>none</allowed-children>
      <container>false</container>
      <platform-constraints>
        <platform-constraint platform="avalonia" min-version="11.0" />
      </platform-constraints>
      <performance-hints virtualization-supported="false" memory-intensive="false" />
    </constraints>
    <attributes>
      <attribute name="text" type="string" default="" category="content" />
      <attribute name="placeholder" type="string" default="" category="display" />
      <attribute name="max-length" type="int" default="255" min="1" max="10000" category="validation" />
      <attribute name="validation-pattern" type="string" default="" category="validation" />
      <attribute name="aria-label" type="string" default="" category="accessibility" />
      <attribute name="high-contrast-support" type="bool" default="true" category="accessibility" />
    </attributes>
    <validation>
      <rule name="required-validation" type="required" message="This field is required" severity="error" />
      <rule name="pattern-validation" type="pattern" pattern="{validation-pattern}" message="Invalid format" severity="warning" />
    </validation>
    <accessibility>
      <requirement standard="wcag" level="aa" description="Keyboard accessible input" required="true" />
      <requirement standard="section-508" level="aa" description="Screen reader compatible" required="true" />
    </accessibility>
    <data-binding supports-two-way="true" supports-commands="false" supports-validation="true">
      <bindable-property name="Text" type="string" mode="TwoWay" dependency-property="true" />
      <bindable-property name="IsValid" type="bool" mode="OneWay" default-value="true" />
    </data-binding>
    <behavior>
      <event name="text-changed" async="false" cancelable="false" />
      <event name="validation-error" async="false" accessibility-event="true" />
      <command name="ClearCommand" can-execute-property="HasText" async="false" />
      <gesture name="double-tap" type="double-tap" description="Select all text" />
    </behavior>
  </control>
</patterns>

Custom Validators

<validation-rules>
  <custom-validator name="EmailValidator" version="1.0" category="business-rules">
    <description>Validates email address format</description>
    <implementation>
      <rule-expression expression="matches(@text, '^[^@]+@[^@]+\.[^@]+$')" language="xpath" />
    </implementation>
    <parameter name="allow-empty" type="bool" default-value="false" description="Allow empty email addresses" />
    <test-case name="valid-email" description="Should accept valid email">
      <input>user@example.com</input>
      <expected-result>pass</expected-result>
    </test-case>
    <test-case name="invalid-email" description="Should reject invalid email">
      <input>invalid-email</input>
      <expected-result>fail</expected-result>
      <expected-message>Invalid email format</expected-message>
    </test-case>
  </custom-validator>
  
  <validation-profile name="ProductionProfile" version="1.0" target-platform="avalonia">
    <description>Production-ready validation profile with comprehensive checks</description>
    <profile-rule rule-name="EmailValidator" enabled="true" severity="error" />
    <profile-rule rule-name="AccessibilityValidator" enabled="true" severity="warning" />
    <profile-group group-name="SecurityValidation" enabled="true" override-severity="error" />
    <configuration stop-on-first-error="false" max-errors="50" parallel-execution="true">
      <setting key="strict-mode" value="true" scope="profile" />
      <exclusion pattern="*.test.xml" type="file" reason="Test files excluded from production validation" />
    </configuration>
  </validation-profile>
</validation-rules>

Advanced View Definitions

Modern Business View

<views>
  <view name="ModernProductView" type="ai-assisted" category="ai-enhanced" 
        schema-version="1.4" platform="avalonia" singleton="false" lazy-loading="true">
    <description>AI-enhanced product management with real-time collaboration</description>
    
    <metadata>
      <author>Development Team</author>
      <version>2.1.0</version>
      <created-date>2024-01-15</created-date>
      <documentation-url>https://docs.company.com/product-view</documentation-url>
      <tags>
        <tag>ai-enhanced</tag>
        <tag>real-time</tag>
        <tag>collaborative</tag>
      </tags>
    </metadata>
    
    <state-management pattern="redux" persistence="distributed">
      <state name="initializing" initial="true" data-snapshot="InitState" />
      <state name="loading" final="false" data-snapshot="LoadingState" />
      <state name="ready" final="false" data-snapshot="ReadyState" />
      <state name="error" final="false" data-snapshot="ErrorState" />
      <transition from="initializing" to="loading" trigger="start-load" action="beginLoad" />
      <transition from="loading" to="ready" trigger="load-complete" condition="data.isValid" action="finalizeLoad" />
      <transition from="loading" to="error" trigger="load-failed" action="handleError" />
    </state-management>
    
    <accessibility level="aaa" tested="true">
      <compliance standard="wcag" level="aaa" verified="true" />
      <compliance standard="section-508" level="aa" verified="true" />
      <feature name="screen-reader" type="screen-reader" required="true" implementation="NVDA,JAWS,VoiceOver" />
      <feature name="voice-control" type="voice-control" required="false" implementation="Dragon,Windows Speech" />
      <feature name="high-contrast" type="high-contrast" required="true" />
      <feature name="magnification" type="magnification" required="true" />
    </accessibility>
    
    <performance target-load-time="1000" memory-limit="100MB">
      <metric name="first-contentful-paint" type="load-time" target="800ms" critical="true" />
      <metric name="memory-usage" type="memory-usage" target="50MB" critical="false" />
      <optimization technique="lazy-loading" description="Load product data on demand" impact="high" />
      <optimization technique="virtualization" description="Virtualize large product lists" impact="medium" />
    </performance>
    
    <security level="high" audit-required="true">
      <permission name="product-read" type="read" required="true" scope="view" />
      <permission name="product-write" type="write" required="false" scope="data" />
      <permission name="product-admin" type="admin" required="false" scope="global" />
      <vulnerability-protection type="xss" protection="input-sanitization" severity="high" />
      <vulnerability-protection type="injection" protection="parameterized-queries" severity="critical" />
      <data-protection encryption="true" gdpr-compliant="true" />
    </security>
    
    <localization default-culture="en-US" rtl-support="true">
      <supported-culture code="ar-SA" name="Arabic (Saudi Arabia)" completion="85" verified="false" />
      <supported-culture code="he-IL" name="Hebrew (Israel)" completion="90" verified="true" />
      <supported-culture code="zh-CN" name="Chinese (Simplified)" completion="95" verified="true" />
      <resource-bundle name="ProductResources" path="Resources/Products" type="resx" />
      <resource-bundle name="CommonResources" path="Resources/Common" type="json" />
    </localization>
    
    <testing coverage-target="95" strategy="e2e">
      <test-scenario name="create-product" type="functional" priority="high" automated="true">
        <step action="click-new-product" expected="product-form-displayed" />
        <step action="enter-product-name" data="Test Product" expected="name-field-filled" />
        <step action="click-save" expected="product-saved-successfully" />
      </test-scenario>
      <test-scenario name="accessibility-navigation" type="accessibility" priority="high" automated="true">
        <step action="tab-navigation" expected="all-controls-reachable" />
        <step action="screen-reader-test" expected="proper-announcements" />
      </test-scenario>
      <automation framework="playwright" selector-strategy="accessibility" page-object-model="true" />
    </testing>
    
    <dependencies>
      <service-ref name="ProductService" interface="IProductService" scope="scoped" required="true" />
      <service-ref name="AIRecommendationService" interface="IAIService" scope="singleton" required="false" />
      <library-ref name="ChartingLibrary" version="2.1.0" source="nuget" optional="false" />
    </dependencies>
    
    <communication>
      <real-time>
        <connection name="product-updates" protocol="signalr" endpoint="/productHub" auto-reconnect="true" />
      </real-time>
    </communication>
  </view>
</views>

---

This format specification v1.4 enables modern, accessible, performant, and secure cross-platform UI definitions with advanced development practices, comprehensive validation, and state-of-the-art tooling support.