@tiaforge-ui/sinter 0.0.0-stage → 0.1.0

package/dist/compiler/diagnostic-docs.d.ts

@@ -0,0 +1,10 @@
+import type { Code } from './diagnostics.js';
+export interface DiagnosticDoc {
+    /** a message as the compiler prints it */
+    example: string;
+    /** what went wrong, in a sentence or two */
+    means: string;
+    /** what to change */
+    fix: string;
+}
+export declare const DIAGNOSTIC_DOCS: Record<Code, DiagnosticDoc>;

package/dist/compiler/diagnostic-docs.js

@@ -0,0 +1,137 @@
+export const DIAGNOSTIC_DOCS = {
+    SN101: {
+        example: '`data-sn-txt` is not a sinter attribute. Did you mean `data-sn-text`?',
+        means: 'An attribute starts with `data-sn-` but is not one sinter knows, usually a typo.',
+        fix: 'Use the suggested name. The attributes are listed in `llms.txt` and, in VS Code, completed from `html-custom-data.json`.',
+    },
+    SN102: {
+        example: '`data-sn-for` must be on a `<template>`',
+        means: 'The attribute or element is valid, but not here: lists and conditionals render from a `<template>`, `data-sn-path` belongs on `<html>`, `<sn-event>` inside `<sn-sync>`, and options such as `data-sn-debounce` need a method attribute on the same element.',
+        fix: 'Move it to where the message says, wrapping the content in a `<template>` if needed.',
+    },
+    SN103: {
+        example: 'a `data-sn-for` over primitive values needs `data-sn-key`',
+        means: 'sinter keys list rows by the resource key or by object identity. Strings and numbers have neither, so rows could not be matched on update.',
+        fix: 'Add `data-sn-key` with an expression that is unique per row, such as the value itself: `data-sn-key="tag"`.',
+    },
+    SN104: {
+        example: '`data-sn-model` does not support `type="file"`; submit the form instead',
+        means: 'Two-way binding has no meaningful value for this input type.',
+        fix: 'Submit the form with a method attribute (`data-sn-post`, …) on it; a form with a file input is sent as `FormData`.',
+    },
+    SN201: {
+        example: '`contcts` is not defined here. Did you mean `contacts`?',
+        means: 'An expression uses a name that is not a loop variable, state field, resource, magic name, helper or JavaScript global in this scope.',
+        fix: 'Fix the typo, declare the name in `data-sn-state`, or export it from the helpers module. Loop variables are only visible inside their `<template>`.',
+    },
+    SN202: {
+        example: '`window` is a browser API; expressions may use JavaScript, not the browser. Use an island',
+        means: 'Expressions may use JavaScript built-ins but not browser APIs such as `window`, `document`, `fetch` or timers, so pages stay safe under a strict CSP and testable.',
+        fix: 'Move the browser code into a helper (for a pure function) or an island (a custom element that owns imperative work).',
+    },
+    SN203: {
+        example: 'value expressions cannot assign; move this to `data-sn-on-*`',
+        means: 'A binding that produces a value (`text`, `attr`, `show`, `for`, …) tried to change state, which would run on every render. Path parameters of `$url` are read-only everywhere.',
+        fix: 'Do the assignment in an event handler (`data-sn-on-click`) or in an action\'s `then`.',
+    },
+    SN204: {
+        example: '`data-sn-optimistic` may only call `patch`, `upsert`, `remove`',
+        means: 'An optimistic change is undone when the request fails, so it may only use the store functions that sinter can roll back.',
+        fix: 'Express the change with `patch`, `upsert` or `remove`; set other state in `then`.',
+    },
+    SN205: {
+        example: '`m.is_read = true` mutates a resource. Use `patch(\'messages\', m, {is_read: true})`',
+        means: 'Resource data is read-only in expressions: it mirrors the server, and a direct write would be lost on the next refresh or event.',
+        fix: 'Use the `patch()` call from the message, or copy the item with `structuredClone(c)` to edit it in state.',
+    },
+    SN206: {
+        example: '`m.inbox_titel` is not exported by namespace `m`. Did you mean `inbox_title`?',
+        means: 'A helper namespace (for example paraglide messages) has no export of that name.',
+        fix: 'Use the suggested name, or add the export to the namespace module.',
+    },
+    SN207: {
+        example: '`onclick` cannot be bound with `data-sn-attr`; use `data-sn-on-click`',
+        means: 'The binding could run script or inject markup from data: event-handler attributes, `style`, `srcdoc`, `innerHTML`, bindings on `<script>` and similar elements, URL templates that do not start with a literal path, or persisted password fields.',
+        fix: 'Use the safe equivalent the message names: `data-sn-on-*` for events, `data-sn-style` for styles, a literal `/path` at the start of a URL template.',
+    },
+    SN208: {
+        example: 'Property \'nmae\' does not exist on type \'Contact\'. (TS2339)',
+        means: 'TypeScript found a type error in an expression. Reported by `sinter check`, `sinter({ typecheck: true })` and the editor integration.',
+        fix: 'Fix the expression, or the type: `type` on `<sn-resource>`, the OpenAPI spec, or a JSDoc cast in `data-sn-state`.',
+    },
+    SN301: {
+        example: 'resource `mesages` is not declared on this page',
+        means: 'A store call, `$meta` or embedded data (`data-sn-data`) names a resource that no `<sn-resource>` on the page or its partials declares.',
+        fix: 'Fix the name or add the `<sn-resource>` element.',
+    },
+    SN302: {
+        example: 'resource `contacts` is declared twice',
+        means: 'Two `<sn-resource>` elements on one page share a name, often once in the page and once in a partial.',
+        fix: 'Rename one, or remove the duplicate.',
+    },
+    SN303: {
+        example: '`$meta.contacts.loadng` is not a status field. Did you mean `loading`?',
+        means: '`$meta.<resource>` has a fixed set of fields: `loading`, `error`, `loadedAt`, `pending`, `total`, and with `paginate` also `page`, `pages`, `from`, `to`, `hasPrev`, `hasNext`.',
+        fix: 'Use the suggested field. A pagination field needs `paginate` on the resource.',
+    },
+    SN304: {
+        example: 'keyset pagination cannot jump to a page number. Use `paginate="offset"`',
+        means: 'Keyset (cursor) pagination only knows the next and previous page, so `page(\'name\', 7)` has nothing to jump to.',
+        fix: 'Use `paginate="offset"` if the API supports offsets, or only step with `next`, `prev` and `first`.',
+    },
+    SN305: {
+        example: 'partial `./partials/contact-dialg.html` not found or outside the project root',
+        means: 'The `src` of `<sn-include>` must be a literal path, relative to the including file, that resolves inside the project root.',
+        fix: 'Fix the path. Partials outside the root are refused on purpose.',
+    },
+    SN306: {
+        example: '`a.html` → `b.html` → `a.html` includes itself',
+        means: 'Partials include each other in a cycle.',
+        fix: 'Move the shared part into a third partial that neither includes back.',
+    },
+    SN307: {
+        example: 'OpenAPI spec `api.yml` is not an OpenAPI 3 document (needs `openapi: 3.x` and `paths`)',
+        means: 'A spec given to `sinter({ openapi })` is missing, unreadable, or not OpenAPI 3.',
+        fix: 'Fix the path in the Vite config, or convert a Swagger 2 spec to OpenAPI 3.',
+    },
+    SN308: {
+        example: 'the response of `GET /articles` has no `articls`. Did you mean `articles`?',
+        means: 'The resource matched an operation in the OpenAPI spec, but its `items` or `total` path is not in the response schema.',
+        fix: 'Fix the path in `items` or `total`, or the spec if the API changed.',
+    },
+    SN401: {
+        example: '`data-sn-for` takes `item in list` or `(item, i) in list`',
+        means: 'An attribute value has the wrong form: a JavaScript syntax error (the column points inside the attribute), or a value outside what the attribute accepts, such as `paginate` or `data-sn-concurrency`.',
+        fix: 'Fix the value as the message says. Handlers are statements separated by `;`; value bindings are a single expression.',
+    },
+    SN501: {
+        example: 'resource `addressbooks` is declared but never read',
+        means: 'The page fetches a resource that nothing on it uses, which costs a request on every load.',
+        fix: 'Remove the `<sn-resource>`, or use it.',
+    },
+    SN502: {
+        example: '`Date.now()` in a binding never updates. Use `$now`',
+        means: 'The binding reads the time or a random number once and is never re-rendered by it.',
+        fix: 'Use `$now`, which sinter updates, or compute the value in a handler.',
+    },
+    SN503: {
+        example: '`id` bound from data can shadow globals other scripts read (DOM clobbering)',
+        means: 'An `id` or `name` set from server data can create a global that overrides one another script relies on.',
+        fix: 'Prefix the value (`\'contact-\' + c.id`) or use a `data-*` attribute instead.',
+    },
+    SN504: {
+        example: 'resource `contacts` has no type: expressions using it are not checked',
+        means: 'The type checker has no type for the resource, so expressions that use it are not checked. Reported by `sinter check` only.',
+        fix: 'Add `type="Contact[]"` with a type from `src/sinter.types.ts`, configure an OpenAPI spec that matches `src`, or write `type="any"` to opt out.',
+    },
+    SN505: {
+        example: '`GET /articles` declares no query parameter `tagg`. Did you mean `tag`?',
+        means: 'A literal query parameter in `src` is not declared by the matched OpenAPI operation, usually a typo the server would ignore.',
+        fix: 'Use the suggested name, or add the parameter to the spec.',
+    },
+    SN506: {
+        example: 'event `contact_updated` has no type: expressions reading its payload are not checked',
+        means: 'An `<sn-event>` reads its payload but has no `type`, so those expressions are not checked. Reported by `sinter check` only.',
+        fix: 'Add `type` with a payload type from `src/sinter.types.ts`, or `type="any"` to opt out.',
+    },
+};

package/dist/compiler/diagnostics.d.ts

@@ -0,0 +1,56 @@
+export type Severity = 'error' | 'warning';
+export interface Diagnostic {
+    severity: Severity;
+    code: string;
+    message: string;
+    file: string;
+    line: number;
+    col: number;
+    hint?: string;
+    /** what an editor underlines, when it is more than the name at `line:col` (a whole attribute, a tag name) */
+    span?: {
+        line: number;
+        col: number;
+        endLine: number;
+        endCol: number;
+    };
+}
+export declare const CODES: {
+    readonly SN101: 'unknown-attribute';
+    readonly SN102: 'wrong-element';
+    readonly SN103: 'missing-key';
+    readonly SN104: 'unsupported-model';
+    readonly SN201: 'unknown-identifier';
+    readonly SN202: 'forbidden-global';
+    readonly SN203: 'side-effect';
+    readonly SN204: 'optimistic-scope';
+    readonly SN205: 'resource-mutation';
+    readonly SN206: 'unknown-namespace-member';
+    readonly SN207: 'unsafe-sink';
+    readonly SN208: 'type-error';
+    readonly SN301: 'unknown-resource';
+    readonly SN302: 'duplicate-resource';
+    readonly SN303: 'unknown-meta-field';
+    readonly SN304: 'keyset-jump';
+    readonly SN305: 'include-not-found';
+    readonly SN306: 'include-cycle';
+    readonly SN307: 'openapi-invalid';
+    readonly SN308: 'unknown-schema-field';
+    readonly SN401: 'parse-error';
+    readonly SN501: 'unused-resource';
+    readonly SN502: 'non-reactive-value';
+    readonly SN503: 'data-bound-id';
+    readonly SN504: 'untyped-resource';
+    readonly SN505: 'unknown-query-param';
+    readonly SN506: 'untyped-event';
+};
+export type Code = keyof typeof CODES;
+export declare const DOCS_URL = "https://github.com/tiaforge/sinter/blob/main/docs/diagnostics.md";
+/** Link to a code's section of `docs/diagnostics.md` (GitHub's heading anchor). */
+export declare function docsUrl(code: string): string;
+export declare function severityOf(code: Code): Severity;
+/** Formats a diagnostic the way the terminal and the testing module print it. */
+export declare function formatDiagnostic(d: Diagnostic): string;
+/** The closest candidate within a small edit distance, for "did you mean" messages. */
+export declare function suggest(name: string, candidates: Iterable<string>): string | undefined;
+export declare function didYouMean(name: string, candidates: Iterable<string>): string;

package/dist/compiler/diagnostics.js

@@ -0,0 +1,76 @@
+export const CODES = {
+    SN101: 'unknown-attribute',
+    SN102: 'wrong-element',
+    SN103: 'missing-key',
+    SN104: 'unsupported-model',
+    SN201: 'unknown-identifier',
+    SN202: 'forbidden-global',
+    SN203: 'side-effect',
+    SN204: 'optimistic-scope',
+    SN205: 'resource-mutation',
+    SN206: 'unknown-namespace-member',
+    SN207: 'unsafe-sink',
+    SN208: 'type-error',
+    SN301: 'unknown-resource',
+    SN302: 'duplicate-resource',
+    SN303: 'unknown-meta-field',
+    SN304: 'keyset-jump',
+    SN305: 'include-not-found',
+    SN306: 'include-cycle',
+    SN307: 'openapi-invalid',
+    SN308: 'unknown-schema-field',
+    SN401: 'parse-error',
+    SN501: 'unused-resource',
+    SN502: 'non-reactive-value',
+    SN503: 'data-bound-id',
+    SN504: 'untyped-resource',
+    SN505: 'unknown-query-param',
+    SN506: 'untyped-event',
+};
+export const DOCS_URL = 'https://github.com/tiaforge/sinter/blob/main/docs/diagnostics.md';
+/** Link to a code's section of `docs/diagnostics.md` (GitHub's heading anchor). */
+export function docsUrl(code) {
+    const name = CODES[code];
+    return `${DOCS_URL}#${code.toLowerCase()}${name ? `-${name}` : ''}`;
+}
+export function severityOf(code) {
+    return code >= 'SN500' ? 'warning' : 'error';
+}
+/** Formats a diagnostic the way the terminal and the testing module print it. */
+export function formatDiagnostic(d) {
+    const name = CODES[d.code] ?? '';
+    let s = `${d.file}:${d.line}:${d.col} ${d.severity} ${d.code} ${name}: ${d.message}`;
+    if (d.hint)
+        s += `\n  hint: ${d.hint}`;
+    return s + `\n  docs: ${docsUrl(d.code)}`;
+}
+function distance(a, b) {
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diag = prev[0];
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = prev[j];
+            prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diag = tmp;
+        }
+    }
+    return prev[b.length];
+}
+/** The closest candidate within a small edit distance, for "did you mean" messages. */
+export function suggest(name, candidates) {
+    let best;
+    let bestD = Math.max(2, Math.floor(name.length / 3)) + 1;
+    for (const c of candidates) {
+        const d = distance(name.toLowerCase(), c.toLowerCase());
+        if (d < bestD) {
+            best = c;
+            bestD = d;
+        }
+    }
+    return best;
+}
+export function didYouMean(name, candidates) {
+    const s = suggest(name, candidates);
+    return s ? ` Did you mean \`${s}\`?` : '';
+}

package/dist/compiler/expr.d.ts

@@ -0,0 +1,89 @@
+import * as acorn from 'acorn';
+import { type Code } from './diagnostics.js';
+type Node = acorn.AnyNode & {
+    start: number;
+    end: number;
+};
+export type Mode = 'value' | 'handler' | 'optimistic';
+export interface LoopEntry {
+    name: string;
+    kind: 'item' | 'index';
+    /** item over a state path: its path with the instance index (`$s1.draft.emails.{$i3}`) */
+    alias: string[] | null;
+    /** item rooted at a resource */
+    resource: string | null;
+    /** index: the item's alias, so `list[i]` over the same list becomes the row's own element */
+    of?: string[] | null;
+}
+export interface StateEntry {
+    sid: number;
+    names: Set<string>;
+}
+export interface ResourceInfo {
+    name: string;
+    key: string[] | null;
+    paginate: string | null;
+    used: boolean;
+}
+export interface Scope {
+    loops: LoopEntry[];
+    states: StateEntry[];
+}
+export interface PageInfo {
+    resources: Map<string, ResourceInfo>;
+    helpers: Set<string>;
+    namespaces: Map<string, Set<string>>;
+    /** imports used by emitted code */
+    usedHelpers: Set<string>;
+    usedNs: Map<string, Set<string>>;
+    usesNow: boolean;
+    /** `:name` segments of the page's `data-sn-path` patterns */
+    pathParams: Set<string>;
+}
+export interface ExprOptions {
+    mode: Mode;
+    /** magic names allowed here besides the everywhere ones */
+    magic?: string[];
+    /** free identifiers resolve to fields of `$.$p` (sn-event, cursor) */
+    payload?: boolean;
+    /** parse as `{...}` object literal; returns its entries */
+    object?: 'literal-keys' | 'any-keys' | 'state';
+    report: (code: Code, message: string, offset: number, hint?: string) => void;
+}
+export interface ObjectEntry {
+    key: string;
+    code: string;
+    deps: string[];
+    offset: number;
+    literal: boolean;
+}
+export interface ExprResult {
+    ok: boolean;
+    code: string;
+    deps: string[];
+    writes: string[];
+    usesEl: boolean;
+    /** reads a loop index variable */
+    usesIndex: boolean;
+    entries?: ObjectEntry[];
+    /** the expression is a plain member path */
+    path: string[] | null;
+    /** resource the expression is rooted at */
+    resource: string | null;
+    ast: Node | null;
+    /** names resolved to payload fields (`payload` mode) */
+    payloadNames?: string[];
+}
+export declare const ALL_MAGIC: string[];
+export declare const STORE_FNS: string[];
+export declare const BUILTIN_HELPERS: string[];
+export declare const META_FIELDS: string[];
+export declare const GLOBALS: Set<string>;
+interface Edit {
+    start: number;
+    end: number;
+    text: string;
+}
+export declare function analyze(src: string, scope: Scope, page: PageInfo, opts: ExprOptions): ExprResult;
+export declare function applyEdits(src: string, edits: Edit[]): string;
+export {};