@rio-cloud/uikit-mcp 1.0.1 → 1.1.1

package/dist/docs/start/guidelines/custom-rioglyph.md

@@ -0,0 +1,35 @@
+# Custom RIOglyph icon
+
+*Category:* Getting started
+*Section:* Guidelines
+*Source:* https://uikit.developers.rio.cloud/#start/guidelines/custom-rioglyph
+*Captured:* 2025-12-12T14:20:04.635Z
+
+To use a custom Rioglyph icon, there are two different approaches:
+
+## Custom RIOglyph icon
+
+1. Use an inline style with a CSS variable
+2. Define a CSS class that applies an SVG as a mask-image
+
+Below is an example of both approaches:
+
+**Approach 1: Inline style**
+
+```html
+<span class="rioglyph" style="--i: url(https://cdn.rio.cloud/images/uikit/react_logo.svg);"></span>
+```
+
+**Approach 2: Custom CSS class**
+
+```html
+<style>
+.rioglyph-custom-xxx {
+--i: url('https://cdn.rio.cloud/images/uikit/react_logo.svg');
+}
+</style>
+```
+
+```html
+<span class="rioglyph rioglyph-custom"></span>
+```

package/dist/docs/start/guidelines/formatting.md

@@ -0,0 +1,587 @@
+# Formatting guide
+
+*Category:* Getting started
+*Section:* Guidelines
+*Source:* https://uikit.developers.rio.cloud/#start/guidelines/formatting
+*Captured:* 2025-12-12T14:20:06.278Z
+
+Having a common date formatting guide is crucial to ensure consistency, clarity, and accuracy in documentation, making it easier to understand and interpret dates correctly across different contexts.
+
+## Formatting guide
+
+## Here's what you will find in the formatting guide
+
+- Date formats
+- Date formats overview If nothing else is specified use the default date format: YYYY-MM-DD Avoid the American date format: MM/DD/YYYY Use the Intl.DateTimeFormat to format dates for all locales Date and time format Format durations Formatting dates for headlines and sections Relative date and time Time format including timezones
+- Number formats
+- Number formats overview Omit unused or meaningless decimals Formatting numbers with units
+
+- Date formats overview
+- If nothing else is specified use the default date format: YYYY-MM-DD
+- Avoid the American date format: MM/DD/YYYY
+- Use the Intl.DateTimeFormat to format dates for all locales
+- Date and time format
+- Format durations
+- Formatting dates for headlines and sections
+- Relative date and time
+- Time format including timezones
+
+- Number formats overview
+- Omit unused or meaningless decimals
+- Formatting numbers with units
+
+## Date formats
+
+## Date formats overview
+
+This is a list of all supported langues and their respective date format showcasing also similar locales sharing the same format.
+
+## If nothing else is specified use the default date format: YYYY-MM-DD
+
+This format is defined in the ISO 8601 standard, which is maintained by the International Organization for Standardization (ISO). It's widely used for data exchange and communication because it:
+
+- Sorts chronologically: Dates appear in order when sorted alphabetically (e.g., 2023-12-31 comes before 2024-01-01).
+- Avoids ambiguity: The clear separation between year, month, and day eliminates confusion, especially when dealing with different cultural date order preferences.
+
+While some countries have their own preferred date formats for everyday use, YYYY-MM-DD is often the chosen format for:
+
+- International communication
+- Data storage and exchange
+- Software applications
+
+In the table above, Swedish (sv-SE) is the only locale listed that uses YYYY-MM-DD as the standard format. However, the international nature of the internet and technology has made YYYY-MM-DD increasingly familiar in many regions.
+
+If nothing else is specified use the default date format otherwise use the date format according the selected locale.
+
+## Avoid the American date format: MM/DD/YYYY
+
+While there's nothing inherently wrong with the American date format (MM/DD/YYYY), it's recommended to avoid it as the default for the following reasons:
+
+- Non-standard: It's not the international standard format defined by ISO 8601 (YYYY-MM-DD). This can lead to confusion and potential errors when exchanging data or collaborating with international teams.
+- Ambiguity: MM/DD/YYYY can be misinterpreted, especially when dealing with unfamiliar dates. For example, 05/07/2024 could be May 7th or July 5th.
+- Sorting Issues: Dates in MM/DD/YYYY format don't sort chronologically by default. This can be problematic when handling lists or data sets involving dates.
+- Limited Reach: The American date format is primarily used in the United States, Canada, and a few other countries. Using a more widely recognized format like YYYY-MM-DD promotes better international understanding.
+
+**Hint for Date Pickers**
+
+Be aware that some date picker components might default to the American format (MM/DD/YYYY) if no locale is explicitly defined. Double-check your date picker's settings to ensure it aligns with these guidelines.
+
+## Use the Intl.DateTimeFormat to format dates for all locales
+
+When formatting dates in React applications, you have two choices:
+
+- Vanilla Intl.DateTimeFormat: Use the standard function.
+- ReactIntl (recommended): Utilize ReactIntl's formatDate function or the FormattedDate component for a more convenient and potentially reusable approach.
+
+Regardless of the chosen method (direct function or ReactIntl), you'll have access to the same set of formatting options for customizing the date output with Intl.DateTimeFormat.
+
+The default date and time format for the default locale "en-GB" looks like this: 27/05/2024
+
+```jsx
+<FormattedDate value={new Date()} year='numeric' month='2-digit' day='2-digit' />
+```
+
+```javascript
+const formatDate = (date, locale) => {
+const options = {
+year: 'numeric',
+month: '2-digit',
+day: '2-digit'
+};
+
+const formatter = new Intl.DateTimeFormat(locale, options);
+return formatter.format(date);
+}
+
+const locales = [
+'bg-BG', 'cs-CZ', 'da-DK', 'el-GR', 'es-ES', 'et-EE', 'fi-FI', 'fr-FR',
+'hr-HR', 'hu-HU', 'it-IT', 'lt-LT', 'lv-LV', 'nb-NO', 'nl-NL', 'pl-PL',
+'pt-PT', 'ro-RO', 'sk-SK', 'sl-SI', 'sv-SE', 'de-DE', 'pt-BR', 'en-GB'
+];
+
+const today = new Date();
+
+locales.forEach(locale => {
+const formattedDate = formatDate(today, locale);
+console.log(`Locale: ${locale}, Formatted date: ${formattedDate}`);
+});
+```
+
+**Formatting a date range**
+
+For formatting a time range use the ReactIntl FormattedDateTimeRange component. Note that for dates in headlines or in sections, there is a dedicated format rule listed below.
+
+```jsx
+() => {
+const yesterday = new Date();
+yesterday.setDate(new Date().getDate() - 1);
+
+return <FormattedDateTimeRange from={yesterday} to={new Date()} />;
+})
+```
+
+## Date and time format
+
+None of the mentioned locales use a 12-hour format by default according to common usage. Here's a breakdown:
+
+- All the listed locales (including en-GB) typically use the 24-hour format for displaying time.
+- While some countries might use a 12-hour format in informal contexts, the 24-hour format is generally preferred for official communication and technical applications.
+
+The default date and time format looks like this: 27/05/2024, 11:17
+
+```jsx
+<FormattedDate value={new Date()} year='numeric' month='2-digit' day='2-digit' hour='2-digit' minute='2-digit' />
+```
+
+```javascript
+const formatDateTime = (date, locale) => {
+const options = {
+year: 'numeric',
+month: '2-digit',
+day: '2-digit',
+hour: '2-digit',
+minute: '2-digit'
+};
+
+const dateTimeFormatter = new Intl.DateTimeFormat(locale, options);
+return dateTimeFormatter.format(date);
+}
+
+const locales = [
+'bg-BG', 'cs-CZ', 'da-DK', 'el-GR', 'es-ES', 'et-EE', 'fi-FI', 'fr-FR',
+'hr-HR', 'hu-HU', 'it-IT', 'lt-LT', 'lv-LV', 'nb-NO', 'nl-NL', 'pl-PL',
+'pt-PT', 'ro-RO', 'sk-SK', 'sl-SI', 'sv-SE', 'de-DE', 'pt-BR', 'en-GB'
+];
+
+const today = new Date();
+
+locales.forEach(locale => {
+const formattedDateTime = formatDateTime(today, locale);
+console.log(`Locale: ${locale}, Formatted date time: ${formattedDateTime}`);
+});
+```
+
+## Formatting dates for headlines and sections
+
+When formatting a date or a date range for a headline or a section, use the following format including the weekday if it's not today. If the date is today, add the word "today" instead of the weekday.
+
+- Today, 24 May 2024
+- Thursday, 23 May 2024
+- 12 Feb - 16 Feb 2024
+
+```jsx
+() => {
+const yesterday = new Date();
+yesterday.setDate(new Date().getDate() - 1);
+
+return (
+<>
+{'Today, '}
+<FormattedDate value={new Date()} year='numeric' month='short' day='numeric' />
+<br />
+<FormattedDate value={yesterday} year='numeric' month='short' day='numeric' weekday='long' />
+</>
+);
+})
+```
+
+```javascript
+function formatDateWithWeekday(date) {
+const today = new Date();
+const isToday =
+today.getDate() === date.getDate() &&
+today.getMonth() === date.getMonth() &&
+today.getFullYear() === date.getFullYear();
+
+const options = {
+day: 'numeric',
+month: 'short',
+year: 'numeric',
+weekday: isToday ? undefined : 'long',
+};
+
+const dateTimeFormatter = new Intl.DateTimeFormat('en-GB', options);
+return isToday ? `Today, ${dateTimeFormatter.format(date)}` : dateTimeFormatter.format(date);
+}
+
+// Example for today
+const today = new Date();
+const formattedDate = formatDateWithWeekday(today);
+console.log(formattedDate);
+
+// Example for yesterday
+const yesterday = new Date();
+yesterday.setDate(today.getDate() - 1); // Subtract 1 day from today
+const formattedDateYesterday = formatDateWithWeekday(yesterday);
+console.log(formattedDateYesterday);
+```
+
+**Formatting a date range for headlines**
+
+When the date rage has the same year for both dates, omit the year for the first date so it looks like this: 27 May - 28 May 2024
+
+```jsx
+() => {
+const yesterday = new Date();
+yesterday.setDate(new Date().getDate() - 1);
+
+return (
+<>
+<FormattedDate value={yesterday} month='short' day='numeric' />
+{' - '}
+<FormattedDate value={new Date()} year='numeric' month='short' day='numeric' />
+</>
+);
+})
+```
+
+```javascript
+function formatDateRange(startDate, endDate) {
+if (!(startDate instanceof Date) || !(endDate instanceof Date)) {
+throw new Error("Invalid input. Please provide valid Date objects.");
+}
+
+const startDateFormatter = new Intl.DateTimeFormat('en-GB', {
+day: 'numeric',
+month: 'short'
+});
+
+const endDateFormatter = new Intl.DateTimeFormat('en-GB', {
+day: 'numeric',
+month: 'short',
+year: 'numeric'
+});
+
+const formattedStartDate = startDateFormatter.format(startDate);
+const formattedEndDate = endDateFormatter.format(endDate);
+
+return `${formattedStartDate} - ${formattedEndDate}`;
+}
+
+// Example usage
+const startDate = new Date(2024, 1, 12); // Feb 12, 2024
+const endDate = new Date(2024, 1, 16); // Feb 16, 2024
+
+const formattedRange = formatDateRange(startDate, endDate);
+console.log("Formatted Date Range:", formattedRange);
+```
+
+## Format durations
+
+Use relative date and time formatting to help the understand quickly when an event happened or when a message has been sent:
+
+- 3 days
+- 2h 32min
+- 45min
+
+Best for: Short durations where hours and minutes are the most relevant unit.
+
+- 3d
+- 3m 20s
+- 10s
+
+Best for: When space is limited, and clarity is still maintained. Example: In a compact playlist view displaying track lengths.
+
+```jsx
+<FormattedNumber value={2} />h <FormattedNumber value={45} />min
+```
+
+## Relative date and time
+
+- "5 minutes ago"
+- "1 month ago"
+- "7 days ago"
+- "In 2 hours"
+- "Now" or "Just now" (for events within the last minute)
+
+- Displaying when a notification arrived or a message was sent
+- Counting down to an upcoming event
+- Indicating how recently an item was updated
+- Benefits
+- Clear and concise for recent events Easy for users to understand the time difference
+
+- Clear and concise for recent events
+- Easy for users to understand the time difference
+
+Using a relative time is simple by using the ReactIntl FormattedRelativeTime component.
+
+Example: now
+
+```jsx
+<FormattedRelativeTime value={0} numeric='auto' updateIntervalInSeconds={1} />
+```
+
+- "Yesterday"
+- "Yesterday, 10:39"
+- "Today, 12:17"
+- "Tomorrow"
+- "Last week"
+- "Next Friday"
+- "In 3 days"
+
+- Displaying upcoming or past calendar events
+- Highlighting recent activity within a timeframe (e.g., "Top posts from the past week")
+- Providing deadlines or due dates in a user-friendly way
+- Benefits
+- Intuitive understanding for users familiar with common timeframes Reduces mental calculations for interpreting absolute dates
+
+- Intuitive understanding for users familiar with common timeframes
+- Reduces mental calculations for interpreting absolute dates
+
+The choice between relative and absolute formats depends on the context and desired level of precision:
+
+- Use relative formats: When the time difference or date proximity is more important than the exact timestamp. Example: "Your flight departs in 2 hours" is more relevant than "Your flight departs at 14:30".
+- Use absolute formats: When precise timestamps are crucial, or for long time spans where relative terms become ambiguous.
+
+Example for an upcoming event using ReactIntl: In 3 Days
+
+```jsx
+<FormattedRelativeTime value={0} numeric='auto' updateIntervalInSeconds={1} />
+```
+
+- Locale and cultural context: Relative terms like "yesterday" or "next week" might vary across languages and cultures. Consider user locale when implementing these formats.
+- Level of detail: You might need to adjust the granularity of relative formats. For example, "3 weeks ago" might be more appropriate than "21 days ago" depending on the context.
+
+## Time format including timezones
+
+**Understanding time zones can be challenging**
+
+While time zones are essential for global coordination, navigating them can be complex. Most users naturally think and schedule their activities in their local time zone. Concepts like Coordinated Universal Time (UTC) and daylight saving time (DST) can add layers of complexity.
+
+This table lists the main timezones used across Europe, including their standard times and any daylight saving times. Note that some regions do not observe daylight saving time.
+
+Studies show that users think in their local time - users often don’t think about UTC at all. Nor do they understand time zones, or the difference between UTC and GMT, or when and where daylight saving times are. But GMT is a more familiar time standard than UTC (even though UTC is the correct time standard). Since the UTC and GMT have the same offset and is widely more common in user interfaces, it is recommended to show GTM to the user instead of UTC.
+
+For optimal clarity and consistency, it's best to display time zone offsets like GMT+1:00 without a blank space before the "+" symbol.
+
+**Prioritize the user's local time**
+
+To simplify the user's experience, we prioritize displaying times in your local time zone. This eliminates the need for manual conversions or deciphering time zone differences.
+
+**Time zone transparency**
+
+While we present times in the user's local time zone by default, we understand the importance of transparency. If needed, you can display information regarding the corresponding GMT time.
+
+- Primary display: Show times in the user's local timezone for ease of use
+- Secondary display: Include the GMT offset in smaller text or tooltips to provide additional context
+
+**Total duration matters**
+
+For situations with multiple locations and time zones, providing a clear "total travel time" or "duration" alongside the individual departure and arrival times is incredibly helpful. This provides a comprehensive picture of the overall journey, just like the best travel itineraries do.
+
+**Event-Based timezones**
+
+For events, show both the local time and the event's original timezone. For example, "Meeting scheduled for 15:00 (CEST) / 16:00 (EEST)
+
+**Localizing time displays for various European countries**
+
+When localizing time displays for German-speaking users, remember to append the term "Uhr" (with a blank separator) after the hour when displaying times in a 24-hour format to ensure accurate and culturally appropriate representation.
+
+This table provides a comprehensive overview of how to handle time display formats across various European countries, ensuring localized and accurate time representations.
+
+- Constitution Day 23/05/2024, 3 days ago
+- Assumption Day 15/08/2024, in 64 days
+
+## Number formats
+
+## Number formats overview
+
+This is a list of all supported langues and their respective country, decimal separator, thousand separator, and an example of a formatted number.
+
+**Best practices for number formatting**
+
+- Locale awareness Always format numbers based on the user’s locale settings to ensure familiarity and reduce errors
+- Consistent use of delimiters Ensure the consistent use of decimal and thousand separators as per the locale’s conventions
+- Handling edge cases Be aware of edge cases like negative numbers, very large numbers, and numbers with many decimal places
+- Use libraries Utilize libraries like ReactIntl to handle number formatting, which provides built-in support for multiple locales and ensures correctness
+
+```jsx
+const NumberFormattingExample = () => {
+const number = 1234567.89;
+
+return (
+<IntlProvider locale="de-DE">
+<FormattedNumber value={number} />
+</IntlProvider>
+);
+};
+```
+
+In this example, the number 1234567.89 will be formatted as 1.234.567,89 in the German locale.
+
+## Omit unused or meaningless decimals
+
+When displaying numbers with units, it's often more readable and professional to omit unnecessary trailing zeros in decimal places. For instance, displaying "123 km" instead of "123.0 km" when the value is a whole number.
+
+Additionally, decimals should be omitted in cases where they do not add meaningful information, such as in a fuel level "74,87 %".
+
+```jsx
+<FormattedNumber
+value={123.0}
+minimumFractionDigits={0}
+maximumFractionDigits={2}
+style='unit'
+unit='kilometer'
+/>
+```
+
+> 123 km 1,234 km Fuel level: 75%
+
+> 123.0 km 1234.0 km Fuel level: 74,87 %
+
+## Formatting numbers with units
+
+ReactIntl also supports formatting units like currency, percentages, and other measurements. Here are some examples on how to format numbers with units.
+
+* Note: kilowatt-hour and megawatt-hour are not yet supported byIntl.NumberFormat(). Please append the unit manually. For more details, see here
+
+```jsx
+const NumberExample = () => {
+const value = 1234.56;
+return (
+<table className='table table-condensed'>
+<tbody>
+<tr>
+<td>Kilograms</td>
+<td>
+<FormattedNumber value={value} style='unit' unit='kilogram' />
+</td>
+</tr>
+<tr>
+<td>Kilometer</td>
+<td>
+<FormattedNumber value={value} style='unit' unit='kilometer' />
+</td>
+</tr>
+<tr>
+<td>Kilometer (long)</td>
+<td>
+<FormattedNumber value={value} style='unit' unit='kilometer' unitDisplay='long' />
+</td>
+</tr>
+<tr>
+<td>Meters</td>
+<td>
+<FormattedNumber value={value} style='unit' unit='meter' />
+</td>
+</tr>
+<tr>
+<td>Seconds (long)</td>
+<td>
+<FormattedNumber value={45} style='unit' unit='second' unitDisplay='long' />
+</td>
+</tr>
+<tr>
+<td>Minutes (long)</td>
+<td>
+<FormattedNumber value={12} style='unit' unit='minute' unitDisplay='long' />
+</td>
+</tr>
+<tr>
+<td>Centimeters</td>
+<td>
+<FormattedNumber value={34} style='unit' unit='centimeter' />
+</td>
+</tr>
+<tr>
+<td>Percent</td>
+<td>
+<FormattedNumber value={0.1234} style='percent' />
+</td>
+</tr>
+<tr>
+<td>Euro</td>
+<td>
+<FormattedNumber value={value} style='currency' currency='EUR' />
+</td>
+</tr>
+<tr>
+<td>Kilobyte</td>
+<td>
+<FormattedNumber value={1000} style='unit' unit='kilobyte' unitDisplay='narrow' />
+</td>
+</tr>
+<tr>
+<td>Celsius</td>
+<td>
+<FormattedNumber value={27} style='unit' unit='celsius' unitDisplay='narrow' />
+</td>
+</tr>
+<tr>
+<td>Duration</td>
+<td>
+<FormattedNumber value={2} />h <FormattedNumber value={45} />
+min
+</td>
+</tr>
+</tbody>
+</table>
+)
+};
+```
+
+In Germany, the correct unit format for kilogram is "kg" with a lowercase "k" and "g". It follows the international standard for unit symbols defined by the International System of Units (SI).
+
+Here's an example of the correct usage:
+
+- Correct: 1.234,56 kg
+- Incorrect: 1.234,56 Kg
+
+The unit symbol should always be in lowercase and a space should be used between the number and the unit symbol
+
+> Note: When formatting durations in a short format, ReactIntl does not follow the more common style defined in the section "Format durations" especially for locales like de-DE. In this case we need to combine the FormattedNumber with a custom unit.
+
+```jsx
+<FormattedNumber value={2} />h <FormattedNumber value={45} />min
+```
+
+```tsx
+type FormattedDuration = {
+hours?: number,
+minutes?: number,
+seconds?: number,
+};
+
+const FormattedDuration = ({ hours, minutes, seconds }) => {
+const hasHours = hours > 0;
+const hasMinutes = minutes > 0;
+const hasSeconds = seconds > 0;
+
+return (
+<div>
+{hasHours && (
+<>
+<FormattedNumber value={hours} />h
+{hasMinutes && ' '}
+</>
+)}
+{hasMinutes && (
+<>
+<FormattedNumber value={minutes} />min
+{hasSeconds && ' '}
+</>
+)}
+{hasSeconds && (
+<>
+<FormattedNumber value={seconds} />s
+</>
+)}
+</div>
+);
+};
+
+// Example Usage
+const App = () => {
+const duration1 = { hours: 8, minutes: 45 };
+const duration2 = { hours: 0, minutes: 56 };
+const duration3 = { hours: 1, minutes: 23 };
+
+return (
+<div>
+<FormattedDuration {...duration1} />
+<FormattedDuration {...duration2} />
+<FormattedDuration {...duration3} />
+</div>
+);
+};
+```