@punica/editor 1.6.11 → 1.6.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punica/editor",
-  "version": "1.6.11",
+  "version": "1.6.13",
   "description": "Punica Editor",
   "private": false,
   "type": "module",

package/types/index.d.ts

@@ -1,4 +1,5 @@
 /// <reference path="punica.module.shell.activityBar.d.ts" />
+/// <reference path="punica.module.shell.appBar.d.ts" />
 /// <reference path="punica.module.shell.keyboardShortcuts.d.ts" />
 /// <reference path="punica.module.shell.dragDrop.d.ts" />
 /// <reference path="punica.module.shell.layout.d.ts" />

package/types/punica.module.shell.appBar.d.ts

@@ -0,0 +1,86 @@
+/**
+ * App bar type declarations.
+ *
+ * The app bar is the top strip of the window: branding on the left, the current
+ * workspace in the middle, actions on the right. On hosts that hide the native
+ * title bar it is also the window's drag handle, so it exists on every profile
+ * that lists `shell.appBar` — including the welcome layout, where it is the only
+ * way to move the window.
+ *
+ * Composition is declarative: a profile's `shell.appBar` spec describes the bar,
+ * and a shell renders it. Extensions may add their own actions at runtime
+ * through `punica.shell.AppBar.manager`, which is the same registry the profile
+ * items go through.
+ */
+
+declare module 'punica' {
+  export namespace shell {
+    namespace AppBar {
+      /** Which end of the bar an item belongs to. */
+      type AppBarAlignment = 'left' | 'right';
+
+      /** What the middle of the bar shows. */
+      type AppBarTitleMode = 'workspace' | 'product' | 'none';
+
+      /** One entry in an item's dropdown menu. */
+      interface AppBarMenuItem {
+        id: string;
+        label: string;
+        /** Command (or capability) id executed on select. */
+        command: string;
+        /** Draw a separator above this entry. */
+        separatorBefore?: boolean;
+      }
+
+      /**
+       * An action on the bar. `command` fires on click; `menu` opens a dropdown
+       * instead. An item may declare both, in which case the menu wins and the
+       * command is ignored.
+       */
+      interface AppBarItem {
+        id: string;
+        /** Icon markup (e.g. `<i class="fa-solid fa-gear"></i>`). */
+        icon?: string;
+        /** Optional text next to the icon. */
+        label?: string;
+        /** Tooltip / accessible name. */
+        title?: string;
+        alignment?: AppBarAlignment;
+        /**
+         * `'avatar'` draws a round account button whose glyph is the first
+         * letter of `label` (or the icon when there is none); `'action'` (the
+         * default) draws a flat icon button.
+         */
+        kind?: 'action' | 'avatar';
+        command?: string;
+        menu?: AppBarMenuItem[];
+        /**
+         * Command id returning a one-line summary rendered as the menu header
+         * (e.g. the licence state). Dropped when the command is not registered,
+         * which is how a host without the surface stays quiet.
+         */
+        summaryCommand?: string;
+      }
+
+      /** A profile's app bar composition (see `ProfileShellSpec.appBar`). */
+      interface AppBarSpec {
+        /** Bar height in px. Defaults to 38. */
+        height?: number;
+        /** What the centre region shows. Defaults to `'workspace'`. */
+        title?: AppBarTitleMode;
+        items?: AppBarItem[];
+      }
+
+      interface IAppBarManager {
+        /**
+         * Add (or replace) an item. Re-adding a known id keeps its original
+         * position, so an extension reload never reshuffles the bar.
+         */
+        addItem(item: AppBarItem): void;
+        removeItem(itemId: string): void;
+      }
+
+      const manager: IAppBarManager;
+    }
+  }
+}

package/types/punica.module.shell.profile.d.ts

@@ -21,6 +21,7 @@ declare module 'punica' {
        */
       type ShellModuleId =
         | 'shell.activityBar'
+        | 'shell.appBar'
         | 'shell.statusbar'
         | 'shell.view'
         | 'shell.views'
@@ -136,6 +137,13 @@ declare module 'punica' {
          * default minimal layout (single content slot).
          */
         layout?: ProfileLayoutSpec;
+        /**
+         * Optional app bar composition — branding, title mode and the actions
+         * on the top strip. Omitted means the profile has no app bar, even when
+         * `shell.appBar` is listed in `activeModules`, in which case the shell
+         * falls back to the module's own defaults.
+         */
+        appBar?: shell.AppBar.AppBarSpec;
         /**
          * Optional product defaults for the bottom panel. User settings
          * (Project > Global) override these; when both are unset the substrate

package/types/punica.module.shell.view.d.ts

@@ -514,6 +514,15 @@ declare module 'punica' {
           options?: StatusDotOptions
         ): HTMLElement;
 
+        /**
+         * Humanize a byte count: `6602` → `"6.4 KB"`. Null for absent, zero or
+         * negative input so a caller drops the chip instead of printing "0 B".
+         *
+         * Shared because sizes are read across panels: a dataset listed at
+         * "6602" in one list and "6.4 KB" in another reads as two sizes.
+         */
+        function formatBytes(bytes?: number | null): string | null;
+
         /** Build an uppercase section header with a trailing divider rule. */
         function createGroupHeader(
           options: GroupHeaderOptions | string