neba 1.6.0 → 1.7.0

package/dist/internal/i18n.d.ts

@@ -14,6 +14,16 @@
  * a picker's "Today", a Pagination's "Next page" — should get it from the same
  * place rather than starting a second table beside this one.
  *
+ * **One exported table per namespace, and never one table of all of them.** A
+ * bundler drops an unused `export const`, and it cannot drop a key out of an
+ * object literal — so a Chip that needs the word "Remove" and reaches it
+ * through a single table holding every namespace ships the ColorPicker's seven
+ * colour words and the Table's seven column words in eighteen languages too.
+ * That was thirty-eight kilobytes of translations behind a two-kilobyte
+ * component. Split per namespace, the Chip carries the four `action` strings
+ * and nothing else. Adding a namespace is therefore a new `export const`
+ * beside the others, not a new key inside one of them.
+ *
  * What is *not* in here is anything `Intl` already knows. Month names, weekday
  * names, AM/PM and number formats come from the platform, which speaks more
  * languages than this file ever will. This is only for the words the platform
@@ -24,255 +34,288 @@
  * you a translation for free, and the prop gets you one for anything else.
  */
 /**
- * One namespace per component, rather than one flat list of keys.
+ * One namespace's strings, in every language that has them.
+ *
+ * `''` is English and is complete by construction — every other tag fills in as
+ * much as it has and is merged over English when it is read, so a half-finished
+ * translation is a half-finished translation rather than a page of blanks.
+ */
+export interface MessageTable<T> {
+    '': T;
+    [tag: string]: Partial<T>;
+}
+/**
+ * The words more than one component needs.
  *
- * A namespace is what makes a partial translation possible: a locale supplies
- * whatever it has and the rest falls back to English one namespace at a time,
- * so adding a namespace here does not silently blank the strings in every
- * language that has not caught up with it yet.
+ * The one namespace here that is not a component, and it exists because five
+ * of them draw the same × and would otherwise each carry their own "Close" in
+ * eighteen languages. A reader meeting that button on a Dialog, a Drawer, a
+ * Popover and a Toast should hear the same word every time, which is easier to
+ * guarantee when there is only one of it.
  */
