Skip to content

Review of 0.3.1: plan for the defects found #66

Open

Description

@n4ff4h

A review of both packages at d3ba05b (v0.3.1, branch dev), and a plan for what it found.

State of the checks. pnpm lint, pnpm typecheck, node scripts/check-docs.mjs, pnpm test (2,824 passed, 1 skipped), pnpm build, the size budgets and scripts/boost.mjs --check all pass. Everything below is behaviour the current tests don't cover.

How to read this. Paths are under packages/onu/src/ unless they start with packages/ or .github/. Line numbers will drift; re-grep before editing. Each item carries how it was established:

  • [R] reproduced with a throwaway test
  • [C] traced by reading the code
  • [P] plausible, needs a browser or device check before fixing

Constraints. The package has no users, so fix each item the clean way: reshape or rename APIs where that is the better fix, with no aliases and no migration notes. Changesets are still needed. Every fix lands with a test that fails first. The earlier PLAN.md items were re-checked where they overlap and are still fixed, with one exception (1.8).


Part 1: form submission and field wiring

Most of these share one cause: composite controls keep their value in a hidden input, and each one wires that input by hand. Do 1.1 first; it removes several of the others.

  • 1.1 One shared hidden-field helper. Add a single internal component for "the hidden input a composite control submits", and use it everywhere. It must:
    • be disabled when the surrounding FormField is disabled, not only when the control's own disabled is set. Today a disabled FormField still submits amount=5, tags[]=one, sel=x, date=2026-01-05. [R] Affected: components/inputs/number-input.tsx:456, inputs/tags-input.tsx:257, choice/_combobox.tsx:550, date/_picker-shell.tsx:281, inputs/color-picker.tsx:194, inputs/icon-picker.tsx:426, choice/segmented-control.tsx:121, choice/dual-listbox.tsx:426, choice/rating.tsx. Radix-based Select, Checkbox and HiddenInput already do this.
    • let Form and ValidationSummary find the visible control from the field name. Today, after a 422, editing a NumberInput leaves its server error showing (the visible input has name=""), and clicking that error in the summary does nothing because findField skips hidden inputs. [R] components/form/form.tsx:219-228, form/validation.ts:97-106.
  • 1.2 PhoneInput submits the display text, not E.164. name lands on the visible input, so a Maldives number posts 777-1234 and defaultCountry="LK" posts 071 234 5678. Submit the E.164 value through the helper from 1.1. [R] components/inputs/phone-input.tsx:211
  • 1.3 TagsInput with required can never submit natively. required is spread onto the always-empty text box, so checkValidity() is false even with tags. Make it required only while there are no tags. [R] inputs/tags-input.tsx:90,201
  • 1.4 ColorPicker and IconPicker put required/aria-required on a plain <button>. axe reports aria-allowed-attr inside a required FormField. The existing axe tests only scan the unwrapped case; extend them. [R] inputs/color-picker.tsx:129, inputs/icon-picker.tsx:257
  • 1.5 DateRangePicker ignores names unless name is also set, so names={{ from: "start", to: "end" }} submits nothing. [R] date/date-range-picker.tsx:175-180
  • 1.6 Form drops the submitter. new FormData(form) loses <button type="submit" name="action" value="draft">. Pass the submitter. [R] form/form.tsx:214
  • 1.7 Dependent selects wipe their value when parent and child load together (RHF reset(data), an async fetch on an edit page): onValueChange(null) fires and the child is empty. Only clear when the parent changes after a value was already settled. [R] choice/_hooks.ts:15-26, used by searchable-select.tsx:116 and api-select.tsx:274
  • 1.8 Button still lets a caller's data-slot replace its own (old plan item B2 was applied to ui/button.tsx only), so the 44px touch rule stops matching. Same in link-button.tsx. [C] form/button.tsx:110,127
  • 1.9 Caller aria-describedby replaces the merged one in SlugInput and Radio because {...props} comes last. [C] inputs/slug-input.tsx, choice/radio.tsx
  • 1.10 One empty-value convention for selects. Select uses "" and onValueChange(string); SearchableSelect and ApiSelect use null and (value, option). Pick null + (value, option) for all three. [C]

