@vertigis/viewer-spec/app-config/web/KpiCardModelProperties.d.ts

VertiGIS Viewer Specification

import type { EntityProperties } from "@vertigis/arcgis-extensions/Entity";
import type { FormatSettingsProperties } from "@vertigis/arcgis-extensions/support/FormatSettings";
import type { ItemRef } from "../common/ItemRef.js";
import type { ColorConfig } from "../common/colors.js";
import type { ComponentModelProperties } from "./ComponentModelProperties.js";
import type { FeatureSetProperties } from "./FeatureSetProperties.js";
/**
 * Configuration for a KPI card component.
 */
export interface KpiCardModelProperties extends ComponentModelProperties {
    /**
     * The background color for the KPI card. If not specified, the branding
     * theme color will be used.
     */
    backgroundColor?: ColorConfig;
    /**
     * Configuration for the bottom section.
     */
    bottom?: KpiCardSectionModelProperties;
    /**
     * A set of conditions to evaluated. If a condition's expression is true,
     * its configuration will take effect. For any given configuration property,
     * conditions that appear earlier in this list will take precedence over
     * ones that come later.
     */
    conditions?: KpiCardConditionModelProperties[];
    /**
     * Configuration for the middle section.
     */
    middle?: KpiCardSectionModelProperties;
    /**
     * A reference value to use for comparison. This is available as a
     * predefined `reference` variable within Arcade expressions.
     */
    reference?: number;
    /**
     * The type of reference to use.
     */
    referenceType?: ReferenceType;
    /**
     * When `referenceType` is "statistic", this Arcade expression will be used
     * to calculate the reference value.
     */
    referenceExpression?: string;
    /**
     * The feature source (e.g. layer, sublayer, table, etc.) that this KPI card
     * is associated with.
     */
    source?: ItemRef;
    /**
     * Configuration for the top section.
     */
    top?: KpiCardSectionModelProperties;
    /**
     * The initial KPI value. Normally this is computed from `valueExpression`
     * rather than set directly.
     */
    value?: number;
    /**
     * An Arcade expression that calculates the KPI value from a feature set.
     * The feature set is made available via a `$features` variable that is
     * available for use within the expression.
     */
    valueExpression?: string;
    /**
     * The set of features contained by the kpi-card model. This property is
     * only serialized into saved projects. Web only.
     */
    results?: FeatureSetProperties;
}
/**
 * Configuration for a specific section of a KPI card (top, middle, or bottom).
 */
export interface KpiCardSectionModelProperties {
    /**
     * The text to display for this section. The text can contain embedded
     * Arcade expressions, surrounded by braces ("{" and "}").
     */
    text?: string;
    /**
     * The ID of the icon to display in this section, or undefined to show no
     * icon.
     */
    icon?: string;
    /**
     * The size of the text and icon.
     */
    size?: KpiCardSectionSize;
    /**
     * The foreground color to use for the text and icon. If undefined, it will
     * use the theme's color.
     */
    color?: ColorConfig;
    /**
     * Format settings that affect how numbers and dates are formatted. Any
     * setting that isn't specified will use the equivalent setting in the
     * region service by default.
     */
    formatSettings?: FormatSettingsProperties;
}
/**
 * Conditional configuration that is applied when the given expression is true.
 */
export interface KpiCardConditionModelProperties extends EntityProperties {
    /**
     * The Arcade expression to evaluate. If the return value is "truthy", the
     * configuration in this condition will take effect.
     */
    expression?: string;
    /**
     * The background color to use if the condition is true.
     */
    backgroundColor?: ColorConfig;
    /**
     * Settings to apply to the top section if the condition is true.
     */
    top?: KpiCardSectionModelProperties;
    /**
     * Settings to apply to the middle section if the condition is true.
     */
    middle?: KpiCardSectionModelProperties;
    /**
     * Settings to apply to the bottom section if the condition is true.
     */
    bottom?: KpiCardSectionModelProperties;
}
/**
 * Determines how the reference value for a KPI card is calculated. A reference
 * is a number to compare against.
 *
 * - "none": No reference value is used for this card.
 * - "previous": The reference value will reflect the previous KPI value whenever
 *   it changes. Initially it will be undefined.
 * - "fixed": A constant value.
 * - "statistic": A calculated value determined via an Arcade expression (see
 *   `referenceExpression`).
 */
export type ReferenceType = "none" | "previous" | "fixed" | "statistic";
/**
 * Determines how large the text and icon are for a KPI card section.
 */
export type KpiCardSectionSize = "extra-small" | "small" | "medium" | "large" | "extra-large";
/**
 * Identifies one of the three possible sections in a KPI card.
 */
export type KpiCardSectionName = "top" | "middle" | "bottom";