docs: document parametric cell formatter preset

docs/.vitepress/config.ts

@@ -82,7 +82,8 @@ export default defineConfig({
           { text: 'Create schema', link: '/schema-builder/create-schema' },
           { text: 'Define columns', link: '/schema-builder/columns' },
           { text: 'Dynamic Columns', link: '/schema-builder/dynamic-columns' },
-          { text: 'Global Transformers', link: '/schema-builder/global-transformers' },
+          { text: 'Reusable Transformers', link: '/schema-builder/reusable-transformers' },
+          { text: 'Reusable Formatters', link: '/schema-builder/reusable-formatters' },
           { text: 'Build Schema', link: '/schema-builder/build-schema' },
         ],
       },

docs/schema-builder/reusable-formatters.md

@@ -0,0 +1,57 @@
+## Reusable formatters
+
+Reusable formatters are excel cell formats that can be registered when creating a schema builder, and used as presets in the `format` property of a column.
+
+```ts twoslash
+// @noErrors
+import { ExcelSchemaBuilder } from '@chronicstone/typed-xlsx'
+// ---cut-before---
+const schema = ExcelSchemaBuilder.create<{ name: string, date: Date, balance: number, currency: 'EUR' | 'USD' }>()
+  .withFormatters({
+    date: 'd mmm yyyy',
+    currency: (params: { currency: 'EUR' | 'USD' }) => `${params.currency === 'EUR' ? '€' : '$'}#,##0.00`,
+  })
+  .column('name', { key: 'name' })
+  .column('date', { key: 'date', format: { preset: 'date' } })
+  .column('balance', {
+    key: 'balance',
+    format: {
+      preset: 'currency',
+      params: { currency: '' }
+//                         ^|
+    }
+  })
+
+  .build()
+```
+
+As shown in the example above, formatters preset can either be static strings, or accept an object argument that can be used to pass parameters to the formatter function. Presets can be applied statically for all rows on a column, or controlled individually for each row
+
+When defining a dynamic format preset, you need to strongly type the params argument so that it can be enforced when the preset is used on columns.
+
+## Share formatters across schemas
+
+You can define formatters externally and then use them on any table schema you want :
+
+```ts twoslash
+// @noErrors
+import { ExcelSchemaBuilder, FormattersMap } from '@chronicstone/typed-xlsx'
+
+const formatters = {
+  date: 'd mmm yyyy',
+  currency: (params: { currency: string }) => `${params.currency}#,##0.00`,
+} satisfies FormattersMap
+
+const schema = ExcelSchemaBuilder.create<{ name: string, date: Date, balance: number, currency: 'EUR' | 'USD' }>()
+  .withFormatters(formatters)
+  .column('name', { key: 'name' })
+  .column('date', { key: 'date', format: { preset: 'date' } })
+  .column('balance', {
+    key: 'balance',
+    format: {
+      preset: 'currency',
+      params: { currency: '$' }
+    }
+  })
+  .build()
+```

docs/schema-builder/global-transformers.md → docs/schema-builder/reusable-transformers.md

@@ -1,5 +1,6 @@
-# Shared transformers
-Global transformers are functions that can be registered when creating a schema builder. They can then be used to transform values with the `transform` property of a column, simply by referencing the function name.
+# Reusable transformers
+
+Reusable transformers are functions that can be registered when creating a schema builder. They can then be used to transform values with the `transform` property of a column, simply by referencing the function name.
 
 ```ts twoslash
 // @noErrors

package.json

@@ -57,7 +57,7 @@
     "@antfu/eslint-config": "^2.1.2",
     "@antfu/ni": "^0.21.12",
     "@antfu/utils": "^0.7.6",
-    "@chronicstone/typed-xlsx": "0.2.13",
+    "@chronicstone/typed-xlsx": "0.2.14",
     "@faker-js/faker": "^8.3.1",
     "@shikijs/vitepress-twoslash": "^1.3.0",
     "@types/node": "^20.12.7",

test/play.test.ts

@@ -11,8 +11,8 @@ describe('should generate the play excel file', () => {
     const schema = ExcelSchemaBuilder.create<User>()
       .withFormatters({
         date: 'd mmm yyyy',
-        currency: (params: { currency: string }) => `${params.currency}#,##0.00`,
-        other: (params: { other: string }) => `${params.other}#,##0.00`,
+        currency: (params: { currency: 'EUR' | 'USD' }) => `${params.currency}#,##0.00`,
+        other: (params: { other: string }) => `${params.other === 'EUR' ? '€' : '$'}#,##0.00`,
       })
       .column('id', { key: 'id' })
       .column('name', {
@@ -22,8 +22,8 @@ describe('should generate the play excel file', () => {
       })
       .column('birthDate', { key: 'birthDate', format: { preset: 'date' } })
       .column('birthDate2', { key: 'birthDate', format: 'd mmm yyyy' })
-      .column('balanceUsd', { key: 'balance', format: { preset: 'currency', params: { currency: '$' } } })
-      .column('balanceEur', { key: 'balance', format: { preset: 'currency', params: { currency: '€' } } })
+      .column('balanceUsd', { key: 'balance', format: { preset: 'currency', params: { currency: 'EUR' } } })
+      .column('balanceEur', { key: 'balance', format: { preset: 'currency', params: { currency: 'USD' } } })
       .build()
 
     const users: User[] = Array.from({ length: 100000 }, (_, i) => ({