kaplay-ui 0.20.15 → 0.20.16

package/README.md

@@ -11,12 +11,25 @@ Kaplay UI provides a game‑oriented **UI plugin** designed specifically for KAP
 For now it helps you build Game Objects like text buttons and labels — without reinventing the wheel.
 
 > ⚠️ **Note**  
-> The currently published stable version (`0.20.15`) is being replaced by a complete redesign.
+> The currently published stable version (`0.20.16`) is being replaced by a complete redesign.
 >
 > A new **v1** version is under active development and can be installed in prerelease form (see below).
 
 ---
 
+## ✨ _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.\*_)
-
-**Kaplay UI** exports a plugin for adding UI Game Objects.
+## 🚀 Quick start (_1.0.0-alpha.\*_)
 
-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,143 +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()`)
+### 🔤 Text Button — `addTextButton()`
+
+Creates a clickable button with centered text and default visuals.
 
-Creates a button-like GameObj with centered text and some convenient defaults.
+```ts
+const btn = k.addTextButton("Start", {
+  width: 200,
+  height: 80,
+});
+```
 
-#### _**Signature**_
+Buttons support runtime updates such as:
 
 ```ts
-addTextButton(
-  txt: string,
-  opts?: object
-): GameObj
+btn.setSize(300, 100);
+btn.setButtonColor([255, 120, 120]);
+btn.setButtonText("Go!");
+btn.setButtonTextSize(24);
 ```
 
-#### _**Default `opts` parameter values**_
+Perfect for menus, dialogs, and in‑game actions.
 
-| Parameter | Default |
-| --------- | :------ |
-| `width`   | `200`   |
-| `height`  | `100`   |
-| `radius`  | `10`    |
-| `posX`    | `0`     |
-| `posY`    | `0`     |
-| `outline` | `3`     |
-| `txtSize` | `22`    |
+---
+
+### 🏷️ Label — `addLabel()`
 
-#### _**Default styling**_
+Creates a lightweight background + text container for HUD elements or titles.
 
-| Comps                       | Values          |
-| --------------------------- | :-------------- |
-| `button base anchor`        | `"topleft"`     |
-| `button base color`         | `200, 200, 200` |
-| `button base outline color` | `92, 91, 91`    |
-| `button text anchor`        | `"center"`      |
-| `buttontext color`          | `0, 0, 0`       |
+```ts
+const label = k.addLabel("Score: 0");
+```
 
-#### _**Examples**_
+Update it dynamically:
 
 ```ts
-// Basic button
-const btn1 = k.addTextButton("Play!");
+label.setLabelText("Score: 10");
+label.setLabelTextColor([255, 255, 0]);
+label.setOpacity(0.9);
+```
 
-// Custom button by opts parameter
-const btn2 = k.addTextButton("Play!", { posX: 300, posY: 200 });
+Ideal for HUDs, counters, status text, and overlays.
 
-// Customize button base by `use()`
-btn2.use(k.color(150, 150, 150));
+---
 
-// Customize button text by `use()`
-btn2.children[0].text = "Go!";
+## 🎨 Customization
 
-// Add interactivity
-btn2.onClick(() => {
-  k.go("game");
+kaplay-ui is designed to be **customized imperatively**, without hiding
+or abstracting away KAPLAY’s core APIs.
+
+### ✅ Option-based customization (at creation)
+
+Both helpers accept an optional `opts` object for common configuration:
+
+```ts
+const btn = k.addTextButton("Options", {
+  width: 250,
+  height: 70,
+  posX: 100,
+  posY: 200,
+  radius: 8,
 });
 ```
 
 ---
 
-### 🏷️ **Label** (`addLabel()`)
-
-A lightweight text-based UI element — ideal for HUD counters, tooltips, status text, or titles.
+### ✅ Runtime customization (after creation)
 
-#### _**Signature**_
+Each UI element exposes helper methods for updating its appearance and layout:
 
 ```ts
