redmine-context 1.0.0

package/dist/surfaces/tui/attachment-status.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Mapeamento de status de extração de anexo para a apresentação na TUI (#32).
+ *
+ * MIGRAÇÃO (M3-08): desde a #50, `src/contract.ts` — a fronteira única que as
+ * superfícies consomem do core (ADR-005) — PASSA a exportar o vocabulário
+ * canônico {@link ExtractionStatus} do pipeline de extração real. Este módulo
+ * foi então REALINHADO: {@link AttachmentExtractionStatus} agora é um ALIAS do
+ * tipo do contrato (não mais uma união local paralela), de modo que a TUI e o
+ * core compartilham exatamente os mesmos estados — incluindo o novo `skipped`
+ * (anexo pulado por exceder o limite de tamanho, ADR-002).
+ *
+ * O que AINDA é TUI-only e provisório é apenas a HEURÍSTICA
+ * {@link deriveAttachmentExtractionStatus}: enquanto a fila de jobs de extração
+ * não roda ligada à TUI, o status exibido é derivado só de
+ * `Attachment.content_type` (apresentação, sem extração de fato). Quando o core
+ * passar a entregar o `ExtractionResult` pronto por anexo (M3/M4), esta derivação
+ * deixa de existir e o status vem direto do `ExtractionResult['status']`;
+ * `attachmentStatusColor`/`attachmentStatusLabel` já operam sobre o tipo do
+ * contrato e permanecem.
+ *
+ * Valores que {@link deriveAttachmentExtractionStatus} produz HOJE:
+ * - `text` — anexo textual (content_type `text/*`), referenciado como texto-only.
+ * - `pending` — ainda não é possível classificar (ex.: `content_type` ausente
+ *   no payload do Redmine) — aguarda uma análise futura, não é erro.
+ * - `unsupported` — anexo binário conhecido (imagem/PDF/áudio/vídeo) para o
+ *   qual não há extrator disponível na TUI ainda.
+ *
+ * Valores restantes do vocabulário (produzidos pelo core real em M3/M4; o
+ * layout de badge já os suporta): `processing` (extração em andamento), `done`
+ * (texto extraído com sucesso), `failed` (extração falhou) e `skipped` (pulado
+ * deliberadamente, ex.: limite de tamanho).
+ */
+import type { Attachment, ExtractionStatus } from '../../index.js';
+import type { Theme } from './theme.js';
+/**
+ * Vocabulário de status de extração consumido pela TUI — ALIAS de
+ * {@link ExtractionStatus} do contrato (ADR-005), garantindo alinhamento total
+ * entre a apresentação e o core. Ver o JSDoc do módulo para a migração.
+ */
+export type AttachmentExtractionStatus = ExtractionStatus;
+/**
+ * Deriva o {@link AttachmentExtractionStatus} de um anexo — heurística de
+ * apresentação a partir SOMENTE do `content_type` (sem extração de fato na tela de
+ * detalhe). Produz `text` (texto puro), `pending` (extraível: imagem/PDF/áudio/
+ * vídeo/OOXML — o texto sai com `--extract`) ou `unsupported` (sem extrator: ex.:
+ * Office binário antigo `.doc`, executáveis, tipos desconhecidos).
+ *
+ * @param attachment - Recorte do anexo com o único campo relevante aqui.
+ * @returns O status derivado.
+ * @example
+ * deriveAttachmentExtractionStatus({ content_type: 'text/plain' })       // 'text'
+ * deriveAttachmentExtractionStatus({ content_type: 'application/pdf' })   // 'pending'
+ * deriveAttachmentExtractionStatus({ content_type: 'image/png' })        // 'pending'
+ * deriveAttachmentExtractionStatus({ content_type: 'application/x-msdownload' }) // 'unsupported'
+ */
+export declare function deriveAttachmentExtractionStatus(attachment: Pick<Attachment, 'content_type'>): AttachmentExtractionStatus;
+/**
+ * Cor (token do tema) do badge de status — nunca uma cor literal (varredura
+ * anti-hardcode, `tests/surfaces/tui/no-hardcoded-colors.test.ts`).
+ *
+ * Guideline fixado nesta issue: `muted` = pending/processing (neutro, nada
+ * acionável ainda), `primary` = text (já disponível, identidade), `warning` =
+ * unsupported (limitação atual, não é erro do usuário), `success`/`danger` =
+ * reservados para done/failed (M3/M4) — nunca usados por
+ * {@link deriveAttachmentExtractionStatus} hoje.
+ *
+ * @param theme - Tema ativo (via `useTheme()` no chamador).
+ * @param status - Status de extração do anexo.
+ * @returns O token de cor do tema.
+ */
+export declare function attachmentStatusColor(theme: Theme, status: AttachmentExtractionStatus): string;
+/**
+ * Rótulo textual (pt-BR) do badge de status, exibido ao lado do nome/tamanho
+ * do anexo.
+ *
+ * @param status - Status de extração do anexo.
+ * @returns O rótulo a exibir dentro do badge (ex.: `[texto]`).
+ */
+export declare function attachmentStatusLabel(status: AttachmentExtractionStatus): string;

package/dist/surfaces/tui/attachment-status.js

@@ -0,0 +1,113 @@
+/** Prefixo de `content_type` considerado texto puro (extraível sem OCR/ASR). */
+const TEXT_CONTENT_TYPE_PREFIX = 'text/';
+/**
+ * `content_type` (ou prefixo) com EXTRATOR disponível no pipeline hoje (imagem via
+ * tesseract; PDF via pdftotext; áudio/vídeo via whisper+ffmpeg; OOXML docx/xlsx/pptx
+ * puro-JS). Esses anexos são `pending` (extraíveis; o texto sai com `--extract` /
+ * `get_attachment_text`), NÃO `unsupported`. A decisão FINAL é por magic bytes na
+ * extração — aqui é só a apresentação a partir do `content_type` do Redmine, então
+ * `application/zip` e `application/octet-stream` (genéricos) entram como pending e o
+ * magic decide de verdade.
+ */
+function isExtractableContentType(contentType) {
+    return (contentType.startsWith('image/') ||
+        contentType.startsWith('audio/') ||
+        contentType.startsWith('video/') ||
+        contentType === 'application/pdf' ||
+        contentType === 'application/zip' ||
+        contentType.startsWith('application/vnd.openxmlformats-officedocument.') ||
+        contentType === 'application/octet-stream');
+}
+/**
+ * Deriva o {@link AttachmentExtractionStatus} de um anexo — heurística de
+ * apresentação a partir SOMENTE do `content_type` (sem extração de fato na tela de
+ * detalhe). Produz `text` (texto puro), `pending` (extraível: imagem/PDF/áudio/
+ * vídeo/OOXML — o texto sai com `--extract`) ou `unsupported` (sem extrator: ex.:
+ * Office binário antigo `.doc`, executáveis, tipos desconhecidos).
+ *
+ * @param attachment - Recorte do anexo com o único campo relevante aqui.
+ * @returns O status derivado.
+ * @example
+ * deriveAttachmentExtractionStatus({ content_type: 'text/plain' })       // 'text'
+ * deriveAttachmentExtractionStatus({ content_type: 'application/pdf' })   // 'pending'
+ * deriveAttachmentExtractionStatus({ content_type: 'image/png' })        // 'pending'
+ * deriveAttachmentExtractionStatus({ content_type: 'application/x-msdownload' }) // 'unsupported'
+ */
+export function deriveAttachmentExtractionStatus(attachment) {
+    const { content_type: contentType } = attachment;
+    if (contentType === undefined)
+        return 'pending';
+    if (contentType.startsWith(TEXT_CONTENT_TYPE_PREFIX))
+        return 'text';
+    if (isExtractableContentType(contentType))
+        return 'pending';
+    return 'unsupported';
+}
+/**
+ * Cor (token do tema) do badge de status — nunca uma cor literal (varredura
+ * anti-hardcode, `tests/surfaces/tui/no-hardcoded-colors.test.ts`).
+ *
+ * Guideline fixado nesta issue: `muted` = pending/processing (neutro, nada
+ * acionável ainda), `primary` = text (já disponível, identidade), `warning` =
+ * unsupported (limitação atual, não é erro do usuário), `success`/`danger` =
+ * reservados para done/failed (M3/M4) — nunca usados por
+ * {@link deriveAttachmentExtractionStatus} hoje.
+ *
+ * @param theme - Tema ativo (via `useTheme()` no chamador).
+ * @param status - Status de extração do anexo.
+ * @returns O token de cor do tema.
+ */
+export function attachmentStatusColor(theme, status) {
+    switch (status) {
+        case 'text':
+            return theme.primary;
+        case 'unsupported':
+            return theme.warning;
+        case 'done':
+            return theme.success;
+        case 'failed':
+            return theme.danger;
+        case 'pending':
+        case 'processing':
+        case 'skipped':
+        case 'cancelled':
+            return theme.muted;
+        default: {
+            // Exaustividade: se a união ganhar um novo membro sem atualizar este
+            // switch, o typecheck falha aqui (nunca em runtime).
+            const exhaustiveCheck = status;
+            return exhaustiveCheck;
+        }
+    }
+}
+/**
+ * Rótulo textual (pt-BR) do badge de status, exibido ao lado do nome/tamanho
+ * do anexo.
+ *
+ * @param status - Status de extração do anexo.
+ * @returns O rótulo a exibir dentro do badge (ex.: `[texto]`).
+ */
+export function attachmentStatusLabel(status) {
+    switch (status) {
+        case 'text':
+            return 'texto';
+        case 'pending':
+            return 'pendente';
+        case 'unsupported':
+            return 'não suportado';
+        case 'processing':
+            return 'processando';
+        case 'done':
+            return 'concluído';
+        case 'failed':
+            return 'falhou';
+        case 'skipped':
+            return 'pulado';
+        case 'cancelled':
+            return 'cancelado';
+        default: {
+            const exhaustiveCheck = status;
+            return exhaustiveCheck;
+        }
+    }
+}

package/dist/surfaces/tui/components/breadcrumb.d.ts

@@ -0,0 +1,7 @@
+import { type ScreenName } from '../screen.js';
+export interface BreadcrumbProps {
+    /** Pilha de telas navegadas (base -> topo) — o topo é a tela atual. */
+    stack: readonly ScreenName[];
+}
+/** Breadcrumb fixo no topo do app: título da tela atual em destaque, caminho anterior discreto. */
+export declare function Breadcrumb({ stack }: BreadcrumbProps): import("react").JSX.Element;

package/dist/surfaces/tui/components/breadcrumb.js

@@ -0,0 +1,31 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Breadcrumb fixo da TUI (M2-04) — reflete a PILHA de telas do roteador
+ * (`../navigation.tsx`) como "Início › Atalhos". Primeiro componente
+ * compartilhado da TUI (`components/`): puramente apresentacional — recebe
+ * a pilha via prop em vez de ler o contexto de navegação diretamente, para
+ * poder ser testado isolado (sem `NavigationProvider`, só `ThemeProvider`).
+ *
+ * Estética: tela atual em `primary` (negrito), telas anteriores em `muted`,
+ * separadas pelo símbolo de navegação de `../symbols.ts` (nunca hardcoded);
+ * uma borda inferior discreta em `theme.border` fecha a barra sem competir
+ * com o conteúdo da tela abaixo.
+ */
+import { Box, Text } from 'ink';
+import { SCREENS } from '../screen.js';
+import { symbols } from '../symbols.js';
+import { useTheme } from '../theme.js';
+/** Breadcrumb fixo no topo do app: título da tela atual em destaque, caminho anterior discreto. */
+export function Breadcrumb({ stack }) {
+    const theme = useTheme();
+    const lastIndex = stack.length - 1;
+    const segments = [];
+    stack.forEach((name, index) => {
+        const isCurrent = index === lastIndex;
+        if (index > 0) {
+            segments.push(_jsxs(Text, { color: theme.muted, children: [' ', symbols.pointerSmall, ' '] }, `separator-${index}`));
+        }
+        segments.push(_jsx(Text, { color: isCurrent ? theme.primary : theme.muted, children: SCREENS[name].title }, `title-${index}`));
+    });
+    return (_jsx(Box, { paddingX: 1, marginBottom: 1, borderStyle: "single", borderTop: false, borderLeft: false, borderRight: false, borderBottomColor: theme.border, children: segments }));
+}

package/dist/surfaces/tui/components/gradient-text.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Gera `steps` cores interpolando linearmente ao longo da ramp `colors`.
+ *
+ * @param colors - Paradas de cor (hex).
+ * @param steps - Quantidade de cores a produzir (ex.: nº de caracteres).
+ * @returns Uma cor hex por passo (vazio se `steps <= 0`).
+ */
+export declare function rampColors(colors: readonly string[], steps: number): string[];
+/**
+ * Renderiza `children` (texto) com um gradiente ao longo de `colors`.
+ *
+ * @param props.children - Texto a colorir.
+ * @param props.colors - Ramp de cores (hex); vazia ⇒ sem cor.
+ * @param props.bold - Negrito (default `false`, #190). Em alguns terminais
+ *   (ex.: Terminal.app do macOS) o atributo BOLD ignora o fg truecolor e
+ *   renderiza "preto", ilegível sobre o bg escuro do OSC — por isso o padrão
+ *   é sem negrito; o destaque do gradiente já vem da própria ramp de cores.
+ */
+export declare function GradientText({ children, colors, bold, }: {
+    children: string;
+    colors: readonly string[];
+    bold?: boolean;
+}): import("react").JSX.Element;

package/dist/surfaces/tui/components/gradient-text.js

@@ -0,0 +1,75 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Texto com GRADIENTE de cores (#190) — zero-dependência (não usa `ink-gradient`).
+ *
+ * Recebe um texto e uma ramp de cores (hex) e pinta cada caractere interpolando
+ * linearmente entre as paradas da ramp. Usado em títulos/destaques para dar o
+ * "muitas cores maneiras" sem depender de biblioteca nova. As cores vêm do tema
+ * (`theme.gradient`), então nenhuma cor literal aparece nas telas (varredura
+ * anti-hardcode) — este componente recebe a ramp como prop (variável).
+ *
+ * Degrada com elegância: ramp vazia ⇒ texto sem cor; 1 cor ⇒ texto sólido.
+ */
+import { Text } from 'ink';
+/** Converte `#rgb`/`#rrggbb` em `[r,g,b]` (0-255); `undefined` se inválido. */
+function hexToRgb(hex) {
+    const m = /^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.exec(hex.trim());
+    if (m === null)
+        return undefined;
+    let h = m[1];
+    if (h.length === 3)
+        h = h.replace(/(.)/g, '$1$1'); // #abc → #aabbcc
+    const n = Number.parseInt(h, 16);
+    return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
+}
+/** Converte `[r,g,b]` em `#rrggbb`. */
+function rgbToHex([r, g, b]) {
+    const to2 = (v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0');
+    return `#${to2(r)}${to2(g)}${to2(b)}`;
+}
+/**
+ * Gera `steps` cores interpolando linearmente ao longo da ramp `colors`.
+ *
+ * @param colors - Paradas de cor (hex).
+ * @param steps - Quantidade de cores a produzir (ex.: nº de caracteres).
+ * @returns Uma cor hex por passo (vazio se `steps <= 0`).
+ */
+export function rampColors(colors, steps) {
+    if (steps <= 0)
+        return [];
+    const stops = colors.map(hexToRgb).filter((c) => c !== undefined);
+    if (stops.length === 0)
+        return [];
+    if (stops.length === 1 || steps === 1) {
+        return Array.from({ length: steps }, () => rgbToHex(stops[0]));
+    }
+    const out = [];
+    for (let i = 0; i < steps; i += 1) {
+        const t = (i / (steps - 1)) * (stops.length - 1); // posição na ramp [0, stops-1]
+        const lo = Math.floor(t);
+        const hi = Math.min(lo + 1, stops.length - 1);
+        const f = t - lo;
+        const a = stops[lo];
+        const b = stops[hi];
+        out.push(rgbToHex([a[0] + (b[0] - a[0]) * f, a[1] + (b[1] - a[1]) * f, a[2] + (b[2] - a[2]) * f]));
+    }
+    return out;
+}
+/**
+ * Renderiza `children` (texto) com um gradiente ao longo de `colors`.
+ *
+ * @param props.children - Texto a colorir.
+ * @param props.colors - Ramp de cores (hex); vazia ⇒ sem cor.
+ * @param props.bold - Negrito (default `false`, #190). Em alguns terminais
+ *   (ex.: Terminal.app do macOS) o atributo BOLD ignora o fg truecolor e
+ *   renderiza "preto", ilegível sobre o bg escuro do OSC — por isso o padrão
+ *   é sem negrito; o destaque do gradiente já vem da própria ramp de cores.
+ */
+export function GradientText({ children, colors, bold = false, }) {
+    const chars = [...children];
+    const ramp = rampColors(colors, chars.length);
+    if (ramp.length === 0) {
+        return _jsx(Text, { bold: bold, children: children });
+    }
+    return (_jsx(Text, { bold: bold, children: chars.map((ch, i) => (_jsx(Text, { color: ramp[i], children: ch }, i))) }));
+}

package/dist/surfaces/tui/components/scroll-view.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from 'react';
+/** Props do `ScrollView`. */
+export interface ScrollViewProps {
+    /**
+     * Linhas de conteúdo, uma por posição — cada item já é o elemento completo
+     * da linha (ex.: `<Text key={...}>...</Text>`), COM `key` próprio (o
+     * componente as renderiza diretamente, sem reatribuir chaves).
+     */
+    lines: ReactNode[];
+    /** Altura da janela visível, em linhas. */
+    height: number;
+    /**
+     * Desativa a captura de teclado desta viewport (ex.: um overlay/modal por
+     * cima está ativo). Default `true`.
+     */
+    isActive?: boolean;
+}
+/**
+ * Viewport rolável de `height` linhas sobre `lines`. Ver o JSDoc do módulo
+ * para o contrato completo de teclado/props.
+ *
+ * @example
+ * <ScrollView lines={rows} height={10} />
+ */
+export declare function ScrollView({ lines, height, isActive }: ScrollViewProps): import("react").JSX.Element;

package/dist/surfaces/tui/components/scroll-view.js

@@ -0,0 +1,77 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Viewport rolável genérico (#31): janela de `height` linhas sobre um array
+ * `lines` potencialmente maior, sem quebrar o layout da tela que o usa (a
+ * altura ocupada na tela é sempre `height`, mesmo perto do fim do conteúdo).
+ *
+ * Extraído como componente próprio (em vez de embutido em
+ * `../screens/issue-detail.tsx`) porque a mecânica de rolagem — deslocar um
+ * `offset` sobre um array já "achatado" em linhas, com wrap NÃO permitido
+ * (ao contrário de `../hooks/use-list-navigation.ts`, que dá a volta nas
+ * pontas) — é genérica o suficiente para qualquer tela futura com conteúdo
+ * maior que a viewport (a #31 é a primeira consumidora: descrição + journals
+ * da issue).
+ *
+ * Teclado: `j`/seta para baixo desce 1 linha, `k`/seta para cima sobe 1
+ * linha, `PageDown`/`PageUp` deslocam uma página inteira (`height` linhas) de
+ * uma vez. Nas duas pontas o `offset` apenas CLAMPA (não há wrap — rolar
+ * "além" do topo/fundo não faz sentido para uma leitura linear de texto).
+ *
+ * `lines` já deve conter os elementos PRONTOS (tipicamente `<Text key=.../>`
+ * ou `<Box key=.../>`) — o componente só decide QUAIS `height` delas mostrar
+ * a cada momento; formatação/estilo de cada linha é responsabilidade de quem
+ * monta o array (ver `../screens/issue-detail.tsx`).
+ */
+import { Box, Text, useInput } from 'ink';
+import { useEffect, useState } from 'react';
+import { symbols } from '../symbols.js';
+import { useTheme } from '../theme.js';
+/** Clampa `offset` para `[0, maxOffset]` — sem wrap (ver o JSDoc do módulo). */
+function clampOffset(offset, maxOffset) {
+    if (maxOffset <= 0)
+        return 0;
+    if (offset < 0)
+        return 0;
+    if (offset > maxOffset)
+        return maxOffset;
+    return offset;
+}
+/**
+ * Viewport rolável de `height` linhas sobre `lines`. Ver o JSDoc do módulo
+ * para o contrato completo de teclado/props.
+ *
+ * @example
+ * <ScrollView lines={rows} height={10} />
+ */
+export function ScrollView({ lines, height, isActive = true }) {
+    const theme = useTheme();
+    const maxOffset = Math.max(lines.length - height, 0);
+    const [offset, setOffset] = useState(0);
+    // Reclampa quando o conteúdo muda de tamanho (ex.: issue recarregada via
+    // retry) para não deixar a janela apontando além do novo fim.
+    useEffect(() => {
+        setOffset((current) => clampOffset(current, maxOffset));
+    }, [maxOffset]);
+    useInput((input, key) => {
+        if (key.pageDown) {
+            setOffset((current) => clampOffset(current + height, maxOffset));
+            return;
+        }
+        if (key.pageUp) {
+            setOffset((current) => clampOffset(current - height, maxOffset));
+            return;
+        }
+        if (key.downArrow || input === 'j') {
+            setOffset((current) => clampOffset(current + 1, maxOffset));
+            return;
+        }
+        if (key.upArrow || input === 'k') {
+            setOffset((current) => clampOffset(current - 1, maxOffset));
+        }
+    }, { isActive });
+    const visible = lines.slice(offset, offset + height);
+    const canScroll = lines.length > height;
+    const atTop = offset <= 0;
+    const atBottom = offset >= maxOffset;
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { flexDirection: "column", height: height, children: visible }), canScroll ? (_jsx(Box, { children: _jsxs(Text, { color: theme.muted, children: [atTop ? ' ' : symbols.arrowUp, " ", offset + 1, "-", offset + visible.length, "/", lines.length, ' ', atBottom ? ' ' : symbols.arrowDown] }) })) : null] }));
+}

