@kosdev-code/kos-asset-manager 0.0.1-next.27 → 0.0.1-next.29

package/README.md

@@ -119,37 +119,114 @@ keys when the declaration is generated:
 
 A pattern that matches nothing is reported during the build.
 
-## Using assets in a ui
+## Installing
+
+```sh
+npm install @kosdev-code/kos-asset-manager
+```
+
+The package is ESM. `@kosdev-code/kos-ui-sdk` (`~3.0.0`) and React 18 or
+newer are peer dependencies, so it uses the copies the application already
+has.
+
+## Setting it up
+
+Register the models where the application registers everything else. Note the
+second call — `registerAssetModels` returns a function.
 
 ```ts
-import { initAssets, wrapAsset, resolveAsset, preloadAssets } from '@kosdev-code/kos-asset-manager';
+import { KosModelRegistry } from '@kosdev-code/kos-dispense-sdk';
+import { registerAssetModels } from '@kosdev-code/kos-asset-manager';
 
-// once while starting, naming the applications whose assets this ui uses
-await initAssets({ contexts: ['my.app.id'], preload: ['boot'] });
+KosModelRegistry.dispense.models();
+registerAssetModels(KosModelRegistry)();
+```
 
-const logo = wrapAsset('brand/logo-primary');
-<img src={logo.src} alt="" />
+Then wrap the tree in the provider, which loads the declarations everything
+else reads:
 
-// anywhere a url is expected
-element.style.backgroundImage = `url(${resolveAsset('brand/logo-primary')})`;
+```tsx
+import { KosAssetProvider } from '@kosdev-code/kos-asset-manager';
+
+const App = () => (
+  <KosTranslationProvider>
+    <KosAssetProvider contexts={['my.app.id']} gate>
+      <MyScreens />
+    </KosAssetProvider>
+  </KosTranslationProvider>
+);
+```
 
-// ready assets ahead of a screen that needs them
-await preloadAssets('checkout');
+`contexts` names the applications whose assets this ui uses, so it loads only
+what it needs; omit it to load everything the device declares, which is what
+a tool that browses them wants. `gate` holds the children back until the
+assets have loaded, which is worth it when the first screen renders them.
+
+`contexts` is also the tie-break order for a bare key: named contexts are
+searched first, in the order given, then everything else.
+
+For an application that would rather drive its own loading UI,
+`useAssetManager(contexts?)` is what the provider uses internally and returns
+`{ model, ready, status, KosModelLoader }`. `useKosAssetContext()` returns
+`{ model }` for components that want the model rather than the helpers.
+
+## Using assets
+
+```tsx
+import { kosComponent } from '@kosdev-code/kos-ui-sdk';
+import { wrapAsset } from '@kosdev-code/kos-asset-manager';
+
+export const Header = kosComponent(() => {
+  const logo = wrapAsset('brand/logo-primary');
+
+  return (
+    <img src={logo.src} width={logo.width} height={logo.height} alt="Home" />
+  );
+});
 ```
 
+`wrapAsset(key)` returns a `ResolvedAsset`: `src`, `width`, `height`,
+`poster`, `type`, `size`, `hash`, `tags`, `key`, `context` and `exists`.
+Images are measured when the declaration is generated, so passing `width` and
+`height` reserves the space and nothing reflows when the file arrives. An
+unknown key logs a warning and comes back with `exists: false` and an empty
+`src` rather than throwing, so a missing asset never takes a screen down.
+
+Two things to get right. The helpers read MobX models, so a component that
+reads them should be a `kosComponent` — otherwise it renders once with
+whatever was loaded at the time and never updates. And resolve inside the
+component rather than at module scope: a value computed when the module loads
+runs before the provider has loaded anything.
+
+`resolveAsset(key)` is the url on its own, for anywhere a url is expected:
+
+```ts
+element.style.backgroundImage = `url(${resolveAsset('brand/logo-primary')})`;
+```
+
+`hasAsset(key)` is true when a loaded application declares the key, for
+branching on an optional asset without the warning `wrapAsset` logs.
+
+A key resolves in the contexts named at the provider, first match winning,
+unless it names one: `other.app.id:brand/logo-primary`.
+
+## Selecting sets
+
 Sets of assets are selected rather than named, so adding a file to a folder
 is all it takes to include it:
 
 ```ts
+listAssets({ tag: 'beverage-logo' }).map((asset) => asset.src);
+
 await preloadAssets({ prefix: 'beverages/' });   // a folder
 await preloadAssets({ tag: 'beverage-logo' });   // a tag, across folders
 await preloadAssets({ type: 'video/' });         // by mime type
-
-listAssets({ tag: 'beverage-logo' }).map((asset) => asset.src);
 ```
 
