Skip to content

feat(forms): add standard input fields - #113

Draft
AndrewKirkovski wants to merge 68 commits into
codex/session-forms-v1-releasefrom
codex/session-forms-v2
Draft

AndrewKirkovski wants to merge 68 commits into
codex/session-forms-v1-releasefrom
codex/session-forms-v2

Conversation

@AndrewKirkovski

Copy link
Copy Markdown
Contributor

Summary

This pull request adds Session Forms V2 (EE2-2462). A second trait, wippy.session.forms:ask_user_fields, lets an agent ask for six standard input fields: text, textarea, number, email, date and checkbox. wippy.session.forms:ask_user stays choice-only, and both traits include read_form. Choice-only forms keep form_version 1 and stay the same byte for byte. Any other form has form_version 2.

Base and order

This pull request is based on #77, so the diff shows V2 only. It moves to master after #77 merges.

Changes

  • src/forms/field_values.lua, form_pattern.lua and form_text.lua validate and normalize each field type. Numbers are finite JSON numbers with no coercion, dates are YYYY-MM-DD, a required checkbox means true, and defaults only prefill.
  • pattern is checked on the server only, with a bounded regular-expression subset. The browser never runs it, because a backtracking engine can hang the tab.
  • Answers are validated against the definition read under the acceptance lock, the same rule feat(forms)!: Session Forms V1 (ask_user trait and form state API) #77 uses for choices.
  • wippy-form gains a fields form and shares one draft and serializer with the question card.
  • test/forms/fixtures/v2_conformance.json holds the rules that both the Lua and the TypeScript validators must pass.
  • The calendar theme observer is removed, because @wippy-fe/theme 0.0.67 carries that fix.

Before this can merge

  • feat(forms)!: Session Forms V1 (ask_user trait and form state API) #77 must merge first.
  • The Web Host must publish @wippy-fe types for version 2 forms. Published 0.0.67 types are choice-only, so frontend/wippy-form/src/wippy-proxy.d.ts stays until then, and it must be removed in the same change that moves to the new version.
  • The visible browser matrix for V2 has not run on this head.

Verification

On d518ac5, on Windows with runtime 0.3.57a:

  • wippy lint: 0 errors.
  • 1938 tests pass. 5 bootstrap_test cases fail because make, jq and sqlite3 are absent on that machine.
  • UI: 663 and 18 tests pass, and check-ui confirms the committed bundles match a fresh build.
  • vue-tsc passes with 0 errors against packed candidate @wippy-fe tarballs with all local type shims removed. With published 0.0.67 types and no shim it reports 1 error, which shows the check can fail.

Probe tests for number decoding and arithmetic, null in decoded
answers, time.parse(DATE_ONLY) strictness and text.regexp dialect and
bounds. Each asserts what runtime 0.3.43a does today, so a runtime
upgrade that changes one fails a named test.
The UTF-8 decoder, code point count, JavaScript trim set, blank and
control character tests and the plain-text definition key checks move
out of definition.lua so the standard field values can use them without
a dependency cycle. Behavior is unchanged; the existing suite is the
regression net.
… checkbox

A form definition may now hold text, textarea, number, email, date and
checkbox fields next to choices. field_values.lua owns the six types:
per-type allowed keys, ranges, steps, a bounded regular expression
subset (form_pattern.lua, compiled as a full match with text.regexp),
defaults validated by the answer checker, the answer checks with stable
codes, and the canonical text of a stored value.

Numbers are checked on their shortest decimal digits with digit-string
arithmetic: this runtime compares and takes remainders of integers
through 64-bit floats, which is not exact above 2^53. Dates use
time.parse(DATE_ONLY) behind an ASCII shape check. Text is stored as
typed; an address is trimmed. The text, textarea and email limits of one
form together are capped at 16,000 characters so every valid submission
fits the 64 KiB body.

The form version follows the definition: version 2 with any standard
field, version 1 otherwise, and a choice-only form is unchanged byte for
byte. The write, parse, GET, the POST envelope and the answer record
all use it, and a stored version lower than the definition needs is
refused. The answer record keeps {question, answer} with the answer as a
JSON literal, and read_form and questions_json describe the new types
and their limits. The ask_user schema is one flat object with the seven
types.

A shared JSON fixture of 481 cases runs through the definition and the
answer validator; the form component is tested against the same file.
Accept form versions 1 and 2 (a higher version, or a field type the component does not know, keeps the "needs a newer version" notice).

Extract the field shell (label, required marker, description, control slot, error list linked by aria-describedby, read-only value) from the choice field and build the text, textarea, email, number, date and checkbox controls on it. Number is a text input with a strict parser, not InputNumber. Date is a PrimeVue DatePicker in string mode that never drops typed text it cannot parse.

Add the per-type client rules and serialization (lib/answers.ts, scalar-answers.ts, decimal.ts, text.ts), defaults that prefill, the Yes/No/Skipped read-only display, and disabled controls for V2 fields in both notices. The fields form is novalidate and gains parts, w-form__ classes and two tokens. A conformance test runs test/forms/fixtures/v2_conformance.json through the client checker.
Update the wippy metadata (description and the form-version and definition props) in package.json and the copy in src/forms/ui/_index.yaml, then rebuild src/forms/ui/dist from the new source. index.js grows from 71.4 KB to 104.0 KB gzip; the PrimeVue DatePicker is 27.8 KB of that.
Add the Fields form section to the wippy-form README: the six controls, the client-side checks by type and code, the two new tokens, the parts and classes with their states, host attributes, accessibility and keyboard behavior, and known gaps. Update the intro, the props table and the answer shapes for form version 2.
…he supported range

A stored definition is not re-checked for the magnitude and decimals
limits, so a step or minimum outside them could reach the digit-string
division. Such a field now reports not_on_step instead of risking a loop
on a zero or malformed divisor.
The pattern is written by the agent and a browser regex engine backtracks: an overlapping repeat such as (a|a)*b or a*a*a*a*b on a 2,000-character answer can freeze the tab. Stop building a RegExp from a definition; the server checks the pattern with RE2 and its 422 pattern_mismatch shows on the field like any client error.

The conformance runner now skips every pattern answer case and names each skip reason, with the checked and skipped counts in the test output. New tests: a value that does not match a pattern is submitted and the 422 shows on that field (text under it, aria-describedby on the real input, invalid, focused, typed value kept), another per-field code and a form-level error are shown too, and no RegExp is built while checking an answer.
… checks

Note in the definition prop description (package.json and its copy in src/forms/ui/_index.yaml) that only the server evaluates a text pattern, then rebuild src/forms/ui/dist. index.js is 103,969 bytes gzip (516,540 raw).
…nd why

Add a Pattern section to the wippy-form README: the browser never evaluates a text field's pattern because an agent-written pattern can make a browser regex engine backtrack without bound, the server checks it with a linear-time engine, and a 422 pattern_mismatch (or any per-field code) shows on the field with the typed value kept.
The README still said forms hold choice fields only. It now lists the six
standard field types, explains form versions 1 and 2 and the older
component's notice, and says the server checks every answer, including a
text field's pattern, which the browser never evaluates.
…ar the form's theme and a sensible width

The date box could not be typed into: every key was erased at once, and text pasted over a valid date left the old date in the box next to the error. The cause is the DatePicker's box, which is uncontrolled: it follows only the last date the picker accepted, and Vue writes that date over the box on every re-render of the inner input, which the form triggers by re-rendering after each reported key. The field now owns the box text and hands it to the box as its value through the picker's pass-through, so every render writes exactly what was typed. A date the picker reads from loose text is held as the full date and shown as such once the box is left; text it rejects stays in the box, is reported as typed, and is put back after the picker's blur reset.

The calendar opens in the theme plugin's overlay layer, a sibling of the themed container, so it stayed white in the Dark theme. appendTo="self" would put it in the themed subtree, but the message bubble around a form clips it: in a one-question form 27% of the calendar was reachable. The calendar instead carries the container's w-theme-dark or w-theme-light class (useThemeModeClass), and its inline min-width, which made it as wide as the whole form, is lifted through its own field-calendar part and class.

Tests type one key at a time with a parent that feeds the draft back in, as the form does.
…or as invalid

A choice group in error exposed its message through aria-describedby on the fieldset but no control carried aria-invalid, unlike every other field. Each radio and checkbox now takes the PrimeVue invalid prop while the group is in error, so the attribute sits on the inputs a screen reader lands on (a group role may not carry it). The Other text box is marked only when the blank Other text is what is wrong.
…ith the errors

The status text stayed at the count from the last submit after every error was fixed. It is now updated when the number of questions with an error changes, once per fixed question and not once per key, and emptied when none are left. A submit-failure message in the same region is never overwritten by the summary.
…ol fixes

Rebuild src/forms/ui/dist from the date box, calendar, choice group and status fixes. index.js is 104,563 bytes gzip (518,714 raw), up from 103,969 (516,540); the package metadata is unchanged.
…group state and the known gaps

The fields form README now says how the date box keeps typed text and why, lists the field-calendar part and class, says where aria-invalid sits for a choice group, describes the status summary as it is kept in step, and records as known gaps the calendar's unnamed day cells, the theme class the calendar carries until the theme plugin's overlay layer does, the inline minimum width the calendar class lifts, and the darker Dark textarea, which is the theme's own textarea style.
Brings upstream 0.6.4 (initial agent and model before the first turn) and
the reload fix: a client disconnect starts the 10 s grace period instead of
finishing the sessions at once, so a page reload no longer stops the turn.
RE2 reads {01}, {1,02} and {00} as text, not as a repeat, so a pattern
that passed the subset check matched a literal brace and the field
became unanswerable. Such counts are now invalid_pattern; {0} stays valid.

The bound and order checks compare the counts as digit strings, so they no
longer assume a three-digit bound. Fixture cases and unit tests cover the
refused spellings, the accepted counts, RE2's own reading of both and the
lengths each accepted count matches.
…ession

form_pattern.check compiled the full-match wrapper on its own, a second
copy of what compile does. It now goes through compile, which owns the
wrapper. Compiled expressions are cached by pattern text, with a bound,
as the email expression is: writing a form with a pattern and a default,
answering it and replaying the answer no longer compile again.
…l autofill, give placeholder to text and textarea only

The number field always asked for the decimal keypad. iOS has no minus key on it, and in a comma-decimal locale it types a comma that the dot-only parser rejects. It now uses the digit keypad (numeric) for a whole number with min >= 0, the decimal keypad for a fraction with min >= 0 when the browser locale writes a dot, and the full keyboard for everything else.

The email field no longer offers the user's own address through autofill, since an agent may ask for someone else's.

placeholder belongs to text and textarea (decisions D32). The number and email types lose it from the types, the control, and the package and registry descriptions. The density description now says it applies to the fields form as well.

The checkbox keyboard test now presses Space through user-event, which sends the click a browser sends on keyup. The old test never touched the keyboard.
… parser reads it

