@seedgrid/ai-toolkit 0.0.0-stage → 0.3.1

package/seedgridKB/SeedGrid/SeedGrid-components/inputs-texto/Exemplos.md

@@ -0,0 +1,312 @@
+---
+tags: [seedgrid, component, frontend, react, inputs-texto, exemplos]
+fonte: front/seedgrid-fe-components/apps/showcase/src/app/components
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# Inputs de texto: exemplos
+
+Todos os exemplos foram conferidos contra os tipos descritos em [[SeedGrid/SeedGrid-components/inputs-texto/API|API dos inputs de texto]]. Os que vêm do showcase indicam o arquivo de origem, relativo a `front/seedgrid-fe-components/apps/showcase/src/app/components/`. Cada componente também tem página no showcase em `/components/<slug>` (campo `showcase.route` dos `*.meta.ts`). Os exemplos não foram compilados nem executados nesta análise. A conferência foi feita contra os tipos.
+
+## Configuração de idioma (recomendada)
+
+Sem provider, as mensagens saem em `en-US`, que é o padrão do i18n global. **Confirmado**.
+
+```tsx
+import { SgComponentsI18nProvider } from "@seedgrid/fe-components";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <SgComponentsI18nProvider locale="pt-BR">{children}</SgComponentsI18nProvider>;
+}
+```
+
+## SgInputText com `register`
+
+Fonte: `sg-input-text/samples/basico-rhf.tsx.sample`.
+
+```tsx
+import * as React from "react";
+import { useForm } from "react-hook-form";
+import { SgInputText } from "@seedgrid/fe-components";
+
+export default function App() {
+  const { register, watch } = useForm({ defaultValues: { nome: "" } });
+  return (
+    <>
+      <SgInputText id="demo-basic" label="Nome completo" name="nome" register={register} />
+      <p>Valor atual: {watch("nome")}</p>
+    </>
+  );
+}
+```
+
+## SgInputText com `control` e validação
+
+Baseado em `sg-input-text/samples/controlado.tsx.sample`, com `required`/`minLength` acrescentados. As props usadas estão confirmadas no tipo.
+
+```tsx
+import * as React from "react";
+import { useForm } from "react-hook-form";
+import { SgButton, SgInputText } from "@seedgrid/fe-components";
+
+export default function App() {
+  const { control, handleSubmit } = useForm({ defaultValues: { cliente: "" } });
+  return (
+    <form onSubmit={handleSubmit((data) => console.log(data))}>
+      <SgInputText
+        id="cliente"
+        label="Cliente"
+        name="cliente"
+        control={control}
+        required
+        minLength={3}
+        showCharCounter
+        maxLength={60}
+      />
+      <SgButton type="submit">Salvar</SgButton>
+    </form>
+  );
+}
+```
+
+## SgInputTextArea
+
+Fonte: `sg-input-text-area/samples/minimo-de-linhas.tsx.sample`.
+
+```tsx
+import * as React from "react";
+import { SgInputTextArea } from "@seedgrid/fe-components";
+
+export default function App() {
+  return <SgInputTextArea id="demo-minlines" label="Min 3 linhas" minLines={3} minLinesMessage="Digite ao menos 3 linhas" />;
+}
+```
+
+## SgInputTextSearch (debounce)
+
+Fonte: `sg-input-text-search/samples/minchars-e-debounce.tsx.sample`.
+
+```tsx
+import * as React from "react";
+import { SgInputTextSearch } from "@seedgrid/fe-components";
+
+export default function App() {
+  const [immediate, setImmediate] = React.useState("");
+  const [searchTerm, setSearchTerm] = React.useState("");
+  return (
+    <>
+      <SgInputTextSearch
+        id="search-tuned"
+        label="Busca"
+        placeholder="Digite para buscar"
+        minChars={1}
+        debounceMs={800}
+        onChange={setImmediate}
+        onSearchChange={setSearchTerm}
+      />
+      <p>Valor imediato (onChange): {immediate}</p>
+      <p>Termo de busca (onSearchChange): {searchTerm}</p>
+    </>
+  );
+}
+```
+
+## SgInputEmail
+
+Fonte: `sg-input-email/samples/basico.tsx.sample`. `blockedEmailDomains` foi acrescentado (prop confirmada).
+
+```tsx
+import * as React from "react";
+import { SgInputEmail } from "@seedgrid/fe-components";
+
+export default function App() {
+  return (
+    <SgInputEmail
+      id="email"
+      label="E-mail"
+      hintText="name@domain.com"
+      blockedEmailDomains={["exemplo-temporario.com"]}
+      onChange={(value) => console.log(value)}
+    />
+  );
+}
+```
+
+## SgInputPassword com política e gerador
+
+Baseado em `sg-input-password/samples/basico.tsx.sample`, com props de política acrescentadas. Observe que o `maxLength` padrão é 15, e por isso aqui ele é aumentado.
+
+```tsx
+import * as React from "react";
+import { SgInputPassword } from "@seedgrid/fe-components";
+
+export default function App() {
+  const [senha, setSenha] = React.useState("");
+  return (
+    <div className="w-80">
+      <SgInputPassword
+        id="senha"
+        label="Senha"
+        minSize={10}
+        maxLength={64}
+        specialCharacterRequired={false}
+        createNewPasswordButton
+        newPasswordLength={16}
+        onChange={setSenha}
+        onValidation={(msg) => console.log("primeira regra pendente:", msg)}
+      />
+      <p className="mt-2 text-xs">Tamanho atual: {senha.length}</p>
+    </div>
+  );
+}
+```
+
+## Documentos brasileiros
+
+Fontes: `sg-input-cpf/samples/basico.tsx.sample`, `sg-input-cnpj/samples/cnpj-publico.tsx.sample`, `sg-input-cpf-cnpj/samples/basico.tsx.sample` e `sg-input-phone/samples/basico.tsx.sample`, combinados em um formulário.
+
+```tsx
+import * as React from "react";
+import { SgInputCNPJ, SgInputCPF, SgInputCPFCNPJ, SgInputPhone } from "@seedgrid/fe-components";
+
+export default function App() {
+  return (
+    <>
+      <SgInputCPF id="cpf" label="CPF" hintText="000.000.000-00" onChange={(value) => console.log(value)} />
+      <SgInputCNPJ
+        id="cnpj"
+        label="CNPJ"
+        hintText="00.000.000/0000-00"
+        validateWithPublicaCnpj
+        publicaCnpjErrorMessage="CNPJ nao encontrado"
+        onPublicaCnpjResult={(data) => console.log(data)}
+        onPublicaCnpjError={(error) => console.log(error)}
+      />
+      <SgInputCPFCNPJ id="doc" label="CPF ou CNPJ" required />
+      <SgInputPhone id="telefone" label="Telefone" hintText="(11) 99999-0000" />
+    </>
+  );
+}
+```
+
+`validateWithPublicaCnpj` faz uma chamada HTTP real a `publica.cnpj.ws`. Em testes, passe `publicaCnpjFetch={async () => ({ ok: true })}`.
+
+## SgInputPostalCode com ViaCEP
+
+Fonte: `sg-input-postal-code/samples/viacep.tsx.sample`.
+
+```tsx
+import * as React from "react";
+import { SgInputPostalCode } from "@seedgrid/fe-components";
+
+export default function App() {
+  return (
+    <SgInputPostalCode
+      id="cep"
+      label="CEP (Brasil)"
+      hintText="00000-000"
+      country="BR"
+      validateWithViaCep
+      viaCepErrorMessage="CEP invalido."
+      onViaCepResult={(data) => console.log(data)}
+    />
+  );
+}
+```
+
+## SgInputDate e SgInputBirthDate
+
+Fontes: `sg-input-date/samples/intervalo.tsx.sample` e `sg-input-birth-date/samples/intervalo.tsx.sample`.
+
+```tsx
+import * as React from "react";
+import { SgInputBirthDate, SgInputDate } from "@seedgrid/fe-components";
+
+export default function App() {
+  return (
+    <div className="w-80">
+      <SgInputDate id="demo-range" label="Periodo" minDate="2020-01-01" maxDate="2030-12-31" />
+      <SgInputBirthDate id="demo-birth" label="Data de nascimento" minAge={12} maxAge={80} />
+    </div>
+  );
+}
+```
+
+Sempre informe `minAge` e/ou `maxAge` no `SgInputBirthDate`. Sem eles, qualquer data gera erro de configuração.
+
+## SgInputNumber e SgInputCurrency com `control`
+
+`SgInputCurrency` vem de `sg-input-currency/samples/controlado.tsx.sample`. O `SgInputNumber` foi acrescentado no mesmo formulário: os samples `basico`/`controlado` dele no showcase não têm `useForm`.
+
+```tsx
+import React from "react";
+import { useForm } from "react-hook-form";
+import { SgButton, SgGrid, SgInputCurrency, SgInputNumber } from "@seedgrid/fe-components";
+
+export default function Example() {
+  const { control, watch, setValue } = useForm({
+    defaultValues: { quantidade: "1.000", controlled: "1234.50" }
+  });
+
+  return (
+    <div className="w-96 space-y-3">
+      <SgInputNumber id="qtd" label="Quantidade" name="quantidade" control={control} decimals={3} minValue={0} allowNegative={false} />
+      <SgInputCurrency id="demo-controlled" label="Controlado" name="controlled" control={control} currency="BRL" />
+
+      <SgGrid columns={{ base: 1, sm: 3 }} gap={8}>
+        <SgButton size="sm" appearance="outline" onClick={() => setValue("controlled", "12345.00")}>Set API</SgButton>
+        <SgButton size="sm" appearance="outline" onClick={() => setValue("controlled", "0.00")}>Reset</SgButton>
+        <SgButton size="sm" appearance="outline" severity="danger" onClick={() => setValue("controlled", "")}>Limpar</SgButton>
+      </SgGrid>
+
+      <p>Estado atual: "{watch("controlled")}" / qtd "{watch("quantidade")}"</p>
+    </div>
+  );
+}
+```
+
+O valor do formulário é uma **string canônica** (`"1234.50"`). Converta com `Number(...)` ao enviar.
+
+## SgInputOTP com ref
+
+Fonte: `sg-input-otp/samples/acesso-por-ref.tsx.sample`.
+
+```tsx
+import * as React from "react";
+import { SgButton, SgGrid, SgInputOTP, type SgInputOTPRef } from "@seedgrid/fe-components";
+
+export default function App() {
+  const otpRef = React.useRef<SgInputOTPRef | null>(null);
+  const [readout, setReadout] = React.useState('Clique em "Ler conteudo".');
+
+  return (
+    <div className="space-y-3">
+      <SgInputOTP id="otp-ref" ref={otpRef} label="OTP por ref" hintText="Use os botoes abaixo" mask="###-###-99" />
+
+      <SgGrid columns={{ base: 1, sm: 3 }} gap={8}>
+        <SgButton size="sm" appearance="outline" onClick={() => otpRef.current?.focus()}>Focar</SgButton>
+        <SgButton size="sm" appearance="outline" onClick={() => otpRef.current?.clear()}>Limpar</SgButton>
+        <SgButton
+          size="sm"
+          appearance="outline"
+          onClick={() => {
+            const masked = otpRef.current?.getMaskedValue() ?? "";
+            const raw = otpRef.current?.getRawValue() ?? "";
+            setReadout(`masked="${masked || "(vazio)"}" | raw="${raw || "(vazio)"}"`);
+          }}
+        >
+          Ler conteudo
+        </SgButton>
+      </SgGrid>
+
+      <div className="rounded border border-border bg-muted/40 p-3 text-xs">
+        <strong>saida:</strong> {readout}
+      </div>
+    </div>
+  );
+}
+```
+
+`onComplete` está em `sg-input-otp/samples/colagem-on-complete.tsx.sample`: `onChange` entrega o valor mascarado, `onRawChange` o bruto e `onComplete` dispara quando todos os slots estão cheios.