-addLabel(
-    txt: string,
-    opts?: object
-)
+btn.setPosition(150, 220);
+btn.setButtonColor([80, 160, 255]);
+btn.setButtonTextColor([255, 255, 255]);
 ```
 
-#### _**Default `opts` values**_
+This makes it easy to animate, react to state changes, or reuse UI elements.
 
-| Parameter | Default |
-| --------- | ------- |
-| `width`   | `160`   |
-| `height`  | `96`    |
-| `posX`    | `0`     |
-| `posY`    | `0`     |
-| `opacity` | `0.7`   |
-| `txtSize` | `22`    |
-
-#### _**Default styling**_
+---
 
-| Comps               | Values          |
-| ------------------- | :-------------- |
-| `label base color`  | `0, 0,0 `       |
-| `label base anchor` | `"topleft"`     |
-| `label text color`  | `255, 255, 255` |
-| `label text anchor` | `"center"`      |
+### ✅ Full KAPLAY access
 
-#### _**Examples**_
+UI elements are **regular KAPLAY game objects**, so you can still use all
+standard KAPLAY features:
 
 ```ts
-// Basic label
-const lbl1 = k.addLabel("Score: 0");
+btn.use(k.opacity(0.8));
+btn.onHover(() => btn.setScale(1.1));
+label.use(k.rotate(5));
+```
 
-// Custom label by opts parameter
-const lbl2 = k.addLabel("Start", { width: 100, height: 50 });
+kaplay-ui never locks you into a restricted UI model.
 
-// Customize label base by `use()`
-lbl2.use(k.color(150, 150, 150));
+---
 
-// Customize label text by `use()`
-lbl2.children[0].text = "Coins: 100";
+## 🧠 Design philosophy
 
-// Update label text example
-let score = 0;
-const scoreLabel = k.addLabel(`Score: ${score}`);
+**kaplay-ui** is intentionally simple:
 
-k.wait(2, () => {
-  score++;
-  scoreLabel.children[0].text = `Score: ${score}`;
-});
-```
+- ✅ No retained UI trees
+- ✅ No layout engine
+- ✅ No reactive framework
+- ✅ Just KAPLAY game objects + helpers
 
-#### _**Common use cases**_
+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/docs/_includes/nav.html

@@ -21,8 +21,8 @@
 
   /* Brand */
   .nav-brand {
-    font-size: 1.3rem;
-    font-weight: 700;
+    font-size: 1.4rem;
+    font-weight: 800;
     text-decoration: none;
     color: var(--text-dark-green);
   }
@@ -105,7 +105,9 @@
 <nav class="navbar">
   <div class="nav-inner">
     <!-- Logo / Title -->
-    <a class="nav-brand" href="./index.html">kaplay‑ui</a>
+    <a class="nav-brand" href="https://jbakchr.github.io/kaplay-ui/index"
+      >kaplay‑ui</a
+    >
 
     <!-- Hamburger -->
     <input type="checkbox" id="nav-toggle" class="nav-toggle" />
@@ -117,9 +119,9 @@
 
     <!-- Menu -->
     <ul class="nav-menu">
-      <li><a href="./index.html">Home</a></li>
-      <li><a href="./faq.html">FAQ</a></li>
-      <li><a href="./about.html">About</a></li>
+      <li><a href="https://jbakchr.github.io/kaplay-ui/api/plugin">API</a></li>
+      <li><a href="https://jbakchr.github.io/kaplay-ui/faq">FAQ</a></li>
+      <li><a href="https://jbakchr.github.io/kaplay-ui/about">About</a></li>
     </ul>
   </div>
 </nav>

package/docs/about.md

