@marinoscar/platform-web 0.0.0-stage → 0.1.0-next.4

package/dist/credentials/index.js

@@ -0,0 +1,9 @@
+// The credentials slice's entry point for SIBLING SLICES of this package
+// (PP-14.5, #923): the boundary lint lets one slice import another only
+// through the other's `index.ts`, and only when packages/platform-slices.json
+// lists the dependency (email, settings -> credentials). Not a package
+// subpath: apps import `@marinoscar/platform-web/credentials/headless` and
+// `/credentials/ui`. Narrow on purpose: only what a sibling uses.
+export { SecretField } from './ui/secret-field.js';
+export { savedSecretHelperText, secretForSubmit } from './headless/index.js';
+//# sourceMappingURL=index.js.map

package/dist/credentials/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/credentials/index.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,wEAAwE;AACxE,8EAA8E;AAC9E,uEAAuE;AACvE,2EAA2E;AAC3E,kEAAkE;AAElE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/credentials/ui/index.d.ts

@@ -0,0 +1,3 @@
+export { SecretField } from './secret-field.js';
+export type { SecretFieldProps, SecretFieldSlots } from './secret-field.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/credentials/ui/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/credentials/ui/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/credentials/ui/index.js

@@ -0,0 +1,4 @@
+// `@marinoscar/platform-web/credentials/ui`: the write-only secret field
+// (issue #735). Documented in ../README.md.
+export { SecretField } from './secret-field.js';
+//# sourceMappingURL=index.js.map

package/dist/credentials/ui/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/credentials/ui/index.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,4CAA4C;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/credentials/ui/secret-field.d.ts

