@12-apps/ui 1.0.0 → 1.3.1

package/src/components/data-display/DataViews/data-views-inline-bar.tsx

@@ -0,0 +1,257 @@
+"use client";
+
+/**
+ * The INLINE filter bar — the horizontal row of controls a grid renders instead
+ * of the slide-in panel on a wide screen (`inlineFilters`): the compact keyword
+ * box, one pill per facet, one pill per range, and the "Filtros ativos" chips
+ * underneath.
+ *
+ * Split from `data-views-filter-panel` because they are two surfaces, not one:
+ * the panel is a column of stacked fields, this is a row of pills, and the only
+ * thing they share is the prop shape they are both driven by.
+ */
+import SearchIcon from '@mui/icons-material/Search';
+import { Box, Button, Chip, InputAdornment, TextField, Typography } from "@mui/material";
+import { useRef, useState } from "react";
+
+import { MultiSelectDropdown } from "../../layout/ContentToolbar";
+
+import type { GridFilterPanelProps } from "./data-views-filter-panel";
+import { isRangeSet, RangePill, rangeChipLabel } from "./data-views-range-pill";
+
+
+
+/* ── Inline (second-line) filter bar ─────────────────────────────────────── */
+
+/** Compact keyword box for the inline bar: commits on Enter/blur (like the panel). */
+function InlineKeyword({
+  value,
+  onChange,
+  testId,
+}: {
+  value: string;
+  onChange: (value: string) => void;
+  testId?: string;
+}): React.JSX.Element {
+  const [draft, setDraft] = useState(value);
+  const prev = useRef(value);
+  if (prev.current !== value) {
+    prev.current = value;
+    if (draft !== value) setDraft(value);
+  }
+  const commit = (): void => {
+    if (draft !== value) onChange(draft);
+  };
+  return (
+    <TextField
+      size="small"
+      value={draft}
+      onChange={(event) => setDraft(event.target.value)}
+      onBlur={commit}
+      onKeyDown={(event) => {
+        if (event.key !== "Enter") return;
+        event.preventDefault();
+        commit();
+      }}
+      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>
+        ),
+      }}
+      sx={{ minWidth: 220 }}
+    />
+  );
+}
+
+/** Props the inline bar needs (the slide-in panel's, minus its own chrome). */
+type InlineFilterBarProps<T extends Record<string, unknown>> = Pick<
+  GridFilterPanelProps<T>,
+  | "testIdPrefix"
+  | "search"
+  | "fields"
+  | "rangeFields"
+  | "pills"
+  | "ranges"
+  | "onSearchChange"
+  | "onTogglePill"
+  | "onChangeRange"
+  | "onClearField"
+  | "onClearAll"
+>;
+
+/** One removable active-filter chip: a search term, a pill value or a window. */
+interface ActiveChip {
+  key: string;
+  label: string;
+  onDelete: () => void;
+}
+
+/**
+ * Every applied filter flattened into removable chips. A pill contributes one
+ * chip per selected value (deleting one leaves the rest), while a RANGE
+ * contributes a single chip for the whole window — "remove the period" means
+ * both ends, not an arbitrary one.
+ */
+function activeChips<T extends Record<string, unknown>>({
+  search,
+  fields,
+  rangeFields,
+  pills,
+  ranges,
+  onSearchChange,
+  onTogglePill,
+  onChangeRange,
+}: Pick<
+  GridFilterPanelProps<T>,
+  | "search"
+  | "fields"
+  | "rangeFields"
+  | "pills"
+  | "ranges"
+  | "onSearchChange"
+  | "onTogglePill"
+  | "onChangeRange"
+>): ActiveChip[] {
+  const searchChip: ActiveChip[] =
+    search.trim() === ""
+      ? []
+      : [{ key: "__search", label: `Busca: ${search}`, onDelete: () => onSearchChange("") }];
+  const pillChips: ActiveChip[] = fields.flatMap((field) =>
+    (pills[field.id] ?? []).map((value) => ({
+      key: `${field.id}:${value}`,
+      label: `${field.label}: ${field.options.find((option) => option.value === value)?.label ?? value}`,
+      onDelete: () => onTogglePill(field.id, value, false),
+    })),
+  );
+  const rangeChips: ActiveChip[] = rangeFields.flatMap((field) => {
+    const range = ranges[field.id];
+    if (!range || !isRangeSet(range)) return [];
+    return [
+      {
+        key: `range:${field.id}`,
+        label: rangeChipLabel(field, range),
+        onDelete: () => onChangeRange(field.id, {}),
+      },
+    ];
+  });
+  return [...searchChip, ...pillChips, ...rangeChips];
+}
+
+/**
+ * A horizontal filter bar (used instead of the slide-in {@link GridFilterPanel} on
+ * wide screens): the compact keyword search, each field as a rounded pill dropdown,
+ * and — when anything is applied — a row of removable "active filter" chips. Range
+ * filters are not shown here (the slide-in panel keeps those).
+ */
+export function InlineFilterBar<T extends Record<string, unknown>>({
+  testIdPrefix,
+  search,
+  fields,
+  rangeFields,
+  pills,
+  ranges,
+  onSearchChange,
+  onTogglePill,
+  onChangeRange,
+  onClearField,
+  onClearAll,
+}: InlineFilterBarProps<T>): React.JSX.Element {
+  const chips = activeChips({
+    search,
+    fields,
+    rangeFields,
+    pills,
+    ranges,
+    onSearchChange,
+    onTogglePill,
+    onChangeRange,
+  });
+  return (
+    <Box
+      data-testid={`${testIdPrefix}-inline-filters`}
+      sx={{ display: "flex", flexDirection: "column", gap: 1.5, py: 1.5 }}
+    >
+      <Box sx={{ display: "flex", flexWrap: "wrap", alignItems: "center", gap: 1.5 }}>
+        <InlineKeyword value={search} onChange={onSearchChange} testId={`${testIdPrefix}-search-all`} />
+        {fields.map((field) => (
+          <MultiSelectDropdown
+            key={field.id}
+            label={field.label}
+            options={field.options}
+            selected={new Set(pills[field.id] ?? [])}
+            onToggle={(value, checked) => onTogglePill(field.id, value, checked)}
+            onClear={() => onClearField(field.id)}
+            allLabel="Todas"
+            searchable={field.searchEnabled ? true : undefined}
+            searchPlaceholder="Buscar…"
+            noResultsLabel="Nenhum resultado"
+            layout="pill"
+            data-testid={`${testIdPrefix}-filter-${field.id}`}
+          />
+        ))}
+        {rangeFields.map((field) => (
+          <RangePill
+            key={field.id}
+            field={field}
+            value={ranges[field.id] ?? {}}
+            onChange={(range) => onChangeRange(field.id, range)}
+            testIdPrefix={testIdPrefix}
+          />
+        ))}
+      </Box>
+      <ActiveChipRow
+        chips={chips}
+        testIdPrefix={testIdPrefix}
+        onClearAll={onClearAll}
+      />
+    </Box>
+  );
+}
+
+/**
+ * The "Filtros ativos:" row — one removable chip per applied filter plus the
+ * single "Limpar" that drops them all. Renders nothing when nothing is applied,
+ * so the bar collapses to its controls.
+ */
+function ActiveChipRow({
+  chips,
+  testIdPrefix,
+  onClearAll,
+}: {
+  chips: ActiveChip[];
+  testIdPrefix: string;
+  onClearAll: () => void;
+}): React.JSX.Element | null {
+  if (chips.length === 0) return null;
+  return (
+    <Box sx={{ display: "flex", flexWrap: "wrap", alignItems: "center", gap: 1 }}>
+      <Typography component="span" sx={{ fontSize: "0.75rem", color: "text.secondary" }}>
+        Filtros ativos:
+      </Typography>
+      {chips.map((chip) => (
+        <Chip
+          key={chip.key}
+          label={chip.label}
+          size="small"
+          variant="outlined"
+          onDelete={chip.onDelete}
+          data-testid={`${testIdPrefix}-active-${chip.key}`}
+        />
+      ))}
+      <Button
+        variant="text"
+        size="small"
+        color="inherit"
+        onClick={onClearAll}
+        data-testid={`${testIdPrefix}-clear-filters`}
+        sx={{ fontSize: "0.75rem", color: "text.secondary", textTransform: "none" }}
+      >
+        Limpar
+      </Button>
+    </Box>
+  );
+}

