@qrvey/formula-lang 3.2.0-rc.1078 → 3.2.0-rc.1101

package/QRVEY-DATE-PRESETS.md

@@ -12,7 +12,7 @@ The API does not change the main grammar. It uses regular Formula Lang functions
 
 ## Public API
 
-The main APIs are in `src/date-presets.ts` and are exported from `src/index.ts`.
+The main APIs are in `src/date-presets/date-presets.ts` and are exported from `src/index.ts`.
 
 ```ts
 TranspileDatePreset(program: string, context?: FormulaContext): DatePresetTranspilationResponse | undefined
@@ -48,8 +48,8 @@ type DatePresetValue = string | DateRangeValue | PartialDateValue;
 
 ```json
 {
-  "start": "2026-07-01T00:00:00.000Z",
-  "end": "2026-07-31T23:59:59.999Z"
+    "start": "2026-07-01T00:00:00.000Z",
+    "end": "2026-07-31T23:59:59.999Z"
 }
 ```
 
@@ -57,31 +57,31 @@ type DatePresetValue = string | DateRangeValue | PartialDateValue;
 
 ```json
 {
-  "month": 4,
-  "day": 15
+    "month": 4,
+    "day": 15
 }
 ```
 
 Supported fields for `partialDate`:
 
-| Field | Meaning | Range |
-| --- | --- | --- |
-| `year` | Specific year | Integer |
-| `month` | Month | 1-12 |
-| `quarter` | Quarter | 1-4 |
-| `week` | Week | 1-54 |
-| `day` | Day of month | 1-31 |
+| Field     | Meaning       | Range   |
+| --------- | ------------- | ------- |
+| `year`    | Specific year | Integer |
+| `month`   | Month         | 1-12    |
+| `quarter` | Quarter       | 1-4     |
+| `week`    | Week          | 1-54    |
+| `day`     | Day of month  | 1-31    |
 
 ## Value Types
 
 `TranspileDatePreset` returns `valueType` to describe the nature of the value.
 
-| Value type | Meaning | Examples |
-| --- | --- | --- |
-| `fixed` | Fixed value or materialized range | `DATE("2026-07-20")`, `DATE_RANGE(...)` |
-| `recurring` | Partial pattern that repeats | `PARTIAL_DATE("ANY", 4)`, `PARTIAL_DATE("ANY", 4, "ANY", "ANY", 15)` |
-| `relative` | Period relative to the calendar or positioned inside a period | `CALENDAR_PERIOD("MONTH", 0)`, `PERIOD_AT("MONTH", 4, 2026)` |
-| `rolling` | Moving window from an anchor | `RELATIVE_PERIOD(-29, "DAY")` |
+| Value type  | Meaning                                                       | Examples                                                             |
+| ----------- | ------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `fixed`     | Fixed value or materialized range                             | `DATE("2026-07-20")`, `DATE_RANGE(...)`                              |
+| `recurring` | Partial pattern that repeats                                  | `PARTIAL_DATE("ANY", 4)`, `PARTIAL_DATE("ANY", 4, "ANY", "ANY", 15)` |
+| `relative`  | Period relative to the calendar or positioned inside a period | `CALENDAR_PERIOD("MONTH", 0)`, `PERIOD_AT("MONTH", 4, 2026)`         |
+| `rolling`   | Moving window from an anchor                                  | `RELATIVE_PERIOD(-29, "DAY")`                                        |
 
 Current note: `PERIOD_AT("MONTH", 4, 2026)` produces a concrete range, but it is classified as `relative` because the root expression is `PERIOD_AT`. If the business goal requires distinguishing `April 2026` as `fixed`, that would be a classification improvement, not a resolution change.
 
@@ -91,34 +91,37 @@ QDP functions can receive `FormulaContext` with date preset configuration:
 
 ```ts
 {
-  datePreset: {
-    calendar: 'gregorian',
-    timezone: 'UTC',
-    locale: 'en-US',
-    fiscalYearStartMonth: 1,
-    fiscalYearStartDay: 1,
-    weekStartsOn: 0
-  }
+    timezone: { timeZone: "America/Bogota" },
+    datePreset: {
+        calendar: "gregorian",
+        locale: "en-US",
+        fiscalYearStartMonth: 1,
+        fiscalYearStartDay: 1,
+        weekStartsOn: 0,
+    },
 }
 ```
 
 Current defaults:
 
-| Option | Default | Notes |
-| --- | --- | --- |
-| `calendar` | `gregorian` | Also supports `corporate-fiscal`, `retail-4-4-5`, `retail-4-5-4` |
-| `timezone` | `UTC` | Affects day starts/ends and periods |
-| `locale` | `en-US` | Used by formatting options |
-| `fiscalYearStartMonth` | `1` | Clamped to 1-12 |
-| `fiscalYearStartDay` | `1` | Clamped to 1-31 and adjusted to the last valid day of the month |
-| `weekStartsOn` | `0` | Sunday. Accepts 0-6 or English weekday names |
+| Option                 | Default     | Notes                                                                                                        |
+| ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
+| `timezone.offset`      | `+00:00`    | Supports `default`, `browser`, or custom offsets such as `UTC-5`, `-05:00`, `+5:30`                          |
+| `timezone.timeZone`    | none        | Optional IANA time zone identifier such as `America/Bogota`; when present it is used for calendar resolution |
+| `calendar`             | `gregorian` | Also supports `corporate-fiscal`, `retail-4-4-5`, `retail-4-5-4`                                             |
+| `locale`               | `en-US`     | Used by formatting options                                                                                   |
+| `fiscalYearStartMonth` | `1`         | Clamped to 1-12                                                                                              |
+| `fiscalYearStartDay`   | `1`         | Clamped to 1-31 and adjusted to the last valid day of the month                                              |
+| `weekStartsOn`         | `0`         | Sunday. Accepts 0-6 or English weekday names                                                                 |
+
+Use `timezone.timeZone` for IANA identifiers. Use `timezone.offset` for admin/default/browser/custom offset values such as `{ offset: "default" }`, `{ offset: "browser" }`, or `{ offset: "-05:00" }`.
 
 Current week convention:
 
-- The default is Sunday (`weekStartsOn: 0`).
-- Week 1 of a year starts on the Sunday on or before Jan 1.
-- Some years can have W54 under this convention.
-- `PERIOD_AT("WEEK", "LAST", year)` is preferred for representing the last week of the year because it avoids hardcoding 52, 53, or 54.
+-   The default is Sunday (`weekStartsOn: 0`).
+-   Week 1 of a year starts on the Sunday on or before Jan 1.
+-   Some years can have W54 under this convention.
+-   `PERIOD_AT("WEEK", "LAST", year)` is preferred for representing the last week of the year because it avoids hardcoding 52, 53, or 54.
 
 ## QDP Date Preset Functions
 
@@ -127,7 +130,7 @@ Current week convention:
 Returns the current timestamp.
 
 ```ts
