@openvoxproject/voxblocks 0.9.0

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@openvoxproject/voxblocks",
+  "version": "0.9.0",
+  "description": "Web components for Vox Pupuli OpenVox community web sites and apps",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OpenVoxProject/voxblocks.git"
+  },
+  "keywords": [
+    "web-components",
+    "lit",
+    "design-system",
+    "voxpupuli",
+    "openvox"
+  ],
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.stories.ts"
+  ],
+  "main": "./dist/voxblocks.js",
+  "module": "./dist/voxblocks.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/voxblocks.js"
+    },
+    "./voxblocks.css": "./dist/voxblocks.css",
+    "./cdn": "./dist/cdn/voxblocks.js",
+    "./cdn/voxblocks.css": "./dist/cdn/voxblocks.css"
+  },
+  "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",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
+  },
+  "dependencies": {
+    "lit": "^3.2.0"
+  },
+  "devDependencies": {
+    "@storybook/web-components": "^10.5.5",
+    "@storybook/web-components-vite": "^10.5.5",
+    "storybook": "^10.5.5",
+    "typescript": "^5.6.0",
+    "vite": "^6.0.0",
+    "vitepress": "^1.5.0"
+  },
+  "allowScripts": {
+    "esbuild@0.25.12": true,
+    "esbuild@0.21.5": true
+  }
+}

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

