@api-client/ui 0.5.38 → 0.5.40

package/package.json

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

package/src/md/list/internals/ListItem.styles.ts

@@ -3,7 +3,6 @@ import { css } from 'lit'
 export default css`
   :host {
     display: block;
-    height: 56px;
     outline: none;
     cursor: default;
     position: relative;
@@ -24,16 +23,6 @@ export default css`
     display: none;
   }
 
-  :host([lines='two']),
-  :host([lines='one'][image='image']) {
-    height: 72px;
-  }
-
-  :host([lines='three']),
-  :host([lines='one'][image='video']) {
-    height: 88px;
-  }
-
   .surface {
     height: inherit;
     box-sizing: border-box;
@@ -44,6 +33,17 @@ export default css`
     padding: 8px 16px 8px 16px;
 
     gap: 16px;
+    height: 56px;
+  }
+
+  :host([image='image']) .surface,
+  .surface.two-lines {
+    height: 72px;
+  }
+
+  :host([image='video']) .surface,
+  .surface.three-lines {
+    height: 88px;
   }
 
   .ripple {

package/src/md/list/internals/ListItem.ts

@@ -13,6 +13,7 @@ export enum ListItemLines {
   one = 'one',
   two = 'two',
   three = 'three',
+  auto = 'auto',
 }
 
 export enum ListItemImage {
@@ -24,28 +25,42 @@ export enum ListItemImage {
 }
 
 /**
- * @slot
- * @slot overline
- * @slot start
- * @slot end
- * @slot end-text
- * @slot supporting-text
+ * @slot - The main content of the list item, typically a label or title.
+ * @slot overline - The text displayed above the main content.
+ * @slot start - The content displayed at the start of the list item.
+ * @slot end - The content displayed at the end of the list item.
+ * @slot end-text - The text displayed at the end of the list item.
+ * @slot supporting-text - The supporting text displayed below the main content.
  */
 export default class UiListItem extends UiElement {
   @query('ui-ripple') accessor ripple!: UiRipple
 
+  #lines: ListItemLines = ListItemLines.one
+
+  get lines(): ListItemLines {
+    if (this.#lines === ListItemLines.auto) {
+      return this.hasOverline || this.hasSupportingText ? ListItemLines.two : ListItemLines.one
+    }
+    return this.#lines
+  }
+
   /**
-   * Whether the chip is disabled. The user can't interact with the chip when `true`.
+   * The number of lines to render the list template for.
+   * @default ListItemLines.one
    * @attribute
    */
-  @property({ type: Boolean, reflect: true }) accessor disabled = false
+  @property({ type: String, reflect: true })
+  set lines(value: ListItemLines) {
+    const oldValue = this.#lines
+    this.#lines = value
+    this.requestUpdate('lines', oldValue)
+  }
 
   /**
-   * The number of lines to render the list template for.
-   * @default ListItemLines.one
+   * Whether the chip is disabled. The user can't interact with the chip when `true`.
    * @attribute
    */
-  @property({ type: String, reflect: true }) accessor lines: ListItemLines
+  @property({ type: Boolean, reflect: true }) accessor disabled = false
 
   /**
    * The type of the list image.
@@ -67,12 +82,14 @@ export default class UiListItem extends UiElement {
   @state() accessor hasStartItem = false
   @state() accessor hasEndItem = false
   @state() accessor hasEndTextItem = false
+  @state() accessor hasOverline = false
+  @state() accessor hasSupportingText = false
 
   constructor() {
     super()
 
-    this.lines = ListItemLines.one
     this.image = ListItemImage.icon
+    this.lines = ListItemLines.one
 
     this.addEventListener('click', this.handleClick.bind(this))
     this.addEventListener('pointerdown', this.handlePointerDown.bind(this))
@@ -195,49 +212,57 @@ export default class UiListItem extends UiElement {
     this.removeAttribute('tabindex')
   }
 
-  protected handleStartSlotChange(): void {
-    const slot = this.shadowRoot?.querySelector<HTMLSlotElement>('slot[name="start"]')
-    if (slot) {
-      this.hasStartItem = slot.assignedNodes({ flatten: true }).length > 0
-    } else {
-      this.hasStartItem = false
-    }
+  private _handleSlotChange(event: Event): boolean {
+    const slot = event.target as HTMLSlotElement
+    return slot.assignedNodes({ flatten: true }).length > 0
+  }
+
+  protected handleOverlineSlotChange(event: Event): void {
+    this.hasOverline = this._handleSlotChange(event)
     this.requestUpdate()
   }
 
-  protected handleEndSlotChange(): void {
-    const slot = this.shadowRoot?.querySelector<HTMLSlotElement>('slot[name="end"]')
-    if (slot) {
-      this.hasEndItem = slot.assignedNodes({ flatten: true }).length > 0
-    } else {
-      this.hasEndItem = false
-    }
+  protected handleSupportingTextSlotChange(event: Event): void {
+    this.hasSupportingText = this._handleSlotChange(event)
     this.requestUpdate()
   }
 
-  protected handleEndTextSlotChange(): void {
-    const slot = this.shadowRoot?.querySelector<HTMLSlotElement>('slot[name="end-text"]')
-    if (slot) {
-      this.hasEndTextItem = slot.assignedNodes({ flatten: true }).length > 0
-    } else {
-      this.hasEndTextItem = false
-    }
+  protected handleStartSlotChange(event: Event): void {
+    this.hasStartItem = this._handleSlotChange(event)
+    this.requestUpdate()
+  }
+
+  protected handleEndSlotChange(event: Event): void {
+    this.hasEndItem = this._handleSlotChange(event)
     this.requestUpdate()
   }
 
+  protected handleEndTextSlotChange(event: Event): void {
+    this.hasEndTextItem = this._handleSlotChange(event)
+    this.requestUpdate()
+  }
+
+  getSurfaceClasses(): ClassInfo {
+    const result: ClassInfo = {
+      'surface': true,
+      'one-line': this.lines === ListItemLines.one,
+      'two-lines': this.lines === ListItemLines.two,
+      'three-lines': this.lines === ListItemLines.three,
+    }
+    return result
+  }
+
   protected override render(): TemplateResult {
-    const surfaceClasses = classMap({
-      surface: true,
-    })
     return html`
       ${this.renderFocusRing()} ${this.renderRipple()}
-      <div class="${surfaceClasses}">${this.renderStart()} ${this.renderBody()} ${this.renderEnd()}</div>
+      <div class="${classMap(this.getSurfaceClasses())}">
+        ${this.renderStart()} ${this.renderBody()} ${this.renderEnd()}
+      </div>
     `
   }
 
   protected renderRipple = (): TemplateResult => {
-    const { disabled, static: isStatic } = this
-    return html`<ui-ripple class="ripple" ?disabled="${disabled || isStatic}"></ui-ripple>`
+    return html`<ui-ripple class="ripple" ?disabled="${this.disabled || this.static}"></ui-ripple>`
   }
 
   protected renderFocusRing(): TemplateResult {
@@ -278,13 +303,13 @@ export default class UiListItem extends UiElement {
   }
 
   protected renderBody(): TemplateResult {
-    const { lines = ListItemLines.one } = this
-    const hasSupportingText = lines !== ListItemLines.one
     return html`
       <div class="body">
-        <slot name="overline"></slot>
+        <slot name="overline" @slotchange=${this.handleOverlineSlotChange}></slot>
         <span class="headline"><slot></slot></span>
-        ${hasSupportingText ? html`<span class="supporting-text"><slot name="supporting-text"></slot></span>` : ''}
+        <span class="supporting-text"
+          ><slot name="supporting-text" @slotchange=${this.handleSupportingTextSlotChange}></slot
+        ></span>
       </div>
     `
   }

package/src/md/select/internals/Option.ts

@@ -1,7 +1,7 @@
 import { html, PropertyValues, TemplateResult } from 'lit'
 import { property } from 'lit/decorators.js'
-import { classMap } from 'lit/directives/class-map.js'
-import UiListItem from '../../list/internals/ListItem.js'
+import { ClassInfo, classMap } from 'lit/directives/class-map.js'
+import UiListItem, { ListItemLines } from '../../list/internals/ListItem.js'
 import { nanoid } from 'nanoid'
 
 /**
@@ -89,11 +89,14 @@ export default class UiOption extends UiListItem {
     return content.join(' ').trim() || this.value || ''
   }
 
+  constructor() {
+    super()
+    this.lines = ListItemLines.auto
+  }
+
   /**
    * Initializes the option when it's connected to the DOM. Sets up ARIA attributes
    * and generates a unique ID if one isn't provided.
-   *
-   * @protected
    */
   override connectedCallback(): void {
     super.connectedCallback()
@@ -106,9 +109,6 @@ export default class UiOption extends UiListItem {
   /**
    * Handles property updates and triggers appropriate side effects.
    * Currently monitors the `selected` property to update selection state.
-   *
-   * @param {PropertyValues<this>} changedProperties - Map of changed properties
-   * @protected
    */
   protected override updated(changedProperties: PropertyValues<this>): void {
     super.updated(changedProperties)
@@ -143,7 +143,7 @@ export default class UiOption extends UiListItem {
    * Handles click events on the option. Prevents default behavior and dispatches
    * a custom 'select' event that the parent select component can listen to.
    *
-   * @param {MouseEvent} e - The click event
+   * @param e - The click event
    * @protected
    * @fires select - Custom event with option details in event.detail
    * @example
@@ -175,23 +175,11 @@ export default class UiOption extends UiListItem {
     )
   }
 
-  /**
-   * Renders the option's template. Creates the main structure with focus ring,
-   * ripple effect, and content areas.
-   *
-   * @returns {TemplateResult} The rendered template
-   * @protected
-   */
-  protected override render(): TemplateResult {
-    const surfaceClasses = classMap({
-      surface: true,
+  override getSurfaceClasses(): ClassInfo {
+    return {
+      ...super.getSurfaceClasses(),
       selected: this.selected,
-    })
-
-    return html`
-      ${this.renderFocusRing()} ${this.renderRipple()}
-      <div class="${surfaceClasses}">${this.renderStart()} ${this.renderBody()} ${this.renderEnd()}</div>
-    `
+    }
   }
 
   /**
@@ -200,10 +188,10 @@ export default class UiOption extends UiListItem {
    */
   protected override renderEnd(): TemplateResult {
     return html`
-      <div class="end">
+      <div class="${classMap(this.getEndClasses())}">
         ${this.selected ? html`<ui-icon icon="check" class="selection-icon"></ui-icon>` : ''}
         <slot name="end" @slotchange=${this.handleEndSlotChange}></slot>
-        <slot name="end-text" class="trailing-supporting-text"></slot>
+        <slot name="end-text" class="trailing-supporting-text" @slotchange=${this.handleEndTextSlotChange}></slot>
       </div>
     `
   }

package/src/md/select/internals/Select.ts

@@ -354,12 +354,17 @@ export default class UiSelect extends LitElement {
 
   protected override firstUpdated(cp: PropertyValues): void {
     super.firstUpdated(cp)
-    this.setCurrentOption()
-    this.#internals.setFormValue(this.value ?? null)
+    this.updateComplete.then(() => {
+      this.setCurrentOption()
+      this.#internals.setFormValue(this.value ?? null)
+      // We need to update here as event with `value` and `selectedOption`
+      // already set, the `renderValue` might have incorrect value
+      // due to the DOM update.
+      this.requestUpdate()
+    })
   }
 
-  protected async setCurrentOption(): Promise<void> {
-    await this.updateComplete
+  protected setCurrentOption(): void {
     const options = this.querySelectorAll<UiOption>('ui-option')
     if (this.value) {
       this.selectedOption = Array.from(options).find((option) => option.value === this.value) || null
@@ -459,6 +464,11 @@ export default class UiSelect extends LitElement {
     if (this.disabled || e.defaultPrevented) return
     e.preventDefault()
     e.stopPropagation()
+    if (this.open && e.target === this) {
+      // If the select is already open and clicked again, close it
+      this.open = false
+      return
+    }
     this.open = true
   }
 
@@ -560,7 +570,7 @@ export default class UiSelect extends LitElement {
     // When options change, re-evaluate the current selection
     // only if we don't have an explicit value set
     if (!this.value) {
-      await this.setCurrentOption()
+      this.setCurrentOption()
       this.requestUpdate()
     }
   }

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.