@@ -0,0 +1,71 @@
+import type { SxProps, TextFieldProps, Theme } from '@mui/material';
+import type { ReactElement } from 'react';
+import type { SavedSecretHelperTextOptions, SavedSecretInfo } from '../headless/index.js';
+/**
+ * The props of {@link SecretField}.
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export interface SecretFieldProps {
+    /** The field's label. */
+    label: string;
+    /** The typed replacement; `''` keeps the stored secret. */
+    value: string;
+    /** Receives the new value on every keystroke. */
+    onChange: (value: string) => void;
+    /** The stored secret's presentation fields, or `null`/absent when nothing is stored. */
+    saved?: SavedSecretInfo | null;
+    /** The helper text when nothing is stored. */
+    emptyHelp?: string;
+    /** What the secret is called in the helper text; default `'key'`. */
+    noun?: string;
+    /** Formats the last-change date; default `toLocaleDateString()`. */
+    formatDate?: SavedSecretHelperTextOptions['formatDate'];
+    /** Disables the input (a viewer without the write permission). */
+    disabled?: boolean;
+    /** An error message, shown instead of the helper text. */
+    error?: string | null;
+    /** The input's `name`. */
+    name?: string;
+    /** The element id; generated when absent. */
+    id?: string;
+    /** Styles for the field's root. */
+    sx?: SxProps<Theme>;
+    /**
+     * Overrides for the underlying parts. `textField` props are spread last,
+     * except `type`, `value` and `onChange`, which stay the field's own.
+     */
+    slots?: SecretFieldSlots;
+}
+/**
+ * The part overrides of {@link SecretField}.
+ *
+ * @stability experimental
+ */
+export interface SecretFieldSlots {
+    /** Props for the MUI `TextField`, except `type`, `value` and `onChange`. */
+    textField?: Partial<Omit<TextFieldProps, 'type' | 'value' | 'onChange'>>;
+}
+/**
+ * A write-only secret input with the unified "saved secret" helper text.
+ *
+ * @param props - see {@link SecretFieldProps}.
+ * @returns the field.
+ *
+ * @example
+ * ```tsx
+ * <SecretField
+ *   label="Signing secret"
+ *   value={secret}
+ *   onChange={setSecret}
+ *   saved={info ? { hint: info.hint, updatedAt: info.updatedAt } : null}
+ *   emptyHelp="No signing secret is saved yet."
+ * />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function SecretField(props: SecretFieldProps): ReactElement;
+//# sourceMappingURL=secret-field.d.ts.map

package/dist/credentials/ui/secret-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-field.d.ts","sourceRoot":"","sources":["../../../src/credentials/ui/secret-field.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAEpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAG1C,OAAO,KAAK,EAAE,4BAA4B,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE1F;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,wFAAwF;IACxF,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/B,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,UAAU,CAAC,EAAE,4BAA4B,CAAC,YAAY,CAAC,CAAC;IACxD,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,0BAA0B;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACpB;;;OAGG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC;CAC1E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,YAAY,CA4BjE"}

package/dist/credentials/ui/secret-field.js

@@ -0,0 +1,47 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// =============================================================================
+// SecretField: a write-only secret input (issue #735, PP-8.8)
+// =============================================================================
+//
+// An MUI `TextField` with `type="password"` that says whether a secret is
+// stored (its non-secret hint and last change) and that leaving it blank keeps
+// it. There is NO reveal toggle: the stored secret is never sent to the
+// browser, and what the user is typing is a replacement, so showing it serves
+// nobody. The helper text is linked to the input through `aria-describedby`
+// (MUI does this when the field has an id and helper text).
+// =============================================================================
+import { TextField } from '@mui/material';
+import { useId } from 'react';
+import { savedSecretHelperText } from '../headless/index.js';
+/**
+ * A write-only secret input with the unified "saved secret" helper text.
+ *
+ * @param props - see {@link SecretFieldProps}.
+ * @returns the field.
+ *
+ * @example
+ * ```tsx
+ * <SecretField
+ *   label="Signing secret"
+ *   value={secret}
+ *   onChange={setSecret}
+ *   saved={info ? { hint: info.hint, updatedAt: info.updatedAt } : null}
+ *   emptyHelp="No signing secret is saved yet."
+ * />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export function SecretField(props) {
+    const generatedId = useId();
+    const id = props.id ?? `secret-field-${generatedId.replace(/[^A-Za-z0-9_-]/g, '')}`;
+    const helper = props.error ??
+        savedSecretHelperText(props.saved, {
+            ...(props.noun !== undefined ? { noun: props.noun } : {}),
+            ...(props.emptyHelp !== undefined ? { emptyHelp: props.emptyHelp } : {}),
+            ...(props.formatDate !== undefined ? { formatDate: props.formatDate } : {}),
+        });
+    return (_jsx(TextField, { id: id, name: props.name, label: props.label, disabled: props.disabled, error: Boolean(props.error), helperText: helper, autoComplete: "new-password", fullWidth: true, sx: props.sx, ...props.slots?.textField, type: "password", value: props.value, onChange: (event) => props.onChange(event.target.value) }));
+}
+//# sourceMappingURL=secret-field.js.map

package/dist/credentials/ui/secret-field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-field.js","sourceRoot":"","sources":["../../../src/credentials/ui/secret-field.tsx"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,8DAA8D;AAC9D,gFAAgF;AAChF,EAAE;AACF,0EAA0E;AAC1E,+EAA+E;AAC/E,wEAAwE;AACxE,8EAA8E;AAC9E,4EAA4E;AAC5E,4DAA4D;AAC5D,gFAAgF;AAEhF,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAG9B,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAmD7D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,MAAM,WAAW,GAAG,KAAK,EAAE,CAAC;IAC5B,MAAM,EAAE,GAAG,KAAK,CAAC,EAAE,IAAI,gBAAgB,WAAW,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,EAAE,CAAC;IACpF,MAAM,MAAM,GACV,KAAK,CAAC,KAAK;QACX,qBAAqB,CAAC,KAAK,CAAC,KAAK,EAAE;YACjC,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzD,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxE,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5E,CAAC,CAAC;IAEL,OAAO,CACL,KAAC,SAAS,IACR,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,KAAK,CAAC,IAAI,EAChB,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ,EACxB,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,EAC3B,UAAU,EAAE,MAAM,EAClB,YAAY,EAAC,cAAc,EAC3B,SAAS,QACT,EAAE,EAAE,KAAK,CAAC,EAAE,KACR,KAAK,CAAC,KAAK,EAAE,SAAS,EAC1B,IAAI,EAAC,UAAU,EACf,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,GACvD,CACH,CAAC;AACJ,CAAC"}

package/dist/datatable/headless/columns.d.ts

@@ -0,0 +1,48 @@
+/**
+ * DataTable — column value helpers.
+ *
+ * The renderer-agnostic half of the column adapter: the scalar behind a cell,
+ * its display text and a row's accessible name. Shared by both renderers and by
+ * the CSV export, so none of them depends on DataGrid.
+ */
+import type { DataTableColumn } from './types.js';
+/**
+ * Extract the scalar behind a cell.
+ *
+ * Order of precedence:
+ *   1. the column's explicit `value` extractor,
+ *   2. `row[column.id]` when the row happens to carry that key,
+ *   3. `null`.
+ *
+ * Non-scalar fallbacks (booleans, Dates, objects) are coerced to something
+ * sortable/exportable rather than leaking a live object into the grid.
+ *
+ * @stability experimental
+ */
+export declare function extractColumnValue<Row>(column: DataTableColumn<Row>, row: Row): string | number | null;
+/**
+ * The scalar rendered as display text (`null`/empty becomes an em dash).
+ *
+ * Shared with the card renderer so an empty cell reads identically in both
+ * layouts — a blank card field and an em-dashed grid cell would look like two
+ * different states of the data.
+ *
+ * @stability experimental
+ */
+export declare function formatColumnValue(value: string | number | null): string;
+/**
+ * The accessible name for ONE row, shared by both renderers wherever a
+ * control needs to disambiguate itself ("Select \{row\}", "Row actions for
+ * \{row\}") — issue #257's accessibility pass.
+ *
+ * Derived from the first `primary` column still on screen (i.e. respecting
+ * the user's #255 visibility choice, when supplied), mirroring exactly what a
+ * user actually reads as "the row" in both the grid and the card headline
+ * (`mobile/DataCard.tsx`'s `headlineText`). Falls back to the row id when
+ * there is no primary column, or its scalar is null/empty — a bare em dash is
+ * not a usable name.
+ *
+ * @stability experimental
+ */
+export declare function rowAccessibleName<Row>(columns: DataTableColumn<Row>[], row: Row, fallbackId: string, visibleColumnIds?: ReadonlySet<string>): string;
+//# sourceMappingURL=columns.d.ts.map

