Skip to content

Commit

Permalink
tweaks in HTML/DOM rendering; other misc
Browse files Browse the repository at this point in the history
  • Loading branch information
@mitranim
mitranim committed Nov 24, 2023
1 parent 9d78fea commit 521cbf4
Show file tree
Hide file tree
Showing 37 changed files with 679 additions and 509 deletions.
9 changes: 9 additions & 0 deletions doc/obs_dom_readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ Optionally combine with {{featLink dom_reg}} for automatic registration of eleme
## TOC

* [#Usage](#usage)
* [#Limitations](#limitations)
* [#API](#api)
{{toc}}

Expand Down Expand Up @@ -46,6 +47,14 @@ document.body.append(
obs.msg = `hello world!`
```

## Limitations

This is intended and well-suited for SPA (single-page applications), or more generally, for custom elements which are client-only. This should be _avoided_ for any elements involved in _SSR_ (server-side rendering). Observable-based reactivity is fundamentally incompatible with the "ideal" way of using custom elements in apps featuring SSR.

One of the biggest benefits of custom elements is how they can enable client-side interactive features by instantiating in-place from existing HTML markup. (For comparison, many JS frameworks require you to re-render the entire markup on the client, which usually also requires re-fetching the source data, or inlining it into the HTML as JSON.) They can enrich SSR apps without forcing you to convert to a SPA. They're also well-suited for SSR/SPA hybrids, with the addition of a {{featLink dom_shim}} and a {{featLink prax rendering system}} compatible with both shimmed and native DOM.

However, this hybrid approach forces some limitations. In particular, when custom elements activate from existing HTML markup, the client side of your application doesn't have the same data which was available to the server side. This is typically a good thing, for a variety of reasons. This also means that for elements that react to changes in {{featLink obs observables}}, those observables are often not available during the initial activation. These issues _can_ be solved in special cases, for example by delaying the registration of custom element classes and creating the relevant global observables first. But in many cases, these issues are impractical to solve. Bottom line: observables are for client-only code.

## API

{{api}}
6 changes: 3 additions & 3 deletions docs/cli_readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
CLI args:

```js
import * as cl from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/cli.mjs'
import * as cl from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/cli.mjs'

const cli = cl.Flag.os()

Expand All @@ -34,15 +34,15 @@ console.log(...cli.args)
Console clearing:

```js
import * as cl from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/cli.mjs'
import * as cl from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/cli.mjs'

cl.emptty()
```

Clearing the console only once, before running your code:

```js
import 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/cli_emptty.mjs'
import 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/cli_emptty.mjs'
```

## API
Expand Down
8 changes: 4 additions & 4 deletions docs/coll_readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Port and rework of https://github.com/mitranim/jol.
## Usage

```js
import * as c from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/coll.mjs'
import * as c from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/coll.mjs'
```

## API
Expand Down Expand Up @@ -101,8 +101,8 @@ Links: [source](../coll.mjs#L102); [test/example](../test/coll_test.mjs#L218).
Variant of [#`Bmap`](#class-bmap) with support for key and value checks. Subclasses must override methods `.reqKey` and `.reqVal`. These methods are automatically called by `.set`. Method `.reqKey` must validate and return the given key, and method `.reqVal` must validate and return the given value. Use type assertions provided by [`lang`](lang_readme.md).

```js
import * as l from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/lang.mjs'
import * as c from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/coll.mjs'
import * as l from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/lang.mjs'
import * as c from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/coll.mjs'

class StrNatMap extends c.TypedMap {
reqKey(key) {return l.reqStr(key)}
Expand Down Expand Up @@ -242,7 +242,7 @@ Differences and advantages over `Array`:
The overhead of the wrapper is insignificant.

```js
import * as c from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/coll.mjs'
import * as c from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/coll.mjs'

console.log(new c.Vec())
// Vec{$: []}
Expand Down
2 changes: 1 addition & 1 deletion docs/dom_glob_native_readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
## Usage

```js
import * as dg from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/dom_glob_native.mjs'
import * as dg from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/dom_glob_native.mjs'

console.log(dg.glob)
```
Expand Down
2 changes: 1 addition & 1 deletion docs/dom_glob_shim_readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
## Usage

```js
import * as dg from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/dom_glob_shim.mjs'
import * as dg from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/dom_glob_shim.mjs'

console.log(dg.glob)
```
Expand Down
2 changes: 1 addition & 1 deletion docs/dom_readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
## Usage

```js
import * as d from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/dom.mjs'
import * as d from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/dom.mjs'
```

## API
Expand Down
4 changes: 2 additions & 2 deletions docs/dom_reg_readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@
Example mockup for a pushstate link.

```js
import * as dr from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/dom_reg.mjs'
import * as dr from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/dom_reg.mjs'

// Immediately ready for use. Tag is automatically set to `a-btn`.
class Btn extends dr.HTMLButtonElement {
Expand Down Expand Up @@ -74,7 +74,7 @@ Registry for custom DOM element classes. Automatically derives tag name from cla
By default, this registry has **no global side effects**. To enable global registration, provide a "definer" to the registry.

```js
import * as dr from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/dom_reg.mjs'
import * as dr from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/dom_reg.mjs'

class Btn extends HTMLButtonElement {
static customName = `some-btn`
Expand Down
54 changes: 27 additions & 27 deletions docs/dom_shim_readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
## Usage

```js
import * as ds from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/dom_shim.mjs'
import * as ds from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/dom_shim.mjs'
```

## API
Expand Down Expand Up @@ -83,29 +83,29 @@ The following APIs are exported but undocumented. Check [dom_shim.mjs](../dom_sh
* [`class HTMLMetaElement`](../dom_shim.mjs#L582)
* [`class HTMLAnchorElement`](../dom_shim.mjs#L587)
* [`class HTMLButtonElement`](../dom_shim.mjs#L614)
* [`class HTMLInputElement`](../dom_shim.mjs#L636)
* [`class HTMLTextAreaElement`](../dom_shim.mjs#L648)
* [`class HTMLTableElement`](../dom_shim.mjs#L650)
* [`class HTMLScriptElement`](../dom_shim.mjs#L659)
* [`class SVGElement`](../dom_shim.mjs#L677)
* [`class DocumentType`](../dom_shim.mjs#L682)
* [`class Document`](../dom_shim.mjs#L705)
* [`class HTMLDocument`](../dom_shim.mjs#L796)
* [`class DOMImplementation`](../dom_shim.mjs#L813)
* [`class DictPh`](../dom_shim.mjs#L847)
* [`class StylePh`](../dom_shim.mjs#L860)
* [`class ClassList`](../dom_shim.mjs#L979)
* [`class GlobPh`](../dom_shim.mjs#L1049)
* [`const glob`](../dom_shim.mjs#L1068)
* [`const document`](../dom_shim.mjs#L1069)
* [`const customElements`](../dom_shim.mjs#L1070)
* [`function auto`](../dom_shim.mjs#L1072)
* [`function escapeAttr`](../dom_shim.mjs#L1085)
* [`function escapeText`](../dom_shim.mjs#L1098)
* [`function escapeChar`](../dom_shim.mjs#L1105)
* [`function unescape`](../dom_shim.mjs#L1114)
* [`function unescapeMatch`](../dom_shim.mjs#L1118)
* [`const styleToCssCache`](../dom_shim.mjs#L1133)
* [`const camelToDataCache`](../dom_shim.mjs#L1137)
* [`const dataToCamelCache`](../dom_shim.mjs#L1141)
* [`const outerHtmlDyn`](../dom_shim.mjs#L1145)
* [`class HTMLInputElement`](../dom_shim.mjs#L639)
* [`class HTMLTextAreaElement`](../dom_shim.mjs#L651)
* [`class HTMLTableElement`](../dom_shim.mjs#L653)
* [`class HTMLScriptElement`](../dom_shim.mjs#L662)
* [`class SVGElement`](../dom_shim.mjs#L680)
* [`class DocumentType`](../dom_shim.mjs#L685)
* [`class Document`](../dom_shim.mjs#L708)
* [`class HTMLDocument`](../dom_shim.mjs#L799)
* [`class DOMImplementation`](../dom_shim.mjs#L816)
* [`class DictPh`](../dom_shim.mjs#L850)
* [`class StylePh`](../dom_shim.mjs#L863)
* [`class ClassList`](../dom_shim.mjs#L982)
* [`class GlobPh`](../dom_shim.mjs#L1052)
* [`const glob`](../dom_shim.mjs#L1071)
* [`const document`](../dom_shim.mjs#L1072)
* [`const customElements`](../dom_shim.mjs#L1073)
* [`function auto`](../dom_shim.mjs#L1075)
* [`function escapeAttr`](../dom_shim.mjs#L1088)
* [`function escapeText`](../dom_shim.mjs#L1101)
* [`function escapeChar`](../dom_shim.mjs#L1108)
* [`function unescape`](../dom_shim.mjs#L1117)
* [`function unescapeMatch`](../dom_shim.mjs#L1121)
* [`const styleToCssCache`](../dom_shim.mjs#L1136)
* [`const camelToDataCache`](../dom_shim.mjs#L1140)
* [`const dataToCamelCache`](../dom_shim.mjs#L1144)
* [`const outerHtmlDyn`](../dom_shim.mjs#L1149)
8 changes: 4 additions & 4 deletions docs/http_readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ HTTP request/response utils are ported and reworked from https://github.com/mitr
## Usage

```js
import * as h from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/http.mjs'
import * as h from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/http.mjs'

const reqBody = {msg: `hello world`}
const resBody = await h.reqBui().to(`/api`).post().json(reqBody).fetchOkJson()
Expand Down Expand Up @@ -234,8 +234,8 @@ rou.groups // {key: `path`}
Routing is imperative:

```js
import * as h from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/http.mjs'
import * as l from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/lang.mjs'
import * as h from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/http.mjs'
import * as l from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/lang.mjs'

const nextPage = route(window.location)

Expand Down Expand Up @@ -263,7 +263,7 @@ Short for "request router" or "request-response router". Advanced version of [#`
Routing can be shared between SSR and SPA:

```js
import * as h from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].47/http.mjs'
import * as h from 'https://cdn.jsdelivr.net/npm/@mitranim/[email protected].48/http.mjs'

function route(rou) {
l.reqInst(rou, h.ReqRou)
Expand Down
Loading

0 comments on commit 521cbf4

Please sign in to comment.