@arqel-dev/ai 0.8.0

package/dist/index.d.ts

@@ -0,0 +1,268 @@
+import { ReactElement } from 'react';
+
+/**
+ * `<AiExtractInput>` — apresentational React component for the PHP
+ * `Arqel\Ai\Fields\AiExtractField` (component string `AiExtractInput`).
+ *
+ * Render contract (AI-010):
+ *   - Read-only label `Source: {sourceField}` indicando o campo do
+ *     formulário de onde o texto-fonte é lido.
+ *   - Botão `Extract with AI` (label vem de `props.buttonLabel`); em
+ *     loading o botão fica `disabled` + spinner inline.
+ *   - Empty state `No extraction yet — click button to start` antes da
+ *     primeira extração.
+ *   - Após sucesso: lista preview `<dl>` com cada `targetField:
+ *     extractedValue`; cada entry tem botão `Apply` individual e o
+ *     toolbar mostra `Apply all`.
+ *   - `Apply` chama `onPopulateField?.(targetField, value)` ou
+ *     `onChange(extracted)` se `onPopulateField` for ausente.
+ *   - Banner `role="alert"` quando o `fetch` falha (com `message` da
+ *     response 422 quando disponível).
+ *
+ * Network:
+ *   - URL = `props.extractUrl` override ou
+ *     `/admin/${resource}/fields/${field}/extract`.
+ *   - Body: `{ sourceText }` lido de `formData?.[sourceField] ?? ''`.
+ *   - Resposta: `{ extracted: Record<string, unknown> }` (200) ou
+ *     `{ message }` (422).
+ *
+ * SSR-safe: nada no render path toca `window`/`document`.
+ */
+
+interface AiExtractInputFieldProps {
+    sourceField: string;
+    targetFields: string[];
+    buttonLabel: string;
+    usingJsonMode: boolean;
+    provider?: string | null;
+}
+type AiExtractValue = Record<string, unknown>;
+interface AiExtractInputProps {
+    name: string;
+    value: AiExtractValue | null;
+    onChange?: (value: AiExtractValue) => void;
+    props: AiExtractInputFieldProps | undefined;
+    resource?: string;
+    field?: string;
+    formData?: Record<string, unknown>;
+    extractUrl?: string;
+    csrfToken?: string;
+    onPopulateField?: (targetField: string, value: unknown) => void;
+}
+declare function AiExtractInput(props: AiExtractInputProps): ReactElement;
+
+/**
+ * `<AiImageInput>` — apresentational React component for the PHP
+ * `Arqel\Ai\Fields\AiImageField` (component string `AiImageInput`).
+ *
+ * Render contract (AI-011):
+ *   - File input restrito por `accept={props.acceptedMimes.join(',')}`
+ *     com drag-drop area visual (`<label>` clicável que dispara o
+ *     `<input type="file">` escondido).
+ *   - Preview da imagem após selecionar (img src vem de
+ *     `URL.createObjectURL` — só é chamado dentro do change handler,
+ *     mantendo o render path SSR-safe).
+ *   - Validação client-side: rejeita arquivos > `props.maxFileSize`
+ *     (em bytes) com banner de erro; nesse caso o botão "Analyze with
+ *     AI" fica `disabled`.
+ *   - Botão `Analyze with AI` (label de `props.buttonLabel`); spinner
+ *     inline + `disabled` durante o `fetch`. Sem arquivo selecionado o
+ *     botão também fica `disabled`.
+ *   - Após sucesso: lista preview `<dl>` com `analysis_key: value` por
+ *     entry; cada entry tem botão `Apply` individual; toolbar mostra
+ *     `Apply all`.
+ *   - `Apply` chama `onPopulateField?.(target, value)` usando o
+ *     mapeamento `props.populateFields[analysisKey]` quando disponível.
+ *     `Apply all` itera todas as analyses que têm mapping.
+ *   - Banner `role="alert"` quando o `fetch` falha (mensagem da
+ *     response 422 quando disponível).
+ *
+ * Network:
+ *   - URL = `props.analyzeUrl` override ou
+ *     `/admin/${resource}/fields/${field}/analyze-image`.
+ *   - Body: `{ imageBase64 }` produzido por `FileReader.readAsDataURL`
+ *     (data URI completo).
+ *   - Resposta: `{ analyses, populateMapping }` (200) ou
+ *     `{ message }` (422).
+ *
+ * SSR-safe: nada no render path toca `window`/`URL`/`FileReader` — só
+ * em handlers de evento.
+ */
+
+interface AiImageInputFieldProps {
+    analyses: string[];
+    populateFields: Record<string, string>;
+    provider?: string | null;
+    acceptedMimes: string[];
+    maxFileSize: number;
+    buttonLabel: string;
+}
+interface AiImageInputProps {
+    name: string;
+    value: string | null;
+    onChange?: (value: string) => void;
+    props: AiImageInputFieldProps | undefined;
+    resource?: string;
+    field?: string;
+    analyzeUrl?: string;
+    csrfToken?: string;
+    onPopulateField?: (targetField: string, value: string) => void;
+}
+declare function AiImageInput(props: AiImageInputProps): ReactElement;
+
+/**
+ * `<AiSelectInput>` — apresentational React component for the PHP
+ * `Arqel\Ai\Fields\AiSelectField` (component string `AiSelectInput`).
+ *
+ * Render contract (AI-009):
+ *   - `<select>` controlled (or uncontrolled fallback) with a
+ *     placeholder option + one entry per `props.options`,
+ *   - "Classify with AI" button next to the select; disabled when
+ *     `hasContextFields` is false (with a tooltip explaining why),
+ *   - while a request is in-flight the button is disabled and an
+ *     inline spinner is rendered,
+ *   - on success a banner with `Suggested by AI` is rendered with two
+ *     dismiss buttons: `Accept` and `Pick another` (both just hide the
+ *     banner — the value is already applied),
+ *   - if the response returns `key: null` and `fallbackOption` is
+ *     configured, the fallback is applied and a `Used fallback`
+ *     banner is shown,
+ *   - if the response returns `key: null` and there is no fallback,
+ *     an error banner `Could not classify` is rendered.
+ *
+ * Network:
+ *   - URL = `props.classifyUrl` override or
+ *     `/admin/${resource}/fields/${field}/classify`.
+ *   - `fetch(url, { method: 'POST', credentials: 'same-origin', headers:
+ *     { Content-Type, Accept, X-CSRF-TOKEN }, body: JSON.stringify({
+ *     formData }) })`. The PHP controller runs the LLM classification
+ *     and returns `{ key, label }`.
+ *
+ * SSR-safe: nothing in the render path touches `window`/`document`.
+ */
+
+interface AiSelectInputFieldProps {
+    options: Record<string, string>;
+    classifyFromFields: string[];
+    provider?: string | null;
+    fallbackOption?: string | null;
+    hasContextFields: boolean;
+}
+interface AiSelectInputProps {
+    name: string;
+    value: string | null;
+    onChange?: (value: string | null) => void;
+    props: AiSelectInputFieldProps | undefined;
+    resource?: string;
+    field?: string;
+    formData?: Record<string, unknown>;
+    classifyUrl?: string;
+    csrfToken?: string;
+}
+declare function AiSelectInput(props: AiSelectInputProps): ReactElement;
+
+/**
+ * `<AiTextInput>` — apresentational React component for the PHP
+ * `Arqel\Ai\Fields\AiTextField` (component string `AiTextInput`).
+ *
+ * Render contract (AI-007):
+ *   - `<textarea>` displaying the current value (controlled if
+ *     `onChange` is provided, otherwise uncontrolled with internal
+ *     state seeded by `value`),
+ *   - "Generate with AI" button (label from `props.buttonLabel`,
+ *     fallback `Generate with AI`); after a successful generation the
+ *     button label becomes `Regenerate`,
+ *   - while a request is in-flight the button is disabled and shows a
+ *     small inline spinner,
+ *   - on failure a banner with a generic message + HTTP status code is
+ *     rendered; the button re-enables so the user can retry,
+ *   - optional `X / maxLength` counter when `props.maxLength` is set.
+ *
+ * Network:
+ *   - URL = `props.generateUrl` (caller override) or
+ *     `/admin/${resource}/fields/${field}/generate` (default route name
+ *     `arqel.ai.generate`).
+ *   - `fetch(url, { method: 'POST', credentials: 'same-origin', headers:
+ *     { Content-Type, Accept, X-CSRF-TOKEN }, body: JSON.stringify({
+ *     formData }) })`. The PHP controller resolves the prompt template
+ *     server-side and returns `{ text }`.
+ *
+ * SSR-safe: nothing in the render path touches `window`/`document`;
+ * the network call only fires from the click handler (post-mount).
+ */
+
+interface AiTextInputFieldProps {
+    provider?: string | null;
+    buttonLabel: string;
+    maxLength?: number | null;
+    hasContextFields: boolean;
+}
+interface AiTextInputProps {
+    name: string;
+    value: string;
+    onChange?: (value: string) => void;
+    props: AiTextInputFieldProps | undefined;
+    resource?: string;
+    field?: string;
+    formData?: Record<string, unknown>;
+    generateUrl?: string;
+    csrfToken?: string;
+}
+declare function AiTextInput(props: AiTextInputProps): ReactElement;
+
+/**
+ * `<AiTranslateInput>` — apresentational React component for the PHP
+ * `Arqel\Ai\Fields\AiTranslateField` (component string `AiTranslateInput`).
+ *
+ * Render contract (AI-008):
+ *   - Tab list (`role="tablist"`) com um `<button role="tab">` por
+ *     idioma configurado em `props.languages`. A tab default vem de
+ *     `props.defaultLanguage`.
+ *   - Cada tab mostra um indicador visual (`data-missing="true"`)
+ *     quando a tradução daquela língua está vazia/null.
+ *   - Painel ativo: `<textarea>` controlado que edita
+ *     `translations[activeLang]`. Mudanças disparam o `onChange` com o
+ *     objeto completo `Record<lang, string>`.
+ *   - Botão "Translate from {defaultLanguage}" presente em todas as
+ *     tabs **não-default**; faz `POST` com `targetLanguages: [lang]`.
+ *   - Botão "Translate all missing" no topo do componente; itera as
+ *     línguas com tradução vazia e dispara um único `POST` com o
+ *     array completo.
+ *   - Loading per-language (`Set<string>`): o botão da tab/lang sendo
+ *     traduzida fica `disabled` + spinner inline.
+ *   - Banner `role="alert"` quando o `fetch` falha; o resto continua
+ *     usável.
+ *
+ * Network:
+ *   - URL = `props.translateUrl` (caller override) ou
+ *     `/admin/${resource}/fields/${field}/translate` (default route
+ *     name `arqel.ai.translate`).
+ *   - Body: `{ sourceLanguage, targetLanguages: string[], sourceText }`.
+ *     `sourceText` vem de `translations[defaultLanguage] ?? ''`.
+ *   - Response: `{ translations: { [lang]: string } }` é mesclado em
+ *     state local + `onChange` callback.
+ *
+ * SSR-safe: nada no render path toca `window`/`document`; o `fetch`
+ * só dispara dentro do click handler (post-mount).
+ */
+
+interface AiTranslateInputFieldProps {
+    languages: string[];
+    defaultLanguage: string;
+    autoTranslate: boolean;
+    provider?: string | null;
+}
+type AiTranslateValue = Record<string, string>;
+interface AiTranslateInputProps {
+    name: string;
+    value: AiTranslateValue | null;
+    onChange?: (value: AiTranslateValue) => void;
+    props: AiTranslateInputFieldProps | undefined;
+    resource?: string;
+    field?: string;
+    translateUrl?: string;
+    csrfToken?: string;
+}
+declare function AiTranslateInput(props: AiTranslateInputProps): ReactElement;
+
+export { AiExtractInput, type AiExtractInputFieldProps, type AiExtractInputProps, type AiExtractValue, AiImageInput, type AiImageInputFieldProps, type AiImageInputProps, AiSelectInput, type AiSelectInputFieldProps, type AiSelectInputProps, AiTextInput, type AiTextInputFieldProps, type AiTextInputProps, AiTranslateInput, type AiTranslateInputFieldProps, type AiTranslateInputProps, type AiTranslateValue, AiTextInput as default };