@arcanejs/toolkit 1.1.0 → 2.0.0

package/dist/toolkit-2w2SWHlT.d.ts

@@ -0,0 +1,269 @@
+import * as _arcanejs_protocol_logging from '@arcanejs/protocol/logging';
+import { Logger } from '@arcanejs/protocol/logging';
+import _ from 'lodash';
+import * as http from 'http';
+import { Application } from 'express';
+import { WebSocket } from 'ws';
+import { ClientMessage, ServerMessage, BaseComponentProto, AnyClientComponentMessage } from '@arcanejs/protocol';
+import * as proto from '@arcanejs/protocol/core';
+import { GroupComponentStyle } from '@arcanejs/protocol/styles';
+import { I as IDMap } from './id-map-DxQ3_gyA.js';
+
+interface Connection {
+    sendMessage(msg: ServerMessage): void;
+}
+declare class Server {
+    private readonly options;
+    private readonly onNewConnection;
+    private readonly onClosedConnection;
+    private readonly onMessage;
+    private readonly log?;
+    private readonly staticFiles;
+    private readonly entrypointFilename;
+    private title;
+    constructor(options: ToolkitOptions, onNewConnection: (connection: Connection) => void, onClosedConnection: (connection: Connection) => void, onMessage: (connection: Connection, message: ClientMessage) => void, log?: Logger | undefined);
+    handleHttpRequest: (req: http.IncomingMessage, res: http.ServerResponse) => Promise<void>;
+    private sendStaticFile;
+    handleWsConnection: <S extends WebSocket>(ws: S) => void;
+}
+
+interface ToolkitOptions {
+    /**
+     * What window title should the toolkit be initialized with?
+     */
+    title?: string;
+    /**
+     * What path should be used to serve the light desk.
+     *
+     * This is important if a express server will be used that serves other paths.
+     */
+    path: string;
+    /**
+     * An optional object that can be used to output log events,
+     * we recommend using `pino` for this,
+     * as log levels etc... can be controlled.
+     *
+     * You can also always use `console` for logging,
+     * but this will be quite verbose.
+     */
+    log?: Logger;
+    /**
+     * The entrypoint file that should be used to serve the light desk.
+     *
+     * This is only needed if you have defined custom extensions,
+     * and need to load custom frontend code that includes your extensions.
+     *
+     * This will allow access to both the js file and the `.map.js` file,
+     * that matches this name.
+     */
+    entrypointJsFile?: string;
+    /**
+     * If it's not possible to automatically resolve and import the
+     * material-symbols package in node_modules
+     * (for example when bundling an electron app),
+     * you can provide the path to the material-symbols-outlined.woff2 file here.
+     */
+    materialIconsFontFile?: string;
+}
+type InitializationOptions = 
+/** automatically start a simple  */
+{
+    mode: 'automatic';
+    port: number;
+    /**
+     * Optional callback that is called when the server is ready,
+     * with the url that the server is running on.
+     */
+    onReady?: (url: string) => void;
+}
+/** Create a websocket server that attaches to an existing express and http server */
+ | {
+    mode: 'express';
+    express: Application;
+    server: http.Server;
+}
+/** Create a websocket server that attaches to an existing express and http server */
+ | {
+    mode: 'manual';
+    setup: (server: Server) => void;
+};
+
+declare abstract class Base<Namespace extends string, Proto extends BaseComponentProto<Namespace>, Props> {
+    /** @hidden */
+    private parent;
+    /** @hidden */
+    private readonly defaultProps;
+    /** @hidden */
+    private _props;
+    /** @hidden */
+    private _onPropsUpdated;
+    constructor(defaultProps: Props, props?: Partial<Props>, options?: {
+        onPropsUpdated?: (oldProps: Props) => void;
+    });
+    /**
+     * Call if
+     */
+    triggerInitialPropsUpdate: () => void;
+    log: () => Logger | null;
+    get props(): Props;
+    set props(props: Partial<Props>);
+    setProps: (props: Partial<Props>) => void;
+    updateProps: (updates: Partial<Props>) => void;
+    /** @hidden */
+    setParent(parent: Parent | null): void;
+    /** @hidden */
+    updateTree(): void;
+    /** @hidden */
+    abstract getProtoInfo(idMap: IDMap): Proto;
+    /** @hidden */
+    handleMessage(_message: AnyClientComponentMessage, _connection: ToolkitConnection): void;
+    routeMessage(_idMap: IDMap, _message: AnyClientComponentMessage, _connection: ToolkitConnection): void;
+}
+type AnyComponent = Base<string, BaseComponentProto<string>, any>;
+/** @hidden */
+interface Parent {
+    updateTree(): void;
+    removeChild(component: AnyComponent): void;
+    log(): Logger | null;
+}
+declare abstract class BaseParent<Namespace extends string, Proto extends BaseComponentProto<Namespace>, T> extends Base<Namespace, Proto, T> implements Parent {
+    /** @hidden */
+    private children;
+    abstract validateChildren(children: AnyComponent[]): void;
+    appendChildren: <CS extends AnyComponent[]>(...children: CS) => CS;
+    appendChild: <C extends AnyComponent>(child: C) => C;
+    removeChild: (component: AnyComponent) => void;
+    removeAllChildren: () => void;
+    /**
+     * Return all children components that messages need to be routed to
+     */
+    getChildren: () => readonly AnyComponent[];
+    /**
+     * TODO: we can do this better, right now it broadcasts the message to all
+     * components of the tree
+     *
+     * @hidden
+     */
+    routeMessage(idMap: IDMap, message: AnyClientComponentMessage, connection: ToolkitConnection): void;
+    insertBefore(child: AnyComponent, beforeChild: AnyComponent): void;
+}
+interface Listenable<Map extends Record<string, (...args: any[]) => void>> {
+    addListener<T extends keyof Map>(type: T, listener: Map[T]): void;
+    removeListener<T extends keyof Map>(type: T, listener: Map[T]): void;
+}
+declare class EventEmitter<Map extends Record<string, (...args: any[]) => void>> implements Listenable<Map> {
+    private readonly listeners;
+    addListener: <T extends keyof Map>(type: T, listener: Map[T]) => void;
+    removeListener: <T extends keyof Map>(type: T, listener: Map[T]) => void;
+    emit: <T extends keyof Map>(type: T, ...args: Parameters<Map[T]>) => Promise<unknown>;
+    /**
+     * Process prop changes to update listeners
+     */
+    processPropChanges: <Mapping extends Record<string, keyof Map>, Props extends { [key in keyof Mapping]?: Map[Mapping[key]] | null | undefined; }>(mapping: Mapping, oldProps: Props, newProps: Props) => void;
+}
+
+type Events$2 = {
+    click: (connection: ToolkitConnection) => void | Promise<void>;
+};
+type ButtonMode = 'normal' | 'pressed';
+type InternalProps$1 = {
+    text: string | null;
+    icon: string | null;
+    mode: ButtonMode;
+    error: string | null;
+    onClick?: Events$2['click'] | null;
+};
+type Props$1 = Partial<InternalProps$1>;
+declare class Button extends Base<proto.CoreNamespace, proto.CoreComponent, InternalProps$1> implements Listenable<Events$2> {
+    /** @hidden */
+    private readonly events;
+    constructor(props?: Props$1);
+    addListener: <T extends "click">(type: T, listener: Events$2[T]) => void;
+    removeListener: <T extends "click">(type: T, listener: Events$2[T]) => void;
+    setText: (text: string | null) => this;
+    setIcon: (icon: string | undefined | null) => this;
+    setMode: (mode: ButtonMode) => this;
+    /** @hidden */
+    getProtoInfo: (idMap: IDMap) => proto.ButtonComponent;
+    /** @hidden */
+    handleMessage: (message: AnyClientComponentMessage, connection: ToolkitConnection) => void;
+}
+
+type Label = (proto.GroupComponent['labels'] & Array<unknown>)[number];
+type GroupOptions = {
+    editableTitle?: boolean;
+    defaultCollapsibleState?: proto.GroupComponent['defaultCollapsibleState'];
+};
+type Events$1 = {
+    'title-changed': (title: string, connection: ToolkitConnection) => void;
+};
+type InternalProps = GroupComponentStyle & GroupOptions & {
+    title: string | null;
+    labels: Label[] | null;
+    onTitleChanged?: Events$1['title-changed'];
+};
+type Props = Partial<InternalProps>;
+declare class GroupHeader extends BaseParent<proto.CoreNamespace, proto.CoreComponent, Record<never, never>> {
+    validateChildren: () => void;
+    /** @hidden */
+    getProtoInfo: (idMap: IDMap) => proto.GroupHeaderComponent;
+}
+/**
+ * A collection of components, grouped in either a row or column. Can contain
+ * further groups as children to organize components however you wish, and have
+ * a number of styling options (such as removing the border).
+ *
+ * ![](media://images/group_screenshot.png)
+ */
+declare class Group extends BaseParent<proto.CoreNamespace, proto.GroupComponent, Props> implements Listenable<Events$1> {
+    /** @hidden */
+    private readonly events;
+    constructor(props?: Props);
+    addListener: <T extends "title-changed">(type: T, listener: Events$1[T]) => void;
+    removeListener: <T extends "title-changed">(type: T, listener: Events$1[T]) => void;
+    validateChildren: () => void;
+    setOptions: (options: GroupOptions) => void;
+    setTitle: (title: string) => void;
+    addLabel: (label: Label) => void;
+    setLabels: (labels: Label[]) => void;
+    addHeaderChild: <C extends Button>(child: C) => C;
+    removeHeaderChild: (child: Button) => void;
+    removeAllHeaderChildren: () => void;
+    /** @hidden */
+    getProtoInfo: (idMap: IDMap) => proto.GroupComponent;
+    /** @hidden */
+    handleMessage: (message: AnyClientComponentMessage, connection: ToolkitConnection) => void;
+}
+
+type ToolkitConnection = {
+    uuid: string;
+};
+type Events = {
+    'new-connection': (connection: ToolkitConnection) => void;
+    'closed-connection': (connection: ToolkitConnection) => void;
+};
+declare class Toolkit implements Parent, Listenable<Events> {
+    private readonly options;
+    /**
+     * Mapping from components to unique IDs that identify them
+     */
+    private readonly componentIDMap;
+    private readonly connections;
+    private rootGroup;
+    /** @hidden */
+    private readonly events;
+    constructor(options?: Partial<ToolkitOptions>);
+    addListener: <T extends keyof Events>(type: T, listener: Events[T]) => void;
+    removeListener: <T extends keyof Events>(type: T, listener: Events[T]) => void;
+    start: (opts: InitializationOptions) => void;
+    setRoot: (group: Group) => void;
+    log(): _arcanejs_protocol_logging.Logger | null;
+    getConnections: () => ToolkitConnection[];
+    updateTree: _.DebouncedFuncLeading<() => void>;
+    removeChild: (component: AnyComponent) => void;
+    private onNewConnection;
+    private onClosedConnection;
+    private onMessage;
+}
+
+export { type AnyComponent as A, Button as B, EventEmitter as E, Group as G, type InternalProps$1 as I, type Listenable as L, type Parent as P, Toolkit as T, type ToolkitConnection as a, type ToolkitOptions as b, GroupHeader as c, Base as d, BaseParent as e, type Events$2 as f, type ButtonMode as g, type Props$1 as h, type Events$1 as i, type InternalProps as j, type Props as k };

