@altertable/data-app 0.65.0 → 0.66.0

package/dist/types/react/annotations/annotation-editor-state.d.ts

@@ -0,0 +1,56 @@
+import type { DataAppAnnotationDraft } from '../../core/annotations.js';
+import type { AnnotationTargetElement } from './annotation-targets.js';
+export type AnnotationEditorState = {
+    target: AnnotationTargetElement;
+    draft: DataAppAnnotationDraft;
+    annotationId?: string;
+    comment: string;
+    captureStatus: 'capturing' | 'ready' | 'failed';
+    error: string;
+    discardArmed: boolean;
+    shaking: boolean;
+};
+type AnnotationControlsState = {
+    annotationModeActive: boolean;
+    observedActive: boolean;
+    hoveredTarget?: AnnotationTargetElement;
+    editor?: AnnotationEditorState;
+    saving: boolean;
+};
+type AnnotationControlsAction = {
+    type: 'annotationModeChanged';
+    active: boolean;
+} | {
+    type: 'externalModeObserved';
+    active: boolean;
+} | {
+    type: 'targetHovered';
+    target?: AnnotationTargetElement;
+} | {
+    type: 'editorOpened';
+    editor: AnnotationEditorState;
+} | {
+    type: 'editorClosed';
+} | {
+    type: 'commentChanged';
+    comment: string;
+} | {
+    type: 'captureCompleted';
+    draftId: string;
+    succeeded: boolean;
+} | {
+    type: 'editorEscaped';
+    hasUnsavedChanges: boolean;
+} | {
+    type: 'shakeFinished';
+} | {
+    type: 'saveStarted';
+} | {
+    type: 'saveFailed';
+    error: string;
+} | {
+    type: 'saveFinished';
+};
+export declare function createAnnotationControlsState(active: boolean): AnnotationControlsState;
+export declare function annotationControlsReducer(state: AnnotationControlsState, action: AnnotationControlsAction): AnnotationControlsState;
+export {};

package/dist/types/react/annotations/annotation-screenshot.d.ts

@@ -0,0 +1,4 @@
+import type { AnnotationRect } from './annotation-targets.js';
+import type { DataAppAnnotationDraft } from '../../core/annotations.js';
+/** Capture the visible target at selection time; never include annotation controls. */
+export declare function captureAnnotationScreenshot(element: HTMLElement, region?: AnnotationRect): Promise<NonNullable<DataAppAnnotationDraft['context']['screenshot']>>;

package/dist/types/react/annotations/annotation-targets.d.ts

@@ -0,0 +1,33 @@
+export type AnnotationPoint = {
+    x: number;
+    y: number;
+};
+export type AnnotationRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type AnnotationTargetElement = {
+    element: HTMLElement;
+    id: string;
+    label: string;
+    kind: 'widget' | 'element' | 'app';
+};
+export declare function discoverAnnotationTargets(root: HTMLElement | null): {
+    targets: AnnotationTargetElement[];
+    hasDuplicateIds: boolean;
+};
+export declare function annotationGeometry(element: HTMLElement): AnnotationRect;
+export declare function annotationPoint(rect: AnnotationRect, point?: AnnotationPoint): {
+    cursor: AnnotationPoint;
+    anchor: {
+        x: number;
+        y: number;
+    };
+};
+/** The iframe document is a crop surface, never a selectable global-layout target. */
+export declare function annotationRoot(root: HTMLElement | null): AnnotationTargetElement | undefined;
+export declare function findAnnotationTarget(root: HTMLElement | null, id: string | undefined): AnnotationTargetElement | undefined;
+export declare function normalizeAnnotationRect(area: AnnotationRect, target: AnnotationRect): AnnotationRect;
+export declare function projectAnnotationRect(area: AnnotationRect, target: AnnotationRect): AnnotationRect;

package/dist/types/react/annotations/getAnnotationProps.d.ts

@@ -0,0 +1,15 @@
+import type { WidgetEvidence } from '../ui/WidgetEvidence.js';
+type AnnotationPropsOptions = {
+    id?: string;
+    label?: string;
+    evidence?: WidgetEvidence;
+    kind?: 'widget' | 'element';
+};
+export declare function getAnnotationProps({ id, label, evidence, kind, }: AnnotationPropsOptions): {
+    'data-annotation-id': string | undefined;
+    'data-annotation-label': string | undefined;
+    'data-annotation-kind': "element" | "widget";
+    'data-annotation-queries': string;
+    'data-annotation-glossary': string;
+};
+export {};

package/dist/types/react/annotations/styles.d.ts

@@ -0,0 +1,3 @@
+import type { DataAppStylesOptions } from '../styles.js';
+/** Install only the outer-frame annotation controls; leave host page typography and layout intact. */
+export declare function injectDataAppAnnotationStyles(options?: DataAppStylesOptions): HTMLStyleElement;

package/dist/types/react/annotations/useAnnotationGeometry.d.ts

