@stigmer/react 3.5.3 → 3.7.0

package/schedule/ScheduleRunsTable.js

@@ -0,0 +1,161 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { cn } from "@stigmer/theme";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { ScheduleRunOrigin, ScheduleRunOutcome, } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/io_pb";
+import { formatRelativeTime } from "../activity/format-relative-time.js";
+import { ErrorMessage } from "../error/ErrorMessage.js";
+import { Pagination } from "../internal/Pagination.js";
+import { useScheduleRuns } from "./useScheduleRuns.js";
+/**
+ * Paginated run-history table for a schedule — the fire ledger,
+ * rendered in full (project DD-017 D-7).
+ *
+ * Every fire leaves a row, INCLUDING fires that created no execution (a
+ * refused launch gate, a missing target agent), carrying the refusing
+ * gate's copy verbatim. Columns: outcome, origin, fired time (relative,
+ * with the absolute instant on hover), duration (recorded → completed;
+ * "—" while a run is in flight or when no run was created), and the
+ * execution reference.
+ *
+ * Owns its data: give it a `scheduleId` and it fetches via
+ * {@link useScheduleRuns} with internal page state. To force a refresh
+ * from outside (e.g. after triggering a manual run), remount with a
+ * React `key` — the standard reset idiom (DD-014); the remount also
+ * returns to page 1, where the new run appears.
+ *
+ * Handles loading, error, and empty states automatically.
+ * Zero Console dependencies — safe for platform builder embedding.
+ * All visual properties flow through `--stgm-*` design tokens.
+ *
+ * @example
+ * ```tsx
+ * <ScheduleRunsTable
+ *   scheduleId={schedule.metadata.id}
+ *   onNavigateToExecution={(id) => router.push(`/executions/${id}`)}
+ * />
+ * ```
+ */
+export function ScheduleRunsTable({ scheduleId, onNavigateToExecution, now, pageSize = 25, className, }) {
+    const [pageNum, setPageNum] = useState(1);
+    const { runs, totalCount, isLoading, error, refetch } = useScheduleRuns(scheduleId, { page: pageNum, pageSize });
+    if (error) {
+        return _jsx(ErrorMessage, { error: error, retry: refetch, className: className });
+    }
+    if (isLoading && runs.length === 0) {
+        return (_jsx("div", { className: cn("space-y-2", className), "aria-busy": "true", children: Array.from({ length: 5 }, (_, i) => (_jsx("div", { className: "h-9 animate-pulse rounded-lg bg-muted-subtle" }, i))) }));
+    }
+    if (runs.length === 0) {
+        return (_jsx("div", { className: className, children: _jsx(EmptyRuns, {}) }));
+    }
+    const renderNow = now ?? new Date();
+    const totalPages = Math.ceil(totalCount / pageSize);
+    return (_jsxs("div", { className: className, children: [_jsxs("div", { role: "table", "aria-label": "Run history", className: "overflow-hidden rounded-lg border border-border", children: [_jsxs("div", { role: "row", className: cn(rowGridClasses, "border-b border-border px-3.5 py-2 text-[0.65rem] font-medium uppercase tracking-wider text-muted-foreground"), children: [_jsx("span", { role: "columnheader", children: "Outcome" }), _jsx("span", { role: "columnheader", className: "hidden sm:block", children: "Origin" }), _jsx("span", { role: "columnheader", children: "Fired" }), _jsx("span", { role: "columnheader", className: "hidden sm:block", children: "Duration" }), _jsx("span", { role: "columnheader", className: "text-right", children: "Execution" })] }), runs.map((run, i) => (_jsx(RunTableRow, { run: run, now: renderNow, onNavigateToExecution: onNavigateToExecution }, runKey(run, i))))] }), totalPages > 1 && (_jsx(Pagination, { pageNum: pageNum, totalPages: totalPages, onPageChange: setPageNum, ariaLabel: "Run history pagination", className: "mt-3" }))] }));
+}
+// Mobile keeps the three load-bearing columns (outcome, fired,
+// execution); origin and duration join at the sm breakpoint.
+const rowGridClasses = "grid grid-cols-[7rem_1fr_auto] items-center gap-x-4 sm:grid-cols-[7rem_5.5rem_1fr_5rem_minmax(0,12rem)]";
+function RunTableRow({ run, now, onNavigateToExecution, }) {
+    const fireDate = run.nominalFireTime
+        ? timestampDate(run.nominalFireTime)
+        : null;
+    const badge = runOutcomeBadge(run.outcome);
+    return (_jsxs("div", { role: "row", className: cn(rowGridClasses, "border-b border-border-muted px-3.5 py-2.5 last:border-b-0"), children: [_jsx("span", { role: "cell", children: _jsx("span", { className: cn("inline-flex items-center rounded-full px-2 py-0.5 text-[0.65rem] font-medium", badge.className), children: badge.label }) }), _jsx("span", { role: "cell", className: "hidden text-xs text-muted-foreground sm:block", children: runOriginLabel(run.origin) }), _jsx("span", { role: "cell", className: "text-xs text-muted-foreground", title: fireDate ? fireDate.toLocaleString() : undefined, children: fireDate ? formatRelativeTime(fireDate, now) : "—" }), _jsx("span", { role: "cell", className: "hidden text-xs tabular-nums text-muted-foreground sm:block", children: formatRunDuration(run) ?? "—" }), _jsx("span", { role: "cell", className: "min-w-0 text-right", children: run.executionId ? (onNavigateToExecution ? (_jsx("button", { type: "button", onClick: () => onNavigateToExecution(run.executionId), className: cn("max-w-full truncate font-mono text-[0.65rem] text-primary underline-offset-2 hover:underline", "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm"), children: run.executionId })) : (_jsx("span", { className: "font-mono text-[0.65rem] text-muted-foreground", children: run.executionId }))) : (_jsx("span", { className: "text-xs text-muted-foreground", children: "\u2014" })) }), run.reason && (_jsx("p", { role: "cell", className: "col-span-full mt-1 whitespace-pre-wrap break-words text-xs text-muted-foreground", children: run.reason }))] }));
+}
+// ---------------------------------------------------------------------------
+// Compact list — the Overview tab's "recent runs" strip
+// ---------------------------------------------------------------------------
+/**
+ * Compact run list: badge, origin, relative time, refusal reason, and
+ * execution link per row — the at-a-glance form used by the detail
+ * view's Overview tab. Presentational: runs come in as props (the
+ * caller owns the fetch, so one hook can also feed the Runs tab badge).
+ *
+ * Not barrel-exported: the public run-history surface is
+ * {@link ScheduleRunsTable}; this exists for the detail view's strip.
+ */
+export function ScheduleRunsCompactList({ runs, isLoading, now, onNavigateToExecution, }) {
+    if (isLoading && runs.length === 0) {
+        return (_jsxs("div", { className: "space-y-2 px-4 py-3", "aria-busy": "true", children: [_jsx("div", { className: "h-4 w-full animate-pulse rounded bg-muted" }), _jsx("div", { className: "h-4 w-3/4 animate-pulse rounded bg-muted" })] }));
+    }
+    if (runs.length === 0) {
+        return _jsx(EmptyRuns, {});
+    }
+    return (_jsx("ul", { className: "divide-y divide-border", children: runs.map((run, i) => (_jsx(CompactRunRow, { run: run, now: now, onNavigateToExecution: onNavigateToExecution }, runKey(run, i)))) }));
+}
+function CompactRunRow({ run, now, onNavigateToExecution, }) {
+    const fireDate = run.nominalFireTime
+        ? timestampDate(run.nominalFireTime)
+        : null;
+    const badge = runOutcomeBadge(run.outcome);
+    return (_jsxs("li", { className: "flex flex-col gap-1 px-4 py-2.5", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: cn("inline-flex items-center rounded-full px-2 py-0.5 text-[0.65rem] font-medium", badge.className), children: badge.label }), _jsx("span", { className: "text-xs text-muted-foreground", children: runOriginLabel(run.origin) }), _jsx("span", { className: "text-xs text-muted-foreground-subtle", children: "\u00B7" }), _jsx("span", { className: "text-xs text-muted-foreground", title: fireDate ? fireDate.toLocaleString() : undefined, children: fireDate ? formatRelativeTime(fireDate, now) : "—" })] }), run.reason && (_jsx("p", { className: "whitespace-pre-wrap break-words text-xs text-muted-foreground", children: run.reason })), run.executionId &&
+                (onNavigateToExecution ? (_jsx("button", { type: "button", onClick: () => onNavigateToExecution(run.executionId), className: cn("self-start font-mono text-[0.65rem] text-primary underline-offset-2 hover:underline", "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm"), children: run.executionId })) : (_jsx("span", { className: "self-start font-mono text-[0.65rem] text-muted-foreground", children: run.executionId })))] }));
+}
+// ---------------------------------------------------------------------------
+// Shared pieces
+// ---------------------------------------------------------------------------
+function EmptyRuns() {
+    return (_jsx("p", { className: "px-4 py-6 text-center text-xs text-muted-foreground", children: "No runs yet. Use \u201CRun now\u201D to fire a test run \u2014 every fire, including a refused one, is recorded here." }));
+}
+/**
+ * Stable row key from the fire ledger's natural identity
+ * (nominal fire time + origin), with the index as a collision tail.
+ */
+function runKey(run, index) {
+    const fireMs = run.nominalFireTime
+        ? timestampDate(run.nominalFireTime).getTime()
+        : "no-time";
+    return `${fireMs}-${run.origin}-${index}`;
+}
+function runOriginLabel(origin) {
+    return origin === ScheduleRunOrigin.MANUAL ? "Manual" : "Scheduled";
+}
+/** Verbatim-label badges for a run outcome, colored by health. */
+export function runOutcomeBadge(outcome) {
+    switch (outcome) {
+        case ScheduleRunOutcome.STARTED:
+            return { label: "Started", className: "bg-info/10 text-info" };
+        case ScheduleRunOutcome.COMPLETED:
+            return { label: "Completed", className: "bg-success/10 text-success" };
+        case ScheduleRunOutcome.REFUSED:
+            return { label: "Refused", className: "bg-warning/10 text-warning" };
+        case ScheduleRunOutcome.TARGET_MISSING:
+            return { label: "Target missing", className: "bg-warning/10 text-warning" };
+        case ScheduleRunOutcome.SKIPPED:
+            return { label: "Skipped", className: "bg-muted text-muted-foreground" };
+        case ScheduleRunOutcome.FAILED:
+            return { label: "Failed", className: "bg-destructive/10 text-destructive" };
+        case ScheduleRunOutcome.TIMED_OUT:
+            return { label: "Timed out", className: "bg-destructive/10 text-destructive" };
+        default:
+            return { label: "Unknown", className: "bg-muted text-muted-foreground" };
+    }
+}
+/**
+ * Wall-clock duration of a run, `recorded_at` → `completed_at`, in the
+ * compact unit style the schedule views use elsewhere (`42s`, `5m 12s`,
+ * `2h 3m`). `null` while the run is in flight or when the fire created
+ * no run at all — the caller renders the em-dash.
+ */
+function formatRunDuration(run) {
+    if (!run.recordedAt || !run.completedAt)
+        return null;
+    const ms = timestampDate(run.completedAt).getTime() -
+        timestampDate(run.recordedAt).getTime();
+    if (ms < 0)
+        return null;
+    const totalSeconds = Math.round(ms / 1000);
+    if (totalSeconds < 1)
+        return "<1s";
+    if (totalSeconds < 60)
+        return `${totalSeconds}s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    if (minutes < 60)
+        return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    const remMinutes = minutes % 60;
+    return remMinutes > 0 ? `${hours}h ${remMinutes}m` : `${hours}h`;
+}
+//# sourceMappingURL=ScheduleRunsTable.js.map

package/schedule/ScheduleRunsTable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScheduleRunsTable.js","sourceRoot":"","sources":["../../src/schedule/ScheduleRunsTable.tsx"],"names":[],"mappings":"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"}

package/schedule/TimeZoneField.d.ts

@@ -0,0 +1,32 @@
+/** Props for {@link TimeZoneField}. */
+export interface TimeZoneFieldProps {
+    /** Element ID, for association with an external `<label htmlFor>`. */
+    readonly id?: string;
+    /** The selected IANA time zone name. */
+    readonly value: string;
+    /** Called with the new zone when the user picks one. */
+    readonly onChange: (timeZone: string) => void;
+    /** Prevents interaction when `true`. */
+    readonly disabled?: boolean;
+}
+/**
+ * Searchable IANA time zone selector for the schedule form.
+ *
+ * The IANA database has ~400 zones — far too many for a plain
+ * `<select>` — so this follows the SDK's searchable-picker idiom
+ * (search input + listbox, as in `AgentPicker`): the input shows the
+ * selected zone; typing filters the list; Enter or click selects.
+ *
+ * The zone list comes from the runtime's own tz database
+ * (`Intl.supportedValuesOf`), which is also what {@link validateTimeZone}
+ * checks against — the offered choices and the accepted choices cannot
+ * drift.
+ *
+ * Internal to the schedule folder by design: public API surface is a
+ * contract, and this earns a barrel export only when a second consumer
+ * appears.
+ */
+export declare function TimeZoneField({ id, value, onChange, disabled, }: TimeZoneFieldProps): import("react/jsx-runtime").JSX.Element;
+/** The browser's own IANA time zone — the form's default. */
+export declare function browserTimeZone(): string;
+//# sourceMappingURL=TimeZoneField.d.ts.map

package/schedule/TimeZoneField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimeZoneField.d.ts","sourceRoot":"","sources":["../../src/schedule/TimeZoneField.tsx"],"names":[],"mappings":"AAWA,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,EAC5B,EAAE,EACF,KAAK,EACL,QAAQ,EACR,QAAQ,GACT,EAAE,kBAAkB,2CAsIpB;AAaD,6DAA6D;AAC7D,wBAAgB,eAAe,IAAI,MAAM,CAExC"}

package/schedule/TimeZoneField.js

@@ -0,0 +1,104 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useMemo, useRef, useState, } from "react";
+import { cn } from "@stigmer/theme";
+const LIST_ID = "stgm-timezone-list";
+const MAX_VISIBLE = 100;
+/**
+ * Searchable IANA time zone selector for the schedule form.
+ *
+ * The IANA database has ~400 zones — far too many for a plain
+ * `<select>` — so this follows the SDK's searchable-picker idiom
+ * (search input + listbox, as in `AgentPicker`): the input shows the
+ * selected zone; typing filters the list; Enter or click selects.
+ *
+ * The zone list comes from the runtime's own tz database
+ * (`Intl.supportedValuesOf`), which is also what {@link validateTimeZone}
+ * checks against — the offered choices and the accepted choices cannot
+ * drift.
+ *
+ * Internal to the schedule folder by design: public API surface is a
+ * contract, and this earns a barrel export only when a second consumer
+ * appears.
+ */
+export function TimeZoneField({ id, value, onChange, disabled, }) {
+    const zones = useMemo(() => allTimeZones(), []);
+    const [query, setQuery] = useState(null);
+    const [focusIndex, setFocusIndex] = useState(-1);
+    const listRef = useRef(null);
+    const isOpen = query !== null;
+    const filtered = useMemo(() => {
+        if (query === null)
+            return [];
+        const needle = query.trim().toLowerCase().replace(/\s+/g, "_");
+        const matches = needle
+            ? zones.filter((z) => z.toLowerCase().includes(needle))
+            : zones;
+        return matches.slice(0, MAX_VISIBLE);
+    }, [zones, query]);
+    const close = useCallback(() => {
+        setQuery(null);
+        setFocusIndex(-1);
+    }, []);
+    const select = useCallback((zone) => {
+        onChange(zone);
+        close();
+    }, [onChange, close]);
+    const handleKeyDown = useCallback((e) => {
+        if (e.key === "Escape") {
+            e.preventDefault();
+            close();
+            return;
+        }
+        if (!isOpen)
+            return;
+        if (e.key === "ArrowDown") {
+            e.preventDefault();
+            setFocusIndex((prev) => (prev < filtered.length - 1 ? prev + 1 : prev));
+        }
+        else if (e.key === "ArrowUp") {
+            e.preventDefault();
+            setFocusIndex((prev) => (prev > 0 ? prev - 1 : -1));
+        }
+        else if (e.key === "Enter") {
+            e.preventDefault();
+            if (focusIndex >= 0 && focusIndex < filtered.length) {
+                select(filtered[focusIndex]);
+            }
+            else if (filtered.length === 1) {
+                select(filtered[0]);
+            }
+        }
+    }, [isOpen, filtered, focusIndex, select, close]);
+    return (_jsxs("div", { className: "relative", children: [_jsx("input", { id: id, type: "text", role: "combobox", "aria-expanded": isOpen, "aria-controls": LIST_ID, "aria-activedescendant": focusIndex >= 0 ? `stgm-timezone-${focusIndex}` : undefined, "aria-label": "Time zone", placeholder: "Search time zones\u2026", value: query ?? value, onChange: (e) => {
+                    setQuery(e.target.value);
+                    setFocusIndex(-1);
+                }, onFocus: () => setQuery(""), 
+                // Closing on blur reverts the input to the committed value —
+                // free-typed text is never submitted, only list selections.
+                onBlur: close, onKeyDown: handleKeyDown, disabled: disabled, className: cn("w-full rounded-md border border-input bg-background px-2.5 py-1.5 text-xs text-foreground", "placeholder:text-muted-foreground", "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring", "disabled:pointer-events-none disabled:opacity-50") }), isOpen && (_jsx("div", { ref: listRef, id: LIST_ID, role: "listbox", "aria-label": "Time zones", className: cn("absolute z-popover mt-1 max-h-52 w-full overflow-y-auto rounded-md border border-border", "bg-popover p-1 text-popover-foreground shadow-md"), children: filtered.length === 0 ? (_jsx("div", { className: "py-3 text-center text-xs text-muted-foreground", children: "No time zones match" })) : (filtered.map((zone, idx) => (_jsx("button", { id: `stgm-timezone-${idx}`, type: "button", role: "option", "aria-selected": zone === value, 
+                    // Runs before the input's blur, so selection wins over
+                    // the close-on-blur revert.
+                    onMouseDown: (e) => {
+                        e.preventDefault();
+                        select(zone);
+                    }, className: cn("flex w-full items-center rounded-sm px-2 py-1.5 text-left text-xs transition-colors", idx === focusIndex
+                        ? "bg-accent text-foreground"
+                        : "text-popover-foreground hover:bg-accent-hover", zone === value && "font-medium"), children: zone }, zone)))) }))] }));
+}
+function allTimeZones() {
+    try {
+        return Intl.supportedValuesOf("timeZone");
+    }
+    catch {
+        // Pre-2022 runtimes without supportedValuesOf: offer the browser's
+        // own zone plus UTC rather than an empty list.
+        const own = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        return own && own !== "UTC" ? [own, "UTC"] : ["UTC"];
+    }
+}
+/** The browser's own IANA time zone — the form's default. */
+export function browserTimeZone() {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+}
+//# sourceMappingURL=TimeZoneField.js.map

package/schedule/TimeZoneField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimeZoneField.js","sourceRoot":"","sources":["../../src/schedule/TimeZoneField.tsx"],"names":[],"mappings":"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"}

package/schedule/cadence.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The cadence model behind {@link CadenceField} — a pure, dependency-free
+ * bridge between human-friendly schedule presets and the 5-field cron
+ * grammar the Schedule spec stores.
+ *
+ * Deliberately NOT a cron parser. The platform owns no cron parsing in
+ * either edition — calendar and DST semantics live in the Temporal server
+ * (see stigmer-server's schedule/controller/cron.go, DD-008 D2). This
+ * module only:
+ *
+ *   1. GENERATES cron strings from presets (`cadenceToCron`) — trivial
+ *      string construction, always valid by construction.
+ *   2. RECOGNIZES the exact shapes the builder emits (`cronToCadence`)
+ *      so a stored cron round-trips back into the preset UI; anything
+ *      else falls back to the `custom` preset showing the raw string.
+ *   3. MIRRORS the server's purely lexical validation (`validateCron`,
+ *      `validateTimeZone`) with the same user-facing wording, so the
+ *      form can reject bad input instantly. The server remains the
+ *      authority — its errors surface verbatim on submit.
+ */
+/** A human-friendly cadence, convertible to/from a cron expression. */
+export type CadencePreset = {
+    readonly kind: "hourly";
+    readonly minute: number;
+} | {
+    readonly kind: "daily";
+    readonly hour: number;
+    readonly minute: number;
+} | {
+    readonly kind: "weekly";
+    /** Days of week, cron numbering: 0 = Sunday … 6 = Saturday. */
+    readonly days: readonly number[];
+    readonly hour: number;
+    readonly minute: number;
+} | {
+    readonly kind: "monthly";
+    /** Day of month, 1–31. Days 29–31 skip months without that day. */
+    readonly day: number;
+    readonly hour: number;
+    readonly minute: number;
+} | {
+    readonly kind: "custom";
+    readonly cron: string;
+};
+/** Discriminant of {@link CadencePreset}. */
+export type CadenceKind = CadencePreset["kind"];
+/** Day-of-week labels indexed by cron numbering (0 = Sunday). */
+export declare const WEEKDAY_LABELS: readonly ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+/**
+ * Build the 5-field cron expression for a preset.
+ *
+ * Output is always valid by construction: numeric fields only,
+ * day-of-week in cron numbering (0 = Sunday). For `custom`, the raw
+ * string is returned as-is — validate it with {@link validateCron}.
+ */
+export declare function cadenceToCron(preset: CadencePreset): string;
+/**
+ * Recognize a cron expression as one of the builder's presets.
+ *
+ * Only the exact shapes {@link cadenceToCron} emits (plus the
+ * calendar shorthands `@hourly`/`@daily`/`@weekly`/`@monthly`) map to a
+ * structured preset. Everything else — ranges, steps, names, `@yearly`
+ * — is a perfectly valid schedule that this UI simply cannot decompose,
+ * so it round-trips as `custom` with the raw string intact.
+ */
+export declare function cronToCadence(cron: string): CadencePreset;
+/**
+ * Human-readable summary of a cadence, e.g.
+ * `"Every day at 09:00 (Asia/Kolkata)"`.
+ *
+ * This is a description of the chosen preset, not a computed fire-time
+ * forecast — the platform's next fire time is published by the server
+ * as `status.next_fire_at` after apply.
+ */
+export declare function describeCadence(preset: CadencePreset, timeZone?: string): string;
+/** `9, 5` → `"09:05"` (24-hour clock, zero-padded). */
+export declare function formatTime(hour: number, minute: number): string;
+/**
+ * Validate a cron expression against the platform's lexical grammar.
+ *
+ * Returns the user-facing error message (identical wording to the
+ * server's) or `null` when the expression is acceptable. Purely
+ * lexical — it does not evaluate calendar semantics.
+ */
+export declare function validateCron(cron: string): string | null;
+/**
+ * Validate an IANA time zone name using the runtime's own tz database
+ * (`Intl`), mirroring the server's check against the platform tz
+ * database. Returns the user-facing error message or `null`.
+ *
+ * `"Local"` is rejected explicitly for the same reason the server
+ * rejects it: it is host-dependent, not a zone.
+ */
+export declare function validateTimeZone(timeZone: string): string | null;
+//# sourceMappingURL=cadence.d.ts.map

package/schedule/cadence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cadence.d.ts","sourceRoot":"","sources":["../../src/schedule/cadence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,uEAAuE;AACvE,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1E;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,mEAAmE;IACnE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD,6CAA6C;AAC7C,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;AAEhD,iEAAiE;AACjE,eAAO,MAAM,cAAc,yFAQjB,CAAC;AAMX;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAiB3D;AAWD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAsDzD;AAcD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAoBR;AAED,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE/D;AA2BD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiCxD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAShE"}