@design.estate/wcctools 5.1.0 → 6.1.0

package/ts/standards/rules/props.reflect-primitive.ts

@@ -0,0 +1,44 @@
+import * as ast from '../helpers.ast.js';
+import type { IRuleFinding, IStandardRule } from '../rule.js';
+import { addOptionFix } from './props.typed.js';
+import { propertyKey, publicProperties } from './shared.js';
+
+/** Global attributes with native behaviour that stay unreflected without an allowlist entry. */
+export const reflectExemptNames: readonly string[] = ['title', 'hidden', 'dir', 'lang', 'role', 'inert', 'draggable'];
+
+const primitiveTypes = ['String', 'Number', 'Boolean'];
+
+/** A primitive public property declares `reflect: true` or `attribute: false`. */
+export const propsReflectPrimitiveRule: IStandardRule = {
+  id: 'props/reflect-primitive',
+  severity: { base: 'error' },
+  fixMode: 'opt-in',
+  allowlistCategories: ['user-data', 'object', 'large-text', 'global-attribute'],
+  detect: ({ project }) => {
+    const findings: IRuleFinding[] = [];
+    for (const property of publicProperties(project)) {
+      if (property.dynamicOptions || reflectExemptNames.includes(property.name)) {
+        continue;
+      }
+      const options = property.options;
+      const type = options ? ast.objectPropertyText(options, 'type') : null;
+      if (type !== null && !primitiveTypes.includes(type)) {
+        continue;
+      }
+      if (options && (ast.objectPropertyText(options, 'attribute') === 'false' || ast.objectPropertyText(options, 'reflect') === 'true')) {
+        continue;
+      }
+      const explicitReflect = options ? ast.objectProperty(options, 'reflect') : null;
+      findings.push({
+        file: property.file,
+        position: property.call.getStart(),
+        key: propertyKey(property),
+        message: `public primitive @property ${property.name} declares neither reflect: true nor attribute: false`,
+        fix: explicitReflect
+          ? (builderArg) => builderArg.edit(property.file, explicitReflect.initializer.getStart(), explicitReflect.initializer.end, 'true')
+          : addOptionFix(property, 'reflect: true', 'last'),
+      });
+    }
+    return findings;
+  },
+};

package/ts/standards/rules/props.typed.ts

@@ -0,0 +1,70 @@
+import * as plugins from '../../plugins.js';
+import * as ast from '../helpers.ast.js';
+import type { IStandardProperty } from '../classes.standardproject.js';
+import type { IRuleFinding, IStandardRule, TFixAction } from '../rule.js';
+import { coreTypeOf, isArrayTypeNode, propertyKey, publicProperties } from './shared.js';
+
+const ts = plugins.typescript;
+
+/** The Lit `type` that the property's annotation maps to, or null when the annotation does not decide it. */
+const litTypeFor = (propertyArg: IStandardProperty): string | null => {
+  const typeNode = coreTypeOf(propertyArg);
+  if (!typeNode) {
+    return null;
+  }
+  switch (typeNode.kind) {
+    case ts.SyntaxKind.StringKeyword:
+      return 'String';
+    case ts.SyntaxKind.NumberKeyword:
+      return 'Number';
+    case ts.SyntaxKind.BooleanKeyword:
+      return 'Boolean';
+  }
+  if (ts.isUnionTypeNode(typeNode) && typeNode.types.every((typeArg) =>
+    (ts.isLiteralTypeNode(typeArg) && ts.isStringLiteral(typeArg.literal))
+    || typeArg.kind === ts.SyntaxKind.UndefinedKeyword
+    || (ts.isLiteralTypeNode(typeArg) && typeArg.literal.kind === ts.SyntaxKind.NullKeyword))) {
+    return 'String';
+  }
+  if (ts.isLiteralTypeNode(typeNode) && ts.isStringLiteral(typeNode.literal)) {
+    return 'String';
+  }
+  return isArrayTypeNode(typeNode) ? 'Array' : null;
+};
+
+/** The edit that adds `propertyTextArg` to a property decorator's options, creating the options literal when absent. */
+export const addOptionFix = (propertyArg: IStandardProperty, propertyTextArg: string, placementArg: 'first' | 'last'): TFixAction => (builderArg) => {
+  if (propertyArg.options) {
+    const edit = placementArg === 'first'
+      ? ast.prependObjectPropertyEdit(propertyArg.options, propertyTextArg)
+      : ast.appendObjectPropertyEdit(propertyArg.options, propertyTextArg);
+    builderArg.edit(propertyArg.file, edit.start, edit.end, edit.text);
+    return;
+  }
+  const at = propertyArg.call.arguments.pos;
+  builderArg.edit(propertyArg.file, at, at, `{ ${propertyTextArg} }`);
+};
+
+/** A public property declares `type`. */
+export const propsTypedRule: IStandardRule = {
+  id: 'props/typed',
+  severity: { base: 'warn' },
+  fixMode: 'auto',
+  detect: ({ project }) => {
+    const findings: IRuleFinding[] = [];
+    for (const property of publicProperties(project)) {
+      if (property.dynamicOptions || (property.options && ast.objectProperty(property.options, 'type'))) {
+        continue;
+      }
+      const litType = litTypeFor(property);
+      findings.push({
+        file: property.file,
+        position: property.call.getStart(),
+        key: propertyKey(property),
+        message: `@property ${property.name} declares no type`,
+        fix: litType ? addOptionFix(property, `type: ${litType}`, 'first') : undefined,
+      });
+    }
+    return findings;
+  },
+};

