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

package/dist/datatable/headless/layout/layoutModel.js

@@ -0,0 +1,459 @@
+/**
+ * DataTable — layout persistence model (issue #255, epic #238).
+ *
+ * The PURE half of per-user layout persistence: the stored shape, the encoding
+ * that survives a round trip through `user_settings.dataTables`, and the
+ * resolution rules that turn a stored blob plus the CURRENT column list into
+ * "which columns does this table draw right now".
+ *
+ * Nothing here touches React or the network — `useDataTableLayoutPrefs`
+ * (state + writes) and `DataTableViewBar` (the controls) build on top of it.
+ *
+ * ## The two rules that make this safe
+ *
+ * 1. **Absent means "use the contract default", never "empty".** An absent
+ *    `dataTables` entry, or an absent field inside one, resolves to the
+ *    priority-derived baseline. The API deliberately never materialises these
+ *    keys; neither do we.
+ *
+ * 2. **A stored list is resolved against the CURRENT columns at render time.**
+ *    A stored id for a column that no longer exists is ignored, not an error;
+ *    a column that did not exist when the layout was stored resolves to its
+ *    default rather than being silently hidden.
+ *
+ * Rule 2 is the reason for the encoding below.
+ */
+// ---------------------------------------------------------------------------
+// Constants (mirroring the bounds of the API's `dataTables` user-settings schema)
+// ---------------------------------------------------------------------------
+/**
+ * Max entries the API accepts in a `visibleColumns` list.
+ *
+ * @stability experimental
+ */
+export const DATA_TABLE_MAX_VISIBLE_COLUMNS = 60;
+/**
+ * Max length of any string inside `visibleColumns`.
+ *
+ * @stability experimental
+ */
+export const DATA_TABLE_MAX_ID_LENGTH = 64;
+/**
+ * Debounce window before an in-session layout change is written to the server.
+ *
+ * @stability experimental
+ */
+export const DATA_TABLE_PERSIST_DEBOUNCE_MS = 500;
+/**
+ * Density used when neither the user nor the page has chosen one.
+ *
+ * @stability experimental
+ */
+export const DEFAULT_DENSITY = 'standard';
+/**
+ * Largest JSON size, in bytes, of a stored `extra` (mirrors the API bound
+ * `DATA_TABLE_EXTRA_MAX_BYTES`).
+ *
+ * @stability experimental
+ */
+export const DATA_TABLE_EXTRA_MAX_BYTES = 8192;
+/**
+ * Most top-level keys of a stored `extra` (mirrors `DATA_TABLE_EXTRA_MAX_KEYS`).
+ *
+ * @stability experimental
+ */
+export const DATA_TABLE_EXTRA_MAX_KEYS = 32;
+/**
+ * Deepest a stored `extra` may nest (mirrors `DATA_TABLE_EXTRA_MAX_DEPTH`).
+ *
+ * @stability experimental
+ */
+export const DATA_TABLE_EXTRA_MAX_DEPTH = 8;
+/**
+ * Most saved views per table (mirrors `DATA_TABLE_MAX_SAVED_VIEWS`).
+ *
+ * @stability experimental
+ */
+export const DATA_TABLE_MAX_SAVED_VIEWS = 20;
+/**
+ * Longest saved-view name (mirrors `DATA_TABLE_VIEW_NAME_MAX_LENGTH`).
+ *
+ * @stability experimental
+ */
+export const DATA_TABLE_VIEW_NAME_MAX_LENGTH = 60;
+/**
+ * Largest JSON size of one table's whole stored entry (mirrors
+ * `DATA_TABLE_ENTRY_MAX_BYTES`).
+ *
+ * @stability experimental
+ */
+export const DATA_TABLE_ENTRY_MAX_BYTES = 32768;
+/**
+ * Marker prefix for a column the user EXPLICITLY hid.
+ *
+ * `visibleColumns` is a `string[]` in the API contract, which can express "these
+ * ids are visible" but not "…and these other ids existed and were deliberately
+ * hidden". Without that second bit, a column added to a table AFTER a user
+ * stored a layout is indistinguishable from one they unchecked, and would be
+ * silently hidden from that user forever — the exact failure mode this design
+ * exists to prevent, just relocated from the server to the client.
+ *
+ * So the list carries every column known at write time: visible ones as bare
+ * ids, hidden ones prefixed with `-`. A current column mentioned by NEITHER is
+ * new, and falls back to its priority-derived default.
+ *
+ * This degrades correctly for any naive consumer that reads the field as a
+ * plain list of visible ids: `-lastError` matches no column id, so it is
+ * ignored and the remaining bare ids are exactly the visible set.
+ *
+ * @stability experimental
+ */
+export const HIDDEN_COLUMN_PREFIX = '-';
+const DENSITIES = ['compact', 'standard', 'comfortable'];
+/**
+ * Whether a value is one of the three densities.
+ *
+ * @stability experimental
+ */
+export function isDensity(value) {
+    return typeof value === 'string' && DENSITIES.includes(value);
+}
+const VIEW_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
+/**
+ * The JSON size of a value in bytes, or `Infinity` when it is not JSON.
+ *
+ * @param value - the value.
+ * @returns its UTF-8 JSON length.
+ *
+ * @stability experimental
+ */
+export function jsonByteLength(value) {
+    try {
+        const encoded = JSON.stringify(value);
+        return encoded === undefined ? Infinity : new TextEncoder().encode(encoded).length;
+    }
+    catch {
+        return Infinity;
+    }
+}
+function isSafeJson(value, depth = 0) {
+    if (depth > DATA_TABLE_EXTRA_MAX_DEPTH)
+        return false;
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every((item) => isSafeJson(item, depth + 1));
+    if (typeof value === 'object') {
+        return Object.keys(value).every((key) => key !== '__proto__' && key !== 'constructor' && key !== 'prototype' && isSafeJson(value[key], depth + 1));
+    }
+    return false;
+}
+/**
+ * Whether `value` is an acceptable stored `extra`: a plain object of bounded
+ * JSON (see {@link DataTableStoredLayout.extra}). The stored copy is
+ * untrusted, and the API enforces the same bounds on write.
+ *
+ * @param value - what was read or is about to be stored.
+ * @returns `true` when it fits.
+ *
+ * @stability experimental
+ */
+export function isValidStoredExtra(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    if (keys.length > DATA_TABLE_EXTRA_MAX_KEYS)
+        return false;
+    if (keys.some((key) => key.length === 0 || key.length > DATA_TABLE_MAX_ID_LENGTH))
+        return false;
+    return isSafeJson(value) && jsonByteLength(value) <= DATA_TABLE_EXTRA_MAX_BYTES;
+}
+function sanitizeViewLayout(raw) {
+    const { savedViews: _ignored, ...layout } = sanitizeStoredLayout(raw);
+    void _ignored;
+    return layout;
+}
+function sanitizeSavedViews(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const views = [];
+    const seen = new Set();
+    for (const entry of raw) {
+        if (views.length >= DATA_TABLE_MAX_SAVED_VIEWS)
+            break;
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const view = entry;
+        const name = typeof view.name === 'string' ? view.name.trim() : '';
+        if (typeof view.id !== 'string' ||
+            view.id.length === 0 ||
+            view.id.length > DATA_TABLE_MAX_ID_LENGTH ||
+            !VIEW_ID_PATTERN.test(view.id) ||
+            seen.has(view.id) ||
+            name === '' ||
+            name.length > DATA_TABLE_VIEW_NAME_MAX_LENGTH) {
+            continue;
+        }
+        seen.add(view.id);
+        views.push({ id: view.id, name, layout: sanitizeViewLayout(view.layout) });
+    }
+    return views;
+}
+/**
+ * Defensively narrow a server payload to the fields the contract allows.
+ *
+ * The stored blob is user-writable JSON: another client, an older build, or a
+ * hand-edited settings row can put anything in it. Dropping what we do not
+ * understand keeps a malformed entry from crashing a render — and keeps us from
+ * echoing an unknown key back on the next PATCH, which the API would reject
+ * with a 400 and take the whole write down with it.
+ *
+ * @stability experimental
+ */
+export function sanitizeStoredLayout(raw) {
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const record = raw;
+    const out = {};
+    if (Array.isArray(record.visibleColumns)) {
+        const ids = record.visibleColumns
+            .filter((id) => typeof id === 'string' && id.length > 0)
+            .slice(0, DATA_TABLE_MAX_VISIBLE_COLUMNS);
+        out.visibleColumns = ids;
+    }
+    if (isDensity(record.density))
+        out.density = record.density;
+    const sort = record.sort;
+    if (sort &&
+        typeof sort === 'object' &&
+        typeof sort.field === 'string' &&
+        sort.field.length > 0 &&
+        (sort.direction === 'asc' || sort.direction === 'desc')) {
+        out.sort = { field: sort.field, direction: sort.direction };
+    }
+    if (typeof record.pageSize === 'number' && Number.isInteger(record.pageSize)) {
+        out.pageSize = record.pageSize;
+    }
+    if (isValidStoredExtra(record.extra))
+        out.extra = record.extra;
+    const views = sanitizeSavedViews(record.savedViews);
+    if (views && views.length > 0)
+        out.savedViews = views;
+    // A hand-edited row can be over the entry bound; drop the app-owned parts
+    // (which could be what is large) rather than echo it back into a PATCH the
+    // API would refuse.
+    if (jsonByteLength(out) > DATA_TABLE_ENTRY_MAX_BYTES) {
+        delete out.savedViews;
+        delete out.extra;
+    }
+    return out;
+}
+/**
+ * `true` when an entry carries nothing — i.e. "reset to contract defaults".
+ *
+ * @stability experimental
+ */
+export function isEmptyStoredLayout(entry) {
+    return (entry.visibleColumns === undefined &&
+        entry.density === undefined &&
+        entry.sort === undefined &&
+        entry.pageSize === undefined &&
+        entry.extra === undefined &&
+        (entry.savedViews === undefined || entry.savedViews.length === 0));
+}
+// ---------------------------------------------------------------------------
+// Column helpers
+// ---------------------------------------------------------------------------
+/**
+ * `hideable` defaults to `true`; `false` pins a column permanently visible.
+ *
+ * @stability experimental
+ */
+export function isHideable(column) {
+    return column.hideable !== false;
+}
+/**
+ * Whether the LAYOUT itself folds a column away, independent of user choice.
+ *
+ * Only the tablet grid does: `detail` columns are hidden there and reached via
+ * the row expander. This is a presentation decision, so it composes with —
+ * rather than being overridden by — the user's stored choice.
+ *
+ * @stability experimental
+ */
+export function layoutHidesColumn(column, layout) {
+    return layout === 'tablet' && column.priority === 'detail';
+}
+/**
+ * The columns the visibility picker offers for the current layout.
+ *
+ * Two exclusions, for the same reason: a control that cannot change anything is
+ * worse than no control. `hideable: false` columns are pinned; `detail` columns
+ * on a tablet are already folded into the row expander, so a checkbox for them
+ * would claim an effect it does not have.
+ *
+ * @stability experimental
+ */
+export function pickerColumns(columns, layout) {
+    return columns.filter((column) => isHideable(column) && !layoutHidesColumn(column, layout));
+}
+/**
+ * Split a stored `visibleColumns` list into its explicit visible/hidden sets.
+ *
+ * @stability experimental
+ */
+export function decodeVisibility(stored) {
+    const visible = new Set();
+    const hidden = new Set();
+    for (const entry of stored) {
+        if (entry.startsWith(HIDDEN_COLUMN_PREFIX)) {
+            const id = entry.slice(HIDDEN_COLUMN_PREFIX.length);
+            if (id)
+                hidden.add(id);
+        }
+        else if (entry) {
+            visible.add(entry);
+        }
+    }
+    return { visible, hidden };
+}
+/**
+ * Encode a user's visibility choice against the columns known right now.
+ *
+ * Visible columns are written as bare ids, hidden ones with the `-` marker, in
+ * declaration order. Two bounds are respected so the write can never be
+ * rejected by the API: at most {@link DATA_TABLE_MAX_VISIBLE_COLUMNS} entries
+ * (visible ids first, since losing a hidden marker only costs the new-column
+ * protection while losing a visible id would hide a column), and no entry
+ * longer than {@link DATA_TABLE_MAX_ID_LENGTH}.
+ *
+ * @stability experimental
+ */
+export function encodeVisibility(columns, visibleIds) {
+    const visible = [];
+    const hidden = [];
+    for (const column of columns) {
+        if (column.id.length > DATA_TABLE_MAX_ID_LENGTH)
+            continue;
+        if (visibleIds.has(column.id)) {
+            visible.push(column.id);
+        }
+        else if (column.id.length + HIDDEN_COLUMN_PREFIX.length <= DATA_TABLE_MAX_ID_LENGTH) {
+            hidden.push(`${HIDDEN_COLUMN_PREFIX}${column.id}`);
+        }
+    }
+    return [...visible, ...hidden].slice(0, DATA_TABLE_MAX_VISIBLE_COLUMNS);
+}
+/**
+ * The user's stored visibility choice, resolved against the CURRENT columns.
+ *
+ * Layout-independent: this answers "which columns has the user chosen to see",
+ * not "which columns does this layout draw". Compose it with
+ * {@link layoutHidesColumn} via {@link resolveVisibleColumnIds}.
+ *
+ * | stored state for a column   | result                                  |
+ * | --------------------------- | --------------------------------------- |
+ * | no `visibleColumns` at all  | default — visible                       |
+ * | listed bare                 | visible                                 |
+ * | listed with the `-` marker  | hidden                                  |
+ * | not listed (added later)    | default — visible                       |
+ * | `hideable: false`           | visible, whatever the list says         |
+ *
+ * A stored id matching no current column simply never matches, so a renamed or
+ * deleted column is ignored rather than throwing.
+ *
+ * @stability experimental
+ */
+export function resolveUserVisibleColumnIds(columns, stored) {
+    const decoded = stored?.visibleColumns ? decodeVisibility(stored.visibleColumns) : null;
+    const out = new Set();
+    for (const column of columns) {
+        if (!isHideable(column)) {
+            out.add(column.id);
+            continue;
+        }
+        // No stored choice, or a column the stored choice never knew about: the
+        // contract default wins, and the contract default is "the user can see it".
+        if (!decoded || !decoded.hidden.has(column.id))
+            out.add(column.id);
+    }
+    return out;
+}
+/**
+ * The columns this table actually draws: the layout baseline AND the user's
+ * choice.
+ *
+ * Intersection, not override, because the two answer different questions. The
+ * tablet grid folds `detail` columns into the row expander so nothing is lost
+ * at 800px; a user's "show me `lastError`" cannot un-fold that without
+ * reintroducing the horizontal scroll the fold exists to remove. Conversely a
+ * user hiding a column must win at every width.
+ *
+ * @stability experimental
+ */
+export function resolveVisibleColumnIds(columns, stored, layout) {
+    const chosen = resolveUserVisibleColumnIds(columns, stored);
+    const out = new Set();
+    for (const column of columns) {
+        if (layoutHidesColumn(column, layout))
+            continue;
+        if (chosen.has(column.id))
+            out.add(column.id);
+    }
+    return out;
+}
+/**
+ * A stored sort, resolved against the current columns.
+ *
+ * Returns `null` when the stored field names a column that no longer exists or
+ * is no longer `sortable` — restoring a sort the server would reject (or the
+ * header cannot show) is worse than opening in the page's own default order.
+ *
+ * @stability experimental
+ */
+export function resolveStoredSort(columns, stored) {
+    const sort = stored?.sort;
+    if (!sort)
+        return null;
+    const column = columns.find((candidate) => candidate.id === sort.field);
+    if (!column || !column.sortable)
+        return null;
+    return sort;
+}
+/**
+ * Spacing metrics of the phone card list, per density.
+ *
+ * @stability experimental
+ */
+export const CARD_DENSITY = {
+    compact: { px: 1, py: 0.75, fieldGap: 0.75, cardGap: 0.75 },
+    standard: { px: 1.5, py: 1.25, fieldGap: 1.25, cardGap: 1.5 },
+    comfortable: { px: 2, py: 1.75, fieldGap: 1.75, cardGap: 2.25 },
+};
+/**
+ * Card metrics for a density, falling back to `standard`.
+ *
+ * @stability experimental
+ */
+export function cardDensityMetrics(density) {
+    return CARD_DENSITY[density ?? DEFAULT_DENSITY] ?? CARD_DENSITY[DEFAULT_DENSITY];
+}
+/**
+ * Human label for a density, used by the picker and its accessible names.
+ *
+ * @stability experimental
+ */
+export const DENSITY_LABELS = {
+    compact: 'Compact',
+    standard: 'Standard',
+    comfortable: 'Comfortable',
+};
+/**
+ * The three densities, in the order the toggle presents them.
+ *
+ * @stability experimental
+ */
+export const DENSITY_OPTIONS = DENSITIES;
+//# sourceMappingURL=layoutModel.js.map

