@optimizely-opal/opal-tools-sdk 0.1.8-dev → 0.1.9-dev

package/dist/proteus.d.ts

@@ -3,7 +3,7 @@
  * DO NOT MODIFY - This file is auto-generated from proteus-document-spec.json
  * Run 'npm run generate:proteus' to regenerate
  */
-export type OpalProteusDocumentSpecification = ProteusAction | ProteusAtomicCondition | ProteusCancelAction | ProteusCondition | ProteusDocument | ProteusElement | ProteusEventHandler | ProteusField | ProteusGroup | ProteusHeading | ProteusImage | ProteusInput | ProteusLink | ProteusMap | ProteusNode | ProteusRange | ProteusSelect | ProteusSelectContent | ProteusSelectTrigger | ProteusSeparator | ProteusShow | ProteusText | ProteusTextarea | ProteusValue;
+export type OpalProteusDocumentSpecification = ProteusAction | ProteusAtomicCondition | ProteusBadge | ProteusCancelAction | ProteusChart | ProteusCondition | ProteusDataTable | ProteusDocument | ProteusElement | ProteusEventHandler | ProteusField | ProteusGroup | ProteusHeading | ProteusImage | ProteusInput | ProteusLink | ProteusMap | ProteusNode | ProteusRange | ProteusSelect | ProteusSelectContent | ProteusSelectTrigger | ProteusSeparator | ProteusShow | ProteusText | ProteusTextarea | ProteusValue;
 export interface ProteusAction {
     $type: "Action";
     alignItems?: SprinklePropAlignItems;
@@ -157,6 +157,71 @@ export type ProteusAtomicCondition = {
      */
     "!!": boolean | null | number | ProteusValue | string;
 };
+export interface ProteusBadge {
+    $type: "Badge";
+    alignItems?: SprinklePropAlignItems;
+    alignSelf?: SprinklePropAlignSelf;
+    animation?: SprinklePropAnimation;
+    backgroundImage?: SprinklePropBackgroundImage;
+    bg?: SprinklePropBg;
+    border?: SprinklePropBorder;
+    borderB?: SprinklePropBorderB;
+    borderColor?: SprinklePropBorderColor;
+    borderL?: SprinklePropBorderL;
+    borderR?: SprinklePropBorderR;
+    borderT?: SprinklePropBorderT;
+    children?: ProteusNode;
+    color?: SprinklePropColor;
+    cursor?: SprinklePropCursor;
+    display?: SprinklePropDisplay;
+    flex?: SprinklePropFlex;
+    flexDirection?: SprinklePropFlexDirection;
+    flexWrap?: SprinklePropFlexWrap;
+    fontFamily?: SprinklePropFontFamily;
+    fontSize?: SprinklePropFontSize;
+    fontWeight?: SprinklePropFontWeight;
+    gap?: SprinklePropGap;
+    gridColumn?: SprinklePropGridColumn;
+    gridTemplateColumns?: SprinklePropGridTemplateColumns;
+    h?: SprinklePropH;
+    /**
+     * Control the appearance by selecting between the different badge types.
+     */
+    intent?: "danger" | "information" | "neutral" | "primary" | "success" | "warning";
+    justifyContent?: SprinklePropJustifyContent;
+    justifyItems?: SprinklePropJustifyItems;
+    m?: SprinklePropM;
+    maxH?: SprinklePropMaxH;
+    maxW?: SprinklePropMaxW;
+    mb?: SprinklePropMb;
+    ml?: SprinklePropMl;
+    mr?: SprinklePropMr;
+    mt?: SprinklePropMt;
+    mx?: SprinklePropMx;
+    my?: SprinklePropMy;
+    objectFit?: SprinklePropObjectFit;
+    overflow?: SprinklePropOverflow;
+    overflowX?: SprinklePropOverflowX;
+    overflowY?: SprinklePropOverflowY;
+    p?: SprinklePropP;
+    pb?: SprinklePropPb;
+    pl?: SprinklePropPl;
+    placeItems?: SprinklePropPlaceItems;
+    pointerEvents?: SprinklePropPointerEvents;
+    pr?: SprinklePropPr;
+    pt?: SprinklePropPt;
+    px?: SprinklePropPx;
+    py?: SprinklePropPy;
+    rounded?: SprinklePropRounded;
+    shadow?: SprinklePropShadow;
+    size?: SprinklePropSize;
+    textAlign?: SprinklePropTextAlign;
+    textTransform?: SprinklePropTextTransform;
+    transition?: SprinklePropTransition;
+    w?: SprinklePropW;
+    whiteSpace?: SprinklePropWhiteSpace;
+    z?: SprinklePropZ;
+}
 export interface ProteusCancelAction {
     $type: "CancelAction";
     alignItems?: SprinklePropAlignItems;
@@ -221,6 +286,44 @@ export interface ProteusCancelAction {
     whiteSpace?: SprinklePropWhiteSpace;
     z?: SprinklePropZ;
 }
+export interface ProteusChart {
+    $type: "Chart";
+    /**
+     * Chart data records, either inline or a ProteusValue reference
+     */
+    data?: ProteusValue | {
+        [k: string]: undefined | unknown;
+    }[];
+    /**
+     * Data series configuration
+     */
+    series?: {
+        /**
+         * Series color
+         */
+        color?: string;
+        /**
+         * Key in data records for this series
+         */
+        dataKey: string;
+        /**
+         * Key in data records for pre-formatted labels displayed above bars
+         */
+        labelKey?: string;
+        /**
+         * Display name for legend
+         */
+        name?: string;
+    }[];
+    /**
+     * Chart type
+     */
+    type?: "bar";
+    /**
+     * Key in data records for x-axis labels
+     */
+    xAxisKey?: string;
+}
 /**
  * Condition for Show component. Can be a comparison operator, logical AND, or logical OR. Supports nesting.
  */
@@ -249,14 +352,33 @@ export type ProteusCondition = ProteusAtomicCondition | {
         })[]
     ];
 };
