@1doc/1ds-react 0.0.1 → 2.7.1

package/src/teste/Drawer.test.tsx

@@ -0,0 +1,265 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useState } from "react";
+import Drawer from "../components/Drawer/Drawer";
+import Button from "../components/Button/Button";
+
+/**
+ * O Drawer é overlay modal: prende o foco, fecha no Escape e devolve o foco a
+ * quem abriu. Nada disso aparece numa foto, e três dos casos guardados aqui são
+ * defeitos que a revisão encontrou e que já estavam escritos no componente:
+ *
+ *  - desmontar COM o painel aberto (`{aberto && <Drawer open …/>}`, o consumo
+ *    mais comum) deixava o foco no `<body>`;
+ *  - o trap contava focáveis invisíveis, e `.focus()` neles é no-op — um
+ *    Accordion fechado dentro da gaveta matava o trap no meio da sessão;
+ *  - o diálogo podia ficar sem nome acessível.
+ */
+
+/** Monta o Drawer atrás de um gatilho, como o consumo real. */
+function ComGatilho(props: Record<string, any> = {}) {
+  const [aberto, setAberto] = useState(false);
+  return (
+    <>
+      <Button variant="primary" onClick={() => setAberto(true)}>
+        Abrir
+      </Button>
+      <Drawer
+        open={aberto}
+        onClose={() => setAberto(false)}
+        title="Detalhes"
+        {...props}
+      >
+        <Button variant="secondary">Primeiro</Button>
+        <Button variant="secondary">Último</Button>
+      </Drawer>
+    </>
+  );
+}
+
+const gatilho = () => screen.getByRole("button", { name: "Abrir" });
+
+describe("Drawer · abrir e fechar", () => {
+  it("abre pelo gatilho e fecha no Escape, devolvendo o foco", async () => {
+    const usuario = userEvent.setup();
+    render(<ComGatilho />);
+
+    await usuario.click(gatilho());
+    await waitFor(() =>
+      expect(screen.getByRole("dialog", { name: "Detalhes" })).toBeInTheDocument(),
+    );
+
+    await usuario.keyboard("{Escape}");
+    await waitFor(() =>
+      expect(screen.queryByRole("dialog")).not.toBeInTheDocument(),
+    );
+    expect(gatilho()).toHaveFocus();
+  });
+
+  it("o botão de fechar aciona onClose", async () => {
+    const usuario = userEvent.setup();
+    const aoFechar = vi.fn();
+    render(
+      <Drawer open title="Detalhes" onClose={aoFechar}>
+        <p>corpo</p>
+      </Drawer>,
+    );
+    await usuario.click(screen.getByRole("button", { name: "Fechar" }));
+    expect(aoFechar).toHaveBeenCalled();
+  });
+
+  it("closeOnEsc={false} não fecha no Escape", async () => {
+    const usuario = userEvent.setup();
+    const aoFechar = vi.fn();
+    render(
+      <Drawer open title="Detalhes" closeOnEsc={false} onClose={aoFechar}>
+        <p>corpo</p>
+      </Drawer>,
+    );
+    await usuario.keyboard("{Escape}");
+    expect(aoFechar).not.toHaveBeenCalled();
+  });
+
+  /**
+   * `closable` ausente precisa valer `true`. No Vue este é o caso que some,
+   * porque prop booleana ausente vira `false` e `!== false` nasce falso — por
+   * isso as booleanas do componente são tipadas `any`.
+   */
+  it("sem a prop, o botão de fechar existe; com closable={false}, não", () => {
+    const { rerender } = render(
+      <Drawer open title="Detalhes">
+        <p>corpo</p>
+      </Drawer>,
+    );
+    expect(screen.getByRole("button", { name: "Fechar" })).toBeInTheDocument();
+
+    rerender(
+      <Drawer open title="Detalhes" closable={false}>
+        <p>corpo</p>
+      </Drawer>,
+    );
+    expect(
+      screen.queryByRole("button", { name: "Fechar" }),
+    ).not.toBeInTheDocument();
+  });
+});
+
+describe("Drawer · foco", () => {
+  /**
+   * `{aberto && <Drawer open …/>}` é o consumo mais comum, e ali o componente
+   * inteiro desmonta com o painel aberto: o ramo de fechamento do
+   * `syncOpenState` nunca roda, e sem a devolução no `onUnMount` o foco cai no
+   * `<body>`.
+   */
+  it("desmontar com o painel aberto ainda devolve o foco ao gatilho", async () => {
+    const usuario = userEvent.setup();
+
+    function ComMontagemCondicional() {
+      const [aberto, setAberto] = useState(false);
+      return (
+        <>
+          <Button variant="primary" onClick={() => setAberto(true)}>
+            Abrir
+          </Button>
+          {aberto && (
+            <Drawer open title="Detalhes" onClose={() => setAberto(false)}>
+              <Button variant="secondary">Dentro</Button>
+            </Drawer>
+          )}
+        </>
+      );
+    }
+
+    render(<ComMontagemCondicional />);
+    await usuario.click(gatilho());
+    await waitFor(() => expect(screen.getByRole("dialog")).toBeInTheDocument());
+
+    await usuario.click(screen.getByRole("button", { name: "Fechar" }));
+    await waitFor(() =>
+      expect(screen.queryByRole("dialog")).not.toBeInTheDocument(),
+    );
+    expect(gatilho()).toHaveFocus();
+  });
+
+  it("o foco entra no painel ao abrir", async () => {
+    const usuario = userEvent.setup();
+    render(<ComGatilho />);
+    await usuario.click(gatilho());
+    await waitFor(() => expect(screen.getByRole("dialog")).toHaveFocus());
+  });
+
+  it("o Tab circula dentro do painel e não vaza para a página", async () => {
+    const usuario = userEvent.setup();
+    render(<ComGatilho />);
+    await usuario.click(gatilho());
+    await waitFor(() => expect(screen.getByRole("dialog")).toBeInTheDocument());
+
+    const dentro = screen.getAllByRole("button");
+    const ultimo = dentro[dentro.length - 1];
+    ultimo.focus();
+
+    await usuario.tab();
+    // Circulou: o foco continua dentro do painel, nunca no gatilho de fora.
+    expect(screen.getByRole("dialog").contains(document.activeElement)).toBe(
+      true,
+    );
+    expect(gatilho()).not.toHaveFocus();
+  });
+});
+
+describe("Drawer · nome acessível", () => {
+  it("com título, o nome é o título", () => {
+    render(
+      <Drawer open title="Detalhes do processo">
+        <p>corpo</p>
+      </Drawer>,
+    );
+    expect(
+      screen.getByRole("dialog", { name: "Detalhes do processo" }),
+    ).toBeInTheDocument();
+  });
+
+  it("sem título, o nome é o ariaLabel", () => {
+    render(
+      <Drawer open ariaLabel="Prévia do documento">
+        <p>corpo</p>
+      </Drawer>,
+    );
+    expect(
+      screen.getByRole("dialog", { name: "Prévia do documento" }),
+    ).toBeInTheDocument();
+  });
+
+  /** Diálogo anônimo é reprovação direta do axe (aria-dialog-name). */
+  it("sem título e sem ariaLabel, ainda assim tem nome", () => {
+    render(
+      <Drawer open closable={false}>
+        <p>corpo</p>
+      </Drawer>,
+    );
+    expect(screen.getByRole("dialog")).toHaveAccessibleName();
+  });
+});
+
+describe("Drawer · semântica", () => {
+  it("o título é h2, não h6 — não salta nível de cabeçalho", () => {
+    render(
+      <Drawer open title="Detalhes">
+        <p>corpo</p>
+      </Drawer>,
+    );
+    const titulo = screen.getByRole("heading", { name: "Detalhes" });
+    expect(titulo.tagName).toBe("H2");
+  });
+
+  it("o lado vira classe na raiz", () => {
+    const { container } = render(
+      <Drawer open side="left" title="X">
+        <p>corpo</p>
+      </Drawer>,
+    );
+    expect(
+      container.querySelector(".umds-drawer-root--left"),
+    ).toBeInTheDocument();
+  });
+});
+
+describe("Drawer · modo contido", () => {
+  /**
+   * `inline` existe para a página de catálogo: sem ele, cada story vira um
+   * overlay `position: fixed` sobre a viewport inteira, e várias na mesma
+   * página se empilham — o catálogo do Drawer estava assim.
+   */
+  it("inline troca a raiz de overlay por contida", () => {
+    const { container, rerender } = render(
+      <Drawer open title="X">
+        <p>corpo</p>
+      </Drawer>,
+    );
+    expect(container.querySelector(".umds-drawer-root")).toBeInTheDocument();
+    expect(
+      container.querySelector(".umds-drawer-root--inline"),
+    ).not.toBeInTheDocument();
+
+    rerender(
+      <Drawer open inline title="X">
+        <p>corpo</p>
+      </Drawer>,
+    );
+    expect(
+      container.querySelector(".umds-drawer-root--inline"),
+    ).toBeInTheDocument();
+  });
+
+  it("contido ou não, continua sendo um diálogo nomeado", () => {
+    render(
+      <Drawer open inline title="Detalhes">
+        <p>corpo</p>
+      </Drawer>,
+    );
+    expect(
+      screen.getByRole("dialog", { name: "Detalhes" }),
+    ).toBeInTheDocument();
+  });
+});

