@nebulahome/package-sdk 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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.4.0
+
+- **Toasts.** `useToast()` from `@nebulahome/package-sdk/ui` shows the interface's own toasts -
+  `success`, `warning`, `error`, `info`, each with a title, a line or two and at most one action -
+  for the outcome of something the viewer just did.
+
+## 1.3.0
+
+- **The page's actions in its header.** `<PageActions>` from `@nebulahome/package-sdk/ui` draws
+  its children in the header of the package's page, beside the title, in place of the platform's
+  own "Details": the buttons a page would otherwise give a row of their own. On a card or an
+  entity view it draws nothing.
+- **Changing the areas.** `useAreaActions()` adds a floor or a room to the house, renames one,
+  moves a floor to another storey or removes an area, with the viewer's permissions (`area:write`,
+  which `canEdit` says): a package that draws the house keeps its floors and rooms the house's own.
+
 ## 1.2.0
 
 - **The past of the house.** `ctx.history.states()` and `ctx.history.telemetry()` on the server

package/README.md

@@ -140,6 +140,22 @@ import { sunPosition } from '@nebulahome/package-sdk/sun';
 const { elevation, azimuth } = sunPosition(at, { latitude, longitude });
 ```
 
+## Toasts
+
+The interface's own toasts, for the outcome of something the viewer just did (since 1.4):
+
+```tsx
+const toast = useToast();
+const save = usePackageMutation('rules.save');
+
+try {
+  await save.mutate(rules);
+  toast.success({ title: t('save.done', 'Saved') });
+} catch (error) {
+  toast.error({ title: t('save.failed', "Couldn't save"), message: String(error) });
+}
+```
+
 ## Entry points
 
 | Import                    | What                                                                                                                                                                                                                                            |
@@ -189,8 +205,9 @@ git tag package-sdk@<version> && git push origin package-sdk@<version>
 ```
 
 `.github/workflows/release-package-sdk.yml` checks the tag says the package's version, runs the
