@praxisui/list 9.0.67 → 9.0.68-rc.0

package/README.md

@@ -97,13 +97,17 @@ For HATEOAS records, the canonical `_links.self.href` is the preferred render id
 - `queryContext?: PraxisDataQueryContext`: runtime query context projected into remote data.
 - `form?: FormGroup`: external form context for selection/form bindings.
 - `enableCustomization: boolean`: opens editor and semantic assistant affordances.
-- `itemClick`, `actionClick`, `selectionChange`, `exportAction`: public events.
+- `itemClick`, `actionClick`, `selectionChange`, `exportAction`: public interaction events.
+- `configPatchChange`: explicit `{ inputPatch: { config: PraxisListConfig } }` after valid native editor Apply/Save or adapter authoring. Dynamic Page/Page Builder updates its authored page so a later Save Page preserves the edit. Hydration, schema inference, runtime filters and selection do not emit this output. The detached config snapshot excludes runtime query context; existing standalone persistence remains governed by `configPersistenceStrategy`.
+
+The hosted list editor exposes **Configuration source** (`configPersistenceStrategy`). Choose **Page configuration** (`input-first`) for a composed page: saved individual list preferences must not replace the page document on reload. **Individual list preferences** preserves `local-first`; **Temporary configuration** uses `volatile`. The choice participates in Apply, Save and Reset alongside the child config, and does not silently replace an existing policy.
 
 ## Configuration Highlights
 
 - Layout variants: `list`, `cards`, `tiles`.
 - Runtime-active layout fields include `lines`, `dividers`, `groupBy`, `pageSize`, `density` and `model`.
 - Templating slots include `leading`, `primary`, `secondary`, `meta`, `trailing`, `features`, `sectionHeader` and `emptyState`.
+- Leading images delegated to Rich Content stay within their reserved track and retain their aspect ratio. Skin overrides are rendered in an instance-scoped style element, using the supplied CSP nonce; updates replace that element's content and destruction removes it. Appearance presets wrap within narrow editors.
 - In `layout.rowLayout`, canonical semantic slots keep the configured desktop grid and reflow into ordered, non-overlapping rows at narrow viewports; extended operational slots stack without requiring host CSS.
 - Template expressions use `${item.field}`. Currency/date/number templates can use config i18n defaults.
 - Selection supports `none`, `single` and `multiple`, with return modes `value`, `item` or `id`.
@@ -122,13 +126,20 @@ Do not document those as active runtime behavior in app-specific guides until th
 
 `enableCustomization` opens the canonical list editor and semantic assistant flow. `PRAXIS_LIST_AUTHORING_MANIFEST` is the executable authoring contract for template slots, actions, empty state, selection, layout, data binding, rules, skin, export, localization, accessibility and declared-only warnings.
 
+The runtime opens its canonical editor when `openConfigEditor()` is invoked; the public `openConfigEditor(): void` method remains stable for templates and host integrations. Generic authoring hosts resolve the editor through `PRAXIS_LIST_COMPONENT_METADATA.configEditor.loadComponent`. This asynchronous resolution does not guarantee a separate downloaded chunk: the public root entrypoint also exports the editor classes, so packaging can include them in the same JavaScript module as the runtime.
+
 `actions[].recordOpen` is runtime materialization evidence produced by governed platform authoring. It round-trips through list config but is intentionally not a free-form field in the visual editor or the list-specific AI manifest. Authors choose business intent; Metadata and Config publish the canonical source field and target identities.
 
 Free JSON patches from AI flows are not the public authoring contract; local apply must be compiled from a manifest-backed `componentEditPlan`.
 
+Invalid JSON in a Surface action remains an unsaved draft and blocks Apply/Save.
+Its validity is combined with raw JSON and document/query validation; visiting
+another tab preserves the text, and Reset discards it explicitly. See
+[Surface consumer validation](../praxis-core/docs/surface-draft-consumers-validation-2026-09-08.md).
+
 ## Public API Snapshot
 
