@knighted/jsx 1.5.2 → 1.6.1

package/README.md

@@ -19,6 +19,7 @@ A runtime JSX template tag backed by the [`oxc-parser`](https://github.com/oxc-p
 - [Loader integration](#loader-integration)
 - [Node / SSR usage](#node--ssr-usage)
 - [Browser usage](#browser-usage)
+- [Development diagnostics](docs/development-diagnostics.md)
 - [TypeScript plugin](docs/ts-plugin.md)
 - [TypeScript guide](docs/typescript.md)
 - [Component testing](docs/testing.md)

package/dist/cjs/cli/init.cjs

@@ -165,6 +165,21 @@ function parsePackageName(spec) {
     return { name, version };
 }
 function readLocalOxcParserVersion(resolver = CLI_REQUIRE) {
+    try {
+        // Prefer the version installed alongside this CLI package, not a hoisted sibling.
+        const jsxPkgPath = resolver.resolve('@knighted/jsx/package.json');
+        const jsxRoot = node_path_1.default.dirname(jsxPkgPath);
+        const localParserPkg = node_path_1.default.join(jsxRoot, 'node_modules', 'oxc-parser', 'package.json');
+        if (node_fs_1.default.existsSync(localParserPkg)) {
+            const pkgJson = JSON.parse(node_fs_1.default.readFileSync(localParserPkg, 'utf8'));
+            if (pkgJson && typeof pkgJson.version === 'string') {
+                return pkgJson.version;
+            }
+        }
+    }
+    catch {
+        // Ignore resolution failures and fall back below.
+    }
     try {
         const pkg = resolver('oxc-parser/package.json');
         if (pkg && typeof pkg.version === 'string') {

package/dist/cjs/debug/diagnostics.cjs

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.disableJsxDebugDiagnostics = exports.enableJsxDebugDiagnostics = void 0;
+const attribute_resolution_js_1 = require("../internal/attribute-resolution.cjs");
+const event_bindings_js_1 = require("../internal/event-bindings.cjs");
+const dev_environment_js_1 = require("../internal/dev-environment.cjs");
+const isAsciiLowercase = (char) => char >= 'a' && char <= 'z';
+let diagnosticsMode = 'env';
+const shouldRunDiagnostics = () => diagnosticsMode === 'always' || (diagnosticsMode === 'env' && (0, dev_environment_js_1.isDevEnvironment)());
+const shouldForceWarnings = () => diagnosticsMode === 'always';
+const attributeDiagnostics = {
+    warnLowercaseEventProp(name) {
+        if (!shouldRunDiagnostics()) {
+            return;
+        }
+        if (!name.startsWith('on') || name.startsWith('on:') || name.length < 3) {
+            return;
+        }
+        const indicator = name[2] ?? '';
+        if (!isAsciiLowercase(indicator)) {
+            return;
+        }
+        const suggestion = `${name.slice(0, 2)}${indicator.toUpperCase()}${name.slice(3)}`;
+        (0, dev_environment_js_1.emitDevWarning)(`Use camelCase DOM event props when targeting runtime jsx templates. Received "${name}"; did you mean "${suggestion}"?`, shouldForceWarnings());
+    },
+    ensureValidDangerouslySetInnerHTML(value) {
+        if (!shouldRunDiagnostics()) {
+            return;
+        }
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw (0, dev_environment_js_1.createDevError)('dangerouslySetInnerHTML expects an object with a string __html field.');
+        }
+        const html = value.__html;
+        if (typeof html !== 'string') {
+            throw (0, dev_environment_js_1.createDevError)(`dangerouslySetInnerHTML.__html must be a string but received ${(0, dev_environment_js_1.describeValue)(html)}.`);
+        }
+    },
+};
+const eventDiagnostics = {
+    onInvalidHandler(propName, value) {
+        if (!shouldRunDiagnostics()) {
+            return;
+        }
+        throw (0, dev_environment_js_1.createDevError)(`The "${propName}" prop expects a function, EventListenerObject, or descriptor ({ handler }) but received ${(0, dev_environment_js_1.describeValue)(value)}.`);
+    },
+};
+const enableJsxDebugDiagnostics = (options) => {
+    diagnosticsMode = options?.mode ?? 'env';
+    (0, attribute_resolution_js_1.setAttributeDiagnosticsHooks)(attributeDiagnostics);
+    (0, event_bindings_js_1.setEventDiagnosticsHooks)(eventDiagnostics);
+};
+exports.enableJsxDebugDiagnostics = enableJsxDebugDiagnostics;
+const disableJsxDebugDiagnostics = () => {
+    (0, attribute_resolution_js_1.setAttributeDiagnosticsHooks)(null);
+    (0, event_bindings_js_1.setEventDiagnosticsHooks)(null);
+};
+exports.disableJsxDebugDiagnostics = disableJsxDebugDiagnostics;

package/dist/cjs/debug/diagnostics.d.cts

@@ -0,0 +1,6 @@
+export type JsxDiagnosticsMode = 'env' | 'always';
+export type EnableJsxDebugDiagnosticsOptions = {
+    mode?: JsxDiagnosticsMode;
+};
+export declare const enableJsxDebugDiagnostics: (options?: EnableJsxDebugDiagnosticsOptions) => void;
+export declare const disableJsxDebugDiagnostics: () => void;

package/dist/cjs/debug/index.cjs

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsx = void 0;
+const diagnostics_js_1 = require("./diagnostics.cjs");
+(0, diagnostics_js_1.enableJsxDebugDiagnostics)({ mode: 'always' });
+var jsx_js_1 = require("../jsx.cjs");
+Object.defineProperty(exports, "jsx", { enumerable: true, get: function () { return jsx_js_1.jsx; } });

package/dist/cjs/debug/index.d.cts

@@ -0,0 +1,2 @@
+export { jsx } from '../jsx.cjs';
+export type { JsxRenderable, JsxComponent } from '../jsx.cjs';

package/dist/cjs/internal/attribute-resolution.cjs

@@ -1,10 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createResolveAttributes = void 0;
+exports.createResolveAttributes = exports.setAttributeDiagnosticsHooks = void 0;
+let attributeDiagnostics = null;
+const setAttributeDiagnosticsHooks = (hooks) => {
+    attributeDiagnostics = hooks;
+};
+exports.setAttributeDiagnosticsHooks = setAttributeDiagnosticsHooks;
+const warnLowercaseEventProp = (name) => {
+    attributeDiagnostics?.warnLowercaseEventProp?.(name);
+};
+const ensureValidDangerouslySetInnerHTML = (value) => {
+    attributeDiagnostics?.ensureValidDangerouslySetInnerHTML?.(value);
+};
 const createResolveAttributes = (deps) => {
     const { getIdentifierName, evaluateExpressionWithNamespace } = deps;
     return (attributes, ctx, namespace) => {
         const props = {};
+        const assignProp = (propName, propValue) => {
+            if (propName === 'dangerouslySetInnerHTML') {
+                ensureValidDangerouslySetInnerHTML(propValue);
+            }
+            props[propName] = propValue;
+        };
         attributes.forEach(attribute => {
             if (attribute.type === 'JSXSpreadAttribute') {
                 const spreadValue = evaluateExpressionWithNamespace(attribute.argument, ctx, namespace);
@@ -16,19 +33,20 @@ const createResolveAttributes = (deps) => {
                 return;
             }
             const name = getIdentifierName(attribute.name);
+            warnLowercaseEventProp(name);
             if (!attribute.value) {
-                props[name] = true;
+                assignProp(name, true);
                 return;
             }
             if (attribute.value.type === 'Literal') {
-                props[name] = attribute.value.value;
+                assignProp(name, attribute.value.value);
                 return;
             }
             if (attribute.value.type === 'JSXExpressionContainer') {
                 if (attribute.value.expression.type === 'JSXEmptyExpression') {
                     return;
                 }
-                props[name] = evaluateExpressionWithNamespace(attribute.value.expression, ctx, namespace);
+                assignProp(name, evaluateExpressionWithNamespace(attribute.value.expression, ctx, namespace));
             }
         });
         return props;

package/dist/cjs/internal/attribute-resolution.d.cts

@@ -1,5 +1,10 @@
 import type { Expression, JSXAttribute, JSXElement, JSXFragment, JSXSpreadAttribute } from '@oxc-project/types';
 import type { TemplateComponent, TemplateContext } from '../runtime/shared.cjs';
+export type AttributeDiagnosticsHooks = {
+    warnLowercaseEventProp?: (name: string) => void;
+    ensureValidDangerouslySetInnerHTML?: (value: unknown) => void;
+};
+export declare const setAttributeDiagnosticsHooks: (hooks: AttributeDiagnosticsHooks | null) => void;
 export type Namespace = 'svg' | null;
 export type EvaluateExpressionWithNamespace<TComponent extends TemplateComponent> = (expression: Expression | JSXElement | JSXFragment, ctx: TemplateContext<TComponent>, namespace: Namespace) => unknown;
 export type ResolveAttributesDependencies<TComponent extends TemplateComponent> = {

package/dist/cjs/internal/dev-environment.cjs

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitDevWarning = exports.createDevError = exports.describeValue = exports.isDevEnvironment = void 0;
+const DEV_PREFIX = '@knighted/jsx';
+const formatDevMessage = (message) => `${DEV_PREFIX}: ${message}`;
+const isDevEnvironment = () => typeof process !== 'undefined' && process.env?.KNIGHTED_JSX_DEBUG === '1';
+exports.isDevEnvironment = isDevEnvironment;
+const describeValue = (value) => {
+    if (value === null) {
+        return 'null';
+    }
+    if (value === undefined) {
+        return 'undefined';
+    }
+    if (typeof value === 'function') {
+        return value.name ? `function ${value.name}` : 'function';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    if (typeof value === 'object') {
+        const ctor = value.constructor;
+        if (ctor && typeof ctor.name === 'string' && ctor.name && ctor.name !== 'Object') {
+            return `${ctor.name} instance`;
+        }
+        return 'object';
+    }
+    return typeof value;
+};
+exports.describeValue = describeValue;
+const createDevError = (message) => new Error(formatDevMessage(message));
+exports.createDevError = createDevError;
+const emitDevWarning = (message, force = false) => {
+    if (!force && !(0, exports.isDevEnvironment)()) {
+        return;
+    }
+    if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+        console.warn(formatDevMessage(message));
+    }
+};
+exports.emitDevWarning = emitDevWarning;

package/dist/cjs/internal/dev-environment.d.cts

@@ -0,0 +1,4 @@
+export declare const isDevEnvironment: () => boolean;
+export declare const describeValue: (value: unknown) => string;
+export declare const createDevError: (message: string) => Error;
+export declare const emitDevWarning: (message: string, force?: boolean) => void;

package/dist/cjs/internal/event-bindings.cjs

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveEventHandlerValue = exports.parseEventPropName = void 0;
+exports.resolveEventHandlerValue = exports.parseEventPropName = exports.setEventDiagnosticsHooks = void 0;
+let eventDiagnostics = null;
+const setEventDiagnosticsHooks = (hooks) => {
+    eventDiagnostics = hooks;
+};
+exports.setEventDiagnosticsHooks = setEventDiagnosticsHooks;
 const captureSuffix = 'Capture';
 const stripCaptureSuffix = (rawName) => {
     if (rawName.endsWith(captureSuffix)) {
@@ -54,11 +59,15 @@ const isEventHandlerDescriptor = (value) => {
     }
     return isEventListenerObject(handler);
 };
-const resolveEventHandlerValue = (value) => {
+const throwInvalidHandlerError = (propName, value) => {
+    eventDiagnostics?.onInvalidHandler?.(propName, value);
+};
+const resolveEventHandlerValue = (propName, value) => {
     if (typeof value === 'function' || isEventListenerObject(value)) {
         return { listener: value };
     }
     if (!isEventHandlerDescriptor(value)) {
+        throwInvalidHandlerError(propName, value);
         return null;
     }
     const descriptor = value;

package/dist/cjs/internal/event-bindings.d.cts

@@ -1,3 +1,7 @@
+export type EventDiagnosticsHooks = {
+    onInvalidHandler?: (propName: string, value: unknown) => void;
+};
+export declare const setEventDiagnosticsHooks: (hooks: EventDiagnosticsHooks | null) => void;
 export type ParsedEventBinding = {
     eventName: string;
     capture: boolean;
@@ -15,4 +19,4 @@ export type ResolvedEventHandler = {
     listener: EventListenerOrEventListenerObject;
     options?: AddEventListenerOptions;
 };
-export declare const resolveEventHandlerValue: (value: unknown) => ResolvedEventHandler | null;
+export declare const resolveEventHandlerValue: (propName: string, value: unknown) => ResolvedEventHandler | null;

package/dist/cjs/internal/template-diagnostics.cjs

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatTaggedTemplateParserError = void 0;
+const DEFAULT_LABEL = 'oxc-parser';
+const buildTemplateDisplaySource = (templates) => {
+    const raw = templates.raw ?? templates;
+    let source = raw[0] ?? '';
+    const spans = [];
+    for (let idx = 0; idx < raw.length - 1; idx++) {
+        const label = '${expr#' + idx + '}';
+        const templateStart = source.length;
+        source += label;
+        const templateEnd = source.length;
+        spans.push({ index: idx, templateStart, templateEnd, label });
+        source += raw[idx + 1] ?? '';
+    }
+    return { source, spans };
+};
+const combineExpressionSpans = (diagnostics, templateSpans) => {
+    const templateSpanMap = new Map();
+    templateSpans.forEach(span => {
+        templateSpanMap.set(span.index, span);
+    });
+    return diagnostics.expressionRanges
+        .map(span => {
+        const templateSpan = templateSpanMap.get(span.index);
+        if (!templateSpan) {
+            return null;
+        }
+        const sourceLength = Math.max(0, span.sourceEnd - span.sourceStart);
+        const templateLength = Math.max(0, templateSpan.templateEnd - templateSpan.templateStart);
+        return {
+            sourceStart: span.sourceStart,
+            sourceEnd: span.sourceEnd,
+            templateStart: templateSpan.templateStart,
+            templateEnd: templateSpan.templateEnd,
+            delta: templateLength - sourceLength,
+        };
+    })
+        .filter((span) => Boolean(span))
+        .sort((a, b) => a.sourceStart - b.sourceStart);
+};
+const mapIndexToTemplate = (index, spans, templateLength) => {
+    if (!Number.isFinite(index) || index <= 0) {
+        return 0;
+    }
+    let delta = 0;
+    for (const span of spans) {
+        if (index < span.sourceStart) {
+            break;
+        }
+        if (index < span.sourceEnd) {
+            const relative = Math.max(0, index - span.sourceStart);
+            const templateSpanLength = Math.max(0, span.templateEnd - span.templateStart);
+            if (templateSpanLength === 0) {
+                return span.templateStart;
+            }
+            const clamped = Math.min(relative, Math.max(0, templateSpanLength - 1));
+            return span.templateStart + clamped;
+        }
+        delta += span.delta;
+    }
+    const mapped = index + delta;
+    if (mapped <= 0) {
+        return 0;
+    }
+    if (mapped >= templateLength) {
+        return templateLength;
+    }
+    return mapped;
+};
+const getLineAndColumnFromIndex = (source, index) => {
+    const limit = Math.max(0, Math.min(index, source.length));
+    let line = 1;
+    let column = 1;
+    for (let idx = 0; idx < limit; idx++) {
+        if (source.charCodeAt(idx) === 10) {
+            line++;
+            column = 1;
+            continue;
+        }
+        column++;
+    }
+    return { line, column };
+};
+const computeLineOffsets = (lines) => {
+    const offsets = [];
+    let cursor = 0;
+    lines.forEach((line, index) => {
+        offsets.push(cursor);
+        cursor += line.length;
+        if (index < lines.length - 1) {
+            cursor += 1;
+        }
+    });
+    return offsets;
+};
+const createPointerLine = (lineNumber, lineText, lineStartOffset, rangeStart, rangeEnd, startLine, endLine) => {
+    const lineEndOffset = lineStartOffset + lineText.length;
+    const overlapStart = Math.max(rangeStart, lineStartOffset);
+    const overlapEnd = Math.min(rangeEnd, lineEndOffset);
+    if (overlapEnd > overlapStart) {
+        const pointerStart = Math.max(0, overlapStart - lineStartOffset);
+        const pointerWidth = Math.max(1, overlapEnd - overlapStart);
+        return ' '.repeat(pointerStart) + '^'.repeat(pointerWidth);
+    }
+    if (lineText.length === 0 && lineNumber >= startLine && lineNumber <= endLine) {
+        return '^';
+    }
+    if (lineNumber === startLine) {
+        const caretPos = Math.max(0, rangeStart - lineStartOffset);
+        return ' '.repeat(Math.min(caretPos, lineText.length)) + '^';
+    }
+    return '';
+};
+const buildCodeFrame = (source, start, end, startLine, endLine) => {
+    if (!source.length) {
+        return '';
+    }
+    const lines = source.split('\n');
+    const offsets = computeLineOffsets(lines);
+    const frameStart = Math.max(1, startLine - 1);
+    const frameEnd = Math.min(lines.length, endLine + 1);
+    const gutterWidth = String(frameEnd).length;
+    const frame = [];
+    for (let lineNumber = frameStart; lineNumber <= frameEnd; lineNumber++) {
+        const lineText = lines[lineNumber - 1] ?? '';
+        const gutter = String(lineNumber).padStart(gutterWidth, ' ');
+        frame.push(`${gutter} | ${lineText}`);
+        const pointer = createPointerLine(lineNumber, lineText, offsets[lineNumber - 1] ?? 0, start, end, startLine, endLine);
+        if (pointer) {
+            frame.push(`${' '.repeat(gutterWidth)} | ${pointer}`);
+        }
+    }
+    return frame.join('\n');
+};
+const formatTaggedTemplateParserError = (tagName, templates, diagnostics, error, options) => {
+    const label = options?.label ?? DEFAULT_LABEL;
+    const fallback = `[${label}] ${error.message}`;
+    const primaryLabel = error.labels?.[0];
+    if (!primaryLabel) {
+        return fallback;
+    }
+    const { source: templateSource, spans } = buildTemplateDisplaySource(templates);
+    const combinedSpans = combineExpressionSpans(diagnostics, spans);
+    const mapIndex = (value) => {
+        const numeric = typeof value === 'number' ? value : 0;
+        return mapIndexToTemplate(numeric, combinedSpans, templateSource.length);
+    };
+    const startIndex = mapIndex(primaryLabel.start);
+    let endIndex = mapIndex(primaryLabel.end);
+    if (endIndex <= startIndex) {
+        endIndex = Math.min(templateSource.length, startIndex + 1);
+    }
+    const startLocation = getLineAndColumnFromIndex(templateSource, startIndex);
+    const endLocation = getLineAndColumnFromIndex(templateSource, Math.max(startIndex, endIndex - 1));
+    const codeframe = buildCodeFrame(templateSource, startIndex, endIndex, startLocation.line, endLocation.line);
+    let message = `[${label}] ${error.message}`;
+    message += `\n--> ${tagName} template:${startLocation.line}:${startLocation.column}`;
+    if (primaryLabel.message) {
+        message += `\n${primaryLabel.message}`;
+    }
+    if (codeframe) {
+        message += `\n${codeframe}`;
+    }
+    if (error.helpMessage) {
+        message += `\n${error.helpMessage}`;
+    }
+    return message;
+};
+exports.formatTaggedTemplateParserError = formatTaggedTemplateParserError;

package/dist/cjs/internal/template-diagnostics.d.cts

@@ -0,0 +1,13 @@
+import type { OxcError } from 'oxc-parser';
+export type TemplateExpressionRange = {
+    index: number;
+    sourceStart: number;
+    sourceEnd: number;
+};
+export type TemplateDiagnostics = {
+    expressionRanges: TemplateExpressionRange[];
+};
+export type TaggedTemplateFormatOptions = {
+    label?: string;
+};
+export declare const formatTaggedTemplateParserError: (tagName: string, templates: TemplateStringsArray, diagnostics: TemplateDiagnostics, error: OxcError, options?: TaggedTemplateFormatOptions) => string;

package/dist/cjs/jsx.cjs

@@ -116,7 +116,7 @@ const setDomProp = (element, name, value, namespace) => {
     }
     const eventBinding = (0, event_bindings_js_1.parseEventPropName)(name);
     if (eventBinding) {
-        const handlerValue = (0, event_bindings_js_1.resolveEventHandlerValue)(value);
+        const handlerValue = (0, event_bindings_js_1.resolveEventHandlerValue)(name, value);
         if (handlerValue) {
             let options = handlerValue.options ? { ...handlerValue.options } : undefined;
             if (eventBinding.capture) {
@@ -311,7 +311,7 @@ const jsx = (templates, ...values) => {
     const build = (0, shared_js_1.buildTemplate)(templates, values);
     const result = (0, oxc_parser_1.parseSync)('inline.jsx', build.source, shared_js_1.parserOptions);
     if (result.errors.length > 0) {
-        throw new Error((0, shared_js_1.formatParserError)(result.errors[0]));
+        throw new Error((0, shared_js_1.formatTaggedTemplateParserError)('jsx', templates, build.diagnostics, result.errors[0]));
     }
     const root = (0, shared_js_1.extractRootNode)(result.program);
     const ctx = {