aktion-runtime 0.5.11 → 0.5.13

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.
@@ -3,8 +3,9 @@ import { grammarSpec, createStreamTokenizer, defaultTagMap, keywordDocs, Grammar
3
3
  import { getComponentCatalog, indexCatalog, ComponentEntry, ComponentParam } from './components.js';
4
4
  import { getSnippets, SnippetEntry } from './snippets.js';
5
5
  import { builtinCatalog, builtinNames, builtinsByName, findBuiltin, isBuiltinName, BuiltinEntry, BuiltinCategory } from './builtins.js';
6
- export type { GrammarSpec, GrammarTokenKind, StreamTokenizer, KeywordDoc, ComponentEntry, ComponentParam, SnippetEntry, BuiltinEntry, BuiltinCategory, };
7
- export { grammarSpec, createStreamTokenizer, defaultTagMap, keywordDocs, getComponentCatalog, indexCatalog, getSnippets, builtinCatalog, builtinNames, builtinsByName, findBuiltin, isBuiltinName, };
6
+ import { namespaceCatalog, factoryResourceCatalog, factoryResourceNames, routeMembers, i18nResultMembers, findNamespace, isNamespaceName, findFactoryResource, namespaceMembersAt, findNamespaceMember, findBuiltinConfig, NamespaceEntry, NamespaceMember, NamespaceMemberKind, FactoryResourceEntry, ConfigKey } from './namespaces.js';
7
+ export type { GrammarSpec, GrammarTokenKind, StreamTokenizer, KeywordDoc, ComponentEntry, ComponentParam, SnippetEntry, BuiltinEntry, BuiltinCategory, NamespaceEntry, NamespaceMember, NamespaceMemberKind, FactoryResourceEntry, ConfigKey, };
8
+ export { grammarSpec, createStreamTokenizer, defaultTagMap, keywordDocs, getComponentCatalog, indexCatalog, getSnippets, builtinCatalog, builtinNames, builtinsByName, findBuiltin, isBuiltinName, namespaceCatalog, factoryResourceCatalog, factoryResourceNames, routeMembers, i18nResultMembers, findNamespace, isNamespaceName, findFactoryResource, namespaceMembersAt, findNamespaceMember, findBuiltinConfig, };
8
9
  /**
9
10
  * Diagnostic severity buckets that map to common editor lint levels.
10
11
  * Editors typically map: `error` → red squiggle, `warning` → yellow,
@@ -0,0 +1,102 @@
1
+ /**
2
+ * Catalog of the *members* exposed by Aktion's `$`-namespace builtins and the
3
+ * reactive resource bags its factory builtins return — the single source of
4
+ * truth for member-level editor tooling (completions / hover / semantic
5
+ * highlighting / signature help after a `.`).
6
+ *
7
+ * The sibling `builtins.ts` catalog covers the top-level `$`-forms
8
+ * (`$util`, `$http`, …). This file covers what comes AFTER the dot:
9
+ *
10
+ * - `$util.format(...)`, `$util.style.cx(...)`, `$util.rules.required()`
11
+ * - `$storage.local.set(...)`, `$storage.cookies.get(...)`
12
+ * - `$console.log(...)`, `$toast.success(...)`
13
+ * - the resource bag a factory returns — `$todos.data` / `.refetch()` for
14
+ * `$http`, `form.values` / `.submit()` for `$form`, … — and the reserved
15
+ * reactive `route` handle (`route.path`, `route.navigate(...)`).
16
+ *
17
+ * Everything here is pure + DOM-free so the VS Code extension, the docs
18
+ * playground, an LSP server, or any other host can consume it.
19
+ *
20
+ * KEEP IN SYNC with the runtime sources:
21
+ * - `$util` → `src/runtime/util.ts` (`Util`) + the `$util` facade getters
22
+ * in `src/runtime/evaluator.ts` + `src/runtime/namespaces-extra.ts`
23
+ * (`Style` → `$util.style`, `Rules` → `$util.rules`).
24
+ * - `$storage` → `src/runtime/storage.ts` (`StorageRoot`).
25
+ * - `$console` → `src/runtime/console.ts` (`ConsoleNamespace`).
26
+ * - `$toast` → `src/runtime/toast.ts` (`ToastManager`).
27
+ * - resource bags → `src/runtime/{http,realtime,effects}.ts`.
28
+ * - `route` → `src/runtime/router.ts`.
29
+ */
30
+ /** What kind of member a name resolves to (drives the editor icon). */
31
+ export type NamespaceMemberKind = "method" | "property" | "namespace";
32
+ export interface NamespaceMember {
33
+ /**
34
+ * Member name RELATIVE to its namespace. Nested members carry a dotted
35
+ * path so a single flat list can describe sub-namespaces: `"style.cx"`,
36
+ * `"rules.required"`, `"url.setQuery"`, `"local.set"`.
37
+ */
38
+ name: string;
39
+ kind: NamespaceMemberKind;
40
+ /** Signature skeleton, e.g. `"format(value, mode?)"` or `"scroll"` for a property. */
41
+ signature: string;
42
+ /** One-line description for hover popups + completion detail. */
43
+ summary: string;
44
+ }
45
+ export interface NamespaceEntry {
46
+ /** Bare namespace name without the `$` sigil (e.g. `"util"`). */
47
+ name: string;
48
+ /** Reference form WITH the sigil (e.g. `"$util"`). */
49
+ sigil: string;
50
+ summary: string;
51
+ members: readonly NamespaceMember[];
52
+ }
53
+ /** Every `$`-namespace whose members are reached via `.`. */
54
+ export declare const namespaceCatalog: readonly NamespaceEntry[];
55
+ export interface FactoryResourceEntry {
56
+ /** Factory builtin bare name (`"http"`, `"query"`, …). */
57
+ factory: string;
58
+ summary: string;
59
+ members: readonly NamespaceMember[];
60
+ }
61
+ /**
62
+ * The resource bag each factory builtin returns. A host that knows a binding
63
+ * was assigned from `$http(...)` / `$form(...)` / … completes `binding.` with
64
+ * the matching member list.
65
+ */
66
+ export declare const factoryResourceCatalog: readonly FactoryResourceEntry[];
67
+ /** Factory builtin names whose returned bag has a known member shape. */
68
+ export declare const factoryResourceNames: ReadonlySet<string>;
69
+ /** Members of the reserved reactive `route` handle (`route.path`, …). */
70
+ export declare const routeMembers: readonly NamespaceMember[];
71
+ /** The bag `$i18n({...})` returns (usually destructured). */
72
+ export declare const i18nResultMembers: readonly NamespaceMember[];
73
+ /** Resolve a namespace entry by its bare name (`"util"`, `"storage"`, …). */
74
+ export declare function findNamespace(bareName: string): NamespaceEntry | undefined;
75
+ /** True when `bareName` (no `$`) names a `.`-member namespace. */
76
+ export declare function isNamespaceName(bareName: string): boolean;
77
+ /** Resolve the resource-bag entry for a factory builtin (`"http"`, …). */
78
+ export declare function findFactoryResource(factory: string): FactoryResourceEntry | undefined;
79
+ /**
80
+ * Members offered at a member-access path inside a namespace. `path` is the
81
+ * already-typed sub-namespace segments after the root, e.g. `["style"]` for
82
+ * `$util.style.`. Returns the matching members with the consumed prefix
83
+ * stripped from each name (so `style.cx` is offered as `cx` after `$util.style.`).
84
+ */
85
+ export declare function namespaceMembersAt(bareName: string, path?: readonly string[]): NamespaceMember[];
86
+ /**
87
+ * Resolve a fully-qualified member by its dotted path within a namespace.
88
+ * `$util.style.cx` → `findNamespaceMember("util", "style.cx")`.
89
+ */
90
+ export declare function findNamespaceMember(bareName: string, memberPath: string): NamespaceMember | undefined;
91
+ export interface ConfigKey {
92
+ name: string;
93
+ /** Value type hint, e.g. `"string"`, `"object"`, `'enum: "GET" | "POST"'`. */
94
+ type: string;
95
+ summary: string;
96
+ }
97
+ /**
98
+ * Config-object keys accepted by a config-taking builtin (`bareName` without
99
+ * the `$` — `"http"`, `"theme"`, …), or `undefined` when the builtin takes no
100
+ * fixed-key config object (e.g. `$router`, whose keys are route patterns).
101
+ */
102
+ export declare function findBuiltinConfig(bareName: string): readonly ConfigKey[] | undefined;
@@ -13,7 +13,7 @@ export { getDiagnostics, getCompletions, getHoverInfo, type Position, type Diagn
13
13
  export { getDefinition, getDefinitionTarget, findDeclaration, getReferences, getDocumentHighlights, getDocumentSymbols, getRenameEdits, type Range, type TextEdit, type RenameResult, type DocumentSymbol, type SymbolKind, type DefinitionTarget, } from './tooling/navigation.js';
14
14
  export { getSemanticTokens, semanticTokenTypes, semanticTokenModifiers, type SemanticToken, type SemanticTokenType, type SemanticTokenModifier, } from './tooling/semantic-tokens.js';
15
15
  export { getSignatureHelp, type SignatureHelp, type SignatureInfo, type ParameterInfo, } from './tooling/signature-help.js';
16
- export { getLanguageSpec, grammarSpec, keywordDocs, getComponentCatalog, getSnippets, builtinCatalog, findBuiltin, isBuiltinName, type LanguageSpec, type GrammarSpec, type ComponentEntry, type ComponentParam, type SnippetEntry, type KeywordDoc, type BuiltinEntry, type BuiltinCategory, } from './language/index.js';
16
+ export { getLanguageSpec, grammarSpec, keywordDocs, getComponentCatalog, getSnippets, builtinCatalog, findBuiltin, isBuiltinName, namespaceCatalog, factoryResourceCatalog, factoryResourceNames, routeMembers, i18nResultMembers, findNamespace, isNamespaceName, findFactoryResource, namespaceMembersAt, findNamespaceMember, findBuiltinConfig, type LanguageSpec, type GrammarSpec, type ComponentEntry, type ComponentParam, type SnippetEntry, type KeywordDoc, type BuiltinEntry, type BuiltinCategory, type NamespaceEntry, type NamespaceMember, type NamespaceMemberKind, type FactoryResourceEntry, type ConfigKey, } from './language/index.js';
17
17
  export { formatProgram, type FormatResult } from './tooling/formatter.js';
18
18
  export { defaultLibrary } from './library/index.js';
19
19
  export type { ComponentLibrary } from './library/types.js';
@@ -0,0 +1,3 @@
1
+ import { ComponentSpec } from '../types.js';
2
+ export declare const Mount: ComponentSpec;
3
+ export declare const WebComponent: ComponentSpec;
@@ -1,10 +1,14 @@
1
1
  import { Expression, Program, Statement, ComponentDeclaration, EffectDeclaration, ActionDeclaration, HookDeclaration, DestructuringPattern } from '../parser/types.js';
2
2
  import { StateStore } from './state.js';
3
3
  import { HttpRuntime, EndpointResource } from './http.js';
4
+ import { DomManager } from './interop.js';
5
+ import { HeadManager } from './head.js';
4
6
  import { Router } from './router.js';
5
7
  import { ComponentLibrary } from '../library/types.js';
6
8
  import { ToastManager } from './toast.js';
7
9
  import { EnvManager } from './env.js';
10
+ /** Lazily build (and cache on the context) the `$head` document-head manager. */
11
+ export declare function getHeadManager(ctx: EvaluationContext): HeadManager;
8
12
  /**
9
13
  * Runtime safety budget — bounds the work a single render can perform
10
14
  * so a partial / accidentally-recursive program (e.g. while the user is
@@ -354,6 +358,17 @@ export interface EvaluationContext {
354
358
  * `getToastManager`; its auto-dismiss timers are cleared on dispose.
355
359
  */
356
360
  toastManager?: ToastManager;
361
+ /**
362
+ * Lazily-created singleton backing the reserved `$dom` observer namespace
363
+ * (`$dom.onResize`, `$dom.onIntersect`, `$dom.measure`, …). Every observer
364
+ * it creates registers on `disposers`, so all are torn down on replan.
365
+ */
366
+ domManager?: DomManager;
367
+ /**
368
+ * Lazily-created singleton backing the `$head({...})` document-head manager.
369
+ * Accumulates per-render contributions and feeds SSR's resolved `<head>`.
370
+ */
371
+ headManager?: HeadManager;
357
372
  /**
358
373
  * Lazily-created singleton backing the reactive environment namespaces
359
374
  * (`$viewport`, `$breakpoint`, `$scroll`, `$media`, `$mouse`). Listeners
@@ -0,0 +1,17 @@
1
+ import { EvaluationContext } from './evaluator.js';
2
+ export interface HeadManager {
3
+ /** Queue a `$head(...)` contribution for the current render pass. */
4
+ apply: (config: unknown) => void;
5
+ /** Force the queued contributions to commit immediately (used by SSR). */
6
+ flush: () => void;
7
+ /** Serialise the resolved head to an HTML string for SSR `<head>` injection. */
8
+ serialize: () => string;
9
+ /** The resolved `<html>` attributes (lang / dir / …) for SSR. */
10
+ htmlAttrs: () => Record<string, string>;
11
+ }
12
+ /**
13
+ * Build the per-context `$head` manager. Contributions accumulate per render
14
+ * pass (synchronously) and commit on a microtask, so the resolved head is the
15
+ * merge of every `$head(...)` that ran this pass.
16
+ */
17
+ export declare function createHeadManager(ctx: EvaluationContext): HeadManager;
@@ -0,0 +1,59 @@
1
+ import { EvaluationContext } from './evaluator.js';
2
+ export interface ScriptResource {
3
+ /** `true` once the resource has finished loading successfully. */
4
+ ready: boolean;
5
+ /** `true` while the resource is still downloading / executing. */
6
+ loading: boolean;
7
+ /** The load error, or `null` on success. */
8
+ error: unknown;
9
+ /**
10
+ * The resolved value. For a script with a `global`, this is
11
+ * `window[global]` once loaded (e.g. `window.Stripe`); otherwise `true`.
12
+ * `null` until ready.
13
+ */
14
+ value: unknown;
15
+ }
16
+ /**
17
+ * `$script({ src, global?, type?, as?, attributes? })` — load an external
18
+ * script (or stylesheet) exactly once, reactively gated on readiness. The
19
+ * returned bag's `ready` flag flips to `true` (and `value` to `window[global]`)
20
+ * when the resource finishes loading; reading any field subscribes the render.
21
+ */
22
+ export declare function createScriptResource(config: unknown, ctx: EvaluationContext): ScriptResource;
23
+ /** A disposer returned by an observer helper; calling it stops observing. */
24
+ export type DomDisposer = () => void;
25
+ export interface DomMeasurement {
26
+ /** The element's bounding rectangle (`getBoundingClientRect()`). */
27
+ rect: DOMRect | {
28
+ width: number;
29
+ height: number;
30
+ top: number;
31
+ left: number;
32
+ right: number;
33
+ bottom: number;
34
+ };
35
+ /** Scroll position + scrollable size of the element. */
36
+ scroll: {
37
+ top: number;
38
+ left: number;
39
+ width: number;
40
+ height: number;
41
+ };
42
+ /** Current viewport size. */
43
+ viewport: {
44
+ width: number;
45
+ height: number;
46
+ };
47
+ }
48
+ export interface DomManager {
49
+ onResize: (node: unknown, callback: unknown) => DomDisposer;
50
+ onIntersect: (node: unknown, callback: unknown, options?: unknown) => DomDisposer;
51
+ onMutation: (node: unknown, callback: unknown, options?: unknown) => DomDisposer;
52
+ measure: (node: unknown) => DomMeasurement | null;
53
+ }
54
+ /**
55
+ * Build the `$dom` observer manager for a context. Every observer it creates
56
+ * is registered on `ctx.disposers`, so a replan / disconnect tears them all
57
+ * down automatically — callers never have to remember to disconnect.
58
+ */
59
+ export declare function createDomManager(ctx: EvaluationContext): DomManager;
@@ -14,6 +14,18 @@ export interface RenderToStringResult {
14
14
  html: string;
15
15
  /** State snapshot to ship to the client for hydration. */
16
16
  state: Record<string, unknown>;
17
+ /**
18
+ * Resolved `<head>` markup emitted by every `$head({...})` the program ran
19
+ * during this render (title, meta, Open Graph / Twitter cards, links,
20
+ * JSON-LD). Inject it into the page shell's `<head>` so the SSR page is
21
+ * crawlable + shows social previews. Empty string when no `$head` ran.
22
+ */
23
+ head: string;
24
+ /**
25
+ * `<html>` attributes (e.g. `{ lang, dir }`) contributed via
26
+ * `$head({ htmlAttrs })` — spread onto the `<html>` element of the shell.
27
+ */
28
+ headAttrs: Record<string, string>;
17
29
  }
18
30
  /**
19
31
  * Render an Aktion program to an HTML string + hydration state.
@@ -31,5 +31,5 @@ export type { SemanticToken, SemanticTokenType, SemanticTokenModifier, } from '.
31
31
  export { getSignatureHelp, } from './signature-help.js';
32
32
  export type { SignatureHelp, SignatureInfo, ParameterInfo, } from './signature-help.js';
33
33
  export { htmlToAktion } from './html-import.js';
34
- export { componentSchema, tailwindToSx, buildGallery, suggestComponent, } from './schema.js';
34
+ export { componentSchema, tailwindToSx, cssToSx, styledToSx, buildGallery, suggestComponent, } from './schema.js';
35
35
  export type { LibrarySchema, ComponentSchemaEntry, ComponentPropSchema, GalleryOptions, } from './schema.js';
@@ -44,6 +44,38 @@ export declare function suggestComponent(name: unknown, library: ComponentLibrar
44
44
  * surface a warning instead of silently dropping intent.
45
45
  */
46
46
  export declare function tailwindToSx(classString: unknown): Record<string, unknown>;
47
+ /**
48
+ * Map a raw CSS declaration string to the closest Aktion `sx` object. The
49
+ * complement of `tailwindToSx` for migrations from inline `style="..."`,
50
+ * CSS Modules, or any hand-written rule body:
51
+ *
52
+ * cssToSx("display:flex; gap:12px; padding:0 16px; color:#1a1a1a")
53
+ * // → { display: "flex", gap: "12px", px: "16px", py: "0", color: "#1a1a1a" }
54
+ *
55
+ * Pass a full rule (`.btn { … }`) and the first rule body is used. Anything
56
+ * the bounded `sx` surface can't express (transforms, transitions, raw
57
+ * gradients, `box-shadow`, …) is returned verbatim under `_unmapped` so the
58
+ * caller can drop it into a `Css(...)` / `Styles(...)` escape hatch instead of
59
+ * losing it silently.
60
+ */
61
+ export declare function cssToSx(cssText: unknown): Record<string, unknown>;
62
+ /**
63
+ * Extract the static declarations from a styled-components / emotion template
64
+ * into an `sx` object. Accepts the template string (or the raw strings array
65
+ * of a tagged template) — `${…}` interpolations are stripped, and nested
66
+ * blocks (`&:hover { … }`, `@media { … }`, child selectors) are dropped into
67
+ * `_unmapped` since the bounded `sx` base layer can't host them (use
68
+ * `sx.hover` / `Styles(...)` for those):
69
+ *
70
+ * styledToSx(`
71
+ * display: flex;
72
+ * padding: 12px 16px;
73
+ * color: ${p => p.color};
74
+ * &:hover { opacity: 0.8; }
75
+ * `)
76
+ * // → { display: "flex", px: "16px", py: "12px", _unmapped: ["&:hover { … }"] }
77
+ */
78
+ export declare function styledToSx(template: unknown): Record<string, unknown>;
47
79
  export interface GalleryOptions {
48
80
  /** Page title (default "Aktion Components"). */
49
81
  title?: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "aktion-runtime",
3
- "version": "0.5.11",
3
+ "version": "0.5.13",
4
4
  "description": "Aktion is a single web component that turns a compact, streaming-first DSL into a rich, interactive UI inside its shadow DOM. Works in React, Vue, Angular, Svelte, plain HTML — or no framework at all.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",