@flamingo-stack/openframe-frontend-core 0.0.740 → 0.0.742

package/src/components/features/scripts/schedule-form/schedule-form-types.ts

@@ -0,0 +1,189 @@
+import type { ReactNode } from 'react';
+import type { ScriptArgument } from '../../../platform/ScriptArguments';
+import {
+  SCHEDULE_OFFLINE_BEHAVIOR,
+  SCHEDULE_TIME_REFERENCE,
+  type ScheduleOfflineBehavior,
+  type ScheduleTimeReference,
+  SCRIPT_SCHEDULE_TRIGGER,
+  type ScriptScheduleTrigger,
+} from './schedule-enums';
+import { DEFAULT_RECONNECT_WINDOW, type DurationUnit } from './schedule-timing';
+
+/** One of a script's own environment variables. `value` is null for a secret: the server masks it on every read. */
+export interface ScheduleFormEnvVar {
+  name: string;
+  value: string | null;
+  secret: boolean;
+}
+
+/** One card of "Scheduled Scripts": the picked script and what the schedule runs it with. */
+export interface ScheduleFormScriptRow {
+  /** `''` = no script picked yet. */
+  scriptId: string;
+  name: string;
+  /** The picked script's OWN platforms (UI ids) — a host checks them against the schedule's. */
+  supportedPlatforms: string[];
+  // 0 = no script picked yet, so the field is locked and empty; a real
+  // timeout only exists once a script is chosen (it seeds this).
+  timeoutSeconds: number;
+  args: ScriptArgument[];
+  envVars: ScriptArgument[];
+  /**
+   * The picked script's OWN defaults, carried with no control of their
+   * own: an override is written only for the half that differs from
+   * them, so a schedule keeps inheriting later edits to the script
+   * instead of freezing a copy the day it was saved.
+   */
+  defaultArgs: string[];
+  defaultEnvVars: ScheduleFormEnvVar[];
+}
+
+/**
+ * Everything the schedule form holds. The fields read it off the
+ * react-hook-form context; the host owns the form itself (its schema, its
+ * seeding, its submit), and checks its own form type against this one.
+ */
+export interface ScheduleFormData {
+  name: string;
+  /** "Note" in the UI. */
+  description: string;
+  trigger: ScriptScheduleTrigger;
+  scheduledDate: Date | null;
+  /** `HH:mm` on the 30-minute grid; `''` = the user hasn't picked a time yet. */
+  scheduledTime: string;
+  /** Which clock the pair above means — the "Timezone" control. Held even when the control is not rendered. */
+  timeReference: ScheduleTimeReference;
+  repeatEnabled: boolean;
+  /** `null` while the box is EMPTY — the user is mid-edit, not proposing zero. */
+  repeatInterval: number | null;
+  repeatUnit: DurationUnit;
+  /** The stored cadence the form was seeded with, carried with no control of its own. */
+  repeatSecondsStored: number | null;
+  /**
+   * The stored start the form was seeded with, carried with no control of its
+   * own: a start that has already passed stays legal for as long as the form
+   * still shows exactly it (see `isStartInPastAndChanged`).
+   */
+  startAtStored: string | null;
+  offlineBehavior: ScheduleOfflineBehavior;
+  /** "Stop Retry after", as the `[interval] [unit]` pair. `null` while the box is empty. */
+  reconnectInterval: number | null;
+  reconnectUnit: DurationUnit;
+  /** The stored reconnect window the form was seeded with, carried with no control of its own. */
+  reconnectWindowSecondsStored: number | null;
+  /** UI platform ids the schedule targets. */
+  supportedPlatforms: string[];
+  /** Card order IS the run order. */
+  scripts: ScheduleFormScriptRow[];
+}
+
+export const EMPTY_SCHEDULE_SCRIPT_ROW: ScheduleFormScriptRow = {
+  scriptId: '',
+  name: '',
+  supportedPlatforms: [],
+  // 0 keeps the Timeout field locked and empty until a script is picked.
+  timeoutSeconds: 0,
+  args: [],
+  envVars: [],
+  defaultArgs: [],
+  defaultEnvVars: [],
+};
+
+export const SCHEDULE_TRIGGER_OPTIONS = [
+  {
+    value: SCRIPT_SCHEDULE_TRIGGER.DATE_TIME,
+    label: 'Run on schedule',
+    description: 'Runs at the set date and time, whether or not the device is online.',
+  },
+  {
+    value: SCRIPT_SCHEDULE_TRIGGER.DEVICE_ONLINE,
+    label: 'Run when device comes online',
+    description: "Waits for the device to connect, then runs as soon as it's reachable.",
+  },
+];
+
+/**
+ * The "Timezone" dropdown (design node 793:61340), in the designer's own
+ * wording: the account's clock, or each device's.
+ *
+ * SERVER first — it is the backend's documented default for a null
+ * `timeReference`, and it is what every schedule authored before the field
+ * existed already means.
+ */
+export const SCHEDULE_TIME_REFERENCE_OPTIONS = [
+  { value: SCHEDULE_TIME_REFERENCE.SERVER, label: 'Your account timezone' },
+  { value: SCHEDULE_TIME_REFERENCE.DEVICE_LOCAL, label: 'Device local timezone' },
+];
+
+/**
+ * The two answers to "if device is offline at scheduled time" (design node
+ * 460:63425). SKIP first, because it is both the design's default and the
+ * behavior every schedule authored before this field existed already has — the
+ * backend reads a null `offlineBehavior` as SKIP.
+ */
+export const SCHEDULE_OFFLINE_BEHAVIOR_OPTIONS = [
+  {
+    value: SCHEDULE_OFFLINE_BEHAVIOR.SKIP,
+    label: 'Skip this Run',
+    description: 'Next run stays on schedule. Missed runs are logged.',
+  },
+  {
+    value: SCHEDULE_OFFLINE_BEHAVIOR.RETRY_ON_RECONNECT,
+    label: 'Run when device comes back online',
+    description: 'Executes on the next reconnect.',
+  },
+];
+
+export const DEFAULT_SCHEDULE_FORM_VALUES: ScheduleFormData = {
+  name: '',
+  description: '',
+  trigger: SCRIPT_SCHEDULE_TRIGGER.DATE_TIME,
+  scheduledDate: null,
+  scheduledTime: '',
+  timeReference: SCHEDULE_TIME_REFERENCE.SERVER,
+  repeatEnabled: false,
+  repeatInterval: 1,
+  repeatUnit: 'day',
+  repeatSecondsStored: null,
+  startAtStored: null,
+  offlineBehavior: SCHEDULE_OFFLINE_BEHAVIOR.SKIP,
+  reconnectInterval: DEFAULT_RECONNECT_WINDOW.interval,
+  reconnectUnit: DEFAULT_RECONNECT_WINDOW.unit,
+  reconnectWindowSecondsStored: null,
+  supportedPlatforms: ['windows'],
+  scripts: [EMPTY_SCHEDULE_SCRIPT_ROW],
+};
+
+/**
+ * A flag a host has asked about and may not have an answer to yet. `loading`
+ * is never read as `off`: the fields it decides are locked until it settles.
+ */
+export type ScheduleFormGate = 'on' | 'off' | 'loading';
+
+/** One option of the Time dropdown: `value` is 24h `HH:mm`, `label` what the viewer reads. */
+export interface ScheduleTimeSlot {
+  value: string;
+  label: string;
+}
+
+/**
+ * What a card's "Select Script" slot is told. Searching the script library is
+ * the host's query, so the field is a slot: the product passes its data-bound
+ * search, a fixture passes a static one. Both draw `ScheduleScriptSearchField`.
+ */
+export interface ScheduleScriptSearchSlotProps {
+  /** The card's script: `''` while nothing is picked. */
+  scriptId: string;
+  /** Its name — the label shown when the script is not on the current search page. */
+  name: string;
+  /** UI platform ids the schedule targets — what a host narrows its search by. */
+  supportedPlatforms: string[];
+  /** Writes the card: the row a picked script seeds, or null when the field is cleared. */
+  onPick: (row: ScheduleFormScriptRow | null) => void;
+  disabled: boolean;
+  error: string | undefined;
+  invalid: boolean;
+}
+
+export type RenderScheduleScriptSearch = (field: ScheduleScriptSearchSlotProps) => ReactNode;

