@12-apps/ui 1.5.1 → 1.6.0

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

@@ -0,0 +1,356 @@
+"use client";
+
+import { useEffect, useMemo, useRef } from "react";
+
+import { Box } from "../../../mui/Box";
+
+/**
+ * SCOPES — a page-level partition rendered as a strip of tabs above the toolbar.
+ *
+ * A scope is not a filter. Filters NARROW within the current partition and are
+ * multi-select by design; a scope PARTITIONS and is exclusive. The distinction
+ * is load-bearing for three reasons, and each is why `FilterFieldConfig` could
+ * not express these tabs:
+ *
+ *   1. They are mutually exclusive, and a pill is not.
+ *   2. They carry counts of the WHOLE query, which no client can compute under
+ *      pagination — the count has to come off the response
+ *      ({@link DataViewServer.scopeCounts}).
+ *   3. They compose with the filters instead of competing with them: the scope
+ *      picks the bucket, the pills narrow inside it.
+ *
+ * The `predicate` is deliberately opaque to this package. Only the host knows
+ * what "recusados" selects; the component's whole job is to say WHICH scope is
+ * active and let the server answer.
+ */
+export interface ScopeConfig {
+  /** Stable id — travels in `DataViewQuery.scope` and in a saved view's state. */
+  id: string;
+  label: string;
+  /**
+   * Opaque payload the SERVER interprets. Omitted on the "all" scope. Never read
+   * by this package: a scope is applied at the backend, never in the browser.
+   */
+  predicate?: unknown;
+}
+
+/**
+ * The active scope id, resolved against what the table currently declares.
+ *
+ * Resolution happens at READ time, on purpose. A saved view is written once and
+ * read many times, and the declared scopes change underneath it — a scope
+ * removed after a view was saved must fall back at render rather than break the
+ * view or, worse, emit a scope the backend rejects. Resolving on write would
+ * bake the mistake in.
+ *
+ * Returns `undefined` when the table declares no scopes, which is what keeps
+ * `scope` out of the emitted query entirely for every table that never opted in.
+ */
+export function resolveScope(scopes: ScopeConfig[], stored: string | undefined): string | undefined {
+  if (scopes.length === 0) return undefined;
+  const declared = stored !== undefined && scopes.some((scope) => scope.id === stored);
+  return declared ? stored : scopes[0]?.id;
+}
+
+/** Are we running outside production? Config mistakes fail loudly only here. */
+function isDevelopment(): boolean {
+  return typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
+}
+
+/**
+ * Reject a table that partitions by a field AND declares a filter pill over the
+ * same field. Two controls over one field is how a tab and a pill end up
+ * contradicting each other — the pill says "estado ∈ {pago, recusado}" while the
+ * tab says "estado = recusado", and nothing in either control can show the user
+ * which one the server honoured.
+ *
+ * Throws in DEVELOPMENT ONLY. A thrown config error in production is strictly
+ * worse than a duplicated control: the duplicate is confusing, the throw is a
+ * blank page. Fail where it is seen and fixed.
+ *
+ * `scopeFieldId` is the field the scopes partition by, when the host knows it.
+ * Absent, the scope IDS are checked against the field ids — which catches the
+ * common shape where the scope ids ARE the field's values (`pago`, `recusado`)
+ * declared a second time as a pill.
+ */
+export function assertNoScopePillOverlap(
+  scopes: ScopeConfig[],
+  fieldIds: string[],
+  scopeFieldId?: string,
+): void {
+  if (scopes.length === 0 || !isDevelopment()) return;
+  const clash = scopeFieldId !== undefined && fieldIds.includes(scopeFieldId) ? scopeFieldId : undefined;
+  if (clash === undefined) return;
+  throw new Error(
+    `DataViews: the field "${clash}" is both the scope partition (scopes: ` +
+      `${scopes.map((scope) => scope.id).join(", ")}) and a filter field (fields: ` +
+      `${fieldIds.join(", ")}). A field may drive the scope tabs or a filter pill, not both — ` +
+      `drop one of the two declarations.`,
+  );
+}
+
+/**
+ * A development-only warning that scopes need server wiring. Scopes are resolved
+ * and emitted, never applied in the browser: filtering locally would make the
+ * counts, the "N de N" counter and the rendered rows disagree the moment a
+ * second page exists.
+ */
+export function warnScopesNeedServer(scopes: ScopeConfig[], hasServer: boolean): void {
+  if (scopes.length === 0 || hasServer || !isDevelopment()) return;
+  // eslint-disable-next-line no-console -- a config warning has no other channel.
+  console.warn(
+    "DataViews: `scopes` require server mode. The scope is tracked and would be emitted, " +
+      "but with no `server` there is nothing to emit it to and rows are NOT filtered in the browser. " +
+      "Supply `server` (see DataViewServer) or drop the scopes.",
+  );
+}
+
+/**
+ * The scope configuration's setup-time checks, run once per configuration rather
+ * than per render: reject a field that is both a scope partition and a filter
+ * pill (development only — see `assertNoScopePillOverlap`), and warn about
+ * scopes declared with no server to apply them.
+ *
+ * In a `useMemo` so a mistake surfaces during the FIRST render, where the stack
+ * still points at the table that made it.
+ */
+export function useScopeConfigChecks(
+  scopes: ScopeConfig[],
+  fieldIds: string[],
+  scopeFieldId: string | undefined,
+  hasServer: boolean,
+): void {
+  useMemo(() => {
+    assertNoScopePillOverlap(scopes, fieldIds, scopeFieldId);
+    warnScopesNeedServer(scopes, hasServer);
+    // Keyed on the ids rather than the arrays: hosts pass inline literals, so the
+    // array identity changes every render while the configuration does not.
+  }, [scopes, fieldIds.join(","), scopeFieldId, hasServer]);
+}
+
+/** Everything the tab strip needs; `counts` is absent when the server omits it. */
+interface DataViewsScopeTabsProps {
+  scopes: ScopeConfig[];
+  /** The RESOLVED active scope id (see {@link resolveScope}). */
+  value: string | undefined;
+  onChange: (id: string) => void;
+  /** Server-supplied per-scope totals. Absent ⇒ tabs render WITHOUT numbers. */
+  counts?: Record<string, number>;
+  testIdPrefix: string;
+}
+
+/** The accessible name of one tab: its label, plus its count when there is one. */
+function tabLabel(label: string, count: number | undefined): string {
+  return count === undefined ? label : `${label}, ${count}`;
+}
+
+/**
+ * Move focus + selection between tabs with the arrow keys, wrapping at both
+ * ends. Selection FOLLOWS focus here (an "automatic activation" tab list): each
+ * arrow press is one scope change, which is one query — the same cost as a
+ * click, and it keeps the strip's behaviour identical whichever input the
+ * operator uses.
+ */
+function arrowTarget(key: string, index: number, total: number): number | null {
+  if (key === "ArrowRight") return (index + 1) % total;
+  if (key === "ArrowLeft") return (index - 1 + total) % total;
+  if (key === "Home") return 0;
+  if (key === "End") return total - 1;
+  return null;
+}
+
+/** The active tab's own scroll-into-view, so a deep link to a late scope lands visible. */
+function useScrollActiveIntoView(value: string | undefined): React.RefObject<HTMLDivElement | null> {
+  const stripRef = useRef<HTMLDivElement | null>(null);
+  useEffect(() => {
+    const strip = stripRef.current;
+    if (!strip || value === undefined) return;
+    const active = strip.querySelector<HTMLElement>('[role="tab"][aria-selected="true"]');
+    // jsdom implements neither, so guard rather than assume the DOM is a browser's.
+    active?.scrollIntoView?.({ block: "nearest", inline: "nearest" });
+  }, [value]);
+  return stripRef;
+}
+
+/** One tab's visual + a11y state, kept out of the strip's map for readability. */
+function scopeTabSx(active: boolean): Record<string, unknown> {
+  return {
+    // A 44px min target: the strip is the first thing a thumb reaches on a phone.
+    minHeight: 44,
+    px: 1.5,
+    py: 1,
+    border: 0,
+    borderBottom: 2,
+    borderStyle: "solid",
+    borderColor: active ? "primary.main" : "transparent",
+    background: "none",
+    cursor: "pointer",
+    whiteSpace: "nowrap",
+    font: "inherit",
+    fontSize: "0.8125rem",
+    fontWeight: active ? 600 : 400,
+    color: active ? "primary.main" : "text.secondary",
+    "&:hover": { color: active ? "primary.main" : "text.primary" },
+    "&:focus-visible": { outline: "2px solid", outlineColor: "primary.main", outlineOffset: -2 },
+  };
+}
+
+/** The count badge. Rendered only when the server actually supplied a number. */
+function ScopeCount({
+  count,
+  active,
+  testId,
+}: {
+  count: number;
+  active: boolean;
+  testId: string;
+}): React.JSX.Element {
+  return (
+    <Box
+      component="span"
+      // The number is already in the tab's `aria-label`; announcing it twice
+      // would read "Recusados 2, 2".
+      aria-hidden="true"
+      data-testid={testId}
+      sx={{
+        ml: 0.75,
+        px: 0.75,
+        borderRadius: 5,
+        fontSize: "0.6875rem",
+        fontWeight: 600,
+        bgcolor: active ? "primary.main" : "action.selected",
+        color: active ? "primary.contrastText" : "text.secondary",
+      }}
+    >
+      {count}
+    </Box>
+  );
+}
+
+interface ScopeTabProps {
+  scope: ScopeConfig;
+  index: number;
+  total: number;
+  active: boolean;
+  count: number | undefined;
+  onChange: (id: string) => void;
+  /**
+   * Move to the tab at `index`: focus it AND select it. Only the strip knows
+   * the other scopes and owns the DOM, so the move belongs to it.
+   */
+  moveTo: (index: number) => void;
+  testIdPrefix: string;
+}
+
+/** One tab: a real `<button role="tab">` with a roving tabindex and arrow keys. */
+function ScopeTab({
+  scope,
+  index,
+  total,
+  active,
+  count,
+  onChange,
+  moveTo,
+  testIdPrefix,
+}: ScopeTabProps): React.JSX.Element {
+  return (
+    <Box
+      component="button"
+      type="button"
+      role="tab"
+      id={`${testIdPrefix}-scope-tab-${scope.id}`}
+      aria-selected={active}
+      // Roving tabindex: one tab stop for the whole strip, arrows move within it.
+      tabIndex={active ? 0 : -1}
+      aria-label={tabLabel(scope.label, count)}
+      data-testid={`${testIdPrefix}-scope-${scope.id}`}
+      onClick={() => onChange(scope.id)}
+      onKeyDown={(event: React.KeyboardEvent<HTMLButtonElement>) => {
+        const target = arrowTarget(event.key, index, total);
+        if (target === null) return;
+        event.preventDefault();
+        moveTo(target);
+      }}
+      sx={scopeTabSx(active)}
+    >
+      {scope.label}
+      {count !== undefined && (
+        <ScopeCount
+          count={count}
+          active={active}
+          testId={`${testIdPrefix}-scope-count-${scope.id}`}
+        />
+      )}
+    </Box>
+  );
+}
+
+/** The strip's own layout: one non-wrapping row that scrolls horizontally. */
+const STRIP_SX = {
+  display: "flex",
+  alignItems: "stretch",
+  gap: 0.5,
+  // One row that scrolls — never wraps, never collapses into a select.
+  flexWrap: "nowrap",
+  overflowX: "auto",
+  overflowY: "hidden",
+  scrollbarWidth: "thin",
+  borderBottom: 1,
+  borderColor: "divider",
+  mx: { xs: -2, md: -3 },
+  px: { xs: 2, md: 3 },
+} as const;
+
+/**
+ * The scope strip: a horizontally scrolling tab list above the toolbar.
+ *
+ * It SCROLLS rather than collapsing into a select on a narrow screen, which is
+ * the opposite of what the filter pills do — and deliberately. The counts are
+ * the reason the tabs exist at all; burying them behind a menu costs a tap per
+ * glance, exactly on the device where glancing is the point.
+ *
+ * Counts render verbatim from `counts` — never derived from the loaded page, and
+ * never invented when the key is missing. A missing count means "the server did
+ * not say", which reads honestly as no badge at all.
+ */
+export function DataViewsScopeTabs({
+  scopes,
+  value,
+  onChange,
+  counts,
+  testIdPrefix,
+}: DataViewsScopeTabsProps): React.JSX.Element | null {
+  const stripRef = useScrollActiveIntoView(value);
+  const moveTo = (index: number): void => {
+    // Focus FIRST, then select: the roving tabindex follows the selection, so
+    // focusing afterwards would land on a tab that has given up its tab stop.
+    stripRef.current?.querySelectorAll<HTMLElement>('[role="tab"]')?.[index]?.focus();
+    const next = scopes[index];
+    if (next) onChange(next.id);
+  };
+  // Reserve NO vertical space when there is nothing to show: a page that
+  // declares no scopes must not gain an empty row.
+  if (scopes.length === 0) return null;
+  const activeIndex = Math.max(
+    0,
+    scopes.findIndex((scope) => scope.id === value),
+  );
+
+  return (
+    <Box ref={stripRef} role="tablist" aria-label="Situação" data-testid={`${testIdPrefix}-scopes`} sx={STRIP_SX}>
+      {scopes.map((scope, index) => (
+        <ScopeTab
+          key={scope.id}
+          scope={scope}
+          index={index}
+          total={scopes.length}
+          active={index === activeIndex}
+          count={counts?.[scope.id]}
+          onChange={onChange}
+          moveTo={moveTo}
+          testIdPrefix={testIdPrefix}
+        />
+      ))}
+    </Box>
+  );
+}

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

