ComponentContracts.js | Arcane OS SDK

On this page

Overview

Owns normalized configuration/value contracts and shared explicit STT activation behavior for chart, dashboard, Markdown, and voice components.

Artifact
ComponentContracts.js · esm
Classification
public first party
Availability
Cross-host with an injected event constructor outside DOM hosts
Normalization
Fully normalized labels, rows, definitions, visibility, formats, editor and voice options, plus capability-neutral STT activation intent and presentation state. Complete finite progress measures remain visible, including fractional and over-total values.

Import and lifecycle

JavaScript

import * as module from '/arcane/modules/ComponentContracts.js';

Normalization and formatting helpers are pure. createSTTActivationController installs one button listener, publishes and projects activation request or error events, invokes the configured host activation callback, reports presentation changes through onChange, and destroy removes the listener and disposes only an event source it created.

Application-facing behavior: Constant sets plus normalization, complete finite-progress formatting, and explicit STT activation helpers.

Protocol and host implementation

In-process only This detail does not widen the application-facing API or grant authority.

Exports, signatures, parameters, and results

Binding	Form	Declaration or signature	Parameter syntax
`CHART_LABELS`	variable · value	`variable CHART_LABELS`	`—`
`DASHBOARD_LABELS`	variable · value	`variable DASHBOARD_LABELS`	`—`
`MARKDOWN_FORMATS`	variable · value	`variable MARKDOWN_FORMATS`	`—`
`MARKDOWN_LABELS`	variable · value	`variable MARKDOWN_LABELS`	`—`
`STT_ACTIVATION_ERROR_CODES`	variable · value	`variable STT_ACTIVATION_ERROR_CODES`	`—`
`STT_ACTIVATION_EVENT_TYPES`	variable · value	`variable STT_ACTIVATION_EVENT_TYPES`	`—`
`STT_ACTIVATION_REASONS`	variable · value	`variable STT_ACTIVATION_REASONS`	`—`
`VOICE_LABELS`	variable · value	`variable VOICE_LABELS`	`—`
`VOICE_MESSAGES`	variable · value	`variable VOICE_MESSAGES`	`—`
`appendTranscription`	function	`function appendTranscription(current='',segment='',separator='\n\n')`	`current='',segment='',separator='\n\n'`
`applyMarkdownFormat`	function	`function applyMarkdownFormat(value='',selectionStart=0,selectionEnd=selectionStart,format={})`	`value='',selectionStart=0,selectionEnd=selectionStart,format={}`
`createSTTActivationController`	function	`function createSTTActivationController({ host, button, onChange, EventClass=globalThis.CustomEvent, eventSource=null })`	`{ host, button, onChange, EventClass=globalThis.CustomEvent, eventSource=null }`
`effectiveDashboardVisibility`	function	`function effectiveDashboardVisibility(definitions=[],visibility={})`	`definitions=[],visibility={}`
`formatAIRuntimeProgress`	function	`function formatAIRuntimeProgress(progress,fallback)`	`progress,fallback`
`normalizeChartOptions`	function	`function normalizeChartOptions(input={},previous={})`	`input={},previous={}`
`normalizeChartRows`	function	`function normalizeChartRows(data=[],options={})`	`data=[],options={}`
`normalizeDashboardDefinitions`	function	`function normalizeDashboardDefinitions(values=[])`	`values=[]`
`normalizeDashboardOptions`	function	`function normalizeDashboardOptions(input={},previous={})`	`input={},previous={}`
`normalizeDashboardVisibility`	function	`function normalizeDashboardVisibility(values={})`	`values={}`
`normalizeMarkdownFormats`	function	`function normalizeMarkdownFormats(values=MARKDOWN_FORMATS)`	`values=MARKDOWN_FORMATS`
`normalizeMarkdownOptions`	function	`function normalizeMarkdownOptions(input={},previous={})`	`input={},previous={}`
`normalizeVoiceOptions`	function	`function normalizeVoiceOptions(input={},previous={})`	`input={},previous={}`

Parameter meanings and results

Normalizers cover chart options and rows, dashboard definitions, options, and visibility, Markdown formats and options, and voice options. applyMarkdownFormat and appendTranscription return deterministic editor text and selection results. formatAIRuntimeProgress(progress,fallback) preserves complete finite completed/total measures, including fractional and over-total values, when total is positive and unit is nonempty; otherwise it returns the phase or fallback. createSTTActivationController({host,button,onChange,EventClass,eventSource}) returns mutable action, error, label, pending, selected, status, title, and visible getters plus request(action), synchronize(role), and destroy().

Events, side effects, and errors

Source-literal `CustomEvent` dispatches

No source-literal CustomEvent dispatch is part of this artifact.

Lifecycle and event flow

emits speech-stt-activation-request
emits speech-stt-activation-error

Direct coded failures

This artifact directly assigns no stable coded failure.

Exported Error subclasses

This artifact exports no Error subclass.

Documented failure behavior

TypeError or RangeError for invalid normalized records, values, callbacks, or chart bounds
ARCANE_STT_ACTIVATION_BUTTON_INVALID
ARCANE_STT_ACTIVATION_BUTTON_LISTENER_FAILED
ARCANE_STT_ACTIVATION_DOM_PROJECTION_UNAVAILABLE
ARCANE_STT_ACTIVATION_EVENT_CLASS_INVALID
ARCANE_STT_ACTIVATION_EVENT_SOURCE_INVALID
ARCANE_STT_ACTIVATION_HOST_INVALID
ARCANE_STT_ACTIVATION_ON_CHANGE_INVALID
ARCANE_STT_ACTIVATION_PRESENTATION_CALLBACK_FAILED
ARCANE_STT_ACTIVATION_REQUEST_REJECTED

Availability and capabilities

Cross-host with an injected event constructor outside DOM hosts. Fully normalized labels, rows, definitions, visibility, formats, editor and voice options, plus capability-neutral STT activation intent and presentation state. Complete finite progress measures remain visible, including fractional and over-total values.

Shared normalized value and explicit STT activation presentation layer for browser components. The configured host remains the lifecycle authority; this module implements no privileged Core service.

Contract example