kaplay-ui 0.20.7 → 0.20.9

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

package/README.md

@@ -8,22 +8,17 @@ _A simple and customizable UI plugin library for building interfaces in https://
 
 Kaplay UI provides a game‑oriented **UI plugin** designed specifically for KAPLAY.
 
-It helps you build Game Objects like buttons, menus, controls, HUD elements, input fields, and more—without reinventing the wheel.
+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.1`) is being replaced by a complete redesign.  
+> The currently published stable version (`0.20.9`) is being replaced by a complete redesign.
+>
 > A new **v1** version is under active development and can be installed in prerelease form (see below).
 
 ---
 
 ## 📦 Installation
 
-### Stable release
-
-```bash
-npm install kaplay-ui
-```
-
 ### Prerelease (new v1 work)
 
 ```bash
@@ -36,9 +31,9 @@ This gives you the latest `1.0.0‑alpha.*` builds.
 
 ## 🚀 Usage
 
-Kaplay UI exports a plugin for adding UI Game Objects.
+**Kaplay UI** exports a plugin for adding UI Game Objects.
 
-The plugin is exported from the package root:
+The `kaplayUI` plugin is exported from the package root:
 
 ```ts
 import kaplay from "kaplay";
@@ -47,36 +42,127 @@ import kaplayUI from "kaplay-ui";
 const k = kaplay({
   plugins: [kaplayUI],
 });
+```
+
+You now have access to the UI helpers via your `k` instance:
+
+```ts
+const btn = k.addTextButton("Play", 200, 100);
+const label = k.addLabel("Score: 0");
+```
+
+---
+
+## 🧩 Game Objects (_**1.0.0‑alpha.\* version**_)
+
+### 🔤 **Text Button** (`addTextButton()`)
+
+Creates a button-like GameObj with centered text and some convenient defaults.
+
+#### _**Signature**_
+
+```ts
+addTextButton(
+  txt?: string,
+  width?: number,
+  height?: number
+): GameObj
+```
+
+#### _**Default values**_
 
+| Parameter | Default    |
+| --------- | ---------- |
+| `txt`     | `"Button"` |
+| `width`   | `200`      |
+| `height`  | `100`      |
+
+#### _**Default styling**_
+
+When created, the button includes:
+
+- k.outline(3)
+- k.pos(0, 0)
+- k.anchor("topleft")
+- k.area() — for click/hover detection
+
+#### _**Examples**_
+
+```ts
+// Default button
+const btn1 = k.addTextButton();
+
+// Custom label
+const btn2 = k.addTextButton("Start");
+
+// Custom size
+const btn3 = k.addTextButton("Start", 150, 75);
+
+// Add interactivity
+btn2.onClick(() => {
+  console.log("Button clicked!");
+});
 ```
 
 ---
 
-## 🧩 Game Objects (_**will evolve over time**_)
+### 🏷️ **Label** (`addLabel()`)
 
-### **Text Button**
+A lightweight text-based UI element — ideal for HUD counters, tooltips, status text, or titles.
 
-Text-based button with centered text:
+#### _**Signature**_
 
 ```ts
-// Button with default centered "Button" text, width of 200, height of 100
-const txtBtn = addTextButton();
+addLabel(
+    txt: string,
+    width: number
+    height: number
+)
+```
+
+#### _**Default values**_
+
+| Parameter | Default |
+| --------- | ------- |
+| `txt`     | `""`    |
+| `width`   | `160`   |
+| `height`  | `96`    |
+
+#### _**Examples**_
+
+```js
+// Default button
+const lbl1 = k.addLabel();
 
-// Button with centered "Play!" text, default width of 200, height of 100
-const txtBtn = addTextButton("Play!");
+// Basic label
+const lbl2 = k.addLabel("Score: 0");
 
-// Button with default centered "Play!" text, width of 250, default height of 100
-const txtBtn = addTextButton("Play!", 250);
+// Custom size
+const lbl3 = k.addLabel("Start", 100, 50);
 
-// Button with default centered "Play!" text, width of 250, height of 150
-const txtBtn = addTextButton("Play!", 250, 150);
+// Update label text example
+let score = 0;
+const scoreLabel = k.addLabel(`Score: ${score}`);
+
+k.wait(2, () => {
+  score++;
+  scoreLabel.children[0].text = `Score: ${score}`;
+});
 ```
 
+#### _**Common use cases**_
+
+- HUD overlays
+- Score counters
+- Time and health displays
+- UI section headings
+- Tooltips and indicators
+
 ---
 
 ## 🛣️ Roadmap
 
