API do elemento

A interface pública nativa é a tag <orb-z>, seus atributos documentados, propriedades de voz, métodos de conversa e métodos de animação. Os nós internos do Shadow DOM e as variáveis CSS não são, intencionalmente, pontos públicos de personalização.

Atributos e propriedades

Atributo HTML	Propriedade JavaScript	Valor aceito	Padrão
`state`	`state`	`idle`, `listening`, `thinking`, `speaking`, `asleep`	`idle`
`speech`	`speech`	Texto do host; tem precedência sobre `talkFlow`	`undefined`
`size`	`size`	Comprimento CSS não vazio; a propriedade também aceita um número positivo em pixels	`16rem`
`speed`	`speed`	Número positivo	`1`
`paused`	`paused`	Presença booleana / propriedade `boolean`	`false`
`elevated`	`elevated`	Presença booleana / propriedade `boolean`	`false`
`reduced-motion`	`reducedMotion`	`system`, `always`, `never`	`system`
`preset`	`preset`	Valores canônicos de `ORBZ_PRESET_NAMES` e um alias obsoleto derivado da conta; veja nomes das predefinições	`neongate` (`DEFAULT_ORBZ_PRESET`)
`color-primary`	—	Cor CSS	Cor primária Neongate
`color-secondary`	—	Cor CSS	Cor secundária Neongate
`color-accent`	—	Cor CSS	Cor de destaque Neongate
`color-highlight`	—	Cor CSS	Cor de realce Neongate
`color-background`	—	Cor CSS	Cor central Neongate

As cinco cores personalizadas são atributos nativos. Elas não são propriedades separadas do elemento nativo.

Propriedades de voz

A configuração de voz usa propriedades JavaScript porque mecanismos e etapas de conversa são valores estruturados, não strings HTML.

Propriedade	Tipo	Padrão
`voiceEngine`	`OrbzVoiceEnginePort \| undefined`	`undefined`
`talkFlow`	`readonly OrbzTalkStep[] \| undefined`	`DEFAULT_TALK_FLOW`
`talkContext`	`OrbzTalkContext` somente leitura	Memória de execução vazia
`intelligence`	`OrbzIntelligencePort \| undefined`	`undefined`

Configure um mecanismo antes de chamar startTalking(). Conectar um elemento e atribuir um mecanismo são ações silenciosas até essa chamada explícita. Atribuir undefined remove o mecanismo configurado.

Estados

Estado	Intenção visual
`idle`	Presença tranquila enquanto o assistente aguarda
`listening`	Sinalização atenta enquanto a entrada é capturada
`thinking`	Movimento concentrado durante o processamento
`speaking`	Movimento enérgico enquanto uma resposta é reproduzida
`asleep`	Repouso tranquilo e atenuado ou estado desativado


const orb = document.querySelector("orb-z");
if (orb) orb.state = "thinking";

Um valor incompatível é normalizado para idle. Ao observar um atributo inválido que não seja nulo, o Orbz escreve o valor normalizado de volta no atributo.

Tamanho e velocidade

A propriedade size aceita um número ou uma string:


orb.size = 320;      // "320px"
orb.size = "20rem"; // "20rem"
orb.size = "40vw";  // "40vw"

Um tamanho numérico não finito ou não positivo usa 16rem. Espaços nas extremidades das strings são removidos; forneça um comprimento CSS válido e não vazio para obter um layout previsível.

speed é um multiplicador positivo. Valores inválidos, zero, negativos ou não finitos são normalizados para 1.


orb.speed = 0.8;
orb.speed = 1.25;

Semântica booleana

paused e elevated são atributos booleanos padrão. Sua presença significa verdadeiro — mesmo quando o valor literal do atributo é "false".


<orb-z paused></orb-z>
<orb-z elevated></orb-z>


orb.paused = false;   // removes the paused attribute
orb.elevated = true;  // adds the elevated attribute

paused congela a animação ativa. elevated adiciona uma sombra centralizada ao redor do componente circular e não altera as dimensões do layout.

