@aliens-syndicate/cli 0.1.3 → 0.1.4
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.es-ES.md +265 -0
- package/README.md +19 -3
- package/README.pt-BR.md +265 -0
- package/README.zh-CN.md +265 -0
- package/package.json +2 -1
- package/tools/build.mjs +47 -11
- package/tools/cache.mjs +41 -0
- package/tools/cli-shared.mjs +237 -0
- package/tools/cli.mjs +145 -53
- package/tools/create.mjs +202 -82
- package/tools/doctor.mjs +139 -0
- package/tools/generate.mjs +175 -0
- package/tools/project-layout.mjs +3 -3
- package/tools/serve.mjs +152 -0
- package/tools/starter/ai/rules/architecture.rule +1 -0
- package/tools/starter/ai/skills/create-element.skill +2 -1
- package/tools/update.mjs +110 -0
package/README.es-ES.md
ADDED
|
@@ -0,0 +1,265 @@
|
|
|
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. Instálalo una vez con `npm install -g @aliens-syndicate/cli`; `aliens new` pregunta qué extensiones usar y ejecuta `npm install`. Los comentarios que empiezan con `#AGENT` son directivas solo para agentes de IA: el build los lista, con archivo y línea, en `directives:` de `ai/.map`.
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
npm install -g @aliens-syndicate/cli
|
|
19
|
+
aliens new mi-proyecto
|
|
20
|
+
cd mi-proyecto
|
|
21
|
+
aliens run
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
| Comando | Qué hace |
|
|
25
|
+
| --- | --- |
|
|
26
|
+
| `aliens new <nombre>` (`n`) | Crea un proyecto y pregunta qué extensiones instalar. `--yes`, `--no-style`, `--no-icons`, `--no-elements` y `--skip-install` saltan las preguntas. |
|
|
27
|
+
| `aliens run` | Hace el build, sirve en http://localhost:5151 y rehace el build y recarga el navegador con cada archivo guardado. `--port <número>` o `serve: port:` en `.config` cambia el puerto. `aliens watch` es un atajo. |
|
|
28
|
+
| `aliens build` | Ejecuta el `tools/build.mjs` del proyecto y genera `dist/` y `ai/.map`. |
|
|
29
|
+
| `aliens generate <tipo> <nombre>` (`g`) | Crea archivos Space. `aliens g element molecules/card` escribe `.markup`, `.logic`, `.style` y `.test`; sin el nivel, la CLI pregunta. Los archivos existentes se conservan y solo se crean los que faltan. Tipos: element (`e`), page (`p`), service (`s`), directive (`d`), interface (`i`), model (`m`), validator (`v`), route (`r`), api, animation, enum, error, guard, interceptor, mock, pipe, storage, agent, rule, skill. `--dry-run` no escribe nada. |
|
|
30
|
+
| `aliens doctor` | Revisa Node.js, npm, la versión de la CLI, `.config`, los paquetes, el puerto y el build, con la corrección de cada problema. |
|
|
31
|
+
| `aliens update` | Actualiza los paquetes `@aliens-syndicate` del proyecto y copia el `tools/` de la CLI instalada. `--dry-run` lista los cambios. |
|
|
32
|
+
| `aliens cache` | Borra `dist/` y las cachés de las herramientas. |
|
|
33
|
+
| `aliens version` | Muestra las versiones de la CLI, Node.js, el sistema y los paquetes. `aliens --version` muestra solo el número. |
|
|
34
|
+
|
|
35
|
+
El comentario al inicio de `.config` lista los mismos comandos, y la página **Instalación** del sitio (`#installation`) los explica paso a paso.
|
|
36
|
+
|
|
37
|
+
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.
|
|
38
|
+
|
|
39
|
+
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/`.
|
|
40
|
+
|
|
41
|
+
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.
|
|
42
|
+
|
|
43
|
+
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.
|
|
44
|
+
|
|
45
|
+
## Biblioteca de estilos y temas
|
|
46
|
+
|
|
47
|
+
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`.
|
|
48
|
+
|
|
49
|
+
- `project/styles/settings/` reúne los tokens de color, espaciado, radio, borde, tipografía y elevación.
|
|
50
|
+
- `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.
|
|
51
|
+
- `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.
|
|
52
|
+
- `project/app/pages/kit-*/` contiene las páginas de muestras. Los Elements reutilizables están en los niveles de Atomic Design.
|
|
53
|
+
|
|
54
|
+
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.
|
|
55
|
+
|
|
56
|
+
```text
|
|
57
|
+
:root[data-theme="ocean"]
|
|
58
|
+
color-scheme: light
|
|
59
|
+
--color-brand: #075985
|
|
60
|
+
--color-brand-hover: #0c4a6e
|
|
61
|
+
--color-on-brand: #ffffff
|
|
62
|
+
--color-focus: #075985
|
|
63
|
+
--color-accent: #e0f2fe
|
|
64
|
+
--color-on-accent: #0c4a6e
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
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.
|
|
68
|
+
|
|
69
|
+
## Atomic Design
|
|
70
|
+
|
|
71
|
+
- `atoms/` contiene elementos básicos, como botones, enlaces y controles de tema.
|
|
72
|
+
- `molecules/` contiene componentes con una función concreta, como la búsqueda, el selector de idioma y el contador.
|
|
73
|
+
- `organisms/` contiene composiciones como el encabezado, la cuadrícula de guías y el playground.
|
|
74
|
+
- `templates/` contiene el layout reutilizable de los paneles de referencia.
|
|
75
|
+
|
|
76
|
+
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.
|
|
77
|
+
|
|
78
|
+
## Convenciones de Space
|
|
79
|
+
|
|
80
|
+
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 `#`.
|
|
81
|
+
|
|
82
|
+
```text
|
|
83
|
+
Markup App
|
|
84
|
+
home
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
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.
|
|
88
|
+
|
|
89
|
+
### Nombres: element-hijo_modificador:estado
|
|
90
|
+
|
|
91
|
+
`.markup`, `.style` y `.logic` usan los mismos nombres, siempre en minúsculas. Cada separador tiene un papel:
|
|
92
|
+
|
|
93
|
+
| Concepto | Separador | Ejemplo |
|
|
94
|
+
| --- | --- | --- |
|
|
95
|
+
| Element | ninguno además de su propio nombre | `site-header` |
|
|
96
|
+
| Hijo | `-` | `site-header-logo` |
|
|
97
|
+
| Modificador | `_` | `site-header-logo_large` |
|
|
98
|
+
| Estado | `:` | `site-header-logo_large:hover` |
|
|
99
|
+
|
|
100
|
+
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`.
|
|
101
|
+
|
|
102
|
+
#### Markup
|
|
103
|
+
|
|
104
|
+
`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"`.
|
|
105
|
+
|
|
106
|
+
```text
|
|
107
|
+
Markup Counter
|
|
108
|
+
section id="counter"
|
|
109
|
+
output={0} id="counter-value"
|
|
110
|
+
div id="counter-controls"
|
|
111
|
+
button variant="counter-button" action="decrement" text="−" label={@counter.decrement}
|
|
112
|
+
button variant="counter-button_increase" action="increment" text="+" label={@counter.increment}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
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.
|
|
116
|
+
|
|
117
|
+
#### Style
|
|
118
|
+
|
|
119
|
+
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`.
|
|
120
|
+
|
|
121
|
+
```text
|
|
122
|
+
Style Counter
|
|
123
|
+
counter-button
|
|
124
|
+
flex items-center gap-2 px-4 py-2 border border-(--line-strong) rounded-lg
|
|
125
|
+
hover:border-(--accent-stroke) max-md:w-full
|
|
126
|
+
counter-button_increase
|
|
127
|
+
bg-(--primary) text-(--primary-ink)
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Dentro de un selector, una línea escrita como `propiedad: valor` es una declaración CSS. Por defecto, `.style` acepta solo CSS normal. Las utilidades son opcionales y viven en su propio paquete: instala `@aliens-syndicate/style` y decláralo en `.config` bajo `style:` con `from: @aliens-syndicate/style`. Sin él, una línea de utilidades detiene el build y explica cómo añadir el paquete. Con él, cualquier otra línea enumera utilidades con los nombres popularizados por frameworks de CSS existentes: `flex`, `gap-4`, `rounded-lg`, `text-sm`. Variantes como `md:`, `max-lg:`, `hover:` y `dark:` escriben la regla `@media` o el selector, y utilidades como `backdrop-blur-md` y `bg-clip-text` añaden las declaraciones `-webkit-`. Los corchetes aceptan cualquier valor, como en `w-[1240px]`, y los paréntesis leen una propiedad personalizada, como en `text-(--muted)`. Cada `--color-<nombre>` de los estilos globales se convierte en un color, como en `bg-brand`. Una utilidad desconocida detiene el build con el archivo y la línea. La página **Styles** del sitio de documentación (`#style-docs`) enumera cada clase con su CSS; `node tools/style-docs.mjs` la vuelve a generar a partir del catálogo del paquete.
|
|
131
|
+
|
|
132
|
+
Los iconos son opcionales y viven en su propio paquete. Instala `@aliens-syndicate/icons` y declaralo en `.config` en `icons:` con `from: @aliens-syndicate/icons` y un `style:` predeterminado. Los iconos pertenecen al markup, sin span y sin clase: `icon add-01 size-4 blue-500 red-500` nombra el icono y después, en cualquier orden, uno de los diez estilos, un tamaño, hasta dos colores (el segundo pinta el tono claro de bulk, duotone y twotone) y un estado como `disabled` o `hidden`; `id`, `variant` y `label` son sus únicos atributos. El build dibuja cada icono inline, y un proyecto sin el paquete se genera igual. La página **Icons** (`#icon-docs`) lista los 6070 iconos por categoría y copia la etiqueta de cualquiera; `node tools/icon-docs.mjs` la regenera a partir del paquete.
|
|
133
|
+
|
|
134
|
+
Los Elements listos también son opcionales y viven en `@aliens-syndicate/elements`; un proyecto nuevo empieza sin ellos. Instala el paquete y decláralo en `.config` bajo `elements:` con `from: @aliens-syndicate/elements`, y cualquier markup puede escribir `ui-button`, `ui-icon-button`, `ui-badge`, `ui-alert`, `ui-card`, `ui-avatar`, `ui-spinner`, `ui-progress`, `ui-stat`, `ui-accordion`, `ui-empty-state`, `ui-divider`, `ui-text-field`, `ui-checkbox` y `ui-switch` con sus propiedades, como en `ui-button label="Guardar" variant="ui-button_primary" action="save"`. Son archivos Space como los Elements del proyecto: el build los valida, `ai/.map` los lista y solo los Elements que la página renderiza llegan a `dist/`. Sus estilos son CSS puro que lee los tokens del starter, y un `.style` del proyecto con los mismos nombres de variant los sobrescribe. La página **Elements** (`#element-docs`) muestra cada uno en vivo, con sus propiedades y su código.
|
|
135
|
+
|
|
136
|
+
#### Logic
|
|
137
|
+
|
|
138
|
+
`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 `site-header` aplica `site-header_menu-open`. `page:` indica el signal que controla el tema o el idioma de la página.
|
|
139
|
+
|
|
140
|
+
```text
|
|
141
|
+
Logic SiteHeader
|
|
142
|
+
signal menuOpen: boolean = false
|
|
143
|
+
|
|
144
|
+
bind:
|
|
145
|
+
site-header:
|
|
146
|
+
_menu-open: this.menuOpen
|
|
147
|
+
site-header-menu-toggle:
|
|
148
|
+
expanded: this.menuOpen
|
|
149
|
+
|
|
150
|
+
actions:
|
|
151
|
+
toggleMenu:
|
|
152
|
+
returns: void
|
|
153
|
+
body:
|
|
154
|
+
this.menuOpen = !this.menuOpen
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
| En `bind:` | Efecto en la etiqueta |
|
|
158
|
+
| --- | --- |
|
|
159
|
+
| `text` | Sustituye el texto por el valor. |
|
|
160
|
+
| `show` | Muestra la etiqueta cuando el valor es verdadero. |
|
|
161
|
+
| `pressed` | Define `aria-pressed`. |
|
|
162
|
+
| `expanded` | Define `aria-expanded`. |
|
|
163
|
+
| `_modificador` | Aplica `id_modificador` mientras el valor sea verdadero. |
|
|
164
|
+
|
|
165
|
+
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`.
|
|
166
|
+
|
|
167
|
+
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`.
|
|
168
|
+
|
|
169
|
+
#### Listas y for
|
|
170
|
+
|
|
171
|
+
`list <nombre>:` en el `.logic` declara una lista fija. Cada elemento tiene un nombre, y ese nombre es su identidad: no hay `track` que declarar. En el markup, `for <item> in <lista>` repite las etiquetas que tiene debajo, y cada campo se lee como `{$item.campo}`.
|
|
172
|
+
|
|
173
|
+
```text
|
|
174
|
+
Logic SiteHeader
|
|
175
|
+
list links:
|
|
176
|
+
agent:
|
|
177
|
+
href: #agent
|
|
178
|
+
label: @nav.agent
|
|
179
|
+
files:
|
|
180
|
+
href: #files-index
|
|
181
|
+
label: @nav.files
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
```text
|
|
185
|
+
Markup SiteHeader
|
|
186
|
+
nav id="site-header-nav"
|
|
187
|
+
for link in links
|
|
188
|
+
nav-item href={$link.href} label={$link.label}
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
El build escribe el nombre del elemento como `data-key` en la primera etiqueta de cada repetición. `{$item.key}` y `{$item.index}` (desde cero) vienen incluidos, por eso `key` e `index` no pueden ser nombres de campo. La lista viene del `.logic` del Element o de un Element a su alrededor. Los nombres repetidos, los campos inexistentes y las listas desconocidas detienen el build con archivo y línea. Las listas se renderizan con la página; el runtime aún no las actualiza.
|
|
192
|
+
|
|
193
|
+
### Elements con solo los archivos necesarios
|
|
194
|
+
|
|
195
|
+
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.
|
|
196
|
+
|
|
197
|
+
| Archivos | Lo que hace el Element |
|
|
198
|
+
| --- | --- |
|
|
199
|
+
| `badge.markup` y `badge.style` | Renderiza estructura y apariencia. |
|
|
200
|
+
| `counter.markup`, `counter.logic` y `counter.style` | Renderiza y reacciona a acciones. |
|
|
201
|
+
| `session.logic` | Ejecuta una única instancia para la página y no renderiza nada. |
|
|
202
|
+
| `spinner.style` | Ofrece variants con el nombre del Element, como `spinner` y `spinner_large`. |
|
|
203
|
+
|
|
204
|
+
- **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.
|
|
205
|
+
- **Element solo con `.style`:** cualquier markup aplica sus nombres con `variant="spinner_large"`. El `.style` solo declara nombres que empiezan por el propio Element.
|
|
206
|
+
- **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`.
|
|
207
|
+
|
|
208
|
+
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.
|
|
209
|
+
|
|
210
|
+
La compilación es selectiva. El build valida todos los archivos, pero el resultado incluye solo:
|
|
211
|
+
|
|
212
|
+
- los estilos y la lógica de los Elements que la página renderiza;
|
|
213
|
+
- los Elements solo con `.style` cuyos nombres usa alguna etiqueta;
|
|
214
|
+
- los Elements solo con `.logic` que alguna etiqueta llama o que declaran `page:`.
|
|
215
|
+
|
|
216
|
+
Los estilos globales de `project/styles/` se incluyen siempre.
|
|
217
|
+
|
|
218
|
+
## Editor Space
|
|
219
|
+
|
|
220
|
+
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.
|
|
221
|
+
|
|
222
|
+
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.
|
|
223
|
+
|
|
224
|
+
Para desarrollar la extensión, abre una ventana temporal de VS Code desde la carpeta que contiene `project/` y `tools/`.
|
|
225
|
+
|
|
226
|
+
```sh
|
|
227
|
+
code --extensionDevelopmentPath="$PWD/tools/vscode-space" "$PWD"
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
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`.
|
|
231
|
+
|
|
232
|
+
## Abrir la vista previa
|
|
233
|
+
|
|
234
|
+
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.
|
|
235
|
+
|
|
236
|
+
```sh
|
|
237
|
+
node tools/build.mjs
|
|
238
|
+
open -a "Google Chrome" dist/index.html
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
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.
|
|
242
|
+
|
|
243
|
+
## Qué incluye
|
|
244
|
+
|
|
245
|
+
- 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.
|
|
246
|
+
- 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.
|
|
247
|
+
- 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.
|
|
248
|
+
|
|
249
|
+
## Lo que reveló el prototipo
|
|
250
|
+
|
|
251
|
+
- 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.
|
|
252
|
+
- 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.
|
|
253
|
+
- 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.
|
|
254
|
+
- El índice sigue el catálogo de 25 tipos. `.style` y `.mock` son las extensiones definidas para hojas de estilo y datos simulados, respectivamente.
|
|
255
|
+
- 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.
|
|
256
|
+
|
|
257
|
+
## Validación
|
|
258
|
+
|
|
259
|
+
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.
|
|
260
|
+
|
|
261
|
+
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.
|
|
262
|
+
|
|
263
|
+
## Licencia
|
|
264
|
+
|
|
265
|
+
Aliens Framework se distribuye bajo la [licencia MIT](LICENSE).
|
package/README.md
CHANGED
|
@@ -12,14 +12,28 @@ cd my-project
|
|
|
12
12
|
node tools/build.mjs
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
The same generator is published on npm as `@aliens-syndicate/cli` and works without cloning the repository.
|
|
15
|
+
The same generator is published on npm as `@aliens-syndicate/cli` and works without cloning the repository. Install it once with `npm install -g @aliens-syndicate/cli`; `aliens new` asks which extensions to use and runs `npm install`. Comments that start with `#AGENT` are directives for AI agents only: the build lists them, with file and line, under `directives:` in `ai/.map`.
|
|
16
16
|
|
|
17
17
|
```sh
|
|
18
|
-
|
|
18
|
+
npm install -g @aliens-syndicate/cli
|
|
19
|
+
aliens new my-project
|
|
19
20
|
cd my-project
|
|
20
|
-
|
|
21
|
+
aliens run
|
|
21
22
|
```
|
|
22
23
|
|
|
24
|
+
| Command | What it does |
|
|
25
|
+
| --- | --- |
|
|
26
|
+
| `aliens new <name>` (`n`) | Creates a project and asks which extensions to install. `--yes`, `--no-style`, `--no-icons`, `--no-elements` and `--skip-install` skip the questions. |
|
|
27
|
+
| `aliens run` | Builds, serves on http://localhost:5151 and rebuilds and reloads the browser on every save. `--port <number>` or `serve: port:` in `.config` changes the port. `aliens watch` is an alias. |
|
|
28
|
+
| `aliens build` | Runs the `tools/build.mjs` of the project and generates `dist/` and `ai/.map`. |
|
|
29
|
+
| `aliens generate <kind> <name>` (`g`) | Creates Space files. `aliens g element molecules/card` writes `.markup`, `.logic`, `.style` and `.test`; without the level the CLI asks. Existing files are kept and only the missing ones are added. Kinds: element (`e`), page (`p`), service (`s`), directive (`d`), interface (`i`), model (`m`), validator (`v`), route (`r`), api, animation, enum, error, guard, interceptor, mock, pipe, storage, agent, rule, skill. `--dry-run` writes nothing. |
|
|
30
|
+
| `aliens doctor` | Checks Node.js, npm, the CLI version, `.config`, the packages, the port and the build, with the fix for each problem. |
|
|
31
|
+
| `aliens update` | Updates the `@aliens-syndicate` packages of the project and copies the `tools/` of the installed CLI. `--dry-run` lists the changes. |
|
|
32
|
+
| `aliens cache` | Deletes `dist/` and the caches the tools keep. |
|
|
33
|
+
| `aliens version` | Shows the CLI, Node.js, system and package versions. `aliens --version` prints only the number. |
|
|
34
|
+
|
|
35
|
+
The comment at the top of `.config` lists the same commands, and the **Installation** page of the site (`#installation`) walks through them step by step.
|
|
36
|
+
|
|
23
37
|
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.
|
|
24
38
|
|
|
25
39
|
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/`.
|
|
@@ -117,6 +131,8 @@ Inside a selector, a line written as `property: value` is a CSS declaration. By
|
|
|
117
131
|
|
|
118
132
|
Icons are optional and live in their own package. Install `@aliens-syndicate/icons` and declare it in `.config` under `icons:` with `from: @aliens-syndicate/icons` and a default `style:`. Icons belong to the markup, with no span and no class: `icon add-01 size-4 blue-500 red-500` names the icon and then, in any order, one of the ten styles, a size, up to two colors (the second paints the light tone of bulk, duotone and twotone) and a state such as `disabled` or `hidden`; `id`, `variant` and `label` are its only attributes. The build draws each icon inline, and a project without the package builds the same way. The **Icons** page (`#icon-docs`) lists all 6,070 icons by category and copies the tag of any of them; `node tools/icon-docs.mjs` regenerates it from the package.
|
|
119
133
|
|
|
134
|
+
Ready-made Elements are optional too and live in `@aliens-syndicate/elements`; a new project starts without them. Install the package and declare it in `.config` under `elements:` with `from: @aliens-syndicate/elements`, and any markup can write `ui-button`, `ui-icon-button`, `ui-badge`, `ui-alert`, `ui-card`, `ui-avatar`, `ui-spinner`, `ui-progress`, `ui-stat`, `ui-accordion`, `ui-empty-state`, `ui-divider`, `ui-text-field`, `ui-checkbox` and `ui-switch` with their properties, as in `ui-button label="Save" variant="ui-button_primary" action="save"`. They are Space files like the Elements of the project: the build validates them, `ai/.map` lists them, and only the Elements a page renders reach `dist/`. Their styles are plain CSS that read the starter tokens, and a project `.style` with the same variant names overrides them. The **Elements** page (`#element-docs`) shows each one live, with its properties and source.
|
|
135
|
+
|
|
120
136
|
#### Logic
|
|
121
137
|
|
|
122
138
|
`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 `site-header` applies `site-header_menu-open`. `page:` names the signal that controls the page theme or language.
|
package/README.pt-BR.md
ADDED
|
@@ -0,0 +1,265 @@
|
|
|
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. Instale uma vez com `npm install -g @aliens-syndicate/cli`; o `aliens new` pergunta quais extensões usar e roda o `npm install`. Comentários que começam com `#AGENT` são diretivas só para agentes de IA: o build os lista, com arquivo e linha, em `directives:` no `ai/.map`.
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
npm install -g @aliens-syndicate/cli
|
|
19
|
+
aliens new meu-projeto
|
|
20
|
+
cd meu-projeto
|
|
21
|
+
aliens run
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
| Comando | O que faz |
|
|
25
|
+
| --- | --- |
|
|
26
|
+
| `aliens new <nome>` (`n`) | Cria um projeto e pergunta quais extensões instalar. `--yes`, `--no-style`, `--no-icons`, `--no-elements` e `--skip-install` pulam as perguntas. |
|
|
27
|
+
| `aliens run` | Faz o build, serve em http://localhost:5151 e refaz o build e recarrega o navegador a cada arquivo salvo. `--port <número>` ou `serve: port:` no `.config` troca a porta. `aliens watch` é um atalho. |
|
|
28
|
+
| `aliens build` | Executa o `tools/build.mjs` do projeto e gera `dist/` e `ai/.map`. |
|
|
29
|
+
| `aliens generate <tipo> <nome>` (`g`) | Cria arquivos Space. `aliens g element molecules/card` escreve `.markup`, `.logic`, `.style` e `.test`; sem o nível, a CLI pergunta. Arquivos que já existem são mantidos e só os que faltam são criados. Tipos: element (`e`), page (`p`), service (`s`), directive (`d`), interface (`i`), model (`m`), validator (`v`), route (`r`), api, animation, enum, error, guard, interceptor, mock, pipe, storage, agent, rule, skill. `--dry-run` não grava nada. |
|
|
30
|
+
| `aliens doctor` | Verifica Node.js, npm, a versão da CLI, o `.config`, os pacotes, a porta e o build, com a correção de cada problema. |
|
|
31
|
+
| `aliens update` | Atualiza os pacotes `@aliens-syndicate` do projeto e copia o `tools/` da CLI instalada. `--dry-run` lista as mudanças. |
|
|
32
|
+
| `aliens cache` | Apaga o `dist/` e os caches das ferramentas. |
|
|
33
|
+
| `aliens version` | Mostra as versões da CLI, do Node.js, do sistema e dos pacotes. `aliens --version` mostra só o número. |
|
|
34
|
+
|
|
35
|
+
O comentário no topo do `.config` lista os mesmos comandos, e a página **Instalação** do site (`#installation`) explica cada um passo a passo.
|
|
36
|
+
|
|
37
|
+
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.
|
|
38
|
+
|
|
39
|
+
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/`.
|
|
40
|
+
|
|
41
|
+
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.
|
|
42
|
+
|
|
43
|
+
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.
|
|
44
|
+
|
|
45
|
+
## Biblioteca de estilos e temas
|
|
46
|
+
|
|
47
|
+
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`.
|
|
48
|
+
|
|
49
|
+
- `project/styles/settings/` reúne os tokens de cor, espaço, raio, borda, tipografia e elevação.
|
|
50
|
+
- `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.
|
|
51
|
+
- `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.
|
|
52
|
+
- `project/app/pages/kit-*/` contém as páginas de amostras. Os Elements reutilizáveis ficam nos níveis do Atomic Design.
|
|
53
|
+
|
|
54
|
+
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.
|
|
55
|
+
|
|
56
|
+
```text
|
|
57
|
+
:root[data-theme="ocean"]
|
|
58
|
+
color-scheme: light
|
|
59
|
+
--color-brand: #075985
|
|
60
|
+
--color-brand-hover: #0c4a6e
|
|
61
|
+
--color-on-brand: #ffffff
|
|
62
|
+
--color-focus: #075985
|
|
63
|
+
--color-accent: #e0f2fe
|
|
64
|
+
--color-on-accent: #0c4a6e
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
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.
|
|
68
|
+
|
|
69
|
+
## Atomic Design
|
|
70
|
+
|
|
71
|
+
- `atoms/` contém elementos básicos, como botões, links e controles de tema.
|
|
72
|
+
- `molecules/` contém componentes de função específica, como busca, seletor de idioma e contador.
|
|
73
|
+
- `organisms/` contém composições como cabeçalho, menu lateral, grade de guias e playground.
|
|
74
|
+
- `templates/` contém o layout reutilizável dos painéis de referência.
|
|
75
|
+
|
|
76
|
+
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.
|
|
77
|
+
|
|
78
|
+
## Padrão Space
|
|
79
|
+
|
|
80
|
+
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 `#`.
|
|
81
|
+
|
|
82
|
+
```text
|
|
83
|
+
Markup App
|
|
84
|
+
home
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
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.
|
|
88
|
+
|
|
89
|
+
### Nomes: element-filho_modificador:estado
|
|
90
|
+
|
|
91
|
+
O `.markup`, o `.style` e o `.logic` usam os mesmos nomes, sempre em minúsculas. Cada separador tem um papel:
|
|
92
|
+
|
|
93
|
+
| Conceito | Separador | Exemplo |
|
|
94
|
+
| --- | --- | --- |
|
|
95
|
+
| Element | nenhum além do próprio nome | `site-header` |
|
|
96
|
+
| Filho | `-` | `site-header-logo` |
|
|
97
|
+
| Modificador | `_` | `site-header-logo_large` |
|
|
98
|
+
| Estado | `:` | `site-header-logo_large:hover` |
|
|
99
|
+
|
|
100
|
+
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`.
|
|
101
|
+
|
|
102
|
+
#### Markup
|
|
103
|
+
|
|
104
|
+
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"`.
|
|
105
|
+
|
|
106
|
+
```text
|
|
107
|
+
Markup Counter
|
|
108
|
+
section id="counter"
|
|
109
|
+
output={0} id="counter-value"
|
|
110
|
+
div id="counter-controls"
|
|
111
|
+
button variant="counter-button" action="decrement" text="−" label={@counter.decrement}
|
|
112
|
+
button variant="counter-button_increase" action="increment" text="+" label={@counter.increment}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
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.
|
|
116
|
+
|
|
117
|
+
#### Style
|
|
118
|
+
|
|
119
|
+
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`.
|
|
120
|
+
|
|
121
|
+
```text
|
|
122
|
+
Style Counter
|
|
123
|
+
counter-button
|
|
124
|
+
flex items-center gap-2 px-4 py-2 border border-(--line-strong) rounded-lg
|
|
125
|
+
hover:border-(--accent-stroke) max-md:w-full
|
|
126
|
+
counter-button_increase
|
|
127
|
+
bg-(--primary) text-(--primary-ink)
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Dentro de um seletor, uma linha escrita como `propriedade: valor` é uma declaração CSS. Por padrão, `.style` aceita apenas CSS normal. Os utilitários são opcionais e ficam num pacote próprio: instale `@aliens-syndicate/style` e declare-o no `.config` em `style:` com `from: @aliens-syndicate/style`. Sem ele, uma linha de utilitários interrompe o build e diz como adicionar o pacote. Com ele, qualquer outra linha lista utilitários com os nomes popularizados por frameworks de CSS existentes: `flex`, `gap-4`, `rounded-lg`, `text-sm`. Variantes como `md:`, `max-lg:`, `hover:` e `dark:` escrevem a regra `@media` ou o seletor, e utilitários como `backdrop-blur-md` e `bg-clip-text` acrescentam as declarações `-webkit-`. Colchetes aceitam qualquer valor, como em `w-[1240px]`, e parênteses leem uma propriedade customizada, como em `text-(--muted)`. Cada `--color-<nome>` dos estilos globais vira uma cor, como em `bg-brand`. Um utilitário desconhecido interrompe o build com o arquivo e a linha. A página **Styles** do site de documentação (`#style-docs`) lista cada classe com o seu CSS; `node tools/style-docs.mjs` a gera de novo a partir do catálogo do pacote.
|
|
131
|
+
|
|
132
|
+
Os ícones são opcionais e ficam em um pacote próprio. Instale `@aliens-syndicate/icons` e declare no `.config` em `icons:` com `from: @aliens-syndicate/icons` e um `style:` padrão. Os ícones pertencem ao markup, sem span e sem classe: `icon add-01 size-4 blue-500 red-500` dá o nome do ícone e depois, em qualquer ordem, um dos dez estilos, um tamanho, até duas cores (a segunda pinta o tom claro do bulk, duotone e twotone) e um estado como `disabled` ou `hidden`; `id`, `variant` e `label` são seus únicos atributos. O build desenha cada ícone inline, e um projeto sem o pacote é gerado do mesmo jeito. A página **Icons** (`#icon-docs`) lista os 6.070 ícones por categoria e copia a tag de qualquer um; `node tools/icon-docs.mjs` a regenera a partir do pacote.
|
|
133
|
+
|
|
134
|
+
Os Elements prontos também são opcionais e ficam em `@aliens-syndicate/elements`; um projeto novo começa sem eles. Instale o pacote e declare no `.config` em `elements:` com `from: @aliens-syndicate/elements`, e qualquer markup pode escrever `ui-button`, `ui-icon-button`, `ui-badge`, `ui-alert`, `ui-card`, `ui-avatar`, `ui-spinner`, `ui-progress`, `ui-stat`, `ui-accordion`, `ui-empty-state`, `ui-divider`, `ui-text-field`, `ui-checkbox` e `ui-switch` com suas propriedades, como em `ui-button label="Salvar" variant="ui-button_primary" action="save"`. Eles são arquivos Space como os Elements do projeto: o build os valida, o `ai/.map` os lista e só os Elements que a página renderiza chegam ao `dist/`. Os estilos são CSS puro que lê os tokens do starter, e um `.style` do projeto com os mesmos nomes de variant os sobrescreve. A página **Elements** (`#element-docs`) mostra cada um ao vivo, com propriedades e código.
|
|
135
|
+
|
|
136
|
+
#### Logic
|
|
137
|
+
|
|
138
|
+
`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 `site-header` aplica `site-header_menu-open`. `page:` indica o signal que controla o tema ou o idioma da página.
|
|
139
|
+
|
|
140
|
+
```text
|
|
141
|
+
Logic SiteHeader
|
|
142
|
+
signal menuOpen: boolean = false
|
|
143
|
+
|
|
144
|
+
bind:
|
|
145
|
+
site-header:
|
|
146
|
+
_menu-open: this.menuOpen
|
|
147
|
+
site-header-menu-toggle:
|
|
148
|
+
expanded: this.menuOpen
|
|
149
|
+
|
|
150
|
+
actions:
|
|
151
|
+
toggleMenu:
|
|
152
|
+
returns: void
|
|
153
|
+
body:
|
|
154
|
+
this.menuOpen = !this.menuOpen
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
| Em `bind:` | Efeito na tag |
|
|
158
|
+
| --- | --- |
|
|
159
|
+
| `text` | Troca o texto pelo valor. |
|
|
160
|
+
| `show` | Mostra a tag quando o valor é verdadeiro. |
|
|
161
|
+
| `pressed` | Define `aria-pressed`. |
|
|
162
|
+
| `expanded` | Define `aria-expanded`. |
|
|
163
|
+
| `_modificador` | Aplica `id_modificador` enquanto o valor for verdadeiro. |
|
|
164
|
+
|
|
165
|
+
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`.
|
|
166
|
+
|
|
167
|
+
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`.
|
|
168
|
+
|
|
169
|
+
#### Listas e for
|
|
170
|
+
|
|
171
|
+
`list <nome>:` no `.logic` declara uma lista fixa. Cada item tem um nome, e esse nome é a identidade dele: não existe `track` para declarar. No markup, `for <item> in <lista>` repete as tags abaixo dele, e cada campo é lido como `{$item.campo}`.
|
|
172
|
+
|
|
173
|
+
```text
|
|
174
|
+
Logic SiteHeader
|
|
175
|
+
list links:
|
|
176
|
+
agent:
|
|
177
|
+
href: #agent
|
|
178
|
+
label: @nav.agent
|
|
179
|
+
files:
|
|
180
|
+
href: #files-index
|
|
181
|
+
label: @nav.files
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
```text
|
|
185
|
+
Markup SiteHeader
|
|
186
|
+
nav id="site-header-nav"
|
|
187
|
+
for link in links
|
|
188
|
+
nav-item href={$link.href} label={$link.label}
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
O build grava o nome do item como `data-key` na primeira tag de cada repetição. `{$item.key}` e `{$item.index}` (a partir de zero) já vêm prontos, por isso `key` e `index` não podem ser nomes de campo. A lista vem do `.logic` do Element ou de um Element ao redor. Nomes repetidos, campos inexistentes e listas desconhecidas param o build com arquivo e linha. As listas são renderizadas com a página; o runtime ainda não as atualiza.
|
|
192
|
+
|
|
193
|
+
### Elements com os arquivos necessários
|
|
194
|
+
|
|
195
|
+
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.
|
|
196
|
+
|
|
197
|
+
| Arquivos | O que o Element faz |
|
|
198
|
+
| --- | --- |
|
|
199
|
+
| `badge.markup` e `badge.style` | Renderiza estrutura e aparência. |
|
|
200
|
+
| `counter.markup`, `counter.logic` e `counter.style` | Renderiza e reage a ações. |
|
|
201
|
+
| `session.logic` | Executa uma instância única para a página e não renderiza nada. |
|
|
202
|
+
| `spinner.style` | Fornece variants com o nome do Element, como `spinner` e `spinner_large`. |
|
|
203
|
+
|
|
204
|
+
- **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.
|
|
205
|
+
- **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.
|
|
206
|
+
- **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`.
|
|
207
|
+
|
|
208
|
+
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.
|
|
209
|
+
|
|
210
|
+
A compilação é seletiva. O build valida todos os arquivos, mas o resultado inclui apenas:
|
|
211
|
+
|
|
212
|
+
- os estilos e a lógica dos Elements que a página renderiza;
|
|
213
|
+
- os Elements só com `.style` cujos nomes alguma tag usa;
|
|
214
|
+
- os Elements só com `.logic` que alguma tag chama ou que declaram `page:`.
|
|
215
|
+
|
|
216
|
+
Os estilos globais de `project/styles/` entram sempre.
|
|
217
|
+
|
|
218
|
+
## Editor Space
|
|
219
|
+
|
|
220
|
+
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.
|
|
221
|
+
|
|
222
|
+
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.
|
|
223
|
+
|
|
224
|
+
Para desenvolver a extensão, abra uma janela temporária do VS Code a partir da pasta que contém `project/` e `tools/`.
|
|
225
|
+
|
|
226
|
+
```sh
|
|
227
|
+
code --extensionDevelopmentPath="$PWD/tools/vscode-space" "$PWD"
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
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`.
|
|
231
|
+
|
|
232
|
+
## Abrir a prévia
|
|
233
|
+
|
|
234
|
+
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.
|
|
235
|
+
|
|
236
|
+
```sh
|
|
237
|
+
node tools/build.mjs
|
|
238
|
+
open -a "Google Chrome" dist/index.html
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
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.
|
|
242
|
+
|
|
243
|
+
## O que entrou
|
|
244
|
+
|
|
245
|
+
- 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.
|
|
246
|
+
- 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.
|
|
247
|
+
- 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.
|
|
248
|
+
|
|
249
|
+
## O que o protótipo revelou
|
|
250
|
+
|
|
251
|
+
- 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.
|
|
252
|
+
- 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.
|
|
253
|
+
- 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.
|
|
254
|
+
- 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.
|
|
255
|
+
- 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.
|
|
256
|
+
|
|
257
|
+
## Validação
|
|
258
|
+
|
|
259
|
+
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.
|
|
260
|
+
|
|
261
|
+
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.
|
|
262
|
+
|
|
263
|
+
## Licença
|
|
264
|
+
|
|
265
|
+
O Aliens Framework é distribuído sob a [licença MIT](LICENSE).
|