Part 2: input behaviour

  • 2.1 NumberInput
    • A stepper field can't be cleared to retype: value 3 with min={1}, Backspace shows 1, typing 5 gives 15. Clamp on blur, not on every keystroke. [R] inputs/number-input.tsx:274-281
    • Arrow keys round to the step's decimals (10.50 + ArrowUp = 12) while the stepper buttons give 11.5. Use one code path. [R] :286 vs :302
    • \d only matches ASCII digits, so a custom numberLocale with other digits can't re-parse its own draft. [P] :145,424
  • 2.2 SlugInput swallows spaces in manual mode: typing my custom slug gives mycustomslug, and with separator="_" no word break can be typed at all. The current test passes only because it types Title Case. [R] inputs/slug-input.tsx:32-34,130
  • 2.3 TagsInput: Enter adds a disabled suggestion, and arrow keys don't skip disabled rows. Autocomplete already guards this. [R] inputs/tags-input.tsx:131-137
  • 2.4 Autocomplete: the list filter doesn't follow a controlled value. Reset "ap" to "" from the parent, press ArrowDown: the input is empty but only apple is listed. [R] inputs/autocomplete.tsx:112,140-143
  • 2.5 InlineEdit blur handling
    • Blur-save pulls focus back to the display button, so clicking another input after editing lands focus on "Edit …". [R] form/inline-edit.tsx:88-96,116,131
    • With a failing validate, the field refocuses on every blur and the user can only leave with Escape. [R] :123
    • Safari doesn't focus buttons on click, so clicking Cancel may save first. [P] :156
  • 2.6 ReportingPeriodPicker: an abandoned custom click overwrites the real choice. Custom tab, click 12 Mar, switch to Monthly, pick May: the field ends as 12/03/2026 – 12/03/2026. commit() must clear the pending range. [R] date/reporting-period-picker.tsx:113-116,139-147
  • 2.7 DateCalendar: PageUp and arrow overflow ignore canPrev/canNext, so the view pages past min while the Previous button is disabled. [R] date/date-calendar.tsx:352
  • 2.8 HijriDatePicker: inMonth compares against midnight, so a value or "today" with a time opens focused on the 1st of the month. [R] date/hijri-date-picker.tsx:72
  • 2.9 Wizard: Finish can run onComplete twice. The busy flag is cleared before await onComplete(). Keep it set until onComplete settles. [C] components/layout/wizard.tsx:166-181
  • 2.10 SearchBox: clicking ✕ with unsubmitted text fires two searches (the blur submits the draft, then the click submits ""). [C] listing/search-box.tsx:123,132-136

