@viniaraujo68/plinth 0.0.0-stage → 0.3.0

package/dist/table/DataTable.svelte.d.ts

@@ -0,0 +1,153 @@
+import type { Snippet } from "svelte";
+import type { ClassValue } from "svelte/elements";
+import type { Column, ColumnState, SortState } from "./types.js";
+declare function $$render<T>(): {
+    props: {
+        rows: readonly T[];
+        columns: Column<T>[];
+        /** Identity of a row, so re-sorting moves the existing markup instead of rebuilding it. */
+        rowKey: (row: T) => string | number;
+        /**
+         * The order the table is in. Bindable and defaulted, so it is uncontrolled when passed as a
+         * plain value — an initial sort — and controlled the moment a caller writes `bind:sort`.
+         */
+        sort?: SortState;
+        /** Collation locale for string columns. Defaults to the runtime's. */
+        locale?: string;
+        onRowClick?: (row: T) => void;
+        /** Shown in place of the rows when there are none. */
+        empty?: Snippet;
+        /**
+         * Replaces the label/value pairs in card form, for rows that read better as a shape than as a
+         * list. Never rendered in table form, so a cell snippet and this one do not compete.
+         *
+         * The second argument is the row's 0-based position in the order currently rendered, so a
+         * rank or a medal can follow the sort without the caller re-deriving it. A snippet declared
+         * with one parameter stays assignable and simply ignores it.
+         */
+        card?: Snippet<[T, number]>;
+        /** Accessible name of the table. A prop because the library ships no translations. */
+        label?: string;
+        /**
+         * Accessible name for a sortable header's control, given the column — `Sort by Elevation`
+         * rather than `Elevation`. Absent by default, which leaves the button named by its own label.
+         * A function, and not a string, because the wording is per column and the library ships no
+         * translations.
+         */
+        sortLabel?: (column: Column<T>) => string;
+        /**
+         * Goes on the `<table>` itself, next to daisyUI's `table`. Density and zebra striping are
+         * `table-sm` and `table-zebra` — classes the framework already has, so they are not re-exposed
+         * here as props that could only spell them differently.
+         */
+        class?: ClassValue;
+        /**
+         * Rendered in a bar above the table, at its start — the place for the controls that change
+         * what the table shows, so they sit with it instead of floating somewhere above it. The
+         * columns menu, when there is one, takes the other end of the same bar.
+         */
+        toolbar?: Snippet;
+        /**
+         * How the reader arranged the columns: order, visibility and dragged widths. Bindable and
+         * defaulted like `sort`: leave it out and the table keeps the arrangement to itself, bind it
+         * to read it back or to share it between tables. `undefined` means "as the columns declare".
+         */
+        columnState?: ColumnState;
+        /**
+         * Remembers `columnState` in `localStorage` under this key, so the reader's arrangement
+         * survives a reload. The stored state is read after the first render, not during it: a table
+         * rendered on the server has no storage to read, and changing the markup before hydration
+         * finished would tear it — so a stored layout lands one frame late instead. A stored state
+         * takes precedence over the `columnState` a parent passes in, since it is the reader's own
+         * later choice.
+         */
+        storageKey?: string | null;
+        /**
+         * Lets the reader drag a header's right edge to resize its column, double-click the edge to
+         * hand the column back to its content, or focus the edge and use the arrow keys. Columns opt
+         * out one by one with `resizable: false`; widths only apply to the table form, never to cards.
+         */
+        resizable?: boolean;
+        /**
+         * Turns on the columns menu, as the text of its trigger. The menu shows and hides columns and
+         * puts them in another order; a prop rather than a default because the library ships no
+         * translations, and the menu has nothing to be called without it.
+         */
+        columnsLabel?: string;
+        /** The menu's action that forgets the reader's arrangement, widths included. */
+        resetColumnsLabel?: string;
+        /** Names the menu's step buttons for a screen reader — "Move Year up" rather than "↑". */
+        moveColumnLabel?: (column: Column<T>, direction: "up" | "down") => string;
+        /** Names a column's resize handle for a screen reader. */
+        resizeLabel?: (column: Column<T>) => string;
+    };
+    exports: {};
+    bindings: "sort" | "columnState";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "sort" | "columnState";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+/**
+ * A sortable table that becomes a list of cards on a narrow screen. Columns are described once, as
+ * data; the rows are ordered in the browser.
+ *
+ * Which form renders is decided by a **container query on the table's own wrapper**, not by
+ * JavaScript. There is no resize listener and no `matchMedia`, so nothing flashes the wrong layout on
+ * the first paint — and because the wrapper is its own container, dropping the table into a narrow
+ * box renders its card form on a desktop, which is how the showcase shows both at once.
+ *
+ * It is one DOM either way. In card form the header row collapses into a strip of sort pills, each
+ * cell prints its column's label beside its value, and no row is duplicated to be hidden.
+ *
+ * Sorting is client-side and stable, so a second sort reads as a tiebreak on the first. Missing
+ * values sort last in both directions. `sort` is bindable: pass a value for an initial order, bind
+ * for a shared or persisted one.
+ *
+ * A `cell` or `card` snippet is rendered with the row and, second, the row's 0-based position in the
+ * order on screen — the rank column that has to follow the sort is the reason it is there, and
+ * re-running `sortRows` outside the table is what it replaces. Snippets that take only the row keep
+ * working unchanged.
+ *
+ * `sortLabel` names the sort control for a screen reader, from the column — "Sort by Elevation"
+ * rather than "Elevation" — on the header buttons and on the card-form pills alike, since they are
+ * the same element. Left out, the button is named by its own label.
+ *
+ * The reader can arrange the columns, when the table asks for it. `columnsLabel` adds a menu that
+ * shows, hides and reorders them; `resizable` adds a drag handle to every header's edge; `storageKey`
+ * remembers both across reloads. All three are off by default, and a column says whether it takes
+ * part — `hideable`, `hiddenByDefault`, `resizable`, `minWidth`. The arrangement is one bindable
+ * `columnState`, stored as overrides of what the columns declare, so adding a column in a later
+ * release neither loses a stored layout nor ends up somewhere nobody put it. Sorting by a column the
+ * reader hid keeps working: the order is about the rows, not about what is on screen.
+ *
+ * It stays short of a data grid — no filtering, no virtualization, no saved views. A table that
+ * needs those needs a different component.
+ *
+ * ```svelte
+ * <DataTable
+ * {rows}
+ * columns={[
+ *   { key: "name", label: "Name" },
+ *   { key: "size", label: "Size", numeric: true },
+ * ]}
+ * rowKey={(row) => row.id}
+ * sort={{ key: "size", direction: "desc" }}
+ * />
+ * ```
+ */
+declare const DataTable: $$IsomorphicComponent;
+type DataTable<T> = InstanceType<typeof DataTable<T>>;
+export default DataTable;

package/dist/table/columns.d.ts

@@ -0,0 +1,55 @@
+import type { Column, ColumnState } from "./types.js";
+/**
+ * The arrangeable half of a table: which columns show, in what order and at what width. Like
+ * `sort.ts` it never touches the DOM, and every change returns a new state rather than editing the
+ * one it was given — the state is usually a bound prop, and a mutation in place would change it
+ * without the owner hearing about it.
+ */
+/** The narrowest a resize can make a column when the column does not say otherwise. */
+export declare const DEFAULT_MIN_WIDTH = 48;
+export declare const emptyColumnState: () => ColumnState;
+export declare const isColumnHideable: <T>(column: Column<T>) => boolean;
+export declare const isColumnResizable: <T>(column: Column<T>) => boolean;
+export declare const minWidthOf: <T>(column: Column<T>) => number;
+/**
+ * The columns in the reader's order. Keys the state names that no longer exist are skipped, a key
+ * named twice counts once, and a column the state never heard of — added after the state was saved
+ * — goes right after the nearest column declared before it, which is where the table's author put
+ * it relative to its neighbours.
+ */
+export declare const orderColumns: <T>(columns: readonly Column<T>[], state: ColumnState | undefined) => Column<T>[];
+/** A column that cannot be hidden is always shown, whatever a stored state says about it. */
+export declare const isColumnVisible: <T>(column: Column<T>, state: ColumnState | undefined) => boolean;
+export declare const visibleColumns: <T>(columns: readonly Column<T>[], state: ColumnState | undefined) => Column<T>[];
+/**
+ * Whether the reader may take this column away. The last visible column is refused: a table with no
+ * columns has nothing left to click to bring the others back but the menu, and a header row with
+ * no headers looks broken rather than empty.
+ */
+export declare const canHideColumn: <T>(columns: readonly Column<T>[], state: ColumnState | undefined, key: string) => boolean;
+/** The width the reader dragged, never below the column's minimum; `undefined` sizes to content. */
+export declare const columnWidth: <T>(column: Column<T>, state: ColumnState | undefined) => number | undefined;
+export declare const setColumnVisible: (state: ColumnState | undefined, key: string, visible: boolean) => ColumnState;
+/**
+ * Moves a column to a position in the full order — hidden columns included, since the menu that
+ * calls this lists them too. The resulting order names every column, so the move survives a
+ * column being added later without the moved one drifting back.
+ */
+export declare const moveColumn: <T>(columns: readonly Column<T>[], state: ColumnState | undefined, key: string, to: number) => ColumnState;
+/** `null` forgets the width, which hands the column back to its content. */
+export declare const setColumnWidth: (state: ColumnState | undefined, key: string, width: number | null) => ColumnState;
+/** Whether the state asks for anything other than what the columns declare. */
+export declare const isColumnStateEmpty: (state: ColumnState | undefined) => boolean;
+/**
+ * Reads a state back from untrusted JSON — storage an older release wrote, or one a person edited
+ * by hand. Entries of the wrong type are dropped one by one instead of failing the whole state, so
+ * a single bad width does not cost the reader their column order.
+ */
+export declare const parseColumnState: (value: unknown) => ColumnState | undefined;
+/**
+ * Storage access throws outright in a sandboxed frame or with site data blocked, and a table that
+ * forgets its layout is not worth an exception — both helpers swallow it, as the shell's sidebar
+ * does.
+ */
+export declare const readColumnState: (storageKey: string) => ColumnState | undefined;
+export declare const writeColumnState: (storageKey: string, state: ColumnState | undefined) => void;

package/dist/table/columns.js

@@ -0,0 +1,153 @@
+/**
+ * The arrangeable half of a table: which columns show, in what order and at what width. Like
+ * `sort.ts` it never touches the DOM, and every change returns a new state rather than editing the
+ * one it was given — the state is usually a bound prop, and a mutation in place would change it
+ * without the owner hearing about it.
+ */
+/** The narrowest a resize can make a column when the column does not say otherwise. */
+export const DEFAULT_MIN_WIDTH = 48;
+/**
+ * Bumped whenever the stored shape changes meaning. A stored state from another version is dropped
+ * rather than migrated: it is a layout preference, and losing it costs one drag, where reading it
+ * wrong could hide a column the reader has no idea is there.
+ */
+const STORAGE_VERSION = 1;
+export const emptyColumnState = () => ({ order: [], visibility: {}, widths: {} });
+export const isColumnHideable = (column) => column.hideable !== false;
+export const isColumnResizable = (column) => column.resizable !== false;
+export const minWidthOf = (column) => column.minWidth ?? DEFAULT_MIN_WIDTH;
+/**
+ * The columns in the reader's order. Keys the state names that no longer exist are skipped, a key
+ * named twice counts once, and a column the state never heard of — added after the state was saved
+ * — goes right after the nearest column declared before it, which is where the table's author put
+ * it relative to its neighbours.
+ */
+export const orderColumns = (columns, state) => {
+    const byKey = new Map(columns.map((column) => [column.key, column]));
+    const keys = (state?.order ?? []).filter((key, index, all) => byKey.has(key) && all.indexOf(key) === index);
+    columns.forEach((column, declared) => {
+        if (keys.includes(column.key))
+            return;
+        let at = 0;
+        for (let previous = declared - 1; previous >= 0; previous--) {
+            const position = keys.indexOf(columns[previous].key);
+            if (position !== -1) {
+                at = position + 1;
+                break;
+            }
+        }
+        keys.splice(at, 0, column.key);
+    });
+    return keys.map((key) => byKey.get(key));
+};
+/** A column that cannot be hidden is always shown, whatever a stored state says about it. */
+export const isColumnVisible = (column, state) => {
+    if (!isColumnHideable(column))
+        return true;
+    return state?.visibility[column.key] ?? !column.hiddenByDefault;
+};
+export const visibleColumns = (columns, state) => orderColumns(columns, state).filter((column) => isColumnVisible(column, state));
+/**
+ * Whether the reader may take this column away. The last visible column is refused: a table with no
+ * columns has nothing left to click to bring the others back but the menu, and a header row with
+ * no headers looks broken rather than empty.
+ */
+export const canHideColumn = (columns, state, key) => {
+    const column = columns.find((candidate) => candidate.key === key);
+    if (!column || !isColumnHideable(column) || !isColumnVisible(column, state))
+        return false;
+    return visibleColumns(columns, state).length > 1;
+};
+/** The width the reader dragged, never below the column's minimum; `undefined` sizes to content. */
+export const columnWidth = (column, state) => {
+    const width = state?.widths[column.key];
+    if (width === undefined || !isColumnResizable(column))
+        return undefined;
+    return Math.max(width, minWidthOf(column));
+};
+const withDefaults = (state) => state ?? emptyColumnState();
+export const setColumnVisible = (state, key, visible) => {
+    const current = withDefaults(state);
+    return { ...current, visibility: { ...current.visibility, [key]: visible } };
+};
+/**
+ * Moves a column to a position in the full order — hidden columns included, since the menu that
+ * calls this lists them too. The resulting order names every column, so the move survives a
+ * column being added later without the moved one drifting back.
+ */
+export const moveColumn = (columns, state, key, to) => {
+    const keys = orderColumns(columns, state).map((column) => column.key);
+    const from = keys.indexOf(key);
+    if (from === -1)
+        return withDefaults(state);
+    keys.splice(from, 1);
+    keys.splice(Math.max(0, Math.min(to, keys.length)), 0, key);
+    return { ...withDefaults(state), order: keys };
+};
+/** `null` forgets the width, which hands the column back to its content. */
+export const setColumnWidth = (state, key, width) => {
+    const current = withDefaults(state);
+    const others = Object.fromEntries(Object.entries(current.widths).filter(([column]) => column !== key));
+    return {
+        ...current,
+        widths: width === null ? others : { ...others, [key]: Math.round(width) },
+    };
+};
+/** Whether the state asks for anything other than what the columns declare. */
+export const isColumnStateEmpty = (state) => !state ||
+    (state.order.length === 0 &&
+        Object.keys(state.visibility).length === 0 &&
+        Object.keys(state.widths).length === 0);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Reads a state back from untrusted JSON — storage an older release wrote, or one a person edited
+ * by hand. Entries of the wrong type are dropped one by one instead of failing the whole state, so
+ * a single bad width does not cost the reader their column order.
+ */
+export const parseColumnState = (value) => {
+    if (!isRecord(value) || value.v !== STORAGE_VERSION)
+        return undefined;
+    const order = Array.isArray(value.order)
+        ? value.order.filter((key) => typeof key === "string")
+        : [];
+    const visibility = {};
+    if (isRecord(value.visibility))
+        for (const [key, shown] of Object.entries(value.visibility))
+            if (typeof shown === "boolean")
+                visibility[key] = shown;
+    const widths = {};
+    if (isRecord(value.widths))
+        for (const [key, width] of Object.entries(value.widths))
+            if (typeof width === "number" && Number.isFinite(width) && width > 0)
+                widths[key] = width;
+    return { order, visibility, widths };
+};
+/**
+ * Storage access throws outright in a sandboxed frame or with site data blocked, and a table that
+ * forgets its layout is not worth an exception — both helpers swallow it, as the shell's sidebar
+ * does.
+ */
+export const readColumnState = (storageKey) => {
+    if (typeof localStorage === "undefined")
+        return undefined;
+    try {
+        const raw = localStorage.getItem(storageKey);
+        return raw === null ? undefined : parseColumnState(JSON.parse(raw));
+    }
+    catch {
+        return undefined;
+    }
+};
+export const writeColumnState = (storageKey, state) => {
+    if (typeof localStorage === "undefined")
+        return;
+    try {
+        if (isColumnStateEmpty(state))
+            localStorage.removeItem(storageKey);
+        else
+            localStorage.setItem(storageKey, JSON.stringify({ v: STORAGE_VERSION, ...state }));
+    }
+    catch {
+        // Same sandbox as above.
+    }
+};

package/dist/table/index.d.ts

@@ -0,0 +1,4 @@
+export { default as DataTable } from "./DataTable.svelte";
+export type { Column, ColumnState, SortDirection, SortState, SortValue } from "./types.js";
+export { ariaSort, cellText, cellValue, compareSortValues, competitionRanks, nextSort, sortFromParams, sortRows, sortToParams, sortValue, type SortParamNames, } from "./sort.js";
+export { canHideColumn, columnWidth, emptyColumnState, isColumnStateEmpty, isColumnVisible, moveColumn, orderColumns, parseColumnState, readColumnState, setColumnVisible, setColumnWidth, visibleColumns, writeColumnState, } from "./columns.js";

package/dist/table/index.js

@@ -0,0 +1,8 @@
+// A sortable table that turns into cards on a narrow screen, whose columns the reader can show,
+// hide, reorder and resize, and the pure functions behind it. Not a data grid: no filtering, no
+// virtualization, no saved views. `@viniaraujo68/plinth/table`.
+export { default as DataTable } from "./DataTable.svelte";
+export { ariaSort, cellText, cellValue, compareSortValues, competitionRanks, nextSort, sortFromParams, sortRows, sortToParams, sortValue, } from "./sort.js";
+// The layout functions the table runs on, for a caller that arranges columns outside the menu —
+// a preset layout, a "show everything" shortcut, or a state kept somewhere other than storage.
+export { canHideColumn, columnWidth, emptyColumnState, isColumnStateEmpty, isColumnVisible, moveColumn, orderColumns, parseColumnState, readColumnState, setColumnVisible, setColumnWidth, visibleColumns, writeColumnState, } from "./columns.js";

package/dist/table/sort.d.ts

@@ -0,0 +1,48 @@
+import type { Column, SortDirection, SortState, SortValue } from "./types.js";
+/** What the cell shows by default, and what it sorts by unless the column says otherwise. */
+export declare const cellValue: <T>(column: Column<T>, row: T) => unknown;
+/** How a cell reads with no snippet to render it, and what a missing value looks like. */
+export declare const cellText: <T>(column: Column<T>, row: T) => string;
+export declare const sortValue: <T>(column: Column<T>, row: T) => SortValue;
+/**
+ * Ascending comparison of two present values. Mixed types fall back to a string comparison rather
+ * than to `NaN`, which is what a `-` on incomparable operands would produce and what would then
+ * make the whole sort order undefined.
+ */
+export declare const compareSortValues: (a: SortValue, b: SortValue, locale?: string) => number;
+/**
+ * A new array in the requested order. `Array.prototype.sort` is stable by specification, so rows
+ * the comparator calls equal keep the order they arrived in — which is what makes a second sort
+ * on a different column read as a tiebreak rather than as a shuffle.
+ */
+export declare const sortRows: <T>(rows: readonly T[], column: Column<T>, direction: SortDirection, locale?: string) => T[];
+/** What a click on `column`'s header means: flip the column it already sorts, or adopt a new one. */
+export declare const nextSort: <T>(current: SortState | undefined, column: Column<T>) => SortState;
+/** The `aria-sort` of a sortable header. Unsortable headers carry no such attribute at all. */
+export declare const ariaSort: <T>(current: SortState | undefined, column: Column<T>) => "ascending" | "descending" | "none";
+/**
+ * Standard competition ranks ("1224") for rows already in display order: rows whose values compare
+ * equal share the rank of the first of them, and the next distinct value skips the places the tie
+ * used up. A missing value gets no rank at all — it sorts last, and "tied for last because nobody
+ * knows" is not a position worth printing.
+ *
+ * The table hands a `cell` snippet the row's position, which is the right number until two rows
+ * tie; a leaderboard that has to say "joint second" needs this instead.
+ */
+export declare const competitionRanks: <T>(ordered: readonly T[], valueOf: (row: T) => SortValue, locale?: string) => (number | null)[];
+/** The search parameter names a sort is written under, when the URL has room for more than one. */
+export interface SortParamNames {
+    key: string;
+    direction: string;
+}
+/**
+ * Reads a sort out of a URL's search parameters, so a shared link opens on the order its sender was
+ * looking at. Anything missing or unrecognised falls back to `fallback` piece by piece: a link with
+ * only `?sort=year` gets the fallback's direction.
+ */
+export declare const sortFromParams: (params: URLSearchParams, fallback: SortState, names?: SortParamNames) => SortState;
+/**
+ * The search parameters that write `sort` back, as updates for `withSearchParams`: a piece equal to
+ * the fallback is `null` — removed — so the URL of a table in its default order stays clean.
+ */
+export declare const sortToParams: (sort: SortState, fallback: SortState, names?: SortParamNames) => Record<string, string | null>;

package/dist/table/sort.js

@@ -0,0 +1,139 @@
+/**
+ * The table's pure half: reading a cell, ordering the rows, and deciding what a header click
+ * means. None of it touches the DOM, so it is checked in node rather than in a browser.
+ */
+/**
+ * A value with no meaningful text of its own stringifies to `[object Object]`, which is what the
+ * lint rule below is warning about and what this accepts: such rows read the same, so they compare
+ * equal and a stable sort leaves them exactly where they were. Ordering them any other way would
+ * mean guessing at a meaning the column never declared — that is what `sortBy` is for.
+ */
+// eslint-disable-next-line @typescript-eslint/no-base-to-string
+const asText = (value) => String(value);
+/** What the cell shows by default, and what it sorts by unless the column says otherwise. */
+export const cellValue = (column, row) => column.value ? column.value(row) : row[column.key];
+/** How a cell reads with no snippet to render it, and what a missing value looks like. */
+export const cellText = (column, row) => {
+    const value = cellValue(column, row);
+    if (value === null || value === undefined)
+        return "—";
+    return asText(value);
+};
+export const sortValue = (column, row) => {
+    if (column.sortBy)
+        return column.sortBy(row);
+    const raw = cellValue(column, row);
+    if (raw === null || raw === undefined)
+        return raw;
+    if (typeof raw === "string" || typeof raw === "number" || raw instanceof Date)
+        return raw;
+    // Anything else orders the way it renders, which is the only ordering the table can defend
+    // without being told what the value means.
+    return asText(raw);
+};
+/** A missing value, an unparsed date and a `NaN` are all "no value", and all sort last. */
+const isMissing = (value) => {
+    if (value === null || value === undefined)
+        return true;
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime());
+    return typeof value === "number" && Number.isNaN(value);
+};
+/**
+ * Ascending comparison of two present values. Mixed types fall back to a string comparison rather
+ * than to `NaN`, which is what a `-` on incomparable operands would produce and what would then
+ * make the whole sort order undefined.
+ */
+export const compareSortValues = (a, b, locale) => {
+    if (typeof a === "number" && typeof b === "number")
+        return a - b;
+    if (a instanceof Date && b instanceof Date)
+        return a.getTime() - b.getTime();
+    // `numeric` so "Row 9" precedes "Row 10"; `base` so case and accents do not decide an order the
+    // reader cannot see — equal strings compare 0 and keep their incoming order.
+    return String(a).localeCompare(String(b), locale, { numeric: true, sensitivity: "base" });
+};
+/**
+ * A new array in the requested order. `Array.prototype.sort` is stable by specification, so rows
+ * the comparator calls equal keep the order they arrived in — which is what makes a second sort
+ * on a different column read as a tiebreak rather than as a shuffle.
+ */
+export const sortRows = (rows, column, direction, locale) => {
+    const factor = direction === "asc" ? 1 : -1;
+    return [...rows].sort((a, b) => {
+        const left = sortValue(column, a);
+        const right = sortValue(column, b);
+        // Missing values are pushed to the end in both directions, so this test sits outside the
+        // direction flip rather than inside the comparison it multiplies.
+        const leftMissing = isMissing(left);
+        const rightMissing = isMissing(right);
+        if (leftMissing && rightMissing)
+            return 0;
+        if (leftMissing)
+            return 1;
+        if (rightMissing)
+            return -1;
+        return factor * compareSortValues(left, right, locale);
+    });
+};
+/** What a click on `column`'s header means: flip the column it already sorts, or adopt a new one. */
+export const nextSort = (current, column) => {
+    const flipped = current?.direction === "asc" ? "desc" : "asc";
+    if (current?.key === column.key)
+        return { key: column.key, direction: flipped };
+    // A fresh numeric column opens on its largest value: "top by revenue" is the question a number
+    // column is almost always there to answer.
+    const fallback = column.numeric ? "desc" : "asc";
+    return { key: column.key, direction: column.defaultSortDirection ?? fallback };
+};
+/** The `aria-sort` of a sortable header. Unsortable headers carry no such attribute at all. */
+export const ariaSort = (current, column) => {
+    if (current?.key !== column.key)
+        return "none";
+    return current.direction === "asc" ? "ascending" : "descending";
+};
+/**
+ * Standard competition ranks ("1224") for rows already in display order: rows whose values compare
+ * equal share the rank of the first of them, and the next distinct value skips the places the tie
+ * used up. A missing value gets no rank at all — it sorts last, and "tied for last because nobody
+ * knows" is not a position worth printing.
+ *
+ * The table hands a `cell` snippet the row's position, which is the right number until two rows
+ * tie; a leaderboard that has to say "joint second" needs this instead.
+ */
+export const competitionRanks = (ordered, valueOf, locale) => {
+    const ranks = [];
+    let previous;
+    ordered.forEach((row, index) => {
+        const value = valueOf(row);
+        if (isMissing(value)) {
+            ranks.push(null);
+            return;
+        }
+        const tied = index > 0 && !isMissing(previous) && compareSortValues(previous, value, locale) === 0;
+        ranks.push(tied ? ranks[index - 1] : index + 1);
+        previous = value;
+    });
+    return ranks;
+};
+const SORT_PARAMS = { key: "sort", direction: "dir" };
+/**
+ * Reads a sort out of a URL's search parameters, so a shared link opens on the order its sender was
+ * looking at. Anything missing or unrecognised falls back to `fallback` piece by piece: a link with
+ * only `?sort=year` gets the fallback's direction.
+ */
+export const sortFromParams = (params, fallback, names = SORT_PARAMS) => {
+    const direction = params.get(names.direction);
+    return {
+        key: params.get(names.key) ?? fallback.key,
+        direction: direction === "asc" || direction === "desc" ? direction : fallback.direction,
+    };
+};
+/**
+ * The search parameters that write `sort` back, as updates for `withSearchParams`: a piece equal to
+ * the fallback is `null` — removed — so the URL of a table in its default order stays clean.
+ */
+export const sortToParams = (sort, fallback, names = SORT_PARAMS) => ({
+    [names.key]: sort.key === fallback.key ? null : sort.key,
+    [names.direction]: sort.direction === fallback.direction ? null : sort.direction,
+});