package/src/teste/Dropdown.test.tsx

@@ -0,0 +1,217 @@
+import { describe, expect, it, vi, beforeAll } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import Dropdown from "../components/Dropdown/Dropdown";
+import Button from "../components/Button/Button";
+
+/**
+ * O `@floating-ui/dom` observa o tamanho do gatilho para reposicionar o menu.
+ * O jsdom não implementa `ResizeObserver`, e sem este stub o `autoUpdate`
+ * estoura no primeiro `open()` — o teste falharia por falta de ambiente, não
+ * por defeito do componente.
+ */
+beforeAll(() => {
+  if (!(globalThis as any).ResizeObserver) {
+    (globalThis as any).ResizeObserver = class {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    };
+  }
+});
+
+/**
+ * O que estes testes prendem é o contrato de ABERTURA, que foi exatamente o
+ * que quebrou no Vue: o Dropdown sem `open` é NÃO-CONTROLADO, e abrir tem de
+ * ser um estado estável — não um menu que aparece e some no update seguinte.
+ *
+ * O defeito original só se manifesta no Vue (lá a prop booleana ausente chega
+ * como `false`, o componente se acha controlado e o `syncOpenState` o fecha no
+ * mesmo flush). Em React não dá para reproduzir. O que dá, e é o que importa,
+ * é prender os dois lados que a correção mexeu — não-controlado e controlado —
+ * para que a próxima mudança em `isOpen`/`syncOpenState` não os troque de
+ * novo. Ver `.agent/troubleshooting/vue-boolean-prop-default.md`.
+ */
+
+const ITENS = [
+  { key: "editar", label: "Editar" },
+  { key: "duplicar", label: "Duplicar" },
+  { key: "excluir", label: "Excluir", danger: true },
+];
+
+const menu = (extra?: Record<string, any>) => (
+  <Dropdown items={ITENS} ariaLabel="Ações do processo" {...extra}>
+    <Button variant="secondary">Abrir</Button>
+  </Dropdown>
+);
+
+const gatilho = () => screen.getByRole("button", { name: "Abrir" });
+
+/**
+ * O menu só trata Esc/setas quando o foco já está DENTRO dele — quem escuta é o
+ * `onKeyDown` do `<ul>`. E esse foco só migra depois que o painel é posicionado,
+ * dois `requestAnimationFrame` adiante. Mandar tecla assim que o `<ul>` aparece
+ * no DOM é corrida: passava no Windows e falhava no runner Linux do CI, onde os
+ * frames caem em outro ritmo. Esperar o foco entrar torna o teste determinístico
+ * e, de quebra, prende o contrato — menu que abre sem receber foco é menu que
+ * não responde ao teclado.
+ */
+const esperarMenuComFoco = async () => {
+  await waitFor(() => {
+    const menuAberto = screen.getByRole("menu");
+    expect(menuAberto.contains(document.activeElement)).toBe(true);
+  });
+};
+
+describe("Dropdown · modo não-controlado", () => {
+  /**
+   * O caso do bug: sem `open`, o clique no gatilho abre o menu e ele FICA
+   * aberto. No Vue, `isControlled` nascia verdadeiro e o menu fechava sozinho.
+   */
+  it("o clique no gatilho abre o menu, e ele continua aberto", async () => {
+    const usuario = userEvent.setup();
+    render(menu());
+
+    expect(screen.queryByRole("menu")).not.toBeInTheDocument();
+
+    await usuario.click(gatilho());
+    await waitFor(() =>
+      expect(
+        screen.getByRole("menu", { name: "Ações do processo" }),
+      ).toBeInTheDocument(),
+    );
+
+    // Um re-render a mais não pode fechar o que o usuário acabou de abrir:
+    // era aqui que o `syncOpenState` derrubava o menu no Vue.
+    await usuario.hover(gatilho());
+    expect(screen.getByRole("menu")).toBeInTheDocument();
+    expect(screen.getAllByRole("menuitem")).toHaveLength(3);
+  });
+
+  it("o segundo clique no gatilho fecha", async () => {
+    const usuario = userEvent.setup();
+    render(menu());
+
+    await usuario.click(gatilho());
+    await waitFor(() => expect(screen.getByRole("menu")).toBeInTheDocument());
+
+    await usuario.click(gatilho());
+    await waitFor(() =>
+      expect(screen.queryByRole("menu")).not.toBeInTheDocument(),
+    );
+  });
+
+  it("o Escape fecha e devolve o foco ao gatilho", async () => {
+    const usuario = userEvent.setup();
+    render(menu());
+
+    await usuario.click(gatilho());
+    await esperarMenuComFoco();
+
+    await usuario.keyboard("{Escape}");
+    await waitFor(() =>
+      expect(screen.queryByRole("menu")).not.toBeInTheDocument(),
+    );
+    expect(gatilho()).toHaveFocus();
+  });
+
+  it("selecionar um item avisa o pai e fecha o menu", async () => {
+    const usuario = userEvent.setup();
+    const aoSelecionar = vi.fn();
+    render(menu({ onSelect: aoSelecionar }));
+
+    await usuario.click(gatilho());
+    await waitFor(() => expect(screen.getByRole("menu")).toBeInTheDocument());
+
+    await usuario.click(screen.getByRole("menuitem", { name: "Duplicar" }));
+    expect(aoSelecionar).toHaveBeenCalledWith(
+      expect.objectContaining({ key: "duplicar" }),
+    );
+    await waitFor(() =>
+      expect(screen.queryByRole("menu")).not.toBeInTheDocument(),
+    );
+  });
+
+  it("avisa o pai quando abre e quando fecha", async () => {
+    const usuario = userEvent.setup();
+    const aoMudar = vi.fn();
+    render(menu({ onOpenChange: aoMudar }));
+
+    await usuario.click(gatilho());
+    await waitFor(() => expect(aoMudar).toHaveBeenCalledWith(true));
+
+    // O `onOpenChange(true)` dispara dentro do `open()`, ANTES de o foco migrar
+    // para o menu — esperar só por ele deixaria a corrida de pé.
+    await esperarMenuComFoco();
+    await usuario.keyboard("{Escape}");
+    await waitFor(() => expect(aoMudar).toHaveBeenLastCalledWith(false));
+  });
+});
+
+describe("Dropdown · semântica do gatilho", () => {
+  /**
+   * `aria-haspopup` e `aria-expanded` não são atributos globais: num `<span>`
+   * de role genérico o axe reprova, e quem recebe o foco é o botão de dentro —
+   * que nunca anunciaria o estado. Antes desta correção o Dropdown com um
+   * `Button` no slot não tinha NENHUM dos dois, em lugar nenhum.
+   */
+  it("os atributos de estado ficam no botão, não no wrapper", async () => {
+    const usuario = userEvent.setup();
+    const { container } = render(menu());
+
+    const wrapper = container.querySelector(".umds-dropdown__trigger")!;
+    expect(wrapper.hasAttribute("aria-haspopup")).toBe(false);
+    expect(wrapper.hasAttribute("aria-expanded")).toBe(false);
+
+    await waitFor(() =>
+      expect(gatilho()).toHaveAttribute("aria-haspopup", "menu"),
+    );
+    expect(gatilho()).toHaveAttribute("aria-expanded", "false");
+
+    await usuario.click(gatilho());
+    await waitFor(() =>
+      expect(gatilho()).toHaveAttribute("aria-expanded", "true"),
+    );
+
+    await esperarMenuComFoco();
+    await usuario.keyboard("{Escape}");
+    await waitFor(() =>
+      expect(gatilho()).toHaveAttribute("aria-expanded", "false"),
+    );
+  });
+});
+
+describe("Dropdown · modo controlado", () => {
+  it("nasce aberto quando o pai manda", async () => {
+    render(menu({ open: true }));
+    await waitFor(() =>
+      expect(
+        screen.getByRole("menu", { name: "Ações do processo" }),
+      ).toBeInTheDocument(),
+    );
+  });
+
+  it("o painel segue a prop do pai", async () => {
+    const { rerender } = render(menu({ open: false }));
+    expect(screen.queryByRole("menu")).not.toBeInTheDocument();
+
+    rerender(menu({ open: true }));
+    await waitFor(() => expect(screen.getByRole("menu")).toBeInTheDocument());
+
+    rerender(menu({ open: false }));
+    await waitFor(() =>
+      expect(screen.queryByRole("menu")).not.toBeInTheDocument(),
+    );
+  });
+
+  /**
+   * `open` é tipada `any` de propósito, para escapar do cast de booleano do
+   * Vue — e o preço disso é que `<Dropdown open>` num template Vue entrega a
+   * string vazia, que é falsy. Este teste prende o tratamento do `""`, que
+   * roda no gerado dos dois frameworks.
+   */
+  it('`open=""` (atributo sem valor no Vue) abre o menu', async () => {
+    render(menu({ open: "" }));
+    await waitFor(() => expect(screen.getByRole("menu")).toBeInTheDocument());
+  });
+});

package/src/teste/Input.test.tsx

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import Input from "../components/Input/Input";
+
+/**
+ * O campo numérico do 1DS. Não virou componente próprio: o produto usa
+ * `<Input type="number" min max>` em três telas — paginação, ano da busca e
+ * tamanho de arquivo — e em todas elas escondia o botão nativo de girar à mão,
+ * no CSS da tela. Um `NumberInput` com +/− seria inventar o que o produto
+ * rejeitou; o que faltava eram os limites e a supressão do girador.
+ *
+ * O que estes testes guardam é justamente isso: que `min`/`max`/`step` chegam
+ * ao DOM (é o navegador quem valida, não nós) e que o girador vem escondido
+ * por padrão.
+ */
+
+describe("Input · numérico", () => {
+  it("min, max e step chegam ao input nativo", () => {
+    render(
+      <Input label="Página" type="number" min={1} max={99} step={1} />,
+    );
+    const campo = screen.getByLabelText("Página");
+    expect(campo).toHaveAttribute("type", "number");
+    expect(campo).toHaveAttribute("min", "1");
+    expect(campo).toHaveAttribute("max", "99");
+    expect(campo).toHaveAttribute("step", "1");
+  });
+
+  it("sem as props, nenhum limite é imposto", () => {
+    render(<Input label="Livre" type="number" />);
+    const campo = screen.getByLabelText("Livre");
+    expect(campo).not.toHaveAttribute("min");
+    expect(campo).not.toHaveAttribute("max");
+    expect(campo).not.toHaveAttribute("step");
+  });
+
+  /**
+   * A supressão do girador é CSS, e CSS não é testável aqui. O que dá para
+   * guardar é o gancho que o CSS usa: sem `numberSpinner` a classe NÃO está
+   * no wrapper, e é a ausência dela que esconde o botão.
+   */
+  it("o girador nativo vem escondido por padrão", () => {
+    const { container } = render(<Input label="Página" type="number" />);
+    expect(
+      container.querySelector(".umds-input--number-spinner"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("numberSpinner devolve o comportamento cru do browser", () => {
+    const { container } = render(
+      <Input label="Página" type="number" numberSpinner />,
+    );
+    expect(
+      container.querySelector(".umds-input--number-spinner"),
+    ).toBeInTheDocument();
+  });
+
+  it("os limites não aparecem em campo de texto", () => {
+    render(<Input label="Nome" type="text" />);
+    const campo = screen.getByLabelText("Nome");
+    expect(campo).toHaveAttribute("type", "text");
+    expect(campo).not.toHaveAttribute("min");
+  });
+});