package/ts/standards/rules/shared.ts

@@ -0,0 +1,127 @@
+import * as plugins from '../../plugins.js';
+import * as ast from '../helpers.ast.js';
+import { baseOf, dirOf, specifierFor } from '../helpers.paths.js';
+import type { IStandardElement, IStandardProperty, StandardProject } from '../classes.standardproject.js';
+import type { IFixBuilder } from '../rule.js';
+
+const ts = plugins.typescript;
+
+export const elementsDir = 'ts_web/elements';
+
+/** `ts_web/elements/00group-<area>` or `ts_web/elements` itself. */
+export const isElementParentDir = (dirArg: string): boolean =>
+  dirArg === elementsDir || /^ts_web\/elements\/00group-[^/]+$/.test(dirArg);
+
+/** Names the HTML specification reserves; `customElements.define` rejects them. */
+const reservedElementNames = ['annotation-xml', 'color-profile', 'font-face', 'font-face-src', 'font-face-uri', 'font-face-format', 'font-face-name', 'missing-glyph'];
+
+/**
+ * A valid custom element name in the ASCII subset the standard allows: a lowercase letter first,
+ * then lowercase letters, digits, `-`, `.` and `_`, at least one `-`, and not a reserved name. Such
+ * a tag is also a safe file and folder name, so only these tags feed fixes that derive paths or code.
+ */
+export const isCustomElementName = (tagArg: string): boolean =>
+  /^[a-z][a-z0-9._-]*$/.test(tagArg) && tagArg.includes('-') && !reservedElementNames.includes(tagArg);
+
+/** True when an element's entry file sits in its own element folder `…/<tag>/`. */
+export const isInElementFolder = (elementArg: IStandardElement): boolean => {
+  const folder = dirOf(elementArg.file);
+  return !!elementArg.tag && baseOf(folder) === elementArg.tag && isElementParentDir(dirOf(folder));
+};
+
+/** The `<area>` of `ts_web/elements/00group-<area>/…`, or null. */
+export const groupAreaOf = (fileArg: string): string | null => /^ts_web\/elements\/00group-([^/]+)\//.exec(fileArg)?.[1] ?? null;
+
+/** Elements outside demo files: the catalog's own elements. */
+export const catalogElements = (projectArg: StandardProject): IStandardElement[] =>
+  projectArg.elements.filter((elementArg) => !elementArg.inDemoFile);
+
+/** Public `@property` members outside demo files. */
+export const publicProperties = (projectArg: StandardProject): IStandardProperty[] =>
+  projectArg.properties.filter((propertyArg) => propertyArg.decorator === 'property' && propertyArg.isPublic && !propertyArg.inDemoFile);
+
+export const elementKey = (elementArg: IStandardElement): string => `${elementArg.file}#${elementArg.className ?? elementArg.tag ?? '?'}`;
+
+export const propertyKey = (propertyArg: IStandardProperty): string => `${propertyArg.file}#${propertyArg.name}`;
+
+/** The type annotation of a property member without `undefined` and `null` union members. */
+export const coreTypeOf = (propertyArg: IStandardProperty): ast.TTypeNode | null => {
+  const member = propertyArg.member;
+  const typeNode = ts.isPropertyDeclaration(member) ? member.type : undefined;
+  if (!typeNode) {
+    return null;
+  }
+  if (ts.isUnionTypeNode(typeNode)) {
+    const members = typeNode.types.filter((typeArg) =>
+      typeArg.kind !== ts.SyntaxKind.UndefinedKeyword
+      && !(ts.isLiteralTypeNode(typeArg) && typeArg.literal.kind === ts.SyntaxKind.NullKeyword));
+    if (members.length === 1) {
+      return members[0];
+    }
+    return typeNode;
+  }
+  return typeNode;
+};
+
+export const isArrayTypeNode = (typeArg: ast.TTypeNode): boolean => {
+  if (ts.isArrayTypeNode(typeArg)) {
+    return true;
+  }
+  if (ts.isTypeOperatorNode(typeArg) && typeArg.operator === ts.SyntaxKind.ReadonlyKeyword) {
+    return ts.isArrayTypeNode(typeArg.type);
+  }
+  return ts.isTypeReferenceNode(typeArg) && ts.isIdentifier(typeArg.typeName) && ['Array', 'ReadonlyArray'].includes(typeArg.typeName.text);
+};
+
+/** The position at the start of the line after the last `export … from` statement, or at the end of the file. */
+export const exportInsertionPoint = (sourceFileArg: ast.TSourceFile): { position: number; prefix: string } => {
+  let lastEnd = -1;
+  for (const statement of sourceFileArg.statements) {
+    if (ts.isExportDeclaration(statement)) {
+      lastEnd = statement.end;
+    }
+  }
+  const text = sourceFileArg.text;
+  if (lastEnd === -1) {
+    return { position: text.length, prefix: text.length > 0 && !text.endsWith('\n') ? '\n' : '' };
+  }
+  const newline = text.indexOf('\n', lastEnd);
+  return newline === -1 ? { position: text.length, prefix: '\n' } : { position: newline + 1, prefix: '' };
+};
+
+/** Adds `export * from '<target>';` to a barrel. */
+export const addReexport = (builderArg: IFixBuilder, projectArg: StandardProject, barrelArg: string, targetArg: string): void => {
+  const point = exportInsertionPoint(projectArg.sourceFile(barrelArg));
+  builderArg.edit(barrelArg, point.position, point.position, `${point.prefix}export * from '${specifierFor(barrelArg, targetArg, 'js')}';\n`);
+};
+
+/** Removes a whole statement including its line break; from the line start when only indentation precedes it. */
+export const removeStatement = (builderArg: IFixBuilder, fileArg: string, statementArg: ast.TNode): void => {
+  const text = statementArg.getSourceFile().text;
+  let start = statementArg.getStart();
+  const lineStart = text.lastIndexOf('\n', start - 1) + 1;
+  if (/^[ \t]*$/.test(text.slice(lineStart, start))) {
+    start = lineStart;
+  }
+  let end = statementArg.end;
+  const rest = /^[ \t]*\r?\n/.exec(text.slice(end));
+  if (rest) {
+    end += rest[0].length;
+  }
+  builderArg.edit(fileArg, start, end, '');
+};
+
+/** The identifier a `static demo` value refers to at its root, e.g. `demoFunc` or `demos` in `demos.main`. */
+export const rootIdentifier = (expressionArg: ast.TExpression): string | null => {
+  let current: ast.TExpression = expressionArg;
+  while (ts.isPropertyAccessExpression(current)) {
+    current = current.expression;
+  }
+  return ts.isIdentifier(current) ? current.text : null;
+};
+
+/** The start of the line following the line a position is on. */
+export const nextLineStart = (textArg: string, positionArg: number): number => {
+  const newline = textArg.indexOf('\n', positionArg);
+  return newline === -1 ? textArg.length : newline + 1;
+};

