react-autoql 8.36.1 → 8.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-autoql",
-  "version": "8.36.1",
+  "version": "8.37.0",
   "description": "React Widget Library",
   "main": "dist/autoql.cjs.js",
   "module": "dist/autoql.esm.js",
@@ -42,11 +42,6 @@
     "cz": "npx git-cz"
   },
   "style": "dist/autoql.esm.css",
-  "husky": {
-    "hooks": {
-      "pre-push": "cross-env NODE_OPTIONS= npx jest --clearCache && cross-env NODE_OPTIONS= npm run test"
-    }
-  },
   "lint-staged": {
     "*.js": [
       "npm run test:staged"
@@ -64,13 +59,14 @@
   },
   "dependencies": {
     "@react-icons/all-files": "4.1.0",
-    "autoql-fe-utils": "1.12.2",
+    "autoql-fe-utils": "1.13.2",
     "axios": "^1.16.0",
     "caniuse-lite": "1.0.30001692",
     "classnames": "2.5.1",
     "d3-array": "2.3.3",
     "d3-axis": "1.0.12",
     "d3-force": "^3.0.0",
+    "d3-hierarchy": "^3.1.2",
     "d3-sankey": "^0.12.3",
     "d3-scale": "4.0.2",
     "d3-selection": "3.0.0",
@@ -139,6 +135,11 @@
     "@rollup/plugin-terser": "^1.0.0",
     "@testing-library/jest-dom": "6.4.2",
     "@testing-library/react": "12.1.2",
+    "@tiptap/core": "3.32.0",
+    "@tiptap/extensions": "3.32.0",
+    "@tiptap/markdown": "3.32.0",
+    "@tiptap/pm": "3.32.0",
+    "@tiptap/starter-kit": "3.32.0",
     "ajv": "^8.20.0",
     "autoprefixer": "10.4.16",
     "axios-mock-adapter": "1.18.1",

package/src/index.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react'
-import type { Authentication } from 'autoql-fe-utils'
+import type { Authentication, PushMessageData } from 'autoql-fe-utils'
 
 export * from 'autoql-fe-utils'
 
@@ -256,7 +256,26 @@ export interface DashboardProps {
   [key: string]: any
 }
 
-export declare class Dashboard extends React.Component<DashboardProps> {}
+export declare class Dashboard extends React.Component<DashboardProps> {
+  // What the chosen tiles show now, for a report: each tile captured as "Add to Report…" captures it
+  // (QueryOutput.captureForReport). Without tileKeys, every tile in reading order.
+  captureTilesForReport(options?: {
+    tileKeys?: Array<string | number>
+    maxTableRows?: number
+    maxChartRows?: number
+  }): DashboardTileCapture[]
+}
+
+// One tile's capture from Dashboard.captureTilesForReport. `result` is { ok: false, reason: 'loading' }
+// while the tile has no finished answer on screen, and 'not-found' for a key the dashboard has no tile for.
+export interface DashboardTileCapture {
+  tileKey: string | number
+  dashboardId?: string
+  title: string
+  query: string
+  displayType?: string
+  result: ReportCaptureResult | { ok: false; reason: 'loading' | 'not-found' }
+}
 
 // ─── DataMessenger ───────────────────────────────────────────────────────────
 
@@ -366,6 +385,8 @@ export interface QueryOutputProps {
 }
 
 export declare class QueryOutput extends React.Component<QueryOutputProps> {
+  // What the answer shows now, as plain JSON, for a report to keep (a report's Data block `capture`).
+  captureForReport(options?: { maxTableRows?: number; maxChartRows?: number }): ReportCaptureResult
   changeDisplayType(displayType: string): void
   getCurrentSupportedDisplayTypes(): string[]
   readonly state: { displayType: string; [key: string]: any }
@@ -411,6 +432,601 @@ export interface DataExplorerProps {
 
 export declare class DataExplorer extends React.Component<DataExplorerProps> {}
 
+// ─── ReportBuilder ───────────────────────────────────────────────────────────
+
+// A report is a template: plain, versioned JSON that says what to show, never the data itself. The
+// builder keeps blocks and fields it doesn't know (from a newer version) through a save.
+//
+// ReportBuilder and Reports fetch their code (a file of its own beside the package's main one) the first time one
+// is shown, saying they're loading meanwhile; a ref to either is null until then.
+
+export type ReportBlockWidth = 'full' | 'half'
+export type ReportHeadingLevel = 1 | 2 | 3
+export type ReportTableRows = 10 | 25 | 50 | 100
+export type ReportTypeface = 'theme' | 'archivo' | 'newsreader' | 'plex-mono'
+
+export interface ReportTextStyle {
+  font?: Exclude<ReportTypeface, 'theme'>
+  size?: 'small' | 'normal' | 'large' | 'xlarge' | 'huge'
+  weight?: 'regular' | 'medium' | 'semibold' | 'bold'
+  color?: string
+  background?: string
+  align?: 'center' | 'right'
+}
+
+export interface ReportHeadingBlock {
+  id: string
+  type: 'heading'
+  text: string
+  level: ReportHeadingLevel
+  width?: ReportBlockWidth
+  style?: ReportTextStyle
+}
+
+export interface ReportTextBlock {
+  id: string
+  type: 'text'
+  // Markdown: **bold**, *italic*, ++underline++, ~~strikethrough~~, [links](https://…), lists and ### headings.
+  // A single line break is a line break, so plain text reads as typed.
+  text: string
+  width?: ReportBlockWidth
+  style?: ReportTextStyle
+}
+
+export interface ReportTileSource {
+  type: 'tile'
+  dashboardId: string
+  tileKey: string
+  // Labels for when the tile can't be found; never executed.
+  snapshot?: { dashboardName?: string; tileTitle?: string; query?: string; displayType?: string }
+}
+
+export interface ReportQuestionSource {
+  type: 'query'
+  query: string
+}
+
+// What an answer showed when it was added to a report ("Add to Report…"): its data and the settings that
+// shaped it, shaped like a dashboard tile's saved view. Made by QueryOutput.captureForReport.
+export interface ReportCapture {
+  version: number
+  capturedAt: string
+  displayType: string
+  data: {
+    columns: Array<Record<string, any>>
+    rows: any[][]
+    count_rows: number
+    text?: string
+    query_id?: string
+    interpretation?: string
+    parsed_interpretation?: any
+  }
+  // Tables only: the columns shown, in display order (indices into `columns`), the sort shown, and the
+  // header filters as typed (optional: older captures have none).
+  table?: {
+    columnIndices?: number[]
+    sort: Array<{ name: string; sort: string }>
+    filters?: Array<{ name: string; value: string }>
+    filtered: boolean
+  }
+  config: Record<string, any>
+}
+
+export type ReportCaptureResult =
+  | { ok: true; capture: ReportCapture }
+  | { ok: false; reason: 'no-data' | 'unsupported' | 'too-large'; rowCount?: number }
+
+export interface ReportDataBlock {
+  id: string
+  type: 'data'
+  source: ReportTileSource | ReportQuestionSource | null
+  // Table rows to print; a chart shows its tile as the dashboard does.
+  rows: ReportTableRows
+  width?: ReportBlockWidth
+  // What the block shows until a run replaces it (always, while enableRunReport is off).
+  capture?: ReportCapture
+  // How it's shown, when not as captured: 'table' or a chart type its data supports ('bar', 'line', …).
+  // Chosen in the properties panel; a choice the data can't be drawn as is ignored.
+  displayType?: string
+  // A question asked in the builder (enableDataBlocks), which its Rerun button can ask again.
+  askedHere?: boolean
+  // Its chart's axes and aggregation, when chosen in the builder with the chart's own axis selectors: what
+  // QueryOutput reports (onTableConfigChange, onAggConfigChange). Kept across Rerun; set right when drawn if the
+  // data no longer fits.
+  dataConfig?: {
+    tableConfig?: Record<string, unknown>
+    pivotTableConfig?: Record<string, unknown>
+    columnOverrides?: Record<string, unknown>
+  }
+  aggConfig?: Record<string, string>
+}
+
+export interface ReportPageBreakBlock {
+  id: string
+  type: 'pagebreak'
+}
+
+// Auto Analyze's wording about one Data block (`target`), as written — Markdown — and edited since.
+export interface ReportAnalysisBlock {
+  id: string
+  type: 'analysis'
+  target: string | null
+  // Asked for next time it's written (Analyze again).
+  focus?: string
+  text: string
+  width?: ReportBlockWidth
+  style?: ReportTextStyle
+  // What it was written from: when, the target's capturedAt then, its title, the focus used, the rows read.
+  writtenAt?: string
+  targetAsOf?: string
+  targetTitle?: string
+  focusUsed?: string
+  rowsAnalyzed?: number
+}
+
+export type ReportBlock =
+  | ReportHeadingBlock
+  | ReportTextBlock
+  | ReportDataBlock
+  | ReportAnalysisBlock
+  | ReportPageBreakBlock
+
+// Paper is always US Letter.
+export interface ReportPageSetup {
+  orientation: 'portrait' | 'landscape'
+  margins: 'narrow' | 'normal' | 'wide'
+  typeface: ReportTypeface
+  header: boolean
+  footer: boolean
+  pageNumbers: boolean
+  repeatTableHeaders: boolean
+  showInterpretation: boolean
+  coverPage: boolean
+  tableOfContents: boolean
+}
+
+export interface Report {
+  schemaVersion: number
+  title: string
+  page: ReportPageSetup
+  blocks: ReportBlock[]
+}
+
+export interface ReportDashboard {
+  id: string | number
+  name?: string
+  // 'PROJECT' for a dashboard the whole project shares, as AutoQL lists it.
+  type?: string
+  tiles?: DashboardTile[]
+  slicers?: Array<{ type?: string; data: any }>
+}
+
+// A font the organisation uploaded: its name as shown, and the file as a data: URL.
+export interface ReportBrandFont {
+  name?: string
+  url: string
+}
+
+export interface ReportBranding {
+  name?: string
+  // The organisation's mark (shown before the name, which stands alone without one) and its name set as an image
+  // (it takes the place of the name); URLs, or data: URLs as uploaded.
+  logoUrl?: string
+  wordmarkUrl?: string
+  // Where the logo and wordmark sit, in each page's header and on the cover. Left by default.
+  position?: 'left' | 'center' | 'right'
+  // Brand colours, '#rrggbb', up to 6: offered in the colour pickers.
+  colors?: string[]
+  // Set in by reports on the theme's typeface, on screen and in print.
+  headingFont?: ReportBrandFont
+  bodyFont?: ReportBrandFont
+}
+
+export interface ReportRunSummary {
+  status: 'success' | 'partial' | 'error' | 'cancelled'
+  // One timestamp for the whole run (ISO 8601).
+  runAt: string
+  blocks: Array<{
+    blockId: string
+    status: 'success' | 'error' | 'cancelled' | 'skipped'
+    rowCount?: number
+    countRows?: number | null
+    error?: { message: string; referenceId?: string }
+  }>
+}
+
+export interface ReportBuilderProps {
+  authentication?: Authentication
+  autoQLConfig?: AutoQLConfig
+  dataFormatting?: DataFormatting
+  // Fetched by the host; data blocks read their tiles from these.
+  dashboards?: ReportDashboard[]
+  // Controlled: the builder stores nothing itself.
+  report?: Report
+  onChange?: (report: Report) => void
+  // The branding the pages are drawn with. With enableBranding, what the organisation set in AutoQL wins and this
+  // fills in the rest (the organisation's name, say).
+  branding?: ReportBranding
+  // The organisation's branding is kept by AutoQL (/autoql/api/v1/reports/branding): the builder loads it and
+  // draws it over `branding`. Off by default.
+  enableBranding?: boolean
+  // With enableBranding: adds "Branding…" to the report options menu (⋮) once AutoQL has answered, to change the
+  // organisation's branding. Saving takes AutoQL's organisation-admin grant, so say who may.
+  canEditBranding?: boolean
+  onRunComplete?: (summary: ReportRunSummary) => void
+  onErrorCallback?: (error: any) => void
+  getAuthenticationForProject?: (projectId: string | number) => Authentication | undefined
+  // A stylesheet that loads the typefaces the report can use. None is loaded by default.
+  fontStylesheetUrl?: string | null
+  // Run report: the builder fetches every data block itself. Off by default: blocks show what was
+  // captured when they were added, and runReport() resolves null.
+  enableRunReport?: boolean
+  // Data blocks can be made in the builder, not only arrive with "Add to Report…". Off by default.
+  enableDataBlocks?: boolean
+  // With enableDataBlocks: an empty Data block offers "Pick dashboard tiles…", which calls this. Show your own
+  // picker and resolve with the blocks to put in the empty block's place, in order, or null to leave it.
+  pickDashboardTiles?: () => Promise<ReportBlock[] | null | undefined> | ReportBlock[] | null | undefined
+  // Analysis blocks can be made and written: Auto Analyze's wording about one result, one Auto Analyze credit
+  // per run. Off by default; analyses already in a report always show and print.
+  enableAnalysis?: boolean
+  // Adds "New report · Get started…" to the palette, which calls this. The host starts the report.
+  onGetStarted?: () => void
+  // Your own element for the toolbar, shown just before Preview (and in the preview): whether the report is
+  // saved, say. None by default.
+  toolbarStatus?: React.ReactNode
+  className?: string
+}
+
+export declare class ReportBuilder extends React.Component<ReportBuilderProps> {
+  // Runs every data block as one run with one timestamp; null if superseded, or if enableRunReport is off.
+  runReport(): Promise<ReportRunSummary | null>
+  openPrintPreview(): Promise<void>
+  closePrintPreview(): Promise<void>
+  // Waits for the preview's pages and charts, then opens the browser's print dialog; true once it has.
+  print(): Promise<boolean>
+}
+
+export declare const REPORT_SCHEMA_VERSION: number
+export declare function createEmptyReport(
+  overrides?: Partial<Omit<Report, 'page'>> & { page?: Partial<ReportPageSetup> },
+): Report
+
+// A question asked once, its answer kept as a Data block's capture (shown the way AutoQL shows it by default),
+// with the table rows the block should print. Never rejects.
+export type CaptureQuestionResult =
+  | { ok: true; capture: ReportCapture; rows: ReportTableRows }
+  | {
+      ok: false
+      reason: 'cancelled' | 'error' | 'no-data' | 'unsupported'
+      // For 'error': why the question didn't run or didn't answer with data.
+      error?: { message: string; referenceId?: string }
+    }
+
+export declare function captureQuestion(options: {
+  query: string
+  authentication?: Authentication
+  autoQLConfig?: AutoQLConfig
+  // Stops the request; the result is then { ok: false, reason: 'cancelled' }.
+  signal?: AbortSignal
+  cancelToken?: any
+}): Promise<CaptureQuestionResult>
+
+// How many table rows a new block for this capture prints: all of a table that 10, 25, 50 or 100 holds,
+// else 25.
+export declare function rowsForCapture(capture: ReportCapture | null | undefined): ReportTableRows
+
+// ─── Reports, kept by AutoQL ─────────────────────────────────────────────────
+// A user's own reports on the token's data source, through AutoQL's report service
+// (/autoql/api/v1/reports), with their folders and tags.
+
+// The service's message ids (the number its reference_id ends with) by name.
+export declare const REPORT_ERROR_CODES: Record<number, string>
+
+export declare class ReportsApiError extends Error {
+  // 0 when the service couldn't be reached.
+  status: number
+  // The message id's name, e.g. 'REPORT_VERSION_CONFLICT', when the service sent one.
+  code?: string
+  messageId?: number
+  referenceId?: string
+  // The answer's data in camelCase: { version, updatedAt } on a version conflict, { reason } on an invalid
+  // report or block, { id } of the folder or tag that holds a name.
+  details?: Record<string, any>
+}
+
+export interface StoredReportSummary {
+  id: string
+  title: string
+  sizeBytes: number
+  version: number
+  folderId: string | null
+  tagIds: string[]
+  createdAt: string
+  updatedAt: string
+}
+
+export interface StoredReport extends StoredReportSummary {
+  projectId: string
+  report: Report
+}
+
+export interface StoredReportStamp {
+  id: string
+  version: number
+  updatedAt: string
+}
+
+export interface ReportFolder {
+  id: string
+  name: string
+  reportCount: number
+  createdAt: string
+  updatedAt: string
+}
+
+export interface ReportTag extends ReportFolder {
+  color: string
+}
+
+export interface ReportPlacement {
+  id: string
+  folderId: string | null
+  tagIds: string[]
+}
+
+interface ReportsCall {
+  authentication: Authentication
+}
+
+export declare function fetchReports(
+  options: ReportsCall & {
+    page?: number
+    pageSize?: number
+    q?: string
+    folderId?: string
+    tagIds?: string[]
+    orderBy?: 'updated_at' | 'created_at' | 'title'
+    order?: 'asc' | 'desc'
+    signal?: AbortSignal
+  },
+): Promise<{ reports: StoredReportSummary[]; page: number; pageSize: number; totalPages: number; totalItems: number }>
+export declare function fetchReport(options: ReportsCall & { id: string; signal?: AbortSignal }): Promise<StoredReport>
+export declare function createReport(
+  options: ReportsCall & { id: string; report: Report; folderId?: string; tagIds?: string[]; keepalive?: boolean },
+): Promise<StoredReport & { created: boolean }>
+export declare function saveReport(
+  options: ReportsCall & { id: string; report: Report; version: number; keepalive?: boolean },
+): Promise<StoredReportStamp>
+export declare function deleteReport(options: ReportsCall & { id: string }): Promise<void>
+export declare function deleteReports(
+  options: ReportsCall & { ids: string[] },
+): Promise<{ deleted: string[]; notFound: string[] }>
+export declare function appendReportBlock(
+  options: ReportsCall & { id: string; block: ReportBlock },
+): Promise<StoredReportStamp & { appended: boolean }>
+export declare function organizeReports(
+  options: ReportsCall & {
+    reportIds: string[]
+    // null unfiles; leaving it out leaves the reports' folders as they are.
+    folderId?: string | null
+    addTagIds?: string[]
+    removeTagIds?: string[]
+  },
+): Promise<ReportPlacement[]>
+
+export declare function fetchReportFolders(options: ReportsCall & { signal?: AbortSignal }): Promise<ReportFolder[]>
+export declare function createReportFolder(
+  options: ReportsCall & { id: string; name: string },
+): Promise<ReportFolder & { created: boolean }>
+export declare function renameReportFolder(options: ReportsCall & { id: string; name: string }): Promise<ReportFolder>
+export declare function deleteReportFolder(options: ReportsCall & { id: string }): Promise<void>
+
+export declare function fetchReportTags(options: ReportsCall & { signal?: AbortSignal }): Promise<ReportTag[]>
+export declare function createReportTag(
+  options: ReportsCall & { id: string; name: string; color: string },
+): Promise<ReportTag & { created: boolean }>
+export declare function updateReportTag(
+  options: ReportsCall & { id: string; name?: string; color?: string },
+): Promise<ReportTag>
+export declare function deleteReportTag(options: ReportsCall & { id: string }): Promise<void>
+
+// ─── Reports workspace ───────────────────────────────────────────────────────
+// A user's reports on the token's data source, each open in a tab with its own ReportBuilder and saved to AutoQL
+// as it's edited: the tab strip, New report (from a question, a dashboard or a blank page), autosave with its
+// save control, and the dashboard-tiles picker. The host draws the home page.
+
+export interface ReportsNotice {
+  tone: 'error' | 'info'
+  text: string
+}
+
+// What renderHome draws the home page from.
+export interface ReportsHomeProps {
+  // The user's reports on the data source, most recently saved first; null while they load.
+  reports: StoredReportSummary[] | null
+  // Why they couldn't be listed.
+  listError: string | null
+  retryList: () => void
+  // Shows the report in its tab (opening one if it isn't open).
+  openReport: (id: string) => void
+  // Deletes the report for good (ask first); its tab closes. Resolves with whether it was deleted — why not is in
+  // notices.
+  deleteReport: (id: string) => Promise<boolean>
+  // Deletes several, one after another as deleteReport does each. Resolves with whether every one was deleted.
+  deleteReports: (ids: string[]) => Promise<boolean>
+  deletingId: string | null
+  // What happened meanwhile: a report deleted in another tab, a delete that failed.
+  notices: ReportsNotice[]
+  // Opens New report.
+  newReport: () => void
+
+  // The user's folders and tags on the data source, A to Z; null while they load. Each report in `reports` says its
+  // folder (folderId, null for none) and its tags (tagIds).
+  folders: ReportFolder[] | null
+  tags: ReportTag[] | null
+  // Why they couldn't be loaded.
+  organizersError: string | null
+  retryOrganizers: () => void
+  // The changes below resolve once AutoQL has them, the lists following, and reject with an Error whose message is
+  // the line to show (`code` and `status` are the service's).
+  // A new folder or tag, or the one with that name already, whatever its case. Names are 1 to 80 characters.
+  createFolder: (name: string) => Promise<ReportFolder>
+  renameFolder: (id: string, name: string) => Promise<ReportFolder>
+  // Its reports become unfiled; none is deleted.
+  deleteFolder: (id: string) => Promise<void>
+  // `color` is a short key the host picks (`blue`, `amber`…), kept as it's sent.
+  createTag: (name: string, color: string) => Promise<ReportTag>
+  updateTag: (id: string, change: { name?: string; color?: string }) => Promise<ReportTag>
+  // Taken off every report that had it; none is deleted.
+  deleteTag: (id: string) => Promise<void>
+  // Files reports in a folder (null: none; left out: as they are) and adds or takes off tags, all at once or not at
+  // all. Resolves with where each report now is.
+  organizeReports: (change: {
+    reportIds: string[]
+    folderId?: string | null
+    addTagIds?: string[]
+    removeTagIds?: string[]
+  }) => Promise<ReportPlacement[]>
+}
+
+export interface ReportsProps {
+  authentication?: Authentication
+  autoQLConfig?: AutoQLConfig
+  dataFormatting?: DataFormatting
+  // Which data source the reports are on. The token's project by default.
+  dataSourceId?: string | number
+  // The dashboards a report can take tiles from (New report from a dashboard, an empty Data block's "Pick
+  // dashboard tiles…"). Null while they load; leave it out where there are none. Tiles may carry their answers.
+  dashboards?: ReportDashboard[] | null
+  // Why the dashboards couldn't be loaded, said over the open report.
+  dashboardsError?: string | null
+  // A dashboard's tiles as the tiles picker answered them, for a host that keeps answers between views.
+  onDashboardTilesChange?: (dashboardId: string, tiles: DashboardTile[]) => void
+  // The report shown (null: the home page), for a host that keeps it in its address: when it changes, that report
+  // shows (once the list is in, and if it's there). onShowReport hears every change made in the workspace.
+  shownReportId?: string | null
+  onShowReport?: (id: string | null) => void
+  // Draws the home page. A plain list of the reports by default.
+  renderHome?: (home: ReportsHomeProps) => React.ReactNode
+  // Where the open tabs are remembered in this browser (localStorage keys start with it); null remembers nothing.
+  // 'react-autoql.' by default.
+  storageKeyPrefix?: string | null
+  // AutoQL turned the token away (401): pass in a new authentication, and what failed is tried again with it.
+  onUnauthorized?: () => void
+  // How long a pause in editing is before a report saves (ms). 2000 by default.
+  saveDelay?: number
+  // The folder New report makes reports in, while it's one of the user's: the one the host's home page shows, say.
+  newReportFolderId?: string | null
+  // Passed on to each report's ReportBuilder.
+  branding?: ReportBranding
+  enableBranding?: boolean
+  canEditBranding?: boolean
+  enableDataBlocks?: boolean
+  enableAnalysis?: boolean
+  enableRunReport?: boolean
+  fontStylesheetUrl?: string | null
+  getAuthenticationForProject?: (projectId: string | number) => Authentication | undefined
+  onRunComplete?: (summary: ReportRunSummary) => void
+  onErrorCallback?: (error: any) => void
+  className?: string
+}
+
+export declare class Reports extends React.Component<ReportsProps> {
+  // Saves everything waiting, now (before signing out, say); keepalive when the page is going away. Resolves with
+  // whether each report reached the server.
+  flushAll(options?: { keepalive?: boolean }): Promise<boolean[]>
+  // Whether any report has edits AutoQL doesn't have yet.
+  hasUnsavedChanges(): boolean
+  // Saves the report shown, now.
+  saveNow(): void
+  // Lists the reports again.
+  reload(): void
+}
+
+// What a toolbar's custom option hands its callback: the answer's payload, and from react-autoql's toolbars a
+// capture of what it shows now.
+export interface ReportToolbarOptionData {
+  query?: string
+  tileKey?: string | number
+  dashboardId?: string | number
+  [key: string]: unknown
+}
+
+export interface ReportToolbarOptionExtra {
+  captureForReport?: (options?: { maxTableRows?: number; maxChartRows?: number }) => ReportCaptureResult
+}
+
+// The Data block "Add to Report…" adds: the answer or tile as it's shown now, and where it came from (the tile,
+// when there is one, else the question). A message to show when it can't be kept.
+export declare function captureReportBlock(options: {
+  data: ReportToolbarOptionData | null | undefined
+  extra: ReportToolbarOptionExtra | null | undefined
+  dashboard?: { id: string; name?: string; tiles?: DashboardTile[] } | null
+}): { ok: true; block: ReportDataBlock } | { ok: false; message: string }
+
+export interface AddToReportDialogProps {
+  authentication?: Authentication
+  // The block to add at the end of the chosen report (captureReportBlock).
+  block: ReportBlock
+  onClose: () => void
+  // After it's added (before onClose): which report, and whether it was made for this.
+  onAdded?: (added: { id: string; title: string; created: boolean }) => void
+}
+
+// "Add to Report…": adds a block to the end of one of the user's reports, or to a new one.
+export declare class AddToReportDialog extends React.Component<AddToReportDialogProps> {}
+
+// ─── Push notifications ───────────────────────────────────────────────────────
+
+export type PushNotificationStatus = 'unsupported' | 'checking' | 'on' | 'off' | 'blocked'
+
+export declare const PUSH_NOTIFICATION_STATUS: {
+  UNSUPPORTED: 'unsupported'
+  CHECKING: 'checking'
+  ON: 'on'
+  OFF: 'off'
+  BLOCKED: 'blocked'
+}
+
+export interface PushNotificationsProviderProps {
+  authentication?: Authentication
+  /** Where the app serves push-sw.js. Defaults to '/push-sw.js'. Pass null when the app's own service worker imports it. */
+  serviceWorkerUrl?: string | null
+  /** Service worker scope. Defaults to the scope of the current page. */
+  scope?: string
+  /** Called with the notification's URL when the user clicks a notification. Defaults to a full page load. */
+  onNotificationClick?: (url: string, data: PushMessageData) => void
+  /** Called when an alert arrives while the app is open. */
+  onPushReceived?: (data: PushMessageData) => void
+  children?: React.ReactNode
+}
+
+export interface UsePushNotificationsResult {
+  isSupported: boolean
+  status: PushNotificationStatus
+  isEnabled: boolean
+  isBusy: boolean
+  error: unknown
+  /** Asks for permission if needed and subscribes. Call it from a click. Resolves true when push is on. */
+  enable: () => Promise<boolean>
+  /** Unsubscribes this browser. Call it on logout too. */
+  disable: () => Promise<void>
+  /** Saves this browser's subscription to the server again. */
+  sync: () => Promise<void>
+}
+
+export interface PushNotificationsToggleProps {
+  label?: string
+  description?: string
+  blockedMessage?: string
+  errorMessage?: string
+  className?: string
+}
+
+export declare const PushNotificationsProvider: React.FC<PushNotificationsProviderProps>
+export declare function usePushNotifications(): UsePushNotificationsResult
+export declare const PushNotificationsToggle: React.FC<PushNotificationsToggleProps>
+
 // ─── Miscellaneous components ─────────────────────────────────────────────────
 
 export declare const Icon: React.FC<{ type: string; className?: string; [key: string]: any }>