package/dist/datatable/headless/layout/layoutModel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layoutModel.js","sourceRoot":"","sources":["../../../../src/datatable/headless/layout/layoutModel.ts"],"names":[],"mappings":"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"}

package/dist/datatable/headless/layout/preferences.d.ts

@@ -0,0 +1,76 @@
+import type { ReactElement, ReactNode } from 'react';
+import type { PlatformApiClient } from '../../../core/index.js';
+import type { DataTableStoredLayout } from './layoutModel.js';
+/**
+ * Where a table's layout preferences (visible columns, density, sort, page
+ * size) are kept between visits.
+ *
+ * The default is the user-settings API, reached through the host's transport
+ * ({@link createUserSettingsPreferencesPort}); an app that keeps them somewhere
+ * else (browser storage, a different endpoint) supplies its own through
+ * {@link DataTablePreferencesProvider}. Both methods may reject: the table
+ * treats persistence as a best-effort backup of what is on screen.
+ *
+ * @stability experimental
+ */
+export interface DataTablePreferencesPort {
+    /**
+     * Reads the whole stored namespace, keyed by table id. Resolves to `null` or
+     * `undefined` when nothing is stored. The value is untrusted JSON: the table
+     * narrows it defensively before use.
+     */
+    load(): Promise<Readonly<Record<string, unknown>> | null | undefined>;
+    /**
+     * Stores one table's COMPLETE entry (it replaces the stored one wholesale),
+     * or deletes it when `entry` is `null`.
+     */
+    save(tableId: string, entry: DataTableStoredLayout | null): Promise<unknown>;
+}
+/**
+ * The port over the platform's user-settings routes: `GET /user-settings`
+ * (the `dataTables` namespace) and `PATCH /user-settings` with
+ * `{ dataTables: { [tableId]: entry | null } }`.
+ *
+ * The PATCH carries no `If-Match`: the write is a fire-and-forget backup that
+ * touches one key of one namespace, and the server merges per table, so a
+ * version check would only fail on an unrelated concurrent write.
+ *
+ * @param api - the host's transport (`usePlatformApi()`).
+ * @returns a port over the user-settings API.
+ *
+ * @example
+ * ```tsx
+ * <DataTablePreferencesProvider port={createUserSettingsPreferencesPort(api)}>
+ *   <Page />
+ * </DataTablePreferencesProvider>
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export declare function createUserSettingsPreferencesPort(api: PlatformApiClient): DataTablePreferencesPort;
+/**
+ * Supplies the {@link DataTablePreferencesPort} to every `DataTable` below it,
+ * instead of the default user-settings port. Keep `port`'s identity stable.
+ *
+ * @param props - `port`: where layouts are kept; `children`: the tree.
+ * @returns the provider element.
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export declare function DataTablePreferencesProvider(props: {
+    port: DataTablePreferencesPort;
+    children: ReactNode;
+}): ReactElement;
+/**
+ * The port in force: the one a {@link DataTablePreferencesProvider} supplies,
+ * else the user-settings port over the host's transport, else `null`
+ * (preferences stay in-session only).
+ *
+ * @returns the port, or `null` when there is nowhere to keep preferences.
+ *
+ * @stability experimental
+ */
+export declare function useDataTablePreferencesPort(): DataTablePreferencesPort | null;
+//# sourceMappingURL=preferences.d.ts.map

