custom-elements-ts 0.1.0 → 0.2.0

package/tests/map-shallow-state.spec.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { CustomElement, State, TemplateResult, html, map } from 'custom-elements-ts';
+
+const nextMicrotask = () => Promise.resolve();
+
+interface Item {
+  id: number;
+  label: string;
+}
+
+const rowSpy = vi.fn();
+
+@CustomElement({
+  tag: 'mapped-list-element',
+  shadow: false,
+})
+class MappedListElement extends HTMLElement {
+  @State({ deep: false }) items: Item[] = [];
+
+  render(): TemplateResult {
+    return html`<ul>
+      ${map(this.items, (item) => {
+        rowSpy(item.id);
+        return html`<li data-id=${item.id}>${item.label}</li>`;
+      })}
+    </ul>`;
+  }
+}
+
+describe('map() identity-based list rendering', () => {
+  afterEach(() => {
+    document.body.innerHTML = '';
+    rowSpy.mockClear();
+  });
+
+  const mount = async (): Promise<MappedListElement> => {
+    const el = document.createElement('mapped-list-element') as MappedListElement;
+    document.body.appendChild(el);
+    await nextMicrotask();
+    return el;
+  };
+
+  it('renders mapped items and skips rows whose item is identical on rerender', async () => {
+    const el = await mount();
+    const a = { id: 1, label: 'one' };
+    const b = { id: 2, label: 'two' };
+    el.items = [a, b];
+    await nextMicrotask();
+
+    const listItems = el.querySelectorAll('li');
+    expect(listItems.length).toBe(2);
+    expect(listItems[1].textContent).toBe('two');
+    expect(rowSpy).toHaveBeenCalledTimes(2);
+
+    // Replace only the second item; the first row must be skipped entirely.
+    rowSpy.mockClear();
+    el.items = [a, { id: 2, label: 'TWO' }];
+    await nextMicrotask();
+
+    expect(rowSpy).toHaveBeenCalledTimes(1);
+    expect(rowSpy).toHaveBeenCalledWith(2);
+    expect(el.querySelectorAll('li')[1].textContent).toBe('TWO');
+    expect(el.querySelectorAll('li')[0].textContent).toBe('one');
+  });
+
+  it('detaches only the removed row on a contiguous middle removal', async () => {
+    const el = await mount();
+    const items = [
+      { id: 1, label: 'one' },
+      { id: 2, label: 'two' },
+      { id: 3, label: 'three' },
+      { id: 4, label: 'four' },
+    ];
+    el.items = items;
+    await nextMicrotask();
+    const before = Array.from(el.querySelectorAll('li'));
+    expect(before.length).toBe(4);
+
+    // Remove the second item: the surviving rows must keep their exact DOM
+    // nodes and the row function must not run at all.
+    rowSpy.mockClear();
+    el.items = [items[0], items[2], items[3]];
+    await nextMicrotask();
+
+    const after = Array.from(el.querySelectorAll('li'));
+    expect(after.length).toBe(3);
+    expect(rowSpy).not.toHaveBeenCalled();
+    expect(after[0]).toBe(before[0]);
+    expect(after[1]).toBe(before[2]);
+    expect(after[2]).toBe(before[3]);
+    expect(after.map((li) => li.textContent)).toEqual(['one', 'three', 'four']);
+
+    // A later unrelated update still works with the spliced bookkeeping.
+    el.items = [items[0], { id: 9, label: 'nine' }, items[3]];
+    await nextMicrotask();
+    expect(Array.from(el.querySelectorAll('li')).map((li) => li.textContent)).toEqual([
+      'one',
+      'nine',
+      'four',
+    ]);
+  });
+
+  it('grows, shrinks, and fast-clears mapped lists', async () => {
+    const el = await mount();
+    const items = [
+      { id: 1, label: 'one' },
+      { id: 2, label: 'two' },
+      { id: 3, label: 'three' },
+    ];
+    el.items = items;
+    await nextMicrotask();
+    expect(el.querySelectorAll('li').length).toBe(3);
+
+    // Shrink: first item kept by identity, rest removed.
+    rowSpy.mockClear();
+    el.items = [items[0]];
+    await nextMicrotask();
+    expect(el.querySelectorAll('li').length).toBe(1);
+    expect(rowSpy).not.toHaveBeenCalled();
+
+    // Grow again.
+    el.items = [items[0], { id: 9, label: 'nine' }];
+    await nextMicrotask();
+    const grown = el.querySelectorAll('li');
+    expect(grown.length).toBe(2);
+    expect(grown[1].textContent).toBe('nine');
+
+    // Clear to empty, then repopulate.
+    el.items = [];
+    await nextMicrotask();
+    expect(el.querySelectorAll('li').length).toBe(0);
+
+    el.items = [{ id: 5, label: 'five' }];
+    await nextMicrotask();
+    expect(el.querySelectorAll('li').length).toBe(1);
+    expect(el.querySelector('li')!.textContent).toBe('five');
+  });
+});
+
+@CustomElement({
+  tag: 'shallow-state-element',
+  shadow: false,
+})
+class ShallowStateElement extends HTMLElement {
+  @State({ deep: false }) data: Item[] = [];
+  renderCount = 0;
+
+  render(): TemplateResult {
+    this.renderCount++;
+    return html`<p>${this.data.length ? this.data[0].label : 'empty'}</p>`;
+  }
+}
+
+describe('@State({ deep: false })', () => {
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('does not proxy values and only rerenders on reassignment', async () => {
+    const el = document.createElement('shallow-state-element') as ShallowStateElement;
+    document.body.appendChild(el);
+    await nextMicrotask();
+
+    const raw = [{ id: 1, label: 'one' }];
+    el.data = raw;
+    await nextMicrotask();
+    // Shallow state stores the value as-is (no proxy wrapper).
+    expect(el.data).toBe(raw);
+    expect(el.querySelector('p')!.textContent).toBe('one');
+    const renders = el.renderCount;
+
+    // Nested mutation must not schedule a render.
+    el.data[0].label = 'mutated';
+    await nextMicrotask();
+    expect(el.renderCount).toBe(renders);
+    expect(el.querySelector('p')!.textContent).toBe('one');
+
+    // Reassignment rerenders.
+    el.data = el.data.slice();
+    await nextMicrotask();
+    expect(el.renderCount).toBe(renders + 1);
+    expect(el.querySelector('p')!.textContent).toBe('mutated');
+  });
+});

