Quick API Reference ⚡

A comprehensive reference for all SigPro APIs. Everything you need to build reactive web applications with signals and web components.

📋 API Functions Reference

Function	Description	Example
$(initialValue)	Creates a reactive signal (getter/setter)	const count = $(0)
$(computedFn)	Creates a computed signal	const full = $(() => first() + last())
$.effect(fn)	Runs effect when dependencies change	$.effect(() => console.log(count()))
$.page(setupFn)	Creates a page with automatic cleanup	$.page(() => html Page )
$.component(tagName, setupFn, attrs, useShadow)	Creates reactive Web Component	$.component('my-menu', setup, ['items'])
$.router(routes)	Creates a hash-based router	$.router([{path:'/', component:Home}])
$.router.go(path)	Navigates to a route	$.router.go('/user/42')
$.fetch(url, data, loadingSignal)	Fetch wrapper with loading state	const data = await $.fetch('/api', data, loading)
$.storage(key, initialValue, storageType)	Persistent signal (local/sessionStorage)	const theme = $.storage('theme', 'light')
html`...`	Template literal for reactive HTML	html`<div>${count}</div>`

Signal Methods

Method	Description	Example
signal()	Gets current value	count()
signal(newValue)	Sets new value	count(5)
signal(prev => new)	Updates using previous value	count(c => c + 1)

Component Context Properties

Property	Description	Example
props	Reactive component properties	props.title()
slot(name)	Accesses slot content	slot() or slot('footer')
emit(event, data)	Dispatches custom event	emit('update', value)
onUnmount(cb)	Registers cleanup callback	onUnmount(() => clearInterval(timer))

Page Context Properties

Property	Description	Example
params	Route parameters	params.id, params.slug
onUnmount(cb)	Registers cleanup callback	onUnmount(() => clearInterval(timer))

HTML Directives

Directive	Description	Example
@event	Event listener	@click=${handler}
:property	Two-way binding	:value=${signal}
?attribute	Boolean attribute	?disabled=${signal}
.property	DOM property binding	.scrollTop=${value}
class:name	Conditional class	class:active=${isActive}

📡 Signals - $(initialValue)

Creates a reactive value that notifies dependents when changed.

Pattern	Example	Description
Basic Signal	const count = $(0)	Create signal with initial value
Getter	count()	Read current value
Setter	count(5)	Set new value directly
Updater	count(prev => prev + 1)	Update based on previous value
Computed	const full = $(() => first() + last())	Auto-updating derived signal

Examples

// Basic signal
const count = $(0);
console.log(count()); // 0
count(5);
count(c => c + 1); // 6

// Computed signal
const firstName = $('John');
const lastName = $('Doe');
const fullName = $(() => `${firstName()} ${lastName()}`);
console.log(fullName()); // "John Doe"
firstName('Jane'); // fullName auto-updates to "Jane Doe"

🔄 Effects - $.effect(fn)

Executes a function and automatically re-runs when its dependencies change.

Pattern	Example	Description
Basic Effect	$.effect(() => console.log(count()))	Run effect on dependency changes
Cleanup	$.effect(() => { timer = setInterval(...); return () => clearInterval(timer) })	Return cleanup function
Stop Effect	const stop = $.effect(...); stop()	Manually stop an effect

Examples

// Auto-running effect
const count = $(0);
$.effect(() => {
  console.log(`Count is: ${count()}`);
}); // Logs immediately and whenever count changes

// Effect with cleanup
const userId = $(1);
$.effect(() => {
  const id = userId();
  const timer = setInterval(() => fetchUser(id), 5000);
  return () => clearInterval(timer); // Cleanup before re-run
});

📄 Pages - $.page(setupFunction)

Creates a page with automatic cleanup of all signals and effects when navigated away.

// pages/about.js
import { $, html } from 'sigpro';

export default $.page(() => {
  const count = $(0);
  
  // Auto-cleaned on navigation
  $.effect(() => {
    document.title = `Count: ${count()}`;
  });
  
  return html`
    <div>
      <h1>About Page</h1>
      <p>Count: ${count}</p>
      <button @click=${() => count(c => c + 1)}>+</button>
    </div>
  `;
});

With Parameters

export default $.page(({ params, onUnmount }) => {
  const userId = params.id;
  
  // Manual cleanup if needed
  const interval = setInterval(() => refresh(), 10000);
  onUnmount(() => clearInterval(interval));
  
  return html`<div>User: ${userId}</div>`;
});

🧩 Components - $.component(tagName, setup, observedAttributes, useShadowDOM)

Creates Custom Elements with reactive properties.

Parameters

Parameter	Type	Default	Description
tagName	string	required	Custom element tag (must include hyphen)
setupFunction	Function	required	Function that renders the component
observedAttributes	string[]	[]	Attributes to observe for changes
useShadowDOM	boolean	false	true = Shadow DOM (encapsulated), false = Light DOM

