@12-apps/ui 1.6.3 → 1.8.0

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

@@ -5,7 +5,7 @@ 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.
+ * SCOPES — a page-level partition rendered as a strip of tabs under 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
@@ -302,7 +302,7 @@ const STRIP_SX = {
 } as const;
 
 /**
- * The scope strip: a horizontally scrolling tab list above the toolbar.
+ * The scope strip: a horizontally scrolling tab list under 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

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

@@ -15,6 +15,21 @@ import { Box } from "../../../mui/Box";
 /** How long the box waits after the last keystroke before it queries. */
 const SEARCH_DEBOUNCE_MS = 350;
 
+/**
+ * How wide the keyword box is allowed to be.
+ *
+ * The 200px floor is right while the box shares the row: a search you cannot
+ * read six characters in is not a search. It is WRONG once the box has been
+ * expanded out of its collapsed state on a narrow screen, where the cluster was
+ * sized for a magnifier — the floor cannot be met there, so the row scrolled
+ * sideways instead (154px of overhang at 320px). In that mode the box shrinks,
+ * and if what is left would still be unreadable the bar hands it the whole
+ * cluster instead (`searchTakeover`).
+ */
+function boxWidth(fill: boolean): { flex: number; minWidth: number; maxWidth: number | "none" } {
+  return { flex: 1, minWidth: fill ? 0 : 200, maxWidth: fill ? "none" : 384 };
+}
+
 /**
  * The bar's keyword box.
  *
@@ -34,6 +49,7 @@ export function InlineKeyword({
   testId,
   autoFocus,
   onEscape,
+  fill = false,
 }: {
   value: string;
   onChange: (value: string) => void;
@@ -41,6 +57,8 @@ export function InlineKeyword({
   autoFocus?: boolean;
   /** Called on Escape with the box already empty — the collapsed bar closes it. */
   onEscape?: () => void;
+  /** Take whatever width there is, with no minimum — see {@link boxWidth}. */
+  fill?: boolean;
 }): React.JSX.Element {
   const [draft, setDraft] = useState(value);
   const prev = useRef(value);
@@ -98,7 +116,7 @@ export function InlineKeyword({
       }}
       // 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 }}
+      sx={boxWidth(fill)}
     />
   );
 }

package/src/components/data-display/DataViews/data-views-shell-toolbar.tsx

