Home Explore Help
Sign In
dvotruba
/
qdr.app.tools
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Branch: master
Branches Tags
qdr.app.tools
/
UILayoutDefinitionFormat
/
CLAUDE.md

CLAUDE.md 9.0 KB
Permalink History Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is the UI Layout Definition Format repository - a comprehensive XML-based format for describing cross-platform user interfaces with inheritance, validation, and modern development practices. Version 1.6 includes advanced features like state management, accessibility compliance, AI assistance, performance optimization, and supported view modes.

Architecture

Core Components

XML Schema Definitions (.xsd files)

  • ui-layout-def.xsd - Main schema definition with root elements and structure
  • ui-layout-patterns.xsd - Pattern definitions for controls, structures, and wireframes
  • ui-layout-views.xsd - Advanced view definitions with state management and AI features
  • ui-layout-validation.xsd - Validation rules, custom validators, and profiles
  • ui-layout-basic-controls.xsd - Basic UI control definitions
  • ui-layout-avalonia-controls.xsd - Avalonia platform-specific controls
  • ui-layout-winforms-controls.xsd - Windows Forms platform-specific controls
  • ui-layout-webawesome-controls.xsd - Web Awesome (formerly Shoelace) web components

Definition Files (Definitions/ folder)

  • abstract-controls.xml - Base control definitions with common attributes and behaviors
  • avalonia-controls.xml - Avalonia UI platform-specific control implementations
  • web-controls.xml - Web platform control definitions
  • winform-controls.xml - Windows Forms control definitions
  • webawesome-controls.xml - Web Awesome component definitions with modern web controls

Sample Files (Samples/ folder)

  • sample.xml - Comprehensive v1.6 sample showcasing all features
  • business-views.xml - Business logic view examples
  • Various platform-specific samples (kde-controls.xml, web-controls.xml, etc.)

Key Architecture Principles

  1. Modular Design: External includes allow splitting definitions across multiple files
  2. Platform Abstraction: Unified control definitions with platform-specific implementations
  3. View-First Architecture: Business views organize related windows and define data context
  4. Pattern-Based Design: All controls must be defined in patterns before use
  5. Comprehensive Validation: Advanced validation system with custom validators and profiles

Development Commands

XML Validation

# Validate XML files against XSD schemas using XMLStarlet
xmlstarlet val -e -s ui-layout-def.xsd Samples/simple-working.xml
xmlstarlet val -e -s ui-layout-def.xsd Samples/sample-minimal.xml

# Validate all schema files
xmlstarlet val -e ui-layout-*.xsd

# Alternative with xmllint if XMLStarlet unavailable
xmllint --schema ui-layout-def.xsd Samples/simple-working.xml --noout

Schema Validation Status

# All schema files are valid ✅
xmlstarlet val -e ui-layout-def.xsd
xmlstarlet val -e ui-layout-basic-controls.xsd
xmlstarlet val -e ui-layout-patterns.xsd
xmlstarlet val -e ui-layout-views.xsd
xmlstarlet val -e ui-layout-validation.xsd
xmlstarlet val -e ui-layout-avalonia-controls.xsd
xmlstarlet val -e ui-layout-winforms-controls.xsd
xmlstarlet val -e ui-layout-webawesome-controls.xsd

# Working sample file ✅
xmlstarlet val -e -s ui-layout-def.xsd Samples/simple-working.xml

# Pattern definitions file ✅
xmlstarlet val -e -s ui-layout-def.xsd Definitions/abstract-controls.xml

# Web Awesome controls file ✅
xmlstarlet val -e -s ui-layout-webawesome-controls.xsd Definitions/webawesome-controls.xml

XML Processing and Querying

# Query XML structure using XMLStarlet
xmlstarlet sel -t -m "//control" -v "@name" -n abstract-controls.xml
xmlstarlet sel -t -m "//window" -v "@name" -n sample.xml

# Format/pretty-print XML files
xmlstarlet fo sample.xml > formatted-sample.xml

File Structure Understanding

  • Root Schema: ui-layout-def.xsd defines the main document structure
  • External Schemas: Platform-specific and feature-specific schemas are imported
  • Control Hierarchy: All controls inherit from CommonControl in abstract-controls.xml
  • Validation System: Custom validators and profiles in validation includes
  • Sample Implementation: sample.xml demonstrates v1.6 features including AI assistance, accessibility, performance optimization, and supported view modes

