@openpen/module-api 1.1.1 → 1.3.0

package/src/uikit/components/AppPopover.vue

@@ -1,268 +0,0 @@
-<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

@@ -1,128 +0,0 @@
-<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
-  testid?: 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 }"
-        :data-testid="opt.testid"
-      >
-        <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

@@ -1,235 +0,0 @@
-<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>