@openpen/module-api 1.0.0

package/src/uikit/components/AppSlider.vue

@@ -0,0 +1,204 @@
+<script setup lang="ts">
+/**
+ * AppSlider — High-level wrapper (Layer 1).
+ *
+ * Wraps Reka UI Slider (SliderRoot / SliderTrack / SliderRange / SliderThumb).
+ *
+ * Visual: 4px track, 14×14 white thumb, accent fill,
+ * hover scale(1.2) at var(--openpen-duration-fast) easing.
+ *
+ * Styles use --openpen-* design tokens.
+ * No Reka UI types are leaked in the public API.
+ */
+import { computed } from 'vue'
+import {
+  SliderRoot,
+  SliderTrack,
+  SliderRange,
+  SliderThumb,
+} from '../primitives'
+
+// ── Public API (MUST NOT reference reka-ui types) ─────────────────────────────
+
+const props = withDefaults(defineProps<{
+  modelValue: number
+  min?: number
+  max?: number
+  step?: number
+  /** Container width (e.g. '100%', '72px'). In vertical mode this sets the height. */
+  width?: string
+  orientation?: 'horizontal' | 'vertical'
+  trackHeight?: string
+  trackRadius?: string
+  thumbWidth?: string
+  thumbHeight?: string
+  thumbRadius?: string
+  /**
+   * Reverse the value-to-position mapping. With orientation='vertical', sets
+   * top=min and bottom=max (drag down to increase). With orientation='horizontal',
+   * sets right=min and left=max (drag left to increase). Useful when an icon
+   * legend implies the opposite direction of the underlying control.
+   *
+   * Delegates to reka-ui SliderRoot's native `inverted` prop, which swaps
+   * startEdge/endEdge on SliderRange — no manual value transformation needed.
+   */
+  inverted?: boolean
+}>(), {
+  min: 0,
+  max: 100,
+  step: 1,
+  width: '100%',
+  orientation: 'horizontal',
+  trackHeight: '4px',
+  trackRadius: '2px',
+  thumbWidth: '14px',
+  thumbHeight: '14px',
+  thumbRadius: '50%',
+  inverted: false,
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: number]
+}>()
+
+// ── Internal state ────────────────────────────────────────────────────────────
+
+const isVertical = computed(() => props.orientation === 'vertical')
+
+/** Fill percentage for the track range background. */
+const fillPct = computed(() => {
+  const range = props.max - props.min
+  if (range === 0) return '0.00%'
+  const pct = ((props.modelValue - props.min) / range) * 100
+  return Math.max(0, Math.min(100, pct)).toFixed(2) + '%'
+})
+
+/** Root element inline style */
+const rootStyle = computed(() => {
+  if (isVertical.value) {
+    return {
+      '--thumb-w': props.thumbWidth,
+      '--thumb-h': props.thumbHeight,
+      '--thumb-r': props.thumbRadius,
+      '--fill-pct': fillPct.value,
+      '--track-height': props.trackHeight,
+      '--track-radius': props.trackRadius,
+      height: props.width,
+      width: '16px',
+    }
+  }
+  return {
+    '--thumb-w': props.thumbWidth,
+    '--thumb-h': props.thumbHeight,
+    '--thumb-r': props.thumbRadius,
+    '--fill-pct': fillPct.value,
+    '--track-height': props.trackHeight,
+    '--track-radius': props.trackRadius,
+    width: props.width,
+  }
+})
+
+function onValueChange(val: number[] | undefined) {
+  if (val && val.length > 0) {
+    emit('update:modelValue', val[0])
+  }
+}
+</script>
+
+<template>
+  <SliderRoot
+    class="app-slider-root"
+    :class="{ 'app-slider-root--vertical': isVertical, 'app-slider-root--inverted': inverted }"
+    :style="rootStyle"
+    :model-value="[modelValue]"
+    :min="min"
+    :max="max"
+    :step="step"
+    :orientation="orientation"
+    :inverted="inverted"
+    @update:model-value="onValueChange"
+  >
+    <SliderTrack class="app-slider-track">
+      <SliderRange class="app-slider-range" />
+    </SliderTrack>
+    <SliderThumb class="app-slider-thumb" />
+  </SliderRoot>
+</template>
+
+<style scoped>
+/* ── Root container ────────────────────────────────────────────────────────── */
+.app-slider-root {
+  position: relative;
+  display: flex;
+  align-items: center;
+  user-select: none;
+  touch-action: none;
+  flex-shrink: 0;
+  cursor: pointer;
+}
+
+.app-slider-root[data-orientation='horizontal'] {
+  height: var(--track-height, 4px);
+}
+
+.app-slider-root[data-orientation='vertical'] {
+  flex-direction: column;
+  width: var(--track-height, 4px);
+}
+
+/* ── Track ─────────────────────────────────────────────────────────────────── */
+.app-slider-track {
+  position: relative;
+  flex-grow: 1;
+  border-radius: var(--track-radius, 2px);
+  background: var(--openpen-color-border-hi);
+}
+
+.app-slider-root[data-orientation='horizontal'] .app-slider-track {
+  height: var(--track-height, 4px);
+}
+
+.app-slider-root[data-orientation='vertical'] .app-slider-track {
+  width: var(--track-height, 4px);
+}
+
+/* ── Range (filled portion) ─────────────────────────────────────────────────── */
+.app-slider-range {
+  position: absolute;
+  border-radius: var(--track-radius, 2px);
+  background: var(--openpen-color-accent);
+}
+
+.app-slider-root[data-orientation='horizontal'] .app-slider-range {
+  height: 100%;
+  top: 0;
+  left: 0;
+}
+
+.app-slider-root[data-orientation='vertical'] .app-slider-range {
+  width: 100%;
+  bottom: 0;
+  left: 0;
+}
+
+/* ── Thumb ─────────────────────────────────────────────────────────────────── */
+.app-slider-thumb {
+  display: block;
+  width: var(--thumb-w, 14px);
+  height: var(--thumb-h, 14px);
+  border-radius: var(--thumb-r, 50%);
+  background: #fff;
+  box-shadow: 0 1px 6px rgba(0, 0, 0, 0.50);
+  cursor: pointer;
+  outline: none;
+  transition: transform var(--openpen-duration-fast) var(--openpen-easing-standard);
+}
+
+.app-slider-thumb:hover {
+  transform: scale(1.2);
+}
+
+.app-slider-thumb:focus-visible {
+  box-shadow: 0 0 0 3px var(--openpen-color-accent-glow);
+}
+</style>

