@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/flow/forms/SchemaConfigForm.tsx

@@ -0,0 +1,214 @@
+// SchemaConfigForm: builds a node's settings form from the field schema the
+// node kind catalog serves, so most kinds need no form of their own. Each
+// property gets the editor its shape asks for; Save merges the edits over the
+// incoming value, keeping keys the schema does not mention.
+
+import { useReducer, type ReactNode } from 'react'
+import { NativeSelect, Switch, TextArea, TextField } from '../../index'
+import type { ConfigSchema, FieldSchema } from '../catalog/kindCatalog'
+import { defineLabels, fill, useFlowLocale, useLabels } from '../internal/labels'
+import { NodeFormFooter } from './NodeFormFooter'
+
+export interface SchemaConfigFormLabels {
+  save: string
+  cancel: string
+  none: string
+  yes: string
+  no: string
+  empty: string
+  invalidStructured: string
+  required: string
+}
+
+export const schemaConfigFormLabels = defineLabels<SchemaConfigFormLabels>('SchemaConfigForm', {
+  en: {
+    save: 'Save',
+    cancel: 'Cancel',
+    none: 'None',
+    yes: 'Yes',
+    no: 'No',
+    empty: 'This step has nothing to configure.',
+    invalidStructured: 'Not valid structured text: {detail}',
+    required: 'Fill in this field.',
+  },
+  'pt-BR': {
+    save: 'Salvar',
+    cancel: 'Cancelar',
+    none: 'Nenhum',
+    yes: 'Sim',
+    no: 'Não',
+    empty: 'Esta etapa não tem nada a configurar.',
+    invalidStructured: 'Texto estruturado inválido: {detail}',
+    required: 'Preencha este campo.',
+  },
+  es: {
+    save: 'Guardar',
+    cancel: 'Cancelar',
+    none: 'Ninguno',
+    yes: 'Sí',
+    no: 'No',
+    empty: 'Este paso no tiene nada que configurar.',
+    invalidStructured: 'Texto estructurado no válido: {detail}',
+    required: 'Complete este campo.',
+  },
+})
+
+export const defaultSchemaConfigFormLabels: SchemaConfigFormLabels = schemaConfigFormLabels.bundles.en
+
+/**
+ * Label from a property key when the schema has no title. Only ASCII keys are
+ * split (camelCase, snake_case, kebab-case); keys in any other script are
+ * shown as they are, so no script is broken apart.
+ */
+export function labelFromKey(key: string): string {
+  if (!/^[\x20-\x7e]+$/.test(key)) return key
+  const lower = key
+    .split(/(?<=[a-z0-9])(?=[A-Z])|[_-]+/)
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase()
+  return lower ? lower.charAt(0).toUpperCase() + lower.slice(1) : key
+}
+
+export interface SchemaConfigFormProps {
+  value: Record<string, unknown>
+  schema: ConfigSchema
+  onSave: (value: Record<string, unknown>) => void
+  onCancel: () => void
+  saveDisabled?: boolean
+  labels?: Partial<SchemaConfigFormLabels>
+}
+
+type Control = 'select' | 'number' | 'switch' | 'structured' | 'multiline' | 'line'
+
+/** Keys whose text is long enough to deserve a multi-line area. */
+const LONG_TEXT = /(prompt|template|body|instructions?|input|code)$/i
+
+/** Shape tests in priority order; the first that matches picks the editor. */
+const SHAPES: ReadonlyArray<[Control, (key: string, f: FieldSchema) => boolean]> = [
+  ['select', (_k, f) => !!f.enum?.length],
+  ['number', (_k, f) => f.type === 'number' || f.type === 'integer'],
+  ['switch', (_k, f) => f.type === 'boolean'],
+  ['structured', (_k, f) => f.type === 'array' || f.type === 'object'],
+  ['multiline', (k) => LONG_TEXT.test(k)],
+]
+
+export function controlFor(key: string, field: FieldSchema): Control {
+  return SHAPES.find(([, test]) => test(key, field))?.[0] ?? 'line'
+}
+
+/** Per-field working state: the value to save (absent = unchanged), raw JSON text, its problem, whether it was visited. */
+interface Slot {
+  changed?: { to: unknown }
+  text?: string
+  problem?: string
+  visited?: boolean
+}
+
+type Slots = Record<string, Slot>
+const patchSlot = (slots: Slots, [key, patch]: [string, Slot]): Slots => ({ ...slots, [key]: { ...slots[key], ...patch } })
+
+const asText = (v: unknown) => (v === undefined || v === null ? '' : String(v))
+const isEmpty = (v: unknown) => v === undefined || v === null || v === ''
+
+/** Everything a field editor needs. */
+interface FieldCtx {
+  name: string
+  field: FieldSchema
+  label: string
+  required: boolean
+  current: unknown
+  slot: Slot
+  problem?: string
+  l: SchemaConfigFormLabels
+  put: (to: unknown) => void
+  visit: () => void
+  typeJson: (text: string) => void
+}
+
+const shared = (c: FieldCtx) => ({ label: c.label, hint: c.field.description, required: c.required, ...(c.problem ? { errorMessage: c.problem } : {}) })
+
+const EDITORS: Record<Control, (c: FieldCtx) => ReactNode> = {
+  select: (c) => (
+    <NativeSelect
+      {...shared(c)}
+      placeholder={c.l.none}
+      options={c.field.enum!.map((o) => ({ value: String(o), label: String(o) }))}
+      value={asText(c.current)}
+      onChange={(picked) => c.put(picked === '' ? undefined : c.field.enum!.find((o) => String(o) === picked))}
+    />
+  ),
+  number: (c) => (
+    <TextField
+      {...shared(c)}
+      inputType="number"
+      value={typeof c.current === 'number' ? String(c.current) : ''}
+      onChange={(t) => c.put(t.trim() === '' || Number.isNaN(Number(t)) ? undefined : Number(t))}
+      onBlur={c.visit}
+    />
+  ),
+  switch: (c) => <Switch label={c.label} {...(c.field.description ? { description: c.field.description } : {})} isSelected={c.current === true} onChange={c.put} />,
+  structured: (c) => <TextArea {...shared(c)} monospace className="ty-ltr-text" rows={5} value={c.slot.text ?? ''} onChange={c.typeJson} />,
+  multiline: (c) => <TextArea {...shared(c)} rows={4} autoGrow value={asText(c.current)} onChange={c.put} />,
+  line: (c) => <TextField {...shared(c)} value={asText(c.current)} onChange={c.put} onBlur={c.visit} />,
+}
+
+export function SchemaConfigForm({ value, schema, onSave, onCancel, saveDisabled = false, labels }: SchemaConfigFormProps) {
+  const l = useLabels(schemaConfigFormLabels, labels)
+  const { locale } = useFlowLocale()
+  const fields = Object.entries(schema.properties ?? {})
+  const needed = schema.required ?? []
+  const [slots, patch] = useReducer(patchSlot, undefined, () =>
+    Object.fromEntries(fields.filter(([k, f]) => controlFor(k, f) === 'structured').map(([k]) => [k, { text: value[k] === undefined ? '' : JSON.stringify(value[k], null, 2) }])),
+  )
+
+  const valueOf = (key: string) => (slots[key]?.changed ? slots[key]!.changed!.to : value[key])
+
+  /** Structured text: blank unsets, valid JSON replaces, invalid keeps the last good value and explains. */
+  const typeJsonFor = (key: string) => (text: string) => {
+    if (!text.trim()) return patch([key, { text, problem: '', changed: { to: undefined } }])
+    try {
+      patch([key, { text, problem: '', changed: { to: JSON.parse(text) as unknown } }])
+    } catch (why) {
+      patch([key, { text, problem: fill(l.invalidStructured, { detail: why instanceof Error ? why.message : String(why) }, locale) }])
+    }
+  }
+
+  const merged = () => {
+    const out = { ...value }
+    for (const [key, slot] of Object.entries(slots)) {
+      if (!slot.changed) continue
+      if (slot.changed.to === undefined) delete out[key]
+      else out[key] = slot.changed.to
+    }
+    return out
+  }
+
+  const editors = fields.map(([name, field]) => {
+    const slot = slots[name] ?? {}
+    const required = needed.includes(name)
+    const current = valueOf(name)
+    const problem = slot.problem || (required && slot.visited && isEmpty(current) ? l.required : undefined)
+    const ctx: FieldCtx = {
+      name,
+      field,
+      label: field.title ?? labelFromKey(name),
+      required,
+      current,
+      slot,
+      ...(problem ? { problem } : {}),
+      l,
+      put: (to) => patch([name, { changed: { to } }]),
+      visit: () => patch([name, { visited: true }]),
+      typeJson: typeJsonFor(name),
+    }
+    return <div key={name} className="ty-schema-form__field">{EDITORS[controlFor(name, field)](ctx)}</div>
+  })
+
+  return (
+    <div className="ty-node-form ty-schema-form">
+      {editors.length ? <div className="ty-node-form__fields">{editors}</div> : <p className="ty-node-form__empty">{l.empty}</p>}
+      <NodeFormFooter onSave={() => onSave(merged())} onCancel={onCancel} saveDisabled={saveDisabled} labels={{ save: l.save, cancel: l.cancel }} />
+    </div>
+  )
+}

