@12-apps/ui 1.0.0 → 1.3.0

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

@@ -0,0 +1,312 @@
+import type { GridColumn, GridSort } from "../DataGrid";
+import type { DropdownMenuItem } from "../../navigation/DropdownMenu";
+
+/**
+ * Shared types for the reusable admin "DataViews" table (FUT-88): a filter bar
+ * (search-across-all + typed multi-select pills + column visibility) whose full
+ * state — filters + sort + visible columns — a saved view (FUT-89) can capture
+ * and restore. Each table declares its own columns + filter fields.
+ */
+
+/**
+ * A single, reusable row action. ONE definition drives BOTH the per-row "⋮"
+ * kebab menu and the bulk-actions menu (tabwoah model): `onSelect` receives the
+ * affected rows — `[row]` from a kebab, the whole selection from the bulk menu.
+ * Single-item-only actions (e.g. "Editar") set `bulk: false` so they never
+ * appear in the bulk menu.
+ */
+export interface RowAction<T extends Record<string, unknown>> {
+  /** Stable id (also the `data-testid` suffix). */
+  id: string;
+  /** Menu label. In the kebab, `rowLabel` overrides it per row when provided. */
+  label: string;
+  /** Menu-item colour (e.g. `"error"` for destructive). */
+  color?: DropdownMenuItem["color"];
+  /**
+   * Runs on the affected rows: `[row]` from the kebab, all selected from bulk.
+   * May be async — the bulk menu awaits it and only clears the selection once it
+   * settles (keeping the selection on failure so the user can retry).
+   */
+  onSelect: (rows: T[]) => void | Promise<void>;
+  /** Include in the bulk menu (2+ selected). Defaults to `true`. */
+  bulk?: boolean;
+  /** Include in the per-row kebab. Defaults to `true`. */
+  row?: boolean;
+  /** Per-row kebab label (e.g. `row.active ? "Inativar" : "Ativar"`). */
+  rowLabel?: (row: T) => string;
+  /**
+   * Per-row applicability (e.g. state-machine guards). `false` hides the
+   * kebab item for that row; in bulk the action runs only on the passing
+   * rows and is dropped when none pass. Defaults to applicable.
+   */
+  isVisible?: (row: T) => boolean;
+}
+
+/** Selection state handed to a card renderer so it can drive its own checkbox. */
+export interface DataViewCardSelection {
+  selected: boolean;
+  onToggleSelect: () => void;
+  /**
+   * Card SIZE multiplier from the toolbar zoom slider. The grid sizes the card's
+   * width to `base × scale`; a card passes this to {@link BaseCard} `scale` so its
+   * padding + typography grow by the same factor — the whole card scales together
+   * (scale 2 → ~2× size). The proportion (aspect ratio) stays constant.
+   */
+  scale: number;
+}
+
+/**
+ * The fixed proportions a {@link BaseCard} tile can take. The tile keeps this
+ * ratio and grows in BOTH width and height as the zoom slider widens its grid
+ * track, so a grid of cards stays visually uniform.
+ */
+export type CardAspectRatio = "1:1" | "4:3" | "16:9" | "9:16" | "3:4";
+
+/** Numeric width/height factor for each {@link CardAspectRatio} (CSS `aspect-ratio`). */
+export const CARD_ASPECT_RATIOS: Record<CardAspectRatio, number> = {
+  "1:1": 1,
+  "4:3": 4 / 3,
+  "16:9": 16 / 9,
+  "9:16": 9 / 16,
+  "3:4": 3 / 4,
+};
+
+/** One selectable value inside a filter pill. */
+export interface FilterOption {
+  value: string;
+  label: string;
+}
+
+/** A typed, multi-select filter pill's configuration for a table. */
+export interface FilterFieldConfig<T extends Record<string, unknown>> {
+  /** Stable id; also the default row key when no `accessor` is given. */
+  id: string;
+  label: string;
+  options: FilterOption[];
+  /**
+   * How the field renders in the filter panel. `checkboxes` (default) is best for
+   * a few fixed options; `multiselect` is a compact dropdown for long option
+   * lists (e.g. many categories).
+   */
+  control?: "checkboxes" | "multiselect";
+  /**
+   * Forces this filter to render as a searchable multi-select dropdown with the
+   * search box always shown, regardless of how many options are currently
+   * loaded. Use it when the option set can grow unbounded (e.g. a filter backed
+   * by a relation such as Roles or Categories). Omit it for a closed value set
+   * (an enum), which keeps the plain checkbox / "search only when long"
+   * behavior.
+   */
+  searchEnabled?: boolean;
+  /**
+   * Reads the row's value(s) for this field. A row matches the pill when any of
+   * its values is selected. Defaults to `String(row[id])`.
+   */
+  accessor?: (row: T) => string | string[];
+}
+
+/**
+ * A selected range for a range filter (either bound optional). Numbers for a
+ * `number` field; `AAAA-MM-DD` day strings for a `day` one — which compare
+ * correctly with `<`/`>` precisely because ISO days sort lexicographically.
+ */
+export interface RangeValue {
+  min?: number | string;
+  max?: number | string;
+}
+
+/** What a range field measures — the input it renders and the bound it stores. */
+export type RangeFieldKind = "number" | "day";
+
+interface RangeFieldBase {
+  /** Stable id; the key under `DataViewState.ranges`. */
+  id: string;
+  label: string;
+}
+
+/** "Filter by amount": price, stock, margin, order total. */
+export interface NumberRangeFieldConfig<T extends Record<string, unknown>> extends RangeFieldBase {
+  kind?: "number";
+  /** Reads the row's numeric value for this range. */
+  accessor: (row: T) => number | null | undefined;
+  /** Optional unit suffix shown next to the inputs (e.g. "R$", "un"). */
+  unit?: string;
+  /** Numeric input step. Defaults to 1. */
+  step?: number;
+}
+
+/**
+ * "Filter by period": a pair of INCLUSIVE calendar days, rendered as two native
+ * date inputs. Inclusive is the reason a day range is its own kind rather than a
+ * number over timestamps — coercing an `até` of `2026-07-15` to a instant lands
+ * on that day's midnight and drops the whole final day (FUT-668).
+ */
+export interface DayRangeFieldConfig<T extends Record<string, unknown>> extends RangeFieldBase {
+  kind: "day";
+  /** Reads the row's `AAAA-MM-DD` day for this range. */
+  accessor: (row: T) => string | null | undefined;
+}
+
+/**
+ * A min/max range filter's configuration. Complements the multi-select pills.
+ * A row with a null/undefined value never matches a bounded range.
+ */
+export type RangeFieldConfig<T extends Record<string, unknown>> =
+  | NumberRangeFieldConfig<T>
+  | DayRangeFieldConfig<T>;
+
+/** A grid column that can join the search scan and the column-visibility menu. */
+export interface DataViewColumn<T extends Record<string, unknown>> extends GridColumn<T> {
+  /** Included in "search across all columns" (needs a resolvable value). */
+  searchable?: boolean;
+  /** Toggleable in the column-visibility menu. Defaults to true; set false for
+   *  structural columns (image thumbnail, actions kebab) that must always show. */
+  hideable?: boolean;
+}
+
+/** The full, serializable state a view captures. */
+export interface DataViewState {
+  /** Free text matched across every `searchable` column. */
+  search: string;
+  /** fieldId → selected option values (empty/absent = no constraint). */
+  pills: Record<string, string[]>;
+  /** fieldId → selected numeric range (min/max). Absent/empty = no constraint. */
+  ranges?: Record<string, RangeValue>;
+  sortBy: GridSort[];
+  /** Column ids kept visible; a hideable column not listed here is hidden. */
+  visibleColumns: string[];
+}
+
+/** A pristine view state showing every given column and no filters/sort. */
+export function emptyViewState(visibleColumns: string[]): DataViewState {
+  return { search: "", pills: {}, ranges: {}, sortBy: [], visibleColumns };
+}
+
+/**
+ * The URL-driven slice of {@link DataViewState} — the controls a server-mode host
+ * mirrors from the address bar (search / pills / ranges / sort), WITHOUT
+ * `visibleColumns`. Supplying it re-applies those controls when its reference
+ * changes (e.g. browser back/forward or a deep-link on the same route), merging
+ * over the current state so a user's show/hide column choices are preserved —
+ * unlike `appliedState`, which fully replaces the state to apply a saved view.
+ */
+export type DataViewSyncState = Pick<DataViewState, "search" | "pills" | "ranges" | "sortBy">;
+
+/**
+ * The query a SERVER-mode table emits whenever its filter/sort/page changes
+ * (FUT-180). The host translates this into a backend request (see
+ * `@12-apps/shared-helpers/search`) — in server mode the grid never filters,
+ * sorts, or paginates in the browser; it renders exactly the page the server
+ * returned. `page` is 1-based to match the backend contract.
+ */
+export interface DataViewQuery {
+  search: string;
+  pills: Record<string, string[]>;
+  ranges: Record<string, RangeValue>;
+  sortBy: GridSort[];
+  page: number;
+  pageSize: number;
+}
+
+/**
+ * Server-mode wiring for a DataViews table. Its PRESENCE flips the table from
+ * in-browser filtering/sorting/pagination to backend-driven: the rows handed in
+ * are already the current page, `totalCount` is the unpaginated total, and
+ * `onQueryChange` fires (search debounced by the host) whenever the user changes
+ * a filter, the sort, or the page. This is the ONLY way an admin list should run
+ * (see the app-side `DataViewsTable` wrapper, which requires it).
+ */
+export interface DataViewServer {
+  /** Total matched rows across all pages (drives the counter + page count). */
+  totalCount: number;
+  /** Current 1-based page. */
+  page: number;
+  /** Rows per page. */
+  pageSize: number;
+  /** Fired when the effective query changes; the host re-fetches the page. */
+  onQueryChange: (query: DataViewQuery) => void;
+}
+
+/**
+ * Coerce an opaque persisted state (a saved view's JSON) into a valid
+ * DataViewState, filling any missing part with a sane default. Guards against
+ * legacy/older shapes so applying a saved view never renders an empty grid.
+ */
+export function coerceViewState(raw: unknown, allColumnIds: string[]): DataViewState {
+  const value = (raw ?? {}) as Partial<DataViewState>;
+  return {
+    search: typeof value.search === "string" ? value.search : "",
+    pills:
+      value.pills && typeof value.pills === "object"
+        ? (value.pills as Record<string, string[]>)
+        : {},
+    ranges:
+      value.ranges && typeof value.ranges === "object"
+        ? (value.ranges as Record<string, RangeValue>)
+        : {},
+    sortBy: Array.isArray(value.sortBy) ? value.sortBy : [],
+    visibleColumns: Array.isArray(value.visibleColumns) ? value.visibleColumns : allColumnIds,
+  };
+}
+
+/** A saved view as consumed by the DataViews UI (FUT-89), with ownership flag. */
+export interface SavedViewSummary {
+  id: string;
+  name: string;
+  description: string | null;
+  state: DataViewState;
+  shared: boolean;
+  pinned: boolean;
+  isDefault: boolean;
+  /** True when the current user owns the view (may edit/delete/pin/share it). */
+  isOwner: boolean;
+}
+
+/** A saved-view repository record (opaque `state`), as returned to server pages. */
+interface SavedViewRecordLike {
+  id: string;
+  name: string;
+  description: string | null;
+  state: unknown;
+  shared: boolean;
+  pinned: boolean;
+  isDefault: boolean;
+  isOwner: boolean;
+}
+
+/** Map a repository record to the client summary (opaque state → DataViewState). */
+export function toSavedViewSummary(record: SavedViewRecordLike): SavedViewSummary {
+  return { ...record, state: (record.state ?? {}) as DataViewState };
+}
+
+/**
+ * Dependency-injection contracts for the framework-agnostic DataViewsTableBase:
+ * the host app supplies saved-view persistence + router side-effects so the ui
+ * component imports neither a backend (server actions) nor a framework router.
+ */
+
+/** A saved view's editable fields, as the host persists them. */
+export interface DataViewSaveInput {
+  name: string;
+  description: string;
+  state: DataViewState;
+  shared: boolean;
+  pinned: boolean;
+  isDefault: boolean;
+}
+
+/** Result of a persistence call — mirrors the app's `Result` without importing it. */
+export type DataViewMutationResult = { ok: true } | { ok: false; error: string };
+
+/** Injected saved-view persistence (create/update/delete), wired by the host. */
+export interface DataViewPersistence {
+  create: (input: DataViewSaveInput) => Promise<DataViewMutationResult>;
+  update: (id: string, input: DataViewSaveInput) => Promise<DataViewMutationResult>;
+  remove: (id: string) => Promise<DataViewMutationResult>;
+}
+
+/** Injected router side-effects: sync the `?view=` param and re-fetch on change. */
+export interface DataViewRouter {
+  syncViewParam: (viewId: string | null) => void;
+  refresh: () => void;
+}

