@xtalpi/agentic-lab-skills 0.0.1

package/skills/lab-orbit-component-builder/examples/xnb-component-template/src/use/useSuperCellDemo.ts

@@ -0,0 +1,257 @@
+import { computed, onScopeDispose, ref, watch } from 'vue'
+import type { ComputedRef, Ref } from 'vue'
+import type {
+  DemoSubBitableOption,
+  XnbEventBus,
+  XnbSuperCellContext,
+  XNBBitableChoreo
+} from '../types/xnb-context'
+
+/** 子表 / sheet 占位名，仅用于示例；真实工程请与宿主约定一致 */
+export const DEMO_SHEET_NAME = 'DemoSheet'
+
+export interface UseSuperCellDemoResult {
+  bookPath: ComputedRef<string>
+  cellUid: ComputedRef<string>
+  hasXNBBitable: ComputedRef<boolean>
+  choreo: Ref<XNBBitableChoreo | null>
+  subCellUid: Ref<string | null>
+  probeLog: Ref<string[]>
+  /** 调用 choreo.getSubCell()，取得子 Cell 标识 */
+  probeSubCell: () => Promise<void>
+  /**
+   * 将 options 补全为带 items / data_columns / config 的 bitable 列表后，调用 createSubBitable。
+   */
+  exampleCreateSubBitable: (optionsList?: DemoSubBitableOption[]) => Promise<void>
+  /** 调用 getSubBitable(true) 读取当前子表 */
+  exampleGetSubBitable: () => Promise<void>
+  /** 拉子表、清空 items、再 updateSubBitable（演示清空子表数据的常见写法） */
+  exampleClearSubBitable: () => Promise<void>
+  /** choreo.delay 后向整书发保存事件（示例不含用户数据回写） */
+  exampleDelayThenEmitBookSave: () => Promise<void>
+  /**
+   * 为 `${subUid}::xnb-sheet-mounted` 与 `${subUid}::cell-updated` 注册监听（常见子表生命周期钩子）。
+   * 会先 getSubCell；重复调用会先卸掉上一轮监听。
+   */
+  exampleAttachSubCellEventChannels: () => Promise<void>
+  /** 卸掉 exampleAttachSubCellEventChannels 注册的监听 */
+  exampleDetachSubCellEventChannels: () => void
+}
+
+function getXnbEventBus (): XnbEventBus | null {
+  const w = window as Window & { xnb?: { event?: XnbEventBus } }
+  return w.xnb?.event ?? null
+}
+
+/**
+ * 将配置项规范为传给 createSubBitable 的 bitable 对象列表（补齐 items / data_columns / config 空壳）。
+ */
+export function mapOptionsToBitables (optionsList: DemoSubBitableOption[]): unknown[] {
+  return optionsList.map((ops: DemoSubBitableOption) => ({
+    items: [],
+    data_columns: [],
+    config: [],
+    ...ops
+  }))
+}
+
+/**
+ * 超级表格 Cell 场景下 XNBBitable 的通用用法示例（无具体领域逻辑）：
+ * - 实例化：`new XNBBitable({ bookPath, cellUid })`
+ * - 子 Cell：getSubCell、createSubBitable
+ * - 子表读写：getSubBitable、清空 items、updateSubBitable
+ * - 整书保存：delay 后 emit `xnb-book-menu` / save
+ * - 子 Cell 事件：`xnb-sheet-mounted`、`cell-updated`
+ */
+export function useSuperCellDemo (getContext: () => XnbSuperCellContext): UseSuperCellDemoResult {
+  const bookPath = computed(() => getContext().bookPath || '')
+  const cellUid = computed(() => getContext().cellUid || '')
+  const hasXNBBitable = computed(() => Boolean(getContext().XNBBitable))
+
+  const choreo = ref<XNBBitableChoreo | null>(null)
+  const subCellUid = ref<string | null>(null)
+  const probeLog = ref<string[]>([])
+
+  const subCellEventCleanups = ref<Array<() => void>>([])
+
+  function pushLog (line: string): void {
+    probeLog.value = [...probeLog.value, line]
+  }
+
+  function exampleDetachSubCellEventChannels (): void {
+    subCellEventCleanups.value.forEach((fn: () => void) => {
+      try {
+        fn()
+      } catch {
+        /* noop */
+      }
+    })
+    subCellEventCleanups.value = []
+  }
+
+  function rebuildChoreo (): void {
+    exampleDetachSubCellEventChannels()
+    const ctx = getContext()
+    const Ctor = ctx.XNBBitable
+    if (!Ctor) {
+      choreo.value = null
+      return
+    }
+    choreo.value = new Ctor({
+      bookPath: ctx.bookPath,
+      cellUid: ctx.cellUid
+    })
+  }
+
+  watch(
+    () => [getContext().bookPath, getContext().cellUid, getContext().XNBBitable] as const,
+    () => {
+      rebuildChoreo()
+      subCellUid.value = null
+      probeLog.value = []
+    },
+    { immediate: true }
+  )
+
+  onScopeDispose(() => {
+    exampleDetachSubCellEventChannels()
+  })
+
+  async function probeSubCell (): Promise<void> {
+    probeLog.value = []
+    if (!choreo.value) {
+      pushLog('[skip] 当前上下文未注入 XNBBitable（真机由宿主提供）')
+      return
+    }
+    try {
+      const uid = await choreo.value.getSubCell()
+      subCellUid.value = uid
+      pushLog(`getSubCell() -> ${uid ?? '(null)'}`)
+    } catch (err) {
+      pushLog(`getSubCell 错误: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
+  async function exampleCreateSubBitable (optionsList?: DemoSubBitableOption[]): Promise<void> {
+    if (!choreo.value) {
+      pushLog('[createSubBitable] skip：无 choreo')
+      return
+    }
+    const list = optionsList ?? [
+      { index: 'demo-sheet-a', name: 'Sheet A', rowFocus: 0, columnFocus: 0 }
+    ]
+    try {
+      const bitables = mapOptionsToBitables(list)
+      const newUid = await choreo.value.createSubBitable(bitables, DEMO_SHEET_NAME)
+      pushLog(`createSubBitable(${DEMO_SHEET_NAME}) -> ${newUid}`)
+    } catch (err) {
+      pushLog(`createSubBitable 错误: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
+  async function exampleGetSubBitable (): Promise<void> {
+    if (!choreo.value) {
+      pushLog('[getSubBitable] skip：无 choreo')
+      return
+    }
+    try {
+      const bitable = await choreo.value.getSubBitable(true)
+      const n = bitable.items?.length ?? 0
+      pushLog(`getSubBitable(true) -> items.length=${n}`)
+    } catch (err) {
+      pushLog(`getSubBitable 错误: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
+  async function exampleClearSubBitable (): Promise<void> {
+    if (!choreo.value) {
+      pushLog('[clear 子表] skip：无 choreo')
+      return
+    }
+    try {
+      const bitable = await choreo.value.getSubBitable(true)
+      bitable.items = []
+      await choreo.value.updateSubBitable([bitable], { isMerge: false, name: DEMO_SHEET_NAME })
+      pushLog(`updateSubBitable：已清空 items（sheet=${DEMO_SHEET_NAME}）`)
+    } catch (err) {
+      pushLog(`clear 子表 错误: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
+  async function exampleDelayThenEmitBookSave (): Promise<void> {
+    if (!choreo.value) {
+      pushLog('[delay + book save] skip：无 choreo')
+      return
+    }
+    try {
+      await choreo.value.delay(20)
+      const bus = getXnbEventBus()
+      if (bus?.emit) {
+        bus.emit('xnb-book-menu', 'save', { isNotify: true })
+        pushLog('choreo.delay(20) 后已 emit xnb-book-menu / save')
+      } else {
+        pushLog('choreo.delay(20) 完成；未检测到 window.xnb.event.emit（dev 可忽略）')
+      }
+    } catch (err) {
+      pushLog(`delay + emit 错误: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
+  async function exampleAttachSubCellEventChannels (): Promise<void> {
+    exampleDetachSubCellEventChannels()
+    if (!choreo.value) {
+      pushLog('[子 Cell 事件] skip：无 choreo')
+      return
+    }
+    let uid: string | null = subCellUid.value
+    if (!uid) {
+      try {
+        uid = await choreo.value.getSubCell()
+        subCellUid.value = uid
+      } catch (err) {
+        pushLog(`[子 Cell 事件] getSubCell 失败: ${err instanceof Error ? err.message : String(err)}`)
+        return
+      }
+    }
+    if (!uid) {
+      pushLog('[子 Cell 事件] skip：subCellUid 为空')
+      return
+    }
+    const bus = getXnbEventBus()
+    if (!bus?.on || !bus?.off) {
+      pushLog('[子 Cell 事件] 未检测到 window.xnb.event.on/off（dev 可忽略）')
+      return
+    }
+    const mountedHandler = (): void => {
+      pushLog(`[event] ${uid}::xnb-sheet-mounted`)
+    }
+    const updatedHandler = (...args: unknown[]): void => {
+      pushLog(`[event] ${uid}::cell-updated payload=${JSON.stringify(args).slice(0, 120)}`)
+    }
+    const chMounted = `${uid}::xnb-sheet-mounted`
+    const chUpdated = `${uid}::cell-updated`
+    bus.on(chMounted, mountedHandler)
+    bus.on(chUpdated, updatedHandler)
+    subCellEventCleanups.value = [
+      (): void => { bus.off(chMounted, mountedHandler) },
+      (): void => { bus.off(chUpdated, updatedHandler) }
+    ]
+    pushLog(`已注册 ${chMounted} / ${chUpdated}`)
+  }
+
+  return {
+    bookPath,
+    cellUid,
+    hasXNBBitable,
+    choreo,
+    subCellUid,
+    probeLog,
+    probeSubCell,
+    exampleCreateSubBitable,
+    exampleGetSubBitable,
+    exampleClearSubBitable,
+    exampleDelayThenEmitBookSave,
+    exampleAttachSubCellEventChannels,
+    exampleDetachSubCellEventChannels
+  }
+}