ilha 0.1.0 → 0.2.1

package/README.md

@@ -25,7 +25,7 @@ const Counter = ilha
   .render(
     ({ state }) => html`
       <div>
-        <p>Count: ${state.count}</p>
+        <p>Count: ${state.count()}</p>
         <button>Increment</button>
       </div>
     `,
@@ -50,11 +50,21 @@ State is managed with signals — when a signal changes, only the affected islan
 
 ## Builder API
 
-Every island starts from the `ilha` builder object (or `ilha.input()` if you need typed props).
+Every island starts from the `ilha` builder object (or `ilha.input<T>()` / `ilha.input(schema)` if you need typed props).
 
-### `ilha.input(schema)`
+### `ilha.input<T>()` / `ilha.input(schema)`
 
-Declares the island's external input type using any [Standard Schema](https://standardschema.dev/) compatible validator (e.g. Zod, Valibot, ArkType).
+Declares the island's external input type. Two forms:
+
+**1. Type-only (no runtime validation):**
+
+```ts
+const MyIsland = ilha
+  .input<{ name: string }>()
+  .render(({ input }) => `<p>Hello, ${input.name}!</p>`);
+```
+
+**2. With a [Standard Schema](https://standardschema.dev/) validator** (Zod, Valibot, ArkType, etc.) — runs validation at render time and uses the schema's inferred output type:
 
 ```ts
 import { z } from "zod";
@@ -129,7 +139,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 +232,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.
@@ -314,13 +380,13 @@ Async method that renders the island wrapped in a `data-ilha` hydration containe
 const html = await MyIsland.hydratable(
   { name: "Ilha" },
   {
-    name: "my-island", // registry key for client-side activation
+    name: "MyIsland", // registry key for client-side activation
     as: "div", // wrapper tag (default: "div")
     snapshot: true, // embed state + derived as data-ilha-state
     skipOnMount: false, // skip onMount on hydration (default: true when snapshot)
   },
 );
-// → '<div data-ilha="my-island" data-ilha-props="…" data-ilha-state="…">…</div>'
+// → '<div data-ilha="MyIsland" data-ilha-props="…" data-ilha-state="…">…</div>'
 ```
 
 **`snapshot` option:**
@@ -430,18 +496,39 @@ raw("<strong>bold</strong>"); // → passes through unescaped
 
 ---
 
-### `type(coerce?)`
+### `css\`\`` tagged template
 
-Creates a lightweight Standard Schema validator for use with `.input()` — useful when you don't want a full validation library.
+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 { type } from "ilha";
+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>`);
+```
 
-const MyIsland = ilha
-  .input(type((v: unknown) => v as { count: number }))
-  .render(({ input }) => `<p>${input.count}</p>`);
+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.
+
 ---
 
 ## SSR + Hydration
@@ -464,7 +551,7 @@ return `<!doctype html><html><body>${html}</body></html>`;
 import { mount } from "ilha";
 import { MyIsland } from "./islands";
 
-mount({ "my-island": MyIsland });
+mount({ MyIsland });
 ```
 
 The client reads `data-ilha-state` to restore signal values from the snapshot, skipping a needless re-render and calling `.onMount()` only if `skipOnMount` is not set.
@@ -474,7 +561,7 @@ The client reads `data-ilha-state` to restore signal values from the snapshot, s
 ```
 server                                    client
 ──────────────────────────────────────    ──────────────────────────────────────────
-.hydratable({ count: 42 }, {              mount({ "my-island": MyIsland })
+.hydratable({ count: 42 }, {              mount({ MyIsland })
   name: "my-island",                        → reads data-ilha-state
   snapshot: true                            → restores signals from snapshot
 })                                          → skips onMount (skipOnMount: true)

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,10 +177,12 @@ 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>;
   constructor(cfg: BuilderConfig<TInput, TStateMap, TDerivedMap, TSlots>);
+  input<T extends Record<string, unknown>>(): IlhaBuilder<T, Record<string, never>, Record<string, never>, Record<string, never>>;
   input<S extends StandardSchemaV1>(schema: S): IlhaBuilder<StandardSchemaV1.InferOutput<S> & Record<string, unknown>, Record<string, never>, Record<string, never>, Record<string, never>>;
   state<V = undefined, K extends string = string>(key: K, init?: StateInit<TInput, V> | undefined): IlhaBuilder<TInput, MergeState<TStateMap, K, V>, TDerivedMap, TSlots>;
   derived<K extends string, V>(key: K, fn: DerivedFn<TInput, TStateMap, V>): IlhaBuilder<TInput, TStateMap, TDerivedMap & Record<K, V>, TSlots>;
@@ -191,6 +194,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;
@@ -203,11 +207,11 @@ declare const ilha: IlhaBuilder<Record<string, unknown>, Record<string, never>,
   from: typeof ilhaFrom;
   context: typeof ilhaContext;
 };
-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 };

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("");
@@ -302,7 +315,7 @@ var IlhaBuilder = class IlhaBuilder {
 	}
 	input(schema) {
 		return new IlhaBuilder({
-			schema,
+			schema: schema ?? null,
 			states: [],
 			deriveds: [],
 			ons: [],
@@ -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,
@@ -810,19 +843,11 @@ const ilha = Object.assign(rootBuilder, {
 	from: ilhaFrom,
 	context: ilhaContext
 });
-function type(coerce) {
-	return { "~standard": {
-		version: 1,
-		vendor: "ilha",
-		validate(value) {
-			return { value: coerce ? coerce(value) : value };
-		}
-	} };
-}
 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ilha",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "A tiny, framework-free island architecture library",
   "license": "MIT",
   "author": "Ryuz <ryuzer@proton.me>",
@@ -26,7 +26,6 @@
     "alien-signals": "3.1.2"
   },
   "devDependencies": {
-    "docsome": "^0.0.6",
     "zod": "^4.3.6"
   }
 }