@openpen/module-api 1.0.0

package/src/uikit/components/AppPopover.vue

@@ -0,0 +1,268 @@
+<script setup lang="ts">
+/**
+ * AppPopover — High-level wrapper (Layer 1).
+ *
+ * Plugin authors use this component without needing to know about inject
+ * keys, Reka UI, modal manager mutual exclusion, or the animating guard.
+ *
+ * Public API is stable: switching the underlying headless library in the
+ * future does not break the plugin author's code.
+ *
+ * Implementation notes:
+ * - placement 'auto' picks the initial Reka UI side based on snap edge:
+ *   vbar-left → 'right', vbar-right → 'left', horizontal → 'bottom'.
+ *   Reka UI's built-in flip middleware then handles viewport-edge collision.
+ * - usePassthroughGuard: called with the content element ref. The contentEl
+ *   ref is passed to usePassthroughGuard, which attaches mousemove/leave
+ *   handlers that toggle mouse passthrough based on pointer position.
+ */
+import { computed, inject, onMounted, ref, useTemplateRef, watch } from 'vue'
+import {
+  PopoverRoot,
+  PopoverTrigger,
+  PopoverPortal,
+  PopoverContent,
+  PopoverArrow,
+} from '../primitives'
+// Inject keys MUST come from the package barrel — the runtime build
+// externalises '@openpen/module-api' so host + uikit share the same Symbol
+// instances. Importing from the relative '../../inject-keys' path bundles a
+// duplicate Symbol into module-api-uikit.js, causing host's provide() and
+// uikit's inject() to miss each other (popover never opens, etc).
+import {
+  WRAPPER_EL_KEY,
+  MODAL_MANAGER_KEY,
+  CONTROL_BAR_ANIMATING_KEY,
+  POPOVER_PLACEMENT_HINT_KEY,
+} from '@openpen/module-api'
+import { usePassthroughGuard } from '../../host/passthrough'
+
+// ── OpenPen-owned type (MUST NOT reference reka-ui types) ─────────────────────
+
+/** Preferred placement for the popover content relative to the trigger. */
+export type Placement = 'auto' | 'top' | 'bottom' | 'left' | 'right'
+
+export interface AppPopoverProps {
+  /** Globally unique popover id; used for modal-stack mutual exclusion. */
+  popoverId: string
+  /**
+   * Popover placement direction.
+   * - 'auto' (default, recommended): the host's snap-edge hint picks the side that
+   *   keeps the popover on-screen across all control-bar modes.
+   * - explicit values ('top' | 'bottom' | 'left' | 'right'): bypass the auto hint.
+   *   In dev mode a console warning is emitted because explicit values can position
+   *   popovers off-screen or away from the trigger button when the control bar is
+   *   in a vertical mode. Only use when you have verified the placement stays
+   *   on-screen across all snap layouts.
+   */
+  placement?: Placement
+  /** Gap between trigger and content in px. Default 8. */
+  gap?: number
+}
+
+export interface AppPopoverSlots {
+  /** Trigger slot; scope exposes active state + toggle / open / close actions. */
+  trigger: (scope: {
+    active: boolean
+    toggle: () => void
+    open: () => void
+    close: () => void
+  }) => unknown
+  /** Popover content slot. */
+  content: () => unknown
+}
+
+const props = withDefaults(defineProps<AppPopoverProps>(), {
+  placement: 'auto',
+  gap: 8,
+})
+
+defineSlots<AppPopoverSlots>()
+
+// ── 0. Dev-mode guard: warn plugin authors about risky explicit placement ─────
+onMounted(() => {
+  if (!import.meta.env.DEV) return
+  if (props.placement !== 'auto' && props.placement !== undefined) {
+    console.warn(
+      `[AppPopover] Explicit placement="${props.placement}" bypasses ` +
+      `the host's snap-edge auto detection. In vertical control-bar modes ` +
+      `this can position popups off-screen or away from the trigger button. ` +
+      `Prefer placement="auto" (default) and let the host pick the side; ` +
+      `use an explicit value only when you have verified it stays on-screen ` +
+      `across snap-left / snap-right / snap-free / horizontal layouts.`
+    )
+  }
+})
+
+// ── 1. Inject host context (plugin author never sees these) ───────────────────
+
+const wrapperElRef = inject(WRAPPER_EL_KEY)
+const wrapperEl = computed<HTMLElement | null>(() => wrapperElRef?.value ?? null)
+const modalManager = inject(MODAL_MANAGER_KEY)
+const animating = inject(CONTROL_BAR_ANIMATING_KEY)
+const popoverPlacementHint = inject(POPOVER_PLACEMENT_HINT_KEY)
+
+// ── 2. Modal manager mutual exclusion ────────────────────────────────────────
+
+const isOpen = computed(() => modalManager?.isOpen(props.popoverId) ?? false)
+
+function open() {
+  modalManager?.open(props.popoverId)
+}
+
+function close() {
+  modalManager?.close(props.popoverId)
+}
+
+function toggle() {
+  if (isOpen.value) {
+    close()
+  } else {
+    open()
+  }
+}
+
+// Sync Reka UI's controlled open state back to modal manager.
+// Reka UI may close via Escape / outside-click; we must keep manager in sync.
+function onUpdateOpen(v: boolean) {
+  if (v) {
+    open()
+  } else {
+    close()
+  }
+}
+
+// ── 3. ControlBar animation guard — auto-close during transitions ────────────
+
+watch(
+  () => animating?.value,
+  (isAnimating) => {
+    if (isAnimating && isOpen.value) {
+      close()
+    }
+  }
+)
+
+// ── 4. placement → Reka UI side mapping ──────────────────────────────────────
+//
+// 'auto' uses the POPOVER_PLACEMENT_HINT_KEY provided by ControlBar. The hint
+// encodes a two-tier UX rule:
+//   - Snap edge set → open away from the edge (left→right, right→left, etc.)
+//   - Snap off → open toward the side with more screen space on the relevant axis
+//     (horizontal bar: top/bottom; vertical bar: left/right)
+// Reka UI's built-in flip middleware handles secondary overflow. The window is
+// workArea-sized, so the viewport equals the workArea and floating-ui's collision
+// detection is correct without any boundary-proxy workaround.
+
+type RekaSide = 'top' | 'bottom' | 'left' | 'right'
+
+const rekaSide = computed<RekaSide>(() => {
+  if (props.placement !== 'auto') return props.placement as RekaSide
+  // Fall back to 'bottom' only if no hint is provided (e.g. standalone use outside ControlBar).
+  return popoverPlacementHint?.value ?? 'bottom'
+})
+
+// ── 5. Passthrough guard integration ─────────────────────────────────────────
+//
+// usePassthroughGuard is called with the content element ref. Reka UI's
+// PopoverContent is a Vue component, so the template ref resolves to a
+// component instance (with `$el`) rather than a raw HTMLElement. We normalize
+// via a watcher so the guard receives a plain element ref.
+// openpen-interactive class enables the ControlBar passthrough guard's CSS selector path.
+const contentInstance = useTemplateRef<HTMLElement | { $el?: HTMLElement } | null>('content')
+const contentEl = ref<HTMLElement | null>(null)
+watch(contentInstance, (instance) => {
+  if (!instance) {
+    contentEl.value = null
+  } else if (instance instanceof HTMLElement) {
+    contentEl.value = instance
+  } else if (typeof instance === 'object' && '$el' in instance && instance.$el instanceof HTMLElement) {
+    contentEl.value = instance.$el
+  } else {
+    contentEl.value = null
+  }
+})
+usePassthroughGuard(contentEl)
+</script>
+
+<template>
+  <PopoverRoot :open="isOpen" @update:open="onUpdateOpen">
+    <PopoverTrigger as-child>
+      <slot
+        name="trigger"
+        :active="isOpen"
+        :toggle="toggle"
+        :open="open"
+        :close="close"
+      />
+    </PopoverTrigger>
+    <PopoverPortal :to="wrapperEl ?? undefined">
+      <PopoverContent
+        ref="content"
+        :side="rekaSide"
+        :avoid-collisions="true"
+        :side-offset="props.gap"
+        class="openpen-popover-content openpen-interactive"
+      >
+        <slot name="content" />
+        <!-- Arrow geometry: 14×8 sharp triangle. Fill shares
+             --openpen-color-popover-frame with the popup border so the arrow
+             reads as a continuous extension of the frame. See tokens.css for
+             per-theme values. -->
+        <PopoverArrow class="openpen-popover-arrow" :width="14" :height="8" />
+      </PopoverContent>
+    </PopoverPortal>
+  </PopoverRoot>
+</template>
+
+<!-- Styles for teleported PopoverContent MUST be unscoped — Vue scoped CSS
+     does not follow Teleport targets, so .openpen-popover-content would not
+     receive the scoped data-v-* attribute when rendered inside the portal. -->
+<style>
+.openpen-popover-content {
+  background: var(--openpen-color-surface-popup);
+  border: 1px solid var(--openpen-color-popover-frame);
+  border-radius: var(--openpen-radius-lg);
+  padding: 14px 16px;
+  color: var(--openpen-color-text-primary);
+  font-size: 13px;
+  box-shadow: var(--openpen-shadow);
+  backdrop-filter: var(--openpen-blur);
+  -webkit-backdrop-filter: var(--openpen-blur);
+  z-index: 100;
+  /* Prevent pointer events from leaking through transparent gaps. */
+  pointer-events: auto;
+}
+
+.openpen-popover-arrow {
+  fill: var(--openpen-color-popover-frame);
+}
+
+/* ── Open / close animations ────────────────────────────────────────────────
+   Reka UI's Presence keeps the element in the DOM until the running CSS
+   animation ends, so animations targeting [data-state="closed"] DO play
+   on close. transform-origin tracks data-side so the popover scales out
+   from the trigger instead of from its own center.
+
+   Timings: 200ms easeOutBack enter, 150ms ease leave. */
+.openpen-popover-content[data-state='open'] {
+  animation: openpen-popover-in 200ms cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+.openpen-popover-content[data-state='closed'] {
+  animation: openpen-popover-out 150ms ease forwards;
+}
+
+.openpen-popover-content[data-side='bottom'] { transform-origin: top center; }
+.openpen-popover-content[data-side='top']    { transform-origin: bottom center; }
+.openpen-popover-content[data-side='left']   { transform-origin: right center; }
+.openpen-popover-content[data-side='right']  { transform-origin: left center; }
+
+@keyframes openpen-popover-in {
+  from { opacity: 0; transform: scale(0.92); }
+  to   { opacity: 1; transform: scale(1); }
+}
+@keyframes openpen-popover-out {
+  from { opacity: 1; transform: scale(1); }
+  to   { opacity: 0; transform: scale(0.92); }
+}
+</style>

package/src/uikit/components/AppSegmented.vue

@@ -0,0 +1,126 @@
+<script setup lang="ts">
+/**
+ * AppSegmented — High-level wrapper (Layer 1).
+ *
+ * Wraps Reka UI RadioGroup (RadioGroupRoot / RadioGroupItem).
+ *
+ * Visual: flex gap 4px, 1.5px border var(--border-hi),
+ * active = var(--accent-bg) background + var(--accent) color.
+ *
+ * Styles use --openpen-* design tokens.
+ * No Reka UI types are leaked in the public API.
+ */
+import {
+  RadioGroupRoot,
+  RadioGroupItem,
+} from '../primitives'
+
+// ── Public API (MUST NOT reference reka-ui types) ─────────────────────────────
+
+interface Option {
+  value: string
+  label: string
+  icon?: string
+}
+
+defineProps<{
+  modelValue: string
+  options: Option[]
+  /** When true, all options are non-interactive and visually dimmed. */
+  disabled?: boolean
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+}>()
+
+// AcceptableValue from Reka UI can be null; we narrow to string so the public API has no Reka UI type leakage.
+function onValueChange(val: unknown) {
+  if (typeof val === 'string') {
+    emit('update:modelValue', val)
+  }
+}
+</script>
+
+<template>
+  <RadioGroupRoot
+    class="app-seg"
+    :class="{ 'app-seg--disabled': disabled }"
+    :model-value="modelValue"
+    :disabled="disabled"
+    orientation="horizontal"
+    @update:model-value="onValueChange"
+  >
+    <RadioGroupItem
+      v-for="opt in options"
+      :key="opt.value"
+      :value="opt.value"
+      as-child
+    >
+      <button
+        class="app-seg-btn"
+        :class="{ active: modelValue === opt.value }"
+      >
+        <span
+          v-if="opt.icon"
+          class="app-seg-icon"
+          aria-hidden="true"
+          v-html="opt.icon"
+        />
+        <span>{{ opt.label }}</span>
+      </button>
+    </RadioGroupItem>
+  </RadioGroupRoot>
+</template>
+
+<style scoped>
+.app-seg {
+  display: flex;
+  gap: var(--openpen-space-xs);
+}
+
+.app-seg-btn {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  padding: 6px var(--openpen-space-lg);
+  border: 1.5px solid var(--openpen-color-border-hi);
+  border-radius: var(--openpen-radius-sm);
+  background: var(--openpen-color-input-bg);
+  color: var(--openpen-color-text-dim);
+  font-size: 12px;
+  font-weight: 600;
+  cursor: pointer;
+  white-space: nowrap;
+  transition:
+    background var(--openpen-duration-fast) var(--openpen-easing-standard),
+    color var(--openpen-duration-fast) var(--openpen-easing-standard),
+    border-color var(--openpen-duration-fast) var(--openpen-easing-standard);
+}
+
+.app-seg-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  line-height: 0;
+}
+
+.app-seg-btn:hover {
+  color: var(--openpen-color-text-primary);
+  background: var(--openpen-color-control-hover);
+}
+
+.app-seg-btn.active {
+  background: var(--openpen-color-accent-bg);
+  color: var(--openpen-color-accent);
+  border-color: color-mix(in srgb, var(--openpen-color-accent) 40%, transparent);
+}
+
+.app-seg--disabled {
+  opacity: 0.45;
+  pointer-events: none;
+  cursor: not-allowed;
+}
+</style>

