@controleonline/ui-default 1.0.270 → 1.0.273

package/.github/workflows/integration-source-gate.yml

@@ -0,0 +1,68 @@
+name: Integration source gate
+
+on:
+  pull_request:
+    branches: [dev, staging, master]
+    types: [opened, synchronize, reopened, edited, ready_for_review]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  source-policy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Enforce task or frozen RC source
+        env:
+          HEAD_REF: ${{ github.head_ref }}
+          BASE_REF: ${{ github.base_ref }}
+        run: |
+          set -eu
+          if [ "$BASE_REF" = "dev" ]; then
+            echo "$HEAD_REF" | grep -Eq '^task-[1-9][0-9]*$' || {
+              echo "::error::dev only accepts task-<numeric issue>."
+              exit 1
+            }
+            exit 0
+          fi
+          echo "$HEAD_REF" | grep -Eq '^rc/[0-9]+\.[0-9]+\.[0-9]+-rc\.[1-9][0-9]*$' || {
+            echo "::error::$BASE_REF only accepts a frozen rc/X.Y.Z-rc.N source."
+            exit 1
+          }
+
+      - uses: actions/checkout@v4
+        if: github.base_ref != 'dev'
+        with:
+          ref: ${{ github.head_ref }}
+
+      - name: Validate frozen RC manifest
+        if: github.base_ref != 'dev'
+        env:
+          HEAD_REF: ${{ github.head_ref }}
+        run: |
+          set -eu
+          test -f .release/rc-manifest.json || {
+            echo "::error::Missing .release/rc-manifest.json"
+            exit 1
+          }
+          node --input-type=module <<'NODE'
+          import fs from 'node:fs';
+          const m = JSON.parse(fs.readFileSync('.release/rc-manifest.json', 'utf8'));
+          const branch = process.env.HEAD_REF;
+          const match = /^rc\/(\d+\.\d+\.\d+)-rc\.([1-9][0-9]*)$/.exec(branch);
+          if (!match) throw new Error('invalid RC branch');
+          if (m.branch !== branch || m.version !== match[1] || Number(m.rc) !== Number(match[2])) throw new Error('manifest identity mismatch');
+          if (m.frozen !== true) throw new Error('manifest is not frozen');
+          if (!Array.isArray(m.tasks) || m.tasks.length < 1 || m.tasks.length > 5) throw new Error('RC must contain 1..5 tasks');
+          const tasks = m.tasks.map(Number);
+          if (tasks.some((id) => !Number.isInteger(id) || id < 1)) throw new Error('invalid task id');
+          if (new Set(tasks).size !== tasks.length) throw new Error('duplicate RC tasks');
+          if (!/^[0-9a-f]{40}$/i.test(String(m.baseMaster || ''))) throw new Error('invalid baseMaster');
+          const repos = m.repositories || {};
+          if (!Object.keys(repos).length) throw new Error('empty repositories manifest');
+          for (const [repo, sha] of Object.entries(repos)) {
+            if (!/^ControleOnline\/[A-Za-z0-9_.-]+$/.test(repo) || !/^[0-9a-f]{40}$/i.test(String(sha))) throw new Error('invalid repository manifest entry');
+          }
+          console.log('Frozen RC manifest valid:', branch, tasks);
+          NODE

package/.github/workflows/manager-worker.yml

@@ -0,0 +1,19 @@
+name: Manager Worker
+
+on:
+  workflow_dispatch:
+
+# PAUSA CTO ControleOnline/agents-mcp#201 (2026-08-29)
+# Trigger original desativado: push em master, dev, staging.
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  manager:
+    name: Manager — paused
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Manager Worker paused by ControleOnline/agents-mcp#201"

package/.github/workflows/publish-npm.yml

