@punica/editor 1.0.5 → 1.0.7

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

@@ -0,0 +1,455 @@
+declare module 'punica' {
+  export namespace shell {
+    export namespace View {
+      const showInformationMessage: <T extends string>(
+        message: string,
+        ...items: T[]
+      ) => Promise<T | undefined>;
+
+      const showWarningMessage: <T extends string>(
+        message: string,
+        ...items: T[]
+      ) => Promise<T | undefined>;
+
+      const showErrorMessage: <T extends string>(
+        message: string,
+        ...items: T[]
+      ) => Promise<T | undefined>;
+
+      interface DialogOptions {
+        title: string;
+        message?: string;
+        html?: string;
+        buttons?: DialogButton[];
+        footerHtml?: string;
+        modal?: boolean;
+        width?: string;
+        height?: string;
+        onMount?: (dialog: HTMLElement) => void;
+      }
+
+      interface DialogButton {
+        label: string;
+        variant?: 'filled' | 'outlined' | 'text';
+        color?: 'primary' | 'secondary' | 'error';
+        action?: string;
+      }
+
+      const showDialog: (options: DialogOptions) => Promise<string | undefined>;
+
+      interface ConfirmOptions {
+        title?: string;
+        message: string;
+        confirmLabel?: string;
+        cancelLabel?: string;
+        variant?: 'info' | 'warning' | 'error';
+      }
+
+      const showConfirm: (options: ConfirmOptions) => Promise<boolean>;
+
+      interface AlertOptions {
+        title?: string;
+        message: string;
+        variant?: 'info' | 'warning' | 'error' | 'success';
+        buttonLabel?: string;
+      }
+
+      const showAlert: (options: AlertOptions) => Promise<void>;
+
+      interface PromptOptions {
+        title?: string;
+        message: string;
+        placeholder?: string;
+        defaultValue?: string;
+        confirmLabel?: string;
+        cancelLabel?: string;
+        type?: 'text' | 'password' | 'number';
+      }
+
+      const showPrompt: (options: PromptOptions) => Promise<string | undefined>;
+
+      interface ToastOptions {
+        title?: string;
+        message?: string;
+        duration?: number;
+        dismissible?: boolean;
+        variant?: 'neutral' | 'info' | 'success' | 'warning' | 'error';
+        placement?:
+          | 'top-left'
+          | 'top-center'
+          | 'top-right'
+          | 'bottom-left'
+          | 'bottom-center'
+          | 'bottom-right';
+      }
+
+      const showToast: (options: ToastOptions) => HTMLElement;
+
+      interface ChangesPreviewOptions {
+        title: string;
+        summary?: string;
+        files: Array<{
+          path: string;
+          action: 'create' | 'update' | 'delete';
+          content?: string;
+        }>;
+        onConfirm: () => Promise<void>;
+        onCancel?: () => void;
+      }
+
+      const showChangesPreview: (
+        options: ChangesPreviewOptions
+      ) => Promise<'confirm' | 'cancel' | undefined>;
+
+      namespace Helpers {
+        interface CreateElementOptions {
+          attrs?: Record<string, string>;
+          text?: string;
+          children?: HTMLElement[];
+          style?: Record<string, string> | string;
+          className?: string;
+        }
+
+        interface ButtonOptions {
+          variant?: 'filled' | 'outlined' | 'text';
+          color?: 'primary' | 'secondary' | 'error';
+          size?: 'small' | 'medium' | 'large';
+          disabled?: boolean;
+          rounded?: boolean;
+          icon?: string;
+          fullwidth?: boolean;
+        }
+
+        interface IconButtonOptions {
+          title?: string;
+          size?: 'x-small' | 'small' | 'medium';
+          variant?: 'text' | 'outlined' | 'filled';
+          disabled?: boolean;
+          attrs?: Record<string, string>;
+        }
+
+        interface TypographyOptions {
+          variant?:
+            | 'h1'
+            | 'h2'
+            | 'h3'
+            | 'h4'
+            | 'h5'
+            | 'h6'
+            | 'body'
+            | 'caption';
+          color?: 'primary' | 'secondary' | 'error';
+          fontWeight?: 'normal' | 'bold';
+          style?: Record<string, string> | string;
+          className?: string;
+          attrs?: Record<string, string>;
+        }
+
+        interface ChipOptions {
+          variant?: 'filled' | 'outlined';
+          color?: 'primary' | 'secondary' | 'error' | 'success' | 'warning';
+          size?: 'small' | 'medium';
+        }
+
+        interface BoxOptions {
+          attrs?: Record<string, string>;
+          children?: HTMLElement[];
+          style?: Record<string, string> | string;
+          className?: string;
+        }
+
+        interface RowOptions {
+          spacing?: string;
+          alignItems?: string;
+          wrap?: string;
+          attrs?: Record<string, string>;
+          children?: HTMLElement[];
+          style?: Record<string, string> | string;
+          className?: string;
+        }
+
+        interface ColOptions {
+          xs?: string | number;
+          sm?: string | number;
+          md?: string | number;
+          lg?: string | number;
+          xl?: string | number;
+          attrs?: Record<string, string>;
+          children?: HTMLElement[];
+          style?: Record<string, string> | string;
+          className?: string;
+        }
+
+        interface InputOptions {
+          value?: string;
+          placeholder?: string;
+          type?: 'text' | 'password' | 'number' | 'email' | 'url';
+          size?: 'small' | 'medium' | 'large';
+          fullwidth?: boolean;
+          rounded?: boolean;
+          disabled?: boolean;
+          id?: string;
+          min?: string | number;
+          max?: string | number;
+          step?: string | number;
+          attrs?: Record<string, string>;
+          style?: Record<string, string> | string;
+          className?: string;
+          onInput?: (value: string) => void;
+          onChange?: (value: string) => void;
+        }
+
+        interface SelectOptions {
+          value?: string;
+          size?: 'small' | 'medium' | 'large';
+          fullwidth?: boolean;
+          rounded?: boolean;
+          disabled?: boolean;
+          minimumTargetWidth?: boolean;
+          id?: string;
+          attrs?: Record<string, string>;
+          style?: Record<string, string> | string;
+          className?: string;
+          onChange?: (value: string) => void;
+        }
+
+        interface SelectItemOptions {
+          value: string;
+          text?: string;
+          attrs?: Record<string, string>;
+        }
+
+        interface CheckboxOptions {
+          checked?: boolean;
+          label?: string;
+          disabled?: boolean;
+          id?: string;
+          attrs?: Record<string, string>;
+          style?: Record<string, string> | string;
+          className?: string;
+          onChange?: (checked: boolean) => void;
+        }
+
+        interface IconOptions {
+          iconClass?: string;
+          innerHTML?: string;
+          slot?: string;
+          attrs?: Record<string, string>;
+          style?: Record<string, string> | string;
+          className?: string;
+        }
+
+        interface TextareaOptions {
+          value?: string;
+          placeholder?: string;
+          rows?: number;
+          cols?: number;
+          size?: 'small' | 'medium' | 'large';
+          fullwidth?: boolean;
+          rounded?: boolean;
+          disabled?: boolean;
+          id?: string;
+          attrs?: Record<string, string>;
+          style?: Record<string, string> | string;
+          className?: string;
+          onInput?: (value: string) => void;
+          onChange?: (value: string) => void;
+        }
+
+        interface DividerOptions {
+          orientation?: 'horizontal' | 'vertical';
+          attrs?: Record<string, string>;
+          style?: Record<string, string> | string;
+          className?: string;
+        }
+
+        interface ListViewOptions {
+          enableDivider?: boolean;
+          spacing?: string;
+          attrs?: Record<string, string>;
+          children?: HTMLElement[];
+          style?: Record<string, string> | string;
+          className?: string;
+        }
+
+        interface ListViewItemOptions {
+          label?: string | HTMLElement;
+          content?: string | HTMLElement;
+          endAdornment?: HTMLElement;
+          attrs?: Record<string, string>;
+          children?: HTMLElement[];
+        }
+
+        interface PaperOptions {
+          elevation?: number;
+          attrs?: Record<string, string>;
+          children?: HTMLElement[];
+          style?: Record<string, string> | string;
+          className?: string;
+        }
+
+        interface TabOptions {
+          value?: string;
+          orientation?: 'horizontal' | 'vertical';
+          attrs?: Record<string, string>;
+          children?: HTMLElement[];
+          onChange?: (value: string) => void;
+        }
+
+        interface TabItemOptions {
+          value: string;
+          text?: string;
+          attrs?: Record<string, string>;
+        }
+
+        interface TabPanelOptions {
+          value: string;
+          selectedValue?: string;
+          attrs?: Record<string, string>;
+          children?: HTMLElement[];
+          style?: Record<string, string> | string;
+          className?: string;
+        }
+
+        interface BadgeOptions {
+          text?: string;
+          variant?: 'filled' | 'outlined';
+          color?: 'primary' | 'secondary' | 'error' | 'success' | 'warning';
+          size?: 'small' | 'medium';
+          title?: string;
+          attrs?: Record<string, string>;
+        }
+
+        interface MenuOptions {
+          attrs?: Record<string, string>;
+          children?: HTMLElement[];
+          style?: Record<string, string> | string;
+          className?: string;
+        }
+
+        interface MenuItemOptions {
+          text?: string;
+          attrs?: Record<string, string>;
+          onClick?: (e: Event) => void;
+          style?: Record<string, string> | string;
+          className?: string;
+          children?: HTMLElement[];
+        }
+
+        interface LinkOptions {
+          href: string;
+          text?: string;
+          target?: '_blank' | '_self' | '_parent' | '_top';
+          rel?: string;
+          download?: string;
+          attrs?: Record<string, string>;
+          style?: Record<string, string> | string;
+          className?: string;
+          children?: HTMLElement[];
+        }
+
+        interface ToolbarOptions {
+          variant?: 'dense' | 'regular';
+          disableGutters?: boolean;
+          attrs?: Record<string, string>;
+          children?: HTMLElement[];
+          style?: Record<string, string> | string;
+          className?: string;
+        }
+
+        function createElement<K extends keyof HTMLElementTagNameMap>(
+          tag: K,
+          options?: CreateElementOptions
+        ): HTMLElementTagNameMap[K];
+        function createElement(
+          tag: shell.Components.Element | string,
+          options?: CreateElementOptions
+        ): HTMLElement;
+
+        function createButton(
+          label: string,
+          onClick: () => void,
+          options?: ButtonOptions
+        ): HTMLElement;
+
+        function createIconButton(
+          iconClass: string,
+          onClick: () => void,
+          options?: IconButtonOptions
+        ): HTMLElement;
+
+        function createTypography(
+          text: string,
+          options?: TypographyOptions
+        ): HTMLElement;
+
+        function createChip(label: string, options?: ChipOptions): HTMLElement;
+
+        function createBox(options?: BoxOptions): HTMLElement;
+
+        function createRow(options?: RowOptions): HTMLElement;
+
+        function createCol(options?: ColOptions): HTMLElement;
+
+        function createInput(options?: InputOptions): HTMLElement;
+
+        function createSelect(options?: SelectOptions): HTMLElement;
+
+        function createSelectItem(options: SelectItemOptions): HTMLElement;
+
+        function createCheckbox(options?: CheckboxOptions): HTMLElement;
+
+        function createIcon(options?: IconOptions): HTMLElement;
+
+        function createTextarea(options?: TextareaOptions): HTMLElement;
+
+        function createDivider(options?: DividerOptions): HTMLElement;
+
+        function createListView(options?: ListViewOptions): HTMLElement;
+
+        function createListViewItem(options?: ListViewItemOptions): HTMLElement;
+
+        function createPaper(options?: PaperOptions): HTMLElement;
+
+        function createTab(options?: TabOptions): HTMLElement;
+
+        function createTabItem(options: TabItemOptions): HTMLElement;
+
+        function createTabPanel(options: TabPanelOptions): HTMLElement;
+
+        function createBadge(options?: BadgeOptions): HTMLElement;
+
+        function createMenu(options?: MenuOptions): HTMLElement;
+
+        function createMenuItem(options?: MenuItemOptions): HTMLElement;
+
+        function createLink(text: string, options: LinkOptions): HTMLElement;
+
+        function createToolbar(options?: ToolbarOptions): HTMLElement;
+      }
+
+      namespace Theme {
+        interface ThemeProfile {
+          id: string;
+          name: string;
+          variables: Record<string, string>;
+        }
+
+        interface ThemeManager {
+          loadProfile(profileId: string): Promise<void>;
+          getCurrentProfile(): string | null;
+          getProfiles(): Record<string, ThemeProfile>;
+          getProfile(profileId: string): ThemeProfile | undefined;
+          registerProfile(profile: ThemeProfile): void;
+          onDidChangeProfile(callback: (profileId: string) => void): () => void;
+          initialize(): Promise<void>;
+        }
+
+        const manager: ThemeManager;
+        const profiles: Record<string, ThemeProfile>;
+      }
+
+      const Theme: Theme;
+    }
+  }
+}

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

