@ifto/mantine-kit 0.0.0-stage → 0.2.0

package/dist/export/ExportDocument.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Model of the exported data, independent of the file format (see `ExportFormat`). An export is a document with one
+ * or more sheets, and each sheet is a matrix (an array of arrays) of cells, with the title of each column.
+ * It depends on no domain: whoever exports converts their data to this model.
+ * @author Manoel Campos
+ */
+import { KitLocale } from '../i18n/KitLocale';
+import { ExportMessages } from '../i18n/KitMessages';
+/** Format of a numeric value. Percentages are in the 0..1 scale and converted only for display. */
+export type NumberFormat = {
+    /** Decimal places shown. */
+    decimals: number;
+    /** Whether the value is a percentage in the 0..1 scale (e.g. 0.85 is shown as 85%). */
+    percent?: boolean;
+};
+/** Number with its own format, for when the format changes from one row to another (e.g. the unit of each row). */
+export type NumberCell = {
+    value: number;
+    format: NumberFormat;
+};
+/** Cell whose value could not be computed (e.g. a calculation error), unlike an empty (absent) cell. */
+export type InvalidCell = {
+    invalid: true;
+    /** Text shown instead of the value. */
+    text: string;
+};
+/**
+ * Value of a cell:
+ * - `string`: text;
+ * - `number`: number, in the format of the column (`NaN` is treated as an absent value);
+ * - {@link NumberCell}: number with its own format;
+ * - {@link InvalidCell}: invalid result;
+ * - `undefined`: absent value (empty cell), which is different from zero.
+ */
+export type ExportCell = string | number | NumberCell | InvalidCell | undefined;
+/** Column of a sheet. */
+export type ExportColumn = {
+    /** Title (header) of the column. */
+    header: string;
+    /** Format of the numbers of the column, used when the cell has none; absent for {@link DEFAULT_NUMBER_FORMAT}. */
+    format?: NumberFormat;
+};
+/** Sheet of the file: a table with the columns and the rows. */
+export type ExportSheet = {
+    /** Name of the sheet. Each format adapts it to its rules (e.g. the maximum length in Excel). */
+    name: string;
+    columns: ExportColumn[];
+    /**
+     * One array per row, with one cell per column, in the order of {@link columns}. A shorter row is completed with
+     * empty cells; a row with more cells than columns is an error, since the extra data would be lost.
+     */
+    rows: ExportCell[][];
+};
+/** Information about the context of the data, shown at the beginning of the file (e.g. the period and the filters). */
+export type ExportInfo = {
+    label: string;
+    value: string;
+};
+/** Visual identity of the system that generated the file, shown in the header and in the footer. */
+export type ExportBranding = {
+    /** Name of the system, shown in the footer (e.g. "Data generated by My System"). */
+    systemName: string;
+    /** Address of the system, shown as a link in the footer. */
+    siteUrl: string;
+    /** Logo shown in the header; absent to show no logo (e.g. if it could not be loaded). */
+    logo?: ExportImage;
+};
+/** PNG image embedded in the file. */
+export type ExportImage = {
+    /** Content of the image, as a base64 data URL (`data:image/png;base64,...`). */
+    pngDataUrl: string;
+    /** Original width and height (px), to keep the aspect ratio when resizing. */
+    width: number;
+    height: number;
+};
+/** Document to export: the data and its context. */
+export type ExportDocument = {
+    /** Title shown at the top of the file. */
+    title: string;
+    /** Name of the file, without the date and the extension, which are added on export. */
+    fileName: string;
+    info: ExportInfo[];
+    /** Date and time the data was generated. */
+    generatedAt: Date;
+    branding: ExportBranding;
+    sheets: ExportSheet[];
+    /** Locale of the texts and of the number format of the file. Default: `en-US`. */
+    locale?: KitLocale;
+    /** Texts that replace the ones of the locale (e.g. the ones the app overrides in the `KitProvider`). */
+    messages?: Partial<ExportMessages>;
+};
+/** Format of the numbers of a column that defines none. */
+export declare const DEFAULT_NUMBER_FORMAT: NumberFormat;
+/** Types of cell, after being normalized by {@link classifyCell}. */
+export type ClassifiedCell = {
+    kind: 'empty';
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'number';
+    value: number;
+    format: NumberFormat;
+} | {
+    kind: 'invalid';
+    text: string;
+};
+/**
+ * Creates a cell with an invalid result.
+ * @param text text shown instead of the value; defaults to the text of the default locale
+ * @return the invalid cell
+ */
+export declare function invalidCell(text?: string): InvalidCell;
+/**
+ * Tells whether the cell is an invalid result.
+ * @param cell cell to check
+ */
+export declare function isInvalidCell(cell: ExportCell): cell is InvalidCell;
+/**
+ * Classifies a cell, so that every format handles each type of value the same way. A `NaN` number is treated as
+ * absent (empty cell), and `Infinity` as invalid (e.g. a division by zero).
+ * @param cell cell to classify
+ * @param columnFormat format of the column of the cell, used when the cell is a number without its own format
+ * @param invalidText text of an infinite number; defaults to the text of the default locale
+ * @return the type and the value of the cell
+ */
+export declare function classifyCell(cell: ExportCell, columnFormat?: NumberFormat, invalidText?: string): ClassifiedCell;

package/dist/export/ExportDocument.js

