pika-shared 1.4.6 → 1.4.8

package/dist/types/chatbot/webcomp-types.d.mts

@@ -1,5 +1,5 @@
 import { UploadStatus } from '../upload-types.mjs';
-import { ShowToastFn, ChatUser, RecordOrUndef, UserAwsCredentials, WidgetRenderingContextType, ShareSessionState, UserPrefs, ChatAppMode, IUserWidgetDataStoreState, CustomDataUiRepresentation, ChatAppOverridableFeatures, TagDefinition, TagDefinitionWidget, ChatSession, UserDataOverrideSettings, ChatMessageForRendering, ChatApp, ChatAppActionMenu, ChatAppAction, WidgetInstance, WidgetMetadata, SpotlightWidgetDefinition, InvokeAgentAsComponentOptions, WidgetAction } from './chatbot-types.mjs';
+import { ShowToastFn, ChatUser, RecordOrUndef, UserAwsCredentials, WidgetRenderingContextType, ShareSessionState, UserPrefs, ChatAppMode, IUserWidgetDataStoreState, CustomDataUiRepresentation, ChatAppOverridableFeatures, TagDefinition, TagDefinitionWidget, ChatSession, UserDataOverrideSettings, ChatMessageForRendering, ChatApp, ChatAppActionMenu, ChatAppAction, WidgetInstance, WidgetSizing, InvokeAgentAsComponentOptions } from './chatbot-types.mjs';
 import '@aws-sdk/client-bedrock-agent-runtime';
 import '@aws-sdk/client-bedrock-agentcore';
 
