[react] feat: Added docs for components/Time

packages/react/components/Time/index.mjs

@@ -6,12 +6,20 @@ const hour = 3600000
 const minute = 60000
 const second = 1000
 
+/**
+ * A component to render date + time
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {string} props.iso - Time in ISO format
+ * @returns {JSX.Element}
+ */
 export const DateAndTime = ({ iso }) => {
   const dt = DateTime.fromISO(iso)
   return dt.toLocaleString(DateTime.DATETIME_MED)
 }
 
-export const TimeForHumans = ({ iso, future = false }) => {
+const TimeForHumans = ({ iso, future = false }) => {
   const suffix = future ? 'from now' : 'ago'
   const dates = [DateTime.fromISO(iso), DateTime.now()]
   if (future) dates.reverse()
@@ -36,11 +44,36 @@ export const TimeForHumans = ({ iso, future = false }) => {
   return `${years} years ${suffix}`
 }
 
-export const TimeAgo = (props) => <TimeForHumans {...props} />
-export const TimeToGo = (props) => <TimeForHumans {...props} future />
+/**
+ * A component to render the time delta between now and a moment in the past.
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {string} props.iso - Time in ISO format
+ * @returns {JSX.Element}
+ */
+export const TimeAgo = (props) => <TimeForHumans {...props} future={false} />
 
+/**
+ * A component to render the time delta between now and a moment in the future.
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {string} props.iso - Time in ISO format
+ * @returns {JSX.Element}
+ */
+export const TimeToGo = (props) => <TimeForHumans {...props} future={true} />
+
+/**
+ * A component to render the time delta between now and a moment in the past.
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {string} props.time - Timestamp in milliseconds
+ * @returns {JSX.Element}
+ */
 export const TimeAgoBrief = ({ time }) => {
-  const d = Math.floor(Date.now() - time)
+  const d = Math.floor(Date.now() - Number(time))
   if (d > day) return `${Math.floor(d / day)}d ago`
   if (d > hour) return `${Math.floor(d / hour)}h ago`
   if (d > minute * 2) return `${Math.floor(d / minute)}m ago`
@@ -48,8 +81,16 @@ export const TimeAgoBrief = ({ time }) => {
   return `${d}ms ago`
 }
 
+/**
+ * A component to render the time delta between now and a moment in the future.
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {string} props.time - Timestamp in milliseconds
+ * @returns {JSX.Element}
+ */
 export const TimeToGoBrief = ({ time }) => {
-  const d = Math.floor(time * 1000 - Date.now())
+  const d = Math.floor(Number(time) - Date.now())
   if (d > day) return `${Math.floor(d / day)}d`
   if (d > hour) return `${Math.floor(d / hour)}h`
   if (d > minute * 2) return `${Math.floor(d / minute)}m`

packages/react/mkdocs.sh

@@ -38,3 +38,4 @@ jsdoc -c jsdoc.json components/Spinner/* > ../../sites/dev/prebuild/jsdoc/react/
 jsdoc -c jsdoc.json components/Stats/* > ../../sites/dev/prebuild/jsdoc/react/components/stats.json
 jsdoc -c jsdoc.json components/Tab/* > ../../sites/dev/prebuild/jsdoc/react/components/tab.json
 jsdoc -c jsdoc.json components/Table/* > ../../sites/dev/prebuild/jsdoc/react/components/table.json
+jsdoc -c jsdoc.json components/Time/* > ../../sites/dev/prebuild/jsdoc/react/components/time.json

sites/dev/docs/reference/packages/react/components/time/_examples.js

@@ -0,0 +1,9 @@
+import React from 'react'
+import { DateAndTime, TimeAgo, TimeToGo, TimeAgoBrief, TimeToGoBrief } from '@freesewing/react/components/Time'
+
+export const DateAndTimeExample = () => <DateAndTime iso="2025-05-29T12:34:00.000Z" />
+export const TimeAgoExample = () => <TimeAgo iso="2025-05-21T12:34:00.000Z" />
+export const TimeToGoExample = () => <TimeToGo iso="2035-05-29T12:34:00.000Z" />
+export const TimeAgoBriefExample = () => <TimeAgoBrief   time={1748000000000} />
+export const TimeToGoBriefExample = () => <TimeToGoBrief time={1900000000000} />
+

sites/dev/docs/reference/packages/react/components/time/readme.mdx

@@ -2,6 +2,43 @@
 title: Time
 ---
 
-:::note
-This page is yet to be created
-:::
+import { DocusaurusDoc } from '@freesewing/react/components/Docusaurus'
+import { ComponentDocs } from '@site/src/components/component-docs.js'
+import * as jsdoc from '@site/prebuild/jsdoc/components.time.mjs'
+import { TimeToGoExample, TimeAgoExample, TimeToGoBriefExample, TimeAgoBriefExample, DateAndTimeExample } from './_examples.js'
+
+<DocusaurusDoc>
+
+- [Components](#components)
+
+## Components
+
+The **Table** component family provides the following components:
+
+- [DateAndTime](#dateandtime)
+- [TimeAgo](#timeago)
+- [TimeAgoBrief](#timeagobrief)
+- [TimeToGo](#timetogo)
+- [TimeToGoBrief](#timetogobrief)
+
+### DateAndTime
+
+<ComponentDocs docs={jsdoc.jsdocDateAndTime} example={DateAndTimeExample} />
+
+### TimeAgo
+
+<ComponentDocs docs={jsdoc.jsdocTimeAgo} example={TimeAgoExample} />
+
+### TimeAgoBrief
+
+<ComponentDocs docs={jsdoc.jsdocTimeAgoBrief} example={TimeAgoBriefExample} />
+
+### TimeToGo
+
+<ComponentDocs docs={jsdoc.jsdocTimeToGo} example={TimeToGoExample} />
+
+### TimeToGoBrief
+
+<ComponentDocs docs={jsdoc.jsdocTimeToGoBrief} example={TimeToGoBriefExample} />
+
+</DocusaurusDoc>