package/dist/toolkit-DB8G2TaA.d.mts

@@ -0,0 +1,269 @@
+import * as _arcanejs_protocol_logging from '@arcanejs/protocol/logging';
+import { Logger } from '@arcanejs/protocol/logging';
+import _ from 'lodash';
+import * as http from 'http';
+import { Application } from 'express';
+import { WebSocket } from 'ws';
+import { ClientMessage, ServerMessage, BaseComponentProto, AnyClientComponentMessage } from '@arcanejs/protocol';
+import * as proto from '@arcanejs/protocol/core';
+import { GroupComponentStyle } from '@arcanejs/protocol/styles';
+import { I as IDMap } from './id-map-DxQ3_gyA.mjs';
+
+interface Connection {
+    sendMessage(msg: ServerMessage): void;
+}
+declare class Server {
+    private readonly options;
+    private readonly onNewConnection;
+    private readonly onClosedConnection;
+    private readonly onMessage;
+    private readonly log?;
+    private readonly staticFiles;
+    private readonly entrypointFilename;
+    private title;
+    constructor(options: ToolkitOptions, onNewConnection: (connection: Connection) => void, onClosedConnection: (connection: Connection) => void, onMessage: (connection: Connection, message: ClientMessage) => void, log?: Logger | undefined);
+    handleHttpRequest: (req: http.IncomingMessage, res: http.ServerResponse) => Promise<void>;
+    private sendStaticFile;
+    handleWsConnection: <S extends WebSocket>(ws: S) => void;
+}
+
+interface ToolkitOptions {
+    /**
+     * What window title should the toolkit be initialized with?
+     */
+    title?: string;
+    /**
+     * What path should be used to serve the light desk.
+     *
+     * This is important if a express server will be used that serves other paths.
+     */
+    path: string;
+    /**
+     * An optional object that can be used to output log events,
+     * we recommend using `pino` for this,
+     * as log levels etc... can be controlled.
+     *
+     * You can also always use `console` for logging,
+     * but this will be quite verbose.
+     */
+    log?: Logger;
+    /**
+     * The entrypoint file that should be used to serve the light desk.
+     *
+     * This is only needed if you have defined custom extensions,
+     * and need to load custom frontend code that includes your extensions.
+     *
+     * This will allow access to both the js file and the `.map.js` file,
+     * that matches this name.
+     */
+    entrypointJsFile?: string;
+    /**
+     * If it's not possible to automatically resolve and import the
+     * material-symbols package in node_modules
+     * (for example when bundling an electron app),
+     * you can provide the path to the material-symbols-outlined.woff2 file here.
+     */
+    materialIconsFontFile?: string;
+}
+type InitializationOptions = 
+/** automatically start a simple  */
+{
+    mode: 'automatic';
+    port: number;
+    /**
+     * Optional callback that is called when the server is ready,
+     * with the url that the server is running on.
+     */
+    onReady?: (url: string) => void;
+}
+/** Create a websocket server that attaches to an existing express and http server */
+ | {
+    mode: 'express';
+    express: Application;
+    server: http.Server;
+}
+/** Create a websocket server that attaches to an existing express and http server */
+ | {
+    mode: 'manual';
+    setup: (server: Server) => void;
+};
+
+declare abstract class Base<Namespace extends string, Proto extends BaseComponentProto<Namespace>, Props> {
+    /** @hidden */
+    private parent;
+    /** @hidden */
+    private readonly defaultProps;
+    /** @hidden */
+    private _props;
+    /** @hidden */
+    private _onPropsUpdated;
+    constructor(defaultProps: Props, props?: Partial<Props>, options?: {
+        onPropsUpdated?: (oldProps: Props) => void;
+    });
+    /**
+     * Call if
+     */
+    triggerInitialPropsUpdate: () => void;
+    log: () => Logger | null;
+    get props(): Props;
+    set props(props: Partial<Props>);
+    setProps: (props: Partial<Props>) => void;
+    updateProps: (updates: Partial<Props>) => void;
+    /** @hidden */
+    setParent(parent: Parent | null): void;
+    /** @hidden */
+    updateTree(): void;
+    /** @hidden */
+    abstract getProtoInfo(idMap: IDMap): Proto;
+    /** @hidden */
+    handleMessage(_message: AnyClientComponentMessage, _connection: ToolkitConnection): void;
+    routeMessage(_idMap: IDMap, _message: AnyClientComponentMessage, _connection: ToolkitConnection): void;
+}
+type AnyComponent = Base<string, BaseComponentProto<string>, any>;
+/** @hidden */
+interface Parent {
+    updateTree(): void;
+    removeChild(component: AnyComponent): void;
+    log(): Logger | null;
+}
+declare abstract class BaseParent<Namespace extends string, Proto extends BaseComponentProto<Namespace>, T> extends Base<Namespace, Proto, T> implements Parent {
+    /** @hidden */
+    private children;
+    abstract validateChildren(children: AnyComponent[]): void;
+    appendChildren: <CS extends AnyComponent[]>(...children: CS) => CS;
+    appendChild: <C extends AnyComponent>(child: C) => C;
+    removeChild: (component: AnyComponent) => void;
+    removeAllChildren: () => void;
+    /**
+     * Return all children components that messages need to be routed to
+     */
+    getChildren: () => readonly AnyComponent[];
+    /**
+     * TODO: we can do this better, right now it broadcasts the message to all
+     * components of the tree
+     *
+     * @hidden
+     */
+    routeMessage(idMap: IDMap, message: AnyClientComponentMessage, connection: ToolkitConnection): void;
+    insertBefore(child: AnyComponent, beforeChild: AnyComponent): void;
+}
+interface Listenable<Map extends Record<string, (...args: any[]) => void>> {
+    addListener<T extends keyof Map>(type: T, listener: Map[T]): void;
+    removeListener<T extends keyof Map>(type: T, listener: Map[T]): void;
+}
+declare class EventEmitter<Map extends Record<string, (...args: any[]) => void>> implements Listenable<Map> {
+    private readonly listeners;
+    addListener: <T extends keyof Map>(type: T, listener: Map[T]) => void;
+    removeListener: <T extends keyof Map>(type: T, listener: Map[T]) => void;
+    emit: <T extends keyof Map>(type: T, ...args: Parameters<Map[T]>) => Promise<unknown>;
+    /**
+     * Process prop changes to update listeners
+     */
+    processPropChanges: <Mapping extends Record<string, keyof Map>, Props extends { [key in keyof Mapping]?: Map[Mapping[key]] | null | undefined; }>(mapping: Mapping, oldProps: Props, newProps: Props) => void;
+}
+
+type Events$2 = {
+    click: (connection: ToolkitConnection) => void | Promise<void>;
+};
+type ButtonMode = 'normal' | 'pressed';
+type InternalProps$1 = {
+    text: string | null;
+    icon: string | null;
+    mode: ButtonMode;
+    error: string | null;
+    onClick?: Events$2['click'] | null;
+};
+type Props$1 = Partial<InternalProps$1>;
+declare class Button extends Base<proto.CoreNamespace, proto.CoreComponent, InternalProps$1> implements Listenable<Events$2> {
+    /** @hidden */
+    private readonly events;
+    constructor(props?: Props$1);
+    addListener: <T extends "click">(type: T, listener: Events$2[T]) => void;
+    removeListener: <T extends "click">(type: T, listener: Events$2[T]) => void;
+    setText: (text: string | null) => this;
+    setIcon: (icon: string | undefined | null) => this;
+    setMode: (mode: ButtonMode) => this;
+    /** @hidden */
+    getProtoInfo: (idMap: IDMap) => proto.ButtonComponent;
+    /** @hidden */
+    handleMessage: (message: AnyClientComponentMessage, connection: ToolkitConnection) => void;
+}
+
+type Label = (proto.GroupComponent['labels'] & Array<unknown>)[number];
+type GroupOptions = {
+    editableTitle?: boolean;
+    defaultCollapsibleState?: proto.GroupComponent['defaultCollapsibleState'];
+};
+type Events$1 = {
+    'title-changed': (title: string, connection: ToolkitConnection) => void;
+};
+type InternalProps = GroupComponentStyle & GroupOptions & {
+    title: string | null;
+    labels: Label[] | null;
+    onTitleChanged?: Events$1['title-changed'];
+};
+type Props = Partial<InternalProps>;
+declare class GroupHeader extends BaseParent<proto.CoreNamespace, proto.CoreComponent, Record<never, never>> {
+    validateChildren: () => void;
+    /** @hidden */
+    getProtoInfo: (idMap: IDMap) => proto.GroupHeaderComponent;
+}
+/**
+ * A collection of components, grouped in either a row or column. Can contain
+ * further groups as children to organize components however you wish, and have
+ * a number of styling options (such as removing the border).
+ *
+ * ![](media://images/group_screenshot.png)
+ */
+declare class Group extends BaseParent<proto.CoreNamespace, proto.GroupComponent, Props> implements Listenable<Events$1> {
+    /** @hidden */
+    private readonly events;
+    constructor(props?: Props);
+    addListener: <T extends "title-changed">(type: T, listener: Events$1[T]) => void;
+    removeListener: <T extends "title-changed">(type: T, listener: Events$1[T]) => void;
+    validateChildren: () => void;
+    setOptions: (options: GroupOptions) => void;
+    setTitle: (title: string) => void;
+    addLabel: (label: Label) => void;
+    setLabels: (labels: Label[]) => void;
+    addHeaderChild: <C extends Button>(child: C) => C;
+    removeHeaderChild: (child: Button) => void;
+    removeAllHeaderChildren: () => void;
+    /** @hidden */
+    getProtoInfo: (idMap: IDMap) => proto.GroupComponent;
+    /** @hidden */
+    handleMessage: (message: AnyClientComponentMessage, connection: ToolkitConnection) => void;
+}
+
+type ToolkitConnection = {
+    uuid: string;
+};
+type Events = {
+    'new-connection': (connection: ToolkitConnection) => void;
+    'closed-connection': (connection: ToolkitConnection) => void;
+};
+declare class Toolkit implements Parent, Listenable<Events> {
+    private readonly options;
+    /**
+     * Mapping from components to unique IDs that identify them
+     */
+    private readonly componentIDMap;
+    private readonly connections;
+    private rootGroup;
+    /** @hidden */
+    private readonly events;
+    constructor(options?: Partial<ToolkitOptions>);
+    addListener: <T extends keyof Events>(type: T, listener: Events[T]) => void;
+    removeListener: <T extends keyof Events>(type: T, listener: Events[T]) => void;
+    start: (opts: InitializationOptions) => void;
+    setRoot: (group: Group) => void;
+    log(): _arcanejs_protocol_logging.Logger | null;
+    getConnections: () => ToolkitConnection[];
+    updateTree: _.DebouncedFuncLeading<() => void>;
+    removeChild: (component: AnyComponent) => void;
+    private onNewConnection;
+    private onClosedConnection;
+    private onMessage;
+}
+
+export { type AnyComponent as A, Button as B, EventEmitter as E, Group as G, type InternalProps$1 as I, type Listenable as L, type Parent as P, Toolkit as T, type ToolkitConnection as a, type ToolkitOptions as b, GroupHeader as c, Base as d, BaseParent as e, type Events$2 as f, type ButtonMode as g, type Props$1 as h, type Events$1 as i, type InternalProps as j, type Props as k };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcanejs/toolkit",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "private": false,
   "description": "Build web-accessible control interfaces for your long-running Node.js processes",
   "keywords": [
@@ -115,23 +115,24 @@
     "tsup": "^8.1.0",
     "typescript": "^5.3.3",
     "@arcanejs/eslint-config": "^0.0.0",
-    "@arcanejs/typescript-config": "^0.0.0",
-    "@arcanejs/toolkit-frontend": "^0.3.1"
+    "@arcanejs/toolkit-frontend": "^0.4.0",
+    "@arcanejs/typescript-config": "^0.0.0"
   },
   "dependencies": {
     "escape-html": "^1.0.3",
     "express": "^4.21.1",
     "lodash": "^4.17.21",
     "material-symbols": "^0.25.0",
+    "uuid": "^11.0.3",
     "ws": "^8.18.0",
     "@arcanejs/diff": "^0.5.1",
-    "@arcanejs/protocol": "^0.4.1"
+    "@arcanejs/protocol": "^0.5.0"
   },
   "peerDependencies": {
     "react": "^18",
     "react-dom": "18.3.1",
     "styled-components": "^6.1.13",
-    "@arcanejs/toolkit-frontend": "^0.3.1"
+    "@arcanejs/toolkit-frontend": "^0.4.0"
   },
   "peerDependenciesMeta": {
     "@arcanejs/toolkit-frontend": {