Light DOM Example (Default)

// button.js - inherits global styles
$.component('my-button', (props, { slot, emit }) => {
  return html`
    <button 
      class="px-4 py-2 bg-blue-500 text-white rounded"
      @click=${() => emit('click')}
    >
      ${slot()}
    </button>
  `;
}, ['variant']); // Observe 'variant' attribute

Shadow DOM Example

// calendar.js - encapsulated styles
$.component('my-calendar', (props) => {
  return html`
    <style>
      /* These styles are isolated */
      .calendar {
        background: white;
        border-radius: 8px;
        box-shadow: 0 2px 10px rgba(0,0,0,0.1);
      }
    </style>
    <div class="calendar">
      ${renderCalendar(props.date())}
    </div>
  `;
}, ['date'], true); // true = use Shadow DOM

🌐 Router - $.router(routes)

Creates a hash-based router with automatic page cleanup.

Route Definition

const routes = [
  // Simple routes
  { path: '/', component: HomePage },
  { path: '/about', component: AboutPage },
  
  // Routes with parameters
  { path: '/user/:id', component: UserPage },
  { path: '/user/:id/posts/:pid', component: PostPage },
  
  // RegExp routes for advanced matching
  { path: /^\/posts\/(?<id>\d+)$/, component: PostPage },
];

Usage

import { $, html } from 'sigpro';
import Home from './pages/Home.js';
import User from './pages/User.js';

const router = $.router([
  { path: '/', component: Home },
  { path: '/user/:id', component: User },
]);

// Navigation
$.router.go('/user/42');
$.router.go('about'); // Same as '/about'

// In templates
html`
  <nav>
    <a href="#/">Home</a>
    <a href="#/user/42">Profile</a>
    <button @click=${() => $.router.go('/contact')}>
      Contact
    </button>
  </nav>
`;

📦 Storage - $.storage(key, initialValue, [storage])

Persistent signal that syncs with localStorage or sessionStorage.

// localStorage (default)
const theme = $.storage('theme', 'light');
const user = $.storage('user', null);
const settings = $.storage('settings', { notifications: true });

// sessionStorage
const tempData = $.storage('temp', {}, sessionStorage);

// Usage like a normal signal
theme('dark'); // Auto-saves to localStorage
console.log(theme()); // 'dark' (even after page refresh)

🌐 Fetch - $.fetch(url, data, [loading])

Simple fetch wrapper with automatic JSON handling.

const loading = $(false);

async function loadUser(id) {
  const user = await $.fetch(`/api/users/${id}`, null, loading);
  if (user) userData(user);
}

// In template
html`
  <div>
    ${() => loading() ? html`<spinner></spinner>` : html`
      <p>${userData()?.name}</p>
    `}
  </div>
`;

🎨 Template Literals - html`...`

Creates reactive DOM fragments with directives.

Directives Reference

Directive	Example	Description
Event	@click=${handler}	Add event listener
Two-way binding	:value=${signal}	Bind signal to input value
Boolean attribute	?disabled=${signal}	Toggle boolean attribute
Property	.scrollTop=${value}	Set DOM property directly
Class toggle	class:active=${isActive}	Toggle class conditionally

Examples

const text = $('');
const isDisabled = $(false);
const activeTab = $('home');

html`
  <!-- Event binding -->
  <button @click=${() => count(c => c + 1)}>+</button>
  
  <!-- Two-way binding -->
  <input :value=${text} />
  <p>You typed: ${text}</p>
  
  <!-- Boolean attributes -->
  <button ?disabled=${isDisabled}>Submit</button>
  
  <!-- Class toggles -->
  <div class:active=${activeTab() === 'home'}>
    Home content
  </div>
  
  <!-- Property binding -->
  <div .scrollTop=${scrollPosition}></div>
`;

🎯 Complete Component Example

import { $, html } from 'sigpro';

// Create a component
$.component('user-profile', (props, { slot, emit }) => {
  // Reactive state
  const user = $(null);
  const loading = $(false);
  
  // Load user data when userId changes
  $.effect(() => {
    const id = props.userId();
    if (id) {
      loading(true);
      $.fetch(`/api/users/${id}`, null, loading)
        .then(data => user(data));
    }
  });
  
  // Computed value
  const fullName = $(() => 
    user() ? `${user().firstName} ${user().lastName}` : ''
  );
  
  // Template
  return html`
    <div class="user-profile">
      ${() => loading() ? html`
        <div class="spinner">Loading...</div>
      ` : user() ? html`
        <h2>${fullName}</h2>
        <p>Email: ${user().email}</p>
        <button @click=${() => emit('select', user())}>
          ${slot('Select')}
        </button>
      ` : html`
        <p>User not found</p>
      `}
    </div>
  `;
}, ['user-id']); // Observe userId attribute