react-semaphor 0.1.526 → 0.1.527

package/dist/types/shared/temporal/calendar-periods.d.ts

@@ -0,0 +1,56 @@
+import { CalendarContext } from '../report-runtime-context/index.js';
+import { ZonedWallClockTime } from './zoned-wall-clock.js';
+/** The units a period or a shift counts in. */
+export type TemporalUnit = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+/**
+ * What period math reads from a calendar. The anchor ("now") is never read
+ * here: callers pass the instant they resolve against.
+ */
+export type TemporalCalendar = Pick<CalendarContext, 'tz' | 'weekStart' | 'fiscalCalendar'>;
+/** Every instant from `start` up to, not including, `endExclusive`. */
+export type TemporalPeriod = {
+    start: Date;
+    endExclusive: Date;
+};
+/** A wall-clock time with every field set. */
+export type WallClockTime = Required<ZonedWallClockTime>;
+/** Units measured as elapsed time rather than on the calendar, in milliseconds. */
+export declare const ELAPSED_UNIT_MILLISECONDS: Partial<Record<TemporalUnit, number>>;
+/** The wall clock at an instant, with its milliseconds (offsets are whole seconds). */
+export declare function wallClockAt(instant: Date, tz: string): WallClockTime;
+/** The instant a wall clock names, under the daylight-saving rule (K7). */
+export declare function instantAt(wall: ZonedWallClockTime, tz: string): Date;
+export declare function daysInMonth(year: number, month: number): number;
+/**
+ * The wall clock moved by whole units, keeping the time of day for calendar
+ * units and clamping the day for months, quarters and years (January 31 plus
+ * one month is February 28), as date-fns does.
+ */
+export declare function shiftWallClock(wall: WallClockTime, amount: number, unit: TemporalUnit): WallClockTime;
+/** The weekday of a wall date, 0 for Sunday. */
+export declare function wallWeekday(wall: Pick<WallClockTime, 'year' | 'month' | 'day'>): number;
+/**
+ * The period `offset` periods from the one containing `instant` (0 for that
+ * period, -1 for the one before). Calendar periods are found in the wall
+ * clock, so a day that starts after a skipped midnight starts when it does
+ * (K7). Seconds, minutes and hours count elapsed time from the instant's own
+ * occurrence, so a repeated hour is two periods.
+ */
+export declare function periodAt(instant: Date, unit: TemporalUnit, calendar: TemporalCalendar, offset?: number): TemporalPeriod;
+/** Where the period containing `instant` starts. */
+export declare function startOfPeriod(instant: Date, unit: TemporalUnit, calendar: TemporalCalendar): Date;
+/** The last millisecond of the period containing `instant`. */
+export declare function endOfPeriod(instant: Date, unit: TemporalUnit, calendar: TemporalCalendar): Date;
+/**
+ * The instant moved by whole units in the calendar's wall clock, keeping its
+ * time of day (see `shiftWallClock`).
+ */
+export declare function shiftInstant(instant: Date, amount: number, unit: TemporalUnit, calendar: Pick<TemporalCalendar, 'tz'>): Date;
+/** Calendar days from `start`'s date to `end`'s date in the timezone. */
+export declare function calendarDaysBetween(start: Date, end: Date, tz: string): number;
+/** `YYYY-MM-DD` of the instant's wall date in the timezone. */
+export declare function formatWallDate(instant: Date, tz: string): string;
+/** The fields of a `YYYY-MM-DD` date that names a real day, else null. */
+export declare function parseWallDate(value: string): Pick<WallClockTime, 'year' | 'month' | 'day'> | null;
+/** The day a `YYYY-MM-DD` date names in the timezone, or null when it names none. */
+export declare function wallDatePeriod(value: string, tz: string): TemporalPeriod | null;

package/dist/types/shared/temporal/index.d.ts

@@ -0,0 +1,5 @@
+export * from './zoned-wall-clock.js';
+export * from './calendar-periods.js';
+export * from './relative-date.js';
+export * from './time-window-periods.js';
+export * from './temporal-parity-fixtures.js';

