From 8bf7d233e51c4d891db64ac1963dfb00ee245f8e Mon Sep 17 00:00:00 2001
From: Nathan Stilwell <nathanstilwell@cockroachlabs.com>
Date: Mon, 21 Sep 2020 16:47:17 -0400
Subject: [PATCH] Extending FuzzyTime props with native span props (#118)

* Extending props with Native Span props

Pass through span props to allow implementor to extend FuzzyTime with
native span props

* got some feedback that comments might be helpful here
---
 .../ui-components/src/FuzzyTime/FuzzyTime.tsx | 20 ++++++++++++++-----
 packages/ui-components/src/FuzzyTime/util.ts  | 18 ++++++++++++++---
 2 files changed, 30 insertions(+), 8 deletions(-)

diff --git a/packages/ui-components/src/FuzzyTime/FuzzyTime.tsx b/packages/ui-components/src/FuzzyTime/FuzzyTime.tsx
index 5f0278a69..9d9cdde2f 100644
--- a/packages/ui-components/src/FuzzyTime/FuzzyTime.tsx
+++ b/packages/ui-components/src/FuzzyTime/FuzzyTime.tsx
@@ -1,20 +1,30 @@
-import React, { FunctionComponent } from "react";
+import React, { FunctionComponent, HTMLAttributes } from "react";
 import classnames from "classnames/bind";
 
 import { fuzzy } from "./util";
 import styles from "./FuzzyTime.module.scss";
 
-export interface FuzzyTimeProps {
+type OwnFuzzyProps = {
   timestamp: Date;
-}
+};
+
+export type FuzzyTimeProps = OwnFuzzyProps &
+  React.HTMLAttributes<HTMLSpanElement>;
 
 const cx = classnames.bind(styles);
 
-export const FuzzyTime: FunctionComponent<FuzzyTimeProps> = ({ timestamp }) => {
+export const FuzzyTime: FunctionComponent<FuzzyTimeProps> = ({
+  timestamp,
+  ...rest
+}) => {
   const timeago = fuzzy(timestamp);
   const classnames = cx("fuzzy-time");
 
-  return <span className={classnames}>{timeago}</span>;
+  return (
+    <span className={classnames} {...rest}>
+      {timeago}
+    </span>
+  );
 };
 
 export * from "./util";
diff --git a/packages/ui-components/src/FuzzyTime/util.ts b/packages/ui-components/src/FuzzyTime/util.ts
index 1c96acce1..2afadb83c 100644
--- a/packages/ui-components/src/FuzzyTime/util.ts
+++ b/packages/ui-components/src/FuzzyTime/util.ts
@@ -1,9 +1,10 @@
 import { aYear, aMonth, aDay, anHour, aMinute, aSecond } from "./constants";
 
+// A time unit represents a relative time unit to display time in (seconds, hours, years, etc)
 export type TimeUnit = {
-  amount: number;
-  comparator: (x: number) => boolean;
-  template: (d: number) => string;
+  amount: number; // the amount of time the unit represents (number of milliseconds)
+  comparator: (x: number) => boolean; // a function to to decide if this unit should be used or not
+  template: (d: number) => string; // a string template used to display time unit given number of milliseconds
 };
 
 export const gteq = (x: number, y: number): boolean => x >= y;
@@ -59,12 +60,23 @@ export const TimeUnits: Array<TimeUnit> = [
   },
 ];
 
+// fuzzyFormatter will return a formatting function given an offset
+// Usage:
+//    const formatter = fuzzyFormatter(numberOfMilliseconds);
+//    const fuzzyTimeString = formatter(timeUnit);
+//
 export const fuzzyFormatter = (offset: number) => (unit: TimeUnit) => {
   if (unit === undefined || offset === undefined) return "";
   const duration = Math.floor(offset / unit.amount);
   return unit.template(duration);
 };
 
+// setFuzzy takes a date representing "now" and returns a function that will format
+// a given date in a "time ago" form.
+// Usage:
+//    const getFuzzyTime = setFuzzy(now);
+//    const fuzzyTime = getFuzzyTime(someDate);
+//
 export const setFuzzy = (now: Date) => (timedate: Date) => {
   const diff = now.getTime() - timedate.getTime();
   const format = fuzzyFormatter(diff);