@punica/editor 1.7.1 → 1.8.1

package/package.json

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

package/types/index.d.ts

@@ -23,6 +23,7 @@
 /// <reference path="punica.module.kernel.tasks.d.ts" />
 /// <reference path="punica.module.extensions.api.d.ts" />
 /// <reference path="punica.module.extensions.settings.d.ts" />
+/// <reference path="punica.module.extensions.i18n.d.ts" />
 /// <reference path="punica.module.runtime.fs.d.ts" />
 /// <reference path="punica.module.runtime.search.d.ts" />
 /// <reference path="punica.module.runtime.vcs.d.ts" />

package/types/punica.module.extensions.api.d.ts

@@ -76,8 +76,24 @@ declare module 'punica' {
          */
         showOnStartup?: boolean;
       };
-      activityBar?: Pick<BaseView, 'id' | 'name'> &
-        Required<Pick<BaseView, 'title' | 'icon' | 'alignment'>>;
+      activityBar?: Pick<BaseView, 'id' | 'name' | 'capability'> &
+        Required<Pick<BaseView, 'title' | 'icon' | 'alignment'>> & {
+          /**
+           * Draw this item together with every other item declaring the same
+           * `group.id`: one icon, and a flyout listing the members once there
+           * is more than one. Lets a family of extensions (marketplaces,
+           * database providers, …) grow without taking a bar slot each.
+           * The group's identity lives here, in the manifests — the substrate
+           * knows only "same id, same icon". Ignored by older shells.
+           */
+          group?: {
+            id: string;
+            /** Tooltip of the group icon. First member to declare it wins. */
+            title?: string;
+            /** Group icon (raw HTML). First member to declare it wins. */
+            icon?: string;
+          };
+        };
       statusBar?: Pick<BaseView, 'id' | 'name'> &
         Required<Pick<BaseView, 'title' | 'label' | 'icon' | 'alignment'>>;
     }
@@ -716,6 +732,16 @@ declare module 'punica' {
        */
       export const manager: extensions.settings.SettingsApi;
     }
+
+    /**
+     * Localization engine for extension user interfaces.
+     */
+    namespace i18n {
+      /**
+       * Localization façade surfaced via `punica.extensions.i18n.manager`.
+       */
+      export const manager: extensions.i18n.I18nApi;
+    }
   }
 
   /**
@@ -809,5 +835,18 @@ declare module 'punica' {
        */
       export const manager: SettingsApi;
     }
+
+    /**
+     * Localization engine — see punica.module.extensions.i18n.d.ts.
+     */
+    export namespace i18n {
+      export import I18nApi = extensions.i18n.I18nApi;
+      export import MessageBundle = extensions.i18n.MessageBundle;
+      export import MessageBundles = extensions.i18n.MessageBundles;
+      /**
+       * Localization façade surfaced via `punica.extensions.i18n.manager`.
+       */
+      export const manager: I18nApi;
+    }
   }
 }

package/types/punica.module.extensions.i18n.d.ts

@@ -0,0 +1,83 @@
+declare module 'punica' {
+  export namespace extensions {
+    /**
+     * Localization for extension user interfaces.
+     *
+     * The substrate owns the ENGINE — one active locale, one change event, one
+     * plural implementation — and extensions own only their dictionaries. The
+     * alternative, a helper copied into every extension, is how this fleet
+     * handles small utilities, but an engine is not a small utility: 80-odd
+     * copies of plural selection and fallback order drift apart, and the drift
+     * shows up as a half-translated screen rather than a failing build.
+     *
+     * The language is stored in the shared `system` / `ui.language` setting,
+     * the same namespace the theme lives in, so every extension resolves the
+     * same value. The set of offered languages comes from the active
+     * ApplicationProfile's `localization.supported` — a v1 slot that existed
+     * unused until this API filled it.
+     */
+    export namespace i18n {
+      /** A dictionary: flat dot-separated keys to display strings. */
+      export type MessageBundle = Record<string, string>;
+
+      /** Locale tag (`en`, `tr`) to that locale's dictionary. */
+      export type MessageBundles = Record<string, MessageBundle>;
+
+      export interface I18nApi {
+        /**
+         * The active locale tag. Resolution order: the `ui.language` setting,
+         * then the app/OS language's subtag when it is supported, then the
+         * profile's declared default, then `'en'`.
+         */
+        getLocale(): string;
+
+        /**
+         * Change the language for the whole application. Writes
+         * `system` / `ui.language` at global scope and notifies subscribers;
+         * callers do not write the setting themselves.
+         */
+        setLocale(locale: string): Promise<void>;
+
+        /**
+         * Languages this product offers, from the active profile's
+         * `localization.supported`. Falls back to `['en']` when the profile
+         * declares none.
+         */
+        supportedLocales(): string[];
+
+        /** Subscribe to language changes. Returns an unsubscribe function. */
+        onDidChange(listener: (locale: string) => void): () => void;
+
+        /**
+         * Register an extension's dictionaries, keyed by locale tag. Call once
+         * during `activate()`, before anything renders. Registering again for
+         * the same extension replaces the previous bundles, so a reload during
+         * development does not accumulate stale strings.
+         */
+        register(extensionName: string, bundles: MessageBundles): void;
+
+        /**
+         * Look up a message for a registered extension.
+         *
+         * `params` values are interpolated into `{name}` placeholders. A
+         * numeric `params.count` also selects a plural form: the lookup tries
+         * `<key>.<pluralCategory>` (via `Intl.PluralRules`) before `<key>`,
+         * which is what lets English say "1 attempt" / "2 attempts" while
+         * Turkish keeps one form after a numeral.
+         *
+         * Never throws. When no message is found — unregistered extension,
+         * unknown key, missing locale — the key itself is returned, because a
+         * visible key is greppable and cannot be mistaken for finished copy.
+         */
+        t(
+          extensionName: string,
+          key: string,
+          params?: Record<string, string | number>
+        ): string;
+      }
+
+      /** Localization façade surfaced via `punica.extensions.i18n.manager`. */
+      export const manager: I18nApi;
+    }
+  }
+}

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

@@ -4,6 +4,20 @@ declare module 'punica' {
       type Alignment = 'primary' | 'secondary';
       type ItemType = 'normal' | 'menu';
 
+      /**
+       * Groups several activity items behind one icon. Declared per member —
+       * the substrate has no group table of its own, so what a group means
+       * (marketplaces, databases, …) stays in the manifests that opt in.
+       */
+      interface IItemGroup {
+        /** Members sharing this id are drawn as a single icon. */
+        id: string;
+        /** Tooltip of the group icon. First member to declare it wins; defaults to `id`. */
+        title?: string;
+        /** Group icon (raw HTML). First member to declare it wins; defaults to the first member's icon. */
+        icon?: string;
+      }
+
       interface IItem {
         id: string;
         name: string;
@@ -31,6 +45,14 @@ declare module 'punica' {
          * and the Capability Catalog. See `IActivityBarManager.syncContentTool`.
          */
         contentViewType?: string;
+        /**
+         * Collect this item into a group. While the group has one member the
+         * shell draws that member's own icon and click behaviour; when a
+         * second member joins, the icon becomes the group's and clicking it
+         * opens a flyout listing the members. Shells that predate grouping
+         * ignore the field and draw the item on its own, as before.
+         */
+        group?: IItemGroup;
       }
 
       interface IActivityBarManager {