package/src/uikit/components/AppTabs.vue

@@ -0,0 +1,163 @@
+<script setup lang="ts">
+/**
+ * AppTabs — High-level wrapper (Layer 1).
+ *
+ * Wraps Reka UI Tabs (TabsRoot / TabsList / TabsTrigger / TabsContent).
+ * Intended for settings UI tabbed navigation and any plugin tab panel.
+ *
+ * Plugin authors get a controlled tab switcher with OpenPen styling without
+ * knowing about Reka UI internals.
+ *
+ * Styles use --openpen-* design tokens.
+ * No Reka UI types are leaked in the public API.
+ *
+ * Usage:
+ *   <AppTabs
+ *     v-model="activeTab"
+ *     :tabs="[{ id: 'general', label: 'General' }, { id: 'advanced', label: 'Advanced' }]"
+ *   >
+ *     <template #default="{ activeTabId }">
+ *       <div v-if="activeTabId === 'general'">...</div>
+ *       <div v-if="activeTabId === 'advanced'">...</div>
+ *     </template>
+ *   </AppTabs>
+ */
+import {
+  TabsRoot,
+  TabsList,
+  TabsTrigger,
+  TabsContent,
+} from '../primitives'
+
+// ── OpenPen-owned types (MUST NOT reference reka-ui types) ────────────────────
+
+export interface AppTabItem {
+  /** Unique identifier for this tab. Used as the v-model value. */
+  id: string
+  /** Human-readable label rendered in the tab trigger button. */
+  label: string
+}
+
+export interface AppTabsProps {
+  /** Currently active tab id (controlled mode). */
+  modelValue: string
+  /** Ordered list of tab descriptors. */
+  tabs: AppTabItem[]
+}
+
+export interface AppTabsSlots {
+  /**
+   * Default slot for tab content area.
+   * Receives the currently active tab id via scoped slot.
+   */
+  default: (scope: { activeTabId: string }) => unknown
+}
+
+const props = defineProps<AppTabsProps>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+}>()
+
+defineSlots<AppTabsSlots>()
+
+function onTabChange(val: string | number | undefined) {
+  if (typeof val === 'string') {
+    emit('update:modelValue', val)
+  }
+}
+</script>
+
+<template>
+  <TabsRoot
+    :model-value="props.modelValue"
+    class="openpen-tabs"
+    @update:model-value="onTabChange"
+  >
+    <TabsList class="openpen-tabs-list">
+      <TabsTrigger
+        v-for="tab in props.tabs"
+        :key="tab.id"
+        :value="tab.id"
+        class="openpen-tabs-trigger"
+      >
+        {{ tab.label }}
+      </TabsTrigger>
+    </TabsList>
+
+    <!-- Single content outlet: plugin author renders tab content via scoped slot. -->
+    <TabsContent
+      v-for="tab in props.tabs"
+      :key="tab.id"
+      :value="tab.id"
+      class="openpen-tabs-content"
+    >
+      <slot :active-tab-id="tab.id" />
+    </TabsContent>
+  </TabsRoot>
+</template>
+
+<style scoped>
+/* ── Tab root ───────────────────────────────────────────────────────────────── */
+.openpen-tabs {
+  display: flex;
+  flex-direction: column;
+  gap: var(--openpen-space-sm);
+}
+
+/* ── Tab list (trigger bar) ─────────────────────────────────────────────────── */
+.openpen-tabs-list {
+  display: flex;
+  flex-direction: row;
+  gap: 2px;
+  padding: 3px;
+  background: var(--openpen-color-control-group);
+  border: 1px solid var(--openpen-color-border);
+  border-radius: var(--openpen-radius-md);
+}
+
+/* ── Individual trigger ─────────────────────────────────────────────────────── */
+.openpen-tabs-trigger {
+  flex: 1;
+  padding: var(--openpen-space-xs) var(--openpen-space-sm);
+  border: none;
+  border-radius: calc(var(--openpen-radius-md) - 3px);
+  background: transparent;
+  color: var(--openpen-color-text-dim);
+  font-size: 13px;
+  font-weight: 500;
+  cursor: pointer;
+  transition:
+    background var(--openpen-duration-fast) var(--openpen-easing-standard),
+    color var(--openpen-duration-fast) var(--openpen-easing-standard);
+  white-space: nowrap;
+  /* Remove default button outline; focus-visible ring below handles a11y. */
+  outline: none;
+}
+
+.openpen-tabs-trigger:hover {
+  background: var(--openpen-color-control-hover);
+  color: var(--openpen-color-text-primary);
+}
+
+.openpen-tabs-trigger[data-state='active'] {
+  background: var(--openpen-color-accent-bg);
+  color: var(--openpen-color-accent);
+  box-shadow: 0 0 0 1px var(--openpen-color-accent-glow);
+}
+
+.openpen-tabs-trigger:focus-visible {
+  box-shadow: 0 0 0 2px var(--openpen-color-accent);
+}
+
+/* ── Tab content ────────────────────────────────────────────────────────────── */
+.openpen-tabs-content {
+  /* Content area has no chrome by default; plugin authors add their own. */
+  outline: none;
+}
+
+.openpen-tabs-content:focus-visible {
+  box-shadow: 0 0 0 2px var(--openpen-color-accent);
+  border-radius: var(--openpen-radius-sm);
+}
+</style>

package/src/uikit/components/AppToggle.vue

@@ -0,0 +1,96 @@
+<script setup lang="ts">
+/**
+ * AppToggle — High-level wrapper (Layer 1).
+ *
+ * Wraps Reka UI Switch (SwitchRoot / SwitchThumb).
+ *
+ * Visual: 40×24px, off=toggle-off-bg, on=accent,
+ * 18×18 white thumb, bounce transition.
+ *
+ * Styles use --openpen-* design tokens.
+ * No Reka UI types are leaked in the public API.
+ *
+ * DOM notes:
+ * - SwitchRoot renders a <button role="switch"> with class "app-toggle"
+ * - "on" class is added when modelValue is true
+ * - aria-pressed is added explicitly because Reka UI's SwitchRoot uses
+ *   aria-checked; both attributes co-exist for maximum a11y surface.
+ */
+import {
+  SwitchRoot,
+  SwitchThumb,
+} from '../primitives'
+
+// ── Public API (MUST NOT reference reka-ui types) ─────────────────────────────
+
+withDefaults(defineProps<{
+  modelValue: boolean
+  ariaLabel?: string
+}>(), { ariaLabel: '' })
+
+const emit = defineEmits<{
+  'update:modelValue': [value: boolean]
+}>()
+
+function onCheckedChange(val: boolean) {
+  emit('update:modelValue', val)
+}
+</script>
+
+<template>
+  <SwitchRoot
+    class="app-toggle"
+    :class="{ on: modelValue }"
+    :model-value="modelValue"
+    :aria-label="ariaLabel"
+    :aria-pressed="modelValue"
+    @update:model-value="onCheckedChange"
+  >
+    <SwitchThumb class="app-toggle-thumb" />
+  </SwitchRoot>
+</template>
+
+<style scoped>
+/* Root — the toggle track */
+.app-toggle {
+  width: 40px;
+  height: 24px;
+  border-radius: 12px;
+  border: none;
+  cursor: pointer;
+  position: relative;
+  flex-shrink: 0;
+  background: var(--openpen-color-toggle-off);
+  transition: background var(--openpen-duration-base) var(--openpen-easing-standard);
+  /* Remove default button styles */
+  padding: 0;
+  appearance: none;
+  -webkit-appearance: none;
+  display: inline-flex;
+  align-items: center;
+}
+
+.app-toggle.on {
+  background: var(--openpen-color-accent);
+}
+
+/* Thumb — the white circular knob */
+.app-toggle-thumb {
+  position: absolute;
+  top: 3px;
+  left: 3px;
+  width: 18px;
+  height: 18px;
+  border-radius: 50%;
+  background: #fff;
+  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.35);
+  transition: left var(--openpen-duration-bounce) var(--openpen-easing-bounce);
+  display: block;
+  pointer-events: none;
+}
+
+.app-toggle.on .app-toggle-thumb,
+.app-toggle[data-state='checked'] .app-toggle-thumb {
+  left: 19px;
+}
+</style>

