custom-elements-ts 0.1.0 → 0.2.0

package/demos/site/source-viewer/source-viewer.element.ts

@@ -0,0 +1,138 @@
+import { CustomElement, Prop, State, TemplateResult, html } from 'custom-elements-ts';
+
+import { SOURCES, SourceFile } from './sources.generated';
+
+declare const Prism: {
+  highlight(code: string, grammar: unknown): string;
+  languages: {
+    typescript: unknown;
+    javascript: unknown;
+  };
+};
+
+/**
+ * Inline source viewer for site playgrounds.
+ */
+@CustomElement({
+  tag: 'cts-source-viewer',
+  styleUrl: './source-viewer.element.scss',
+})
+export class SourceViewerElement extends HTMLElement {
+  /** Key into the `SOURCES` map. e.g. `counter`, `todo-dashboard`. */
+  @Prop() slug = '';
+
+  /** Index of the file shown in the body. Reset whenever `slug` changes. */
+  @State() activeIndex = 0;
+
+  // Avoid re-tokenizing unchanged source.
+  private files: SourceFile[] = [];
+  private highlighted: string[] = [];
+  private cachedFor = '\0';
+
+  // Raw node insertion avoids lowercasing `.innerHTML` in parsed templates.
+  private bodyNode: HTMLPreElement | null = null;
+  private codeNode: HTMLElement | null = null;
+  private renderedHtml = '';
+
+  render(): TemplateResult {
+    if (this.cachedFor !== this.slug) {
+      this.recompute();
+      this.cachedFor = this.slug;
+    }
+
+    if (!this.files.length) {
+      return html`
+        <div class="viewer">
+          <p class="empty">Source unavailable for <code>${this.slug}</code>.</p>
+        </div>
+      `;
+    }
+
+    const showTabs = this.files.length > 1;
+    const active = this.highlighted[this.activeIndex] ?? '';
+
+    if (!this.bodyNode || !this.codeNode) {
+      this.codeNode = document.createElement('code');
+      this.bodyNode = document.createElement('pre');
+      this.bodyNode.className = 'body';
+      this.bodyNode.tabIndex = 0;
+      this.bodyNode.appendChild(this.codeNode);
+    }
+    if (this.renderedHtml !== active) {
+      this.codeNode.innerHTML = active;
+      this.renderedHtml = active;
+    }
+
+    return html`
+      <div class="viewer">
+        <div class="bar">
+          <span class="kicker">
+            <span class="kicker-dot" aria-hidden="true"></span>
+            inline source
+          </span>
+
+          ${showTabs
+            ? html`
+                <div class="tabs" role="tablist" aria-label="Source files">
+                  ${this.files.map((file, index) => {
+                    const isActive = index === this.activeIndex;
+                    return html`
+                      <button
+                        class=${isActive ? 'tab is-active' : 'tab'}
+                        role="tab"
+                        type="button"
+                        aria-selected=${isActive ? 'true' : 'false'}
+                        @click=${() => this.selectTab(index)}
+                      >
+                        ${file.name}
+                      </button>
+                    `;
+                  })}
+                </div>
+              `
+            : html`<span class="single">${this.files[0]?.name ?? ''}</span>`}
+        </div>
+
+        ${this.bodyNode}
+      </div>
+    `;
+  }
+
+  private selectTab(index: number) {
+    if (index === this.activeIndex) return;
+    this.activeIndex = index;
+    // Center the active tab when the bar is overflowing on narrow widths.
+    requestAnimationFrame(() => {
+      const tab = this.shadowRoot?.querySelectorAll<HTMLElement>('.tab')[index];
+      tab?.scrollIntoView({ inline: 'center', block: 'nearest', behavior: 'smooth' });
+    });
+  }
+
+  private recompute() {
+    const files = SOURCES[this.slug] ?? [];
+    this.files = files;
+
+    const grammar =
+      typeof Prism !== 'undefined'
+        ? (Prism.languages.typescript ?? Prism.languages.javascript)
+        : null;
+
+    this.highlighted = files.map((file) =>
+      grammar ? Prism.highlight(file.source, grammar) : escapeHtml(file.source)
+    );
+
+    if (this.activeIndex >= files.length) {
+      this.activeIndex = 0;
+    }
+  }
+}
+
+const ENTITY_MAP: Record<string, string> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+};
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>]/g, (char) => ENTITY_MAP[char] ?? char);
+}

