@api-client/ui 0.5.58 → 0.6.0

package/src/help/help_topic.ts

@@ -0,0 +1,61 @@
+/**
+ * Represents a link in the help topic, typically used for additional resources or documentation.
+ * Each link has a text label and a URL.
+ */
+export interface HelpLink {
+  /**
+   * Text to display for the link
+   */
+  text: string
+  /**
+   * URL to navigate to when the link is clicked
+   */
+  url: string
+}
+
+/**
+ * Represents an example in a help topic with optional title and content.
+ */
+export interface HelpExample {
+  /**
+   * Optional title for the example
+   */
+  title?: string
+  /**
+   * The example content, typically in Markdown format
+   */
+  value: string
+}
+
+/**
+ * Represents a help topic with structured content for user assistance.
+ * Each topic is categorized and can include examples and related links.
+ */
+export interface HelpTopic {
+  /**
+   * Identifier within the category, e.g., "name-input"
+   */
+  id: string
+  /**
+   * Category of the help topic, used for grouping and filtering
+   */
+  category: string
+  /**
+   * Title for the help panel header
+   */
+  title: string
+  /**
+   * Body content for the help topic, typically in Markdown format.
+   */
+  body: string
+  /**
+   * Optional examples content. Can be either:
+   * - A single string (legacy format for backward compatibility)
+   * - An array of objects with optional title and value properties
+   */
+  examples?: string | HelpExample[]
+  /**
+   * Optional array of related links, each with text and URL
+   */
+  links?: HelpLink[]
+}

package/src/help/index.ts

@@ -0,0 +1,8 @@
+// Main help system exports
+export { renderHelp } from './render.js'
+export { HelpServiceController } from './help_service_controller.js'
+export { HelpCoordinator } from './help_coordinator.js'
+export { HelpPanel } from './help_panel.js'
+
+// Type exports
+export type { HelpTopic, HelpLink } from './help_topic.js'

package/src/help/render.ts

@@ -0,0 +1,41 @@
+import { type TemplateResult, html } from 'lit'
+import type { HelpRequestDetail } from './help_coordinator.js'
+
+import '../md/icons/ui-icon.js'
+import '../md/icon-button/ui-icon-button.js'
+
+/**
+ * Renders a help icon with a button that can be used to trigger help functionality.
+ * The help system lives outside the application and renders the help content in a node controlled
+ * by the help system.
+ *
+ * @param category The category of the help content, which determines where to look for the help content.
+ * @param id The identifier for the specific help content within the category.
+ * @returns The template result containing the help icon button.
+ */
+export function renderHelp(category: string, id: string): TemplateResult {
+  const handleClick = (event: Event) => {
+    const button = event.currentTarget as HTMLElement
+    const { category, id } = button.dataset
+    if (!category || !id) {
+      return
+    }
+    const detail: HelpRequestDetail = {
+      category,
+      id,
+      target: button,
+    }
+    button.dispatchEvent(
+      new CustomEvent('request-help', {
+        bubbles: true,
+        composed: true,
+        detail,
+      })
+    )
+  }
+  return html`<span class="help"
+    ><ui-icon-button type="button" data-category="${category}" data-id="${id}" @click="${handleClick}"
+      ><ui-icon>help</ui-icon></ui-icon-button
+    ></span
+  >`
+}

package/src/lib/Dom.ts

@@ -1,3 +1,5 @@
+import { CSSResultOrNative } from 'lit'
+
 /**
  * Searches for an element with the given ID in parent shadow roots
  */
@@ -39,3 +41,37 @@ export function findElementInShadowRoots(id: string, from: HTMLElement): HTMLEle
 
   return null
 }
+
+const adoptedStyles = new WeakSet<CSSResultOrNative>()
+
+/**
+ * Adopts the provided styles into the document.
+ *
+ * @param styles - The styles to adopt.
+ */
+export function adoptStyles(...styles: CSSResultOrNative[]): void {
+  if (typeof document === 'undefined' || !('adoptedStyleSheets' in document)) {
+    // Constructable stylesheets are not supported in this environment.
+    return
+  }
+  const sheets: CSSStyleSheet[] = []
+  for (const style of styles) {
+    if (adoptedStyles.has(style)) {
+      continue
+    }
+    if (style instanceof CSSStyleSheet) {
+      adoptedStyles.add(style)
+      sheets.push(style)
+    } else if (style && typeof style === 'object' && 'styleSheet' in style) {
+      const styleSheet = (style as { styleSheet?: CSSStyleSheet }).styleSheet
+      if (styleSheet instanceof CSSStyleSheet) {
+        adoptedStyles.add(style)
+        sheets.push(styleSheet)
+      }
+    }
+  }
+  if (sheets.length === 0) {
+    return
+  }
+  document.adoptedStyleSheets = [...document.adoptedStyleSheets, ...sheets]
+}

package/src/lib/files/Utils.ts

@@ -1,3 +1,21 @@
+import { SVGTemplateResult } from 'lit'
+import {
+  schemaModel as schemaIcon,
+  folderFilled as folderIcon,
+  api as apiIcon,
+  collectionsBookmark,
+  certificate,
+} from '../../md/icons/Icons.js'
+import type { IFile } from '@api-client/core/models/store/File.js'
+import {
+  ApiFileKind,
+  CertificateFileKind,
+  DomainFileKind,
+  FolderKind,
+  ProjectKind,
+} from '@api-client/core/models/kinds.js'
+import type { TrashEntry } from '@api-client/core/models/TrashEntry.js'
+
 /**
  * Reads the last segment of the file path and returns it as a file name.
  *
@@ -8,3 +26,50 @@ export function getFileName(path: string): string {
   const last = path.split(delimiter).pop()
   return last || ''
 }
+
+/**
+ * Sorts files on the list.
+ *
+ * Folders are always on top.
+ */
+export function filesSortFunction(a: IFile, b: IFile): number {
+  if (a.kind !== b.kind) {
+    if (a.kind === FolderKind) {
+      return -1
+    }
+    return 1
+  }
+  if (a.kind === b.kind && a.kind === FolderKind) {
+    if (!a.info) {
+      return -1
+    }
+    if (!b.info) {
+      return 1
+    }
+    return (a.info.name || '').localeCompare(b.info.name || '')
+  }
+  return b.lastModified.time - a.lastModified.time
+}
+
+export function fileIcon(item: IFile | TrashEntry): SVGTemplateResult | undefined {
+  let icon: SVGTemplateResult | undefined
+  switch (item.kind) {
+    case DomainFileKind:
+      icon = schemaIcon
+      break
+    case FolderKind:
+      icon = folderIcon
+      break
+    case ApiFileKind:
+      icon = apiIcon
+      break
+    case ProjectKind:
+      icon = collectionsBookmark
+      break
+    case CertificateFileKind:
+      icon = certificate
+      break
+    default:
+  }
+  return icon
+}

package/src/md/button/internals/base.ts