Important Development Notes

Schema Versioning

  • Current version: 1.6
  • Schema version must match in schema-version attribute
  • Platform compatibility defined in platform-constraints

Validation Requirements

  • All interactive controls require accessibility attributes for WCAG compliance
  • Performance targets recommended for data-heavy views
  • Security attributes required for high-security applications

Control Definition Process

  1. Define abstract control in Definitions/abstract-controls.xml
  2. Add platform-specific implementations in appropriate control files
  3. Update schema definitions to include new control types
  4. Add validation rules for new attributes

Gallery Control Implementation

The Gallery control (introduced in v1.5) is for displaying collections with customizable templates:

Key Features:

  • Inherits from CommonControl with ListView-like behavior
  • Custom box templates with positioning and styling
  • Support for paging and virtualization
  • Gallery-specific attributes: image-width, image-height, box-width, box-height
  • Data binding support with custom properties and fields

Files Updated:

  • Definitions/abstract-controls.xml - Gallery control definition and related structures
  • ui-layout-basic-controls.xsd - Gallery schema types and validation rules
  • README.md - Documentation and usage examples

v1.6 Enhancements

  • Supported View Modes: New element for defining display modes (grid, gallery, tree) per view
  • Enhanced Descriptions: Added description attributes to DataPropertyType, ViewBehaviorType, and PublishedEventType
  • All schema files updated to version 1.6 with consistent defaults

v1.5 Enhancements

  • Advanced state management with Redux/MobX patterns
  • Comprehensive accessibility framework (WCAG 2.1 AA/AAA)
  • Performance optimization system with metrics and targets
  • Security framework with GDPR compliance
  • Enhanced testing framework with automation support
  • Advanced localization with RTL support
  • Gallery Control: Specialized list control for displaying collections with customizable box templates

Web Awesome Controls Implementation

Web Awesome (formerly Shoelace) component support for modern web applications (added in v1.5):

Key Features:

  • Complete Web Awesome component library (75+ controls)
  • Modern web components with Shadow DOM encapsulation
  • Accessibility-first design with WCAG compliance
  • Comprehensive form controls with built-in validation
  • Advanced UI patterns (modals, tooltips, animations)
  • TypeScript definitions and framework integrations

Control Categories:

  • Action Controls: wa-button, wa-dropdown, wa-copy-button, wa-qr-code
  • Form Controls: wa-input, wa-select, wa-checkbox, wa-color-picker, wa-rating
  • Feedback & Status: wa-badge, wa-callout, wa-progress-bar, wa-spinner, wa-tooltip
  • Navigation: wa-breadcrumb, wa-tab-group, wa-tree
  • Organization: wa-card, wa-dialog, wa-drawer, wa-split-panel
  • Imagery: wa-avatar, wa-carousel, wa-icon, wa-animated-image
  • Utility: wa-animation, wa-format-date, wa-include, wa-popover

Files Added:

  • Definitions/webawesome-controls.xml - Complete Web Awesome control definitions
  • ui-layout-webawesome-controls.xsd - Schema for Web Awesome components
  • Platform-specific validation and accessibility requirements
  • Custom Web Awesome wireframes and patterns

Usage Pattern:

<patterns>
  <pattern-include src="webawesome-controls.xml" platform="web" important="true" />
</patterns>

<window platform="web">
  <wa-card size="medium">
    <wa-input label="Name" required="true" help-text="Enter your full name">
    </wa-input>
    <wa-button variant="brand" type="submit">Submit</wa-button>
  </wa-card>
</window>

Recent Updates

  • Gallery Control Added: New Gallery control in abstract-controls.xml and ui-layout-basic-controls.xsd
  • Web Awesome Controls Added: Complete Web Awesome component library in webawesome-controls.xml and ui-layout-webawesome-controls.xsd
  • Namespace Fixes: Corrected namespace declarations in abstract-controls.xml
  • Schema Validation: All files now validate successfully against their schemas, including Web Awesome controls
  • Documentation Updated: README.md and CLAUDE.md include Web Awesome control examples and validation status

When working with this codebase, always validate XML against schemas and ensure new features follow the established patterns for platform abstraction and modular design. Use the Web Awesome controls for modern web applications requiring advanced UI components with built-in accessibility.