package/demos/site/source-viewer/sources.generated.ts

@@ -0,0 +1,11 @@
+// Stub committed so the IDE / type checker has something to resolve.
+// The real, populated module is emitted by `tools/generate-sources.js`
+// into `.tmp/site/source-viewer/sources.generated.ts` at build/dev time
+// and is what the bundler actually picks up.
+
+export interface SourceFile {
+  name: string;
+  source: string;
+}
+
+export const SOURCES: Record<string, SourceFile[]> = {};

package/demos/site/styles/site.css

@@ -167,6 +167,7 @@ a:hover { color: var(--accent); }
   font-family: var(--font-mono);
   font-size: 14px;
   color: var(--fg);
+  white-space: nowrap;
 }
 .brand__name .dim { color: var(--fg-subtle); }
 
@@ -238,6 +239,7 @@ a:hover { color: var(--accent); }
   font-size: 12px;
   color: var(--fg-muted);
   font-variant-numeric: tabular-nums;
+  white-space: nowrap;
 }
 .hero__pill .badge {
   display: inline-flex;
@@ -410,21 +412,6 @@ a:hover { color: var(--accent); }
 }
 .window__title .accent { color: var(--accent-fg); }
 
-.window__copy {
-  margin-left: auto;
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-  padding: 4px 10px;
-  font-family: var(--font-mono);
-  font-size: 11px;
-  color: var(--fg-muted);
-  border: 1px solid var(--line);
-  border-radius: var(--radius-xs);
-  background: var(--bg-elev-2);
-}
-.window__copy svg { width: 12px; height: 12px; }
-
 .window__body {
   background: #0b0e14;
 }
@@ -576,6 +563,13 @@ a:hover { color: var(--accent); }
   color: var(--accent-fg);
 }
 
+/* Keep inline code chips like `npm install` or `@State()` atomic so
+   prose wraps around them instead of breaking them mid-token. */
+:where(.hero__lede, .live__lede, .side-card__sub, .playground__title,
+       .playground__sub, .stage__caption, .api__lede) code {
+  white-space: nowrap;
+}
+
 .playground {
   position: relative;
   margin-top: 22px;
@@ -646,7 +640,69 @@ a:hover { color: var(--accent); }
   font-size: 12px;
   color: var(--accent-fg);
 }
-.playground__source {
+/* Playground header actions. */
+.playground__actions {
+  flex: 0 0 auto;
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+}
+
+.playground__btn {
+  flex: 0 0 auto;
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 12px;
+  border: 1px solid var(--line-strong);
+  border-radius: var(--radius-xs);
+  background: rgba(255, 255, 255, 0.02);
+  font-family: var(--font-mono);
+  font-size: 12px;
+  color: var(--fg-muted);
+  white-space: nowrap;
+  cursor: pointer;
+  text-decoration: none;
+  transition: border-color var(--dur) var(--ease),
+              color var(--dur) var(--ease),
+              background var(--dur) var(--ease);
+}
+.playground__btn:hover {
+  color: var(--fg);
+  border-color: var(--line-accent);
+  background: var(--accent-soft);
+}
+.playground__btn:active {
+  transform: translateY(1px);
+}
+.playground__btn[aria-expanded="true"],
+.playground__btn.is-active {
+  color: var(--accent-fg);
+  border-color: var(--line-accent);
+  background: var(--accent-soft);
+}
+
+.playground__btn-caret {
+  margin-left: 2px;
+  opacity: 0.6;
+  transition: transform var(--dur) var(--ease), opacity var(--dur) var(--ease);
+}
+.playground__btn[aria-expanded="true"] .playground__btn-caret {
+  transform: rotate(180deg);
+  opacity: 0.9;
+}
+
+.playground__btn--ghost {
+  background: transparent;
+}
+.playground__btn--ghost:hover {
+  background: var(--bg-elev-2);
+}
+
+/* Backwards compatibility for the original source link class. */
+.playground__source {
   flex: 0 0 auto;
   display: inline-flex;
   align-items: center;
@@ -686,9 +742,19 @@ a:hover { color: var(--accent); }
   }
 }
 
