@concord-consortium/lara-interactive-api 1.6.0 → 1.7.0-pre.1

package/api.d.ts

@@ -1,4 +1,4 @@
-import { IInitInteractive, INavigationOptions, IAuthInfo, ISupportedFeatures, IShowModal, ICloseModal, IGetInteractiveListOptions, IGetInteractiveListResponse, ISetLinkedInteractives, IGetLibraryInteractiveListRequest, IJwtResponse, ICustomMessageHandler, ICustomMessagesHandledMap, IGetInteractiveSnapshotOptions, IGetInteractiveSnapshotResponse, IAddLinkedInteractiveStateListenerOptions, IDecoratedContentEvent, ITextDecorationHandler, WriteAttachmentParams, ReadAttachmentParams, GetAttachmentUrlParams, IGetReportItemAnswerHandler, IReportItemAnswer, OnUnloadFunction } from "./types";
+import { IInitInteractive, INavigationOptions, IAuthInfo, ISupportedFeatures, IShowModal, ICloseModal, IGetInteractiveListOptions, IGetInteractiveListResponse, ISetLinkedInteractives, IGetLibraryInteractiveListRequest, IJwtResponse, ICustomMessageHandler, ICustomMessagesHandledMap, IGetInteractiveSnapshotOptions, IGetInteractiveSnapshotResponse, IAddLinkedInteractiveStateListenerOptions, IDecoratedContentEvent, ITextDecorationHandler, WriteAttachmentParams, ReadAttachmentParams, GetAttachmentUrlParams, IGetReportItemAnswerHandler, IReportItemAnswer, OnUnloadFunction, IReportItemHandlerMetadata } from "./types";
 export declare const getInitInteractiveMessage: <InteractiveState = {}, AuthoredState = {}, GlobalInteractiveState = {}>() => Promise<IInitInteractive<InteractiveState, AuthoredState, GlobalInteractiveState> | null>;
 export declare const getMode: () => Promise<"runtime" | "authoring" | "report" | "reportItem" | undefined>;
 export declare const getInteractiveState: <InteractiveState>() => InteractiveState | null;
@@ -66,11 +66,12 @@ export declare const getGlobalInteractiveState: <GlobalInteractiveState>() => Gl
  */
 export declare const setGlobalInteractiveState: <GlobalInteractiveState>(newGlobalState: GlobalInteractiveState | null) => void;
 export declare const addCustomMessageListener: (callback: ICustomMessageHandler, handles?: ICustomMessagesHandledMap | undefined) => void;
-export declare const removeCustomMessageListener: () => void;
+export declare const removeCustomMessageListener: () => boolean;
 export declare const addDecorateContentListener: (callback: ITextDecorationHandler) => void;
 export declare const removeDecorateContentListener: () => void;
 export declare const addGetReportItemAnswerListener: <InteractiveState, AuthoredState>(callback: IGetReportItemAnswerHandler<InteractiveState, AuthoredState>) => void;
 export declare const removeGetReportItemAnswerListener: () => void;
+export declare const notifyReportItemClientReady: (metadata?: IReportItemHandlerMetadata | undefined) => void;
 export declare const setSupportedFeatures: (features: ISupportedFeatures) => void;
 export declare const setHeight: (height: number | string) => void;
 export declare const postDecoratedContentEvent: (msg: IDecoratedContentEvent) => void;

package/client.d.ts

@@ -1,11 +1,16 @@
 import * as iframePhone from "iframe-phone";
-import { ClientMessage, ICustomMessageHandler, ICustomMessagesHandledMap, ISupportedFeaturesRequest, ServerMessage, ITextDecorationHandler, IGetReportItemAnswerHandler, OnUnloadFunction } from "./types";
+import { ClientMessage, ICustomMessagesHandledMap, ISupportedFeaturesRequest, ServerMessage, OnUnloadFunction } from "./types";
 import { ManagedState } from "./managed-state";
 export declare const getClient: () => Client;
