kaplay-ui 0.20.1 → 1.0.0-alpha.1

package/README.md

@@ -1,245 +1,230 @@
-![WIP](https://img.shields.io/badge/status-WIP-yellow)
-<br>_🚧 This package is a work in progress! 🚧_  
-_Expect breaking changes and incomplete features._
+<p align="center">
+  <img src="assets/kaplay-ui-logo.png" alt="kaplay-ui logo" width="400" >
+</p>
 
-# KAPLAY UI - A UI Component Library for KAPLAY
+# KAPLAY UI Plugin
 
-_A simple and customizable component UI library for [KAPLAY](https://kaplayjs.com/)._
+A lightweight UI helper plugin for the https://kaplayjs.com/ game library, providing ready‑to‑use UI components such as text‑based buttons.
 
-## 🚀 Introduction
+This plugin simplifies the creation of UI elements using familiar KAPLAY primitives, offering sensible defaults while remaining flexible and composable.
 
-Kaplay UI is a component library designed specifically for KAPLAY. It will provide ready-made UI components to help you build better user interfaces for your KAPLAY games with minimal effort.
+---
 
-- [Installation](#installation)
-- [Usage](#usage)
-- [License](#license)
+## ✨ Features
 
-## Installation
+- 🎛️ **Text Button** — easily create a button with centered text
+- 🧩 Designed to feel like native KAPLAY components
+- 🎨 Comes with built‑in sizing, positioning, and outline defaults
+- 🔧 Fully customizable through the normal KAPLAY component system
 
-You can install Kaplay UI via npm:
+---
 
-```bash
-npm install kaplay-ui
-```
-
-## Usage
+## 📦 Installation
 
-### Inputs
+You can install the plugin using your preferred package manager:
 
-All inputs are imported from the <code>/inputs</code> folder.
-
-```javascript
-import {} from "kaplay-ui/inputs";
+```sh
+npm install kaplay-ui
 ```
 
-#### Checkbox
-
-To make a checkbox, one must use the exported <code>makeCheckbox()</code> function.
-
-##### Example
-
-An example usage of a checkbox.
-
-```javascript
-import kaplay from "kaplay";
-import "kaplay/global";
-
-import { makeCheckbox } from "kaplay-ui/inputs";
-
-kaplay();
+or:
 
-const checkBox = makeCheckbox();
-
-add(checkBox);
+```sh
+pnpm add kaplay-ui
 ```
 
-##### State
-
-A cehckbox has the following state:
-
-| state     | Type      | Default | State change by   |
-| --------- | --------- | ------- | ----------------- |
-| `checked` | `boolean` | false   | Click on checkbox |
-
-##### Parameters
-
-A checkbox can take the following parameters:
-
-| Parameter | Type     | Default | Required | Description         |
-| --------- | -------- | ------- | -------- | ------------------- |
-| `x`       | `number` | 0       | ❌ No    | Checkbox x position |
-| `y`       | `number` | 0       | ❌ No    | Checkbox x position |
-| `width`   | `number` | 25      | ❌ No    | Checkbox width      |
-| `height`  | `number` | 25      | ❌ No    | Checkbox height     |
+or:
 
-<br>
+yarn add kaplay-ui
 
-#### Switch
+````
 
-To make a text button, one must use the exported <code>makeSwitch()</code> function.
+---
 
-##### Example
+## 🚀 Usage
+Import and register the plugin when initializing your KAPLAY game:
 
-An example usage of a text button.
-
-```javascript
+```js
 import kaplay from "kaplay";
-import "kaplay/global";
-
-import { makeSwitch } from "kaplay-ui/inputs";
+import kaplayUI from "kaplay-ui";
 
-kaplay();
+const k = kaplay({
+  plugins: [kaplayUI],
+});
+````
 
-const switchBtn = makeSwitch();
+You now have access to the UI helpers via your `k` instance:
 
-add(switchBtn);
+```js
+const btn = k.addTextButton("Play", 200, 100);
 ```
 
-##### State
-
-A cehckbox has the following state:
-
-| state      | Type      | Default | State change by |
-| ---------- | --------- | ------- | --------------- |
-| `switched` | `boolean` | false   | Click on switch |
-
-##### Parameters
-
-A switch can take the following parameters:
+---
 
-| Parameter | Type     | Default | Required | Description       |
-| --------- | -------- | ------- | -------- | ----------------- |
-| `x`       | `number` | 0       | ❌ No    | Switch x position |
-| `y`       | `number` | 0       | ❌ No    | Switch x position |
-| `width`   | `number` | 50      | ❌ No    | Switch width      |
-| `height`  | `number` | 25      | ❌ No    | Switch height     |
+## 🔘 `addTextButton()`
 
-<br>
+Creates a button-like GameObj with centered text and some convenient defaults.
 
-#### Text Button
+### **Signature**
 
-To make a text button, one must use the exported <code>makeTextButton()</code> function.
-
-##### Example
-
-An example usage of a text button.
-
-```javascript
-import kaplay from "kaplay";
-import "kaplay/global";
-
-import { makeTextButton } from "kaplay-ui/inputs";
-
-kaplay();
-
-const txtBtn = makeTextButton("Start");
-
-add(txtBtn);
+```ts
+addTextButton(
+  txt?: string,
+  width?: number,
+  height?: number
+): GameObj
 ```
 
-##### Parameters
-
-A text button can take the following parameters:
+### **Default values**
 
-| Parameter    | Type     | Default | Required | Description                        |
-| ------------ | -------- | ------- | -------- | ---------------------------------- |
-| `text`       | `string` | N/A     | ✅ Yes   | The text to display on the button. |
-| `x`          | `number` | 0       | ❌ No    | Button x position                  |
-| `y`          | `number` | 0       | ❌ No    | Button y position                  |
-| `width`      | `number` | 100     | ❌ No    | Button width                       |
-| `height`     | `number` | 50      | ❌ No    | Button height                      |
-| `btnRadius`  | `number` | 8       | ❌ No    | Button radius                      |
-| `btnOutline` | `number` | 1       | ❌ No    | Button outline                     |
-| `txtSize`    | `number` | 15      | ❌ No    | Text size                          |
+| Parameter | Default    |
+| --------- | ---------- |
+| `txt`     | `"Button"` |
+| `width`   | `200`      |
+| `height`  | `100`      |
 
-<br>
+### **Default styling**
 
-#### Text input
+When created, the button includes:
 
-To make a toggle, one must use the exported <code>makeTextInput()</code> function.
+- `k.outline(3)`
+- `k.pos(0, 0)`
+- `k.anchor("topleft")`
+- `k.area()` — for click/hover detection
 
-##### Example
-
-An example usage of a toggle.
-
-```javascript
-import kaplay from "kaplay";
-import "kaplay/global";
+### **Example**
 
-import { makeTextInput } from "kaplay-ui/inputs";
+```js
+// Default button
+const btn1 = k.addTextButton();
 
-kaplay();
+// Custom label
+const btn2 = k.addTextButton("Start");
 
-const txtInput = makeTextInput();
+// Custom size
+const btn3 = k.addTextButton("Start", 150, 75);
 
-add(txtInput);
+// Add interactivity
+btn2.onClick(() => {
+  console.log("Button clicked!");
+});
 ```
 
-##### Parameters
+---
 
-A text input can take the following parameters:
+## 🧱 How It Works
 
-| Parameter  | Type      | Default | Required | Description                    |
-| ---------- | --------- | ------- | -------- | ------------------------------ |
-| `x`        | `number`  | 0       | ❌ No    | x position                     |
-| `y`        | `number`  | 0       | ❌ No    | y position                     |
-| `width`    | `number`  | 400     | ❌ No    | width                          |
-| `txtSize`  | `number`  | 15      | ❌ No    | Input text size                |
-| `pad`      | `number`  | 10      | ❌ No    | Padding                        |
-| `hasFocus` | `boolean` | true    | ❌ No    | If text input has focus or not |
+Internally, the plugin creates a GameObj composed of:
 
-<br>
+- A rectangle-like button base
+- Centered text using KAPLAY's built‑in text component
+- A combined area for input events
 
-#### Toggle
+This keeps your UI elements fully compatible with:
 
-To make a toggle, one must use the exported <code>makeToggle()</code> function.
+- `onClick()`
+- `onHover()`
+- `color()`, `scale()`, etc.
+- Layout within scenes or parent objects
 
-##### Example
+---
 
-An example usage of a toggle.
+## 📱 Mobile‑Friendly UI Demo
 
-```javascript
-import kaplay from "kaplay";
-import "kaplay/global";
-
-import { makeToggle } from "kaplay-ui/inputs";
-
-kaplay();
+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.
 
-const toggle = makeToggle();
+### **Example**
 
-add(toggle);
+```js
+import kaplay from "kaplay";
+import kaplayUI from "kaplay-ui";
+
+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) {
+  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");
 ```
 
-##### State
-
-A cehckbox has the following state:
-
-| state     | Type      | Default | State change by |
-| --------- | --------- | ------- | --------------- |
-| `toggled` | `boolean` | false   | Click on toggle |
-
-##### Parameters
-
-A toggle can take the following parameters:
-
-| Parameter | Type     | Default | Required | Description       |
-| --------- | -------- | ------- | -------- | ----------------- |
-| `x`       | `number` | 0       | ❌ No    | Toggle x position |
-| `y`       | `number` | 0       | ❌ No    | Toggle y position |
-| `width`   | `number` | 50      | ❌ No    | Toggle width      |
-| `height`  | `number` | 25      | ❌ No    | Toggle height     |
-
-<br>
-
-## License
-
-This project is licensed under the MIT License - see the LICENSE file for details.
+### ✔ Features demonstrated
 
-<br>
+- Responsive UI scaling
+- Touch‑friendly hit areas
+- Hover animations for mobile
+- Auto‑centered vertical layout
+- Scene navigation
 
-## Contact
+---
 
-Have questions or suggestions? Reach out via:
+## 📄 License
 
-- GitHub Issues
+MIT — free for personal and commercial use.

package/ROADMAP.md

@@ -0,0 +1,162 @@
+# 📘 **KAPLAY‑UI — Updated Development Roadmap (v1)**
+
+_(Reflecting current progress as of Phase 2 Step 2.4)_
+
+This roadmap tracks the incremental development of the **Container** UI element and the overall plugin architecture for `kaplay-ui`.  
+It replaces the old roadmap and reflects the precise, step-based structure we are now following.
+
+---
+
+# 🌱 **Phase 0 — Planning & API Definition (Completed)**
+
+### **0.1 – Folder Structure Setup** ✔
+
+- Create `src/components/container/` directory
+- Add `index.ts`, `container.types.ts`, `container.logic.ts`, `container.styles.ts`
+
+### **0.2 – Public API Definition** ✔
+
+- Define developer experience (“DX sentence”)
+- Draft ideal usage examples
+- Decide initial required options (`width`, `height`)
+- Decide return type (GameObj + UI helpers)
+- Write full API Contract
+
+---
+
+# 🧱 **Phase 1 — Minimal Functional Container (Completed)**
+
+### **1.1 – Type Definitions** ✔
+
+- Create `UIContainerOptions`
+- Create `UIContainerReturn`
+
+### **1.2 – Factory Scaffolding** ✔
+
+- Add `createContainer()` factory
+- Export from plugin via `k.addContainer()`
+- Add placeholder logic/style hookups
+
+### **1.3 – Minimal Functional Implementation** ✔
+
+- Create Kaplay rect
+- Apply width/height
+- Return real container GameObj
+- Implement minimal `addChild()` (no positioning yet)
+
+---
+
+# 🎨 **Phase 2 — Core Container Functionality (In Progress)**
+
+## ✔ Completed Steps
+
+### **2.1 – Add Basic Styling Support** ✔
+
+- Introduce `defaultContainerStyles`
+- Add `container.styles` field
+- Add placeholder `setStyle()` method
+
+### **2.2 – Add Anchor Support (Scaffolding)** ✔
+
+- Add `anchor?: string` to options
+- Add `container.anchor` property
+- Add `setAnchor()` method
+- Add `applyAnchor()` placeholder
+- Call anchor logic in `initContainerLogic()`
+
+## 🔄 **Current Step (Next to Implement)**
+
+### **2.3 – Apply Styles & Anchors Visually (NOT STARTED YET)**
+
+This will include:
+
+- Applying background color to the rect
+- Applying borderWidth, borderColor, radius
+- Applying padding to internal GameObj positioning
+- Applying anchor visually via Kaplay’s `.anchor()` component
+- Ensuring container size + style reflect options
+
+## ⏳ **Upcoming Step (Depends on Step 2.3)**
+
+### **2.4 – Implement Basic Child Positioning & Padding**
+
+- Children positioned relative to container origin
+- Apply padding offsets
+- Children follow container movement
+- Simple update loop to sync child positions
+
+---
+
+# 📦 **Phase 3 — Layout Engine (Future)**
+
+### **3.1 – Layout Modes: none, vertical, horizontal**
+
+### **3.2 – Spacing support**
+
+### **3.3 – Auto-size based on children**
+
+### **3.4 – Alignment (start, center, end)**
+
+---
+
+# ✨ **Phase 4 — Advanced Features (Future)**
+
+### **4.1 – Borders, shadows, hover states**
+
+### **4.2 – Themes & preset styles**
+
+### **4.3 – z-index / UI layers**
+
+### **4.4 – Optional clipping / scroll masking**
+
+---
+
+# 📚 **Phase 5 — Docs & Testing**
+
+### **5.1 – Full README examples**
+
+### **5.2 – API documentation**
+
+### **5.3 – Unit tests for container behavior**
+
+### **5.4 – Interactive demo in `/test/game.ts`**
+
+---
+
+# 🚀 **Phase 6 — v0.1.0 Release**
+
+### **6.1 – Code cleanup & final polish**
+
+### **6.2 – Publish `kaplay-ui` to npm**
+
+### **6.3 – Announce first usable Container component**
+
+---
+
+# 🧭 **Where We Are Right Now**
+
+As of your last message, you are here:
+
+### ⭐ **Phase 2 → Step 2.4 complete**
+
+Meaning the next step to do together is:
+
+# 👉 **Phase 2 Step 3 — Apply Styles & Anchors Visually**
+
+This is where your container becomes:
+
+- visually styled
+- anchored correctly
+- padded properly
+- a _real_ UI element, not just a rectangle
+
+---
+
+# If you'd like, I can now:
+
+- Create a “live” ROADMAP.md file matching this structure
+- Move you into Phase 2 Step 3
+- Review your existing code to ensure everything matches the roadmap
+- Add future sections (Buttons, Sliders, Text, etc.)
+
+Just tell me what you'd like to do next.

package/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>KAPLAY Plugin Template (TypeScript)</title>
+  </head>
+
+  <body>
+    <script src="./test/game.ts" type="module"></script>
+  </body>
+</html>

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "kaplay-ui",
-  "version": "0.20.1",
+  "version": "1.0.0-alpha.1",
   "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/components/buttons/index.ts

@@ -0,0 +1 @@
+export * from "./text-button";

package/src/components/buttons/text-button/index.ts

@@ -0,0 +1,24 @@
+import type { KAPLAYCtx } from "kaplay";
+
+import { makeButtonText } from "../../texts/index";
+
+export function createTextButton(
+  k: KAPLAYCtx,
+  txt: string,
+  width: number,
+  height: number,
+) {
+  const btn = k.add([
+    k.rect(width, height),
+    k.outline(3),
+    k.pos(0, 0),
+    k.anchor("topleft"),
+    k.area(),
+  ]);
+
+  const btnTxt = makeButtonText(k, btn, txt);
+
+  btn.add(btnTxt);
+
+  return btn;
+}

package/src/components/container/container.logic.ts

@@ -0,0 +1,31 @@
+// src/components/container/container.logic.ts
+
+import type { KAPLAYCtx } from "kaplay";
+import type { UIContainerOptions, UIContainerReturn } from "./container.types";
+
+/**
+ * Placeholder for the internal container logic.
+ * Will create the actual Kaplay GameObj in Phase 1 Step 3.
+ */
+export function initContainerLogic(
+  _k: KAPLAYCtx,
+  container: UIContainerReturn,
+  opts: UIContainerOptions,
+) {
+  console.warn("initContainerLogic() placeholder running.");
+
+  // NEW: anchor preparation
+  applyAnchor(container, opts);
+}
+
+/**
+ * Placeholder function for applying anchor behavior.
+ *
+ * The real implementation will come in Phase 2 Step 3.
+ */
+export function applyAnchor(
+  _container: UIContainerReturn,
+  _opts: UIContainerOptions,
+) {
+  console.warn("applyAnchor() not implemented yet.");
+}

package/src/components/container/container.styles.ts

@@ -0,0 +1,22 @@
+// src/components/container/container.styles.ts
+
+/**
+ * Default styles for all UI Containers.
+ *
+ * These values will later be applied visually (Phase 2 Step 3),
+ * but for now they simply exist as the container's internal style model.
+ */
+export const defaultContainerStyles = {
+  backgroundColor: "rgba(0, 0, 0, 0.4)", // translucent dark background
+  borderColor: "rgba(255, 255, 255, 0.1)", // subtle border
+  borderWidth: 0,
+  radius: 0,
+};
+
+/**
+ * Placeholder: in the future, this will apply the
+ * default styles to the actual Kaplay GameObj.
+ */
+export function applyDefaultContainerStyles(_container: any) {
+  // Implementation will come later in Phase 2 Step 3.
+}

package/src/components/container/container.types.ts

@@ -0,0 +1,45 @@
+// src/components/container/container.types.ts
+
+/**
+ * UIContainerOptions (initial minimal version)
+ *
+ * Only width and height are required at this stage.
+ *
+ * Phase 2 Step 3 introduces padding:
+ *
+ *   padding?: number
+ *
+ * Padding is optional. Default = 0.
+ * Padding represents empty space INSIDE the container.
+ * Children added to the container are offset by the padding
+ * on all sides (top, left, right, bottom).
+ *
+ * Example:
+ * const panel = k.addContainer({
+ *   width: 300,
+ *   height: 200,
+ *   padding: 16,
+ * });
+ */
+export interface UIContainerOptions {
+  width: number;
+  height: number;
+
+  anchor?: string; // "center" and so on
+
+  // Added in Phase 2 Step 3:
+  padding?: number;
+}
+
+/**
+ * UIContainerReturn (initial minimal version)
+ *
+ * The container will eventually merge this with a Kaplay GameObj.
+ */
+export interface UIContainerReturn {
+  uiWidth: number;
+  uiHeight: number;
+  addChild(child: any): void;
+  anchor: string;
+  setAnchor(anchor: string): void;
+}

package/src/components/container/index.ts

@@ -0,0 +1,47 @@
+// src/components/container/index.ts
+
+import type { KAPLAYCtx } from "kaplay";
+import type { UIContainerOptions } from "./container.types";
+import { initContainerLogic } from "./container.logic";
+import {
+  defaultContainerStyles,
+  applyDefaultContainerStyles,
+} from "./container.styles";
+
+/**
+ * Factory function for creating a UI Container.
+ * Phase 2 Step 1: Add styling scaffolding.
+ */
+export function createContainer(k: KAPLAYCtx, opts: UIContainerOptions) {
+  const container = {
+    uiWidth: opts.width,
+    uiHeight: opts.height,
+
+    addChild: (_child: any) => {
+      console.warn("addChild() not implemented yet.");
+    },
+
+    styles: {
+      ...defaultContainerStyles,
+    },
+
+    setStyle(_newStyles: any) {
+      console.warn("setStyle() not implemented yet.");
+    },
+
+    // NEW: store anchor
+    anchor: opts.anchor ?? "topleft",
+
+    // NEW: runtime anchor setter
+    setAnchor(newAnchor: string) {
+      this.anchor = newAnchor;
+      console.warn("setAnchor() not implemented yet.");
+    },
+  };
+
+  // placeholder logic and style application
+  initContainerLogic(k, container, opts);
+  applyDefaultContainerStyles(container);
+
+  return container as any;
+}

package/src/components/index.ts

@@ -0,0 +1 @@
+export * from "./buttons";

package/src/components/texts/index.ts

@@ -0,0 +1 @@
+export * from "./text-button/text-button";

package/src/components/texts/text-button/text-button.ts

@@ -0,0 +1,24 @@
+import type {
+  GameObj,
+  KAPLAYCtx,
+  PosComp,
+  RectComp,
+  OutlineComp,
+  AnchorComp,
+  AreaComp,
+} from "kaplay";
+
+export function makeButtonText(
+  k: KAPLAYCtx,
+  btn: GameObj<PosComp | RectComp | OutlineComp | AnchorComp | AreaComp>,
+  txt: string,
+) {
+  const btnTxt = k.make([
+    k.text(txt),
+    k.color(0, 0, 0),
+    k.pos(btn.width / 2, btn.height / 2),
+    k.anchor("center"),
+  ]);
+
+  return btnTxt;
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+import type { KAPLAYCtx, GameObj } from "kaplay";
+
+import { createTextButton } from "./components";
+
+/**
+ * # KAPLAY UI Plugin
+ * _Add UI Game Objects to your game._
+ *
+ * ## Features
+ * - Text Button (`addTextButton()`)
+ */
+export default function kaplayUI(k: KAPLAYCtx) {
+  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
+     * | Name     | Default      |
+     * |:---------|:-------------|
+     * | `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 {GameObj}
+     *   A KAPLAY Game Object representing the button with centered text.
+     *
+     * @example
+     * const btn = addTextButton();
+     * const playBtn = addTextButton("Play");
+     * const wideBtn = addTextButton("Play", 150);
+     * const smallBtn = addTextButton("Play", 150, 75);
+     */
+    addTextButton: (
+      txt: string = "Button",
+      width: number = 200,
+      height: number = 100,
+    ): GameObj => createTextButton(k, txt, width, height),
+  };
+}

package/test/game.ts

@@ -0,0 +1,9 @@
+import kaplay from "kaplay";
+import kaplayUI from "../src/index";
+
+const k = kaplay({
+  plugins: [kaplayUI],
+  debugKey: "d",
+});
+
+const txtBtn = k.addTextButton("Hello");

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

package/vite.config.ts

@@ -0,0 +1,14 @@
+import { resolve } from "path";
+import { defineConfig } from "vite";
+import dts from "vite-plugin-dts";
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: resolve(__dirname, "src/index.ts"),
+      name: "uiPlugin",
+      fileName: "uiplugin",
+    },
+  },
+  plugins: [dts({ rollupTypes: true, tsconfigPath: "./tsconfig.json" })],
+});

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;
-};