RickUIBuilder 0.3.0 — Edit Runtime & Samples Catalog

🚀 Destaques da versão 0.3.0

A versão 0.3.0 amplia o RickUIBuilder em duas frentes principais: a evolução do componente Edit em runtime e a consolidação de uma nova arquitetura para o catálogo de Samples FMX.

Note

Esta release também atualiza a documentação técnica para refletir a estrutura atual do projeto e remove artefatos legados que não fazem mais parte da entrega oficial.

✏️ Edit — runtime, validação e experiência de uso

• Adicionado suporte ao Edit runtime builder, com configuração pública, tipos padrão, interfaces e ciclo de vida de behavior/handle.
• Evolução do tratamento de entrada para máscaras, casing, números, CPF, CNPJ, e-mail e URL.
• Adicionado suporte a campo obrigatório, incluindo validação de valores vazios após Trim.
• Validação de valores completos ao sair do campo, com tratamento de entrada parcial ou inválida.
• Proteção contra overflow em colagens de CPF/CNPJ e preservação do último valor válido.
• Melhorias no posicionamento do caret durante formatação e ao sair do controle.
• Novas opções visuais para background, cores individuais de ícones, área de ações, underline e mensagens de validação.
• Adicionado comportamento read-only e configuração de tamanho da fonte do label.
• Ajustes de altura mínima e alinhamento para evitar clipping de mensagens de validação.
• Ampliação da cobertura DUnitX e de testes de integração relacionados ao comportamento do Edit.

🧩 Novo catálogo de Samples FMX

• Nova aplicação RickUIBuilder.Samples, organizada por App, Home, Components e páginas de exemplos.
• Navegação baseada em Coordinator/Presenter e catálogo de componentes.
• Páginas dedicadas para Text/Label, Button, Badge, Divider, ComboBox e Edit.
• Novo Sample Page Base, com estrutura reutilizável para header, navegação, código e resultado.
• Alternância funcional entre Código Delphi e Resultado.
• CodePanel baseado em TMemo somente leitura, com seleção, cópia para clipboard e feedback temporário de cópia.
• ResultHost estável para renderização dos exemplos.
• Exemplos Factory e Fluent Builder para Text/Label, Button, Badge, Divider e ComboBox.
• Exemplo Fluent Builder para Edit.
• Layouts configuráveis por página com TExamplePageLayout e ConfigureLayout.
• Opção de inicialização -nodx para cenários em que o DirectX precisa ser desabilitado antes da inicialização FMX.
• Inclusão de assets locais do projeto para Android, iOS, macOS e Windows.

🧱 Arquitetura e documentação

• Atualização das especificações e decisões relacionadas ao Edit e ao runtime.
• Documentação da arquitetura atual do catálogo de Samples e das responsabilidades entre páginas, runners, conteúdo e navegação.
• Formalização de quality gates e auditorias locais para nomenclatura, toxicidade e contratos/lifetime em alterações Delphi relevantes.
• Clarificação da diferença entre API pública e runtime handles não proprietários.
• Documentos antigos de backlog/spec passam a ser tratados como registros históricos quando não representam mais o estado atual da implementação.
• README principal e referências de componentes atualizados para acompanhar a estrutura real do projeto.

🧹 Manutenção do repositório

• Removido o sample legado e seu checklist manual de verificação.
• Reorganização de units, enums, estilos compartilhados e diretórios dos exemplos para manter a estrutura do projeto consistente.

🔗 Changelog completo

Full Changelog: 0.2.2...0.3.0

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 runti...

RickUIBuilder 0.2.1 — Expose mutable button hover state

🚀 What's Changed

✨ New Features & Improvements

• Expose Mutable Button Hover State:
  • Exposed the built button's mutable hover state through the public handle API.
  • Hover behavior remains active via the owner while dynamically reading current values on each mouse event.
  • Hover configuration is now treated as live state — post-Build updates to FillColor, HoverFillColor, OnEnter, and OnLeave take effect on the next matching mouse event without requiring a full button rebuild.