package/dist/table/types.d.ts

@@ -0,0 +1,93 @@
+import type { Snippet } from "svelte";
+import type { ClassValue } from "svelte/elements";
+/**
+ * A value the table knows how to order. `null` and `undefined` both mean "missing" and sort to
+ * the end in either direction — a blank cell is never the answer to "who is first".
+ */
+export type SortValue = string | number | Date | null | undefined;
+export type SortDirection = "asc" | "desc";
+/**
+ * Which column the table is ordered by, and how. Absent means "the order the rows arrived in",
+ * which is a state the table can start in but never returns to: a header toggles between the two
+ * directions rather than cycling through a third, unsorted step.
+ */
+export interface SortState {
+    key: string;
+    direction: SortDirection;
+}
+/**
+ * One column of a {@link Column}-driven table.
+ *
+ * `key` is a plain string rather than `keyof T` on purpose: a ratio, a total, or a pair of fields
+ * rendered as one cell has no field to name, and forcing those to alias a real one would be worse
+ * than losing the check. When `key` does name a field, everything else has a working default —
+ * `{ key: "name", label: "Name" }` reads it, renders it and sorts by it.
+ */
+export interface Column<T> {
+    /** Identifies the column: keys the header, and is the default field accessor. */
+    key: string;
+    label: string;
+    /** Reads the cell's value. Defaults to `row[key]`. */
+    value?: (row: T) => unknown;
+    /** Whether the header sorts. On by default — a column that cannot be ordered opts out. */
+    sortable?: boolean;
+    /**
+     * What to order by, when that is not what the cell shows: a formatted date sorts by the
+     * `Date`, a status badge by its rank. Defaults to {@link Column.value}.
+     */
+    sortBy?: (row: T) => SortValue;
+    /** Direction the first click picks. Defaults to descending for `numeric`, ascending otherwise. */
+    defaultSortDirection?: SortDirection;
+    /** Defaults to `right` for `numeric`, `left` otherwise. */
+    align?: "left" | "center" | "right";
+    /** Renders the column in tabular figures, so digits line up column-wise as the rows change. */
+    numeric?: boolean;
+    /** Extra classes for this column's cells and header. */
+    class?: ClassValue;
+    /**
+     * Whether the reader can take the column off the table from the columns menu. On by default; a
+     * column that the rest of the row makes no sense without — the name a row is about, the rank a
+     * reader counts down — opts out, and the menu lists it without a checkbox.
+     */
+    hideable?: boolean;
+    /**
+     * Starts the column hidden, so a table can carry a detail nobody needs at a glance without
+     * making everyone who does not want it take it away first. Ignored when `hideable` is `false`.
+     */
+    hiddenByDefault?: boolean;
+    /** Whether the header grows a resize handle when the table is `resizable`. On by default. */
+    resizable?: boolean;
+    /** The narrowest a reader can drag the column, in pixels. Defaults to 48. */
+    minWidth?: number;
+    /**
+     * Renders the cell. Without it the cell is `String(value)`, and `null`/`undefined` is an
+     * em dash.
+     *
+     * The second argument is the row's 0-based position in the order currently rendered, which is
+     * what a rank or a medal column follows; it changes with the sort. A snippet declared with only
+     * the row parameter stays assignable and simply ignores it.
+     *
+     * Svelte hoists a template snippet that captures no state to module scope, so a `columns` array
+     * declared with `const` can usually name one — but a snippet that reads `$state` is declared
+     * where it appears in the template, after the instance script has run. Build the array with
+     * `$derived` and the distinction stops mattering.
+     */
+    cell?: Snippet<[T, number]>;
+}
+/**
+ * The part of a table the reader arranges: which columns show, in what order, and how wide the
+ * ones they dragged are. Everything is an override of what the columns declare, so a table whose
+ * columns change — one added by a later release, one that only exists for some data — reads an old
+ * state without losing its own defaults, and an empty state means "as declared".
+ */
+export interface ColumnState {
+    /**
+     * Column keys in the order the reader put them. Keys that no longer name a column are ignored,
+     * and a column missing from the list keeps its declared place next to its declared neighbour.
+     */
+    order: string[];
+    /** Per-key shown or hidden, over the column's own `hiddenByDefault`. */
+    visibility: Record<string, boolean>;
+    /** Widths the reader dragged, in pixels. A column with no entry sizes to its content. */
+    widths: Record<string, number>;
+}

package/dist/table/types.js

@@ -0,0 +1 @@
+export {};