An open source design system that's fully customizable and agent ready
TypeScript
architecture(internationalization): type-to-select ignores marks in every locale (INV17) (#9009)
Cindy Zhangcd40b8b2e46e
diff --git a/docs/architecture/internationalization.md b/docs/architecture/internationalization.mdindex d12bc1e85f..1316faa9ba 100644--- a/docs/architecture/internationalization.md+++ b/docs/architecture/internationalization.md@@ -64,7 +64,8 @@ deciding_specs: []"INV7","INV8","INV9",- "INV10"+ "INV10",+ "INV17"],"compatibility": ["INV2", "INV9", "INV10"],"layout": ["INV11", "INV12"],@@ -76,15 +77,15 @@ deciding_specs: []## Contract at a glance-| Area | Contract |-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Governing contract | `component:InternationalizationProvider` owns provider behavior. This record defines the intended internationalization contract and the implemented runtime-catalog delivery boundary; it does not certify every existing consumer's conformance. |-| System behavior | Astryx-owned strings resolve through per-locale overrides, supplied catalogs, then shipped English, walking exact → parent locale. Locale-sensitive operations (date, time, number, list, collation) receive the provider locale directly, with no catalog or override step; legacy pure helpers with an optional locale default deterministically to English, except the known `currency()` gap recorded under INV9. Without a provider the result is deterministic English. Authored catalogs are rich (`defaultMessage` + `description`); shipped runtime catalogs are generated string maps derived from them. Messages are ICU MessageFormat 1 strings. `PlainDate` stays Gregorian. Rendered direction comes from the DOM. |-| End-user impact | People using a non-English locale see Astryx interface text, formats, and sort order in that locale wherever a translation exists and English otherwise; layout and mirroring follow the document direction they are reading in. |-| Builder impact | Render one `InternationalizationProvider` and keep DOM `dir` aligned with it. Import a shipped locale from `@astryxdesign/core/locales/<tag>.generated.js` (string map) or `<tag>.json` (rich); both are accepted. Pass the provider locale to Astryx-owned `Intl` calls. Add Astryx strings to `en.json` with a description; never edit generated modules. No separate locale packages and no second Astryx runtime. |-| Compatibility/readiness | Released provider, hooks, subpath, rich JSON exports, and the rich context shape are preserved; `RuntimeCatalog`, `ProviderMessagesByLocale`, and the `*.generated.js` exports are additive. A server/RSC translation runtime and an external-runtime adapter remain separate decisions (INV13, INV14). |-| Review checks | Reject Astryx-owned text or announcements built from literals, concatenation, or hand-rolled plurals instead of a catalog message (INV1a); locale-sensitive `Intl` or prototype calls outside the named shared helpers, or a public date helper called without its provider-locale argument (INV8); a parallel or replacement runtime without a migration decision (INV2); implicit host-locale reads (INV3); non-string message output (INV7); a translation catalog that adds stale keys or changes an ICU contract (INV6); a hand-edited, committed, or description-carrying generated module, or a changed rich export path (INV15); locale silently changing `PlainDate` calendar semantics (INV10); render-time provider direction driving geometry (INV11); the provider mutating DOM `dir` (INV12). |-| Governing rules | No deciding system spec. |+| Area | Contract |+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Governing contract | `component:InternationalizationProvider` owns provider behavior. This record defines the intended internationalization contract and the implemented runtime-catalog delivery boundary; it does not certify every existing consumer's conformance. |+| System behavior | Astryx-owned strings resolve through per-locale overrides, supplied catalogs, then shipped English, walking exact → parent locale. Locale-sensitive operations (date, time, number, list, collation) receive the provider locale directly, with no catalog or override step; legacy pure helpers with an optional locale default deterministically to English, except the known `currency()` gap recorded under INV9. Without a provider the result is deterministic English. Authored catalogs are rich (`defaultMessage` + `description`); shipped runtime catalogs are generated string maps derived from them. Messages are ICU MessageFormat 1 strings. `PlainDate` stays Gregorian. Rendered direction comes from the DOM. |+| End-user impact | People using a non-English locale see Astryx interface text, formats, and sort order in that locale wherever a translation exists and English otherwise; layout and mirroring follow the document direction they are reading in. |+| Builder impact | Render one `InternationalizationProvider` and keep DOM `dir` aligned with it. Import a shipped locale from `@astryxdesign/core/locales/<tag>.generated.js` (string map) or `<tag>.json` (rich); both are accepted. Pass the provider locale to Astryx-owned `Intl` calls. Add Astryx strings to `en.json` with a description; never edit generated modules. No separate locale packages and no second Astryx runtime. |+| Compatibility/readiness | Released provider, hooks, subpath, rich JSON exports, and the rich context shape are preserved; `RuntimeCatalog`, `ProviderMessagesByLocale`, and the `*.generated.js` exports are additive. A server/RSC translation runtime and an external-runtime adapter remain separate decisions (INV13, INV14). INV17 is not implemented yet: `useTypeahead`, `useTreeFocus` and MultiSelector's own handler still compare a plain lowercase prefix; adopting it replaces the documented "starts with" matching of the released `useTypeahead` and `useTreeFocus` hooks, and its tests are pending. |+| Review checks | Reject Astryx-owned text or announcements built from literals, concatenation, or hand-rolled plurals instead of a catalog message (INV1a); locale-sensitive `Intl` or prototype calls outside the named shared helpers, or a public date helper called without its provider-locale argument (INV8); a parallel or replacement runtime without a migration decision (INV2); implicit host-locale reads (INV3); non-string message output (INV7); a translation catalog that adds stale keys or changes an ICU contract (INV6); a hand-edited, committed, or description-carrying generated module, or a changed rich export path (INV15); locale silently changing `PlainDate` calendar semantics (INV10); render-time provider direction driving geometry (INV11); the provider mutating DOM `dir` (INV12); type-to-select that misses a marked or stroked first letter, or a fold that reaches sorting or displayed text (INV17). |+| Governing rules | No deciding system spec. |This table is a review projection; the body below is authoritative.@@ -293,6 +294,22 @@ for all 30 shipped locales plus `pseudo`.authored file and `@astryxdesign/core/locales/<tag>.generated.js` to thegenerated source module in source mode, so applications and the repository'sown apps import either form the same way in development and production.+- **INV17 — Type-to-select ignores marks.** Everywhere Core moves to an item+ when a person types its first letters, the typed letters and each item's label+ are compared after folding, the same way in every locale. That covers the+ public `useTypeahead` and `useTreeFocus` hooks and every collection with+ type-to-select, including Selector, MultiSelector, DropdownMenu, ContextMenu+ and TreeList. Folding ignores case; removes the combining marks left by+ canonical decomposition (U+0300–U+036F), in any script; maps exactly six Latin+ letters with a stroke or bar to their base letter (đ→d, ł→l, ø→o, ħ→h, ŧ→t,+ ƀ→b), in either case; and maps Turkish dotless ı and dotted İ to i. So "d"+ reaches "Đào", "a" reaches "Ánh" and "Ä", "l" reaches "Łódź", and "i" or "ı"+ reaches "Isparta" and "İzmir". When the typed letters include a diacritic, a+ stroked letter, ı or İ, items that match them exactly come first; for that+ preference case pairs the Turkish way, ı with I and İ with i, so "ı" over+ "İzmir, Isparta" lands on Isparta and "İ" over "Isparta, İzmir" lands on+ İzmir. INV17 does not change sorting, search filtering or displayed text. One+ shared folding helper serves every path, so they all match the same way.## Change coupling@@ -376,14 +393,15 @@ consumer or every edge case conforms. Helper admission defines responsibility;review and regression tests verify caller behavior. Missing evidence or violatingcallers remain conformance work and do not relax INV1a, INV8, INV9, or INV10.-| Invariant | Evidence | Failure signal |-| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| INV1, INV1a, INV7 | hardcoded-string lint, catalog tests, component translation tests with a non-English provider | Astryx-owned text bypasses the catalog, an announcement or count is assembled from fragments or a hand-rolled plural, or non-string output reaches visible/AT attributes |-| INV2, INV13, INV14 | export drift checks, public i18n tests, compatibility review | A parallel/replacement runtime lands without migration, or client hooks claim server behavior |-| INV3–INV5 | resolver and provider rerender tests | no-provider output depends on the host, locale swaps stay stale, fallback order changes, or malformed-locale behavior is described as graceful |-| INV6 | `check:i18n-catalog`, key-format lint, and focused mutation tests | stale/malformed keys, malformed ICU, or source/translation runtime-contract drift passes CI |-| INV15 | generator tests, `check:i18n-runtime`, package-export drift check, provider/resolver runtime-catalog tests | a generated module carries descriptions or is committed, a malformed entry projects instead of failing, a rich export path changes, or a `RuntimeCatalog` input is rejected or leaks a non-rich context shape |-| INV16 | build-plugin unit and real-build tests | a rich or generated locale import fails to resolve through the standard plugin |-| INV8, INV9 | raw-Intl-locale lint (module allowlist plus date-helper locale-argument check) and provider-locale regression tests, including a server/client render pair | Astryx output follows the host locale, raw `Intl` appears outside a named formatter module, an owned call omits the locale argument, or server and client output differ for the same provider locale |-| INV10 | PlainDate and built-in date formatter tests, including locales with non-Gregorian defaults | locale selects a non-Gregorian built-in date display, changes PlainDate calendar semantics, or loses the explicit low-level display override |-| INV11, INV12 | direction helper/provider tests plus rendered RTL audit | component layout reads provider direction instead of the region, provider mutates DOM, or overrides stop composing |+| Invariant | Evidence | Failure signal |+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| INV1, INV1a, INV7 | hardcoded-string lint, catalog tests, component translation tests with a non-English provider | Astryx-owned text bypasses the catalog, an announcement or count is assembled from fragments or a hand-rolled plural, or non-string output reaches visible/AT attributes |+| INV2, INV13, INV14 | export drift checks, public i18n tests, compatibility review | A parallel/replacement runtime lands without migration, or client hooks claim server behavior |+| INV3–INV5 | resolver and provider rerender tests | no-provider output depends on the host, locale swaps stay stale, fallback order changes, or malformed-locale behavior is described as graceful |+| INV6 | `check:i18n-catalog`, key-format lint, and focused mutation tests | stale/malformed keys, malformed ICU, or source/translation runtime-contract drift passes CI |+| INV15 | generator tests, `check:i18n-runtime`, package-export drift check, provider/resolver runtime-catalog tests | a generated module carries descriptions or is committed, a malformed entry projects instead of failing, a rich export path changes, or a `RuntimeCatalog` input is rejected or leaks a non-rich context shape |+| INV16 | build-plugin unit and real-build tests | a rich or generated locale import fails to resolve through the standard plugin |+| INV8, INV9 | raw-Intl-locale lint (module allowlist plus date-helper locale-argument check) and provider-locale regression tests, including a server/client render pair | Astryx output follows the host locale, raw `Intl` appears outside a named formatter module, an owned call omits the locale argument, or server and client output differ for the same provider locale |+| INV10 | PlainDate and built-in date formatter tests, including locales with non-Gregorian defaults | locale selects a non-Gregorian built-in date display, changes PlainDate calendar semantics, or loses the explicit low-level display override |+| INV11, INV12 | direction helper/provider tests plus rendered RTL audit | component layout reads provider direction instead of the region, provider mutates DOM, or overrides stop composing |+| INV17 | `useTypeahead` and `useTreeFocus` tests and type-to-select tests in Selector, MultiSelector, DropdownMenu and TreeList, one case each: a combining mark ("a" reaches "Ánh"); each stroked letter (đ, ł, ø, ħ, ŧ, ƀ); ı and İ ("i" and "ı" reach "Isparta" and "İzmir"); and a typed diacritic, stroked letter, ı or İ preferring the exact match ("đ" reaches "Đào" before "Dung", "ı" reaches "Isparta" before "İzmir", "İ" reaches "İzmir" before "Isparta"); under en, vi, pl, sv and tr providers | a plain letter misses a marked or stroked first letter in any locale, i or ı misses an İ or I label, a typed diacritic, stroked letter, ı or İ does not prefer the exact match, ı or İ pairs case the non-Turkish way, two paths disagree, or folding reaches sorting or displayed text |