@12-apps/ui 1.0.0 → 1.3.1

package/src/components/data-display/DataViews/base-card.tsx

@@ -0,0 +1,278 @@
+"use client";
+
+import { type ReactNode } from "react";
+
+import type { SxProps, Theme } from "@mui/material/styles";
+
+import { Checkbox } from "../../form/Checkbox";
+import { Card } from "../../layout/Card";
+import { Box } from "../../../mui/Box";
+import { Text } from "../../typography/Text";
+
+import { CARD_ASPECT_RATIOS, type CardAspectRatio } from "./data-views-types";
+
+interface BaseCardProps {
+  /** Extra body content below the caption (chips, meta). Optional. */
+  children?: ReactNode;
+  /** Tile proportion. Defaults to "4:3". */
+  aspectRatio?: CardAspectRatio;
+  /**
+   * Size multiplier from the zoom slider (1 = base). Scales the card's padding +
+   * typography in step with its width (the grid sizes the track to base × scale),
+   * so the whole card grows together — a card at scale 2 renders at ~twice the
+   * size, its proportion preserved by `aspectRatio`. Default 1.
+   */
+  scale?: number;
+  /** Display-image node (e.g. an `<img>` / thumbnail) filling the media region. */
+  image?: ReactNode;
+  /** Shown centered in the media region when there is no `image` (icon/initial). */
+  imageFallback?: ReactNode;
+  /** First-class title, rendered in the caption. */
+  title?: ReactNode;
+  /** Secondary caption line under the title. */
+  subtitle?: ReactNode;
+  /** The 3-dots menu (or any action node) pinned to the top-right corner. */
+  menu?: ReactNode;
+  /** Whether this card is in the grid's selection. */
+  selected?: boolean;
+  /** Toggle this card's selection. Omit to hide the checkbox (non-selectable). */
+  onToggleSelect?: () => void;
+  /** Card click (e.g. open/edit). The checkbox/menu stop propagation. */
+  onClick?: () => void;
+  /** Visually de-emphasise (e.g. a disabled/hidden entity). */
+  dimmed?: boolean;
+  dataTestId?: string;
+  checkboxTestId?: string;
+}
+
+/** The outlined-tile style: fixed ratio, scaled padding, selected/dimmed states. */
+function cardSx(opts: {
+  aspectRatio: CardAspectRatio;
+  pad: number;
+  interactive: boolean;
+  dimmed: boolean;
+  selected: boolean;
+}): SxProps<Theme> {
+  const { aspectRatio, pad, interactive, dimmed, selected } = opts;
+  return {
+    position: "relative",
+    aspectRatio: String(CARD_ASPECT_RATIOS[aspectRatio]),
+    display: "flex",
+    flexDirection: "column",
+    overflow: "hidden",
+    p: pad,
+    transition: "border-color 120ms, box-shadow 120ms, background-color 120ms",
+    cursor: interactive ? "pointer" : undefined,
+    opacity: dimmed ? 0.6 : 1,
+    borderColor: selected ? "primary.main" : undefined,
+    boxShadow: selected ? (theme) => `inset 0 0 0 1px ${theme.palette.primary.main}` : undefined,
+    backgroundColor: selected ? "action.selected" : undefined,
+  };
+}
+
+/** The top-corner overlays: the select checkbox (left) and the menu slot (right). */
+function CardOverlays({
+  selected,
+  onToggleSelect,
+  checkboxTestId,
+  menu,
+}: Pick<BaseCardProps, "selected" | "onToggleSelect" | "checkboxTestId" | "menu">): React.JSX.Element {
+  return (
+    <>
+      {onToggleSelect && (
+        <Box sx={{ position: "absolute", top: 4, left: 4, zIndex: 2 }}>
+          <Checkbox
+            checked={selected}
+            onChange={() => onToggleSelect()}
+            // Selecting must never trigger the card's own click (open/edit).
+            onClick={(event) => event.stopPropagation()}
+            size="small"
+            data-testid={checkboxTestId}
+            aria-label="Selecionar"
+          />
+        </Box>
+      )}
+      {menu && (
+        <Box
+          sx={{ position: "absolute", top: 4, right: 4, zIndex: 2 }}
+          // Acting on the menu must never trigger the card's own click.
+          onClick={(event) => event.stopPropagation()}
+        >
+          {menu}
+        </Box>
+      )}
+    </>
+  );
+}
+
+/**
+ * Media region: fills the tile above the caption; centers `imageFallback` when
+ * there is no image so title-only entities still fill the ratio box and mixed
+ * grids stay aligned.
+ */
+function CardMedia({ image, imageFallback }: Pick<BaseCardProps, "image" | "imageFallback">): React.JSX.Element {
+  return (
+    <Box
+      sx={{
+        flex: 1,
+        minHeight: 0,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        overflow: "hidden",
+        borderRadius: 1,
+        "& img": { width: "100%", height: "100%", objectFit: "cover" },
+      }}
+    >
+      {image ?? imageFallback}
+    </Box>
+  );
+}
+
+/** The body slot (chips/meta); fills remaining space when there is no media. */
+function CardBodyContent({
+  children,
+  fill,
+  scale,
+  topGap,
+}: {
+  children: ReactNode;
+  fill: boolean;
+  scale: number;
+  topGap: number;
+}): React.JSX.Element {
+  return (
+    <Box
+      sx={{
+        flex: fill ? 1 : "none",
+        minHeight: 0,
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        justifyContent: "center",
+        gap: 0.75 * scale,
+        mt: topGap,
+        overflow: "hidden",
+      }}
+    >
+      {children}
+    </Box>
+  );
+}
+
+/** The title/subtitle caption. */
+function CardCaption({
+  title,
+  subtitle,
+  scale,
+  topGap,
+}: {
+  title?: ReactNode;
+  subtitle?: ReactNode;
+  scale: number;
+  topGap: number;
+}): React.JSX.Element {
+  return (
+    <Box sx={{ mt: topGap, minWidth: 0 }}>
+      {title != null && (
+        <Text
+          variant="heading"
+          size="sm"
+          weight="bold"
+          as="p"
+          style={{
+            lineHeight: 1.15,
+            fontSize: `${0.95 * scale}rem`,
+            overflow: "hidden",
+            textOverflow: "ellipsis",
+            whiteSpace: "nowrap",
+          }}
+        >
+          {title}
+        </Text>
+      )}
+      {subtitle != null && (
+        <Text variant="caption" size="xs" color="secondary" as="p">
+          {subtitle}
+        </Text>
+      )}
+    </Box>
+  );
+}
+
+/** The stacked media / body / caption slots inside the tile (below the overlays). */
+function CardContents({
+  children,
+  image,
+  imageFallback,
+  title,
+  subtitle,
+  scale,
+  pad,
+}: Pick<BaseCardProps, "children" | "image" | "imageFallback" | "title" | "subtitle"> & {
+  scale: number;
+  pad: number;
+}): React.JSX.Element {
+  const hasMedia = image != null || imageFallback != null;
+  const hasBody = children != null;
+  const hasCaption = title != null || subtitle != null;
+  const gap = pad * 0.5;
+  return (
+    <>
+      {hasMedia && <CardMedia image={image} imageFallback={imageFallback} />}
+      {hasBody && (
+        <CardBodyContent fill={!hasMedia} scale={scale} topGap={hasMedia ? gap : 0}>
+          {children}
+        </CardBodyContent>
+      )}
+      {hasCaption && (
+        <CardCaption
+          title={title}
+          subtitle={subtitle}
+          scale={scale}
+          topGap={hasMedia || hasBody ? gap : 0}
+        />
+      )}
+    </>
+  );
+}
+
+/**
+ * Reusable selectable card shell for the DataViews "Grade" (cards) layout, and
+ * the ONLY card component that lives in `@12-apps/ui` — every domain "kind card"
+ * (product, mesa, role, …) lives in the app and composes this envelope. See the
+ * per-slot helpers above; this shell just assembles them within a fixed-ratio
+ * tile. Reads no context, so it renders standalone as well as inside the grid.
+ */
+export function BaseCard(props: BaseCardProps): React.JSX.Element {
+  const { aspectRatio = "4:3", scale = 1, selected = false, dimmed = false } = props;
+  const { menu, onToggleSelect, onClick, dataTestId, checkboxTestId } = props;
+  const pad = 1.5 * scale;
+
+  return (
+    <Card
+      variant="outlined"
+      borderRadius="lg"
+      onClick={onClick}
+      dataTestId={dataTestId}
+      sx={cardSx({ aspectRatio, pad, interactive: onClick != null, dimmed, selected })}
+    >
+      <CardOverlays
+        selected={selected}
+        onToggleSelect={onToggleSelect}
+        checkboxTestId={checkboxTestId}
+        menu={menu}
+      />
+      <CardContents
+        image={props.image}
+        imageFallback={props.imageFallback}
+        title={props.title}
+        subtitle={props.subtitle}
+        scale={scale}
+        pad={pad}
+      >
+        {props.children}
+      </CardContents>
+    </Card>
+  );
+}