@@ -147,6 +147,11 @@ export default class BaseButton extends UiElement {
    *   "toggle" is the default action that will be performed by the control button.
    */
   @property({ type: String, reflect: true }) accessor popoverTargetAction: string | undefined
+  /**
+   * When true, the focus ring effect will be constrained to the inside of the button's bounds.
+   * @attribute
+   */
+  @property({ type: Boolean }) accessor inwardFocus: boolean | undefined
 
   constructor() {
     super()
@@ -242,7 +247,6 @@ export default class BaseButton extends UiElement {
   }
 
   override handleClick(e: MouseEvent): void {
-    // Do not call super.handleClick() here, as it would call `endPress` again.
     if (this.disabled) {
       e.preventDefault()
       e.stopPropagation()
@@ -260,7 +264,10 @@ export default class BaseButton extends UiElement {
       this.dispatchEvent(e)
     }
     this.handlePopoverAction()
-    this.endPress({ cancelled: false, actionData: { event: e } })
+    // Delegate to ActionController to properly end the press and reset phase
+    // state; this removes the 'pressed' class via endPress() and ensures
+    // subsequent pointerdown events work again.
+    super.handleClick(e)
   }
 
   protected setupPopoverTarget(): void {
@@ -370,7 +377,12 @@ export default class BaseButton extends UiElement {
   }
 
   protected renderFocusRing(): TemplateResult {
-    return html`<ui-focus-ring part="focus-ring" class="focus-ring" .control="${this as HTMLElement}"></ui-focus-ring>`
+    return html`<ui-focus-ring
+      part="focus-ring"
+      class="focus-ring"
+      .control="${this}"
+      ?inward="${this.inwardFocus}"
+    ></ui-focus-ring>`
   }
 
   protected renderRipple(): TemplateResult {

package/src/md/dropdown-list/internals/UiDropdownList.ts

@@ -130,6 +130,7 @@ export default class UiDropdownList extends LitElement {
     this.dropdownOpenHandler = this.dropdownOpenHandler.bind(this)
     this.scrollHandler = this.scrollHandler.bind(this)
     this.clickHandler = this.clickHandler.bind(this)
+    this.verticalAlign = 'auto'
   }
 
   override connectedCallback(): void {
@@ -165,7 +166,10 @@ export default class UiDropdownList extends LitElement {
 
   protected override updated(cp: PropertyValues<this>): void {
     super.updated(cp)
-    if (cp.has('open')) {
+    if (cp.has('open') && cp.get('open') !== undefined) {
+      // When undefined then the component is initializing.
+      // In that case, we don't want to trigger opened/closed handlers since
+      // they manage focus.
       this.toggleOpened()
       this.updateExpanded()
       // this.manageTabindex()
@@ -230,6 +234,11 @@ export default class UiDropdownList extends LitElement {
   }
 
   protected contentKeyDownHandler(e: KeyboardEvent): void {
+    if (['Enter', 'Space'].includes(e.code)) {
+      // The UiList cancels the event when an item is selected
+      this.activate(e)
+      return
+    }
     if (e.defaultPrevented) {
       return
     }
@@ -239,8 +248,6 @@ export default class UiDropdownList extends LitElement {
       if (this.closeOnTab) {
         this.close()
       }
-    } else if (['Enter', 'Space'].includes(e.code)) {
-      this.activate(e)
     }
   }
 
@@ -332,7 +339,7 @@ export default class UiDropdownList extends LitElement {
       // const activeChild = dropdown.querySelector(':focus') || dropdown
       // this.lastActiveChild = activeChild as HTMLElement
       // activeChild.removeAttribute('tabindex')
-      // this.trigger?.focus()
+      this.trigger?.focus()
     }
   }
 

package/src/md/icons/Icons.ts

@@ -54,6 +54,7 @@ export type IconType =
   | 'personAdd'
   | 'playArrow'
   | 'project'
+  | 'questionMark'
   | 'remove'
   | 'rename'
   | 'request'
@@ -209,6 +210,13 @@ export const project = iconWrapper(
   192,
   192
 )
+export const questionMark = iconWrapper(
+  svg`<path d="M424-320q0-81 14.5-116.5T500-514q41-36 62.5-62.5T584-637q0-41-27.5-68T480-732q-51 0-77.5 31T365-638l-103-44q21-64 77-111t141-47q105 0 161.5 58.5T698-641q0 50-21.5 85.5T609-475q-49 47-59.5 71.5T539-320H424Zm56 240q-33 0-56.5-23.5T400-160q0-33 23.5-56.5T480-240q33 0 56.5 23.5T560-160q0 33-23.5 56.5T480-80Z"/>`,
+  960,
+  960,
+  0,
+  -960
+)
 export const remove = iconWrapper(svg`<path d="M0 0h24v24H0V0z" fill="none"/><path d="M19 13H5v-2h14v2z"/>`)
 export const rename = iconWrapper(
   svg`<g><rect fill="none" height="24" width="24"/></g><g><g><polygon points="15,16 11,20 21,20 21,16"/><path d="M12.06,7.19L3,16.25V20h3.75l9.06-9.06L12.06,7.19z M5.92,18H5v-0.92l7.06-7.06l0.92,0.92L5.92,18z"/><path d="M18.71,8.04c0.39-0.39,0.39-1.02,0-1.41l-2.34-2.34C16.17,4.09,15.92,4,15.66,4c-0.25,0-0.51,0.1-0.7,0.29l-1.83,1.83 l3.75,3.75L18.71,8.04z"/></g></g>`

package/src/md/input/Input.ts

@@ -866,7 +866,7 @@ export default abstract class Input extends UiElement {
     return html`
       <div class="${containerClasses}">
         <div class="container"></div>
-        <div class="content">
+        <div class="content" part="content">
           ${this.renderPrefix()} ${this.renderBody()} ${this.renderPasswordControl()} ${this.renderSuffix()}
           ${this.renderHighlight()}
         </div>
@@ -880,7 +880,7 @@ export default abstract class Input extends UiElement {
       start: true,
       prefixed: this.hasPrefix,
     })
-    return html` <div class="${classes}">
+    return html`<div class="${classes}" part="prefix">
       <slot name="prefix" @slotchange=${this.handleSlotChange}></slot>
     </div>`
   }
@@ -890,13 +890,13 @@ export default abstract class Input extends UiElement {
       end: true,
       suffixed: this.hasSuffix,
     })
-    return html` <div class="${classes}">
+    return html`<div class="${classes}" part="suffix">
       <slot name="suffix" @slotchange=${this.handleSlotChange}></slot>
     </div>`
   }
 
   protected renderBody(): TemplateResult {
-    return html` <div class="body">${this.renderLabel()} ${this.renderInput()}</div> `
+    return html`<div class="body" part="body">${this.renderLabel()} ${this.renderInput()}</div>`
   }
 
   protected renderLabel(): TemplateResult {
@@ -904,17 +904,19 @@ export default abstract class Input extends UiElement {
     if (!label) {
       return html``
     }
-    return html` <span class="label" id="${this.labelId}" title="label">${label}</span> `
+    return html`<span class="label" id="${this.labelId}" title="${label}" part="label">${label}</span>`
   }
 
   protected renderHighlight(): TemplateResult {
-    return html` <span class="highlight"></span> `
+    return html`<span class="highlight"></span>`
   }
 
   protected abstract renderInput(): TemplateResult
 
   protected renderSupportingText(): TemplateResult {
-    return html` <span class="supporting-text"> ${this.renderSupportingTextValue()} ${this.renderCounter()} </span> `
+    return html` <span class="supporting-text" part="supporting-text"
+      >${this.renderSupportingTextValue()} ${this.renderCounter()}</span
+    >`
   }
 
   protected renderSupportingTextValue(): TemplateResult | typeof nothing {
@@ -939,7 +941,9 @@ export default abstract class Input extends UiElement {
       return html``
     }
     // TODO: add aria-label and announcements
-    return html`<span id=${this.counterId} class="supporting-text-end">${this.getCounterText()}</span>`
+    return html`<span id=${this.counterId} class="supporting-text-end" part="supporting-text-end"
+      >${this.getCounterText()}</span
+    >`
   }
 
   protected renderPasswordControl(): TemplateResult | typeof nothing {
@@ -954,6 +958,7 @@ export default abstract class Input extends UiElement {
         aria-label="Toggle password visibility"
         @click="${this.#handlePasswordToggle}"
         title="Shows or hides the password"
+        part="password-toggle"
       >
         <ui-icon icon="${icon}"></ui-icon>
       </ui-icon-button>
@@ -965,6 +970,6 @@ export default abstract class Input extends UiElement {
     if (!Array.isArray(list) || !list.length) {
       return nothing
     }
-    return html` <datalist id="input-list">${list.map((i) => html`<option value="${i}"></option>`)}</datalist> `
+    return html`<datalist id="input-list">${list.map((i) => html`<option value="${i}"></option>`)}</datalist>`
   }
 }

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

@@ -56,6 +56,15 @@ export default class UiList extends LitElement {
 
   @queryAssignedElements({ flatten: true }) protected accessor assignedElements!: HTMLElement[]
 
+  /**
+   * When set it delegates focus to the active child of a list item.
+   * Used when the list has input controls like checkboxes or switches.
+   * When set, the list behaves like a regular HTML (but styled) listbox
+   * and does not manage focus on its own.
+   * @attribute
+   */
+  @property({ type: Boolean }) accessor delegateFocus: boolean | undefined
+
   constructor() {
     super()
     this.selector = 'ui-list-item'
@@ -66,7 +75,7 @@ export default class UiList extends LitElement {
 
   override connectedCallback(): void {
     super.connectedCallback()
-    if (!this.hasAttribute('tabindex')) {
+    if (!this.hasAttribute('tabindex') && !this.delegateFocus) {
       this.setAttribute('tabindex', '0')
     }
   }
@@ -115,6 +124,10 @@ export default class UiList extends LitElement {
     const elements = this.assignedElements || []
     const items = elements.filter(this.isListItem, this)
     this.items = items
+    if (this.delegateFocus) {
+      // remove tabindex from the list and items
+      items.forEach((item) => item.removeAttribute('tabindex'))
+    }
     if (this.activeListItem && !items.includes(this.activeListItem)) {
       this.activeListItem = null
     }
@@ -227,6 +240,9 @@ export default class UiList extends LitElement {
   }
 
   handleKeydown(event: KeyboardEvent): void {
+    if (this.delegateFocus) {
+      return
+    }
     if (Object.values(ACTIVATION_KEYS).includes(event.key)) {
       this.activateFromEvent(event)
       return

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

@@ -123,22 +123,24 @@ export default class UiListItem extends UiElement {
   }
 
   override handleKeyDown(e: KeyboardEvent): void {
-    if (this.disabled || this.static) {
+    if (this.disabled) {
       e.stopPropagation()
       e.preventDefault()
       return
     }
+    if (this.static) return
     if (e.key !== ' ' && e.key !== 'Enter') return
     // do not prevent default, so that parent elements can handle the key event
     this.beginPress({ positionEvent: e })
   }
 
   override handleKeyUp(e: KeyboardEvent): void {
-    if (this.disabled || this.static) {
+    if (this.disabled) {
       e.stopPropagation()
       e.preventDefault()
       return
     }
+    if (this.static) return
     if (e.key !== ' ' && e.key !== 'Enter') return
 
     // do not prevent default, so that parent elements can handle the key event
@@ -255,14 +257,14 @@ export default class UiListItem extends UiElement {
   protected override render(): TemplateResult {
     return html`
       ${this.renderFocusRing()} ${this.renderRipple()}
-      <div class="${classMap(this.getSurfaceClasses())}">
+      <div class="${classMap(this.getSurfaceClasses())}" part="surface">
         ${this.renderStart()} ${this.renderBody()} ${this.renderEnd()}
       </div>
     `
   }
 
   protected renderRipple(): TemplateResult {
-    return html`<ui-ripple class="ripple" ?disabled="${this.disabled || this.static}"></ui-ripple>`
+    return html`<ui-ripple part="ripple" class="ripple" ?disabled="${this.disabled || this.static}"></ui-ripple>`
   }
 
   protected renderFocusRing(): TemplateResult {

package/src/md/menu/internal/Menu.styles.ts

@@ -34,9 +34,11 @@ export default css`
   :host(:popover-open) {
     display: block;
     background-color: var(--md-sys-color-surface-container);
-    border-radius: var(--md-sys-shape-corner-extra-small);
-    box-shadow: var(--md-sys-elevation-3);
+    /* border-radius: var(--md-sys-shape-corner-extra-small);
+    box-shadow: var(--md-sys-elevation-3); */
     animation: menu-scale-in 0.15s cubic-bezier(0.4, 0, 0.2, 1) forwards;
+    box-shadow: var(--md-sys-elevation-1);
+    border-radius: var(--md-sys-shape-corner-medium);
   }
 
   /* Scale animation for menus positioned below the anchor */

package/src/md/menu/internal/Menu.ts

@@ -112,7 +112,7 @@ export default class Menu extends UiList {
     super.showPopover()
     this.open = true
     this.focus()
-    this.dispatchEvent(new CustomEvent('open', { bubbles: false, composed: true }))
+    this.dispatchEvent(new CustomEvent('open'))
   }
 
   /**
@@ -124,7 +124,7 @@ export default class Menu extends UiList {
     super.hidePopover()
     this.open = false
     this.closeSubMenu()
-    this.dispatchEvent(new CustomEvent('close', { bubbles: false, composed: true }))
+    this.dispatchEvent(new CustomEvent('close'))
   }
 
   positionMenu(): void {

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

@@ -9,6 +9,8 @@ export default css`
     --md-focus-ring-shape-end-start: var(--md-sys-shape-corner-extra-small);
     --md-focus-ring-shape-start-end: var(--md-sys-shape-corner-extra-small);
     --md-focus-ring-shape-start-start: var(--md-sys-shape-corner-extra-small);
+    /* Same as text input */
+    min-width: 200px;
   }
 
   .ui-select {
@@ -21,5 +23,6 @@ export default css`
   .input {
     cursor: default;
     flex: 1;
+    min-width: inherit;
   }
 `

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

@@ -526,10 +526,10 @@ export default class UiSelect extends UiElement {
           firstSelectableOption.scrollIntoView({ behavior: 'instant', block: 'nearest', inline: 'nearest' })
         }
       }
-      this.dispatchEvent(new CustomEvent('open', { bubbles: false, composed: true }))
+      this.dispatchEvent(new CustomEvent('open'))
     } else {
       menu.hidePopover()
-      this.dispatchEvent(new CustomEvent('close', { bubbles: false, composed: true }))
+      this.dispatchEvent(new CustomEvent('close'))
       // Return focus to the select element when menu closes
       this.focus()
     }
@@ -739,16 +739,10 @@ export default class UiSelect extends UiElement {
     this.#value = option.value
     this.#internals.setFormValue(this.value ?? null)
 
-    // Dispatch change event
-    const changeEvent = new CustomEvent<UiSelectChangeEvent>('change', {
-      detail: { value: this.value, item: option },
-      bubbles: false,
-      composed: true,
-    })
-    this.dispatchEvent(changeEvent)
+    this.dispatchChangeEvent(option)
   }
 
-  handleSelect(e: CustomEvent<{ item: UiOption }>): void {
+  protected handleSelect(e: CustomEvent<{ item: UiOption }>): void {
     e.stopPropagation()
     const item = e.detail.item
     if (this.selectedOption && this.selectedOption !== item) {
@@ -761,26 +755,30 @@ export default class UiSelect extends UiElement {
     this.open = false
 
     // Dispatch change event
-    const changeEvent = new CustomEvent<UiSelectChangeEvent>('change', {
-      detail: { value: this.value, item: item },
-      bubbles: false,
-      composed: true,
-    })
-    this.dispatchEvent(changeEvent)
+    this.dispatchChangeEvent(item)
     // Focus will be returned to select element by handleOpenChange when open=false
   }
 
-  handleMenuClose(): void {
+  protected handleMenuClose(): void {
     this.open = false
     // Focus will be returned to select element by handleOpenChange when open=false
   }
 
-  handleMenuToggle(e: ToggleEvent): void {
+  protected handleMenuToggle(e: ToggleEvent): void {
     if (e.newState === 'closed') {
       this.open = false
     }
   }
 
+  protected dispatchChangeEvent(item: UiOption): void {
+    const changeEvent = new CustomEvent<UiSelectChangeEvent>('change', {
+      detail: { value: this.value, item },
+      bubbles: false,
+      composed: false,
+    })
+    this.dispatchEvent(changeEvent)
+  }
+
   protected renderInput(): TemplateResult {
     const styles = {
       'anchor-name': `--${this.id}`,

package/src/md/switch/internals/SwitchElement.ts

@@ -59,13 +59,13 @@ export default class SwitchElement extends CheckedElement {
 
   protected override render(): TemplateResult {
     const { pressed = false, _rendersIcons } = this
-    const surfaceClasses = classMap({
+    const surfaceClasses = {
       surface: true,
       pressed,
       withIcon: _rendersIcons,
-    })
+    }
     return html`
-      <div class="${surfaceClasses}">
+      <div class="${classMap(surfaceClasses)}">
         <div class="container track"></div>
         <div class="state"></div>
         <div class="content">