@wellingtonhlc/shared-ui 0.24.9 → 0.24.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +83 -93
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
- # EloDesk CRM Shared UI
1
+ # Wellington Shared UI
2
2
 
3
- Pacote de componentes visuais genericos usados pelos frontends `EloDesk.CRM` e `EloDesk.CRM.Portal`.
3
+ Conjunto de componentes visuais padronizados, criado por Wellington Henrique para aplicacoes React.
4
4
 
5
5
  O objetivo deste pacote e concentrar componentes base, tokens, presets e helpers de UI reutilizaveis, sem regras de negocio de dominio.
6
6
 
@@ -20,8 +20,8 @@ export function ExamplePage() {
20
20
  <Page.Root>
21
21
  <Card.Root>
22
22
  <Card.Header>
23
- <Card.Title>Clientes</Card.Title>
24
- <Card.Description>Consulta operacional</Card.Description>
23
+ <Card.Title>Registros</Card.Title>
24
+ <Card.Description>Consulta de dados</Card.Description>
25
25
  </Card.Header>
26
26
  <Card.Body>
27
27
  <Button>Salvar</Button>
@@ -32,24 +32,16 @@ export function ExamplePage() {
32
32
  }
33
33
  ```
34
34
 
35
- ## Escopo
35
+ ## Principios
36
36
 
37
- Inclua aqui apenas infraestrutura visual generica:
37
+ Este pacote foi desenhado para oferecer infraestrutura visual generica:
38
38
 
39
39
  - componentes base de interface;
40
40
  - campos de formulario reutilizaveis;
41
- - primitives de acao;
41
+ - primitivas de acao;
42
42
  - tokens, estilos e presets;
43
- - helpers sem dependencia de dominio.
44
-
45
- Nao inclua:
46
-
47
- - services HTTP;
48
- - rotas;
49
- - schemas de dominio;
50
- - permissoes;
51
- - regras de negocio;
52
- - componentes acoplados a `customer`, `supplier`, `item`, PDV, financeiro, estoque, licencas, suporte ou relatorios.
43
+ - helpers sem dependencia de dominio;
44
+ - composicao por slots quando o componente possui partes internas.
53
45
 
54
46
  ## Scripts
55
47
 
@@ -64,9 +56,9 @@ Nao inclua:
64
56
  | `npm run storybook` | Sobe o Storybook local. |
65
57
  | `npm run build-storybook` | Gera build estatico do Storybook. |
66
58
 
67
- ## Validadores para consumidores
59
+ ## Validacao de Page Actions
68
60
 
69
- O pacote publica o CLI `shared-ui-check-page-actions` para validar o contrato de actions em projetos consumidores.
61
+ O pacote publica o CLI `shared-ui-check-page-actions` para validar o contrato de actions em uma aplicacao.
70
62
 
71
63
  Contrato esperado:
72
64
 
@@ -75,7 +67,7 @@ Contrato esperado:
75
67
  - Props como `helpContent`, `helpLabel`, `position`, `align` e `size` pertencem ao `Page.Actions`.
76
68
  - Nao usar `ActionBar.*`, `Page.Root actions=...` dentro de `AppLayout`, Fragment, `div` ou `Page.ActionButton` solto como root de `AppLayout.actions`.
77
69
 
78
- Uso recomendado no consumidor:
70
+ Uso recomendado:
79
71
 
80
72
  ```json
81
73
  {
@@ -101,15 +93,60 @@ Persistencia de preferencia continua sendo responsabilidade do consumidor. Use
101
93
  `localStorage`:
102
94
 
103
95
  ```tsx
104
- <Page.ActionsProvider
105
- preferences={{
106
- movable: true,
107
- onPositionChange: setActionsPosition,
108
- position: actionsPosition,
109
- }}
110
- >
111
- <App />
112
- </Page.ActionsProvider>
96
+ import { useCallback, useMemo, useState } from 'react';
97
+ import { Page, type PageActionsPosition, type PageActionsPreferences } from '@wellingtonhlc/shared-ui';
98
+
99
+ const storageKey = '@my-app/preference/page-actions-position';
100
+ const positions: PageActionsPosition[] = ['left', 'top', 'right', 'bottom'];
101
+
102
+ function readStoredPosition() {
103
+ const stored = window.localStorage.getItem(storageKey);
104
+ return positions.includes(stored as PageActionsPosition) ? (stored as PageActionsPosition) : undefined;
105
+ }
106
+
107
+ export function AppLayout({ children }: { children: React.ReactNode }) {
108
+ const [position, setPosition] = useState<PageActionsPosition | undefined>(readStoredPosition);
109
+
110
+ const handlePositionChange = useCallback(function handlePositionChange(nextPosition: PageActionsPosition) {
111
+ setPosition(nextPosition);
112
+ window.localStorage.setItem(storageKey, nextPosition);
113
+ }, []);
114
+
115
+ const preferences = useMemo<PageActionsPreferences>(
116
+ () => ({
117
+ mobilePosition: 'bottom',
118
+ movable: true,
119
+ onPositionChange: handlePositionChange,
120
+ position,
121
+ }),
122
+ [handlePositionChange, position],
123
+ );
124
+
125
+ return (
126
+ <Page.ActionsProvider preferences={preferences}>
127
+ <Page.ActionsSlot position="left" />
128
+ <main>{children}</main>
129
+ <Page.ActionsSlot position="right" />
130
+ <Page.ActionsSlot position="top" />
131
+ <Page.ActionsSlot position="bottom" />
132
+ </Page.ActionsProvider>
133
+ );
134
+ }
135
+ ```
136
+
137
+ Acoes de uma tela devem continuar usando `Page.Actions`; o provider apenas controla onde elas serao exibidas:
138
+
139
+ ```tsx
140
+ import { Page } from '@wellingtonhlc/shared-ui/components/Page';
141
+ import { Save } from 'lucide-react';
142
+
143
+ export function EditPageActions() {
144
+ return (
145
+ <Page.Actions helpLabel="Ajuda" helpContent="Revise os dados antes de salvar.">
146
+ <Page.ActionButton icon={<Save />} label="Salvar" />
147
+ </Page.Actions>
148
+ );
149
+ }
113
150
  ```
114
151
 
115
152
  Telas podem limitar o contrato localmente:
@@ -137,19 +174,6 @@ npm run build-storybook
137
174
  npm run check:storybook-static
138
175
  ```
139
176
 
140
- ## Qualidade publica
141
-
142
- Todo export publico deve ter pelo menos uma destas evidencias:
143
-
144
- - teste de contrato observavel em `tests/`;
145
- - story em `stories/` cobrindo uso real, estados e variantes;
146
- - justificativa explicita na spec/PR quando o export for puramente auxiliar.
147
-
148
- Componentes interativos devem preservar acessibilidade verificavel: labels, roles, atributos
149
- `aria-*`, estado `disabled`/`loading`/`selected` quando aplicavel, foco e callbacks publicos.
150
- O gate `npm run test` inclui axe em composicoes representativas e nao deve ser burlado com
151
- snapshots de classe completa.
152
-
153
177
  ## Exportacoes
154
178
 
155
179
  Entrada principal:
@@ -267,21 +291,7 @@ Padrões do painel:
267
291
  - Limita a altura com `maxHeightClassName`; o default é `max-h-[calc(100vh-12rem)]`.
268
292
  - Aplica rolagem apenas na área de filtros.
269
293
  - Use `Filter.Footer` para manter botões sempre visíveis no rodapé do painel.
270
- - Em telas administrativas, campos internos devem preferir `size="sm"` e não devem usar formato `rounded-full`.
271
-
272
- ## Contrato publico atual
273
-
274
- O pacote oficial e `@wellingtonhlc/shared-ui`, publicado no npm publico (`https://registry.npmjs.org/`).
275
- Ele deve permanecer generico: componentes visuais, utilitarios, tokens, estilos e preset Tailwind.
276
-
277
- Fora do contrato publico:
278
-
279
- - regra de negocio;
280
- - services HTTP;
281
- - rotas;
282
- - permissoes;
283
- - schemas de dominio;
284
- - textos ou fluxos especificos de CRM, licencas, pagamentos, suporte, relatorios ou clientes.
294
+ - Em interfaces densas, campos dentro do painel devem preferir `size="sm"` e nao devem usar formato `rounded-full`.
285
295
 
286
296
  ## Contrato publico 0.1.0
287
297
 
@@ -299,17 +309,6 @@ Exports removidos:
299
309
  - `SearchWorkspace`: componha layout no consumidor ou com componentes genéricos.
300
310
  - `TabsUnderline` e `UnderlinedTabs`: use `TabsUnderlined`.
301
311
 
302
- ## Padroes de implementacao
303
-
304
- - Exporte sempre o componente e seus tipos publicos em `src/index.ts`.
305
- - Prefira composicao por slots para componentes com partes internas (`Root`, `Header`, `Body`, `Footer`, `Actions`, etc.).
306
- - Evite aliases antes da v1; a API deve ser definitiva sempre que possivel.
307
- - Preserve nomes semanticos e contratos pequenos.
308
- - Use `cn` para composicao de classes.
309
- - Mantenha o pacote livre de regra de negocio dos consumidores.
310
- - Rode `npm run build` antes de publicar.
311
- - Valide pelo menos um consumidor quando a mudanca puder afetar runtime.
312
-
313
312
  ## Versionamento
314
313
 
315
314
  Este pacote segue SemVer, mesmo antes da v1:
@@ -322,12 +321,16 @@ Tabela de historico:
322
321
 
323
322
  | Versao | Data | Tipo | Resumo | Validacao |
324
323
  |--------|------|------|--------|-----------|
324
+ | `0.24.10` | 2026-06-20 | Patch | Documenta o uso de `Page.ActionsProvider`, preferencias de posicao, slots e consumo pos-publicacao com `@latest`. | `npm run check`. |
325
+ | `0.24.9` | 2026-06-20 | Patch | Estabiliza o pacote publicado de `Page.Actions` movel para consumo em aplicacoes React. | `npm run typecheck`; `npm run build`; builds de consumidores. |
326
+ | `0.24.8` | 2026-06-20 | Patch | Corrige a renderizacao de `Page.Actions` em slots clonando o componente com marcador interno de slot. | `npm run typecheck`; `npm run test`; `npm run build`. |
327
+ | `0.24.7` | 2026-06-20 | Minor pre-v1 | Adiciona `Page.ActionsProvider`, `Page.ActionsSlot`, posicoes `left/top/right/bottom`, ajuda contextual e movimentacao de acoes por preferencia do consumidor. | `npm run check`. |
325
328
  | `0.24.3` | 2026-06-18 | Patch | Amplia testes de contrato para exports publicos, adiciona gate axe e smoke do Storybook estatico ao `check`. | `npm run test`; `npm run check`. |
326
329
  | `0.24.2` | 2026-06-18 | Patch | Alinha metadados e documentacao do pacote npm publico, mantendo o contrato generico e sem regra de negocio. | `npm run build`; `npm run build-storybook`; `npm pack --dry-run`. |
327
- | `0.24.0` | 2026-06-17 | Minor pre-v1 | Adiciona `Workspace` e corrige a composicao de `Filter` para consultas com painel de filtros e area de resultados. | `npm run build`; build do `EloDesk.CRM`. |
330
+ | `0.24.0` | 2026-06-17 | Minor pre-v1 | Adiciona `Workspace` e corrige a composicao de `Filter` para consultas com painel de filtros e area de resultados. | `npm run build`; build de consumidor. |
328
331
  | `0.21.0` | 2026-06-17 | Minor pre-v1 | Adiciona stories para `Modal`, `Card`, `PageMessage`, `EmptyState`, `StatCard`, `SelectField`, `TextareaField`, `DateField`, `DecimalField`, `RadioGroup`, `MultiSelectField`, `TabsUnderlined`, `Tooltip`, `CopyableField`, `FieldGroup`, `FieldSkeleton`, `FieldValidationError`, `NavCard`, `Sidebar` e `AppShell`. | `npm run build`; `npm run build-storybook`. |
329
- | `0.1.17` | 2026-06-16 | Minor pre-v1 | Remove a variante ambigua `default` de `Button`; adiciona variants semanticas `information` e `warning`; `ConfirmationDialog` usa `information`, `question`, `warning` e `destructive` com botao principal na cor da variant; Storybook passou a gerar tokens semanticos de tema. | `npm run build`; `npm run build-storybook`; builds do `EloDesk.CRM` e `EloDesk.CRM.Portal`. |
330
- | `0.1.16` | 2026-06-16 | Patch | Consolida os ajustes visuais recentes do pacote para consumo no `EloDesk.CRM`. | `npm run build`; `npm run build-storybook`; validacao no `EloDesk.CRM`. |
332
+ | `0.1.17` | 2026-06-16 | Minor pre-v1 | Remove a variante ambigua `default` de `Button`; adiciona variants semanticas `information` e `warning`; `ConfirmationDialog` usa `information`, `question`, `warning` e `destructive` com botao principal na cor da variant; Storybook passou a gerar tokens semanticos de tema. | `npm run build`; `npm run build-storybook`; builds de consumidores. |
333
+ | `0.1.16` | 2026-06-16 | Patch | Consolida ajustes visuais recentes do pacote para consumo em aplicacoes React. | `npm run build`; `npm run build-storybook`; validacao em consumidor. |
331
334
  | `0.1.15` | 2026-06-16 | Patch | Corrige a hierarquia de z-index de `Modal` e `ConfirmationDialog` para o overlay cobrir sidebar e flyouts. | `npm run build`; `npm run build-storybook`. |
332
335
  | `0.1.14` | 2026-06-16 | Minor pre-v1 | Adiciona `icon` e `iconPosition` ao `TextField` e ajusta o offset lateral dos icones internos. | `npm run build`; `npm run build-storybook`. |
333
336
  | `0.1.13` | 2026-06-16 | Minor pre-v1 | Refina o visual do `Pagination`, remove botoes circulares e adiciona `size="sm" | "md" | "lg"`. | `npm run build`; `npm run build-storybook`. |
@@ -335,32 +338,23 @@ Tabela de historico:
335
338
  | `0.1.11` | 2026-06-16 | Patch | Reequilibra variantes de `Button`, separando `default` de `primary` e usando cores explicitas para estados de marca e semanticos. | `npm run build`; `npm run build-storybook`. |
336
339
  | `0.1.10` | 2026-06-16 | Patch | Reequilibra `Badge` `default`, `primary` e `muted` com estilos distintos e cor de texto explicita para `primary`. | `npm run build`; `npm run build-storybook`. |
337
340
  | `0.1.9` | 2026-06-16 | Patch | Garante estilos distintos para `Badge` `default`, `primary` e `muted`, e normaliza alias legado `active` para `success`. | `npm run build`; `npm run build-storybook`. |
338
- | `0.1.8` | 2026-06-16 | Minor pre-v1 | Adiciona `Switch display="inline"` para linhas compactas com label integrado e alinhamento previsivel. | `npm run build`; `npm run build-storybook`; build do `EloDesk.CRM`. |
339
- | `0.1.7` | 2026-06-16 | Minor pre-v1 | Adiciona props de customizacao dos botoes de aparencia em `ThemePreferencesSelector`. | `npm run build`; build do `EloDesk.CRM`. |
340
- | `0.1.6` | 2026-06-16 | Patch | Forca o destaque da aparencia selecionada por CSS explicito em `[aria-pressed='true']`. | `npm run build`; `npm run build-storybook`; build do `EloDesk.CRM.Portal`. |
341
- | `0.1.5` | 2026-06-16 | Patch | Aplica o destaque da aparencia selecionada por estilo inline para evitar perda por ordem/geracao de CSS nos consumidores. | `npm run build`; `npm run build-storybook`; build do `EloDesk.CRM.Portal`. |
341
+ | `0.1.8` | 2026-06-16 | Minor pre-v1 | Adiciona `Switch display="inline"` para linhas compactas com label integrado e alinhamento previsivel. | `npm run build`; `npm run build-storybook`; build de consumidor. |
342
+ | `0.1.7` | 2026-06-16 | Minor pre-v1 | Adiciona props de customizacao dos botoes de aparencia em `ThemePreferencesSelector`. | `npm run build`; build de consumidor. |
343
+ | `0.1.6` | 2026-06-16 | Patch | Forca o destaque da aparencia selecionada por CSS explicito em `[aria-pressed='true']`. | `npm run build`; `npm run build-storybook`; build de consumidor. |
344
+ | `0.1.5` | 2026-06-16 | Patch | Aplica o destaque da aparencia selecionada por estilo inline para evitar perda por ordem/geracao de CSS nos consumidores. | `npm run build`; `npm run build-storybook`; build de consumidor. |
342
345
  | `0.1.4` | 2026-06-16 | Patch | Usa estado `data-selected` no `ThemePreferencesSelector` para manter o destaque da aparencia selecionada nos consumidores. | `npm run build`; `npm run build-storybook`. |
343
346
  | `0.1.3` | 2026-06-16 | Patch | Atualiza Storybook para `10.4.6`, documenta `ThemePreferencesSelector` e reforca o destaque visual da aparencia selecionada. | `npm run build`; `npm run build-storybook`. |
344
- | `0.1.0` | 2026-06-15 | Breaking pre-v1 | Define `Filter.Root`/`Filter.Footer` como contrato final de filtros e remove aliases públicos provisórios. | `npm run build`; builds de `EloDesk.CRM` e `EloDesk.CRM.Portal`. |
347
+ | `0.1.0` | 2026-06-15 | Breaking pre-v1 | Define `Filter.Root`/`Filter.Footer` como contrato final de filtros e remove aliases públicos provisórios. | `npm run build`; builds de consumidores. |
345
348
  | `0.0.7` | 2026-06-14 | Breaking pre-v1 | Publica API composicional `SearchWorkspace.Root` e `SearchFilter.Root`/`SearchFilter.Footer` para consultas com filtros compactos. | Pendente antes da publicacao. |
346
349
  | `0.0.5` | 2026-06-14 | Minor pre-v1 | Adiciona `Table.Root isFramed`, `fill`, `viewportClassName` e `wrapperProps` para controlar frame e ocupacao de espaco sem classes ad-hoc. | `npm run build`. |
347
350
  | `0.0.4` | 2026-06-14 | Minor pre-v1 | Adiciona `Table.Row isInteractive` para controlar cursor de linhas interativas, com padrao `true`. | `npm run build`. |
348
- | `0.0.3` | 2026-06-14 | Breaking pre-v1 | Define API final de `Card` por slots explicitos; remove `<Card>` chamavel, `Card.Content` e `CardContentProps`. | `npm run build`; builds de `EloDesk.CRM` e `EloDesk.CRM.Portal`. |
351
+ | `0.0.3` | 2026-06-14 | Breaking pre-v1 | Define API final de `Card` por slots explicitos; remove `<Card>` chamavel, `Card.Content` e `CardContentProps`. | `npm run build`; builds de consumidores. |
349
352
  | `0.0.2` | 2026-06-14 | Minor pre-v1 | Publica pacote no npm publico com novos slots de `Card` ainda retrocompativeis. | `npm run build`. |
350
353
  | `0.0.0` | 2026-06-14 | Inicial | Publicacao inicial do pacote `@wellingtonhlc/shared-ui`. | Build do pacote. |
351
354
 
352
- Ao criar uma nova versao:
353
-
354
- 1. Atualize `package.json`.
355
- 2. Atualize esta tabela com versao, data, tipo, resumo e validacao.
356
- 3. Rode `npm run check`.
357
- 4. Rode `npm pack --dry-run` e revise o conteudo do pacote.
358
- 5. Publique com `npm publish --access public --registry=https://registry.npmjs.org/`.
359
- 6. Atualize os consumidores afetados.
360
-
361
355
  ## Publicacao
362
356
 
363
- Publicacao npm:
357
+ Validacao e publicacao npm:
364
358
 
365
359
  ```bash
366
360
  npm run build
@@ -375,10 +369,10 @@ Quando o npm exigir OTP:
375
369
  npm publish --access public --registry=https://registry.npmjs.org/ --otp CODIGO_OTP
376
370
  ```
377
371
 
378
- Depois de publicar, atualize os consumidores:
372
+ Depois de publicar, atualize a aplicacao consumidora:
379
373
 
380
374
  ```bash
381
- npm install @wellingtonhlc/shared-ui@^VERSAO
375
+ npm install @wellingtonhlc/shared-ui@latest
382
376
  npm run build
383
377
  ```
384
378
 
@@ -388,7 +382,3 @@ Se o consumidor estiver com dev server Vite em execucao, reinicie com cache limp
388
382
  Remove-Item -Recurse -Force node_modules\.vite -ErrorAction SilentlyContinue
389
383
  npm run dev -- --force
390
384
  ```
391
-
392
- ## Template de demanda
393
-
394
- Use `docs/templates/novo-componente-shared-ui.md` quando solicitar um novo componente para este pacote.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wellingtonhlc/shared-ui",
3
- "version": "0.24.9",
3
+ "version": "0.24.10",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",