@jxsuite/runtime 7.0.0 → 7.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/runtime",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "description": "JSON-native reactive web component runtime",
   "license": "MIT",
   "repository": {
@@ -33,12 +33,12 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "^6.0.0",
-    "@vue/reactivity": "3.5.44"
+    "@jxsuite/schema": "^6.0.2",
+    "@vue/reactivity": "3.5.45"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^21.0.4",
-    "@jxsuite/erase": "^0.3.0",
+    "@jxsuite/erase": "^0.3.2",
     "@jxsuite/test-support": "^0.0.0"
   }
 }

package/src/css.ts

@@ -507,8 +507,8 @@ export interface CssRule {
    * It is NOT in {@link CssRule.text}, and that is the point. `text` is what a sheet inserts and
    * what {@link hashCss} interns, so prose there would make two identical rules two rules and put a
    * paragraph in every adopted sheet at runtime. A static emitter — the one writing a stylesheet a
-   * person will read — renders it as a comment; every other consumer ignores it, exactly as a
-   * document's own `$description` is ignored.
+   * person will read — renders it as a comment through {@link commentedRuleText}; every other
+   * consumer ignores it, exactly as a document's own `$description` is ignored.
    */
   description?: string;
   /** See {@link CssRuleTarget}. */
@@ -521,8 +521,8 @@ export interface CssRule {
 export interface CssBuildOptions {
   /**
    * The selector the style object hangs off. Every nested key resolves against it, so the runtime
-   * passes a placeholder it substitutes afterwards and the compiler passes `#id` / `.jx-N` / a
-   * tag.
+   * passes a placeholder it substitutes afterwards and the compiler passes an element's generated
+   * class or a component's tag.
    */
   scope?: string | null;
   /** The project's `$media` map, for resolving `@--name` keys. */
@@ -614,6 +614,25 @@ export function cssRuleText(
   return text;
 }
 
+/**
+ * A rule as a static build writes it: its `$description` as a comment on the line above, then its
+ * text (spec.md §9.2). An undescribed rule is its text, byte for byte.
+ *
+ * CSS comments have no escape, so a comment terminator in the prose (an asterisk and then a slash)
+ * is written with a space between the two: breaking the sequence is the only way to keep the
+ * comment from ending early. The prose is otherwise verbatim, newlines included.
+ *
+ * @param {Pick<CssRule, "text" | "description">} rule
+ * @returns {string}
+ * @docs framework/concepts/styling
+ */
+export function commentedRuleText(rule: Pick<CssRule, "text" | "description">): string {
+  if (rule.description === undefined) {
+    return rule.text;
+  }
+  return `/* ${rule.description.replaceAll("*/", "* /")} */\n${rule.text}`;
+}
+
 /**
  * Serialize one `@keyframes` block: every stop, in authored order, inside ONE at-rule, wrapped in
  * its enclosing conditions.
@@ -815,6 +834,10 @@ export function buildStyleRules(style: JxStyle, options: CssBuildOptions = {}):
     return declarations;
   };
 
+  /** A block's `$description` as the member a rule carries, when it wrote a non-empty one. */
+  const describedBy = (description: JxStyle[string]): { description?: string } =>
+    isString(description) && description !== "" ? { description } : {};
+
   const emit = (
     conditions: readonly string[],
     selector: string | null,
@@ -842,10 +865,7 @@ export function buildStyleRules(style: JxStyle, options: CssBuildOptions = {}):
       target,
       key: hashCss(text),
     };
-    if (isString(description) && description !== "") {
-      rule.description = description;
-    }
-    rules.push(rule);
+    rules.push({ ...rule, ...describedBy(description) });
   };
 
   /**
@@ -884,6 +904,7 @@ export function buildStyleRules(style: JxStyle, options: CssBuildOptions = {}):
       return;
     }
     const text = cssKeyframesText(conditions, name, blocks);
+    // The block's own `$description` documents the rule; a stop's is ignored, as a stop is no rule.
     rules.push({
       blocks,
       conditions: [...conditions],
@@ -892,6 +913,7 @@ export function buildStyleRules(style: JxStyle, options: CssBuildOptions = {}):
       selector: null,
       target: "unscoped",
       text,
+      ...describedBy(block["$description"]),
     });
   };
 

package/src/runtime.ts

@@ -5031,15 +5031,27 @@ export function isSignal(v: unknown): v is Ref<unknown> {
  * type. The default is the value the entry had before anyone set the attribute, which is what the
  * removal is asking to go back to.
  *
- * @param defaults The declared defaults by state key; a key absent from it has none.
+ * A COMPUTED entry is never written, by a change or by a removal: its value is produced, and
+ * attribute text replacing a `$prototype` or `$src` entry's function or record is not something a
+ * removal could give back. `declaredDefaults` records such an entry as present with the value
+ * `undefined`, which is what this reads.
+ *
+ * Exported for the compiler, which inlines the rule into generated modules and calls it for the
+ * prerender; `observed-attr-agreement.test.ts` there proves the copy agrees.
+ *
+ * @param defaults The declared defaults by state key; a key absent from it has none, and a key
+ *   present with `undefined` is computed.
  */
-function absorbAttribute(
+export function absorbAttribute(
   state: JxScope,
   name: string,
   value: string | null,
   defaults?: ReadonlyMap<string, JxScopeValue>,
 ): void {
   const camelKey = name.replaceAll(/-([a-z])/g, (_: string, c: string) => c.toUpperCase());
+  if (defaults?.has(camelKey) && defaults.get(camelKey) === undefined) {
+    return;
+  }
   const current = state[camelKey];
   if (isBoolean(current)) {
     // Presence IS the value for a boolean, so a removal is already spelled by the same rule.
@@ -5055,25 +5067,44 @@ function absorbAttribute(
 }
 
 /**
- * The declared default of every state entry that has one, by state key.
+ * The declared default of every state entry, by state key, read the way `buildScope` reads the
+ * entry's shape:
+ *
+ * - An object with `default` declares that value.
+ * - A computed entry (a marker of {@link COMPUTED_STATE_KEYS}, or a `${…}` template string) is
+ *   recorded as PRESENT with the value `undefined`: its value is produced, so it has no default and
+ *   an observed attribute never writes it ({@link absorbAttribute}).
+ * - A pure type definition (`{ "type": "number" }`), which `buildScope` leaves out of state, is
+ *   absent: it declares no default, and recording the schema object as one wrote that object into
+ *   state when its attribute was removed.
+ * - Anything else is its own default: the shorthand `{ "label": "none" }`, a plain object, an array.
+ *
+ * Exported for the compiler, which serializes the observed keys' defaults into generated modules;
+ * `observed-attr-agreement.test.ts` there proves the emitted map equals this function's output.
  *
  * @param def The element definition
  * @returns {Map<string, JxScopeValue>} Key → default
  */
-function declaredDefaults(def: JxElement): Map<string, JxScopeValue> {
+export function declaredDefaults(def: JxElement): Map<string, JxScopeValue> {
   const out = new Map<string, JxScopeValue>();
   for (const [key, entry] of Object.entries(def.state ?? {})) {
-    if (isNonNullObject(entry)) {
+    if (isString(entry) && isTemplateString(entry)) {
+      out.set(key, undefined);
+      continue;
+    }
+    if (isNonNullObject(entry) && !Array.isArray(entry)) {
       if ("default" in entry) {
         out.set(key, entry.default);
         continue;
       }
-      // A computed entry has no default: its value is produced, and a removal leaves it alone.
       if (COMPUTED_STATE_KEYS.some((marker) => marker in entry)) {
+        out.set(key, undefined);
+        continue;
+      }
+      if (hasSchemaKeywords(entry)) {
         continue;
       }
     }
-    // The shorthand `{ "label": "none" }` IS the default, the same way `buildScope` reads it.
     out.set(key, entry);
   }
   return out;
@@ -5113,11 +5144,14 @@ const _privatePropWarned = new Set<string>();
  * declares one. What the accessor DOES do is write the attribute, so the attribute is the evidence
  * that somebody set it, whether that was `$props` before connection or the author in the document.
  *
+ * Exported for the compiler, which inlines the rule into generated modules; a compiler test proves
+ * the copy agrees.
+ *
  * @param {HTMLElement} el - The instance being connected.
  * @param {string} key - A state key declared by the component definition.
  * @returns {boolean}
  */
-function instanceSupplies(el: HTMLElement, key: string): boolean {
+export function instanceSupplies(el: HTMLElement, key: string): boolean {
   if (Object.hasOwn(el, key)) {
     return true;
   }
@@ -5199,6 +5233,7 @@ export {
   camelToKebab,
   COLOR_SCHEME_ATTR,
   COLOR_SCHEME_STORAGE_KEY,
+  commentedRuleText,
   cssPropertyName,
   cssRuleText,
   hashCss,
@@ -5746,6 +5781,11 @@ export async function defineElement(source: string | JxDocument, baseUrl?: strin
         return;
       }
       if (this._jxInitialized) {
+        /* Put back in a document (moved to another parent, or removed and inserted). Everything
+           below happens to an instance once, `onMount` included (§16.4): a sidecar wires up what it
+           was handed at the first insertion and is not handed it twice, which is what lets a
+           slotted element, moved by its parent's slot distribution straight after it rendered,
+           mount once. `onUnmount` still runs on every removal. */
         return;
       }
       this._jxInitialized = true;
@@ -5777,9 +5817,10 @@ export async function defineElement(source: string | JxDocument, baseUrl?: strin
          for an attribute set before connection too — but on an instance with no state yet, so it
          had nothing to write into, and `<jx-icon name="plus">` rendered with the default. Before
          the `$props` merges below, so a property a parent set still wins (spec §16.2). */
+      const connectDefaults = declaredDefaults(def);
       for (const attr of observedAttrs) {
         if (this.hasAttribute(attr)) {
-          absorbAttribute(state, attr, this.getAttribute(attr));
+          absorbAttribute(state, attr, this.getAttribute(attr), connectDefaults);
           // The raw string, not the coerced value: coercion is a function of it, so two equal
           // Strings are one input.
           supplied[attr] = this.getAttribute(attr);
@@ -5997,7 +6038,11 @@ export async function defineElement(source: string | JxDocument, baseUrl?: strin
          the ones a prop can write: a computed entry is what threw, and reading it here would
          throw again. Writes are coalesced into one microtask, because a parent sets its props one
          at a time. The same error is reported once, not once per attempt. */
-      const inputs = [...declaredDefaults(def).keys()].filter((key) => !isPrivateStateKey(key));
+      const inputs = Object.keys(def.state ?? {}).filter(
+        (key) =>
+          !isPrivateStateKey(key) &&
+          !(connectDefaults.has(key) && connectDefaults.get(key) === undefined),
+      );
       let lastMessage = failure.message;
       let queued = false;
       const watch = effect(
@@ -6089,12 +6134,14 @@ export async function defineElement(source: string | JxDocument, baseUrl?: strin
 function writeInstanceProp(el: HTMLElement, key: string, resolved: JxScopeValue): void {
   const value = isString(resolved) ? canvasAssetValue(el.tagName, key, resolved) : resolved;
   elementProperties(el)[key] = value;
-  /* A declared prop that shares its name with an `HTMLElement` property (`title`, `lang`) gets
-     no forwarding accessor (§16.2), so the write above lands on the element and never reaches
-     the instance's state. Connection reads it once; a binding that changes AFTER connection
-     (a row whose data arrives later) was lost, and the instance went on drawing the value it
-     connected with. The binding is the parent's `$props`, addressed to the definition's prop,
-     so it writes that prop's state. */
+  /* A prop that shares its name with an `HTMLElement` property (`title`, `lang`) is forwarded
+     like any other once the instance has connected (§16.2): its accessor calls the platform's
+     setter, then writes state, so the write above already reaches state there. The write below
+     covers the instance that holds the name in its state with NO accessor for it, which is a
+     name its live definition does not declare and it was not given at connection (an inherited
+     project formula, §13.4). There the write above lands on the platform's property alone, and
+     the instance would go on drawing the value it connected with. The binding is the parent's
+     `$props`, addressed to the instance's state, so it writes that state. */
   const instanceState = instanceStateOf(el);
   if (instanceState && key in HTMLElement.prototype && Object.hasOwn(toRaw(instanceState), key)) {
     instanceState[key] = value;