@api-client/ui 0.5.32 → 0.5.34

package/package.json

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

package/src/core/ApplicationRoute.ts

@@ -34,7 +34,10 @@ function parseParams(pattern: string, uri: string): Record<string, string | stri
   const result: Record<string, string | string[]> = {}
   if (groups) {
     Object.keys(groups).forEach((key) => {
-      let value = groups[key] as string
+      let value = groups[key] as string | undefined
+      if (value === undefined) {
+        return
+      }
       if (value[0] === '/') {
         value = value.substring(1)
       }

package/src/elements/navigation/internals/Navigation.styles.ts

@@ -0,0 +1,24 @@
+import { css } from 'lit'
+
+export default css`
+  :host {
+    display: block;
+    outline: none;
+  }
+
+  nav {
+    display: flex;
+    gap: 8px;
+    list-style: none;
+    padding: 0;
+    margin: 0;
+  }
+
+  :host([orientation='horizontal']) nav {
+    flex-direction: row;
+  }
+
+  :host([orientation='vertical']) nav {
+    flex-direction: column;
+  }
+`

package/src/elements/navigation/internals/Navigation.ts

@@ -0,0 +1,181 @@
+import { html, LitElement, type TemplateResult } from 'lit'
+import { property, queryAssignedElements } from 'lit/decorators.js'
+import type NavigationItem from './NavigationItem.js'
+import { AriaCurrent } from '../../../types/aria.js'
+
+/**
+ * NavigationList
+ *
+ * A semantic, accessible navigation container for `ui-navigation-item` elements.
+ * Handles keyboard navigation (roving tabindex), focus management, and ARIA roles.
+ *
+ * ## Usage Example
+ *
+ * ```html
+ * <ui-navigation aria-label="Main navigation" current="page">
+ *   <ui-navigation-item selected>
+ *     <span slot="icon" aria-hidden="true">🏠</span>
+ *     Home
+ *   </ui-navigation-item>
+ *   <ui-navigation-item>
+ *     <span slot="icon" aria-hidden="true">🔍</span>
+ *     Search
+ *   </ui-navigation-item>
+ *   <ui-navigation-item>
+ *     <span slot="icon" aria-hidden="true">📁</span>
+ *     Files
+ *   </ui-navigation-item>
+ *   <ui-navigation-item iconOnly disabled aria-disabled="true" tabindex="-1">
+ *     <span slot="icon" aria-hidden="true">⚙️</span>
+ *   </ui-navigation-item>
+ * </ui-navigation>
+ * ```
+ *
+ * @slot - Place `ui-navigation-item` elements as direct children.
+ * @fires select - Dispatched when an item is selected via click or keyboard.
+ *                 The `detail` object contains the selected `item`.
+ */
+export default class Navigation extends LitElement {
+  /**
+   * Orientation of the navigation: 'horizontal' or 'vertical'.
+   * @attribute
+   */
+  @property({ type: String, reflect: true }) accessor orientation: 'horizontal' | 'vertical' = 'vertical'
+
+  /**
+   * The current item in the navigation, used for ARIA attributes.
+   * Can be 'page', 'step', 'location', 'date', 'time', 'true', 'false', or ''.
+   * @attribute
+   */
+  @property({ type: String, reflect: true }) accessor current: AriaCurrent = ''
+
+  /**
+   * Query all ui-navigation-item children
+   */
+  @queryAssignedElements({ flatten: true }) accessor _items!: NavigationItem[]
+
+  override render(): TemplateResult {
+    return html`
+      <nav aria-label="${this.getAttribute('aria-label') || 'Navigation'}">
+        <slot @slotchange="${this._onSlotChange}"></slot>
+      </nav>
+    `
+  }
+
+  constructor() {
+    super()
+    this.addEventListener('keydown', this._onKeyDown.bind(this))
+    this.addEventListener('click', this._onClick.bind(this))
+  }
+
+  override firstUpdated() {
+    this._setTabIndexes()
+  }
+
+  private _onSlotChange = () => {
+    this._setTabIndexes()
+  }
+
+  /**
+   * Sets the initial `tabindex` for the items. The first selected item,
+   * or the first item if none are selected, receives `tabindex="0"`.
+   * All other items receive `tabindex="-1"`.
+   */
+  private _setTabIndexes() {
+    const items = this._getEnabledItems()
+    if (!items.length) {
+      return
+    }
+    items.forEach((item) => {
+      if (item.disabled) {
+        return
+      }
+      item.setAttribute('tabindex', item.selected ? '0' : '-1')
+    })
+  }
+
+  private _getEnabledItems(): NavigationItem[] {
+    return (this._items || []).filter((item) => !item.disabled)
+  }
+
+  private _onClick = (e: MouseEvent) => {
+    const target = e.target as HTMLElement
+    const item = target.closest('ui-navigation-item')
+    if (item && this._items.includes(item)) {
+      this._selectItem(item)
+    }
+  }
+
+  private _selectItem(itemToSelect: NavigationItem) {
+    if (itemToSelect.disabled) {
+      return
+    }
+
+    this._items.forEach((item) => {
+      item.selected = item === itemToSelect
+      if (item.hasAttribute('aria-current')) {
+        item.removeAttribute('aria-current')
+      }
+    })
+
+    if (this.current) {
+      itemToSelect.setAttribute('aria-current', this.current)
+    }
+    this._updateFocus(itemToSelect)
+
+    this.dispatchEvent(
+      new CustomEvent('select', {
+        detail: { item: itemToSelect },
+        bubbles: false,
+        composed: true,
+      })
+    )
+  }
+
+  private _updateFocus(itemToFocus: NavigationItem) {
+    this._setTabIndexes()
+    itemToFocus.focus()
+  }
+
+  private _onKeyDown(e: KeyboardEvent) {
+    const items = this._getEnabledItems()
+    if (!items.length) {
+      return
+    }
+
+    const activeElement = (this.getRootNode() as Document | ShadowRoot).activeElement
+    if (!activeElement) {
+      return
+    }
+
+    // Find which of our items is the host of the active element.
+    // This is necessary because of focus delegation in ui-navigation-item.
+    const activeItem = items.find((item) => item === activeElement || item.shadowRoot?.contains(activeElement))
+    if (!activeItem) {
+      return
+    }
+
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      this._selectItem(activeItem)
+      return
+    }
+
+    const idx = items.indexOf(activeItem)
+    let nextIdx = idx
+    if (this.orientation === 'horizontal') {
+      if (e.key === 'ArrowRight') nextIdx = (idx + 1) % items.length
+      if (e.key === 'ArrowLeft') nextIdx = (idx - 1 + items.length) % items.length
+    } else {
+      if (e.key === 'ArrowDown') nextIdx = (idx + 1) % items.length
+      if (e.key === 'ArrowUp') nextIdx = (idx - 1 + items.length) % items.length
+    }
+    if (e.key === 'Home') nextIdx = 0
+    if (e.key === 'End') nextIdx = items.length - 1
+    if (nextIdx !== idx) {
+      items[nextIdx].focus()
+      items.forEach((item, i) => item.setAttribute('tabindex', i === nextIdx ? '0' : '-1'))
+      e.preventDefault()
+    }
+  }
+}

package/src/elements/navigation/internals/NavigationItem.ts

@@ -1,19 +1,84 @@
-import { html, TemplateResult } from 'lit'
+import { html, TemplateResult, nothing } from 'lit'
 import { property, state } from 'lit/decorators.js'
 import { classMap } from 'lit/directives/class-map.js'
+import { when } from 'lit/directives/when.js'
 import { UiElement } from '../../../md/UiElement.js'
+import { isDisabled, setDisabled } from '../../../lib/disabled.js'
 
+/**
+ * NavigationItem
+ *
+ * An element to be placed inside a navigation bar. This component is designed for use with navigation bars and supports
+ * icon-only, selected, and disabled states. It is built with accessibility and composability in mind.
+ *
+ * ## Accessibility
+ *
+ * - Uses a native `<button>` element for proper semantics and keyboard accessibility.
+ * - The icon is marked with `role="presentation"` to indicate it is decorative.
+ * - Focus ring and ripple effects are included for visual feedback.
+ *
+ * ## Usage Example
+ *
+ * ### Accessible Navigation Example
+ *
+ * ```html
+ * <nav aria-label="Main navigation">
+ *   <ul style="display: flex; gap: 8px; list-style: none; padding: 0; margin: 0;">
+ *     <li>
+ *       <navigation-item selected aria-current="page">
+ *         <span slot="icon" aria-hidden="true">🏠</span>
+ *         Home
+ *       </navigation-item>
+ *     </li>
+ *     <li>
+ *       <navigation-item>
+ *         <span slot="icon" aria-hidden="true">🔍</span>
+ *         Search
+ *       </navigation-item>
+ *     </li>
+ *     <li>
+ *       <navigation-item>
+ *         <span slot="icon" aria-hidden="true">📁</span>
+ *         Files
+ *       </navigation-item>
+ *     </li>
+ *     <li>
+ *       <navigation-item iconOnly disabled aria-disabled="true" tabindex="-1">
+ *         <span slot="icon" aria-hidden="true">⚙️</span>
+ *       </navigation-item>
+ *     </li>
+ *   </ul>
+ * </nav>
+ * ```
+ *
+ * This example demonstrates a horizontal navigation bar using semantic HTML. Each `navigation-item`
+ * is placed inside a list item for proper structure. The `aria-current="page"` attribute marks the current
+ * page, and `aria-disabled="true"` with `tabindex="-1"` ensures the disabled item is not focusable.
+ * Icons use `aria-hidden="true"` for accessibility.
+ *
+ * @slot icon - A slot for the icon element
+ * @slot - The default slot for the label
+ */
 export default class NavigationItem extends UiElement {
   static override shadowRootOptions: ShadowRootInit = {
     mode: 'open',
     delegatesFocus: true,
   }
 
+  get disabled(): boolean {
+    return isDisabled(this)
+  }
+
   /**
-   * When set, the button is a disabled state.
+   * When set, the navigation item is in a disabled state.
    * @attribute
    */
-  @property({ reflect: true, type: Boolean }) accessor disabled = false
+  @property({ reflect: true, type: Boolean })
+  set disabled(value: boolean) {
+    const old = isDisabled(this)
+    setDisabled(this, value)
+    this.requestUpdate('disabled', old)
+  }
 
   /**
    * Whether the navigation item is selected.
@@ -26,6 +91,11 @@ export default class NavigationItem extends UiElement {
    * @attribute
    */
   @property({ reflect: true, type: Boolean }) accessor iconOnly = false
+  /**
+   * The reference of the navigation item to the target.
+   * @attribute
+   */
+  @property({ reflect: true, type: String }) accessor href: string | undefined
 
   /**
    * Determines when the element has an icon in the "icon" slot.
@@ -49,10 +119,14 @@ export default class NavigationItem extends UiElement {
       'icon-only': this.iconOnly,
     })
     return html`
-      <button class="${containerClasses}" id="button">
+      <button class="${containerClasses}" id="button" ?disabled="${this.disabled}" aria-disabled="${this.disabled}">
         <md-focus-ring part="focus-ring" for="button"></md-focus-ring>
         <md-ripple></md-ripple>
-        ${this.renderIcon()}${this.iconOnly ? '' : html`<slot></slot>`}
+        ${this.renderIcon()}${when(
+          this.iconOnly,
+          () => nothing,
+          () => html`<slot></slot>`
+        )}
       </button>
     `
   }

package/src/elements/navigation/ui-navigation.ts

@@ -0,0 +1,15 @@
+import type { CSSResultOrNative } from 'lit'
+import { customElement } from 'lit/decorators.js'
+import Element from './internals/Navigation.js'
+import styles from './internals/Navigation.styles.js'
+
+@customElement('ui-navigation')
+export class NavigationListElement extends Element {
+  static override styles: CSSResultOrNative[] = [styles]
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ui-navigation': NavigationListElement
+  }
+}

package/src/types/aria.ts

@@ -0,0 +1,141 @@
+/**
+ * - `page` - Represents the current page within a set of pages.
+ * - `step` - Represents the current step within a process.
+ * - `location` - Represents the current location, for example the current page in a breadcrumbs hierarchy.
+ * - `date` - Represents the current date within a collection of dates.
+ * - `time` - Represents the current time within a set of times.
+ * - `true` - Represents the current item within a set.
+ * - `false` - Does not represent the current item within a set.
+ * - `''` - No current state.
+ */
+export type AriaCurrent = 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false' | ''
+
+/**
+ * Valid values for `aria-expanded`.
+ */
+export type ARIAAutoComplete = 'none' | 'inline' | 'list' | 'both'
+
+/**
+ * Valid values for `aria-expanded`.
+ */
+export type ARIAExpanded = 'true' | 'false'
+
+/**
+ * Valid values for `aria-haspopup`.
+ */
+export type ARIAHasPopup = 'false' | 'true' | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog'
+
+/**
+ * Valid values for `role`.
+ */
+export type ARIARole =
+  | 'alert'
+  | 'alertdialog'
+  | 'button'
+  | 'checkbox'
+  | 'dialog'
+  | 'gridcell'
+  | 'link'
+  | 'log'
+  | 'marquee'
+  | 'menuitem'
+  | 'menuitemcheckbox'
+  | 'menuitemradio'
+  | 'option'
+  | 'progressbar'
+  | 'radio'
+  | 'scrollbar'
+  | 'searchbox'
+  | 'slider'
+  | 'spinbutton'
+  | 'status'
+  | 'switch'
+  | 'tab'
+  | 'tabpanel'
+  | 'textbox'
+  | 'timer'
+  | 'tooltip'
+  | 'treeitem'
+  | 'combobox'
+  | 'grid'
+  | 'listbox'
+  | 'menu'
+  | 'menubar'
+  | 'radiogroup'
+  | 'tablist'
+  | 'tree'
+  | 'treegrid'
+  | 'application'
+  | 'article'
+  | 'cell'
+  | 'columnheader'
+  | 'definition'
+  | 'directory'
+  | 'document'
+  | 'feed'
+  | 'figure'
+  | 'group'
+  | 'heading'
+  | 'img'
+  | 'list'
+  | 'listitem'
+  | 'math'
+  | 'none'
+  | 'note'
+  | 'presentation'
+  | 'region'
+  | 'row'
+  | 'rowgroup'
+  | 'rowheader'
+  | 'separator'
+  | 'table'
+  | 'term'
+  | 'text'
+  | 'toolbar'
+  | 'banner'
+  | 'complementary'
+  | 'contentinfo'
+  | 'form'
+  | 'main'
+  | 'navigation'
+  | 'region'
+  | 'search'
+  | 'doc-abstract'
+  | 'doc-acknowledgments'
+  | 'doc-afterword'
+  | 'doc-appendix'
+  | 'doc-backlink'
+  | 'doc-biblioentry'
+  | 'doc-bibliography'
+  | 'doc-biblioref'
+  | 'doc-chapter'
+  | 'doc-colophon'
+  | 'doc-conclusion'
+  | 'doc-cover'
+  | 'doc-credit'
+  | 'doc-credits'
+  | 'doc-dedication'
+  | 'doc-endnote'
+  | 'doc-endnotes'
+  | 'doc-epigraph'
+  | 'doc-epilogue'
+  | 'doc-errata'
+  | 'doc-example'
+  | 'doc-footnote'
+  | 'doc-foreword'
+  | 'doc-glossary'
+  | 'doc-glossref'
+  | 'doc-index'
+  | 'doc-introduction'
+  | 'doc-noteref'
+  | 'doc-notice'
+  | 'doc-pagebreak'
+  | 'doc-pagelist'
+  | 'doc-part'
+  | 'doc-preface'
+  | 'doc-prologue'
+  | 'doc-pullquote'
+  | 'doc-qna'
+  | 'doc-subtitle'
+  | 'doc-tip'
+  | 'doc-toc'

package/src/types/role.ts

@@ -1,129 +1 @@
-/**
- * Valid values for `aria-expanded`.
- */
-export type ARIAAutoComplete = 'none' | 'inline' | 'list' | 'both'
-
-/**
- * Valid values for `aria-expanded`.
- */
-export type ARIAExpanded = 'true' | 'false'
-
-/**
- * Valid values for `aria-haspopup`.
- */
-export type ARIAHasPopup = 'false' | 'true' | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog'
-
-/**
- * Valid values for `role`.
- */
-export type ARIARole =
-  | 'alert'
-  | 'alertdialog'
-  | 'button'
-  | 'checkbox'
-  | 'dialog'
-  | 'gridcell'
-  | 'link'
-  | 'log'
-  | 'marquee'
-  | 'menuitem'
-  | 'menuitemcheckbox'
-  | 'menuitemradio'
-  | 'option'
-  | 'progressbar'
-  | 'radio'
-  | 'scrollbar'
-  | 'searchbox'
-  | 'slider'
-  | 'spinbutton'
-  | 'status'
-  | 'switch'
-  | 'tab'
-  | 'tabpanel'
-  | 'textbox'
-  | 'timer'
-  | 'tooltip'
-  | 'treeitem'
-  | 'combobox'
-  | 'grid'
-  | 'listbox'
-  | 'menu'
-  | 'menubar'
-  | 'radiogroup'
-  | 'tablist'
-  | 'tree'
-  | 'treegrid'
-  | 'application'
-  | 'article'
-  | 'cell'
-  | 'columnheader'
-  | 'definition'
-  | 'directory'
-  | 'document'
-  | 'feed'
-  | 'figure'
-  | 'group'
-  | 'heading'
-  | 'img'
-  | 'list'
-  | 'listitem'
-  | 'math'
-  | 'none'
-  | 'note'
-  | 'presentation'
-  | 'region'
-  | 'row'
-  | 'rowgroup'
-  | 'rowheader'
-  | 'separator'
-  | 'table'
-  | 'term'
-  | 'text'
-  | 'toolbar'
-  | 'banner'
-  | 'complementary'
-  | 'contentinfo'
-  | 'form'
-  | 'main'
-  | 'navigation'
-  | 'region'
-  | 'search'
-  | 'doc-abstract'
-  | 'doc-acknowledgments'
-  | 'doc-afterword'
-  | 'doc-appendix'
-  | 'doc-backlink'
-  | 'doc-biblioentry'
-  | 'doc-bibliography'
-  | 'doc-biblioref'
-  | 'doc-chapter'
-  | 'doc-colophon'
-  | 'doc-conclusion'
-  | 'doc-cover'
-  | 'doc-credit'
-  | 'doc-credits'
-  | 'doc-dedication'
-  | 'doc-endnote'
-  | 'doc-endnotes'
-  | 'doc-epigraph'
-  | 'doc-epilogue'
-  | 'doc-errata'
-  | 'doc-example'
-  | 'doc-footnote'
-  | 'doc-foreword'
-  | 'doc-glossary'
-  | 'doc-glossref'
-  | 'doc-index'
-  | 'doc-introduction'
-  | 'doc-noteref'
-  | 'doc-notice'
-  | 'doc-pagebreak'
-  | 'doc-pagelist'
-  | 'doc-part'
-  | 'doc-preface'
-  | 'doc-prologue'
-  | 'doc-pullquote'
-  | 'doc-qna'
-  | 'doc-subtitle'
-  | 'doc-tip'
-  | 'doc-toc'
+export { ARIAAutoComplete, ARIAExpanded, ARIAHasPopup, ARIARole } from './aria.js'