@1doc/1ds-react 2.11.1 → 2.12.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @1doc/1ds-react
 
+## 2.12.0
+
+### Minor Changes
+
+- d03c66d: Timeline: estado vazio dentro do componente, como o List. `isEmpty`, `emptyTitle`, `emptyDescription`, `emptyIcon`, `emptySize`, `emptyActionLabel` com `onEmptyAction` e o slot `empty` (no React, a prop `empty`) trocam só a trilha por um `EmptyState` com `role="status"`, sem desmontar o que está em volta. Sem `isEmpty`, `items` vazio mostra o vazio quando há `emptyTitle` ou o slot; sem nenhum dos dois, a trilha vazia segue como antes. No Vue, `isEmpty` ausente agora chega como `undefined` (e não `false`), para distinguir "não passou" de "passou false".
+
 ## 2.11.1
 
 ### Patch Changes

package/dist/components/Timeline/Timeline.css

@@ -214,3 +214,11 @@
 .umds-timeline--sm.umds-timeline--card .umds-timeline__body {
   padding: var(--umds-primitive-spacing-mini); /* 12px */
 }
+
+/* ── Estado vazio ──
+   O miolo da trilha troca de conteúdo; quem rodeia não muda. O EmptyState já
+   tem o próprio respiro e alinhamento, o wrapper só dá o lugar. */
+.umds-timeline-empty {
+  display: block;
+  font-family: var(--umds-semantic-font-family-base);
+}

package/dist/components/Timeline/Timeline.d.ts