@@ -0,0 +1,150 @@
+declare module 'punica' {
+  export namespace shell {
+    /**
+     * ViewRegistry — the substrate's single visibility authority
+     * (`punica.shell.Views.manager`).
+     *
+     * Extension lifecycle model, dimension B: view presentation state is
+     * tracked per VIEW and is orthogonal to the extension's runtime
+     * state. Activation never shows UI; the only visibility mutators are
+     * `reveal`/`hide`, publicly surfaced as the `shell.revealView` /
+     * `shell.hideView` core capabilities (user gestures, extensions,
+     * agents and MCP clients all converge on them).
+     */
+    export namespace Views {
+      export type ViewSlotId =
+        | 'primarySidebar'
+        | 'secondarySidebar'
+        | 'contentSidebar'
+        | 'content'
+        | 'panel';
+
+      /**
+       * - `registered`: placement known from the manifest, no DOM.
+       * - `materialized`: host DOM exists and the provider rendered; hidden.
+       * - `visible`: shown in its slot.
+       */
+      export type ViewPresentationState =
+        | 'registered'
+        | 'materialized'
+        | 'visible';
+
+      export interface ViewPlacement {
+        viewId: string;
+        slot: ViewSlotId;
+        extensionName: string;
+        title?: string;
+        icon?: string;
+        order?: number;
+        /**
+         * TRANSITIONAL — command executed on reveal when the owning
+         * extension has not registered a ViewProvider yet. Removed once
+         * the fleet migrates to view providers.
+         */
+        fallbackCommand?: string;
+      }
+
+      export interface ViewProviderDisposable {
+        dispose(): void;
+      }
+
+      /**
+       * Render contract for a declared view. Registered by extension
+       * code during activation via `context.ui.registerViewProvider`;
+       * the SHELL decides when to materialize (first reveal) — never the
+       * extension.
+       */
+      export interface ViewProvider {
+        render(
+          host: HTMLElement
+        ):
+          | void
+          | ViewProviderDisposable
+          | Promise<void | ViewProviderDisposable>;
+      }
+
+      /** Who asked for a reveal/hide — recorded in shell.view.* events. */
+      export interface RevealSource {
+        kind:
+          | 'user-gesture'
+          | 'capability'
+          | 'extension'
+          | 'session-restore'
+          | 'host';
+        id?: string;
+      }
+
+      export interface RevealOptions {
+        focus?: boolean;
+      }
+
+      export interface ViewInfo {
+        viewId: string;
+        slot: ViewSlotId;
+        extensionName: string;
+        title?: string;
+        state: ViewPresentationState;
+      }
+
+      export interface IViewRegistryManager {
+        /** Manifest-level placement registration (analysis phase). */
+        registerPlacement(placement: ViewPlacement): void;
+
+        /**
+         * Register a render provider for a declared view. Registration
+         * alone never shows anything.
+         */
+        registerProvider(
+          viewId: string,
+          provider: ViewProvider,
+          extensionName?: string
+        ): ViewProviderDisposable;
+
+        getPlacement(viewId: string): ViewPlacement | undefined;
+        hasProvider(viewId: string): boolean;
+        getState(viewId: string): ViewPresentationState | undefined;
+        getVisibleView(slot: ViewSlotId): string | undefined;
+        listViews(): ViewInfo[];
+
+        /**
+         * Reveal a view — the single visibility mutator. Activates the
+         * owning extension when needed (reason `view`), materializes the
+         * host, renders the provider once (transient contentSidebar
+         * views: on every reveal), shows the slot and emits
+         * `shell.view.revealed` with the source. Prefer calling the
+         * `shell.revealView` capability so the reveal is audited and
+         * policy-gated.
+         */
+        reveal(
+          viewId: string,
+          source: RevealSource,
+          options?: RevealOptions
+        ): Promise<void>;
+
+        /**
+         * Hide a view. Emits `shell.view.hidden`. For the transient
+         * contentSidebar drawer this unmounts the slot's hosts (the
+         * overlay collapses via the host CSS `:empty` rule); providers
+         * re-render on the next reveal.
+         */
+        hide(viewId: string, source: RevealSource): void;
+
+        /**
+         * Sync bookkeeping after the Layout manager wiped a slot's
+         * hosts wholesale (primary sidebar switch resets the contextual
+         * contentSidebar drawer): dispose provider results, forget
+         * materialization, emit `shell.view.hidden`.
+         */
+        notifySlotReset(slot: ViewSlotId): void;
+
+        /**
+         * Dispose providers and remove rendered hosts owned by an
+         * extension (deactivation). Manifest placements stay.
+         */
+        unmountByExtension(extensionName: string): void;
+      }
+
+      export const manager: IViewRegistryManager;
+    }
+  }
+}