Setting control

import { SectionHeading } from "@bosunkit/components/section-heading";
import {
  SettingField,
  SettingSelect,
  SettingToggle,
  type SaveState,
  type SettingSelectOption,
} from "@bosunkit/components/setting-control";
import { Anchor, Radio } from "lucide-react";
import {
  useEffect,
  useId,
  useRef,
  useState,
  type Dispatch,
  type ReactElement,
  type ReactNode,
  type RefObject,
  type SetStateAction,
} from "react";

export const description: string =
  "An anchor watch settings page: switches that save, fail, refuse input and wait on a save, a number field sized " +
  "to its digits, text, secret and read-only fields, and a select, each save chip on its row's edge.";

interface Saved<Value> {
  readonly value: Value;
  readonly state: SaveState;
}

/** How long the example's save takes to come back. */
const SAVE_MS: number = 900;

/**
 * A setting whose save comes back after SAVE_MS: it lands, or it fails and the control returns to the value that is
 * saved on the vessel.
 */
function useSetting<Value>(initial: Value, fails: boolean = false): [Saved<Value>, (next: Value) => void] {
  const [setting, setSetting]: [Saved<Value>, Dispatch<SetStateAction<Saved<Value>>>] = useState<Saved<Value>>({
    value: initial,
    state: "idle",
  });
  const saved: RefObject<Value> = useRef<Value>(initial);
  const timer: RefObject<ReturnType<typeof setTimeout> | undefined> = useRef<ReturnType<typeof setTimeout> | undefined>(
    undefined,
  );
  useEffect((): (() => void) => {
    return (): void => {
      clearTimeout(timer.current);
    };
  }, []);

  function save(next: Value): void {
    setSetting({ value: next, state: "saving" });
    clearTimeout(timer.current);
    // Stands in for the PUT to the vessel's settings.
    timer.current = setTimeout((): void => {
      if (fails) {
        setSetting({ value: saved.current, state: "error" });
        return;
      }
      saved.current = next;
      setSetting({ value: next, state: "saved" });
    }, SAVE_MS);
  }

  return [setting, save];
}

const LANGUAGES: readonly SettingSelectOption[] = [
  { value: "en", label: "English" },
  { value: "nl", label: "Nederlands" },
  { value: "fr", label: "Français" },
  { value: "de", label: "Deutsch" },
  { value: "es", label: "Español" },
  { value: "it", label: "Italiano" },
];

function ignore(): void {
  // A disabled or read-only control saves nothing.
}

function Group({ icon, title, children }: { icon: ReactNode; title: string; children: ReactNode }): ReactElement {
  const headingId: string = useId();
  return (
    <section aria-labelledby={headingId} style={{ display: "flex", flexDirection: "column", gap: "var(--space-sm)" }}>
      <SectionHeading level={3} id={headingId} icon={icon}>
        {title}
      </SectionHeading>
      {children}
    </section>
  );
}