@@ -0,0 +1,156 @@
+"use client";
+
+/**
+ * THE INLINE BAR'S SEARCH — the one control on the toolbar that cannot be
+ * guessed from an icon's position, which is why it is the LAST thing the
+ * degradation ladder takes away. See `data-views-overflow.ts`.
+ */
+import CloseIcon from "@mui/icons-material/Close";
+import SearchIcon from "@mui/icons-material/Search";
+import { IconButton, InputAdornment, TextField } from "@mui/material";
+import { useEffect, useRef, useState } from "react";
+
+import { Box } from "../../../mui/Box";
+
+/** How long the box waits after the last keystroke before it queries. */
+const SEARCH_DEBOUNCE_MS = 350;
+
+/**
+ * The bar's keyword box.
+ *
+ * DEBOUNCED rather than committed on Enter/blur. In server mode every commit is
+ * a round trip, and a box that only fires on blur makes the operator press a
+ * key they were not told about to see any result at all — they type, nothing
+ * happens, and the list looks broken. 350ms is long enough that a word costs
+ * one query, short enough to feel like live search.
+ *
+ * `Escape` clears; the X clears without leaving the box. Both exist because
+ * clearing by selecting-and-deleting is three gestures for the most common
+ * thing anyone does to a search box.
+ */
+export function InlineKeyword({
+  value,
+  onChange,
+  testId,
+  autoFocus,
+  onEscape,
+}: {
+  value: string;
+  onChange: (value: string) => void;
+  testId?: string;
+  autoFocus?: boolean;
+  /** Called on Escape with the box already empty — the collapsed bar closes it. */
+  onEscape?: () => void;
+}): React.JSX.Element {
+  const [draft, setDraft] = useState(value);
+  const prev = useRef(value);
+  // An external change (a saved view, the URL, "Limpar") wins over the draft.
+  if (prev.current !== value) {
+    prev.current = value;
+    if (draft !== value) setDraft(value);
+  }
+  useEffect(() => {
+    if (draft === value) return undefined;
+    const timer = setTimeout(() => onChange(draft), SEARCH_DEBOUNCE_MS);
+    return () => clearTimeout(timer);
+  }, [draft, value, onChange]);
+
+  return (
+    <TextField
+      size="small"
+      value={draft}
+      autoFocus={autoFocus}
+      onChange={(event) => setDraft(event.target.value)}
+      onKeyDown={(event) => {
+        if (event.key === "Escape") {
+          event.preventDefault();
+          if (draft === "") onEscape?.();
+          setDraft("");
+          return;
+        }
+        // Enter still commits IMMEDIATELY, ahead of the debounce — someone who
+        // presses it has decided, and waiting out the timer reads as a stall.
+        if (event.key !== "Enter") return;
+        event.preventDefault();
+        if (draft !== value) onChange(draft);
+      }}
+      placeholder="Buscar…"
+      inputProps={{ "aria-label": "Buscar em todas as colunas", "data-testid": testId }}
+      InputProps={{
+        startAdornment: (
+          <InputAdornment position="start">
+            <SearchIcon sx={{ fontSize: 16, color: "text.secondary" }} />
+          </InputAdornment>
+        ),
+        endAdornment: draft ? (
+          <InputAdornment position="end">
+            <IconButton
+              size="small"
+              aria-label="Limpar busca"
+              data-testid={testId ? `${testId}-clear` : undefined}
+              onClick={() => setDraft("")}
+              sx={{ p: 0.25 }}
+            >
+              <CloseIcon sx={{ fontSize: 14 }} />
+            </IconButton>
+          </InputAdornment>
+        ) : undefined,
+      }}
+      // Takes the free space and gives it up first — step 3 of the ladder,
+      // which needs no flag because flex does it (see `computeSplit`).
+      sx={{ flex: 1, minWidth: 200, maxWidth: 384 }}
+    />
+  );
+}
+
+/**
+ * Step 4 of the ladder: the search as a magnifier.
+ *
+ * Carries a dot when a search is APPLIED. Collapsing a control that is
+ * currently filtering the list, with nothing saying so, is how an operator ends
+ * up staring at 3 rows of 214 and reading it as missing data.
+ */
+export function CollapsedSearch({
+  active,
+  onOpen,
+  testId,
+}: {
+  active: boolean;
+  onOpen: () => void;
+  testId?: string;
+}): React.JSX.Element {
+  return (
+    <IconButton
+      size="small"
+      onClick={onOpen}
+      aria-label="Buscar"
+      aria-expanded={false}
+      data-testid={testId ? `${testId}-collapsed` : undefined}
+      sx={{
+        position: "relative",
+        border: 1,
+        borderRadius: 1,
+        borderColor: active ? "primary.main" : "divider",
+        color: active ? "primary.main" : "text.secondary",
+        bgcolor: active ? "action.selected" : "background.paper",
+      }}
+    >
+      <SearchIcon sx={{ fontSize: 18 }} />
+      {active && (
+        <Box
+          component="span"
+          sx={{
+            position: "absolute",
+            top: 2,
+            right: 2,
+            width: 6,
+            height: 6,
+            borderRadius: "50%",
+            bgcolor: "primary.main",
+          }}
+        />
+      )}
+    </IconButton>
+  );
+}
+