@@ -25,6 +25,7 @@ export function ShellToolbar<T extends Record<string, unknown>>({
   toolbarRightSlot,
   showInline,
   compactControls,
+  counterHidden,
   sortKinds,
   displayView,
   exportConfig,
@@ -46,6 +47,8 @@ export function ShellToolbar<T extends Record<string, unknown>>({
   showInline: boolean;
   /** Step 2 of the ladder: Exibir/Exportar as icons only. */
   compactControls?: boolean;
+  /** Step 5, last resort: drop the counter so the row still fits one line. */
+  counterHidden?: boolean;
 }): React.JSX.Element {
   const columnOptions: ColumnVisibilityOption[] = c.hideableColumns.map((col) => ({
     id: col.id,
@@ -61,6 +64,7 @@ export function ShellToolbar<T extends Record<string, unknown>>({
       filterControls={filterControls}
       barRef={barRef}
       compactControls={compactControls}
+      counterHidden={counterHidden}
       testIdPrefix={testIdPrefix}
       selectedRows={c.selectedRows}
       selectAll={c.selectAll}

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

@@ -60,6 +60,12 @@ export interface GridToolbarProps<T extends Record<string, unknown>> {
    * has already given them up.
    */
   compactControls?: boolean;
+  /**
+   * Step 5 of the ladder, and its floor: on a screen too narrow for even the
+   * fully-collapsed row, the counter is dropped so the controls still fit one
+   * line instead of spilling outside the toolbar.
+   */
+  counterHidden?: boolean;
 }
 
 /** The right-aligned toolbar controls: Sort By, the counter, zoom/layout/columns, filters. */
@@ -67,27 +73,31 @@ function ToolbarRightControls<T extends Record<string, unknown>>(props: GridTool
   const { testIdPrefix, matchedCount, totalCount, filterOpen, setFilterOpen } = props;
   return (
     <>
-      <Text variant="caption" as="span">
-        {/* Always rendered, never breakpointed: `RESERVED.counter` already
-            prices it into the collapse ladder, so hiding it at `md` was the
-            ladder and a breakpoint disagreeing about the same pixels — which
-            is what broke the row at exactly 900px. */}
-        <Box
-          component="span"
-          data-testid={`${testIdPrefix}-counter`}
-          sx={{ whiteSpace: "nowrap" }}
-        >
-          {matchedCount} de {totalCount}
-        </Box>
-      </Text>
-      {/* Divides the READING of the list from the controls that change it —
-          the counter states what is on screen, everything right of here acts
-          on it. */}
-      <Divider
-        orientation="vertical"
-        flexItem
-        sx={{ height: 20, alignSelf: "center", mx: 0.5 }}
-      />
+      {/* MEASURED, never breakpointed: `RESERVED.counter` prices it into the
+          ladder, so hiding it at `md` was the ladder and a breakpoint
+          disagreeing about the same pixels — which broke the row at exactly
+          900px. It is dropped only as the ladder's last rung. */}
+      {!props.counterHidden && (
+        <>
+          <Text variant="caption" as="span">
+            <Box
+              component="span"
+              data-testid={`${testIdPrefix}-counter`}
+              sx={{ whiteSpace: "nowrap" }}
+            >
+              {matchedCount} de {totalCount}
+            </Box>
+          </Text>
+          {/* Divides the READING of the list from the controls that change it —
+              the counter states what is on screen, everything right of here
+              acts on it. */}
+          <Divider
+            orientation="vertical"
+            flexItem
+            sx={{ height: 20, alignSelf: "center", mx: 0.5 }}
+          />
+        </>
+      )}
       {props.toolbarRightSlot}
       {/* Sort + columns + format, in ONE control — see DataViewsDisplayPanel. */}
       <DataViewsDisplayPanel

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

@@ -1,5 +1,8 @@
 import type { GridColumn, GridSort } from "../DataGrid";
 import type { DropdownMenuItem } from "../../navigation/DropdownMenu";
+// A re-export does not bring the name into local scope, and the state/query
+// types below are written in terms of it.
+import type { RangeValue } from "./data-views-range-types";
 
 /**
  * Shared types for the reusable admin "DataViews" table (FUT-88): a filter bar
@@ -106,54 +109,18 @@ export interface FilterFieldConfig<T extends Record<string, unknown>> {
 }
 
 /**
- * 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.
+ * The range types live in `data-views-range-types` (this file outgrew the
+ * size gate); they are re-exported here so `data-views-types` stays the one
+ * name every consumer imports the model from.
  */
-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>;
+export type {
+  DayRangeFieldConfig,
+  NumberRangeFieldConfig,
+  RangeFieldConfig,
+  RangeFieldKind,
+  RangePreset,
+  RangeValue,
+} from "./data-views-range-types";
 
 /** 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> {

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

@@ -6,6 +6,13 @@
  * wires them to its backend and framework router.
  */
 export { BaseCard } from "./base-card";
+export { BaseListCard, type BaseListCardProps } from "./base-list-card";
+export {
+  DragContainerProvider,
+  useDragItem,
+  type DragContainerValue,
+  type DragItemProps,
+} from "./data-views-drag";
 export { DataViewsGrid } from "./DataViewsGrid";
 export { DataViewsTableBase, type DataViewsTableBaseProps } from "./DataViewsTableBase";
 export { toSavedViewSummary, CARD_ASPECT_RATIOS, DATA_VIEWS_LAYOUTS } from "./data-views-types";
@@ -35,6 +42,7 @@ export type {
   RangeFieldConfig,
   RangeFieldKind,
   RangeValue,
+  RangePreset,
   NumberRangeFieldConfig,
   DayRangeFieldConfig,
   DataViewPersistence,

package/src/components/data-display/DataViews/list-card-rails.tsx

@@ -0,0 +1,141 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+
+import { Box } from "../../../mui/Box";
+import { DENSITY_ROW_PADDING, type DataViewsDensity } from "./data-views-layout-context";
+
+/**
+ * THE LIST OWNS THE COLUMNS, NOT THE ROW.
+ *
+ * Every row laying itself out with flex produces a list where nothing lines up.
+ * The caption takes `flex: 1` and shoves the rest right; the value sits after
+ * the meta cluster with the same gap as any other pair, so `MÉTODO PIX
+ * R$ 13,90` reads as one continuous run and the only unlabelled thing in the
+ * row is the number that matters most; and because the status chip's width
+ * varies with its text (`Pago` vs `Em aberto` vs `Cancelado`), the money jitters
+ * left and right on every row down the page.
+ *
+ * So the rails are declared ONCE, here, and each card is `grid-template-columns:
+ * subgrid` spanning them. One set of edges for the whole list, the value on its
+ * own rail, the status in a slot wide enough for the longest label it will ever
+ * hold. Adding a row cannot move the column.
+ *
+ * Subgrid needs the card to be a DIRECT child of this grid — no wrapper element
+ * between them, which is why the group renders its children bare.
+ */
+
+/** One rail. Fixed where alignment matters, flexible where it does not. */
+export interface ListRails {
+  /** Reserved even when nothing drags: toggling drag mode must not shift the list. */
+  drag: string;
+  /** Reserved even when nothing is selectable, for the same reason. */
+  select: string;
+  leading: string;
+  /** The one column that absorbs spare width. */
+  caption: string;
+  meta: string;
+  /** The value's own rail, with a fixed right edge. */
+  value: string;
+  /** Wide enough for the longest status this list holds. */
+  status: string;
+  actions: string;
+}
+
+const DEFAULT_RAILS: ListRails = {
+  drag: "auto",
+  select: "auto",
+  leading: "auto",
+  caption: "minmax(0, 1fr)",
+  meta: "auto",
+  // `max-content` on the value, so the rail is as wide as the widest amount in
+  // the list and no wider — a fixed px guess is either clipping or dead space.
+  value: "max-content",
+  status: "max-content",
+  actions: "auto",
+};
+
+interface ListRailsValue {
+  density: DataViewsDensity;
+  /** Whether the gutters are held open even when empty. */
+  reserveGutters: boolean;
+}
+
+const ListRailsContext = createContext<ListRailsValue | null>(null);
+
+/** Is this card inside a group that owns the rails? */
+export function useListRails(): ListRailsValue | null {
+  return useContext(ListRailsContext);
+}
+
+/** The column template, as one `grid-template-columns` value. */
+export function railsTemplate(rails: ListRails): string {
+  return [
+    rails.drag,
+    rails.select,
+    rails.leading,
+    rails.caption,
+    rails.meta,
+    rails.value,
+    rails.status,
+    rails.actions,
+  ].join(" ");
+}
+
+/** How many rails there are — the span a card claims. */
+export const RAIL_COUNT = 8;
+
+/**
+ * A list of {@link BaseListCard}s that share one set of columns.
+ *
+ * Also the natural home for the things a review pointed out belong to the list
+ * rather than the card: the density every row answers, and — when it lands —
+ * shift-click range selection and the single `aria-live` region a list needs
+ * (fifty polite live regions is a screen-reader nightmare, which is why the
+ * card no longer takes one).
+ */
+export function ListCardGroup({
+  children,
+  density = "cozy",
+  rails,
+  reserveGutters = true,
+  gap,
+  dataTestId,
+}: {
+  children: ReactNode;
+  density?: DataViewsDensity;
+  /** Override individual rails; anything omitted keeps its default. */
+  rails?: Partial<ListRails>;
+  /**
+   * Hold the drag and select gutters open even when nothing uses them.
+   *
+   * On by default: a selectable list and a read-only one should line up, and
+   * turning drag mode on should not shift every row sideways.
+   */
+  reserveGutters?: boolean;
+  /** Row gap. Defaults to the density's own spacing. */
+  gap?: number;
+  dataTestId?: string;
+}): React.JSX.Element {
+  const resolved = { ...DEFAULT_RAILS, ...rails };
+  return (
+    <ListRailsContext.Provider value={{ density, reserveGutters }}>
+      <Box
+        data-testid={dataTestId}
+        sx={{
+          // The query container for every row inside it — a row cannot be one
+          // itself and a subgrid at the same time (containment drops subgrid).
+          // Every row in a list is the same width anyway, so the group is the
+          // honest place to ask the question.
+          containerType: "inline-size",
+          display: "grid",
+          gridTemplateColumns: railsTemplate(resolved),
+          alignItems: "center",
+          rowGap: gap ?? DENSITY_ROW_PADDING[density],
+        }}
+      >
+        {children}
+      </Box>
+    </ListRailsContext.Provider>
+  );
+}

package/src/components/data-display/DataViews/pedidos.server.ts

@@ -0,0 +1,118 @@
+import type { DataViewQuery, RangeValue } from "./data-views-types";
+
+/**
+ * THE "SERVER" FOR THE PEDIDOS STORY.
+ *
+ * Server mode means the grid does not filter, sort or paginate — it emits the
+ * query and renders exactly the page it is handed back. A story that wires
+ * `onQueryChange` to a no-op spy therefore looks broken in a specific and
+ * misleading way: the pills apply, the counter never moves, and every row
+ * stays. The controls are working; there is simply nobody on the other end.
+ *
+ * So this is the other end. It is deliberately fenced into its own module and
+ * written the way the real endpoint is: it is the ONLY code allowed to narrow
+ * the dataset, and the story never reaches past `data`.
+ */
+
+/** The subset of a row this fake backend knows how to query. */
+export interface ServerRow extends Record<string, unknown> {
+  pedido: string;
+  cliente: string;
+  metodo: string;
+  pagamento: string;
+  situacao: string;
+  dataIso: string;
+  valor: number;
+}
+
+export interface ServerPage<T> {
+  data: T[];
+  totalCount: number;
+  /**
+   * Per-scope totals over search + pills + ranges, IGNORING the active scope —
+   * computed with it applied, every inactive tab reads zero.
+   */
+  scopeCounts: Record<string, number>;
+}
+
+/** A row matches a pill field when ANY selected value matches. */
+function matchesPills(row: ServerRow, pills: Record<string, string[]>): boolean {
+  return Object.entries(pills).every(([fieldId, values]) => {
+    if (!values || values.length === 0) return true;
+    return values.includes(String(row[fieldId] ?? ""));
+  });
+}
+
+/**
+ * Ranges. A DAY bound is compared as an ISO STRING, never coerced to a
+ * timestamp: turning an `até` of 2026-07-15 into an instant lands on that day's
+ * midnight and silently drops the final day (FUT-668). Both ends are inclusive.
+ */
+function matchesRanges(row: ServerRow, ranges: Record<string, RangeValue>): boolean {
+  return Object.entries(ranges).every(([fieldId, range]) => {
+    if (!range || (range.min == null && range.max == null)) return true;
+    const value = fieldId === "data" ? row.dataIso : row.valor;
+    if (value == null) return false;
+    if (range.min != null && value < range.min) return false;
+    if (range.max != null && value > range.max) return false;
+    return true;
+  });
+}
+
+function matchesSearch(row: ServerRow, search: string): boolean {
+  const term = search.trim().toLowerCase();
+  if (!term) return true;
+  return [row.pedido, row.cliente, row.metodo].some((field) =>
+    String(field).toLowerCase().includes(term),
+  );
+}
+
+/** The scopes this story declares, as predicates over a row's `situacao`. */
+const SCOPES: Record<string, (row: ServerRow) => boolean> = {
+  todos: () => true,
+  "Em aberto": (row) => row.situacao === "Em aberto",
+  Cancelado: (row) => row.situacao === "Cancelado",
+};
+
+function compare(a: ServerRow, b: ServerRow, id: string): number {
+  const left = a[id];
+  const right = b[id];
+  if (typeof left === "number" && typeof right === "number") return left - right;
+  return String(left ?? "").localeCompare(String(right ?? ""), "pt-BR");
+}
+
+/**
+ * Answer one query: narrow, count, scope, sort, then cut the page.
+ *
+ * `scopeCounts` is computed BEFORE the scope is applied, which is the whole
+ * reason it cannot be done in the browser — a count taken from the loaded page
+ * is wrong the moment there is a second page.
+ */
+export function queryPedidos(rows: ServerRow[], query: DataViewQuery): ServerPage<ServerRow> {
+  const narrowed = rows.filter(
+    (row) =>
+      matchesSearch(row, query.search) &&
+      matchesPills(row, query.pills) &&
+      matchesRanges(row, query.ranges ?? {}),
+  );
+
+  const scopeCounts = Object.fromEntries(
+    Object.entries(SCOPES).map(([id, predicate]) => [id, narrowed.filter(predicate).length]),
+  );
+
+  const predicate = query.scope ? SCOPES[query.scope] : undefined;
+  const scoped = predicate ? narrowed.filter(predicate) : narrowed;
+
+  const sorted = [...scoped];
+  const sort = query.sortBy?.[0];
+  if (sort) {
+    sorted.sort((a, b) => (sort.dir === "asc" ? compare(a, b, sort.id) : compare(b, a, sort.id)));
+  }
+
+  const start = (query.page - 1) * query.pageSize;
+  return {
+    data: sorted.slice(start, start + query.pageSize),
+    totalCount: scoped.length,
+    scopeCounts,
+  };
+}

package/src/components/data-display/DataViews/use-data-views-state.ts

@@ -58,7 +58,7 @@ interface UseDataViewsStateArgs<T extends Record<string, unknown>> {
    */
   server?: DataViewServer;
   /**
-   * The page-level partition rendered as tabs above the toolbar. Requires server
+   * The page-level partition rendered as tabs under the toolbar. Requires server
    * mode: a scope is applied at the BACKEND, never in the browser.
    */
   scopes?: ScopeConfig[];

package/src/components/data-display/DescriptionItem/DescriptionItem.tsx

@@ -21,6 +21,21 @@ export interface DescriptionItemProps {
    */
   orientation?: 'vertical' | 'horizontal';
 
+  /**
+   * Which edge the label and value line up on.
+   *
+   * - `start` (default): both flush left, the reading order for a form or a
+   *   description list.
+   * - `center`: both centred over each other — for a pair sitting in a column
+   *   of its own, where a left-flush label over a shorter value looks unhinged
+   *   from it.
+   * - `end`: both flush right, which is what a numeric column wants so its
+   *   digits line up with the value above and below.
+   *
+   * Applies to `vertical`; a `horizontal` pair is already a single line.
+   */
+  align?: 'start' | 'center' | 'end';
+
   /**
    * Optional CSS class name
    */
@@ -54,13 +69,20 @@ export interface DescriptionItemProps {
  * />
  * ```
  */
+/** `align` in the terms flexbox and CSS each want it. */
+const FLEX_ALIGN = { start: 'flex-start', center: 'center', end: 'flex-end' } as const;
+
 // Vertical stacks the label above the value; horizontal sets them side by side
 // with the label sized to its content.
-const containerSx = (isHorizontal: boolean) => ({
+const containerSx = (isHorizontal: boolean, align: 'start' | 'center' | 'end') => ({
   display: 'flex',
   flexDirection: isHorizontal ? ('row' as const) : ('column' as const),
-  alignItems: isHorizontal ? 'center' : 'flex-start',
+  alignItems: isHorizontal ? 'center' : FLEX_ALIGN[align],
   gap: isHorizontal ? 1 : 0,
+  // `alignItems` places the two boxes; `textAlign` handles a label or value
+  // that WRAPS, whose second line would otherwise fall back to flush-left
+  // inside a box the alignment had already centred.
+  textAlign: align,
 });
 
 const labelStyle = (isHorizontal: boolean) => ({
@@ -79,6 +101,7 @@ export const DescriptionItem: React.FC<DescriptionItemProps> = ({
   label,
   value,
   orientation = 'vertical',
+  align = 'start',
   className,
   'data-testid': dataTestId,
 }) => {
@@ -88,7 +111,7 @@ export const DescriptionItem: React.FC<DescriptionItemProps> = ({
   return (
     <Box
       className={className}
-      sx={containerSx(isHorizontal)}
+      sx={containerSx(isHorizontal, align)}
       data-testid={dataTestId || 'description-item'}
     >
       <Text

package/src/components/layout/ContentToolbar/ContentToolbar.tsx

@@ -120,7 +120,22 @@ function BrowsingClusters({
       {/* minWidth:0 lets this cluster be the one that gives up width as the row
        * tightens, which is what the filter overflow measures against. */}
       {leadingControls !== undefined && (
-        <Box sx={{ display: 'flex', alignItems: 'center', flexGrow: 1, minWidth: 0 }}>
+        <Box
+          sx={{
+            display: 'flex',
+            alignItems: 'center',
+            flexGrow: 1,
+            minWidth: 0,
+            // The collapse ladder has a FLOOR — below roughly 400px even the
+            // fully-collapsed row does not fit, and its controls cannot shrink
+            // (they are flexShrink:0 so an over-packed row sheds instead of
+            // squeezing). Past that point this scrolls rather than letting them
+            // paint outside the toolbar, which is what a narrow phone did.
+            overflowX: 'auto',
+            // No scrollbar gutter stealing height on the common case.
+            scrollbarWidth: 'thin',
+          }}
+        >
           {leadingControls}
         </Box>
       )}

package/src/components/layout/ContentToolbar/MultiSelectDropdown.tsx

@@ -93,7 +93,15 @@ export function MultiSelectDropdown<TValue extends string = string>({
 
   const renderTrigger = (): React.JSX.Element => {
     if (stacked) return <StackedTrigger label={label} {...triggerProps} />;
-    if (layout === 'pill') return <PillTrigger label={label} selectedCount={selected.size} {...triggerProps} />;
+    if (layout === 'pill')
+      return (
+        <PillTrigger
+          label={label}
+          selectedCount={selected.size}
+          onClear={onClear}
+          {...triggerProps}
+        />
+      );
     return <InlineTrigger label={label} {...triggerProps} />;
   };