-Selector fields combine, so `{ prefix: 'brand/', type: 'image/svg+xml' }` is
-the svg files in that folder.
+An `AssetSelector` has `context`, `prefix`, `tag`, `type` and `keys`, and the
+fields combine — `{ prefix: 'brand/', type: 'image/svg+xml' }` is the svg
+files in that folder. `listAssets()` with no selector is everything loaded,
+and `contextNames()` is the application ids that declared assets.
 
 ## Preloading during bootstrap
 
@@ -160,6 +237,15 @@ which is what makes images pop into view on lower powered hardware. Paying
 for it during a bootstrap sequence trades a couple of seconds at startup for
 screens that render immediately afterwards.
 
+`preloadAssets` takes a group name, a key, an array of either, or a selector:
+
+```ts
+await preloadAssets('boot');                     // a group from the declaration
+await preloadAssets('brand/logo-primary');       // one key
+await preloadAssets(['boot', 'checkout']);       // several
+await preloadAssets({ prefix: 'beverages/' });   // a selector
+```
+
 ```ts
 await preloadAssets({ prefix: 'beverages/' }, {
   concurrency: 4,
@@ -167,23 +253,19 @@ await preloadAssets({ prefix: 'beverages/' }, {
 });
 ```
 
-Assets are readied a few at a time, because a wide fan out on a slow device
-only thrashes. A single asset that cannot be readied is reported through
-`onProgress` with `ok: false` and never fails the sequence, so one bad file
-cannot stop a device from starting.
-
-Images are measured when the declaration is generated, so the space they
-take can be reserved and nothing reflows when they arrive:
+Assets are readied a few at a time (`concurrency`, 4 by default), because a
+wide fan out on a slow device only thrashes. A single asset that cannot be
+readied is reported through `onProgress` with `ok: false` and never fails the
+sequence, so one bad file cannot stop a device from starting.
 
-```tsx
-const logo = wrapAsset('brand/logo-primary');
-<img src={logo.src} width={logo.width} height={logo.height} alt="" />
-```
+`preloadDeclared(options?)` readies every loaded asset whose declaration set
+`preload: true`, so the application doesn't have to know which those are.
+`releaseAssets()` drops the decoded images preloading is holding — worth
+calling when leaving a section whose assets are large and won't be shown
+again.
 
-`{ hold: true }` additionally keeps the bytes as an object url, which is
-worth it only when an asset must survive the content going away.
-`releaseAssets()` drops everything preloading is holding.
+## Where the files come from
 
-Only the contexts named in `initAssets` are requested. Keys resolve in the
-default context (the first one declared) unless they name another, as in
-`other.app.id:brand/logo-primary`.
+Urls are built against the `host` query parameter when there is one, and the
+page's own origin otherwise, so a ui run on a laptop against a device
+resolves assets by opening it with `?host=http://device-address`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kosdev-code/kos-asset-manager",
-  "version": "0.0.1-next.27",
+  "version": "0.0.1-next.29",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -25,7 +25,7 @@
   },
   "kos": {
     "build": {
-      "gitHash": "e99638c2d2d0816216d4ed2d7c167703fc9b687d"
+      "gitHash": "1b2fc996563150e3da055a9506a28b7cb132c060"
     }
   },
   "publishConfig": {