@madojs/mado 0.5.0

package/dist/src/page.js

@@ -0,0 +1,38 @@
+/**
+ * Page contract — a uniform format for describing a page.
+ *
+ *   // pages/user-profile.ts
+ *   import { page, html, resource, jsonFetcher } from '@madojs/mado';
+ *
+ *   export default page({
+ *     title: ({ id }) => `User #${id}`,
+ *     load:  ({ id }) => resource(() => `/api/users/${id}`, jsonFetcher()),
+ *     view:  ({ params, data }) => html`
+ *       <h1>${() => data?.data()?.name ?? '\u2026'}</h1>
+ *     `,
+ *   });
+ *
+ *   // routes.ts
+ *   import { routes } from '@madojs/mado';
+ *
+ *   export default routes({
+ *     '/users/:id': () => import('./pages/user-profile.js'),
+ *   });
+ *
+ * The contract is strict: exactly three slots — title / load / view.
+ * If a page exports something other than Page — tsc will stop it before build.
+ * "One right way" — as in Rust: fewer branches, fewer bugs.
+ */
+/**
+ * Page factory. A typed wrapper over a plain object —
+ * needed only for type inference and the single "_page" stamp.
+ */
+export function page(spec) {
+    return { _page: true, ...spec };
+}
+export const isPage = (v) => typeof v === "object" && v !== null && v._page === true;
+export function nested(spec) {
+    return { _nested: true, ...spec };
+}
+export const isNested = (v) => typeof v === "object" && v !== null && v._nested === true;
+//# sourceMappingURL=page.js.map

package/dist/src/page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.js","sourceRoot":"","sources":["../../src/page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AA0GH;;;GAGG;AACH,MAAM,UAAU,IAAI,CAClB,IAA+B;IAE/B,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;AAClC,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,CAAU,EAAa,EAAE,CAC9C,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAAU,CAAC,KAAK,KAAK,IAAI,CAAC;AA8BpE,MAAM,UAAU,MAAM,CAAC,IAAmC;IACxD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;AACpC,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAU,EAAqB,EAAE,CACxD,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAAkB,CAAC,OAAO,KAAK,IAAI,CAAC"}

package/dist/src/persisted.d.ts

@@ -0,0 +1,47 @@
+/**
+ * persisted() wraps a signal in localStorage / sessionStorage.
+ *
+ * Useful for:
+ *   - theme (light/dark)
+ *   - selected language
+ *   - last viewed product
+ *   - form drafts
+ *
+ *   const theme = persisted('theme', signal<'light'|'dark'>('light'));
+ *   const draft = persisted('newPost.draft', signal(''),
+ *     { storage: 'session', debounce: 300 });
+ *
+ * Returns the same Signal API. Reads from storage on startup; writes on every
+ * change (optionally debounced). Synchronizes across tabs via BroadcastChannel.
+ *
+ * Notes:
+ *   - JSON.parse/stringify; Date/Map/Set need a custom serializer.
+ *   - On QuotaExceeded or private-mode failures it silently falls back to memory.
+ *   - destroy() optionally closes the BroadcastChannel subscription.
+ */
+import { type Signal } from "./signal.js";
+export interface PersistedOptions<T> {
+    /** "local" (default) or "session". */
+    storage?: "local" | "session";
+    /** Write delay in ms. Default 0 (synchronous). */
+    debounce?: number;
+    /**
+     * Key prefix. Default "mado:". Helps avoid collisions
+     * with other scripts on the page.
+     */
+    keyPrefix?: string;
+    /** Custom serialiser. Default JSON.stringify. */
+    serialize?: (value: T) => string;
+    /** Custom deserialiser. Default JSON.parse. */
+    deserialize?: (raw: string) => T;
+    /**
+     * Cross-tab synchronisation via BroadcastChannel.
+     * Default true for "local", false for "session".
+     */
+    syncTabs?: boolean;
+}
+export interface PersistedSignal<T> extends Signal<T> {
+    /** Remove the value from storage and unsubscribe from the bus. */
+    destroy(): void;
+}
+export declare function persisted<T>(key: string, base: Signal<T>, options?: PersistedOptions<T>): PersistedSignal<T>;

