aktion-runtime 0.5.8 → 0.5.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +196 -26
- package/dist/aktion.iife.js +879 -78
- package/dist/aktion.iife.js.map +1 -1
- package/dist/aktion.js +16396 -10312
- package/dist/aktion.js.map +1 -1
- package/dist/aktion.umd.cjs +879 -78
- package/dist/aktion.umd.cjs.map +1 -1
- package/dist/devtools.js +554 -20
- package/dist/devtools.js.map +1 -1
- package/dist/language.js +4883 -572
- package/dist/language.js.map +1 -1
- package/dist/plugin.cjs +2 -2
- package/dist/plugin.cjs.map +1 -1
- package/dist/plugin.js +2 -2
- package/dist/plugin.js.map +1 -1
- package/dist/system_prompt.txt +269 -20
- package/dist/system_prompt_chat.txt +3 -3
- package/dist/testing.js +15977 -7890
- package/dist/testing.js.map +1 -1
- package/dist/types/devtools/panel.d.ts +32 -0
- package/dist/types/devtools/styles.d.ts +1 -1
- package/dist/types/element.d.ts +26 -0
- package/dist/types/icons/index.d.ts +10 -0
- package/dist/types/library/components/_internal.d.ts +18 -0
- package/dist/types/library/components/a11y.d.ts +5 -0
- package/dist/types/library/components/canvas.d.ts +3 -0
- package/dist/types/library/components/extras.d.ts +15 -0
- package/dist/types/library/components/feedback.d.ts +1 -0
- package/dist/types/library/components/forms-shared.d.ts +55 -0
- package/dist/types/library/components/layout-motion.d.ts +14 -0
- package/dist/types/library/components/layout.d.ts +1 -0
- package/dist/types/library/components/marketing.d.ts +35 -0
- package/dist/types/library/components/new-components.d.ts +1 -0
- package/dist/types/library/components/scheduling.d.ts +2 -0
- package/dist/types/library/components/wave3.d.ts +6 -0
- package/dist/types/library/highlight.d.ts +21 -0
- package/dist/types/library/qr.d.ts +12 -0
- package/dist/types/library/responsive-style.d.ts +51 -0
- package/dist/types/library/sx.d.ts +51 -0
- package/dist/types/runtime/env.d.ts +33 -0
- package/dist/types/runtime/evaluator.d.ts +30 -0
- package/dist/types/runtime/http.d.ts +37 -1
- package/dist/types/runtime/index.d.ts +2 -0
- package/dist/types/runtime/namespaces-extra.d.ts +73 -0
- package/dist/types/runtime/realtime.d.ts +46 -0
- package/dist/types/runtime/router.d.ts +42 -4
- package/dist/types/runtime/ssr.d.ts +29 -0
- package/dist/types/runtime/util.d.ts +65 -0
- package/dist/types/testing/index.d.ts +35 -0
- package/dist/types/theme/fonts.d.ts +30 -0
- package/dist/types/theme/index.d.ts +28 -0
- package/dist/types/theme/styles.d.ts +1 -1
- package/dist/types/tooling/html-import.d.ts +19 -0
- package/dist/types/tooling/index.d.ts +3 -0
- package/dist/types/tooling/schema.d.ts +58 -0
- package/package.json +1 -1
|
@@ -36,6 +36,16 @@ export interface EndpointResource {
|
|
|
36
36
|
lastUpdated?: number;
|
|
37
37
|
refetch: () => Promise<void>;
|
|
38
38
|
cancel: () => void;
|
|
39
|
+
/**
|
|
40
|
+
* Infinite/paginated query extras (VI.1), present only when the resource was
|
|
41
|
+
* created with `$query({ infinite: {...} })`. `data` holds the flattened
|
|
42
|
+
* items across every loaded page.
|
|
43
|
+
*/
|
|
44
|
+
loadMore?: () => Promise<void>;
|
|
45
|
+
hasMore?: boolean;
|
|
46
|
+
loadingMore?: boolean;
|
|
47
|
+
page?: number;
|
|
48
|
+
pages?: unknown[];
|
|
39
49
|
/**
|
|
40
50
|
* Optional completion callback. Fires once each time a request settles
|
|
41
51
|
* (success *or* error) — the initial load and every `refetch()`. It does
|
|
@@ -58,8 +68,22 @@ export interface EndpointResource {
|
|
|
58
68
|
export declare function isEndpointResource(value: unknown): value is EndpointResource;
|
|
59
69
|
export declare class HttpRuntime {
|
|
60
70
|
private interceptors;
|
|
71
|
+
/**
|
|
72
|
+
* Program-level interceptors registered in-program via
|
|
73
|
+
* `$util.onRequest` / `$util.onResponse` (suggestions-global VI.5). Kept in
|
|
74
|
+
* a separate layer from host interceptors so a replan can wipe them without
|
|
75
|
+
* disturbing host glue. Request interceptors run host→program; response
|
|
76
|
+
* interceptors run program→host (inner-to-outer, the usual convention).
|
|
77
|
+
*/
|
|
78
|
+
private programInterceptors;
|
|
61
79
|
/** Merge new interceptors on top of any previously-registered ones. */
|
|
62
80
|
registerInterceptors(interceptors: HttpInterceptors): void;
|
|
81
|
+
/** Merge in-program interceptors on top of any already registered. */
|
|
82
|
+
registerProgramInterceptors(interceptors: HttpInterceptors): void;
|
|
83
|
+
/** Drop every in-program interceptor (called on replan so they don't leak). */
|
|
84
|
+
clearProgramInterceptors(): void;
|
|
85
|
+
/** Notify both interceptor layers of a request error. */
|
|
86
|
+
private fireError;
|
|
63
87
|
/**
|
|
64
88
|
* Resolve a URL. Currently a pass-through — every `Http({ url })` call
|
|
65
89
|
* is expected to supply an absolute URL. Kept as a hook so request
|
|
@@ -69,10 +93,22 @@ export declare class HttpRuntime {
|
|
|
69
93
|
resolveUrl(url: string): string;
|
|
70
94
|
/**
|
|
71
95
|
* Issue a single HTTP request. Runs through `onRequest`/`onResponse`
|
|
72
|
-
* interceptors and surfaces a `retry()` one-shot
|
|
96
|
+
* interceptors (host + program layers) and surfaces a `retry()` one-shot
|
|
97
|
+
* inside each `onResponse`.
|
|
73
98
|
*/
|
|
74
99
|
request(input: HttpRequest): Promise<HttpResponse>;
|
|
75
100
|
}
|
|
101
|
+
/**
|
|
102
|
+
* Refetch every cached query whose key contains any of the given substrings
|
|
103
|
+
* (VI.2). Used by `$mutation({ invalidates: [...] })` and `$util.invalidate`.
|
|
104
|
+
*
|
|
105
|
+
* Matching is deliberately SUBSTRING-based: cache keys are derived from the
|
|
106
|
+
* request (url + params), so `invalidates: ["/api/posts"]` refreshes the
|
|
107
|
+
* list, every page of it, and any filtered variant in one go. The trade-off
|
|
108
|
+
* is that a short needle ("post") can over-invalidate ("composting") — use
|
|
109
|
+
* a path-ish needle ("/posts") when precision matters.
|
|
110
|
+
*/
|
|
111
|
+
export declare function invalidateQueries(ctx: EvaluationContext, keys: unknown): void;
|
|
76
112
|
/**
|
|
77
113
|
* Run a single `Http({...})` call and return the reactive resource bag.
|
|
78
114
|
*
|
|
@@ -4,6 +4,8 @@ export * from './evaluator.js';
|
|
|
4
4
|
export * from './router.js';
|
|
5
5
|
export * from './http.js';
|
|
6
6
|
export * from './i18n.js';
|
|
7
|
+
export { renderToString, renderToStaticMarkup } from './ssr.js';
|
|
8
|
+
export type { RenderToStringOptions, RenderToStringResult } from './ssr.js';
|
|
7
9
|
export { storage, type CookieOptions, type StorageNamespace, type StorageRoot } from './storage.js';
|
|
8
10
|
export { consoleNs, type ConsoleNamespace } from './console.js';
|
|
9
11
|
export { createToastManager, type ToastManager, type ToastItem, type ToastOptions, } from './toast.js';
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Extra runtime namespaces exposed to Aktion programs (suggestions-global
|
|
3
|
+
* Parts V.2, XIII.2): `$style` (bounded styling helpers) and `$rules`
|
|
4
|
+
* (composable validators). Both are pure — no side effects — and safe to
|
|
5
|
+
* call from any expression / action / effect / lambda.
|
|
6
|
+
*/
|
|
7
|
+
export declare const Style: {
|
|
8
|
+
/**
|
|
9
|
+
* Classname helper (clsx-style). Accepts strings, arrays, and objects
|
|
10
|
+
* `{ "is-active": cond }`; returns a space-joined, de-duped class string.
|
|
11
|
+
* Tokens that aren't valid CSS identifiers are dropped.
|
|
12
|
+
*/
|
|
13
|
+
readonly cx: (...args: unknown[]) => string;
|
|
14
|
+
/**
|
|
15
|
+
* Build a safe `linear-gradient(...)` from an array of color stops (and an
|
|
16
|
+
* optional angle in degrees). Returns "" if fewer than two valid stops.
|
|
17
|
+
*/
|
|
18
|
+
readonly gradient: (stops: unknown, angle?: unknown) => string;
|
|
19
|
+
/** color-mix wrapper: blend a color with transparent at `amount` (0–1). */
|
|
20
|
+
readonly alpha: (color: unknown, amount: unknown) => string;
|
|
21
|
+
/** Build a responsive `clamp(min, preferred, max)` size. */
|
|
22
|
+
readonly clamp: (min: unknown, preferred: unknown, max: unknown) => string;
|
|
23
|
+
/**
|
|
24
|
+
* Resolve a dotted token path to its CSS variable: `style.token("spacing.l")`
|
|
25
|
+
* → `var(--rui-spacing-l)`, `style.token("colors.primary")` →
|
|
26
|
+
* `var(--rui-color-primary)`. Falls back to "" for unknown shapes.
|
|
27
|
+
*/
|
|
28
|
+
readonly token: (path: unknown) => string;
|
|
29
|
+
/** Serialize a plain object of CSS declarations to a sanitised style string. */
|
|
30
|
+
readonly toStyle: (obj: unknown) => string;
|
|
31
|
+
};
|
|
32
|
+
export type StyleNamespace = typeof Style;
|
|
33
|
+
/**
|
|
34
|
+
* A validator returns an error message (invalid), null (valid), or a Promise
|
|
35
|
+
* of either — async validators (V.2 `asyncCustom`) resolve server-side checks
|
|
36
|
+
* like username uniqueness.
|
|
37
|
+
*/
|
|
38
|
+
type Validator = (value: unknown) => string | null | Promise<string | null>;
|
|
39
|
+
export declare const Rules: {
|
|
40
|
+
readonly required: (message?: string) => Validator;
|
|
41
|
+
readonly email: (message?: string) => Validator;
|
|
42
|
+
readonly url: (message?: string) => Validator;
|
|
43
|
+
readonly min: (n: number, message?: string) => Validator;
|
|
44
|
+
readonly max: (n: number, message?: string) => Validator;
|
|
45
|
+
readonly minLength: (n: number, message?: string) => Validator;
|
|
46
|
+
readonly maxLength: (n: number, message?: string) => Validator;
|
|
47
|
+
readonly pattern: (re: unknown, message?: string) => Validator;
|
|
48
|
+
readonly oneOf: (options: unknown[], message?: string) => Validator;
|
|
49
|
+
readonly matches: (other: unknown, message?: string) => Validator;
|
|
50
|
+
readonly custom: (fn: unknown, message?: string) => Validator;
|
|
51
|
+
/**
|
|
52
|
+
* Async validator (V.2) — `fn(value)` may return a Promise resolving to
|
|
53
|
+
* true/null (valid), false (invalid → `message`), or an error string. Use
|
|
54
|
+
* for server-side checks (e.g. username uniqueness). `$form` awaits these
|
|
55
|
+
* before submitting; a rejected promise counts as invalid.
|
|
56
|
+
*/
|
|
57
|
+
readonly asyncCustom: (fn: unknown, message?: string) => Validator;
|
|
58
|
+
/**
|
|
59
|
+
* Run a list of validators against a value; returns the first error
|
|
60
|
+
* message, or null when all pass. Stays fully synchronous for sync
|
|
61
|
+
* validators; returns a Promise only when an async validator is hit.
|
|
62
|
+
*/
|
|
63
|
+
readonly validate: (value: unknown, validators: unknown) => string | null | Promise<string | null>;
|
|
64
|
+
/**
|
|
65
|
+
* Validate an object of `{ field: value }` against a schema of
|
|
66
|
+
* `{ field: [validators] }`. Returns `{ field: message }` for failures
|
|
67
|
+
* (empty object when valid) — or a Promise of it when any validator in the
|
|
68
|
+
* schema is async.
|
|
69
|
+
*/
|
|
70
|
+
readonly validateAll: (values: unknown, schema: unknown) => Record<string, string> | Promise<Record<string, string>>;
|
|
71
|
+
};
|
|
72
|
+
export type RulesNamespace = typeof Rules;
|
|
73
|
+
export {};
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { EvaluationContext } from './evaluator.js';
|
|
2
|
+
export type SocketStatus = "connecting" | "open" | "closed";
|
|
3
|
+
export interface SocketResource {
|
|
4
|
+
/** Convenience boolean — true while `status === "open"`. */
|
|
5
|
+
connected: boolean;
|
|
6
|
+
/** Connection lifecycle: "connecting" | "open" | "closed" (spec VI.3). */
|
|
7
|
+
status: SocketStatus;
|
|
8
|
+
/** Most recent messages (capped to `bufferSize`, newest last). */
|
|
9
|
+
messages: unknown[];
|
|
10
|
+
/** The latest message (or null before the first arrives). */
|
|
11
|
+
last: unknown;
|
|
12
|
+
error: unknown;
|
|
13
|
+
/** Reconnect attempts made so far (resets on a successful open). */
|
|
14
|
+
attempts: number;
|
|
15
|
+
/**
|
|
16
|
+
* Send a message; objects are JSON-stringified. While the socket is still
|
|
17
|
+
* connecting (or briefly reconnecting), messages queue (bounded) and flush
|
|
18
|
+
* on open; once closed for good they are dropped.
|
|
19
|
+
*/
|
|
20
|
+
send: (data: unknown) => void;
|
|
21
|
+
/** Close the connection (disables auto-reconnect). */
|
|
22
|
+
close: () => void;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* `$socket({ url, protocols?, bufferSize?, onMessage?, reconnect? })` — a
|
|
26
|
+
* reactive WebSocket. Reads of `.status` / `.last` / `.messages` re-render on
|
|
27
|
+
* change. `reconnect: true` retries dropped connections with exponential
|
|
28
|
+
* backoff (a number caps the attempts); `close()` always stops for good.
|
|
29
|
+
*/
|
|
30
|
+
export declare function createSocketResource(config: unknown, ctx: EvaluationContext): SocketResource;
|
|
31
|
+
export interface SseResource {
|
|
32
|
+
connected: boolean;
|
|
33
|
+
/** Connection lifecycle: "connecting" | "open" | "closed". */
|
|
34
|
+
status: SocketStatus;
|
|
35
|
+
messages: unknown[];
|
|
36
|
+
last: unknown;
|
|
37
|
+
error: unknown;
|
|
38
|
+
close: () => void;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* `$sse({ url, withCredentials?, bufferSize?, event?, onMessage? })` — a
|
|
42
|
+
* reactive Server-Sent Events stream. `event` names a custom event type to
|
|
43
|
+
* listen for (defaults to the unnamed `message` stream). EventSource
|
|
44
|
+
* reconnects natively; `status` reads "connecting" while it does.
|
|
45
|
+
*/
|
|
46
|
+
export declare function createSseResource(config: unknown, ctx: EvaluationContext): SseResource;
|
|
@@ -31,6 +31,19 @@ export interface RouteChangeDetail {
|
|
|
31
31
|
source: "init" | "hashchange" | "navigate" | "external";
|
|
32
32
|
}
|
|
33
33
|
export type RouteListener = (detail: RouteChangeDetail) => void;
|
|
34
|
+
/** Payload handed to a navigation guard before a path change commits. */
|
|
35
|
+
export interface NavigationInfo {
|
|
36
|
+
/** The path the user is trying to reach (normalised). */
|
|
37
|
+
to: string;
|
|
38
|
+
/** The path being left (null on the very first navigation). */
|
|
39
|
+
from: string | null;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* A navigation guard decides whether a pending navigation may proceed.
|
|
43
|
+
* Return `false` to block it, a path string to redirect, or `true` /
|
|
44
|
+
* `undefined` to allow it.
|
|
45
|
+
*/
|
|
46
|
+
export type NavigationGuard = (info: NavigationInfo) => boolean | string | void;
|
|
34
47
|
export interface RouterOptions {
|
|
35
48
|
/** Initial path when no hash is set. Defaults to `/`. */
|
|
36
49
|
defaultPath?: string;
|
|
@@ -67,11 +80,21 @@ export declare function normalisePath(raw: string | null | undefined): string;
|
|
|
67
80
|
* - mixed wildcard: `/docs/*` (matches everything under `/docs/`)
|
|
68
81
|
*/
|
|
69
82
|
export declare function matchRoute(pattern: string, path: string): RouteMatch;
|
|
83
|
+
/** Result of a prefix match — the captured params plus the unmatched tail. */
|
|
84
|
+
export interface PrefixMatch {
|
|
85
|
+
matched: boolean;
|
|
86
|
+
params: RouteParams;
|
|
87
|
+
/** The remaining path after the matched prefix, normalised (e.g. `/settings`). */
|
|
88
|
+
rest: string;
|
|
89
|
+
}
|
|
70
90
|
/**
|
|
71
|
-
*
|
|
72
|
-
*
|
|
73
|
-
*
|
|
91
|
+
* Match a route pattern as a PREFIX of `path` (suggestions-global IV.1 — nested
|
|
92
|
+
* routes / layout routes). `/app` prefix-matches `/app`, `/app/x`, `/app/x/y`.
|
|
93
|
+
* Returns the captured `:params` plus the unmatched tail (`rest`) so a nested
|
|
94
|
+
* router can resolve the child route. A pure-segment pattern only matches on
|
|
95
|
+
* segment boundaries (so `/app` does not match `/application`).
|
|
74
96
|
*/
|
|
97
|
+
export declare function matchRoutePrefix(pattern: string, path: string): PrefixMatch;
|
|
75
98
|
export declare class Router {
|
|
76
99
|
private currentPath;
|
|
77
100
|
private currentParams;
|
|
@@ -85,6 +108,8 @@ export declare class Router {
|
|
|
85
108
|
/** True while we're updating `window.location` ourselves — used to
|
|
86
109
|
* filter out the resulting `hashchange` / `popstate` echo. */
|
|
87
110
|
private settingHash;
|
|
111
|
+
/** Optional navigation guard registered via `$util.onNavigate(fn)`. */
|
|
112
|
+
private guard;
|
|
88
113
|
constructor(options?: RouterOptions);
|
|
89
114
|
/**
|
|
90
115
|
* Re-configure the URL strategy before `start()` is called. The host
|
|
@@ -121,9 +146,22 @@ export declare class Router {
|
|
|
121
146
|
/**
|
|
122
147
|
* Navigate to the given path. When enabled, this updates the URL hash and
|
|
123
148
|
* relies on `hashchange` to notify listeners (so browser history works).
|
|
124
|
-
* When disabled, the navigation stays in-memory.
|
|
149
|
+
* When disabled, the navigation stays in-memory. A registered navigation
|
|
150
|
+
* guard may block (`false`) or redirect (path string) the change.
|
|
125
151
|
*/
|
|
126
152
|
navigate(path: string): void;
|
|
153
|
+
/**
|
|
154
|
+
* Register (or clear, with `null`) the navigation guard. The guard runs
|
|
155
|
+
* before every in-app `navigate(...)` and every URL-driven change once the
|
|
156
|
+
* router is started. Set via `$util.onNavigate(fn)`.
|
|
157
|
+
*/
|
|
158
|
+
setGuard(guard: NavigationGuard | null): void;
|
|
159
|
+
/** Run the guard for a pending navigation, failing open on error. */
|
|
160
|
+
private runGuard;
|
|
161
|
+
/** Rewind `window.location` to the current path (used when a guard blocks). */
|
|
162
|
+
private restoreUrl;
|
|
163
|
+
/** Commit a navigation after the guard has approved it (with redirect cap). */
|
|
164
|
+
private navigateInternal;
|
|
127
165
|
subscribe(listener: RouteListener): () => void;
|
|
128
166
|
/** Replace the current path without going through `window.location`. */
|
|
129
167
|
private setPath;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { ComponentLibrary } from '../library/types.js';
|
|
2
|
+
export interface RenderToStringOptions {
|
|
3
|
+
/** Component library to render against (defaults to the built-in one). */
|
|
4
|
+
library?: ComponentLibrary;
|
|
5
|
+
/** Initial path for the in-memory router (default "/"). */
|
|
6
|
+
path?: string;
|
|
7
|
+
/** Seed state for SSR — values hydrate over the program's declarations. */
|
|
8
|
+
initialState?: Record<string, unknown>;
|
|
9
|
+
/** Wrap the output in a single container element (default true). */
|
|
10
|
+
container?: boolean;
|
|
11
|
+
}
|
|
12
|
+
export interface RenderToStringResult {
|
|
13
|
+
/** Serialised HTML for the rendered program. */
|
|
14
|
+
html: string;
|
|
15
|
+
/** State snapshot to ship to the client for hydration. */
|
|
16
|
+
state: Record<string, unknown>;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Render an Aktion program to an HTML string + hydration state.
|
|
20
|
+
*
|
|
21
|
+
* Throws when no DOM is available (install `happy-dom`/`jsdom` and register it
|
|
22
|
+
* on `globalThis` in a Node SSR entry).
|
|
23
|
+
*/
|
|
24
|
+
export declare function renderToString(program: string, options?: RenderToStringOptions): RenderToStringResult;
|
|
25
|
+
/**
|
|
26
|
+
* Like `renderToString` but returns only the markup (no hydration state) —
|
|
27
|
+
* for fully static pages / SSG (suggestions-global XI.1).
|
|
28
|
+
*/
|
|
29
|
+
export declare function renderToStaticMarkup(program: string, options?: RenderToStringOptions): string;
|
|
@@ -94,5 +94,70 @@ export declare const Util: {
|
|
|
94
94
|
readonly sqrt: (value: unknown) => number;
|
|
95
95
|
readonly random: () => number;
|
|
96
96
|
readonly log: (value: unknown) => number;
|
|
97
|
+
readonly slugify: (text: unknown) => string;
|
|
98
|
+
readonly truncate: (text: unknown, length?: unknown, ellipsis?: string) => string;
|
|
99
|
+
readonly initials: (name: unknown, max?: unknown) => string;
|
|
100
|
+
readonly currency: (value: unknown, code?: string, locale?: string) => string;
|
|
101
|
+
readonly percent: (value: unknown, decimals?: unknown) => string;
|
|
102
|
+
readonly bytes: (value: unknown) => string;
|
|
103
|
+
readonly relativeTime: (value: unknown) => string;
|
|
104
|
+
/**
|
|
105
|
+
* Copy text to the clipboard. Resolves `true` only once the async Clipboard
|
|
106
|
+
* API write actually succeeds (permission can deny it), `false` otherwise.
|
|
107
|
+
* `await $util.copy(x)` in an action; plain truthy checks keep working.
|
|
108
|
+
*/
|
|
109
|
+
readonly copy: (text: unknown) => Promise<boolean>;
|
|
110
|
+
/** Await a pause: `await $util.sleep(300)`. Capped at 60s. */
|
|
111
|
+
readonly sleep: (ms?: unknown) => Promise<void>;
|
|
112
|
+
readonly uuid: () => string;
|
|
113
|
+
/** Wrap a function so it only fires `wait` ms after the last call. */
|
|
114
|
+
readonly debounceFn: (fn: unknown, wait?: unknown) => ((...args: unknown[]) => void);
|
|
115
|
+
/**
|
|
116
|
+
* Wrap a function so it fires at most once per `wait` ms. Leading edge
|
|
117
|
+
* fires immediately; calls landing inside the window schedule one trailing
|
|
118
|
+
* fire with the latest arguments, so the final value is never dropped.
|
|
119
|
+
*/
|
|
120
|
+
readonly throttleFn: (fn: unknown, wait?: unknown) => ((...args: unknown[]) => void);
|
|
121
|
+
/** Trigger device haptics. `pattern` is ms or an array of on/off ms. */
|
|
122
|
+
readonly vibrate: (pattern?: unknown) => boolean;
|
|
123
|
+
/** Native share sheet. `data` = { title?, text?, url? }. Returns a promise. */
|
|
124
|
+
readonly share: (data: unknown) => Promise<boolean>;
|
|
125
|
+
/** Read text from the clipboard (async). Returns "" when unavailable/denied. */
|
|
126
|
+
readonly readClipboard: () => Promise<string>;
|
|
127
|
+
/** Current geolocation as a promise of { lat, lng, accuracy } (or null). */
|
|
128
|
+
readonly geolocate: (options?: unknown) => Promise<{
|
|
129
|
+
lat: number;
|
|
130
|
+
lng: number;
|
|
131
|
+
accuracy: number;
|
|
132
|
+
} | null>;
|
|
133
|
+
/** `true` when the device is currently online. */
|
|
134
|
+
readonly isOnline: () => boolean;
|
|
135
|
+
/** Best-effort device class from the user agent: "mobile" | "tablet" | "desktop". */
|
|
136
|
+
readonly deviceType: () => string;
|
|
137
|
+
/**
|
|
138
|
+
* Run a PURE function off the main thread in a Web Worker, resolving with its
|
|
139
|
+
* result. `fn` is serialised via `toString()`, so it must not close over
|
|
140
|
+
* outer variables (pass everything it needs as arguments). Falls back to
|
|
141
|
+
* running inline (still async) when Workers aren't available.
|
|
142
|
+
* $util.worker((n) => heavyCompute(n), 1000).then(r => $result = r)
|
|
143
|
+
*/
|
|
144
|
+
readonly worker: (fn: unknown, ...args: unknown[]) => Promise<unknown>;
|
|
145
|
+
/** Register a service worker. Resolves true on success, false otherwise. */
|
|
146
|
+
readonly registerServiceWorker: (url: unknown, scope?: unknown) => Promise<boolean>;
|
|
147
|
+
/**
|
|
148
|
+
* Build a sanitised Web App Manifest object from a config (XII.2). Use it to
|
|
149
|
+
* inline a manifest (`<link rel="manifest" href="data:...">`) or write one at
|
|
150
|
+
* build time. Unknown/unsafe keys are dropped.
|
|
151
|
+
*/
|
|
152
|
+
readonly webManifest: (config: unknown) => Record<string, unknown>;
|
|
153
|
+
/**
|
|
154
|
+
* Detect the native shell the app is running inside (Capacitor / Cordova /
|
|
155
|
+
* Tauri / Electron / React Native WebView), or "web" when it's a plain
|
|
156
|
+
* browser. Lets a program branch on the host (e.g. hide a download button in
|
|
157
|
+
* a native shell, or call a bridge when present).
|
|
158
|
+
*/
|
|
159
|
+
readonly nativeShell: () => string;
|
|
160
|
+
/** True when running inside any native shell (not a plain browser). */
|
|
161
|
+
readonly isNativeApp: () => boolean;
|
|
97
162
|
};
|
|
98
163
|
export type UtilNamespace = typeof Util;
|
|
@@ -199,3 +199,38 @@ export declare function renderComponent(expression: string, options?: ComponentR
|
|
|
199
199
|
export declare function cleanup(): void;
|
|
200
200
|
/** Convenience for building a JSON `MockResult` in a `fetch` handler. */
|
|
201
201
|
export declare function json(data: unknown, status?: number): MockResult;
|
|
202
|
+
export interface WithinQueries {
|
|
203
|
+
getByText(matcher: Matcher): HTMLElement;
|
|
204
|
+
queryByText(matcher: Matcher): HTMLElement | null;
|
|
205
|
+
getAllByText(matcher: Matcher): HTMLElement[];
|
|
206
|
+
getByRole(role: string, options?: {
|
|
207
|
+
name?: Matcher;
|
|
208
|
+
}): HTMLElement;
|
|
209
|
+
queryByRole(role: string, options?: {
|
|
210
|
+
name?: Matcher;
|
|
211
|
+
}): HTMLElement | null;
|
|
212
|
+
getAllByRole(role: string, options?: {
|
|
213
|
+
name?: Matcher;
|
|
214
|
+
}): HTMLElement[];
|
|
215
|
+
getByTestId(id: string): HTMLElement;
|
|
216
|
+
queryByTestId(id: string): HTMLElement | null;
|
|
217
|
+
}
|
|
218
|
+
/**
|
|
219
|
+
* Scope Testing-Library-style queries to a subtree (XIV.6). Mirror of RTL's
|
|
220
|
+
* `within(node)` — useful for asserting inside one card/row of a list without
|
|
221
|
+
* matching siblings.
|
|
222
|
+
*/
|
|
223
|
+
export declare function within(root: Element): WithinQueries;
|
|
224
|
+
export interface A11yViolation {
|
|
225
|
+
rule: string;
|
|
226
|
+
message: string;
|
|
227
|
+
element: string;
|
|
228
|
+
}
|
|
229
|
+
/**
|
|
230
|
+
* Lightweight accessibility audit (XIV.6) — a pragmatic subset of axe-style
|
|
231
|
+
* checks that need no dependency: images without alt, non-decorative SVGs
|
|
232
|
+
* without a label, buttons/links without an accessible name (resolving
|
|
233
|
+
* `aria-labelledby`), inputs without a label, duplicate ids, and positive
|
|
234
|
+
* tabindex. Returns the list of violations (empty = clean).
|
|
235
|
+
*/
|
|
236
|
+
export declare function axe(root: Element): A11yViolation[];
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Web-font loading for `$theme({ fonts: { import: [...] } })`
|
|
3
|
+
* (suggestions-global I.7).
|
|
4
|
+
*
|
|
5
|
+
* Accepts a short Google-Fonts shorthand list and injects a single
|
|
6
|
+
* `<link rel="stylesheet">` into `document.head` (once per unique URL).
|
|
7
|
+
* Font faces loaded into the document are visible to shadow roots, so the
|
|
8
|
+
* renderer can reference them via the `font` theme tokens.
|
|
9
|
+
*
|
|
10
|
+
* Shorthand:
|
|
11
|
+
* "Inter:400,700" → family Inter, weights 400 & 700
|
|
12
|
+
* "JetBrains Mono" → family JetBrains Mono, default weight
|
|
13
|
+
* "Inter:400,500i,700" → `i` suffix marks an italic weight
|
|
14
|
+
*
|
|
15
|
+
* Only well-formed family names (letters, digits, spaces) and numeric
|
|
16
|
+
* weights are accepted; anything else is dropped so a hostile value can't
|
|
17
|
+
* smuggle a different origin or CSS payload into the page.
|
|
18
|
+
*/
|
|
19
|
+
/**
|
|
20
|
+
* Build a sanitised Google Fonts CSS2 URL from a shorthand list, or "" when
|
|
21
|
+
* no valid family is present.
|
|
22
|
+
*/
|
|
23
|
+
export declare function buildFontUrl(list: unknown): string;
|
|
24
|
+
/**
|
|
25
|
+
* Inject the web fonts named in `import` into `document.head` (idempotent).
|
|
26
|
+
* `record` is the `fonts` group from a `$theme({ fonts: {...} })` call; only
|
|
27
|
+
* its `import` array is used here (the `family`/`familyHeading` tokens are
|
|
28
|
+
* applied separately by the normal token flow). Returns the injected URL or "".
|
|
29
|
+
*/
|
|
30
|
+
export declare function loadFonts(record: unknown): string;
|
|
@@ -89,12 +89,40 @@ export interface ThemeTokens {
|
|
|
89
89
|
spacingM: string;
|
|
90
90
|
spacingL: string;
|
|
91
91
|
spacingXl: string;
|
|
92
|
+
/** Extra-large spacing steps for marketing/section rhythm. */
|
|
93
|
+
spacing2xl: string;
|
|
94
|
+
spacing3xl: string;
|
|
95
|
+
/** Primary brand gradient — used by `fill: "gradient.brand"`, GradientText, etc. */
|
|
96
|
+
gradientBrand: string;
|
|
97
|
+
gradientAccent: string;
|
|
98
|
+
gradientWarm: string;
|
|
99
|
+
gradientCool: string;
|
|
100
|
+
gradientSuccess: string;
|
|
101
|
+
gradientDanger: string;
|
|
92
102
|
buttonFontWeight: string;
|
|
93
103
|
buttonTextTransform: string;
|
|
94
104
|
buttonLetterSpacing: string;
|
|
95
105
|
buttonPaddingY: string;
|
|
96
106
|
buttonPaddingX: string;
|
|
97
107
|
transitionDuration: string;
|
|
108
|
+
/** Motion tokens (I.2) — `$theme({ motion: { fast, base, slow, ease } })`.
|
|
109
|
+
* Optional: components fall back to their built-in timings. */
|
|
110
|
+
motionFast?: string;
|
|
111
|
+
motionBase?: string;
|
|
112
|
+
motionSlow?: string;
|
|
113
|
+
motionEase?: string;
|
|
114
|
+
/** z-index tokens — `$theme({ zIndex: { modal: 2000, ... } })`. Optional:
|
|
115
|
+
* `sx.zIndex` tokens fall back to the documented defaults. */
|
|
116
|
+
zBase?: string;
|
|
117
|
+
zRaised?: string;
|
|
118
|
+
zDropdown?: string;
|
|
119
|
+
zSticky?: string;
|
|
120
|
+
zBanner?: string;
|
|
121
|
+
zOverlay?: string;
|
|
122
|
+
zModal?: string;
|
|
123
|
+
zPopover?: string;
|
|
124
|
+
zToast?: string;
|
|
125
|
+
zTooltip?: string;
|
|
98
126
|
chart1: string;
|
|
99
127
|
chart2: string;
|
|
100
128
|
chart3: string;
|