@conterra/ct-mapapps-typings 4.13.0 → 4.13.2-PRE-1

package/result-api/api/actions.d.ts

@@ -0,0 +1,209 @@
+import type { TableItem, ItemGeometry, TableModel, ResultModel } from "./model";
+import type { EventSource } from "apprt-core/Events";
+/**
+ * All BulkTableAction types.
+ */
+export declare type BulkTableAction = BulkButtonTableAction;
+/**
+ * All RowTableAction types.
+ */
+export declare type RowTableAction = RowButtonTableAction;
+/**
+ * All currently supported UI types.
+ */
+export declare type TableActionUIType = "button";
+/**
+ * Base interface for BulkTableActions and RowTableActions.
+ */
+export interface TableAction {
+    /** ID used to identify this action. */
+    readonly id: string;
+    /** Type of action that describes how it is rendered, e.g. as a button **/
+    readonly uiType: TableActionUIType;
+}
+/**
+ * An action that is displayed as a button in a table's menu bar.
+ */
+export interface BulkButtonTableAction extends TableAction {
+    readonly uiType: "button";
+    /** Icon of the button that will be rendered in the menu bar. **/
+    readonly icon: string;
+    /** Label that might be rendered on a button beside or instead of the icon. **/
+    readonly label: string;
+    /** Tooltip that is displayed, when hovering the button. **/
+    readonly tooltip: string;
+    /**
+     * Runs the action code.
+     *
+     * @param actionContext the data the action can operate on.
+     **/
+    trigger(actionContext: BulkActionContext): Promise<void>;
+    /**
+     * Actions can optionally provide a display state that controls
+     * if this action is visible or enabled in a table's menu bar.
+     *
+     * @param tableModel the table model that requests the display state.
+     */
+    provideDisplayState?(tableModel: TableModel): Partial<TableActionDisplayState>;
+}
+/**
+ * An action that is displayed as a button in the row of all table item.
+ */
+export interface RowButtonTableAction extends TableAction {
+    readonly uiType: "button";
+    /** Icon of the button that will be rendered in the table row **/
+    readonly icon: string;
+    /** Label that might be rendered on a button beside or instead of the icon. **/
+    readonly label: string;
+    /** Tooltip that is displayed, when hovering the button. **/
+    readonly tooltip: string;
+    /**
+     * Runs the action code.
+     *
+     * @param actionContext the data the action can operate on.
+     **/
+    trigger(actionContext: RowActionContext): Promise<void>;
+    /**
+     * Actions can optionally provide a display state that controls
+     * if this action is visible or enabled for a specific table item.
+     *
+     * @param tableModel the table model that requests the display state.
+     * @param tableItem the current table item for the state is requested.
+     */
+    provideDisplayState?(tableModel: TableModel, tableItem: TableItem): Partial<TableActionDisplayState>;
+}
+/**
+ * Data that a {@link RowTableAction} can operate on.
+ */
+export interface RowActionContext {
+    /**
+     * The table model that the action is triggered for.
+     * The model provides access to items and metadata.
+     */
+    readonly model: TableModel;
+    /** Renders the given field value to a string. */
+    renderAsString(fieldName: string, value: any): string;
+    /** Provides the current active item, for which the action is triggered. Used for inline actions. **/
+    getActiveItem(): Promise<TableItem | undefined>;
+    /** Provides the current geometry of the active item **/
+    getGeometryOfActiveItem(): Promise<ItemGeometry | undefined>;
+}
+/**
+ * Data that a {@link BulkTableAction} can operate on.
+ */
+export interface BulkActionContext {
+    /**
+     * The table model that the action is triggered for.
+     * The model provides access to items and metadata.
+     */
+    readonly model: TableModel;
+    /** Renders the given field value to a string. */
+    renderAsString(fieldName: string, value: any): string;
+    /** Provides a subset of items, usually the selected items from a result-ui **/
+    getSelectedItems(): Promise<TableItem[]>;
+    /** Optional: returns geometries for currently selected items **/
+    getGeometriesForSelectedItems?(): Promise<ItemGeometry[]>;
+}
+/**
+ * Event specifiers for the {@link TableActionResolver}.
+ * <ul>
+ *      <li>Key: event name</li>
+ *      <li>Type: event type in event handler</li>
+ * </ul>
+ */
+export interface TableActionResolverContextEvents {
+    /** Emitted after an action was added or removed **/
+    "bulk-actions-changed": void;
+    /** Emitted after an row action was added or removed **/
+    "row-actions-changed": void;
+}
+/**
+ * A bridge and extension point between the requirements of a concrete UI to lookup actions
+ * and a dynamic rendering of actions in the UI.
+ */
+export interface TableActionResolver {
+    /**
+     * Creates a resolve context that provides access to actions.
+     *
+     * @param options the resolving options
+     */
+    createResolverContext(options: TableActionResolverContextOptions): TableActionResolverContext;
+}
+/**
+ * Options controlling the result of {@link TableActionResolver.createResolverContext}.
+ */
+export interface TableActionResolverContextOptions {
+    /**
+     * IDs of {@link BulkTableAction}s to resolve.
+     * The order of the IDs determines the order of the resolved actions.
+     * The expression `["*"]` gets all available actions in a implementation-specific order.
+     */
+    bulkActionIds: string[];
+    /**
+     * IDs of {@link RowTableAction}s to resolve.
+     * The order of the IDs determines the order of the resolved actions.
+     * The expression `["*"]` gets all available actions in a implementation-specific order.
+     */
+    rowActionIds: string[];
+    /**
+     * The current result model for which the actions should be resolved.
+     */
+    model: ResultModel;
+}
+/**
+ *  An object of this kind lives only for the time a concrete UI is displayed.
+ *  It provides a way to react to action state changes, e.g. when an action is hidden or deactivated.
+ *  Additionally, it provides a way to conditionally render row actions.
+ */
+export interface TableActionResolverContext extends EventSource<TableActionResolverContextEvents> {
+    /**
+     * Gets actions available for the TableModel.
+     */
+    getBulkActions(tableModel: TableModel): TableActionItem<BulkTableAction>[];
+    /**
+     * Gets actions available for the TableModel and TableItem.
+     */
+    getRowActions(tableModel: TableModel, tableItem: TableItem): TableActionItem<RowTableAction>[];
+    /**
+     * Must be called by a UI to indicate that the context is no longer required.
+     */
+    destroy(): void;
+}
+/**
+ * Links a {@link TableAction} to the "enabled" state.
+ */
+export interface TableActionItem<T extends TableAction> {
+    /** A TableAction */
+    action: T;
+    /**
+     * `true` if the action enabled.
+     */
+    enabled: boolean;
+}
+/**
+ * UI state of a {@link TableAction}.
+ */
+export interface TableActionDisplayState {
+    /**
+     * `true` if the corresponding action should be displayed. If `false`, the action is not displayed in the UI.
+     */
+    visible: boolean;
+    /**
+     * `true` if the corresponding action should be rendered as "clickable" (if visible).
+     * If `false` the action is rendered disabled.
+     */
+    enabled: boolean;
+}
+/** Used by the {@link TableActionResolver} implementation to allow the customization
+ *  of the visible and enabled states of a row action.
+ */
+export interface TableActionDisplayStateProvider {
+    /**
+     * Provides the UI state information for an action.
+     * @param actionId ID of the action to decide upon.
+     * @param tableModel the current table model.
+     * @param tableItem the current table item. `undefined` if the state is requested for a {@link BulkTableAction}.
+     * @returns the state. `undefined` if no state could be provided.
+     */
+    provideDisplayState(actionId: string, tableModel: TableModel, tableItem?: TableItem): Partial<TableActionDisplayState> | undefined;
+}

