@kosdev-code/kos-asset-manager 0.0.1-next.3 → 0.0.1-next.30

package/README.md

@@ -119,37 +119,179 @@ keys when the declaration is generated:
 
 A pattern that matches nothing is reported during the build.
 
-## Using assets in a ui
+## Media somewhere else
+
+`src/assets/media` is the ui default. A content project — a brandset, a
+descriptor pack — usually keeps its media elsewhere and ships it at a
+different path inside the kab, so both are settable:
+
+```json
+{
+  "kondra": {
+    "ui": {
+      "assets": {
+        "mediaSrc": "assets/logos",
+        "mediaRoot": "/logos",
+        "groups": { "boot": ["coke/**"] }
+      }
+    }
+  }
+}
+```
+
+`mediaSrc` is where the files are **on disk**, relative to the project root.
+`mediaRoot` is where they land **inside the kab**, which is what urls are
+built from. They are two different things — a project using vite's
+`publicDir` drops the directory name on the way out, so `assets/logos` on
+disk is `/logos` in the kab — and neither can be derived from the other.
+Leave both out and you get `src/assets/media` and `/assets/media`.
+
+Keys are still relative to `mediaSrc`, so `assets/logos/coke/pour.svg` is the
+key `coke/pour`, and bindings, groups and tags work exactly as they do
+anywhere else.
+
+The build checks its work: every declared file has to be in the build output
+under `mediaRoot`, and if none of them are the build fails naming the setting
+rather than leaving a kab whose every image 404s on the device.
+
+```
+kos-assets: 214 declared assets are not in the build output under
+/assets/media — check mediaRoot in .kos.json, and that the build copies
+the media into dist/content/ui-brandset/assets/media
+```
+
+You don't have to work either of them out by hand. `kos-assets init` looks
+for the media on disk, and reads where the build puts it out of the build
+output — exact, where guessing from the source path would be wrong for any
+project that rewrites paths on the way out:
+
+```sh
+npx nx run ui-brandset:build     # so there is an output to read
+npx kos-assets init content/ui-brandset
+```
+
+```
+kos-assets: found media in assets/logos
+kos-assets: it is served from /logos in the kab
+kos-assets: recorded the media location in content/ui-brandset/.kos.json
+kos-assets: added the assets target to content/ui-brandset/project.json
+```
+
+It writes only what it can establish and never touches a value already
+there, so a project it gets wrong is corrected by setting it and running
+again. Without a build output it records `mediaSrc` and says it could not
+tell what the root is, rather than guessing one. The target it writes then
+scans the right folder and follows the project's own `descriptor` target
+wherever that writes.
+
+## 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>
+);
+```
+
+`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.
 
-// ready assets ahead of a screen that needs them
-await preloadAssets('checkout');
+`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 +302,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 +318,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/bin/kos-assets.mjs

@@ -10,11 +10,13 @@
  * adds the target that runs it to the project.
  */
 import { existsSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 
 import {
-  SOURCE_DIR,
   buildAssets,
+  detectMediaRoot,
+  detectMediaSrc,
+  mediaSource,
   readJson,
   writeJson,
 } from './lib/declare-assets.mjs';
@@ -24,10 +26,129 @@ const fail = (message) => {
   process.exit(1);
 };
 
-const build = (projectRoot, out) => {
-  const descriptorPath = resolve(
-    out ?? join('dist', projectRoot, 'descriptor.json')
+/**
+ * The declared paths are only useful if the files are actually in the kab at
+ * the root the declaration names. The build output is what gets zipped, so
+ * it can be checked here -- which turns a wrong `mediaRoot` into a build
+ * error rather than an image that 404s on the device.
+ */
+const verifyContents = (assets, outputDir) => {
+  const missing = Object.values(assets.entries).filter(
+    (entry) => !existsSync(join(outputDir, assets.root, entry.path))
   );
+  if (missing.length === 0) {
+    return;
+  }
+
+  const total = Object.keys(assets.entries).length;
+  const root = assets.root || '/';
+  if (missing.length === total) {
+    fail(
+      `${total} declared assets are not in the build output under ${root} — ` +
+        `check mediaRoot in .kos.json, and that the build copies the media ` +
+        `into ${join(outputDir, assets.root)}`
+    );
+  }
+  console.warn(
+    `kos-assets: ${missing.length} of ${total} declared assets are not in ` +
+      `the build output: ${missing
+        .slice(0, 5)
+        .map((entry) => entry.path)
+        .join(', ')}${missing.length > 5 ? ', …' : ''}`
+  );
+};
+
+/** Where the descriptor lands unless the project says otherwise. */
+const defaultDescriptor = (projectRoot) =>
+  join('dist', projectRoot, 'descriptor.json');
+
+/**
+ * The media directory the project declares, for the target's inputs. A
+ * project that keeps its media somewhere else still has to invalidate the
+ * cache when it changes.
+ */
+const readDeclared = (projectRoot) => {
+  const dotKos = resolve(projectRoot, '.kos.json');
+  return existsSync(dotKos)
+    ? readJson(dotKos)?.kondra?.ui?.assets ?? {}
+    : {};
+};
+
+const mediaGlob = (declared) => mediaSource(declared).join('/');
+
+/**
+ * Write a detected media location into the project's .kos.json, so a project
+ * that keeps its media somewhere other than the ui default is wired up
+ * without having to be told where it is.
+ *
+ * Only what can be established is written: `mediaSrc` comes off the disk,
+ * and `mediaRoot` off a build output, which is exact where guessing from the
+ * source path would be wrong for any project that rewrites paths on the way
+ * out. Nothing already declared is touched.
+ */
+const detectLayout = (projectRoot, declared, outputDir) => {
+  const dotKos = resolve(projectRoot, '.kos.json');
+  if (!existsSync(dotKos)) {
+    return declared;
+  }
+
+  const found = { ...declared };
+  if (!found.mediaSrc) {
+    const detected = detectMediaSrc(projectRoot);
+    if (detected) {
+      found.mediaSrc = detected;
+      console.log(`kos-assets: found media in ${detected}`);
+    }
+  }
+  if (found.mediaSrc && found.mediaRoot === undefined) {
+    const root = detectMediaRoot(
+      projectRoot,
+      mediaSource(found),
+      resolve(outputDir)
+    );
+    if (root === undefined) {
+      console.warn(
+        `kos-assets: could not tell where ${found.mediaSrc} ends up inside ` +
+          `the kab — build the project and run init again, or set ` +
+          `kondra.ui.assets.mediaRoot in .kos.json`
+      );
+    } else {
+      found.mediaRoot = root;
+      console.log(`kos-assets: it is served from ${root || '/'} in the kab`);
+    }
+  }
+
+  if (found.mediaSrc === declared.mediaSrc &&
+      found.mediaRoot === declared.mediaRoot) {
+    return declared;
+  }
+
+  const kos = readJson(dotKos);
+  kos.kondra = {
+    ...kos.kondra,
+    ui: { ...kos.kondra?.ui, assets: { ...kos.kondra?.ui?.assets, ...found } },
+  };
+  writeJson(dotKos, kos);
+  console.log(`kos-assets: recorded the media location in ${dotKos}`);
+  return found;
+};
+
+/**
+ * Where the project's descriptor target writes, which is not always
+ * `dist/<projectRoot>` -- content projects in particular often point
+ * somewhere else, and the assets target has to follow it.
+ */
+const descriptorTarget = (project, projectRoot) => {
+  const options = project.targets?.descriptor?.options;
+  if (!options?.outputPath) {
+    return defaultDescriptor(projectRoot);
+  }
+  const dir = options.outputPath.replace('{projectRoot}', projectRoot);
+  return join(dir, options.fileName ?? 'descriptor.json');
+};
+
+const build = (projectRoot, out) => {
+  const descriptorPath = resolve(out ?? defaultDescriptor(projectRoot));
   if (!existsSync(descriptorPath)) {
     fail(
       `no descriptor at ${descriptorPath} — run the descriptor target first, or pass --out`
@@ -40,6 +161,8 @@ const build = (projectRoot, out) => {
     return;
   }
 
+  verifyContents(assets, dirname(descriptorPath));
+
   const descriptor = readJson(descriptorPath);
   descriptor.kondra = {
     ...descriptor.kondra,
@@ -81,17 +204,30 @@ const init = (projectRoot) => {
 
   const project = readJson(path);
   project.targets = project.targets ?? {};
+
+  // follow the project's own descriptor target rather than assuming where it
+  // writes, so a content project is wired correctly without a manual --out
+  const descriptor = descriptorTarget(project, projectRoot);
+  const out =
+    descriptor === defaultDescriptor(projectRoot) ? '' : ` --out ${descriptor}`;
+
+  const declared = detectLayout(
+    projectRoot,
+    readDeclared(projectRoot),
+    dirname(descriptor)
+  );
+
   // the declaration is written into a build output, so nx needs to know what
   // it reads and what it produces — otherwise a restored build can be paired
   // with a freshly scanned declaration and the kab ships a mismatch
   project.targets.assets = {
-    command: `${invocation()} build ${projectRoot}`,
+    command: `${invocation()} build ${projectRoot}${out}`,
     dependsOn: ['descriptor'],
     inputs: [
-      `{projectRoot}/${SOURCE_DIR.join('/')}/**/*`,
+      `{projectRoot}/${mediaGlob(declared)}/**/*`,
       '{projectRoot}/.kos.json',
     ],
-    outputs: ['{workspaceRoot}/dist/{projectRoot}/descriptor.json'],
+    outputs: [`{workspaceRoot}/${descriptor}`],
   };
 
   const zip = project.targets.zip;

package/bin/lib/declare-assets.mjs

@@ -12,6 +12,26 @@ import { join, resolve } from 'node:path';
 
 const SOURCE_DIR = ['src', 'assets', 'media'];
 const ASSETS_ROOT = '/assets/media';
+
+/**
+ * Where a project keeps its media, and where that media ends up inside the
+ * kab. They are two different things -- the project's build step decides the
+ * mapping between them, and a content project using vite's `publicDir` drops
+ * the directory name on the way out -- so neither can be derived from the
+ * other. A project that doesn't say gets the ui defaults.
+ *
+ *   "assets": { "mediaSrc": "assets/logos", "mediaRoot": "/logos" }
+ */
+const mediaSource = (declared) =>
+  declared.mediaSrc ? declared.mediaSrc.split('/').filter(Boolean) : SOURCE_DIR;
+
+const mediaRoot = (declared) => {
+  if (!declared.mediaRoot) {
+    return declared.mediaSrc ? '' : ASSETS_ROOT;
+  }
+  const trimmed = declared.mediaRoot.replace(/\/+$/, '');
+  return trimmed === '/' || trimmed === '' ? '' : `/${trimmed.replace(/^\/+/, '')}`;
+};
 const TYPES = {
   '.avif': 'image/avif',
   '.gif': 'image/gif',
@@ -243,6 +263,114 @@ const boundKey = (rel, bindings) => {
   return undefined;
 };
 
+/** Never a project's own media, and expensive to walk. */
+const SKIP_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'tmp',
+  'coverage',
+  '.git',
+  '.nx',
+  '.kos',
+]);
+
+/** Every media file below a directory, by extension, with its path. */
+const scanMedia = (dir, prefix = '') =>
+  readdirSync(dir, { withFileTypes: true }).flatMap((item) => {
+    if (item.name.startsWith('.') || SKIP_DIRS.has(item.name)) return [];
+    const rel = prefix ? `${prefix}/${item.name}` : item.name;
+    if (item.isDirectory()) return scanMedia(join(dir, item.name), rel);
+    const ext = item.name.slice(item.name.lastIndexOf('.')).toLowerCase();
+    return TYPES[ext] ? [rel] : [];
+  });
+
+/** The deepest directory every one of these paths sits under. */
+const commonDir = (paths) => {
+  const segments = paths.map((path) => path.split('/').slice(0, -1));
+  const [first = [], ...rest] = segments;
+  let shared = first;
+  for (const other of rest) {
+    let i = 0;
+    while (i < shared.length && shared[i] === other[i]) i += 1;
+    shared = shared.slice(0, i);
+  }
+  return shared.join('/');
+};
+
+/** True when this directory holds media, or leads to some. */
+const holdsMedia = (dir) => scanMedia(dir).length > 0;
+
+/**
+ * The common ancestor of a project's media is too deep when the media
+ * happens to sit in one subfolder -- a brandset with a single brand would be
+ * read as that brand. So climb back up while the parent holds nothing but
+ * media, which stops at the directory the project actually treats as its
+ * media root: the one with something else beside it.
+ */
+const climbToMedia = (projectRoot, dir) => {
+  const segments = dir.split('/').filter(Boolean);
+  while (segments.length > 1) {
+    const parent = segments.slice(0, -1);
+    const entries = readdirSync(resolve(projectRoot, ...parent), {
+      withFileTypes: true,
+    }).filter(
+      (item) => !item.name.startsWith('.') && !SKIP_DIRS.has(item.name)
+    );
+    const onlyMedia = entries.every((item) =>
+      item.isDirectory()
+        ? holdsMedia(resolve(projectRoot, ...parent, item.name))
+        : TYPES[item.name.slice(item.name.lastIndexOf('.')).toLowerCase()]
+    );
+    if (!onlyMedia) {
+      break;
+    }
+    segments.pop();
+  }
+  return segments.join('/');
+};
+
+/**
+ * Where a project already keeps its media, for a project that hasn't said.
+ * Returns undefined when it is already in the ui default place, or when
+ * there is no media to find.
+ */
+const detectMediaSrc = (projectRoot) => {
+  if (existsSync(resolve(projectRoot, ...SOURCE_DIR))) {
+    return undefined;
+  }
+  const found = scanMedia(resolve(projectRoot));
+  if (found.length === 0) {
+    return undefined;
+  }
+  const dir = commonDir(found);
+  return dir === '' ? undefined : climbToMedia(projectRoot, dir);
+};
+
+/**
+ * Where a media directory ends up inside the kab, read off a build output
+ * rather than guessed: find a file the build already copied and take the
+ * path it was copied to. Undefined when the project hasn't been built, or
+ * when the build doesn't carry the media at all.
+ */
+const detectMediaRoot = (projectRoot, source, outputDir) => {
+  const mediaDir = resolve(projectRoot, ...source);
+  if (!existsSync(mediaDir) || !existsSync(outputDir)) {
+    return undefined;
+  }
+  const [sample] = scanMedia(mediaDir);
+  if (!sample) {
+    return undefined;
+  }
+  const built = scanMedia(resolve(outputDir)).filter(
+    (path) => path === sample || path.endsWith(`/${sample}`)
+  );
+  if (built.length !== 1) {
+    return undefined;
+  }
+  const root = built[0].slice(0, built[0].length - sample.length);
+  return root === '' ? '' : `/${root.replace(/\/+$/, '')}`;
+};
+
 const fail = (message) => {
   console.error(`kos-assets: ${message}`);
   process.exit(1);
@@ -269,16 +397,22 @@ const walk = (dir, prefix = '') =>
  * groups and preload flags are authored in .kos.json and carried through.
  */
 const buildAssets = (projectRoot) => {
-  const mediaDir = resolve(projectRoot, ...SOURCE_DIR);
-  if (!existsSync(mediaDir)) {
-    return undefined;
-  }
-
   const dotKos = resolve(projectRoot, '.kos.json');
   const declared = existsSync(dotKos)
     ? readJson(dotKos)?.kondra?.ui?.assets ?? {}
     : {};
 
+  const source = mediaSource(declared);
+  const mediaDir = resolve(projectRoot, ...source);
+  if (!existsSync(mediaDir)) {
+    // a project that named its media directory meant it, so a typo there is
+    // a build error rather than a project that quietly declares nothing
+    if (declared.mediaSrc) {
+      fail(`no media directory at ${join(projectRoot, ...source)} (mediaSrc)`);
+    }
+    return undefined;
+  }
+
   const bindings = declared.keys ?? {};
   const markers = readMarkers(mediaDir);
   const claimed = new Set();
@@ -379,7 +513,7 @@ const buildAssets = (projectRoot) => {
   }
 
   return {
-    root: ASSETS_ROOT,
+    root: mediaRoot(declared),
     entries,
     ...(Object.keys(groups).length > 0 ? { groups } : {}),
   };
@@ -390,6 +524,13 @@ export {
   SOURCE_DIR,
   ASSETS_ROOT,
   TYPES,
+  mediaSource,
+  mediaRoot,
+  scanMedia,
+  commonDir,
+  climbToMedia,
+  detectMediaSrc,
+  detectMediaRoot,
   parseMarker,
   readMarkers,
   bindingMatcher,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kosdev-code/kos-asset-manager",
-  "version": "0.0.1-next.3",
+  "version": "0.0.1-next.30",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -25,7 +25,7 @@
   },
   "kos": {
     "build": {
-      "gitHash": "57650e696a0e7be23bbacfa175acdce4d8425420"
+      "gitHash": "630400cd67fd24b5cd069b7661dae83277c18934"
     }
   },
   "publishConfig": {