@havelaer/msgs 0.0.2 → 0.0.5

package/dist/functions.d.ts

@@ -1,7 +1,118 @@
 import { MessageFunction } from "messageformat/functions";
 
 //#region src/functions/index.d.ts
-declare const currency: MessageFunction<any, any>, date: MessageFunction<any, any>, datetime: MessageFunction<any, any>, percent: MessageFunction<any, any>, time: MessageFunction<any, any>, unit: MessageFunction<any, any>;
-declare const integer: MessageFunction<any, any>, number: MessageFunction<any, any>, offset: MessageFunction<any, any>, string: MessageFunction<any, any>;
+
+/**
+ * Currency formatting function for MessageFormat.
+ * Formats numbers as currency values.
+ *
+ * @beta
+ *
+ * @example
+ * ```ts
+ * "Price: {$price :currency currency=USD}"
+ * ```
+ */
+declare const currency: MessageFunction<any, any>;
+/**
+ * Date formatting function for MessageFormat.
+ * Formats dates according to locale conventions.
+ *
+ * @beta
+ *
+ * @example
+ * ```ts
+ * "Today is {$date :date dateStyle=medium}"
+ * ```
+ */
+declare const date: MessageFunction<any, any>;
+/**
+ * Date and time formatting function for MessageFormat.
+ * Formats both date and time components.
+ *
+ * @beta
+ *
+ * @example
+ * ```ts
+ * "Event at {$datetime :datetime dateStyle=short timeStyle=short}"
+ * ```
+ */
+declare const datetime: MessageFunction<any, any>;
+/**
+ * Percentage formatting function for MessageFormat.
+ * Formats numbers as percentages.
+ *
+ * @beta
+ *
+ * @example
+ * ```ts
+ * "Progress: {$progress :percent}"
+ * ```
+ */
+declare const percent: MessageFunction<any, any>;
+/**
+ * Number formatting function for MessageFormat.
+ * Formats numbers with locale-specific formatting.
+ *
+ * @example
+ * ```ts
+ * "Count: {$count :number}"
+ * ```
+ */
+declare const number: MessageFunction<any, any>;
+/**
+ * Time formatting function for MessageFormat.
+ * Formats time values according to locale conventions.
+ *
+ * @beta
+ *
+ * @example
+ * ```ts
+ * "Time: {$time :time timeStyle=short}"
+ * ```
+ */
+declare const time: MessageFunction<any, any>;
+/**
+ * Unit formatting function for MessageFormat.
+ * Formats numbers with units (length, weight, etc.).
+ *
+ * @beta
+ *
+ * @example
+ * ```ts
+ * "Distance: {$distance :unit unit=mile}"
+ * ```
+ */
+declare const unit: MessageFunction<any, any>;
+/**
+ * Integer formatting function for MessageFormat.
+ * Formats numbers as integers.
+ *
+ * @example
+ * ```ts
+ * "Items: {$count :integer}"
+ * ```
+ */
+declare const integer: MessageFunction<any, any>;
+/**
+ * Offset formatting function for MessageFormat.
+ * Formats timezone offsets.
+ *
+ * @example
+ * ```ts
+ * "Offset: {$offset :offset}"
+ * ```
+ */
+declare const offset: MessageFunction<any, any>;
+/**
+ * String formatting function for MessageFormat.
+ * Formats values as strings with optional transformations.
+ *
+ * @example
+ * ```ts
+ * "Name: {$name :string}"
+ * ```
+ */
+declare const string: MessageFunction<any, any>;
 //#endregion
 export { currency, date, datetime, integer, number, offset, percent, string, time, unit };

package/dist/functions.js

@@ -1,8 +1,118 @@
 import { DefaultFunctions, DraftFunctions } from "messageformat/functions";
 
 //#region src/functions/index.ts
-const { currency, date, datetime, percent, time, unit } = DraftFunctions;
-const { integer, number, offset, string } = DefaultFunctions;
+/**
+* Currency formatting function for MessageFormat.
+* Formats numbers as currency values.
+*
+* @beta
+*
+* @example
+* ```ts
+* "Price: {$price :currency currency=USD}"
+* ```
+*/
+const currency = DraftFunctions.currency;
+/**
+* Date formatting function for MessageFormat.
+* Formats dates according to locale conventions.
+*
+* @beta
+*
+* @example
+* ```ts
+* "Today is {$date :date dateStyle=medium}"
+* ```
+*/
+const date = DraftFunctions.date;
+/**
+* Date and time formatting function for MessageFormat.
+* Formats both date and time components.
+*
+* @beta
+*
+* @example
+* ```ts
+* "Event at {$datetime :datetime dateStyle=short timeStyle=short}"
+* ```
+*/
+const datetime = DraftFunctions.datetime;
+/**
+* Percentage formatting function for MessageFormat.
+* Formats numbers as percentages.
+*
+* @beta
+*
+* @example
+* ```ts
+* "Progress: {$progress :percent}"
+* ```
+*/
+const percent = DraftFunctions.percent;
+/**
+* Number formatting function for MessageFormat.
+* Formats numbers with locale-specific formatting.
+*
+* @example
+* ```ts
+* "Count: {$count :number}"
+* ```
+*/
+const number = DefaultFunctions.number;
+/**
+* Time formatting function for MessageFormat.
+* Formats time values according to locale conventions.
+*
+* @beta
+*
+* @example
+* ```ts
+* "Time: {$time :time timeStyle=short}"
+* ```
+*/
+const time = DraftFunctions.time;
+/**
+* Unit formatting function for MessageFormat.
+* Formats numbers with units (length, weight, etc.).
+*
+* @beta
+*
+* @example
+* ```ts
+* "Distance: {$distance :unit unit=mile}"
+* ```
+*/
+const unit = DraftFunctions.unit;
+/**
+* Integer formatting function for MessageFormat.
+* Formats numbers as integers.
+*
+* @example
+* ```ts
+* "Items: {$count :integer}"
+* ```
+*/
+const integer = DefaultFunctions.integer;
+/**
+* Offset formatting function for MessageFormat.
+* Formats timezone offsets.
+*
+* @example
+* ```ts
+* "Offset: {$offset :offset}"
+* ```
+*/
+const offset = DefaultFunctions.offset;
+/**
+* String formatting function for MessageFormat.
+* Formats values as strings with optional transformations.
+*
+* @example
+* ```ts
+* "Name: {$name :string}"
+* ```
+*/
+const string = DefaultFunctions.string;
 
 //#endregion
 export { currency, date, datetime, integer, number, offset, percent, string, time, unit };

package/dist/index-DqWXabHs.d.ts

@@ -0,0 +1,84 @@
+import { MessageFormatOptions, MessagePart, Model } from "messageformat";
+
+//#region src/index.d.ts
+
+/**
+ * Represents a nested structure of messages for different locales.
+ * Can be either a nested object with string keys or a flat object with locale keys.
+ *
+ * @template TLocales - The supported locale strings
+ *
+ * @example
+ * ```ts
+ * const messages: Messages<"en-US" | "nl-NL"> = {
+ *   greeting: {
+ *     "en-US": "Hello {$name}",
+ *     "nl-NL": "Hallo {$name}"
+ *   }
+ * };
+ * ```
+ */
+type Messages<TLocales extends string> = {
+  [key: string]: Messages<TLocales>;
+} | { [P in TLocales]: string };
+/**
+ * Configuration object returned by defineConfig containing all message processing methods.
+ *
+ * @template TLocales - The supported locale strings
+ *
+ * @example
+ * ```ts
+ * const config = defineConfig({
+ *   defaultLocale: "en-US",
+ *   locales: { "en-US": {}, "nl-NL": {} }
+ * });
+ *
+ * // Parse messages
+ * const parsed = config.parse(messages);
+ *
+ * // Format a message
+ * const formatted = config.format("en-US", parsed.greeting, { name: "John" });
+ * ```
+ */
+type MsgsConfig<TLocales extends string> = {
+  /** Parse message strings into MessageFormat objects */
+  parse: <T extends string = TLocales, const U extends Messages<T> = Messages<T>>(messages: U) => U;
+  /** Format a message to a string */
+  format: (locale: TLocales, msgs: Record<TLocales, Model.Message | string>, args?: Record<string, unknown>) => string;
+  /** Format a message to an array of MessagePart objects */
+  formatToParts: (locale: TLocales, msgs: Record<TLocales, Model.Message | string>, args?: Record<string, unknown>) => MessagePart<any>[];
+  /** Resolve the best matching locale from user preferences */
+  resolveLocale: (userLocales: string[] | readonly string[]) => TLocales;
+};
+/**
+ * Creates a message configuration object for internationalization.
+ *
+ * @template TLocales - The supported locale strings
+ * @template TDefaultLocale - The default locale (must be one of TLocales)
+ *
+ * @param config - Configuration object
+ * @param config.defaultLocale - The default locale to use as fallback
+ * @param config.locales - Locale-specific MessageFormat options
+ * @param config.options - Global MessageFormat options applied to all locales
+ *
+ * @returns A MsgsConfig object with parsing, formatting, and locale resolution methods
+ *
+ * @example
+ * ```ts
+ * const msgsConfig = defineConfig({
+ *   defaultLocale: "en-US",
+ *   locales: {
+ *     "en-US": { currency: "USD" },
+ *     "nl-NL": { currency: "EUR" }
+ *   },
+ *   options: { date: { dateStyle: "medium" } }
+ * });
+ * ```
+ */
+declare function defineConfig<TLocales extends string, TDefaultLocale extends TLocales>(config: {
+  defaultLocale: TDefaultLocale;
+  locales: Record<TLocales, MessageFormatOptions<any, any>>;
+  options?: MessageFormatOptions<any, any>;
+}): MsgsConfig<TLocales>;
+//#endregion
+export { Messages, MsgsConfig, defineConfig };

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { Config, Messages, MsgsConfig, defineConfig } from "./index-CrRmYrrh.js";
-export { Config, Messages, MsgsConfig, defineConfig };
+import { Messages, MsgsConfig, defineConfig } from "./index-DqWXabHs.js";
+export { Messages, MsgsConfig, defineConfig };

