proteus-sdk 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "proteus-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Proteus, a UI framework whose components transform into other components instead of loading new screens. Draws with WebGPU or WebGL2.",
+  "type": "module",
+  "license": "MIT OR Apache-2.0",
+  "author": "Blue <isaac.chellin@gmail.com>",
+  "homepage": "https://github.com/ichellin1/proteus/tree/main/docs",
+  "bugs": {
+    "url": "https://github.com/ichellin1/proteus/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ichellin1/proteus.git",
+    "directory": "crates/proteus-sdk-web/ts"
+  },
+  "keywords": [
+    "proteus",
+    "ui",
+    "ui-framework",
+    "webgl",
+    "webgl2",
+    "webgpu",
+    "wasm",
+    "webassembly",
+    "animation",
+    "transitions",
+    "metamorphic"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "pkg",
+    "pkg-host"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepack": "rm -f pkg/.gitignore pkg-host/.gitignore",
+    "check-docs": "typedoc src/index.ts --emit none --excludeInternal --validation.notDocumented --validation.invalidLink --treatValidationWarningsAsErrors",
+    "check-snippets": "node ../../../scripts/check-ts-snippets.mjs"
+  },
+  "devDependencies": {
+    "typedoc": "^0.28.20",
+    "typescript": "^5.6.0"
+  }
+}

package/pkg/README.md

@@ -0,0 +1,11 @@
+# proteus-sdk-web
+
+WebAssembly bindings that expose `proteus-sdk` to JavaScript, for the Proteus TypeScript SDK.
+
+Part of [Proteus](https://github.com/ichellin1/proteus).
+
+Apps don't use it directly. In TypeScript, use the [`proteus-sdk` npm package](https://www.npmjs.com/package/proteus-sdk), which is built from it; in Rust, use [`proteus-sdk`](https://crates.io/crates/proteus-sdk).
+
+## License
+
+MIT or Apache-2.0, at your option.

package/pkg/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "proteus-sdk-web",
+  "type": "module",
+  "collaborators": [
+    "Blue <isaac.chellin@gmail.com>"
+  ],
+  "description": "WebAssembly bindings that expose proteus-sdk to JavaScript, for the Proteus TypeScript SDK.",
+  "version": "0.1.0",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ichellin1/proteus"
+  },
+  "files": [
+    "proteus_sdk_web_bg.wasm",
+    "proteus_sdk_web.js",
+    "proteus_sdk_web_bg.js",
+    "proteus_sdk_web.d.ts"
+  ],
+  "main": "proteus_sdk_web.js",
+  "homepage": "https://ichellin1.github.io/proteus/",
+  "types": "proteus_sdk_web.d.ts",
+  "sideEffects": [
+    "./proteus_sdk_web.js",
+    "./snippets/*"
+  ],
+  "keywords": [
+    "ui",
+    "gui",
+    "animation",
+    "transitions",
+    "wgpu"
+  ]
+}

package/pkg/proteus_sdk_web.d.ts

@@ -0,0 +1,309 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * A handle to a component.
+ */
+export class Handle {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Returns a handle for an ID from [`Handle::id`] or
+     * `ComponentData.children`. The ID isn't checked: if its component has
+     * been destroyed, methods that change it throw and `get` returns
+     * `undefined`.
+     */
+    static fromId(id: number): Handle;
+    /**
+     * The component's ID: its entity's bits as a number, which is exact for
+     * any realistic app (see the `dto` module). [`Handle::from_id`] turns it
+     * back into a handle.
+     */
+    id(): number;
+}
+
+/**
+ * A [`Proteus`](sdk::Proteus) app, as JavaScript sees it. Cloning shares the
+ * same app.
+ */
+export class ProteusApp {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Calls [`Handle::add_child`](sdk::Handle::add_child).
+     */
+    addChild(parent: Handle, child: Handle): void;
+    /**
+     * Calls [`Handle::animate_to`](sdk::Handle::animate_to).
+     */
+    animateTo(handle: Handle, to: any, config: any): void;
+    /**
+     * Calls [`Proteus::bake_texture`](sdk::Proteus::bake_texture).
+     */
+    bakeTexture(width: number, height: number, rgba: Uint8Array, request: any): TextureHandle;
+    /**
+     * Calls [`Handle::baked_image_size`](sdk::Handle::baked_image_size).
+     * Returns `undefined` if there is no baked image.
+     */
+    bakedImageSize(handle: Handle): any;
+    /**
+     * Calls [`Handle::baked_text_size`](sdk::Handle::baked_text_size).
+     * Returns `undefined` if there is no baked text.
+     */
+    bakedTextSize(handle: Handle): any;
+    /**
+     * Calls [`TransitionChannel::destroy`](sdk::TransitionChannel::destroy). Consumes
+     * `channel`: the JavaScript object can't be used afterwards.
+     */
+    channelDestroy(channel: TransitionChannel): void;
+    /**
+     * Calls [`TransitionChannel::set`](sdk::TransitionChannel::set).
+     */
+    channelSet(channel: TransitionChannel, to: Handle, from: Handle, config: any, interruptible: boolean): void;
+    /**
+     * Calls [`Proteus::component`](sdk::Proteus::component). `spec` is a
+     * `ComponentSpec` object; its `children` are handle IDs.
+     */
+    component(spec: any): Handle;
+    /**
+     * Calls [`Handle::copy_baked_image_from`](sdk::Handle::copy_baked_image_from).
+     */
+    copyBakedImageFrom(handle: Handle, source: Handle): boolean;
+    /**
+     * Calls [`Proteus::create_video`](sdk::Proteus::create_video).
+     */
+    createVideo(): VideoHandle;
+    /**
+     * Calls [`Handle::crop_image`](sdk::Handle::crop_image). Throws if
+     * `crop` isn't a valid `ImageCrop`.
+     */
+    cropImage(handle: Handle, crop: any): boolean;
+    /**
+     * Calls [`Handle::destroy`](sdk::Handle::destroy). Consumes `handle`: the
+     * JavaScript object can't be used afterwards.
+     */
+    destroy(handle: Handle): void;
+    /**
+     * Calls [`Handle::free_resources`](sdk::Handle::free_resources).
+     */
+    freeResources(handle: Handle): void;
+    /**
+     * Calls [`Proteus::get`](sdk::Proteus::get). Returns `undefined` if the
+     * component has been destroyed.
+     */
+    get(handle: Handle): any;
+    /**
+     * Calls [`Handle::hide_video`](sdk::Handle::hide_video).
+     */
+    hideVideo(handle: Handle): void;
+    /**
+     * Calls [`Proteus::load_texture`](sdk::Proteus::load_texture). Returns
+     * `undefined` if the bytes can't be decoded.
+     */
+    loadTexture(bytes: Uint8Array, request: any): TextureHandle | undefined;
+    /**
+     * Calls [`Handle::merge_from`](sdk::Handle::merge_from). The sources
+     * cross as handle IDs.
+     */
+    mergeFrom(handle: Handle, source_ids: Float64Array, config: any, layout: any): void;
+    /**
+     * Calls [`Handle::merge_from_with_behavior`](sdk::Handle::merge_from_with_behavior).
+     * `child_behavior` is called once per source, before the merge starts.
+     */
+    mergeFromWithBehavior(handle: Handle, source_ids: Float64Array, config: any, layout: any, child_behavior: Function): void;
+    /**
+     * Creates a standalone app, with no host, that draws nothing.
+     */
+    constructor();
+    /**
+     * Calls [`Handle::on_blur`](sdk::Handle::on_blur).
+     */
+    onBlur(handle: Handle, cb: Function): void;
+    /**
+     * Calls [`Handle::on_click`](sdk::Handle::on_click).
+     */
+    onClick(handle: Handle, cb: Function): void;
+    /**
+     * Calls [`Handle::on_drag`](sdk::Handle::on_drag). `cb` receives the
+     * movement as two numbers, `x` and `y`.
+     */
+    onDrag(handle: Handle, cb: Function): void;
+    /**
+     * Calls [`TransitionChannel::on_dropped`](sdk::TransitionChannel::on_dropped).
+     */
+    onDropped(channel: TransitionChannel, cb: Function): void;
+    /**
+     * Calls [`Handle::on_focus`](sdk::Handle::on_focus).
+     */
+    onFocus(handle: Handle, cb: Function): void;
+    /**
+     * Calls [`Handle::on_hover_enter`](sdk::Handle::on_hover_enter).
+     */
+    onHoverEnter(handle: Handle, cb: Function): void;
+    /**
+     * Calls [`Handle::on_hover_exit`](sdk::Handle::on_hover_exit).
+     */
+    onHoverExit(handle: Handle, cb: Function): void;
+    /**
+     * Calls [`Handle::on_press`](sdk::Handle::on_press).
+     */
+    onPress(handle: Handle, cb: Function): void;
+    /**
+     * Calls [`Handle::on_release`](sdk::Handle::on_release).
+     */
+    onRelease(handle: Handle, cb: Function): void;
+    /**
+     * Calls [`Handle::on_transition_complete`](sdk::Handle::on_transition_complete).
+     */
+    onTransitionComplete(handle: Handle, cb: Function): void;
+    /**
+     * Records that the pointer left the viewport: `pointer_moved(None)`.
+     */
+    pointerLeft(): void;
+    /**
+     * Calls [`Proteus::pointer_moved`](sdk::Proteus::pointer_moved). `x` and
+     * `y` are world units: origin at the viewport center, y up.
+     */
+    pointerMoved(x: number, y: number): void;
+    /**
+     * Calls [`Proteus::pointer_pressed`](sdk::Proteus::pointer_pressed).
+     */
+    pointerPressed(): void;
+    /**
+     * Calls [`Proteus::pointer_released`](sdk::Proteus::pointer_released).
+     */
+    pointerReleased(): void;
+    /**
+     * Calls [`VideoHandle::release`](sdk::VideoHandle::release).
+     */
+    releaseVideo(video: VideoHandle): void;
+    /**
+     * Calls [`Handle::remove_child`](sdk::Handle::remove_child).
+     */
+    removeChild(parent: Handle, child: Handle): void;
+    /**
+     * Calls [`Handle::set_declared_geometry`](sdk::Handle::set_declared_geometry).
+     */
+    setDeclaredGeometry(handle: Handle, state: any): void;
+    /**
+     * Calls [`Handle::set_disabled`](sdk::Handle::set_disabled).
+     */
+    setDisabled(handle: Handle, disabled: boolean): void;
+    /**
+     * Calls [`Handle::set_image`](sdk::Handle::set_image).
+     */
+    setImage(handle: Handle, image: any): void;
+    /**
+     * Calls [`Handle::set_interactive`](sdk::Handle::set_interactive).
+     */
+    setInteractive(handle: Handle, interactive: boolean): void;
+    /**
+     * Calls [`Handle::set_opacity`](sdk::Handle::set_opacity).
+     */
+    setOpacity(handle: Handle, opacity: number): void;
+    /**
+     * Calls [`Handle::set_text`](sdk::Handle::set_text).
+     */
+    setText(handle: Handle, text: any): void;
+    /**
+     * Calls [`Handle::set_texture`](sdk::Handle::set_texture).
+     */
+    setTexture(handle: Handle, texture: TextureHandle): boolean;
+    /**
+     * Calls [`Handle::set_transition_interaction`](sdk::Handle::set_transition_interaction).
+     * `null` or `undefined` restores the default.
+     */
+    setTransitionInteraction(handle: Handle, config: any): void;
+    /**
+     * Calls [`Handle::set_video_crossfade`](sdk::Handle::set_video_crossfade).
+     */
+    setVideoCrossfade(handle: Handle, video_t: number): boolean;
+    /**
+     * Calls [`Handle::set_visible`](sdk::Handle::set_visible).
+     */
+    setVisible(handle: Handle, visible: boolean): void;
+    /**
+     * Calls [`Handle::show_video`](sdk::Handle::show_video).
+     */
+    showVideo(handle: Handle, video: VideoHandle): boolean;
+    /**
+     * Calls [`Handle::split_to`](sdk::Handle::split_to). The targets cross
+     * as handle IDs.
+     */
+    splitTo(handle: Handle, target_ids: Float64Array, config: any, strategy: any): void;
+    /**
+     * Calls [`Handle::split_to_with_behavior`](sdk::Handle::split_to_with_behavior).
+     * `child_behavior` is called once per target, before the split starts.
+     */
+    splitToWithBehavior(handle: Handle, target_ids: Float64Array, config: any, strategy: any, child_behavior: Function): void;
+    /**
+     * Calls [`Handle::split_to_with_states`](sdk::Handle::split_to_with_states).
+     * `targets` is an array of `{ id, state }` objects.
+     */
+    splitToWithStates(handle: Handle, targets: any, config: any, strategy: any): void;
+    /**
+     * Returns a texture handle for a texture ID.
+     */
+    texture(id: number): TextureHandle;
+    /**
+     * Calls [`TextureHandle::state`](sdk::TextureHandle::state). Returns
+     * `undefined` if the texture has been evicted or never existed.
+     */
+    textureState(handle: TextureHandle): any;
+    /**
+     * Calls [`Proteus::tick`](sdk::Proteus::tick). For a standalone app only:
+     * a host ticks the shared `Proteus` itself.
+     */
+    tick(dt: number): void;
+    /**
+     * Calls [`Proteus::transition_channel`](sdk::Proteus::transition_channel).
+     * `owner` is a handle ID, since `wasm-bindgen` can't take an optional
+     * reference.
+     */
+    transitionChannel(owner?: number | null): TransitionChannel;
+    /**
+     * Calls [`VideoHandle::upload_frame`](sdk::VideoHandle::upload_frame).
+     */
+    uploadVideoFrame(video: VideoHandle, width: number, height: number, rgba: Uint8Array): boolean;
+}
+
+/**
+ * A handle to a texture in the atlas.
+ */
+export class TextureHandle {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Returns a handle for an ID from [`JsTextureHandle::id`]. To add a
+     * texture, use `loadTexture` or `bakeTexture`.
+     */
+    static fromId(id: number): TextureHandle;
+    /**
+     * The texture's ID, as a number. [`JsTextureHandle::from_id`] turns it
+     * back into a handle.
+     */
+    id(): number;
+}
+
+/**
+ * A handle to a transition channel. It has no methods of its own; it is
+ * passed to `channelSet`, `channelDestroy` and `onDropped`.
+ */
+export class TransitionChannel {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
+/**
+ * A handle to a video whose frames the app supplies. It has no methods of
+ * its own; it is passed to `uploadVideoFrame`, `releaseVideo` and
+ * `showVideo`.
+ */
+export class VideoHandle {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}

package/pkg/proteus_sdk_web.js

@@ -0,0 +1,9 @@
+/* @ts-self-types="./proteus_sdk_web.d.ts" */
+import * as wasm from "./proteus_sdk_web_bg.wasm";
+import { __wbg_set_wasm } from "./proteus_sdk_web_bg.js";
+
+__wbg_set_wasm(wasm);
+wasm.__wbindgen_start();
+export {
+    Handle, ProteusApp, TextureHandle, TransitionChannel, VideoHandle
+} from "./proteus_sdk_web_bg.js";