@@ -0,0 +1,59 @@
+"use client";
+import { DEFAULT_MESSAGES } from "../i18n/resolveMessages.js";
+// src/export/ExportDocument.ts
+/** Format of the numbers of a column that defines none. */
+var DEFAULT_NUMBER_FORMAT = { decimals: 2 };
+/**
+* Creates a cell with an invalid result.
+* @param text text shown instead of the value; defaults to the text of the default locale
+* @return the invalid cell
+*/
+function invalidCell(text = DEFAULT_MESSAGES.export.invalidCell) {
+	return {
+		invalid: true,
+		text
+	};
+}
+/**
+* Tells whether the cell is an invalid result.
+* @param cell cell to check
+*/
+function isInvalidCell(cell) {
+	return typeof cell === "object" && "invalid" in cell;
+}
+/**
+* Classifies a cell, so that every format handles each type of value the same way. A `NaN` number is treated as
+* absent (empty cell), and `Infinity` as invalid (e.g. a division by zero).
+* @param cell cell to classify
+* @param columnFormat format of the column of the cell, used when the cell is a number without its own format
+* @param invalidText text of an infinite number; defaults to the text of the default locale
+* @return the type and the value of the cell
+*/
+function classifyCell(cell, columnFormat = DEFAULT_NUMBER_FORMAT, invalidText = DEFAULT_MESSAGES.export.invalidCell) {
+	if (cell === void 0) return { kind: "empty" };
+	if (typeof cell === "string") return {
+		kind: "text",
+		text: cell
+	};
+	if (isInvalidCell(cell)) return {
+		kind: "invalid",
+		text: cell.text
+	};
+	const { value, format } = typeof cell === "number" ? {
+		value: cell,
+		format: columnFormat
+	} : cell;
+	if (Number.isNaN(value)) return { kind: "empty" };
+	if (!Number.isFinite(value)) return {
+		kind: "invalid",
+		text: invalidText
+	};
+	return {
+		kind: "number",
+		value,
+		format
+	};
+}
+export { DEFAULT_NUMBER_FORMAT, classifyCell, invalidCell, isInvalidCell };
+
+//# sourceMappingURL=ExportDocument.js.map

package/dist/export/ExportDocument.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExportDocument.js","names":[],"sources":["../../src/export/ExportDocument.ts"],"sourcesContent":["/**\n * Model of the exported data, independent of the file format (see `ExportFormat`). An export is a document with one\n * or more sheets, and each sheet is a matrix (an array of arrays) of cells, with the title of each column.\n * It depends on no domain: whoever exports converts their data to this model.\n * @author Manoel Campos\n */\n\nimport { KitLocale } from '../i18n/KitLocale';\nimport { ExportMessages } from '../i18n/KitMessages';\nimport { DEFAULT_MESSAGES } from '../i18n/resolveMessages';\n\n/** Format of a numeric value. Percentages are in the 0..1 scale and converted only for display. */\nexport type NumberFormat = {\n    /** Decimal places shown. */\n    decimals: number;\n\n    /** Whether the value is a percentage in the 0..1 scale (e.g. 0.85 is shown as 85%). */\n    percent?: boolean;\n};\n\n/** Number with its own format, for when the format changes from one row to another (e.g. the unit of each row). */\nexport type NumberCell = {\n    value: number;\n    format: NumberFormat;\n};\n\n/** Cell whose value could not be computed (e.g. a calculation error), unlike an empty (absent) cell. */\nexport type InvalidCell = {\n    invalid: true;\n\n    /** Text shown instead of the value. */\n    text: string;\n};\n\n/**\n * Value of a cell:\n * - `string`: text;\n * - `number`: number, in the format of the column (`NaN` is treated as an absent value);\n * - {@link NumberCell}: number with its own format;\n * - {@link InvalidCell}: invalid result;\n * - `undefined`: absent value (empty cell), which is different from zero.\n */\nexport type ExportCell = string | number | NumberCell | InvalidCell | undefined;\n\n/** Column of a sheet. */\nexport type ExportColumn = {\n    /** Title (header) of the column. */\n    header: string;\n\n    /** Format of the numbers of the column, used when the cell has none; absent for {@link DEFAULT_NUMBER_FORMAT}. */\n    format?: NumberFormat;\n};\n\n/** Sheet of the file: a table with the columns and the rows. */\nexport type ExportSheet = {\n    /** Name of the sheet. Each format adapts it to its rules (e.g. the maximum length in Excel). */\n    name: string;\n    columns: ExportColumn[];\n\n    /**\n     * One array per row, with one cell per column, in the order of {@link columns}. A shorter row is completed with\n     * empty cells; a row with more cells than columns is an error, since the extra data would be lost.\n     */\n    rows: ExportCell[][];\n};\n\n/** Information about the context of the data, shown at the beginning of the file (e.g. the period and the filters). */\nexport type ExportInfo = {\n    label: string;\n    value: string;\n};\n\n/** Visual identity of the system that generated the file, shown in the header and in the footer. */\nexport type ExportBranding = {\n    /** Name of the system, shown in the footer (e.g. \"Data generated by My System\"). */\n    systemName: string;\n\n    /** Address of the system, shown as a link in the footer. */\n    siteUrl: string;\n\n    /** Logo shown in the header; absent to show no logo (e.g. if it could not be loaded). */\n    logo?: ExportImage;\n};\n\n/** PNG image embedded in the file. */\nexport type ExportImage = {\n    /** Content of the image, as a base64 data URL (`data:image/png;base64,...`). */\n    pngDataUrl: string;\n\n    /** Original width and height (px), to keep the aspect ratio when resizing. */\n    width: number;\n    height: number;\n};\n\n/** Document to export: the data and its context. */\nexport type ExportDocument = {\n    /** Title shown at the top of the file. */\n    title: string;\n\n    /** Name of the file, without the date and the extension, which are added on export. */\n    fileName: string;\n    info: ExportInfo[];\n\n    /** Date and time the data was generated. */\n    generatedAt: Date;\n    branding: ExportBranding;\n    sheets: ExportSheet[];\n\n    /** Locale of the texts and of the number format of the file. Default: `en-US`. */\n    locale?: KitLocale;\n\n    /** Texts that replace the ones of the locale (e.g. the ones the app overrides in the `KitProvider`). */\n    messages?: Partial<ExportMessages>;\n};\n\n/** Format of the numbers of a column that defines none. */\nexport const DEFAULT_NUMBER_FORMAT: NumberFormat = { decimals: 2 };\n\n/** Types of cell, after being normalized by {@link classifyCell}. */\nexport type ClassifiedCell =\n    | { kind: 'empty' }\n    | { kind: 'text'; text: string }\n    | { kind: 'number'; value: number; format: NumberFormat }\n    | { kind: 'invalid'; text: string };\n\n/**\n * Creates a cell with an invalid result.\n * @param text text shown instead of the value; defaults to the text of the default locale\n * @return the invalid cell\n */\nexport function invalidCell(text: string = DEFAULT_MESSAGES.export.invalidCell): InvalidCell {\n    return { invalid: true, text };\n}\n\n/**\n * Tells whether the cell is an invalid result.\n * @param cell cell to check\n */\nexport function isInvalidCell(cell: ExportCell): cell is InvalidCell {\n    return typeof cell === 'object' && 'invalid' in cell;\n}\n\n/**\n * Classifies a cell, so that every format handles each type of value the same way. A `NaN` number is treated as\n * absent (empty cell), and `Infinity` as invalid (e.g. a division by zero).\n * @param cell cell to classify\n * @param columnFormat format of the column of the cell, used when the cell is a number without its own format\n * @param invalidText text of an infinite number; defaults to the text of the default locale\n * @return the type and the value of the cell\n */\nexport function classifyCell(\n    cell: ExportCell,\n    columnFormat: NumberFormat = DEFAULT_NUMBER_FORMAT,\n    invalidText: string = DEFAULT_MESSAGES.export.invalidCell\n): ClassifiedCell {\n    if (cell === undefined) return { kind: 'empty' };\n    if (typeof cell === 'string') return { kind: 'text', text: cell };\n    if (isInvalidCell(cell)) return { kind: 'invalid', text: cell.text };\n\n    const { value, format } = typeof cell === 'number' ? { value: cell, format: columnFormat } : cell;\n    if (Number.isNaN(value)) return { kind: 'empty' };\n    if (!Number.isFinite(value)) return { kind: 'invalid', text: invalidText };\n\n    return { kind: 'number', value, format };\n}\n"],"mappings":";;;;AAoHA,IAAa,wBAAsC,EAAE,UAAU,EAAE;;;;;;AAcjE,SAAgB,YAAY,OAAe,iBAAiB,OAAO,aAA0B;CACzF,OAAO;EAAE,SAAS;EAAM;CAAK;AACjC;;;;;AAMA,SAAgB,cAAc,MAAuC;CACjE,OAAO,OAAO,SAAS,YAAY,aAAa;AACpD;;;;;;;;;AAUA,SAAgB,aACZ,MACA,eAA6B,uBAC7B,cAAsB,iBAAiB,OAAO,aAChC;CACd,IAAI,SAAS,KAAA,GAAW,OAAO,EAAE,MAAM,QAAQ;CAC/C,IAAI,OAAO,SAAS,UAAU,OAAO;EAAE,MAAM;EAAQ,MAAM;CAAK;CAChE,IAAI,cAAc,IAAI,GAAG,OAAO;EAAE,MAAM;EAAW,MAAM,KAAK;CAAK;CAEnE,MAAM,EAAE,OAAO,WAAW,OAAO,SAAS,WAAW;EAAE,OAAO;EAAM,QAAQ;CAAa,IAAI;CAC7F,IAAI,OAAO,MAAM,KAAK,GAAG,OAAO,EAAE,MAAM,QAAQ;CAChD,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG,OAAO;EAAE,MAAM;EAAW,MAAM;CAAY;CAEzE,OAAO;EAAE,MAAM;EAAU;EAAO;CAAO;AAC3C"}

