@openvoxproject/voxblocks 0.9.0 → 0.11.0

package/src/components/radio/vox-radio-group.ts

@@ -1,5 +1,6 @@
-import { html, css } from 'lit';
+import { html, css, nothing } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
+import { ifDefined } from 'lit/directives/if-defined.js';
 import { VoxFieldElement, fieldStyles } from '../../internal/field.js';
 import type { VoxRadio } from './vox-radio.js';
 
@@ -35,8 +36,9 @@ export class VoxRadioGroup extends VoxFieldElement {
 
   updated() {
     this.internals.setFormValue(this.value || null);
+    this.invalid = this.required && !this.value;
     this.internals.setValidity(
-      this.required && !this.value ? { valueMissing: true } : {},
+      this.invalid ? { valueMissing: true } : {},
       'Please select an option.',
       this,
     );
@@ -46,10 +48,12 @@ export class VoxRadioGroup extends VoxFieldElement {
   private syncRadios() {
     const radios = this.radios;
     const anyChecked = radios.some((r) => r.value === this.value && this.value !== '');
-    radios.forEach((radio, index) => {
+    const firstEnabled = radios.find((r) => !r.disabled);
+    radios.forEach((radio) => {
       radio.checked = this.value !== '' && radio.value === this.value;
-      // Roving tabindex: the checked radio is tabbable, else the first one.
-      const tabbable = anyChecked ? radio.checked : index === 0;
+      // Roving tabindex: the checked radio is tabbable, else the first
+      // enabled one (a disabled radio can't receive focus at all).
+      const tabbable = anyChecked ? radio.checked : radio === firstEnabled;
       radio.shadowRoot
         ?.querySelector('.radio')
         ?.setAttribute('tabindex', tabbable ? '0' : '-1');
@@ -89,7 +93,14 @@ export class VoxRadioGroup extends VoxFieldElement {
 
   render() {
     return html`
-      <div class="field" role="radiogroup" aria-label=${this.label}>
+      <div
+        class="field"
+        role="radiogroup"
+        aria-label=${this.label || nothing}
+        aria-describedby=${ifDefined(this.noteId)}
+        aria-invalid=${this.invalid ? 'true' : 'false'}
+        aria-required=${this.required ? 'true' : 'false'}
+      >
         ${this.label
           ? html`<span class="label">
               ${this.label}${this.required

package/src/components/select/vox-select.ts

@@ -1,5 +1,6 @@
 import { html, css } from 'lit';
 import { customElement, property, query } from 'lit/decorators.js';
+import { ifDefined } from 'lit/directives/if-defined.js';
 import { VoxFieldElement, fieldStyles } from '../../internal/field.js';
 
 /**
@@ -73,6 +74,8 @@ export class VoxSelect extends VoxFieldElement {
           class="control"
           ?required=${this.required}
           ?disabled=${this.disabled}
+          aria-describedby=${ifDefined(this.noteId)}
+          aria-invalid=${this.invalid ? 'true' : 'false'}
           @change=${this.handleChange}
         ></select>
         ${this.renderNote()}

package/src/components/sidenav/vox-sidenav.ts

@@ -1,8 +1,12 @@
 import { LitElement, html, css } from 'lit';
-import { customElement, property } from 'lit/decorators.js';
+import { customElement, property, state } from 'lit/decorators.js';
+import { ICON_PATHS } from '../icon/icon-paths.js';
 
 /**
  * A vertical section navigation, in the style of the OpenVox docs sidebar.
+ * Below 768px, collapses behind a toggle button — the same breakpoint and
+ * pattern `vox-header` uses for its own nav, so a page's top nav and side
+ * nav switch to mobile mode together.
  *
  * ```html
  * <vox-sidenav>
@@ -17,24 +21,152 @@ import { customElement, property } from 'lit/decorators.js';
  */
 @customElement('vox-sidenav')
 export class VoxSidenav extends LitElement {
+  /** Accessible name for the `<nav>` landmark. */
   @property() label = 'Section';
 
+  /** Visible text on the mobile toggle button. */
+  @property({ attribute: 'toggle-label' }) toggleLabel = 'Menu';
+
+  @state() private mobileOpen = false;
+
   static styles = css`
     :host {
       display: block;
       font-family: var(--vox-font-family-base);
     }
 
+    .toggle {
+      display: none;
+      align-items: center;
+      justify-content: space-between;
+      width: 100%;
+      gap: var(--vox-space-2);
+      padding: var(--vox-space-2) var(--vox-space-3);
+      background: none;
+      border: 1px solid var(--vox-color-divider);
+      border-radius: var(--vox-radius-md);
+      color: var(--vox-color-text-1);
+      font-family: inherit;
+      font-size: 14px;
+      font-weight: 600;
+      cursor: pointer;
+    }
+
+    .toggle:hover {
+      border-color: var(--vox-color-brand-1);
+      color: var(--vox-color-brand-1);
+    }
+
+    .toggle:focus-visible {
+      outline: 2px solid var(--vox-color-brand-1);
+      outline-offset: 2px;
+    }
+
+    .toggle-icon {
+      width: 18px;
+      height: 18px;
+      flex: none;
+    }
+
     nav {
       display: flex;
       flex-direction: column;
       gap: 2px;
     }
+
+    @media (max-width: 768px) {
+      .toggle {
+        display: flex;
+      }
+
+      nav {
+        display: none;
+        margin-top: var(--vox-space-2);
+      }
+
+      nav.open {
+        display: flex;
+      }
+    }
   `;
 
+  connectedCallback() {
+    super.connectedCallback();
+    document.addEventListener('click', this.handleOutsideClick);
+    this.addEventListener('keydown', this.handleKeydown);
+    this.addEventListener('focusout', this.handleFocusOut);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    document.removeEventListener('click', this.handleOutsideClick);
+    this.removeEventListener('keydown', this.handleKeydown);
+    this.removeEventListener('focusout', this.handleFocusOut);
+  }
+
+  private handleOutsideClick = (event: MouseEvent) => {
+    if (this.mobileOpen && !event.composedPath().includes(this)) {
+      this.mobileOpen = false;
+    }
+  };
+
+  /** Close the mobile menu once focus tabs past its last item. */
+  private handleFocusOut = (event: FocusEvent) => {
+    const next = event.relatedTarget as Node | null;
+    if (this.mobileOpen && !(next && this.contains(next))) {
+      this.mobileOpen = false;
+    }
+  };
+
+  private handleKeydown = (event: KeyboardEvent) => {
+    if (event.key === 'Escape' && this.mobileOpen) {
+      this.mobileOpen = false;
+      this.renderRoot.querySelector<HTMLElement>('.toggle')?.focus();
+    }
+  };
+
+  private toggleMobile = () => {
+    this.mobileOpen = !this.mobileOpen;
+  };
+
+  private handleNavClick = (event: MouseEvent) => {
+    // Only close on an actual navigation (an <a> in the composed path) —
+    // not on a vox-sidenav-group's own expand/collapse trigger, which is
+    // a <button> nested inside this same <nav>.
+    if (event.composedPath().some((el) => el instanceof HTMLAnchorElement)) {
+      this.mobileOpen = false;
+    }
+  };
+
   render() {
     return html`
-      <nav aria-label=${this.label}>
+      <button
+        type="button"
+        class="toggle"
+        aria-expanded=${this.mobileOpen ? 'true' : 'false'}
+        aria-controls="nav"
+        @click=${this.toggleMobile}
+      >
+        ${this.toggleLabel}
+        <svg
+          class="toggle-icon"
+          viewBox="0 0 48 48"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          ${this.mobileOpen ? ICON_PATHS.close : ICON_PATHS.menu}
+        </svg>
+      </button>
+      <nav
+        id="nav"
+        class=${this.mobileOpen ? 'open' : ''}
+        aria-label=${this.label}
+        @click=${this.handleNavClick}
+      >
         <slot></slot>
       </nav>
     `;
@@ -48,9 +180,13 @@ export class VoxSidenav extends LitElement {
  */
 @customElement('vox-sidenav-group')
 export class VoxSidenavGroup extends LitElement {
+  private static nextId = 0;
+
   @property() heading = '';
   @property({ type: Boolean, reflect: true }) open = false;
 
+  private readonly itemsId = `vox-sidenav-group-items-${VoxSidenavGroup.nextId++}`;
+
   static styles = css`
     :host {
       display: block;
@@ -118,6 +254,7 @@ export class VoxSidenavGroup extends LitElement {
       <button
         class="trigger"
         aria-expanded=${this.open ? 'true' : 'false'}
+        aria-controls=${this.itemsId}
         @click=${this.toggle}
       >
         ${this.heading}
@@ -125,7 +262,7 @@ export class VoxSidenavGroup extends LitElement {
           <path d="m9 6 6 6-6 6" />
         </svg>
       </button>
-      <div class="items"><slot></slot></div>
+      <div id=${this.itemsId} class="items"><slot></slot></div>
     `;
   }
 }
@@ -134,6 +271,7 @@ export class VoxSidenavGroup extends LitElement {
  * One sidenav link. Set `current` on the active page's item.
  *
  * @slot - Link text.
+ * @slot icon - Optional icon before the link text, e.g. `<vox-icon>`.
  */
 @customElement('vox-sidenav-item')
 export class VoxSidenavItem extends LitElement {
@@ -147,7 +285,9 @@ export class VoxSidenavItem extends LitElement {
     }
 
     a {
-      display: block;
+      display: flex;
+      align-items: center;
+      gap: var(--vox-space-2);
       padding: var(--vox-space-2) var(--vox-space-3);
       border-radius: var(--vox-radius-sm);
       color: var(--vox-color-text-2);
@@ -172,11 +312,31 @@ export class VoxSidenavItem extends LitElement {
       color: var(--vox-color-brand-1);
       font-weight: 600;
     }
+
+    .icon {
+      display: flex;
+      flex: none;
+    }
+
+    .icon:not(.has-icon) {
+      display: none;
+    }
   `;
 
+  private hasIcon = false;
+
+  private handleIconSlotChange(event: Event) {
+    const slot = event.target as HTMLSlotElement;
+    this.hasIcon = slot.assignedNodes({ flatten: true }).length > 0;
+    this.requestUpdate();
+  }
+
   render() {
     return html`
       <a href=${this.href} aria-current=${this.current ? 'page' : 'false'}>
+        <span class="icon ${this.hasIcon ? 'has-icon' : ''}">
+          <slot name="icon" @slotchange=${this.handleIconSlotChange}></slot>
+        </span>
         <slot></slot>
       </a>
     `;

package/src/components/step-indicator/vox-step-indicator.ts

@@ -1,4 +1,4 @@
-import { LitElement, html, css } from 'lit';
+import { LitElement, html, css, nothing } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 
 export type StepState = 'complete' | 'current' | 'upcoming';
@@ -122,6 +122,15 @@ export class VoxStep extends LitElement {
       font-weight: 600;
       color: var(--vox-color-text-1);
     }
+
+    .visually-hidden {
+      position: absolute;
+      width: 1px;
+      height: 1px;
+      overflow: hidden;
+      clip: rect(0 0 0 0);
+      white-space: nowrap;
+    }
   `;
 
   render() {
@@ -138,7 +147,12 @@ export class VoxStep extends LitElement {
               </svg>`
             : this.number}
         </span>
-        <span class="label">${this.label}</span>
+        <span class="label">
+          ${this.label}
+          ${this.state !== 'current'
+            ? html`<span class="visually-hidden"> (${this.state})</span>`
+            : nothing}
+        </span>
       </div>
     `;
   }

package/src/components/tabs/vox-tabs.ts

@@ -65,11 +65,18 @@ export class VoxTabs extends LitElement {
   }
 
   private handleKeydown(event: KeyboardEvent) {
+    const tabs = this.tabs;
+    if (event.key === 'Home' || event.key === 'End') {
+      event.preventDefault();
+      const target = tabs[event.key === 'Home' ? 0 : tabs.length - 1];
+      target.select();
+      target.focusTab();
+      return;
+    }
     const deltas: Record<string, number> = { ArrowRight: 1, ArrowLeft: -1 };
     const delta = deltas[event.key];
     if (!delta) return;
     event.preventDefault();
-    const tabs = this.tabs;
     const index = tabs.findIndex((t) => t.selected);
     const next = tabs[(index + delta + tabs.length) % tabs.length];
     next.select();
@@ -150,9 +157,11 @@ export class VoxTab extends LitElement {
   render() {
     return html`
       <button
+        id="tab-${this.panel}"
         class="tab"
         role="tab"
         aria-selected=${this.selected ? 'true' : 'false'}
+        aria-controls="panel-${this.panel}"
         tabindex=${this.selected ? '0' : '-1'}
         @click=${this.select}
       >
@@ -185,10 +194,25 @@ export class VoxTabPanel extends LitElement {
     :host([active]) {
       display: block;
     }
+
+    div:focus-visible {
+      outline: 2px solid var(--vox-color-brand-1);
+      outline-offset: 2px;
+      border-radius: var(--vox-radius-sm);
+    }
   `;
 
   render() {
-    return html`<div role="tabpanel"><slot></slot></div>`;
+    return html`
+      <div
+        id="panel-${this.name}"
+        role="tabpanel"
+        aria-labelledby="tab-${this.name}"
+        tabindex="0"
+      >
+        <slot></slot>
+      </div>
+    `;
   }
 }
 

package/src/components/textarea/vox-textarea.ts

@@ -59,6 +59,8 @@ export class VoxTextarea extends VoxFieldElement {
           ?required=${this.required}
           ?readonly=${this.readonly}
           ?disabled=${this.disabled}
+          aria-describedby=${ifDefined(this.noteId)}
+          aria-invalid=${this.invalid ? 'true' : 'false'}
           @input=${this.handleInput}
           @change=${this.handleChange}
         ></textarea>

package/src/components/toc/vox-toc.ts

@@ -0,0 +1,140 @@
+import { LitElement, html, css } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+
+/**
+ * An in-page table of contents / heading outline, in the style of the
+ * OpenVox docs "On this page" panel. Nest `<vox-toc-item>` for
+ * sub-headings via the `children` slot.
+ *
+ * ```html
+ * <vox-toc heading="On this page">
+ *   <vox-toc-item href="#palette" current>Palette</vox-toc-item>
+ *   <vox-toc-item href="#pairing-hues">
+ *     Pairing hues
+ *     <vox-toc-item slot="children" href="#soft-badge">Soft badge</vox-toc-item>
+ *   </vox-toc-item>
+ * </vox-toc>
+ * ```
+ *
+ * @slot - `<vox-toc-item>` elements.
+ */
+@customElement('vox-toc')
+export class VoxToc extends LitElement {
+  @property() heading = 'On this page';
+
+  static styles = css`
+    :host {
+      display: block;
+      font-family: var(--vox-font-family-base);
+    }
+
+    .heading {
+      margin: 0 0 var(--vox-space-2);
+      padding-left: var(--vox-space-3);
+      font-size: 13px;
+      font-weight: 600;
+      color: var(--vox-color-text-1);
+    }
+
+    nav {
+      display: flex;
+      flex-direction: column;
+      gap: 1px;
+      border-left: 1px solid var(--vox-color-divider);
+    }
+  `;
+
+  render() {
+    return html`
+      <div class="heading" id="vox-toc-heading">${this.heading}</div>
+      <nav aria-labelledby="vox-toc-heading">
+        <slot></slot>
+      </nav>
+    `;
+  }
+}
+
+/**
+ * One heading link in a vox-toc. Set `current` on the active section.
+ *
+ * @slot - Link text.
+ * @slot children - Nested `<vox-toc-item>` elements for sub-headings.
+ */
+@customElement('vox-toc-item')
+export class VoxTocItem extends LitElement {
+  @property() href = '#';
+  @property({ type: Boolean, reflect: true }) current = false;
+
+  static styles = css`
+    :host {
+      display: block;
+      font-family: var(--vox-font-family-base);
+    }
+
+    a {
+      display: block;
+      margin-left: -1px;
+      padding: var(--vox-space-1) var(--vox-space-3);
+      border-left: 2px solid transparent;
+      color: var(--vox-color-text-2);
+      font-size: 13px;
+      line-height: 1.5;
+      text-decoration: none;
+      transition:
+        color var(--vox-transition-fast),
+        border-color var(--vox-transition-fast);
+    }
+
+    a:hover {
+      color: var(--vox-color-text-1);
+    }
+
+    a:focus-visible {
+      outline: 2px solid var(--vox-color-brand-1);
+      outline-offset: -2px;
+    }
+
+    :host([current]) a {
+      border-left-color: var(--vox-color-brand-1);
+      color: var(--vox-color-brand-1);
+      font-weight: 600;
+    }
+
+    .children {
+      display: flex;
+      flex-direction: column;
+      gap: 1px;
+      padding-left: var(--vox-space-3);
+    }
+
+    .children:not(.has-children) {
+      display: none;
+    }
+  `;
+
+  private hasChildren = false;
+
+  private handleChildrenSlotChange(event: Event) {
+    const slot = event.target as HTMLSlotElement;
+    this.hasChildren = slot.assignedNodes({ flatten: true }).length > 0;
+    this.requestUpdate();
+  }
+
+  render() {
+    return html`
+      <a href=${this.href} aria-current=${this.current ? 'true' : 'false'}>
+        <slot></slot>
+      </a>
+      <div class="children ${this.hasChildren ? 'has-children' : ''}">
+        <slot name="children" @slotchange=${this.handleChildrenSlotChange}></slot>
+      </div>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vox-toc': VoxToc;
+    'vox-toc-item': VoxTocItem;
+  }
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 import './tokens/tokens.css';
+import './tokens/palette.css';
 import './styles/utilities.css';
 
 // Actions
@@ -6,6 +7,9 @@ export { VoxButton } from './components/button/vox-button.js';
 export { VoxCta } from './components/cta/vox-cta.js';
 export { VoxThemeToggle } from './components/theme-toggle/vox-theme-toggle.js';
 
+// Icon
+export { VoxIcon } from './components/icon/vox-icon.js';
+
 // Forms
 export { VoxCheckbox } from './components/checkbox/vox-checkbox.js';
 export { VoxFileInput } from './components/file-input/vox-file-input.js';
@@ -28,6 +32,7 @@ export { VoxSeriesNav } from './components/series-nav/vox-series-nav.js';
 export { VoxSidenav, VoxSidenavGroup, VoxSidenavItem } from './components/sidenav/vox-sidenav.js';
 export { VoxSubnav } from './components/subnav/vox-subnav.js';
 export { VoxTabs, VoxTab, VoxTabPanel } from './components/tabs/vox-tabs.js';
+export { VoxToc, VoxTocItem } from './components/toc/vox-toc.js';
 
 // Overlays
 export { VoxDialog } from './components/dialog/vox-dialog.js';
@@ -56,6 +61,7 @@ export { VoxStepIndicator, VoxStep } from './components/step-indicator/vox-step-
 export { VoxTimeline, VoxTimelineItem } from './components/timeline/vox-timeline.js';
 
 // Types
+export type { IconName, IconSize } from './components/icon/vox-icon.js';
 export type { ButtonVariant, ButtonSize } from './components/button/vox-button.js';
 export type { CalloutVariant } from './components/callout/vox-callout.js';
 export type { BadgeVariant } from './components/badge/vox-badge.js';

package/src/internal/field.ts

@@ -1,5 +1,5 @@
 import { LitElement, html, css, nothing } from 'lit';
-import { property } from 'lit/decorators.js';
+import { property, state } from 'lit/decorators.js';
 
 /**
  * Shared base for form-associated VoxBlocks controls. Uses ElementInternals
@@ -10,6 +10,9 @@ export class VoxFieldElement extends LitElement {
 
   protected internals: ElementInternals;
 
+  /** Whether the control currently fails validation; drives `aria-invalid`. */
+  @state() protected invalid = false;
+
   @property() name = '';
   @property() label = '';
   @property() note = '';
@@ -46,6 +49,7 @@ export class VoxFieldElement extends LitElement {
     inner: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement,
   ) {
     this.internals.setValidity(inner.validity, inner.validationMessage, inner);
+    this.invalid = !inner.validity.valid;
   }
 
   protected renderLabel(forId: string) {
@@ -59,8 +63,13 @@ export class VoxFieldElement extends LitElement {
     `;
   }
 
+  /** `note`'s id when present, for `aria-describedby` on the native control. */
+  protected get noteId(): string | undefined {
+    return this.note ? 'note' : undefined;
+  }
+
   protected renderNote() {
-    return this.note ? html`<p class="note">${this.note}</p>` : nothing;
+    return this.note ? html`<p class="note" id="note">${this.note}</p>` : nothing;
   }
 }
 
@@ -119,6 +128,15 @@ export const fieldStyles = css`
     box-shadow: 0 0 0 3px var(--vox-color-brand-soft);
   }
 
+  .control[aria-invalid='true'] {
+    border-color: var(--vox-color-danger-1);
+  }
+
+  .control[aria-invalid='true']:focus {
+    border-color: var(--vox-color-danger-1);
+    box-shadow: 0 0 0 3px var(--vox-color-danger-soft);
+  }
+
   /* Corner flattening when placed inside a <vox-input-group>. */
   :host([data-vox-group]) .control {
     border-radius: 0;