@@ -37,9 +37,6 @@ Thanks for being here — and happy creating! 🦖✨
 
 _— [Jonas Bak Phillipson](https://github.com/jbakchr) (2026)_ 💚 🇩🇰 🏴‍☠️
 
-
-_(And oh .. "ps": I'm actually **not** a 'gamer' myself - but I'd **love** it if KAPLAY and my KAPLAY-UI plugin could help kids and others code their own games!)_
-
 ---
 
 <p align="center">

package/docs/api/components.md

@@ -0,0 +1,255 @@
+# 🧱 UI Components
+
+KAPLAY‑UI provides a small set of lightweight, game‑ready UI components.
+
+All components behave like native KAPLAY objects, integrating naturally with scenes, layers, positions, and events.
+
+---
+
+## 🔤 TextButton
+
+A clickable button with centered text.
+
+```ts
+const btn = k.addTextButton("Play");
+```
+
+---
+
+### Signature
+
+The `addTextButton` method takes a required `string` and an optional `object`.
+
+```ts
+k.addTextButton(txt: string, opts?: {});
+```
+
+---
+
+### Options
+
+All fields are optional. Defaults are shown below.
+
+| Option       | Type                    | Default         |
+| ------------ | ----------------------- | --------------- |
+| width        | number                  | 150             |
+| height       | number                  | 60              |
+| posX         | number                  | 0               |
+| posY         | number                  | 0               |
+| radius       | number                  | 10              |
+| outline      | number                  | 3               |
+| txtSize      | number                  | 22              |
+| btnColor     | [number, number, nuber] | [200, 200, 200] |
+| outlineColor | string                  | #5c5b5b         |
+| txtColor     | [number, number, nuber] | [0, 0, 0]       |
+
+---
+
+### Default Styling
+
+These are the built‑in visual defaults applied automatically.
+
+The **button object** is created with:
+
+- `k.anchor("topleft")`
+- `k.area()`
+
+The **button text** is created with:
+
+- `k.anchor("center")`
+
+---
+
+### Text Button Instance Methods
+
+The returned `ButtonComponent` exposes the following mutator methods,
+allowing the button to be updated after creation:
+
+#### Layout & Geometry
+
+- `setSize(w: number, h: number): void`  
+  _Update the button width and height._
+
+- `setPosition(x: number, y: number): void`  
+  _Move the button to a new position._
+
+- `setAnchor(a: Anchor): void`  
+  _Change the anchor used for positioning._
+
+- `setRadius(r: number): void`  
+  _Update the corner radius._
+
+- `setOutline(t: number): void`  
+  _Set the outline thickness._
+
+#### Text
+
+- `setButtonText(txt: string): void`  
+  _Replace the button label._
+
+- `setButtonTextSize(size: number): void`  
+  _Change the font size of the button text._
+
+- `setButtonTextColor(color: KaplayColor): void`  
+  _Update the text color._
+
+#### Colors
+
+- `setButtonColor(color: KaplayColor): void`  
+  _Change the button fill color._
+
+- `setButtonOutlineColor(color: KaplayRGB): void`  
+  _Change the outline stroke color._
+
+---
+
+### Examples
+
+```ts
+// Basic usage
+const btn1 = addTextButton("Play");
+btn1.onClick(() => k.go("game"));
+
+// Runtime mutation
+const btn2 = addTextButton("Start");
+btn2.setSize(300, 120);
+btn2.setButtonColor([255, 100, 100]);
+btn2.setButtonText("Go!");
+
+// Visual-only updates
+const btn3 = addTextButton("Options", {
+  radius: 2,
+});
+btn3.setButtonOutlineColor([0, 0, 0]);
+btn3.setButtonTextSize(24);
+```
+
+---
+
+## 🏷️ Label
+
+A small, fast text element ideal for HUDs, overlays, and lightweight UI.
+
+```ts
+const score = k.addLabel("Score: 0");
+```
+
+---
+
+### Signature
+
+The `addLabel` method takes a required `string` and an optional `object`.
+
+```ts
+k.addLabel(txt: string, opts?: {});
+```
+
+---
+
+### Options
+
+All fields are optional. Defaults are shown below.
+
+| Option   | Type                     | Default         |
+| -------- | ------------------------ | --------------- |
+| widht    | number                   | 160             |
+| height   | number                   | 96              |
+| posX     | number                   | 0               |
+| posY     | number                   | 0               |
+| opacity  | number                   | 0.7             |
+| txtSize  | number                   | 22              |
+| lblColor | [number, number, number] | [0, 0, 0]       |
+| txtColor | [number, number, number] | [255, 255, 255] |
+
+---
+
+### Default Styling
+
+| Style             | Value     |
+| ----------------- | --------- |
+| label anchor      | "topleft" |
+| label text anchor | "center"  |
+
+---
+
+### Label Instance Methods
+
+The returned `LabelComponent` exposes helper methods that allow the label to be updated dynamically at runtime.
+
+#### Layout & Geometry
+
+- `setSize(w: number, h: number): void`  
+  _Update the label width and height._
+
+- `setPosition(x: number, y: number): void`  
+  _Move the label to a new position._
+
+- `setRadius(r: number): void`  
+  _Update the background corner radius._
+
+- `setLabelAnchor(anchor: Anchor): void`  
+  _Change the anchor used for positioning the label._
+
+#### Appearance
+
+- `setOpacity(o: number): void`  
+  _Set label background opacity (0–1)._
+
+- `setLabelColor(c: KaplayColor): void`  
+  _Change the background color of the label._
+
+#### Text
+
+- `setLabelText(txt: string): void`  
+  _Replace the label text._
+
+- `setLabelTextSize(size: number): void`  
+  _Change the font size of the label text._
+
+- `setLabelTextColor(c: KaplayColor): void`  
+  _Update the label text color._
+
+---
+
+### Example
+
+```ts
+// Basic usage
+const lbl = addLabel("Score: 0");
+lbl.setPosition(20, 20);
+
+// Dynamic text updates (e.g. score counter)
+let score = 0;
+const scoreLbl = addLabel(`Score: ${score}`);
+
+k.wait(2, () => {
+  score++;
+  scoreLbl.setLabelText(`Score: ${score}`);
+});
+
+// Runtime appearance updates
+const title = addLabel("Game Over", {
+  txtSize: 36,
+});
+title.setLabelColor([40, 40, 40]);
+title.setLabelTextColor([255, 80, 80]);
+title.setOpacity(0.9);
+
+// Layout adjustment after creation
+const hudLabel = addLabel("Paused");
+hudLabel.setSize(200, 60);
+hudLabel.setLabelAnchor("center");
+```
+
+---
+
+## 📦 More Components Coming Soon
+
+Planned UI components include:
+
+- Sliders
+- Toggles
+- Panels / Containers
+- Layout helpers (stacks, grids)
+
+These will be added here as the library grows.

package/docs/api/plugin.md

@@ -0,0 +1,117 @@
+# Plugin API
+
+The KAPLAY‑UI plugin extends your `kaplay()` instance with a small set of UI‑focused helper methods.
+
+Once added, the plugin injects new functions on your KAPLAY context for creating UI components.
+
+---
+
+## 🧩 Adding the Plugin
+
+```ts
+import kaplay from "kaplay";
+import kaplayUI from "kaplay-ui";
+
+const k = kaplay({
+  plugins: [kaplayUI],
+});
+```
+
+After this, your `k` instance includes:
+
+- `k.addTextButton(txt, opts?)`
+- `k.addLabel(txt, opts?)`
+
+---
+
+## 🟦 `k.addTextButton(txt, opts?)`
+
+Creates a clickable UI button with built‑in hitbox, outline, and text alignment.
+
+```ts
+const btn = k.addTextButton("Play");
+```
+
+### Parameters
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>Type</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>txt</td>
+    <td>string</td>
+    <td>The button label</td>
+  </tr>
+  <tr>
+    <td>opts</td>
+    <td>object (optional)</td>
+    <td>Styling & behavior options</td>
+  </tr>
+</table>
+
+### Returns
+
+A `TextButton` game object.
+
+For full option details and defaults, see:
+➡️ **[./components#textbutton](https://jbakchr.github.io/kaplay-ui/api/components#-textbutton)**
+
+---
+
+## 🟨 `k.addLabel(txt, opts?)`
+
+Creates a lightweight text element ideal for HUDs and overlays.
+
+```ts
+const lbl = k.addLabel("Score: 0");
+```
+
+### Parameters
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>Type</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>txt</td>
+    <td>string</td>
+    <td>The displayed text</td>
+  </tr>
+  <tr>
+    <td>opts</td>
+    <td>object (optional)</td>
+    <td>Styling options.</td>
+  </tr>
+</table>
+
+### Returns
+
+A `Label` game object.
+
+For full option details and defaults, see:
+➡️ **[./components.md#label](https://jbakchr.github.io/kaplay-ui/api/components#-label)**
+
+---
+
+## ✅ Notes
+
+- All UI components behave like standard KAPLAY game objects.
+- They support transforms, events, layers, and plugin composition.
+- UI elements are intentionally minimal, predictable, and easy to theme.
+
+---
+
+## 📦 More Plugin Coming Soon
+
+Future versions of KAPLAY‑UI will extend the plugin with:
+
+- Additional UI creation helpers
+- Built‑in layout utilities
+- Themable presets (light/dark UI packs)
+
+These will be added here as the library grows.

package/docs/assets/style.css

@@ -217,3 +217,35 @@ a:hover {
   color: var(--text-box-black);
   transform: translateY(-2px);
 }
+
+/* --------------------------------------------------
+ API Tables (Parameters)
+-------------------------------------------------- */
+.page-content table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 1.2rem 0 2rem 0;
+  background: var(--bg-box);
+  border-radius: 10px;
+  overflow: hidden; /* ensures rounded corners clip */
+}
+
+.page-content th,
+.page-content td {
+  padding: 0.6rem 0.8rem;
+  border: 1px solid #3a3a3a;
+  text-align: left;
+  vertical-align: top;
+}
+
+.page-content th {
+  background: #2f2f2f;
+  color: var(--kaplay-yellow);
+  font-weight: 600;
+  font-size: 0.95rem;
+}
+
+.page-content td {
+  color: var(--text-light);
+  font-size: 0.95rem;
+}

package/docs/index.md

@@ -14,7 +14,7 @@ Perfect for menus, HUDs, mobile UI, prototypes, and small-to-medium games.
 
 ---
 
-## 🚀 Why KAPLAY UI?
+## 🚀 Why KAPLAY-UI?
 
 - 🧩 Works exactly like native KAPLAY
 - 🎛️ Easy, declarative API
@@ -57,24 +57,24 @@ _**That’s it** — you’re ready to build UI!_
 
 ## 🧱 Core Components
 
-### 🔤 Text Button
+### 🔤 [Text Button](https://jbakchr.github.io/kaplay-ui/api/components#-textbutton)
 
 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!");
-});
+tb.onClick(() => k.go("game"));
 ```
 
-### 🏷️ Label
+### 🏷️ [Label](https://jbakchr.github.io/kaplay-ui/api/components#-label)
 
 A small, flexible text element — perfect for HUDs.
 
 ```ts
 const lbl = k.addLabel("Score: 0");