+export interface ProteusDataTable {
+    $type: "DataTable";
+    /**
+     * Column definitions
+     */
+    columns?: {
+        /**
+         * Key in data objects
+         */
+        accessorKey: string;
+        /**
+         * Column header text
+         */
+        header: string;
+    }[];
+    data?: ProteusValue | {
+        [k: string]: undefined | unknown;
+    }[];
+}
 export interface ProteusDocument {
     $type: "Document";
     /**
      * Actions available for this document
      */
-    actions?: ProteusNode;
+    actions?: (boolean | null | number | ProteusElement | string)[] | boolean | null | number | ProteusElement | string;
     /**
-     * A visual representation of the application
+     * URL or data URI for the application icon (e.g., 'https://example.com/icon.png' or 'data:image/svg+xml,...'). Rendered as an <img> element.
      */
     appIcon?: string;
     /**
@@ -267,20 +389,23 @@ export interface ProteusDocument {
      * If true, hides chat prompt and forces user interaction with document. User can press ESC or close to abandon.
      */
     blocking?: boolean;
-    body: ProteusNode;
     /**
-     * A brief description or tagline that provides additional context about the Proteus document's purpose.
+     * A Proteus node can be a string, number, boolean, null, a single element, or an array of these types (similar to ReactNode)
+     */
+    body: (boolean | null | number | ProteusElement | string)[] | boolean | null | number | ProteusElement | string;
+    /**
+     * A Proteus node can be a string, number, boolean, null, a single element, or an array of these types (similar to ReactNode)
      */
-    subtitle?: string;
+    subtitle?: (boolean | null | number | ProteusElement | string)[] | boolean | null | number | ProteusElement | string;
     /**
-     * A concise heading that encapsulates the essence of the Proteus document's content or intended action.
+     * A Proteus node can be a string, number, boolean, null, a single element, or an array of these types (similar to ReactNode)
      */
-    title: string;
+    title: (boolean | null | number | ProteusElement | string)[] | boolean | null | number | ProteusElement | string;
 }
 /**
  * A single Proteus UI component element identified by its $type discriminator
  */
