@nebulahome/package-sdk 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 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.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/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.3.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.3.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,6 +261,16 @@
   --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;
@@ -329,14 +342,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 ---------------------------------------------------------------------------- */
 

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,10 @@ 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 the interface lends to implement `/ui`. */
 type UiHost = {
   readonly usePackage: () => PackageInfo;
@@ -303,6 +328,10 @@ 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;
 };
 //#endregion
 //#region src/ui/index.d.ts
@@ -418,6 +447,13 @@ 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;
 /**
  * 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 +507,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, Translate, Translation, TranslationValues, UiHost, Viewer, VisibleSettings };

package/dist/ui.js

@@ -203,6 +203,15 @@ 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")();
+}
+/**
 * 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 +280,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, useTranslation, useViewer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulahome/package-sdk",
-  "version": "1.2.0",
+  "version": "1.3.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/contracts": "0.0.0",
     "@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"
   },
   "scripts": {
     "build": "tsdown && node scripts/build-styles.js",