@nebulahome/package-sdk 1.0.0 → 1.1.0

package/dist/ui.d.ts

@@ -128,6 +128,27 @@ type Locale = {
   readonly locale: string;
   readonly timeZone: string;
 };
+/** A plural's English: the form for one, and the form for any other number. */
+type PluralEnglish = {
+  readonly one: string;
+  readonly other: string;
+};
+/** What fills a string's `{{placeholders}}`; `count` also picks a plural's form. */
+type TranslationValues = Readonly<Record<string, string | number>>;
+/**
+ * Says one of the package's strings in the viewer's language.
+ *
+ * The key is looked up in the package's catalogue for that language (`locales/it.json`); when it
+ * is not there, the English given here is said instead. A plural takes its English as
+ * `{ one, other }` and the number as `count`: each language's catalogue holds the forms it needs.
+ */
+type Translate = (key: string, english: string | PluralEnglish, values?: TranslationValues) => string;
+/** The package's strings, in the viewer's language. */
+type Translation = {
+  readonly t: Translate;
+  /** The language they are said in, `it`: the viewer's, whether or not the package has it. */
+  readonly locale: string;
+};
 /** Which theme the interface draws in. */
 type Theme = {
   readonly scheme: 'light' | 'dark';
@@ -185,6 +206,8 @@ type UiHost = {
   readonly usePackageSettings: <TSettings extends SettingsDefinition | undefined = undefined>(settings?: TSettings) => PackageSettings<TSettings>;
   readonly useViewer: () => Viewer;
   readonly useLocale: () => Locale;
+  /** Since 1.1. */
+  readonly useTranslation: () => Translation;
   readonly useTheme: () => Theme;
   readonly usePortalContainer: () => HTMLElement | null;
   readonly usePackageRoute: () => PackageRoute;
@@ -272,6 +295,17 @@ export declare function useViewer(): Viewer;
  * @returns Them, for `Intl`.
  */
 export declare function useLocale(): Locale;
+/**
+ * The package's strings in the viewer's language, from the catalogues in its `locales` folder
+ * (PACKAGES_DOCS.md 6.5).
+ *
+ * `t('clients.title', 'Clients')` says the key from the viewer's catalogue, and its English when
+ * the catalogue lacks it; outside an interface that lends this - a component's unit test - every
+ * string is its English.
+ *
+ * @returns `t`, and the language it speaks.
+ */
+export declare function useTranslation(): Translation;
 /**
  * The theme the interface draws in, for what draws its own colours: a canvas, a chart.
  *
@@ -317,4 +351,4 @@ export declare function PackageLink(props: PackageLinkProps): ReactElement;
  */
 export declare function PlatformLink(props: PlatformLinkProps): ReactElement;
 //#endregion
-export type { CardProps, CustomEntityState, EntitiesFilter, EntityView, EntityViewProps, Locale, Mutation, MutationOptions, PackageCall, PackageInfo, PackageLinkProps, PackageNavigate, PackageRoute, PackageSettings, PageProps, PlatformLinkProps, PlatformNavigate, PlatformTarget, RpcOptions, RpcState, SendCommand, SettingsPatch, Theme, UiHost, Viewer, VisibleSettings };
+export type { CardProps, CustomEntityState, EntitiesFilter, EntityView, EntityViewProps, Locale, Mutation, MutationOptions, PackageCall, PackageInfo, PackageLinkProps, PackageNavigate, PackageRoute, PackageSettings, PageProps, PlatformLinkProps, PlatformNavigate, PlatformTarget, PluralEnglish, RpcOptions, RpcState, SendCommand, SettingsPatch, Theme, Translate, Translation, TranslationValues, UiHost, Viewer, VisibleSettings };

package/dist/ui.js

@@ -1,5 +1,45 @@
-import { n as UI_MODULE, r as hostMember } from "./chunks/host.js";
+import { i as lentMember, n as UI_MODULE, r as hostMember } from "./chunks/host.js";
 import { createElement } from "react";
+//#region src/ui/english.ts
+/** A `{{placeholder}}`, as i18next writes it. */
+const PLACEHOLDER = /\{\{\s*(\w+)\s*\}\}/g;
+/**
+* Fills a string's placeholders.
+*
+* @param text - The string.
+* @param values - What fills them; a placeholder with no value is left as written.
+* @returns The string, filled.
+*/
+function interpolate(text, values) {
+	return text.replaceAll(PLACEHOLDER, (whole, name) => {
+		const value = values?.[name];
+		return value === void 0 ? whole : String(value);
+	});
+}
+/**
+* Says a string's English, its plural form chosen by `count`.
+*
+* @param english - The English, or a plural's two forms.
+* @param values - What fills it.
+* @returns The English, filled.
+*/
+function englishOf(english, values) {
+	return interpolate(typeof english === "string" ? english : values?.["count"] === 1 ? english.one : english.other, values);
+}
+/** The package's strings in English. */
+const ENGLISH = {
+	/**
+	* Says a string's English.
+	*
+	* @param key - Its key, unused: there is no catalogue here.
+	* @param english - Its English.
+	* @param values - What fills it.
+	* @returns The English, filled.
+	*/
+	t: (key, english, values) => englishOf(english, values),
+	locale: "en"
+};
+//#endregion
 //#region src/ui/index.ts
 /**
 * `@nebulahome/package-sdk/ui`: what a package's page, cards and entity views are written with
@@ -119,6 +159,20 @@ function useLocale() {
 	return ui("useLocale", "1.0")();
 }
 /**
+* The package's strings in the viewer's language, from the catalogues in its `locales` folder
+* (PACKAGES_DOCS.md 6.5).
+*
+* `t('clients.title', 'Clients')` says the key from the viewer's catalogue, and its English when
+* the catalogue lacks it; outside an interface that lends this - a component's unit test - every
+* string is its English.
+*
+* @returns `t`, and the language it speaks.
+*/
+function useTranslation() {
+	const lent = lentMember(UI_MODULE, "useTranslation");
+	return lent === void 0 ? ENGLISH : lent();
+}
+/**
 * The theme the interface draws in, for what draws its own colours: a canvas, a chart.
 *
 * @returns Light or dark.
@@ -177,4 +231,4 @@ function PlatformLink(props) {
 	return createElement(ui("PlatformLink", "1.0"), props);
 }
 //#endregion
-export { PackageLink, PlatformLink, useCommand, useCustomEntity, useEntities, useEntity, useLocale, usePackage, usePackageCall, usePackageMutation, usePackageNavigate, usePackageRoute, usePackageRpc, usePackageSettings, usePlatformNavigate, usePortalContainer, useTheme, useViewer };
+export { PackageLink, PlatformLink, useCommand, useCustomEntity, useEntities, useEntity, useLocale, usePackage, usePackageCall, usePackageMutation, usePackageNavigate, usePackageRoute, usePackageRpc, usePackageSettings, usePlatformNavigate, usePortalContainer, useTheme, useTranslation, useViewer };

package/dist/vite.d.ts

@@ -52,8 +52,8 @@ type CheckedPackage = {
   readonly generated: GeneratedPackage;
 };
 /**
- * Checks a package without building it: its declaration against the platform's schemas, and the
- * files it names.
+ * Checks a package without building it: its declaration against the platform's schemas, the
+ * files it names, and its translation catalogues.
  *
  * @param options - Where the package is.
  * @returns The package, checked.

package/dist/vite.js

@@ -1,2 +1,3 @@
-import { n as checkPackage, r as nebula, t as buildPackage, w as PackageConfigError } from "./chunks/node-build.js";
+import { n as checkPackage, r as nebula, t as buildPackage } from "./chunks/node-build.js";
+import { t as PackageConfigError } from "./chunks/node-problems.js";
 export { PackageConfigError, buildPackage, checkPackage, nebula };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulahome/package-sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Write a NebulaHome package: declare it, build it, and run it on the platform.",
   "license": "MIT",
   "type": "module",
@@ -96,10 +96,10 @@
     "vitest": "^4.1.11",
     "yaml": "^2.9.0",
     "zod": "^4.5.4",
-    "@nebulahome/tsconfig": "0.0.0",
     "@nebulahome/contracts": "0.0.0",
-    "@nebulahome/eslint-config": "0.0.0",
-    "@nebulahome/ui": "0.0.0"
+    "@nebulahome/tsconfig": "0.0.0",
+    "@nebulahome/ui": "0.0.0",
+    "@nebulahome/eslint-config": "0.0.0"
   },
   "scripts": {
     "build": "tsdown && node scripts/build-styles.js",