export default function Showcase(): ReactElement {
  const [alarm, saveAlarm]: [Saved<boolean>, (next: boolean) => void] = useSetting<boolean>(true);
  const [phone, savePhone]: [Saved<boolean>, (next: boolean) => void] = useSetting<boolean>(false, true);
  const [radius, saveRadius]: [Saved<string>, (next: string) => void] = useSetting<string>("45");
  const [message, saveMessage]: [Saved<string>, (next: string) => void] = useSetting<string>("");
  const [language, saveLanguage]: [Saved<string>, (next: string) => void] = useSetting<string>("en");
  const [token, saveToken]: [Saved<string>, (next: string) => void] = useSetting<string>("7311029847:AAF-anchor");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: "var(--space-xl)", width: "100%" }}>
      <Group icon={<Anchor />} title="Anchor watch">
        <SettingToggle
          label="Anchor alarm"
          description="Sound the alarm on deck and below when the vessel leaves the swing circle."
          checked={alarm.value}
          state={alarm.state}
          onCheckedChange={saveAlarm}
        />
        <SettingField
          label="Swing radius"
          description="How far the vessel may move from the anchor position before the alarm sounds."
          type="number"
          value={radius.value}
          unit="m"
          maxDigits={3}
          placeholder="45"
          state={radius.state}
          onSave={saveRadius}
        />
        <SettingField
          label="Alarm announcement"
          description="Spoken after the alarm tone; leave it empty for the standard announcement."
          value={message.value}
          placeholder="Anchor drag. All hands on deck."
          state={message.state}
          onSave={saveMessage}
        />
        <SettingSelect
          label="Announcement language"
          description="The language the alarm is spoken in on deck."
          value={language.value}
          options={LANGUAGES}
          state={language.state}
          onSave={saveLanguage}
        />
      </Group>
      <Group icon={<Radio />} title="Reaching the crew">
        <SettingToggle
          label="Call the skipper's phone"
          description="Ring Maya's phone if nobody acknowledges within two minutes. In this example the save fails."
          checked={phone.value}
          state={phone.state}
          onCheckedChange={savePhone}
        />
        <SettingToggle
          label="Send the position to the crew"
          description="Message the anchor position to the crew's phones every hour. In this example the save is on its way."
          checked
          state="saving"
          onCheckedChange={ignore}
        />
        <SettingToggle
          label="Shore power alarm"
          description="Available once the shore power monitor reports on the network."
          checked={false}
          state="idle"
          onCheckedChange={ignore}
          disabled
        />
        <SettingField
          label="Telegram bot token"
          description="The token Bosun sends watch alerts with."
          type="password"
          value={token.value}
          state={token.state}
          onSave={saveToken}
        />
        <SettingField
          label="MMSI"
          description="From the vessel's registration; change it on the vessel profile."
          value="224123456"
          state="idle"
          onSave={ignore}
          readOnly
        />
      </Group>
    </div>
  );
}

import { SettingToggle, type SaveState } from "@bosunkit/components/setting-control";
import { useEffect, useRef, useState, type Dispatch, type ReactElement, type RefObject, type SetStateAction } from "react";

export const description: string =
  "A switch that saves as it is pressed: it turns at once, shows saving, then saved.";

export default function Toggle(): ReactElement {
  const [checked, setChecked]: [boolean, Dispatch<SetStateAction<boolean>>] = useState<boolean>(false);
  const [state, setState]: [SaveState, Dispatch<SetStateAction<SaveState>>] = useState<SaveState>("idle");
  const timer: RefObject<ReturnType<typeof setTimeout> | undefined> = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
  useEffect((): (() => void) => (): void => {
    clearTimeout(timer.current);
  }, []);

  function toggle(next: boolean): void {
    setChecked(next);
    setState("saving");
    clearTimeout(timer.current);
    // Stands in for the PUT to the vessel's settings.
    timer.current = setTimeout((): void => {
      setState("saved");
    }, 700);
  }

  return (
    <SettingToggle
      label="Anchor watch"
      description="Sound the alarm when the vessel moves outside her swing circle."
      checked={checked}
      state={state}
      onCheckedChange={toggle}
    />
  );
}

import { SettingToggle } from "@bosunkit/components/setting-control";
import type { ReactElement } from "react";

export const description: string = "The switch while its change is being saved.";

function ignore(): void {
  // The example saves nothing.
}

export default function ToggleSaving(): ReactElement {
  return <SettingToggle label="Enabled" checked state="saving" onCheckedChange={ignore} />;
}

import { SettingField, type SaveState } from "@bosunkit/components/setting-control";
import { useEffect, useRef, useState, type Dispatch, type ReactElement, type RefObject, type SetStateAction } from "react";

export const description: string = "A text field that saves on blur or Enter, with no save button.";

