tosijs 1.0.3

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2022, Tonio Loewald
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,385 @@
+# tosijs
+
+<!--{ "pin": "top" }-->
+
+> `tosijs` is being renamed `tosijs`. This is a work-in-progress.
+
+[tosijs.net](https://tosijs.net) | [tosijs-ui](https://ui.tosijs.net) | [github](https://github.com/tonioloewald/tosijs) | [npm](https://www.npmjs.com/package/tosijs) | [cdn](https://www.jsdelivr.com/package/npm/tosijs) | [react-tosijs](https://github.com/tonioloewald/react-tosijs#readme) | [discord](https://discord.gg/ramJ9rgky5)
+
+[![tosijs is on NPM](https://badge.fury.io/js/tosijs.svg)](https://www.npmjs.com/package/tosijs)
+[![tosijs is about 10kB gzipped](https://deno.bundlejs.com/?q=tosijs&badge=)](https://bundlejs.com/?q=tosijs&badge=)
+[![tosijs on jsdelivr](https://data.jsdelivr.com/v1/package/npm/tosijs/badge)](https://www.jsdelivr.com/package/npm/tosijs)
+
+<div style="text-align: center; margin: 20px">
+  <img style="width: 250px; max-width: 80%" class="logo" alt="tosijs logo" src="https://tosijs.net/favicon.svg">
+</div>
+
+> For a pretty thorough overview of tosijs, you might like to start with [What is tosijs?](https://loewald.com/blog/2025/6/4/what-is-tosijs-).
+> To understand the thinking behind tosijs, there's [What should a front-end framework do?](https://loewald.com/blog/2025/6/4/what-should-a-front-end-framework-do).
+
+### Build UIs with less code
+
+If you want to build a web-application that's performant, robust, and maintainable,
+`tosijs` lets you:
+
+- build user-interfaces with pure javascript/typescript—no JSX, complex tooling, or spooky action-at-a-distance
+- manage application state almost effortlessly—eliminate most binding code
+- written in Typescript, Javascript-friendly
+- use web-components, build your own web-components quickly and easily
+- manage CSS efficiently and flexibly using CSS variables and Color computations
+- leverage existing business logic and libraries without complex wrappers
+
+```js
+const { elements, tosi, touch } = tosijs
+
+const todo = {
+  list: [],
+  addItem(reminder) {
+    if (reminder.trim()) {
+      todo.list.push(reminder)
+    }
+  }
+}
+
+const { readmeTodoDemo } = tosi({ readmeTodoDemo: todo })
+
+const { h4, ul, template, li, label, input } = elements
+preview.append(
+  h4('To Do List'),
+  ul(
+    {
+      bindList: {
+        value: readmeTodoDemo.list
+      }
+    },
+    template(li({ bindText: '^' }))
+  ),
+  label(
+    'Reminder',
+    input({ 
+      placeholder: 'enter a reminder',
+      onKeydown(event) {
+        if (event.key === 'Enter') {
+          event.preventDefault()
+          readmeTodoDemo.addItem(event.target.value.trim())
+          event.target.value = ''
+          touch(readmeTodoDemo)
+        }
+      }
+    })
+  )
+)
+```
+
+In general, `tosijs` is able to accomplish the same or better compactness, expressiveness,
+and simplicity as you get with highly-refined React-centric toolchains, but without transpilation,
+domain-specific-languages, or other tricks that provide "convenience" at the cost of becoming locked-in
+to React, a specific state-management system (which permeates your business logic), and usually a specific UI framework.
+
+`tosijs` lets you work with pure HTML and web-component as cleanly—more cleanly—and efficiently than
+React toolchains let you work with JSX.
+
+    export default function App() {
+      return (
+        <div className="App">
+          <h1>Hello React</h1>
+          <h2>Start editing to see some magic happen!</h2>
+        </div>
+      );
+    }
+
+Becomes:
+
+    const { div, h1, h2 } = elements // exported from tosijs
+    export const App = () => div(
+      { class: 'App' },
+      h1('Hello tosijs'),
+      h2('Start editing to see some magic happen!')
+    )
+
+Except this reusable component outputs native DOM nodes. No transpilation, spooky magic at a distance,
+or virtual DOM required. And it all works just as well with web-components. This is you get when
+you run App() in the console:
+
+    ▼ <div class="App">
+        <h1>Hello tosijs</h1>
+        <h2>Start editing to see some magic happen!</h2>
+      </div>
+
+The ▼ is there to show that's **DOM nodes**, not HTML.
+
+`tosijs` lets you lean into web-standards and native browser functionality while writing less code that's
+easier to run, debug, deploy, and maintain. Bind data direct to standard input elements—without having
+to fight their basic behavior—and now you're using _native_ functionality with _deep accessibility_ support
+as opposed to whatever the folks who wrote the library you're using have gotten around to implementing.
+
+> **Aside**: `tosijs` will also probably work perfectly well with `Angular`, `Vue`, et al, but I haven't
+> bothered digging into it and don't want to deal with `ngZone` stuff unless someone is paying
+> me.
+
+If you want to build your own `web-components` versus use something off-the-rack like
+[Shoelace](https://shoelace.style), `tosijs` offers a `Component` base class that, along with
+its `elements` and `css` libraries allows you to implement component views in pure Javascript
+more compactly than with `jsx` (and without a virtual DOM).
+
+    import { Component, elements, css } from 'tosijs'
+
+    const { style, h1, slot } = elements
+    export class MyComponent extends Component {
+      styleNode = style(css({
+        h1: {
+          color: 'blue'
+        }
+      }))
+      content = [ h1('hello world'), slot() ]
+    }
+
+The difference is that `web-components` are drop-in replacements for standard HTML elements
+and interoperate happily with one-another and other libraries, load asynchronously,
+and are natively supported by all modern browsers.
+
+## What `tosijs` does
+
+### Observe Object State
+
+`tosijs` tracks the state of objects you assign to it using `paths` allowing economical
+and direct updates to application state.
+
+    import { xinProxy, observe } from 'tosijs'
+
+    const { app } = xinProxy({
+      app: {
+        prefs: {
+          darkmode: false
+        },
+        docs: [
+          {
+            id: 1234,
+            title: 'title',
+            body: 'markdown goes here'
+          }
+        ]
+      }
+    })
+
+    observe('app.prefs.darkmode', () => {
+      document.body.classList.toggle('dark-mode', app.prefs.darkmode)
+    })
+
+    observe('app.docs', () => {
+      // render docs
+    })
+
+> #### What does `xinProxy` do, and what is a `XinProxy`?
+>
+> `xinProxy` is syntax sugar for assigning something to `xin` (which is a `XinProxyObject`)
+> and then getting it back out again.
+>
+> A `XinProxy` is an [ES Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
+> wrapped around an `object` (which in Javascript means anything
+> that has a `constructor` which in particular includes `Array`s, `class` instances, `function`s
+> and so on, but not "scalars" like `number`s, `string`s, `boolean`s, `null`, and `undefined`)
+>
+> All you need to know about a `XinProxy` is that it's Proxy wrapped around your original
+> object that allows you to interact with the object normally, but which allows `tosijs` to
+> **observe** changes made to the wrapped object and tell interested parties about the changes.
+>
+> If you want to original object back you can just hold on to a reference or use `xinValue(someProxy)`
+> to unwrap it.
+
+### No Tax, No Packaging
+
+`tosijs` does not modify the stuff you hand over to it… it just wraps objects
+with a `Proxy` and then if you use `xin` to make changes to those objects,
+`tosijs` will notify any interested observers.
+
+**Note** `xinProxy({foo: {...}})` is syntax sugar for `xin.foo = {...}`.
+
+    import { xinProxy, observe } from 'tosijs'
+    const { foo } = xinProxy({
+      foo: {
+        bar: 17
+      }
+    })
+
+    observe('foo.bar', v => {
+      console.log('foo.bar was changed to', xin.foo.bar)
+    })
+
+    foo.bar = 17        // does not trigger the observer
+    foo.bar = Math.PI   // triggers the observer
+
+### Paths are like JavaScript
+
+`xin` is designed to behave just like a JavaScript `Object`. What you put
+into it is what you get out of it:
+
+    import { xin, xinValue } from 'tosijs'
+
+    const foo = {bar: 'baz'}
+    xin.foo = foo
+
+    // xin.foo returns a Proxy wrapped around foo (without touching foo)
+    xinValue(xin.foo) === foo
+
+    // really, it's just the original object
+    xin.foo.bar = 'lurman'
+    foo.bar === 'lurman' // true
+
+    // seriously, it's just the original object
+    foo.bar = 'luhrman'
+    xin.foo.bar === 'luhrman' // true
+
+### …but better!
+
+It's very common to deal with arrays of objects that have unique id values,
+so `tosijs` supports the idea of id-paths
+
+    import { xinProxy, xin } from 'tosijs
+
+    const { app } = xinProxy ({
+      app: {
+        list: [
+          {
+            id: '1234abcd',
+            text: 'hello world'
+          },
+          {
+            id: '5678efgh',
+            text: 'so long, redux'
+          }
+        ]
+      }
+    })
+
+    console.log(app.list[0].text)              // hello world
+    console.log(app.list['id=5678efgh'])       // so long, redux
+    console.log(xin['app.list[id=1234abcd'])   // hello world
+
+### Telling `xin` about changes using `touch()`
+
+Sometimes you will modify an object behind `xin`'s back (e.g. for efficiency).
+When you want to trigger updates, simply touch the path.
+
+    import { xin, observe, touch } from 'tosijs'
+
+    const foo = { bar: 17 }
+    xin.foo = foo
+    observe('foo.bar', path => console.log(path, '->', xin[path])
+    xin.foo.bar = -2              // console will show: foo.bar -> -2
+
+    foo.bar = 100                 // nothing happens
+    touch('foo.bar')              // console will show: foo.bar -> 100
+
+### CSS
+
+`tosijs` includes utilities for working with css.
+
+    import {css, vars, initVars, darkMode} from 'tosijs'
+    const cssVars = {
+      textFont: 'sans-serif'
+      color: '#111'
+    }
+
+`initVars()` processes an object changing its keys from camelCase to --kabob-case:
+
+    initVars(cssVars) // emits { --text-font: "sans-serif", --color: "#111" }
+
+`darkMode()` processes an object, taking only the color properties and inverting their luminance values:
+darkMode(cssVars) // emits { color: '#ededed' }
+
+The `vars` simply converts its camelCase properties into css variable references
+
+    vars.fooBar // emits 'var(--foo-bar)'
+    calc(`${vars.width} + 2 * ${vars.spacing}`) // emits 'calc(var(--width) + 2 * var(--spacing))'
+
+`css()` processes an object, rendering it as CSS
+
+    css({
+      '.container': {
+        'position', 'relative'
+      }
+    }) // emits .container { position: relative; }
+
+## Color
+
+`tosijs` includes a powerful `Color` class for manipulating colors.
+
+    import {Color} from 'tosijs
+    const translucentBlue = new Color(0, 0, 255, 0.5) // r, g, b, a parameters
+    const postItBackground = Color.fromCss('#e7e79d')
+    const darkGrey = Color.fromHsl(0, 0, 0.2)
+
+The color objects have computed properties for rendering the color in different ways,
+making adjustments, blending colors, and so forth.
+
+## Hot Reload
+
+One of the nice things about working with the React toolchain is hot reloading.
+`tosijs` supports hot reloading (and not just in development!) via the `hotReload()`
+function:
+
+    import {xin, hotReload} from 'tosijs'
+
+    xin.app = {
+      ...
+    }
+
+    hotReload()
+
+`hotReload` stores serializable state managed by `xin` in localStorage and restores
+it (by overlay) on reload. Because any functions (for example) won't be persisted,
+simply call `hotReload` after initializing your app state and you're good to go.
+
+`hotReload` accepts a test function (path => boolean) as a parameter.
+Only top-level properties in `xin` that pass the test will be persisted.
+
+To completely reset the app, run `localStorage.clear()` in the console.
+
+### Types
+
+`tosijs` [type-by-example](https://www.npmjs.com/package/type-by-example) has been
+broken out into a separate standalone library. (Naturally it works very well with
+tosijs but they are completely independent.)
+
+## Development Notes
+
+You'll need to install [bun](https://bun.sh/) and [nodejs](https://nodejs.org)),
+and then run `npm install` and `bun install`. `bun` is used because it's
+**fast** and is a really nice test-runner.
+
+To work interactively on the demo code, use `bun start`. This runs the demo
+site on localhost.
+
+To build everything run `bun run make` which builds production versions of the
+demo site (in `www`) and the `dist` and `cdn` directories.
+
+To create a local package (for experimenting with a build) run `bun pack`.
+
+### Parcel Occasionally Gets Screwed Up
+
+- remove all the parcel transformer dependencies @parcel/\*
+- rm -rf node_modules
+- run the update script
+- npx parcel build (which restores needed parcel transformers)
+
+## Related Libraries
+
+- react-tosijs [react-tosijs](https://github.com/tonioloewald/react-tosijs#readme)
+  allows you to use xin's path-observer model in React [ReactJS](https://reactjs.org) apps
+- type-by-example [github](https://github.com/tonioloewald/type-by-example) | [npm](https://www.npmjs.com/package/type-by-example)
+  is a library for declaring types in pure javascript, allowing run-time type-checking.
+- filter-shapes [github](https://github.com/tonioloewald/filter-shapes) | [npm](https://www.npmjs.com/package/filter-shapes)
+  is a library for filtering objects (and arrays of objects) to specific shapes (e.g. to reduce storage / bandwidth costs).
+  It is built on top of type-by-example.
+
+## Credits
+
+`tosijs` is in essence a highly incompatible update to `b8rjs` with the goal
+of removing cruft, supporting more use-cases, and eliminating functionality
+that has been made redundant by improvements to the JavaScript language and
+DOM APIs.
+
+`tosijs` is being developed using [bun](https://bun.sh/).
+`bun` is crazy fast (based on Webkit's JS engine, vs. V8), does a lot of stuff
+natively, and runs TypeScript (with import and require) directly.

package/dist/bind.d.ts

@@ -0,0 +1,9 @@
+import { XinEventHandler, XinTouchableType, XinBinding, XinBindingSpec, EventType } from './xin-types';
+export declare const touchElement: (element: Element, changedPath?: string) => void;
+interface BindingOptions {
+    [key: string]: any;
+}
+export declare function bind<T extends Element = Element>(element: T, what: XinTouchableType | XinBindingSpec, binding: XinBinding<T>, options?: BindingOptions): T;
+type RemoveListener = VoidFunction;
+export declare function on<E extends HTMLElement, K extends EventType>(element: E, eventType: K, eventHandler: XinEventHandler<HTMLElementEventMap[K], E>): RemoveListener;
+export {};

package/dist/bindings.d.ts

@@ -0,0 +1,4 @@
+import { XinBinding } from './xin-types';
+export declare const bindings: {
+    [key: string | symbol]: XinBinding<Element>;
+};

package/dist/blueprint-loader.d.ts

@@ -0,0 +1,19 @@
+import { Component } from './component';
+import { XinPackagedComponent } from './make-component';
+export declare class Blueprint extends Component {
+    tag: string;
+    src: string;
+    property: string;
+    loaded?: XinPackagedComponent;
+    blueprintLoaded: (_package: XinPackagedComponent) => void;
+    packaged(): Promise<XinPackagedComponent>;
+    constructor();
+}
+export declare const blueprint: import("./xin-types").ElementCreator<Component<import("./xin-types").PartsMap>>;
+export declare class BlueprintLoader extends Component {
+    allLoaded: () => void;
+    constructor();
+    private load;
+    connectedCallback(): void;
+}
+export declare const blueprintLoader: import("./xin-types").ElementCreator<Component<import("./xin-types").PartsMap>>;

package/dist/by-path.d.ts

@@ -0,0 +1,8 @@
+import { XinObject, XinArray } from './xin-types';
+type Part = string | string[];
+type PartArray = Part[];
+declare function pathParts(path: string | PartArray): PartArray;
+declare function getByPath(obj: XinObject | XinArray, path: string): any;
+declare function setByPath(orig: XinObject | XinArray, path: string, val: any): boolean;
+declare function deleteByPath(orig: XinObject, path: string): void;
+export { getByPath, setByPath, deleteByPath, pathParts };

package/dist/color.d.ts

@@ -0,0 +1,46 @@
+import { CSSSystemColor } from './css-system-color';
+declare class HslColor {
+    h: number;
+    s: number;
+    l: number;
+    constructor(r: number, g: number, b: number);
+}
+export declare class Color {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+    static fromVar(varName: string, element?: HTMLElement): Color;
+    static fromCss(spec: CSSSystemColor | string): Color;
+    static fromHsl(h: number, s: number, l: number, a?: number): Color;
+    static black: Color;
+    static white: Color;
+    constructor(r: number, g: number, b: number, a?: number);
+    get inverse(): Color;
+    get inverseLuminance(): Color;
+    contrasting(amount?: number): Color;
+    get rgb(): string;
+    get rgba(): string;
+    get RGBA(): number[];
+    get ARGB(): number[];
+    private hslCached?;
+    get _hsl(): HslColor;
+    get hsl(): string;
+    get hsla(): string;
+    get mono(): Color;
+    get brightness(): number;
+    get html(): string;
+    toString(): string;
+    brighten(amount: number): Color;
+    darken(amount: number): Color;
+    saturate(amount: number): Color;
+    desaturate(amount: number): Color;
+    rotate(amount: number): Color;
+    opacity(alpha: number): Color;
+    swatch(): Color;
+    blend(otherColor: Color, t: number): Color;
+    static blendHue(a: number, b: number, t: number): number;
+    mix(otherColor: Color, t: number): Color;
+    colorMix(otherColor: Color, t: number): Color;
+}
+export {};

package/dist/component.d.ts

@@ -0,0 +1,37 @@
+import { XinStyleSheet } from './css-types';
+import { ElementsProxy } from './elements';
+import { ElementCreator, ContentType, PartsMap } from './xin-types';
+interface ElementCreatorOptions extends ElementDefinitionOptions {
+    tag?: string;
+    styleSpec?: XinStyleSheet;
+}
+export declare abstract class Component<T = PartsMap> extends HTMLElement {
+    static elements: ElementsProxy;
+    private static _elementCreator?;
+    instanceId: string;
+    styleNode?: HTMLStyleElement;
+    static styleSpec?: XinStyleSheet;
+    static styleNode?: HTMLStyleElement;
+    content: ContentType | (() => ContentType) | null;
+    isSlotted?: boolean;
+    private static _tagName;
+    static get tagName(): null | string;
+    [key: string]: any;
+    static StyleNode(styleSpec: XinStyleSheet): HTMLStyleElement;
+    static elementCreator(options?: ElementCreatorOptions): ElementCreator<Component>;
+    initAttributes(...attributeNames: string[]): void;
+    private initValue;
+    private _parts?;
+    get parts(): T;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private _changeQueued;
+    private _renderQueued;
+    queueRender(triggerChangeEvent?: boolean): void;
+    private _hydrated;
+    private hydrate;
+    render(): void;
+}
+export declare const xinSlot: ElementCreator<Component<PartsMap>>;
+export {};

package/dist/css-colors.d.ts

@@ -0,0 +1,3 @@
+export declare const cssColors: {
+    [key: string]: string;
+};

package/dist/css-system-color.d.ts

@@ -0,0 +1 @@
+export type CSSSystemColor = 'aliceblue' | 'antiquewhite' | 'aqua' | 'aquamarine' | 'azure' | 'beige' | 'bisque' | 'black' | 'blanchedalmond' | 'blue' | 'blueviolet' | 'brown' | 'burlywood' | 'cadetblue' | 'chartreuse' | 'chocolate' | 'coral' | 'cornflowerblue' | 'cornsilk' | 'crimson' | 'cyan' | 'darkblue' | 'darkcyan' | 'darkgoldenrod' | 'darkgray' | 'darkgreen' | 'darkgrey' | 'darkkhaki' | 'darkmagenta' | 'darkolivegreen' | 'darkorange' | 'darkorchid' | 'darkred' | 'darksalmon' | 'darkseagreen' | 'darkslateblue' | 'darkslategray' | 'darkslategrey' | 'darkturquoise' | 'darkviolet' | 'deeppink' | 'deepskyblue' | 'dimgray' | 'dimgrey' | 'dodgerblue' | 'firebrick' | 'floralwhite' | 'forestgreen' | 'fuchsia' | 'gainsboro' | 'ghostwhite' | 'gold' | 'goldenrod' | 'gray' | 'green' | 'greenyellow' | 'grey' | 'honeydew' | 'hotpink' | 'indianred' | 'indigo' | 'ivory' | 'khaki' | 'lavender' | 'lavenderblush' | 'lawngreen' | 'lemonchiffon' | 'lightblue' | 'lightcoral' | 'lightcyan' | 'lightgoldenrodyellow' | 'lightgray' | 'lightgreen' | 'lightgrey' | 'lightpink' | 'lightsalmon' | 'lightseagreen' | 'lightskyblue' | 'lightslategray' | 'lightslategrey' | 'lightsteelblue' | 'lightyellow' | 'lime' | 'limegreen' | 'linen' | 'magenta' | 'maroon' | 'mediumaquamarine' | 'mediumblue' | 'mediumorchid' | 'mediumpurple' | 'mediumseagreen' | 'mediumslateblue' | 'mediumspringgreen' | 'mediumturquoise' | 'mediumvioletred' | 'midnightblue' | 'mintcream' | 'mistyrose' | 'moccasin' | 'navajowhite' | 'navy' | 'oldlace' | 'olive' | 'olivedrab' | 'orange' | 'orangered' | 'orchid' | 'palegoldenrod' | 'palegreen' | 'paleturquoise' | 'palevioletred' | 'papayawhip' | 'peachpuff' | 'peru' | 'pink' | 'plum' | 'powderblue' | 'purple' | 'red' | 'rosybrown' | 'royalblue' | 'saddlebrown' | 'salmon' | 'sandybrown' | 'seagreen' | 'seashell' | 'sienna' | 'silver' | 'skyblue' | 'slateblue' | 'slategray' | 'slategrey' | 'snow' | 'springgreen' | 'steelblue' | 'tan' | 'teal' | 'thistle' | 'tomato' | 'turquoise' | 'violet' | 'wheat' | 'white' | 'whitesmoke' | 'yellow' | 'yellowgreen';