@nocobase/flow-engine 2.3.0-alpha.1 → 2.3.0-beta.2

package/src/flowContext.ts

@@ -50,11 +50,11 @@ import {
   resolveModuleUrl,
 } from './utils';
 import { FlowExitAllException } from './utils/exceptions';
-import { enqueueVariablesResolve, JSONValue } from './utils/params-resolvers';
+import { buildFlowModelResolveDescriptor, enqueueVariablesResolve, JSONValue } from './utils/params-resolvers';
 import type { RecordRef } from './utils/serverContextParams';
 import { buildServerContextParams as _buildServerContextParams } from './utils/serverContextParams';
-import { getDirtyAwareApiClient } from './utils/dirtyAwareApiClient';
-import { inferRecordRef } from './utils/variablesParams';
+import { getDirtyAwareApiClient, PREPARE_CONTEXT_RESOURCE_ACTION_PARAMS } from './utils/dirtyAwareApiClient';
+import { inferRecordRef, inferViewRecordRef } from './utils/variablesParams';
 import { FlowView, FlowViewer } from './views/FlowView';
 import { RunJSContextRegistry, getModelClassName, type RunJSVersion } from './runjs-context/registry';
 import { createEphemeralContext } from './utils/createEphemeralContext';
@@ -165,6 +165,10 @@ function inferSelectsFromUsage(paths: string[] = []): { generatedAppends?: strin
 
 type Getter<T = any> = (ctx: FlowContext) => T | Promise<T>;
 
+export type ResolveJsonTemplateOptions = {
+  contractModelUid?: string | number | null;
+};
+
 export type FlowContextDocRef = string | { url: string; title?: string };
 
 export type FlowDeprecationDoc =
@@ -221,6 +225,8 @@ export interface MetaTreeNode {
   // 变量禁用状态与原因（用于变量选择器 UI 展示）
   disabled?: boolean | (() => boolean);
   disabledReason?: string | (() => string | undefined);
+  // 允许节点仅用于展开子级，而不能作为变量值被选中
+  selectable?: boolean;
   children?: MetaTreeNode[] | (() => Promise<MetaTreeNode[]>);
 }
 
@@ -3044,7 +3050,7 @@ class BaseFlowEngineContext extends FlowContext {
    * @deprecated use `resolveJsonTemplate` instead
    */
   declare renderJson: (template: JSONValue) => Promise<any>;
-  declare resolveJsonTemplate: (template: JSONValue) => Promise<any>;
+  declare resolveJsonTemplate: (template: JSONValue, options?: ResolveJsonTemplateOptions) => Promise<any>;
   declare getVar: (path: string) => Promise<any>;
   declare request: (options: RequestOptions) => Promise<any>;
   declare runjs: (code: string, variables?: Record<string, any>, options?: JSRunnerOptions) => Promise<any>;
@@ -3227,7 +3233,11 @@ export class FlowEngineContext extends BaseFlowEngineContext {
     this.defineMethod('renderJson', function (template: any) {
       return this.resolveJsonTemplate(template);
     });
-    this.defineMethod('resolveJsonTemplate', async function (this: BaseFlowEngineContext, template: any) {
+    const resolveJsonTemplate = async function (
+      this: BaseFlowEngineContext,
+      template: any,
+      options?: ResolveJsonTemplateOptions,
+    ) {
       // 提取模板使用到的变量及其子路径
       const used = extractUsedVariablePaths(template);
       const usedVarNames = Object.keys(used || {});
@@ -3316,6 +3326,15 @@ export class FlowEngineContext extends BaseFlowEngineContext {
         const inputFromMeta = await collectFromMeta();
         const autoInput = { ...inputFromMeta } as Record<string, any>;
 
+        const viewPaths = serverVarPaths.view || [];
+        if (
+          !autoInput.view &&
+          viewPaths.some((path) => path === 'record' || path.startsWith('record.') || path.startsWith('record['))
+        ) {
+          const recordRef = inferViewRecordRef(this);
+          if (recordRef) autoInput.view = { record: recordRef };
+        }
+
         // Special-case: formValues
         // If server needs to resolve some formValues paths but meta params only cover association anchors
         // (e.g. formValues.customer) and some top-level paths are missing (e.g. formValues.status),
@@ -3387,7 +3406,13 @@ export class FlowEngineContext extends BaseFlowEngineContext {
 
         if (this.api) {
           try {
+            const contractRd = buildFlowModelResolveDescriptor(
+              this as FlowRuntimeContext<FlowModel>,
+              options?.contractModelUid,
+            );
             serverResolved = await enqueueVariablesResolve(this as FlowRuntimeContext<FlowModel>, {
+              ...(contractRd ? { contractRd } : {}),
+              rd: buildFlowModelResolveDescriptor(this as FlowRuntimeContext<FlowModel>, this.model?.uid),
               template,
               contextParams: autoContextParams || {},
             });
@@ -3399,7 +3424,8 @@ export class FlowEngineContext extends BaseFlowEngineContext {
       }
 
       return resolveExpressions(serverResolved, this);
-    });
+    };
+    this.defineMethod('resolveJsonTemplate', resolveJsonTemplate);
 
     // Helper: resolve a single ctx expression value via resolveJsonTemplate behavior.
     // Example: await ctx.getVar('ctx.record.id')
@@ -4582,9 +4608,56 @@ function __mergeRunJSDocMeta(base: any, patch: any): RunJSDocMeta {
   return out as RunJSDocMeta;
 }
 export class FlowRunJSContext extends FlowContext {
+  [PREPARE_CONTEXT_RESOURCE_ACTION_PARAMS](
+    action: { actionName: string; dataSourceKey?: string; resourceName: string; resourceOf?: unknown },
+    params: Record<string, unknown> | undefined,
+  ) {
+    if (
+      action.actionName.toLowerCase() !== 'create' ||
+      !params ||
+      Array.isArray(params) ||
+      Object.prototype.hasOwnProperty.call(params, 'updateAssociationValues') ||
+      !this.form ||
+      typeof this.blockModel?.submitFromRunJs !== 'function'
+    ) {
+      return params;
+    }
+
+    const resource = this.resource;
+    const currentResourceName = resource?.getResourceName?.();
+    const currentDataSourceKey = resource?.getDataSourceKey?.() || 'main';
+    if (action.resourceName !== currentResourceName || (action.dataSourceKey || 'main') !== currentDataSourceKey) {
+      return params;
+    }
+
+    const currentSourceId = resource?.getSourceId?.();
+    if (
+      currentResourceName?.includes('.') &&
+      currentSourceId !== null &&
+      typeof currentSourceId !== 'undefined' &&
+      String(action.resourceOf ?? '') !== String(currentSourceId)
+    ) {
+      return params;
+    }
+
+    const updateAssociationValues = resource?.getUpdateAssociationValues?.();
+    if (!Array.isArray(updateAssociationValues) || updateAssociationValues.length === 0) {
+      return params;
+    }
+
+    return {
+      ...params,
+      updateAssociationValues: [...updateAssociationValues],
+    };
+  }
+
   constructor(delegate: FlowContext) {
     super();
     this.addDelegate(delegate);
+    const submit = delegate.blockModel?.submitFromRunJs?.bind(delegate.blockModel);
+    if (delegate.form && submit) {
+      this.defineProperty('form', { value: { ...delegate.form, submit } });
+    }
     this.defineProperty('React', { value: React });
     this.defineProperty('antd', { value: antd });
     this.defineProperty('dayjs', {

package/src/locale/__tests__/index.test.ts

@@ -0,0 +1,21 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { getFlowEngineTranslation } from '../index';
+
+describe('flow engine locale', () => {
+  it('translates the default secondary confirmation text into Chinese', () => {
+    expect(getFlowEngineTranslation('Please Confirm', 'zh-CN')).toBe('请确认');
+    expect(getFlowEngineTranslation('Are you sure you want to perform the action?', 'zh-CN')).toBe(
+      '确定要执行此操作吗？',
+    );
+  });
+});

package/src/locale/en-US.json

@@ -1,5 +1,6 @@
 {
   "Add": "Add",
+  "Are you sure you want to perform the action?": "Are you sure you want to perform the action?",
   "Are you sure you want to delete this item? This action cannot be undone.": "Are you sure you want to delete this item? This action cannot be undone.",
   "Are you sure to convert this template block to copy mode?": "Are you sure you want to convert this template block to copy mode?",
   "Array index out of bounds": "Array index {{index}} out of bounds for '{{subKey}}'",
@@ -53,6 +54,7 @@
   "Other blocks": "Other blocks",
   "Parent not found, cannot replace block": "Parent not found, cannot replace block",
   "Previous step": "Previous step",
+  "Please Confirm": "Please Confirm",
   "Replace current block with template?": "Replace current block with template?",
   "Replaced with template block": "Replaced with template block",
   "Render failed": "Render failed",

package/src/locale/zh-CN.json

@@ -1,5 +1,6 @@
 {
   "Add": "添加",
+  "Are you sure you want to perform the action?": "确定要执行此操作吗？",
   "Are you sure you want to delete this item? This action cannot be undone.": "确定要删除此项吗？此操作不可撤销。",
   "Are you sure to convert this template block to copy mode?": "确定将该模板区块转换为复制模式吗？",
   "Array index out of bounds": "数组索引 {{index}} 超出 '{{subKey}}' 的边界",
@@ -59,6 +60,7 @@
   "OK": "确定",
   "Other blocks": "其他区块",
   "Previous step": "上一步",
+  "Please Confirm": "请确认",
   "Render failed": "渲染失败",
   "Response record": "响应结果记录",
   "Step configuration": "步骤配置",

package/src/resources/__tests__/flowResource.test.ts

@@ -79,6 +79,9 @@ describe('FlowResource - error handling', () => {
     expect(r.getError()).toBeNull();
 
     const err = new ResourceError({ response: { data: { error: { message: 'boom', code: 'X' } } } });
+    expect(err.data).toEqual({ message: 'boom', code: 'X' });
+    expect(err.message).toBe('boom');
+    expect(err.code).toBe('X');
     const ret = r.setError(err);
     expect(ret).toBe(r);
     expect(r.error).toBe(err);

package/src/resources/flowResource.ts

@@ -47,6 +47,7 @@ export class ResourceError extends Error {
   constructor(error) {
     const data = toErrMessages(error).shift();
     super(data.message);
+    this.data = data;
     this.name = 'ResponseError';
   }
 

package/src/utils/__tests__/dateVariable.test.ts

@@ -12,9 +12,12 @@ import {
   decodeBase64Url,
   encodeBase64Url,
   isCompleteCtxDatePath,
+  isCtxDatePathPrefix,
   isCtxDateExpression,
   parseCtxDateExpression,
+  parseCtxDateExpressionConfig,
   resolveCtxDatePath,
+  serializeCtxDateExpressionConfig,
   serializeCtxDateValue,
 } from '../dateVariable';
 
@@ -54,13 +57,60 @@ describe('dateVariable utils', () => {
       number: 2,
     });
 
-    const singleExpr = serializeCtxDateValue('2026-02-12')!;
+    const singleExpr = serializeCtxDateValue('2026-02-12');
+    if (!singleExpr) throw new Error('Expected exact date expression');
     expect(parseCtxDateExpression(singleExpr)).toBe('2026-02-12');
 
-    const rangeExpr = serializeCtxDateValue(['2026-02-12', '2026-02-20'])!;
+    const rangeExpr = serializeCtxDateValue(['2026-02-12', '2026-02-20']);
+    if (!rangeExpr) throw new Error('Expected exact date range expression');
     expect(parseCtxDateExpression(rangeExpr)).toEqual(['2026-02-12', '2026-02-20']);
   });
 
+  it('serializes, parses and resolves formatted expressions', () => {
+    const expression = serializeCtxDateExpressionConfig({
+      kind: 'preset',
+      preset: 'today',
+      format: 'YYYY/MM/DD',
+    });
+    if (!expression) throw new Error('Expected formatted date expression');
+
+    expect(expression).toMatch(/^\{\{ ctx\.date\.format\.v[A-Za-z0-9_-]+\.preset\.today \}\}$/);
+    expect(parseCtxDateExpressionConfig(expression)).toEqual({
+      kind: 'preset',
+      preset: 'today',
+      format: 'YYYY/MM/DD',
+    });
+    // Keep the legacy parser contract for filter-form consumers.
+    expect(parseCtxDateExpression(expression)).toEqual({ type: 'today' });
+
+    const path = expression.replace('{{ ctx.', '').replace(' }}', '').split('.');
+    expect(resolveCtxDatePath(path)).toMatch(/^\d{4}\/\d{2}\/\d{2}$/);
+    expect(isCompleteCtxDatePath(path)).toBe(true);
+  });
+
+  it('preserves significant whitespace in a custom Format', () => {
+    const expression = serializeCtxDateExpressionConfig({
+      kind: 'preset',
+      preset: 'today',
+      format: 'YYYY-MM-DD ',
+    });
+    if (!expression) throw new Error('Expected formatted date expression');
+
+    expect(parseCtxDateExpressionConfig(expression)?.format).toBe('YYYY-MM-DD ');
+  });
+
+  it('formats exact ranges element by element', () => {
+    const expression = serializeCtxDateExpressionConfig({
+      kind: 'exact',
+      value: ['2026-02-12', '2026-02-20'],
+      format: 'YYYYMMDD',
+    });
+    if (!expression) throw new Error('Expected formatted date range expression');
+    const path = expression.replace('{{ ctx.', '').replace(' }}', '').split('.');
+
+    expect(resolveCtxDatePath(path)).toEqual(['20260212', '20260220']);
+  });
+
   it('resolves preset/relative/exact path', () => {
     expect(typeof resolveCtxDatePath(['date', 'preset', 'now'])).toBe('string');
 
@@ -72,11 +122,13 @@ describe('dateVariable utils', () => {
     expect(typeof rel).toBe('string');
     expect(rel).toMatch(/^\d{4}-\d{2}-\d{2}$/);
 
-    const singleExpr = serializeCtxDateValue('2026-02-12')!;
+    const singleExpr = serializeCtxDateValue('2026-02-12');
+    if (!singleExpr) throw new Error('Expected exact date expression');
     const token = singleExpr.replace('{{ ctx.date.exact.single.date.', '').replace(' }}', '');
     expect(resolveCtxDatePath(['date', 'exact', 'single', 'date', token])).toBe('2026-02-12');
 
-    const rangeExpr = serializeCtxDateValue(['2026-02-12', '2026-02-20'])!;
+    const rangeExpr = serializeCtxDateValue(['2026-02-12', '2026-02-20']);
+    if (!rangeExpr) throw new Error('Expected exact date range expression');
     const parts = rangeExpr.replace('{{ ctx.date.exact.range.date.', '').replace(' }}', '').split('.');
     expect(resolveCtxDatePath(['date', 'exact', 'range', 'date', parts[0], parts[1]])).toEqual([
       '2026-02-12',
@@ -90,6 +142,7 @@ describe('dateVariable utils', () => {
     expect(isCompleteCtxDatePath(['date', 'exact', 'single', 'date', 'vabc'])).toBe(true);
     expect(isCompleteCtxDatePath(['date', 'exact', 'range', 'date', 'vabc', 'vdef'])).toBe(true);
     expect(isCompleteCtxDatePath(['date', 'relative', 'next', 'day'])).toBe(false);
+    expect(isCtxDatePathPrefix(['date', 'format'])).toBe(true);
     expect(isCompleteCtxDatePath(['user', 'name'])).toBe(false);
   });
 

package/src/utils/__tests__/variablesParams.test.ts

@@ -34,7 +34,8 @@ describe('variablesParams helpers', () => {
 
   it('inferRecordRef fallback to collection.getFilterByTK when resource has no filterByTk', () => {
     const engine = new FlowEngine();
-    const ds = engine.context.dataSourceManager.getDataSource('main')!;
+    const ds = engine.context.dataSourceManager.getDataSource('main');
+    if (!ds) throw new Error('main data source is required');
     ds.addCollection({
       name: 'users',
       filterTargetKey: 'id',
@@ -108,6 +109,32 @@ describe('variablesParams helpers', () => {
     });
   });
 
+  it('collectContextParamsForTemplate infers view.record when its meta has no descriptor', async () => {
+    const ctx: any = {
+      getPropertyOptions: () => undefined,
+      view: {
+        inputArgs: {
+          collectionName: 'posts',
+          dataSourceKey: 'main',
+          filterByTk: 3,
+        },
+      },
+    };
+
+    const res = await collectContextParamsForTemplate(ctx, {
+      recordId: '{{ ctx.view.record.id }}',
+      viewType: '{{ ctx.view.type }}',
+    });
+
+    expect(res).toEqual({
+      'view.record': {
+        collection: 'posts',
+        dataSourceKey: 'main',
+        filterByTk: 3,
+      },
+    });
+  });
+
   it('createRecordResolveOnServerWithLocal: no local record => always use server', () => {
     const resolver = createRecordResolveOnServerWithLocal(
       () => ({ name: 'posts', dataSourceKey: 'main' }) as any,

package/src/utils/associationObjectVariable.ts

@@ -51,13 +51,14 @@ function findFieldByName(collection: Collection | null | undefined, name?: strin
  * @param primaryKey 主键字段名
  * @returns 解析出的主键值，无法解析时返回 undefined
  */
-function toFilterByTk(value: unknown, primaryKey: string | string[]) {
+export function getAssociationFilterByTk(value: unknown, primaryKey: string | string[]) {
   if (value == null) return undefined;
   if (Array.isArray(primaryKey)) {
     if (typeof value !== 'object' || !value) return undefined;
-    const out: Record<string, any> = {};
+    const record = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
     for (const k of primaryKey) {
-      const v = (value as any)[k];
+      const v = record[k];
       if (typeof v === 'undefined' || v === null) return undefined;
       out[k] = v;
     }
@@ -65,7 +66,7 @@ function toFilterByTk(value: unknown, primaryKey: string | string[]) {
   }
   if (typeof value === 'string' || typeof value === 'number') return value;
   if (typeof value === 'object') {
-    return (value as any)[primaryKey];
+    return (value as Record<string, unknown>)[primaryKey];
   }
   return undefined;
 }
@@ -149,7 +150,9 @@ export function createAssociationAwareObjectMetaFactory(
           if (associationValue == null) continue;
 
           if (Array.isArray(associationValue)) {
-            const ids = associationValue.map((item) => toFilterByTk(item, primaryKey)).filter((v) => v != null);
+            const ids = associationValue
+              .map((item) => getAssociationFilterByTk(item, primaryKey))
+              .filter((v) => v != null);
             if (ids.length) {
               params[name] = {
                 collection: target,
@@ -158,7 +161,7 @@ export function createAssociationAwareObjectMetaFactory(
               };
             }
           } else {
-            const id = toFilterByTk(associationValue, primaryKey);
+            const id = getAssociationFilterByTk(associationValue, primaryKey);
             if (id != null) {
               params[name] = {
                 collection: target,

package/src/utils/dateVariable.ts

@@ -11,7 +11,7 @@ import dayjs from 'dayjs';
 
 const CTX_DATE_REGEX = /^\{\{\s*ctx\.date(?:\.(.+?))?\s*\}\}$/;
 
-const PRESET_KEYS = new Set([
+const PRESET_KEY_LIST = [
   'today',
   'now',
   'yesterday',
@@ -28,10 +28,28 @@ const PRESET_KEYS = new Set([
   'thisYear',
   'lastYear',
   'nextYear',
-]);
+] as const;
+
+export type CtxDatePreset = (typeof PRESET_KEY_LIST)[number];
+export type CtxDateRelativeDirection = 'next' | 'past';
+export type CtxDateRelativeUnit = 'day' | 'week' | 'month' | 'year';
+
+export type CtxDateExpressionConfig =
+  | { kind: 'exact'; value: string | [string, string]; format?: string }
+  | {
+      kind: 'relative';
+      direction: CtxDateRelativeDirection;
+      amount: number;
+      unit: CtxDateRelativeUnit;
+      format?: string;
+    }
+  | { kind: 'preset'; preset: CtxDatePreset; format?: string };
+
+const PRESET_KEYS = new Set<string>(PRESET_KEY_LIST);
 
 const RELATIVE_DIRECTIONS = new Set(['next', 'past']);
 const RELATIVE_UNITS = new Set(['day', 'week', 'month', 'year']);
+const MAX_DATE_FORMAT_LENGTH = 128;
 
 function parseCtxDateSegments(value: string): string[] | null {
   if (typeof value !== 'string') return null;
@@ -46,8 +64,7 @@ function parseCtxDateSegments(value: string): string[] | null {
     .filter(Boolean);
 }
 
-export function isCtxDatePathPrefix(pathSegments: string[]): boolean {
-  const segments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
+function isBaseCtxDatePathPrefix(segments: string[]): boolean {
   if (segments[0] !== 'date') return false;
   if (segments.length === 1) return true;
 
@@ -96,6 +113,36 @@ export function isCtxDatePathPrefix(pathSegments: string[]): boolean {
   return false;
 }
 
+function decodeFormatToken(token: string): string | undefined {
+  const raw = String(token || '');
+  if (!raw.startsWith('v')) return undefined;
+  const decoded = decodeBase64Url(raw.slice(1));
+  if (!decoded || decoded.length > MAX_DATE_FORMAT_LENGTH) return undefined;
+  return decoded;
+}
+
+function splitFormattedDateSegments(segments: string[]): { baseSegments: string[]; format?: string } | null {
+  if (segments[0] !== 'date') return null;
+  if (segments[1] !== 'format') return { baseSegments: segments };
+  if (segments.length < 4) return null;
+
+  const format = decodeFormatToken(segments[2]);
+  if (!format) return null;
+  return { baseSegments: ['date', ...segments.slice(3)], format };
+}
+
+export function isCtxDatePathPrefix(pathSegments: string[]): boolean {
+  const segments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
+  if (segments[0] !== 'date') return false;
+  if (segments.length === 1) return true;
+  if (segments[1] !== 'format') return isBaseCtxDatePathPrefix(segments);
+  if (segments.length === 2) return true;
+  if (segments.length === 3) return typeof decodeFormatToken(segments[2]) === 'string';
+
+  const formatted = splitFormattedDateSegments(segments);
+  return formatted ? isBaseCtxDatePathPrefix(formatted.baseSegments) : false;
+}
+
 function withDatePrefix(pathSegments: string[]): string[] {
   if (pathSegments[0] === 'date') {
     return pathSegments;
@@ -210,27 +257,29 @@ export function isCtxDateExpression(value: unknown): value is string {
 export function isCompleteCtxDatePath(pathSegments: string[]): boolean {
   if (!isCtxDatePathPrefix(pathSegments)) return false;
   const segments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
-  if (segments[0] !== 'date') return false;
+  const formatted = splitFormattedDateSegments(segments);
+  if (!formatted) return false;
+  const baseSegments = formatted.baseSegments;
 
-  if (segments[1] === 'preset') {
-    return segments.length === 3 && PRESET_KEYS.has(segments[2]);
+  if (baseSegments[1] === 'preset') {
+    return baseSegments.length === 3 && PRESET_KEYS.has(baseSegments[2]);
   }
 
-  if (segments[1] === 'relative') {
-    if (segments.length !== 5) return false;
+  if (baseSegments[1] === 'relative') {
+    if (baseSegments.length !== 5) return false;
     return (
-      RELATIVE_DIRECTIONS.has(segments[2]) &&
-      RELATIVE_UNITS.has(segments[3]) &&
-      typeof parseNumberToken(segments[4]) === 'number'
+      RELATIVE_DIRECTIONS.has(baseSegments[2]) &&
+      RELATIVE_UNITS.has(baseSegments[3]) &&
+      typeof parseNumberToken(baseSegments[4]) === 'number'
     );
   }
 
-  if (segments[1] === 'exact' && segments[2] === 'single' && segments[3] === 'date') {
-    return segments.length === 5 && /^v.+/.test(segments[4]);
+  if (baseSegments[1] === 'exact' && baseSegments[2] === 'single' && baseSegments[3] === 'date') {
+    return baseSegments.length === 5 && /^v.+/.test(baseSegments[4]);
   }
 
-  if (segments[1] === 'exact' && segments[2] === 'range' && segments[3] === 'date') {
-    return segments.length === 6 && /^v.+/.test(segments[4]) && /^v.+/.test(segments[5]);
+  if (baseSegments[1] === 'exact' && baseSegments[2] === 'range' && baseSegments[3] === 'date') {
+    return baseSegments.length === 6 && /^v.+/.test(baseSegments[4]) && /^v.+/.test(baseSegments[5]);
   }
 
   return false;
@@ -238,7 +287,10 @@ export function isCompleteCtxDatePath(pathSegments: string[]): boolean {
 
 export function parseCtxDateExpression(value: unknown): any {
   if (!isCtxDateExpression(value)) return undefined;
-  const segments = withDatePrefix(parseCtxDateSegments(value as string) || []);
+  const rawSegments = withDatePrefix(parseCtxDateSegments(value as string) || []);
+  const formatted = splitFormattedDateSegments(rawSegments);
+  if (!formatted) return undefined;
+  const segments = formatted.baseSegments;
 
   if (segments[1] === 'preset' && segments.length === 3 && PRESET_KEYS.has(segments[2])) {
     return { type: segments[2] };
@@ -276,6 +328,66 @@ export function parseCtxDateExpression(value: unknown): any {
   return undefined;
 }
 
+export function parseCtxDateExpressionConfig(value: unknown): CtxDateExpressionConfig | undefined {
+  if (!isCtxDateExpression(value)) return undefined;
+  const segments = withDatePrefix(parseCtxDateSegments(value) || []);
+  const formatted = splitFormattedDateSegments(segments);
+  if (!formatted) return undefined;
+
+  const parsed = parseCtxDateExpression(value);
+  const formatConfig = formatted.format ? { format: formatted.format } : {};
+  if (typeof parsed === 'string') {
+    return { kind: 'exact', value: parsed, ...formatConfig };
+  }
+  if (Array.isArray(parsed) && parsed.length === 2 && typeof parsed[0] === 'string' && typeof parsed[1] === 'string') {
+    return { kind: 'exact', value: [parsed[0], parsed[1]], ...formatConfig };
+  }
+
+  if (!parsed || typeof parsed !== 'object') return undefined;
+  const typed = parsed as { type?: unknown; unit?: unknown; number?: unknown };
+  if (typed.type === 'past' || typed.type === 'next') {
+    if (typeof typed.unit !== 'string' || !RELATIVE_UNITS.has(typed.unit) || typeof typed.number !== 'number') {
+      return undefined;
+    }
+    return {
+      kind: 'relative',
+      direction: typed.type,
+      amount: typed.number,
+      unit: typed.unit as CtxDateRelativeUnit,
+      ...formatConfig,
+    };
+  }
+
+  if (typeof typed.type === 'string' && PRESET_KEYS.has(typed.type)) {
+    return { kind: 'preset', preset: typed.type as CtxDatePreset, ...formatConfig };
+  }
+  return undefined;
+}
+
+export function serializeCtxDateExpressionConfig(config: CtxDateExpressionConfig): string | undefined {
+  let legacyValue: unknown;
+
+  if (config.kind === 'preset') {
+    if (!PRESET_KEYS.has(config.preset)) return undefined;
+    legacyValue = { type: config.preset };
+  } else if (config.kind === 'relative') {
+    if (!RELATIVE_DIRECTIONS.has(config.direction) || !RELATIVE_UNITS.has(config.unit)) return undefined;
+    const amount = Math.floor(Number(config.amount));
+    if (!Number.isFinite(amount) || amount <= 0) return undefined;
+    legacyValue = { type: config.direction, unit: config.unit, number: amount };
+  } else {
+    legacyValue = config.value;
+  }
+
+  const expression = serializeCtxDateValue(legacyValue);
+  if (!expression || !config.format) return expression;
+
+  const format = String(config.format);
+  if (!format.trim() || format.length > MAX_DATE_FORMAT_LENGTH) return undefined;
+  const segments = withDatePrefix(parseCtxDateSegments(expression) || []);
+  return toCtxDateExpression(['date', 'format', `v${encodeBase64Url(format)}`, ...segments.slice(1)]);
+}
+
 export function serializeCtxDateValue(value: unknown): string | undefined {
   if (isCtxDateExpression(value)) {
     return String(value).trim();
@@ -327,8 +439,23 @@ export function serializeCtxDateValue(value: unknown): string | undefined {
   return undefined;
 }
 
+function formatResolvedDateValue(value: unknown, format: string): unknown {
+  const formatValue = (item: unknown) => {
+    if (typeof item !== 'string') return item;
+    const parsed = dayjs(item);
+    return parsed.isValid() ? parsed.format(format) : item;
+  };
+  return Array.isArray(value) ? value.map(formatValue) : formatValue(value);
+}
+
 export function resolveCtxDatePath(pathSegments: string[]): any {
-  const segments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
+  const rawSegments = withDatePrefix((pathSegments || []).map((seg) => String(seg)));
+  const formatted = splitFormattedDateSegments(rawSegments);
+  if (!formatted) return undefined;
+  if (formatted.format) {
+    return formatResolvedDateValue(resolveCtxDatePath(formatted.baseSegments), formatted.format);
+  }
+  const segments = formatted.baseSegments;
   if (segments[0] !== 'date') return undefined;
 
   if (segments[1] === 'preset' && segments.length === 3) {