package/dist/export/ExportDownload.d.ts

@@ -0,0 +1,9 @@
+import { ExportDocument } from './ExportDocument';
+import { ExportFormat } from './ExportFormat';
+/**
+ * Generates the file of a document in the chosen format and makes the browser download it, named after the document,
+ * with the generation date and the extension of the format.
+ * @param document data to export
+ * @param format format of the file
+ */
+export declare function downloadExport(document: ExportDocument, format: ExportFormat): Promise<void>;

package/dist/export/ExportDownload.js

@@ -0,0 +1,19 @@
+"use client";
+import { exportFileName } from "./ExportFileName.js";
+import { exportMessages } from "./ExportTexts.js";
+import { downloadBlob } from "../util/DownloadUtil.js";
+// src/export/ExportDownload.ts
+/**
+* Generates the file of a document in the chosen format and makes the browser download it, named after the document,
+* with the generation date and the extension of the format.
+* @param document data to export
+* @param format format of the file
+*/
+async function downloadExport(document, format) {
+	const blob = await format.generate(document);
+	const defaultName = exportMessages(document).defaultFileName;
+	downloadBlob(blob, exportFileName(document.fileName, document.generatedAt, format.extension, defaultName));
+}
+export { downloadExport };
+
+//# sourceMappingURL=ExportDownload.js.map

package/dist/export/ExportDownload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExportDownload.js","names":[],"sources":["../../src/export/ExportDownload.ts"],"sourcesContent":["import { ExportDocument } from './ExportDocument';\nimport { exportFileName } from './ExportFileName';\nimport { ExportFormat } from './ExportFormat';\nimport { exportMessages } from './ExportTexts';\nimport { downloadBlob } from '../util/DownloadUtil';\n\n/**\n * Generates the file of a document in the chosen format and makes the browser download it, named after the document,\n * with the generation date and the extension of the format.\n * @param document data to export\n * @param format format of the file\n */\nexport async function downloadExport(document: ExportDocument, format: ExportFormat): Promise<void> {\n    const blob = await format.generate(document);\n    const defaultName = exportMessages(document).defaultFileName;\n    downloadBlob(blob, exportFileName(document.fileName, document.generatedAt, format.extension, defaultName));\n}\n"],"mappings":";;;;;;;;;;;AAYA,eAAsB,eAAe,UAA0B,QAAqC;CAChG,MAAM,OAAO,MAAM,OAAO,SAAS,QAAQ;CAC3C,MAAM,cAAc,eAAe,QAAQ,CAAC,CAAC;CAC7C,aAAa,MAAM,eAAe,SAAS,UAAU,SAAS,aAAa,OAAO,WAAW,WAAW,CAAC;AAC7G"}