package/seedgridKB/SeedGrid/SeedGrid-components/inputs-texto/Visao-geral.md

@@ -0,0 +1,123 @@
+---
+tags: [seedgrid, component, frontend, react, inputs-texto]
+fonte: front/seedgrid-fe-components/packages/seedgrid-fe-components/src/inputs
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# Inputs de texto (SgInput*)
+
+Este grupo reúne os 15 campos de digitação do pacote `@seedgrid/fe-components` (v`2026.7.1`). Todos estão em `src/inputs/` e todos são exportados pela raiz do pacote. Detalhe de props, eventos e ref: [[SeedGrid/SeedGrid-components/inputs-texto/API|API dos inputs de texto]]. Código: [[SeedGrid/SeedGrid-components/inputs-texto/Exemplos|Exemplos dos inputs de texto]]. Grupos vizinhos: [[SeedGrid/SeedGrid-components/inputs-selecao/Visao-geral|inputs de seleção]], [[SeedGrid/SeedGrid-components/datatable/Visao-geral|SgDatatable]], [[SeedGrid/SeedGrid-components/editor/Visao-geral|SgTextEditor]].
+
+## Objetivo
+
+Os componentes oferecem campos de formulário prontos, com as seguintes características comuns:
+- rótulo flutuante, no topo ou à esquerda;
+- validação embutida, com mensagens traduzidas;
+- máscaras brasileiras (CPF, CNPJ alfanumérico, telefone, CEP);
+- integração opcional com react-hook-form, por `register` ou por `control`.
+
+O padrão de nomes de eventos vem da casa: `onEnter` no foco, `onExit` no blur, `onChange(value)` com o valor já tratado e `onValidation(msg | null)`. **Confirmado**: comentários "padrao seedgrid" nos tipos.
+
+## Quando usar cada um
+
+| Componente | Use para | Base |
+|---|---|---|
+| `SgInputText` | Texto curto livre (nome, título, código). É a base dos demais. | própria |
+| `SgInputTextArea` | Texto longo multilinha, com mínimo de linhas e palavras. | própria (`<textarea>`) |
+| `SgInputTextSearch` | Caixa de busca com debounce (`onSearchChange`). | `SgInputText` |
+| `SgInputEmail` | E-mail com validação de formato e bloqueio de domínios temporários. | `SgInputText` |
+| `SgInputPassword` | Senha com política configurável, barra de força, olho e gerador. | `SgInputText` |
+| `SgInputPhone` | Telefone BR com máscara (10 ou 11 dígitos). | `SgInputText` |
+| `SgInputCPF` | CPF com máscara e dígito verificador. | `SgInputText` |
+| `SgInputCNPJ` | CNPJ numérico ou alfanumérico, com consulta pública opcional. | `SgInputText` |
+| `SgInputCPFCNPJ` | Campo único que aceita CPF ou CNPJ e detecta qual é. | `SgInputText` |
+| `SgInputPostalCode` | CEP/código postal de BR, PT, US, ES, UY, AR e PY, com ViaCEP opcional. | `SgInputText` |
+| `SgInputDate` | Data com o widget nativo (`type="date"`) e limites min/max. | `SgInputText` |
+| `SgInputBirthDate` | Data de nascimento com idade mínima/máxima. | `SgInputDate` |
+| `SgInputNumber` | Número decimal formatado pelo locale, com min/max. | própria |
+| `SgInputCurrency` | Valor monetário com símbolo via `Intl` (padrão BRL). | própria (derivada do código do `SgInputNumber`) |
+| `SgInputOTP` | Código de uso único segmentado, com máscara (`999999`, `###-###`). | própria |
+
+Para escolhas fechadas, como combos e listas, use o grupo [[SeedGrid/SeedGrid-components/inputs-selecao/Visao-geral|inputs de seleção]]. Para texto rico, use o [[SeedGrid/SeedGrid-components/editor/Visao-geral|SgTextEditor]]. Esses mesmos encaminhamentos aparecem nos `aiHints.avoidUseCases` de `SgInputText.meta.ts`. **Confirmado**.
+
+## Composição
+
+```mermaid
+graph TD
+  T[SgInputText] --> S[SgInputTextSearch]
+  T --> E[SgInputEmail]
+  T --> P[SgInputPassword]
+  T --> Ph[SgInputPhone]
+  T --> CPF[SgInputCPF]
+  T --> CNPJ[SgInputCNPJ]
+  T --> CC[SgInputCPFCNPJ]
+  T --> CEP[SgInputPostalCode]
+  T --> D[SgInputDate] --> B[SgInputBirthDate]
+  T -.também usado por.-> SEL[SgAutocomplete / SgCombobox / SgMultiSelect]
+```
+
+- Os wrappers usam `Omit<SgInputTextProps, …>`, acrescentam as próprias props e repassam o resto ao `SgInputText`. A integração com o RHF fica no `SgInputText`.
+- Cada wrapper mantém **o próprio erro interno** e o passa como `error` ao `SgInputText`, junto com o erro de `fieldState` via `resolveFieldError`. Como o `SgInputText` também valida (required/maxLength…), uma mensagem do wrapper tem precedência sobre a dele. **Confirmado**.
+- `SgInputTextArea`, `SgInputNumber`, `SgInputCurrency` e `SgInputOTP` repetem o padrão visual do `SgInputText`, mas têm implementação própria.
+
+## Dependências
+
+- **Peers obrigatórios do pacote:**
+  - `react` `^18.2.0 || ^19.0.0`;
+  - `react-hook-form` `^7.0.0`, importado estaticamente (`Controller`) pelos inputs, mesmo sem uso de formulário;
+  - `lucide-react` `^0.468.0 || ^1.0.0` (ícone `X` do botão limpar).
+
+  **Confirmado** em `package.json` e nos imports.
+- **Peers TipTap:** não são usados por este grupo, mas são carregados pela raiz do pacote. Ver [[SeedGrid/SeedGrid-components/editor/Visao-geral|SgTextEditor]].
+- **Rede:** `SgInputCNPJ` (`validateWithPublicaCnpj`) e `SgInputPostalCode` (`validateWithViaCep`) chamam `fetch` para `publica.cnpj.ws` e `viacep.com.br` por padrão. Ambos aceitam uma função de consulta própria (`publicaCnpjFetch`, `viaCepFetch`).
+- **APIs do navegador:** `SgInputPassword` usa `crypto.getRandomValues` para gerar senha.
+- **"use client":** todos os arquivos começam com `"use client"`, o que serve ao Next.js App Router.
+
+## Tema e estilos
+
+- O CSS compilado (Tailwind) é **injetado automaticamente** no `<head>` quando o pacote é importado (`ensureSeedgridStylesInjected()` em `src/injectStyles.ts`, chamado no topo de `src/index.ts`). A injeção tem proteção para SSR e para dupla injeção (id `seedgrid-fe-components-styles`). Também existe `@seedgrid/fe-components/style.css` para quem prefere importar o arquivo. **Confirmado**.
+- **Tokens:**
+  - Cores via variáveis CSS do tema: `hsl(var(--primary))`, `--destructive`, `--foreground`, `--muted`, `--border`.
+  - Variáveis específicas de input, com fallback: `--sg-input-bg`, `--sg-input-fg`, `--sg-input-placeholder`, `--sg-input-disabled-bg`, `--sg-input-disabled-fg`.
+
+  O pacote `@seedgrid/fe-theme` aparece só como devDependency. A relação exata entre ele e essas variáveis é **Inferência**.
+- **Customização:**
+  - Props: `className` (no `SgInputText` **substitui** as classes do input), `labelClassName`, `width`, `borderRadius`, `elevation`, `withBorder`, `filled`.
+  - Dark mode do `SgInputDate`: `color-scheme` via `useDarkFlag()`.
+
+## Internacionalização
+
+- **Provider:** textos padrão vêm de `useComponentsI18n()` (`src/i18n/index.ts`). Locales embutidos: `pt-BR`, `pt-PT`, `en-US` (alias `en`), `es`, `fr`.
+- **Sem provider:** vale o i18n global, que por padrão é **`en-US`**. Para trocar, use `<SgComponentsI18nProvider locale="pt-BR" messages={…}>` ou `setComponentsI18n(...)`. As mensagens passadas sobrescrevem as embutidas, chave por chave.
+- **Chaves deste grupo:** `components.inputs.*`, `components.password.*`, `components.validators.*` e `components.actions.clear`.
+- **Props `*Message`:** sempre têm precedência sobre a tradução.
+
+**Confirmado**.
+
+## Testes existentes (lidos, **não executados**)
+
+- `tests/inputs-dom.test.mjs` (jsdom) cobre:
+  - `SgInputText` controlado via `inputProps.value` e via RHF;
+  - `onChange` do `SgInputPassword` e o tamanho da senha gerada;
+  - asterisco do `SgInputPhone`;
+  - debounce, `minChars` e "distinct" do `SgInputTextSearch`.
+- `tests/inputs-i18n.test.mjs`: rótulos de acessibilidade do `SgInputOTP`.
+- `tests/rhf.test.mjs` e `tests/rhf-components-contract.test.mjs`: `resolveFieldError`, `mergeRequiredRule` e presença dos caminhos `register`/`control` no `SgInputTextArea`.
+- `tests/i18n-components-contract.test.mjs`: garante que os componentes usam `t(...)` em vez de texto fixo.
+
+O script `test` do pacote roda `pnpm run build` antes.
+
+## Limitações e pontos de atenção
+
+- `SgInputBirthDate` sem `minAge` nem `maxAge` acusa erro de configuração para qualquer data preenchida. **Confirmado**.
+- `SgInputPassword` tem `maxLength` padrão **15**. `SgInputCPF`, `SgInputCNPJ` e `SgInputCPFCNPJ` têm `maxLength` padrão 18. **Confirmado**.
+- `SgInputCPF`, `SgInputCNPJ`, `SgInputCPFCNPJ`, `SgInputPostalCode`, `SgInputDate` e `SgInputBirthDate` não repassam `required` ao `SgInputText`. Consequências:
+  - o rótulo fica sem `*`;
+  - as rules do RHF ficam sem `required` automático (a validação interna continua funcionando).
+
+  `SgInputPhone`, `SgInputEmail` e `SgInputPassword` repassam. **Confirmado** (`required={required}` só aparece nesses três).
+- O erro não é anunciado a leitores de tela no `SgInputText` (sem `aria-invalid`/`aria-describedby`). O `SgToggleSwitch` e o `SgInputOTP` fazem isso. **Confirmado**.
+- Para reagir ao foco, use `onEnter`: o `inputProps.onFocus` não é chamado pelo `SgInputText`. **Confirmado**; ver [[SeedGrid/SeedGrid-components/inputs-texto/API#Contrato base SgInputText|contrato base]].
+- Os tipos de props de `SgInputEmail`, `SgInputPassword`, `SgInputDate` e `SgInputBirthDate` não são reexportados. **Confirmado**.