package/dist/surfaces/tui/components/spinner.d.ts

@@ -0,0 +1,12 @@
+/** Sequência de frames do spinner — um giro completo por volta do array (ASCII no Windows legado). */
+export declare const SPINNER_FRAMES: readonly string[];
+/** Intervalo (ms) entre frames — rápido o bastante para parecer fluido, sem sobrecarregar o terminal. */
+export declare const SPINNER_INTERVAL_MS = 80;
+/**
+ * Spinner animado em `theme.primary` — usado inline junto de um rótulo (ex.:
+ * `<Text><Spinner /> Validando credenciais...</Text>`).
+ *
+ * @example
+ * <Text color={theme.primary}><Spinner /> Validando...</Text>
+ */
+export declare function Spinner(): import("react").JSX.Element;

package/dist/surfaces/tui/components/spinner.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Spinner de terminal (#28) — indicador de "operação em andamento" para as
+ * telas assíncronas do onboarding (`../screens/onboarding/validating.tsx`,
+ * `../screens/onboarding/api-key.tsx`). Implementação própria, sem depender
+ * de `@inkjs/ui` (ver `../theme.tsx`, mapeamento previsto): frames braille
+ * (mesmo conjunto usado por spinners de terminal populares), avançados por um
+ * `setInterval` simples.
+ *
+ * HARDENING WINDOWS LEGADO (M5-09, #84): os frames vêm de `../glyphs.ts`, que
+ * degrada os braille para um spinner ASCII (`| / - \`) no terminal legado do
+ * Windows — do contrário apareceriam como mojibake.
+ */
+import { useEffect, useState } from 'react';
+import { Text } from 'ink';
+import { glyphs } from '../glyphs.js';
+import { useTheme } from '../theme.js';
+/** Sequência de frames do spinner — um giro completo por volta do array (ASCII no Windows legado). */
+export const SPINNER_FRAMES = glyphs.spinnerFrames;
+/** Intervalo (ms) entre frames — rápido o bastante para parecer fluido, sem sobrecarregar o terminal. */
+export const SPINNER_INTERVAL_MS = 80;
+/**
+ * Spinner animado em `theme.primary` — usado inline junto de um rótulo (ex.:
+ * `<Text><Spinner /> Validando credenciais...</Text>`).
+ *
+ * @example
+ * <Text color={theme.primary}><Spinner /> Validando...</Text>
+ */
+export function Spinner() {
+    const theme = useTheme();
+    const [frameIndex, setFrameIndex] = useState(0);
+    useEffect(() => {
+        const timer = setInterval(() => {
+            setFrameIndex((current) => (current + 1) % SPINNER_FRAMES.length);
+        }, SPINNER_INTERVAL_MS);
+        return () => clearInterval(timer);
+    }, []);
+    return _jsx(Text, { color: theme.primary, children: SPINNER_FRAMES[frameIndex] });
+}

package/dist/surfaces/tui/components/text-input.d.ts

@@ -0,0 +1,45 @@
+/** Props do `TextInput` — ver guideline de uso na documentação do arquivo. */
+export interface TextInputProps {
+    /** Valor atual — controlado pelo componente pai (ex.: `useOnboarding().url`). */
+    value: string;
+    /** Chamado a cada tecla que altera o valor (digitação, backspace/delete). */
+    onChange: (value: string) => void;
+    /** Chamado quando o usuário confirma com Enter. Opcional. */
+    onSubmit?: (value: string) => void;
+    /**
+     * Caractere de máscara — quando definido, o valor real NUNCA é
+     * renderizado; a tela mostra `mask` repetido pelo comprimento do valor.
+     * Omitido: eco normal (comportamento padrão).
+     */
+    mask?: string;
+    /** Texto exibido (em `theme.muted`) quando `value` está vazio. */
+    placeholder?: string;
+    /** Captura teclado quando `true` (default). Ver guideline de foco acima. */
+    isActive?: boolean;
+    /**
+     * Caracteres reservados por uma tecla de CONTROLE da tela pai (ex.: `f`
+     * cicla o filtro de status na busca da home, M2-07/#30) — quando o `input`
+     * recebido for EXATAMENTE um desses (tecla única, não uma sequência
+     * colada com mais de um caractere), o `TextInput` ignora e NÃO chama
+     * `onChange`. A tela pai continua recebendo o mesmo evento normalmente
+     * (Ink despacha para todos os `useInput()` registrados, não só este) e
+     * decide o que fazer com ele — este campo só evita que a tecla de controle
+     * também vire texto digitado. Default: nenhum caractere reservado.
+     */
+    reservedChars?: readonly string[];
+    /**
+     * Largura máxima (colunas) do texto EXIBIDO — trunca `value`/`placeholder`
+     * quando excedida (ver o JSDoc do módulo). Omitido: sem truncamento (uso
+     * padrão, campo sozinho na própria linha).
+     */
+    maxWidth?: number;
+}
+/**
+ * Input de texto de linha única com eco normal ou mascarado.
+ *
+ * @example
+ * <TextInput value={url} onChange={setUrl} onSubmit={handleSubmit} placeholder="https://redmine.example" />
+ * @example
+ * <TextInput value={password} onChange={setPassword} mask="•" isActive={field === 'password'} />
+ */
+export declare function TextInput({ value, onChange, onSubmit, mask, placeholder, isActive, reservedChars, maxWidth, }: TextInputProps): import("react").JSX.Element;

package/dist/surfaces/tui/components/text-input.js

@@ -0,0 +1,114 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Input de texto de linha única, Ink puro (M2-05.1, issue #27) — sem
+ * depender do `@inkjs/ui` ainda (ver `../theme.tsx`, mapeamento previsto
+ * para quando a primeira tela adotar a lib). Cobre o necessário para as
+ * telas de onboarding: eco normal (URL, usuário) e eco mascarado (senha,
+ * `mask="•"`) — com `mask` definido, o valor real NUNCA é ecoado na tela,
+ * só o caractere de máscara repetido pelo comprimento do valor.
+ *
+ * Suporta apenas edição no fim da string (sem mover o cursor pelo meio) —
+ * suficiente para os campos de onboarding (URL, usuário, senha); um cursor
+ * navegável fica para quando alguma tela precisar editar no meio do texto.
+ *
+ * `isActive` (default `true`) desliga a captura de teclado deste input
+ * específico — necessário quando mais de um campo divide a mesma tela (ex.:
+ * `../screens/onboarding/login.tsx`, usuário + senha): o `useInput()` do
+ * Ink não tem noção de foco, então cada `TextInput` "inativo" precisa
+ * ignorar o teclado, senão a mesma tecla digitaria nos dois campos ao mesmo
+ * tempo.
+ *
+ * `maxWidth` (M2-16, #39, opcional) trunca o TEXTO EXIBIDO (nunca o `value`
+ * de verdade, que segue completo para `onChange`/`onSubmit`) quando este
+ * campo divide uma linha com outro elemento (ex.: um rótulo, ver
+ * `../screens/export.tsx`) — sem isso, um valor comprido (ex.: um caminho de
+ * destino) sobrepõe o rótulo vizinho (o Ink não reflui `<Text>` IRMÃS dentro
+ * de um `<Box>` em linha; ver o JSDoc de `../truncate.ts`). O corte é a
+ * partir do INÍCIO (`truncateStart`) — o usuário digita/edita no FIM da
+ * string (ver o JSDoc do módulo acima), então é o fim que precisa continuar
+ * visível.
+ */
+import { useCallback, useRef } from 'react';
+import { Text, useInput } from 'ink';
+import { useTheme } from '../theme.js';
+import { truncate, truncateStart } from '../truncate.js';
+/**
+ * Input de texto de linha única com eco normal ou mascarado.
+ *
+ * @example
+ * <TextInput value={url} onChange={setUrl} onSubmit={handleSubmit} placeholder="https://redmine.example" />
+ * @example
+ * <TextInput value={password} onChange={setPassword} mask="•" isActive={field === 'password'} />
+ */
+export function TextInput({ value, onChange, onSubmit, mask, placeholder, isActive = true, reservedChars = [], maxWidth, }) {
+    const theme = useTheme();
+    // O handler do useInput pode disparar antes do resubscribe pós-commit do
+    // Ink (ex.: colar "url\n" entrega texto e Enter no mesmo lote) — closures
+    // capturariam o value da renderização anterior e o submit sairia vazio.
+    // Refs sempre apontam para a versão corrente.
+    const valueRef = useRef(value);
+    valueRef.current = value;
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    const onSubmitRef = useRef(onSubmit);
+    onSubmitRef.current = onSubmit;
+    const reservedCharsRef = useRef(reservedChars);
+    reservedCharsRef.current = reservedChars;
+    // Handler ESTÁVEL (useCallback + refs): identidade nova a cada render faz o
+    // useInput des/re-subscrever no efeito pós-commit, abrindo janelas sem
+    // listener onde teclas rápidas (ou lote colado) se perdem.
+    const handleInput = useCallback((input, key) => {
+        if (key.return) {
+            onSubmitRef.current?.(valueRef.current);
+            return;
+        }
+        // Reason: teclas de navegação/controle não devem virar caracteres no
+        // valor — Esc/Tab/setas são atalhos de outras camadas (roteador
+        // global, troca de campo do formulário pai); Ctrl/Meta evitam
+        // capturar sequências de atalho (ex.: Ctrl+C) como texto digitado.
+        if (key.escape ||
+            key.tab ||
+            key.upArrow ||
+            key.downArrow ||
+            key.leftArrow ||
+            key.rightArrow ||
+            key.pageUp ||
+            key.pageDown ||
+            key.ctrl ||
+            key.meta) {
+            return;
+        }
+        if (key.backspace || key.delete) {
+            onChangeRef.current(valueRef.current.slice(0, -1));
+            return;
+        }
+        // Reason: tecla ÚNICA reservada por um controle da tela pai (ex.: "f"
+        // cicla o filtro de status na busca da home, M2-07/#30) — ignorada
+        // aqui para não virar texto digitado; a tela pai trata o mesmo evento
+        // via seu próprio `useInput()`. Só bloqueia o caractere isolado, não
+        // uma sequência colada maior que o contenha.
+        if (reservedCharsRef.current.includes(input)) {
+            return;
+        }
+        if (input.length > 0) {
+            onChangeRef.current(valueRef.current + input);
+        }
+    }, []);
+    useInput(handleInput, { isActive });
+    // Reason: cursor em bloco simples (inversão de cor, sem literal — não
+    // conta como cor hardcoded) só quando o campo está ativo, reforçando
+    // visualmente qual campo recebe o próximo caractere digitado.
+    const cursor = isActive ? _jsx(Text, { inverse: true, children: " " }) : null;
+    // Reserva 1 coluna para o cursor quando ativo — sem isso, o texto truncado
+    // + cursor poderia exceder `maxWidth` por 1 caractere.
+    const budget = maxWidth !== undefined ? Math.max(maxWidth - (isActive ? 1 : 0), 1) : undefined;
+    if (value.length === 0 && placeholder !== undefined) {
+        const shownPlaceholder = budget !== undefined ? truncate(placeholder, budget) : placeholder;
+        return (_jsxs(Text, { children: [_jsx(Text, { color: theme.muted, children: shownPlaceholder }), cursor] }));
+    }
+    const displayValue = mask !== undefined ? mask.repeat(value.length) : value;
+    // truncateStart (não truncate): o usuário edita no FIM da string — é o
+    // fim que precisa continuar visível, ver o JSDoc do módulo.
+    const shownValue = budget !== undefined ? truncateStart(displayValue, budget) : displayValue;
+    return (_jsxs(Text, { children: [shownValue, cursor] }));
+}