@flamingo-stack/openframe-frontend-core 0.0.591 → 0.0.592-snapshot.20260905013229

package/dist/utils/search-params.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/search-params.ts"],"names":[],"mappings":"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","file":"search-params.cjs","sourcesContent":["/**\n * URL parameter schema engine — the ONE grammar for every URL/API integer,\n * the ONE omission rule, the ONE serializer.\n *\n * Hoisted out of `hooks/state/` so SERVER code (route handlers, DALs) and the\n * CLIENT hook parse the same URL with the same function: a param contract that\n * disagrees across the wire is the bug class this removes. JSX-free leaf with\n * its own `exports` subpath; `hooks/state/*` re-exports every name it used to own.\n */\n\n/** JavaScript types a URL parameter can carry. `int` is a whole number with a floor. */\nexport type JSType = 'string' | 'number' | 'int' | 'boolean' | 'array' | 'object';\n\n// ── The integer grammar ─────────────────────────────────────────────────────\n\nexport interface PositiveIntOptions {\n  /** Smallest accepted value (default 1). Anything below falls back. */\n  min?: number;\n  /** Largest accepted value. Applied to the PARSED value AND to the fallback. */\n  max?: number;\n}\n\n/**\n * THE integer grammar for URL params, env vars, and page sizes.\n *\n * `null`/`undefined`/`''` → fallback. Otherwise `Math.trunc(Number(raw))`, which\n * accepts `'12'`, `12`, `'12.9'` (→ 12) and `'0x10'` (→ 16), and rejects `'12abc'`\n * and `'abc'` (`NaN`) — the historical `parseInt` accepted `'12abc'` as 12 and\n * produced `NaN` for `'abc'`. A value below `min` falls back. The RESULT (parsed\n * value or fallback alike) is clamped to `max`, so \"never exceeds max\" has one owner.\n */\nexport function positiveInt<TFallback = number>(\n  raw: string | number | null | undefined,\n  fallback: TFallback,\n  { min = 1, max }: PositiveIntOptions = {},\n): number | TFallback {\n  // The fallback is returned AS GIVEN — capping only ever applies to a value\n  // parsed out of the input, so a caller with no default (`null`) gets its\n  // sentinel back untouched instead of `Math.min(null, max)`.\n  const capped = (v: number) => (max == null ? v : Math.min(v, max));\n  if (raw === null || raw === undefined || raw === '') {\n    return typeof fallback === 'number' ? (capped(fallback) as number | TFallback) : fallback;\n  }\n  const n = Math.trunc(Number(raw));\n  if (!Number.isFinite(n) || n < min) {\n    return typeof fallback === 'number' ? (capped(fallback) as number | TFallback) : fallback;\n  }\n  return capped(n);\n}\n\n/** Ceilings every paged surface shares. */\nexport const PAGE_PARAM_LIMITS = { maxPage: 10_000, maxPageSize: 100 } as const;\n\n/** Total pages for a row count. Floors at 1, so an empty result is still \"page 1 of 1\". */\nexport function pageCount(total: number, pageSize: number): number {\n  if (!Number.isFinite(total) || !Number.isFinite(pageSize) || pageSize <= 0) return 1;\n  return Math.max(1, Math.ceil(total / pageSize));\n}\n\n/** Clamp a requested page into `1..totalPages`. */\nexport function clampPageToTotal(page: number, totalPages: number): number {\n  return Math.min(page, Math.max(1, totalPages));\n}\n\n// ── Schema ──────────────────────────────────────────────────────────────────\n\ntype OutputTypeMap = {\n  string: string;\n  number: number;\n  int: number;\n  boolean: boolean;\n  array: string[];\n  object: Record<string, unknown>;\n};\n\nexport type OutputTypeForJSType<T extends JSType> = OutputTypeMap[T];\n\nexport interface BaseParamConfig<T extends JSType = JSType> {\n  type: T;\n  default?: OutputTypeMap[T];\n  required?: boolean;\n}\n\n/** An integer parameter with an optional floor and ceiling. */\nexport interface IntParamConfig extends BaseParamConfig<'int'> {\n  min?: number;\n  max?: number;\n}\n\nexport type ParamConfig<T extends JSType = JSType> = T extends 'int' ? IntParamConfig : BaseParamConfig<T>;\n\nexport type ParamSchema = Record<string, ParamConfig>;\n\n/** Identity helper that preserves literal types through a schema object. */\nexport function defineParamSchema<T extends ParamSchema>(schema: T): T {\n  return schema;\n}\n\n/**\n * Build a `Record<K, V>` from a key tuple. Keeps `keyof` EXACT when spreading a\n * shared config across derived keys (an inline `Object.fromEntries` widens to\n * `Record<string, V>` and loses the key union).\n */\nexport function fromKeys<K extends string, V>(keys: readonly K[], value: V): Record<K, V> {\n  return Object.fromEntries(keys.map(k => [k, value])) as Record<K, V>;\n}\n\n// ── Reading ─────────────────────────────────────────────────────────────────\n\n/** Anything a URL can be read from: `URLSearchParams`, Next's `searchParams`, or a plain record. */\nexport type ParamInput = URLSearchParams | Record<string, string | string[] | undefined> | null | undefined;\n\n/** THE first-value rule for a duplicated key (`?a=1&a=2` reads as `1`). */\nexport function firstParamValue(input: ParamInput, key: string): string | undefined {\n  if (!input) return undefined;\n  if (input instanceof URLSearchParams) return input.get(key) ?? undefined;\n  const value = input[key];\n  return Array.isArray(value) ? value[0] : value;\n}\n\n/** Every value for a key (arrays read repeated params, then a `,`-joined single value). */\nfunction allParamValues(input: ParamInput, key: string): string[] {\n  if (!input) return [];\n  const raw = input instanceof URLSearchParams ? input.getAll(key) : input[key];\n  const list = Array.isArray(raw) ? raw : raw === undefined ? [] : [raw];\n  if (list.length === 1 && list[0]?.includes(',')) return list[0].split(',').filter(Boolean);\n  return list.filter(v => v !== undefined && v !== '');\n}\n\nexport interface ParseSchemaOptions {\n  /**\n   * What an ABSENT scalar with no declared `default` resolves to.\n   * `'undefined'` (default) keeps today's behaviour; `'null'` is the explicit\n   * \"this filter is unset\" spelling that survives JSON and `URLSearchParams`.\n   */\n  absent?: 'undefined' | 'null';\n}\n\nexport type AbsentValue<Opts extends ParseSchemaOptions | undefined> = Opts extends { absent: 'null' }\n  ? null\n  : undefined;\n\n/**\n * The parsed shape of a schema: keys with a `default` and every array key are\n * non-nullable; an undefaulted scalar carries the caller's absent value.\n */\nexport type InferParsedParams<TSchema extends ParamSchema, Absent = undefined> = {\n  [K in keyof TSchema]: TSchema[K] extends { type: 'array' }\n    ? string[]\n    : TSchema[K] extends { default: infer D }\n      ? D\n      : TSchema[K]['type'] extends infer T\n        ? T extends JSType\n          ? OutputTypeForJSType<T> | Absent\n          : never\n        : never;\n};\n\nfunction coerceScalar(raw: string | undefined, config: ParamConfig): unknown {\n  if (raw === undefined || raw === '') return undefined;\n  switch (config.type) {\n    case 'int': {\n      const int = config as IntParamConfig;\n      // ONE integer grammar, default or not. Without a declared default the\n      // fallback is `undefined` (an unparseable value is absent), which\n      // `positiveInt` returns untouched — the branch used to open-code the\n      // truncation, the min floor and the max clamp a second time.\n      return positiveInt<undefined>(raw, int.default as undefined, { min: int.min, max: int.max });\n    }\n    case 'number': {\n      const n = Number(raw);\n      return Number.isFinite(n) ? n : undefined;\n    }\n    case 'boolean':\n      return raw === 'true' || raw === '1';\n    case 'object':\n      try {\n        return JSON.parse(raw) as Record<string, unknown>;\n      } catch {\n        return undefined;\n      }\n    default:\n      return raw;\n  }\n}\n\n/**\n * Parse a URL into a schema's shape. THE reader — the server route and the\n * client hook both call this, so a URL means exactly one thing.\n *\n * PRECEDENCE: an absent or empty SCALAR takes the declared `default` when there\n * is one, else the `absent` value. ARRAY keys never take `absent`: they are `[]`.\n */\nexport function parseSchemaParams<TSchema extends ParamSchema, Opts extends ParseSchemaOptions = Record<string, never>>(\n  schema: TSchema,\n  input: ParamInput,\n  options?: Opts,\n): InferParsedParams<TSchema, AbsentValue<Opts>> {\n  const absent = options?.absent === 'null' ? null : undefined;\n  const out: Record<string, unknown> = {};\n  for (const [key, config] of Object.entries(schema)) {\n    if (config.type === 'array') {\n      const values = allParamValues(input, key);\n      out[key] = values.length > 0 ? values : ((config.default as string[] | undefined) ?? []);\n      continue;\n    }\n    const coerced = coerceScalar(firstParamValue(input, key), config);\n    out[key] = coerced !== undefined ? coerced : (config.default ?? absent);\n  }\n  return out as InferParsedParams<TSchema, AbsentValue<Opts>>;\n}\n\n// ── Writing ─────────────────────────────────────────────────────────────────\n\n/**\n * A schema entry OR a legacy flattened param (which spells its default\n * `defaultValue`).\n *\n * A UNION, not a bag of two optional fields: with only `default?` and\n * `defaultValue?` this is a WEAK TYPE, and TypeScript rejects any argument\n * sharing neither — including `{ type: 'string' }`, the single most common\n * schema entry there is. Naming the real config shapes fixes that without an\n * index signature, which `FlattenedParam` (an interface) could never satisfy.\n */\ntype OmissionConfig = ParamConfig | { default?: unknown; defaultValue?: unknown };\n\n/**\n * THE omission rule: `null`, `undefined`, `''`, `[]`, and a value equal to the\n * declared default are left out, so a URL only ever carries what differs.\n */\nexport function shouldIncludeInUrl(value: unknown, config: OmissionConfig | undefined): boolean {\n  if (value === null || value === undefined) return false;\n  if (Array.isArray(value) && value.length === 0) return false;\n  if (value === '') return false;\n  // `in` narrowing rather than a cast: the union's members genuinely differ —\n  // a schema entry spells its default `default`, a flattened param spells it\n  // `defaultValue`, and neither is obliged to carry the other's field.\n  const fromDefault = config && 'default' in config ? config.default : undefined;\n  const fromLegacy = config && 'defaultValue' in config ? config.defaultValue : undefined;\n  const declared = fromDefault !== undefined ? fromDefault : fromLegacy;\n  if (declared !== undefined && value === declared) return false;\n  return true;\n}\n\nexport interface CreateSearchParamsOptions {\n  /** Join arrays with this separator instead of repeating the key (`;` for the hub's list APIs). */\n  arrayJoin?: string;\n}\n\n/** Build `URLSearchParams` from a value record (arrays repeat the key by default). */\nexport function createSearchParams(\n  params: Record<string, unknown>,\n  { arrayJoin }: CreateSearchParamsOptions = {},\n): URLSearchParams {\n  const search = new URLSearchParams();\n  for (const [key, value] of Object.entries(params)) {\n    // The emptiness half of the omission rule has ONE owner. (No config here:\n    // callers that must also drop schema DEFAULTS filter through\n    // `shouldIncludeInUrl` with the config first — see `serializeSchemaParams`.)\n    if (!shouldIncludeInUrl(value, undefined)) continue;\n    if (Array.isArray(value)) {\n      // Empty ELEMENTS are dropped, and an array that filters to nothing is\n      // absent (a cleared multi-select must not leave `?tags=` behind).\n      const items = value.filter(v => v !== null && v !== undefined && v !== '');\n      if (items.length === 0) continue;\n      if (arrayJoin) search.set(key, items.join(arrayJoin));\n      else for (const item of items) search.append(key, String(item));\n      continue;\n    }\n    if (typeof value === 'object') {\n      search.set(key, JSON.stringify(value));\n      continue;\n    }\n    search.set(key, String(value));\n  }\n  return search;\n}\n\n/** Serialize params to a query string, omitting everything `shouldIncludeInUrl` rejects. */\nexport function serializeSchemaParams<TSchema extends ParamSchema>(\n  schema: TSchema,\n  params: Record<string, unknown>,\n  options?: CreateSearchParamsOptions,\n): string {\n  const kept: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(params)) {\n    if (shouldIncludeInUrl(value, schema[key])) kept[key] = value;\n  }\n  return createSearchParams(kept, options).toString();\n}\n\n/** Append a query string to a path, or return the path unchanged when it is empty. */\nexport function withQuery(path: string, queryString: string | null | undefined): string {\n  return queryString ? `${path}?${queryString}` : path;\n}\n"]}
+{"version":3,"sources":["../../src/utils/search-params.ts"],"names":[],"mappings":";;;AA+BO,SAAS,WAAA,CACd,KACA,QAAA,EACA,EAAE,MAAM,CAAA,EAAG,GAAA,EAAI,GAAwB,EAAC,EACpB;AAIpB,EAAA,MAAM,MAAA,GAAS,CAAC,CAAA,KAAe,GAAA,IAAO,OAAO,CAAA,GAAI,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,GAAG,CAAA;AAChE,EAAA,IAAI,GAAA,KAAQ,IAAA,IAAQ,GAAA,KAAQ,MAAA,IAAa,QAAQ,EAAA,EAAI;AACnD,IAAA,OAAO,OAAO,QAAA,KAAa,QAAA,GAAW,MAAA,CAAO,QAAQ,CAAA,GAAI,QAAA;AAAA,EAC3D;AACA,EAAA,MAAM,CAAA,GAAI,IAAA,CAAK,KAAA,CAAM,MAAA,CAAO,GAAG,CAAC,CAAA;AAChC,EAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,CAAC,CAAA,IAAK,IAAI,GAAA,EAAK;AAClC,IAAA,OAAO,OAAO,QAAA,KAAa,QAAA,GAAW,MAAA,CAAO,QAAQ,CAAA,GAAI,QAAA;AAAA,EAC3D;AACA,EAAA,OAAO,OAAO,CAAC,CAAA;AACjB;AAGO,IAAM,iBAAA,GAAoB,EAAE,OAAA,EAAS,GAAA,EAAQ,aAAa,GAAA;AAG1D,SAAS,SAAA,CAAU,OAAe,QAAA,EAA0B;AACjE,EAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,KAAK,CAAA,IAAK,CAAC,MAAA,CAAO,QAAA,CAAS,QAAQ,CAAA,IAAK,QAAA,IAAY,CAAA,EAAG,OAAO,CAAA;AACnF,EAAA,OAAO,KAAK,GAAA,CAAI,CAAA,EAAG,KAAK,IAAA,CAAK,KAAA,GAAQ,QAAQ,CAAC,CAAA;AAChD;AAGO,SAAS,gBAAA,CAAiB,MAAc,UAAA,EAA4B;AACzE,EAAA,OAAO,KAAK,GAAA,CAAI,IAAA,EAAM,KAAK,GAAA,CAAI,CAAA,EAAG,UAAU,CAAC,CAAA;AAC/C;AAgCO,SAAS,kBAAyC,MAAA,EAAc;AACrE,EAAA,OAAO,MAAA;AACT;AAOO,SAAS,QAAA,CAA8B,MAAoB,KAAA,EAAwB;AACxF,EAAA,OAAO,MAAA,CAAO,YAAY,IAAA,CAAK,GAAA,CAAI,OAAK,CAAC,CAAA,EAAG,KAAK,CAAC,CAAC,CAAA;AACrD;AAQO,SAAS,eAAA,CAAgB,OAAmB,GAAA,EAAiC;AAClF,EAAA,IAAI,CAAC,OAAO,OAAO,MAAA;AACnB,EAAA,IAAI,iBAAiB,eAAA,EAAiB,OAAO,KAAA,CAAM,GAAA,CAAI,GAAG,CAAA,IAAK,MAAA;AAC/D,EAAA,MAAM,KAAA,GAAQ,MAAM,GAAG,CAAA;AACvB,EAAA,OAAO,MAAM,OAAA,CAAQ,KAAK,CAAA,GAAI,KAAA,CAAM,CAAC,CAAA,GAAI,KAAA;AAC3C;AAGA,SAAS,cAAA,CAAe,OAAmB,GAAA,EAAuB;AAChE,EAAA,IAAI,CAAC,KAAA,EAAO,OAAO,EAAC;AACpB,EAAA,MAAM,GAAA,GAAM,iBAAiB,eAAA,GAAkB,KAAA,CAAM,OAAO,GAAG,CAAA,GAAI,MAAM,GAAG,CAAA;AAC5E,EAAA,MAAM,IAAA,GAAO,KAAA,CAAM,OAAA,CAAQ,GAAG,CAAA,GAAI,GAAA,GAAM,GAAA,KAAQ,MAAA,GAAY,EAAC,GAAI,CAAC,GAAG,CAAA;AACrE,EAAA,IAAI,KAAK,MAAA,KAAW,CAAA,IAAK,IAAA,CAAK,CAAC,GAAG,QAAA,CAAS,GAAG,CAAA,EAAG,OAAO,KAAK,CAAC,CAAA,CAAE,MAAM,GAAG,CAAA,CAAE,OAAO,OAAO,CAAA;AACzF,EAAA,OAAO,KAAK,MAAA,CAAO,CAAA,CAAA,KAAK,CAAA,KAAM,MAAA,IAAa,MAAM,EAAE,CAAA;AACrD;AA+BA,SAAS,YAAA,CAAa,KAAyB,MAAA,EAA8B;AAC3E,EAAA,IAAI,GAAA,KAAQ,MAAA,IAAa,GAAA,KAAQ,EAAA,EAAI,OAAO,MAAA;AAC5C,EAAA,QAAQ,OAAO,IAAA;AAAM,IACnB,KAAK,KAAA,EAAO;AACV,MAAA,MAAM,GAAA,GAAM,MAAA;AAKZ,MAAA,OAAO,WAAA,CAAuB,GAAA,EAAK,GAAA,CAAI,OAAA,EAAsB,EAAE,GAAA,EAAK,GAAA,CAAI,GAAA,EAAK,GAAA,EAAK,GAAA,CAAI,GAAA,EAAK,CAAA;AAAA,IAC7F;AAAA,IACA,KAAK,QAAA,EAAU;AACb,MAAA,MAAM,CAAA,GAAI,OAAO,GAAG,CAAA;AACpB,MAAA,OAAO,MAAA,CAAO,QAAA,CAAS,CAAC,CAAA,GAAI,CAAA,GAAI,MAAA;AAAA,IAClC;AAAA,IACA,KAAK,SAAA;AACH,MAAA,OAAO,GAAA,KAAQ,UAAU,GAAA,KAAQ,GAAA;AAAA,IACnC,KAAK,QAAA;AACH,MAAA,IAAI;AACF,QAAA,OAAO,IAAA,CAAK,MAAM,GAAG,CAAA;AAAA,MACvB,CAAA,CAAA,MAAQ;AACN,QAAA,OAAO,MAAA;AAAA,MACT;AAAA,IACF;AACE,MAAA,OAAO,GAAA;AAAA;AAEb;AASO,SAAS,iBAAA,CACd,MAAA,EACA,KAAA,EACA,OAAA,EAC+C;AAC/C,EAAA,MAAM,MAAA,GAAS,OAAA,EAAS,MAAA,KAAW,MAAA,GAAS,IAAA,GAAO,MAAA;AACnD,EAAA,MAAM,MAA+B,EAAC;AACtC,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,MAAM,KAAK,MAAA,CAAO,OAAA,CAAQ,MAAM,CAAA,EAAG;AAClD,IAAA,IAAI,MAAA,CAAO,SAAS,OAAA,EAAS;AAC3B,MAAA,MAAM,MAAA,GAAS,cAAA,CAAe,KAAA,EAAO,GAAG,CAAA;AACxC,MAAA,GAAA,CAAI,GAAG,IAAI,MAAA,CAAO,MAAA,GAAS,IAAI,MAAA,GAAU,MAAA,CAAO,WAAW,EAAC;AAC5D,MAAA;AAAA,IACF;AACA,IAAA,MAAM,UAAU,YAAA,CAAa,eAAA,CAAgB,KAAA,EAAO,GAAG,GAAG,MAAM,CAAA;AAChE,IAAA,GAAA,CAAI,GAAG,CAAA,GAAI,OAAA,KAAY,MAAA,GAAY,OAAA,GAAW,OAAO,OAAA,IAAW,MAAA;AAAA,EAClE;AACA,EAAA,OAAO,GAAA;AACT;AAoBO,SAAS,kBAAA,CAAmB,OAAgB,MAAA,EAA6C;AAC9F,EAAA,IAAI,KAAA,KAAU,IAAA,IAAQ,KAAA,KAAU,MAAA,EAAW,OAAO,KAAA;AAClD,EAAA,IAAI,MAAM,OAAA,CAAQ,KAAK,KAAK,KAAA,CAAM,MAAA,KAAW,GAAG,OAAO,KAAA;AACvD,EAAA,IAAI,KAAA,KAAU,IAAI,OAAO,KAAA;AAIzB,EAAA,MAAM,WAAA,GAAc,MAAA,IAAU,SAAA,IAAa,MAAA,GAAS,OAAO,OAAA,GAAU,MAAA;AACrE,EAAA,MAAM,UAAA,GAAa,MAAA,IAAU,cAAA,IAAkB,MAAA,GAAS,OAAO,YAAA,GAAe,MAAA;AAC9E,EAAA,MAAM,QAAA,GAAW,WAAA,KAAgB,MAAA,GAAY,WAAA,GAAc,UAAA;AAC3D,EAAA,IAAI,QAAA,KAAa,MAAA,IAAa,KAAA,KAAU,QAAA,EAAU,OAAO,KAAA;AACzD,EAAA,OAAO,IAAA;AACT;AAQO,SAAS,mBACd,MAAA,EACA,EAAE,SAAA,EAAU,GAA+B,EAAC,EAC3B;AACjB,EAAA,MAAM,MAAA,GAAS,IAAI,eAAA,EAAgB;AACnC,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,MAAM,CAAA,EAAG;AAIjD,IAAA,IAAI,CAAC,kBAAA,CAAmB,KAAA,EAAO,MAAS,CAAA,EAAG;AAC3C,IAAA,IAAI,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,EAAG;AAGxB,MAAA,MAAM,KAAA,GAAQ,MAAM,MAAA,CAAO,CAAA,CAAA,KAAK,MAAM,IAAA,IAAQ,CAAA,KAAM,MAAA,IAAa,CAAA,KAAM,EAAE,CAAA;AACzE,MAAA,IAAI,KAAA,CAAM,WAAW,CAAA,EAAG;AACxB,MAAA,IAAI,WAAW,MAAA,CAAO,GAAA,CAAI,KAAK,KAAA,CAAM,IAAA,CAAK,SAAS,CAAC,CAAA;AAAA,WAC/C,KAAA,MAAW,QAAQ,KAAA,EAAO,MAAA,CAAO,OAAO,GAAA,EAAK,MAAA,CAAO,IAAI,CAAC,CAAA;AAC9D,MAAA;AAAA,IACF;AACA,IAAA,IAAI,OAAO,UAAU,QAAA,EAAU;AAC7B,MAAA,MAAA,CAAO,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,SAAA,CAAU,KAAK,CAAC,CAAA;AACrC,MAAA;AAAA,IACF;AACA,IAAA,MAAA,CAAO,GAAA,CAAI,GAAA,EAAK,MAAA,CAAO,KAAK,CAAC,CAAA;AAAA,EAC/B;AACA,EAAA,OAAO,MAAA;AACT;AAGO,SAAS,qBAAA,CACd,MAAA,EACA,MAAA,EACA,OAAA,EACQ;AACR,EAAA,MAAM,OAAgC,EAAC;AACvC,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,MAAM,CAAA,EAAG;AACjD,IAAA,IAAI,kBAAA,CAAmB,OAAO,MAAA,CAAO,GAAG,CAAC,CAAA,EAAG,IAAA,CAAK,GAAG,CAAA,GAAI,KAAA;AAAA,EAC1D;AACA,EAAA,OAAO,kBAAA,CAAmB,IAAA,EAAM,OAAO,CAAA,CAAE,QAAA,EAAS;AACpD;AAGO,SAAS,SAAA,CAAU,MAAc,WAAA,EAAgD;AACtF,EAAA,OAAO,WAAA,GAAc,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI,WAAW,CAAA,CAAA,GAAK,IAAA;AAClD","file":"search-params.cjs","sourcesContent":["/**\n * URL parameter schema engine — the ONE grammar for every URL/API integer,\n * the ONE omission rule, the ONE serializer.\n *\n * Hoisted out of `hooks/state/` so SERVER code (route handlers, DALs) and the\n * CLIENT hook parse the same URL with the same function: a param contract that\n * disagrees across the wire is the bug class this removes. JSX-free leaf with\n * its own `exports` subpath; `hooks/state/*` re-exports every name it used to own.\n */\n\n/** JavaScript types a URL parameter can carry. `int` is a whole number with a floor. */\nexport type JSType = 'string' | 'number' | 'int' | 'boolean' | 'array' | 'object';\n\n// ── The integer grammar ─────────────────────────────────────────────────────\n\nexport interface PositiveIntOptions {\n  /** Smallest accepted value (default 1). Anything below falls back. */\n  min?: number;\n  /** Largest accepted value. Applied to the PARSED value AND to the fallback. */\n  max?: number;\n}\n\n/**\n * THE integer grammar for URL params, env vars, and page sizes.\n *\n * `null`/`undefined`/`''` → fallback. Otherwise `Math.trunc(Number(raw))`, which\n * accepts `'12'`, `12`, `'12.9'` (→ 12) and `'0x10'` (→ 16), and rejects `'12abc'`\n * and `'abc'` (`NaN`) — the historical `parseInt` accepted `'12abc'` as 12 and\n * produced `NaN` for `'abc'`. A value below `min` falls back. The RESULT (parsed\n * value or fallback alike) is clamped to `max`, so \"never exceeds max\" has one owner.\n */\nexport function positiveInt<TFallback = number>(\n  raw: string | number | null | undefined,\n  fallback: TFallback,\n  { min = 1, max }: PositiveIntOptions = {},\n): number | TFallback {\n  // The fallback is returned AS GIVEN — capping only ever applies to a value\n  // parsed out of the input, so a caller with no default (`null`) gets its\n  // sentinel back untouched instead of `Math.min(null, max)`.\n  const capped = (v: number) => (max == null ? v : Math.min(v, max));\n  if (raw === null || raw === undefined || raw === '') {\n    return typeof fallback === 'number' ? capped(fallback) : fallback;\n  }\n  const n = Math.trunc(Number(raw));\n  if (!Number.isFinite(n) || n < min) {\n    return typeof fallback === 'number' ? capped(fallback) : fallback;\n  }\n  return capped(n);\n}\n\n/** Ceilings every paged surface shares. */\nexport const PAGE_PARAM_LIMITS = { maxPage: 10_000, maxPageSize: 100 } as const;\n\n/** Total pages for a row count. Floors at 1, so an empty result is still \"page 1 of 1\". */\nexport function pageCount(total: number, pageSize: number): number {\n  if (!Number.isFinite(total) || !Number.isFinite(pageSize) || pageSize <= 0) return 1;\n  return Math.max(1, Math.ceil(total / pageSize));\n}\n\n/** Clamp a requested page into `1..totalPages`. */\nexport function clampPageToTotal(page: number, totalPages: number): number {\n  return Math.min(page, Math.max(1, totalPages));\n}\n\n// ── Schema ──────────────────────────────────────────────────────────────────\n\ntype OutputTypeMap = {\n  string: string;\n  number: number;\n  int: number;\n  boolean: boolean;\n  array: string[];\n  object: Record<string, unknown>;\n};\n\nexport type OutputTypeForJSType<T extends JSType> = OutputTypeMap[T];\n\nexport interface BaseParamConfig<T extends JSType = JSType> {\n  type: T;\n  default?: OutputTypeMap[T];\n  required?: boolean;\n}\n\n/** An integer parameter with an optional floor and ceiling. */\nexport interface IntParamConfig extends BaseParamConfig<'int'> {\n  min?: number;\n  max?: number;\n}\n\nexport type ParamConfig<T extends JSType = JSType> = T extends 'int' ? IntParamConfig : BaseParamConfig<T>;\n\nexport type ParamSchema = Record<string, ParamConfig>;\n\n/** Identity helper that preserves literal types through a schema object. */\nexport function defineParamSchema<T extends ParamSchema>(schema: T): T {\n  return schema;\n}\n\n/**\n * Build a `Record<K, V>` from a key tuple. Keeps `keyof` EXACT when spreading a\n * shared config across derived keys (an inline `Object.fromEntries` widens to\n * `Record<string, V>` and loses the key union).\n */\nexport function fromKeys<K extends string, V>(keys: readonly K[], value: V): Record<K, V> {\n  return Object.fromEntries(keys.map(k => [k, value])) as Record<K, V>;\n}\n\n// ── Reading ─────────────────────────────────────────────────────────────────\n\n/** Anything a URL can be read from: `URLSearchParams`, Next's `searchParams`, or a plain record. */\nexport type ParamInput = URLSearchParams | Record<string, string | string[] | undefined> | null | undefined;\n\n/** THE first-value rule for a duplicated key (`?a=1&a=2` reads as `1`). */\nexport function firstParamValue(input: ParamInput, key: string): string | undefined {\n  if (!input) return undefined;\n  if (input instanceof URLSearchParams) return input.get(key) ?? undefined;\n  const value = input[key];\n  return Array.isArray(value) ? value[0] : value;\n}\n\n/** Every value for a key (arrays read repeated params, then a `,`-joined single value). */\nfunction allParamValues(input: ParamInput, key: string): string[] {\n  if (!input) return [];\n  const raw = input instanceof URLSearchParams ? input.getAll(key) : input[key];\n  const list = Array.isArray(raw) ? raw : raw === undefined ? [] : [raw];\n  if (list.length === 1 && list[0]?.includes(',')) return list[0].split(',').filter(Boolean);\n  return list.filter(v => v !== undefined && v !== '');\n}\n\nexport interface ParseSchemaOptions {\n  /**\n   * What an ABSENT scalar with no declared `default` resolves to.\n   * `'undefined'` (default) keeps today's behaviour; `'null'` is the explicit\n   * \"this filter is unset\" spelling that survives JSON and `URLSearchParams`.\n   */\n  absent?: 'undefined' | 'null';\n}\n\nexport type AbsentValue<Opts extends ParseSchemaOptions | undefined> = Opts extends { absent: 'null' }\n  ? null\n  : undefined;\n\n/**\n * The parsed shape of a schema: keys with a `default` and every array key are\n * non-nullable; an undefaulted scalar carries the caller's absent value.\n */\nexport type InferParsedParams<TSchema extends ParamSchema, Absent = undefined> = {\n  [K in keyof TSchema]: TSchema[K] extends { type: 'array' }\n    ? string[]\n    : TSchema[K] extends { default: infer D }\n      ? D\n      : TSchema[K]['type'] extends infer T\n        ? T extends JSType\n          ? OutputTypeForJSType<T> | Absent\n          : never\n        : never;\n};\n\nfunction coerceScalar(raw: string | undefined, config: ParamConfig): unknown {\n  if (raw === undefined || raw === '') return undefined;\n  switch (config.type) {\n    case 'int': {\n      const int = config;\n      // ONE integer grammar, default or not. Without a declared default the\n      // fallback is `undefined` (an unparseable value is absent), which\n      // `positiveInt` returns untouched — the branch used to open-code the\n      // truncation, the min floor and the max clamp a second time.\n      return positiveInt<undefined>(raw, int.default as undefined, { min: int.min, max: int.max });\n    }\n    case 'number': {\n      const n = Number(raw);\n      return Number.isFinite(n) ? n : undefined;\n    }\n    case 'boolean':\n      return raw === 'true' || raw === '1';\n    case 'object':\n      try {\n        return JSON.parse(raw) as Record<string, unknown>;\n      } catch {\n        return undefined;\n      }\n    default:\n      return raw;\n  }\n}\n\n/**\n * Parse a URL into a schema's shape. THE reader — the server route and the\n * client hook both call this, so a URL means exactly one thing.\n *\n * PRECEDENCE: an absent or empty SCALAR takes the declared `default` when there\n * is one, else the `absent` value. ARRAY keys never take `absent`: they are `[]`.\n */\nexport function parseSchemaParams<TSchema extends ParamSchema, Opts extends ParseSchemaOptions = Record<string, never>>(\n  schema: TSchema,\n  input: ParamInput,\n  options?: Opts,\n): InferParsedParams<TSchema, AbsentValue<Opts>> {\n  const absent = options?.absent === 'null' ? null : undefined;\n  const out: Record<string, unknown> = {};\n  for (const [key, config] of Object.entries(schema)) {\n    if (config.type === 'array') {\n      const values = allParamValues(input, key);\n      out[key] = values.length > 0 ? values : (config.default ?? []);\n      continue;\n    }\n    const coerced = coerceScalar(firstParamValue(input, key), config);\n    out[key] = coerced !== undefined ? coerced : (config.default ?? absent);\n  }\n  return out as InferParsedParams<TSchema, AbsentValue<Opts>>;\n}\n\n// ── Writing ─────────────────────────────────────────────────────────────────\n\n/**\n * A schema entry OR a legacy flattened param (which spells its default\n * `defaultValue`).\n *\n * A UNION, not a bag of two optional fields: with only `default?` and\n * `defaultValue?` this is a WEAK TYPE, and TypeScript rejects any argument\n * sharing neither — including `{ type: 'string' }`, the single most common\n * schema entry there is. Naming the real config shapes fixes that without an\n * index signature, which `FlattenedParam` (an interface) could never satisfy.\n */\ntype OmissionConfig = ParamConfig | { default?: unknown; defaultValue?: unknown };\n\n/**\n * THE omission rule: `null`, `undefined`, `''`, `[]`, and a value equal to the\n * declared default are left out, so a URL only ever carries what differs.\n */\nexport function shouldIncludeInUrl(value: unknown, config: OmissionConfig | undefined): boolean {\n  if (value === null || value === undefined) return false;\n  if (Array.isArray(value) && value.length === 0) return false;\n  if (value === '') return false;\n  // `in` narrowing rather than a cast: the union's members genuinely differ —\n  // a schema entry spells its default `default`, a flattened param spells it\n  // `defaultValue`, and neither is obliged to carry the other's field.\n  const fromDefault = config && 'default' in config ? config.default : undefined;\n  const fromLegacy = config && 'defaultValue' in config ? config.defaultValue : undefined;\n  const declared = fromDefault !== undefined ? fromDefault : fromLegacy;\n  if (declared !== undefined && value === declared) return false;\n  return true;\n}\n\nexport interface CreateSearchParamsOptions {\n  /** Join arrays with this separator instead of repeating the key (`;` for the hub's list APIs). */\n  arrayJoin?: string;\n}\n\n/** Build `URLSearchParams` from a value record (arrays repeat the key by default). */\nexport function createSearchParams(\n  params: Record<string, unknown>,\n  { arrayJoin }: CreateSearchParamsOptions = {},\n): URLSearchParams {\n  const search = new URLSearchParams();\n  for (const [key, value] of Object.entries(params)) {\n    // The emptiness half of the omission rule has ONE owner. (No config here:\n    // callers that must also drop schema DEFAULTS filter through\n    // `shouldIncludeInUrl` with the config first — see `serializeSchemaParams`.)\n    if (!shouldIncludeInUrl(value, undefined)) continue;\n    if (Array.isArray(value)) {\n      // Empty ELEMENTS are dropped, and an array that filters to nothing is\n      // absent (a cleared multi-select must not leave `?tags=` behind).\n      const items = value.filter(v => v !== null && v !== undefined && v !== '');\n      if (items.length === 0) continue;\n      if (arrayJoin) search.set(key, items.join(arrayJoin));\n      else for (const item of items) search.append(key, String(item));\n      continue;\n    }\n    if (typeof value === 'object') {\n      search.set(key, JSON.stringify(value));\n      continue;\n    }\n    search.set(key, String(value));\n  }\n  return search;\n}\n\n/** Serialize params to a query string, omitting everything `shouldIncludeInUrl` rejects. */\nexport function serializeSchemaParams<TSchema extends ParamSchema>(\n  schema: TSchema,\n  params: Record<string, unknown>,\n  options?: CreateSearchParamsOptions,\n): string {\n  const kept: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(params)) {\n    if (shouldIncludeInUrl(value, schema[key])) kept[key] = value;\n  }\n  return createSearchParams(kept, options).toString();\n}\n\n/** Append a query string to a path, or return the path unchanged when it is empty. */\nexport function withQuery(path: string, queryString: string | null | undefined): string {\n  return queryString ? `${path}?${queryString}` : path;\n}\n"]}

