kaplay-ui 0.20.8 → 1.0.0-alpha.10

package/README.md

@@ -2,38 +2,49 @@
   <img src="assets/kaplay-ui-logo.png" alt="kaplay-ui logo" width="400" >
 </p>
 
-# KAPLAY UI
+# KAPLAY UI Plugin
 
-_A simple and customizable UI plugin library for building interfaces in https://kaplayjs.com/._
+A lightweight UI helper plugin for the [KAPLAY](https://kaplayjs.com/) game library, providing ready‑to‑use UI Game Objects such as text‑based buttons **and labels**.
 
-Kaplay UI provides a game‑oriented **UI plugin** designed specifically for KAPLAY.
+This plugin simplifies the creation of UI Game Object elements using familiar KAPLAY primitives, offering sensible defaults while remaining flexible and composable.
 
-For now it helps you build Game Objects like text buttons and labels — without reinventing the wheel.
+---
+
+## ✨ Features
 
-> ⚠️ **Note**  
-> The currently published stable version (`0.20.8`) is being replaced by a complete redesign.
->
-> A new **v1** version is under active development and can be installed in prerelease form (see below).
+- 🎛️ **Text Button** — easily create a button with centered text
+- 🏷️ **Label** — a lightweight text-based UI element for HUDs, counters, tooltips, and more
+- 🧩 Designed to feel like native KAPLAY components
+- 🎨 Comes with built‑in sizing, positioning, and outline defaults
+- 🔧 Fully customizable through the normal KAPLAY component system
 
 ---
 
 ## 📦 Installation
 
-### Prerelease (new v1 work)
+Install the plugin using your preferred package manager:
+
+```sh
+npm install kaplay-ui
+```
+
+or:
 
-```bash
-npm install kaplay-ui@next
+```sh
+pnpm add kaplay-ui
 ```
 
-This gives you the latest `1.0.0‑alpha.*` builds.
+or:
+
+```sh
+yarn add kaplay-ui
+```
 
 ---
 
 ## 🚀 Usage
 
-**Kaplay UI** exports a plugin for adding UI Game Objects.
-
-The `kaplayUI` plugin is exported from the package root:
+Import and register the plugin when initializing your KAPLAY game:
 
 ```ts
 import kaplay from "kaplay";
@@ -46,20 +57,18 @@ const k = kaplay({
 
 You now have access to the UI helpers via your `k` instance:
 
-```ts
+```js
 const btn = k.addTextButton("Play", 200, 100);
 const label = k.addLabel("Score: 0");
 ```
 
 ---
 
-## 🧩 Game Objects (_**1.0.0‑alpha.\* version**_)
-
-### 🔤 **Text Button** (`addTextButton()`)
+## 🔘 `addTextButton()`
 
 Creates a button-like GameObj with centered text and some convenient defaults.
 
-#### _**Signature**_
+### **Signature**
 
 ```ts
 addTextButton(
@@ -69,7 +78,7 @@ addTextButton(
 ): GameObj
 ```
 
-#### _**Default values**_
+### **Default values**
 
 | Parameter | Default    |
 | --------- | ---------- |
@@ -77,18 +86,18 @@ addTextButton(
 | `width`   | `200`      |
 | `height`  | `100`      |
 
-#### _**Default styling**_
+### **Default styling**
 
 When created, the button includes:
 
-- k.outline(3)
-- k.pos(0, 0)
-- k.anchor("topleft")
-- k.area() — for click/hover detection
+- `k.outline(3)`
+- `k.pos(0, 0)`
+- `k.anchor("topleft")`
+- `k.area()` — for click/hover detection
 
-#### _**Examples**_
+### **Example**
 
-```ts
+```js
 // Default button
 const btn1 = k.addTextButton();
 
@@ -106,11 +115,11 @@ btn2.onClick(() => {
 
 ---
 
-### 🏷️ **Label** (`addLabel()`)
+## 🏷️ `addLabel()`
 
 A lightweight text-based UI element — ideal for HUD counters, tooltips, status text, or titles.
 
-#### _**Signature**_
+### **Signature**
 
 ```ts
 addLabel(
@@ -120,7 +129,7 @@ addLabel(
 )
 ```
 
-#### _**Default values**_
+### **Default values**
 
 | Parameter | Default |
 | --------- | ------- |
@@ -128,7 +137,7 @@ addLabel(
 | `width`   | `160`   |
 | `height`  | `96`    |
 
-#### _**Examples**_
+### **Example**
 
 ```js
 // Default button
@@ -146,11 +155,11 @@ const scoreLabel = k.addLabel(`Score: ${score}`);
 
 k.wait(2, () => {
   score++;
-  scoreLabel.children[0].text = `Score: ${score}`;
-});
+  scoreLabel.children[0].text = `Score: ${score}`
+})
 ```
 
-#### _**Common use cases**_
+### Common use cases
 
 - HUD overlays
 - Score counters
@@ -160,22 +169,108 @@ k.wait(2, () => {
 
 ---
 
-## 🛣️ Roadmap
+## 📱 Mobile‑Friendly UI Demo
 
-_See evolving roadmap at: https://github.com/jbakchr/kaplay-ui/blob/v1/ROADMAP.md_
+This example shows how to build a touch‑friendly UI using `addTextButton()` on mobile devices. It uses responsive scaling and KAPLAY’s `stretch` and `letterbox` features to adapt to different screen sizes.
 
----
+### **Example**
 
-## 📚 License
+```js
+import kaplay from "kaplay";
+import kaplayUI from "kaplay-ui";
 
-This project is licensed under the **MIT License**.  
-See the `LICENSE` file for details.
+const k = kaplay({
+  width: 480, // required when using letterbox/stretch
+  height: 270,
+  background: [25, 25, 25],
+  plugins: [kaplayUI],
+
+  stretch: true, // resize canvas on mobile
+  letterbox: true, // preserve aspect ratio
+});
+
+function uiScale() {
+  return Math.min(k.width() / 400, 1.4);
+}
+
+function centerX(width: number) {
+  return k.center().x - width / 2;
+}
+
+k.scene("mobile-menu", () => {
+  const scale = uiScale();
+
+  k.add([
+    k.text("Mobile Menu", { size: 36 * scale }),
+    k.anchor("center"),
+    k.pos(k.center().x, 70 * scale),
+  ]);
+
+  const btnWidth = 260 * scale;
+  const btnHeight = 90 * scale;
+
+  const startBtn = k.addTextButton("Start", btnWidth, btnHeight);
+  startBtn.pos = k.vec2(centerX(btnWidth), 150 * scale);
+  startBtn.onClick(() => k.go("mobile-game"));
+  startBtn.onHover(() => (startBtn.color = k.rgb(140, 220, 140)));
+  startBtn.onHoverEnd(() => (startBtn.color = k.WHITE));
+
+  const settingsBtn = k.addTextButton("Settings", btnWidth, btnHeight);
+  settingsBtn.pos = k.vec2(centerX(btnWidth), 280 * scale);
+  settingsBtn.onClick(() => k.go("settings"));
+  settingsBtn.onHover(() => (settingsBtn.color = k.rgb(140, 160, 240)));
+  settingsBtn.onHoverEnd(() => (settingsBtn.color = k.WHITE));
+});
+
+k.scene("mobile-game", () => {
+  const scale = uiScale();
+
+  k.add([
+    k.text("Game Scene", { size: 28 * scale }),
+    k.anchor("center"),
+    k.pos(k.center().x, 90 * scale),
+  ]);
+
+  const backBtn = k.addTextButton("Back", 200 * scale, 80 * scale);
+  backBtn.pos = k.vec2(centerX(200 * scale), k.height() - 120 * scale);
+  backBtn.onClick(() => k.go("mobile-menu"));
+  backBtn.onHover(() => (backBtn.scale = 1.1 * scale));
+  backBtn.onHoverEnd(() => (backBtn.scale = scale));
+});
+
+k.scene("settings", () => {
+  const scale = uiScale();
+
+  k.add([
+    k.text("Settings", { size: 32 * scale }),
+    k.anchor("center"),
+    k.pos(k.center().x, 70 * scale),
+  ]);
+
+  const backBtn = k.addTextButton("Back", 200 * scale, 80 * scale);
+  backBtn.pos = k.vec2(centerX(200 * scale), k.height() - 140 * scale);
+  backBtn.onClick(() => k.go("mobile-menu"));
+});
+
+k.go("mobile-menu");
+```
+
+### ✔ Features demonstrated
+
+- Responsive UI scaling
+- Touch‑friendly hit areas
+- Hover animations for mobile
+- Auto‑centered vertical layout
+- Scene navigation
 
 ---
 
-## 💬 Contact
+## 📚 Documentation
+
+_**Evolving**_ documentation is available in the [docs](https://github.com/jbakchr/kaplay-ui/blob/v1/docs/index.md) folder.
+
+---
 
-Have questions or suggestions?  
-Open an issue on GitHub:
+## 📄 License
 
-👉 <https://github.com/jbakchr/kaplay-ui>
+MIT — free for personal and commercial use.

package/dist/uiplugin.js

@@ -0,0 +1,113 @@
+//#region src/components/button/index.ts
+function e(e, t, n, r) {
+	return e.make([
+		e.rect(t, n, { radius: 15 }),
+		e.color(200, 200, 200),
+		e.outline(3, e.rgb(92, 91, 91)),
+		e.pos(0, 0),
+		e.anchor(r),
+		e.area()
+	]);
+}
+//#endregion
+//#region src/components/label/index.ts
+function t(e, t, n) {
+	return e.make([
+		e.rect(t, n),
+		e.pos(0, 0),
+		e.color(0, 0, 0),
+		e.opacity(.7),
+		e.anchor("topleft")
+	]);
+}
+//#endregion
+//#region src/components/text/index.ts
+function n(e, t, n, r, i, a) {
+	return e.make([
+		e.text(t, { size: n }),
+		e.color(0, 0, 0),
+		e.pos(r, i),
+		e.anchor(a)
+	]);
+}
+//#endregion
+//#region src/helpers/pos-utils.ts
+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;
+	}
+}
+//#endregion
+//#region src/helpers/layout-utils.ts
+var a = new Set([
+	"anchor",
+	"pos",
+	"area"
+]);
+function o(e) {
+	return a.has(e);
+}
+//#endregion
+//#region src/elements/text-button/index.ts
+function s(t, a, s, c) {
+	let l = e(t, s, c, "topleft"), { cX: u, cY: d } = r(l), f = n(t, a, 22, u, d, "center");
+	return l.add(f), t.add(l), l.onUse((e) => {
+		if (o(e)) {
+			let { cX: e, cY: n } = r(l);
+			i(t, l, f, e, n);
+		}
+	}), l.onHover(() => {
+		t.setCursor("pointer");
+	}), l.onHoverEnd(() => {
+		t.setCursor("default");
+	}), l;
+}
+//#endregion
+//#region src/elements/label/index.ts
+function c(e, i, a, o) {
+	let s = t(e, a, o), { cX: c, cY: l } = r(s), u = n(e, i, 20, c, l, "center");
+	return u.use(e.color(255, 255, 255)), s.add(u), e.add(s), s;
+}
+//#endregion
+//#region src/index.ts
+function l(e) {
+	return {
+		addTextButton: (t = "Settings", n = 150, r = 60) => s(e, t, n, r),
+		addLabel: (t = "", n = 160, r = 96) => c(e, t, n, r)
+	};
+}
+//#endregion
+export { l as default };

package/dist/uiplugin.umd.cjs

@@ -0,0 +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,r){return e.make([e.rect(t,n,{radius:15}),e.color(200,200,200),e.outline(3,e.rgb(92,91,91)),e.pos(0,0),e.anchor(r),e.area()])}function t(e,t,n){return e.make([e.rect(t,n),e.pos(0,0),e.color(0,0,0),e.opacity(.7),e.anchor(`topleft`)])}function n(e,t,n,r,i,a){return e.make([e.text(t,{size:n}),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,c){let l=e(t,s,c,`topleft`),{cX:u,cY:d}=r(l),f=n(t,a,22,u,d,`center`);return l.add(f),t.add(l),l.onUse(e=>{if(o(e)){let{cX:e,cY:n}=r(l);i(t,l,f,e,n)}}),l.onHover(()=>{t.setCursor(`pointer`)}),l.onHoverEnd(()=>{t.setCursor(`default`)}),l}function c(e,i,a,o){let s=t(e,a,o),{cX:c,cY:l}=r(s),u=n(e,i,20,c,l,`center`);return u.use(e.color(255,255,255)),s.add(u),e.add(s),s}function l(e){return{addTextButton:(t=`Settings`,n=150,r=60)=>s(e,t,n,r),addLabel:(t=``,n=160,r=96)=>c(e,t,n,r)}}return l});

package/docs/_config.yml

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

package/docs/_layouts/default.html

@@ -0,0 +1,23 @@
+<!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

@@ -0,0 +1,23 @@
+<!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

@@ -0,0 +1,6 @@
+# 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

@@ -0,0 +1,219 @@
+# 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

@@ -0,0 +1,72 @@
+# ❓ 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

@@ -0,0 +1,126 @@
+# 🦖 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/package.json

@@ -1,8 +1,13 @@
 {
   "name": "kaplay-ui",
-  "version": "0.20.8",
+  "version": "1.0.0-alpha.10",
   "description": "UI components for KAPLAY",
-  "main": "index.js",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jbakchr/kaplay-ui.git"
@@ -19,7 +24,11 @@
   },
   "homepage": "https://github.com/jbakchr/kaplay-ui#readme",
   "dependencies": {
-    "kaplay": "^3001.0.10"
+    "kaplay": "^3001.0.19"
   },
-  "type": "module"
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "vite": "^8.0.2",
+    "vite-plugin-dts": "^4.5.4"
+  }
 }

package/src/index.ts

@@ -0,0 +1,133 @@
+import type { KAPLAYCtx } from "kaplay";
+
+// Types
+import { LabelComponent, TextButtonElement } 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.
+ *
+ * The returned object extends your KAPLAY context with UI creation helpers.
+ *
+ * ## Available Helpers
+ * - `addTextButton(txt?, width?, height?)`
+ * - `addLabel(txt?, width?, height?)`
+ *
+ * @returns {{
+ *   addTextButton: (txt?: string, width?: number, height?: number) => TextButtonElement,
+ *   addLabel:      (txt?: string, width?: number, height?: number) => LabelElement
+ * }}
+ *   An object exposing helper functions for creating UI elements.
+ *
+ * @example
+ * import kaplay from "kaplay";
+ * import kaplayUI from "kaplay-ui"
+ *
+ * const k = kaplay({
+ *    plugins: [kaplayUI]
+ * })
+ *
+ * const label = k.addLabel("Hello!");
+ * const button = k.addTextButton("Start");
+ */
+
+export default function kaplayUI(k: KAPLAYCtx): {
+  addTextButton: (
+    txt?: string,
+    width?: number,
+    height?: number,
+  ) => TextButtonElement;
+  addLabel: (txt?: string, width?: number, height?: number) => LabelComponent;
+} {
+  return {
+    /**
+     * # Text button
+     * Creates a clickable game object containing a button with centered text.
+     *
+     * This helper provides sensible defaults for size, layout, and styling so you can
+     * quickly add UI buttons to your KAPLAY game.
+     *
+     * ## Default Parameter Values
+     * - `txt`: `"Button"`
+     * - `width`: `200`
+     * - `height`: `100`
+     *
+     * ## Default Styling
+     * The button object is created with:
+     * - `k.outline(3)`
+     * - `k.pos(0, 0)`
+     * - `k.anchor("topleft")`
+     * - `k.area()`
+     *
+     * @param {string} [txt="Button"]
+     *   The text label displayed at the center of the button.
+     *
+     * @param {number} [width=200]
+     *   Width of the button in pixels.
+     *
+     * @param {number} [height=100]
+     *   Height of the button in pixels.
+     *
+     * @returns {TextButton}
+     *   A KAPLAY Game Object representing the button with centered text.
+     *
+     * @example
+     * const playBtn = addTextButton("Play");
+     * playBtn.onClick(() => console.log("Play clicked!"));
+     */
+    addTextButton: (
+      txt: string = "Settings",
+      width: number = 150,
+      height: number = 60,
+    ): TextButtonElement => createTextButton(k, txt, width, height),
+    /**
+     * # 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.).
+     *
+     * ## Default Parameter Values
+     * - `txt`: `""`
+     * - `width`: `160`
+     * - `height`: `96`
+     *
+     * ## Default Styling
+     * A label includes:
+     * - `k.color(0, 0, 0)`
+     * - `k.opacity(0.7)`
+     * - `k.anchor("topleft")`
+     *
+     * @param {string} [txt=""]
+     *   The text content shown inside the label.
+     *
+     * @param {number} [width=160]
+     *   Width of the label container in pixels.
+     *
+     * @param {number} [height=96]
+     *   Height of the label container in pixels.
+     *
+     * @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 = "",
+      width: number = 160,
+      height: number = 96,
+    ): LabelComponent => createLabel(k, txt, width, height),
+  };
+}

package/inputs/index.js

@@ -1,226 +0,0 @@
-import "kaplay/global";
-
-import cbIcon from "../assets/cb-icon.png";
-
-/**
- * Makes button with centered text
- * @param {string} txt - Button text to display
- * @param {number} x - The x postion to set (default is 0).
- * @param {number} y - The x postion to set (default is 0)
- * @param {number} width - Width of button (default is 100)
- * @param {number} height - Height of button (default is 50)
- * @param {number} btnRadius - Border radius of button (default is 8)
- * @param {number} btnOutline - Button outline (default is 1)
- * @param {number} txtSize - Text size of button (default is 15)
- * @returns {GameObj}
- */
-export const makeTextButton = (
-  txt,
-  x = 0,
-  y = 0,
-  width = 100,
-  height = 50,
-  btnRadius = 8,
-  btnOutline = 1,
-  txtSize = 15
-) => {
-  // Make button
-  const btn = make([
-    rect(width, height, { radius: btnRadius }),
-    pos(x, y),
-    area(),
-    scale(1),
-    outline(btnOutline),
-    color(255, 255, 255),
-  ]);
-
-  // Make button text
-  const btnText = make([
-    text(txt, { size: txtSize }),
-    pos(width / 2, height / 2),
-    anchor("center"),
-    color(0, 0, 0),
-  ]);
-
-  // Add text to button
-  btn.add(btnText);
-
-  return btn;
-};
-
-/**
- * Makes toggle
- * @param {number} x - The x postion to set (default is 0)
- * @param {number} y - The x postion to set (default is 0)
- * @param {number} width - Toggle width (default is 50)
- * @param {number} height - Toggle height (default is 25)
- * @returns {GameObj}
- */
-export const makeToggle = (x = 0, y = 0, width = 50, height = 25) => {
-  // Toggle base
-  const toggle = make([
-    rect(width, height, { radius: height / 2 }),
-    pos(x, y),
-    color(169, 169, 169),
-    area(),
-    {
-      toggled: false,
-    },
-  ]);
-
-  // Toggle button
-  const toggleBtn = make([
-    circle(height * 0.4),
-    color(WHITE),
-    pos(height / 2, height / 2),
-  ]);
-
-  // Add button to toggleBase
-  toggle.add(toggleBtn);
-
-  toggle.onClick(() => {
-    if (toggle.toggled) {
-      toggle.use(color(169, 169, 169));
-      toggleBtn.use(pos(height / 2, height / 2));
-      toggle.toggled = false;
-    } else {
-      toggle.use(color(148, 188, 236));
-      toggleBtn.use(pos(width - height / 2, height / 2));
-      toggle.toggled = true;
-    }
-  });
-
-  return toggle;
-};
-
-/**
- * Makes checkbox
- * @param {number} x - The x postion to set (default is 0)
- * @param {number} y - The x postion to set (default is 0)
- * @param {number} width - Checkbox width (default is 25)
- * @param {number} height - Checkbox height (default is 25)
- * @returns {GameObj}
- */
-export const makeCheckbox = (x = 0, y = 0, width = 25, height = 25) => {
-  loadSprite("cb", cbIcon);
-
-  const checkbox = make([
-    rect(width, height, { radius: 4 }),
-    pos(x, y),
-    color(255, 255, 255),
-    outline(1),
-    area(),
-    {
-      checked: false,
-    },
-  ]);
-
-  const checkedIcon = make([sprite("cb", { width, height }), area()]);
-
-  checkbox.onClick(() => {
-    if (checkbox.checked) {
-      checkbox.use(color(255, 255, 255));
-      checkbox.remove(checkedIcon);
-      checkbox.checked = false;
-    } else {
-      checkbox.use(color(148, 188, 236));
-      checkbox.add(checkedIcon);
-      checkbox.checked = true;
-    }
-  });
-
-  return checkbox;
-};
-
-/**
- * Makes switch
- * @param {number} x - Switch x postion (default is 0)
- * @param {number} y - Switch y postion (default is 0)
- * @param {number} width - Switch width (default is 50)
- * @param {number} height - Switch height (default is 25)
- * @returns {GameObj}
- */
-export const makeSwitch = (x = 0, y = 0, width = 50, height = 25) => {
-  // Make switch base
-  const switchBase = make([
-    rect(width, height),
-    pos(x, y),
-    opacity(0),
-    area(),
-    {
-      switched: false,
-    },
-  ]);
-
-  // Make switch line
-  const switchLine = make([
-    rect(width, height / 2, { radius: height / 4 }),
-    color(169, 169, 169),
-    pos(0, height / 2 - height / 4),
-    area(),
-  ]);
-
-  // Make switch circle
-  const switchCircle = make([circle(height / 2), pos(height / 2, height / 2)]);
-
-  // On click
-  switchBase.onClick(() => {
-    if (switchBase.switched) {
-      switchLine.use(color(169, 169, 169));
-      switchCircle.use(color(255, 255, 255));
-      switchCircle.use(pos(height / 2, height / 2));
-      switchBase.switched = false;
-    } else {
-      switchLine.use(color(148, 188, 236));
-      switchCircle.use(color(24, 118, 210));
-      switchCircle.use(pos(width - switchCircle.radius, height / 2));
-      switchBase.switched = true;
-    }
-  });
-
-  // Add line and circle
-  switchBase.add(switchLine);
-  switchBase.add(switchCircle);
-
-  return switchBase;
-};
-
-/**
- * Makes text input
- * @param {number} x - Text input x postion (default is 0)
- * @param {number} y - Text input y postion (default is 0)
- * @param {number} width - Text input width (default is 400)
- * @param {number} txtSize - Text input text size (default is 15)
- * @param {number} pad - Text input padding (default is 10)
- * @param {boolean} hasFocus - Text input focus (default is true)
- * @returns {GameObj}
- */
-export const makeTextInput = (
-  x = 0,
-  y = 0,
-  width = 400,
-  txtSize = 15,
-  pad = 10,
-  hasFocus = true
-) => {
-  // Text input container
-  const inputBase = make([
-    rect(width, txtSize + pad * 2),
-    pos(x, y),
-    area(),
-    outline(1),
-  ]);
-
-  // Text input
-  const input = make([
-    text("", { width: width - pad * 2, size: txtSize }),
-    textInput(hasFocus),
-    color(BLACK),
-    pos(pad, pad),
-    area(),
-  ]);
-
-  inputBase.add(input);
-
-  return inputBase;
-};