@olenbetong/appframe-core 2.13.1 → 2.15.1

package/src/getLocalizedString.ts

@@ -1,6 +1,42 @@
-async function fetchLocalizedString(text: string) {
+/**
+ * Localized strings come from two places on a page:
+ *
+ * - `af.article.i18n`: the strings the article's project uses, rendered by the framework
+ *   into every page of that article. A string missing there is harvested by posting it to
+ *   `/api/user/localize/new/<article>`, which registers it as used by the article and
+ *   returns the translation.
+ * - `af.i18n[<project>]`: the strings of another project, for code that runs on every
+ *   page without belonging to any one article - the site chrome bundle, the shared
+ *   component packages. Such a project is a name, not an article; the harvest endpoint
+ *   accepts any name, so `localize/new/<project>` registers the string under that project.
+ *
+ * Keeping a project's strings apart from the article's matters when a word means
+ * different things: "Articles" is "Artikler" in the chrome and "Varer" in an accounting
+ * app, which the framework's project-specific base strings express only if the two are
+ * looked up in different dictionaries.
+ *
+ * A project's dictionary is in play only when something put it there: the template
+ * rendered it (`@Render("ChromeStrings", Project: "...")`), or the caller fetched it and
+ * assigned `af.i18n[project]` itself (an empty object counts). On a page that did neither -
+ * a legacy template - the project falls back to the article's dictionary and the article's
+ * harvesting, so the page behaves as it always did instead of posting every string of a
+ * grid on every load. The project fills up from the pages that render it.
+ */
+
+export type LocalizeOptions = {
+	/**
+	 * The globalization project the string belongs to. Defaults to the article, whose
+	 * strings the framework renders into `af.article.i18n`. Falls back to the article when
+	 * the page carries no dictionary for the project (see the module comment).
+	 */
+	project?: string;
+	/** Resolve with the translation once it has been fetched, instead of the base text at once. */
+	wait?: boolean;
+};
+
+async function fetchLocalizedString(text: string, project: string) {
 	try {
-		let response = await fetch(`/api/user/localize/new/${af.article.id}`, {
+		let response = await fetch(`/api/user/localize/new/${encodeURIComponent(project)}`, {
 			body: JSON.stringify({ text }),
 			headers: {
 				Accept: "application/json; */*",
@@ -17,12 +53,38 @@ async function fetchLocalizedString(text: string) {
 
 	return text;
 }
+
+type Source = {
+	/** Where the string is looked up and the fetched translation is kept for the page. */
+	dictionary: Record<string, string>;
+	/** The name a missing string is harvested under: the project, or the article's id. */
+	harvestAs: string;
+};
+
+/**
+ * The dictionary a string is resolved in: the project's when the page carries one,
+ * otherwise the article's; nothing when the page has no `af` at all.
+ */
+function sourceFor(project: string | undefined): Source | undefined {
+	let af = globalThis.af;
+	if (!af) return undefined;
+
+	if (project) {
+		let dictionary = af.i18n?.[project];
+		if (dictionary) return { dictionary, harvestAs: project };
+	}
+
+	let article = af.article;
+	if (!article?.i18n) return undefined;
+	return { dictionary: article.i18n, harvestAs: article.id };
+}
+
 export function getLocalizedStringAsync(string: undefined | null): undefined | null;
-export function getLocalizedStringAsync(string: string): Promise<string>;
-export function getLocalizedStringAsync(string: string | undefined | null) {
+export function getLocalizedStringAsync(string: string, options?: Omit<LocalizeOptions, "wait">): Promise<string>;
+export function getLocalizedStringAsync(string: string | undefined | null, options?: Omit<LocalizeOptions, "wait">) {
 	if (!string) return string;
 
-	return getLocalizedString(string, true);
+	return getLocalizedString(string, { ...options, wait: true });
 }
 
 export function getLocalizedString(string: undefined | null): undefined | null;
@@ -30,9 +92,12 @@ export function getLocalizedString(string: string): string;
 export function getLocalizedString(string: string, wait: false): string;
 export function getLocalizedString(string: string, wait: true): Promise<string>;
 export function getLocalizedString(string: undefined | null, wait: true): undefined | null;
+export function getLocalizedString(string: string, options: LocalizeOptions & { wait: true }): Promise<string>;
+export function getLocalizedString(string: string, options: LocalizeOptions): string;
+export function getLocalizedString(string: undefined | null, options: LocalizeOptions): undefined | null;
 export function getLocalizedString(
 	string: string | undefined | null,
-	wait?: boolean,
+	waitOrOptions?: boolean | LocalizeOptions,
 ): string | undefined | null | Promise<string> {
 	if (typeof string === "string" && string.trim().length === 0) {
 		return string;
@@ -42,22 +107,61 @@ export function getLocalizedString(
 		return;
 	}
 
-	if (globalThis.af?.article?.i18n !== undefined) {
-		if (!Object.hasOwn(af.article.i18n, string)) {
-			af.article.i18n[string] = string;
+	let { project, wait } = typeof waitOrOptions === "object" ? waitOrOptions : { wait: waitOrOptions };
+	let source = sourceFor(project);
+	if (source === undefined) {
+		return string;
+	}
 
-			let promise = fetchLocalizedString(string).then((text) => {
-				af.article.i18n[string] = text;
-				return text;
-			});
+	let { dictionary, harvestAs } = source;
+	if (!Object.hasOwn(dictionary, string)) {
+		dictionary[string] = string;
 
-			if (wait) {
-				return promise;
-			}
+		let promise = fetchLocalizedString(string, harvestAs).then((text) => {
+			dictionary[string] = text;
+			return text;
+		});
+
+		if (wait) {
+			return promise;
 		}
+	}
 
-		return af.article.i18n[string];
-	} else {
-		return string;
+	return dictionary[string];
+}
+
+/**
+ * `getLocalizedString` and `localize` bound to a globalization project, for code that is
+ * not part of the article it runs on: the site chrome, the shared component packages.
+ *
+ * On a page whose template renders the project (`af.i18n[project]` exists) the strings are
+ * looked up and harvested there; on any other page they resolve through the article's
+ * dictionary as a plain `getLocalizedString` would.
+ *
+ * @example
+ * ```ts
+ * const { getLocalizedString: t } = createLocalizer("synergi-chrome");
+ * t("Applications");
+ * ```
+ */
+export function createLocalizer(project: string) {
+	function bound(string: undefined | null): undefined | null;
+	function bound(string: string): string;
+	function bound(string: string, wait: true): Promise<string>;
+	function bound(string: string | undefined | null, wait?: boolean): string | undefined | null | Promise<string> {
+		return getLocalizedString(string as string, { project, wait } as LocalizeOptions & { wait: true });
 	}
+
+	function localize(stringParts: TemplateStringsArray, ...args: unknown[]): string {
+		let stringToLocalize = stringParts.map((s, i) => (i === stringParts.length - 1 ? s : `${s}$${i}`)).join("");
+		let localized = bound(stringToLocalize);
+
+		args.forEach((arg, index) => {
+			localized = localized.replace(`$${index}`, String(arg));
+		});
+
+		return localized;
+	}
+
+	return { project, getLocalizedString: bound, localize };
 }

package/src/index.ts

@@ -14,7 +14,7 @@ export type { DownloadItem, DownloadParameters } from "./downloadRequest.js";
 export { downloadRequest } from "./downloadRequest.js";
 export { expose } from "./expose.js";
 export * from "./filter/index.js";
-export { getLocalizedString } from "./getLocalizedString.js";
+export { createLocalizer, getLocalizedString, type LocalizeOptions } from "./getLocalizedString.js";
 export type { getUserImageOptions } from "./getUserImage.js";
 export { getUserImage } from "./getUserImage.js";
 export { invariant } from "./invariant.js";
@@ -50,6 +50,12 @@ export interface AfArticle {
 
 export interface AfCore {
 	article: AfArticle;
+	/**
+	 * Strings of globalization projects other than the article's, by project name, for
+	 * code that runs on every page without belonging to an article (the site chrome).
+	 * Rendered server side or filled by the caller; see `getLocalizedString`'s `project`.
+	 */
+	i18n?: Record<string, Record<string, string>>;
 	common: {
 		getLocalizedString: typeof getLocalizedString;
 		expose: typeof expose;

package/src/report/render.test.ts

@@ -5,6 +5,7 @@ import {
 	getReportExtension,
 	getReportFileName,
 	getReportRequest,
+	openReport,
 	printReport,
 	type ReportRenderOptions,
 	renderReport,
@@ -145,7 +146,41 @@ describe("printReport", () => {
 
 		await printReport(options());
 
-		expect(openMock).toHaveBeenCalledWith(expect.stringContaining("blob:"), "_blank", "noopener");
+		expect(openMock).toHaveBeenCalledWith(expect.stringContaining("blob:"), "_blank");
+	});
+});
+
+describe("openReport", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	function stubRender() {
+		vi.stubGlobal(
+			"fetch",
+			vi.fn().mockResolvedValue(new Response("%PDF-", { headers: { "Content-Type": "application/pdf" } })),
+		);
+	}
+
+	it("keeps the file available to the tab it opened, and cuts the tab off from the opener", async () => {
+		let tab = { opener: {} as unknown };
+		let revoke = vi.spyOn(URL, "revokeObjectURL");
+		stubRender();
+		vi.stubGlobal("open", vi.fn().mockReturnValue(tab));
+
+		await openReport(options());
+
+		expect(revoke).not.toHaveBeenCalled();
+		expect(tab.opener).toBeNull();
+	});
+
+	it("reports a blocked pop-up and releases the file", async () => {
+		let revoke = vi.spyOn(URL, "revokeObjectURL");
+		stubRender();
+		vi.stubGlobal("open", vi.fn().mockReturnValue(null));
+
+		await expect(openReport(options())).rejects.toThrow("Allow pop-ups");
+		expect(revoke).toHaveBeenCalled();
 	});
 });
 

package/src/report/render.ts

@@ -193,13 +193,18 @@ export async function openReport(options: ReportRenderOptions): Promise<void> {
 	// The route serves some formats as types a browser downloads rather than
 	// displays; the format's own media type is what decides how it opens.
 	let url = URL.createObjectURL(blob.type ? blob : new Blob([blob], { type: getReportMediaType(options.format) }));
-	let opened = globalThis.open(url, "_blank", "noopener");
+	// Not opened with the `noopener` feature: `open` then returns null even when
+	// the tab opens, which read as a blocked pop-up and revoked the URL before
+	// the tab could load it. The opener is cut off by hand instead.
+	let opened = globalThis.open(url, "_blank");
 
 	if (!opened) {
 		URL.revokeObjectURL(url);
 		throw new Error("The report could not be opened. Allow pop-ups for this site and try again.");
 	}
 
+	opened.opener = null;
+
 	// Revoking immediately would cancel the load in some browsers, and never
 	// revoking keeps the whole rendered report in memory.
 	globalThis.setTimeout(() => URL.revokeObjectURL(url), 60_000);