Movimento reduzido

Valor	Comportamento
`system`	Segue `prefers-reduced-motion` e responde às mudanças de preferência
`always`	Sempre apresenta movimento reduzido
`never`	Sempre apresenta o perfil completo de movimento

Valores inválidos são normalizados para system. paused e movimento reduzido são diferentes: a pausa congela a apresentação atual; o movimento reduzido seleciona uma apresentação mais tranquila.

Predefinições

Nome	Primária	Secundária	Destaque	Realce	Fundo
`neongate` (padrão)	`#6C5CFF`	`#00E9FF`	`#FF4DDE`	`#FFB07A`	`#14142B`
`periwinkle`	`#6667AB`	`#8FB8FF`	`#E66FA9`	`#F3ECFF`	`#111226`
`magenta`	`#BB2649`	`#F06A82`	`#29B8A6`	`#FFDCE4`	`#250A12`
`peach`	`#FFBE98`	`#FF8F70`	`#D987A3`	`#FFF0E7`	`#2A1516`
`mocha`	`#A47864`	`#D3A17E`	`#7FA18F`	`#F2E2D7`	`#211613`
`ivory`	`#F0EEE9`	`#AFC7D3`	`#C8B3D4`	`#FFFFFF`	`#171A20`


<orb-z preset="ivory"></orb-z>

Uma predefinição inválida é normalizada para DEFAULT_ORBZ_PRESET. A API pública se chama preset; não existe atributo nem propriedade palette. Veja nomes das predefinições Neongate para conhecer o alias obsoleto e a normalização canônica.

Paleta personalizada

Omita o atributo preset e defina uma ou mais cores personalizadas:


<orb-z
  color-primary="#7C3AED"
  color-secondary="#22D3EE"
  color-accent="#F472B6"
  color-highlight="#FDE68A"
  color-background="#09090B"
></orb-z>

Valores vazios são removidos e cores ausentes usam os padrões Neongate. Uma predefinição explícita e cores personalizadas são mutuamente exclusivas. Quando ambas estão presentes, a predefinição prevalece, as cores personalizadas são ignoradas e o Orbz registra um erro de conflito. Remover preset ativa as cores personalizadas que ainda estiverem presentes.

O getter da propriedade preset sempre retorna um nome de predefinição normalizado, incluindo DEFAULT_ORBZ_PRESET quando o atributo está ausente. Use hasAttribute("preset") para distinguir o modo de predefinição explícita do modo de cores personalizadas. Atribuir null ou undefined ao setter de preset remove o atributo.

Métodos

Método	Efeito
`pause()`	Pausa a animação ativa e reflete o estado de pausa
`play()`	Retoma a animação ativa e remove o estado de pausa
`restart()`	Reconstrói a animação do estado atual desde o início
`startTalking()`	Fala `speech` do host ou limpa o contexto e inicia `talkFlow` não vazio; sem ambos, não faz nada
`receive(input)`	Envia texto à etapa atual de pergunta ou resposta
`stopTalking()`	Interrompe o mecanismo de voz e a execução da conversa atuais


import type { OrbzElement } from "@neongate-ai/orbz";
 
const orb = document.querySelector<OrbzElement>("orb-z");
 
orb?.pause();
orb?.play();
orb?.restart();
await orb?.receive('Jonatas');

Orbz só inicia fala após o host chamar startTalking(). Forneça speech ou talkFlow não vazio; speech tem precedência e, sem ambos, a chamada não faz nada. Uma etapa ask personalizada guarda a entrada na chave capture do contexto da instância. Não há pergunta de nome ou conversa padrão integrada. Veja Voz e execução de conversas.

Atributos observados

ORBZ_OBSERVED_ATTRIBUTES contém a lista exata de atributos reativos:


state, size, speed, speech, paused, elevated, preset, reduced-motion,
color-accent, color-background, color-highlight,
color-primary, color-secondary

Alterar um desses atributos após a conexão sincroniza o componente. Veja Exportações do pacote para conhecer as constantes e os tipos TypeScript.