@design.estate/wcctools 5.1.0 → 6.0.0

package/ts/classes.devapi.ts

@@ -0,0 +1,25 @@
+import * as plugins from './plugins.js';
+
+/**
+ * The typed API the shell reaches on `/wcctools/typedrequest`. Later features register their
+ * handlers on `typedrouter`.
+ */
+export class WccDevApi {
+  public readonly typedrouter = new plugins.typedrequest.TypedRouter();
+  private serverInfo: plugins.interfaces.IWccDevServerInfo | null = null;
+
+  constructor() {
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<plugins.interfaces.IReq_GetDevServerInfo>('getDevServerInfo', async () => {
+        if (!this.serverInfo) {
+          throw new Error('The dev server has not started.');
+        }
+        return { ...this.serverInfo };
+      }),
+    );
+  }
+
+  public setServerInfo(infoArg: plugins.interfaces.IWccDevServerInfo) {
+    this.serverInfo = { ...infoArg };
+  }
+}

package/ts/classes.devserver.ts

@@ -0,0 +1,161 @@
+import * as plugins from './plugins.js';
+import * as paths from './paths.js';
+import { commitinfo } from './00_commitinfo_data.js';
+import { WccDevApi } from './classes.devapi.js';
+import { loadShellContent, shellPathPrefix } from './shellcontent.js';
+
+export interface IWccDevServerOptions {
+  /** Port to listen on; overrides the tswatch configuration. 0 picks a free port. */
+  port?: number;
+}
+
+export interface IWccDevServerAddress {
+  port: number;
+  /** The shell's address. */
+  url: string;
+}
+
+/** tswatch's default port and serve directory, used when the configuration names none. */
+const defaultPort = 3002;
+const defaultServeDir = './dist_watch/';
+
+/** The development headers tswatch serves catalogs with: a cross-origin isolated document. */
+const securityHeaders: plugins.typedserver.ISecurityHeaders = {
+  crossOriginOpenerPolicy: 'same-origin',
+  crossOriginEmbedderPolicy: 'require-corp',
+};
+
+const acceptAnyHostname = () => true;
+
+/**
+ * `wcctools dev`: bundles the catalog of the current project with tswatch, as its
+ * `@git.zone/tswatch` configuration (or the `element` preset) describes, and serves on one port:
+ *
+ * - the shell on `/wcctools/` (`/` redirects there) and its routes `/wcctools-route/...`,
+ * - the typed API on `/wcctools/typedrequest`,
+ * - the catalog's preview document and bundle from the tswatch serve directory on every other
+ *   path, with live reload that reloads only the preview document.
+ *
+ * tswatch resolves its paths against the process's working directory, so the server serves the
+ * project the process runs in.
+ */
+export class WccDevServer {
+  /** The typed API on `/wcctools/typedrequest`; register further handlers before `start()`. */
+  public readonly api = new WccDevApi();
+  private tsWatch: plugins.tswatch.TsWatch | null = null;
+  private typedServer: plugins.typedserver.TypedServer | null = null;
+  private readonly smartExit = new plugins.smartexit.SmartExit({ silent: true });
+
+  constructor(private readonly options: IWccDevServerOptions = {}) {
+    this.smartExit.addCleanupFunction(() => this.stop());
+  }
+
+  public async start(): Promise<IWccDevServerAddress> {
+    if (this.typedServer) {
+      throw new Error('wcctools: the dev server is already started.');
+    }
+    const cwd = process.cwd();
+    const configHandler = new plugins.tswatch.ConfigHandler(cwd);
+    const config = configHandler.loadConfig() ?? configHandler.getPreset('element');
+    const serveDir = plugins.path.resolve(cwd, config.server?.serveDir ?? defaultServeDir);
+    const port = this.options.port ?? config.server?.port ?? defaultPort;
+
+    // The preview surface watches the serve directory, which must exist before the first bundle
+    await plugins.fs.mkdir(serveDir, { recursive: true });
+    this.api.setServerInfo({
+      wcctoolsVersion: commitinfo.version,
+      projectName: await this.readProjectName(cwd),
+    });
+    const typedServer = new plugins.typedserver.TypedServer({
+      cors: false,
+      port,
+      surfaces: [
+        await this.createShellSurface(),
+        this.createPreviewSurface(serveDir),
+      ],
+    });
+    this.typedServer = typedServer;
+
+    // Bundling and watching stay tswatch's; its own server stays off
+    this.tsWatch = new plugins.tswatch.TsWatch({ ...config, server: { enabled: false } });
+    try {
+      await this.tsWatch.start();
+      await typedServer.start();
+    } catch (error) {
+      await this.stop();
+      throw error;
+    }
+    const boundPort = typedServer.listeningPort ?? port;
+    return { port: boundPort, url: `http://localhost:${boundPort}${shellPathPrefix}/` };
+  }
+
+  /** Stops the server, then tswatch's bundling and watching. */
+  public async stop(): Promise<void> {
+    const typedServer = this.typedServer;
+    const tsWatch = this.tsWatch;
+    this.typedServer = null;
+    this.tsWatch = null;
+    this.smartExit.deregister();
+    await typedServer?.stop();
+    await tsWatch?.stop();
+  }
+
+  /**
+   * The shell: the prebuilt shell bundle and the typed API.
+   *
+   * Seam for side-effecting APIs (assistant, capture, standards fixes): before any handler with
+   * side effects is registered here, add a `websocketAdmission`/`requestAdmission` that accepts
+   * only the shell's own origin, and keep surface mode's strict authority validation.
+   */
+  private async createShellSurface(): Promise<plugins.typedserver.ITypedServerSurface> {
+    return {
+      name: 'shell',
+      match: {
+        hostnameResolver: acceptAnyHostname,
+        pathPrefixes: [shellPathPrefix, '/wcctools-route'],
+      },
+      bundledContent: await loadShellContent(paths.distShellDir),
+      spaFallback: true,
+      httpTypedRouter: this.api.typedrouter,
+      typedRequestPath: `${shellPathPrefix}/typedrequest`,
+      noCache: true,
+      securityHeaders,
+    };
+  }
+
+  /**
+   * The preview: the catalog's own document and bundle from the tswatch serve directory, on
+   * the root paths it was written for. Its live reload client is injected into its document
+   * only, so a rebuilt bundle reloads the preview frame and never the shell.
+   */
+  private createPreviewSurface(serveDirArg: string): plugins.typedserver.ITypedServerSurface {
+    return {
+      name: 'preview',
+      match: {
+        hostnameResolver: acceptAnyHostname,
+        pathPrefixes: ['/'],
+      },
+      serveDir: serveDirArg,
+      spaFallback: true,
+      injectReload: true,
+      watch: true,
+      // Lets the reload client get pushed changes instead of polling
+      websocketTypedRouter: new plugins.typedrequest.TypedRouter(),
+      // As tswatch serves catalogs
+      cors: true,
+      httpHandler: async (contextArg) => {
+        if (contextArg.path === '/' && (contextArg.method === 'GET' || contextArg.method === 'HEAD')) {
+          return new Response(null, { status: 302, headers: { Location: `${shellPathPrefix}/` } });
+        }
+        return null;
+      },
+      noCache: true,
+      securityHeaders,
+    };
+  }
+
+  private async readProjectName(cwdArg: string): Promise<string> {
+    const packageJson = JSON.parse(await plugins.fs.readFile(plugins.path.join(cwdArg, 'package.json'), 'utf8')) as { name?: string };
+    return packageJson.name ?? plugins.path.basename(cwdArg);
+  }
+}