package/src/components/data-display/DataViews/data-views-filter-panel.tsx

@@ -0,0 +1,184 @@
+"use client";
+
+import { Box, Link } from "@mui/material";
+
+import { StackedModal, StackedModalContent } from "../../feedback/StackedModal";
+import { MultiSelectDropdown } from "../../layout/ContentToolbar";
+import { TableFilter } from "../../layout/TableFilter";
+
+import { PanelRangeField } from "./data-views-range-pill";
+import type {
+  FilterFieldConfig,
+  RangeFieldConfig,
+  RangeValue,
+} from "./data-views-types";
+
+/* ── Filter panel ────────────────────────────────────────────────────────── */
+
+export interface GridFilterPanelProps<T extends Record<string, unknown>> {
+  testIdPrefix: string;
+  search: string;
+  fields: FilterFieldConfig<T>[];
+  rangeFields: RangeFieldConfig<T>[];
+  pills: Record<string, string[]>;
+  ranges: Record<string, RangeValue>;
+  onSearchChange: (value: string) => void;
+  onTogglePill: (fieldId: string, value: string, checked: boolean) => void;
+  onChangeRange: (fieldId: string, range: RangeValue) => void;
+  onClearField: (fieldId: string) => void;
+  onClearAll: () => void;
+}
+
+/** One pill field: a compact multi-select for long lists, else a checkbox list. */
+function PillField<T extends Record<string, unknown>>({
+  field,
+  selected,
+  testIdPrefix,
+  onTogglePill,
+  onClearField,
+}: {
+  field: FilterFieldConfig<T>;
+  selected: string[];
+  testIdPrefix: string;
+  onTogglePill: (fieldId: string, value: string, checked: boolean) => void;
+  onClearField: (fieldId: string) => void;
+}): React.JSX.Element {
+  const testId = `${testIdPrefix}-filter-${field.id}`;
+  // `searchEnabled` forces the searchable multi-select; a plain `multiselect`
+  // keeps the auto "search only when the list is long" rule.
+  if (field.searchEnabled || field.control === "multiselect") {
+    return (
+      <MultiSelectDropdown
+        label={field.label}
+        options={field.options}
+        selected={new Set(selected)}
+        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="stacked"
+        data-testid={testId}
+      />
+    );
+  }
+  return (
+    <TableFilter.CheckboxField
+      label={field.label}
+      options={field.options}
+      selected={new Set(selected)}
+      onToggle={(value, checked) => onTogglePill(field.id, value, checked)}
+      testId={testId}
+    />
+  );
+}
+
+/** The filter controls (keyword + pill facets + numeric ranges), surface-agnostic. */
+function FilterControls<T extends Record<string, unknown>>({
+  testIdPrefix,
+  search,
+  fields,
+  rangeFields,
+  pills,
+  ranges,
+  onSearchChange,
+  onTogglePill,
+  onChangeRange,
+  onClearField,
+}: Omit<GridFilterPanelProps<T>, "onClearAll">): React.JSX.Element {
+  return (
+    <>
+      <TableFilter.Keyword
+        value={search}
+        onChange={onSearchChange}
+        label="Buscar em todas as colunas"
+        placeholder="Pressione Enter para filtrar"
+        testId={`${testIdPrefix}-search-all`}
+      />
+      {(fields.length > 0 || rangeFields.length > 0) && (
+        <TableFilter.Section title="Filtros">
+          {fields.map((field) => (
+            <PillField
+              key={field.id}
+              field={field}
+              selected={pills[field.id] ?? []}
+              testIdPrefix={testIdPrefix}
+              onTogglePill={onTogglePill}
+              onClearField={onClearField}
+            />
+          ))}
+          {rangeFields.map((field) => (
+            <PanelRangeField
+              key={field.id}
+              field={field}
+              value={ranges[field.id] ?? {}}
+              onChange={(range) => onChangeRange(field.id, range)}
+              testId={`${testIdPrefix}-range-${field.id}`}
+            />
+          ))}
+        </TableFilter.Section>
+      )}
+    </>
+  );
+}
+
+/** The slide-in filter panel: keyword + checkbox facets + numeric ranges. */
+export function GridFilterPanel<T extends Record<string, unknown>>(
+  props: GridFilterPanelProps<T>,
+): React.JSX.Element {
+  return (
+    <TableFilter.Panel
+      onClearAll={props.onClearAll}
+      clearTestId={`${props.testIdPrefix}-clear-filters`}
+      ariaLabel="Filtros"
+    >
+      <FilterControls {...props} />
+    </TableFilter.Panel>
+  );
+}
+
+/** Props for the modal filter surface used below the inline breakpoint. */
+interface FilterDialogProps<T extends Record<string, unknown>> extends GridFilterPanelProps<T> {
+  open: boolean;
+  onClose: () => void;
+}
+
+/**
+ * The same filter controls in a centered modal — used on smaller screens where the
+ * slide-in panel would overlap the table. The "Filtros" toolbar button opens it.
+ */
+export function FilterDialog<T extends Record<string, unknown>>({
+  open,
+  onClose,
+  ...props
+}: FilterDialogProps<T>): React.JSX.Element {
+  return (
+    <StackedModal
+      open={open}
+      onClose={onClose}
+      navigationTitle="Filtros"
+      modalId={`${props.testIdPrefix}-filters`}
+      maxWidth="xs"
+      dataTestId={`${props.testIdPrefix}-filter-dialog`}
+    >
+      <StackedModalContent>
+        <Box sx={{ display: "flex", flexDirection: "column", gap: 2.5 }}>
+          <Box sx={{ display: "flex", justifyContent: "flex-end" }}>
+            <Link
+              component="button"
+              type="button"
+              underline="hover"
+              onClick={props.onClearAll}
+              data-testid={`${props.testIdPrefix}-clear-filters`}
+              sx={{ fontSize: "0.75rem", color: "text.secondary" }}
+            >
+              Clear All Filters
+            </Link>
+          </Box>
+          <FilterControls {...props} />
+        </Box>
+      </StackedModalContent>
+    </StackedModal>
+  );
+}

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