-Main exports include `PraxisList`, editor components, `PraxisListConfig`, list data services, templating/rich-content/selection adapters, metadata provider, list i18n helpers, AI capabilities, `PRAXIS_LIST_AUTHORING_MANIFEST` and `PraxisListDocPageComponent`.
+The root `@praxisui/list` entrypoint exports `PraxisList`, `PraxisListConfig`, list data services, templating/rich-content/selection adapters, metadata provider, list i18n helpers, AI capabilities, `PRAXIS_LIST_AUTHORING_MANIFEST` and `PraxisListDocPageComponent`. It also preserves the public editor classes `PraxisListConfigEditor` and `PraxisListWidgetConfigEditor`, and the types `PraxisListWidgetEditorInputs` and `PraxisListWidgetEditorValue`. Hosts can import these names directly from `@praxisui/list`; generic authoring hosts should resolve the configured editor through component metadata.
 
 ## Official Links
 

package/ai/component-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-09-07T00:54:55.301Z",
+  "generatedAt": "2026-09-09T10:03:24.330Z",
   "packageName": "@praxisui/list",
-  "packageVersion": "9.0.67",
+  "packageVersion": "9.0.68-rc.0",
   "sourceRegistry": "praxis-component-registry-ingestion",
   "sourceRegistryVersion": "1.0.0",
   "componentCount": 1,