-/* Todo playground: dashboard on top, full-width log below.
-   The dashboard sets its own max width; we just center it. */
-.playground__body--stack {
+/* Todo needs a wider breakpoint than the counter card. */
+.playground--todo .playground__body--split {
+  grid-template-columns: 1fr;
+}
+@media (min-width: 1024px) {
+  .playground--todo .playground__body--split {
+    grid-template-columns: minmax(0, 1fr) minmax(280px, 360px);
+    align-items: stretch;
+  }
+}
+
+/* Legacy stack variant for external embeds. */
+.playground__body--stack {
   grid-template-columns: 1fr;
 }
 
@@ -722,6 +788,11 @@ a:hover { color: var(--accent); }
 .stage--todo {
   padding: 32px 18px;
 }
+/* Prevent host min-content overflow on narrow phones. */
+.stage--todo cts-todo-dashboard {
+  width: min(540px, 100%);
+  min-width: 0;
+}
 
 .stage__caption {
   margin: 0;
@@ -750,9 +821,16 @@ a:hover { color: var(--accent); }
   width: 100%;
 }
 
-/* Custom element loading skeletons for the live demos.
-   Match the same hydration pattern used on the install pill above. */
-cts-counter,
+/* Do not set display here; the host grid drives the open/close animation. */
+cts-source-viewer:not(:defined) {
+  /* Keep the collapsed state during hydration. */
+  display: block;
+  height: 0;
+  overflow: hidden;
+}
+
+/* Loading skeletons for live demos. */
+cts-counter,
 cts-todo-dashboard,
 cts-event-log {
   display: block;
@@ -766,8 +844,9 @@ cts-counter:not(:defined) {
   background: linear-gradient(180deg, #11141a 0%, #0f131b 100%);
 }
 
-cts-todo-dashboard:not(:defined) {
-  width: min(720px, calc(100vw - 80px));
+cts-todo-dashboard:not(:defined) {
+  /* Match the compact hydrated width. */
+  width: min(540px, calc(100vw - 80px));
   height: 520px;
   border: 1px solid var(--line-strong);
   border-radius: var(--radius-lg);
@@ -937,10 +1016,8 @@ cts-message:not(:defined)::after {
   pointer-events: none;
 }
 
-/* Code window: fake "lines of code" via stacked gradients.
-   --skel is the line color; positions are content-box relative
-   so we don't have to add the padding offset to every value. */
-cts-code-example:not(:defined) {
+/* Code skeleton lines via stacked gradients. */
+cts-code-example:not(:defined) {
   --skel: rgba(255, 255, 255, 0.06);
   min-height: 380px;
   padding: 28px 32px;
@@ -997,10 +1074,8 @@ cts-message:not(:defined) {
   100% { background-position: -110% 0; }
 }
 
-/* Soft fade-in once the real component swaps in, so the skeleton
-   doesn't pop. `:defined` matches the moment customElements.define
-   completes, which is exactly when the new content renders. */
-cts-code-example:defined,
+/* Fade in once custom elements are defined. */
+cts-code-example:defined,
 cts-message:defined {
   animation: cts-hydrate 280ms var(--ease) both;
 }
@@ -1010,6 +1085,43 @@ cts-message:defined {
   to   { opacity: 1; }
 }
 
+/* Mobile / narrow-viewport adjustments */
+@media (max-width: 720px) {
+  .playground__head {
+    flex-direction: column;
+    align-items: stretch;
+    gap: 14px;
+    padding: 20px 18px 16px;
+  }
+  .playground__actions {
+    justify-content: flex-start;
+    flex-wrap: wrap;
+  }
+  .playground__title {
+    font-size: 19px;
+  }
+  .playground__sub {
+    font-size: 13.5px;
+  }
+
+  .playground__body {
+    padding: 18px 16px 22px;
+    gap: 18px;
+  }
+
+  .stage {
+    padding: 22px 14px;
+    min-height: 200px;
+  }
+  .stage--todo {
+    padding: 22px 10px;
+  }
+
+  cts-code-example {
+    font-size: 12px;
+  }
+}
+
 /* ─────────────────────────────────────────────────────────────
    Reduced motion
    ───────────────────────────────────────────────────────────── */

package/demos/todo-dashboard/todo-dashboard.element.scss

@@ -47,7 +47,7 @@
   --dur-slow: 420ms;
 
   display: block;
-  width: min(720px, calc(100vw - 32px));
+  width: min(720px, 100%);
   color: var(--fg);
   font-family:
     'Geist',
@@ -86,7 +86,7 @@
 }
 
 .shell.compact {
-  width: min(540px, calc(100vw - 32px));
+  width: min(540px, 100%);
 }
 
 @keyframes shell-in {
@@ -310,6 +310,7 @@ cts-todo-item {
   font-weight: 500;
   letter-spacing: 0.14em;
   text-transform: uppercase;
+  white-space: nowrap;
 }
 
 .stat-tag {
@@ -329,6 +330,7 @@ cts-todo-item {
   font-weight: 500;
   letter-spacing: 0.12em;
   text-transform: uppercase;
+  white-space: nowrap;
 }
 
 .stat-tag::before {
@@ -1020,7 +1022,8 @@ input.task-label:focus {
   display: flex;
   align-items: center;
   justify-content: space-between;
-  gap: 12px;
+  flex-wrap: wrap;
+  gap: 10px 12px;
   padding: 14px 18px 14px 24px;
   border-top: 1px solid var(--line);
   background: rgba(0, 0, 0, 0.18);
@@ -1069,6 +1072,7 @@ input.task-label:focus {
 .footer-actions {
   display: flex;
   gap: 6px;
+  margin-left: auto;
 }
 
 .footer-actions button {
@@ -1078,6 +1082,7 @@ input.task-label:focus {
   background: transparent;
   border-color: transparent;
   color: var(--fg-muted);
+  white-space: nowrap;
 }
 
 .footer-actions button:hover {

package/demos/todo-dashboard/todo-dashboard.element.ts

@@ -120,6 +120,7 @@ export class TodoDashboardElement extends HTMLElement {
           <div class="composer-field">
             <span class="composer-icon" aria-hidden="true">${this.iconPlus()}</span>
             <input
+              name="new-task"
               aria-label="New task"
               placeholder="Capture a task and press enter"
               .value=${this.draft}

package/demos/todo-dashboard/todo-item.element.ts

@@ -37,6 +37,7 @@ export class TodoItemElement extends HTMLElement {
           ? html`<span class="task-label is-done">${this.label}</span>`
           : html`<input
               class="task-label"
+              name=${`task-label-${this.todoId}`}
               aria-label="Task label"
               .value=${this.label}
               @change=${this.changeLabel}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "custom-elements-ts",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Create native Custom Elements using Typescript without using any third party libraries",
   "main": "index.js",
   "module": "custom-element.js",
@@ -8,8 +8,8 @@
     "build": "node tools/build.js",
     "start": "node tools/start.js",
     "bundle": "node tools/bundle.js",
-    "publish:dist": "npm run bundle && npm publish dist --access public",
-    "publish:dry-run": "npm run bundle && npm publish dist --dry-run",
+    "publish:dist": "npm run bundle && npm publish ./dist --access public",
+    "publish:dry-run": "npm run bundle && npm publish ./dist --dry-run",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage --coverage.reporter=lcov",

package/src/index.ts

@@ -3,5 +3,6 @@ export * from './watch';
 export * from './prop';
 export * from './toggle';
 export * from './listen';
-export { State } from './state';
-export { html, TemplateResult, TemplateValue } from './template-runtime';
+export { State, StateOptions } from './state';
+export { signal, Signal, isSignal, SignalSubscriber } from './signal';
+export { html, map, TemplateResult, TemplateValue, MappedTemplates } from './template-runtime';

package/src/signal.ts

@@ -0,0 +1,66 @@
+export type SignalSubscriber<T> = (value: T) => void;
+
+/**
+ * Sentinel thrown by a subscriber whose DOM target has been garbage
+ * collected. The notifying signal catches it and drops that subscriber, so
+ * bindings clean themselves up lazily — no explicit disposal bookkeeping is
+ * needed when rendered subtrees are discarded wholesale.
+ */
+export const signalTargetCollected: symbol = Symbol('custom-elements-ts-signal-target-collected');
+
+/**
+ * A writable reactive value. When a signal is embedded in a template
+ * (`html`\`<td>${row.label}</td>\`` or `class=${row.selected}`), the render
+ * part subscribes directly to it: assigning `.value` updates just that DOM
+ * node, bypassing component re-rendering entirely.
+ */
+export class Signal<T> {
+  private currentValue: T;
+  private observers?: Set<SignalSubscriber<T>>;
+
+  constructor(initialValue: T) {
+    this.currentValue = initialValue;
+  }
+
+  get value(): T {
+    return this.currentValue;
+  }
+
+  set value(newValue: T) {
+    if (newValue === this.currentValue) {
+      return;
+    }
+    this.currentValue = newValue;
+    const observers = this.observers;
+    if (!observers) {
+      return;
+    }
+    observers.forEach((observer) => {
+      try {
+        observer(newValue);
+      } catch (error) {
+        if (error === signalTargetCollected) {
+          observers.delete(observer);
+          return;
+        }
+        throw error;
+      }
+    });
+  }
+
+  subscribe(observer: SignalSubscriber<T>): void {
+    (this.observers || (this.observers = new Set())).add(observer);
+  }
+
+  unsubscribe(observer: SignalSubscriber<T>): void {
+    this.observers?.delete(observer);
+  }
+
+  valueOf(): T {
+    return this.currentValue;
+  }
+}
+
+export const signal = <T>(initialValue: T): Signal<T> => new Signal(initialValue);
+
+export const isSignal = (value: unknown): value is Signal<unknown> => value instanceof Signal;

package/src/state.ts

@@ -6,7 +6,17 @@ export interface StateMetadata {
 
 const proxyToRaw = new WeakMap<object, object>();
 
-export const State = (): any => {
+export interface StateOptions {
+  /**
+   * When false, the value is stored as-is: no deep proxy is created and
+   * nested mutations do not schedule renders — reassign the property to
+   * re-render. Much cheaper for large arrays of objects. Defaults to true.
+   */
+  deep?: boolean;
+}
+
+export const State = (options?: StateOptions): any => {
+  const deep = options?.deep !== false;
   return (target: any, propName: string) => {
     if (!target.constructor.stateInit) {
       target.constructor.stateInit = {};
@@ -27,13 +37,15 @@ export const State = (): any => {
 
       const oldValue = this.__stateValues[propName];
       const proxyCache = (this.__stateProxyCaches[propName] ||= new WeakMap<object, unknown>());
-      const newValue = createStateProxy(value, proxyCache, () => {
-        this.__notifyPropertyChange?.(
-          propName,
-          this.__stateValues[propName],
-          this.__stateValues[propName]
-        );
-      });
+      const newValue = deep
+        ? createStateProxy(value, proxyCache, () => {
+            this.__notifyPropertyChange?.(
+              propName,
+              this.__stateValues[propName],
+              this.__stateValues[propName]
+            );
+          })
+        : value;
 
       if (Object.is(oldValue, newValue)) {
         return;