@openvcs/sdk 0.2.11 → 0.2.13

package/src/lib/runtime/modal.ts

@@ -0,0 +1,172 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type {
+  ModalButtonDefinition,
+  ModalButtonVariant,
+  ModalContentAlign,
+  ModalInputDefinition,
+  ModalInputKind,
+  ModalListDefinition,
+  ModalListRowDefinition,
+  ModalSelectDefinition,
+  ModalSelectOptionDefinition,
+  PluginModalContentItem,
+  PluginModalDefinition,
+} from '../types/modal.js';
+
+import { invoke } from './menu.js';
+
+/** Describes the options accepted by `ModalBuilder.button()`. */
+export interface ModalBuilderButtonOptions {
+  /** Stores the optional tooltip text. */
+  title?: string;
+  /** Stores the visual button variant. */
+  variant?: ModalButtonVariant;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+  /** Stores a static payload merged into the action payload. */
+  payload?: Record<string, unknown>;
+}
+
+/** Describes the options accepted by `ModalBuilder.text()`. */
+export interface ModalBuilderTextOptions {
+  /** Stores the optional tooltip text. */
+  title?: string;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+}
+
+/** Describes the options accepted by `ModalBuilder.input()`. */
+export interface ModalBuilderInputOptions {
+  /** Stores the input kind. */
+  kind?: ModalInputKind;
+  /** Stores the default value. */
+  value?: string;
+  /** Stores the placeholder text. */
+  placeholder?: string;
+  /** Stores whether the field is required. */
+  required?: boolean;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+}
+
+/** Describes the options accepted by `ModalBuilder.select()`. */
+export interface ModalBuilderSelectOptions {
+  /** Stores the available options. */
+  options: ModalSelectOptionDefinition[];
+  /** Stores the default value. */
+  value?: string;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+}
+
+/** Describes the options accepted by `ModalBuilder.list()`. */
+export interface ModalBuilderListOptions {
+  /** Stores the list label. */
+  label?: string;
+  /** Stores the empty-state text. */
+  emptyText?: string;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+  /** Stores the list rows. */
+  items: ModalListRowDefinition[];
+}
+
+/** Builds a structured modal definition with a fluent class API. */
+export class ModalBuilder {
+  private readonly definition: PluginModalDefinition;
+
+  /** Creates a new modal builder with the provided title. */
+  constructor(title: string) {
+    this.definition = {
+      title: String(title || '').trim(),
+      content: [],
+    };
+  }
+
+  /** Adds a text block to the modal body. */
+  text(content: string, options: ModalBuilderTextOptions = {}): this {
+    this.definition.content.push({
+      type: 'text',
+      content: String(content || ''),
+      ...(options.title ? { title: options.title } : {}),
+      ...(options.align ? { align: options.align } : {}),
+    });
+    return this;
+  }
+
+  /** Adds a separator to the modal body. */
+  separator(): this {
+    this.definition.content.push({ type: 'separator' });
+    return this;
+  }
+
+  /** Adds a button to the modal body. */
+  button(id: string, content: string, options: ModalBuilderButtonOptions = {}): this {
+    this.definition.content.push({
+      type: 'button',
+      id: String(id || '').trim(),
+      content: String(content || ''),
+      ...(options.title ? { title: options.title } : {}),
+      ...(options.variant && options.variant !== 'default' ? { variant: options.variant } : {}),
+      ...(options.align ? { align: options.align } : {}),
+      ...(options.payload ? { payload: options.payload } : {}),
+    });
+    return this;
+  }
+
+  /** Adds a text input to the modal body. */
+  input(id: string, label: string, options: ModalBuilderInputOptions = {}): this {
+    this.definition.content.push({
+      type: 'input',
+      id: String(id || '').trim(),
+      label: String(label || '').trim(),
+      ...(options.kind ? { kind: options.kind } : {}),
+      ...(options.value !== undefined ? { value: options.value } : {}),
+      ...(options.placeholder ? { placeholder: options.placeholder } : {}),
+      ...(options.required ? { required: true } : {}),
+      ...(options.align ? { align: options.align } : {}),
+    });
+    return this;
+  }
+
+  /** Adds a select field to the modal body. */
+  select(id: string, label: string, options: ModalBuilderSelectOptions): this {
+    this.definition.content.push({
+      type: 'select',
+      id: String(id || '').trim(),
+      label: String(label || '').trim(),
+      options: Array.isArray(options.options) ? options.options : [],
+      ...(options.value !== undefined ? { value: options.value } : {}),
+      ...(options.align ? { align: options.align } : {}),
+    });
+    return this;
+  }
+
+  /** Adds a list block to the modal body. */
+  list(id: string, options: ModalBuilderListOptions): this {
+    this.definition.content.push({
+      type: 'list',
+      id: String(id || '').trim(),
+      ...(options.label ? { label: options.label } : {}),
+      ...(options.emptyText ? { emptyText: options.emptyText } : {}),
+      ...(options.align ? { align: options.align } : {}),
+      items: Array.isArray(options.items) ? options.items : [],
+    });
+    return this;
+  }
+
+  /** Returns the serialized modal payload. */
+  build(): PluginModalDefinition {
+    return {
+      title: this.definition.title,
+      content: this.definition.content.map((item) => ({ ...item })) as PluginModalContentItem[],
+    };
+  }
+
+  /** Requests the host to open the modal with the current definition. */
+  async open(): Promise<void> {
+    await invoke('open_plugin_modal', { modal: this.build() });
+  }
+}

package/src/lib/types/index.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 export * from './host';
+export * from './modal';
 export * from './menubar';
 export * from './plugin';
 export * from './protocol';

package/src/lib/types/modal.ts

@@ -0,0 +1,152 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/** Describes horizontal alignment hints for modal content. */
+export type ModalContentAlign = 'left' | 'centered' | 'right';
+
+/** Describes visual emphasis for modal buttons. */
+export type ModalButtonVariant = 'default' | 'primary' | 'danger';
+
+/** Describes the text input kinds supported by plugin modals. */
+export type ModalInputKind = 'text' | 'search' | 'password' | 'url' | 'number';
+
+/** Describes one button option rendered inside a modal. */
+export interface ModalButtonDefinition {
+  /** Stores the action id triggered when the button is pressed. */
+  id: string;
+  /** Stores the button label. */
+  content: string;
+  /** Stores the optional tooltip text. */
+  title?: string;
+  /** Stores the visual button variant. */
+  variant?: ModalButtonVariant;
+  /** Stores the button alignment hint. */
+  align?: ModalContentAlign;
+  /** Stores a static payload merged into the action payload. */
+  payload?: Record<string, unknown>;
+}
+
+/** Describes one text block rendered inside a modal. */
+export interface ModalTextDefinition {
+  /** Always stores `text`. */
+  type: 'text';
+  /** Stores the block text. */
+  content: string;
+  /** Stores an optional tooltip. */
+  title?: string;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+}
+
+/** Describes one separator rendered inside a modal. */
+export interface ModalSeparatorDefinition {
+  /** Always stores `separator`. */
+  type: 'separator';
+}
+
+/** Describes one button rendered inside a modal body. */
+export interface ModalButtonItemDefinition extends ModalButtonDefinition {
+  /** Always stores `button`. */
+  type: 'button';
+}
+
+/** Describes one text input rendered inside a modal. */
+export interface ModalInputDefinition {
+  /** Always stores `input`. */
+  type: 'input';
+  /** Stores the input field id. */
+  id: string;
+  /** Stores the label text. */
+  label: string;
+  /** Stores the input kind. */
+  kind?: ModalInputKind;
+  /** Stores the default value. */
+  value?: string;
+  /** Stores the placeholder text. */
+  placeholder?: string;
+  /** Stores whether the field is required. */
+  required?: boolean;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+}
+
+/** Describes one select option rendered inside a modal. */
+export interface ModalSelectOptionDefinition {
+  /** Stores the option label. */
+  label: string;
+  /** Stores the option value. */
+  value: string;
+  /** Stores whether the option is selected by default. */
+  selected?: boolean;
+}
+
+/** Describes one select field rendered inside a modal. */
+export interface ModalSelectDefinition {
+  /** Always stores `select`. */
+  type: 'select';
+  /** Stores the field id. */
+  id: string;
+  /** Stores the label text. */
+  label: string;
+  /** Stores the available options. */
+  options: ModalSelectOptionDefinition[];
+  /** Stores the default value. */
+  value?: string;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+}
+
+/** Describes one row-level action rendered in a list item. */
+export interface ModalListActionDefinition extends ModalButtonDefinition {
+  /** Always stores `button`. */
+  type: 'button';
+}
+
+/** Describes one list row rendered inside a modal list. */
+export interface ModalListRowDefinition {
+  /** Stores the row id. */
+  id: string;
+  /** Stores the row title. */
+  title: string;
+  /** Stores a short status label. */
+  status?: string;
+  /** Stores a secondary metadata label. */
+  meta?: string;
+  /** Stores longer descriptive text. */
+  description?: string;
+  /** Stores the row actions. */
+  actions?: ModalListActionDefinition[];
+}
+
+/** Describes one list block rendered inside a modal. */
+export interface ModalListDefinition {
+  /** Always stores `list`. */
+  type: 'list';
+  /** Stores the list id. */
+  id: string;
+  /** Stores the list label. */
+  label?: string;
+  /** Stores the empty-state text. */
+  emptyText?: string;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+  /** Stores the list rows. */
+  items: ModalListRowDefinition[];
+}
+
+/** Describes one plugin modal content item. */
+export type PluginModalContentItem =
+  | ModalTextDefinition
+  | ModalSeparatorDefinition
+  | ModalButtonItemDefinition
+  | ModalInputDefinition
+  | ModalSelectDefinition
+  | ModalListDefinition;
+
+/** Describes the structured payload used to render a plugin modal. */
+export interface PluginModalDefinition {
+  /** Stores the modal title. */
+  title: string;
+  /** Stores the ordered list of modal content items. */
+  content: PluginModalContentItem[];
+}

package/src/lib/types/plugin.ts

@@ -32,6 +32,8 @@ export type PluginSettingsValue = Record<string, unknown>;
 export interface PluginHandleActionParams extends RequestParams {
   /** Stores the action id selected by the user. */
   action_id?: string;
+  /** Stores an optional payload supplied by the triggering UI. */
+  payload?: Record<string, unknown>;
 }
 
 /** Describes the params shape for plugin settings callbacks. */

package/test/modal.test.ts

@@ -0,0 +1,24 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { ModalBuilder } from '../src/lib/runtime/index.js';
+
+describe('ModalBuilder', () => {
+  it('builds a structured modal definition', () => {
+    const modal = new ModalBuilder('Manage Submodules')
+      .text('Hello, World!')
+      .button('new-button', 'Test button, push me!', { align: 'centered' })
+      .build();
+
+    assert.deepStrictEqual(modal, {
+      title: 'Manage Submodules',
+      content: [
+        { type: 'text', content: 'Hello, World!' },
+        { type: 'button', id: 'new-button', content: 'Test button, push me!', align: 'centered' },
+      ],
+    });
+  });
+});