kaplay-ui 1.0.0-alpha.13 → 1.0.0-alpha.15

package/README.md

@@ -17,6 +17,19 @@ For now it helps you build Game Objects like text buttons and labels — without
 
 ---
 
+## ✨ _What this plugin currently provides_
+
+When installed, this plugin extends the KAPLAY context (`k`) with:
+
+- `k.addTextButton()` – interactive buttons with centered text
+- `k.addLabel()` – lightweight, non-interactive text labels
+
+Each helper returns a regular KAPLAY game object enhanced with
+**convenience methods** for changing size, position, colors, text, and more
+after creation.
+
+---
+
 ## 📦 Installation
 
 ### Prerelease (new v1 work)
@@ -29,11 +42,9 @@ This gives you the latest `1.0.0‑alpha.*` builds.
 
 ---
 
-## 🚀 Usage (_1.0.0-alpha.\*_)
+## 🚀 Quick start (_1.0.0-alpha.\*_)
 
-**Kaplay UI** exports a plugin for adding UI Game Objects.
-
-The `kaplayUI` plugin is exported from the package root:
+The **Kaplay-UI** plugin is exported as `kaplayUI` from the package root:
 
 ```ts
 import kaplay from "kaplay";
@@ -47,130 +58,144 @@ const k = kaplay({
 You now have access to the UI helpers via your `k` instance:
 
 ```ts
-const btn = k.addTextButton("Play");
-const label = k.addLabel("Score: 0");
+const btn = k.addTextButton("Start");
+btn.onClick(() => {
+  k.go("game");
+});
+
+const lbl = k.addLabel("Score: 0");
+lbl.setLabelText("Score: 1");
 ```
 
 ---
 
 ## 🧩 Game Objects (_**1.0.0‑alpha.\***_)
 
-### 🔤 **Text Button** (`addTextButton()`)
-
-Creates a button-like GameObj with centered text and some convenient defaults.
+### 🔤 Text Button — `addTextButton()`
 
-#### _**Signature**_
+Creates a clickable button with centered text and default visuals.
 
 ```ts
-addTextButton(
-  txt: string,
-  opts?: object
-): GameObj
+const btn = k.addTextButton("Start", {
+  width: 200,
+  height: 80,
+});
 ```
 
-#### _**Default `opts` parameter values**_
+Buttons support runtime updates such as:
 
-| Parameter | Default |
-| --------- | :------ |
-| `width`   | `200`   |
-| `height`  | `100`   |
-| `radius`  | `10`    |
-| `posX`    | `0`     |
-| `posY`    | `0`     |
-| `outline` | `3`     |
-| `txtSize` | `22`    |
+```ts
+btn.setSize(300, 100);
+btn.setButtonColor([255, 120, 120]);
+btn.setButtonText("Go!");
+btn.setButtonTextSize(24);
+```
 
-#### _**Default styling**_
+Perfect for menus, dialogs, and in‑game actions.
+
+---
 
-| Comps                  | Values          |
-| ---------------------- | :-------------- |
-| `button anchor`        | `"topleft"`     |
-| `button color`         | `200, 200, 200` |
-| `button outline color` | `92, 91, 91`    |
-| `text anchor`          | `"center"`      |
-| `text color`           | `0, 0, 0`       |
+### 🏷️ Label — `addLabel()`
 
-#### _**Examples**_
+Creates a lightweight background + text container for HUD elements or titles.
 
 ```ts
-// Basic button
-const btn1 = k.addTextButton("Play!");
+const label = k.addLabel("Score: 0");
+```
 
-// Custom button
-const btn2 = k.addTextButton("Play!", { posX: 300, posY: 200 });
+Update it dynamically:
 
-// Add interactivity
-btn2.onClick(() => {
-  console.log("Button clicked!");
-});
+```ts
+label.setLabelText("Score: 10");
+label.setLabelTextColor([255, 255, 0]);
+label.setOpacity(0.9);
 ```
 
+Ideal for HUDs, counters, status text, and overlays.
+
 ---
 
-### 🏷️ **Label** (`addLabel()`)
+## 🎨 Customization
 
-A lightweight text-based UI element — ideal for HUD counters, tooltips, status text, or titles.
+kaplay-ui is designed to be **customized imperatively**, without hiding
+or abstracting away KAPLAY’s core APIs.
 
-#### _**Signature**_
+### ✅ Option-based customization (at creation)
+
+Both helpers accept an optional `opts` object for common configuration:
 
 ```ts
-addLabel(
-    txt: string,
-    opts?: object
-)
+const btn = k.addTextButton("Options", {
+  width: 250,
+  height: 70,
+  posX: 100,
+  posY: 200,
+  radius: 8,
+});
 ```
 
-#### _**Default `opts` values**_
+---
 
-| Parameter | Default |
-| --------- | ------- |
-| `width`   | `160`   |
-| `height`  | `96`    |
-| `txtSize` | `22`    |
+### ✅ Runtime customization (after creation)
 
-#### _**Default styling**_
+Each UI element exposes helper methods for updating its appearance and layout:
 
-| Comps           | Values          |
-| --------------- | :-------------- |
-| `label pos`     | `0, 0`          |
-| `label color`   | `0, 0,0 `       |
-| `label opacity` | `0.7`           |
-| `label anchor`  | `"topleft"`     |
-| `text color`    | `255, 255, 255` |
-| `text anchor`   | `"center"`      |
+```ts
+btn.setPosition(150, 220);
+btn.setButtonColor([80, 160, 255]);
+btn.setButtonTextColor([255, 255, 255]);
+```
 
-#### _**Examples**_
+This makes it easy to animate, react to state changes, or reuse UI elements.
 
-```ts
-// Basic label
-const lbl2 = k.addLabel("Score: 0");
+---
 
