npm install @web-loom/ui-patterns

interface PatternBehavior<State, Actions> {
  getState(): State;                              // synchronous snapshot
  subscribe(listener: (state: State) => void): () => void; // returns unsubscribe fn
  actions: Actions;                               // all available mutations
  eventBus?: EventBus;                            // pattern-specific events
  destroy(): void;                                // cleanup: subscriptions, timers, listeners
}

const pattern = createSomePattern({ ... });
 
// Subscribe to state changes
const unsubscribe = pattern.subscribe((state) => {
  render(state);
});
 
// Trigger actions
pattern.actions.doSomething();
 
// Teardown
pattern.destroy();
unsubscribe();

import { createMasterDetail } from '@web-loom/ui-patterns';
 
const masterDetail = createMasterDetail<Item>({
  items: initialItems,
  getId: (item) => item.id,
  initialDetailView: 'overview',
  onSelectionChange: (item) => console.log('Selected:', item),
});

import { createMasterDetail } from '@web-loom/ui-patterns';
import { useState, useEffect, useMemo } from 'react';
 
function usePattern<S>(pattern: { getState(): S; subscribe(fn: (s: S) => void): () => void }) {
  const [state, setState] = useState(() => pattern.getState());
  useEffect(() => pattern.subscribe(setState), [pattern]);
  return state;
}
 
export function GreenhouseExplorer({ greenhouses }: { greenhouses: Greenhouse[] }) {
  const md = useMemo(
    () => createMasterDetail({ items: greenhouses, getId: (g) => g.id }),
    [greenhouses],
  );
  useEffect(() => () => md.destroy(), [md]);
 
  const { items, selectedItem } = usePattern(md);
 
  return (
    <div className="flex">
      <ul className="w-64 border-r">
        {items.map((g) => (
          <li
            key={g.id}
            className={g.id === selectedItem?.id ? 'bg-blue-50' : ''}
            onClick={() => md.actions.selectItem(g)}
          >
            {g.name}
          </li>
        ))}
      </ul>
      <div className="flex-1 p-6">
        {selectedItem ? <GreenhouseDetail item={selectedItem} /> : <p>Select a greenhouse</p>}
      </div>
    </div>
  );
}

import { createWizard } from '@web-loom/ui-patterns';
 
const wizard = createWizard<OnboardingData>({
  steps: [
    {
      id: 'account-type',
      label: 'Account Type',
      validate: (data) => (!data.accountType ? 'Select an account type' : null),
      getNextStep: (data) => (data.accountType === 'business' ? 'company-info' : 'personal-info'),
    },
    { id: 'personal-info', label: 'Personal Info' },
    { id: 'company-info',  label: 'Company Info' },
    {
      id: 'confirm',
      label: 'Confirm',
      validate: (data) => (!data.agreed ? 'You must agree to continue' : null),
    },
  ],
  onComplete: async (data) => {
    await api.createAccount(data);
  },
  onStepChange: (index, step) => analytics.track('wizard_step', { step: step.id }),
});

// Move forward (with validation)
const advanced = await wizard.actions.goToNextStep();
if (!advanced) {
  // show wizard.getState().steps[currentIndex] validation error
}
 
// Save partial data from a step form
wizard.actions.setStepData({ email: 'alice@example.com' });
 
// Finish
await wizard.actions.completeWizard();

import { createModal } from '@web-loom/ui-patterns';
 
const modal = createModal({
  onModalOpened: (m)  => console.log('opened', m.id),
  onModalClosed: (id) => console.log('closed', id),
  onStackChange: (stack) => updateBackdrop(stack.length > 0),
});

// Open a confirmation dialog
modal.actions.openModal('confirm-delete', { item: selectedItem });
 
// In a React modal renderer
const { stack } = modal.getState();
return stack.map((m) => (
  <Dialog key={m.id} onClose={() => modal.actions.closeModal(m.id)}>
    <ConfirmDeleteDialog item={m.content.item} />
  </Dialog>
));