@@ -0,0 +1,91 @@
+name: Publish Package to npmjs
+
+on:
+  push:
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: ${{ github.repository }}-npm-release
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    if: ${{ github.repository_owner == 'ControleOnline' && (github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/v')) }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref }}
+          fetch-depth: 0
+      - name: Validate package metadata and create version tag
+        id: release
+        env:
+          REF_TYPE: ${{ github.ref_type }}
+          REF_NAME: ${{ github.ref_name }}
+          EXPECTED_REPOSITORY: ${{ github.repository }}
+        run: |
+          node <<'NODE'
+          const fs = require('node:fs');
+          const cp = require('node:child_process');
+          const pkg = require('./package.json');
+          const expectedUrl = `https://github.com/${process.env.EXPECTED_REPOSITORY}`;
+          if (!/^\d+\.\d+\.\d+$/.test(String(pkg.version))) throw new Error(`Expected stable X.Y.Z, got ${pkg.version}`);
+          if (pkg.repository?.url !== expectedUrl) throw new Error(`repository.url must be ${expectedUrl}; got ${pkg.repository?.url}`);
+          const sourceSha = cp.execFileSync('git', ['rev-parse', 'HEAD'], {encoding:'utf8'}).trim();
+          let tag = '';
+          if (process.env.REF_TYPE === 'tag') {
+            tag = process.env.REF_NAME;
+            if (tag !== `v${pkg.version}`) throw new Error(`Tag ${tag} does not match package version ${pkg.version}`);
+          } else {
+            let previous = '';
+            try { previous = JSON.parse(cp.execFileSync('git', ['show', `${sourceSha}^:package.json`], {encoding:'utf8'})).version || ''; } catch {}
+            if (previous === pkg.version) { fs.appendFileSync(process.env.GITHUB_OUTPUT, 'release_tag=\n'); process.exit(0); }
+            const parts = String(pkg.version).split('.').map(Number);
+            if (previous) {
+              const old = String(previous).split('.').map(Number);
+              let cmp = 0; for (let i=0;i<3;i++) { if ((parts[i]||0)!==(old[i]||0)) { cmp=(parts[i]||0)>(old[i]||0)?1:-1; break; } }
+              if (cmp <= 0) throw new Error(`Version ${pkg.version} must be greater than first-parent version ${previous}`);
+            }
+            tag = `v${pkg.version}`;
+            const existing = cp.spawnSync('git', ['ls-remote', '--exit-code', '--refs', 'origin', `refs/tags/${tag}`], {encoding:'utf8'});
+            if (existing.status === 0) {
+              cp.execFileSync('git', ['fetch', 'origin', `refs/tags/${tag}:refs/tags/${tag}`], {stdio:'inherit'});
+              const tagged = cp.execFileSync('git', ['rev-parse', `${tag}^{commit}`], {encoding:'utf8'}).trim();
+              if (tagged !== sourceSha) throw new Error(`Immutable tag ${tag} already points at ${tagged}, not ${sourceSha}`);
+            } else {
+              cp.execFileSync('git', ['config', 'user.name', 'github-actions[bot]']);
+              cp.execFileSync('git', ['config', 'user.email', '41898282+github-actions[bot]@users.noreply.github.com']);
+              cp.execFileSync('git', ['tag', '-a', tag, sourceSha, '-m', `Release ${pkg.name}@${pkg.version}`], {stdio:'inherit'});
+              cp.execFileSync('git', ['push', 'origin', `refs/tags/${tag}`], {stdio:'inherit'});
+            }
+          }
+          fs.appendFileSync(process.env.GITHUB_OUTPUT, `release_tag=${tag}\n`);
+          console.log(`Validated ${pkg.name}@${pkg.version} from ${sourceSha}; release tag ${tag}`);
+          NODE
+      - uses: actions/setup-node@v4
+        if: steps.release.outputs.release_tag != ''
+        with:
+          node-version: 24
+      - name: Ensure npm 11.5.1+ (OIDC support)
+        if: steps.release.outputs.release_tag != ''
+        run: |
+          npm install --global npm@latest
+          npm --version
+      - name: Skip if version is already on npm
+        id: registry
+        if: steps.release.outputs.release_tag != ''
+        run: |
+          PACKAGE_NAME=$(node -p "require('./package.json').name")
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          if npm view "$PACKAGE_NAME@$PACKAGE_VERSION" version >/dev/null 2>&1; then
+            echo 'published=true' >> "$GITHUB_OUTPUT"
+            echo "$PACKAGE_NAME@$PACKAGE_VERSION is already published; skipping duplicate publish"
+          else
+            echo 'published=false' >> "$GITHUB_OUTPUT"
+          fi
+      - name: Publish to npmjs with trusted publishing
+        if: steps.release.outputs.release_tag != '' && steps.registry.outputs.published != 'true'
+        run: npm publish --access public --loglevel verbose

package/AGENTS.md

@@ -1,50 +1,46 @@
-# ui-default
-
-## Escopo
-
-- Biblioteca base de componentes reutilizaveis do front.
-- `DefaultTable` e o shell canonico de listagens React deste sistema.
-
-## Contrato do DefaultTable
-
-- A tela deve passar preferencialmente apenas `storeName` e contexto minimo, como `requestParams`, `onRowPress`, `renderCard`, `onAdd`, `onEdit` ou componentes extras realmente especificos.
-- O componente pode receber componentes de composicao para variacoes visuais, como `renderCard`, add personalizado, toolbar customizada, acoes auxiliares e modais de apoio; isso nao muda o contrato de que a listagem continua sendo responsabilidade do `DefaultTable`.
-- Quando `data` nao e informada e existe `storeName`, o `DefaultTable` trabalha em modo automatico e carrega os itens pelas actions do store.
-- O componente e responsavel por busca, ordenacao, filtros, paginação, infinite scroll, loading, erro, resumo, visibilidade de colunas, modo desktop e modo card no mobile.
-- Preferencias de usuario do `DefaultTable`, incluindo filtros, busca, ordenacao, modo de exibicao e visibilidade de colunas, devem ser salvas em `localStorage` na chave `default-table`, sempre no formato `[store][rota] = valores`. Nunca usar chave apenas por store ou apenas por rota.
-- O store nao e fallback: ele e a regra. Se `columns` define um comportamento, o `DefaultTable` deve obedecer sem recriar uma segunda regra na tela.
-- `columns` e a fonte de verdade para label, visibilidade, ordem, `editable`, `sortable`, `inputType`, `list`, `format`, `formatList`, `formatFilter`, `saveFormat`, `searchParam`, `externalFilter`, `summary` e `defaultSort`. `show:false` e um alias aceito para ocultar coluna, junto com `visible:false` e `table:false`.
-- Se uma coluna vier como `editable: false`, ela continua nao editavel mesmo que seja ordenavel. Se vier como `sortable: true`, a ordenacao precisa continuar funcionando.
-- `inputType: 'date-range'` exige filtro de intervalo. `externalFilter: true` habilita o filtro externo quando a listagem suporta esse contrato.
-- Campos `list` e selects com listas nao devem ser pre-carregados no mount nem na abertura do modal inteiro. O carregamento das opcoes acontece no `onBeforeOpen` do proprio campo ou filtro, para evitar requests globais desnecessarios.
-- Nada de search local, sort local, paginacao manual, contador local, total calculado por `reduce` ou cards paralelos quando o `DefaultTable` ja puder resolver isso pelo store.
-- `requestParams` serve para contexto fixo do fluxo, nao para duplicar estado de filtro que ja vive no store.
-- `pageSize` so deve ser usado quando o contrato externo exigir e com justificativa clara no modulo.
-- `summary` e `totalItems` vem do backend/store e pertencem ao rodape interno do `DefaultTable`.
-- `add: true` abre o `DefaultForm` quando a tela nao prover `onAdd`.
-- `rowActionsComponent` e o slot canonico para acoes por linha quando a tela precisa renderizar mais do que o botao padrao de edicao. Ele pode ser componente, funcao ou elemento React, recebe `row`, `storeName`, `openEdit`, `openRow` e `helpers`, e a largura da coluna deve ser ajustada com `rowActionsWidth` quando houver mais de uma acao.
-- O modo controlado continua existindo apenas para excecoes reais de integracao; o padrao do sistema e o modo store-driven.
-- Loadings e erros devem seguir o fluxo central do sistema, sem banners ou estados paralelos na tela.
-- O `get` do store default pode preservar o `item` atual durante refresh quando receber `__storeMeta.preserveItem = true`; use esse modo quando a tela precisa atualizar o registro sem desmontar o detalhe em exibição.
-- Explicacoes permanentes de tela devem sair do corpo principal e ir para o `DefaultTooltip`, acionado por `?`, quando houver contexto necessario para o usuario.
-
-## Componentes de feedback
-
-- `StateStore` e o shell compartilhado para loading e saving de tela/seção.
-- O `mode` do `StateStore` e um preset generico do shell e pode variar conforme a tela; exemplos validos incluem `compact`, `display` e outros modos reais do fluxo.
-- `DefaultErrors` e o shell compartilhado para erro local/inline de tela ou tab; ele lê o `error` dos stores informados, aparece como popup, auto-fecha em 5 segundos e limpa o erro do store ao ser fechado.
-- `showError` continua sendo feedback transitório global; nao deve substituir `DefaultErrors` quando o erro for inline ou local.
-- Telas e componentes visuais nao devem usar `ActivityIndicator` direto quando o estado puder ser representado por `StateStore`.
-- O contrato de explicacao permanente continua sendo `DefaultTooltip`, sempre acionado por `?` e fora do corpo principal da tela.
-
-## Arquivos e imagens
-
-- `DefaultFile` e o componente compartilhado para arquivos/imagens vindos do backend.
-- Quando a fonte for um arquivo de download do backend, o componente deve resolver a URL com `app-domain=<dominio configurado>` e enviar o mesmo valor em `headers` quando a plataforma permitir.
-- Telas que exibem logo, fundo, avatar, banner ou qualquer arquivo de empresa devem preferir `DefaultFile` em vez de `Image` direto quando o contrato vier do backend.
-
-## Regra de uso
-
-- Telas antigas devem ser simplificadas para passar o store e apenas as excecoes declarativas que o store nao cobre.
-- Se a listagem precisa de outra regra de exibicao, a primeira opcao e mover essa regra para `columns` ou para o store correspondente.
-- Se duas telas repetem a mesma logica de listagem, a resposta e um componente default ou um ajuste no `DefaultTable`, nunca uma copia local do comportamento.
+## Ponto de entrada
+
+- A documentação funcional e de regras deste modulo vive na **wiki do proprio repositório** e na wiki principal do app.
+- Regras transversais de qualidade, modularizacao e limites de componente vivem em `https://github.com/ControleOnline/agents-mcp/blob/master/skills/shared/code-quality.md`.
+- Quando houver detalhe especifico de implementacao, prefira comentar no codigo em ingles perto da regra.
+- Este arquivo deve ficar curto e servir apenas como ponte para as fontes oficiais.
+
+## Documentação (navegação humana)
+
+| Categoria | Destino |
+| --- | --- |
+| Home do módulo | https://github.com/ControleOnline/ui-default/wiki |
+| Wiki principal do app | https://github.com/ControleOnline/app-community/wiki |
+
+### Componentes Default*
+
+| Página | O que documenta |
+| --- | --- |
+| [Índice Default*](https://github.com/ControleOnline/ui-default/wiki/Default-Components) | Mapa da família e arquitetura |
+| [DefaultTable](https://github.com/ControleOnline/ui-default/wiki/DefaultTable) | Listagens, store contract, view modes, **hydrate único de filtros** (`useDefaultTableStoreSync`, anti #185) |
+| [DefaultForm](https://github.com/ControleOnline/ui-default/wiki/DefaultForm) | Create/edit genérico |
+| [DefaultInput e DefaultSelect](https://github.com/ControleOnline/ui-default/wiki/DefaultInput-e-DefaultSelect) | Campos e listas |
+| [Contrato de colunas](https://github.com/ControleOnline/ui-default/wiki/Contrato-de-colunas) | Flags e serialização |
+
+Cópias versionadas: `docs/technical/*.md`
+
+### Visão deste módulo
+
+`ui-default` é a **biblioteca de UI genérica** (tabela, form, inputs, filtros, upload, mapa) consumida pelos submódulos do `app-community`. Não carrega regra de domínio de um `APP_TYPE` específico; o domínio entra via `storeName` + `columns`.
+
+### DefaultUpload (app-community#296)
+
+| Página / arquivo | O que documenta |
+| --- | --- |
+| `src/react/components/upload/DefaultUpload.js` | Mini gerenciador de arquivos por **contexto** (biblioteca + anexos da entidade) |
+| `DefaultUploadManagerModal.js` | Modal de biblioteca / upload / attach |
+| `DefaultUploadAttachmentsList.js` | Lista inline de anexos + capa |
+| `defaultUploadHelpers.js` / `defaultUploadLibrary.js` / `fileUpload.js` | Helpers puros e fetch da biblioteca |
+
+**Contrato de uso**
+
+- Props principais: `context` (obrigatório — escopo dos arquivos), `companyId` / people da empresa, `entityId` + `relationResource` / `relationField` para vínculo, `fileActions` / `relationActions` (stores), `fileType`, `maxFiles`, `attachmentRows`, callbacks `onChanged` / `onCoverChanged` / `onAttachFile` / `onUploadFile`.
+- Todo upload abre o mini gerenciador já limitado ao `context` (e `people` da company quando informado).
+- Listagem da biblioteca chama `fileActions.getItems({ context, people, ... })` — o backend aplica `FileService::securityFilter` (company-scoped).
+- Não chamar API de files diretamente nas telas consumidoras; usar stores/actions.
+- Reutilizar `DefaultFile` para preview/download.

package/docs/technical/Contrato-de-colunas.md

@@ -0,0 +1,67 @@
+# Contrato de colunas (`defaultInputUtils`)
+
+**Arquivo:** `src/react/components/inputs/defaultInputUtils.js`
+
+A coluna é o **contrato de UI + serialização** compartilhado por Table, Form e Inputs.
+
+## Identidade
+
+| Campo | Uso |
+| --- | --- |
+| `key` ou `name` | Nome do campo (`getColumnKey`) |
+| `label` | Rótulo (i18n via `formatStoreColumnLabel`) |
+| `isIdentity` | PK visual; fora do form; largura própria na tabela |
+
+## Visibilidade e edição
+
+| Flag | Efeito |
+| --- | --- |
+| `show` / `visible` / `table` | Inclusão na tabela (`shouldIncludeColumn` em utils da table) |
+| `form` | `false` remove do form |
+| `add` | `false` remove do create |
+| `editable` | `false` bloqueia edição |
+| `visibleForm` | bool ou fn |
+| `multiline` | excluído do DefaultForm atual |
+| `sortable` / `sortField` / `defaultSort` | Sort |
+| `summary` | Agregações no footer |
+
+## Tipos de input
+
+| `inputType` / `type` | Comportamento |
+| --- | --- |
+| `date` / `date-range` / `range-date` | `DefaultDateInput`; save via `Formatter` |
+| `color` / `hexcolor` ou nome color-like | `DefaultColorInput` |
+| `file` / `image` / `document` / … | `DefaultFileColumn` (não editável inline) |
+| `extradata` | `DefaultExtraData` |
+| `number` / `float` | teclado numérico |
+| `increase` | não editável |
+
+## Listas (select)
+
+| Campo | Uso |
+| --- | --- |
+| `list` | Array local **ou** `"store/action"` |
+| `listRequestParams` | Filtros extras do load |
+| `listSearchParam` / `searchParam` | Query de busca |
+| `formatList` | Normaliza item → label/meta |
+| `translate` | Força/desliga i18n de labels de opção |
+
+## Formatação
+
+| Campo | Uso |
+| --- | --- |
+| `format` | Apresentação de célula (pode retornar objeto com color/icon) |
+| `editFormat` | Valor ao entrar em edição |
+| `saveFormat` | Valor ao persistir |
+| `prefix` / `sufix`/`suffix` | Decoração textual |
+| `style` | estilo estático ou fn(row) |
+| `width` / `minWidth` / `flexBasis` | Layout de coluna na table |
+| `defaultValue` / `initialValue` / `defaultColor` | Defaults de form/cor |
+
+## Helpers exportados (referência rápida)
+
+`normalizeText`, `getColumnKey`, `isEditableColumn`, `isDateLikeColumn`, `isColorColumn`, `isFileColumn`, `isExtraDataColumn`, `normalizeId`, `normalizeOptionKey`, `mapOptions`, `buildOptionsFromColumn`, `resolveCellText`, `resolveCellPresentation`, `buildReadPresentationStyles`, `resolveEditValue`, `formatSaveValue`, `resolveStoreNameFromList`, `resolveColorToken`
+
+## Campos traduzíveis por convenção
+
+Sem `translate: true`, ainda traduz labels de opção se o nome do campo estiver em: `active`, `app`, `channel`, `status`, `ordertype`, `peopletype`, etc. (`DEFAULT_TRANSLATABLE_FIELDS`).

package/docs/technical/Default-Components.md

@@ -0,0 +1,76 @@
+# Componentes Default* (`ui-default`)
+
+Documentação técnica da família de componentes genéricos do módulo **`ControleOnline/ui-default`**.
+
+> Público: desenvolvedores e agents internos.  
+> Issue: `ControleOnline/ui-default#2`.
+
+## Objetivo do módulo
+
+`ui-default` concentra UI reutilizável orientada a **stores** (`useStore(storeName)`): tabelas, formulários, inputs, filtros, upload, mapas e anexos. O contrato central é a **definição de colunas** (`columns`) + estado do store (`items`, `filters`, `configs`, `actions`).
+
+```mermaid
+flowchart TB
+  subgraph app [Módulo de domínio]
+    Page[Page / Screen]
+    Store[useStore storeName]
+  end
+  subgraph defaults [ui-default]
+    DT[DefaultTable]
+    DF[DefaultForm]
+    DI[DefaultInput]
+    DS[DefaultSelect]
+  end
+  Page --> DT
+  Page --> DF
+  DT --> Store
+  DF --> DI
+  DI --> DS
+  DI --> Store
+  DS --> Store
+```
+
+## Mapa de componentes
+
+| Família | Componentes principais | Pasta |
+| --- | --- | --- |
+| Tabela | `DefaultTable`, Body, Rows, Cards, Toolbar, Footer, Search, Controls… | `src/react/components/table/` |
+| Formulário | `DefaultForm` | `src/react/components/form/` |
+| Inputs | `DefaultInput`, `DefaultSelect`, `DefaultDateInput`, `DefaultColorInput`, `DefaultFeatherIconPicker` | `src/react/components/inputs/` |
+| Filtros | `DefaultSearch`, `DefaultColumnFilter`, `DefaultExternalFilters`, `DateShortcutFilter`, `CompactFilterSelector` | `src/react/components/filters/` |
+| Arquivos | `DefaultFile`, `DefaultFileColumn` | `src/react/components/files/` |
+| Upload | `DefaultUpload` | `src/react/components/upload/` |
+| Extra | `DefaultExtraData` | `src/react/components/extra-data/` |
+| Erros | `DefaultErrors` | `src/react/components/errors/` |
+| Ajuda | `DefaultTooltip` | `src/react/components/help/` |
+| Mapa | `DefaultMap`, `DefaultGoogleMap`, `DefaultNativeMap` | `src/react/components/map/` |
+
+## Páginas detalhadas
+
+| Página | Conteúdo |
+| --- | --- |
+| [DefaultTable](DefaultTable) | Orquestração, props, store contract, view modes, preferências |
+| [DefaultForm](DefaultForm) | Create/edit, draft, payload de save |
+| [DefaultInput-e-DefaultSelect](DefaultInput-e-DefaultSelect) | Roteamento por tipo de coluna, list remote, apresentação |
+| [Contrato-de-colunas](Contrato-de-colunas) | Flags e helpers de `defaultInputUtils` |
+
+## Dependências transversais
+
+- `@store` — `useStore` / `getAllStores`
+- `@controleonline/ui-common` — `MessageService`, `Formatter`, `formatStoreColumnLabel` / `formatStoreColumnValue`, date range helpers
+- `@react-navigation/native` — foco e escopo de preferências da tabela
+- Tema via store `theme` e tokens em `useDefaultTableTheme`
+
+## Quando usar
+
+| Situação | Preferir |
+| --- | --- |
+| Listagem CRUD ligada a store com `getItems` / `save` | `DefaultTable` (+ `DefaultForm` no modal de add/edit) |
+| Campo isolado em tela custom | `DefaultInput` / `DefaultSelect` |
+| Upload de arquivos | `DefaultUpload` |
+| Mapa web/native | família `DefaultMap*` |
+
+## Não objetivos
+
+- Não substituir telas de domínio com regras de negócio específicas sem `columns`/`store`.
+- Não publicar esta documentação na Central de Ajuda do cliente (`tutorial-assistant`); é documentação **técnica**.

package/docs/technical/DefaultForm.md

@@ -0,0 +1,80 @@
+# DefaultForm
+
+Formulário genérico create/edit orientado a **colunas** e `actions.save`.
+
+**Arquivo:** `src/react/components/form/DefaultForm.js`
+
+## Responsabilidade
+
+- Filtrar colunas elegíveis ao formulário
+- Montar **draft** a partir da row / defaults
+- Salvar apenas campos alterados (edit) ou preenchidos (create)
+- Renderizar cada campo com `DefaultInput` em `variant="form"`
+
+## Props
+
+| Prop | Default | Função |
+| --- | --- | --- |
+| `storeName` | `''` | i18n de labels/botões |
+| `columns` | `[]` | Definição de campos |
+| `row` | `{}` | Registro em edição |
+| `mode` | `'edit'` | `'create'` \| `'edit'` |
+| `actions` | `{}` | Precisa de `actions.save(payload)` |
+| `getOptionsForColumn` | null | Options locais |
+| `onBeforeOpen` | null | Antes de abrir select (`(column) => ...`) |
+| `onCancel` | null | Cancelar |
+| `onSaved` | null | `(savedItem, previousRow) => ...` |
+
+## Inclusão de coluna no form
+
+`shouldIncludeColumn(column, row, mode)`:
+
+- precisa de `key`/`name`
+- **exclui** `isIdentity === true`
+- **exclui** `form === false` ou `multiline === true`
+- em `create`: respeita `add === false`
+- em `edit`: exige `isEditableColumn(column)`
+- `visibleForm` (bool ou fn `(row, column) => boolean`)
+
+## Draft e defaults
+
+Ordem em `resolveDefaultValue`:
+
+1. `row[field]`
+2. `column.defaultValue` (valor ou fn)
+3. `column.initialValue` (valor ou fn)
+
+`resolveEditValue` normaliza para edição (list → option key, date → dmY, `editFormat`).
+
+## Payload de save
+
+**Create:** objeto só com campos que `hasValue`.  
+**Edit:** sempre inclui `id` (`@id` ou `id` normalizado) + campos cujo texto normalizado **mudou**.
+
+`formatSaveValue(column, value, row)`:
+
+- `column.saveFormat` se existir
+- objetos com `value` / `@id`
+- datas → formato americano via `Formatter`
+- números quando aplicável
+
+Se não há nada a salvar → chama `onCancel` e não bate no backend.
+
+## UI
+
+- Grid scrollável de campos
+- Botões Cancelar / Salvar (tema: store `theme`)
+- Estado `isSaving` desabilita botão primário
+
+## Exemplo
+
+```jsx
+<DefaultForm
+  mode="create"
+  storeName="customers"
+  columns={store.getters.columns}
+  actions={{ save: store.actions.save }}
+  onCancel={close}
+  onSaved={(item) => { close(); refresh(); }}
+/>
+```

package/docs/technical/DefaultInput-e-DefaultSelect.md

@@ -0,0 +1,73 @@
+# DefaultInput e DefaultSelect
+
+Camada de campo único usada por **tabela** (`variant="cell"`) e **form** (`variant="form"`).
+
+## DefaultInput
+
+**Arquivo:** `src/react/components/inputs/DefaultInput.js`
+
+### Roteamento por tipo de coluna
+
+| Condição | Componente |
+| --- | --- |
+| `column.list` truthy | `DefaultSelect` |
+| `isColorColumn(column)` | `DefaultColorInput` |
+| `isDateLikeColumn(column)` | `DefaultDateInput` |
+| leitura + extra data | `DefaultExtraData` |
+| leitura + file | `DefaultFileColumn` |
+| senão | `TextInput` ou modo leitura com badge/ícone/imagem |
+
+### Props relevantes
+
+| Prop | Função |
+| --- | --- |
+| `column` / `columns` / `row` | Contrato de coluna e contexto |
+| `editing` | Alterna leitura × edição (cell) |
+| `variant` | `'cell'` \| `'form'` |
+| `autoSave` | `true`: `onSave` no blur/submit; `false`: só `onChangeValue` |
+| `onStartEditing` / `onCancelEditing` / `onSave` | Ciclo de edição inline |
+| `getOptionsForColumn` | Options injetadas |
+| `showLabel` | Label acima do campo |
+| `displayValue` | Override de texto lido |
+| `accentColor` / `defaultColor` | Tema / cor default |
+
+### Modo leitura
+
+- `resolveCellText` + `resolveCellPresentation` (cor, ícone Feather, image, badge)
+- Ícone de editar se `isEditableColumn` e existe `onStartEditing`
+- Prefixo/sufixo da coluna
+
+### Modo edição texto
+
+- `keyboardType` numérico se `inputType` number/float
+- Cancel (X) só fora de form
+
+## DefaultSelect
+
+**Arquivo:** `src/react/components/inputs/DefaultSelect.js`
+
+### Fontes de opções
+
+1. `getOptionsForColumn(column)`
+2. `column.list` como **array** estática
+3. `column.list` como string `"storeName/actionName"` → `getAllStores()[store].actions[action]`
+4. Cache em memória por chave serializada de params
+
+### Params de load remoto
+
+`resolveColumnListLoadParams`:
+
+- escopo empresa para `categories` (`company`), `paymentType` / `wallet` (`people`)
+- `column.listRequestParams` (objeto ou fn)
+- busca: `listSearchParam` \|\| `searchParam` \|\| `'search'`
+
+### UX
+
+- Toque abre `Modal` com busca e lista
+- `autoSave`: `onSave({ value, label, object })`
+- form: `onChangeValue(key, meta)`
+- `onBeforeOpen` pode pré-carregar items
+
+### Meta visual de opção
+
+`formatList` / item pode expor `color`, `icon`, `image` para badges na lista e no valor selecionado.