@aws/mynah-ui 4.35.3 → 4.35.4

package/dist/static.d.ts

@@ -81,6 +81,18 @@ export interface MynahUIDataModel {
     * Placeholder to be shown on prompt input
     */
     promptInputPlaceholder?: string;
+    /**
+     * Title to be shown on prompt top bar
+     */
+    promptTopBarTitle?: string;
+    /**
+   * Items to be pinned in prompt top bar
+   */
+    promptTopBarContextItems?: QuickActionCommand[];
+    /**
+   * Button to display at end of prompt top bar
+   */
+    promptTopBarButton?: ChatItemButton | null;
     /**
     * Prompt input text
     */
@@ -200,7 +212,11 @@ export declare enum MynahEventNames {
     TAB_BAR_BUTTON_CLICK = "tabBarButtonClick",
     PROMPT_PROGRESS_ACTION_CLICK = "promptProgressActionClick",
     ROOT_RESIZE = "rootResize",
-    CONTEXT_SELECTED = "contextSelected"
+    CONTEXT_SELECTED = "contextSelected",
+    TOP_BAR_ITEM_ADD = "promptInputTopBarItemAdd",
+    TOP_BAR_ITEM_REMOVE = "promptInputTopBarItemRemove",
+    TOP_BAR_BUTTON_CLICK = "promptInputTopBarButtonClick",
+    CONTEXT_PINNED = "contextPinned"
 }
 export declare enum MynahPortalNames {
     WRAPPER = "wrapper",
@@ -261,6 +277,7 @@ export interface DetailedListItemGroup {
     actions?: Action[];
     icon?: MynahIcons | MynahIconsType;
     children?: DetailedListItem[];
+    childrenIndented?: boolean;
 }
 export interface DetailedListItem {
     title?: string;

package/docs/DATAMODEL.md

@@ -573,6 +573,92 @@ mynahUI.updateStore('tab-1', {
   <img src="./img/data-model/tabStore/promptInputPlaceholder.png" alt="mainTitle" style="max-width:500px; width:100%;border: 1px solid #e0e0e0;">
 </p>
 
+---
+### `promptTopBarTitle` (default: `''`)
+
+This is the title displayed in the prompt top bar. When set, it enables a top bar that can be used for pinned context items.
+
+```typescript
+const mynahUI = new MynahUI({
+    tabs: {
+        'tab-1': {
+            ...
+        }
+    }
+});
+
+mynahUI.updateStore('tab-1', {
+    promptTopBarTitle: '@Pin Context'
+})
+```
+
+<p align="center">
+  <img src="./img/data-model/tabStore/promptTopBarTitle.png" alt="prompt top bar title" style="max-width:500px; width:100%;border: 1px solid #e0e0e0;">
+</p>
+
+---
+
+### `promptTopBarContextItems` (default: `[]`)
+
+These are the context items pinned to the prompt top bar. They appear as pills that can be removed by the user. Top bar only appears when `promptTopBarTitle` is not empty.
+
+```typescript
+const mynahUI = new MynahUI({
+    tabs: {
+        'tab-1': {
+            ...
+        }
+    }
+});
+
+mynahUI.updateStore('tab-1', {
+    promptTopBarContextItems: [
+        {
+            command: 'ex-dom.ts',
+            icon: MynahIcons.FILE,
+            description: '.src/helper'
+        },
+        {
+            command: 'main',
+            icon: MynahIcons.FOLDER,
+            description: '.src/'
+        }
+    ]
+})
+```
+
+<p align="center">
+  <img src="./img/data-model/tabStore/promptTopBarContextItems.png" alt="prompt top bar context items" style="max-width:500px; width:100%;border: 1px solid #e0e0e0;">
+</p>
+
+---
+
+### `promptTopBarButton` (default: `null`)
+
+This is a button displayed at the end of the prompt top bar. Clicking on the button will call onPromptTopBarButtonClick(). Button only appears when `promptTopBarTitle` is not empty.
+
+```typescript
+const mynahUI = new MynahUI({
+    tabs: {
+        'tab-1': {
+            ...
+        }
+    }
+});
+
+mynahUI.updateStore('tab-1', {
+    promptTopBarButton: {
+        id: 'project-rules',
+        icon: MynahIcons.CHECK_LIST,
+        text: 'Rules'
+    }
+})
+```
+
+<p align="center">
+  <img src="./img/data-model/tabStore/promptTopBarButton.png" alt="prompt top bar button" style="max-width:500px; width:100%;border: 1px solid #e0e0e0;">
+</p>
+
 ---
 
 ### `promptInputText` (default: `''`)

package/docs/DEVELOPER.md

@@ -487,8 +487,9 @@ You've created an actuall and usable component. To remind you again about what i
   - Never create doms other with methods than `DomBuilder`
   - Use `MynahUITabsStore` data store carefully, do not duplicate anything and never use it for non tab or chat content related things.
   - Always clearly define your types
-- **Tests**
+- **Tests (see `TESTING.MD`)**
   - Add your unit tests to check the basic functionality of it works or not
+  - Add E2E tests to test the user flows
 - **Documentation**
   - Each change on `mynah-ui` has to go into the related documentation if it adds/changes/removes anything exposed. 
 

package/docs/PROPERTIES.md

@@ -177,6 +177,18 @@ export interface MynahUIProps {
   onSplashLoaderActionClick?: (
     action: Action,
     eventId?: string) => void;
+  onPromptTopBarItemAdded?: (
+    tabId: string,
+    topBarItem: ChatItemButton,
+    eventId?: string) => void;
+  onPromptTopBarItemRemoved?: (
+    tabId: string,
+    topBarItemId: string,
+    eventId?: string) => void;
+  onPromptTopBarButtonClick?: (
+    tabId: string,
+    topBarButton: ChatItemButton,
+    eventId?: string) => void;
 }
 ```
 _Let's deep dive into each property you can set._
@@ -1158,9 +1170,6 @@ This event will be fired when user clicks to an action inside the splash loader.
 
 ```typescript
 ...
-onSplashLoaderActionClick?: (
-    action: Action,
-    eventId?: string) => void;
 onSplashLoaderActionClick?: (
     action: Action,
     eventId?: string)):void => {
@@ -1168,3 +1177,59 @@ onSplashLoaderActionClick?: (
     };
 ...
 ```
+
+---
+
+### onPromptTopBarItemAdded
+
+This event will be fired when a new item is added to the prompt top bar. It passes the `tabId`, the added `topBarItem` object, and the `eventId`.
+
+```typescript
+...
+onPromptTopBarItemAdded?: (
+    tabId: string,
+    topBarItem: ChatItemButton,
+    eventId?: string):void => {
+      console.log(`Top bar item added to tab: ${tabId}`);
+      console.log(`Item ID: ${topBarItem.id}`);
+      console.log(`Item text: ${topBarItem.text}`);
+    };
+...
+```
+
+---
+
+### onPromptTopBarItemRemoved
+
+This event will be fired when an item is removed from the prompt top bar. It passes the `tabId`, the `topBarItemId` of the removed item, and the `eventId`.
+
+```typescript
+...
+onPromptTopBarItemRemoved?: (
+    tabId: string,
+    topBarItemId: string,
+    eventId?: string):void => {
+      console.log(`Top bar item removed from tab: ${tabId}`);
+      console.log(`Removed item ID: ${topBarItemId}`);
+    };
+...
+```
+
+---
+
+### onPromptTopBarButtonClick
+
+This event will be fired when a user clicks on a button in the prompt top bar. It passes the `tabId`, the clicked `topBarButton` object, and the `eventId`.
+
+```typescript
+...
+onPromptTopBarButtonClick?: (
+    tabId: string,
+    topBarButton: ChatItemButton,
+    eventId?: string):void => {
+      console.log(`Top bar button clicked on tab: ${tabId}`);
+      console.log(`Button ID: ${topBarButton.id}`);
+      console.log(`Button text: ${topBarButton.text}`);
+    };
+...
+```

package/docs/TESTING.md

@@ -0,0 +1,73 @@
+# Testing MynahUI
+To ensure both visual and logical correctness in MynahUI, we have implemented two types of tests:
+
+## 1. Unit tests (Jest)
+We use the Jest library for unit testing. These test individual components and smaller parts of the whole system. You can run the unit tests using `npm run tests:unit`. We currently have tests for:
+* The main MynahUI (in `src/__test__/main.spec.ts`)
+* And the components of MynahUI (in `src/components/__test__`)
+
+The `tests:unit` script also generates a `/coverage` folder in the root of the workspace, which includes an Istanbul coverage report. The current coverage at the time of writing is only around 51%, so there is definitely room for improvement.
+
+## 2. E2E tests (Playwright)
+Testing the full system from start to finish, simulating real user scenarios. We use Playwright for E2E testing, specifically visual regression testing with snapshots.
+
+Currently, (at the time of writing) there are **58** tests, running on both *Chromium* and *Webkit*, so **116** tests in total.
+
+All of these tests are defined in `ui-tests/__test__/main.spec.ts`, and their specific flows can be found under `ui-tests/__test__/flows/`.
+
+### Adding a new E2E test
+Adding a new test here is as simple as adding a new `test()` call in the `main.spec.ts`, e.g.:
+
+```typescript
+test('should do something', async ({ page }) => {
+   await testSomething(page);
+});
+```
+
+A new test flow should then be added to `ui-tests/__test__/flows/`. A basic flow looks something like this:
+
+```typescript
+export const testSomething = async (page: Page, skipScreenshots?: boolean): Promise<void> => {
+  if (skipScreenshots !== true) {
+    expect(await page.screenshot()).toMatchSnapshot();
+  }
+};
+```
+
+### Running E2E tests
+Running the E2E tests has to be done in a Dockerized environment,  otherwise generated snapshots might slightly differ based on the environment (e.g. OS) in which they were generated. This means that having Docker desktop installed is a requirement for running the E2E tests.
+
+Simply run all the e2e tests through the command `npm run tests:e2e`. Under the hood, this will run:
+`npm run docker:clean && npm run docker:build && npm run docker:run`.
+
+To specifically run only the chromium or webkit tests, you can use the `npm run tests:e2e:chromium` and `npm run tests:e2e:webkit` commands.
+
+### Extracting results & updating snapshots
+To extract the results from the Docker container, you should run `npm run docker:extract`. This will add a results folder to `ui-tests/__results__`. This folder contains the following:
+
+```python
+__results__:
+
+  __reports__: # Reports of failed tests
+    ...
+    junit.xml # JUnit report of the test results, to be used by the GitHub test reporter
+    .last-run.json # JSON formatted overview of the final status and an array of failed test IDs
+    
+  __snapshots__ # All snapshots that were used to run the tests
+    chromium: # All the chromium snapshots, with subfolders for each test
+    webkit: # All the webkit snapshots, with subfolders for each test
+```
+
+In case of any failed tests, the __reports__ directory will contain a subfolder for each of these failed tests, e.g.:
+```python
+main-Open-MynahUI-Feedback-form-should-cancel-feedback-form-chromium:
+  snapshot-actual.png # the real output
+  snapshot-diff.png # the differing pixels between actual and expected
+  snapshot-expected.png # the expected output (= the provided golden snapshot)
+  error-context.md # some context on why the test failed
+  trace.zip # the traces, usable on the Playwright Trace Viewer website
+```
+
+The `error-context.md` will provide some context about why the test failed. Additionally, the `trace.zip` can be used on https://trace.playwright.dev/ to visually watch back the test’s execution and see what went wrong.
+
+In case you now want any golden snapshot to be updated, you should take the `snapshot-actual.png` from this folder and replace the one in `ui-tests/__snapshots__/*THE_TEST'S_FOLDER*` with the new (actual) one. This process is slightly tedious on purpose, with the goal of encouraging extra carefulness when updating the golden snapshots.

package/docs/USAGE.md

@@ -621,4 +621,61 @@ You can use this method to tear down the existing Mynah UI state. This is useful
 
 ```typescript
 mynahUI.destroy();
-```
+```
+
+---
+
+# Opening a Top Bar Button Overlay (`openTopBarButtonOverlay`)
+
+You can programmatically open an overlay for a top bar button using the `openTopBarButtonOverlay` function. This is useful when you want to display a detailed list or other content associated with a specific top bar button.
+
+```typescript
+mynahUI.openTopBarButtonOverlay(
+  tabId,           // The ID of the tab containing the top bar button
+  topBarButtonId,  // The ID of the top bar button to open the overlay for
+  {
+    topBarButtonOverlay: {
+      // DetailedList configuration for the overlay content
+      list: [
+        {
+          groupName: 'Group 1',
+          children: [
+            {
+              title: 'Item 1',
+              description: 'Description for item 1'
+            },
+            {
+              title: 'Item 2',
+              description: 'Description for item 2'
+            }
+          ]
+        }
+      ],
+      selectable: 'clickable'
+    },
+    events: {
+      onGroupClick: (groupName) => {
+        console.log(`Group clicked: ${groupName}`);
+      },
+      onItemClick: (detailedListItem) => {
+        console.log(`Item clicked: ${detailedListItem.title}`);
+      },
+      onKeyPress: (e) => {
+        // Handle keyboard events
+        if (e.key === 'Escape') {
+          // Close the overlay
+        }
+      },
+      onClose: () => {
+        console.log('Overlay closed');
+      }
+    }
+  }
+);
+```
+
+The overlay will appear positioned relative to the specified top bar button, displaying the detailed list content you've provided. Users can interact with the items in the list, and you can handle these interactions through the event callbacks.
+
+<p align="center">
+  <img src="./img/topBarButtonOverlay.png" alt="Top Bar Button Overlay" style="max-width:500px; width:100%;border: 1px solid #e0e0e0;">
+</p>

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@aws/mynah-ui",
     "displayName": "AWS Mynah UI",
-    "version": "4.35.3",
+    "version": "4.35.4",
     "description": "AWS Toolkit VSCode and Intellij IDE Extension Mynah UI",
     "publisher": "Amazon Web Services",
     "license": "Apache License 2.0",
@@ -27,10 +27,17 @@
         "lint": "npx eslint \"./**\"",
         "format:check": "npx prettier --check .",
         "format:write": "npx prettier --write .",
-        "tests:unit": "jest",
-        "tests:e2e": "cd ./ui-tests && npm install && npm run prepare && npm run e2e",
-        "tests:e2e:chromium": "cd ./ui-tests && npm install && npm run prepare && BROWSER=chromium ts-node run-browser-tests.ts",
-        "tests:e2e:webkit": "cd ./ui-tests && npm install && npm run prepare && BROWSER=webkit ts-node run-browser-tests.ts",
+        "docker:clean": "docker rm -f mynah-ui-e2e-container || true",
+        "docker:build": "docker build -t mynah-ui-e2e -f Dockerfile .",
+        "docker:run": "docker run --name mynah-ui-e2e-container mynah-ui-e2e",
+        "docker:run:chromium": "docker run -e BROWSER=chromium --name mynah-ui-e2e-container mynah-ui-e2e",
+        "docker:run:webkit": "docker run -e BROWSER=webkit --name mynah-ui-e2e-container mynah-ui-e2e",
+        "docker:extract": "docker cp mynah-ui-e2e-container:/app/ui-tests/__results__ ./ui-tests/ && docker cp mynah-ui-e2e-container:/app/ui-tests/__snapshots__ ./ui-tests/__results__/__snapshots__",
+        "tests:e2e": "npm run docker:clean && npm run docker:build && npm run docker:run",
+        "tests:e2e:chromium": "npm run docker:clean && npm run docker:build && npm run docker:run:chromium",
+        "tests:e2e:webkit": "npm run docker:clean && npm run docker:build && npm run docker:run:webkit",
+        "tests:e2e:trace": "cd ./ui-tests && npm run trace",
+        "tests:unit": "jest --collect-coverage",
         "api-docs": "npx typedoc src/main.ts --out ./api-docs",
         "api-doc-deploy": "npx typedoc src/main.ts --out ./example/dist/api-doc",
         "postinstall": "node postinstall.js",