@rockrms/obsidian-framework 17.5.2 → 18.1.0

package/types/Utility/block.d.ts

@@ -1,12 +1,13 @@
-import { BlockEvent, InvokeBlockActionFunc, SecurityGrant } from "@Obsidian/Types/Utility/block";
+import { BlockEvent, InvokeBlockActionFunc, InvokeStreamingBlockActionFunc, SecurityGrant } from "@Obsidian/Types/Utility/block";
 import { IBlockPersonPreferencesProvider } from "@Obsidian/Types/Core/personPreferences";
 import { ExtendedRef } from "@Obsidian/Types/Utility/component";
 import { Ref } from "vue";
 import { Guid } from "@Obsidian/Types";
-import { HttpPostFunc } from "@Obsidian/Types/Utility/http";
+import { HttpDoStreamingApiCallFunc, HttpPostFunc } from "@Obsidian/Types/Utility/http";
 import { ValidPropertiesBox } from "@Obsidian/ViewModels/Utility/validPropertiesBox";
 import { IEntity } from "@Obsidian/ViewModels/entity";
 import { BrowserBus } from "./browserBus";
+import { BlockRole } from "@Obsidian/Enums/Cms/blockRole";
 /**
  * Maps the block configuration values to the expected type.
  *
@@ -41,6 +42,28 @@ export declare function useBlockActionUrl(): (actionName: string) => string;
  * @returns A function that can be used to provide the invoke block action.
  */
 export declare function createInvokeBlockAction(post: HttpPostFunc, pageGuid: Guid, blockGuid: Guid, pageParameters: Record<string, string>, sessionGuid: Guid, interactionGuid: Guid): InvokeBlockActionFunc;
+/**
+ * Gets the function that will be used to invoke block actions.
+ *
+ * @returns An instance of @see {@link InvokeStreamingBlockActionFunc}.
+ */
+export declare function useInvokeStreamingBlockAction(): InvokeStreamingBlockActionFunc;
+/**
+ * Creates a function that can be provided to the block that allows calling
+ * block actions and returning streaming data.
+ *
+ * @private This should not be used by plugins.
+ *
+ * @param post The function to handle the post operation.
+ * @param pageGuid The unique identifier of the page.
+ * @param blockGuid The unique identifier of the block.
+ * @param pageParameters The parameters to include with the block action calls.
+ * @param sessionGuid The unique identifier of the session from the original page request.
+ * @param interactionGuid The unique identifier of the interaction from the original page request.
+ *
+ * @returns A function that can be used to provide the invoke block action.
+ */
+export declare function createInvokeStreamingBlockAction(doStreamingApiCall: HttpDoStreamingApiCallFunc, pageGuid: Guid, blockGuid: Guid, pageParameters: Record<string, string>, sessionGuid: Guid, interactionGuid: Guid): InvokeStreamingBlockActionFunc;
 /**
  * Provides the reload block callback function for a block. This is an internal
  * method and should not be used by plugins.
@@ -83,13 +106,6 @@ export declare function provideStaticContent(content: Ref<Node[]>): void;
  * @returns A string of HTML content or undefined.
  */
 export declare function useStaticContent(): Node[];
-/**
- * Provides the browser bus configured to publish messages for the current
- * block.
- *
- * @param bus The browser bus.
- */
-export declare function provideBlockBrowserBus(bus: BrowserBus): void;
 /**
  * Gets the browser bus configured for use by the current block. If available
  * this will be properly configured to publish messages with the correct block
@@ -202,10 +218,11 @@ export declare function useEntityTypeGuid(): Guid | undefined;
  * useSecurityGrant() function instead.
  *
  * @param token The token provided by the server.
+ * @param renewTokenCallback An optional function that overrides the default token renewal callback.
  *
  * @returns A reference to the security grant that will be updated automatically when it has been renewed.
  */
-export declare function getSecurityGrant(token: string | null | undefined): SecurityGrant;
+export declare function getSecurityGrant(token: string | null | undefined, renewTokenCallback?: (() => Promise<string | null> | string | null)): SecurityGrant;
 /**
  * Provides the security grant to child components to use in their API calls.
  *
@@ -284,4 +301,67 @@ export declare function providePersonPreferences(provider: IBlockPersonPreferenc
  * @returns An object that implements {@link IBlockPersonPreferencesProvider}.
  */
 export declare function usePersonPreferences(): IBlockPersonPreferencesProvider;