package/src/components/features/scripts/schedule-form/schedule-interval-input.tsx

@@ -0,0 +1,121 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { Input } from '../../../ui/input';
+
+interface ScheduleIntervalInputProps {
+  /** The form's value. `null` = the box is empty. */
+  value: number | null;
+  onChange: (next: number | null) => void;
+  /**
+   * The form's own blur handler. Load-bearing, not optional plumbing: react-hook-form
+   * learns a field was left ONLY through this, and `reValidateMode: 'onBlur'` is
+   * what re-runs the schema. Without it an error the user has already fixed sits
+   * on screen until the next Save.
+   */
+  onBlur?: () => void;
+  disabled?: boolean;
+  invalid?: boolean;
+  error?: string;
+  min?: number;
+  className?: string;
+  'aria-label'?: string;
+  /**
+   * Marks this box as where `scrollToFirstInvalidField` should put focus when
+   * the error is carried by an ancestor rather than by the input itself.
+   */
+  'data-invalid-focus'?: boolean;
+}
+
+/**
+ * The `[interval]` half of the form's two duration pairs (Repeat in, Stop Retry
+ * after).
+ *
+ * **What the user types owns the display; the form value never writes back into
+ * it while the field has focus.** That inversion is the whole component. Binding
+ * a number input straight to validated state reads as a bug rather than a rule:
+ * the previous version coerced an emptied box back to a floor on every
+ * keystroke, so the digit reappeared as fast as it was deleted and "1" could not
+ * be typed over. Any round trip through `Number()` has the same shape in
+ * smaller ways — a leading zero vanishes mid-word, "10" briefly becomes "1"
+ * while a character is being removed.
+ *
+ * So the raw string is local state, and the form is told the PARSED value as it
+ * changes. Keeping the form current (rather than committing on blur alone)
+ * matters for one case: submitting with Enter never fires a blur, and a form
+ * reading a stale interval would save a number the user cannot see.
+ *
+ * The reverse direction — form → box — is deliberately narrow. It runs only
+ * when the field is NOT focused, which is exactly the set of changes that come
+ * from somewhere else: the record arriving (`useSeedForm`), or the unit
+ * dropdown raising the interval to its floor. While the box has focus those
+ * cannot happen, and nothing else may repaint what is being typed.
+ *
+ * Validation timing is the form's business, not this component's: errors are
+ * held until the first Save (`showErrors`) and re-checked on blur
+ * (`reValidateMode`), so nothing here is judged mid-word.
+ */
+export function ScheduleIntervalInput({
+  value,
+  onChange,
+  onBlur,
+  disabled,
+  invalid,
+  error,
+  min,
+  className,
+  'aria-label': ariaLabel,
+  'data-invalid-focus': invalidFocus,
+}: ScheduleIntervalInputProps) {
+  const [text, setText] = useState(() => (value === null ? '' : String(value)));
+  const focused = useRef(false);
+
+  // Adopts the FORM's value, never its own output — hence the functional
+  // `setText`, which keeps `text` out of the dependency list. Reacting to the
+  // text this effect just wrote is what would fight the user.
+  useEffect(() => {
+    if (focused.current) return;
+    const next = value === null ? '' : String(value);
+    setText(current => (current === next ? current : next));
+  }, [value]);
+
+  return (
+    <Input
+      // Left as a number field so the stepper and the numeric keypad stay. The
+      // one cost is that a browser reports `''` for a half-typed exponent
+      // ("1e"), which reads here as a cleared box — it resolves itself on blur,
+      // and it is the browser's own behaviour for the type rather than
+      // something this component can improve on.
+      type="number"
+      min={min}
+      inputMode="numeric"
+      aria-label={ariaLabel}
+      data-invalid-focus={invalidFocus || undefined}
+      className={className}
+      value={text}
+      onFocus={() => {
+        focused.current = true;
+      }}
+      onBlur={() => {
+        focused.current = false;
+        // Normalise what is shown to what was actually stored: "007" settles to
+        // "7". Only on the way out, never mid-word.
+        setText(value === null ? '' : String(value));
+        onBlur?.();
+      }}
+      onChange={e => {
+        const raw = e.target.value;
+        setText(raw);
+        if (raw.trim() === '') {
+          onChange(null);
+          return;
+        }
+        const parsed = Number(raw);
+        onChange(Number.isFinite(parsed) ? parsed : null);
+      }}
+      disabled={disabled}
+      invalid={invalid}
+      error={error}
+    />
+  );
+}

