@widgetic/design-system 0.5.15 → 0.5.16

package/dist/i18n/createI18n.js

@@ -0,0 +1,72 @@
+import { getContext, setContext } from 'svelte';
+import { derived, readable, writable } from 'svelte/store';
+import { createTranslator, describeMessageProblem } from "./translator.js";
+/** How many different problems the console is told about, so a page that keeps changing its messages cannot fill memory. */
+const MAX_REPORTED_PROBLEMS = 200;
+/** Two settings are the same language when they have the same locale and the same words. */
+function signatureOf(settings) {
+    try {
+        return JSON.stringify([settings.locale ?? null, settings.messages ?? null]);
+    }
+    catch {
+        // Not serializable (a cycle, a BigInt): treat it as new every time rather than guess.
+        return `${Math.random()}`;
+    }
+}
+/**
+ * Makes the words of one package: the context its root component provides, the hook its parts use, and the English
+ * translator for code with no component around it.
+ *
+ * Every package makes its own (its catalog, its console label, its own context key), so the File Browser inside the
+ * editor and the editor around it can each have their own words, and each is told only about its own messages.
+ */
+export function createI18n(options) {
+    const { catalog, label } = options;
+    const api = options.contextApi ?? { getContext, setContext };
+    const contextKey = Symbol(`widgetic-${label}-i18n`);
+    const reportedProblems = new Set();
+    /** Says a problem with the page's messages in the console, once per page however often the language is set. */
+    const reportProblem = (problem) => {
+        const text = describeMessageProblem(problem);
+        if (reportedProblems.has(text) || reportedProblems.size >= MAX_REPORTED_PROBLEMS)
+            return;
+        reportedProblems.add(text);
+        console.warn(`[${label}] ${text}`);
+    };
+    const translatorFor = (settings) => createTranslator({
+        catalog,
+        locale: settings.locale ?? undefined,
+        messages: settings.messages,
+        onProblem: reportProblem
+    });
+    /** The English translator that a part uses when nothing above it chose a language. */
+    const englishTranslator = translatorFor({});
+    const englishContext = Object.freeze({
+        t: readable(englishTranslator.t),
+        locale: readable(englishTranslator.locale)
+    });
+    function provideI18n(initial) {
+        const settings = writable(initial);
+        const translator = derived(settings, ($settings) => translatorFor($settings));
+        const t = derived(translator, ($translator) => $translator.t);
+        const locale = derived(translator, ($translator) => $translator.locale);
+        const context = { t, locale };
+        api.setContext(contextKey, context);
+        let lastSignature = signatureOf(initial);
+        return {
+            ...context,
+            update(next) {
+                // Setting the same language again would rebuild every message for nothing.
+                const signature = signatureOf(next);
+                if (signature === lastSignature)
+                    return;
+                lastSignature = signature;
+                settings.set(next);
+            }
+        };
+    }
+    function useI18n() {
+        return api.getContext(contextKey) ?? englishContext;
+    }
+    return { provideI18n, useI18n, translateEnglish: englishTranslator.t };
+}

package/dist/i18n/direction.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Which way a language is read, so that a screen that follows its page's language can mirror its layout for the
+ * languages that are written right to left (Arabic, Hebrew, Persian, Urdu ...), give its elements the `lang` the same
+ * language deserves, and keep the names it puts inside a sentence from being turned around (see `translator.ts`).
+ *
+ * The direction comes from the SCRIPT a language tag is written in, not from a list of languages:
+ * `Intl.Locale(tag).maximize()` fills in the script the language is usually written in (`ar` is Arab, `he` is Hebr,
+ * `pa-PK` is Arab while `pa-IN` is Guru), and a tag that names its script is taken at its word (`ar-Latn` is Latin and
+ * so left to right, `ku-Arab` is Arabic and so right to left). A short list of languages is only the fallback for a
+ * browser without `Intl.Locale` and for a tag it cannot read.
+ *
+ * Nothing here knows about Svelte or the DOM: the same code runs in a unit test.
+ */
+/** The two ways text runs: the values of the `dir` attribute. */
+export type TextDirection = 'ltr' | 'rtl';
+/**
+ * Which way `locale` is read. Blank, missing or unreadable is left to right, which is what a screen has always been.
+ * Never throws.
+ */
+export declare function resolveTextDirection(locale: string | null | undefined): TextDirection;
+/**
+ * The `lang` a screen's elements get for `locale`: the language tag in its canonical spelling (`pt_BR` and `PT-br`
+ * become `pt-BR`). A blank locale is English, which is what the words are then. A tag a browser cannot read gives
+ * `undefined`: the screen leaves `lang` off and its elements take the language of the page around them, which is better
+ * than a language that is wrong.
+ */
+export declare function resolveLanguageTag(locale: string | null | undefined): string | undefined;

package/dist/i18n/direction.js

@@ -0,0 +1,89 @@
+/**
+ * Which way a language is read, so that a screen that follows its page's language can mirror its layout for the
+ * languages that are written right to left (Arabic, Hebrew, Persian, Urdu ...), give its elements the `lang` the same
+ * language deserves, and keep the names it puts inside a sentence from being turned around (see `translator.ts`).
+ *
+ * The direction comes from the SCRIPT a language tag is written in, not from a list of languages:
+ * `Intl.Locale(tag).maximize()` fills in the script the language is usually written in (`ar` is Arab, `he` is Hebr,
+ * `pa-PK` is Arab while `pa-IN` is Guru), and a tag that names its script is taken at its word (`ar-Latn` is Latin and
+ * so left to right, `ku-Arab` is Arabic and so right to left). A short list of languages is only the fallback for a
+ * browser without `Intl.Locale` and for a tag it cannot read.
+ *
+ * Nothing here knows about Svelte or the DOM: the same code runs in a unit test.
+ */
+/**
+ * The scripts that are written right to left and that a language of today is written in (ISO 15924): Arabic, Hebrew,
+ * Thaana (Dhivehi), Syriac, N'Ko, Adlam (Fulani), Hanifi Rohingya, Mandaic, Samaritan, Garay and Yezidi.
+ */
+const RIGHT_TO_LEFT_SCRIPTS = new Set(['Arab', 'Hebr', 'Thaa', 'Syrc', 'Nkoo', 'Adlm', 'Rohg', 'Mand', 'Samr', 'Gara', 'Yezi']);
+/**
+ * The languages that are written right to left when their tag says nothing else, for the browser or the tag that
+ * `Intl.Locale` cannot answer for. `iw` and `prs` are the old code of Hebrew and the code of Dari.
+ */
+const RIGHT_TO_LEFT_LANGUAGES = new Set([
+    'ar',
+    'arc',
+    'arz',
+    'ary',
+    'apc',
+    'azb',
+    'ckb',
+    'dv',
+    'fa',
+    'he',
+    'iw',
+    'ks',
+    'prs',
+    'ps',
+    'sd',
+    'ug',
+    'ur',
+    'yi'
+]);
+/** A language tag the way a browser wants it: no blanks around it, and a hyphen where a page wrote an underscore (`pt_BR`). */
+function cleanLanguageTag(locale) {
+    return typeof locale === 'string' ? locale.trim().replace(/_/g, '-') : '';
+}
+/** The script a language tag is written in, or `undefined` when this browser cannot say (no `Intl.Locale`, or a tag it refuses). */
+function scriptOfLanguageTag(languageTag) {
+    if (typeof Intl === 'undefined' || typeof Intl.Locale !== 'function')
+        return undefined;
+    try {
+        return new Intl.Locale(languageTag).maximize().script;
+    }
+    catch {
+        // A tag that is not a language tag at all (`x-foo`, `1234`): the fallback list decides.
+        return undefined;
+    }
+}
+/**
+ * Which way `locale` is read. Blank, missing or unreadable is left to right, which is what a screen has always been.
+ * Never throws.
+ */
+export function resolveTextDirection(locale) {
+    const languageTag = cleanLanguageTag(locale);
+    if (languageTag === '')
+        return 'ltr';
+    const script = scriptOfLanguageTag(languageTag);
+    if (script !== undefined)
+        return RIGHT_TO_LEFT_SCRIPTS.has(script) ? 'rtl' : 'ltr';
+    const primaryLanguage = (languageTag.split('-')[0] ?? '').toLowerCase();
+    return RIGHT_TO_LEFT_LANGUAGES.has(primaryLanguage) ? 'rtl' : 'ltr';
+}
+/**
+ * The `lang` a screen's elements get for `locale`: the language tag in its canonical spelling (`pt_BR` and `PT-br`
+ * become `pt-BR`). A blank locale is English, which is what the words are then. A tag a browser cannot read gives
+ * `undefined`: the screen leaves `lang` off and its elements take the language of the page around them, which is better
+ * than a language that is wrong.
+ */
+export function resolveLanguageTag(locale) {
+    const languageTag = cleanLanguageTag(locale);
+    if (languageTag === '')
+        return 'en';
+    try {
+        return Intl.getCanonicalLocales(languageTag)[0];
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/i18n/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The words of a Widgetic package in the page's language: the translator that fills in a catalog of English messages, and
+ * the Svelte context a package's screens read them from.
+ *
+ *   // in the package: its catalog, once
+ *   const { provideI18n, useI18n, translateEnglish } = createI18n({ catalog: MY_MESSAGES, label: 'MyPackage' });
+ *   // in its root component: provideI18n({ locale, messages })
+ *   // in any part: const { t } = useI18n();   then   $t('upload.clear')
+ *
+ * See `translator.ts` for the format of a message.
+ */
+export { createI18n } from './createI18n.ts';
+export { resolveLanguageTag, resolveTextDirection, type TextDirection } from './direction.ts';
+export { splitMessages, type SplitMessages } from './splitMessages.ts';
+export type { I18n, I18nContext, I18nHandle, I18nOptions, I18nSettings, SvelteContextApi, Translate } from './createI18n.ts';
+export { createTranslator, describeMessageProblem, findMessageProblems, valueNamesOfTemplate, type MessageOverrides, type MessageProblem, type MessageValue, type MessageValues, type Translator, type TranslatorOptions } from './translator.ts';
+export { formatCalendarWeekdayLabel, formatLocaleShortDate, parseLocaleShortDate, type NumericDateParts } from './localeDate.ts';

package/dist/i18n/index.js

@@ -0,0 +1,16 @@
+/**
+ * The words of a Widgetic package in the page's language: the translator that fills in a catalog of English messages, and
+ * the Svelte context a package's screens read them from.
+ *
+ *   // in the package: its catalog, once
+ *   const { provideI18n, useI18n, translateEnglish } = createI18n({ catalog: MY_MESSAGES, label: 'MyPackage' });
+ *   // in its root component: provideI18n({ locale, messages })
+ *   // in any part: const { t } = useI18n();   then   $t('upload.clear')
+ *
+ * See `translator.ts` for the format of a message.
+ */
+export { createI18n } from "./createI18n.js";
+export { resolveLanguageTag, resolveTextDirection } from "./direction.js";
+export { splitMessages } from "./splitMessages.js";
+export { createTranslator, describeMessageProblem, findMessageProblems, valueNamesOfTemplate } from "./translator.js";
+export { formatCalendarWeekdayLabel, formatLocaleShortDate, parseLocaleShortDate } from "./localeDate.js";

package/dist/i18n/localeDate.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Locale-aware short dates for calendars and range pickers. Values in compositions stay structured (CalendarDate); only
+ * display and typed input use these helpers.
+ */
+export type NumericDateParts = {
+    year: number;
+    month: number;
+    day: number;
+};
+/** Formats a calendar day the way `locale` writes short numeric dates (order and separators from Intl). */
+export declare function formatLocaleShortDate(parts: NumericDateParts, locale: string): string;
+/**
+ * Parses a typed short date for `locale`, and still accepts legacy `DD/MM/YY` (day/month with `/` separators).
+ * Returns null when the text is not a valid date.
+ */
+export declare function parseLocaleShortDate(text: string, locale: string): NumericDateParts | null;
+/** What a calendar's column heading says for one weekday. */
+export type CalendarWeekdayHeading = {
+    /** The text in the column heading. */
+    label: string;
+    /** The whole name of the weekday, for a screen reader, when `label` is only its one-letter name. Otherwise undefined. */
+    fullName: string | undefined;
+};
+/**
+ * Weekday heading for calendar grids: uses Intl `weekday: 'short'` for the column (no code-unit truncation).
+ *
+ * A language written right to left gets the one-letter (`narrow`) name instead, because its short names are whole words
+ * that do not fit a column (Arabic `الأربعاء`), and then the whole name goes with it for a screen reader, which would
+ * otherwise read a single letter. Only when the browser has such names for the language: when it has none it answers
+ * with English letters (Urdu, Pashto, Yiddish), and the short names stay. Every other language keeps its short names.
+ */
+export declare function describeCalendarWeekdayHeading(locale: string, weekdayIndex: number): CalendarWeekdayHeading;
+/** The text of a calendar's weekday heading: see `describeCalendarWeekdayHeading` (which also gives the whole name). */
+export declare function formatCalendarWeekdayLabel(locale: string, weekdayIndex: number): string;

package/dist/i18n/localeDate.js

@@ -0,0 +1,104 @@
+/**
+ * Locale-aware short dates for calendars and range pickers. Values in compositions stay structured (CalendarDate); only
+ * display and typed input use these helpers.
+ */
+import { resolveTextDirection } from "./direction.js";
+/** Formats a calendar day the way `locale` writes short numeric dates (order and separators from Intl). */
+export function formatLocaleShortDate(parts, locale) {
+    try {
+        const jsDate = new Date(parts.year, parts.month - 1, parts.day);
+        const formatter = new Intl.DateTimeFormat(locale, { day: '2-digit', month: '2-digit', year: '2-digit' });
+        return formatter.format(jsDate);
+    }
+    catch (error) {
+        console.warn('[DesignSystem] formatLocaleShortDate failed:', error);
+        return `${String(parts.day).padStart(2, '0')}/${String(parts.month).padStart(2, '0')}/${String(parts.year).slice(-2)}`;
+    }
+}
+/**
+ * Parses a typed short date for `locale`, and still accepts legacy `DD/MM/YY` (day/month with `/` separators).
+ * Returns null when the text is not a valid date.
+ */
+export function parseLocaleShortDate(text, locale) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return null;
+    const legacy = /^(\d{1,2})\/(\d{1,2})\/(\d{2}|\d{4})$/.exec(trimmed);
+    if (legacy) {
+        const day = Number.parseInt(legacy[1], 10);
+        const month = Number.parseInt(legacy[2], 10);
+        let year = Number.parseInt(legacy[3], 10);
+        if (legacy[3].length === 2)
+            year += year >= 70 ? 1900 : 2000;
+        if (month < 1 || month > 12 || day < 1 || day > 31)
+            return null;
+        return { year, month, day };
+    }
+    try {
+        const formatter = new Intl.DateTimeFormat(locale, { day: '2-digit', month: '2-digit', year: '2-digit' });
+        const sample = new Date(2024, 10, 7);
+        const sampleParts = formatter.formatToParts(sample);
+        const order = sampleParts.filter((part) => part.type !== 'literal').map((part) => part.type);
+        const literals = sampleParts.filter((part) => part.type === 'literal').map((part) => part.value);
+        const separator = literals[0] ?? '/';
+        const chunks = trimmed.split(separator).map((chunk) => chunk.trim());
+        if (chunks.length !== 3)
+            return null;
+        const values = {};
+        for (let i = 0; i < 3; i += 1) {
+            const kind = order[i];
+            if (!kind || kind === 'literal')
+                return null;
+            const num = Number.parseInt(chunks[i], 10);
+            if (!Number.isFinite(num))
+                return null;
+            values[kind] = num;
+        }
+        let year = values.year;
+        if (year < 100)
+            year += year >= 70 ? 1900 : 2000;
+        const month = values.month;
+        const day = values.day;
+        if (month < 1 || month > 12 || day < 1 || day > 31)
+            return null;
+        return { year, month, day };
+    }
+    catch (error) {
+        console.warn('[DesignSystem] parseLocaleShortDate failed:', error);
+        return null;
+    }
+}
+/**
+ * Latin letters. A browser that has no one-letter weekday names for a language answers with the English ones
+ * (`S M T W T F S`), which must never stand in the calendar of a language written in another script.
+ */
+const LATIN_LETTER = /\p{Script=Latin}/u;
+/**
+ * Weekday heading for calendar grids: uses Intl `weekday: 'short'` for the column (no code-unit truncation).
+ *
+ * A language written right to left gets the one-letter (`narrow`) name instead, because its short names are whole words
+ * that do not fit a column (Arabic `الأربعاء`), and then the whole name goes with it for a screen reader, which would
+ * otherwise read a single letter. Only when the browser has such names for the language: when it has none it answers
+ * with English letters (Urdu, Pashto, Yiddish), and the short names stay. Every other language keeps its short names.
+ */
+export function describeCalendarWeekdayHeading(locale, weekdayIndex) {
+    try {
+        const date = new Date(Date.UTC(2024, 0, 7 + weekdayIndex));
+        const shortName = new Intl.DateTimeFormat(locale, { weekday: 'short', timeZone: 'UTC' }).format(date);
+        if (resolveTextDirection(locale) !== 'rtl')
+            return { label: shortName, fullName: undefined };
+        const narrowName = new Intl.DateTimeFormat(locale, { weekday: 'narrow', timeZone: 'UTC' }).format(date);
+        if (narrowName === '' || LATIN_LETTER.test(narrowName))
+            return { label: shortName, fullName: undefined };
+        const longName = new Intl.DateTimeFormat(locale, { weekday: 'long', timeZone: 'UTC' }).format(date);
+        return { label: narrowName, fullName: longName };
+    }
+    catch (error) {
+        console.warn('[DesignSystem] describeCalendarWeekdayHeading failed:', error);
+        return { label: '', fullName: undefined };
+    }
+}
+/** The text of a calendar's weekday heading: see `describeCalendarWeekdayHeading` (which also gives the whole name). */
+export function formatCalendarWeekdayLabel(locale, weekdayIndex) {
+    return describeCalendarWeekdayHeading(locale, weekdayIndex).label;
+}

package/dist/i18n/splitMessages.d.ts

@@ -0,0 +1,21 @@
+import type { MessageOverrides } from './translator.ts';
+/**
+ * A page gives the words of a package as one flat `messages` object. When that package has others inside it (an editor
+ * that has the File Browser and a rich text editor in it), the page should not have to know which package a key belongs
+ * to, and each package should only hear about its own keys: a package says "this key does not exist" for every key it does
+ * not have, so a flat object handed to all of them would make each one complain about the others' words.
+ */
+export interface SplitMessages<Name extends string> {
+    /** For each package, the entries of `messages` whose key is in its catalog. Every package has one, empty or not. */
+    slices: Record<Name, MessageOverrides>;
+    /** The entries whose key is in no catalog: a misspelt key, or a key of a package that is not on the page. */
+    unclaimed: MessageOverrides;
+}
+/**
+ * Gives each catalog the entries of `messages` it has a key for. An entry goes to every catalog that has its key (a key
+ * is meant to belong to one package, so that is nearly always one), and to `unclaimed` when no catalog has it. When
+ * `messages` is not an object (nothing, a string, a list) every package gets nothing, as it does on its own.
+ * Nothing is checked here: a value that is not text, or a template that does not read, is said by the package that owns
+ * the key, once, as it is for a page that gives it directly.
+ */
+export declare function splitMessages<Name extends string>(messages: MessageOverrides | null | undefined, catalogs: Readonly<Record<Name, Readonly<Record<string, unknown>>>>): SplitMessages<Name>;

package/dist/i18n/splitMessages.js

@@ -0,0 +1,33 @@
+/** Writes `key` into `target` as an own property, even when `key` is `__proto__`, which `target[key] = …` would turn into a prototype. */
+function setOwn(target, key, value) {
+    Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+}
+/**
+ * Gives each catalog the entries of `messages` it has a key for. An entry goes to every catalog that has its key (a key
+ * is meant to belong to one package, so that is nearly always one), and to `unclaimed` when no catalog has it. When
+ * `messages` is not an object (nothing, a string, a list) every package gets nothing, as it does on its own.
+ * Nothing is checked here: a value that is not text, or a template that does not read, is said by the package that owns
+ * the key, once, as it is for a page that gives it directly.
+ */
+export function splitMessages(messages, catalogs) {
+    const names = Object.keys(catalogs);
+    const slices = {};
+    for (const name of names)
+        slices[name] = {};
+    const unclaimed = {};
+    if (messages === null || messages === undefined || typeof messages !== 'object' || Array.isArray(messages))
+        return { slices, unclaimed };
+    for (const key of Object.keys(messages)) {
+        const value = messages[key];
+        let claimed = false;
+        for (const name of names) {
+            if (Object.prototype.hasOwnProperty.call(catalogs[name], key)) {
+                setOwn(slices[name], key, value);
+                claimed = true;
+            }
+        }
+        if (!claimed)
+            setOwn(unclaimed, key, value);
+    }
+    return { slices, unclaimed };
+}

package/dist/i18n/translator.d.ts

@@ -0,0 +1,61 @@
+/** A value a template can show. */
+export type MessageValue = string | number;
+export type MessageValues = Readonly<Record<string, MessageValue>>;
+/** Something wrong in what the page supplied. Reported once, never thrown: a broken message must not break the screen. */
+export type MessageProblem = {
+    kind: 'unknown-message';
+    key: string;
+    suggestion?: string;
+} | {
+    kind: 'not-text';
+    key: string;
+} | {
+    kind: 'broken-message';
+    key: string;
+    reason: string;
+} | {
+    kind: 'unknown-value';
+    key: string;
+    name: string;
+} | {
+    kind: 'unknown-locale';
+    locale: string;
+};
+/** One line a developer can read in the console about a {@link MessageProblem}. */
+export declare function describeMessageProblem(problem: MessageProblem): string;
+/** The shape the page supplies for `messages`: any of the catalog's keys, with text. */
+export type MessageOverrides = Readonly<Record<string, unknown>>;
+export interface TranslatorOptions<Key extends string> {
+    /** A BCP 47 tag ("de", "pt-BR"). It sets plural rules and number formats. The words come from `messages`. Default "en". */
+    locale?: string;
+    /** The built-in English messages. Every key the screens ask for is here. */
+    catalog: Readonly<Record<Key, string>>;
+    /** The page's own words: any of the catalog's keys. */
+    messages?: MessageOverrides | null;
+    /** Told about each problem once. The default is to say nothing. */
+    onProblem?: (problem: MessageProblem) => void;
+    /**
+     * Whether a text value is put between isolate marks, so that the sentence around it cannot turn it around. The default
+     * is yes for a language written right to left, where a name in another script, one that starts with a digit or one that
+     * ends with a bracket would otherwise be put in the wrong place, and no for any other language.
+     */
+    isolateValues?: boolean;
+}
+export interface Translator<Key extends string> {
+    /** The message for `key`, with `values` put in. An unknown key comes back as the key itself. */
+    t: (key: Key, values?: MessageValues) => string;
+    /** The language tag in use, after checking it ("en" when the one given was not a tag). */
+    readonly locale: string;
+}
+/**
+ * Makes the function that turns keys into text. It never throws for what the page supplied: an unusable message is
+ * reported through `onProblem` (once) and the English one is used in its place.
+ */
+export declare function createTranslator<Key extends string>(options: TranslatorOptions<Key>): Translator<Key>;
+/**
+ * The names of the values a message asks for: each `{name}` in it, and the number a plural looks at, sorted. For a test
+ * or a tool that checks the code gives a message everything it needs. Throws when the template does not parse.
+ */
+export declare function valueNamesOfTemplate(template: string): string[];
+/** Checks `messages` against a catalog without making a translator: what a test, or a build step, can call. */
+export declare function findMessageProblems<Key extends string>(catalog: Readonly<Record<Key, string>>, messages: MessageOverrides): MessageProblem[];