package/dist/src/persisted.js

@@ -0,0 +1,119 @@
+/**
+ * persisted() wraps a signal in localStorage / sessionStorage.
+ *
+ * Useful for:
+ *   - theme (light/dark)
+ *   - selected language
+ *   - last viewed product
+ *   - form drafts
+ *
+ *   const theme = persisted('theme', signal<'light'|'dark'>('light'));
+ *   const draft = persisted('newPost.draft', signal(''),
+ *     { storage: 'session', debounce: 300 });
+ *
+ * Returns the same Signal API. Reads from storage on startup; writes on every
+ * change (optionally debounced). Synchronizes across tabs via BroadcastChannel.
+ *
+ * Notes:
+ *   - JSON.parse/stringify; Date/Map/Set need a custom serializer.
+ *   - On QuotaExceeded or private-mode failures it silently falls back to memory.
+ *   - destroy() optionally closes the BroadcastChannel subscription.
+ */
+import { effect } from "./signal.js";
+export function persisted(key, base, options = {}) {
+    const prefix = options.keyPrefix ?? "mado:";
+    const fullKey = prefix + key;
+    const storage = options.storage === "session"
+        ? safeStorage("sessionStorage")
+        : safeStorage("localStorage");
+    const serialize = options.serialize ?? JSON.stringify;
+    const deserialize = options.deserialize ?? ((s) => JSON.parse(s));
+    // 1) Read initial value
+    if (storage) {
+        try {
+            const raw = storage.getItem(fullKey);
+            if (raw != null)
+                base.set(deserialize(raw));
+        }
+        catch {
+            /* corrupt JSON — ignore */
+        }
+    }
+    // 2) Write on each change (optionally debounced)
+    let writeTimer = null;
+    const flushWrite = (v) => {
+        if (!storage)
+            return;
+        try {
+            storage.setItem(fullKey, serialize(v));
+        }
+        catch {
+            /* QuotaExceeded — skip */
+        }
+    };
+    effect(() => {
+        const v = base();
+        if (options.debounce && options.debounce > 0) {
+            if (writeTimer)
+                clearTimeout(writeTimer);
+            writeTimer = setTimeout(() => flushWrite(v), options.debounce);
+        }
+        else {
+            flushWrite(v);
+        }
+    });
+    // 3) Cross-tab synchronisation via BroadcastChannel
+    const wantSync = options.syncTabs ?? options.storage !== "session";
+    let bc = null;
+    if (wantSync && typeof BroadcastChannel !== "undefined") {
+        try {
+            bc = new BroadcastChannel(`mado:persisted:${key}`);
+            bc.addEventListener("message", (e) => {
+                try {
+                    base.set(e.data);
+                }
+                catch {
+                    /* noop */
+                }
+            });
+            // publish changes
+            effect(() => {
+                const v = base();
+                // peek-exclusion to avoid infinite loop: we don't read from bc-source
+                bc?.postMessage(v);
+            });
+        }
+        catch {
+            bc = null;
+        }
+    }
+    const out = base;
+    out.destroy = () => {
+        if (storage) {
+            try {
+                storage.removeItem(fullKey);
+            }
+            catch {
+                /* noop */
+            }
+        }
+        bc?.close();
+    };
+    return out;
+}
+function safeStorage(name) {
+    try {
+        const s = globalThis[name];
+        if (!s)
+            return null;
+        // Some browsers throw on storage access in private mode.
+        const probe = "__madoprobe__";
+        s.setItem(probe, "1");
+        s.removeItem(probe);
+        return s;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=persisted.js.map

package/dist/src/persisted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persisted.js","sourceRoot":"","sources":["../../src/persisted.ts"],"names":[],"mappings":"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"}

package/dist/src/resource.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Reactive fetch + cache. Replaces React-Query / SWR.
+ *
+ * Core idea:
+ *   1. resource(keyFn, fetcher) — keyFn reads signals like a normal effect.
+ *      When dependencies change the key is recomputed, and if the key
+ *      actually differs — a new fetch starts (the old one is cancelled via
+ *      AbortController).
+ *   2. Data is cached by key in a global Map.
+ *   3. resource returns three signals: data/error/loading, plus
+ *      refresh()/mutate()/invalidate().
+ *
+ * mutation(fetcher) — a wrapper for POST/PUT/DELETE. After a successful run
+ * it can invalidate specified resource keys (exact match or prefix-glob 'users/*').
+ *
+ * No runtime dependencies: only fetch + AbortController + signals.
+ */
+import { type Signal } from "./signal.js";
+/**
+ * Remove from cache all keys matching the pattern, and force
+ * all live resource() instances with that key to re-fetch.
+ *
+ * Only a trailing `*` is supported for prefix-match:
+ *   invalidate('users/42')   → exact match
+ *   invalidate('users/*')    → everything starting with 'users/'
+ *   invalidate('*')          → drop the ENTIRE cache (use intentionally)
+ *
+ * NOT supported: glob-in-middle (`users/* /posts`), regex, multi-star.
+ * For more complex cases call invalidate() multiple times with different prefixes,
+ * or iterate your own keys manually.
+ */
+export declare function invalidate(pattern: string): void;
+export interface ResourceOptions {
+    /** How many ms the data is considered fresh (fetch is skipped). */
+    staleTime?: number;
+    /** Initial value shown immediately. */
+    initialData?: unknown;
+}
+export interface Resource<T> {
+    /** Signal: data or undefined */
+    data: () => T | undefined;
+    /** Signal: error or null */
+    error: () => Error | null;
+    /** Signal: whether a request is in progress */
+    loading: () => boolean;
+    /** Signal: current key (useful for debugging and DI) */
+    key: () => string;
+    /** Force re-run the request. */
+    refresh(): void;
+    /**
+     * Locally replace the data (optimistic update).
+     * The cache is also updated.
+     */
+    mutate(next: T | ((prev: T | undefined) => T)): void;
+}
+export declare function resource<T>(keyFn: () => string, fetcher: (key: string, signal: AbortSignal) => Promise<T>, options?: ResourceOptions): Resource<T>;
+export interface MutationOptions<TArgs = unknown, TResult = unknown> {
+    /**
+     * Invalidate cache by these patterns after success.
+     *
+     * Can be:
+     *   - a static array:  `['users/*']`
+     *   - a function of result and args:
+     *     `(result, args) => [${'`'}posts/${result.id}${'`'}, 'feed/*']`
+     *
+     * The function is called AFTER a successful request. If it throws — the error
+     * is logged to console, but the mutation success is preserved (invalidation is best-effort).
+     *
+     * Only `*` at the END of a pattern is supported (see invalidate()).
+     */
+    invalidates?: readonly string[] | ((result: TResult, args: TArgs) => readonly string[]);
+}
+export interface Mutation<TArgs, TResult> {
+    /** Signal: request in progress */
+    loading: Signal<boolean>;
+    /** Signal: error */
+    error: Signal<Error | null>;
+    /** Signal: last received data */
+    data: Signal<TResult | undefined>;
+    /** Execute. Returns a Promise. */
+    run(args: TArgs): Promise<TResult>;
+    /** Reset error/data state. */
+    reset(): void;
+}
+export declare function mutation<TArgs, TResult>(fetcher: (args: TArgs, signal: AbortSignal) => Promise<TResult>, options?: MutationOptions<TArgs, TResult>): Mutation<TArgs, TResult>;
+/**
+ * Extended HTTP error thrown by jsonFetcher() on `!response.ok`.
+ *
+ * Unlike a plain `Error("HTTP 422")`, it preserves:
+ *   - `status` / `statusText` — for UI discrimination ("422 → show form errors")
+ *   - `url` — which endpoint failed
+ *   - `body` — parsed response body (JSON if possible, then text, then null)
+ *
+ *   try {
+ *     await api.save(user);
+ *   } catch (err) {
+ *     if (err instanceof HttpError && err.status === 422) {
+ *       // err.body may contain { errors: { email: 'taken' } }
+ *     }
+ *   }
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly url: string;
+    readonly body: unknown;
+    constructor(status: number, statusText: string, url: string, body: unknown);
+}
+/**
+ * Simple JSON fetcher for resource. Throws HttpError on `!response.ok`,
+ * with a parsed body (JSON → text → null) for proper UI error handling.
+ *
+ *   const user = resource(() => `/api/users/${id()}`, jsonFetcher());
+ */
+export declare function jsonFetcher<T>(init?: RequestInit): (url: string, signal: AbortSignal) => Promise<T>;
+export declare const _testHooks: {
+    invalidatorsSize(): number;
+    cacheSize(): number;
+    clearCache(): void;
+};

package/dist/src/resource.js

@@ -0,0 +1,275 @@
+/**
+ * Reactive fetch + cache. Replaces React-Query / SWR.
+ *
+ * Core idea:
+ *   1. resource(keyFn, fetcher) — keyFn reads signals like a normal effect.
+ *      When dependencies change the key is recomputed, and if the key
+ *      actually differs — a new fetch starts (the old one is cancelled via
+ *      AbortController).
+ *   2. Data is cached by key in a global Map.
+ *   3. resource returns three signals: data/error/loading, plus
+ *      refresh()/mutate()/invalidate().
+ *
+ * mutation(fetcher) — a wrapper for POST/PUT/DELETE. After a successful run
+ * it can invalidate specified resource keys (exact match or prefix-glob 'users/*').
+ *
+ * No runtime dependencies: only fetch + AbortController + signals.
+ */
+import { signal, effect, untracked } from "./signal.js";
+import { getCurrentLifecycle } from "./lifecycle.js";
+import { warnOnce } from "./diagnostics.js";
+const cache = new Map();
+const invalidators = new Set();
+/**
+ * Remove from cache all keys matching the pattern, and force
+ * all live resource() instances with that key to re-fetch.
+ *
+ * Only a trailing `*` is supported for prefix-match:
+ *   invalidate('users/42')   → exact match
+ *   invalidate('users/*')    → everything starting with 'users/'
+ *   invalidate('*')          → drop the ENTIRE cache (use intentionally)
+ *
+ * NOT supported: glob-in-middle (`users/* /posts`), regex, multi-star.
+ * For more complex cases call invalidate() multiple times with different prefixes,
+ * or iterate your own keys manually.
+ */
+export function invalidate(pattern) {
+    const isGlob = pattern.endsWith("*");
+    const prefix = isGlob ? pattern.slice(0, -1) : pattern;
+    const toDelete = [];
+    for (const key of cache.keys()) {
+        if (isGlob ? key.startsWith(prefix) : key === pattern) {
+            toDelete.push(key);
+        }
+    }
+    for (const k of toDelete)
+        cache.delete(k);
+    for (const fn of invalidators) {
+        for (const k of toDelete)
+            fn(k);
+    }
+}
+export function resource(keyFn, fetcher, options = {}) {
+    const data = signal(options.initialData);
+    const error = signal(null);
+    const loading = signal(false);
+    const keySig = signal("");
+    let abort = null;
+    let lastKey = "";
+    let force = false;
+    // if inside component-setup — auto-cleanup on unmount.
+    // if outside — print a warning so the developer knows
+    // about the potential leak.
+    const lifecycle = getCurrentLifecycle();
+    if (!lifecycle) {
+        warnOnce("resource-outside-lifecycle", "resource() called outside of component-setup. " +
+            "Invalidator subscriptions will not be cleaned up automatically — " +
+            "this is a leak. Use resource() inside component(...), or " +
+            "manage the lifecycle manually via createLifecycle()/runInLifecycle().");
+    }
+    const run = (key) => {
+        abort?.abort();
+        const ac = new AbortController();
+        abort = ac;
+        // if there is a fresh cache and not forced — use it
+        const cached = cache.get(key);
+        if (cached &&
+            !force &&
+            (!options.staleTime || Date.now() - cached.timestamp < options.staleTime)) {
+            data.set(cached.data);
+            error.set(null);
+            loading.set(false);
+            return;
+        }
+        loading.set(true);
+        error.set(null);
+        force = false;
+        fetcher(key, ac.signal).then((result) => {
+            if (ac.signal.aborted)
+                return;
+            cache.set(key, { data: result, timestamp: Date.now() });
+            data.set(result);
+            loading.set(false);
+        }, (err) => {
+            if (ac.signal.aborted)
+                return;
+            error.set(err instanceof Error ? err : new Error(String(err)));
+            loading.set(false);
+        });
+    };
+    // subscribe to key changes
+    const stopKeyEffect = effect(() => {
+        const key = keyFn();
+        keySig.set(key);
+        if (key !== lastKey || force) {
+            lastKey = key;
+            run(key);
+        }
+    });
+    // subscribe to global invalidation
+    const onInv = (invKey) => {
+        if (invKey === lastKey) {
+            force = true;
+            run(lastKey);
+        }
+    };
+    invalidators.add(onInv);
+    // auto-cleanup if inside a component
+    if (lifecycle) {
+        lifecycle.onDispose(() => {
+            stopKeyEffect();
+            invalidators.delete(onInv);
+            abort?.abort();
+        });
+    }
+    return {
+        data,
+        error,
+        loading,
+        key: keySig,
+        refresh() {
+            force = true;
+            // read key without tracking — otherwise we'd end up inside someone else's effect
+            const key = untracked(keyFn);
+            run(key);
+        },
+        mutate(next) {
+            const prev = data.peek();
+            const value = typeof next === "function"
+                ? next(prev)
+                : next;
+            data.set(value);
+            if (lastKey)
+                cache.set(lastKey, { data: value, timestamp: Date.now() });
+        },
+    };
+}
+export function mutation(fetcher, options = {}) {
+    const loading = signal(false);
+    const error = signal(null);
+    const data = signal(undefined);
+    let abort = null;
+    return {
+        loading,
+        error,
+        data,
+        async run(args) {
+            abort?.abort();
+            const ac = new AbortController();
+            abort = ac;
+            loading.set(true);
+            error.set(null);
+            try {
+                const result = await fetcher(args, ac.signal);
+                if (ac.signal.aborted) {
+                    throw new DOMException("aborted", "AbortError");
+                }
+                data.set(result);
+                loading.set(false);
+                const inv = options.invalidates;
+                if (inv) {
+                    let patterns = [];
+                    try {
+                        patterns = typeof inv === "function" ? inv(result, args) : inv;
+                    }
+                    catch (err) {
+                        // Invalidation is best-effort. Don't fail the mutation because of it.
+                        // eslint-disable-next-line no-console
+                        console.error("[mado] mutation.invalidates threw:", err);
+                    }
+                    for (const p of patterns)
+                        invalidate(p);
+                }
+                return result;
+            }
+            catch (err) {
+                if (!ac.signal.aborted) {
+                    error.set(err instanceof Error ? err : new Error(String(err)));
+                    loading.set(false);
+                }
+                throw err;
+            }
+        },
+        reset() {
+            abort?.abort();
+            loading.set(false);
+            error.set(null);
+            data.set(undefined);
+        },
+    };
+}
+// ---------- Utilities ----------
+/**
+ * Extended HTTP error thrown by jsonFetcher() on `!response.ok`.
+ *
+ * Unlike a plain `Error("HTTP 422")`, it preserves:
+ *   - `status` / `statusText` — for UI discrimination ("422 → show form errors")
+ *   - `url` — which endpoint failed
+ *   - `body` — parsed response body (JSON if possible, then text, then null)
+ *
+ *   try {
+ *     await api.save(user);
+ *   } catch (err) {
+ *     if (err instanceof HttpError && err.status === 422) {
+ *       // err.body may contain { errors: { email: 'taken' } }
+ *     }
+ *   }
+ */
+export class HttpError extends Error {
+    status;
+    statusText;
+    url;
+    body;
+    constructor(status, statusText, url, body) {
+        super(`HTTP ${status} ${statusText} ${url}`);
+        this.name = "HttpError";
+        this.status = status;
+        this.statusText = statusText;
+        this.url = url;
+        this.body = body;
+    }
+}
+/**
+ * Simple JSON fetcher for resource. Throws HttpError on `!response.ok`,
+ * with a parsed body (JSON → text → null) for proper UI error handling.
+ *
+ *   const user = resource(() => `/api/users/${id()}`, jsonFetcher());
+ */
+export function jsonFetcher(init = {}) {
+    return async (url, signal) => {
+        const res = await fetch(url, { ...init, signal });
+        if (!res.ok) {
+            let body = null;
+            // Try to read the body: JSON first, then text. Don't fail if that doesn't work.
+            try {
+                const ct = res.headers.get("content-type") ?? "";
+                if (ct.includes("application/json")) {
+                    body = await res.json();
+                }
+                else {
+                    body = await res.text();
+                }
+            }
+            catch {
+                body = null;
+            }
+            throw new HttpError(res.status, res.statusText, url, body);
+        }
+        return (await res.json());
+    };
+}
+// ---------- Test hooks ----------
+//
+// Not public API. Used by tests to inspect lifecycle cleanup.
+export const _testHooks = {
+    invalidatorsSize() {
+        return invalidators.size;
+    },
+    cacheSize() {
+        return cache.size;
+    },
+    clearCache() {
+        cache.clear();
+    },
+};
+//# sourceMappingURL=resource.js.map

package/dist/src/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../../src/resource.ts"],"names":[],"mappings":"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"}

package/dist/src/router/manifest.d.ts

@@ -0,0 +1,56 @@
+/**
+ * routes() — high-level manifest router with lazy loading, layouts,
+ * prefetch and a sync-fast-path for already-loaded pages.
+ *
+ * On top of the raw router() from navigation.ts this adds:
+ *   - dynamic-import loaders (code splitting via `() => import(...)`),
+ *   - nested routes with layouts (via page.ts: nested({ layout, routes })),
+ *   - per-instance module cache (not global — two routes() calls
+ *     in the same process do NOT interfere),
+ *   - hover prefetch and programmatic prefetchPath(),
+ *   - smart loadingDelay (no progress-bar flicker on fast networks),
+ *   - sync-fast-path: if the page is already in cache — renders synchronously,
+ *     without loading state and without a microtask. Removes flicker on back/forward.
+ */
+import type { TemplateResult } from "../html/template-types.js";
+import { type RoutesMap } from "./match.js";
+import { type RouterApi } from "./navigation.js";
+export interface RoutesOptions {
+    /**
+     * TemplateResult while the module is loading. Default — thin
+     * progress bar at the top (see defaultLoadingView). If the page is in cache,
+     * loading is not shown at all (sync render).
+     */
+    loading?: () => TemplateResult;
+    /** TemplateResult if the import threw. */
+    error?: (err: Error) => TemplateResult;
+    /** Prefix for document.title (e.g. ' · MyApp'). */
+    titleSuffix?: string;
+    /**
+     * Delay before showing the loading view in ms. If loading
+     * finishes faster — loading is not shown, the ready page renders immediately.
+     * Guards against flicker on fast connections.
+     * Default 100ms. Set to 0 to disable.
+     */
+    loadingDelay?: number;
+    /**
+     * Use View Transitions API on navigation (smooth crossfade).
+     * Default true.
+     */
+    viewTransitions?: boolean;
+}
+/**
+ * Create a router from a manifest. Returns the same RouterApi as router().
+ */
+export declare function routes(manifest: RoutesMap, options?: RoutesOptions): RouterApi;
+/**
+ * Prefetch-load modules for a path (hover, programmatic).
+ * Safe to call repeatedly — cached.
+ *
+ * Iterates all active routes() and starts loaders for matched entries.
+ * If there is no active routes() — no-op.
+ */
+export declare function prefetchPath(pathname: string): void;
+export declare const _testHooks: {
+    activeRoutesSize(): number;
+};