package/dist/datatable/headless/columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"columns.d.ts","sourceRoot":"","sources":["../../../src/datatable/headless/columns.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EACpC,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,EAC5B,GAAG,EAAE,GAAG,GACP,MAAM,GAAG,MAAM,GAAG,IAAI,CAWxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAEvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EACnC,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,EAC/B,GAAG,EAAE,GAAG,EACR,UAAU,EAAE,MAAM,EAClB,gBAAgB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GACrC,MAAM,CAQR"}

package/dist/datatable/headless/columns.js

@@ -0,0 +1,70 @@
+/**
+ * DataTable — column value helpers.
+ *
+ * The renderer-agnostic half of the column adapter: the scalar behind a cell,
+ * its display text and a row's accessible name. Shared by both renderers and by
+ * the CSV export, so none of them depends on DataGrid.
+ */
+/**
+ * Extract the scalar behind a cell.
+ *
+ * Order of precedence:
+ *   1. the column's explicit `value` extractor,
+ *   2. `row[column.id]` when the row happens to carry that key,
+ *   3. `null`.
+ *
+ * Non-scalar fallbacks (booleans, Dates, objects) are coerced to something
+ * sortable/exportable rather than leaking a live object into the grid.
+ *
+ * @stability experimental
+ */
+export function extractColumnValue(column, row) {
+    if (column.value) {
+        return column.value(row);
+    }
+    const record = row;
+    const raw = record == null ? undefined : record[column.id];
+    if (raw === null || raw === undefined)
+        return null;
+    if (typeof raw === 'string' || typeof raw === 'number')
+        return raw;
+    if (typeof raw === 'boolean')
+        return raw ? 'true' : 'false';
+    if (raw instanceof Date)
+        return raw.toISOString();
+    return String(raw);
+}
+/**
+ * The scalar rendered as display text (`null`/empty becomes an em dash).
+ *
+ * Shared with the card renderer so an empty cell reads identically in both
+ * layouts — a blank card field and an em-dashed grid cell would look like two
+ * different states of the data.
+ *
+ * @stability experimental
+ */
+export function formatColumnValue(value) {
+    return value === null || value === '' ? '—' : String(value);
+}
+/**
+ * The accessible name for ONE row, shared by both renderers wherever a
+ * control needs to disambiguate itself ("Select \{row\}", "Row actions for
+ * \{row\}") — issue #257's accessibility pass.
+ *
+ * Derived from the first `primary` column still on screen (i.e. respecting
+ * the user's #255 visibility choice, when supplied), mirroring exactly what a
+ * user actually reads as "the row" in both the grid and the card headline
+ * (`mobile/DataCard.tsx`'s `headlineText`). Falls back to the row id when
+ * there is no primary column, or its scalar is null/empty — a bare em dash is
+ * not a usable name.
+ *
+ * @stability experimental
+ */
+export function rowAccessibleName(columns, row, fallbackId, visibleColumnIds) {
+    const primary = columns.find((column) => column.priority === 'primary' && (!visibleColumnIds || visibleColumnIds.has(column.id)));
+    if (!primary)
+        return fallbackId;
+    const text = formatColumnValue(extractColumnValue(primary, row));
+    return text === '—' || text === '' ? fallbackId : text;
+}
+//# sourceMappingURL=columns.js.map