package/dist/index.js

@@ -1,6 +1,27 @@
 import { MessageFormat, parseMessage } from "messageformat";
 
 //#region src/resolveLocale.ts
+/**
+* Resolves the best matching locale from user preferences against supported locales.
+* Uses Intl locale matching with fallback chains for better compatibility.
+*
+* @param userLocales - User's preferred locales (e.g. navigator.languages)
+* @param supportedLocales - The locales your app supports (e.g. ["en", "nl-NL", "fr-FR"])
+* @param localeMatcher - Intl matching strategy (used only for runtime support check)
+* @returns The best matching locale string
+*
+* @throws {Error} When userLocales is not a non-empty array
+* @throws {Error} When supportedLocales is not a non-empty array
+*
+* @example
+* ```ts
+* const locale = resolveLocale(
+*   navigator.languages,
+*   ["en-US", "nl-NL", "fr-FR"],
+*   "best fit"
+* );
+* ```
+*/
 function resolveLocale(userLocales, supportedLocales, localeMatcher = "best fit") {
 	if (!Array.isArray(userLocales) || userLocales.length === 0) throw new Error("userLocales must be a non-empty array");
 	if (!Array.isArray(supportedLocales) || supportedLocales.length === 0) throw new Error("supportedLocales must be a non-empty array");
@@ -38,6 +59,31 @@ function walkAndParse(node, target) {
 		} else if (typeof value === "string") target[key] = parseMessage(value);
 	}
 }
+/**
+* Creates a message configuration object for internationalization.
+*
+* @template TLocales - The supported locale strings
+* @template TDefaultLocale - The default locale (must be one of TLocales)
+*
+* @param config - Configuration object
+* @param config.defaultLocale - The default locale to use as fallback
+* @param config.locales - Locale-specific MessageFormat options
+* @param config.options - Global MessageFormat options applied to all locales
+*
+* @returns A MsgsConfig object with parsing, formatting, and locale resolution methods
+*
+* @example
+* ```ts
+* const msgsConfig = defineConfig({
+*   defaultLocale: "en-US",
+*   locales: {
+*     "en-US": { currency: "USD" },
+*     "nl-NL": { currency: "EUR" }
+*   },
+*   options: { date: { dateStyle: "medium" } }
+* });
+* ```
+*/
 function defineConfig(config) {
 	function parse(messages) {
 		const parsed = {};

package/dist/react.d.ts

@@ -1,29 +1,119 @@
-import { MsgsConfig } from "./index-CrRmYrrh.js";
+import { MsgsConfig } from "./index-DqWXabHs.js";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 import { ReactNode } from "react";
 
 //#region src/react/index.d.ts
+/**
+ * Valid argument values for message formatting.
+ */
 type ArgValue = string | number | boolean | null | undefined;
+/**
+ * Translator object returned by useTranslator hook.
+ * Provides methods for formatting messages as strings or JSX.
+ */
 type Translator = {
+  /** Format a message to a string */
   (msg: any, args?: Record<string, ArgValue>): string;
+  /** Format a message to JSX elements, used for messages with markup */
   jsx(msg: any, args?: Record<string, ArgValue>): ReactNode;
+  /** Current locale string */
   locale: string;
 };
+/**
+ * React hook for accessing the message translator.
+ * Must be used within a MsgsProvider context.
+ *
+ * @returns A translator object with format and jsx methods
+ *
+ * @throws {Error} When used outside of MsgsProvider context
+ * @throws {Error} When locale is not set by either MsgsProvider or LocaleProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const t = useTranslator();
+ *
+ *   return (
+ *     <div>
+ *       <h1>{t(msgs.greeting, { name: "John" })}</h1>
+ *       <p>{t.jsx(msgs.description, { count: 5 })}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 declare function useTranslator(): Translator;
+/**
+ * Props for the MsgsProvider component.
+ *
+ * @template TLocales - The supported locale strings
+ */
 interface MsgsProviderProps<TLocales extends string> {
+  /** The message configuration object */
   config: MsgsConfig<TLocales>;
+  /** The current locale */
   locale: TLocales;
+  /** Child components */
   children: ReactNode;
 }
+/**
+ * React provider component that makes message configuration available to child components.
+ *
+ * @template TLocales - The supported locale strings
+ *
+ * @param props - Component props
+ * @param props.config - The message configuration object
+ * @param props.locale - The current locale
+ * @param props.children - Child components
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <MsgsProvider config={msgsConfig} locale="en-US">
+ *       <MyComponent />
+ *     </MsgsProvider>
+ *   );
+ * }
+ * ```
+ */
 declare function MsgsProvider<TLocales extends string>({
   config,
   locale,
   children
 }: MsgsProviderProps<TLocales>): react_jsx_runtime0.JSX.Element;
+/**
+ * Props for the LocaleProvider component.
+ *
+ * @template TLocales - The supported locale strings
+ */
 interface LocaleProviderProps<TLocales extends string> {
+  /** The locale to set */
   locale: TLocales;
+  /** Child components */
   children: ReactNode;
 }
+/**
+ * React provider component that sets the locale for child components.
+ * Can be used to override the locale set by MsgsProvider.
+ *
+ * @template TLocales - The supported locale strings
+ *
+ * @param props - Component props
+ * @param props.locale - The locale to set
+ * @param props.children - Child components
+ *
+ * @example
+ * ```tsx
+ * function LocalizedSection() {
+ *   return (
+ *     <LocaleProvider locale="nl-NL">
+ *       <MyComponent />
+ *     </LocaleProvider>
+ *   );
+ * }
+ * ```
+ */
 declare function LocaleProvider<TLocales extends string>({
   locale,
   children

package/dist/react.js

@@ -1324,6 +1324,20 @@ var import_jsx_runtime = /* @__PURE__ */ __toESM(require_jsx_runtime());
 function createKey(part, i) {
 	return `${part.type}-${part.value}-${part.locale}-${part.kind}-${part.name}-${part.source}-${i}`;
 }
+/**
+* Converts an array of MessagePart objects to React JSX elements.
+* Handles markup parts by converting them to React components and text parts to fragments.
+*
+* @param parts - Array of MessagePart objects to convert
+* @param args - Optional arguments that can be used to override markup components
+* @returns Array of React nodes
+*
+* @example
+* ```tsx
+* const parts = config.formatToParts(locale, message, args);
+* const jsxElements = partsToJSX(parts, { strong: 'b' });
+* ```
+*/
 function partsToJSX(parts, args, start = 0, stop) {
 	const result = [];
 	let i = start;
@@ -1370,6 +1384,29 @@ function partsToJSX(parts, args, start = 0, stop) {
 //#region src/react/index.tsx
 const localeContext = (0, import_react.createContext)(null);
 const configContext = (0, import_react.createContext)(null);
+/**
+* React hook for accessing the message translator.
+* Must be used within a MsgsProvider context.
+*
+* @returns A translator object with format and jsx methods
+*
+* @throws {Error} When used outside of MsgsProvider context
+* @throws {Error} When locale is not set by either MsgsProvider or LocaleProvider
+*
+* @example
+* ```tsx
+* function MyComponent() {
+*   const t = useTranslator();
+*
+*   return (
+*     <div>
+*       <h1>{t(msgs.greeting, { name: "John" })}</h1>
+*       <p>{t.jsx(msgs.description, { count: 5 })}</p>
+*     </div>
+*   );
+* }
+* ```
+*/
 function useTranslator() {
 	const config = (0, import_react.useContext)(configContext);
 	const locale = (0, import_react.useContext)(localeContext);
@@ -1385,6 +1422,27 @@ function useTranslator() {
 	translator.locale = locale;
 	return translator;
 }
+/**
+* React provider component that makes message configuration available to child components.
+*
+* @template TLocales - The supported locale strings
+*
+* @param props - Component props
+* @param props.config - The message configuration object
+* @param props.locale - The current locale
+* @param props.children - Child components
+*
+* @example
+* ```tsx
+* function App() {
+*   return (
+*     <MsgsProvider config={msgsConfig} locale="en-US">
+*       <MyComponent />
+*     </MsgsProvider>
+*   );
+* }
+* ```
+*/
 function MsgsProvider({ config, locale, children }) {
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(configContext.Provider, {
 		value: config,
@@ -1394,6 +1452,27 @@ function MsgsProvider({ config, locale, children }) {
 		})
 	});
 }
+/**
+* React provider component that sets the locale for child components.
+* Can be used to override the locale set by MsgsProvider.
+*
+* @template TLocales - The supported locale strings
+*
+* @param props - Component props
+* @param props.locale - The locale to set
+* @param props.children - Child components
+*
+* @example
+* ```tsx
+* function LocalizedSection() {
+*   return (
+*     <LocaleProvider locale="nl-NL">
+*       <MyComponent />
+*     </LocaleProvider>
+*   );
+* }
+* ```
+*/
 function LocaleProvider({ locale, children }) {
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(localeContext.Provider, {
 		value: locale,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@havelaer/msgs",
-  "version": "0.0.2",
+  "version": "0.0.5",
   "type": "module",
   "exports": {
     ".": {
@@ -8,20 +8,29 @@
       "import": "./dist/index.js"
     },
     "./react": {
-      "types": "./dist/react/index.d.ts",
-      "import": "./dist/react/index.js"
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
     },
     "./functions": {
-      "types": "./dist/functions/index.d.ts",
-      "import": "./dist/functions/index.js"
+      "types": "./dist/functions.d.ts",
+      "import": "./dist/functions.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
+  "keywords": [
+    "messageformat",
+    "MessageFormat2",
+    "MF2",
+    "l10n",
+    "localization",
+    "react",
+    "typescript"
+  ],
   "scripts": {
     "check": "biome check .",
-    "prepublishOnly": "npm run check -- --fix && npm run build && npm version patch -m 'chore: publishing version %s'",
+    "prepublishOnly": "npm run check && npm run build && npm version patch -m 'chore: publishing version %s'",
     "build": "tsdown"
   },
   "files": [

package/dist/index-CrRmYrrh.d.ts

@@ -1,22 +0,0 @@
-import { MessageFormatOptions, MessagePart, Model } from "messageformat";
-
-//#region src/index.d.ts
-type Messages<TLocales extends string> = {
-  [key: string]: Messages<TLocales>;
-} | { [P in TLocales]: string };
-type Config = {
-  messageFormatOptions?: MessageFormatOptions<any, any>;
-};
-type MsgsConfig<TLocales extends string> = {
-  parse: <T extends string = TLocales, const U extends Messages<T> = Messages<T>>(messages: U) => U;
-  format: (locale: TLocales, msgs: Record<TLocales, Model.Message | string>, args?: Record<string, unknown>) => string;
-  formatToParts: (locale: TLocales, msgs: Record<TLocales, Model.Message | string>, args?: Record<string, unknown>) => MessagePart<any>[];
-  resolveLocale: (userLocales: string[] | readonly string[]) => TLocales;
-};
-declare function defineConfig<TLocales extends string, TDefaultLocale extends TLocales>(config: {
-  defaultLocale: TDefaultLocale;
-  locales: Record<TLocales, MessageFormatOptions<any, any>>;
-  options?: MessageFormatOptions<any, any>;
-}): MsgsConfig<TLocales>;
-//#endregion
-export { Config, Messages, MsgsConfig, defineConfig };