package/dist/export/ExportFileName.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Builds the name of the exported file: the base name without accents or invalid characters, the generation date and
+ * the extension (e.g. "sales-north-2026-10-20.xlsx"). Without accents, the name works in any system and e-mail
+ * attachment.
+ * @param baseName desired name, without date or extension
+ * @param generatedAt date the data was generated
+ * @param extension extension of the format, without the dot
+ * @param defaultName name used when the base name has no valid character; defaults to the one of the default locale
+ * @return the name of the file
+ */
+export declare function exportFileName(baseName: string, generatedAt: Date, extension: string, defaultName?: string): string;

package/dist/export/ExportFileName.js

@@ -0,0 +1,24 @@
+"use client";
+import { DEFAULT_MESSAGES } from "../i18n/resolveMessages.js";
+import { formatDateToISO } from "../util/DateUtil.js";
+// src/export/ExportFileName.ts
+/** Characters not accepted in file names by some operating system, plus the spaces. */
+var INVALID_FILE_NAME_CHARS = /[\s/\\:*?"<>|]+/g;
+/** Accent marks, separated from the letters by the NFD normalization. */
+var DIACRITICS = /\p{Diacritic}/gu;
+/**
+* Builds the name of the exported file: the base name without accents or invalid characters, the generation date and
+* the extension (e.g. "sales-north-2026-10-20.xlsx"). Without accents, the name works in any system and e-mail
+* attachment.
+* @param baseName desired name, without date or extension
+* @param generatedAt date the data was generated
+* @param extension extension of the format, without the dot
+* @param defaultName name used when the base name has no valid character; defaults to the one of the default locale
+* @return the name of the file
+*/
+function exportFileName(baseName, generatedAt, extension, defaultName = DEFAULT_MESSAGES.export.defaultFileName) {
+	return `${baseName.normalize("NFD").replace(DIACRITICS, "").replace(INVALID_FILE_NAME_CHARS, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase() || defaultName}-${formatDateToISO(generatedAt)}.${extension}`;
+}
+export { exportFileName };
+
+//# sourceMappingURL=ExportFileName.js.map

package/dist/export/ExportFileName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExportFileName.js","names":[],"sources":["../../src/export/ExportFileName.ts"],"sourcesContent":["import { DEFAULT_MESSAGES } from '../i18n/resolveMessages';\nimport { formatDateToISO } from '../util/DateUtil';\n\n/** Characters not accepted in file names by some operating system, plus the spaces. */\nconst INVALID_FILE_NAME_CHARS = /[\\s/\\\\:*?\"<>|]+/g;\n\n/** Accent marks, separated from the letters by the NFD normalization. */\nconst DIACRITICS = /\\p{Diacritic}/gu;\n\n/**\n * Builds the name of the exported file: the base name without accents or invalid characters, the generation date and\n * the extension (e.g. \"sales-north-2026-10-20.xlsx\"). Without accents, the name works in any system and e-mail\n * attachment.\n * @param baseName desired name, without date or extension\n * @param generatedAt date the data was generated\n * @param extension extension of the format, without the dot\n * @param defaultName name used when the base name has no valid character; defaults to the one of the default locale\n * @return the name of the file\n */\nexport function exportFileName(\n    baseName: string,\n    generatedAt: Date,\n    extension: string,\n    defaultName: string = DEFAULT_MESSAGES.export.defaultFileName\n): string {\n    const name = baseName\n        .normalize('NFD')\n        .replace(DIACRITICS, '')\n        .replace(INVALID_FILE_NAME_CHARS, '-')\n        .replace(/-+/g, '-')\n        .replace(/^-|-$/g, '')\n        .toLowerCase();\n\n    return `${name || defaultName}-${formatDateToISO(generatedAt)}.${extension}`;\n}\n"],"mappings":";;;;;AAIA,IAAM,0BAA0B;;AAGhC,IAAM,aAAa;;;;;;;;;;;AAYnB,SAAgB,eACZ,UACA,aACA,WACA,cAAsB,iBAAiB,OAAO,iBACxC;CASN,OAAO,GARM,SACR,UAAU,KAAK,CAAC,CAChB,QAAQ,YAAY,EAAE,CAAC,CACvB,QAAQ,yBAAyB,GAAG,CAAC,CACrC,QAAQ,OAAO,GAAG,CAAC,CACnB,QAAQ,UAAU,EAAE,CAAC,CACrB,YAEK,KAAQ,YAAY,GAAG,gBAAgB,WAAW,EAAE,GAAG;AACrE"}

package/dist/export/ExportFormat.d.ts

@@ -0,0 +1,30 @@
+import { ExportDocument } from './ExportDocument';
+/**
+ * Contract every export format must follow (Strategy pattern). Each format generates the file from the same
+ * {@link ExportDocument}, so whoever exports chooses the format without knowing the details of each one. To add a
+ * format, create the implementation and register it in `ExportFormats.ts`.
+ * @author Manoel Campos
+ */
+export interface ExportFormat {
+    /** Unique id of the format (e.g. `xlsx`), used as the key of the format in menus. */
+    readonly id: string;
+    /** Name of the format shown to the user (e.g. "Excel (.xlsx)"), the same in every language. */
+    readonly label: string;
+    /** Extension of the file, without the dot. */
+    readonly extension: string;
+    /** MIME type of the file. */
+    readonly mimeType: string;
+    /**
+     * Whether the format stores many sheets in a single file. A format without sheets (e.g. CSV) accepts only
+     * documents with one sheet, so whoever exports must build the document according to this value.
+     */
+    readonly multipleSheets: boolean;
+    /**
+     * Generates the file.
+     * @param document data to export
+     * @return the content of the file
+     * @throws Error if the document cannot be exported in the format: without any sheet, with many sheets in a
+     *         format without sheets, or with a row with more cells than columns
+     */
+    generate(document: ExportDocument): Promise<Blob>;
+}

