@ac-base/ac-demo-content 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Renzo Cordova
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,89 @@
1
- # Temporary Holding Version
1
+ # @ac-base/ac-demo-content
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Contenedor centralizado para las demos de los componentes de `ac-lit`. En vez de que cada componente reimplemente su propio selector de caso/idioma/tema/tamaño/panel de eventos a mano (como hicieron `ac-button-basic`, `ac-link-basic`, etc.), todas las demos usan este contenedor — así, cuando la demo evoluciona, se cambia en un solo lugar.
4
+
5
+ ## Uso
6
+
7
+ ```html
8
+ <ac-demo-content
9
+ name="ac-mi-componente"
10
+ tech="Lit v3"
11
+ package-name="@ac-components/ac-mi-componente"
12
+ docs-href="https://github.com/RenzoCordovaDev/ac-lit/blob/main/packages/components/ac-mi-componente/README.md"
13
+ language="es-PE, en-EN"
14
+ ambients="primary, primary-alt, secondary, secondary-alt"
15
+ events="ac-mi-componente-click"
16
+ dark-mode
17
+ >
18
+ <ac-demo-case header="Básico" descripcion="Uso por defecto" href="case-basic.html"></ac-demo-case>
19
+ <ac-demo-case
20
+ header="Estados"
21
+ descripcion="Disabled/loading"
22
+ href="case-states.html"
23
+ ></ac-demo-case>
24
+ </ac-demo-content>
25
+ ```
26
+
27
+ ```js
28
+ import '@ac-base/ac-demo-content';
29
+ ```
30
+
31
+ > **Los archivos `href` de cada `ac-demo-case` deben vivir en `demo/public/`**, no directo en `demo/` — Vite solo copia `public/` tal cual al build (`vite build`); cualquier otro archivo que no esté referenciado desde `index.html` se queda afuera de `dist/` y el `fetch()` en producción (`vite preview`) da 404.
32
+
33
+ ## `<ac-demo-content>`
34
+
35
+ | Atributo | Tipo | Descripción |
36
+ | -------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
37
+ | `name` | string | Nombre del componente, mostrado como título (sin `<>`) — reemplaza el `<h1>` manual que antes vivía en `demo/index.html`. |
38
+ | `tech` | string | Tecnología base, mostrada como badge junto al nombre (ej. `"Lit v3"`). |
39
+ | `package-name` | string | Nombre del paquete npm — muestra los snippets `pnpm add`/`npm i`; al hacer click en cualquiera, se copia al portapapeles. |
40
+ | `docs-href` | string (URL) | Link "Documentación" — debe ser una URL completa (ej. al `README.md` del componente en GitHub), no una ruta local: el dev server de Vite no sirve archivos fuera de `demo/`. |
41
+ | `language` | string, coma-separado | **Exactamente 2 locales** (ej. `"es-PE, en-EN"`) — el framework solo ofrece español o inglés. Se renderiza como control segmentado ES/EN (no un select, no un switch deslizante). Con 0, 1 o 3+ valores no se renderiza nada. Usa `setGlobalLocale` — cero wiring extra. |
42
+ | `ambients` | string, coma-separado | Valores de `ambient` a ofrecer. Al cambiar, setea `.ambient` en los elementos del caso activo que tengan esa propiedad. |
43
+ | `events` | string, coma-separado | Nombres de eventos a escuchar en `document`. Si hay al menos uno, se muestra un ícono de campana con contador — al hacer click abre un **panel lateral** (pegado al borde derecho) con la configuración (qué eventos escucha) y cada evento disparado, con sus campos etiquetados (`Evento:`, `Hora:`, `Payload:`). |
44
+ | `dark-mode` | boolean | Muestra el switch de tema (2 iconos: sol/luna, dentro de un control segmentado). El demo arranca en **modo claro** por defecto; togglea `data-theme` en `<html>` — requiere que el host importe la paleta `light` de `@ac-base/ac-core` además de la oscura. |
45
+
46
+ Siempre presentes, sin atributo que los active:
47
+
48
+ - **Switcher de caso** — `<select>` con estilo moderno (en Chromium también se estiliza la lista desplegable vía `appearance: base-select`; en otros navegadores queda el `<select>` nativo), muestra solo el `header` de cada `<ac-demo-case>`. Va **solo en la primera fila** del toolbar, a todo el ancho, porque los `header` pueden ser largos (hacen wrap, no se truncan); el resto de controles van en una segunda fila. Se muestra incluso con un solo caso.
49
+ - **Switcher de tamaño de dispositivo** — 3 presets fijos con ancho **y alto** fijos: Móvil (375×667, por defecto), Tablet (768×1024) y Desktop (1280×800). Cada uno envuelve el `<slot>` en un marco visual (`.ac-demo-content__device-frame`) que simula el bisel del dispositivo. El alto es fijo a propósito — si el contenido no entra, **scrollea adentro del viewport simulado** en vez de estirar el marco, para que la demo se vea como el dispositivo real se vería. El marco usa `max-width`: para que Desktop alcance sus 1280 px, el contenedor de la página (`.demo-root` en `demo/demo-base.css`, `max-width: 1440px`) tiene que ser lo bastante ancho; en pantallas más angostas el marco se encoge.
50
+ - **Switch Visual/Código** — "Visual" (por defecto) renderiza el caso activo de verdad, dentro del marco de dispositivo. "Código" muestra el HTML fuente de ese caso (`ac-demo-case.source`, el contenido crudo de su `href`) con aspecto de **editor de código**: barra de título con el nombre del archivo, líneas numeradas y resaltado de sintaxis HTML, sin marco de dispositivo. La paleta del editor es fija (oscura en ambos temas).
51
+ - **Snippets de instalación copiables** — con `package-name`, cada comando (`pnpm add …`, `npm i …`) es un botón: al hacer click se copia al portapapeles, el botón muestra un check unos instantes y se anuncia "Copiado al portapapeles" a lectores de pantalla.
52
+
53
+ ## Eventos
54
+
55
+ | Evento | Cuándo | `detail` |
56
+ | ---------------------- | ------------------------------------------ | ------------------ |
57
+ | `ac-demo-content-copy` | El usuario copió un comando de instalación | `{ text: string }` |
58
+
59
+ Es `bubbles` y `composed`. Solo se dispara si el copiado tuvo éxito.
60
+
61
+ Todos los controles de 2+ opciones (idioma, tema, tamaño de dispositivo, vista) comparten el mismo patrón visual: un contenedor con borde redondeado, opciones separadas por un divisor vertical, y la opción activa resaltada — nunca un switch deslizante ni texto plano de estado ("Modo claro"/"Modo oscuro").
62
+
63
+ ## `<ac-demo-case>`
64
+
65
+ | Atributo | Descripción |
66
+ | ------------- | ---------------------------------------------------------------------------------------------------------------- |
67
+ | `header` | Texto mostrado en el switcher de casos. |
68
+ | `descripcion` | Descripción corta del caso (no se renderiza todavía — reservado para un tooltip/subtítulo futuro). |
69
+ | `href` | Ruta al archivo HTML con el contenido del caso. Se carga (fetch) la primera vez que el caso se activa, no antes. |
70
+
71
+ Deliberadamente **no usa Shadow DOM**: el HTML de `href` participa del CSS global de la página (clases como `.row` de `demo-base.css`), y evita tener que atravesar dos shadow roots anidados para que `ac-demo-content` pueda manipular los componentes reales de adentro (ej. cambiar su `ambient`). El contenido de `href` se asume de confianza — lo escribe quien desarrolla el componente, igual que el propio `demo/index.html` — no se sanitiza.
72
+
73
+ `.source` expone el HTML crudo ya cargado (string) — lo usa el switch Visual/Código de `ac-demo-content` para mostrar el HTML fuente del caso activo.
74
+
75
+ ## `ambient`: requiere que el componente lo use de verdad
76
+
77
+ `ambients` solo tiene efecto visual si el componente dentro del caso activo **usa realmente** la propiedad `ambient` (heredada de `@ac-base/ac-component-mixin`) en su styling — no basta con que la tenga disponible sin usarla. Ver `docs/CONVENTIONS.md`.
78
+
79
+ ## Desarrollo
80
+
81
+ ```bash
82
+ pnpm --filter @ac-base/ac-demo-content component:serve # demo en http://localhost:5173 (usa un botón de prueba propio, ver demo/sample-button.js)
83
+ pnpm --filter @ac-base/ac-demo-content component:test
84
+ pnpm --filter @ac-base/ac-demo-content component:build
85
+ pnpm --filter @ac-base/ac-demo-content component:test:e2e
86
+ pnpm --filter @ac-base/ac-demo-content component:test:e2e:a11y
87
+ ```
88
+
89
+ > `src/demo-content.styles.js` se genera a partir de `src/demo-content.styles.scss` (`component:build:styles`, corre automáticamente antes de `component:serve`/`component:build`/`component:test`) y no se versiona en git. Durante `component:serve` queda además en modo watch: cada guardado de `.scss` lo recompila y Vite recarga el navegador solo, sin reiniciar nada.
package/index.js ADDED
@@ -0,0 +1,8 @@
1
+ import { DemoContent } from './src/demo-content.js';
2
+ import { DemoCase } from './src/demo-case.js';
3
+
4
+ export { DemoContent } from './src/demo-content.js';
5
+ export { DemoCase } from './src/demo-case.js';
6
+
7
+ customElements.define(DemoContent.is, DemoContent);
8
+ customElements.define(DemoCase.is, DemoCase);
package/package.json CHANGED
@@ -1,6 +1,49 @@
1
1
  {
2
2
  "name": "@ac-base/ac-demo-content",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.1",
4
+ "description": "Contenedor centralizado para demos de componentes ac-lit (casos, idioma, ambient, modo oscuro, tamaños, panel de eventos)",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "main": "index.js",
8
+ "exports": {
9
+ ".": "./index.js"
10
+ },
11
+ "files": [
12
+ "/src/",
13
+ "index.js"
14
+ ],
15
+ "publishConfig": {
16
+ "access": "public"
17
+ },
18
+ "dependencies": {
19
+ "@ac-base/ac-component-mixin": "^0.1.0",
20
+ "@ac-base/ac-intl-mixin": "^0.1.0"
21
+ },
22
+ "peerDependencies": {
23
+ "lit": "^3.0.0"
24
+ },
25
+ "devDependencies": {
26
+ "@ac-base/ac-core": "^0.1.0",
27
+ "@ac-base/ac-e2e-testing": "^0.1.0",
28
+ "@ac-base/cli": "^0.2.0",
29
+ "@open-wc/testing": "^4.0.0",
30
+ "@web/test-runner": "^0.18.0",
31
+ "concurrently": "^9.1.0",
32
+ "lit": "^3.0.0",
33
+ "sass": "^1.79.4",
34
+ "vite": "^5.4.8"
35
+ },
36
+ "scripts": {
37
+ "component:lint": "eslint .",
38
+ "component:build:styles": "node ./node_modules/@ac-base/cli/scripts/compile-scss-to-lit.cjs src/demo-content.styles.scss src/demo-content.styles.js DemoContentStyles",
39
+ "component:build:styles:watch": "node ./node_modules/@ac-base/cli/scripts/compile-scss-to-lit.cjs src/demo-content.styles.scss src/demo-content.styles.js DemoContentStyles --watch",
40
+ "component:serve": "pnpm run component:build:styles && concurrently -k -n styles,vite -c blue,green \"pnpm run component:build:styles:watch\" \"vite demo\"",
41
+ "component:build": "pnpm run component:build:styles && vite build",
42
+ "component:preview": "vite preview",
43
+ "component:test": "pnpm run component:build:styles && web-test-runner \"test/**/*.test.js\"",
44
+ "component:test:e2e": "pnpm run component:build && start-server-and-test component:preview http://localhost:4173 component:test:e2e:run",
45
+ "component:test:e2e:run": "wdio run test_e2e/wdio.conf.js",
46
+ "component:test:e2e:a11y": "pnpm run component:build && start-server-and-test component:preview http://localhost:4173 component:test:e2e:a11y:run",
47
+ "component:test:e2e:a11y:run": "wdio run test_e2e/wdio.a11y.conf.js"
48
+ }
6
49
  }
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Copia `text` al portapapeles. Usa la Clipboard API y, si no está disponible
3
+ * (contexto no seguro, ej. http://<ip-de-la-red>) o rechaza el permiso, cae a
4
+ * un `<textarea>` temporal con `execCommand('copy')`. Devuelve si se pudo copiar.
5
+ */
6
+ export async function copyToClipboard(text) {
7
+ try {
8
+ await navigator.clipboard.writeText(text);
9
+ return true;
10
+ } catch {
11
+ return copyWithTextarea(text);
12
+ }
13
+ }
14
+
15
+ function copyWithTextarea(text) {
16
+ const textarea = document.createElement('textarea');
17
+ textarea.value = text;
18
+ textarea.setAttribute('readonly', '');
19
+ textarea.style.position = 'fixed';
20
+ textarea.style.opacity = '0';
21
+ document.body.appendChild(textarea);
22
+ textarea.select();
23
+
24
+ try {
25
+ return document.execCommand('copy');
26
+ } catch {
27
+ return false;
28
+ } finally {
29
+ textarea.remove();
30
+ }
31
+ }
@@ -0,0 +1,84 @@
1
+ /**
2
+ * ac-demo-case: contenedor de un caso de demo cargado desde un archivo HTML
3
+ * externo (`href`). Deliberadamente NO usa Shadow DOM ni Lit: el HTML que
4
+ * carga está pensado para comportarse como si fuera parte directa de la
5
+ * página (participa del CSS global del demo, ej. `.row`/`.controls` de
6
+ * demo-base.css), y evita el problema de tener que atravesar dos shadow
7
+ * roots anidados (ac-demo-content -> ac-demo-case -> los componentes reales)
8
+ * para que ac-demo-content pueda controlarlos (ej. cambiar su `ambient`).
9
+ *
10
+ * El contenido de `href` se asume de confianza — lo escribe quien desarrolla
11
+ * el componente, igual que el propio demo/index.html. No se sanitiza.
12
+ */
13
+ export class DemoCase extends HTMLElement {
14
+ static get is() {
15
+ return 'ac-demo-case';
16
+ }
17
+
18
+ static get observedAttributes() {
19
+ return ['active'];
20
+ }
21
+
22
+ constructor() {
23
+ super();
24
+ this._loaded = false;
25
+ this._source = '';
26
+ }
27
+
28
+ /** HTML crudo cargado desde `href` — usado por el toggle Visual/Código. */
29
+ get source() {
30
+ return this._source;
31
+ }
32
+
33
+ get header() {
34
+ return this.getAttribute('header') ?? '';
35
+ }
36
+
37
+ get descripcion() {
38
+ return this.getAttribute('descripcion') ?? '';
39
+ }
40
+
41
+ get href() {
42
+ return this.getAttribute('href') ?? '';
43
+ }
44
+
45
+ get active() {
46
+ return this.hasAttribute('active');
47
+ }
48
+
49
+ set active(value) {
50
+ this.toggleAttribute('active', Boolean(value));
51
+ }
52
+
53
+ connectedCallback() {
54
+ this.hidden = !this.active;
55
+ }
56
+
57
+ attributeChangedCallback(name, _oldValue, newValue) {
58
+ if (name !== 'active') return;
59
+
60
+ const isActive = newValue !== null;
61
+ this.hidden = !isActive;
62
+
63
+ if (isActive && !this._loaded) {
64
+ this._loadContent();
65
+ }
66
+ }
67
+
68
+ async _loadContent() {
69
+ this._loaded = true;
70
+ try {
71
+ const response = await fetch(this.href);
72
+ if (!response.ok) {
73
+ throw new Error(`HTTP ${response.status}`);
74
+ }
75
+ this._source = await response.text();
76
+ this.innerHTML = this._source;
77
+ } catch (error) {
78
+ this.textContent = `Error cargando "${this.href}": ${error.message}`;
79
+ }
80
+ // ac-demo-content escucha esto para aplicar `contained`/`getBoundary` a los
81
+ // componentes recién insertados (ver "Superposiciones" en CONVENTIONS.md).
82
+ this.dispatchEvent(new CustomEvent('ac-demo-case-load', { bubbles: true }));
83
+ }
84
+ }