package/result-api/api/{all.d.ts → index.d.ts}

@@ -1,3 +1,4 @@
 export * from "./model";
 export * from "./service";
 export * from "./ui";
+export * from "./actions";

package/result-api/api/model.d.ts

@@ -1,111 +1,230 @@
-import { EventSource } from "apprt-core/Events";
-import { DeepReadonly } from "apprt-core/Types";
+/// <reference types="arcgis-js-api" />
+import type { EventSource } from "apprt-core/Events";
+import type { DeepReadonly } from "apprt-core/Types";
+import type { Geometry, SpatialReference } from "esri/geometry";
 /**
  * The event specifiers for the result model.
  * Key: event name, Type: event type in event handler.
  */
 export interface ResultModelEvents {
-    /**
-     * Emitted when the array of result set changes, for example
-     * if another result set has been added or one has been removed.
-     */
-    "results-changed": {
-        added?: readonly ResultSet<any>[];
-        removed?: readonly ResultSet<any>[];
+    /** Emitted after a new table has been added to the model. */
+    "table-added": {
+        id: string;
+    };
+    /** Emitted after a table has been removed from the model. */
+    "table-removed": {
+        id: string;
     };
+    /** Emitted when the model is destroyed. */
+    "destroyed": void;
 }
+/**
+ * A result model represents a collection of result tables.
+ */
 export interface ResultModel extends EventSource<ResultModelEvents> {
     /**
-     * The optional display title of this result set.
-     * The UI should display this title in a prominent position and size.
+     * A model may have multiple result tables, each conceptually resembling a table of records.
      */
-    readonly title: string | undefined;
+    readonly tables: readonly TableModel<any>[];
+    /** Destroys all its child table models. Destruction emits the 'destroyed' event. */
+    destroy(): void;
     /**
-     * An optional subtitle for this model.
+     * Attempts to remove the table model with the given `id`.
+     * Returns `true` and emits the `table-removed` events if the table was found.
+     * Returns `false` and does nothing otherwise.
      */
-    readonly subtitle: string | undefined;
-    /**
-     * A model may have multiple result sets, each conceptually resembling a table of records.
-     */
-    readonly results: readonly ResultSet<any>[];
+    removeTableModel(id: string): boolean;
 }
 /**
- * The event specifiers for the result set.
+ * The event specifiers for the result table.
  * Key: event name, Type: event type in event handler.
  */
-export interface ResultSetEvents {
-    /** Emitted when the state of the result set changed. */
+export interface TableModelEvents {
+    /** Emitted when the state of the result table changed. */
     "state-changed": {
-        state: ResultSetState;
+        state: TableState;
     };
-    /** Emitted when the total number of results in the result set changed. */
-    "total-changed": {
-        total: number;
+    /** Emitted when the total number of results in the table changed. */
+    "total-items-changed": {
+        totalItems: TotalItemInfo | undefined;
     };
     /** Emitted when the sort order changed. */
-    "sort-by-changed": {
-        sortBy: DeepReadonly<SortSpecifier>;
+    "sorted-by-changed": {
+        sortedBy: DeepReadonly<SortSpecifier> | undefined;
     };
+    /** Emitted when the table model is destroyed. */
+    "destroyed": void;
+}
+/**
+ * Represents the most generic form of a result item.
+ * Note that table models must not be changed directly from the outside.
+ * Use modifying methods on the table model instead!
+ */
+export interface TableItem {
+    /** Unique id in its model. */
+    id: string;
+    /** Raw attributes of this item (see `fields` in model interface). */
+    attributes: Record<string, unknown>;
+}
+/**
+ * Returned by the model when loading item geometries.
+ */
+export interface ItemGeometry {
+    /** Unique id of the table item that this geometry belongs to. */
+    id: string;
+    /** Item geometry */
+    geometry: Geometry;
+}
+/**
+ * Represents a collection of result items.
+ * All items in a table have the same shape.
+ */
+export declare type TableModel<T extends TableItem = TableItem> = TableModelBase<T> & EnforceInvariants<TableModelBase<T>>;
+/** Holds information about the total number of items in a model. */
+export interface TotalItemInfo {
+    /** The number of items shown to the user. */
+    count: number;
+    /** Whether there were more items that are not shown (e.g. query limits exceeded). */
+    hasMoreItems: boolean;
+}
+/**
+ * Options of this type can be passed to a model during load.
+ */
+export interface LoadOptions {
+    maxItems?: number;
+}
+/**
+ * Represents the capabilities of a table model.
+ */
+export interface TableModelCapabilities {
+    /** Whether items in this model have a geometry. */
+    supportsGeometry: boolean;
 }
-/** Represents the most generic form of a result item. */
-export declare type ResultItem = Record<string, unknown>;
-/** Represents the results within a single topic. */
-export declare type ResultSet<T = ResultItem> = ResultSetBase<T> & EnforceInvariants<ResultSetBase<T>>;
-/** Represents the results within a single topic. */
-export interface ResultSetBase<T = ResultItem> extends EventSource<ResultSetEvents> {
-    /** The unique id of this result set within its parent model. */
+/**
+ * Represents a collection of table items.
+ * This interface must be implemented by a table model.
+ *
+ * Note that this interface does not express all invariants through the type model.
+ * For example, when a model has been loaded successfully, `fields` and other metadata must be available.
+ * You can cast instances of `TableModelBase<T>` to `TableModel<T>` manually to *promise* that you respect the
+ * invariants of this interface.
+ */
+export interface TableModelBase<T extends TableItem = TableItem> extends EventSource<TableModelEvents> {
+    /** The unique id of this table within its parent model. */
     readonly id: string;
-    /** A human readable title for this result set. */
+    /** A human readable title for this table. */
     readonly title: string;
-    /** The current load state of this set. */
-    readonly state: ResultSetState;
-    /** The set of fields used by the items in this store. */
-    readonly fields: DeepReadonly<ResultSetField[]> | undefined;
+    /** The current load state of this table. */
+    readonly state: TableState;
+    /**
+     * Capabilities of this model.
+     * Present if `state === "loaded"`, although it may change.
+     */
+    readonly capabilities: DeepReadonly<TableModelCapabilities> | undefined;
+    /**
+     * The set of fields used by the items in this store.
+     * Present if `state === "loaded"`.
+     */
+    readonly fields: DeepReadonly<TableField[]> | undefined;
     /** The current sort order. */
-    readonly sortBy: DeepReadonly<SortSpecifier> | undefined;
-    /** The total number of results. */
-    readonly total: number | undefined;
-    /** An error that occurred while loading this set. */
+    readonly sortedBy: DeepReadonly<SortSpecifier> | undefined;
+    /**
+     * The total number of results that can be shown to the user.
+     * Present if `state === "loaded"`, although it may change.
+     */
+    readonly totalItems: TotalItemInfo | undefined;
+    /**
+     * An error that occurred while loading this table.
+     * Present if `state === "error"`.
+     */
     readonly loadError: Error | undefined;
+    /** Performs cleanup. Destruction emits the `destroyed` event.*/
+    destroy(): void;
+    /**
+     * Called once by the UI on initialization.
+     * The UI can provide initial options such as the maximum number of items to fetch.
+     * This method should trigger a state change from `not-loaded` to `loading` / `loaded`,
+     * after which metadata should be available.
+     */
+    load(options?: LoadOptions): Promise<void>;
+    /**
+     * Waits until the table is loaded.
+     * After the promise resolved, the model's state will be "loaded",
+     * i.e. metadata will be available.
+     */
+    whenLoaded(): Promise<void>;
+    /**
+     * Updates the sort order.
+     * May throw an exception if the field is not known or if it does not support sorting.
+     *
+     * On success, the `sortBy` property is updated and the `sort-by-changed` event is thrown.
+     */
+    setSortedBy(spec: SortSpecifier): void;
     /**
      * Returns up to `count` items starting from `startIndex`.
      * This is typically used by the UI to render the contents of a page.
+     *
+     * The items order for this method is affected by the sort order.
+     *
+     * This method should only return fewer than `count` items if the query
+     * goes beyond the `total` number of items.
+     *
+     * TODO: Probably does not need to be async if we require that all items are always loaded
+     * or that only loaded items may be accessed.
      */
-    getItems(startIndex: number, count: number): Promise<T[]>;
+    getItemsByRows(startIndex: number, count: number): Promise<T[]>;
     /**
-     * Takes an item as input (returned by `getItems()`) and returns a record of display values.
-     * The keys in the returned record must be field names of the item, but the values may be different.
+     * Searches for the items with the given ids and returns them.
+     *
+     * NOTE: May currently throw if an unknown item id is used.
      */
-    getDisplayValues?(item: T): Record<string, unknown>;
+    getItemsById(itemIds: string[]): Promise<T[]>;
+    /**
+     * Returns all item ids known to the model.
+     */
+    getAllItemIds(): Promise<string[]>;
+    /**
+     * Returns an array of geometries for the selected results.
+     * This is typically used to show the results in the map.
+     * The requested spatial reference system is forwarded to the underlying implementation.
+     * The implementation must return geometries in the requested SRS or thrown an error.
+     *
+     * NOTE: This API is unfinished - it will always fetch all geometries.
+     *
+     * This method is optional as not every data source supports geometries.
+     */
+    getGeometries?(sr: SpatialReference): Promise<ItemGeometry[]>;
 }
 /**
- * Represents the state of a result set.
+ * Represents the state of a table model.
  *
  * The different states must behave as follows:
  *
  * - "loading":
- *      The result set is currently loading. Metadata (e.g. fields, total etc.) may not be available.
+ *      The table is currently loading. Metadata (e.g. fields, total etc.) may not be available.
  *
  * - "loaded":
- *      The result set has finished loading for now.
+ *      The table has initialized.
  *      Metadata must be available (e.g. fields must be a valid array).
  *      Note that this does not mean that all _Items_ need to be loaded, those can be fetched later.
  *
  * - "error":
- *      An error occurred while loading the result set.
+ *      An error occurred while loading the table.
  *      The `loadError` field must contain a valid error value explaining what happened.
  */
-export declare type ResultSetState = "loading" | "loaded" | "error";
-/** Represents an item field (or attribute) within a result set. */
-export interface ResultSetField {
+export declare type TableState = "not-loaded" | "loading" | "loaded" | "error";
+/** Represents an item field (or attribute) within a table model. */
+export interface TableField {
     /** The raw property name of this field. */
     name: string;
-    /** The value type. TODO specify */
-    type?: string;
+    /** The UI implementation can select an appropriate style based on the field type. */
+    type: string;
     /** The display title of this field, e.g. used as a column header. */
-    displayTitle: string;
+    title: string;
+    /** Whether this field represents an object identifier. Default: false. */
+    identifier?: boolean;
 }
-/** Specifies the sort order in a result set. */
+/** Specifies the sort order in a result table. */
 export interface SortSpecifier {
     /** The field being sorted by. */
     fieldName: string;
@@ -115,11 +234,13 @@ export interface SortSpecifier {
 declare type MakeRequired<T, K extends keyof T> = {
     [P in K]: NonNullable<T[P]>;
 };
-declare type EnforceInvariants<T extends ResultSetBase<any>> = ({
+declare type EnforceInvariants<T extends TableModelBase<any>> = ({
+    readonly state: "not-loaded";
+}) | ({
     readonly state: "loading";
 }) | ({
     readonly state: "loaded";
-} & MakeRequired<T, "fields" | "sortBy" | "total">) | ({
+} & MakeRequired<T, "fields" | "totalItems">) | ({
     readonly state: "error";
 } & MakeRequired<T, "loadError">);
 export {};

package/result-api/api/service.d.ts

@@ -1,11 +1,30 @@
+import { ComplexQueryExpression } from "store-api/api/ComplexQueryLang";
+import { AsyncStore, QueryOptions } from "store-api/api/Store";
 import { ResultModel } from "./model";
 export interface Handle {
     remove(): void;
 }
-/** Options for the `open` method of the `OpenResultsService`. */
-export interface OpenResultsOptions {
-    position?: "default";
-}
+/**
+ * Provides a service to show a result model in the UI.
+ *
+ * The service can be injected by referencing `"result-api.OpenResultsService"`.
+ */
 export interface OpenResultsService {
-    open(model: ResultModel, options?: OpenResultsOptions): Handle;
+    /**
+     * Opens the given model in the UI and returns a handle that allows the caller
+     * to hide the model again.
+     */
+    open(model: ResultModel): Handle;
+}
+export interface ResultModelFactoryOptions {
+    topicTitle: string;
+    store: AsyncStore<any>;
+    queryExpression: ComplexQueryExpression;
+    queryOptions?: QueryOptions;
+}
+export interface ResultModelFactory {
+    /**
+     * Creates a result model from a store and a complex query.
+     */
+    fromStoreAndQuery(options: ResultModelFactoryOptions): Promise<ResultModel>;
 }

package/result-api/api/ui.d.ts

@@ -6,13 +6,11 @@ import { ResultModel } from "./model";
 export interface ResultUIFactory {
     /**
      * Creates a new UI instance.
-     *
-     * TODO: Options
      */
     createUI(): ResultUI;
 }
 /**
- * Implements the display of a single result model.
+ * Displays a single result model.
  */
 export interface ResultUI {
     /**
@@ -21,6 +19,7 @@ export interface ResultUI {
     destroy(): void;
     /**
      * Displays the content of the given model.
+     * Existing content for previous models is replaced.
      */
     show(model: ResultModel): void;
     /**

package/result-api/module.d.ts

@@ -1 +1,7 @@
 export { OpenResultsServiceImpl as OpenResultsService } from "./OpenResultsServiceImpl";
+export { ResultModelFactoryImpl as ResultModelFactory } from "./ResultModelFactoryImpl";
+export { TableActionResolverImpl as TableActionResolver } from "./TableActionResolverImpl";
+export { ExportCsvAction } from "./actions/ExportCsvAction";
+export { ZoomToSelectedAction } from "./actions/ZoomToSelectedAction";
+export { ZoomToItemAction } from "./actions/ZoomToItemAction";
+export { SelectionEventHandler } from "./SelectionEventHandler";

package/result-ui/CellRenderer.d.ts

@@ -0,0 +1,27 @@
+export declare const CellRenderer: import("vue/types/v3-define-component").DefineComponent<{
+    type: {
+        type: StringConstructor;
+        required: true;
+    };
+    identifier: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    value: {
+        required: true;
+    };
+}, import("vue").Data, import("vue").Data, {}, {}, import("vue/types/v3-component-options").ComponentOptionsMixin, import("vue/types/v3-component-options").ComponentOptionsMixin, {}, string, Readonly<import("vue").ExtractPropTypes<{
+    type: {
+        type: StringConstructor;
+        required: true;
+    };
+    identifier: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    value: {
+        required: true;
+    };
+}>>, {
+    identifier: boolean;
+}>;

package/result-ui/ConditionalTooltip.d.ts

@@ -0,0 +1,19 @@
+import { VNode } from "vue";
+declare const _default: import("vue/types/v3-define-component").DefineComponent<{
+    text: {
+        type: StringConstructor;
+        default: undefined;
+    };
+}, import("vue").Data, import("vue").Data, {}, {
+    renderActivator(data: {
+        on: Record<string, any>;
+    } | undefined): VNode | undefined;
+}, import("vue/types/v3-component-options").ComponentOptionsMixin, import("vue/types/v3-component-options").ComponentOptionsMixin, {}, string, Readonly<import("vue").ExtractPropTypes<{
+    text: {
+        type: StringConstructor;
+        default: undefined;
+    };
+}>>, {
+    text: string;
+}>;
+export default _default;