@nil-/xit 0.0.1 → 0.0.3

package/README.md

@@ -1,5 +1,288 @@
-# @nil-/xit
+# nil/xit
 
-front end for nil's xit project.
+_nil/xit_ is a small project designed to bridge the gap between C++ and Svelte for creating GUI applications.
 
-TODO: this document
+Note: _Xit_ is a temporary name. It's my playful way of saying, "This is my xit (💩)."
+
+## Motivation
+
+This project isn't intended to replace existing, more mature GUI frameworks. Writing GUI applications in C++ can be complex, with frameworks like Qt, ImGui, and others requiring a deep understanding of setup and usage.
+
+With _nil/xit_, you can write your UI in Svelte and add hooks/bindings to control the interface. While you'll need some familiarity with Svelte, it's a relatively small hurdle to overcome compared to mastering traditional C++ GUI frameworks.
+
+## Requirements
+
+This library is developed in a repo with `vcpkg`.
+
+To consume the library, add _nil_ registry to your _vcpkg-configuration.json_
+
+```json
+{
+    "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg-configuration.schema.json",
+    "default-registry": {
+        "kind": "git",
+        "repository": "https://github.com/Microsoft/vcpkg",
+        "baseline": "da21e45c9ae689f63aa27f3a4ee0e64fe6b16494"
+    },
+    "registries": [
+        {
+            "kind": "git",
+            "repository": "https://github.com/njaldea/nil-vcpkg-ports",
+            "baseline": "02b02d3bc913cbd52da7654cb6f46207e6a9c6d1",
+            "packages": ["nil", "nil-service", "nil-xit"]
+        }
+    ]
+}
+```
+
+Create your target binary and link nil::xit.
+
+```cmake
+project(YOUR_PROJECT)
+
+find_package(nil-xit CONFIG REQUIRED)
+
+add_executable(${PROJECT_NAME} main.cpp)
+target_link_libraries(${PROJECT_NAME} PRIVATE nil::xit)
+```
+
+The following libraries are required to use _nil/xit_ alongside `vcpkg`:
+
+-   [nil/service](https://github.com/njaldea/nil-service)
+
+The following are the libraries needed to compile from source if vcpkg is available.
+
+-   `boost` (`asio` and `beast`)
+-   `protobuf`
+
+TODO: publish libraries other than `vcpkg`
+
+## How it works
+
+The C++ API primarily sets up the network service.
+The GUI itself is not part of the C++ API but is served externally, for example, from [https://xit-ui.vercel.app](https://xit-ui.vercel.app).
+
+At present, the frontend UI connects to a specified URL. For example, if you spawn a WebSocket server on port 1101, you can access the UI by visiting:
+
+```
+https://xit-ui.vercel.app/localhost:1101/id-1
+```
+
+The Svelte files provided to the framework are sent to the frontend, where they are recompiled into a consumable module. You can use any JavaScript libraries available on npm, typically through [https://unpkg.com](https://unpkg.com).
+
+Note: Every page refresh will trigger a recompilation of the files. Caching will be implemented as the library matures.
+
+## Example
+
+### C++ Code
+
+```cpp
+#include <nil/service/ws/Server.hpp>
+
+#include <nil/xit.hpp>
+
+#include <iostream>
+#include <thread>
+
+int main()
+{
+    nil::service::ws::Server server({.port = 1101});
+    // https://xit-ui.vercel.app/{server or ip:port}/{frame id}
+    // https://xit-ui.vercel.app/localhost:1101/frame-id
+
+    auto core = nil::xit::make_core(server);
+
+    auto& frame = add_frame(
+        core,
+        "frame-id",
+        "/absolute/path/to/your/svelte/file.svelte"
+    );
+
+    auto& str_bind = bind(
+        frame,
+        "binding_0_1",
+        "initial value",
+        // this is to test gui -> cpp data flow
+        [](const std::string& value)
+        {
+            // local value is already updated when this is called.
+            std::cout << "value changed: " << value << std::endl;
+        }
+    );
+
+    // this is to test cpp -> gui data flow
+    const std::thread th(
+        [&]()
+        {
+            std::string line;
+            std::cout << "input here: ";
+            while (std::getline(std::cin, line))
+            {
+                // will not update the local data inside str_bind
+                post(str_bind, line);
+
+                // if local data needs to be overwritten, use `set` instead
+                // this will update the local data without waiting for an update
+                // from the UI.
+                set(str_bind, line);
+                std::cout << "input here: ";
+            }
+        }
+    );
+
+    server.run();
+    return 0;
+}
+```
+
+### Svelte UI
+
+```html
+<script>
+    import Text from "./components/Text.svelte";
+
+    import { getContext } from "svelte";
+
+    const { binding } = getContext("nil.xit");
+    const str_binding = binding.string("binding_0_1", "world");
+</script>
+
+<Text bind:value="{$str_binding}" placeholder="placeholder" label="text label here" />
+```
+
+## Supported Binding Types
+
+-   `std::int64_t`
+-   `std::string`
+-   `std::vector\<std::int8_t>`
+
+These are accessible from a context provided to the user.
+
+```html
+<script>
+    import { getContext } from "svelte";
+
+    const { binding } = getContext("nil.xit");
+
+    const store_string = binding.string("id-string", "default_value"); // string
+    const store_number = binding.number("id-number", 1101); // number
+    const store_buffer = binding.buffer("id-buffer", []); // UInt8Array
+</script>
+```
+
+## How about JSON?
+
+JSON is not directly supported. This is intentional since the frontend might not be a browser. It will be up to the user to serialize and deserialize this kind of data.
+
+Example below is an example for handling json by simply stringifying it.
+
+### C++ Code
+
+```cpp
+struct JSON
+{
+    std::string buffer;
+};
+
+namespace nil::xit
+{
+    template <>
+    struct buffer_type<JSON>
+    {
+        static JSON deserialize(const void* data, std::uint64_t size)
+        {
+            return {.buffer = {static_cast<const char*>(data), size}};
+        }
+
+        static std::vector<std::uint8_t> serialize(const JSON& value)
+        {
+            return {value.buffer.begin(), value.buffer.end()};
+        }
+    };
+}
+
+...
+{
+    auto& json_editor = add_frame(
+        core,
+        "frame-id",
+        "/absolute/path/to/your/svelte/file.svelte"
+    );
+    bind<JSON>(
+        json_editor,
+        "json_binding",
+        JSON{.buffer = R"({ "hello": "hello this is buffer" })"},
+        [](const JSON& value) { std::cout << "value changed: " << value.buffer << std::endl; }
+    );
+}
+```
+
+### Svelte UI
+
+```html
+<script>
+    import { getContext } from "svelte";
+
+    const { binding } = getContext("nil.xit");
+    const str_binding = binding.json(
+        "binding-id",
+        {}, // default value
+        {
+            encode: (o) => new TextEncoder().encode(JSON.stringify(o)),
+            decode: (o) => JSON.parse(new TextDecoder().decode(o))
+        }
+    );
+</script>
+```
+
+## Frame Composition
+
+Composing multiple frames into one is possible.
+
+### C++ Code
+
+```cpp
+auto& group = add_frame(
+    core,
+    "group",
+    std::filesystem::path(__FILE__).parent_path() / "gui/GroupUp.svelte"
+);
+
+bind<JSON>(
+    group,
+    "frames",
+    JSON{.buffer = R"({ "frames": ["frame-1", "frame-2"] })"}
+);
+```
+
+### Svelte UI
+
+```html
+<script>
+    import { getContext } from "svelte";
+    const { binding, loader } = getContext("nil.xit");
+
+    const links = binding.json(
+        "links",
+        { links: [] },
+        {
+            encode: (o) => new TextEncoder().encode(JSON.stringify(o)),
+            decode: (o) => JSON.parse(new TextDecoder().decode(o))
+        }
+    );
+</script>
+
+<div class="wrapper">
+    {#each $links.links as link} {@const frame = loader.one(link)}
+    <div use:frame />
+    {/each}
+</div>
+```
+
+TODO:
+
+-   Implement signal/event binding
+-   Develop a usable component library
+-   Create a more intuitive way to specify the connection URL for the page
+-   Enable bundle caching
+-   Optimize json type support

package/index.d.ts

@@ -1 +1,21 @@
-export { binding } from "./src/binding";
+import { type Action } from "svelte/action";
+import { type Writable } from "svelte/store";
+export type CoDec = {
+    encode: (o: object) => Uint8Array;
+    decode: (a: Uint8Array) => object;
+};
+export type Loader = {
+    one: (f: string) => Action<HTMLDivElement>;
+    all: (f: string[]) => Action<HTMLDivElement>;
+};
+export type Xit = {
+    binding: {
+        string: (t: string, v: string) => Writable<string>;
+        number: (t: string, v: number) => Writable<number>;
+        buffer: (t: string, v: Uint8Array) => Writable<Uint8Array>;
+        json: (t: string, v: object, codec: CoDec) => Writable<object>;
+    };
+    loader: Loader;
+};
+export declare const nil_xit: () => Xit;
+export declare const json_string_codec: CoDec;

package/index.js

@@ -1 +1,10 @@
-export { binding } from "./src/binding";
+import { getContext } from "svelte";
+import {} from "svelte/action";
+import {} from "svelte/store";
+export const nil_xit = () => {
+    return getContext("@nil-/xit");
+};
+export const json_string_codec = {
+    encode: (o) => new TextEncoder().encode(JSON.stringify(o)),
+    decode: (o) => JSON.parse(new TextDecoder().decode(o))
+};

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "@nil-/xit",
-  "version": "0.0.1",
+  "version": "0.0.3",
+  "dependencies": {
+    "@rollup/browser": "^4.21.2",
+    "acorn": "^8.12.1",
+    "estree-walker": "^3.0.3",
+    "mdsvex": "^0.12.3",
+    "remark-admonitions": "^1.2.1",
+    "resolve.exports": "^2.0.2"
+  },
   "type": "module",
   "exports": {
     "./package.json": "./package.json",

package/message.proto

@@ -1,49 +0,0 @@
-syntax = "proto3";
-
-option optimize_for = LITE_RUNTIME;
-
-package nil.xit.proto;
-
-enum MessageType {
-    MessageType_MarkupRequest = 0;
-    MessageType_MarkupResponse = 1;
-    MessageType_BindingRequest = 2;
-    MessageType_BindingResponse = 3;
-    MessageType_BindingUpdate = 4;
-    MessageType_FileRequest = 5;
-    MessageType_FileResponse = 6;
-}
-
-message MarkupResponse
-{
-    repeated string components = 1;
-}
-
-message Binding
-{
-    string tag = 1;
-    oneof value {
-        int64 value_i64 = 2;
-        string value_str = 3;
-    }
-}
-
-message BindingGroup
-{
-    repeated Binding bindings = 1;
-}
-
-message BindingResponse
-{
-    repeated BindingGroup info = 1;
-}
-
-message FileRequest
-{
-    string target = 1;
-}
-
-message FileResponse {
-    string target = 1;
-    string content = 3;
-}

package/src/binding.d.ts

@@ -1 +0,0 @@
-export declare const binding: <T>(tag: string, default_value: T) => {};

package/src/binding.js

@@ -1,10 +0,0 @@
-import { getContext } from "svelte";
-import { writable } from 'svelte/store';
-const create_writable = (value) => {
-    const w = writable(value);
-    w.subscribe((v) => console.log("not used", v));
-    return w;
-};
-export const binding = (tag, default_value) => {
-    return getContext(tag) ?? create_writable(default_value);
-};