@everystack/admin 0.4.5 → 0.4.7

package/src/utils/view-filters.ts

@@ -6,7 +6,7 @@
  * AnalyticsHeader's DashboardFilters and the CRUD table's PostgREST conditions.
  */
 
-import type { ViewParams } from '../hooks/useViewState';
+import type { ViewParams, ViewParamValues } from '../hooks/useViewState';
 import type { DimensionConfig, ResourceDashboardConfig } from '../types';
 import type { DashboardFilters } from '../rpc/resource-dashboard-rpc';
 
@@ -39,7 +39,9 @@ export function filtersToParams(filters: DashboardFilters, dimensions: Dimension
 }
 
 /** Query params reserved for view state (not column filters). */
-export const RESERVED_PARAMS: ReadonlySet<string> = new Set(['from', 'to', 'sort', 'dir', 'page', 'size', 'q', 'tab']);
+export const RESERVED_PARAMS: ReadonlySet<string> = new Set([
+  'from', 'to', 'sort', 'dir', 'page', 'size', 'q', 'tab',
+]);
 
 /**
  * Pass-through column filters: any query param that names a real resource field
@@ -51,11 +53,15 @@ export function paramsToColumnFilters(
   params: ViewParams,
   fieldNames: Set<string>,
   exclude: Set<string> = new Set(),
+  paramValues?: ViewParamValues,
 ): Record<string, unknown> {
   const f: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(params)) {
     if (RESERVED_PARAMS.has(k) || exclude.has(k)) continue;
-    if (fieldNames.has(k) && v) f[k] = v;
+    if (!fieldNames.has(k)) continue;
+    const values = paramValues?.[k] ?? [v];
+    if (values.length > 1) f[k] = values;
+    else if (values.length === 1 && values[0]) f[k] = values[0];
   }
   return f;
 }

package/src/utils/wall-clock.ts

@@ -0,0 +1,72 @@
+/**
+ * Wall-clock datetime fields (`type: 'datetime', timezone, storage: 'wall'`): a naive `timestamp`
+ * column holding "this wall-clock time in one business zone". The API carries the stored digits
+ * labelled `Z`; these helpers read those digits literally and never through the viewer's zone.
+ */
+
+import { assertTimeZone, partsToWall, wallTimeExists, wallToParts, zoneAbbreviation } from '@everystack/ui/wall-time';
+import type { AdminConfig, FieldDefinition, FieldDefinitionBase, WallClockDatetime } from '../types';
+
+export type WallClockField = FieldDefinitionBase & WallClockDatetime;
+
+export function isWallClock(field: FieldDefinition): field is WallClockField {
+  return field.storage === 'wall';
+}
+
+/**
+ * A wall value as the string the input and the parser read. A native Date (a custom adapter's
+ * prerogative) carries the digits as its UTC fields, the same as the `Z`-labelled string.
+ */
+function wallString(value: unknown): unknown {
+  return value instanceof Date && !Number.isNaN(value.getTime()) ? value.toISOString() : value;
+}
+
+/**
+ * The stored digits, formatted with no zone shift (a Date built from the digits as UTC, shown in
+ * UTC), then the business zone's abbreviation. An unparseable value passes through untouched.
+ */
+export function formatWallClock(field: WallClockField, value: unknown): string {
+  const parts = wallToParts(wallString(value));
+  if (!parts) return String(value);
+  const digits = new Date(partsToWall(parts)).toLocaleString(undefined, { timeZone: 'UTC' });
+  return `${digits} ${zoneAbbreviation(parts, field.timezone)}`;
+}
+
+/**
+ * The field error for a wall value the business zone's clocks skip (a spring-forward gap), or
+ * null. An overlap time exists (twice) and is accepted as typed. An empty or unparseable value
+ * is not this check's concern.
+ */
+export function wallClockError(field: FieldDefinition, value: unknown): string | null {
+  if (!isWallClock(field)) return null;
+  const parts = wallToParts(wallString(value));
+  if (!parts || wallTimeExists(parts, field.timezone)) return null;
+  return `${field.label ?? field.name} does not exist in ${field.timezone}: clocks skip that time. Pick another time.`;
+}
+
+/**
+ * Checks every field's wall-clock options at setup, loudly: a `timezone` needs `storage: 'wall'`
+ * on a `datetime` field and must be a time zone this engine knows. Config can arrive untyped,
+ * so the TypeScript union is not enough on its own.
+ */
+export function validateWallClockFields(config: AdminConfig): void {
+  for (const resource of config.resources ?? []) {
+    for (const field of resource.fields ?? []) {
+      const raw = field as { name: string; type: unknown; timezone?: unknown; storage?: unknown };
+      if (raw.timezone === undefined && raw.storage === undefined) continue;
+      const where = `Admin resource "${resource.name}", field "${raw.name}"`;
+      if (raw.type !== 'datetime') {
+        throw new TypeError(`${where}: timezone and storage are only for a datetime field, not type ${JSON.stringify(raw.type)}`);
+      }
+      if (raw.storage === 'utc' && raw.timezone === undefined) continue;
+      if (raw.storage !== 'wall') {
+        throw new TypeError(`${where}: a timezone needs storage: 'wall' (a naive timestamp column), got storage ${JSON.stringify(raw.storage)}`);
+      }
+      try {
+        assertTimeZone(raw.timezone as string);
+      } catch (err) {
+        throw new RangeError(`${where}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+  }
+}