@happyvertical/smrt-ui 0.51.39 → 0.53.0

package/dist/components/data/link-surface.d.ts

@@ -0,0 +1,79 @@
+/**
+ * A navigation list (a menu, a tab row, a section list) as a mounted data
+ * surface, so an agent can move a person between pages without a REST path.
+ *
+ * A view intent can only dispatch a registry command, so "go to page X" needs
+ * a mounted surface whose visible control performs the navigation. This
+ * registers one: the links are published in the snapshot state
+ * (`state.links`: id, label, description, group — never an href an agent
+ * could steer), and each declared control resolves its payload to one of
+ * those links (or to a caller-built href) and hands it to `navigate`.
+ *
+ * Navigation is a read-only view-state change: nothing is created or changed.
+ */
+import type { DataSurfaceDescriptor, DataSurfaceJsonValue, DataSurfaceKind, DataSurfaceRegistry, DataSurfaceSubject } from '@happyvertical/smrt-types';
+export interface LinkSurfaceItem {
+    /** Stable id, e.g. the nav item or tab id. */
+    id: string;
+    /** Plain label a person sees in the menu. */
+    label: string;
+    href: string;
+    description?: string;
+    /** Group or section heading the link sits under, if any. */
+    group?: string;
+}
+export interface LinkSurfaceControl {
+    id: string;
+    label: string;
+    description?: string;
+    /**
+     * Resolve a command payload to an href, or `null` to refuse. Defaults to
+     * {@link resolveLinkTarget} over the published links.
+     */
+    resolve?: (payload: DataSurfaceJsonValue | undefined, links: readonly LinkSurfaceItem[]) => string | null;
+}
+export interface LinkSurfaceOptions {
+    registry: DataSurfaceRegistry;
+    surfaceId: string;
+    kind?: DataSurfaceKind;
+    subject?: DataSurfaceSubject;
+    label: string;
+    description: string;
+    links: readonly LinkSurfaceItem[];
+    /** Defaults to one `open` control over the published links. */
+    controls?: readonly LinkSurfaceControl[];
+    /**
+     * Perform the navigation. Return its promise (e.g. SvelteKit's `goto`):
+     * the command does not wait for it, since the new page may unmount this
+     * surface, but it is tracked on the registry, so
+     * `whenSurfaceNavigationSettled(registry)` resolves only once it finished
+     * and the new page's surfaces registered.
+     */
+    navigate: (href: string) => unknown;
+    /** Extra JSON state published alongside the links (e.g. the active id). */
+    state?: Record<string, DataSurfaceJsonValue>;
+}
+export interface LinkSurfaceHandle {
+    update(next: {
+        links?: readonly LinkSurfaceItem[];
+        state?: Record<string, DataSurfaceJsonValue>;
+    }): void;
+    destroy(): void;
+}
+/** Cap on published links (and the surface's query limit). */
+export declare const LINK_SURFACE_MAX_LINKS = 200;
+/**
+ * The string an agent passed: `"Events"` or `{ target: "Events" }` (also
+ * `id` / `label` / `section` / `tab` / `page`).
+ */
+export declare function linkTargetFromPayload(payload: DataSurfaceJsonValue | undefined): string | null;
+/**
+ * Resolve a payload to one link's href: by id, then exact label, then a unique
+ * label prefix, all case-insensitive. Ambiguity resolves to `null`.
+ */
+export declare function resolveLinkTarget(payload: DataSurfaceJsonValue | undefined, links: readonly LinkSurfaceItem[]): string | null;
+/** The descriptor {@link registerLinkSurface} mounts. */
+export declare function linkSurfaceDescriptor(options: Pick<LinkSurfaceOptions, 'surfaceId' | 'kind' | 'subject' | 'label' | 'description' | 'controls'>): DataSurfaceDescriptor;
+/** Mount a navigation list on a data-surface registry. */
+export declare function registerLinkSurface(options: LinkSurfaceOptions): LinkSurfaceHandle;
+//# sourceMappingURL=link-surface.d.ts.map

package/dist/components/data/link-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-surface.d.ts","sourceRoot":"","sources":["../../../src/components/data/link-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAEnB,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,CACR,OAAO,EAAE,oBAAoB,GAAG,SAAS,EACzC,KAAK,EAAE,SAAS,eAAe,EAAE,KAC9B,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACzC;;;;;;OAMG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACpC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,IAAI,EAAE;QACX,KAAK,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;QACnC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;KAC9C,GAAG,IAAI,CAAC;IACT,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,8DAA8D;AAC9D,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAe1C;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,oBAAoB,GAAG,SAAS,GACxC,MAAM,GAAG,IAAI,CASf;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,oBAAoB,GAAG,SAAS,EACzC,KAAK,EAAE,SAAS,eAAe,EAAE,GAChC,MAAM,GAAG,IAAI,CAaf;AAaD,yDAAyD;AACzD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,IAAI,CACX,kBAAkB,EAClB,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,GAAG,UAAU,CACxE,GACA,qBAAqB,CAqCvB;AAED,0DAA0D;AAC1D,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,kBAAkB,GAC1B,iBAAiB,CAiDnB"}

package/dist/components/data/link-surface.js

@@ -0,0 +1,155 @@
+/**
+ * A navigation list (a menu, a tab row, a section list) as a mounted data
+ * surface, so an agent can move a person between pages without a REST path.
+ *
+ * A view intent can only dispatch a registry command, so "go to page X" needs
+ * a mounted surface whose visible control performs the navigation. This
+ * registers one: the links are published in the snapshot state
+ * (`state.links`: id, label, description, group — never an href an agent
+ * could steer), and each declared control resolves its payload to one of
+ * those links (or to a caller-built href) and hands it to `navigate`.
+ *
+ * Navigation is a read-only view-state change: nothing is created or changed.
+ */
+import { trackSurfaceNavigation } from './surface-navigation.js';
+/** Cap on published links (and the surface's query limit). */
+export const LINK_SURFACE_MAX_LINKS = 200;
+const DEFAULT_CONTROLS = [
+    {
+        id: 'open',
+        label: 'Open',
+        description: 'Go to one of the listed pages. Payload: { target } — a link id or its label.',
+    },
+];
+function normalize(value) {
+    return value.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+/**
+ * The string an agent passed: `"Events"` or `{ target: "Events" }` (also
+ * `id` / `label` / `section` / `tab` / `page`).
+ */
+export function linkTargetFromPayload(payload) {
+    if (typeof payload === 'string')
+        return payload.trim() ? payload : null;
+    if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+        for (const key of ['target', 'id', 'label', 'section', 'tab', 'page']) {
+            const value = payload[key];
+            if (typeof value === 'string' && value.trim())
+                return value;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve a payload to one link's href: by id, then exact label, then a unique
+ * label prefix, all case-insensitive. Ambiguity resolves to `null`.
+ */
+export function resolveLinkTarget(payload, links) {
+    const target = linkTargetFromPayload(payload);
+    if (!target)
+        return null;
+    const wanted = normalize(target);
+    const byId = links.find((link) => normalize(link.id) === wanted);
+    if (byId)
+        return byId.href;
+    const byLabel = links.filter((link) => normalize(link.label) === wanted);
+    if (byLabel.length === 1)
+        return byLabel[0].href;
+    if (byLabel.length > 1)
+        return null;
+    const byPrefix = links.filter((link) => normalize(link.label).startsWith(wanted));
+    return byPrefix.length === 1 ? byPrefix[0].href : null;
+}
+function publishedLinks(links) {
+    return links.slice(0, LINK_SURFACE_MAX_LINKS).map((link) => ({
+        id: link.id,
+        label: link.label,
+        ...(link.description ? { description: link.description } : {}),
+        ...(link.group ? { group: link.group } : {}),
+    }));
+}
+/** The descriptor {@link registerLinkSurface} mounts. */
+export function linkSurfaceDescriptor(options) {
+    const columns = [
+        { id: 'id', label: 'ID', capabilities: ['read'], role: 'row-key' },
+        { id: 'label', label: 'Name', capabilities: ['read'] },
+        { id: 'description', label: 'About', capabilities: ['read'] },
+        { id: 'group', label: 'Group', capabilities: ['read'] },
+    ];
+    return {
+        version: 1,
+        identity: {
+            kind: options.kind ?? 'list',
+            surfaceId: options.surfaceId,
+            ...(options.subject ? { subject: options.subject } : {}),
+        },
+        schemaVersion: 1,
+        label: options.label,
+        description: options.description,
+        rowKey: 'id',
+        columns,
+        query: {
+            modes: ['rows'],
+            projectableColumnIds: columns.map((column) => column.id),
+            filterableColumnIds: [],
+            sortableColumnIds: [],
+        },
+        controls: (options.controls ?? DEFAULT_CONTROLS).map((control) => ({
+            id: control.id,
+            label: control.label,
+            ...(control.description ? { description: control.description } : {}),
+        })),
+        actions: [],
+        limits: {
+            maxQueryRows: LINK_SURFACE_MAX_LINKS,
+            maxQueryBytes: 200_000,
+            maxSelectionSize: 1,
+        },
+    };
+}
+/** Mount a navigation list on a data-surface registry. */
+export function registerLinkSurface(options) {
+    let links = [...options.links];
+    let extraState = { ...(options.state ?? {}) };
+    let revision = 1;
+    const controls = new Map((options.controls ?? DEFAULT_CONTROLS).map((control) => [
+        control.id,
+        control,
+    ]));
+    const dispose = options.registry.register({
+        descriptor: linkSurfaceDescriptor(options),
+        getSnapshot: () => ({
+            revision,
+            state: { ...extraState, links: publishedLinks(links) },
+            selection: null,
+        }),
+        execute: (command) => {
+            const control = controls.get(command.controlId);
+            if (!control)
+                return { ok: false };
+            const href = (control.resolve ?? resolveLinkTarget)(command.payload, links);
+            if (!href)
+                return { ok: false };
+            void trackSurfaceNavigation(options.registry, options.navigate(href));
+            return undefined;
+        },
+    });
+    return {
+        update(next) {
+            const nextLinks = next.links ? [...next.links] : links;
+            const nextState = next.state ? { ...next.state } : extraState;
+            const changed = JSON.stringify(publishedLinks(nextLinks)) !==
+                JSON.stringify(publishedLinks(links)) ||
+                JSON.stringify(nextState) !== JSON.stringify(extraState) ||
+                nextLinks.length !== links.length ||
+                nextLinks.some((link, index) => link.href !== links[index]?.href);
+            links = nextLinks;
+            extraState = nextState;
+            if (changed)
+                revision += 1;
+        },
+        destroy() {
+            dispose();
+        },
+    };
+}

package/dist/components/data/list-sort-state.svelte.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Reactive list-sort state for pages — the one object a list's headers
+ * (`SortableHeader list={...}`), phone picker (`ListSortSelect list={...}`),
+ * rows (`sortListRows(rows, list.sort, ...)`), and data surface (`sort` /
+ * `onSort`) share. Call during component initialisation.
+ *
+ * - `createUrlListSort(spec, { url, navigate })` — server-paginated lists:
+ *   the sort lives in the URL (`?sort=&dir=`); headers are links, and `set`
+ *   navigates. Framework-agnostic: pass the router's current URL and its
+ *   navigate function (SvelteKit: `() => page.url` and `goto`).
+ * - `createLocalListSort(spec)` — lists that load every row: page state.
+ */
+import { type ListSort, type ListSortSpec } from './list-sort.js';
+export interface ListSortState {
+    readonly sort: ListSort;
+    readonly spec: ListSortSpec;
+    /** Link to the list after activating `columnId`'s header (URL lists only). */
+    href(columnId: string): string | undefined;
+    /** Activate a header: toggle `columnId` (URL lists: the link navigates). */
+    toggle(columnId: string): void | Promise<void>;
+    /**
+     * Apply a sort (headers, the "Sort by" picker, agents). A sort naming an
+     * undeclared column or an unknown direction is ignored.
+     */
+    set(sort: ListSort): void | Promise<void>;
+}
+export interface UrlListSortOptions {
+    /** The current URL (reactive, e.g. SvelteKit's `page.url`). */
+    url: () => URL | {
+        pathname: string;
+        search: string;
+        searchParams: URLSearchParams;
+    };
+    /** Navigate to a same-page href (keep focus and scroll, replace history). */
+    navigate: (href: string) => void | Promise<void>;
+}
+export declare function createUrlListSort(spec: ListSortSpec, options: UrlListSortOptions): ListSortState;
+export declare function createLocalListSort(spec: ListSortSpec, initial?: ListSort): ListSortState;
+//# sourceMappingURL=list-sort-state.svelte.d.ts.map

package/dist/components/data/list-sort-state.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-sort-state.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/data/list-sort-state.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,YAAY,EAIlB,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,8EAA8E;IAC9E,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC3C,4EAA4E;IAC5E,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,GAAG,EAAE,MACD,GAAG,GACH;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,eAAe,CAAA;KAAE,CAAC;IACxE,6EAA6E;IAC7E,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,kBAAkB,GAC1B,aAAa,CAef;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,YAAY,EAClB,OAAO,CAAC,EAAE,QAAQ,GACjB,aAAa,CAkBf"}

package/dist/components/data/list-sort-state.svelte.js

@@ -0,0 +1,47 @@
+/**
+ * Reactive list-sort state for pages — the one object a list's headers
+ * (`SortableHeader list={...}`), phone picker (`ListSortSelect list={...}`),
+ * rows (`sortListRows(rows, list.sort, ...)`), and data surface (`sort` /
+ * `onSort`) share. Call during component initialisation.
+ *
+ * - `createUrlListSort(spec, { url, navigate })` — server-paginated lists:
+ *   the sort lives in the URL (`?sort=&dir=`); headers are links, and `set`
+ *   navigates. Framework-agnostic: pass the router's current URL and its
+ *   navigate function (SvelteKit: `() => page.url` and `goto`).
+ * - `createLocalListSort(spec)` — lists that load every row: page state.
+ */
+import { isValidListSort, listSortHref, parseListSort, toggleListSort, } from './list-sort.js';
+export function createUrlListSort(spec, options) {
+    const sort = $derived(parseListSort(options.url().searchParams, spec));
+    return {
+        get sort() {
+            return sort;
+        },
+        spec,
+        href: (columnId) => listSortHref(options.url(), toggleListSort(sort, columnId, spec), spec),
+        toggle: () => { },
+        set: (next) => {
+            if (!isValidListSort(spec, next))
+                return;
+            return options.navigate(listSortHref(options.url(), next, spec));
+        },
+    };
+}
+export function createLocalListSort(spec, initial) {
+    let sort = $state(isValidListSort(spec, initial) ? { ...initial } : { ...spec.default });
+    return {
+        get sort() {
+            return sort;
+        },
+        spec,
+        href: () => undefined,
+        toggle: (columnId) => {
+            sort = toggleListSort(sort, columnId, spec);
+        },
+        set: (next) => {
+            if (!isValidListSort(spec, next))
+                return;
+            sort = { columnId: next.columnId, direction: next.direction };
+        },
+    };
+}

package/dist/components/data/list-sort.d.ts

@@ -0,0 +1,94 @@
+/**
+ * List sorting — one contract for every list, client or server paginated.
+ *
+ * - A list declares its sortable columns and a default sort (usually its main
+ *   date column, newest first).
+ * - Clicking a header toggles that column between ascending and descending;
+ *   a column not yet sorted starts at its `firstDirection` (dates and numbers
+ *   usually `desc`, text `asc`). Sorting never "clears" back to unsorted: the
+ *   list always has one well-defined order.
+ * - Server-paginated lists keep the sort in the URL (`?sort=<column>&dir=<asc|desc>`)
+ *   so the database orders the WHOLE result set, not just the current page.
+ *   The default sort is omitted from the URL, and changing the sort drops the
+ *   page parameter (back to page 1).
+ * - Values are validated against the declared columns, so a URL or an agent
+ *   command can only pick a declared column and a known direction.
+ *
+ * Pure functions, no Svelte or DOM: usable in `+page.server.ts` loads,
+ * components, and data-surface handlers alike.
+ */
+export type ListSortDirection = 'asc' | 'desc';
+export interface ListSort {
+    columnId: string;
+    direction: ListSortDirection;
+}
+export interface ListSortColumnSpec {
+    id: string;
+    /** Direction on the first click of this column (default `asc`; use `desc` for dates and counts). */
+    firstDirection?: ListSortDirection;
+}
+/** A column offered by `ListSortSelect` (the phone / card-list sort picker). */
+export interface ListSortSelectColumn {
+    id: string;
+    label: string;
+    /** Picks the plain words: dates "newest first", numbers "highest first", text "A–Z". */
+    kind?: 'date' | 'number' | 'text';
+}
+export interface ListSortSpec {
+    /** Sortable columns. Ids are what the URL and agents use. */
+    columns: readonly (ListSortColumnSpec | string)[];
+    /** The list's order with no `sort` parameter. Must name a declared column. */
+    default: ListSort;
+    /** Query parameter names (default `sort` and `dir`). */
+    sortParam?: string;
+    dirParam?: string;
+    /** Page parameter to drop when the sort changes (default `page`; `null` keeps it). */
+    pageParam?: string | null;
+}
+/** The ids of the sortable columns. */
+export declare function listSortColumnIds(spec: ListSortSpec): string[];
+/** Whether `sort` names a declared column and a known direction. */
+export declare function isValidListSort(spec: ListSortSpec, sort: Partial<ListSort> | null | undefined): sort is ListSort;
+/**
+ * Read the sort from URL parameters. An unknown column falls back to the
+ * default; a missing or unknown direction falls back to the column's first
+ * direction (or the default's direction for the default column).
+ */
+export declare function parseListSort(params: URLSearchParams | {
+    get(name: string): string | null;
+}, spec: ListSortSpec): ListSort;
+/** The sort after activating a column's header (toggle; never cleared). */
+export declare function toggleListSort(current: ListSort, columnId: string, spec: ListSortSpec): ListSort;
+/**
+ * URL parameters for `sort`: sets (or, for the default, removes) the sort
+ * parameters and drops the page parameter when the sort changed.
+ */
+export declare function listSortSearchParams(params: URLSearchParams | string, sort: ListSort, spec: ListSortSpec): URLSearchParams;
+/** `?query` string (with the leading `?`, or `''`) for a sort link. */
+export declare function listSortHref(url: URL | {
+    pathname: string;
+    search: string;
+}, sort: ListSort, spec: ListSortSpec): string;
+/** `aria-sort` for a header cell. */
+export declare function listSortAria(current: ListSort | null | undefined, columnId: string): 'ascending' | 'descending' | 'none';
+/** A plain-language label for the header's action, e.g. "Sort by Date, newest first". */
+export declare function listSortActionLabel(current: ListSort | null | undefined, columnId: string, label: string, spec?: ListSortSpec): string;
+export type ListSortValue = string | number | boolean | Date | null | undefined;
+/**
+ * Compare two values for `direction`. Empty values (null, undefined, '',
+ * invalid dates) always sort last. Strings compare with `localeCompare`
+ * (numeric-aware, case-insensitive).
+ */
+export declare function compareListValues(left: ListSortValue, right: ListSortValue, direction: ListSortDirection): number;
+/** A sorted copy of `rows` (stable; empties last). */
+export declare function sortListRows<T>(rows: readonly T[], sort: ListSort | null | undefined, getValue: (row: T, columnId: string) => ListSortValue): T[];
+/**
+ * Resolve a sort to an allow-listed ORDER BY term for a server query. `map`
+ * names the SQL expression (or ORM field) for each sortable column; the
+ * result is only ever built from `map` values, never from the input.
+ * Returns e.g. `COALESCE(c.publish_date, c.created_at) DESC NULLS LAST`.
+ */
+export declare function listSortOrderBy(sort: ListSort, map: Readonly<Record<string, string>>, options?: {
+    nulls?: 'last' | 'first' | false;
+}): string;
+//# sourceMappingURL=list-sort.d.ts.map

package/dist/components/data/list-sort.d.ts.map

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

package/dist/components/data/list-sort.js

@@ -0,0 +1,182 @@
+/**
+ * List sorting — one contract for every list, client or server paginated.
+ *
+ * - A list declares its sortable columns and a default sort (usually its main
+ *   date column, newest first).
+ * - Clicking a header toggles that column between ascending and descending;
+ *   a column not yet sorted starts at its `firstDirection` (dates and numbers
+ *   usually `desc`, text `asc`). Sorting never "clears" back to unsorted: the
+ *   list always has one well-defined order.
+ * - Server-paginated lists keep the sort in the URL (`?sort=<column>&dir=<asc|desc>`)
+ *   so the database orders the WHOLE result set, not just the current page.
+ *   The default sort is omitted from the URL, and changing the sort drops the
+ *   page parameter (back to page 1).
+ * - Values are validated against the declared columns, so a URL or an agent
+ *   command can only pick a declared column and a known direction.
+ *
+ * Pure functions, no Svelte or DOM: usable in `+page.server.ts` loads,
+ * components, and data-surface handlers alike.
+ */
+function columnSpecs(spec) {
+    return spec.columns.map((column) => typeof column === 'string' ? { id: column } : column);
+}
+function columnSpec(spec, columnId) {
+    return columnSpecs(spec).find((column) => column.id === columnId);
+}
+function isDirection(value) {
+    return value === 'asc' || value === 'desc';
+}
+/** The ids of the sortable columns. */
+export function listSortColumnIds(spec) {
+    return columnSpecs(spec).map((column) => column.id);
+}
+/** Whether `sort` names a declared column and a known direction. */
+export function isValidListSort(spec, sort) {
+    return (!!sort &&
+        typeof sort.columnId === 'string' &&
+        columnSpec(spec, sort.columnId) !== undefined &&
+        isDirection(sort.direction));
+}
+/**
+ * Read the sort from URL parameters. An unknown column falls back to the
+ * default; a missing or unknown direction falls back to the column's first
+ * direction (or the default's direction for the default column).
+ */
+export function parseListSort(params, spec) {
+    const columnId = params.get(spec.sortParam ?? 'sort');
+    const direction = params.get(spec.dirParam ?? 'dir');
+    const column = columnId ? columnSpec(spec, columnId) : undefined;
+    if (!column) {
+        return isDirection(direction) && !columnId
+            ? { columnId: spec.default.columnId, direction }
+            : { ...spec.default };
+    }
+    if (isDirection(direction))
+        return { columnId: column.id, direction };
+    return {
+        columnId: column.id,
+        direction: column.id === spec.default.columnId
+            ? spec.default.direction
+            : (column.firstDirection ?? 'asc'),
+    };
+}
+/** The sort after activating a column's header (toggle; never cleared). */
+export function toggleListSort(current, columnId, spec) {
+    const column = columnSpec(spec, columnId);
+    if (!column)
+        return current;
+    if (current.columnId === columnId) {
+        return {
+            columnId,
+            direction: current.direction === 'asc' ? 'desc' : 'asc',
+        };
+    }
+    return { columnId, direction: column.firstDirection ?? 'asc' };
+}
+/**
+ * URL parameters for `sort`: sets (or, for the default, removes) the sort
+ * parameters and drops the page parameter when the sort changed.
+ */
+export function listSortSearchParams(params, sort, spec) {
+    const next = new URLSearchParams(params);
+    const sortParam = spec.sortParam ?? 'sort';
+    const dirParam = spec.dirParam ?? 'dir';
+    const previous = parseListSort(next, spec);
+    const isDefault = sort.columnId === spec.default.columnId &&
+        sort.direction === spec.default.direction;
+    if (isDefault) {
+        next.delete(sortParam);
+        next.delete(dirParam);
+    }
+    else {
+        next.set(sortParam, sort.columnId);
+        next.set(dirParam, sort.direction);
+    }
+    const pageParam = spec.pageParam === undefined ? 'page' : spec.pageParam;
+    if (pageParam &&
+        (previous.columnId !== sort.columnId ||
+            previous.direction !== sort.direction)) {
+        next.delete(pageParam);
+    }
+    return next;
+}
+/** `?query` string (with the leading `?`, or `''`) for a sort link. */
+export function listSortHref(url, sort, spec) {
+    const query = listSortSearchParams(url.search, sort, spec).toString();
+    return `${url.pathname}${query ? `?${query}` : ''}`;
+}
+/** `aria-sort` for a header cell. */
+export function listSortAria(current, columnId) {
+    if (!current || current.columnId !== columnId)
+        return 'none';
+    return current.direction === 'asc' ? 'ascending' : 'descending';
+}
+/** A plain-language label for the header's action, e.g. "Sort by Date, newest first". */
+export function listSortActionLabel(current, columnId, label, spec) {
+    const next = spec
+        ? toggleListSort(current ?? spec.default, columnId, spec).direction
+        : current?.columnId === columnId && current.direction === 'asc'
+            ? 'desc'
+            : 'asc';
+    return `Sort by ${label}, ${next === 'asc' ? 'ascending' : 'descending'}`;
+}
+function comparable(value) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    if (value instanceof Date) {
+        const time = value.getTime();
+        return Number.isNaN(time) ? null : time;
+    }
+    if (typeof value === 'boolean')
+        return value ? 1 : 0;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    return value;
+}
+/**
+ * Compare two values for `direction`. Empty values (null, undefined, '',
+ * invalid dates) always sort last. Strings compare with `localeCompare`
+ * (numeric-aware, case-insensitive).
+ */
+export function compareListValues(left, right, direction) {
+    const a = comparable(left);
+    const b = comparable(right);
+    if (a === null && b === null)
+        return 0;
+    if (a === null)
+        return 1;
+    if (b === null)
+        return -1;
+    const sign = direction === 'asc' ? 1 : -1;
+    if (typeof a === 'number' && typeof b === 'number')
+        return (a - b) * sign;
+    return (String(a).localeCompare(String(b), undefined, {
+        numeric: true,
+        sensitivity: 'base',
+    }) * sign);
+}
+/** A sorted copy of `rows` (stable; empties last). */
+export function sortListRows(rows, sort, getValue) {
+    if (!sort)
+        return [...rows];
+    return rows
+        .map((row, index) => ({ row, index }))
+        .sort((left, right) => compareListValues(getValue(left.row, sort.columnId), getValue(right.row, sort.columnId), sort.direction) || left.index - right.index)
+        .map((entry) => entry.row);
+}
+/**
+ * Resolve a sort to an allow-listed ORDER BY term for a server query. `map`
+ * names the SQL expression (or ORM field) for each sortable column; the
+ * result is only ever built from `map` values, never from the input.
+ * Returns e.g. `COALESCE(c.publish_date, c.created_at) DESC NULLS LAST`.
+ */
+export function listSortOrderBy(sort, map, options = {}) {
+    const expression = Object.hasOwn(map, sort.columnId)
+        ? map[sort.columnId]
+        : undefined;
+    if (!expression) {
+        throw new Error(`Unknown sort column: ${sort.columnId}`);
+    }
+    const nulls = options.nulls === undefined ? 'last' : options.nulls;
+    return `${expression} ${sort.direction === 'asc' ? 'ASC' : 'DESC'}${nulls ? ` NULLS ${nulls === 'last' ? 'LAST' : 'FIRST'}` : ''}`;
+}