@morscherlab/mint-sdk 1.2.0-beta.1 → 1.2.0-beta.11

package/src/composables/useListReorder.ts

@@ -0,0 +1,242 @@
+import { nextTick, ref, type Ref } from 'vue'
+
+/** Inline style for a visually hidden `aria-live` region (no global utility class in the SDK). */
+export const REORDER_ANNOUNCER_STYLE = Object.freeze({
+  position: 'absolute',
+  width: '1px',
+  height: '1px',
+  padding: '0',
+  margin: '-1px',
+  overflow: 'hidden',
+  clip: 'rect(0, 0, 0, 0)',
+  whiteSpace: 'nowrap',
+  border: '0',
+})
+
+export interface UseReorderAnnouncerReturn {
+  /** Bind to a polite live region's text content. */
+  announcement: Ref<string>
+  /** Publishes a message to the live region. */
+  announce: (message: string) => void
+  /** Bind to the live region's `style` so it stays visually hidden. */
+  announcerStyle: typeof REORDER_ANNOUNCER_STYLE
+}
+
+/**
+ * Screen-reader announcements for drag/keyboard move interactions. Bind
+ * `announcement` to a `role="status" aria-live="polite"` element styled with
+ * `announcerStyle`.
+ */
+export function useReorderAnnouncer(): UseReorderAnnouncerReturn {
+  const announcement = ref('')
+
+  function announce(message: string) {
+    // Re-announce identical consecutive messages by clearing first.
+    if (announcement.value === message) announcement.value = ''
+    void nextTick(() => {
+      announcement.value = message
+    })
+  }
+
+  return { announcement, announce, announcerStyle: REORDER_ANNOUNCER_STYLE }
+}
+
+export interface ListReorderMove<T> {
+  /** Index the item moved from, within `items()`. */
+  fromIndex: number
+  /** Index the item moved to, within `items()`. */
+  toIndex: number
+  /** The reordered array (a copy — `items()` is never mutated). */
+  items: T[]
+  /** Whether the move came from the keyboard or a pointer drag. */
+  source: 'keyboard' | 'drag'
+}
+
+export interface UseListReorderOptions<T> {
+  /** The list being reordered, in its canonical (not merely rendered) order. */
+  items: () => T[]
+  /** Stable id for an item; falls back to the render index when ids repeat. */
+  getId: (item: T, index: number) => string
+  /** Applies the move. The composable never mutates the source array. */
+  onReorder: (move: ListReorderMove<T>) => void
+  /** Human-readable name used in announcements. Defaults to the item's id. */
+  getLabel?: (item: T, index: number) => string
+  /** Blocks every reorder while it returns `true` (readonly / non-sortable lists). */
+  disabled?: () => boolean
+  /** Resolves the focusable element for an id so keyboard moves keep focus on the item. */
+  getElement?: (id: string) => HTMLElement | null | undefined
+  /** Noun used in announcements, e.g. `'Reagent'`. Default `'Item'`. */
+  itemNoun?: string
+}
+
+export interface UseListReorderReturn<T> {
+  /** Id of the item currently being dragged, or `null`. */
+  draggingId: Ref<string | null>
+  /** Id of the item the pointer is hovering as a drop target, or `null`. */
+  dragOverId: Ref<string | null>
+  isDragging: (id: string) => boolean
+  isDragOver: (id: string) => boolean
+  announcement: Ref<string>
+  announcerStyle: typeof REORDER_ANNOUNCER_STYLE
+  announce: (message: string) => void
+  /** Bind to the draggable element's `@dragstart`. */
+  onDragStart: (event: DragEvent, item: T, index: number) => void
+  /** Bind to `@dragover` — calls `preventDefault()` so the drop is accepted. */
+  onDragOver: (event: DragEvent, item: T, index: number) => void
+  /** Bind to `@dragleave`. */
+  onDragLeave: () => void
+  /** Bind to `@drop`. */
+  onDrop: (event: DragEvent, item: T, index: number) => void
+  /** Bind to `@dragend`. */
+  onDragEnd: () => void
+  /**
+   * Bind to the item's (or its drag handle's) `@keydown`: Alt+ArrowUp / Alt+ArrowLeft
+   * moves the item one position earlier, Alt+ArrowDown / Alt+ArrowRight one later.
+   */
+  onKeydown: (event: KeyboardEvent, item: T, index: number) => void
+  /** Moves an item between two indices of `items()` programmatically. */
+  move: (fromIndex: number, toIndex: number, source?: 'keyboard' | 'drag') => void
+}
+
+/** Pure helper: a copy of `items` with the entry at `from` moved to `to`. */
+export function reorderList<T>(items: T[], from: number, to: number): T[] {
+  const next = [...items]
+  const [moved] = next.splice(from, 1)
+  next.splice(to, 0, moved)
+  return next
+}
+
+/**
+ * Keyboard-accessible list reordering shared by the SDK's drag-to-reorder lists.
+ * It owns the HTML5 drag state, the drop-index maths, and an Alt+Arrow keyboard
+ * alternative that announces every move through a polite live region — so a
+ * reorder never depends on a pointer.
+ */
+export function useListReorder<T>(options: UseListReorderOptions<T>): UseListReorderReturn<T> {
+  const draggingId = ref<string | null>(null)
+  const dragOverId = ref<string | null>(null)
+  const { announcement, announce, announcerStyle } = useReorderAnnouncer()
+  const noun = options.itemNoun ?? 'Item'
+
+  function isDisabled(): boolean {
+    return options.disabled?.() === true
+  }
+
+  function idFor(item: T, index: number): string {
+    return options.getId(item, index)
+  }
+
+  /** Index within `items()`, resolved by id so filtered/sorted renders still map back. */
+  function indexOf(item: T, renderIndex: number): number {
+    const id = idFor(item, renderIndex)
+    const found = options.items().findIndex((candidate, index) => idFor(candidate, index) === id)
+    return found === -1 ? renderIndex : found
+  }
+
+  function labelFor(index: number): string {
+    const item = options.items()[index]
+    if (item === undefined) return noun
+    return options.getLabel?.(item, index) ?? idFor(item, index)
+  }
+
+  function clearDragState() {
+    draggingId.value = null
+    dragOverId.value = null
+  }
+
+  function move(fromIndex: number, toIndex: number, source: 'keyboard' | 'drag' = 'keyboard') {
+    if (isDisabled()) return
+    const items = options.items()
+    if (
+      fromIndex === toIndex ||
+      fromIndex < 0 ||
+      toIndex < 0 ||
+      fromIndex >= items.length ||
+      toIndex >= items.length
+    ) return
+
+    const movedId = idFor(items[fromIndex], fromIndex)
+    const label = labelFor(fromIndex)
+    options.onReorder({
+      fromIndex,
+      toIndex,
+      items: reorderList(items, fromIndex, toIndex),
+      source,
+    })
+    announce(`${label} moved to position ${toIndex + 1} of ${items.length}.`)
+    void nextTick(() => options.getElement?.(movedId)?.focus())
+  }
+
+  function onDragStart(event: DragEvent, item: T, index: number) {
+    if (isDisabled()) return
+    const id = idFor(item, index)
+    draggingId.value = id
+    if (event.dataTransfer) {
+      event.dataTransfer.effectAllowed = 'move'
+      event.dataTransfer.setData('text/plain', id)
+    }
+  }
+
+  function onDragOver(event: DragEvent, item: T, index: number) {
+    if (isDisabled() || draggingId.value === null) return
+    event.preventDefault()
+    if (event.dataTransfer) event.dataTransfer.dropEffect = 'move'
+    const id = idFor(item, index)
+    dragOverId.value = id === draggingId.value ? null : id
+  }
+
+  function onDragLeave() {
+    dragOverId.value = null
+  }
+
+  function onDrop(event: DragEvent, item: T, index: number) {
+    if (isDisabled() || draggingId.value === null) {
+      clearDragState()
+      return
+    }
+    event.preventDefault()
+
+    const items = options.items()
+    const fromIndex = items.findIndex((candidate, i) => idFor(candidate, i) === draggingId.value)
+    const toIndex = indexOf(item, index)
+    clearDragState()
+    if (fromIndex === -1) return
+    move(fromIndex, toIndex, 'drag')
+  }
+
+  function onDragEnd() {
+    clearDragState()
+  }
+
+  function onKeydown(event: KeyboardEvent, item: T, index: number) {
+    if (isDisabled() || !event.altKey) return
+    const direction =
+      event.key === 'ArrowUp' || event.key === 'ArrowLeft'
+        ? -1
+        : event.key === 'ArrowDown' || event.key === 'ArrowRight'
+          ? 1
+          : 0
+    if (direction === 0) return
+
+    event.preventDefault()
+    const fromIndex = indexOf(item, index)
+    move(fromIndex, fromIndex + direction, 'keyboard')
+  }
+
+  return {
+    draggingId,
+    dragOverId,
+    isDragging: (id: string) => draggingId.value === id,
+    isDragOver: (id: string) => dragOverId.value === id,
+    announcement,
+    announcerStyle,
+    announce,
+    onDragStart,
+    onDragOver,
+    onDragLeave,
+    onDrop,
+    onDragEnd,
+    onKeydown,
+    move,
+  }
+}

