@stigmer/react 3.5.3 → 3.6.0

package/src/schedule/TimeZoneField.tsx

@@ -0,0 +1,199 @@
+"use client";
+
+import {
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+  type KeyboardEvent,
+} from "react";
+import { cn } from "@stigmer/theme";
+
+/** 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;
+}
+
+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,
+}: TimeZoneFieldProps) {
+  const zones = useMemo(() => allTimeZones(), []);
+
+  const [query, setQuery] = useState<string | null>(null);
+  const [focusIndex, setFocusIndex] = useState(-1);
+  const listRef = useRef<HTMLDivElement>(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: string) => {
+      onChange(zone);
+      close();
+    },
+    [onChange, close],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLInputElement>) => {
+      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 (
+    <div className="relative">
+      <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…"
+        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 && (
+        <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",
+          )}
+        >
+          {filtered.length === 0 ? (
+            <div className="py-3 text-center text-xs text-muted-foreground">
+              No time zones match
+            </div>
+          ) : (
+            filtered.map((zone, idx) => (
+              <button
+                key={zone}
+                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",
+                )}
+              >
+                {zone}
+              </button>
+            ))
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function allTimeZones(): readonly string[] {
+  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(): string {
+  return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+}

package/src/schedule/__tests__/ScheduleDetailView.test.tsx

@@ -0,0 +1,260 @@
+import { describe, it, expect, vi, beforeAll, beforeEach, afterEach } from "vitest";
+import { render, screen, waitFor, fireEvent, cleanup } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { clone, create } from "@bufbuild/protobuf";
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+import { ScheduleSchema, type Schedule } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { StigmerContext } from "../../context";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { ScheduleDetailView } from "../ScheduleDetailView";
+
+vi.mock("../../feedback/toast", () => ({
+  toast: Object.assign(vi.fn(), { success: vi.fn(), error: vi.fn() }),
+}));
+
+beforeAll(() => {
+  // happy-dom does not implement the native dialog show/close methods.
+  HTMLDialogElement.prototype.showModal = function showModal() {
+    this.open = true;
+  };
+  HTMLDialogElement.prototype.close = function close() {
+    this.open = false;
+  };
+});
+
+beforeEach(() => vi.clearAllMocks());
+afterEach(cleanup);
+
+const NOW = new Date("2026-08-04T10:00:00Z");
+
+function makeSchedule(overrides?: {
+  enabled?: boolean;
+  pausedReason?: string;
+  lastExecutionId?: string;
+}): Schedule {
+  return create(ScheduleSchema, {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "Schedule",
+    metadata: {
+      id: "sch_01example",
+      name: "daily-fee-reminders",
+      slug: "daily-fee-reminders",
+      org: "isc",
+    },
+    spec: {
+      cron: "0 9 * * *",
+      timeZone: "Asia/Kolkata",
+      enabled: overrides?.enabled ?? true,
+      target: {
+        case: "agent",
+        value: {
+          agentRef: { kind: ApiResourceKind.agent, org: "isc", slug: "fee-reminder" },
+          message: "Send today's fee reminders.",
+        },
+      },
+    },
+    status: {
+      nextFireAt: timestampFromDate(new Date(NOW.getTime() + 3 * 3_600_000)),
+      lastFireAt: timestampFromDate(new Date(NOW.getTime() - 5 * 60_000)),
+      lastExecutionId: overrides?.lastExecutionId ?? "aex_01run",
+      consecutiveFailures: overrides?.pausedReason ? 5 : 0,
+      pausedReason: overrides?.pausedReason ?? "",
+    },
+  });
+}
+
+interface MockClient {
+  schedule: {
+    getByReference: ReturnType<typeof vi.fn>;
+    resume: ReturnType<typeof vi.fn>;
+    trigger: ReturnType<typeof vi.fn>;
+    delete: ReturnType<typeof vi.fn>;
+  };
+  manifest: { apply: ReturnType<typeof vi.fn> };
+}
+
+function makeClient(schedule: Schedule): MockClient {
+  return {
+    schedule: {
+      getByReference: vi.fn().mockResolvedValue(schedule),
+      resume: vi.fn().mockResolvedValue(schedule),
+      trigger: vi.fn().mockResolvedValue(schedule),
+      delete: vi.fn().mockResolvedValue(schedule),
+    },
+    manifest: {
+      apply: vi.fn(async (doc: { message: unknown }) => ({
+        yamlKind: "Schedule",
+        displayName: "Schedule",
+        name: "daily-fee-reminders",
+        slug: "daily-fee-reminders",
+        org: "isc",
+        id: "sch_01example",
+        message: doc.message,
+      })),
+    },
+  };
+}
+
+function renderView(
+  client: MockClient,
+  props?: Partial<Parameters<typeof ScheduleDetailView>[0]>,
+) {
+  function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <FetchCacheContext.Provider value={null}>
+        <StigmerContext.Provider value={client as never}>
+          {children}
+        </StigmerContext.Provider>
+      </FetchCacheContext.Provider>
+    );
+  }
+  return render(
+    <ScheduleDetailView
+      org="isc"
+      slug="daily-fee-reminders"
+      now={NOW}
+      {...props}
+    />,
+    { wrapper: Wrapper },
+  );
+}
+
+describe("ScheduleDetailView", () => {
+  it("renders definition and status for an active schedule", async () => {
+    renderView(makeClient(makeSchedule()));
+
+    await screen.findByRole("heading", { name: "daily-fee-reminders" });
+    expect(screen.getByText("0 9 * * *")).toBeTruthy();
+    expect(screen.getByText("Asia/Kolkata")).toBeTruthy();
+    expect(screen.getByText("isc/fee-reminder")).toBeTruthy();
+    expect(screen.getByText("Send today's fee reminders.")).toBeTruthy();
+    expect(screen.getByText("in 3h")).toBeTruthy();
+    expect(screen.getByText("5m")).toBeTruthy();
+    expect(screen.getByText("aex_01run")).toBeTruthy();
+    expect(screen.getByText("Active")).toBeTruthy();
+    // Active schedules show no state banner.
+    expect(screen.queryByText("Schedule is disabled")).toBeNull();
+    expect(screen.queryByText("Paused by the platform")).toBeNull();
+  });
+
+  it("renders the disabled banner with an inline Enable remedy", async () => {
+    const client = makeClient(makeSchedule({ enabled: false }));
+    renderView(client);
+
+    await screen.findByText("Schedule is disabled");
+    expect(screen.getByText("Disabled")).toBeTruthy();
+    // Owner-disabled schedules have no meaningful countdown.
+    expect(screen.queryByText("in 3h")).toBeNull();
+
+    fireEvent.click(screen.getByRole("button", { name: "Enable schedule" }));
+
+    await waitFor(() => expect(client.manifest.apply).toHaveBeenCalledOnce());
+    const doc = client.manifest.apply.mock.calls[0][0] as { message: Schedule };
+    expect(doc.message.spec?.enabled).toBe(true);
+  });
+
+  it("renders the paused banner with reason and an inline Resume remedy", async () => {
+    const client = makeClient(makeSchedule({ pausedReason: "5 consecutive failures" }));
+    renderView(client);
+
+    await screen.findByText("Paused by the platform");
+    expect(screen.getByText(/5 consecutive failures — resuming clears/)).toBeTruthy();
+    expect(screen.getByText("Paused")).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("button", { name: "Resume schedule" }));
+
+    await waitFor(() =>
+      expect(client.schedule.resume).toHaveBeenCalledWith("sch_01example"),
+    );
+  });
+
+  it("never collapses disabled and paused: disabled wins, pause stays visible", async () => {
+    const client = makeClient(
+      makeSchedule({ enabled: false, pausedReason: "5 consecutive failures" }),
+    );
+    renderView(client);
+
+    await screen.findByText("Schedule is disabled");
+    expect(screen.queryByText("Paused by the platform")).toBeNull();
+    // The badge says Disabled, but the platform pause is still explained.
+    expect(screen.getByText("Disabled")).toBeTruthy();
+    expect(screen.getByText(/also paused by the platform/)).toBeTruthy();
+  });
+
+  it("gates Run now behind a confirmation and refetches after", async () => {
+    const client = makeClient(makeSchedule());
+    renderView(client);
+
+    await screen.findByRole("heading", { name: "daily-fee-reminders" });
+    fireEvent.click(screen.getByRole("button", { name: "Run now" }));
+
+    // Confirmation first — nothing fired yet.
+    await screen.findByText("Run this schedule now?");
+    expect(client.schedule.trigger).not.toHaveBeenCalled();
+
+    fireEvent.click(screen.getByText("Start run"));
+    await waitFor(() =>
+      expect(client.schedule.trigger).toHaveBeenCalledWith("sch_01example"),
+    );
+    // Refetch picks up the new last_execution_id.
+    await waitFor(() =>
+      expect(client.schedule.getByReference.mock.calls.length).toBeGreaterThan(1),
+    );
+  });
+
+  it("disables Run now when the schedule cannot fire", async () => {
+    renderView(makeClient(makeSchedule({ enabled: false })));
+
+    await screen.findByText("Schedule is disabled");
+    const runButton = screen.getByRole("button", { name: "Run now" });
+    expect((runButton as HTMLButtonElement).disabled).toBe(true);
+  });
+
+  it("navigates through the callback seams (DD-004)", async () => {
+    const onNavigateToAgent = vi.fn();
+    const onNavigateToExecution = vi.fn();
+    renderView(makeClient(makeSchedule()), {
+      onNavigateToAgent,
+      onNavigateToExecution,
+    });
+
+    await screen.findByRole("heading", { name: "daily-fee-reminders" });
+    fireEvent.click(screen.getByRole("button", { name: "isc/fee-reminder" }));
+    expect(onNavigateToAgent).toHaveBeenCalledWith("isc", "fee-reminder");
+
+    fireEvent.click(screen.getByRole("button", { name: "aex_01run" }));
+    expect(onNavigateToExecution).toHaveBeenCalledWith("aex_01run");
+  });
+
+  it("renders references as plain text without navigation callbacks", async () => {
+    renderView(makeClient(makeSchedule()));
+
+    await screen.findByRole("heading", { name: "daily-fee-reminders" });
+    expect(screen.queryByRole("button", { name: "isc/fee-reminder" })).toBeNull();
+    expect(screen.getByText("isc/fee-reminder")).toBeTruthy();
+  });
+
+  it("shows the not-found state for a missing schedule", async () => {
+    const client = makeClient(makeSchedule());
+    // NOT_FOUND resolves to null via useSchedule's isNotFound handling —
+    // simulate the resolved-null directly.
+    client.schedule.getByReference.mockResolvedValue(null);
+    renderView(client);
+
+    await screen.findByText("Schedule not found");
+  });
+
+  it("keeps the caller's schedule untouched when toggling (immutability)", async () => {
+    const schedule = makeSchedule({ enabled: false });
+    const original = clone(ScheduleSchema, schedule);
+    const client = makeClient(schedule);
+    renderView(client);
+
+    await screen.findByText("Schedule is disabled");
+    fireEvent.click(screen.getByRole("button", { name: "Enable schedule" }));
+    await waitFor(() => expect(client.manifest.apply).toHaveBeenCalledOnce());
+
+    expect(schedule.spec?.enabled).toBe(original.spec?.enabled);
+  });
+});