package/tests/signal.spec.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { CustomElement, Signal, State, TemplateResult, html, signal } from 'custom-elements-ts';
+
+const nextMicrotask = () => Promise.resolve();
+
+interface Row {
+  id: number;
+  label: Signal<string>;
+  selected: Signal<string | null>;
+}
+
+@CustomElement({
+  tag: 'signal-row-element',
+  shadow: false,
+})
+class SignalRowElement extends HTMLElement {
+  @State({ deep: false }) rows: Row[] = [];
+  renderCount = 0;
+
+  render(): TemplateResult {
+    this.renderCount++;
+    return html`<ul>
+      ${this.rows.map(
+        (row) => html`<li class=${row.selected} .title=${row.label}>${row.label}</li>`
+      )}
+    </ul>`;
+  }
+}
+
+describe('signal bindings', () => {
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('updates text, attribute, and property directly without re-rendering', async () => {
+    const el = document.createElement('signal-row-element') as SignalRowElement;
+    document.body.appendChild(el);
+    await nextMicrotask();
+
+    const row: Row = { id: 1, label: signal('one'), selected: signal<string | null>(null) };
+    el.rows = [row];
+    await nextMicrotask();
+
+    const li = el.querySelector('li')!;
+    expect(li.textContent).toBe('one');
+    expect(li.hasAttribute('class')).toBe(false);
+    expect(li.title).toBe('one');
+    const renders = el.renderCount;
+
+    // Signal writes go straight to the DOM — no render pass.
+    row.label.value = 'uno';
+    row.selected.value = 'danger';
+    expect(el.renderCount).toBe(renders);
+    expect(li.textContent).toBe('uno');
+    expect(li.getAttribute('class')).toBe('danger');
+    expect(li.title).toBe('uno');
+
+    // Null removes the attribute again.
+    row.selected.value = null;
+    expect(li.hasAttribute('class')).toBe(false);
+  });
+
+  it('keeps bindings across re-renders with the same signal and rebinds on a new one', async () => {
+    const el = document.createElement('signal-row-element') as SignalRowElement;
+    document.body.appendChild(el);
+    await nextMicrotask();
+
+    const row: Row = { id: 1, label: signal('a'), selected: signal<string | null>(null) };
+    el.rows = [row];
+    await nextMicrotask();
+
+    // Re-render with the same signal instances: binding must survive.
+    el.rows = [row];
+    await nextMicrotask();
+    row.label.value = 'b';
+    expect(el.querySelector('li')!.textContent).toBe('b');
+
+    // Re-render with a different signal: old one must be detached.
+    const oldLabel = row.label;
+    const replacement: Row = { id: 1, label: signal('fresh'), selected: row.selected };
+    el.rows = [replacement];
+    await nextMicrotask();
+    const li = el.querySelector('li')!;
+    expect(li.textContent).toBe('fresh');
+    oldLabel.value = 'stale write';
+    expect(li.textContent).toBe('fresh');
+    replacement.label.value = 'newer';
+    expect(li.textContent).toBe('newer');
+  });
+
+  it('unsubscribes disposed parts and skips notifications with equal values', async () => {
+    const el = document.createElement('signal-row-element') as SignalRowElement;
+    document.body.appendChild(el);
+    await nextMicrotask();
+
+    const label = signal('x');
+    const row: Row = { id: 1, label, selected: signal<string | null>(null) };
+    el.rows = [row];
+    await nextMicrotask();
+    expect(el.querySelector('li')).not.toBeNull();
+
+    let calls = 0;
+    label.subscribe(() => calls++);
+    label.value = 'x'; // equal value: no notification
+    expect(calls).toBe(0);
+    label.value = 'y';
+    expect(calls).toBe(1);
+
+    // Clearing the list disposes parts; writes afterwards must not throw.
+    el.rows = [];
+    await nextMicrotask();
+    expect(el.querySelector('li')).toBeNull();
+    expect(() => {
+      label.value = 'z';
+    }).not.toThrow();
+  });
+});

package/tools/build.js

@@ -7,16 +7,17 @@ const rimraf = require('rimraf');
 const { copyFile } = require('fs').promises;
 const glob = require('glob');
 const { readFileSync, writeFileSync } = require('fs');
+const { generateSources } = require('./generate-sources');
 
 const DEST_PATH = 'dist';
-// Inline every demo source so a demo (like `site`) can freely import sibling
-// demos and have their templateUrl/styleUrl references resolved.
+// Inline demo sources so sibling demo imports resolve.
 const SRC_PATH = `demos/**/*.ts`;
 const SRC_TMP_PATH = `.tmp`;
 
 const STATIC_ASSET_EXTS = new Set([
   '.css', '.svg', '.png', '.jpg', '.jpeg', '.gif',
-  '.ico', '.webp', '.woff', '.woff2', '.ttf', '.otf'
+  '.ico', '.webp', '.woff', '.woff2', '.ttf', '.otf',
+  '.txt'
 ]);
 
 function copyStaticAssets(srcDir, destDir) {
@@ -36,7 +37,14 @@ function copyDemoShell() {
   if (!existsSync(DEST_PATH)) mkdirSync(DEST_PATH, { recursive: true });
   const indexSrc = `demos/${ELEMENT_NAME}/index.html`;
   if (existsSync(indexSrc)) {
-    copyFileSync(indexSrc, path.join(DEST_PATH, 'index.html'));
+    const pkg = JSON.parse(readFileSync('package.json', 'utf-8'));
+    let html = readFileSync(indexSrc, 'utf-8');
+    // Keep the landing page's version badge in sync with package.json.
+    html = html.replace(
+      /<span class="badge">v[^<]*<\/span>/,
+      `<span class="badge">v${pkg.version}</span>`
+    );
+    writeFileSync(path.join(DEST_PATH, 'index.html'), html);
   }
   copyStaticAssets(`demos/${ELEMENT_NAME}`, DEST_PATH);
 }
@@ -111,9 +119,10 @@ async function rollupGenerate(config) {
 
 Promise.all([clean(DEST_PATH), clean(SRC_TMP_PATH)])
   .then(() => inlineSources(SRC_PATH, SRC_TMP_PATH))
+  .then(() => generateSources(SRC_TMP_PATH))
   .then(() => rollupGenerate(config))
   .then(() => copyDemoShell())
   .catch(err => {
     console.error('Build failed:', err);
     process.exit(1);
-  });
+  });

package/tools/generate-sources.js

@@ -0,0 +1,76 @@
+/**
+ * Builds the source map consumed by <cts-source-viewer>.
+ */
+const path = require('path');
+const { readFileSync, writeFileSync, existsSync, mkdirSync } = require('fs');
+
+// First file is the default tab.
+const ENTRIES = [
+  {
+    slug: 'counter',
+    folder: 'demos/counter',
+    files: ['counter.element.ts'],
+  },
+  {
+    slug: 'todo-dashboard',
+    folder: 'demos/todo-dashboard',
+    files: [
+      'todo-dashboard.element.ts',
+      'todo-stats.element.ts',
+      'todo-filters.element.ts',
+      'todo-item.element.ts',
+    ],
+  },
+];
+
+const OUTPUT_REL = path.join('site', 'source-viewer', 'sources.generated.ts');
+
+function buildSourcesMap() {
+  const map = {};
+  for (const entry of ENTRIES) {
+    map[entry.slug] = entry.files
+      .map((name) => {
+        const fullPath = path.join(entry.folder, name);
+        if (!existsSync(fullPath)) {
+          console.warn(`generate-sources: missing ${fullPath}; skipping.`);
+          return null;
+        }
+        return { name, source: readFileSync(fullPath, 'utf-8') };
+      })
+      .filter(Boolean);
+  }
+  return map;
+}
+
+function renderModule(map) {
+  // JSON can be embedded directly as a TS object literal.
+  const body = JSON.stringify(map, null, 2);
+  return [
+    '// AUTO-GENERATED by tools/generate-sources.js — do not edit by hand.',
+    '// Regenerated on every build/start so the live viewer always shows',
+    '// the source that ships with the bundle.',
+    '',
+    'export interface SourceFile {',
+    '  name: string;',
+    '  source: string;',
+    '}',
+    '',
+    `export const SOURCES: Record<string, SourceFile[]> = ${body};`,
+    '',
+  ].join('\n');
+}
+
+/**
+ * @param {string} destRoot Usually `.tmp`.
+ */
+function generateSources(destRoot) {
+  const map = buildSourcesMap();
+  const outPath = path.join(destRoot, OUTPUT_REL);
+  const outDir = path.dirname(outPath);
+  if (!existsSync(outDir)) {
+    mkdirSync(outDir, { recursive: true });
+  }
+  writeFileSync(outPath, renderModule(map));
+}
+
+module.exports = { generateSources, ENTRIES };

