diff --git a/.gitignore b/.gitignore index f164418..5d68909 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,5 @@ +<<<<<<< HEAD +node_modules +======= scripts/node_modules/ +>>>>>>> origin/main diff --git a/docs-templates/api/components/relativetime.mdx b/docs-templates/api/components/relativetime.mdx new file mode 100644 index 0000000..4dd8eaf --- /dev/null +++ b/docs-templates/api/components/relativetime.mdx @@ -0,0 +1,184 @@ +--- +title: RelativeTime +description: API reference for the RelativeTime component +--- + +## Overview + +The `` component renders a localized relative time string, such as "2 hours ago" or "in 3 days". +It supports two usage modes: automatically selecting the best unit from a `Date`, or explicitly specifying a value and unit. + +```jsx +{someDate} +// Output: "2 hours ago" +``` + +All formatting is handled locally using the [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) API. + +## Reference + +### Props + + + +### Description +| Prop Name | Description | +|-----------|-------------| +| `children` | A `Date` object. The component automatically selects the best unit (seconds, minutes, hours, days, weeks, months, or years) and formats the time relative to now. | +| `date` | Alias for `children`. A `Date` object to compute relative time from now. If both are provided, `date` takes precedence. | +| `value` | An explicit numeric value for the relative time (e.g., `-1` for "yesterday"). Must be used together with `unit`. | +| `unit` | The unit of time (e.g., `'second'`, `'minute'`, `'hour'`, `'day'`, `'week'`, `'month'`, `'year'`). Required when using `value`. | +| `options` | Optional formatting options following the [`Intl.RelativeTimeFormatOptions` specification](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat). Use this to control `numeric` and `style` behavior. | +| `locales` | Optional locales to specify the formatting locale. If not provided, the user's locale is used. Read more about specifying locales [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument). | + +### Returns + +`JSX.Element` containing the formatted relative time as a string, or `null` if no date or value is provided. + +--- +## Examples + +### Auto-select unit from a Date +Pass a `Date` as children and the component automatically picks the best unit. + +```jsx title="PostTimestamp.jsx" copy +import { RelativeTime } from '__PACKAGE_NAME__'; + +export default function PostTimestamp({ post }) { + return ( + {post.createdAt} // [!code highlight] + ); + // Output: "2 hours ago", "3 days ago", "in 5 minutes", etc. +} +``` + +### Using the date prop +You can also pass the date via the `date` prop instead of `children`. + +```jsx title="PostTimestamp.jsx" copy +import { RelativeTime } from '__PACKAGE_NAME__'; + +export default function PostTimestamp({ post }) { + return ( + // [!code highlight] + ); +} +``` + +### Explicit value and unit +Specify an exact value and unit, mirroring the `Intl.RelativeTimeFormat` API. + +```jsx title="Reminder.jsx" copy +import { RelativeTime } from '__PACKAGE_NAME__'; + +export default function Reminder() { + return ( +

+ Your trial ends . // [!code highlight] +

