Local Time

npm install motion clsx tailwind-merge

import { clsx, type ClassValue } from "clsx";
import { extendTailwindMerge } from "tailwind-merge";

/* tailwind-merge must know the site's type scale (globals.css) is a font size, not a text color — otherwise
   cn("text-h6 text-muted-foreground") drops text-h6. */
const twMerge = extendTailwindMerge({
  extend: { classGroups: { "font-size": [{ text: ["display", "h1", "h2", "h3", "h4", "h5", "h6"] }] } },
});

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

"use client";

import * as React from "react";
import { cn } from "@/lib/utils";

/*
 * Local Time — the time on a visitor's own clock, or in another place's time zone ("7:41 PM"), following the clock.
 * It is Framer's "Time & Date" code component, which three of our templates carry (the Ciketo header, the Lookis header and
 * footer, the Marai Neesu footer), as a `<time>` element.
 *
 * It ticks on the minute, or on the second with `seconds`, aligned to the real boundary (not a timer that drifts), and
 * draws again when the tab comes back to the front. Only a string that changed is drawn, and figures are tabular, so the
 * text does not shift as the digits change.
 *
 * The server cannot know the visitor's moment, so it draws `fallback` (nothing by default) and the browser fills the time
 * in right after hydration, which React does not count as a mismatch: the time is read through useSyncExternalStore with
 * a server snapshot of null. Give `fallback` a placeholder the width of the time ("--:-- --") when the row must not move.
 * `timeZone` takes any IANA zone ("Asia/Dubai"); the visitor's own is the default. `options` is Intl.DateTimeFormat's, for a
 * date or a long form.
 */

export type LocalTimeProps = Omit<React.ComponentProps<"time">, "children" | "dateTime"> & {
  /** An IANA zone such as "Asia/Dubai"; the visitor's own zone when left out. */
  timeZone?: string;
  /** BCP 47 locale. "en-US" draws "7:41 PM". */
  locale?: string;
  /** Show seconds; the clock then ticks every second instead of every minute. */
  seconds?: boolean;
  /** Force a 12 or a 24 hour clock; the locale decides when left out. */
  hour12?: boolean;
  /** Any Intl.DateTimeFormat options, in place of the hour and minute (`{ dateStyle: "medium" }` draws a date). */
  options?: Intl.DateTimeFormatOptions;
  /** What the server draws, and the browser until it has the time. Nothing by default. */
  fallback?: React.ReactNode;
};

export function LocalTime({ timeZone, locale = "en-US", seconds = false, hour12, options, fallback, className, ...props }: LocalTimeProps) {
  /* A key for the options that matter, so a new object with the same content does not rebuild the formatter. */
  const optionsKey = JSON.stringify(options ?? null);
  const formatter = React.useMemo(
    () =>
      new Intl.DateTimeFormat(locale, {
        ...(options ?? { hour: "numeric", minute: "2-digit", ...(seconds ? { second: "2-digit" } : {}) }),
        ...(hour12 === undefined ? {} : { hour12 }),
        ...(timeZone ? { timeZone } : {}),
      }),
    // eslint-disable-next-line react-hooks/exhaustive-deps
    [locale, seconds, hour12, timeZone, optionsKey],
  );
  const ticksEverySecond = formatter.resolvedOptions().second !== undefined || (options?.fractionalSecondDigits ?? 0) > 0;
  const period = ticksEverySecond ? 1000 : 60_000;

  const subscribe = React.useCallback(
    (notify: () => void) => {
      let timer = 0;
      const tick = () => {
        notify();
        timer = window.setTimeout(tick, period - (Date.now() % period));
      };
      timer = window.setTimeout(tick, period - (Date.now() % period));
      const visible = () => document.visibilityState === "visible" && notify();
      document.addEventListener("visibilitychange", visible);
      return () => {
        window.clearTimeout(timer);
        document.removeEventListener("visibilitychange", visible);
      };
    },
    [period],
  );

  const text = React.useSyncExternalStore(
    subscribe,
    () => formatter.format(new Date()),
    () => null,
  );

  return (
    <time {...props} dateTime={text === null ? undefined : new Date().toISOString()} className={cn("tabular-nums", className)}>
      {text ?? fallback}
    </time>
  );
}