@aliens-syndicate/cli 0.1.0 → 0.1.2

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License
2
+
3
+ Copyright (c) 2026 Aliens Syndicate
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
@@ -0,0 +1,222 @@
1
+ # Aliens Framework · Documentación
2
+
3
+ [English](README.md) · [Português](README.pt-BR.md) · **Español** · [中文](README.zh-CN.md)
4
+
5
+ Las fuentes de la aplicación están en `project/`. Las páginas están en `project/app/pages/` y los Elements reutilizables en `project/app/elements/`. Las imágenes están en `project/assets/`, las traducciones en `project/language/` y los estilos globales en `project/styles/`. El build lee `.config` y genera `ai/.map` para el CodingBot. Ambos archivos usan rutas relativas a la raíz del workspace. Las herramientas de Space están en `tools/`, junto a `project/`.
6
+
7
+ ## Crear un proyecto
8
+
9
+ ```sh
10
+ node tools/create.mjs mi-proyecto
11
+ cd mi-proyecto
12
+ node tools/build.mjs
13
+ ```
14
+
15
+ El mismo generador está publicado en npm como `@aliens-syndicate/cli` y funciona sin clonar el repositorio. El comando `aliens build` ejecuta el `tools/build.mjs` del proyecto en el que estás.
16
+
17
+ ```sh
18
+ npx @aliens-syndicate/cli create mi-proyecto
19
+ cd mi-proyecto
20
+ npx @aliens-syndicate/cli build
21
+ ```
22
+
23
+ Para publicar una nueva versión, actualiza `version` en `package.json` y ejecuta `npm publish` en la raíz, con la cuenta `aliens-syndicate` conectada en npm.
24
+
25
+ El generador crea la Home en `project/app/pages/home/`, los cuatro niveles de Elements y las carpetas de los tipos de archivo de la aplicación. Los ejemplos comentados del catálogo de héroes vienen de la base del motor en `tools/starter/`, independientemente de la aplicación que tengas abierta. El Element `hero-card` reúne `.markup`, `.logic`, `.style` y `.test` en `project/app/elements/molecules/hero-card/`. Las carpetas `agents/`, `rules/` y `skills/` están en `ai/`.
26
+
27
+ Cada ejemplo tiene una descripción seguida de una línea que contiene solo `#`. Para probarlo, quita el prefijo `# ` de las líneas de código debajo de esa línea, manteniendo tres espacios por nivel. En la tarjeta, descomenta `hero-card.markup`, `hero-card.logic` y `hero-card.style` e incluye `hero-card` en el markup de una página.
28
+
29
+ En `project/app/routes/`, los ejemplos comentados muestran rutas fijas e hijas, parámetros, filtros, redirecciones, guards, estado y fallback. La ejecución de rutas y de archivos `.test` forma parte del trabajo pendiente en el runtime.
30
+
31
+ ## Biblioteca de estilos y temas
32
+
33
+ Cada proyecto nuevo abre con una biblioteca de estilos navegable escrita en Space, con siete vistas y ejemplos en portugués, inglés, español y chino. En el sitio de la documentación, el botón **Biblioteca de estilos** de la Home abre `#kit-overview`.
34
+
35
+ - `project/styles/settings/` reúne los tokens de color, espaciado, radio, borde, tipografía y elevación.
36
+ - `project/styles/components/` ofrece tipografía H1–H6, párrafo, texto auxiliar, leyenda, enlace, lista, cita y código; botones, campos, tarjetas, etiquetas, avisos, bordes, espaciado, tabla, progreso y panel desplegable.
37
+ - `project/styles/settings/theme.style` centraliza los valores semánticos de los temas `light` y `dark` de la biblioteca. Los componentes usan esos valores mediante variables CSS.
38
+ - `project/app/pages/kit-*/` contiene las páginas de muestras. Los Elements reutilizables están en los niveles de Atomic Design.
39
+
40
+ Para crear otro tema, añade un bloque al final de `theme.style`, con un nombre en minúsculas, números y guiones, que empiece por una letra. Los valores que no redefinas heredan la base clara de `:root`. Para un tema oscuro completo, copia el bloque `dark`, cámbiale el nombre y personaliza sus tokens.
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
+ Ejecuta el build después de editar. El motor reconoce los bloques del archivo y añade los temas al selector, manteniendo la preferencia entre recargas. Las muestras enseñan el código real de los archivos `.style`. La base del generador está en `tools/starter/`; las personalizaciones de un proyecto no se copian a los siguientes.
54
+
55
+ ## Atomic Design
56
+
57
+ - `atoms/` contiene elementos básicos, como botones, enlaces y controles de tema.
58
+ - `molecules/` contiene componentes con una función concreta, como la búsqueda, el selector de idioma y el contador.
59
+ - `organisms/` contiene composiciones como el encabezado, la cuadrícula de guías y el playground.
60
+ - `templates/` contiene el layout reutilizable de los paneles de referencia.
61
+
62
+ El catálogo de tipos está en `project/app/pages/type-index/`, junto a las páginas, y usa el template `type-summary` para montar los paneles navegables. Cada Element mantiene sus archivos Space en su propia carpeta.
63
+
64
+ ## Convenciones de Space
65
+
66
+ El encabezado de los archivos con nombre empieza por el tipo y el nombre en PascalCase. El cuerpo usa tres espacios por nivel. Los campos y contratos usan tipos explícitos. Los comentarios declarativos empiezan por `#`.
67
+
68
+ ```text
69
+ Markup App
70
+ home
71
+ ```
72
+
73
+ El ejemplo está en `project/app/app.markup`. Otros encabezados son `Logic App`, `Style App` y `Pipe Currency`. `.config`, `.env`, `ai/.map` y los archivos de traducción tienen sus propias estructuras Space. El build valida el encabezado y la indentación en las fuentes del proyecto. Los ejemplos de código usan la paleta de Space en ambos temas.
74
+
75
+ ### Nombres: element-hijo_modificador:estado
76
+
77
+ `.markup`, `.style` y `.logic` usan los mismos nombres, siempre en minúsculas. Cada separador tiene un papel:
78
+
79
+ | Concepto | Separador | Ejemplo |
80
+ | --- | --- | --- |
81
+ | Element | ninguno además de su propio nombre | `site-header` |
82
+ | Hijo | `-` | `site-header-logo` |
83
+ | Modificador | `_` | `site-header-logo_large` |
84
+ | Estado | `:` | `site-header-logo_large:hover` |
85
+
86
+ El orden es `element-hijo_modificador:estado`. Las carpetas y archivos de Elements siguen el nombre del Element, como `site-header/site-header.markup`. El build reconoce el Element por su nombre conocido: `site-header-logo` pertenece a `site-header`. Cada nombre tiene como máximo un modificador. El estado es una pseudoclase de CSS y aparece solo en `.style`.
87
+
88
+ #### Markup
89
+
90
+ `id` nombra una etiqueta. `variant` nombra un estilo compartido por varias etiquetas. El markup no acepta `class`. Un nombre empieza por el Element que lo escribe, por un Element que lo renderiza o por la biblioteca `space`. El modificador ya incluye la base: `variant="counter-button_increase"` genera `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
+ El build rechaza la página cuando un `id` se repite, cuando un nombre es `id` y `variant` a la vez, cuando coincide con una etiqueta HTML o cuando no sigue el formato.
102
+
103
+ #### Style
104
+
105
+ Escribe el nombre sin `#` ni `.`. El build genera `[id="nombre"]` para un `id` y `.nombre` para un `variant`, con el mismo peso en la cascada. Para combinar dos nombres en la misma etiqueta, usa `:is()`, como en `space-card:is(space-border_strong)`. Los nombres que no son `id`, `variant` ni etiqueta HTML generan un error. Los estilos globales de `project/styles/` declaran los variants de la biblioteca, siempre con el prefijo `space-`, como `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:` lista cada `id` del Element con lo que un signal define en la etiqueta. Las expresiones usan el mismo JavaScript que `body:`. Una entrada `_modificador` activa y desactiva el modificador en la etiqueta: `_menu-open` en `home` aplica `home_menu-open`. `page:` indica el signal que controla el tema o el idioma de la página.
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
+ | En `bind:` | Efecto en la etiqueta |
139
+ | --- | --- |
140
+ | `text` | Sustituye el texto por el valor. |
141
+ | `show` | Muestra la etiqueta cuando el valor es verdadero. |
142
+ | `pressed` | Define `aria-pressed`. |
143
+ | `expanded` | Define `aria-expanded`. |
144
+ | `_modificador` | Aplica `id_modificador` mientras el valor sea verdadero. |
145
+
146
+ Un `id` con el formato `<element>-<signal>` no necesita `bind:` para el texto: `counter-value` muestra `value` en Counter. En el cuerpo de una acción, `element("counter-title")` devuelve la etiqueta. `bind:` alcanza las etiquetas del propio Element y las de Elements hijos sin `.logic`. Los atributos `data-show`, `data-pressed`, `data-expanded`, `data-state`, `data-bind`, `data-theme-control` y `data-language` no se aceptan en el markup. Los signals y las actions son identificadores JavaScript y siguen en camelCase, como `menuOpen` y `toggleMenu`.
147
+
148
+ Las etiquetas nativas aceptan las mismas propiedades cortas que los Elements: `variant` se convierte en `class`, `action` en `data-action`, `label` en `aria-label` y `text` en el texto de la etiqueta. `button` recibe `type="button"` cuando no declara `type`.
149
+
150
+ ### Elements con solo los archivos necesarios
151
+
152
+ Un Element es el conjunto de archivos con el mismo nombre en la misma carpeta. Ningún archivo es obligatorio, y el build reconoce cada uno por su nombre y extensión.
153
+
154
+ | Archivos | Lo que hace el Element |
155
+ | --- | --- |
156
+ | `badge.markup` y `badge.style` | Renderiza estructura y apariencia. |
157
+ | `counter.markup`, `counter.logic` y `counter.style` | Renderiza y reacciona a acciones. |
158
+ | `session.logic` | Ejecuta una única instancia para la página y no renderiza nada. |
159
+ | `spinner.style` | Ofrece variants con el nombre del Element, como `spinner` y `spinner_large`. |
160
+
161
+ - **Element solo con `.logic`:** el markup llama a sus acciones con el nombre del Element, como en `action="session.logout"`. `page:` también funciona. Como no hay etiquetas, `bind:` genera un error.
162
+ - **Element solo con `.style`:** cualquier markup aplica sus nombres con `variant="spinner_large"`. El `.style` solo declara nombres que empiezan por el propio Element.
163
+ - **Errores de uso:** usar como etiqueta un Element sin `.markup`, como `spinner` o `session`, genera un error. Lo mismo ocurre con etiquetas que no son HTML ni Element, y con Elements que llevan el nombre de una etiqueta HTML, como `button`.
164
+
165
+ El build valida por necesidad. Cada `action` de una etiqueta renderizada debe existir en el `.logic` de su propio Element o de un Element que la rodee. Una action con nombre de Element, como `session.logout`, debe existir en ese Element. Un error de escritura aparece en el build, con archivo y línea.
166
+
167
+ La compilación es selectiva. El build valida todos los archivos, pero el resultado incluye solo:
168
+
169
+ - los estilos y la lógica de los Elements que la página renderiza;
170
+ - los Elements solo con `.style` cuyos nombres usa alguna etiqueta;
171
+ - los Elements solo con `.logic` que alguna etiqueta llama o que declaran `page:`.
172
+
173
+ Los estilos globales de `project/styles/` se incluyen siempre.
174
+
175
+ ## Editor Space
176
+
177
+ La extensión de `tools/vscode-space/` registra el modo Space y el resaltado semántico en el editor. En los archivos `.style`, los literales hexadecimales, RGB y HSL y los nombres de color CSS en propiedades de color reciben muestras interactivas. El selector edita solo el literal elegido y conserva la transparencia hexadecimal.
178
+
179
+ Instala la extensión en tu perfil del editor para que los archivos se abran en modo Space en las ventanas normales. Con `vsce` disponible, ejecuta `vsce package` en `tools/vscode-space/` y usa **Install from VSIX** en el panel de extensiones. Recarga la ventana y confirma **Space** en la barra de estado.
180
+
181
+ Para desarrollar la extensión, abre una ventana temporal de VS Code desde la carpeta que contiene `project/` y `tools/`.
182
+
183
+ ```sh
184
+ code --extensionDevelopmentPath="$PWD/tools/vscode-space" "$PWD"
185
+ ```
186
+
187
+ Abre `project/styles/settings/tokens.style` y haz clic en la muestra junto a un color. El generador incluye la extensión y la paleta semántica de Space en `.vscode/settings.json`.
188
+
189
+ ## Abrir la vista previa
190
+
191
+ En la carpeta que contiene `project/` y `tools/`, genera la página y abre el resultado en Chrome. La vista previa se verificó con Node.js 26.13.0.
192
+
193
+ ```sh
194
+ node tools/build.mjs
195
+ open -a "Google Chrome" dist/index.html
196
+ ```
197
+
198
+ Para probar por HTTP, ejecuta `python3 -m http.server 4173 --bind 127.0.0.1 --directory dist` y abre [la vista previa local](http://127.0.0.1:4173/). Después de editar archivos Space, ejecuta el build de nuevo y recarga.
199
+
200
+ ## Qué incluye
201
+
202
+ - Home en formato de landing page, con menú en el encabezado (Archivos, Playground, Styles, Markup, Logic, idioma y tema), un cuadro para copiar el comando de instalación y secciones sobre IA, Elements sin archivos obligatorios, lo mejor de cada framework y el lenguaje Space. La página Archivos lista los 25 tipos con búsqueda, y cada enlace abre el panel del tipo. La búsqueda está en el encabezado y se abre con ⌘K o Ctrl+K. Las páginas Para agentes de IA (`#ai-guide`) y Roadmap (`#roadmap`) están enlazadas en el pie de la Home, y cada bloque de código tiene un botón de copiar. `.logic` tiene introducción, decisiones de arquitectura, tutorial y playground.
203
+ - Playground con un contador funcional y tres pestañas que muestran el contenido de `counter.logic`, `counter.markup` y `counter.style` directamente desde los archivos. Para probar otro valor inicial, sigue el tutorial, cambia el archivo local y genera la vista previa de nuevo.
204
+ - Traducciones en inglés, portugués de Brasil, español y chino simplificado. La primera visita usa la preferencia del navegador, con inglés como idioma predeterminado cuando ninguna preferencia coincide. La elección manual se guarda cuando el navegador ofrece almacenamiento.
205
+
206
+ ## Lo que reveló el prototipo
207
+
208
+ - La herramienta de `aliens-exemplo` solo demostraba la compilación de hojas de estilo. La vista previa de `tools/` se creó para renderizar la composición de Elements, aplicar traducciones, ejecutar las acciones del contador y alternar paneles. El código de la interfaz permanece en los archivos de cada Element.
209
+ - El markup llama a las acciones con `action` y el `.logic` vincula los signals a las etiquetas por `id`, en el bloque `bind:`. Estas convenciones, la sintaxis de propiedades de Elements y el formato de las traducciones necesitan validación antes de formar parte de la gramática definitiva.
210
+ - El compilador de vista previa cubre los signals primitivos y las acciones sin parámetros que usa la documentación. Elimina las anotaciones TypeScript, sin comprobación semántica de tipos. El ciclo de vida, las dependencias reales entre módulos, los servicios y la ejecución de archivos `.test` quedan pendientes. La navegación de la página usa fragmentos de URL. El archivo `app.route` registra la ruta inicial y aún necesita un enrutador para ejecutarla.
211
+ - El índice sigue el catálogo de 25 tipos. `.style` y `.mock` son las extensiones definidas para hojas de estilo y datos simulados, respectivamente.
212
+ - Las pestañas del playground reutilizan el código que compila la página. La simulación es interactiva y los archivos son de solo lectura en el navegador. La edición en el playground queda para cuando exista una forma aislada de compilar y ejecutar el código escrito.
213
+
214
+ ## Validación
215
+
216
+ El build pasó y el JavaScript generado se verificó con `node --check`. En el navegador se comprobaron la Home, el menú en pantallas pequeñas, los enlaces del tema, las pestañas de código, los clics y el teclado en el contador. La Home final se abrió en Chrome en portugués detectado desde el navegador. En el runtime compilado se verificaron siete escenarios de preferencia de idioma, los cuatro selectores manuales y la igualdad entre el código mostrado y los tres archivos de origen.
217
+
218
+ La biblioteca de estilos se validó en un proyecto nuevo y en otro creado por el generador de ese proyecto. Se comprobaron los enlaces, los IDs únicos, la indentación Space, los cuatro idiomas, H1–H6 a 390 px y la sincronización de los selectores de tema. Se añadió un tema extra solo en el proyecto temporal para verificar su detección por el build y su aplicación en el navegador.
219
+
220
+ ## Licencia
221
+
222
+ Aliens Framework se distribuye bajo la [licencia MIT](LICENSE).
package/README.md CHANGED
@@ -1,41 +1,43 @@
1
- # Aliens Framework · Documentação
1
+ # Aliens Framework · Documentation
2
2
 
3
- Os fontes da aplicação ficam em `project/`. As páginas ficam em `project/app/pages/` e os Elements reutilizáveis em `project/app/elements/`. As imagens ficam em `project/assets/`, as traduções em `project/language/` e os estilos globais em `project/styles/`. O build lê `.config` e gera `ai/.map` para o CodingBot. Os dois arquivos usam caminhos relativos à raiz do workspace. As ferramentas do Space ficam em `tools/`, ao lado de `project/`.
3
+ **English** · [Português](README.pt-BR.md) · [Español](README.es-ES.md) · [中文](README.zh-CN.md)
4
4
 
5
- ## Criar um projeto
5
+ Application sources live in `project/`. Pages live in `project/app/pages/` and reusable Elements in `project/app/elements/`. Images live in `project/assets/`, translations in `project/language/` and global styles in `project/styles/`. The build reads `.config` and generates `ai/.map` for the CodingBot. Both files use paths relative to the workspace root. The Space tools live in `tools/`, next to `project/`.
6
+
7
+ ## Create a project
6
8
 
7
9
  ```sh
8
- node tools/create.mjs meu-projeto
9
- cd meu-projeto
10
+ node tools/create.mjs my-project
11
+ cd my-project
10
12
  node tools/build.mjs
11
13
  ```
12
14
 
13
- Depois da publicação do pacote `@aliens-syndicate/cli` no npm, o mesmo gerador fica disponível sem clonar o repositório. O comando `aliens build` executa o `tools/build.mjs` do projeto aberto.
15
+ The same generator is published on npm as `@aliens-syndicate/cli` and works without cloning the repository. The `aliens build` command runs the `tools/build.mjs` of the project you are in.
14
16
 
15
17
  ```sh
16
- npx @aliens-syndicate/cli create meu-projeto
17
- cd meu-projeto
18
+ npx @aliens-syndicate/cli create my-project
19
+ cd my-project
18
20
  npx @aliens-syndicate/cli build
19
21
  ```
20
22
 
21
- Para publicar uma nova versão, atualize `version` em `package.json` e execute `npm publish` na raiz, com a conta `aliens-syndicate` logada no npm.
23
+ To publish a new version, update `version` in `package.json` and run `npm publish` at the root, with the `aliens-syndicate` account logged in to npm.
22
24
 
23
- O gerador cria a Home em `project/app/pages/home/`, os quatro níveis de Elements e as pastas dos tipos de arquivo da aplicação. Os exemplos comentados do catálogo de heróis vêm da base do motor em `tools/starter/`, independente da aplicação que estiver aberta. O Element `hero-card` reúne `.markup`, `.logic`, `.style` e `.test` em `project/app/elements/molecules/hero-card/`. As pastas `agents/`, `rules/` e `skills/` ficam em `ai/`.
25
+ The generator creates the Home in `project/app/pages/home/`, the four Element levels and the folders for the application file types. The commented examples of the hero catalog come from the engine base in `tools/starter/`, regardless of the application you have open. The `hero-card` Element brings together `.markup`, `.logic`, `.style` and `.test` in `project/app/elements/molecules/hero-card/`. The `agents/`, `rules/` and `skills/` folders live in `ai/`.
24
26
 
25
- Cada exemplo tem uma descrição seguida de uma linha que contém apenas `#`. Para experimentar, remova o prefixo `# ` das linhas de código abaixo dessa linha, preservando os três espaços por nível. No cartão, descomente `hero-card.markup`, `hero-card.logic` e `hero-card.style` e inclua `hero-card` no markup de uma página.
27
+ Each example has a description followed by a line that contains only `#`. To try it, remove the `# ` prefix from the code lines below that line, keeping three spaces per level. In the card, uncomment `hero-card.markup`, `hero-card.logic` and `hero-card.style` and add `hero-card` to a page's markup.
26
28
 
27
- Em `project/app/routes/`, os exemplos comentados mostram rotas fixas e filhas, parâmetros, filtros, redirecionamento, guard, estado e fallback. A execução de rotas e de arquivos `.test` faz parte do trabalho pendente no runtime.
29
+ In `project/app/routes/`, the commented examples show fixed and child routes, parameters, filters, redirects, guards, state and fallback. Running routes and `.test` files is part of the pending runtime work.
28
30
 
29
- ## Biblioteca de estilos e temas
31
+ ## Style library and themes
30
32
 
31
- Cada projeto novo abre com uma biblioteca navegável em Space, com sete vistas e exemplos em português, inglês, espanhol e chinês. No site da documentação, o botão **Biblioteca de estilos** na Home abre `#kit-overview`.
33
+ Every new project opens with a browsable style library written in Space, with seven views and examples in Portuguese, English, Spanish and Chinese. On the documentation site, the **Style library** button on the Home opens `#kit-overview`.
32
34
 
33
- - `project/styles/settings/` reúne os tokens de cor, espaço, raio, borda, tipografia e elevação.
34
- - `project/styles/components/` fornece tipografia H1–H6, parágrafo, texto auxiliar, legenda, link, lista, citação e código; botões, campos, cartões, etiquetas, avisos, bordas, espaçamento, tabela, progresso e painel expansível.
35
- - `project/styles/settings/theme.style` centraliza os valores semânticos dos temas `light` e `dark` da biblioteca. Os componentes usam esses valores por meio de variáveis CSS.
36
- - `project/app/pages/kit-*/` contém as páginas de amostras. Os Elements reutilizáveis ficam nos níveis do Atomic Design.
35
+ - `project/styles/settings/` holds the color, spacing, radius, border, typography and elevation tokens.
36
+ - `project/styles/components/` provides H1–H6 typography, paragraph, helper text, caption, link, list, quote and code; buttons, fields, cards, badges, alerts, borders, spacing, table, progress and expandable panel.
37
+ - `project/styles/settings/theme.style` centralizes the semantic values of the library's `light` and `dark` themes. Components use these values through CSS variables.
38
+ - `project/app/pages/kit-*/` contains the sample pages. Reusable Elements live in the Atomic Design levels.
37
39
 
38
- Para criar outro tema, acrescente um bloco ao final de `theme.style`, com um nome em letras minúsculas, números e hífens, começando por letra. Os valores não redefinidos herdam a base clara de `:root`. Para um tema escuro completo, copie o bloco `dark`, troque o nome e personalize seus tokens.
40
+ To create another theme, add a block at the end of `theme.style`, with a name made of lowercase letters, numbers and hyphens, starting with a letter. Values you don't redefine inherit the light base from `:root`. For a complete dark theme, copy the `dark` block, rename it and customize its tokens.
39
41
 
40
42
  ```text
41
43
  :root[data-theme="ocean"]
@@ -48,44 +50,44 @@ Para criar outro tema, acrescente um bloco ao final de `theme.style`, com um nom
48
50
  --color-on-accent: #0c4a6e
49
51
  ```
50
52
 
51
- Execute o build após editar. O motor reconhece os blocos do arquivo e adiciona os temas ao seletor, mantendo a preferência entre recarregamentos. As amostras exibem o código real dos arquivos `.style`. A base do gerador fica em `tools/starter/`; personalizações de um projeto não são copiadas para os projetos seguintes.
53
+ Run the build after editing. The engine recognizes the blocks in the file and adds the themes to the picker, keeping the preference across reloads. The samples show the real code of the `.style` files. The generator base lives in `tools/starter/`; customizations to one project are not copied to the next ones.
52
54
 
53
55
  ## Atomic Design
54
56
 
55
- - `atoms/` contém elementos básicos, como botões, links e controles de tema.
56
- - `molecules/` contém componentes de função específica, como busca, seletor de idioma e contador.
57
- - `organisms/` contém composições como cabeçalho, menu lateral, grade de guias e playground.
58
- - `templates/` contém o layout reutilizável dos painéis de referência.
57
+ - `atoms/` contains basic elements, such as buttons, links and theme controls.
58
+ - `molecules/` contains components with a specific job, such as search, language picker and counter.
59
+ - `organisms/` contains compositions such as the header, guide grid and playground.
60
+ - `templates/` contains the reusable layout of the reference panels.
59
61
 
60
- O catálogo de tipos fica em `project/app/pages/type-index/`, junto às páginas, e usa o template `type-summary` para montar os painéis navegáveis. Cada Element mantém seus arquivos Space na própria pasta.
62
+ The type catalog lives in `project/app/pages/type-index/`, next to the pages, and uses the `type-summary` template to build the navigable panels. Each Element keeps its Space files in its own folder.
61
63
 
62
- ## Padrão Space
64
+ ## Space conventions
63
65
 
64
- O cabeçalho dos arquivos nomeados começa com o tipo e o nome em PascalCase. O corpo usa três espaços por nível. Campos e contratos usam tipos explícitos. Comentários declarativos começam com `#`.
66
+ The header of named files starts with the type and the name in PascalCase. The body uses three spaces per level. Fields and contracts use explicit types. Declarative comments start with `#`.
65
67
 
66
68
  ```text
67
69
  Markup App
68
70
  home
69
71
  ```
70
72
 
71
- O exemplo está em `project/app/app.markup`. Outros cabeçalhos são `Logic App`, `Style App` e `Pipe Currency`. `.config`, `.env`, `ai/.map` e os arquivos de tradução têm suas próprias estruturas Space. O build valida cabeçalho e indentação nos fontes do projeto. Os exemplos de código usam a paleta do Space nos dois temas.
73
+ The example is in `project/app/app.markup`. Other headers are `Logic App`, `Style App` and `Pipe Currency`. `.config`, `.env`, `ai/.map` and the translation files have their own Space structures. The build validates headers and indentation in the project sources. Code examples use the Space palette in both themes.
72
74
 
73
- ### Nomes: element-filho_modificador:estado
75
+ ### Names: element-child_modifier:state
74
76
 
75
- O `.markup`, o `.style` e o `.logic` usam os mesmos nomes, sempre em minúsculas. Cada separador tem um papel:
77
+ `.markup`, `.style` and `.logic` use the same names, always in lowercase. Each separator has a role:
76
78
 
77
- | Conceito | Separador | Exemplo |
79
+ | Concept | Separator | Example |
78
80
  | --- | --- | --- |
79
- | Element | nenhum além do próprio nome | `site-header` |
80
- | Filho | `-` | `site-header-logo` |
81
- | Modificador | `_` | `site-header-logo_large` |
82
- | Estado | `:` | `site-header-logo_large:hover` |
81
+ | Element | none besides its own name | `site-header` |
82
+ | Child | `-` | `site-header-logo` |
83
+ | Modifier | `_` | `site-header-logo_large` |
84
+ | State | `:` | `site-header-logo_large:hover` |
83
85
 
84
- A ordem é `element-filho_modificador:estado`. Pastas e arquivos de Elements seguem o nome do Element, como `site-header/site-header.markup`. O build reconhece o Element pelo nome conhecido: `site-header-logo` pertence a `site-header`. Cada nome tem no máximo um modificador. O estado é uma pseudo-classe do CSS e aparece apenas no `.style`.
86
+ The order is `element-child_modifier:state`. Element folders and files follow the Element name, as in `site-header/site-header.markup`. The build recognizes the Element by its known name: `site-header-logo` belongs to `site-header`. Each name has at most one modifier. The state is a CSS pseudo-class and appears only in `.style`.
85
87
 
86
88
  #### Markup
87
89
 
88
- O `id` nomeia uma tag. O `variant` nomeia um estilo compartilhado por várias tags. O markup não aceita `class`. Um nome começa pelo Element que o escreve, por um Element que o renderiza ou pela biblioteca `space`. O modificador já traz a base: `variant="counter-button_increase"` gera `class="counter-button counter-button_increase"`.
90
+ `id` names one tag. `variant` names a style shared by several tags. Markup does not accept `class`. A name starts with the Element that writes it, an Element that renders it or the `space` library. A modifier brings its base along: `variant="counter-button_increase"` generates `class="counter-button counter-button_increase"`.
89
91
 
90
92
  ```text
91
93
  Markup Counter
@@ -96,11 +98,11 @@ Markup Counter
96
98
  button variant="counter-button_increase" action="increment" text="+" label={@counter.increment}
97
99
  ```
98
100
 
99
- O build recusa a página quando um `id` se repete, quando um nome é `id` e `variant` ao mesmo tempo, quando coincide com uma tag HTML ou quando sai do formato.
101
+ The build rejects the page when an `id` repeats, when a name is both an `id` and a `variant`, when it matches an HTML tag or when it breaks the format.
100
102
 
101
103
  #### Style
102
104
 
103
- Escreva o nome sem `#` ou `.`. O build gera `[id="nome"]` para um `id` e `.nome` para um `variant`, com o mesmo peso no cascade. Para combinar dois nomes na mesma tag, use `:is()`, como em `space-card:is(space-border_strong)`. Nomes que não são `id`, `variant` nem tag HTML geram erro. Os estilos globais de `project/styles/` declaram os variants da biblioteca, sempre com o prefixo `space-`, como `space-button_primary`.
105
+ Write the name without `#` or `.`. The build generates `[id="name"]` for an `id` and `.name` for a `variant`, with the same weight in the cascade. To combine two names on the same tag, use `:is()`, as in `space-card:is(space-border_strong)`. Names that are not an `id`, a `variant` or an HTML tag raise an error. The global styles in `project/styles/` declare the library variants, always with the `space-` prefix, such as `space-button_primary`.
104
106
 
105
107
  ```text
106
108
  Style Counter
@@ -114,7 +116,7 @@ Style Counter
114
116
 
115
117
  #### Logic
116
118
 
117
- `bind:` lista cada `id` do Element com o que um signal define na tag. As expressões usam o mesmo JavaScript do `body:`. Uma entrada `_modificador` liga e desliga o modificador na tag: `_menu-open` em `home` aplica `home_menu-open`. `page:` indica o signal que controla o tema ou o idioma da página.
119
+ `bind:` lists each `id` of the Element with what a signal sets on the tag. Expressions use the same JavaScript as `body:`. A `_modifier` entry toggles the modifier on the tag: `_menu-open` on `home` applies `home_menu-open`. `page:` names the signal that controls the page theme or language.
118
120
 
119
121
  ```text
120
122
  Logic Home
@@ -133,84 +135,88 @@ Logic Home
133
135
  this.menuOpen = !this.menuOpen
134
136
  ```
135
137
 
136
- | Em `bind:` | Efeito na tag |
138
+ | In `bind:` | Effect on the tag |
137
139
  | --- | --- |
138
- | `text` | Troca o texto pelo valor. |
139
- | `show` | Mostra a tag quando o valor é verdadeiro. |
140
- | `pressed` | Define `aria-pressed`. |
141
- | `expanded` | Define `aria-expanded`. |
142
- | `_modificador` | Aplica `id_modificador` enquanto o valor for verdadeiro. |
140
+ | `text` | Replaces the text with the value. |
141
+ | `show` | Shows the tag when the value is true. |
142
+ | `pressed` | Sets `aria-pressed`. |
143
+ | `expanded` | Sets `aria-expanded`. |
144
+ | `_modifier` | Applies `id_modifier` while the value is true. |
143
145
 
144
- Um `id` no formato `<element>-<signal>` dispensa o `bind:` para texto: `counter-value` exibe `value` em Counter. No corpo de uma ação, `element("counter-title")` devolve a tag. O `bind:` alcança as tags do próprio Element e as de Elements filhos sem `.logic`. Os atributos `data-show`, `data-pressed`, `data-expanded`, `data-state`, `data-bind`, `data-theme-control` e `data-language` não são aceitos no markup. Signals e actions são identificadores JavaScript e continuam em camelCase, como `menuOpen` e `toggleMenu`.
146
+ An `id` in the `<element>-<signal>` format needs no `bind:` for text: `counter-value` shows `value` in Counter. In an action body, `element("counter-title")` returns the tag. `bind:` reaches the tags of the Element itself and those of child Elements without `.logic`. The attributes `data-show`, `data-pressed`, `data-expanded`, `data-state`, `data-bind`, `data-theme-control` and `data-language` are not accepted in markup. Signals and actions are JavaScript identifiers and stay in camelCase, such as `menuOpen` and `toggleMenu`.
145
147
 
146
- Tags nativas aceitam as mesmas propriedades curtas dos Elements: `variant` vira `class`, `action` vira `data-action`, `label` vira `aria-label` e `text` vira o texto da tag. `button` recebe `type="button"` quando não declara `type`.
148
+ Native tags accept the same short properties as Elements: `variant` becomes `class`, `action` becomes `data-action`, `label` becomes `aria-label` and `text` becomes the tag text. `button` gets `type="button"` when it declares no `type`.
147
149
 
148
- ### Elements com os arquivos necessários
150
+ ### Elements with only the files they need
149
151
 
150
- Um Element é o conjunto de arquivos com o mesmo nome na mesma pasta. Nenhum arquivo é obrigatório, e o build reconhece cada um pelo nome e pela extensão.
152
+ An Element is the set of files with the same name in the same folder. No file is required, and the build recognizes each one by its name and extension.
151
153
 
152
- | Arquivos | O que o Element faz |
154
+ | Files | What the Element does |
153
155
  | --- | --- |
154
- | `badge.markup` e `badge.style` | Renderiza estrutura e aparência. |
155
- | `counter.markup`, `counter.logic` e `counter.style` | Renderiza e reage a ações. |
156
- | `session.logic` | Executa uma instância única para a página e não renderiza nada. |
157
- | `spinner.style` | Fornece variants com o nome do Element, como `spinner` e `spinner_large`. |
156
+ | `badge.markup` and `badge.style` | Renders structure and appearance. |
157
+ | `counter.markup`, `counter.logic` and `counter.style` | Renders and reacts to actions. |
158
+ | `session.logic` | Runs a single instance for the page and renders nothing. |
159
+ | `spinner.style` | Provides variants named after the Element, such as `spinner` and `spinner_large`. |
158
160
 
159
- - **Element só com `.logic`:** o markup chama as ações com o nome do Element, como em `action="session.logout"`. O `page:` também funciona. Como não há tags, o `bind:` gera erro.
160
- - **Element só com `.style`:** qualquer markup aplica os nomes com `variant="spinner_large"`. O `.style` só declara nomes que começam pelo próprio Element.
161
- - **Erros de uso:** usar como tag um Element sem `.markup`, como `spinner` ou `session`, gera erro. O mesmo vale para tags que não são HTML nem Element, e para Elements com nome de tag HTML, como `button`.
161
+ - **Element with only `.logic`:** markup calls its actions with the Element name, as in `action="session.logout"`. `page:` works too. Since there are no tags, `bind:` raises an error.
162
+ - **Element with only `.style`:** any markup applies its names with `variant="spinner_large"`. The `.style` only declares names that start with the Element itself.
163
+ - **Usage errors:** using an Element without `.markup`, such as `spinner` or `session`, as a tag raises an error. The same applies to tags that are neither HTML nor an Element, and to Elements named after an HTML tag, such as `button`.
162
164
 
163
- O build valida por necessidade. Cada `action` de uma tag renderizada precisa existir no `.logic` do próprio Element ou de um Element ao redor dela. Uma action com nome de Element, como `session.logout`, precisa existir nesse Element. Um erro de digitação aparece no build, com arquivo e linha.
165
+ The build validates by need. Every `action` of a rendered tag must exist in the `.logic` of its own Element or of an Element around it. An action with an Element name, such as `session.logout`, must exist in that Element. A typo shows up in the build, with file and line.
164
166
 
165
- A compilação é seletiva. O build valida todos os arquivos, mas o resultado inclui apenas:
167
+ Compilation is selective. The build validates every file, but the output includes only:
166
168
 
167
- - os estilos e a lógica dos Elements que a página renderiza;
168
- - os Elements só com `.style` cujos nomes alguma tag usa;
169
- - os Elements só com `.logic` que alguma tag chama ou que declaram `page:`.
169
+ - the styles and logic of the Elements the page renders;
170
+ - the `.style`-only Elements whose names some tag uses;
171
+ - the `.logic`-only Elements that some tag calls or that declare `page:`.
170
172
 
171
- Os estilos globais de `project/styles/` entram sempre.
173
+ The global styles in `project/styles/` are always included.
172
174
 
173
- ## Editor Space
175
+ ## Space editor
174
176
 
175
- A extensão em `tools/vscode-space/` registra o modo Space e o realce semântico no editor. Nos arquivos `.style`, os literais em hexadecimal, RGB, HSL e os nomes CSS em propriedades de cor recebem amostras interativas. O seletor edita apenas o literal escolhido e preserva a transparência em hexadecimal.
177
+ The extension in `tools/vscode-space/` registers the Space mode and semantic highlighting in the editor. In `.style` files, hexadecimal, RGB and HSL literals and CSS color names in color properties get interactive swatches. The picker edits only the chosen literal and preserves hexadecimal transparency.
176
178
 
177
- Instale a extensão no perfil do editor para que os arquivos abram em modo Space nas janelas normais. Com `vsce` disponível, execute `vsce package` em `tools/vscode-space/` e use **Install from VSIX** no painel de extensões. Recarregue a janela e confirme **Space** na barra de status.
179
+ Install the extension in your editor profile so files open in Space mode in normal windows. With `vsce` available, run `vsce package` in `tools/vscode-space/` and use **Install from VSIX** in the extensions panel. Reload the window and confirm **Space** in the status bar.
178
180
 
179
- Para desenvolver a extensão, abra uma janela temporária do VS Code a partir da pasta que contém `project/` e `tools/`.
181
+ To develop the extension, open a temporary VS Code window from the folder that contains `project/` and `tools/`.
180
182
 
181
183
  ```sh
182
184
  code --extensionDevelopmentPath="$PWD/tools/vscode-space" "$PWD"
183
185
  ```
184
186
 
185
- Abra `project/styles/settings/tokens.style` e clique na amostra ao lado de uma cor. O gerador inclui a extensão e a paleta semântica do Space em `.vscode/settings.json`.
187
+ Open `project/styles/settings/tokens.style` and click the swatch next to a color. The generator includes the extension and the Space semantic palette in `.vscode/settings.json`.
186
188
 
187
- ## Abrir a prévia
189
+ ## Open the preview
188
190
 
189
- Na pasta que contém `project/` e `tools/`, gere a página e abra o resultado no Chrome. A prévia foi verificada com Node.js 26.13.0.
191
+ In the folder that contains `project/` and `tools/`, generate the page and open the result in Chrome. The preview was verified with Node.js 26.13.0.
190
192
 
191
193
  ```sh
192
194
  node tools/build.mjs
193
195
  open -a "Google Chrome" dist/index.html
194
196
  ```
195
197
 
196
- Para testar via HTTP, execute `python3 -m http.server 4173 --bind 127.0.0.1 --directory dist` e abra [a prévia local](http://127.0.0.1:4173/). Depois de editar arquivos Space, execute o build de novo e recarregue.
198
+ To test over HTTP, run `python3 -m http.server 4173 --bind 127.0.0.1 --directory dist` and open [the local preview](http://127.0.0.1:4173/). After editing Space files, run the build again and reload.
199
+
200
+ ## What's included
201
+
202
+ - Home as a landing page, with a header menu (Files, Playground, Styles, Markup, Logic, language and theme), a box to copy the install command and sections about AI, Elements without required files, the best of every framework and the Space language. The Files page lists the 25 types with search, and each link opens the type's panel. Search lives in the header and opens with ⌘K or Ctrl+K. The For AI agents (`#ai-guide`) and Roadmap (`#roadmap`) pages are linked in the Home footer, and every code block has a copy button. `.logic` has an introduction, architecture decisions, a tutorial and a playground.
203
+ - Playground with a working counter and three tabs that show the contents of `counter.logic`, `counter.markup` and `counter.style` straight from the files. To try a different initial value, follow the tutorial, change the local file and generate the preview again.
204
+ - Translations in English, Brazilian Portuguese, Spanish and Simplified Chinese. The first visit uses the browser preference, with English as the default when no preference matches. A manual choice is saved when the browser provides storage.
197
205
 
198
- ## O que entrou
206
+ ## What the prototype revealed
199
207
 
200
- - Home no formato de landing page, com menu no header (Arquivos, Playground, Styles, Markup, Logic, idioma e tema), caixa para copiar o comando de instalação e seções sobre IA, Elements sem arquivos obrigatórios, o melhor de cada framework e a linguagem Space. A página Arquivos lista os 25 tipos com busca, e cada link leva ao painel do tipo. A busca fica no header e abre com ⌘K ou Ctrl+K. As páginas Para agentes de IA (`#ai-guide`) e Roadmap (`#roadmap`) ficam no rodapé da Home, e todo bloco de código ganha um botão de copiar. `.logic` tem apresentação, decisões de arquitetura, tutorial e playground.
201
- - Playground com contador funcional e três abas que mostram o conteúdo de `counter.logic`, `counter.markup` e `counter.style` diretamente dos arquivos. Para testar um valor inicial diferente, siga o tutorial, altere o arquivo local e gere a prévia novamente.
202
- - Traduções em inglês, português do Brasil, espanhol e chinês simplificado. A primeira visita usa a preferência do navegador, com inglês como idioma padrão quando nenhuma preferência é compatível. A escolha manual é guardada quando o navegador disponibiliza armazenamento.
208
+ - The `aliens-exemplo` tool only demonstrated stylesheet compilation. The preview in `tools/` was created to render Element composition, apply translations, run the counter actions and switch panels. The interface code stays in each Element's files.
209
+ - Markup calls actions with `action` and `.logic` binds signals to tags by `id`, in the `bind:` block. These conventions, the Element property syntax and the translation format need validation before they become part of the final grammar.
210
+ - The preview compiler covers primitive signals and the parameterless actions used by the documentation. It strips TypeScript annotations without semantic type checking. Lifecycle, real dependencies between modules, services and running `.test` files are pending. Page navigation uses URL fragments. The `app.route` file registers the initial route and still needs a router to run it.
211
+ - The index follows the catalog of 25 types. `.style` and `.mock` are the extensions defined for stylesheets and mock data, respectively.
212
+ - The playground tabs reuse the code the page compiles. The simulation is interactive and the files are read-only in the browser. Editing in the playground waits for an isolated way to compile and run typed code.
203
213
 
204
- ## O que o protótipo revelou
214
+ ## Validation
205
215
 
206
- - A ferramenta do `aliens-exemplo` demonstrava apenas a compilação das folhas de estilo. A prévia em `tools/` foi criada para renderizar a composição de Elements, aplicar traduções, executar ações do contador e alternar os painéis. O código da interface permanece nos arquivos de cada Element.
207
- - O markup chama as ações com `action` e o `.logic` liga os signals às tags por `id`, no bloco `bind:`. Essas convenções, a sintaxe das propriedades de Elements e o formato das traduções precisam de validação antes de virarem parte da gramática definitiva.
208
- - O compilador de prévia cobre os sinais primitivos e as ações sem parâmetros usadas pela documentação. Ele remove anotações TypeScript, sem fazer checagem semântica de tipos. Ciclo de vida, dependências reais entre módulos, serviços e execução de arquivos `.test` ficam pendentes. A navegação da página usa fragmentos de URL. O arquivo `app.route` registra a rota inicial e ainda precisa de um roteador para executá-la.
209
- - O índice segue o catálogo de 25 tipos. `.style` e `.mock` são as extensões definidas para folhas de estilo e dados simulados, respectivamente.
210
- - As abas do playground reaproveitam o código que a página compila. A simulação é interativa e os arquivos são para leitura no navegador. A edição no playground fica para depois que existir uma forma isolada de compilar e executar o código digitado.
216
+ The build passed and the generated JavaScript was checked with `node --check`. In the browser, the Home, the menu on small screens, the topic links, the code tabs, and clicks and keyboard on the counter were checked. The final Home opened in Chrome in Portuguese detected from the browser. In the compiled runtime, seven language-preference scenarios, the four manual pickers and the match between the displayed code and the three source files were verified.
211
217
 
212
- ## Validação
218
+ The style library was validated in a new project and in another one created by that project's generator. Links, unique IDs, Space indentation, four languages, H1–H6 at 390 px and theme-picker sync were checked. An extra theme was added only to the temporary project to verify its discovery by the build and its application in the browser.
213
219
 
214
- O build passou e o JavaScript gerado foi verificado com `node --check`. No navegador, foram conferidos a Home, o menu em tela pequena, os links do tópico, as abas de código, os cliques e o teclado no contador. A Home final abriu no Chrome em português detectado pelo navegador. No runtime compilado foram verificados sete cenários de preferência de idioma, os quatro seletores manuais e a igualdade entre o código exibido e os três arquivos de origem.
220
+ ## License
215
221
 
216
- A biblioteca de estilos foi validada em um projeto novo e em outro criado pelo gerador desse projeto. Foram conferidos os links, IDs únicos, indentação Space, quatro idiomas, H1–H6 em 390 px e sincronização dos seletores de tema. Um tema adicional foi incluído somente no projeto temporário para verificar sua descoberta pelo build e aplicação no navegador.
222
+ Aliens Framework is distributed under the [MIT license](LICENSE).
@@ -0,0 +1,222 @@
1
+ # Aliens Framework · Documentação
2
+
3
+ [English](README.md) · **Português** · [Español](README.es-ES.md) · [中文](README.zh-CN.md)
4
+
5
+ Os fontes da aplicação ficam em `project/`. As páginas ficam em `project/app/pages/` e os Elements reutilizáveis em `project/app/elements/`. As imagens ficam em `project/assets/`, as traduções em `project/language/` e os estilos globais em `project/styles/`. O build lê `.config` e gera `ai/.map` para o CodingBot. Os dois arquivos usam caminhos relativos à raiz do workspace. As ferramentas do Space ficam em `tools/`, ao lado de `project/`.
6
+
7
+ ## Criar um projeto
8
+
9
+ ```sh
10
+ node tools/create.mjs meu-projeto
11
+ cd meu-projeto
12
+ node tools/build.mjs
13
+ ```
14
+
15
+ O mesmo gerador está publicado no npm como `@aliens-syndicate/cli` e funciona sem clonar o repositório. O comando `aliens build` executa o `tools/build.mjs` do projeto aberto.
16
+
17
+ ```sh
18
+ npx @aliens-syndicate/cli create meu-projeto
19
+ cd meu-projeto
20
+ npx @aliens-syndicate/cli build
21
+ ```
22
+
23
+ Para publicar uma nova versão, atualize `version` em `package.json` e execute `npm publish` na raiz, com a conta `aliens-syndicate` logada no npm.
24
+
25
+ O gerador cria a Home em `project/app/pages/home/`, os quatro níveis de Elements e as pastas dos tipos de arquivo da aplicação. Os exemplos comentados do catálogo de heróis vêm da base do motor em `tools/starter/`, independente da aplicação que estiver aberta. O Element `hero-card` reúne `.markup`, `.logic`, `.style` e `.test` em `project/app/elements/molecules/hero-card/`. As pastas `agents/`, `rules/` e `skills/` ficam em `ai/`.
26
+
27
+ Cada exemplo tem uma descrição seguida de uma linha que contém apenas `#`. Para experimentar, remova o prefixo `# ` das linhas de código abaixo dessa linha, preservando os três espaços por nível. No cartão, descomente `hero-card.markup`, `hero-card.logic` e `hero-card.style` e inclua `hero-card` no markup de uma página.
28
+
29
+ Em `project/app/routes/`, os exemplos comentados mostram rotas fixas e filhas, parâmetros, filtros, redirecionamento, guard, estado e fallback. A execução de rotas e de arquivos `.test` faz parte do trabalho pendente no runtime.
30
+
31
+ ## Biblioteca de estilos e temas
32
+
33
+ Cada projeto novo abre com uma biblioteca navegável em Space, com sete vistas e exemplos em português, inglês, espanhol e chinês. No site da documentação, o botão **Biblioteca de estilos** na Home abre `#kit-overview`.
34
+
35
+ - `project/styles/settings/` reúne os tokens de cor, espaço, raio, borda, tipografia e elevação.
36
+ - `project/styles/components/` fornece tipografia H1–H6, parágrafo, texto auxiliar, legenda, link, lista, citação e código; botões, campos, cartões, etiquetas, avisos, bordas, espaçamento, tabela, progresso e painel expansível.
37
+ - `project/styles/settings/theme.style` centraliza os valores semânticos dos temas `light` e `dark` da biblioteca. Os componentes usam esses valores por meio de variáveis CSS.
38
+ - `project/app/pages/kit-*/` contém as páginas de amostras. Os Elements reutilizáveis ficam nos níveis do Atomic Design.
39
+
40
+ Para criar outro tema, acrescente um bloco ao final de `theme.style`, com um nome em letras minúsculas, números e hífens, começando por letra. Os valores não redefinidos herdam a base clara de `:root`. Para um tema escuro completo, copie o bloco `dark`, troque o nome e personalize seus tokens.
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
+ Execute o build após editar. O motor reconhece os blocos do arquivo e adiciona os temas ao seletor, mantendo a preferência entre recarregamentos. As amostras exibem o código real dos arquivos `.style`. A base do gerador fica em `tools/starter/`; personalizações de um projeto não são copiadas para os projetos seguintes.
54
+
55
+ ## Atomic Design
56
+
57
+ - `atoms/` contém elementos básicos, como botões, links e controles de tema.
58
+ - `molecules/` contém componentes de função específica, como busca, seletor de idioma e contador.
59
+ - `organisms/` contém composições como cabeçalho, menu lateral, grade de guias e playground.
60
+ - `templates/` contém o layout reutilizável dos painéis de referência.
61
+
62
+ O catálogo de tipos fica em `project/app/pages/type-index/`, junto às páginas, e usa o template `type-summary` para montar os painéis navegáveis. Cada Element mantém seus arquivos Space na própria pasta.
63
+
64
+ ## Padrão Space
65
+
66
+ O cabeçalho dos arquivos nomeados começa com o tipo e o nome em PascalCase. O corpo usa três espaços por nível. Campos e contratos usam tipos explícitos. Comentários declarativos começam com `#`.
67
+
68
+ ```text
69
+ Markup App
70
+ home
71
+ ```
72
+
73
+ O exemplo está em `project/app/app.markup`. Outros cabeçalhos são `Logic App`, `Style App` e `Pipe Currency`. `.config`, `.env`, `ai/.map` e os arquivos de tradução têm suas próprias estruturas Space. O build valida cabeçalho e indentação nos fontes do projeto. Os exemplos de código usam a paleta do Space nos dois temas.
74
+
75
+ ### Nomes: element-filho_modificador:estado
76
+
77
+ O `.markup`, o `.style` e o `.logic` usam os mesmos nomes, sempre em minúsculas. Cada separador tem um papel:
78
+
79
+ | Conceito | Separador | Exemplo |
80
+ | --- | --- | --- |
81
+ | Element | nenhum além do próprio nome | `site-header` |
82
+ | Filho | `-` | `site-header-logo` |
83
+ | Modificador | `_` | `site-header-logo_large` |
84
+ | Estado | `:` | `site-header-logo_large:hover` |
85
+
86
+ A ordem é `element-filho_modificador:estado`. Pastas e arquivos de Elements seguem o nome do Element, como `site-header/site-header.markup`. O build reconhece o Element pelo nome conhecido: `site-header-logo` pertence a `site-header`. Cada nome tem no máximo um modificador. O estado é uma pseudo-classe do CSS e aparece apenas no `.style`.
87
+
88
+ #### Markup
89
+
90
+ O `id` nomeia uma tag. O `variant` nomeia um estilo compartilhado por várias tags. O markup não aceita `class`. Um nome começa pelo Element que o escreve, por um Element que o renderiza ou pela biblioteca `space`. O modificador já traz a base: `variant="counter-button_increase"` gera `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
+ O build recusa a página quando um `id` se repete, quando um nome é `id` e `variant` ao mesmo tempo, quando coincide com uma tag HTML ou quando sai do formato.
102
+
103
+ #### Style
104
+
105
+ Escreva o nome sem `#` ou `.`. O build gera `[id="nome"]` para um `id` e `.nome` para um `variant`, com o mesmo peso no cascade. Para combinar dois nomes na mesma tag, use `:is()`, como em `space-card:is(space-border_strong)`. Nomes que não são `id`, `variant` nem tag HTML geram erro. Os estilos globais de `project/styles/` declaram os variants da biblioteca, sempre com o prefixo `space-`, como `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:` lista cada `id` do Element com o que um signal define na tag. As expressões usam o mesmo JavaScript do `body:`. Uma entrada `_modificador` liga e desliga o modificador na tag: `_menu-open` em `home` aplica `home_menu-open`. `page:` indica o signal que controla o tema ou o idioma da página.
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
+ | Em `bind:` | Efeito na tag |
139
+ | --- | --- |
140
+ | `text` | Troca o texto pelo valor. |
141
+ | `show` | Mostra a tag quando o valor é verdadeiro. |
142
+ | `pressed` | Define `aria-pressed`. |
143
+ | `expanded` | Define `aria-expanded`. |
144
+ | `_modificador` | Aplica `id_modificador` enquanto o valor for verdadeiro. |
145
+
146
+ Um `id` no formato `<element>-<signal>` dispensa o `bind:` para texto: `counter-value` exibe `value` em Counter. No corpo de uma ação, `element("counter-title")` devolve a tag. O `bind:` alcança as tags do próprio Element e as de Elements filhos sem `.logic`. Os atributos `data-show`, `data-pressed`, `data-expanded`, `data-state`, `data-bind`, `data-theme-control` e `data-language` não são aceitos no markup. Signals e actions são identificadores JavaScript e continuam em camelCase, como `menuOpen` e `toggleMenu`.
147
+
148
+ Tags nativas aceitam as mesmas propriedades curtas dos Elements: `variant` vira `class`, `action` vira `data-action`, `label` vira `aria-label` e `text` vira o texto da tag. `button` recebe `type="button"` quando não declara `type`.
149
+
150
+ ### Elements com os arquivos necessários
151
+
152
+ Um Element é o conjunto de arquivos com o mesmo nome na mesma pasta. Nenhum arquivo é obrigatório, e o build reconhece cada um pelo nome e pela extensão.
153
+
154
+ | Arquivos | O que o Element faz |
155
+ | --- | --- |
156
+ | `badge.markup` e `badge.style` | Renderiza estrutura e aparência. |
157
+ | `counter.markup`, `counter.logic` e `counter.style` | Renderiza e reage a ações. |
158
+ | `session.logic` | Executa uma instância única para a página e não renderiza nada. |
159
+ | `spinner.style` | Fornece variants com o nome do Element, como `spinner` e `spinner_large`. |
160
+
161
+ - **Element só com `.logic`:** o markup chama as ações com o nome do Element, como em `action="session.logout"`. O `page:` também funciona. Como não há tags, o `bind:` gera erro.
162
+ - **Element só com `.style`:** qualquer markup aplica os nomes com `variant="spinner_large"`. O `.style` só declara nomes que começam pelo próprio Element.
163
+ - **Erros de uso:** usar como tag um Element sem `.markup`, como `spinner` ou `session`, gera erro. O mesmo vale para tags que não são HTML nem Element, e para Elements com nome de tag HTML, como `button`.
164
+
165
+ O build valida por necessidade. Cada `action` de uma tag renderizada precisa existir no `.logic` do próprio Element ou de um Element ao redor dela. Uma action com nome de Element, como `session.logout`, precisa existir nesse Element. Um erro de digitação aparece no build, com arquivo e linha.
166
+
167
+ A compilação é seletiva. O build valida todos os arquivos, mas o resultado inclui apenas:
168
+
169
+ - os estilos e a lógica dos Elements que a página renderiza;
170
+ - os Elements só com `.style` cujos nomes alguma tag usa;
171
+ - os Elements só com `.logic` que alguma tag chama ou que declaram `page:`.
172
+
173
+ Os estilos globais de `project/styles/` entram sempre.
174
+
175
+ ## Editor Space
176
+
177
+ A extensão em `tools/vscode-space/` registra o modo Space e o realce semântico no editor. Nos arquivos `.style`, os literais em hexadecimal, RGB, HSL e os nomes CSS em propriedades de cor recebem amostras interativas. O seletor edita apenas o literal escolhido e preserva a transparência em hexadecimal.
178
+
179
+ Instale a extensão no perfil do editor para que os arquivos abram em modo Space nas janelas normais. Com `vsce` disponível, execute `vsce package` em `tools/vscode-space/` e use **Install from VSIX** no painel de extensões. Recarregue a janela e confirme **Space** na barra de status.
180
+
181
+ Para desenvolver a extensão, abra uma janela temporária do VS Code a partir da pasta que contém `project/` e `tools/`.
182
+
183
+ ```sh
184
+ code --extensionDevelopmentPath="$PWD/tools/vscode-space" "$PWD"
185
+ ```
186
+
187
+ Abra `project/styles/settings/tokens.style` e clique na amostra ao lado de uma cor. O gerador inclui a extensão e a paleta semântica do Space em `.vscode/settings.json`.
188
+
189
+ ## Abrir a prévia
190
+
191
+ Na pasta que contém `project/` e `tools/`, gere a página e abra o resultado no Chrome. A prévia foi verificada com Node.js 26.13.0.
192
+
193
+ ```sh
194
+ node tools/build.mjs
195
+ open -a "Google Chrome" dist/index.html
196
+ ```
197
+
198
+ Para testar via HTTP, execute `python3 -m http.server 4173 --bind 127.0.0.1 --directory dist` e abra [a prévia local](http://127.0.0.1:4173/). Depois de editar arquivos Space, execute o build de novo e recarregue.
199
+
200
+ ## O que entrou
201
+
202
+ - Home no formato de landing page, com menu no header (Arquivos, Playground, Styles, Markup, Logic, idioma e tema), caixa para copiar o comando de instalação e seções sobre IA, Elements sem arquivos obrigatórios, o melhor de cada framework e a linguagem Space. A página Arquivos lista os 25 tipos com busca, e cada link leva ao painel do tipo. A busca fica no header e abre com ⌘K ou Ctrl+K. As páginas Para agentes de IA (`#ai-guide`) e Roadmap (`#roadmap`) ficam no rodapé da Home, e todo bloco de código ganha um botão de copiar. `.logic` tem apresentação, decisões de arquitetura, tutorial e playground.
203
+ - Playground com contador funcional e três abas que mostram o conteúdo de `counter.logic`, `counter.markup` e `counter.style` diretamente dos arquivos. Para testar um valor inicial diferente, siga o tutorial, altere o arquivo local e gere a prévia novamente.
204
+ - Traduções em inglês, português do Brasil, espanhol e chinês simplificado. A primeira visita usa a preferência do navegador, com inglês como idioma padrão quando nenhuma preferência é compatível. A escolha manual é guardada quando o navegador disponibiliza armazenamento.
205
+
206
+ ## O que o protótipo revelou
207
+
208
+ - A ferramenta do `aliens-exemplo` demonstrava apenas a compilação das folhas de estilo. A prévia em `tools/` foi criada para renderizar a composição de Elements, aplicar traduções, executar ações do contador e alternar os painéis. O código da interface permanece nos arquivos de cada Element.
209
+ - O markup chama as ações com `action` e o `.logic` liga os signals às tags por `id`, no bloco `bind:`. Essas convenções, a sintaxe das propriedades de Elements e o formato das traduções precisam de validação antes de virarem parte da gramática definitiva.
210
+ - O compilador de prévia cobre os sinais primitivos e as ações sem parâmetros usadas pela documentação. Ele remove anotações TypeScript, sem fazer checagem semântica de tipos. Ciclo de vida, dependências reais entre módulos, serviços e execução de arquivos `.test` ficam pendentes. A navegação da página usa fragmentos de URL. O arquivo `app.route` registra a rota inicial e ainda precisa de um roteador para executá-la.
211
+ - O índice segue o catálogo de 25 tipos. `.style` e `.mock` são as extensões definidas para folhas de estilo e dados simulados, respectivamente.
212
+ - As abas do playground reaproveitam o código que a página compila. A simulação é interativa e os arquivos são para leitura no navegador. A edição no playground fica para depois que existir uma forma isolada de compilar e executar o código digitado.
213
+
214
+ ## Validação
215
+
216
+ O build passou e o JavaScript gerado foi verificado com `node --check`. No navegador, foram conferidos a Home, o menu em tela pequena, os links do tópico, as abas de código, os cliques e o teclado no contador. A Home final abriu no Chrome em português detectado pelo navegador. No runtime compilado foram verificados sete cenários de preferência de idioma, os quatro seletores manuais e a igualdade entre o código exibido e os três arquivos de origem.
217
+
218
+ A biblioteca de estilos foi validada em um projeto novo e em outro criado pelo gerador desse projeto. Foram conferidos os links, IDs únicos, indentação Space, quatro idiomas, H1–H6 em 390 px e sincronização dos seletores de tema. Um tema adicional foi incluído somente no projeto temporário para verificar sua descoberta pelo build e aplicação no navegador.
219
+
220
+ ## Licença
221
+
222
+ O Aliens Framework é distribuído sob a [licença MIT](LICENSE).
@@ -0,0 +1,222 @@
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)发布。
package/package.json CHANGED
@@ -1,7 +1,9 @@
1
1
  {
2
2
  "name": "@aliens-syndicate/cli",
3
- "version": "0.1.0",
4
- "description": "CLI do Aliens, o framework front-end da era da IA escrito em Space.",
3
+ "version": "0.1.2",
4
+ "description": "CLI for Aliens, the AI-era front-end framework written in Space.",
5
+ "license": "MIT",
6
+ "author": "Aliens Syndicate",
5
7
  "type": "module",
6
8
  "bin": {
7
9
  "aliens": "tools/cli.mjs"
package/tools/cli.mjs CHANGED
@@ -6,12 +6,29 @@ import { pathToFileURL } from 'node:url';
6
6
 
7
7
  const [command, ...args] = process.argv.slice(2);
8
8
  const { version } = JSON.parse(readFileSync(join(import.meta.dirname, '..', 'package.json'), 'utf8'));
9
+ // Messages follow the system language (ALIENS_LANG overrides it): English, Portuguese, Spanish or Chinese.
10
+ const language = (() => {
11
+ const tag = (process.env.ALIENS_LANG || process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG ||
12
+ Intl.DateTimeFormat().resolvedOptions().locale || 'en').toLowerCase();
13
+ return ['pt', 'es', 'zh'].find(code => tag.startsWith(code)) ?? 'en';
14
+ })();
15
+ const text = {
16
+ en: { usage: 'Usage', create: 'Creates an Aliens project in the given folder.', build: 'Generates the preview in dist/ from the current folder.',
17
+ version: 'Shows the CLI version.', folder: 'folder', missing: 'No Aliens project in this folder: tools/build.mjs was not found.' },
18
+ pt: { usage: 'Uso', create: 'Cria um projeto Aliens na pasta indicada.', build: 'Gera a prévia em dist/ a partir da pasta atual.',
19
+ version: 'Mostra a versão do CLI.', folder: 'pasta', missing: 'Nenhum projeto Aliens nesta pasta: tools/build.mjs não foi encontrado.' },
20
+ es: { usage: 'Uso', create: 'Crea un proyecto Aliens en la carpeta indicada.', build: 'Genera la vista previa en dist/ desde la carpeta actual.',
21
+ version: 'Muestra la versión del CLI.', folder: 'carpeta', missing: 'No hay un proyecto Aliens en esta carpeta: no se encontró tools/build.mjs.' },
22
+ zh: { usage: '用法', create: '在指定文件夹中创建 Aliens 项目。', build: '在当前文件夹中生成 dist/ 预览。',
23
+ version: '显示 CLI 版本。', folder: '文件夹', missing: '此文件夹中没有 Aliens 项目:未找到 tools/build.mjs。' }
24
+ }[language];
25
+ const create = `aliens create <${text.folder}>`;
9
26
  const help = `Aliens ${version}
10
27
 
11
- Uso:
12
- aliens create <pasta> Cria um projeto Aliens na pasta indicada.
13
- aliens build Gera a prévia em dist/ a partir da pasta atual.
14
- aliens --version Mostra a versão do CLI.
28
+ ${text.usage}:
29
+ ${create.padEnd(24)}${text.create}
30
+ ${'aliens build'.padEnd(24)}${text.build}
31
+ ${'aliens --version'.padEnd(24)}${text.version}
15
32
  `;
16
33
 
17
34
  // Each script reads its own arguments, so the CLI hands them over through process.argv.
@@ -26,7 +43,7 @@ if (command === 'create') {
26
43
  // A project carries its own tools/, so the build always matches the project's version.
27
44
  const script = join(process.cwd(), 'tools', 'build.mjs');
28
45
  if (!existsSync(script)) {
29
- console.error('Nenhum projeto Aliens nesta pasta: tools/build.mjs não foi encontrado.');
46
+ console.error(text.missing);
30
47
  process.exitCode = 1;
31
48
  } else {
32
49
  await run(script, args);
package/tools/create.mjs CHANGED
@@ -2,15 +2,32 @@ import { copyFile, cp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/p
2
2
  import { basename, join, resolve } from 'node:path';
3
3
  import { createProjectDirectories, styleLayers } from './project-layout.mjs';
4
4
 
5
+ // Messages follow the system language (ALIENS_LANG overrides it): English, Portuguese, Spanish or Chinese.
6
+ const language = (() => {
7
+ const tag = (process.env.ALIENS_LANG || process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG ||
8
+ Intl.DateTimeFormat().resolvedOptions().locale || 'en').toLowerCase();
9
+ return ['pt', 'es', 'zh'].find(code => tag.startsWith(code)) ?? 'en';
10
+ })();
11
+ const messages = {
12
+ en: { usage: 'Usage: node tools/create.mjs <new-project-folder>', name: 'Use a single-line folder name without leading or trailing spaces.',
13
+ created: 'Aliens project created in', exists: 'The destination folder already exists.' },
14
+ pt: { usage: 'Uso: node tools/create.mjs <pasta-do-novo-projeto>', name: 'Use um nome de pasta em uma única linha, sem espaços nas pontas.',
15
+ created: 'Projeto Aliens criado em', exists: 'A pasta de destino já existe.' },
16
+ es: { usage: 'Uso: node tools/create.mjs <carpeta-del-nuevo-proyecto>', name: 'Usa un nombre de carpeta en una sola línea, sin espacios en los extremos.',
17
+ created: 'Proyecto Aliens creado en', exists: 'La carpeta de destino ya existe.' },
18
+ zh: { usage: '用法:node tools/create.mjs <新项目文件夹>', name: '请使用单行文件夹名称,首尾不要有空格。',
19
+ created: 'Aliens 项目已创建于', exists: '目标文件夹已存在。' }
20
+ }[language];
21
+
5
22
  const starter = join(import.meta.dirname, 'starter');
6
23
  const editorExtension = join(import.meta.dirname, 'vscode-space');
7
24
 
8
25
  async function create([path, ...extra]) {
9
- if (!path || extra.length) throw new Error('Uso: node tools/create.mjs <pasta-do-novo-projeto>');
26
+ if (!path || extra.length) throw new Error(messages.usage);
10
27
  const destination = resolve(path);
11
28
  const name = basename(destination);
12
29
  if (!name || /[\r\n\u2028\u2029]/u.test(name) || name !== name.trim()) {
13
- throw new Error('Use um nome de pasta em uma única linha, sem espaços nas pontas.');
30
+ throw new Error(messages.name);
14
31
  }
15
32
 
16
33
  await mkdir(destination);
@@ -38,13 +55,13 @@ async function create([path, ...extra]) {
38
55
  ...translations,
39
56
  'README.md': `# ${name}
40
57
 
41
- Use \`node tools/build.mjs\` para gerar a prévia em \`dist/\`.
58
+ Run \`node tools/build.mjs\` to generate the preview in \`dist/\`.
42
59
 
43
- A configuração fica em \`.config\` e o build gera o índice \`ai/.map\`.
44
- A Home inclui a biblioteca de estilos, com tokens em \`project/styles/settings/\`, componentes em \`project/styles/components/\` e temas em \`project/styles/settings/theme.style\`.
45
- Adicione um bloco \`:root[data-theme="nome"]\` nesse arquivo e execute o build para disponibilizar o tema no seletor.
60
+ The configuration lives in \`.config\` and the build generates the \`ai/.map\` index.
61
+ The Home includes the style library, with tokens in \`project/styles/settings/\`, components in \`project/styles/components/\` and themes in \`project/styles/settings/theme.style\`.
62
+ Add a \`:root[data-theme="name"]\` block to that file and run the build to make the theme available in the picker.
46
63
 
47
- As páginas e os Elements ficam em \`project/app/pages/\` e \`project/app/elements/\`.
64
+ Pages and Elements live in \`project/app/pages/\` and \`project/app/elements/\`.
48
65
  `,
49
66
  '.config': `project:
50
67
  name: ${name}
@@ -91,12 +108,12 @@ language:
91
108
  throw error;
92
109
  }
93
110
 
94
- console.log(`Projeto Aliens criado em ${destination}`);
111
+ console.log(`${messages.created} ${destination}`);
95
112
  }
96
113
 
97
114
  try {
98
115
  await create(process.argv.slice(2));
99
116
  } catch (error) {
100
- console.error(error.code === 'EEXIST' ? 'A pasta de destino já existe.' : error.message);
117
+ console.error(error.code === 'EEXIST' ? messages.exists : error.message);
101
118
  process.exitCode = 1;
102
119
  }