@ngx-docs-markdown-kit/ui
v0.1.0
Published
Componentes de Angular genericos y reusables (sin logica de parseo de markdown) compartidos entre los paquetes de este ecosistema y las plantillas de create-ngx-docs-site.
Readme
@ngx-docs-markdown-kit/ui
Componentes de Angular genericos y reusables, sin ninguna logica de parseo de markdown -- separado
de @ngx-docs-markdown-kit/parser-md-code-block (de donde se movio SearchableSelectComponent)
para que consumirlos no arrastre highlight.js, CodeThemeService, ni el catalogo de temas de
codigo si solo necesitas el componente en si.
SearchableSelectComponent
Select con buscador para catalogos largos ({id, label}[]) donde una lista desplegable comun se
vuelve inmanejable -- filtra por label mientras se escribe, muestra maximo 10 resultados, y un
boton "Ver todo" quita ese limite. No es especifico de ningun caso de uso en particular (el
selector de tema de codigo del CLI lo usa, pero cualquier catalogo del mismo shape sirve).
import { SearchableSelectComponent, type SearchableSelectItem } from '@ngx-docs-markdown-kit/ui';<ndmk-searchable-select
[items]="items"
[value]="selectedId"
placeholder="Buscar..."
(valueChange)="onSelect($event)"
/>ui
Dependencias:
@angular/animations: ^22.1.0@angular/cdk: ^22.1.0@angular/common: ^22.1.0@angular/compiler: ^22.1.0@angular/core: ^22.1.0@angular/forms: ^22.1.0@angular/material: ^22.1.0@angular/platform-browser: ^22.1.0@angular/platform-server: ^22.1.0@angular/router: ^22.1.0@angular/ssr: ^22.1.3@ngx-docs-markdown-kit/parser-md: file:./vendor/parser-md/ngx-docs-markdown-kit-parser-md-0.1.0.tgz@ngx-docs-markdown-kit/parser-md-seo: file:./vendor/parser-md-seo/ngx-docs-markdown-kit-parser-md-seo-0.1.0.tgz@ngx-docs-markdown-kit/parser-md-code-block: file:./vendor/parser-md-code-block/ngx-docs-markdown-kit-parser-md-code-block-0.1.0.tgz@ngx-docs-markdown-kit/parser-md-code-block-themes: file:./vendor/parser-md-code-block-themes/ngx-docs-markdown-kit-parser-md-code-block-themes-0.1.0.tgz@ngx-docs-markdown-kit/parser-md-image: file:./vendor/parser-md-image/ngx-docs-markdown-kit-parser-md-image-0.1.0.tgz@ngx-docs-markdown-kit/parser-md-card: file:./vendor/parser-md-card/ngx-docs-markdown-kit-parser-md-card-0.1.0.tgz@ngx-docs-markdown-kit/parser-md-converter: file:./vendor/parser-md-converter/ngx-docs-markdown-kit-parser-md-converter-0.1.0.tgz@ngx-docs-markdown-kit/ui: file:./vendor/ui/ngx-docs-markdown-kit-ui-0.1.0.tgzrxjs: ~7.8.0tslib: ^2.3.0
Apartados de ui
- Docs -- @ngx-docs-markdown-kit/ui -- componentes de Angular genéricos y reusables, sin lógica de parseo de Markdown. Hoy: SearchableSelectComponent.
- UI -- Componentes de Angular genericos y reusables, compartidos entre las librerias de @ngx-docs-markdown-kit.
Docs de ui
Índice Docs de ui
- Primeros pasos -- Cómo instalar @ngx-docs-markdown-kit/ui en un proyecto Angular existente.
- Instalación -- Cómo instalar @ngx-docs-markdown-kit/ui en un proyecto Angular existente.
- Uso -- Los componentes reales de @ngx-docs-markdown-kit/ui -- API completa y ejemplos.
- SearchableSelectComponent -- Select genérico con buscador, pensado para catálogos largos (decenas de items).
- Ecosistema -- Relación de @ngx-docs-markdown-kit/ui con el resto del kit -- qué la consume y por qué.
- Relación con el ecosistema -- Quién usa @ngx-docs-markdown-kit/ui y por qué está separada del resto del kit.
Primeros pasos de ui
Instalación de ui
@ngx-docs-markdown-kit/ui es una librería de componentes standalone de Angular -- sin NgModule,
se importa el componente directo donde lo necesites.
npm install @ngx-docs-markdown-kit/uiRequiere @angular/common y @angular/core como peer dependencies (^22.1.0) -- ya presentes en
cualquier proyecto Angular real, no se instalan aparte.
Uso
Cada componente se importa por su cuenta en el array imports de tu propio componente standalone:
import { Component } from '@angular/core';
import { SearchableSelectComponent } from '@ngx-docs-markdown-kit/ui';
@Component({
selector: 'app-mi-componente',
imports: [SearchableSelectComponent],
template: `<ndmk-searchable-select [items]="items" (valueChange)="onChange($event)" />`,
})
export class MiComponente {
// ...
}Ver Relación con el ecosistema para el detalle de por qué esta librería no depende de ninguna otra del kit.
Uso de ui
SearchableSelectComponent de ui
Select genérico con buscador (ndmk-searchable-select) -- pensado para catálogos largos (ej.
decenas de temas de código) donde una lista desplegable común se vuelve inmanejable. Mientras se
escribe, filtra por label y muestra un máximo de 10 resultados; un botón "Ver todo" quita ese
límite (el filtro de búsqueda, si hay uno escrito, sigue aplicando).
No es específico de ningún catálogo puntual -- cualquier lista {id, label}[] sirve, reusable en
cualquier parte de un proyecto Angular, no solo en un sitio generado con create-ngx-docs-site.
import { SearchableSelectComponent, type SearchableSelectItem } from '@ngx-docs-markdown-kit/ui';
const items: SearchableSelectItem[] = [
{ id: 'ts', label: 'TypeScript' },
{ id: 'js', label: 'JavaScript' },
{ id: 'py', label: 'Python' },
];<ndmk-searchable-select
[items]="items"
[value]="selectedId"
placeholder="Buscar lenguaje..."
(valueChange)="selectedId = $event"
/>API
| Input/Output | Tipo | Descripción |
| --- | --- | --- |
| items | readonly SearchableSelectItem[] (requerido) | El catálogo completo -- {id: string, label: string}. |
| value | string \| null (default null) | El id seleccionado actualmente. |
| placeholder | string (default 'Buscar...') | Texto del input de búsqueda. |
| valueChange | output<string> | Emite el id del item elegido. |
Cómo funciona por dentro
Componente standalone OnPush, estado 100% con signals: un query (lo que se escribe) y un
showAll (si se tocó "Ver todo"), encadenados en computed(): filteredItems (filtra items por
label, case-insensitive, contra query) → visibleItems (si showAll es false, corta a los
primeros MAX_RESULTS = 10) → hasMore (si quedó algo cortado, para saber si mostrar el botón).
Sin dependencias de Angular Material ni de ningún otro paquete del ecosistema -- CSS propio con
variables custom y fallback (var(--color-x, var(--ndmk-select-x))), para que el sitio anfitrión
pueda sobrescribir colores sin que el componente dependa de que un tema específico esté instalado.
Por qué existe como librería separada
Este componente vivió antes dentro de
@ngx-docs-markdown-kit/parser-md-code-block, pero
no tiene nada que ver con parsear Markdown ni resaltar código -- es un select genérico. Se movió a
esta librería aparte para que instalar
@ngx-docs-markdown-kit/parser-md-code-block-themes
(que lo usa para el selector de "Mod" por lenguaje) no arrastre highlight.js ni el resto de la
infraestructura de resaltado de sintaxis solo para mostrar un select con buscador.
Alcance conocido
No incluye navegación por teclado (flechas/Home/End) -- alcance mínimo a propósito, el tab order nativo del input/botones ya cubre el caso de accesibilidad básico. El límite de 10 resultados + "Ver todo" es una decisión de simplicidad para catálogos de decenas de items (el caso real de uso, temas de código) -- no está pensado para listas de miles de entradas.
Ecosistema de ui
Relación con el ecosistema de ui
@ngx-docs-markdown-kit/ui es, a propósito, la única librería del kit sin ninguna dependencia
de @ngx-docs-markdown-kit/parser-md ni de su mecanismo de
extensión (.use()). No parsea Markdown, no reconoce ningún fence -- es una librería de
componentes de Angular genéricos, pensada para usarse en cualquier proyecto, no solo en un sitio de
documentación generado con create-ngx-docs-site.
Quién la usa hoy
@ngx-docs-markdown-kit/parser-md-code-block-themesla importa como dependencia real (SearchableSelectComponent/SearchableSelectItem) para el selector de tema de código por lenguaje.create-ngx-docs-site(el CLI) la trae siempre en la plantilla de cualquier sitio nuevo, y suAppShell/DocsShellla usan directo para ese mismo selector de "Mod".
Ninguna otra librería del ecosistema (parser-md-seo, parser-md-code-block, parser-md-image,
parser-md-card, parser-md-converter) depende de ui hoy.
Por qué no vive dentro de create-ngx-docs-site
Porque parser-md-code-block-themes la necesita como dependencia de librería, instalable por
cualquiera que use ese paquete de forma independiente -- no solo por un sitio ya generado por el
CLI. Si viviera dentro de la plantilla del CLI, cualquier otro consumidor de
parser-md-code-block-themes (fuera de este ecosistema de sitios) no tendría forma de instalarla.
Por qué es chica hoy
Nació de una extracción puntual (mover SearchableSelectComponent fuera de
parser-md-code-block, ver Uso para el detalle completo) -- no de
un diseño de "kit de UI" pensado desde el inicio con muchos componentes. Hoy exporta exactamente
uno. Es el lugar natural donde agregar cualquier componente genérico futuro que varias librerías
del ecosistema necesiten compartir, sin acoplarlas entre sí.
UI de ui
ui reune componentes de Angular genericos y reusables -- sin logica de parseo de Markdown -- que
comparten las demas librerias de este ecosistema y las plantillas de create-ngx-docs-site. Hoy
vive un solo componente, SearchableSelectComponent, pero el paquete existe para crecer.
Por que un paquete aparte en vez de vivir en cada libreria
SearchableSelectComponent lo usa parser-md-code-block-themes directamente en su propio codigo
fuente (el selector de tema de su config UI) -- si viviera solo dentro de la plantilla del CLI
(archivos copiados, no un paquete), ninguna libreria publicada por separado podria depender de el.
Sacarlo a su propio paquete evita que cada libreria reimplemente el mismo widget generico.
Que trae de base
SearchableSelectComponent: un <select> con busqueda, pensado para listas largas (ej. las ~80
paletas de parser-md-code-block-themes) donde un <select> nativo se vuelve incomodo de navegar.