+/**
+ * The block actions that can be performed on a block.
+ */
+export interface IBlockActions {
+    /** Called when the block should hide itself. */
+    hideBlock?(): Promise<void>;
+    /** Called when the block should show itself. */
+    showBlock?(): Promise<void>;
+    /** Called when the block should reload itself. */
+    reloadBlock?(): Promise<void>;
+}
+/**
+ * Registers a block with the specified actions and role.
+ *
+ * **This is an internal function that should not be called by plugins.**
+ *
+ * @param actions The actions that can be performed on the block.
+ * @param role The role of the block on the page.
+ */
+export declare function registerBlock(actions: IBlockActions, role: BlockRole): void;
+/**
+ * Unregisters a block with the specified actions and role.
+ *
+ * **This is an internal function that should not be called by plugins.**
+ *
+ * @param actions The actions that can be performed on the block.
+ * @param role The role of the block on the page.
+ */
+export declare function unregisterBlock(actions: IBlockActions, role: BlockRole): void;
+/**
+ * Provides the block actions that will be used by child components
+ * to access the actions associated with their block.
+ *
+ * **This is an internal function that should not be called by plugins.**
+ *
+ * @param actions The actions that can be performed on the block.
+ */
+export declare function provideBlockActions(actions: IBlockActions): void;
+/**
+ * Gets the block actions that can be used by child components
+ * to access the actions associated with their block.
+ *
+ * @returns An object that implements {@link IBlockActions}.
+ */
+export declare function useBlockActions(): IBlockActions;
+/**
+ * Hides the blocks on the page that match the specified role.
+ *
+ * @param role The role to use when deciding which blocks to hide.
+ */
+export declare function hideBlockRole(role: BlockRole): Promise<void>;
+/**
+ * Shows the blocks on the page that match the specified role.
+ *
+ * @param role The role to use when deciding which blocks to show.
+ */
+export declare function showBlockRole(role: BlockRole): Promise<void>;
+/**
+ * Reloads the blocks on the page that match the specified role.
+ *
+ * @param role The role to use when deciding which blocks to reload.
+ */
+export declare function reloadBlockRole(role: BlockRole): Promise<void>;
 export {};

package/types/Utility/browserBus.d.ts

