From 1f8554ad1b15b82b76dd06cf1f68d8b8923c1f57 Mon Sep 17 00:00:00 2001 From: Noel Chou Date: Mon, 7 Oct 2024 09:46:14 -0400 Subject: [PATCH] Readmes and reorganization --- README.md | 48 ++++- components/language-chooser/README.md | 43 ----- .../common/find-language/README.md | 145 +++++++++++++++ .../getShortestSufficientLangtag.ts | 2 +- .../common/find-language/langtagProcessing.ts | 14 +- .../{ => language-data}/iso-639-3.tab | 0 .../{ => language-data}/langtags.txt | 0 .../shortestTagLookups.json | 0 .../find-language}/macrolanguageNotes.md | 0 .../common/find-language/scripts.json | 173 ------------------ .../language-chooser-react-hook/README.md | 41 +++++ .../useLanguageChooser.tsx | 4 +- .../language-chooser-react-mui/README.md | 65 +++++++ .../src/CustomizeLanguageDialog.tsx | 2 +- 14 files changed, 303 insertions(+), 234 deletions(-) delete mode 100644 components/language-chooser/README.md rename components/language-chooser/common/find-language/{ => language-data}/iso-639-3.tab (100%) rename components/language-chooser/common/find-language/{ => language-data}/langtags.txt (100%) rename components/language-chooser/common/find-language/{ => language-data}/shortestTagLookups.json (100%) rename components/language-chooser/{ => common/find-language}/macrolanguageNotes.md (100%) delete mode 100644 components/language-chooser/common/find-language/scripts.json create mode 100644 components/language-chooser/react/common/language-chooser-react-hook/README.md create mode 100644 components/language-chooser/react/language-chooser-react-mui/README.md diff --git a/README.md b/README.md index b68c572..9d29924 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,49 @@ +> [!warning] +> This project is currently under development and not ready for public use. + # Ethnolib -This is a small collection of browser components for language apps. Each is published to its own npm package. +Ethnolib is a small collection of browser components for language apps. Each component may be published to its own npm package. -> [!warning] -> This project is currently under development and not ready for public use. +## Components + +### [Find-Language](components/language-chooser/common/find-language/README.md) + +A package for fuzzy-searching for languages, with language database based on [langtags.json](https://github.com/silnrsi/langtags). It also includes various utilities for working with language tags and language info. + +### [Language Chooser React Hook](components/language-chooser/react/common/language-chooser-react-hook/README.md) -## About the monorepo +A React hook that provides the logic for a language chooser component. It utilizes the `find-language` component. -Ethnolib is a [monorepo](https://nx.dev/concepts/decisions/why-monorepos) using nx. +### [MUI Language Chooser](components/language-chooser/react/language-chooser-react-mui/README.md) + +A MUI styled language chooser interface, initially developed for use in [BloomDesktop](https://github.com/BloomBooks/BloomDesktop). It uses the `language-chooser-react-hook` component. + +## Development + +Ethnolib is a [monorepo using nx](https://nx.dev/concepts/decisions/why-monorepos), with npm for package management. We recommend installing nx globally. -`npm i -g nx` +`npm i -g nx`. If you prefer not to, you can simply prefix all commands with with `npx` instead. + +Nx caches builds for efficiency. To clear the local cache, run `nx reset`. + +Use nx to build or run a hot-reload development server. For example, to build or run the MUI language chooser demo: + +``` +nx build @ethnolib/language-chooser-react-mui +``` + +or -But if you don't, you can just prefix all the commands with `npx` +``` +nx dev @ethnolib/language-chooser-react-mui +``` -Nx caches builds for efficiency. If at any point you need to clear your local cache, run `nx reset` +### Dependency Versions -## Language Chooser +We are currently having all packages manage their own dependencies in their package level `package.json` files, but keeping them all on the same versions of commonly used packages for compatibility. Current versions: -See [language-chooser/README.md](components/language-chooser/README.md) + "react": "^17.0.2", + "@mui/material": "^5.15.19", + "@emotion/react": "^11.11.4", diff --git a/components/language-chooser/README.md b/components/language-chooser/README.md deleted file mode 100644 index de5296e..0000000 --- a/components/language-chooser/README.md +++ /dev/null @@ -1,43 +0,0 @@ -# Language Chooser - -This project was initially developed for use in [BloomDesktop](https://github.com/BloomBooks/BloomDesktop). - -The `language-chooser/common/find-language` module contains the logic for fuzzy-searching languages. This module is designed to be published independently and can be utilized by various frontends. The language database is based on [langtags.json](https://github.com/silnrsi/langtags) and also references [langtags.txt](https://github.com/silnrsi/langtags/blob/master/doc/tagging.md#langtagstxt). It includes various methods for adjusting search results to handle special cases, such as sign languages and very common languages. Currently, edge cases in the search results are adjusted for Bloom’s use case by the `defaultSearchResultModifier`, which: - -- Ensures the English result comes up on top when the user starts typing "English" -- Ensures the French result comes up on top when the user starts typing "French", "Francais" or "Français" -- Simplifies English and French entries by removing region lists and most alternative names -- Excludes certain langtags.json entries that don't represent specific extant human languages, such as zxx (no linguistic content) or ang (old english) -- Filters out Braille and script codes that do not refer to specific relevant scripts from script options - -The `searchResultModifiers.ts` file includes various helper methods that can be used to create modifiers suitable for different use cases. - -The `language-chooser/react/language-chooser-react-mui` is a React component which uses the `language-chooser/common/find-language` logic to present a language chooser interface. - -**See demo on Storybook at [https://sillsdev.github.io/EthnoLib/](https://sillsdev.github.io/EthnoLib/)** - -For details of macrolanguage handling, see [macrolanguageNotes.md](macrolanguageNotes.md). - -## Project status - -> [!warning] -> This project is currently under development and not ready for public use. - -## Developing - -First, set up nx if you haven't done so already (see [README.md](../../README.md)). - -We recommend installing nx globally, but if you haven't, you can just prefix all the commands with `npx` - -Although we recommend installing nx globally, you can alternatively run the nx commands without a global installation by prefixing them with `npx`, e.g. `npx nx dev @ethnolib/language-chooser-react-mui`. - -To locally run a hot-reloading demo of the MUI language chooser: `nx dev @ethnolib/language-chooser-react-mui` - -If you make changes to the `find-language` package, you will need to run `nx build @ethnolib/find-language` each time for the frontend (e.g. react mui language chooser demo) to incorporate those changes. - -If you modify [langtagProcessing.ts](common/find-language/langtagProcessing.ts), run `npm run find-language/common/langtag-processing` to update [languageData.json](common/find-language/languageData.json). - -## Unit tests - -Language chooser uses vitest for unit testing. To run tests, use: -`nx test @ethnolib/find-language` diff --git a/components/language-chooser/common/find-language/README.md b/components/language-chooser/common/find-language/README.md index 2f2586c..f32c6ca 100644 --- a/components/language-chooser/common/find-language/README.md +++ b/components/language-chooser/common/find-language/README.md @@ -1,2 +1,147 @@ > [!warning] > This project is currently under development and not ready for public use. + +# Find-Language + +This component contains the logic for fuzzy-searching languages, designed for use by frontend language choosers. The language database is based on [langtags.json](https://github.com/silnrsi/langtags) and also references [langtags.txt](https://github.com/silnrsi/langtags/blob/master/doc/tagging.md#langtagstxt). We use [fuse.js](https://fusejs.io/) for fuzzy-searching. + +It also contains various utilities for working with language tags and language information. + +This project was initially developed for use in [BloomDesktop](https://github.com/BloomBooks/BloomDesktop). + +## Usage + +### Installation + +`npm i @ethnolib/find-language` + +### Searching for languages + +Use `searchForLanguage` to search for languages by name (including autonyms, exonyms, or alternative names), associated regions, or ISO 639 tags matching the search string argument. It returns a `FuseResult[]`, which we recommend passing into a search result modifier. See details in Search Result Modification section. + +### Search Result Modification + +This package includes various methods for adjusting search results to handle special cases, such as sign languages and very common languages. Currently, edge cases in the search results are adjusted for Bloom’s use case by the `defaultSearchResultModifier`, which: + +- Demarcates portions (substrings) of results which match the search string. For example, if the search string is "nglis" then any instance of "English" would be marked as "E[nglis]h" +- Ensures the English result is the first result when the user starts typing "English" +- Ensures the French result is the first result when the user starts typing "French", "Francais" or "Français" +- Simplifies English and French entries by removing region lists and most alternative names +- Excludes certain langtags.json entries that don't represent specific extant human languages, such as zxx (no linguistic content) or ang (Old English) +- Filters out Braille and script codes that do not refer to specific relevant scripts from script options + +The `searchResultModifiers.ts` file includes various helper methods that can be used to create modifiers suitable for different use cases. + +### Macrolanguages + +For details of macrolanguage handling, see [macrolanguageNotes.md](macrolanguageNotes.md). + +### Example + +``` +import { + searchForLanguage, + defaultSearchResultModifier, + stripResultMetadata, + ILanguage, +} from '@ethnolib/find-language'; +import { FuseResult } from 'fuse.js'; + + const searchString = "englisj"; //Fuzzy search will still find English + const fuseSearchResults: FuseResult[] = searchForLanguage(searchString); + const defaultModifiedSearchResults: ILanguage[] = defaultSearchResultModifier(fuseSearchResults); + const unmodifiedSearchResults: ILanguage[] = stripResultMetadata(defaultModifiedSearchResults); + +``` + +In default modification, much of the language info is stripped from the English and French results for simplicity. It also adds bracket demarcation of search string match. See the section on Search Result Modification for details. + +`defaultModifiedSearchResults[0]`: + +``` + { + "exonym": "[Engl]i[sh]", + "iso639_3_code": "eng", + "languageSubtag": "en", + "regionNames": "", + "names": [], + "scripts": [ + { + "code": "Latn", + "name": "Latin" + } + ], + "variants": "", + "alternativeTags": [] + } +``` + +Original English result, `unmodifiedSearchResults[0]` (truncated to save space): + +``` + { + "autonym": "English", + "exonym": "English", + "iso639_3_code": "eng", + "languageSubtag": "en", + "regionNames": "United States, World, Europe, United Arab Emirates, Antigua and Barbuda, ...", + "scripts": [ + { + "code": "Latn", + "name": "Latin" + }, + { + "code": "Brai", + "name": "Braille" + }, + { + "code": "Dsrt", + "name": "Deseret (Mormon)" + }, + { + "code": "Dupl", + "name": "Duployan stenography Duployan shorthand" + }, + ... + ], + "names": [ + "Anglais", + "Angleščina", + "Anglisy", + "Angličtina", + "Anglų", + "Angol", + ...], + "alternativeTags": [ + "en-Latn", + "en-US" + ] + } + +``` + +## Development + +See the main [README](../../../../README.md). + +### Language data processing pipeline + +If you modify [langtagProcessing.ts](./langtagProcessing.ts), run `npm run find-language/common/langtag-processing` to update [languageData.json](language-data/languageData.json) and [shortestTagLookups.json](language-data/shortestTagLookups.json). + +#### ISO-639-3 language consolidation + +find-language searches languages included in the ISO-639-3 standard; every result returned will have a unique ISO-639-3 code. The entries listed in our source database, langtags.json, are combinations of languages, scripts, regions, and/or variants. [langtagProcessing.ts](./langtagProcessing.ts) consolidates these entries by their ISO-639-3 code and saves the result to [languageData.json](language-data/languageData.json) for searching. For example, langtags.json has separate entries for Abhaz with Cyrillic script, Abhaz with Georgian script, and Abhaz with Latin script. langtagProcessing.ts will combine these into a single entry which lists all three possible scripts and has the superset of the names, regions, etc. of the three entries from langtags.json. This way the search results will contain at most one entry for the language Abhaz. + +#### Language tag shortening + +The [createTag](./languageTagUtils.ts) function in this package will return the shortest (and thus preferred) tag for a given language/script/region/dialect combination. For example, given language code "emm" (Mamulique), script code "Latn" (Latin) and region code "MX" (Mexico), `createTag` will return "emm" because it is the preferred equivalent tag for emm-Latn-MX. + +[langtags.txt](https://github.com/silnrsi/langtags/blob/master/doc/tagging.md#langtagstxt) lists equivalent language tags. langtagProcessing.ts reformats it into [shortestTagLookups.json](language-data/shortestTagLookups.json) which we use for mapping language tags to their shortest equivalent. + +### Unit tests + +`Find-language` uses Vitest for unit testing. Use nx to run tests: + +``` +nx test @ethnolib/find-language +``` diff --git a/components/language-chooser/common/find-language/getShortestSufficientLangtag.ts b/components/language-chooser/common/find-language/getShortestSufficientLangtag.ts index 061be62..4b96b93 100644 --- a/components/language-chooser/common/find-language/getShortestSufficientLangtag.ts +++ b/components/language-chooser/common/find-language/getShortestSufficientLangtag.ts @@ -1,4 +1,4 @@ -import shortestTags from "./shortestTagLookups.json" assert { type: "json" }; +import shortestTags from "./language-data/shortestTagLookups.json" assert { type: "json" }; const shortPreferredTagLookup = new Map(); for (const tagset of shortestTags) { diff --git a/components/language-chooser/common/find-language/langtagProcessing.ts b/components/language-chooser/common/find-language/langtagProcessing.ts index de271a1..c7638b8 100644 --- a/components/language-chooser/common/find-language/langtagProcessing.ts +++ b/components/language-chooser/common/find-language/langtagProcessing.ts @@ -22,7 +22,10 @@ const scriptNames = iso15924.reduce( function getIso639_3CodeDetails() { const codeDetails = new Set(); // downloaded from https://iso639-3.sil.org/sites/iso639-3/files/downloads/iso-639-3.tab - const codeDetailsFile = fs.readFileSync("iso-639-3.tab", "utf8"); + const codeDetailsFile = fs.readFileSync( + "language-data/iso-639-3.tab", + "utf8" + ); for (const line of codeDetailsFile.split("\n")) { if (line.length === 0) { continue; @@ -83,7 +86,7 @@ function autonymOrFallback(entry: any, fallback: string) { return entry.localnames ? entry.localnames[0] : undefined ?? fallback; } -// We want to have one entry for every ISO 630-3 code, whereas langtags.json sometimes has multiple entries per code +// We want to have one entry for every ISO 639-3 code, whereas langtags.json sometimes has multiple entries per code // Combine entry into the entry with matching ISO 630-3 code in langs if there is one, otherwise create a new entry function addOrCombineLangtagsEntry(entry, langs) { if (!entry.iso639_3) { @@ -222,7 +225,7 @@ function parseLangtagsJson() { } function parseLangTagsTxt() { - const langTagsTxtRaw = fs.readFileSync("langtags.txt", "utf8"); + const langTagsTxtRaw = fs.readFileSync("language-data/langtags.txt", "utf8"); const langTagsTxt = langTagsTxtRaw.replaceAll("*", ""); const lines = langTagsTxt.split("\n"); const tagLookups = []; @@ -233,7 +236,10 @@ function parseLangTagsTxt() { allTags: tags, }); } - fs.writeFileSync("shortestTagLookups.json", JSON.stringify(tagLookups)); + fs.writeFileSync( + "language-data/shortestTagLookups.json", + JSON.stringify(tagLookups) + ); } parseLangtagsJson(); diff --git a/components/language-chooser/common/find-language/iso-639-3.tab b/components/language-chooser/common/find-language/language-data/iso-639-3.tab similarity index 100% rename from components/language-chooser/common/find-language/iso-639-3.tab rename to components/language-chooser/common/find-language/language-data/iso-639-3.tab diff --git a/components/language-chooser/common/find-language/langtags.txt b/components/language-chooser/common/find-language/language-data/langtags.txt similarity index 100% rename from components/language-chooser/common/find-language/langtags.txt rename to components/language-chooser/common/find-language/language-data/langtags.txt diff --git a/components/language-chooser/common/find-language/shortestTagLookups.json b/components/language-chooser/common/find-language/language-data/shortestTagLookups.json similarity index 100% rename from components/language-chooser/common/find-language/shortestTagLookups.json rename to components/language-chooser/common/find-language/language-data/shortestTagLookups.json diff --git a/components/language-chooser/macrolanguageNotes.md b/components/language-chooser/common/find-language/macrolanguageNotes.md similarity index 100% rename from components/language-chooser/macrolanguageNotes.md rename to components/language-chooser/common/find-language/macrolanguageNotes.md diff --git a/components/language-chooser/common/find-language/scripts.json b/components/language-chooser/common/find-language/scripts.json deleted file mode 100644 index e023db0..0000000 --- a/components/language-chooser/common/find-language/scripts.json +++ /dev/null @@ -1,173 +0,0 @@ -Adlam -Afaka -Arabic -Armenian -Avestan -Balinese -Bamum -Bassa Vah -Batak -Bengali (Bangla) -Bhaiksuki -Bopomofo -Brahmi -Braille -Buginese -Buhid -Caucasian Albanian -Chakma -Cham -Cherokee -Chisoi -Chorasmian -Cirth -Code for uncoded script -Code for undetermined script -Code for unwritten documents -Coptic -Cypriot syllabary -Cyrillic -Cyrillic (Old Church Slavonic variant) -Deseret (Mormon) -Devanagari (Nagari) -Dives Akuru -Dogra -Duployan shorthand, Duployan stenography -Elbasan -Elymaic -Ethiopic (Geʻez) -Garay -Georgian (Mkhedruli and Mtavruli) -Glagolitic -Grantha -Greek -Gujarati -Gunjala Gondi -Gurmukhi -Gurung Khema -Han (Hanzi, Kanji, Hanja) -Han (Simplified variant) -Han (Traditional variant) -Han with Bopomofo (alias for Han + Bopomofo) -Hangul (Hangŭl, Hangeul) -Hanifi Rohingya -Hanunoo (Hanunóo) -Hatran -Hebrew -Imperial Aramaic -Inscriptional Pahlavi -Japanese (alias for Han + Hiragana + Katakana) -Javanese -Kaithi -Kannada -Katakana -Kawi -Kayah Li -Kharoshthi -Khitan large script -Khitan small script -Khmer -Khojki -Khudawadi, Sindhi -Khutsuri (Asomtavruli and Nuskhuri) -Kirat Rai -Klingon (KLI pIqaD) -Korean (alias for Hangul + Han) -Lao -Latin -Latin (Fraktur variant) -Latin (Gaelic variant) -Leke -Lepcha (Róng) -Limbu -Linear B -Lisu (Fraser) -Loma -Mahajani -Makasar -Malayalam -Manichaean -Marchen -Masaram Gondi -Mathematical notation -Meitei Mayek (Meithei, Meetei) -Mende Kikakui -Miao (Pollard) -Modi, Moḍī -Mongolian -Mro, Mru -Multani -Myanmar (Burmese) -Nabataean -Nag Mundari -Nandinagari -Naxi Dongba (na²¹ɕi³³ to³³ba²¹, Nakhi Tomba) -Naxi Geba (na²¹ɕi³³ gʌ²¹ba²¹, 'Na-'Khi ²Ggŏ-¹baw, Nakhi Geba) -New Tai Lue -Newa, Newar, Newari, Nepāla lipi -Nyiakeng Puachue Hmong -N’Ko -Ogham -Ol Chiki (Ol Cemet’, Ol, Santali) -Ol Onal -Old Hungarian (Hungarian Runic) -Old Italic (Etruscan, Oscan, etc.) -Old Permic -Old Sogdian -Old Uyghur -Oriya (Odia) -Osage -Osmanya -Pahawh Hmong -Palmyrene -Pau Cin Hau -Phags-pa -Psalter Pahlavi -Ranjana -Rejang (Redjang, Kaganga) -Runic -Samaritan -Sarati -Saurashtra -Sharada, Śāradā -Shavian (Shaw) -Siddham, Siddhaṃ, Siddhamātṛkā -SignWriting -Sinhala -Sogdian -Sora Sompeng -Soyombo -Sundanese -Sunuwar -Syloti Nagri -Symbols -Syriac -Syriac (Western variant) -Tagalog (Baybayin, Alibata) -Tagbanwa -Tai Le -Tai Tham (Lanna) -Tai Viet -Tai Yo -Takri, Ṭākrī, Ṭāṅkrī -Tamil -Tangsa -Telugu -Tengwar -Thaana -Thai -Tibetan -Tifinagh (Berber) -Tirhuta -Tolong Siki -Toto -Tulu-Tigalari -Unified Canadian Aboriginal Syllabics -Vai -Vithkuqi -Wancho -Warang Citi (Varang Kshiti) -Woleai -Yezidi -Yi -Zanabazar Square (Zanabazarin Dörböljin Useg, Xewtee Dörböljin Bicig, Horizontal Square Script) \ No newline at end of file diff --git a/components/language-chooser/react/common/language-chooser-react-hook/README.md b/components/language-chooser/react/common/language-chooser-react-hook/README.md new file mode 100644 index 0000000..30d0d62 --- /dev/null +++ b/components/language-chooser/react/common/language-chooser-react-hook/README.md @@ -0,0 +1,41 @@ +> [!warning] +> This project is currently under development and not ready for public use. + +# Language Chooser React Hook + +A React hook that uses the [find-language](../../../common/find-language/README.md) to provide the logic for a language chooser React component such as [MUI Language Chooser](../../language-chooser-react-mui/README.md). + +## Usage + +Install with npm: `npm i @ethnolib/language-chooser-react-hook` + +### Props + +- `searchResultModifier: ( + results: FuseResult[], + searchString: string +) => ILanguage[]` - Can be used to add, remove, and modify results. See [find-language](../../../common/find-language/README.md) for details. + +### Returns + +- `languageData: ILanguage[]` - The list of languages resulting from fuzzy-searching `searchString` against the language database. Automatically updates whenever `searchString` changes. +- `selectedLanguage: ILanguage | undefined` - A React state variable for storing a language selected by the user. Set by `toggleSelectedLanguage`, `selectUnlistedLanguage`, and `resetTo`. Automatically cleared whenever `searchString` changes. +- `selectedScript: IScript | undefined` - A React state variable for storing a script selected by the user. Set by `toggleSelectedScript`, `saveLanguageDetails`, and `resetTo`. Automatically cleared whenever `selectedLanguage` changes. When a language with exactly 1 script option is selected, `selectedScript` will automatically be set to that script. +- `customizableLanguageDetails: ICustomizableLanguageDetails` - A React state variable for storing any custom display name, region, or dialect information the user has entered. Set by `saveLanguageDetails` and `resetTo`. Automatically cleared whenever the `selectedLanguage` changes. +- `searchString: string` - A React state variable. Value is set by the `searchString` argument of the most recent call to `onSearchStringChange`. +- `onSearchStringChange: (searchString: string) => void` - Should be called whenever the user makes changes to the search string (debouncing first is recommended). + +- `toggleSelectLanguage: (language: ILanguage) => void` - If `language` is the `selectedLanguage`, clears the `selectedLanguage`. Otherwise, sets `selectedLanguage` to `language`. If selecting a language that has only one script option, this will automatically set `selectedScript` to that script. +- `toggleSelectScript: (script: IScript) => void` - If `script` is the `selectedScript`, clears the `selectedScript`. Otherwise, sets `selectedScript` to `script`. +- `isReadyToSubmit: boolean` - Returns true if the user has selected a language and, if that language requires a script selection, has selected a script. +- `saveLanguageDetails: ( details: ICustomizableLanguageDetails, script: IScript | undefined ) => void` - Sets `customizableLanguageDetails` and `selectedScript` +- `selectUnlistedLanguage: () => void` - Set the `selectedLanguage` to "Unknown Language" with code "qaa". To be used for languages that are not in the database. +- `resetTo: (initialState: IOrthography) => void` - For restoring preexisting data when the LanguageChooser is first opened. Sets `selectedLanguage`, `selectedScript`, and `customizableLanguageDetails` to the values in `initialState`. + +### Example + +See Mui React [LanguageChooser](../../language-chooser-react-mui/src/LanguageChooser.tsx) for an example usage. + +## Development + +See the main [README](../../../../../README.md). diff --git a/components/language-chooser/react/common/language-chooser-react-hook/useLanguageChooser.tsx b/components/language-chooser/react/common/language-chooser-react-hook/useLanguageChooser.tsx index c58a686..53090a4 100644 --- a/components/language-chooser/react/common/language-chooser-react-hook/useLanguageChooser.tsx +++ b/components/language-chooser/react/common/language-chooser-react-hook/useLanguageChooser.tsx @@ -34,7 +34,7 @@ export interface ILanguageChooser { isReadyToSubmit: boolean; saveLanguageDetails: ( details: ICustomizableLanguageDetails, - script?: IScript + script: IScript | undefined ) => void; selectUnlistedLanguage: () => void; resetTo: (initialState: IOrthography) => void; @@ -114,7 +114,7 @@ export const useLanguageChooser = ( function saveLanguageDetails( details: ICustomizableLanguageDetails, - script?: IScript + script: IScript | undefined ) { setSelectedScript(script); setCustomizableLanguageDetails(details); diff --git a/components/language-chooser/react/language-chooser-react-mui/README.md b/components/language-chooser/react/language-chooser-react-mui/README.md new file mode 100644 index 0000000..144701c --- /dev/null +++ b/components/language-chooser/react/language-chooser-react-mui/README.md @@ -0,0 +1,65 @@ +> [!warning] +> This project is currently under development and not ready for public use. + +# MUI React Language Chooser + +A MUI-styled React component that uses the [find-language](../../common/find-language/README.md) and [language-chooser-react-hook](../common/language-chooser-react-hook/README.md) packages to present a language chooser interface. + +**See demo on Storybook at [https://sillsdev.github.io/EthnoLib/](https://sillsdev.github.io/EthnoLib/)** + +Initially developed for use in [BloomDesktop](https://github.com/BloomBooks/BloomDesktop). + +## Usage + +### Installation + +Requires interfaces, methods, etc. from [@ethnolib/find-language](../../common/find-language/README.md). +Install with npm: + +``` +npm i @ethnolib/find-language +npm i @ethnolib/language-chooser-react-mui +``` + +### Sizing + +Designed to be used in a dialog. The desired height and width need to be set on the parent dialog (see example below). + +### Props + +- `searchResultModifier: ( + results: FuseResult[], + searchString: string +) => ILanguage[]` - Can be used to add, remove, and modify results. See [find-language](../../common/find-language/README.md) for details. +- `initialState: IOrthography` - The initial state of selections with which to populate the LanguageChooser when it is first opened, e.g. if the user has already selected a language and is modifying it. +- `onClose: (languageSelection: IOrthography | undefined) => void` - This is called when the user clicks the "OK" or "Cancel" button to close the dialog. + +### Example + +``` +/** @jsxImportSource @emotion/react */ +import { css } from "@emotion/react"; +import { Dialog } from "@mui/material"; +import { LanguageChooser } from "@ethnolib/language-chooser-react-mui"; + + + + +``` + +## Development + +See the main [README](../../../../README.md). diff --git a/components/language-chooser/react/language-chooser-react-mui/src/CustomizeLanguageDialog.tsx b/components/language-chooser/react/language-chooser-react-mui/src/CustomizeLanguageDialog.tsx index 8aab1bd..31bec1a 100644 --- a/components/language-chooser/react/language-chooser-react-mui/src/CustomizeLanguageDialog.tsx +++ b/components/language-chooser/react/language-chooser-react-mui/src/CustomizeLanguageDialog.tsx @@ -53,7 +53,7 @@ export const CustomizeLanguageDialog: React.FunctionComponent<{ customizableLanguageDetails: ICustomizableLanguageDetails; saveLanguageDetails: ( details: ICustomizableLanguageDetails, - script?: IScript + script: IScript | undefined ) => void; selectUnlistedLanguage: () => void; searchString: string;