@@ -177,7 +177,11 @@ interface IChatAppState {
     readonly customDataForChatApp: Record<string, unknown> | undefined;
     readonly customTitleBarActions: (ChatAppActionMenu | ChatAppAction)[];
     readonly widgetInstances: Map<string, WidgetInstance>;
-    readonly user: ChatUser;
+    /**
+     * Current user information
+     * @since 0.11.0
+     */
+    readonly user: ChatUser<RecordOrUndef>;
     setCurrentSessionById(sessionId: string): void;
     removeFile(s3Key: string): void;
     startNewChatSession(): void;
@@ -188,12 +192,22 @@ interface IChatAppState {
     getMessageByMessageId(messageId: string): ChatMessageForRendering | undefined;
     uploadFiles(files: File[]): Promise<void>;
     initializeData(): Promise<void>;
+    /**
+     * Render a tag in a specific context
+     * @param metadata - Optional metadata for the widget (title, actions, icon)
+     * @since 0.11.0 - Added metadata parameter
+     */
     renderTag(tagId: string, context: 'spotlight' | 'inline' | 'dialog' | 'canvas' | 'static', data?: Record<string, any>, metadata?: WidgetMetadata): Promise<void>;
     closeCanvas(): void;
     closeDialog(): void;
     setOrUpdateCustomTitleBarAction(action: ChatAppActionMenu | ChatAppAction): void;
     removeCustomTitleBarAction(actionId: string): void;
     getWidgetInstance(instanceId: string): WidgetInstance | undefined;
+    /**
+     * Get the full context for a widget instance
+     * @since 0.11.0
+     */
+    getWidgetContext(instanceId: string): PikaWCContext | undefined;
     /**
      * Update context for a widget. Call this when your widget's context has changed.
      *
@@ -272,6 +286,7 @@ interface IChatAppState {
      * @param dataKey - The key to store data under (default: 'data')
      * @param metadata - Optional widget metadata (title, actions, icon, etc.)
      * @returns The instance ID (UUID)
+     * @since 0.11.0 - Added metadata parameter
      *
      * @example
      * ```typescript
@@ -446,14 +461,52 @@ interface IUploadInstance {
  * Called after the element is created but before it's added to the DOM.
  */
 interface OnReadyCallback {
-    (params: {
-        /** The web component element that was created */
-        element: HTMLElement;
-        /** The unique instance ID assigned to this component */
-        instanceId: string;
-        /** The full Pika context with instanceId */
-        context: PikaWCContext;
-    }): void;
+    (params: WidgetCallbackContext): void;
+}
+/**
+ * Action button that appears in the widget's chrome (title bar, toolbar, etc.)
+ *
+ * @example
+ * ```js
+ * const action: WidgetAction = {
+ *   id: 'refresh',
+ *   title: 'Refresh data',
+ *   iconSvg: '<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20">...</svg>',
+ *   callback: async () => { await fetchData(); }
+ * };
+ * ```
+ *
+ * @since 0.11.0 - Moved from chatbot-types to webcomp-types
+ */
+interface WidgetAction {
+    /** Unique identifier for this action */
+    id: string;
+    /** Tooltip/label for the action (also button text in dialog context) */
+    title: string;
+    /** SVG markup string for the icon (e.g., from extractIconSvg() helper) */
+    iconSvg: string;
+    /** Whether action is currently disabled */
+    disabled?: boolean;
+    /** If true, renders as default/prominent button (used in dialog context) */
+    primary?: boolean;
+    /**
+     * Handler when clicked
+     * @since 0.11.0 - Callback now receives WidgetCallbackContext parameter
+     */
+    callback: (context: WidgetCallbackContext) => void | Promise<void>;
+}
+/**
+ * The context object that is passed to the onReady callback and in action callbacks functions.
+ *
+ * @since 0.11.0
+ */
+interface WidgetCallbackContext {
+    /** The web component element that was created */
+    element: HTMLElement;
+    /** The unique instance ID assigned to this component */
+    instanceId: string;
+    /** The full Pika context with instanceId */
+    context: PikaWCContext;
 }
 /**
  * Structure for data passed to web components.
@@ -513,5 +566,92 @@ interface PikaWCContextRequestDetail {
 interface PikaWCContextRequestEvent extends CustomEvent<PikaWCContextRequestDetail> {
     detail: PikaWCContextRequestDetail;
 }
+/**
+ * Metadata that widgets register with the parent app
+ *
+ * @example
+ * ```js
+ * const metadata: WidgetMetadata = {
+ *   title: 'My Widget',
+ *   iconSvg: '<svg>...</svg>',
+ *   iconColor: '#001F3F',
+ *   actions: [
+ *     { id: 'refresh', title: 'Refresh', iconSvg: '<svg>...</svg>', callback: () => refresh() }
+ *   ]
+ * };
+ * ```
+ *
+ * @since 0.11.0 - Moved from chatbot-types to webcomp-types
+ */
+interface WidgetMetadata {
+    /** Widget title shown in chrome */
+    title: string;
+    /**
+     * Optional Lucide icon name (will be fetched automatically and set as iconSvg).
+     *
+     * The name will be snake cased as in `arrow-big-down` and not `arrowBigDown`
+     */
+    lucideIconName?: string;
+    /** Optional icon SVG markup for the widget title */
+    iconSvg?: string;
+    /** Optional color for the widget icon (hex, rgb, or CSS color name) */
+    iconColor?: string;
+    /** Optional action buttons */
+    actions?: WidgetAction[];
+    /** Optional loading status */
+    loadingStatus?: {
+        loading: boolean;
+        loadingMsg?: string;
+    };
+}
+/**
+ * Internal state tracked for each widget instance
+ *
+ * @since 0.11.0 - Moved from chatbot-types to webcomp-types
+ */
+interface WidgetMetadataState extends WidgetMetadata {
+    /** Unique instance ID for this widget */
+    instanceId: string;
+    /** Widget scope (e.g., 'weather', 'pika') */
+    scope: string;
+    /** Widget tag (e.g., 'favorite-cities') */
+    tag: string;
+    /** Rendering context (spotlight, canvas, dialog, inline) */
+    renderingContext: WidgetRenderingContextType;
+}
+/**
+ * This is used when manually registering a custom element as a spotlight widget by a component in the client.
+ *
+ * @since 0.11.0 - Moved from chatbot-types to webcomp-types
+ */
+interface SpotlightWidgetDefinition {
+    /** @see TagDefinition.tag */
+    tag: string;
+    /** @see TagDefinition.scope */
+    scope: string;
+    /** @see TagDefinitionWidgetWebComponent.customElementName */
+    customElementName?: string;
+    /** @see TagDefinition.tagTitle */
+    tagTitle: string;
+    /** @see TagDefinitionWidgetWebComponent.sizing */
+    sizing?: WidgetSizing;
+    /** @see TagDefinition.componentAgentInstructionsMd */
+    componentAgentInstructionsMd?: Record<string, string>;
+    /**
+     * If true and there isn't an instance of this widget already created as a spotlight widget, then a new instance will be created.
+     */
+    autoCreateInstance?: boolean;
+    /** The display order of the widget in the spotlight. If not provided, is put first. */
+    displayOrder?: number;
+    /** Defaults to true.  If true, then only one instance of this widget can be created. */
+    singleton?: boolean;
+    /** If false, widget won't appear in unpinned menu. Default: true. Use false for base widgets that only create instances */
+    showInUnpinnedMenu?: boolean;
+    /**
+     * Optional metadata (title, actions, icon) to apply to the widget when rendered
+     * @since 0.11.0
+     */
+    metadata?: WidgetMetadata;
+}
 
-export type { DataForWidget, IAppState, IChatAppState, IIdentityState, IUploadInstance, IUserPrefsState, IWidgetMetadataAPI, OnReadyCallback, PikaWCContext, PikaWCContextRequestCallbackFn, PikaWCContextRequestDetail, PikaWCContextRequestEvent, PikaWCContextWithoutInstanceId, SidebarState, Snippet };
+export type { DataForWidget, IAppState, IChatAppState, IIdentityState, IUploadInstance, IUserPrefsState, IWidgetMetadataAPI, OnReadyCallback, PikaWCContext, PikaWCContextRequestCallbackFn, PikaWCContextRequestDetail, PikaWCContextRequestEvent, PikaWCContextWithoutInstanceId, SidebarState, Snippet, SpotlightWidgetDefinition, WidgetAction, WidgetCallbackContext, WidgetMetadata, WidgetMetadataState };

package/dist/types/chatbot/webcomp-types.d.ts

@@ -1,5 +1,5 @@
 import { UploadStatus } from '../upload-types.js';
-import { ShowToastFn, ChatUser, RecordOrUndef, UserAwsCredentials, WidgetRenderingContextType, ShareSessionState, UserPrefs, ChatAppMode, IUserWidgetDataStoreState, CustomDataUiRepresentation, ChatAppOverridableFeatures, TagDefinition, TagDefinitionWidget, ChatSession, UserDataOverrideSettings, ChatMessageForRendering, ChatApp, ChatAppActionMenu, ChatAppAction, WidgetInstance, WidgetMetadata, SpotlightWidgetDefinition, InvokeAgentAsComponentOptions, WidgetAction } from './chatbot-types.js';
+import { ShowToastFn, ChatUser, RecordOrUndef, UserAwsCredentials, WidgetRenderingContextType, ShareSessionState, UserPrefs, ChatAppMode, IUserWidgetDataStoreState, CustomDataUiRepresentation, ChatAppOverridableFeatures, TagDefinition, TagDefinitionWidget, ChatSession, UserDataOverrideSettings, ChatMessageForRendering, ChatApp, ChatAppActionMenu, ChatAppAction, WidgetInstance, WidgetSizing, InvokeAgentAsComponentOptions } from './chatbot-types.js';
 import '@aws-sdk/client-bedrock-agent-runtime';
 import '@aws-sdk/client-bedrock-agentcore';
 
@@ -177,7 +177,11 @@ interface IChatAppState {
     readonly customDataForChatApp: Record<string, unknown> | undefined;
     readonly customTitleBarActions: (ChatAppActionMenu | ChatAppAction)[];
     readonly widgetInstances: Map<string, WidgetInstance>;
-    readonly user: ChatUser;
+    /**
+     * Current user information
+     * @since 0.11.0
+     */
+    readonly user: ChatUser<RecordOrUndef>;
     setCurrentSessionById(sessionId: string): void;
     removeFile(s3Key: string): void;
     startNewChatSession(): void;
@@ -188,12 +192,22 @@ interface IChatAppState {
     getMessageByMessageId(messageId: string): ChatMessageForRendering | undefined;
     uploadFiles(files: File[]): Promise<void>;
     initializeData(): Promise<void>;
+    /**
+     * Render a tag in a specific context
+     * @param metadata - Optional metadata for the widget (title, actions, icon)
+     * @since 0.11.0 - Added metadata parameter
+     */
     renderTag(tagId: string, context: 'spotlight' | 'inline' | 'dialog' | 'canvas' | 'static', data?: Record<string, any>, metadata?: WidgetMetadata): Promise<void>;
     closeCanvas(): void;
     closeDialog(): void;
     setOrUpdateCustomTitleBarAction(action: ChatAppActionMenu | ChatAppAction): void;
     removeCustomTitleBarAction(actionId: string): void;
     getWidgetInstance(instanceId: string): WidgetInstance | undefined;
+    /**
+     * Get the full context for a widget instance
+     * @since 0.11.0
+     */
+    getWidgetContext(instanceId: string): PikaWCContext | undefined;
     /**
      * Update context for a widget. Call this when your widget's context has changed.
      *
@@ -272,6 +286,7 @@ interface IChatAppState {
      * @param dataKey - The key to store data under (default: 'data')
      * @param metadata - Optional widget metadata (title, actions, icon, etc.)
      * @returns The instance ID (UUID)
+     * @since 0.11.0 - Added metadata parameter
      *
      * @example
      * ```typescript
@@ -446,14 +461,52 @@ interface IUploadInstance {
  * Called after the element is created but before it's added to the DOM.
  */
 interface OnReadyCallback {
-    (params: {
-        /** The web component element that was created */
-        element: HTMLElement;
-        /** The unique instance ID assigned to this component */
-        instanceId: string;
-        /** The full Pika context with instanceId */
-        context: PikaWCContext;
-    }): void;
+    (params: WidgetCallbackContext): void;
+}
+/**
+ * Action button that appears in the widget's chrome (title bar, toolbar, etc.)
+ *
+ * @example
+ * ```js
+ * const action: WidgetAction = {
+ *   id: 'refresh',
+ *   title: 'Refresh data',
+ *   iconSvg: '<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20">...</svg>',
+ *   callback: async () => { await fetchData(); }
+ * };
+ * ```
+ *
+ * @since 0.11.0 - Moved from chatbot-types to webcomp-types
+ */
+interface WidgetAction {
+    /** Unique identifier for this action */
+    id: string;
+    /** Tooltip/label for the action (also button text in dialog context) */
+    title: string;
+    /** SVG markup string for the icon (e.g., from extractIconSvg() helper) */
+    iconSvg: string;
+    /** Whether action is currently disabled */
+    disabled?: boolean;
+    /** If true, renders as default/prominent button (used in dialog context) */
+    primary?: boolean;
+    /**
+     * Handler when clicked
+     * @since 0.11.0 - Callback now receives WidgetCallbackContext parameter
+     */
+    callback: (context: WidgetCallbackContext) => void | Promise<void>;
+}
+/**
+ * The context object that is passed to the onReady callback and in action callbacks functions.
+ *
+ * @since 0.11.0
+ */
+interface WidgetCallbackContext {
+    /** The web component element that was created */
+    element: HTMLElement;
+    /** The unique instance ID assigned to this component */
+    instanceId: string;
+    /** The full Pika context with instanceId */
+    context: PikaWCContext;
 }
 /**
  * Structure for data passed to web components.
@@ -513,5 +566,92 @@ interface PikaWCContextRequestDetail {
 interface PikaWCContextRequestEvent extends CustomEvent<PikaWCContextRequestDetail> {
     detail: PikaWCContextRequestDetail;
 }
+/**
+ * Metadata that widgets register with the parent app
+ *
+ * @example
+ * ```js
+ * const metadata: WidgetMetadata = {
+ *   title: 'My Widget',
+ *   iconSvg: '<svg>...</svg>',
+ *   iconColor: '#001F3F',
+ *   actions: [
+ *     { id: 'refresh', title: 'Refresh', iconSvg: '<svg>...</svg>', callback: () => refresh() }
+ *   ]
+ * };
+ * ```
+ *
+ * @since 0.11.0 - Moved from chatbot-types to webcomp-types
+ */
+interface WidgetMetadata {
+    /** Widget title shown in chrome */
+    title: string;
+    /**
+     * Optional Lucide icon name (will be fetched automatically and set as iconSvg).
+     *
+     * The name will be snake cased as in `arrow-big-down` and not `arrowBigDown`
+     */
+    lucideIconName?: string;
+    /** Optional icon SVG markup for the widget title */
+    iconSvg?: string;
+    /** Optional color for the widget icon (hex, rgb, or CSS color name) */
+    iconColor?: string;
+    /** Optional action buttons */
+    actions?: WidgetAction[];
+    /** Optional loading status */
+    loadingStatus?: {
+        loading: boolean;
+        loadingMsg?: string;
+    };
+}
+/**
+ * Internal state tracked for each widget instance
+ *
+ * @since 0.11.0 - Moved from chatbot-types to webcomp-types
+ */
+interface WidgetMetadataState extends WidgetMetadata {
+    /** Unique instance ID for this widget */
+    instanceId: string;
+    /** Widget scope (e.g., 'weather', 'pika') */
+    scope: string;
+    /** Widget tag (e.g., 'favorite-cities') */
+    tag: string;
+    /** Rendering context (spotlight, canvas, dialog, inline) */
+    renderingContext: WidgetRenderingContextType;
+}
+/**
+ * This is used when manually registering a custom element as a spotlight widget by a component in the client.
+ *
+ * @since 0.11.0 - Moved from chatbot-types to webcomp-types
+ */
+interface SpotlightWidgetDefinition {
+    /** @see TagDefinition.tag */
+    tag: string;
+    /** @see TagDefinition.scope */
+    scope: string;
+    /** @see TagDefinitionWidgetWebComponent.customElementName */
+    customElementName?: string;
+    /** @see TagDefinition.tagTitle */
+    tagTitle: string;
+    /** @see TagDefinitionWidgetWebComponent.sizing */
+    sizing?: WidgetSizing;
+    /** @see TagDefinition.componentAgentInstructionsMd */
+    componentAgentInstructionsMd?: Record<string, string>;
+    /**
+     * If true and there isn't an instance of this widget already created as a spotlight widget, then a new instance will be created.
+     */
+    autoCreateInstance?: boolean;
+    /** The display order of the widget in the spotlight. If not provided, is put first. */
+    displayOrder?: number;
+    /** Defaults to true.  If true, then only one instance of this widget can be created. */
+    singleton?: boolean;
+    /** If false, widget won't appear in unpinned menu. Default: true. Use false for base widgets that only create instances */
+    showInUnpinnedMenu?: boolean;
+    /**
+     * Optional metadata (title, actions, icon) to apply to the widget when rendered
+     * @since 0.11.0
+     */
+    metadata?: WidgetMetadata;
+}
 
-export type { DataForWidget, IAppState, IChatAppState, IIdentityState, IUploadInstance, IUserPrefsState, IWidgetMetadataAPI, OnReadyCallback, PikaWCContext, PikaWCContextRequestCallbackFn, PikaWCContextRequestDetail, PikaWCContextRequestEvent, PikaWCContextWithoutInstanceId, SidebarState, Snippet };
+export type { DataForWidget, IAppState, IChatAppState, IIdentityState, IUploadInstance, IUserPrefsState, IWidgetMetadataAPI, OnReadyCallback, PikaWCContext, PikaWCContextRequestCallbackFn, PikaWCContextRequestDetail, PikaWCContextRequestEvent, PikaWCContextWithoutInstanceId, SidebarState, Snippet, SpotlightWidgetDefinition, WidgetAction, WidgetCallbackContext, WidgetMetadata, WidgetMetadataState };