package/src/components/data-display/DataViews/data-views-select-all-strip.tsx

@@ -0,0 +1,105 @@
+"use client";
+
+import { Checkbox } from "@mui/material";
+
+import { Button } from "../../form/Button";
+import { Box } from "../../../mui/Box";
+import { Text } from "../../typography/Text";
+
+/**
+ * SELECT-ALL FOR THE LAYOUTS THAT HAVE NO HEADER ROW.
+ *
+ * The table gets this for free: its `<thead>` carries a checkbox, so beginning
+ * a selection is one click on a control that sits with the rows it selects.
+ * The cards, the list and the board have no header at all — so without this
+ * there is NO way to start a selection except clicking an item first, and
+ * "select everything on this page" costs one click per row.
+ *
+ * It is deliberately NOT more toolbar chrome. It sits directly above the
+ * content it selects, which is exactly where the table's `<thead>` checkbox
+ * sits; putting it in the toolbar would separate the control from its object
+ * and would also be the third place in this component that renders a
+ * select-all.
+ *
+ * Renders nothing for an empty page: a select-all over zero rows is a control
+ * that cannot do anything, and reserving its band would make the empty state
+ * sit lower in the cards than it does in the table.
+ */
+export function SelectAllStrip<T>({
+  rows,
+  getRowId,
+  selectedIds,
+  onChange,
+  testIdPrefix,
+}: {
+  rows: T[];
+  getRowId: (row: T) => string | number;
+  selectedIds: Set<string | number>;
+  onChange: (next: Set<string | number>) => void;
+  testIdPrefix: string;
+}): React.JSX.Element | null {
+  if (rows.length === 0) return null;
+  const pageIds = rows.map(getRowId);
+  const selectedHere = pageIds.filter((id) => selectedIds.has(id)).length;
+  const all = selectedHere === pageIds.length;
+  // INDETERMINATE, not just checked/unchecked: with 3 of 25 selected, an
+  // unchecked box says "nothing is selected" and a checked one says
+  // "everything is". Both are wrong, and the third state is the honest one.
+  const some = selectedHere > 0 && !all;
+
+  const toggle = (): void => {
+    if (all) {
+      // Clear only THIS page's ids — a selection made on another page is not
+      // this control's to discard.
+      const next = new Set(selectedIds);
+      pageIds.forEach((id) => next.delete(id));
+      onChange(next);
+      return;
+    }
+    onChange(new Set([...selectedIds, ...pageIds]));
+  };
+
+  return (
+    <Box
+      data-testid={`${testIdPrefix}-select-all-strip`}
+      sx={{
+        display: "flex",
+        alignItems: "center",
+        gap: 1,
+        mt: 1.5,
+        px: 1,
+        py: 0.75,
+        borderBottom: 1,
+        borderColor: "divider",
+        bgcolor: "action.hover",
+        borderRadius: 1,
+      }}
+    >
+      <Checkbox
+        size="small"
+        checked={all}
+        indeterminate={some}
+        onChange={toggle}
+        data-testid={`${testIdPrefix}-select-all-box`}
+        inputProps={{ "aria-label": "Selecionar todos nesta página" }}
+        sx={{ p: 0.5 }}
+      />
+      <Button
+        variant="text"
+        size="sm"
+        color="secondary"
+        onClick={toggle}
+        dataTestId={`${testIdPrefix}-select-all-toggle`}
+      >
+        {all ? "Limpar seleção" : "Selecionar tudo"}
+      </Button>
+      <Text variant="caption" as="span">
+        {/* "nesta página" is load-bearing: the scope tabs above show
+            whole-query totals, so an unqualified count here would read as one. */}
+        <Box component="span" sx={{ ml: "auto", color: "text.disabled", whiteSpace: "nowrap" }}>
+          {rows.length} nesta página
+        </Box>
+      </Text>
+    </Box>
+  );
+}