+ ); + // Output: "Your trial ends in 3 days." +} +``` + +### Specifying locales +Display relative time in a specific locale. + +```jsx title="FrenchTimestamp.jsx" copy +import { RelativeTime } from '__PACKAGE_NAME__'; + +export default function FrenchTimestamp({ date }) { + return ( + {date} // [!code highlight] + ); + // Output: "il y a 2 heures" +} +``` + +### Translating RelativeTime +Wrap `` in a `` component to include it in a translated sentence. + +```jsx title="Comment.jsx" copy +import { T, RelativeTime } from '__PACKAGE_NAME__'; + +export default function Comment({ comment }) { + return ( + + Posted {comment.createdAt} // [!code highlight] + + ); +} +``` + +### Custom formatting options +Control the output style with `Intl.RelativeTimeFormat` options. + +```jsx title="VerboseTimestamp.jsx" copy +import { RelativeTime } from '__PACKAGE_NAME__'; + +export default function VerboseTimestamp({ date }) { + return ( + + {date} + + ); + // With numeric: 'auto', outputs "yesterday" instead of "1 day ago" +} +``` + +--- + +## Notes + * The `` component is a variable component that formats relative time values. + * When using auto mode (with a `Date`), the component selects the most appropriate unit automatically. + * The component uses [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) under the hood. + +## Next steps + * For more details and usage examples of the `` component and other variable components like ``, ``, ``, and ``, see the [Using Variable Components](__DOCS_PATH__/guides/variables) documentation. diff --git a/docs/en-US/core/class/methods/formatting/format-relative-time-from-date.mdx b/docs/en-US/core/class/methods/formatting/format-relative-time-from-date.mdx new file mode 100644 index 0000000..8053584 --- /dev/null +++ b/docs/en-US/core/class/methods/formatting/format-relative-time-from-date.mdx @@ -0,0 +1,95 @@ +--- +title: formatRelativeTimeFromDate +description: API reference for the formatRelativeTimeFromDate method to format relative time from a Date +--- + +## Overview + +The `formatRelativeTimeFromDate` method takes a `Date` and formats it as a localized relative time string, automatically selecting the most appropriate unit. + +```typescript +const gt = new GT({ targetLocale: 'en-US' }); + +const formatted = gt.formatRelativeTimeFromDate( + new Date(Date.now() - 3600000) +); +// Returns: "1 hour ago" +``` + +## Reference + +### Parameters + +| Name | Type | Description | +|------|------|-------------| +| `date` | `Date` | The date to format relative to now | +| `options?` | `Intl.RelativeTimeFormatOptions & { locales?: string \| string[] }` | Optional formatting configuration | + +### Options + +| Name | Type | Description | +|------|------|-------------| +| `locales?` | `string \| string[]` | Override locales for formatting (defaults to instance locales) | +| `numeric?` | `'always' \| 'auto'` | Whether to always use numeric output (default: `'auto'`) | +| `style?` | `'long' \| 'short' \| 'narrow'` | The length of the output | + +### Returns + +`string` - The formatted relative time string (e.g., "2 hours ago", "in 3 days"). + +--- + +## Examples + +### Basic usage + +```typescript copy +import { GT } from 'generaltranslation'; + +const gt = new GT({ targetLocale: 'en-US' }); + +// Recent timestamps +const fiveMinAgo = new Date(Date.now() - 5 * 60 * 1000); +console.log(gt.formatRelativeTimeFromDate(fiveMinAgo)); +// Output: "5 minutes ago" + +// Future dates +const nextWeek = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000); +console.log(gt.formatRelativeTimeFromDate(nextWeek)); +// Output: "in 1 week" +``` + +### Different locales + +```typescript copy +const twoHoursAgo = new Date(Date.now() - 2 * 60 * 60 * 1000); + +console.log(gt.formatRelativeTimeFromDate(twoHoursAgo, { locales: 'es-ES' })); +// Output: "hace 2 horas" + +console.log(gt.formatRelativeTimeFromDate(twoHoursAgo, { locales: 'zh-CN' })); +// Output: "2小时前" +``` + +### Natural language output + +```typescript copy +const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000); + +console.log(gt.formatRelativeTimeFromDate(yesterday, { numeric: 'auto' })); +// Output: "yesterday" +``` + +--- + +## Notes + +* Automatically selects the best unit based on the time difference +* Unit selection follows natural thresholds: seconds → minutes → hours → days → weeks → months → years +* Uses `Intl.RelativeTimeFormat` under the hood + +## Related methods + +* See [`formatRelativeTime`](/docs/core/class/methods/formatting/format-relative-time) for explicit value + unit formatting +* See [`formatDateTime`](/docs/core/class/methods/formatting/format-date-time) for absolute date formatting +* See standalone [`formatRelativeTimeFromDate`](/docs/core/functions/formatting/format-relative-time-from-date) for use without GT instance diff --git a/docs/en-US/core/class/methods/formatting/format-relative-time.mdx b/docs/en-US/core/class/methods/formatting/format-relative-time.mdx new file mode 100644 index 0000000..87134d0 --- /dev/null +++ b/docs/en-US/core/class/methods/formatting/format-relative-time.mdx @@ -0,0 +1,87 @@ +--- +title: formatRelativeTime +description: API reference for the formatRelativeTime method to format relative time strings according to locale conventions +--- + +## Overview + +The `formatRelativeTime` method formats a numeric value and time unit into a localized relative time string. + +```typescript +const gt = new GT({ targetLocale: 'en-US' }); + +const formatted = gt.formatRelativeTime(-1, 'day', { + numeric: 'auto' +}); +// Returns: "yesterday" +``` + +## Reference + +### Parameters + +| Name | Type | Description | +|------|------|-------------| +| `value` | `number` | The numeric value (negative for past, positive for future) | +| `unit` | `Intl.RelativeTimeFormatUnit` | The unit of time (`'second'`, `'minute'`, `'hour'`, `'day'`, `'week'`, `'month'`, `'year'`) | +| `options?` | `Intl.RelativeTimeFormatOptions & { locales?: string \| string[] }` | Optional formatting configuration | + +### Options + +| Name | Type | Description | +|------|------|-------------| +| `locales?` | `string \| string[]` | Override locales for formatting (defaults to instance locales) | +| `numeric?` | `'always' \| 'auto'` | Whether to always use numeric output (default: `'auto'`) | +| `style?` | `'long' \| 'short' \| 'narrow'` | The length of the output | + +### Returns + +`string` - The formatted relative time string. + +--- + +## Examples + +### Basic usage + +```typescript copy +import { GT } from 'generaltranslation'; + +const gt = new GT({ targetLocale: 'en-US' }); + +// Past +console.log(gt.formatRelativeTime(-2, 'hour')); +// Output: "2 hours ago" + +// Future +console.log(gt.formatRelativeTime(3, 'day')); +// Output: "in 3 days" + +// Natural language +console.log(gt.formatRelativeTime(-1, 'day', { numeric: 'auto' })); +// Output: "yesterday" +``` + +### Different locales + +```typescript copy +console.log(gt.formatRelativeTime(-1, 'week', { locales: 'fr-FR' })); +// Output: "la semaine dernière" + +console.log(gt.formatRelativeTime(2, 'month', { locales: 'ja-JP' })); +// Output: "2 か月後" +``` + +--- + +## Notes + +* Uses browser-native `Intl.RelativeTimeFormat` for formatting +* When `numeric` is `'auto'`, special values like -1 day may produce "yesterday" instead of "1 day ago" + +## Related methods + +* See [`formatRelativeTimeFromDate`](/docs/core/class/methods/formatting/format-relative-time-from-date) for auto-selecting the unit from a Date +* See [`formatDateTime`](/docs/core/class/methods/formatting/format-date-time) for absolute date formatting +* See standalone [`formatRelativeTime`](/docs/core/functions/formatting/format-relative-time) for use without GT instance +* Check out [`Intl.RelativeTimeFormat` documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) for more options diff --git a/docs/en-US/core/class/methods/formatting/meta.json b/docs/en-US/core/class/methods/formatting/meta.json index 9f690e6..30d4ead 100644 --- a/docs/en-US/core/class/methods/formatting/meta.json +++ b/docs/en-US/core/class/methods/formatting/meta.json @@ -1,4 +1,4 @@ { "title": "Formatting", - "pages": ["./format-cutoff", "./format-date-time", "./format-list-to-parts", "./format-message", "./format-num"] + "pages": ["./format-cutoff", "./format-date-time", "./format-relative-time", "./format-relative-time-from-date", "./format-list-to-parts", "./format-message", "./format-num"] } diff --git a/docs/en-US/core/functions/formatting/format-relative-time-from-date.mdx b/docs/en-US/core/functions/formatting/format-relative-time-from-date.mdx new file mode 100644 index 0000000..8989a7a --- /dev/null +++ b/docs/en-US/core/functions/formatting/format-relative-time-from-date.mdx @@ -0,0 +1,108 @@ +--- +title: formatRelativeTimeFromDate +description: Standalone function to format relative time from a Date, automatically selecting the best unit +--- + +## Overview + +The standalone `formatRelativeTimeFromDate` function takes a `Date` and formats it as a relative time string, automatically selecting the most appropriate unit (seconds, minutes, hours, days, weeks, months, or years). + +```typescript +import { formatRelativeTimeFromDate } from 'generaltranslation'; + +const formatted = formatRelativeTimeFromDate( + new Date(Date.now() - 3600000), // 1 hour ago + { locales: 'en-US' } +); +// Returns: "1 hour ago" +``` + +## Reference + +### Parameters + +| Name | Type | Description | +|------|------|-------------| +| `date` | `Date` | The date to format relative to now | +| `options` | `RelativeTimeFormatOptions & { locales: string \| string[] }` | Formatting configuration with locales | + +### RelativeTimeFormatOptions + +| Name | Type | Description | +|------|------|-------------| +| `locales` | `string \| string[]` | Locales for formatting (required) | +| `numeric?` | `'always' \| 'auto'` | Whether to always use numeric output (e.g., `'auto'` may produce "yesterday" instead of "1 day ago") | +| `style?` | `'long' \| 'short' \| 'narrow'` | The length of the output | + +### Returns + +`string` - The formatted relative time string (e.g., "2 hours ago", "in 3 days"). + +--- + +## Examples + +### Basic usage + +```typescript copy +import { formatRelativeTimeFromDate } from 'generaltranslation'; + +// A date from 2 hours ago +const twoHoursAgo = new Date(Date.now() - 2 * 60 * 60 * 1000); +console.log(formatRelativeTimeFromDate(twoHoursAgo, { locales: 'en-US' })); +// Output: "2 hours ago" + +// A date 3 days in the future +const threeDaysFromNow = new Date(Date.now() + 3 * 24 * 60 * 60 * 1000); +console.log(formatRelativeTimeFromDate(threeDaysFromNow, { locales: 'en-US' })); +// Output: "in 3 days" +``` + +### Different locales + +```typescript copy +const date = new Date(Date.now() - 2 * 60 * 60 * 1000); + +console.log(formatRelativeTimeFromDate(date, { locales: 'fr-FR' })); +// Output: "il y a 2 heures" + +console.log(formatRelativeTimeFromDate(date, { locales: 'ja-JP' })); +// Output: "2 時間前" + +console.log(formatRelativeTimeFromDate(date, { locales: 'de-DE' })); +// Output: "vor 2 Stunden" +``` + +### With formatting options + +```typescript copy +const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000); + +// Default numeric: 'auto' +console.log(formatRelativeTimeFromDate(yesterday, { + locales: 'en-US' +})); +// Output: "yesterday" + +// Strictly numeric with numeric: 'always' +console.log(formatRelativeTimeFromDate(yesterday, { + locales: 'en-US', + numeric: 'always' +})); +// Output: "1 day ago" +``` + +--- + +## Notes + +* The function automatically selects the best unit based on the time difference between the date and now +* Unit selection follows natural thresholds: seconds → minutes → hours → days → weeks → months → years +* Uses `Intl.RelativeTimeFormat` under the hood +* The `locales` parameter is required for the standalone function + +## Next steps + +* See [`formatRelativeTime`](/docs/core/functions/formatting/format-relative-time) for explicit value + unit formatting +* See [`formatDateTime`](/docs/core/functions/formatting/format-date-time) for absolute date formatting +* See GT class [`formatRelativeTimeFromDate`](/docs/core/class/methods/formatting/format-relative-time-from-date) for instance-based usage diff --git a/docs/en-US/core/functions/formatting/format-relative-time.mdx b/docs/en-US/core/functions/formatting/format-relative-time.mdx new file mode 100644 index 0000000..74a69bb --- /dev/null +++ b/docs/en-US/core/functions/formatting/format-relative-time.mdx @@ -0,0 +1,118 @@ +--- +title: formatRelativeTime +description: Standalone function to format relative time strings according to locale conventions +--- + +## Overview + +The standalone `formatRelativeTime` function formats a relative time value and unit into a localized string without requiring a GT instance. + +```typescript +import { formatRelativeTime } from 'generaltranslation'; + +const formatted = formatRelativeTime(-2, 'day', { + locales: 'en-US' +}); +// Returns: "2 days ago" +``` + +## Reference + +### Parameters + +| Name | Type | Description | +|------|------|-------------| +| `value` | `number` | The numeric value (negative for past, positive for future) | +| `unit` | `Intl.RelativeTimeFormatUnit` | The unit of time (`'second'`, `'minute'`, `'hour'`, `'day'`, `'week'`, `'month'`, `'year'`) | +| `options` | `RelativeTimeFormatOptions & { locales: string \| string[] }` | Formatting configuration with locales | + +### RelativeTimeFormatOptions + +| Name | Type | Description | +|------|------|-------------| +| `locales` | `string \| string[]` | Locales for formatting (required) | +| `numeric?` | `'always' \| 'auto'` | Whether to always use numeric output (e.g., `'auto'` may produce "yesterday" instead of "1 day ago") | +| `style?` | `'long' \| 'short' \| 'narrow'` | The length of the output (e.g., "in 1 month" vs "in 1 mo." vs "in 1 mo") | + +### Returns + +`string` - The formatted relative time string. + +--- + +## Examples + +### Basic usage + +```typescript copy +import { formatRelativeTime } from 'generaltranslation'; + +// Past times +console.log(formatRelativeTime(-1, 'day', { locales: 'en-US' })); +// Output: "1 day ago" + +// Future times +console.log(formatRelativeTime(3, 'hour', { locales: 'en-US' })); +// Output: "in 3 hours" + +// Different locales +console.log(formatRelativeTime(-2, 'week', { locales: 'de-DE' })); +// Output: "vor 2 Wochen" +``` + +### Auto vs numeric output + +```typescript copy +// Default numeric: 'auto' +console.log(formatRelativeTime(-1, 'day', { + locales: 'en-US' +})); +// Output: "yesterday" + +// With numeric: 'always' for strictly numeric output +console.log(formatRelativeTime(-1, 'day', { + locales: 'en-US', + numeric: 'always' +})); +// Output: "1 day ago" +``` + +### Style options + +```typescript copy +// Long (default) +console.log(formatRelativeTime(2, 'month', { + locales: 'en-US', + style: 'long' +})); +// Output: "in 2 months" + +// Short +console.log(formatRelativeTime(2, 'month', { + locales: 'en-US', + style: 'short' +})); +// Output: "in 2 mo." + +// Narrow +console.log(formatRelativeTime(2, 'month', { + locales: 'en-US', + style: 'narrow' +})); +// Output: "in 2 mo." +``` + +--- + +## Notes + +* Uses the browser-native `Intl.RelativeTimeFormat` for formatting +* The `locales` parameter is required for the standalone function +* For auto-selecting the best unit from a `Date`, use [`formatRelativeTimeFromDate`](/docs/core/functions/formatting/format-relative-time-from-date) + +## Next steps + +* See [`formatRelativeTimeFromDate`](/docs/core/functions/formatting/format-relative-time-from-date) for auto-selecting the unit from a Date +* See [`formatDateTime`](/docs/core/functions/formatting/format-date-time) for absolute date formatting +* See GT class [`formatRelativeTime`](/docs/core/class/methods/formatting/format-relative-time) for instance-based usage +* Check out [`Intl.RelativeTimeFormat` documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) for more options diff --git a/docs/en-US/core/functions/formatting/meta.json b/docs/en-US/core/functions/formatting/meta.json index 9f690e6..30d4ead 100644 --- a/docs/en-US/core/functions/formatting/meta.json +++ b/docs/en-US/core/functions/formatting/meta.json @@ -1,4 +1,4 @@ { "title": "Formatting", - "pages": ["./format-cutoff", "./format-date-time", "./format-list-to-parts", "./format-message", "./format-num"] + "pages": ["./format-cutoff", "./format-date-time", "./format-relative-time", "./format-relative-time-from-date", "./format-list-to-parts", "./format-message", "./format-num"] } diff --git a/docs/en-US/next/api/components/meta.json b/docs/en-US/next/api/components/meta.json index 242971f..b95f58e 100644 --- a/docs/en-US/next/api/components/meta.json +++ b/docs/en-US/next/api/components/meta.json @@ -7,6 +7,7 @@ "./num", "./currency", "./datetime", + "./relativetime", "./derive", "./branch", "./plural", diff --git a/docs/en-US/next/api/components/relativetime.mdx b/docs/en-US/next/api/components/relativetime.mdx new file mode 100644 index 0000000..26b5c21 --- /dev/null +++ b/docs/en-US/next/api/components/relativetime.mdx @@ -0,0 +1,5 @@ +--- +title: RelativeTime +description: API reference for the RelativeTime component +--- +{/* AUTO-GENERATED: Do not edit directly. Edit the template in content/docs-templates/ instead. */} diff --git a/docs/en-US/react/api/components/meta.json b/docs/en-US/react/api/components/meta.json index 5aa8fe1..616d7d2 100644 --- a/docs/en-US/react/api/components/meta.json +++ b/docs/en-US/react/api/components/meta.json @@ -7,6 +7,7 @@ "./num", "./currency", "./datetime", + "./relativetime", "./derive", "./branch", "./plural", diff --git a/docs/en-US/react/api/components/relativetime.mdx b/docs/en-US/react/api/components/relativetime.mdx new file mode 100644 index 0000000..26b5c21 --- /dev/null +++ b/docs/en-US/react/api/components/relativetime.mdx @@ -0,0 +1,5 @@ +--- +title: RelativeTime +description: API reference for the RelativeTime component +--- +{/* AUTO-GENERATED: Do not edit directly. Edit the template in content/docs-templates/ instead. */}