package/src/flow/forms/StartNodeForm.css

@@ -0,0 +1,29 @@
+/* StartNodeForm: default fields in two columns from the medium breakpoint. */
+@layer tympan.components {
+  .ty-start-form__defaults {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ty-space-3);
+  }
+  .ty-start-form__defaults-title {
+    color: var(--ty-ink);
+    font-size: var(--ty-font-size-label);
+    font-weight: var(--ty-font-weight-semibold);
+  }
+  .ty-start-form__grid {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    gap: var(--ty-space-4);
+  }
+  /* Variable names label the fields: identifiers in mono. */
+  .ty-start-form__default label {
+    font-family: var(--ty-font-mono);
+    direction: ltr;
+    unicode-bidi: isolate;
+  }
+  @media (min-width: 768px) {
+    .ty-start-form__grid {
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+    }
+  }
+}

package/src/flow/forms/StartNodeForm.test.tsx

@@ -0,0 +1,66 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { renderWithProvider } from '../../../test/render'
+import { StartNodeForm } from './StartNodeForm'
+
+describe('StartNodeForm', () => {
+  it('saves both variables and only the non-empty defaults', async () => {
+    const onSave = vi.fn()
+    const { container } = render(<StartNodeForm config={{ inputVariables: ['amount', 'term'] }} onSave={onSave} onCancel={() => {}} />)
+    await userEvent.type(screen.getByRole('textbox', { name: 'amount' }), '10')
+    await userEvent.click(screen.getByRole('button', { name: 'Save' }))
+    expect(onSave).toHaveBeenCalledWith({ kind: 'start', inputVariables: ['amount', 'term'], inputDefaults: { amount: '10' } })
+    await expectNoAxeViolations(container)
+  })
+
+  it('drops the default of a removed variable', async () => {
+    const onSave = vi.fn()
+    render(<StartNodeForm config={{ inputVariables: ['amount', 'term'], inputDefaults: { amount: '10' } }} onSave={onSave} onCancel={() => {}} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Remove amount' }))
+    await userEvent.click(screen.getByRole('button', { name: 'Save' }))
+    expect(onSave.mock.calls[0]![0].inputDefaults).toEqual({})
+  })
+
+  it('omits a default cleared to empty', async () => {
+    const onSave = vi.fn()
+    render(<StartNodeForm config={{ inputVariables: ['amount'], inputDefaults: { amount: '10' } }} onSave={onSave} onCancel={() => {}} />)
+    await userEvent.clear(screen.getByRole('textbox', { name: 'amount' }))
+    await userEvent.click(screen.getByRole('button', { name: 'Save' }))
+    expect(onSave.mock.calls[0]![0].inputDefaults).toEqual({})
+  })
+
+  it('hides the defaults group without variables', () => {
+    render(<StartNodeForm config={{}} onSave={() => {}} onCancel={() => {}} />)
+    expect(screen.queryByRole('group', { name: 'Default values' })).toBeNull()
+  })
+
+  it('cancels without saving', async () => {
+    const onSave = vi.fn()
+    const onCancel = vi.fn()
+    render(<StartNodeForm config={{ inputVariables: ['a'] }} onSave={onSave} onCancel={onCancel} />)
+    await userEvent.type(screen.getByRole('textbox', { name: 'a' }), 'x')
+    await userEvent.click(screen.getByRole('button', { name: 'Cancel' }))
+    expect(onCancel).toHaveBeenCalled()
+    expect(onSave).not.toHaveBeenCalled()
+  })
+
+  it('keeps unknown keys and drops blank variable names on save', async () => {
+    const onSave = vi.fn()
+    render(<StartNodeForm config={{ inputVariables: ['a', ''], extra: 1 }} onSave={onSave} onCancel={() => {}} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Save' }))
+    expect(onSave).toHaveBeenCalledWith({ kind: 'start', extra: 1, inputVariables: ['a'], inputDefaults: {} })
+  })
+
+  it('uses the built-in Portuguese strings under a pt-BR provider', () => {
+    renderWithProvider(<StartNodeForm config={{ inputVariables: ['a'] }} onSave={() => {}} onCancel={() => {}} />, { locale: 'pt-BR' })
+    expect(screen.getByRole('group', { name: 'Valores padrão' })).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Salvar' })).toBeInTheDocument()
+  })
+
+  it('lays defaults in two columns from the medium breakpoint', () => {
+    expect(mediaBlock(cssOf('flow/forms/StartNodeForm.css'), /\(min-width: 768px\)/)).toMatch(/repeat\(2/)
+  })
+})

package/src/flow/forms/StartNodeForm.tsx

@@ -0,0 +1,88 @@
+// StartNodeForm: which inputs a run asks for, and a starting value for each.
+// Nothing leaves the form until Save; Save cleans the names and keeps only the
+// defaults that still belong to a named variable and are not empty.
+
+import { useId, useReducer } from 'react'
+import { TextField } from '../../index'
+import { defineLabels, useLabels } from '../internal/labels'
+import { NodeFormFooter } from './NodeFormFooter'
+import { VariableListEditor } from './VariableListEditor'
+
+export interface StartConfig {
+  kind: 'start'
+  inputVariables: string[]
+  inputDefaults: Record<string, string>
+  [key: string]: unknown
+}
+
+export interface StartNodeFormLabels {
+  variables: string
+  add: string
+  placeholder: string
+  defaults: string
+  defaultPlaceholder: string
+  save: string
+  cancel: string
+}
+
+export const startNodeFormLabels = defineLabels<StartNodeFormLabels>('StartNodeForm', {
+  en: { variables: 'Input variables', add: 'Add variable', placeholder: 'Variable name', defaults: 'Default values', defaultPlaceholder: 'Default value', save: 'Save', cancel: 'Cancel' },
+  'pt-BR': { variables: 'Variáveis de entrada', add: 'Adicionar variável', placeholder: 'Nome da variável', defaults: 'Valores padrão', defaultPlaceholder: 'Valor padrão', save: 'Salvar', cancel: 'Cancelar' },
+  es: { variables: 'Variables de entrada', add: 'Añadir variable', placeholder: 'Nombre de la variable', defaults: 'Valores predeterminados', defaultPlaceholder: 'Valor predeterminado', save: 'Guardar', cancel: 'Cancelar' },
+})
+
+export const defaultStartNodeFormLabels: StartNodeFormLabels = startNodeFormLabels.bundles.en
+
+export interface StartNodeFormProps {
+  config: { inputVariables?: string[]; inputDefaults?: Record<string, string>; [key: string]: unknown }
+  onSave: (config: StartConfig) => void
+  onCancel: () => void
+  labels?: Partial<StartNodeFormLabels>
+}
+
+interface Draft {
+  names: string[]
+  fallback: Record<string, string>
+}
+
+type DraftEdit = { names: string[] } | { name: string; fallback: string }
+
+function edit(draft: Draft, change: DraftEdit): Draft {
+  return 'names' in change ? { ...draft, names: change.names } : { ...draft, fallback: { ...draft.fallback, [change.name]: change.fallback } }
+}
+
+/** The start configuration Save emits: unique trimmed names, non-empty defaults of those names, other keys untouched. */
+function settle(config: StartNodeFormProps['config'], draft: Draft): StartConfig {
+  const inputVariables = Array.from(new Set(draft.names.map((n) => n.trim()).filter(Boolean)))
+  const inputDefaults = Object.fromEntries(inputVariables.flatMap((n) => (draft.fallback[n] ? [[n, draft.fallback[n]!]] : [])))
+  return { ...config, kind: 'start', inputVariables, inputDefaults }
+}
+
+function DefaultValues({ names, fallback, heading, placeholder, onEdit }: { names: string[]; fallback: Record<string, string>; heading: string; placeholder: string; onEdit: (name: string, value: string) => void }) {
+  const headingId = useId()
+  return (
+    <div className="ty-start-form__defaults" role="group" aria-labelledby={headingId}>
+      <span id={headingId} className="ty-start-form__defaults-title">
+        {heading}
+      </span>
+      <div className="ty-start-form__grid">
+        {names.map((name) => (
+          <TextField key={name} className="ty-start-form__default" label={name} placeholder={placeholder} value={fallback[name] ?? ''} onChange={(v) => onEdit(name, v)} />
+        ))}
+      </div>
+    </div>
+  )
+}
+
+export function StartNodeForm({ config, onSave, onCancel, labels }: StartNodeFormProps) {
+  const l = useLabels(startNodeFormLabels, labels)
+  const [draft, change] = useReducer(edit, config, (c): Draft => ({ names: [...(c.inputVariables ?? [])], fallback: { ...(c.inputDefaults ?? {}) } }))
+  const named = draft.names.filter((n) => n.trim() !== '')
+  return (
+    <div className="ty-node-form ty-start-form">
+      <VariableListEditor label={l.variables} value={draft.names} onChange={(names) => change({ names })} numbered editable tone="input" addLabel={l.add} placeholder={l.placeholder} />
+      {named.length > 0 && <DefaultValues names={named} fallback={draft.fallback} heading={l.defaults} placeholder={l.defaultPlaceholder} onEdit={(name, fallback) => change({ name, fallback })} />}
+      <NodeFormFooter onSave={() => onSave(settle(config, draft))} onCancel={onCancel} labels={{ save: l.save, cancel: l.cancel }} />
+    </div>
+  )
+}

package/src/flow/forms/ToolServerListField.css

@@ -0,0 +1,58 @@
+/* ToolServerListField: entries as fieldsets; address and command side by side from the medium breakpoint. */
+@layer tympan.components {
+  .ty-tool-servers {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ty-space-3);
+  }
+  .ty-tool-servers__header {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--ty-space-2);
+  }
+  .ty-tool-servers__label {
+    color: var(--ty-ink);
+    font-size: var(--ty-font-size-label);
+    line-height: var(--ty-font-line-height-label);
+    font-weight: var(--ty-font-weight-semibold);
+  }
+  .ty-tool-servers__empty {
+    margin: 0;
+    color: var(--ty-ink-3);
+  }
+  .ty-tool-servers__entry {
+    padding: var(--ty-space-4);
+    border: 1px solid var(--ty-line);
+    border-radius: var(--ty-radius-card);
+  }
+  .ty-tool-servers__reach {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    gap: var(--ty-space-4);
+  }
+  @media (min-width: 768px) {
+    .ty-tool-servers__reach[data-command] {
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+    }
+  }
+  .ty-tool-servers__mono input {
+    font-family: var(--ty-font-mono);
+  }
+  .ty-tool-servers__hint {
+    margin: 0;
+    color: var(--ty-on-warning-soft, var(--ty-ink-2));
+    font-size: var(--ty-font-size-meta);
+    line-height: var(--ty-font-line-height-meta);
+  }
+  .ty-tool-servers__actions {
+    display: flex;
+    justify-content: flex-end;
+  }
+  @media (forced-colors: active) {
+    .ty-tool-servers__entry {
+      border-color: CanvasText;
+    }
+  }
+}

package/src/flow/forms/ToolServerListField.test.tsx

@@ -0,0 +1,73 @@
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { useState } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { cleanToolServers, ToolServerListField, type ToolServer } from './ToolServerListField'
+
+function Controlled({ initial = [], spy, allowCommand }: { initial?: ToolServer[]; spy?: (l: ToolServer[]) => void; allowCommand?: boolean }) {
+  const [value, setValue] = useState(initial)
+  return (
+    <ToolServerListField
+      value={value}
+      {...(allowCommand !== undefined ? { allowCommand } : {})}
+      onChange={(l) => {
+        spy?.(l)
+        setValue(l)
+      }}
+    />
+  )
+}
+
+describe('ToolServerListField', () => {
+  it('adds a blank entry and focuses its prefix field', async () => {
+    const spy = vi.fn()
+    const { container } = render(<Controlled spy={spy} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Add server' }))
+    expect(spy).toHaveBeenCalledWith([{}])
+    await waitFor(() => expect(screen.getByRole('textbox', { name: /Tool name prefix/ })).toHaveFocus())
+    expect(screen.getByRole('status')).toHaveTextContent('Server added')
+    await expectNoAxeViolations(container)
+  })
+
+  it('stores space-separated arguments as a list', async () => {
+    const spy = vi.fn()
+    render(<Controlled initial={[{ command: 'x' }]} spy={spy} />)
+    await userEvent.type(screen.getByRole('textbox', { name: /Command arguments/ }), 'run -p tool')
+    expect(spy).toHaveBeenLastCalledWith([{ command: 'x', args: ['run', '-p', 'tool'] }])
+  })
+
+  it('cleans entries: trims, drops blanks, returns undefined when nothing remains', () => {
+    expect(cleanToolServers([{}, { url: ' https://x ' }])).toEqual([{ url: 'https://x' }])
+    expect(cleanToolServers([{}, { prefix: '  ' }])).toBeUndefined()
+  })
+
+  it('hides command and arguments when commands are not allowed', () => {
+    render(<Controlled initial={[{}]} allowCommand={false} />)
+    expect(screen.queryByRole('textbox', { name: /Local command/ })).toBeNull()
+    expect(screen.queryByRole('textbox', { name: /Command arguments/ })).toBeNull()
+  })
+
+  it('moves focus to the remaining entry after removing the first', async () => {
+    render(<Controlled initial={[{ url: 'https://a' }, { url: 'https://b' }]} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Remove server 1' }))
+    await waitFor(() => expect(screen.getAllByRole('textbox', { name: /Tool name prefix/ })[0]).toHaveFocus())
+    expect(screen.getAllByRole('group', { name: /Server/ })).toHaveLength(1)
+  })
+
+  it('warns about an incomplete entry and a malformed address after blur', async () => {
+    render(<Controlled initial={[{}]} />)
+    expect(screen.getByText(/will be ignored on save/)).toBeInTheDocument()
+    const url = screen.getByRole('textbox', { name: /Remote address/ })
+    await userEvent.type(url, 'nope')
+    await userEvent.tab()
+    expect(screen.getByText('Not a valid address.')).toBeInTheDocument()
+  })
+
+  it('stacks fields on narrow widths and keeps entry borders in forced colours', () => {
+    const css = cssOf('flow/forms/ToolServerListField.css')
+    expect(mediaBlock(css, /\(min-width: 768px\)/)).toMatch(/repeat\(2/)
+    expect(mediaBlock(css, /\(forced-colors: active\)/)).toMatch(/CanvasText/)
+  })
+})