@clicktap/ui 0.32.0 → 0.33.0

package/components/Time/Time.d.ts

@@ -0,0 +1,13 @@
+import { TimeProps } from './Time.types';
+/**
+ * Renders an instant as a localized, timezone-aware `<time>` element.
+ *
+ * The displayed string is formatted in the **server** timezone from `TimezoneProvider` by
+ * default; pass `local` to render it in the viewer's timezone instead. Because the resolved
+ * timezone comes from context (identical on server and client) and `Intl.DateTimeFormat` is
+ * deterministic, server and first client render produce the same string — no hydration
+ * mismatch. The machine-readable `dateTime` attribute always carries the unambiguous UTC
+ * instant regardless of the displayed zone.
+ */
+export declare function Time({ locale, fallback, children, local, showZone, timeZone: timeZoneOverride, timeZoneName, ...options }: TimeProps): import("react/jsx-runtime").JSX.Element;
+export default Time;

package/components/Time/Time.js

@@ -0,0 +1 @@
+"use client";import{jsx as o,Fragment as m}from"react/jsx-runtime";import{useTimezone as v}from"../Timezone/TimezoneContext.js";import"react";function w({locale:r="en-US",fallback:n="-",children:e,local:a=!1,showZone:s=!1,timeZone:f,timeZoneName:u,...d}){const{timezone:i,viewerTimezone:l}=v();if(e==null)return o(m,{children:n});const t=new Date(e);if(Number.isNaN(t.valueOf()))return o(m,{children:n});const c=f??(a?l??i:i),T=new Intl.DateTimeFormat(r,{...d,timeZone:c,timeZoneName:u??(s?"short":void 0)}).format(t);return o("time",{dateTime:t.toISOString(),children:T})}export{w as Time,w as default};

package/components/Time/Time.types.d.ts

@@ -0,0 +1,21 @@
+import { ReactNode } from 'react';
+export type TimeProps = Intl.DateTimeFormatOptions & {
+    /** BCP 47 locale used for formatting. Defaults to `en-US`. */
+    locale?: string;
+    /** Rendered when `children` is missing or not a valid date. Defaults to `-`. */
+    fallback?: ReactNode;
+    /** The instant to render — ISO string, `Date`, or epoch milliseconds. */
+    children?: string | Date | number;
+    /**
+     * Opt this output into the viewer's local ("client") timezone instead of the configured
+     * default ("server") timezone. Falls back to the server timezone when the viewer's zone is
+     * not yet known (no cookie), so first-render output stays hydration-safe. Defaults to
+     * `false` (server time).
+     */
+    local?: boolean;
+    /**
+     * Append the timezone abbreviation (e.g. "EST") to the output. Shorthand for
+     * `timeZoneName: 'short'`; an explicit `timeZoneName` always wins.
+     */
+    showZone?: boolean;
+};

package/components/Time/index.d.ts

@@ -0,0 +1,2 @@
+export { Time } from './Time';
+export type { TimeProps } from './Time.types';

package/components/Time/index.js

@@ -0,0 +1 @@
+import{Time as t}from"./Time.js";import"react/jsx-runtime";import"../Timezone/TimezoneContext.js";import"react";export{t as Time};

package/components/Timezone/TimezoneContext.d.ts

@@ -0,0 +1,25 @@
+import { ReactNode } from 'react';
+export type TimezoneConfig = {
+    /**
+     * The configured default ("server") timezone — an IANA identifier resolved on the server
+     * (the `display/default_timezone` setting, or the PHP default when unset) and passed down
+     * so server and client render identical date/time output. This is the default zone every
+     * `<Time>` renders in.
+     */
+    timezone: string;
+    /**
+     * The viewer's ("client") timezone, when known — typically derived server-side from a
+     * cookie set by `TimezoneCookieSync`. Only used by outputs that opt in via the `local`
+     * prop. Undefined until the cookie is present (first visit), in which case `local` outputs
+     * fall back to `timezone`, keeping rendering hydration-safe.
+     */
+    viewerTimezone?: string;
+};
+type TimezoneProviderProps = {
+    children: ReactNode;
+    timezone: string;
+    viewerTimezone?: string;
+};
+export declare function TimezoneProvider({ children, timezone, viewerTimezone, }: TimezoneProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useTimezone(): TimezoneConfig;
+export {};

package/components/Timezone/TimezoneContext.js

@@ -0,0 +1 @@
+"use client";import{jsx as r}from"react/jsx-runtime";import{createContext as i,useContext as m}from"react";const e=i({timezone:"UTC"});function s({children:o,timezone:t,viewerTimezone:n}){return r(e.Provider,{value:{timezone:t,viewerTimezone:n},children:o})}function x(){return m(e)}export{s as TimezoneProvider,x as useTimezone};

package/components/Timezone/TimezoneCookieSync.d.ts

@@ -0,0 +1,17 @@
+/** Cookie name carrying the viewer's IANA timezone for server-side `local`-mode rendering. */
+export declare const TIMEZONE_COOKIE_NAME = "displayTimezone";
+type TimezoneCookieSyncProps = {
+    /** Cookie lifetime in seconds. Defaults to one year. */
+    maxAgeSeconds?: number;
+};
+/**
+ * Writes the viewer's detected timezone to a cookie **after hydration** (in an effect only —
+ * never during render), so the *next* server render can resolve `local`-mode timestamps in
+ * the viewer's zone deterministically. Renders nothing.
+ *
+ * Setting the cookie only in an effect is deliberate: the current render must not re-resolve
+ * the timezone from the browser, or it would diverge from the server output and reintroduce
+ * the hydration mismatch this whole mechanism exists to avoid.
+ */
+export declare function TimezoneCookieSync({ maxAgeSeconds, }?: TimezoneCookieSyncProps): null;
+export {};

package/components/Timezone/TimezoneCookieSync.js

@@ -0,0 +1 @@
+"use client";import{useEffect as o}from"react";const n="displayTimezone",i=3600*24*365;function m({maxAgeSeconds:e=i}={}){return o(()=>{try{const t=Intl.DateTimeFormat().resolvedOptions().timeZone;t&&(document.cookie=`${n}=${encodeURIComponent(t)};path=/;max-age=${e};samesite=lax`)}catch{}},[e]),null}export{n as TIMEZONE_COOKIE_NAME,m as TimezoneCookieSync};

package/components/Timezone/index.d.ts

@@ -0,0 +1,2 @@
+export { TimezoneProvider, useTimezone, type TimezoneConfig, } from './TimezoneContext';
+export { TimezoneCookieSync, TIMEZONE_COOKIE_NAME } from './TimezoneCookieSync';

package/components/Timezone/index.js

@@ -0,0 +1 @@
+import{TimezoneProvider as m,useTimezone as n}from"./TimezoneContext.js";import{TIMEZONE_COOKIE_NAME as t,TimezoneCookieSync as E}from"./TimezoneCookieSync.js";import"react/jsx-runtime";import"react";export{t as TIMEZONE_COOKIE_NAME,E as TimezoneCookieSync,m as TimezoneProvider,n as useTimezone};

package/index.d.ts

@@ -0,0 +1,12 @@
+export * from './components/Avatar';
+export * from './components/Badge';
+export * from './components/Button';
+export * from './components/Divider';
+export * from './components/Link';
+export * from './components/Meter';
+export * from './components/Switch';
+export * from './components/Time';
+export * from './components/TimeInput';
+export * from './components/Timezone';
+export * from './components/ToggleButton';
+export * from './components/Tooltip';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clicktap/ui",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "private": false,
   "author": "Clicktap",
   "description": "A library of React UI components and low-level hooks.",