RickUIBuilder 0.2.2 — ComboBox, Runtime Architecture & Engineering Governance

RickUIBuilder 0.2.2 — ComboBox, Runtime Architecture & Engineering Governance

Release: 0.2.2
Previous: 0.2.1
Comparison: 0.2.1...0.2.2

Overview

The 0.2.2 release represents a significant evolution of RickUIBuilder, with the introduction of a complete ComboBox component, improvements to runtime lifecycle management, expanded FMX behavior handling, a substantially expanded documentation system, and the establishment of a formal AI-assisted engineering governance layer.

This release also strengthens the project's documentation, maintenance contracts, testing coverage, and architectural boundaries, establishing a more consistent foundation for future component development.

🚀 Highlights

ComboBox — Complete Component Implementation

The main feature of this release is the introduction of a complete ComboBox implementation covering both builder-time configuration and runtime behavior.

The new ComboBox implementation includes:

• Builder and factory support.
• Runtime handle and behavior management.
• Data and item configuration.
• Selection state management.
• Search and filtering.
• Filtered-view to source-index mapping.
• Desktop, mobile, adaptive, and custom variants.
• FullWindow presentation mode.
• Popup sizing and presentation configuration.
• Runtime arrow behavior.
• Visual styling and presentation resolution.
• Keyboard navigation and interaction.
• Lifecycle and ownership management.
• Virtualization support.
• Dedicated runtime behavior component.

Keyboard handling was also centralized through action tables, covering navigation and interaction keys such as:

• Arrow Up / Down
• Home / End
• Page Up / Page Down
• Enter / Space
• Escape
• Tab

This provides a consistent interaction model across ComboBox open and search modes.

🧱 Runtime Architecture and Lifecycle

The runtime architecture was refined to improve ownership and lifetime management.

ComboBox visual lifetime management is now isolated in a dedicated behavior component. The behavior maintains the required runtime references while coordinating visual detachment through a callback-based mechanism.

This approach:

• Keeps runtime handles alive only while the visual container exists.
• Avoids unnecessary coupling between behavior and concrete handle implementations.
• Prevents detach operations caused by unrelated parent destruction.
• Preserves ownership boundaries between runtime state and FMX visual components.

The same architectural direction was also applied to Button hover behavior.

Button Hover Behavior

Button hover handling was extracted into a dedicated FMX component while keeping the state/configuration model in HoverState.

The implementation now:

• Re-evaluates the hover fill callback on enter and leave.
• Updates Fill.Color according to the current hover state.
• Invokes registered hover handlers.
• Preserves the state lifetime correctly.
• Avoids exposing TComponent through the public API.
• Uses the dedicated Boolean callback type for state transitions.

The Button Build contract was also clarified: Button(AValue) must be configured before calling Build, while ownership remains with AOwner.

📚 Documentation Expansion

This release introduces a much broader documentation structure in both English and Brazilian Portuguese.

New and expanded documentation covers:

• ComboBox API and architecture.
• ComboBox advanced configuration.
• FullWindow behavior and styling.
• Keyboard interaction.
• Popup sizing.
• Runtime arrow behavior.
• Ownership and lifecycle flow.
• Label.
• Button.
• Badge.
• Divider.
• Factory and builder behavior.
• Hover behavior.
• Component maintenance contracts.
• Architecture and component maps.

The ComboBox documentation specifically documents the relationship between the runtime handle, behavior component, visual container, ownership model, and detach lifecycle.

The documentation also now includes tested-contract notes and maintenance maps to help future contributors identify the relevant implementation, documentation, and tests before modifying component behavior.

🧪 Testing and Quality

The DUnitX test suite was expanded alongside the new functionality.

Coverage includes ComboBox:

• Filtering.
• Searching.
• Selection.
• Keyboard behavior.
• Visual contracts.
• Lifecycle behavior.
• Runtime configuration.

The sample application was also updated to exercise the new component behavior and configuration scenarios.

The release additionally clarifies the project's Method Toxicity reporting, distinguishing the current library CSV baseline from historical measurements captured from samples and tests.

🧩 Sample Application Improvements

The sample application received a structural refactoring to reduce duplication and improve consistency.

Reusable configuration builders were extracted for:

• Text.
• Dividers.
• Badges.
• Buttons.
• Factory-based examples.
• Composition-based examples.

ComboBox keyboard actions were also centralized into reusable action tables, making navigation and interaction behavior easier to maintain and keeping the sample implementation aligned with the component's runtime behavior.

🤖 AI Engineering Governance

This release introduces a formal repository-level engineering governance structure for AI-assisted development.

The new .agents structure provides:

• Agent skills.
• Agent personas.
• Engineering references.
• Documentation references.
• Templates.
• Quality gates.
• Workflow definitions.
• Delphi/FMX-specific engineering guidance.
• Testing and documentation procedures.

The previous .ai structure was replaced by the new workflow-oriented engineering model.

AGENTS.md was also updated to establish repository-level maintenance and delivery rules.

The governance layer incorporates a local adaptation of the upstream agent-skills benchmark for RickUIBuilder, providing a structured foundation for future AI-assisted engineering work.

📝 README and Branding

The English and Brazilian Portuguese README files were refreshed with:

• Branded project titles.
• Centered header presentation.
• Updated project information.
• Maintainer information.
• Proprietary licensing details.
• Official English and Portuguese license references.
• ComboBox API information.
• Sample usage.
• Test coverage information.
• Method Toxicity baseline information.
• Navigation to component documentation.
• Closing project summary.

The README back-to-top links were also corrected to match GitHub's generated heading anchors.

🔐 Licensing

The project documentation now makes the project's proprietary licensing model and commercial usage boundaries more explicit.

The official English and Portuguese license references remain visible from the main documentation to reduce ambiguity regarding permitted usage and distribution.

🏗️ Architectural Improvements

Beyond the new features, this release establishes several architectural patterns intended to make future components easier to maintain:

• Clear separation between builder configuration and runtime behavior.
• Dedicated behavior components for visual lifecycle concerns.
• Callback-based detachment instead of unnecessary concrete-type coupling.
• Explicit ownership and lifetime contracts.
• Reusable configuration builders.
• Centralized interaction/action definitions.
• Component-specific maintenance documentation.
• Documentation-to-test contract mapping.
• Formal engineering quality gates.

These changes provide a stronger foundation for extending RickUIBuilder with additional FMX components while preserving its existing API and runtime contracts.

📦 Release Summary

RickUIBuilder 0.2.2 is primarily focused on expanding the component system with a production-oriented ComboBox implementation while strengthening the project's architecture, lifecycle management, testing, documentation, and engineering governance.

The release combines:

• A complete ComboBox builder/runtime API.
• Advanced ComboBox interaction and presentation behavior.
• Improved FMX lifecycle handling.
• Dedicated Button hover behavior.
• Expanded DUnitX coverage.
• Refactored sample configurations.
• Comprehensive bilingual documentation.
• Component maintenance contracts.
• AI engineering governance and quality gates.
• Updated branding and licensing documentation.

This release establishes a stronger technical and documentation foundation for the next stage of RickUIBuilder development.

🔗 Release Comparison

Full changes between versions: 0.2.1...0.2.2

---

RickUIBuilder 0.2.2 — ComboBox, Arquitetura de Runtime e Governança de Engenharia (Versão em pt-BR)

Release: 0.2.2
Anterior: 0.2.1
Comparação: 0.2.1...0.2.2

Visão Geral

A versão 0.2.2 representa uma evolução significativa do RickUIBuilder, com a introdução de um ComboBox completo, melhorias no gerenciamento do ciclo de vida em runtime, aprimoramentos no comportamento FMX, uma expansão significativa do sistema de documentação e a criação de uma camada formal de governança para engenharia assistida por IA.

Esta release também fortalece a documentação, os contratos de manutenção, a cobertura de testes e os limites arquiteturais do projeto, estabelecendo uma base mais consistente para o desenvolvimento dos próximos componentes.

🚀 Destaques

ComboBox — Implementação Completa

A principal funcionalidade desta release é a introdução de uma implementação completa de ComboBox, abrangendo tanto a configuração em tempo de construção quanto o comportamento em runtime.

A nova implementação do ComboBox inclui:

• Suporte a Builder e Factory.
• Handle e gerenciamento de comportamento em runtime.
• Configuração de dados e itens.
• Gerenciamento do estado de seleção.
• Pesquisa e filtragem.
• Mapeamento entre a visualização filtrada e os índices da fonte original.
• Variantes para desktop, mobile, adaptativa e customizada.
• Modo de apresentação FullWindow.
• Configuração do tamanho do popup.
• Comportamento da seta em runtime.
• Estilização e resolução de apresentação.
• Navegação e interação por teclado.
• Gerenciamento de ciclo de vida e ownership.
• Suporte à virtualização.
• Componente dedicado para o comportamento em runtime.

O tratamento do teclado também foi centralizado por meio de tabelas de ações, contemplando teclas de navegação e interação como:

• Seta para Cima / Baixo.
• Home / End.
• Page Up / Page Down.
• Enter / Space.
• Escape.
• Tab.

Isso proporciona um modelo de interação consistente nos modos de abertura e pesquisa do ComboBox.

🧱 Arquitetura de Runtime e Ciclo de Vida

A arquitetura de runtime foi refinada para melhorar o gerenciamento de ownership e lifetime.

O gerenciamento do ciclo de vida visual do ComboBox agora está isolado em um componente de comportamento dedicado. Esse comportamento mantém as referências de runtime necessárias enquanto coordena o detach visual por meio de um mecanismo baseado em callback.

Essa abordagem:

• Mantém os handles de runtime vivos somente enquanto o container visual existir.
• Evita acoplamento desnecessário entre o comportamento e implementações concretas de handles.
• Impede operações de detach causadas pela destruição de um parent não relacionado.
• Preserva os limites de ownership entre o estado de runtime e os componentes visuais FMX.

A mesma direção arquitetural também foi aplicada ao comportamento de hover do Button.

Comportamento de Hover do Button

O tratamento de hover do Button foi extraído para um componente FMX dedicado, mantendo o modelo de estado/configuração em HoverState.

A implementação agora:

• Reavalia o callback de preenchimento do hover ao entrar e sair do estado.
• Atualiza Fill.Color de acordo com o estado atual de hover.
• Executa os handlers de hover registrados.
• Preserva corretamente o lifetime do estado.
• Evita expor TComponent na API pública.
• Utiliza o tipo de callback Boolean dedicado para as transições de estado.

O contrato de Build do Button também foi esclarecido: Button(AValue) deve ser configurado antes da chamada de Build, enquanto o ownership permanece com AOwner.

📚 Expansão da Documentação

Esta release introduz uma estrutura de documentação muito mais abrangente, disponível em inglês e português brasileiro.

A documentação nova e expandida contempla:

• API e arquitetura do ComboBox.
• Configuração avançada do ComboBox.
• Comportamento e estilização do FullWindow.
• Interação por teclado.
• Dimensionamento do popup.
• Comportamento da seta em runtime.
• Fluxo de ownership e ciclo de vida.
• Label.
• Button.
• Badge.
• Divider.
• Comportamento de Factory e Builder.
• Comportamento de hover.
• Contratos de manutenção dos componentes.
• Mapas de arquitetura e componentes.

A documentação do ComboBox descreve especificamente o relacionamento entre o handle de runtime, o componente de comportamento, o container visual, o modelo de ownership e o ciclo de detach.

A documentação também passou a incluir notas de contratos testados e mapas de manutenção, permitindo que futuros contribuidores identifiquem os pontos relevantes de implementação, documentação e testes antes de alterar o comportamento de um componente.

🧪 Testes e Qualidade

A suíte de testes DUnitX foi expandida juntamente com as novas funcionalidades.

A cobertura inclui:

• Filtragem do ComboBox.
• Pesquisa.
• Seleção.
• Comportamento do teclado.
• Contratos visuais.
• Comportamento de ciclo de vida.
• Configuração de runtime.

A aplicação de exemplo também foi atualizada para exercitar os novos comportamentos e cenários de configuração do componente.

A release também esclarece o relatório de Method Toxicity, diferenciando o baseline atual do CSV da biblioteca em relação às medições históricas capturadas a partir de exemplos e testes.

🧩 Melhorias na Aplicação de Exemplo

A aplicação de exemplo recebeu uma refatoração estrutural para reduzir duplicações e melhorar a consistência.