+/**
+ * This class is intended to provide basic helpers (like `post()` or `add/removeListener`), maintain client-specific
+ * state, and generally be as minimal as possible. Most of the client-specific helpers and logic can be implemented
+ * in api.ts or hooks.ts (or both so the client app has choice).
+ */
 export declare class Client {
     phone: iframePhone.IFrameEndpoint;
     managedState: ManagedState;
-    private customMessagesHandled;
+    customMessagesHandled: ICustomMessagesHandledMap;
     private listeners;
     private requestId;
     private onUnload;
@@ -14,12 +19,6 @@ export declare class Client {
     post(message: ClientMessage, content?: any): void;
     addListener(message: ServerMessage, callback: iframePhone.ListenerCallback, requestId?: number): boolean;
     removeListener(message: ServerMessage, requestId?: number, callback?: iframePhone.ListenerCallback): boolean;
-    addCustomMessageListener(callback: ICustomMessageHandler, handles?: ICustomMessagesHandledMap): void;
-    removeCustomMessageListener(): boolean;
-    addDecorateContentListener(callback: ITextDecorationHandler): void;
-    removeDecorateContentListener(): boolean;
-    addGetReportItemAnswerListener(callback: IGetReportItemAnswerHandler): void;
-    removeGetReportItemAnswerListener(): boolean;
     setSupportedFeatures: (request: ISupportedFeaturesRequest) => void;
     setOnUnload: (onUnload?: OnUnloadFunction<{}> | undefined) => void;
     private connect;

package/hooks.d.ts

@@ -1,4 +1,4 @@
-import { ICustomMessageHandler, ICustomMessagesHandledMap, IInitInteractive, ITextDecorationHandler } from "./types";
+import { ICustomMessageHandler, ICustomMessagesHandledMap, IInitInteractive, ITextDecorationHandler, IReportItemHandlerMetadata, IGetReportItemAnswerHandler } from "./types";
 declare type UpdateFunc<S> = (prevState: S | null) => S;
 export declare const useInteractiveState: <InteractiveState>() => {
     interactiveState: InteractiveState | null;
@@ -16,4 +16,9 @@ export declare const useInitMessage: <InteractiveState = {}, AuthoredState = {},
 export declare const useCustomMessages: (callback: ICustomMessageHandler, handles?: ICustomMessagesHandledMap | undefined) => void;
 export declare const useDecorateContent: (callback: ITextDecorationHandler) => void;
 export declare const useAutoSetHeight: () => void;
+export interface IUseReportItemOptions<InteractiveState, AuthoredState> {
+    metadata: IReportItemHandlerMetadata;
+    handler: IGetReportItemAnswerHandler<InteractiveState, AuthoredState>;
+}
+export declare const useReportItem: <InteractiveState, AuthoredState>({ metadata, handler }: IUseReportItemOptions<InteractiveState, AuthoredState>) => void;
 export {};

package/index-bundle.d.ts

@@ -123,13 +123,14 @@ interface IReportInitInteractive<InteractiveState = {}, AuthoredState = {}> {
     interactiveState: InteractiveState;
     themeInfo: IThemeInfo;
     attachments?: AttachmentInfoMap;
+    linkedInteractives: ILinkedInteractive[];
 }
 interface IReportItemInitInteractive<InteractiveState = {}, AuthoredState = {}> {
     version: 1;
     mode: "reportItem";
     hostFeatures: IHostFeatures;
     interactiveItemId: string;
-    view: "singleAnswer" | "multipleAnswer";
+    view: "singleAnswer" | "multipleAnswer" | "hidden";
     users: Record<string, {
         hasAnswer: boolean;
     }>;
@@ -360,11 +361,17 @@ interface ILinkedInteractiveStateResponse<LinkedInteractiveState> {
     listenerId: string;
     interactiveState: LinkedInteractiveState | undefined;
 }
+declare type ReportItemsType = "fullAnswer" | "compactAnswer";
 interface IGetReportItemAnswer<InteractiveState = {}, AuthoredState = {}> extends IBaseRequestResponse {
-    version: "2.0.0";
+    version: "2.1.0";
     platformUserId: string;
     interactiveState: InteractiveState;
     authoredState: AuthoredState;
+    /**
+     * When not provided, host should assume that itemsType is equal to "fullAnswer" (to maintain backward compatibility
+     * with version 2.0.0).
+     */
+    itemsType?: ReportItemsType;
 }
 interface IReportItemAnswerItemAttachment {
     type: "attachment";
@@ -383,13 +390,31 @@ interface IReportItemAnswerItemLinks {
     hideViewInline?: boolean;
     hideViewInNewTab?: boolean;
 }
-declare type IReportItemAnswerItem = IReportItemAnswerItemAttachment | IReportItemAnswerItemAnswerText | IReportItemAnswerItemHtml | IReportItemAnswerItemLinks;
+interface IReportItemAnswerItemScore {
+    type: "score";
+    score: number;
+    maxScore: number;
+}
+declare type IReportItemAnswerItem = IReportItemAnswerItemAttachment | IReportItemAnswerItemAnswerText | IReportItemAnswerItemHtml | IReportItemAnswerItemLinks | IReportItemAnswerItemScore;
 interface IReportItemAnswer extends IBaseRequestResponse {
-    version: "2.0.0";
+    version: "2.1.0";
     platformUserId: string;
     items: IReportItemAnswerItem[];
+    /**
+     * When not provided, host should assume that itemsType is equal to "fullAnswer" (to maintain backward compatibility
+     * with version 2.0.0).
+     */
+    itemsType: ReportItemsType;
 }
 declare type IGetReportItemAnswerHandler<InteractiveState = {}, AuthoredState = {}> = (message: IGetReportItemAnswer<InteractiveState, AuthoredState>) => void;
+interface IReportItemHandlerMetadata {
+    /**
+     * When compactAnswerReportItems is present and equal to true, report will try to get report items related to compact
+     * answer (small icons visible in the dashboard grid view). An example of compact answer report item is "score"
+     * used by ScoreBOT question.
+     */
+    compactAnswerReportItemsAvailable?: boolean;
+}
 /**
  * Interface that can be used by interactives to export and consume datasets. For example:
  * - Vortex interactive is exporting its dataset in the interactive state
@@ -548,11 +573,12 @@ declare const getGlobalInteractiveState: <GlobalInteractiveState>() => GlobalInt
  */
 declare const setGlobalInteractiveState: <GlobalInteractiveState>(newGlobalState: GlobalInteractiveState | null) => void;
 declare const addCustomMessageListener: (callback: ICustomMessageHandler, handles?: ICustomMessagesHandledMap | undefined) => void;
-declare const removeCustomMessageListener: () => void;
+declare const removeCustomMessageListener: () => boolean;
 declare const addDecorateContentListener: (callback: ITextDecorationHandler) => void;
 declare const removeDecorateContentListener: () => void;
 declare const addGetReportItemAnswerListener: <InteractiveState, AuthoredState>(callback: IGetReportItemAnswerHandler<InteractiveState, AuthoredState>) => void;
 declare const removeGetReportItemAnswerListener: () => void;
+declare const notifyReportItemClientReady: (metadata?: IReportItemHandlerMetadata | undefined) => void;
 declare const setSupportedFeatures: (features: ISupportedFeatures) => void;
 declare const setHeight: (height: number | string) => void;
 declare const postDecoratedContentEvent: (msg: IDecoratedContentEvent) => void;
@@ -615,6 +641,11 @@ declare const useInitMessage: <InteractiveState = {}, AuthoredState = {}, Global
 declare const useCustomMessages: (callback: ICustomMessageHandler, handles?: ICustomMessagesHandledMap | undefined) => void;
 declare const useDecorateContent: (callback: ITextDecorationHandler) => void;
 declare const useAutoSetHeight: () => void;
+interface IUseReportItemOptions<InteractiveState, AuthoredState> {
+    metadata: IReportItemHandlerMetadata;
+    handler: IGetReportItemAnswerHandler<InteractiveState, AuthoredState>;
+}
+declare const useReportItem: <InteractiveState, AuthoredState>({ metadata, handler }: IUseReportItemOptions<InteractiveState, AuthoredState>) => void;
 
 declare type ManagedStateEvent = "interactiveStateUpdated" | "globalInteractiveStateUpdated" | "authoredStateUpdated" | "initInteractive";
 declare class ManagedState {
@@ -639,10 +670,15 @@ declare class ManagedState {
 }
 
 declare const getClient: () => Client;
+/**
+ * This class is intended to provide basic helpers (like `post()` or `add/removeListener`), maintain client-specific
+ * state, and generally be as minimal as possible. Most of the client-specific helpers and logic can be implemented
+ * in api.ts or hooks.ts (or both so the client app has choice).
+ */
 declare class Client {
     phone: iframePhone.IFrameEndpoint;
     managedState: ManagedState;
-    private customMessagesHandled;
+    customMessagesHandled: ICustomMessagesHandledMap;
     private listeners;
     private requestId;
     private onUnload;
@@ -651,15 +687,9 @@ declare class Client {
     post(message: ClientMessage, content?: any): void;
     addListener(message: ServerMessage, callback: iframePhone.ListenerCallback, requestId?: number): boolean;
     removeListener(message: ServerMessage, requestId?: number, callback?: iframePhone.ListenerCallback): boolean;
-    addCustomMessageListener(callback: ICustomMessageHandler, handles?: ICustomMessagesHandledMap): void;
-    removeCustomMessageListener(): boolean;
-    addDecorateContentListener(callback: ITextDecorationHandler): void;
-    removeDecorateContentListener(): boolean;
-    addGetReportItemAnswerListener(callback: IGetReportItemAnswerHandler): void;
-    removeGetReportItemAnswerListener(): boolean;
     setSupportedFeatures: (request: ISupportedFeaturesRequest) => void;
     setOnUnload: (onUnload?: OnUnloadFunction<{}> | undefined) => void;
     private connect;
 }
 
-export { AttachmentInfoMap, ChoiceId, Client, ClientMessage, DeprecatedRuntimeClientMessage, DeprecatedRuntimeServerMessage, GetAttachmentUrlParams, GlobalIFrameSaverClientMessage, GlobalIFrameSaverServerMessage, IAddLinkedInteractiveStateListenerOptions, IAddLinkedInteractiveStateListenerRequest, IAttachmentInfo, IAttachmentUrlRequest, IAttachmentUrlResponse, IAuthInfo, IAuthoringClientMessage, IAuthoringCustomReportField, IAuthoringCustomReportFields, IAuthoringImageQuestionMetadata, IAuthoringInitInteractive, IAuthoringInteractiveMetadata, IAuthoringMetadata, IAuthoringMetadataBase, IAuthoringMultipleChoiceChoiceMetadata, IAuthoringMultipleChoiceMetadata, IAuthoringOpenResponseMetadata, IAuthoringServerMessage, IBaseShowModal, ICloseModal, IContextMember, IContextMembership, ICustomMessage, ICustomMessageHandler, ICustomMessageOptions, ICustomMessagesHandledMap, ICustomReportFieldsAuthoredState, ICustomReportFieldsAuthoredStateField, ICustomReportFieldsInteractiveState, IDataset, IDecoratedContentEvent, IGetAuthInfoRequest, IGetAuthInfoResponse, IGetFirebaseJwtRequest, IGetFirebaseJwtResponse, IGetInteractiveListOptions, IGetInteractiveListRequest, IGetInteractiveListResponse, IGetInteractiveSnapshotOptions, IGetInteractiveSnapshotRequest, IGetInteractiveSnapshotResponse, IGetInteractiveState, IGetLibraryInteractiveListOptions, IGetLibraryInteractiveListRequest, IGetLibraryInteractiveListResponse, IGetReportItemAnswer, IGetReportItemAnswerHandler, IHintRequest, IHostFeatureSupport, IHostFeatures, IHostModalSupport, IInitInteractive, IInteractiveListResponseItem, IInteractiveStateProps, IInteractiveStateWithDataset, IJwtClaims, IJwtResponse, ILibraryInteractiveListResponseItem, ILinkedInteractive, ILinkedInteractiveStateResponse, INavigationOptions, IPortalClaims, IRemoveLinkedInteractiveStateListenerRequest, IReportInitInteractive, IReportItemAnswer, IReportItemAnswerItem, IReportItemAnswerItemAnswerText, IReportItemAnswerItemAttachment, IReportItemAnswerItemHtml, IReportItemAnswerItemLinks, IReportItemClientMessage, IReportItemInitInteractive, IReportItemServerMessage, IRuntimeClientMessage, IRuntimeCustomReportValues, IRuntimeImageQuestionMetadata, IRuntimeInitInteractive, IRuntimeInteractiveMetadata, IRuntimeMetadata, IRuntimeMetadataBase, IRuntimeMultipleChoiceMetadata, IRuntimeOpenResponseMetadata, IRuntimeServerMessage, ISetLinkedInteractives, IShowAlert, IShowDialog, IShowLightbox, IShowModal, ISupportedFeatures, ISupportedFeaturesRequest, ITextDecorationHandler, ITextDecorationHandlerInfo, ITextDecorationInfo, IThemeInfo, IWriteAttachmentRequest, IframePhoneServerMessage, InitInteractiveMode, InteractiveItemId, LoggerClientMessage, ModalType, OnUnloadFunction, ReadAttachmentParams, ServerMessage, WriteAttachmentParams, addAuthoredStateListener, addCustomMessageListener, addDecorateContentListener, addGetReportItemAnswerListener, addGlobalInteractiveStateListener, addInteractiveStateListener, addLinkedInteractiveStateListener, closeModal, flushStateUpdates, getAttachmentUrl, getAuthInfo, getAuthoredState, getClient, getFirebaseJwt, getGlobalInteractiveState, getInitInteractiveMessage, getInteractiveList, getInteractiveSnapshot, getInteractiveState, getLibraryInteractiveList, getMode, inIframe, log, postDecoratedContentEvent, readAttachment, removeAuthoredStateListener, removeCustomMessageListener, removeDecorateContentListener, removeGetReportItemAnswerListener, removeGlobalInteractiveStateListener, removeInteractiveStateListener, removeLinkedInteractiveStateListener, sendReportItemAnswer, setAuthoredState, setGlobalInteractiveState, setHeight, setHint, setInteractiveState, setInteractiveStateTimeout, setLinkedInteractives, setNavigation, setOnUnload, setSupportedFeatures, showModal, useAuthoredState, useAutoSetHeight, useCustomMessages, useDecorateContent, useGlobalInteractiveState, useInitMessage, useInteractiveState, writeAttachment };
+export { AttachmentInfoMap, ChoiceId, Client, ClientMessage, DeprecatedRuntimeClientMessage, DeprecatedRuntimeServerMessage, GetAttachmentUrlParams, GlobalIFrameSaverClientMessage, GlobalIFrameSaverServerMessage, IAddLinkedInteractiveStateListenerOptions, IAddLinkedInteractiveStateListenerRequest, IAttachmentInfo, IAttachmentUrlRequest, IAttachmentUrlResponse, IAuthInfo, IAuthoringClientMessage, IAuthoringCustomReportField, IAuthoringCustomReportFields, IAuthoringImageQuestionMetadata, IAuthoringInitInteractive, IAuthoringInteractiveMetadata, IAuthoringMetadata, IAuthoringMetadataBase, IAuthoringMultipleChoiceChoiceMetadata, IAuthoringMultipleChoiceMetadata, IAuthoringOpenResponseMetadata, IAuthoringServerMessage, IBaseShowModal, ICloseModal, IContextMember, IContextMembership, ICustomMessage, ICustomMessageHandler, ICustomMessageOptions, ICustomMessagesHandledMap, ICustomReportFieldsAuthoredState, ICustomReportFieldsAuthoredStateField, ICustomReportFieldsInteractiveState, IDataset, IDecoratedContentEvent, IGetAuthInfoRequest, IGetAuthInfoResponse, IGetFirebaseJwtRequest, IGetFirebaseJwtResponse, IGetInteractiveListOptions, IGetInteractiveListRequest, IGetInteractiveListResponse, IGetInteractiveSnapshotOptions, IGetInteractiveSnapshotRequest, IGetInteractiveSnapshotResponse, IGetInteractiveState, IGetLibraryInteractiveListOptions, IGetLibraryInteractiveListRequest, IGetLibraryInteractiveListResponse, IGetReportItemAnswer, IGetReportItemAnswerHandler, IHintRequest, IHostFeatureSupport, IHostFeatures, IHostModalSupport, IInitInteractive, IInteractiveListResponseItem, IInteractiveStateProps, IInteractiveStateWithDataset, IJwtClaims, IJwtResponse, ILibraryInteractiveListResponseItem, ILinkedInteractive, ILinkedInteractiveStateResponse, INavigationOptions, IPortalClaims, IRemoveLinkedInteractiveStateListenerRequest, IReportInitInteractive, IReportItemAnswer, IReportItemAnswerItem, IReportItemAnswerItemAnswerText, IReportItemAnswerItemAttachment, IReportItemAnswerItemHtml, IReportItemAnswerItemLinks, IReportItemAnswerItemScore, IReportItemClientMessage, IReportItemHandlerMetadata, IReportItemInitInteractive, IReportItemServerMessage, IRuntimeClientMessage, IRuntimeCustomReportValues, IRuntimeImageQuestionMetadata, IRuntimeInitInteractive, IRuntimeInteractiveMetadata, IRuntimeMetadata, IRuntimeMetadataBase, IRuntimeMultipleChoiceMetadata, IRuntimeOpenResponseMetadata, IRuntimeServerMessage, ISetLinkedInteractives, IShowAlert, IShowDialog, IShowLightbox, IShowModal, ISupportedFeatures, ISupportedFeaturesRequest, ITextDecorationHandler, ITextDecorationHandlerInfo, ITextDecorationInfo, IThemeInfo, IUseReportItemOptions, IWriteAttachmentRequest, IframePhoneServerMessage, InitInteractiveMode, InteractiveItemId, LoggerClientMessage, ModalType, OnUnloadFunction, ReadAttachmentParams, ReportItemsType, ServerMessage, WriteAttachmentParams, addAuthoredStateListener, addCustomMessageListener, addDecorateContentListener, addGetReportItemAnswerListener, addGlobalInteractiveStateListener, addInteractiveStateListener, addLinkedInteractiveStateListener, closeModal, flushStateUpdates, getAttachmentUrl, getAuthInfo, getAuthoredState, getClient, getFirebaseJwt, getGlobalInteractiveState, getInitInteractiveMessage, getInteractiveList, getInteractiveSnapshot, getInteractiveState, getLibraryInteractiveList, getMode, inIframe, log, notifyReportItemClientReady, postDecoratedContentEvent, readAttachment, removeAuthoredStateListener, removeCustomMessageListener, removeDecorateContentListener, removeGetReportItemAnswerListener, removeGlobalInteractiveStateListener, removeInteractiveStateListener, removeLinkedInteractiveStateListener, sendReportItemAnswer, setAuthoredState, setGlobalInteractiveState, setHeight, setHint, setInteractiveState, setInteractiveStateTimeout, setLinkedInteractives, setNavigation, setOnUnload, setSupportedFeatures, showModal, useAuthoredState, useAutoSetHeight, useCustomMessages, useDecorateContent, useGlobalInteractiveState, useInitMessage, useInteractiveState, useReportItem, writeAttachment };