export default function Field(): ReactElement {
  const [value, setValue]: [string, Dispatch<SetStateAction<string>>] = useState<string>("Althea");
  const [state, setState]: [SaveState, Dispatch<SetStateAction<SaveState>>] = useState<SaveState>("idle");
  const timer: RefObject<ReturnType<typeof setTimeout> | undefined> = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
  useEffect((): (() => void) => (): void => {
    clearTimeout(timer.current);
  }, []);

  function save(next: string): void {
    setValue(next);
    setState("saving");
    clearTimeout(timer.current);
    // Stands in for the PUT to the vessel's settings.
    timer.current = setTimeout((): void => {
      setState("saved");
    }, 700);
  }

  return (
    <SettingField
      label="Vessel name"
      description="How bosun names the vessel on the radio and in messages."
      value={value}
      state={state}
      onSave={save}
    />
  );
}

import { SettingField, type SaveState } from "@bosunkit/components/setting-control";
import {
  useEffect,
  useRef,
  useState,
  type Dispatch,
  type ReactElement,
  type RefObject,
  type SetStateAction,
} from "react";

export const description: string =
  "A number field sized to its three digits, right-aligned, with its unit inside its right edge.";

export default function NumberField(): ReactElement {
  const [value, setValue]: [string, Dispatch<SetStateAction<string>>] = useState<string>("45");
  const [state, setState]: [SaveState, Dispatch<SetStateAction<SaveState>>] = useState<SaveState>("idle");
  const timer: RefObject<ReturnType<typeof setTimeout> | undefined> = useRef<ReturnType<typeof setTimeout> | undefined>(
    undefined,
  );
  useEffect(
    (): (() => void) => (): void => {
      clearTimeout(timer.current);
    },
    [],
  );

  function save(next: string): void {
    setValue(next);
    setState("saving");
    clearTimeout(timer.current);
    // Stands in for the PUT to the vessel's settings.
    timer.current = setTimeout((): void => {
      setState("saved");
    }, 700);
  }

  return (
    <SettingField
      label="Swing radius"
      description="How far the vessel may move from the anchor position before the alarm sounds."
      type="number"
      value={value}
      unit="m"
      maxDigits={3}
      state={state}
      onSave={save}
    />
  );
}

import { SettingSelect, type SaveState } from "@bosunkit/components/setting-control";
import { useEffect, useRef, useState, type Dispatch, type ReactElement, type RefObject, type SetStateAction } from "react";

export const description: string = "A list of choices for a setting that takes one of a few values, saved when chosen.";

export default function Select(): ReactElement {
  const [value, setValue]: [string, Dispatch<SetStateAction<string>>] = useState<string>("en");
  const [state, setState]: [SaveState, Dispatch<SetStateAction<SaveState>>] = useState<SaveState>("idle");
  const timer: RefObject<ReturnType<typeof setTimeout> | undefined> = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
  useEffect((): (() => void) => (): void => {
    clearTimeout(timer.current);
  }, []);

  function save(next: string): void {
    setValue(next);
    setState("saving");
    clearTimeout(timer.current);
    // Stands in for the PUT to the vessel's settings.
    timer.current = setTimeout((): void => {
      setState("saved");
    }, 700);
  }

  return (
    <SettingSelect
      label="Vessel default language"
      description="Used when a crew member has not chosen a language of their own."
      value={value}
      options={[
        { value: "en", label: "English" },
        { value: "nl", label: "Nederlands" },
        { value: "fr", label: "Français" },
        { value: "de", label: "Deutsch" },
        { value: "es", label: "Español" },
        { value: "it", label: "Italiano" },
      ]}
      state={state}
      onSave={save}
    />
  );
}

import { SaveChip } from "@bosunkit/components/setting-control";
import type { ReactElement } from "react";

export const description: string = "The green chip a control shows once its change is saved, which fades.";

export default function Saved(): ReactElement {
  return <SaveChip state="saved" />;
}