import { createTabbedInterface } from '@web-loom/ui-patterns';
 
const tabs = createTabbedInterface({
  tabs: [
    { id: 'overview',  label: 'Overview' },
    { id: 'sensors',   label: 'Sensors' },
    { id: 'settings',  label: 'Settings', disabled: false },
  ],
  initialActiveTabId: 'overview',
  orientation: 'horizontal',
  wrap: true,
  onTabChange: (tabId) => router.navigate(`#${tabId}`),
});

// Wire arrow keys in a React component
<TabList role="tablist" onKeyDown={(e) => {
  if (e.key === 'ArrowRight') tabs.actions.focusNextTab();
  if (e.key === 'ArrowLeft')  tabs.actions.focusPreviousTab();
}}>
  {state.tabs.map((tab) => (
    <Tab
      key={tab.id}
      role="tab"
      aria-selected={tab.id === state.activeTabId}
      onClick={() => tabs.actions.activateTab(tab.id)}
    >
      {tab.label}
    </Tab>
  ))}
</TabList>

import { createSidebarShell } from '@web-loom/ui-patterns';
 
const sidebar = createSidebarShell({
  initialExpanded: true,
  initialActiveSection: 'dashboard',
  initialPinned: false,
  initialWidth: 260,
  onExpand:  ()  => savePreference('sidebar', 'expanded'),
  onCollapse: () => savePreference('sidebar', 'collapsed'),
  onSectionChange: (s) => router.navigate(`/${s}`),
});

// Drive mobile mode from a resize observer
const resizeObserver = new ResizeObserver(([entry]) => {
  const isMobile = entry.contentRect.width < 768;
  sidebar.actions.setMobileMode(isMobile);
});
resizeObserver.observe(document.body);

import { createToastQueue } from '@web-loom/ui-patterns';
 
const toasts = createToastQueue({
  maxVisible: 4,
  defaultDuration: 4000,
  position: 'bottom-right',
  onToastAdded:   (t)  => console.log('added', t.id),
  onToastRemoved: (id) => console.log('removed', id),
});
 
// Show a toast
const id = toasts.actions.addToast({
  message: 'Greenhouse saved successfully',
  type: 'success',
  duration: 3000,
});

// In a ViewModel, inject the toast queue
class GreenhouseViewModel extends BaseViewModel {
  constructor(private toasts: ToastQueueBehavior) { super(); }
 
  readonly saveCommand = new Command(async () => {
    await this.model.save();
    this.toasts.actions.addToast({ message: 'Saved', type: 'success' });
  });
}

import { createCommandPalette } from '@web-loom/ui-patterns';
 
const palette = createCommandPalette({
  commands: [
    {
      id: 'new-greenhouse',
      label: 'New Greenhouse',
      category: 'Actions',
      keywords: ['create', 'add'],
      shortcut: 'Ctrl+N',
      action: () => modal.actions.openModal('new-greenhouse', {}),
    },
    {
      id: 'toggle-theme',
      label: 'Toggle Dark Mode',
      category: 'Appearance',
      action: () => themeStore.actions.toggle(),
    },
  ],
  onOpen:           () => analytics.track('palette_opened'),
  onClose:          () => {},
  onCommandExecute: (cmd) => analytics.track('command', { id: cmd.id }),
});

