ilha 0.1.0 → 0.2.0

package/README.md

@@ -129,7 +129,6 @@ ilha
   .on("@click", ({ state }) => state.count(state.count() + 1)) // host click
   .on("button.inc@click", ({ state }) => state.count(state.count() + 1)) // child click
   .on("input@input:debounce", ({ state, event }) => {
-    // with modifier
     state.query((event.target as HTMLInputElement).value);
   })
   .render(({ state }) => html`<div><button class="inc">+</button></div>`);
@@ -223,6 +222,63 @@ You can also bind to an external signal created with `context()`:
 
 ---
 
+### `.css(strings, ...values)`
+
+Attaches scoped styles to the island. Accepts a tagged template literal or a plain string. The CSS is automatically wrapped in a `@scope` rule bounded to the island host, so styles are contained within the island and do not leak into child islands.
+
+```ts
+import { css } from "ilha";
+
+const Card = ilha.state("active", false).css`
+    .title { font-weight: 700; }
+    button { background: teal; color: white; }
+  `.render(
+  ({ state }) => html`
+    <div>
+      <p class="title">Hello</p>
+      <button>Toggle</button>
+    </div>
+  `,
+);
+```
+
+Interpolations are supported:
+
+```ts
+const accent = "teal";
+
+ilha.css`button { background: ${accent}; }`.render(() => `<button>Go</button>`);
+```
+
+You can also pass a plain string (e.g. from an external `.css` file):
+
+```ts
+import styles from "./card.css?raw";
+
+ilha.css(styles).render(() => `<div class="card">…</div>`);
+```
+
+**SSR output** — a `<style data-ilha-css>` tag is prepended as the first child of the island's rendered HTML:
+
+```html
+<style data-ilha-css>
+  @scope (:scope) to ([data-ilha]) {
+    .title {
+      font-weight: 700;
+    }
+  }
+</style>
+<div>…</div>
+```
+
+**Client mount** — the style element is injected once as the first child of the host and preserved across re-renders (morph never replaces it). During hydration, the SSR-emitted `<style>` node is reused and not duplicated.
+
+**`.hydratable()` integration** — the style tag is included inside the `data-ilha` wrapper regardless of the `snapshot` option.
+
+> **Note:** Calling `.css()` more than once on the same builder chain is not supported. In dev mode a warning is logged and only the last stylesheet is used. Compose all your styles into a single `.css()` call.
+
+---
+
 ### `.slot(name, island)`
 
 Embeds a child island as a named slot. The child island is mounted and managed independently. During SSR the slot renders the child's HTML inline; during client mount the child island is activated for interactivity.
@@ -430,6 +486,41 @@ raw("<strong>bold</strong>"); // → passes through unescaped
 
 ---
 
+### `css\`\`` tagged template
+
+A passthrough tagged template for CSS strings. Functionally identical to a plain template literal — no runtime transformation occurs. Its purpose is purely to enable editor tooling (LSP syntax highlighting, Prettier formatting) to recognise the contents as CSS.
+
+```ts
+import { css } from "ilha";
+
+const styles = css`
+  button {
+    background: teal;
+    color: white;
+  }
+  .label {
+    font-weight: 700;
+  }
+`;
+
+ilha.css(styles).render(() => `<button class="label">Go</button>`);
+```
+
+Interpolations work as normal string concatenation:
+
+```ts
+const accent = "coral";
+const styles = css`
+  button {
+    background: ${accent};
+  }
+`;
+```
+
+> **Note:** `css` (the named export) is the plain passthrough tag for tooling. `ilha.css` is the builder chain method that attaches styles to an island. They are intentionally separate.
+
+---
+
 ### `type(coerce?)`
 
 Creates a lightweight Standard Schema validator for use with `.input()` — useful when you don't want a full validation library.

package/dist/index.d.ts

