Docs
This commit is contained in:
@@ -1,436 +0,0 @@
|
||||
# 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`<div>Page</div>`)` |
|
||||
| **`$.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} `` |
|
||||
|
||||
<style>
|
||||
table {
|
||||
width: 100%;
|
||||
border-collapse: collapse;
|
||||
margin: 1.5rem 0;
|
||||
}
|
||||
|
||||
th {
|
||||
background-color: var(--vp-c-bg-soft);
|
||||
padding: 0.75rem;
|
||||
text-align: left;
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
td {
|
||||
padding: 0.75rem;
|
||||
border-bottom: 1px solid var(--vp-c-divider);
|
||||
}
|
||||
|
||||
tr:hover {
|
||||
background-color: var(--vp-c-bg-soft);
|
||||
}
|
||||
|
||||
code {
|
||||
font-size: 0.9em;
|
||||
padding: 0.2em 0.4em;
|
||||
border-radius: 4px;
|
||||
background-color: var(--vp-c-bg-mute);
|
||||
}
|
||||
</style>
|
||||
|
||||
|
||||
## 📡 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
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```javascript
|
||||
// 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.
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```javascript
|
||||
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)
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```javascript
|
||||
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
|
||||
|
||||
```javascript
|
||||
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.
|
||||
|
||||
```javascript
|
||||
// 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.
|
||||
|
||||
```javascript
|
||||
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
|
||||
|
||||
```javascript
|
||||
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
|
||||
|
||||
```javascript
|
||||
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
|
||||
```
|
||||
|
||||
<style>
|
||||
table {
|
||||
width: 100%;
|
||||
border-collapse: collapse;
|
||||
margin: 1.5rem 0;
|
||||
}
|
||||
|
||||
th {
|
||||
background-color: var(--vp-c-bg-soft);
|
||||
padding: 0.75rem;
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
td {
|
||||
padding: 0.75rem;
|
||||
border-bottom: 1px solid var(--vp-c-divider);
|
||||
}
|
||||
|
||||
tr:hover {
|
||||
background-color: var(--vp-c-bg-soft);
|
||||
}
|
||||
|
||||
code {
|
||||
font-size: 0.9em;
|
||||
padding: 0.2em 0.4em;
|
||||
border-radius: 4px;
|
||||
}
|
||||
</style>
|
||||
Reference in New Issue
Block a user