Part 3: Thaana and locale

  • 3.1 The Thaana keyboard never attaches to an input that mounts after the hook runs. The attach effect is keyed on the ref object, whose identity never changes. Take a callback ref (or the element in state) so attaching follows the DOM node.
    • CommandPalette thaana: the input shows lang="dv", dir="rtl" and the toggle, but typing stays Latin, on every open. The existing test only asserts the attributes. [R] thaana/use-thaana-input.ts:57-75, components/overlays/command-palette.tsx:179,316
    • TextInput: when endAddon goes from empty to set the input node is replaced and Thaana stops working on the new one. [R] components/inputs/text-input.tsx:111-133
  • 3.2 Typing on a closed thaana select seeds the search with the Latin key (k, not ކ). [R] components/choice/_combobox.tsx:276-280
  • 3.3 paste: "transliterate" ignores any paste with a newline or tab, so multi-line paste into a Thaana Textarea stays Latin. Allow whitespace in isLatinKeyboardText. [R] thaana/convert.ts:29-31, thaana/attach.ts:129-133
  • 3.4 Composition path (Gboard and other predictive keyboards). Test on a real Android device before changing. thaana/attach.ts:135-151
    • Contenteditable targets return early, although the doc comment at :93-97 says composed words are converted. [C]
    • Re-composing an existing word replaces the wrong range (the range starts at the caret, the word starts before it). [P]
    • A partly-Thaana re-composed word leaves the new Latin letters unconverted. [P]
  • 3.5 Controlled enabled can desync. The shortcut flips the controller's internal state before calling onToggle; with enabled={true} and a parent that ignores the change, the field stays dir="rtl" while typing is Latin. [C] thaana/attach.ts:164-165, thaana/use-thaana-input.ts:38-44
  • 3.6 useFormatCurrency renders the literal common.currency unless another loaded module happens to register the common namespace; a tree-shaken production build can differ from dev. Call registerEnglish({ common }) in i18n/format.ts, and stop excluding i18n/ in english-registry.test.ts:50. [R] i18n/format.ts:92
  • 3.7 Dhivehi date-fns locale. No in-repo caller hits these, but app patterns passed to useFormatDate do. locales/date-fns-dv.ts
    • dayPeriod tests startsWith("a"), so "afternoon" gets the AM label and "midnight" gets PM. [R] :139-143
    • match.day only knows full weekday names, so parse("އާދި", "EEE", …) is Invalid Date. [R] :156
  • 3.8 Glued confirm title. ${label} ${name}? assumes English word order and a Latin ? (same class as old plan item B6, missed there). Non-delete items with confirm: true also get "This can't be undone." Move both into the locale files with placeholders. [C] components/overlays/_menu-items.tsx:171-172
  • 3.9 Numbers and dates formatted with the browser locale, not Onu's. Wrong for dv, and server and client can differ. [C] ui/chart.tsx (~230, the tooltip marked "onu: locale-aware value formatting"), components/listing/data-table.tsx:148
  • 3.10 The on-demand dv load has no rejection handler or retry. One failed chunk load leaves the app RTL with English text for the session. [C] providers/onu-provider.tsx:112-115

Part 4: effects keyed on unstable identities

One pattern: an effect depends on a value that callers naturally write inline, or on the translator t, which is rebuilt whenever provider props change. Fix each by holding the callback or t in a ref (or comparing by value), then grep for the same pattern elsewhere.

  • 4.1 useListingState: an inline paramNames object makes onValueChange fire on every render, which is an endless request loop when the callback fetches and sets state. Under StrictMode it also fires once on mount. [C] components/listing/use-listing-state.ts:239,270-277
  • 4.2 SignaturePad: the pad is recreated, and the drawing wiped, whenever t changes identity (a language switch, or an inline maps={{…}} on OnuProvider re-rendering mid-signature). The hidden input keeps the old signature, so what is shown and what is submitted disagree. [C] media/signature-pad.tsx:130,169
  • 4.3 Editors: recreating the editor discards uncontrolled content. Toggling thaana (for example thaana={locale.code === "dv"}) rebuilds Tiptap from defaultValue while the hidden input still holds the typed HTML. The placeholder also stays in the old language after a locale switch. [C] editor/_use-editor.ts:85,137
  • 4.4 LoadMore auto mode: an inline onLoadMore rebuilds the observer every render, and a new observer reports the visible button straight away, so it can fire repeatedly. [P] components/listing/load-more.tsx:63-85
  • 4.5 useMergedRef drops React 19 ref cleanup functions. A consumer ref that returns a cleanup never has it called and is called with null instead, which leaks observers. [R] hooks/use-merged-ref.ts:5-18