@@ -0,0 +1,150 @@
+import { LitElement, html, css } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+
+/**
+ * A stack of expandable panels.
+ *
+ * @slot - `<vox-accordion-item>` elements.
+ */
+@customElement('vox-accordion')
+export class VoxAccordion extends LitElement {
+  /** Allow only one panel open at a time. */
+  @property({ type: Boolean }) single = false;
+
+  static styles = css`
+    :host {
+      display: block;
+      border: 1px solid var(--vox-color-divider);
+      border-radius: var(--vox-radius-md);
+      overflow: hidden;
+    }
+
+    ::slotted(vox-accordion-item:not(:first-child)) {
+      border-top: 1px solid var(--vox-color-divider);
+    }
+  `;
+
+  private handleToggle(event: Event) {
+    if (!this.single) return;
+    const opened = event.target as VoxAccordionItem;
+    if (!opened.open) return;
+    this.querySelectorAll<VoxAccordionItem>('vox-accordion-item').forEach(
+      (item) => {
+        if (item !== opened) item.open = false;
+      },
+    );
+  }
+
+  render() {
+    return html`<slot @vox-toggle=${this.handleToggle}></slot>`;
+  }
+}
+
+/**
+ * One panel of a `<vox-accordion>`.
+ *
+ * @slot - Panel content.
+ * @fires vox-toggle - When the panel opens or closes.
+ */
+@customElement('vox-accordion-item')
+export class VoxAccordionItem extends LitElement {
+  @property() heading = '';
+  @property({ type: Boolean, reflect: true }) open = false;
+
+  static styles = css`
+    :host {
+      display: block;
+      font-family: var(--vox-font-family-base);
+    }
+
+    .trigger {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: var(--vox-space-3);
+      width: 100%;
+      padding: var(--vox-space-4);
+      background: none;
+      border: none;
+      color: var(--vox-color-text-1);
+      font-family: inherit;
+      font-size: 15px;
+      font-weight: 600;
+      text-align: left;
+      cursor: pointer;
+    }
+
+    .trigger:hover {
+      color: var(--vox-color-brand-1);
+    }
+
+    .trigger:focus-visible {
+      outline: 2px solid var(--vox-color-brand-1);
+      outline-offset: -2px;
+    }
+
+    .chevron {
+      flex: none;
+      width: 16px;
+      height: 16px;
+      transition: transform var(--vox-transition-fast);
+    }
+
+    :host([open]) .chevron {
+      transform: rotate(180deg);
+    }
+
+    .panel {
+      padding: 0 var(--vox-space-4) var(--vox-space-4);
+      font-size: 14px;
+      line-height: 1.7;
+      color: var(--vox-color-text-2);
+    }
+
+    .panel[hidden] {
+      display: none;
+    }
+
+    ::slotted(p:first-child) {
+      margin-top: 0;
+    }
+
+    ::slotted(p:last-child) {
+      margin-bottom: 0;
+    }
+  `;
+
+  toggle() {
+    this.open = !this.open;
+    this.dispatchEvent(
+      new CustomEvent('vox-toggle', { bubbles: true, composed: true }),
+    );
+  }
+
+  render() {
+    return html`
+      <h3 style="margin:0">
+        <button
+          class="trigger"
+          aria-expanded=${this.open ? 'true' : 'false'}
+          @click=${this.toggle}
+        >
+          ${this.heading}
+          <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">
+            <path d="m6 9 6 6 6-6" />
+          </svg>
+        </button>
+      </h3>
+      <div class="panel" ?hidden=${!this.open}>
+        <slot></slot>
+      </div>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vox-accordion': VoxAccordion;
+    'vox-accordion-item': VoxAccordionItem;
+  }
+}

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

@@ -0,0 +1,155 @@
+import { LitElement, html, css, nothing } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+
+export type AlertVariant = 'info' | 'success' | 'warning' | 'danger';
+
+/**
+ * A page-level notification message, optionally dismissible.
+ * For static advisory text inside prose, see `<vox-callout>`.
+ *
+ * @slot - Alert message.
+ * @fires vox-dismiss - When the user dismisses the alert.
+ */
+@customElement('vox-alert')
+export class VoxAlert extends LitElement {
+  @property() variant: AlertVariant = 'info';
+  @property() heading = '';
+  @property({ type: Boolean }) dismissible = false;
+  @property({ type: Boolean, reflect: true }) open = true;
+
+  static styles = css`
+    :host {
+      display: block;
+      font-family: var(--vox-font-family-base);
+    }
+
+    :host(:not([open])) {
+      display: none;
+    }
+
+    .alert {
+      display: flex;
+      gap: var(--vox-space-3);
+      align-items: flex-start;
+      padding: var(--vox-space-4);
+      border-radius: var(--vox-radius-md);
+      border-left: 4px solid;
+      font-size: 14px;
+      line-height: 1.6;
+      color: var(--vox-color-text-1);
+    }
+
+    .body {
+      flex: 1 1 auto;
+    }
+
+    .heading {
+      margin: 0 0 var(--vox-space-1);
+      font-size: 14px;
+      font-weight: 600;
+    }
+
+    .info {
+      background-color: var(--vox-color-brand-soft);
+      border-color: var(--vox-color-brand-1);
+    }
+    .info .heading {
+      color: var(--vox-color-brand-1);
+    }
+
+    .success {
+      background-color: var(--vox-color-tip-soft);
+      border-color: var(--vox-color-tip-1);
+    }
+    .success .heading {
+      color: var(--vox-color-tip-1);
+    }
+
+    .warning {
+      background-color: var(--vox-color-warning-soft);
+      border-color: var(--vox-color-warning-1);
+    }
+    .warning .heading {
+      color: var(--vox-color-warning-1);
+    }
+
+    .danger {
+      background-color: var(--vox-color-danger-soft);
+      border-color: var(--vox-color-danger-1);
+    }
+    .danger .heading {
+      color: var(--vox-color-danger-1);
+    }
+
+    .close {
+      flex: none;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      width: 24px;
+      height: 24px;
+      padding: 0;
+      background: none;
+      border: none;
+      border-radius: var(--vox-radius-sm);
+      color: var(--vox-color-text-2);
+      cursor: pointer;
+    }
+
+    .close:hover {
+      color: var(--vox-color-text-1);
+    }
+
+    .close:focus-visible {
+      outline: 2px solid var(--vox-color-brand-1);
+    }
+
+    .close svg {
+      width: 14px;
+      height: 14px;
+    }
+
+    ::slotted(p:first-child) {
+      margin-top: 0;
+    }
+
+    ::slotted(p:last-child) {
+      margin-bottom: 0;
+    }
+  `;
+
+  dismiss() {
+    this.open = false;
+    this.dispatchEvent(
+      new CustomEvent('vox-dismiss', { bubbles: true, composed: true }),
+    );
+  }
+
+  render() {
+    return html`
+      <div class="alert ${this.variant}" role="alert">
+        <div class="body">
+          ${this.heading
+            ? html`<p class="heading">${this.heading}</p>`
+            : nothing}
+          <slot></slot>
+        </div>
+        ${this.dismissible
+          ? html`
+              <button class="close" aria-label="Dismiss" @click=${this.dismiss}>
+                <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" />
+                </svg>
+              </button>
+            `
+          : nothing}
+      </div>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vox-alert': VoxAlert;
+  }
+}

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

