@softize/opus 9.1.0 → 9.1.1

package/CHANGELOG.md

@@ -11,6 +11,15 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 > tinha ficado sem registro nenhum, o que é exatamente o caso que este arquivo existe
 > pra cobrir.
 
+## 9.1.1 — 2026-08-20
+
+**`Ask` leva elicitação estruturada para `@softize/opus/ui/react`.** O componente
+controlado apresenta de uma a quatro `AskQuestion`, deriva `AskAnswer[]` sem tipos
+paralelos e suporta seleção única por radiogroup, seleção múltipla por pills e texto livre
+sempre disponível. Descrições usam Tooltip; teclado, validação, estados `disabled`/`busy`
+e submit acessível ficam no componente. Transporte, SSE, persistência e integração com
+`ChatEvent` continuam sob responsabilidade do consumidor.
+
 ## 9.1.0 — 2026-08-19
 
 **Observabilidade ganha uma porta vendor-neutral no runtime.** `ObservabilityAdapter`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "9.1.0",
+  "version": "9.1.1",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/src/ui/components/primitives/ask.tsx

@@ -0,0 +1,186 @@
+import * as React from 'react'
+import type { AskAnswer, AskQuestion } from '../../../core/index.ts'
+import { cn } from '../../lib/cn.ts'
+import { Button } from './button.tsx'
+import { Card } from './card.tsx'
+import { Input } from './input.tsx'
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from './tooltip.tsx'
+
+export interface AskProps {
+  /** Uma a quatro perguntas do contrato de elicitação. */
+  questions: AskQuestion[]
+  /** Respostas controladas, na mesma ordem de `questions`. Entradas ausentes são vazias. */
+  answers: AskAnswer[]
+  onChange: (answers: AskAnswer[]) => void
+  /** Dispara somente quando toda pergunta tem uma opção ou texto livre. */
+  onSubmit: (answers: AskAnswer[]) => void
+  disabled?: boolean
+  busy?: boolean
+  className?: string
+}
+
+function answerFor(question: AskQuestion, answer?: AskAnswer): AskAnswer {
+  const optionLabels = new Set(question.options.map((option) => option.label))
+  const selected = (answer?.selected ?? []).filter((label) => optionLabels.has(label))
+  return {
+    header: question.header?.trim() || question.question,
+    selected: question.multiSelect ? selected : selected.slice(0, 1),
+    ...(answer?.text === undefined ? {} : { text: answer.text }),
+  }
+}
+
+function isAnswered(answer: AskAnswer): boolean {
+  return answer.selected.length > 0 || (answer.text?.trim() ?? '') !== ''
+}
+
+/** Elicitação estruturada controlada. Não executa transporte nem mantém estado de domínio. */
+export function Ask({
+  questions,
+  answers,
+  onChange,
+  onSubmit,
+  disabled = false,
+  busy = false,
+  className,
+}: AskProps): React.ReactElement {
+  const id = React.useId()
+  const questionSignature = JSON.stringify(questions)
+  const [submittedSignature, setSubmittedSignature] = React.useState<string>()
+  const submitted = submittedSignature === questionSignature
+  const normalized = questions.map((question, index) => answerFor(question, answers[index]))
+  const validCount = questions.length >= 1 && questions.length <= 4
+  const allAnswered = validCount && normalized.every(isAnswered)
+  const locked = disabled || busy
+
+  const changeAt = (index: number, next: AskAnswer): void => {
+    const nextAnswers = [...normalized]
+    nextAnswers[index] = next
+    onChange(nextAnswers)
+  }
+
+  return (
+    <Card
+      asChild
+      className={cn('p-4', className)}
+      aria-busy={busy || undefined}
+      aria-disabled={disabled || undefined}
+    >
+      <form
+        data-slot="ask"
+        noValidate
+        onSubmit={(event) => {
+          event.preventDefault()
+          setSubmittedSignature(questionSignature)
+          if (allAnswered && !locked) onSubmit(normalized)
+        }}
+      >
+        <TooltipProvider>
+          <div className="space-y-4">
+            {questions.map((question, questionIndex) => {
+              const answer = normalized[questionIndex]
+              const questionId = `${id}-question-${questionIndex}`
+              const errorId = `${id}-error-${questionIndex}`
+              const invalid = submitted && !isAnswered(answer)
+
+              return (
+                <fieldset key={questionId} disabled={locked} className="min-w-0 space-y-2.5">
+                  <legend id={questionId} className="text-sm font-medium text-foreground">
+                    {question.question}
+                  </legend>
+                  <div
+                    role={question.multiSelect ? 'group' : 'radiogroup'}
+                    aria-labelledby={questionId}
+                    aria-describedby={invalid ? errorId : undefined}
+                    className="flex flex-wrap gap-2"
+                    onKeyDown={question.multiSelect ? undefined : (event) => {
+                      if (!['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown'].includes(event.key)) return
+                      const radios = Array.from(
+                        event.currentTarget.querySelectorAll<HTMLButtonElement>('[role="radio"]:not(:disabled)'),
+                      )
+                      const current = radios.indexOf(document.activeElement as HTMLButtonElement)
+                      if (current < 0 || radios.length === 0) return
+                      event.preventDefault()
+                      const direction = event.key === 'ArrowRight' || event.key === 'ArrowDown' ? 1 : -1
+                      const next = radios[(current + direction + radios.length) % radios.length]
+                      next.focus()
+                      next.click()
+                    }}
+                  >
+                    {question.options.map((option) => {
+                      const selected = answer.selected.includes(option.label)
+                      const firstSelected = answer.selected[0]
+                      const firstOption = question.options[0]?.label
+                      const optionButton = (
+                        <Button
+                          type="button"
+                          size="sm"
+                          shape="pill"
+                          variant={selected ? 'secondary' : 'outline'}
+                          role={question.multiSelect ? undefined : 'radio'}
+                          aria-checked={question.multiSelect ? undefined : selected}
+                          aria-pressed={question.multiSelect ? selected : undefined}
+                          tabIndex={question.multiSelect
+                            ? undefined
+                            : selected || (firstSelected === undefined && option.label === firstOption)
+                              ? 0
+                              : -1}
+                          disabled={locked}
+                          onClick={() => {
+                            const selectedOptions = question.multiSelect
+                              ? selected
+                                ? answer.selected.filter((label) => label !== option.label)
+                                : [...answer.selected, option.label]
+                              : [option.label]
+                            changeAt(questionIndex, { ...answer, selected: selectedOptions })
+                          }}
+                        >
+                          {option.label}
+                        </Button>
+                      )
+
+                      return option.description ? (
+                        <Tooltip key={option.label}>
+                          <TooltipTrigger asChild>{optionButton}</TooltipTrigger>
+                          <TooltipContent>{option.description}</TooltipContent>
+                        </Tooltip>
+                      ) : (
+                        <React.Fragment key={option.label}>{optionButton}</React.Fragment>
+                      )
+                    })}
+                  </div>
+                  <Input
+                    value={answer.text ?? ''}
+                    onChange={(event) => changeAt(questionIndex, { ...answer, text: event.target.value })}
+                    placeholder="Outro (opcional)…"
+                    aria-label={`Outra resposta para: ${question.question}`}
+                    aria-invalid={invalid || undefined}
+                    aria-describedby={invalid ? errorId : undefined}
+                    disabled={locked}
+                  />
+                  {invalid && (
+                    <p id={errorId} className="text-sm text-destructive">
+                      Escolha uma opção ou escreva uma resposta.
+                    </p>
+                  )}
+                </fieldset>
+              )
+            })}
+          </div>
+        </TooltipProvider>
+        {!validCount && (
+          <p role="alert" className="mt-3 text-sm text-destructive">
+            Ask aceita de 1 a 4 perguntas.
+          </p>
+        )}
+        <div aria-live="polite" className="sr-only">
+          {submitted && !allAnswered ? 'Há perguntas sem resposta.' : ''}
+        </div>
+        <div className="mt-4 flex justify-end">
+          <Button type="submit" size="sm" busy={busy} disabled={disabled || !validCount}>
+            Responder
+          </Button>
+        </div>
+      </form>
+    </Card>
+  )
+}

