blessed-components 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 el_jijuna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# blessed-components
+
+Composable, typed terminal UI components for
+[Blessed](https://github.com/chjj/blessed).
+
+> **Project status:** foundation stage. The package structure and automated
+> release pipeline are ready; UI components are coming soon.
+
+## Goals
+
+- Small, consistent component APIs.
+- Deterministic renderers that can be tested without a terminal.
+- Thin adapters for Blessed elements and lifecycle.
+- Responsive layouts for narrow terminals.
+- Unicode, ASCII, color, and no-color modes.
+- TypeScript types included with every release.
+
+## Installation
+
+Components are not available yet. Once the first component ships:
+
+```sh
+npm install blessed blessed-components
+```
+
+`blessed` is a peer dependency.
+
+## Coming soon
+
+### Core components
+
+| Component     | Purpose                                              | Priority |
+| ------------- | ---------------------------------------------------- | -------- |
+| `ProgressBar` | Render one bounded horizontal progress bar.          | P0       |
+| `Sparkline`   | Render compact time-series data with Unicode blocks. | P0       |
+| `MetricBars`  | Render labeled metrics as aligned progress bars.     | P0       |
+| `Stat`        | Display a label and highlighted value.               | P0       |
+
+### Composition
+
+| Component  | Purpose                                               | Priority |
+| ---------- | ----------------------------------------------------- | -------- |
+| `Card`     | Frame content with an optional title and footer.      | P1       |
+| `KeyValue` | Display aligned label/value rows.                     | P1       |
+| `Badge`    | Display compact semantic status text.                 | P1       |
+| `Divider`  | Separate terminal content horizontally or vertically. | P1       |
+| `Stack`    | Arrange components with consistent spacing.           | P2       |
+
+### Feedback and live data
+
+| Component   | Purpose                                            | Priority |
+| ----------- | -------------------------------------------------- | -------- |
+| `Spinner`   | Show ongoing work.                                 | P1       |
+| `Status`    | Display semantic state and optional details.       | P1       |
+| `Alert`     | Display informational, warning, or error messages. | P1       |
+| `LogViewer` | Stream and retain bounded log output.              | P1       |
+| `Timer`     | Display elapsed or remaining time.                 | P1       |
+
+### Data visualization
+
+| Component   | Purpose                               | Priority |
+| ----------- | ------------------------------------- | -------- |
+| `Table`     | Display structured tabular data.      | P1       |
+| `BarChart`  | Compare categorical values.           | P2       |
+| `LineChart` | Display one or more time series.      | P2       |
+| `Histogram` | Display value distributions.          | P2       |
+| `Tree`      | Navigate hierarchical data.           | P3       |
+| `Heatmap`   | Display dense two-dimensional values. | P3       |
+
+### Interaction
+
+| Component        | Purpose                      | Priority |
+| ---------------- | ---------------------------- | -------- |
+| `Tabs`           | Switch between views.        | P2       |
+| `Menu`           | Navigate a list of actions.  | P2       |
+| `Select`         | Choose one or more values.   | P3       |
+| `TextField`      | Enter and validate text.     | P3       |
+| `Form`           | Compose terminal inputs.     | P3       |
+| `CommandPalette` | Search and execute commands. | P3       |
+
+See [ROADMAP.md](./ROADMAP.md) for milestones, proposed APIs, and TDD strategy.
+
+## Architecture
+
+```text
+src/
+  core/         framework-independent rendering primitives
+  components/   pure component renderers
+  adapters/     Blessed widget adapters
+tests/
+  public-api/           behavior through exported APIs
+  blessed-integration/  integration with real Blessed elements
+examples/
+  dashboard/            executable component showcase
+```
+
+Renderers remain independent from Blessed. Adapters own element updates,
+listeners, timers, and cleanup.
+
+## Development
+
+Requires Node.js 22.14 or newer.
+
+```sh
+npm install
+npm run validate
+```
+
+Useful commands:
+
+```sh
+npm run build
+npm test
+npm run test:watch
+npm run lint
+npm run typecheck
+npm run format
+```
+
+## Testing
+
+Development follows vertical TDD slices:
+
+1. Add one failing test for public behavior.
+2. Add minimum implementation needed to pass.
+3. Refactor while tests remain green.
+4. Repeat with next behavior.
+
+Tests should use public interfaces and observable output. Internal mocks and
+large snapshots are avoided.
+
+## Releases
+
+[semantic-release](https://github.com/semantic-release/semantic-release)
+publishes from `main`.
+
+Commit messages follow
+[Conventional Commits](https://www.conventionalcommits.org/):
+
+```text
+fix: clamp progress values
+feat: add progress bar renderer
+feat!: change component update contract
+```
+
+Release mapping:
+
+| Commit          | Release |
+| --------------- | ------- |
+| `fix:`          | Patch   |
+| `feat:`         | Minor   |
+| Breaking change | Major   |
+
+The release workflow:
+
+1. Validates formatting, linting, types, tests, and build.
+2. Calculates the next version from commits.
+3. Publishes the package to npm.
+4. Creates a GitHub release with generated notes.
+
+### npm trusted publishing setup
+
+Before the first release, configure an npm trusted publisher for:
+
+- Organization or user: `ElJijuna`
+- Repository: `blessed-components`
+- Workflow filename: `release.yml`
+
+The workflow uses GitHub Actions OIDC and npm provenance. No long-lived
+`NPM_TOKEN` is required.
+
+## License
+
+[MIT](./LICENSE)

package/ROADMAP.md

@@ -0,0 +1,406 @@
+# blessed-components — Roadmap
+
+Biblioteca de componentes reutilizables para interfaces de terminal construidas
+sobre `blessed`.
+
+## Visión
+
+Convertir bloques de texto, tags, Unicode, cálculo de ancho y estado en
+componentes con:
+
+- API pequeña y consistente.
+- renderizado determinista.
+- actualización de datos sin reconstruir pantalla.
+- soporte para terminales estrechas, sin color y sin Unicode.
+- integración directa con elementos `blessed`.
+- pruebas mediante API pública.
+
+## Vocabulario
+
+Los ejemplos iniciales representan dos componentes distintos:
+
+| Nombre        | Responsabilidad                                          |
+| ------------- | -------------------------------------------------------- |
+| `Sparkline`   | Serie temporal compacta usando `▁▂▃▄▅▆▇█`.               |
+| `MetricBars`  | Grupo de métricas con barras horizontales y porcentajes. |
+| `ProgressBar` | Una sola barra horizontal. Base usada por `MetricBars`.  |
+| `Stat`        | Etiqueta y valor destacado.                              |
+| `Card`        | Marco opcional que compone título, contenido y pie.      |
+
+`BarChart` queda reservado para barras que representan categorías o series. No
+debe usarse para `Sparkline` ni `ProgressBar`.
+
+## API pública propuesta
+
+Dos capas:
+
+1. Renderers puros: reciben datos y retornan contenido compatible con
+   `blessed`.
+2. Widgets: crean elementos `blessed`, conservan estado y exponen `setData`.
+
+```ts
+import {
+  renderSparkline,
+  renderMetricBars,
+  sparkline,
+  metricBars,
+} from 'blessed-components'
+```
+
+### Renderer puro
+
+```ts
+const content = renderSparkline({
+  label: 'Last 30 days',
+  values: [1, 2, 3, 4, 3, 5, 6, 7, 8],
+  summary: 'peak: 3.8M',
+  width: 40,
+})
+```
+
+### Widget Blessed
+
+```ts
+const downloads = sparkline({
+  parent: screen,
+  label: 'Weekly downloads',
+  value: 25_200_000,
+  values: downloadsByDay,
+  summary: 'peak: 3.8M',
+  top: 0,
+  left: 0,
+  width: 42,
+  height: 7,
+})
+
+downloads.setData(nextDownloadsByDay)
+```
+
+### MetricBars
+
+```ts
+const score = metricBars({
+  parent: screen,
+  label: 'Overall',
+  value: 85,
+  metrics: [
+    { label: 'Quality', value: 78 },
+    { label: 'Popularity', value: 99 },
+    { label: 'Maintenance', value: 82 },
+  ],
+  min: 0,
+  max: 100,
+})
+```
+
+## Principios de diseño
+
+- Datos separados de presentación.
+- Renderer puro como fuente única del contenido.
+- Widget `blessed` como adaptador fino.
+- `setData` actualiza contenido; caller decide cuándo ejecutar
+  `screen.render()`.
+- Dimensiones automáticas usan ancho interior real.
+- Valores fuera de rango se limitan mediante `clamp`.
+- Datos inválidos producen error descriptivo o estado vacío documentado.
+- Tema mediante tokens semánticos, no tags escritos por consumidor.
+- Colores y caracteres configurables por componente.
+- Sin mutación de arrays u objetos recibidos.
+- TypeScript primero; tipos publicados con paquete.
+- Dependencia `blessed` como `peerDependency`.
+
+## Arquitectura objetivo
+
+```text
+src/
+  core/
+    width.ts
+    scale.ts
+    format.ts
+    theme.ts
+    tags.ts
+  components/
+    stat/
+    progress-bar/
+    sparkline/
+    metric-bars/
+  adapters/
+    blessed.ts
+  index.ts
+tests/
+  public-api/
+  blessed-integration/
+examples/
+  dashboard/
+```
+
+`core` no conoce `blessed`. `components` usa `core` para producir modelos o
+contenido. `adapters` conecta contenido, eventos y ciclo de vida con
+`blessed`.
+
+## Estrategia TDD
+
+Desarrollo por cortes verticales. Nunca escribir todas las pruebas antes de
+toda la implementación.
+
+```text
+RED: prueba de un comportamiento público
+  ↓
+GREEN: implementación mínima
+  ↓
+REFACTOR: limpiar manteniendo verde
+  ↓
+siguiente comportamiento
+```
+
+Prioridad de pruebas:
+
+1. Salida visible del renderer público.
+2. Límites, escalado y ancho disponible.
+3. Actualización mediante `setData`.
+4. Integración real con elemento `blessed`.
+5. Fallbacks ASCII, sin color y estado vacío.
+
+Evitar pruebas de funciones privadas, mocks internos o estructura de carpetas.
+Snapshots grandes no serán contrato principal; usar expectativas pequeñas y
+legibles.
+
+## Hitos
+
+### M0 — Fundación del paquete
+
+Objetivo: paquete instalable, testeable y publicable.
+
+- Configurar TypeScript.
+- Elegir runner de pruebas.
+- Definir builds ESM y CommonJS según compatibilidad real de `blessed`.
+- Configurar lint, format, coverage y CI.
+- Publicar exports y tipos.
+- Añadir ejemplo mínimo que monte un componente en `blessed`.
+
+Criterio de salida:
+
+- `npm test`, `npm run build` y typecheck pasan.
+- consumidor externo puede importar un renderer.
+- CI prueba versiones Node soportadas.
+
+### M1 — Tracer bullet: ProgressBar
+
+Objetivo: probar camino completo renderer → widget → pantalla.
+
+Ciclos RED→GREEN:
+
+1. Renderiza barra al 50% con ancho fijo.
+2. Limita valores menores que `min` y mayores que `max`.
+3. Muestra etiqueta y valor formateado.
+4. Respeta ancho interior estrecho.
+5. `setData` cambia contenido del widget.
+6. Usa caracteres ASCII cuando Unicode está desactivado.
+
+Criterio de salida:
+
+- API pública validada con un componente pequeño.
+- patrón reutilizable para próximos widgets.
+
+### M2 — Sparkline
+
+Objetivo: componetizar gráfico de descargas.
+
+Ciclos RED→GREEN:
+
+1. Escala valores al rango `▁`…`█`.
+2. Conserva orden de serie.
+3. Maneja serie constante sin división por cero.
+4. Maneja serie vacía con placeholder.
+5. Reduce o recorta datos según ancho disponible.
+6. Renderiza label, valor principal y summary opcionales.
+7. Actualiza serie mediante `setData`.
+8. Permite dominio explícito `{ min, max }`.
+
+Criterio de salida:
+
+- ejemplo `downloads` ya no contiene strings de presentación manuales.
+- salida estable en terminal estrecha.
+
+### M3 — MetricBars
+
+Objetivo: componetizar score general y desglose.
+
+Ciclos RED→GREEN:
+
+1. Renderiza una métrica mediante `ProgressBar`.
+2. Alinea labels usando ancho visible, no longitud bruta con tags.
+3. Renderiza varias métricas en orden.
+4. Calcula ancho restante para barra y valor.
+5. Trunca labels largos.
+6. Admite valor general opcional.
+7. Actualiza una lista completa mediante `setData`.
+
+Criterio de salida:
+
+- ejemplo `score` usa datos estructurados.
+- `MetricBars` compone `ProgressBar`; no duplica escalado.
+
+### M4 — Sistema visual
+
+Objetivo: consistencia entre componentes.
+
+- `Theme`: `primary`, `muted`, `success`, `warning`, `danger`, `border`.
+- Presets `unicode`, `ascii`, `noColor`.
+- `formatNumber`, `formatPercent`, `formatDuration`, `formatBytes`.
+- Utilidad de ancho visible compatible con tags `blessed`.
+- Escape seguro de texto dinámico.
+- Estados `empty`, `loading`, `error`, `disabled`.
+
+Criterio de salida:
+
+- consumidor cambia apariencia sin construir tags manuales.
+- texto con llaves o tags no rompe contenido.
+
+### M5 — Composición de dashboard
+
+Objetivo: construir pantallas completas sin strings monolíticos.
+
+Componentes:
+
+- `Stat`
+- `Card`
+- `KeyValue`
+- `Badge`
+- `Divider`
+- `Stack`
+
+Validación:
+
+- dashboard de ejemplo combina `Stat`, `Sparkline` y `MetricBars`.
+- resize recalcula contenido sin fugas de listeners.
+- navegación de foco sigue siendo responsabilidad clara.
+
+### M6 — Feedback y datos vivos
+
+Componentes:
+
+- `Spinner`
+- `Status`
+- `Alert`
+- `LogViewer`
+- `Timer`
+
+Capacidades:
+
+- actualizaciones frecuentes con render mínimo.
+- pausa, reanudación y limpieza de timers/listeners.
+- límite configurable de historial.
+
+### M7 — Datos avanzados
+
+Componentes:
+
+- `BarChart`
+- `LineChart`
+- `Histogram`
+- `Heatmap`
+- `Table`
+- `Tree`
+
+Regla: construir solo cuando primitives actuales no puedan componer caso.
+Evitar duplicar `blessed-contrib` sin ventaja clara de API, tamaño, pruebas o
+accesibilidad.
+
+### M8 — Interacción
+
+Componentes:
+
+- `Tabs`
+- `Menu`
+- `CommandPalette`
+- `Select`
+- `TextField`
+- `Form`
+
+Requisitos:
+
+- teclado configurable.
+- foco visible.
+- cleanup completo de eventos.
+- acciones públicas testeables sin inspeccionar internals.
+
+### M9 — Release 1.0
+
+- API estable y política SemVer.
+- documentación por componente.
+- ejemplos copiables.
+- tabla de compatibilidad Node, terminal y `blessed`.
+- changelog y guía de migración.
+- pruebas en Linux, macOS y Windows.
+- presupuesto de tamaño y rendimiento.
+
+## Backlog de componentes
+
+| Prioridad | Componente                                  | Estado objetivo   |
+| --------- | ------------------------------------------- | ----------------- |
+| P0        | `ProgressBar`                               | tracer bullet     |
+| P0        | `Sparkline`                                 | ejemplo downloads |
+| P0        | `MetricBars`                                | ejemplo score     |
+| P0        | `Stat`                                      | valor destacado   |
+| P1        | `Card`, `KeyValue`, `Badge`, `Divider`      | composición       |
+| P1        | `Spinner`, `Status`, `Alert`                | feedback          |
+| P1        | `Table`, `LogViewer`                        | datos             |
+| P2        | `Stack`, `Tabs`, `Menu`                     | layout/navegación |
+| P2        | `BarChart`, `LineChart`, `Histogram`        | charts            |
+| P3        | `CommandPalette`, `Form`, `Tree`, `Heatmap` | avanzado          |
+
+## Contratos comunes
+
+Todos los componentes deben definir:
+
+- datos aceptados.
+- salida para datos vacíos.
+- comportamiento ante valores inválidos.
+- política de truncado y resize.
+- soporte color/Unicode.
+- métodos de actualización.
+- eventos emitidos, si existen.
+- ownership de listeners, timers y destrucción.
+
+Interfaz común candidata:
+
+```ts
+interface ComponentHandle<T> {
+  element: blessed.Widgets.BoxElement
+  setData(data: T): void
+  destroy(): void
+}
+```
+
+Adoptar solo después del tracer bullet. Si retornar directamente elemento
+`blessed` resulta más natural, preferir API menor.
+
+## Definition of Done por componente
+
+- API pública documentada.
+- cada comportamiento agregado mediante ciclo RED→GREEN.
+- tests ejercen renderer/widget público.
+- estados normal, vacío, inválido y estrecho cubiertos.
+- Unicode y ASCII cubiertos.
+- ejemplo ejecutable.
+- cero listeners o timers después de `destroy`.
+- exports y tipos verificados desde paquete compilado.
+- changelog actualizado.
+
+## Decisiones antes de implementar M0
+
+1. Runtime mínimo de Node.
+2. TypeScript obligatorio o JS con tipos generados.
+3. Runner: Vitest, Node test runner u otro.
+4. Soporte ESM, CommonJS o ambos.
+5. `blessed` exacto soportado: paquete original o fork mantenido.
+6. Primera API de widget:
+   - retornar elemento `blessed` extendido; o
+   - retornar `ComponentHandle`.
+7. Política de resize:
+   - automática mediante eventos; o
+   - explícita mediante `setSize`/`render`.
+
+Recomendación inicial: resolver estas decisiones durante M0; después ejecutar
+M1 como tracer bullet antes de ampliar catálogo.

package/dist/index.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "blessed-components",
+  "version": "0.0.1",
+  "description": "Composable, typed terminal UI components for Blessed.",
+  "keywords": [
+    "blessed",
+    "cli",
+    "components",
+    "terminal",
+    "tui"
+  ],
+  "homepage": "https://github.com/ElJijuna/blessed-components#readme",
+  "bugs": {
+    "url": "https://github.com/ElJijuna/blessed-components/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ElJijuna/blessed-components.git"
+  },
+  "license": "MIT",
+  "author": "pilmee <pilmee@gmail.com> (https://github.com/ElJijuna)",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "ROADMAP.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "packageManager": "npm@11.16.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf coverage dist",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "release": "semantic-release",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "validate": "npm run format:check && npm run lint && npm run typecheck && npm test && npm run build",
+    "prepublishOnly": "npm run validate"
+  },
+  "peerDependencies": {
+    "blessed": "^0.1.81"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/github": "^12.0.8",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.1",
+    "@types/blessed": "^0.1.27",
+    "@types/node": "^22.20.0",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "eslint": "^10.5.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.4",
+    "semantic-release": "^25.0.5",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.61.1",
+    "vitest": "^4.1.9"
+  }
+}