@@ -48,6 +48,7 @@ interface MarkedSignalAccessor<T> {
   [SIGNAL_ACCESSOR]: true;
 }
 declare function ilhaRaw(value: string): RawHtml;
+declare function ilhaCss(strings: TemplateStringsArray | string, ...values: (string | number)[]): string;
 declare function ilhaHtml(strings: TemplateStringsArray, ...values: unknown[]): RawHtml;
 type ContextSignal<T> = {
   (): T;
@@ -176,6 +177,7 @@ interface BuilderConfig<TInput, TStateMap extends Record<string, unknown>, TDeri
   slots: Record<string, AnyIsland>;
   transition: TransitionOptions | null;
   binds: BindEntry<TStateMap>[];
+  css: string | null;
 }
 declare class IlhaBuilder<TInput extends Record<string, unknown>, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<string, never>, TSlots extends SlotMap = Record<string, never>> {
   readonly _cfg: BuilderConfig<TInput, TStateMap, TDerivedMap, TSlots>;
@@ -191,6 +193,7 @@ declare class IlhaBuilder<TInput extends Record<string, unknown>, TStateMap exte
   onMount(fn: (ctx: OnMountContext<TInput, TStateMap, TDerivedMap>) => (() => void) | void): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots>;
   slot<K extends string, I extends AnyIsland>(name: K, island: I): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots & Record<K, I>>;
   transition(opts: TransitionOptions): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots>;
+  css(strings: TemplateStringsArray | string, ...values: (string | number)[]): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots>;
   render(fn: (ctx: RenderContext<TInput, TStateMap, TDerivedMap, TSlots>) => string | RawHtml): Island<TInput, TStateMap>;
 }
 declare function ilhaFrom<TInput, TStateMap extends Record<string, unknown>>(selector: string | Element, island: Island<TInput, TStateMap>, props?: Partial<TInput>): (() => void) | null;
@@ -206,8 +209,9 @@ declare const ilha: IlhaBuilder<Record<string, unknown>, Record<string, never>,
 declare function type<TInput, TOutput = TInput>(coerce?: (input: TInput) => TOutput): StandardSchemaV1<TInput, TOutput>;
 declare const html: typeof ilhaHtml;
 declare const raw: typeof ilhaRaw;
+declare const css: typeof ilhaCss;
 declare const mount: typeof mountAll;
 declare const from: typeof ilhaFrom;
 declare const context: typeof ilhaContext;
 //#endregion
-export { DerivedValue, HandlerContext, HandlerContextFor, HydratableOptions, Island, IslandDerived, IslandState, MountOptions, MountResult, OnMountContext, RawHtml, SignalAccessor, SlotAccessor, context, ilha as default, from, html, mount, raw, type };
+export { DerivedValue, HandlerContext, HandlerContextFor, HydratableOptions, Island, IslandDerived, IslandState, MountOptions, MountResult, OnMountContext, RawHtml, SignalAccessor, SlotAccessor, context, css, ilha as default, from, html, mount, raw, type };

package/dist/index.js

@@ -82,6 +82,10 @@ const SIGNAL_ACCESSOR = Symbol("ilha.signalAccessor");
 const SLOT_ATTR = "data-ilha-slot";
 const PROPS_ATTR = "data-ilha-props";
 const STATE_ATTR = "data-ilha-state";
+const CSS_ATTR = "data-ilha-css";
+function buildScopedStyle(css) {
+	return `<style ${CSS_ATTR}>@scope (:scope) to ([data-ilha]){${css}}</style>`;
+}
 function makeSlotAccessor(render) {
 	const fn = (props) => ({
 		[RAW]: true,
@@ -107,6 +111,15 @@ function ilhaRaw(value) {
 		value
 	};
 }
+function ilhaCss(strings, ...values) {
+	if (typeof strings === "string") return strings;
+	let result = "";
+	for (let i = 0; i < strings.length; i++) {
+		result += strings[i];
+		if (i < values.length) result += String(values[i]);
+	}
+	return result;
+}
 function interpolateValue(v) {
 	if (v == null) return "";
 	if (Array.isArray(v)) return v.map(interpolateValue).join("");
@@ -310,7 +323,8 @@ var IlhaBuilder = class IlhaBuilder {
 			onMounts: [],
 			slots: {},
 			transition: null,
-			binds: []
+			binds: [],
+			css: null
 		});
 	}
 	state(key, init) {
@@ -381,8 +395,26 @@ var IlhaBuilder = class IlhaBuilder {
 			transition: opts
 		});
 	}
+	css(strings, ...values) {
+		let source;
+		if (typeof strings === "string") source = strings;
+		else {
+			let result = "";
+			for (let i = 0; i < strings.length; i++) {
+				result += strings[i];
+				if (i < values.length) result += String(values[i]);
+			}
+			source = result;
+		}
+		if (__DEV__ && this._cfg.css !== null) warn("css(): called more than once on the same builder chain. The previous stylesheet has been discarded. Compose styles into a single .css() call instead.");
+		return new IlhaBuilder({
+			...this._cfg,
+			css: source
+		});
+	}
 	render(fn) {
-		const { schema, states, deriveds, ons, effects, onMounts, slots: slotDefs, transition, binds } = this._cfg;
+		const { schema, states, deriveds, ons, effects, onMounts, slots: slotDefs, transition, binds, css: cssSource } = this._cfg;
+		const stylePrefix = cssSource != null ? buildScopedStyle(cssSource) : "";
 		function resolveInput(props) {
 			const value = props ?? {};
 			if (!schema) return value;
@@ -460,7 +492,7 @@ var IlhaBuilder = class IlhaBuilder {
 					value: r.result,
 					error: void 0
 				};
-				return unwrapHtml(fn({
+				return stylePrefix + unwrapHtml(fn({
 					state,
 					derived,
 					input,
@@ -490,7 +522,7 @@ var IlhaBuilder = class IlhaBuilder {
 			})).then((resolved) => {
 				const derived = {};
 				for (const r of resolved) derived[r.key] = r.envelope;
-				return unwrapHtml(fn({
+				return stylePrefix + unwrapHtml(fn({
 					state,
 					derived,
 					input,
@@ -613,7 +645,7 @@ Element: ${host.outerHTML.slice(0, 120)}`);
 				listeners.length = 0;
 			}
 			const slots = makeSlotsProxy(false, host);
-			if (!(hydrated && host.childNodes.length > 0)) host.innerHTML = unwrapHtml(fn({
+			if (!(hydrated && host.childNodes.length > 0)) host.innerHTML = stylePrefix + unwrapHtml(fn({
 				state,
 				derived,
 				input,
@@ -642,7 +674,7 @@ Element: ${host.outerHTML.slice(0, 120)}`);
 			}
 			let initialized = false;
 			const stopRender = effect(() => {
-				const html = unwrapHtml(fn({
+				const html = stylePrefix + unwrapHtml(fn({
 					state,
 					derived,
 					input,
@@ -801,7 +833,8 @@ const rootBuilder = new IlhaBuilder({
 	onMounts: [],
 	slots: {},
 	transition: null,
-	binds: []
+	binds: [],
+	css: null
 });
 const ilha = Object.assign(rootBuilder, {
 	html: ilhaHtml,
@@ -821,8 +854,9 @@ function type(coerce) {
 }
 const html = ilhaHtml;
 const raw = ilhaRaw;
+const css = ilhaCss;
 const mount = mountAll;
 const from = ilhaFrom;
 const context = ilhaContext;
 //#endregion
-export { context, ilha as default, from, html, mount, raw, type };
+export { context, css, ilha as default, from, html, mount, raw, type };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ilha",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A tiny, framework-free island architecture library",
   "license": "MIT",
   "author": "Ryuz <ryuzer@proton.me>",