afformative 0.6.2 → 0.6.3

package/README.md

@@ -81,13 +81,13 @@ Although formatters can render icons or custom translation components, we often
 
 > Lexicographic sorting of items based on translations is a typical real world example, especially when you are using a custom React component for visualising the translation keys alongside the actual translations.
 
-This is where usage suggestions comes into play. Suggestions can be used to tell formatters that a value needs to be rendered with some special care. For example, pass `"primitive"` to tell a formatter that it should return a primitive value, such as a string.
+This is where usage suggestions come into play. Suggestions can be used to tell formatters that a value needs to be rendered with some special care. For example, pass `"primitive"` to tell a formatter that it should return a primitive value, such as a string.
 
 ```js
 import { makeFormatter } from "afformative"
 
-const booleanFormatter = makeFormatter((value, usageSuggestions) => {
-  if (usageSuggestions.includes("primitive")) {
+const booleanFormatter = makeFormatter((value, suggestions) => {
+  if (suggestions.includes("primitive")) {
     return value ? "True" : "False"
   }
 

package/dist/afformative.cjs.js

@@ -3,25 +3,18 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var _toConsumableArray = require('@babel/runtime/helpers/toConsumableArray');
-var _objectWithoutProperties = require('@babel/runtime/helpers/objectWithoutProperties');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
 var _toConsumableArray__default = /*#__PURE__*/_interopDefaultLegacy(_toConsumableArray);
-var _objectWithoutProperties__default = /*#__PURE__*/_interopDefaultLegacy(_objectWithoutProperties);
 
-// TODO: Update `FormatDefinition` type based on this snippet. Sadly, TypeScript cannot correctly
-// verify the return type of the format definition based on the suggestions, printing errors such
-// as `Type 'string' is not assignable to type '"primitive" extends TSuggestion ? string : string'`
-// which is, of course, nonsense. Same applies to `FormatChainDefinition`.
-//
-//   interface FormatDefinition<TInput, TOutput, TPrimitiveOutput, TDataContext extends DataContext> {
-//     <TSuggestion extends Suggestion>(
-//       value: TInput,
-//       usageSuggestions: TSuggestion[],
-//       dataContext: Partial<TDataContext>,
-//     ): PrimitiveSuggestion extends TSuggestion ? TPrimitiveOutput : TOutput
-//   }
+var ensureFormatSuggestionIntegrity = function ensureFormatSuggestionIntegrity(suggestions) {
+  return suggestions.includes("primitive") || !suggestions.includes("comparable") ? suggestions : ["primitive"].concat(_toConsumableArray__default["default"](suggestions));
+};
+
+var ensureFormatAsPrimitiveSuggestionIntegrity = function ensureFormatAsPrimitiveSuggestionIntegrity(suggestions) {
+  return suggestions.includes("primitive") ? suggestions : ["primitive"].concat(_toConsumableArray__default["default"](suggestions));
+};
 
 /**
  * Creates a new formatter.
@@ -30,38 +23,33 @@ var _objectWithoutProperties__default = /*#__PURE__*/_interopDefaultLegacy(_obje
  * @param formatterOptions Additional options for the formatter.
  */
 var makeFormatter = function makeFormatter(format, formatterOptions) {
-  var formatter = function formatter(_ref) {
-    var _format;
-
-    var children = _ref.children,
-        _ref$suggestions = _ref.suggestions,
-        suggestions = _ref$suggestions === void 0 ? [] : _ref$suggestions,
-        dataContext = _objectWithoutProperties__default['default'](_ref, ["children", "suggestions"]);
+  var formatter = function formatter(props) {
+    var _format, _props$suggestions;
 
-    return (_format = format(children, suggestions, dataContext)) !== null && _format !== void 0 ? _format : null;
+    return (_format = format(props.children, (_props$suggestions = props.suggestions) !== null && _props$suggestions !== void 0 ? _props$suggestions : [], props)) !== null && _format !== void 0 ? _format : null;
   };
 
   formatter.displayName = formatterOptions === null || formatterOptions === void 0 ? void 0 : formatterOptions.displayName;
 
   formatter.format = function (value) {
-    var usageSuggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
+    var suggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
     var dataContext = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
-    return format(value, usageSuggestions, dataContext);
+    return format(value, ensureFormatSuggestionIntegrity(suggestions), dataContext);
   };
 
   formatter.formatAsPrimitive = function (value) {
-    var usageSuggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
+    var suggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
     var dataContext = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
-    return format(value, ["primitive"].concat(_toConsumableArray__default['default'](usageSuggestions)), dataContext);
+    return format(value, ensureFormatAsPrimitiveSuggestionIntegrity(suggestions), dataContext);
   };
 
   formatter.wrap = function (nextFormat, nextFormatterOptions) {
-    var nextFormatter = makeFormatter(function (value, usageSuggestions, dataContext) {
-      var delegate = function delegate(delegatedValue, delegatedUsageSuggestions, delegatedDataContext) {
-        return formatter.format(delegatedValue, delegatedUsageSuggestions !== null && delegatedUsageSuggestions !== void 0 ? delegatedUsageSuggestions : usageSuggestions, delegatedDataContext !== null && delegatedDataContext !== void 0 ? delegatedDataContext : dataContext);
+    var nextFormatter = makeFormatter(function (value, suggestions, dataContext) {
+      var delegate = function delegate(delegatedValue, delegatedSuggestions, delegatedDataContext) {
+        return formatter.format(delegatedValue, delegatedSuggestions !== null && delegatedSuggestions !== void 0 ? delegatedSuggestions : suggestions, delegatedDataContext !== null && delegatedDataContext !== void 0 ? delegatedDataContext : dataContext);
       };
 
-      return nextFormat(delegate, value, usageSuggestions, dataContext);
+      return nextFormat(delegate, value, suggestions, dataContext);
     }, nextFormatterOptions !== null && nextFormatterOptions !== void 0 ? nextFormatterOptions : formatterOptions);
     nextFormatter.innerFormatter = formatter;
     return nextFormatter;

package/dist/afformative.esm.js

@@ -1,18 +1,12 @@
 import _toConsumableArray from '@babel/runtime/helpers/esm/toConsumableArray';
-import _objectWithoutProperties from '@babel/runtime/helpers/esm/objectWithoutProperties';
 
-// TODO: Update `FormatDefinition` type based on this snippet. Sadly, TypeScript cannot correctly
-// verify the return type of the format definition based on the suggestions, printing errors such
-// as `Type 'string' is not assignable to type '"primitive" extends TSuggestion ? string : string'`
-// which is, of course, nonsense. Same applies to `FormatChainDefinition`.
-//
-//   interface FormatDefinition<TInput, TOutput, TPrimitiveOutput, TDataContext extends DataContext> {
-//     <TSuggestion extends Suggestion>(
-//       value: TInput,
-//       usageSuggestions: TSuggestion[],
-//       dataContext: Partial<TDataContext>,
-//     ): PrimitiveSuggestion extends TSuggestion ? TPrimitiveOutput : TOutput
-//   }
+var ensureFormatSuggestionIntegrity = function ensureFormatSuggestionIntegrity(suggestions) {
+  return suggestions.includes("primitive") || !suggestions.includes("comparable") ? suggestions : ["primitive"].concat(_toConsumableArray(suggestions));
+};
+
+var ensureFormatAsPrimitiveSuggestionIntegrity = function ensureFormatAsPrimitiveSuggestionIntegrity(suggestions) {
+  return suggestions.includes("primitive") ? suggestions : ["primitive"].concat(_toConsumableArray(suggestions));
+};
 
 /**
  * Creates a new formatter.
@@ -21,38 +15,33 @@ import _objectWithoutProperties from '@babel/runtime/helpers/esm/objectWithoutPr
  * @param formatterOptions Additional options for the formatter.
  */
 var makeFormatter = function makeFormatter(format, formatterOptions) {
-  var formatter = function formatter(_ref) {
-    var _format;
-
-    var children = _ref.children,
-        _ref$suggestions = _ref.suggestions,
-        suggestions = _ref$suggestions === void 0 ? [] : _ref$suggestions,
-        dataContext = _objectWithoutProperties(_ref, ["children", "suggestions"]);
+  var formatter = function formatter(props) {
+    var _format, _props$suggestions;
 
-    return (_format = format(children, suggestions, dataContext)) !== null && _format !== void 0 ? _format : null;
+    return (_format = format(props.children, (_props$suggestions = props.suggestions) !== null && _props$suggestions !== void 0 ? _props$suggestions : [], props)) !== null && _format !== void 0 ? _format : null;
   };
 
   formatter.displayName = formatterOptions === null || formatterOptions === void 0 ? void 0 : formatterOptions.displayName;
 
   formatter.format = function (value) {
-    var usageSuggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
+    var suggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
     var dataContext = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
-    return format(value, usageSuggestions, dataContext);
+    return format(value, ensureFormatSuggestionIntegrity(suggestions), dataContext);
   };
 
   formatter.formatAsPrimitive = function (value) {
-    var usageSuggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
+    var suggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
     var dataContext = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
-    return format(value, ["primitive"].concat(_toConsumableArray(usageSuggestions)), dataContext);
+    return format(value, ensureFormatAsPrimitiveSuggestionIntegrity(suggestions), dataContext);
   };
 
   formatter.wrap = function (nextFormat, nextFormatterOptions) {
-    var nextFormatter = makeFormatter(function (value, usageSuggestions, dataContext) {
-      var delegate = function delegate(delegatedValue, delegatedUsageSuggestions, delegatedDataContext) {
-        return formatter.format(delegatedValue, delegatedUsageSuggestions !== null && delegatedUsageSuggestions !== void 0 ? delegatedUsageSuggestions : usageSuggestions, delegatedDataContext !== null && delegatedDataContext !== void 0 ? delegatedDataContext : dataContext);
+    var nextFormatter = makeFormatter(function (value, suggestions, dataContext) {
+      var delegate = function delegate(delegatedValue, delegatedSuggestions, delegatedDataContext) {
+        return formatter.format(delegatedValue, delegatedSuggestions !== null && delegatedSuggestions !== void 0 ? delegatedSuggestions : suggestions, delegatedDataContext !== null && delegatedDataContext !== void 0 ? delegatedDataContext : dataContext);
       };
 
-      return nextFormat(delegate, value, usageSuggestions, dataContext);
+      return nextFormat(delegate, value, suggestions, dataContext);
     }, nextFormatterOptions !== null && nextFormatterOptions !== void 0 ? nextFormatterOptions : formatterOptions);
     nextFormatter.innerFormatter = formatter;
     return nextFormatter;

package/dist/afformative.umd.js

@@ -2,7 +2,7 @@
 typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
 typeof define === 'function' && define.amd ? define(['exports'], factory) :
 (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.Afformative = {}));
-}(this, (function (exports) { 'use strict';
+})(this, (function (exports) { 'use strict';
 
 function _arrayLikeToArray(arr, len) {
   if (len == null || len > arr.length) len = arr.length;
@@ -39,52 +39,13 @@ function _toConsumableArray(arr) {
   return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread();
 }
 
-function _objectWithoutPropertiesLoose(source, excluded) {
-  if (source == null) return {};
-  var target = {};
-  var sourceKeys = Object.keys(source);
-  var key, i;
-
-  for (i = 0; i < sourceKeys.length; i++) {
-    key = sourceKeys[i];
-    if (excluded.indexOf(key) >= 0) continue;
-    target[key] = source[key];
-  }
-
-  return target;
-}
-
-function _objectWithoutProperties(source, excluded) {
-  if (source == null) return {};
-  var target = _objectWithoutPropertiesLoose(source, excluded);
-  var key, i;
-
-  if (Object.getOwnPropertySymbols) {
-    var sourceSymbolKeys = Object.getOwnPropertySymbols(source);
-
-    for (i = 0; i < sourceSymbolKeys.length; i++) {
-      key = sourceSymbolKeys[i];
-      if (excluded.indexOf(key) >= 0) continue;
-      if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue;
-      target[key] = source[key];
-    }
-  }
-
-  return target;
-}
+var ensureFormatSuggestionIntegrity = function ensureFormatSuggestionIntegrity(suggestions) {
+  return suggestions.includes("primitive") || !suggestions.includes("comparable") ? suggestions : ["primitive"].concat(_toConsumableArray(suggestions));
+};
 
-// TODO: Update `FormatDefinition` type based on this snippet. Sadly, TypeScript cannot correctly
-// verify the return type of the format definition based on the suggestions, printing errors such
-// as `Type 'string' is not assignable to type '"primitive" extends TSuggestion ? string : string'`
-// which is, of course, nonsense. Same applies to `FormatChainDefinition`.
-//
-//   interface FormatDefinition<TInput, TOutput, TPrimitiveOutput, TDataContext extends DataContext> {
-//     <TSuggestion extends Suggestion>(
-//       value: TInput,
-//       usageSuggestions: TSuggestion[],
-//       dataContext: Partial<TDataContext>,
-//     ): PrimitiveSuggestion extends TSuggestion ? TPrimitiveOutput : TOutput
-//   }
+var ensureFormatAsPrimitiveSuggestionIntegrity = function ensureFormatAsPrimitiveSuggestionIntegrity(suggestions) {
+  return suggestions.includes("primitive") ? suggestions : ["primitive"].concat(_toConsumableArray(suggestions));
+};
 
 /**
  * Creates a new formatter.
@@ -93,38 +54,33 @@ function _objectWithoutProperties(source, excluded) {
  * @param formatterOptions Additional options for the formatter.
  */
 var makeFormatter = function makeFormatter(format, formatterOptions) {
-  var formatter = function formatter(_ref) {
-    var _format;
-
-    var children = _ref.children,
-        _ref$suggestions = _ref.suggestions,
-        suggestions = _ref$suggestions === void 0 ? [] : _ref$suggestions,
-        dataContext = _objectWithoutProperties(_ref, ["children", "suggestions"]);
+  var formatter = function formatter(props) {
+    var _format, _props$suggestions;
 
-    return (_format = format(children, suggestions, dataContext)) !== null && _format !== void 0 ? _format : null;
+    return (_format = format(props.children, (_props$suggestions = props.suggestions) !== null && _props$suggestions !== void 0 ? _props$suggestions : [], props)) !== null && _format !== void 0 ? _format : null;
   };
 
   formatter.displayName = formatterOptions === null || formatterOptions === void 0 ? void 0 : formatterOptions.displayName;
 
   formatter.format = function (value) {
-    var usageSuggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
+    var suggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
     var dataContext = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
-    return format(value, usageSuggestions, dataContext);
+    return format(value, ensureFormatSuggestionIntegrity(suggestions), dataContext);
   };
 
   formatter.formatAsPrimitive = function (value) {
-    var usageSuggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
+    var suggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
     var dataContext = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
-    return format(value, ["primitive"].concat(_toConsumableArray(usageSuggestions)), dataContext);
+    return format(value, ensureFormatAsPrimitiveSuggestionIntegrity(suggestions), dataContext);
   };
 
   formatter.wrap = function (nextFormat, nextFormatterOptions) {
-    var nextFormatter = makeFormatter(function (value, usageSuggestions, dataContext) {
-      var delegate = function delegate(delegatedValue, delegatedUsageSuggestions, delegatedDataContext) {
-        return formatter.format(delegatedValue, delegatedUsageSuggestions !== null && delegatedUsageSuggestions !== void 0 ? delegatedUsageSuggestions : usageSuggestions, delegatedDataContext !== null && delegatedDataContext !== void 0 ? delegatedDataContext : dataContext);
+    var nextFormatter = makeFormatter(function (value, suggestions, dataContext) {
+      var delegate = function delegate(delegatedValue, delegatedSuggestions, delegatedDataContext) {
+        return formatter.format(delegatedValue, delegatedSuggestions !== null && delegatedSuggestions !== void 0 ? delegatedSuggestions : suggestions, delegatedDataContext !== null && delegatedDataContext !== void 0 ? delegatedDataContext : dataContext);
       };
 
-      return nextFormat(delegate, value, usageSuggestions, dataContext);
+      return nextFormat(delegate, value, suggestions, dataContext);
     }, nextFormatterOptions !== null && nextFormatterOptions !== void 0 ? nextFormatterOptions : formatterOptions);
     nextFormatter.innerFormatter = formatter;
     return nextFormatter;
@@ -137,4 +93,4 @@ exports.makeFormatter = makeFormatter;
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-})));
+}));

package/dist/afformative.umd.min.js

@@ -1 +1 @@
-!function(t,r){"object"==typeof exports&&"undefined"!=typeof module?r(exports):"function"==typeof define&&define.amd?define(["exports"],r):r((t="undefined"!=typeof globalThis?globalThis:t||self).Afformative={})}(this,(function(t){"use strict";function r(t,r){(null==r||r>t.length)&&(r=t.length);for(var e=0,n=Array(r);r>e;e++)n[e]=t[e];return n}function e(t){return function(t){if(Array.isArray(t))return r(t)}(t)||function(t){if("undefined"!=typeof Symbol&&null!=t[Symbol.iterator]||null!=t["@@iterator"])return Array.from(t)}(t)||function(t,e){if(t){if("string"==typeof t)return r(t,e);var n=Object.prototype.toString.call(t).slice(8,-1);return"Object"===n&&t.constructor&&(n=t.constructor.name),"Map"===n||"Set"===n?Array.from(t):"Arguments"===n||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)?r(t,e):void 0}}(t)||function(){throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}()}function n(t,r){if(null==t)return{};var e,n,o=function(t,r){if(null==t)return{};var e,n,o={},i=Object.keys(t);for(n=0;i.length>n;n++)0>r.indexOf(e=i[n])&&(o[e]=t[e]);return o}(t,r);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(t);for(n=0;i.length>n;n++)0>r.indexOf(e=i[n])&&Object.prototype.propertyIsEnumerable.call(t,e)&&(o[e]=t[e])}return o}t.makeFormatter=function t(r,o){var i=function(t){var e,o=t.children,i=t.suggestions,u=void 0===i?[]:i,l=n(t,["children","suggestions"]);return null!==(e=r(o,u,l))&&void 0!==e?e:null};return i.displayName=null==o?void 0:o.displayName,i.format=function(t){var e=arguments.length>1&&void 0!==arguments[1]?arguments[1]:[],n=arguments.length>2&&void 0!==arguments[2]?arguments[2]:{};return r(t,e,n)},i.formatAsPrimitive=function(t){var n=arguments.length>1&&void 0!==arguments[1]?arguments[1]:[],o=arguments.length>2&&void 0!==arguments[2]?arguments[2]:{};return r(t,["primitive"].concat(e(n)),o)},i.wrap=function(r,e){var n=t((function(t,e,n){return r((function(t,r,o){return i.format(t,null!=r?r:e,null!=o?o:n)}),t,e,n)}),null!=e?e:o);return n.innerFormatter=i,n},i},Object.defineProperty(t,"__esModule",{value:!0})}));
+!function(t,n){"object"==typeof exports&&"undefined"!=typeof module?n(exports):"function"==typeof define&&define.amd?define(["exports"],n):n((t="undefined"!=typeof globalThis?globalThis:t||self).Afformative={})}(this,(function(t){"use strict";function n(t,n){(null==n||n>t.length)&&(n=t.length);for(var r=0,e=Array(n);n>r;r++)e[r]=t[r];return e}function r(t){return function(t){if(Array.isArray(t))return n(t)}(t)||function(t){if("undefined"!=typeof Symbol&&null!=t[Symbol.iterator]||null!=t["@@iterator"])return Array.from(t)}(t)||function(t,r){if(t){if("string"==typeof t)return n(t,r);var e=Object.prototype.toString.call(t).slice(8,-1);return"Object"===e&&t.constructor&&(e=t.constructor.name),"Map"===e||"Set"===e?Array.from(t):"Arguments"===e||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(e)?n(t,r):void 0}}(t)||function(){throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}()}var e=function(t){return t.includes("primitive")||!t.includes("comparable")?t:["primitive"].concat(r(t))},i=function(t){return t.includes("primitive")?t:["primitive"].concat(r(t))};t.makeFormatter=function t(n,r){var o=function(t){var r,e;return null!==(r=n(t.children,null!==(e=t.suggestions)&&void 0!==e?e:[],t))&&void 0!==r?r:null};return o.displayName=null==r?void 0:r.displayName,o.format=function(t){var r=arguments.length>1&&void 0!==arguments[1]?arguments[1]:[],i=arguments.length>2&&void 0!==arguments[2]?arguments[2]:{};return n(t,e(r),i)},o.formatAsPrimitive=function(t){var r=arguments.length>1&&void 0!==arguments[1]?arguments[1]:[],e=arguments.length>2&&void 0!==arguments[2]?arguments[2]:{};return n(t,i(r),e)},o.wrap=function(n,e){var i=t((function(t,r,e){return n((function(t,n,i){return o.format(t,null!=n?n:r,null!=i?i:e)}),t,r,e)}),null!=e?e:r);return i.innerFormatter=o,i},o},Object.defineProperty(t,"__esModule",{value:!0})}));

package/dist/types/index.d.ts

@@ -1,2 +1,2 @@
-export * from "./makeFormatter";
+export * from "./makeFormatter";
 //# sourceMappingURL=index.d.ts.map

package/dist/types/makeFormatter.d.ts

@@ -1,94 +1,97 @@
-declare type PrimitiveSuggestion = "primitive";
-declare type SemanticSuggestion = "abbreviated" | "icon" | "verbose";
-declare type Suggestion = PrimitiveSuggestion | SemanticSuggestion;
-interface FormatterOptions {
-    /** Formatter name, useful for debugging or advanced pattern matching. */
-    displayName?: string;
-}
-declare type DataContext = Record<string, any>;
-interface FormatDefinition<TInput, TOutput, TPrimitiveOutput, TDataContext extends DataContext> {
-    (
-    /** Value to format. */
-    value: TInput, 
-    /** Suggestions passed by the consumer of a formatter. */
-    usageSuggestions: Suggestion[], 
-    /** Additional data context to be used by the formatter. */
-    dataContext: Partial<TDataContext>): TOutput | TPrimitiveOutput;
-}
-interface FormatMethod<TInput, TOutput, TPrimitiveOutput, TDataContext extends DataContext> {
-    <TSuggestion extends Suggestion>(
-    /** Value to format. */
-    value: TInput, 
-    /** Suggestions the formatter should take note of. */
-    usageSuggestions?: TSuggestion[], 
-    /** Additional data context the formatter might find useful. */
-    dataContext?: Partial<TDataContext>): PrimitiveSuggestion extends TSuggestion ? TPrimitiveOutput : TOutput;
-}
-interface FormatAsPrimitiveMethod<TInput, TPrimitiveOutput, TDataContext extends DataContext> {
-    (
-    /** Value to format. */
-    value: TInput, 
-    /** Suggestions the formatter should take note of in addition to `primitive`. */
-    usageSuggestions?: Suggestion[], 
-    /** Additional data context the formatter might find useful. */
-    dataContext?: Partial<TDataContext>): TPrimitiveOutput;
-}
-interface FormatChainDefinition<TInnerInput, TInnerOutput, TInnerPrimitiveInput, TInnerDataContext extends DataContext, TOuterInput, TOuterOutput, TOuterPrimitiveOutput, TOuterDataContext extends DataContext> {
-    (
-    /**
-     * The `formatter.format` method which can be used to delegate the formatting
-     * to the wrapped formatter. Delegation is simplified so if no suggestions or contextual
-     * props are passed, the original ones are used instead.
-     */
-    delegate: FormatMethod<TInnerInput, TInnerOutput, TInnerPrimitiveInput, TInnerDataContext>, 
-    /** Value to format. */
-    value: TOuterInput, 
-    /** Suggestions the formatter should take note of. */
-    usageSuggestions: Suggestion[], 
-    /** Additional data context the formatter might find useful. */
-    dataContext: Partial<TOuterDataContext>): TOuterOutput | TOuterPrimitiveOutput;
-}
-declare type FormatterProps<TInput, TDataContext extends DataContext> = {
-    /** Value to format. */
-    children: TInput;
-    /** Suggestions the formatter should take note of. */
-    suggestions?: Suggestion[];
-} & Partial<TDataContext>;
-export interface Formatter<TInput, TOutput, TPrimitiveOutput = TOutput, TDataContext extends DataContext = DataContext> {
-    /** Formatter name, useful for debugging or advanced pattern matching. */
-    displayName?: string;
-    /** Formats a value. */
-    format: FormatMethod<TInput, TOutput, TPrimitiveOutput, TDataContext>;
-    /** Formats a value with the `primitive` suggestion. */
-    formatAsPrimitive: FormatAsPrimitiveMethod<TInput, TPrimitiveOutput, TDataContext>;
-    /** The callee of the `.wrap` method used to produce this formatter. */
-    innerFormatter?: Formatter<any, any, any, any>;
-    /**
-     * Creates a new formatter from an existing one. Allows overriding of formatter behaviour
-     * for certain values.
-     */
-    wrap: <TNextInput = TInput, TNextOutput = TOutput, TNextPrimitiveOutput = TPrimitiveOutput, TNextDataContext extends DataContext = TDataContext>(
-    /**
-     * Function used to format the value. Has the same signature as the one passed
-     * to `makeFormatter`, except a `delegate` function is passed in the first position.
-     * This function can be used to delegate formatting to the original (inner) formatter.
-     */
-    nextFormat: FormatChainDefinition<TInput, TOutput, TPrimitiveOutput, TDataContext, TNextInput, TNextOutput, TNextPrimitiveOutput, TNextDataContext>, 
-    /** New formatter options, replacing the original ones. */
-    nextFormatterOptions?: FormatterOptions) => Formatter<TNextInput, TNextOutput, TNextPrimitiveOutput, TNextDataContext>;
-    /**
-     * Backwards-compatible way to use the formatter as a React component.
-     *
-     * @deprecated Since v0.6.0. Prefer using the `Formatter.format` method instead.
-     */
-    (props: FormatterProps<TInput, TDataContext>): TOutput | TPrimitiveOutput | null;
-}
-/**
- * Creates a new formatter.
- *
- * @param format Function used to format the value.
- * @param formatterOptions Additional options for the formatter.
- */
-export declare const makeFormatter: <TInput, TOutput, TPrimitiveOutput = TOutput, TDataContext extends DataContext = DataContext>(format: FormatDefinition<TInput, TOutput, TPrimitiveOutput, TDataContext>, formatterOptions?: FormatterOptions | undefined) => Formatter<TInput, TOutput, TPrimitiveOutput, TDataContext>;
-export {};
+declare type PrimitiveSuggestion = "primitive" | "comparable";
+declare type Suggestion = PrimitiveSuggestion | "abbreviated" | "as-icon"
+/**
+ * @deprecated Since v0.6.3. Use `"as-icon"` or `"with-icon"` instead.
+ */
+ | "icon" | "verbose" | "with-icon";
+declare type DataContext = Record<string, any>;
+interface FormatterOptions {
+    /** Formatter name, useful for debugging or advanced pattern matching. */
+    displayName?: string;
+}
+interface FormatDefinition<TInput, TOutput, TPrimitiveOutput, TDataContext extends DataContext> {
+    (
+    /** Value to format. */
+    value: TInput, 
+    /** Suggestions passed by the consumer of a formatter. */
+    suggestions: Suggestion[], 
+    /** Additional data context to be used by the formatter. */
+    dataContext: Partial<TDataContext>): TOutput | TPrimitiveOutput;
+}
+interface FormatMethod<TInput, TOutput, TPrimitiveOutput, TDataContext extends DataContext> {
+    (
+    /** Value to format. */
+    value: TInput, 
+    /** Suggestions the formatter should take note of. */
+    suggestions?: Suggestion[], 
+    /** Additional data context the formatter might find useful. */
+    dataContext?: Partial<TDataContext>): TOutput | TPrimitiveOutput;
+}
+interface FormatAsPrimitiveMethod<TInput, TPrimitiveOutput, TDataContext extends DataContext> {
+    (
+    /** Value to format. */
+    value: TInput, 
+    /** Suggestions the formatter should take note of in addition to `primitive`. */
+    suggestions?: Suggestion[], 
+    /** Additional data context the formatter might find useful. */
+    dataContext?: Partial<TDataContext>): TPrimitiveOutput;
+}
+interface FormatChainDefinition<TInnerInput, TInnerOutput, TInnerPrimitiveInput, TInnerDataContext extends DataContext, TOuterInput, TOuterOutput, TOuterPrimitiveOutput, TOuterDataContext extends DataContext> {
+    (
+    /**
+     * The `formatter.format` method which can be used to delegate the formatting
+     * to the wrapped formatter. Delegation is simplified so if no suggestions or contextual
+     * props are passed, the original ones are used instead.
+     */
+    delegate: FormatMethod<TInnerInput, TInnerOutput, TInnerPrimitiveInput, TInnerDataContext>, 
+    /** Value to format. */
+    value: TOuterInput, 
+    /** Suggestions the formatter should take note of. */
+    suggestions: Suggestion[], 
+    /** Additional data context the formatter might find useful. */
+    dataContext: Partial<TOuterDataContext>): TOuterOutput | TOuterPrimitiveOutput;
+}
+declare type FormatterProps<TInput, TDataContext extends DataContext> = {
+    /** Value to format. */
+    children: TInput;
+    /** Suggestions the formatter should take note of. */
+    suggestions?: Suggestion[];
+} & Partial<TDataContext>;
+export interface Formatter<TInput, TOutput, TPrimitiveOutput = TOutput, TDataContext extends DataContext = DataContext> {
+    /** Formatter name, useful for debugging or advanced pattern matching. */
+    displayName?: string;
+    /** Formats a value. */
+    format: FormatMethod<TInput, TOutput, TPrimitiveOutput, TDataContext>;
+    /** Formats a value with the `primitive` suggestion. */
+    formatAsPrimitive: FormatAsPrimitiveMethod<TInput, TPrimitiveOutput, TDataContext>;
+    /** The callee of the `wrap` method used to produce this formatter. */
+    innerFormatter?: Formatter<any, any, any, any>;
+    /**
+     * Creates a new formatter from an existing one. Allows overriding of formatter behaviour
+     * for certain values.
+     */
+    wrap: <TNextInput = TInput, TNextOutput = TOutput, TNextPrimitiveOutput = TPrimitiveOutput, TNextDataContext extends TDataContext = TDataContext>(
+    /**
+     * Function used to format the value. Has the same signature as the one passed
+     * to `makeFormatter`, except a `delegate` function is passed in the first position.
+     * This function can be used to delegate formatting to the original (inner) formatter.
+     */
+    nextFormat: FormatChainDefinition<TInput, TOutput, TPrimitiveOutput, TDataContext, TNextInput, TNextOutput, TNextPrimitiveOutput, TNextDataContext>, 
+    /** New formatter options, replacing the original ones. */
+    nextFormatterOptions?: FormatterOptions) => Formatter<TNextInput, TNextOutput, TNextPrimitiveOutput, TNextDataContext>;
+    /**
+     * Backwards-compatible way to use the formatter as a React component.
+     *
+     * @deprecated Since v0.6.0. Prefer using the `format` method instead.
+     */
+    (props: FormatterProps<TInput, TDataContext>): TOutput | TPrimitiveOutput | null;
+}
+/**
+ * Creates a new formatter.
+ *
+ * @param format Function used to format the value.
+ * @param formatterOptions Additional options for the formatter.
+ */
+export declare const makeFormatter: <TInput, TOutput, TPrimitiveOutput = TOutput, TDataContext extends DataContext = DataContext>(format: FormatDefinition<TInput, TOutput, TPrimitiveOutput, TDataContext>, formatterOptions?: FormatterOptions | undefined) => Formatter<TInput, TOutput, TPrimitiveOutput, TDataContext>;
+export {};
 //# sourceMappingURL=makeFormatter.d.ts.map

package/dist/types/makeFormatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"makeFormatter.d.ts","sourceRoot":"","sources":["../../src/makeFormatter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"makeFormatter.d.ts","sourceRoot":"","sources":["../../src/makeFormatter.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "afformative",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "license": "MIT",
   "main": "dist/afformative.cjs.js",
   "module": "dist/afformative.esm.js",
@@ -34,5 +34,5 @@
     "access": "public"
   },
   "sideEffects": false,
-  "gitHead": "3e3b893eee2b69d29019b3683b9d1d719192a2b5"
+  "gitHead": "ddc8c8682e2777c730108466792b7670d8a43f06"
 }

package/src/makeFormatter.test.ts

@@ -2,158 +2,217 @@ import { makeFormatter } from "./makeFormatter"
 
 const toUpperCase = (string: string) => string.toUpperCase()
 
+const upperCaseFormatter = makeFormatter<string, string>(toUpperCase)
+
+interface ValueRecord {
+  value: string
+}
+
+const valueRecordUpperCaseFormatter = makeFormatter<ValueRecord, ValueRecord, string>(
+  ({ value }, suggestions) => {
+    if (suggestions.includes("primitive")) {
+      return toUpperCase(value)
+    }
+
+    return { value: toUpperCase(value) }
+  },
+)
+
 describe("makeFormatter", () => {
-  it("handles trivial formatting", () => {
-    const formatter = makeFormatter<string, string>(toUpperCase)
-    expect(formatter.format("foo")).toBe("FOO")
-  })
+  const format = jest.fn()
 
-  it("accepts a `name` option", () => {
-    const formatter = makeFormatter<string, string>(toUpperCase, { displayName: "UpperFormatter" })
-    expect(formatter.displayName).toBe("UpperFormatter")
+  afterEach(() => {
+    jest.clearAllMocks()
   })
 
-  it("passes `suggestions` to `format`", () => {
-    const formatter = makeFormatter<string, string>((value, suggestions) => {
-      if (suggestions.includes("abbreviated")) {
-        return value[0]
-      }
+  describe("displayName", () => {
+    it("accepts a `displayName` option", () => {
+      const displayName = "upperCaseFormatter"
+      const formatter = makeFormatter<string, string>(toUpperCase, { displayName })
+      expect(formatter.displayName).toBe(displayName)
+    })
+  })
 
-      return value
+  describe("format", () => {
+    it("handles trivial formatting", () => {
+      expect(upperCaseFormatter.format("foo")).toBe("FOO")
     })
 
-    expect(formatter.format("foo", ["abbreviated"])).toBe("f")
-    expect(formatter.format("foo", [])).toBe("foo")
-    expect(formatter.format("foo")).toBe("foo")
-  })
+    it("passes through non-empty suggestions", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.format("foo", ["abbreviated"])
+      expect(format.mock.calls[0][1]).toEqual(["abbreviated"])
+    })
 
-  it("handles formatting with the `primitive` suggestion", () => {
-    type Structure = { value: string }
+    it("passes through empty suggestions", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.format("foo", [])
+      expect(format.mock.calls[0][1]).toEqual([])
+    })
 
-    const formatter = makeFormatter<Structure, Structure, string>((value, suggestions) => {
-      if (suggestions.includes("primitive")) {
-        return value.value
-      }
+    it("defaults suggestions to an empty array", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.format("foo")
+      expect(format.mock.calls[0][1]).toEqual([])
+    })
 
-      return value
+    it("passes through the `primitive` suggestion", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.format("foo", ["primitive"])
+      expect(format.mock.calls[0][1]).toEqual(["primitive"])
     })
 
-    expect(formatter.format({ value: "foo" }, ["primitive"])).toBe("foo")
-    expect(formatter.formatAsPrimitive({ value: "foo" })).toBe("foo")
-    expect(formatter.formatAsPrimitive({ value: "foo" }, ["primitive"])).toBe("foo")
-  })
+    it("passes the `primitive` suggestion alongside `comparable` when missing", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.format("foo", ["comparable"])
+      expect(format.mock.calls[0][1]).toEqual(["primitive", "comparable"])
+    })
 
-  it("supports simple behavior wrapping", () => {
-    const formatter = makeFormatter<string, string>(toUpperCase)
+    it("does not pass the `primitive` suggestion alongside other suggestions when missing", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.format("foo", ["abbreviated", "verbose"])
+      expect(format.mock.calls[0][1]).toEqual(["abbreviated", "verbose"])
+    })
 
-    const wrappedFormatter = formatter.wrap((delegate, value) =>
-      value === "foo" ? "override" : delegate(value),
-    )
+    it("supports data context", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.format("foo", [], { foo: "bar" })
+      expect(format.mock.calls[0][2]).toEqual({ foo: "bar" })
+    })
 
-    expect(wrappedFormatter.format("foo")).toBe("override")
-    expect(wrappedFormatter.format("bar")).toBe("BAR")
+    it("defaults data context to an empty object", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.format("foo")
+      expect(format.mock.calls[0][2]).toEqual({})
+    })
   })
 
-  it("supports simple behavior wrapping with suggestions", () => {
-    const formatter = makeFormatter<string, string>(toUpperCase)
+  describe("formatAsPrimitive", () => {
+    it("handles trivial formatting", () => {
+      expect(upperCaseFormatter.formatAsPrimitive("foo")).toBe("FOO")
+    })
 
-    const wrappedFormatter = formatter.wrap((delegate, value, suggestions) =>
-      value === "foo" && suggestions.includes("abbreviated") ? "f" : delegate(value),
-    )
+    it("passes the `primitive` suggestion when no suggestions are passed", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.formatAsPrimitive("foo")
+      expect(format.mock.calls[0][1]).toEqual(["primitive"])
+    })
 
-    expect(wrappedFormatter.format("foo")).toBe("FOO")
-    expect(wrappedFormatter.format("foo", ["abbreviated"])).toBe("f")
-    expect(wrappedFormatter.format("bar")).toBe("BAR")
-  })
+    it("passes the `primitive` suggestion when empty suggestions are passed", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.formatAsPrimitive("foo", [])
+      expect(format.mock.calls[0][1]).toEqual(["primitive"])
+    })
 
-  it("supports simple behavior wrapping with the `primitive` suggestion", () => {
-    type Structure = { value: string }
+    it("passes the `primitive` suggestion when a different suggestion is passed", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.formatAsPrimitive("foo", ["abbreviated"])
+      expect(format.mock.calls[0][1]).toEqual(["primitive", "abbreviated"])
+    })
 
-    const formatter = makeFormatter<string, string>(toUpperCase)
+    it("passes through the `primitive` suggestion", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.formatAsPrimitive("foo", ["primitive"])
+      expect(format.mock.calls[0][1]).toEqual(["primitive"])
+    })
 
-    const wrappedFormatter = formatter.wrap<Structure, Structure, string>(
-      (delegate, value, suggestions) => (suggestions.includes("primitive") ? value.value : value),
-    )
+    it("passes the `primitive` suggestion alongside `comparable`", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.formatAsPrimitive("foo", ["comparable"])
+      expect(format.mock.calls[0][1]).toEqual(["primitive", "comparable"])
+    })
+
+    it("supports data context", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.formatAsPrimitive("foo", [], { foo: "bar" })
+      expect(format.mock.calls[0][2]).toEqual({ foo: "bar" })
+    })
 
-    expect(wrappedFormatter.format({ value: "foo" }, ["primitive"])).toBe("foo")
-    expect(wrappedFormatter.formatAsPrimitive({ value: "foo" })).toBe("foo")
-    expect(wrappedFormatter.formatAsPrimitive({ value: "foo" }, ["primitive"])).toBe("foo")
+    it("defaults data context to an empty object", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.formatAsPrimitive("foo")
+      expect(format.mock.calls[0][2]).toEqual({})
+    })
   })
 
-  it("supports simple behavior wrapping with data context", () => {
-    const formatter = makeFormatter<string, string>(toUpperCase)
+  describe("wrap", () => {
+    it("handles trivial wrapping", () => {
+      const formatter = makeFormatter<string, string>(format).wrap(() => "bar")
+      expect(formatter.format("foo")).toBe("bar")
+    })
 
-    interface WrappedDataContext {
-      forcedValue?: string
-    }
+    it("handles single-value mapping", () => {
+      const formatter = makeFormatter<string, string>(format).wrap((delegate, value) =>
+        value === "ping" ? "pong" : delegate(value),
+      )
 
-    const wrappedFormatter = formatter.wrap(
-      (delegate, value, suggestions, { forcedValue }: WrappedDataContext) =>
-        forcedValue ?? delegate(value),
-    )
+      expect(formatter.format("ping")).toBe("pong")
+    })
 
-    expect(wrappedFormatter.format("foo")).toBe("FOO")
-    expect(wrappedFormatter.format("foo", undefined, { forcedValue: "override" })).toBe("override")
-  })
+    it("handles delegation to the original formatter", () => {
+      const formatter = upperCaseFormatter.wrap((delegate, value) =>
+        value === "ping" ? "pong" : delegate(value),
+      )
 
-  it("passes the original suggestions when they are not passed manually to `format` when wrapping", () => {
-    const formatter = makeFormatter<string, string>((value, suggestions) => {
-      if (suggestions.includes("abbreviated")) {
-        return value[0]
-      }
+      expect(formatter.format("foo")).toBe("FOO")
+    })
 
-      return value
+    it("sets the `innerFormatter` property", () => {
+      const wrappedFormatter = upperCaseFormatter.wrap((delegate, value) => delegate(value))
+      expect(wrappedFormatter.innerFormatter).toBe(upperCaseFormatter)
     })
 
-    const wrappedFormatter = formatter.wrap((delegate, value) => delegate(value))
-    expect(wrappedFormatter.format("foo", ["abbreviated"])).toBe("f")
-  })
+    it("passes the `primitive` suggestion to `delegate` when using `formatAsPrimitive`", () => {
+      const formatter = valueRecordUpperCaseFormatter.wrap((delegate, value) => delegate(value))
+      expect(formatter.formatAsPrimitive({ value: "foo" })).toBe("FOO")
+    })
 
-  it("sets the `innerFormatter` static property when wrapping", () => {
-    const formatter = makeFormatter<string, string>(toUpperCase)
-    const wrappedFormatter = formatter.wrap((delegate, value) => delegate(value))
-    expect(wrappedFormatter.innerFormatter).toBe(formatter)
-  })
+    it("passes suggestions through to `delegate` when not overriden", () => {
+      const formatter = valueRecordUpperCaseFormatter.wrap((delegate, value) => delegate(value))
+      expect(formatter.format({ value: "foo" }, ["primitive"])).toBe("FOO")
+    })
 
-  it("handles complex wrapping with structural changes", () => {
-    interface BasicDataContext {
-      index?: number
-    }
+    it("supports overriding of suggestions for `delegate`", () => {
+      const formatter = valueRecordUpperCaseFormatter.wrap((delegate, value) => delegate(value, []))
+      expect(formatter.format({ value: "foo" }, ["primitive"])).toEqual({ value: "FOO" })
+    })
 
-    const basicFormatter = makeFormatter(
-      (value: string, suggestions, dataContext: BasicDataContext): string | undefined =>
-        value[dataContext.index ?? 0],
-    )
+    it("supports modifying the input structure", () => {
+      const formatter = upperCaseFormatter.wrap<ValueRecord>((delegate, { value }) =>
+        delegate(value),
+      )
 
-    expect(basicFormatter.format("test", [], { index: 2 })).toBe("s")
+      expect(formatter.format({ value: "foo" })).toBe("FOO")
+    })
 
-    interface ComplexStructure {
-      index: number
-      value: string
-    }
+    it("supports modifying the output structure", () => {
+      const formatter = upperCaseFormatter.wrap<ValueRecord, ValueRecord>(
+        (delegate, { value }) => ({ value: delegate(value) }),
+      )
 
-    interface ComplexDataContext {
-      getIndex?: (structure: ComplexStructure) => number
-    }
+      expect(formatter.format({ value: "foo" })).toEqual({ value: "FOO" })
+    })
+
+    it("supports modifying the data context structure", () => {
+      interface ListContext {
+        row: string
+      }
 
-    const complexFormatter = basicFormatter.wrap(
-      (delegate, value: ComplexStructure, suggestions, dataContext: ComplexDataContext) =>
-        delegate(value.value, suggestions, { index: dataContext.getIndex?.(value) }),
-    )
+      const listFormatter = upperCaseFormatter.wrap<string, string, string, ListContext>(
+        (delegate, value, suggestions, { row }) => `${row}: ${delegate(value)}`,
+      )
 
-    expect(complexFormatter.format({ index: 3, value: "procrastination" })).toBe("p")
+      interface GridContext extends ListContext {
+        column: string
+      }
 
-    expect(
-      complexFormatter.format({ index: 3, value: "procrastination" }, [], {
-        getIndex: ({ index }) => index,
-      }),
-    ).toBe("c")
+      expect(listFormatter.format("foo", [], { row: "A" })).toBe("A: FOO")
 
-    const boundComplexFormatter = complexFormatter.wrap(
-      (delegate, value, suggestions, dataContext) =>
-        delegate(value, suggestions, { ...dataContext, getIndex: ({ index }) => index }),
-    )
+      const gridFormatter = listFormatter.wrap<string, string, string, GridContext>(
+        (delegate, value, suggestions, { column }) => delegate(value).replace(":", `${column}:`),
+      )
 
-    expect(boundComplexFormatter.format({ index: 2, value: "swag" })).toBe("a")
+      expect(gridFormatter.format("foo", [], { row: "B", column: "1" })).toBe("B1: FOO")
+    })
   })
 })

package/src/makeFormatter.ts

@@ -1,47 +1,51 @@
-type PrimitiveSuggestion = "primitive"
-type SemanticSuggestion = "abbreviated" | "icon" | "verbose"
-type Suggestion = PrimitiveSuggestion | SemanticSuggestion
+type PrimitiveSuggestion = "primitive" | "comparable"
+
+type Suggestion =
+  | PrimitiveSuggestion
+  | "abbreviated"
+  | "as-icon"
+  /**
+   * @deprecated Since v0.6.3. Use `"as-icon"` or `"with-icon"` instead.
+   */
+  | "icon"
+  | "verbose"
+  | "with-icon"
+
+const ensureFormatSuggestionIntegrity = (suggestions: Suggestion[]): Suggestion[] =>
+  suggestions.includes("primitive") || !suggestions.includes("comparable")
+    ? suggestions
+    : ["primitive", ...suggestions]
+
+const ensureFormatAsPrimitiveSuggestionIntegrity = (suggestions: Suggestion[]): Suggestion[] =>
+  suggestions.includes("primitive") ? suggestions : ["primitive", ...suggestions]
+
+type DataContext = Record<string, any>
 
 interface FormatterOptions {
   /** Formatter name, useful for debugging or advanced pattern matching. */
   displayName?: string
 }
 
-type DataContext = Record<string, any>
-
-// TODO: Update `FormatDefinition` type based on this snippet. Sadly, TypeScript cannot correctly
-// verify the return type of the format definition based on the suggestions, printing errors such
-// as `Type 'string' is not assignable to type '"primitive" extends TSuggestion ? string : string'`
-// which is, of course, nonsense. Same applies to `FormatChainDefinition`.
-//
-//   interface FormatDefinition<TInput, TOutput, TPrimitiveOutput, TDataContext extends DataContext> {
-//     <TSuggestion extends Suggestion>(
-//       value: TInput,
-//       usageSuggestions: TSuggestion[],
-//       dataContext: Partial<TDataContext>,
-//     ): PrimitiveSuggestion extends TSuggestion ? TPrimitiveOutput : TOutput
-//   }
-
 interface FormatDefinition<TInput, TOutput, TPrimitiveOutput, TDataContext extends DataContext> {
   (
     /** Value to format. */
     value: TInput,
     /** Suggestions passed by the consumer of a formatter. */
-    usageSuggestions: Suggestion[],
+    suggestions: Suggestion[],
     /** Additional data context to be used by the formatter. */
     dataContext: Partial<TDataContext>,
   ): TOutput | TPrimitiveOutput
 }
 
 interface FormatMethod<TInput, TOutput, TPrimitiveOutput, TDataContext extends DataContext> {
-  <TSuggestion extends Suggestion>(
+  (
     /** Value to format. */
     value: TInput,
     /** Suggestions the formatter should take note of. */
-    usageSuggestions?: TSuggestion[],
+    suggestions?: Suggestion[],
     /** Additional data context the formatter might find useful. */
     dataContext?: Partial<TDataContext>,
-  ): PrimitiveSuggestion extends TSuggestion ? TPrimitiveOutput : TOutput
+  ): TOutput | TPrimitiveOutput
 }
 
 interface FormatAsPrimitiveMethod<TInput, TPrimitiveOutput, TDataContext extends DataContext> {
@@ -49,7 +53,7 @@ interface FormatAsPrimitiveMethod<TInput, TPrimitiveOutput, TDataContext extends
     /** Value to format. */
     value: TInput,
     /** Suggestions the formatter should take note of in addition to `primitive`. */
-    usageSuggestions?: Suggestion[],
+    suggestions?: Suggestion[],
     /** Additional data context the formatter might find useful. */
     dataContext?: Partial<TDataContext>,
   ): TPrimitiveOutput
@@ -75,7 +79,7 @@ interface FormatChainDefinition<
     /** Value to format. */
     value: TOuterInput,
     /** Suggestions the formatter should take note of. */
-    usageSuggestions: Suggestion[],
+    suggestions: Suggestion[],
     /** Additional data context the formatter might find useful. */
     dataContext: Partial<TOuterDataContext>,
   ): TOuterOutput | TOuterPrimitiveOutput
@@ -100,7 +104,7 @@ export interface Formatter<
   format: FormatMethod<TInput, TOutput, TPrimitiveOutput, TDataContext>
   /** Formats a value with the `primitive` suggestion. */
   formatAsPrimitive: FormatAsPrimitiveMethod<TInput, TPrimitiveOutput, TDataContext>
-  /** The callee of the `.wrap` method used to produce this formatter. */
+  /** The callee of the `wrap` method used to produce this formatter. */
   innerFormatter?: Formatter<any, any, any, any>
   /**
    * Creates a new formatter from an existing one. Allows overriding of formatter behaviour
@@ -110,7 +114,7 @@ export interface Formatter<
     TNextInput = TInput,
     TNextOutput = TOutput,
     TNextPrimitiveOutput = TPrimitiveOutput,
-    TNextDataContext extends DataContext = TDataContext
+    TNextDataContext extends TDataContext = TDataContext
   >(
     /**
      * Function used to format the value. Has the same signature as the one passed
@@ -133,7 +137,7 @@ export interface Formatter<
   /**
    * Backwards-compatible way to use the formatter as a React component.
    *
-   * @deprecated Since v0.6.0. Prefer using the `Formatter.format` method instead.
+   * @deprecated Since v0.6.0. Prefer using the `format` method instead.
    */
   (props: FormatterProps<TInput, TDataContext>): TOutput | TPrimitiveOutput | null
 }
@@ -153,25 +157,26 @@ export const makeFormatter = <
   format: FormatDefinition<TInput, TOutput, TPrimitiveOutput, TDataContext>,
   formatterOptions?: FormatterOptions,
 ): Formatter<TInput, TOutput, TPrimitiveOutput, TDataContext> => {
-  const formatter: Formatter<TInput, TOutput, TPrimitiveOutput, TDataContext> = ({
-    children,
-    suggestions = [],
-    ...dataContext
-  }) => format(children, suggestions, dataContext as any) ?? null
+  const formatter: Formatter<TInput, TOutput, TPrimitiveOutput, TDataContext> = props =>
+    format(props.children, props.suggestions ?? [], props) ?? null
 
   formatter.displayName = formatterOptions?.displayName
 
-  formatter.format = (value, usageSuggestions = [], dataContext = {}) =>
-    format(value, usageSuggestions, dataContext) as any
+  formatter.format = (value, suggestions = [], dataContext = {}) =>
+    format(value, ensureFormatSuggestionIntegrity(suggestions), dataContext)
 
-  formatter.formatAsPrimitive = (value, usageSuggestions = [], dataContext = {}) =>
-    format(value, ["primitive", ...usageSuggestions], dataContext) as any
+  formatter.formatAsPrimitive = (value, suggestions = [], dataContext = {}) =>
+    format(
+      value,
+      ensureFormatAsPrimitiveSuggestionIntegrity(suggestions),
+      dataContext,
+    ) as TPrimitiveOutput
 
   formatter.wrap = <
     TNextInput,
     TNextOutput,
     TNextPrimitiveOutput,
-    TNextDataContext extends DataContext
+    TNextDataContext extends TDataContext
   >(
     nextFormat: FormatChainDefinition<
       TInput,
@@ -185,24 +190,24 @@ export const makeFormatter = <
     >,
     nextFormatterOptions?: FormatterOptions,
   ) => {
-    const nextFormatter: Formatter<
+    const nextFormatter = makeFormatter<
       TNextInput,
       TNextOutput,
       TNextPrimitiveOutput,
       TNextDataContext
-    > = makeFormatter((value, usageSuggestions, dataContext) => {
+    >((value, suggestions, dataContext) => {
       const delegate: FormatMethod<TInput, TOutput, TPrimitiveOutput, TDataContext> = (
         delegatedValue,
-        delegatedUsageSuggestions,
+        delegatedSuggestions,
         delegatedDataContext,
       ) =>
         formatter.format(
           delegatedValue,
-          delegatedUsageSuggestions ?? usageSuggestions,
-          (delegatedDataContext ?? dataContext) as any,
-        ) as any
+          delegatedSuggestions ?? suggestions,
+          delegatedDataContext ?? dataContext,
+        )
 
-      return nextFormat(delegate, value, usageSuggestions, dataContext) as any
+      return nextFormat(delegate, value, suggestions, dataContext)
     }, nextFormatterOptions ?? formatterOptions)
 
     nextFormatter.innerFormatter = formatter