@@ -8,6 +8,10 @@ export declare const PageMessages: {
      * Sent when the query string is changed outside the context of a page load.
      */
     readonly QueryStringChanged: "page.core.queryStringChanged";
+    /**
+     * Sent when one of the context entity values have changed on the page.
+     */
+    readonly ContextEntityChanged: "page.core.contextEntityChanged";
 };
 /**
  * Framework messages that will be sent for blocks.

package/types/Utility/chartUtils.d.ts

@@ -0,0 +1,139 @@
+import { ChartData, ChartOptions, ChartType, Plugin } from "@Obsidian/Libs/chart";
+import { ChartNumericDataPointBag } from "@Obsidian/ViewModels/Reporting/chartNumericDataPointBag";
+import { Enumerable } from "./linq";
+import { RockDateTime } from "./rockDateTime";
+export declare const BarDatasetLabelsPlugin: Plugin<"bar">;
+interface IBarValueLabelsPluginOptions {
+    isBackgroundDark?: (barColor: string) => boolean;
+    formatter?: (value: string) => string;
+}
+declare module "@Obsidian/Libs/chart" {
+    interface PluginOptionsByType<TType extends ChartType> {
+        barValueLabels?: IBarValueLabelsPluginOptions;
+    }
+}
+export declare const BarValueLabelsPlugin: Plugin<"bar">;
+export declare class BarChartDataBuilder {
+    private dataPoints;
+    private seriesNameOrderBy;
+    private constructor();
+    static createFromDataPoints(dataPoints: ChartNumericDataPointBag[]): BarChartDataBuilder;
+    /**
+     * Sets the order of the series in the chart to match the supplied array. Any series not in the array will be placed at the end.
+     *
+     * This is useful when you want to control the order of the series in the chart
+     * instead of relying on the order of the source array elements.
+     *
+     * For bar charts, this affects the order of the bars in the chart.
+     */
+    withSeriesOrder(orderBy: string[]): BarChartDataBuilder;
+    /**
+     * Sets the order of the series in the chart based on a comparator function.
+     *
+     * This is useful when you want to control the order of the series in the chart
+     * instead of relying on the order of the source array elements.
+     *
+     * For bar charts, this affects the order of the bars in the chart.
+     */
+    withSeriesOrder(orderBy: ((seriesNameA: string, seriesNameB: string) => number)): BarChartDataBuilder;
+    build(): ChartData<"bar">;
+}
+export declare class BarChartOptionsBuilder {
+    private options;
+    private constructor();
+    static create(): BarChartOptionsBuilder;
+    build(): ChartOptions<"bar">;
+    withXAxisAsDate(options?: {
+        timeUnit: "millisecond" | "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+    }): BarChartOptionsBuilder;
+    /**
+     * Formats the value as a percentage (with a '%' sign) in the Y-axis ticks and tooltips.
+     *
+     * This assumes the value is a fractional number representing a percentage (e.g., 0.5 for 50%).
+     */
+    withYAxisAsPercent(options?: {
+        maxDecimalPlaces: number | undefined;
+    }): BarChartOptionsBuilder;
+    withoutLegend(): BarChartOptionsBuilder;
+    withResponsiveSizing(): BarChartOptionsBuilder;
+    withoutTooltips(): BarChartOptionsBuilder;
+    withBarValueLabels(options?: IBarValueLabelsPluginOptions): BarChartOptionsBuilder;
+}
+export declare class LineChartDataBuilder {
+    private dataPoints;
+    private seriesNameOrderBy;
+    private constructor();
+    static createFromData(dataPoints: ChartNumericDataPointBag[]): LineChartDataBuilder;
+    /**
+     * Sets the order of the series in the chart to match the supplied array. Any series not in the array will be placed at the end.
+     *
+     * This is useful when you want to control the order of the series in the chart
+     * instead of relying on the order of the source array elements.
+     *
+     * For line charts, this affects which line is on top of others.
+     */
+    withSeriesOrder(orderBy: string[]): LineChartDataBuilder;
+    /**
+     * Sets the order of the series in the chart based on a comparator function.
+     *
+     * This is useful when you want to control the order of the series in the chart
+     * instead of relying on the order of the source array elements.
+     *
+     * For line charts, this affects which line is on top of others.
+     */
+    withSeriesOrder(orderBy: ((seriesNameA: string, seriesNameB: string) => number)): LineChartDataBuilder;
+    build(): ChartData<"line">;
+}
+export declare class LineChartOptionsBuilder {
+    private options;
+    private constructor();
+    static create(): LineChartOptionsBuilder;
+    static createFrom(options?: ChartOptions<"line">): LineChartOptionsBuilder;
+    build(): ChartOptions<"line">;
+    withXAxisAsDate(options?: {
+        timeUnit: "millisecond" | "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+    }): LineChartOptionsBuilder;
+    /**
+     * Formats the value as a percentage (with a '%' sign) in the Y-axis ticks and tooltips.
+     *
+     * This assumes the value is a fractional number representing a percentage (e.g., 0.5 for 50%).
+     */
+    withYAxisAsPercent(options?: {
+        maxDecimalPlaces: number | undefined;
+    }): LineChartOptionsBuilder;
+    withResponsiveSizing(): LineChartOptionsBuilder;
+}
+/**
+ * Builds a cumulative chart series from an enumerable of RockDateTime objects.
+ *
+ * @param dateEnumerable An enumerable of RockDateTime objects or null/undefined values.
+ * @param options An object containing options for the series.
+ * @returns An array of ChartNumericDateTimeDataPoint objects representing the cumulative series.
+ */
+export declare function buildCumulativeRates(dateEnumerable: Enumerable<RockDateTime>, options: {
+    /**
+     * The name of the series to use in the chart.
+     */
+    seriesName: string;
+    /**
+     * The color to use for the series in the chart.
+     */
+    color: string;
+    /**
+     * The total count of recipients or messages to use for calculating the percentage.
+     */
+    totalCount: number;
+    /**
+     * Transforms the date after the ISO date string is parsed.
+     * This is useful for grouping dates into weeks or months.
+     */
+    dateTransformer?: ((d: RockDateTime) => RockDateTime) | null | undefined;
+    /**
+     * Formats the date for display in the chart.
+     * Defaults to outputting an ISO string if not provided.
+     */
+    dateFormatter?: ((d: RockDateTime) => string) | null | undefined;
+}): Enumerable<ChartNumericDataPointBag & {
+    rockDateTime: RockDateTime;
+}>;
+export {};

package/types/Utility/component.d.ts

@@ -4,6 +4,7 @@ import { PickerDisplayStyle } from "@Obsidian/Enums/Controls/pickerDisplayStyle"
 import { FilterMode } from "@Obsidian/Enums/Reporting/filterMode";
 import { ExtendedRef, ExtendedRefContext } from "@Obsidian/Types/Utility/component";
 import type { RulesPropType } from "@Obsidian/Types/validationRules";
+import type { DynamicComponentDefinitionBag } from "@Obsidian/ViewModels/Controls/dynamicComponentDefinitionBag";
 type Prop = {
     [key: string]: unknown;
 };
@@ -140,14 +141,35 @@ export declare const standardAsyncPickerProps: StandardAsyncPickerProps;
  * @returns An object of prop values that can be used with v-bind.
  */
 export declare function useStandardAsyncPickerProps(props: ExtractPropTypes<StandardAsyncPickerProps>): ExtractPropTypes<StandardAsyncPickerProps>;
-type DataViewFilterProps = {
-    /**
-     * The component data value from the C# component class.
-     */
+export type StandardDynamicComponentProps = {
     modelValue: {
-        type: PropType<Record<string, string | undefined | null>>;
+        type: PropType<Record<string, string | null | undefined>>;
         required: true;
     };
+    options: {
+        type: PropType<Record<string, string | null | undefined>>;
+        required: true;
+    };
+    executeRequest: {
+        type: PropType<(request: Record<string, string | null | undefined>) => Promise<Record<string, string | null | undefined> | null>>;
+        required: true;
+    };
+};
+/**
+ * The standard props that are available to an instantiated component by the
+ * dynamicComponent.obs component.
+ */
+export declare const standardDynamicComponentProps: StandardDynamicComponentProps;
+/**
+ * This is used to pre-load the URL in the definition so that it is ready for
+ * immediate display when passed to the dynamic component. This can be used to
+ * delay the display of the dynamic component container until the actual
+ * component is loaded into memory and ready to be displayed.
+ *
+ * @param definition The dynamic component definition that contains the URL to load.
+ */
+export declare function loadDynamicComponentDefinition(definition: DynamicComponentDefinitionBag): Promise<void>;
+type DataViewFilterProps = StandardDynamicComponentProps & {
     /**
      * The mode this filter is operating in.
      */
@@ -158,15 +180,7 @@ type DataViewFilterProps = {
 };
 /** The standard component props that will be passed to DataView Filter components. */
 export declare const dataViewFilterProps: DataViewFilterProps;
-type DataViewSelectProps = {
-    /**
-     * The component data value from the C# component class.
-     */
-    modelValue: {
-        type: PropType<Record<string, string | undefined | null>>;
-        required: true;
-    };
-};
+type DataViewSelectProps = StandardDynamicComponentProps;
 /** The standard component props that will be passed to DataView Select components. */
 export declare const dataViewSelectProps: DataViewSelectProps;
 /**

package/types/Utility/cssUtils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Gets the CSS variable value.
+ *
+ * @param cssVariableName The name of the CSS variable.
+ * @param fallbackValue The optional fallback value to use.
+ * @param targetElement The optional target element to get the CSS variable
+ * value from. Can be a CSS selector to query the element or a reference to
+ * the HTML element itself. If not provided, defaults to the document root.
+ *
+ * @returns The value of the CSS variable, the fallback value if not found, or
+ * an empty string if neither are defined.
+ */
+export declare function getCssVariableValue(cssVariableName: string, fallbackValue?: string, targetElement?: string | HTMLElement): string;

package/types/Utility/http.d.ts

@@ -14,6 +14,17 @@ import { ICancellationToken } from "./cancellation";
  * @param {any} data This will be the body of the request
  */
 export declare function doApiCall<T>(method: HttpMethod, url: string, params?: HttpUrlParams, data?: HttpBodyData, cancellationToken?: ICancellationToken): Promise<HttpResult<T>>;
+/**
+ * Make an API call.  This is a special use function that should not
+ * normally be used. Instead call useHttp() to get the HTTP functions that
+ * can be used.
+ *
+ * @param {string} method The HTTP method, such as GET
+ * @param {string} url The endpoint to access, such as /api/campuses/
+ * @param {object} params Query parameter object.  Will be converted to ?key1=value1&key2=value2 as part of the URL.
+ * @param {any} data This will be the body of the request
+ */
+export declare function doStreamingApiCall<T>(method: HttpMethod, url: string, params?: HttpUrlParams, data?: HttpBodyData, cancellationToken?: ICancellationToken): Promise<HttpResult<ReadableStream<T>>>;
 /**
  * Make a GET HTTP request. This is a special use function that should not
  * normally be used. Instead call useHttp() to get the HTTP functions that

package/types/Utility/jsonUtils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Attempts to parse the JSON and returns undefined if it could not be parsed.
+ *
+ * @param value The JSON value to parse.
+ *
+ * @returns The object that represents the JSON or undefined.
+ */
+export declare function safeParseJson<T>(value: string | null | undefined): T | undefined;