@@ -35,20 +35,56 @@ export interface TimelineItem {
  * Extraída do histórico de versões do processo e da timeline de despachos da
  * 1Doc.
  *
+ * Sem eventos, a trilha troca por um estado vazio dentro do próprio componente:
+ * um `EmptyState` (`emptyTitle`, `emptyDescription`, `emptyIcon`,
+ * `emptyActionLabel` com `onEmptyAction`) ou, para um conteúdo próprio, o slot
+ * `empty` (no React, a prop `empty` recebe o nó). Só o miolo troca: o título do
+ * cartão, os filtros e o que mais estiver ao redor continuam montados, e o
+ * vazio é anunciado ao leitor de tela (`role="status"`). Passe `isEmpty` quando
+ * a decisão for sua (`:is-empty="!eventos.length"`); sem ele, `items` vazio já
+ * mostra o vazio, desde que haja `emptyTitle` ou o slot. Sem nenhum dos dois,
+ * `items` vazio rende a trilha sem eventos, como sempre.
+ *
  * @property {TimelineItem[]} items - Eventos, na ordem em que devem aparecer.
  * @property {boolean} card - Envolve o conteúdo de cada evento num card branco bordered.
  * @property {string} size - Tamanho do marcador e do texto: 'sm' | 'md'.
  * @property {string} ariaLabel - Nome acessível da lista. Padrão: "Linha do tempo".
+ * @property {boolean} isEmpty - Decide o estado vazio: `true` mostra o vazio no lugar da trilha, `false` mantém a trilha. Sem ele, o vazio aparece quando `items` está vazio e há `emptyTitle` ou o slot `empty`.
+ * @property {string} emptyTitle - Título do estado vazio (padrão: "Nenhum evento registrado")
+ * @property {string} emptyDescription - Texto de apoio do estado vazio
+ * @property {IconProp} emptyIcon - Ícone do estado vazio (objeto do Font Awesome)
+ * @property {string} emptySize - Tamanho do estado vazio: 'sm' (padrão, compacto) | 'md' | 'lg'
+ * @property {string} emptyActionLabel - Rótulo do botão do estado vazio (junto de onEmptyAction)
+ * @property {function} onEmptyAction - Callback do botão do estado vazio
+ * @property {any} empty - Slot `empty`: conteúdo próprio no lugar do EmptyState (React node ou Vue slot)
  * @property {string} className - Classes CSS adicionais.
- * @quandoUsar Mostrar o que aconteceu e quando — auditoria, histórico de versões, despachos de um processo.
- * @quandoNaoUsar Para um processo com etapas futuras e progresso, use `Stepper`. Para uma lista sem eixo de tempo, use `List` ou `Card`.
+ * @slot empty - Conteúdo do estado vazio (substitui o EmptyState padrão).
+ * @quandoUsar Mostrar o que aconteceu e quando — auditoria, histórico de versões, despachos de um processo — inclusive quando ainda não aconteceu nada: o "nenhum despacho registrado" fica no componente, sem `v-if` por fora.
+ * @quandoNaoUsar Para um processo com etapas futuras e progresso, use `Stepper`. Para uma lista sem eixo de tempo, use `List` ou `Card`. Para um vazio que ocupa a tela inteira (sem trilha), use `EmptyState` direto.
  */
 export interface TimelineProps {
     items: TimelineItem[];
     card?: boolean;
     size?: "sm" | "md";
     ariaLabel?: string;
+    /** Decide o estado vazio. Sem ele, vale `items` vazio com `emptyTitle` ou slot. */
+    isEmpty?: boolean;
+    /** Título do estado vazio. @default 'Nenhum evento registrado' */
+    emptyTitle?: string;
+    /** Texto de apoio do estado vazio. */
+    emptyDescription?: string;
+    /** Ícone do estado vazio: o objeto importado do Font Awesome. */
+    emptyIcon?: IconProp;
+    /** Tamanho do estado vazio. @default 'sm' */
+    emptySize?: "sm" | "md" | "lg";
+    /** Rótulo do botão do estado vazio (exibido junto de `onEmptyAction`). */
+    emptyActionLabel?: string;
+    /** Chamado no botão do estado vazio. */
+    onEmptyAction?: () => void;
+    /** Conteúdo próprio do estado vazio. No Vue, slot `empty`. */
+    empty?: any;
     className?: string;
 }
+import type { IconProp } from "../Icon/Icon";
 declare function Timeline(props: TimelineProps): import("react/jsx-runtime").JSX.Element;
 export default Timeline;

package/dist/components/Timeline/Timeline.js

@@ -1,8 +1,36 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import './Timeline.css';
 import Text from "../Text/Text";
 import Icon from "../Icon/Icon";
+import EmptyState from "../EmptyState/EmptyState";
 function Timeline(props) {
+    function showEmpty() {
+        if (props.isEmpty !== undefined && props.isEmpty !== null) {
+            return !!props.isEmpty;
+        }
+        const semEventos = !props.items || props.items.length === 0;
+        return semEventos && !!(props.emptyTitle || props.empty);
+    }
+    function showItems() {
+        return !showEmpty();
+    }
+    function classesDoVazio() {
+        return ["umds-timeline-empty", props.className].filter(Boolean).join(" ");
+    }
+    function emptyTitleText() {
+        return props.emptyTitle || "Nenhum evento registrado";
+    }
+    function emptyActionProps() {
+        if (!props.onEmptyAction)
+            return {};
+        return {
+            actionLabel: props.emptyActionLabel,
+            onAction: props.onEmptyAction,
+        };
+    }
+    function emptySizeValue() {
+        return props.emptySize || "sm";
+    }
     function classesDaLista() {
         return [
             "umds-timeline",
@@ -36,6 +64,6 @@ function Timeline(props) {
     function temCabecalho(item) {
         return !!(item.title || item.timestamp || item.actor);
     }
-    return (_jsx("ol", { role: "list", "aria-label": props.ariaLabel || "Linha do tempo", className: classesDaLista(), children: props.items?.map((item, index) => (_jsxs("li", { "aria-current": item.current ? "true" : undefined, className: classesDoItem(item), children: [_jsxs("div", { "aria-hidden": "true", className: "umds-timeline__rail", children: [_jsx("span", { className: classesDoMarcador(item), children: item.icon ? _jsx(Icon, { size: "sm", icon: item.icon }) : null }), !ehUltimo(index) ? (_jsx("span", { className: "umds-timeline__connector" })) : null] }), _jsxs("div", { className: "umds-timeline__body", children: [temCabecalho(item) ? (_jsxs("div", { className: "umds-timeline__header", children: [item.title ? (_jsx(Text, { as: "span", variant: "body2", weight: "semibold", children: item.title })) : null, item.timestamp ? (_jsx(Text, { as: "span", variant: "caption", color: "secondary", children: item.timestamp })) : null, item.actor ? (_jsx(Text, { as: "span", variant: "caption", color: "secondary", children: item.actor })) : null] })) : null, item.description ? (_jsx(Text, { as: "p", variant: "body2", color: "secondary", children: item.description })) : null] })] }, index))) }));
+    return (_jsxs(_Fragment, { children: [showEmpty() ? (_jsx("div", { role: "status", className: classesDoVazio(), children: _jsx(_Fragment, { children: props.empty || (_jsx(EmptyState, { icon: props.emptyIcon, title: emptyTitleText(), description: props.emptyDescription, size: emptySizeValue(), ...emptyActionProps() })) }) })) : null, showItems() ? (_jsx("ol", { role: "list", "aria-label": props.ariaLabel || "Linha do tempo", className: classesDaLista(), children: props.items?.map((item, index) => (_jsxs("li", { "aria-current": item.current ? "true" : undefined, className: classesDoItem(item), children: [_jsxs("div", { "aria-hidden": "true", className: "umds-timeline__rail", children: [_jsx("span", { className: classesDoMarcador(item), children: item.icon ? _jsx(Icon, { size: "sm", icon: item.icon }) : null }), !ehUltimo(index) ? (_jsx("span", { className: "umds-timeline__connector" })) : null] }), _jsxs("div", { className: "umds-timeline__body", children: [temCabecalho(item) ? (_jsxs("div", { className: "umds-timeline__header", children: [item.title ? (_jsx(Text, { as: "span", variant: "body2", weight: "semibold", children: item.title })) : null, item.timestamp ? (_jsx(Text, { as: "span", variant: "caption", color: "secondary", children: item.timestamp })) : null, item.actor ? (_jsx(Text, { as: "span", variant: "caption", color: "secondary", children: item.actor })) : null] })) : null, item.description ? (_jsx(Text, { as: "p", variant: "body2", color: "secondary", children: item.description })) : null] })] }, index))) })) : null] }));
 }
 export default Timeline;

package/dist/teste/Timeline.test.js

@@ -1,6 +1,7 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { describe, expect, it } from "vitest";
-import { render, screen } from "@testing-library/react";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 import { faCheck } from "@fortawesome/free-solid-svg-icons";
 import Timeline from "../components/Timeline/Timeline";
 /**
@@ -71,3 +72,72 @@ describe("Timeline · conteúdo", () => {
         expect(screen.getByRole("list", { name: "Despachos do processo" })).toBeInTheDocument();
     });
 });
+describe("Timeline · estado vazio", () => {
+    it("isEmpty troca a trilha pelo vazio, com role status e o título padrão", () => {
+        const { container } = render(_jsx(Timeline, { items: EVENTOS, isEmpty: true }));
+        expect(screen.getByRole("status")).toBeInTheDocument();
+        expect(screen.getByText("Nenhum evento registrado")).toBeInTheDocument();
+        expect(screen.queryByRole("list")).toBeNull();
+        expect(screen.queryAllByRole("listitem")).toHaveLength(0);
+        expect(container.querySelector(".umds-timeline__marker")).toBeNull();
+    });
+    it("título, descrição e ícone do vazio vêm das props", () => {
+        const { container } = render(_jsx(Timeline, { items: [], isEmpty: true, emptyTitle: "Nenhum despacho registrado", emptyDescription: "O hist\u00F3rico aparece aqui.", emptyIcon: faCheck }));
+        expect(screen.getByText("Nenhum despacho registrado")).toBeInTheDocument();
+        expect(screen.getByText("O histórico aparece aqui.")).toBeInTheDocument();
+        expect(container.querySelector(".umds-empty-state svg")).toBeInTheDocument();
+    });
+    it("sem isEmpty, items vazio com emptyTitle mostra o vazio", () => {
+        render(_jsx(Timeline, { items: [], emptyTitle: "Nada por aqui" }));
+        expect(screen.getByRole("status")).toBeInTheDocument();
+        expect(screen.getByText("Nada por aqui")).toBeInTheDocument();
+        expect(screen.queryByRole("list")).toBeNull();
+    });
+    it("sem isEmpty, items vazio com a prop empty (slot) mostra o conteúdo próprio", () => {
+        render(_jsx(Timeline, { items: [], empty: _jsx("span", { "data-testid": "proprio", children: "Sem despachos" }) }));
+        expect(screen.getByRole("status")).toContainElement(screen.getByTestId("proprio"));
+        // o EmptyState padrão não entra: o conteúdo próprio o substitui
+        expect(screen.queryByText("Nenhum evento registrado")).toBeNull();
+    });
+    it("sem isEmpty e sem emptyTitle nem slot, items vazio segue sendo a trilha vazia", () => {
+        render(_jsx(Timeline, { items: [] }));
+        expect(screen.queryByRole("status")).toBeNull();
+        expect(screen.getByRole("list")).toBeInTheDocument();
+    });
+    it("isEmpty false manda: items vazio com emptyTitle mantém a trilha", () => {
+        render(_jsx(Timeline, { items: [], isEmpty: false, emptyTitle: "Nada por aqui" }));
+        expect(screen.queryByRole("status")).toBeNull();
+        expect(screen.getByRole("list")).toBeInTheDocument();
+    });
+    it("items com eventos e emptyTitle, sem isEmpty, mostra a trilha", () => {
+        render(_jsx(Timeline, { items: EVENTOS, emptyTitle: "Nada por aqui" }));
+        expect(screen.queryByRole("status")).toBeNull();
+        expect(screen.getAllByRole("listitem")).toHaveLength(3);
+    });
+    it("o botão do vazio só aparece com rótulo e callback, e chama o callback", async () => {
+        const usuario = userEvent.setup();
+        const aoAgir = vi.fn();
+        const { rerender } = render(_jsx(Timeline, { items: [], isEmpty: true, emptyActionLabel: "Limpar filtro" }));
+        expect(screen.queryByRole("button")).toBeNull();
+        rerender(_jsx(Timeline, { items: [], isEmpty: true, emptyActionLabel: "Limpar filtro", onEmptyAction: aoAgir }));
+        await usuario.click(screen.getByRole("button", { name: "Limpar filtro" }));
+        expect(aoAgir).toHaveBeenCalledTimes(1);
+    });
+    it("o entorno não desmonta: só o miolo troca ao esvaziar e ao voltar", async () => {
+        const { rerender } = render(_jsxs("section", { children: [_jsx("h3", { "data-testid": "titulo", children: "Hist\u00F3rico" }), _jsx(Timeline, { items: EVENTOS, isEmpty: false, emptyTitle: "Sem eventos" })] }));
+        const titulo = screen.getByTestId("titulo");
+        expect(screen.getAllByRole("listitem")).toHaveLength(3);
+        rerender(_jsxs("section", { children: [_jsx("h3", { "data-testid": "titulo", children: "Hist\u00F3rico" }), _jsx(Timeline, { items: [], isEmpty: true, emptyTitle: "Sem eventos" })] }));
+        await waitFor(() => expect(screen.getByRole("status")).toBeInTheDocument());
+        expect(screen.getByTestId("titulo")).toBe(titulo);
+        expect(screen.queryByRole("list")).toBeNull();
+        rerender(_jsxs("section", { children: [_jsx("h3", { "data-testid": "titulo", children: "Hist\u00F3rico" }), _jsx(Timeline, { items: EVENTOS, isEmpty: false, emptyTitle: "Sem eventos" })] }));
+        await waitFor(() => expect(screen.getAllByRole("listitem")).toHaveLength(3));
+        expect(screen.getByTestId("titulo")).toBe(titulo);
+        expect(screen.queryByRole("status")).toBeNull();
+    });
+    it("className vai ao wrapper do vazio", () => {
+        render(_jsx(Timeline, { items: [], isEmpty: true, className: "meu-vazio" }));
+        expect(screen.getByRole("status")).toHaveClass("meu-vazio");
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1doc/1ds-react",
-  "version": "2.11.1",
+  "version": "2.12.0",
   "main": "dist/index.js",
   "sideEffects": [
     "**/*.css"
@@ -45,7 +45,7 @@
     "react-dom": "^18.0.0",
     "typescript": "^5.0.0",
     "vitest": "^3.2.7",
-    "@1doc/1ds-core": "2.11.1",
+    "@1doc/1ds-core": "2.12.0",
     "@1doc/1ds-tokens": "0.7.0"
   },
   "publishConfig": {

package/src/teste/Timeline.test.tsx

@@ -1,5 +1,6 @@
-import { describe, expect, it } from "vitest";
-import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 import { faCheck } from "@fortawesome/free-solid-svg-icons";
 import Timeline from "../components/Timeline/Timeline";
 
@@ -98,3 +99,120 @@ describe("Timeline · conteúdo", () => {
     ).toBeInTheDocument();
   });
 });
+
+describe("Timeline · estado vazio", () => {
+  it("isEmpty troca a trilha pelo vazio, com role status e o título padrão", () => {
+    const { container } = render(<Timeline items={EVENTOS} isEmpty />);
+    expect(screen.getByRole("status")).toBeInTheDocument();
+    expect(screen.getByText("Nenhum evento registrado")).toBeInTheDocument();
+    expect(screen.queryByRole("list")).toBeNull();
+    expect(screen.queryAllByRole("listitem")).toHaveLength(0);
+    expect(container.querySelector(".umds-timeline__marker")).toBeNull();
+  });
+
+  it("título, descrição e ícone do vazio vêm das props", () => {
+    const { container } = render(
+      <Timeline
+        items={[]}
+        isEmpty
+        emptyTitle="Nenhum despacho registrado"
+        emptyDescription="O histórico aparece aqui."
+        emptyIcon={faCheck}
+      />,
+    );
+    expect(screen.getByText("Nenhum despacho registrado")).toBeInTheDocument();
+    expect(screen.getByText("O histórico aparece aqui.")).toBeInTheDocument();
+    expect(container.querySelector(".umds-empty-state svg")).toBeInTheDocument();
+  });
+
+  it("sem isEmpty, items vazio com emptyTitle mostra o vazio", () => {
+    render(<Timeline items={[]} emptyTitle="Nada por aqui" />);
+    expect(screen.getByRole("status")).toBeInTheDocument();
+    expect(screen.getByText("Nada por aqui")).toBeInTheDocument();
+    expect(screen.queryByRole("list")).toBeNull();
+  });
+
+  it("sem isEmpty, items vazio com a prop empty (slot) mostra o conteúdo próprio", () => {
+    render(
+      <Timeline items={[]} empty={<span data-testid="proprio">Sem despachos</span>} />,
+    );
+    expect(screen.getByRole("status")).toContainElement(
+      screen.getByTestId("proprio"),
+    );
+    // o EmptyState padrão não entra: o conteúdo próprio o substitui
+    expect(screen.queryByText("Nenhum evento registrado")).toBeNull();
+  });
+
+  it("sem isEmpty e sem emptyTitle nem slot, items vazio segue sendo a trilha vazia", () => {
+    render(<Timeline items={[]} />);
+    expect(screen.queryByRole("status")).toBeNull();
+    expect(screen.getByRole("list")).toBeInTheDocument();
+  });
+
+  it("isEmpty false manda: items vazio com emptyTitle mantém a trilha", () => {
+    render(<Timeline items={[]} isEmpty={false} emptyTitle="Nada por aqui" />);
+    expect(screen.queryByRole("status")).toBeNull();
+    expect(screen.getByRole("list")).toBeInTheDocument();
+  });
+
+  it("items com eventos e emptyTitle, sem isEmpty, mostra a trilha", () => {
+    render(<Timeline items={EVENTOS} emptyTitle="Nada por aqui" />);
+    expect(screen.queryByRole("status")).toBeNull();
+    expect(screen.getAllByRole("listitem")).toHaveLength(3);
+  });
+
+  it("o botão do vazio só aparece com rótulo e callback, e chama o callback", async () => {
+    const usuario = userEvent.setup();
+    const aoAgir = vi.fn();
+    const { rerender } = render(
+      <Timeline items={[]} isEmpty emptyActionLabel="Limpar filtro" />,
+    );
+    expect(screen.queryByRole("button")).toBeNull();
+    rerender(
+      <Timeline
+        items={[]}
+        isEmpty
+        emptyActionLabel="Limpar filtro"
+        onEmptyAction={aoAgir}
+      />,
+    );
+    await usuario.click(screen.getByRole("button", { name: "Limpar filtro" }));
+    expect(aoAgir).toHaveBeenCalledTimes(1);
+  });
+
+  it("o entorno não desmonta: só o miolo troca ao esvaziar e ao voltar", async () => {
+    const { rerender } = render(
+      <section>
+        <h3 data-testid="titulo">Histórico</h3>
+        <Timeline items={EVENTOS} isEmpty={false} emptyTitle="Sem eventos" />
+      </section>,
+    );
+    const titulo = screen.getByTestId("titulo");
+    expect(screen.getAllByRole("listitem")).toHaveLength(3);
+
+    rerender(
+      <section>
+        <h3 data-testid="titulo">Histórico</h3>
+        <Timeline items={[]} isEmpty emptyTitle="Sem eventos" />
+      </section>,
+    );
+    await waitFor(() => expect(screen.getByRole("status")).toBeInTheDocument());
+    expect(screen.getByTestId("titulo")).toBe(titulo);
+    expect(screen.queryByRole("list")).toBeNull();
+
+    rerender(
+      <section>
+        <h3 data-testid="titulo">Histórico</h3>
+        <Timeline items={EVENTOS} isEmpty={false} emptyTitle="Sem eventos" />
+      </section>,
+    );
+    await waitFor(() => expect(screen.getAllByRole("listitem")).toHaveLength(3));
+    expect(screen.getByTestId("titulo")).toBe(titulo);
+    expect(screen.queryByRole("status")).toBeNull();
+  });
+
+  it("className vai ao wrapper do vazio", () => {
+    render(<Timeline items={[]} isEmpty className="meu-vazio" />);
+    expect(screen.getByRole("status")).toHaveClass("meu-vazio");
+  });
+});