utils.ts · Source

utils.tsapps/web/src/lib/utils.tsraw ← lib4,858 B← Back to the app
1import { clsx, type ClassValue } from "clsx";
2import { twMerge } from "tailwind-merge";
3import { formatDistanceToNowStrict, parseISO } from "date-fns";
4import {
5  afterPosition,
6  beforePosition,
7  betweenPosition,
8  comparePositions,
9  positionForSlotNeighbors,
10  type Position,
11} from "@factory/shared/positions";
12 
13/** Merge Tailwind class lists, resolving conflicts (shadcn/ui convention). */
14export function cn(...inputs: ClassValue[]): string {
15  return twMerge(clsx(inputs));
16}
17 
18/** "2h ago" style relative timestamp; degrades gracefully on bad input. */
19export function formatRelativeTime(iso: string | Date): string {
20  try {
21    const date = typeof iso === "string" ? parseISO(iso) : iso;
22    if (Number.isNaN(date.getTime())) return "";
23    // date-fns v3 (the pinned major) has no `now` option — "now" is the
24    // process clock. (The v4-style `now` param was dead: no caller passed
25    // it, and it type-checked against a type that doesn't exist here.)
26    const dist = formatDistanceToNowStrict(date, { addSuffix: true });
27    const [head, ...rest] = dist.split(" ");
28    if (!head || head.length === 0) return dist;
29    return `${head.charAt(0).toUpperCase()}${head.slice(1)} ${rest.join(" ")}`.trim();
30  } catch {
31    return "";
32  }
33}
34 
35/** Truncate to `max` chars, appending an ellipsis when text was cut. */
36export function truncate(text: string, max = 80): string {
37  if (max <= 0) return "";
38  if (text.length <= max) return text;
39  return `${text.slice(0, max - 1).trimEnd()}…`;
40}
41 
42/**
43 * Comparator for fractional (LexoRank-style) positions with a null tolerance:
44 * the shared `comparePositions` owns the lexicographic rule, and a
45 * `null`/`undefined` position sorts LAST so a partial position update never
46 * jumps a row to the top of the list.
47 */
48export function comparePositionStrings(
49  a: string | undefined | null,
50  b: string | undefined | null,
51): number {
52  if (a == null && b == null) return 0;
53  if (a == null) return 1;
54  if (b == null) return -1;
55  return comparePositions(a, b);
56}
57 
58/**
59 * Sort a list of items by fractional `position` (stable for equal keys).
60 * Accepts the raw string form so callers don't import the shared type.
61 */
62export function sortByPosition<T extends { position?: string | null }>(items: readonly T[]): T[] {
63  return [...items].sort((a, b) => comparePositionStrings(a.position ?? null, b.position ?? null));
64}
65 
66/* --------------------------------------------------------------------- *
67 * Fractional-position helpers — thin, null-tolerant wrappers over the
68 * canonical engine in `@factory/shared/positions` (single source of truth,
69 * property-tested there). The UI layer never re-implements the algorithm.
70 * --------------------------------------------------------------------- */
71 
72/**
73 * Midpoint position strictly between two positions (`a < b`). Delegates to
74 * the shared `betweenPosition`. Throws when the two positions are adjacent
75 * with no room (empty gap) — the sibling list needs a server-side rebalance.
76 */
77export function between(a: Position, b: Position): Position {
78  return betweenPosition(a, b);
79}
80 
81/**
82 * Insert a new row's position between its neighbors (or append/prepend).
83 * `before` is the preceding sibling, `after` the following sibling. Delegates
84 * to the shared `positionForSlotNeighbors`; throws on an empty gap (rebalance
85 * required) rather than emitting a mis-ordered position.
86 */
87export function positionForInsert(
88  before: string | null | undefined,
89  after: string | null | undefined,
90): Position {
91  if (!before && !after) return "a0"; // first sibling of a new list
92  return positionForSlotNeighbors(before ?? null, after ?? null);
93}
94 
95/**
96 * Position strictly smaller than `p` (for "insert above"). Delegates to the
97 * shared `beforePosition`. At the very bottom of the range (`"0"`) there is no
98 * smaller position — fall back to `p` itself so callers never crash.
99 */
100export function positionBefore(p: Position): Position {
101  try {
102    return beforePosition(p);
103  } catch {
104    return p;
105  }
106}
107 
108/**
109 * Position strictly greater than `p` (for "append after"). Delegates to the
110 * shared `afterPosition` (appends the alphabet midpoint `'i'`, keeping maximal
111 * headroom below).
112 */
113export function positionAfter(p: Position): Position {
114  return afterPosition(p);
115}
116 
117/** Fuzzy-ish subsequence match used by the command palette & slash menu. */
118export function fuzzyMatch(needle: string, haystack: string): boolean {
119  const n = needle.trim().toLowerCase();
120  const h = haystack.toLowerCase();
121  if (!n) return true;
122  if (h.includes(n)) return true;
123  let i = 0;
124  for (const ch of h) {
125    if (ch === n[i]) i += 1;
126    if (i === n.length) return true;
127  }
128  return false;
129}
130 
131/** Clamp helper for presence/pagination math. */
132export function clamp(n: number, min: number, max: number): number {
133  return Math.min(max, Math.max(min, n));
134}
135