npm - @iyulab/components - Versions diffs - 1.43.0 → 1.44.0 - Mend

@iyulab/components 1.43.0 → 1.44.0

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.

Files changed (5) hide show

package/CHANGELOG.md +36 -0
package/dist/utilities/Theme.d.ts +18 -0
package/dist/utilities/Theme.js +25 -2
package/package.json +1 -1
package/skills/iyulab-components/references/utilities/theme.md +6 -0

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,41 @@
 # Changelog
+## [1.44.0] - 2026-09-22
+### Fixed
+- 🔴 **`Theme.init()` no longer overrides styles the document already has.** The built-in token
+  sheets were appended to the end of `<head>`. A consumer stylesheet declaring the same `--u-*`
+  tokens on `:root` is placed by the bundler while the document parses, so the runtime append
+  always came *after* it — and at equal specificity the later rule wins. The result was that the
+  built-in defaults silently overrode whatever the consumer had set, with no error and no
+  warning. Where the two sheets agreed on some values and differed on others, it read as
+  *partially applied* rather than as ignored, which is harder to notice than an outright failure.
+- **The sheets are a defaults layer, so they now go in front of the document's other styles.**
+  They are inserted ahead of the first `<style>`/`<link rel=stylesheet>` — not pushed past
+  `<meta>` and friends — and their order relative to each other is preserved rather than
+  reversed. If a document has no stylesheets at all, they are appended as before; anything added
+  later still comes after them, which is the point.
+⚠ **If you relied on the old behavior** — that is, on the built-in values winning over a sheet
+you loaded yourself — you no longer need to; load order now works the way `:root` at equal
+specificity implies. Nothing changes for consumers who never override these tokens.
+### Documentation
+- **`docs/theming.md` no longer tells you to sequence your override after `Theme.init()`.** That
+  instruction existed because of the behavior above, and it outlived it by exactly one release
+  otherwise. The Custom Themes section now says a plain static `import` is enough, states what
+  changed for anyone still on an older version, and keeps the one rule that *does* still decide
+  the outcome: specificity. `How Theme Switching Works` says where the sheets are inserted, not
+  just that they are.
+- The same note is in the skill reference for `Theme`, which is where an assistant reads it.
+### Notes
+- The regression measures computed values in a real browser. Asserting where a node was inserted
+  would describe placement, not the cascade, and the contract here is the cascade.
 ## [1.43.0] - 2026-09-22
 ### Added

package/dist/utilities/Theme.d.ts CHANGED Viewed

@@ -102,6 +102,24 @@ export declare class Theme {
     static accent(seed: string | null): void;
     /** 현재 시드를 현재 테마의 바탕에 맞춰 다시 계산해 적용한다. */
     private static applyAccent;
+    /**
+     * 내장 시트를 넣을 자리 — **다른 모든 스타일 «앞», 우리가 이미 넣은 것 «뒤»**.
+     *
+     * 🔴**왜 맨 앞인가.** 이 시트들은 이름 그대로 «기본값» 층이다. 소비자(또는 하우스 프리셋)가
+     * 같은 `--u-*` 토큰을 `:root` 로 덮으면 **특이도가 대등**하므로 승부는 문서 순서가 가른다 —
+     * 그런데 이 시트는 **런타임에** 붙고 소비자 시트는 번들러가 **파싱 시점에** 올리므로,
+     * 종전(`appendChild`)에는 ***언제나 기본값이 이겼다.*** 소비자 입장에서는 덮어쓰기가
+     * **오류도 경고도 없이 무효**가 되고, 값이 일부만 다르면 「적용된 것처럼」 보이기까지 한다.
+     *
+     * ⚠**`<meta charset>` 류를 넘어 맨 앞으로 밀지 않는다** — 첫 «스타일» 앞에만 선다.
+     * 스타일이 하나도 없으면 붙일 곳이 없으므로 그대로 끝에 넣는다(뒤에 오는 것이 이긴다는
+     * 성질은 그대로다).
+     *
+     * ⚠**우리 시트끼리의 순서는 유지한다** — 매번 `firstChild` 앞에 넣으면 번들 순서가 뒤집힌다.
+     * 실제로는 `light`/`dark` 의 상대 순서가 결과를 바꾸지 않지만(`dark.css` 는
+     * `:root[theme="dark"]` 로 **특이도가 이긴다**), 순서가 뒤집히는 자료구조를 남기지 않는다.
+     */
+    private static builtInAnchor;
     /** 디버그 모드시 로그 출력 함수 (인스턴스 스코프) */
     private static log;
 }