-// Custom label
-const lbl3 = k.addLabel("Start", { width: 100, height: 50 });
+### ✅ Full KAPLAY access
 
-// Update label text example
-let score = 0;
-const scoreLabel = k.addLabel(`Score: ${score}`);
+UI elements are **regular KAPLAY game objects**, so you can still use all
+standard KAPLAY features:
 
-k.wait(2, () => {
-  score++;
-  scoreLabel.children[0].text = `Score: ${score}`;
-});
+```ts
+btn.use(k.opacity(0.8));
+btn.onHover(() => btn.setScale(1.1));
+label.use(k.rotate(5));
 ```
 
-#### _**Common use cases**_
+kaplay-ui never locks you into a restricted UI model.
+
+---
+
+## 🧠 Design philosophy
+
+kaplay-ui is intentionally simple:
+
+- ✅ No retained UI trees
+- ✅ No layout engine
+- ✅ No reactive framework
+- ✅ Just KAPLAY game objects + helpers
+
+You stay in control of how and when UI updates happen.
 
-- HUD overlays
-- Score counters
-- Time and health displays
-- UI section headings
-- Tooltips and indicators
+---
+
+## 📚 Documentation
+
+- Full API documentation is available via **JSDocs**
+- All helpers are strongly typed and editor-friendly
+- Hover over methods in your editor to explore options
 
 ---
 
 ## 🛣️ Roadmap
 
-_See evolving roadmap at: https://github.com/jbakchr/kaplay-ui/blob/v1/ROADMAP.md_
+Future components may include:
+
+- Toggles
+- Sliders
+- Panels / containers
+
+See the roadmap here:  
+👉 <https://github.com/jbakchr/kaplay-ui/blob/v1/ROADMAP.md>
 
 ---
 

package/dist/uiplugin.d.ts

@@ -0,0 +1 @@
+export { }

package/dist/uiplugin.js

@@ -1,62 +1,48 @@
-//#region src/components/button/index.ts
+//#region src/helpers/color-utils.ts
 function e(e, t, n) {
-	let { width: r, height: i, radius: a, posX: o, posY: s, outline: c } = {
-		width: 150,
-		height: 60,
-		radius: 10,
-		posX: 0,
-		posY: 0,
-		outline: 3,
-		...t
-	};
-	return e.make([
-		e.rect(r, i, { radius: a }),
-		e.pos(o, s),
-		e.color(200, 200, 200),
-		e.outline(c, e.rgb(92, 91, 91)),
-		e.anchor(n),
-		e.area()
-	]);
+	if (Array.isArray(n)) {
+		t.use(e.color([
+			n[0],
+			n[1],
+			n[2]
+		]));
+		return;
+	}
+	if (typeof n == "string") {
+		t.use(e.color(n));
+		return;
+	}
+	if (typeof n == "object" && "r" in n) {
+		t.use(e.color(e.rgb(n.r, n.g, n.b)));
+		return;
+	}
+	t.use(e.color(n));
 }
