# UI Layout Definition Format

**Version:** 1.2  
**Documentation Version:** 1.2  
**Author:** Dalibor Votruba  
**URL:** [quadarax.com/ui-layout-def](https://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, data binding, and accessibility support. This format enables cross-platform UI generation with strict validation and modular component libraries.

## Table of Contents

- [Overview](#overview)
- [What's New in v1.2](#whats-new-in-v12)
- [Core Concepts](#core-concepts)
- [Document Structure](#document-structure)
- [View Definitions](#view-definitions)
- [Pattern Definitions](#pattern-definitions)
- [Data Binding Support](#data-binding-support)
- [Accessibility Features](#accessibility-features)
- [Wireframe Inheritance](#wireframe-inheritance)
- [Window Definitions](#window-definitions)
- [External Includes](#external-includes)
- [Window Includes](#window-includes)
- [Validation System](#validation-system)
- [Platform Support](#platform-support)
- [Examples](#examples)
- [Best Practices](#best-practices)
- [Migration Guide](#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
- **Data Binding**: MVVM-style data binding with validation and converters
- **Accessibility**: WCAG compliance and screen reader support
- **Validation**: Strict constraints ensure consistent, valid UIs
- **Cross-Platform**: Platform-specific control libraries
- **Enterprise Ready**: Comprehensive business view patterns

## What's New in v1.2

### Major Enhancements

1. **Enhanced Data Binding Support**
   - MVVM-style property binding with two-way support
   - Validation rules and converters
   - Command binding for actions
   - Context-aware data binding

2. **Comprehensive Accessibility Features**
   - WCAG A/AA/AAA compliance levels
   - Screen reader support with ARIA attributes
   - Keyboard navigation patterns
   - High contrast and visual accessibility

3. **Window Includes Support**
   - Separate window definitions into external files
   - Improved organization for large applications
   - Better team collaboration capabilities

4. **Enhanced Schema Validation**
   - More comprehensive XSD schema with proper namespaces
   - Better error reporting and validation
   - Support for all platform-specific controls

5. **Expanded Platform Support**
   - Full Avalonia UI control library with modern controls
   - Enhanced WinForms control definitions
   - Web and mobile control patterns
   - KDE/Qt control support

6. **Advanced Business View Features**
   - Entity-relationship modeling in views
   - Enhanced communication patterns
   - Workflow support for process-driven views
   - Module view organization
   - Dependency injection patterns

7. **Enhanced Control Library**
   - Abstract control definitions with inheritance
   - Platform-specific specializations
   - Data binding and accessibility at control level
   - Comprehensive attribute validation

### Breaking Changes from v1.1

- Enhanced schema validation may require updates to existing documents
- Some control attributes have been refined for better platform compatibility
- Window include structure requires specific file organization
- Data binding syntax has been formalized

## Core Concepts

### 1. View-First Design
Views represent logical business functions (ProductView, OrderView) that group related windows and define shared data context and behaviors.

### 2. Patterns-First Design
All controls and structures must be defined in the `<patterns>` section before use in windows.

### 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. Data Binding Architecture
- Property binding with validation
- Command binding for user actions
- Converter support for data transformation
- Context-aware binding scopes

### 5. Accessibility-First Design
- Built-in WCAG compliance support
- Screen reader optimization
- Keyboard navigation patterns
- Visual accessibility features

### 6. Inheritance Hierarchy
- Views can inherit from other views
- Controls can inherit from other controls
- Windows can inherit from wireframe layouts
- Attributes can be overridden at any level

### 7. Slot-Based Composition
Wireframes use slots as placeholders that windows can fill with specific content.

### 8. Constraint Validation
Comprehensive validation rules ensure UI consistency and platform compliance.

## Document Structure

```xml
<?xml version="1.0" encoding="UTF-8"?>
<ui-layout-def xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns="ui-layout-definition"
               xsi:schemaLocation="ui-layout-definition ui-layout-def.xsd"
               version="1.2"
               schema-version="1.2"
               target-platform="basic|winforms|avalonia|kde|web|mobile"
               accessibility-compliance="none|basic|wcag-a|wcag-aa|wcag-aaa">
  
  <!-- Optional: Validation rules with external includes -->
  <validation-rules>
    <validation-include src="..." important="true/false" min-version="1.0" max-version="2.0" />
    <rule name="...">...</rule>
  </validation-rules>
  
  <!-- Required: Pattern definitions with external includes -->
  <patterns>
    <pattern-include src="..." important="true/false" platform="basic|winforms|avalonia" min-version="1.0" max-version="2.0" />
    <control name="..." type="..." category="..." inherits="...">...</control>
    <structure name="..." type="..." category="..." inherits="...">...</structure>
    <wireframe name="..." type="...">...</wireframe>
  </patterns>
  
  <!-- View definitions with external includes -->
  <views>
    <view-include src="..." important="true/false" min-version="1.0" max-version="2.0" />
    <view name="..." type="..." category="..." inherits="...">...</view>
  </views>
  
  <!-- Window includes -->
  <window-includes>
    <window-include src="..." important="true/false" platform="..." min-version="1.0" max-version="2.0" />
  </window-includes>
  
  <!-- Window definitions (can be in external files) -->
  <window name="..." title="..." wireframe="..." view="..." target-platform="..." schema-version="1.2">
    <!-- Data binding configuration -->
    <data-binding>
      <data-context source="..." type="..." mode="TwoWay" />
      <view-model class="..." assembly="..." namespace="..." />
      <binding-properties>
        <property control="..." property="..." binding-path="..." mode="..." validation-rule="..." converter="..." />
      </binding-properties>
    </data-binding>
    
    <!-- Accessibility configuration -->
    <accessibility compliance-level="wcag-aa">
      <screen-reader window-title="..." description="..." landmark-role="..." />
      <keyboard-navigation tab-order-start="1" focus-trap="false" escape-closes="true" />
      <color-contrast high-contrast-support="true" minimum-ratio="4.5" />
    </accessibility>
    
    <!-- Window content -->
    <slot-overrides>
      <!-- Slot content with enhanced controls -->
    </slot-overrides>
  </window>
  
</ui-layout-def>
```

## Data Binding Support

### Enhanced Control Attributes
All controls now support comprehensive data binding:

```xml
<control name="EnhancedTextBox" type="input" category="basic" inherits="TextBox">
  <attributes>
    <!-- Data Binding Support -->
    <attribute name="data-context" type="string" default="" />
    <attribute name="binding-path" type="string" default="" />
    <attribute name="command-binding" type="string" default="" />
    <attribute name="validation-rule" type="string" default="" />
    <attribute name="converter" type="string" default="" />
    <attribute name="binding-mode" type="enum" values="OneWay,TwoWay,OneTime,OneWayToSource" default="TwoWay" />
    
    <!-- Enhanced input features -->
    <attribute name="input-type" type="enum" values="text,email,url,tel,number,search" default="text" />
    <attribute name="auto-complete" type="enum" values="off,on,name,email,username" default="off" />
    <attribute name="validation-pattern" type="string" default="" />
    <attribute name="required" type="bool" default="false" />
  </attributes>
  <behavior>
    <event name="validation-error" />
    <event name="validation-success" />
  </behavior>
</control>
```

### Window-Level Data Binding
```xml
<window name="ProductEditDialog" title="Edit Product">
  <data-binding>
    <data-context source="ProductEditViewModel" type="ViewModels.ProductEditViewModel" mode="TwoWay" />
    <view-model class="ProductEditViewModel" assembly="MyApp.ViewModels" namespace="MyApp.ViewModels" />
    <binding-properties>
      <property control="nameTextBox" property="text" binding-path="Product.Name" mode="TwoWay" validation-rule="RequiredValidator" />
      <property control="priceTextBox" property="text" binding-path="Product.Price" mode="TwoWay" converter="CurrencyConverter" />
      <property control="saveButton" property="enabled" binding-path="CanSave" mode="OneWay" />
    </binding-properties>
  </data-binding>
</window>
```

## Accessibility Features

### Control-Level Accessibility
```xml
<control name="AccessibleButton" type="action" category="basic" inherits="Button">
  <attributes>
    <!-- Accessibility Support -->
    <attribute name="aria-label" type="string" default="" />
    <attribute name="aria-description" type="string" default="" />
    <attribute name="aria-role" type="string" default="" />
    <attribute name="tab-index" type="int" default="0" />
    <attribute name="access-key" type="string" default="" />
    <attribute name="high-contrast-support" type="bool" default="true" />
    <attribute name="screen-reader-text" type="string" default="" />
  </attributes>
</control>
```

### Window-Level Accessibility
```xml
<window name="MainWindow" title="Application">
  <accessibility compliance-level="wcag-aa">
    <screen-reader window-title="Main Application Window" 
                   description="Primary interface for data management"
                   landmark-role="main" />
    <keyboard-navigation tab-order-start="1" focus-trap="false" escape-closes="false" />
    <color-contrast high-contrast-support="true" minimum-ratio="4.5" />
  </accessibility>
</window>
```

## Platform Support

### Enhanced Platform Integration

**Windows Forms**
- Complete DataGridView, ToolStrip, and dialog support
- Generate view classes with proper MVVM binding
- Create dependency injection containers
- Generate navigation services

**Avalonia UI**
- Full modern control set including Grid, StackPanel, DataGrid
- Cross-platform compatibility
- Modern UI patterns and styling
- MVVM architecture support with command binding

**Qt / KDE**
- Qt widget system integration
- KDE desktop integration patterns
- Cross-platform Qt navigation

**Web / HTML**
- Generate MVC views or React components
- Support for SPA routing
- Progressive web app patterns
- Responsive design support

### Platform-Specific Control Libraries

The format includes comprehensive control libraries for each platform:

- **abstract-controls.xml** - Base control definitions with enhanced features
- **winform-controls.xml** - Complete WinForms control set
- **avalonia-controls.xml** - Modern Avalonia UI controls
- **web-controls.xml** - Web-specific controls
- **kde-controls.xml** - KDE/Qt controls

## Enhanced Business Views

### Entity Relationship Patterns
```xml
<view name="OrderView" type="business-entity" category="core">
  <dependencies>
    <view-ref name="OrderItemView" relationship="detail" required="true">
      <interaction type="manage-items" context="current-order" />
    </view-ref>
    <view-ref name="CustomerView" relationship="reference" required="false">
      <interaction type="view-customer" context="customer-id" />
    </view-ref>
    <view-ref name="ProductView" relationship="lookup" required="false">
      <interaction type="select-product" returns="product-id" />
    </view-ref>
  </dependencies>
  
  <communication>
    <publishes>
      <event name="order-created" data="order-id" />
      <event name="order-processed" data="order-id" />
    </publishes>
    <subscribes>
      <event name="customer-changed" source="CustomerView" handler="update-customer-info" />
      <event name="inventory-updated" source="ProductView" handler="check-availability" />
    </subscribes>
  </communication>
</view>
```

## Advanced Features

### Comprehensive Control Definitions
The format now includes advanced controls with rich attribute sets:

- **ProgressBar** with indeterminate mode and styling
- **DatePicker** with calendar integration
- **NumericUpDown** with validation and formatting
- **Slider** with tick marks and value display
- **Enhanced DataGridView** with sorting, filtering, and virtualization

### Enhanced Validation System
```xml
<validation-rules>
  <!-- Data binding validation -->
  <rule name="data-binding-validation">
    <description>Data binding must be valid and type-safe</description>
    <constraint>Binding paths must reference valid properties</constraint>
    <constraint>Binding modes must be appropriate for property types</constraint>
  </rule>
  
  <!-- Accessibility validation -->
  <rule name="accessibility-compliance">
    <description>Controls must meet accessibility requirements</description>
    <constraint>Interactive controls must have aria-label or accessible text</constraint>
    <constraint>Color contrast must meet minimum ratios</constraint>
  </rule>
</validation-rules>
```

## File Organization

### Recommended Project Structure
```
project/
├── main.xml                        # Main document with includes
├── patterns/
│   ├── abstract-controls.xml       # Enhanced base control definitions
│   ├── winform-controls.xml        # Complete WinForms controls
│   ├── avalonia-controls.xml       # Modern Avalonia controls
│   ├── web-controls.xml            # Web-specific controls
│   └── kde-controls.xml            # KDE/Qt controls
├── views/
│   ├── business-views.xml          # Business entity view patterns
│   └── admin-views.xml             # Administrative views
├── windows/
│   ├── main-windows.xml            # Primary application windows
│   ├── dialog-windows.xml          # Modal dialogs and popups
│   └── admin-windows.xml           # Administrative interfaces
├── validation/
│   ├── base-validation.xml         # Core validation rules
│   ├── view-validation.xml         # View-specific rules
│   └── accessibility-rules.xml     # Accessibility compliance
└── samples/
    ├── sample.xml                  # Comprehensive example
    ├── sample-minimal.xml          # Minimal example
    └── platform-config-sample.xml # Platform-specific example
```

## Schema Files

The format includes comprehensive XSD schema files:

- **ui-layout-def.xsd** - Main schema with imports
- **ui-layout-basic-controls.xsd** - Basic control definitions
- **ui-layout-winforms-controls.xsd** - WinForms-specific controls  
- **ui-layout-avalonia-controls.xsd** - Avalonia-specific controls
- **ui-layout-patterns.xsd** - Pattern definition schema
- **ui-layout-views.xsd** - View definition schema
- **ui-layout-validation.xsd** - Validation rule schema

## Best Practices

### 1. Data Binding Strategy
- Use two-way binding for user input controls
- Implement validation rules for data integrity
- Use converters for data transformation
- Bind commands to user actions

### 2. Accessibility Design
- Always provide aria-label for interactive controls
- Ensure proper tab order and keyboard navigation
- Test with screen readers
- Maintain appropriate color contrast

### 3. View Organization
- **Single Responsibility**: Each view should handle one business concept
- **Dependency Injection**: Use view dependencies rather than tight coupling
- **Data Context**: Define clear data scopes (view, shared, global)
- **Communication**: Use events for loose coupling between views

### 4. Platform Compatibility
- Define abstract controls for common functionality
- Use platform-specific includes for specialized features
- Test on all target platforms
- Maintain compatibility matrices

### 5. Include Management
- Mark critical includes as `important="true"`
- Use version constraints for compatibility
- Document include dependencies
- Test with missing optional includes

## Examples

See the included sample files for comprehensive examples:

- **sample.xml** - Full-featured application with advanced patterns
- **platform-config-sample.xml** - Platform-specific configuration with data binding
- **sample-minimal.xml** - Minimal working example
- **business-views.xml** - Business entity view patterns
- **abstract-controls.xml** - Enhanced control definitions

## Migration Guide

### From Version 1.1 to 1.2

#### Backward Compatibility
Version 1.2 maintains full backward compatibility with 1.1 documents. Existing documents will work without modification.

#### New Features Available
1. **Enhanced Data Binding**: Add MVVM-style binding to existing controls
2. **Accessibility Support**: Add WCAG compliance to existing windows
3. **Window Includes**: Organize windows in separate files
4. **Enhanced Schema**: Better validation and error reporting
5. **Extended Platform Support**: More control libraries available

#### Migration Steps
1. **Update Schema Reference**: Change version to "1.2" and add schema-version="1.2"
2. **Optional: Add Data Binding**: Enhance controls with binding attributes
3. **Optional: Add Accessibility**: Include accessibility configuration
4. **Optional: Reorganize Windows**: Move windows to separate files
5. **Optional: Add Platform Controls**: Include platform-specific patterns
6. **Update Validation**: Add new validation rule includes

---

*This format specification enables consistent, validated, cross-platform UI definitions with powerful view organization, data binding, accessibility support, external includes, inheritance, and modular design capabilities. The comprehensive control libraries and business view patterns make it suitable for enterprise application development.*