doc(*): improve readmes

packages/controllers/package.json

@@ -1,15 +1,15 @@
 {
  "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": {
  "./package.json": "./package.json",
  ".": {
  "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",

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 

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'] })
+
+// <hello-world name="lorenzofox"></hello-world> 
+```
+
+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](<script src="https://unpkg.com/@ungap/[email protected]/es.js"></script>)
+* ``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.

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
+<some-provider>
+
+<!-- any element will see injectable "a" as 'ac' -->
+ <some-other-provider>
+ <!-- any element will see injectable "a" as 'aotherC' -->
+ </some-other-provider>
+
+</some-provider>
+```
+
+### 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
+
+}));
+```
+
+
+
+