elowen-plugin-ui-kit 0.6.0 → 0.7.0

package/index.d.ts

@@ -10,7 +10,7 @@ import type { ComponentType } from 'react';
 /** See index.js — bump on incompatible changes to `ElowenUiRuntime`. Deliberately a LITERAL type:
  *  the web app re-declares the value and annotates it with `typeof PLUGIN_UI_API_VERSION`, so a kit
  *  bump that forgets the host fails the web typecheck instead of drifting silently. */
-export declare const PLUGIN_UI_API_VERSION: 11;
+export declare const PLUGIN_UI_API_VERSION: 12;
 
 /** Public props of `ElowenUiRuntime.components.Slider`. */
 export interface SliderProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'min' | 'max' | 'step' | 'type'> {
@@ -29,6 +29,76 @@ export interface DirectoryPickerProps {
   onClose: () => void;
 }
 
+export interface PluginConfigField {
+  key: string;
+  label: string;
+  type:
+    | 'string' | 'secret' | 'boolean' | 'number' | 'textarea' | 'rolePolicies' | 'model' | 'provider'
+    | 'section' | 'enum' | 'multiSelect' | 'code' | 'prompt' | 'json' | 'embeddingModel' | 'mcpServers'
+    | 'destination' | 'projects' | 'plugins' | 'tools' | 'models' | 'timezone' | 'tokenList';
+  hint?: string;
+  required?: boolean;
+  min?: number;
+  max?: number;
+  step?: number;
+  placeholder?: string;
+  display?: { control?: 'input' | 'slider'; unit?: string; divisor?: number };
+  browse?: 'directory';
+  default?: string | number | boolean | string[];
+  providerType?: string;
+  options?: { value: string; label: string }[];
+  language?: string;
+  help?: string;
+  risk?: 'low' | 'medium' | 'high';
+  advanced?: boolean;
+  fullWidth?: boolean;
+  visibleWhen?: { key: string; equals: string | number | boolean };
+}
+
+export type SaveStatus = 'idle' | 'saving' | 'saved' | 'pending' | 'error';
+
+export interface AutoSaveStatusProps {
+  status: SaveStatus;
+  onRetry?: () => void | Promise<void>;
+}
+
+export interface UseAutoSaveStatusOptions {
+  ready?: boolean;
+  savable?: boolean;
+  delay?: number;
+}
+
+export interface UseAutoSaveStatusResult {
+  status: SaveStatus;
+  retry: () => Promise<void>;
+  flush: () => Promise<SaveStatus>;
+}
+
+export type UseAutoSaveStatus = (
+  deps: readonly unknown[],
+  save: () => unknown | Promise<unknown>,
+  options?: UseAutoSaveStatusOptions,
+) => UseAutoSaveStatusResult;
+
+export type PluginConfigErrorKind = 'validation' | 'conflict' | 'transport';
+
+export interface PluginConfigDraft {
+  values: Record<string, unknown>;
+  setValue: (key: string, value: unknown) => void;
+  commitValue: (key: string, value: unknown) => Promise<{ pending: boolean }>;
+  status: SaveStatus;
+  errorKind: PluginConfigErrorKind | null;
+  retry: () => Promise<void>;
+  flush: () => Promise<SaveStatus>;
+  ready: boolean;
+}
+
+export type UsePluginConfigDraft = (
+  name: string,
+  detail: { config: Record<string, unknown>; configSchema: readonly PluginConfigField[]; revision?: number },
+  options?: { save?: (value: { name: string; values: Record<string, unknown>; expectedRevision?: number }) => Promise<unknown> },
+) => PluginConfigDraft;
+
 export type ConfirmDialogButtonVariant = 'default' | 'accent' | 'ghost' | 'danger' | 'ghost-danger' | 'outline' | 'outline-danger';
 
 /** Public props of the API 11 async-safe `ElowenUiRuntime.components.ConfirmDialog`. */
@@ -97,7 +167,7 @@ export interface PluginPageProps {
    *  inside a group header can ignore it; a section declaring `layout: 'orbital'` cannot — the orbital
    *  group is a field of pods with no header to hold one, so this channel is the only place its user
    *  ever learns that a save failed. */
-  onSaveState?: (status: 'idle' | 'saving' | 'saved' | 'error', retry?: () => void) => void;
+  onSaveState?: (status: SaveStatus, retry?: () => void | Promise<void>) => void;
 }
 
 /** Props for a contextual Project panel. It is never a standalone route: the selected Project and panel
@@ -157,11 +227,16 @@ export interface ElowenUiRuntime {
   react: typeof React;
   reactDom: typeof ReactDom;
   jsxRuntime: typeof JsxRuntime;
-  components: Record<string, ComponentType<never>>;
+  components: Record<string, ComponentType<never>> & {
+    AutoSaveStatus: ComponentType<AutoSaveStatusProps>;
+  };
   /** Curated React hooks (i18n, toasts, the app's react-query data hooks). Safe across the boundary:
    *  the bundle runs on the HOST's React instance, so the rules of hooks hold. A bundle narrows each
    *  entry to the signature it expects; an absent name means the host predates the bundle. */
-  hooks: Record<string, unknown>;
+  hooks: Record<string, unknown> & {
+    useAutoSaveStatus: UseAutoSaveStatus;
+    usePluginConfigDraft: UsePluginConfigDraft;
+  };
   /** Curated pure helpers (formatting, session/task mapping, error shaping) shared with bundles. */
   utils: Record<string, unknown>;
   api: (path: string, init?: RequestInit) => Promise<unknown>;

package/index.js

@@ -2,4 +2,4 @@
  *  `window.ElowenUiRuntime` stamped with this number; a bundle whose `requiresApiVersion` is NEWER
  *  renders a placeholder instead of executing against a contract it was not built for. Bump on
  *  incompatible changes to the `ElowenUiRuntime` surface (see index.d.ts). */
-export const PLUGIN_UI_API_VERSION = 11;
+export const PLUGIN_UI_API_VERSION = 12;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elowen-plugin-ui-kit",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Contract types and esbuild toolchain for building Elowen plugin browser-UI bundles.",
   "license": "MIT",
   "type": "module",

package/theme.css

@@ -67,6 +67,10 @@
      three states, and borrowing `primary` or `chart-*` for them would say something they do not mean. */
   --color-success: #32c986;
   --color-success-foreground: var(--color-primary-foreground);
+  /* Toasts are outcome banners, not tiny status marks. GitHub's Primer success green gives them the
+     saturated diff/merge signal Filip expects while keeping white body text above AA contrast. */
+  --color-toast-success: #1f883d;
+  --color-toast-success-foreground: #ffffff;
   --color-warning: #edae49;
   --color-info: #62a8ea;