export function CommandPaletteShell() {
  const [state, setState] = useState(() => palette.getState());
  useEffect(() => palette.subscribe(setState), []);
 
  // Open with ⌘K / Ctrl+K
  useEffect(() => {
    const handler = (e: KeyboardEvent) => {
      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
        e.preventDefault();
        palette.actions.open();
      }
      if (e.key === 'Escape') palette.actions.close();
      if (e.key === 'ArrowDown') palette.actions.selectNext();
      if (e.key === 'ArrowUp')   palette.actions.selectPrevious();
      if (e.key === 'Enter')     palette.actions.executeSelected();
    };
    document.addEventListener('keydown', handler);
    return () => document.removeEventListener('keydown', handler);
  }, []);
 
  if (!state.isOpen) return null;
 
  return (
    <div className="fixed inset-0 z-50 flex items-start justify-center pt-24 bg-black/40">
      <div className="w-full max-w-xl bg-white dark:bg-slate-900 rounded-xl shadow-2xl">
        <input
          autoFocus
          value={state.query}
          onChange={(e) => palette.actions.setQuery(e.target.value)}
          placeholder="Type a command…"
          className="w-full px-4 py-3 text-lg border-b"
        />
        <ul>
          {state.filteredCommands.map((cmd, i) => (
            <li
              key={cmd.id}
              className={i === state.selectedIndex ? 'bg-blue-50 dark:bg-slate-700' : ''}
              onClick={() => palette.actions.executeCommand(cmd.id)}
            >
              <span>{cmd.label}</span>
              {cmd.shortcut && <kbd>{cmd.shortcut}</kbd>}
            </li>
          ))}
        </ul>
      </div>
    </div>
  );
}

import { createHubAndSpoke } from '@web-loom/ui-patterns';
 
const nav = createHubAndSpoke({
  spokes: [
    { id: 'analytics',  label: 'Analytics', icon: 'chart' },
    { id: 'settings',   label: 'Settings',  icon: 'gear' },
    {
      id: 'greenhouses',
      label: 'Greenhouses',
      subSpokes: [
        { id: 'greenhouse-list',   label: 'All Greenhouses' },
        { id: 'greenhouse-create', label: 'Add Greenhouse'  },
      ],
    },
  ],
  enableBrowserHistory: true,
  onSpokeActivate: (id) => console.log('navigated to', id),
  onReturnToHub:   ()   => console.log('back to home'),
});

import { createGridLayout } from '@web-loom/ui-patterns';
 
const grid = createGridLayout<Product>({
  items: products,
  getId: (p) => p.id,
  breakpoints: [
    { minWidth: 0,    columns: 2 },
    { minWidth: 640,  columns: 3 },
    { minWidth: 1024, columns: 4 },
    { minWidth: 1280, columns: 5 },
  ],
  selectionMode: 'multi',
  wrap: true,
  initialViewportWidth: window.innerWidth,
  onSelectionChange: (selected) => setCart(selected),
});
 
// Update columns when the viewport resizes
window.addEventListener('resize', () => {
  grid.actions.updateViewportWidth(window.innerWidth);
});

// Wire arrow keys in a React grid
<div
  role="grid"
  onKeyDown={(e) => {
    const map: Record<string, () => void> = {
      ArrowUp:    () => grid.actions.navigateUp(),
      ArrowDown:  () => grid.actions.navigateDown(),
      ArrowLeft:  () => grid.actions.navigateLeft(),
      ArrowRight: () => grid.actions.navigateRight(),
    };
    map[e.key]?.();
  }}
>
  {state.items.map((item, i) => (
    <div
      key={item.id}
      role="gridcell"
      tabIndex={i === state.focusedIndex ? 0 : -1}
      aria-selected={state.selectedItems.includes(item.id)}
      onClick={() => grid.actions.selectItem(item.id)}
    >
      {item.name}
    </div>
  ))}
</div>

import { createFloatingActionButton } from '@web-loom/ui-patterns';
 
const fab = createFloatingActionButton({
  scrollThreshold: 200,    // show after scrolling 200 px
  hideOnScrollDown: true,  // hide when scrolling down (show only when scrolling up)
  onVisibilityChange: (visible) => {
    document.getElementById('fab')!.style.display = visible ? 'flex' : 'none';
  },
});
 
// Feed scroll position from a scroll listener
window.addEventListener('scroll', () => {
  fab.actions.setScrollPosition(window.scrollY);
});

const backToTop = createFloatingActionButton({ scrollThreshold: 300 });
 
