chapterjs 0.1.2 → 0.1.4

package/dist/components/layout.js

@@ -0,0 +1,279 @@
+// The pieces of a message that have no action of their own, written where
+// the message is: rows, link and premium buttons, texts, sections,
+// thumbnails, galleries, files, separators and containers. Each is checked
+// against the limits of Discord when it is made.
+// https://docs.discord.com/developers/components/reference
+import { Limits } from '../discord/api.js';
+import { ButtonStyle, ComponentType, } from '../discord/types/component.js';
+import { emojiOf, piece, compose, renderedOf, } from './instance.js';
+const fail = (message) => {
+    throw new TypeError(message);
+};
+function checkText(what, value, max, { required = true } = {}) {
+    if (value === undefined) {
+        return required ? fail(`${what} is missing.`) : undefined;
+    }
+    if (typeof value !== 'string') {
+        return fail(`${what} is a text, got ${typeof value}.`);
+    }
+    if (value.trim() === '')
+        return fail(`${what} is empty.`);
+    if (value.length > max) {
+        return fail(`${what} is ${value.length} characters long: Discord accepts ${max} at most.`);
+    }
+    return value;
+}
+/**
+ * A button that opens a link. Nothing runs in your bot when it is clicked:
+ * Discord opens the address.
+ * @see https://docs.discord.com/developers/components/reference#button
+ */
+export function linkButton(options) {
+    if (typeof options !== 'object' || options === null) {
+        fail(`linkButton() takes an object like { label: 'Docs', url: '...' }.`);
+    }
+    const url = checkText('The url of a link button', options.url, Limits.ButtonUrl);
+    if (!/^https?:\/\/|^discord:\/\//.test(url)) {
+        fail(`The url of a link button must start with https:// (got ${JSON.stringify(url)}).`);
+    }
+    const label = checkText('The label of a link button', options.label, Limits.ButtonLabel, { required: false });
+    if (label === undefined && options.emoji === undefined) {
+        fail('A link button needs a label or an emoji.');
+    }
+    const raw = {
+        type: ComponentType.Button,
+        style: ButtonStyle.Link,
+        url,
+    };
+    if (label !== undefined)
+        raw.label = label;
+    if (options.emoji !== undefined)
+        raw.emoji = emojiOf(options.emoji, 'a link button');
+    if (options.disabled)
+        raw.disabled = true;
+    return piece('button', raw);
+}
+/**
+ * A button that offers something to buy: Discord shows the name and the
+ * price of the SKU itself.
+ * @see https://docs.discord.com/developers/components/reference#button
+ */
+export function premiumButton(skuId, { disabled = false } = {}) {
+    if (typeof skuId !== 'string' || !/^\d+$/.test(skuId)) {
+        fail(`premiumButton() takes the id of a SKU, got ${JSON.stringify(skuId)}.`);
+    }
+    const raw = {
+        type: ComponentType.Button,
+        style: ButtonStyle.Premium,
+        sku_id: skuId,
+    };
+    if (disabled)
+        raw.disabled = true;
+    return piece('button', raw);
+}
+/**
+ * A row of components: up to 5 buttons, or one select menu. The framework
+ * makes rows by itself; use this to choose which buttons share a row.
+ * @see https://docs.discord.com/developers/components/reference#action-row
+ */
+export function row(components) {
+    if (!Array.isArray(components) || components.length === 0) {
+        fail('row() takes a list of buttons, or one select menu.');
+    }
+    const rendered = components.map((component, index) => renderedOf(component, `Component ${index + 1} of a row`));
+    if (rendered.some(one => one.kind === 'select')) {
+        if (rendered.length > 1) {
+            fail('A select menu takes a whole row: put it in a row of its own.');
+        }
+    }
+    else if (rendered.some(one => one.kind !== 'button')) {
+        fail('A row only holds buttons, or one select menu.');
+    }
+    else if (rendered.length > Limits.ActionRowButtons) {
+        fail(`A row holds ${Limits.ActionRowButtons} buttons at most, got ${rendered.length}.`);
+    }
+    return piece('row', compose(rendered, raws => ({
+        type: ComponentType.ActionRow,
+        components: raws,
+    })));
+}
+/**
+ * A text in a message built with components. Markdown works as in any
+ * message, mentions included. The texts of a message add up to 4000
+ * characters at most.
+ * @see https://docs.discord.com/developers/components/reference#text-display
+ */
+export function text(content) {
+    return piece('text', {
+        type: ComponentType.TextDisplay,
+        content: checkText('A text', content, Limits.TextDisplayTotal),
+    });
+}
+function mediaOf(input, what) {
+    const options = typeof input === 'string' ? { url: input } : input;
+    if (typeof options !== 'object' || options === null) {
+        fail(`${what} is an address, or an object like { url: '...' }.`);
+    }
+    const url = checkText(`The url of ${what}`, options.url, 2048);
+    const item = { media: { url } };
+    const description = checkText(`The description of ${what}`, options.description, Limits.MediaDescription, { required: false });
+    if (description !== undefined)
+        item.description = description;
+    if (options.spoiler)
+        item.spoiler = true;
+    return item;
+}
+/**
+ * A small picture beside the texts of a section.
+ * @see https://docs.discord.com/developers/components/reference#thumbnail
+ */
+export function thumbnail(media) {
+    const item = mediaOf(media, 'a thumbnail');
+    const raw = {
+        type: ComponentType.Thumbnail,
+        media: item.media,
+    };
+    if (item.description !== undefined)
+        raw.description = item.description;
+    if (item.spoiler)
+        raw.spoiler = true;
+    return piece('thumbnail', raw);
+}
+/**
+ * One to three texts with a button or a thumbnail beside them.
+ * @see https://docs.discord.com/developers/components/reference#section
+ */
+export function section(texts, accessory) {
+    const list = typeof texts === 'string' ? [texts] : texts;
+    if (!Array.isArray(list) ||
+        list.length === 0 ||
+        list.length > Limits.SectionTexts) {
+        fail(`A section has 1 to ${Limits.SectionTexts} texts, got ${Array.isArray(list) ? list.length : typeof list}.`);
+    }
+    const side = renderedOf(accessory, 'The accessory of a section');
+    if (side.kind !== 'button' && side.kind !== 'thumbnail') {
+        fail(`Beside a section goes a button or a thumbnail(), got a ${side.kind}.`);
+    }
+    const displays = list.map((content, index) => ({
+        type: ComponentType.TextDisplay,
+        content: checkText(`Text ${index + 1} of a section`, content, Limits.TextDisplayTotal),
+    }));
+    return piece('section', compose([side], ([accessory]) => ({
+        type: ComponentType.Section,
+        components: displays,
+        accessory: accessory,
+    })));
+}
+/**
+ * Up to 10 pictures or videos, shown in a grid.
+ * @see https://docs.discord.com/developers/components/reference#media-gallery
+ */
+export function gallery(items) {
+    if (!Array.isArray(items) ||
+        items.length === 0 ||
+        items.length > Limits.MediaGalleryItems) {
+        fail(`A gallery has 1 to ${Limits.MediaGalleryItems} items, got ${Array.isArray(items) ? items.length : typeof items}.`);
+    }
+    return piece('gallery', {
+        type: ComponentType.MediaGallery,
+        items: items.map((item, index) => mediaOf(item, `item ${index + 1} of a gallery`)),
+    });
+}
+/**
+ * A file sent with the message (its `files`), shown where it is placed.
+ * @see https://docs.discord.com/developers/components/reference#file
+ */
+export function file(name, { spoiler = false } = {}) {
+    const fileName = checkText('The name of a file component', name, 1024).replace(/^attachment:\/\//, '');
+    const raw = {
+        type: ComponentType.File,
+        file: { url: `attachment://${fileName}` },
+        ...(spoiler ? { spoiler: true } : {}),
+    };
+    return piece('file', raw);
+}
+/**
+ * Space between two pieces, with a line by default.
+ * @see https://docs.discord.com/developers/components/reference#separator
+ */
+export function separator({ divider = true, spacing = 'small', } = {}) {
+    if (spacing !== 'small' && spacing !== 'large') {
+        fail(`The spacing of a separator is 'small' or 'large', got ${JSON.stringify(spacing)}.`);
+    }
+    return piece('separator', {
+        type: ComponentType.Separator,
+        ...(divider ? {} : { divider: false }),
+        ...(spacing === 'large' ? { spacing: 2 } : {}),
+    });
+}
+/**
+ * A box around texts, sections, rows, galleries, files and separators,
+ * with an optional color on its left, like an embed.
+ * @see https://docs.discord.com/developers/components/reference#container
+ */
+export function container(children, { color, spoiler = false } = {}) {
+    if (!Array.isArray(children) || children.length === 0) {
+        fail('container() takes a list of components to put in the box.');
+    }
+    if (color !== undefined &&
+        (!Number.isInteger(color) || color < 0 || color > 0xffffff)) {
+        fail(`The color of a container is a number between 0 and 0xFFFFFF, got ${String(color)}.`);
+    }
+    const components = autoRows(children.map((child, index) => renderedOf(child, `Component ${index + 1} of a container`)), 'a container');
+    for (const child of components) {
+        if (child.kind === 'container' || child.kind === 'thumbnail') {
+            fail(`A container can't hold a ${child.kind}: it holds texts, sections, rows, galleries, files and separators.`);
+        }
+    }
+    return piece('container', compose(components, raws => ({
+        type: ComponentType.Container,
+        components: raws,
+        ...(color !== undefined ? { accent_color: color } : {}),
+        ...(spoiler ? { spoiler: true } : {}),
+    })));
+}
+/**
+ * Puts the buttons and menus of a list in rows: buttons that follow each
+ * other share a row of 5 at most, a menu gets its own. Rows and layout
+ * pieces are kept as they are.
+ */
+export function autoRows(pieces, where) {
+    const result = [];
+    let buttons = [];
+    const asRow = (children) => ({
+        kind: 'row',
+        raw: compose(children, raws => ({
+            type: ComponentType.ActionRow,
+            components: raws,
+        })),
+    });
+    const flush = () => {
+        if (buttons.length === 0)
+            return;
+        result.push(asRow(buttons));
+        buttons = [];
+    };
+    for (const one of pieces) {
+        if (one.kind === 'button') {
+            buttons.push(one);
+            if (buttons.length === Limits.ActionRowButtons)
+                flush();
+        }
+        else if (one.kind === 'select') {
+            flush();
+            result.push(asRow([one]));
+        }
+        else if (one.kind === 'thumbnail') {
+            fail(`A thumbnail only goes beside a section: section(['...'], thumbnail(...)). It can't be in ${where} on its own.`);
+        }
+        else if (one.kind === 'modal') {
+            fail(`A form is not part of ${where}: open it with interaction.showModal().`);
+        }
+        else {
+            flush();
+            result.push(one);
+        }
+    }
+    flush();
+    return result;
+}

package/dist/components/modal.d.ts

@@ -0,0 +1,244 @@
+import type { ChannelType } from '../discord/types/channel.js';
+import type { Channel } from '../structures/channel.js';
+import type { ModalInteraction } from '../structures/interaction.js';
+import type { Attachment, Message } from '../structures/message.js';
+import type { Role } from '../structures/role.js';
+import type { User } from '../structures/user.js';
+import type { TranslationContext } from '../messages/messages.js';
+import { type ComponentWhere, type DynamicText, type PlaceOf } from './component.js';
+import { type DataShape, type DataInputOf, type DataValuesOf } from './custom-id.js';
+import type { ModalComponent, Rendered } from './instance.js';
+import { type LoadedOption, type OptionValue, type SelectOptions } from './options.js';
+/** What every field of a form has: how it is named for the person. */
+interface FieldBase {
+    /**
+     * The name of the field, above it (45 characters at most): written as
+     * is, or a function of `t` and the data, run when the form opens.
+     */
+    label: DynamicText;
+    /** A help text under the label (100 characters at most): a text, or a function of `t` and the data. */
+    description?: DynamicText;
+}
+/** A text the person types. */
+export interface TextField extends FieldBase {
+    /** The kind of field: a text. */
+    type: 'text';
+    /** One line (`'short'`, the default) or several (`'paragraph'`). */
+    style?: 'short' | 'paragraph';
+    /** The text shown while the field is empty (100 characters at most): a text, or a function of `t` and the data. */
+    placeholder?: DynamicText;
+    /** Whether the person must fill it in. `true` by default. */
+    required?: boolean;
+    /** The shortest text accepted, in characters (0 to 4000). */
+    minLength?: number;
+    /** The longest text accepted, in characters (1 to 4000). */
+    maxLength?: number;
+    /** What the field holds when the form opens (4000 characters at most). */
+    value?: string;
+}
+/** A menu of texts you declare. */
+export interface SelectField<Options extends SelectOptions = SelectOptions> extends FieldBase {
+    /** The kind of field: a menu of texts. */
+    type: 'select';
+    /** The options (25 at most), written like the options of a select menu. */
+    options: Options;
+    /** The text shown when nothing is picked (150 characters at most): a text, or a function of `t` and the data. */
+    placeholder?: DynamicText;
+    /** How many options must be picked at least (0 to 25). 1 by default. */
+    min?: number;
+    /** How many options can be picked at most (1 to 25). 1 by default. */
+    max?: number;
+    /** Whether something must be picked. `true` by default. */
+    required?: boolean;
+}
+/** A menu of users, roles, users and roles, or channels of the server. */
+export interface EntityField extends FieldBase {
+    /** The kind of field: what Discord lists. */
+    type: 'user' | 'role' | 'mentionable' | 'channel';
+    /** The text shown when nothing is picked (150 characters at most): a text, or a function of `t` and the data. */
+    placeholder?: DynamicText;
+    /** How many things must be picked at least (0 to 25). 1 by default. */
+    min?: number;
+    /** How many things can be picked at most (1 to 25). 1 by default. */
+    max?: number;
+    /** Whether something must be picked. `true` by default. */
+    required?: boolean;
+    /** For a menu of channels: the kinds of channels listed. All by default. */
+    channelTypes?: readonly ChannelType[];
+}
+/** Files the person uploads. */
+export interface FilesField extends FieldBase {
+    /** The kind of field: files to upload. */
+    type: 'files';
+    /** How many files must be uploaded at least (0 to 10). 1 by default. */
+    min?: number;
+    /** How many files can be uploaded at most (1 to 10). 1 by default. */
+    max?: number;
+    /** Whether files must be uploaded. `true` by default. */
+    required?: boolean;
+    /** The kinds of files accepted: `'image'`, `'video'`, `'audio'`, or extensions like `'.pdf'` (10 at most). */
+    fileTypes?: readonly string[];
+}
+/** One choice among a few, shown as radio buttons. */
+export interface RadioField<Options extends SelectOptions = SelectOptions> extends FieldBase {
+    /** The kind of field: one choice among 2 to 10. */
+    type: 'radio';
+    /** The choices (2 to 10), written like the options of a select menu. */
+    options: Options;
+    /** Whether a choice must be made. `true` by default. */
+    required?: boolean;
+}
+/** Several choices among a few, shown as checkboxes. */
+export interface CheckboxesField<Options extends SelectOptions = SelectOptions> extends FieldBase {
+    /** The kind of field: several choices among 1 to 10. */
+    type: 'checkboxes';
+    /** The choices (1 to 10), written like the options of a select menu. */
+    options: Options;
+    /** How many must be checked at least (0 to 10). 1 by default. */
+    min?: number;
+    /** How many can be checked at most (1 to 10). All by default. */
+    max?: number;
+    /** Whether something must be checked. `true` by default. */
+    required?: boolean;
+}
+/** One checkbox: yes or no. */
+export interface CheckboxField extends FieldBase {
+    /** The kind of field: one checkbox. */
+    type: 'checkbox';
+    /** Whether it is checked when the form opens. */
+    default?: boolean;
+}
+/** A text shown in the form, which nobody fills in. */
+export interface NoteField {
+    /** The kind of field: a text to read. */
+    type: 'note';
+    /** The text, with Markdown: written as is, or a function of `t` and the data. */
+    content: DynamicText;
+}
+/** One field of a form. */
+export type ModalField = TextField | SelectField | EntityField | FilesField | RadioField | CheckboxesField | CheckboxField | NoteField;
+/** The fields of a form, by name (5 at most). */
+export type ModalFields = Readonly<Record<string, ModalField>>;
+/** What `run` receives for one picked thing of a menu of the server. */
+interface EntityValues {
+    user: User;
+    role: Role;
+    mentionable: User | Role;
+    channel: Channel;
+}
+/** What `run` receives for a field, from its declaration. */
+export type FieldValue<Field extends ModalField> = Field extends TextField ? Field extends {
+    required: false;
+} ? string | undefined : string : Field extends SelectField<infer Options> ? OptionValue<Options>[] : Field extends EntityField ? EntityValues[Field['type']][] : Field extends FilesField ? Attachment[] : Field extends RadioField<infer Options> ? Field extends {
+    required: false;
+} ? OptionValue<Options> | undefined : OptionValue<Options> : Field extends CheckboxesField<infer Options> ? OptionValue<Options>[] : Field extends CheckboxField ? boolean : never;
+/** What the person filled in, typed field by field. Notes are not there. */
+export type FieldValuesOf<Fields extends ModalFields> = {
+    [Name in keyof Fields as Fields[Name] extends NoteField ? never : Name]: FieldValue<Fields[Name]>;
+};
+/** What a form can hold when it opens: a value for some of its fields. */
+export type ModalPrefill<Fields extends ModalFields> = {
+    readonly [Name in keyof Fields as Fields[Name] extends TextField | SelectField | RadioField | CheckboxesField | CheckboxField ? Name : never]?: Fields[Name] extends TextField ? string : Fields[Name] extends SelectField<infer Options> | CheckboxesField<infer Options> ? readonly OptionValue<Options>[] : Fields[Name] extends RadioField<infer Options> ? OptionValue<Options> : boolean;
+};
+/** What `run` receives when the form is sent. */
+export type ModalContext<Fields extends ModalFields = ModalFields, Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> = {
+    /** Who sent the form. */
+    user: User;
+    /** What the person filled in. */
+    fields: FieldValuesOf<Fields>;
+    /** What the form carries, as declared in `data`. */
+    data: DataValuesOf<Data>;
+    /** The message whose button or menu opened the form; `null` when a command did. */
+    message: Message | null;
+} & TranslationContext & PlaceOf<Where, ModalInteraction>;
+/** What a modal file gives to `modal()`. */
+export interface ModalConfig<Fields extends ModalFields = ModalFields, Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> {
+    /**
+     * The title of the form (45 characters at most): written as is, or a
+     * function of `t` and the data, run when the form opens.
+     */
+    title: DynamicText;
+    /** The fields, by name (1 to 5). `run` receives them under the same names. */
+    fields: Fields;
+    /**
+     * What the form carries from the code that opens it to the code that
+     * runs when it is sent: a name and a kind for each value. Given when the
+     * form is opened, received typed in `run`.
+     */
+    data?: Data;
+    /**
+     * Where the form can be sent from: `'guild'` (servers, the default),
+     * `'dm'` (private messages with the bot) or `'both'`. What `run`
+     * receives follows it.
+     */
+    where?: Where;
+    /**
+     * Make the answers of the form only visible to who sent it. When a
+     * component of a message only the person sees opened it, they already are.
+     */
+    ephemeral?: boolean;
+    /** What to do when someone sends the form. */
+    run: (context: ModalContext<Fields, Data, Where>) => unknown;
+}
+/** What a form is opened with: its data, and what some fields hold. */
+export interface ModalInstanceOptions<Fields extends ModalFields = ModalFields> {
+    /** What some fields hold when the form opens. */
+    values?: ModalPrefill<Fields>;
+}
+/**
+ * What `modal()` returns: the default export of a modal file. Import it
+ * where someone uses a command or a component, and open it:
+ * `interaction.showModal(report({ userId }))`, or
+ * `interaction.showModal(feedback)` for a form without data.
+ */
+export type ModalFile<Fields extends ModalFields = ModalFields, Data extends DataShape = {}> = {
+    /** What the file gave to `modal()`, not checked yet. */
+    readonly config: unknown;
+} & ({} extends Data ? ((options?: ModalInstanceOptions<Fields>) => ModalComponent) & ModalComponent : {} extends DataInputOf<Data> ? ((data?: DataInputOf<Data>, options?: ModalInstanceOptions<Fields>) => ModalComponent) & ModalComponent : (data: DataInputOf<Data>, options?: ModalInstanceOptions<Fields>) => ModalComponent);
+/**
+ * Declares a form. Export the result as the default export of a file of
+ * `src/components/modals/`: the path of the file is what tells the form
+ * apart, so you never write an id.
+ *
+ * ```ts
+ * import { modal } from 'chapterjs';
+ *
+ * export default modal({
+ *   title: 'Feedback',
+ *   fields: {
+ *     text: { type: 'text', label: 'What do you think?', style: 'paragraph' },
+ *   },
+ *   async run({ interaction, fields }) {
+ *     await interaction.reply({ content: `Thanks! You wrote: ${fields.text}`, ephemeral: true });
+ *   },
+ * });
+ * ```
+ */
+export declare function modal<const Fields extends ModalFields, const Data extends DataShape = {}, const Where extends ComponentWhere = 'guild'>(config: ModalConfig<Fields, Data, Where>): ModalFile<Fields, Data>;
+/** A field of a form, checked, with how it is sent. */
+export interface LoadedField {
+    readonly name: string;
+    readonly field: ModalField;
+    /** The options of a menu, radio or checkboxes, their texts maybe computed when sent. */
+    readonly options: readonly LoadedOption[];
+    readonly required: boolean;
+    readonly min: number;
+    readonly max: number;
+}
+/** A modal file, checked. */
+export interface LoadedModal {
+    readonly kind: 'modal';
+    readonly path: string;
+    /** The title (45 characters at most): a text, or computed when the form opens. */
+    readonly title: DynamicText;
+    readonly fields: readonly LoadedField[];
+    readonly data: DataShape;
+    readonly where: ComponentWhere;
+    readonly ephemeral: boolean;
+    readonly run: (context: ModalContext<ModalFields, DataShape, ComponentWhere>) => unknown;
+}
+/** Checks one field of a form. */
+export declare function readField(name: string, given: unknown): LoadedField;
+/** The form as Discord takes it, for the data and the values given. */
+export declare function renderModal(loaded: LoadedModal, args: readonly unknown[]): Rendered<'modal'>;
+export {};