package/src/composables/useMenuKeyboard.ts

@@ -0,0 +1,90 @@
+import { nextTick } from 'vue'
+
+export interface UseMenuKeyboardOptions {
+  /** Returns the currently navigable items inside the open panel, in DOM order. */
+  items: () => HTMLElement[]
+  /** True while the panel is open. */
+  isOpen: () => boolean
+  /** Opens the panel. */
+  open: () => void
+  /** Closes the panel. When `returnFocus` is true, focus should return to the trigger. */
+  close: (returnFocus?: boolean) => void
+}
+
+export interface UseMenuKeyboardReturn {
+  /**
+   * Bind to the trigger's `@keydown`. ArrowDown/Enter/Space open the panel (when
+   * closed) and focus its first item; ArrowUp opens it focused on the last item.
+   */
+  handleTriggerKeydown: (event: KeyboardEvent) => void
+  /**
+   * Bind to the open panel's `@keydown`. ArrowUp/ArrowDown cycle focus with
+   * wraparound, Home/End jump to the first/last item, Escape closes and returns
+   * focus to the trigger, and Tab closes without moving focus.
+   */
+  handlePanelKeydown: (event: KeyboardEvent) => void
+}
+
+/**
+ * Shared keyboard contract for menu- and listbox-style disclosure panels (the
+ * WAI-ARIA menu button pattern). Used by ActionMenu, AppAvatarMenu and DropdownButton,
+ * each pairing it with `useDropdownState` for the disclosure state itself.
+ */
+export function useMenuKeyboard(options: UseMenuKeyboardOptions): UseMenuKeyboardReturn {
+  function focusItem(position: 'first' | 'last') {
+    void nextTick(() => {
+      const items = options.items()
+      const target = position === 'first' ? items[0] : items[items.length - 1]
+      target?.focus()
+    })
+  }
+
+  function handleTriggerKeydown(event: KeyboardEvent) {
+    if (options.isOpen()) return
+
+    if (event.key === 'ArrowDown' || event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault()
+      options.open()
+      focusItem('first')
+      return
+    }
+    if (event.key === 'ArrowUp') {
+      event.preventDefault()
+      options.open()
+      focusItem('last')
+    }
+  }
+
+  function handlePanelKeydown(event: KeyboardEvent) {
+    const items = options.items()
+    const currentIndex = items.indexOf(document.activeElement as HTMLElement)
+
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      options.close(true)
+      return
+    }
+    if (event.key === 'Tab') {
+      options.close()
+      return
+    }
+    if (event.key === 'Home') {
+      event.preventDefault()
+      items[0]?.focus()
+      return
+    }
+    if (event.key === 'End') {
+      event.preventDefault()
+      items[items.length - 1]?.focus()
+      return
+    }
+    if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return
+
+    event.preventDefault()
+    const direction = event.key === 'ArrowDown' ? 1 : -1
+    const nextIndex = (Math.max(currentIndex, 0) + direction + items.length) % items.length
+    items[nextIndex]?.focus()
+  }
+
+  return { handleTriggerKeydown, handlePanelKeydown }
+}

