@api-client/ui 0.5.39 → 0.5.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@api-client/ui",
-  "version": "0.5.39",
+  "version": "0.5.41",
   "description": "Internal UI component library for the API Client ecosystem.",
   "license": "UNLICENSED",
   "main": "build/src/index.js",

package/src/elements/contextual-menu/{internals/ContextualMenu.ts → ContextualMenu.ts}

@@ -1,18 +1,20 @@
-import { MenuItem } from './MenuItem.js'
-import { genId } from './IdGenerator.js'
+import { MenuItem } from './internals/MenuItem.js'
+import { genId } from './internals/IdGenerator.js'
 import type {
   CommandBase,
   ContextMenuCommand,
   ContextMenuExecuteDetail,
   CustomMenuEventDetail,
+  MenuContext,
   MenuOptions,
   MenuPoint,
   MenuTriggerInfo,
-} from './types.js'
-import type ContextMenuElement from './ContextualMenuElement.js'
+} from './internals/types.js'
+import type ContextMenuElement from './internals/ContextualMenuElement.js'
 import { Logger, ILogObj } from 'tslog'
+export type * from './internals/types.js'
 
-import '../contextual-menu.js'
+import './contextual-menu.js'
 
 function cancelEvent(e: Event): void {
   e.preventDefault()
@@ -248,7 +250,7 @@ export class ContextualMenu<S = unknown> extends EventTarget {
    * Register a list of commands to be rendered in the menu when triggered.
    * This overrides previously registered commands.
    */
-  registerCommands(commands: CommandBase<S>[]): void {
+  registerCommands(commands: (CommandBase<S> | ContextMenuCommand<S>)[]): void {
     if (!Array.isArray(commands) || !commands.length) {
       this.logger.warn('registerCommands called with empty array')
       return
@@ -259,7 +261,7 @@ export class ContextualMenu<S = unknown> extends EventTarget {
   /**
    * Adds a single command to the menu.
    */
-  addCommand(command: CommandBase<S>): void {
+  addCommand(command: CommandBase<S> | ContextMenuCommand<S>): void {
     if (!this.commands) {
       this.commands = []
     }
@@ -338,11 +340,33 @@ export class ContextualMenu<S = unknown> extends EventTarget {
       customData,
       target,
     }
+    this.beforeRender()
     this.render(placementPoint, commands)
     target.setAttribute('active', '')
     return true
   }
 
+  /**
+   * A lifecycle method called before the `render()` method.
+   */
+  protected beforeRender(): void {
+    const { beforeRender } = this.options
+    if (!beforeRender) {
+      return
+    }
+    const context: MenuContext = {
+      store: this.store,
+      target: this.triggerInfo?.target || this.workspace,
+      root: this.workspace,
+      customData: this.triggerInfo?.customData,
+    }
+    try {
+      beforeRender(context)
+    } catch {
+      // ...
+    }
+  }
+
   /**
    * @param placementPoint The workspace position of where to place the menu.
    * @param commands The commands render

package/src/elements/contextual-menu/internals/types.ts

@@ -15,6 +15,13 @@ export interface MenuOptions {
    * would render this context menu and in another system's & browser context menu.
    */
   cancelNativeWhenHandled?: boolean
+  /**
+   * Called before the menu is rendered.
+   * Specifically, it is called right before the internal `render()` method is called.
+   * It doesn't allow you to modify the menu items, but you can perform any setup
+   * before the menu is rendered.
+   */
+  beforeRender?: (ctx: MenuContext) => void
 }
 
 export interface MenuPoint {
@@ -22,11 +29,7 @@ export interface MenuPoint {
   y: number
 }
 
-interface LifecycleContext<S> {
-  /**
-   * The id of the command.
-   */
-  id: string
+export interface MenuContext<S = unknown> {
   /**
    * The object store to be used to store menu item data.
    */
@@ -45,14 +48,21 @@ interface LifecycleContext<S> {
   customData?: unknown
 }
 
+interface LifecycleContext<S = unknown> extends MenuContext<S> {
+  /**
+   * The id of the command.
+   */
+  id: string
+}
+
 export interface EnabledMenuOptions<S = unknown> extends LifecycleContext<S> {}
 
-export interface CheckedMenuOptions<S> extends LifecycleContext<S> {}
+export interface CheckedMenuOptions<S = unknown> extends LifecycleContext<S> {}
 
 /**
  * Options passed to the `visible()` callback function.
  */
-export type VisibleOptions<S> = EnabledMenuOptions<S>
+export type VisibleOptions<S = unknown> = EnabledMenuOptions<S>
 
 export interface CommandExecuteOptions<S = unknown> extends LifecycleContext<S> {
   /**

package/.aiexclude

@@ -1,3 +0,0 @@
-coverage/
-.tmp/
-build/

package/.cursor/rules/html-and-css-best-practices.mdc

@@ -1,63 +0,0 @@
----
-description: 
-globs: *.ts,*.css,*html
-alwaysApply: false
----
-
-    You are an expert developer in HTML and CSS, focusing on best practices, accessibility, and responsive design.
-
-    Key Principles
-    - Write semantic HTML to improve accessibility and SEO.
-    - Use CSS for styling, avoiding inline styles.
-    - Ensure responsive design using media queries and flexible layouts.
-    - Prioritize accessibility by using ARIA roles and attributes.
-
-    HTML
-    - Use semantic elements (e.g., <header>, <main>, <footer>, <article>, <section>).
-    - Use <button> for clickable elements, not <div> or <span>.
-    - Use <a> for links, ensuring href attribute is present.
-    - Use <img> with alt attribute for images.
-    - Use <form> for forms, with appropriate input types and labels.
-    - Avoid using deprecated elements (e.g., <font>, <center>).
-
-    CSS
-    - Use external stylesheets for CSS.
-    - Use class selectors over ID selectors for styling.
-    - Use Flexbox and Grid for layout.
-    - Use rem and em units for scalable and accessible typography.
-    - Use CSS variables for consistent theming.
-    - Use BEM (Block Element Modifier) methodology for naming classes.
-    - Avoid !important; use specificity to manage styles.
-
-    Responsive Design
-    - Use media queries to create responsive layouts.
-    - Use mobile-first approach for media queries.
-    - Ensure touch targets are large enough for touch devices.
-    - Use responsive images with srcset and sizes attributes.
-    - Use viewport meta tag for responsive scaling.
-
-    Accessibility
-    - Use ARIA roles and attributes to enhance accessibility.
-    - Ensure sufficient color contrast for text.
-    - Provide keyboard navigation for interactive elements.
-    - Use focus styles to indicate focus state.
-    - Use landmarks (e.g., <nav>, <main>, <aside>) for screen readers.
-
-    Performance
-    - Minimize CSS and HTML file sizes.
-    - Use CSS minification and compression.
-    - Avoid excessive use of animations and transitions.
-    - Use lazy loading for images and other media.
-
-    Testing
-    - Test HTML and CSS in multiple browsers and devices.
-    - Use tools like Lighthouse for performance and accessibility audits.
-    - Validate HTML and CSS using W3C validators.
-
-    Documentation
-    - Comment complex CSS rules and HTML structures.
-    - Use consistent naming conventions for classes and IDs.
-    - Document responsive breakpoints and design decisions.
-
-    Refer to MDN Web Docs for HTML and CSS best practices and to the W3C guidelines for accessibility standards.
-    

package/.cursor/rules/lit-best-practices.mdc

@@ -1,89 +0,0 @@
----
-globs: src/elements/**,src/md/**,src/styles/**,demo/**
-alwaysApply: false
----
-
-You are an expert developer in web components using the Lit library and Material Design version 3, focusing on best practices, accessibility, and responsive design.
-
-Key Principles
-
-- Comply with web elements authoring standards when designing a web component.
-- Use accessibility best practices to produce semantically relevant web components.
-- Prioritize web standards over custom implementation.
-- Prioritize APIs that are passing the Web Platform Baseline
-- Minimize external dependencies, but also balance between custom code and widely known and trusted dependencies.
-- Everything must be ES compliant. Use the appropriate standards for module imports.
-
-Lit Web Components
-
-- Document public properties and public function for authors to understand what these properties and functions do.
-- Ensure the appropriate aria roles are applied to each element.
-- Document all events and their structure (for custom events).
-- Prioritize well-known events (like change, select) over custom events.
-- Provide examples of usage when producing component documentation.
-- Prioritize native elements over custom elements whenever possible.
-- Prioritize composition over attribute passed configuration (a dropdown should have a semantic HTML structure and not auto-generated structure from a complex configuration object).
-- Think of other use-cases and how the custom element can scale for future use cases.
-- Reuse existing components whenever possible.
-- Prefer to put lifecycle methods after the constructor and before the render and other methods.
-- Put render methods at the end of the class.
-- Use `@property` decorator for public properties and `@state` decorator for private properties.
-- Use `@query` decorator for querying elements in the shadow DOM.
-- Use `@queryAssignedElements` decorator for querying slotted elements.
-- Boolean properties should be initialized to `false` in the constructor.
-- Use `@eventOptions` decorator to specify event options like `capture`, `passive`, and `once`.
-- Use `@queryAsync` decorator for querying elements that may not be immediately available in the DOM.
-- Use `@state` decorator for properties that are internal to the component and should not be exposed to the outside world.
-- Avoid passing complex objects as properties. Instead, use simple types like `string`, `number`, or `boolean` and handle complex logic internally.
-- Use lifecycle methods like `connectedCallback`, `disconnectedCallback`, and `update` to manage component state and behavior.
-- Use `willUpdate` method to perform actions before the component updates, such as validating properties or preparing data.
-- Place the component definition under the `internals/` directory of a component folder. The components registration should be done in the component file in the main component directory.
-- Place the base material components under the `src/md/` directory.
-- Place composite components under the `src/elements/` directory.
-
-CSS and Styling
-
-- Prioritize native CSS over JavaScript implementation. Use Web Platform Baseline even if the editor says it's not supported.
-- Use anchoring and popover API whenever possible and applicable over JavaScript positioning.
-- Place lit component styles in a separate file with the `.styles.ts` extension.
-- Add styles to the component registration class, not the base class.
-- Declare the `part` attributes to expose custom styling.
-- When working on base components, use CSS variables to allow customization of the component styles.
-- Define component states via the `internals.states.add("--state-name")` method. These states can be used as `component-name:state(state-name) {}` in the CSS.
-
-Error handling
-
-- Components either communicate errors through rendering them internally or dispatch an error event with the error details to the parent component or application.
-- Prefer error states defined on the element internals over custom error styling.
-
-Naming Convention
-
-- Follow web authoring standards as closely as possible.
-- Minimize the use of "-" in attribute and event names
-- Use camelCase for properties and methods.
-- Do not prefix private or protected properties and methods with an underscore. Use the typescript `private` and `protected` keywords to indicate visibility.
-
-Testing
-
-- Use @open-wc/testing library.
-- Always add accessibility tests.
-- Create fixtures for different states of a component.
-- To run tests for a specific file, use the `--files` option in the test command. For example:
-
-  ```bash
-  npm test -- --files=".tmp/test/**/[test file name].test.js"
-  ```
-
-- Prefer the Assert API over the Expect API for assertions. The Assert API is more performant and provides better error messages.
-- When updating an element's property, await for the update to complete using `await element.updateComplete` before making assertions. This ensures that the component has fully rendered before checking its state.
-
-Component Demoing
-
-- Always produce a demo page under the demo/ directory.
-- Use the `DemoPage` class to bootstrap the demo page.
-- Use material styles with the demo page. Minimize custom styling.
-- Try to render each state separately and minimize the use of complex configurations.
-- Start with simple states and progressively enhance the demo with more complex configurations.
-- If a component produces output, ensure that the demo page shows the output in a readable format. Use one output per component.
-- Document the states in a way that is obvious to the user. Use headings and paragraphs to explain the states.
-- Due to the nature how the demo pages are processed, ensure that typescript files that belong to the demo page are imported from the `/.tmp/demo/` directory. This is done automatically by the build process. Imports inside the typescript file should reference files from the `src/` folder directly.

package/.editorconfig

@@ -1,29 +0,0 @@
-# EditorConfig helps developers define and maintain consistent
-# coding styles between different editors and IDEs
-# editorconfig.org
-
-root = true
-
-
-[*]
-
-# Change these settings to your own preference
-indent_style = space
-indent_size = 2
-
-# We recommend you to keep these unchanged
-end_of_line = lf
-charset = utf-8
-trim_trailing_whitespace = true
-insert_final_newline = true
-
-[*.md]
-trim_trailing_whitespace = false
-
-[*.json]
-indent_size = 2
-
-[*.{html,js,md}]
-block_comment_start = /**
-block_comment = *
-block_comment_end = */

package/.github/CONTRIBUTING.md

@@ -1,24 +0,0 @@
-# Contributing to API Client
-
-First of all, we are happy you want to contribute to API Client open source project. API Client is a community driven project and we are open to your input. Before you start lets clear some things first so your contribution is accepted without unnecessary delays.
-
-## Start with an issue report
-
-Before you start working on any code or architecture, please, report an issue in the corresponding repository. This is crucial for open projects so the community can take a part in the discussion. Also, the project is being developed so we can predict upcoming changes. This way we will also be able to direct you in the right direction, like telling you where you can find relevant code. See below for more information.
-
-## Code the change
-
-### Code and PR
-
-After you have created an issue report and picked the right repository you now are enabled to code the change. After you finish **introduce relevant tests**. We can't accept PRs that contains an untested code. After that create a PR to the relevant repository. We will get back to you as soon as possible. Heel free to mention us directly in the PR so we will get a notification from GitHub.
-
-### Things to consider
-
-- Introduce changes that other users will benefit from
-- Significant architecture changes make take longer to be accepted giving the complexity of the dependencies. API Client has a shared code with MuleSoft's API Console. We need to ensure the stability of both projects.
-- Understand the reasons for the distributed architecture and honor the structure of the project. Most likely you want to introduce changes to the `core` repository. Less likely others.
-- We are here to help. Ask us questions about the architecture or how stuff work.
-
-------
-
-That's it. We are thrilled seeing you contributing to the project. Drop us a message in case you have any questions.

package/.github/instructions/html-and-css-best-practices.instructions.md

@@ -1,70 +0,0 @@
----
-applyTo: "*.ts,*.css,*html"
----
-
-# HTML and CSS Best Practices
-
-You are an expert developer in HTML and CSS, focusing on best practices, accessibility, and responsive design.
-
-## Key Principles
-
-- Write semantic HTML to improve accessibility and SEO.
-- Use CSS for styling, avoiding inline styles.
-- Ensure responsive design using media queries and flexible layouts.
-- Prioritize accessibility by using ARIA roles and attributes.
-
-## HTML
-
-- Use semantic elements (e.g., <header>, <main>, <footer>, <article>, <section>).
-- Use <button> for clickable elements, not <div> or <span>.
-- Use <a> for links, ensuring href attribute is present.
-- Use <img> with alt attribute for images.
-- Use <form> for forms, with appropriate input types and labels.
-- Avoid using deprecated elements (e.g., <font>, <center>).
-
-## CSS
-
-- Use external stylesheets for CSS.
-- Use class selectors over ID selectors for styling.
-- Use Flexbox and Grid for layout.
-- Use rem and em units for scalable and accessible typography.
-- Use CSS variables for consistent theming.
-- Use BEM (Block Element Modifier) methodology for naming classes.
-- Avoid !important; use specificity to manage styles.
-
-## Responsive Design
-
-- Use media queries to create responsive layouts.
-- Use mobile-first approach for media queries.
-- Ensure touch targets are large enough for touch devices.
-- Use responsive images with srcset and sizes attributes.
-- Use viewport meta tag for responsive scaling.
-
-## Accessibility
-
-- Use ARIA roles and attributes to enhance accessibility.
-- Ensure sufficient color contrast for text.
-- Provide keyboard navigation for interactive elements.
-- Use focus styles to indicate focus state.
-- Use landmarks (e.g., <nav>, <main>, <aside>) for screen readers.
-
-## Performance
-
-- Minimize CSS and HTML file sizes.
-- Use CSS minification and compression.
-- Avoid excessive use of animations and transitions.
-- Use lazy loading for images and other media.
-
-## Testing
-
-- Test HTML and CSS in multiple browsers and devices.
-- Use tools like Lighthouse for performance and accessibility audits.
-- Validate HTML and CSS using W3C validators.
-
-## Documentation
-
-- Comment complex CSS rules and HTML structures.
-- Use consistent naming conventions for classes and IDs.
-- Document responsive breakpoints and design decisions.
-
-Refer to MDN Web Docs for HTML and CSS best practices and to the W3C guidelines for accessibility standards.

package/.github/instructions/lit-best-practices.instructions.md

@@ -1,90 +0,0 @@
----
-applyTo: "src/{elements,md,styles}/**,demo/**"
----
-
-# Lit Element Best Practices
-
-You are an expert developer in web components using the Lit library and Material Design version 3, focusing on best practices, accessibility, and responsive design.
-
-## Key Principles
-
-- Comply with web elements authoring standards when designing a web component.
-- Use accessibility best practices to produce semantically relevant web components.
-- Prioritize web standards over custom implementation.
-- Prioritize APIs that are passing the Web Platform Baseline
-- Minimize external dependencies, but also balance between custom code and widely known and trusted dependencies.
-- Everything must be ES compliant. Use the appropriate standards for module imports.
-
-## Lit Web Components
-
-- Document public properties and public function for authors to understand what these properties and functions do.
-- Ensure the appropriate aria roles are applied to each element.
-- Document all events and their structure (for custom events).
-- Prioritize well-known events (like change, select) over custom events.
-- Provide examples of usage when producing component documentation.
-- Prioritize native elements over custom elements whenever possible.
-- Prioritize composition over attribute passed configuration (a dropdown should have a semantic HTML structure and not auto-generated structure from a complex configuration object).
-- Think of other use-cases and how the custom element can scale for future use cases.
-- Reuse existing components whenever possible.
-- Prefer to put lifecycle methods after the constructor and before the render and other methods.
-- Put render methods at the end of the class.
-- Use `@property` decorator for public properties and `@state` decorator for private properties.
-- Use `@query` decorator for querying elements in the shadow DOM.
-- Use `@queryAssignedElements` decorator for querying slotted elements.
-- Boolean properties should be initialized to `false` in the constructor.
-- Use `@eventOptions` decorator to specify event options like `capture`, `passive`, and `once`.
-- Use `@queryAsync` decorator for querying elements that may not be immediately available in the DOM.
-- Use `@state` decorator for properties that are internal to the component and should not be exposed to the outside world.
-- Avoid passing complex objects as properties. Instead, use simple types like `string`, `number`, or `boolean` and handle complex logic internally.
-- Use lifecycle methods like `connectedCallback`, `disconnectedCallback`, and `update` to manage component state and behavior.
-- Use `willUpdate` method to perform actions before the component updates, such as validating properties or preparing data.
-- Place the component definition under the `internals/` directory of a component folder. The components registration should be done in the component file in the main component directory.
-- Place the base material components under the `src/md/` directory.
-- Place composite components under the `src/elements/` directory.
-
-## CSS and Styling
-
-- Prioritize native CSS over JavaScript implementation. Use Web Platform Baseline even if the editor says it's not supported.
-- Use anchoring and popover API whenever possible and applicable over JavaScript positioning.
-- Place lit component styles in a separate file with the `.styles.ts` extension.
-- Add styles to the component registration class, not the base class.
-- Declare the `part` attributes to expose custom styling.
-- When working on base components, use CSS variables to allow customization of the component styles.
-- Define component states via the `internals.states.add("--state-name")` method. These states can be used as `component-name:state(state-name) {}` in the CSS.
-
-## Error handling
-
-- Components either communicate errors through rendering them internally or dispatch an error event with the error details to the parent component or application.
-- Prefer error states defined on the element internals over custom error styling.
-
-## Naming Convention
-
-- Follow web authoring standards as closely as possible.
-- Minimize the the of "-" in attribute and event names
-- Use camelCase for properties and methods.
-- Do not prefix private or protected properties and methods with an underscore. Use the typescript `private` and `protected` keywords to indicate visibility.
-
-## Testing
-
-- Use @open-wc/testing library.
-- Always add accessibility tests.
-- Create fixtures for different states of a component.
-- To run tests for a specific file, use the `--files` option in the test command. For example:
-
-  ```bash
-  npm test -- --files=".tmp/test/**/[test file name].test.js"
-  ```
-  
-- Prefer the Assert API over the Expect API for assertions. The Assert API is more performant and provides better error messages.
-- When updating an element's property, await for the update to complete using `await element.updateComplete` before making assertions. This ensures that the component has fully rendered before checking its state.
-
-## Component Demoing
-
-- Always produce a demo page under the demo/ directory.
-- Use the `DemoPage` class to bootstrap the demo page.
-- Use material styles with the demo page. Minimize custom styling.
-- Try to render each state separately and minimize the use of complex configurations.
-- Start with simple states and progressively enhance the demo with more complex configurations.
-- If a component produces output, ensure that the demo page shows the output in a readable format. Use one output per component.
-- Document the states in a way that is obvious to the user. Use headings and paragraphs to explain the states.
-- Due to the nature how the demo pages are processed, ensure that typescript files that belong to the demo page are imported from the `/.tmp/demo/` directory. This is done automatically by the build process. Imports inside the typescript file should reference files from the `src/` folder directly.

package/.github/release.yml

@@ -1,14 +0,0 @@
-changelog:
-  exclude:
-    labels:
-      - ignore-for-release
-  categories:
-    - title: 🏕 Features
-      labels:
-        - '*'
-      exclude:
-        labels:
-          - dependencies
-    - title: 👒 Dependencies
-      labels:
-        - dependencies

package/.github/stale.yml

@@ -1,23 +0,0 @@
-# Number of days of inactivity before an issue becomes stale
-daysUntilStale: 45
-# Number of days of inactivity before a stale issue is closed
-daysUntilClose: 7
-# Issues with these labels will never be considered stale
-exemptLabels:
-   - bug
-   - fixme/bug
-   - fixme/security
-   - blocked
-   - needs-review
-   - roadmap
-# Label to use when marking an issue as stale
-staleLabel: stale
-# Comment to post when marking an issue as stale. Set to `false` to disable
-markComment: >
-  This issue has been automatically marked as stale because it has not had
-  recent activity and is not currently prioritized. It will be closed
-  in a week if no further activity occurs :)
-# Comment to post when closing a stale issue. Set to `false` to disable
-closeComment: >
-  If you still think this issue is relevant, please ping a maintainer or
-  leave a comment!