+
+lbl.setLabelText("Score: 1");
 ```
 
 _More components are being added soon as the plugin grows._ 🎉
@@ -83,15 +83,27 @@ _More components are being added soon as the plugin grows._ 🎉
 
 ## 📚 Documentation
 
-_Soon_ .. you can find more details here:
+You can find more details here:
+
+- [x] 🔌 **[plugin API](api/plugin)**  
+       — _How the plugin integrates into KAPLAY_
+
+- [x] 🧱 **[Components API](api/components)**  
+       — _All UI components and their options_
+
+- [x] 📄 **[faq.md](https://jbakchr.github.io/kaplay-ui/faq)**  
+       — _Questions and answers_
+
+_And soon also:_
+
+- [ ] 🧪 **Examples**  
+       — _Learn by doing!_
 
-- [x] 📄 **[faq.md](https://jbakchr.github.io/kaplay-ui/faq)** — _Questions and answers_
-- [ ] 🧠 **design-decisions** — _The Whys?_
-- [ ] 🔘 **API Pages** — _The What & How?_
-- [ ] 🧪 **Examples** — _Learn by doing!_
-- [ ] 🪧 **Demos** — _See it in action .._
+- [ ] 🪧 **Demos**  
+       — _See it in action .._
 
-_(And even an [about page](https://jbakchr.github.io/kaplay-ui/about.html) — if anybody would **ever** want to read about why I even started creating `kaply-ui` .. 🤷)_
+- [ ] 🧠 **design-decisions**  
+       — _The Whys?_
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaplay-ui",
-  "version": "0.20.15",
+  "version": "0.20.16",
   "description": "UI components for KAPLAY",
   "main": "index.js",
   "repository": {