[RFC] more semantic & descriptive API names?

[alexzhang1030]

Summary

Vue Vine's API is much clearer now, but the names are not semantic, especially for someone who only knows Vue SFC and is trying to play Vue Vine.

Some Vue and Vue Vine APIs are equivalent, such as vineEmits or vineSlots.

Vue Vine and Vue SFC use the same backend @vue/compiler-dom to compile templates, using consistent and descriptive API names can help users quickly grasp and understand the related concepts in Vue Vine.

API Changes Overview

• vineEmits() -> defineEmits()
• vineOptions() -> defineOptions()
• vineExpose() -> defineExpose()
• vineSlots() -> defineSlots()

For styles:

• vineStyle(scss()) -> style(scss()) or just scss()
• vineStyle.scoped(scss()) -> style.scoped(scss()) or just scss.scoped()

For template:

• vine -> html or template.html
• for pug -> pug or template.pug

For new features (that Vue doesn't have), we should align as closely as possible with Vue

• vineProp() -> defineProp()
• vineProp().withDefault() -> defineProp().withDefault()

Changes Challenge

Well, maybe zero cost. We use .vine.ts as a Vue Vine file extension, so we should not worry about duplicate name issues. For our LSP, the same as above.

[ShenQingchuan]

如果你想看中文版回复，点这里 ...

收到你的建议我很感动！非常感谢你的思考。

关于 宏 API 设计

的确，更语义化的、更直观易懂的 API 是每个框架的设计理想，但在此，关于和 Vue API 保持一致这方面我有一些不同的意见想要分享。

首先，必须要强调的是 Vine 的设计初衷：Vine 目前乃至今后的很长一段时间都只是想要作为一个第三方库，或者说一个和 SFC 并行的解决方案提供，因此，我希望 Vue Vine 的 API 可以一眼看上去不同。

其次，诸如 vineEmits、vineExpose、vineSlots 这样的宏虽然用途上和 Vue 原生相对应的宏 API 没有特别大的差别，但我们之所以在 Vue Vine 这个解决方案里自己构建宏，就是希望我们能够对宏这个功能机制有所控制，以便我们在这样一套完全不同的写法中保留未来扩展更多自定义写法的能力。

第三，从架构分层上讲，我们这个方案应该是 compiler-vine 之于 compiler-sfc，所以容易想到我们非常有可能会有一部分编译的工作和原有存在的内容在功能性上有重复，但因为目的是一套全新的写法，所以我认为这都是可以接受的。同样也是因为这个原因，我不愿意在设计上引导用户再在我们这套解决方案中使用 compiler-sfc 的 API / 宏

另外，在类型定义方面，vineEmits、vineExpose 作为宏的 TypeScript 类型定义是由一份我们新编写的、针对我们的需求精简化后的 .d.ts 文件提供、并注入到 TS 全局环境的，我想要尽可能地避免依赖 Vue 在 compiler-sfc 包中导出的宏 API 的类型。

关于 样式和模板相关的 API 设计

诚然我的确也是一个非常喜欢 API 名称短小精悍的人，但是对于 style 这个单词在前端项目中的使用还是需要非常谨慎的，这个词太过常见了。同样还是上面提到的类型定义相关的问题，我们的宏相当于在 .d.ts 文件中作为一个虚构的全局函数占据了一个名字，我不希望这个名字能够在用户代码中被过多的 shadowing（覆盖），这是一种或许运行起来功能上无害、但直觉和思考层面怎么想都怪怪的感觉。

模板在 pug 相关的支持我还没有考虑的那么长远，但是可能后面会考虑支持为 vine.pug

关于对目前来说对改造成本

首先要遗憾地说，肯定不是零成本的！因为针对宏 API、相关“关键字”（例如 vineStyle、vine 模板字符串函数）的解析逻辑都是 compiler 包中非常重要的逻辑，因为临近 VueConf 2024 CN，同时我们也已经 0.1 版本，我还是尽可能地希望保持稳定，如果要改造需要更谨慎慎重。

但我当然不会完全关闭任何讨论的可能性，也并不是说现有的设计就是十全十美的，只是分享我设计之初的考量和取舍。

---

I am deeply moved by your suggestion and very grateful for your thoughts.

Regarding Macro API Design

Certainly, a more semantic and intuitive API is the ideal for every framework design. However, I have some differing opinions on aligning with Vue API that I would like to share.

Firstly, it is essential to emphasize the design intent of Vine: Vine is intended to be a third-party library or a parallel solution to SFC for the foreseeable future. Therefore, I hope that the API of Vue Vine can be visually distinct at a glance.

Secondly, while macros like vineEmits, vineExpose, and vineSlots serve similar purposes to their Vue-native counterparts, we have built our own macros in Vue Vine to maintain control over the macro functionality. This allows us to retain the ability to expand more custom syntax in the future within this entirely different writing style.

Thirdly, from an architectural perspective, our solution should be compiler-vine in relation to compiler-sfc. It is conceivable that some of our compilation work may overlap with existing content in terms of functionality. However, since our aim is to introduce a completely new writing style, I believe these overlaps are acceptable. For the same reason, I am reluctant to guide users to use compiler-sfc's API/macros within our solution.

Additionally, regarding type definitions, the TypeScript type definitions for vineEmits and vineExpose, as macros, are provided by a newly written, simplified .d.ts file tailored to our needs and injected into the TS global environment. I aim to minimize reliance on the types of the macros exported by Vue in the compiler-sfc package.

Regarding the Design of Style and Template-related APIs

Indeed, I am also a fan of short and concise API names, but we must be very cautious about using the word "style" in frontend projects; it is too common. The same issue arises with type definitions; our macros act as a fictional global function in the .d.ts file, occupying a name. I do not want this name to be shadowed (overridden) too much in user code. This might be harmless in terms of functionality, but it feels odd intuitively and conceptually.

I have not yet considered the support for pug in templates in the long term, but I may consider supporting it as vine.pug later.

Regarding the Transformation Cost at Present

Firstly, I must regretfully say that it is not zero cost! The parsing logic for macro APIs and related "keywords" (e.g., vineStyle, vine template string functions) are crucial to the compiler package. As we approach VueConf 2024 CN and have already released version 0.1, I am keen to maintain stability. Any transformation would require careful and cautious consideration.

However, I will not completely close the door to discussion, nor am I suggesting that the current design is perfect. I am merely sharing the considerations and trade-offs I made at the beginning of the design process.