🪟 Painéis e botões

Um painel tem duas metades. $.ui.open({ id, title }) pede o espaço; um hook ui.render em { component: 'Pane', requestId: id } desenha o conteúdo. Um painel por id: abrir de novo um id aberto só troca o título.

Quem decide onde ele fica é a superfície. No terminal em tela cheia, ele encaixa ao lado da conversa (dock); fora disso, abre acima do prompt (inline). O painel existe em todas as superfícies, inclusive no celular.

O que olhar na tabela: o exemplo oficial faz as duas coisas para mostrar que dá. O curso segue o recibo: abrir só por pedido evita um painel tomando a tela de quem não pediu.

// meu-painel/.claude-plugin/plugin.json
{
  "name": "meu-painel",
  "version": "0.1.0",
  "description": "Painel do Rafa: arquivos editados nesta sessão (/tocados)",
  "author": { "name": "Rafa" },
  "types": "./types/index.d.ts"
}

// meu-painel/hooks/hooks.json
{ "modules": ["./register.tsx"] }

// meu-painel/types/index.d.ts
export type Caminho = string

declare module 'claude-code' {
  interface PluginState {
    'meu-painel': { arquivos: string[] }
  }
}

// meu-painel/hooks/register.tsx
import { atom, read, update } from 'claude-code'
import type { Register } from 'claude-code'

const PAINEL = 'meu-painel'
const arquivos = atom({ plugin: 'meu-painel', key: 'arquivos' } as const, [])

export const register: Register = on => {
  on('session.start', async ($, e, next) => {
    await $.command.register({ name: 'tocados', description: 'Abre o painel dos arquivos editados' })
    return next(e)
  })

  on('tool.call', { tool: 'Edit' }, async ($, e, next) => {
    const ran = await next(e)
    if (ran.deny === undefined && ran.isError !== true) {
      await update($, arquivos, lista => [...lista.filter(p => p !== e.file_path), e.file_path].slice(-50))
    }
    return ran
  })

  on('command.run', { command: 'tocados' }, async $ => {
    const aberto = await $.ui.open({ id: PAINEL, title: 'Arquivos tocados' })
    return { text: aberto.isPlaced ? 'Painel aberto.' : 'Painel esperando espaço na tela.' }
  })

  on('ui.render', { component: 'Pane', requestId: PAINEL }, async ($, e) => {
    const { Box, Text, Button } = $.ui.resolve(e)
    const lista = await read($, arquivos)
    const largura = e.props.bodyColumns
    const corta = (s: string) => (s.length > largura ? `…${s.slice(-(largura - 1))}` : s)

    return (
      <Box flexDirection="column">
        {lista.length === 0 && <Text dimColor>Nenhuma edição ainda.</Text>}
        {lista.map(p => <Text>{corta(p)}</Text>)}
        <Box key="botoes">
          <Button key="limpar" hotkey="l" label="limpar" onPress={() => update($, arquivos, () => [])} />
          <Button key="fechar" hotkey="f" label="fechar" role="dismiss" onPress={() => $.ui.close({ id: PAINEL })} />
        </Box>
      </Box>
    )
  })
}

O painel encaixado ao lado da conversa é mais estreito que a tela. Se o Rafa medir por e.viewport.columns, a linha passa da moldura. A medida certa é e.props.bodyColumns: as colunas dentro da moldura, sem nenhuma célula embaixo da marca de fechar.

Uma mudança de largura redesenha sozinha, então uma árvore medida por bodyColumns fica certa. Mudança só de altura não redesenha nada.

Como ler o desenho: o mesmo painel em duas telas. A seta azul é o bodyColumns em cada uma: muito menor que a tela à esquerda. O placement chega nas props e é só leitura.

No terminal, um Button aparece como [ label ]. A hotkey (um dígito ou uma letra minúscula) aperta o botão enquanto o painel ou a faixa tem o teclado: depois de ctrl+x tab, de um clique, ou se o painel abriu com focus.

Sempre dê key aos botões. É pela key que o engine sabe qual foi apertado e que os testes acham o botão (módulo 4.2).

<Box key="botoes">
  <Button key="alternar" hotkey="t" label={modo === 'bytes' ? 'ver por arquivos' : 'ver por tamanho'} onPress={alternar} />
  <Text> </Text>
  <Button key="reler" hotkey="r" label="ler de novo" onPress={reler} />
</Box>

Os handlers ficam no próprio plugin, como closures da árvore: onPress no Button, onSubmit e onInput no Input, onSelect no Select. A superfície só manda de volta "apertaram tal key".

No caminho, cada gesto vira um evento: ui.press, ui.input, ui.select. Outro mod pode se pendurar neles (por exemplo, para registrar cliques). No seu mod, quase sempre basta o handler no elemento.

const { Box, Text, Input } = $.ui.resolve(e)
// ...
<Input
  key="filtro"
  placeholder="filtrar por pasta"
  onSubmit={valor => update($, filtro, () => valor)}
/>

Às vezes o Rafa quer uma pergunta rápida que a pessoa responde e fecha: "limpar a lista?". Três opções de $.ui.open juntas transformam o painel num diálogo: focus, closeOnEscape e holdToasts.

Com elas, o painel pega o teclado, Tab e setas andam pelos botões, Esc fecha, e todo toast (de qualquer plugin) espera atrás dele. rows pede a altura certa para um diálogo curto aparecer inteiro.

$.ui.close({ id }) fecha um painel do seu plugin; um id que não está aberto é ignorado. Todo fechamento passa pelo evento ui.close, com e.origin dizendo de quem foi: plugin (a sua chamada), person (a marca de fechar, ctrl+x x ou Esc com closeOnEscape) ou unload (o engine descarregou o plugin).

Um hook em ui.close que responde sem next mantém o painel aberto, menos no unload. Use com cuidado: segurar o painel contra a vontade da pessoa é irritante. Para saber o que está aberto, $.ui.panes() lista os seus painéis com isPlaced.

Como ler o desenho: os fechamentos do plugin e da pessoa passam pelo ui.close, onde um hook pode segurar. O unload (tracejado) não pode ser segurado: quando o engine descarrega o plugin, o painel fecha de qualquer jeito.

claude --plugin-dir meu-painel