beez-ui 0.6.2 → 0.8.0

package/dist/hooks/use-minute-clock.js

@@ -0,0 +1,147 @@
+"use client";
+import { c as _c } from "react/compiler-runtime";
+/** Shares one minute-aligned clock across components, hydration-safe and with exact wake-ups. */
+import { useEffect, useSyncExternalStore } from "react";
+const MILLISECONDS_PER_MINUTE = 6e4;
+const NO_WAKE_UP_TIMES = [];
+const clockListeners = new Set();
+/**
+* Latest instant the clock settled on. It only moves forward: minute ticks
+* raise it to the current minute and wake-ups (or an instant the server
+* confirmed) raise it to that exact instant. Null while nobody observes the
+* clock, so a later mount starts again from the real time.
+*/
+let settledClockTime = null;
+let minuteTickTimeoutId = null;
+function truncateToMinute(time) {
+	return Math.floor(time / MILLISECONDS_PER_MINUTE) * MILLISECONDS_PER_MINUTE;
+}
+function notifyClockListeners() {
+	for (const listener of clockListeners) {
+		listener();
+	}
+}
+/**
+* Moves the clock forward to `instantTime` (epoch ms) and re-renders every
+* consumer. Earlier instants are ignored, so the clock never goes back. Use
+* it when a scheduled boundary is reached or the server proved that an
+* instant already passed (for example an occurrence it reported as ended
+* while the local clock still lagged behind).
+*
+* @param instantTime - Instant the clock must reach, in epoch milliseconds.
+*/
+export function advanceMinuteClockTo(instantTime) {
+	if (settledClockTime !== null && instantTime <= settledClockTime) {
+		return;
+	}
+	settledClockTime = instantTime;
+	notifyClockListeners();
+}
+/**
+* Schedules the next tick on the next minute boundary. Each tick measures the
+* remaining time again instead of relying on a fixed interval, so the clock
+* never lags by the mount offset and a timer that fires a little early or
+* late re-aligns on the following boundary.
+*/
+function scheduleNextMinuteTick() {
+	const currentTime = Date.now();
+	const millisecondsToNextMinute = truncateToMinute(currentTime) + MILLISECONDS_PER_MINUTE - currentTime;
+	minuteTickTimeoutId = window.setTimeout(() => {
+		scheduleNextMinuteTick();
+		notifyClockListeners();
+	}, millisecondsToNextMinute);
+}
+function stopMinuteTicks() {
+	if (minuteTickTimeoutId !== null) {
+		window.clearTimeout(minuteTickTimeoutId);
+		minuteTickTimeoutId = null;
+	}
+}
+function subscribe(onStoreChange) {
+	clockListeners.add(onStoreChange);
+	if (clockListeners.size === 1) {
+		scheduleNextMinuteTick();
+	}
+	return () => {
+		clockListeners.delete(onStoreChange);
+		if (clockListeners.size === 0) {
+			stopMinuteTicks();
+			settledClockTime = null;
+		}
+	};
+}
+function getSnapshot() {
+	const currentMinuteTime = truncateToMinute(Date.now());
+	if (settledClockTime === null || currentMinuteTime > settledClockTime) {
+		settledClockTime = currentMinuteTime;
+	}
+	return settledClockTime;
+}
+function getServerSnapshot() {
+	return null;
+}
+function findNextWakeUpTime(wakeUpTimes, nowTime) {
+	let nextWakeUpTime = null;
+	for (const wakeUpTime of wakeUpTimes) {
+		if (wakeUpTime > nowTime && (nextWakeUpTime === null || wakeUpTime < nextWakeUpTime)) {
+			nextWakeUpTime = wakeUpTime;
+		}
+	}
+	return nextWakeUpTime;
+}
+/**
+* Current time, refreshed on every minute boundary and at the exact instant of
+* each wake-up time that falls before the next boundary. Between boundaries it
+* holds the minute (or the last wake-up instant) it settled on. Returns null
+* during server rendering and hydration so time-dependent UI never produces a
+* server/client markup mismatch; it settles to a number right after mount.
+*
+* @param wakeUpTimes - Instants (epoch ms) where time-dependent UI changes,
+*   such as the end of an occurrence on screen; the clock re-renders exactly
+*   then instead of waiting for the next minute.
+* @returns The clock value in epoch milliseconds, or null before hydration.
+*/
+export function useMinuteClock(t0) {
+	const $ = _c(8);
+	const wakeUpTimes = t0 === undefined ? NO_WAKE_UP_TIMES : t0;
+	const nowTime = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+	let t1;
+	if ($[0] !== nowTime || $[1] !== wakeUpTimes) {
+		t1 = nowTime === null ? null : findNextWakeUpTime(wakeUpTimes, nowTime);
+		$[0] = nowTime;
+		$[1] = wakeUpTimes;
+		$[2] = t1;
+	} else {
+		t1 = $[2];
+	}
+	const nextWakeUpTime = t1;
+	let t2;
+	if ($[3] !== nextWakeUpTime) {
+		t2 = () => {
+			if (nextWakeUpTime === null) {
+				return;
+			}
+			const millisecondsToWakeUp = nextWakeUpTime - Date.now();
+			if (millisecondsToWakeUp > MILLISECONDS_PER_MINUTE) {
+				return;
+			}
+			const wakeUpTimeoutId = window.setTimeout(() => advanceMinuteClockTo(nextWakeUpTime), Math.max(0, millisecondsToWakeUp));
+			return () => window.clearTimeout(wakeUpTimeoutId);
+		};
+		$[3] = nextWakeUpTime;
+		$[4] = t2;
+	} else {
+		t2 = $[4];
+	}
+	let t3;
+	if ($[5] !== nextWakeUpTime || $[6] !== nowTime) {
+		t3 = [nextWakeUpTime, nowTime];
+		$[5] = nextWakeUpTime;
+		$[6] = nowTime;
+		$[7] = t3;
+	} else {
+		t3 = $[7];
+	}
+	useEffect(t2, t3);
+	return nowTime;
+}

