Skip to content

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.md
index 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 the
generated source module in source mode, so applications and the repository's
own 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 violating
callers 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 |