package/tools/rollup-config.js

@@ -13,7 +13,7 @@ const prodModeParams = ['--prod', '--prod=true', '--prod true'];
 const ELEMENT_PATH = `${ELEMENT_NAME}/index.ts`;
 const INPUT_PATH = path.join('.tmp', ELEMENT_PATH);
 
-if (ELEMENT_NAME == undefined) {
+if (ELEMENT_NAME === undefined) {
   console.log('specify which element to start');
   console.log(' ↳  eg. npm start element-name');
   process.exit();
@@ -67,4 +67,4 @@ if (isProcess(prodModeParams)) {
 }
 
 exports.config = config;
-exports.ELEMENT_NAME = ELEMENT_NAME;
+exports.ELEMENT_NAME = ELEMENT_NAME;

package/tools/start.js

@@ -6,16 +6,19 @@ const rollup = require('rollup');
 const rimraf = require('rimraf');
 const glob = require('glob');
 const { config, ELEMENT_NAME } = require('./rollup-config');
+const { generateSources } = require('./generate-sources');
 
 const STATIC_ASSET_EXTS = new Set([
   '.css', '.svg', '.png', '.jpg', '.jpeg', '.gif',
-  '.ico', '.webp', '.woff', '.woff2', '.ttf', '.otf'
+  '.ico', '.webp', '.woff', '.woff2', '.ttf', '.otf',
+  '.txt'
 ]);
 
+const INLINE_SOURCE_EXTS = new Set(['.ts', '.scss']);
+
 const DEST_PATH = 'dist';
-// Inline every demo source so a demo (like `site`) can freely import sibling
-// demos and have their templateUrl/styleUrl references resolved.
-const SRC_PATH = `demos/**/*.ts`;
+// Inline demo sources so sibling demo imports resolve.
+const SRC_PATH = `demos/**/*.ts`;
 const SRC_TMP_PATH = `.tmp`;
 
 // Simple dev server
@@ -151,9 +154,10 @@ const copy = () => {
 const fileWatcher = () => {
   // Watch src and demos directories
   watch('src', { recursive: true }, async (eventType, filename) => {
-    if (filename && filename.endsWith('.ts')) {
+    if (filename && INLINE_SOURCE_EXTS.has(path.extname(filename).toLowerCase())) {
       console.log(`File changed: ${filename}`);
       await inlineSources(SRC_PATH, SRC_TMP_PATH);
+      await generateSources(SRC_TMP_PATH);
       await rollupGenerate(config);
     }
   });
@@ -161,9 +165,10 @@ const fileWatcher = () => {
   watch('demos', { recursive: true }, async (eventType, filename) => {
     if (!filename) return;
     const ext = path.extname(filename).toLowerCase();
-    if (ext === '.ts') {
+    if (INLINE_SOURCE_EXTS.has(ext)) {
       console.log(`File changed: ${filename}`);
       await inlineSources(SRC_PATH, SRC_TMP_PATH);
+      await generateSources(SRC_TMP_PATH);
       await rollupGenerate(config);
     } else if (ext === '.html') {
       console.log(`HTML changed: ${filename}`);
@@ -177,6 +182,7 @@ const fileWatcher = () => {
 
 Promise.all([clean(DEST_PATH), clean(SRC_TMP_PATH)])
   .then(() => Promise.all([inlineSources(SRC_PATH, SRC_TMP_PATH), copy()]))
+  .then(() => generateSources(SRC_TMP_PATH))
   .then(() => {
     rollupGenerate(config);
     DevServer.start();
@@ -185,4 +191,4 @@ Promise.all([clean(DEST_PATH), clean(SRC_TMP_PATH)])
   .catch(err => {
     console.error('Start failed:', err);
     process.exit(1);
-  });
+  });