package/src/components/data-display/DataViews/data-views-selection.ts

@@ -0,0 +1,50 @@
+"use client";
+
+import { useMemo, useState } from "react";
+
+/** The multi-select model, identical in every layout (table, cards, board). */
+interface DataViewsSelection<T> {
+  selectedIds: Set<string | number>;
+  setSelectedIds: (ids: Set<string | number>) => void;
+  /** Add/remove ONE id — what a card's or board card's checkbox calls. */
+  toggleId: (id: string | number) => void;
+  /** The selected rows, narrowed to what is currently rendered. */
+  selectedRows: T[];
+  clearSelection: () => void;
+  selectAll: () => void;
+}
+
+/**
+ * Owns the DataViews selection. ONE set of ids across every layout, so switching
+ * from the board to the table (or to the cards) keeps exactly the same rows
+ * selected and offers exactly the same bulk actions.
+ *
+ * Extracted from {@link useDataViewsState} for that hook's size budget, and
+ * because `toggleId` needs a functional update: two cards toggled in the same
+ * tick would otherwise both read the pre-render set and the second would drop
+ * the first's change.
+ */
+export function useSelection<T>(
+  matched: T[],
+  getRowId: (row: T) => string | number,
+): DataViewsSelection<T> {
+  const [selectedIds, setSelectedIds] = useState<Set<string | number>>(new Set());
+  const selectedRows = useMemo(
+    () => matched.filter((row) => selectedIds.has(getRowId(row))),
+    [matched, selectedIds, getRowId],
+  );
+  return {
+    selectedIds,
+    setSelectedIds,
+    toggleId: (id) =>
+      setSelectedIds((prev) => {
+        const next = new Set(prev);
+        if (next.has(id)) next.delete(id);
+        else next.add(id);
+        return next;
+      }),
+    selectedRows,
+    clearSelection: () => setSelectedIds(new Set()),
+    selectAll: () => setSelectedIds(new Set(matched.map((row) => getRowId(row)))),
+  };
+}