-//#endregion
-//#region src/components/label/index.ts
-function t(e, t) {
-	let { width: n, height: r } = {
-		width: 160,
-		height: 96,
-		...t
-	};
-	return e.make([
-		e.rect(n, r),
-		e.pos(0, 0),
-		e.color(0, 0, 0),
-		e.opacity(.7),
-		e.anchor("topleft")
-	]);
+function t(e, t, n, r) {
+	if (typeof r == "string") {
+		t.use(e.outline(n, e.rgb(r)));
+		return;
+	}
+	if (Array.isArray(r)) {
+		t.use(e.outline(n, e.rgb(r[0], r[1], r[2])));
+		return;
+	}
 }
 //#endregion
-//#region src/components/text/index.ts
-function n(e, t, n, r, i, a) {
-	let { txtSize: o } = {
-		txtSize: 22,
-		...n
-	};
-	return e.make([
-		e.text(t, { size: o }),
-		e.color(0, 0, 0),
-		e.pos(r, i),
-		e.anchor(a)
-	]);
+//#region src/helpers/layout-utils.ts
+var n = new Set(["anchor", "rect"]);
+function r(e) {
+	return n.has(e);
 }
 //#endregion
 //#region src/helpers/pos-utils.ts
-function r(e) {
+function i(e) {
 	return {
 		cX: e.width / 2,
 		cY: e.height / 2
 	};
 }
-function i(e, t, n, r, i) {
+function a(e, t, n, r, i) {
 	switch (t.anchor) {
 		case "bot":
 			n.use(e.pos(0 * r, -1 * i));
@@ -89,43 +75,189 @@ function i(e, t, n, r, i) {
 	}
 }
 //#endregion
-//#region src/helpers/layout-utils.ts
-var a = new Set([
-	"anchor",
-	"pos",
-	"area"
-]);
-function o(e) {
-	return a.has(e);
+//#region src/components/label.ts
+function o(t, n) {
+	let { width: r, height: o, radius: s, posX: c, posY: l, opacity: u, lblColor: d } = {
+		width: 160,
+		height: 96,
+		radius: 0,
+		posX: 0,
+		posY: 0,
+		opacity: .7,
+		lblColor: [
+			0,
+			0,
+			0
+		],
+		...n
+	}, f = t.make([
+		t.rect(r, o, { radius: s }),
+		t.pos(c, l),
+		t.opacity(u),
+		t.anchor("topleft"),
+		{
+			setSize(e, n) {
+				f.width = e, f.height = n;
+				let { cX: r, cY: o } = i(f);
+				a(t, f, f.children[0], r, o);
+			},
+			setRadius(e) {
+				f.radius = e;
+			},
+			setPosition(e, t) {
+				f.pos.x = e, f.pos.y = t;
+			},
+			setOpacity(e) {
+				f.opacity = e;
+			},
+			setLabelColor(n) {
+				e(t, f, n);
+			},
+			setLabelText(e) {
+				let t = f.children[0];
+				t.text = e;
+			},
+			setLabelTextColor(n) {
+				let r = f.children[0];
+				e(t, r, n);
+			},
+			setLabelTextSize(e) {
+				let t = f.children[0];
+				t.textSize = e;
+			},
+			setLabelAnchor(e) {
+				f.anchor = e;
+				let { cX: n, cY: r } = i(f);
+				a(t, f, f.children[0], n, r);
+			}
+		}
+	]);
+	return e(t, f, d), f;
 }
 //#endregion
-//#region src/elements/text-button/index.ts
-function s(t, a, s) {
-	let c = e(t, s, "topleft"), { cX: l, cY: u } = r(c), d = n(t, a, s, l, u, "center");
-	return c.add(d), t.add(c), c.onUse((e) => {
-		if (o(e)) {
-			let { cX: e, cY: n } = r(c);
-			i(t, c, d, e, n);
+//#region src/components/button.ts
+function s(n, r, o) {
+	let { width: s, height: c, posX: l, posY: u, radius: d, outline: f, btnColor: p, outlineColor: m } = {
+		width: 150,
+		height: 60,
+		posX: 0,
+		posY: 0,
+		radius: 10,
+		outline: 3,
+		btnColor: [
+			200,
+			200,
+			200
+		],
+		outlineColor: "#5c5b5b",
+		...r
+	}, h = n.make([
+		n.rect(s, c, { radius: d }),
+		n.pos(l, u),
+		n.anchor(o),
+		n.area(),
+		{
+			setSize(e, t) {
+				h.width = e, h.height = t;
+				let { cX: r, cY: o } = i(h);
+				a(n, h, h.children[0], r, o);
+			},
+			setPosition(e, t) {
+				h.pos.x = e, h.pos.y = t;
+			},
+			setRadius(e) {
+				h.radius = e;
+			},
+			setOutline(e) {
+				t(n, h, e, m);
+			},
+			setButtonText(e) {
+				let t = h.children[0];
+				t.text = e;
+			},
+			setButtonTextSize(e) {
+				let t = h.children[0];
+				t.textSize = e;
+			},
+			setButtonColor(t) {
+				e(n, h, t);
+			},
+			setButtonOutlineColor(e) {
+				t(n, h, f, e);
+			},
+			setAnchor(e) {
+				h.anchor = e;
+				let { cX: t, cY: r } = i(h);
+				a(n, h, h.children[0], t, r);
+			},
+			setButtonTextColor(t) {
+				let r = h.children[0];
+				e(n, r, t);
+			}
+		}
+	]);
+	return e(n, h, p), t(n, h, f, m), h;
+}
+//#endregion
+//#region src/components/text.ts
+function c(t, n, r, i, a, o) {
+	let { txtSize: s, txtColor: c } = {
+		txtSize: 22,
+		...r
+	}, l = t.make([
+		t.text(n, { size: s }),
+		t.pos(i, a),
+		t.anchor(o)
+	]);
+	return e(t, l, c), l;
+}
+//#endregion
+//#region src/elements/label.ts
+function l(e, t, n) {
+	let s = {
+		txtColor: [
+			255,
+			255,
+			255
+		],
+		...n
+	}, l = o(e, s), { cX: u, cY: d } = i(l), f = c(e, t, s, u, d, "center");
+	return l.add(f), e.add(l), l.onUse((t) => {
+		if (r(t)) {
+			let { cX: t, cY: n } = i(l);
+			a(e, l, f, t, n);
 		}
-	}), c.onHover(() => {
-		t.setCursor("pointer");
-	}), c.onHoverEnd(() => {
-		t.setCursor("default");
-	}), c;
+	}), l;
 }
 //#endregion
-//#region src/elements/label/index.ts
-function c(e, i, a) {
-	let o = t(e, a), { cX: s, cY: c } = r(o), l = n(e, i, a, s, c, "center");
-	return l.use(e.color(255, 255, 255)), o.add(l), e.add(o), o;
+//#region src/elements/text-button.ts
+function u(e, t, n) {
+	let o = {
+		txtColor: [
+			0,
+			0,
+			0
+		],
+		...n
+	}, l = s(e, o, "topleft"), { cX: u, cY: d } = i(l), f = c(e, t, o, u, d, "center");
+	return l.add(f), e.add(l), l.onUse((t) => {
+		if (r(t)) {
+			let { cX: t, cY: n } = i(l);
+			a(e, l, f, t, n);
+		}
+	}), l.onHover(() => {
+		e.setCursor("pointer");
+	}), l.onHoverEnd(() => {
+		e.setCursor("default");
+	}), l;
 }
 //#endregion
 //#region src/index.ts
-function l(e) {
+function d(e) {
 	return {
-		addTextButton: (t, n = {}) => s(e, t, n),
-		addLabel: (t, n = {}) => c(e, t, n)
+		addTextButton: (t, n = {}) => u(e, t, n),
+		addLabel: (t, n = {}) => l(e, t, n)
 	};
 }
 //#endregion
-export { l as default };
+export { d as default };

package/dist/uiplugin.umd.cjs

@@ -1 +1 @@
-(function(e,t){typeof exports==`object`&&typeof module<`u`?module.exports=t():typeof define==`function`&&define.amd?define([],t):(e=typeof globalThis<`u`?globalThis:e||self,e.uiPlugin=t())})(this,function(){function e(e,t,n){let{width:r,height:i,radius:a,posX:o,posY:s,outline:c}={width:150,height:60,radius:10,posX:0,posY:0,outline:3,...t};return e.make([e.rect(r,i,{radius:a}),e.pos(o,s),e.color(200,200,200),e.outline(c,e.rgb(92,91,91)),e.anchor(n),e.area()])}function t(e,t){let{width:n,height:r}={width:160,height:96,...t};return e.make([e.rect(n,r),e.pos(0,0),e.color(0,0,0),e.opacity(.7),e.anchor(`topleft`)])}function n(e,t,n,r,i,a){let{txtSize:o}={txtSize:22,...n};return e.make([e.text(t,{size:o}),e.color(0,0,0),e.pos(r,i),e.anchor(a)])}function r(e){return{cX:e.width/2,cY:e.height/2}}function i(e,t,n,r,i){switch(t.anchor){case`bot`:n.use(e.pos(0*r,-1*i));break;case`botleft`:n.use(e.pos(1*r,-1*i));break;case`botright`:n.use(e.pos(-1*r,-1*i));break;case`center`:n.use(e.pos(0*r,0*i));break;case`left`:n.use(e.pos(1*r,0*i));break;case`right`:n.use(e.pos(-1*r,0*i));break;case`top`:n.use(e.pos(0*r,1*i));break;case`topleft`:n.use(e.pos(1*r,1*i));break;case`topright`:n.use(e.pos(-1*r,1*i));break;default:break}}var a=new Set([`anchor`,`pos`,`area`]);function o(e){return a.has(e)}function s(t,a,s){let c=e(t,s,`topleft`),{cX:l,cY:u}=r(c),d=n(t,a,s,l,u,`center`);return c.add(d),t.add(c),c.onUse(e=>{if(o(e)){let{cX:e,cY:n}=r(c);i(t,c,d,e,n)}}),c.onHover(()=>{t.setCursor(`pointer`)}),c.onHoverEnd(()=>{t.setCursor(`default`)}),c}function c(e,i,a){let o=t(e,a),{cX:s,cY:c}=r(o),l=n(e,i,a,s,c,`center`);return l.use(e.color(255,255,255)),o.add(l),e.add(o),o}function l(e){return{addTextButton:(t,n={})=>s(e,t,n),addLabel:(t,n={})=>c(e,t,n)}}return l});
+(function(e,t){typeof exports==`object`&&typeof module<`u`?module.exports=t():typeof define==`function`&&define.amd?define([],t):(e=typeof globalThis<`u`?globalThis:e||self,e.uiPlugin=t())})(this,function(){function e(e,t,n){if(Array.isArray(n)){t.use(e.color([n[0],n[1],n[2]]));return}if(typeof n==`string`){t.use(e.color(n));return}if(typeof n==`object`&&`r`in n){t.use(e.color(e.rgb(n.r,n.g,n.b)));return}t.use(e.color(n))}function t(e,t,n,r){if(typeof r==`string`){t.use(e.outline(n,e.rgb(r)));return}if(Array.isArray(r)){t.use(e.outline(n,e.rgb(r[0],r[1],r[2])));return}}var n=new Set([`anchor`,`rect`]);function r(e){return n.has(e)}function i(e){return{cX:e.width/2,cY:e.height/2}}function a(e,t,n,r,i){switch(t.anchor){case`bot`:n.use(e.pos(0*r,-1*i));break;case`botleft`:n.use(e.pos(1*r,-1*i));break;case`botright`:n.use(e.pos(-1*r,-1*i));break;case`center`:n.use(e.pos(0*r,0*i));break;case`left`:n.use(e.pos(1*r,0*i));break;case`right`:n.use(e.pos(-1*r,0*i));break;case`top`:n.use(e.pos(0*r,1*i));break;case`topleft`:n.use(e.pos(1*r,1*i));break;case`topright`:n.use(e.pos(-1*r,1*i));break;default:break}}function o(t,n){let{width:r,height:o,radius:s,posX:c,posY:l,opacity:u,lblColor:d}={width:160,height:96,radius:0,posX:0,posY:0,opacity:.7,lblColor:[0,0,0],...n},f=t.make([t.rect(r,o,{radius:s}),t.pos(c,l),t.opacity(u),t.anchor(`topleft`),{setSize(e,n){f.width=e,f.height=n;let{cX:r,cY:o}=i(f);a(t,f,f.children[0],r,o)},setRadius(e){f.radius=e},setPosition(e,t){f.pos.x=e,f.pos.y=t},setOpacity(e){f.opacity=e},setLabelColor(n){e(t,f,n)},setLabelText(e){let t=f.children[0];t.text=e},setLabelTextColor(n){let r=f.children[0];e(t,r,n)},setLabelTextSize(e){let t=f.children[0];t.textSize=e},setLabelAnchor(e){f.anchor=e;let{cX:n,cY:r}=i(f);a(t,f,f.children[0],n,r)}}]);return e(t,f,d),f}function s(n,r,o){let{width:s,height:c,posX:l,posY:u,radius:d,outline:f,btnColor:p,outlineColor:m}={width:150,height:60,posX:0,posY:0,radius:10,outline:3,btnColor:[200,200,200],outlineColor:`#5c5b5b`,...r},h=n.make([n.rect(s,c,{radius:d}),n.pos(l,u),n.anchor(o),n.area(),{setSize(e,t){h.width=e,h.height=t;let{cX:r,cY:o}=i(h);a(n,h,h.children[0],r,o)},setPosition(e,t){h.pos.x=e,h.pos.y=t},setRadius(e){h.radius=e},setOutline(e){t(n,h,e,m)},setButtonText(e){let t=h.children[0];t.text=e},setButtonTextSize(e){let t=h.children[0];t.textSize=e},setButtonColor(t){e(n,h,t)},setButtonOutlineColor(e){t(n,h,f,e)},setAnchor(e){h.anchor=e;let{cX:t,cY:r}=i(h);a(n,h,h.children[0],t,r)},setButtonTextColor(t){let r=h.children[0];e(n,r,t)}}]);return e(n,h,p),t(n,h,f,m),h}function c(t,n,r,i,a,o){let{txtSize:s,txtColor:c}={txtSize:22,...r},l=t.make([t.text(n,{size:s}),t.pos(i,a),t.anchor(o)]);return e(t,l,c),l}function l(e,t,n){let s={txtColor:[255,255,255],...n},l=o(e,s),{cX:u,cY:d}=i(l),f=c(e,t,s,u,d,`center`);return l.add(f),e.add(l),l.onUse(t=>{if(r(t)){let{cX:t,cY:n}=i(l);a(e,l,f,t,n)}}),l}function u(e,t,n){let o={txtColor:[0,0,0],...n},l=s(e,o,`topleft`),{cX:u,cY:d}=i(l),f=c(e,t,o,u,d,`center`);return l.add(f),e.add(l),l.onUse(t=>{if(r(t)){let{cX:t,cY:n}=i(l);a(e,l,f,t,n)}}),l.onHover(()=>{e.setCursor(`pointer`)}),l.onHoverEnd(()=>{e.setCursor(`default`)}),l}function d(e){return{addTextButton:(t,n={})=>u(e,t,n),addLabel:(t,n={})=>l(e,t,n)}}return d});

package/package.json

@@ -1,12 +1,24 @@
 {
   "name": "kaplay-ui",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.15",
   "description": "UI components for KAPLAY",
   "type": "module",
-  "main": "src/index.ts",
+  "main": "./dist/uiplugin.js",
+  "types": "./dist/uiplugin.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/uiplugin.js",
+      "require": "./dist/uiplugin.umd.cjs",
+      "types": "./dist/uiplugin.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "dev": "vite dev",
-    "build": "vite build"
+    "build": "vite build",
+    "prepublishOnly": "npm run build"
   },
   "repository": {
     "type": "git",

package/docs/_config.yml

@@ -1,4 +0,0 @@
-theme: jekyll-theme-minimal
-title: "KAPLAY UI"
-description: "UI Plugin for KAPLAY"
-markdown: kramdown

package/docs/_layouts/default.html

@@ -1,23 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-
-    <title>{{ page.title }} - {{ site.title }}</title>
-
-    <!-- Load custom stylesheet -->
-    <link rel="stylesheet" href="{{ '/assets/style.css' | relative_url }}" />
-  </head>
-
-  <body>
-    <!-- KAPLAY-style header -->
-    <header class="kaplay-header">
-      <img src="{{ '/assets/logo.png' | relative_url }}" class="kaplay-logo" />
-    </header>
-
-    <!-- Main content -->
-    <main class="page-content">{{ content }}</main>
-  </body>
-</html>

package/docs/design-decisions/_layout/default.html

@@ -1,23 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-
-    <title>{{ page.title }} - {{ site.title }}</title>
-
-    <!-- Load custom stylesheet -->
-    <link rel="stylesheet" href="{{ '/assets/style.css' | relative_url }}" />
-  </head>
-
-  <body>
-    <!-- KAPLAY-style header -->
-    <header class="kaplay-header">
-      <img src="{{ '/assets/logo.png' | relative_url }}" class="kaplay-logo" />
-    </header>
-
-    <!-- Main content -->
-    <main class="page-content">{{ content }}</main>
-  </body>
-</html>

package/docs/design-decisions/design-decisions.md

@@ -1,6 +0,0 @@
-# Design Decisions
-
-This md and the subfolders below it documents to design decision defaults of:
-
-- [Label](https://github.com/jbakchr/kaplay-ui/blob/v1/docs/design-decisions/label/label-defaults.md)
-- [Text Button](https://github.com/jbakchr/kaplay-ui/blob/v1/docs/design-decisions/text-button/text-button-defaults.md)

package/docs/design-decisions/label/label-defaults.md

@@ -1,219 +0,0 @@
-# Label Design Decisions
-
-This document provides why the current defaults for the `addLabel()` Game Objects are what they are for:
-
-1. [Background color](#-most-common-background-colors-for-labels-in-games)
-2. [Width and Height](#-the-most-common-label-sizes-in-games)
-
-## 🎨 Most Common Background Colors for Labels in Games
-
-### **1. Dark, Semi-Transparent Background (Most Common Overall)**
-
-Examples:
-
-- `rgba(0, 0, 0, 0.5)`
-- `rgba(0, 0, 0, 0.7)`
-
-Why it's common:
-
-- Works on almost every scene background (bright, dark, colorful).
-- Makes white or light text extremely readable.
-- Gives a “HUD” feel found in many genres.
-
-Where it's used:
-
-- Health bars
-- Tooltips
-- HUD counters
-- Inventory labels
-
-This is the single most widely used choice in modern 2D games.
-
----
-
-### **2. Solid Black or Near‑Black Background**
-
-Examples:
-
-- `rgb(0, 0, 0)`
-- `rgb(20, 20, 20)`
-
-Why:
-
-- Maximum contrast
-- Minimalistic
-- Fits sci-fi, retro, and clean UI styles
-
-Often used for:
-
-- Menu labels
-- Title bars
-- Status text
-
-Good when opacity effects aren’t needed.
-
----
-
-### **3. Light Background With Dark Text**
-
-Examples:
-
-- `rgb(255, 255, 255)` with black text
-- `rgb(240, 240, 240)` for softer look
-
-Why:
-
-- Works well for “window”-style UI
-- Mimics desktop/UI patterns
-- Very readable for high-contrast HUDs
-
-Used in:
-
-- Casual games
-- Puzzle games
-- Mobile UX-inspired UI
-
-This is less common than dark backgrounds but still widely used.
-
----
-
-### **4. Colored Background Matching the Game’s Theme**
-
-Examples:
-
-- Blue, red, or green surfaces
-- Faded color fills like `rgba(50, 100, 200, 0.8)`
-
-Why:
-
-- Looks more “stylized” or thematic
-- Helps differentiate label purposes (e.g., warning = red)
-- Used in highly themed menus and fantasy games
-
-Common in:
-
-- JRPG-style menus
-- Crafting systems
-- Quest logs
-
----
-
-### **5. No Background (Text Only)**
-
-While not literally a “background color,” this is a very common choice:
-
-- Pure text HUD
-- Floating damage numbers
-- Dialogue text overlays
-
-Games often use this when:
-
-- Text doesn’t compete with backgrounds
-- The look should be minimal
-
-You can easily support this in `addLabel()` by letting `background: null`.
-
----
-
-## ⭐ If you want the safest, most universal choice…
-
-#### → **Use a dark semi-transparent background with light text.**
-
-Something like:
-
-```ts
-background: rgba(0, 0, 0, 0.5),
-color: rgb(255, 255, 255)
-```
-
-This works cleanly on:
-
-- Dark levels
-- Bright levels
-- High-motion action scenes
-- Stylized or pixel art environments
-
-And it's easy for players to read instantly.
-
----
-
-## 🎮 The Most Common Label Sizes in Games
-
-Even though no source gives explicit “standard label dimensions,” we _can_ derive the common ranges from:
-
-- Typical **pixel-art game resolutions** such as **320×180**, **640×360**, **1280×720** (all frequently used) [\[screwloose....github.io\]](https://screwloose-games.github.io/documentation/content/guides/art/pixel_art/pixel_art_guide.html)
-- Common **sprite and tile sizes** (16×16, 32×32, 64×64) which UI assets usually align to [\[aipixelart.net\]](https://aipixelart.net/node/267)
-- Observed dimensions in **pixel-art UI packs** on itch.io (buttons, panels, labels etc. typically in the 32–128px height range) [\[itch.io\]](https://itch.io/game-assets/tag-gui/tag-pixel-art)
-
-From these, we can determine practical label sizes used in real games.
-
----
-
-### 📐 **Typical Label Widths**
-
-#### **Small labels (HUD counters, score, ammo):**
-
-- **96px – 160px** wide
-- Fits single short text like “SCORE: 0”, “HP”, “XP”, “TIME”
-
-#### **Medium labels (section titles, longer stat text):**
-
-- **160px – 256px** wide
-- Fits text strings like “OBJECTIVE COMPLETE”, “CURRENT QUEST”
-
-#### **Large labels (UI titles, menu headings):**
-
-- **256px – 384px** wide
-- Used for things like “INVENTORY”, “SETTINGS”, “PAUSED”
-
-These sizes map cleanly into 16px/32px multiples recommended for pixel-art alignment.
-
----
-
-### 📏 **Typical Label Heights**
-
-Based on common UI asset proportions:
-
-- **Text-only HUD label:**  
-  **24–32px** tall (for 8–16px font sizes)
-
-- **Label with padding + background panel:**  
-  **32–48px** tall is most standard
-
-- **Chunkier RPG or fantasy labels:**  
-  **48–64px** tall in many itch.io GUI packs [\[itch.io\]](https://itch.io/game-assets/tag-gui/tag-pixel-art)
-
-These heights align with the commonly used sprite grids of **16×16**, **32×32**, and **64×64** pixels from pixel-art standards. [\[aipixelart.net\]](https://aipixelart.net/node/267)
-
----
-
-### 🧩 **Putting It All Together (Practical Defaults)**
-
-For a game using a common base pixel-art resolution like **640×360** (widely recommended), typical label sizes look like this: [\[screwloose....github.io\]](https://screwloose-games.github.io/documentation/content/guides/art/pixel_art/pixel_art_guide.html)
-
-| Label Type          | Width         | Height      |
-| ------------------- | ------------- | ----------- |
-| Small HUD label     | **120–160px** | **24–32px** |
-| Medium UI label     | **160–256px** | **32–48px** |
-| Large heading label | **256–384px** | **48–64px** |
-
-These fit cleanly into standard pixel-art grids and look correct across the common 320×180, 640×360, and 1280×720 style pixel resolutions.
-
----
-
-### 🎯 **Recommended Defaults for kaplay-ui**
-
-If you want to provide sensible defaults for your Label component:
-
-- **Width:** Automatically sized based on text
-- **Height:**
-  - **32px** for simple HUD labels
-  - **48px** for background panels
-
-This keeps things aligned with the pixel-art norms and avoids awkward scaling.
-
----
-
-_**See next decisions about `Text Button` here:**_
-
-- [Text Button](https://github.com/jbakchr/kaplay-ui/blob/v1/docs/design-decisions/text-button/text-button-defaults.md)

package/docs/faq.md

@@ -1,72 +0,0 @@
-# ❓ KAPLAY UI — FAQ
-
-_Frequently asked questions about the KAPLAY UI plugin._
-
----
-
-## 📚 Table of Contents
-
-- [General](#-general)
-- [Installation](#-installation)
-- [Usage](#-usage)
-- [Licensing](#-licensing)
-
----
-
-## 🧠 General
-
-**Q:** _**What is this plugin for?**_
-
-**A:** KAPLAY UI provides lightweight, composable UI helpers — such as text‑based buttons and labels — built using familiar **KAPLAY primitives**.
-
-<div class="block">
-It reduces boilerplate, keeps UI consistent, and helps you build menus, HUDs, overlays, and interactive UI faster.
-</div>
-
----
-
-## 📦 Installation
-
-### **Q:** _**How do I install KAPLAY UI?**_
-
-**A:** Install from your project root using your preferred package manager:
-
-```sh
-npm install kaplay-ui@next
-```
-
----
-
-## 🚀 Usage
-
-### **Q:** _**How do I use the `kaplay-ui` plugin?**_
-
-**A:** Import and enable the plugin when creating your KAPLAY instance:
-
-```ts
-import kaplay from "kaplay";
-import kaplayUI from "kaplay-ui";
-
-const k = kaplay({
-  plugins: [kaplayUI],
-});
-```
-
-Now you can create UI components such as:
-
-```ts
-k.addTextButton("Play");
-k.addLabel("Score: 0");
-```
-
----
-
-## 📄 Licensing
-
-### **Q:** _**How may I use `kaplay-ui` ?**_
-
-The **MIT License** allows full personal and commercial use with virtually no restrictions.
-
-<div class="block">
-🔓 **In short:** You can use, modify, distribute, and even sell projects using KAPLAY UI.
-</div>

package/docs/index.md

@@ -1,126 +0,0 @@
-# 🦖 KAPLAY-UI 🧩
-
-_A lightweight and flexible **UI plugin for KAPLAY**, built to feel like a natural extension of the engine._
-
-Create UI elements quickly using familiar KAPLAY primitives — buttons, labels, HUD elements, menus, and more.
-
-<div class="block">
-
-✨ KAPLAY UI helps you build game-ready user interfaces with almost no setup.
-
-Perfect for menus, HUDs, mobile UI, prototypes, and small-to-medium games.
-
-</div>
-
----
-
-## 🚀 Why KAPLAY UI?
-
-- 🧩 Works exactly like native KAPLAY
-- 🎛️ Easy, declarative API
-- ✨ Sensible styling defaults
-- 🎨 Fully customizable
-
----
-
-## 📦 Installation _(v1.0.0-alpha\*)_
-
-```sh
-npm install kaplay-ui@next
-```
-
----
-
-## 🧰 Getting Started
-
-Add the plugin when creating your KAPLAY instance:
-
-```ts
-import kaplay from "kaplay";
-import kaplayUI from "kaplay-ui";
-
-const k = kaplay({
-  plugins: [kaplayUI],
-});
-```
-
-Now create a UI element:
-
-```ts
-const tb = k.addTextButton("Play");
-const sl = k.addLabel("Score: 0");
-```
-
-_**That’s it** — you’re ready to build UI!_
-
----
-
-## 🧱 Core Components
-
-### 🔤 Text Button
-
-Create an interactive button with centered text and built‑in outline & area detection.
-
-```ts
-const tb = k.addTextButton("Play");
-
-tb.onClick(() => {
-  console.log("Let's play!");
-});
-```
-
-### 🏷️ Label
-
-A small, flexible text element — perfect for HUDs.
-
-```ts
-const lbl = k.addLabel("Score: 0");
-```
-
-_More components are being added soon as the plugin grows._ 🎉
-
----
-
-## 📚 Documentation
-
-_Soon_ .. you can find more details here:
-
-- 📄 **faq.md** — _Questions and answers_
-- 🧠 **design-decisions** — _The Whys?_
-- 🔘 **API Pages** — _The What & How_
-- 🧪 **Examples** — _Learn by doing_
-- 🪧 **Demos** — _See it in action_
-
-## 🗺️ Roadmap (WIP)
-
-- **⏳ More component types**  
-   _(sliders, toggles, panels)_
-
-- **🎨 Theme presets**  
-  _(built-in light/dark UI packs)_
-
-- **🎛️ Complex layout helpers**  
-  _(stacks, grids)_
-
-- **📘 Full documentation site**  
-  _(getting started, faq and .. more)_
-
----
-
-## 🤝 Contributing
-
-Contributions and feature ideas are warmly welcome!
-
-Feel free to submit issues or PRs on GitHub — or share ideas in the discussions tab.
-
----
-
-## 📜 License
-
-MIT © 2026 [Jonas Bak Phillipson](https://github.com/jbakchr)
-
----
-
-<div class="block" style="text-align:center;font-weight:bold;">
-  <p>Made with 💚 + 🦖 by:<p>
-  <p style="font-style:italic;"><span style="color:#ffde86;">The</span> <span style="color:#f2ae99;">KAPLAY </span><span style="color:#CF9FFF;">Community</span></p>

package/docs/release/release.md

@@ -1,19 +0,0 @@
-# About releases
-
-## Alpha releases
-
-### Before release
-Before releasing a new alpha.* version remember to:
-
-- Update v* branch JSDocs
-- Update main branch README.md
-- Update ROADMAP.md
-- Update main branch docs for website
-
-### Steps to release alpha version to npm
-
-1. run `npm login``
-2. npm version prerelease --preid=alpha
-3. npm run build
-4. git push
-5. npm publish --tag next

package/src/index.ts

@@ -1,146 +0,0 @@
-import type { KAPLAYCtx } from "kaplay";
-
-// Types
-import {
-  LabelComponent,
-  LabelOptions,
-  TextButtonElement,
-  TextButtonOptions,
-} from "./types";
-
-// Text Button
-import { createLabel, createTextButton } from "./elements";
-
-/**
- * # KAPLAY UI Plugin
- *
- * A small UI helper plugin that adds convenience functions for creating
- * common UI components such as buttons and labels within a KAPLAY game.
- *
- * ## Available UI Creation Helpers
- *
- * @returns {object} An object exposing UI creation helpers on `k`:
- * - `addTextButton(txt, opts?) → TextButtonElement`
- * - `addLabel(txt, opts?) → LabelComponent`
- *
- * ## Examples
- *
- * @example
- * import kaplay from "kaplay";
- * import kaplayUI from "kaplay-ui"
- *
- * const k = kaplay({
- *    plugins: [kaplayUI]
- * })
- *
- * const button = k.addTextButton("Start");
- * const label = k.addLabel("Hello!");
- */
-
-export default function kaplayUI(k: KAPLAYCtx): {
-  /**
-   * # Text Button
-   * Creates a clickable UI button with centered text.
-   *
-   * This helper provides sensible defaults for size, layout, and styling<br>
-   * so you can quickly add text-based buttons to your KAPLAY game or UI.
-   *
-   * ## Parameters
-   *
-   * ### Required Paramters
-   * - `txt` {string}
-   *
-   * ### Default Parameter Values for 'opts'
-   * - `opts.width`: `150`
-   * - `opts.height`: `60`
-   * - `opts.radius`: `10`
-   * - `opts.posX`: `0`
-   * - `opts.posY`: `0`
-   * - `opts.outline`: `3`
-   *
-   * ## Default Styling
-   * The button object is created with:
-   * - `k.anchor("topleft")`
-   * - `k.color(200, 200, 200)`
-   * - `k.outline(opts.outline, k.rgb(92, 91, 91))`
-   * - `k.area()`
-   *
-   * @param {string} [txt]
-   *   Required text label to be displayed at the center of the button.
-   *
-   * @param {TextButtonOptions} [opts={}]
-   *   Optional configuration object used to customize the button.
-   *
-   * @returns {TextButtonElement}
-   *   A KAPLAY Game Object representing the button with centered text.
-   *
-   * @example
-   * // Basic usage (uses default width/height)
-   * const playBtn = addTextButton("Play");
-   * playBtn.onClick(() => console.log("Play clicked!"));
-   *
-   * @example
-   * // Custom sizing
-   * const bigBtn = addTextButton("Start", { width: 300, height: 120 });
-   *
-   * @example
-   * // Override only one dimension
-   * const tallBtn = addTextButton("Options", { radius: 2 });
-   */
-  addTextButton(txt: string, opts?: TextButtonOptions): TextButtonElement;
-  /**
-   * # Label
-   *
-   * Creates a simple text container with a background and layout box.
-   *
-   * Labels are lightweight UI elements used to display non-interactive text
-   * such as titles, descriptions, or dynamic info (scores, status, etc.).
-   *
-   * ## Parameters
-   *
-   * ### Required Paramters
-   * - `txt` {string}
-   *
-   * ### Default Parameter Values for 'opts'
-   * - `opts.width`: `160`
-   * - `opts.height`: `96`
-   * - `opts.txtSize`: `22`
-   *
-   * ## Default Styling
-   *
-   * A labels base (its 'background' surface) includes:
-   * - `k.pos(0, 0)`
-   * - `k.color(0, 0, 0)`
-   * - `k.opacity(0.7)`
-   * - `k.anchor("topleft")`
-   *
-   * A label centered text includes:
-   * - `k.anchor("center"))
-   * - `k.color(255, 255, 255))
-   *
-   * @param {LabelOptions} [opts={}]
-   *   Optional configuration object used to customize the button.
-   *
-   * @returns {LabelElement}
-   *   A KAPLAY game object representing a text label.
-   *
-   * @example
-   * let score = 0
-   * const scoreLabel = addLabel(`Score: ${score}`);
-   *
-   * k.wait(2, () => {
-   *   score++;
-   *   scoreLabel.children[0].text = `Score: ${score}`;
-   * })
-   */
-  addLabel(txt: string, opts?: LabelOptions): LabelComponent;
-} {
-  return {
-    addTextButton: (
-      txt: string,
-      opts: TextButtonOptions = {},
-    ): TextButtonElement => createTextButton(k, txt, opts),
-    addLabel: (txt, opts: LabelOptions = {}): LabelComponent =>
-      createLabel(k, txt, opts),
-  };
-}