@arcanejs/toolkit-frontend 0.9.0 → 0.11.0

package/README.md

@@ -1,43 +1,144 @@
-# `@arcanejs/diff`
+# `@arcanejs/toolkit-frontend`
 
-[![NPM Version](https://img.shields.io/npm/v/%40arcanejs%2Fdiff)](https://www.npmjs.com/package/@arcanejs/diff)
+[![NPM Version](https://img.shields.io/npm/v/%40arcanejs%2Ftoolkit-frontend)](https://www.npmjs.com/package/@arcanejs/toolkit-frontend)
 
-This package provides an easy way to:
+Browser-side renderer components and stage utilities for ArcaneJS.
 
-- Create diffs by comparing objects
-- Update objects by applying diffs
+This package is used by `@arcanejs/toolkit`'s default frontend bundle, and can also be used directly when building custom frontend entrypoints for custom component namespaces.
 
-This library is written in TypeScript,
-and produces diffs that are type-safe,
-and can only be applied to objects that match the type
-of the objects being compared.
+## Install
 
-This package is part of the
-[`arcanejs` project](https://github.com/ArcaneWizards/arcanejs#arcanejs),
-and is used to maintain a copy of a JSON tree in downstream clients in real-time
-via websockets.
+```bash
+npm install @arcanejs/toolkit-frontend
+```
+
+Peer ecosystem typically used with this package:
+
+- `react@^19.2.0`
+- `react-dom@^19.2.0`
+- `@arcanejs/protocol`
+
+## What It Provides
+
+- Core frontend renderer: `CORE_FRONTEND_COMPONENT_RENDERER`
+- Core UI components (`Button`, `Group`, `Switch`, `Tabs`, etc.)
+- Stage context and connection state (`StageContext`)
+- Theme root wrapper (`ThemeRoot`)
+- Touch/mouse interaction helpers (`usePressable`, `trackTouch`, `initialiseListeners`)
+- Precompiled core component stylesheet (`@arcanejs/toolkit-frontend/styles/core.css`)
+- Default theme variables stylesheet (`@arcanejs/toolkit-frontend/styles/theme.css`)
+- Tailwind base stylesheet for custom utility generation (`@arcanejs/toolkit-frontend/styles/base.css`)
+
+## Public Exports
+
+### `@arcanejs/toolkit-frontend`
+
+- `CORE_FRONTEND_COMPONENT_RENDERER`
+- Component exports: `Button`, `Group`, `GroupStateWrapper`, `Label`, `NestedContent`, `Rect`, `SliderButton`, `Switch`, `Tabs`, `TextInput`, `Timeline`
+- `StageContext`
+- Types: `StageContextData`, `StageConnectionState`
+- `code` namespace re-export (`core` helpers such as `Icon`, transparency SVG constants)
+
+### `@arcanejs/toolkit-frontend/components/core`
+
+- `Icon`
+- `TRANSPARENCY_SVG`
+- `TRANSPARENCY_SVG_URI`
+
+### `@arcanejs/toolkit-frontend/styling`
+
+- `ThemeRoot`
+
+### `@arcanejs/toolkit-frontend/styles`
+
+- `CORE_STYLE_PATH`
+- `THEME_STYLE_PATH`
+- `BASE_STYLE_PATH`
+
+### `@arcanejs/toolkit-frontend/styles/core.css`
+
+- Tailwind-generated core Arcane component classes and shared global rules
+- Excludes default theme variable values
+
+### `@arcanejs/toolkit-frontend/styles/theme.css`
+
+- Default Arcane theme variable values (`.arcane-theme-root`, dark mode, and `prefers-color-scheme` behavior)
+
+### `@arcanejs/toolkit-frontend/styles/base.css`
 
-## Usage
+- Tailwind source stylesheet for custom builds
+- Provides Arcane `@theme` token mappings and Tailwind utility generation entrypoint for custom component classes
 
-```ts
-import { diffJson, Diff } from '@arcanejs/diff/diff';
-import { patchJson } from '@arcanejs/diff/patch';
+### `@arcanejs/toolkit-frontend/types`
 
-type E = {
-  foo: string;
-  bar?: number[];
-};
+- `FrontendComponentRenderer`
+- `FrontendComponentRenderers`
 
-const a: E = { foo: 'bar' };
-const b: E = { foo: 'baz', bar: [1] };
+### `@arcanejs/toolkit-frontend/util`
 
-const diffA: Diff<E> = diffJson(a, b);
+- `calculateClass`
+- touch helpers: `initialiseListeners`, `usePressable`, `trackTouch`, etc.
+- theme preference hooks: `useColorSchemePreferences`, `usePreferredColorScheme`
+- `VALID_COLOR_SCHEME_PREFS`
 
-const resultA = patchJson(a, diffA);
+## Typical Usage
 
-console.log(resultB); // { foo: 'baz', bar: [1] }
+In most apps you will not call this package directly; `@arcanejs/toolkit` serves a prebuilt frontend entrypoint.
 
-const c = { baz: 'foo' };
+Use this package directly when you provide your own frontend bundle for custom namespaces:
 
-const resultB = patchJson(c, diffA); // TypeScript Type Error: Property 'baz' is missing in type '{ foo: string; bar?: number[] | undefined; }' but required in type '{ baz: string; }'
+```tsx
+import '@arcanejs/toolkit-frontend/styles/core.css';
+import '@arcanejs/toolkit-frontend/styles/theme.css';
+import { startArcaneFrontend } from '@arcanejs/toolkit/frontend';
+import { CORE_FRONTEND_COMPONENT_RENDERER } from '@arcanejs/toolkit-frontend';
+
+startArcaneFrontend({
+  renderers: [CORE_FRONTEND_COMPONENT_RENDERER, customRenderer],
+});
 ```
+
+For default core frontend styling, import both:
+
+- `@arcanejs/toolkit-frontend/styles/core.css`
+- `@arcanejs/toolkit-frontend/styles/theme.css`
+
+If you compile your own stylesheet with Tailwind (for example to generate utilities used by custom component `className`s), import `@arcanejs/toolkit-frontend/styles/base.css` in your Tailwind input file.
+
+Common CSS import combinations:
+
+- Core components + default theme: `core.css` + `theme.css`
+- Core components + custom theme: `core.css` (plus your own theme variable overrides)
+- Custom components (Tailwind) + default theme: `base.css` + `theme.css`
+- Core components + custom components (Tailwind) + default theme: `core.css` + `base.css` + `theme.css`
+
+`startArcaneFrontend` supports:
+
+- `themeRootProps?: React.HTMLAttributes<HTMLDivElement>`: props for the root theme container.
+
+Theme switching is class-based (`theme-auto`, `theme-dark`, `theme-light`) and managed internally from `useColorSchemePreferences`; theme customization should be done in CSS by overriding Arcane variables on `.arcane-theme-root` for those classes.
+
+## Stage Context
+
+`StageContext` provides browser-side runtime hooks for custom renderers:
+
+- `sendMessage(...)`: fire-and-forget component messages
+- `call(...)`: request/response component calls
+- `renderComponent(...)`: render nested protocol components
+- `connection`, `connectionUuid`, `reconnect()`
+- `timeDifferenceMs`: estimated `browserTime - serverTime` in milliseconds (only when toolkit clock sync is enabled)
+- `lastPingMs`: latest ping round-trip time in milliseconds
+
+## When To Use This Package
+
+Use `@arcanejs/toolkit-frontend` if you are:
+
+- creating custom frontend renderers for non-core namespaces
+- customizing ArcaneJS theme/styling behavior
+- implementing browser-side interaction behavior integrated with Arcane stage context
+
+If you only need server-side panel composition, use `@arcanejs/react-toolkit` and the default toolkit frontend.
+
+## Example
+
+- Custom frontend entrypoint example: <https://github.com/ArcaneWizards/arcanejs/blob/main/examples/custom-components/src/frontend.tsx>

package/dist/chunk-7P6ASYW6.mjs

@@ -0,0 +1,9 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export {
+  __export
+};

package/dist/{chunk-UHFE2X4V.js → chunk-BBUHASWZ.js}

@@ -1,37 +1,39 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
+var _chunkR7E6SIN6js = require('./chunk-R7E6SIN6.js');
 
-var _chunkTMN35K5Yjs = require('./chunk-TMN35K5Y.js');
+
+var _chunkMLKGABMKjs = require('./chunk-MLKGABMK.js');
 
 // src/components/core/index.ts
 var core_exports = {};
-_chunkTMN35K5Yjs.__export.call(void 0, core_exports, {
+_chunkMLKGABMKjs.__export.call(void 0, core_exports, {
   Icon: () => Icon,
   TRANSPARENCY_SVG: () => TRANSPARENCY_SVG,
   TRANSPARENCY_SVG_URI: () => TRANSPARENCY_SVG_URI
 });
 
 // src/components/core/icon.tsx
-var _styledcomponents = require('styled-components');
 var _jsxruntime = require('react/jsx-runtime');
-var ICON_CLASS = "icon";
-var Span = _styledcomponents.styled.span`
-  font-family: 'Material Symbols Outlined';
-  font-weight: normal;
-  font-style: normal;
-  font-size: 22px;
-  display: inline-block;
-  line-height: 1;
-  text-transform: none;
-  letter-spacing: normal;
-  word-wrap: normal;
-  white-space: nowrap;
-  direction: ltr;
-  font-variation-settings:
-    'wght' 300,
-    'GRAD' -25;
-`;
-var Icon = ({ icon, ...props }) => /* @__PURE__ */ _jsxruntime.jsx.call(void 0, Span, { className: _chunkTMN35K5Yjs.calculateClass.call(void 0, props.className, ICON_CLASS), ...props, children: icon });
+var Icon = ({
+  icon,
+  className,
+  ...props
+}) => /* @__PURE__ */ _jsxruntime.jsx.call(void 0, 
+  "span",
+  {
+    className: _chunkR7E6SIN6js.cn.call(void 0, 
+      `
+        inline-block text-arcane-icon leading-none font-normal tracking-normal
+        whitespace-nowrap
+      `,
+      "font-arcane-icon",
+      className
+    ),
+    ...props,
+    children: icon
+  }
+);
 
 // src/components/core/index.ts
 var TRANSPARENCY_SVG = `

package/dist/{chunk-GMPDVDSW.mjs → chunk-DK4BAXVE.mjs}

@@ -1,7 +1,9 @@
 import {
-  __export,
-  calculateClass
-} from "./chunk-PTANIWKR.mjs";
+  cn
+} from "./chunk-SNIL7DDI.mjs";
+import {
+  __export
+} from "./chunk-7P6ASYW6.mjs";
 
 // src/components/core/index.ts
 var core_exports = {};
@@ -12,26 +14,26 @@ __export(core_exports, {
 });
 
 // src/components/core/icon.tsx
-import { styled } from "styled-components";
 import { jsx } from "react/jsx-runtime";
-var ICON_CLASS = "icon";
-var Span = styled.span`
-  font-family: 'Material Symbols Outlined';
-  font-weight: normal;
-  font-style: normal;
-  font-size: 22px;
-  display: inline-block;
-  line-height: 1;
-  text-transform: none;
-  letter-spacing: normal;
-  word-wrap: normal;
-  white-space: nowrap;
-  direction: ltr;
-  font-variation-settings:
-    'wght' 300,
-    'GRAD' -25;
-`;
-var Icon = ({ icon, ...props }) => /* @__PURE__ */ jsx(Span, { className: calculateClass(props.className, ICON_CLASS), ...props, children: icon });
+var Icon = ({
+  icon,
+  className,
+  ...props
+}) => /* @__PURE__ */ jsx(
+  "span",
+  {
+    className: cn(
+      `
+        inline-block text-arcane-icon leading-none font-normal tracking-normal
+        whitespace-nowrap
+      `,
+      "font-arcane-icon",
+      className
+    ),
+    ...props,
+    children: icon
+  }
+);
 
 // src/components/core/index.ts
 var TRANSPARENCY_SVG = `

package/dist/chunk-MLKGABMK.js

@@ -0,0 +1,9 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+
+
+exports.__export = __export;

package/dist/{chunk-TMN35K5Y.js → chunk-R7E6SIN6.js}

@@ -1,11 +1,7 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-
-// src/util/index.ts
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});// src/util/index.ts
 var _react = require('react');
+var _clsx = require('clsx');
+var _tailwindmerge = require('tailwind-merge');
 
 // src/util/touch.ts
 
@@ -41,12 +37,49 @@ var usePressable = (click) => {
         if (touching) {
           event.preventDefault();
           setTouching(false);
-          click();
+          click(event);
         }
       }
     }
   };
 };
+var useLongPressable = ({
+  onPress,
+  onRelease
+}) => {
+  const [touching, setTouching] = _react.useState.call(void 0, false);
+  return _react.useMemo.call(void 0, 
+    () => ({
+      touching,
+      handlers: {
+        onTouchStart: (e) => {
+          setTouching(true);
+          onPress(e);
+        },
+        onMouseDown: (e) => {
+          setTouching(true);
+          onPress(e);
+        },
+        onMouseUp: (e) => {
+          setTouching(false);
+          onRelease(e);
+        },
+        onTouchMove: (e) => {
+          setTouching(false);
+          onRelease(e);
+        },
+        onTouchEnd: (event) => {
+          if (touching) {
+            event.preventDefault();
+            setTouching(false);
+            onRelease(event);
+          }
+        }
+      }
+    }),
+    [touching, onRelease, onPress]
+  );
+};
 function trackTouch(touch, move, end) {
   const touchMove = (ev) => {
     ev.preventDefault();
@@ -72,7 +105,8 @@ function trackTouch(touch, move, end) {
 }
 
 // src/util/index.ts
-var calculateClass = (...args) => args.filter((a) => !!a).join(" ");
+var cn = (...args) => _tailwindmerge.twMerge.call(void 0, _clsx.clsx.call(void 0, args));
+var calculateClass = cn;
 var COLOR_SCHEME_SETTINGS = "arcane-color-scheme-preference";
 var VALID_COLOR_SCHEME_PREFS = ["auto", "dark", "light"];
 var isValidColorSchemePreference = (value) => {
@@ -152,4 +186,5 @@ var usePreferredColorScheme = () => {
 
 
 
-exports.__export = __export; exports.switchToMouseMode = switchToMouseMode; exports.switchToTouchMode = switchToTouchMode; exports.initialiseListeners = initialiseListeners; exports.usePressable = usePressable; exports.trackTouch = trackTouch; exports.calculateClass = calculateClass; exports.VALID_COLOR_SCHEME_PREFS = VALID_COLOR_SCHEME_PREFS; exports.useColorSchemePreferences = useColorSchemePreferences; exports.usePreferredColorScheme = usePreferredColorScheme;
+
+exports.switchToMouseMode = switchToMouseMode; exports.switchToTouchMode = switchToTouchMode; exports.initialiseListeners = initialiseListeners; exports.usePressable = usePressable; exports.useLongPressable = useLongPressable; exports.trackTouch = trackTouch; exports.cn = cn; exports.calculateClass = calculateClass; exports.VALID_COLOR_SCHEME_PREFS = VALID_COLOR_SCHEME_PREFS; exports.useColorSchemePreferences = useColorSchemePreferences; exports.usePreferredColorScheme = usePreferredColorScheme;

package/dist/{chunk-PTANIWKR.mjs → chunk-SNIL7DDI.mjs}

@@ -1,14 +1,10 @@
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-
 // src/util/index.ts
 import { useEffect, useState as useState2 } from "react";
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
 
 // src/util/touch.ts
-import { useState } from "react";
+import { useMemo, useState } from "react";
 function switchToMouseMode(ev) {
   if (ev.movementX === 0 && ev.movementY === 0) return;
   document.body.classList.remove("touch-mode");
@@ -41,12 +37,49 @@ var usePressable = (click) => {
         if (touching) {
           event.preventDefault();
           setTouching(false);
-          click();
+          click(event);
         }
       }
     }
   };
 };
+var useLongPressable = ({
+  onPress,
+  onRelease
+}) => {
+  const [touching, setTouching] = useState(false);
+  return useMemo(
+    () => ({
+      touching,
+      handlers: {
+        onTouchStart: (e) => {
+          setTouching(true);
+          onPress(e);
+        },
+        onMouseDown: (e) => {
+          setTouching(true);
+          onPress(e);
+        },
+        onMouseUp: (e) => {
+          setTouching(false);
+          onRelease(e);
+        },
+        onTouchMove: (e) => {
+          setTouching(false);
+          onRelease(e);
+        },
+        onTouchEnd: (event) => {
+          if (touching) {
+            event.preventDefault();
+            setTouching(false);
+            onRelease(event);
+          }
+        }
+      }
+    }),
+    [touching, onRelease, onPress]
+  );
+};
 function trackTouch(touch, move, end) {
   const touchMove = (ev) => {
     ev.preventDefault();
@@ -72,7 +105,8 @@ function trackTouch(touch, move, end) {
 }
 
 // src/util/index.ts
-var calculateClass = (...args) => args.filter((a) => !!a).join(" ");
+var cn = (...args) => twMerge(clsx(args));
+var calculateClass = cn;
 var COLOR_SCHEME_SETTINGS = "arcane-color-scheme-preference";
 var VALID_COLOR_SCHEME_PREFS = ["auto", "dark", "light"];
 var isValidColorSchemePreference = (value) => {
@@ -142,12 +176,13 @@ var usePreferredColorScheme = () => {
 };
 
 export {
-  __export,
   switchToMouseMode,
   switchToTouchMode,
   initialiseListeners,
   usePressable,
+  useLongPressable,
   trackTouch,
+  cn,
   calculateClass,
   VALID_COLOR_SCHEME_PREFS,
   useColorSchemePreferences,

package/dist/components/core/index.js

@@ -2,10 +2,11 @@
 
 
 
-var _chunkUHFE2X4Vjs = require('../../chunk-UHFE2X4V.js');
-require('../../chunk-TMN35K5Y.js');
+var _chunkBBUHASWZjs = require('../../chunk-BBUHASWZ.js');
+require('../../chunk-R7E6SIN6.js');
+require('../../chunk-MLKGABMK.js');
 
 
 
 
-exports.Icon = _chunkUHFE2X4Vjs.Icon; exports.TRANSPARENCY_SVG = _chunkUHFE2X4Vjs.TRANSPARENCY_SVG; exports.TRANSPARENCY_SVG_URI = _chunkUHFE2X4Vjs.TRANSPARENCY_SVG_URI;
+exports.Icon = _chunkBBUHASWZjs.Icon; exports.TRANSPARENCY_SVG = _chunkBBUHASWZjs.TRANSPARENCY_SVG; exports.TRANSPARENCY_SVG_URI = _chunkBBUHASWZjs.TRANSPARENCY_SVG_URI;

package/dist/components/core/index.mjs

@@ -2,8 +2,9 @@ import {
   Icon,
   TRANSPARENCY_SVG,
   TRANSPARENCY_SVG_URI
-} from "../../chunk-GMPDVDSW.mjs";
-import "../../chunk-PTANIWKR.mjs";
+} from "../../chunk-DK4BAXVE.mjs";
+import "../../chunk-SNIL7DDI.mjs";
+import "../../chunk-7P6ASYW6.mjs";
 export {
   Icon,
   TRANSPARENCY_SVG,

package/dist/components/index.d.mts

@@ -1,6 +1,6 @@
 export { i as code } from '../index-Db4cPoyC.mjs';
 import * as React from 'react';
-import React__default, { FC } from 'react';
+import React__default, { FC, ReactElement, ReactNode } from 'react';
 import * as proto from '@arcanejs/protocol/core';
 import * as proto$1 from '@arcanejs/protocol';
 import { FrontendComponentRenderer } from '../types.mjs';
@@ -9,7 +9,7 @@ interface Props$8 {
     className?: string;
     info: proto.ButtonComponent;
 }
-declare const StyledButton: FC<Props$8>;
+declare const Button: FC<Props$8>;
 
 type StageConnectionState = {
     state: 'connecting' | 'closed';
@@ -23,9 +23,15 @@ type StageConnectionState = {
 type StageContextData = {
     sendMessage: (<M extends proto$1.AnyClientComponentMessage>(msg: M) => void) | null;
     call: (<Namespace extends string, P, Action extends string & keyof P>(msg: proto$1.CallForPair<Namespace, P, Action>) => Promise<proto$1.ReturnForPair<P, Action>>) | null;
-    renderComponent: (info: proto$1.AnyComponentProto) => JSX.Element;
+    renderComponent: (info: proto$1.AnyComponentProto) => ReactElement;
     connectionUuid: string | null;
     connection: StageConnectionState;
+    /**
+     * Estimated offset in milliseconds for how far ahead of the server clock
+     * the client clock is.
+     */
+    timeDifferenceMs: number | null;
+    lastPingMs: number | null;
     reconnect: () => void;
 };
 declare const StageContext: React.Context<StageContextData>;
@@ -39,21 +45,21 @@ declare const GroupStateWrapper: React__default.FunctionComponent<{
      * Whether new groups using `auto` should be open by default.
      */
     openByDefault: boolean;
-    children: JSX.Element | JSX.Element[];
+    children: ReactNode;
 }>;
-declare const StyledGroup: FC<Props$7>;
+declare const Group: FC<Props$7>;
 
 interface Props$6 {
     className?: string;
     info: proto.LabelComponent;
 }
-declare const StyledLabel: FC<Props$6>;
+declare const Label: FC<Props$6>;
 
 type NestContentProps = {
     className?: string;
-    children?: JSX.Element | JSX.Element[];
+    children?: ReactNode;
 };
-declare const StyledNestedContent: FC<NestContentProps>;
+declare const NestedContent: FC<NestContentProps>;
 
 interface Props$5 {
     className?: string;
@@ -65,13 +71,13 @@ interface Props$4 {
     className?: string;
     info: proto.SliderButtonComponent;
 }
-declare const StyledSliderButton: FC<Props$4>;
+declare const SliderButton: FC<Props$4>;
 
 interface Props$3 {
     className?: string;
     info: proto.SwitchComponent;
 }
-declare const StyledSwitch: FC<Props$3>;
+declare const Switch: FC<Props$3>;
 
 interface Props$2 {
     info: proto.TabsComponent;
@@ -82,7 +88,7 @@ interface Props$1 {
     className?: string;
     info: proto.TextInputComponent;
 }
-declare const StyledTextInput: FC<Props$1>;
+declare const TextInput: FC<Props$1>;
 
 interface Props {
     className?: string;
@@ -92,4 +98,4 @@ declare const Timeline: FC<Props>;
 
 declare const CORE_FRONTEND_COMPONENT_RENDERER: FrontendComponentRenderer;
 
-export { StyledButton as Button, CORE_FRONTEND_COMPONENT_RENDERER, StyledGroup as Group, GroupStateWrapper, StyledLabel as Label, StyledNestedContent as NestedContent, Rect, StyledSliderButton as SliderButton, type StageConnectionState, StageContext, type StageContextData, StyledSwitch as Switch, Tabs, StyledTextInput as TextInput, Timeline };
+export { Button, CORE_FRONTEND_COMPONENT_RENDERER, Group, GroupStateWrapper, Label, NestedContent, Rect, SliderButton, type StageConnectionState, StageContext, type StageContextData, Switch, Tabs, TextInput, Timeline };