package/dist/datatable/headless/columns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"columns.js","sourceRoot":"","sources":["../../../src/datatable/headless/columns.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAA4B,EAC5B,GAAQ;IAER,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IACD,MAAM,MAAM,GAAG,GAA4D,CAAC;IAC5E,MAAM,GAAG,GAAG,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC3D,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC;IACnE,IAAI,OAAO,GAAG,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IAC5D,IAAI,GAAG,YAAY,IAAI;QAAE,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC;IAClD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAA6B;IAC7D,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA+B,EAC/B,GAAQ,EACR,UAAkB,EAClB,gBAAsC;IAEtC,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAC1B,CAAC,MAAM,EAAE,EAAE,CACT,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,gBAAgB,IAAI,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAC1F,CAAC;IACF,IAAI,CAAC,OAAO;QAAE,OAAO,UAAU,CAAC;IAChC,MAAM,IAAI,GAAG,iBAAiB,CAAC,kBAAkB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;IACjE,OAAO,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;AACzD,CAAC"}

package/dist/datatable/headless/export/csv.d.ts

@@ -0,0 +1,120 @@
+/**
+ * DataTable — CSV serialization (issue #256, epic #238).
+ *
+ * The PURE half of export: scalars in, a CSV string out. Nothing here knows
+ * about columns, rows, React or the DOM, which is what makes the escaping rules
+ * testable as arithmetic rather than through a rendered table.
+ *
+ * Three rules, and all three exist because a CSV is not just text — it is a
+ * file another program will open:
+ *
+ *  1. **RFC 4180 quoting.** A field containing a comma, a double quote, a CR or
+ *     an LF is wrapped in double quotes with internal quotes doubled. Rows are
+ *     separated by CRLF, which is what the RFC specifies and what Excel expects.
+ *  2. **Formula-injection neutralization.** A cell whose text starts with `=`,
+ *     `+`, `-`, `@` (or a leading tab / CR, which some spreadsheets strip before
+ *     parsing) is executable the moment the file is opened in Excel, Sheets or
+ *     LibreOffice — `=cmd|'/c calc'!A1` is the classic proof. Those fields get a
+ *     leading apostrophe, the one prefix every major spreadsheet treats as
+ *     "this is literal text". See OWASP "CSV Injection".
+ *  3. **A UTF-8 BOM.** Excel on Windows reads a BOM-less UTF-8 CSV as the local
+ *     ANSI code page, so `José` opens as `José`. Three bytes fix it, and every
+ *     other consumer skips them.
+ *
+ * ### Why numbers are exempt from rule 2
+ *
+ * Neutralizing blindly would turn the number `-5` into the text `'-5`, breaking
+ * every numeric column that can go negative — a real regression traded for a
+ * theoretical attack, since `-5` is not a formula. So the prefix is applied only
+ * to text that is not a well-formed number. A genuinely dangerous cell
+ * (`-1+cmd|…`) does not parse as a number and is still neutralized.
+ */
+/**
+ * The UTF-8 byte-order mark, as a JS string.
+ *
+ * Prepended to the *file*, never to a field: `toCsv` deliberately returns
+ * BOM-less text so it can be composed, and {@link toCsvFile} is the thing that
+ * gets written to disk.
+ *
+ * @stability experimental
+ */
+export declare const CSV_BOM = "\uFEFF";
+/**
+ * RFC 4180 row separator. Excel is the reason this is CRLF and not `\n`.
+ *
+ * @stability experimental
+ */
+export declare const CSV_ROW_SEPARATOR = "\r\n";
+/**
+ * RFC 4180 field separator.
+ *
+ * @stability experimental
+ */
+export declare const CSV_FIELD_SEPARATOR = ",";
+/**
+ * The characters that make a leading position dangerous.
+ *
+ * `=`, `+`, `-` and `@` start a formula in Excel / Sheets / LibreOffice. Tab and
+ * CR are here because some spreadsheets strip leading whitespace *before*
+ * deciding whether a cell is a formula, so `\t=1+1` is `=1+1`.
+ *
+ * @stability experimental
+ */
+export declare const CSV_FORMULA_PREFIXES: readonly ["=", "+", "-", "@", "\t", "\r"];
+/**
+ * The prefix that forces a spreadsheet to treat a cell as literal text.
+ *
+ * @stability experimental
+ */
+export declare const CSV_FORMULA_ESCAPE = "'";
+/**
+ * Whether a raw string would be interpreted as a formula by a spreadsheet.
+ *
+ * Exported because "is this dangerous" is a question worth asserting directly,
+ * separately from what the escaper then does about it.
+ *
+ * @stability experimental
+ */
+export declare function isFormulaText(text: string): boolean;
+/**
+ * Prefix a formula-shaped field so it opens as literal text.
+ *
+ * @stability experimental
+ */
+export declare function neutralizeFormula(text: string): string;
+/**
+ * One scalar → one fully escaped CSV field.
+ *
+ * `null` / `undefined` become an EMPTY field, not `—`: the em dash is a display
+ * convention for a human reading a table (`formatColumnValue`), and writing it
+ * into a CSV would turn "no value" into the literal three-byte string a
+ * downstream import would then have to know about.
+ *
+ * Numbers are stringified and never neutralized (see the module note).
+ *
+ * @stability experimental
+ */
+export declare function escapeCsvField(value: string | number | null | undefined): string;
+/**
+ * One record → one CSV line (no trailing separator).
+ *
+ * @stability experimental
+ */
+export declare function toCsvRow(fields: readonly (string | number | null | undefined)[]): string;
+/**
+ * A header row plus body rows → CSV text, WITHOUT the BOM.
+ *
+ * A trailing CRLF is emitted after the final record (RFC 4180 permits it and
+ * POSIX tools expect a final line terminator) whenever there is at least one
+ * row of content.
+ *
+ * @stability experimental
+ */
+export declare function toCsv(header: readonly string[], body: readonly (readonly (string | number | null | undefined)[])[]): string;
+/**
+ * {@link toCsv} plus the UTF-8 BOM — i.e. the exact bytes written to disk.
+ *
+ * @stability experimental
+ */
+export declare function toCsvFile(header: readonly string[], body: readonly (readonly (string | number | null | undefined)[])[]): string;
+//# sourceMappingURL=csv.d.ts.map