-NOW()
+NOW();
 // 2026-07-22T23:42:50.413Z
 ```
 
@@ -140,7 +143,7 @@ Value type when used as the final result: `fixed`.
 Returns the start of the current day in the context timezone.
 
 ```ts
-TODAY()
+TODAY();
 // 2026-07-22T00:00:00.000Z
 ```
 
@@ -153,30 +156,30 @@ Value type when used as the final result: `fixed`.
 Normalizes an ISO date or ISO date-time string to UTC ISO.
 
 ```ts
-DATE("2026-07-20")
+DATE("2026-07-20");
 // 2026-07-20T00:00:00.000Z
 ```
 
 Supported input formats:
 
-| Input | Example | Resolved value |
-| --- | --- | --- |
-| ISO date | `DATE("2026-07-08")` | `2026-07-08T00:00:00.000Z` |
-| ISO date-time without timezone | `DATE("2026-07-08T15:30")` | `2026-07-08T15:30:00.000Z` |
-| ISO date-time with UTC timezone | `DATE("2026-07-08T15:30:45Z")` | `2026-07-08T15:30:45.000Z` |
+| Input                              | Example                             | Resolved value             |
+| ---------------------------------- | ----------------------------------- | -------------------------- |
+| ISO date                           | `DATE("2026-07-08")`                | `2026-07-08T00:00:00.000Z` |
+| ISO date-time without timezone     | `DATE("2026-07-08T15:30")`          | `2026-07-08T15:30:00.000Z` |
+| ISO date-time with UTC timezone    | `DATE("2026-07-08T15:30:45Z")`      | `2026-07-08T15:30:45.000Z` |
 | ISO date-time with offset timezone | `DATE("2026-07-08T15:30:45-05:00")` | `2026-07-08T20:30:45.000Z` |
 
 Parameters:
 
-| Parameter | Type | Required | Validation |
-| --- | --- | --- | --- |
-| `VALUE` | `string` | Yes | ISO date or ISO date-time |
+| Parameter | Type     | Required | Validation                |
+| --------- | -------- | -------- | ------------------------- |
+| `VALUE`   | `string` | Yes      | ISO date or ISO date-time |
 
 Rules:
 
-- `DATE("2026-07-08")` is valid and resolves to `2026-07-08T00:00:00.000Z`.
-- Calendrically invalid dates, such as `DATE("2026-02-31T00:00")`, are rejected.
-- If the string does not include a timezone, UTC is assumed.
+-   `DATE("2026-07-08")` is valid and resolves to `2026-07-08T00:00:00.000Z`.
+-   Calendrically invalid dates, such as `DATE("2026-02-31T00:00")`, are rejected.
+-   If the string does not include a timezone, UTC is assumed.
 
 Output: `date`.
 
@@ -187,24 +190,21 @@ Value type: `fixed`.
 Builds a range between two dates.
 
 ```ts
-DATE_RANGE(
-  DATE("2026-07-20"),
-  END_OF(DATE("2026-07-25"))
-)
+DATE_RANGE(DATE("2026-07-20"), END_OF(DATE("2026-07-25")));
 // { start: "2026-07-20T00:00:00.000Z", end: "2026-07-25T23:59:59.999Z" }
 ```
 
 Parameters:
 
-| Parameter | Type | Required |
-| --- | --- | --- |
-| `START` | `date` | Yes |
-| `END` | `date` | Yes |
+| Parameter | Type   | Required |
+| --------- | ------ | -------- |
+| `START`   | `date` | Yes      |
+| `END`     | `date` | Yes      |
 
 Rules:
 
-- `END` must be greater than or equal to `START`.
-- If `END < START`, the function returns `INVALID_DATE_RANGE`.
+-   `END` must be greater than or equal to `START`.
+-   If `END < START`, the function returns `INVALID_DATE_RANGE`.
 
 Output: `dateRange`.
 
@@ -215,28 +215,28 @@ Value type: `fixed`.
 Creates a moving window relative to an anchor. If no anchor is passed, it uses `TODAY()`.
 
 ```ts
-RELATIVE_PERIOD(-29, "DAY")
+RELATIVE_PERIOD(-29, "DAY");
 // { start: "2026-06-23T00:00:00.000Z", end: "2026-07-22T23:59:59.999Z" }
 ```
 
 Parameters:
 
-| Parameter | Type | Required | Values |
-| --- | --- | --- | --- |
-| `OFFSET` | Integer `number` | Yes | Negative, zero, or positive |
-| `UNIT` | `string` | Yes | `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR` |
-| `ANCHOR` | `date` | No | Base date |
+| Parameter | Type             | Required | Values                                    |
+| --------- | ---------------- | -------- | ----------------------------------------- |
+| `OFFSET`  | Integer `number` | Yes      | Negative, zero, or positive               |
+| `UNIT`    | `string`         | Yes      | `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR` |
+| `ANCHOR`  | `date`           | No       | Base date                                 |
 
 Semantics:
 
-- Negative offset: from `anchor + offset` to the end of the anchor day.
-- Positive offset: from the start of the anchor day to `anchor + offset`.
-- It is rolling and not necessarily aligned to calendar boundaries.
+-   Negative offset: from `anchor + offset` to the end of the anchor day.
+-   Positive offset: from the start of the anchor day to `anchor + offset`.
+-   It is rolling and not necessarily aligned to calendar boundaries.
 
 Examples:
 
 ```ts
-RELATIVE_PERIOD(-2, "WEEK", DATE("2026-07-08T15:30"))
+RELATIVE_PERIOD(-2, "WEEK", DATE("2026-07-08T15:30"));
 // 2026-06-24T00:00:00.000Z -> 2026-07-08T23:59:59.999Z
 ```
 
@@ -249,31 +249,31 @@ Value type: `rolling`.
 Returns a complete calendar period containing the current day, shifted by `offset`.
 
 ```ts
