@happyvertical/smrt-content 0.43.4 → 0.43.6

package/dist/svelte/content-list-url-state.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Shareable URL state for ContentList (#2452).
+ *
+ * A content list view is a link: an operator narrows the list, copies the
+ * address bar, and a colleague opens the same result. That makes the query
+ * string an *untrusted* input — it arrives from whoever sent the link, not from
+ * the operator's own session — so every restored value is re-derived here
+ * against the adapter's published column and operator vocabulary rather than
+ * trusted as written.
+ *
+ * The module owns two things:
+ *
+ * 1. A compact, human-legible parameter shape (`q`, `type`, `status`, `sort`,
+ *    `page`, `size`, and `<column>.<operator>` for the richer operators). A
+ *    base64 blob would round-trip just as well but would be unreadable, and an
+ *    unreadable link is one nobody can sanity-check before sending it.
+ * 2. `sanitizeContentListViewState`, the single validator shared with the
+ *    saved-views module (`content-list-saved-views.ts`), so a crafted URL and a
+ *    tampered stored view are held to exactly the same allowlist.
+ *
+ * ## What may be restored
+ *
+ * | Aspect | Allowlist |
+ * |--------|-----------|
+ * | filters, sorting | `CONTENT_LIST_VISIBLE_COLUMN_IDS` — the columns the surface descriptor publishes with `filter`/`sort` capability |
+ * | projection (order, visibility, widths, pinning) | `CONTENT_LIST_TABLE_COLUMN_IDS`, and a hidden column can never be forced visible |
+ * | filter operators | `CONTENT_LIST_FILTER_OPERATORS` |
+ * | filter values | strings only, normalized by `normalizeContentListFilterValue` |
+ *
+ * The search-only `description` column, the structural `select`/`actions`
+ * columns, and any column id the adapter does not publish are dropped from
+ * filters and sorting. Dropping — never throwing — is deliberate: a stale link
+ * or an out-of-date saved view must still open the list, minus the parts that
+ * are no longer meaningful.
+ *
+ * ## What is deliberately NOT URL state
+ *
+ * Selection and expansion are excluded, and `sanitizeContentListViewState`
+ * never emits them either. A shared link must not carry another operator's
+ * selection: the recipient would inherit a checked set they never chose, and
+ * the very next bulk action — delete included — would run against it. Row ids
+ * are also the one part of view state that leaks data (which specific contents
+ * someone had singled out) into a URL that gets pasted into chat and tickets.
+ */
+import type { DataTableController, DataTableTransition, DataTableViewState } from '@happyvertical/smrt-ui/data';
+/** Query-string parameter carrying the free-text search. */
+export declare const CONTENT_LIST_SEARCH_PARAM = "q";
+/** Query-string parameter carrying the ordered sort rules. */
+export declare const CONTENT_LIST_SORT_PARAM = "sort";
+/** Query-string parameter carrying the 1-based page. */
+export declare const CONTENT_LIST_PAGE_PARAM = "page";
+/** Query-string parameter carrying the page size. */
+export declare const CONTENT_LIST_PAGE_SIZE_PARAM = "size";
+/**
+ * Parameter names this module owns. A column may not shadow one of them; the
+ * assertion below keeps that true if a future column is ever named `q` or
+ * `page`.
+ */
+export declare const CONTENT_LIST_RESERVED_PARAMS: readonly ["q", "sort", "page", "size"];
+/**
+ * Columns a restored filter or sort rule may address: exactly the columns the
+ * surface descriptor publishes with `filter` and `sort` capability.
+ */
+export declare const CONTENT_LIST_QUERYABLE_COLUMN_IDS: readonly ["type", "title", "author", "status", "state", "publish", "updated", "site"];
+/**
+ * Operators a restored filter may use. This is the full DataTable operator
+ * vocabulary the adapter's evaluator implements — narrower than "anything that
+ * parses", so an unrecognized operator can never reach the query layer.
+ */
+export declare const CONTENT_LIST_FILTER_OPERATORS: readonly ["equals", "notEquals", "contains", "notContains", "startsWith", "endsWith", "in", "notIn", "gt", "gte", "lt", "lte", "isNull", "isNotNull"];
+/**
+ * Upper bound for a restored page size, mirroring the surface descriptor's
+ * `limits.maxQueryRows`. A link is an untrusted input into a server query
+ * (#2452), so `?size=1000000` must clamp rather than become a row budget.
+ */
+export declare const CONTENT_LIST_MAX_PAGE_SIZE = 200;
+/** Why one piece of a restored view was discarded. */
+export type ContentListStateDropReason = 
+/** The column id is not published by the adapter at all. */
+'unknown-column'
+/** The column exists but is search-only and never published. */
+ | 'hidden-column'
+/** The column is structural (`select`/`actions`) and carries no query. */
+ | 'structural-column'
+/** The operator is outside `CONTENT_LIST_FILTER_OPERATORS`. */
+ | 'unsupported-operator'
+/** The value is missing, blank, or not expressible as normalized text. */
+ | 'unsupported-value'
+/** The entry is not shaped like the state it claims to be. */
+ | 'malformed'
+/** The value was outside the accepted range and was clamped or reset. */
+ | 'out-of-range';
+/** Which part of the view a drop applies to. */
+export type ContentListStateDropScope = 
+/** The payload as a whole was not shaped like a view state. */
+'state' | 'search' | 'filter' | 'sorting' | 'page' | 'pageSize' | 'columnOrder' | 'columnVisibility' | 'columnWidths' | 'columnPinning';
+/**
+ * One discarded piece of a restored view. Reported rather than thrown so a UI
+ * can tell the operator "this saved view referenced a column that no longer
+ * exists" instead of failing to open the list.
+ */
+export interface ContentListStateDrop {
+    scope: ContentListStateDropScope;
+    reason: ContentListStateDropReason;
+    columnId?: string;
+    detail?: string;
+}
+/**
+ * The validated subset of a view state.
+ *
+ * Deliberately `Partial`: only the aspects the source actually carried are
+ * present, and selection/expansion are never present at all.
+ */
+export interface ContentListViewStateSanitization {
+    state: Partial<DataTableViewState>;
+    dropped: ContentListStateDrop[];
+}
+export interface ContentListStateValidationOptions {
+    /** Overrides the clamp on a restored page size. */
+    maxPageSize?: number;
+}
+export interface ContentListUrlStateOptions extends ContentListStateValidationOptions {
+    /**
+     * Namespaces every owned parameter, so two lists can share one URL. With a
+     * prefix set, an unrecognized prefixed parameter is reported rather than
+     * ignored as a foreign parameter.
+     */
+    prefix?: string;
+    /**
+     * The page size that is considered the default and therefore omitted from —
+     * and filled back in by — the query string. Hosts that seed a page size must
+     * pass the same value both ways or a clean link will restore as unpaginated.
+     */
+    defaultPageSize?: number | null;
+}
+/** Reading a URL additionally reports what it refused to restore. */
+export interface ContentListUrlStateReading extends ContentListViewStateSanitization {
+    state: Partial<DataTableViewState>;
+}
+/**
+ * The single validator behind both restoration paths.
+ *
+ * Every restored aspect is re-derived from the adapter's published vocabulary,
+ * so neither a crafted query string nor a tampered saved view can introduce a
+ * filter, a sort rule, or a projection on a column the surface does not
+ * publish. Invalid input is dropped and reported, never thrown, and selection
+ * and expansion are never emitted.
+ */
+export declare function sanitizeContentListViewState(input: unknown, options?: ContentListStateValidationOptions): ContentListViewStateSanitization;
+/**
+ * Merges a patch onto a controller's current state, validating it first.
+ *
+ * INVARIANT: no exported path may apply unvalidated state to a controller.
+ * This function is the only application point the package publishes, and it is
+ * routinely composed with values that came from somewhere untrusted — a query
+ * string, a `localStorage` blob, an agent command. Sanitizing here means the
+ * composition `applyContentListViewState(controller, storedView.snapshot.state)`
+ * is safe even though the store's read path deliberately keeps the raw payload
+ * so a stale view's drops can still be reported (see
+ * `restoreContentListSavedView`). Sanitization is idempotent, so calling this
+ * with an already-validated patch changes nothing.
+ *
+ * Only the *patch* is sanitized, never the merged result: the sanitizer never
+ * emits selection or expansion, so sanitizing the merge would silently clear
+ * the operator's current selection.
+ *
+ * Restoration is a state replacement rather than a command: it is not a user
+ * interaction and must not reset the page the way `setSearch`/`setFilters` do.
+ * Aspects the patch omits — selection and expansion above all — are carried
+ * over from the controller untouched.
+ *
+ * Use {@link sanitizeContentListViewState} directly when the caller needs to
+ * report what was refused.
+ */
+export declare function applyContentListViewState(controller: DataTableController, patch: Partial<DataTableViewState>, options?: ContentListStateValidationOptions): DataTableTransition;
+/**
+ * Serializes a view state into shareable query parameters.
+ *
+ * The state is validated on the way out as well as on the way in: a link this
+ * module produces can never carry a filter or sort on a column the surface
+ * does not publish, even if the caller's controller somehow holds one.
+ * Defaults are omitted so an untouched list produces a clean URL.
+ */
+export declare function contentListViewStateToSearchParams(state: Partial<DataTableViewState>, options?: ContentListUrlStateOptions): URLSearchParams;
+/**
+ * Writes the owned parameters into a copy of an existing query string,
+ * preserving every parameter this module does not own (routing keys, campaign
+ * tags, a sibling list's prefixed parameters).
+ */
+export declare function mergeContentListViewStateIntoSearchParams(params: URLSearchParams, state: Partial<DataTableViewState>, options?: ContentListUrlStateOptions): URLSearchParams;
+/**
+ * Reads a view state from query parameters and reports everything it refused.
+ *
+ * Foreign parameters are ignored silently: a shared link routinely carries
+ * routing and campaign keys this module knows nothing about, and reporting
+ * them as drops would bury the reports that matter. A parameter that *looks*
+ * like a content-list filter — a known column, or any name carrying a known
+ * operator suffix — is reported when it is refused, which is what makes a
+ * crafted `description=` or `evil.contains=` visible rather than silent.
+ */
+export declare function readContentListViewStateFromSearchParams(params: URLSearchParams, options?: ContentListUrlStateOptions): ContentListUrlStateReading;
+/**
+ * Reads a view state from query parameters.
+ *
+ * The result always carries `search`, `filters`, `sorting`, `page`, and
+ * `pageSize` — an absent parameter restores that aspect's default, so a clean
+ * link restores a clean view rather than leaving stale state in place. Use
+ * {@link readContentListViewStateFromSearchParams} when the refusals matter.
+ */
+export declare function contentListViewStateFromSearchParams(params: URLSearchParams, options?: ContentListUrlStateOptions): Partial<DataTableViewState>;
+//# sourceMappingURL=content-list-url-state.d.ts.map

package/dist/svelte/content-list-url-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-list-url-state.d.ts","sourceRoot":"","sources":["../../src/svelte/content-list-url-state.ts"],"names":[],"mappings":"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"}