feat(api): enhance getFlagsFromActions and setActions with options for default action selection and close behavior; add overlay helper functions

Author: johnlindquist

src/api/kit.ts

@@ -821,7 +821,10 @@ function sortArrayByIndex(arr) {
   return sortedArr
 }
 
-export let getFlagsFromActions = (actions: PromptConfig['actions']) => {
+export let getFlagsFromActions = (
+  actions: PromptConfig['actions'],
+  options: { defaultActionsId?: string; defaultClose?: boolean } = {},
+) => {
   let flags: FlagsObject = {}
   let indices = new Set()
   for (let a of actions as Action[]) {
@@ -831,7 +834,15 @@ export let getFlagsFromActions = (actions: PromptConfig['actions']) => {
   }
   let groups = new Set()
   if (Array.isArray(actions)) {
-    const sortedActions = sortArrayByIndex(actions)
+    let sortedActions = sortArrayByIndex(actions)
+    // Optional: preselect a default by moving it to the front without changing explicit indices
+    if (options?.defaultActionsId) {
+      const i = sortedActions.findIndex((a: any) => (a?.flag || a?.name) === options.defaultActionsId)
+      if (i > 0) {
+        const [def] = sortedActions.splice(i, 1)
+        sortedActions.unshift(def)
+      }
+    }
     for (let i = 0; i < sortedActions.length; i++) {
       let action = sortedActions[i]
       if (typeof action === 'string') {
@@ -847,7 +858,8 @@ export let getFlagsFromActions = (actions: PromptConfig['actions']) => {
       let flagAction = {
         flag: action.flag || action.name,
         index: i,
-        close: true,
+        // Default close behavior is true (legacy). Allow override via options or per-action.
+        close: typeof options?.defaultClose === 'boolean' ? options.defaultClose : true,
         ...action,
         hasAction: !!action?.onAction,
         bar: action?.visible ? 'right' : ''
@@ -861,8 +873,14 @@ export let getFlagsFromActions = (actions: PromptConfig['actions']) => {
   return flags
 }
 
-global.setActions = async (actions: Action[], options = {}) => {
-  let flags = getFlagsFromActions(actions)
+global.setActions = async (
+  actions: Action[],
+  options: { name?: string; placeholder?: string; active?: string; defaultActionsId?: string; defaultClose?: boolean } = {},
+) => {
+  const flags = getFlagsFromActions(actions, {
+    defaultActionsId: options?.defaultActionsId,
+    defaultClose: options?.defaultClose,
+  })
   await setFlags(flags, options)
 }
 
@@ -878,6 +896,20 @@ global.setFlagValue = (value: any) => {
   return global.sendWait(Channel.SET_FLAG_VALUE, value)
 }
 
+// Overlay-aligned helpers (non-breaking wrappers)
+global.openActionsOverlay = async (opts: { source?: 'choice' | 'input' | 'ui' | 'editor'; flag?: string } = {}) => {
+  // OPEN_ACTIONS triggers overlay visibility in renderer (via main mapping to SET_FLAG_VALUE 'action')
+  await global.openActions()
+  if (typeof opts.flag === 'string' && opts.flag.length > 0) {
+    // Set payload after opening for better parity with renderer’s split of visibility vs payload
+    await global.setFlagValue(opts.flag)
+  }
+}
+
+global.closeActionsOverlay = async () => {
+  await global.closeActions()
+}
+
 global.hide = async (hideOptions = {}) => {
   await global.sendWait(Channel.HIDE_APP, hideOptions)
   if (process.env.KIT_HIDE_DELAY) {

src/editor/types/kit-editor.d.ts

@@ -366,6 +366,15 @@ declare module "@johnlindquist/kit" {
     name?: string
     placeholder?: string
     active?: string
+    /**
+     * Optional: preselect an action in the overlay by id (flag or name).
+     */
+    defaultActionsId?: string
+    /**
+     * Optional: default close behavior for actions (legacy default: true).
+     * Set false to keep overlay open unless an action explicitly sets close: true.
+    */
+    defaultClose?: boolean
   }
 
   export type Action = {
@@ -10912,6 +10921,13 @@ declare module "@johnlindquist/kit" {
     var setActions: ActionsFn
     var openActions: () => Promise<void>
     var closeActions: () => Promise<void>
+    /**
+     * Open the actions overlay with optional payload.
+     * Visibility is separate from payload; when `flag` is provided it will be set after opening.
+     */
+    var openActionsOverlay: (opts?: { source?: 'choice' | 'input' | 'ui' | 'editor'; flag?: string }) => Promise<void>
+    /** Close the actions overlay. */
+    var closeActionsOverlay: () => Promise<void>
     var setFlagValue: (value: any) => Promise<void>
     var prepFlags: PrepFlags
 

src/types/core.d.ts

@@ -353,6 +353,15 @@ export type ActionsConfig = {
   name?: string
   placeholder?: string
   active?: string
+  /**
+ * Optional: preselect a
+ */
+  defaultActionsId?: strin
+  /**
+   * Optional: default clo
+   * Set false to keep ove
+  */
+  defaultClose?: boolean
 }
 
 export type Action = {

test-sdk/overlay-helpers.test.js

@@ -0,0 +1,64 @@
+import test from 'ava'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+// Helper to import from built .kit output
+const importKit = async (...parts) => {
+  const base = process.env.KIT
+  if (!base) throw new Error('KIT env var not set for tests')
+  const fileUrl = pathToFileURL(path.resolve(base, ...parts)).href
+  return await import(fileUrl)
+}
+
+test.serial('openActionsOverlay calls openActions then setFlagValue when flag provided', async (t) => {
+  // Ensure kit globals are available
+  await importKit('api', 'kit.js')
+
+  const calls = []
+  global.openActions = async () => calls.push({ fn: 'openActions' })
+  global.setFlagValue = async (v) => calls.push({ fn: 'setFlagValue', v })
+
+  await global.openActionsOverlay({ source: 'editor', flag: 'abc' })
+
+  t.deepEqual(calls, [
+    { fn: 'openActions' },
+    { fn: 'setFlagValue', v: 'abc' },
+  ])
+})
+
+test.serial('closeActionsOverlay calls closeActions', async (t) => {
+  await importKit('api', 'kit.js')
+
+  let closed = false
+  global.closeActions = async () => { closed = true }
+
+  await global.closeActionsOverlay()
+  t.true(closed)
+})
+
+test.serial('setActions honors defaultActionsId and defaultClose=false', async (t) => {
+  await importKit('api', 'kit.js')
+
+  let sent = null
+  global.sendWait = async (channel, payload) => {
+    if (channel === (await importKit('core', 'enum.js')).Channel.SET_FLAGS) {
+      sent = payload
+    }
+  }
+
+  const actions = [
+    { name: 'Second', flag: 'second', onAction: () => {} },
+    { name: 'First', flag: 'first', onAction: () => {} },
+  ]
+
+  await global.setActions(actions, { defaultActionsId: 'first', defaultClose: false })
+
+  t.truthy(sent)
+  const { flags } = sent
+  // default action should be index 0
+  t.is(flags.first.index, 0)
+  // defaultClose=false should apply unless overridden
+  t.is(flags.first.close, false)
+  t.is(flags.second.close, false)
+})
+