afformative 0.6.0 → 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

@@ -2,33 +2,19 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-function _objectWithoutPropertiesLoose(source, excluded) {
-  if (source == null) return {};
-  var target = {};
-  var sourceKeys = Object.keys(source);
-  var key, i;
+var _toConsumableArray = require('@babel/runtime/helpers/toConsumableArray');
 
-  for (i = 0; i < sourceKeys.length; i++) {
-    key = sourceKeys[i];
-    if (excluded.indexOf(key) >= 0) continue;
-    target[key] = source[key];
-  }
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
-  return target;
-}
+var _toConsumableArray__default = /*#__PURE__*/_interopDefaultLegacy(_toConsumableArray);
 
-// 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> {
-//     <TSuggestion extends Suggestion>(
-//       value: TInput,
-//       usageSuggestions: TSuggestion[],
-//       dataContext: DataContext,
-//     ): 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.
@@ -37,50 +23,33 @@ function _objectWithoutPropertiesLoose(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 = _objectWithoutPropertiesLoose(_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 ? void 0 : formatterOptions.displayName;
+  formatter.displayName = formatterOptions === null || formatterOptions === void 0 ? void 0 : formatterOptions.displayName;
 
-  formatter.format = function (value, usageSuggestions, dataContext) {
-    if (usageSuggestions === void 0) {
-      usageSuggestions = [];
-    }
-
-    if (dataContext === void 0) {
-      dataContext = {};
-    }
-
-    return format(value, usageSuggestions, dataContext);
+  formatter.format = function (value) {
+    var suggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
+    var dataContext = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+    return format(value, ensureFormatSuggestionIntegrity(suggestions), dataContext);
   };
 
-  formatter.formatAsPrimitive = function (value, usageSuggestions, dataContext) {
-    if (usageSuggestions === void 0) {
-      usageSuggestions = [];
-    }
-
-    if (dataContext === void 0) {
-      dataContext = {};
-    }
-
-    return format(value, ["primitive"].concat(usageSuggestions), dataContext);
+  formatter.formatAsPrimitive = function (value) {
+    var suggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
+    var dataContext = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+    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,30 +1,12 @@
-function _objectWithoutPropertiesLoose(source, excluded) {
-  if (source == null) return {};
-  var target = {};
-  var sourceKeys = Object.keys(source);
-  var key, i;
+import _toConsumableArray from '@babel/runtime/helpers/esm/toConsumableArray';
 
-  for (i = 0; i < sourceKeys.length; i++) {
-    key = sourceKeys[i];
-    if (excluded.indexOf(key) >= 0) 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> {
-//     <TSuggestion extends Suggestion>(
-//       value: TInput,
-//       usageSuggestions: TSuggestion[],
-//       dataContext: DataContext,
-//     ): PrimitiveSuggestion extends TSuggestion ? TPrimitiveOutput : TOutput
-//   }
+var ensureFormatAsPrimitiveSuggestionIntegrity = function ensureFormatAsPrimitiveSuggestionIntegrity(suggestions) {
+  return suggestions.includes("primitive") ? suggestions : ["primitive"].concat(_toConsumableArray(suggestions));
+};
 
 /**
  * Creates a new formatter.
@@ -33,50 +15,33 @@ function _objectWithoutPropertiesLoose(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 = _objectWithoutPropertiesLoose(_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 ? void 0 : formatterOptions.displayName;
+  formatter.displayName = formatterOptions === null || formatterOptions === void 0 ? void 0 : formatterOptions.displayName;
 
-  formatter.format = function (value, usageSuggestions, dataContext) {
-    if (usageSuggestions === void 0) {
-      usageSuggestions = [];
-    }
-
-    if (dataContext === void 0) {
-      dataContext = {};
-    }
-
-    return format(value, usageSuggestions, dataContext);
+  formatter.format = function (value) {
+    var suggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
+    var dataContext = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+    return format(value, ensureFormatSuggestionIntegrity(suggestions), dataContext);
   };
 
-  formatter.formatAsPrimitive = function (value, usageSuggestions, dataContext) {
-    if (usageSuggestions === void 0) {
-      usageSuggestions = [];
-    }
-
-    if (dataContext === void 0) {
-      dataContext = {};
-    }
-
-    return format(value, ["primitive"].concat(usageSuggestions), dataContext);
+  formatter.formatAsPrimitive = function (value) {
+    var suggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
+    var dataContext = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+    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,35 +2,50 @@
 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';
-
-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];
+})(this, (function (exports) { 'use strict';
+
+function _arrayLikeToArray(arr, len) {
+  if (len == null || len > arr.length) len = arr.length;
+
+  for (var i = 0, arr2 = new Array(len); i < len; i++) {
+    arr2[i] = arr[i];
   }
 
-  return target;
+  return arr2;
+}
+
+function _arrayWithoutHoles(arr) {
+  if (Array.isArray(arr)) return _arrayLikeToArray(arr);
+}
+
+function _iterableToArray(iter) {
+  if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+
+function _unsupportedIterableToArray(o, minLen) {
+  if (!o) return;
+  if (typeof o === "string") return _arrayLikeToArray(o, minLen);
+  var n = Object.prototype.toString.call(o).slice(8, -1);
+  if (n === "Object" && o.constructor) n = o.constructor.name;
+  if (n === "Map" || n === "Set") return Array.from(o);
+  if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen);
+}
+
+function _nonIterableSpread() {
+  throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
 
-// 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> {
-//     <TSuggestion extends Suggestion>(
-//       value: TInput,
-//       usageSuggestions: TSuggestion[],
-//       dataContext: DataContext,
-//     ): PrimitiveSuggestion extends TSuggestion ? TPrimitiveOutput : TOutput
-//   }
+function _toConsumableArray(arr) {
+  return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread();
+}
+
+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.
@@ -39,50 +54,33 @@ function _objectWithoutPropertiesLoose(source, excluded) {
  * @param formatterOptions Additional options for the formatter.
  */
 var makeFormatter = function makeFormatter(format, formatterOptions) {
-  var formatter = function formatter(_ref) {
-    var _format;
+  var formatter = function formatter(props) {
+    var _format, _props$suggestions;
 
-    var children = _ref.children,
-        _ref$suggestions = _ref.suggestions,
-        suggestions = _ref$suggestions === void 0 ? [] : _ref$suggestions,
-        dataContext = _objectWithoutPropertiesLoose(_ref, ["children", "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 ? void 0 : formatterOptions.displayName;
-
-  formatter.format = function (value, usageSuggestions, dataContext) {
-    if (usageSuggestions === void 0) {
-      usageSuggestions = [];
-    }
-
-    if (dataContext === void 0) {
-      dataContext = {};
-    }
+  formatter.displayName = formatterOptions === null || formatterOptions === void 0 ? void 0 : formatterOptions.displayName;
 
-    return format(value, usageSuggestions, dataContext);
+  formatter.format = function (value) {
+    var suggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
+    var dataContext = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+    return format(value, ensureFormatSuggestionIntegrity(suggestions), dataContext);
   };
 
-  formatter.formatAsPrimitive = function (value, usageSuggestions, dataContext) {
-    if (usageSuggestions === void 0) {
-      usageSuggestions = [];
-    }
-
-    if (dataContext === void 0) {
-      dataContext = {};
-    }
-
-    return format(value, ["primitive"].concat(usageSuggestions), dataContext);
+  formatter.formatAsPrimitive = function (value) {
+    var suggestions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
+    var dataContext = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+    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;
@@ -95,4 +93,4 @@ exports.makeFormatter = makeFormatter;
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-})));
+}));

package/dist/afformative.umd.min.js

@@ -1 +1 @@
-!function(n,e){"object"==typeof exports&&"undefined"!=typeof module?e(exports):"function"==typeof define&&define.amd?define(["exports"],e):e((n="undefined"!=typeof globalThis?globalThis:n||self).Afformative={})}(this,(function(n){"use strict";n.makeFormatter=function n(e,t){var i=function(n){var t,i=n.children,r=n.suggestions,o=void 0===r?[]:r,u=function(n,e){if(null==n)return{};var t,i,r={},o=Object.keys(n);for(i=0;o.length>i;i++)0>e.indexOf(t=o[i])&&(r[t]=n[t]);return r}(n,["children","suggestions"]);return null!==(t=e(i,o,u))&&void 0!==t?t:null};return i.displayName=null==t?void 0:t.displayName,i.format=function(n,t,i){return void 0===t&&(t=[]),void 0===i&&(i={}),e(n,t,i)},i.formatAsPrimitive=function(n,t,i){return void 0===t&&(t=[]),void 0===i&&(i={}),e(n,["primitive"].concat(t),i)},i.wrap=function(e,r){var o=n((function(n,t,r){return e((function(n,e,o){return i.format(n,null!=e?e:t,null!=o?o:r)}),n,t,r)}),null!=r?r:t);return o.innerFormatter=i,o},i},Object.defineProperty(n,"__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/makeFormatter.d.ts

@@ -1,89 +1,90 @@
-declare type PrimitiveSuggestion = "primitive";
-declare type SemanticSuggestion = "abbreviated" | "icon" | "verbose";
-declare type Suggestion = PrimitiveSuggestion | SemanticSuggestion;
+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;
 }
-declare type DataContext = Record<string, any>;
-interface FormatDefinition<TInput, TOutput, TPrimitiveOutput> {
+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: DataContext): TOutput | TPrimitiveOutput;
+    dataContext: Partial<TDataContext>): TOutput | TPrimitiveOutput;
 }
-interface FormatMethod<TInput, TOutput, TPrimitiveOutput> {
-    <TSuggestion extends Suggestion>(
+interface FormatMethod<TInput, TOutput, TPrimitiveOutput, TDataContext extends DataContext> {
+    (
     /** 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?: DataContext): PrimitiveSuggestion extends TSuggestion ? TPrimitiveOutput : TOutput;
+    dataContext?: Partial<TDataContext>): TOutput | TPrimitiveOutput;
 }
-interface FormatAsPrimitiveMethod<TInput, TPrimitiveOutput> {
+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[], 
+    suggestions?: Suggestion[], 
     /** Additional data context the formatter might find useful. */
-    dataContext?: DataContext): TPrimitiveOutput;
+    dataContext?: Partial<TDataContext>): TPrimitiveOutput;
 }
-interface FormatChainDefinition<TInnerInput, TInnerOutput, TInnerPrimitiveInput, TOuterInput, TOuterOutput, TOuterPrimitiveOutput> {
+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>, 
+    delegate: FormatMethod<TInnerInput, TInnerOutput, TInnerPrimitiveInput, TInnerDataContext>, 
     /** 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: DataContext): TOuterOutput | TOuterPrimitiveOutput;
+    dataContext: Partial<TOuterDataContext>): TOuterOutput | TOuterPrimitiveOutput;
 }
-interface FormatterProps<TInput> {
+declare type FormatterProps<TInput, TDataContext extends DataContext> = {
     /** Value to format. */
     children: TInput;
     /** Suggestions the formatter should take note of. */
     suggestions?: Suggestion[];
-    /** Additional data context to be used by the formatter. */
-    [dataContextPropName: string]: any;
-}
-export interface Formatter<TInput, TOutput, TPrimitiveOutput = TOutput> {
+} & 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>;
+    format: FormatMethod<TInput, TOutput, TPrimitiveOutput, TDataContext>;
     /** Formats a value with the `primitive` suggestion. */
-    formatAsPrimitive: FormatAsPrimitiveMethod<TInput, TPrimitiveOutput>;
-    /** The callee of the `.wrap` method used to produce this formatter. */
-    innerFormatter?: Formatter<any, any, any>;
+    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>(
+    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, TNextInput, TNextOutput, TNextPrimitiveOutput>, 
+    nextFormat: FormatChainDefinition<TInput, TOutput, TPrimitiveOutput, TDataContext, TNextInput, TNextOutput, TNextPrimitiveOutput, TNextDataContext>, 
     /** New formatter options, replacing the original ones. */
-    nextFormatterOptions?: FormatterOptions) => Formatter<TNextInput, TNextOutput, TNextPrimitiveOutput>;
+    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.
+     * @deprecated Since v0.6.0. Prefer using the `format` method instead.
      */
-    (props: FormatterProps<TInput>): TOutput | TPrimitiveOutput | null;
+    (props: FormatterProps<TInput, TDataContext>): TOutput | TPrimitiveOutput | null;
 }
 /**
  * Creates a new formatter.
@@ -91,6 +92,6 @@ export interface Formatter<TInput, TOutput, TPrimitiveOutput = TOutput> {
  * @param format Function used to format the value.
  * @param formatterOptions Additional options for the formatter.
  */
-export declare const makeFormatter: <TInput, TOutput, TPrimitiveOutput = TOutput>(format: FormatDefinition<TInput, TOutput, TPrimitiveOutput>, formatterOptions?: FormatterOptions | undefined) => Formatter<TInput, TOutput, TPrimitiveOutput>;
+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.0",
+  "version": "0.6.3",
   "license": "MIT",
   "main": "dist/afformative.cjs.js",
   "module": "dist/afformative.esm.js",
@@ -27,9 +27,12 @@
   "contributors": [
     "Vaclav Jancarik <vaclav.janc@gmail.com>"
   ],
+  "dependencies": {
+    "@babel/runtime": "^7.12.1"
+  },
   "publishConfig": {
     "access": "public"
   },
   "sideEffects": false,
-  "gitHead": "b5ffb3e48e19a74b2ca89af2ad7a96becbe711e7"
+  "gitHead": "ddc8c8682e2777c730108466792b7670d8a43f06"
 }

package/src/makeFormatter.test.ts

@@ -2,111 +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()
+
+  afterEach(() => {
+    jest.clearAllMocks()
   })
 
-  it("accepts a `name` option", () => {
-    const formatter = makeFormatter<string, string>(toUpperCase, { displayName: "UpperFormatter" })
-    expect(formatter.displayName).toBe("UpperFormatter")
+  describe("displayName", () => {
+    it("accepts a `displayName` option", () => {
+      const displayName = "upperCaseFormatter"
+      const formatter = makeFormatter<string, string>(toUpperCase, { displayName })
+      expect(formatter.displayName).toBe(displayName)
+    })
   })
 
-  it("passes `suggestions` to `format`", () => {
-    const formatter = makeFormatter<string, string>((value, suggestions) => {
-      if (suggestions.includes("abbreviated")) {
-        return value[0]
-      }
+  describe("format", () => {
+    it("handles trivial formatting", () => {
+      expect(upperCaseFormatter.format("foo")).toBe("FOO")
+    })
 
-      return value
+    it("passes through non-empty suggestions", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.format("foo", ["abbreviated"])
+      expect(format.mock.calls[0][1]).toEqual(["abbreviated"])
     })
 
-    expect(formatter.format("foo", ["abbreviated"])).toBe("f")
-    expect(formatter.format("foo", [])).toBe("foo")
-    expect(formatter.format("foo")).toBe("foo")
-  })
+    it("passes through empty suggestions", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.format("foo", [])
+      expect(format.mock.calls[0][1]).toEqual([])
+    })
 
-  it("handles formatting with the `primitive` suggestion", () => {
-    type Structure = { value: string }
+    it("defaults suggestions to an empty array", () => {
+      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("passes through the `primitive` suggestion", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.format("foo", ["primitive"])
+      expect(format.mock.calls[0][1]).toEqual(["primitive"])
+    })
 
-      return value
+    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"])
     })
 
-    expect(formatter.format({ value: "foo" }, ["primitive"])).toBe("foo")
-    expect(formatter.formatAsPrimitive({ value: "foo" })).toBe("foo")
-    expect(formatter.formatAsPrimitive({ value: "foo" }, ["primitive"])).toBe("foo")
+    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"])
+    })
+
+    it("supports data context", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.format("foo", [], { foo: "bar" })
+      expect(format.mock.calls[0][2]).toEqual({ foo: "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", () => {
-    const formatter = makeFormatter<string, string>(toUpperCase)
+  describe("formatAsPrimitive", () => {
+    it("handles trivial formatting", () => {
+      expect(upperCaseFormatter.formatAsPrimitive("foo")).toBe("FOO")
+    })
 
-    const wrappedFormatter = formatter.wrap((delegate, value) =>
-      value === "foo" ? "override" : 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("override")
-    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("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"])
+    })
+
+    it("passes through the `primitive` suggestion", () => {
+      const formatter = makeFormatter<string, string>(format)
+      formatter.formatAsPrimitive("foo", ["primitive"])
+      expect(format.mock.calls[0][1]).toEqual(["primitive"])
+    })
 
-  it("supports simple behavior wrapping with suggestions", () => {
-    const formatter = makeFormatter<string, string>(toUpperCase)
+    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"])
+    })
 
-    const wrappedFormatter = formatter.wrap((delegate, value, suggestions) =>
-      value === "foo" && suggestions.includes("abbreviated") ? "f" : delegate(value),
-    )
+    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("foo")).toBe("FOO")
-    expect(wrappedFormatter.format("foo", ["abbreviated"])).toBe("f")
-    expect(wrappedFormatter.format("bar")).toBe("BAR")
+    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 the `primitive` suggestion", () => {
-    type Structure = { value: string }
+  describe("wrap", () => {
+    it("handles trivial wrapping", () => {
+      const formatter = makeFormatter<string, string>(format).wrap(() => "bar")
+      expect(formatter.format("foo")).toBe("bar")
+    })
 
-    const formatter = makeFormatter<string, string>(toUpperCase)
+    it("handles single-value mapping", () => {
+      const formatter = makeFormatter<string, string>(format).wrap((delegate, value) =>
+        value === "ping" ? "pong" : delegate(value),
+      )
 
-    const wrappedFormatter = formatter.wrap<Structure, Structure, string>(
-      (delegate, value, suggestions) => (suggestions.includes("primitive") ? value.value : value),
-    )
+      expect(formatter.format("ping")).toBe("pong")
+    })
 
-    expect(wrappedFormatter.format({ value: "foo" }, ["primitive"])).toBe("foo")
-    expect(wrappedFormatter.formatAsPrimitive({ value: "foo" })).toBe("foo")
-    expect(wrappedFormatter.formatAsPrimitive({ value: "foo" }, ["primitive"])).toBe("foo")
-  })
+    it("handles delegation to the original formatter", () => {
+      const formatter = upperCaseFormatter.wrap((delegate, value) =>
+        value === "ping" ? "pong" : delegate(value),
+      )
 
-  it("supports simple behavior wrapping with data context", () => {
-    const formatter = makeFormatter<string, string>(toUpperCase)
+      expect(formatter.format("foo")).toBe("FOO")
+    })
 
-    const wrappedFormatter = formatter.wrap(
-      (delegate, value, suggestions, { forcedValue }) => forcedValue ?? delegate(value),
-    )
+    it("sets the `innerFormatter` property", () => {
+      const wrappedFormatter = upperCaseFormatter.wrap((delegate, value) => delegate(value))
+      expect(wrappedFormatter.innerFormatter).toBe(upperCaseFormatter)
+    })
 
-    expect(wrappedFormatter.format("foo")).toBe("FOO")
-    expect(wrappedFormatter.format("foo", undefined, { forcedValue: "override" })).toBe("override")
-  })
+    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("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]
-      }
+    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")
+    })
 
-      return value
+    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 wrappedFormatter = formatter.wrap((delegate, value) => delegate(value))
-    expect(wrappedFormatter.format("foo", ["abbreviated"])).toBe("f")
-  })
+    it("supports modifying the input structure", () => {
+      const formatter = upperCaseFormatter.wrap<ValueRecord>((delegate, { value }) =>
+        delegate(value),
+      )
 
-  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)
+      expect(formatter.format({ value: "foo" })).toBe("FOO")
+    })
+
+    it("supports modifying the output structure", () => {
+      const formatter = upperCaseFormatter.wrap<ValueRecord, ValueRecord>(
+        (delegate, { value }) => ({ value: delegate(value) }),
+      )
+
+      expect(formatter.format({ value: "foo" })).toEqual({ value: "FOO" })
+    })
+
+    it("supports modifying the data context structure", () => {
+      interface ListContext {
+        row: string
+      }
+
+      const listFormatter = upperCaseFormatter.wrap<string, string, string, ListContext>(
+        (delegate, value, suggestions, { row }) => `${row}: ${delegate(value)}`,
+      )
+
+      interface GridContext extends ListContext {
+        column: string
+      }
+
+      expect(listFormatter.format("foo", [], { row: "A" })).toBe("A: FOO")
+
+      const gridFormatter = listFormatter.wrap<string, string, string, GridContext>(
+        (delegate, value, suggestions, { column }) => delegate(value).replace(":", `${column}:`),
+      )
+
+      expect(gridFormatter.format("foo", [], { row: "B", column: "1" })).toBe("B1: FOO")
+    })
   })
 })

package/src/makeFormatter.ts

@@ -1,57 +1,61 @@
-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> {
-//     <TSuggestion extends Suggestion>(
-//       value: TInput,
-//       usageSuggestions: TSuggestion[],
-//       dataContext: DataContext,
-//     ): PrimitiveSuggestion extends TSuggestion ? TPrimitiveOutput : TOutput
-//   }
-
-interface FormatDefinition<TInput, TOutput, TPrimitiveOutput> {
+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: DataContext,
+    dataContext: Partial<TDataContext>,
   ): TOutput | TPrimitiveOutput
 }
 
-interface FormatMethod<TInput, TOutput, TPrimitiveOutput> {
-  <TSuggestion extends Suggestion>(
+interface FormatMethod<TInput, TOutput, TPrimitiveOutput, TDataContext extends DataContext> {
+  (
     /** 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?: DataContext,
-  ): PrimitiveSuggestion extends TSuggestion ? TPrimitiveOutput : TOutput
+    dataContext?: Partial<TDataContext>,
+  ): TOutput | TPrimitiveOutput
 }
 
-interface FormatAsPrimitiveMethod<TInput, TPrimitiveOutput> {
+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[],
+    suggestions?: Suggestion[],
     /** Additional data context the formatter might find useful. */
-    dataContext?: DataContext,
+    dataContext?: Partial<TDataContext>,
   ): TPrimitiveOutput
 }
 
@@ -59,9 +63,11 @@ interface FormatChainDefinition<
   TInnerInput,
   TInnerOutput,
   TInnerPrimitiveInput,
+  TInnerDataContext extends DataContext,
   TOuterInput,
   TOuterOutput,
-  TOuterPrimitiveOutput
+  TOuterPrimitiveOutput,
+  TOuterDataContext extends DataContext
 > {
   (
     /**
@@ -69,39 +75,47 @@ interface FormatChainDefinition<
      * 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>,
+    delegate: FormatMethod<TInnerInput, TInnerOutput, TInnerPrimitiveInput, TInnerDataContext>,
     /** 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: DataContext,
+    dataContext: Partial<TOuterDataContext>,
   ): TOuterOutput | TOuterPrimitiveOutput
 }
 
-interface FormatterProps<TInput> {
+type FormatterProps<TInput, TDataContext extends DataContext> = {
   /** Value to format. */
   children: TInput
   /** Suggestions the formatter should take note of. */
   suggestions?: Suggestion[]
-  /** Additional data context to be used by the formatter. */
-  [dataContextPropName: string]: any
-}
+} & Partial<TDataContext>
 
-export interface Formatter<TInput, TOutput, TPrimitiveOutput = TOutput> {
+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>
+  format: FormatMethod<TInput, TOutput, TPrimitiveOutput, TDataContext>
   /** Formats a value with the `primitive` suggestion. */
-  formatAsPrimitive: FormatAsPrimitiveMethod<TInput, TPrimitiveOutput>
-  /** The callee of the `.wrap` method used to produce this formatter. */
-  innerFormatter?: Formatter<any, any, any>
+  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>(
+  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.
@@ -111,19 +125,21 @@ export interface Formatter<TInput, TOutput, TPrimitiveOutput = TOutput> {
       TInput,
       TOutput,
       TPrimitiveOutput,
+      TDataContext,
       TNextInput,
       TNextOutput,
-      TNextPrimitiveOutput
+      TNextPrimitiveOutput,
+      TNextDataContext
     >,
     /** New formatter options, replacing the original ones. */
     nextFormatterOptions?: FormatterOptions,
-  ) => Formatter<TNextInput, TNextOutput, TNextPrimitiveOutput>
+  ) => 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.
+   * @deprecated Since v0.6.0. Prefer using the `format` method instead.
    */
-  (props: FormatterProps<TInput>): TOutput | TPrimitiveOutput | null
+  (props: FormatterProps<TInput, TDataContext>): TOutput | TPrimitiveOutput | null
 }
 
 /**
@@ -132,52 +148,67 @@ export interface Formatter<TInput, TOutput, TPrimitiveOutput = TOutput> {
  * @param format Function used to format the value.
  * @param formatterOptions Additional options for the formatter.
  */
-export const makeFormatter = <TInput, TOutput, TPrimitiveOutput = TOutput>(
-  format: FormatDefinition<TInput, TOutput, TPrimitiveOutput>,
+export const makeFormatter = <
+  TInput,
+  TOutput,
+  TPrimitiveOutput = TOutput,
+  TDataContext extends DataContext = DataContext
+>(
+  format: FormatDefinition<TInput, TOutput, TPrimitiveOutput, TDataContext>,
   formatterOptions?: FormatterOptions,
-): Formatter<TInput, TOutput, TPrimitiveOutput> => {
-  const formatter: Formatter<TInput, TOutput, TPrimitiveOutput> = ({
-    children,
-    suggestions = [],
-    ...dataContext
-  }) => format(children, suggestions, dataContext) ?? null
+): Formatter<TInput, TOutput, TPrimitiveOutput, TDataContext> => {
+  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.formatAsPrimitive = (value, usageSuggestions = [], dataContext = {}) =>
-    format(value, ["primitive", ...usageSuggestions], dataContext) as any
-
-  formatter.wrap = <TNextInput, TNextOutput, TNextPrimitiveOutput>(
+  formatter.format = (value, suggestions = [], dataContext = {}) =>
+    format(value, ensureFormatSuggestionIntegrity(suggestions), dataContext)
+
+  formatter.formatAsPrimitive = (value, suggestions = [], dataContext = {}) =>
+    format(
+      value,
+      ensureFormatAsPrimitiveSuggestionIntegrity(suggestions),
+      dataContext,
+    ) as TPrimitiveOutput
+
+  formatter.wrap = <
+    TNextInput,
+    TNextOutput,
+    TNextPrimitiveOutput,
+    TNextDataContext extends TDataContext
+  >(
     nextFormat: FormatChainDefinition<
       TInput,
       TOutput,
       TPrimitiveOutput,
+      TDataContext,
       TNextInput,
       TNextOutput,
-      TNextPrimitiveOutput
+      TNextPrimitiveOutput,
+      TNextDataContext
     >,
     nextFormatterOptions?: FormatterOptions,
   ) => {
-    const nextFormatter: Formatter<TNextInput, TNextOutput, TNextPrimitiveOutput> = makeFormatter(
-      (value, usageSuggestions, dataContext) => {
-        const delegate: FormatMethod<TInput, TOutput, TPrimitiveOutput> = (
+    const nextFormatter = makeFormatter<
+      TNextInput,
+      TNextOutput,
+      TNextPrimitiveOutput,
+      TNextDataContext
+    >((value, suggestions, dataContext) => {
+      const delegate: FormatMethod<TInput, TOutput, TPrimitiveOutput, TDataContext> = (
+        delegatedValue,
+        delegatedSuggestions,
+        delegatedDataContext,
+      ) =>
+        formatter.format(
           delegatedValue,
-          delegatedUsageSuggestions,
-          delegatedDataContext,
-        ) =>
-          formatter.format(
-            delegatedValue,
-            delegatedUsageSuggestions ?? usageSuggestions,
-            delegatedDataContext ?? dataContext,
-          ) as any
-
-        return nextFormat(delegate, value, usageSuggestions, dataContext) as any
-      },
-      nextFormatterOptions ?? formatterOptions,
-    )
+          delegatedSuggestions ?? suggestions,
+          delegatedDataContext ?? dataContext,
+        )
+
+      return nextFormat(delegate, value, suggestions, dataContext)
+    }, nextFormatterOptions ?? formatterOptions)
 
     nextFormatter.innerFormatter = formatter