ranuts 0.4.0-alpha.1 → 0.4.0-alpha.2

package/dist/src/utils/time.d.ts

@@ -1,3 +1,5 @@
+/** Accepted everywhere a moment in time is taken; `undefined` means "now". */
+export type DateInput = number | string | Date;
 /**
  * @description: Format a date with a token pattern. Accepts a timestamp, a date string, a
  * `Date`, or nothing (meaning now). Wrap literal text in `[]` to keep it out of the substitution.
@@ -23,10 +25,10 @@
  * ```ts
  * formatDate();                                          // '2026-07-25 14:30:00'
  * formatDate(1753425000000, 'YYYY/MM/DD');               // '2026/07/25'
- * formatDate(new Date(), 'YYYY[年]MM[月]DD[日] hh:mm a'); // '2026年07月25日 02:30 pm' (escaped literals)
+ * formatDate(new Date(), 'YYYY[年]MM[月]DD[日] hh:mm a'); // '2026 年 07 月 25 日 02:30 pm' (escaped literals)
  * ```
  */
-export declare const formatDate: (value?: number | string | Date, pattern?: string) => string;
+export declare const formatDate: (value?: DateInput, pattern?: string) => string;
 /**
  * @description: Turn a timestamp into a `Date` carrying a `format` method.
  * @deprecated Use [`formatDate`](#formatdate). This returns a `Date` with an extra method
@@ -39,12 +41,80 @@ export declare const formatDate: (value?: number | string | Date, pattern?: stri
 export declare function timestampToTime(timestamp?: number | string): Date & {
     format?: Function;
 };
+/**
+ * @description: Format an elapsed number of **seconds** as a colon-separated clock duration,
+ * the shape media players use for a playhead: `mm:ss`, widening to `hh:mm:ss` past an hour.
+ *
+ * This is a length of time, not a point in time — for the latter see
+ * [`formatDate`](#formatdate) (absolute) and [`formatRelative`](#formatrelative) (relative).
+ *
+ * @param {number} seconds elapsed seconds; negatives clamp to `0`
+ * @return {string} the duration, or `''` when the input is not a finite number — a player
+ * asks for `video.duration` before metadata loads and gets `NaN`, and an empty label reads
+ * better there than `NaN:NaN`
+ * @example
+ * ```ts
+ * formatDuration(0);    // '00:00'
+ * formatDuration(65);   // '01:05'
+ * formatDuration(3661); // '01:01:01'
+ * formatDuration(NaN);  // ''
+ * ```
+ */
+export declare const formatDuration: (seconds: number) => string;
 /**
  * @description: Format a number of seconds as a colon-separated duration
+ * @deprecated Renamed to [`formatDuration`](#formatduration) — `timeFormat` said nothing about
+ * *which* of the three time formats it was, and read backwards from its `formatDate` sibling.
+ * This alias stays for compatibility and behaves identically.
  * @param {number} time
- * @return {*}
+ * @return {string}
  */
 export declare const timeFormat: (time: number) => string;
+/** `'compact'` is ours; the other three are `Intl.RelativeTimeFormat` styles. */
+export type RelativeStyle = 'long' | 'short' | 'narrow' | 'compact';
+export interface FormatRelativeOptions {
+    /** What to measure against. Defaults to the current time. */
+    now?: DateInput;
+    /** BCP 47 tag(s); defaults to the runtime's locale. Ignored by the `compact` style. */
+    locale?: string | string[];
+    /** Defaults to `'long'` (`'3 days ago'`). */
+    style?: RelativeStyle;
+    /**
+     * `'auto'` (the default here) swaps in idioms where a language has them — `yesterday`
+     * rather than `1 day ago`, `now` rather than `in 0 seconds`. `'always'` keeps the number.
+     */
+    numeric?: 'always' | 'auto';
+}
+/**
+ * @description: Format a point in time relative to another — "3 days ago", "in 2 hours".
+ *
+ * Localization is delegated to the platform's `Intl.RelativeTimeFormat`, which has been
+ * available in every major browser since 2020 and knows each language's plural and
+ * inflection rules. This function supplies only the part `Intl` deliberately leaves out:
+ * picking *which* unit to express the gap in.
+ *
+ * Like `Intl` itself it reports a **single** unit — a gap of 3 days and 6 hours is
+ * "3 days ago", never "3 days and 6 hours ago".
+ *
+ * The extra `compact` style is the dense badge form seen next to list items (`5m`, `3h`,
+ * `2d`). It is a magnitude only: it carries **no direction**, so a future timestamp reads
+ * the same as a past one. Use it for feeds of past events, and any other style when the
+ * reader has to tell past from future.
+ *
+ * @param {DateInput} value the moment to describe
+ * @param {FormatRelativeOptions} options
+ * @return {string} the description, or `''` when either end cannot be parsed
+ * @example
+ * ```ts
+ * const twoHoursAgo = Date.now() - 2 * 3600_000;
+ * formatRelative(twoHoursAgo);                          // '2 hours ago'
+ * formatRelative(twoHoursAgo, { style: 'short' });      // '2 hr. ago'
+ * formatRelative(twoHoursAgo, { style: 'compact' });    // '2h'
+ * formatRelative(twoHoursAgo, { locale: 'zh-CN' });     // '2 小时前'
+ * formatRelative(Date.now() + 60_000);                  // 'in 1 minute'
+ * ```
+ */
+export declare const formatRelative: (value: DateInput, options?: FormatRelativeOptions) => string;
 /**
  * @description: Current timestamp
  * @return {*}

package/dist/test/utils/autosize.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/utils/i18n.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/utils/speech.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/utils/time.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/utils/truncate.test.d.ts

@@ -0,0 +1 @@
+export {};