The schema listed the escapes loosely ("a backslash before a punctuation
character") and left out ^, $, {n,}, the lazy ? and the leading-zero rule.
It now lists the characters a backslash may precede, the constructs the
subset accepts and refuses, and the bounds.

form_pattern builds its error message for a refused escape from the same
character list it parses with, and exposes the list. A test compares the
schema's list, the message's list and the parser's behaviour for every
printable ASCII character, checks an example of each described construct
against the parser, and ties the stated bounds to the constants.
…on reload, keep years below 1000 as typed

A tap on the date box did nothing on a phone: PrimeVue sets inputmode="none" and the field does not open on focus. On a coarse pointer a tap now opens the calendar through the calendar button; a mouse click and keyboard focus behave as before.

min and max became new Date objects on every state reload, which made PrimeVue reset an open calendar to the month of the selection. They are now computed from the text of the bounds, so the Date changes only when the text does.

PrimeVue reads a typed year below 100 as a two-digit year (0050 became 1950) and writes a picked year below 1000 without padding. A typed text that is itself a whole valid date is now reported as typed, and a picked year is padded to four digits.

The theme class observer is installed only while the date field can open a calendar (not read-only, not disabled) and is released and read again as that changes. The tautological unmount test now spies on MutationObserver disconnect with a positive control that the observer was installed. The composable carries a TODO(D36) naming what to delete with @wippy-fe/theme 0.0.61, and the calendar min-width rule carries the same lifecycle note.

New tests cover a loose date through Tab and Enter, IME composition (with a positive control that a rewrite of the box is detected), the touch tap with a mocked matchMedia, and the reload.
The Other text and the note of a choice, and the text, textarea and email
fields each carried their own copy of the same steps: size guard, trim,
UTF-8 count, control characters, blank, length, with different
multipliers and wording. They now call form_text.read_answer (options:
max, raw factor, trim, multiline), which names the first problem; each
caller keeps its own codes and messages, and the order is unchanged.

A new suite pins every step of the six answers, codes and messages
included, and passed against the old code before the change; it also
tests the helper on its own.
…nd drop the group role that cannot carry aria-required

The description and error ids were only on the fieldset, so a screen reader that landed on a radio, a checkbox or the Other text box did not read the blank-Other message. Every input and the Other box now carries aria-describedby next to the aria-invalid it already had.

A multiple-choice field put role="group" and aria-required on a div inside a fieldset, which is already the group, and aria-required is not allowed on that role. It now adds neither; a single choice keeps its radiogroup with aria-required. Tests assert the attributes.
A field with a type the form does not know fell through to the choice
rules, so the agent was also told "A choice field needs options". The type
is the one thing to fix. Other mistakes in the same field (id, label) are
still reported, and a real choice without options is still told so.
…claim

- A refused answer must carry exactly one error, on the one field under
  test, and its message must not repeat the value sent (from 3
  characters). A refused definition must carry the listed errors and no
  other. This found three cases that hid a second error, fixed in the
  previous commit.
- The cases named "exponent spelling", "capital exponent spelling" and
  "negative zero is zero" now carry 1e2, 1E2 and -0 in the file, which a
  JSON writer had turned into 100.0 and 0; a test reads the file text to
  keep them. The case with -0.0 is renamed for what it is.
- A default is prefill only: cases for every V2 type with a default and no
  value (required is required, optional is unanswered). A mutation that
  falls back to the default fails 13 of them.
…usal and acceptance

State service tests on the real database:
- A form whose fields all have defaults reads as active with no data, no
  submitted_at, no answer message and no wake-up; an answer that leaves the
  required fields out gets 422 required for each; an empty answer to
  optional fields is accepted with nothing stored and the record shows
  null for each; read_form shows it unanswered, then answer_pending.
- A patterned form answers 422 pattern_mismatch (without the value, for
  five near misses), then accepts a match and replays it.

Both fail under a mutation that falls back to the default or skips the
pattern, so they check the behaviour and not only the shape.
…be every route a pattern could be evaluated through

A missing test/forms/fixtures/v2_conformance.json skipped the whole comparison with the server, so a moved fixture or a checkout without test/ passed silently. It now fails.

The no-RegExp guard spied on the RegExp constructor, which a string handed to match, search or split never calls. A new test feeds patterns no engine can compile ("(", "[a-", ")", "*a", "\\", a duplicate group name, a reversed repeat) to the text handler and the whole checker, and asserts the answer is accepted with no throw, with a positive control that each pattern really throws when compiled. A temporary string.match route was caught by the new test and missed by the old one.
…answer guard

missingRequiredFields, fieldsWithBlankOther, fieldsWithOverlongOtherText and noteTextLength had no caller outside their own tests; evaluateField and validateAnswers answer the same questions. The helpers are removed and the tests that covered real rules (blank and over-long Other text, required fields, the U+3000 and U+200B trim cases) now run through validateAnswers.

The { other: text } check existed three times (definition.ts, answers.ts, choice-field.vue). definition.ts exports the one guard and the others use it. text.ts now points at src/forms/form_text.lua, where the server's text rules live.
… a value

A step grid starts at min (zero without a min) and a value below min is
refused anyway, so min is always on the grid and inside the range: an
accepted number definition cannot allow no answer, and min 1, max 4, step
5 (also with integer) allows exactly 1. Nothing to refuse at creation.
A sweep over min, max, step and integer proves every accepted combination
has an allowed value, and fixture cases pin the narrow-range behaviour for
the server and the client.
The gate's any-count matched ": any" in a comment of the new pattern test. The comment says the same thing without that text.
Rebuild src/forms/ui/dist from the number keypad, date field, choice ARIA, announcement, date width and shared header, notice and label changes. index.js is 105,238 bytes gzip (518,844 raw), up from 104,563 (518,714); wippy-meta.json carries the updated package description and prop descriptions.
…ests

make lint found seven type errors in the last commits: an untyped table
returned as {[string]: boolean}, a bare {} indexed in the form_checks
tests, and two values of type any passed where a number is expected after
the whole-number and free-text refactors. Typed explicitly; no behaviour
change.
…(EE2-2462)

A keyboard pick (ArrowDown, ArrowDown, Enter) or Escape could leave focus on
the page instead of the date box in about one run in four. PrimeVue focuses the
box when a day is picked, but a re-render of the picker queues a zero-delay
re-focus of its day cells, and when two renders land before those timers run
the second one focuses the first day cell after the box. The picker only skips
that when `overlay.contains(document.activeElement)`, and inside the component's
shadow root `document.activeElement` is the shadow host, so the check never sees
the box. When the calendar then closes, the browser drops focus to the page.

The field now listens for the picker's `hide` event. If the root's own
`activeElement` is still inside the calendar panel it focuses the box, without
scrolling. Focus that has already moved (a click elsewhere, Tab) is left alone.

Tests run in a shadow root with fake timers: a keyboard pick, a keyboard pick
with a second render of the field, Escape, no scroll, and three guards (focus
moved on purpose, focus nowhere, Tab out of the box).
The fields form passed a fresh [] as each field's errors on every render, so
every field re-rendered whenever the form did; one of those extra renders fed
the date picker's delayed refocus. The dist is rebuilt.
Fields form: V2 renders every form with a standard field through ActiveForm,
IdleForm and ChoiceField, so they stay and only the V1 routing changes come
in. wippy-form.vue takes the V1 structure (FormMessage, one notice computed,
no answer-submitted event) and routes a choice-only state to the question
card and any other state to the fields form. FormNotice keeps the V1
severity/message props and the V2 rendering of every field as a disabled
control of its own kind. idle-form.test.ts is kept.

Shared pieces: part-class.ts is replaced by part-attrs.ts everywhere. The
fields form's error text, required marker and banner use ERROR_TEXT_CLASS
and WARN_TEXT_CLASS through FormMessage, and a send clears its previous
server errors as the card does. The density prop and its CSS are removed.

Answer rules: one free-text pipeline on the server (form_text.read_answer,
V1's check_user_text dropped) and one length helper on the client
(exceedsLength and lengthLimitMessage; trimAnswerText and codePointLength
live in text.ts). The V2 serializers and validators stay in answers.ts.

Types and tests: question card files take the choice-only types; the shared
test fixtures are generic over the definition; V2 tests use the shared test
support and answer_admission. A version 2 form is supported, so the
unsupported-version tests use version 3. The date focus tests pin the clock.

Registry: state_service declares the logger module V1 now uses. V2 keeps
its ask_user schema and trait prompt and takes the V1 trait icon. The
package description, props and README cover both renderers in plain words.
The ask_user trait and tool go back to choice questions only, so upgrading
the module does not give an existing agent the standard fields. The new
ask_user_fields trait adds the ask_user_fields tool, which takes choice
questions and text, textarea, number, email, date and checkbox fields.

Both tools share one handler. Each passes the field types it accepts to
definition.normalize, which reports any other known type as
unsupported_type with the accepted list, so an agent that ignores the
schema still cannot create a form with fields through ask_user. The tools
have different names because the agent compiler keeps only the last tool of
a name, and both traits include read_form.
ask_user answered a field of an unknown type with all seven type names,
naming types that tool refuses. Every unsupported_type message now lists
the types the calling tool accepts.
…red views

The question card summary and the answered fields form each had their own
copy of the late notice, delivery text, answered time and its focus handling.
Both now render form-answered-status.vue.
…tCSS config

A checkout nested in another project picked up that project's Tailwind
setup and warned about a missing content option. The build output is
unchanged.
Takes V1 at b1fa43a: the review fixes, the settle order, the delivery retry, the empty Other message and answer validation inside the acceptance transaction. Bundles are rebuilt, and the lock is regenerated.

Keeps the local proxy type shim, because the published 0.0.67 types are choice-only. Points the fixture volume at the checkout, because tests now run from a workspace outside the repository. Fixes number digits for a whole float past 2^63 and updates the runtime probes to 0.3.57a.
…before acceptance

Each standard field type is checked against the definition read under the acceptance lock. A pattern that stops compiling before acceptance answers 500 and stores nothing.
…swers

The read boundary kept only choice shapes, so a stored 0, false, true or 3 was dropped and a read-only form showed Skipped.
…lizer

The card had its own copy of the choice serializer beside serializeAnswers. It now reads stored answers through draftFromAnswers and writes them through serializeAnswers, and QuestionAnswerState only keeps what the card's interaction needs. Nothing rendered changes.
@wippy-fe/theme 0.0.67 puts the theme class on the overlay layer and keeps it current (followTheme in primevue-plugin.ts), so the date field no longer mirrors it. The theme tests now assert on the layer.
string.find returns two values, and the linter reads the second as is_nil's message.
A pattern within the length, repeat and nesting limits could take 217 ms per field under the acceptance lock, and 1.7 s for one form. A pattern now counts at most 75 with every repeat written out, which keeps the check at 4.9 ms on a 2,000 character ASCII answer. MAX_REPEAT drops to 75, because a higher count could not pass.

The tool schema names the limit, and the shared conformance fixture covers it.
The model gets one number: a repeat count and a whole pattern both stop at 100, so a{100} and the D32 repeat limit stay. The worst pattern at this size takes 6.7 ms on a 2,000 character ASCII answer, and the worst whole form takes 81 ms. The 200 character case now uses a class, because 200 literals are over the size limit.
Brings the V1 fixes for the answered-elsewhere notice, the banner after a
rebind and Optional questions. The shared watcher reads hasUnsentInput from
whichever form is active, so the fields form gets the same rule. The bundles
are rebuilt from the merged source.
- A repeat counts its body at least once, so a{0} counts 1. A group of them
  could pass the pattern budget at 100 and compile to about 4,500
  instructions, 34 ms per field on 2,000 characters.
- An exact replay of a form whose stored pattern no longer compiles answers
  500 internal, not 409 request_conflict.
- An unknown field type reports only unsupported_type.
- form_version is checked again against the form read under the lock.
- The ask_user_fields schema and prompt state the empty group, the repeat of
  zero and the email length correctly.
- A form stored by the V1 release, frozen from that code, reads, shows and
  accepts an answer byte for byte as V1 did.
- An agent with both traits compiles to both tools and prompts, and
  ask_user and ask_user_fields share the one form limit of a turn.
- An invalid_default message never repeats the value.
- form_artifact.parse refuses any stored version other than the one the
  definition has. Forms stored by V1 still pass.
- The email syntax compiles through form_pattern.compile, so field_values
  no longer needs the text module.
- form_text owns the digit string comparison and the raw size factor of a
  trimmed answer, and definition.lua owns the list of field types.
- The conformance fixture gains choice answer cases (Other length, note
  length, required, several answers). The client runner runs them, and
  evaluateChoice refuses a note over the limit as the server does.
- The README states what an external TEST_CONFIG must carry.
- Public code no longer names planning documents.
- Screen reader text uses sr-only, so it no longer shows or adds a gap,
  in the fields form and in a V1 form under a notice.
- Retry validates as Submit does, so a value edited into something invalid
  is named on its field and not left out of a one-time answer.
- Submit stays focusable during a send and offline (aria-disabled), and a
  failed send that left no focus gives it to Submit.
- The status region is emptied when a send starts, so a repeated failure
  with the same text is announced.
- Stored text keeps its whitespace in the read-only view.
- Tab and Shift+Tab move inside the calendar in a shadow root.
- A number with digits a JSON number cannot hold is invalid_number.
- field-row and field-item join the styling API, and the stale theme gap
  leaves the README.
- The length message moves to lib/text.ts, the client reads the lengths the
  server always sets, and isBlank is isWhitespaceOnly, as in Lua.
While a send runs, Submit reads "Sending…" and shows a spinner that stops
under reduced motion, with the progress cursor. It stays focusable and
aria-disabled (not disabled), so focus returns to it after a failed send.
The status region says "Sending your answers." only after 2 seconds, so a
fast send is announced once. The new send-sending part and class are
documented in the README.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant