@controleonline/ui-common 1.2.75 → 1.2.77

package/AGENTS.md

@@ -4,3 +4,22 @@
 - 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-common/wiki |
+| Wiki principal do app | https://github.com/ControleOnline/app-community/wiki |
+
+### Automações de documentação
+
+| Página | O que documenta |
+| --- | --- |
+| [Technical Documenter workflow](https://github.com/ControleOnline/ui-common/wiki/Technical-Documenter-Workflow) | Abertura/preparo automático da trilha documental após push em `master` |
+
+Cópia versionada no Git: `docs/technical/Technical-Documenter-Workflow.md`
+
+### Visão deste módulo
+
+`ui-common` é o módulo compartilhado de runtime, API e utilitários de UI usado pelas visões `MANAGER`, `ADMIN`, `CRM`, `POS`, `PPC`, `SHOP`, `DELIVERY` e `SERVICE`. A automação documentada aqui é de governança do repositório e não altera comportamento funcional dessas visões.

package/docs/technical/Technical-Documenter-Workflow.md

@@ -0,0 +1,150 @@
+# Technical Documenter workflow
+
+Documentação técnica da automação introduzida por `ControleOnline/ui-common` commit `155af951fb80f13180fe3d8befa1922efe6d1390` (`ci: add technical-documenter workflow`) e rastreada em `ControleOnline/ui-common#18`.
+
+> Cópia operacional no repositório (`docs/technical/`). A wiki do módulo (`ui-common/wiki`) é a fonte primária de leitura.
+
+## Objetivo
+
+Registrar como o repositório abre ou prepara automaticamente a trilha de documentação técnica sempre que houver `push` em `master`.
+
+O fluxo existe para evitar merge em `master` sem rastreabilidade documental:
+
+- se o commit já mencionar uma issue, a issue existente recebe a trilha `technical-documenter`;
+- se o commit não mencionar issue fonte, o workflow cria uma issue documental dedicada;
+- em ambos os casos a automação deixa instruções explícitas para o Copilot atuar como `technical-documenter`.
+
+## Repositórios e superfícies afetadas
+
+| Módulo / superfície | Papel no fluxo |
+| --- | --- |
+| `ControleOnline/ui-common` | Repositório dono do workflow `.github/workflows/technical-documenter.yml` |
+| `ControleOnline/agents-mcp` | Fonte canônica do papel `technical-documenter` e das skills obrigatórias |
+| `ControleOnline/ui-common/wiki` | Destino primário da documentação técnica publicada para humanos |
+| GitHub Issues do próprio repositório | Fila operacional do fluxo documental |
+
+## Visão do módulo (`APP_TYPE`)
+
+`ui-common` atende várias visões do app (`MANAGER`, `ADMIN`, `CRM`, `POS`, `PPC`, `SHOP`, `DELIVERY` e `SERVICE`) como base compartilhada de runtime e utilitários.
+
+Esta automação:
+
+- **não** é uma feature de uma visão específica;
+- **não** altera contratos de UI, API ou comportamento de runtime;
+- atua somente na governança documental do repositório para manter a trilha técnica encontrável depois de publicações em `master`.
+
+## Gatilho
+
+Arquivo: `.github/workflows/technical-documenter.yml`
+
+```yaml
+on:
+  push:
+    branches: [master]
+```
+
+O workflow roda apenas em `push` para `master`.
+
+## Fluxo operacional
+
+```mermaid
+flowchart TD
+  A[Push em master] --> B[Checkout com histórico completo]
+  B --> C[Detectar referência de issue nas mensagens dos commits]
+  C -->|Encontrou issue| D[Adicionar label agent:technical-documenter]
+  C -->|Não encontrou issue| E[Criar issue documental com commit e mensagem]
+  D --> F[Assign Copilot com custom_instructions do papel]
+  E --> F
+  F --> G[Finalizar labels]
+  G -->|Issue criada pelo workflow| H[Adicionar qa:accepted e security:accepted]
+  G --> I[Comentar resumo da automação na issue]
+```
+
+## Etapas detalhadas
+
+### 1. Checkout
+
+O job faz `actions/checkout@v4` com `fetch-depth: 0` para conseguir ler o intervalo de commits do push.
+
+### 2. Detecção de issue fonte
+
+O step `Detect source issue from commit messages` lê as mensagens entre `${{ github.event.before }}` e `${{ github.sha }}`. O regex aceito é:
+
+```text
+([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)?#([0-9]+)
+```
+
+Com isso o workflow aceita tanto:
+
+- `#123`
+- `ControleOnline/ui-common#123`
+
+Se nada for encontrado, o fluxo entra no caminho de criação automática da issue documental.
+
+### 3. Preparar ou criar a issue documental
+
+O step `Create or prepare issue + assign Copilot` usa `gh` com `GH_TOKEN` para dois caminhos:
+
+| Situação | Comportamento |
+| --- | --- |
+| Commit com issue referenciada | Reusa a issue encontrada, adiciona `agent:technical-documenter` e envia `agent_assignment` para `copilot-swe-agent[bot]` |
+| Commit sem issue referenciada | Cria issue com título `docs: documentação técnica automática (push master <sha>)`, corpo com SHA + mensagem do commit, label `agent:technical-documenter` e atribuição inicial ao Copilot |
+
+As `custom_instructions` embutidas no payload exigem:
+
+- seguir o papel canônico `technical-documenter` em `agents-mcp`;
+- tratar a wiki técnica como fonte primária;
+- usar as labels `agent:technical-documenter` e `agent:technical-documenter:done`;
+- **não** implementar código de produto.
+
+### 4. Finalização automática de labels
+
+O step `Finalize labels` sempre:
+
+- adiciona `agent:technical-documenter:done`;
+- remove `agent:technical-documenter` quando presente.
+
+Quando a issue foi criada automaticamente pelo próprio workflow, ele também tenta adicionar:
+
+- `qa:accepted`
+- `security:accepted`
+
+e publica um comentário informando que a documentação técnica automática foi disparada.
+
+## Contrato de labels e comentários
+
+| Artefato | Uso |
+| --- | --- |
+| `agent:technical-documenter` | Marca a solicitação enquanto a trilha documental está aberta |
+| `agent:technical-documenter:done` | Marca a trilha documental como concluída |
+| `qa:accepted` / `security:accepted` | Aplicados apenas no caminho em que a issue foi criada automaticamente |
+| Comentário na issue | Registra que a automação disparou e deixa o histórico visível para humanos |
+
+## Limites e cuidados
+
+- O workflow depende de `GH_TOKEN` com permissão para `issues: write` e `pull-requests: write`.
+- O parser usa apenas a **primeira** referência de issue encontrada nas mensagens do push.
+- O fluxo opera sobre GitHub Issues; não usa ProjectV2 para decidir elegibilidade.
+- A automação prepara a trilha documental, mas a documentação humana continua devendo existir na wiki do módulo e, quando fizer sentido, em `docs/technical/`.
+- O conteúdo publicado não deve expor credenciais, dados reais ou links privados.
+
+## Verificação manual
+
+Checklist mínimo quando esse workflow mudar:
+
+1. validar se o `push` em `master` continua acionando o job;
+2. conferir se commits com `#issue` reaproveitam a issue correta;
+3. conferir se commits sem referência criam a issue `docs: documentação técnica automática...`;
+4. revisar se as labels finais e o comentário esperado continuam sendo aplicados;
+5. confirmar se o texto de `custom_instructions` ainda aponta para a fonte canônica em `agents-mcp`.
+
+## Links cruzados
+
+| Destino | URL |
+| --- | --- |
+| Home do módulo | https://github.com/ControleOnline/ui-common/wiki |
+| Wiki principal do app | https://github.com/ControleOnline/app-community/wiki |
+| Visões do app (`APP_TYPE`) | https://raw.githubusercontent.com/ControleOnline/app-community/master/MODOS_OPERACAO.md |
+| Issue de origem | https://github.com/ControleOnline/ui-common/issues/18 |
+| Commit documentado | https://github.com/ControleOnline/ui-common/commit/155af951fb80f13180fe3d8befa1922efe6d1390 |
+| Workflow | https://github.com/ControleOnline/ui-common/blob/master/.github/workflows/technical-documenter.yml |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@controleonline/ui-common",
-  "version": "1.2.75",
+  "version": "1.2.77",
   "author": "ControleOnline",
   "description": "ControleOnline Common Quasar UI Component",
   "license": "MIT",

package/src/react/components/RuntimeInfoFooter.js

@@ -11,9 +11,9 @@ import {useSafeAreaInsets} from 'react-native-safe-area-context';
 import {
   DEVICE_RUNTIME_DEBUG_INFO_ENABLED_KEY,
   isTruthyValue,
-  parseConfigsObject,
-} from '@controleonline/ui-common/src/react/config/deviceConfigBootstrap';
-import {
+  parseConfigsObject,
+} from '@controleonline/ui-common/src/react/config/deviceConfigBootstrap';
+import {
   getRuntimeFooterDebugInfo,
   getRuntimeFooterPrimaryText,
   getRuntimeFooterRotationEntries,
@@ -22,11 +22,11 @@ import {
 } from '@controleonline/ui-common/src/react/utils/runtimeFooter';
 import styles from './RuntimeInfoFooter.styles';
 
-const ROTATION_INTERVAL_MS = 6000;
+const ROTATION_INTERVAL_MS = 4000;
 const FADE_DURATION_MS = 260;
 const COMPACT_BREAKPOINT = 720;
 const MAX_INLINE_TEXT_LENGTH = 84;
-
+
 const RuntimeInfoFooter = ({
   appVersion,
   defaultCompany,
@@ -43,26 +43,26 @@ const RuntimeInfoFooter = ({
   const runtimeDebugStore = useStore('runtime_debug');
   const deviceConfigItem = deviceConfigStore?.getters?.item || {};
   const runtimeDebugSummary = runtimeDebugStore?.getters?.summary || {};
-
-  const footerDebugInfo = useMemo(
-    () =>
-      getRuntimeFooterDebugInfo({
-        device,
-        appVersion,
-        deviceConfig: deviceConfigItem,
-      }),
-    [appVersion, device, deviceConfigItem],
-  );
-  const primaryText = useMemo(
-    () =>
-      footerDebugInfo.primaryText ||
-      getRuntimeFooterPrimaryText({
-        device,
-        appVersion,
-        deviceConfig: deviceConfigItem,
-      }),
-    [appVersion, device, deviceConfigItem, footerDebugInfo.primaryText],
-  );
+
+  const footerDebugInfo = useMemo(
+    () =>
+      getRuntimeFooterDebugInfo({
+        device,
+        appVersion,
+        deviceConfig: deviceConfigItem,
+      }),
+    [appVersion, device, deviceConfigItem],
+  );
+  const primaryText = useMemo(
+    () =>
+      footerDebugInfo.primaryText ||
+      getRuntimeFooterPrimaryText({
+        device,
+        appVersion,
+        deviceConfig: deviceConfigItem,
+      }),
+    [appVersion, device, deviceConfigItem, footerDebugInfo.primaryText],
+  );
   const companyFooterText = useMemo(
     () => getRuntimeFooterText(defaultCompany),
     [defaultCompany?.configs],
@@ -71,18 +71,18 @@ const RuntimeInfoFooter = ({
     () => getRuntimeFooterTextLines(companyFooterText),
     [companyFooterText],
   );
-  const deviceConfigs = useMemo(
-    () => parseConfigsObject(deviceConfigItem?.configs),
-    [deviceConfigItem?.configs],
-  );
-  const showDebugInfo = useMemo(
-    () =>
-      isTruthyValue(
-        deviceConfigs?.[DEVICE_RUNTIME_DEBUG_INFO_ENABLED_KEY],
-      ),
-    [deviceConfigs],
-  );
-
+  const deviceConfigs = useMemo(
+    () => parseConfigsObject(deviceConfigItem?.configs),
+    [deviceConfigItem?.configs],
+  );
+  const showDebugInfo = useMemo(
+    () =>
+      isTruthyValue(
+        deviceConfigs?.[DEVICE_RUNTIME_DEBUG_INFO_ENABLED_KEY],
+      ),
+    [deviceConfigs],
+  );
+
   const rotationEntries = useMemo(
     () =>
       getRuntimeFooterRotationEntries({
@@ -95,43 +95,39 @@ const RuntimeInfoFooter = ({
     () => [primaryText, ...footerTextLines].filter(Boolean).join('  •  '),
     [footerTextLines, primaryText],
   );
+  // Always rotate when there is more than one entry (e.g. 1 footer line + primaryText).
+  // Do not fall back to concatenated inlineText in that case.
   const shouldRotate =
-    !showDebugInfo &&
-    rotationEntries.length > 1 &&
-    (
-      footerTextLines.length > 1 ||
-      width < COMPACT_BREAKPOINT ||
-      inlineText.length > MAX_INLINE_TEXT_LENGTH
-    );
-  const footerEntries = useMemo(
-    () =>
-      Object.values(runtimeDebugSummary?.entries || {})
-        .filter(entry => entry && Array.isArray(entry.lines) && entry.lines.length > 0)
-        .sort((left, right) => {
-          const leftOrder = Number(left?.order || 100);
-          const rightOrder = Number(right?.order || 100);
-          if (leftOrder !== rightOrder) {
-            return leftOrder - rightOrder;
-          }
-
-          const leftTime = Date.parse(left?.updatedAt || '');
-          const rightTime = Date.parse(right?.updatedAt || '');
-          if (Number.isFinite(leftTime) && Number.isFinite(rightTime)) {
-            return rightTime - leftTime;
-          }
-
-          if (Number.isFinite(rightTime)) {
-            return 1;
-          }
-
-          if (Number.isFinite(leftTime)) {
-            return -1;
-          }
-
-          return 0;
-        }),
-    [runtimeDebugSummary?.entries],
-  );
+    !showDebugInfo && rotationEntries.length > 1;
+  const footerEntries = useMemo(
+    () =>
+      Object.values(runtimeDebugSummary?.entries || {})
+        .filter(entry => entry && Array.isArray(entry.lines) && entry.lines.length > 0)
+        .sort((left, right) => {
+          const leftOrder = Number(left?.order || 100);
+          const rightOrder = Number(right?.order || 100);
+          if (leftOrder !== rightOrder) {
+            return leftOrder - rightOrder;
+          }
+
+          const leftTime = Date.parse(left?.updatedAt || '');
+          const rightTime = Date.parse(right?.updatedAt || '');
+          if (Number.isFinite(leftTime) && Number.isFinite(rightTime)) {
+            return rightTime - leftTime;
+          }
+
+          if (Number.isFinite(rightTime)) {
+            return 1;
+          }
+
+          if (Number.isFinite(leftTime)) {
+            return -1;
+          }
+
+          return 0;
+        }),
+    [runtimeDebugSummary?.entries],
+  );
   const socketEntry = useMemo(
     () => footerEntries.find(entry => entry?.key === 'socket') || null,
     [footerEntries],
@@ -170,7 +166,7 @@ const RuntimeInfoFooter = ({
     [allStores],
   );
   const bottomInset = Math.max(Number(insets.bottom) || 0, 16);
-
+
   useEffect(() => {
     if (!shouldRotate || rotationEntries.length <= 1) {
       setActiveIndex(0);
@@ -302,5 +298,5 @@ const RuntimeInfoFooter = ({
     </View>
   );
 };
-
-export default RuntimeInfoFooter;
+
+export default RuntimeInfoFooter;