@nebulahome/package-sdk 1.0.1 → 1.2.0

package/dist/testing.js

@@ -38,6 +38,52 @@ async function check(schema, value) {
 }
 //#endregion
 //#region src/testing/index.ts
+/** The most entities and points one read of the past takes, as the platform has it. */
+const HISTORY_MAX_ENTITIES = 64;
+const HISTORY_MAX_POINTS = 1e4;
+/** An hour and a day, in milliseconds. */
+const HOUR_MS = 36e5;
+const DAY_MS = 24 * HOUR_MS;
+/**
+* The resolution the platform reads a window at when a read leaves it to it.
+*
+* @param spanMs - How long the window is.
+* @returns Raw up to an hour, minutes up to 30 hours, hours up to 80 days, days beyond.
+*/
+function resolutionFor(spanMs) {
+	if (spanMs <= HOUR_MS) return "raw";
+	if (spanMs <= 30 * HOUR_MS) return "1m";
+	return spanMs <= 80 * DAY_MS ? "1h" : "1d";
+}
+/**
+* Reads a window of points as the platform does: checked, oldest first, the newest kept.
+*
+* @param read - Which entities, which window, how many points each.
+* @param pointsOf - An entity's points, in any order.
+* @returns Each entity's points in the window, and which lost their oldest.
+* @throws {Error} When the read names no entity or too many, or its window is backwards.
+*/
+function readWindow(read, pointsOf) {
+	const from = new Date(read.from).getTime();
+	const to = new Date(read.to).getTime();
+	const limit = read.limit ?? HISTORY_MAX_POINTS;
+	if (read.entityIds.length === 0 || read.entityIds.length > HISTORY_MAX_ENTITIES) throw new Error(`A read of the past names 1 to ${String(HISTORY_MAX_ENTITIES)} entities`);
+	if (!(from < to)) throw new Error("The window starts at or after it ends");
+	const series = {};
+	const truncated = [];
+	for (const entityId of read.entityIds) {
+		const inWindow = pointsOf(entityId).filter((point) => {
+			const time = new Date(point.time).getTime();
+			return time >= from && time < to;
+		}).toSorted((a, b) => new Date(a.time).getTime() - new Date(b.time).getTime());
+		series[entityId] = inWindow.slice(Math.max(0, inWindow.length - limit));
+		if (inWindow.length > limit) truncated.push(entityId);
+	}
+	return {
+		series,
+		truncated
+	};
+}
 /** Service names the platform keeps for itself. */
 const RESERVED_SERVICES = /* @__PURE__ */ new Set([
 	"command",
@@ -99,6 +145,7 @@ function createTestContext(options = {}) {
 	const reports = [];
 	const logs = [];
 	const entities = new Map((options.entities ?? []).map((each) => [each.entityId, each]));
+	const histories = new Map(Object.entries(options.history ?? {}));
 	const methods = /* @__PURE__ */ new Map();
 	const services = /* @__PURE__ */ new Map();
 	const answers = /* @__PURE__ */ new Map();
@@ -462,6 +509,29 @@ function createTestContext(options = {}) {
 					};
 				}
 			},
+			history: {
+				/**
+				* The changes of some entities in a window.
+				*
+				* @param read - Which, when, how many.
+				* @returns Them, oldest first.
+				*/
+				states: async (read) => Promise.resolve(readWindow(read, (entityId) => histories.get(entityId)?.states ?? [])),
+				/**
+				* The readings of some entities in a window, as given: a test gives the buckets it wants.
+				*
+				* @param read - Which, when, how many, at which resolution.
+				* @returns Them, oldest first, and the resolution.
+				*/
+				telemetry: async (read) => {
+					const span = new Date(read.to).getTime() - new Date(read.from).getTime();
+					const resolution = read.resolution === void 0 || read.resolution === "auto" ? resolutionFor(span) : read.resolution;
+					return Promise.resolve({
+						...readWindow(read, (entityId) => histories.get(entityId)?.telemetry ?? []),
+						resolution
+					});
+				}
+			},
 			rpc: { method: rpcMethod },
 			services: {
 				provide,
@@ -578,6 +648,15 @@ function createTestContext(options = {}) {
 			entities.set(snapshot.entityId, snapshot);
 		},
 		/**
+		* Gives an entity a past.
+		*
+		* @param entityId - The entity.
+		* @param history - Its changes and readings.
+		*/
+		setHistory: (entityId, history) => {
+			histories.set(entityId, history);
+		},
+		/**
 		* Changes an entity of the house.
 		*
 		* @param change - The change.

package/dist/ui.d.ts

@@ -1,5 +1,6 @@
-import { G as CapabilityState, H as CapabilityCommands, S as FormValues, ct as EntityDomain, d as EntityTypeDefinition, f as ValuesOf, i as SettingsDefinition, lt as EntityId, q as CommandableCapability, r as JsonValue, s as ArgsOf, t as JsonObject, u as CommandsOf, z as ValueOfField } from "./chunks/json.js";
+import { G as CapabilityState, H as CapabilityCommands, S as FormValues, Y as DeclaredCapabilities, ct as EntityDomain, d as EntityTypeDefinition, f as ValuesOf, i as SettingsDefinition, lt as EntityId, q as CommandableCapability, r as JsonValue, s as ArgsOf, t as JsonObject, u as CommandsOf, z as ValueOfField } from "./chunks/json.js";
 import { a as PageProps, n as EntityViewProps, t as CardProps } from "./chunks/props.js";
+import { a as TelemetryResolution, i as TelemetryPoint, n as HistorySeries, r as StateHistoryPoint, t as ChangeCause } from "./chunks/history.js";
 import { AnchorHTMLAttributes, ComponentType, ReactElement, ReactNode } from "react";
 //#region src/ui/types.d.ts
 /** The package drawn. */
@@ -15,7 +16,13 @@ type EntityView = {
   readonly name: string;
   readonly icon: string | null;
   readonly deviceId: string | null;
+  /** Its area's key - the entity's own, else its device's - as {@link AreaView} `key` says it. */
   readonly areaId: string | null;
+  /**
+   * What it declares it can do, with the device's limits: a cover's tilt, a thermostat's range
+   * and modes, a select's options. Since 1.2.
+   */
+  readonly capabilities: DeclaredCapabilities;
   readonly state: CapabilityState;
   readonly attributes: JsonObject;
   readonly isAvailable: boolean;
@@ -24,6 +31,79 @@ type EntityView = {
   readonly deviceClass: string | null;
   readonly displayPrecision: number | null;
 };
+/** A window of the past: between two moments (ISO 8601), or the last so many milliseconds. */
+type HistoryWindow = {
+  readonly from: string;
+  readonly to: string;
+} | {
+  readonly lastMs: number;
+};
+/** Which entities' past `useStateHistory` reads, over which window. Since 1.2. */
+type HistoryQuery = {
+  /** At most 64. */
+  readonly entityIds: readonly EntityId[];
+  readonly window: HistoryWindow;
+  /** False holds the read back. */
+  readonly isEnabled?: boolean;
+  /** Reads it again every so often; a window of the last so many milliseconds moves with it. */
+  readonly refetchIntervalMs?: number;
+};
+/** Which entities' readings `useTelemetry` reads: `auto` picks the resolution by the window. */
+type TelemetryQuery = HistoryQuery & {
+  readonly resolution?: TelemetryResolution | 'auto';
+};
+/** A read of the past, as it stands. */
+type History<TPoint> = {
+  /** Each entity's points, oldest first; empty while it loads. */
+  readonly series: HistorySeries<TPoint>;
+  /** The window read, in milliseconds since the epoch; undefined before the first answer. */
+  readonly window: {
+    readonly from: number;
+    readonly to: number;
+  } | undefined;
+  /** The entities whose window held more than one read returns: their oldest points are gone. */
+  readonly truncated: readonly EntityId[];
+  readonly isLoading: boolean;
+  readonly error: Error | null;
+  /** Reads it again. */
+  readonly refetch: () => void;
+};
+/** A read of readings, and the resolution it was read at. */
+type Telemetry = History<TelemetryPoint> & {
+  readonly resolution: TelemetryResolution;
+};
+/** What kind of place an area is. */
+type AreaKind = 'house' | 'floor' | 'room';
+/** One area of the house: the house itself, a floor, a room. Since 1.2. */
+type AreaView = {
+  /** What `EntityView.areaId` names it by. */
+  readonly key: string;
+  readonly name: string;
+  readonly kind: AreaKind;
+  /** The floor a room is on, the house a floor is in; null for the house. */
+  readonly parentKey: string | null;
+  readonly icon: string | null;
+  readonly sortOrder: number;
+  /** A floor's storey: 0 the ground floor, -1 the one below; null for the rest. */
+  readonly level: number | null;
+  /** The house's position, when the owner has set it; null for the rest. */
+  readonly latitude: number | null;
+  readonly longitude: number | null;
+};
+/** How a picture is fetched. */
+type PictureOptions = {
+  /** A camera's still is fetched again this often; 15 seconds when not said, at least 2. */
+  readonly refreshMs?: number;
+  /** False holds it back. */
+  readonly isEnabled?: boolean;
+};
+/** A camera's latest still, or an image entity's picture, as an address an `<img>` shows. */
+type EntityPicture = {
+  /** Null before there is one, or when the entity has none. */
+  readonly url: string | null;
+  readonly isLoading: boolean;
+  readonly error: Error | null;
+};
 /** Which entities `useEntities` reads. */
 type EntitiesFilter = {
   /** Whose: the package's own (the default), anyone's, or another package's by id. */
@@ -128,6 +208,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 +286,16 @@ 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;
+  /** Since 1.2. */
+  readonly useStateHistory: (query: HistoryQuery) => History<StateHistoryPoint>;
+  /** Since 1.2. */
+  readonly useTelemetry: (query: TelemetryQuery) => Telemetry;
+  /** Since 1.2. */
+  readonly useAreas: () => readonly AreaView[];
+  /** Since 1.2. */
+  readonly useEntityPicture: (entityId: EntityId, options?: PictureOptions) => EntityPicture;
   readonly useTheme: () => Theme;
   readonly usePortalContainer: () => HTMLElement | null;
   readonly usePackageRoute: () => PackageRoute;
@@ -272,6 +383,50 @@ 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 recorded changes of some entities over a window, live as the window moves: what a chart of
+ * an on/off thing, an activity list or a replay of a day is drawn from. Read with the viewer's
+ * permissions: an entity they may not read has no points.
+ *
+ * @param query - Which entities (at most 64), which window, how often to read it again.
+ * @returns Each entity's changes, oldest first, and whether the read is still on its way.
+ */
+export declare function useStateHistory(query: HistoryQuery): History<StateHistoryPoint>;
+/**
+ * The numeric readings of some entities over a window: what a sensor's chart is drawn from. A
+ * long window is read in buckets of a minute, an hour or a day, each with its lowest and highest.
+ *
+ * @param query - Which entities (at most 64), which window, which resolution (`auto` by default).
+ * @returns Each entity's readings, oldest first, and the resolution they were read at.
+ */
+export declare function useTelemetry(query: TelemetryQuery): Telemetry;
+/**
+ * The areas of the house: the house itself (with its position, when set), its floors and its
+ * rooms, as the owner arranged them.
+ *
+ * @returns Them, in the owner's order.
+ */
+export declare function useAreas(): readonly AreaView[];
+/**
+ * A camera's latest still, fetched again every so often, or an image entity's picture, fetched
+ * again when it changes: an address an `<img>` shows, let go of when a newer one replaces it.
+ *
+ * @param entityId - A `camera.*` or an `image.*` entity.
+ * @param options - How often a still is fetched again, and whether at all.
+ * @returns The address, or null before there is one.
+ */
+export declare function useEntityPicture(entityId: EntityId, options?: PictureOptions): EntityPicture;
 /**
  * The theme the interface draws in, for what draws its own colours: a canvas, a chart.
  *
@@ -317,4 +472,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 { AreaKind, AreaView, CardProps, ChangeCause, CustomEntityState, EntitiesFilter, EntityPicture, EntityView, EntityViewProps, History, HistoryQuery, HistorySeries, HistoryWindow, Locale, Mutation, MutationOptions, PackageCall, PackageInfo, PackageLinkProps, PackageNavigate, PackageRoute, PackageSettings, PageProps, PictureOptions, PlatformLinkProps, PlatformNavigate, PlatformTarget, PluralEnglish, RpcOptions, RpcState, SendCommand, SettingsPatch, StateHistoryPoint, Telemetry, TelemetryPoint, TelemetryQuery, TelemetryResolution, 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,61 @@ 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 recorded changes of some entities over a window, live as the window moves: what a chart of
+* an on/off thing, an activity list or a replay of a day is drawn from. Read with the viewer's
+* permissions: an entity they may not read has no points.
+*
+* @param query - Which entities (at most 64), which window, how often to read it again.
+* @returns Each entity's changes, oldest first, and whether the read is still on its way.
+*/
+function useStateHistory(query) {
+	return ui("useStateHistory", "1.2")(query);
+}
+/**
+* The numeric readings of some entities over a window: what a sensor's chart is drawn from. A
+* long window is read in buckets of a minute, an hour or a day, each with its lowest and highest.
+*
+* @param query - Which entities (at most 64), which window, which resolution (`auto` by default).
+* @returns Each entity's readings, oldest first, and the resolution they were read at.
+*/
+function useTelemetry(query) {
+	return ui("useTelemetry", "1.2")(query);
+}
+/**
+* The areas of the house: the house itself (with its position, when set), its floors and its
+* rooms, as the owner arranged them.
+*
+* @returns Them, in the owner's order.
+*/
+function useAreas() {
+	return ui("useAreas", "1.2")();
+}
+/**
+* A camera's latest still, fetched again every so often, or an image entity's picture, fetched
+* again when it changes: an address an `<img>` shows, let go of when a newer one replaces it.
+*
+* @param entityId - A `camera.*` or an `image.*` entity.
+* @param options - How often a still is fetched again, and whether at all.
+* @returns The address, or null before there is one.
+*/
+function useEntityPicture(entityId, options) {
+	return ui("useEntityPicture", "1.2")(entityId, options);
+}
+/**
 * The theme the interface draws in, for what draws its own colours: a canvas, a chart.
 *
 * @returns Light or dark.
@@ -177,4 +272,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, useAreas, useCommand, useCustomEntity, useEntities, useEntity, useEntityPicture, useLocale, usePackage, usePackageCall, usePackageMutation, usePackageNavigate, usePackageRoute, usePackageRpc, usePackageSettings, usePlatformNavigate, usePortalContainer, useStateHistory, useTelemetry, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulahome/package-sdk",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Write a NebulaHome package: declare it, build it, and run it on the platform.",
   "license": "MIT",
   "type": "module",
@@ -32,6 +32,10 @@
       "types": "./dist/ui.d.ts",
       "default": "./dist/ui.js"
     },
+    "./sun": {
+      "types": "./dist/sun.d.ts",
+      "default": "./dist/sun.js"
+    },
     "./components": {
       "types": "./dist/components.d.ts",
       "default": "./dist/components.js"
@@ -97,9 +101,9 @@
     "yaml": "^2.9.0",
     "zod": "^4.5.4",
     "@nebulahome/eslint-config": "0.0.0",
+    "@nebulahome/ui": "0.0.0",
     "@nebulahome/tsconfig": "0.0.0",
-    "@nebulahome/contracts": "0.0.0",
-    "@nebulahome/ui": "0.0.0"
+    "@nebulahome/contracts": "0.0.0"
   },
   "scripts": {
     "build": "tsdown && node scripts/build-styles.js",