package/dist/datatable/headless/export/csv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../../../../src/datatable/headless/export/csv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,WAAW,CAAC;AAEhC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,SAAS,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,2CAA4C,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAQtC;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMnD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAWhF;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG,MAAM,CAExF;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CACnB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,IAAI,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC,EAAE,GACjE,MAAM,CAGR;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,IAAI,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC,EAAE,GACjE,MAAM,CAER"}

package/dist/datatable/headless/export/csv.js

@@ -0,0 +1,151 @@
+/**
+ * DataTable — CSV serialization (issue #256, epic #238).
+ *
+ * The PURE half of export: scalars in, a CSV string out. Nothing here knows
+ * about columns, rows, React or the DOM, which is what makes the escaping rules
+ * testable as arithmetic rather than through a rendered table.
+ *
+ * Three rules, and all three exist because a CSV is not just text — it is a
+ * file another program will open:
+ *
+ *  1. **RFC 4180 quoting.** A field containing a comma, a double quote, a CR or
+ *     an LF is wrapped in double quotes with internal quotes doubled. Rows are
+ *     separated by CRLF, which is what the RFC specifies and what Excel expects.
+ *  2. **Formula-injection neutralization.** A cell whose text starts with `=`,
+ *     `+`, `-`, `@` (or a leading tab / CR, which some spreadsheets strip before
+ *     parsing) is executable the moment the file is opened in Excel, Sheets or
+ *     LibreOffice — `=cmd|'/c calc'!A1` is the classic proof. Those fields get a
+ *     leading apostrophe, the one prefix every major spreadsheet treats as
+ *     "this is literal text". See OWASP "CSV Injection".
+ *  3. **A UTF-8 BOM.** Excel on Windows reads a BOM-less UTF-8 CSV as the local
+ *     ANSI code page, so `José` opens as `José`. Three bytes fix it, and every
+ *     other consumer skips them.
+ *
+ * ### Why numbers are exempt from rule 2
+ *
+ * Neutralizing blindly would turn the number `-5` into the text `'-5`, breaking
+ * every numeric column that can go negative — a real regression traded for a
+ * theoretical attack, since `-5` is not a formula. So the prefix is applied only
+ * to text that is not a well-formed number. A genuinely dangerous cell
+ * (`-1+cmd|…`) does not parse as a number and is still neutralized.
+ */
+/**
+ * The UTF-8 byte-order mark, as a JS string.
+ *
+ * Prepended to the *file*, never to a field: `toCsv` deliberately returns
+ * BOM-less text so it can be composed, and {@link toCsvFile} is the thing that
+ * gets written to disk.
+ *
+ * @stability experimental
+ */
+export const CSV_BOM = '\uFEFF';
+/**
+ * RFC 4180 row separator. Excel is the reason this is CRLF and not `\n`.
+ *
+ * @stability experimental
+ */
+export const CSV_ROW_SEPARATOR = '\r\n';
+/**
+ * RFC 4180 field separator.
+ *
+ * @stability experimental
+ */
+export const CSV_FIELD_SEPARATOR = ',';
+/**
+ * The characters that make a leading position dangerous.
+ *
+ * `=`, `+`, `-` and `@` start a formula in Excel / Sheets / LibreOffice. Tab and
+ * CR are here because some spreadsheets strip leading whitespace *before*
+ * deciding whether a cell is a formula, so `\t=1+1` is `=1+1`.
+ *
+ * @stability experimental
+ */
+export const CSV_FORMULA_PREFIXES = ['=', '+', '-', '@', '\t', '\r'];
+/**
+ * The prefix that forces a spreadsheet to treat a cell as literal text.
+ *
+ * @stability experimental
+ */
+export const CSV_FORMULA_ESCAPE = "'";
+/** Anything a spreadsheet would read as a number, and therefore never a formula. */
+const NUMERIC_TEXT = /^[+-]?(?:\d+(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+/** Characters that force a field to be quoted. */
+const MUST_QUOTE = /["\r\n,]/;
+/**
+ * Whether a raw string would be interpreted as a formula by a spreadsheet.
+ *
+ * Exported because "is this dangerous" is a question worth asserting directly,
+ * separately from what the escaper then does about it.
+ *
+ * @stability experimental
+ */
+export function isFormulaText(text) {
+    if (text.length === 0)
+        return false;
+    if (!CSV_FORMULA_PREFIXES.includes(text.charAt(0)))
+        return false;
+    // `-5` / `+1.5e3` are numbers, not formulas. Neutralizing them would corrupt
+    // every numeric column that can go negative.
+    return !NUMERIC_TEXT.test(text);
+}
+/**
+ * Prefix a formula-shaped field so it opens as literal text.
+ *
+ * @stability experimental
+ */
+export function neutralizeFormula(text) {
+    return isFormulaText(text) ? `${CSV_FORMULA_ESCAPE}${text}` : text;
+}
+/**
+ * One scalar → one fully escaped CSV field.
+ *
+ * `null` / `undefined` become an EMPTY field, not `—`: the em dash is a display
+ * convention for a human reading a table (`formatColumnValue`), and writing it
+ * into a CSV would turn "no value" into the literal three-byte string a
+ * downstream import would then have to know about.
+ *
+ * Numbers are stringified and never neutralized (see the module note).
+ *
+ * @stability experimental
+ */
+export function escapeCsvField(value) {
+    if (value === null || value === undefined)
+        return '';
+    const text = typeof value === 'number' ? String(value) : neutralizeFormula(value);
+    // Leading/trailing whitespace is quoted too: it is semantically meaningful and
+    // several parsers trim unquoted fields.
+    const needsQuotes = MUST_QUOTE.test(text) || text !== text.trim();
+    if (!needsQuotes)
+        return text;
+    return `"${text.replace(/"/g, '""')}"`;
+}
+/**
+ * One record → one CSV line (no trailing separator).
+ *
+ * @stability experimental
+ */
+export function toCsvRow(fields) {
+    return fields.map(escapeCsvField).join(CSV_FIELD_SEPARATOR);
+}
+/**
+ * A header row plus body rows → CSV text, WITHOUT the BOM.
+ *
+ * A trailing CRLF is emitted after the final record (RFC 4180 permits it and
+ * POSIX tools expect a final line terminator) whenever there is at least one
+ * row of content.
+ *
+ * @stability experimental
+ */
+export function toCsv(header, body) {
+    const lines = [toCsvRow(header), ...body.map((row) => toCsvRow(row))];
+    return `${lines.join(CSV_ROW_SEPARATOR)}${CSV_ROW_SEPARATOR}`;
+}
+/**
+ * {@link toCsv} plus the UTF-8 BOM — i.e. the exact bytes written to disk.
+ *
+ * @stability experimental
+ */
+export function toCsvFile(header, body) {
+    return `${CSV_BOM}${toCsv(header, body)}`;
+}
+//# sourceMappingURL=csv.js.map

package/dist/datatable/headless/export/csv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.js","sourceRoot":"","sources":["../../../../src/datatable/headless/export/csv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC;AAEhC;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAExC;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEvC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAU,CAAC;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAEtC,oFAAoF;AACpF,MAAM,YAAY,GAAG,iDAAiD,CAAC;AAEvE,kDAAkD;AAClD,MAAM,UAAU,GAAG,UAAU,CAAC;AAE9B;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,IAAI,CAAE,oBAA0C,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACxF,6EAA6E;IAC7E,6CAA6C;IAC7C,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,kBAAkB,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,KAAyC;IACtE,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAErD,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAElF,+EAA+E;IAC/E,wCAAwC;IACxC,MAAM,WAAW,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;IAClE,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAE9B,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAuD;IAC9E,OAAO,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,KAAK,CACnB,MAAyB,EACzB,IAAkE;IAElE,MAAM,KAAK,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACtE,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,iBAAiB,EAAE,CAAC;AAChE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CACvB,MAAyB,EACzB,IAAkE;IAElE,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;AAC5C,CAAC"}