@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.es-ES.md
DELETED
|
@@ -1,222 +0,0 @@
|
|
|
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.pt-BR.md
DELETED
|
@@ -1,222 +0,0 @@
|
|
|
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).
|