From 36c0d221aa6d619fa397023dd55e958d830560e5 Mon Sep 17 00:00:00 2001 From: lorenzofox3 Date: Wed, 20 Mar 2024 10:54:23 +0100 Subject: [PATCH] doc(*): improve readmes --- packages/controllers/package.json | 6 +-- packages/controllers/readme.md | 4 ++ packages/core/readme.md | 44 +++++++++++++++++++ packages/di/readme.md | 71 +++++++++++++++++++++++++++++++ 4 files changed, 122 insertions(+), 3 deletions(-) diff --git a/packages/controllers/package.json b/packages/controllers/package.json index 188ff08..cc41ea7 100644 --- a/packages/controllers/package.json +++ b/packages/controllers/package.json @@ -1,7 +1,7 @@ { "name": "@cofn/controllers", "version": "0.0.1", - "description": "", + "description": "A set of higher order function to help implement update logic", "type": "module", "types": "./dist/index.d.ts", "exports": { @@ -9,7 +9,7 @@ ".": { "import": { "types": "./dist/index.d.ts", - "default": "./dist/cofn-controller.js" + "default": "./dist/cofn-controllers.js" } } }, @@ -20,7 +20,7 @@ "scripts": { "dev": "vite", "test": "node test/run-ci.js", - "build": "mkdir -p dist && rollup src/index.js > dist/cofn-controller.js && cp src/index.d.ts dist", + "build": "mkdir -p dist && rollup src/index.js > dist/cofn-controllers.js && cp src/index.d.ts dist", "size": "rollup -p @rollup/plugin-terser src/index.js | gzip | wc -c" }, "author": "Laurent RENARD", diff --git a/packages/controllers/readme.md b/packages/controllers/readme.md index ab77550..4ea64ff 100644 --- a/packages/controllers/readme.md +++ b/packages/controllers/readme.md @@ -9,6 +9,10 @@ you can install the library with a package manager (like npm): Or import it directly from a CDN +```js +import {withController} from 'https://unpkg.com/@cofn/controllers/dist/cofn-controllers.js'; +``` + ## Reactive props Defines a list of properties to watch. The namespace ``properties`` is injected into the rendering generator diff --git a/packages/core/readme.md b/packages/core/readme.md index d9aa1cf..9aaaf91 100644 --- a/packages/core/readme.md +++ b/packages/core/readme.md @@ -14,3 +14,47 @@ Or import it directly from a CDN ```js import {define} from 'https://unpkg.com/@cofn/core/dist/cofn-core.js' ``` + +## Usage + +The package exports a ``define`` function you can use to define new custom elements + +```js +import { define } from '@cofn/core'; + +define('hello-world', function* ({ $host, $root, $signal }) { + // constructing + let input = yield 'constructured'; + + // mounted + + try { + while (true) { + $root.textContent = `hello ${input.attributes.name}`; + input = yield; + // update requested + } + } finally { + // the instance is removed from the DOM tree: you won't be able to use it anymore + console.log('clean up') + } +}, { observedAttributes: ['name'] }) + +// +``` + +The component is defined as a generator function which has injected: +* ``$host``: the custom element instance +* ``$root``: the DOM tree root of the custom element instance. It is either the ``$host`` itself or the ``shadowRoot`` if you have passed shadow dom option in the third optional argument +* ``$signal``: an ``AbortSignal`` which is triggered when the element is unmounted. This is more for convenience, to ease the cleanup, if you use APIs which can take an abort signal as option. Otherwise, you can run clean up code in the ``finally`` clause. + +Because generators are functions, you can use higher order functions and delegation to enhance the custom element behaviour. You will find more details in the [blog](https://lorenzofox.dev) + +By default, when the generator yields, the attributes of the custom elements are assigned under the ``attributes`` namespace. + +### options + +The third argument is optional. It takes the same parameters as the regular [customElementRegistry.define](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define) and some more: +* ``extends``: If you wish to make your custom element extends a built-in element. Careful, webkit refuses to implement that spec and you will need a [polyfill]() +* ``shadow``: same as [attachShadow](https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow) function. +* ``observedAttributes``: the list of attributes the browser will observe. Any change on the one of these attributes will resume the generator execution. diff --git a/packages/di/readme.md b/packages/di/readme.md index 365b0f0..b1a267f 100644 --- a/packages/di/readme.md +++ b/packages/di/readme.md @@ -8,3 +8,74 @@ you can install the library with a package manager (like npm): ``npm install @cofn/di`` Or import it directly from a CDN + +```js +import {provide, inject} from 'https://unpkg.com/@cofn/di/dist/cofn-di.js'; +``` + +## usage + +### provide + +``provide`` is a higher order function which takes as input either a function which returns a map of injectables or a map of injectables. +If it is a function it takes all as input all the dependencies of the bound generator (ie ``$host``, etc). + +The map is an object whose keys are injection tokens (by name or symbol) and the values are factory functions (functions used to create an "instance" of that injectable) or values. +These factories can themselves depends on other injectables: + +```js +import {provide} from '@cofn/di'; +import {define} from '@cofn/core'; + +const withAB = provide({ + a: ({b}) => 'a' + b, + b: 'c' +}); + +define('some-provider', withAB(function*(){ + +})); +``` + +When a child element of the DOM tree is also a provider, it can override dependencies for its descendants + +```js +const withbbis = provide({ + a: ({b}) => 'a' + b, + b: 'otherC' +}); + +define('some-other-provider', withAB(function*(){ + +})); +``` + +```html + + + + + + + + +``` + +### inject + +A higher order function to declare that the component will have the map of services injected. Services are instantiated only when you call the getter related to a specific injected + +```js +import { inject } from '@cofn/di'; + +define('some-el', inject(function* ({ services }) { + + const { b } = services; // only b is instantiated + // etc + +})); +``` + + + +