import { SettingToggle, type SaveState } from "@bosunkit/components/setting-control";
import { useEffect, useRef, useState, type Dispatch, type ReactElement, type RefObject, type SetStateAction } from "react";

export const description: string =
  "A switch whose save fails: it turns back to the saved value and the amber chip stays until the next attempt.";

export default function SaveFailed(): ReactElement {
  const [checked, setChecked]: [boolean, Dispatch<SetStateAction<boolean>>] = useState<boolean>(true);
  const [state, setState]: [SaveState, Dispatch<SetStateAction<SaveState>>] = useState<SaveState>("idle");
  const timer: RefObject<ReturnType<typeof setTimeout> | undefined> = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
  useEffect((): (() => void) => (): void => {
    clearTimeout(timer.current);
  }, []);

  function toggle(next: boolean): void {
    const previous: boolean = checked;
    setChecked(next);
    setState("saving");
    clearTimeout(timer.current);
    // Stands in for a PUT the vessel rejects: the switch returns to the value that is still saved.
    timer.current = setTimeout((): void => {
      setChecked(previous);
      setState("error");
    }, 900);
  }

  return (
    <SettingToggle
      label="Shore power alarm"
      description="Press the switch: this example's save always fails."
      checked={checked}
      state={state}
      onCheckedChange={toggle}
    />
  );
}

import { Button } from "@bosunkit/components/button";
import { isValidMmsi, MmsiInput } from "@bosunkit/components/mmsi-input";
import { checkNewPassword, PasswordInput } from "@bosunkit/components/password-input";
import { PositionInput, type Position } from "@bosunkit/components/position-input";
import { QrCode, wifiNetworkText } from "@bosunkit/components/qr-code";
import { SectionHeading } from "@bosunkit/components/section-heading";
import { SettingRow, type SaveState, type SettingRowControl } from "@bosunkit/components/setting-control";
import type { MessageKey, Translator } from "@bosunkit/i18n";
import { useTranslator } from "@bosunkit/provider";
import { Anchor, Copy, Wifi } from "lucide-react";
import {
  useEffect,
  useId,
  useRef,
  useState,
  type Dispatch,
  type ReactElement,
  type ReactNode,
  type RefObject,
  type SetStateAction,
} from "react";

export const description: string =
  "Kit controls inside setting rows: the vessel's MMSI and home port, and its Wi-Fi passwords. A value that fails " +
  "its rules is not saved and the row says why. The guest password is shown, with a copy button and a code a " +
  "phone's camera joins from; the crew network's password is never shown again once saved.";

/** How long the example's save takes to come back. */
const SAVE_MS: number = 900;

/**
 * A WPA2 passphrase: 8 to 63 printable ASCII characters, without the vessel's or the network's name. Lengths and a
 * character set, as NIST SP 800-63B-4 asks; no character classes.
 */
const GUEST_RULES: {
  readonly minLength: number;
  readonly maxLength: number;
  readonly contextWords: readonly string[];
} = { minLength: 8, maxLength: 63, contextWords: ["Althea", "Althea Guest"] };

const WPA2_RULES: string = "minlength: 8; maxlength: 63; allowed: ascii-printable;";

/** The crew network's password: the same lengths, without the vessel's or either network's name. */
const CREW_RULES: {
  readonly minLength: number;
  readonly maxLength: number;
  readonly contextWords: readonly string[];
} = { minLength: 8, maxLength: 63, contextWords: ["Althea", "Althea Guest"] };

