@12-apps/ui 1.5.2 → 1.6.1

package/src/components/data-display/DataViews/data-views-empty.tsx

@@ -0,0 +1,91 @@
+"use client";
+
+import FilterAltOffRoundedIcon from "@mui/icons-material/FilterAltOffRounded";
+import InboxRoundedIcon from "@mui/icons-material/InboxRounded";
+
+import { Button } from "../../form/Button";
+import { Box } from "../../../mui/Box";
+import { Text } from "../../typography/Text";
+
+/**
+ * TWO EMPTY STATES, NOT ONE.
+ *
+ * "Nenhum pagamento registrado" under an active filter is a lie, and it is the
+ * expensive kind: the operator reads it as "this store has no payments" and
+ * goes looking for the bug somewhere else. The page's own empty copy answers
+ * "there is nothing here yet"; it cannot answer "nothing matches what you
+ * typed", because it does not know what was typed.
+ *
+ * So the grid renders the FILTERED variant itself — it is the only party that
+ * knows a filter is applied — and defers to the host's `emptyState` only when
+ * the list is genuinely empty. The filtered one carries the way out, which is
+ * the whole point: the fix is one click, and it is right there.
+ */
+export function DataViewsEmpty({
+  filtered,
+  onClearFilters,
+  emptyState,
+  testIdPrefix,
+}: {
+  /** Is anything narrowing the list right now (search, pills or ranges)? */
+  filtered: boolean;
+  onClearFilters: () => void;
+  /** The page's own copy for a genuinely empty list. */
+  emptyState?: React.ReactNode;
+  testIdPrefix: string;
+}): React.JSX.Element {
+  const Icon = filtered ? FilterAltOffRoundedIcon : InboxRoundedIcon;
+  return (
+    <Box
+      data-testid={`${testIdPrefix}-empty${filtered ? "-filtered" : ""}`}
+      sx={{
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        textAlign: "center",
+        py: 8,
+        px: 2,
+      }}
+    >
+      <Box
+        sx={{
+          display: "inline-flex",
+          p: 2,
+          mb: 1.5,
+          borderRadius: "50%",
+          bgcolor: "action.hover",
+          color: "text.disabled",
+        }}
+      >
+        <Icon />
+      </Box>
+      {filtered ? (
+        <>
+          <Text variant="body" as="p">
+            <Box component="span" sx={{ fontWeight: 600 }}>
+              Nenhum resultado para esses filtros
+            </Box>
+          </Text>
+          <Text variant="caption" as="p">
+            <Box component="span" sx={{ display: "block", mt: 0.5, mb: 2, color: "text.secondary", maxWidth: 380 }}>
+              Ajuste ou remova os filtros.
+            </Box>
+          </Text>
+          <Button
+            variant="outline"
+            size="sm"
+            color="secondary"
+            onClick={onClearFilters}
+            dataTestId={`${testIdPrefix}-empty-clear`}
+          >
+            Limpar filtros
+          </Button>
+        </>
+      ) : (
+        // The page's own words for "nothing here yet" — it knows what the
+        // entity is and how one comes to exist; this component does not.
+        emptyState
+      )}
+    </Box>
+  );
+}

package/src/components/data-display/DataViews/data-views-export.tsx

@@ -0,0 +1,260 @@
+"use client";
+
+import DownloadRoundedIcon from "@mui/icons-material/DownloadRounded";
+import KeyboardArrowDownRoundedIcon from "@mui/icons-material/KeyboardArrowDownRounded";
+import { CircularProgress, Popover } from "@mui/material";
+import { useState } from "react";
+
+import { Button } from "../../form/Button";
+import { Box } from "../../../mui/Box";
+import { Text } from "../../typography/Text";
+
+import type { DataViewQuery } from "./data-views-types";
+
+/**
+ * EXPORT — the current QUERY, never the rendered page.
+ *
+ * Exporting what happens to be on screen is the single most common bug in an
+ * admin table: the operator filtered 214 records, sees 25, exports, and gets
+ * 25 — with nothing anywhere saying so. So this control does not touch the
+ * loaded rows at all. It hands the host the same `DataViewQuery` the grid is
+ * showing, unpaginated, and the HOST re-queries the backend — the same
+ * division as everywhere else here: the component emits, the host fetches.
+ *
+ * The menu states the number it is about to export before the click, so the
+ * two possible answers (the selection, or the whole filtered set) are never a
+ * guess.
+ */
+
+/** What a host can be asked to produce. */
+export type DataViewExportFormat = "xlsx" | "csv" | "json";
+
+/** The request handed to the host when the operator picks a format. */
+export interface DataViewExportRequest {
+  format: DataViewExportFormat;
+  /**
+   * The live query with `page: 1` and `pageSize` set to the whole matched
+   * total — i.e. "everything this filter selects", not this page.
+   */
+  query: DataViewQuery;
+  /**
+   * The selected row ids, when the operator has a selection. The host filters
+   * the re-queried rows to these; absent means the whole filtered set.
+   */
+  selectedIds?: Array<string | number>;
+  /** The visible columns, in the operator's current order. */
+  columns: { id: string; label: string }[];
+}
+
+/** Injected export. Absent ⇒ no Exportar control, exactly like `renderCard`. */
+export interface DataViewExport {
+  /** Runs the export. Awaited, so the trigger can show it is working. */
+  onExport: (request: DataViewExportRequest) => Promise<void> | void;
+  /** Formats to offer, in menu order. Defaults to all three. */
+  formats?: DataViewExportFormat[];
+}
+
+/** One line per format: what it is, and when to reach for it. */
+const FORMAT_COPY: Record<DataViewExportFormat, { label: string; hint: string }> = {
+  xlsx: { label: "Excel (.xlsx)", hint: "Abre direto, com as colunas dimensionadas" },
+  csv: { label: "CSV (.csv)", hint: "Para importar em outro sistema" },
+  json: { label: "JSON (.json)", hint: "Para integrações" },
+};
+
+const ALL_FORMATS: DataViewExportFormat[] = ["xlsx", "csv", "json"];
+
+interface ExportMenuProps {
+  config: DataViewExport;
+  /** The live query — copied and unpaginated before it reaches the host. */
+  query: DataViewQuery;
+  /** The unpaginated total, so the label can state what "tudo" means. */
+  totalCount: number;
+  selectedIds: Array<string | number>;
+  columns: { id: string; label: string }[];
+  testIdPrefix: string;
+  /** Render icon-only (measured upstream). */
+  compact?: boolean;
+}
+
+/** "Exportando 214 itens filtrados" / "3 itens selecionados" — never a guess. */
+function scopeLabel(selected: number, total: number): string {
+  if (selected > 0) {
+    return `${selected} ${selected === 1 ? "item selecionado" : "itens selecionados"}`;
+  }
+  return `${total} ${total === 1 ? "item filtrado" : "itens filtrados"}`;
+}
+
+/** The trigger. Shows a spinner while the host's export is still running. */
+function ExportTrigger({
+  busy,
+  onOpen,
+  testIdPrefix,
+  compact,
+}: {
+  busy: boolean;
+  onOpen: (anchor: HTMLElement) => void;
+  testIdPrefix: string;
+  /** Icon only — step 2 of the toolbar's degradation ladder. */
+  compact?: boolean;
+}): React.JSX.Element {
+  return (
+    <Button
+      variant="outline"
+      size="sm"
+      color="neutral"
+      disabled={busy}
+      onClick={(event) => onOpen(event.currentTarget as HTMLElement)}
+      dataTestId={`${testIdPrefix}-export-trigger`}
+      aria-label="Exportar"
+      // The label is gone, so the tooltip is the only thing naming the control.
+      title={compact ? "Exportar" : undefined}
+    >
+      <Box component="span" sx={{ display: "inline-flex", alignItems: "center", gap: 0.5 }}>
+        {busy ? <CircularProgress size={14} /> : <DownloadRoundedIcon fontSize="small" />}
+        {!compact && (
+          <Box component="span" sx={{ display: { xs: "none", sm: "inline" } }}>
+            Exportar
+          </Box>
+        )}
+        <KeyboardArrowDownRoundedIcon fontSize="small" />
+      </Box>
+    </Button>
+  );
+}
+
+/** One format row: what it produces, and when to reach for it. */
+function FormatRow({
+  format,
+  onPick,
+  testIdPrefix,
+}: {
+  format: DataViewExportFormat;
+  onPick: () => void;
+  testIdPrefix: string;
+}): React.JSX.Element {
+  return (
+    <Box
+      component="button"
+      type="button"
+      onClick={onPick}
+      data-testid={`${testIdPrefix}-export-${format}`}
+      sx={{
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "flex-start",
+        width: "100%",
+        px: 1.5,
+        py: 1,
+        border: 0,
+        background: "none",
+        cursor: "pointer",
+        font: "inherit",
+        textAlign: "left",
+        "&:hover": { bgcolor: "action.hover" },
+      }}
+    >
+      <Box component="span" sx={{ fontSize: "0.8125rem" }}>
+        {FORMAT_COPY[format].label}
+      </Box>
+      <Box component="span" sx={{ fontSize: "0.6875rem", color: "text.disabled" }}>
+        {FORMAT_COPY[format].hint}
+      </Box>
+    </Box>
+  );
+}
+
+/** The panel: what is about to be exported, then the formats. */
+function ExportPanel({
+  formats,
+  selectedCount,
+  totalCount,
+  columnCount,
+  onPick,
+  testIdPrefix,
+}: {
+  formats: DataViewExportFormat[];
+  selectedCount: number;
+  totalCount: number;
+  columnCount: number;
+  onPick: (format: DataViewExportFormat) => void;
+  testIdPrefix: string;
+}): React.JSX.Element {
+  return (
+    <Box data-testid={`${testIdPrefix}-export-panel`}>
+      <Box sx={{ px: 1.5, pt: 1, pb: 1, borderBottom: 1, borderColor: "divider" }}>
+        <Text variant="caption" as="p">
+          <Box component="span" data-testid={`${testIdPrefix}-export-scope`}>
+            Exportando {scopeLabel(selectedCount, totalCount)}
+          </Box>
+        </Text>
+        <Text variant="caption" as="p">
+          <Box component="span" sx={{ color: "text.disabled" }}>
+            {columnCount} colunas visíveis, na ordem atual
+          </Box>
+        </Text>
+      </Box>
+      {formats.map((format) => (
+        <FormatRow
+          key={format}
+          format={format}
+          onPick={() => onPick(format)}
+          testIdPrefix={testIdPrefix}
+        />
+      ))}
+    </Box>
+  );
+}
+
+/** The toolbar's Exportar control. Renders nothing when no host wired it. */
+export function DataViewsExportMenu({
+  config,
+  query,
+  totalCount,
+  selectedIds,
+  columns,
+  testIdPrefix,
+  compact,
+}: ExportMenuProps): React.JSX.Element {
+  const [anchor, setAnchor] = useState<HTMLElement | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  const run = async (format: DataViewExportFormat): Promise<void> => {
+    setAnchor(null);
+    setBusy(true);
+    try {
+      await config.onExport({
+        format,
+        // UNPAGINATED: page 1 of a page as large as the whole result. The host
+        // re-queries with this; nothing here reads the loaded rows.
+        query: { ...query, page: 1, pageSize: Math.max(1, totalCount) },
+        selectedIds: selectedIds.length > 0 ? [...selectedIds] : undefined,
+        columns,
+      });
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <>
+      <ExportTrigger busy={busy} onOpen={setAnchor} testIdPrefix={testIdPrefix} compact={compact} />
+      <Popover
+        open={Boolean(anchor)}
+        anchorEl={anchor}
+        onClose={() => setAnchor(null)}
+        anchorOrigin={{ vertical: "bottom", horizontal: "right" }}
+        transformOrigin={{ vertical: "top", horizontal: "right" }}
+        slotProps={{ paper: { sx: { width: 260, maxWidth: "calc(100vw - 32px)" } } }}
+      >
+        <ExportPanel
+          formats={config.formats ?? ALL_FORMATS}
+          selectedCount={selectedIds.length}
+          totalCount={totalCount}
+          columnCount={columns.length}
+          onPick={(format) => void run(format)}
+          testIdPrefix={testIdPrefix}
+        />
+      </Popover>
+    </>
+  );
+}

package/src/components/data-display/DataViews/data-views-glyphs.tsx

@@ -0,0 +1,103 @@
+"use client";
+
+import { Box } from "../../../mui/Box";
+
+/**
+ * Miniature previews of what a layout or a density setting DOES.
+ *
+ * "Baixa / Média / Alta" tells an operator nothing until they try it, and
+ * "Grade" vs "Lista" is only obvious to whoever named them. A glyph that draws
+ * three tight rows, or three loose ones, or a grid of blocks, answers the
+ * question before the click — so the picker is read once instead of cycled
+ * through.
+ *
+ * Deliberately CSS boxes rather than icons: the point is to show spacing and
+ * proportion, which is exactly what an icon font flattens away.
+ */
+
+/** The glyph's own footprint, so every tile in a picker lines up. */
+const FRAME = { width: 32, height: 24, display: "flex" } as const;
+
+/** Active tiles use the accent; the rest stay muted so the choice reads at a glance. */
+function barColor(active: boolean): string {
+  return active ? "primary.main" : "action.disabled";
+}
+
+/** Three rows at a given gap — the density preview for the table and list. */
+export function RowsGlyph({ gap, active }: { gap: number; active: boolean }): React.JSX.Element {
+  return (
+    <Box sx={{ ...FRAME, flexDirection: "column", justifyContent: "center", gap: `${gap}px` }}>
+      {[0, 1, 2].map((index) => (
+        <Box key={index} sx={{ height: 2, width: "100%", borderRadius: 1, bgcolor: barColor(active) }} />
+      ))}
+    </Box>
+  );
+}
+
+/** A dense block grid — the table layout. */
+export function TableGlyph({ active }: { active: boolean }): React.JSX.Element {
+  return (
+    <Box sx={{ ...FRAME, display: "grid", gridTemplateColumns: "repeat(3, 1fr)", gap: "2px" }}>
+      {Array.from({ length: 9 }).map((_, index) => (
+        <Box
+          key={index}
+          sx={{ borderRadius: 0.5, bgcolor: barColor(active), opacity: index < 3 ? 1 : 0.55 }}
+        />
+      ))}
+    </Box>
+  );
+}
+
+/** Full-width rows each carrying a leading mark — the list layout. */
+export function ListGlyph({ active }: { active: boolean }): React.JSX.Element {
+  return (
+    <Box sx={{ ...FRAME, flexDirection: "column", justifyContent: "center", gap: "4px" }}>
+      {[0, 1, 2].map((index) => (
+        <Box
+          key={index}
+          sx={{
+            height: 5,
+            width: "100%",
+            borderRadius: 0.5,
+            bgcolor: barColor(active),
+            opacity: 0.7,
+            display: "flex",
+            alignItems: "center",
+          }}
+        >
+          <Box sx={{ ml: "2px", height: 3, width: 3, borderRadius: "50%", bgcolor: "background.paper" }} />
+        </Box>
+      ))}
+    </Box>
+  );
+}
+
+/**
+ * A grid of blocks — the cards layout, and ALSO the cards density preview: `n`
+ * is how many fit per row, so "Muitos / Médio / Poucos" is shown rather than
+ * described.
+ */
+export function GridGlyph({ n = 3, active }: { n?: number; active: boolean }): React.JSX.Element {
+  return (
+    <Box sx={{ ...FRAME, display: "grid", gridTemplateColumns: `repeat(${n}, 1fr)`, gap: "2px" }}>
+      {Array.from({ length: n * 2 }).map((_, index) => (
+        <Box key={index} sx={{ borderRadius: 0.5, bgcolor: barColor(active) }} />
+      ))}
+    </Box>
+  );
+}
+
+/** Three columns of decreasing height — the board. */
+export function BoardGlyph({ active }: { active: boolean }): React.JSX.Element {
+  return (
+    <Box sx={{ ...FRAME, gap: "2px" }}>
+      {[3, 2, 1].map((count, column) => (
+        <Box key={column} sx={{ flex: 1, display: "flex", flexDirection: "column", gap: "2px" }}>
+          {Array.from({ length: count }).map((_, index) => (
+            <Box key={index} sx={{ height: 5, borderRadius: 0.5, bgcolor: barColor(active) }} />
+          ))}
+        </Box>
+      ))}
+    </Box>
+  );
+}