package/dist/types/shared/temporal/relative-date.d.ts

@@ -0,0 +1,21 @@
+import { RelativeDateFilter } from '../analytics-protocol/relative-date-filter.js';
+import { TemporalCalendar } from './calendar-periods.js';
+/** A resolved window: `end` is the inclusive last instant. */
+export type ResolvedRelativeDate = {
+    start: Date;
+    end: Date;
+};
+/**
+ * The window a relative date names at `anchor` in the calendar:
+ * - `last` n units: the n units back to the anchor, the same wall-clock time
+ *   n units earlier (minutes and hours count elapsed time); with `complete`,
+ *   the n whole periods before the one containing the anchor;
+ * - `this`: the period containing the anchor, or up to the anchor with
+ *   `toDate`; a month `boundary` names its first or last day (months only);
+ * - `previous`: the period before;
+ * - `between` from/to: from the start of the `from` period to the end of the
+ *   `to` period, counted from the anchor's.
+ * Weeks start on the calendar's week start; quarters and years follow its
+ * fiscal calendar when it has one.
+ */
+export declare function resolveRelativeDate(relative: RelativeDateFilter, calendar: TemporalCalendar, anchor: Date): ResolvedRelativeDate;

package/dist/types/shared/temporal/temporal-parity-fixtures.d.ts

@@ -0,0 +1,73 @@
+import { RelativeDateFilter } from '../analytics-protocol/relative-date-filter.js';
+import { WeekStart } from '../report-runtime-context/index.js';
+import { TemporalUnit } from './calendar-periods.js';
+import { ZonedWallClockTime } from './zoned-wall-clock.js';
+/** A relative date resolved at an anchor: `[start, inclusive end]`. */
+export type TemporalParityRelativeCase = {
+    tz: string;
+    weekStart: WeekStart;
+    /** The month-aligned fiscal year's first month, when the calendar has one. */
+    fiscalStart?: number;
+    anchor: string;
+    relative: RelativeDateFilter;
+    expected: [string, string];
+    /**
+     * The browser's old result where it differed, and the rule that changed
+     * it: `fiscal_periods`, the browser ignored the fiscal calendar for
+     * quarters and years. Previews still show those as labels only (K8).
+     */
+    browser?: {
+        old: [string, string];
+        rule: 'fiscal_periods';
+    };
+};
+/** An instant moved by whole units in the timezone's wall clock. */
+export type TemporalParityShiftCase = {
+    tz: string;
+    at: string;
+    unit: TemporalUnit;
+    amount: number;
+    expected: string;
+};
+/** The period containing an instant: `[start, endExclusive]`. */
+export type TemporalParityPeriodCase = {
+    tz: string;
+    at: string;
+    unit: TemporalUnit;
+    weekStart?: WeekStart;
+    expected: [string, string];
+};
+/**
+ * A daylight-saving case (K7): the instant a wall clock names, or the period
+ * containing an instant. `before` is the old result, which depended on
+ * date-fns-tz's offset guess: a repeated hour took its second occurrence east
+ * of UTC, a skipped hour moved back, and a day starting after a skipped
+ * midnight started an hour early.
+ */
+export type TemporalParityDaylightCase = {
+    kind: 'instant';
+    tz: string;
+    wall: ZonedWallClockTime;
+    expected: string;
+    before: string;
+} | {
+    kind: 'period';
+    tz: string;
+    at: string;
+    unit: TemporalUnit;
+    expected: [string, string];
+    before: [string, string];
+};
+/**
+ * The parity grid (analytics kernel Phase 3): units, modes, the six
+ * timezones, week starts 0 to 6, fiscal start months 1 to 12 and four
+ * anchors. Both repos run it: react-semaphor against `shared/temporal`, and
+ * semaphor-app against the server functions that delegate to it. Built by a
+ * pure call, so a bundle that doesn't use it drops it.
+ */
+export declare const TEMPORAL_PARITY_FIXTURES: {
+    relative: TemporalParityRelativeCase[];
+    shifts: TemporalParityShiftCase[];
+    periods: TemporalParityPeriodCase[];
+    daylight: TemporalParityDaylightCase[];
+};