-_to be added shortly .._
+_See evolving roadmap at: https://github.com/jbakchr/kaplay-ui/blob/v1/ROADMAP.md_
 
 ---
 

package/docs/_config.yml

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

package/docs/_includes/nav.html

@@ -0,0 +1,125 @@
+<!-- Reusable Navigation Block -->
+<style>
+  /* --------------------------------------------------
+   Sticky Navbar Base Styles
+  -------------------------------------------------- */
+  .navbar {
+    position: sticky;
+    top: 0;
+    z-index: 1000;
+    background: var(--bg-box);
+    padding: 0.75rem 1.25rem;
+    border-bottom: 2px solid var(--kaplay-yellow);
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.25);
+  }
+
+  .nav-inner {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+  }
+
+  /* Brand */
+  .nav-brand {
+    font-size: 1.3rem;
+    font-weight: 700;
+    text-decoration: none;
+    color: var(--text-dark-green);
+  }
+
+  /* Desktop menu */
+  .nav-menu {
+    list-style: none;
+    display: flex;
+    gap: 1.5rem;
+  }
+
+  .nav-menu a {
+    text-decoration: none;
+    font-weight: 600;
+    color: var(--text-purple);
+  }
+
+  .nav-menu a:hover {
+    color: var(--kaplay-salmon);
+  }
+
+  /* --------------------------------------------------
+   Mobile Styles
+-------------------------------------------------- */
+
+  /* Hide checkbox */
+  .nav-toggle {
+    display: none;
+  }
+
+  /* Hamburger icon */
+  .nav-toggle-label {
+    display: none;
+    flex-direction: column;
+    cursor: pointer;
+    gap: 5px;
+  }
+
+  .nav-toggle-label span {
+    display: block;
+    width: 26px;
+    height: 3px;
+    background: var(--kaplay-purple);
+    border-radius: 3px;
+    transition: 0.3s;
+  }
+
+  @media (max-width: 650px) {
+    .nav-toggle-label {
+      display: flex;
+    }
+
+    .nav-menu {
+      position: absolute;
+      top: 60px;
+      left: 0;
+      right: 0;
+
+      width: 100%;
+      max-width: 100vw;
+      box-sizing: border-box;
+
+      background: var(--bg-box);
+      flex-direction: column;
+      padding: 1rem;
+      display: none;
+      border-bottom: 2px solid var(--kaplay-purple);
+    }
+
+    .nav-menu li {
+      margin: 0.75rem 0;
+    }
+
+    .nav-toggle:checked ~ .nav-menu {
+      display: flex;
+    }
+  }
+</style>
+
+<nav class="navbar">
+  <div class="nav-inner">
+    <!-- Logo / Title -->
+    <a class="nav-brand" href="./index.html">kaplay‑ui</a>
+
+    <!-- Hamburger -->
+    <input type="checkbox" id="nav-toggle" class="nav-toggle" />
+    <label for="nav-toggle" class="nav-toggle-label">
+      <span></span>
+      <span></span>
+      <span></span>
+    </label>
+
+    <!-- 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>
+    </ul>
+  </div>
+</nav>

package/docs/_layouts/default.html

@@ -0,0 +1,74 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+
+    <meta name="description" content="Game-ready user interfaces for KAPLAY" />
+
+    <meta name="robots" content="index, follow" />
+
+    <meta name="author" content="Jonas Bak Phillipson" />
+
+    <title>{{ page.title }}</title>
+
+    <!-- Favicons -->
+    <link
+      rel="icon"
+      type="image/png"
+      sizes="32x32"
+      href="{{ '/assets/favicon-32.png' | relative_url }}"
+    />
+    <link
+      rel="icon"
+      type="image/png"
+      sizes="64x64"
+      href="{{ '/assets/favicon-64.png' | relative_url }}"
+    />
+    <link
+      rel="icon"
+      type="image/png"
+      sizes="128x128"
+      href="{{ '/assets/favicon-128.png' | relative_url }}"
+    />
+    <link
+      rel="icon"
+      type="image/png"
+      sizes="256x256"
+      href="{{ '/assets/favicon-256.png' | relative_url }}"
+    />
+    <link
+      rel="icon"
+      type="image/x-icon"
+      href="{{ '/assets/favicon.ico' | relative_url }}"
+    />
+
+    <!-- Load custom stylesheet -->
+    <link rel="stylesheet" href="{{ '/assets/style.css' | relative_url }}" />
+
+    <!-- Open Graph (Facebook, LinkedIn, Discord, Slack) -->
+    <meta property="og:title" content="KAPLAY-UI" />
+    <meta
+      property="og:description"
+      content="A lightweight UI plugin for the KAPLAY game framework."
+    />
+    <meta property="og:type" content="website" />
+    <meta property="og:url" content="https://jbakchr.github.io/kaplay-ui/" />
+    <meta
+      property="og:image"
+      content="{{ '/assets/social-preview.png' | relative_url }}"
+    />
+  </head>
+
+  <body>
+    {% include nav.html %}
+    <!-- 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/about.md