package/src/components/data-display/DataViews/data-views-layout-context.tsx

@@ -0,0 +1,176 @@
+"use client";
+
+import { createContext, useContext, useMemo, useState, type ReactNode } from "react";
+
+import GridViewOutlinedIcon from "@mui/icons-material/GridViewOutlined";
+import KeyboardArrowDownRoundedIcon from "@mui/icons-material/KeyboardArrowDownRounded";
+import ViewListOutlinedIcon from "@mui/icons-material/ViewListOutlined";
+
+import { Button } from "../../form/Button";
+import { Slider } from "../../form/Slider";
+import { Box } from "../../../mui/Box";
+import { DropdownMenu } from "../../navigation/DropdownMenu";
+
+/**
+ * The DataViews layout (view type): the dense "Tabela" grid, or the "Grade" of
+ * cards. Shared across the toolbar (the toggle) and the body (the selector) via
+ * context so a single source of truth drives what renders — the toggle only
+ * appears when the table opts into cards by supplying a `renderCard` (each entity
+ * implements its own card). Reusable feature of the DataViews machinery.
+ */
+export type DataViewsLayout = "cards" | "table";
+
+interface DataViewsLayoutValue {
+  layout: DataViewsLayout;
+  setLayout: (layout: DataViewsLayout) => void;
+  /** Whether the cards layout is available (a `renderCard` was supplied). */
+  canUseCards: boolean;
+  /** Card-size zoom (0–100); drives the card grid's min column width. */
+  zoom: number;
+  setZoom: (zoom: number) => void;
+}
+
+const DataViewsLayoutContext = createContext<DataViewsLayoutValue | null>(null);
+
+/** Default card zoom (0–100). */
+const DEFAULT_ZOOM = 35;
+/** The card's width in px at scale 1 — the zoom slider multiplies this. */
+const BASE_CARD_WIDTH = 180;
+/** The size multiplier the zoom slider spans (0.75× to 2×). */
+const CARD_SCALE_RANGE = { min: 0.75, max: 2 } as const;
+
+/**
+ * Map the 0–100 zoom to the card SIZE multiplier. This is the single knob: the
+ * card's width is {@link BASE_CARD_WIDTH} × scale and its padding + typography
+ * scale by the same factor, so the whole card grows together (scale 2 → twice
+ * the size, proportion preserved by the aspect ratio). Passed to a card via
+ * `DataViewCardSelection.scale`.
+ */
+export function cardScaleForZoom(zoom: number): number {
+  const clamped = Math.max(0, Math.min(100, zoom));
+  return CARD_SCALE_RANGE.min + (clamped / 100) * (CARD_SCALE_RANGE.max - CARD_SCALE_RANGE.min);
+}
+
+/** The card grid's min column width in px = base width × the zoom size multiplier. */
+export function cardMinWidthForZoom(zoom: number): number {
+  return Math.round(BASE_CARD_WIDTH * cardScaleForZoom(zoom));
+}
+
+/**
+ * Provides the view-type state. When cards aren't available the layout is pinned
+ * to "table" regardless, so a consumer never renders a cards body without a
+ * `renderCard`.
+ */
+export function DataViewsLayoutProvider({
+  canUseCards,
+  defaultLayout = "table",
+  children,
+}: {
+  canUseCards: boolean;
+  defaultLayout?: DataViewsLayout;
+  children: ReactNode;
+}): React.JSX.Element {
+  const [layout, setLayout] = useState<DataViewsLayout>(canUseCards ? defaultLayout : "table");
+  const [zoom, setZoom] = useState(DEFAULT_ZOOM);
+  const value = useMemo<DataViewsLayoutValue>(
+    () => ({ layout: canUseCards ? layout : "table", setLayout, canUseCards, zoom, setZoom }),
+    [layout, canUseCards, zoom],
+  );
+  return <DataViewsLayoutContext.Provider value={value}>{children}</DataViewsLayoutContext.Provider>;
+}
+
+/** Read the current DataViews layout. Throws outside a provider. */
+export function useDataViewsLayout(): DataViewsLayoutValue {
+  const ctx = useContext(DataViewsLayoutContext);
+  if (!ctx) {
+    throw new Error("useDataViewsLayout must be used within a DataViewsLayoutProvider");
+  }
+  return ctx;
+}
+
+/** The layout options, in menu order. */
+const GRADE_OPTION = { value: "cards" as const, label: "Grade", Icon: GridViewOutlinedIcon };
+const TABELA_OPTION = { value: "table" as const, label: "Tabela", Icon: ViewListOutlinedIcon };
+const LAYOUT_OPTIONS = [GRADE_OPTION, TABELA_OPTION];
+
+/**
+ * The layout selector for the toolbar — a muted dropdown icon-button showing the
+ * active view's icon + a chevron, opening a menu of Grade/Tabela with a check on
+ * the active one. Mirrors the other toolbar dropdowns (Columns / Sort By) rather
+ * than a pair of buttons. Renders nothing when the table has no cards layout, so
+ * pages without a `renderCard` are unaffected.
+ */
+export function DataViewsLayoutToggle({ testIdPrefix }: { testIdPrefix: string }): React.JSX.Element | null {
+  const { layout, setLayout, canUseCards } = useDataViewsLayout();
+  if (!canUseCards) return null;
+
+  const active = layout === "cards" ? GRADE_OPTION : TABELA_OPTION;
+  const ActiveIcon = active.Icon;
+
+  return (
+    <DropdownMenu
+      size="sm"
+      items={LAYOUT_OPTIONS.map((option) => ({
+        id: option.value,
+        // A check on the active option; the icon stays leading. `color` highlights
+        // the active row. NOTE: DropdownMenu drops onClick for items with a custom
+        // `component`, so keep to label/icon/onClick here.
+        label: option.value === layout ? `${option.label}  ✓` : option.label,
+        icon: <option.Icon fontSize="small" />,
+        color: option.value === layout ? ("primary" as const) : undefined,
+        onClick: () => setLayout(option.value),
+      }))}
+      trigger={
+        <Button
+          variant="text"
+          size="sm"
+          color="secondary"
+          aria-label={`Exibição: ${active.label}`}
+          dataTestId={`${testIdPrefix}-layout-toggle`}
+        >
+          <Box component="span" sx={{ display: "inline-flex", alignItems: "center", gap: 0.25 }}>
+            <ActiveIcon fontSize="small" />
+            <KeyboardArrowDownRoundedIcon fontSize="small" />
+          </Box>
+        </Button>
+      }
+    />
+  );
+}
+
+/**
+ * Card-size slider for the toolbar — shown ONLY in the cards ("Grade") layout,
+ * mirroring the tabwoah view-selector's zoom. Adjusts the card grid's min column
+ * width so the shopper can pack more/larger cards. Renders nothing in the table
+ * layout or when cards aren't available.
+ */
+export function DataViewsZoomSlider({ testIdPrefix }: { testIdPrefix: string }): React.JSX.Element | null {
+  const { layout, canUseCards, zoom, setZoom } = useDataViewsLayout();
+  if (!canUseCards || layout !== "cards") return null;
+  return (
+    <Box
+      sx={{
+        display: { xs: "none", sm: "flex" },
+        alignItems: "center",
+        gap: 1,
+        color: "text.secondary",
+      }}
+    >
+      <GridViewOutlinedIcon sx={{ fontSize: 14 }} />
+      <Box sx={{ width: 88, display: "flex", alignItems: "center" }}>
+        <Slider
+          size="sm"
+          showValue={false}
+          value={zoom}
+          min={0}
+          max={100}
+          step={5}
+          onChange={(_event, next) => setZoom(Array.isArray(next) ? (next[0] ?? 0) : next)}
+          aria-label="Tamanho dos cards"
+          data-testid={`${testIdPrefix}-card-zoom`}
+        />
+      </Box>
+      <GridViewOutlinedIcon sx={{ fontSize: 20 }} />
+    </Box>
+  );
+}

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