@@ -56,6 +56,12 @@
         }
       ],
       "outputs": [
+        {
+          "name": "configPatchChange",
+          "type": "{ inputPatch: { config: PraxisListConfig } }",
+          "required": false,
+          "description": "Alteração explícita do editor ou adapter para atualizar a configuração autorada na página; não emite hidratação, filtros ou seleção runtime."
+        },
         {
           "name": "itemClick",
           "type": "ListItemEvent",
@@ -476,7 +482,6 @@
         }
       ],
       "configEditor": {
-        "component": "[ref:PraxisListWidgetConfigEditor]",
         "title": "Configure list"
       },
       "authoringManifestRef": {
@@ -9061,9 +9066,9 @@
         {
           "chunkIndex": 0,
           "chunkKind": "summary",
-          "content": "Component ID: praxis-list\nSelector: praxis-list\nFriendly Name: Praxis List\nDescription: Lista com suporte a seleção (single/multiple), agrupamento e templates.\nLib/Package: @praxisui/list\nTags: widget, list, lista, selection, configurable\nInputs:\n  - config (PraxisListConfig)\n  - listId (string)\n  - componentInstanceId (string)\n  - configPersistenceStrategy ('local-first' | 'input-first' | 'volatile')\n  - queryContext (PraxisDataQueryContext | null)\n  - form (FormGroup)\n  - enableCustomization (boolean)\nOutputs:\n  - itemClick (ListItemEvent)\n  - actionClick (ListActionEvent)\n  - selectionChange (ListSelectionEvent)\n",
+          "content": "Component ID: praxis-list\nSelector: praxis-list\nFriendly Name: Praxis List\nDescription: Lista com suporte a seleção (single/multiple), agrupamento e templates.\nLib/Package: @praxisui/list\nTags: widget, list, lista, selection, configurable\nInputs:\n  - config (PraxisListConfig)\n  - listId (string)\n  - componentInstanceId (string)\n  - configPersistenceStrategy ('local-first' | 'input-first' | 'volatile')\n  - queryContext (PraxisDataQueryContext | null)\n  - form (FormGroup)\n  - enableCustomization (boolean)\nOutputs:\n  - configPatchChange ({ inputPatch: { config: PraxisListConfig } })\n  - itemClick (ListItemEvent)\n  - actionClick (ListActionEvent)\n  - selectionChange (ListSelectionEvent)\n",
           "sourcePointer": "projects/praxis-list/src/lib/praxis-list.metadata.ts",
-          "contentHash": "f589cb2341d7a23ed3df996c9d11ffb8902a62747c54cf3c16187b503ab0df9a",
+          "contentHash": "edfe4ebebb53222fa9c50c8dfce03f969d98f8efb5068b074dc51df5fb864e4a",
           "sourceKind": "component_definition",
           "sourceId": "praxis-list",
           "corpusVersion": "1.0.0"

package/docs/2026-09-09-editor-public-api-investigation.md

@@ -0,0 +1,189 @@
+# Investigação da API pública dos editores List — 2026-09-09
+
+> Registro da investigação inicial; a correção autorizada posteriormente está
+> documentada em “Implementação e validação da correção” ao final.
+
+## Pergunta e escopo
+
+O usuário solicitou investigar se a remoção dos editores foi um erro, antes de
+escolher preservar imports ou preparar uma publicação incompatível.
+Classificação do experimento: `contrato-publico`; entrega desta investigação:
+documentação e ferramenta de auditoria. Nenhuma variante experimental foi
+aplicada ao checkout compartilhado ou publicada.
+
+Fonte canônica: `projects/praxis-list/src/public-api.ts`, os dois editores e
+`praxis-list.metadata.ts`. Consumidor direto: Stepper, que importa metadata de
+List em seu editor. Page Builder resolve o configurador por metadata. Não foi
+encontrado import direto das quatro declarações em outros componentes de
+`projects/`, `src/` e `examples/` deste checkout; isso não prova ausência de hosts
+externos. Os símbolos já eram públicos e documentados, não uma nova necessidade
+ou uma fachada de símbolos pertencentes a outra biblioteca.
+
+Base isolada: `7c9badae7394166101da96fbab084f1a8db2f34d`.
+Commit da remoção: `edb8c2565fe9d4ee23d4d3903b46350fd6fef080`.
+A tarefa paralela de navegação de editores não participa desta evidência.
+
+## O que foi removido e por quê
+
+O mesmo commit retirou duas linhas de `export *`, tornou lazy a resolução do
+configurador na metadata e a abertura por `PraxisList.openConfigEditor()` e
+passou a documentar editores opcionais fora do barrel de runtime. Portanto há
+uma intenção explícita de carregamento sob demanda. Não encontramos, nos
+arquivos de histórico e documentação inspecionados, uma falha reproduzida de
+ciclo que justificasse especificamente a retirada dos exports públicos.
+
+O pacote **realmente publicado** `@praxisui/list@9.0.67` contém quatro nomes que
+somem do candidato atual:
+
+- Classes: `PraxisListConfigEditor`, `PraxisListWidgetConfigEditor`.
+- Interfaces: `PraxisListWidgetEditorInputs`, `PraxisListWidgetEditorValue`.
+
+Baseline npm: `https://registry.npmjs.org/`, tarball `praxisui-list-9.0.67.tgz`;
+SHA-1 do tarball: `ee84020b086a6b0c26a12f9014f0702c2c30dd25`;
+SHA-256 da declaração: `552819ed07fe9b0cda6cd2cdf724bc7c5c2e4317ec0d61d6e032c6a2fd365f84`.
+Os imports de classes/componentes usados em templates não são substituídos
+transparentemente por uma função assíncrona em metadata.
+
+## Experimentos controlados
+
+Todas as variantes usam as mesmas dependências e configuração do checkout
+isolado. Nenhum package.json, tsconfig ou configuração de build foi alterado.
+
+| Variante | Exports ausentes contra npm | Resultado | Separação dos editores |
+| --- | --- | --- | --- |
+| Atual, sem os dois `export *` | 4 | Build List + Stepper; imports ESM passam | Dois chunks de editores separados |
+| Restaurar os dois `export *`, mantendo loaders no fonte | 0 | Build List + Stepper; imports ESM; consumidor TS estrito; 48 testes passam | Um único FESM; loaders viram `Promise.resolve()` |
+| Restaurar somente as duas interfaces com `export type` | 2 classes | Build List e comparação de exports passam como experimento; gate continua acusando as 2 remoções | JavaScript executável idêntico à variante atual |
+
+Na restauração completa, o loader da metadata retorna exatamente a classe
+exportada; não há duplicação de classe ou erro de inicialização nas importações
+ESM de List e Stepper testadas. Os 48 testes existentes cobrem metadata,
+`list-config-editor` e `list-widget-config-editor`. Isso não constitui teste de
+todos os hosts, SSR ou certificação visual/E2E da variante.
+
+Na variante atual, o entrypoint e o módulo runtime somam **1.076.605 bytes**;
+os dois módulos de editores somam **648.541 bytes**. Restaurando os exports,
+o FESM único tem **1.721.700 bytes**. São bytes de JavaScript parcial Angular,
+sem compressão ou otimização de um aplicativo host. Não representam download
+final, tempo de interação nem aumento equivalente no bundle de todo consumidor.
+O total do pacote não aumentou: mudou principalmente o momento em que o código
+pode ser carregado.
+
+A variante de tipos foi compilada diretamente com `ng build praxis-list`;
+o fluxo oficial de produção também remove comentários de source maps. Após
+normalizar somente esses comentários **em memória para comparar**, todos os
+quatro hashes JS coincidem com a variante atual. Nenhum artefato gerado foi
+editado manualmente para obter esse resultado.
+
+## Diagnóstico e decisão recomendada
+
+1. **Erro confirmado na retirada das interfaces.** Ela não era necessária para
+   carregar editores sob demanda. `export type` preserva o contrato existente
+   sem trazer o código dos editores para o módulo principal.
+2. **Benefício técnico confirmado na separação das classes.** A otimização não
+   era fictícia. Porém, a remoção alterou uma API já publicada e documentada.
+3. **Não foi demonstrado que restaurar as classes causa falha funcional.** O
+   build, consumidor, importação e testes focais passaram. A consequência
+   demonstrada é a perda do splitting obtido depois da versão pública 9.0.67.
+4. **O erro de governança foi misturar otimização com remoção pública sem um
+   tratamento explícito de compatibilidade.** Não classificar automaticamente
+   como patch compatível nem escolher uma nova major para justificar a alteração.
+
+Para uma próxima publicação que preserve o contrato já oferecido aos hosts,
+recomenda-se restaurar os quatro exports e ajustar a promessa documental de
+lazy loading. Isso recupera declarações originais do dono canônico, sem alias,
+DTO duplicado ou fachada entre bibliotecas. Se o requisito prioritário passar
+a ser uma fronteira pública separada para os editores, preparar uma proposta
+arquitetural de entrypoint editorial e migração explícita dos imports. Manter
+as classes estaticamente reexportadas na raiz não garante isolamento lazy,
+mesmo que exista um novo entrypoint. Essa decisão não foi tomada pelo usuário
+nesta investigação; ele solicitou primeiro esclarecer se a retirada estava errada.
+
+O estado atual com quatro remoções **não está liberado como publicação
+compatível**. A variante somente com interfaces também não resolve a quebra dos
+imports das classes e não deve ser apresentada como correção completa.
+
+## Reprodução mínima
+
+Em um checkout isolado, instalar com `npm ci --no-audit --fund=false`, obter o
+tarball público com `npm pack @praxisui/list@9.0.67 --registry=https://registry.npmjs.org/`
+e descompactá-lo. Usar os mesmos argumentos de build nas variantes completas:
+
+```bash
+node scripts/build-libs.js --prod --only praxis-list,praxis-stepper
+node tools/compare-package-exports.mjs /caminho/baseline/package dist/praxis-list
+node --input-type=module -e "await import('@angular/compiler'); await import('@praxisui/list'); await import('@praxisui/stepper');"
+node node_modules/@angular/cli/bin/ng.js test praxis-list --watch=false --progress=false --browsers=ChromeHeadless --include=projects/praxis-list/src/lib/praxis-list.metadata.spec.ts --include=projects/praxis-list/src/lib/editors/list-widget-config-editor.component.spec.ts --include=projects/praxis-list/src/lib/editors/list-config-editor.component.spec.ts
+```
+
+O gate de comparação verifica nomes exportados, incluindo interfaces, e hashes
+da declaração. Não certifica assinaturas, subpaths ou comportamento. A prova
+adicional TypeScript usou imports dos quatro nomes por `@praxisui/list`,
+atribuição de `{ inputs: { listId, config: {} } }` ao tipo público e compilação
+`strict`, `noEmit`, `NodeNext`, sem caminhos privados de fonte.
+
+## Documentação, skills e limites
+
+A skill `praxis-angular-public-api-governance` incorpora a separação entre tipos,
+valores, imports públicos e chunks emitidos. O relatório de prontidão aponta
+para esta investigação. Não há mudança de metadata, JSON, tokens, registry AI,
+contratos backend, configuração de hosts ou conteúdo visual neste fechamento;
+portanto não há artefato derivado desses contratos a regenerar. A recomendação
+de implementação ainda exige atualizar README público e sua projeção na landing
+quando a política final de export/loading for escolhida.
+
+Angular MCP executado: `list_projects`, `get_best_practices`,
+`search_documentation` (além da listagem de ferramentas). Foram mantidos tipos
+estritos na prova de consumidor, responsabilidade dos componentes e configuração
+original. A busca MCP falhou por indisponibilidade do serviço; consulta direta
+à documentação oficial confirmou a relação entre entrypoints e code splitting:
+[Angular Package Format](https://angular.dev/tools/libraries/angular-package-format)
+e [Creating Libraries](https://angular.dev/tools/libraries/creating-libraries).
+
+Nenhum bump, tag, publicação, deploy ou teste E2E da restauração foi realizado.
+Os experimentos não alteraram o servidor compartilhado na porta 4003.
+
+## Implementação e validação da correção
+
+Após a investigação, o usuário autorizou seguir a recomendação. Foram restaurados
+os dois `export *` originais no dono List, recuperando os quatro nomes. Os loaders
+na metadata e em `openConfigEditor()` foram mantidos; o README agora distingue
+abertura do editor e carregamento do JavaScript, sem garantir chunks separados.
+Nenhuma configuração de build, dependência, payload ou manifesto foi alterado.
+
+Foi adicionado `src/lib/list-public-api.spec.ts`, que importa as classes e as
+interfaces pelo barrel público e verifica que a metadata resolve a mesma classe
+exportada. A validação desta implementação produziu:
+
+- Build oficial isolado de List e Stepper com sincronização das dependências: passou.
+- Importação ESM dos pacotes compilados e identidade do editor resolvido: passou.
+- Comparação com o tarball npm 9.0.67: nenhum nome removido, no build isolado e no
+  build focal de List no checkout compartilhado.
+- Testes focais de API, metadata e dois editores: **49/49**.
+- Testes da ferramenta de comparação: **6/6**.
+- E2E `list-authoring-canonical.playwright.spec.ts`: **1/1**, no origin oficial
+  `http://localhost:4003`, em contexto isolado. Provou abertura, aplicação JSON,
+  salvamento, atualização do runtime, reload e reabertura com o valor preservado.
+  A captura do painel foi inspecionada. O host usa os paths de fonte oficiais;
+  a prova do pacote compilado foi feita separadamente pelas importações acima.
+
+A evidência E2E foi arquivada em `/private/tmp/list-api-fix-browser-evidence`;
+o runner sobrescreveu artefatos históricos rastreados, que foram restaurados
+sem incorporar exclusões ou relatórios transitórios ao commit.
+
+As skills `praxis-angular-public-api-governance` e
+`praxis-list-authoring-settings` foram atualizadas, validadas e sincronizadas.
+A skill `praxis-authoring-editors`, revisada pela tarefa de navegação de editores,
+também foi sincronizada nesta rodada; sua evidência de runtime pertence àquela
+tarefa. As auditorias finais registram Praxis **167/167** e Ergon **19/19** sem
+drift, itens ausentes ou fonte inválida.
+
+A sincronização oficial de vendor docs na landing não produziu alteração por
+List: o artefato publicado é `praxis-list.json-api.md`, não seu README. A API JSON
+permanece intacta. Check vendor, governança de 145 guias e sitemap passaram.
+Não foi necessário regenerar registry AI/backend, pois os contratos declarativos
+continuam iguais. A nova documentação de exports acompanha o README do pacote.
+
+A remoção dos quatro nomes foi corrigida. Esta prova focal não substitui o
+preflight integral de uma futura publicação de todas as bibliotecas, nem certifica
+compatibilidade de todas as assinaturas. Não houve bump, tag, publicação ou deploy.