@atmos.build/ui 0.1.0

package/dist/lib/view-query/config.js

@@ -0,0 +1,162 @@
+/** The budget a consumer whose table carries an octet_length CHECK should pass to writeViewConfig. */
+export const MAX_VIEW_CONFIG_BYTES = 16 * 1024;
+export { GROUP_ORDER_ALIASES, toInMemoryGroupOrder, toStoredGroupOrder } from './group-order.js';
+const SYNTHETIC_DEFAULT_SORT_ID = 'default-sort';
+export function readViewConfig(raw, registry, sortFields, display) {
+    const root = asRecord(raw) ?? {};
+    const query = asRecord(root.query) ?? root;
+    const displayRoot = asRecord(root.display) ?? root;
+    return {
+        query: {
+            filter: readFilter(query.filter, registry),
+            sort: readSort(query.sort, sortFields),
+        },
+        display: display.read(displayRoot),
+    };
+}
+export function writeViewConfig(blob, next, display, options) {
+    const owned = new Set(['filter', 'sort', 'query', 'display', ...display.keys]);
+    const rest = Object.entries(asRecord(blob) ?? {}).filter(([key]) => !owned.has(key));
+    const out = {
+        ...Object.fromEntries(rest),
+        query: next.query,
+        display: display.write(next.display),
+    };
+    const maxBytes = options?.maxBytes;
+    if (maxBytes !== undefined) {
+        const bytes = viewConfigByteLength(out);
+        if (bytes > maxBytes) {
+            throw new Error(`view config is ${bytes} bytes, over the ${maxBytes} byte limit`);
+        }
+    }
+    return out;
+}
+const utf8 = new TextEncoder();
+/**
+ * The size Postgres will measure: `octet_length(config::text)` on a jsonb column, which
+ * re-serializes with a space after every `:` and `,` and counts UTF-8 bytes, not UTF-16 units.
+ */
+export function viewConfigByteLength(blob) {
+    return utf8.encode(jsonbText(blob)).length;
+}
+function jsonbText(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => jsonbText(item === undefined ? null : item)).join(', ')}]`;
+    }
+    if (value && typeof value === 'object') {
+        const pairs = Object.entries(value)
+            .filter(([, member]) => member !== undefined && typeof member !== 'function')
+            .map(([key, member]) => `${JSON.stringify(key)}: ${jsonbText(member)}`);
+        return `{${pairs.join(', ')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+function asRecord(raw) {
+    if (typeof raw === 'string') {
+        if (!raw.trim())
+            return null;
+        try {
+            return asRecord(JSON.parse(raw));
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    return raw;
+}
+function emptyFilterTree() {
+    return { id: 'root', node: 'group', conjunction: 'and', children: [] };
+}
+function readFilter(raw, registry) {
+    const node = readNode(raw, registry, 'root');
+    return node?.node === 'group' ? node : emptyFilterTree();
+}
+function readNode(raw, registry, fallbackId) {
+    const node = asRecord(raw);
+    if (!node)
+        return null;
+    const id = typeof node.id === 'string' ? node.id : fallbackId;
+    if (node.node === 'group') {
+        const children = Array.isArray(node.children)
+            ? node.children
+                .map((child, index) => readNode(child, registry, `${fallbackId}.${index}`))
+                .filter((child) => child !== null)
+            : [];
+        return { id, node: 'group', conjunction: node.conjunction === 'or' ? 'or' : 'and', children };
+    }
+    return node.node === 'condition' ? readCondition(node, registry, id) : null;
+}
+function readCondition(node, registry, id) {
+    if (typeof node.field !== 'string')
+        return null;
+    const meta = registry.meta[node.field];
+    if (!meta)
+        return null;
+    const operator = meta.operators.find((declared) => declared === node.operator);
+    if (!operator)
+        return null;
+    const value = readValue(node.value);
+    if (!value)
+        return null;
+    return { id, node: 'condition', field: node.field, operator, value };
+}
+function readValue(raw) {
+    const value = asRecord(raw);
+    if (!value)
+        return null;
+    switch (value.kind) {
+        case 'text':
+            return typeof value.text === 'string' ? { kind: 'text', text: value.text } : null;
+        case 'tokens':
+            return isStringArray(value.tokens) ? { kind: 'tokens', tokens: value.tokens } : null;
+        case 'ids':
+            return isStringArray(value.ids) ? { kind: 'ids', ids: value.ids } : null;
+        case 'number':
+            return isFiniteNumber(value.n) ? { kind: 'number', n: value.n } : null;
+        case 'boolean':
+            return typeof value.value === 'boolean' ? { kind: 'boolean', value: value.value } : null;
+        case 'date':
+            return isNullableIso(value.iso) ? { kind: 'date', iso: value.iso ?? null } : null;
+        case 'date_range':
+            return isNullableIso(value.from) && isNullableIso(value.to)
+                ? { kind: 'date_range', from: value.from ?? null, to: value.to ?? null }
+                : null;
+        case 'relative_days':
+            return isFiniteNumber(value.days) ? { kind: 'relative_days', days: value.days } : null;
+        case 'current_user':
+            return { kind: 'current_user' };
+        case 'empty':
+            return { kind: 'empty' };
+        default:
+            return null;
+    }
+}
+function isStringArray(raw) {
+    return Array.isArray(raw) && raw.every((item) => typeof item === 'string');
+}
+function isFiniteNumber(raw) {
+    return typeof raw === 'number' && Number.isFinite(raw);
+}
+function isNullableIso(raw) {
+    return raw === null || raw === undefined || typeof raw === 'string';
+}
+function readSort(raw, sortFields) {
+    if (!Array.isArray(raw))
+        return [];
+    const sort = [];
+    for (const [index, item] of raw.entries()) {
+        const entry = asRecord(item);
+        if (!entry || typeof entry.field !== 'string' || !sortFields.has(entry.field))
+            continue;
+        sort.push({
+            id: typeof entry.id === 'string' ? entry.id : `s-${index}`,
+            field: entry.field,
+            dir: entry.dir === 'desc' ? 'desc' : 'asc',
+            nulls: entry.nulls === 'first' ? 'first' : entry.nulls === 'last' ? 'last' : undefined,
+        });
+    }
+    const onlyEntry = sort.length === 1 ? sort[0] : undefined;
+    return onlyEntry?.id === SYNTHETIC_DEFAULT_SORT_ID ? [] : sort;
+}

package/dist/lib/view-query/evaluate.d.ts

@@ -0,0 +1,11 @@
+import type { FieldRegistry } from './model.js';
+import { type FilterTree } from './types.js';
+export interface EvalContext {
+    categoryOf?: (id: string) => string | undefined;
+    currentUserId?: string | null;
+    now?: number;
+}
+export interface EvalAdapter<TRow> {
+    valueOf: (row: TRow, field: string) => unknown;
+}
+export declare function evaluateTree<TRow>(row: TRow, tree: FilterTree, registry: FieldRegistry, adapter: EvalAdapter<TRow>, ctx?: EvalContext): boolean;

package/dist/lib/view-query/evaluate.js

@@ -0,0 +1,196 @@
+import { CURRENT_USER_FILTER_ID, } from './types.js';
+const NO_CONTEXT = {};
+export function evaluateTree(row, tree, registry, adapter, ctx = NO_CONTEXT) {
+    return evaluateNode(row, tree, registry, adapter, ctx);
+}
+function evaluateNode(row, node, registry, adapter, ctx) {
+    if (node.node === 'group') {
+        if (node.children.length === 0)
+            return true;
+        const results = node.children.map((child) => evaluateNode(row, child, registry, adapter, ctx));
+        return node.conjunction === 'and' ? results.every(Boolean) : results.some(Boolean);
+    }
+    const meta = registry.meta[node.field];
+    if (!meta)
+        return true;
+    const value = adapter.valueOf(row, node.field);
+    switch (meta.kind) {
+        case 'text':
+            return evalText(value, node.operator, node.value);
+        case 'number':
+            return evalNumber(value, node.operator, node.value);
+        case 'boolean':
+            return evalBoolean(value, node.operator, node.value);
+        case 'date':
+            return evalDate(value, node.operator, node.value, ctx);
+        case 'select':
+            return evalSelect(value, node.operator, node.value, meta, ctx);
+    }
+}
+function evalText(value, op, filter) {
+    const text = typeof value === 'string' ? value : '';
+    if (op === 'is_set')
+        return text.length > 0;
+    if (op === 'is_not_set')
+        return text.length === 0;
+    if (filter.kind !== 'text')
+        return false;
+    const probe = filter.text.trim().toLowerCase();
+    if (!probe)
+        return true;
+    const hay = text.toLowerCase();
+    switch (op) {
+        case 'contains':
+            return hay.includes(probe);
+        case 'starts_with':
+            return hay.startsWith(probe);
+        case 'ends_with':
+            return hay.endsWith(probe);
+        case 'is':
+            return hay === probe;
+        case 'is_not':
+            return hay !== probe;
+        default:
+            return false;
+    }
+}
+function evalNumber(value, op, filter) {
+    const n = typeof value === 'number' ? value : null;
+    if (op === 'is_set')
+        return n != null;
+    if (op === 'is_not_set')
+        return n == null;
+    if (n == null || filter.kind !== 'number')
+        return false;
+    const target = filter.n;
+    switch (op) {
+        case 'eq':
+            return n === target;
+        case 'neq':
+            return n !== target;
+        case 'gt':
+            return n > target;
+        case 'gte':
+            return n >= target;
+        case 'lt':
+            return n < target;
+        case 'lte':
+            return n <= target;
+        default:
+            return false;
+    }
+}
+function evalBoolean(value, op, filter) {
+    const current = typeof value === 'boolean' ? value : null;
+    if (op === 'is_set')
+        return current != null;
+    if (op === 'is_not_set')
+        return current == null;
+    if (current == null || filter.kind !== 'boolean')
+        return false;
+    switch (op) {
+        case 'is':
+            return current === filter.value;
+        case 'is_not':
+            return current !== filter.value;
+        default:
+            return false;
+    }
+}
+function evalDate(value, op, filter, ctx) {
+    if (op === 'is_set')
+        return value != null;
+    if (op === 'is_not_set')
+        return value == null;
+    if (value == null)
+        return false;
+    const ts = typeof value === 'number' ? value : typeof value === 'string' ? Date.parse(value) : NaN;
+    if (Number.isNaN(ts))
+        return false;
+    if (op === 'within_next' || op === 'within_last') {
+        if (filter.kind !== 'relative_days')
+            return false;
+        const now = ctx.now ?? Date.now();
+        const span = filter.days * 86_400_000;
+        return op === 'within_next' ? ts >= now && ts <= now + span : ts <= now && ts >= now - span;
+    }
+    if (op === 'between') {
+        if (filter.kind !== 'date_range')
+            return false;
+        const from = filter.from ? Date.parse(filter.from) : null;
+        const to = filter.to ? Date.parse(filter.to) : null;
+        if (from != null && ts < from)
+            return false;
+        if (to != null && ts > to)
+            return false;
+        return true;
+    }
+    if (filter.kind !== 'date')
+        return false;
+    if (filter.iso == null)
+        return true;
+    const target = Date.parse(filter.iso);
+    switch (op) {
+        case 'before':
+            return ts < target;
+        case 'after':
+            return ts > target;
+        case 'on':
+            return sameUtcDay(ts, target);
+        default:
+            return false;
+    }
+}
+function sameUtcDay(a, b) {
+    const da = new Date(a);
+    const db = new Date(b);
+    return (da.getUTCFullYear() === db.getUTCFullYear() &&
+        da.getUTCMonth() === db.getUTCMonth() &&
+        da.getUTCDate() === db.getUTCDate());
+}
+function evalSelect(value, op, filter, meta, ctx) {
+    const held = heldValues(value, meta.cardinality === 'many');
+    if (op === 'is_set')
+        return held.length > 0;
+    if (op === 'is_not_set')
+        return held.length === 0;
+    const ids = selectedIds(filter, meta, ctx);
+    if (ids == null)
+        return false;
+    if (ids.length === 0)
+        return true;
+    const categoryOf = meta.categoryOf ?? ctx.categoryOf;
+    const matched = held.some((one) => {
+        if (ids.includes(one))
+            return true;
+        const category = categoryOf?.(one);
+        return category != null && ids.includes(category);
+    });
+    switch (op) {
+        case 'is':
+        case 'is_any_of':
+            return matched;
+        case 'is_not':
+        case 'is_none_of':
+            return !matched;
+        default:
+            return false;
+    }
+}
+function heldValues(value, many) {
+    if (many) {
+        return Array.isArray(value) ? value.filter((one) => typeof one === 'string') : [];
+    }
+    return typeof value === 'string' ? [value] : [];
+}
+function selectedIds(filter, meta, ctx) {
+    if (filter.kind === 'current_user')
+        return ctx.currentUserId ? [ctx.currentUserId] : [];
+    if (filter.kind !== 'ids')
+        return null;
+    const alias = meta.aliasId;
+    const resolved = filter.ids
+        .map((id) => (id === CURRENT_USER_FILTER_ID ? ctx.currentUserId : id))
+        .filter((id) => Boolean(id));
+    return alias ? resolved.map(alias) : resolved;
+}

package/dist/lib/view-query/group-order.d.ts

@@ -0,0 +1,25 @@
+export type GroupItemOrder = 'manual' | 'alphabetical' | 'item_count';
+/**
+ * Maps the value persisted on the wire onto the in-memory vocabulary.
+ * Do not delete an entry once added: if a wire value ever reaches storage with
+ * no alias back to its in-memory counterpart, an older bundle that doesn't
+ * recognize it will silently degrade group ordering to `manual`.
+ */
+export declare const GROUP_ORDER_ALIASES: Readonly<Record<string, string>>;
+export declare function toInMemoryGroupOrder(stored: string): string;
+export declare function toStoredGroupOrder(inMemory: string): string;
+export interface OrderableGroup {
+    key: string;
+    rows: readonly unknown[];
+}
+export interface GroupOrderDisplay {
+    groupItemOrder: GroupItemOrder;
+    groupOrderIds: readonly string[];
+}
+export interface GroupVisibilityDisplay {
+    groupBy: string;
+    hideEmptyGroups: boolean;
+    hiddenGroupIds: readonly string[];
+}
+export declare function applyGroupOrder<TGroup extends OrderableGroup>(groups: TGroup[], display: GroupOrderDisplay, labelOf: (group: TGroup) => string): TGroup[];
+export declare function applyGroupDisplay<TGroup extends OrderableGroup>(groups: TGroup[], display: GroupVisibilityDisplay): TGroup[];

package/dist/lib/view-query/group-order.js

@@ -0,0 +1,49 @@
+/**
+ * Maps the value persisted on the wire onto the in-memory vocabulary.
+ * Do not delete an entry once added: if a wire value ever reaches storage with
+ * no alias back to its in-memory counterpart, an older bundle that doesn't
+ * recognize it will silently degrade group ordering to `manual`.
+ */
+export const GROUP_ORDER_ALIASES = { task_count: 'item_count' };
+const STORED_GROUP_ORDERS = Object.fromEntries(Object.entries(GROUP_ORDER_ALIASES).map(([stored, inMemory]) => [inMemory, stored]));
+export function toInMemoryGroupOrder(stored) {
+    return GROUP_ORDER_ALIASES[stored] ?? stored;
+}
+export function toStoredGroupOrder(inMemory) {
+    return STORED_GROUP_ORDERS[inMemory] ?? inMemory;
+}
+export function applyGroupOrder(groups, display, labelOf) {
+    switch (display.groupItemOrder) {
+        case 'alphabetical':
+            return [...groups].sort((a, b) => labelOf(a).localeCompare(labelOf(b)));
+        case 'item_count':
+            return [...groups].sort((a, b) => b.rows.length - a.rows.length || labelOf(a).localeCompare(labelOf(b)));
+        default:
+            return orderByIds(groups, display.groupOrderIds);
+    }
+}
+export function applyGroupDisplay(groups, display) {
+    if (display.groupBy === 'none')
+        return groups;
+    const hidden = new Set(display.hiddenGroupIds);
+    return groups.filter((group) => {
+        if (hidden.has(group.key))
+            return false;
+        return !display.hideEmptyGroups || group.rows.length > 0;
+    });
+}
+function orderByIds(groups, ids) {
+    if (ids.length === 0)
+        return groups;
+    const byId = new Map(groups.map((group) => [group.key, group]));
+    const seen = new Set();
+    const ordered = [];
+    for (const id of ids) {
+        const group = byId.get(id);
+        if (!group || seen.has(id))
+            continue;
+        ordered.push(group);
+        seen.add(id);
+    }
+    return [...ordered, ...groups.filter((group) => !seen.has(group.key))];
+}

package/dist/lib/view-query/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './model.js';
+export * from './config.js';
+export * from './group-order.js';
+export * from './evaluate.js';
+export * from './sort.js';

package/dist/lib/view-query/index.js

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './model.js';
+export * from './config.js';
+export * from './group-order.js';
+export * from './evaluate.js';
+export * from './sort.js';

package/dist/lib/view-query/model.d.ts

@@ -0,0 +1,34 @@
+import { type Conjunction, type FieldKind, type FilterCondition, type FilterGroup, type FilterNode, type FilterOp, type FilterTree, type FilterValue } from './types.js';
+export interface ViewQueryFieldMeta {
+    field: string;
+    operators: FilterOp[];
+    defaultOperator: FilterOp;
+    kind: FieldKind;
+    defaultNumber?: number;
+    /** Multi-valued fields (assignee) match if ANY value satisfies the condition. */
+    cardinality?: 'one' | 'many';
+    /** Maps a stored id onto the row's actual value, for aliased columns. */
+    aliasId?: (id: string) => string;
+    /** Lazily resolved option source, so a consumer can supply late-bound select options. */
+    selectOptions?: () => readonly {
+        id: string;
+        label: string;
+    }[];
+    /** Explicit category resolver, modelled on the evaluator's EvalContext.categoryOf. */
+    categoryOf?: (id: string) => string | undefined;
+}
+export interface FieldRegistry<TMeta extends ViewQueryFieldMeta = ViewQueryFieldMeta> {
+    order: string[];
+    meta: Record<string, TMeta>;
+}
+export declare function defaultValueFor(meta: ViewQueryFieldMeta, op: FilterOp): FilterValue;
+export declare function newCondition<TMeta extends ViewQueryFieldMeta>(registry: FieldRegistry<TMeta>, field: string): FilterCondition;
+export declare function newGroup(conjunction?: Conjunction): FilterGroup;
+export declare function updateNode(tree: FilterTree, id: string, fn: (node: FilterNode) => FilterNode): FilterTree;
+export declare function removeNode(tree: FilterTree, id: string): FilterTree;
+export declare function addChild(tree: FilterTree, groupId: string, child: FilterNode): FilterTree;
+export declare function wrapInGroup(tree: FilterTree, id: string, conjunction?: Conjunction): FilterTree;
+export declare function topLevelConditions(tree: FilterTree): FilterCondition[];
+export declare function topLevelGroups(tree: FilterTree): FilterGroup[];
+export declare function conditionCount(node: FilterNode): number;
+export declare function isAdvanced(tree: FilterTree): boolean;

package/dist/lib/view-query/model.js

@@ -0,0 +1,88 @@
+// `{ kind: 'current_user' }` (FilterValue) and CURRENT_USER_FILTER_ID (a sentinel
+// field id) are two mechanisms for the same "current user" idea; unifying them is
+// an objects-table data migration and is deferred.
+import { nodeId, } from './types.js';
+export function defaultValueFor(meta, op) {
+    if (op === 'is_set' || op === 'is_not_set')
+        return { kind: 'empty' };
+    if (op === 'within_next' || op === 'within_last')
+        return { kind: 'relative_days', days: 7 };
+    switch (meta.kind) {
+        case 'text':
+            return op === 'is_any_of' || op === 'is_none_of'
+                ? { kind: 'tokens', tokens: [] }
+                : { kind: 'text', text: '' };
+        case 'select':
+            return { kind: 'ids', ids: [] };
+        case 'number':
+            return { kind: 'number', n: meta.defaultNumber ?? 3 };
+        case 'date':
+            return op === 'between'
+                ? { kind: 'date_range', from: null, to: null }
+                : { kind: 'date', iso: null };
+        case 'boolean':
+            return { kind: 'boolean', value: true };
+    }
+}
+export function newCondition(registry, field) {
+    const meta = registry.meta[field];
+    if (!meta)
+        throw new Error(`newCondition: unknown field "${field}"`);
+    const operator = meta.defaultOperator;
+    return {
+        id: nodeId('c'),
+        node: 'condition',
+        field,
+        operator,
+        value: defaultValueFor(meta, operator),
+    };
+}
+export function newGroup(conjunction = 'and') {
+    return { id: nodeId('g'), node: 'group', conjunction, children: [] };
+}
+export function updateNode(tree, id, fn) {
+    return mapNode(tree, id, fn);
+}
+function mapNode(node, id, fn) {
+    if (node.id === id)
+        return fn(node);
+    if (node.node === 'group') {
+        return { ...node, children: node.children.map((child) => mapNode(child, id, fn)) };
+    }
+    return node;
+}
+export function removeNode(tree, id) {
+    return pruneChildren(tree, id);
+}
+function pruneChildren(node, id) {
+    if (node.node !== 'group')
+        return node;
+    return {
+        ...node,
+        children: node.children
+            .filter((child) => child.id !== id)
+            .map((child) => pruneChildren(child, id)),
+    };
+}
+export function addChild(tree, groupId, child) {
+    return updateNode(tree, groupId, (node) => node.node === 'group' ? { ...node, children: [...node.children, child] } : node);
+}
+export function wrapInGroup(tree, id, conjunction = 'or') {
+    if (id === tree.id)
+        return tree;
+    return updateNode(tree, id, (node) => ({ ...newGroup(conjunction), children: [node] }));
+}
+export function topLevelConditions(tree) {
+    return tree.children.filter((node) => node.node === 'condition');
+}
+export function topLevelGroups(tree) {
+    return tree.children.filter((node) => node.node === 'group');
+}
+export function conditionCount(node) {
+    if (node.node === 'condition')
+        return 1;
+    return node.children.reduce((sum, child) => sum + conditionCount(child), 0);
+}
+export function isAdvanced(tree) {
+    return tree.children.some((node) => node.node === 'group') || tree.conjunction === 'or';
+}

package/dist/lib/view-query/sort.d.ts

@@ -0,0 +1,7 @@
+import type { ViewSort } from './types.js';
+export type SortValue = string | number | null | undefined;
+export interface SortAdapter<T> {
+    valueOf: (row: T, field: string) => SortValue;
+    tieBreak?: (a: T, b: T) => number;
+}
+export declare function sortRows<T>(rows: readonly T[], sort: ViewSort, adapter: SortAdapter<T>): T[];

package/dist/lib/view-query/sort.js

@@ -0,0 +1,30 @@
+const collator = new Intl.Collator(undefined, { sensitivity: 'base', numeric: true });
+function compareOne(a, b, spec, adapter) {
+    const av = adapter.valueOf(a, spec.field);
+    const bv = adapter.valueOf(b, spec.field);
+    const nullsLast = (spec.nulls ?? 'last') === 'last';
+    if (av == null && bv == null)
+        return 0;
+    if (av == null)
+        return nullsLast ? 1 : -1;
+    if (bv == null)
+        return nullsLast ? -1 : 1;
+    const cmp = typeof av === 'string' && typeof bv === 'string'
+        ? collator.compare(av, bv)
+        : Number(av) - Number(bv);
+    return spec.dir === 'asc' ? cmp : -cmp;
+}
+export function sortRows(rows, sort, adapter) {
+    if (sort.length === 0)
+        return rows;
+    const copy = [...rows];
+    copy.sort((a, b) => {
+        for (const spec of sort) {
+            const cmp = compareOne(a, b, spec, adapter);
+            if (cmp !== 0)
+                return cmp;
+        }
+        return adapter.tieBreak?.(a, b) ?? 0;
+    });
+    return copy;
+}