` `` — returns real DOM nodes |
| Component | `` class X extends Tina4Element { render() { return html`...`; } } `` |
| Route | `` route('/path', (params) => html`...`) `` |
| Navigate | `navigate('/path')` |
| API | `await api.get('/path')`, `.post`, `.put`, `.patch`, `.delete` |
| PWA | `pwa.register({ name, themeColor, cacheStrategy })` |
| WebSocket | `ws.connect('wss://...', { reconnect: true })` — signals for status/messages |
| Storage | `persist(signal('light'), { key: 'theme' })` from `tina4js/storage` — survives a refresh |
| Debug | `import 'tina4js/debug'` — toggle with Ctrl+Shift+D |
## File Conventions
- Components: `src/components/kebab-case.ts`
- Routes: `src/routes/index.ts`, or one file per feature wired with a wildcard (below)
- Pages: `src/pages/kebab-case.ts`
- Static files: `src/public/`
- Styles: `src/public/css/`
**Wildcard imports.** `route()` appends to the router table and `customElements.define()`
runs at module scope, so importing a file *is* registering what it declares. One glob
replaces the whole barrel file:
```ts
// src/main.ts
import { route, router, html } from 'tina4js';
import.meta.glob('./routes/*.ts', { eager: true });
import.meta.glob('./components/**/*.ts', { eager: true });
route('*', () => html`
404
`); // catch-all AFTER the glob
router.start({ target: '#root', mode: 'history' });
```
`{ eager: true }` is mandatory. Without it the glob returns loader functions nobody calls,
so nothing registers at all. Keep the catch-all out of the globbed folder: glob keys arrive
in alphabetical path order and the router takes the first matching pattern, so a `404.ts`
inside the folder renders for every path.
## Rules
1. Always use `.value` to read/write signals
2. Always return `` html`...` `` from `render()` and route handlers
3. Route params use `{name}` syntax: `` route('/user/{id}', ({ id }) => ...) ``
4. Event handlers use `@` prefix: `` @click=${handler} ``, `` @input=${handler} ``
5. Boolean attrs use `?` prefix: `` ?disabled=${signal} ``
6. API calls are async/await
7. Components extend `Tina4Element` and must call `customElements.define()`
8. Use `static props = { name: String }` for component attributes
9. Use `` static styles = `css` `` for scoped styles (Shadow DOM)
10. Use `static shadow = false` for light DOM components
11. `route(pattern, handler)` — pattern is ALWAYS the first argument, handler/config is second
12. `api.configure()` must be called before any API calls if you need auth or a base URL
13. `persist()` is for user preferences only — never tokens, passwords, personal data, or any
credentials. localStorage is XSS-readable. See `STORAGE.md` for the full dangers list.
14. Wire folders with `import.meta.glob(pattern, { eager: true })` instead of a hand-written
barrel. The pattern must be a literal string, and `route('*', ...)` goes after the glob
## Signal Patterns
```ts
// Create
const count = signal(0);
// Create with debug label (shows in debug overlay)
const count = signal(0, 'count');
// Read
count.value; // 0
// Write (triggers DOM updates)
count.value = 5;
// Read without subscribing
count.peek(); // 5
// Derived (auto-updates)
const doubled = computed(() => count.value * 2);
// Side effect
effect(() => console.log(count.value));
// Batch multiple updates
batch(() => { a.value = 1; b.value = 2; }); // one notification
// Check if something is a signal
isSignal(count); // true
// In templates — signals interpolate directly
html`${count}`; // auto-updates when count changes
```
## Component Pattern
```ts
import { Tina4Element, html, signal } from 'tina4js';
class MyWidget extends Tina4Element {
static props = { label: String, count: Number, active: Boolean };
static styles = `:host { display: block; }`;
// Internal state
expanded = signal(false);
render() {
return html`