saykit 0.6.1 → 0.8.0

package/README.md

@@ -31,7 +31,7 @@ const say = new Say({
 say.activate('en');
 
 say`Hello, ${name}!`;
-say.plural(count, { one: '1 item', other: '# items' });
+say.plural(count, { one: '1 item', other: `${count} items` });
 ```
 
 ## Documentation

package/dist/runtime.d.mts

@@ -11,13 +11,42 @@ type Awaitable<T> = T | PromiseLike<T>;
 type Named<T> = {
   [name: string]: T;
 };
-interface NumeralOptions extends Omit<Partial<Record<Intl.LDMLPluralRule, string>>, 'other'> {
-  other: string;
-  [digit: number]: string;
+/**
+ * Branches of a choice, keyed by CLDR category or by exact number.
+ *
+ * `Branch` is what a case may be written as. It is text everywhere the message
+ * is text, and widens in JSX, where a case that shows the number has to be a
+ * fragment — a string attribute has nowhere to put a value.
+ */
+interface NumeralOptions<Branch = string> extends Omit<Partial<Record<Intl.LDMLPluralRule, Branch>>, 'other'> {
+  other: Branch;
+  [digit: number]: Branch;
+  /**
+   * Subtracted from the value before `#` is formatted, so "You and 2 others"
+   * can select on a total of three. Reserved — it never names a branch.
+   */
+  offset?: number;
+}
+interface SelectOptions<Branch = string> {
+  other: Branch;
+  [match: string | number]: Branch;
 }
-interface SelectOptions {
-  other: string;
-  [match: string | number]: string;
+/**
+ * Formatting for a `{arg, number}` placeholder.
+ *
+ * `currency` is not offered: MF1 has nowhere to write the currency code, so
+ * `{price, number, currency}` formats as a literal `{$price}` rather than an
+ * amount. A literal pattern such as `#,##0.00` is accepted for the cases the
+ * named styles do not cover.
+ */
+interface NumberOptions {
+  style?: 'integer' | 'percent' | (string & {});
+}
+/**
+ * Formatting for a `{arg, date}` or `{arg, time}` placeholder.
+ */
+interface DateTimeOptions {
+  style?: 'short' | 'medium' | 'long' | 'full';
 }
 //#endregion
 //#region src/runtime.d.ts
@@ -166,11 +195,12 @@ declare class Say<Locale extends string = string, Loader extends Say.Loader<Loca
    * ```ts
    * say.plural(count, {
    *   one: 'You have 1 item',
-   *   other: 'You have # items',
+   *   other: `You have ${count} items`,
    * })
    * ```
    *
-   * The `#` symbol inside options is replaced with the numeric value.
+   * Interpolating the selector into a branch extracts as ICU's `#`, the number
+   * the message branched on. A `#` you write yourself is text.
    * @param _ Number to determine the plural form of
    * @param options Pluralisation rules keyed by CLDR categories or specific numbers
    * @returns The plural form of the number
@@ -179,15 +209,17 @@ declare class Say<Locale extends string = string, Loader extends Say.Loader<Loca
   plural(_: number | Named<number>, options: Disallow<NumeralOptions, 'id' | 'context'>): string;
   /**
    * Define an ordinal message (e.g. "1st", "2nd", "3rd").
-   * The `#` symbol inside options is replaced with the numeric value.
+   *
+   * Interpolating the selector into a branch extracts as ICU's `#`, the number
+   * the message branched on. A `#` you write yourself is text.
    *
    * @example
    * ```ts
    * say.ordinal(position, {
-   *   1: '#st',
-   *   2: '#nd',
-   *   3: '#rd',
-   *   other: '#th',
+   *   1: `${position}st`,
+   *   2: `${position}nd`,
+   *   3: `${position}rd`,
+   *   other: `${position}th`,
    * })
    * ```
    *
@@ -214,7 +246,57 @@ declare class Say<Locale extends string = string, Loader extends Say.Loader<Loca
    * @returns The select form of the value
    * @remark This is a macro and must be used with the relevant saykit plugin
    */
-  select(_: string | Named<string>, options: Disallow<SelectOptions, 'id' | 'context'>): string;
+  select(_: string | number | Named<string | number>, options: Disallow<SelectOptions, 'id' | 'context'>): string;
+  /**
+   * Format a number the way the active locale writes one, with its own grouping
+   * separators and decimal mark.
+   *
+   * Unlike `plural`, `ordinal`, and `select`, this is a fragment rather than a
+   * whole message, and is normally written inside one.
+   *
+   * @example
+   * ```ts
+   * say`You have ${say.number(items.length)} items`
+   * say`Battery at ${say.number(level, { style: 'percent' })}`
+   * say`Total: ${say.number({ cartTotal: getTotal() }, { style: '#,##0.00' })}`
+   * ```
+   *
+   * @param _ Number to format
+   * @param options Formatting style, either a named style or a literal number pattern
+   * @returns The formatted number
+   * @remark This is a macro and must be used with the relevant saykit plugin
+   */
+  number(_: number | Named<number>, options?: Disallow<NumberOptions, 'id' | 'context'>): string;
+  /**
+   * Format the date portion of a value the way the active locale writes one.
+   *
+   * @example
+   * ```ts
+   * say`Published ${say.date(post.publishedAt)}`
+   * say`Published ${say.date(post.publishedAt, { style: 'full' })}`
+   * ```
+   *
+   * @param _ Date to format
+   * @param options Formatting style
+   * @returns The formatted date
+   * @remark This is a macro and must be used with the relevant saykit plugin
+   */
+  date(_: Date | number | Named<Date | number>, options?: Disallow<DateTimeOptions, 'id' | 'context'>): string;
+  /**
+   * Format the time portion of a value the way the active locale writes one.
+   *
+   * @example
+   * ```ts
+   * say`Doors open at ${say.time(opensAt)}`
+   * say`Doors open at ${say.time(opensAt, { style: 'short' })}`
+   * ```
+   *
+   * @param _ Date to format
+   * @param options Formatting style
+   * @returns The formatted time
+   * @remark This is a macro and must be used with the relevant saykit plugin
+   */
+  time(_: Date | number | Named<Date | number>, options?: Disallow<DateTimeOptions, 'id' | 'context'>): string;
 }
 //#endregion
-export { Awaitable, Disallow, Named, NumeralOptions, ReadonlySay, Say, SelectOptions, Tuple };
+export { Awaitable, DateTimeOptions, Disallow, Named, NumberOptions, NumeralOptions, ReadonlySay, Say, SelectOptions, Tuple };

package/dist/runtime.mjs

@@ -203,11 +203,12 @@ var Say = class Say {
 	* ```ts
 	* say.plural(count, {
 	*   one: 'You have 1 item',
-	*   other: 'You have # items',
+	*   other: `You have ${count} items`,
 	* })
 	* ```
 	*
-	* The `#` symbol inside options is replaced with the numeric value.
+	* Interpolating the selector into a branch extracts as ICU's `#`, the number
+	* the message branched on. A `#` you write yourself is text.
 	* @param _ Number to determine the plural form of
 	* @param options Pluralisation rules keyed by CLDR categories or specific numbers
 	* @returns The plural form of the number
@@ -218,15 +219,17 @@ var Say = class Say {
 	}
 	/**
 	* Define an ordinal message (e.g. "1st", "2nd", "3rd").
-	* The `#` symbol inside options is replaced with the numeric value.
+	*
+	* Interpolating the selector into a branch extracts as ICU's `#`, the number
+	* the message branched on. A `#` you write yourself is text.
 	*
 	* @example
 	* ```ts
 	* say.ordinal(position, {
-	*   1: '#st',
-	*   2: '#nd',
-	*   3: '#rd',
-	*   other: '#th',
+	*   1: `${position}st`,
+	*   2: `${position}nd`,
+	*   3: `${position}rd`,
+	*   other: `${position}th`,
 	* })
 	* ```
 	*
@@ -258,6 +261,62 @@ var Say = class Say {
 	select(_, options) {
 		throw new Error("'Say#select' is a macro and must be used with the relevant saykit plugin");
 	}
+	/**
+	* Format a number the way the active locale writes one, with its own grouping
+	* separators and decimal mark.
+	*
+	* Unlike `plural`, `ordinal`, and `select`, this is a fragment rather than a
+	* whole message, and is normally written inside one.
+	*
+	* @example
+	* ```ts
+	* say`You have ${say.number(items.length)} items`
+	* say`Battery at ${say.number(level, { style: 'percent' })}`
+	* say`Total: ${say.number({ cartTotal: getTotal() }, { style: '#,##0.00' })}`
+	* ```
+	*
+	* @param _ Number to format
+	* @param options Formatting style, either a named style or a literal number pattern
+	* @returns The formatted number
+	* @remark This is a macro and must be used with the relevant saykit plugin
+	*/
+	number(_, options) {
+		throw new Error("'Say#number' is a macro and must be used with the relevant saykit plugin");
+	}
+	/**
+	* Format the date portion of a value the way the active locale writes one.
+	*
+	* @example
+	* ```ts
+	* say`Published ${say.date(post.publishedAt)}`
+	* say`Published ${say.date(post.publishedAt, { style: 'full' })}`
+	* ```
+	*
+	* @param _ Date to format
+	* @param options Formatting style
+	* @returns The formatted date
+	* @remark This is a macro and must be used with the relevant saykit plugin
+	*/
+	date(_, options) {
+		throw new Error("'Say#date' is a macro and must be used with the relevant saykit plugin");
+	}
+	/**
+	* Format the time portion of a value the way the active locale writes one.
+	*
+	* @example
+	* ```ts
+	* say`Doors open at ${say.time(opensAt)}`
+	* say`Doors open at ${say.time(opensAt, { style: 'short' })}`
+	* ```
+	*
+	* @param _ Date to format
+	* @param options Formatting style
+	* @returns The formatted time
+	* @remark This is a macro and must be used with the relevant saykit plugin
+	*/
+	time(_, options) {
+		throw new Error("'Say#time' is a macro and must be used with the relevant saykit plugin");
+	}
 };
 function _call(locale, messages, descriptor) {
 	const message = messages[descriptor.id];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saykit",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Type-safe i18n library with compile-time macro transforms",
   "keywords": [
     "i18n",