Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

docs(frontend): say what the tooltip reaches, and what the rule reserves

zchpeter6b44aa6010e3
diff --git a/docs/design/timestamp-display.md b/docs/design/timestamp-display.md
index 6e547f00b3..a29aaf3e1a 100644
--- a/docs/design/timestamp-display.md
+++ b/docs/design/timestamp-display.md
@@ -113,10 +113,15 @@ deferred.
**D6 — Full date-time tooltip on every reduced display.**
Any timestamp that does not show the full form — relative, date-only after the switch, or the
compact history tier — carries the full absolute date-time with seconds and timezone in its
-tooltip. This is the universal escape hatch that keeps every reduced cell recoverable. The rule
-cuts both ways: a tooltip carries only what its label hides, so a label already showing the full
-instant gets none of it repeated. Corollary: a context that cannot host a tooltip —
-i18n-interpolated strings, exports, titles — carries the full-precision string itself.
+tooltip. This is the escape hatch that keeps a reduced cell recoverable — for a pointer. The
+shared tooltip's trigger is a plain span that takes no focus, so a hidden reading is not reachable
+by keyboard or touch, and a reduced label is all those readers get. Operational times are
+unaffected, since they carry their zone in the visible string, which is what D5's safety rests on;
+what a keyboard reader cannot recover is the seconds and zone behind a queue or compact label.
+Closing that would make every tooltip in the app a tab stop, which is a larger decision than this
+design. The rule cuts both ways: a tooltip carries only what its label hides, so a label already
+showing the full instant gets none of it repeated. Corollary: a context that cannot host a tooltip
+— i18n-interpolated strings, exports, titles — carries the full-precision string itself.
**D7 — History views carry two precision tiers.**
*A history row orients; a history record testifies.* Full precision (seconds + timezone,
@@ -288,11 +293,11 @@ no seconds per D5. Relative age may accompany it in the tooltip.
modules that define the readings, it rejects `read` and `nextChangeAt` reached as a member —
under an alias, through a local, through a table, through `.call`, passed as a callback,
optionally chained, or keyed by a literal — destructured one member at a time, and defined
- on an object, which is what keeps a display from assembling a reading of its own. Two
- spellings get past it, both measured: a key held in a variable, and a destructure taking both
- members at once. Neither is what anyone writes by accident. Test files are excluded, since a
- test builds a reading and reads it directly, and matching the member reserves both names
- across the app — a permission object spelled `{ read: true }` would be reported too. The rule
+ on an object, which is what keeps a display from assembling a reading of its own. What gets
+ past it, measured: a key that is not a plain identifier or quoted string, and a destructure of
+ two or more properties. Neither is what anyone writes by accident. Test files are excluded,
+ since a test builds a reading and reads it directly, and matching the member reserves both
+ names across the app — a permission object spelled `{ read: true }` would be reported too. The rule
is the convention; the plugin is what makes drifting off it loud.
- **The shared clock accepts any instant.** Deadlines are wall-clock instants but timers skip time
the machine sleeps, so the clock re-checks at least once a minute: a display is at most a
@@ -387,6 +392,11 @@ masking-exemption expiry label, the sample-instance expiry alert, and the access
badge.
The rule governs displays of time. Two kinds of clock read stay outside it: **query membership** —
-the masking-exemption status filter, the role-expiry reminder's "within two days" list — which,
-like the fetched data itself, reflects when the query ran; and the **input side**, the validation
-of an expiration being entered, deferred with the pickers.
+the masking-exemption status filter, the role-expiry reminder's "within two days" list — which
+reflects when the list was last computed, not the passing second; and the **input side**, the
+validation of an expiration being entered, deferred with the pickers. Where that list is computed
+server-side, that is when the query ran. Where it is computed in the browser, as the
+masking-exemption filter is, it is whenever the page last re-rendered for some other reason — so a
+grant already showing its own expiry label, which is on the clock, can still sit under the Active
+filter. Moving the bucket with the label would mean rows leaving a list while someone reads it,
+which is a product call this design does not make.
diff --git a/frontend/biome-plugins/time-reading-through-hook.grit b/frontend/biome-plugins/time-reading-through-hook.grit
index 747ed21f78..ce79d60b1e 100644
--- a/frontend/biome-plugins/time-reading-through-hook.grit
+++ b/frontend/biome-plugins/time-reading-through-hook.grit
@@ -5,15 +5,16 @@
//
// The rule is about the member, not the name it is reached through, so this
// matches `read` and `nextChangeAt` wherever they are named: under an alias,
-// through a local or a table, via `.call`, passed as a callback, optionally
-// chained, keyed by a literal, or destructured one member at a time. It also
-// rejects an object that defines those members, which is what keeps readings
-// in the modules below rather than assembled at a display.
+// through a local or a table, via `.call`, passed as a callback, or optionally
+// chained. It also rejects an object that defines those members, which is what
+// keeps readings in the modules below rather than assembled at a display.
//
-// Two spellings escape it, both measured rather than assumed: a key held in a
-// variable, and a destructure taking both members at once, which Grit's object
-// snippets match by exact arity. Neither is a spelling anyone reaches for by
-// accident, and the member match catches every ordinary one.
+// Where it stops, measured rather than assumed, is a key that is not a plain
+// identifier or quoted string -- `x[key]` and ``x[`read`]`` both get past it --
+// and a destructuring pattern of two or more properties, including one with a
+// rest element. Object literals are caught at any size; only patterns are
+// limited that way. None of these is a spelling anyone reaches for by accident,
+// and the member match catches every ordinary one.
//
// `$object?.read` cannot be written as `$object?.$member` -- that snippet
// matches nothing here, so the two literal forms stay.
@@ -24,10 +25,13 @@
// reading and reads it directly, since that is how it checks one at all.
//
// Matching the member rather than the receiver reserves these two names across
-// src/: a permission object spelled `{ read: true }`, or a stream reader's
-// `.read()`, would be reported although neither has anything to do with time.
-// Neither exists in src/ today. If one arrives, rename it or exclude the file
-// in biome.json -- the rule cannot tell them apart, and that is the price of
+// src/, and more widely than it first looks. A stream reader's `.read()` is
+// reported, and because the object-literal alternative uses `contains`, so is
+// any object literal with an identifier `read` anywhere beneath it: `{ onRead:
+// read }`, or a nested `{ handlers: { read } }`, which reports twice -- once
+// for each literal. None of this has anything to do with time, and none of it
+// exists in src/ today. If one arrives, rename it or exclude the file in
+// biome.json: the rule cannot tell them apart, and that is the price of
// catching the spellings a name-based rule missed.
language js
diff --git a/frontend/src/components/HumanizeTs.test.tsx b/frontend/src/components/HumanizeTs.test.tsx
index 73d0250b54..4d30a75c7c 100644
--- a/frontend/src/components/HumanizeTs.test.tsx
+++ b/frontend/src/components/HumanizeTs.test.tsx
@@ -2,9 +2,17 @@ import { act } from "react";
import { createRoot } from "react-dom/client";
import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
-// The real datetime module is loaded below for its domain check, and it reads
-// the active locale from here rather than from the react-i18next mock.
-vi.mock("@/lib/i18n", () => ({ default: { language: "en-US" } }));
+// The real datetime module is loaded below for its domain check, and importing
+// it reaches this one. Stubbed so a test does not boot i18next and pull every
+// locale bundle, and backed by the same state as the stub above so the file has
+// one active language rather than two that happen not to meet.
+vi.mock("@/lib/i18n", () => ({
+ default: {
+ get language() {
+ return language.current;
+ },
+ },
+}));
// Enough of react-i18next to carry the one thing a timestamp depends on: a
// component that calls useTranslation re-renders when the language changes.
@@ -115,6 +123,7 @@ describe("HumanizeTs", () => {
beforeEach(() => {
vi.useFakeTimers();
vi.setSystemTime(new Date("2026-03-02T12:00:00Z"));
+ language.current = "en";
formatters.formatAbsoluteDateTime.mockClear();
});
@@ -190,17 +199,20 @@ describe("HumanizeTs", () => {
expect(container.textContent).toBe("");
});
- test("re-reads every label when the language changes", () => {
- // The only thing that re-renders a timestamp on a language switch is its
- // own useTranslation subscription: a reading holds no locale, and a fixed
- // one holds no subscription to the clock either.
- const { container, root } = mount();
- act(() => root.render(<HumanizeTs tsMs={1_000_000} mode="compact" />));
- expect(container.textContent).toContain("compact:1000000:en");
+ test.each(["compact", "operational", "datetime"] as const)(
+ "re-reads a %s label when the language changes",
+ (mode) => {
+ // The only thing that re-renders a timestamp on a language switch is its
+ // own useTranslation subscription: a reading holds no locale, and a fixed
+ // one holds no subscription to the clock either.
+ const { container, root } = mount();
+ act(() => root.render(<HumanizeTs tsMs={1_000_000} mode={mode} />));
+ expect(container.textContent).toContain(":1000000:en");
- act(() => language.switchTo("zh-CN"));
- expect(container.textContent).toContain("compact:1000000:zh-CN");
- });
+ act(() => language.switchTo("zh-CN"));
+ expect(container.textContent).toContain(":1000000:zh-CN");
+ }
+ );
test("omits the tooltip when tooltip is false", async () => {
const { container, root } = mount();
diff --git a/frontend/src/routes/project/DatabaseChangelogDetailPage.test.tsx b/frontend/src/routes/project/DatabaseChangelogDetailPage.test.tsx
index c9df236668..c6572d388b 100644
--- a/frontend/src/routes/project/DatabaseChangelogDetailPage.test.tsx
+++ b/frontend/src/routes/project/DatabaseChangelogDetailPage.test.tsx
@@ -235,7 +235,6 @@ vi.mock("@/utils", () => ({
};
},
bytesToString: (size: number) => `${size} B`,
- formatAbsoluteDateTime: () => "formatted time",
extractDatabaseResourceName: (name: string) => ({
instance: "instances/inst1",
instanceName: "inst1",
diff --git a/frontend/src/routes/project/database-detail/panels/DatabaseOverviewPanel.test.tsx b/frontend/src/routes/project/database-detail/panels/DatabaseOverviewPanel.test.tsx
index 517dfbfd92..5257e99f28 100644
--- a/frontend/src/routes/project/database-detail/panels/DatabaseOverviewPanel.test.tsx
+++ b/frontend/src/routes/project/database-detail/panels/DatabaseOverviewPanel.test.tsx
@@ -143,29 +143,21 @@ vi.mock("@/stores/app/databaseCatalog", () => ({
getTableCatalog: mocks.getTableCatalog,
}));
+// A rendering that never changes on its own, which is every reading this
+// panel shows.
+const fixedReading = (read: (ms: number) => string) => ({
+ read,
+ nextChangeAt: () => Number.POSITIVE_INFINITY,
+});
+
vi.mock("@/utils/datetime", async (importOriginal) => ({
...(await importOriginal<typeof import("@/utils/datetime")>()),
- queueTimeReading: {
- read: mocks.formatRelativeTime,
- nextChangeAt: () => Number.POSITIVE_INFINITY,
- },
- relativeTimeReading: {
- read: mocks.formatRelativeTime,
- nextChangeAt: () => Number.POSITIVE_INFINITY,
- },
+ queueTimeReading: fixedReading(mocks.formatRelativeTime),
+ relativeTimeReading: fixedReading(mocks.formatRelativeTime),
+ compactTimeReading: fixedReading(mocks.formatAbsoluteDateTime),
+ operationalTimeReading: fixedReading(mocks.formatAbsoluteDateTime),
+ absoluteTimeReading: fixedReading(mocks.formatAbsoluteDateTime),
formatAbsoluteDateTime: mocks.formatAbsoluteDateTime,
- compactTimeReading: {
- read: mocks.formatAbsoluteDateTime,
- nextChangeAt: () => Number.POSITIVE_INFINITY,
- },
- operationalTimeReading: {
- read: mocks.formatAbsoluteDateTime,
- nextChangeAt: () => Number.POSITIVE_INFINITY,
- },
- absoluteTimeReading: {
- read: mocks.formatAbsoluteDateTime,
- nextChangeAt: () => Number.POSITIVE_INFINITY,
- },
}));
vi.mock("@/utils", () => ({
@@ -173,7 +165,6 @@ vi.mock("@/utils", () => ({
getDatabaseEngine: mocks.getDatabaseEngine,
getInstanceResource: mocks.getInstanceResource,
getDatabaseProject: mocks.getDatabaseProject,
- formatAbsoluteDateTime: mocks.formatAbsoluteDateTime,
hasIndexSizeProperty: mocks.hasIndexSizeProperty,
isDev: mocks.isDev,
hasProjectPermissionV2: mocks.hasProjectPermissionV2,