@@ -0,0 +1,31 @@
+"use client";
+
+import { Box } from "../../../mui/Box";
+import { Pagination } from "../../navigation/Pagination";
+
+import type { DataViewsController } from "./use-data-views-state";
+
+/**
+ * The server-mode pagination control rendered beneath the grid — shown only
+ * when the table is backend-driven and there is more than one page. Client-mode
+ * tables render every matched row at once, so they never show it (FUT-180).
+ */
+export function DataViewsPagination<T extends Record<string, unknown>>({
+  c,
+  testIdPrefix,
+}: {
+  c: DataViewsController<T>;
+  testIdPrefix: string;
+}): React.JSX.Element | null {
+  if (!c.serverMode || c.serverPageCount <= 1) return null;
+  return (
+    <Box sx={{ mt: 2, display: "flex", justifyContent: "center" }}>
+      <Pagination
+        page={c.serverPage}
+        count={c.serverPageCount}
+        onChange={(_event, page) => c.changePage(page)}
+        dataTestId={`${testIdPrefix}-pagination`}
+      />
+    </Box>
+  );
+}

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

@@ -0,0 +1,53 @@
+import type {
+  DataViewColumn,
+  DataViewState,
+  FilterFieldConfig,
+} from "./data-views-types";
+
+/**
+ * Human-readable summary of a view state (FUT-89), used by the save-view modal's
+ * preview and the manage dialog. Pure + label-driven so it is unit-testable and
+ * shared. Returns empty arrays for sections with nothing set.
+ */
+interface ViewStateDescription {
+  filters: string[];
+  columns: string[];
+  sort: string[];
+}
+
+function columnLabel<T extends Record<string, unknown>>(
+  columns: DataViewColumn<T>[],
+  id: string,
+): string {
+  const col = columns.find((c) => c.id === id);
+  if (col && typeof col.header === "string" && col.header) return col.header;
+  return id;
+}
+
+export function describeViewState<T extends Record<string, unknown>>(
+  state: DataViewState,
+  fields: FilterFieldConfig<T>[],
+  columns: DataViewColumn<T>[],
+): ViewStateDescription {
+  const filters: string[] = [];
+  if (state.search.trim()) filters.push(`Busca: "${state.search.trim()}"`);
+  for (const field of fields) {
+    const selected = state.pills[field.id];
+    if (!selected || selected.length === 0) continue;
+    const labels = selected.map(
+      (value) => field.options.find((option) => option.value === value)?.label ?? value,
+    );
+    filters.push(`${field.label}: ${labels.join(", ")}`);
+  }
+
+  const hideable = columns.filter((col) => col.hideable !== false);
+  const columnsShown = hideable
+    .filter((col) => state.visibleColumns.includes(col.id))
+    .map((col) => columnLabel(columns, col.id));
+
+  const sort = state.sortBy
+    .filter((entry) => entry.dir)
+    .map((entry) => `${columnLabel(columns, entry.id)} (${entry.dir === "asc" ? "crescente" : "decrescente"})`);
+
+  return { filters, columns: columnsShown, sort };
+}