elowen-plugin-ui-kit 0.2.0 → 0.6.0

package/build.js

@@ -47,8 +47,8 @@ export async function buildPluginUiBundle({ entry, outfile, minify = false, node
  *  utility rendered unstyled there, with nothing the user could do about it. So the plugin brings its own.
  *
  *  Three scoping rules make that safe to drop into a running app, and each is load-bearing:
- *  - everything lands in `@layer utilities`, so the host's own utilities (declared in the same layer, but
- *    earlier in the cascade order the host establishes) are not globally outranked by a plugin's sheet;
+ *  - everything lands in `@layer utilities`, and the host loader inserts the plugin sheet BEFORE host styles,
+ *    so plugin-only classes exist while matching host utilities win by source order;
  *  - NO preflight — a plugin must never reset the host's elements;
  *  - NO prefix — the plugin shares class names with the shared components it renders from
  *    `window.ElowenUiRuntime`, which are styled by the host's sheet.
@@ -65,7 +65,7 @@ export async function buildPluginUiCss({ bundle, outfile }) {
 
   const source = resolve(bundle);
   const css = [
-    // Declare the layer order the host uses, so `utilities` sorts where the host puts it.
+    // Declare the standard Tailwind order; the host loader owns source order between plugin and host sheets.
     '@layer theme, base, components, utilities;',
     // Reference-only: gives the compiler the design system (Tailwind's defaults + the host tokens)
     // WITHOUT emitting a single variable or preflight rule of its own.

package/index.d.ts

@@ -10,7 +10,74 @@ 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: 1;
+export declare const PLUGIN_UI_API_VERSION: 11;
+
+/** Public props of `ElowenUiRuntime.components.Slider`. */
+export interface SliderProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'min' | 'max' | 'step' | 'type'> {
+  value: number;
+  onChange: (value: number) => void;
+  min?: number;
+  max?: number;
+  step?: number;
+}
+
+/** Public props of `ElowenUiRuntime.components.DirectoryPicker`. Selection reports the currently open
+ *  server directory; closing has no side effect. */
+export interface DirectoryPickerProps {
+  initialPath?: string;
+  onSelect: (path: string) => void;
+  onClose: () => void;
+}
+
+export type ConfirmDialogButtonVariant = 'default' | 'accent' | 'ghost' | 'danger' | 'ghost-danger' | 'outline' | 'outline-danger';
+
+/** Public props of the API 11 async-safe `ElowenUiRuntime.components.ConfirmDialog`. */
+export interface ConfirmDialogProps {
+  open: boolean;
+  title: string;
+  description?: string;
+  confirmLabel?: string;
+  confirmVariant?: ConfirmDialogButtonVariant;
+  pendingLabel?: string;
+  pending?: boolean;
+  disabled?: boolean;
+  /** Legacy confirm-only disable; unlike `disabled`, Cancel remains available. */
+  confirmDisabled?: boolean;
+  error?: React.ReactNode;
+  /** A promise enables the built-in pending lock; synchronous callbacks remain source-compatible. */
+  onConfirm: () => unknown;
+  onConfirmError?: (error: unknown) => void;
+  onClose: () => void;
+}
+
+/** Project metadata exposed to a contextual plugin panel. The Project remains core-owned; a panel uses
+ *  this identity to address only its own project-scoped API data. */
+export interface PluginUiProject {
+  id: number;
+  slug: string;
+  path: string;
+  notes: string;
+  icon?: string;
+}
+
+/** 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 {
+  id: number;
+  username: string;
+  created_at: string;
+  is_admin: boolean;
+  allowed_execs: string[];
+  disabled_tools: string[];
+  allowed_tools: string[];
+  granted_plugins: string[];
+  name: string;
+  email: string;
+  avatar: string;
+  default_exec: string;
+  advisor_exec: string;
+  advisor_autostart: boolean;
+}
 
 /** Props every plugin page/settings component receives. */
 export interface PluginPageProps {
@@ -33,13 +100,53 @@ export interface PluginPageProps {
   onSaveState?: (status: 'idle' | 'saving' | 'saved' | 'error', retry?: () => void) => void;
 }
 
+/** Props for a contextual Project panel. It is never a standalone route: the selected Project and panel
+ *  id come from the host's Project detail rail. */
+export interface PluginProjectPanelProps {
+  plugin: string;
+  panelId: string;
+  project: PluginUiProject;
+  surface: 'project';
+}
+
+/** Props for an administrator panel mounted for one selected core User. */
+export interface PluginUserPanelProps {
+  plugin: string;
+  panelId: string;
+  user: PluginUiUser;
+  surface: 'user';
+}
+
 /** What a bundle hands to window.__elowenRegisterPluginUi. Routes are `/`-joined segment patterns
- *  (`''` = the root page, `detail/:id` captures params). `settings` components are keyed by the
- *  manifest's `web.settings[].id` and render inside the Settings page's control deck. */
+ *  (`''` = 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;
   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
+   *  summary, keyed by the same panel id. Whether a connector is currently linked is a fact only the
+   *  bundle holds, so the host cannot draw this chip on its behalf — but it also must not mount the
+   *  PANEL to ask, which is why this is its own entry. Omit it and the summary simply says nothing
+   *  about this connector. Draw it with `components.SummaryChip` so it matches the chips beside it. */
+  accountChip?: Record<string, ComponentType<PluginPageProps>>;
+  user?: Record<string, ComponentType<PluginUserPanelProps>>;
+  project?: Record<string, ComponentType<PluginProjectPanelProps>>;
   settings?: Record<string, ComponentType<PluginPageProps>>;
+  /** Ids of `settings` sections that draw their OWN page frame — the shell, the masthead and the save
+   *  indicator — and therefore want none from the host.
+   *
+   *  The host serves a plugin's SOLE settings section as its page (`/p/<plugin>`) and wraps it in a
+   *  page column plus a masthead, because a section written for the Settings deck brings neither. A
+   *  section that renders `components.WorkspaceShell` itself then gets both twice: two nested page
+   *  frames, so the gutter and the bottom padding apply twice and the page is measurably narrower than
+   *  its sibling registers, above a masthead that is a zero-height row of margin holding an idle save
+   *  indicator. Naming the section here is how a bundle says "the frame is mine", and it is a fact only
+   *  the bundle holds — the host cannot see what a component renders without mounting it.
+   *
+   *  A section listed here owns the whole surface, so it also owns showing its own save state and must
+   *  not rely on `onSaveState` being displayed anywhere. Ids not present in `settings` are ignored. */
+  ownsPageFrame?: string[];
 }
 
 /** The host API surface a bundle finds on `window.ElowenUiRuntime`: the HOST's React instance (a

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 = 1;
+export const PLUGIN_UI_API_VERSION = 11;

package/package.json

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

package/theme.css

@@ -3,34 +3,86 @@
  * emit `var(--token, fallback)`. tests/contract/pluginUiKitTheme.test.ts fails the moment the two drift.
  */
 @theme {
-  /* OLED Ember: true black canvas, warm near-black surfaces, one unmistakable Elowen accent. */
-  --color-bg: #000000;
+  /* OLED Ember: true black canvas, warm near-black surfaces, one unmistakable Elowen ember. */
+  --color-background: #000000;
+  --color-foreground: #f7f3f0;
+
+  /* NOT a shadcn token. One ground between the canvas and a card, for the ambient chrome that has to
+     read as raised off `background` without being a card — the orbit pods, the section nodes, the
+     settings groups. shadcn's ramp goes straight from `background` to `card`. */
   --color-document: #030303;
-  --color-surface: #070707;
-  --color-elevated: #0d0d0d;
-  --color-overlay: #151515;
+
+  --color-card: #070707;
+  --color-card-foreground: var(--color-foreground);
+  --color-popover: #151515;
+  --color-popover-foreground: var(--color-foreground);
+
+  --color-muted: #0d0d0d;
+  --color-muted-foreground: #9d948e;
+  /* shadcn separates the secondary-button fill from the muted surface so a design can make one louder
+     than the other; ours does not, and an alias says that on purpose rather than by omission. */
+  --color-secondary: var(--color-muted);
+  --color-secondary-foreground: var(--color-foreground);
+
+  --color-accent: color-mix(in srgb, var(--color-foreground) 10%, transparent);
+  --color-accent-foreground: var(--color-foreground);
+
+  /* NOT a shadcn token: shadcn's text ramp stops at `muted-foreground`, and the app has a third step
+     carrying timestamps, units and table metadata. It still has to be READABLE, not decorative, so it is
+     held at >= 4.5:1 (WCAG AA, normal text) against every surface token — 4.57:1 on the lightest one,
+     --color-muted — while staying far enough under --color-muted-foreground (6.53:1 there) that the
+     three steps remain distinguishable. */
+  --color-subtle-foreground: #827974;
+
+  /* NOT a shadcn token. Opaque backing for anything that scrolls content UNDER itself — sticky table
+     headers, sticky toolbars. It must not be translucent or rows show through the header as it passes,
+     which rules out `accent`. Derived from the document ground so every skin, including forks this repo
+     cannot see, inherits a correct sticky colour without declaring one. */
+  --color-sticky: color-mix(in srgb, var(--color-document) 94%, var(--color-foreground) 6%);
+
   --color-border: #242424;
+  /* NOT a shadcn token: the heavier rule, for a scrollbar thumb and a focused edge. */
   --color-border-strong: #363636;
-  --color-accent: #ff5236;
-  --color-accent-hot: #ff735c;
+  /* Form-control edges are the app's ordinary border. shadcn separates `input` from `border` so a design
+     can make fields louder than cards; ours does not, and an alias says that on purpose rather than by
+     omission — a skin that wants the distinction overrides this one token. */
+  --color-input: var(--color-border);
+  --color-ring: var(--color-primary);
+
+  --color-primary: #ff5236;
+  /* The ink on a saturated fill. shadcn gives every fill its own `-foreground`, and the app deliberately
+     paints all of them with ONE ink, so the value is stated here once and the others alias it — a skin
+     that wants to split them overrides the individual names. */
+  --color-primary-foreground: #070707;
+  /* NOT shadcn tokens: the brand ember is a RAMP, not a single fill. `-hot` is its hover step and
+     `-bright` its pale far stop, so a heat gradient or a chart moves with a repaint instead of staying
+     orange under a blue design. */
+  --color-primary-hot: #ff735c;
   --color-ember: #ff9a62;
-  /* The pale end of the ember ramp — the far stop of a heat gradient, where the accent is the near one.
-     It is a token so a repaint moves the whole ramp; a literal in a chart would stay orange. */
   --color-ember-bright: #ffd09a;
 
-  --color-text: #f7f3f0;
-  --color-text-muted: #9d948e;
-  --color-text-subtle: #6e6661;
-
-  --color-danger: #e94d42;
+  --color-destructive: #e94d42;
+  --color-destructive-foreground: var(--color-primary-foreground);
+  /* NOT shadcn tokens. shadcn ships only `destructive`; an app that reports outcomes needs the other
+     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);
   --color-warning: #edae49;
-  --color-error: #e94d42;
   --color-info: #62a8ea;
-  --color-approve: #32c986;
-  --color-cancelled: #756d68;
 
-  /* Organic but disciplined: compact controls, roomier panels, never pill-shaped by default. */
+  /* The categorical series. Charts and legends read these and never a literal, so a repaint moves the
+     whole set. 1–3 are the brand ramp; 4 and 5 are deliberately UNLIKE it, so a swatch stays
+     distinguishable from its neighbours without borrowing `destructive` or `success` and implying a
+     state it does not mean. */
+  --color-chart-1: var(--color-primary);
+  --color-chart-2: var(--color-ember);
+  --color-chart-3: var(--color-ember-bright);
+  --color-chart-4: #a78bfa;
+  --color-chart-5: #f472b6;
+
+  /* Organic but disciplined: compact controls, roomier panels, never pill-shaped by default.
+     This scale ALREADY carries shadcn's names, so components use `rounded-sm|md|lg|xl|2xl` directly and
+     must never reach for `rounded-[var(--radius)]` — that would bypass the scale and pin one size. */
   --radius-sm: 0.375rem;
   --radius: 0.5rem;
   --radius-md: 0.625rem;
@@ -38,16 +90,6 @@
   --radius-xl: 1rem;
   --radius-2xl: 1.25rem;
 
-  --space-1: 0.25rem;
-  --space-2: 0.5rem;
-  --space-3: 0.75rem;
-  --space-4: 1rem;
-  --space-5: 1.25rem;
-  --space-6: 1.5rem;
-  --space-8: 2rem;
-  --space-10: 2.5rem;
-  --space-12: 3rem;
-
   --font-mono: var(--font-geist-mono), ui-monospace, "SF Mono", monospace;
   --font-sans: var(--font-geist-sans), -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
   --font-display: var(--font-geist-sans), var(--font-sans);
@@ -56,14 +98,14 @@
   --text-caption: 0.6875rem;
   --text-tiny: 0.5625rem;
 
-  /* The accent as a bare R G B triple, so shadow/glow tokens can compose alpha variants — and so a
+  /* The primary as a bare R G B triple, so shadow/glow tokens can compose alpha variants — and so a
      white-label theme can retint them by overriding this ONE variable instead of every baked shadow. */
-  --accent-rgb: 255 82 54;
+  --primary-rgb: 255 82 54;
   --shadow-card: 0 1px 0 rgb(255 255 255 / 0.025), 0 14px 40px rgb(0 0 0 / 0.2);
   --shadow-raised: 0 1px 0 rgb(255 255 255 / 0.04), 0 22px 64px rgb(0 0 0 / 0.48);
-  --shadow-ember: 0 16px 48px rgb(var(--accent-rgb) / 0.14);
-  --glow-active: 0 0 0 1px rgb(var(--accent-rgb) / 0.3), 0 0 24px rgb(var(--accent-rgb) / 0.22), 0 0 64px rgb(var(--accent-rgb) / 0.12);
-  --glow-soft: 0 0 44px rgb(var(--accent-rgb) / 0.1);
+  --shadow-ember: 0 16px 48px rgb(var(--primary-rgb) / 0.14);
+  --glow-active: 0 0 0 1px rgb(var(--primary-rgb) / 0.3), 0 0 24px rgb(var(--primary-rgb) / 0.22), 0 0 64px rgb(var(--primary-rgb) / 0.12);
+  --glow-soft: 0 0 44px rgb(var(--primary-rgb) / 0.1);
   --hairline: 1px solid rgb(255 255 255 / 0.075);
 
   --motion-instant: 80ms;