@12-apps/ui 1.6.3 → 1.7.0

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

@@ -2,6 +2,7 @@
 
 import { useEffect, useRef, useState } from "react";
 
+import { estimateWidth, GAP, isRangeSet, pillText, RESERVED } from "./data-views-overflow-costs";
 import type { FilterFieldConfig, RangeFieldConfig, RangeValue } from "./data-views-types";
 
 /**
@@ -12,10 +13,14 @@ import type { FilterFieldConfig, RangeFieldConfig, RangeValue } from "./data-vie
  * 1. Controls shed ONE AT A TIME into an overflow, never all at once. With four
  *    filters and room for three, hiding all four throws away the room that was
  *    there.
- * 2. An APPLIED filter never hides. Applied controls take the visible slots
- *    first, so the overflow badge counts hidden FIELDS and never active
- *    filters — a filter you cannot see is a filter you forget you set, and then
- *    the list is "wrong" for reasons nothing on screen explains.
+ * 2. An APPLIED filter is ranked first, not exempt. Applied controls take the
+ *    visible slots ahead of idle ones, and go into "Mais" like anything else
+ *    when even those slots run out. Exempting them outright — the earlier rule
+ *    — meant four applied filters on a phone claimed more width than the row
+ *    had, and the bar painted past its own edge: the pills were reachable only
+ *    by scrolling the toolbar sideways. Hiding one is safe because "Mais" says
+ *    how many applied filters are behind it; scrolling one off-screen says
+ *    nothing at all.
  *
  * It MEASURES rather than picking a breakpoint, which is what
  * `FILTERS-CONTRACT.md` asks for: pages declare different numbers of filters
@@ -46,53 +51,39 @@ export interface OverflowSplit<T extends Record<string, unknown>> {
    * Cheap: both keep their icon, their tooltip and their position.
    */
   compactControls: boolean;
+  /**
+   * Step 5, and the LAST resort — the "N de N" counter is dropped.
+   *
+   * Only once every control has already collapsed and the row STILL does not
+   * fit, which on a six-filter table is below about 400px. The counter goes
+   * last because it is the only thing left that reports rather than does: an
+   * operator can act without knowing the total, but not without the search.
+   */
+  counterHidden: boolean;
   /**
    * Step 4 — the search collapses to a magnifier that expands on click.
    * The most expensive step, so it is taken last: the search is the one
    * control on the bar that cannot be guessed from an icon's position.
    */
   searchCollapsed: boolean;
-  /** Attach to the toolbar row being measured. */
-  barRef: React.RefObject<HTMLDivElement | null>;
-}
-
-/**
- * Rough rendered width of a control, in px.
- *
- * An ESTIMATE from the label text rather than a real measurement, deliberately:
- * measuring the true width needs every control mounted first, and mounting them
- * to decide whether to mount them is the layout thrash this hook exists to
- * avoid. The estimate only has to rank controls and find the cut point — being
- * a few px out moves the cut by at most one control, and the overflow catches it.
- */
-function estimateWidth(text: string, extra: number): number {
   /**
-   * ~7.6px per character at the toolbar's font size, plus 76px of chrome:
-   * horizontal padding, the border, and the dropdown chevron. The chrome used
-   * to be 52, which under-priced every control by roughly a chevron's width —
-   * six of them then "fitted" a row they overflowed, and because they are flex
-   * children the row paid for it by squeezing labels to "D…" and "V…" rather
-   * than by shedding a control into the overflow.
+   * Step 6, below even the counter — "Limpar" leaves the bar.
    *
-   * Deliberately generous: over-pricing sheds one control too early, which the
-   * "Mais" button absorbs invisibly. Under-pricing breaks the line.
+   * The one control here with a second home: the overflow panel's footer
+   * carries "Limpar todos os filtros". So it goes before the search icon or
+   * "Mais", neither of which has anywhere else to be.
    */
-  return Math.round(text.length * 7.6) + 76 + extra;
-}
-
-/** Is a range bounded at either end? */
-function isRangeSet(range: RangeValue | undefined): boolean {
-  return Boolean(range && (range.min !== undefined || range.max !== undefined));
-}
-
-/** The label a pill actually renders, which is what decides its width. */
-function pillText<T extends Record<string, unknown>>(field: OverflowField<T>, values: string[]): string {
-  if (values.length === 0) return field.label;
-  if (values.length === 1) {
-    const option = field.pill?.options.find((entry) => entry.value === values[0]);
-    return `${field.label}: ${option?.label ?? values[0]}`;
-  }
-  return `${field.label}: ${values.length}`;
+  clearAllHidden: boolean;
+  /**
+   * Expanding the magnifier must take the whole cluster, filters and all.
+   *
+   * Only on the rungs where what is left over would be too narrow to read —
+   * on a large phone the box simply shrinks and the filters stay, which is why
+   * this is its own answer rather than `searchCollapsed` reused.
+   */
+  searchTakeover: boolean;
+  /** Attach to the toolbar row being measured. */
+  barRef: React.RefObject<HTMLDivElement | null>;
 }
 
 /** Every declared control, pills first, in the order the bar renders them. */
