@lvl99dotcom/paintcanvas 0.2.0 → 0.3.1

package/README.md

@@ -75,7 +75,7 @@ Guides and API pages are in [docs/](docs/), a [Docusaurus](https://docusaurus.io
 - [Building your own UI on the engine](docs/docs/engine.md)
 - [Messages and events](docs/docs/messages.md)
 - [Saving and opening drawings](docs/docs/documents.md)
-- [Translations](docs/docs/translations.md)
+- [Translations, and adding your app's own](docs/docs/translations.md)
 - [Icons](docs/docs/icons.md)
 - [Theming](docs/docs/theming.md)
 
@@ -92,7 +92,7 @@ Starts a development server and opens the demo in your browser. It uses the sour
 
 To try it with a pen or touch on another device (e.g. a tablet) on the same network, run `pnpm dev --host` and open the network address it prints. This makes the server reachable by anyone on that network.
 
-The UI text follows your device's languages: on an English (UK) device, edit `locales/en-GB.json` to see text changes.
+The UI text follows your device's languages: on an English (UK) device, edit `locales/en-GB.json` to see text changes. The demo's own text (e.g. the "New drawing" button) is in `demo/locales/`, added the way an app adds its translations.
 
 ## Development
 

package/dist/lib/classes/PaintCanvas/index.js

@@ -13,8 +13,9 @@ import Layer, { createOffscreenCanvas } from "../Layer/index.js";
 import LayerAutosave from "../LayerAutosave/index.js";
 import { brushPresets, eraserPresets } from "../../brushes/index.js";
 import { BUILT_IN_AUTHOR, UNKNOWN_AUTHOR, authorHandle } from "../../brushes/authors/index.js";
-import { BRUSH_PRESET_FILE_FORMAT } from "../../presets/schema.js";
+import "../../presets/index.js";
 import CustomPresets from "../CustomPresets/index.js";
+import { BRUSH_PRESET_FILE_FORMAT } from "../../presets/schema.js";
 import InputSettings from "../InputSettings/index.js";
 import ExternalSheets from "../ExternalSheets/index.js";
 import PatchSender from "../../messages/PatchSender/index.js";

package/dist/lib/i18n/index.d.ts

@@ -26,6 +26,16 @@ export declare const matchLocale: (requested: readonly string[], available: read
  * interpolate("Delete \"{name}\"?", { name: "Sketch" }); // 'Delete "Sketch"?'
  */
 export declare const interpolate: (text: string, values?: Record<string, string | number>) => string;
+/**
+ * A locale's language name, written in that language (so people can find their own), with its first letter in
+ * capitals. Gives the tag itself if the browser can't name it.
+ *
+ * @example
+ * languageName("ja"); // "日本語"
+ * languageName("fr"); // "Français"
+ * languageName("en-GB"); // "English (United Kingdom)"
+ */
+export declare const languageName: (locale: string) => string;
 /** Options for translations */
 export interface TranslationsOptions {
     /** Locales that can be used, and how to load each (default: all the locales that come with PaintCanvas) */
@@ -40,53 +50,80 @@ export interface TranslationsOptions {
  * match for the device, and `setLocale` to any available locale. Locale files load when first used, without reloading
  * the page. Strings missing from a locale come from the fallback locale, then the key itself.
  *
+ * Other projects can add their own strings and locales with `addLocales` and `addStrings`. A locale's strings from
+ * every set load together and are merged in the order the sets were added (PaintCanvas's first), so a key in a later
+ * set replaces the same key in an earlier one. Keys are prefixed by project by convention: `paintCanvas.` for
+ * PaintCanvas's, and e.g. `liveCanvas.` for an app's.
+ *
  * Dispatches a `change` event when the locale or its strings change, so the UI can show the new text.
  *
  * @example
  * const translations = new Translations({ locales: { "en-US": ..., ja: () => import("./ja.json") } });
  * await translations.useDeviceLocale();
- * translations.t("layers.delete", { name: "Sketch" });
+ * translations.t("paintCanvas.layers.delete", { name: "Sketch" });
  */
 export default class Translations extends EventTarget {
-    private readonly loaders;
     private readonly fallback;
-    /** Strings of each locale loaded so far, plus any added */
-    private readonly loaded;
+    /** Sets of strings, in the order they were added */
+    private readonly sources;
+    /** Each locale's strings from every set loaded so far, merged in order */
+    private readonly merged;
     private current;
     /** The locale most recently asked for, so a slow load can't override a later choice */
     private requested?;
     constructor(options?: TranslationsOptions);
     /** The locale in use (an IETF BCP 47 tag, e.g. `ja`) */
     get locale(): string;
-    /** Locales that can be used */
+    /** Locales that can be used: the fallback, and every locale a set of strings can load */
     get locales(): string[];
     /**
      * Switch to the best available locale for the device's languages (`navigator.languages`).
      */
     useDeviceLocale(languages?: readonly string[]): Promise<void>;
     /**
-     * Switch to a locale (the best available match for the tag), loading its strings if needed. Dispatches `change` once
-     * its strings are ready. If loading fails, the current locale stays and this rejects.
+     * Switch to a locale (the best available match for the tag), loading its strings from every set if needed.
+     * Dispatches `change` once they're ready. If loading fails, the current locale stays and this rejects.
      *
      * @example
      * await translations.setLocale("zh-TW"); // uses zh-Hant
      */
     setLocale(tag: string): Promise<void>;
     /**
-     * Add or replace strings for a locale (e.g. the implementer's own wording or extra keys). Dispatches `change` if it's
-     * the locale in use or the fallback.
+     * Add a set of strings for some locales, loaded when first used, after the sets already added (so its keys replace
+     * theirs). Its locales become available. The locale in use and the fallback load straight away, then `change` is
+     * dispatched if the set has strings for either.
      *
      * @example
-     * translations.addStrings("en-US", { "toolbar.brush": "Paintbrush" });
+     * await translations.addLocales({
+     *   "en-US": () => import("./locales/en-US.json"),
+     *   fr: () => import("./locales/fr.json"),
+     * });
+     * translations.t("liveCanvas.share");
+     */
+    addLocales(loaders: Record<string, LocaleLoader>): Promise<void>;
+    /**
+     * Add or replace strings for a locale (e.g. the implementer's own wording or extra keys), after the sets already
+     * added. Dispatches `change` if it's the locale in use or the fallback.
+     *
+     * @example
+     * translations.addStrings("en-US", { "paintCanvas.tool.brush": "Paintbrush" });
      */
     addStrings(locale: string, strings: Strings): void;
+    /**
+     * Load a locale's strings from every set, including sets added while loading, then merge them.
+     */
+    private load;
+    /**
+     * Merge a locale's strings loaded so far from every set, in the order the sets were added.
+     */
+    private merge;
     /**
      * Translate a key, putting values into its `{name}` placeholders. With a numeric `count`, the key's plural form for
-     * the locale is used when there is one (e.g. `presets.imported.one` and `presets.imported.other`). Falls back to the
-     * fallback locale, then the key.
+     * the locale is used when there is one (e.g. `paintCanvas.presets.imported.one` and
+     * `paintCanvas.presets.imported.other`). Falls back to the fallback locale, then the key.
      *
      * @example
-     * translations.t("presets.imported", { count: 3 }); // "Imported 3 brush presets"
+     * translations.t("paintCanvas.presets.imported", { count: 3 }); // "Imported 3 brush presets"
      */
     t(key: string, values?: Record<string, string | number>): string;
 }

package/dist/lib/i18n/index.js

@@ -82,39 +82,102 @@ var matchLocale = (requested, available, fallback = FALLBACK_LOCALE) => {
 */
 var interpolate = (text, values = {}) => text.replace(/\{(\w+)\}/g, (placeholder, name) => Object.hasOwn(values, name) ? String(values[name]) : placeholder);
 /**
+* A locale's language name, written in that language (so people can find their own), with its first letter in
+* capitals. Gives the tag itself if the browser can't name it.
+*
+* @example
+* languageName("ja"); // "日本語"
+* languageName("fr"); // "Français"
+* languageName("en-GB"); // "English (United Kingdom)"
+*/
+var languageName = (locale) => {
+	try {
+		const name = new Intl.DisplayNames([locale], {
+			type: "language",
+			languageDisplay: "standard",
+			fallback: "none"
+		}).of(locale);
+		return name ? name.charAt(0).toLocaleUpperCase(locale) + name.slice(1) : locale;
+	} catch {
+		return locale;
+	}
+};
+/** A locale loader's strings, whether given directly or as a module's default export */
+var unwrap = (module) => "default" in module && typeof module.default === "object" ? module.default : module;
+/**
+* One set of strings for some locales (e.g. PaintCanvas's, or an app's), each loaded once, when first needed.
+*/
+var LocaleSource = class {
+	loaders;
+	/** Strings of each locale loaded so far */
+	strings = /* @__PURE__ */ new Map();
+	/** Loads started, so a locale loading for two callers loads once */
+	loading = /* @__PURE__ */ new Map();
+	constructor(loaders = {}) {
+		this.loaders = loaders;
+	}
+	/**
+	* Load a locale's strings, if this has a loader for it and they aren't loaded yet. A failed load rejects, and can be
+	* tried again.
+	*/
+	load(locale) {
+		const loader = this.loaders[locale];
+		if (!loader || this.strings.has(locale)) return Promise.resolve();
+		let loading = this.loading.get(locale);
+		if (!loading) {
+			loading = loader().then((module) => {
+				this.strings.set(locale, unwrap(module));
+			}, (error) => {
+				this.loading.delete(locale);
+				throw error;
+			});
+			this.loading.set(locale, loading);
+		}
+		return loading;
+	}
+};
+/**
 * The text the UI shows, in the chosen language. Starts in the fallback locale; `useDeviceLocale` switches to the best
 * match for the device, and `setLocale` to any available locale. Locale files load when first used, without reloading
 * the page. Strings missing from a locale come from the fallback locale, then the key itself.
 *
+* Other projects can add their own strings and locales with `addLocales` and `addStrings`. A locale's strings from
+* every set load together and are merged in the order the sets were added (PaintCanvas's first), so a key in a later
+* set replaces the same key in an earlier one. Keys are prefixed by project by convention: `paintCanvas.` for
+* PaintCanvas's, and e.g. `liveCanvas.` for an app's.
+*
 * Dispatches a `change` event when the locale or its strings change, so the UI can show the new text.
 *
 * @example
 * const translations = new Translations({ locales: { "en-US": ..., ja: () => import("./ja.json") } });
 * await translations.useDeviceLocale();
-* translations.t("layers.delete", { name: "Sketch" });
+* translations.t("paintCanvas.layers.delete", { name: "Sketch" });
 */
 var Translations = class extends EventTarget {
-	loaders;
 	fallback;
-	/** Strings of each locale loaded so far, plus any added */
-	loaded = /* @__PURE__ */ new Map();
+	/** Sets of strings, in the order they were added */
+	sources;
+	/** Each locale's strings from every set loaded so far, merged in order */
+	merged = /* @__PURE__ */ new Map();
 	current;
 	/** The locale most recently asked for, so a slow load can't override a later choice */
 	requested;
 	constructor(options = {}) {
 		super();
-		this.loaders = options.locales ?? BUILT_IN_LOCALES;
 		this.fallback = options.fallback ?? "en-US";
-		this.loaded.set(this.fallback, options.fallbackStrings ?? en_US_default);
+		const builtIn = new LocaleSource(options.locales ?? BUILT_IN_LOCALES);
+		builtIn.strings.set(this.fallback, options.fallbackStrings ?? en_US_default);
+		this.sources = [builtIn];
+		this.merge(this.fallback);
 		this.current = this.fallback;
 	}
 	/** The locale in use (an IETF BCP 47 tag, e.g. `ja`) */
 	get locale() {
 		return this.current;
 	}
-	/** Locales that can be used */
+	/** Locales that can be used: the fallback, and every locale a set of strings can load */
 	get locales() {
-		return [.../* @__PURE__ */ new Set([this.fallback, ...Object.keys(this.loaders)])];
+		return [.../* @__PURE__ */ new Set([this.fallback, ...this.sources.flatMap((source) => Object.keys(source.loaders))])];
 	}
 	/**
 	* Switch to the best available locale for the device's languages (`navigator.languages`).
@@ -123,8 +186,8 @@ var Translations = class extends EventTarget {
 		return this.setLocale(matchLocale(languages, this.locales, this.fallback));
 	}
 	/**
-	* Switch to a locale (the best available match for the tag), loading its strings if needed. Dispatches `change` once
-	* its strings are ready. If loading fails, the current locale stays and this rejects.
+	* Switch to a locale (the best available match for the tag), loading its strings from every set if needed.
+	* Dispatches `change` once they're ready. If loading fails, the current locale stays and this rejects.
 	*
 	* @example
 	* await translations.setLocale("zh-TW"); // uses zh-Hant
@@ -132,35 +195,67 @@ var Translations = class extends EventTarget {
 	async setLocale(tag) {
 		const locale = matchLocale([tag], this.locales, this.fallback);
 		this.requested = locale;
-		if (!this.loaded.has(locale)) {
-			const module = await this.loaders[locale]();
-			this.loaded.set(locale, "default" in module && typeof module.default === "object" ? module.default : module);
-		}
+		await this.load(locale);
 		if (this.requested !== locale) return;
 		this.current = locale;
 		this.dispatchEvent(new Event("change"));
 	}
 	/**
-	* Add or replace strings for a locale (e.g. the implementer's own wording or extra keys). Dispatches `change` if it's
-	* the locale in use or the fallback.
+	* Add a set of strings for some locales, loaded when first used, after the sets already added (so its keys replace
+	* theirs). Its locales become available. The locale in use and the fallback load straight away, then `change` is
+	* dispatched if the set has strings for either.
 	*
 	* @example
-	* translations.addStrings("en-US", { "toolbar.brush": "Paintbrush" });
+	* await translations.addLocales({
+	*   "en-US": () => import("./locales/en-US.json"),
+	*   fr: () => import("./locales/fr.json"),
+	* });
+	* translations.t("liveCanvas.share");
+	*/
+	async addLocales(loaders) {
+		this.sources.push(new LocaleSource(loaders));
+		const locales = [.../* @__PURE__ */ new Set([this.current, this.fallback])];
+		await Promise.all(locales.map((locale) => this.load(locale)));
+		if (locales.some((locale) => Object.hasOwn(loaders, locale))) this.dispatchEvent(new Event("change"));
+	}
+	/**
+	* Add or replace strings for a locale (e.g. the implementer's own wording or extra keys), after the sets already
+	* added. Dispatches `change` if it's the locale in use or the fallback.
+	*
+	* @example
+	* translations.addStrings("en-US", { "paintCanvas.tool.brush": "Paintbrush" });
 	*/
 	addStrings(locale, strings) {
-		this.loaded.set(locale, {
-			...this.loaded.get(locale),
-			...strings
-		});
+		const source = new LocaleSource();
+		source.strings.set(locale, strings);
+		this.sources.push(source);
+		this.merge(locale);
 		if (locale === this.current || locale === this.fallback) this.dispatchEvent(new Event("change"));
 	}
 	/**
+	* Load a locale's strings from every set, including sets added while loading, then merge them.
+	*/
+	async load(locale) {
+		let count;
+		do {
+			count = this.sources.length;
+			await Promise.all(this.sources.map((source) => source.load(locale)));
+		} while (count !== this.sources.length);
+		this.merge(locale);
+	}
+	/**
+	* Merge a locale's strings loaded so far from every set, in the order the sets were added.
+	*/
+	merge(locale) {
+		this.merged.set(locale, Object.assign({}, ...this.sources.map((source) => source.strings.get(locale))));
+	}
+	/**
 	* Translate a key, putting values into its `{name}` placeholders. With a numeric `count`, the key's plural form for
-	* the locale is used when there is one (e.g. `presets.imported.one` and `presets.imported.other`). Falls back to the
-	* fallback locale, then the key.
+	* the locale is used when there is one (e.g. `paintCanvas.presets.imported.one` and
+	* `paintCanvas.presets.imported.other`). Falls back to the fallback locale, then the key.
 	*
 	* @example
-	* translations.t("presets.imported", { count: 3 }); // "Imported 3 brush presets"
+	* translations.t("paintCanvas.presets.imported", { count: 3 }); // "Imported 3 brush presets"
 	*/
 	t(key, values) {
 		const count = values?.count;
@@ -170,7 +265,7 @@ var Translations = class extends EventTarget {
 			key
 		] : [key];
 		for (const locale of [this.current, this.fallback]) {
-			const strings = this.loaded.get(locale);
+			const strings = this.merged.get(locale);
 			const found = keys.find((each) => strings && Object.hasOwn(strings, each));
 			if (found) return interpolate(strings[found], values);
 		}
@@ -179,4 +274,4 @@ var Translations = class extends EventTarget {
 };
 /** The translations PaintCanvas's UI uses, unless an element is given others */
 var translations = new Translations();
-export { BUILT_IN_LOCALES, FALLBACK_LOCALE, Translations as default, interpolate, matchLocale, translations };
+export { BUILT_IN_LOCALES, FALLBACK_LOCALE, Translations as default, interpolate, languageName, matchLocale, translations };