Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

08 — Form Specifications (Search Module)

Specification of the search input (the module's only form element). Backend constraints are exact from search-query.dto.ts; client rules are (proposed) where marked. There is no multi-field form in this module.


1. Search input — the only field

1.1 Server contract (exact)

PropertyValueSource
Nameqsearch-query.dto.ts:6-9
Typestring, optional@IsString @IsOptional (:7-9)
Max lengthnone (unbounded)DTO has no @MaxLength
Min lengthnone (empty allowed)empty/whitespace → empty result, not an error (search.service.ts:28-30)
Other paramsentityType (optional string), page (≥1), limit (1–50)search-query.dto.ts:11-29

1.2 Client rules (proposed) — fill the server's gaps

RuleValueRationale
Trimleading/trailing whitespace stripped before sendserver compares q?.trim() (search.service.ts:28-30) — trailing spaces would still match server-side but inflate tokens
Empty guardnever send blank q; show landing insteadserver returns data: [] (search.service.ts:28-30) — a wasted round trip
Max input length100 charsserver is unbounded; beyond 100 the $text query degrades (search-index.repository.ts:24-33); no server error exists, so cap client-side
Debounce300 ms after last keystroke (06 §1.3)each search = 2 queries (search.service.ts:36-37)
Whitespace collapseinternal runs collapsed to single space (proposed)avoids empty tokens in $text
Min chars1 (no enforced minimum)server matches single characters via fallback regex (search-index.repository.ts:36-50); client still debounces to protect the index

1.3 Validation behavior (client-side, none server-side)

Server-side validation fires only for non-string/negative/non-integer params → 400 VALIDATION_ERROR with per-field details (00-shared/07 §3). The client prevents these by construction (int types on page/limit, string on q). No inline field errors exist on this input; failures surface as screen-level AppErrorState (06 §2.5).

1.4 Special characters

  • Regex fallback risk: the fallback builds { $regex: q, $options: 'i' } from the raw query (search-index.repository.ts:40). Unescaped regex metacharacters (( ) [ ] { } * + ? ^ $ | . \) can throw a server error on that path. The client escapes nothing today — QA-14 §6 covers testing; a client-side escape (proposed) is the mitigation.
  • Text-index behavior: $text tokenizes; punctuation is largely ignored by Mongo (search-index.repository.ts:24-33) — so ADM-20 vs ADM 20 can return different results; fallback covers substring cases.

1.5 Autofill / IME

  • autofillHints: none (search is not a stored identity field).
  • IME composing: debounce timer starts only after composition ends (CJK-safe, 06 §6).
  • textInputAction: search → submits and navigates to /search.
ControlSpec
See-all filtersingle-select of entityType via chip row; maps to entityType param (search-query.dto.ts:11-14); client remembers it in cubit state
Clear✕ button: clears text + entityType, resets to landing, cancels debounce
Example chips (landing)fill bar with sample query, trigger debounce (07 §6)

2. Accessibility of the input

  • Label/hint linked to the field semantics (00-shared/09).
  • Clear and scan buttons are labeled controls, not icon-only.
  • Results count announced via live region after each successful response.
  • Focus order: bar → groups → per-row actions.

3. Data sent vs data shown

FieldSentShown
qtrimmed, whitespace-collapsedas typed (original casing preserved)
entityTypeone of 9 known typesgroup headers + filter chips
page, limitintspagination spinner only