package/src/composables/useOptimisticMutation.ts

@@ -1,4 +1,5 @@
 import { computed, ref, shallowRef, type ComputedRef, type Ref, type ShallowRef } from 'vue'
+import { readErrorMessage } from '../utils/errors'
 
 export interface OptimisticMutationContext<TVariables, TSnapshot> {
   variables: TVariables
@@ -32,7 +33,11 @@ export interface UseOptimisticMutationReturn<TVariables, TData, TSnapshot = unkn
   reset: () => void
 }
 
-/** Run async mutations with optional optimistic local updates and rollback. */
+/**
+ * Run async mutations with optional optimistic local updates and rollback.
+ *
+ * @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `useRequestSyncState()` instead.
+ */
 export function useOptimisticMutation<TVariables, TData, TSnapshot = unknown>(
   options: UseOptimisticMutationOptions<TVariables, TData, TSnapshot>,
 ): UseOptimisticMutationReturn<TVariables, TData, TSnapshot> {
@@ -90,18 +95,3 @@ export function useOptimisticMutation<TVariables, TData, TSnapshot = unknown>(
     reset,
   }
 }
-
-function readErrorMessage(value: unknown): string {
-  if (value instanceof Error && value.message) return value.message
-  if (typeof value === 'string' && value.trim()) return value
-  if (
-    typeof value === 'object'
-    && value !== null
-    && 'message' in value
-    && typeof (value as { message?: unknown }).message === 'string'
-    && (value as { message: string }).message.trim()
-  ) {
-    return (value as { message: string }).message
-  }
-  return 'Request failed.'
-}

