@nebulahome/package-sdk 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 The SDK's version is the version of the package API the platform implements: a minor version adds
 to it, a major one breaks it, and a patch leaves it as it is.
 
+## 1.1.0
+
+- `useTranslation()` in `@nebulahome/package-sdk/ui`: a package's page, cards and entity views
+  say their strings with `t('clients.title', 'Clients')`, in the viewer's language. The English
+  is the fallback, and a plural takes `{ one, other }` with `count`; outside the interface - a
+  component's unit test - every string is its English.
+- Catalogues: `locales/<language>.json` beside `nebula.config.ts` (`it.json`, `pt-BR.json`), JSON
+  objects of strings nested as the keys are dotted, with i18next's plural suffixes and
+  `{{placeholders}}`. `nebula()` bundles each as a chunk of the interface, loaded only for a viewer
+  who reads that language; `validate` checks them (a language for a name, strings only, plurals
+  with their `_other`, at most 256 KB); `build` warns which strings a catalogue says in English
+  and which of its keys no string uses.
+- What `nebula.config.ts` declares - names, settings, entity types - stays English, as the
+  platform shows it everywhere.
+
+## 1.0.1
+
+- `nebulahome-package --help`, and a mistyped command, work where Vite is not installed -
+  `npx -p @nebulahome/package-sdk nebulahome-package --help` in an empty folder. `validate`,
+  `build` and `pack` run without it say what to install in the package's folder, instead of
+  failing with `ERR_MODULE_NOT_FOUND`.
+
 ## 1.0.0
 
 The first public release.

package/README.md

@@ -86,17 +86,47 @@ import { nebula } from '@nebulahome/package-sdk/vite';
 export default defineConfig({ plugins: [react(), tailwindcss(), nebula()] });
 ```
 
+## Translating the interface
+
+The page, the cards and the entity views say their strings through `useTranslation()`, with the
+English beside each key; a catalogue per language goes in `locales/` next to `nebula.config.ts`:
+
+```tsx
+// src/ui/forecast-card.tsx
+import { useTranslation } from '@nebulahome/package-sdk/ui';
+
+const { t } = useTranslation();
+
+t('forecast.empty', 'No forecast yet');
+t('forecast.days', { one: '{{count}} day', other: '{{count}} days' }, { count: days.length });
+```
+
+```json
+// locales/it.json
+{
+  "forecast": {
+    "empty": "Ancora nessuna previsione",
+    "days_one": "{{count}} giorno",
+    "days_other": "{{count}} giorni"
+  }
+}
+```
+
+A string a catalogue lacks is said in English, and `nebulahome-package build` lists them. What
+`nebula.config.ts` declares (the package's name, its cards' and settings' names, its entity types)
+stays English: the platform shows it the same way to everyone.
+
 ## Entry points
 
-| Import                    | What                                                                                                                                                                                                    |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@nebulahome/package-sdk` | `definePackage`, `defineSettings`, `defineCard`, `defineEntityType`, `definePage`, `defineContainer`, `defineCompose`, `field`, entity id helpers, `SDK_VERSION`, the value types.                      |
-| `/server`                 | `defineServer`, and the context `start` is given: settings (live or restart), devices and entities, typed custom entities, the rest of the house, methods for the interface, services between packages. |
-| `/ui`                     | The props of a page, a card and an entity view; hooks for the package, its methods, its settings, the house, the viewer, the theme; navigation inside the package's page and to the platform's places.  |
-| `/components`             | The part of the interface's design system a package may draw with.                                                                                                                                      |
-| `/vite`                   | `nebula()`, the Vite plugin that builds both halves: the interface in chunks with its CSS scoped to the package, the server bundled whole.                                                              |
-| `/testing`                | `createTestContext()`: run `start` in a unit test, every effect recorded.                                                                                                                               |
-| `/styles.css`             | The interface's Tailwind tokens, to `@reference`.                                                                                                                                                       |
+| Import                    | What                                                                                                                                                                                                      |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@nebulahome/package-sdk` | `definePackage`, `defineSettings`, `defineCard`, `defineEntityType`, `definePage`, `defineContainer`, `defineCompose`, `field`, entity id helpers, `SDK_VERSION`, the value types.                        |
+| `/server`                 | `defineServer`, and the context `start` is given: settings (live or restart), devices and entities, typed custom entities, the rest of the house, methods for the interface, services between packages.   |
+| `/ui`                     | The props of a page, a card and an entity view; hooks for the package, its methods, its settings, the house, the viewer, the theme, its strings; navigation inside the package's page and the platform's. |
+| `/components`             | The part of the interface's design system a package may draw with.                                                                                                                                        |
+| `/vite`                   | `nebula()`, the Vite plugin that builds both halves: the interface in chunks with its CSS scoped to the package, the server bundled whole.                                                                |
+| `/testing`                | `createTestContext()`: run `start` in a unit test, every effect recorded.                                                                                                                                 |
+| `/styles.css`             | The interface's Tailwind tokens, to `@reference`.                                                                                                                                                         |
 
 The `nebulahome-package` command checks, builds and packs a package:
 

package/dist/chunks/host.js

@@ -23,15 +23,16 @@ function hostSdkVersion() {
 	return typeof version === "string" ? version : void 0;
 }
 /**
-* One member of a module the interface lends.
+* One member of a module the interface lends, when it lends it.
+*
+* For a member with a way of its own to do without the interface - `useTranslation` says the
+* English - where {@link hostMember} would refuse.
 *
 * @param module - The module's key.
 * @param name - The member.
-* @param since - The SDK version that added it.
-* @returns The interface's implementation of it.
-* @throws {Error} When there is no interface, or it does not implement the member.
+* @returns The interface's implementation of it, or undefined when there is none.
 */
-function hostMember(module, name, since) {
+function lentMember(module, name) {
 	const nebula = Reflect.get(globalThis, "__nebula");
 	const modules = isRecord(nebula) ? nebula["modules"] : void 0;
 	const lent = isRecord(modules) ? modules[module] : void 0;
@@ -45,9 +46,22 @@ function hostMember(module, name, since) {
 	* @returns True when it can be called or drawn.
 	*/
 	const isLent = (value) => typeof value === "function" || isRecord(value) && "$$typeof" in value;
-	if (isLent(member)) return member;
+	return isLent(member) ? member : void 0;
+}
+/**
+* One member of a module the interface lends.
+*
+* @param module - The module's key.
+* @param name - The member.
+* @param since - The SDK version that added it.
+* @returns The interface's implementation of it.
+* @throws {Error} When there is no interface, or it does not implement the member.
+*/
+function hostMember(module, name, since) {
+	const member = lentMember(module, name);
+	if (member !== void 0) return member;
 	const version = hostSdkVersion();
 	throw new Error(version === void 0 ? `${name} is lent by the NebulaHome interface, and there is none here` : `${name} needs package SDK ${since}; this interface implements ${version}`);
 }
 //#endregion
-export { UI_MODULE as n, hostMember as r, COMPONENTS_MODULE as t };
+export { lentMember as i, UI_MODULE as n, hostMember as r, COMPONENTS_MODULE as t };