proteus-sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ichellin1/proteus/main/brand/logo/assets/lockup-color-dark.png">
+    <img alt="Proteus" src="https://raw.githubusercontent.com/ichellin1/proteus/main/brand/logo/assets/lockup-color-light.png" width="210">
+  </picture>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# proteus-sdk
+
+The TypeScript SDK for [Proteus](https://github.com/ichellin1/proteus), a UI framework whose components transform into one
+another instead of loading new screens: a button can become the panel it opens. It draws on a
+`<canvas>` with WebGPU, or WebGL2 where WebGPU isn't available. Its core is written in Rust and
+compiled to WebAssembly.
+
+```bash
+npm install proteus-sdk
+npm install --save-dev vite-plugin-wasm vite-plugin-top-level-await@1.5.0 @swc/core@1.10.16
+```
+
+With Vite, add both plugins to `vite.config.ts`: `plugins: [wasm(), topLevelAwait()]`. Then, with
+a `<canvas id="app">` on the page, a button that turns into a panel when it's clicked, and back
+when the panel is clicked:
+
+```ts
+import { colorFrom, mount, type Geometry } from "proteus-sdk";
+
+function centered(width: number, height: number, cornerRadius: number): Geometry {
+  return {
+    position: { x: 0, y: 0, z: 0 },
+    size: { width, height },
+    rotation: 0,
+    scale: 1,
+    anchor: { x: 0.5, y: 0.5 },
+    color: colorFrom("#7359cc"),
+    cornerRadius,
+  };
+}
+
+await mount("app", {
+  setup(app) {
+    const button = app.component({
+      geometry: centered(200, 60, 30),
+      text: { content: "Open", sizePx: 24 },
+    });
+    const panel = app.component({
+      geometry: centered(480, 320, 16),
+      text: { content: "Close", sizePx: 24 },
+      visible: false,
+    });
+    const channel = app.transitionChannel();
+    button.onClick(() => channel.set(panel, button, { duration: 0.4 }));
+    panel.onClick(() => channel.set(button, panel, { duration: 0.4 }));
+  },
+});
+```
+
+## Learn more
+
+- [Getting started in TypeScript](https://github.com/ichellin1/proteus/blob/main/docs/getting-started/typescript.md),
+  step by step.
+- [Guides](https://github.com/ichellin1/proteus/tree/main/docs): the concepts, and how-tos.
+- [API reference](https://ichellin1.github.io/proteus/api/ts/).
+- [Examples](https://github.com/ichellin1/proteus/tree/main/examples), and
+  [the reference demo](https://ichellin1.github.io/proteus/), running in your browser.
+- Proteus is written in Rust, and its [Rust crates](https://crates.io/crates/proteus-sdk) can be
+  used directly.
+
+## License
+
+MIT or Apache-2.0, at your option.

package/dist/convert.d.ts

@@ -0,0 +1,24 @@
+import type { Color, Vec2 } from "./types.js";
+/** Converts degrees to radians, the unit {@link Geometry.rotation} uses. */
+export declare function degreesToRadians(degrees: number): number;
+/** Converts radians to degrees. */
+export declare function radiansToDegrees(radians: number): number;
+/**
+ * Converts a hex color or a color name to a {@link Color}.
+ *
+ * Accepts `#rgb`, `#rrggbb` and `#rrggbbaa`, with or without the `#`, and the
+ * names black, white, red, green, blue, yellow, orange, purple, gray (or grey)
+ * and transparent.
+ *
+ * @throws if `input` isn't one of those.
+ */
+export declare function colorFrom(input: string): Color;
+/**
+ * Converts a position measured from the canvas's top-left corner, with y
+ * pointing down (the usual page and canvas convention), to world units, with
+ * the origin at the center and y pointing up. `viewportWidth` and
+ * `viewportHeight` are the canvas's size in the same units as `x` and `y`.
+ */
+export declare function topLeftToWorld(x: number, y: number, viewportWidth: number, viewportHeight: number): Vec2;
+/** Converts world units back to a position from the top-left; the inverse of {@link topLeftToWorld}. */
+export declare function worldToTopLeft(x: number, y: number, viewportWidth: number, viewportHeight: number): Vec2;

package/dist/convert.js

@@ -0,0 +1,76 @@
+// Conversions from familiar web conventions (degrees, hex and named colors,
+// page coordinates) to the values the SDK takes (radians, RGBA from 0 to 1,
+// world units with the origin at the viewport center and y up).
+/** Converts degrees to radians, the unit {@link Geometry.rotation} uses. */
+export function degreesToRadians(degrees) {
+    return (degrees * Math.PI) / 180;
+}
+/** Converts radians to degrees. */
+export function radiansToDegrees(radians) {
+    return (radians * 180) / Math.PI;
+}
+// A small set of CSS color names for quick prototyping. Deliberately not the
+// full CSS list.
+const NAMED_COLORS = {
+    black: "#000000",
+    white: "#ffffff",
+    red: "#ff0000",
+    green: "#008000",
+    blue: "#0000ff",
+    yellow: "#ffff00",
+    orange: "#ffa500",
+    purple: "#800080",
+    gray: "#808080",
+    grey: "#808080",
+    transparent: "#00000000",
+};
+/**
+ * Converts a hex color or a color name to a {@link Color}.
+ *
+ * Accepts `#rgb`, `#rrggbb` and `#rrggbbaa`, with or without the `#`, and the
+ * names black, white, red, green, blue, yellow, orange, purple, gray (or grey)
+ * and transparent.
+ *
+ * @throws if `input` isn't one of those.
+ */
+export function colorFrom(input) {
+    const named = NAMED_COLORS[input.toLowerCase()];
+    const hex = (named ?? input).replace(/^#/, "");
+    let r;
+    let g;
+    let b;
+    let a = 1;
+    if (hex.length === 3) {
+        r = parseInt(hex[0] + hex[0], 16);
+        g = parseInt(hex[1] + hex[1], 16);
+        b = parseInt(hex[2] + hex[2], 16);
+    }
+    else if (hex.length === 6 || hex.length === 8) {
+        r = parseInt(hex.slice(0, 2), 16);
+        g = parseInt(hex.slice(2, 4), 16);
+        b = parseInt(hex.slice(4, 6), 16);
+        if (hex.length === 8) {
+            a = parseInt(hex.slice(6, 8), 16) / 255;
+        }
+    }
+    else {
+        throw new Error(`colorFrom: unrecognized color "${input}"`);
+    }
+    if ([r, g, b].some((c) => Number.isNaN(c))) {
+        throw new Error(`colorFrom: unrecognized color "${input}"`);
+    }
+    return { r: r / 255, g: g / 255, b: b / 255, a };
+}
+/**
+ * Converts a position measured from the canvas's top-left corner, with y
+ * pointing down (the usual page and canvas convention), to world units, with
+ * the origin at the center and y pointing up. `viewportWidth` and
+ * `viewportHeight` are the canvas's size in the same units as `x` and `y`.
+ */
+export function topLeftToWorld(x, y, viewportWidth, viewportHeight) {
+    return { x: x - viewportWidth / 2, y: viewportHeight / 2 - y };
+}
+/** Converts world units back to a position from the top-left; the inverse of {@link topLeftToWorld}. */
+export function worldToTopLeft(x, y, viewportWidth, viewportHeight) {
+    return { x: x + viewportWidth / 2, y: viewportHeight / 2 - y };
+}