package/ts/cli.ts

@@ -0,0 +1,46 @@
+import * as plugins from './plugins.js';
+import { commitinfo } from './00_commitinfo_data.js';
+import { WccDevServer } from './classes.devserver.js';
+
+/**
+ * Registers the wcctools commands on the given console.
+ */
+export const registerCommands = (out: plugins.smartconsole.SmartConsole): void => {
+  out.cli.configure({
+    name: 'wcctools',
+    version: commitinfo.version,
+    description: 'Develop a web component catalog in the wcctools shell',
+  });
+
+  out.cli.command({
+    name: 'dev',
+    description: 'Bundle the catalog with live reload and serve it in the wcctools shell',
+    options: {
+      port: {
+        type: 'number',
+        description: 'Port to listen on (0 picks a free port); overrides the tswatch configuration',
+      },
+    },
+  }, async ({ options }) => {
+    const devServer = new WccDevServer({ port: options.port });
+    const address = await devServer.start();
+    await out.log(`wcctools dev: ${address.url}`);
+  });
+
+  out.cli.default({}, async () => {
+    await out.log(out.cli.renderHelp());
+  });
+};
+
+export const runCli = async () => {
+  const out = new plugins.smartconsole.SmartConsole();
+  try {
+    registerCommands(out);
+    await out.cli.run();
+  } catch (error) {
+    await out.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  } finally {
+    await out.dispose();
+  }
+};

package/ts/index.ts

@@ -0,0 +1,3 @@
+export { runCli } from './cli.js';
+export { WccDevServer, type IWccDevServerOptions, type IWccDevServerAddress } from './classes.devserver.js';
+export { WccDevApi } from './classes.devapi.js';

package/ts/paths.ts

@@ -0,0 +1,7 @@
+import * as plugins from './plugins.js';
+
+/** The root of the installed wcctools package. */
+export const packageDir = plugins.path.resolve(plugins.path.dirname(plugins.url.fileURLToPath(import.meta.url)), '..');
+
+/** The prebuilt shell bundle the package ships. */
+export const distShellDir = plugins.path.join(packageDir, 'dist_shell');

package/ts/plugins.ts

@@ -0,0 +1,29 @@
+// node native scope
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as url from 'node:url';
+
+export { fs, path, url };
+
+// @api.global scope
+import * as typedrequest from '@api.global/typedrequest';
+import * as typedserver from '@api.global/typedserver';
+
+export { typedrequest, typedserver };
+
+// @git.zone scope
+import * as tswatch from '@git.zone/tswatch';
+
+export { tswatch };
+
+// @push.rocks scope
+import * as smartconsole from '@push.rocks/smartconsole';
+import * as smartexit from '@push.rocks/smartexit';
+
+export { smartconsole, smartexit };
+
+// project scope
+import * as interfaces from '../ts_interfaces/index.js';
+import * as shared from '../ts_shared/index.js';
+
+export { interfaces, shared };

package/ts/shellcontent.ts

@@ -0,0 +1,42 @@
+import * as plugins from './plugins.js';
+
+/** The path below which the shell surface serves the shell bundle. */
+export const shellPathPrefix = '/wcctools';
+
+const collectFiles = async (dirArg: string, relativeDirArg = ''): Promise<string[]> => {
+  const entries = await plugins.fs.readdir(plugins.path.join(dirArg, relativeDirArg), { withFileTypes: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const relativePath = relativeDirArg ? `${relativeDirArg}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      files.push(...await collectFiles(dirArg, relativePath));
+    } else if (entry.isFile()) {
+      files.push(relativePath);
+    }
+  }
+  return files;
+};
+
+/**
+ * The prebuilt shell bundle as in-memory content of the shell surface. A surface serves files
+ * by their full request path, so every file is keyed below `wcctools/`; the shell page is
+ * also keyed as `index.html`, which the surface's SPA fallback answers `/wcctools-route/...` with.
+ */
+export const loadShellContent = async (distShellDirArg: string): Promise<plugins.typedserver.IBundledContentItem[]> => {
+  const indexPath = plugins.path.join(distShellDirArg, 'index.html');
+  try {
+    await plugins.fs.access(indexPath);
+  } catch {
+    throw new Error(`wcctools: the shell bundle is missing (${indexPath}); build the package with "pnpm build".`);
+  }
+  const prefix = shellPathPrefix.slice(1);
+  const content: plugins.typedserver.IBundledContentItem[] = [];
+  for (const relativePath of await collectFiles(distShellDirArg)) {
+    const contentBase64 = (await plugins.fs.readFile(plugins.path.join(distShellDirArg, relativePath))).toString('base64');
+    content.push({ path: `${prefix}/${relativePath}`, contentBase64 });
+    if (relativePath === 'index.html') {
+      content.push({ path: 'index.html', contentBase64 });
+    }
+  }
+  return content;
+};

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/wcctools',
-  version: '5.1.0',
+  version: '6.0.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;
+  }
+}