package/ts/standards/rules/style.bdtheme.ts

@@ -0,0 +1,31 @@
+import * as plugins from '../../plugins.js';
+import * as ast from '../helpers.ast.js';
+import type { IRuleFinding, IStandardRule } from '../rule.js';
+
+const ts = plugins.typescript;
+
+/** The one module that may call `bdTheme()`: the token bridge. */
+export const bdThemeBridge = 'ts_web/elements/00theme.ts';
+
+/** dees: no new `cssManager.bdTheme()` call outside `ts_web/elements/00theme.ts`. A ratchet: baselines only. */
+export const styleBdThemeRule: IStandardRule = {
+  id: 'style/bdtheme',
+  severity: { dees: 'error' },
+  fixMode: 'none',
+  detect: ({ project }) => {
+    const findings: IRuleFinding[] = [];
+    for (const file of project.webFiles) {
+      if (file === bdThemeBridge) {
+        continue;
+      }
+      const visit = (nodeArg: ast.TNode): void => {
+        if (ts.isCallExpression(nodeArg) && ast.calleeName(nodeArg.expression) === 'bdTheme') {
+          findings.push({ file, position: nodeArg.getStart(), key: file, message: 'bdTheme() call; use --dees-* tokens' });
+        }
+        ts.forEachChild(nodeArg, visit);
+      };
+      visit(project.sourceFile(file));
+    }
+    return findings;
+  },
+};

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/wcctools',
-  version: '5.1.0',
+  version: '6.1.0',
   description: 'A set of web component tools for creating element catalogues, enabling the structured development and documentation of custom elements and pages.'
 }