@@ -0,0 +1,80 @@
+import { LitElement, html, css } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+
+export type AvatarSize = 'sm' | 'md' | 'lg' | 'xl';
+
+/**
+ * A circular avatar showing an image, or initials as a fallback.
+ */
+@customElement('vox-avatar')
+export class VoxAvatar extends LitElement {
+  @property() src?: string;
+  @property() alt = '';
+  @property() initials = '';
+  @property({ reflect: true }) size: AvatarSize = 'md';
+
+  static styles = css`
+    :host {
+      display: inline-block;
+    }
+
+    .avatar {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      overflow: hidden;
+      border-radius: 50%;
+      background-color: var(--vox-color-brand-soft);
+      color: var(--vox-color-brand-1);
+      font-family: var(--vox-font-family-base);
+      font-weight: 600;
+      user-select: none;
+    }
+
+    img {
+      width: 100%;
+      height: 100%;
+      object-fit: cover;
+    }
+
+    :host([size='sm']) .avatar {
+      width: 28px;
+      height: 28px;
+      font-size: 11px;
+    }
+
+    :host([size='md']) .avatar {
+      width: 40px;
+      height: 40px;
+      font-size: 14px;
+    }
+
+    :host([size='lg']) .avatar {
+      width: 56px;
+      height: 56px;
+      font-size: 20px;
+    }
+
+    :host([size='xl']) .avatar {
+      width: 80px;
+      height: 80px;
+      font-size: 28px;
+    }
+  `;
+
+  render() {
+    return html`
+      <span class="avatar" role=${this.src ? 'presentation' : 'img'} aria-label=${this.alt}>
+        ${this.src
+          ? html`<img src=${this.src} alt=${this.alt} />`
+          : this.initials}
+      </span>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vox-avatar': VoxAvatar;
+  }
+}

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

@@ -0,0 +1,67 @@
+import { LitElement, html, css } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+
+export type BadgeVariant = 'brand' | 'tip' | 'warning' | 'danger' | 'neutral';
+
+/**
+ * A small status pill, e.g. for version labels or deprecation notices.
+ *
+ * @slot - Badge label.
+ */
+@customElement('vox-badge')
+export class VoxBadge extends LitElement {
+  @property() variant: BadgeVariant = 'brand';
+
+  static styles = css`
+    :host {
+      display: inline-block;
+    }
+
+    .badge {
+      display: inline-flex;
+      align-items: center;
+      padding: 2px 10px;
+      border-radius: var(--vox-radius-full);
+      font-family: var(--vox-font-family-base);
+      font-size: 12px;
+      font-weight: 600;
+      line-height: 1.6;
+      white-space: nowrap;
+    }
+
+    .brand {
+      background-color: var(--vox-color-brand-soft);
+      color: var(--vox-color-brand-1);
+    }
+
+    .tip {
+      background-color: var(--vox-color-tip-soft);
+      color: var(--vox-color-tip-1);
+    }
+
+    .warning {
+      background-color: var(--vox-color-warning-soft);
+      color: var(--vox-color-warning-1);
+    }
+
+    .danger {
+      background-color: var(--vox-color-danger-soft);
+      color: var(--vox-color-danger-1);
+    }
+
+    .neutral {
+      background-color: var(--vox-color-bg-soft);
+      color: var(--vox-color-text-2);
+    }
+  `;
+
+  render() {
+    return html`<span class="badge ${this.variant}"><slot></slot></span>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vox-badge': VoxBadge;
+  }
+}

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

