@hzblj/kara-expo-plugin 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @hzblj/kara-expo-plugin
+
+## 0.1.0
+
+### Minor Changes
+
+- [`f919c7b`](https://github.com/hzblj/kara-ui/commit/f919c7b06f3798cebd58eef1581076bf1ee61cd1) Thanks [@hzblj](https://github.com/hzblj)! - First release of the kara-ui design system: theme and tokens, the `sx` engine, atoms, molecules, organisms and `Screen`, native tabs (`@hzblj/kara-ui/router`), the KaraUI native module (Liquid Glass, scroll edge effect, native countdown, context menu with preview, rich tooltip, FAB menu), and `KaraProvider` with theme overrides — colours, the app's own fonts, the Material seed, and Material You dynamic colour on Android. Text uses the platform's face by default. Install `@hzblj/kara-ui`; the scoped packages are its building blocks.

package/README.md

@@ -1,3 +1,8 @@
-# Temporary Holding Version
+# @hzblj/kara-expo-plugin
 
-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.
+The optional Expo config plugin of kara-ui. It redefines UIKit semantic colours app-wide, natively, from a JSON file or inline values — `plugins: [['@hzblj/kara-ui', {iosSemanticColors: {file: './ios-colors.json'}}]]`.
+
+**Install [`@hzblj/kara-ui`](https://www.npmjs.com/package/@hzblj/kara-ui) instead.** This package is one of its building
+blocks, published so the umbrella can depend on it; it is versioned together with it and has no standalone docs.
+
+MIT

package/app.plugin.js

@@ -0,0 +1,2 @@
+// The Expo config plugin: `plugins: ['@hzblj/kara-expo-plugin']`. Built from `src/` by `yarn build`.
+module.exports = require('./build').default

package/build/index.d.ts

@@ -0,0 +1,9 @@
+import { type ConfigPlugin } from 'expo/config-plugins';
+import { type IosSemanticColorsProps } from './ios-semantic-colors';
+export type { IosColorAppearances, IosSemanticColorsProps } from './ios-semantic-colors';
+export type KaraUIPluginProps = {
+    /** Redefines UIKit semantic colours app-wide, natively. See `withIosSemanticColors`. */
+    iosSemanticColors?: IosSemanticColorsProps;
+};
+declare const _default: ConfigPlugin<KaraUIPluginProps | undefined>;
+export default _default;

package/build/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_plugins_1 = require("expo/config-plugins");
+const ios_semantic_colors_1 = require("./ios-semantic-colors");
+/**
+ * `plugins: [['@hzblj/kara-ui', {iosSemanticColors: {file: './ios-colors.json'}}]]` in the app config. Optional — the
+ * library needs no native configuration to run. It exists for the one override the theme cannot make from JS: what a
+ * UIKit semantic colour itself resolves to, for every token (and every piece of UIKit) that names it.
+ */
+const withKaraUI = (config, { iosSemanticColors } = {}) => iosSemanticColors ? (0, ios_semantic_colors_1.withIosSemanticColors)(config, iosSemanticColors) : config;
+// Read at prebuild from the shipped package.json, beside `build/` — outside `rootDir`, so not an import.
+const pkg = require('../package.json');
+exports.default = (0, config_plugins_1.createRunOncePlugin)(withKaraUI, pkg.name, pkg.version);

package/build/ios-semantic-colors.d.ts

@@ -0,0 +1,49 @@
+import { type ConfigPlugin } from 'expo/config-plugins';
+/**
+ * Our own values for one UIKit semantic colour. `light` and `dark` are required — a colour set without both
+ * would leave one appearance to fall through to Apple's value, which is the confusing half-override.
+ */
+export type IosColorAppearances = {
+    dark: string;
+    /** Used instead of `dark` when the user has asked for increased contrast. */
+    highContrastDark?: string;
+    /** Used instead of `light` when the user has asked for increased contrast. */
+    highContrastLight?: string;
+    light: string;
+};
+export type IosSemanticColorsProps = {
+    /**
+     * The overrides, keyed by UIKit semantic name. Wins over anything in `file` for the same key, so a designer
+     * can hand over a JSON and the config can still pin one colour.
+     */
+    colors?: Record<string, IosColorAppearances>;
+    /** Path to a JSON file of the same shape, relative to the project root. */
+    file?: string;
+};
+/**
+ * Builds one colour set's `Contents.json`. Exported so the mapping can be exercised without a prebuild.
+ *
+ * A colour set carries one entry per appearance combination it answers. The plain entry is the fallback UIKit uses
+ * when nothing more specific matches, so light lives there rather than under `luminosity: light`.
+ */
+export declare const iosColorSet: (name: string, appearances: IosColorAppearances) => string;
+export declare const assertOverridable: (names: string[]) => void;
+/**
+ * Redefines what a UIKit semantic colour resolves to, app-wide, by writing a colour set of that exact name into
+ * the generated asset catalog. Both bridges look a semantic name up with `UIColor(named:)` *before* falling back
+ * to the platform's own colour, so an asset of that name wins — which is what makes this an override rather than
+ * one more token.
+ *
+ * Two things it does not do, and both matter:
+ *
+ * - It reaches only code that resolves colours *by name*, which means our own tokens. UIKit asking itself for
+ *   `UIColor.label` is a class property, not a lookup, so system chrome is unlikely to follow. Verify on device
+ *   before relying on it.
+ * - It has no Android counterpart. Material roles are computed from the wallpaper, `materialSeed` or the M3
+ *   baseline, none of which an app can reach into — so anything overridden here needs `adaptive(...)` in the
+ *   palette to match on the other platform.
+ *
+ * Prefer `adaptive({light, dark})` in the palette for a single colour. This earns its keep when one semantic
+ * backs many tokens and you want all of them moved by one edit.
+ */
+export declare const withIosSemanticColors: ConfigPlugin<IosSemanticColorsProps>;

package/build/ios-semantic-colors.js

@@ -0,0 +1,193 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withIosSemanticColors = exports.assertOverridable = exports.iosColorSet = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const config_plugins_1 = require("expo/config-plugins");
+/**
+ * The names this plugin will write a colour set for. A value rather than a type because JSON is not type-checked — a
+ * typo would otherwise produce an asset nobody asks for, and the override would silently not apply.
+ *
+ * Deliberately a copy of the theme's `IosSemanticColor` rather than an import of it: the plugin is compiled for Node on
+ * its own, and the theme sits behind platform-split files that only Metro resolves. A name added there and not here
+ * fails loudly at prebuild, listing what is known, rather than silently doing nothing.
+ */
+const OVERRIDABLE = [
+    'blueColor',
+    'clearColor',
+    'darkTextColor',
+    'labelColor',
+    'lightTextColor',
+    'linkColor',
+    'opaqueSeparatorColor',
+    'placeholderTextColor',
+    'quaternaryLabelColor',
+    'quaternarySystemFillColor',
+    'secondaryLabelColor',
+    'secondarySystemBackgroundColor',
+    'secondarySystemFillColor',
+    'secondarySystemGroupedBackgroundColor',
+    'separatorColor',
+    'systemBackgroundColor',
+    'systemBlueColor',
+    'systemBrownColor',
+    'systemCyanColor',
+    'systemFillColor',
+    'systemGray2Color',
+    'systemGray3Color',
+    'systemGray4Color',
+    'systemGray5Color',
+    'systemGray6Color',
+    'systemGrayColor',
+    'systemGreenColor',
+    'systemGroupedBackgroundColor',
+    'systemIndigoColor',
+    'systemMintColor',
+    'systemOrangeColor',
+    'systemPinkColor',
+    'systemPurpleColor',
+    'systemRedColor',
+    'systemTealColor',
+    'systemYellowColor',
+    'tertiaryLabelColor',
+    'tertiarySystemBackgroundColor',
+    'tertiarySystemFillColor',
+    'tertiarySystemGroupedBackgroundColor',
+];
+/** Stamped into every set we write, so a later run can tell ours from one a designer added by hand. */
+const AUTHOR = '@hzblj/kara-ui';
+const COLORSET_SUFFIX = '.colorset';
+const HEX_SHORT = 4;
+const HEX_RGB = 7;
+const HEX_RGBA = 9;
+const ALPHA_MAX = 255;
+const byte = (hex) => `0x${hex.toUpperCase()}`;
+/**
+ * Accepts `#rgb`, `#rrggbb` and `#rrggbbaa` — the forms the palette itself is written in, alpha last, CSS order.
+ * The asset catalog wants the channels as `0xNN` and the alpha as a decimal fraction, hence the split.
+ */
+const components = (name, appearance, hex) => {
+    const value = hex.trim();
+    if (!/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(value)) {
+        throw new Error(`[ios-semantic-colors] "${name}.${appearance}" is "${hex}" — expected #rgb, #rrggbb or #rrggbbaa.`);
+    }
+    const digits = value.length === HEX_SHORT ? [...value.slice(1)].map(digit => `${digit}${digit}`).join('') : value.slice(1, HEX_RGB);
+    const alpha = value.length === HEX_RGBA ? Number.parseInt(value.slice(HEX_RGB), 16) / ALPHA_MAX : 1;
+    return {
+        alpha: alpha.toFixed(3),
+        blue: byte(digits.slice(4, 6)),
+        green: byte(digits.slice(2, 4)),
+        red: byte(digits.slice(0, 2)),
+    };
+};
+const entry = (appearances, components) => ({
+    ...(appearances.length > 0 ? { appearances } : {}),
+    color: { 'color-space': 'srgb', components },
+    idiom: 'universal',
+});
+/**
+ * Builds one colour set's `Contents.json`. Exported so the mapping can be exercised without a prebuild.
+ *
+ * A colour set carries one entry per appearance combination it answers. The plain entry is the fallback UIKit uses
+ * when nothing more specific matches, so light lives there rather than under `luminosity: light`.
+ */
+const iosColorSet = (name, appearances) => {
+    const colors = [
+        entry([], components(name, 'light', appearances.light)),
+        entry([{ appearance: 'luminosity', value: 'dark' }], components(name, 'dark', appearances.dark)),
+    ];
+    if (appearances.highContrastLight) {
+        colors.push(entry([{ appearance: 'contrast', value: 'high' }], components(name, 'highContrastLight', appearances.highContrastLight)));
+    }
+    if (appearances.highContrastDark) {
+        colors.push(entry([
+            { appearance: 'contrast', value: 'high' },
+            { appearance: 'luminosity', value: 'dark' },
+        ], components(name, 'highContrastDark', appearances.highContrastDark)));
+    }
+    return `${JSON.stringify({ colors, info: { author: AUTHOR, version: 1 } }, null, 2)}\n`;
+};
+exports.iosColorSet = iosColorSet;
+const readJsonColors = async (projectRoot, file) => {
+    const filePath = node_path_1.default.resolve(projectRoot, file);
+    try {
+        return JSON.parse(await (0, promises_1.readFile)(filePath, 'utf8'));
+    }
+    catch (cause) {
+        throw new Error(`[ios-semantic-colors] Could not read "${filePath}".`, { cause });
+    }
+};
+const assertOverridable = (names) => {
+    const unknown = names.filter(name => !OVERRIDABLE.some(allowed => allowed === name));
+    if (unknown.length > 0) {
+        throw new Error(`[ios-semantic-colors] Not UIKit semantic colours: ${unknown.join(', ')}. ` +
+            `A name must carry its Objective-C \`Color\` suffix — \`labelColor\`, not \`label\`. ` +
+            `Known: ${OVERRIDABLE.join(', ')}.`);
+    }
+};
+exports.assertOverridable = assertOverridable;
+/**
+ * Removes sets this plugin wrote on an earlier run that are no longer configured. Only ours are touched — the
+ * author stamp is what keeps a hand-authored set safe — and a stale one matters because a colour left in the
+ * catalog keeps overriding long after it was deleted from the config.
+ */
+const removeOrphans = async (catalog, keep) => {
+    const dirents = await (0, promises_1.readdir)(catalog, { withFileTypes: true }).catch(() => []);
+    for (const dirent of dirents) {
+        if (!dirent.isDirectory() || !dirent.name.endsWith(COLORSET_SUFFIX)) {
+            continue;
+        }
+        const name = dirent.name.slice(0, -COLORSET_SUFFIX.length);
+        if (keep.has(name)) {
+            continue;
+        }
+        const setPath = node_path_1.default.join(catalog, dirent.name);
+        const existing = await (0, promises_1.readFile)(node_path_1.default.join(setPath, 'Contents.json'), 'utf8').catch(() => '');
+        if (existing.includes(`"author": "${AUTHOR}"`)) {
+            await (0, promises_1.rm)(setPath, { force: true, recursive: true });
+        }
+    }
+};
+/**
+ * Redefines what a UIKit semantic colour resolves to, app-wide, by writing a colour set of that exact name into
+ * the generated asset catalog. Both bridges look a semantic name up with `UIColor(named:)` *before* falling back
+ * to the platform's own colour, so an asset of that name wins — which is what makes this an override rather than
+ * one more token.
+ *
+ * Two things it does not do, and both matter:
+ *
+ * - It reaches only code that resolves colours *by name*, which means our own tokens. UIKit asking itself for
+ *   `UIColor.label` is a class property, not a lookup, so system chrome is unlikely to follow. Verify on device
+ *   before relying on it.
+ * - It has no Android counterpart. Material roles are computed from the wallpaper, `materialSeed` or the M3
+ *   baseline, none of which an app can reach into — so anything overridden here needs `adaptive(...)` in the
+ *   palette to match on the other platform.
+ *
+ * Prefer `adaptive({light, dark})` in the palette for a single colour. This earns its keep when one semantic
+ * backs many tokens and you want all of them moved by one edit.
+ */
+const withIosSemanticColors = (config, { colors = {}, file } = {}) => (0, config_plugins_1.withDangerousMod)(config, [
+    'ios',
+    async (config) => {
+        const fromFile = file ? await readJsonColors(config.modRequest.projectRoot, file) : {};
+        const merged = { ...fromFile, ...colors };
+        const names = Object.keys(merged);
+        (0, exports.assertOverridable)(names);
+        // Everything is generated — and therefore validated — before anything is written, so a bad hex late in the
+        // map cannot leave the catalog holding half an override.
+        const sets = names.map(name => [name, (0, exports.iosColorSet)(name, merged[name])]);
+        const catalog = node_path_1.default.join(config_plugins_1.IOSConfig.Paths.getSourceRoot(config.modRequest.projectRoot), 'Images.xcassets');
+        for (const [name, contents] of sets) {
+            const setPath = node_path_1.default.join(catalog, `${name}${COLORSET_SUFFIX}`);
+            await (0, promises_1.mkdir)(setPath, { recursive: true });
+            await (0, promises_1.writeFile)(node_path_1.default.join(setPath, 'Contents.json'), contents, 'utf8');
+        }
+        // Sets from an earlier run that are no longer configured, so a deleted override stops overriding.
+        await removeOrphans(catalog, new Set(names));
+        return config;
+    },
+]);
+exports.withIosSemanticColors = withIosSemanticColors;

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@hzblj/kara-expo-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The optional Expo config plugin of @hzblj/kara-ui: redefines UIKit semantic colours app-wide, natively.",
+  "author": "Jan Blazej",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hzblj/kara-ui.git",
+    "directory": "packages/expo-plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/hzblj/kara-ui/issues"
+  },
+  "homepage": "https://github.com/hzblj/kara-ui/tree/main/packages/expo-plugin#readme",
+  "keywords": [
+    "expo",
+    "config-plugin",
+    "kara-ui"
+  ],
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    },
+    "./app.plugin.js": "./app.plugin.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "build",
+    "app.plugin.js"
+  ],
+  "scripts": {
+    "build": "tsc -p ./tsconfig.json",
+    "clean": "rm -rf build",
+    "prepack": "yarn run -T turbo run build --filter=$npm_package_name...",
+    "lint": "yarn run -T concurrently \"yarn biome:check\" \"yarn tsc:check\"",
+    "lint:fix": "yarn run -T biome check --write .",
+    "biome:check": "yarn run -T biome check .",
+    "tsc:check": "tsc -p ./tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "expo": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "expo": "~57.0.22",
+    "typescript": "~7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }