tosijs-ui 1.0.0

package/dist/localize.d.ts

@@ -0,0 +1,46 @@
+import { Component } from 'tosijs';
+import { XinSelect } from './select';
+interface TranslationMap {
+    [key: string]: string[];
+}
+interface I18nConfig {
+    locale: string;
+    locales: string[];
+    languages: string[];
+    emoji: string[];
+    stringMap: TranslationMap;
+    localeOptions: Array<{
+        icon: HTMLElement;
+        caption: string;
+        value: string;
+    }>;
+}
+export declare const i18n: I18nConfig;
+export declare const setLocale: (language: string) => void;
+export declare const updateLocalized: () => void;
+export declare function initLocalization(localizedStrings: string): void;
+export declare function localize(ref: string): string;
+export declare class LocalePicker extends Component {
+    hideCaption: boolean;
+    content: () => XinSelect;
+    constructor();
+    render(): void;
+}
+export declare const localePicker: import("tosijs").ElementCreator<Component<import("tosijs").PartsMap>>;
+interface AbstractLocalized {
+    localeChanged: () => void;
+    connectedCallback: () => void;
+    disconnectedCallback: () => void;
+}
+export declare class XinLocalized extends Component {
+    static allInstances: Set<AbstractLocalized>;
+    contents: () => any;
+    refString: string;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    localeChanged(): void;
+    render(): void;
+}
+export declare const xinLocalized: import("tosijs").ElementCreator<Component<import("tosijs").PartsMap>>;
+export {};

package/dist/localize.js

@@ -0,0 +1,381 @@
+/*#
+# localize
+
+`xinjs-ui` provides support for localization via the `localize` method and the `<xin-locale-picker>`
+and `<xin-localized>` custom-elements.
+
+> ### Important Note
+> This module deals with the **language** used in the user interface. "locale" is
+> *not the same thing*. The (usually) two-letter codes used designate **language**
+> and **not locale**.
+>
+> E.g. the US *locale* includes things like measurement systems
+> and date format. Most European locales use commas where we use decimal points in the US.
+>
+> Similarly, `ja` is the code for the Japanese **language** while `jp` is the **locale**.
+
+## `initLocalization(localizationData: string)`
+
+Enables localization from TSV string data.
+
+## XinLocalePicker
+
+A selector that lets the user pick from among supported languages.
+
+```html
+<h3>Locale Picker</h3>
+<xin-locale-picker></xin-locale-picker>
+
+<h3>Locale Picker with <code>hide-captions</code></h3>
+<xin-locale-picker hide-caption></xin-locale-picker>
+```
+
+## `localize()`
+
+If you just want to localize a string with code, use `localize(s: string): string`.
+
+If the reference string only matches when both are converted to
+lowercase, the output string will also be lowercase.
+
+E.g. if you have localized `Cancel` as `Annuler`, then `localize("cancel")
+will output `annuler`.
+
+### ellipses
+
+If you end a string with an ellipsis, `localize` will ignore the ellipsis,
+localize the string, and then append the ellipsis.
+
+## `setLocale(language: string)`
+
+```js
+const { button, p } = xinjs.elements
+const { setLocale } = xinjsui
+
+preview.append(
+  p(
+    button(
+      {
+        onClick() {
+          setLocale('en-US')
+        }
+      },
+      'setLocale("en-US")'
+    )
+  ),
+  p(
+    button(
+      {
+        onClick() {
+          setLocale('fr')
+        }
+      },
+      'setLocale("fr")'
+    )
+  ),
+  p(
+    button(
+      {
+        onClick() {
+          setLocale('qq')
+        }
+      },
+      'setLocale("qq") (see console for error message)'
+    )
+  ),
+)
+```
+
+If you want to directly set locale, just use `setLocale()`.
+
+## XinLocalized
+
+A span-replacement that automatically localizes its text content.
+By default the case in the localized data is preserved unless the
+reference text is all lowercase, in which case the localized text
+is also lowercased.
+
+While viewing this documentation, all `<xin-localized>` elements should display a **red
+underline**.
+
+```html
+<h3>Localized Widgets</h3>
+<button><xin-localized>Yes</xin-localized></button>
+<button><xin-localized>No</xin-localized></button>
+<button><xin-localized>Open…</xin-localized></button> <i>note the ellipsis</i>
+
+<h3>Lowercase is preserved</h3>
+<button><xin-localized>yes</xin-localized></button>
+<button><xin-localized>no</xin-localized></button>
+<button><xin-localized>open…</xin-localized></button>
+
+<h3>Localized Attribute</h3>
+<input>
+```
+```css
+xin-localized {
+  border-bottom: 2px solid red;
+}
+```
+```js
+const { xinLocalized, localize } = xinjsui
+
+preview.append(xinLocalized({
+  refString: 'localized placeholder',
+  localeChanged() {
+    this.previousElementSibling.setAttribute('placeholder', localize(this.refString))
+  }
+}))
+```
+
+`<xin-localized>` has a `refString` attribute (which defaults to its initial `textContent`)
+which is the text that it localizes. You can set it directly.
+
+It also has an `localeChanged` method which defaults to setting the content of the element
+to the localized reference string, but which you can override, to (for example) set a property
+or attribute of the parent element.
+
+> `<xin-localized>` *can* be used inside the shadowDOM of other custom-elements.
+
+## `i18n`
+
+All of the data can be bound in the `i18n` proxy (`xin.i18n`), including the currently selected
+locale (which will default to `navigator.language`).
+
+You can take a look at `xin.i18n` in the console. `i18n` can be used to access localization
+data directly, and also to determine which locales are available `i18n.locales` and set the
+locale programmatically (e.g. `i18n.locale = 'en'`).
+
+```
+if (i18n.locales.includes('fr')) {
+  i18n.locale = 'fr'
+}
+```
+
+## Creating Localized String Data
+
+You can create your own localization data using any spreadsheet and exporting TSV.
+
+E.g. you can automatically create localization data
+using something like my [localized](https://docs.google.com/spreadsheets/d/1L0_4g_dDhVCwVVxLzYbMj_H86xSp9lsRCKj7IS9psso/edit?usp=sharing)
+Google Sheet which leverages `googletranslate` to automatically translate reference strings
+(and which you can manually override as you like).
+
+E.g. in this demo I've replaced the incorrect translation of "Finnish"
+(`googletranslate` used the word for Finnish nationality rather than the language).
+
+The format of the input data is a table in TSV format, that looks like this:
+
+en-US | fr | fi | sv | zh
+------|----|----|----|----
+English (US) | French | Finnish | Swedish | Chinese (Mandarin)
+English (US) | Français | suomi | svenska | 中文（普通话）
+🇺🇸 | 🇫🇷 | 🇫🇮 | 🇸🇪 | 🇨🇳
+Icon | Icône | Kuvake | Ikon | 图标
+Ok | D'accord | Ok | Ok | 好的
+Cancel | Annuler | Peruuttaa | Avboka | 取消
+
+- Column 1 is your reference language.
+- Row 1 is [language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes).
+- Row 2 is the name of the language in your reference language.
+- Row 3 is the name of the language in itself (because it's silly to expect people
+  to know the name of their language in a language they don't know)
+- Row 4 is the flag emoji for that language (yes, that's problematic, but languages
+  do not have flags, per se)
+- Rows 5 and on are user interface strings you want to localize
+
+In the spreadsheet provided, each cell contains a formula that translates the term
+in the left-most column from the language in that column to the language in the
+destination column. Once you have an automatic translation, you can hand off the
+sheet to language experts to vet the translations.
+
+Finally, create a `tsv` file and then turn that into a Typescript file by wrapping
+the content thus:
+
+```
+export default `( content of tsv file )`
+```
+
+You use this data using `initLocalization()`.
+
+## Leveraging XinLocalized Automatic Updates
+
+If you want to leverage XinLocalized's automatic updates you simply need to
+implement `updateLocale` and register yourself with `XinLocalized.allInstances`
+(which is a `Set<AbstractLocalized>).
+
+Typically, this would look like something like:
+
+```
+class MyLocalizedComponent extends Component {
+  ...
+
+  // register yourself as a localized component
+  connectecCallback() {
+    super.connectedCallback()
+
+    XinLocalized.allInstances.add(this)
+  }
+
+  // avoid leaking!
+  disconnectecCallback() {
+    super.connectedCallback()
+
+    XinLocalized.allInstances.delete(this)
+  }
+
+  // presumably your render method does the right things
+  updateLocale = () =>  {
+    this.queueRender()
+  }
+}
+```
+*/
+import { Component, boxedProxy, elements, bindings, observe } from 'xinjs';
+import { makeSorter } from './make-sorter';
+import { xinSelect, XinSelect } from './select';
+const { span } = elements;
+export const { i18n } = boxedProxy({
+    i18n: {
+        locale: window.navigator.language,
+        locales: [window.navigator.language],
+        languages: [window.navigator.language],
+        emoji: [''],
+        stringMap: {},
+        localeOptions: [
+            {
+                icon: span(),
+                caption: window.navigator.language,
+                value: window.navigator.language,
+            },
+        ],
+    },
+});
+bindings.localeOptions = {
+    toDOM(select, options) {
+        if (select instanceof XinSelect) {
+            select.options = options;
+        }
+    },
+};
+export const setLocale = (language) => {
+    if (i18n.locales.includes(language)) {
+        i18n.locale = language;
+    }
+    else {
+        console.error(`language ${language} is not available`);
+    }
+};
+export const updateLocalized = () => {
+    const localizeds = Array.from(XinLocalized.allInstances);
+    for (const localized of localizeds) {
+        localized.localeChanged();
+    }
+};
+observe(i18n.locale.xinPath, updateLocalized);
+const captionSort = makeSorter((locale) => [
+    locale.caption.toLocaleLowerCase(),
+]);
+export function initLocalization(localizedStrings) {
+    const [locales, , languages, emoji, ...strings] = localizedStrings
+        .split('\n')
+        .map((line) => line.split('\t'));
+    if (locales && languages && emoji && strings) {
+        i18n.locales = locales;
+        i18n.languages = languages;
+        i18n.emoji = emoji;
+        i18n.stringMap = strings.reduce((map, strings) => {
+            map[strings[0].toLocaleLowerCase()] = strings;
+            return map;
+        }, {});
+        i18n.localeOptions = locales
+            .map((locale, index) => ({
+            icon: span({ title: locales[index] }, emoji[index]),
+            caption: languages[index],
+            value: locale,
+        }))
+            .sort(captionSort);
+        // if user locale isn't available, find the best match
+        if (!i18n.locales.includes(i18n.locale.valueOf())) {
+            const language = i18n.locale.substring(0, 2);
+            i18n.locale =
+                i18n.locales.find((locale) => locale.substring(0, 2) === language) ||
+                    i18n.locales[0];
+        }
+        updateLocalized();
+    }
+}
+export function localize(ref) {
+    if (ref.endsWith('…')) {
+        return localize(ref.substring(0, ref.length - 1)) + '…';
+    }
+    const index = i18n.locales.indexOf(i18n.locale.valueOf());
+    if (index > -1) {
+        const map = i18n.stringMap[ref.toLocaleLowerCase()];
+        const localized = map && map[index];
+        if (localized) {
+            ref =
+                ref.toLocaleLowerCase() === ref
+                    ? localized.toLocaleLowerCase()
+                    : localized.valueOf();
+        }
+    }
+    return ref;
+}
+export class LocalePicker extends Component {
+    hideCaption = false;
+    content = () => {
+        return xinSelect({
+            part: 'select',
+            showIcon: true,
+            title: localize('Language'),
+            bindValue: i18n.locale,
+            bindLocaleOptions: i18n.localeOptions,
+        });
+    };
+    constructor() {
+        super();
+        this.initAttributes('hideCaption');
+    }
+    render() {
+        super.render();
+        this.parts.select.toggleAttribute('hide-caption', this.hideCaption);
+    }
+}
+export const localePicker = LocalePicker.elementCreator({
+    tag: 'xin-locale-picker',
+});
+export class XinLocalized extends Component {
+    static allInstances = new Set();
+    contents = () => elements.xinSlot();
+    refString = '';
+    constructor() {
+        super();
+        this.initAttributes('refString');
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        XinLocalized.allInstances.add(this);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        XinLocalized.allInstances.delete(this);
+    }
+    localeChanged() {
+        if (!this.refString) {
+            this.refString = this.textContent || '';
+        }
+        this.textContent = this.refString ? localize(this.refString) : '';
+    }
+    render() {
+        super.render();
+        this.localeChanged();
+    }
+}
+export const xinLocalized = XinLocalized.elementCreator({
+    tag: 'xin-localized',
+    styleSpec: {
+        ':host': {
+            pointerEvents: 'none',
+        },
+    },
+});

package/dist/make-sorter.d.ts

@@ -0,0 +1,3 @@
+export type SortValuator<T = object> = (f: T) => (string | number)[];
+export type SortCallback<T = object> = (p: T, q: T) => number;
+export declare function makeSorter<T>(sortValuator: SortValuator<T>, ascending?: boolean | boolean[]): SortCallback<T>;

package/dist/make-sorter.js

@@ -0,0 +1,119 @@
+/*#
+# makeSorter
+
+I'm always confusing myself when writing sort functions, so I wrote `makeSorter()`. It's
+insanely simple and just works™. It makes writing an array sort callback for anything
+other than an array of numbers or strings easier.
+
+```js
+const { select, option, div, span, ul, li } = xinjs.elements
+const { icons, makeSorter } = xinjsui
+
+const people = [
+  { first: 'Frasier', last: 'Crane', age: 38 },
+  { first: 'Lilith', last: 'Crane', age: 37 },
+  { first: 'Rebecca', last: 'Howe', age: 35 },
+  { first: 'Woody', last: 'Boyd', age: 25 },
+  { first: 'Sam', last: 'Malone', age: 40 },
+  { first: 'Norm', last: 'Peterson', age: 38 },
+]
+
+const sorters = {
+  firstSort: makeSorter(person => [person.first]),
+  firstDescSort: makeSorter(person => [person.first], false),
+  nameSort: makeSorter(person => [person.last, person.first]),
+  ageFirst: makeSorter(person => [-person.age, person.last]),
+  ageLast: makeSorter(person => [person.age, person.first], [true, false]),
+}
+
+function person({first, last, age}) {
+  return li(`${first} ${last}, ${age}`)
+}
+
+const list = ul()
+sortPicker = select(
+  option('Sort by first', {value: 'firstSort'}),
+  option('Sort by first (desc)', {value: 'firstDescSort'}),
+  option('Sort by last, first', {value: 'nameSort'}),
+  option('Sort by age (desc), first', {value: 'ageFirst'}),
+  option('Sort by age, last (desc)', {value: 'ageLast'}),
+  {
+    onChange: render,
+    value: 'nameSort'
+  },
+)
+
+function render () {
+  list.textContent = ''
+  list.append(...people.sort(sorters[sortPicker.value]).map(person))
+}
+
+preview.append(
+  div(
+    sortPicker,
+    icons.chevronDown()
+  ),
+  list
+)
+
+render()
+```
+```css
+.preview {
+  padding: var(--spacing);
+}
+
+.preview div {
+  position: absolute;
+  top: var(--spacing);
+  right: var(--spacing);
+}
+```
+
+## Details
+
+To create a sort callback that sorts by propA then propB (if propA is tied):
+
+```
+const sorter = makeSorter(
+  obj => [obj.propA, obj.propB]
+)
+```
+
+As above, but sort descending:
+```
+const sorter = makeSorter(
+  obj => [obj.propA, obj.propB],
+  false
+)
+```
+
+As above but propA is sorted ascending, propB descending
+```
+const sorter = makeSorter(
+  obj => [obj.propA, obj.propB],
+  [true, false]
+)
+```
+*/
+export function makeSorter(sortValuator, ascending = true) {
+    return (p, q) => {
+        const pSort = sortValuator(p);
+        const qSort = sortValuator(q);
+        for (const i in pSort) {
+            if (pSort[i] !== qSort[i]) {
+                const isAscending = Array.isArray(ascending)
+                    ? ascending[i] !== false
+                    : ascending;
+                return isAscending
+                    ? pSort[i] > qSort[i]
+                        ? 1
+                        : -1
+                    : pSort[i] > qSort[i]
+                        ? -1
+                        : 1;
+            }
+        }
+        return 0;
+    };
+}

package/dist/make-sorter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/make-sorter.test.js

@@ -0,0 +1,48 @@
+/* eslint-disable */
+import { test, expect } from 'bun:test';
+import { makeSorter } from './make-sorter';
+test('sorts simple values', () => {
+    const simpleSort = makeSorter((a) => [a]);
+    const array = [5, -1, 3];
+    expect([...array].sort(simpleSort)[0]).toBe(-1);
+    expect([...array].sort(simpleSort)[1]).toBe(3);
+    const strings = ['oh', 'be', 'a', 'fine'];
+    expect([...strings].sort(simpleSort)[0]).toBe('a');
+    expect([...strings].sort(simpleSort)[1]).toBe('be');
+});
+test('sorts simple values descending', () => {
+    const simpleSort = makeSorter((a) => [a], false);
+    const array = [5, -1, 3];
+    expect([...array].sort(simpleSort)[0]).toBe(5);
+    expect([...array].sort(simpleSort)[1]).toBe(3);
+    const strings = ['oh', 'be', 'a', 'fine'];
+    expect([...strings].sort(simpleSort)[0]).toBe('oh');
+    expect([...strings].sort(simpleSort)[1]).toBe('fine');
+});
+test('sorts compound objects', () => {
+    const sortNameThenId = makeSorter((a) => [
+        a.name,
+        a.id,
+    ]);
+    const sortLowercaseNameThenId = makeSorter((a) => [a.name.toLocaleLowerCase(), a.id]);
+    const idThenName = makeSorter((a) => [
+        a.id,
+        a.name,
+    ]);
+    const array = [
+        { name: 'alice', id: 100 },
+        { name: 'bob', id: 1 },
+        { name: 'alice', id: 10 },
+        { name: 'Zed', id: 5 },
+        { name: 'smaug', id: -7 },
+    ];
+    expect([...array].sort(sortNameThenId)[0].id).toBe(5);
+    expect([...array].sort(sortNameThenId)[2].id).toBe(100);
+    expect([...array].sort(sortNameThenId)[4].id).toBe(-7);
+    expect([...array].sort(sortLowercaseNameThenId)[0].id).toBe(10);
+    expect([...array].sort(sortLowercaseNameThenId)[2].id).toBe(1);
+    expect([...array].sort(sortLowercaseNameThenId)[4].id).toBe(5);
+    expect([...array].sort(idThenName)[0].id).toBe(-7);
+    expect([...array].sort(idThenName)[2].id).toBe(5);
+    expect([...array].sort(idThenName)[4].id).toBe(100);
+});

package/dist/mapbox.d.ts

@@ -0,0 +1,24 @@
+import { Component as WebComponent, ElementCreator } from 'tosijs';
+export declare class MapBox extends WebComponent {
+    coords: string;
+    content: HTMLDivElement;
+    get map(): any;
+    mapStyle: string;
+    token: string;
+    static mapboxCSSAvailable: Promise<void>;
+    static mapboxAvailable?: Promise<any>;
+    private _map;
+    static styleSpec: {
+        ':host': {
+            display: string;
+            position: string;
+            width: string;
+            height: string;
+            textAlign: string;
+        };
+    };
+    constructor();
+    connectedCallback(): void;
+    render(): void;
+}
+export declare const mapBox: ElementCreator<MapBox>;