tosijs 1.5.2 → 1.5.4

package/README.md

@@ -28,7 +28,8 @@ If you want to build a web-application that's performant, robust, and maintainab
 
 - 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
+- bind application state to the UI and services without locking yourself into a specific framework
+- work in Typescript or Javascript
 - 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
@@ -54,7 +55,7 @@ const { h4, ul, template, li, label, input } = elements
 preview.append(
   h4('To Do List'),
   ul(
-    ...readmeTodoDemo.list.tosiListBinding(
+    ...readmeTodoDemo.list.listBinding(
       ({ li, button }, item) =>
         li(
           item.reminder,
@@ -92,7 +93,7 @@ and simplicity as you get with highly-refined React-centric toolchains, but with
 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
+`tosijs` lets you work with pure HTML and web-components as cleanly—more cleanly—and efficiently than
 React toolchains let you work with JSX.
 
     export default function App() {
@@ -114,7 +115,7 @@ Becomes:
     )
 
 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
+or virtual DOM required. And it all works just as well with web-components. This is what you get when
 you run App() in the console:
 
     ▼ <div class="App">
@@ -140,13 +141,13 @@ more compactly than with `jsx` (and without a virtual DOM).
 
     import { Component, elements, css } from 'tosijs'
 
-    const { style, h1, slot } = elements
+    const { h1, slot } = elements
     export class MyComponent extends Component {
-      styleNode = style(css({
+      static shadowStyleSpec = css({
         h1: {
           color: 'blue'
         }
-      }))
+      })
       content = [ h1('hello world'), slot() ]
     }
 
@@ -161,9 +162,9 @@ and are natively supported by all modern browsers.
 `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'
+    import { tosi, observe } from 'tosijs'
 
-    const { app } = xinProxy({
+    const { app } = tosi({
       app: {
         prefs: {
           darkmode: false
@@ -179,29 +180,28 @@ and direct updates to application state.
     })
 
     observe('app.prefs.darkmode', () => {
-      document.body.classList.toggle('dark-mode', app.prefs.darkmode)
+      document.body.classList.toggle('dark-mode', app.prefs.darkmode.value)
     })
 
     observe('app.docs', () => {
       // render docs
     })
 
-> #### What does `xinProxy` do, and what is a `XinProxy`?
+> #### What does `tosi` do, and what is a `BoxedProxy`?
 >
-> `xinProxy` is syntax sugar for assigning something to `xin` (which is a `XinProxyObject`)
-> and then getting it back out again.
+> `tosi` is syntax sugar for assigning something to `xin` (which is a proxy over
+> the central registry) and then getting it back out as a `BoxedProxy`.
 >
-> A `XinProxy` is an [ES Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
+> A `BoxedProxy` 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
+> All you need to know about a `BoxedProxy` is that it's a 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.
+> If you want the original object back you can use `.value` on any proxy to unwrap it.
 
 ### No Tax, No Packaging
 
@@ -209,17 +209,17 @@ and direct updates to application state.
 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 = {...}`.
+**Note** `tosi({foo: {...}})` is syntax sugar for `xin.foo = {...}`.
 
-    import { xinProxy, observe } from 'tosijs'
-    const { foo } = xinProxy({
+    import { tosi, observe } from 'tosijs'
+    const { foo } = tosi({
       foo: {
         bar: 17
       }
     })
 
-    observe('foo.bar', v => {
-      console.log('foo.bar was changed to', xin.foo.bar)
+    observe('foo.bar', (path) => {
+      console.log('foo.bar was changed to', foo.bar.value)
     })
 
     foo.bar = 17        // does not trigger the observer
@@ -230,13 +230,13 @@ with a `Proxy` and then if you use `xin` to make changes to those objects,
 `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'
+    import { xin } from 'tosijs'
 
     const foo = {bar: 'baz'}
     xin.foo = foo
 
-    // xin.foo returns a Proxy wrapped around foo (without touching foo)
-    xinValue(xin.foo) === foo
+    // xin.foo returns the value directly
+    xin.foo.bar === 'baz'
 
     // really, it's just the original object
     xin.foo.bar = 'lurman'
@@ -251,9 +251,9 @@ into it is what you get out of it:
 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
+    import { tosi, xin } from 'tosijs'
 
-    const { app } = xinProxy ({
+    const { app } = tosi({
       app: {
         list: [
           {
@@ -270,7 +270,7 @@ so `tosijs` supports the idea of id-paths
 
     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
+    console.log(xin['app.list[id=1234abcd]'])  // hello world
 
 ### Telling `xin` about changes using `touch()`
 
@@ -281,7 +281,7 @@ When you want to trigger updates, simply touch the path.
 
     const foo = { bar: 17 }
     xin.foo = foo
-    observe('foo.bar', path => console.log(path, '->', xin[path])
+    observe('foo.bar', (path) => console.log(path, '->', xin[path]))
     xin.foo.bar = -2              // console will show: foo.bar -> -2
 
     foo.bar = 100                 // nothing happens
@@ -320,37 +320,35 @@ elements are reused (no teardown/recreation).
 
 `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' }
+    import { css, vars } from 'tosijs'
 
-The `vars` simply converts its camelCase properties into css variable references
+The `vars` proxy converts 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))'
+    `calc(${vars.width} + 2 * ${vars.spacing})` // emits 'calc(var(--width) + 2 * var(--spacing))'
 
-`css()` processes an object, rendering it as CSS
+`css()` processes an object, rendering it as CSS:
 
     css({
       '.container': {
-        'position', 'relative'
+        position: 'relative'
       }
     }) // emits .container { position: relative; }
 
+CSS variables can be declared using `_` and `__` prefixes in `css()` objects:
+
+    css({
+      ':root': {
+        _textFont: 'sans-serif',   // emits --text-font: sans-serif
+        _color: '#111',            // emits --color: #111
+      }
+    })
+
 ## Color
 
 `tosijs` includes a powerful `Color` class for manipulating colors.
 
-    import {Color} from 'tosijs
+    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)
@@ -358,13 +356,15 @@ The `vars` simply converts its camelCase properties into css variable references
 The color objects have computed properties for rendering the color in different ways,
 making adjustments, blending colors, and so forth.
 
+Use `invertLuminance()` to generate dark-mode equivalents of color values.
+
 ## 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'
+    import { xin, hotReload } from 'tosijs'
 
     xin.app = {
       ...
@@ -381,42 +381,21 @@ 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
+You'll need to install [bun](https://bun.sh/) and then run `bun install`.
 
-- remove all the parcel transformer dependencies @parcel/\*
-- rm -rf node_modules
-- run the update script
-- npx parcel build (which restores needed parcel transformers)
+    bun start                  # dev server with hot reload (https://localhost:8018)
+    bun test                   # run all tests
+    bun run dev.ts --build     # production build (runs tests, then bundles)
+    bun run format             # lint and format (ESLint + Prettier)
+    bun pack                   # create local package tarball
 
 ## 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.
+- [tosijs-ui](https://ui.tosijs.net) — a web-component library built on tosijs `Component`
+- [tosijs-3d](https://3d.tosijs.net) — 3D graphics library built on tosijs
+- [react-tosijs](https://github.com/tonioloewald/react-tosijs#readme) — use tosijs's path-observer model in [React](https://reactjs.org) apps
 
 ## Credits
 

package/dist/by-path.d.ts

@@ -1,4 +1,5 @@
 import { XinObject, XinArray } from './xin-types';
+export declare const id: () => string;
 type Part = string | string[];
 type PartArray = Part[];
 declare function pathParts(path: string | PartArray): PartArray;

package/dist/component.d.ts

@@ -100,7 +100,7 @@ export declare abstract class Component<T = PartsMap> extends HTMLElement {
 interface SlotParts extends PartsMap {
     slotty: HTMLSlotElement;
 }
-declare class XinSlot extends Component<SlotParts> {
+declare class TosiSlot extends Component<SlotParts> {
     static preferredTagName: string;
     static initAttributes: {
         name: string;
@@ -108,5 +108,15 @@ declare class XinSlot extends Component<SlotParts> {
     content: null;
     static replaceSlot(slot: HTMLSlotElement): void;
 }
+export declare const tosiSlot: ElementCreator<TosiSlot>;
+declare class XinSlot extends Component<SlotParts> {
+    static preferredTagName: string;
+    static initAttributes: {
+        name: string;
+    };
+    content: null;
+    constructor();
+    static replaceSlot: typeof TosiSlot.replaceSlot;
+}
 export declare const xinSlot: ElementCreator<XinSlot>;
 export {};

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { css, invertLuminance, initVars, vars, varDefault, StyleSheet, onStylesh
 export type { ColorScheme, ContrastPreference, ThemePreferences } from './css';
 export type { XinStyleSheet, XinStyleMap, XinStyleRule } from './css-types';
 export { Color } from './color';
-export { Component } from './component';
+export { Component, tosiSlot, xinSlot } from './component';
 export { validateAgainstConstraints, type FormValidation, } from './form-validation';
 export { elements, svgElements, mathML, bindParts } from './elements';
 export type { ElementsProxy } from './elements-types';
@@ -24,4 +24,4 @@ export { version } from './version';
 export { xin, boxed, observe, unobserve, touch, updates } from './xin';
 export { tosiBlueprint, tosiLoader, blueprint, Blueprint, blueprintLoader, BlueprintLoader, } from './blueprint-loader';
 export * from './xin-types';
-export { tosi, xinProxy, boxedProxy } from './xin-proxy';
+export { tosi, tosiUnique, xinProxy, boxedProxy } from './xin-proxy';