package/src/components/features/scripts/schedule-form/schedule-offline-fields.tsx

@@ -0,0 +1,218 @@
+'use client';
+'use no memo';
+
+import { useController, useFormContext, useWatch } from 'react-hook-form';
+import { cn } from '../../../../utils/cn';
+import { Label } from '../../../ui/label';
+import { RadioGroupBlock } from '../../../ui/radio-group';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../../../ui/select';
+import { TruncateText } from '../../../ui/truncate-text';
+import { type ScheduleFormData, SCHEDULE_OFFLINE_BEHAVIOR_OPTIONS } from './schedule-form-types';
+import { ScheduleIntervalInput } from './schedule-interval-input';
+import {
+  DURATION_UNIT_OPTIONS,
+  type DurationUnit,
+  isEventTrigger,
+  isRetryOnReconnect,
+  MIN_RECONNECT_MINUTES,
+  snapReconnectInterval,
+} from './schedule-timing';
+
+interface ReconnectWindowFieldsProps {
+  interval: number | null;
+  unit: DurationUnit;
+  onIntervalChange: (next: number | null) => void;
+  onIntervalBlur: () => void;
+  onUnitChange: (next: DurationUnit) => void;
+  disabled: boolean;
+  invalid: boolean;
+  /**
+   * Let the two controls share the width they are given instead of taking the
+   * design's fixed 120px each — what the full-width row below `md` needs, where
+   * the fixed pair plus its caption overflows a phone.
+   */
+  fluid?: boolean;
+  className?: string;
+}
+
+/**
+ * "Stop Retry after [1] [Week]" — how long a queued run stays worth running.
+ *
+ * Presentational and stateless: the two form fields are registered ONCE by the
+ * block below and handed down, because this renders TWICE (see the two call
+ * sites). Two `Controller`s on one name would also work, but one registration
+ * with two views is the honest description of what this is.
+ */
+function ReconnectWindowFields({
+  interval,
+  unit,
+  onIntervalChange,
+  onIntervalBlur,
+  onUnitChange,
+  disabled,
+  invalid,
+  fluid = false,
+  className,
+}: ReconnectWindowFieldsProps) {
+  const controlWidth = fluid ? 'flex-1 min-w-0' : 'w-[120px]';
+  return (
+    <div className={cn('flex items-center gap-[var(--spacing-system-xsf)]', className)}>
+      <span className={cn('shrink-0 text-h4', disabled ? 'text-ods-text-disabled' : 'text-ods-text-secondary')}>
+        Stop Retry after
+      </span>
+      <ScheduleIntervalInput
+        min={unit === 'minute' ? MIN_RECONNECT_MINUTES : 1}
+        aria-label="Stop retry after"
+        className={controlWidth}
+        value={interval}
+        onChange={onIntervalChange}
+        onBlur={onIntervalBlur}
+        // Where a failed Save should land. Without it the section marker below
+        // hands focus to its first focusable descendant, which is the "Skip
+        // this Run" radio — three controls away from the value to fix.
+        data-invalid-focus
+        disabled={disabled}
+        invalid={invalid}
+      />
+      {/* Switching to minutes drags the interval up to the floor with it: "1 Day"
+          would otherwise read "1 Minute", a value the user never typed and the
+          form cannot save. Coarser units clear the floor by construction. */}
+      <Select value={unit} onValueChange={(next: DurationUnit) => onUnitChange(next)} disabled={disabled}>
+        <SelectTrigger className={controlWidth} aria-label="Stop retry after unit">
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          {DURATION_UNIT_OPTIONS.map(opt => (
+            <SelectItem key={opt.value} value={opt.value}>
+              {opt.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    </div>
+  );
+}
+
+/**
+ * "If device is offline at scheduled time" — Skip this Run vs Run when device
+ * comes back online, plus the reconnect window the second one needs
+ * (design node 460:63425).
+ *
+ * Maps to `offlineBehavior` (`SKIP` | `RETRY_ON_RECONNECT`) and
+ * `reconnectWindowSeconds`. The window is submitted ONLY alongside
+ * RETRY_ON_RECONNECT — the schema documents it as "set only when offlineBehavior
+ * is RETRY_ON_RECONNECT" — which is also why it is required rather than
+ * optional-meaning-forever: nothing in the contract says a null window queues a
+ * run indefinitely, so the form never offers a reading it cannot back up.
+ *
+ * The block presupposes a scheduled time the device can be absent FOR, so it
+ * collapses for DEVICE_ONLINE — which fires on the reconnect already — and
+ * submits the SKIP default instead of what the collapsed controls hold.
+ * DEVICE_LOCAL keeps it: its scheduled moment is the device's own wall clock.
+ *
+ * It collapses with the `0fr → 1fr` grid-rows technique, staying MOUNTED so
+ * toggling the trigger back restores what was picked, `inert` to drop the
+ * collapsed controls out of the tab order, and a padding/negative-margin pair:
+ * the bottom padding is the room the absolutely-positioned error renders into,
+ * and the constant negative margin cancels it so a collapsed block leaves no
+ * hole.
+ */
+export function ScheduleOfflineFields({ showErrors, disabled = false }: { showErrors: boolean; disabled?: boolean }) {
+  const { control } = useFormContext<ScheduleFormData>();
+  const trigger = useWatch({ control, name: 'trigger' });
+  // The one reading with no offline moment to decide about — see the docstring.
+  const collapsed = isEventTrigger(trigger);
+
+  const { field: behaviorField } = useController({ control, name: 'offlineBehavior' });
+  const { field: intervalField, fieldState: intervalState } = useController({ control, name: 'reconnectInterval' });
+  const { field: unitField } = useController({ control, name: 'reconnectUnit' });
+
+  // The window belongs to the second option and only to it. Locked under SKIP
+  // rather than hidden: the design keeps it on the row so the choice reads as
+  // "skip, or retry for THIS long", and a click anywhere on that row selects the
+  // option and unlocks it — the controls themselves are interactive content,
+  // which a label's activation behavior skips, so using them never re-triggers
+  // the radio they sit inside.
+  const windowDisabled = disabled || !isRetryOnReconnect(behaviorField.value);
+  const intervalError = showErrors ? intervalState.error?.message : undefined;
+
+  // Switching TO minutes drags the interval up to the floor with it, the way the
+  // repeat pair does: "1 Day" would otherwise read "1 Minute", a value the user
+  // never typed and the form cannot save. A cleared field stays cleared.
+  const handleUnitChange = (next: DurationUnit) => {
+    unitField.onChange(next);
+    const snapped = snapReconnectInterval(intervalField.value, next);
+    if (snapped !== intervalField.value) intervalField.onChange(snapped);
+  };
+
+  const windowFieldsFor = (fluid: boolean) => (
+    <ReconnectWindowFields
+      interval={intervalField.value}
+      unit={unitField.value}
+      onIntervalChange={intervalField.onChange}
+      onIntervalBlur={intervalField.onBlur}
+      onUnitChange={handleUnitChange}
+      disabled={windowDisabled}
+      invalid={!!intervalError}
+      fluid={fluid}
+    />
+  );
+
+  const options = SCHEDULE_OFFLINE_BEHAVIOR_OPTIONS.map(option =>
+    isRetryOnReconnect(option.value)
+      ? // Desktop only. Below `md` the caption plus two controls cannot share a
+        // row with the option's own label without squeezing it to nothing, so
+        // the same fields render full-width under the group instead.
+        { ...option, trailing: <div className="hidden content-md:flex">{windowFieldsFor(false)}</div> }
+      : option,
+  );
+
+  return (
+    <div
+      inert={collapsed}
+      style={{
+        gridTemplateRows: collapsed ? '0fr' : '1fr',
+        opacity: collapsed ? 0 : 1,
+      }}
+      className="mb-[calc(-1*var(--spacing-system-lf))] grid transition-[grid-template-rows,opacity] duration-200 ease-out motion-reduce:transition-none"
+    >
+      <div className="min-h-0 overflow-hidden">
+        {/* The bottom padding is the room the error below renders into, and it
+            sits on a wrapper INSIDE the clipping box rather than on the box
+            itself: a box is never shorter than its own padding — border-box
+            included — so padding on the grid item would survive the 0fr track as
+            24px of residue that the negative margin above then spends cancelling
+            instead of closing the section gap. */}
+        <div className="pb-[var(--spacing-system-lf)]">
+          {/* `data-invalid` on the SECTION, not on the number inputs: one of
+              those two copies is always display:none, and an ancestor is matched
+              before either, so the marker is visible at every breakpoint. What
+              it cannot say on its own is WHERE to put focus — the first
+              focusable inside it is the "Skip this Run" radio — so the input
+              carries `data-invalid-focus` and the helper prefers it. */}
+          <div
+            className="relative flex flex-col gap-[var(--spacing-system-xxs)]"
+            data-invalid={intervalError ? true : undefined}
+          >
+            <Label className="text-h4">If device is offline at scheduled time</Label>
+            <RadioGroupBlock
+              variant="grouped"
+              value={behaviorField.value}
+              onValueChange={behaviorField.onChange}
+              disabled={disabled}
+              options={options}
+            />
+            <div className="pt-[var(--spacing-system-xs)] content-md:hidden">{windowFieldsFor(true)}</div>
+            {intervalError && (
+              <div className="absolute bottom-0 left-0 right-0 translate-y-full">
+                <TruncateText variant="h6" className="text-ods-error">
+                  {intervalError}
+                </TruncateText>
+              </div>
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}