@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

package/seedgridKB/SeedGrid/SeedGrid-components/navegacao-e-overlay/Exemplos.md

@@ -0,0 +1,561 @@
+---
+tags: [seedgrid, front, component, navegacao-e-overlay]
+fonte: front/seedgrid-fe-components/apps/showcase/src/app/components (sg-dock-menu, sg-popup, sg-dialog, sg-confirmation-dialog, sg-wizard)
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# Exemplos — navegação e overlay
+
+Visão geral: [[SeedGrid/SeedGrid-components/navegacao-e-overlay/Visao-geral|Navegação e overlay]] · API: [[SeedGrid/SeedGrid-components/navegacao-e-overlay/API|API]]
+
+Todos os exemplos abaixo foram verificados com type-check TypeScript (`strict`) contra `packages/seedgrid-fe-components/src/index.ts` no commit `ad30fc11de` (resultado: OK). Os marcados "1:1" são cópias exatas dos arquivos `samples/*.tsx.sample` do showcase. Os do `SgDockMenu` foram **completados** (imports e componente) porque os samples do showcase desse componente são trechos sem `import`/`export` — o JSX e os dados são os do sample citado.
+
+## SgDockMenu
+
+### Dock básico ancorado num container
+Baseado em `apps/showcase/src/app/components/sg-dock-menu/samples/basico.tsx.sample` (completado com imports). `style={{ position: "absolute" }}` prende o dock ao container `relative`.
+
+```tsx
+import React from "react";
+import { Bell, Home, Mail, Settings, User } from "lucide-react";
+import { SgDockMenu, type SgDockMenuItem } from "@seedgrid/fe-components";
+
+const items: SgDockMenuItem[] = [
+  { id: "home", icon: <Home size={24} />, label: "Home" },
+  { id: "mail", icon: <Mail size={24} />, label: "Mail", badge: 5 },
+  { id: "notifications", icon: <Bell size={24} />, label: "Notifications", badge: 12 },
+  { id: "settings", icon: <Settings size={24} />, label: "Settings" },
+  { id: "profile", icon: <User size={24} />, label: "Profile" }
+];
+
+export default function Example() {
+  return (
+    <div className="relative h-64 rounded-lg border-2 border-dashed border-border bg-muted/20">
+      <SgDockMenu id="basic-dock" items={items} position="center-bottom" zIndex={10} style={{ position: "absolute" }} />
+    </div>
+  );
+}
+```
+
+### Arraste com posição persistida + callbacks e item desabilitado
+Combina `samples/drag-and-drop.tsx.sample` e `samples/callbacks-e-disabled.tsx.sample` (completado). Com `dragId`, a posição arrastada é salva (`localStorage` ou `SgEnvironmentProvider`) e o clique direito oferece "resetar posição".
+
+```tsx
+import React from "react";
+import { Home, Mail, Settings } from "lucide-react";
+import { SgDockMenu, type SgDockMenuItem } from "@seedgrid/fe-components";
+
+const items: SgDockMenuItem[] = [
+  { id: "home", icon: <Home size={24} />, label: "Home" },
+  { id: "mail", icon: <Mail size={24} />, label: "Mail", badge: 5 },
+  { id: "settings", icon: <Settings size={24} />, label: "Settings", disabled: true }
+];
+
+export default function Example() {
+  const [eventLog, setEventLog] = React.useState<string[]>([]);
+  const callbackItems: SgDockMenuItem[] = items.map((item) => ({
+    ...item,
+    onClick: () => setEventLog((prev) => [`${item.label} clicked`, ...prev].slice(0, 10))
+  }));
+
+  return (
+    <div className="space-y-4">
+      <div className="relative h-80 rounded-lg border-2 border-dashed border-border bg-muted/20">
+        <SgDockMenu
+          id="draggable-dock"
+          dragId="demo-dockmenu-draggable"
+          items={callbackItems}
+          position="center-bottom"
+          enableDragDrop
+          zIndex={10}
+          style={{ position: "absolute" }}
+        />
+      </div>
+      <div className="h-32 overflow-y-auto rounded border border-border bg-foreground/5 p-2 font-mono text-xs">
+        {eventLog.map((entry, idx) => <div key={idx}>{entry}</div>)}
+      </div>
+    </div>
+  );
+}
+```
+
+## SgPopup
+
+### Popup com ações (1:1)
+`apps/showcase/src/app/components/sg-popup/samples/basico.tsx.sample` — o consumidor abre pelo botão âncora; o popup fecha por clique fora, `Esc` ou clique numa ação.
+
+```tsx
+import React from "react";
+import { SgButton, SgPopup } from "@seedgrid/fe-components";
+
+export default function Example() {
+  const btnRef = React.useRef<HTMLButtonElement>(null);
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <SgButton ref={btnRef} onClick={() => setOpen(true)}>Abrir popup</SgButton>
+      <SgPopup
+        title="Configuracao"
+        subtitle="Resumo da acao"
+        open={open}
+        onOpenChange={setOpen}
+        anchorRef={btnRef as React.RefObject<HTMLElement>}
+        placement="auto"
+        preferPlacement="right"
+        align="start"
+        actions={[
+          { label: "Confirmar" },
+          { label: "Cancelar" }
+        ]}
+      />
+    </>
+  );
+}
+```
+
+### Ações com ícone e hint (1:1)
+`apps/showcase/src/app/components/sg-popup/samples/icone-hint.tsx.sample`
+
+```tsx
+import React from "react";
+import { Check, X } from "lucide-react";
+import { SgButton, SgPopup } from "@seedgrid/fe-components";
+
+export default function Example() {
+  const btnRef = React.useRef<HTMLButtonElement>(null);
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <SgButton ref={btnRef} onClick={() => setOpen(true)}>Abrir popup com icones</SgButton>
+      <SgPopup
+        title="Aprovacao"
+        open={open}
+        onOpenChange={setOpen}
+        anchorRef={btnRef as React.RefObject<HTMLElement>}
+        placement="auto"
+        preferPlacement="right"
+        align="start"
+        actions={[
+          {
+            label: "Aprovar",
+            hint: "Aprova a acao atual",
+            icon: <Check className="h-4 w-4" />
+          },
+          {
+            label: "Rejeitar",
+            hint: "Cancela a acao atual",
+            icon: <X className="h-4 w-4" />
+          }
+        ]}
+      />
+    </>
+  );
+}
+```
+
+## SgDialog
+
+### Dialog com cabeçalho, rodapé e foco inicial (1:1)
+`apps/showcase/src/app/components/sg-dialog/samples/basico.tsx.sample` — usa `leading`/`trailing`, `customColor`, `elevation` como `box-shadow` literal e `data-sg-dialog-initial-focus`.
+
+```tsx
+import React from "react";
+import { SgButton, SgDialog } from "@seedgrid/fe-components";
+
+export default function Example() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <SgButton onClick={() => setOpen(true)}>Abrir dialog</SgButton>
+      <SgDialog
+        open={open}
+        onOpenChange={setOpen}
+        title="Confirmar acao"
+        subtitle="Exemplo basico"
+        customColor="#fff7ed"
+        elevation="0 0 0 1px rgba(234, 88, 12, 0.22), 0 24px 56px rgba(234, 88, 12, 0.28)"
+        style={{ border: "1px solid rgba(59, 130, 246, 0.25)" }}
+        leading={<span>O</span>}
+        trailing={<span>ID: 428</span>}
+        footer={
+          <>
+            <SgButton appearance="ghost" onClick={() => setOpen(false)}>Cancelar</SgButton>
+            <SgButton onClick={() => setOpen(false)}>Confirmar</SgButton>
+          </>
+        }
+      >
+        <div className="space-y-2 text-sm">
+          <p>Conteudo principal do dialog.</p>
+          <input
+            data-sg-dialog-initial-focus="true"
+            className="h-10 w-full rounded-lg border border-border bg-background px-3"
+            placeholder="Digite algo"
+          />
+        </div>
+      </SgDialog>
+    </>
+  );
+}
+```
+
+### Modo estrito (1:1)
+`apps/showcase/src/app/components/sg-dialog/samples/strict.tsx.sample` — sem X, sem fechar por overlay/Esc. Atenção: com `closeOnEsc={false}` o *focus trap* de `Tab` também fica desligado (ver [[SeedGrid/SeedGrid-components/navegacao-e-overlay/API#SgDialog|API › SgDialog]]).
+
+```tsx
+import React from "react";
+import { SgButton, SgDialog } from "@seedgrid/fe-components";
+
+export default function Example() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <SgButton appearance="outline" onClick={() => setOpen(true)}>Abrir modo estrito</SgButton>
+      <SgDialog
+        open={open}
+        onOpenChange={setOpen}
+        closeable={false}
+        closeOnOverlayClick={false}
+        closeOnEsc={false}
+        title="Confirmacao obrigatoria"
+        subtitle="Nao fecha por ESC nem overlay"
+        footer={
+          <>
+            <SgButton appearance="ghost" onClick={() => setOpen(false)}>Cancelar</SgButton>
+            <SgButton onClick={() => setOpen(false)}>Confirmar</SgButton>
+          </>
+        }
+      >
+        <div className="text-sm text-muted-foreground">Use este modo quando o usuario precisa tomar uma decisao explicita.</div>
+      </SgDialog>
+    </>
+  );
+}
+```
+
+### Auto-fechamento (1:1)
+`apps/showcase/src/app/components/sg-dialog/samples/auto-close.tsx.sample`
+
+```tsx
+import React from "react";
+import { SgButton, SgDialog } from "@seedgrid/fe-components";
+
+export default function Example() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <SgButton appearance="outline" onClick={() => setOpen(true)}>Abrir com auto close</SgButton>
+      <SgDialog
+        open={open}
+        onOpenChange={setOpen}
+        autoCloseMs={3000}
+        title="Sincronizacao concluida"
+        subtitle="O dialog fecha em 3 segundos"
+      >
+        <div className="text-sm text-muted-foreground">Esse exemplo mostra o uso de autoCloseMs.</div>
+      </SgDialog>
+    </>
+  );
+}
+```
+
+## SgConfirmationDialog
+
+### Confirmação básica (1:1)
+`apps/showcase/src/app/components/sg-confirmation-dialog/samples/basico.tsx.sample` — `onCancel` também dispara ao dispensar pelo overlay/Esc.
+
+```tsx
+import React from "react";
+import { SgButton, SgConfirmationDialog } from "@seedgrid/fe-components";
+
+export default function Example() {
+  const [open, setOpen] = React.useState(false);
+  const [result, setResult] = React.useState("none");
+
+  return (
+    <>
+      <SgButton onClick={() => setOpen(true)}>delete permission</SgButton>
+      <SgConfirmationDialog
+        open={open}
+        onOpenChange={setOpen}
+        title="Delete permission"
+        message="Confirm delete?"
+        severity="danger"
+        onCancel={() => setResult("cancel")}
+        onConfirm={() => setResult("confirm")}
+      />
+      <p className="text-xs text-muted-foreground">result: {result}</p>
+    </>
+  );
+}
+```
+
+### Botões customizados (1:1)
+`apps/showcase/src/app/components/sg-confirmation-dialog/samples/botoes-customizados.tsx.sample`
+
+```tsx
+import React from "react";
+import { Trash2, X } from "lucide-react";
+import { SgButton, SgConfirmationDialog, type SgConfirmationDialogButtonConfig } from "@seedgrid/fe-components";
+
+const cancelButton: SgConfirmationDialogButtonConfig = {
+  label: "No, keep it",
+  icon: <X className="size-4" />,
+  severity: "secondary",
+  appearance: "ghost"
+};
+
+const confirmButton: SgConfirmationDialogButtonConfig = {
+  label: "Yes, delete",
+  icon: <Trash2 className="size-4" />,
+  severity: "danger"
+};
+
+export default function Example() {
+  const [open, setOpen] = React.useState(false);
+  const [log, setLog] = React.useState("none");
+
+  return (
+    <>
+      <SgButton severity="danger" onClick={() => setOpen(true)}>delete row</SgButton>
+      <SgConfirmationDialog
+        open={open}
+        onOpenChange={setOpen}
+        title="Delete permission"
+        message="Confirm delete?"
+        severity="danger"
+        cancelButton={cancelButton}
+        confirmButton={confirmButton}
+        onCancel={() => setLog("cancel")}
+        onConfirm={() => setLog("confirm")}
+      />
+      <p className="text-xs text-muted-foreground">last action: {log}</p>
+    </>
+  );
+}
+```
+
+## SgWizard / SgWizardPage
+
+### Stepper numerado (1:1)
+`apps/showcase/src/app/components/sg-wizard/samples/stepper-numerado.tsx.sample`
+
+```tsx
+import React from "react";
+import { SgWizard, SgWizardPage } from "@seedgrid/fe-components";
+
+export default function Example() {
+  return (
+    <SgWizard stepper="numbered" onFinish={() => {}}>
+      <SgWizardPage title="Introducao">
+        <div className="rounded border border-border bg-foreground/5 p-4">
+          <div className="text-sm font-semibold">1. Introducao</div>
+          <p className="mt-1 text-sm text-muted-foreground">Conteudo introdutorio.</p>
+        </div>
+      </SgWizardPage>
+      <SgWizardPage title="Detalhes">
+        <div className="rounded border border-border bg-foreground/5 p-4">
+          <div className="text-sm font-semibold">2. Detalhes</div>
+          <p className="mt-1 text-sm text-muted-foreground">Preencha os detalhes.</p>
+        </div>
+      </SgWizardPage>
+      <SgWizardPage title="Revisao">
+        <div className="rounded border border-border bg-foreground/5 p-4">
+          <div className="text-sm font-semibold">3. Revisao</div>
+          <p className="mt-1 text-sm text-muted-foreground">Revise as informacoes.</p>
+        </div>
+      </SgWizardPage>
+      <SgWizardPage title="Confirmacao">
+        <div className="rounded border border-border bg-foreground/5 p-4">
+          <div className="text-sm font-semibold">4. Confirmacao</div>
+          <p className="mt-1 text-sm text-muted-foreground">Confirme e finalize.</p>
+        </div>
+      </SgWizardPage>
+    </SgWizard>
+  );
+}
+```
+
+### Validação por etapa com `validateStep` (1:1)
+`apps/showcase/src/app/components/sg-wizard/samples/validatestep.tsx.sample`
+
+```tsx
+import React from "react";
+import { SgInputEmail, SgInputText, SgWizard, SgWizardPage } from "@seedgrid/fe-components";
+
+export default function Example() {
+  const [formValues, setFormValues] = React.useState({ name: "", email: "" });
+
+  return (
+    <SgWizard
+      validateStep={(index) => {
+        if (index === 0) {
+          return Boolean(formValues.name.trim()) && Boolean(formValues.email.trim());
+        }
+        return true;
+      }}
+      onFinish={() => {}}
+    >
+      <SgWizardPage title="Campos obrigatorios">
+        <div className="grid gap-3 sm:grid-cols-2">
+          <SgInputText
+            id="validate-step-name"
+            label="Nome"
+            inputProps={{
+              value: formValues.name,
+              onChange: (event) =>
+                setFormValues((prev) => ({ ...prev, name: event.target.value })),
+            }}
+          />
+          <SgInputEmail
+            id="validate-step-email"
+            label="Email"
+            inputProps={{
+              value: formValues.email,
+              onChange: (event) =>
+                setFormValues((prev) => ({ ...prev, email: event.target.value })),
+            }}
+          />
+        </div>
+      </SgWizardPage>
+      <SgWizardPage title="Etapa liberada">
+        <div className="rounded border border-border bg-foreground/5 p-4">
+          <div className="text-sm font-semibold">Etapa seguinte</div>
+          <p className="mt-1 text-sm text-muted-foreground">
+            So abre quando nome e email foram preenchidos.
+          </p>
+        </div>
+      </SgWizardPage>
+    </SgWizard>
+  );
+}
+```
+
+### Guarda assíncrona e conclusão assíncrona (1:1)
+`apps/showcase/src/app/components/sg-wizard/samples/onbeforenext-async.tsx.sample`
+
+```tsx
+import React from "react";
+import { SgWizard, SgWizardPage } from "@seedgrid/fe-components";
+
+export default function Example() {
+  return (
+    <SgWizard
+      onBeforeNext={async () => {
+        await new Promise((resolve) => setTimeout(resolve, 600));
+        return true;
+      }}
+      onFinish={async () => {
+        await new Promise((resolve) => setTimeout(resolve, 400));
+      }}
+    >
+      <SgWizardPage>
+        <div className="rounded border border-border bg-foreground/5 p-4">
+          <div className="text-sm font-semibold">Validacao assicrona</div>
+          <p className="mt-1 text-sm text-muted-foreground">
+            Antes de avancar, o wizard aguarda uma promise.
+          </p>
+        </div>
+      </SgWizardPage>
+      <SgWizardPage>
+        <div className="rounded border border-border bg-foreground/5 p-4">
+          <div className="text-sm font-semibold">Segunda etapa</div>
+          <p className="mt-1 text-sm text-muted-foreground">
+            O submit final tambem pode ser assicrono.
+          </p>
+        </div>
+      </SgWizardPage>
+    </SgWizard>
+  );
+}
+```
+
+### Bloqueio declarativo com `nextDisabled` (1:1)
+`apps/showcase/src/app/components/sg-wizard/samples/nextdisabled.tsx.sample`
+
+```tsx
+import React from "react";
+import { SgInputText, SgWizard, SgWizardPage } from "@seedgrid/fe-components";
+
+/**
+ * `nextDisabled` — bloqueio JA conhecido.
+ *
+ * `onBeforeNext` e `validateStep` so agem no clique: o botao continua com aparencia de habilitado
+ * e, quando eles recusam, nada acontece na tela. Quando o consumidor JA sabe que a etapa nao pode
+ * avancar — tipicamente o resultado de uma checagem assincrona que ja terminou —, `nextDisabled`
+ * deixa isso visivel: botao opaco, cursor de bloqueio e stepper sem oferecer as proximas etapas.
+ */
+export default function Example() {
+  const [codigo, setCodigo] = React.useState("");
+  const [checando, setChecando] = React.useState(false);
+  const [jaUsado, setJaUsado] = React.useState(false);
+
+  // Simula a consulta ao servidor ao sair do campo.
+  async function verificarCodigo() {
+    if (!codigo.trim()) return;
+    setChecando(true);
+    await new Promise((resolve) => setTimeout(resolve, 600));
+    setJaUsado(codigo.trim().toUpperCase() === "SG-123");
+    setChecando(false);
+  }
+
+  return (
+    <SgWizard
+      // Durante a consulta o wizard ja desabilita sozinho enquanto aguarda onBeforeNext; aqui o
+      // bloqueio PERMANECE depois que a resposta chegou.
+      nextDisabled={jaUsado}
+      onFinish={() => undefined}
+    >
+      <SgWizardPage title="Convite">
+        <SgInputText
+          id="wizard-codigo-convite"
+          label="Codigo do convite"
+          error={jaUsado ? "Este codigo ja foi utilizado." : undefined}
+          onChange={(value) => {
+            setCodigo(value);
+            setJaUsado(false); // digitou de novo: reabre o avanco ate a proxima checagem
+          }}
+          onExit={() => void verificarCodigo()}
+        />
+        <p className="mt-2 text-sm text-muted-foreground">
+          {checando
+            ? "Verificando o codigo..."
+            : 'Digite "SG-123" e saia do campo: o botao Proximo fica desabilitado.'}
+        </p>
+      </SgWizardPage>
+      <SgWizardPage title="Conclusao">
+        <div className="rounded border border-border bg-foreground/5 p-4">
+          <div className="text-sm font-semibold">Codigo aceito</div>
+          <p className="mt-1 text-sm text-muted-foreground">
+            So se chega aqui com um codigo que a checagem liberou.
+          </p>
+        </div>
+      </SgWizardPage>
+    </SgWizard>
+  );
+}
+```
+
+### Helpers puros do wizard
+Exemplo próprio (não vem do showcase), baseado nas assinaturas de `src/wizard/logic.ts` e nos casos de `tests/wizard-logic.test.mjs`.
+
+```tsx
+import { canNavigateToWizardStep, canProceedWizardAction, clampWizardStep } from "@seedgrid/fe-components";
+
+export async function demo(): Promise<boolean> {
+  const step = clampWizardStep(5, 3); // 2
+  const canGoBack = canNavigateToWizardStep({ currentStep: step, targetStep: 0, pageCount: 3, stepNavigation: "previous" });
+  const ok = await canProceedWizardAction({
+    validateCurrentPage: () => true,
+    validateStep: async (index) => index >= 0,
+    step
+  });
+  return canGoBack && ok;
+}
+```

package/seedgridKB/SeedGrid/SeedGrid-components/navegacao-e-overlay/Visao-geral.md

@@ -0,0 +1,82 @@
+---
+tags: [seedgrid, front, component, navegacao-e-overlay]
+fonte: front/seedgrid-fe-components/packages/seedgrid-fe-components/src/menus, front/seedgrid-fe-components/packages/seedgrid-fe-components/src/overlay, front/seedgrid-fe-components/packages/seedgrid-fe-components/src/wizard
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# Navegação e overlay — visão geral
+
+Grupo de componentes do pacote `@seedgrid/fe-components` que reúne **três pastas pequenas** de `src/` numa só nota, por terem pouco conteúdo cada uma:
+
+| Pasta de origem | Conteúdo |
+|---|---|
+| `src/menus/` | `SgDockMenu` (dock flutuante estilo macOS) e os helpers puros de `dock-menu-logic.ts` |
+| `src/overlay/` | `SgPopup` (overlay ancorado, não modal), `SgDialog` (modal), `SgConfirmationDialog` (modal de confirmação construído sobre `SgDialog`) |
+| `src/wizard/` | `SgWizard` + `SgWizardPage` (fluxo multi-etapas) e os helpers puros de `logic.ts` |
+
+> O menu de navegação lateral/horizontal (`SgMenu`), breadcrumb, toolbar e page control ficam em `src/layout/` — ver [[SeedGrid/SeedGrid-components/layout/Visao-geral|Layout]].
+
+- API completa: [[SeedGrid/SeedGrid-components/navegacao-e-overlay/API|API de navegação e overlay]]
+- Exemplos: [[SeedGrid/SeedGrid-components/navegacao-e-overlay/Exemplos|Exemplos de navegação e overlay]]
+- Fundamentos do pacote (instalação, CSS, i18n): [[SeedGrid/SeedGrid-components/fundamentos/Visao-geral|Fundamentos]]
+
+## Componentes
+
+| Componente | Exportado | Para que serve | Showcase |
+|---|---|---|---|
+| `SgDockMenu` | sim | Dock flutuante de ações com ícones, badges, efeito *magnify*, 8 posições ancoradas e arraste com posição persistida | `/components/sg-dock-menu` |
+| `SgPopup` | sim | Overlay contextual ancorado a um elemento (`anchorRef`), com título, lista de ações e/ou conteúdo livre; fecha por clique fora/Esc | `/components/sg-popup` |
+| `SgDialog` | sim | Modal com cabeçalho/corpo/rodapé, severidade, animação, auto-fechamento, foco inicial, *focus trap* e bloqueio de scroll | `/components/sg-dialog` |
+| `SgConfirmationDialog` | sim | `SgDialog` especializado em confirmar/cancelar, com ícone por severidade e botões configuráveis | `/components/sg-confirmation-dialog` |
+| `SgWizard` | sim | Fluxo em etapas com stepper opcional, validação automática dos inputs da etapa, guardas síncronas/assíncronas e conclusão assíncrona | `/components/sg-wizard` |
+| `SgWizardPage` | sim | Etapa de um `SgWizard` (título/ícone usados no stepper) | `/components/sg-wizard` |
+
+Exportação confirmada em `src/index.ts` (barrel; o `package.json` expõe apenas `"."` e `"./style.css"`).
+
+### Funções e tipos públicos relacionados
+
+| Símbolo | Origem | Exportado |
+|---|---|---|
+| `resolveDockMenuOrientation`, `resolveDockMenuLiftDirection`, `buildDockMenuLayout`, `buildDockMenuItemMotion`, `buildDockMenuLabelStyle`, `buildDockMenuContainerStyle`, `buildDockMenuContextMenuState` | `src/menus/dock-menu-logic.ts` | sim |
+| `buildDockMenuStorageKey` (e `parseStoredPanelDragPosition`, compartilhado com a toolbar) | `src/layout/drag-position.ts` | sim |
+| `clampWizardStep`, `canNavigateToWizardStep`, `canProceedWizardAction` | `src/wizard/logic.ts` | sim |
+| Tipos `SgDockMenuProps`, `SgDockMenuItem`, `SgDockMenuPosition`, `SgDockMenuOrientation` | `SgDockMenu.tsx` | sim |
+| Tipos `SgPopupProps`, `SgPopupAction`, `SgPopupPlacement`, `SgPopupPreferPlacement`, `SgPopupAlign`, `SgPopupSeverity` | `SgPopup.tsx` | sim |
+| Tipos `SgDialogProps`, `SgDialogSize`, `SgDialogSeverity`, `SgDialogAnimation` | `SgDialog.tsx` | sim |
+| Tipos `SgConfirmationDialogProps`, `SgConfirmationDialogButtonConfig` | `SgConfirmationDialog.tsx` | sim |
+| Tipos `SgWizardProps`, `SgWizardPageProps`, `SgWizardLabels`, `SgWizardStepper`, `WizardStepNavigation`, `WizardGuardRunner` | `SgWizard.tsx`, `logic.ts` | sim |
+
+Os helpers do dock e do wizard são funções puras usadas internamente pelos componentes e cobertas por testes; o export público permite reuso/teste, mas o uso normal é só via componente. Detalhes em [[SeedGrid/SeedGrid-components/navegacao-e-overlay/API|API]].
+
+## Como se compõem
+
+- Nenhum componente do grupo exige provider. Todos chamam `useComponentsI18n()` para textos padrão (ex.: `components.dialog.close`, `components.wizard.next`) — opcionalmente envolva a app em `SgComponentsI18nProvider` (ver [[SeedGrid/SeedGrid-components/fundamentos/API|API › i18n]]). **Confirmado**.
+- `SgDockMenu` persiste a posição arrastada: com `SgEnvironmentProvider` presente usa `useSgPersistence()` (estratégia/namespace do ambiente); sem ele usa `localStorage` direto, chave `sg-dockmenu-pos:<dragId>:<viewport|parent>`. Ver [[SeedGrid/SeedGrid-components/providers/API|Providers]]. **Confirmado** (`SgDockMenu.tsx` → `loadStoredPosition`/`saveStoredPosition`).
+- `SgPopup` e `SgDialog` renderizam via `createPortal(..., document.body)`. `SgConfirmationDialog` compõe `SgDialog` + `SgButton` (rodapé).
+- `SgWizard` só considera filhos diretos cujo `type === SgWizardPage`; outros filhos são descartados. A validação automática procura elementos com atributo `data-sg-error` dentro da etapa — atributo emitido pelos inputs SeedGrid (ex.: `SgInputText`, `SgInputNumber`), ver [[SeedGrid/SeedGrid-components/inputs-texto/Visao-geral|Inputs de texto]]. **Confirmado** (`SgWizard.tsx` → `validateCurrentPage`).
+
+## Dependências
+
+- Peer: `react`, `react-dom` (portais). Nenhuma lib externa específica deste grupo. Os exemplos do showcase usam `lucide-react` (peer opcional do pacote) para ícones.
+
+## Testes (não executados)
+
+| Arquivo | Cobertura |
+|---|---|
+| `tests/overlay.test.mjs` | Contratos estáticos: textos padrão de `SgConfirmationDialog`/`SgDialog`/`SgPopup` vindos de chaves i18n; padrões `closeOnCancel/closeOnConfirm = true`; dismiss do dialog roteado para o fluxo de cancelamento; `closeOnEsc`/`closeOnOverlayClick`/`closeOnOutsideClick`/`closeOnEscape` ligados por padrão; popup usa `title` antes do aria-label i18n |
+| `tests/wizard.test.mjs` | Render SSR: labels traduzidos, clamp de `initialStep`, override de labels, stepper `none`, navegação desabilitada, `nextDisabled` |
+| `tests/wizard-logic.test.mjs` | `clampWizardStep`, `canNavigateToWizardStep` (modos), `canProceedWizardAction` (ordem e interrupção das guardas) |
+| `tests/buttons-menus.test.mjs` | `SgDockMenu` com botões acessíveis/disabled; helpers `buildDockMenu*`/`resolveDockMenu*`, `buildDockMenuStorageKey` determinísticos |
+| `tests/buttons-menus-dom.test.mjs` (jsdom) | Dock: menu de contexto de reset e persistência de arraste em `localStorage`; Wizard: avançar/voltar, clique no stepper, guardas, validação de inputs; Popup: fecha por clique fora e Esc |
+
+## Limitações e observações
+
+- `SgPopup` não abre sozinho ao clicar na âncora: o consumidor controla `open`/`onOpenChange` (o clique na âncora é ignorado pelo "clique fora"). **Confirmado**.
+- No `SgDialog`, o *focus trap* de `Tab` vive no mesmo efeito do `Esc`: com `closeOnEsc={false}` o foco **não** fica preso no modal. **Confirmado** (`SgDialog.tsx`, efeito `onKeyDown`).
+- `SgDialog.onClose` só dispara pelos fechamentos internos (botão X, overlay, Esc, `autoCloseMs`); mudar `open` para `false` de fora não chama `onClose`. **Confirmado**.
+- `SgWizard` chama `onStepChange` num efeito com dependências `[props, step]`: além das trocas de etapa, ele dispara de novo sempre que o wizard re-renderiza com um novo objeto `props`. **Confirmado** (código); impacto prático = **Inferência**.
+- `SgWizard` não expõe etapa controlada (não há `step`/`activeStep` como prop) nem `ref`.
+- `SgDockMenu`: `item.badge && (...)` — badge `0` não renderiza a bolha e o React imprime `0` como texto. **Inferência** (semântica de JSX com `&&`).
+- O grupo não tem menu de contexto genérico; o menu de contexto do dock é apenas o diálogo "resetar posição".