docs: add more info about properties

Parkreiner · Parkreiner · commit d0a57de9fe1f · 2025-05-07T18:04:48.000Z
diff --git a/site/src/components/SignInLayout/SignInLayout.tsx b/site/src/components/SignInLayout/SignInLayout.tsx
@@ -4,7 +4,7 @@ import type { FC, PropsWithChildren } from "react";
 
 export const SignInLayout: FC<PropsWithChildren> = ({ children }) => {
 	const year = useTimeSync({
-		idealRefreshIntervalMs: Number.POSITIVE_INFINITY,
+		targetRefreshInterval: Number.POSITIVE_INFINITY,
 		select: (date) => date.getFullYear(),
 	});
 
diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
@@ -158,8 +158,28 @@ export const TimeSyncProvider: FC<TimeSyncProviderProps> = ({
 };
 
 type UseTimeSyncOptions<T = Date> = Readonly<{
-	idealRefreshIntervalMs: number;
-	selectDeps?: readonly unknown[];
+	/**
+	 * targetRefreshInterval is the ideal interval of time, in milliseconds,
+	 * that defines how often the hook should refresh with the newest Date
+	 * value from TimeSync.
+	 *
+	 * Note that a refresh is not the same as a re-render. If the hook is
+	 * refreshed with a new datetime, but its select callback produces the same
+	 * value as before, the hook will skip re-rendering.
+	 *
+	 * The hook reserves the right to refresh MORE frequently than the
+	 * specified value if it would guarantee that the hook does not get out of
+	 * sync with other useTimeSync users that are currently mounted on screen.
+	 */
+	targetRefreshInterval: number;
+
+	/**
+	 * selectDependencies acts like the dependency array for a useMemo callback.
+	 * Whenever any of the elements in the array change by value, that will
+	 * cause the select callback to re-run synchronously and produce a new,
+	 * up-to-date value for the current render.
+	 */
+	selectDependencies?: readonly unknown[];
 
 	/**
 	 * Allows you to transform any date values received from the TimeSync class.
@@ -189,7 +209,11 @@ type UseTimeSyncOptions<T = Date> = Readonly<{
  * interval.
  */
 export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
-	const { select, selectDeps, idealRefreshIntervalMs } = options;
+	const {
+		select,
+		selectDependencies: selectDeps,
+		targetRefreshInterval: idealRefreshIntervalMs,
+	} = options;
 	const timeSync = useContext(timeSyncContext);
 	if (timeSync === null) {
 		throw new Error("Cannot call useTimeSync outside of a TimeSyncProvider");
diff --git a/site/src/pages/CliInstallPage/CliInstallPageView.tsx b/site/src/pages/CliInstallPage/CliInstallPageView.tsx
@@ -11,7 +11,7 @@ type CliInstallPageViewProps = {
 
 export const CliInstallPageView: FC<CliInstallPageViewProps> = ({ origin }) => {
 	const year = useTimeSync({
-		idealRefreshIntervalMs: Number.POSITIVE_INFINITY,
+		targetRefreshInterval: Number.POSITIVE_INFINITY,
 		select: (date) => date.getFullYear(),
 	});
 
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicenseCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicenseCard.tsx
@@ -25,7 +25,7 @@ export const LicenseCard: FC<LicenseCardProps> = ({
 	onRemove,
 	isRemoving,
 }) => {
-	const time = useTimeSync({ idealRefreshIntervalMs: 30_000 });
+	const time = useTimeSync({ targetRefreshInterval: 30_000 });
 	const [licenseIDMarkedForRemoval, setLicenseIDMarkedForRemoval] = useState<
 		number | undefined
 	>(undefined);
diff --git a/site/src/pages/LoginPage/LoginPageView.tsx b/site/src/pages/LoginPage/LoginPageView.tsx
@@ -29,7 +29,7 @@ export const LoginPageView: FC<LoginPageViewProps> = ({
 	redirectTo,
 }) => {
 	const year = useTimeSync({
-		idealRefreshIntervalMs: Number.POSITIVE_INFINITY,
+		targetRefreshInterval: Number.POSITIVE_INFINITY,
 		select: (date) => date.getFullYear(),
 	});
 	const location = useLocation();
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
@@ -44,7 +44,7 @@ interface DateRangeProps {
 
 export const DateRange: FC<DateRangeProps> = ({ value, onChange }) => {
 	const currentTime = useTimeSync({
-		idealRefreshIntervalMs: IDEAL_REFRESH_ONE_MINUTE,
+		targetRefreshInterval: IDEAL_REFRESH_ONE_MINUTE,
 	});
 	const selectionStatusRef = useRef<"idle" | "selecting">("idle");
 	const [ranges, setRanges] = useState<RangesState>([
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
@@ -71,8 +71,8 @@ export default function TemplateInsightsPage() {
 
 	const paramsInterval = searchParams.get("interval");
 	const insightsInterval = useTimeSync<InsightsInterval>({
-		idealRefreshIntervalMs: IDEAL_REFRESH_ONE_DAY,
-		selectDeps: [paramsInterval],
+		targetRefreshInterval: IDEAL_REFRESH_ONE_DAY,
+		selectDependencies: [paramsInterval],
 		select: (newDate) => {
 			const templateCreateDate = new Date(template.created_at);
 			const hasFiveWeeksOrMore = addWeeks(templateCreateDate, 5) < newDate;
diff --git a/site/src/pages/WorkspacePage/AppStatuses.tsx b/site/src/pages/WorkspacePage/AppStatuses.tsx
@@ -154,7 +154,7 @@ export const AppStatuses: FC<AppStatusesProps> = ({
 	referenceDate,
 }) => {
 	const comparisonDate = useTimeSync({
-		idealRefreshIntervalMs: IDEAL_REFRESH_ONE_MINUTE,
+		targetRefreshInterval: IDEAL_REFRESH_ONE_MINUTE,
 		select: (dateState) => referenceDate ?? dateState,
 	});
 	const theme = useTheme();
diff --git a/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx b/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
@@ -163,7 +163,7 @@ const AutostopDisplay: FC<AutostopDisplayProps> = ({
 	};
 
 	const activityStatus = useTimeSync({
-		idealRefreshIntervalMs: 1_000,
+		targetRefreshInterval: 1_000,
 		select: () => getWorkspaceActivityStatus(workspace),
 	});
 	const { message, tooltip, danger } = autostopDisplay(
