@wellingtonhlc/shared-ui 0.24.9 → 0.24.11

package/README.md

@@ -1,6 +1,6 @@
-# EloDesk CRM Shared UI
+# Wellington Shared UI
 
-Pacote de componentes visuais genericos usados pelos frontends `EloDesk.CRM` e `EloDesk.CRM.Portal`.
+Conjunto de componentes visuais padronizados, criado por Wellington Henrique para aplicacoes React.
 
 O objetivo deste pacote e concentrar componentes base, tokens, presets e helpers de UI reutilizaveis, sem regras de negocio de dominio.
 
@@ -20,8 +20,8 @@ export function ExamplePage() {
     <Page.Root>
       <Card.Root>
         <Card.Header>
-          <Card.Title>Clientes</Card.Title>
-          <Card.Description>Consulta operacional</Card.Description>
+          <Card.Title>Registros</Card.Title>
+          <Card.Description>Consulta de dados</Card.Description>
         </Card.Header>
         <Card.Body>
           <Button>Salvar</Button>
@@ -32,24 +32,16 @@ export function ExamplePage() {
 }
 ```
 
-## Escopo
+## Principios
 
-Inclua aqui apenas infraestrutura visual generica:
+Este pacote foi desenhado para oferecer infraestrutura visual generica:
 
 - componentes base de interface;
 - campos de formulario reutilizaveis;
-- primitives de acao;
+- primitivas de acao;
 - tokens, estilos e presets;
-- helpers sem dependencia de dominio.
-
-Nao inclua:
-
-- services HTTP;
-- rotas;
-- schemas de dominio;
-- permissoes;
-- regras de negocio;
-- componentes acoplados a `customer`, `supplier`, `item`, PDV, financeiro, estoque, licencas, suporte ou relatorios.
+- helpers sem dependencia de dominio;
+- composicao por slots quando o componente possui partes internas.
 
 ## Scripts
 
@@ -64,9 +56,9 @@ Nao inclua:
 | `npm run storybook` | Sobe o Storybook local. |
 | `npm run build-storybook` | Gera build estatico do Storybook. |
 
-## Validadores para consumidores
+## Validacao de Page Actions
 
-O pacote publica o CLI `shared-ui-check-page-actions` para validar o contrato de actions em projetos consumidores.
+O pacote publica o CLI `shared-ui-check-page-actions` para validar o contrato de actions em uma aplicacao.
 
 Contrato esperado:
 
@@ -75,7 +67,7 @@ Contrato esperado:
 - Props como `helpContent`, `helpLabel`, `position`, `align` e `size` pertencem ao `Page.Actions`.
 - Nao usar `ActionBar.*`, `Page.Root actions=...` dentro de `AppLayout`, Fragment, `div` ou `Page.ActionButton` solto como root de `AppLayout.actions`.
 
-Uso recomendado no consumidor:
+Uso recomendado:
 
 ```json
 {
@@ -101,15 +93,60 @@ Persistencia de preferencia continua sendo responsabilidade do consumidor. Use
 `localStorage`:
 
 ```tsx
-<Page.ActionsProvider
-  preferences={{
-    movable: true,
-    onPositionChange: setActionsPosition,
-    position: actionsPosition,
-  }}
->
-  <App />
-</Page.ActionsProvider>
+import { useCallback, useMemo, useState } from 'react';
+import { Page, type PageActionsPosition, type PageActionsPreferences } from '@wellingtonhlc/shared-ui';
+
+const storageKey = '@my-app/preference/page-actions-position';
+const positions: PageActionsPosition[] = ['left', 'top', 'right', 'bottom'];
+
+function readStoredPosition() {
+  const stored = window.localStorage.getItem(storageKey);
+  return positions.includes(stored as PageActionsPosition) ? (stored as PageActionsPosition) : undefined;
+}
+
+export function AppLayout({ children }: { children: React.ReactNode }) {
+  const [position, setPosition] = useState<PageActionsPosition | undefined>(readStoredPosition);
+
+  const handlePositionChange = useCallback(function handlePositionChange(nextPosition: PageActionsPosition) {
+    setPosition(nextPosition);
+    window.localStorage.setItem(storageKey, nextPosition);
+  }, []);
+
+  const preferences = useMemo<PageActionsPreferences>(
+    () => ({
+      mobilePosition: 'bottom',
+      movable: true,
+      onPositionChange: handlePositionChange,
+      position,
+    }),
+    [handlePositionChange, position],
+  );
+
+  return (
+    <Page.ActionsProvider preferences={preferences}>
+      <Page.ActionsSlot position="left" />
+      <main>{children}</main>
+      <Page.ActionsSlot position="right" />
+      <Page.ActionsSlot position="top" />
+      <Page.ActionsSlot position="bottom" />
+    </Page.ActionsProvider>
+  );
+}
+```
+
+Acoes de uma tela devem continuar usando `Page.Actions`; o provider apenas controla onde elas serao exibidas:
+
+```tsx
+import { Page } from '@wellingtonhlc/shared-ui/components/Page';
+import { Save } from 'lucide-react';
+
+export function EditPageActions() {
+  return (
+    <Page.Actions helpLabel="Ajuda" helpContent="Revise os dados antes de salvar.">
+      <Page.ActionButton icon={<Save />} label="Salvar" />
+    </Page.Actions>
+  );
+}
 ```
 
 Telas podem limitar o contrato localmente:
@@ -137,19 +174,6 @@ npm run build-storybook
 npm run check:storybook-static
 ```
 
-## Qualidade publica
-
-Todo export publico deve ter pelo menos uma destas evidencias:
-
-- teste de contrato observavel em `tests/`;
-- story em `stories/` cobrindo uso real, estados e variantes;
-- justificativa explicita na spec/PR quando o export for puramente auxiliar.
-
-Componentes interativos devem preservar acessibilidade verificavel: labels, roles, atributos
-`aria-*`, estado `disabled`/`loading`/`selected` quando aplicavel, foco e callbacks publicos.
-O gate `npm run test` inclui axe em composicoes representativas e nao deve ser burlado com
-snapshots de classe completa.
-
 ## Exportacoes
 
 Entrada principal:
@@ -267,21 +291,7 @@ Padrões do painel:
 - Limita a altura com `maxHeightClassName`; o default é `max-h-[calc(100vh-12rem)]`.
 - Aplica rolagem apenas na área de filtros.
 - Use `Filter.Footer` para manter botões sempre visíveis no rodapé do painel.
-- Em telas administrativas, campos internos devem preferir `size="sm"` e não devem usar formato `rounded-full`.
-
-## Contrato publico atual
-
-O pacote oficial e `@wellingtonhlc/shared-ui`, publicado no npm publico (`https://registry.npmjs.org/`).
-Ele deve permanecer generico: componentes visuais, utilitarios, tokens, estilos e preset Tailwind.
-
-Fora do contrato publico:
-
-- regra de negocio;
-- services HTTP;
-- rotas;
-- permissoes;
-- schemas de dominio;
-- textos ou fluxos especificos de CRM, licencas, pagamentos, suporte, relatorios ou clientes.
+- Em interfaces densas, campos dentro do painel devem preferir `size="sm"` e nao devem usar formato `rounded-full`.
 
 ## Contrato publico 0.1.0
 
@@ -299,17 +309,6 @@ Exports removidos:
 - `SearchWorkspace`: componha layout no consumidor ou com componentes genéricos.
 - `TabsUnderline` e `UnderlinedTabs`: use `TabsUnderlined`.
 
-## Padroes de implementacao
-
-- Exporte sempre o componente e seus tipos publicos em `src/index.ts`.
-- Prefira composicao por slots para componentes com partes internas (`Root`, `Header`, `Body`, `Footer`, `Actions`, etc.).
-- Evite aliases antes da v1; a API deve ser definitiva sempre que possivel.
-- Preserve nomes semanticos e contratos pequenos.
-- Use `cn` para composicao de classes.
-- Mantenha o pacote livre de regra de negocio dos consumidores.
-- Rode `npm run build` antes de publicar.
-- Valide pelo menos um consumidor quando a mudanca puder afetar runtime.
-
 ## Versionamento
 
 Este pacote segue SemVer, mesmo antes da v1:
@@ -322,12 +321,17 @@ Tabela de historico:
 
 | Versao | Data | Tipo | Resumo | Validacao |
 |--------|------|------|--------|-----------|
+| `0.24.11` | 2026-06-20 | Patch | Mantem o botao de ajuda antes das acoes da pagina para evitar que fique oculto em barras horizontais com overflow. | `npm run check`. |
+| `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`. |
+| `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. |
+| `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`. |
+| `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`. |
 | `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`. |
 | `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`. |
-| `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`. |
+| `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. |
 | `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`. |
-| `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`. |
-| `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`. |
+| `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. |
+| `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. |
 | `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`. |
 | `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`. |
 | `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 +339,23 @@ Tabela de historico:
 | `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`. |
 | `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`. |
 | `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`. |
-| `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`. |
-| `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`. |
-| `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`. |
-| `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`. |
+| `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. |
+| `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. |
+| `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. |
+| `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. |
 | `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`. |
 | `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`. |
-| `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`. |
+| `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. |
 | `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. |
 | `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`. |
 | `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`. |
-| `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`. |
+| `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. |
 | `0.0.2` | 2026-06-14 | Minor pre-v1 | Publica pacote no npm publico com novos slots de `Card` ainda retrocompativeis. | `npm run build`. |
 | `0.0.0` | 2026-06-14 | Inicial | Publicacao inicial do pacote `@wellingtonhlc/shared-ui`. | Build do pacote. |
 
-Ao criar uma nova versao:
-
-1. Atualize `package.json`.
-2. Atualize esta tabela com versao, data, tipo, resumo e validacao.
-3. Rode `npm run check`.
-4. Rode `npm pack --dry-run` e revise o conteudo do pacote.
-5. Publique com `npm publish --access public --registry=https://registry.npmjs.org/`.
-6. Atualize os consumidores afetados.
-
 ## Publicacao
 
-Publicacao npm:
+Validacao e publicacao npm:
 
 ```bash
 npm run build
@@ -375,10 +370,10 @@ Quando o npm exigir OTP:
 npm publish --access public --registry=https://registry.npmjs.org/ --otp CODIGO_OTP
 ```
 
-Depois de publicar, atualize os consumidores:
+Depois de publicar, atualize a aplicacao consumidora:
 
 ```bash
-npm install @wellingtonhlc/shared-ui@^VERSAO
+npm install @wellingtonhlc/shared-ui@latest
 npm run build
 ```
 
@@ -388,7 +383,3 @@ Se o consumidor estiver com dev server Vite em execucao, reinicie com cache limp
 Remove-Item -Recurse -Force node_modules\.vite -ErrorAction SilentlyContinue
 npm run dev -- --force
 ```
-
-## Template de demanda
-
-Use `docs/templates/novo-componente-shared-ui.md` quando solicitar um novo componente para este pacote.

package/dist/components/Page.js

@@ -210,7 +210,7 @@ function Actions({ align = 'start', __fromSlot = false, children, className, def
     }
     const helpButton = helpVisible ? (_jsx("div", { className: cn('flex shrink-0', isVertical && 'w-full justify-center'), children: _jsx(Tooltip, { className: cn('max-w-[22rem] px-3 py-2', helpClassName), content: helpContent, delayDuration: 120, openOnClick: true, side: getHelpSide(effectivePosition), children: _jsx(ActionButtonPrimitive, { "aria-label": helpLabel, icon: _jsx(CircleHelpIcon, { "aria-hidden": "true" }), tooltip: helpLabel }) }) })) : null;
     const moveButton = canMove ? (_jsxs("div", { className: cn('relative flex shrink-0', isVertical && 'w-full justify-center'), children: [_jsx(ActionButtonPrimitive, { "aria-haspopup": "menu", "aria-label": "Mover barra de acoes", "aria-expanded": isMenuOpen, className: cn(isDragging ? 'cursor-grabbing' : 'cursor-grab'), icon: _jsx(GripVerticalIcon, { "aria-hidden": "true" }), tooltip: "Mover barra de acoes", onClick: handleMoveMenuToggle, onKeyDown: handleMoveKeyDown, onPointerCancel: handleMovePointerCancel, onPointerDown: handleMovePointerDown, onPointerMove: handleMovePointerMove, onPointerUp: handleMovePointerUp }), isMenuOpen ? (_jsx("div", { role: "menu", className: cn('border-app-border bg-surface text-foreground absolute z-40 min-w-36 rounded-md border p-1 text-xs shadow-lg', isVertical ? 'left-full top-0 ml-2' : 'right-0 top-full mt-2'), children: effectiveAllowedPositions.map((nextPosition) => (_jsx("button", { type: "button", role: "menuitemradio", "aria-checked": nextPosition === effectivePosition, className: cn('hover:bg-background-secondary flex w-full cursor-pointer items-center rounded px-2 py-1.5 text-left', nextPosition === effectivePosition && 'font-semibold text-brand'), onClick: () => handleSelectPosition(nextPosition), children: positionLabels[nextPosition] }, nextPosition))) })) : null] })) : null;
-    const actions = (_jsxs(ActionGroupPrimitive, { align: align, size: size, className: cn('min-w-0', isVertical ? 'w-full flex-col items-stretch' : 'min-w-0 overflow-x-auto overflow-y-hidden', alignClasses[align]), children: [children, helpButton, moveButton] }));
+    const actions = (_jsxs(ActionGroupPrimitive, { align: align, size: size, className: cn('min-w-0', isVertical ? 'w-full flex-col items-stretch' : 'min-w-0 overflow-x-auto overflow-y-hidden', alignClasses[align]), children: [helpButton, children, moveButton] }));
     return (_jsxs("div", { className: cn('flex min-w-0', positionClasses[effectivePosition], isVertical ? 'flex-col' : 'items-center', className), children: [actions, isDragging ? _jsx(PageActionsDropZones, { activePosition: dragTarget ?? effectivePosition, allowedPositions: effectiveAllowedPositions }) : null] }));
 }
 function PageActionsDropZones({ activePosition, allowedPositions }) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@wellingtonhlc/shared-ui",
-    "version": "0.24.9",
+    "version": "0.24.11",
     "private": false,
     "type": "module",
     "main": "./dist/index.js",