package/src/uikit/components/AppSelect.vue

@@ -0,0 +1,235 @@
+<script setup lang="ts">
+/**
+ * AppSelect — High-level wrapper (Layer 1).
+ *
+ * Plugin authors use this component without needing to know about Reka UI's
+ * Select primitives. The API surface is OpenPen-owned and stable.
+ *
+ * Public API is stable: switching the underlying headless library in the
+ * future does not break the plugin author's code.
+ *
+ * Implementation notes:
+ * - Controlled via modelValue / update:modelValue (standard Vue v-model pattern).
+ * - options[] is an OpenPen-owned type; no Reka UI types leak to the public API.
+ * - Popup styling mirrors surface-popup tokens (same as AppPopover content).
+ * - Styles are unscoped because SelectContent is teleported via SelectPortal.
+ */
+import {
+  SelectRoot,
+  SelectTrigger,
+  SelectPortal,
+  SelectContent,
+  SelectViewport,
+  SelectItem,
+  SelectItemText,
+  SelectItemIndicator,
+  SelectValue,
+  SelectIcon,
+} from '../primitives'
+
+// ── OpenPen-owned types (MUST NOT reference reka-ui types) ───────────────────
+
+/** A single option in the dropdown list. */
+export interface SelectOption {
+  /** The value emitted on selection. */
+  value: string
+  /** The label shown to the user. */
+  label: string
+}
+
+export interface AppSelectProps {
+  /** Currently selected value (bind with v-model). */
+  modelValue: string
+  /** List of selectable options. */
+  options: SelectOption[]
+  /** Placeholder shown when no option is selected. */
+  placeholder: string
+  /** Whether the select is disabled. */
+  disabled?: boolean
+}
+
+const props = withDefaults(defineProps<AppSelectProps>(), {
+  disabled: false,
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+}>()
+
+function onValueChange(v: string) {
+  emit('update:modelValue', v)
+}
+</script>
+
+<template>
+  <SelectRoot
+    :model-value="modelValue"
+    :disabled="disabled"
+    @update:model-value="onValueChange"
+  >
+    <SelectTrigger class="openpen-select-trigger">
+      <SelectValue :placeholder="placeholder" />
+      <SelectIcon class="openpen-select-icon" aria-hidden="true">
+        <svg width="12" height="12" viewBox="0 0 12 12" fill="none">
+          <path d="M2 4L6 8L10 4" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+        </svg>
+      </SelectIcon>
+    </SelectTrigger>
+    <SelectPortal>
+      <SelectContent class="openpen-select-content" position="popper" :side-offset="4">
+        <SelectViewport class="openpen-select-viewport">
+          <SelectItem
+            v-for="option in options"
+            :key="option.value"
+            :value="option.value"
+            class="openpen-select-item"
+          >
+            <SelectItemIndicator class="openpen-select-item-indicator">
+              <svg width="12" height="12" viewBox="0 0 12 12" fill="none" aria-hidden="true">
+                <path d="M2 6L5 9L10 3" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+              </svg>
+            </SelectItemIndicator>
+            <SelectItemText>{{ option.label }}</SelectItemText>
+          </SelectItem>
+        </SelectViewport>
+      </SelectContent>
+    </SelectPortal>
+  </SelectRoot>
+</template>
+
+<!-- Styles MUST be unscoped — Vue scoped CSS does not follow Teleport targets,
+     so .openpen-select-* classes would not receive the scoped data-v-* attribute
+     when rendered inside the portal. -->
+<style>
+/* ── Trigger ─────────────────────────────────────────────────────────────── */
+.openpen-select-trigger {
+  display: inline-flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--openpen-space-sm);
+  min-width: 120px;
+  height: 32px;
+  padding: 0 var(--openpen-space-md);
+  background: var(--openpen-color-input-bg);
+  border: 1px solid var(--openpen-color-border-hi);
+  border-radius: var(--openpen-radius-md);
+  color: var(--openpen-color-text-primary);
+  font-size: 13px;
+  cursor: pointer;
+  transition:
+    background var(--openpen-duration-fast),
+    border-color var(--openpen-duration-fast);
+  outline: none;
+  white-space: nowrap;
+  user-select: none;
+}
+
+.openpen-select-trigger:hover {
+  background: var(--openpen-color-control-hover);
+  border-color: var(--openpen-color-border-hi);
+}
+
+.openpen-select-trigger:focus-visible {
+  border-color: var(--openpen-color-accent);
+  box-shadow: 0 0 0 2px var(--openpen-color-accent-glow);
+}
+
+.openpen-select-trigger[data-disabled] {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+/* ── Trigger icon (chevron) ──────────────────────────────────────────────── */
+.openpen-select-icon {
+  color: var(--openpen-color-text-dim);
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  transition: transform var(--openpen-duration-fast);
+}
+
+.openpen-select-trigger[data-state='open'] .openpen-select-icon {
+  transform: rotate(180deg);
+}
+
+/* ── Dropdown content ────────────────────────────────────────────────────── */
+.openpen-select-content {
+  background: var(--openpen-color-surface-popup);
+  border: 1px solid var(--openpen-color-border-hi);
+  border-radius: var(--openpen-radius-md);
+  box-shadow: var(--openpen-shadow);
+  backdrop-filter: var(--openpen-blur);
+  -webkit-backdrop-filter: var(--openpen-blur);
+  z-index: 100;
+  pointer-events: auto;
+  /* Match trigger width */
+  min-width: var(--reka-select-trigger-width, 120px);
+  max-height: 240px;
+  overflow: hidden;
+}
+
+/* ── Viewport scrollable area ────────────────────────────────────────────── */
+.openpen-select-viewport {
+  padding: var(--openpen-space-xs);
+}
+
+/* ── Individual items ────────────────────────────────────────────────────── */
+.openpen-select-item {
+  display: flex;
+  align-items: center;
+  gap: var(--openpen-space-sm);
+  height: 30px;
+  padding: 0 var(--openpen-space-md);
+  padding-left: 28px; /* indent to align text past indicator */
+  border-radius: var(--openpen-radius-sm);
+  font-size: 13px;
+  color: var(--openpen-color-text-primary);
+  cursor: pointer;
+  position: relative;
+  user-select: none;
+  outline: none;
+  transition: background var(--openpen-duration-fast);
+}
+
+.openpen-select-item[data-highlighted] {
+  background: var(--openpen-color-control-hover);
+  color: var(--openpen-color-text-primary);
+}
+
+.openpen-select-item[data-state='checked'] {
+  color: var(--openpen-color-accent);
+}
+
+.openpen-select-item[data-disabled] {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+/* ── Selected item indicator (checkmark) ─────────────────────────────────── */
+.openpen-select-item-indicator {
+  position: absolute;
+  left: var(--openpen-space-sm);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--openpen-color-accent);
+}
+
+/* ── Open / close animations ─────────────────────────────────────────────────
+   Pattern matches AppPopover keyframes (200ms bounce enter, 150ms ease leave). */
+.openpen-select-content[data-state='open'] {
+  animation: openpen-select-in 200ms cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+.openpen-select-content[data-state='closed'] {
+  animation: openpen-select-out 150ms ease forwards;
+}
+
+@keyframes openpen-select-in {
+  from { opacity: 0; transform: scale(0.95); }
+  to   { opacity: 1; transform: scale(1); }
+}
+@keyframes openpen-select-out {
+  from { opacity: 1; transform: scale(1); }
+  to   { opacity: 0; transform: scale(0.95); }
+}
+</style>