window.addEventListener('scroll', () =>
  backToTop.actions.setScrollPosition(window.scrollY),
);
 
document.getElementById('back-to-top')!.addEventListener('click', () => {
  window.scrollTo({ top: 0, behavior: 'smooth' });
});
 
backToTop.subscribe(({ isVisible }) => {
  document.getElementById('back-to-top')!.style.opacity = isVisible ? '1' : '0';
});

const md = createMasterDetail({ items, getId });
 
// Listen to side-channel events
const off = md.eventBus.on('item:selected', (item) => {
  detailPane.load(item.id);
});
 
// Later
off();          // unsubscribe just this listener
md.destroy();   // unsubscribes all listeners + cleans up state

import { createToastQueue, createModal, type ToastQueueBehavior, type ModalBehavior } from '@web-loom/ui-patterns';
import { BaseViewModel, Command } from '@web-loom/mvvm-core';
 
class GreenhouseViewModel extends BaseViewModel {
  constructor(
    private model: GreenhouseModel,
    private toasts: ToastQueueBehavior,
    private modal: ModalBehavior,
  ) {
    super();
  }
 
  readonly deleteCommand = new Command(async (id: string) => {
    await this.model.delete(id);
    this.toasts.actions.addToast({ message: 'Deleted', type: 'success' });
  });
 
  readonly confirmDelete = (id: string) => {
    this.modal.actions.openModal('confirm-delete', { id });
  };
}
 
// Singletons shared across the app
export const toastQueue = createToastQueue({ maxVisible: 3 });
export const globalModal = createModal();
export const greenhouseVM = new GreenhouseViewModel(
  new GreenhouseModel(),
  toastQueue,
  globalModal,
);

function usePattern<S>(p: { getState(): S; subscribe(fn: (s: S) => void): () => void }): S {
  const [state, setState] = useState(() => p.getState());
  useEffect(() => p.subscribe(setState), [p]);
  return state;
}

function usePattern<S>(p: { getState(): S; subscribe(fn: (s: S) => void): () => void }) {
  const state = ref<S>(p.getState());
  let unsub: (() => void) | null = null;
  onMounted(() => { unsub = p.subscribe((s) => { state.value = s; }); });
  onUnmounted(() => { unsub?.(); p.destroy(); });
  return readonly(state);
}

@Injectable({ providedIn: 'root' })
export class ToastService implements OnDestroy {
  private queue = createToastQueue({ maxVisible: 4 });
  private _state$ = new BehaviorSubject(this.queue.getState());
 
  constructor() {
    this.queue.subscribe((s) => this._state$.next(s));
  }
 
  get state$() { return this._state$.asObservable(); }
  get actions()  { return this.queue.actions; }
 
  ngOnDestroy() { this.queue.destroy(); }
}

import { describe, it, expect, vi } from 'vitest';
import { createWizard } from '@web-loom/ui-patterns';
 
describe('createWizard', () => {
  it('validates before advancing', async () => {
    const onComplete = vi.fn();
    const wizard = createWizard({
      steps: [
        { id: 'step1', label: 'Step 1', validate: (d) => (!d.name ? 'Required' : null) },
        { id: 'step2', label: 'Step 2' },
      ],
      onComplete,
    });
 
    const advanced = await wizard.actions.goToNextStep();
    expect(advanced).toBe(false); // blocked by validation
 
    wizard.actions.setStepData({ name: 'Alice' });
    const advanced2 = await wizard.actions.goToNextStep();
    expect(advanced2).toBe(true);
    expect(wizard.getState().currentStepIndex).toBe(1);
 
    wizard.destroy();
  });
 
  it('calls onComplete when wizard finishes', async () => {
    const onComplete = vi.fn();
    const wizard = createWizard({
      steps: [{ id: 'only', label: 'Only Step' }],
      onComplete,
    });
 
    await wizard.actions.completeWizard();
    expect(onComplete).toHaveBeenCalledOnce();
    wizard.destroy();
  });
});