--- title: "Dynamic Fields Playground Catalog Plan" slug: "dynamic-fields-playground-catalog-plan" description: "Plano canonico para publicar um catalogo jogavel de Dynamic Fields consumido pela landing/playground sem duplicar fonte de verdade no host." doc_type: "reference" document_kind: "governance-reference" component: "dynamic-fields" category: "components" audience: - "frontend" - "architect" - "platform-team" level: "advanced" status: "draft" owner: "praxis-ui" tags: - "dynamic-fields" - "playground" - "catalog" - "governance" - "platform" order: 31 icon: "view_quilt" toc: true sidebar: false search_boost: 0.7 reading_time: 16 estimated_setup_time: 20 version: "1.0" related_docs: - "dynamic-fields-inventory" - "dynamic-fields-field-catalog" - "dynamic-fields-field-selection-guide" - "dynamic-fields-inline-filter-catalog" keywords: - "playable catalog" - "landing playground" - "source of truth" - "registry parity" last_updated: "2026-03-26" --- # Dynamic Fields Playground Catalog Plan ## Objective Definir a modelagem canonica para um catalogo jogavel de `@praxisui/dynamic-fields` que possa ser consumido por `praxis-ui-landing-page` na rota `playground` sem criar uma lista manual paralela no host. ## Problem statement Hoje existem tres camadas com papeis diferentes: 1. `ComponentRegistryService` - define o suporte runtime real dos fields registrados por default 2. metadata exports e docs governadas - descrevem friendly names, iconografia, uso recomendado, inventario e narrativa oficial 3. landing/playground - publica docs e experiencias exploratorias para squads O problema atual e que a landing ainda precisa montar algumas sementes manuais para navegacao/catalogo, enquanto o `playground` existente foi desenhado para macrocomponentes (`praxis-table`, `praxis-list`, `praxis-dynamic-form`), nao para dezenas de fields. ## Canonical source-of-truth model ### Runtime truth A fonte de verdade do suporte default continua sendo o runtime da lib: - `projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.ts` - `projects/praxis-core/src/lib/utils/inline-filter-controls.util.ts` Essa camada responde: - quais `controlType` existem - quais sao canonicamente registrados por default - quais aliases existem por compatibilidade ### Published catalog truth O catalogo jogavel nao deve nascer na landing. Ele deve ser publicado pela lib canonica como um export agregado e tipado. Essa camada responde: - quais `controlType` devem aparecer para descoberta publica - em qual `track` e `family` cada item entra - quais estados sao demonstraveis - qual snippet usar - quais docs oficiais linkar - quais tags e notas de UX expor ### Documentation truth As docs governadas continuam sendo a narrativa oficial e a superficie editorial publica: - inventario runtime-first - field catalog - field selection guide - inline filter catalog Essas docs nao devem ser parseadas para dirigir o preview. Elas devem ser referenciadas pelo catalogo exportado. ## Non-goals Este plano nao pretende: - transformar markdown em fonte primária do runtime - permitir que a landing invente `controlType` ou families locais - misturar aliases reconhecidos internamente como se fossem escolhas novas recomendadas - substituir o `ComponentRegistryService` como prova de suporte real - virar um builder visual completo dentro do `playground` ## Proposed architecture Criar uma nova superficie publica em `@praxisui/dynamic-fields`: - `DynamicFieldCatalogEntry` - `DynamicFieldCatalogTrack` - `DynamicFieldCatalogFamily` - `DynamicFieldPreviewRecipe` - `DYNAMIC_FIELDS_PLAYGROUND_CATALOG` Essa superficie deve ser: - publicada no `public-api.ts` - derivada do runtime real - enriquecida com metadata/governanca - consumida pela landing e pelo playground ## Catalog entry contract Cada entry do catalogo deve conter no minimo: - `id` - `controlType` - `track` - `primary-form` - `inline-filter` - `family` - `status` - `friendlyName` - `description` - `tags` - `keywords` - `valueShape` - `recommendedWhen` - `avoidWhen` - `dataSourceKind` - `supportsStates` - `docs` - `catalogSlug` - `detailFragment` - `selectionGuideSlug` - `overviewSlug?` - `jsonApiPath?` - `previewRecipe` - `snippetRecipe` - `a11yNotes?` - `themingNotes?` ## Governance rules ### Rule 1. The landing is a consumer `praxis-ui-landing-page` nao pode manter o catalogo de Dynamic Fields como fonte primaria. ### Rule 2. Runtime parity is mandatory Todo item publicado no catalogo precisa corresponder a um `controlType` realmente registrado por default no runtime, exceto quando marcado explicitamente como `experimental` ou `host-owned`. ### Rule 3. Docs are linked, not parsed O catalogo aponta para docs governadas por slug/fragment. O preview nao depende de parsing de markdown. ### Rule 4. Inline filters remain a separate track `inline*` continua sendo trilha especializada. O catalogo jogavel pode expor essa trilha, mas sem misturar a narrativa de formulario comum. ### Rule 5. Aliases are not discovery-first Aliases como `dateTime` ou `treeView` continuam existindo por compatibilidade, mas nao entram como escolha principal no catalogo. ### Rule 6. States are governed Estados como `default`, `filled`, `disabled`, `readonly` e `error` devem ser definidos por recipes governadas na lib, nao por patches soltos no host. ## Recommended rollout ### Phase 1. Contract and recipes Publicar tipos e recipes basicas de estado dentro da lib. ### Phase 2. Canonical catalog export Publicar o catalogo agregado da lib e exporta-lo em `public-api.ts`. ### Phase 3. Registry parity tests Adicionar testes de paridade catalogo x runtime. ### Phase 4. Docs alignment Atualizar inventario e catalogos governados para reconhecer o novo artefato publicado. ### Phase 5. Landing adoption Trocar seeds manuais de `dynamic-fields` na landing por derivacao do catalogo exportado. ### Phase 6. Playground adoption Adaptar o playground para suportar items do tipo `field`, com preview host canonico minimo e painel de detalhe. ## Validation requirements Validacoes minimas esperadas ao implementar este plano: - build focal de `praxis-dynamic-fields` - teste focal de paridade catalogo x registry - build focal da landing - smoke da vitrine/playground - verificacao de foco, teclado, contraste e links para docs oficiais ## Success criteria O plano sera considerado bem-sucedido quando: - a landing deixar de manter listas soltas de Dynamic Fields - a fonte de verdade do catalogo jogavel passar a estar na lib canonica - docs, runtime e vitrine permanecerem coerentes - novos fields conseguirem entrar no ecossistema com uma trilha previsivel: - runtime - metadata - catalogo - docs - preview ## Implementation note Este documento e um artefato de planejamento de plataforma. Ele nao substitui: - `dynamic-fields-inventory.md` como auditoria runtime-first - `dynamic-fields-field-catalog.md` como referencia funcional - `dynamic-fields-inline-filter-catalog.md` como trilha especializada Ele apenas fixa a fronteira correta para a evolucao da surface jogavel.