diff --git a/dev/vscode-breadcrumbs.html b/dev/vscode-breadcrumbs.html new file mode 100644 index 000000000..a3bbbf8d0 --- /dev/null +++ b/dev/vscode-breadcrumbs.html @@ -0,0 +1,73 @@ + + + + + + <vscode-breadcrumbs> Demo + + + + + + + + + +
+
+

Basic example

+
+ + + + + workspace + + + + src + + + + components + + + + vscode-breadcrumbs.ts + + + +
+
+ +
+

Programmatic selection

+
+ + + Root + src + index.ts + + + +
+
+
+ + diff --git a/src/main.ts b/src/main.ts index 97fe0665e..686064a0d 100644 --- a/src/main.ts +++ b/src/main.ts @@ -35,3 +35,5 @@ export {VscodeToolbarButton} from './vscode-toolbar-button/index.js'; export {VscodeToolbarContainer} from './vscode-toolbar-container/index.js'; export {VscodeTree} from './vscode-tree/index.js'; export {VscodeTreeItem} from './vscode-tree-item/index.js'; +export {VscodeBreadcrumbs} from './vscode-breadcrumbs/index.js'; +export {VscodeBreadcrumbItem} from './vscode-breadcrumb-item/index.js'; diff --git a/src/vscode-breadcrumb-item/index.ts b/src/vscode-breadcrumb-item/index.ts new file mode 100644 index 000000000..0b5725e40 --- /dev/null +++ b/src/vscode-breadcrumb-item/index.ts @@ -0,0 +1 @@ +export {VscodeBreadcrumbItem} from './vscode-breadcrumb-item.js'; diff --git a/src/vscode-breadcrumb-item/vscode-breadcrumb-item.styles.ts b/src/vscode-breadcrumb-item/vscode-breadcrumb-item.styles.ts new file mode 100644 index 000000000..aca3dc5f8 --- /dev/null +++ b/src/vscode-breadcrumb-item/vscode-breadcrumb-item.styles.ts @@ -0,0 +1,49 @@ +import {css, CSSResultGroup} from 'lit'; +import defaultStyles from '../includes/default.styles.js'; + +const styles: CSSResultGroup = [ + defaultStyles, + css` + :host { + display: inline-flex; + align-items: center; + gap: 6px; + color: var(--vscode-breadcrumb-foreground, inherit); + outline: none; + cursor: default; + } + + :host(:focus) { + color: var( + --vscode-breadcrumb-focusForeground, + var(--vscode-breadcrumb-foreground, inherit) + ); + } + + :host(.selected) { + color: var( + --vscode-breadcrumb-activeSelectionForeground, + var(--vscode-breadcrumb-focusForeground, inherit) + ); + } + + .separator { + user-select: none; + color: var(--vscode-breadcrumb-foreground, inherit); + opacity: 0.7; + } + + :host(:first-child) .separator { + display: none; + } + + .icon::slotted(*) { + display: inline-flex; + align-items: center; + font-size: 12px; + line-height: 1; + } + `, +]; + +export default styles; diff --git a/src/vscode-breadcrumb-item/vscode-breadcrumb-item.ts b/src/vscode-breadcrumb-item/vscode-breadcrumb-item.ts new file mode 100644 index 000000000..9dfbd72f9 --- /dev/null +++ b/src/vscode-breadcrumb-item/vscode-breadcrumb-item.ts @@ -0,0 +1,39 @@ +import {TemplateResult, html} from 'lit'; +import {customElement, VscElement} from '../includes/VscElement.js'; +import styles from './vscode-breadcrumb-item.styles.js'; + +/** + * @tag vscode-breadcrumb-item + * + * Slot the label/icon as content. + * + * @cssprop [--vscode-breadcrumb-foreground=inherit] - Breadcrumb text and icon color + * @cssprop [--vscode-breadcrumb-focusForeground=var(--vscode-breadcrumb-foreground, inherit)] - Text color when an item has focus + * @cssprop [--vscode-breadcrumb-activeSelectionForeground=var(--vscode-breadcrumb-focusForeground, inherit)] - Text color for the selected item + */ +@customElement('vscode-breadcrumb-item') +export class VscodeBreadcrumbItem extends VscElement { + static override styles = styles; + + override connectedCallback(): void { + super.connectedCallback(); + if (!this.hasAttribute('tabindex')) { + this.tabIndex = -1; + } + this.setAttribute('role', 'listitem'); + } + + override render(): TemplateResult { + return html` + + `; + } +} + +declare global { + interface HTMLElementTagNameMap { + 'vscode-breadcrumb-item': VscodeBreadcrumbItem; + } +} diff --git a/src/vscode-breadcrumbs/index.ts b/src/vscode-breadcrumbs/index.ts new file mode 100644 index 000000000..e7ae284f3 --- /dev/null +++ b/src/vscode-breadcrumbs/index.ts @@ -0,0 +1 @@ +export {VscodeBreadcrumbs} from './vscode-breadcrumbs.js'; diff --git a/src/vscode-breadcrumbs/vscode-breadcrumbs.styles.ts b/src/vscode-breadcrumbs/vscode-breadcrumbs.styles.ts new file mode 100644 index 000000000..6459f9682 --- /dev/null +++ b/src/vscode-breadcrumbs/vscode-breadcrumbs.styles.ts @@ -0,0 +1,35 @@ +import {css, CSSResultGroup} from 'lit'; +import defaultStyles from '../includes/default.styles.js'; + +const styles: CSSResultGroup = [ + defaultStyles, + css` + :host { + display: block; + width: 100%; + outline: none; + } + + .container { + position: relative; + display: flex; + align-items: center; + gap: 6px; + overflow-x: auto; + overflow-y: hidden; + scrollbar-width: none; /* Firefox */ + -ms-overflow-style: none; /* IE 10+ */ + background: var(--vscode-breadcrumb-background, transparent); + } + + .container::-webkit-scrollbar { + display: none; /* Chrome/Safari */ + } + + ::slotted(vscode-breadcrumb-item) { + flex: 0 0 auto; + } + `, +]; + +export default styles; diff --git a/src/vscode-breadcrumbs/vscode-breadcrumbs.test.ts b/src/vscode-breadcrumbs/vscode-breadcrumbs.test.ts new file mode 100644 index 000000000..a55f32aef --- /dev/null +++ b/src/vscode-breadcrumbs/vscode-breadcrumbs.test.ts @@ -0,0 +1,97 @@ +import {expect, fixture, html} from '@open-wc/testing'; +import './vscode-breadcrumbs.js'; +import '../vscode-breadcrumb-item/vscode-breadcrumb-item.js'; +import {VscodeBreadcrumbs} from './vscode-breadcrumbs.js'; + +describe('vscode-breadcrumbs', () => { + it('is defined', () => { + const el = document.createElement('vscode-breadcrumbs'); + expect(el).to.be.instanceOf(VscodeBreadcrumbs); + }); + + it('focuses and selects items on click', async () => { + const el = (await fixture(html` + + Root + src + index.ts + + `)) as VscodeBreadcrumbs; + + const items = el.querySelectorAll('vscode-breadcrumb-item'); + + const selectPromise = new Promise((resolve) => { + const handler = (e: Event) => { + el.removeEventListener('vsc-select', handler); + resolve(e as CustomEvent); + }; + el.addEventListener('vsc-select', handler, {once: true}); + }); + (items[1] as HTMLElement).click(); + const ev = await selectPromise; + + expect((items[1] as HTMLElement).classList.contains('selected')).to.be.true; + expect(ev.detail.index).to.equal(1); + }); + + it('supports keyboard navigation and selection', async () => { + const el = (await fixture(html` + + Root + src + index.ts + + `)) as VscodeBreadcrumbs; + + // Focus the last item by default + const items = el.querySelectorAll('vscode-breadcrumb-item'); + await el.updateComplete; + + // Move left, then select + el.dispatchEvent( + new KeyboardEvent('keydown', {key: 'ArrowLeft', bubbles: true}) + ); + el.dispatchEvent( + new KeyboardEvent('keydown', {key: 'Enter', bubbles: true}) + ); + + await el.updateComplete; + + expect((items[1] as HTMLElement).classList.contains('selected')).to.be.true; + }); + + it('sets aria-current on the last item and aria-label on the host by default', async () => { + const el = (await fixture(html` + + Root + src + index.ts + + `)) as VscodeBreadcrumbs; + + const items = el.querySelectorAll('vscode-breadcrumb-item'); + await el.updateComplete; + + // Host should have an aria-label + expect(el.getAttribute('aria-label')).to.equal('Breadcrumb'); + + // Last item should have aria-current="page" + expect((items[2] as HTMLElement).getAttribute('aria-current')).to.equal( + 'page' + ); + // Other items should not have aria-current + expect((items[0] as HTMLElement).hasAttribute('aria-current')).to.be.false; + }); + + it('does not override an existing aria-label on the host', async () => { + const el = (await fixture(html` + + Root + src + + `)) as VscodeBreadcrumbs; + + await el.updateComplete; + expect(el.getAttribute('aria-label')).to.equal('Custom label'); + }); +}); diff --git a/src/vscode-breadcrumbs/vscode-breadcrumbs.ts b/src/vscode-breadcrumbs/vscode-breadcrumbs.ts new file mode 100644 index 000000000..f7fa34e82 --- /dev/null +++ b/src/vscode-breadcrumbs/vscode-breadcrumbs.ts @@ -0,0 +1,196 @@ +import {TemplateResult, html} from 'lit'; +import {customElement, VscElement} from '../includes/VscElement.js'; +import {property} from 'lit/decorators.js'; +import styles from './vscode-breadcrumbs.styles.js'; +import '../vscode-breadcrumb-item/vscode-breadcrumb-item.js'; + +export type VscodeBreadcrumbsEventDetail = { + index: number; + item: HTMLElement; + payload?: Event; +}; + +export type VscodeBreadcrumbsFocusEvent = + CustomEvent; +export type VscodeBreadcrumbsSelectEvent = + CustomEvent; + +/** + * @tag vscode-breadcrumbs + * + * Container for breadcrumb items. + * + * @fires vsc-focus Fired when a breadcrumb item receives focus. Detail: { index, item, payload } + * @fires vsc-select Fired when a breadcrumb item is selected. Detail: { index, item, payload } + * + * @cssprop [--vscode-breadcrumb-background=transparent] - Breadcrumbs container background + * + * @prop {number} selectedIndex - Index of the selected breadcrumb item (-1 for none) + * @attr {number} selected-index - Index of the selected breadcrumb item (-1 for none) + */ +@customElement('vscode-breadcrumbs') +export class VscodeBreadcrumbs extends VscElement { + static override styles = styles; + + @property({type: Number, reflect: true, attribute: 'selected-index'}) + selectedIndex = -1; + private _focusedIndex = -1; + + override connectedCallback(): void { + super.connectedCallback(); + this.setAttribute('role', 'list'); + if (!this.hasAttribute('aria-label')) { + this.setAttribute('aria-label', 'Breadcrumb'); + } + this.tabIndex = -1; // focus individual items + this.addEventListener('click', this.onClick as EventListener); + this.addEventListener('keydown', this.onKeydown as EventListener); + } + + override disconnectedCallback(): void { + this.removeEventListener('click', this.onClick as EventListener); + this.removeEventListener('keydown', this.onKeydown as EventListener); + super.disconnectedCallback(); + } + + override firstUpdated(): void { + this.refreshItems(); + } + + private getItems(): HTMLElement[] { + return Array.from( + this.querySelectorAll('vscode-breadcrumb-item') + ) as HTMLElement[]; + } + + private refreshItems(_event?: Event): void { + const items = this.getItems(); + // Make one item tabbable if none yet + if (this._focusedIndex < 0 && items.length) { + this._focusedIndex = items.length - 1; // default to last + } + this.applyItemStates(); + } + + private applyItemStates(): void { + const items = this.getItems(); + items.forEach((el, idx) => { + el.setAttribute('tabindex', idx === this._focusedIndex ? '0' : '-1'); + el.classList.toggle('selected', idx === this.selectedIndex); + // Mark the last breadcrumb as the current page for accessibility + if (idx === items.length - 1) { + el.setAttribute('aria-current', 'page'); + } else { + el.removeAttribute('aria-current'); + } + }); + // Ensure focused is scrolled into view + items[this._focusedIndex]?.scrollIntoView({ + block: 'nearest', + inline: 'nearest', + }); + } + + private onClick(ev: MouseEvent) { + const items = this.getItems(); + for ( + let el = ev.target as HTMLElement | null; + el && this.contains(el); + el = el.parentElement + ) { + const idx = items.indexOf(el); + if (idx >= 0) { + this.focusItem(idx, ev); + this.selectItem(idx, ev); + break; + } + } + } + + private onKeydown(ev: KeyboardEvent): void { + const items = this.getItems(); + if (!items.length) return; + if (ev.key === 'ArrowLeft') { + ev.preventDefault(); + const next = Math.max(0, this._focusedIndex - 1); + this.focusItem(next, ev); + } else if (ev.key === 'ArrowRight') { + ev.preventDefault(); + const next = Math.min(items.length - 1, this._focusedIndex + 1); + this.focusItem(next, ev); + } else if (ev.key === 'Enter' || ev.key === ' ') { + ev.preventDefault(); + this.selectItem(this._focusedIndex, ev); + } + } + + private focusItem(idx: number, payload?: Event): void { + const items = this.getItems(); + if (idx < 0 || idx >= items.length) return; + this._focusedIndex = idx; + this.applyItemStates(); + items[idx].focus(); + this.dispatchEvent( + this.createFocusEvent({index: idx, item: items[idx], payload}) + ); + } + + private selectItem(idx: number, payload?: Event): void { + const items = this.getItems(); + if (idx < 0 || idx >= items.length) return; + this.selectedIndex = idx; + this.applyItemStates(); + this.dispatchEvent( + this.createSelectEvent({index: idx, item: items[idx], payload}) + ); + } + + override render(): TemplateResult { + return html`
+ +
`; + } + + override attributeChangedCallback( + name: string, + old: string | null, + value: string | null + ): void { + super.attributeChangedCallback(name, old, value); + if (name === 'selected-index') { + // When selected-index changes via attribute/property, update item states + this.applyItemStates(); + } + } + + protected createFocusEvent( + detail: VscodeBreadcrumbsEventDetail + ): VscodeBreadcrumbsFocusEvent { + return new CustomEvent('vsc-focus', { + detail, + bubbles: true, + composed: true, + }); + } + + protected createSelectEvent( + detail: VscodeBreadcrumbsEventDetail + ): VscodeBreadcrumbsSelectEvent { + return new CustomEvent('vsc-select', { + detail, + bubbles: true, + composed: true, + }); + } +} + +declare global { + interface HTMLElementTagNameMap { + 'vscode-breadcrumbs': VscodeBreadcrumbs; + } + + interface GlobalEventHandlersEventMap { + 'vsc-focus': VscodeBreadcrumbsFocusEvent; + 'vsc-select': VscodeBreadcrumbsSelectEvent; + } +}