package/ts_web/catalog.ts

@@ -0,0 +1,194 @@
+import * as plugins from './wcctools.plugins.js';
+import {
+  classifyCatalogEntry,
+  getDemoAtIndex,
+  getDemoCount,
+  getElementDemoGroups,
+  getElementTagName,
+  type ICatalogElementConstructor,
+  type TDemoDefinition,
+  type TTemplateFactory,
+} from './elements/wcctools.helpers.js';
+import type { IWccConfig, IWccSection } from './wcctools.interfaces.js';
+
+type TSectionEntry = [string, any];
+
+const applySectionFilterAndSort = (
+  section: IWccSection,
+  entries: TSectionEntry[],
+  fallbackSort?: (a: TSectionEntry, b: TSectionEntry) => number
+): TSectionEntry[] => {
+  let result = entries;
+  if (section.filter) {
+    const filterFn = section.filter;
+    result = result.filter(([name, item]) => filterFn(name, item));
+  }
+  const sortFn = section.sort ?? fallbackSort;
+  if (sortFn) {
+    result = [...result].sort(sortFn);
+  }
+  return result;
+};
+
+/**
+ * The navigable entries of a section, after classification and the section's own filter and sort.
+ * Elements sections keep only custom element classes with a usable static `demo`;
+ * pages sections keep only template factories.
+ */
+export const getSectionItems = (section: IWccSection): TSectionEntry[] => {
+  const entries = Object.entries(section.items).filter(([, item]) =>
+    section.type === 'elements'
+      ? classifyCatalogEntry(item) === 'demo'
+      : typeof item === 'function'
+  );
+  return applySectionFilterAndSort(section, entries);
+};
+
+/**
+ * Registered custom elements of an elements section that have no usable demo.
+ * They are listed (not navigable) in the sidebar's "Without demo" group.
+ */
+export const getSectionItemsWithoutDemo = (section: IWccSection): TSectionEntry[] => {
+  if (section.type !== 'elements') {
+    return [];
+  }
+  const entries = Object.entries(section.items).filter(([, item]) => classifyCatalogEntry(item) === 'no-demo');
+  return applySectionFilterAndSort(section, entries, ([a], [b]) => a.localeCompare(b));
+};
+
+/** What a selection resolves to: something to render, or the reason there is nothing. */
+export type TWccCatalogTarget =
+  | { kind: 'element'; factory: TTemplateFactory; elementClass: ICatalogElementConstructor }
+  | { kind: 'page'; factory: TTemplateFactory }
+  | { kind: 'empty'; reason: plugins.interfaces.TWccEmptyReason; emptyState: plugins.interfaces.IWccEmptyState };
+
+type TResolvedEntry =
+  | { kind: 'listed'; section: IWccSection; item: unknown }
+  | { kind: 'no-demo' | 'ignored' | 'missing'; section: IWccSection | null };
+
+/**
+ * The catalog of one `setupWccTools` call: classifies its sections, describes them as a
+ * data-only manifest and resolves selections to template factories.
+ */
+export class WccCatalog {
+  private readonly sections: IWccSection[];
+
+  constructor(configArg: IWccConfig) {
+    this.sections = configArg.sections;
+  }
+
+  public getManifest(): plugins.interfaces.IWccCatalogManifest {
+    return {
+      sections: this.sections.map((section) => ({
+        name: section.name,
+        type: section.type,
+        ...(section.icon ? { icon: section.icon } : {}),
+        ...(section.collapsed ? { collapsed: true } : {}),
+        entries: getSectionItems(section).map(([name, item]) => ({
+          name,
+          tagName: getElementTagName(item),
+          demoCount: section.type === 'elements' ? getDemoCount(item.demo as TDemoDefinition) : 1,
+          demoGroups: getElementDemoGroups(item),
+        })),
+        entriesWithoutDemo: getSectionItemsWithoutDemo(section).map(([name, item]) => ({
+          name,
+          tagName: getElementTagName(item),
+        })),
+      })),
+    };
+  }
+
+  public resolve(selectionArg: plugins.interfaces.IWccSelection | null): TWccCatalogTarget {
+    if (!selectionArg) {
+      return {
+        kind: 'empty',
+        reason: 'nothing-selected',
+        emptyState: {
+          title: 'Nothing selected',
+          detail: 'Choose an element or page in the sidebar to preview it here.',
+        },
+      };
+    }
+    const { sectionName, itemName, demoIndex } = selectionArg;
+    const resolved = this.resolveEntry(sectionName, itemName);
+    if (resolved.kind !== 'listed') {
+      return { kind: 'empty', reason: resolved.kind, emptyState: this.getUnavailableEmptyState(resolved, sectionName, itemName) };
+    }
+    if (resolved.section.type === 'pages') {
+      return { kind: 'page', factory: resolved.item as TTemplateFactory };
+    }
+    const elementClass = resolved.item as ICatalogElementConstructor;
+    const demo = elementClass.demo as TDemoDefinition;
+    const factory = getDemoAtIndex(demo, demoIndex);
+    if (!factory) {
+      const count = getDemoCount(demo);
+      return {
+        kind: 'empty',
+        reason: 'no-such-demo',
+        emptyState: {
+          title: `${itemName} has no demo ${demoIndex + 1}`,
+          detail: `This element defines ${count} ${count === 1 ? 'demo' : 'demos'}.`,
+        },
+      };
+    }
+    return { kind: 'element', factory, elementClass };
+  }
+
+  /**
+   * Resolve a section/item pair to a listed entry, or to the reason it cannot be previewed.
+   * The section names `element` and `page` of links from before sections existed search every section.
+   */
+  private resolveEntry(sectionNameArg: string, itemNameArg: string): TResolvedEntry {
+    const section = this.sections.find((sectionArg) => sectionArg.name === sectionNameArg) ?? null;
+    const isLegacyName = !section && (sectionNameArg === 'element' || sectionNameArg === 'page');
+    const candidates = section ? [section] : isLegacyName ? this.sections : [];
+
+    for (const candidate of candidates) {
+      const listed = getSectionItems(candidate).find(([name]) => name === itemNameArg);
+      if (listed) {
+        return { kind: 'listed', section: candidate, item: listed[1] };
+      }
+    }
+    for (const candidate of candidates) {
+      if (getSectionItemsWithoutDemo(candidate).some(([name]) => name === itemNameArg)) {
+        return { kind: 'no-demo', section: candidate };
+      }
+    }
+    for (const candidate of candidates) {
+      if (Object.prototype.hasOwnProperty.call(candidate.items, itemNameArg)) {
+        const item = candidate.items[itemNameArg];
+        const notDemoable = candidate.type === 'elements'
+          ? classifyCatalogEntry(item) === 'ignored'
+          : typeof item !== 'function';
+        return { kind: notDemoable ? 'ignored' : 'missing', section: candidate };
+      }
+    }
+    return { kind: 'missing', section };
+  }
+
+  private getUnavailableEmptyState(
+    resolvedArg: Exclude<TResolvedEntry, { kind: 'listed' }>,
+    sectionNameArg: string,
+    itemNameArg: string,
+  ): plugins.interfaces.IWccEmptyState {
+    switch (resolvedArg.kind) {
+      case 'no-demo': {
+        const tagName = getElementTagName(resolvedArg.section?.items[itemNameArg]);
+        return {
+          title: `${itemNameArg} has no demo`,
+          detail: `${tagName ? `<${tagName}>` : 'This element'} is a registered custom element without a static demo. It is listed under "Without demo".`,
+        };
+      }
+      case 'ignored':
+        return {
+          title: `${itemNameArg} cannot be previewed`,
+          detail: 'This export is not a custom element with a demo, so the catalog does not list it.',
+        };
+      case 'missing':
+        return {
+          title: `${itemNameArg} was not found`,
+          detail: `No entry with this name exists in "${sectionNameArg}".`,
+        };
+    }
+  }
+}