@@ -106,24 +97,6 @@ export function toOverflowFields<T extends Record<string, unknown>>(
   ];
 }
 
-/** Fixed toolbar furniture the filters have to fit around, in px. */
-const RESERVED = {
-  /** The search box never shrinks below this. */
-  search: 200,
-  /** The "N de N" counter. */
-  counter: 96,
-  /** Exibir + Exportar WITH their text labels. */
-  right: 216,
-  /** The same two controls as icons only — step 2 of the ladder. */
-  rightCompact: 96,
-  /** The "Mais" button, only charged when there IS an overflow. */
-  overflowButton: 104,
-  /** Gaps + the row's own padding. */
-  chrome: 64,
-} as const;
-
-/** The gap between two controls. */
-const GAP = 8;
 
 /** Observe the bar's width. Returns 0 until the first measurement lands. */
 function useBarWidth(): { barRef: React.RefObject<HTMLDivElement | null>; width: number } {
@@ -189,23 +162,32 @@ function splitFilters<T extends Record<string, unknown>>(
   const active = all.filter((field) => isActiveField(field, pills, ranges));
   const idle = all.filter((field) => !isActiveField(field, pills, ranges));
 
-  // AN APPLIED FILTER NEVER HIDES — it is not merely ranked first, it is
-  // exempt. Applying a value LENGTHENS a control ("Método: Pix"), so ranking
-  // alone still loses the one filter the operator just set whenever it no
-  // longer fits on its own. The bar wraps; a filter you cannot see does not
-  // announce itself at all.
+  // "Limpar" rides the end of the cluster whenever anything is applied.
+  const clearCost = active.length > 0 ? RESERVED.clearAll + GAP : 0;
   let available =
-    width - RESERVED.search - RESERVED.counter - RESERVED.right - RESERVED.chrome - cost(active);
-  if (idle.length === 0 || cost(idle) <= available) {
-    return { inline: all, overflow: none, used: cost(all) };
+    width - RESERVED.search - RESERVED.counter - RESERVED.right - RESERVED.chrome - clearCost;
+  if (cost(all) <= available) {
+    return { inline: all, overflow: none, used: cost(all) + clearCost };
   }
 
   // There IS an overflow, so its button now costs room too.
   available -= RESERVED.overflowButton;
-  const keep = new Set(active.map((field) => field.id));
-  for (const field of idle) {
+  // APPLIED FIRST, BUT NOT EXEMPT.
+  //
+  // Applied controls take the visible slots ahead of idle ones — that part was
+  // always right. Exempting them from the overflow entirely was not: applying
+  // a value LENGTHENS a control ("Pagamento (1)"), so on a phone four applied
+  // filters claimed more width than the row had and the bar simply painted
+  // past its own edge, leaving pills reachable only by scrolling sideways.
+  //
+  // An applied filter hidden in "Mais" is not lost the way it would be if it
+  // vanished silently: the trigger goes to the applied tone and says how many
+  // are in there (see `MoreTrigger`), which is the same signal the pill itself
+  // was carrying. A control you scroll off-screen carries no signal at all.
+  const keep = new Set<string>();
+  for (const field of [...active, ...idle]) {
     const next = widthOf(field) + GAP;
-    if (next > available) break;
+    if (next > available) continue;
     available -= next;
     keep.add(field.id);
   }
@@ -216,7 +198,7 @@ function splitFilters<T extends Record<string, unknown>>(
   return {
     inline,
     overflow: all.filter((field) => !keep.has(field.id)),
-    used: cost(inline) + RESERVED.overflowButton,
+    used: cost(inline) + RESERVED.overflowButton + clearCost,
   };
 }
 
@@ -249,7 +231,10 @@ function computeSplit<T extends Record<string, unknown>>(
       inline: all,
       overflow: [],
       compactControls: false,
+      counterHidden: false,
       searchCollapsed: false,
+      clearAllHidden: false,
+      searchTakeover: false,
     };
   }
   const { inline, overflow, used } = splitFilters(all, pills, ranges, width);
@@ -260,8 +245,39 @@ function computeSplit<T extends Record<string, unknown>>(
   const rightCost = compactControls ? RESERVED.rightCompact : RESERVED.right;
   // …and with them off?
   const searchCollapsed = base - RESERVED.counter - rightCost < RESERVED.search;
+  // Everything has collapsed and the row STILL overflows. The controls cannot
+  // shrink further — they are `flexShrink: 0` precisely so an over-packed row
+  // sheds rather than squeezes — so without this last rung they simply paint
+  // outside the toolbar, which is what a narrow phone was doing.
+  const counterHidden =
+    searchCollapsed && base - RESERVED.counter - rightCost < RESERVED.searchIcon;
+  // Step 6 — below even that, "Limpar" leaves the bar. It is the ONLY control
+  // here with a second home: the overflow panel's footer carries "Limpar todos
+  // os filtros", so nothing is lost, which is exactly why it goes before the
+  // search icon or "Mais" (neither of which has anywhere else to be). Guarded
+  // on there BEING an overflow, because with no panel the footer does not
+  // exist and dropping this would strand the operator.
+  const clearAllHidden = counterHidden && overflow.length > 0;
+  // What the keyword box would get if the operator expanded the magnifier and
+  // everything else stayed put. `searchCollapsed` is a different question — it
+  // asks whether the box fits at its PREFERRED 200px, and is deliberately
+  // pessimistic — so reusing it to decide the takeover evicted the filters on
+  // screens where the box had plenty of room to simply shrink.
+  const searchBoxRoom = base - (counterHidden ? 0 : RESERVED.counter) - rightCost;
+  // Below this a box is too narrow to read what you typed into it, and shrinking
+  // further buys nothing; that is the only point at which taking the whole
+  // cluster is worth losing the filters.
+  const searchTakeover = searchCollapsed && searchBoxRoom < RESERVED.usableSearch;
 
-  return { inline, overflow, compactControls, searchCollapsed };
+  return {
+    inline,
+    overflow,
+    compactControls,
+    counterHidden,
+    searchCollapsed,
+    clearAllHidden,
+    searchTakeover,
+  };
 }
 
 /**

package/src/components/data-display/DataViews/data-views-preset-chips.tsx

@@ -0,0 +1,100 @@
+"use client";
+
+/**
+ * THE ONE-CLICK WINDOWS ABOVE A RANGE'S `De`/`Até` INPUTS.
+ *
+ * "Filter by last month" is two date pickers, four gestures and a mental
+ * calculation of which day the month ended on. It is also the overwhelmingly
+ * common case. So the common windows get a chip each, and the inputs stay for
+ * the windows nobody could enumerate.
+ *
+ * Clicking an active preset CLEARS it. A chip that reads as pressed and does
+ * nothing when pressed again is a dead control, and the alternative — hunting
+ * for the pill's ✕ — is the gesture this row exists to remove.
+ */
+import { Box } from "@mui/material";
+
+import { isPresetActive, resolvePreset } from "./data-views-range-presets";
+import type { RangePreset, RangeValue } from "./data-views-types";
+
+/** One preset, styled as the same pill-shaped chip the filter bar uses. */
+function PresetChip({
+  preset,
+  active,
+  onSelect,
+  testId,
+}: {
+  preset: RangePreset;
+  active: boolean;
+  onSelect: () => void;
+  testId: string;
+}): React.JSX.Element {
+  return (
+    <Box
+      component="button"
+      type="button"
+      onClick={onSelect}
+      aria-pressed={active}
+      data-testid={testId}
+      sx={{
+        px: 1.25,
+        py: 0.5,
+        border: 1,
+        borderStyle: "solid",
+        borderColor: active ? "primary.main" : "divider",
+        borderRadius: 999,
+        bgcolor: active ? "action.selected" : "background.paper",
+        color: active ? "primary.main" : "text.secondary",
+        cursor: "pointer",
+        font: "inherit",
+        fontSize: "0.75rem",
+        fontWeight: 600,
+        whiteSpace: "nowrap",
+        "&:hover": { borderColor: active ? "primary.main" : "text.primary" },
+      }}
+    >
+      {preset.label}
+    </Box>
+  );
+}
+
+/**
+ * The preset row. Renders nothing when a field declares none, so a numeric
+ * range without host-configured windows keeps the popover it had.
+ *
+ * Carries no outer margin — the three surfaces that host it (the pill's
+ * popover, the slide-in panel, the "Mais" overflow) each sit it in a different
+ * stack, and a baked-in margin would be wrong in two of them.
+ */
+export function RangePresets({
+  presets,
+  value,
+  onChange,
+  testId,
+}: {
+  presets: RangePreset[];
+  value: RangeValue;
+  onChange: (range: RangeValue) => void;
+  testId: string;
+}): React.JSX.Element | null {
+  if (presets.length === 0) return null;
+  return (
+    <Box
+      data-testid={`${testId}-presets`}
+      sx={{ display: "flex", flexWrap: "wrap", gap: 0.75 }}
+    >
+      {presets.map((preset) => {
+        const active = isPresetActive(preset, value);
+        return (
+          <PresetChip
+            key={preset.id}
+            preset={preset}
+            active={active}
+            onSelect={() => onChange(active ? {} : resolvePreset(preset))}
+            testId={`${testId}-preset-${preset.id}`}
+          />
+        );
+      })}
+    </Box>
+  );
+}

package/src/components/data-display/DataViews/data-views-range-pill.tsx

@@ -19,6 +19,8 @@ import React, { useState } from 'react';
 import { TableFilter } from '../../layout/TableFilter';
 import { DayBoundInput } from './data-views-day-input';
 import { NumberBoundInput } from './data-views-number-input';
+import { RangePresets } from './data-views-preset-chips';
+import { presetsFor } from './data-views-range-presets';
 import {
   isRangeInverted,
   isRangeSet,
@@ -90,6 +92,11 @@ export function RangeBounds<T extends Record<string, unknown>>({
   const inverted = isRangeInverted(value);
   return (
     <Box data-testid={`${testId}-panel`}>
+      {/* Above the inputs, not below: the presets are the answer for most
+          merchants, and the two date pickers are the escape hatch. */}
+      <Box sx={{ '&:not(:empty)': { mb: 1.5 } }}>
+        <RangePresets presets={presetsFor(field)} value={value} onChange={onChange} testId={testId} />
+      </Box>
       <Box sx={{ display: 'flex', alignItems: 'center', gap: 1.5 }}>
         <BoundField
           field={field}
@@ -200,13 +207,16 @@ function RangeTrigger<T extends Record<string, unknown>>({
       aria-haspopup="dialog"
       aria-expanded={open}
       onClick={(event) => onOpen(event.currentTarget)}
-      endIcon={
+      // ✕ FIRST, chevron LAST — the same shape as every other pill. It used to
+      // replace the chevron at the end, so a range pill and a multi-select pill
+      // put the clear in different places, and an applied range lost the
+      // affordance that says it opens.
+      startIcon={
         active ? (
           <ClearAffordance label={field.label} onClear={() => onChange({})} testId={`${testId}-clear-inline`} />
-        ) : (
-          <ChevronDownIcon sx={{ fontSize: 16 }} />
-        )
+        ) : undefined
       }
+      endIcon={<ChevronDownIcon sx={{ fontSize: 16 }} />}
       sx={{
         borderRadius: 999,
         height: 34,
@@ -327,12 +337,18 @@ export function PanelRangeField<T extends Record<string, unknown>>({
     );
   }
   return (
-    <TableFilter.RangeField
-      label={field.label}
-      unit={field.unit}
-      value={numericRange(value)}
-      onChange={(range) => onChange(range)}
-      testId={testId}
-    />
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 1 }}>
+      <TableFilter.RangeField
+        label={field.label}
+        unit={field.unit}
+        value={numericRange(value)}
+        onChange={(range) => onChange(range)}
+        testId={testId}
+      />
+      {/* Below the numeric control here, unlike the pill's popover: this one
+          renders its own label, and chips above it would separate the label
+          from the field it names. */}
+      <RangePresets presets={presetsFor(field)} value={value} onChange={onChange} testId={testId} />
+    </Box>
   );
 }

package/src/components/data-display/DataViews/data-views-range-presets.ts

@@ -0,0 +1,121 @@
+import type { RangeFieldConfig, RangePreset, RangeValue } from "./data-views-types";
+
+/**
+ * THE CALENDAR WINDOWS BEHIND A DATE FILTER'S ONE-CLICK PRESETS.
+ *
+ * Pure and component-free, for the same reason `data-views-range-values` is:
+ * the pill's popover, the slide-in panel and the "Mais" overflow all offer the
+ * same presets, and none of them should have to import a component to know what
+ * "Esta semana" resolves to.
+ *
+ * Every window is computed in the LOCAL calendar and emitted as `AAAA-MM-DD`.
+ * Going through `toISOString()` would answer in UTC, which for every Brazilian
+ * timezone is a day ahead after 21:00 — "Hoje" would quietly become tomorrow
+ * every evening.
+ */
+
+/** `AAAA-MM-DD` for a date, read in the local calendar (never UTC). */
+function isoDay(date: Date): string {
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${date.getFullYear()}-${month}-${day}`;
+}
+
+/** The same date shifted by whole days, without mutating the original. */
+function shiftDays(date: Date, days: number): Date {
+  const next = new Date(date);
+  next.setDate(next.getDate() + days);
+  return next;
+}
+
+/**
+ * The five windows every date filter wants, resolved when CLICKED.
+ *
+ * Each is a whole calendar unit rather than a unit-to-date: "Este mês" is the
+ * whole month, not the 1st through today. It is what the words say, it matches
+ * the label a merchant reads back on the pill, and it changes nothing for a
+ * dataset with no future rows — while a page that does have them (scheduled
+ * orders) would otherwise hide them under a preset that claims to show the
+ * month.
+ *
+ * The week starts on SUNDAY, following the Brazilian calendar these grids are
+ * read against rather than ISO-8601's Monday.
+ */
+export const DAY_RANGE_PRESETS: RangePreset[] = [
+  {
+    id: "hoje",
+    label: "Hoje",
+    range: () => {
+      const today = isoDay(new Date());
+      return { min: today, max: today };
+    },
+  },
+  {
+    id: "ontem",
+    label: "Ontem",
+    range: () => {
+      const yesterday = isoDay(shiftDays(new Date(), -1));
+      return { min: yesterday, max: yesterday };
+    },
+  },
+  {
+    id: "semana",
+    label: "Esta semana",
+    range: () => {
+      const now = new Date();
+      const sunday = shiftDays(now, -now.getDay());
+      return { min: isoDay(sunday), max: isoDay(shiftDays(sunday, 6)) };
+    },
+  },
+  {
+    id: "mes",
+    label: "Este mês",
+    range: () => {
+      const now = new Date();
+      const year = now.getFullYear();
+      const month = now.getMonth();
+      // Day 0 of the NEXT month is the last day of this one — the only spelling
+      // that needs no month-length table and no leap-year branch.
+      return { min: isoDay(new Date(year, month, 1)), max: isoDay(new Date(year, month + 1, 0)) };
+    },
+  },
+  {
+    id: "ano",
+    label: "Este ano",
+    range: () => {
+      const year = new Date().getFullYear();
+      return { min: `${year}-01-01`, max: `${year}-12-31` };
+    },
+  },
+];
+
+/**
+ * The presets a field offers: its own, or the calendar defaults for a day field
+ * that declared none. An explicit `[]` means none — a host suppressing them is
+ * saying something, and must not be overridden by the fallback.
+ */
+export function presetsFor<T extends Record<string, unknown>>(
+  field: RangeFieldConfig<T>,
+): RangePreset[] {
+  if (field.presets) return field.presets;
+  return field.kind === "day" ? DAY_RANGE_PRESETS : [];
+}
+
+/** A preset's window, evaluating it if it is time-dependent. */
+export function resolvePreset(preset: RangePreset): RangeValue {
+  return typeof preset.range === "function" ? preset.range() : preset.range;
+}
+
+/**
+ * Is this preset the window currently applied?
+ *
+ * Bounds compare as STRINGS because a `number` field's stored bound may have
+ * arrived from an input as `100` while the preset declares `100` — same window,
+ * and `undefined` vs a missing key must read as equal too.
+ */
+export function isPresetActive(preset: RangePreset, value: RangeValue): boolean {
+  const resolved = resolvePreset(preset);
+  const same = (a: number | string | undefined, b: number | string | undefined): boolean =>
+    String(a ?? "") === String(b ?? "");
+  return same(resolved.min, value.min) && same(resolved.max, value.max);
+}

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

@@ -0,0 +1,94 @@
+/**
+ * RANGE FILTERS — the value types, apart from the rest of the DataViews model.
+ *
+ * Split out because `data-views-types` had grown past the file-size gate, and
+ * this is the seam that actually exists: a range is a self-contained little
+ * language (a window, its two kinds, its one-click presets) that the pill, the
+ * overflow panel, the slide-in panel and the fake backend all speak.
+ *
+ * Every one of them still imports from `data-views-types`, which re-exports
+ * these — there is one public name for the model, and moving a type between
+ * files is not a reason to touch a dozen import lines.
+ */
+
+/**
+ * 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";
+
+/**
+ * A one-click window for a range filter: "Hoje", "Acima de R$ 500".
+ *
+ * `range` is a FUNCTION when the answer depends on when it is clicked and a
+ * literal when it does not. "Hoje" must mean today at the moment of the click,
+ * not at the moment the config object was built — a long-lived admin tab
+ * evaluating it once would go on filtering by the day it was opened.
+ *
+ * What lands in `DataViewState.ranges` is always the RESOLVED window, so a
+ * saved view captures the days "Hoje" meant when it was saved. That is the
+ * honest behaviour for a saved view: it is a stored filter, not a stored
+ * intent, and re-running it later must not silently answer a different
+ * question.
+ */
+export interface RangePreset {
+  /** Stable id, used as the React key and in the preset's test id. */
+  id: string;
+  label: string;
+  range: RangeValue | (() => RangeValue);
+}
+
+interface RangeFieldBase {
+  /** Stable id; the key under `DataViewState.ranges`. */
+  id: string;
+  label: string;
+  /**
+   * One-click windows offered above the `De`/`Até` inputs.
+   *
+   * A `day` field falls back to the calendar defaults (Hoje / Ontem / Esta
+   * semana / Este mês / Este ano) when this is omitted, because those windows
+   * are the same for every date filter that has ever existed. A `number` field
+   * has no such universal set — what counts as a big order is the host's
+   * business — so it shows presets only when given them. Pass `[]` to a day
+   * field to suppress the defaults.
+   */
+  presets?: RangePreset[];
+}
+
+/** "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>;

package/src/components/data-display/DataViews/data-views-scope-tabs.tsx

@@ -0,0 +1,57 @@
+"use client";
+
+/**
+ * WHERE THE SCOPE TABS GO, AND WHEN THEY DO NOT GO THERE AT ALL.
+ *
+ * Its own module because it is a placement rule rather than a control: the
+ * strip itself is `DataViewsScopeTabs`, and this decides whether the grid shows
+ * one.
+ */
+import { DataViewsScopeTabs, type ScopeConfig } from "./data-views-scopes";
+import { useDataViewsLayout } from "./data-views-layout-context";
+
+/**
+ * The scope tabs — BELOW the toolbar, and absent when the board is already
+ * showing the same partition.
+ *
+ * A "Quadro" grouped by `situacao` is a column per situação; a scope strip over
+ * the same field is a tab per situação. Together they are the same partition
+ * offered twice, one of which silently narrows what the other displays —
+ * picking the "Cancelado" tab leaves a board with one populated column and the
+ * rest empty, which reads as data loss rather than as a filter.
+ *
+ * Only when they partition by the SAME field: a board grouped by one field
+ * beside scopes over another are two different cuts, and both belong.
+ */
+export function ScopeTabsSlot({
+  scopes,
+  scopeFieldId,
+  board,
+  value,
+  onChange,
+  counts,
+  testIdPrefix,
+}: {
+  scopes: ScopeConfig[];
+  scopeFieldId?: string;
+  board?: { groupBy: string };
+  value?: string;
+  onChange: (id: string) => void;
+  counts?: Record<string, number>;
+  testIdPrefix: string;
+}): React.JSX.Element | null {
+  const { layout } = useDataViewsLayout();
+  const boardOwnsThisPartition =
+    layout === "board" && Boolean(scopeFieldId) && scopeFieldId === board?.groupBy;
+  if (boardOwnsThisPartition) return null;
+  // Renders nothing (and reserves nothing) for an empty scope list.
+  return (
+    <DataViewsScopeTabs
+      scopes={scopes}
+      value={value}
+      onChange={onChange}
+      counts={counts}
+      testIdPrefix={testIdPrefix}
+    />
+  );
+}