package/dist/types/shared/temporal/time-window-periods.d.ts

@@ -0,0 +1,21 @@
+import { TemporalCalendar, TemporalUnit } from './calendar-periods.js';
+/** A rolling window's length: `value` units. */
+export type TemporalSpan = {
+    unit: TemporalUnit;
+    value: number;
+};
+/**
+ * Where a window of `span` ending at `end` starts: elapsed time for seconds,
+ * minutes and hours; the same wall-clock time `value` units earlier for
+ * calendar units.
+ */
+export declare function subtractTimeSpan(end: Date, span: TemporalSpan, calendar: TemporalCalendar): Date;
+/** The `value` whole periods before the one containing `latest`. */
+export type CompletePeriodWindow = {
+    windowStart: Date;
+    /** The inclusive last instant: the millisecond before `latest`'s period. */
+    windowEnd: Date;
+    /** Whether `latest`'s own period, which is partial, was left out. */
+    excludedPartialPeriod: boolean;
+};
+export declare function completePeriodWindow(latest: Date, span: TemporalSpan, calendar: TemporalCalendar): CompletePeriodWindow;

package/dist/types/shared/temporal/zoned-wall-clock.d.ts

@@ -0,0 +1,23 @@
+export type ZonedWallClock = {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+};
+export declare function zonedWallClock(instant: Date, tz: string): ZonedWallClock;
+/** A wall-clock time, with optional milliseconds. */
+export type ZonedWallClockTime = ZonedWallClock & {
+    millisecond?: number;
+};
+/** The wall clock as if it were UTC, in milliseconds. */
+export declare function wallClockMilliseconds(wall: ZonedWallClockTime): number;
+/**
+ * The instant a wall-clock time names in a timezone (analytics kernel K7). A
+ * repeated hour takes its first occurrence; a skipped hour moves forward by
+ * the gap, as JavaScript's Temporal API and java.time do by default. The
+ * offsets a day either side cover any one change, and no offset reaches a
+ * day, so the answer never depends on the machine.
+ */
+export declare function zonedWallClockToInstant(wall: ZonedWallClockTime, tz: string): Date;

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.526",
+  "version": "0.1.527",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",
@@ -72,22 +72,6 @@
       "types": "./dist/types/data-app-sdk-validation.d.ts",
       "import": "./dist/data-app-sdk-validation/index.js"
     },
-    "./data-app-codegen": {
-      "types": "./dist/types/data-app-codegen.d.ts",
-      "import": "./dist/data-app-codegen/index.js"
-    },
-    "./data-app-codegen/node": {
-      "types": "./dist/types/data-app-codegen-node.d.ts",
-      "import": "./dist/data-app-codegen-node/index.js"
-    },
-    "./data-app-builder": {
-      "types": "./dist/types/data-app-builder.d.ts",
-      "import": "./dist/data-app-builder/index.js"
-    },
-    "./data-app-builder/browser-runtime": {
-      "types": "./dist/types/data-app-builder-browser-runtime.d.ts",
-      "import": "./dist/data-app-builder-browser-runtime/index.js"
-    },
     "./appearance": {
       "types": "./dist/types/appearance.d.ts",
       "import": "./dist/appearance/index.js"

package/src/data-app-sdk/README.md

@@ -1,8 +1,11 @@
 # Data App SDK Quick Reference
 
-Use this file as the public contract quick reference for generated Semaphor
-Data Apps. Do not inspect SDK implementation internals to discover these
-patterns.
+> Frozen: no new work goes into this SDK. A replacement built on the shared
+> analytics protocol replaces it in place (semaphor-app
+> `docs/implementation-plans/analytics-mcp-and-sdk/PLAN-3-ANALYTICS-SDK.md`).
+
+Use this file as the public contract quick reference for Data App SDK code.
+Do not inspect SDK implementation internals to discover these patterns.
 
 ## Imports