@marko/runtime-tags 6.3.4 → 6.3.6

package/cheatsheet.md

@@ -14,7 +14,8 @@ Marko 6 = HTML superset. NOT JSX, NOT old Marko 4/5. `.marko` files are componen
    - object: `user = { ...user, name }`
 5. Events: method shorthand `onClick() { ... }` or `onClick=fn`. Handler gets the DOM event: `onSubmit(e) { e.preventDefault(); save() }`. Don't sync input values through `onInput`/`onChange` listeners — that's what change handlers (next rule) are for, and they make the data's owner explicit.
 6. Native inputs are UNCONTROLLED by default: `value=` only sets the initial value. Adding the matching `*Change` handler is what makes them controlled — `valueChange` on `<input>`/`<textarea>`/`<select>`, `checkedChange` on checkboxes/radios, `openChange` on `<details>`/`<dialog>`. `value:=text` is the shorthand for `value=text valueChange(v) { text = v }`. (`<textarea value:=text/>` — value attribute, not body.)
-7. Write the change handler yourself when updates need transforming — number inputs give STRINGS: `<input type="number" value=n valueChange(v) { n = +v }>`.
+7. Transform in the handler when needed — number inputs give STRINGS: `<input type="number" value=n valueChange(v) { n = +v }>`, or `value:parseFloat:=n`.
+8. Radio/checkbox groups: `checkedValue:=picked` on each input (shared var, distinct `value=`) — the match is checked; array var for multi-checkbox. Dropdown: `<select value:=picked>`.
 
 ## Canonical component (copy this shape)
 
@@ -109,7 +110,8 @@ Don't fetch while rendering: start data loads early, pass the PROMISE through th
 
 - Repeated attr tags (many `<@tab ...>`) arrive as the SINGULAR prop `input.tab`, which is iterable but NOT an array: `input.tab[i]` and `input.tab.length` are undefined. To index or count, spread first: `<const/tabs=[...input.tab ?? []]>` then `tabs[active]`/`tabs.length`. Looping directly is fine: `<for|tab| of=input.tab>`.
 - Conditional attrs: `false`/`null` attrs are omitted from HTML. `aria-selected` etc. want strings: `aria-selected=(i === active && "true")`.
-- `class=` / `style=` accept strings, objects, arrays: `class=["btn", { active }]`, `style={ color }` (single braces).
+- `class=` / `style=` accept strings, objects, arrays: `class=["btn", { active }]`, `style={ color }` (single braces). `style=` keys are kebab-case CSS names (`{ "background-color": c }`), not camelCase.
+- `<id/x>` mints a collision-free id for label/input wiring (`<label for=x>`/`<input id=x>`) — don't hardcode ids in reusable tags; `<id/x=input.id>` reuses a caller's.
 
 ## Client-side effects (rare — prefer state/const)
 
@@ -125,6 +127,26 @@ Don't fetch while rendering: start data loads early, pass the PROMISE through th
 
 `<style>` = real CSS, extracted & global. `<script>` = reactive effect, NOT an HTML script tag.
 
+Imperative libs (charts, maps) needing mount/update/destroy: use `<lifecycle>`, not a hand-wired `<script>`. `this` persists across all three; return an object from `onMount` to stash the instance:
+
+```marko
+<canvas/canvas/>
+<lifecycle
+  onMount() { return { chart: new Chart(canvas(), data) } }
+  onUpdate() { this.chart.setData(data) }         // re-runs when `data` changes
+  onDestroy() { this.chart.destroy() }
+/>
+```
+
+## Lazy loading
+
+Defer a tag's JS into its own bundle until a trigger fires: `render`, `visible#sel`, `idle`, `media(...)`, `on-click#sel` (combine with `|`). Server HTML renders immediately; `<try>` shows a `@placeholder` while loading. Don't hand-roll an `IntersectionObserver`.
+
+```marko
+import PriceChart from "<price-chart>" with { load: "visible#chart" }
+<div#chart><PriceChart symbol=input.symbol/></div>
+```
+
 ## DON'T (these are errors or silently wrong)
 
 | Wrong (React/Vue/Marko5 habit)                              | Right                                                                                |
@@ -144,3 +166,9 @@ Don't fetch while rendering: start data loads early, pass the PROMISE through th
 | `by=item` using the loop variable                           | `by="propName"` or `by=(item) => key` — `by=` is evaluated outside the loop          |
 | `onInput(e) { q = e.target.value }` to sync an input        | `value:=q` — the change handler owns the value                                       |
 | fetching inside the component that renders the data         | start the promise early (route handler / top of template), pass it down to `<await>` |
+| `style={ backgroundColor: c }` (camelCase keys)             | `style={ "background-color": c }` (kebab-case)                                       |
+| `this.querySelector` / `this.getRootNode()` in `<script>`   | element ref getter: `<div/el>` then `el()` (there is no `this`)                      |
+| `<div/my-el>` / `<input/card-input>` (hyphen in tag var)    | valid JS identifier: `<div/myEl>`                                                    |
+| hand-rolled radios `checked=x checkedChange(v){…}`          | `checkedValue:=picked` on each radio (shared var, distinct `value=`)                 |
+| hand-rolled `IntersectionObserver` to defer a widget's JS   | `import W from "<w>" with { load: "visible#sel" }`                                   |
+| imperative lib wired through `<script>` mount + cleanup     | `<lifecycle onMount/onUpdate/onDestroy>` (keeps `this` across all three)             |

package/dist/debug/dom.js

@@ -68,7 +68,12 @@ function _call(fn, v) {
 function stringifyClassObject(name, value) {
 	return value ? name : "";
 }
+const warnedStyleKeys = /* @__PURE__ */ new Set();
 function stringifyStyleObject(name, value) {
+	if (/[A-Z]/.test(name) && !name.includes("-") && !warnedStyleKeys.has(name)) {
+		warnedStyleKeys.add(name);
+		console.warn(`\`${name}\` is not a CSS property name; \`style\` object keys are written verbatim, so it renders as invalid CSS. Use \`${name.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase()).replace(/^ms-/, "-ms-")}\`.`);
+	}
 	return value || value === 0 ? name + ":" + value : "";
 }
 function escapeStyleValue(str) {

package/dist/debug/dom.mjs

@@ -66,7 +66,12 @@ function _call(fn, v) {
 function stringifyClassObject(name, value) {
 	return value ? name : "";
 }
+const warnedStyleKeys = /* @__PURE__ */ new Set();
 function stringifyStyleObject(name, value) {
+	if (/[A-Z]/.test(name) && !name.includes("-") && !warnedStyleKeys.has(name)) {
+		warnedStyleKeys.add(name);
+		console.warn(`\`${name}\` is not a CSS property name; \`style\` object keys are written verbatim, so it renders as invalid CSS. Use \`${name.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase()).replace(/^ms-/, "-ms-")}\`.`);
+	}
 	return value || value === 0 ? name + ":" + value : "";
 }
 function escapeStyleValue(str) {

package/dist/debug/html.js

@@ -64,7 +64,12 @@ function getWrongAttrSuggestion(name) {
 function stringifyClassObject(name, value) {
 	return value ? name : "";
 }
+const warnedStyleKeys = /* @__PURE__ */ new Set();
 function stringifyStyleObject(name, value) {
+	if (/[A-Z]/.test(name) && !name.includes("-") && !warnedStyleKeys.has(name)) {
+		warnedStyleKeys.add(name);
+		console.warn(`\`${name}\` is not a CSS property name; \`style\` object keys are written verbatim, so it renders as invalid CSS. Use \`${name.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase()).replace(/^ms-/, "-ms-")}\`.`);
+	}
 	return value || value === 0 ? name + ":" + value : "";
 }
 function escapeStyleValue(str) {

package/dist/debug/html.mjs

@@ -62,7 +62,12 @@ function getWrongAttrSuggestion(name) {
 function stringifyClassObject(name, value) {
 	return value ? name : "";
 }
+const warnedStyleKeys = /* @__PURE__ */ new Set();
 function stringifyStyleObject(name, value) {
+	if (/[A-Z]/.test(name) && !name.includes("-") && !warnedStyleKeys.has(name)) {
+		warnedStyleKeys.add(name);
+		console.warn(`\`${name}\` is not a CSS property name; \`style\` object keys are written verbatim, so it renders as invalid CSS. Use \`${name.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase()).replace(/^ms-/, "-ms-")}\`.`);
+	}
 	return value || value === 0 ? name + ":" + value : "";
 }
 function escapeStyleValue(str) {

package/dist/translator/index.d.ts

@@ -1,5 +1,6 @@
 import type { Config } from "@marko/compiler";
 export { version } from "../../package.json";
+export declare const cheatsheet = "../../cheatsheet.md";
 export declare const tagDiscoveryDirs: string[];
 export { default as internalEntryBuilder } from "./util/entry-builder";
 export declare const preferAPI = "tags";

package/dist/translator/index.js

@@ -3802,6 +3802,8 @@ var for_default = {
 			default: throw tag.buildCodeFrameError("The [`<for>` tag](https://markojs.com/docs/reference/core-tag#for) requires an `of=`, `in=`, or `to=` attribute.");
 		}
 		if (!isAttrTag) allowAttrs.push("by");
+		const keyAttr = tag.node.attributes.find((attr) => attr.type === "MarkoAttribute" && attr.name === "key");
+		if (keyAttr) throw tag.hub.buildError(keyAttr, `The [\`<for>\` tag](https://markojs.com/docs/reference/core-tag#for) keys items with the \`by=\` attribute, not \`key=\`. ${forType === "of" ? "Use `by=\"propName\"` or `by=(item, index) => key`" : forType === "in" ? "Use `by=(key, value) => key`" : "Use `by=(num) => key`"}.`);
 		(0, _marko_compiler_babel_utils.assertAllowedAttributes)(tag, allowAttrs);
 		if (isAttrTag) return;
 		const byAttr = getKnownAttrValues(tag.node).by;
@@ -4359,6 +4361,7 @@ var native_tag_default = {
 				seen[attr.name] = attr;
 				assertValidNativeAttrName(tag, attr);
 				assertNativeAttrValueType(tag, attr);
+				if (attr.name === "style") warnCamelCaseStyleKeys(tag, attr);
 				if (injectNonce && attr.name === "nonce") injectNonce = false;
 				if (isEventOrChangeHandler(attr.name)) assertNativeHandlerAttr(tag, attr);
 				if (isEventHandler(attr.name)) {
@@ -4810,6 +4813,19 @@ function assertNativeAttrValueType(tag, attr) {
 	if (_marko_compiler.types.isFunction(attr.value)) throw tag.hub.buildError(attr, `The \`${name}\` attribute cannot be a function.`, Error);
 	if (_marko_compiler.types.isObjectExpression(attr.value)) throw tag.hub.buildError(attr, `The \`${name}\` attribute cannot be a plain object (it would render as \`[object Object]\`).`, Error);
 }
+function warnCamelCaseStyleKeys(tag, attr) {
+	const { value } = attr;
+	const objects = value.type === "ObjectExpression" ? [value] : value.type === "ArrayExpression" ? value.elements.filter((el) => el?.type === "ObjectExpression") : [];
+	for (const object of objects) for (const prop of object.properties) {
+		if (prop.type !== "ObjectProperty" || prop.computed) continue;
+		const { key } = prop;
+		const name = key.type === "Identifier" ? key.name : key.type === "StringLiteral" ? key.value : void 0;
+		if (name && !name.startsWith("--") && !name.includes("-") && /[A-Z]/.test(name)) (0, _marko_compiler_babel_utils.diagnosticWarn)(tag, {
+			label: `\`${name}\` is not a CSS property name; the [\`style=\` object](https://markojs.com/docs/reference/native-tag#style) writes keys out verbatim (unlike the camelCased DOM style API), so this renders as invalid CSS the browser ignores. Use the kebab-case name \`${name.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase()).replace(/^ms-/, "-ms-")}\`.`,
+			loc: key.loc ?? void 0
+		});
+	}
+}
 function assertNativeHandlerAttr(tag, attr) {
 	if (_marko_compiler.types.isObjectExpression(attr.value)) throw tag.hub.buildError(attr.value, `The \`${attr.name}\` ${isEventHandler(attr.name) ? "event handler" : "change handler"} on a [native tag](https://markojs.com/docs/reference/native-tag) must be a function. Attribute values in Marko are plain JavaScript expressions, not JSX; remove the wrapping \`{ }\` (e.g. \`${attr.name}=myHandler\` or \`${attr.name}() { ... }\`).`, Error);
 	if ((0, _marko_compiler_babel_utils.computeNode)(attr.value)?.value) throw tag.hub.buildError(attr.value, `The \`${attr.name}\` ${isEventHandler(attr.name) ? "event handler" : "change handler"} on a [native tag](https://markojs.com/docs/reference/native-tag) must be a function or a falsey value (\`null\`, \`undefined\`, \`false\`, \`0\`, …).`, Error);
@@ -9339,8 +9355,9 @@ function getTagRelativePath(tag) {
 	const { node, hub: { file } } = tag;
 	let relativePath;
 	if (_marko_compiler.types.isStringLiteral(node.name)) {
-		const template = node.extra?.featureType === "class" && (0, _marko_compiler_babel_utils.getTagDef)(tag)?.renderer || (0, _marko_compiler_babel_utils.getTagTemplate)(tag);
-		relativePath = template && (0, _marko_compiler_babel_utils.resolveRelativePath)(file, template);
+		const tagDef = (0, _marko_compiler_babel_utils.getTagDef)(tag);
+		const template = node.extra?.featureType === "class" && tagDef?.renderer || (0, _marko_compiler_babel_utils.getTagTemplate)(tag);
+		relativePath = template && (0, _marko_compiler_babel_utils.resolveRelativePath)(file, template, tagDef);
 	} else if (node.extra?.tagNameImported) relativePath = node.extra.tagNameImported;
 	if (!relativePath) throw tagNotFoundError(tag);
 	return relativePath;
@@ -9355,13 +9372,36 @@ function tagNotFoundError(tag) {
 	if (tagName && tag.scope.hasBinding(tagName)) return tag.get("name").buildCodeFrameError(`Local variables must be in a [dynamic tag](https://markojs.com/docs/reference/language#dynamic-tags) unless they are PascalCase. Use \`<\${${tagName}}/>\` or rename to \`${tagName.charAt(0).toUpperCase() + tagName.slice(1)}\`.`);
 	let didYouMean = "";
 	const knownWrongTagHint = tagName && knownWrongTags.get(tagName);
+	const proseText = tagName && getProseText(tag);
 	if (knownWrongTagHint) didYouMean = ` ${knownWrongTagHint}`;
+	else if (proseText) didYouMean = ` If this line is meant to be text, prefix it with \`--\` (e.g. \`-- ${proseText}\`) or wrap it in an element such as \`<p>${proseText}</p>\`.`;
 	else if (tagName) {
 		const closestTag = (0, fastest_levenshtein.closest)(tagName, Object.keys((0, _marko_compiler_babel_utils.getTaglibLookup)(tag.hub.file).merged.tags));
 		if ((0, fastest_levenshtein.distance)(tagName, closestTag) < 4) didYouMean = ` Did you mean \`<${closestTag}>\`?`;
 	}
 	return tag.get("name").buildCodeFrameError(`Unable to find entry point for [custom tag](https://markojs.com/docs/reference/custom-tag#relative-custom-tags) \`<${tagName}>\`.${didYouMean}`);
 }
+const wordReg = /^[A-Za-z]+$/;
+function getProseText(tag) {
+	const { node } = tag;
+	const tagName = getTagName(tag);
+	if (!tagName || !wordReg.test(tagName) || node.var || node.body.params.length || node.body.body.length || !node.attributes.length || !isConciseModeTag(node)) return;
+	return collectProseWords(node, tagName);
+}
+function isConciseModeTag(node) {
+	const tagLoc = node.loc;
+	const nameLoc = node.name.loc;
+	if (!tagLoc || !nameLoc) return false;
+	return tagLoc.start.line === nameLoc.start.line && tagLoc.start.column === nameLoc.start.column;
+}
+function collectProseWords(node, tagName) {
+	let text = tagName;
+	for (const attr of node.attributes) {
+		if (attr.type !== "MarkoAttribute" || attr.default || !wordReg.test(attr.name) || attr.value.type !== "BooleanLiteral" || attr.value.value !== true) return;
+		text += " " + attr.name;
+	}
+	return text;
+}
 function importOrSelfReferenceName(file, request, name, nameHint) {
 	if (isCircularRequest(file, request)) return _marko_compiler.types.identifier(name);
 	return (0, _marko_compiler_babel_utils.importNamed)(file, request, name, nameHint);
@@ -9983,6 +10023,7 @@ function getVisitorExit(visit) {
 }
 //#endregion
 //#region src/translator/index.ts
+const cheatsheet = "../../cheatsheet.md";
 const visitors = extractVisitors({
 	Program: program_default,
 	Function: function_default,
@@ -10009,6 +10050,7 @@ function getRuntimeEntryFiles(output, optimize) {
 }
 //#endregion
 exports.analyze = analyze;
+exports.cheatsheet = cheatsheet;
 exports.createInteropTranslator = createInteropTranslator;
 exports.getRuntimeEntryFiles = getRuntimeEntryFiles;
 exports.internalEntryBuilder = entry_builder_default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marko/runtime-tags",
-  "version": "6.3.4",
+  "version": "6.3.6",
   "description": "Optimized runtime for Marko templates.",
   "keywords": [
     "api",
@@ -51,7 +51,7 @@
     "build": "node -r ~ts ./scripts/bundle.mts"
   },
   "dependencies": {
-    "@marko/compiler": "^5.40.2",
+    "@marko/compiler": "^5.41.1",
     "csstype": "^3.2.3",
     "fastest-levenshtein": "^1.0.16",
     "magic-string": "^0.30.21"