@altertable/data-app 0.65.0 → 0.67.0

package/dist/types/react/ui/TableWidget.d.ts

@@ -14,34 +14,37 @@ export type TableWidgetColumn<Row> = {
     cell: (row: Row, hit?: SearchHit<Row>) => ReactNode;
 };
 export type TableWidgetSearch<Row> = Omit<DataTableSearch, 'itemCount'> & Pick<SearchItemsOptions<Row>, 'attributes' | 'mode' | 'fuzzyThreshold'>;
+export type TableDisplayMode = {
+    /** Positive integer preview cap after search; disables pagination. */
+    limit: number;
+    pagination?: never;
+} | {
+    /** Local pagination after search: 10 rows by default, false shows all supplied rows.
+     * pageSize must be a positive integer. Counts refer only to supplied rows.
+     * The widget owns bottom-footer controls and shares the current page with inspection. */
+    pagination?: {
+        pageSize: number;
+    } | false;
+    limit?: never;
+};
 type TableWidgetBaseProps<Row> = {
     title: ReactNode;
+    annotationId?: string;
     count?: number;
     description?: ReactNode;
     columns: readonly [TableWidgetColumn<Row>, ...TableWidgetColumn<Row>[]];
     /** Unique, nonempty row identity. Numeric keys must be finite; 1 and "1" collide. */
     rowKey: (row: Row) => string | number;
-    insight?: ReactNode;
     status?: WidgetStatus;
     action?: ReactNode;
     evidence?: WidgetEvidence;
     search?: TableWidgetSearch<Row>;
     /** Valid result with no rows; the header remains visible. */
-    empty: EmptyContent;
-} & ({
-    /** Positive integer preview cap after search; disables pagination. */
-    limit: number;
-    pagination?: never;
-} | {
-    /** Local pagination after search: 10 rows by default, false shows all supplied rows.
-     * pageSize must be a positive integer. Counts refer only to supplied rows.
-     * The widget owns bottom-footer controls and shares the current page with inspection. */
-    pagination?: {
-        pageSize: number;
-    } | false;
-    limit?: never;
-}) & Omit<ComponentPropsWithRef<'section'>, 'about' | 'title' | 'children'>;
-/** Column definitions own both header and body semantics; the first column is the row header. */
+    emptyFallback: EmptyContent;
+} & TableDisplayMode & Omit<ComponentPropsWithRef<'section'>, 'about' | 'title' | 'children'>;
+/** Composes VisualizationWidget with DataTable, search, and local pagination.
+ * Columns own header and body semantics; the first column is the row header.
+ * Use DataTable inside VisualizationWidget directly for custom table markup. */
 export type TableWidgetProps<Row> = TableWidgetBaseProps<Row> & ({
     rows: readonly Row[];
     reading?: never;

package/dist/types/react/ui/Tabs.d.ts

@@ -1,5 +1,9 @@
-import { Tabs, TabList, Tab, TabPanels, TabPanel } from 'react-aria-components/Tabs';
+import { type ComponentPropsWithRef } from 'react';
+import { Tabs as AriaTabs, TabList, Tab as AriaTab, TabPanels, TabPanel as AriaTabPanel } from 'react-aria-components/Tabs';
 /** React Aria tabs with keyboard and ARIA behavior; pair each Tab and TabPanel by stable id. */
-export { Tabs, TabList, Tab, TabPanels, TabPanel };
+export { TabList, TabPanels };
+export declare function Tab(props: ComponentPropsWithRef<typeof AriaTab>): import("react").JSX.Element;
+export declare function TabPanel(props: ComponentPropsWithRef<typeof AriaTabPanel>): import("react").JSX.Element;
+export declare function Tabs({ className, ...props }: ComponentPropsWithRef<typeof AriaTabs>): import("react").JSX.Element;
 /** Keep a page-level tab in `?view=`; reserve `?tab=` for the inspect sheet. */
 export declare function useViewTab<View extends string>(views: readonly View[], fallback: View): [View, (key: string | number) => void];

package/dist/types/react/ui/TextWidget.d.ts

@@ -5,7 +5,8 @@ import type { WidgetEvidence } from './WidgetEvidence.js';
 type TextWidgetBaseProps = Omit<Extract<DataWidgetProps, {
     reading?: never;
 }>, 'reading' | 'children' | 'isEmpty' | 'empty' | 'skeleton' | 'bodyPadding'>;
-/** Framed narrative context. Bind claims and scope to the same displayed reading.
+/** Narrative sibling of VisualizationWidget, composing DataWidget with TextContent.
+ * Use TextContent directly for borderless prose. Bind claims and scope to the same displayed reading.
  * The renderer handles every ready value, including zero and empty collections. */
 export type TextWidgetProps<Data = unknown> = TextWidgetBaseProps & ({
     reading: DataReading<Data>;

package/dist/types/react/ui/Tooltip.d.ts

@@ -11,12 +11,13 @@ export type TooltipProps = {
     content: ReactNode;
     children: ReactNode;
     variant?: 'hint' | 'chart';
+    onOpenChange?: (open: boolean) => void;
     align?: 'start' | 'center' | 'end';
     placement?: 'top' | 'bottom';
     portalRoot?: RefObject<HTMLElement | null>;
-    tooltipProps?: Omit<ComponentPropsWithRef<'span'>, 'children' | 'role'>;
 } & Omit<ComponentPropsWithRef<'span'>, 'children' | 'content'>;
 /** Short visual hint for an already labeled control. variant="chart" follows the cursor
- * on hover and toggles on tap so a bar or point can show the period and value. Hint
+ * on hover and toggles on tap so a bar or point can show the period and value. Chart
+ * tooltips dismiss on scroll and do not open on keyboard focus. Hint
  * tooltips hide once the control is pressed. Escape closes either. */
-export declare function Tooltip({ content, children, variant, align, placement, portalRoot, tooltipProps, className, ref, onPointerEnter, onPointerMove, onPointerLeave, onPointerDown, onFocusCapture, onBlurCapture, ...props }: TooltipProps): import("react").JSX.Element;
+export declare function Tooltip({ content, children, onOpenChange, variant, align, placement, portalRoot, className, ref, onPointerEnter, onPointerMove, onPointerLeave, onPointerDown, onFocusCapture, onBlurCapture, ...props }: TooltipProps): import("react").JSX.Element;

package/dist/types/react/ui/TooltipSurface.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentPropsWithRef } from 'react';
+/** Shared surface for floating hints and chart value inspection. */
+export declare function TooltipSurface({ className, ...props }: ComponentPropsWithRef<'span'>): import("react").JSX.Element;

package/dist/types/react/ui/TrendChart.d.ts

@@ -0,0 +1,5 @@
+import type { ValueChartProps } from './chart-data.js';
+/** Ordered, equally spaced samples; negative values share an explicit zero baseline. */
+export declare function TrendChart({ items, unit, ariaLabel, formatValue, area, }: ValueChartProps & {
+    area?: boolean;
+}): import("react").JSX.Element;

package/dist/types/react/ui/UpdatedAt.d.ts

@@ -6,4 +6,4 @@ export type UpdatedAtProps = {
     label?: string;
     children?: ReactNode;
 } & Omit<DateTimeTooltipProps, 'date' | 'children'>;
-export declare function UpdatedAt({ timestamp, locale, label, children, triggerClassName, ...props }: UpdatedAtProps): import("react").JSX.Element;
+export declare function UpdatedAt({ timestamp, locale, label, children, triggerProps, ...props }: UpdatedAtProps): import("react").JSX.Element;

package/dist/types/react/ui/VisualizationWidget.d.ts

@@ -1,22 +1,18 @@
 import { type ComponentPropsWithRef, type ReactNode } from 'react';
-import type { WidgetEvidence } from './WidgetEvidence.js';
-import type { WidgetStatus } from './RequestHint.js';
-import type { EmptyContent, BoundWidgetReading } from './presentation.js';
-type VisualizationWidgetBaseProps = {
-    title: ReactNode;
-    description?: ReactNode;
-    insight?: ReactNode;
-    action?: ReactNode;
-    evidence?: WidgetEvidence;
-    status?: WidgetStatus;
-    empty?: EmptyContent;
+import { type DataWidgetProps } from './DataWidget.js';
+import type { BoundWidgetReading } from './presentation.js';
+type VisualizationWidgetBaseProps = Pick<DataWidgetProps, 'title' | 'annotationId' | 'description' | 'count' | 'action' | 'evidence' | 'status' | 'emptyFallback'> & {
+    /** Footer controls, such as table pagination. */
+    footer?: ReactNode;
 } & Omit<ComponentPropsWithRef<'section'>, 'about' | 'title' | 'children'>;
 type UnboundVisualizationWidgetProps = VisualizationWidgetBaseProps & ({
     loading: true;
+    loadingContent?: ReactNode;
     visual?: never;
 } | {
     loading?: false;
     visual: ReactNode;
+    loadingContent?: never;
 });
 export type VisualizationWidgetView<Data> = {
     /** Stable, nonempty identity; unique within this widget. */
@@ -28,8 +24,10 @@ type BoundVisualizationWidgetBase<Data> = VisualizationWidgetBaseProps & BoundWi
     visual?: never;
     loading?: never;
 };
-/** The widget owns alternate-view selection and shares it with inspection.
- * Custom chart interactions remain controlled by the caller, above both mounts. */
+/** DataWidget frame for charts, DataTable, metrics, or a custom data display.
+ * Owns alternate-view selection and shares it with inspection. Built-in charts own
+ * transient tooltips; lift persistent custom interactions above both mounts.
+ * For narrative prose use the sibling TextWidget, which composes DataWidget directly. */
 export type VisualizationWidgetProps<Data = unknown> = UnboundVisualizationWidgetProps | (BoundVisualizationWidgetBase<Data> & {
     children: (data: Data) => ReactNode;
     views?: never;
@@ -40,5 +38,6 @@ export type VisualizationWidgetProps<Data = unknown> = UnboundVisualizationWidge
     initialView?: string;
     children?: never;
 });
+/** Compose an unframed visual with the shared heading and inspection. */
 export declare function VisualizationWidget<Data>(props: VisualizationWidgetProps<Data>): import("react").JSX.Element;
 export {};

package/dist/types/react/ui/WidgetViewTabs.d.ts

@@ -4,7 +4,7 @@ export type WidgetView = {
     id: string;
     label: ReactNode;
     content: ReactNode;
-    empty: EmptyContent;
+    emptyFallback: EmptyContent;
     isEmpty: boolean;
 };
 export type WidgetViewTabsProps<Views extends readonly WidgetView[] = readonly WidgetView[]> = {

package/dist/types/react/ui/chart-data.d.ts

@@ -0,0 +1,25 @@
+/** Ordered category or time-series sample. IDs are unique and nonblank; values are finite. */
+export type ChartItem = {
+    id: string;
+    label: string;
+    value: number;
+};
+export type ValueChartProps = {
+    /** Ordered samples; the chart validates IDs and values when rendering. */
+    items: readonly ChartItem[];
+    unit: string;
+    ariaLabel: string;
+    formatValue?: (value: number) => string;
+};
+/** Independent observation on two finite numeric axes. */
+export type ScatterChartItem = {
+    id: string;
+    label: string;
+    x: number;
+    y: number;
+};
+type ChartKind = 'bar' | 'line' | 'area' | 'pie' | 'scatter';
+type ItemFor<Kind extends ChartKind> = Kind extends 'scatter' ? ScatterChartItem : ChartItem;
+/** Validate standalone item-based chart inputs. */
+export declare function validateChartItems<Kind extends ChartKind>(kind: Kind, items: readonly ItemFor<Kind>[]): void;
+export {};

package/dist/types/react/ui/chart-primitives.d.ts

@@ -0,0 +1,20 @@
+import type { ComponentProps } from 'react';
+import { type DotProps, Scatter, XAxis, YAxis, CartesianGrid, Tooltip, type BarProps, type LineProps, type AreaProps } from 'recharts';
+export declare const chartBarFill = "var(--atbl-chart-fill, color-mix(in srgb, var(--atbl-accent) 75%, var(--atbl-surface)))";
+/** Hollow sample marker shared by standalone and composed series. */
+export declare function ChartDot({ active, stroke, fill, r, ...props }: DotProps & {
+    active?: boolean;
+}): import("react").JSX.Element;
+/** Shared series defaults; native props override every authored choice. */
+export declare function ChartBar<Row = unknown, Value = number | null>(props: BarProps<Row, Value>): import("react").JSX.Element;
+/** Themed hollow sample dots are enabled by default; dot=false hides them.
+ * activeDot independently controls the hovered point. Native dot props and renderers remain available. */
+export declare function ChartLine<Row = unknown, Value = number | null>({ stroke, dot, activeDot, ...props }: LineProps<Row, Value>): import("react").JSX.Element;
+/** Filled series with the same sample-dot and activeDot options as ChartLine. */
+export declare function ChartArea<Row = unknown, Value = number | null>({ stroke, dot, activeDot, ...props }: AreaProps<Row, Value>): import("react").JSX.Element;
+export declare function ChartScatter<Row = unknown, Value = number>(props: ComponentProps<typeof Scatter<Row, Value>>): import("react").JSX.Element;
+export declare function ChartXAxis<Row = unknown, Value = string | number>(props: ComponentProps<typeof XAxis<Row, Value>>): import("react").JSX.Element;
+export declare function ChartYAxis<Row = unknown, Value = number>(props: ComponentProps<typeof YAxis<Row, Value>>): import("react").JSX.Element;
+export declare function ChartGrid(props: ComponentProps<typeof CartesianGrid>): import("react").JSX.Element;
+/** Uses the same surface as single-series inspection; Recharts owns interaction. */
+export declare function ChartTooltip(props: ComponentProps<typeof Tooltip>): import("react").JSX.Element;

package/dist/types/react/ui/data-context.d.ts

@@ -15,15 +15,26 @@ export type DataContext = {
     identifiers?: Readonly<Record<string, DataIdentifierDefinition>>;
     queryNames?: Readonly<Record<string, string>>;
 };
-export declare function defineDataContext<const Context extends DataContext>(context: Context): Context;
-export declare function evidenceFor<const Context extends DataContext, const Names extends Record<string, string> = Record<string, string>>(context: Context, names?: Names): (evidence: {
+export type MetricDeclaration = {
     id: string;
-    glossaryIds?: readonly (keyof Context['glossary'] & string)[];
-    queryNames?: readonly Names[keyof Names][];
-}) => {
+    glossaryId: string;
+    label?: string;
+    format: MetricFormat;
+    favorableDirection?: 'up' | 'down';
+    queryNames?: readonly string[];
+};
+export type EvidenceDeclaration = {
     id: string;
-    glossaryIds: (keyof Context["glossary"] & string)[] | undefined;
-    queryNames: Names[keyof Names][] | undefined;
+} & ({
+    glossaryIds: readonly [string, ...string[]];
+    queryNames?: readonly string[];
+} | {
+    queryNames: readonly [string, ...string[]];
+    glossaryIds?: readonly string[];
+});
+export type AuthoringDataContext = DataContext & {
+    metric(definition: MetricDeclaration): MetricDefinition;
+    evidence(definition: EvidenceDeclaration): WidgetEvidence;
 };
 /** Bind glossary query references and card evidence to the same registry. */
 export declare function createDataContext<const Names extends Record<string, string>>(queryNames: Names): <const Context extends Omit<DataContext, 'glossary'> & {

package/dist/types/react/ui/icons.d.ts

@@ -1,6 +1,7 @@
 import { type LucideProps } from 'lucide-react';
 /** Use semantic names to keep icon meaning and optical size consistent across controls. */
 declare const brandedIcons: {
+    readonly annotate: import("lucide-react").LucideIcon;
     readonly cancel: import("lucide-react").LucideIcon;
     readonly calendar: import("lucide-react").LucideIcon;
     readonly clock: import("lucide-react").LucideIcon;
@@ -17,6 +18,7 @@ declare const brandedIcons: {
     readonly export: import("lucide-react").LucideIcon;
     readonly error: import("lucide-react").LucideIcon;
     readonly close: import("lucide-react").LucideIcon;
+    readonly clearFilters: import("lucide-react").LucideIcon;
     readonly previous: import("lucide-react").LucideIcon;
     readonly next: import("lucide-react").LucideIcon;
     readonly lightTheme: import("lucide-react").LucideIcon;

package/dist/types/react/ui/index.d.ts

@@ -0,0 +1,98 @@
+/** Direct UI composition and static screens. Requests use declared views from /react. */
+export { injectDataAppShellStyles } from '../shellStyles.js';
+export { DataAppProvider } from '../mount.js';
+export { isPlainKeyEvent } from './keyboard.js';
+export { GettingStarted } from './GettingStarted.js';
+export { DataWidget } from './DataWidget.js';
+export type { WidgetStatus } from './RequestHint.js';
+export type { DataWidgetProps } from './DataWidget.js';
+export { TextWidget } from './TextWidget.js';
+export type { TextWidgetProps } from './TextWidget.js';
+export { VisualizationWidget } from './VisualizationWidget.js';
+export type { VisualizationWidgetProps } from './VisualizationWidget.js';
+export { TableWidget } from './TableWidget.js';
+export type { TableWidgetProps } from './TableWidget.js';
+export { DataTable, DataTableEmptyRow, DataTableTimestamp, DataTableShare, } from './DataTable.js';
+export type { DataTableProps, DataTableSearch, DataTableEmptyRowProps, DataTableTimestampProps, } from './DataTable.js';
+export { MetricWidget } from './MetricWidget.js';
+export type { MetricWidgetProps } from './MetricWidget.js';
+export { DimensionPicker } from './DimensionPicker.js';
+export { DataAppSkeleton } from './DataAppSkeleton.js';
+export type { DataAppSkeletonProps } from './DataAppSkeleton.js';
+export { LiveControl } from './LiveControl.js';
+export type { LiveControlProps, LiveIntervalSeconds, } from './LiveControl.js';
+export { DateRangePicker } from './DateRangePicker.js';
+export type { DatePresetId, DateRange, DateRangePickerProps, } from './DateRangePicker.js';
+export { useAppVariables } from './variables.js';
+export { SearchField } from './SearchField.js';
+export type { SearchFieldProps } from './SearchField.js';
+export { searchItems } from './searchItems.js';
+export type { SearchAttribute, SearchHit, SearchItemsOptions, SearchMatchValue, SearchRange, } from './searchItems.js';
+export { SearchMatch } from './SearchMatch.js';
+export type { SearchMatchProps } from './SearchMatch.js';
+export { ChoicePicker } from './ChoicePicker.js';
+export type { ChoiceOption, ChoicePickerProps, } from './ChoicePicker.js';
+export { MenuTrigger, MenuButton, MenuPopover, Menu, MenuItem, MenuSection, MenuSeparator, } from './Menu.js';
+export type { MenuTriggerProps, MenuPopoverProps, MenuProps, MenuItemProps, } from './Menu.js';
+export { GradientScroll } from './GradientScroll.js';
+export type { GradientScrollProps } from './GradientScroll.js';
+export { Tabs, TabList, Tab, TabPanels, TabPanel, useViewTab, } from './Tabs.js';
+export { GlossaryExplanation } from './GlossaryExplanation.js';
+export type { GlossaryExplanationProps } from './GlossaryExplanation.js';
+export { GlossaryDefinition } from './GlossaryDefinition.js';
+export type { GlossaryDefinitionProps } from './GlossaryDefinition.js';
+export { AboutData } from './AboutData.js';
+export type { AboutDataProps, AboutEmpty, AboutSubject, AboutTab, } from './AboutData.js';
+export { PresentStory } from './PresentStory.js';
+export type { PresentStoryProps } from './PresentStory.js';
+export type { StoryFinding, BoundStory } from './story.js';
+export { Checkbox } from './Checkbox.js';
+export type { CheckboxProps } from './Checkbox.js';
+export { AppIcon } from './icons.js';
+export type { AppIconName, AppIconProps } from './icons.js';
+export { Sheet } from './Sheet.js';
+export type { SheetProps } from './Sheet.js';
+export { HelpPopover } from './HelpPopover.js';
+export type { HelpPopoverProps } from './HelpPopover.js';
+export { DataApp } from './StaticDataApp.js';
+export type { DataAppProps } from './StaticDataApp.js';
+export { injectDataAppStyles } from '../styles.js';
+export { Tooltip, TooltipProvider } from './Tooltip.js';
+export type { TooltipProps, TooltipProviderProps, } from './Tooltip.js';
+export { LineChart } from './LineChart.js';
+export type { LineChartProps, LineChartItem } from './LineChart.js';
+export { AreaChart } from './AreaChart.js';
+export type { AreaChartProps, AreaChartItem } from './AreaChart.js';
+export { PieChart } from './PieChart.js';
+export type { PieChartProps, PieChartItem } from './PieChart.js';
+export { ScatterChart } from './ScatterChart.js';
+export type { ScatterChartProps, ScatterChartItem, } from './ScatterChart.js';
+export { BarChart } from './BarChart.js';
+export type { BarChartProps, BarChartItem } from './BarChart.js';
+export { DataValue } from './DataValue.js';
+export type { DataValueProps } from './DataValue.js';
+export type { CsvExport, CsvTable } from './csv-export.js';
+export type { TableWidgetColumn } from './TableWidget.js';
+export type { DataReading, MetricReading } from '../../core/reading.js';
+export type { DataAppStyle, DataAppStyleToken, DataAppStyleHooks, } from '../style-contract.js';
+export { Select } from './Select.js';
+export type { SelectProps } from './Select.js';
+export { RadioGroup, Radio, SegmentedControl } from './RadioGroup.js';
+export type { RadioGroupProps, RadioProps, SegmentedControlProps, } from './RadioGroup.js';
+export { CheckboxGroup } from './CheckboxGroup.js';
+export type { CheckboxGroupProps } from './CheckboxGroup.js';
+export { NumberField, NumberRangeField } from './NumberField.js';
+export type { NumberFieldProps, NumberRangeFieldProps, NumberRange, } from './NumberField.js';
+export { FilterBar } from './FilterBar.js';
+export type { FilterBarProps } from './FilterBar.js';
+export { VariableBar } from './VariableBar.js';
+export type { VariableBarProps } from './VariableBar.js';
+export { FilterActions } from './FilterActions.js';
+export type { FilterActionsProps } from './FilterActions.js';
+export { NumberFilterPicker } from './NumberFilterPicker.js';
+export type { NumberFilterPickerProps } from './NumberFilterPicker.js';
+export { ComposedChart } from './ComposedChart.js';
+export type { ComposedChartProps } from './ComposedChart.js';
+export { ChartLegend } from './ChartLegend.js';
+export type { ChartLegendProps, ChartLegendItemProps, ChartLegendMarkerProps, ChartLegendLabelProps, ChartLegendMarkerKind, } from './ChartLegend.js';
+export type { ComposedChartLegendProps } from './ComposedChartLegend.js';

package/dist/types/react/ui/keyboard.d.ts

@@ -0,0 +1,6 @@
+type KeyEvent = Pick<KeyboardEvent, 'altKey' | 'ctrlKey' | 'metaKey' | 'shiftKey' | 'isComposing'>;
+/** Keep local key actions separate from shortcuts and IME composition. Pass React's nativeEvent. */
+export declare function isPlainKeyEvent(event: KeyEvent, { allowShift }?: {
+    allowShift?: boolean;
+}): boolean;
+export {};

package/dist/types/react/ui/metric.d.ts

@@ -8,4 +8,4 @@ export type MetricDefinition = {
     favorableDirection?: 'up' | 'down';
     evidence: WidgetEvidence;
 };
-export declare function metricComparison(metric: MetricDefinition, reading: MetricReading): import("./comparison.js").MetricComparison | undefined;
+export declare function metricComparison(metric: MetricDefinition, reading: MetricReading): import("./metric-comparison.js").MetricComparison | undefined;

package/dist/types/react/ui/presentation.d.ts

@@ -7,13 +7,17 @@ export type EmptyContent = {
 };
 export type SkeletonContent = {
     variant: 'metric' | 'panel' | 'ranking';
+    /**
+     * Placeholder rows, clamped to 0–100.
+     * @default 4
+     */
     rows?: number;
 };
 /** A bound widget must explain empty results and link the reading to its evidence. */
 export type BoundWidgetReading<Data> = {
     reading: DataReading<Data>;
     isEmpty: (data: Data) => boolean;
-    empty: EmptyContent;
+    emptyFallback: EmptyContent;
     evidence: WidgetEvidence;
     skeleton?: SkeletonContent;
 };

package/dist/types/react/ui/shortcuts.d.ts

@@ -9,6 +9,17 @@ export type Shortcut = {
     key: string;
 };
 export declare const shortcuts: {
+    readonly annotate: {
+        readonly modifier: 'mod';
+        readonly shift: true;
+        readonly code: 'Period';
+        readonly key: '.';
+    };
+    readonly sendAnnotations: {
+        readonly modifier: 'mod';
+        readonly code: 'Enter';
+        readonly key: 'Enter';
+    };
     readonly refresh: {
         readonly modifier: 'alt';
         readonly code: 'KeyR';
@@ -21,6 +32,7 @@ export declare const shortcuts: {
     };
     readonly playStory: {
         readonly modifier: 'mod';
+        readonly shift: true;
         readonly code: 'Enter';
         readonly key: 'Enter';
     };
@@ -28,5 +40,6 @@ export declare const shortcuts: {
 export declare function shortcutLabel({ modifier, shift, key }: Shortcut): string;
 export declare function ariaKeyShortcuts({ modifier, shift, key }: Shortcut): string;
 export declare function isEditingTarget(target: EventTarget | null): boolean;
+export declare function matchesShortcut(event: KeyboardEvent, shortcut: Shortcut): boolean;
 /** Bind a page-level shortcut. Ignored while typing or while a modal layer is open. */
-export declare function useShortcut(shortcut: Shortcut, action: () => void, enabled?: boolean): void;
+export declare function useShortcut(shortcut: Shortcut, action: () => void, enabled?: boolean, allowWhileEditing?: boolean): void;

package/dist/types/react/ui/useAppAppearance.d.ts

@@ -1,3 +1,3 @@
 import { type Theme, type AppearanceOptions } from '../../core/appearance.js';
 /** The parent theme takes precedence; only standalone viewers receive controls. */
-export declare function useAppAppearance(appearance: AppearanceOptions, hostTheme?: Theme): import("../../core/appearance.js").ThemeController | undefined;
+export declare function useAppAppearance(appearance: AppearanceOptions | undefined, hostTheme?: Theme): import("../../core/appearance.js").ThemeController | undefined;

package/dist/types/react/ui/variables.d.ts

@@ -1,7 +1,7 @@
 import type { DatePresetId, DateRange } from '../../core/date-range.js';
 import { type AppVariableValues, type DateRangeSelection, type DateRangeVariable, type HistoryMode, type VariableCollection } from '../../core/variables.js';
-export { defineAppVariables, textVariable, selectVariable, dateRangeVariable, } from '../../core/variables.js';
-export type { AppVariable, AppVariableValues, DateRangeSelection, DateRangeVariable, DateRangeVariableOptions, VariableCollection, } from '../../core/variables.js';
+export { defineAppVariables, searchVariable, choiceVariable, multiChoiceVariable, dateRangeVariable, } from '../../core/variables.js';
+export type { AppVariable, AppVariableValues, ChoiceOption, ChoiceVariable, MultiChoiceVariable, SearchVariable, DateRangeSelection, DateRangeVariable, DateRangeVariableOptions, VariableCollection, } from '../../core/variables.js';
 /** Adapt one date variable to the controlled picker without giving the picker URL ownership. */
 export declare function dateRangeControl(variable: DateRangeVariable, selection: DateRangeSelection, onChange: (selection: DateRangeSelection) => void): {
     minDate?: string;
@@ -27,6 +27,8 @@ export declare function useAppVariables<const Variables extends VariableCollecti
     values: AppVariableValues<Variables>;
     set: <Key extends keyof Variables & string>(name: Key, value: AppVariableValues<Variables>[Key]) => void;
     reset: <Key extends keyof Variables & string>(name: Key) => void;
+    resetAll: () => void;
+    clearAll: () => void;
     update: (next: Partial<AppVariableValues<Variables>>, history?: HistoryMode) => void;
     bind: <Key extends keyof Variables & string>(name: Key) => {
         value: AppVariableValues<Variables>[Key];

package/dist/types/react/view-controls.d.ts

@@ -6,7 +6,9 @@ export declare function useViewVariables<Variables extends VariableCollection>(d
     values: AppVariableValues<Variables>;
     set: <Key extends keyof Variables & string>(name: Key, value: AppVariableValues<Variables>[Key]) => void;
     reset: <Key extends keyof Variables & string>(name: Key) => void;
-    update: (next: Partial<AppVariableValues<Variables>>, history?: import("../core/navigation.js").HistoryMode) => void;
+    resetAll: () => void;
+    clearAll: () => void;
+    update: (next: Partial<AppVariableValues<Variables>>, history?: import("../core/variables.js").HistoryMode) => void;
     bind: <Key extends keyof Variables & string>(name: Key) => {
         value: AppVariableValues<Variables>[Key];
         onChange(value: AppVariableValues<Variables>[Key]): void;

package/dist/types/react/view-runtime.d.ts

@@ -0,0 +1,29 @@
+import type { DataContext } from './ui/data-context.js';
+import type { ReactNode } from 'react';
+import type { DataView, DisplayedSnapshot } from '../core/data-view.js';
+import type { DisclosedQuery } from '../core/contract.js';
+import type { EmptyContent } from './ui/presentation.js';
+export type ViewResult<Data, Input> = {
+    dataContext: DataContext;
+    view: DataView<Data, Input>;
+    snapshot?: DisplayedSnapshot<Data, Input>;
+    refetch: () => unknown;
+    cancel: () => unknown;
+    refreshing: boolean;
+    queries?: DisclosedQuery[];
+    controls?: ReactNode;
+    emptyFallback: EmptyContent;
+};
+/** The executor is private; declarations expose data composition, not subscription hooks. */
+export declare class DeclaredView<Data, Input, Definition = unknown> {
+    #private;
+    constructor(useResult: () => ViewResult<Data, Input>, definition?: Definition);
+    static definition<Data, Input, Definition>(view: DeclaredView<Data, Input, Definition>): Definition;
+    static useResult<Data, Input>(view: DeclaredView<Data, Input>): ViewResult<Data, Input>;
+}
+export declare function useDeclaredResult<Data, Input>(view: DeclaredView<Data, Input>): ViewResult<Data, Input>;
+export declare const PrimaryViewContext: import("react").Context<{
+    declaration: object;
+    result: ViewResult<unknown, unknown>;
+} | null>;
+export declare function getViewDefinition<Data, Input, Definition>(view: DeclaredView<Data, Input, Definition>): Definition;

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

@@ -1,3 +1,4 @@
+import type { DataContext } from './ui/data-context.js';
 import type { EmptyContent } from './ui/presentation.js';
 import type { AppVariableValues, DateRangeVariable, VariableCollection } from '../core/variables.js';
 import type { DateRangeRequest } from '../core/contract.js';
@@ -16,21 +17,37 @@ export type ViewDate<Variables extends VariableCollection, Input> = {
 export type ViewBindings<Variables extends VariableCollection, Input> = Partial<{
     [Key in keyof Variables]: (input: Input) => ResolvedVariables<Variables>[Key];
 }>;
+type SameViewInput<Variables extends VariableCollection, Input> = [
+    ResolvedVariables<Variables>
+] extends [Input] ? [Input] extends [ResolvedVariables<Variables>] ? [Input] extends [Record<string, never>] ? true : [keyof Input] extends [keyof Variables] ? true : false : false : false;
+type ViewInputMapping<Variables extends VariableCollection, Input> = SameViewInput<Variables, Input> extends true ? {
+    input?: (values: ResolvedVariables<Variables>) => Input;
+} : {
+    input: (values: ResolvedVariables<Variables>) => Input;
+};
 export type DataViewDefinition<Name extends string, Variables extends VariableCollection, Input, Data> = {
     operation: Name;
-    variables: Variables;
-    input: (values: ResolvedVariables<Variables>) => Input;
+    dataContext: DataContext;
     bindings?: ViewBindings<Variables, Input>;
     /** App-owned semantics: measured zero need not mean an empty result. */
     isEmpty: (data: Data) => boolean;
-    empty: EmptyContent;
-} & ({
+    /** Inherited by DataSection unless it supplies its own copy. */
+    emptyFallback: EmptyContent;
+} & (keyof Variables extends never ? {
+    variables?: Variables;
+} : {
+    variables: Variables;
+}) & ViewInputMapping<NoInfer<Variables>, Input> & ({
     date: ViewDate<Variables, Input>;
     describeInput?: (input: Input) => string;
 } | {
     date?: never;
     describeInput: (input: Input) => string;
 });
+export type ResolvedDataViewDefinition<Name extends string, Variables extends VariableCollection, Input, Data> = Omit<DataViewDefinition<Name, Variables, Input, Data>, 'variables' | 'input'> & {
+    variables: Variables;
+    input: (values: ResolvedVariables<Variables>) => Input;
+};
 export declare function describeViewInput<Input>(definition: {
     variables: VariableCollection;
     bindings?: Partial<Record<string, (input: Input) => unknown>>;