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

package/README.md

@@ -184,6 +184,55 @@ 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.
 
+## Content in its own section
+
+Content usually ships inside an application's section, and then it belongs to
+that application: the kab's assets join the application's context and are
+addressed by its id. Content that ships in a section of its own has no
+application to take a name from, so it names itself:
+
+```json
+{
+  "kondra": {
+    "ui": {
+      "assets": {
+        "context": "tccc.brandset",
+        "mediaSrc": "assets/logos",
+        "mediaRoot": "/logos"
+      }
+    }
+  }
+}
+```
+
+That name is what a ui asks for and addresses it by, exactly like an
+application id:
+
+```tsx
+<KosAssetProvider contexts={['my.app.id', 'tccc.brandset']} gate>
+```
+
+```ts
+wrapAsset('tccc.brandset:coke/pour');
+```
+
+Content in its own section that names nothing belongs to its manifest
+section, under the section's name. Two kabs naming the same context
+contribute to the same one.
+
+Shipping separately is also what lets content replace what an application
+declares. Within one context the first declaration of a key wins and the rest
+are ignored, so a brandset packaged alongside an application can only add to
+it. As its own context it is a separate set of keys, and a ui chooses which
+one wins by the order it lists them in `contexts`.
+
+Everything you author under `kondra.ui.assets` carries through to the
+declaration, with what the build derives landing on top. The exception is the
+handful of settings that drive the build rather than describe the result —
+`keys`, `tags`, `mediaSrc`, `mediaRoot`, and the pattern form of `groups` and
+`entries` — which are expanded into what the device reads and not shipped as
+written.
+
 ## Installing
 
 ```sh
@@ -275,6 +324,38 @@ 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`.
 
+## Loading data in a model
+
+Json is declared like any other asset, which makes it fetchable by key:
+
+```ts
+import { loadAsset } from '@kosdev-code/kos-asset-manager';
+
+@kosModel({ modelTypeId: MODEL_TYPE })
+export class MenuModelImpl {
+  async load(): Promise<void> {
+    const menu = await loadAsset<MenuDto>('config/menu');
+    if (!menu) return;
+    this.reconcile(menu.items);
+  }
+}
+```
+
+Data usually has to be parsed and normalised into a model's own shape
+anyway, so this is deliberately a plain async call rather than something a
+component reads. The point is the key: the file can be renamed, moved, or
+moved into a different kab without the model changing.
+
+Undefined comes back when the key isn't declared, the fetch fails, or the
+content isn't valid json, each logged with the key — so a model handles it
+the way it already handles a service returning nothing. `loadAssetText(key)`
+is the same without the parse.
+
+Json files are declared and keyed like anything else, but they don't count
+as media when `kos-assets init` works out where a project keeps its media —
+a manifest sitting beside a folder of images is what marks the images as the
+media, not the whole folder.
+
 ## Selecting sets
 
 Sets of assets are selected rather than named, so adding a file to a folder

package/bin/lib/declare-assets.mjs

@@ -45,6 +45,35 @@ const TYPES = {
   '.webm': 'video/webm',
   '.webp': 'image/webp',
   '.woff2': 'font/woff2',
+  '.json': 'application/json',
+};
+
+/**
+ * Data assets are declared like any other, but they are not what makes a
+ * directory a project's media directory -- a brandset keeps its manifest
+ * beside its images, and it is the manifest sitting there that tells you the
+ * images are the media rather than the whole folder. So layout detection
+ * looks past them.
+ */
+const DATA_TYPES = new Set(['.json']);
+
+/**
+ * Authored to drive the build rather than to be read on the device. Patterns
+ * and partial entries are expanded into the real thing, so passing them
+ * through would ship a `groups` of patterns the device would read as keys.
+ */
+const BUILD_INPUTS = new Set([
+  'keys',
+  'tags',
+  'entries',
+  'groups',
+  'mediaSrc',
+  'mediaRoot',
+]);
+
+const isMedia = (name) => {
+  const ext = name.slice(name.lastIndexOf('.')).toLowerCase();
+  return Boolean(TYPES[ext]) && !DATA_TYPES.has(ext);
 };
 
 /**
@@ -280,8 +309,7 @@ const scanMedia = (dir, prefix = '') =>
     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] : [];
+    return isMedia(item.name) ? [rel] : [];
   });
 
 /** The deepest directory every one of these paths sits under. */
@@ -319,7 +347,7 @@ const climbToMedia = (projectRoot, dir) => {
     const onlyMedia = entries.every((item) =>
       item.isDirectory()
         ? holdsMedia(resolve(projectRoot, ...parent, item.name))
-        : TYPES[item.name.slice(item.name.lastIndexOf('.')).toLowerCase()]
+        : isMedia(item.name)
     );
     if (!onlyMedia) {
       break;
@@ -512,7 +540,16 @@ const buildAssets = (projectRoot) => {
     );
   }
 
+  // what a project authors under kondra.ui.assets carries through to the
+  // declaration, and what the build derives lands on top of it -- so a field
+  // the device reads, like the context a brandset belongs to, is authored
+  // once and needs nothing here to know about it
+  const authored = Object.fromEntries(
+    Object.entries(declared).filter(([key]) => !BUILD_INPUTS.has(key))
+  );
+
   return {
+    ...authored,
     root: mediaRoot(declared),
     entries,
     ...(Object.keys(groups).length > 0 ? { groups } : {}),
@@ -524,6 +561,9 @@ export {
   SOURCE_DIR,
   ASSETS_ROOT,
   TYPES,
+  DATA_TYPES,
+  BUILD_INPUTS,
+  isMedia,
   mediaSource,
   mediaRoot,
   scanMedia,

package/index.d.ts

@@ -5,6 +5,7 @@ export { registerAssetModels } from './registration';
 export { contextNames } from './runtime/assets';
 export { KosAssetProvider, KosAssetContext, useAssetManager, useKosAssetContext, } from './runtime/asset-provider';
 export { resolveAsset, wrapAsset, hasAsset, listAssets } from './runtime/resolve';
+export { loadAsset, loadAssetText } from './runtime/data';
 export { preloadAssets, preloadDeclared, releaseAssets, } from './runtime/preload';
 export type { AssetSelector, PreloadOptions, PreloadProgress, ResolvedAsset, } from './runtime/types';
 //# sourceMappingURL=index.d.ts.map