package/dist/hooks/use-month-transition-direction.d.ts

@@ -0,0 +1,21 @@
+export declare const MONTH_TRANSITION_DIRECTION: {
+    readonly next: "next";
+    readonly none: "none";
+    readonly previous: "previous";
+};
+export type MonthTransitionDirection = (typeof MONTH_TRANSITION_DIRECTION)[keyof typeof MONTH_TRANSITION_DIRECTION];
+/**
+ * Compares two `YYYY-MM` keys, which sort chronologically as plain strings.
+ * @param fromMonth - Month shown before, or null when there is none.
+ * @param toMonth - Month shown now.
+ * @returns `next` or `previous` when the month changed, `none` otherwise.
+ */
+export declare function resolveMonthTransitionDirection(fromMonth: string | null, toMonth: string): MonthTransitionDirection;
+/**
+ * Direction of the latest month change of a calendar: a new `month` on the same instance, or a
+ * fresh mount right after another month of the same calendar was on screen.
+ * @param scopeKey - Calendar identity, so different calendars do not orient each other.
+ * @param month - Visible `YYYY-MM` month.
+ * @returns Direction to animate the month entrance with.
+ */
+export declare function useMonthTransitionDirection(scopeKey: string, month: string): MonthTransitionDirection;

package/dist/hooks/use-month-transition-direction.js

@@ -0,0 +1,110 @@
+"use client";
+import { c as _c } from "react/compiler-runtime";
+/** Tracks which way the visible month moved, to orient month entrance animations. */
+import { useEffect, useState } from "react";
+export const MONTH_TRANSITION_DIRECTION = {
+	next: "next",
+	none: "none",
+	previous: "previous"
+};
+/**
+* How long, in milliseconds, the last shown month still orients the next calendar mount. Month
+* links may remount the calendar behind a route loading state, so the memory must outlive that
+* gap but not a later, unrelated visit.
+*/
+const SHOWN_MONTH_MEMORY_MS = 5e3;
+/**
+* Last month shown by a calendar in this tab. It is written only from effects, which never run on
+* the server, so server renders and the hydration render always read `null` and match.
+*/
+let lastShownMonth = null;
+/**
+* Records the month a calendar is showing.
+* @param scopeKey - Calendar identity, such as a group or resource id.
+* @param month - Visible `YYYY-MM` month.
+*/
+function rememberShownMonth(scopeKey, month) {
+	lastShownMonth = {
+		month,
+		shownAt: Date.now(),
+		scopeKey
+	};
+}
+/**
+* Reads the month recently shown by the same calendar, if still within the memory window.
+* @param scopeKey - Calendar identity.
+* @returns The month, or null.
+*/
+function readRecentlyShownMonth(scopeKey) {
+	if (lastShownMonth === null || lastShownMonth.scopeKey !== scopeKey || Date.now() - lastShownMonth.shownAt > SHOWN_MONTH_MEMORY_MS) {
+		return null;
+	}
+	return lastShownMonth.month;
+}
+/**
+* Compares two `YYYY-MM` keys, which sort chronologically as plain strings.
+* @param fromMonth - Month shown before, or null when there is none.
+* @param toMonth - Month shown now.
+* @returns `next` or `previous` when the month changed, `none` otherwise.
+*/
+export function resolveMonthTransitionDirection(fromMonth, toMonth) {
+	if (fromMonth === null || fromMonth === toMonth) return MONTH_TRANSITION_DIRECTION.none;
+	return toMonth > fromMonth ? MONTH_TRANSITION_DIRECTION.next : MONTH_TRANSITION_DIRECTION.previous;
+}
+/**
+* Direction of the latest month change of a calendar: a new `month` on the same instance, or a
+* fresh mount right after another month of the same calendar was on screen.
+* @param scopeKey - Calendar identity, so different calendars do not orient each other.
+* @param month - Visible `YYYY-MM` month.
+* @returns Direction to animate the month entrance with.
+*/
+export function useMonthTransitionDirection(scopeKey, month) {
+	const $ = _c(11);
+	let t0;
+	if ($[0] !== month || $[1] !== scopeKey) {
+		t0 = () => ({
+			direction: resolveMonthTransitionDirection(readRecentlyShownMonth(scopeKey), month),
+			month
+		});
+		$[0] = month;
+		$[1] = scopeKey;
+		$[2] = t0;
+	} else {
+		t0 = $[2];
+	}
+	const [transition, setTransition] = useState(t0);
+	if (transition.month !== month) {
+		setTransition({
+			direction: resolveMonthTransitionDirection(transition.month, month),
+			month
+		});
+	}
+	let t1;
+	let t2;
+	if ($[3] !== month || $[4] !== scopeKey) {
+		t1 = () => {
+			rememberShownMonth(scopeKey, month);
+			return () => rememberShownMonth(scopeKey, month);
+		};
+		t2 = [month, scopeKey];
+		$[3] = month;
+		$[4] = scopeKey;
+		$[5] = t1;
+		$[6] = t2;
+	} else {
+		t1 = $[5];
+		t2 = $[6];
+	}
+	useEffect(t1, t2);
+	let t3;
+	if ($[7] !== month || $[8] !== transition.direction || $[9] !== transition.month) {
+		t3 = transition.month === month ? transition.direction : resolveMonthTransitionDirection(transition.month, month);
+		$[7] = month;
+		$[8] = transition.direction;
+		$[9] = transition.month;
+		$[10] = t3;
+	} else {
+		t3 = $[10];
+	}
+	return t3;
+}