package/src/composables/usePluginClient.ts

@@ -15,6 +15,7 @@ import {
 import { usePlatformContext } from './usePlatformContext'
 import { useRequestSyncState } from './useRequestSyncState'
 import { useAuthStore } from '../stores/auth'
+import { PLUGIN_SECRET_FORMAT_KEY } from '../utils/pluginSecrets'
 import {
   currentExperimentFromContext,
   getInjectedPlatformContext,
@@ -538,8 +539,33 @@ function normalizePluginSettingsOptions(options: UsePluginSettingsOptions | stri
   return typeof options === 'string' ? { pluginName: options } : options
 }
 
+/** @deprecated Use `useGeneratedPluginClient()` for generated clients. */
+export function usePluginClient<TClient>(client: TClient): TClient {
+  return client
+}
+
 const PLATFORM_OWNED_SETTINGS_KEY = 'allowed_experiment_types'
 
+/**
+ * Secret settings travel as `{ "$secret": "<id>" }` references, so an untouched
+ * secret round-trips without ever exposing its value. Declaring the format on
+ * every write keeps a `null` unambiguous: it clears the stored secret instead of
+ * meaning "unchanged", which is what the deprecated placeholder form meant.
+ */
+function withSecretFormat(
+  payload: Record<string, unknown>,
+  secretFormat: string | null,
+): Record<string, unknown> {
+  if (!secretFormat) return payload
+  return { ...payload, [PLUGIN_SECRET_FORMAT_KEY]: secretFormat }
+}
+
+function responseSecretFormat(response: unknown): string | null {
+  if (!response || typeof response !== 'object') return null
+  const format = (response as Record<string, unknown>)[PLUGIN_SECRET_FORMAT_KEY]
+  return typeof format === 'string' && format ? format : null
+}
+
 function cloneRecord(value: Record<string, unknown>): Record<string, unknown> {
   return JSON.parse(JSON.stringify(value)) as Record<string, unknown>
 }
@@ -613,6 +639,7 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
   const values = ref({}) as Ref<PluginSettingsValues<TSettings>>
   const savedValues = shallowRef<Record<string, unknown>>({})
   const revision = ref<string | null>(null)
+  const secretFormat = ref<string | null>(null)
   const request = useRequestSyncState('Plugin settings request failed.')
   const isLoading = ref(false)
   const isSaving = ref(false)
@@ -645,11 +672,16 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
     values.value = cloneRecord(nextValues) as PluginSettingsValues<TSettings>
   }
 
-  function applyLoaded(nextValues: Record<string, unknown>, nextRevision: string | null): void {
+  function applyLoaded(
+    nextValues: Record<string, unknown>,
+    nextRevision: string | null,
+    nextSecretFormat: string | null = secretFormat.value,
+  ): void {
     const cloned = cloneRecord(nextValues)
     values.value = cloned as PluginSettingsValues<TSettings>
     savedValues.value = cloneRecord(cloned)
     revision.value = nextRevision
+    secretFormat.value = nextSecretFormat
   }
 
   async function load(): Promise<void> {
@@ -669,6 +701,7 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
       applyLoaded(
         responseSettingsPayload(response),
         responseSettingsRevision(response),
+        responseSecretFormat(response),
       )
     } catch {
       // Error state is handled by request.run().
@@ -702,7 +735,12 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
               revision?: string
             }>(
               `/plugins/${encodeURIComponent(resolvedPluginName.value)}/config`,
-              { config: topLevelSettingsPatch(payload, typedKeys) },
+              {
+                config: withSecretFormat(
+                  topLevelSettingsPatch(payload, typedKeys),
+                  secretFormat.value,
+                ),
+              },
             ),
             { success: 'save', errorMessage: 'Failed to save plugin settings' },
           )
@@ -725,7 +763,11 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
         }
 
         if (!response) return true
-        applyLoaded(responseSettingsPayload(response), nextRevision)
+        applyLoaded(
+          responseSettingsPayload(response),
+          nextRevision,
+          responseSecretFormat(response) ?? secretFormat.value,
+        )
         return true
       } else {
         const ifMatch = revision.value
@@ -736,13 +778,14 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
             settings: Record<string, unknown>
             mode?: string
             revision?: string
-          }>('/settings', payload, ifMatch),
+          }>('/settings', withSecretFormat(payload, secretFormat.value), ifMatch),
           { success: 'save', errorMessage: 'Failed to save plugin settings' },
         )
       }
       applyLoaded(
         responseSettingsPayload(response),
         responseSettingsRevision(response) ?? revision.value,
+        responseSecretFormat(response) ?? secretFormat.value,
       )
       return true
     } catch {