package/dist/datatable/headless/layout/preferences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preferences.d.ts","sourceRoot":"","sources":["../../../../src/datatable/headless/layout/preferences.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACtE;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iCAAiC,CAAC,GAAG,EAAE,iBAAiB,GAAG,wBAAwB,CAQlG;AAKD;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IAClD,IAAI,EAAE,wBAAwB,CAAC;IAC/B,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,YAAY,CAEf;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,IAAI,wBAAwB,GAAG,IAAI,CAK7E"}

package/dist/datatable/headless/layout/preferences.js

@@ -0,0 +1,65 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from 'react';
+import { useOptionalPlatformHost } from '../../../core/index.js';
+/**
+ * The port over the platform's user-settings routes: `GET /user-settings`
+ * (the `dataTables` namespace) and `PATCH /user-settings` with
+ * `{ dataTables: { [tableId]: entry | null } }`.
+ *
+ * The PATCH carries no `If-Match`: the write is a fire-and-forget backup that
+ * touches one key of one namespace, and the server merges per table, so a
+ * version check would only fail on an unrelated concurrent write.
+ *
+ * @param api - the host's transport (`usePlatformApi()`).
+ * @returns a port over the user-settings API.
+ *
+ * @example
+ * ```tsx
+ * <DataTablePreferencesProvider port={createUserSettingsPreferencesPort(api)}>
+ *   <Page />
+ * </DataTablePreferencesProvider>
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export function createUserSettingsPreferencesPort(api) {
+    return {
+        async load() {
+            const settings = await api.get('/user-settings');
+            return settings?.dataTables;
+        },
+        save: (tableId, entry) => api.patch('/user-settings', { dataTables: { [tableId]: entry } }),
+    };
+}
+const PreferencesContext = createContext(null);
+PreferencesContext.displayName = 'DataTablePreferencesContext';
+/**
+ * Supplies the {@link DataTablePreferencesPort} to every `DataTable` below it,
+ * instead of the default user-settings port. Keep `port`'s identity stable.
+ *
+ * @param props - `port`: where layouts are kept; `children`: the tree.
+ * @returns the provider element.
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export function DataTablePreferencesProvider(props) {
+    return _jsx(PreferencesContext.Provider, { value: props.port, children: props.children });
+}
+/**
+ * The port in force: the one a {@link DataTablePreferencesProvider} supplies,
+ * else the user-settings port over the host's transport, else `null`
+ * (preferences stay in-session only).
+ *
+ * @returns the port, or `null` when there is nowhere to keep preferences.
+ *
+ * @stability experimental
+ */
+export function useDataTablePreferencesPort() {
+    const supplied = useContext(PreferencesContext);
+    const host = useOptionalPlatformHost();
+    const api = host?.api;
+    return useMemo(() => supplied ?? (api ? createUserSettingsPreferencesPort(api) : null), [supplied, api]);
+}
+//# sourceMappingURL=preferences.js.map

