@applicaster/quick-brick-assets 0.0.0-stage → 16.0.0-rc.123

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# @applicaster/quick-brick-assets
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Static assets that Quick Brick ships with the app. Only `assets/` and the generated `index.ts` are published.
+
+```
+assets/
+  {plugin_identifier}/
+    ...
+```
+
+| Plugin identifier    | Content                                                         |
+| -------------------- | --------------------------------------------------------------- |
+| `mute_unmute_action` | Default mute / unmute icons for cell actions and mobile buttons |
+
+## Using an asset
+
+Look the asset up by plugin identifier and path relative to the plugin folder:
+
+```ts
+import { getQuickBrickAsset } from "@applicaster/zapp-react-native-utils/quickBrickAssets";
+
+const source = getQuickBrickAsset("mute_unmute_action", "action/flavour_1/mute.png");
+```
+
+- It returns the same value as a static `require` would (a number on native, a URL on web).
+- Both arguments are type-checked against the files in `assets/`: an unknown plugin identifier or path is a compile error.
+- Density variants (`@2x` / `@3x`) aren't supported: webpack's `asset/resource` only follows literal paths, so `generate` fails on them. Use one file per asset.
+- Platform variants (`.ios.png` / `.android.png`) aren't supported.
+
+## How it works
+
+Bundlers only include assets that are `require`d with a static string. `scripts/generate.ts` writes `index.ts`, the package `main`, which maps each `{plugin_identifier}/{path}` to a static `require` of that file under `assets/`:
+
+```ts
+const assets = {
+  "mute_unmute_action/action/flavour_1/mute.png": require("./assets/mute_unmute_action/action/flavour_1/mute.png"),
+  // one entry per file
+};
+
+export type QuickBrickAssetKey = keyof typeof assets;
+```
+
+- `index.ts` is committed and published. Metro and webpack compile it like any other `@applicaster/*` TS source, so there's no bundler config to add.
+- `getQuickBrickAsset` imports the map, and its parameter types come from `QuickBrickAssetKey`. The types and the runtime map are the same object, so they can't disagree.
+- `scripts/` and `__tests__/` are TypeScript sources for maintaining the package and aren't published.
+- In Jest, `tests/quickBrickAssetsMock.js` replaces the map with one that keeps the real keys and uses each key as its value.
+
+The native and web app entries also import `@applicaster/quick-brick-assets`, so `react-native bundle --assets-dest res` (native) and webpack (web) export every file even if nothing looks it up.
+
+## Contributing: adding assets
+
+1. **Put the files under `assets/{plugin_identifier}/`.**
+   - `{plugin_identifier}` is the identifier of the plugin or feature that owns the assets (e.g. `mute_unmute_action`). Never put customer-specific assets here.
+   - Group files in subfolders as you like. The path relative to the plugin folder is the lookup key, so treat it as a public API: renaming or moving a file is a breaking change for its callers.
+   - Use a file type from Metro's `assetExts` (e.g. `png`, `jpg`). If the asset is also used on web, stick to types that the web template's image rule handles (`png`, `svg`, `jpg`, `jpeg`, `gif`, `mp4`). Every file except dotfiles gets a `require`, so don't put anything else (READMEs, sources) under `assets/`. It would break the bundle.
+
+2. **Regenerate the index:**
+
+   ```bash
+   yarn workspace @applicaster/quick-brick-assets generate
+   ```
+
+   This rewrites `index.ts`, so the new file is bundled and its key is accepted by `getQuickBrickAsset`. It doesn't run on `yarn install`. A running `yarn start` picks up the change without a restart.
+
+3. **Use it** through the helper, never with a `require` of a path into this package:
+
+   ```ts
+   getQuickBrickAsset("my_plugin", "icons/icon.png");
+   ```
+
+   In Jest the helper returns the key itself (see `tests/quickBrickAssetsMock.js`), so tests can assert which asset was picked.
+
+4. **Add the plugin identifier to the table** at the top of this README if it's a new folder.
+
+5. **Check and commit:**
+
+   ```bash
+   jest ./packages/quick-brick-assets --config=./tests/jest.unit.config.js
+   ```
+
+   This fails if `index.ts` is out of date with `assets/`. Commit the assets together with `index.ts`, and never edit `index.ts` by hand.
+
+To confirm a file reaches `res/`, bundle a prepared app with `--assets-dest`. Then look for files named `*quickbrickassets_assets_{plugin_identifier}_*` in the `drawable-*` folders:
+
+```bash
+# from development-app/, after `yarn zapplicaster prepare -a <app_id>`
+mkdir -p /tmp/qb/res && npx react-native bundle --platform android --dev false --entry-file development-app/index.js --bundle-output /tmp/qb/index.bundle --assets-dest /tmp/qb/res
+```
+
+Removing or renaming an asset works the same way: run `generate` again, and the type checker shows every call site that still uses the old key.