package/dist/export/ExportFormat.js

@@ -0,0 +1 @@
+"use client";

package/dist/export/ExportFormats.d.ts

@@ -0,0 +1,12 @@
+import { CsvFormat } from './csv/CsvFormat';
+import { ExportFormat } from './ExportFormat';
+import { XlsxFormat } from './xlsx/XlsxFormat';
+/**
+ * Single instances of the export formats. The formats have no state, so they can be shared by all screens.
+ * @author Manoel Campos
+ */
+/** Excel format (`.xlsx`), with a sheet in the file for each sheet of the document. */
+export declare const XLSX_FORMAT: XlsxFormat;
+export declare const CSV_FORMAT: CsvFormat;
+/** All built-in export formats, in the order they appear in an export menu. */
+export declare const EXPORT_FORMATS: readonly ExportFormat[];

package/dist/export/ExportFormats.js

@@ -0,0 +1,16 @@
+"use client";
+import { CsvFormat } from "./csv/CsvFormat.js";
+import { XlsxFormat } from "./xlsx/XlsxFormat.js";
+// src/export/ExportFormats.ts
+/**
+* Single instances of the export formats. The formats have no state, so they can be shared by all screens.
+* @author Manoel Campos
+*/
+/** Excel format (`.xlsx`), with a sheet in the file for each sheet of the document. */
+var XLSX_FORMAT = new XlsxFormat();
+var CSV_FORMAT = new CsvFormat();
+/** All built-in export formats, in the order they appear in an export menu. */
+var EXPORT_FORMATS = [XLSX_FORMAT, CSV_FORMAT];
+export { CSV_FORMAT, EXPORT_FORMATS, XLSX_FORMAT };
+
+//# sourceMappingURL=ExportFormats.js.map

package/dist/export/ExportFormats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExportFormats.js","names":[],"sources":["../../src/export/ExportFormats.ts"],"sourcesContent":["import { CsvFormat } from './csv/CsvFormat';\nimport { ExportFormat } from './ExportFormat';\nimport { XlsxFormat } from './xlsx/XlsxFormat';\n\n/**\n * Single instances of the export formats. The formats have no state, so they can be shared by all screens.\n * @author Manoel Campos\n */\n\n/** Excel format (`.xlsx`), with a sheet in the file for each sheet of the document. */\nexport const XLSX_FORMAT = new XlsxFormat();\nexport const CSV_FORMAT = new CsvFormat();\n\n/** All built-in export formats, in the order they appear in an export menu. */\nexport const EXPORT_FORMATS: readonly ExportFormat[] = [XLSX_FORMAT, CSV_FORMAT];\n"],"mappings":";;;;;;;;;AAUA,IAAa,cAAc,IAAI,WAAW;AAC1C,IAAa,aAAa,IAAI,UAAU;;AAGxC,IAAa,iBAA0C,CAAC,aAAa,UAAU"}

package/dist/export/ExportTexts.d.ts

@@ -0,0 +1,14 @@
+import { ExportMessages } from '../i18n/KitMessages';
+import { ExportDocument } from './ExportDocument';
+/**
+ * Returns the texts of an exported document: the ones of its locale, with the ones the document overrides.
+ * @param document exported document
+ * @return the texts shown in the file
+ */
+export declare function exportMessages(document: Pick<ExportDocument, 'locale' | 'messages'>): ExportMessages;
+/**
+ * Returns the locale of an exported document.
+ * @param document exported document
+ * @return the locale of the document, or the default one
+ */
+export declare function exportLocale(document: Pick<ExportDocument, 'locale'>): string;

package/dist/export/ExportTexts.js

@@ -0,0 +1,23 @@
+"use client";
+import "../i18n/KitLocale.js";
+import { resolveMessages } from "../i18n/resolveMessages.js";
+// src/export/ExportTexts.ts
+/**
+* Returns the texts of an exported document: the ones of its locale, with the ones the document overrides.
+* @param document exported document
+* @return the texts shown in the file
+*/
+function exportMessages(document) {
+	return resolveMessages(document.locale, { export: document.messages }).export;
+}
+/**
+* Returns the locale of an exported document.
+* @param document exported document
+* @return the locale of the document, or the default one
+*/
+function exportLocale(document) {
+	return document.locale ?? "en-US";
+}
+export { exportLocale, exportMessages };
+
+//# sourceMappingURL=ExportTexts.js.map

package/dist/export/ExportTexts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExportTexts.js","names":[],"sources":["../../src/export/ExportTexts.ts"],"sourcesContent":["import { DEFAULT_LOCALE } from '../i18n/KitLocale';\nimport { ExportMessages } from '../i18n/KitMessages';\nimport { resolveMessages } from '../i18n/resolveMessages';\nimport { ExportDocument } from './ExportDocument';\n\n/**\n * Returns the texts of an exported document: the ones of its locale, with the ones the document overrides.\n * @param document exported document\n * @return the texts shown in the file\n */\nexport function exportMessages(document: Pick<ExportDocument, 'locale' | 'messages'>): ExportMessages {\n    return resolveMessages(document.locale, { export: document.messages }).export;\n}\n\n/**\n * Returns the locale of an exported document.\n * @param document exported document\n * @return the locale of the document, or the default one\n */\nexport function exportLocale(document: Pick<ExportDocument, 'locale'>): string {\n    return document.locale ?? DEFAULT_LOCALE;\n}\n"],"mappings":";;;;;;;;;AAUA,SAAgB,eAAe,UAAuE;CAClG,OAAO,gBAAgB,SAAS,QAAQ,EAAE,QAAQ,SAAS,SAAS,CAAC,CAAC,CAAC;AAC3E;;;;;;AAOA,SAAgB,aAAa,UAAkD;CAC3E,OAAO,SAAS,UAAA;AACpB"}