package/src/uikit/components/AppTooltip.vue

@@ -0,0 +1,118 @@
+<script setup lang="ts">
+/**
+ * AppTooltip — High-level wrapper (Layer 1).
+ *
+ * Wraps Reka UI Tooltip (TooltipProvider / TooltipRoot / TooltipTrigger /
+ * TooltipPortal / TooltipContent / TooltipArrow).
+ *
+ * Plugin authors get hover-triggered tooltips with OpenPen styling without
+ * knowing about Reka UI internals or inject keys.
+ *
+ * Styles use --openpen-* design tokens.
+ * No Reka UI types are leaked in the public API.
+ *
+ * Usage:
+ *   <AppTooltip content="Save file" side="top">
+ *     <button>Save</button>
+ *   </AppTooltip>
+ */
+import {
+  TooltipProvider,
+  TooltipRoot,
+  TooltipTrigger,
+  TooltipPortal,
+  TooltipContent,
+  TooltipArrow,
+} from '../primitives'
+
+// ── OpenPen-owned types (MUST NOT reference reka-ui types) ────────────────────
+
+/** Preferred side for tooltip content relative to the trigger. */
+export type TooltipSide = 'top' | 'bottom' | 'left' | 'right'
+
+export interface AppTooltipProps {
+  /** Tooltip text content. */
+  content: string
+  /** Preferred placement side relative to the trigger. Default 'top'. */
+  side?: TooltipSide
+  /** Delay before tooltip appears on hover, in ms. Default 200. */
+  delay?: number
+}
+
+export interface AppTooltipSlots {
+  /** Trigger element. Any element that receives hover events. */
+  default: () => unknown
+}
+
+const props = withDefaults(defineProps<AppTooltipProps>(), {
+  side: 'top',
+  delay: 200,
+})
+
+defineSlots<AppTooltipSlots>()
+</script>
+
+<template>
+  <TooltipProvider :delay-duration="props.delay">
+    <TooltipRoot>
+      <TooltipTrigger as-child>
+        <slot />
+      </TooltipTrigger>
+      <TooltipPortal>
+        <TooltipContent
+          :side="props.side"
+          :side-offset="6"
+          :avoid-collisions="true"
+          :collision-padding="8"
+          class="openpen-tooltip-content"
+        >
+          {{ props.content }}
+          <TooltipArrow class="openpen-tooltip-arrow" :width="10" :height="5" />
+        </TooltipContent>
+      </TooltipPortal>
+    </TooltipRoot>
+  </TooltipProvider>
+</template>
+
+<!-- Styles for teleported TooltipContent MUST be unscoped — Vue scoped CSS
+     does not follow Teleport targets (same rationale as AppPopover). -->
+<style>
+.openpen-tooltip-content {
+  background: var(--openpen-color-tooltip-bg);
+  border: 1px solid var(--openpen-color-border-hi);
+  border-radius: var(--openpen-radius-sm);
+  padding: 5px 9px;
+  color: var(--openpen-color-tooltip-text);
+  font-size: 12px;
+  line-height: 1.4;
+  /* Prevent text wrap for short tooltip labels */
+  white-space: nowrap;
+  box-shadow: var(--openpen-shadow-sm);
+  z-index: 200;
+  pointer-events: none;
+}
+
+.openpen-tooltip-arrow {
+  fill: var(--openpen-color-tooltip-bg);
+}
+
+/* ── Open / close animations ────────────────────────────────────────────────
+   Reka UI Presence keeps the element in the DOM until the CSS animation ends,
+   so data-state="delayed-open" / "instant-open" / "closed" all animate. */
+.openpen-tooltip-content[data-state='delayed-open'],
+.openpen-tooltip-content[data-state='instant-open'] {
+  animation: openpen-tooltip-in var(--openpen-duration-fast) var(--openpen-easing-standard);
+}
+.openpen-tooltip-content[data-state='closed'] {
+  animation: openpen-tooltip-out var(--openpen-duration-fast) ease forwards;
+}
+
+@keyframes openpen-tooltip-in {
+  from { opacity: 0; transform: scale(0.95); }
+  to   { opacity: 1; transform: scale(1); }
+}
+@keyframes openpen-tooltip-out {
+  from { opacity: 1; transform: scale(1); }
+  to   { opacity: 0; transform: scale(0.95); }
+}
+</style>