edytor 1.0.0-rc.2 → 1.0.0

package/dist/labels.d.ts

@@ -1,18 +1,15 @@
 /**
- * The words the editor's chrome shows or says: one dictionary section per
- * bundled plugin, plus `editor` for the view itself (announcements, a
- * suggestion's name). English is the default; each plugin factory takes a
- * `labels` option with the entries to replace (`PartialLabels`), and
- * `<Edytor labels>` takes the `editor` section.
+ * The words the package itself shows or says: the kinds' and commands'
+ * names (the menus search them), the document's own markup (placeholders,
+ * a to-do's checkbox, an empty body's hint, a page's or an entry's
+ * "Untitled"), the accessible names of the elements it renders, and the
+ * view's announcements. English is the default. A view's `labels`
+ * (`<Edytor labels>`) replaces any entry of any section, and its
+ * `keywords` a command's slash keywords, by command id. The words of the
+ * chrome (menus, bars, panels, cards) are the app's: its snippets write them.
  *
  * A label that says something about a value is a function of it, so a
  * language can order and inflect the words: `moved: (what) => …`.
- *
- * Group names (`KindPreset.group`: `Basic blocks`, `Advanced blocks`,
- * `Media`, `Layout`), the toolbar's color names (`TOOLBAR_COLORS`) and the
- * block palette's (`BLOCK_COLORS`, and `default`) are keys: the slash menu's
- * `groups`, the toolbar's `colors` and the block menu's `colors` map them to
- * what is shown.
  */
 /** What the view itself says: its live announcements and a suggestion's default name. */
 export type EditorLabels = {
@@ -29,14 +26,8 @@ export type EditorLabels = {
     /** A move to a place (a drop). */
     moved: (what: string) => string;
     deleted: (what: string) => string;
-    /** A trigger menu's accessible name when its trigger names none (`Trigger.name`). */
-    triggerMenu: string;
-    /** A trigger menu's text while a search is pending, when its trigger says none. */
-    searching: string;
-    /** A trigger menu's text when no row matches, when its trigger says none. */
-    noResults: string;
 };
-/** The rich text kinds and marks: menu rows, toolbar buttons, placeholders. */
+/** The rich text kinds and marks: their names, the document's own words, placeholders. */
 export type RichTextLabels = {
     /** Each preset's label: the slash menu, Turn into, the handles' names. */
     kinds: {
@@ -55,7 +46,7 @@ export type RichTextLabels = {
         quote: string;
         divider: string;
     };
-    /** The toolbar's mark buttons. */
+    /** The marks' toolbar buttons (`MarkDefinition.toolbar.label`). */
     marks: {
         bold: string;
         italic: string;
@@ -65,7 +56,17 @@ export type RichTextLabels = {
     };
     /** A to-do's checkbox. */
     checkbox: string;
-    /** `createRichTextPlaceholder`'s texts. */
+    /** The hint an empty body shows (an open toggle's, a callout's): a press there starts it. */
+    emptyBody: {
+        toggle: string;
+        callout: string;
+    };
+    /** A callout's icon button: `change` its icon, `add` one when it has none. */
+    calloutIcon: {
+        change: string;
+        add: string;
+    };
+    /** `richTextPlaceholder`'s texts. */
     placeholders: {
         heading: (level: 1 | 2 | 3) => string;
         toggleHeading: (level: 1 | 2 | 3) => string;
@@ -73,7 +74,7 @@ export type RichTextLabels = {
         todo: string;
         toggle: string;
         quote: string;
-        /** A focused empty callout. */
+        /** An empty callout's title. */
         callout: string;
         /** A focused empty caption (image, embed, bookmark, file, video, audio). */
         caption: string;
@@ -81,187 +82,44 @@ export type RichTextLabels = {
         empty: string;
     };
 };
-export type ToolbarLabels = {
-    /** The bar's accessible name. */
-    bar: string;
-    /** The kind button when the selection's kind has no label. */
-    text: string;
-    turnInto: string;
-    link: string;
-    /** The link field's accessible name. */
-    linkUrl: string;
-    linkPlaceholder: string;
-    apply: string;
-    applyLink: string;
-    remove: string;
-    removeLink: string;
-    color: string;
-    textColor: string;
-    backgroundColor: string;
-    /** A color's name, by its `TOOLBAR_COLORS` name. */
-    colors: Record<string, string>;
-    /** A text color swatch, from the color's name. */
-    colorText: (color: string) => string;
-    /** A background swatch, from the color's name. */
-    colorBackground: (color: string) => string;
-    /** The card under a hovered link. */
-    card: string;
-    open: string;
-    openLink: string;
-    edit: string;
-    editLink: string;
-};
-export type SlashMenuLabels = {
-    /** The `+` menu's field. */
-    filter: string;
-    filterLabel: string;
-    /** The list's accessible name. */
-    list: string;
-    noResults: string;
-    close: string;
-    /** The key shown beside Close. */
-    closeKey: string;
-    /** A section heading, by its group key (`Basic blocks`, `Advanced blocks`, `Media`, `Layout`, `Color`, `Inline`); others show as they are. */
-    groups: Record<string, string>;
-};
+/** The block menu's actions (its search matches them) and the block colours' commands. */
 export type BlockMenuLabels = {
-    search: string;
-    searchLabel: string;
-    /** The menu's accessible name. */
-    menu: string;
-    /** The heading when the block's kind has no label. */
-    block: string;
     turnInto: string;
-    /** The Color row, and its flyout's accessible name. */
+    /** The Color row. */
     color: string;
-    /** The flyout's sections. */
-    textColor: string;
-    backgroundColor: string;
     /** A color's name, by its `BLOCK_COLORS` name (`red`), `default` for none. */
     colors: Record<string, string>;
-    /** A text color row, from the color's name ("Red text"). */
+    /** A text color row and command, from the color's name ("Red text"). */
     colorText: (color: string) => string;
-    /** A background row, from the color's name ("Red background"). */
+    /** A background row and command, from the color's name ("Red background"). */
     colorBackground: (color: string) => string;
     copyLink: string;
     duplicate: string;
     moveUp: string;
     moveDown: string;
     delete: string;
-    noResults: string;
     /** Key names in the shortcuts shown off a Mac. */
     ctrl: string;
     shift: string;
     deleteKey: string;
 };
-export type BlockHandlesLabels = {
-    /** The `+`'s accessible name, from its block's kind. */
-    add: (kind: string) => string;
-    /** The same, for a block directly in a column (Alt adds a column). */
-    addBeside: (kind: string) => string;
-    /** The `+`'s tooltip. */
-    addHint: string;
-    addBesideHint: string;
-    /** The grip's accessible name, from its block's kind. */
-    grip: (kind: string) => string;
-};
 export type ImageLabels = {
-    /** The preset, and a readonly empty image. */
-    image: string;
-    add: string;
-    link: string;
-    linkPlaceholder: string;
-    embed: string;
-    upload: string;
-    uploading: string;
-    /** An inline image over the size limit (`limit`, in words); `upload`: an upload is offered. */
-    tooLarge: (limit: string, upload: boolean) => string;
-    uploadFailed: string;
-    invalid: string;
-    /** The chrome's toolbar name. */
-    toolbar: string;
-    alignLeft: string;
-    alignCenter: string;
-    alignRight: string;
-    alt: string;
-    altPlaceholder: string;
-};
-/** One media kind's empty block and menu row. */
-export type MediaKindLabels = {
     /** The preset. */
-    label: string;
-    /** The empty block's button. */
-    add: string;
-    placeholder: string;
-    submit: string;
-    invalid: string;
+    image: string;
 };
+/** The media kinds' presets, and a file's size. */
 export type MediaLabels = {
-    embed: MediaKindLabels & {
-        /** The row a pasted link offers. */
-        offer: string;
-    };
-    bookmark: MediaKindLabels & {
-        offer: string;
-    };
-    file: MediaKindLabels & {
-        /** The button when an upload is offered. */
-        addOrUpload: string;
-    };
-    video: MediaKindLabels;
-    audio: MediaKindLabels;
-    upload: string;
-    /** A pasted or dropped file's block while it uploads. */
-    uploading: string;
-    /** A pasted or dropped file whose upload failed. */
-    uploadFailed: string;
+    embed: string;
+    bookmark: string;
+    file: string;
+    video: string;
+    audio: string;
     /** A file's size, in bytes. */
     fileSize: (bytes: number) => string;
-    /** The menu a pasted link opens. */
-    pasteAs: string;
-    /** Its row keeping the link. */
-    pasteLink: string;
 };
 export type CodeLabels = {
-    /** The preset. */
+    /** The preset (a language's name is its `CodePluginOptions.languages` row's). */
     code: string;
-    /** The language picker's name. */
-    language: string;
-    copy: string;
-    copied: string;
-    /** A language's label, by id, over the language list's own. */
-    languages: Record<string, string>;
-};
-export type FindLabels = {
-    /** The bar's accessible name. */
-    bar: string;
-    query: string;
-    queryPlaceholder: string;
-    noResults: string;
-    /** The current match and the count. */
-    count: (current: number, total: number) => string;
-    matchCase: string;
-    previous: string;
-    previousHint: string;
-    next: string;
-    nextHint: string;
-    close: string;
-    closeHint: string;
-    replaceWith: string;
-    replace: string;
-    replaceAll: string;
-};
-export type SuggestionsLabels = {
-    /** A suggestion's name when it has no `label`. */
-    suggestion: string;
-    /** While it streams, from its `label`. */
-    writing: (label: string | undefined) => string;
-    accept: string;
-    discard: string;
-    retry: string;
-    /** Key names in the hints. */
-    ctrl: string;
-    escape: string;
 };
 /** The page block (`createPagePlugin`). */
 export type PageLabels = {
@@ -279,73 +137,11 @@ export type TocLabels = {
     /** The hint shown with no heading. */
     empty: string;
 };
-/** The `[[` page link menu and atom (`createPageLinkPlugin`). */
+/** The `[[` page link atom (`createPageLinkPlugin`). */
 export type PageLinkLabels = {
-    /** The menu's accessible name. */
-    menu: string;
-    /** The menu while a search is pending, with no rows. */
-    searching: string;
-    noResults: string;
     /** An atom whose page has no title. */
     untitled: string;
 };
-/** The `@` mention menu (`createMentionPlugin`). */
-export type MentionLabels = {
-    /** The menu's accessible name. */
-    menu: string;
-    /** The menu while a search is pending, with no rows. */
-    searching: string;
-    noResults: string;
-};
-/** The version history panel (`HistoryPanel`). */
-export type HistoryPanelLabels = {
-    /** The panel's name (its `aria-label`). */
-    title: string;
-    /** The list's name. */
-    versions: string;
-    /** The first half of a day (before local noon). */
-    morning: string;
-    /** The second half of a day (until midnight). */
-    evening: string;
-    loading: string;
-    /** No version stored yet. */
-    empty: string;
-    /** A version's editors are unknown (a server edit). */
-    noEditors: string;
-    /** Editors left out of a version's list, after the names shown. */
-    moreEditors: (count: number) => string;
-    /** Shown before a version's write time. */
-    saved: string;
-    /** The preview's name (its `aria-label`). */
-    preview: string;
-    /** Pick a version to preview it. */
-    choose: string;
-    /** The highlight toggle. */
-    highlight: string;
-    /** Blocks added since the version. */
-    added: (count: number) => string;
-    /** Blocks removed since the version. */
-    removed: (count: number) => string;
-    /** Blocks changed since the version. */
-    changed: (count: number) => string;
-    /** The version equals the current document. */
-    same: string;
-    restore: string;
-    restoring: string;
-    undo: string;
-    restored: string;
-    /** A restore that changed nothing (`noop`). */
-    unchanged: string;
-    /** The version is gone (`refused`). */
-    unavailable: string;
-    undone: string;
-    /** An undo with no restore to undo (`noop`). */
-    nothingToUndo: string;
-    /** A `401` or `403`. */
-    denied: string;
-    /** Any other failure. */
-    failed: string;
-};
 /** The block and inline equations (`createEquationPlugin`). */
 export type EquationLabels = {
     /** The block preset, and the block's accessible name. */
@@ -356,11 +152,6 @@ export type EquationLabels = {
     blockPlaceholder: string;
     /** An empty inline equation. */
     inlinePlaceholder: string;
-    /** The editor's accessible name, and its field's. */
-    editor: string;
-    /** The field's placeholder. */
-    placeholder: string;
-    done: string;
     /** TeX that does not render: shown as the equation's title, with KaTeX's message. */
     invalid: string;
 };
@@ -370,35 +161,14 @@ export type ColumnsLabels = {
     /** A resize band's accessible name. */
     resize: string;
 };
-/** The comments plugin (`createCommentsPlugin`): its toolbar button, sidebar and composer. */
+/** The comments plugin (`createCommentsPlugin`): its toolbar button and its sidebar. */
 export type CommentsLabels = {
-    /** The toolbar button and the sidebar's accessible name. */
+    /** The toolbar button, and a thread's card's accessible name. */
     comment: string;
     /** The sidebar's accessible name. */
     sidebar: string;
-    /** The new thread's field. */
-    placeholder: string;
-    /** A thread's reply field. */
-    reply: string;
-    /** The button posting a new thread or a reply. */
-    post: string;
-    cancel: string;
-    resolve: string;
-    reopen: string;
-    delete: string;
-    /** A resolved thread's line, with who resolved it. */
-    resolvedBy: (name: string) => string;
-    /** The button showing the resolved threads, with their count. */
-    showResolved: (count: number) => string;
-    hideResolved: string;
-    /** The current user, in place of their name. */
-    you: string;
-    /** When a comment was written (ms since the epoch). */
-    when: (at: number) => string;
-    /** A request the server refused or could not answer. */
-    failed: string;
 };
-/** The table block and its controls (`createTablePlugin`). */
+/** The table block (`createTablePlugin`). */
 export type TableLabels = {
     /** The "Table" command, and a table's accessible name. */
     table: string;
@@ -410,23 +180,8 @@ export type TableLabels = {
     insertRowBelow: string;
     insertColumnLeft: string;
     insertColumnRight: string;
-    /** The row and column menus. */
-    insertAbove: string;
-    insertBelow: string;
-    insertLeft: string;
-    insertRight: string;
-    moveUp: string;
-    moveDown: string;
-    moveLeft: string;
-    moveRight: string;
     deleteRow: string;
     deleteColumn: string;
-    /** The `+` under the table and beside it. */
-    addRow: string;
-    addColumn: string;
-    /** The grips that open the row and column menus. */
-    rowMenu: string;
-    columnMenu: string;
     /** A column's resize band. */
     resize: string;
     /** A padded cell (a row showing none in a column): its first press creates it. */
@@ -436,57 +191,79 @@ export type TableLabels = {
 export type Labels = {
     editor: EditorLabels;
     richText: RichTextLabels;
-    toolbar: ToolbarLabels;
-    slashMenu: SlashMenuLabels;
     blockMenu: BlockMenuLabels;
-    blockHandles: BlockHandlesLabels;
     image: ImageLabels;
     media: MediaLabels;
     code: CodeLabels;
-    find: FindLabels;
-    suggestions: SuggestionsLabels;
     columns: ColumnsLabels;
     page: PageLabels;
     toc: TocLabels;
     pageLink: PageLinkLabels;
     comments: CommentsLabels;
     table: TableLabels;
-    mention: MentionLabels;
-    history: HistoryPanelLabels;
     equation: EquationLabels;
 };
+/** The entries of a section to replace: any of them, and any entry of a nested group. */
+type Overrides<L> = {
+    [P in keyof L]?: L[P] extends (...args: never[]) => unknown ? L[P] : L[P] extends object ? Partial<L[P]> : L[P];
+};
 /**
- * The entries of section `K` to replace: any of them, and any entry of a
- * nested group (`placeholders`, `groups`, a media kind) without the others.
+ * A view's words (`<Edytor labels>`): any entry of any section, and any
+ * entry of a nested group (`placeholders`, `kinds`) without the others;
+ * `keywords` replaces a command's slash keywords by command id (list the
+ * English ones in it to keep them).
  */
-export type PartialLabels<K extends keyof Labels> = {
-    [P in keyof Labels[K]]?: Labels[K][P] extends (...args: never[]) => unknown ? Labels[K][P] : Labels[K][P] extends object ? Partial<Labels[K][P]> : Labels[K][P];
+export type PartialLabels = {
+    [K in keyof Labels]?: Overrides<Labels[K]>;
+} & {
+    keywords?: Partial<Record<string, string[]>>;
 };
+/** The `editor` section in English. */
+export declare const editorEnglish: EditorLabels;
+/** The `richText` section in English. */
+export declare const richTextEnglish: RichTextLabels;
+/** The `blockMenu` section in English. */
+export declare const blockMenuEnglish: BlockMenuLabels;
+/** The `image` section in English. */
+export declare const imageEnglish: ImageLabels;
+/** The `media` section in English. */
+export declare const mediaEnglish: MediaLabels;
+/** The `code` section in English. */
+export declare const codeEnglish: CodeLabels;
+/** The `columns` section in English. */
+export declare const columnsEnglish: ColumnsLabels;
+/** The `page` section in English. */
+export declare const pageEnglish: PageLabels;
+/** The `toc` section in English. */
+export declare const tocEnglish: TocLabels;
+/** The `pageLink` section in English. */
+export declare const pageLinkEnglish: PageLinkLabels;
+/** The `comments` section in English. */
+export declare const commentsEnglish: CommentsLabels;
+/** The `table` section in English. */
+export declare const tableEnglish: TableLabels;
+/** The `equation` section in English. */
+export declare const equationEnglish: EquationLabels;
 /**
  * The English dictionary: the default of every section. Frozen: start
- * yours from a copy (`{ ...englishLabels.toolbar, link: '…' }`).
+ * yours from a copy (`{ ...englishLabels.richText, checkbox: '…' }`). Each
+ * plugin reads only its own section, so an app ships the words of the
+ * plugins it lists.
  */
 export declare const englishLabels: Labels;
 /**
- * Section `section` of the dictionary with `overrides` over the English one:
- * an entry replaces its English entry, a nested group's entries replace
- * only theirs.
- */
-export declare const labelsWith: <K extends keyof Labels>(section: K, overrides: PartialLabels<K> | undefined) => Labels[K];
-/**
- * The keywords of command `id`: `overrides`' entry for it when there is one
- * (it replaces the defaults: list the English ones in it to keep them),
- * else `defaults`.
+ * The words of `section` in `view` (`english` its English words): the
+ * view's `labels` entries over them, a nested group's entries replacing
+ * only theirs. English for no view (a document read without one).
  */
-export declare const keywordsOf: (id: string, defaults: string[] | undefined, overrides: Partial<Record<string, string[]>> | undefined) => string[] | undefined;
+export declare const labelsOf: <K extends keyof Labels>(view: {
+    readonly labels: PartialLabels;
+} | undefined, section: K, english: Labels[K]) => Labels[K];
 /**
- * One plugin's labels per view: the first plugin of its kind listed in a
- * view claims them, as its kind records (first wins); its components read
- * them through the view they render in, English when none claimed them.
+ * The slash keywords of command `id` in `view`: its `keywords` entry for
+ * the id when there is one (it replaces the defaults), else `defaults`.
  */
-export declare const viewLabels: <K extends keyof Labels>(section: K) => {
-    /** `labels` for `view`, unless a plugin listed before claimed it. */
-    claim: (view: object | undefined, labels: Labels[K]) => void;
-    /** The labels of `view` (English for none, or a view no plugin claimed). */
-    of: (view: object | undefined) => Labels[K];
-};
+export declare const keywordsOf: (view: {
+    readonly labels: PartialLabels;
+} | undefined, id: string, defaults: string[] | undefined) => string[] | undefined;
+export {};