-CALENDAR_PERIOD("MONTH", 0)
+CALENDAR_PERIOD("MONTH", 0);
 // 2026-07-01T00:00:00.000Z -> 2026-07-31T23:59:59.999Z
 ```
 
 Parameters:
 
-| Parameter | Type | Required | Values |
-| --- | --- | --- | --- |
-| `PERIOD` | `string` | Yes | `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR` |
-| `OFFSET` | Integer `number` | No | Default `0` |
+| Parameter | Type             | Required | Values                                    |
+| --------- | ---------------- | -------- | ----------------------------------------- |
+| `PERIOD`  | `string`         | Yes      | `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR` |
+| `OFFSET`  | Integer `number` | No       | Default `0`                               |
 
 Semantics:
 
-- `0` means the current period.
-- `-1` means the previous period.
-- `1` means the next period.
-- Respects calendar boundaries, timezone, fiscal calendar, and week start from the context.
+-   `0` means the current period.
+-   `-1` means the previous period.
+-   `1` means the next period.
+-   Respects calendar boundaries, timezone, fiscal calendar, and week start from the context.
 
 Examples:
 
 ```ts
-CALENDAR_PERIOD("WEEK", 0)
+CALENDAR_PERIOD("WEEK", 0);
 // with weekStartsOn Sunday: 2026-07-19T00:00:00.000Z -> 2026-07-25T23:59:59.999Z
 
-CALENDAR_PERIOD("QUARTER", -1)
+CALENDAR_PERIOD("QUARTER", -1);
 // 2026-04-01T00:00:00.000Z -> 2026-06-30T23:59:59.999Z
 ```
 
@@ -286,37 +286,37 @@ Value type: `relative`.
 Returns the period located at a position inside a year. If `year` is not passed, it uses the current year from the context.
 
 ```ts
-PERIOD_AT("MONTH", 4, 2026)
+PERIOD_AT("MONTH", 4, 2026);
 // 2026-04-01T00:00:00.000Z -> 2026-04-30T23:59:59.999Z
 ```
 
 Parameters:
 
-| Parameter | Type | Required | Values |
-| --- | --- | --- | --- |
-| `PERIOD` | `string` | Yes | `DAY`, `WEEK`, `MONTH`, `QUARTER` |
-| `POSITION` | Integer `number` or `string` | Yes | Number, `FIRST`, `LAST` |
-| `YEAR` | Integer `number` | No | Default: current year |
+| Parameter  | Type                         | Required | Values                            |
+| ---------- | ---------------------------- | -------- | --------------------------------- |
+| `PERIOD`   | `string`                     | Yes      | `DAY`, `WEEK`, `MONTH`, `QUARTER` |
+| `POSITION` | Integer `number` or `string` | Yes      | Number, `FIRST`, `LAST`           |
+| `YEAR`     | Integer `number`             | No       | Default: current year             |
 
 Examples:
 
 ```ts
-PERIOD_AT("QUARTER", 2, 2026)
+PERIOD_AT("QUARTER", 2, 2026);
 // 2026-04-01T00:00:00.000Z -> 2026-06-30T23:59:59.999Z
 
-PERIOD_AT("MONTH", "LAST", 2025)
+PERIOD_AT("MONTH", "LAST", 2025);
 // 2025-12-01T00:00:00.000Z -> 2025-12-31T23:59:59.999Z
 
-PERIOD_AT("WEEK", "LAST", 2028)
+PERIOD_AT("WEEK", "LAST", 2028);
 // 2028-12-31T00:00:00.000Z -> 2029-01-06T23:59:59.999Z
 ```
 
 Week rules:
 
-- For `WEEK`, the start of the year is anchored to the start of the week that falls on or before the start of the year.
-- The last week can cross into the next year.
-- Numeric `POSITION` does not force an error if it points to a computable range outside the nominal year. For example, W54 can resolve by shifting even when the year does not nominally have W54.
-- `"MIDDLE"` and other strings different from `FIRST` or `LAST` are invalid.
+-   For `WEEK`, the start of the year is anchored to the start of the week that falls on or before the start of the year.
+-   The last week can cross into the next year.
+-   Numeric `POSITION` does not force an error if it points to a computable range outside the nominal year. For example, W54 can resolve by shifting even when the year does not nominally have W54.
+-   `"MIDDLE"` and other strings different from `FIRST` or `LAST` are invalid.
 
 Output: `dateRange`.
 
@@ -327,71 +327,71 @@ Current value type: `relative`.
 Represents a partial or recurring date. Each field can be a number or `"ANY"`. Omitted fields are treated as `ANY`.
 
 ```ts
-PARTIAL_DATE("ANY", 4, "ANY", "ANY", 15)
+PARTIAL_DATE("ANY", 4, "ANY", "ANY", 15);
 // { month: 4, day: 15 }
 ```
 
 Parameters:
 
-| Position | Field | Range | Example |
-| --- | --- | --- | --- |
-| 1 | `YEAR` | Integer or `ANY` | `2026` |
-| 2 | `MONTH` | 1-12 or `ANY` | `4` |
-| 3 | `QUARTER` | 1-4 or `ANY` | `2` |
-| 4 | `WEEK` | 1-54 or `ANY` | `40` |
-| 5 | `DAY` | 1-31 or `ANY` | `15` |
+| Position | Field     | Range            | Example |
+| -------- | --------- | ---------------- | ------- |
+| 1        | `YEAR`    | Integer or `ANY` | `2026`  |
+| 2        | `MONTH`   | 1-12 or `ANY`    | `4`     |
+| 3        | `QUARTER` | 1-4 or `ANY`     | `2`     |
+| 4        | `WEEK`    | 1-54 or `ANY`    | `40`    |
+| 5        | `DAY`     | 1-31 or `ANY`    | `15`    |
 
 Date picker examples:
 
 ```ts
-PARTIAL_DATE()
+PARTIAL_DATE();
 // {}
 // Short format: Any date
 
-PARTIAL_DATE("ANY", 4)
+PARTIAL_DATE("ANY", 4);
 // { month: 4 }
 // Short format: Apr
 
-PARTIAL_DATE("ANY", 4, "ANY", "ANY", 15)
+PARTIAL_DATE("ANY", 4, "ANY", "ANY", 15);
 // { month: 4, day: 15 }
 // Short format: Apr 15
 
-PARTIAL_DATE("ANY", "ANY", 2)
+PARTIAL_DATE("ANY", "ANY", 2);
 // { quarter: 2 }
 // Short format: Q2
 
-PARTIAL_DATE("ANY", "ANY", "ANY", 40)
+PARTIAL_DATE("ANY", "ANY", "ANY", 40);
 // { week: 40 }
 // Short format: W40
 
-PARTIAL_DATE("ANY", "ANY", "ANY", "ANY", 15)
+PARTIAL_DATE("ANY", "ANY", "ANY", "ANY", 15);
 // { day: 15 }
 // Short format: Day 15
 ```
 
 Value type:
 
-- `fixed` if it includes `year`, `month`, and `day`, without `week`.
-- `relative` if it includes `week`.
-- `recurring` for all other partial dates.
+-   `fixed` if it includes `year`, `month`, and `day`, without `week`.
+-   `relative` if it includes `week`.
+-   `recurring` for all other partial dates.
 
 ### `START_OF(value)`
 
 Returns the start of a `date` or the `start` of a `dateRange`.
 
 ```ts
-START_OF(DATE("2026-07-08T15:30"))
+START_OF(DATE("2026-07-08T15:30"));
 // 2026-07-08T00:00:00.000Z
 
-START_OF(CALENDAR_PERIOD("MONTH", -1))
+START_OF(CALENDAR_PERIOD("MONTH", -1));
 // 2026-06-01T00:00:00.000Z
 ```
 
 Parameter:
 
-| Parameter | Type |
-| --- | --- |
-| `VALUE` | `date` or `dateRange` |
+| Parameter | Type                  |
+| --------- | --------------------- |
+| `VALUE`   | `date` or `dateRange` |
 
 Output: `date`.
 
@@ -402,18 +402,18 @@ Value type when used as root: `relative`.
 Returns the end of a `date` or the `end` of a `dateRange`.
 
 ```ts
-END_OF(DATE("2026-07-08T15:30"))
+END_OF(DATE("2026-07-08T15:30"));
 // 2026-07-08T23:59:59.999Z
 
-END_OF(CALENDAR_PERIOD("YEAR", -1))
+END_OF(CALENDAR_PERIOD("YEAR", -1));
 // 2025-12-31T23:59:59.999Z
 ```
 
 Parameter:
 
-| Parameter | Type |
-| --- | --- |
-| `VALUE` | `date` or `dateRange` |
+| Parameter | Type                  |
+| --------- | --------------------- |
+| `VALUE`   | `date` or `dateRange` |
 
 Output: `date`.
 
@@ -424,55 +424,55 @@ Value type when used as root: `relative`.
 Extracts one part of a date.
 
 ```ts
-PART(DATE("2026-07-08T15:30"), "DAY_OF_WEEK_NAME")
+PART(DATE("2026-07-08T15:30"), "DAY_OF_WEEK_NAME");
 // Wednesday
 ```
 
 Parameters:
 
-| Parameter | Type | Values |
-| --- | --- | --- |
-| `DATE` | `date` | Resolved ISO date |
-| `PART` | `string` | See the table below |
+| Parameter | Type     | Values              |
+| --------- | -------- | ------------------- |
+| `DATE`    | `date`   | Resolved ISO date   |
+| `PART`    | `string` | See the table below |
 
 Supported parts:
 
-| Value | Output |
-| --- | --- |
-| `YEAR` | UTC year |
-| `QUARTER` | Quarter 1-4 |
-| `MONTH` | Month 1-12 |
-| `MONTH_NAME` | English month name |
-| `DAY` | Day of month |
-| `DAY_OF_MONTH` | Day of month |
-| `DAY_OF_WEEK` | UTC weekday, Sunday = 0 |
-| `DAY_OF_WEEK_NAME` | English weekday name |
-| `DAY_OF_YEAR` | Day of year |
-| `WEEK_OF_YEAR` | Week according to the current convention |
-| `HOUR` | UTC hour |
-| `MINUTE` | UTC minute |
-| `SECOND` | UTC second |
+| Value              | Output                                   |
+| ------------------ | ---------------------------------------- |
+| `YEAR`             | UTC year                                 |
+| `QUARTER`          | Quarter 1-4                              |
+| `MONTH`            | Month 1-12                               |
+| `MONTH_NAME`       | English month name                       |
+| `DAY`              | Day of month                             |
+| `DAY_OF_MONTH`     | Day of month                             |
+| `DAY_OF_WEEK`      | UTC weekday, Sunday = 0                  |
+| `DAY_OF_WEEK_NAME` | English weekday name                     |
+| `DAY_OF_YEAR`      | Day of year                              |
+| `WEEK_OF_YEAR`     | Week according to the current convention |
+| `HOUR`             | UTC hour                                 |
+| `MINUTE`           | UTC minute                               |
+| `SECOND`           | UTC second                               |
 
 Important: `PART` is available as a QDP function, but it is not a valid final result for `TranspileDatePreset` because it returns `string`. It can be used as a helper function when accessing the QDP transpiler directly, but a final date preset expression must return `date`, `dateRange`, or `partialDate`.
 
 ## Differences Between Period Functions
 
-| Function | Question it answers | Example | Type |
-| --- | --- | --- | --- |
-| `CALENDAR_PERIOD` | What is this/previous/next calendar period? | This month, last week | `relative` |
-| `PERIOD_AT` | What is period N inside a year? | April 2026, Q2 2026, W40 2026 | Current `relative` |
-| `RELATIVE_PERIOD` | What is the moving window from today/anchor? | Last 30 days | `rolling` |
+| Function          | Question it answers                          | Example                       | Type               |
+| ----------------- | -------------------------------------------- | ----------------------------- | ------------------ |
+| `CALENDAR_PERIOD` | What is this/previous/next calendar period?  | This month, last week         | `relative`         |
+| `PERIOD_AT`       | What is period N inside a year?              | April 2026, Q2 2026, W40 2026 | Current `relative` |
+| `RELATIVE_PERIOD` | What is the moving window from today/anchor? | Last 30 days                  | `rolling`          |
 
 Examples with current date `2026-07-22`:
 
 ```ts
-CALENDAR_PERIOD("MONTH", -1)
+CALENDAR_PERIOD("MONTH", -1);
 // previous calendar month: Jun 1 -> Jun 30
 
-PERIOD_AT("MONTH", 4, 2026)
+PERIOD_AT("MONTH", 4, 2026);
 // fourth month of 2026: Apr 1 -> Apr 30
 
-RELATIVE_PERIOD(-29, "DAY")
+RELATIVE_PERIOD(-29, "DAY");
 // last 30 days inclusive: Jun 23 -> Jul 22
 ```
 
@@ -485,27 +485,27 @@ It is not recommended to merge them into a single public function because they e
 ### Expression Nodes
 
 ```ts
-{ type: 'NOW' }
-{ type: 'TODAY' }
-{ type: 'DATE', value: '2026-07-20' }
-{ type: 'DATE_RANGE', start: DatePresetJSON, end: DatePresetJSON }
-{ type: 'PARTIAL_DATE', value: { year?, quarter?, month?, week?, day? } }
-{ type: 'RELATIVE_PERIOD', offset: -30, unit: 'DAY', anchor?: DatePresetJSON }
-{ type: 'CALENDAR_PERIOD', period: 'MONTH', offset?: 0 }
-{ type: 'PERIOD_AT', period: 'MONTH', position: 4 | 'FIRST' | 'LAST', year?: 2026 }
-{ type: 'START_OF', input: DatePresetJSON }
-{ type: 'END_OF', input: DatePresetJSON }
+{ type: "NOW" }
+{ type: "TODAY" }
+{ type: "DATE", value: "2026-07-20" }
+{ type: "DATE_RANGE", start: DatePresetJSON, end: DatePresetJSON }
+{ type: "PARTIAL_DATE", value: { year?, quarter?, month?, week?, day? } }
+{ type: "RELATIVE_PERIOD", offset: -30, unit: "DAY", anchor?: DatePresetJSON }
+{ type: "CALENDAR_PERIOD", period: "MONTH", offset?: 0 }
+{ type: "PERIOD_AT", period: "MONTH", position: 4 | "FIRST" | "LAST", year?: 2026 }
+{ type: "START_OF", input: DatePresetJSON }
+{ type: "END_OF", input: DatePresetJSON }
 ```
 
 Example:
 
 ```ts
 TranspileJSONToDatePreset({
-  type: 'PERIOD_AT',
-  period: 'WEEK',
-  position: 'LAST',
-  year: 2028,
-})
+    type: "PERIOD_AT",
+    period: "WEEK",
+    position: "LAST",
+    year: 2028,
+});
 // PERIOD_AT("WEEK", "LAST", 2028)
 ```
 
@@ -514,119 +514,161 @@ TranspileJSONToDatePreset({
 Date picker oriented shapes are also supported:
 
 ```ts
-{ type: 'SINGLE_PERIOD', date: { year: 2026, month: 7 } }
+{ type: "SINGLE_PERIOD", date: { year: 2026, month: 7 } }
 // DATE_RANGE(DATE("2026-07-01"), END_OF(DATE("2026-07-31")))
 
-{ type: 'SINGLE_PERIOD', period: 'month', offset: -1 }
+{ type: "SINGLE_PERIOD", period: "month", offset: -1 }
 // CALENDAR_PERIOD("MONTH", -1)
 
-{ type: 'CUSTOM_RANGE', from: { year: 2026, month: 5, day: 31 }, to: { year: 2026, month: 6, day: 30 } }
+{ type: "CUSTOM_RANGE", from: { year: 2026, month: 5, day: 31 }, to: { year: 2026, month: 6, day: 30 } }
 // DATE_RANGE(DATE("2026-05-31"), END_OF(DATE("2026-06-30")))
 
-{ type: 'ROLLING_WINDOW', direction: 'last', amount: 30, unit: 'days' }
+{ type: "ROLLING_WINDOW", direction: "last", amount: 30, unit: "days" }
 // RELATIVE_PERIOD(-30, "DAY")
 ```
 
 Rules:
 
-- `SINGLE_PERIOD` with `date` requires `year`.
-- `CUSTOM_RANGE` materializes dates with start-of-day and end-of-day boundaries.
-- `ROLLING_WINDOW` normalizes plural units by removing the final `s`.
-- `direction: 'NEXT'` produces a positive offset; any other value behaves as `LAST`.
+-   `SINGLE_PERIOD` with `date` requires `year`.
+-   `CUSTOM_RANGE` materializes dates with start-of-day and end-of-day boundaries.
+-   `ROLLING_WINDOW` normalizes plural units by removing the final `s`.
+-   `direction: "NEXT"` produces a positive offset; any other value behaves as `LAST`.
 
 ## Formatting
 
 `FormatDatePreset` formats values using `Intl.DateTimeFormat`.
 
-By default, `date` and `dateRange` values include time using `timeStyle: 'short'`. When `partialDateStyle: 'short'` is used and no explicit `timeStyle` is provided, `date` and `dateRange` values omit time so they align with picker-style labels. Passing `timeStyle` explicitly keeps time in the output.
+By default, `date` and `dateRange` values include time using `timeStyle: "short"`. When `partialDateStyle: "short"` is used and no explicit `timeStyle` is provided, `date` and `dateRange` values omit time so they align with picker-style labels. Passing `timeStyle` explicitly keeps time in the output.
+
+`dateStyle: "short-padded"` is a Formula Lang formatting extension. It keeps the date order and separators from the selected locale, but renders year, month, and day with two digits. For example, `en-US` renders `07/30/26`, while `es-CO` renders `30/07/26`.
+
+`customFormat` has precedence over `dateStyle`, `timeStyle`, and locale date ordering. It is intended for explicit UI contracts that require a fixed token pattern. Supported tokens are `yyyy`, `yy`, `MM`, `M`, `dd`, `d`, `HH`, `H`, `mm`, `m`, `ss`, and `s`.
 
 Main options:
 
 ```ts
 {
-  locale?: 'en-US',
-  timezone?: 'UTC',
-  dateStyle?: 'full' | 'long' | 'medium' | 'short',
-  timeStyle?: 'full' | 'long' | 'medium' | 'short',
-  partialDateStyle?: 'long' | 'short'
+        locale?: "en-US",
+        timezone?: { offset?: string; timeZone?: string; name?: string; type?: string; timeZoneId?: string; numericFormat?: number },
+        customFormat?: string,
+        dateStyle?: "full" | "long" | "medium" | "short" | "short-padded",
+        timeStyle?: "full" | "long" | "medium" | "short",
+        partialDateStyle?: "long" | "short"
 }
 ```
 
 Examples:
 
 ```ts
-FormatDatePreset('2026-07-15T14:35:27.000Z', {
-  locale: 'en-US',
-  timezone: 'America/Chicago',
-  dateStyle: 'medium',
-  timeStyle: 'short',
-})
+FormatDatePreset("2026-07-15T14:35:27.000Z", {
+    locale: "en-US",
+    timezone: { timeZone: "America/Chicago" },
+    dateStyle: "medium",
+    timeStyle: "short",
+});
 // Jul 15, 2026, 9:35 AM
 
-FormatDatePreset('2026-07-15T14:35:27.000Z', { partialDateStyle: 'short' })
+FormatDatePreset("2026-07-15T14:35:27.000Z", { partialDateStyle: "short" });
 // Jul 15, 2026
 
+FormatDatePreset("2026-07-30T14:35:27.000Z", {
+    locale: "en-US",
+    dateStyle: "short-padded",
+    partialDateStyle: "short",
+});
+// 07/30/26
+
+FormatDatePreset("2026-07-30T14:35:27.000Z", {
+    locale: "es-CO",
+    dateStyle: "short-padded",
+    partialDateStyle: "short",
+});
+// 30/07/26
+
+FormatDatePreset("2026-07-30T14:35:27.000Z", {
+    locale: "es-CO",
+    customFormat: "MM/dd/yy",
+});
+// 07/30/26
+
 FormatDatePreset(
-  { start: '2026-07-01T00:00:00.000Z', end: '2026-07-31T23:59:59.999Z' },
-  { partialDateStyle: 'short' },
-)
-// { start: 'Jul 1, 2026', end: 'Jul 31, 2026' }
+    { start: "2026-07-01T00:00:00.000Z", end: "2026-07-31T23:59:59.999Z" },
+    { partialDateStyle: "short" },
+);
+// { start: "Jul 1, 2026", end: "Jul 31, 2026" }
 