package/dist/utilities/Theme.js CHANGED Viewed

@@ -73,8 +73,8 @@ var Theme = class {
 					this.log("style already present, skipping", name);
 					continue;
 				}
-				document.head.appendChild(style);
-				this.log("appended style to head", name);
+				document.head.insertBefore(style, this.builtInAnchor());
+				this.log("inserted style at the base layer", name);
 			}
 		} else {
 			document.head.querySelectorAll("style[data-name]").forEach((el) => el.remove());
@@ -218,6 +218,29 @@ var Theme = class {
 		for (const [name, value] of Object.entries(accentCustomProperties(ramp))) root.style.setProperty(name, value);
 		this.log("accent applied", this.accentSeed, "→", ramp);
 	}
+	/**
+	* 내장 시트를 넣을 자리 — **다른 모든 스타일 «앞», 우리가 이미 넣은 것 «뒤»**.
+	*
+	* 🔴**왜 맨 앞인가.** 이 시트들은 이름 그대로 «기본값» 층이다. 소비자(또는 하우스 프리셋)가
+	* 같은 `--u-*` 토큰을 `:root` 로 덮으면 **특이도가 대등**하므로 승부는 문서 순서가 가른다 —
+	* 그런데 이 시트는 **런타임에** 붙고 소비자 시트는 번들러가 **파싱 시점에** 올리므로,
+	* 종전(`appendChild`)에는 ***언제나 기본값이 이겼다.*** 소비자 입장에서는 덮어쓰기가
+	* **오류도 경고도 없이 무효**가 되고, 값이 일부만 다르면 「적용된 것처럼」 보이기까지 한다.
+	*
+	* ⚠**`<meta charset>` 류를 넘어 맨 앞으로 밀지 않는다** — 첫 «스타일» 앞에만 선다.
+	* 스타일이 하나도 없으면 붙일 곳이 없으므로 그대로 끝에 넣는다(뒤에 오는 것이 이긴다는
+	* 성질은 그대로다).
+	*
+	* ⚠**우리 시트끼리의 순서는 유지한다** — 매번 `firstChild` 앞에 넣으면 번들 순서가 뒤집힌다.
+	* 실제로는 `light`/`dark` 의 상대 순서가 결과를 바꾸지 않지만(`dark.css` 는
+	* `:root[theme="dark"]` 로 **특이도가 이긴다**), 순서가 뒤집히는 자료구조를 남기지 않는다.
+	*/
+	static builtInAnchor() {
+		const ours = document.head.querySelectorAll("style[data-name]");
+		const last = ours[ours.length - 1];
+		if (last) return last.nextSibling;
+		return document.head.querySelectorAll("style, link[rel~=\"stylesheet\"]")[0] ?? null;
+	}
 	/** 디버그 모드시 로그 출력 함수 (인스턴스 스코프) */
 	static log(...args) {
 		if (this._isDebugMode) console.log("[theme]", ...args);

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/components",
   "description": "web-components library based on lit-element made by iyulab",
-  "version": "1.43.0",
+  "version": "1.44.0",
   "keywords": [
     "iyulab",
     "components",

package/skills/iyulab-components/references/utilities/theme.md CHANGED Viewed

@@ -51,6 +51,12 @@ changes**, because those targets are relative to the page background.
 > from `--u-primary-color-strong`, so they stay on the default ramp and the brand looks
 > half-applied. (The sheet derives no step from `--u-primary-color` — measured: 0 references.)
+> **Load that block however you like — a plain static `import` is enough.** Since 1.44.0 the
+> built-in sheets are inserted *ahead of* the document's other styles, so your override wins at
+> equal specificity whenever it arrives. Before 1.44.0 they were appended last and a static
+> import silently did nothing; on those versions, load your sheet after `await Theme.init(...)`.
+> Specificity still decides: a `:where(:root)` wrapper drops to 0 and loses regardless of order.
 ## API
 | Member | Type | Description |