package/src/ui/docs/content/ask.md

@@ -0,0 +1,31 @@
+Elicitação estruturada controlada baseada diretamente em `AskQuestion` e `AskAnswer`. O componente só apresenta e valida respostas; transporte, persistência e continuação do agente pertencem ao consumidor.
+
+```tsx preview
+const [answers, setAnswers] = React.useState([])
+
+render(
+  <Ask
+      questions={[
+        {
+          question: 'Qual ambiente devemos usar?',
+          header: 'Ambiente',
+          options: [
+            { label: 'Produção', description: 'Usa dados e serviços reais.' },
+            { label: 'Homologação', description: 'Usa o ambiente de validação.' },
+          ],
+        },
+        {
+          question: 'Quais verificações devo executar?',
+          header: 'Verificações',
+          multiSelect: true,
+          options: [{ label: 'Testes' }, { label: 'Typecheck' }, { label: 'Build' }],
+        },
+      ]}
+      answers={answers}
+      onChange={setAnswers}
+      onSubmit={(next) => console.log(next)}
+  />,
+)
+```
+
+Cada pergunta exige pelo menos uma opção válida selecionada **ou** texto livre não vazio. `busy` mostra o progresso no botão e trava os controles; `disabled` apenas trava a interação. A ordem de `answers` acompanha a ordem de `questions`, e o `header` de cada resposta é derivado de `question.header` (ou do próprio enunciado quando o header estiver vazio).

