# Box SDK

## Overview

The Box SDK provides plugins with the ability to control CoreBox window behavior, including show/hide, resizing, and input field control.

## Introduction

**Quick Start**

:::TuffCodeBlock{lang="typescript"}
---
code: |
  import { useBox } from '@talex-touch/utils/plugin/sdk'

  const box = useBox()

  // Hide CoreBox
  box.hide()

  // Expand CoreBox to show 10 results
  await box.expand({ length: 10 })

  // Get current input
  const input = await box.getInput()
---
:::

---

## API Reference

**useBox()**

Get Box SDK instance.

:::TuffCodeBlock{lang="typescript"}
---
code: |
  import { useBox } from '@talex-touch/utils/plugin/sdk'

  const box = useBox()
---
:::

> **Note**: Must be called within plugin renderer context.

---

## Window Control

**`hide()`**

Hide the CoreBox window.

:::TuffCodeBlock{lang="typescript"}
---
code: |
  box.hide()
---
:::

**`show()`**

Show the CoreBox window.

:::TuffCodeBlock{lang="typescript"}
---
code: |
  box.show()
---
:::

**`expand(options?)`**

Expand the CoreBox window to show more results.

:::TuffCodeBlock{lang="typescript"}
---
code: |
  // Expand to show 10 items
  await box.expand({ length: 10 })

  // Force maximum expansion
  await box.expand({ forceMax: true })

  // Default expansion
  await box.expand()
---
:::

| Parameter | Type | Description |
|-----------|------|-------------|
| `length` | `number` | Number of items to show |
| `forceMax` | `boolean` | Force maximum expansion |

**`shrink()`**

Shrink the CoreBox window to compact mode.

:::TuffCodeBlock{lang="typescript"}
---
code: |
  await box.shrink()
---
:::

---

## Input Field Control

**`hideInput()`**

Hide the search input field.

:::TuffCodeBlock{lang="typescript"}
---
code: |
  await box.hideInput()
---
:::

**`showInput()`**

Show the search input field.

:::TuffCodeBlock{lang="typescript"}
---
code: |
  await box.showInput()
---
:::

**`getInput()`**

Get current input field value.

:::TuffCodeBlock{lang="typescript"}
---
code: |
  const input = await box.getInput()
  console.log('Current input:', input)
---
:::

**`setInput(value)`**

Set input field value.

:::TuffCodeBlock{lang="typescript"}
---
code: |
  await box.setInput('hello world')
---
:::

**`clearInput()`**

Clear the input field.

:::TuffCodeBlock{lang="typescript"}
---
code: |
  await box.clearInput()
---
:::

---

## Monitoring Features

**`allowInput()`**

Enable input monitoring, allowing plugin to receive input change events.

:::TuffCodeBlock{lang="typescript"}
---
code: |
  import { onCoreBoxInputChange, useBox } from '@talex-touch/utils/plugin/sdk'

  const box = useBox()

  // Enable input monitoring
  await box.allowInput()

  // Listen to input changes
  onCoreBoxInputChange(({ data }) => {
    console.log('Input changed:', data.query.text)
  })
---
:::

**`allowClipboard(types)`**

Enable clipboard monitoring, allowing plugin to receive clipboard change events.

:::TuffCodeBlock{lang="typescript"}
---
code: |
  import { useBox, ClipboardType, ClipboardTypePresets } from '@talex-touch/utils/plugin/sdk'

  const box = useBox()

  // Monitor text and images
  await box.allowClipboard(ClipboardType.TEXT | ClipboardType.IMAGE)

  // Or use presets
  await box.allowClipboard(ClipboardTypePresets.ALL)
---
:::

**ClipboardType Enum**

| Value | Binary | Description |
|-------|--------|-------------|
| `TEXT` | `0b0001` | Description for TEXT. |
| `IMAGE` | `0b0010` | Image |
| `FILE` | `0b0100` | File |

**Preset Combinations**

:::TuffCodeBlock{lang="typescript"}
---
code: |
  import { ClipboardTypePresets } from '@talex-touch/utils/plugin/sdk'

  // Text only
  ClipboardTypePresets.TEXT_ONLY

  // Text and images
  ClipboardTypePresets.TEXT_AND_IMAGE

  // All types
  ClipboardTypePresets.ALL
---
:::

---

## Complete Example

**Translation plugin**

:::TuffCodeBlock{lang="typescript"}
---
code: |
  import { useBox, useClipboard, ClipboardType } from '@talex-touch/utils/plugin/sdk'

  const box = useBox()
  const clipboard = useClipboard()

  // Initialise
  async function init() {
    // Enable clipboard monitoring
    await box.allowClipboard(ClipboardType.TEXT)

    // Watch for clipboard changes
    clipboard.history.onDidChange(async (item) => {
      if (item.type === 'text') {
        // Translate newly copied text automatically
        const translated = await translate(item.content)
        console.log('Translation:', translated)
      }
    })
  }

  // Emit the translation
  async function outputTranslation(text: string) {
    // Hide CoreBox and paste the result
    await clipboard.copyAndPaste({ text })
  }
---
:::

**Search plugin**

:::TuffCodeBlock{lang="typescript"}
---
code: |
  import { onCoreBoxInputChange, useBox } from '@talex-touch/utils/plugin/sdk'

  const box = useBox()

  async function init() {
    // Enable input monitoring
    await box.allowInput()

    // Watch for input changes
    onCoreBoxInputChange(async ({ data }) => {
      const results = await search(data.query.text)

      // Resize the window to match the result count
      await box.expand({ length: Math.min(results.length, 10) })
    })
  }
---
:::

---

## Type Definitions

:::TuffCodeBlock{lang="typescript"}
---
code: |
  interface BoxSDK {
    hide(): void
    show(): void
    expand(options?: BoxExpandOptions): Promise<void>
    shrink(): Promise<void>
    hideInput(): Promise<void>
    showInput(): Promise<void>
    getInput(): Promise<string>
    setInput(value: string): Promise<void>
    clearInput(): Promise<void>
    allowInput(): Promise<void>
    allowClipboard(types: number): Promise<void>
  }

  interface BoxExpandOptions {
    length?: number
    forceMax?: boolean
  }

  enum ClipboardType {
    TEXT = 0b0001,
    IMAGE = 0b0010,
    FILE = 0b0100,
  }
---
:::

## Best Practices

- Stop listeners when the feature is idle to reduce event noise.
- Use `expand`/`shrink` based on result count for predictable UX.
- Throttle heavy logic in input or clipboard callbacks.

## Technical Notes

- Box SDK sends IPC requests to the main process to manage window state safely.
- Monitoring is filtered in the CoreBox main process before reaching plugins.