From a0e579b71909d3006fe75b37b8f7aa8c58691713 Mon Sep 17 00:00:00 2001
From: ChronicStone <55083156+ChronicStone@users.noreply.github.com>
Date: Mon, 29 Apr 2024 23:03:45 +0200
Subject: [PATCH] docs: document parametric cell formatter preset

---
 bun.lockb                                     | Bin 359371 -> 359371 bytes
 docs/.vitepress/config.ts                     |   3 +-
 docs/schema-builder/reusable-formatters.md    |  57 ++++++++++++++++++
 ...ansformers.md => reusable-transformers.md} |   5 +-
 package.json                                  |   2 +-
 test/play.test.ts                             |   8 +--
 6 files changed, 67 insertions(+), 8 deletions(-)
 create mode 100644 docs/schema-builder/reusable-formatters.md
 rename docs/schema-builder/{global-transformers.md => reusable-transformers.md} (85%)

diff --git a/bun.lockb b/bun.lockb
index 5d70a9ecea75f6ad116009f4514e851914b55ee1..b9b118e451b573843e7d780a47b2fb0f2f2e4421 100755
GIT binary patch
delta 156
zcmV;N0Av5l_Z7?c6_76<nm@3Vt@2J<0Su4*`L>#N4{gJYFGw+9U6=$Z;A--*PTKR6
zq&g^*&^ri&SoF78^Z^}QKv|k<&*R}QRThwjrqty{a#A}4^5^TJAPstrr^1$!)cDym
z_1Gn6H6RU6Gqk%>+xW|wPWO`FQU1Jpuw(r1_=mMn0=KnL11MAhG>6`#1GnC!1mvdy
KG`GV{1qd%ut4_)Q

delta 156
zcmV;N0Av5l_Z7?c6_76<e=nGhTcPwGA0Rn=I<`JbbjeO2TE=*HELDOnaI_P#PTKR6
zByK2^&^ri&SoF78^Z^}QKrN=H=WO_J-oub+T8nv{H<K6irAai74CN_%LlFEh&=Sv<
zvFmOZ3KlWMy{)Z@dqN~s!)K6evEKgQBbwW}Z-=!|0=KnL11MAhGl$-!1GnC!1mvdy
KGq=M`1qd%S;7C*e

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 1f7fcf4..633ab7c 100644
--- a/docs/.vitepress/config.ts
+++ b/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' },
         ],
       },
diff --git a/docs/schema-builder/reusable-formatters.md b/docs/schema-builder/reusable-formatters.md
new file mode 100644
index 0000000..80a3bea
--- /dev/null
+++ b/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()
+```
diff --git a/docs/schema-builder/global-transformers.md b/docs/schema-builder/reusable-transformers.md
similarity index 85%
rename from docs/schema-builder/global-transformers.md
rename to docs/schema-builder/reusable-transformers.md
index a0331f8..f02470c 100644
--- a/docs/schema-builder/global-transformers.md
+++ b/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
diff --git a/package.json b/package.json
index 6654276..195e202 100644
--- a/package.json
+++ b/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",
diff --git a/test/play.test.ts b/test/play.test.ts
index 3ed0675..2492c42 100644
--- a/test/play.test.ts
+++ b/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) => ({