@@ -0,0 +1,47 @@
+---
+layout: default
+title: About
+---
+
+# 🧩 About KAPLAY-UI
+
+<p><span style="color:#6bc96c;font-style:italic;font-weight:bold;">ROAARRR!!</span> .. <span style="font-style:italic">and oh</span> .. Hi! I’m <b>Jonas</b> 👋 — Software Developer 👨‍💻 and the Captain and Board Chairman of <a href="https://codingpirates.dk/what-is-coding-pirates">Coding Pirates Hillerød</a> 🫡🤵‍♂️🏴‍☠️, where we help kids (7–17) explore coding, creativity, and technological daring in the most playful way possible.</p>
+
+## Why? Cuz .. 🦖 + 🧒 + 🧑‍💻 === 💚
+
+One evening while preparing activities, I stumbled across **KAPLAY** …  
+and instantly thought:
+
+<div class="block">
+“Wow — this is perfect for kids!  
+Fast, fun, visual, creative…  
+…BUT the UI bits could be even easier.”
+</div>
+
+So I started building **KAPLAY UI** — a tiny helper library that gives any coders simple, friendly tools like buttons, labels, menus, and HUD elements without the usual boilerplate.
+
+## 🎯 The goal?
+
+- Help kids and others build games
+- Keep the creative flow alive
+- Reduce friction
+- Make KAPLAY _**even more**_ magical
+
+<div class="block">
+If KAPLAY makes game creation fun, <b>KAPLAY UI aims to make it feel <i>accessible</i></b> — even for kids and others discovering coding for the first time.
+</div>
+
+## 🙏 Thanks
+
+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">
+  <a href="./index.html" class="btn">⬅️ Back to Home</a>
+</p>

package/docs/assets/style.css

@@ -0,0 +1,219 @@
+/* --------------------------------------------------
+   KAPLAY Color Variables
+-------------------------------------------------- */
+:root {
+  --kaplay-salmon: #f2ae99;
+  --kaplay-yellow: #ffde86;
+  --kaplay-cyan: #7ffcff;
+  --kaplay-purple: #b291ff;
+
+  --bg-dark: #1b1b1b;
+  --bg-box: #262626;
+
+  --text-light: #eaeaea;
+  --text-purple: #b291ff;
+  --text-dark-green: #6bc96c;
+  --text-box-black: #262626;
+}
+
+/* --------------------------------------------------
+   Base Page Styling
+-------------------------------------------------- */
+body {
+  margin: 0;
+  font-family: "Inter", sans-serif;
+  background: var(--bg-dark);
+  color: var(--text-light);
+  padding-bottom: 4rem;
+}
+
+.page-content {
+  max-width: 860px;
+  margin: 0 auto;
+  padding: 1rem 2rem;
+}
+
+/* --------------------------------------------------
+   KAPLAY-Style Header
+-------------------------------------------------- */
+.kaplay-header {
+  width: 100%;
+  text-align: center;
+  padding: 2rem 0 2rem 0;
+}
+
+.kaplay-logo {
+  width: 400px; /* Your chosen logo width */
+  max-width: 60vw; /* Responsive scaling on mobile */
+  height: auto;
+  opacity: 0.95;
+  transition:
+    transform 0.25s ease,
+    opacity 0.25s ease;
+}
+
+.kaplay-logo:hover {
+  transform: scale(1.06);
+  opacity: 1;
+}
+
+/* --------------------------------------------------
+   Headings (KAPLAY look)
+-------------------------------------------------- */
+h1,
+h2,
+h3 {
+  font-weight: 700;
+  letter-spacing: -0.5px;
+}
+
+h1 {
+  color: var(--kaplay-salmon);
+  font-size: 2.8rem;
+}
+
+h2 {
+  color: var(--kaplay-yellow);
+}
+
+h3 {
+  color: var(--kaplay-purple);
+}
+
+/* --------------------------------------------------
+   Beautiful KAPLAY-style code blocks (fixed + pretty)
+-------------------------------------------------- */
+pre {
+  background: var(--bg-box); /* Match the .block color */
+  padding: 1.25rem 1.5rem; /* Similar to .block but slightly tighter */
+  margin: 2rem 0; /* More breathing room */
+  border-radius: 12px; /* Match block radius */
+  overflow-x: auto;
+  white-space: pre; /* Prevent weird wrapping */
+  box-shadow: 0 4px 18px rgba(0, 0, 0, 0.25);
+}
+
+/* Inner <code> should NOT have padding or background */
+pre code {
+  background: none;
+  padding: 0;
+  margin: 0;
+  line-height: 1.55;
+  font-size: 0.95rem;
+}
+
+/* Inline code */
+code {
+  background: #2b2b2b;
+  padding: 0.15rem 0.35rem;
+  border-radius: 4px;
+}
+
+/* --------------------------------------------------
+   Links
+-------------------------------------------------- */
+a {
+  color: var(--kaplay-purple);
+  text-decoration: none;
+}
+
+a:hover {
+  color: var(--kaplay-salmon);
+}
+
+/* --------------------------------------------------
+   KAPLAY-like Blocks
+-------------------------------------------------- */
+.block {
+  background: var(--bg-box);
+  padding: 1.5rem 2rem;
+  border-radius: 14px;
+  margin: 2rem 0;
+}
+
+/* --------------------------------------------------
+   Improved Mobile Layout - NEW
+   For devices narrower than ~650px
+-------------------------------------------------- */
+@media (max-width: 650px) {
+  /* Reduce global padding so content fits comfortably */
+  .page-content {
+    padding: 0.75rem 1rem;
+  }
+
+  /* Make H1 + H2 more compact and mobile-friendly */
+  h1 {
+    font-size: 2rem;
+    margin-top: 1rem;
+    margin-bottom: 1rem;
+  }
+
+  h2 {
+    font-size: 1.4rem;
+    margin-top: 1.2rem;
+    margin-bottom: 0.8rem;
+  }
+
+  /* Reduce paragraph and list spacing */
+  p,
+  li {
+    line-height: 1.55;
+    font-size: 1rem;
+  }
+
+  /* KAPLAY header styling */
+  .kaplay-header {
+    padding: 1.5rem 0 1.25rem 0;
+  }
+
+  /* Better phone-sized logo */
+  .kaplay-logo {
+    width: 200px; /* smaller default */
+    max-width: 70vw; /* allow it to shrink on narrow screens */
+    margin-bottom: 0.5rem;
+  }
+
+  /* Code blocks: tighter and more readable */
+  pre {
+    padding: 0.75rem;
+    font-size: 0.9rem;
+    line-height: 1.35;
+    margin: 1.25rem 0;
+    border-radius: 8px;
+  }
+
+  code {
+    font-size: 0.9rem;
+  }
+
+  /* Improve .block container spacing */
+  .block {
+    padding: 1.25rem 1.25rem;
+    margin: 1.5rem 0;
+    border-radius: 12px;
+  }
+
+  /* Make links easier to tap */
+  a {
+    padding: 0.2rem 0;
+  }
+}
+
+.btn {
+  display: inline-block;
+  background: var(--kaplay-purple);
+  color: var(--text-light);
+  padding: 0.6rem 1.2rem;
+  border-radius: 8px;
+  text-decoration: none;
+  font-weight: 600;
+  transition:
+    background 0.2s ease,
+    transform 0.2s ease;
+}
+
+.btn:hover {
+  background: var(--kaplay-salmon);
+  color: var(--text-box-black);
+  transform: translateY(-2px);
+}

package/docs/faq.md

@@ -0,0 +1,78 @@
+# ❓ 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` ?**_
+
+**A:** 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>
+
+---
+
+<p align="center">
+  <a href="./index.html" class="btn">⬅️ Back to Home</a>
+</p>

package/docs/index.md

@@ -0,0 +1,130 @@
+# 🦖 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:
+
+- [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 .._
+
+_(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` .. 🤷)_
+
+---
+
+## 🗺️ 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,6 +1,6 @@
 {
   "name": "kaplay-ui",
-  "version": "0.20.7",
+  "version": "0.20.9",
   "description": "UI components for KAPLAY",
   "main": "index.js",
   "repository": {
@@ -17,7 +17,7 @@
   "bugs": {
     "url": "https://github.com/jbakchr/kaplay-ui/issues"
   },
-  "homepage": "https://github.com/jbakchr/kaplay-ui#readme",
+  "homepage": "https://jbakchr.github.io/kaplay-ui/",
   "dependencies": {
     "kaplay": "^3001.0.10"
   },