package/dist/datatable/headless/layout/preferences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preferences.js","sourceRoot":"","sources":["../../../../src/datatable/headless/layout/preferences.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAG3D,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AA8BjE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iCAAiC,CAAC,GAAsB;IACtE,OAAO;QACL,KAAK,CAAC,IAAI;YACR,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,GAAG,CAAqE,gBAAgB,CAAC,CAAC;YACrH,OAAO,QAAQ,EAAE,UAAU,CAAC;QAC9B,CAAC;QACD,IAAI,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,gBAAgB,EAAE,EAAE,UAAU,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;KAC5F,CAAC;AACJ,CAAC;AAED,MAAM,kBAAkB,GAAG,aAAa,CAAkC,IAAI,CAAC,CAAC;AAChF,kBAAkB,CAAC,WAAW,GAAG,6BAA6B,CAAC;AAE/D;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B,CAAC,KAG5C;IACC,OAAO,KAAC,kBAAkB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,CAAC,IAAI,YAAG,KAAK,CAAC,QAAQ,GAA+B,CAAC;AACxG,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,2BAA2B;IACzC,MAAM,QAAQ,GAAG,UAAU,CAAC,kBAAkB,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,uBAAuB,EAAE,CAAC;IACvC,MAAM,GAAG,GAAG,IAAI,EAAE,GAAG,CAAC;IACtB,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,QAAQ,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,iCAAiC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;AAC3G,CAAC"}