package/src/components/data-display/DataViews/data-views-view-mutations.ts

@@ -0,0 +1,68 @@
+"use client";
+
+import type { MutableRefObject } from "react";
+
+import type {
+  DataViewPersistence,
+  DataViewSaveInput,
+  DataViewState,
+  SavedViewSummary,
+} from "./data-views-types";
+import { type SaveViewPayload } from "./SaveViewModal";
+
+export interface ViewMutations {
+  handleSave: (payload: SaveViewPayload) => Promise<void>;
+  patchView: (
+    view: SavedViewSummary,
+    changes: Partial<Pick<SavedViewSummary, "isDefault" | "pinned" | "shared">>,
+  ) => Promise<void>;
+  handleDelete: (view: SavedViewSummary) => Promise<void>;
+}
+
+/** The SavedView persistence handlers (create/update/delete), via injected `persistence`. */
+export function useViewMutations(
+  persistence: DataViewPersistence,
+  editing: SavedViewSummary | null,
+  currentRef: MutableRefObject<DataViewState>,
+  onDone: (ok: boolean, error?: string) => void,
+): ViewMutations {
+  async function handleSave(payload: SaveViewPayload): Promise<void> {
+    const state = editing ? editing.state : currentRef.current;
+    const input: DataViewSaveInput = {
+      name: payload.name,
+      description: payload.description,
+      state,
+      shared: payload.shared,
+      pinned: payload.pinned,
+      isDefault: payload.isDefault,
+    };
+    const result = editing ? await persistence.update(editing.id, input) : await persistence.create(input);
+    // Fail loudly on a rejected save (e.g. duplicate name) so the modal stays
+    // open and shows the error instead of closing as if it succeeded.
+    if (!result.ok) throw new Error(result.error);
+    onDone(true);
+  }
+
+  async function patchView(
+    view: SavedViewSummary,
+    changes: Partial<Pick<SavedViewSummary, "isDefault" | "pinned" | "shared">>,
+  ): Promise<void> {
+    const next = { ...view, ...changes };
+    const result = await persistence.update(view.id, {
+      name: next.name,
+      description: next.description ?? "",
+      state: next.state,
+      shared: next.shared,
+      pinned: next.pinned,
+      isDefault: next.isDefault,
+    });
+    onDone(result.ok, result.ok ? undefined : result.error);
+  }
+
+  async function handleDelete(view: SavedViewSummary): Promise<void> {
+    const result = await persistence.remove(view.id);
+    onDone(result.ok, result.ok ? undefined : result.error);
+  }
+
+  return { handleSave, patchView, handleDelete };
+}

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