Part 5: listing, files and navigation

  • 5.1 Row click fires for clicks inside the row's portalled menu or confirm dialog. React bubbles through portals to the <tr>/<li>; isInteractiveTarget walks DOM parents and never sees the row. Clicking a confirm dialog's title or backdrop opens or navigates the row mid-confirmation. Ignore events whose DOM target is outside the row. [C] components/listing/data-table.tsx:285-290,449,517, listing/_collection.tsx, listing/_shared.tsx
  • 5.2 Pagination: links built from a Laravel paginator drop the query string. The meta.path-based URL wins over the server's prev/next URLs and links[] is ignored, so /users?search=ali&page=2 links to /users?page=3. A custom pageName breaks too. Build page URLs from the server-provided links. [C] listing/pagination.tsx:95-101,191,210-216
  • 5.3 FileInput dropzone cancels every non-file drop on the page. The document drop listener lacks the hasFiles check its dragover twin has, so dragging text into a textarea or the editor does nothing while a dropzone is mounted. [C] components/files/file-input.tsx:366-369
  • 5.4 A cancelled or removed upload can still land in the value when a custom upload ignores signal: the success branch never checks aborted. In single mode the request that finishes last wins. [C] files/use-files.ts:191-197
  • 5.5 FilterPanel: the badge and "Clear all" act on filters the panel doesn't own (tabs and queryFilters on ListingPage). Scope both to the panel's filters. [C] listing/filter-panel.tsx:244,251-254
  • 5.6 Custom filter render controls get no accessible name. id is documented as "already wired to the filter's label", but the label is a <span>. Render a real <label htmlFor> or pass labelId. [C] listing/listing-types.ts:42, listing/filter-panel.tsx:150,267, listing/_filter-controls.tsx:334-341
  • 5.7 The record link can be hidden. With no primary column, columns[0] carries the row link but the Columns menu lets it be hidden. [C] listing/column-visibility.tsx:52, listing/data-table.tsx:202,216,296-308
  • 5.8 AppSidebar
    • A nested item with onSelect and no href is inert and announced as disabled in the expanded sidebar (it works collapsed and at top level). A third level of items is silently ignored. [C] components/layout/app-sidebar.tsx:377-399
    • badge: 0 draws an empty filled pill on leaf items. [C] :137-154
  • 5.9 TopNav: items with only onSelect render <a href="#">. Render a button. [C] layout/top-nav.tsx:223,252
  • 5.10 normalizeUrl treats host:port as a scheme, so localhost:3000 and example.mv:8080/x are rejected (also in the editor's link dialog). [C] lib/url.ts:25
  • 5.11 Sidebar with collapsible="none" drops the dir prop. [C] ui/sidebar.tsx:181-195

Part 6: focus management

  • 6.1 RecordActionsMenu: triggerRef is never attached to the "More actions" button, so a confirm dialog opens with focus on <body> and closing it leaves focus there. [C] components/listing/record-actions-menu.tsx:47,98
  • 6.2 Editor toolbar loses its only tab stop when the roving item is disabled (caret in a code block): Tab skips the toolbar and Alt+F10 does nothing. Rove to the first enabled item. [C] editor/_toolbar.tsx:345,392,516
  • 6.3 BulkActions: focus drops to <body> when an action's inline form opens or is cancelled. [C] listing/bulk-actions.tsx:217-267
  • 6.4 AdditionalFilesUpload: removing a file at maxFiles loses focus (the picker is still disabled when it is focused). Reuse FileInput's deferred focus. [C] files/additional-files-upload.tsx:146
  • 6.5 ExportMenu: the trigger is disabled as the menu closes, so focus can't return to it. Use aria-disabled, as SearchResults does. [C] listing/export-menu.tsx:93
  • 6.6 Check in a browser: SortableList "Move down" and Alt+ArrowDown probably lose focus after each press (listing/sortable-list.tsx:99-140,245); Form disabling fields while processing drops focus on Enter-submit (form/form.tsx:237); the top-level comment composer doesn't restore focus after posting (display/_composer.tsx:93). [P]
  • 6.7 Slash menu inside a modal dialog. It is portalled to document.body, which a modal Radix dialog makes inert, so it can't be clicked and is hidden from assistive technology. Portal into the dialog. [P] editor/_slash-menu.tsx:165-211

Part 7: server rendering and hydration

  • 7.1 ThemeProvider reads localStorage in its useState initialiser, so a stored dark mismatches the server's system; ThemeToggle variant="segmented" stays on System while the page is dark. Read the stored theme with useSyncExternalStore, like the system theme. [R] providers/theme-provider.tsx:66-68, also ui/sonner.tsx:14
  • 7.2 themeScript and the provider disagree on edge inputs. An invalid stored value paints light in the script but falls back to defaultTheme in the provider (a flash); the script ignores forcedTheme. [C] providers/theme-provider.tsx:105-106
  • 7.3 ShareButtons: server-rendered share links carry an empty URL, and hydration doesn't patch attributes. [C] components/display/share-buttons.tsx:110
  • 7.4 FullCalendar: "agenda on phones" never applies after SSR (useIsMobile() is false during hydration and seeds useState). [C] calendar/full-calendar.tsx:227-231
  • 7.5 new Date() during render in inline DateCalendar and HijriDatePicker: a UTC server and a Maldives client disagree on "today" from 00:00 to 05:00 MVT. [C] date/date-calendar.tsx:188, date/hijri-date-picker.tsx:57
  • 7.6 Pure helpers can't be called from Server Components. The build puts "use client" on every module (packages/onu/vite.config.ts:50), including cn, createTranslator, mergeMessages, themeScript, /thaana conversion and /export. The Next.js guide already documents the themeScript workaround. Emit the banner only for modules that need it, and add a Server Component call of cn and themeScript to e2e/nextjs. [C]
  • 7.7 Add the Part 7 cases to the e2e/nextjs fixture (stored theme, ShareButtons, a phone-width FullCalendar), so they can't regress.

Part 8: charts, maps, media and export

  • 8.1 Excel dates are written in UTC while CSV and PDF use local time. In UTC+5 a date cell "2026-03-12" shows as 2026-03-11 in the .xlsx and datetime cells are 5 hours early. [C] export/excel.ts:72-75, export/columns.ts:77
  • 8.2 A NaN date value aborts the whole PDF export with a RangeError and writes NaN-NaN-NaN to CSV. Validate numeric dates in toDate. [C] export/columns.ts:75
  • 8.3 TimeSeriesChart: interval silently drops rows. "week" drops any row not a whole number of weeks after the first; "day"/"month" keep only the last row per bucket; more than 10,000 steps truncates the newest data. Bucket and aggregate, or reject. [C] charts/time-series-chart.tsx:150-158
  • 8.4 MediaPlayer: changing src doesn't change what plays (swapping <source> children needs .load(); key the media element by source). [C] media/media-player.tsx:153-155
  • 8.5 SignaturePad (with 4.2)
    • Ink is the theme text colour, so a signature drawn in dark mode exports as near-white strokes on transparent, invisible on a white document. Export with a fixed dark ink. [C] media/signature-pad.tsx:121-124,130,180
    • A resize erases a signature loaded from defaultValue while the hidden input keeps it. [C] :139-151
  • 8.6 AvatarUpload: transparent images get a black background (JPEG on an unfilled canvas), and the file is named *.jpg whatever the output type. [C] media/avatar-upload.tsx:123-124, media/crop-image.ts:73-80
  • 8.7 QrCode downloads. media/qr-code.tsx
    • tone="transparent" in dark mode exports light modules on forced white, which doesn't scan. [C] :328-333
    • The SVG download embeds the logo as an external href, a broken image in the saved file. [C] :119
    • Export failures are swallowed with no feedback. [C] :346
    • The object URL is revoked after 0 ms (export/download.ts waits 1000 ms). [P] :208
  • 8.8 QrCodeScanner: continuous mode fires onScan and the announcement four times a second while one code stays in view, and a failed detector load removes the Start button with no retry. [C] media/qr-code-scanner.tsx:166-167,185-188,269
  • 8.9 Maps
    • A map edit deletes a half-entered keyboard shape (fewer than 3 points). [C] maps/_google-adapter.tsx:396-400, maps/_shape-editor.tsx:132-136
    • LiveMap: streamed markers always override markers props and are never removed. [C] maps/live-map.tsx:117-123
    • Geocoding hard-codes region: "mv" regardless of MapProvider region. [C] maps/_google-adapter.tsx:654
    • MapRadius probably reports each programmatic change twice, with mixed old and new halves when centre and radius change together. [P] maps/_google-adapter.tsx:217-238
  • 8.10 Stale read-outs after data changes: TimeSeriesChart zoom range (charts/time-series-chart.tsx:239-241,280, [P]) and MapChart selected region (charts/map-chart.tsx:72,125-133, [C]).
  • 8.11 ImageCropper ignores aspect after mount. [C] media/image-cropper.tsx:87
  • 8.12 Check that "loaded on demand" peers don't break app builds. import() of deck.gl (charts/map-chart.tsx:45) and write-excel-file (export/excel.ts:137) must still resolve at build time; a webpack or Turbopack app using only Recharts charts may fail to build without deck.gl installed. Test with a fixture that installs none of the optional peers; workspace resolution hides it today. [P]
  • 8.13 Rejected async callbacks surface as unhandled rejections in Wizard, LoadMore and the comment composer. [C]

Part 9: MCP server and packaging

  • 9.1 Docs search never matches the page path, and titles are CamelCase, so onu_search_docs("date-picker") doesn't return date-and-time/date-picker in the top 5. The same ranking feeds the "closest matches" hint in onu_get_doc. Index the path and split CamelCase titles; give an exact title word more weight ("Button props" ranks SubmitButton above Button). [R] packages/onu-mcp/src/docs.ts:108-131
  • 9.2 No fallback when project docs fail to load. A typo in ONU_DOCS_DIR or a malformed index.json kills the server with a stack trace; ONU_DOCS_DIR="" reads ./index.json from the cwd while reporting source: "bundled"; one missing .md fails every search. Fall back to the bundled docs with a warning on stderr. [C] packages/onu-mcp/src/docs.ts:59-63, src/index.ts:7
  • 9.3 src/styles/theme.test.ts ships in the npm tarball because files lists src/styles. Exclude test files. [C] packages/onu/package.json

Order and verification

Suggested order: Part 1 (data that reaches the server), Part 4 and 3.1 (data loss and a feature that doesn't work), Part 5, Part 7, then the rest. One PR per part against dev.

After each part:

pnpm lint && pnpm format:check && pnpm typecheck
pnpm --filter @javaabu/onu exec vitest run <the touched folder>
node scripts/check-docs.mjs

At the end: pnpm test && pnpm build && pnpm --filter @javaabu/onu size, pnpm build:web, the e2e/nextjs check and pnpm e2e:chromium.

Not covered by this review

  • Dhivehi wording, styles/*.css beyond base.css and tailwind.css, and most stock ui/* code outside the // onu: changes.
  • Unread or only skimmed: about half of components/layout and components/display (for example side-nav, timeline, breadcrumbs, toast, callout), files/attachment-preview, parts of maps (address-input, route-stop-editor, geo), editor/translations-editor, editor/thaana-keyboard, and the auth forms.
  • web, figma, scripts and the Playwright suite were not reviewed, and nothing was run in a real browser or on a device, which is why the [P] items need that check first.

Activity

  1. added 9 commits that reference this issue on Nov 17, 2026
  2. n4ff4h commented on Nov 18, 2026

    @n4ff4h
    CollaboratorAuthor

    Every [R] and [C] item in Parts 1–9 is fixed and merged into dev. Each has a test that failed before the fix, its own commit and a changeset.

    Part PR
    1. Form submission and field wiring #67
    2. Input behaviour #70
    3. Thaana and locale #72
    4. Effects keyed on unstable identities #69
    5. Listing, files and navigation #71
    6. Focus management #73
    7. Server rendering and hydration #75
    8. Charts, maps, media and export #76
    9. MCP server and packaging #74

    Not changed. These are marked [P] or need a browser or device check first:

    • 2.1 third bullet (\d and numberLocale)
    • 2.5 third bullet (Safari: clicking Cancel)
    • 3.4 (Gboard composition: all three bullets)
    • 4.4 (LoadMore auto observer)
    • 6.6 (SortableList, Form Enter-submit, comment composer focus)
    • 6.7 (slash menu inside a modal dialog)
    • 8.7 last bullet (object URL revoked after 0 ms)
    • 8.9 last bullet (MapRadius double report)
    • 8.10 TimeSeriesChart half (zoom range)
    • 8.12 (optional peers in app builds)

    Verified on the merged dev tree (ee2fd38):

    • Passed: lint, format check, typecheck, check-docs, pnpm test (2,955 passed, 1 skipped; MCP 24 passed), build, size budgets (none raised), build:web, and the e2e/nextjs build and SSR check in English and Dhivehi.
    • pnpm e2e:chromium a11y and Thaana specs: 527 passed.
    • Not compared: visual screenshots. They need the CI baselines.

    Needs review: the new Dhivehi strings, including the 3.8 confirm-title word order and the four 8.x error messages, were written without a native speaker.

  3. added a commit that references this issue on Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions