App Shell – Code

Implementation
AppShell Props
AppSurfaceHandle

Common Examples

To use the AppShell, pass the required chat region. Add header, rail, and artifact as needed. The kit forbids children. chat is always inline and never leaves the layout.

import { AppShell } from "@servicetitan/anvil2-ai-kit";

function ExampleComponent() {
  return (
    <AppShell
      header={<AppHeader title="Atlas" />}
      rail={<ChatHistory items={chats} />}
      chat={<ChatLayout conversation={messages} prompt={prompt} />}
      artifact={<TabbedLayout tabs={tabs} />}
    />
  );
}

Regions

A region shows inline when it fits and becomes a modal drawer when it cannot. The rail auto-yields before the artifact as the shell narrows.

Initial visibility

defaultRailCollapsed and defaultArtifactCollapsed start a region collapsed on first paint, without a close transition.

Artifact width

defaultArtifactWidth is "regular" (560px) or "large" (a 720px floor that fills available width and collapses the rail). It is a starting width only; the artifact stays drag-resizable.

Auto-collapse

Dragging the artifact past the point where chat would hit its minimum detaches it into a drawer. Dragging back re-attaches it inline.

`useAppSurface`

Region show, hide, and toggle live on AppSurfaceHandle. From a parent, pass controlRef. From inside the tree, call useAppSurface().

const { toggleRail, showArtifact } = useAppSurface();

return (
  <AppHeader
    title="Atlas"
    trailingActions={[
      { icon: <IconPanelLeft />, label: "Toggle rail", onPress: toggleRail },
      {
        icon: <IconPanelRight />,
        label: "Show artifact",
        onPress: () => showArtifact({ width: "large" }),
      },
    ]}
  />
);

Window methods on the handle (open, maximize, …) are no-ops in a bare shell. isOpen and isFullscreen read true because the shell is the full surface.

Internationalization

AppShell owns these localized strings:

ai-kit.appShell.resizeRail
ai-kit.appShell.resizeArtifact
ai-kit.appShell.railDrawer
ai-kit.appShell.artifactDrawer

Mount AiKitIntlProvider inside CartoTheme to switch them.

React Accessibility

Rail and artifact drawers expose localized names.
Resize handles expose localized names for the rail and artifact.

<AppShell
  header={header}
  rail={rail}
  chat={chat}
  artifact={artifact}
  controlRef={controlRef}
/>

`AppShell` Props

The AppShell accepts the following props and forwards remaining <div> attributes except children and style.

ReactNode

required

Center region. Always inline.

ReactNode

Right region. Omit to render no artifact.

string

Class merged onto the root element.

Ref<AppSurfaceHandle>

Imperative surface handle for a parent. Prefer useAppSurface inside the tree. ref still forwards the root <div>.

boolean

default:"false"

Starts the artifact collapsed on first paint.

"regular" | "large"

default:"regular"

Starting artifact width preset. The artifact stays drag-resizable.

boolean

default:"false"

Starts the rail collapsed on first paint.

ReactNode

Full-width top region. Omit for no header.

ReactNode

Left region. Fixed width; never drag-resized. Omit to render no rail.

const surface = useAppSurface();
surface.showArtifact({ width: "large" });

`AppSurfaceHandle`

The same handle drives a bare AppShell and a Window. Region intents in a docked window maximize first, then apply.

"inline" | "drawer" | "hidden"

required

How the artifact is currently presented. Read-only.

() => void

required

Hides the window. No-op without a window.

WindowDragHandleProps

required

Spread onto a header action to move a docked window. Inert otherwise.

() => void

required

Hides the artifact.

() => void

required

Hides the rail.

boolean

required

Whether the surface is fullscreen. Always true in a bare shell.

boolean

required

Whether the window is open. Always true in a bare shell.

() => void

required

Expands the window to fullscreen. No-op without a window.

() => void

required

Shows the window. No-op without a window.

() => void

required

Restores the window to docked. No-op without a window.

(options?: { width?: 'regular' | 'large' }) => void

required

Shows the artifact. Maximizes a docked window first.

() => void

required

Shows the rail. Maximizes a docked window first.

() => void

required

Toggles the window open or closed. No-op without a window.

(options?: { width?: 'regular' | 'large' }) => void

required

Toggles the artifact. Maximizes first when docked and hidden.

() => void

required

Toggles the rail. Maximizes first when docked and hidden.

() => void

required

Toggles docked and fullscreen. No-op without a window.

AI Kit

Agent Experience

App Shell – Code

Common Examples

Regions

Initial visibility

Artifact width

Auto-collapse

`useAppSurface`

Internationalization

React Accessibility

`AppShell` Props

`AppSurfaceHandle`

​Common Examples

​Regions

​Initial visibility

​Artifact width

​Auto-collapse

​useAppSurface

​Internationalization

​React Accessibility

​AppShell Props

​AppSurfaceHandle

Common Examples

Regions

Initial visibility

Artifact width

Auto-collapse

`useAppSurface`

Internationalization

React Accessibility

`AppShell` Props

`AppSurfaceHandle`