@openvoxproject/voxblocks 0.9.0 → 0.11.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openvoxproject/voxblocks",
-  "version": "0.9.0",
-  "description": "Web components for Vox Pupuli OpenVox community web sites and apps",
+  "version": "0.11.0",
+  "description": "Web components for OpenVox community web sites and apps",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
@@ -35,9 +35,11 @@
   "scripts": {
     "prepare": "npm run build",
     "build": "vite build && vite build --config vite.cdn.config.ts && tsc -p tsconfig.build.json",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs",
+    "docs:dev": "rm -rf docs/assets docs/_data/manifest.json && concurrently -n vite,jekyll -c blue,magenta \"npm:docs:assets:watch\" \"npm:docs:jekyll:wait\"",
+    "docs:assets:watch": "vite build --config docs/vite.config.js --watch",
+    "docs:jekyll:wait": "wait-on docs/_data/manifest.json && npm run docs:jekyll",
+    "docs:jekyll": "BUNDLE_GEMFILE=docs/Gemfile bundle exec jekyll serve --livereload --source docs --destination docs/_site",
+    "docs:build": "vite build --config docs/vite.config.js && BUNDLE_GEMFILE=docs/Gemfile bundle exec jekyll build --source docs --destination docs/_site --config docs/_config.yml,docs/_config_production.yml",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build"
   },
@@ -47,10 +49,11 @@
   "devDependencies": {
     "@storybook/web-components": "^10.5.5",
     "@storybook/web-components-vite": "^10.5.5",
+    "concurrently": "^9.1.0",
     "storybook": "^10.5.5",
     "typescript": "^5.6.0",
     "vite": "^6.0.0",
-    "vitepress": "^1.5.0"
+    "wait-on": "^9.1.0"
   },
   "allowScripts": {
     "esbuild@0.25.12": true,

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

@@ -48,9 +48,13 @@ export class VoxAccordion extends LitElement {
  */
 @customElement('vox-accordion-item')
 export class VoxAccordionItem extends LitElement {
+  private static nextId = 0;
+
   @property() heading = '';
   @property({ type: Boolean, reflect: true }) open = false;
 
+  private readonly panelId = `vox-accordion-panel-${VoxAccordionItem.nextId++}`;
+
   static styles = css`
     :host {
       display: block;
@@ -127,6 +131,7 @@ export class VoxAccordionItem extends LitElement {
         <button
           class="trigger"
           aria-expanded=${this.open ? 'true' : 'false'}
+          aria-controls=${this.panelId}
           @click=${this.toggle}
         >
           ${this.heading}
@@ -135,7 +140,7 @@ export class VoxAccordionItem extends LitElement {
           </svg>
         </button>
       </h3>
-      <div class="panel" ?hidden=${!this.open}>
+      <div id=${this.panelId} class="panel" ?hidden=${!this.open}>
         <slot></slot>
       </div>
     `;

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

@@ -1,10 +1,19 @@
 import { LitElement, html, css, nothing } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
+import { ICON_PATHS, type IconName } from '../icon/icon-paths.js';
 
 export type AlertVariant = 'info' | 'success' | 'warning' | 'danger';
 
+const VARIANT_ICON: Record<AlertVariant, IconName> = {
+  info: 'info',
+  success: 'check-circle',
+  warning: 'warning',
+  danger: 'x-circle',
+};
+
 /**
- * A page-level notification message, optionally dismissible.
+ * A page-level notification message, optionally dismissible. Shows an
+ * icon matching `variant` automatically — no icon slot to fill in.
  * For static advisory text inside prose, see `<vox-callout>`.
  *
  * @slot - Alert message.
@@ -43,6 +52,13 @@ export class VoxAlert extends LitElement {
       flex: 1 1 auto;
     }
 
+    .icon {
+      flex: none;
+      width: 20px;
+      height: 20px;
+      margin-top: 1px;
+    }
+
     .heading {
       margin: 0 0 var(--vox-space-1);
       font-size: 14px;
@@ -56,6 +72,9 @@ export class VoxAlert extends LitElement {
     .info .heading {
       color: var(--vox-color-brand-1);
     }
+    .info .icon {
+      color: var(--vox-color-brand-1);
+    }
 
     .success {
       background-color: var(--vox-color-tip-soft);
@@ -64,6 +83,9 @@ export class VoxAlert extends LitElement {
     .success .heading {
       color: var(--vox-color-tip-1);
     }
+    .success .icon {
+      color: var(--vox-color-tip-1);
+    }
 
     .warning {
       background-color: var(--vox-color-warning-soft);
@@ -72,6 +94,9 @@ export class VoxAlert extends LitElement {
     .warning .heading {
       color: var(--vox-color-warning-1);
     }
+    .warning .icon {
+      color: var(--vox-color-warning-1);
+    }
 
     .danger {
       background-color: var(--vox-color-danger-soft);
@@ -80,6 +105,9 @@ export class VoxAlert extends LitElement {
     .danger .heading {
       color: var(--vox-color-danger-1);
     }
+    .danger .icon {
+      color: var(--vox-color-danger-1);
+    }
 
     .close {
       flex: none;
@@ -126,8 +154,24 @@ export class VoxAlert extends LitElement {
   }
 
   render() {
+    const isUrgent = this.variant === 'danger' || this.variant === 'warning';
     return html`
-      <div class="alert ${this.variant}" role="alert">
+      <div
+        class="alert ${this.variant}"
+        role=${isUrgent ? 'alert' : 'status'}
+      >
+        <svg
+          class="icon"
+          viewBox="0 0 48 48"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          ${ICON_PATHS[VARIANT_ICON[this.variant]]}
+        </svg>
         <div class="body">
           ${this.heading
             ? html`<p class="heading">${this.heading}</p>`

package/src/components/avatar/vox-avatar.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 AvatarSize = 'sm' | 'md' | 'lg' | 'xl';
@@ -63,8 +63,15 @@ export class VoxAvatar extends LitElement {
   `;
 
   render() {
+    // Without `alt`, fall back to letting AT read the initials as plain text
+    // rather than hiding them behind an empty aria-label via role="img".
+    const labelled = !this.src && this.alt;
     return html`
-      <span class="avatar" role=${this.src ? 'presentation' : 'img'} aria-label=${this.alt}>
+      <span
+        class="avatar"
+        role=${labelled ? 'img' : nothing}
+        aria-label=${labelled ? this.alt : nothing}
+      >
         ${this.src
           ? html`<img src=${this.src} alt=${this.alt} />`
           : this.initials}

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

@@ -1,5 +1,6 @@
 import { LitElement, html, css } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
+import { ICON_PATHS, type IconName } from '../icon/icon-paths.js';
 
 export type CalloutVariant = 'info' | 'tip' | 'warning' | 'danger';
 
@@ -10,9 +11,17 @@ const DEFAULT_HEADINGS: Record<CalloutVariant, string> = {
   danger: 'Danger',
 };
 
+const VARIANT_ICON: Record<CalloutVariant, IconName> = {
+  info: 'info',
+  tip: 'check-circle',
+  warning: 'warning',
+  danger: 'x-circle',
+};
+
 /**
  * An admonition block matching the custom containers on the OpenVox docs
- * (::: tip, ::: warning, ...).
+ * (::: tip, ::: warning, ...). Shows an icon matching `variant`
+ * automatically — no icon slot to fill in.
  *
  * @slot - Callout body content.
  */
@@ -29,6 +38,9 @@ export class VoxCallout extends LitElement {
     }
 
     .callout {
+      display: flex;
+      gap: var(--vox-space-3);
+      align-items: flex-start;
       border-radius: var(--vox-radius-md);
       padding: var(--vox-space-4);
       font-family: var(--vox-font-family-base);
@@ -37,6 +49,18 @@ export class VoxCallout extends LitElement {
       color: var(--vox-color-text-2);
     }
 
+    .icon {
+      flex: none;
+      width: 18px;
+      height: 18px;
+      margin-top: 2px;
+    }
+
+    .content {
+      flex: 1 1 auto;
+      min-width: 0;
+    }
+
     .heading {
       margin: 0 0 var(--vox-space-2);
       font-size: 14px;
@@ -49,6 +73,9 @@ export class VoxCallout extends LitElement {
     .info .heading {
       color: var(--vox-color-text-1);
     }
+    .info .icon {
+      color: var(--vox-color-text-1);
+    }
 
     .tip {
       background-color: var(--vox-color-tip-soft);
@@ -56,6 +83,9 @@ export class VoxCallout extends LitElement {
     .tip .heading {
       color: var(--vox-color-tip-1);
     }
+    .tip .icon {
+      color: var(--vox-color-tip-1);
+    }
 
     .warning {
       background-color: var(--vox-color-warning-soft);
@@ -63,6 +93,9 @@ export class VoxCallout extends LitElement {
     .warning .heading {
       color: var(--vox-color-warning-1);
     }
+    .warning .icon {
+      color: var(--vox-color-warning-1);
+    }
 
     .danger {
       background-color: var(--vox-color-danger-soft);
@@ -70,6 +103,9 @@ export class VoxCallout extends LitElement {
     .danger .heading {
       color: var(--vox-color-danger-1);
     }
+    .danger .icon {
+      color: var(--vox-color-danger-1);
+    }
 
     ::slotted(p:first-child) {
       margin-top: 0;
@@ -83,8 +119,22 @@ export class VoxCallout extends LitElement {
   render() {
     return html`
       <div class="callout ${this.variant}" role="note">
-        <p class="heading">${this.heading ?? DEFAULT_HEADINGS[this.variant]}</p>
-        <slot></slot>
+        <svg
+          class="icon"
+          viewBox="0 0 48 48"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          ${ICON_PATHS[VARIANT_ICON[this.variant]]}
+        </svg>
+        <div class="content">
+          <p class="heading">${this.heading ?? DEFAULT_HEADINGS[this.variant]}</p>
+          <slot></slot>
+        </div>
       </div>
     `;
   }

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

@@ -32,6 +32,11 @@ export class VoxCard extends LitElement {
       border-radius: var(--vox-radius-lg);
       padding: var(--vox-space-6);
       font-family: var(--vox-font-family-base);
+      /* Slotted content (e.g. an icon using stroke="currentColor")
+         inherits from this element's position in the flat tree — when
+         rendered as an <a>, that means the browser's default link color
+         without this, since nothing else in .card sets one. */
+      color: var(--vox-color-text-1);
       text-decoration: none;
       transition: border-color var(--vox-transition-base);
     }
@@ -124,7 +129,7 @@ export class VoxCard extends LitElement {
       <div class="badge ${this.hasBadge ? 'has-badge' : ''}">
         <slot name="badge" @slotchange=${this.handleBadgeSlotChange}></slot>
       </div>
-      <div class="icon ${this.hasIcon ? 'has-icon' : ''}">
+      <div class="icon ${this.hasIcon ? 'has-icon' : ''}" aria-hidden="true">
         <slot name="icon" @slotchange=${this.handleIconSlotChange}></slot>
       </div>
       <h3 class="heading">${this.heading}</h3>

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

@@ -60,10 +60,9 @@ export class VoxCheckbox extends VoxFieldElement {
 
   updated() {
     this.internals.setFormValue(this.checked ? this.value : null);
+    this.invalid = this.required && !this.checked;
     this.internals.setValidity(
-      this.required && !this.checked
-        ? { valueMissing: true }
-        : {},
+      this.invalid ? { valueMissing: true } : {},
       'Please check this box.',
       this.renderRoot.querySelector('input') ?? undefined,
     );
@@ -81,6 +80,8 @@ export class VoxCheckbox extends VoxFieldElement {
           type="checkbox"
           .checked=${this.checked}
           ?disabled=${this.disabled}
+          ?required=${this.required}
+          aria-invalid=${this.invalid ? 'true' : 'false'}
           @change=${this.handleChange}
         />
         <span class="box" aria-hidden="true">

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

@@ -148,12 +148,12 @@ export class VoxDialog extends LitElement {
   render() {
     return html`
       <dialog
-        aria-label=${this.heading || nothing}
+        aria-labelledby=${this.heading ? 'heading' : nothing}
         @close=${this.handleNativeClose}
         @click=${this.handleClick}
       >
         <div class="header">
-          <h2 class="heading">${this.heading}</h2>
+          <h2 class="heading" id="heading">${this.heading}</h2>
           <button class="close" aria-label="Close dialog" @click=${this.close}>
             <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" aria-hidden="true">
               <path d="M18 6 6 18M6 6l12 12" />

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

@@ -9,9 +9,13 @@ import { customElement, property } from 'lit/decorators.js';
  */
 @customElement('vox-disclosure')
 export class VoxDisclosure extends LitElement {
+  private static nextId = 0;
+
   @property() summary = 'Show details';
   @property({ type: Boolean, reflect: true }) open = false;
 
+  private readonly panelId = `vox-disclosure-panel-${VoxDisclosure.nextId++}`;
+
   static styles = css`
     :host {
       display: block;
@@ -77,6 +81,7 @@ export class VoxDisclosure extends LitElement {
       <button
         class="trigger"
         aria-expanded=${this.open ? 'true' : 'false'}
+        aria-controls=${this.panelId}
         @click=${this.toggle}
       >
         <svg class="chevron" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
@@ -84,7 +89,7 @@ export class VoxDisclosure extends LitElement {
         </svg>
         ${this.summary}
       </button>
-      <div class="panel" ?hidden=${!this.open}>
+      <div id=${this.panelId} class="panel" ?hidden=${!this.open}>
         <slot></slot>
       </div>
     `;

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

@@ -122,12 +122,14 @@ export class VoxDropdown extends LitElement {
     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) => {
@@ -136,6 +138,20 @@ export class VoxDropdown extends LitElement {
     }
   };
 
+  /** Close when focus leaves the component entirely (e.g. Tab past the last item). */
+  private handleFocusOut = (event: FocusEvent) => {
+    const next = event.relatedTarget as Node | null;
+    if (this.open && !(next && this.contains(next))) {
+      this.open = false;
+    }
+  };
+
+  private focusItem(index: number) {
+    const items = [...this.querySelectorAll<HTMLElement>('a, button')];
+    if (items.length === 0) return;
+    items[(index + items.length) % items.length].focus();
+  }
+
   private handleKeydown = (event: KeyboardEvent) => {
     if (event.key === 'Escape' && this.open) {
       this.open = false;
@@ -143,20 +159,27 @@ export class VoxDropdown extends LitElement {
       return;
     }
 
-    if ((event.key === 'ArrowDown' || event.key === 'ArrowUp') && this.open) {
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
       event.preventDefault();
-      const items = [...this.querySelectorAll<HTMLElement>('a, button')];
-      if (items.length === 0) return;
-      const active = document.activeElement as HTMLElement;
-      const index = items.indexOf(active);
       const delta = event.key === 'ArrowDown' ? 1 : -1;
-      const next = items[(Math.max(index, 0) + delta + items.length) % items.length];
-      next.focus();
+      if (!this.open) {
+        this.open = true;
+        this.updateComplete.then(() =>
+          this.focusItem(event.key === 'ArrowDown' ? 0 : -1),
+        );
+        return;
+      }
+      const items = [...this.querySelectorAll<HTMLElement>('a, button')];
+      const index = items.indexOf(document.activeElement as HTMLElement);
+      this.focusItem(Math.max(index, 0) + delta);
     }
   };
 
   private toggle() {
     this.open = !this.open;
+    if (this.open) {
+      this.updateComplete.then(() => this.focusItem(0));
+    }
   }
 
   render() {
@@ -165,6 +188,7 @@ export class VoxDropdown extends LitElement {
         class="trigger"
         aria-expanded=${this.open ? 'true' : 'false'}
         aria-haspopup="true"
+        aria-controls="menu"
         @click=${this.toggle}
       >
         ${this.label}
@@ -172,7 +196,7 @@ export class VoxDropdown extends LitElement {
           <path d="m6 9 6 6 6-6" />
         </svg>
       </button>
-      <div class="menu">
+      <div id="menu" class="menu">
         <slot @click=${() => (this.open = false)}></slot>
       </div>
     `;

package/src/components/empty-state/vox-empty-state.ts

@@ -60,7 +60,7 @@ export class VoxEmptyState extends LitElement {
   render() {
     return html`
       <div class="empty">
-        <div class="icon"><slot name="icon"></slot></div>
+        <div class="icon" aria-hidden="true"><slot name="icon"></slot></div>
         <h3 class="heading">${this.heading}</h3>
         <div class="body"><slot></slot></div>
         <div class="actions"><slot name="actions"></slot></div>

package/src/components/file-input/vox-file-input.ts

@@ -84,8 +84,9 @@ export class VoxFileInput extends VoxFieldElement {
     for (const file of files) data.append(this.name, file);
     this.internals.setFormValue(files.length > 0 ? data : null);
 
+    this.invalid = this.required && files.length === 0;
     this.internals.setValidity(
-      this.required && files.length === 0 ? { valueMissing: true } : {},
+      this.invalid ? { valueMissing: true } : {},
       'Please select a file.',
       this.inputEl,
     );
@@ -103,6 +104,8 @@ export class VoxFileInput extends VoxFieldElement {
             accept=${ifDefined(this.accept)}
             ?multiple=${this.multiple}
             ?disabled=${this.disabled}
+            aria-describedby=${ifDefined(this.noteId)}
+            aria-invalid=${this.invalid ? 'true' : 'false'}
             @change=${this.handleChange}
           />
           <span class="picker">