@api-client/ui 0.5.32 → 0.5.33

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.
@@ -49,10 +114,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'

package/test/elements/navigation/Navigation.test.ts

@@ -0,0 +1,120 @@
+import { html, fixture, assert, oneEvent, aTimeout } from '@open-wc/testing'
+import type Navigation from '../../../src/elements/navigation/internals/Navigation.js'
+import '../../../src/elements/navigation/ui-navigation.js'
+import '../../../src/elements/navigation/ui-navigation-item.js'
+
+describe('Navigation', () => {
+  it('renders with slot content', async () => {
+    const el = await fixture<Navigation>(html`
+      <ui-navigation aria-label="Main navigation">
+        <ui-navigation-item selected aria-current="page">Home</ui-navigation-item>
+        <ui-navigation-item>Search</ui-navigation-item>
+        <ui-navigation-item>Files</ui-navigation-item>
+      </ui-navigation>
+    `)
+    const nav = el.shadowRoot!.querySelector('nav')
+    assert.ok(nav, 'nav element is rendered')
+    assert.equal(nav?.getAttribute('aria-label'), 'Main navigation')
+    const items = el._items
+    assert.equal(items.length, 3)
+    assert.isTrue(items[0].selected)
+    assert.equal(items[0].getAttribute('aria-current'), 'page')
+  })
+
+  it('sets correct tabindex for items', async () => {
+    const el = await fixture<Navigation>(html`
+      <ui-navigation>
+        <ui-navigation-item selected>Home</ui-navigation-item>
+        <ui-navigation-item>Search</ui-navigation-item>
+      </ui-navigation>
+    `)
+    const items = el._items
+    assert.equal(items[0].getAttribute('tabindex'), '0')
+    assert.equal(items[1].getAttribute('tabindex'), '-1')
+  })
+
+  it('selects item on click and fires select event', async () => {
+    const el = await fixture<Navigation>(html`
+      <ui-navigation>
+        <ui-navigation-item>Home</ui-navigation-item>
+        <ui-navigation-item>Search</ui-navigation-item>
+      </ui-navigation>
+    `)
+    const items = el._items
+    setTimeout(() => items[1].click())
+    const ev = await oneEvent(el, 'select')
+    assert.equal(ev.detail.item, items[1])
+    assert.isTrue(items[1].selected)
+    assert.equal(items[1].getAttribute('tabindex'), '0')
+    assert.isFalse(items[0].selected)
+    assert.equal(items[0].getAttribute('tabindex'), '-1')
+  })
+
+  it('handles keyboard navigation (vertical)', async () => {
+    const el = await fixture<Navigation>(html`
+      <ui-navigation>
+        <ui-navigation-item>Home</ui-navigation-item>
+        <ui-navigation-item>Search</ui-navigation-item>
+        <ui-navigation-item>Files</ui-navigation-item>
+      </ui-navigation>
+    `)
+    const items = el._items
+    items[0].focus()
+    // ArrowDown moves to next
+    items[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }))
+    await aTimeout(0)
+    assert.dom.equal(document.activeElement, items[1])
+    // ArrowUp wraps to last
+    items[1].dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowUp', bubbles: true }))
+    await aTimeout(0)
+    assert.dom.equal(document.activeElement, items[0])
+  })
+
+  it('handles keyboard navigation (horizontal)', async () => {
+    const el = await fixture<Navigation>(html`
+      <ui-navigation orientation="horizontal">
+        <ui-navigation-item>Home</ui-navigation-item>
+        <ui-navigation-item>Search</ui-navigation-item>
+      </ui-navigation>
+    `)
+    const items = el._items
+    items[0].focus()
+    items[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }))
+    await aTimeout(0)
+    assert.dom.equal(document.activeElement, items[1])
+    items[1].dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowLeft', bubbles: true }))
+    await aTimeout(0)
+    assert.dom.equal(document.activeElement, items[0])
+  })
+
+  it('skips disabled items in navigation', async () => {
+    const el = await fixture<Navigation>(html`
+      <ui-navigation>
+        <ui-navigation-item>Home</ui-navigation-item>
+        <ui-navigation-item disabled>Search</ui-navigation-item>
+        <ui-navigation-item>Files</ui-navigation-item>
+      </ui-navigation>
+    `)
+    const items = el._items
+    items[0].focus()
+    items[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }))
+    await aTimeout(0)
+    // Should skip disabled and go to Files
+    assert.dom.equal(document.activeElement, items[2])
+  })
+
+  it('sets aria-current on selected item if current is set', async () => {
+    const el = await fixture<Navigation>(html`
+      <ui-navigation current="page">
+        <ui-navigation-item>Home</ui-navigation-item>
+        <ui-navigation-item>Search</ui-navigation-item>
+      </ui-navigation>
+    `)
+    const items = el._items
+    // Simulate user selection by clicking the item (public API)
+    items[1].click()
+    await aTimeout(0)
+    assert.equal(items[1].getAttribute('aria-current'), 'page')
+    assert.isFalse(items[0].hasAttribute('aria-current'))
+  })
+})

package/tsconfig.json

@@ -36,6 +36,6 @@
       }
     ]
   },
-  "include": ["src/**/*.ts"],
+  "include": ["src/**/*.ts", "test/elements/navigation/Navigation.test.ts"],
   "exclude": ["demo/apis/*", "demo/models/*", "node_modules", ".wireit", ".tmp", ".rollup.cache"]
 }