@@ -0,0 +1,22 @@
+import { type ComponentRef, type RefObject } from 'react';
+import type { DataAppAnnotationPresentation } from '../../core/annotations.js';
+import { type AnnotationRect, type AnnotationTargetElement } from './annotation-targets.js';
+import type { AnnotationPin } from './AnnotationMarkers.js';
+type AnnotationRootRef = RefObject<ComponentRef<'div'> | null>;
+export declare function useAnnotationTargets(rootRef: AnnotationRootRef, active: boolean): {
+    targets: AnnotationTargetElement[];
+    hasDuplicateIds: boolean;
+} & {
+    scope?: HTMLElement;
+};
+type AnnotationGeometryOptions = {
+    rootRef: AnnotationRootRef;
+    target?: AnnotationTargetElement;
+    region?: AnnotationRect;
+    targets: DataAppAnnotationPresentation['targets'];
+};
+export declare function useAnnotationGeometry({ rootRef, target, region, targets, }: AnnotationGeometryOptions): {
+    pins: AnnotationPin[];
+    outline?: AnnotationRect;
+};
+export {};

package/dist/types/react/annotations/useDataAppAnnotations.d.ts

@@ -0,0 +1,19 @@
+/** Bind annotation delivery to this app's current iframe bridge. The host owns storage and submission. */
+export declare function useDataAppAnnotations(): {
+    reportAnnotationEditorState(state: {
+        hasUnsavedChanges: boolean;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<null>;
+    addAnnotation(draft: import("../../core/annotations.js").DataAppAnnotationDraft, options?: {
+        signal?: AbortSignal;
+    }): Promise<null>;
+    updateAnnotation(id: string, comment: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<null>;
+    requestAnnotationModeChange(request: {
+        active: boolean;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<null>;
+};

package/dist/types/react/bindings.d.ts

@@ -0,0 +1,110 @@
+import type { EvidenceDeclaration } from './ui/data-context.js';
+import type { ReactNode } from 'react';
+import type { DateRangeRequest } from '../core/contract.js';
+import type { DataView, DisplayedSnapshot } from '../core/data-view.js';
+import type { MetricFormat } from '../core/format.js';
+import type { DataReading, MetricValues } from '../core/reading.js';
+import type { CsvCell, CsvTable, CsvExport } from './ui/csv-export.js';
+import type { MetricDefinition } from './ui/metric.js';
+import type { EmptyContent } from './ui/presentation.js';
+import type { TableWidgetColumn } from './ui/TableWidget.js';
+import type { WidgetEvidence } from './ui/WidgetEvidence.js';
+/** Displayed data, or an initial loading reading. Pending filter values are never a source. */
+export type ViewSource<Data, Input> = {
+    loading: true;
+} | {
+    loading?: false;
+    data: Data;
+    input: Input;
+};
+type SourceReading<Source, Value> = Source extends {
+    loading: true;
+} ? {
+    loading: true;
+} : {
+    loading: false;
+    value: Value;
+};
+/** Keys supply IDs; accessors supply raw CSV values. Formats affect display only. */
+export type DatasetColumn<Row> = {
+    label?: string;
+} & ({
+    value: (row: Row) => CsvCell;
+    format?: (row: Row) => ReactNode;
+} | {
+    value: (row: Row) => number | null | undefined;
+    format: MetricFormat;
+});
+export type DatasetDefinition<Data, Input, Row, Evidence = WidgetEvidence> = {
+    name: string;
+    select: (data: Data, input: Input) => readonly Row[];
+    columns: Record<string, DatasetColumn<NoInfer<Row>>>;
+    rowKey: (row: NoInfer<Row>) => string | number;
+    evidence: Evidence;
+    emptyFallback?: EmptyContent;
+};
+/** Authoring references are registered by the owning view. */
+export type DatasetDeclaration<Data, Input, Row> = DatasetDefinition<Data, Input, Row, EvidenceDeclaration>;
+/** Real view ownership and registered references, shared by metrics and datasets. */
+export declare class RegisteredBinding {
+    #private;
+    constructor(owner?: object, evidence?: WidgetEvidence);
+    protected assertSource(source: object): void;
+    static evidence(binding: RegisteredBinding, owner: object): WidgetEvidence;
+}
+export declare function registeredEvidence(binding: RegisteredBinding, owner: object): WidgetEvidence;
+export declare class ExportDataset<Data, Input> extends RegisteredBinding {
+    #private;
+    readonly name: string;
+    constructor(name: string, csv: (snapshot: DisplayedSnapshot<Data, Input>) => CsvTable, owner?: object, evidence?: WidgetEvidence);
+    static csv<Data, Input>(dataset: ExportDataset<Data, Input>, snapshot: DisplayedSnapshot<Data, Input>): CsvTable;
+}
+export declare class Dataset<Data, Input, Row> extends ExportDataset<Data, Input> {
+    #private;
+    readonly evidence: WidgetEvidence;
+    constructor(definition: DatasetDefinition<Data, Input, Row>, owner?: object);
+    read: <Source extends ViewSource<Data, Input>>(source: Source) => SourceReading<Source, readonly Row[]>;
+    static table<Data, Input, Row>(dataset: Dataset<Data, Input, Row>, source: ViewSource<Data, Input>): {
+        title: string;
+        columns: [TableWidgetColumn<Row>, ...TableWidgetColumn<Row>[]];
+        rowKey: (row: Row) => string | number;
+        evidence: WidgetEvidence;
+        emptyFallback: EmptyContent;
+        reading: {
+            loading: true;
+        } | {
+            loading: false;
+            value: readonly Row[];
+        };
+    };
+}
+export declare function bindDataset<Data, Input, Row>(definition: DatasetDefinition<Data, Input, Row>, owner?: object): Dataset<Data, Input, Row>;
+export declare function datasetTable<Data, Input, Row>(dataset: Dataset<Data, Input, Row>, source: ViewSource<Data, Input>): {
+    title: string;
+    columns: [TableWidgetColumn<Row>, ...TableWidgetColumn<Row>[]];
+    rowKey: (row: Row) => string | number;
+    evidence: WidgetEvidence;
+    emptyFallback: EmptyContent;
+    reading: {
+        loading: true;
+    } | {
+        loading: false;
+        value: readonly Row[];
+    };
+};
+export declare function datasetCsv<Data, Input>(dataset: ExportDataset<Data, Input>, snapshot: DisplayedSnapshot<Data, Input>): CsvTable;
+export declare class Metric<Data, Input> extends RegisteredBinding {
+    #private;
+    readonly definition: MetricDefinition;
+    constructor(definition: MetricDefinition, select: (data: Data, input: Input) => MetricValues, date?: (input: Input) => DateRangeRequest, owner?: object);
+    read: <Source extends ViewSource<Data, Input>>(source: Source) => SourceReading<Source, MetricValues & {
+        period?: DateRangeRequest;
+    }>;
+}
+export declare function bindMetric<Data, Input>(definition: MetricDefinition, select: (data: Data, input: Input) => MetricValues, date?: (input: Input) => DateRangeRequest, owner?: object): Metric<Data, Input>;
+export declare function displayedScope<Data, Input>(view: DataView<Data, Input>, describeInput: (input: Input) => string): DataReading<string>;
+export declare function exportDatasets<Data, Input>(datasets: readonly [
+    ExportDataset<Data, Input>,
+    ...ExportDataset<Data, Input>[]
+], snapshot: DisplayedSnapshot<Data, Input>, scope: string, appTitle: string): CsvExport;
+export {};

package/dist/types/react/content.d.ts

@@ -1,11 +1,9 @@
+import type { DeclaredView } from './view-runtime.js';
 import type { ReactNode } from 'react';
-import type { DataReading, MetricReading, MetricValues } from '../core/reading.js';
-import type { DateRangeRequest } from '../core/contract.js';
-export type DataContentHelpers<Data, Input> = {
-    select: <Value>(select: (data: Data, input: Input) => Value) => DataReading<Value>;
-    metric: (select: (data: Data) => MetricValues) => MetricReading;
-};
-export type DataContentState<Data, Input> = DataContentHelpers<Data, Input> & ({
+import type { DataReading } from '../core/reading.js';
+export type DataContentState<Data, Input> = {
+    scope: DataReading<string>;
+} & ({
     loading: true;
     data?: never;
     input?: never;
@@ -14,10 +12,25 @@ export type DataContentState<Data, Input> = DataContentHelpers<Data, Input> & ({
     data: Data;
     input: Input;
 });
-/** Selectors run only for displayed data. Date comparisons inherit that result's input. */
+/** Content receives only displayed data, its original input, and the derived scope. */
 export declare function defineDataContent<Data, Input>(render: (state: DataContentState<Data, Input>) => ReactNode, options?: {
-    date?: (input: Input) => DateRangeRequest;
+    describeInput?: (input: Input) => string;
 }): {
-    loading: ReactNode;
-    children(data: Data, input: Input): ReactNode;
+    loadingFallback: ReactNode;
+    children(this: void, data: Data, input: Input): ReactNode;
+};
+/** A section's request owner and render layout are declared together. */
+export declare class ViewContent<Data, Input> {
+    #private;
+    constructor(view: DeclaredView<Data, Input>, render: (source: DataContentState<Data, Input>) => ReactNode, describeInput: (input: Input) => string);
+    static section<Data, Input>(content: ViewContent<Data, Input>): {
+        loadingFallback: ReactNode;
+        children(this: void, data: Data, input: Input): ReactNode;
+        view: DeclaredView<Data, Input, unknown>;
+    };
+}
+export declare function sectionContent<Data, Input>(content: ViewContent<Data, Input>): {
+    loadingFallback: ReactNode;
+    children(this: void, data: Data, input: Input): ReactNode;
+    view: DeclaredView<Data, Input, unknown>;
 };