@@ -0,0 +1,109 @@
+import { LitElement, html, css } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+
+/**
+ * A split media-and-content section for landing pages.
+ *
+ * @slot media - Image or other media shown beside the content.
+ * @slot - Body content.
+ * @slot actions - Buttons or CTA links below the body.
+ */
+@customElement('vox-billboard')
+export class VoxBillboard extends LitElement {
+  @property() heading = '';
+
+  /** Put the media on the right instead of the left. */
+  @property({ type: Boolean, reflect: true }) reverse = false;
+
+  static styles = css`
+    :host {
+      display: block;
+      font-family: var(--vox-font-family-base);
+    }
+
+    .billboard {
+      display: flex;
+      gap: var(--vox-space-8);
+      align-items: center;
+      flex-wrap: wrap;
+      padding: var(--vox-space-8);
+      background-color: var(--vox-color-bg-soft);
+      border-radius: var(--vox-radius-lg);
+    }
+
+    :host([reverse]) .billboard {
+      flex-direction: row-reverse;
+    }
+
+    .media {
+      flex: 1 1 280px;
+      min-width: 0;
+    }
+
+    .media ::slotted(img) {
+      display: block;
+      max-width: 100%;
+      border-radius: var(--vox-radius-md);
+    }
+
+    .content {
+      flex: 1 1 320px;
+      min-width: 0;
+    }
+
+    .heading {
+      margin: 0 0 var(--vox-space-3);
+      font-family: var(--vox-font-family-display);
+      font-size: 28px;
+      font-weight: 600;
+      line-height: 1.3;
+      color: var(--vox-color-text-1);
+    }
+
+    .body {
+      font-size: 16px;
+      line-height: 1.7;
+      color: var(--vox-color-text-2);
+    }
+
+    .actions {
+      display: flex;
+      gap: var(--vox-space-3);
+      flex-wrap: wrap;
+      margin-top: var(--vox-space-6);
+    }
+
+    .actions:not(.has-content) {
+      display: none;
+    }
+  `;
+
+  private hasActions = false;
+
+  private handleActionsSlotChange(event: Event) {
+    const slot = event.target as HTMLSlotElement;
+    this.hasActions = slot.assignedNodes({ flatten: true }).length > 0;
+    this.requestUpdate();
+  }
+
+  render() {
+    return html`
+      <div class="billboard">
+        <div class="media"><slot name="media"></slot></div>
+        <div class="content">
+          <h2 class="heading">${this.heading}</h2>
+          <div class="body"><slot></slot></div>
+          <div class="actions ${this.hasActions ? 'has-content' : ''}">
+            <slot name="actions" @slotchange=${this.handleActionsSlotChange}></slot>
+          </div>
+        </div>
+      </div>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vox-billboard': VoxBillboard;
+  }
+}

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

@@ -0,0 +1,68 @@
+import { LitElement, html, css } from 'lit';
+import { customElement } from 'lit/decorators.js';
+
+/**
+ * A breadcrumb trail. Children are plain links, with the current page
+ * as a `<span aria-current="page">`:
+ *
+ * ```html
+ * <vox-breadcrumbs>
+ *   <a href="/">Home</a>
+ *   <a href="/modules">Modules</a>
+ *   <span aria-current="page">puppet-nginx</span>
+ * </vox-breadcrumbs>
+ * ```
+ *
+ * @slot - Links and the current-page span.
+ */
+@customElement('vox-breadcrumbs')
+export class VoxBreadcrumbs extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+      font-family: var(--vox-font-family-base);
+    }
+
+    nav {
+      display: flex;
+      align-items: center;
+      flex-wrap: wrap;
+      font-size: 13px;
+    }
+
+    ::slotted(*) {
+      color: var(--vox-color-text-2);
+      text-decoration: none;
+    }
+
+    ::slotted(a:hover) {
+      color: var(--vox-color-brand-1);
+      text-decoration: underline;
+    }
+
+    ::slotted([aria-current='page']) {
+      color: var(--vox-color-text-1);
+      font-weight: 600;
+    }
+
+    ::slotted(*:not(:first-child))::before {
+      content: '/';
+      margin: 0 var(--vox-space-2);
+      color: var(--vox-color-text-3);
+    }
+  `;
+
+  render() {
+    return html`
+      <nav aria-label="Breadcrumbs">
+        <slot></slot>
+      </nav>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vox-breadcrumbs': VoxBreadcrumbs;
+  }
+}