Elements

Every <aparte-*> custom element, generated from the source. Attributes, events and descriptions come from the components’ JSDoc; this page can’t drift from the code.

<aparte-chat>

AparteChat - The Shell

The container element for a chat. Wrap a <aparte-chat-viewport> and a <aparte-composer> in it and it lays them out as a flex column — the viewport grows and scrolls, the composer sits below. Provide your own children for full control (custom composer, extra buttons), or leave it empty and it fills in a sensible default composition. Uses Light DOM for global CSS styling.

Being a component (not a bare <div>), it also owns behaviour a wrapper div can’t: with center-empty, it watches its own viewport and keeps the composer centered as a welcome state until the first message, then slides to the normal layout — no external JavaScript.

Presentational only: it does NOT wire a transport/client. Attach an AparteClient, or handle aparte-send yourself, as with the primitives. Size the element via CSS (a height, or let it fill a sized parent).

Attributes

Attribute	Description
placeholder	Placeholder for the composer input (default composition)
disabled	Disables the composer
center-empty	Center the composer as a welcome state until the first message, then slide to the normal layout

Properties

Property	Type	Description
viewport (readonly)	AparteChatViewport | null	The message viewport (yours or the default), or null before connect.
composer (readonly)	AparteComposer | null	The composer (yours or the default), or null before connect.

<aparte-chat-viewport>

AparteChatViewport - The Core

Container component with smart scroll, streaming, and segment support. Uses Light DOM for global CSS styling.

Attributes

Attribute	Description
scroll-threshold
max-rendered-bubbles
max-messages

Methods

