elowen-plugin-ui-kit 0.11.0 → 0.13.2

package/index.d.ts

@@ -11,7 +11,7 @@ import type { ComponentType } from 'react';
  *  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: 16;
+export declare const PLUGIN_UI_API_VERSION: 18;
 
 /** Public props of `ElowenUiRuntime.components.Slider`. */
 export interface SliderProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'min' | 'max' | 'step' | 'type'> {
@@ -37,6 +37,16 @@ export interface ProjectIconProps {
   className?: string;
 }
 
+/** `ElowenUiRuntime.components.Calendar` (API 17) is the host's shadcn Calendar, built on
+ *  `react-day-picker` v9, and its props ARE that library's: a controlled `month`, `selected`,
+ *  `modifiers`, `components.DayButton`, `locale`, `hidden`/`disabled`, `onSelect`. v9 has NO
+ *  `DayContent`: a caller replaces the day's own button, and has to forward every prop the library
+ *  computed and honour `modifiers.focused`, or the grid's arrow keys stop moving. Deliberately not
+ *  re-declared here as a second interface: the truth is one `import type { DayPicker } from
+ *  'react-day-picker'` away in the bundle's own runtime type, while dragging the dependency into this
+ *  kit would make every plugin build install it just to host-render one grid. A bundle types the
+ *  element it destructures off `runtime().components.Calendar` with the props it actually passes. */
+
 export interface PluginConfigField {
   key: string;
   label: string;
@@ -54,6 +64,7 @@ export interface PluginConfigField {
   browse?: 'directory';
   default?: string | number | boolean | string[];
   providerType?: string | string[];
+  modelKind?: 'image';
   options?: { value: string; label: string }[];
   language?: string;
   help?: string;
@@ -182,8 +193,56 @@ export interface PluginUiProject {
   path: string;
   notes: string;
   icon?: string;
+  executionKind?: 'host' | 'managed';
+  guestRoot?: string;
+}
+
+/** One plugin-owned action on a core Project register card. */
+export interface PluginProjectRowAction {
+  id: string;
+  label: string;
+  icon?: string;
+  disabled?: boolean;
+  tone?: 'danger';
+  onSelect: () => void;
+}
+
+/** One plugin-owned resource status on a core Project register card. */
+export interface PluginProjectRowStatus {
+  label: string;
+  icon?: string;
+  tone?: 'muted' | 'accent' | 'success' | 'warning' | 'danger';
+  busy?: boolean;
 }
 
+/** One plugin-owned resource metric. Percent is valid only for a real configured ceiling. */
+export interface PluginProjectRowMetric {
+  id: string;
+  label: string;
+  value: string;
+  valueText?: string;
+  description?: string;
+  percent?: number;
+  state: 'ready' | 'absolute' | 'unknown' | 'stopped' | 'unavailable';
+}
+
+/** A plugin's contribution to the Project register. Core owns the rows and only renders these optional
+ * projections and the plugin-owned overlay. */
+export interface PluginProjectRowContribution {
+  status?: Record<number, PluginProjectRowStatus>;
+  metrics?: Record<number, {
+    label: string;
+    items: PluginProjectRowMetric[];
+    refreshing?: boolean;
+    stale?: boolean;
+    staleLabel?: string;
+  }>;
+  actions?: Record<number, PluginProjectRowAction[]>;
+  overlay?: React.ReactNode;
+}
+
+export type PluginProjectRowsHook = (input: { projects: PluginUiProject[] }) => PluginProjectRowContribution;
+
 /** The selected core User DTO exposed only to administrator user-detail panels. Compatibility fields stay
  * present because plugins receive the same object as the host Users screen, not a second partial identity. */
 export interface PluginUiUser {
@@ -308,11 +367,91 @@ export interface PluginChatArtifactProps {
   narration?: string;
 }
 
+/** Dashboard metric input shared by plugin metric tiles. */
+export interface DashboardMetricProps {
+  now: number;
+  locale: string;
+  monthCostUsd: number | null;
+  monthTokens: number;
+}
+
+/** A generic card emitted by a plugin tool. The host keeps this wire shape opaque to slot renderers. */
+export interface BrainCard {
+  id: string;
+  title?: string;
+  items?: readonly {
+    text: string;
+    status?: 'pending' | 'in_progress' | 'completed';
+    startedAt?: number;
+    id?: string;
+    label?: string;
+    owner?: string;
+    blockedBy?: readonly string[];
+  }[];
+  body?: string;
+  pinned?: boolean;
+}
+
+/** The core conversation row handed to a history branch renderer. */
+export interface ConversationRow {
+  id: string;
+  title: string;
+  model: string;
+  updated_at: string;
+  running: boolean;
+  kind: 'conversation' | 'channel' | 'task';
+  tokens?: number;
+  ownerId?: number;
+  ownerLabel?: string;
+  platform?: string | null;
+  direct?: boolean;
+  lastWriterId?: number | null;
+  lastWriterLabel?: string | null;
+  parentSessionId?: string | null;
+}
+
+export interface PluginChatPickerProps {
+  plugin: string;
+  command: string;
+  sessionId: string | null;
+  argument?: string;
+  send: (text: string) => void;
+  close: () => void;
+}
+
+export interface PluginChatCardProps {
+  card: BrainCard;
+  sessionId: string | null;
+  live: boolean;
+  open: (command?: string) => void;
+}
+
+export interface PluginChatRailSectionProps {
+  variant: 'expanded' | 'compact';
+  sessionId: string | null;
+  data: unknown;
+  open: (target: string) => void;
+  closeMobile?: () => void;
+}
+
+export interface PluginHistoryBranchProps {
+  parent: ConversationRow;
+  items: readonly unknown[];
+  expanded: boolean;
+  toggle: () => void;
+  open: (target: string) => void;
+}
+
 /** What a bundle hands to window.__elowenRegisterPluginUi. Routes are `/`-joined segment patterns
  *  (`''` = the root page, `detail/:id` captures params). Contextual component maps are keyed by their
  *  matching manifest panel ids and mount only in the corresponding host surface. */
 export interface PluginUiRegistration {
   requiresApiVersion: number;
+  dashboardMetrics?: Record<string, ComponentType<DashboardMetricProps>>;
+  chatPickers?: Record<string, ComponentType<PluginChatPickerProps>>;
+  chatCards?: Record<string, ComponentType<PluginChatCardProps>>;
+  chatRailSections?: Record<string, ComponentType<PluginChatRailSectionProps>>;
+  historyBranches?: Record<string, ComponentType<PluginHistoryBranchProps>>;
   pages?: Record<string, ComponentType<PluginPageProps>>;
   account?: Record<string, ComponentType<PluginPageProps>>;
   /** For an `account` entry placed as `linkedAccount`: its one-line claim in the CLOSED Linked accounts
@@ -323,6 +462,8 @@ export interface PluginUiRegistration {
   accountChip?: Record<string, ComponentType<PluginPageProps>>;
   user?: Record<string, ComponentType<PluginUserPanelProps>>;
   project?: Record<string, ComponentType<PluginProjectPanelProps>>;
+  /** Actions and overlays contributed to the core Projects register. */
+  projectRows?: PluginProjectRowsHook;
   /** Inline chat views keyed by the artifact `view` selected by the publishing plugin. */
   chatArtifacts?: Record<string, ComponentType<PluginChatArtifactProps>>;
   settings?: Record<string, ComponentType<PluginPageProps>>;
@@ -342,6 +483,43 @@ export interface PluginUiRegistration {
   ownsPageFrame?: string[];
 }
 
+/** Every component name `window.ElowenUiRuntime.components` actually carries.
+ *
+ *  This used to be `Record<string, …>`, and an open record is how `C.Progress` reached production: the
+ *  todo rail asked for a primitive the host had never published, the bundle's own typecheck was happy
+ *  because any string is a key of an open record, and React was handed `undefined` at render time —
+ *  which the chat rail shows as "the plugin interface hit an error", naming nothing. The host asserts
+ *  itself against this union (`web/lib/pluginUi.tsx`), so publishing a primitive without listing it
+ *  here, or listing one the host does not publish, is a type error on the host side rather than a
+ *  crash on a user's screen.
+ *
+ *  A bundle that declares its own narrowed view of the runtime — which is the recommended shape, since
+ *  the runtime cannot publish prop types — runs its key names through `AssertPublished` to get the same
+ *  check in its own repository. */
+export type PluginUiComponentName =
+  | 'ActionMenu' | 'AutoSaveStatus' | 'Avatar' | 'BackendPicker' | 'Badge' | 'BrainModelField'
+  | 'Button' | 'Calendar' | 'ChangeStrip' | 'Checkbox' | 'ChoiceField' | 'CompactWorkspaceHeader'
+  | 'ConfirmDialog' | 'ContextMenu' | 'ControlSurfaceDocument' | 'ControlSurfaceRegister'
+  | 'ControlSurfaceState' | 'ControlSurfaceToolbar' | 'DataTable' | 'DataTableCell'
+  | 'DataTableChevronCell' | 'DataTableRow' | 'DataTableSelectCell' | 'DateRangeFilter'
+  | 'DetailBlock' | 'DirectoryPicker' | 'EmptyState' | 'EntityList' | 'EntityRow' | 'ErrorState'
+  | 'ExecutorPicker' | 'Field' | 'HelpTip' | 'IconButton' | 'Input' | 'LinkedAccountRow' | 'LiveTail'
+  | 'LoadingLine' | 'LoadingState' | 'ManageSelectionModal' | 'MarkdownAssetEditor' | 'Modal'
+  | 'ModalBody' | 'ModalFooter' | 'ModelCatalogField' | 'ModelIcon' | 'ModuleHeader' | 'MotionLayout'
+  | 'MotionLayoutItem' | 'MotionPresence' | 'OperationProgressDialog' | 'OutcomeBadge' | 'PageFilters'
+  | 'PageToolbar' | 'Pager' | 'PatchView' | 'PluginConfigEditor' | 'PluginPageFrame'
+  | 'PluginPageHeader' | 'PluginSection' | 'Progress' | 'ProgressRibbon' | 'ProjectFilterPills'
+  | 'ProjectIcon' | 'ProjectPill' | 'RailSectionHead' | 'ProviderLogo' | 'ProviderPicker' | 'RegisterSearch' | 'Segmented'
+  | 'SelectMenu' | 'SelectionSummary' | 'SettingsDocument' | 'SettingsGroup' | 'SettingsRow' | 'Slider'
+  | 'SpatialIdentity' | 'SpatialWorkspaceLayout' | 'Spinner' | 'SummaryChip' | 'TimeSeriesChart'
+  | 'Toggle' | 'WorkspaceDetailRail' | 'WorkspaceHero' | 'WorkspaceMetric' | 'WorkspacePage'
+  | 'WorkspaceShell' | 'WorkspaceTakeover';
+
+/** Fails the bundle's own typecheck when it names a component the host does not publish. Used as
+ *  `export type ComponentName = AssertPublished<keyof Components>` beside a bundle's narrowed runtime
+ *  declaration, where `Components` carries the real prop types the bundle passes. */
+export type AssertPublished<N extends PluginUiComponentName> = N;
+
 /** The host API surface a bundle finds on `window.ElowenUiRuntime`: the HOST's React instance (a
  *  bundle must never ship its own — the build aliases `react` imports here), a curated set of the
  *  app's UI components, an authenticated same-origin `api` fetch, and SPA navigation. */
@@ -350,7 +528,7 @@ export interface ElowenUiRuntime {
   react: typeof React;
   reactDom: typeof ReactDom;
   jsxRuntime: typeof JsxRuntime;
-  components: Record<string, ComponentType<never>> & {
+  components: Record<PluginUiComponentName, ComponentType<never>> & {
     AutoSaveStatus: ComponentType<AutoSaveStatusProps>;
     ProjectIcon: ComponentType<ProjectIconProps>;
   };

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 whenever
  *  a released bundle requires a newly published `ElowenUiRuntime` contract (see index.d.ts). */
-export const PLUGIN_UI_API_VERSION = 16;
+export const PLUGIN_UI_API_VERSION = 18;

package/package.json

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

package/theme.css

@@ -124,7 +124,7 @@
   --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. */
+     saturated diff/merge signal the owner expects while keeping white body text above AA contrast. */
   --color-toast-success: #1f883d;
   --color-toast-success-foreground: #ffffff;
   --color-warning: #edae49;