# 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.5 includes advanced features like state management, accessibility compliance, AI assistance, and performance optimization.

## 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.5 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**
```bash
# 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**
```bash
# 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**
```bash
# 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.5 features including AI assistance, accessibility, and performance optimization

## Important Development Notes

### Schema Versioning
- Current version: 1.5
- 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 is a new v1.5 feature 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.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
- **New Gallery Control**: Specialized list control for displaying collections with customizable box templates

### Web Awesome Controls Implementation
Version 1.5 adds comprehensive Web Awesome (formerly Shoelace) component support for modern web applications:

**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:**
```xml
<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.