afformative 0.7.0-beta.4 → 0.7.0-beta.5

package/README.md

@@ -38,6 +38,8 @@ npm i afformative
 
 ## Quick Start
 
+Afformative is framework-agnostic, but this section will assume usage with React.
+
 A formatter is an object with `format`, `stringify`, and `compare` methods. Formatters must be created using the `createFormatter` function.
 
 `createFormatter` accepts a single object parameter. `format` is the only required property, but specifying `stringify` is recommended in most cases.
@@ -49,6 +51,7 @@ import { ReactNode } from "react"
 const dateFormatter = createFormatter<Date, ReactNode>({
   format: value => <time dateTime={value.toISOString()}>{value.toLocaleDateString()}</time>,
   stringify: value => value.toLocaleDateString(),
+  compare: value => value.valueOf(),
 })
 
 dateFormatter.format(new Date()) // <time dateTime="2026-05-30T09:17:26.263Z">30/05/2026</time>
@@ -75,11 +78,36 @@ const List = <TItem extends unknown>({ formatter, items }: ListProps<TItem>) =>
 )
 ```
 
-The `stringify` method is useful when you need a plain string representation of a value. For example, a combobox component can use it to match items against the user's typed input.
+The `stringify` method is useful when you need a plain string representation of a value. For example, a combobox component can use it to match items against the user's typed input. The default implementation of `stringify` is simply `String(format(value))`.
+
+## Accessing State
+
+Create formatters inside hooks to access React context.
+
+```tsx
+const useEnumFormatter = (enumType: string): Formatter<string, ReactNode> => {
+  const enumTranslationKeys = useSelector(selectEnumTranslationKeys(enumType))
+  const intl = useIntl()
+
+  return useMemo(
+    () =>
+      createFormatter<string, ReactNode>({
+        format: value => (
+          <FormattedMessage defaultMessage={value} id={enumTranslationKeys[value]} />
+        ),
+        stringify: value =>
+          intl.formatMessage({ defaultMessage: value, id: enumTranslationKeys[value] }),
+      }),
+    [intl, enumTranslationKeys],
+  )
+}
+```
+
+## Comparing Values
 
-## Compare
+Every formatter exposes a `compare` method which can be directly passed to `Array.prototype.sort`. The default implementation compares the return values of `stringify` via `localeCompare`.
 
-Every formatter exposes a `compare` method, which can be used to sort values. The default implementation compares the return values of `stringify` via `localeCompare`. In the following example, `Amount` objects are sorted first by currency, then by value.
+In the following example, `Amount` objects are sorted first by currency, then by value.
 
 ```tsx
 import { createFormatter } from "afformative"
@@ -109,7 +137,7 @@ amounts.sort(amountFormatter.compare)
 // [{ EUR, 1 }, { EUR, 5 }, { USD, 2 }, { USD, 3 }]
 ```
 
-## Context
+## Formatter Context
 
 You can pass context to all formatter methods. Let's use a dummy table component as an example.
 
@@ -140,7 +168,9 @@ const Table = ({ rows, formatter }: TableProps) => (
 )
 ```
 
-Context allows the users of this table component to write purpose-built formatters, making it possible to take other values in the same row into account. For example, the following formatter would change the color of the cell value based on the previous value in the same row.
+Context allows the users of this table component to write purpose-built formatters, making it possible to take other values in the same row into account.
+
+For example, the following formatter would change the color of the cell value based on the previous value in the same row.
 
 ```tsx
 import { createFormatter } from "afformative"
@@ -165,26 +195,31 @@ This formatter only makes sense in the context of our table component.
 
 Because `row` and `cellIndex` are passed as context, the formatter still receives only the cell value as its first parameter. This means generic formatters (e.g. a currency formatter) can be passed to the table component without any changes.
 
-## Accessing React Context
+## Formatter Meta
+
+As explained above, context can be used to pass information from the consumer to the formatter. The `meta` property can be used to pass information from the formatter to the consumer instead. The base `FormatterMeta` interface is extensible via declaration merging.
 
-Create formatters inside custom hooks to access React context values such as translations or application state.
+For example, formatters can explicily mark themselves as print-friendly. Consumers may then decide to use `stringify` instead of `format` based on this flag.
 
 ```tsx