@@ -0,0 +1,138 @@
+import type { GridColumn } from "../DataGrid";
+
+import type {
+  DataViewColumn,
+  FilterFieldConfig,
+  RangeFieldConfig,
+  RangeValue,
+} from "./data-views-types";
+
+/**
+ * Pure filtering for the DataViews table (FUT-88) — kept out of the component so
+ * the search + pill semantics are unit-testable in isolation. The grid does its
+ * own sorting + column hiding; this narrows the row set (and drives the "showing
+ * X of Y" counter), so all filtering lives here in one place.
+ */
+
+/** Resolve a column's raw value for a row (function accessor, key, or id fallback). */
+function resolveColumnValue<T extends Record<string, unknown>>(
+  row: T,
+  col: Pick<GridColumn<T>, "accessor" | "id">,
+): unknown {
+  const { accessor, id } = col;
+  if (typeof accessor === "function") return accessor(row);
+  if (accessor) return row[accessor];
+  return row[id as keyof T];
+}
+
+function matchesSearch<T extends Record<string, unknown>>(
+  row: T,
+  searchableColumns: DataViewColumn<T>[],
+  term: string,
+): boolean {
+  if (!term) return true;
+  const q = term.trim().toLowerCase();
+  if (!q) return true;
+  return searchableColumns.some((col) => {
+    const value = resolveColumnValue(row, col);
+    return value != null && String(value).toLowerCase().includes(q);
+  });
+}
+
+function matchesPills<T extends Record<string, unknown>>(
+  row: T,
+  fields: FilterFieldConfig<T>[],
+  pills: Record<string, string[]>,
+): boolean {
+  return fields.every((field) => {
+    const selected = pills[field.id];
+    if (!selected || selected.length === 0) return true;
+    const raw = field.accessor ? field.accessor(row) : row[field.id];
+    const values = Array.isArray(raw) ? raw.map((v) => String(v)) : [String(raw ?? "")];
+    return values.some((value) => selected.includes(value));
+  });
+}
+
+/**
+ * Is this range an active filter? A missing range, one with no bounds, or an
+ * inverted one (max < min, which is invalid) is inactive — an inactive range
+ * never filters anything out; the UI surfaces the inverted case as an error.
+ */
+function isRangeActive(range: RangeValue | undefined): range is RangeValue {
+  if (!range || (range.min == null && range.max == null)) return false;
+  if (range.min != null && range.max != null) {
+    const order = compareBounds(range.max, range.min);
+    if (order !== null && order < 0) return false;
+  }
+  return true;
+}
+
+/**
+ * Order two bounds of the SAME range. A field's bounds are always one kind —
+ * both numbers, or both `AAAA-MM-DD` days, which sort correctly as strings.
+ * Mixed kinds are not comparable and return null, which every caller reads as
+ * "this bound constrains nothing" rather than silently ordering them wrong.
+ */
+function compareBounds(a: number | string, b: number | string): number | null {
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "string" && typeof b === "string") return a < b ? -1 : a > b ? 1 : 0;
+  return null;
+}
+
+/**
+ * Is `value` on the allowed side of ONE bound? `direction` is +1 for a lower
+ * bound (value must be at or above it) and -1 for an upper one. An absent bound
+ * constrains nothing; an incomparable pair excludes the row rather than
+ * quietly admitting it.
+ */
+function withinBound(
+  value: number | string,
+  bound: number | string | undefined,
+  direction: 1 | -1,
+): boolean {
+  if (bound == null) return true;
+  const order = compareBounds(value, bound);
+  return order !== null && order * direction >= 0;
+}
+
+/** Does one value satisfy a single (possibly one-sided) range? */
+function rangeAllows(
+  range: RangeValue | undefined,
+  value: number | string | null | undefined,
+): boolean {
+  if (!isRangeActive(range)) return true;
+  // A row without a comparable value can't satisfy a bounded range.
+  if (value == null || (typeof value === "number" && Number.isNaN(value))) return false;
+  return withinBound(value, range.min, 1) && withinBound(value, range.max, -1);
+}
+
+/** Does the row fall within every bounded range? */
+function matchesRanges<T extends Record<string, unknown>>(
+  row: T,
+  rangeFields: RangeFieldConfig<T>[],
+  ranges: Record<string, RangeValue>,
+): boolean {
+  return rangeFields.every((field) => rangeAllows(ranges[field.id], field.accessor(row)));
+}
+
+/**
+ * The rows matching the current search + pill selections + numeric ranges
+ * (order unchanged). `rangeFields` is optional so existing multi-select-only
+ * tables call this unchanged.
+ */
+export function filterRows<T extends Record<string, unknown>>(
+  rows: T[],
+  columns: DataViewColumn<T>[],
+  fields: FilterFieldConfig<T>[],
+  criteria: { search: string; pills: Record<string, string[]>; ranges?: Record<string, RangeValue> },
+  rangeFields: RangeFieldConfig<T>[] = [],
+): T[] {
+  const searchable = columns.filter((col) => col.searchable);
+  const ranges = criteria.ranges ?? {};
+  return rows.filter(
+    (row) =>
+      matchesSearch(row, searchable, criteria.search) &&
+      matchesPills(row, fields, criteria.pills) &&
+      matchesRanges(row, rangeFields, ranges),
+  );
+}