DOCS.js

// --- Main Export ---
// Usage: const docs = DOCS(__filename)(opts.sid)
//        docs.wrap(handler, docContent)
// Admin: Only first caller (root module) gets admin API

module.exports = function DOCS (filename) {
  return function (sid) {
    return create_context(filename, sid)
  }
}

const scope = typeof window !== 'undefined' ? window : global

if (!scope.__DOCS_GLOBAL_STATE__) {
  scope.__DOCS_GLOBAL_STATE__ = {
    docs_mode_active: false,
    docs_mode_listeners: [],
    doc_display_callback: null,
    action_registry: new Map()
  }
}

const state = scope.__DOCS_GLOBAL_STATE__

// --- Static Methods (called as DOCS.method()) ---
// Exported via DOCS admin API (only available to first caller)
function set_docs_mode (active) {
  state.docs_mode_active = active
  state.docs_mode_listeners.forEach(listener => listener(active))
}

function get_docs_mode () {
  return state.docs_mode_active
}

function on_docs_mode_change (listener) {
  state.docs_mode_listeners.push(listener)
  return () => {
    state.docs_mode_listeners = state.docs_mode_listeners.filter(l => l !== listener)
  }
}

function set_doc_display_handler (callback) {
  state.doc_display_callback = callback
}

function get_actions (sid) {
  const actions = state.action_registry.get(sid) || []
  if (actions.length === 0) throw new Error('DOCS: No actions registered for SID ' + sid)
  return actions
}

function list_registered () {
  return Array.from(state.action_registry.keys())
}

// --- Internal Helpers ---

function verify_actions (actions) {
  if (!Array.isArray(actions)) throw new Error('DOCS: Actions must be array')
  actions.forEach((action, i) => {
    if (!action.name || typeof action.name !== 'string') throw new Error(`DOCS: Action[${i}] Invalid 'name'`)
    if (!action.icon || typeof action.icon !== 'string') throw new Error(`DOCS: Action[${i}] Invalid 'icon'`)
    if (!action.status || typeof action.status !== 'object') throw new Error(`DOCS: Action[${i}] Invalid 'status'`)
    if (!action.steps || !Array.isArray(action.steps)) throw new Error(`DOCS: Action[${i}] Invalid 'steps'`)
  })
}

async function display_doc (content, sid) {
  let resolved_content = content
  if (typeof content === 'function') {
    resolved_content = await content()
  } else if (content && typeof content.then === 'function') {
    resolved_content = await content
  }

  if (state.doc_display_callback) {
    state.doc_display_callback({ content: resolved_content || 'No documentation available', sid })
  }
}

function create_sys_api (meta) {
  return {
    is_docs_mode: () => state.docs_mode_active,
    get_doc: () => meta.doc || 'No documentation available',
    get_meta: () => ({ ...meta }),
    show_doc: () => display_doc(meta.doc || 'No documentation available', meta.sid)
  }
}

// --- Instance Methods (called as docs.method()) ---

function wrap (handler, meta = {}, make_sys = create_sys_api) {
  const sys = make_sys(meta)

  return async function wrapped_handler (event) {
    if (sys.is_docs_mode()) {
      if (event && event.preventDefault) {
        event.preventDefault()
        event.stopPropagation()
      }
      sys.show_doc()
      return
    }
    return handler.call(this, event, sys)
  }
}

function wrap_isolated (handler_string, meta = {}) {
  try {
    const params = 'meta, make_sys'
    const source = `(${wrap.toString()})(${handler_string}, ${params})`
    const isolated_fn = new Function(params, source)(meta, create_sys_api)
    return isolated_fn
  } catch (err) {
    console.error('handler function is not allowed to access closure scope', err)
    return wrap(() => {}, meta)
  }
}

function hook (dom, meta = {}) {
  if (!dom) return dom

  const proto = Object.getPrototypeOf(Object.getPrototypeOf(dom))
  if (!proto) return dom

  Object.keys(proto).forEach(key => {
    if (key.startsWith('on') && typeof dom[key] === 'function') {
      const original = dom[key]
      dom[key] = wrap(original, { ...meta, event_type: key })
    }
  })

  return dom
}

// --- Context Factory (creates instance with component scope) ---

function register_actions (sid, actions) {
  verify_actions(actions)
  state.action_registry.set(sid, actions)
}

let admin = true
function create_context (filename, sid) {
  const api = {
    wrap: (handler, doc) => wrap(handler, { doc, sid, component: filename }),
    wrap_isolated: (handler_string, doc) => wrap_isolated(handler_string, { doc, sid, component: filename }),
    hook: (dom, doc) => hook(dom, { doc, sid, component: filename }),
    get_docs_mode,
    on_docs_mode_change,
    register_actions: (actions) => register_actions(sid, actions)
  }
  return admin ? (admin = false, Object.assign({ admin: { set_docs_mode, set_doc_display_handler, get_actions, list_registered } }, api)) : api
}