package/dist/export/csv/CsvFormat.d.ts

@@ -0,0 +1,41 @@
+import { ExportDocument, ExportSheet } from '../ExportDocument';
+import { ExportFormat } from '../ExportFormat';
+/**
+ * Column separator used when the decimal separator of the locale is the comma (e.g. `pt-BR`), which is what Excel
+ * expects in these languages.
+ */
+export declare const CSV_SEPARATOR = ";";
+/** Column separator used when the decimal separator of the locale is not the comma (e.g. `en-US`). */
+export declare const CSV_COMMA_SEPARATOR = ",";
+/**
+ * Returns the column separator of the CSV for a locale: `;` when the decimal separator is the comma, so numbers do not
+ * clash with the separator, or `,` otherwise.
+ * @param locale locale of the number format
+ */
+export declare function csvSeparator(locale: string): string;
+/**
+ * Exports to CSV, as Excel in the language of the locale expects: the decimal separator of the locale, a column
+ * separator that does not clash with it (see {@link csvSeparator}), no thousands separator and UTF-8 with BOM. The CSV
+ * has only the table (header and rows), without the title or the context, so other programs can also read the
+ * columns. Having no sheets, it accepts only documents with one sheet.
+ *
+ * The CSV is text, so each number has the decimal places of its format (the same as on the screen), rounded. The
+ * `.xlsx` stores the full value and just shows it with these places.
+ * @author Manoel Campos
+ */
+export declare class CsvFormat implements ExportFormat {
+    readonly id = "csv";
+    readonly label = "CSV";
+    readonly extension = "csv";
+    readonly mimeType = "text/csv;charset=utf-8";
+    readonly multipleSheets = false;
+    generate(document: ExportDocument): Promise<Blob>;
+}
+/**
+ * Builds the CSV text of a sheet.
+ * @param sheet columns and rows of the table
+ * @param locale locale of the number format, which also defines the column separator; defaults to `en-US`
+ * @param invalidText text of an infinite number
+ * @return the header and the rows, each one ended by a line break
+ */
+export declare function csvText(sheet: ExportSheet, locale?: string, invalidText?: string): string;

package/dist/export/csv/CsvFormat.js

@@ -0,0 +1,91 @@
+"use client";
+import { cellText } from "../ExportCellText.js";
+import { classifyCell } from "../ExportDocument.js";
+import { DEFAULT_LOCALE } from "../../i18n/KitLocale.js";
+import { exportLocale, exportMessages } from "../ExportTexts.js";
+// src/export/csv/CsvFormat.ts
+/**
+* Column separator used when the decimal separator of the locale is the comma (e.g. `pt-BR`), which is what Excel
+* expects in these languages.
+*/
+var CSV_SEPARATOR = ";";
+/** Column separator used when the decimal separator of the locale is not the comma (e.g. `en-US`). */
+var CSV_COMMA_SEPARATOR = ",";
+/** Line break of the CSV ({@link https://www.rfc-editor.org/rfc/rfc4180 RFC 4180}). */
+var LINE_BREAK = "\r\n";
+/** UTF-8 byte order mark (BOM): without it, Excel opens the file with garbled accents. */
+var UTF8_BOM = "";
+/**
+* Start of a text that Excel would read as a formula (`=`, `+`, `-`, `@`, tab or CR). A name typed by a user as
+* `=HYPERLINK(...)` would become a formula when the file is opened (CSV injection), so the text gets a leading
+* apostrophe.
+*/
+var FORMULA_START = /^[=+\-@\t\r]/;
+/**
+* Returns the column separator of the CSV for a locale: `;` when the decimal separator is the comma, so numbers do not
+* clash with the separator, or `,` otherwise.
+* @param locale locale of the number format
+*/
+function csvSeparator(locale) {
+	return new Intl.NumberFormat(locale).formatToParts(1.1).find((part) => part.type === "decimal")?.value === "," ? ";" : ",";
+}
+/**
+* Exports to CSV, as Excel in the language of the locale expects: the decimal separator of the locale, a column
+* separator that does not clash with it (see {@link csvSeparator}), no thousands separator and UTF-8 with BOM. The CSV
+* has only the table (header and rows), without the title or the context, so other programs can also read the
+* columns. Having no sheets, it accepts only documents with one sheet.
+*
+* The CSV is text, so each number has the decimal places of its format (the same as on the screen), rounded. The
+* `.xlsx` stores the full value and just shows it with these places.
+* @author Manoel Campos
+*/
+var CsvFormat = class {
+	id = "csv";
+	label = "CSV";
+	extension = "csv";
+	mimeType = "text/csv;charset=utf-8";
+	multipleSheets = false;
+	async generate(document) {
+		if (document.sheets.length !== 1) throw new Error(`A CSV file has a single sheet, but the document has ${document.sheets.length}.`);
+		const text = csvText(document.sheets[0], exportLocale(document), exportMessages(document).invalidCell);
+		return new Blob([UTF8_BOM + text], { type: this.mimeType });
+	}
+};
+/**
+* Builds the CSV text of a sheet.
+* @param sheet columns and rows of the table
+* @param locale locale of the number format, which also defines the column separator; defaults to `en-US`
+* @param invalidText text of an infinite number
+* @return the header and the rows, each one ended by a line break
+*/
+function csvText(sheet, locale = DEFAULT_LOCALE, invalidText) {
+	const separator = csvSeparator(locale);
+	const field = (text) => csvField(text, separator);
+	return [sheet.columns.map((column) => field(column.header)), ...sheet.rows.map((row) => sheet.columns.map((column, i) => csvCell(classifyCell(row[i], column.format, invalidText), locale, field)))].map((fields) => fields.join(separator) + LINE_BREAK).join("");
+}
+/**
+* Converts a cell to the CSV field. Numbers have the decimal separator of the locale and no thousands separator, which
+* Excel in that language reads as a number (and a percentage, such as "85,5%", as 0.855). Texts, including the one of
+* an invalid cell, go through the text field function.
+* @param cell cell already classified
+* @param locale locale of the number format
+* @param field function that prepares a text field
+* @return the CSV field
+*/
+function csvCell(cell, locale, field) {
+	const text = cellText(cell, false, locale);
+	return cell.kind === "number" ? text : field(text);
+}
+/**
+* Prepares a text for the CSV: prevents it from becoming a formula and quotes it if needed.
+* @param text text of the field
+* @param separator column separator, which requires quotes when present in the text
+* @return the CSV field
+*/
+function csvField(text, separator) {
+	const safeText = FORMULA_START.test(text) ? `'${text}` : text;
+	return safeText.includes(separator) || /["\r\n]/.test(safeText) ? `"${safeText.replaceAll("\"", "\"\"")}"` : safeText;
+}
+export { CSV_COMMA_SEPARATOR, CSV_SEPARATOR, CsvFormat, csvSeparator, csvText };
+
+//# sourceMappingURL=CsvFormat.js.map

package/dist/export/csv/CsvFormat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CsvFormat.js","names":[],"sources":["../../../src/export/csv/CsvFormat.ts"],"sourcesContent":["import { cellText } from '../ExportCellText';\nimport { ClassifiedCell, classifyCell, ExportDocument, ExportSheet } from '../ExportDocument';\nimport { ExportFormat } from '../ExportFormat';\nimport { DEFAULT_LOCALE } from '../../i18n/KitLocale';\nimport { exportLocale, exportMessages } from '../ExportTexts';\n\n/**\n * Column separator used when the decimal separator of the locale is the comma (e.g. `pt-BR`), which is what Excel\n * expects in these languages.\n */\nexport const CSV_SEPARATOR = ';';\n\n/** Column separator used when the decimal separator of the locale is not the comma (e.g. `en-US`). */\nexport const CSV_COMMA_SEPARATOR = ',';\n\n/** Line break of the CSV ({@link https://www.rfc-editor.org/rfc/rfc4180 RFC 4180}). */\nconst LINE_BREAK = '\\r\\n';\n\n/** UTF-8 byte order mark (BOM): without it, Excel opens the file with garbled accents. */\nconst UTF8_BOM = '';\n\n/**\n * Start of a text that Excel would read as a formula (`=`, `+`, `-`, `@`, tab or CR). A name typed by a user as\n * `=HYPERLINK(...)` would become a formula when the file is opened (CSV injection), so the text gets a leading\n * apostrophe.\n */\nconst FORMULA_START = /^[=+\\-@\\t\\r]/;\n\n/**\n * Returns the column separator of the CSV for a locale: `;` when the decimal separator is the comma, so numbers do not\n * clash with the separator, or `,` otherwise.\n * @param locale locale of the number format\n */\nexport function csvSeparator(locale: string): string {\n    const decimal = new Intl.NumberFormat(locale).formatToParts(1.1).find(part => part.type === 'decimal')?.value;\n\n    return decimal === ',' ? CSV_SEPARATOR : CSV_COMMA_SEPARATOR;\n}\n\n/**\n * Exports to CSV, as Excel in the language of the locale expects: the decimal separator of the locale, a column\n * separator that does not clash with it (see {@link csvSeparator}), no thousands separator and UTF-8 with BOM. The CSV\n * has only the table (header and rows), without the title or the context, so other programs can also read the\n * columns. Having no sheets, it accepts only documents with one sheet.\n *\n * The CSV is text, so each number has the decimal places of its format (the same as on the screen), rounded. The\n * `.xlsx` stores the full value and just shows it with these places.\n * @author Manoel Campos\n */\nexport class CsvFormat implements ExportFormat {\n    readonly id = 'csv';\n    readonly label = 'CSV';\n    readonly extension = 'csv';\n    readonly mimeType = 'text/csv;charset=utf-8';\n    readonly multipleSheets = false;\n\n    async generate(document: ExportDocument): Promise<Blob> {\n        if (document.sheets.length !== 1) {\n            throw new Error(`A CSV file has a single sheet, but the document has ${document.sheets.length}.`);\n        }\n\n        const text = csvText(document.sheets[0], exportLocale(document), exportMessages(document).invalidCell);\n        return new Blob([UTF8_BOM + text], { type: this.mimeType });\n    }\n}\n\n/**\n * Builds the CSV text of a sheet.\n * @param sheet columns and rows of the table\n * @param locale locale of the number format, which also defines the column separator; defaults to `en-US`\n * @param invalidText text of an infinite number\n * @return the header and the rows, each one ended by a line break\n */\nexport function csvText(sheet: ExportSheet, locale: string = DEFAULT_LOCALE, invalidText?: string): string {\n    const separator = csvSeparator(locale);\n    const field = (text: string) => csvField(text, separator);\n    const header = sheet.columns.map(column => field(column.header));\n    const rows = sheet.rows.map(row =>\n        sheet.columns.map((column, i) => csvCell(classifyCell(row[i], column.format, invalidText), locale, field))\n    );\n\n    return [header, ...rows].map(fields => fields.join(separator) + LINE_BREAK).join('');\n}\n\n/**\n * Converts a cell to the CSV field. Numbers have the decimal separator of the locale and no thousands separator, which\n * Excel in that language reads as a number (and a percentage, such as \"85,5%\", as 0.855). Texts, including the one of\n * an invalid cell, go through the text field function.\n * @param cell cell already classified\n * @param locale locale of the number format\n * @param field function that prepares a text field\n * @return the CSV field\n */\nfunction csvCell(cell: ClassifiedCell, locale: string, field: (text: string) => string): string {\n    const text = cellText(cell, false, locale);\n\n    return cell.kind === 'number' ? text : field(text);\n}\n\n/**\n * Prepares a text for the CSV: prevents it from becoming a formula and quotes it if needed.\n * @param text text of the field\n * @param separator column separator, which requires quotes when present in the text\n * @return the CSV field\n */\nfunction csvField(text: string, separator: string): string {\n    const safeText = FORMULA_START.test(text) ? `'${text}` : text;\n    const needsQuotes = safeText.includes(separator) || /[\"\\r\\n]/.test(safeText);\n\n    return needsQuotes ? `\"${safeText.replaceAll('\"', '\"\"')}\"` : safeText;\n}\n"],"mappings":";;;;;;;;;;AAUA,IAAa,gBAAgB;;AAG7B,IAAa,sBAAsB;;AAGnC,IAAM,aAAa;;AAGnB,IAAM,WAAW;;;;;;AAOjB,IAAM,gBAAgB;;;;;;AAOtB,SAAgB,aAAa,QAAwB;CAGjD,OAFgB,IAAI,KAAK,aAAa,MAAM,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,MAAK,SAAQ,KAAK,SAAS,SAAS,CAAC,EAAE,UAErF,MAAA,MAAA;AACvB;;;;;;;;;;;AAYA,IAAa,YAAb,MAA+C;CAC3C,KAAc;CACd,QAAiB;CACjB,YAAqB;CACrB,WAAoB;CACpB,iBAA0B;CAE1B,MAAM,SAAS,UAAyC;EACpD,IAAI,SAAS,OAAO,WAAW,GAC3B,MAAM,IAAI,MAAM,uDAAuD,SAAS,OAAO,OAAO,EAAE;EAGpG,MAAM,OAAO,QAAQ,SAAS,OAAO,IAAI,aAAa,QAAQ,GAAG,eAAe,QAAQ,CAAC,CAAC,WAAW;EACrG,OAAO,IAAI,KAAK,CAAC,WAAW,IAAI,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;CAC9D;AACJ;;;;;;;;AASA,SAAgB,QAAQ,OAAoB,SAAiB,gBAAgB,aAA8B;CACvG,MAAM,YAAY,aAAa,MAAM;CACrC,MAAM,SAAS,SAAiB,SAAS,MAAM,SAAS;CAMxD,OAAO,CALQ,MAAM,QAAQ,KAAI,WAAU,MAAM,OAAO,MAAM,CAKtD,GAAQ,GAJH,MAAM,KAAK,KAAI,QACxB,MAAM,QAAQ,KAAK,QAAQ,MAAM,QAAQ,aAAa,IAAI,IAAI,OAAO,QAAQ,WAAW,GAAG,QAAQ,KAAK,CAAC,CAG1F,CAAI,CAAC,CAAC,KAAI,WAAU,OAAO,KAAK,SAAS,IAAI,UAAU,CAAC,CAAC,KAAK,EAAE;AACvF;;;;;;;;;;AAWA,SAAS,QAAQ,MAAsB,QAAgB,OAAyC;CAC5F,MAAM,OAAO,SAAS,MAAM,OAAO,MAAM;CAEzC,OAAO,KAAK,SAAS,WAAW,OAAO,MAAM,IAAI;AACrD;;;;;;;AAQA,SAAS,SAAS,MAAc,WAA2B;CACvD,MAAM,WAAW,cAAc,KAAK,IAAI,IAAI,IAAI,SAAS;CAGzD,OAFoB,SAAS,SAAS,SAAS,KAAK,UAAU,KAAK,QAAQ,IAEtD,IAAI,SAAS,WAAW,MAAK,MAAI,EAAE,KAAK;AACjE"}

package/dist/export/xlsx/XlsxFormat.d.ts

@@ -0,0 +1,35 @@
+import type { Workbook } from 'exceljs';
+import { ExportDocument } from '../ExportDocument';
+import { ExportFormat } from '../ExportFormat';
+import { XlsxColors } from './XlsxStyle';
+/** Options of an {@link XlsxFormat}. */
+export type XlsxFormatOptions = {
+    /** Colors of the file (e.g. the brand colors of the app); the ones not given use the defaults. */
+    colors?: Partial<XlsxColors>;
+};
+/**
+ * Exports to Excel (`.xlsx`) with [ExcelJS](https://github.com/exceljs/exceljs): a sheet in the file for each sheet
+ * of the document, with styles, the logo and the numbers in a numeric format (not text).
+ *
+ * ExcelJS is loaded on demand (dynamic `import()`), like ECharts: imported statically, it would be in the bundle of
+ * every page that can export, even if the user exports nothing.
+ * @author Manoel Campos
+ */
+export declare class XlsxFormat implements ExportFormat {
+    readonly id = "xlsx";
+    readonly label = "Excel (.xlsx)";
+    readonly extension = "xlsx";
+    readonly mimeType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+    readonly multipleSheets = true;
+    private readonly styles;
+    /** @param options options of the format, such as the colors of the file */
+    constructor(options?: XlsxFormatOptions);
+    generate(document: ExportDocument): Promise<Blob>;
+    /**
+     * Builds the workbook with a sheet for each sheet of the document.
+     * @param document data to export
+     * @return the workbook ready to be written
+     * @throws Error if the document has no sheets
+     */
+    buildWorkbook(document: ExportDocument): Promise<Workbook>;
+}