package/index.ts

@@ -0,0 +1,39 @@
+// Generated by scripts/generate.ts. Do not edit.
+// Run `yarn workspace @applicaster/quick-brick-assets generate` after changing assets/.
+// Static requires make the bundler include every asset (and export it with --assets-dest).
+
+// prettier-ignore
+const assets = {
+  "local-storage-favourites-action/action/flavour_1.png": require("./assets/local-storage-favourites-action/action/flavour_1.png"),
+  "local-storage-favourites-action/action/flavour_1_active.png": require("./assets/local-storage-favourites-action/action/flavour_1_active.png"),
+  "local-storage-favourites-action/action/flavour_1_default.png": require("./assets/local-storage-favourites-action/action/flavour_1_default.png"),
+  "local-storage-favourites-action/action/flavour_2.png": require("./assets/local-storage-favourites-action/action/flavour_2.png"),
+  "local-storage-favourites-action/action/flavour_2_active.png": require("./assets/local-storage-favourites-action/action/flavour_2_active.png"),
+  "local-storage-favourites-action/action/flavour_2_default.png": require("./assets/local-storage-favourites-action/action/flavour_2_default.png"),
+  "local-storage-favourites-action/button/flavour_1.png": require("./assets/local-storage-favourites-action/button/flavour_1.png"),
+  "local-storage-favourites-action/button/flavour_1_active.png": require("./assets/local-storage-favourites-action/button/flavour_1_active.png"),
+  "local-storage-favourites-action/button/flavour_1_default.png": require("./assets/local-storage-favourites-action/button/flavour_1_default.png"),
+  "local-storage-favourites-action/button/flavour_2.png": require("./assets/local-storage-favourites-action/button/flavour_2.png"),
+  "local-storage-favourites-action/button/flavour_2_active.png": require("./assets/local-storage-favourites-action/button/flavour_2_active.png"),
+  "local-storage-favourites-action/button/flavour_2_default.png": require("./assets/local-storage-favourites-action/button/flavour_2_default.png"),
+  "mute_unmute_action/action/flavour_1/mute.png": require("./assets/mute_unmute_action/action/flavour_1/mute.png"),
+  "mute_unmute_action/action/flavour_1/unmute.png": require("./assets/mute_unmute_action/action/flavour_1/unmute.png"),
+  "mute_unmute_action/action/flavour_2/mute.png": require("./assets/mute_unmute_action/action/flavour_2/mute.png"),
+  "mute_unmute_action/action/flavour_2/unmute.png": require("./assets/mute_unmute_action/action/flavour_2/unmute.png"),
+  "mute_unmute_action/button/flavour_1/mute.png": require("./assets/mute_unmute_action/button/flavour_1/mute.png"),
+  "mute_unmute_action/button/flavour_1/unmute.png": require("./assets/mute_unmute_action/button/flavour_1/unmute.png"),
+  "mute_unmute_action/button/flavour_2/mute.png": require("./assets/mute_unmute_action/button/flavour_2/mute.png"),
+  "mute_unmute_action/button/flavour_2/unmute.png": require("./assets/mute_unmute_action/button/flavour_2/unmute.png"),
+};
+
+/** `{plugin_identifier}/{path}` of every asset in this package. */
+export type QuickBrickAssetKey = keyof typeof assets;
+
+/** What `require` returns for an asset: a number on native, a URL on web. */
+export type QuickBrickAssetSource = number | string;
+
+type QuickBrickAssets = Readonly<
+  Record<QuickBrickAssetKey, QuickBrickAssetSource>
+>;
+
+export default assets as QuickBrickAssets;

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@applicaster/quick-brick-assets",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "16.0.0-rc.123",
+  "description": "Static assets bundled by Quick Brick, grouped by plugin identifier",
+  "main": "index.ts",
+  "files": [
+    "assets",
+    "index.ts"
+  ],
+  "scripts": {
+    "generate": "yarn run -T ts-node -P ../../scripts/tsconfig.json scripts/generate.ts"
+  },
+  "keywords": [
+    "Applicaster",
+    "Zapp",
+    "Quick-Brick",
+    "assets"
+  ],
+  "author": "Applicaster",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/applicaster/quickbrick.git"
+  },
+  "bugs": {
+    "url": "https://github.com/applicaster/quickbrick/issues"
+  },
+  "homepage": "https://github.com/applicaster/quickbrick#readme"
 }