-FormatDatePreset({ month: 4, day: 15 })
+FormatDatePreset(
+    { start: "2026-07-01T05:00:00.000Z", end: "2026-08-01T04:59:59.999Z" },
+    {
+        locale: "en-US",
+        timezone: { timeZone: "America/Chicago" },
+        dateStyle: "short-padded",
+        partialDateStyle: "short",
+    },
+);
+// { start: "07/01/26", end: "07/31/26" }
+
+FormatDatePreset({ month: 4, day: 15 });
 // April 15
 
-FormatDatePreset({ month: 4, day: 15 }, { partialDateStyle: 'short' })
+FormatDatePreset({ month: 4, day: 15 }, { partialDateStyle: "short" });
 // Apr 15
 
-FormatDatePreset({ week: 40 }, { partialDateStyle: 'short' })
+FormatDatePreset({ week: 40 }, { partialDateStyle: "short" });
 // W40
 
-FormatDatePreset({ day: 15 }, { partialDateStyle: 'short' })
+FormatDatePreset({ day: 15 }, { partialDateStyle: "short" });
 // Day 15
+
+FormatDatePreset(
+    { year: 2026, month: 7, day: 3 },
+    { locale: "en-US", dateStyle: "short-padded" },
+);
+// 07/03/26
 ```
 
 ## Legacy Tokens
 
 Legacy tokens are resolved with `TranspileJSONToDatePreset(token)` using `DATE_PRESET_TOKEN_MAP`.
 
-| Token | QDP expression |
-| --- | --- |
-| `NOW` | `NOW()` |
-| `TODAY` | `TODAY()` |
-| `CURRENT_DATE` | `TODAY()` |
-| `TODAY-7` | `START_OF(RELATIVE_PERIOD(-7, "DAY"))` |
-| `TODAY-30` | `START_OF(RELATIVE_PERIOD(-30, "DAY"))` |
-| `TODAY-60` | `START_OF(RELATIVE_PERIOD(-60, "DAY"))` |
-| `TODAY-90` | `START_OF(RELATIVE_PERIOD(-90, "DAY"))` |
-| `TODAY-120` | `START_OF(RELATIVE_PERIOD(-120, "DAY"))` |
-| `TODAY-365` | `START_OF(RELATIVE_PERIOD(-365, "DAY"))` |
-| `YESTERDAY` | `START_OF(RELATIVE_PERIOD(-1, "DAY"))` |
-| `TOMORROW` | `START_OF(END_OF(RELATIVE_PERIOD(1, "DAY")))` |
-| `CURRENT_MONTH` | `CALENDAR_PERIOD("MONTH", 0)` |
-| `CURRENT_MONTH_START` | `START_OF(CALENDAR_PERIOD("MONTH", 0))` |
-| `CURRENT_MONTH_END` | `END_OF(CALENDAR_PERIOD("MONTH", 0))` |
-| `LAST_MONTH` | `CALENDAR_PERIOD("MONTH", -1)` |
-| `LAST_MONTH_START` | `START_OF(CALENDAR_PERIOD("MONTH", -1))` |
-| `LAST_MONTH_END` | `END_OF(CALENDAR_PERIOD("MONTH", -1))` |
-| `CURRENT_WEEK` | `CALENDAR_PERIOD("WEEK", 0)` |
-| `CURRENT_WEEK_START` | `START_OF(CALENDAR_PERIOD("WEEK", 0))` |
-| `CURRENT_WEEK_END` | `END_OF(CALENDAR_PERIOD("WEEK", 0))` |
-| `LAST_WEEK` | `CALENDAR_PERIOD("WEEK", -1)` |
-| `LAST_WEEK_START` | `START_OF(CALENDAR_PERIOD("WEEK", -1))` |
-| `LAST_WEEK_END` | `END_OF(CALENDAR_PERIOD("WEEK", -1))` |
-| `CURRENT_QUARTER` | `CALENDAR_PERIOD("QUARTER", 0)` |
-| `CURRENT_QUARTER_START` | `START_OF(CALENDAR_PERIOD("QUARTER", 0))` |
-| `CURRENT_QUARTER_END` | `END_OF(CALENDAR_PERIOD("QUARTER", 0))` |
-| `LAST_QUARTER` | `CALENDAR_PERIOD("QUARTER", -1)` |
-| `LAST_QUARTER_START` | `START_OF(CALENDAR_PERIOD("QUARTER", -1))` |
-| `LAST_QUARTER_END` | `END_OF(CALENDAR_PERIOD("QUARTER", -1))` |
-| `CURRENT_YEAR` | `CALENDAR_PERIOD("YEAR", 0)` |
-| `CURRENT_YEAR_START` | `START_OF(CALENDAR_PERIOD("YEAR", 0))` |
-| `LAST_YEAR` | `CALENDAR_PERIOD("YEAR", -1)` |
-| `LAST_YEAR_START` | `START_OF(CALENDAR_PERIOD("YEAR", -1))` |
-| `LAST_YEAR_END` | `END_OF(CALENDAR_PERIOD("YEAR", -1))` |
-| `YEAR_BEFORE_LAST_YEAR_START` | `START_OF(CALENDAR_PERIOD("YEAR", -2))` |
-| `YEAR_BEFORE_LAST_YEAR_END` | `END_OF(CALENDAR_PERIOD("YEAR", -2))` |
+| Token                         | QDP expression                                |
+| ----------------------------- | --------------------------------------------- |
+| `NOW`                         | `NOW()`                                       |
+| `TODAY`                       | `TODAY()`                                     |
+| `CURRENT_DATE`                | `TODAY()`                                     |
+| `TODAY-7`                     | `START_OF(RELATIVE_PERIOD(-7, "DAY"))`        |
+| `TODAY-30`                    | `START_OF(RELATIVE_PERIOD(-30, "DAY"))`       |
+| `TODAY-60`                    | `START_OF(RELATIVE_PERIOD(-60, "DAY"))`       |
+| `TODAY-90`                    | `START_OF(RELATIVE_PERIOD(-90, "DAY"))`       |
+| `TODAY-120`                   | `START_OF(RELATIVE_PERIOD(-120, "DAY"))`      |
+| `TODAY-365`                   | `START_OF(RELATIVE_PERIOD(-365, "DAY"))`      |
+| `YESTERDAY`                   | `START_OF(RELATIVE_PERIOD(-1, "DAY"))`        |
+| `TOMORROW`                    | `START_OF(END_OF(RELATIVE_PERIOD(1, "DAY")))` |
+| `CURRENT_MONTH`               | `CALENDAR_PERIOD("MONTH", 0)`                 |
+| `CURRENT_MONTH_START`         | `START_OF(CALENDAR_PERIOD("MONTH", 0))`       |
+| `CURRENT_MONTH_END`           | `END_OF(CALENDAR_PERIOD("MONTH", 0))`         |
+| `LAST_MONTH`                  | `CALENDAR_PERIOD("MONTH", -1)`                |
+| `LAST_MONTH_START`            | `START_OF(CALENDAR_PERIOD("MONTH", -1))`      |
+| `LAST_MONTH_END`              | `END_OF(CALENDAR_PERIOD("MONTH", -1))`        |
+| `CURRENT_WEEK`                | `CALENDAR_PERIOD("WEEK", 0)`                  |
+| `CURRENT_WEEK_START`          | `START_OF(CALENDAR_PERIOD("WEEK", 0))`        |
+| `CURRENT_WEEK_END`            | `END_OF(CALENDAR_PERIOD("WEEK", 0))`          |
+| `LAST_WEEK`                   | `CALENDAR_PERIOD("WEEK", -1)`                 |
+| `LAST_WEEK_START`             | `START_OF(CALENDAR_PERIOD("WEEK", -1))`       |
+| `LAST_WEEK_END`               | `END_OF(CALENDAR_PERIOD("WEEK", -1))`         |
+| `CURRENT_QUARTER`             | `CALENDAR_PERIOD("QUARTER", 0)`               |
+| `CURRENT_QUARTER_START`       | `START_OF(CALENDAR_PERIOD("QUARTER", 0))`     |
+| `CURRENT_QUARTER_END`         | `END_OF(CALENDAR_PERIOD("QUARTER", 0))`       |
+| `LAST_QUARTER`                | `CALENDAR_PERIOD("QUARTER", -1)`              |
+| `LAST_QUARTER_START`          | `START_OF(CALENDAR_PERIOD("QUARTER", -1))`    |
+| `LAST_QUARTER_END`            | `END_OF(CALENDAR_PERIOD("QUARTER", -1))`      |
+| `CURRENT_YEAR`                | `CALENDAR_PERIOD("YEAR", 0)`                  |
+| `CURRENT_YEAR_START`          | `START_OF(CALENDAR_PERIOD("YEAR", 0))`        |
+| `LAST_YEAR`                   | `CALENDAR_PERIOD("YEAR", -1)`                 |
+| `LAST_YEAR_START`             | `START_OF(CALENDAR_PERIOD("YEAR", -1))`       |
+| `LAST_YEAR_END`               | `END_OF(CALENDAR_PERIOD("YEAR", -1))`         |
+| `YEAR_BEFORE_LAST_YEAR_START` | `START_OF(CALENDAR_PERIOD("YEAR", -2))`       |
+| `YEAR_BEFORE_LAST_YEAR_END`   | `END_OF(CALENDAR_PERIOD("YEAR", -2))`         |
 
 Tokens can be wrapped like `{{TODAY-7}}`. The normalizer removes braces and outer spaces.
 
@@ -634,51 +676,51 @@ Scalar tokens such as `CURRENT_TIME`, `CURRENT_TIMEZONE`, and `CURRENT_DAY_OF_WE
 
 ## Main Equivalences With The Date Picker
 
