@aliens-syndicate/cli 0.1.2 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +35 -8
- package/package.json +5 -1
- package/tools/build.mjs +326 -26
- package/tools/cli.mjs +10 -5
- package/tools/create.mjs +12 -3
- package/tools/icon-docs.mjs +132 -0
- package/tools/runtime.mjs +216 -8
- package/tools/starter/ai/agents/codingbot.agent +5 -0
- package/tools/starter/ai/rules/architecture.rule +11 -0
- package/tools/starter/ai/skills/create-element.skill +6 -0
- package/tools/starter/app/elements/molecules/kit-card-link/kit-card-link.markup +0 -2
- package/tools/starter/app/pages/kit-overview/kit-overview.markup +6 -6
- package/tools/starter/app/pages/style-guide/style-guide.style +57 -57
- package/tools/starter/styles/components/alerts.style +6 -5
- package/tools/starter/styles/components/badges.style +6 -5
- package/tools/starter/styles/components/borders.style +2 -1
- package/tools/starter/styles/components/buttons.style +14 -13
- package/tools/starter/styles/components/cards.style +1 -1
- package/tools/starter/styles/components/feedback.style +3 -2
- package/tools/starter/styles/components/forms.style +5 -4
- package/tools/starter/styles/components/tables.style +4 -3
- package/tools/starter/styles/components/typography.style +6 -5
- package/tools/starter/styles/generic/ui-base.style +1 -1
- package/tools/starter/styles/objects/ui-layout.style +1 -1
- package/tools/style-docs.mjs +274 -0
- package/tools/vscode-space/package.json +5 -8
- package/tools/vscode-space/space.tmLanguage.json +1 -1
- package/tools/vscode-space/syntax.cjs +103 -62
- package/tools/watch.mjs +48 -0
- package/README.es-ES.md +0 -222
- package/README.pt-BR.md +0 -222
- package/README.zh-CN.md +0 -222
package/README.zh-CN.md
DELETED
|
@@ -1,222 +0,0 @@
|
|
|
1
|
-
# Aliens Framework · 文档
|
|
2
|
-
|
|
3
|
-
[English](README.md) · [Português](README.pt-BR.md) · [Español](README.es-ES.md) · **中文**
|
|
4
|
-
|
|
5
|
-
应用源码位于 `project/`。页面位于 `project/app/pages/`,可复用的 Element 位于 `project/app/elements/`。图片位于 `project/assets/`,翻译位于 `project/language/`,全局样式位于 `project/styles/`。构建会读取 `.config` 并为 CodingBot 生成 `ai/.map`。这两个文件都使用相对于工作区根目录的路径。Space 工具位于 `project/` 旁边的 `tools/`。
|
|
6
|
-
|
|
7
|
-
## 创建项目
|
|
8
|
-
|
|
9
|
-
```sh
|
|
10
|
-
node tools/create.mjs my-project
|
|
11
|
-
cd my-project
|
|
12
|
-
node tools/build.mjs
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
同一个生成器已作为 `@aliens-syndicate/cli` 发布到 npm,无需克隆仓库即可使用。`aliens build` 命令会运行当前项目中的 `tools/build.mjs`。
|
|
16
|
-
|
|
17
|
-
```sh
|
|
18
|
-
npx @aliens-syndicate/cli create my-project
|
|
19
|
-
cd my-project
|
|
20
|
-
npx @aliens-syndicate/cli build
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
要发布新版本,请更新 `package.json` 中的 `version`,并在已登录 `aliens-syndicate` 账号的情况下于根目录运行 `npm publish`。
|
|
24
|
-
|
|
25
|
-
生成器会在 `project/app/pages/home/` 中创建首页,并创建四个 Element 层级以及应用各文件类型的文件夹。英雄目录的注释示例来自引擎基础目录 `tools/starter/`,与当前打开的应用无关。`hero-card` Element 在 `project/app/elements/molecules/hero-card/` 中包含 `.markup`、`.logic`、`.style` 和 `.test`。`agents/`、`rules/` 和 `skills/` 文件夹位于 `ai/`。
|
|
26
|
-
|
|
27
|
-
每个示例都有一段说明,后面跟着一行只包含 `#` 的内容。要试用示例,请删除该行下方代码行的 `# ` 前缀,并保持每级三个空格。在卡片示例中,取消 `hero-card.markup`、`hero-card.logic` 和 `hero-card.style` 的注释,并在某个页面的 markup 中加入 `hero-card`。
|
|
28
|
-
|
|
29
|
-
在 `project/app/routes/` 中,注释示例展示了固定路由和子路由、参数、过滤器、重定向、guard、状态和回退。路由和 `.test` 文件的执行属于 runtime 的待办工作。
|
|
30
|
-
|
|
31
|
-
## 样式库与主题
|
|
32
|
-
|
|
33
|
-
每个新项目都会打开一个用 Space 编写、可浏览的样式库,包含七个视图以及葡萄牙语、英语、西班牙语和中文示例。在文档站点中,首页的 **样式库** 按钮会打开 `#kit-overview`。
|
|
34
|
-
|
|
35
|
-
- `project/styles/settings/` 汇集颜色、间距、圆角、边框、字体和阴影 token。
|
|
36
|
-
- `project/styles/components/` 提供 H1–H6 字体、段落、辅助文本、说明文字、链接、列表、引用和代码;按钮、输入框、卡片、标签、提示、边框、间距、表格、进度条和可展开面板。
|
|
37
|
-
- `project/styles/settings/theme.style` 集中定义样式库 `light` 和 `dark` 主题的语义值。组件通过 CSS 变量使用这些值。
|
|
38
|
-
- `project/app/pages/kit-*/` 包含示例页面。可复用的 Element 位于 Atomic Design 各层级中。
|
|
39
|
-
|
|
40
|
-
要创建新主题,请在 `theme.style` 末尾添加一个代码块,名称由小写字母、数字和连字符组成,并以字母开头。未重新定义的值会继承 `:root` 的浅色基础。要创建完整的深色主题,请复制 `dark` 代码块,修改名称并自定义其 token。
|
|
41
|
-
|
|
42
|
-
```text
|
|
43
|
-
:root[data-theme="ocean"]
|
|
44
|
-
color-scheme: light
|
|
45
|
-
--color-brand: #075985
|
|
46
|
-
--color-brand-hover: #0c4a6e
|
|
47
|
-
--color-on-brand: #ffffff
|
|
48
|
-
--color-focus: #075985
|
|
49
|
-
--color-accent: #e0f2fe
|
|
50
|
-
--color-on-accent: #0c4a6e
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
编辑后运行构建。引擎会识别文件中的代码块,将主题加入选择器,并在页面重新加载后保留偏好。示例展示的是 `.style` 文件中的真实代码。生成器的基础文件位于 `tools/starter/`;某个项目的自定义内容不会复制到之后的项目中。
|
|
54
|
-
|
|
55
|
-
## Atomic Design
|
|
56
|
-
|
|
57
|
-
- `atoms/` 包含基础元素,例如按钮、链接和主题控件。
|
|
58
|
-
- `molecules/` 包含职责明确的组件,例如搜索、语言选择器和计数器。
|
|
59
|
-
- `organisms/` 包含组合结构,例如页头、指南网格和演练场。
|
|
60
|
-
- `templates/` 包含参考面板的可复用布局。
|
|
61
|
-
|
|
62
|
-
类型目录位于页面旁边的 `project/app/pages/type-index/`,并使用 `type-summary` 模板构建可导航的面板。每个 Element 都把自己的 Space 文件保存在各自的文件夹中。
|
|
63
|
-
|
|
64
|
-
## Space 约定
|
|
65
|
-
|
|
66
|
-
具名文件的声明头以类型和 PascalCase 名称开头。正文每级使用三个空格。字段和契约使用显式类型。声明式注释以 `#` 开头。
|
|
67
|
-
|
|
68
|
-
```text
|
|
69
|
-
Markup App
|
|
70
|
-
home
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
该示例位于 `project/app/app.markup`。其他声明头包括 `Logic App`、`Style App` 和 `Pipe Currency`。`.config`、`.env`、`ai/.map` 和翻译文件有各自的 Space 结构。构建会校验项目源码中的声明头和缩进。代码示例在两种主题中都使用 Space 配色。
|
|
74
|
-
|
|
75
|
-
### 命名:element-child_modifier:state
|
|
76
|
-
|
|
77
|
-
`.markup`、`.style` 和 `.logic` 使用相同的名称,且始终为小写。每个分隔符都有各自的作用:
|
|
78
|
-
|
|
79
|
-
| 概念 | 分隔符 | 示例 |
|
|
80
|
-
| --- | --- | --- |
|
|
81
|
-
| Element | 仅使用其自身名称 | `site-header` |
|
|
82
|
-
| 子元素 | `-` | `site-header-logo` |
|
|
83
|
-
| 修饰符 | `_` | `site-header-logo_large` |
|
|
84
|
-
| 状态 | `:` | `site-header-logo_large:hover` |
|
|
85
|
-
|
|
86
|
-
顺序为 `element-child_modifier:state`。Element 的文件夹和文件遵循 Element 名称,例如 `site-header/site-header.markup`。构建通过已知名称识别 Element:`site-header-logo` 属于 `site-header`。每个名称最多有一个修饰符。状态是 CSS 伪类,只出现在 `.style` 中。
|
|
87
|
-
|
|
88
|
-
#### Markup
|
|
89
|
-
|
|
90
|
-
`id` 命名单个标签。`variant` 命名多个标签共享的样式。markup 不接受 `class`。名称必须以编写它的 Element、渲染它的 Element 或 `space` 库开头。修饰符会自动带上基础名称:`variant="counter-button_increase"` 会生成 `class="counter-button counter-button_increase"`。
|
|
91
|
-
|
|
92
|
-
```text
|
|
93
|
-
Markup Counter
|
|
94
|
-
section id="counter"
|
|
95
|
-
output={0} id="counter-value"
|
|
96
|
-
div id="counter-controls"
|
|
97
|
-
button variant="counter-button" action="decrement" text="−" label={@counter.decrement}
|
|
98
|
-
button variant="counter-button_increase" action="increment" text="+" label={@counter.increment}
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
当 `id` 重复、某个名称同时是 `id` 和 `variant`、与 HTML 标签同名或不符合格式时,构建会拒绝该页面。
|
|
102
|
-
|
|
103
|
-
#### Style
|
|
104
|
-
|
|
105
|
-
书写名称时不要加 `#` 或 `.`。构建会为 `id` 生成 `[id="name"]`,为 `variant` 生成 `.name`,两者在层叠中权重相同。要在同一标签上组合两个名称,请使用 `:is()`,例如 `space-card:is(space-border_strong)`。既不是 `id`、`variant`,也不是 HTML 标签的名称会报错。`project/styles/` 中的全局样式声明样式库的 variant,始终带有 `space-` 前缀,例如 `space-button_primary`。
|
|
106
|
-
|
|
107
|
-
```text
|
|
108
|
-
Style Counter
|
|
109
|
-
counter-button
|
|
110
|
-
border: 1px solid var(--line-strong)
|
|
111
|
-
counter-button_increase
|
|
112
|
-
background: var(--primary)
|
|
113
|
-
counter-button:hover
|
|
114
|
-
border-color: var(--accent-stroke)
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
#### Logic
|
|
118
|
-
|
|
119
|
-
`bind:` 列出 Element 的每个 `id`,以及 signal 在该标签上设置的内容。表达式使用与 `body:` 相同的 JavaScript。`_modifier` 条目会在标签上切换修饰符:`home` 上的 `_menu-open` 会应用 `home_menu-open`。`page:` 指定控制页面主题或语言的 signal。
|
|
120
|
-
|
|
121
|
-
```text
|
|
122
|
-
Logic Home
|
|
123
|
-
signal menuOpen: boolean = false
|
|
124
|
-
|
|
125
|
-
bind:
|
|
126
|
-
home:
|
|
127
|
-
_menu-open: this.menuOpen
|
|
128
|
-
site-header-menu-toggle:
|
|
129
|
-
expanded: this.menuOpen
|
|
130
|
-
|
|
131
|
-
actions:
|
|
132
|
-
toggleMenu:
|
|
133
|
-
returns: void
|
|
134
|
-
body:
|
|
135
|
-
this.menuOpen = !this.menuOpen
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
| `bind:` 中的条目 | 对标签的效果 |
|
|
139
|
-
| --- | --- |
|
|
140
|
-
| `text` | 用该值替换文本。 |
|
|
141
|
-
| `show` | 值为真时显示标签。 |
|
|
142
|
-
| `pressed` | 设置 `aria-pressed`。 |
|
|
143
|
-
| `expanded` | 设置 `aria-expanded`。 |
|
|
144
|
-
| `_modifier` | 值为真时应用 `id_modifier`。 |
|
|
145
|
-
|
|
146
|
-
格式为 `<element>-<signal>` 的 `id` 无需 `bind:` 即可显示文本:`counter-value` 会在 Counter 中显示 `value`。在 action 的 body 中,`element("counter-title")` 会返回该标签。`bind:` 可以作用于 Element 自身的标签,以及没有 `.logic` 的子 Element 的标签。markup 不接受 `data-show`、`data-pressed`、`data-expanded`、`data-state`、`data-bind`、`data-theme-control` 和 `data-language` 属性。signal 和 action 是 JavaScript 标识符,保持 camelCase,例如 `menuOpen` 和 `toggleMenu`。
|
|
147
|
-
|
|
148
|
-
原生标签接受与 Element 相同的简写属性:`variant` 变为 `class`,`action` 变为 `data-action`,`label` 变为 `aria-label`,`text` 变为标签文本。未声明 `type` 的 `button` 会获得 `type="button"`。
|
|
149
|
-
|
|
150
|
-
### 只包含所需文件的 Element
|
|
151
|
-
|
|
152
|
-
Element 是同一文件夹中同名文件的集合。没有任何文件是必需的,构建通过名称和扩展名识别每个文件。
|
|
153
|
-
|
|
154
|
-
| 文件 | Element 的作用 |
|
|
155
|
-
| --- | --- |
|
|
156
|
-
| `badge.markup` 和 `badge.style` | 渲染结构和外观。 |
|
|
157
|
-
| `counter.markup`、`counter.logic` 和 `counter.style` | 渲染并响应 action。 |
|
|
158
|
-
| `session.logic` | 为页面运行单个实例,不渲染任何内容。 |
|
|
159
|
-
| `spinner.style` | 提供以 Element 命名的 variant,例如 `spinner` 和 `spinner_large`。 |
|
|
160
|
-
|
|
161
|
-
- **只有 `.logic` 的 Element:** markup 通过 Element 名称调用其 action,例如 `action="session.logout"`。`page:` 同样可用。由于没有标签,`bind:` 会报错。
|
|
162
|
-
- **只有 `.style` 的 Element:** 任何 markup 都可以通过 `variant="spinner_large"` 使用其名称。该 `.style` 只能声明以 Element 自身名称开头的名称。
|
|
163
|
-
- **使用错误:** 把没有 `.markup` 的 Element(例如 `spinner` 或 `session`)当作标签使用会报错。既不是 HTML 也不是 Element 的标签,以及与 HTML 标签同名的 Element(例如 `button`)同样会报错。
|
|
164
|
-
|
|
165
|
-
构建按需校验。每个已渲染标签的 `action` 都必须存在于其自身 Element 或外层 Element 的 `.logic` 中。带有 Element 名称的 action(例如 `session.logout`)必须存在于该 Element 中。拼写错误会在构建时连同文件和行号一起显示。
|
|
166
|
-
|
|
167
|
-
编译是按需进行的。构建会校验所有文件,但输出只包括:
|
|
168
|
-
|
|
169
|
-
- 页面渲染的 Element 的样式和逻辑;
|
|
170
|
-
- 名称被某个标签使用的、只有 `.style` 的 Element;
|
|
171
|
-
- 被某个标签调用或声明了 `page:` 的、只有 `.logic` 的 Element。
|
|
172
|
-
|
|
173
|
-
`project/styles/` 中的全局样式始终会被包含。
|
|
174
|
-
|
|
175
|
-
## Space 编辑器
|
|
176
|
-
|
|
177
|
-
`tools/vscode-space/` 中的扩展会在编辑器中注册 Space 模式和语义高亮。在 `.style` 文件中,颜色属性里的十六进制、RGB、HSL 字面量以及 CSS 颜色名称会显示可交互的色块。选择器只编辑所选的字面量,并保留十六进制透明度。
|
|
178
|
-
|
|
179
|
-
请在编辑器配置中安装该扩展,以便文件在普通窗口中以 Space 模式打开。在可以使用 `vsce` 的情况下,在 `tools/vscode-space/` 中运行 `vsce package`,然后在扩展面板中使用 **Install from VSIX**。重新加载窗口,并确认状态栏中显示 **Space**。
|
|
180
|
-
|
|
181
|
-
要开发该扩展,请从包含 `project/` 和 `tools/` 的文件夹打开一个临时 VS Code 窗口。
|
|
182
|
-
|
|
183
|
-
```sh
|
|
184
|
-
code --extensionDevelopmentPath="$PWD/tools/vscode-space" "$PWD"
|
|
185
|
-
```
|
|
186
|
-
|
|
187
|
-
打开 `project/styles/settings/tokens.style`,点击颜色旁边的色块。生成器会在 `.vscode/settings.json` 中加入该扩展和 Space 语义配色。
|
|
188
|
-
|
|
189
|
-
## 打开预览
|
|
190
|
-
|
|
191
|
-
在包含 `project/` 和 `tools/` 的文件夹中生成页面,并在 Chrome 中打开结果。预览已在 Node.js 26.13.0 上验证。
|
|
192
|
-
|
|
193
|
-
```sh
|
|
194
|
-
node tools/build.mjs
|
|
195
|
-
open -a "Google Chrome" dist/index.html
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
要通过 HTTP 测试,请运行 `python3 -m http.server 4173 --bind 127.0.0.1 --directory dist` 并打开[本地预览](http://127.0.0.1:4173/)。编辑 Space 文件后,请重新运行构建并刷新页面。
|
|
199
|
-
|
|
200
|
-
## 包含的内容
|
|
201
|
-
|
|
202
|
-
- 落地页形式的首页:页头菜单(文件、Playground、Styles、Markup、Logic、语言和主题)、可复制安装命令的输入框,以及关于 AI、无必需文件的 Element、集各框架之所长和 Space 语言的章节。文件页面列出 25 种类型并支持搜索,每个链接都会打开对应类型的面板。搜索位于页头,可通过 ⌘K 或 Ctrl+K 打开。面向 AI 智能体(`#ai-guide`)和路线图(`#roadmap`)页面链接在首页页脚,每个代码块都有复制按钮。`.logic` 包含介绍、架构决策、教程和演练场。
|
|
203
|
-
- 演练场包含一个可用的计数器,以及三个标签页,直接显示 `counter.logic`、`counter.markup` 和 `counter.style` 文件的内容。要尝试不同的初始值,请按照教程修改本地文件并重新生成预览。
|
|
204
|
-
- 提供英语、巴西葡萄牙语、西班牙语和简体中文翻译。首次访问时使用浏览器偏好;没有匹配的偏好时默认使用英语。在浏览器提供存储时,会保存手动选择的语言。
|
|
205
|
-
|
|
206
|
-
## 原型的发现
|
|
207
|
-
|
|
208
|
-
- `aliens-exemplo` 工具只演示了样式表编译。`tools/` 中的预览是为渲染 Element 组合、应用翻译、运行计数器 action 和切换面板而创建的。界面代码保留在各个 Element 的文件中。
|
|
209
|
-
- markup 通过 `action` 调用 action,`.logic` 在 `bind:` 块中通过 `id` 将 signal 绑定到标签。这些约定、Element 属性语法和翻译格式在成为最终语法的一部分之前还需要验证。
|
|
210
|
-
- 预览编译器覆盖文档中使用的基本 signal 和无参数 action。它会去掉 TypeScript 注解,但不做语义类型检查。生命周期、模块之间的真实依赖、服务以及 `.test` 文件的执行仍待完成。页面导航使用 URL 片段。`app.route` 文件登记了初始路由,但仍需要路由器来执行它。
|
|
211
|
-
- 索引遵循 25 种类型的目录。`.style` 和 `.mock` 分别是为样式表和模拟数据定义的扩展名。
|
|
212
|
-
- 演练场的标签页复用页面编译的代码。模拟是可交互的,文件在浏览器中只读。演练场中的编辑功能要等到有独立的方式编译和运行输入的代码之后再实现。
|
|
213
|
-
|
|
214
|
-
## 验证
|
|
215
|
-
|
|
216
|
-
构建已通过,生成的 JavaScript 已通过 `node --check` 检查。在浏览器中检查了首页、小屏幕上的菜单、主题链接、代码标签页,以及计数器上的点击和键盘操作。最终的首页在 Chrome 中以浏览器检测到的葡萄牙语打开。在编译后的 runtime 中验证了七种语言偏好场景、四个手动选择器,以及显示的代码与三个源文件是否一致。
|
|
217
|
-
|
|
218
|
-
样式库在一个新项目以及由该项目的生成器创建的另一个项目中完成了验证。检查了链接、唯一 ID、Space 缩进、四种语言、390 px 下的 H1–H6,以及主题选择器的同步。仅在临时项目中添加了一个额外主题,用于验证构建能否识别它并在浏览器中应用。
|
|
219
|
-
|
|
220
|
-
## 许可证
|
|
221
|
-
|
|
222
|
-
Aliens Framework 采用 [MIT 许可证](LICENSE)发布。
|