Spaces:
Running on CPU Upgrade
Running on CPU Upgrade
Download web/src/sheet/DrillModal.tsx from fsanyoto/runloopable: direct link, hf CLI and curl.
- Browser
- Download file 55.9 kB
-
https://huggingface.co/spaces/fsanyoto/runloopable/resolve/main/web/src/sheet/DrillModal.tsx
- Command line
-
hf download hf://spaces/fsanyoto/runloopable/web/src/sheet/DrillModal.tsx
-
curl -L -o DrillModal.tsx https://huggingface.co/spaces/fsanyoto/runloopable/resolve/main/web/src/sheet/DrillModal.tsx
55.9 kB
// sheet/DrillModal.tsx β a bound cell's rows, in the Link field's own popup (W49-T07, R6/R13/R17).
//
// ββ R6 SAYS "EXACTLY THE LINK FIELD TYPE'S POPUP UI", SO THIS REUSES THE COMPONENT RATHER THAN
// ITS APPEARANCE. `LinkGridModal` is imported from `customer-grid/CustomerGrid.tsx`. Rebuilding a
// lookalike would give the product two
// popups that behave almost the same, and "almost" is where a focus trap or an escape key goes
// missing on one of them.
//
// R13 requires live rows and counts. The drill returns an exact count and page IDs.
// Its caller-owned row source replays structured queries under current permissions.
// Page IDs identify rows already read and never restrict the remaining population.
//
// β R13 ALSO FORBIDS DISCLOSING STALENESS HERE. A stale cell opens the same popup with the same
// chrome and NO comparison text: no "was 24,920", no badge, nothing. The staleness is a property of
// the CELL and it is marked on the grid; repeating it here would be answering a question the person
// did not ask, at the moment they asked a different one.
//
// ββ W54-T34 (owner instruction 10) β NINE SECONDS OF NOTHING WAS THE DEFECT.
// Owner, verbatim: *"Clicking View rows still takes a long time; if it must, we need a loading
// button so the user knows their click worked."* This component used to render `null` for the whole
// of that wait, so a drill that was working and a click that never landed looked identical. Measured
// on tenant #0 (`AutoWiki/waves/wave54/lanes/E/T36-baseline.md`): `drill_cell` costs 55 to 90 ms
// against a `ut_*` table but 9,248 to 9,448 ms against `customer_data`, which goes through the
// registry-module mirror rather than a DuckDB query. So the wait is real and it is long.
//
// β BOTH `null`S WERE THE DEFECT, NOT ONE. The request had no loading state and neither did the
// LAZY CHUNK behind it, so a warm answer could still be followed by a second blank window while
// 1,850 kB of `CustomerGrid` downloaded. The Suspense fallback's old note argued that "a skeleton
// behind a modal that is about to cover it would be a flash of furniture nobody asked for" - which
// was right when there was no skeleton at all and the two states were nothing and everything. Now
// the skeleton is ALREADY on screen when the answer lands, so keeping it up for the chunk is
// CONTINUITY rather than new furniture: the surface never blinks back to nothing.
//
// ββ W54-T35 (owner instruction 8, ruling R8) β THE ROWS ARE HERE, SO THE REASON FOR THEM
// SHOULD BE TOO. Owner, verbatim: *"the Filter module itself will show exactly what the filter is
// when we click 'View row' so its easy for user also to know what this filter is. In fact, they
// should be able to change the filter there too. And if they make a mistake etc, they can just
// CTRL + Z to return the Cell to its original filter."* Three clauses, and each one is a decision
// recorded beside the code that answers it: the BAND (`DrillFilterBand`) states it, the grid's
// Filter control edits it, and one cell-scoped step of undo takes it back.
//
// ββ W56-T24 / R4 / C4 β THE LINK MODAL NOW OWNS ORDINARY SLOTS FOR THE SHEET'S CHROME.
// The toolbar and filter statement are children of the modal's header and footer, so they remain
// inside its focus trap and dismissal boundary without querying the DOM or waiting for a frame.
// The body is the default `CustomerGrid` export itself, with `cellView` relaxing only its embedded
// mode-switcher withholding. The embedded write and workspace guards remain untouched.
//
// β THE REAL FOOTER MAY WEAR `.cg-link-grid-foot`, WHICH THE SKELETON ABOVE MAY NOT. The rule that
// stops `DrillSkeleton` borrowing `customer-grid/RecordDetail.css` is that the skeleton stands in
// for a chunk that has not arrived, so on a cold cache its class names would exist and its rules
// would not. `LinkGridModal` renders that footer only after the same chunk is in hand, so its
// stylesheet is guaranteed present. Same file, opposite verdict, for one reason: WHEN it paints.
import { Suspense, lazy, useCallback, useEffect, useMemo, useRef, useState } from "react";
import { API_V1, CREDENTIALS } from "../apiContract";
import { aggregatePageProgress, aggregatePayload, fetchWorkspace } from "../customer-grid/apiBridge";
import { dropAppliedFilterLimits } from "../customer-grid/drillLimits";
import type { SurfaceScope } from "../customer-grid/apiBridge";
import type { CellDisplayChoice, EmbeddedRowSource } from "../customer-grid/CustomerGrid";
import { dataPathHash } from "../customer-grid/dataPath";
import { AnchoredOverlay, BodyPortal, OverlayProvider, useOverlayLayer } from "../customer-grid/OverlaySurface";
import type { CustomersPayload, Field, FilterTree, GridWorkspace, Row } from "../customer-grid/types";
import { mayEditField } from "../customer-grid/types";
import { conditionCountLabel, filterSentence } from "../filter-kit/SheetFilterPopup";
import { useEscapeClose } from "../ui/useEscapeClose";
import { cellForcedFieldKeys, cellViewVisibleKeys } from "./bindingRefs";
import { drillCell } from "./sheetApi";
import type { CellDrill } from "./sheetApi";
import type { BindingDisplay, ViewBinding, ViewRowsAnswer } from "./types";
import { bindingDisplay } from "./types";
import { fetchViewRows, showingLine } from "./viewPlacement";
import "../styles/sdlc80/drill.css";
/**
* ββ LAZY, AND THE BUILD IS WHAT SAID SO. A plain `import { LinkGridModal } from
* "../customer-grid/CustomerGrid"` compiles and typechecks perfectly, and it quietly defeats the
* code-splitting of a 1,850 kB chunk. Rollup reported it as
* `INEFFECTIVE_DYNAMIC_IMPORT: CustomerGrid.tsx is dynamically imported by App.tsx,
* RecordDetail.tsx, QueryPage.tsx and Shell.tsx but also statically imported by DrillModal.tsx,
* dynamic import will not move module into another chunk` - which in practice means opening the
* Sheet page downloads the whole customer grid before anyone has drilled into anything.
*
* β `React.lazy` wants a DEFAULT export and `LinkGridModal` is a named one, so the promise is
* mapped. That is the whole trick: the export stays named and the split remains intact while
* W56-T24 extends the modal through optional props.
*/
const LinkGridModal = lazy(() =>
import("../customer-grid/CustomerGrid").then((m) => ({ default: m.LinkGridModal })),
);
/**
* ββ W54-T34 β THE CHUNK IS ASKED FOR WHEN THE READER ASKS FOR THE ROWS, NOT AFTER THEY ARRIVE.
*
* `React.lazy` starts its import on the first render that actually reaches `<LinkGridModal>`, which
* on the success path is AFTER the drill has answered. On `customer_data` that is nine seconds, and
* the 1,850 kB download then begins from zero: two waits, back to back, for one click. Warming the
* module the moment this component mounts runs them together instead. Nothing is imported twice -
* the two dynamic imports name the same module, so the second one resolves off the registry.
*
* β AND THE BOOLEAN IT FEEDS IS NOT A CONVENIENCE, IT IS THE ESCAPE CLAIM. `LinkGridModal` joins
* the base kit's stack from inside itself, through `useOverlayLayer`, so it claims Escape only once
* it has MOUNTED. The window while its chunk is still in flight belongs to nobody. Knowing when the
* module is in hand is what lets the skeleton hold the claim for exactly that window and hand it
* over, rather than overlap it - the double-push the W51-T12 note below is careful to avoid.
*/
const warmLinkChunk = () => import("../customer-grid/CustomerGrid");
/**
* A Sheet binding names a DATABASE KEY; `LinkGridModal` wants a `SurfaceScope`. The two are not
* the same vocabulary and the difference is only visible for the two compiled modules.
*
* β The same mapping already exists in the Time-series panel, which is ANOTHER LANE'S FILE in this
* wave. It is re-stated here rather than imported so lane A touches nothing of lane C's; the pair
* is small, total, and the right place to unify them is after both lanes merge.
*/
const scopeOf = (database: string): SurfaceScope | null => {
if (database === "customer_data") return "customer";
if (database === "product_data") return "product";
return database.startsWith("ut_") ? (database as SurfaceScope) : null;
};
/**
* ββ W54-T34 β WHAT VIEW ROWS OPENS INTO WHILE ITS ROWS ARE FETCHED.
*
* β THE SKELETON LANGUAGE IS INHERITED, NOT INVENTED. `sheet/SheetRail.tsx::RailSkeleton` set it
* and `sheet/BindingEditor.tsx::BindingSkeleton` followed it one ticket ago: ONE flat
* `--lp-surface-2` tone, no shimmer (an animated sweep is a second thing moving on a surface whose
* whole job is to sit still, and `prefers-reduced-motion` would then need a third state), bars
* `aria-hidden` under ONE `role="status"` so a screen reader hears "loading" once, and 150 ms
* ease-out on opacity alone. A second skeleton dialect in the same stylesheet would be the cost.
*
* ββ AND IT CANNOT BORROW `.cg-record-backdrop` / `.cg-link-grid-modal`, WHICH IS THE OBVIOUS
* SHORTCUT AND IS EXACTLY BACKWARDS. Those rules live in `customer-grid/RecordDetail.css`, imported
* by `RecordDetail.tsx` - inside the very chunk this skeleton is standing in for. On a cold cache
* the class names would be there and the rules would not, so the stand-in for a slow chunk would
* paint in native chrome, precisely when it is needed most.
* ([[portalling-drops-descendant-scoped-css]], same failure through a different door.)
*
* β THE GEOMETRY IS THE SETTLED MODAL'S, measured off `.cg-link-grid-modal`: the same
* `min(1320px, 100vw - 48px)` by `min(840px, 100vh - 48px)` card on the same centred scrim, a 54px
* head, then rows. That is what makes it a skeleton rather than a placeholder - the real grid lands
* where the bars were instead of resizing the surface under the reader's eyes.
*/
function DrillSkeleton(
{ label, nodeRef, onClose }: {
label: string; nodeRef: { current: HTMLDivElement | null }; onClose: () => void;
},
) {
useOverlayLayer({ panelRef: nodeRef, onDismiss: onClose, dismissOnOutside: false,
initialFocus: "first", restoreFocus: true, trapFocus: true });
return (
<div
className="sheet-drill-skeleton-backdrop"
onClick={(event) => { if (event.target === event.currentTarget) onClose(); }}
>
<div className="sheet-drill-skeleton" role="dialog" aria-modal="true"
aria-label={`Loading the rows behind ${label}`} ref={nodeRef}>
<div className="sheet-drill-skeleton-head">
<div className="sheet-drill-skeleton-labels" aria-hidden="true">
<span className="sheet-drill-skeleton-title" />
<span className="sheet-drill-skeleton-sub" />
</div>
<button type="button" className="sheet-action" onClick={onClose}>Close</button>
</div>
<div className="sheet-drill-skeleton-rows" role="status" aria-label="Loading rows">
<div className="sheet-drill-skeleton-bars" aria-hidden="true">
<span className="sheet-drill-skeleton-row is-head" />
{[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11].map((i) => (
<span className="sheet-drill-skeleton-row" key={i} />
))}
</div>
</div>
</div>
</div>
);
}
/**
* ββ W54-T35 / R8 β WHICH ROWS THE CELL ASKED FOR, IN THE TWO SHAPES A BINDING CAN SAY IT.
*
* β THE `view` ARM EXISTS SO THE EDITOR CAN BE WITHHELD, AND THAT IS R8 VERBATIM: *"The Fields
* list β¦ is hidden everywhere else, including under 'A saved view', where the view already fixes
* the rows."* A saved view's rows are the VIEW's business; editing a filter here would either
* silently fork the cell off its view or edit the view for everybody who uses it. So a view-bound
* cell gets the sentence and no Edit door.
*/
export type DrillCellScope = (
| { kind: "filter"; tree: FilterTree }
| { kind: "view"; name: string }
)
& {
/** C4: the cell's persisted column choices, independent of any shared View. */
display?: BindingDisplay;
/** The host supplies these from the current binding alongside its filter or saved view. */
aggregateField?: string;
/** The Option step's binding.onDrag.down.field, when down is a field rule. */
stepField?: string;
};
/** What the drill's own answer says about the scope, for a caller that passed none. */
function scopeFromDrill(drill: CellDrill | null): DrillCellScope | null {
if (!drill) return null;
if (drill.view_id) return { kind: "view", name: "" };
const tree = drill.filter as FilterTree | null | undefined;
return { kind: "filter", tree: tree ?? { conj: "and", nodes: [] } };
}
/**
* β TREE EQUALITY BY SERIALISATION, deliberately, and the shape is what makes it safe. A
* `FilterTree` is plain JSON with no cycles and no undefined-versus-absent subtleties that matter
* here: both sides of every comparison this file makes came out of the SAME builder, so their key
* order is the builder's own. A hand-written deep-equal over `FilterRule`'s eleven optional
* members is the thing that would quietly stop noticing a member somebody added later.
*/
const sameTree = (a: FilterTree | null, b: FilterTree | null): boolean =>
JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
/**
* ββ W54-T35 β THE BAND THAT STATES THE FILTER, at the foot of the rows it produced.
*
* The sentence is the whole of the owner's first clause, so it takes the width and truncates with
* an ellipsis rather than being shortened into a count; the full text stays reachable as the
* element's `title`. The grid's Filter control owns editing; this band states the cell's scope
* and any editing limit. W56-T24 seats it inside `LinkGridModal`'s footer slot, so that shell now
* supplies the `cg-link-grid-foot` paint instead of this child impersonating the footer itself.
*/
function DrillFilterBand(
{ text }: { text: string },
) {
return (
<span
// The modal's real `cg-link-grid-foot` wrapper supplies the paint. These classes name the
// statement itself for a gate, a screenshot or a person in the inspector.
className="sheet-drill-filter sheet-drill-filter-text"
style={{
minWidth: 0,
overflow: "hidden",
textOverflow: "ellipsis",
whiteSpace: "nowrap",
color: "var(--lp-muted)",
}}
title={text}
>
{text}
</span>
);
}
/** Explain a legacy server's ID cap while page-based responses use their ordinary pager. */
function drillCapText(drill: Pick<CellDrill, "record_ids" | "count" | "record_ids_scope"> | null): string {
if (!drill || drill.record_ids_scope === "page" || drill.record_ids.length >= drill.count) return "";
return `Showing ${drill.record_ids.length.toLocaleString()} of ${drill.count.toLocaleString()} `
+ "matching records. Narrow the cell's filter to list the rest.";
}
export interface DrillModalProps {
embedded?: boolean;
onNavigate?: (address: { database: string; view?: string }) => void;
workbookId: string;
addr: string;
/** S66-T48: the tab the cell is on, so the drill reads THIS tab's cell at `addr`. */
tab?: string;
/** The label the popup wears. The cell's own address is the honest one: it is what was clicked. */
label: string;
onClose: () => void;
previewBinding?: ViewBinding;
onPlace?: () => void;
/**
* W54-T34: the drill has stopped waiting - it answered, or it was refused. The page uses this to
* take the busy state back off the control that was clicked. It is NOT "the rows are on screen":
* a refusal settles too, and a control left spinning over a refusal is the worse failure.
*/
onSettled?: () => void;
/**
* W54-T35: the cell's OWN rows-to-include, read off its binding by the page.
*
* β NOT THE SAME THING AS THE DRILL ANSWER'S `filter`, and the difference is worth a prop. The
* answer describes what the SERVER used for the rows on screen; this describes what the cell
* holds NOW, which is what an edit changes and what an undo restores. On a healthy save the two
* agree within one round trip. Absent, the answer is used instead, so a caller that passes
* nothing still gets a drill that states its filter.
*/
cellScope?: DrillCellScope | null;
/**
* W54-T35: persist a new filter for this cell and recompute it.
*
* β IT RESOLVES WHEN THE WRITE HAS SETTLED, which is what lets the rows be re-read afterwards
* rather than immediately: `GET β¦/drill` reads the STORED binding, so a re-read fired before
* the save landed would answer with the filter that is being replaced and paint the old rows
* over the new filter.
*/
onFilterChange?: (addr: string, tree: FilterTree) => void | Promise<void>;
/**
* C4: persist column choices for this cell. The grid reports ordered visibility; this modal
* settles the edits before calling the Sheet host's binding writer.
*/
onDisplayChange?: (addr: string, display: BindingDisplay) => void | Promise<void>;
}
export default function DrillModalEntry(props: DrillModalProps) {
return props.previewBinding
? <OverlayProvider><ViewRowsPreview {...props} previewBinding={props.previewBinding} /></OverlayProvider>
: <DrillModal {...props} />;
}
// R35 deliberately previews the resolver's own projection, not LinkGridModal's record list.
// LinkGridModal needs recordIds from a stored-cell drill, but this binding is not stored yet.
// Adding ids would change routes_sheet.py outside this ticket's fence, and a record list would
// show every field instead of the chosen fields at the chosen limit in the chosen order.
function ViewRowsPreview({ workbookId, label, previewBinding, onClose, onPlace, onSettled }:
DrillModalProps & { previewBinding: ViewBinding }) {
const requestKey = JSON.stringify([workbookId, previewBinding]);
const [viewRows, setViewRows] = useState<{
key: string; answer?: ViewRowsAnswer; error?: string;
} | null>(null);
const settledRef = useRef(onSettled);
settledRef.current = onSettled;
const panelRef = useRef<HTMLDivElement>(null);
useOverlayLayer({ panelRef, onDismiss: onClose, dismissOnOutside: false,
initialFocus: "first", restoreFocus: true, trapFocus: true });
useEffect(() => {
let live = true;
const [id, binding] = JSON.parse(requestKey) as [string, ViewBinding];
void fetchViewRows(id, binding).then((got) => {
if (!live) return;
setViewRows(got.ok ? { key: requestKey, answer: got.answer }
: { key: requestKey, error: got.message });
settledRef.current?.();
});
return () => { live = false; };
}, [requestKey]);
const current = viewRows?.key === requestKey ? viewRows : null;
const answer = current?.answer;
const headerActions = onPlace ? (
<div className="sheet-cell-view-toolbar" role="toolbar" aria-label="View controls">
<button type="button" className="lp-btn lp-btn-primary" disabled={!answer}
onClick={onPlace}>Place in sheet</button>
</div>
) : null;
const cellText = (value: unknown) => value == null ? ""
: typeof value === "object" ? JSON.stringify(value) : String(value);
return <BodyPortal>
<div className="sheet-drill-skeleton-backdrop">
<div className="sheet-drill-skeleton" role="dialog" aria-modal="true"
aria-label={label} ref={panelRef}>
<header className="sheet-drill-skeleton-head" style={{ flexDirection: "row", alignItems: "center" }}>
<h2 className="sheet-binding-title" style={{ flex: 1 }}>{label}</h2>
{headerActions}
<button type="button" className="lp-btn lp-btn-quiet" onClick={onClose}>Close</button>
</header>
<div style={{ overflow: "auto", padding: 16, minHeight: 0,
...(!current ? { flex: 1, display: "grid", placeItems: "center" } : {}) }} aria-busy={!current}>
{!current && <p className="sheet-chart-empty" role="status" style={{ margin: 0 }}>Loading viewβ¦</p>}
{current?.error && <p className="sheet-notice" role="alert">{current.error}</p>}
{answer && <>
<p className="sheet-period-note" role="status">{showingLine(answer.rows.length, answer.total)}</p>
<table style={{ width: "100%", borderCollapse: "collapse", fontSize: "var(--lp-fs-xs)" }}>
<thead><tr>{answer.fields.map((field) => <th key={field.key} scope="col"
style={{ textAlign: "left", padding: 8, borderBottom: "1px solid var(--lp-line)" }}>
{field.label}
</th>)}</tr></thead>
<tbody>{answer.rows.map((row, index) => <tr key={index}>
{answer.fields.map((field) => <td key={field.key} style={{ padding: 8,
borderBottom: "1px solid var(--lp-line)", fontVariantNumeric: "tabular-nums",
textAlign: typeof row[field.key] === "number" ? "right" : "left" }}>
{cellText(row[field.key])}
</td>)}
</tr>)}</tbody>
</table>
</>}
</div>
</div>
</div>
</BodyPortal>;
}
function DrillModal(
{
workbookId, addr, tab, label, onClose, onSettled, cellScope, onFilterChange, onDisplayChange,
onPlace, embedded = false, onNavigate,
}: DrillModalProps,
) {
const [drill, setDrill] = useState<CellDrill | null>(null);
const [error, setError] = useState("");
/** Is `LinkGridModal`'s module in hand? See `warmLinkChunk` for why this is a state and not a
* detail of Suspense. */
const [linkReady, setLinkReady] = useState(false);
/** β A REF, so a page that hands this an inline arrow does not re-run the fetch effect below on
* every one of its own renders. */
const settledRef = useRef(onSettled);
settledRef.current = onSettled;
/** Same reason, one ticket later: the page hands this an inline arrow too. */
const filterChangeRef = useRef(onFilterChange);
filterChangeRef.current = onFilterChange;
// ββ W54-T35 state βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
/**
* ββ THE UNDO, AND IT IS ONE STEP SCOPED TO THIS CELL. Owner: *"if they make a mistake etc,
* they can just CTRL + Z to return the Cell to its original filter."*
*
* ββ IT IS DELIBERATELY NOT `SheetPage`'s `historyRef`. That stack snapshots the WHOLE `sheets`
* array on every commit, so pushing a filter edit onto it would make one Ctrl+Z walk back
* whatever else the reader had typed since - an undo that reaches past the surface it was
* pressed on, into cells nobody was looking at. This holds ONE tree: the cell's filter as it
* stood before the latest grid filter edit. A second Ctrl+Z therefore has nothing to pop and does not
* go further back, which is the done-when clause spelled as a data structure rather than as a
* guard somebody has to remember to write.
*/
const [undoTree, setUndoTree] = useState<FilterTree | null>(null);
/** The tree before the current grid filter edit burst, retained for its undo step. */
const preEditRef = useRef<FilterTree | null>(null);
/** Latest grid-owned filter edit waiting for 800 ms of quiet before it reaches the cell. */
const pendingCellFilterRef = useRef<FilterTree | null>(null);
// Columns respond to the current edit while its binding write is still debounced. The base
// prevents an old draft from overriding a later host update (including undo or a refusal).
const [cellFilterDraft, setCellFilterDraft] = useState<{
base: string; tree: FilterTree;
} | null>(null);
const cellFilterTimerRef = useRef<number | null>(null);
const [cellDisplayDraft, setCellDisplayDraft] = useState<{
base: string; display: BindingDisplay;
} | null>(null);
const cellDisplayTimerRef = useRef<number | null>(null);
const pendingCellDisplayRef = useRef<{
addr: string; display: BindingDisplay; report: DrillModalProps["onDisplayChange"];
} | null>(null);
/** Bumped when a filter change has landed, so the rows are read again. */
const [reloadSeq, setReloadSeq] = useState(0);
/** Fields for the filter sentence and export, fetched once the drill has answered. */
const [fields, setFields] = useState<Field[]>([]);
const [workspace, setWorkspace] = useState<GridWorkspace | null>(null);
const [rowsResolved, setRowsResolved] = useState(false);
const [rowsError, setRowsError] = useState("");
useEffect(() => {
let live = true;
// β BOTH OUTCOMES SET IT. A chunk that fails to load is React's own error path once
// `<LinkGridModal>` renders, exactly as it was before this ticket; holding the skeleton up
// forever instead would turn a loud failure into a silent one that looks like a slow server.
void warmLinkChunk().then(
() => { if (live) setLinkReady(true); },
() => { if (live) setLinkReady(true); },
);
return () => { live = false; };
}, []);
/**
* ββ W51-T12 - THE REFUSAL CARDS CLOSE ON ESCAPE TOO, AND THAT WAS THE HOLE.
*
* The SUCCESS path already closes on Escape and needs nothing from this component:
* `CustomerGrid.tsx::LinkGridModal` calls `useOverlayLayer`, which calls
* `useEscapeClose(true, onEscape, ...)` (`customer-grid/OverlaySurface.tsx`), so the popup joined
* the base kit's topmost-wins stack in W51-T01. Verified on this branch rather than assumed.
*
* β BUT THE TWO ERROR BRANCHES BELOW RENDER OUTSIDE `LinkGridModal` - a bare `.sheet-drill-error`
* card with its own Close button and nothing else. The overlay stack never hears about them, so
* before this a reader who drilled into a database the popup cannot address got a card that
* Escape did nothing to. The claim is registered only while such a card is on screen, so the
* success path keeps exactly one claimant and the stack is never double-pushed.
*/
const cardRef = useRef<HTMLDivElement | null>(null);
const scope = drill ? scopeOf(drill.database) : null;
const showingCard = Boolean(error) || Boolean(drill && !scope);
const onEscape = useCallback(() => onClose(), [onClose]);
const escapeContainer = useCallback(() => cardRef.current as HTMLElement | null, []);
useEscapeClose(showingCard, onEscape, { container: escapeContainer });
// The mounted skeleton owns its focus trap and Escape claim until LinkGridModal replaces it.
const skeletonRef = useRef<HTMLDivElement | null>(null);
/** Every drill answer carries its request's number and only the newest lands (S68-T23 finding). */
const drillSeqRef = useRef(0);
const draftTimerRef = useRef<number | null>(null);
/** From a grid filter edit until the ids for it land: the grid's rows for the OLD ids are not an answer. */
const [idsPending, setIdsPending] = useState(false);
/**
* ββ W54-T35 β `reloadSeq` IS A DEPENDENCY AND `setDrill(null)` IS STILL NOT CALLED. A filter
* that has just been changed has to be answered again, because the ids on screen were narrowed
* by the OLD one. But clearing the answer first would unmount `LinkGridModal`, put the skeleton
* back over a card the reader is already reading, and then remount the whole grid: a blink, in
* exactly the place W54-T34 spent a ticket removing one. The previous answer stays up and is
* REPLACED when the new one lands, so only the row list changes.
*/
useEffect(() => {
let live = true;
const seq = ++drillSeqRef.current;
setIdsPending(true);
(async () => {
const got = await drillCell(workbookId, addr, tab);
if (!live) return;
settledRef.current?.();
// A newer draft drill has already answered for the grid's current filter.
if (seq !== drillSeqRef.current) return;
setIdsPending(false);
if (!got.ok) {
setError(got.message);
return;
}
setError("");
setDrill(got.value);
})();
return () => {
live = false;
};
}, [workbookId, addr, tab, reloadSeq]);
/**
* W54-T35: what the band says, and what the grid's Filter control edits.
*
* The page's own reading of the cell wins, because it is the one that MOVES: it is rebuilt from
* the workbook after every commit, so the sentence changes the moment a filter is applied. The
* drill answer is the fallback for a caller that passed none, and it is a real one rather than a
* courtesy: the server sends the scope on every drill.
*/
const shown = cellScope ?? scopeFromDrill(drill);
const shownKind = shown?.kind ?? "";
const shownTree = shown?.kind === "filter" ? shown.tree : null;
const shownDisplayKey = JSON.stringify([workbookId, addr, shown?.display ?? null]);
const cellDisplay = cellDisplayDraft?.base === shownDisplayKey
? cellDisplayDraft.display : shown?.display;
useEffect(() => {
setCellDisplayDraft((draft) => draft?.base === shownDisplayKey ? draft : null);
}, [shownDisplayKey]);
/** The cell's current tree at the instant a delayed grid edit settles. */
const shownTreeRef = useRef<FilterTree | null>(shownTree);
shownTreeRef.current = shownTree;
const shownTreeKey = JSON.stringify(shownTree);
const [relatedLabels, setRelatedLabels] = useState<{ database: string; fields: Field[] } | null>(null);
const relatedDatabase = shownTreeKey.includes('"related:') ? drill?.database : undefined;
useEffect(() => {
if (!relatedDatabase) return;
const controller = new AbortController();
void fetch(`${API_V1}/sheets/filter-fields/${encodeURIComponent(relatedDatabase)}`, {
credentials: CREDENTIALS, signal: controller.signal,
}).then(async response => {
if (!response.ok) return;
const body = await response.json();
if (!controller.signal.aborted && Array.isArray(body?.fields)) {
const labels = body.fields.flatMap((field: Field & { related?: { legacyKeys?: string[] } }) =>
[field, ...(field.related?.legacyKeys ?? []).map(key => ({ ...field, key }))]);
setRelatedLabels({ database: relatedDatabase, fields: labels });
}
}).catch(() => { /* The footer keeps its unnamed-field fallback if metadata is unavailable. */ });
return () => controller.abort();
}, [relatedDatabase]);
useEffect(() => {
setCellFilterDraft((draft) => draft?.base === shownTreeKey ? draft : null);
}, [shownTreeKey]);
// C2: read the field catalogue through the existing workspace client. Export asks for rows
// only on click; this surface owns no workspace cache or whole-table row book.
const [rowsGo, setRowsGo] = useState(false);
useEffect(() => { if (drill && linkReady) setRowsGo(true); }, [drill, linkReady]);
useEffect(() => {
if (!scope || !rowsGo) return;
let live = true;
setRowsResolved(false);
setRowsError("");
setFields([]);
setWorkspace(null);
(async () => {
const ws = await fetchWorkspace(scope, { allowCached: true, fieldsOnly: true });
if (!live) return;
if (!ws?.fields) {
setRowsError("The fields for these records could not be loaded. Reopen View data to try again.");
setRowsResolved(true);
return;
}
setWorkspace(ws);
setFields(ws.fields);
setRowsResolved(true);
})();
return () => { live = false; };
}, [scope, rowsGo]);
/** Persist a tree through the page's one binding writer, then read the rows again. */
const applyTree = useCallback(async (tree: FilterTree) => {
await Promise.resolve(filterChangeRef.current?.(addr, tree));
setCellFilterDraft((draft) => draft && sameTree(draft.tree, tree) ? null : draft);
setReloadSeq((n) => n + 1);
}, [addr]);
/**
* The grid filter panel reports every change. The cell commits only after the edit has been
* quiet for 800 ms, so typing one condition produces one write and one re-drill.
*/
/**
* S68-T23 finding: the grid re-queries the OLD drilled ids with the NEW filter at once, so until
* the cell write lets the re-drill land it painted those ids narrowed (often empty). The draft
* tree is drilled after a short pause instead; its ids reach the grid, whose window hook drops
* the stale answer for the old ids. Nothing is written here; the 800 ms write below still is.
*/
const drillDraft = useCallback((tree: FilterTree) => {
setIdsPending(true);
if (draftTimerRef.current !== null) window.clearTimeout(draftTimerRef.current);
const seq = ++drillSeqRef.current;
draftTimerRef.current = window.setTimeout(() => {
draftTimerRef.current = null;
void drillCell(workbookId, addr, tab, { filter: tree }).then((got) => {
if (seq !== drillSeqRef.current) return;
setIdsPending(false);
if (got.ok) {
setError("");
setDrill(got.value);
} else {
setError(got.message);
}
});
}, 150);
}, [workbookId, addr, tab]);
const settleCellFilter = useCallback((tree: FilterTree) => {
const current = shownTreeRef.current;
if (!current) return;
if (!sameTree(tree, current)) drillDraft(tree);
setCellFilterDraft({ base: JSON.stringify(current), tree });
if (cellFilterTimerRef.current === null) {
// One burst gets one undo step: the tree held before its first reported change.
preEditRef.current = current;
} else {
window.clearTimeout(cellFilterTimerRef.current);
}
pendingCellFilterRef.current = tree;
cellFilterTimerRef.current = window.setTimeout(() => {
cellFilterTimerRef.current = null;
const next = pendingCellFilterRef.current;
pendingCellFilterRef.current = null;
const currentTree = shownTreeRef.current;
if (!next || !currentTree || sameTree(next, currentTree)) return;
setUndoTree(preEditRef.current);
void applyTree(next);
}, 800);
}, [applyTree, drillDraft]);
useEffect(() => () => {
if (cellFilterTimerRef.current !== null)
window.clearTimeout(cellFilterTimerRef.current);
cellFilterTimerRef.current = null;
pendingCellFilterRef.current = null;
if (draftTimerRef.current !== null) window.clearTimeout(draftTimerRef.current);
draftTimerRef.current = null;
drillSeqRef.current += 1;
}, []);
const flushCellDisplay = useCallback(() => {
if (cellDisplayTimerRef.current !== null)
window.clearTimeout(cellDisplayTimerRef.current);
cellDisplayTimerRef.current = null;
const pending = pendingCellDisplayRef.current;
pendingCellDisplayRef.current = null;
if (pending) void pending.report?.(pending.addr, pending.display);
}, []);
// Mirror the filter's quiet period, but keep presentation edits when the reader closes early.
// Capture the address and writer together so a later cell cannot receive an earlier edit.
const settleCellDisplay = useCallback((display: CellDisplayChoice) => {
const next = bindingDisplay({ display });
if (!next) return;
setCellDisplayDraft({ base: shownDisplayKey, display: next });
pendingCellDisplayRef.current = { addr, display: next, report: onDisplayChange };
if (cellDisplayTimerRef.current !== null)
window.clearTimeout(cellDisplayTimerRef.current);
cellDisplayTimerRef.current = window.setTimeout(flushCellDisplay, 800);
}, [addr, shownDisplayKey, onDisplayChange, flushCellDisplay]);
useEffect(() => () => flushCellDisplay(), [workbookId, addr, flushCellDisplay]);
/**
* ββ WHERE THE KEYSTROKE ACTUALLY ARRIVES, WHICH IS NOT WHERE THE SHEET'S UNDO LIVES.
*
* Ctrl+Z on the Sheet belongs to `SheetGrid.tsx::onKeyDown` (through `shortcuts.ts`), a REACT
* handler on the grid's own wrapper. While this modal is open the grid canvas does not have
* focus - focus is trapped inside a body-level portal that is a SIBLING of the grid in the
* React tree, not a descendant - so that handler is not on the propagation path at all and
* cannot be reached from here. Nothing in lane D's file has to change, and nothing in it does.
*
* ββ WHAT IS ON THE PATH IS `CustomerGrid.tsx`'s OWN Ctrl+Z, and it is the reason this is a
* capture-phase WINDOW listener rather than a React handler. That component installs
* `window.addEventListener("keydown", onKey, true)` for its per-database undo, and the drill
* mounts a CustomerGrid inside the linked-record popup. Capture listeners on one target run in
* registration order, and this component mounts BEFORE the lazy chunk that mounts that grid, so
* this one runs first and `stopImmediatePropagation` is what keeps a filter undo from also
* popping the data grid's stack. A React handler could not have got in front of it.
*
* β THE KEY IS CLAIMED FOR AS LONG AS THE DRILL IS OPEN, INCLUDING WHEN THERE IS NOTHING TO
* UNDO. That is the second half of the done-when: a second press must not go further back, and
* the only way to guarantee that is to consume it rather than to let it fall through to
* whichever stack is next in line.
*
* β AN INPUT KEEPS ITS OWN UNDO. The same guard `CustomerGrid` uses, for the same reason: a
* caret in a condition's value box is the browser's text undo, and stealing it would be worse
* than not having ours. Ctrl+Shift+Z and Ctrl+Y are not claimed; redo is not in this ticket.
*/
const undoRef = useRef<() => void>(() => {});
undoRef.current = () => {
if (!undoTree) return;
setUndoTree(null);
void applyTree(undoTree);
};
useEffect(() => {
const onKey = (event: KeyboardEvent) => {
if (!(event.ctrlKey || event.metaKey) || event.altKey || event.shiftKey) return;
if (event.key.toLowerCase() !== "z") return;
const el = document.activeElement as HTMLElement | null;
if (el && (el.tagName === "INPUT" || el.tagName === "TEXTAREA" || el.isContentEditable))
return;
event.preventDefault();
event.stopImmediatePropagation();
undoRef.current();
};
window.addEventListener("keydown", onKey, true);
return () => window.removeEventListener("keydown", onKey, true);
}, []);
// The shared ID-window hook consumes the server page without a second row request.
const initialPage = useMemo(() => {
if (!drill?.page) return undefined;
const source = scopeFromDrill(drill);
const payload: CustomersPayload = {
fields: drill.page.fields?.length ? drill.page.fields : fields,
rows: drill.page.rows,
today: drill.page.today,
recordsMutable: drill.page.recordsMutable,
limits: dropAppliedFilterLimits(drill.page.limits, source?.kind === "filter" ? source.tree : undefined),
counts: { shown: drill.page.rows.length, matched: drill.count,
total: drill.page.totalUnfiltered ?? drill.count, windowed: true },
};
return { offset: drill.page.offset, limit: drill.page.limit, token: drill.token, payload,
filter: source?.kind === "filter" ? source.tree : undefined };
}, [drill, fields]);
const rowSource = useMemo<EmbeddedRowSource | undefined>(() => {
if (!drill || drill.record_ids_scope !== "page") return undefined;
const source = scopeFromDrill(drill);
const filter = source?.kind === "filter" ? source.tree : undefined;
const read = async (query: import("./sheetApi").CellDrillQuery, offset = 0, limit = 100) => {
const got = await drillCell(workbookId, addr, tab, { query, offset, limit, filter });
if (!got.ok) { setRowsError(got.message); return null; }
return got.value;
};
return {
key: JSON.stringify([workbookId, addr, tab, drill.population, drill.filter, drill.view_id, reloadSeq]),
readGroups: async (request, by, aggs, offset, size) => {
const value = await read({ filters: request.filters, filterConj: request.filterConj,
search: request.search, groupBy: by, aggs, groupOffset: offset, groupLimit: size });
const summary = value?.summary;
if (!summary || !Array.isArray(summary.groups) || typeof summary.total_groups !== "number")
throw new Error("Groups could not be read for this window.");
if (summary.limits.length)
throw new Error(summary.limits.map(limit => limit.cause).filter(Boolean).join(". "));
return { groups: summary.groups as { key: string | number | null; label: string; count: number;
aggregates: Record<string, number | null> }[], totalGroups: summary.total_groups,
totalRows: summary.total_rows, aggregates: summary.aggregates };
},
readWindow: async (request) => {
const value = await read({ filters: request.filters, filterConj: request.filterConj,
sorts: request.sorts, search: request.search, group: request.group }, request.offset, request.limit);
if (!value?.page) return null;
const page = value.page;
return { ...initialPage?.payload, fields: page.fields?.length ? page.fields : fields,
rows: page.rows, today: page.today, recordsMutable: page.recordsMutable,
limits: dropAppliedFilterLimits(page.limits, filter),
counts: { shown: page.rows.length, matched: value.count,
total: page.totalUnfiltered ?? value.count, windowed: true } };
},
readAggregates: async (request) => {
let offset = 0;
let answer: ReturnType<typeof aggregatePayload> = null;
let total: number | undefined;
let population: string | null | undefined;
do {
const value = await read({ filters: request.filters, filterConj: request.filterConj,
search: request.search, aggs: request.aggs, groupBy: request.groupBy,
groupOffset: offset, groupLimit: 1000 });
const summary = value?.summary;
const page = summary ? aggregatePayload(summary) : null;
if (!page || !summary) return null;
if (!request.groupBy) return page;
const progress = aggregatePageProgress(summary, offset, page.groups?.length, total);
if (!progress) return null;
if (!progress.done && !value?.population) return null;
if (!answer) { answer = page; total = summary.total_groups; population = value?.population; }
else {
if (value?.population !== population || total !== summary.total_groups
|| page.totalRows !== answer.totalRows
|| JSON.stringify(page.aggregates) !== JSON.stringify(answer.aggregates)) return null;
answer.groups = [...(answer.groups ?? []), ...(page.groups ?? [])];
}
offset += page.groups?.length ?? 0;
if (progress.done) return answer;
} while (true);
},
};
}, [drill, workbookId, addr, tab, reloadSeq, initialPage, fields]);
const identityField = fields.find((field) => field.pinned) ?? fields[0] ?? null;
const savedView = drill?.view_id
? workspace?.views?.find((view) => view.id === drill.view_id) ?? null
: null;
const fieldFilter: FilterTree | null = shown?.kind === "filter"
? (cellFilterDraft?.base === shownTreeKey ? cellFilterDraft.tree : shown.tree)
: savedView
? { conj: savedView.config.filterConj, nodes: savedView.config.filters }
: null;
const forcedFieldKeys = cellForcedFieldKeys(
fieldFilter, shown?.aggregateField, shown?.stepField, fields,
);
const defaultFieldKeys = fields
.filter((field) => field.default !== false
&& (field.custom !== true || Boolean(field.measure))
&& field.shared !== true)
.map((field) => field.key);
const visibleKeys = cellViewVisibleKeys(
defaultFieldKeys,
cellDisplay?.visible ?? [],
forcedFieldKeys,
fields.map((field) => field.key),
identityField?.key ?? "",
);
const visibleFields = visibleKeys
.map((key) => fields.find((field) => field.key === key))
.filter((field): field is Field => Boolean(field));
// CustomerGrid's own value-edit predicate. It distinguishes source-locked values, machine-
// written pre-set fields and viewer grants field by field instead of inventing one read-only flag.
const canEditRows = Boolean(
workspace?.fields && fields.some((field) => mayEditField(field, workspace?.viewer)),
);
const exportReady = rowsResolved && Boolean(workspace?.fields);
const editInData = useCallback(() => {
if (!drill || !canEditRows) return;
onClose();
const address = {
database: drill.database,
...(drill.view_id ? { view: drill.view_id } : {}),
};
if (embedded) onNavigate?.(address);
else window.location.hash = dataPathHash(address);
}, [canEditRows, drill, embedded, onClose, onNavigate]);
const exportButtonRef = useRef<HTMLButtonElement>(null);
const [exportOpen, setExportOpen] = useState(false);
const [exporting, setExporting] = useState(false);
const exportCell = useCallback(async (format: "csv" | "xlsx" | "pdf" | "json") => {
if (!drill || !exportReady || exporting) return;
setExportOpen(false);
setExporting(true);
setRowsError("");
try {
const first = drill.page?.offset === 0 ? drill.page : undefined;
const recordRows: Row[] = [];
const recordIds = new Set<number>();
let offset = 0;
if (!drill.population) throw new Error("These records have no freshness stamp. Reopen View data and try Export again.");
if (!Number.isSafeInteger(drill.count) || drill.count < 0)
throw new Error("These records have no complete count. Reopen View data and try Export again.");
while (offset < drill.count) {
const got = await drillCell(workbookId, addr, tab, { offset, limit: 1000,
filter: drill.view_id ? undefined : drill.filter, query: drill.query });
if (!got.ok) throw new Error(got.message);
if (!got.value.page) throw new Error("The records for Export did not include a page. Try again.");
if (got.value.population !== drill.population || got.value.count !== drill.count)
throw new Error("These records changed while Export was preparing. Try again.");
if (got.value.page.offset !== offset || got.value.page.total !== drill.count
|| got.value.page.rows.length > drill.count - offset)
throw new Error("Some records could not be read. Try Export again.");
if (!got.value.page.rows.length)
throw new Error("These records changed while Export was preparing. Try again.");
for (const row of got.value.page.rows) {
if (!Number.isSafeInteger(row.pid) || recordIds.has(row.pid))
throw new Error("Some records could not be read. Try Export again.");
recordIds.add(row.pid);
}
recordRows.push(...got.value.page.rows);
offset += got.value.page.rows.length;
}
if (recordRows.length !== drill.count) throw new Error("Some records could not be read. Try Export again.");
const exporter = await import("../customer-grid/export");
exporter.runExport(format, `${label} records`, first?.today, visibleFields, recordRows);
} catch (cause) {
setRowsError(cause instanceof Error ? cause.message : "These records could not be prepared for Export.");
} finally {
setExporting(false);
}
}, [drill, exportReady, exporting, workbookId, addr, tab, label, visibleFields]);
/**
* The sentence. β NOT MEMOISED, and that is measured rather than lazy: `filterSentence` walks
* at most three live leaves and stops, so a memo keyed on a `shown` the page rebuilds every
* render would recompute exactly as often while costing an extra comparison.
*/
const sentenceFields = relatedLabels && relatedLabels.database === drill?.database
? [...fields, ...relatedLabels.fields] : fields;
const said = shown?.kind === "filter" ? filterSentence(shown.tree, sentenceFields) : "";
const bandText = !shown
? ""
: shown.kind === "view"
// ββ W57-T21 - THE BAND CARRIES THE EDITING LIMIT NOW, because the control that used to
// carry it is gone. The deleted Edit filter button was DISABLED on this branch with a title
// saying where the filter is changed instead; without a replacement the grid's own Filter
// control would sit there looking editable and quietly write nothing back, which is standing
// rule 1's second sentence exactly: a limit that cannot be removed is REPORTED, never
// silently enforced.
? (shown.name
? `Rows come from the saved view ${shown.name}, so this cell's filter is changed in Table`
: "Rows come from a saved view, so this cell's filter is changed in Table")
// β THE FALLBACK IS THE COUNT, NOT A SECOND SENTENCE. `filterSentence` answers "" when the
// filter narrows nothing, which covers both an empty tree and one whose conditions are all
// still half typed; `conditionCountLabel` keeps the wording shared with the filter kit.
: said ? `Rows where ${said}` : conditionCountLabel(shown.tree);
// S66-T48: stated beside the rows, never enforced silently (standing rule 1).
const capText = drillCapText(drill);
if (error) {
// A refusal is a plain sentence naming the cause and the subject, per the design contract.
// It is NOT rendered inside the popup: the popup is a grid of rows, and an error is not a row.
return (
<div className="sheet-drill-error" role="alert" ref={cardRef}>
<p>{error}</p>
<button type="button" className="sheet-action" onClick={onClose}>
Close
</button>
</div>
);
}
// ββ W54-T34 β THIS WAS `return null`, AND IT IS THE OWNER'S REPORT IN ONE LINE. For as long as
// the drill is in flight the reader got a blank screen, which is what a dead control also looks
// like. The surface opens immediately and fills in.
if (!drill) return <DrillSkeleton label={label} nodeRef={skeletonRef} onClose={onClose} />;
if (!scope) {
// Named rather than swallowed: a database the popup cannot address is a real gap, and a blank
// popup would look like "no rows" - the wrong answer, delivered convincingly.
return (
<div className="sheet-drill-error" role="alert" ref={cardRef}>
<p>{`Rows for ${drill.database} cannot be opened from a cell yet.`}</p>
<button type="button" className="sheet-action" onClick={onClose}>
Close
</button>
</div>
);
}
return (
// ββ W54-T34 REVERSED THIS FALLBACK, DELIBERATELY. It read `fallback={null}` under the note
// "the popup either opens or it does not, and a skeleton behind a modal that is about to cover
// it would be a flash of furniture nobody asked for". That was a true statement about a tree
// with no skeleton in it: the choice then was between nothing and a brand new surface appearing
// for one frame. The same skeleton is now ALREADY on screen when the answer lands, so passing
// it here does not add a surface, it declines to REMOVE one - the chunk loads under the same
// card the reader has been looking at, and the popup replaces it in place. Handing `null` here
// now would blink the screen back to empty at the last moment, which is the defect this ticket
// exists to remove, arriving one step later.
/**
* ββ ONE `OverlayProvider` OVER EVERY LAYER THIS CARD OPENS, AND IT IS STILL LOAD-BEARING
* AFTER W57-T21 DELETED THE EDIT DOOR. `useOverlayLayer` defers to a higher layer only when it
* can SEE one: `if (!dismissOnOutside || (stack && !stack.isTop(id))) return;`, where `stack`
* is `useContext(OverlayStackContext)`. The Sheet route mounts no provider of its own, so
* `LinkGridModal` would run with `stack === null` and read a pointerdown ANYWHERE outside its
* own card as a dismissal, including one inside a layer opened on top of it. The Export menu
* below is exactly such a layer, and so is every filter, field and sort popover the grid's own
* chrome opens now that the chrome is the only filter door. Both register here instead, the
* later one is topmost, and the card stands down while it is up. `filter-kit/SheetFilterPopup.tsx`
* documents the same trap one layer further out.
*
* β ESCAPE IS UNAFFECTED AND STILL RESOLVES TO EXACTLY ONE SURFACE. That is the module-level
* stack in `ui/useEscapeClose`, not this one: the card claims when it mounts, a popover claims
* when it opens and is therefore topmost, so one press closes the popover and the next closes
* the drill. The band claims nothing: it is a statement inside the card, not an overlay.
*/
<OverlayProvider>
<Suspense fallback={<DrillSkeleton label={label} nodeRef={skeletonRef} onClose={onClose} />}>
<LinkGridModal
label={label}
table={scope}
recordIds={drill.record_ids}
rowSource={rowSource}
{...{ initialPage, idsPending }}
editable={false}
cellView
cellFields={visibleKeys}
onCellDisplayChange={settleCellDisplay}
// A view-bound cell passes neither prop: its rows remain the saved view's business.
cellFilter={shownTree ?? undefined}
onCellFilterChange={shownKind === "filter" ? settleCellFilter : undefined}
headerActions={(
<div className="sheet-cell-view-toolbar" role="toolbar" aria-label="Cell View controls">
{onPlace && <button type="button" className="lp-btn lp-btn-primary"
onClick={onPlace}>Place in sheet</button>}
{canEditRows && (
<button type="button" className="sheet-cell-view-action" onClick={editInData}>
<svg viewBox="0 0 16 16" aria-hidden="true">
<path d="m3 11.8-.3 2.1 2.1-.3 7.9-7.9-1.8-1.8zM9.9 4.9l1.8 1.8" />
</svg>
<span>Edit rows</span>
</button>
)}
<button
ref={exportButtonRef}
type="button"
className="sheet-cell-view-action"
aria-haspopup="menu"
aria-expanded={exportOpen}
disabled={!exportReady || exporting || idsPending}
onClick={() => setExportOpen((open) => !open)}
>
<svg viewBox="0 0 16 16" aria-hidden="true">
<path d="M8 2v8M5 7l3 3 3-3M3 12.5h10" />
</svg>
<span>{exporting ? "Preparing" : "Export"}</span>
</button>
</div>
)}
footer={bandText || capText || rowsError || drill.count === 0
? <>
{drill.count === 0 && (
<DrillFilterBand text="No records match this cell's filter." />
)}
{rowsError && <DrillFilterBand text={rowsError} />}
{capText && <DrillFilterBand text={capText} />}
{bandText && <DrillFilterBand text={bandText} />}
</>
: undefined}
onClose={onClose}
/>
</Suspense>
{exportOpen && exportButtonRef.current && (
<AnchoredOverlay
anchor={exportButtonRef.current}
className="sheet-cell-export-pop"
placement="bottom-end"
onDismiss={() => setExportOpen(false)}
role="menu"
ariaLabel="Export matching records"
dataKind="sheet-cell-export"
>
{(["csv", "xlsx", "pdf", "json"] as const).map((format) => (
<button
type="button"
role="menuitem"
className="sheet-cell-export-choice"
onClick={() => { void exportCell(format); }}
key={format}
>
{format === "xlsx" ? "Excel" : format === "pdf" ? "PDF" : format.toUpperCase()}
</button>
))}
</AnchoredOverlay>
)}
</OverlayProvider>
);
}
// sheet/DrillModal.tsx β a bound cell's rows, in the Link field's own popup (W49-T07, R6/R13/R17).
//
// ββ R6 SAYS "EXACTLY THE LINK FIELD TYPE'S POPUP UI", SO THIS REUSES THE COMPONENT RATHER THAN
// ITS APPEARANCE. `LinkGridModal` is imported from `customer-grid/CustomerGrid.tsx`. Rebuilding a
// lookalike would give the product two
// popups that behave almost the same, and "almost" is where a focus trap or an escape key goes
// missing on one of them.
//
// R13 requires live rows and counts. The drill returns an exact count and page IDs.
// Its caller-owned row source replays structured queries under current permissions.
// Page IDs identify rows already read and never restrict the remaining population.
//
// β R13 ALSO FORBIDS DISCLOSING STALENESS HERE. A stale cell opens the same popup with the same
// chrome and NO comparison text: no "was 24,920", no badge, nothing. The staleness is a property of
// the CELL and it is marked on the grid; repeating it here would be answering a question the person
// did not ask, at the moment they asked a different one.
//
// ββ W54-T34 (owner instruction 10) β NINE SECONDS OF NOTHING WAS THE DEFECT.
// Owner, verbatim: *"Clicking View rows still takes a long time; if it must, we need a loading
// button so the user knows their click worked."* This component used to render `null` for the whole
// of that wait, so a drill that was working and a click that never landed looked identical. Measured
// on tenant #0 (`AutoWiki/waves/wave54/lanes/E/T36-baseline.md`): `drill_cell` costs 55 to 90 ms
// against a `ut_*` table but 9,248 to 9,448 ms against `customer_data`, which goes through the
// registry-module mirror rather than a DuckDB query. So the wait is real and it is long.
//
// β BOTH `null`S WERE THE DEFECT, NOT ONE. The request had no loading state and neither did the
// LAZY CHUNK behind it, so a warm answer could still be followed by a second blank window while
// 1,850 kB of `CustomerGrid` downloaded. The Suspense fallback's old note argued that "a skeleton
// behind a modal that is about to cover it would be a flash of furniture nobody asked for" - which
// was right when there was no skeleton at all and the two states were nothing and everything. Now
// the skeleton is ALREADY on screen when the answer lands, so keeping it up for the chunk is
// CONTINUITY rather than new furniture: the surface never blinks back to nothing.
//
// ββ W54-T35 (owner instruction 8, ruling R8) β THE ROWS ARE HERE, SO THE REASON FOR THEM
// SHOULD BE TOO. Owner, verbatim: *"the Filter module itself will show exactly what the filter is
// when we click 'View row' so its easy for user also to know what this filter is. In fact, they
// should be able to change the filter there too. And if they make a mistake etc, they can just
// CTRL + Z to return the Cell to its original filter."* Three clauses, and each one is a decision
// recorded beside the code that answers it: the BAND (`DrillFilterBand`) states it, the grid's
// Filter control edits it, and one cell-scoped step of undo takes it back.
//
// ββ W56-T24 / R4 / C4 β THE LINK MODAL NOW OWNS ORDINARY SLOTS FOR THE SHEET'S CHROME.
// The toolbar and filter statement are children of the modal's header and footer, so they remain
// inside its focus trap and dismissal boundary without querying the DOM or waiting for a frame.
// The body is the default `CustomerGrid` export itself, with `cellView` relaxing only its embedded
// mode-switcher withholding. The embedded write and workspace guards remain untouched.
//
// β THE REAL FOOTER MAY WEAR `.cg-link-grid-foot`, WHICH THE SKELETON ABOVE MAY NOT. The rule that
// stops `DrillSkeleton` borrowing `customer-grid/RecordDetail.css` is that the skeleton stands in
// for a chunk that has not arrived, so on a cold cache its class names would exist and its rules
// would not. `LinkGridModal` renders that footer only after the same chunk is in hand, so its
// stylesheet is guaranteed present. Same file, opposite verdict, for one reason: WHEN it paints.
import { Suspense, lazy, useCallback, useEffect, useMemo, useRef, useState } from "react";
import { API_V1, CREDENTIALS } from "../apiContract";
import { aggregatePageProgress, aggregatePayload, fetchWorkspace } from "../customer-grid/apiBridge";
import { dropAppliedFilterLimits } from "../customer-grid/drillLimits";
import type { SurfaceScope } from "../customer-grid/apiBridge";
import type { CellDisplayChoice, EmbeddedRowSource } from "../customer-grid/CustomerGrid";
import { dataPathHash } from "../customer-grid/dataPath";
import { AnchoredOverlay, BodyPortal, OverlayProvider, useOverlayLayer } from "../customer-grid/OverlaySurface";
import type { CustomersPayload, Field, FilterTree, GridWorkspace, Row } from "../customer-grid/types";
import { mayEditField } from "../customer-grid/types";
import { conditionCountLabel, filterSentence } from "../filter-kit/SheetFilterPopup";
import { useEscapeClose } from "../ui/useEscapeClose";
import { cellForcedFieldKeys, cellViewVisibleKeys } from "./bindingRefs";
import { drillCell } from "./sheetApi";
import type { CellDrill } from "./sheetApi";
import type { BindingDisplay, ViewBinding, ViewRowsAnswer } from "./types";
import { bindingDisplay } from "./types";
import { fetchViewRows, showingLine } from "./viewPlacement";
import "../styles/sdlc80/drill.css";
/**
* ββ LAZY, AND THE BUILD IS WHAT SAID SO. A plain `import { LinkGridModal } from
* "../customer-grid/CustomerGrid"` compiles and typechecks perfectly, and it quietly defeats the
* code-splitting of a 1,850 kB chunk. Rollup reported it as
* `INEFFECTIVE_DYNAMIC_IMPORT: CustomerGrid.tsx is dynamically imported by App.tsx,
* RecordDetail.tsx, QueryPage.tsx and Shell.tsx but also statically imported by DrillModal.tsx,
* dynamic import will not move module into another chunk` - which in practice means opening the
* Sheet page downloads the whole customer grid before anyone has drilled into anything.
*
* β `React.lazy` wants a DEFAULT export and `LinkGridModal` is a named one, so the promise is
* mapped. That is the whole trick: the export stays named and the split remains intact while
* W56-T24 extends the modal through optional props.
*/
const LinkGridModal = lazy(() =>
import("../customer-grid/CustomerGrid").then((m) => ({ default: m.LinkGridModal })),
);
/**
* ββ W54-T34 β THE CHUNK IS ASKED FOR WHEN THE READER ASKS FOR THE ROWS, NOT AFTER THEY ARRIVE.
*
* `React.lazy` starts its import on the first render that actually reaches `<LinkGridModal>`, which
* on the success path is AFTER the drill has answered. On `customer_data` that is nine seconds, and
* the 1,850 kB download then begins from zero: two waits, back to back, for one click. Warming the
* module the moment this component mounts runs them together instead. Nothing is imported twice -
* the two dynamic imports name the same module, so the second one resolves off the registry.
*
* β AND THE BOOLEAN IT FEEDS IS NOT A CONVENIENCE, IT IS THE ESCAPE CLAIM. `LinkGridModal` joins