Foram extraídos builders reutilizáveis de configuração para:

• Textos.
• Dividers.
• Badges.
• Buttons.
• Exemplos baseados em Factory.
• Exemplos baseados em Composition.

As ações de teclado do ComboBox também foram centralizadas em tabelas de ações reutilizáveis, tornando a navegação e a interação mais fáceis de manter e mantendo a implementação do exemplo alinhada ao comportamento de runtime do componente.

🤖 Governança de Engenharia com IA

Esta release introduz uma estrutura formal de governança para engenharia assistida por IA em nível de repositório.

A nova estrutura .agents fornece:

• Skills para agentes.
• Personas de agentes.
• Referências de engenharia.
• Referências de documentação.
• Templates.
• Quality gates.
• Definições de workflow.
• Orientações específicas para Delphi/FMX.
• Procedimentos de testes e documentação.

A estrutura anterior .ai foi substituída pelo novo modelo de engenharia orientado a workflows.

O arquivo AGENTS.md também foi atualizado para estabelecer regras de manutenção e procedimentos de entrega em nível de repositório.

A camada de governança incorpora uma adaptação local do benchmark upstream agent-skills para o RickUIBuilder, fornecendo uma base estruturada para futuros trabalhos de engenharia assistidos por IA.

📝 README e Branding

Os arquivos README em inglês e português brasileiro foram atualizados com:

• Títulos com a identidade visual do projeto.
• Cabeçalhos centralizados.
• Informações atualizadas do projeto.
• Informações do mantenedor.
• Detalhes da licença proprietária.
• Referências oficiais às licenças em inglês e português.
• Informações sobre a API do ComboBox.
• Exemplos de utilização.
• Informações sobre cobertura de testes.
• Informações sobre o baseline de Method Toxicity.
• Navegação para a documentação dos componentes.
• Seção de encerramento e resumo do projeto.

Os links de retorno ao topo também foram corrigidos para corresponder aos anchors gerados pelo GitHub a partir dos títulos dos documentos.

🔐 Licenciamento

A documentação do projeto agora deixa mais explícito o modelo de licenciamento proprietário e os limites de uso comercial.

As referências oficiais às licenças em inglês e português permanecem disponíveis na documentação principal, reduzindo ambiguidades relacionadas ao uso e à distribuição do projeto.

🏗️ Melhorias Arquiteturais

Além das novas funcionalidades, esta release estabelece diversos padrões arquiteturais destinados a facilitar a manutenção e evolução dos componentes:

• Separação clara entre configuração do Builder e comportamento de runtime.
• Componentes de comportamento dedicados para responsabilidades relacionadas ao ciclo de vida visual.
• Detach baseado em callback em vez de acoplamento desnecessário a tipos concretos.
• Contratos explícitos de ownership e lifetime.
• Builders reutilizáveis para configurações.
• Definições centralizadas de ações e interações.
• Documentação de manutenção específica por componente.
• Mapeamento entre contratos de documentação e testes.
• Quality gates formais para engenharia.

Essas mudanças fornecem uma base mais sólida para a expansão do RickUIBuilder com novos componentes FMX, preservando seus contratos existentes de API e runtime.

📦 Resumo da Release

O RickUIBuilder 0.2.2 tem como foco principal a expansão do sistema de componentes com uma implementação completa e orientada a produção do ComboBox, ao mesmo tempo em que fortalece a arquitetura, o gerenciamento de ciclo de vida, os testes, a documentação e a governança de engenharia do projeto.

Esta release reúne:

• Nova API completa de Builder e runtime para ComboBox.
• Comportamentos avançados de interação e apresentação do ComboBox.
• Melhorias no gerenciamento de ciclo de vida FMX.
• Comportamento dedicado de hover para Button.
• Expansão da cobertura DUnitX.
• Refatoração das configurações da aplicação de exemplo.
• Documentação bilíngue ampliada.
• Contratos de manutenção dos componentes.
• Governança de engenharia assistida por IA e quality gates.
• Atualização do branding e da documentação de licenciamento.

Esta release estabelece uma base técnica e documental mais robusta para a próxima etapa de evolução do RickUIBuilder.

🔗 Comparação da Release

Confira todas as alterações entre as versões: 0.2.1...0.2.2