@sigma-file-manager/api 1.4.0 → 1.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @sigma-file-manager/api
 
-Types and manifest schema for Sigma File Manager extensions.
+Type definitions and the extension manifest JSON schema for [Sigma File Manager](https://github.com/aleksey-hoffman/sigma-file-manager) extensions.
 
 ## Install
 
@@ -8,35 +8,52 @@ Types and manifest schema for Sigma File Manager extensions.
 npm install -D @sigma-file-manager/api
 ```
 
-## Use in JavaScript extensions
+Add a `devDependency` only; the host does not run `npm install` for installed extensions.
 
-Use `// @ts-check` and JSDoc imports from the package:
+## TypeScript
 
-```js
-// @ts-check
+Import types for entrypoints and helpers. The global `sigma` object is declared in this package.
 
-/**
- * @typedef {import('@sigma-file-manager/api').ExtensionActivationContext} ExtensionActivationContext
- */
+```ts
+import type { ExtensionActivationContext, ExtensionContextEntry, UIElement } from '@sigma-file-manager/api';
 
-/**
- * @param {ExtensionActivationContext} context
- */
-async function activate(context) {
-  console.log(context.extensionPath);
+export async function activate(context: ExtensionActivationContext): Promise<void> {
+  await sigma.i18n.mergeFromPath('locales');
 }
+
+export async function deactivate(): Promise<void> {}
+```
+
+Point `package.json` `"main"` at your compiled file (for example `dist/index.js`), set `"type": "module"`, and build with `tsc` or your bundler. Commit build output if installs come from a Git tag archive without running a build on the client.
+
+## i18n
+
+Keep strings in `locales/*.json`, merge every locale from the extension root, and alias `sigma.i18n.extensionT` for extension-local keys:
+
+```ts
+const t = sigma.i18n.extensionT;
 ```
 
+Call `await sigma.i18n.mergeFromPath('locales')` in `activate` before registering UI that uses `t`.
+
+`sigma.i18n.formatMessage` is available when you need `{placeholder}` formatting outside the translator.
+
 ## Manifest schema
 
-Use this schema URL in your extension `package.json`:
+In extension `package.json`:
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/aleksey-hoffman/sigma-file-manager/main/packages/api/manifest.schema.json"
+  "$schema": "./node_modules/@sigma-file-manager/api/manifest.schema.json"
 }
 ```
 
+Run `npm install` first so the local schema file exists.
+
 ## Release
 
-API package versions are independent from app versions and tagged as `api-vX.Y.Z`.
+API package versions are independent from app releases and are published to npm as `@sigma-file-manager/api`.
+
+## Resources
+
+**[Docs](https://github.com/sigma-hub/sfm-extensions-registry/wiki)** - documentation for extension development

package/index.d.ts

@@ -4,6 +4,9 @@ declare global {
 
 export type ExtensionType = 'api' | 'iframe' | 'webview';
 
+/** Flat key–value map for one extension locale file (for example `locales/en.json`). */
+export type ExtensionLocaleStrings = Record<string, string>;
+
 export type ExtensionPermission
   = | 'contextMenu'
     | 'sidebar'
@@ -149,6 +152,14 @@ export interface ManifestBinaryDefinition {
   assets: ManifestBinaryAsset[];
 }
 
+export type ExtensionManifestMediaType = 'image' | 'video';
+
+export interface ExtensionManifestMediaItem {
+  title: string;
+  src: string;
+  type: ExtensionManifestMediaType;
+}
+
 export interface ExtensionManifest {
   id: string;
   name: string;
@@ -159,6 +170,7 @@ export interface ExtensionManifest {
   license: string;
   icon?: string;
   banner?: string;
+  media?: ExtensionManifestMediaItem[];
   categories?: string[];
   tags?: string[];
   extensionType: ExtensionType;
@@ -376,7 +388,12 @@ export interface SigmaExtensionAPI {
     t(key: string, params?: Record<string, string | number>): string;
     mergeMessages(messages: Record<string, Record<string, string>>): void;
     mergeFromPath(basePath: string): Promise<void>;
+    /**
+     * Resolves extension-localized strings under `extensions.<extensionId>.<key>`.
+     * When no translation exists, this returns `fallback` if provided, otherwise the original `key`.
+     */
     extensionT(key: string, params?: Record<string, string | number>, fallback?: string): string;
+    formatMessage(template: string, params?: Record<string, string | number>): string;
   };
   contextMenu: {
     registerItem(

package/manifest.schema.json

@@ -69,6 +69,37 @@
       "type": "string",
       "description": "Relative path to banner image"
     },
+    "media": {
+      "type": "array",
+      "description": "Preview images or videos for the extension detail overview (paths relative to the extension root, or absolute http(s) URLs)",
+      "items": {
+        "type": "object",
+        "required": [
+          "title",
+          "src",
+          "type"
+        ],
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "Label shown under the preview"
+          },
+          "src": {
+            "type": "string",
+            "description": "Relative path to a file in the extension package, or an absolute http(s) URL"
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "image",
+              "video"
+            ],
+            "description": "How the preview is rendered"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     "categories": {
       "type": "array",
       "description": "Categories for extension classification",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigma-file-manager/api",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Type definitions and manifest schema for Sigma File Manager extensions",
   "license": "GPL-3.0-or-later",
   "repository": {