/** The guest password, shown so the crew can read it out, copy it, or let a guest's phone scan it. */
function GuestJoin({ password }: { password: string }): ReactElement {
  const [copied, setCopied]: [string, Dispatch<SetStateAction<string>>] = useState<string>("");
  return (
    <div style={{ display: "flex", flexWrap: "wrap", alignItems: "center", gap: "var(--space-md)" }}>
      <QrCode
        value={wifiNetworkText({ ssid: "Althea Guest", password })}
        label="Code to join Althea Guest with a phone's camera"
        size="8em"
      />
      <div style={{ display: "grid", gap: "var(--space-xs)", justifyItems: "start" }}>
        <Button
          type="button"
          size="sm"
          onClick={(): void => {
            navigator.clipboard.writeText(password).then(
              (): void => {
                setCopied("Copied the guest password.");
              },
              (): void => {
                setCopied("Couldn't copy. Select the password in the field and copy it.");
              },
            );
          }}
        >
          <Copy aria-hidden="true" size={14} /> Copy password
        </Button>
        <span role="status" style={{ fontSize: "0.75em" }}>
          {copied}
        </span>
      </div>
    </div>
  );
}

/** Whether two positions are the same place; a position the fields do not hold whole is `null`. */
function samePosition(first: Position | null, second: Position | null): boolean {
  return (
    first === second ||
    (first !== null && second !== null && first.latitude === second.latitude && first.longitude === second.longitude)
  );
}

/** A setting's save lifecycle: a save comes back as saved after SAVE_MS, standing in for the PUT to the vessel. */
function useSave<Value>(onLanded: (saved: Value) => void): [SaveState, (next: Value) => void] {
  const [state, setState]: [SaveState, Dispatch<SetStateAction<SaveState>>] = useState<SaveState>("idle");
  const timer: RefObject<ReturnType<typeof setTimeout> | undefined> = useRef<ReturnType<typeof setTimeout> | undefined>(
    undefined,
  );
  useEffect((): (() => void) => {
    return (): void => {
      clearTimeout(timer.current);
    };
  }, []);

  function save(next: Value): void {
    setState("saving");
    clearTimeout(timer.current);
    timer.current = setTimeout((): void => {
      onLanded(next);
      setState("saved");
    }, SAVE_MS);
  }

  return [state, save];
}

function Group({ icon, title, children }: { icon: ReactNode; title: string; children: ReactNode }): ReactElement {
  const headingId: string = useId();
  return (
    <section aria-labelledby={headingId} style={{ display: "flex", flexDirection: "column", gap: "var(--space-sm)" }}>
      <SectionHeading level={3} id={headingId} icon={icon}>
        {title}
      </SectionHeading>
      {children}
    </section>
  );
}