-| Picker expression | QDP expression | Note |
-| --- | --- | --- |
-| Today | `TODAY()` | Fixed date at the start of the current day |
-| Yesterday | `START_OF(RELATIVE_PERIOD(-1, "DAY"))` | Start of yesterday |
-| Tomorrow | `START_OF(END_OF(RELATIVE_PERIOD(1, "DAY")))` | Start of tomorrow |
-| This month | `CALENDAR_PERIOD("MONTH", 0)` | Current calendar month |
-| Previous month | `CALENDAR_PERIOD("MONTH", -1)` | Previous calendar month |
-| Last 30 days inclusive | `RELATIVE_PERIOD(-29, "DAY")` | Inclusive 30-day rolling window counting today |
-| April | `PARTIAL_DATE("ANY", 4)` | Recurring month |
-| April 2026 | `PERIOD_AT("MONTH", 4, 2026)` | Positional month in a year |
-| Apr 15 | `PARTIAL_DATE("ANY", 4, "ANY", "ANY", 15)` | Recurring month/day |
-| Day 15 | `PARTIAL_DATE("ANY", "ANY", "ANY", "ANY", 15)` | Recurring day of month |
-| Q2 | `PARTIAL_DATE("ANY", "ANY", 2)` | Recurring quarter |
-| Q2 2026 | `PERIOD_AT("QUARTER", 2, 2026)` | Positional quarter in a year |
-| W40 | `PARTIAL_DATE("ANY", "ANY", "ANY", 40)` | Recurring week |
-| W40 2026 | `PERIOD_AT("WEEK", 40, 2026)` | Positional week in a year |
-| Last week of 2028 | `PERIOD_AT("WEEK", "LAST", 2028)` | Avoids assuming W53/W54 |
-| Last month of the past year | `PERIOD_AT("MONTH", "LAST", 2025)` | Equivalent to December 2025 with current date 2026 |
-| Between inclusive | `DATE_RANGE(DATE(start), END_OF(DATE(end)))` | Materialize inclusive boundaries |
-| Between exclusive | `DATE_RANGE(DATE(adjustedStart), END_OF(DATE(adjustedEnd)))` | Materialize exclusion in the dates |
+| Picker expression           | QDP expression                                               | Note                                               |
+| --------------------------- | ------------------------------------------------------------ | -------------------------------------------------- |
+| Today                       | `TODAY()`                                                    | Fixed date at the start of the current day         |
+| Yesterday                   | `START_OF(RELATIVE_PERIOD(-1, "DAY"))`                       | Start of yesterday                                 |
+| Tomorrow                    | `START_OF(END_OF(RELATIVE_PERIOD(1, "DAY")))`                | Start of tomorrow                                  |
+| This month                  | `CALENDAR_PERIOD("MONTH", 0)`                                | Current calendar month                             |
+| Previous month              | `CALENDAR_PERIOD("MONTH", -1)`                               | Previous calendar month                            |
+| Last 30 days inclusive      | `RELATIVE_PERIOD(-29, "DAY")`                                | Inclusive 30-day rolling window counting today     |
+| April                       | `PARTIAL_DATE("ANY", 4)`                                     | Recurring month                                    |
+| April 2026                  | `PERIOD_AT("MONTH", 4, 2026)`                                | Positional month in a year                         |
+| Apr 15                      | `PARTIAL_DATE("ANY", 4, "ANY", "ANY", 15)`                   | Recurring month/day                                |
+| Day 15                      | `PARTIAL_DATE("ANY", "ANY", "ANY", "ANY", 15)`               | Recurring day of month                             |
+| Q2                          | `PARTIAL_DATE("ANY", "ANY", 2)`                              | Recurring quarter                                  |
+| Q2 2026                     | `PERIOD_AT("QUARTER", 2, 2026)`                              | Positional quarter in a year                       |
+| W40                         | `PARTIAL_DATE("ANY", "ANY", "ANY", 40)`                      | Recurring week                                     |
+| W40 2026                    | `PERIOD_AT("WEEK", 40, 2026)`                                | Positional week in a year                          |
+| Last week of 2028           | `PERIOD_AT("WEEK", "LAST", 2028)`                            | Avoids assuming W53/W54                            |
+| Last month of the past year | `PERIOD_AT("MONTH", "LAST", 2025)`                           | Equivalent to December 2025 with current date 2026 |
+| Between inclusive           | `DATE_RANGE(DATE(start), END_OF(DATE(end)))`                 | Materialize inclusive boundaries                   |
+| Between exclusive           | `DATE_RANGE(DATE(adjustedStart), END_OF(DATE(adjustedEnd)))` | Materialize exclusion in the dates                 |
 
 ## Validations And Expected Errors
 
 Important invalid cases:
 
 ```ts
-DATE("2026-02-31")
+DATE("2026-02-31");
 // INVALID_ALLOW_VALUE: calendrically invalid date
 
-DATE("2026-02-31T00:00")
+DATE("2026-02-31T00:00");
 // INVALID_ALLOW_VALUE: calendrically invalid date
 
-RELATIVE_PERIOD(-1, "HOUR")
+RELATIVE_PERIOD(-1, "HOUR");
 // INVALID_ALLOW_VALUE: unsupported unit
 
-CALENDAR_PERIOD("DECADE", 0)
+CALENDAR_PERIOD("DECADE", 0);
 // INVALID_ALLOW_VALUE: unsupported period
 
-PERIOD_AT("MONTH", "MIDDLE", 2026)
+PERIOD_AT("MONTH", "MIDDLE", 2026);
 // INVALID_ALLOW_VALUE: unsupported symbolic position
 
-PARTIAL_DATE("ANY", 13)
+PARTIAL_DATE("ANY", 13);
 // INVALID_ALLOW_VALUE: month out of range
 
-DATE_RANGE(DATE("2026-07-31T00:00"), DATE("2026-07-01T00:00"))
+DATE_RANGE(DATE("2026-07-31T00:00"), DATE("2026-07-01T00:00"));
 // INVALID_DATE_RANGE: end before start
 ```
 
