Skip to content

docs: add forms and validation conventions guide - #448

Open
playmaker410 wants to merge 3 commits into
Agentpay-Org:mainfrom
playmaker410:docs/forms-validation-guide
Open

docs: add forms and validation conventions guide#448
playmaker410 wants to merge 3 commits into
Agentpay-Org:mainfrom
playmaker410:docs/forms-validation-guide

Conversation

@playmaker410

Copy link
Copy Markdown

Closes #329

Summary

Adds the forms and validation guide requested in issue #329. Documents the shared validation contract so new forms stop inlining their own checks.

What's changed

docs/forms.md — new guide

  • Section 1 — forms-to-validator mapping table (Create Service, Edit Service, Usage Metering, Webhooks)
  • Section 2 — full signatures and invariants for validateIdentifier, parseNonNegativeInt, parsePositiveInt, including Number() coercion edge cases (hex, binary, leading-plus, trailing .0)
  • Section 3 — error-message conventions: sentence case, trailing period, and the documented inconsistency in parsePositiveInt's default message
  • Section 4TextField ARIA wiring (aria-invalid, aria-describedby, role="alert")
  • Section 5 — decision table: shared helper vs. inline validation
  • Section 6 — end-to-end worked example: state wiring → TextField → submit guard → unit test

docs/components.md

  • Added cross-reference from the TextField entry to docs/forms.md

src/lib/validateNumber.ts

  • Fixed incorrect JSDoc: "1e2" was listed in the Rejected examples but correctly evaluates to the integer 100 and is accepted

src/lib/__tests__/validateNumber.test.ts

  • Added 5 new edge-case tests: ParseResult type assertion, hex/binary coercion (0xff, 0b101), leading-plus (+1, +0), and parsePositiveInt("00000") → rejected
  • Total: 29 tests, all passing

jest.config.ts

  • Locked validateNumber.ts and validateId.ts at ≥ 95% coverage thresholds (statements / branches / lines) and 100% functions

Test output

PASS src/lib/__tests__/validateNumber.test.ts (22 tests)
PASS src/lib/__tests__/validateId.test.ts (7 tests)

validateNumber.ts  100% stmts | 100% branch | 100% funcs | 100% lines
validateId.ts      100% stmts | 100% branch | 100% funcs | 100% lines

npm run lint, npm test, and npm run build all pass. The 3 pre-existing test failures in docs/page.test.tsx, export/page.test.tsx, and events/page.test.tsx are unrelated to this PR and exist on main before this change.

- Add docs/forms.md: validator signatures, error-message conventions,
  TextField ARIA wiring, shared-vs-inline decision table, and a
  worked end-to-end example of adding a validated field
- Update docs/components.md: cross-link to forms.md and expand the
  TextField section with error wiring details
- Expand src/lib/__tests__/validateNumber.test.ts with comprehensive
  edge-case coverage (empty, whitespace, -0, floats, NaN, Infinity,
  scientific notation, leading zeros, safe integers)
- Lock validateNumber.ts and validateId.ts at ≥ 95% in jest.config.ts
  coverage thresholds to prevent regressions
- Fix JSDoc comment in validateNumber.ts: 1e2 is accepted (integer 100),
  not rejected; was incorrectly listed in 'Rejected examples'
- Expand validateNumber.test.ts with 5 new edge-case tests:
  * ParseResult type-level assertion
  * Hex/binary literal coercion behaviour (0xff, 0b101)
  * Leading-plus coercion (+1, +0)
  * parsePositiveInt: leading-zero string resolving to 0 is rejected
- Document Number() coercion edge cases in docs/forms.md
- Note parsePositiveInt error message inconsistency (missing period)
  and the conventions new validators should follow
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.

Document the form validation conventions and shared validators

1 participant