-export interface NebaMessages {
+export interface ActionMessages {
+    /** The × on a Dialog, a Drawer, a Popover and a Toast. */
+    close: string;
     /**
-     * The words more than one component needs.
-     *
-     * The one namespace here that is not a component, and it exists because five
-     * of them draw the same × and would otherwise each carry their own "Close" in
-     * eighteen languages. A reader meeting that button on a Dialog, a Drawer, a
-     * Popover and a Toast should hear the same word every time, which is easier to
-     * guarantee when there is only one of it.
+     * And the one on an Alert, which is a different act: a dialog is closed
+     * because it has been answered, an alert is waved away.
      */
-    action: {
-        /** The × on a Dialog, a Drawer, a Popover and a Toast. */
-        close: string;
-        /**
-         * And the one on an Alert, which is a different act: a dialog is closed
-         * because it has been answered, an alert is waved away.
-         */
-        dismiss: string;
-        /** The × that empties a Combobox. */
-        clear: string;
-        /** The × on a Chip. */
-        remove: string;
-    };
-    /** TextLink. */
-    link: {
-        /**
-         * What is read out after a link that opens a new tab, and never drawn. A
-         * window changing under the reader is the one thing about a link that is
-         * invisible until it has already happened.
-         */
-        newTab: string;
-    };
-    /** Spoiler. */
-    spoiler: {
-        /** The button that uncovers the content. */
-        reveal: string;
-        /** And the one that covers it again, when the Spoiler is reversible. */
-        hide: string;
-        /** The line above the button, saying why the content is covered. */
-        notice: string;
-    };
-    /** ChatBubble. */
-    chat: {
-        /** The four steps a message goes through, as the mark under it. */
-        sending: string;
-        sent: string;
-        delivered: string;
-        read: string;
-        /** And the fifth, which is not a step: it did not go. */
-        failed: string;
-        /** What the three dots mean. */
-        typing: string;
-    };
-    /** Empty. */
-    empty: {
-        /**
-         * The headline over a region with nothing in it.
-         *
-         * The one string in here that is *drawn* at full size rather than read out
-         * or written on a button, and it is here for the same reason the rest are:
-         * an empty state has nothing to take its words from. What is missing is the
-         * caller's — a search, an inbox, a folder — so the default says only that
-         * there is nothing, and anything more specific is the `title` prop.
-         */
-        title: string;
-    };
-    /**
-     * DataTable.
-     *
-     * A DataTable is the one component in the library that draws chrome of its
-     * own — a search field, a header tick that chooses everything at once, a
-     * footer counting what is on screen — so it is also the one that has the most
-     * to say without being handed the words.
-     */
-    table: {
-        /** Placeholder and accessible name of the search field. */
-        search: string;
-        /** The tick in the header row, which chooses every row at once. */
-        selectAll: string;
-        /** The tick on a row. */
-        selectRow: string;
-        /** Beside the footer's page-size Select. */
-        rowsPerPage: string;
-        /**
-         * Which rows are on screen, out of how many there are. `{start}`, `{end}`
-         * and `{total}` are replaced with the numbers, already formatted for the
-         * locale — a template rather than three fragments, because the order the
-         * three appear in is exactly what differs between languages.
-         */
-        range: string;
-        /** How many rows are chosen. `{count}` is replaced the same way. */
-        selected: string;
-        /**
-         * What a table with no rows in it says. Shared with Table, which has the
-         * same nothing to report and no chrome of its own to say it with.
-         */
-        empty: string;
-    };
+    dismiss: string;
+    /** The × that empties a Combobox. */
+    clear: string;
+    /** The × on a Chip. */
+    remove: string;
+}
+/** The `action` namespace, as Alert, Chip, Combobox, Dialog, Drawer, Popover and Toast read it. */
+export declare const actionMessages: MessageTable<ActionMessages>;
+/** TextLink. */
+export interface LinkMessages {
     /**
-     * ColorPicker.
-     *
-     * All but one of these are names for something with no text on it: a square
-     * of colour, two rails, a grid of swatches. A control a sighted reader
-     * understands from a glance at a gradient is a control that says nothing at
-     * all without them, which makes this the one namespace here where the strings
-     * are the entire accessible interface rather than a convenience on top of it.
+     * What is read out after a link that opens a new tab, and never drawn. A
+     * window changing under the reader is the one thing about a link that is
+     * invisible until it has already happened.
      */
-    color: {
-        /** The saturation/brightness square. */
-        area: string;
-        /** The rail beside it. */
-        hue: string;
-        /** The rail below that, when `alpha` is on. */
-        alpha: string;
-        /** The field the colour can be typed into. */
-        value: string;
-        /** The grid of ready-made colours. */
-        swatches: string;
-        /** The × that empties the control. */
-        clear: string;
-        /** What the trigger reads before anything has been chosen. */
-        empty: string;
-    };
+    newTab: string;
+}
+/** The `link` namespace, as TextLink read it. */
+export declare const linkMessages: MessageTable<LinkMessages>;
+/** Spoiler. */
+export interface SpoilerMessages {
+    /** The button that uncovers the content. */
+    reveal: string;
+    /** And the one that covers it again, when the Spoiler is reversible. */
+    hide: string;
+    /** The line above the button, saying why the content is covered. */
+    notice: string;
+}
+/** The `spoiler` namespace, as Spoiler read it. */
+export declare const spoilerMessages: MessageTable<SpoilerMessages>;
+/** ChatBubble. */
+export interface ChatMessages {
+    /** The four steps a message goes through, as the mark under it. */
+    sending: string;
+    sent: string;
+    delivered: string;
+    read: string;
+    /** And the fifth, which is not a step: it did not go. */
+    failed: string;
+    /** What the three dots mean. */
+    typing: string;
+}
+/** The `chat` namespace, as ChatBubble read it. */
+export declare const chatMessages: MessageTable<ChatMessages>;
+/** Empty. */
+export interface EmptyMessages {
     /**
-     * Rating.
+     * The headline over a region with nothing in it.
      *
-     * A row of stars is the same case the ColorPicker's rails are: the whole
-     * control is a picture, and without these it says nothing at all to a reader
-     * who is not looking at it.
+     * The one string in here that is *drawn* at full size rather than read out
+     * or written on a button, and it is here for the same reason the rest are:
+     * an empty state has nothing to take its words from. What is missing is the
+     * caller's — a search, an inbox, a folder — so the default says only that
+     * there is nothing, and anything more specific is the `title` prop.
      */
-    rating: {
-        /** Names the group, when the caller has not named it themselves. */
-        label: string;
-        /**
-         * What one star — and the whole control, once it is read only — is called.
-         * `{value}` and `{max}` are replaced with the numbers, already formatted
-         * for the locale.
-         *
-         * A sentence with both numbers in it rather than "3 stars", because a count
-         * of stars is a plural in most languages and a fraction in none of them:
-         * "3 out of 5" is one string per locale, and "3 stars" is one per locale
-         * per plural form.
-         */
-        value: string;
-        /** And what it is called before anything has been chosen. */
-        empty: string;
-    };
+    title: string;
+}
+/** The `empty` namespace, as Empty, DataTable, HeatmapChart and PieChart read it. */
+export declare const emptyMessages: MessageTable<EmptyMessages>;
+/**
+ * DataTable.
+ *
+ * A DataTable is the one component in the library that draws chrome of its
+ * own — a search field, a header tick that chooses everything at once, a
+ * footer counting what is on screen — so it is also the one that has the most
+ * to say without being handed the words.
+ */
+export interface TableMessages {
+    /** Placeholder and accessible name of the search field. */
+    search: string;
+    /** The tick in the header row, which chooses every row at once. */
+    selectAll: string;
+    /** The tick on a row. */
+    selectRow: string;
+    /** Beside the footer's page-size Select. */
+    rowsPerPage: string;
     /**
-     * NumberField.
-     *
-     * Two buttons with an arrow on each and nothing else, which is the same case
-     * the ColorPicker's rails are.
+     * Which rows are on screen, out of how many there are. `{start}`, `{end}`
+     * and `{total}` are replaced with the numbers, already formatted for the
+     * locale — a template rather than three fragments, because the order the
+     * three appear in is exactly what differs between languages.
      */
-    number: {
-        /** The stepper that goes up. */
-        increase: string;
-        /** And the one that goes down. */
-        decrease: string;
-    };
+    range: string;
+    /** How many rows are chosen. `{count}` is replaced the same way. */
+    selected: string;
     /**
-     * Pagination.
-     *
-     * Every string here names a control that is a number or an arrow, so without
-     * them the row reads out as a list of digits with no idea what they page
-     * through.
+     * What a table with no rows in it says. Shared with Table, which has the
+     * same nothing to report and no chrome of its own to say it with.
      */
-    pagination: {
-        /** Names the `<nav>` landmark. */
-        label: string;
-        /** One page button. `{page}` is replaced with the number. */
-        page: string;
-        /**
-         * Where the reader is, read out rather than drawn. `{page}` and `{total}`
-         * are both replaced — one sentence rather than two fragments, because a
-         * count of pages and the page you are on go in opposite orders depending on
-         * the language.
-         */
-        status: string;
-        previous: string;
-        next: string;
-        first: string;
-        last: string;
-    };
-    /** Carousel. */
-    carousel: {
-        /** Names the region, beside the `carousel` roledescription. */
-        label: string;
-        /** One slide. `{index}` and `{total}` are replaced with the numbers. */
-        slide: string;
-        previous: string;
-        next: string;
-    };
+    empty: string;
+}
+/** The `table` namespace, as Table and DataTable read it. */
+export declare const tableMessages: MessageTable<TableMessages>;
+/**
+ * ColorPicker.
+ *
+ * All but one of these are names for something with no text on it: a square
+ * of colour, two rails, a grid of swatches. A control a sighted reader
+ * understands from a glance at a gradient is a control that says nothing at
+ * all without them, which makes this the one namespace here where the strings
+ * are the entire accessible interface rather than a convenience on top of it.
+ */
+export interface ColorMessages {
+    /** The saturation/brightness square. */
+    area: string;
+    /** The rail beside it. */
+    hue: string;
+    /** The rail below that, when `alpha` is on. */
+    alpha: string;
+    /** The field the colour can be typed into. */
+    value: string;
+    /** The grid of ready-made colours. */
+    swatches: string;
+    /** The × that empties the control. */
+    clear: string;
+    /** What the trigger reads before anything has been chosen. */
+    empty: string;
+}
+/** The `color` namespace, as ColorPicker read it. */
+export declare const colorMessages: MessageTable<ColorMessages>;
+/**
+ * Rating.
+ *
+ * A row of stars is the same case the ColorPicker's rails are: the whole
+ * control is a picture, and without these it says nothing at all to a reader
+ * who is not looking at it.
+ */
+export interface RatingMessages {
+    /** Names the group, when the caller has not named it themselves. */
+    label: string;
     /**
-     * ScrollZone.
+     * What one star — and the whole control, once it is read only — is called.
+     * `{value}` and `{max}` are replaced with the numbers, already formatted
+     * for the locale.
      *
-     * Both buttons are an arrow with nothing else on them, and which way the
-     * strip runs is a prop — so the words are logical rather than physical. A
-     * vertical zone's "back" is up, and under RTL a horizontal one's is to the
-     * right.
+     * A sentence with both numbers in it rather than "3 stars", because a count
+     * of stars is a plural in most languages and a fraction in none of them:
+     * "3 out of 5" is one string per locale, and "3 stars" is one per locale
+     * per plural form.
      */
-    scroll: {
-        previous: string;
-        next: string;
-    };
-    /** Breadcrumb. */
-    breadcrumb: {
-        /** Names the `<nav>` landmark. */
-        label: string;
-        /** The `…` that puts the folded middle of the trail back. */
-        expand: string;
-    };
-    /** Combobox. */
-    combobox: {
-        /** The line where the list would be, when nothing matched what was typed. */
-        empty: string;
-        /** The × on one chosen entry. `{label}` is replaced with its own label. */
-        remove: string;
-    };
-    /** Overlay. */
-    overlay: {
-        /** Names the sheet that covers whatever it was wrapped around. */
-        label: string;
-    };
+    value: string;
+    /** And what it is called before anything has been chosen. */
+    empty: string;
+}
+/** The `rating` namespace, as Rating read it. */
+export declare const ratingMessages: MessageTable<RatingMessages>;
+/**
+ * NumberField.
+ *
+ * Two buttons with an arrow on each and nothing else, which is the same case
+ * the ColorPicker's rails are.
+ */
+export interface NumberMessages {
+    /** The stepper that goes up. */
+    increase: string;
+    /** And the one that goes down. */
+    decrease: string;
+}
+/** The `number` namespace, as NumberField read it. */
+export declare const numberMessages: MessageTable<NumberMessages>;
+/**
+ * Pagination.
+ *
+ * Every string here names a control that is a number or an arrow, so without
+ * them the row reads out as a list of digits with no idea what they page
+ * through.
+ */
+export interface PaginationMessages {
+    /** Names the `<nav>` landmark. */
+    label: string;
+    /** One page button. `{page}` is replaced with the number. */
+    page: string;
     /**
-     * WindowPane.
-     *
-     * The three buttons on a title bar that are drawings of what they do, and the
-     * handle that has no drawing at all. The × is `action.close`, which every
-     * other component's close button already reads — a reader meeting it on a
-     * Dialog and on a window should hear the same word.
+     * Where the reader is, read out rather than drawn. `{page}` and `{total}`
+     * are both replaced — one sentence rather than two fragments, because a
+     * count of pages and the page you are on go in opposite orders depending on
+     * the language.
      */
-    window: {
-        minimize: string;
-        maximize: string;
-        /** What the maximize button becomes once the window is maximized. */
-        restore: string;
-        /** Names the corner a pointer drags to resize. */
-        resize: string;
-    };
+    status: string;
+    previous: string;
+    next: string;
+    first: string;
+    last: string;
+}
+/** The `pagination` namespace, as Pagination read it. */
+export declare const paginationMessages: MessageTable<PaginationMessages>;
+/** Carousel. */
+export interface CarouselMessages {
+    /** Names the region, beside the `carousel` roledescription. */
+    label: string;
+    /** One slide. `{index}` and `{total}` are replaced with the numbers. */
+    slide: string;
+    previous: string;
+    next: string;
+}
+/** The `carousel` namespace, as Carousel read it. */
+export declare const carouselMessages: MessageTable<CarouselMessages>;
+/**
+ * ScrollZone.
+ *
+ * Both buttons are an arrow with nothing else on them, and which way the
+ * strip runs is a prop — so the words are logical rather than physical. A
+ * vertical zone's "back" is up, and under RTL a horizontal one's is to the
+ * right.
+ */
+export interface ScrollMessages {
+    previous: string;
+    next: string;
+}
+/** The `scroll` namespace, as ScrollZone read it. */
+export declare const scrollMessages: MessageTable<ScrollMessages>;
+/** Breadcrumb. */
+export interface BreadcrumbMessages {
+    /** Names the `<nav>` landmark. */
+    label: string;
+    /** The `…` that puts the folded middle of the trail back. */
+    expand: string;
+}
+/** The `breadcrumb` namespace, as Breadcrumb read it. */
+export declare const breadcrumbMessages: MessageTable<BreadcrumbMessages>;
+/** Combobox. */
+export interface ComboboxMessages {
+    /** The line where the list would be, when nothing matched what was typed. */
+    empty: string;
+    /** The × on one chosen entry. `{label}` is replaced with its own label. */
+    remove: string;
+}
+/** The `combobox` namespace, as Combobox read it. */
+export declare const comboboxMessages: MessageTable<ComboboxMessages>;
+/** Overlay. */
+export interface OverlayMessages {
+    /** Names the sheet that covers whatever it was wrapped around. */
+    label: string;
+}
+/** The `overlay` namespace, as Overlay read it. */
+export declare const overlayMessages: MessageTable<OverlayMessages>;
+/**
+ * WindowPane.
+ *
+ * The three buttons on a title bar that are drawings of what they do, and the
+ * handle that has no drawing at all. The × is `action.close`, which every
+ * other component's close button already reads — a reader meeting it on a
+ * Dialog and on a window should hear the same word.
+ */
+export interface WindowMessages {
+    minimize: string;
+    maximize: string;
+    /** What the maximize button becomes once the window is maximized. */
+    restore: string;
+    /** Names the corner a pointer drags to resize. */
+    resize: string;
 }
+/** The `window` namespace, as WindowPane read it. */
+export declare const windowMessages: MessageTable<WindowMessages>;
 /**
- * The strings for a locale, merged over English.
+ * One namespace's strings for a locale, merged over English.
  *
  * `undefined` is English rather than the runtime's own locale, and that is
  * deliberate: `navigator.language` differs between the server that renders the
@@ -281,9 +324,9 @@ export interface NebaMessages {
  * at. A component that should follow the reader is told which language to
  * follow.
  */
-export declare function resolveMessages(locale?: string): NebaMessages;
+export declare function resolveMessages<T extends object>(table: MessageTable<T>, locale?: string): T;
 /** The same, as a hook, for the components that read it during a render. */
-export declare function useMessages(locale?: string): NebaMessages;
+export declare function useMessages<T extends object>(table: MessageTable<T>, locale?: string): T;
 /**
  * Fills the `{placeholders}` in one of the strings above.
  *
@@ -295,3 +338,73 @@ export declare function useMessages(locale?: string): NebaMessages;
  * hole in the middle of a sentence.
  */
 export declare function fillMessage(template: string, values: Record<string, string>): string;
+/**
+ * A language, as `neba/locales` hands it over.
+ *
+ * Every namespace is optional and every string inside one is too: a locale
+ * fills in what it has and English answers for the rest, so a translation that
+ * has not caught up with a new component is a translation that has not caught
+ * up rather than a page of blanks.
+ */
+export interface NebaLocale {
+    /** Action. */
+    action?: Partial<ActionMessages>;
+    /** Link. */
+    link?: Partial<LinkMessages>;
+    /** Spoiler. */
+    spoiler?: Partial<SpoilerMessages>;
+    /** Chat. */
+    chat?: Partial<ChatMessages>;
+    /** Empty. */
+    empty?: Partial<EmptyMessages>;
+    /** Table. */
+    table?: Partial<TableMessages>;
+    /** Color. */
+    color?: Partial<ColorMessages>;
+    /** Rating. */
+    rating?: Partial<RatingMessages>;
+    /** Number. */
+    number?: Partial<NumberMessages>;
+    /** Pagination. */
+    pagination?: Partial<PaginationMessages>;
+    /** Carousel. */
+    carousel?: Partial<CarouselMessages>;
+    /** Scroll. */
+    scroll?: Partial<ScrollMessages>;
+    /** Breadcrumb. */
+    breadcrumb?: Partial<BreadcrumbMessages>;
+    /** Combobox. */
+    combobox?: Partial<ComboboxMessages>;
+    /** Overlay. */
+    overlay?: Partial<OverlayMessages>;
+    /** Window. */
+    window?: Partial<WindowMessages>;
+}
+/**
+ * Teaches the library a language.
+ *
+ * English is the only one built in. Everything else is a module under
+ * `neba/locales` that a project imports and registers once, at module scope,
+ * before it renders:
+ *
+ * ```ts
+ * import { registerMessages, ko } from 'neba/locales';
+ *
+ * registerMessages('ko', ko);
+ * ```
+ *
+ * Shipping the other seventeen unconditionally would put them in the bundle of
+ * every product that speaks one language, because a bundler cannot drop a key
+ * out of an object literal — which is the same reason the namespaces above are
+ * fourteen exports rather than one table. Registering is what makes the cost
+ * follow the need.
+ *
+ * The tag is matched the way a `locale` prop is: by script, then by region,
+ * then by language. Registering `zh-hans` answers `zh-CN` and a bare `zh`;
+ * registering `pt` answers `pt-BR`.
+ *
+ * Calling this after a tree has rendered does not re-render it. It replaces
+ * what a locale had, rather than merging into it, so a second call with a
+ * partial locale is a correction and not an addition.
+ */
+export declare function registerMessages(tag: string, locale: NebaLocale): void;