@12-apps/ui 1.0.0 → 1.3.0

package/src/components/data-display/index.ts

@@ -22,6 +22,7 @@ export * from './Popover';
 export * from './Progress';
 export * from './SectionOnboarding/SectionOnboarding';
 export * from './Sheet';
+export * from './StatCard';
 export * from './Stepper/Stepper';
 export * from './Table';
 export * from './Timeline';

package/src/components/feedback/ConfirmAction/ConfirmAction.hooks.ts

@@ -0,0 +1,96 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { ConfirmHandler, UseConfirmActionResult } from './ConfirmAction.types';
+
+/** Used when the guarded action rejects and the caller supplied no wording. */
+export const DEFAULT_ERROR_TEXT = 'Não foi possível concluir a ação. Tente novamente.';
+
+/**
+ * What the popup says after a failed attempt.
+ *
+ * A rejection carrying a message wins: the server's sentence ("esta categoria
+ * ainda tem produtos vinculados") is the one the operator can act on, and it is
+ * strictly better than the generic fallback. Handlers that have nothing useful
+ * to say reject with nothing and get `errorText`.
+ */
+function failureMessage(cause: unknown, errorText: string): string {
+  if (cause instanceof Error && cause.message) return cause.message;
+  return errorText;
+}
+
+/**
+ * The confirmation state machine, headless.
+ *
+ * It is the whole safety contract in one place, so every consumer gets the same
+ * behaviour: the action runs ONLY from `confirm`, never from opening the popup;
+ * a second confirm while the first is in flight is dropped (a double-click
+ * cannot send two deletes); a rejection keeps the popup open carrying the
+ * failure instead of closing over a write that never happened.
+ */
+export function useConfirmAction(
+  onConfirm: ConfirmHandler,
+  errorText: string = DEFAULT_ERROR_TEXT,
+): UseConfirmActionResult {
+  const [open, setOpen] = useState(false);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // `pending` is mirrored in a ref because the two guards that matter — drop a
+  // second confirm, ignore a cancel mid-flight — are read inside callbacks that
+  // must not be rebuilt on every state change. Reading the state variable there
+  // would leave a stale closure holding `false` for the whole in-flight window,
+  // which is exactly the double-submit this component exists to prevent.
+  const busy = useRef(false);
+
+  // The action can settle after the trigger has unmounted (a row deleted from
+  // under its own menu), so the settle path must not touch state by then.
+  const mounted = useRef(true);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+
+  const request = useCallback((): void => {
+    setError(null);
+    setOpen(true);
+  }, []);
+
+  const cancel = useCallback((): void => {
+    // Inert mid-flight: the write has already left, and closing here would hide
+    // its outcome.
+    if (busy.current) return;
+    setOpen(false);
+    setError(null);
+  }, []);
+
+  const settle = useCallback((failure: string | null): void => {
+    busy.current = false;
+    if (!mounted.current) return;
+    setPending(false);
+    setError(failure);
+    if (!failure) setOpen(false);
+  }, []);
+
+  const confirm = useCallback((): void => {
+    if (busy.current) return;
+    busy.current = true;
+    setPending(true);
+    setError(null);
+    // The handler is invoked synchronously, exactly as a plain `onClick` would
+    // be — only the OUTCOME is awaited. The try/catch is what puts a handler
+    // that throws synchronously on the same failure path as one that returns a
+    // rejected promise.
+    try {
+      const result = onConfirm();
+      void Promise.resolve(result)
+        .then(() => settle(null))
+        .catch((cause: unknown) => settle(failureMessage(cause, errorText)));
+    } catch (cause) {
+      settle(failureMessage(cause, errorText));
+    }
+  }, [errorText, onConfirm, settle]);
+
+  return { open, pending, error, request, cancel, confirm };
+}

package/src/components/feedback/ConfirmAction/ConfirmAction.md

@@ -0,0 +1,140 @@
+# ConfirmAction
+
+The confirmation popup for destructive actions — one implementation, so every
+delete in the product behaves the same way.
+
+It exists because the admin's destructive actions used to fire on a single
+click: picking "Excluir" in a card's 3-dots menu called the endpoint
+immediately, and a mis-tap on a phone destroyed the row. The few screens that
+did confirm had each hand-rolled their own dialog, so the wording, the focus
+order and the double-click behaviour all differed.
+
+## What it guarantees
+
+Whichever of the three entry points you use, you get the same contract:
+
+- **Nothing runs until the operator confirms.** Opening the popup has no side
+  effect; the guarded handler is called from the confirm button and nowhere else.
+- **One write per confirmation.** A returned promise holds the popup in its
+  pending state, and a second confirm during that window is dropped — a
+  double-click cannot send two DELETEs.
+- **A failure stays visible.** If the action rejects, the popup stays open
+  carrying the error instead of closing over a write that never landed, and the
+  operator can retry from there. A rejection with a message shows that message
+  — throw the server's sentence (`throw new Error(result.error)`) and the
+  operator reads what actually blocked the write; `errorText` is the fallback.
+- **The keyboard is safe.** Destructive popups open with focus on *Cancel*, so a
+  stray Enter still on the trigger cannot complete the action. Escape and the
+  backdrop cancel; both are inert while a write is in flight.
+- **The popup names the thing.** `entityName` is echoed into the body, so it
+  reads "Bebidas", not "este item".
+
+## Three entry points
+
+### `withConfirmation(Component, defaults?)` — the HOC
+
+The path of least resistance for an existing button: the wrapped component's own
+`onClick` becomes the guarded action, so the call site keeps its shape.
+
+```tsx
+import { withConfirmation } from '@12-apps/ui/feedback/ConfirmAction';
+import { Button } from '@12-apps/ui/form/Button';
+
+const DeleteButton = withConfirmation(Button, {
+  confirmText: 'Excluir',
+  description: 'Vai para a lixeira e pode ser restaurado de lá.',
+});
+
+<DeleteButton
+  color="danger"
+  onClick={() => deleteCategoryAction({ tenantSlug, id: row.id })}
+  confirm={{ title: 'Excluir a categoria?', entityName: row.name }}
+>
+  Excluir
+</DeleteButton>;
+```
+
+Defaults baked into the wrapper are merged with each instance's `confirm` prop,
+instance wins. `confirm={false}` falls through to the plain component — the
+escape hatch for the same button in a context where the action is harmless.
+
+Refs are not forwarded (the HOC renders trigger + popup as a fragment, so there
+is no single node to hand back). Use `<ConfirmAction>` where a ref is needed.
+
+### `ConfirmButton` — the HOC, pre-applied
+
+`withConfirmation(Button)` with the shared wording already in place. Use it when
+you just want a guarded button and have no reason to build your own wrapper.
+
+```tsx
+import { ConfirmButton } from '@12-apps/ui/feedback/ConfirmAction';
+
+<ConfirmButton
+  color="danger"
+  onClick={remove}
+  confirm={{ title: 'Remover o domínio?', entityName: domain.host, confirmText: 'Remover' }}
+>
+  Remover
+</ConfirmButton>;
+```
+
+### `<ConfirmAction>` — the render prop
+
+For triggers that are not buttons: a dropdown item, a table row action, an icon.
+
+```tsx
+<ConfirmAction
+  title="Excluir a mesa?"
+  entityName={row.label}
+  confirmText="Excluir"
+  onConfirm={() => deleteTableAction({ tenantSlug, id: row.id })}
+>
+  {(request) => <MenuItem onClick={request}>Excluir</MenuItem>}
+</ConfirmAction>
+```
+
+### `useConfirmAction(handler, errorText?)` — headless
+
+The state machine on its own (`open`, `pending`, `error`, `request`, `cancel`,
+`confirm`), for a popup that has to look like something else entirely. Pair it
+with `<ConfirmActionDialog state={…} />` or your own surface.
+
+## Writing the wording
+
+- `title` is the question — "Excluir a categoria?".
+- `confirmText` is the **verb**, never "OK". It is required for that reason: a
+  button reading "Confirmar" tells the operator nothing about what is about to
+  happen.
+- `description` should say whether the action can be undone. A soft delete goes
+  to the recycle bin and comes back; a purge does not. Say which. Without one,
+  the popup falls back to naming the affected row.
+- `typeToConfirm` requires the operator to type an exact string before the
+  confirm enables. Reserve it for actions with **no** recovery path — a
+  permanent purge, suspending a live store. Everywhere else it is friction that
+  buys nothing.
+
+## Props
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `title` | `string` | — | Required. The question. |
+| `confirmText` | `string` | — | Required. The verb on the confirm button. |
+| `description` | `ReactNode` | derived from `entityName` | The consequence. |
+| `entityName` | `string` | — | The row being acted on, echoed into the body. |
+| `cancelText` | `string` | `Cancelar` | |
+| `typeToConfirm` | `string` | — | Gates the confirm until typed exactly. |
+| `typeToConfirmLabel` | `string` | derived | Label above the field. |
+| `tone` | `'destructive' \| 'default'` | `destructive` | Colour + default focus. |
+| `initialFocus` | `'confirm' \| 'cancel'` | `cancel` when destructive | |
+| `errorText` | `string` | generic pt-BR sentence | Shown when the action rejects. |
+| `dataTestId` | `string` | `confirm-action` | The popup's parts derive theirs from it. |
+
+## Test ids
+
+`dataTestId` (default `confirm-action`) is the root; the parts follow
+`AlertDialog`'s convention:
+
+- `confirm-action-confirm-button`
+- `confirm-action-cancel-button`
+- `confirm-action-error`
+- `confirm-action-type-to-confirm` (on the input itself)

package/src/components/feedback/ConfirmAction/ConfirmAction.parts.tsx

@@ -0,0 +1,154 @@
+import { Alert, Stack, TextField, Typography } from '@mui/material';
+import React, { type ReactNode } from 'react';
+
+import { AlertDialog } from '../../data-display/AlertDialog';
+
+import type {
+  ConfirmInitialFocus,
+  ConfirmOptions,
+  ConfirmTone,
+  UseConfirmActionResult,
+} from './ConfirmAction.types';
+
+const DEFAULT_CANCEL_TEXT = 'Cancelar';
+const DEFAULT_TEST_ID = 'confirm-action';
+
+/**
+ * The popup's body: the row being acted on, then what happens to it.
+ *
+ * The NAME is rendered in its own right rather than woven into the sentence, so
+ * it is there whatever the caller wrote — "the popup names the specific entity"
+ * is the one thing that must not depend on each call site remembering to
+ * mention it. A body with neither a name nor a description would leave the
+ * operator with only the title to decide on, so a neutral fallback covers that.
+ */
+function confirmBody(description: ReactNode, entityName?: string): ReactNode {
+  if (!entityName) return description ?? "Esta ação não pode ser desfeita.";
+  return (
+    <>
+      <Typography component="span" sx={{ fontWeight: 600, display: "block" }}>
+        {entityName}
+      </Typography>
+      {description}
+    </>
+  );
+}
+
+/** Destructive dialogs open on Cancel; anything else opens on the confirm. */
+function resolveInitialFocus(
+  tone: ConfirmTone,
+  initialFocus?: ConfirmInitialFocus,
+): ConfirmInitialFocus {
+  if (initialFocus) return initialFocus;
+  return tone === 'destructive' ? 'cancel' : 'confirm';
+}
+
+/**
+ * The type-to-confirm field. Rendered only when `typeToConfirm` is set, which
+ * should be rare: it is the guard for actions with NO recovery path, where a
+ * click is too cheap a gesture. Comparison is exact — trimmed of surrounding
+ * whitespace only, so a trailing space from a paste does not read as a mismatch.
+ */
+function TypeToConfirmField({
+  expected,
+  label,
+  value,
+  onChange,
+  disabled,
+  dataTestId,
+}: {
+  expected: string;
+  label?: string;
+  value: string;
+  onChange: (next: string) => void;
+  disabled: boolean;
+  dataTestId: string;
+}): React.ReactElement {
+  return (
+    <Stack spacing={1} sx={{ mt: 2 }}>
+      <Typography variant="body2" color="text.secondary">
+        {label ?? `Digite "${expected}" para confirmar.`}
+      </Typography>
+      <TextField
+        size="small"
+        value={value}
+        disabled={disabled}
+        onChange={(event) => onChange(event.target.value)}
+        // On the INPUT rather than the wrapper: a test id on MUI's TextField
+        // lands on the outer div, which is not the node a test can type into.
+        inputProps={{
+          'aria-label': label ?? `Digite ${expected} para confirmar`,
+          'data-testid': `${dataTestId}-type-to-confirm`,
+        }}
+      />
+    </Stack>
+  );
+}
+
+export interface ConfirmActionDialogProps extends ConfirmOptions {
+  state: UseConfirmActionResult;
+}
+
+/**
+ * The popup itself: an `AlertDialog` in its destructive skin, plus the two
+ * things a bare AlertDialog has no opinion about — the failure the last attempt
+ * produced (shown IN the dialog, which stays open, rather than closing over a
+ * write that never landed) and the optional type-to-confirm gate.
+ */
+export function ConfirmActionDialog({
+  state,
+  title,
+  description,
+  entityName,
+  confirmText,
+  cancelText = DEFAULT_CANCEL_TEXT,
+  typeToConfirm,
+  typeToConfirmLabel,
+  tone = 'destructive',
+  initialFocus,
+  dataTestId = DEFAULT_TEST_ID,
+}: ConfirmActionDialogProps): React.ReactElement {
+  const [typed, setTyped] = React.useState('');
+
+  // Every fresh open starts from an empty field: carrying the previous answer
+  // over would hand the next delete a pre-satisfied gate.
+  React.useEffect(() => {
+    if (state.open) setTyped('');
+  }, [state.open]);
+
+  const gateUnmet = typeToConfirm !== undefined && typed.trim() !== typeToConfirm;
+
+  return (
+    <AlertDialog
+      open={state.open}
+      variant={tone === 'destructive' ? 'destructive' : 'default'}
+      title={title}
+      description={confirmBody(description, entityName)}
+      confirmText={confirmText}
+      cancelText={cancelText}
+      loading={state.pending}
+      confirmDisabled={gateUnmet}
+      initialFocus={resolveInitialFocus(tone, initialFocus)}
+      onConfirm={state.confirm}
+      onCancel={state.cancel}
+      onClose={state.cancel}
+      data-testid={dataTestId}
+    >
+      {state.error && (
+        <Alert severity="error" sx={{ mt: 1 }} data-testid={`${dataTestId}-error`}>
+          {state.error}
+        </Alert>
+      )}
+      {typeToConfirm !== undefined && (
+        <TypeToConfirmField
+          expected={typeToConfirm}
+          label={typeToConfirmLabel}
+          value={typed}
+          onChange={setTyped}
+          disabled={state.pending}
+          dataTestId={dataTestId}
+        />
+      )}
+    </AlertDialog>
+  );
+}

