@kosdev-code/kos-asset-manager 0.0.1-next.31 → 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

package/bin/lib/declare-assets.mjs

@@ -57,6 +57,20 @@ const TYPES = {
  */
 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);
@@ -526,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 } : {}),
@@ -539,6 +562,7 @@ export {
   ASSETS_ROOT,
   TYPES,
   DATA_TYPES,
+  BUILD_INPUTS,
   isMedia,
   mediaSource,
   mediaRoot,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kosdev-code/kos-asset-manager",
-  "version": "0.0.1-next.31",
+  "version": "0.0.1-next.32",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -25,7 +25,7 @@
   },
   "kos": {
     "build": {
-      "gitHash": "56c8640462a5c40c4498377f96b18b6da0009421"
+      "gitHash": "c7ed2185841d6bf5f7709af1d03dfbbd838e116b"
     }
   },
   "publishConfig": {