@@ -686,24 +728,25 @@ Additionally, any QDP expression whose final result is not `date`, `dateRange`,
 
 ## Relevant Files
 
-| File | Responsibility |
-| --- | --- |
-| `src/date-presets.ts` | Public API, JSON conversion, formatting, and `valueType` classification |
-| `src/date-preset-tokens.ts` | Legacy token map to QDP expressions |
-| `src/functions/index.ts` | Function registration for `ENGINES.QDP` |
-| `src/functions/datePresetUtils.ts` | Date, range, calendar, week, timezone, and partial date resolution |
-| `src/functions/*.ts` | Individual QDP function definitions |
-| `__tests__/unit/datePresetTranspiler.test.ts` | Main transpilation and picker compatibility cases |
-| `__tests__/unit/datePresetJson.test.ts` | JSON to QDP conversion |
-| `__tests__/unit/datePresetFormat.test.ts` | Date and partial date formatting |
-| `__tests__/unit/datePresetTokens.test.ts` | Legacy tokens |
-| `date-preset-qdp-examples.csv` | Generated examples with tokens and picker expressions |
+| File                                          | Responsibility                                                          |
+| --------------------------------------------- | ----------------------------------------------------------------------- |
+| `src/date-presets/date-presets.ts`            | Public API, JSON conversion, formatting, and `valueType` classification |
+| `src/date-presets/date-preset-tokens.ts`      | Legacy token map to QDP expressions                                     |
+| `src/functions/index.ts`                      | Function registration for `ENGINES.QDP`                                 |
+| `src/utils/datePresetUtils.ts`                | Date, range, calendar, week, and partial date resolution                |
+| `src/utils/timezone.ts`                       | Timezone definition normalization and offset helpers                    |
+| `src/functions/*.ts`                          | Individual QDP function definitions                                     |
+| `__tests__/unit/datePresetTranspiler.test.ts` | Main transpilation and picker compatibility cases                       |
+| `__tests__/unit/datePresetJson.test.ts`       | JSON to QDP conversion                                                  |
+| `__tests__/unit/datePresetFormat.test.ts`     | Date and partial date formatting                                        |
+| `__tests__/unit/datePresetTokens.test.ts`     | Legacy tokens                                                           |
+| `date-preset-qdp-examples.csv`                | Generated examples with tokens and picker expressions                   |
 
 ## Current State And Design Notes
 
-- QDP is limited to date preset functions in `ENGINE_FN_MAP[ENGINES.QDP]`.
-- Date preset expressions can be nested as long as the final result is `date`, `dateRange`, or `partialDate`.
-- `partialDate` was added as a primitive to represent incomplete date picker selections.
-- Week compatibility with the date picker uses Sunday as the default start day and supports W54.
-- `PERIOD_AT` supports symbolic positions `FIRST` and `LAST` to reduce ambiguity in variable-length periods.
-- For documentation and example auditing, the CSV `date-preset-qdp-examples.csv` contains resolved, formatted, and classified values.
+-   QDP is limited to date preset functions in `ENGINE_FN_MAP[ENGINES.QDP]`.
+-   Date preset expressions can be nested as long as the final result is `date`, `dateRange`, or `partialDate`.
+-   `partialDate` was added as a primitive to represent incomplete date picker selections.
+-   Week compatibility with the date picker uses Sunday as the default start day and supports W54.
+-   `PERIOD_AT` supports symbolic positions `FIRST` and `LAST` to reduce ambiguity in variable-length periods.
+-   For documentation and example auditing, the CSV `date-preset-qdp-examples.csv` contains resolved, formatted, and classified values.