package/src/ui/docs/registry.tsx

@@ -56,6 +56,7 @@ import buttonGroupMd from './content/button-group.md?raw'
 import calendarMd from './content/calendar.md?raw'
 import cardMd from './content/card.md?raw'
 import carouselMd from './content/carousel.md?raw'
+import askMd from './content/ask.md?raw'
 import chatMd from './content/chat.md?raw'
 import checkboxMd from './content/checkbox.md?raw'
 import collapsibleMd from './content/collapsible.md?raw'
@@ -316,6 +317,7 @@ export const UI_SECTIONS: DocSection[] = [
       {
         label: 'IA',
         pages: [
+          { slug: 'ask', title: 'Ask', render: comp('Ask', 'ask', askMd) },
           { slug: 'chat', title: 'Chat', render: comp('Chat', 'chat', chatMd) },
           { slug: 'composer', title: 'Composer', render: comp('Composer', 'composer', composerMd) },
         ],

package/src/ui/meta.ts

@@ -11,6 +11,12 @@ import type { ComponentMeta } from './index.ts'
 
 /** Todos os metas, chaveados pelo nome canônico (kebab). Fonte única — zero duplicação. */
 export const componentMeta = {
+  'ask': {
+    name: 'ask',
+    ancestry: 'opus',
+    whenToUse:
+      'Elicitação estruturada controlada para 1–4 perguntas `AskQuestion`: opções single/multi em pills, texto livre opcional, validação e submit de `AskAnswer[]`. Não faz transporte, persistência nem integração automática com ChatEvent; o consumidor controla `answers`/`onChange` e conecta `onSubmit` ao canal apropriado.',
+  },
   'alert': {
     name: 'alert',
     ancestry: 'opus',

package/src/ui/react.tsx

@@ -19,6 +19,8 @@ export { Input } from './components/primitives/input.tsx'
 
 export { Chat } from './components/primitives/chat.tsx'
 export type { ChatProps, ChatMessage, ChatArtifact, ChatTranscriptItem } from './components/primitives/chat.tsx'
+export { Ask } from './components/primitives/ask.tsx'
+export type { AskProps } from './components/primitives/ask.tsx'
 export { Composer } from './components/primitives/composer.tsx'
 export type { ComposerProps } from './components/primitives/composer.tsx'
 export { Copyable } from './components/primitives/copyable.tsx'