package/dist/utils/search-params.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/search-params.ts"],"names":[],"mappings":"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","file":"search-params.js","sourcesContent":["/**\n * URL parameter schema engine — the ONE grammar for every URL/API integer,\n * the ONE omission rule, the ONE serializer.\n *\n * Hoisted out of `hooks/state/` so SERVER code (route handlers, DALs) and the\n * CLIENT hook parse the same URL with the same function: a param contract that\n * disagrees across the wire is the bug class this removes. JSX-free leaf with\n * its own `exports` subpath; `hooks/state/*` re-exports every name it used to own.\n */\n\n/** JavaScript types a URL parameter can carry. `int` is a whole number with a floor. */\nexport type JSType = 'string' | 'number' | 'int' | 'boolean' | 'array' | 'object';\n\n// ── The integer grammar ─────────────────────────────────────────────────────\n\nexport interface PositiveIntOptions {\n  /** Smallest accepted value (default 1). Anything below falls back. */\n  min?: number;\n  /** Largest accepted value. Applied to the PARSED value AND to the fallback. */\n  max?: number;\n}\n\n/**\n * THE integer grammar for URL params, env vars, and page sizes.\n *\n * `null`/`undefined`/`''` → fallback. Otherwise `Math.trunc(Number(raw))`, which\n * accepts `'12'`, `12`, `'12.9'` (→ 12) and `'0x10'` (→ 16), and rejects `'12abc'`\n * and `'abc'` (`NaN`) — the historical `parseInt` accepted `'12abc'` as 12 and\n * produced `NaN` for `'abc'`. A value below `min` falls back. The RESULT (parsed\n * value or fallback alike) is clamped to `max`, so \"never exceeds max\" has one owner.\n */\nexport function positiveInt<TFallback = number>(\n  raw: string | number | null | undefined,\n  fallback: TFallback,\n  { min = 1, max }: PositiveIntOptions = {},\n): number | TFallback {\n  // The fallback is returned AS GIVEN — capping only ever applies to a value\n  // parsed out of the input, so a caller with no default (`null`) gets its\n  // sentinel back untouched instead of `Math.min(null, max)`.\n  const capped = (v: number) => (max == null ? v : Math.min(v, max));\n  if (raw === null || raw === undefined || raw === '') {\n    return typeof fallback === 'number' ? (capped(fallback) as number | TFallback) : fallback;\n  }\n  const n = Math.trunc(Number(raw));\n  if (!Number.isFinite(n) || n < min) {\n    return typeof fallback === 'number' ? (capped(fallback) as number | TFallback) : fallback;\n  }\n  return capped(n);\n}\n\n/** Ceilings every paged surface shares. */\nexport const PAGE_PARAM_LIMITS = { maxPage: 10_000, maxPageSize: 100 } as const;\n\n/** Total pages for a row count. Floors at 1, so an empty result is still \"page 1 of 1\". */\nexport function pageCount(total: number, pageSize: number): number {\n  if (!Number.isFinite(total) || !Number.isFinite(pageSize) || pageSize <= 0) return 1;\n  return Math.max(1, Math.ceil(total / pageSize));\n}\n\n/** Clamp a requested page into `1..totalPages`. */\nexport function clampPageToTotal(page: number, totalPages: number): number {\n  return Math.min(page, Math.max(1, totalPages));\n}\n\n// ── Schema ──────────────────────────────────────────────────────────────────\n\ntype OutputTypeMap = {\n  string: string;\n  number: number;\n  int: number;\n  boolean: boolean;\n  array: string[];\n  object: Record<string, unknown>;\n};\n\nexport type OutputTypeForJSType<T extends JSType> = OutputTypeMap[T];\n\nexport interface BaseParamConfig<T extends JSType = JSType> {\n  type: T;\n  default?: OutputTypeMap[T];\n  required?: boolean;\n}\n\n/** An integer parameter with an optional floor and ceiling. */\nexport interface IntParamConfig extends BaseParamConfig<'int'> {\n  min?: number;\n  max?: number;\n}\n\nexport type ParamConfig<T extends JSType = JSType> = T extends 'int' ? IntParamConfig : BaseParamConfig<T>;\n\nexport type ParamSchema = Record<string, ParamConfig>;\n\n/** Identity helper that preserves literal types through a schema object. */\nexport function defineParamSchema<T extends ParamSchema>(schema: T): T {\n  return schema;\n}\n\n/**\n * Build a `Record<K, V>` from a key tuple. Keeps `keyof` EXACT when spreading a\n * shared config across derived keys (an inline `Object.fromEntries` widens to\n * `Record<string, V>` and loses the key union).\n */\nexport function fromKeys<K extends string, V>(keys: readonly K[], value: V): Record<K, V> {\n  return Object.fromEntries(keys.map(k => [k, value])) as Record<K, V>;\n}\n\n// ── Reading ─────────────────────────────────────────────────────────────────\n\n/** Anything a URL can be read from: `URLSearchParams`, Next's `searchParams`, or a plain record. */\nexport type ParamInput = URLSearchParams | Record<string, string | string[] | undefined> | null | undefined;\n\n/** THE first-value rule for a duplicated key (`?a=1&a=2` reads as `1`). */\nexport function firstParamValue(input: ParamInput, key: string): string | undefined {\n  if (!input) return undefined;\n  if (input instanceof URLSearchParams) return input.get(key) ?? undefined;\n  const value = input[key];\n  return Array.isArray(value) ? value[0] : value;\n}\n\n/** Every value for a key (arrays read repeated params, then a `,`-joined single value). */\nfunction allParamValues(input: ParamInput, key: string): string[] {\n  if (!input) return [];\n  const raw = input instanceof URLSearchParams ? input.getAll(key) : input[key];\n  const list = Array.isArray(raw) ? raw : raw === undefined ? [] : [raw];\n  if (list.length === 1 && list[0]?.includes(',')) return list[0].split(',').filter(Boolean);\n  return list.filter(v => v !== undefined && v !== '');\n}\n\nexport interface ParseSchemaOptions {\n  /**\n   * What an ABSENT scalar with no declared `default` resolves to.\n   * `'undefined'` (default) keeps today's behaviour; `'null'` is the explicit\n   * \"this filter is unset\" spelling that survives JSON and `URLSearchParams`.\n   */\n  absent?: 'undefined' | 'null';\n}\n\nexport type AbsentValue<Opts extends ParseSchemaOptions | undefined> = Opts extends { absent: 'null' }\n  ? null\n  : undefined;\n\n/**\n * The parsed shape of a schema: keys with a `default` and every array key are\n * non-nullable; an undefaulted scalar carries the caller's absent value.\n */\nexport type InferParsedParams<TSchema extends ParamSchema, Absent = undefined> = {\n  [K in keyof TSchema]: TSchema[K] extends { type: 'array' }\n    ? string[]\n    : TSchema[K] extends { default: infer D }\n      ? D\n      : TSchema[K]['type'] extends infer T\n        ? T extends JSType\n          ? OutputTypeForJSType<T> | Absent\n          : never\n        : never;\n};\n\nfunction coerceScalar(raw: string | undefined, config: ParamConfig): unknown {\n  if (raw === undefined || raw === '') return undefined;\n  switch (config.type) {\n    case 'int': {\n      const int = config as IntParamConfig;\n      // ONE integer grammar, default or not. Without a declared default the\n      // fallback is `undefined` (an unparseable value is absent), which\n      // `positiveInt` returns untouched — the branch used to open-code the\n      // truncation, the min floor and the max clamp a second time.\n      return positiveInt<undefined>(raw, int.default as undefined, { min: int.min, max: int.max });\n    }\n    case 'number': {\n      const n = Number(raw);\n      return Number.isFinite(n) ? n : undefined;\n    }\n    case 'boolean':\n      return raw === 'true' || raw === '1';\n    case 'object':\n      try {\n        return JSON.parse(raw) as Record<string, unknown>;\n      } catch {\n        return undefined;\n      }\n    default:\n      return raw;\n  }\n}\n\n/**\n * Parse a URL into a schema's shape. THE reader — the server route and the\n * client hook both call this, so a URL means exactly one thing.\n *\n * PRECEDENCE: an absent or empty SCALAR takes the declared `default` when there\n * is one, else the `absent` value. ARRAY keys never take `absent`: they are `[]`.\n */\nexport function parseSchemaParams<TSchema extends ParamSchema, Opts extends ParseSchemaOptions = Record<string, never>>(\n  schema: TSchema,\n  input: ParamInput,\n  options?: Opts,\n): InferParsedParams<TSchema, AbsentValue<Opts>> {\n  const absent = options?.absent === 'null' ? null : undefined;\n  const out: Record<string, unknown> = {};\n  for (const [key, config] of Object.entries(schema)) {\n    if (config.type === 'array') {\n      const values = allParamValues(input, key);\n      out[key] = values.length > 0 ? values : ((config.default as string[] | undefined) ?? []);\n      continue;\n    }\n    const coerced = coerceScalar(firstParamValue(input, key), config);\n    out[key] = coerced !== undefined ? coerced : (config.default ?? absent);\n  }\n  return out as InferParsedParams<TSchema, AbsentValue<Opts>>;\n}\n\n// ── Writing ─────────────────────────────────────────────────────────────────\n\n/**\n * A schema entry OR a legacy flattened param (which spells its default\n * `defaultValue`).\n *\n * A UNION, not a bag of two optional fields: with only `default?` and\n * `defaultValue?` this is a WEAK TYPE, and TypeScript rejects any argument\n * sharing neither — including `{ type: 'string' }`, the single most common\n * schema entry there is. Naming the real config shapes fixes that without an\n * index signature, which `FlattenedParam` (an interface) could never satisfy.\n */\ntype OmissionConfig = ParamConfig | { default?: unknown; defaultValue?: unknown };\n\n/**\n * THE omission rule: `null`, `undefined`, `''`, `[]`, and a value equal to the\n * declared default are left out, so a URL only ever carries what differs.\n */\nexport function shouldIncludeInUrl(value: unknown, config: OmissionConfig | undefined): boolean {\n  if (value === null || value === undefined) return false;\n  if (Array.isArray(value) && value.length === 0) return false;\n  if (value === '') return false;\n  // `in` narrowing rather than a cast: the union's members genuinely differ —\n  // a schema entry spells its default `default`, a flattened param spells it\n  // `defaultValue`, and neither is obliged to carry the other's field.\n  const fromDefault = config && 'default' in config ? config.default : undefined;\n  const fromLegacy = config && 'defaultValue' in config ? config.defaultValue : undefined;\n  const declared = fromDefault !== undefined ? fromDefault : fromLegacy;\n  if (declared !== undefined && value === declared) return false;\n  return true;\n}\n\nexport interface CreateSearchParamsOptions {\n  /** Join arrays with this separator instead of repeating the key (`;` for the hub's list APIs). */\n  arrayJoin?: string;\n}\n\n/** Build `URLSearchParams` from a value record (arrays repeat the key by default). */\nexport function createSearchParams(\n  params: Record<string, unknown>,\n  { arrayJoin }: CreateSearchParamsOptions = {},\n): URLSearchParams {\n  const search = new URLSearchParams();\n  for (const [key, value] of Object.entries(params)) {\n    // The emptiness half of the omission rule has ONE owner. (No config here:\n    // callers that must also drop schema DEFAULTS filter through\n    // `shouldIncludeInUrl` with the config first — see `serializeSchemaParams`.)\n    if (!shouldIncludeInUrl(value, undefined)) continue;\n    if (Array.isArray(value)) {\n      // Empty ELEMENTS are dropped, and an array that filters to nothing is\n      // absent (a cleared multi-select must not leave `?tags=` behind).\n      const items = value.filter(v => v !== null && v !== undefined && v !== '');\n      if (items.length === 0) continue;\n      if (arrayJoin) search.set(key, items.join(arrayJoin));\n      else for (const item of items) search.append(key, String(item));\n      continue;\n    }\n    if (typeof value === 'object') {\n      search.set(key, JSON.stringify(value));\n      continue;\n    }\n    search.set(key, String(value));\n  }\n  return search;\n}\n\n/** Serialize params to a query string, omitting everything `shouldIncludeInUrl` rejects. */\nexport function serializeSchemaParams<TSchema extends ParamSchema>(\n  schema: TSchema,\n  params: Record<string, unknown>,\n  options?: CreateSearchParamsOptions,\n): string {\n  const kept: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(params)) {\n    if (shouldIncludeInUrl(value, schema[key])) kept[key] = value;\n  }\n  return createSearchParams(kept, options).toString();\n}\n\n/** Append a query string to a path, or return the path unchanged when it is empty. */\nexport function withQuery(path: string, queryString: string | null | undefined): string {\n  return queryString ? `${path}?${queryString}` : path;\n}\n"]}
+{"version":3,"sources":["../../src/utils/search-params.ts"],"names":[],"mappings":"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","file":"search-params.js","sourcesContent":["/**\n * URL parameter schema engine — the ONE grammar for every URL/API integer,\n * the ONE omission rule, the ONE serializer.\n *\n * Hoisted out of `hooks/state/` so SERVER code (route handlers, DALs) and the\n * CLIENT hook parse the same URL with the same function: a param contract that\n * disagrees across the wire is the bug class this removes. JSX-free leaf with\n * its own `exports` subpath; `hooks/state/*` re-exports every name it used to own.\n */\n\n/** JavaScript types a URL parameter can carry. `int` is a whole number with a floor. */\nexport type JSType = 'string' | 'number' | 'int' | 'boolean' | 'array' | 'object';\n\n// ── The integer grammar ─────────────────────────────────────────────────────\n\nexport interface PositiveIntOptions {\n  /** Smallest accepted value (default 1). Anything below falls back. */\n  min?: number;\n  /** Largest accepted value. Applied to the PARSED value AND to the fallback. */\n  max?: number;\n}\n\n/**\n * THE integer grammar for URL params, env vars, and page sizes.\n *\n * `null`/`undefined`/`''` → fallback. Otherwise `Math.trunc(Number(raw))`, which\n * accepts `'12'`, `12`, `'12.9'` (→ 12) and `'0x10'` (→ 16), and rejects `'12abc'`\n * and `'abc'` (`NaN`) — the historical `parseInt` accepted `'12abc'` as 12 and\n * produced `NaN` for `'abc'`. A value below `min` falls back. The RESULT (parsed\n * value or fallback alike) is clamped to `max`, so \"never exceeds max\" has one owner.\n */\nexport function positiveInt<TFallback = number>(\n  raw: string | number | null | undefined,\n  fallback: TFallback,\n  { min = 1, max }: PositiveIntOptions = {},\n): number | TFallback {\n  // The fallback is returned AS GIVEN — capping only ever applies to a value\n  // parsed out of the input, so a caller with no default (`null`) gets its\n  // sentinel back untouched instead of `Math.min(null, max)`.\n  const capped = (v: number) => (max == null ? v : Math.min(v, max));\n  if (raw === null || raw === undefined || raw === '') {\n    return typeof fallback === 'number' ? capped(fallback) : fallback;\n  }\n  const n = Math.trunc(Number(raw));\n  if (!Number.isFinite(n) || n < min) {\n    return typeof fallback === 'number' ? capped(fallback) : fallback;\n  }\n  return capped(n);\n}\n\n/** Ceilings every paged surface shares. */\nexport const PAGE_PARAM_LIMITS = { maxPage: 10_000, maxPageSize: 100 } as const;\n\n/** Total pages for a row count. Floors at 1, so an empty result is still \"page 1 of 1\". */\nexport function pageCount(total: number, pageSize: number): number {\n  if (!Number.isFinite(total) || !Number.isFinite(pageSize) || pageSize <= 0) return 1;\n  return Math.max(1, Math.ceil(total / pageSize));\n}\n\n/** Clamp a requested page into `1..totalPages`. */\nexport function clampPageToTotal(page: number, totalPages: number): number {\n  return Math.min(page, Math.max(1, totalPages));\n}\n\n// ── Schema ──────────────────────────────────────────────────────────────────\n\ntype OutputTypeMap = {\n  string: string;\n  number: number;\n  int: number;\n  boolean: boolean;\n  array: string[];\n  object: Record<string, unknown>;\n};\n\nexport type OutputTypeForJSType<T extends JSType> = OutputTypeMap[T];\n\nexport interface BaseParamConfig<T extends JSType = JSType> {\n  type: T;\n  default?: OutputTypeMap[T];\n  required?: boolean;\n}\n\n/** An integer parameter with an optional floor and ceiling. */\nexport interface IntParamConfig extends BaseParamConfig<'int'> {\n  min?: number;\n  max?: number;\n}\n\nexport type ParamConfig<T extends JSType = JSType> = T extends 'int' ? IntParamConfig : BaseParamConfig<T>;\n\nexport type ParamSchema = Record<string, ParamConfig>;\n\n/** Identity helper that preserves literal types through a schema object. */\nexport function defineParamSchema<T extends ParamSchema>(schema: T): T {\n  return schema;\n}\n\n/**\n * Build a `Record<K, V>` from a key tuple. Keeps `keyof` EXACT when spreading a\n * shared config across derived keys (an inline `Object.fromEntries` widens to\n * `Record<string, V>` and loses the key union).\n */\nexport function fromKeys<K extends string, V>(keys: readonly K[], value: V): Record<K, V> {\n  return Object.fromEntries(keys.map(k => [k, value])) as Record<K, V>;\n}\n\n// ── Reading ─────────────────────────────────────────────────────────────────\n\n/** Anything a URL can be read from: `URLSearchParams`, Next's `searchParams`, or a plain record. */\nexport type ParamInput = URLSearchParams | Record<string, string | string[] | undefined> | null | undefined;\n\n/** THE first-value rule for a duplicated key (`?a=1&a=2` reads as `1`). */\nexport function firstParamValue(input: ParamInput, key: string): string | undefined {\n  if (!input) return undefined;\n  if (input instanceof URLSearchParams) return input.get(key) ?? undefined;\n  const value = input[key];\n  return Array.isArray(value) ? value[0] : value;\n}\n\n/** Every value for a key (arrays read repeated params, then a `,`-joined single value). */\nfunction allParamValues(input: ParamInput, key: string): string[] {\n  if (!input) return [];\n  const raw = input instanceof URLSearchParams ? input.getAll(key) : input[key];\n  const list = Array.isArray(raw) ? raw : raw === undefined ? [] : [raw];\n  if (list.length === 1 && list[0]?.includes(',')) return list[0].split(',').filter(Boolean);\n  return list.filter(v => v !== undefined && v !== '');\n}\n\nexport interface ParseSchemaOptions {\n  /**\n   * What an ABSENT scalar with no declared `default` resolves to.\n   * `'undefined'` (default) keeps today's behaviour; `'null'` is the explicit\n   * \"this filter is unset\" spelling that survives JSON and `URLSearchParams`.\n   */\n  absent?: 'undefined' | 'null';\n}\n\nexport type AbsentValue<Opts extends ParseSchemaOptions | undefined> = Opts extends { absent: 'null' }\n  ? null\n  : undefined;\n\n/**\n * The parsed shape of a schema: keys with a `default` and every array key are\n * non-nullable; an undefaulted scalar carries the caller's absent value.\n */\nexport type InferParsedParams<TSchema extends ParamSchema, Absent = undefined> = {\n  [K in keyof TSchema]: TSchema[K] extends { type: 'array' }\n    ? string[]\n    : TSchema[K] extends { default: infer D }\n      ? D\n      : TSchema[K]['type'] extends infer T\n        ? T extends JSType\n          ? OutputTypeForJSType<T> | Absent\n          : never\n        : never;\n};\n\nfunction coerceScalar(raw: string | undefined, config: ParamConfig): unknown {\n  if (raw === undefined || raw === '') return undefined;\n  switch (config.type) {\n    case 'int': {\n      const int = config;\n      // ONE integer grammar, default or not. Without a declared default the\n      // fallback is `undefined` (an unparseable value is absent), which\n      // `positiveInt` returns untouched — the branch used to open-code the\n      // truncation, the min floor and the max clamp a second time.\n      return positiveInt<undefined>(raw, int.default as undefined, { min: int.min, max: int.max });\n    }\n    case 'number': {\n      const n = Number(raw);\n      return Number.isFinite(n) ? n : undefined;\n    }\n    case 'boolean':\n      return raw === 'true' || raw === '1';\n    case 'object':\n      try {\n        return JSON.parse(raw) as Record<string, unknown>;\n      } catch {\n        return undefined;\n      }\n    default:\n      return raw;\n  }\n}\n\n/**\n * Parse a URL into a schema's shape. THE reader — the server route and the\n * client hook both call this, so a URL means exactly one thing.\n *\n * PRECEDENCE: an absent or empty SCALAR takes the declared `default` when there\n * is one, else the `absent` value. ARRAY keys never take `absent`: they are `[]`.\n */\nexport function parseSchemaParams<TSchema extends ParamSchema, Opts extends ParseSchemaOptions = Record<string, never>>(\n  schema: TSchema,\n  input: ParamInput,\n  options?: Opts,\n): InferParsedParams<TSchema, AbsentValue<Opts>> {\n  const absent = options?.absent === 'null' ? null : undefined;\n  const out: Record<string, unknown> = {};\n  for (const [key, config] of Object.entries(schema)) {\n    if (config.type === 'array') {\n      const values = allParamValues(input, key);\n      out[key] = values.length > 0 ? values : (config.default ?? []);\n      continue;\n    }\n    const coerced = coerceScalar(firstParamValue(input, key), config);\n    out[key] = coerced !== undefined ? coerced : (config.default ?? absent);\n  }\n  return out as InferParsedParams<TSchema, AbsentValue<Opts>>;\n}\n\n// ── Writing ─────────────────────────────────────────────────────────────────\n\n/**\n * A schema entry OR a legacy flattened param (which spells its default\n * `defaultValue`).\n *\n * A UNION, not a bag of two optional fields: with only `default?` and\n * `defaultValue?` this is a WEAK TYPE, and TypeScript rejects any argument\n * sharing neither — including `{ type: 'string' }`, the single most common\n * schema entry there is. Naming the real config shapes fixes that without an\n * index signature, which `FlattenedParam` (an interface) could never satisfy.\n */\ntype OmissionConfig = ParamConfig | { default?: unknown; defaultValue?: unknown };\n\n/**\n * THE omission rule: `null`, `undefined`, `''`, `[]`, and a value equal to the\n * declared default are left out, so a URL only ever carries what differs.\n */\nexport function shouldIncludeInUrl(value: unknown, config: OmissionConfig | undefined): boolean {\n  if (value === null || value === undefined) return false;\n  if (Array.isArray(value) && value.length === 0) return false;\n  if (value === '') return false;\n  // `in` narrowing rather than a cast: the union's members genuinely differ —\n  // a schema entry spells its default `default`, a flattened param spells it\n  // `defaultValue`, and neither is obliged to carry the other's field.\n  const fromDefault = config && 'default' in config ? config.default : undefined;\n  const fromLegacy = config && 'defaultValue' in config ? config.defaultValue : undefined;\n  const declared = fromDefault !== undefined ? fromDefault : fromLegacy;\n  if (declared !== undefined && value === declared) return false;\n  return true;\n}\n\nexport interface CreateSearchParamsOptions {\n  /** Join arrays with this separator instead of repeating the key (`;` for the hub's list APIs). */\n  arrayJoin?: string;\n}\n\n/** Build `URLSearchParams` from a value record (arrays repeat the key by default). */\nexport function createSearchParams(\n  params: Record<string, unknown>,\n  { arrayJoin }: CreateSearchParamsOptions = {},\n): URLSearchParams {\n  const search = new URLSearchParams();\n  for (const [key, value] of Object.entries(params)) {\n    // The emptiness half of the omission rule has ONE owner. (No config here:\n    // callers that must also drop schema DEFAULTS filter through\n    // `shouldIncludeInUrl` with the config first — see `serializeSchemaParams`.)\n    if (!shouldIncludeInUrl(value, undefined)) continue;\n    if (Array.isArray(value)) {\n      // Empty ELEMENTS are dropped, and an array that filters to nothing is\n      // absent (a cleared multi-select must not leave `?tags=` behind).\n      const items = value.filter(v => v !== null && v !== undefined && v !== '');\n      if (items.length === 0) continue;\n      if (arrayJoin) search.set(key, items.join(arrayJoin));\n      else for (const item of items) search.append(key, String(item));\n      continue;\n    }\n    if (typeof value === 'object') {\n      search.set(key, JSON.stringify(value));\n      continue;\n    }\n    search.set(key, String(value));\n  }\n  return search;\n}\n\n/** Serialize params to a query string, omitting everything `shouldIncludeInUrl` rejects. */\nexport function serializeSchemaParams<TSchema extends ParamSchema>(\n  schema: TSchema,\n  params: Record<string, unknown>,\n  options?: CreateSearchParamsOptions,\n): string {\n  const kept: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(params)) {\n    if (shouldIncludeInUrl(value, schema[key])) kept[key] = value;\n  }\n  return createSearchParams(kept, options).toString();\n}\n\n/** Append a query string to a path, or return the path unchanged when it is empty. */\nexport function withQuery(path: string, queryString: string | null | undefined): string {\n  return queryString ? `${path}?${queryString}` : path;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.591",
+  "version": "0.0.592-snapshot.20260905013229",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/__tests__/data-table-row-height.test.tsx

@@ -0,0 +1,170 @@
+import { createColumnHelper } from '@tanstack/react-table';
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { DataTable } from '../components/ui/data-table';
+import { useDataTable } from '../components/ui/data-table/use-data-table';
+import { EntityImage } from '../components/ui/entity-image';
+
+/**
+ * `minRows` promises a stable table height. It kept that promise only for a
+ * table whose rows are the design height — a table stating its own height got
+ * pad rows and a skeleton at the design height instead, so a short page came up
+ * short by the difference, per missing row.
+ *
+ * These lock the one thing that makes the promise true: EVERY row slot a table
+ * can draw — a real row, a pad row, a skeleton row — reserves the SAME height.
+ */
+
+interface Row {
+  id: string;
+  name: string;
+}
+
+const columnHelper = createColumnHelper<Row>();
+const columns = [columnHelper.accessor('name', { id: 'name', header: 'Name' })];
+
+const ROW_H = 'h-[112px]';
+
+function Table({
+  data,
+  loading = false,
+  rowHeightClassName,
+}: {
+  data: Row[];
+  loading?: boolean;
+  rowHeightClassName?: string;
+}) {
+  const table = useDataTable({ data, columns });
+  return (
+    <DataTable table={table}>
+      <DataTable.Body<Row>
+        loading={loading}
+        minRows={4}
+        skeletonRows={4}
+        autoHeight
+        rowHeightClassName={rowHeightClassName}
+      />
+    </DataTable>
+  );
+}
+
+/** The same table, but every row carries a sub-row beneath its cells. */
+function TableWithSubRows({ data, rowHeightClassName }: { data: Row[]; rowHeightClassName?: string }) {
+  const table = useDataTable({ data, columns });
+  return (
+    <DataTable table={table}>
+      <DataTable.Body<Row>
+        minRows={4}
+        skeletonRows={4}
+        rowHeightClassName={rowHeightClassName}
+        renderSubRow={() => <div style={{ height: 96 }}>sub</div>}
+      />
+    </DataTable>
+  );
+}
+
+const rows = (n: number): Row[] => Array.from({ length: n }, (_, i) => ({ id: String(i), name: `Row ${i}` }));
+
+/**
+ * Every explicit height utility in the rendered markup.
+ *
+ * Read off the markup rather than through a selector, because the height a row
+ * slot reserves is exactly what ships in the class attribute — and matching an
+ * arbitrary-value class through `querySelectorAll` is its own trap.
+ */
+function heightClasses(container: HTMLElement): string[] {
+  return [...container.innerHTML.matchAll(/\b(?:md:)?(?:min-)?h-\[[^\]\s"]+\]/g)].map(m => m[0]);
+}
+
+/** The class list of every row-card slot (real or pad) in the rendered markup. */
+function slotClasses(container: HTMLElement): string[] {
+  return [...container.innerHTML.matchAll(/class="([^"]*\brounded-md\b[^"]*)"/g)].map(m => m[1]);
+}
+
+describe('DataTable row height', () => {
+  it('reserves the SAME height for real rows and the pad rows beside them', () => {
+    // Two real rows in a table promising four: two pad rows make up the rest.
+    const { container } = render(<Table data={rows(2)} rowHeightClassName={ROW_H} />);
+    const heights = heightClasses(container);
+
+    expect(heights.length).toBeGreaterThan(0);
+    // Not "most of them" — every single slot, or the table's height moves with
+    // how many results the page happens to hold.
+    expect(new Set(heights)).toEqual(new Set([ROW_H]));
+  });
+
+  it('reserves that height in the SKELETON too, so loading and loaded agree', () => {
+    const { container } = render(<Table data={[]} loading rowHeightClassName={ROW_H} />);
+    expect(new Set(heightClasses(container))).toEqual(new Set([ROW_H]));
+  });
+
+  it('reserves it for an EMPTY board, which is when a collapse is most visible', () => {
+    const { container } = render(<Table data={[]} rowHeightClassName={ROW_H} />);
+    expect(new Set(heightClasses(container))).toEqual(new Set([ROW_H]));
+  });
+
+  it('REPLACES the height rather than merging, so no md: default survives', () => {
+    const { container } = render(<Table data={rows(1)} rowHeightClassName={ROW_H} />);
+    const html = container.innerHTML;
+    // The exact leftover that made a caller-supplied height hold on a phone and
+    // lose on a desktop.
+    expect(html).not.toContain('md:h-[78px]');
+    expect(html).not.toContain('md:min-h-[78px]');
+  });
+
+  it('gives a pad row the same BORDER BOX as the row it stands in for', () => {
+    // A real row card draws a 1px border on each side, so its outer block is
+    // the inner height plus 2. A pad row without one is 2px shorter — nothing
+    // per row, 54px across a 27-row remainder.
+    const { container } = render(<Table data={rows(2)} rowHeightClassName={ROW_H} />);
+    const slots = slotClasses(container);
+
+    expect(slots.length).toBeGreaterThanOrEqual(4);
+    expect(slots.every(cls => cls.split(/\s+/).includes('border'))).toBe(true);
+  });
+
+  it('sizes the ROW SLOT, so a sub-row does not make real rows outgrow pad rows', () => {
+    // The trap: a row with a sub-row is taller than its cells. Sizing the cells
+    // left every pad row short by exactly the sub-row — 96px each on a phone
+    // board — which is the same jump `minRows` exists to prevent, reintroduced
+    // one level down.
+    const { container } = render(<TableWithSubRows data={rows(2)} rowHeightClassName={ROW_H} />);
+    const slots = slotClasses(container);
+
+    expect(slots.length).toBeGreaterThanOrEqual(4);
+    // Every card — the two real rows and the two pad rows — carries the height.
+    expect(slots.every(cls => cls.split(/\s+/).includes(ROW_H))).toBe(true);
+    // And the cells inside a real row FILL it rather than restating it, or the
+    // card would be the cells plus the sub-row.
+    expect(container.innerHTML).toContain('flex-1');
+  });
+
+  it('keeps the design height when a table does not state one', () => {
+    const { container } = render(<Table data={rows(1)} />);
+    expect(container.innerHTML).toContain('md:h-[78px]');
+  });
+});
+
+describe('EntityImage size', () => {
+  it('SUBSTITUTES the default size, leaving no responsive half behind', () => {
+    const { container } = render(<EntityImage src="https://example.test/a.png" alt="A" sizeClassName="size-6" />);
+    const html = container.innerHTML;
+    expect(html).toContain('size-6');
+    // `h-4 w-6` through className used to leave this behind, which is the whole
+    // bug: 16px on a phone, 60px on a desktop.
+    expect(html).not.toContain('md:size-[60px]');
+    expect(html).not.toContain('size-[52px]');
+  });
+
+  it('applies the same substitution to the initials fallback', () => {
+    const { container } = render(<EntityImage src={null} alt="New York" sizeClassName="size-6" />);
+    const html = container.innerHTML;
+    expect(html).toContain('size-6');
+    expect(html).not.toContain('md:size-[60px]');
+  });
+
+  it('keeps the design size when a caller does not state one', () => {
+    const { container } = render(<EntityImage src={null} alt="New York" />);
+    expect(container.innerHTML).toContain('md:size-[60px]');
+  });
+});

package/src/__tests__/mlg-platform-leaves.test.ts

@@ -131,7 +131,7 @@ describe('common leaf', () => {
     expect(clamp(5, 1, 3)).toBe(3);
     expect(clamp(-5, 1, 3)).toBe(1);
     expect(pick({ a: 1, b: 2, c: 3 }, ['a', 'c'])).toEqual({ a: 1, c: 3 });
-    expect(pick({ a: undefined } as { a: number | undefined }, ['a'])).toEqual({ a: undefined });
+    expect(pick({ a: undefined }, ['a'])).toEqual({ a: undefined });
   });
   it('states the no-client-cache rule once', () => {
     expect(NO_CLIENT_CACHE).toEqual({ staleTime: 0 });

package/src/components/ui/data-table/data-table-body.tsx

@@ -30,6 +30,23 @@ export interface DataTableBodyProps<T = unknown> {
    * the row instead of clipping. Default keeps the fixed height.
    */
   autoHeight?: boolean;
+  /**
+   * REPLACES the design row height for THIS table's rows, its pad rows and its
+   * skeleton alike — one number, so they cannot disagree.
+   *
+   * Why a prop and not a className: `minRows` promises a stable table height,
+   * but its pad rows and the skeleton were hard-coded to the design height
+   * while a row passing `autoHeight` renders as tall as its content. A table
+   * with 112px rows padded a short page with 78px placeholders and came up
+   * 34px per missing row too short — on a 15-row page with 5 results, 340px of
+   * jump against every other page. Appending a height through `rowClassName`
+   * cannot fix it either: tailwind-merge drops the plain `h-[66px]` but keeps
+   * the `md:h-[78px]` beside it, so the override holds on a phone and loses on
+   * a desktop. Pass it here and every row slot in the table agrees.
+   *
+   * Responsive values belong in the string itself, e.g. `'h-[200px] md:h-[112px]'`.
+   */
+  rowHeightClassName?: string;
   /**
    * Click anywhere on a row (except elements with `data-no-row-click`). Prefer
    * `useCallback` to avoid breaking `React.memo` on rows.
@@ -68,6 +85,7 @@ export function DataTableBody<T = unknown>({
   rowClassName,
   compact,
   autoHeight,
+  rowHeightClassName,
   onRowClick,
   rowHref,
   minRows,
@@ -79,7 +97,7 @@ export function DataTableBody<T = unknown>({
   if (loading && rows.length === 0) {
     return (
       <div className={cn('flex w-full flex-col gap-[var(--spacing-system-xsf)]', className)}>
-        <DataTableSkeleton rows={skeletonRows} />
+        <DataTableSkeleton rows={skeletonRows} rowHeightClassName={rowHeightClassName} />
       </div>
     );
   }
@@ -100,7 +118,7 @@ export function DataTableBody<T = unknown>({
     if (minRows) {
       return (
         <div className={cn('relative flex w-full flex-col gap-[var(--spacing-system-xsf)]', className)}>
-          <PlaceholderRows count={minRows} />
+          <PlaceholderRows count={minRows} rowHeightClassName={rowHeightClassName} />
           <div className="absolute inset-0 flex items-center justify-center">{empty}</div>
         </div>
       );
@@ -125,12 +143,13 @@ export function DataTableBody<T = unknown>({
             href={href}
             compact={compact}
             autoHeight={autoHeight}
+            rowHeightClassName={rowHeightClassName}
             className={cls}
             subRow={renderSubRow?.(item)}
           />
         );
       })}
-      {padCount > 0 && <PlaceholderRows count={padCount} />}
+      {padCount > 0 && <PlaceholderRows count={padCount} rowHeightClassName={rowHeightClassName} />}
     </div>
   );
 }
@@ -142,17 +161,37 @@ export function DataTableBody<T = unknown>({
  * sites use it, so a padded page and an empty one are the same height by
  * construction rather than by two matching guesses.
  */
-function PlaceholderRows({ count }: { count: number }) {
+function PlaceholderRows({ count, rowHeightClassName }: { count: number; rowHeightClassName?: string }) {
   return (
     <>
       {Array.from({ length: count }).map((_, i) => (
         <div
           key={`placeholder-${i}`}
-          className="pointer-events-none relative overflow-hidden rounded-md"
+          // `border-transparent`, not no border: a real row card draws a 1px
+          // border on each side, so its outer block is the inner height PLUS 2.
+          // A pad row without one is 2px shorter than the row it stands in for
+          // — invisible per row, 54px over a 27-row remainder, which is the
+          // same shift `minRows` exists to prevent.
+          className={cn(
+            'pointer-events-none relative overflow-hidden rounded-md border border-transparent',
+            // The stated slot height belongs on the CARD, exactly as a real
+            // row carries it — a real row with a sub-row is taller than its
+            // cells, so reserving the cells' height here left every pad row
+            // short by the sub-row.
+            rowHeightClassName,
+          )}
           aria-hidden="true"
         >
-          <div className={cn('hidden py-0 md:flex', ROW_SHELL_CLASSES, ROW_HEIGHT_DESKTOP)} />
-          <div className={cn('flex justify-start py-0 md:hidden', ROW_SHELL_CLASSES, ROW_HEIGHT_MOBILE)} />
+          <div
+            className={cn('hidden py-0 md:flex', ROW_SHELL_CLASSES, rowHeightClassName ? 'h-full' : ROW_HEIGHT_DESKTOP)}
+          />
+          <div
+            className={cn(
+              'flex justify-start py-0 md:hidden',
+              ROW_SHELL_CLASSES,
+              rowHeightClassName ? 'h-full' : ROW_HEIGHT_MOBILE,
+            )}
+          />
         </div>
       ))}
     </>

package/src/components/ui/data-table/data-table-row.tsx

@@ -20,6 +20,18 @@ export interface DataTableRowProps<T> {
    * clipped. Default keeps the fixed height.
    */
   autoHeight?: boolean;
+  /**
+   * REPLACES the height this row would otherwise take (`compact`, `autoHeight`
+   * or the design default). The one place a table states how tall a row is, so
+   * the pad rows and the skeleton can reserve the SAME number — see
+   * `DataTableBodyProps.rowHeightClassName`.
+   *
+   * It sizes the row SLOT — the whole card — not the cells inside it. A row
+   * with a `subRow` is taller than its cells, so sizing the cells would leave
+   * the pad rows (which have no sub-row) short by exactly the sub-row: on a
+   * phone board that was 96px per missing row.
+   */
+  rowHeightClassName?: string;
   className?: string;
   /** Expandable content rendered below the cells, inside the same card. */
   subRow?: ReactNode;
@@ -62,7 +74,16 @@ export interface DataTableRowProps<T> {
  * for `onClick` and `className` (if function) via `useCallback` / `useMemo` in
  * the consumer. `href` and string `className` are compared by value.
  */
-function DataTableRowImpl<T>({ row, onClick, href, compact, autoHeight, className, subRow }: DataTableRowProps<T>) {
+function DataTableRowImpl<T>({
+  row,
+  onClick,
+  href,
+  compact,
+  autoHeight,
+  rowHeightClassName,
+  className,
+  subRow,
+}: DataTableRowProps<T>) {
   const hasSubRow = subRow != null && subRow !== false;
   // A sub-row carries its own interactive controls, so it must not live inside the
   // row-level <Link>; when present, the link wraps only the cells.
@@ -90,7 +111,11 @@ function DataTableRowImpl<T>({ row, onClick, href, compact, autoHeight, classNam
   );
 
   const containerClassName = cn(
-    'block overflow-hidden rounded-md border border-ods-border bg-ods-card text-inherit no-underline',
+    'overflow-hidden rounded-md border border-ods-border bg-ods-card text-inherit no-underline',
+    // A stated slot height goes HERE, on the card, with the cells flexing to
+    // fill whatever the sub-row leaves. `border-box` sizing means the number a
+    // caller writes is the number the row occupies, borders included.
+    rowHeightClassName ? `flex flex-col ${rowHeightClassName}` : 'block',
     // With a sub-row the link wraps only the cells, so keep the clickable affordance off the whole card.
     (onClick || isWholeCardLink) && 'cursor-pointer transition-colors hover:bg-ods-bg-active',
     className,
@@ -101,11 +126,13 @@ function DataTableRowImpl<T>({ row, onClick, href, compact, autoHeight, classNam
       className={cn(
         'flex',
         ROW_SHELL_CLASSES,
-        compact
-          ? 'py-[var(--spacing-system-xsf)]'
-          : autoHeight
-            ? 'min-h-[66px] py-[var(--spacing-system-sf)] md:min-h-[78px]'
-            : `py-0 ${ROW_HEIGHT_DESKTOP}`,
+        rowHeightClassName
+          ? 'min-h-0 flex-1 py-0'
+          : compact
+            ? 'py-[var(--spacing-system-xsf)]'
+            : autoHeight
+              ? 'min-h-[66px] py-[var(--spacing-system-sf)] md:min-h-[78px]'
+              : `py-0 ${ROW_HEIGHT_DESKTOP}`,
         hasSubRow && 'border-b border-ods-border',
       )}
     >
@@ -153,7 +180,10 @@ function DataTableRowImpl<T>({ row, onClick, href, compact, autoHeight, classNam
         <Link
           href={href}
           prefetch={false}
-          className="block cursor-pointer text-inherit no-underline transition-colors hover:bg-ods-bg-active"
+          className={cn(
+            'cursor-pointer text-inherit no-underline transition-colors hover:bg-ods-bg-active',
+            rowHeightClassName ? 'flex min-h-0 flex-1 flex-col' : 'block',
+          )}
           onClick={handleClick}
         >
           {cells}

package/src/components/ui/data-table/data-table-skeleton.tsx

@@ -29,9 +29,17 @@ export interface DataTableSkeletonProps {
   rows?: number;
   className?: string;
   rowClassName?: string;
+  /**
+   * REPLACES the design row height, for a table whose rows are not that tall.
+   * Sizes the CARD, as a real row does.
+   * Appending a height through `rowClassName` cannot do this: tailwind-merge
+   * drops the plain `h-[66px]` but keeps `md:h-[78px]`, so the override held
+   * on a phone and lost on a desktop. See `DataTableBodyProps.rowHeightClassName`.
+   */
+  rowHeightClassName?: string;
 }
 
-export function DataTableSkeleton({ rows = 10, className, rowClassName }: DataTableSkeletonProps) {
+export function DataTableSkeleton({ rows = 10, className, rowClassName, rowHeightClassName }: DataTableSkeletonProps) {
   const table = useDataTableContext();
   const columns = table.getVisibleFlatColumns();
   const firstColumnId = columns[0]?.id;
@@ -43,10 +51,19 @@ export function DataTableSkeleton({ rows = 10, className, rowClassName }: DataTa
           key={index}
           className={cn(
             'relative animate-pulse overflow-hidden rounded-md border border-ods-border bg-ods-card',
+            // The slot height sits on the card, matching a real row.
+            rowHeightClassName,
             className,
           )}
         >
-          <div className={cn('hidden py-0 md:flex', ROW_SHELL_CLASSES, ROW_HEIGHT_DESKTOP, rowClassName)}>
+          <div
+            className={cn(
+              'hidden py-0 md:flex',
+              ROW_SHELL_CLASSES,
+              rowHeightClassName ? 'h-full' : ROW_HEIGHT_DESKTOP,
+              rowClassName,
+            )}
+          >
             {columns.map(column => {
               const meta = column.columnDef.meta;
               return (
@@ -71,7 +88,14 @@ export function DataTableSkeleton({ rows = 10, className, rowClassName }: DataTa
               );
             })}
           </div>
-          <div className={cn('flex justify-start py-0 md:hidden', ROW_SHELL_CLASSES, ROW_HEIGHT_MOBILE, rowClassName)}>
+          <div
+            className={cn(
+              'flex justify-start py-0 md:hidden',
+              ROW_SHELL_CLASSES,
+              rowHeightClassName ? 'h-full' : ROW_HEIGHT_MOBILE,
+              rowClassName,
+            )}
+          >
             <div className="flex min-w-0 flex-1 flex-col justify-center py-[var(--spacing-system-sf)]">
               <div className="mb-[var(--spacing-system-xsf)] h-4 w-3/4 rounded-sm bg-ods-bg-surface" />
               <div className="h-3 w-1/2 rounded-sm bg-ods-bg-surface opacity-60" />