@meistrari/chat-ui-lang 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# @meistrari/chat-ui-lang
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The catalogue of widgets the chat agent may emit as OpenUI Lang, shared by
+chat-nuxt (which renders them) and agent-api (which puts `prompt()` in the
+system prompt). No Vue here: only names, descriptions, Zod props and the
+prompt generator.
+
+Adding a widget is a two-part change in this monorepo: define it here and add
+its Vue renderer to `chat-nuxt/src/runtime/rendering/openui/registry.ts`. The
+registry test fails until both sides match. The full walkthrough is in
+`packages/chat-nuxt/docs/guides/widgets.md`.
+
+Bump `LIBRARY_VERSION` on every catalogue change: agent-api stamps it on each
+turn and chat-nuxt logs it with widget errors, which is how drift between the
+prompt and the renderer shows up in production.
+
+`@openuidev/lang-core` ships a postinstall that sends installation telemetry;
+the root `pnpm.neverBuiltDependencies` entry disables it.

package/package.json

@@ -1,6 +1,37 @@
 {
-  "name": "@meistrari/chat-ui-lang",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@meistrari/chat-ui-lang",
+    "version": "0.3.0",
+    "type": "module",
+    "main": "./src/index.ts",
+    "types": "./src/index.ts",
+    "exports": {
+        ".": "./src/index.ts"
+    },
+    "files": [
+        "src",
+        "README.md"
+    ],
+    "scripts": {
+        "test": "bun test",
+        "typecheck": "tsc --noEmit",
+        "measure": "bun scripts/measure.ts"
+    },
+    "dependencies": {
+        "@openuidev/lang-core": "1.0.0",
+        "zod": "^4.1.13"
+    },
+    "devDependencies": {
+        "@anthropic-ai/sdk": "0.133.0",
+        "typescript": "5.9.3"
+    },
+    "description": "Catalogue of chat widgets the Tela agent may emit as OpenUI Lang, shared by chat-nuxt and agent-api",
+    "license": "UNLICENSED",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/meistrari/chat-app.git",
+        "directory": "packages/ui-lang"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/actions.ts

@@ -0,0 +1,12 @@
+import { defineAction } from '@openuidev/lang-core'
+import { z } from 'zod'
+
+export const CopyText = defineAction({
+    name: 'CopyText',
+    description: 'Copia um texto para a área de transferência do usuário.',
+    params: z.object({
+        text: z.string(),
+    }),
+})
+
+export const actions = { CopyText }

package/src/components/actions.ts

@@ -0,0 +1,21 @@
+import { action } from '@openuidev/lang-core'
+import { z } from 'zod'
+import { defineUiComponent } from '../define'
+
+export const Button = defineUiComponent({
+    name: 'Button',
+    description: 'Botão de ação. Com @ToAssistant envia uma mensagem como se o usuário tivesse digitado.',
+    props: z.object({
+        label: z.string(),
+        action: action().optional(),
+        variant: z.enum(['primary', 'secondary']).optional().describe('Padrão secondary; no máximo um primary por grupo'),
+    }),
+})
+
+export const Buttons = defineUiComponent({
+    name: 'Buttons',
+    description: 'Grupo horizontal de botões.',
+    props: z.object({
+        buttons: z.array(Button.ref).min(1).max(4),
+    }),
+})

package/src/components/chart.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod'
+import { defineUiComponent } from '../define'
+
+export const Bar = defineUiComponent({
+    name: 'Bar',
+    description: 'Uma barra do gráfico.',
+    props: z.object({
+        label: z.string(),
+        value: z.number().describe('Valor numérico usado para o tamanho da barra'),
+        display: z.string().optional().describe('Valor formatado para exibir, ex: "R$ 1,2 mi"'),
+    }),
+})
+
+export const BarChart = defineUiComponent({
+    name: 'BarChart',
+    description: 'Gráfico de barras horizontais para comparar até 8 valores da mesma unidade.',
+    props: z.object({
+        title: z.string(),
+        bars: z.array(Bar.ref).min(2).max(8),
+        tone: z.enum(['neutral', 'positive', 'negative']).optional(),
+    }),
+})

package/src/components/chat.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod'
+import { defineUiComponent } from '../define'
+
+export const Option = defineUiComponent({
+    name: 'Option',
+    description: 'Uma alternativa de resposta.',
+    props: z.object({
+        id: z.string().describe('Identificador curto e único dentro da pergunta'),
+        label: z.string(),
+        description: z.string().optional().describe('Uma linha explicando a alternativa'),
+    }),
+})
+
+export const Question = defineUiComponent({
+    name: 'Question',
+    description: 'Pergunta de múltipla escolha para o usuário. Entre 2 e 4 alternativas.',
+    props: z.object({
+        id: z.string(),
+        title: z.string(),
+        options: z.array(Option.ref).min(2).max(4),
+        multiple: z.boolean().optional().describe('true permite marcar mais de uma alternativa'),
+    }),
+})
+
+export const Questions = defineUiComponent({
+    name: 'Questions',
+    description: 'Bloco de perguntas de esclarecimento. As respostas voltam como uma mensagem do usuário. Use no máximo 3 perguntas e só quando a resposta depender delas.',
+    props: z.object({
+        requestId: z.string().describe('Identificador curto desta rodada de perguntas, ex: "q-prazos"'),
+        questions: z.array(Question.ref).min(1).max(3),
+    }),
+})
+
+export const FileCard = defineUiComponent({
+    name: 'FileCard',
+    description: 'Cartão de um documento do vault, com preview e download.',
+    props: z.object({
+        vaultRef: z.string().describe('Referência vault:// do documento, exatamente como recebida'),
+        name: z.string().describe('Nome exibido do arquivo'),
+    }),
+})
+
+export const Citation = defineUiComponent({
+    name: 'Citation',
+    description: 'Chip de citação para um trecho de documento. Prefira citações inline no markdown; use este componente dentro de Card ou Stack quando a citação for o item em si.',
+    props: z.object({
+        ref: z.string().describe('Referência cite:// exatamente como recebida'),
+        label: z.string().optional().describe('Texto curto exibido no chip'),
+    }),
+})
+
+export const Image = defineUiComponent({
+    name: 'Image',
+    description: 'Imagem com legenda. Aceita referência vault:// de uma imagem gerada ou recebida, ou uma URL https pública.',
+    props: z.object({
+        src: z.string().describe('vault://... ou https://..., exatamente como recebida'),
+        alt: z.string().describe('Descrição curta da imagem'),
+        caption: z.string().optional(),
+    }),
+})

package/src/components/data.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod'
+import { defineUiComponent } from '../define'
+
+export const Metric = defineUiComponent({
+    name: 'Metric',
+    description: 'Um número de destaque com rótulo. Use para valores isolados, nunca para listas.',
+    props: z.object({
+        label: z.string().describe('O que o número representa'),
+        value: z.string().describe('Valor já formatado, ex: "R$ 12.400,00"'),
+        delta: z.string().optional().describe('Variação, ex: "+12%"'),
+        tone: z.enum(['neutral', 'positive', 'negative']).optional(),
+    }),
+})
+
+export const Col = defineUiComponent({
+    name: 'Col',
+    description: 'Uma coluna de tabela: rótulo e a lista de valores, um por linha.',
+    props: z.object({
+        label: z.string(),
+        values: z.array(z.union([z.string(), z.number()])).describe('Um valor por linha, na mesma ordem em todas as colunas'),
+        align: z.enum(['left', 'right']).optional().describe('right para números'),
+    }),
+})
+
+export const Table = defineUiComponent({
+    name: 'Table',
+    description: 'Tabela orientada a colunas. Use para 3 ou mais linhas comparáveis.',
+    props: z.object({
+        columns: z.array(Col.ref).min(1),
+        caption: z.string().optional(),
+    }),
+})

package/src/components/form.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod'
+import { defineUiComponent } from '../define'
+
+export const Input = defineUiComponent({
+    name: 'Input',
+    description: 'Campo de texto livre de uma linha.',
+    props: z.object({
+        name: z.string().describe('Identificador do campo dentro do formulário'),
+        label: z.string(),
+        placeholder: z.string().optional(),
+    }),
+})
+
+export const Select = defineUiComponent({
+    name: 'Select',
+    description: 'Escolha única entre alternativas curtas.',
+    props: z.object({
+        name: z.string(),
+        label: z.string(),
+        options: z.array(z.string()).min(2).max(8),
+    }),
+})
+
+export const Checkbox = defineUiComponent({
+    name: 'Checkbox',
+    description: 'Caixa de marcação sim/não.',
+    props: z.object({
+        name: z.string(),
+        label: z.string(),
+    }),
+})
+
+export const Form = defineUiComponent({
+    name: 'Form',
+    description: 'Formulário curto para coletar dados que faltam. Ao enviar, os valores voltam como uma mensagem do usuário.',
+    props: z.object({
+        name: z.string().describe('Identificador do formulário, ex: "dados-prazo"'),
+        fields: z.array(z.union([Input.ref, Select.ref, Checkbox.ref])).min(1).max(6),
+        submitLabel: z.string().optional().describe('Padrão "Enviar"'),
+    }),
+})

package/src/components/layout.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod'
+import { defineUiComponent } from '../define'
+import { Button, Buttons } from './actions'
+import { Bar, BarChart } from './chart'
+import { Citation, FileCard, Image, Option, Question, Questions } from './chat'
+import { Col, Metric, Table } from './data'
+import { Checkbox, Form, Input, Select } from './form'
+import { Callout, Markdown } from './text'
+
+const blockRef = z.union([Markdown.ref, Callout.ref, Metric.ref, Table.ref, BarChart.ref, Buttons.ref, Form.ref, Questions.ref, FileCard.ref, Image.ref, Citation.ref])
+
+export const Card = defineUiComponent({
+    name: 'Card',
+    description: 'Cartão com borda que agrupa blocos relacionados. Não aninhe Card em Card.',
+    props: z.object({
+        children: z.array(blockRef).min(1),
+        title: z.string().optional(),
+    }),
+})
+
+export const Stack = defineUiComponent({
+    name: 'Stack',
+    description: 'Raiz do widget. Empilha blocos em coluna ou os distribui em linha.',
+    props: z.object({
+        children: z.array(z.union([Card.ref, ...blockRef.options])).min(1),
+        direction: z.enum(['column', 'row']).optional().describe('row só para Metric ou Card lado a lado'),
+    }),
+})
+
+export const components = { Stack, Card, Markdown, Callout, Metric, Col, Table, Bar, BarChart, Button, Buttons, Input, Select, Checkbox, Form, Option, Question, Questions, FileCard, Image, Citation }

package/src/components/text.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod'
+import { defineUiComponent } from '../define'
+
+export const Markdown = defineUiComponent({
+    name: 'Markdown',
+    description: 'Texto em markdown. Use para qualquer prose dentro de um widget; suporta citações cite:// e links vault://.',
+    props: z.object({
+        text: z.string().describe('Conteúdo em markdown'),
+    }),
+})
+
+export const Callout = defineUiComponent({
+    name: 'Callout',
+    description: 'Aviso destacado com tom. Use para alertas, prazos, ressalvas ou conclusões importantes.',
+    props: z.object({
+        text: z.string().describe('Conteúdo em markdown'),
+        tone: z.enum(['info', 'success', 'warning', 'error']).optional().describe('Tom visual, padrão info'),
+        title: z.string().optional(),
+    }),
+})

package/src/define.ts

@@ -0,0 +1,9 @@
+import { defineComponent as defineLangComponent } from '@openuidev/lang-core'
+import type { DefinedComponent } from '@openuidev/lang-core'
+import type { z } from 'zod'
+
+export type UiComponent<T extends z.ZodObject = z.ZodObject> = DefinedComponent<T, null>
+
+export function defineUiComponent<T extends z.ZodObject>(config: { name: string, description: string, props: T }): UiComponent<T> {
+    return defineLangComponent<T, null>({ ...config, component: null })
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { actions, CopyText } from './actions'
+export { Button, Buttons } from './components/actions'
+export { Bar, BarChart } from './components/chart'
+export { Citation, FileCard, Image, Option, Question, Questions } from './components/chat'
+export { Col, Metric, Table } from './components/data'
+export { Checkbox, Form, Input, Select } from './components/form'
+export { Card, components, Stack } from './components/layout'
+export { Callout, Markdown } from './components/text'
+export { defineUiComponent } from './define'
+export type { UiComponent } from './define'
+export { componentNames, library } from './library'
+export type { UiLibrary } from './library'
+export { prompt, PROMPT_EXAMPLES } from './prompt'
+export { LIBRARY_VERSION, UI_LANG_FENCE } from './version'

package/src/library.ts

@@ -0,0 +1,64 @@
+import { createLibrary } from '@openuidev/lang-core'
+import { CopyText } from './actions'
+import { components } from './components/layout'
+
+export const library = createLibrary<null, typeof CopyText>({
+    root: 'Stack',
+    components: Object.values(components),
+    actions: [CopyText],
+    componentGroups: [
+        {
+            name: 'Layout',
+            components: ['Stack', 'Card'],
+            notes: [
+                '- root é sempre Stack. Use Card só quando houver mais de um bloco relacionado.',
+                '- direction "row" apenas para Metric ou Card lado a lado, no máximo 3.',
+            ],
+        },
+        {
+            name: 'Texto',
+            components: ['Markdown', 'Callout'],
+            notes: [
+                '- Citações cite:// e links vault:// aparecem no markdown, em Markdown/Callout, ou nos props ref de Citation e vaultRef de FileCard. Nunca em labels, títulos ou valores de tabela.',
+            ],
+        },
+        {
+            name: 'Dados',
+            components: ['Metric', 'Table', 'Col', 'BarChart', 'Bar'],
+            notes: [
+                '- Table para 3 ou mais linhas comparáveis. Menos que isso, use markdown fora do widget.',
+                '- Cada Col tem exatamente o mesmo número de values. Declare cada Col como statement próprio.',
+                '- Metric só para valores isolados e já formatados. Nunca repita um valor da tabela como Metric.',
+                '- BarChart só para valores numéricos da mesma unidade; Bar.value é número puro e Bar.display é o texto formatado.',
+            ],
+        },
+        {
+            name: 'Documentos',
+            components: ['FileCard', 'Image', 'Citation'],
+            notes: [
+                '- Use FileCard para um arquivo gerado ou recebido que o usuário deve abrir, e Image para uma imagem que deve aparecer na resposta. Nunca invente referências vault://, cite:// ou URLs.',
+            ],
+        },
+        {
+            name: 'Perguntas e formulários',
+            components: ['Questions', 'Question', 'Option', 'Form', 'Input', 'Select', 'Checkbox'],
+            notes: [
+                '- Questions quando a resposta depender de uma escolha do usuário. Pergunte o mínimo; não pergunte o que já foi dito.',
+                '- Form quando faltarem dados concretos (datas, valores, nomes). Nunca combine Form e Questions no mesmo widget.',
+                '- Depois de um Questions ou Form, encerre a resposta: não responda o que ainda depende da resposta do usuário.',
+            ],
+        },
+        {
+            name: 'Ações',
+            components: ['Buttons', 'Button'],
+            notes: [
+                '- Use Buttons para oferecer próximos passos concretos. Cada Button com @ToAssistant("mensagem") escrita na primeira pessoa, como o usuário diria.',
+                '- @CopyText("texto") para copiar um valor pronto, como um número de processo ou um trecho de petição.',
+                '- No máximo um Button com variant "primary".',
+            ],
+        },
+    ],
+})
+
+export type UiLibrary = typeof library
+export const componentNames = Object.keys(library.components) as Array<keyof typeof components>

package/src/prompt.ts

@@ -0,0 +1,54 @@
+import { library } from './library'
+import { UI_LANG_FENCE } from './version'
+
+const PREAMBLE = `## Widgets na resposta
+
+Você responde em markdown normal. Quando parte da resposta ficar melhor como interface (tabela comparativa, números de destaque, aviso, próximos passos clicáveis), insira um bloco de código com a linguagem \`${UI_LANG_FENCE}\` contendo um programa OpenUI Lang. O bloco é renderizado como interface nativa no lugar do código; o texto fora do bloco continua markdown.
+
+Regras do envelope:
+- Zero ou mais blocos \`${UI_LANG_FENCE}\` por resposta, cada um com seu próprio \`root = Stack(...)\` na primeira linha.
+- Prose, citações cite:// e links vault:// ficam no markdown fora do bloco, ou dentro de Markdown/Callout.
+- Resposta curta ou puramente textual: nenhum bloco. A maioria das respostas não precisa de widget.
+- Nunca repita no markdown o que já está no widget, nem o contrário.
+- Dentro do bloco só OpenUI Lang: sem comentários, sem markdown solto, sem fences aninhados.`
+
+export const PROMPT_EXAMPLES = [
+    [
+        'Pergunta: "compare os prazos de recurso". Resposta com widget:',
+        '',
+        'Os prazos variam por tipo de recurso:',
+        '',
+        `\`\`\`${UI_LANG_FENCE}`,
+        'root = Stack([tbl, next])',
+        'tbl = Table([tipo, prazo, base], "Prazos recursais")',
+        'tipo = Col("Recurso", ["Apelação", "Agravo", "Embargos"])',
+        'prazo = Col("Prazo", ["15 dias", "15 dias", "5 dias"], "right")',
+        'base = Col("Base legal", ["CPC art. 1.003", "CPC art. 1.003", "CPC art. 1.023"])',
+        'next = Buttons([b1, b2])',
+        'b1 = Button("Detalhar a apelação", @ToAssistant("Detalhe os requisitos da apelação"), "primary")',
+        'b2 = Button("Ver contagem em dias úteis", @ToAssistant("Como conto esses prazos em dias úteis?"))',
+        '```',
+        '',
+        'Todos contados em dias úteis [cite://doc/123#p=4].',
+    ].join('\n'),
+]
+
+let defaultPrompt: string | undefined
+
+export function prompt(options: { additionalRules?: string[] } = {}): string {
+    if (!options.additionalRules?.length)
+        return defaultPrompt ??= buildPrompt()
+    return buildPrompt(options.additionalRules)
+}
+
+function buildPrompt(additionalRules?: string[]): string {
+    return library.prompt({
+        preamble: PREAMBLE,
+        examples: PROMPT_EXAMPLES,
+        inlineMode: false,
+        toolCalls: false,
+        bindings: false,
+        builtinFunctions: false,
+        additionalRules,
+    })
+}

package/src/version.ts

@@ -0,0 +1,2 @@
+export const LIBRARY_VERSION = '0.3.0'
+export const UI_LANG_FENCE = 'openui-lang'