-const useEnumFormatter = (enumType: string): Formatter<string, ReactNode> => {
-  const enumTranslationKeys = useSelector(selectEnumTranslationKeys(enumType))
-  const intl = useIntl()
+declare module "afformative" {
+  interface FormatterMeta<TInput, TOutput, TContext> {
+    isPrintFriendly?: boolean
+  }
+}
 
-  return useMemo(
-    () =>
-      createFormatter<string, ReactNode>({
-        format: value => (
-          <FormattedMessage defaultMessage={value} id={enumTranslationKeys[value]} />
-        ),
-        stringify: value =>
-          intl.formatMessage({ defaultMessage: value, id: enumTranslationKeys[value] }),
-      }),
-    [intl, enumTranslationKeys],
-  )
+const colorfulFormatter = createFormatter<string, ReactNode>({
+  format: value => <Colorful>{value}</Colorful>,
+  stringify: value => value,
+})
+
+interface PrinterProps {
+  content: string
+  formatter: Formatter<string, ReactNode>
+}
+
+const Printer = ({ content, formatter }: PrinterProps) => {
+  return formatter.meta?.isPrintFriendly ? formatter.format(content) : formatter.stringify(content)
 }
 ```
 

package/dist/index.cjs

@@ -1,14 +1,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/createFormatter.ts
 const createFormatter = (param) => {
-	const { format: formatParam, stringify: stringifyParam, compare: compareParam, meta } = param;
-	const format = (value, ctx) => formatParam(value, ctx);
-	const stringify = stringifyParam ? (value, ctx) => stringifyParam(value, ctx) : (value, ctx) => String(format(value, ctx));
+	const { compare: compareParam, format, meta, stringify: stringifyParam } = param;
+	const stringify = stringifyParam ?? ((value, ctx) => String(format(value, ctx)));
 	return {
-		compare: compareParam ? (a, b, ctx) => compareParam(a, b, ctx) : (a, b, ctx) => stringify(a, ctx).localeCompare(stringify(b, ctx)),
+		compare: compareParam ?? ((a, b, ctx) => stringify(a, ctx).localeCompare(stringify(b, ctx))),
 		format,
-		stringify,
-		meta
+		meta,
+		stringify
 	};
 };
 //#endregion

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../src/createFormatter.ts"],"sourcesContent":["export interface FormatterFormat<TInput, TOutput, TContext = unknown> {\n  (value: TInput, ctx?: TContext): TOutput\n}\n\nexport interface FormatterStringify<TInput, TContext = unknown> {\n  (value: TInput, ctx?: TContext): string\n}\n\nexport interface FormatterCompare<TInput, TContext = unknown> {\n  (a: TInput, b: TInput, ctx?: TContext): number\n}\n\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type, @typescript-eslint/no-unused-vars\nexport interface FormatterMeta<TInput, TOutput, TContext = unknown> {}\n\nexport interface Formatter<TInput, TOutput, TContext = unknown> {\n  compare: FormatterCompare<TInput, TContext>\n  format: FormatterFormat<TInput, TOutput, TContext>\n  stringify: FormatterStringify<TInput, TContext>\n  meta?: FormatterMeta<TInput, TOutput, TContext>\n}\n\nexport interface CreateFormatterParam<TInput, TOutput, TContext = unknown> {\n  compare?: FormatterCompare<TInput, TContext>\n  format: FormatterFormat<TInput, TOutput, TContext>\n  stringify?: FormatterStringify<TInput, TContext>\n  meta?: FormatterMeta<TInput, TOutput, TContext>\n}\n\nexport const createFormatter = <TInput, TOutput, TContext = unknown>(\n  param: CreateFormatterParam<TInput, TOutput, TContext>,\n): Formatter<TInput, TOutput, TContext> => {\n  const { format: formatParam, stringify: stringifyParam, compare: compareParam, meta } = param\n\n  const format: FormatterFormat<TInput, TOutput, TContext> = (value, ctx) => formatParam(value, ctx)\n\n  const stringify: FormatterStringify<TInput, TContext> = stringifyParam\n    ? (value, ctx) => stringifyParam(value, ctx)\n    : (value, ctx) => String(format(value, ctx))\n\n  const compare: FormatterCompare<TInput, TContext> = compareParam\n    ? (a, b, ctx) => compareParam(a, b, ctx)\n    : (a, b, ctx) => stringify(a, ctx).localeCompare(stringify(b, ctx))\n\n  return {\n    compare,\n    format,\n    stringify,\n    meta,\n  }\n}\n"],"mappings":";;AA6BA,MAAa,mBACX,UACyC;CACzC,MAAM,EAAE,QAAQ,aAAa,WAAW,gBAAgB,SAAS,cAAc,SAAS;CAExF,MAAM,UAAsD,OAAO,QAAQ,YAAY,OAAO,GAAG;CAEjG,MAAM,YAAkD,kBACnD,OAAO,QAAQ,eAAe,OAAO,GAAG,KACxC,OAAO,QAAQ,OAAO,OAAO,OAAO,GAAG,CAAC;CAM7C,OAAO;EACL,SALkD,gBAC/C,GAAG,GAAG,QAAQ,aAAa,GAAG,GAAG,GAAG,KACpC,GAAG,GAAG,QAAQ,UAAU,GAAG,GAAG,EAAE,cAAc,UAAU,GAAG,GAAG,CAAC;EAIlE;EACA;EACA;CACF;AACF"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/createFormatter.ts"],"sourcesContent":["export interface FormatterFormat<TInput, TOutput, TContext = unknown> {\n  (value: TInput, ctx?: TContext): TOutput\n}\n\nexport interface FormatterStringify<TInput, TContext = unknown> {\n  (value: TInput, ctx?: TContext): string\n}\n\nexport interface FormatterCompare<TInput, TContext = unknown> {\n  (a: TInput, b: TInput, ctx?: TContext): number\n}\n\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type, @typescript-eslint/no-unused-vars\nexport interface FormatterMeta<TInput, TOutput, TContext = unknown> {}\n\nexport interface Formatter<TInput, TOutput, TContext = unknown> {\n  compare: FormatterCompare<TInput, TContext>\n  format: FormatterFormat<TInput, TOutput, TContext>\n  meta?: FormatterMeta<TInput, TOutput, TContext>\n  stringify: FormatterStringify<TInput, TContext>\n}\n\nexport interface CreateFormatterParam<TInput, TOutput, TContext = unknown> {\n  compare?: FormatterCompare<TInput, TContext>\n  format: FormatterFormat<TInput, TOutput, TContext>\n  meta?: FormatterMeta<TInput, TOutput, TContext>\n  stringify?: FormatterStringify<TInput, TContext>\n}\n\nexport const createFormatter = <TInput, TOutput, TContext = unknown>(\n  param: CreateFormatterParam<TInput, TOutput, TContext>,\n): Formatter<TInput, TOutput, TContext> => {\n  const { compare: compareParam, format, meta, stringify: stringifyParam } = param\n\n  const stringify: FormatterStringify<TInput, TContext> =\n    stringifyParam ?? ((value, ctx) => String(format(value, ctx)))\n\n  const compare: FormatterCompare<TInput, TContext> =\n    compareParam ?? ((a, b, ctx) => stringify(a, ctx).localeCompare(stringify(b, ctx)))\n\n  return {\n    compare,\n    format,\n    meta,\n    stringify,\n  }\n}\n"],"mappings":";;AA6BA,MAAa,mBACX,UACyC;CACzC,MAAM,EAAE,SAAS,cAAc,QAAQ,MAAM,WAAW,mBAAmB;CAE3E,MAAM,YACJ,oBAAoB,OAAO,QAAQ,OAAO,OAAO,OAAO,GAAG,CAAC;CAK9D,OAAO;EACL,SAHA,kBAAkB,GAAG,GAAG,QAAQ,UAAU,GAAG,GAAG,EAAE,cAAc,UAAU,GAAG,GAAG,CAAC;EAIjF;EACA;EACA;CACF;AACF"}

package/dist/index.d.cts

@@ -12,14 +12,14 @@ interface FormatterMeta<TInput, TOutput, TContext = unknown> {}
 interface Formatter<TInput, TOutput, TContext = unknown> {
   compare: FormatterCompare<TInput, TContext>;
   format: FormatterFormat<TInput, TOutput, TContext>;
-  stringify: FormatterStringify<TInput, TContext>;
   meta?: FormatterMeta<TInput, TOutput, TContext>;
+  stringify: FormatterStringify<TInput, TContext>;
 }
 interface CreateFormatterParam<TInput, TOutput, TContext = unknown> {
   compare?: FormatterCompare<TInput, TContext>;
   format: FormatterFormat<TInput, TOutput, TContext>;
-  stringify?: FormatterStringify<TInput, TContext>;
   meta?: FormatterMeta<TInput, TOutput, TContext>;
+  stringify?: FormatterStringify<TInput, TContext>;
 }
 declare const createFormatter: <TInput, TOutput, TContext = unknown>(param: CreateFormatterParam<TInput, TOutput, TContext>) => Formatter<TInput, TOutput, TContext>;
 //#endregion

package/dist/index.d.ts

@@ -12,14 +12,14 @@ interface FormatterMeta<TInput, TOutput, TContext = unknown> {}
 interface Formatter<TInput, TOutput, TContext = unknown> {
   compare: FormatterCompare<TInput, TContext>;
   format: FormatterFormat<TInput, TOutput, TContext>;
-  stringify: FormatterStringify<TInput, TContext>;
   meta?: FormatterMeta<TInput, TOutput, TContext>;
+  stringify: FormatterStringify<TInput, TContext>;
 }
 interface CreateFormatterParam<TInput, TOutput, TContext = unknown> {
   compare?: FormatterCompare<TInput, TContext>;
   format: FormatterFormat<TInput, TOutput, TContext>;
-  stringify?: FormatterStringify<TInput, TContext>;
   meta?: FormatterMeta<TInput, TOutput, TContext>;
+  stringify?: FormatterStringify<TInput, TContext>;
 }
 declare const createFormatter: <TInput, TOutput, TContext = unknown>(param: CreateFormatterParam<TInput, TOutput, TContext>) => Formatter<TInput, TOutput, TContext>;
 //#endregion

package/dist/index.js

@@ -1,13 +1,12 @@
 //#region src/createFormatter.ts
 const createFormatter = (param) => {
-	const { format: formatParam, stringify: stringifyParam, compare: compareParam, meta } = param;
-	const format = (value, ctx) => formatParam(value, ctx);
-	const stringify = stringifyParam ? (value, ctx) => stringifyParam(value, ctx) : (value, ctx) => String(format(value, ctx));
+	const { compare: compareParam, format, meta, stringify: stringifyParam } = param;
+	const stringify = stringifyParam ?? ((value, ctx) => String(format(value, ctx)));
 	return {
-		compare: compareParam ? (a, b, ctx) => compareParam(a, b, ctx) : (a, b, ctx) => stringify(a, ctx).localeCompare(stringify(b, ctx)),
+		compare: compareParam ?? ((a, b, ctx) => stringify(a, ctx).localeCompare(stringify(b, ctx))),
 		format,
-		stringify,
-		meta
+		meta,
+		stringify
 	};
 };
 //#endregion

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/createFormatter.ts"],"sourcesContent":["export interface FormatterFormat<TInput, TOutput, TContext = unknown> {\n  (value: TInput, ctx?: TContext): TOutput\n}\n\nexport interface FormatterStringify<TInput, TContext = unknown> {\n  (value: TInput, ctx?: TContext): string\n}\n\nexport interface FormatterCompare<TInput, TContext = unknown> {\n  (a: TInput, b: TInput, ctx?: TContext): number\n}\n\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type, @typescript-eslint/no-unused-vars\nexport interface FormatterMeta<TInput, TOutput, TContext = unknown> {}\n\nexport interface Formatter<TInput, TOutput, TContext = unknown> {\n  compare: FormatterCompare<TInput, TContext>\n  format: FormatterFormat<TInput, TOutput, TContext>\n  stringify: FormatterStringify<TInput, TContext>\n  meta?: FormatterMeta<TInput, TOutput, TContext>\n}\n\nexport interface CreateFormatterParam<TInput, TOutput, TContext = unknown> {\n  compare?: FormatterCompare<TInput, TContext>\n  format: FormatterFormat<TInput, TOutput, TContext>\n  stringify?: FormatterStringify<TInput, TContext>\n  meta?: FormatterMeta<TInput, TOutput, TContext>\n}\n\nexport const createFormatter = <TInput, TOutput, TContext = unknown>(\n  param: CreateFormatterParam<TInput, TOutput, TContext>,\n): Formatter<TInput, TOutput, TContext> => {\n  const { format: formatParam, stringify: stringifyParam, compare: compareParam, meta } = param\n\n  const format: FormatterFormat<TInput, TOutput, TContext> = (value, ctx) => formatParam(value, ctx)\n\n  const stringify: FormatterStringify<TInput, TContext> = stringifyParam\n    ? (value, ctx) => stringifyParam(value, ctx)\n    : (value, ctx) => String(format(value, ctx))\n\n  const compare: FormatterCompare<TInput, TContext> = compareParam\n    ? (a, b, ctx) => compareParam(a, b, ctx)\n    : (a, b, ctx) => stringify(a, ctx).localeCompare(stringify(b, ctx))\n\n  return {\n    compare,\n    format,\n    stringify,\n    meta,\n  }\n}\n"],"mappings":";AA6BA,MAAa,mBACX,UACyC;CACzC,MAAM,EAAE,QAAQ,aAAa,WAAW,gBAAgB,SAAS,cAAc,SAAS;CAExF,MAAM,UAAsD,OAAO,QAAQ,YAAY,OAAO,GAAG;CAEjG,MAAM,YAAkD,kBACnD,OAAO,QAAQ,eAAe,OAAO,GAAG,KACxC,OAAO,QAAQ,OAAO,OAAO,OAAO,GAAG,CAAC;CAM7C,OAAO;EACL,SALkD,gBAC/C,GAAG,GAAG,QAAQ,aAAa,GAAG,GAAG,GAAG,KACpC,GAAG,GAAG,QAAQ,UAAU,GAAG,GAAG,EAAE,cAAc,UAAU,GAAG,GAAG,CAAC;EAIlE;EACA;EACA;CACF;AACF"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/createFormatter.ts"],"sourcesContent":["export interface FormatterFormat<TInput, TOutput, TContext = unknown> {\n  (value: TInput, ctx?: TContext): TOutput\n}\n\nexport interface FormatterStringify<TInput, TContext = unknown> {\n  (value: TInput, ctx?: TContext): string\n}\n\nexport interface FormatterCompare<TInput, TContext = unknown> {\n  (a: TInput, b: TInput, ctx?: TContext): number\n}\n\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type, @typescript-eslint/no-unused-vars\nexport interface FormatterMeta<TInput, TOutput, TContext = unknown> {}\n\nexport interface Formatter<TInput, TOutput, TContext = unknown> {\n  compare: FormatterCompare<TInput, TContext>\n  format: FormatterFormat<TInput, TOutput, TContext>\n  meta?: FormatterMeta<TInput, TOutput, TContext>\n  stringify: FormatterStringify<TInput, TContext>\n}\n\nexport interface CreateFormatterParam<TInput, TOutput, TContext = unknown> {\n  compare?: FormatterCompare<TInput, TContext>\n  format: FormatterFormat<TInput, TOutput, TContext>\n  meta?: FormatterMeta<TInput, TOutput, TContext>\n  stringify?: FormatterStringify<TInput, TContext>\n}\n\nexport const createFormatter = <TInput, TOutput, TContext = unknown>(\n  param: CreateFormatterParam<TInput, TOutput, TContext>,\n): Formatter<TInput, TOutput, TContext> => {\n  const { compare: compareParam, format, meta, stringify: stringifyParam } = param\n\n  const stringify: FormatterStringify<TInput, TContext> =\n    stringifyParam ?? ((value, ctx) => String(format(value, ctx)))\n\n  const compare: FormatterCompare<TInput, TContext> =\n    compareParam ?? ((a, b, ctx) => stringify(a, ctx).localeCompare(stringify(b, ctx)))\n\n  return {\n    compare,\n    format,\n    meta,\n    stringify,\n  }\n}\n"],"mappings":";AA6BA,MAAa,mBACX,UACyC;CACzC,MAAM,EAAE,SAAS,cAAc,QAAQ,MAAM,WAAW,mBAAmB;CAE3E,MAAM,YACJ,oBAAoB,OAAO,QAAQ,OAAO,OAAO,OAAO,GAAG,CAAC;CAK9D,OAAO;EACL,SAHA,kBAAkB,GAAG,GAAG,QAAQ,UAAU,GAAG,GAAG,EAAE,cAAc,UAAU,GAAG,GAAG,CAAC;EAIjF;EACA;EACA;CACF;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "afformative",
-  "version": "0.7.0-beta.4",
+  "version": "0.7.0-beta.5",
   "description": "A standardized way to format values in your React components.",
   "keywords": [
     "react",