-SDK's gates and publishes a GitHub release with the archive npm will receive. The maintainer
-publishes that archive, signed in to npm:
+SDK's gates and keeps the archive npm will receive as the run's artifact; it makes no GitHub
+release, npm is where the SDK is published. The maintainer downloads that artifact from the run
+and publishes it, signed in to npm:
 
 ```sh
 npm publish nebulahome-package-sdk-<version>.tgz

package/dist/chunks/node-build.js

@@ -6850,7 +6850,7 @@ function composeFileProblems(text, settingKeys) {
 * the two are compared before a package is installed or started (PACKAGES_DOCS.md 11).
 */
 /** The SDK's own version, `1.0.0`. */
-const SDK_VERSION = "1.2.0";
+const SDK_VERSION = "1.4.0";
 //#endregion
 //#region src/vite/catalogues.ts
 /**

package/dist/chunks/version.js

@@ -7,6 +7,6 @@
 * the two are compared before a package is installed or started (PACKAGES_DOCS.md 11).
 */
 /** The SDK's own version, `1.0.0`. */
-const SDK_VERSION = "1.2.0";
+const SDK_VERSION = "1.4.0";
 //#endregion
 export { SDK_VERSION as t };

package/dist/styles.css

@@ -116,9 +116,12 @@
   /** Scenes, aliases and computed things; the If lane of an automation. */
   --color-violet: #a78bfa;
 
-  /** Sensors, charts, live scanning; the When lane of an automation. */
+  /** Sensors, charts, live scanning; the When lane of an automation. Wi-Fi on a network map. */
   --color-cyan: #4fd0ee;
 
+  /** Thread, on a network map: its links, its routers. */
+  --color-thread: #e879f9;
+
   /* --- states ------------------------------------------------------------------------------ */
 
   --color-success: #52cd86;
@@ -258,11 +261,26 @@
   --text-headline--line-height: 1.25;
   --text-headline--letter-spacing: -0.02em;
 
+  /** A settings page's own title, beside its icon chip under the breadcrumb. */
+  --text-headline-lg: 24px;
+  --text-headline-lg--line-height: 1.2;
+  --text-headline-lg--letter-spacing: -0.02em;
+
+  /** The title of a section with its own column of pages, such as Settings. */
+  --text-display-sm: 28px;
+  --text-display-sm--line-height: 1.15;
+  --text-display-sm--letter-spacing: -0.03em;
+
   /** The page title, one per screen, with its meta beside it in `mono-ui`. */
   --text-display: 30px;
   --text-display--line-height: 1.15;
   --text-display--letter-spacing: -0.03em;
 
+  /** The title of the screen every page shows while Nebula Home restarts or updates. */
+  --text-display-lg: 40px;
+  --text-display-lg--line-height: 1.1;
+  --text-display-lg--letter-spacing: -0.035em;
+
   /** The number an entity card is about; its unit follows at half size in `foreground-subtle`. */
   --text-reading: 32px;
   --text-reading--line-height: 1;
@@ -329,14 +347,15 @@
   /* --- depth -------------------------------------------------------------------------------- */
   /*
    * Flat. A panel has no resting shadow; an entity card has the faint lit top edge of `edge`. A
-   * dialog and the sign-in card take `dialog`, a menu and a dragged card `float`, a focused
-   * field `focus`.
+   * dialog and the sign-in card take `dialog`, a menu and a dragged card `float`, a popover
+   * (search results, the icon picker) `popover`, a focused field `focus`.
    */
 
   --shadow-edge: inset 0 1px 0 rgb(255 255 255 / 0.04);
   --shadow-focus: 0 0 0 3px rgb(124 134 255 / 0.25);
   --shadow-float: 0 24px 48px -12px rgb(0 0 0 / 0.7);
   --shadow-dialog: 0 30px 80px -20px rgb(0 0 0 / 0.9);
+  --shadow-popover: 0 28px 60px -20px rgb(0 0 0 / 0.95);
 
   /* --- motion ---------------------------------------------------------------------------- */
 
@@ -370,6 +389,92 @@
    * the dashes go by `animation-direction`.
    */
   --animate-energy-flow: energy-flow 1.6s linear infinite;
+
+  /*
+   * Nebula Home restarting or updating itself (boards N-Restart, N-Update, N-Transition-Flow): the
+   * ring turns slowly and unevenly while the core breathes out of phase, rings ripple out from the
+   * mark, its glow swells, a bar sweeps or shimmers, and the screen arrives out of a blur.
+   */
+  --animate-orbit-work: orbit 2.4s cubic-bezier(0.55, 0.1, 0.35, 0.9) infinite;
+  --animate-breathe: breathe 2.4s ease-in-out infinite;
+  --animate-ripple: ripple 2.4s cubic-bezier(0.2, 0.6, 0.3, 1) infinite;
+  --animate-glow: glow 3.6s ease-in-out infinite;
+  --animate-sweep: sweep 1.6s cubic-bezier(0.4, 0, 0.2, 1) infinite;
+  --animate-shimmer: shimmer 2s linear infinite;
+  --animate-enter: enter 0.8s cubic-bezier(0.2, 0.7, 0.2, 1) both;
+  --animate-arrive: arrive 0.6s cubic-bezier(0.2, 0.7, 0.2, 1) both;
+}
+
+/* The core of the mark breathing while Nebula Home works on itself. */
+@keyframes breathe {
+  0%,
+  100% {
+    transform: scale(1);
+    opacity: 1;
+  }
+  50% {
+    transform: scale(0.86);
+    opacity: 0.75;
+  }
+}
+
+/* A ring leaving the mark and fading as it widens. */
+@keyframes ripple {
+  from {
+    transform: scale(0.55);
+    opacity: 0.55;
+  }
+  to {
+    transform: scale(1.9);
+    opacity: 0;
+  }
+}
+
+@keyframes glow {
+  0%,
+  100% {
+    opacity: 0.45;
+  }
+  50% {
+    opacity: 0.8;
+  }
+}
+
+/* A bar that cannot say how far it is: a highlight crossing it again and again. */
+@keyframes sweep {
+  from {
+    left: -40%;
+  }
+  to {
+    left: 100%;
+  }
+}
+
+/* A light passing along a bar that is moving. */
+@keyframes shimmer {
+  from {
+    background-position: -200% 0;
+  }
+  to {
+    background-position: 200% 0;
+  }
+}
+
+/* A screen arriving out of a blur, a little small. */
+@keyframes enter {
+  from {
+    opacity: 0;
+    transform: scale(0.96);
+    filter: blur(10px);
+  }
+}
+
+/* A note rising into place. */
+@keyframes arrive {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
 }
 
 /* One period of a wire's dash pattern, which is 12 units long: 2 drawn, 10 gap. */
@@ -552,6 +657,47 @@
  * The Matter mark's square, lit violet from its top-left corner: the broker's hero and its
  * dialogs' lead. Over the square's own ground, so it sits on `bg-surface-raised`.
  */
+@utility modbus-glow {
+  background-image: radial-gradient(
+    120% 120% at 0% 0%,
+    color-mix(in srgb, var(--color-cyan) 18%, transparent),
+    transparent 60%
+  );
+}
+
+/* The newer brokers' squares, each lit in its own mark's colour the same way. */
+@utility thread-glow {
+  background-image: radial-gradient(
+    120% 120% at 0% 0%,
+    color-mix(in srgb, var(--color-thread) 20%, transparent),
+    transparent 60%
+  );
+}
+
+@utility bluetooth-glow {
+  background-image: radial-gradient(
+    120% 120% at 0% 0%,
+    color-mix(in srgb, #5b9dff 20%, transparent),
+    transparent 60%
+  );
+}
+
+@utility serial-glow {
+  background-image: radial-gradient(
+    120% 120% at 0% 0%,
+    color-mix(in srgb, #f0c27b 18%, transparent),
+    transparent 60%
+  );
+}
+
+@utility infrared-glow {
+  background-image: radial-gradient(
+    120% 120% at 0% 0%,
+    color-mix(in srgb, #f7895c 18%, transparent),
+    transparent 60%
+  );
+}
+
 @utility matter-glow {
   background-image: radial-gradient(
     120% 120% at 0% 0%,

package/dist/ui.d.ts

@@ -90,6 +90,27 @@ type AreaView = {
   readonly latitude: number | null;
   readonly longitude: number | null;
 };
+/** A floor or a room to add to the house. Since 1.3. */
+type AreaDraft = {
+  readonly kind: 'floor' | 'room';
+  readonly name: string;
+  /** The house a floor is in, the floor a room is on. */
+  readonly parentKey: string;
+  /** A floor's storey: 0 the ground floor, -1 the one below. */
+  readonly level?: number;
+};
+/** Changes to the house's areas, with the viewer's permissions. Since 1.3. */
+type AreaActions = {
+  /** Whether the viewer may change the areas (`area:write`). */
+  readonly canEdit: boolean;
+  /** Adds a floor or a room; its key comes from its name. */
+  readonly create: (draft: AreaDraft) => Promise<AreaView>;
+  readonly rename: (key: string, name: string) => Promise<void>;
+  /** Moves a floor to another storey. */
+  readonly setLevel: (key: string, level: number) => Promise<void>;
+  /** Removes an area and everything under it. */
+  readonly remove: (key: string) => Promise<void>;
+};
 /** How a picture is fetched. */
 type PictureOptions = {
   /** A camera's still is fetched again this often; 15 seconds when not said, at least 2. */
@@ -273,6 +294,36 @@ type PackageLinkProps = LinkAttributes & {
 type PlatformLinkProps = LinkAttributes & {
   readonly to: PlatformTarget;
 };
+/** What the header of the package's page shows. Since 1.3. */
+type PageActionsProps = {
+  readonly children?: ReactNode;
+};
+/** What a toast says. Since 1.4. */
+type ToastMessage = {
+  /** A few words, no full stop. */
+  readonly title: string;
+  /** One or two lines. */
+  readonly message?: string;
+  /** The one thing to do about it; doing it closes the toast. */
+  readonly action?: {
+    readonly label: string;
+    readonly onSelect: () => void;
+  };
+};
+/**
+ * Shows one of the interface's toasts, one function per kind: bottom right, three at a time, the
+ * rest waiting their turn; the same toast twice is shown once. Since 1.4.
+ */
+type Toasts = {
+  /** Confirms what was just done; stays 4 s. */
+  readonly success: (message: ToastMessage) => void;
+  /** Something that needs a look, not right now; stays 8 s. */
+  readonly warning: (message: ToastMessage) => void;
+  /** Something that failed; stays 10 s. */
+  readonly error: (message: ToastMessage) => void;
+  /** Something that started or changed; stays 6 s. */
+  readonly info: (message: ToastMessage) => void;
+};
 /** What the interface lends to implement `/ui`. */
 type UiHost = {
   readonly usePackage: () => PackageInfo;
@@ -303,6 +354,12 @@ type UiHost = {
   readonly usePlatformNavigate: () => PlatformNavigate;
   readonly PackageLink: ComponentType<PackageLinkProps>;
   readonly PlatformLink: ComponentType<PlatformLinkProps>;
+  /** Since 1.3. */
+  readonly PageActions: ComponentType<PageActionsProps>;
+  /** Since 1.3. */
+  readonly useAreaActions: () => AreaActions;
+  /** Since 1.4. */
+  readonly useToast: () => Toasts;
 };
 //#endregion
 //#region src/ui/index.d.ts
@@ -418,6 +475,20 @@ export declare function useTelemetry(query: TelemetryQuery): Telemetry;
  * @returns Them, in the owner's order.
  */
 export declare function useAreas(): readonly AreaView[];
+/**
+ * Adds, renames and removes the house's floors and rooms, as the platform's areas page does, with
+ * the viewer's permissions: `canEdit` says whether they hold them. Since 1.3.
+ *
+ * @returns What changes the areas.
+ */
+export declare function useAreaActions(): AreaActions;
+/**
+ * Shows the interface's toasts: the outcome of something the viewer just did - "Saved", "Couldn't
+ * reach the printer" - from a handler, a mutation's `onError`, wherever. Since 1.4.
+ *
+ * @returns One function per kind: `success`, `warning`, `error`, `info`.
+ */
+export declare function useToast(): Toasts;
 /**
  * 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.
@@ -471,5 +542,13 @@ export declare function PackageLink(props: PackageLinkProps): ReactElement;
  * @returns The link.
  */
 export declare function PlatformLink(props: PlatformLinkProps): ReactElement;
+/**
+ * Buttons and links drawn in the header of the package's page, in place of the platform's own:
+ * the page's actions, beside its title. On a card or a view it draws nothing. Since 1.3.
+ *
+ * @param props - What the header shows.
+ * @returns The actions.
+ */
+export declare function PageActions(props: PageActionsProps): ReactElement;
 //#endregion
-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 };
+export type { AreaActions, AreaDraft, AreaKind, AreaView, CardProps, ChangeCause, CustomEntityState, EntitiesFilter, EntityPicture, EntityView, EntityViewProps, History, HistoryQuery, HistorySeries, HistoryWindow, Locale, Mutation, MutationOptions, PackageCall, PackageInfo, PackageLinkProps, PackageNavigate, PackageRoute, PackageSettings, PageActionsProps, PageProps, PictureOptions, PlatformLinkProps, PlatformNavigate, PlatformTarget, PluralEnglish, RpcOptions, RpcState, SendCommand, SettingsPatch, StateHistoryPoint, Telemetry, TelemetryPoint, TelemetryQuery, TelemetryResolution, Theme, ToastMessage, Toasts, Translate, Translation, TranslationValues, UiHost, Viewer, VisibleSettings };

package/dist/ui.js

@@ -203,6 +203,24 @@ function useAreas() {
 	return ui("useAreas", "1.2")();
 }
 /**
+* Adds, renames and removes the house's floors and rooms, as the platform's areas page does, with
+* the viewer's permissions: `canEdit` says whether they hold them. Since 1.3.
+*
+* @returns What changes the areas.
+*/
+function useAreaActions() {
+	return ui("useAreaActions", "1.3")();
+}
+/**
+* Shows the interface's toasts: the outcome of something the viewer just did - "Saved", "Couldn't
+* reach the printer" - from a handler, a mutation's `onError`, wherever. Since 1.4.
+*
+* @returns One function per kind: `success`, `warning`, `error`, `info`.
+*/
+function useToast() {
+	return ui("useToast", "1.4")();
+}
+/**
 * 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.
 *
@@ -271,5 +289,15 @@ function PackageLink(props) {
 function PlatformLink(props) {
 	return createElement(ui("PlatformLink", "1.0"), props);
 }
+/**
+* Buttons and links drawn in the header of the package's page, in place of the platform's own:
+* the page's actions, beside its title. On a card or a view it draws nothing. Since 1.3.
+*
+* @param props - What the header shows.
+* @returns The actions.
+*/
+function PageActions(props) {
+	return createElement(ui("PageActions", "1.3"), props);
+}
 //#endregion
-export { PackageLink, PlatformLink, useAreas, useCommand, useCustomEntity, useEntities, useEntity, useEntityPicture, useLocale, usePackage, usePackageCall, usePackageMutation, usePackageNavigate, usePackageRoute, usePackageRpc, usePackageSettings, usePlatformNavigate, usePortalContainer, useStateHistory, useTelemetry, useTheme, useTranslation, useViewer };
+export { PackageLink, PageActions, PlatformLink, useAreaActions, useAreas, useCommand, useCustomEntity, useEntities, useEntity, useEntityPicture, useLocale, usePackage, usePackageCall, usePackageMutation, usePackageNavigate, usePackageRoute, usePackageRpc, usePackageSettings, usePlatformNavigate, usePortalContainer, useStateHistory, useTelemetry, useTheme, useToast, useTranslation, useViewer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulahome/package-sdk",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Write a NebulaHome package: declare it, build it, and run it on the platform.",
   "license": "MIT",
   "type": "module",
@@ -100,10 +100,10 @@
     "vitest": "^4.1.11",
     "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/contracts": "2026.10.0-alpha.23",
+    "@nebulahome/tsconfig": "2026.10.0-alpha.23",
+    "@nebulahome/eslint-config": "2026.10.0-alpha.23",
+    "@nebulahome/ui": "2026.10.0-alpha.23"
   },
   "scripts": {
     "build": "tsdown && node scripts/build-styles.js",