@openpen/module-api 1.1.1 → 1.3.0

package/src/uikit/components/DialogHost.vue

@@ -1,272 +0,0 @@
-<script setup lang="ts">
-/**
- * DialogHost — private host-internal component.
- *
- * HOST-INTERNAL: Do not export from any public barrel. Plugin authors never
- * interact with this component directly. The host mounts exactly one instance
- * at bootstrap; it renders the currently active imperative dialog request from
- * the useDialog() store.
- *
- * Rendering strategy:
- * - Reads the active request from _activeRequest (module-scoped reactive ref).
- * - Renders an <AppDialog> wired to that request's options.
- * - On ok / cancel / dismiss: resolves the request's Promise and advances queue.
- *
- * Settings window constraint: AppDialog internally injects MODAL_MANAGER_KEY
- * and CONTROL_BAR_ANIMATING_KEY. In the settings window those keys are not
- * provided (ControlBar only exists in the overlay/main window), so the dialog
- * falls back gracefully (no mutual exclusion, no animating-guard) — it still
- * renders and resolves correctly, just without those host integrations.
- */
-import { computed, inject, nextTick, provide, ref, watch } from 'vue'
-import AppDialog from './AppDialog.vue'
-// _activeRequest MUST come from the package barrel — see AppPopover.vue header
-// comment. The runtime build externalises '@openpen/module-api/uikit' so host
-// + uikit share the same module instance. A relative '../composables/useDialog'
-// import bundles a duplicate ref into the host bundle, causing useDialog()
-// callers to write to a different ref than DialogHost watches (dialog never
-// opens in production).
-import { _activeRequest, _resolveActive } from '@openpen/module-api/uikit'
-import { HOST_DIALOG_OPEN_COUNT_KEY } from '@openpen/module-api'
-import { DIALOG_PLUGIN_HANDLE_KEY } from '../composables/dialog-internal-keys'
-import type { DialogPluginComponentHandle } from '../composables/useDialogPluginComponent'
-
-const MODAL_ID = '__openpen_imperative_dialog__'
-
-// Increment/decrement the host-level dialog-open counter so ControlBar can
-// pause the auto-collapse timer while any imperative dialog is visible.
-// Falls back to a local ref when not provided (settings window has no host bar).
-const dialogOpenCount = inject(HOST_DIALOG_OPEN_COUNT_KEY, ref(0))
-
-// Whether the dialog is open: true when there is an active request.
-const isOpen = ref(false)
-
-// Prompt value — bound to the input in prompt dialogs.
-const promptValue = ref('')
-
-// Track the prompt input element so we can focus it on open.
-const promptInputRef = ref<HTMLInputElement | null>(null)
-
-// Watch the active request: open when a request arrives, close when cleared.
-watch(_activeRequest, (req) => {
-  if (req) {
-    if (req.kind === 'prompt') {
-      promptValue.value = req.opts.defaultValue ?? ''
-    }
-    if (!isOpen.value) {
-      dialogOpenCount.value++
-    }
-    isOpen.value = true
-    if (req.kind === 'prompt') {
-      nextTick(() => {
-        promptInputRef.value?.focus()
-      })
-    }
-  } else {
-    if (isOpen.value) {
-      dialogOpenCount.value = Math.max(0, dialogOpenCount.value - 1)
-    }
-    isOpen.value = false
-  }
-})
-
-// Derived from the active request for convenience.
-const req = computed(() => _activeRequest.value)
-const opts = computed(() => req.value?.opts)
-
-function handleOk() {
-  const r = _activeRequest.value
-  if (!r) return
-  if (r.kind === 'confirm') {
-    r.resolve(true)
-  } else if (r.kind === 'alert') {
-    r.resolve()
-  } else if (r.kind === 'prompt') {
-    r.resolve(promptValue.value)
-  }
-  // custom: custom component handles its own resolution via ok/cancel/dismiss
-  _resolveActive()
-}
-
-function handleCancel() {
-  const r = _activeRequest.value
-  if (!r) return
-  if (r.kind === 'confirm') {
-    r.resolve(false)
-  } else if (r.kind === 'prompt') {
-    r.resolve(null)
-  }
-  _resolveActive()
-}
-
-function handleUpdateOpen(v: boolean) {
-  if (!v) {
-    // Dialog closed via ESC / close button (not persistent).
-    const r = _activeRequest.value
-    if (!r) return
-    if (r.kind === 'confirm') {
-      r.resolve(false)
-    } else if (r.kind === 'alert') {
-      r.resolve()
-    } else if (r.kind === 'prompt') {
-      r.resolve(null)
-    } else if (r.kind === 'custom') {
-      r.resolve(null)
-    }
-    _resolveActive()
-  }
-}
-
-// ── Custom component plugin handle ───────────────────────────────────────────
-//
-// Provide the handle so custom components can call ok/cancel/dismiss via
-// useDialogPluginComponent(). We provide at this component level so only the
-// custom component subtree gets it.
-
-function customOk(payload?: unknown) {
-  const r = _activeRequest.value
-  if (!r || r.kind !== 'custom') return
-  r.resolve(payload ?? null)
-  _resolveActive()
-}
-
-function customCancel() {
-  const r = _activeRequest.value
-  if (!r || r.kind !== 'custom') return
-  r.resolve(null)
-  _resolveActive()
-}
-
-const pluginHandle: DialogPluginComponentHandle<unknown> = {
-  ok: customOk,
-  cancel: customCancel,
-  dismiss: customCancel,
-}
-
-provide(DIALOG_PLUGIN_HANDLE_KEY, pluginHandle)
-</script>
-
-<template>
-  <!-- DialogHost renders nothing when there is no active request. -->
-  <AppDialog
-    v-if="req"
-    :modal-id="MODAL_ID"
-    :title="opts!.title"
-    :open="isOpen"
-    :persistent="opts!.persistent"
-    :danger="opts!.danger"
-    @update:open="handleUpdateOpen"
-  >
-    <!-- Body slot: varies by kind -->
-    <template v-if="req.kind === 'confirm' || req.kind === 'alert'">
-      <p class="openpen-dialog-host-message">{{ (opts as { message: string }).message }}</p>
-    </template>
-
-    <template v-else-if="req.kind === 'prompt'">
-      <p class="openpen-dialog-host-message">{{ (opts as { message: string }).message }}</p>
-      <input
-        ref="promptInputRef"
-        v-model="promptValue"
-        class="openpen-dialog-host-input"
-        :placeholder="(opts as { placeholder?: string }).placeholder"
-        type="text"
-        @keydown.enter="handleOk"
-        @keydown.esc="handleCancel"
-      />
-    </template>
-
-    <template v-else-if="req.kind === 'custom'">
-      <!-- Render the custom component; it gets ok/cancel/dismiss via injection. -->
-      <component
-        :is="(opts as { component: unknown }).component"
-        v-bind="(opts as { componentProps?: Record<string, unknown> }).componentProps ?? {}"
-      />
-    </template>
-
-    <!-- Footer slot: only for confirm/alert/prompt; custom owns its own buttons. -->
-    <template v-if="req.kind !== 'custom'" #footer>
-      <button
-        v-if="req.kind === 'confirm' || req.kind === 'prompt'"
-        class="openpen-btn openpen-btn-secondary"
-        @click="handleCancel"
-      >
-        {{ (opts as { cancelLabel?: string }).cancelLabel ?? 'Cancel' }}
-      </button>
-      <button
-        class="openpen-btn openpen-btn-primary"
-        :class="{ 'openpen-btn-danger': opts!.danger }"
-        @click="handleOk"
-      >
-        {{ (opts as { okLabel?: string }).okLabel ?? 'OK' }}
-      </button>
-    </template>
-  </AppDialog>
-</template>
-
-<style>
-/* ── DialogHost utility styles ───────────────────────────────────────────── */
-.openpen-dialog-host-message {
-  margin: 0 0 var(--openpen-space-md, 12px) 0;
-  color: var(--openpen-color-text-primary, #fff);
-  line-height: 1.5;
-}
-
-.openpen-dialog-host-input {
-  display: block;
-  width: 100%;
-  box-sizing: border-box;
-  padding: 6px 10px;
-  border: 1px solid var(--openpen-color-border-hi, rgba(255,255,255,0.2));
-  border-radius: var(--openpen-radius-sm, 6px);
-  background: var(--openpen-color-control, rgba(255,255,255,0.08));
-  color: var(--openpen-color-text-primary, #fff);
-  font-size: 13px;
-  outline: none;
-}
-
-.openpen-dialog-host-input:focus {
-  border-color: var(--accent, #7c7cff);
-  box-shadow: 0 0 0 2px var(--accent-bg, rgba(124,124,255,0.18));
-}
-
-/* ── DialogHost button styles ─────────────────────────────────────────────── */
-.openpen-btn {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  padding: 6px 16px;
-  border-radius: var(--openpen-radius-sm, 6px);
-  font-size: 13px;
-  font-weight: 500;
-  cursor: pointer;
-  border: none;
-  transition: background var(--openpen-duration-fast, 120ms), color var(--openpen-duration-fast, 120ms);
-}
-
-.openpen-btn-secondary {
-  background: var(--openpen-color-control, rgba(255,255,255,0.08));
-  color: var(--openpen-color-text-primary, #fff);
-}
-
-.openpen-btn-secondary:hover {
-  background: var(--openpen-color-control-hover, rgba(255,255,255,0.14));
-}
-
-.openpen-btn-primary {
-  background: var(--accent, #7c7cff);
-  color: #fff;
-}
-
-.openpen-btn-primary:hover {
-  opacity: 0.9;
-}
-
-.openpen-btn-danger {
-  background: var(--openpen-color-danger, #e05252);
-  color: #fff;
-}
-
-.openpen-btn-danger:hover {
-  opacity: 0.9;
-}
-</style>

package/src/uikit/composables/useDialog.ts

@@ -1,141 +0,0 @@
-/**
- * useDialog — imperative dialog API for OpenPen modules.
- *
- * Returns a DialogApi with confirm/alert/prompt/custom methods that each
- * return a Promise. At most one imperative dialog is open at a time; extra
- * calls are queued and executed sequentially.
- *
- * The active request is stored in a module-scoped reactive store. DialogHost
- * (mounted by the host at bootstrap) reads this store and renders the dialog.
- *
- * Usage:
- *   const dialog = useDialog()
- *   const ok = await dialog.confirm({ title: 'Delete?', message: '...' })
- */
-import type { Component } from 'vue'
-import { ref } from 'vue'
-
-// ── Public option types ───────────────────────────────────────────────────────
-
-interface BaseDialogOptions {
-  title: string
-  persistent?: boolean
-  danger?: boolean
-}
-
-export interface DialogConfirmOptions extends BaseDialogOptions {
-  message: string
-  okLabel?: string
-  cancelLabel?: string
-}
-
-export interface DialogAlertOptions extends BaseDialogOptions {
-  message: string
-  okLabel?: string
-}
-
-export interface DialogPromptOptions extends BaseDialogOptions {
-  message: string
-  defaultValue?: string
-  placeholder?: string
-  okLabel?: string
-  cancelLabel?: string
-}
-
-export interface DialogCustomOptions<T = unknown> extends BaseDialogOptions {
-  component: Component
-  componentProps?: Record<string, unknown>
-  /** Phantom type field for TypeScript to infer the resolution payload type. */
-  __payloadType?: T
-}
-
-// ── Internal request types (tagged union) ─────────────────────────────────────
-
-type DialogRequest =
-  | { kind: 'confirm'; opts: DialogConfirmOptions; resolve: (v: boolean) => void }
-  | { kind: 'alert';   opts: DialogAlertOptions;   resolve: () => void }
-  | { kind: 'prompt';  opts: DialogPromptOptions;  resolve: (v: string | null) => void }
-  | { kind: 'custom';  opts: DialogCustomOptions<unknown>; resolve: (v: unknown) => void }
-
-// ── Module-scoped store ───────────────────────────────────────────────────────
-//
-// Single reactive ref holds the currently rendered request. DialogHost watches
-// this and renders the appropriate dialog. When DialogHost resolves a request,
-// it calls resolveActive() which drains the queue.
-
-export const _activeRequest = ref<DialogRequest | null>(null)
-
-const _queue: (() => void)[] = []
-let _processing = false
-
-function _enqueue(run: () => void): void {
-  if (_processing) {
-    _queue.push(run)
-  } else {
-    _processing = true
-    run()
-  }
-}
-
-/**
- * Called by DialogHost when the dialog is resolved (ok/cancel/dismiss).
- * Advances the queue if there are pending requests.
- */
-export function _resolveActive(): void {
-  _activeRequest.value = null
-  const next = _queue.shift()
-  if (next) {
-    next()
-  } else {
-    _processing = false
-  }
-}
-
-// ── Public API ────────────────────────────────────────────────────────────────
-
-export interface DialogApi {
-  confirm(opts: DialogConfirmOptions): Promise<boolean>
-  alert(opts: DialogAlertOptions): Promise<void>
-  prompt(opts: DialogPromptOptions): Promise<string | null>
-  custom<T = unknown>(opts: DialogCustomOptions<T>): Promise<T | null>
-}
-
-export function useDialog(): DialogApi {
-  return {
-    confirm(opts: DialogConfirmOptions): Promise<boolean> {
-      return new Promise<boolean>((resolve) => {
-        _enqueue(() => {
-          _activeRequest.value = { kind: 'confirm', opts, resolve }
-        })
-      })
-    },
-
-    alert(opts: DialogAlertOptions): Promise<void> {
-      return new Promise<void>((resolve) => {
-        _enqueue(() => {
-          _activeRequest.value = { kind: 'alert', opts, resolve }
-        })
-      })
-    },
-
-    prompt(opts: DialogPromptOptions): Promise<string | null> {
-      return new Promise<string | null>((resolve) => {
-        _enqueue(() => {
-          _activeRequest.value = { kind: 'prompt', opts, resolve }
-        })
-      })
-    },
-
-    custom<T = unknown>(opts: DialogCustomOptions<T>): Promise<T | null> {
-      return new Promise<T | null>((resolve) => {
-        _enqueue(() => {
-          _activeRequest.value = {
-            kind: 'custom',
-            opts: opts as DialogCustomOptions<unknown>,
-            resolve: resolve as (v: unknown) => void,
-          }
-        })
-      })
-    },
-  }
-}

package/src/uikit/composables/useDialogPluginComponent.ts

@@ -1,27 +0,0 @@
-/**
- * useDialogPluginComponent — composable for components rendered via useDialog().custom().
- *
- * The custom component calls this to get ok/cancel/dismiss callbacks, which
- * resolve the Promise returned by useDialog().custom().
- */
-import { inject } from 'vue'
-import { DIALOG_PLUGIN_HANDLE_KEY } from './dialog-internal-keys'
-
-export interface DialogPluginComponentHandle<T = unknown> {
-  /** Resolve with a payload value and close the dialog. */
-  ok(payload?: T): void
-  /** Resolve with null and close the dialog. */
-  cancel(): void
-  /** Alias for cancel() — resolves with null. */
-  dismiss(): void
-}
-
-export function useDialogPluginComponent<T = unknown>(): DialogPluginComponentHandle<T> {
-  const handle = inject(DIALOG_PLUGIN_HANDLE_KEY)
-  if (!handle) {
-    throw new Error(
-      'useDialogPluginComponent() must be called inside a component rendered via useDialog().custom()'
-    )
-  }
-  return handle as DialogPluginComponentHandle<T>
-}

package/src/uikit/index.ts

@@ -1,79 +0,0 @@
-/**
- * @openpen/module-api/uikit — Three-layer API surface
- *
- * Layer 1 — High-level Wrappers (80% case)
- *   OpenPen-opinionated components with preset styles + auto-injected host
- *   context. Plugin authors should start here: no knowledge of inject keys
- *   or Reka UI primitives required.
- *
- * Layer 2 — Primitive Re-exports (20% advanced)
- *   Raw Reka UI headless components. Use when you need full control over
- *   markup / styling but still want a11y / focus / keyboard nav behaviour.
- *   Note: you must manually handle modal-manager, animating guard,
- *   passthrough, and teleport target when walking this layer.
- *
- * Layer 3 — Escape Hatch (5% fully custom)
- *   Plugin installs reka-ui (or any library) directly in its own package.json.
- *   UIKit MUST NOT block this. Not handled here — plugin author's choice.
- *
- * See docs/reference/uikit.md for the full trade-off description.
- */
-
-// ── Layer 1: High-level Wrappers ──────────────────────────────────────────────
-
-export { default as AppPopover } from './components/AppPopover.vue'
-export type { AppPopoverProps, Placement } from './components/AppPopover.vue'
-
-export { default as AppSlider } from './components/AppSlider.vue'
-export { default as AppToggle } from './components/AppToggle.vue'
-export { default as AppSegmented } from './components/AppSegmented.vue'
-
-export { default as AppDialog } from './components/AppDialog.vue'
-export type { AppDialogProps } from './components/AppDialog.vue'
-
-export { useDialog } from './composables/useDialog'
-export type {
-  DialogConfirmOptions,
-  DialogAlertOptions,
-  DialogPromptOptions,
-  DialogCustomOptions,
-} from './composables/useDialog'
-export { useDialogPluginComponent } from './composables/useDialogPluginComponent'
-
-// Host-internal: shared by DialogHost so it sees the same _activeRequest ref
-// instance as useDialog() callers. MUST be exported via this barrel — the
-// uikit runtime bundle (dist/openpen-runtime/module-api-uikit.js) is the
-// single shared module instance referenced by the importmap; a relative
-// '../composables/useDialog' import in DialogHost would bundle a second
-// duplicate ref into the host bundle (see project_dev_prod_parity.md), so
-// dialog.confirm() would never reach DialogHost in production.
-// Underscore-prefixed: NOT part of the plugin-facing API surface.
-export { _activeRequest, _resolveActive } from './composables/useDialog'
-export { default as AppSelect } from './components/AppSelect.vue'
-export type { AppSelectProps, SelectOption } from './components/AppSelect.vue'
-export { default as AppTooltip } from './components/AppTooltip.vue'
-export type { AppTooltipProps, TooltipSide } from './components/AppTooltip.vue'
-export { default as AppTabs } from './components/AppTabs.vue'
-export type { AppTabsProps, AppTabItem } from './components/AppTabs.vue'
-
-export { default as AppBanner } from './components/AppBanner.vue'
-export type { BannerVariant } from './components/AppBanner.vue'
-
-export { default as AppButton } from './components/AppButton.vue'
-
-// ── Layer 2: Primitive Re-exports ────────────────────────────────────────────
-//
-// Re-export entire primitives namespace.
-// MUST NOT re-export any reka-ui type through this index — wrapper types only.
-// (primitives.ts is the designated channel for the raw headless exports.)
-export * from './primitives'
-
-// ── Host context inject keys ──────────────────────────────────────────────────
-//
-// Keys are defined in @openpen/module-api root inject-keys.ts and re-exported
-// here for convenience. Plugin authors who need to walk Layer 2 should import
-// from the root package:
-//   import { WRAPPER_EL_KEY, MODAL_MANAGER_KEY } from '@openpen/module-api'
-//
-// Root index.ts already covers:
-//   WRAPPER_EL_KEY, SNAP_EDGE_KEY, MODAL_MANAGER_KEY, ANCHOR_EL_KEY.

package/src/uikit/primitives.ts

@@ -1,150 +0,0 @@
-/**
- * Reka UI primitive re-exports.
- *
- * This module exposes the raw Reka UI headless components for plugin authors
- * who need full control over markup and styling but still want Reka UI's
- * a11y / focus / keyboard navigation behaviour.
- *
- * Usage (escape hatch from high-level wrappers):
- *   import { PopoverRoot, PopoverTrigger, ... } from '@openpen/module-api/uikit'
- *   // or directly:
- *   import { ... } from '@openpen/module-api/uikit/primitives'  (if re-exported)
- *
- * WARNING: Walking this layer means you must manually handle:
- *   - Modal manager mutual exclusion
- *   - ControlBar animation auto-close (inject CONTROL_BAR_ANIMATING_KEY)
- *   - Mouse passthrough guard (usePassthroughGuard)
- *   - Teleport target (inject WRAPPER_EL_KEY)
- *
- * See docs/reference/uikit.md for the full trade-off description.
- *
- * All v1.0 high-level wrappers are implemented — prefer them over
- * the corresponding primitive:
- *   Popover    → AppPopover
- *   Dialog     → AppDialog
- *   Slider     → AppSlider
- *   Switch     → AppToggle
- *   RadioGroup → AppSegmented
- *   Select     → AppSelect
- *   Tooltip    → AppTooltip
- *   Tabs       → AppTabs
- */
-
-// ── Popover ──────────────────────────────────────────────────────────────────
-export {
-  PopoverRoot,
-  PopoverTrigger,
-  PopoverPortal,
-  PopoverContent,
-  PopoverArrow,
-  PopoverClose,
-  PopoverAnchor,
-} from 'reka-ui'
-
-// ── Dialog (Modal) ────────────────────────────────────────────────────────────
-export {
-  DialogRoot,
-  DialogTrigger,
-  DialogPortal,
-  DialogContent,
-  DialogOverlay,
-  DialogClose,
-  DialogTitle,
-  DialogDescription,
-} from 'reka-ui'
-
-// ── Slider ────────────────────────────────────────────────────────────────────
-export {
-  SliderRoot,
-  SliderTrack,
-  SliderRange,
-  SliderThumb,
-} from 'reka-ui'
-
-// ── Switch (Toggle) ───────────────────────────────────────────────────────────
-export {
-  SwitchRoot,
-  SwitchThumb,
-} from 'reka-ui'
-
-// ── RadioGroup (Segmented) ────────────────────────────────────────────────────
-export {
-  RadioGroupRoot,
-  RadioGroupItem,
-  RadioGroupIndicator,
-} from 'reka-ui'
-
-// ── Select ────────────────────────────────────────────────────────────────────
-export {
-  SelectRoot,
-  SelectTrigger,
-  SelectPortal,
-  SelectContent,
-  SelectViewport,
-  SelectItem,
-  SelectItemText,
-  SelectItemIndicator,
-  SelectLabel,
-  SelectGroup,
-  SelectSeparator,
-  SelectScrollUpButton,
-  SelectScrollDownButton,
-  SelectArrow,
-  SelectValue,
-  SelectIcon,
-} from 'reka-ui'
-
-// ── Tooltip ───────────────────────────────────────────────────────────────────
-export {
-  TooltipProvider,
-  TooltipRoot,
-  TooltipTrigger,
-  TooltipPortal,
-  TooltipContent,
-  TooltipArrow,
-} from 'reka-ui'
-
-// ── Tabs ──────────────────────────────────────────────────────────────────────
-export {
-  TabsRoot,
-  TabsList,
-  TabsTrigger,
-  TabsContent,
-} from 'reka-ui'
-
-// ── NumberField (numeric spinner with +/- buttons) ────────────────────────────
-export {
-  NumberFieldRoot,
-  NumberFieldInput,
-  NumberFieldIncrement,
-  NumberFieldDecrement,
-} from 'reka-ui'
-
-// ── TagsInput (chip / token input) ────────────────────────────────────────────
-export {
-  TagsInputRoot,
-  TagsInputInput,
-  TagsInputItem,
-  TagsInputItemText,
-  TagsInputItemDelete,
-  TagsInputClear,
-} from 'reka-ui'
-
-// ── Combobox (searchable dropdown with free-text input) ───────────────────────
-export {
-  ComboboxRoot,
-  ComboboxAnchor,
-  ComboboxInput,
-  ComboboxTrigger,
-  ComboboxPortal,
-  ComboboxContent,
-  ComboboxViewport,
-  ComboboxItem,
-  ComboboxItemIndicator,
-  ComboboxGroup,
-  ComboboxLabel,
-  ComboboxSeparator,
-  ComboboxEmpty,
-  ComboboxArrow,
-  ComboboxCancel,
-} from 'reka-ui'