export default function NestingControls(): ReactElement {
  const translator: Translator<MessageKey> = useTranslator();
  const [mmsi, setMmsi]: [string, Dispatch<SetStateAction<string>>] = useState<string>("235012345");
  const [mmsiState, saveMmsi]: [SaveState, (next: string) => void] = useSave<string>(setMmsi);
  const [homePort, setHomePort]: [Position | null, Dispatch<SetStateAction<Position | null>>] =
    useState<Position | null>({ latitude: 50.8472, longitude: -1.3 });
  const [homePortState, saveHomePort]: [SaveState, (next: Position | null) => void] = useSave<Position | null>(
    setHomePort,
  );
  // The guest password is handed to guests, so the vessel hands it back and the row shows it.
  const [guestPassword, setGuestPassword]: [string, Dispatch<SetStateAction<string>>] =
    useState<string>("harbor-lantern-41");
  const [guestState, saveGuest]: [SaveState, (next: string) => void] = useSave<string>(setGuestPassword);
  // The crew network's password is never handed back, so the page only knows whether one is saved.
  const [crewSaved, setCrewSaved]: [boolean, Dispatch<SetStateAction<boolean>>] = useState<boolean>(true);
  const [crewState, saveCrew]: [SaveState, (next: string) => void] = useSave<string>((): void => {
    setCrewSaved(true);
  });
  const [marinaSaved, setMarinaSaved]: [boolean, Dispatch<SetStateAction<boolean>>] = useState<boolean>(true);
  const [marinaState, saveMarina]: [SaveState, (next: string) => void] = useSave<string>((): void => {
    setMarinaSaved(true);
  });

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: "var(--space-xl)", width: "100%" }}>
      <Group icon={<Anchor />} title="Vessel identity">
        <SettingRow<string>
          label="MMSI"
          description="The vessel's own number, from its radio licence."
          value={mmsi}
          state={mmsiState}
          validate={(draft: string): string | undefined =>
            isValidMmsi(draft) ? undefined : "Type all nine digits of the vessel's MMSI."
          }
          onSave={saveMmsi}
        >
          {(control: SettingRowControl<string>): ReactElement => (
            <MmsiInput
              id={control.id}
              value={control.draft}
              onValueChange={control.onDraftChange}
              disabled={control.disabled}
              aria-describedby={control.describedBy}
            />
          )}
        </SettingRow>
        <SettingRow<Position | null>
          label="Home port"
          description="Where the vessel is kept; the anchor alarm and the tide table start from here."
          value={homePort}
          isEqual={samePosition}
          state={homePortState}
          validate={(draft: Position | null): string | undefined =>
            draft === null ? "Give the latitude and the longitude, both whole." : undefined
          }
          onSave={saveHomePort}
        >
          {(control: SettingRowControl<Position | null>): ReactElement => (
            <PositionInput
              id={control.id}
              value={control.draft}
              onValueChange={control.onDraftChange}
              disabled={control.disabled}
            />
          )}
        </SettingRow>
      </Group>
      <Group icon={<Wifi />} title="Wi-Fi">
        <SettingRow<string>
          label="Guest Wi-Fi password"
          description="The password visitors use on the Althea Guest network; shown, so the crew can hand it on."
          value={guestPassword}
          saved={false}
          state={guestState}
          validate={(draft: string): string | undefined => checkNewPassword(draft, GUEST_RULES, translator).refusal}
          onSave={saveGuest}
        >
          {(control: SettingRowControl<string>): ReactElement => (
            <>
              <PasswordInput
                id={control.id}
                purpose="shared"
                minLength={GUEST_RULES.minLength}
                maxLength={GUEST_RULES.maxLength}
                contextWords={GUEST_RULES.contextWords}
                value={control.draft}
                onValueChange={control.onDraftChange}
                disabled={control.disabled}
                aria-describedby={control.describedBy}
              />
              <GuestJoin password={guestPassword} />
            </>
          )}
        </SettingRow>
        <SettingRow<string>
          label="Crew Wi-Fi password"
          description="The password of the Althea network the crew's devices and the instruments use."
          value=""
          saved={crewSaved}
          savedSummary="A password is saved"
          changeLabel="Change password"
          state={crewState}
          validate={(draft: string): string | undefined => checkNewPassword(draft, CREW_RULES, translator).refusal}
          onSave={saveCrew}
        >
          {(control: SettingRowControl<string>): ReactElement => (
            <PasswordInput
              id={control.id}
              purpose="new"
              username="Althea"
              passwordRules={WPA2_RULES}
              minLength={CREW_RULES.minLength}
              maxLength={CREW_RULES.maxLength}
              contextWords={CREW_RULES.contextWords}
              value={control.draft}
              onValueChange={control.onDraftChange}
              disabled={control.disabled}
              aria-describedby={control.describedBy}
            />
          )}
        </SettingRow>
        <SettingRow<string>
          label="Upstream Wi-Fi password"
          description="The password of Hamble Point Marina's network, which bosun joins for its internet."
          value=""
          saved={marinaSaved}
          savedSummary="A password is saved"
          changeLabel="Change password"
          state={marinaState}
          onSave={saveMarina}
        >
          {(control: SettingRowControl<string>): ReactElement => (
            <PasswordInput
              id={control.id}
              purpose="current"
              username="Hamble Point Marina"
              value={control.draft}
              onValueChange={control.onDraftChange}
              disabled={control.disabled}
              aria-describedby={control.describedBy}
            />
          )}
        </SettingRow>
      </Group>
    </div>
  );
}