import { DateTimePropertyType } from '../limetype';
/**
 * The possible types a date can be formatted as.
 *
 * @public
 * @group Localization
 */
export type DateTimeType = 'week' | 'relative' | DateTimePropertyType;
/**
 * The hour cycle to use.
 * - `h11` is 12 hour clock where midnight and midday are 0:00.
 * - `h12` is 12 hour clock where midnight and midday are 12:00.
 * - `h23` is 24 hour clock where midnight is 0:00.
 * - `h24` is 24 hour clock where midnight is 24:00.
 *
 * @public
 * @group Localization
 */
export type HourCycle = 'h11' | 'h12' | 'h23' | 'h24';
/**
 * Options for `DateTimeFormatter.format()`.
 *
 * @public
 * @group Localization
 */
export interface DateTimeFormatterOptions {
    /**
     * The type to format the date as.
     */
    type: DateTimeType;
    /**
     * The locale to use for formatting. A service implementing the
     * `DateTimeFormatter` is free to choose the default value for this.
     * For example, it may use the value from the user's browser or OS,
     * or it may use a value from user configured preferences.
     *
     * **Note**<br>
     * For a consistent user experience, it is recommended to _not_ set this
     * property, and instead allow the service to use its own default value.
     */
    locale?: string;
    /**
     * The hour cycle to use.
     */
    hourCycle?: HourCycle;
}
/**
 * Service for formatting and parsing date and time values according to user locale
 *
 * The DateTimeFormatter provides locale-aware formatting for dates and times,
 * ensuring that dates are displayed in a format familiar to the user. It handles
 * various date types including full timestamps, date-only values, times, and
 * relative dates (like "2 hours ago").
 *
 * The service also handles the complexities of parsing date strings and converting
 * between UTC and local time, which is particularly important for date-only values
 * that need timezone compensation.
 *
 * @example Basic date formatting
 * ```ts
 * import { PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const formatter = platform.get(PlatformServiceName.DateTimeFormatter);
 *
 * const timestamp = '2024-03-15T14:30:00.000Z';
 *
 * // `time` covers a full date and time. A clock time on its own is `timeofday`.
 * const formatted = formatter.format(timestamp, 'time');
 * ```
 *
 * @public
 * @group Localization
 */
export interface DateTimeFormatter {
    /**
     * Format a date or timestamp as a localized string
     *
     * Converts a date value to a human-readable string according to the user's
     * locale and the specified format type. The formatting automatically respects
     * the user's locale preferences for date ordering, separators, and time format.
     *
     * @param date - The date to format, either as a Date object or an ISO string
     * @param options - Either a string specifying the format type (e.g., 'date', 'time', 'relative'),
     *                  or a {@link DateTimeFormatterOptions} object for more control
     * @returns A localized string representation of the date
     *
     * @example Simple string format types
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const formatter = platform.get(PlatformServiceName.DateTimeFormatter);
     * const date = new Date();
     *
     * // The output depends on the user's locale and hour cycle, so the same date
     * // looks different for different users.
     * const dateAndTime = formatter.format(date, 'time');
     * const clockTime = formatter.format(date, 'timeofday');
     * const dateOnly = formatter.format(date, 'date');
     * const month = formatter.format(date, 'month');
     * const quarter = formatter.format(date, 'quarter');
     * const year = formatter.format(date, 'year');
     * const week = formatter.format(date, 'week');
     * const relative = formatter.format(date, 'relative');
     * ```
     *
     * @example Using format options
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const formatter = platform.get(PlatformServiceName.DateTimeFormatter);
     *
     * const formatted = formatter.format(new Date(), {
     *     type: 'time',
     *     hourCycle: 'h23',
     * });
     * ```
     *
     * @example Formatting a date loaded from the server
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const formatter = platform.get(PlatformServiceName.DateTimeFormatter);
     * const repository = platform.get(PlatformServiceName.LimeObjectRepository);
     *
     * if (context.limetype && context.id) {
     *     const object = await repository.loadObject(context.limetype, context.id, {
     *         properties: ['createdtime'],
     *     });
     *
     *     if (object) {
     *         const createdTime = object.getValue('createdtime');
     *         const formatted = formatter.format(createdTime, 'time');
     *     }
     * }
     * ```
     *
     * @note If a `string` is supplied to the `date` parameter, it will be converted
     *       to a `Date` object before formatting. See {@link DateTimeFormatter.parse}
     *       for details on how strings are parsed.
     */
    format(date: Date | string, options: DateTimeType | DateTimeFormatterOptions): string;
    /**
     * Parse a date string and convert it to a Date object with proper timezone handling
     *
     * This method handles the complexity of converting date strings to Date objects,
     * with special handling for date-only values that need timezone compensation.
     * This is important when working with dates stored in a database, which are
     * typically in UTC but should be displayed in the user's local timezone.
     *
     * For date-only types ('date', 'year', 'quarter', 'month', 'week'), the method
     * compensates for timezone differences to ensure the date is displayed as stored.
     *
     * @param date - The date value to parse. Can be a Date object (returned unchanged)
     *               or a string in ISO format
     * @param type - The date type, which determines how timezone conversion is handled
     * @returns A Date object in local time
     *
     * @example Parsing a date-only value from the database
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const formatter = platform.get(PlatformServiceName.DateTimeFormatter);
     *
     * // The server stores a `date` as midnight UTC. Parsing it as `date` keeps the
     * // same calendar day in local time, so a user west of UTC does not see the day
     * // before.
     * const storedDate = '2024-03-15T00:00:00.000Z';
     * const localDate = formatter.parse(storedDate, 'date');
     * ```
     *
     * @example Parsing a timestamp
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const formatter = platform.get(PlatformServiceName.DateTimeFormatter);
     *
     * // A `time` value points at one moment, so it is not shifted. The `Date` shows
     * // that moment in the user's own time zone.
     * const storedTimestamp = '2024-03-15T14:30:00.000Z';
     * const localTime = formatter.parse(storedTimestamp, 'time');
     * ```
     *
     * @example Parsing a date string without timezone info
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const formatter = platform.get(PlatformServiceName.DateTimeFormatter);
     *
     * // Without a time zone offset the string is read as local time, not as UTC.
     * const localDateString = '2024-03-15 23:59:59';
     * const date = formatter.parse(localDateString, 'time');
     * ```
     */
    parse(date: Date | string, type: DateTimeType): Date;
}