-export type ProteusElement = ProteusAction | ProteusCancelAction | ProteusField | ProteusGroup | ProteusHeading | ProteusImage | ProteusInput | ProteusLink | ProteusMap | ProteusRange | ProteusSelect | ProteusSelectContent | ProteusSelectTrigger | ProteusSeparator | ProteusShow | ProteusText | ProteusTextarea | ProteusValue;
+export type ProteusElement = ProteusAction | ProteusBadge | ProteusCancelAction | ProteusChart | ProteusDataTable | ProteusField | ProteusGroup | ProteusHeading | ProteusImage | ProteusInput | ProteusLink | ProteusMap | ProteusRange | ProteusSelect | ProteusSelectContent | ProteusSelectTrigger | ProteusSeparator | ProteusShow | ProteusText | ProteusTextarea | ProteusValue;
 /**
  * Handler for user interactions - either a server-side tool call or client-side message
  */
@@ -520,7 +645,7 @@ export interface ProteusImage {
     /**
      * Alternative text for the image
      */
-    alt?: string;
+    alt?: ProteusValue | string;
     animation?: SprinklePropAnimation;
     backgroundImage?: SprinklePropBackgroundImage;
     bg?: SprinklePropBg;
@@ -573,7 +698,7 @@ export interface ProteusImage {
     /**
      * The image source URL
      */
-    src?: string;
+    src?: ProteusValue | string;
     textAlign?: SprinklePropTextAlign;
     textTransform?: SprinklePropTextTransform;
     transition?: SprinklePropTransition;
@@ -732,13 +857,13 @@ export interface ProteusLink {
 export interface ProteusMap {
     $type: "Map";
     /**
-     * Template object to render for each item in the array. Value paths are relative to current item.
+     * Template object to render for each item in the array. Value paths inside this template are relative to the current item (e.g., path='title' resolves to each item's 'title' field). Use a leading '/' to reference top-level data (e.g., path='/title' resolves to the root data's 'title').
      */
     children?: {
         [k: string]: undefined | unknown;
     };
     /**
-     * JSON pointer path to array (e.g., '/questions')
+     * JSON pointer path to the source array in the data (e.g., '/results')
      */
     path: string;
 }
@@ -1070,6 +1195,10 @@ export interface ProteusText {
     h?: SprinklePropH;
     justifyContent?: SprinklePropJustifyContent;
     justifyItems?: SprinklePropJustifyItems;
+    /**
+     * Truncate the text at specific number of lines.
+     */
+    lineClamp?: "1" | "2" | "3" | "4";
     m?: SprinklePropM;
     maxH?: SprinklePropMaxH;
     maxW?: SprinklePropMaxW;
@@ -1098,6 +1227,10 @@ export interface ProteusText {
     textAlign?: SprinklePropTextAlign;
     textTransform?: SprinklePropTextTransform;
     transition?: SprinklePropTransition;
+    /**
+     * Whether to truncate the text and add an ellipsis at the end.
+     */
+    truncate?: boolean;
     w?: SprinklePropW;
     whiteSpace?: SprinklePropWhiteSpace;
     z?: SprinklePropZ;
@@ -1184,7 +1317,7 @@ export interface ProteusTextarea {
 export interface ProteusValue {
     $type: "Value";
     /**
-     * JSON pointer path to value (e.g., '/question', '/options/0/label')
+     * Path to a value in the data. Absolute paths start with '/' and resolve from the root (e.g., '/title', '/options/0/label'). Inside a Map template, paths without a leading '/' are relative to the current item (e.g., 'title' resolves to each item's 'title' field).
      */
     path: string;
 }
@@ -1429,7 +1562,10 @@ export type SprinklePropZ = "0" | "10" | "20" | "30" | "auto" | "popover" | "toa
  */
 export declare const UI: {
     Action: (props: Omit<ProteusAction, "$type">) => ProteusAction;
+    Badge: (props: Omit<ProteusBadge, "$type">) => ProteusBadge;
     CancelAction: (props: Omit<ProteusCancelAction, "$type">) => ProteusCancelAction;
+    Chart: (props: Omit<ProteusChart, "$type">) => ProteusChart;
+    DataTable: (props: Omit<ProteusDataTable, "$type">) => ProteusDataTable;
     Document: (props: Omit<ProteusDocument, "$type">) => ProteusDocument;
     Field: (props: Omit<ProteusField, "$type">) => ProteusField;
     Group: (props: Omit<ProteusGroup, "$type">) => ProteusGroup;

package/dist/proteus.js

@@ -19,7 +19,19 @@ exports.UI = {
         $type: "Action",
         ...props,
     }),
+    Badge: (props) => ({
+        $type: "Badge",
+        ...props,
+    }),
     CancelAction: (props) => ({ $type: "CancelAction", ...props }),
+    Chart: (props) => ({
+        $type: "Chart",
+        ...props,
+    }),
+    DataTable: (props) => ({
+        $type: "DataTable",
+        ...props,
+    }),
     Document: (props) => ({
         $type: "Document",
         ...props,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optimizely-opal/opal-tools-sdk",
-  "version": "0.1.8-dev",
+  "version": "0.1.9-dev",
   "description": "SDK for creating Opal-compatible tools services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/proteus.ts

@@ -7,8 +7,11 @@
 export type OpalProteusDocumentSpecification =
   | ProteusAction
   | ProteusAtomicCondition
+  | ProteusBadge
   | ProteusCancelAction
+  | ProteusChart
   | ProteusCondition
+  | ProteusDataTable
   | ProteusDocument
   | ProteusElement
   | ProteusEventHandler
@@ -199,6 +202,77 @@ export type ProteusAtomicCondition =
        */
       "!!": boolean | null | number | ProteusValue | string;
     };
+export interface ProteusBadge {
+  $type: "Badge";
+  alignItems?: SprinklePropAlignItems;
+  alignSelf?: SprinklePropAlignSelf;
+  animation?: SprinklePropAnimation;
+  backgroundImage?: SprinklePropBackgroundImage;
+  bg?: SprinklePropBg;
+  border?: SprinklePropBorder;
+  borderB?: SprinklePropBorderB;
+  borderColor?: SprinklePropBorderColor;
+  borderL?: SprinklePropBorderL;
+  borderR?: SprinklePropBorderR;
+  borderT?: SprinklePropBorderT;
+  children?: ProteusNode;
+  color?: SprinklePropColor;
+  cursor?: SprinklePropCursor;
+  display?: SprinklePropDisplay;
+  flex?: SprinklePropFlex;
+  flexDirection?: SprinklePropFlexDirection;
+  flexWrap?: SprinklePropFlexWrap;
+  fontFamily?: SprinklePropFontFamily;
+  fontSize?: SprinklePropFontSize;
+  fontWeight?: SprinklePropFontWeight;
+  gap?: SprinklePropGap;
+  gridColumn?: SprinklePropGridColumn;
+  gridTemplateColumns?: SprinklePropGridTemplateColumns;
+  h?: SprinklePropH;
+  /**
+   * Control the appearance by selecting between the different badge types.
+   */
+  intent?:
+    | "danger"
+    | "information"
+    | "neutral"
+    | "primary"
+    | "success"
+    | "warning";
+  justifyContent?: SprinklePropJustifyContent;
+  justifyItems?: SprinklePropJustifyItems;
+  m?: SprinklePropM;
+  maxH?: SprinklePropMaxH;
+  maxW?: SprinklePropMaxW;
+  mb?: SprinklePropMb;
+  ml?: SprinklePropMl;
+  mr?: SprinklePropMr;
+  mt?: SprinklePropMt;
+  mx?: SprinklePropMx;
+  my?: SprinklePropMy;
+  objectFit?: SprinklePropObjectFit;
+  overflow?: SprinklePropOverflow;
+  overflowX?: SprinklePropOverflowX;
+  overflowY?: SprinklePropOverflowY;
+  p?: SprinklePropP;
+  pb?: SprinklePropPb;
+  pl?: SprinklePropPl;
+  placeItems?: SprinklePropPlaceItems;
+  pointerEvents?: SprinklePropPointerEvents;
+  pr?: SprinklePropPr;
+  pt?: SprinklePropPt;
+  px?: SprinklePropPx;
+  py?: SprinklePropPy;
+  rounded?: SprinklePropRounded;
+  shadow?: SprinklePropShadow;
+  size?: SprinklePropSize;
+  textAlign?: SprinklePropTextAlign;
+  textTransform?: SprinklePropTextTransform;
+  transition?: SprinklePropTransition;
+  w?: SprinklePropW;
+  whiteSpace?: SprinklePropWhiteSpace;
+  z?: SprinklePropZ;
+}
 export interface ProteusCancelAction {
   $type: "CancelAction";
   alignItems?: SprinklePropAlignItems;
@@ -263,6 +337,46 @@ export interface ProteusCancelAction {
   whiteSpace?: SprinklePropWhiteSpace;
   z?: SprinklePropZ;
 }
+export interface ProteusChart {
+  $type: "Chart";
+  /**
+   * Chart data records, either inline or a ProteusValue reference
+   */
+  data?:
+    | ProteusValue
+    | {
+        [k: string]: undefined | unknown;
+      }[];
+  /**
+   * Data series configuration
+   */
+  series?: {
+    /**
+     * Series color
+     */
+    color?: string;
+    /**
+     * Key in data records for this series
+     */
+    dataKey: string;
+    /**
+     * Key in data records for pre-formatted labels displayed above bars
+     */
+    labelKey?: string;
+    /**
+     * Display name for legend
+     */
+    name?: string;
+  }[];
+  /**
+   * Chart type
+   */
+  type?: "bar";
+  /**
+   * Key in data records for x-axis labels
+   */
+  xAxisKey?: string;
+}
 /**
  * Condition for Show component. Can be a comparison operator, logical AND, or logical OR. Supports nesting.
  */
@@ -299,14 +413,41 @@ export type ProteusCondition =
         )[],
       ];
     };
+export interface ProteusDataTable {
+  $type: "DataTable";
+  /**
+   * Column definitions
+   */
+  columns?: {
+    /**
+     * Key in data objects
+     */
+    accessorKey: string;
+    /**
+     * Column header text
+     */
+    header: string;
+  }[];
+  data?:
+    | ProteusValue
+    | {
+        [k: string]: undefined | unknown;
+      }[];
+}
 export interface ProteusDocument {
   $type: "Document";
   /**
    * Actions available for this document
    */
-  actions?: ProteusNode;
+  actions?:
+    | (boolean | null | number | ProteusElement | string)[]
+    | boolean
+    | null
+    | number
+    | ProteusElement
+    | string;
   /**
-   * A visual representation of the application
+   * URL or data URI for the application icon (e.g., 'https://example.com/icon.png' or 'data:image/svg+xml,...'). Rendered as an <img> element.
    */
   appIcon?: string;
   /**
@@ -317,22 +458,46 @@ export interface ProteusDocument {
    * If true, hides chat prompt and forces user interaction with document. User can press ESC or close to abandon.
    */
   blocking?: boolean;
-  body: ProteusNode;
   /**
-   * A brief description or tagline that provides additional context about the Proteus document's purpose.
+   * A Proteus node can be a string, number, boolean, null, a single element, or an array of these types (similar to ReactNode)
+   */
+  body:
+    | (boolean | null | number | ProteusElement | string)[]
+    | boolean
+    | null
+    | number
+    | ProteusElement
+    | string;
+  /**
+   * A Proteus node can be a string, number, boolean, null, a single element, or an array of these types (similar to ReactNode)
    */
-  subtitle?: string;
+  subtitle?:
+    | (boolean | null | number | ProteusElement | string)[]
+    | boolean
+    | null
+    | number
+    | ProteusElement
+    | string;
   /**
-   * A concise heading that encapsulates the essence of the Proteus document's content or intended action.
+   * A Proteus node can be a string, number, boolean, null, a single element, or an array of these types (similar to ReactNode)
    */
-  title: string;
+  title:
+    | (boolean | null | number | ProteusElement | string)[]
+    | boolean
+    | null
+    | number
+    | ProteusElement
+    | string;
 }
 /**
  * A single Proteus UI component element identified by its $type discriminator
  */
 export type ProteusElement =
   | ProteusAction
+  | ProteusBadge
   | ProteusCancelAction
+  | ProteusChart
+  | ProteusDataTable
   | ProteusField
   | ProteusGroup
   | ProteusHeading
@@ -608,7 +773,7 @@ export interface ProteusImage {
   /**
    * Alternative text for the image
    */
-  alt?: string;
+  alt?: ProteusValue | string;
   animation?: SprinklePropAnimation;
   backgroundImage?: SprinklePropBackgroundImage;
   bg?: SprinklePropBg;
@@ -661,7 +826,7 @@ export interface ProteusImage {
   /**
    * The image source URL
    */
-  src?: string;
+  src?: ProteusValue | string;
   textAlign?: SprinklePropTextAlign;
   textTransform?: SprinklePropTextTransform;
   transition?: SprinklePropTransition;
@@ -855,13 +1020,13 @@ export interface ProteusLink {
 export interface ProteusMap {
   $type: "Map";
   /**
-   * Template object to render for each item in the array. Value paths are relative to current item.
+   * Template object to render for each item in the array. Value paths inside this template are relative to the current item (e.g., path='title' resolves to each item's 'title' field). Use a leading '/' to reference top-level data (e.g., path='/title' resolves to the root data's 'title').
    */
   children?: {
     [k: string]: undefined | unknown;
   };
   /**
-   * JSON pointer path to array (e.g., '/questions')
+   * JSON pointer path to the source array in the data (e.g., '/results')
    */
   path: string;
 }
@@ -1208,6 +1373,10 @@ export interface ProteusText {
   h?: SprinklePropH;
   justifyContent?: SprinklePropJustifyContent;
   justifyItems?: SprinklePropJustifyItems;
+  /**
+   * Truncate the text at specific number of lines.
+   */
+  lineClamp?: "1" | "2" | "3" | "4";
   m?: SprinklePropM;
   maxH?: SprinklePropMaxH;
   maxW?: SprinklePropMaxW;
@@ -1236,6 +1405,10 @@ export interface ProteusText {
   textAlign?: SprinklePropTextAlign;
   textTransform?: SprinklePropTextTransform;
   transition?: SprinklePropTransition;
+  /**
+   * Whether to truncate the text and add an ellipsis at the end.
+   */
+  truncate?: boolean;
   w?: SprinklePropW;
   whiteSpace?: SprinklePropWhiteSpace;
   z?: SprinklePropZ;
@@ -1322,7 +1495,7 @@ export interface ProteusTextarea {
 export interface ProteusValue {
   $type: "Value";
   /**
-   * JSON pointer path to value (e.g., '/question', '/options/0/label')
+   * Path to a value in the data. Absolute paths start with '/' and resolve from the root (e.g., '/title', '/options/0/label'). Inside a Map template, paths without a leading '/' are relative to the current item (e.g., 'title' resolves to each item's 'title' field).
    */
   path: string;
 }
@@ -1762,6 +1935,7 @@ export type SprinklePropMy =
   | "64"
   | "80"
   | "auto";
+
 /**
  * Set the element's `object-fit` CSS property
  */
@@ -1774,7 +1948,6 @@ export type SprinklePropOverflow = "auto" | "hidden" | "visible";
  * Set the element's `overflow-x` CSS property
  */
 export type SprinklePropOverflowX = "auto" | "hidden" | "visible";
-
 /**
  * Set the element's `overflow-y` CSS property
  */
@@ -2056,9 +2229,21 @@ export const UI = {
     $type: "Action" as const,
     ...props,
   }),
+  Badge: (props: Omit<ProteusBadge, "$type">): ProteusBadge => ({
+    $type: "Badge" as const,
+    ...props,
+  }),
   CancelAction: (
     props: Omit<ProteusCancelAction, "$type">,
   ): ProteusCancelAction => ({ $type: "CancelAction" as const, ...props }),
+  Chart: (props: Omit<ProteusChart, "$type">): ProteusChart => ({
+    $type: "Chart" as const,
+    ...props,
+  }),
+  DataTable: (props: Omit<ProteusDataTable, "$type">): ProteusDataTable => ({
+    $type: "DataTable" as const,
+    ...props,
+  }),
   Document: (props: Omit<ProteusDocument, "$type">): ProteusDocument => ({
     $type: "Document" as const,
     ...props,