package/dist/hooks/use-rich-link-editor.d.ts

@@ -0,0 +1,55 @@
+/** Owns the state of `RichLinkEditor`: content, tracked links, popover and selection. */
+import { type ClipboardEvent, type FormEvent, type KeyboardEvent } from "react";
+import { RICH_LINK_POPOVER_MODE } from "../lib/rich-text/link-markdown-constants.js";
+import type { ActiveRichPreviewLink, RichLink, RichPreviewSegment } from "../lib/rich-text/link-markdown-types.js";
+type RichLinkPopoverMode = (typeof RICH_LINK_POPOVER_MODE)[keyof typeof RICH_LINK_POPOVER_MODE];
+/** Plain-text content plus tracked links, used to snapshot/restore the editor. */
+export type RichLinkEditorDisplayState = {
+    content: string;
+    links: RichLink[];
+};
+type UseRichLinkEditorOptions = {
+    /** Persisted markdown loaded as the initial editor value. */
+    initialMarkdown?: string;
+    /** Called whenever the author changes the content (e.g. to clear errors). */
+    onContentChange?: () => void;
+};
+/** Imperative + reactive API exposed by `useRichLinkEditor` to the editor UI. */
+export type RichLinkEditorController = {
+    setEditorElement: (node: HTMLDivElement | null) => void;
+    segments: RichPreviewSegment[];
+    hasContent: boolean;
+    content: string;
+    activeLink: ActiveRichPreviewLink | null;
+    linkTextInput: string;
+    linkUrlInput: string;
+    popoverMode: RichLinkPopoverMode;
+    /** Whether the popover draft has visible text and an http(s) URL, so it can be saved. */
+    isLinkEditValid: boolean;
+    /** Whether the author typed a URL that cannot become a safe http(s) link. */
+    hasInvalidLinkUrl: boolean;
+    setLinkTextInput: (value: string) => void;
+    setLinkUrlInput: (value: string) => void;
+    setPopoverMode: (mode: RichLinkPopoverMode) => void;
+    handleBeforeInput: (event: FormEvent<HTMLDivElement>) => void;
+    handleInput: (event: FormEvent<HTMLDivElement>) => void;
+    handleKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void;
+    handlePaste: (event: ClipboardEvent<HTMLDivElement>) => void;
+    openLinkPopover: (segment: ActiveRichPreviewLink) => void;
+    closeLinkPopover: () => void;
+    removeLink: (segment: ActiveRichPreviewLink) => void;
+    saveLinkEdit: (segment: ActiveRichPreviewLink) => void;
+    serialize: () => string;
+    reset: (markdown?: string) => void;
+    getDisplayState: () => RichLinkEditorDisplayState;
+    loadFromDisplay: (state: RichLinkEditorDisplayState) => void;
+};
+/**
+ * Controls a rich link editor backed by a `contentEditable` element: it owns the
+ * plain-text content, the tracked explicit/suppressed links, the link popover
+ * state, and the selection bookkeeping, and exposes serialize/reset/snapshot
+ * helpers so a feature can persist or restore the value. The DOM rendering lives
+ * in `RichLinkEditor`.
+ */
+export declare function useRichLinkEditor(options?: UseRichLinkEditorOptions): RichLinkEditorController;
+export {};