Method	Description
configure(config: AparteViewportConfig): void	Configure viewport with options
appendToken(messageId: string, chunk: string): void	Append a token chunk to a message’s content (simple text streaming)
appendToSegment(messageId: string, segmentId: string, chunk: string): void	Append content to a specific segment within a message
addSegment(segment: AparteSegment): void	Add a new segment. Two calling conventions are accepted: - addSegment(segment) — AparteClient’s 1-arg “operate on the current (head) message” convention (also what a wrapper host installs); - addSegment(messageId, segment) — explicit standalone form. The first argument’s type disambiguates (string = messageId, object = segment), so a raw viewport driven by AparteClient no longer drops text (the args used to bind one position short, creating a phantom message).
addSegment(messageId: string, segment: AparteSegment): void
addSegment(messageIdOrSegment: string | AparteSegment, maybeSegment?: AparteSegment): void
updateSegment(segmentId: string, updates: Partial<AparteSegment>): void	Update a segment. updateSegment(segmentId, updates) (1-arg client convention → current message) or updateSegment(messageId, segmentId, updates) (explicit). Disambiguated by arity: the 3rd arg is absent and the 2nd is the updates object in the 1-arg form.
updateSegment(messageId: string, segmentId: string, updates: Partial<AparteSegment>): void
updateSegment(a: string, b: string | Partial<AparteSegment>, c?: Partial<AparteSegment>): void
removeSegment(segmentId: string): void	Remove a segment. removeSegment(segmentId) (1-arg client convention → current message) or removeSegment(messageId, segmentId) (explicit).
removeSegment(messageId: string, segmentId: string): void
removeSegment(a: string, b?: string): void
startSegment(messageId: string, segment: AparteSegment): void	Start a new streaming segment (e.g., thinking or code block) Creates the segment and marks it as streaming
completeSegment(messageId: string, segmentId: string): void	Complete a streaming segment
setUsage(messageId: string, usage: AparteUsage): void	Persist token usage on a message and propagate to the live bubble so the perf chip (tokens/sec) renders in the action bar.
completeMessage(messageId: string): void	Mark a message as finished streaming
updateMessage(messageId: string, updates: Partial<AparteMessage>): void	Atomic update for a message by ID Supports updating content, status, segments, and other metadata
addMessage(message: AparteMessage): void	Add a complete message to the message registry.
appendMessage(message: AparteMessage): void	Append a new message and create its bubble in the DOM. Implements the same contract as the Angular wrapper’s appendMessage(), making aparte-chat-viewport a fully standalone target for aparte-client. When _frameworkManagedDOM is true, only the internal repo is updated — the framework owns the DOM and will create the bubble element itself.
updateLastMessage(content: string, options?: { append?: boolean }): void	Update the last message content, optionally appending. Implements the same contract as the Angular wrapper’s updateLastMessage(),’ making aparte-chat-viewport a fully standalone streaming target for aparte-client.
addBranch(messageId: string): void	Add a new sibling branch to an assistant message (retry flow). Creates a new empty assistant message as a sibling of messageId under the same parent, switches the active branch to it, and re-renders the active path.
addSiblingOf(existingId: string, newMessage: AparteMessage): string | null	Add a new message relative to existingId, switch to it, and re-render. Role-aware semantics: - existingId is an assistant message → create a sibling (same parent), so the active path replaces the old response with the new one. - existingId is a user message → create a child of that message, so the user message stays on the active path and the new response follows it. Returns the new message’s ID, or null if existingId is not found.
navigateBranch(messageId: string, direction: 'prev' | 'next'): void	Navigate to the previous or next sibling branch of a message. Triggers a full re-render of the active path.
truncateResponsesAfter(userMessageId: string): void	Remove ALL responses to a user message (every child branch) and set head back to userMessageId. Cleaner than truncateFrom for edit flows: it discards stale sibling branches so the regenerated response starts alone.
truncateFrom(messageId: string): void	Remove all messages from messageId onwards (inclusive) from state and DOM. Used by edit to truncate history before re-generating.
getMessage(messageId: string): AparteMessage | undefined	Get a message by ID
getMessages(): AparteMessage[]
exportTree(): ExportedMessageRepository	Export the full conversation tree (all branches, not just the active path). The returned snapshot can be persisted and restored via importTree().
importTree(tree: ExportedMessageRepository): void	Import a previously-exported tree snapshot, restoring the full branch topology and the active head. Replaces any existing repo content. Always calls _reRenderActivePath(): - In native DOM mode: rebuilds bubble elements. - In framework-managed mode: skips DOM manipulation but dispatches aparte-path-changed with sibling metadata so the wrapper can update branch arrows on already-rendered bubbles.
clearAll(): void	Clear all messages and remove all bubble elements from the DOM. Also dispatches a aparte-reset-done event. In framework-managed mode the DOM is owned by the host framework (Angular
clearMessages(): void	Clear all messages
setMessages(messages: AparteMessage[]): void	Replace the entire message list in one shot. Used when switching conversations: clears existing repo + DOM, then appends each message. In framework-managed mode the framework re-renders the bubble DOM itself; we only update the internal repo (used by aparte-client to build chat history).
scrollToBottom(): void	Scroll to bottom of viewport
resetSpacer(): void	Reset the bottom spacer to 0 height immediately and freeze it for 350 ms so the host-app layout transition (e.g. flex: 0→1 animation) does not trigger a premature recalculation with mid-animation geometry. Call before a full messages swap.
setAutoScroll(enabled: boolean): void	Enable or disable auto-scroll
setFrameworkManagedDOM(managed: boolean): void	Signal that a framework (e.g. Angular) manages the bubble DOM. When true, branch navigation dispatches aparte-path-changed without clearing/rebuilding the messages wrapper — the framework re-renders instead.
requestSmoothScroll(): void	Request that the next auto-scroll triggered by a DOM mutation uses smooth behaviour instead of instant. Call this just before adding a user message bubble so the viewport animates down rather than jumping. Resets automatically after the first auto-scroll fires.

Events

Event	Description
aparte-segment-update
aparte-reset-done
aparte-path-changed

<aparte-composer>

Attributes

Attribute	Description
placeholder	Forwarded to aparte-composer-input via event
disabled	Disables the whole composer
target	ID of the target element

Properties

Property	Type	Description
value (readonly)	string
streaming (readonly)	boolean
disabled (readonly)	boolean
submitOnEnter (readonly)	boolean	When false, Shift+Enter submits and a bare Enter inserts a newline — the inverse of the default. Driven by the submit-on-enter attribute.
attachments (readonly)	File[]
placeholder (readonly)	string
targetId (readonly)	string | null
panelActive (readonly)	boolean

Methods

Method	Description
getState(): AparteComposerState	Snapshot of the composer’s observable state. Pair with the aparte-composer-change DOM event to drive a custom send button or footer control that lives outside the composer package:
setValue(value: string): void
addAttachments(files: FileList | File[]): void
removeAttachment(file: File): void
clearAttachments(): void
showPanel(panel: HTMLElement, options?: { submitEnabled?: boolean; onSubmit?: () => void }): void	Inject a panel into the composer, hiding the text input. The send button calls onSubmit when clicked.
hidePanel(): void	Remove the panel and restore the text input.
setPanelSubmitEnabled(enabled: boolean): void	Update the send button enabled state while a panel is active.
submit(): void	Submit the current value. Called by aparte-composer-send or programmatically.
cancel(): void	Cancel the current streaming response.
reset(): void	Reset the composer to its initial state. Clears value, attachments, and hides any active panel. Call this when switching conversations.
focus(): void	Focus the input primitive inside this composer.

Events

Event	Description
aparte-send	Fired when a message is submitted
aparte-cancel
aparte-composer-change

<aparte-chat-bubble>

AparteChatBubble - The Render

Message component supporting both simple content and rich segments. Uses Light DOM for global CSS styling.

Attributes

Attribute	Description
role
data-role
content
timestamp
message-id
streaming
name

Methods

Method	Description
appendToken(chunk: string): void	Append a token chunk (for streaming)
setContent(content: string): void	Set content directly
getContent(): string	Get current content
setSegments(segments: AparteSegment[]): void	Set segments for rich content
addSegment(segment: AparteSegment): void	Add a segment
updateSegment(segmentId: string, updates: Partial<AparteSegment>): void	Update a specific segment
appendToSegment(segmentId: string, content: string): void	Append content to a segment
getSegments(): AparteSegment[]	Get all segments
removeSegment(segmentId: string): void	Remove a segment by id (e.g. to discard a transient waiting indicator)
setAttachments(attachments: AparteAttachment[]): void	Set attachments (chips shown above message content, user role only)
setUsage(usage: AparteUsage | null | undefined): void	Set token usage + timing for this message (assistant only). Renders the info (“i”) action in the action bar; clicking it opens the app-owned stats popover (aparte-message-info).
setSiblings(count: number, index: number): void	Update the branch picker UI for tree-based navigation. The viewport calls this after a branch switch or re-render. Prev/Next clicks dispatch aparte-branch-navigate (bubbles: true) so the viewport can handle the actual tree switch.
updateMessage(updates: Partial<AparteMessage>): void	Atomic update for the message

Events

Event	Description
aparte-attachment-preview
aparte-branch-navigate
aparte-action
aparte-retry
aparte-feedback
aparte-message-info
aparte-edit

<aparte-chat-status>

Attributes

Attribute	Description
visible
text

Methods

Method	Description
show(): void	Show the typing indicator
hide(): void	Hide the typing indicator
toggle(): void	Toggle visibility
isVisible(): boolean	Check if visible

<aparte-conversation-list>

Attributes

Attribute	Description
active-id

Properties

Property	Type	Description
conversations	AparteConversationListItem[]	Set the list of conversations to display. Triggers a re-render.

<aparte-elicitation>

<aparte-composer-action>

Attributes

Attribute	Description
icon	Icon key for AparteConfig.getIcon(), or raw SVG/HTML starting with <
label	Accessible label (also used as tooltip)
disabled	Disables the button

Events

Event	Description
aparte-action-click	Bubbles up when the button is clicked detail: { actionId: string, composer: AparteComposer | null }

Slots

Slot	Description
default	Optional: override button content entirely

<aparte-composer-add-attachment>

Attributes

Attribute	Description
accept	MIME types / extensions passed to the file input (e.g. “image/*,.pdf”)
multiple	Allow multiple file selection (default: true)
disabled

<aparte-composer-attachments>

Events

Event	Description
aparte-attachment-preview

<aparte-composer-cancel>

<aparte-composer-input>

Attributes

Attribute	Description
placeholder	Placeholder text (fallback: reads from aparte-composer)
max-height	Max height in px before scroll (default: 200)
min-height	Min height in px. When omitted, the stylesheet’s min-height governs (44px in aparte.css) — so themes can resize the editor in pure CSS without being fought by an inline height.
disabled

Methods

Method	Description
getValue(): string
setValue(value: string): void
clear(): void
focus(): void
blur(): void
focusEnd(): void	Focus the editor and place the caret at the very end of its content.

Events

Event	Description
aparte-composer-submit

<aparte-composer-send>

<aparte-optgroup>

AparteOptgroup

Option group element for aparte-select dropdown.

Attributes

Attribute	Description
label	Group label
collapsible	Allow collapse/expand
collapsed	Collapsed state
loading

Properties

Property	Type	Description
label	string
collapsible (readonly)	boolean
collapsed	boolean
loading	boolean

Events

Event	Description
aparte-optgroup-toggle

<aparte-option>

AparteOption

Option element for aparte-select dropdown.

Attributes

Attribute	Description
value	Option value
disabled	Disabled state
selected	Selected state
data-status

Properties

Property	Type	Description
value	string
label (readonly)	string
disabled	boolean
selected	boolean

<aparte-progress-spinner>

AparteProgressSpinner

Circular progress spinner web component.

• Indeterminate (no value attribute): continuous rotation animation
• Determinate (value="0–100"): fills the arc proportionally

Attributes

Attribute	Description
value	Progress percentage 0–100 (omit for indeterminate)

<aparte-select>

Attributes

Attribute	Description
value
placeholder
disabled
grouped
searchable
open

Properties

Property	Type	Description
value	string
open	boolean

Events

Event	Description
aparte-select-open
aparte-select-close
aparte-select-change