package/src/components/feedback/ConfirmAction/ConfirmAction.stories.tsx

@@ -0,0 +1,146 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Stack } from '@mui/material';
+
+import { Button } from '../../form/Button';
+
+import { ConfirmAction } from './ConfirmAction';
+import { ConfirmButton } from './ConfirmButton';
+import { withConfirmation } from './with-confirmation';
+
+const meta: Meta<typeof ConfirmAction> = {
+  title: 'Feedback/ConfirmAction',
+  component: ConfirmAction,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Wraps a destructive action in a confirmation popup. The guarded handler runs only after the operator confirms; cancelling sends nothing, an in-flight write cannot be fired twice, and a failure keeps the popup open carrying the error.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    tone: { control: 'inline-radio', options: ['destructive', 'default'] },
+    initialFocus: { control: 'inline-radio', options: ['confirm', 'cancel'] },
+    typeToConfirm: { control: 'text' },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Resolves after a beat, so the popup's pending state is visible in the story. */
+const slowWrite = () => new Promise<void>((resolve) => setTimeout(resolve, 1200));
+
+export const Default: Story = {
+  args: {
+    title: 'Excluir a categoria?',
+    entityName: 'Bebidas',
+    description: 'Ela vai para a lixeira e pode ser restaurada de lá.',
+    confirmText: 'Excluir',
+    onConfirm: slowWrite,
+    children: (request) => (
+      <Button color="danger" onClick={request}>
+        Excluir
+      </Button>
+    ),
+  },
+};
+
+/** No body of its own: the popup falls back to naming the row it affects. */
+export const DescriptionFromEntityName: Story = {
+  args: {
+    ...Default.args,
+    description: undefined,
+  },
+};
+
+/** The non-destructive tone — same machinery, and focus opens on the confirm. */
+export const NeutralTone: Story = {
+  args: {
+    ...Default.args,
+    title: 'Publicar o cardápio?',
+    description: 'As alterações ficam visíveis na vitrine imediatamente.',
+    confirmText: 'Publicar',
+    tone: 'default',
+  },
+};
+
+/** For actions with no recovery path: the confirm stays dead until the name is typed. */
+export const TypeToConfirm: Story = {
+  args: {
+    ...Default.args,
+    title: 'Excluir definitivamente',
+    description: 'Este item e tudo o que depende dele somem para sempre.',
+    confirmText: 'Excluir definitivamente',
+    typeToConfirm: 'Bebidas',
+  },
+};
+
+/** The write rejects: the popup stays open and says so, instead of closing silently. */
+export const FailedWrite: Story = {
+  args: {
+    ...Default.args,
+    onConfirm: () => Promise.reject(new Error('409')),
+    errorText: 'Esta categoria ainda tem produtos vinculados.',
+  },
+};
+
+/** The long label case — a title and body that wrap. */
+export const LongContent: Story = {
+  args: {
+    ...Default.args,
+    title: 'Remover este integrante da equipe e revogar todos os seus acessos?',
+    entityName: 'maria.fernanda.dossantos@exemplo.com.br',
+    description:
+      'A pessoa perde o acesso ao painel imediatamente e precisa de um novo convite para voltar. Os pedidos que ela registrou continuam no histórico da loja, atribuídos ao nome dela.',
+  },
+};
+
+/** The HOC path: an ordinary button, guarded by adding one prop. */
+export const WithConfirmationHoc: StoryObj = {
+  render: () => (
+    <Stack direction="row" spacing={2}>
+      <ConfirmButton
+        color="danger"
+        onClick={slowWrite}
+        confirm={{
+          title: 'Excluir o desconto?',
+          entityName: 'Combo almoço',
+          description: 'O cupom para de valer na vitrine assim que for excluído.',
+          confirmText: 'Excluir',
+        }}
+      >
+        Excluir
+      </ConfirmButton>
+      <ConfirmButton color="neutral" onClick={slowWrite} confirm={false}>
+        Sem confirmação
+      </ConfirmButton>
+    </Stack>
+  ),
+};
+
+/** Wording baked into the wrapper once; each instance only says what differs. */
+const DeleteButton = withConfirmation(Button, {
+  title: 'Excluir o item?',
+  confirmText: 'Excluir',
+  description: 'Ele vai para a lixeira e pode ser restaurado de lá.',
+});
+
+export const HocWithBakedInDefaults: StoryObj = {
+  render: () => (
+    <Stack direction="row" spacing={2}>
+      <DeleteButton color="danger" onClick={slowWrite} confirm={{ entityName: 'Bebidas' }}>
+        Excluir categoria
+      </DeleteButton>
+      <DeleteButton
+        color="danger"
+        onClick={slowWrite}
+        confirm={{ entityName: 'Mesa 12', title: 'Excluir a mesa?' }}
+      >
+        Excluir mesa
+      </DeleteButton>
+    </Stack>
+  ),
+};

package/src/components/feedback/ConfirmAction/ConfirmAction.test.stories.tsx

@@ -0,0 +1,114 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, within } from 'storybook/test';
+
+import { Button } from '../../form/Button';
+
+import { ConfirmAction } from './ConfirmAction';
+import { ConfirmButton } from './ConfirmButton';
+
+const meta: Meta<typeof ConfirmAction> = {
+  title: 'Feedback/ConfirmAction/Tests',
+  component: ConfirmAction,
+  parameters: {
+    layout: 'centered',
+    chromatic: { disableSnapshot: false },
+  },
+  tags: ['autodocs', 'test', 'component:ConfirmAction'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const BASE = {
+  title: 'Excluir a categoria?',
+  description: 'Ela vai para a lixeira e pode ser restaurada de lá.',
+  confirmText: 'Excluir',
+};
+
+/** The popup lives on `document.body`, so queries run against the whole screen. */
+const body = (): ReturnType<typeof within> => within(document.body);
+
+export const OpensWithoutRunningTheAction: Story = {
+  name: '🧪 Trigger opens the popup and runs nothing',
+  args: {
+    ...BASE,
+    onConfirm: fn(),
+    children: (request) => (
+      <Button color="danger" onClick={request}>
+        Excluir
+      </Button>
+    ),
+  },
+  play: async ({ args, canvasElement }) => {
+    await userEvent.click(within(canvasElement).getByRole('button', { name: 'Excluir' }));
+
+    await expect(body().getByText('Excluir a categoria?')).toBeInTheDocument();
+    await expect(args.onConfirm).not.toHaveBeenCalled();
+  },
+};
+
+export const CancelSendsNothing: Story = {
+  name: '🧪 Cancel sends nothing',
+  args: { ...OpensWithoutRunningTheAction.args, onConfirm: fn() },
+  play: async ({ args, canvasElement }) => {
+    await userEvent.click(within(canvasElement).getByRole('button', { name: 'Excluir' }));
+    await userEvent.click(body().getByTestId('confirm-action-cancel-button'));
+
+    await expect(args.onConfirm).not.toHaveBeenCalled();
+  },
+};
+
+export const ConfirmRunsTheAction: Story = {
+  name: '🧪 Confirm runs the action once',
+  args: { ...OpensWithoutRunningTheAction.args, onConfirm: fn() },
+  play: async ({ args, canvasElement }) => {
+    await userEvent.click(within(canvasElement).getByRole('button', { name: 'Excluir' }));
+    await userEvent.click(body().getByTestId('confirm-action-confirm-button'));
+
+    await expect(args.onConfirm).toHaveBeenCalledTimes(1);
+  },
+};
+
+export const TypeToConfirmGate: Story = {
+  name: '🧪 Type-to-confirm gates the confirm button',
+  args: {
+    ...OpensWithoutRunningTheAction.args,
+    onConfirm: fn(),
+    typeToConfirm: 'Bebidas',
+  },
+  play: async ({ canvasElement }) => {
+    await userEvent.click(within(canvasElement).getByRole('button', { name: 'Excluir' }));
+
+    await expect(body().getByTestId('confirm-action-confirm-button')).toBeDisabled();
+    await userEvent.type(body().getByTestId('confirm-action-type-to-confirm'), 'Bebidas');
+    await expect(body().getByTestId('confirm-action-confirm-button')).toBeEnabled();
+  },
+};
+
+export const KeyboardCancelsWithEscape: Story = {
+  name: '🧪 Escape closes without running the action',
+  args: { ...OpensWithoutRunningTheAction.args, onConfirm: fn() },
+  play: async ({ args, canvasElement }) => {
+    await userEvent.click(within(canvasElement).getByRole('button', { name: 'Excluir' }));
+    await userEvent.keyboard('{Escape}');
+
+    await expect(args.onConfirm).not.toHaveBeenCalled();
+  },
+};
+
+export const HocGuardsTheWrappedButton: StoryObj = {
+  name: '🧪 withConfirmation guards the wrapped button',
+  render: (_args, { args }) => (
+    <ConfirmButton color="danger" onClick={args.onClick} confirm={BASE}>
+      Excluir
+    </ConfirmButton>
+  ),
+  args: { onClick: fn() },
+  play: async ({ args, canvasElement }) => {
+    await userEvent.click(within(canvasElement).getByRole('button', { name: 'Excluir' }));
+    await expect(args.onClick).not.toHaveBeenCalled();
+
+    await userEvent.click(body().getByTestId('confirm-action-confirm-button'));
+    await expect(args.onClick).toHaveBeenCalledTimes(1);
+  },
+};