📚 Documentation & Tests

• 📝 Updated English and Portuguese documentation to reflect the new dynamic hover state behavior.
• 🧪 Added regression tests covering post-Build state updates and mouse event evaluation.

---

Full Changelog: 0.2.0...0.2.1

---

0.2.1 - Permitir o controle dinâmico do estado de hover do botão (Vesrsão em pt-BR)

🚀 O que mudou

✨ Novidades e melhorias

• Estado de hover do botão agora é dinâmico
  • O estado mutável de hover do botão criado agora fica exposto por meio da API pública do handle.
  • O comportamento de hover continua sendo controlado pelo owner, mas passa a consultar os valores atuais a cada evento do mouse.
  • A configuração de hover agora funciona como um estado em tempo real. Isso significa que alterações feitas após o Build em FillColor, HoverFillColor, OnEnter e OnLeave passam a valer no próximo evento de mouse correspondente, sem a necessidade de reconstruir o botão.

📚 Documentação e testes

• 📝 Atualizamos a documentação em inglês e português para refletir o novo comportamento dinâmico do estado de hover.
• 🧪 Adicionamos testes de regressão para garantir o funcionamento das atualizações de estado feitas após o Build e a correta avaliação dos eventos do mouse.

---

Changelog completo: 0.2.0...0.2.1

RickUIBuilder 0.2.0 — Button Handles & Fluent Hover State

RickUIBuilder 0.2.0

This release extends the RickUIBuilder Button API with explicit access to generated controls and introduces a fluent, interface-based hover state architecture while preserving the existing Button API and behavior.

Highlights

• Added IRickUIBuilderButtonHandle.
• Added explicit access to:
  • Container: TRectangle
  • TextLabel: TLabel
• Added BuildHandle(AParent) to the Button Builder.
• Preserved the existing Build(AParent): TRectangle API.
• Removed the need for consumers to search the Button's child controls to retrieve its internal text label.
• Added a fluent IRickUIBuilderButtonHoverState contract.
• TRickUIBuilderButtonHoverState.New now requires no parameters.
• Added input/output overloads for hover state configuration.
• Preserved Owner-based lifetime management for the runtime hover behavior.
• Preserved existing click, hover, enabled, visibility, opacity, cursor, caption, font, spacing, border and corner-radius behavior.

Button Handle

Buttons can now expose both controls created by the builder through an explicit handle:

LHandle := TRickUIBuilder.Button
  .Caption('Save')
  .BuildHandle(AParent);

LHandle.Container;
LHandle.TextLabel;

**Full Changelog**: https://github.com/ricksolucoes/RickUIBuilder/compare/0.1.0...0.2.0

RickUIBuilder 0.1.0 — Initial Release

RickUIBuilder 0.1.0

Initial release of RickUIBuilder, a Delphi FireMonkey (FMX) library for creating and composing UI controls programmatically.

Highlights

• Direct FMX control creation through TRickUIBuilderFactory.
• Fluent Builders for:
  • Label
  • Button
  • Badge
  • Divider
• UI composition through TRickUIBuilder.On(AParent).
• Public IRickUIBuilder* interfaces for working with builder contracts.
• Configuration records with reusable Default values.
• Shared margin and padding configuration through TRickUIBuilderSpacing.
• Button click and hover configuration.
• Badge handles for accessing the generated container and internal text label.
• Source-based integration: add the src directory to the Delphi project Search Path.
• FireMonkey sample application demonstrating the main usage approaches.
• DUnitX test suite covering the main RickUIBuilder features.
• Documentation available in English and Portuguese (Brazil).

Usage

RickUIBuilder does not require package installation for normal use.

Add the following directory to your Delphi project's Search Path:

<path-to-RickUIBuilder>\src

Full Changelog: https://github.com/ricksolucoes/RickUIBuilder/commits/0.1.0