Peek UI Components#

A lightweight, themeable web component library with a "native-first" approach. Uses Lit.js minimally for reactive rendering while maximizing native browser APIs and following Open UI specifications.

Native APIs Used:

• <dialog> - Dialogs
• <details>/<summary> - Disclosure/accordion
• Popover API - Floating content, dropdowns
• CSS scroll-snap - Carousels
• ARIA patterns - Accessibility

Quick Start#

<!-- Import all components -->
<script type="module" src="peek://app/components/index.js"></script>

<!-- Or import individually -->
<script type="module" src="peek://app/components/peek-button.js"></script>

<!-- Use components -->
<peek-button variant="primary">Save</peek-button>
<peek-card>
  <span slot="header">Card Title</span>
  <p>Card content here</p>
</peek-card>

Theming#

Components inherit from the Peek theme system (peek://theme/variables.css). Override component tokens via CSS custom properties:

/* Global theming */
:root {
  --theme-accent: #ff6b35;
  --peek-radius-md: 8px;
}

/* Component-specific overrides */
peek-button {
  --peek-btn-bg: #333;
  --peek-btn-text: #fff;
}

Design Tokens#

All components share these tokens:

Components#

<peek-button>#

A themeable button built on native <button> for accessibility.

Properties#

Slots#

CSS Parts#

CSS Custom Properties#

Examples#

<!-- Variants -->
<peek-button variant="primary">Primary</peek-button>
<peek-button variant="secondary">Secondary</peek-button>
<peek-button variant="ghost">Ghost</peek-button>
<peek-button variant="danger">Delete</peek-button>

<!-- Sizes -->
<peek-button size="sm">Small</peek-button>
<peek-button size="md">Medium</peek-button>
<peek-button size="lg">Large</peek-button>

<!-- States -->
<peek-button disabled>Disabled</peek-button>
<peek-button loading>Loading</peek-button>

<!-- With icons -->
<peek-button>
  <svg slot="prefix">...</svg>
  Save
</peek-button>

<peek-card>#

A flexible card container with header, body, and footer slots.

Properties#

Slots#

CSS Parts#

CSS Custom Properties#

Events#

Examples#

<!-- Basic card -->
<peek-card>
  <span slot="header">Card Title</span>
  <p>Card content goes here.</p>
  <span slot="footer">Updated 2 hours ago</span>
</peek-card>

<!-- Interactive card -->
<peek-card interactive elevated>
  <img slot="media" src="image.jpg" alt="Preview">
  <h3 slot="header">Clickable Card</h3>
  <p>Click anywhere on this card.</p>
</peek-card>

<!-- Selected card -->
<peek-card selected>
  <span slot="header">Selected Item</span>
  <p>This card is in selected state.</p>
</peek-card>

<peek-list> and <peek-list-item>#

A keyboard-navigable list with selection support.

<peek-list> Properties#

<peek-list-item> Properties#

Slots#

<peek-list>:

<peek-list-item>:

CSS Parts#

CSS Custom Properties#

Events#

Keyboard Navigation#

Examples#

<!-- Single selection -->
<peek-list selection="single" @selection-change=${handleChange}>
  <peek-list-item value="1">Option 1</peek-list-item>
  <peek-list-item value="2">Option 2</peek-list-item>
  <peek-list-item value="3">Option 3</peek-list-item>
</peek-list>

<!-- Multiple selection -->
<peek-list selection="multiple" wrap>
  <peek-list-item>
    <svg slot="prefix">...</svg>
    Item with icon
    <span slot="suffix">Badge</span>
  </peek-list-item>
  <peek-list-item disabled>Disabled item</peek-list-item>
</peek-list>

<!-- Navigation list (no selection) -->
<peek-list @item-activate=${navigate}>
  <peek-list-item value="/home">Home</peek-list-item>
  <peek-list-item value="/settings">Settings</peek-list-item>
</peek-list>

Extending Components#

Create custom components by extending PeekElement:

import { html, css } from 'lit';
import { PeekElement, sharedStyles } from 'peek://app/components/base.js';

class MyComponent extends PeekElement {
  static styles = [
    sharedStyles,
    css`
      :host {
        display: block;
      }
      /* Component styles */
    `
  ];

  render() {
    return html`<div>My component</div>`;
  }
}

customElements.define('my-component', MyComponent);

PeekElement Utilities#

Reactive System#

Signals#

Reactive primitives for state management. Native JavaScript implementation following the TC39 Signals proposal pattern.

import { signal, computed, effect, batch, watch } from 'peek://app/components/signals.js';

// Create reactive value
const count = signal(0);
console.log(count.value); // 0

// Computed values auto-update
const doubled = computed(() => count.value * 2);

// Effects run when dependencies change
const dispose = effect(() => {
  console.log(`Count: ${count.value}, Doubled: ${doubled.value}`);
});

// Update triggers effect
count.value = 5; // Logs: "Count: 5, Doubled: 10"

// Batch multiple updates
batch(() => {
  count.value = 10;
  // other updates...
}); // Effects run once at end

// Watch specific signal
const stop = watch(count, (newVal, oldVal) => {
  console.log(`Changed from ${oldVal} to ${newVal}`);
});

// Cleanup
dispose();
stop();

Signal API#

Schema Validation#

Lightweight JSON Schema validation for component data.

import { validate, createValidator, Schema } from 'peek://app/components/schema.js';

// Define schema
const userSchema = {
  type: 'object',
  required: ['name', 'email'],
  properties: {
    name: { type: 'string', minLength: 1 },
    email: { type: 'string', format: 'email' },
    age: { type: 'integer', minimum: 0, default: 0 }
  }
};

// Validate data
const result = validate({ name: 'Alice', email: 'alice@example.com' }, userSchema);
// { valid: true, errors: [], data: { name: 'Alice', email: 'alice@example.com', age: 0 } }

// Create reusable validator
const validateUser = createValidator(userSchema);
validateUser({ name: '', email: 'invalid' });
// { valid: false, errors: [...] }

// Schema builders
const schema = Schema.object({
  title: Schema.string({ minLength: 1 }),
  count: Schema.integer({ minimum: 0 }),
  tags: Schema.array(Schema.string())
}, { required: ['title'] });

Supported Keywords#

Data Binding#

Bind components to reactive data sources with automatic updates.

import { DataBoundElement, createDataComponent } from 'peek://app/components/data-binding.js';
import { signal } from 'peek://app/components/signals.js';
import { html, css } from 'lit';

// Extend DataBoundElement
class UserCard extends DataBoundElement {
  static dataSchema = {
    type: 'object',
    properties: {
      name: { type: 'string' },
      avatar: { type: 'string', format: 'uri' }
    }
  };

  render() {
    return html`
      <img src=${this.data.avatar}>
      <span>${this.data.name}</span>
    `;
  }
}
customElements.define('user-card', UserCard);

// Bind to signal
const userData = signal({ name: 'Alice', avatar: 'https://...' });
const card = document.querySelector('user-card');
card.bindTo(userData);

// Updates automatically when signal changes
userData.value = { name: 'Bob', avatar: 'https://...' };

// Or create data component dynamically
const StatusBadge = createDataComponent('status-badge', {
  schema: { type: 'object', properties: { status: { type: 'string' } } },
  render: (data) => html`<span class=${data.status}>${data.status}</span>`
});

DataBoundElement API#

Event Bus#

Cross-component communication that works across Shadow DOM.

import { on, emit, channel, waitFor, EventBusMixin } from 'peek://app/components/events.js';

// Subscribe to events
const unsubscribe = on('user:login', (user) => {
  console.log('User logged in:', user.name);
});

// Emit events
emit('user:login', { name: 'Alice', id: 123 });

// Wildcard subscriptions
on('user:*', (data, eventName) => {
  console.log(`User event: ${eventName}`, data);
});

// Namespaced channels
const userChannel = channel('user');
userChannel.on('login', handler);
userChannel.emit('login', userData);
userChannel.onAny(handler); // All 'user:*' events

// Promise-based waiting
const user = await waitFor('user:login', { timeout: 5000 });

// Replay last value
emit('config:loaded', config, { retain: true });
on('config:loaded', handler, { replay: true }); // Gets config immediately

// Unsubscribe
unsubscribe.unsubscribe();

Component Integration#

import { EventBusMixin } from 'peek://app/components/events.js';
import { PeekElement } from 'peek://app/components/base.js';

class MyComponent extends EventBusMixin(PeekElement) {
  connectedCallback() {
    super.connectedCallback();
    // Auto-cleanup on disconnect
    this.subscribe('data:update', this.handleUpdate);
  }

  handleUpdate = (data) => {
    this.data = data;
  }

  save() {
    this.publish('data:saved', this.data);
  }
}

Event Bus API#

Theme System#

Dynamic theme registration, switching, and token inheritance.

import {
  registerTheme, setTheme, getTheme,
  onThemeChange, followSystemTheme,
  ThemeMixin
} from 'peek://app/components/theme.js';

// Built-in themes: 'light', 'dark'
setTheme('dark');

// Register custom theme (extends light by default)
registerTheme('brand', {
  'theme-accent': '#ff6b35',
  'theme-bg': '#fefefe',
  'peek-radius-md': '12px'
});

// Extend a specific theme
registerTheme('brand-dark', {
  'theme-accent': '#ff8c5a'
}, { extends: 'dark' });

// Listen for theme changes
const unsubscribe = onThemeChange(({ theme, previousTheme }) => {
  console.log(`Theme changed from ${previousTheme} to ${theme}`);
});

// Auto-follow system preference (light/dark)
const stopFollowing = followSystemTheme();

// Get/set individual tokens
import { getToken, setToken } from 'peek://app/components/theme.js';
const accent = getToken('theme-accent');
setToken('theme-accent', '#00ff00');

Theme API#

Available Tokens#

See Design Tokens for the full list. Key theme tokens:

Extension System#

Tools for extensions to register, inject styles, and create isolated component containers.

import {
  registerExtension,
  initContentScript,
  initPopup
} from 'peek://app/components/extension.js';

// Register extension with custom theme
const ext = registerExtension('my-extension', {
  theme: {
    'theme-accent': '#9b59b6',
    'peek-card-bg': '#f8f8f8'
  }
});

// Inject styles into document
ext.injectStyles(document);

// Create isolated shadow DOM container
const container = ext.createContainer();
container.innerHTML = '<peek-card>...</peek-card>';

// Clean up when done
ext.destroy();

Content Script Usage#

import { initContentScript } from 'peek://app/components/extension.js';

// One-call setup for content scripts
const { container, context, destroy } = initContentScript({
  id: 'my-content-script',
  theme: { 'theme-accent': '#e74c3c' },
  parent: document.body,
  render: (shadow) => {
    shadow.innerHTML = `
      <peek-card>
        <span slot="header">Injected Card</span>
        <p>Content script UI</p>
      </peek-card>
    `;
  }
});

// Later: cleanup
destroy();

Popup/Sidebar Usage#

import { initPopup } from 'peek://app/components/extension.js';

// Initialize popup with theming
const context = initPopup({
  id: 'my-popup',
  theme: { 'theme-accent': '#3498db' }
});

Extension API#

ExtensionContext Methods#

Complex Components#

<peek-carousel>#

A scroll-snap based carousel for horizontal or vertical content.

Properties#

Events#

Methods#

Example#

<peek-carousel controls indicators loop>
  <img src="slide1.jpg" alt="Slide 1">
  <img src="slide2.jpg" alt="Slide 2">
  <img src="slide3.jpg" alt="Slide 3">
</peek-carousel>

<!-- Vertical carousel -->
<peek-carousel direction="vertical" style="--peek-carousel-height: 400px">
  <div>Item 1</div>
  <div>Item 2</div>
</peek-carousel>

<peek-input>#

Input field with autocomplete suggestions dropdown.

Properties#

Slots#

Events#

Example#

<peek-input
  placeholder="Search tags..."
  .suggestions=${['work', 'personal', 'urgent', 'todo']}
  @suggestion-select=${(e) => addTag(e.detail.value)}
>
  <svg slot="prefix"><!-- search icon --></svg>
</peek-input>

<!-- With object suggestions -->
<peek-input
  .suggestions=${[{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]}
  suggestion-key="name"
></peek-input>

<peek-grid>#

Responsive CSS Grid layout with auto-fit columns.

Properties#

Example#

<!-- Auto-fit grid -->
<peek-grid min-item-width="300" gap="20">
  <peek-card>Card 1</peek-card>
  <peek-card>Card 2</peek-card>
  <peek-card>Card 3</peek-card>
</peek-grid>

<!-- Fixed 3-column grid -->
<peek-grid columns="3">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</peek-grid>

<!-- With spanning items -->
<peek-grid>
  <peek-grid-item col-span="2">Wide item</peek-grid-item>
  <peek-grid-item>Normal</peek-grid-item>
  <peek-grid-item row-span="2">Tall item</peek-grid-item>
</peek-grid>

<peek-dialog>#

Modal/non-modal dialog using native <dialog> element.

Properties#

Slots#

Events#

Methods#

Example#

<peek-dialog id="confirmDialog" size="sm">
  <span slot="header">Confirm Delete</span>
  <p>Are you sure you want to delete this item?</p>
  <div slot="footer">
    <peek-button variant="ghost" onclick="confirmDialog.close()">
      Cancel
    </peek-button>
    <peek-button variant="danger" onclick="deleteItem()">
      Delete
    </peek-button>
  </div>
</peek-dialog>

<peek-button onclick="confirmDialog.show()">Delete Item</peek-button>

Native/Open UI Components#

<peek-popover>#

Native Popover API wrapper for tooltips, dropdowns, and floating content.

Properties#

Slots#

CSS Parts#

Events#

Methods#

Example#

<!-- Basic popover -->
<peek-popover>
  <peek-button slot="trigger">Open Menu</peek-button>
  <div>Popover content here</div>
</peek-popover>

<!-- Tooltip-style (top position) -->
<peek-popover position="top" offset="4">
  <span slot="trigger">Hover target</span>
  <span>Tooltip text</span>
</peek-popover>

<!-- Manual control (no light-dismiss) -->
<peek-popover mode="manual" id="menuPopover">
  <peek-button slot="trigger">Settings</peek-button>
  <peek-list>
    <peek-list-item @click=${() => menuPopover.hide()}>Option 1</peek-list-item>
    <peek-list-item @click=${() => menuPopover.hide()}>Option 2</peek-list-item>
  </peek-list>
</peek-popover>

<peek-tabs>, <peek-tab>, <peek-tab-panel>#

Accessible tabs following Open UI tablist/tab/tabpanel pattern with full ARIA support.

<peek-tabs> Properties#

<peek-tab> Properties#

Slots#

<peek-tabs>: Contains <peek-tab> elements (in tablist) and <peek-tab-panel> elements

<peek-tab>: Tab label content

<peek-tab-panel>: Panel content

CSS Parts#

Events#

Keyboard Navigation#

Methods#

Example#

<peek-tabs @tab-change=${handleTabChange}>
  <peek-tab>General</peek-tab>
  <peek-tab>Advanced</peek-tab>
  <peek-tab disabled>Locked</peek-tab>

  <peek-tab-panel>
    <p>General settings content</p>
  </peek-tab-panel>
  <peek-tab-panel>
    <p>Advanced settings content</p>
  </peek-tab-panel>
  <peek-tab-panel>
    <p>This panel is not accessible</p>
  </peek-tab-panel>
</peek-tabs>

<!-- Manual activation (requires Enter to select) -->
<peek-tabs activation="manual">
  <peek-tab>Tab 1</peek-tab>
  <peek-tab>Tab 2</peek-tab>
  <peek-tab-panel>Content 1</peek-tab-panel>
  <peek-tab-panel>Content 2</peek-tab-panel>
</peek-tabs>

<peek-details>#

Native <details>/<summary> wrapper with styling and accordion support.

Properties#

Slots#

CSS Parts#

Events#

Methods#

Example#

<!-- Single disclosure -->
<peek-details>
  <span slot="summary">Click to expand</span>
  <p>Hidden content revealed when expanded.</p>
</peek-details>

<!-- Initially open -->
<peek-details open>
  <span slot="summary">Already expanded</span>
  <p>This content is visible by default.</p>
</peek-details>

<!-- Exclusive accordion (native behavior) -->
<peek-details name="faq">
  <span slot="summary">Question 1</span>
  <p>Answer 1</p>
</peek-details>
<peek-details name="faq">
  <span slot="summary">Question 2</span>
  <p>Answer 2</p>
</peek-details>
<peek-details name="faq">
  <span slot="summary">Question 3</span>
  <p>Answer 3</p>
</peek-details>

Phase 4 Components#

<peek-select>#

Select/combobox with native and custom modes.

Properties#

Events#

Example#

<!-- Native select -->
<peek-select
  placeholder="Choose a color"
  .options=${['Red', 'Green', 'Blue']}
  @change=${(e) => console.log(e.detail.value)}
></peek-select>

<!-- Custom styled select -->
<peek-select
  mode="custom"
  .options=${[
    { value: 'sm', label: 'Small' },
    { value: 'md', label: 'Medium' },
    { value: 'lg', label: 'Large', disabled: true }
  ]}
></peek-select>

<peek-dropdown>, <peek-dropdown-item>, <peek-dropdown-divider>#

Action menu / context menu using Popover API.

<peek-dropdown> Properties#

<peek-dropdown-item> Properties#

Slots#

<peek-dropdown>:

<peek-dropdown-item>:

Events#

Example#

<peek-dropdown @select=${(e) => handleAction(e.detail.value)}>
  <peek-button slot="trigger">Actions</peek-button>

  <peek-dropdown-item value="edit">
    <svg slot="prefix">...</svg>
    Edit
    <span slot="suffix">⌘E</span>
  </peek-dropdown-item>
  <peek-dropdown-item value="duplicate">Duplicate</peek-dropdown-item>
  <peek-dropdown-divider></peek-dropdown-divider>
  <peek-dropdown-item value="delete" danger>Delete</peek-dropdown-item>
</peek-dropdown>

<peek-switch>#

Toggle switch built on native checkbox.

Properties#

Slots#

Events#

Methods#

Example#

<!-- Basic switch -->
<peek-switch @change=${(e) => setDarkMode(e.detail.checked)}>
  Dark mode
</peek-switch>

<!-- With on/off labels -->
<peek-switch checked>
  <span slot="on">ON</span>
  <span slot="off">OFF</span>
  Notifications
</peek-switch>

<!-- Sizes -->
<peek-switch size="sm">Small</peek-switch>
<peek-switch size="lg">Large</peek-switch>

<peek-drawer>#

Slide-out panel using native <dialog>.

Properties#

Slots#

CSS Parts#

Events#

Methods#

Example#

<peek-drawer id="settingsDrawer" position="right" size="400px">
  <span slot="header">Settings</span>

  <peek-list>
    <peek-list-item>Profile</peek-list-item>
    <peek-list-item>Preferences</peek-list-item>
    <peek-list-item>Security</peek-list-item>
  </peek-list>

  <div slot="footer">
    <peek-button @click=${() => settingsDrawer.close()}>Close</peek-button>
  </div>
</peek-drawer>

<peek-button @click=${() => settingsDrawer.show()}>Open Settings</peek-button>

<peek-tooltip>#

Hover-triggered tooltip using Popover API.

Properties#

Slots#

Methods#

Example#

<!-- Basic tooltip -->
<peek-tooltip content="Save your changes">
  <peek-button>Save</peek-button>
</peek-tooltip>

<!-- Different positions -->
<peek-tooltip content="Top" position="top">
  <span>Hover me</span>
</peek-tooltip>

<peek-tooltip content="Right side" position="right" delay="0">
  <span>Instant tooltip</span>
</peek-tooltip>

<peek-button-group>, <peek-button-group-item>#

Segmented controls and tag sets with selection.

<peek-button-group> Properties#

<peek-button-group-item> Properties#

Slots#

<peek-button-group-item>:

Events#

Methods#

Example#

<!-- Segmented control (single selection) -->
<peek-button-group value="day" @change=${(e) => setView(e.detail.value)}>
  <peek-button-group-item value="day">Day</peek-button-group-item>
  <peek-button-group-item value="week">Week</peek-button-group-item>
  <peek-button-group-item value="month">Month</peek-button-group-item>
</peek-button-group>

<!-- Tag set (multiple selection) -->
<peek-button-group
  selection="multiple"
  variant="ghost"
  .values=${['urgent', 'work']}
>
  <peek-button-group-item value="urgent">Urgent</peek-button-group-item>
  <peek-button-group-item value="work">Work</peek-button-group-item>
  <peek-button-group-item value="personal">Personal</peek-button-group-item>
</peek-button-group>

<!-- With icons -->
<peek-button-group selection="single" size="sm">
  <peek-button-group-item value="list">
    <svg slot="prefix">...</svg>
  </peek-button-group-item>
  <peek-button-group-item value="grid">
    <svg slot="prefix">...</svg>
  </peek-button-group-item>
</peek-button-group>

Browser Support#

Components use modern CSS and HTML features:

CSS:

• CSS custom properties
• color-mix() for color adjustments
• :focus-visible for keyboard focus styles
• CSS Grid and Flexbox
• CSS scroll-snap (carousels)
• @starting-style for entry animations

Native APIs:

• Popover API (popover attribute, showPopover()) - Chrome 114+, Safari 17+, Firefox 125+
• <dialog> element - All modern browsers
• <details>/<summary> elements - All modern browsers
• name attribute for exclusive accordions - Chrome 120+, Safari 17.2+

Supported in all modern browsers (Chrome 120+, Firefox 125+, Safari 17.2+, Edge 120+).

Extension Developer Guide#

Complete guide for building Peek extensions with the component library.

Getting Started#

// Import components you need
import {
  PeekButton, PeekCard, PeekList,
  registerExtension, setTheme
} from 'peek://app/components/index.js';

// Or import everything
import 'peek://app/components/index.js';

Project Structure#

my-extension/
├── manifest.json
├── background.js
├── content.js          # Content script
├── popup/
│   ├── popup.html
│   └── popup.js
└── styles/
    └── theme.js        # Custom theme tokens

Content Script Pattern#

Content scripts need style isolation to avoid conflicts with host pages:

// content.js
import { initContentScript } from 'peek://app/components/extension.js';

const { container, destroy } = initContentScript({
  id: 'my-extension',
  theme: {
    'theme-accent': '#9b59b6'
  },
  render: (shadow) => {
    // Shadow DOM container - styles are isolated
    shadow.innerHTML = `
      <div class="my-extension-ui">
        <peek-card>
          <span slot="header">My Extension</span>
          <peek-list selection="single">
            <peek-list-item value="1">Item 1</peek-list-item>
            <peek-list-item value="2">Item 2</peek-list-item>
          </peek-list>
          <div slot="footer">
            <peek-button variant="primary">Action</peek-button>
          </div>
        </peek-card>
      </div>
    `;

    // Add event listeners
    shadow.querySelector('peek-list').addEventListener('selection-change', (e) => {
      console.log('Selected:', e.detail);
    });
  }
});

// Cleanup when extension unloads
window.addEventListener('unload', destroy);

Popup Pattern#

<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
  <style>
    body { width: 320px; padding: 16px; margin: 0; }
  </style>
</head>
<body>
  <peek-card>
    <span slot="header">Settings</span>
    <peek-switch id="darkMode">Dark Mode</peek-switch>
    <peek-select id="theme" placeholder="Choose theme"></peek-select>
  </peek-card>
  <script type="module" src="popup.js"></script>
</body>
</html>

// popup.js
import { initPopup, setTheme, getThemeNames } from 'peek://app/components/index.js';

initPopup({ id: 'my-popup' });

// Setup theme selector
const themeSelect = document.getElementById('theme');
themeSelect.options = getThemeNames();
themeSelect.addEventListener('change', (e) => setTheme(e.detail.value));

// Dark mode toggle
document.getElementById('darkMode').addEventListener('change', (e) => {
  setTheme(e.detail.checked ? 'dark' : 'light');
});

Custom Theming#

// theme.js - Define your extension's theme
import { registerTheme } from 'peek://app/components/theme.js';

// Extend the light theme
registerTheme('my-brand', {
  'theme-accent': '#e74c3c',
  'theme-accent-hover': '#c0392b',
  'peek-radius-md': '8px',
  'peek-btn-height-md': '40px'
});

// Dark variant
registerTheme('my-brand-dark', {
  'theme-accent': '#e74c3c',
  'theme-bg': '#1e1e1e',
  'theme-text': '#f0f0f0'
}, { extends: 'dark' });

export { 'my-brand', 'my-brand-dark' };

Data-Driven Components#

import { signal, effect } from 'peek://app/components/signals.js';
import { DataBoundElement } from 'peek://app/components/data-binding.js';

// Create reactive data
const items = signal([
  { id: 1, name: 'Task 1', done: false },
  { id: 2, name: 'Task 2', done: true }
]);

// Update UI automatically when data changes
effect(() => {
  const list = document.querySelector('peek-list');
  list.innerHTML = items.value.map(item => `
    <peek-list-item value="${item.id}" ${item.done ? 'selected' : ''}>
      ${item.name}
    </peek-list-item>
  `).join('');
});

// Add item
function addItem(name) {
  items.value = [...items.value, { id: Date.now(), name, done: false }];
}

Cross-Component Communication#

import { on, emit, channel } from 'peek://app/components/events.js';

// Create namespaced channel
const taskChannel = channel('tasks');

// Subscribe to events
taskChannel.on('add', (task) => {
  console.log('Task added:', task);
});

taskChannel.on('complete', (taskId) => {
  console.log('Task completed:', taskId);
});

// Emit events
taskChannel.emit('add', { id: 1, name: 'New task' });

// Wait for event (async)
const task = await taskChannel.waitFor('add', { timeout: 5000 });

Form Validation#

import { validate, Schema } from 'peek://app/components/schema.js';

const formSchema = Schema.object({
  email: Schema.string({ format: 'email' }),
  password: Schema.string({ minLength: 8 }),
  age: Schema.integer({ minimum: 18 })
}, { required: ['email', 'password'] });

function handleSubmit(formData) {
  const result = validate(formData, formSchema);

  if (!result.valid) {
    result.errors.forEach(err => {
      console.error(`${err.path}: ${err.message}`);
    });
    return;
  }

  // Process valid data
  submitForm(result.data);
}

Responsive Layouts#

<!-- Auto-fit grid -->
<peek-grid min-item-width="200" gap="16">
  <peek-card>Card 1</peek-card>
  <peek-card>Card 2</peek-card>
  <peek-card>Card 3</peek-card>
</peek-grid>

<!-- Fixed columns -->
<peek-grid columns="2">
  <peek-grid-item col-span="2">Wide item</peek-grid-item>
  <peek-grid-item>Normal</peek-grid-item>
  <peek-grid-item>Normal</peek-grid-item>
</peek-grid>

Accessibility Patterns#

<!-- Keyboard navigable list with selection -->
<peek-list selection="single" wrap>
  <peek-list-item value="opt1">Option 1</peek-list-item>
  <peek-list-item value="opt2">Option 2</peek-list-item>
  <peek-list-item value="opt3" disabled>Disabled</peek-list-item>
</peek-list>

<!-- Accessible tabs -->
<peek-tabs>
  <peek-tab>General</peek-tab>
  <peek-tab>Advanced</peek-tab>
  <peek-tab-panel>General content</peek-tab-panel>
  <peek-tab-panel>Advanced content</peek-tab-panel>
</peek-tabs>

<!-- Accessible dialog -->
<peek-dialog id="confirmDialog" size="sm" close-on-escape>
  <span slot="header">Confirm Action</span>
  <p>Are you sure?</p>
  <div slot="footer">
    <peek-button variant="ghost" onclick="confirmDialog.close()">Cancel</peek-button>
    <peek-button variant="danger" onclick="doAction()">Confirm</peek-button>
  </div>
</peek-dialog>

Component Customization#

Via CSS Custom Properties#

/* Global customization */
:root {
  --peek-radius-md: 12px;
  --peek-btn-height-md: 42px;
}

/* Component-specific */
peek-button {
  --peek-btn-bg: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

peek-card {
  --peek-card-bg: #f8f9fa;
  --peek-card-border: transparent;
  --peek-card-radius: 16px;
}