@@ -0,0 +1,33 @@
+/**
+ * DataViews — the reusable admin table/grid machinery (FUT-88/89): a filter bar,
+ * saved views, sort, column visibility, select-all + bulk actions, and an opt-in
+ * "Grade" (cards) layout. Framework-agnostic: {@link DataViewsTableBase} takes its
+ * saved-view persistence + router side-effects as injected props, so a host app
+ * wires them to its backend and framework router.
+ */
+export { BaseCard } from "./base-card";
+export { DataViewsGrid } from "./DataViewsGrid";
+export { DataViewsTableBase, type DataViewsTableBaseProps } from "./DataViewsTableBase";
+export { toSavedViewSummary, CARD_ASPECT_RATIOS } from "./data-views-types";
+export { cardScaleForZoom, cardMinWidthForZoom } from "./data-views-layout-context";
+export type {
+  RowAction,
+  DataViewCardSelection,
+  CardAspectRatio,
+  SavedViewSummary,
+  DataViewState,
+  DataViewSyncState,
+  DataViewColumn,
+  FilterFieldConfig,
+  RangeFieldConfig,
+  RangeFieldKind,
+  RangeValue,
+  NumberRangeFieldConfig,
+  DayRangeFieldConfig,
+  DataViewPersistence,
+  DataViewRouter,
+  DataViewSaveInput,
+  DataViewMutationResult,
+  DataViewQuery,
+  DataViewServer,
+} from "./data-views-types";