Charliehub · by A.N.D.Why

Building block 5 · The basics

Surfaces

A surface is a place your extension can show you something. It can ask a quick question, open a window that stays put, or add its own section or page to Charlie.

What you'd use it for

In your manifest

From the checklist extension, trimmed: a tool that opens a window, and a sidebar section.

checklist / manifest.json
"sidebar": {
  "label": "Checklists",
  "component": "./build/ChecklistSidebar.js"
},
"tools": [
  {
    "name": "open",
    "handler": "./handlers/open.js",
    "ui": {
      "surface": "window",
      "component": "./build/ChecklistWindow.js"
    }
  }
]

From the hub-persistence extension (Finder), trimmed: a top-bar page with its own chat.

hub-persistence / manifest.json
"topBar": {
  "label": "Finder",
  "icon": "folders",
  "component": "./build/Finder.js",
  "keepAlive": true,
  "thread": {
    "instructions": {
      "module": "./handlers/finderInstructions.js"
    }
  }
}

What each part means

FieldWhat it does
ui.surface: "modal"A pop-up card over the chat, which dims behind it. It waits for one answer, then closes.
ui.surface: "chat-replacement"Takes the place of the message box until you answer. The conversation above stays visible. Questions uses this.
ui.surface: "window"A separate window that stays open after the reply. Later tool calls can update it.
ui.componentThe built file to show in that surface.
sidebarA section in Charlie's left sidebar, with a label and a component.
topBarAn item in Charlie's top bar. Picking it fills the main area with your component. icon is a Tabler icon name.
topBar.keepAliveOptional. Hides the page when you switch away, so unsaved work survives.
topBar.threadOptional. Docks a chat under the page. See Instructions.

Charlie also accepts "popover" for ui.surface, but it isn't built yet.

How a tool uses its surface

For a modal or chat-replacement, the handler calls ctx.requestUI(props). Your answer comes back as the result. A handler can also pass a second value to pick a different surface for that one call.

For a window, the handler calls ctx.openWindow(props, { instanceKey }). It returns at once and never waits for an answer. Calling again with the same instanceKey brings the same window forward.

Components are built files

Each component is a React component, written as JSX in src/ and compiled to plain JavaScript in build/. Point your manifest at the build/ file. Don't import anything: React and CharlieUI are already there.

Talking to Charlie

What a component receives depends on where it lives:

CharlieUI is Charlie's kit of ready-made pieces: Surface, Field, Text, Button, Choice, TextInput, List, Badge, Markdown and more. They follow light and dark mode for you. Escape lets you drop to plain markup, such as a dense table, and still match the theme.

Things to know

See it in

Every field, in full: reference: ui, sidebar and topBar.