package/ts_web/elementproperties.ts

@@ -0,0 +1,96 @@
+import * as plugins from './wcctools.plugins.js';
+import { determinePropertyType, type IReactivePropertyDeclaration } from './elements/wcctools.helpers.js';
+
+/** The reactive property declarations Lit keeps on an element class. */
+type TPropertyDeclarations = Map<PropertyKey, IReactivePropertyDeclaration>;
+
+const skippedPropertyNames = new Set(['goBright', 'domtools']);
+
+const scalarKinds = new Set<plugins.interfaces.TWccPropertyKind>(['String', 'Number', 'Boolean', 'Enum']);
+
+const getDeclarations = (elementClassArg: unknown): TPropertyDeclarations | null => {
+  const declarations = (elementClassArg as { elementProperties?: unknown }).elementProperties;
+  return declarations instanceof Map ? declarations as TPropertyDeclarations : null;
+};
+
+const toScalar = (valueArg: unknown): plugins.interfaces.TWccPropertyScalar => {
+  if (typeof valueArg === 'string' || typeof valueArg === 'number' || typeof valueArg === 'boolean') {
+    return valueArg;
+  }
+  return null;
+};
+
+const toJson = (valueArg: unknown): string | undefined => {
+  try {
+    return JSON.stringify(valueArg ?? null, null, 2);
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * The editable properties an element class declares and the values its instance holds.
+ * It runs in the realm that defined the class, so Lit's `type: String` declarations compare
+ * against the same `String` and the values never cross into another document's realm.
+ */
+export class WccElementProperties {
+  constructor(
+    private readonly elementClass: unknown,
+    private readonly instance: HTMLElement,
+  ) {}
+
+  public describe(): plugins.interfaces.IWccPropertyDescriptor[] | null {
+    const declarations = getDeclarations(this.elementClass);
+    if (!declarations) {
+      return null;
+    }
+    const descriptors: plugins.interfaces.IWccPropertyDescriptor[] = [];
+    for (const [key, declaration] of declarations) {
+      if (typeof key !== 'string' || key.startsWith('#') || skippedPropertyNames.has(key)) {
+        continue;
+      }
+      const kind = determinePropertyType(declaration);
+      if (!kind) {
+        continue;
+      }
+      const value = (this.instance as unknown as Record<string, unknown>)[key];
+      if (scalarKinds.has(kind)) {
+        descriptors.push(kind === 'Enum'
+          ? { name: key, kind, value: toScalar(value), enumValues: Object.keys(declaration.type as object) }
+          : { name: key, kind, value: toScalar(value) });
+      } else {
+        descriptors.push({ name: key, kind, json: toJson(value) });
+      }
+    }
+    return descriptors;
+  }
+
+  public set(nameArg: string, valueArg: plugins.interfaces.TWccPropertyScalar): plugins.interfaces.TWccPropertyEditResult {
+    const kind = this.getKind(nameArg);
+    if (!kind || !scalarKinds.has(kind)) {
+      return { ok: false, error: `${nameArg} is not an editable scalar property` };
+    }
+    (this.instance as unknown as Record<string, unknown>)[nameArg] = valueArg;
+    return { ok: true };
+  }
+
+  public setJson(nameArg: string, jsonArg: string): plugins.interfaces.TWccPropertyEditResult {
+    const kind = this.getKind(nameArg);
+    if (kind !== 'Object' && kind !== 'Array') {
+      return { ok: false, error: `${nameArg} is not an Object or Array property` };
+    }
+    let value: unknown;
+    try {
+      value = JSON.parse(jsonArg);
+    } catch (error) {
+      return { ok: false, error: `Invalid JSON: ${(error as Error).message}` };
+    }
+    (this.instance as unknown as Record<string, unknown>)[nameArg] = value;
+    return { ok: true };
+  }
+
+  private getKind(nameArg: string): plugins.interfaces.TWccPropertyKind | null {
+    const declaration = getDeclarations(this.elementClass)?.get(nameArg);
+    return declaration && !skippedPropertyNames.has(nameArg) ? determinePropertyType(declaration) : null;
+  }
+}

package/ts_web/elements/wcc-preview.ts

@@ -0,0 +1,111 @@
+import { DeesElement, property, html, customElement, type TemplateResult, css } from '@design.estate/dees-element';
+import * as plugins from '../wcctools.plugins.js';
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'wcc-preview': WccPreview;
+  }
+}
+
+/**
+ * The surface a preview document renders demos and pages into. The preview document is as
+ * wide as the selected viewport, so width media queries and the `wccToolsViewport` container
+ * queries of the rendered elements both follow it.
+ */
+@customElement('wcc-preview')
+export class WccPreview extends DeesElement {
+  @property({ attribute: false })
+  accessor emptyState: plugins.interfaces.IWccEmptyState | null = null;
+
+  public static styles = [
+    css`
+      :host {
+        display: block;
+        position: relative;
+        min-height: 100vh;
+      }
+
+      .viewport {
+        box-sizing: border-box;
+        container-type: inline-size;
+        container-name: wccToolsViewport;
+        position: relative;
+        min-height: 100vh;
+      }
+
+      .empty-state {
+        position: absolute;
+        inset: 0;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        padding: 24px;
+        pointer-events: none;
+      }
+
+      .empty-state-card {
+        pointer-events: auto;
+        max-width: 420px;
+        padding: 20px 24px;
+        border-radius: 8px;
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        background: rgba(10, 10, 10, 0.88);
+        backdrop-filter: blur(8px);
+        color: #e5e5e5;
+        font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif;
+        text-align: center;
+      }
+
+      .empty-state-title {
+        margin: 0 0 6px;
+        font-size: 15px;
+        font-weight: 600;
+        overflow-wrap: anywhere;
+      }
+
+      .empty-state-detail {
+        margin: 0;
+        font-size: 13px;
+        line-height: 1.5;
+        color: #a3a3a3;
+        overflow-wrap: anywhere;
+      }
+    `,
+  ];
+
+  public render(): TemplateResult {
+    const pattern = this.goBright
+      ? { dot: '#CCCCCC', base: '#eeeeee' }
+      : { dot: '#444444', base: '#222222' };
+    return html`
+      <style>
+        .viewport {
+          background:
+            radial-gradient(${pattern.dot} 3px, transparent 4px),
+            radial-gradient(${pattern.dot} 3px, transparent 4px),
+            linear-gradient(${pattern.base} 4px, transparent 0),
+            linear-gradient(45deg, transparent 74px, transparent 75px, ${pattern.dot} 75px, ${pattern.dot} 76px, transparent 77px, transparent 109px),
+            linear-gradient(-45deg, transparent 75px, transparent 76px, ${pattern.dot} 76px, ${pattern.dot} 77px, transparent 78px, transparent 109px),
+            ${pattern.base};
+          background-size: 109px 109px, 109px 109px, 100% 6px, 109px 109px, 109px 109px;
+          background-position: 54px 55px, 0px 0px, 0px 0px, 0px 0px, 0px 0px;
+        }
+      </style>
+      <div class="viewport"></div>
+      ${this.emptyState ? html`
+        <div class="empty-state">
+          <div class="empty-state-card" role="status">
+            <h2 class="empty-state-title">${this.emptyState.title}</h2>
+            <p class="empty-state-detail">${this.emptyState.detail}</p>
+          </div>
+        </div>
+      ` : null}
+    `;
+  }
+
+  /** The element demos and pages render into; available once the first update completed. */
+  public async getViewportElement(): Promise<HTMLElement> {
+    await this.updateComplete;
+    return this.shadowRoot.querySelector('.viewport') as HTMLElement;
+  }
+}