noora

import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";

const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const check = process.argv.includes("--check");
const generatedNotice =
  "<!-- Generated by scripts/generate-web-components.js. Do not edit directly. -->";

function fail(message) {
  throw new Error(`Invalid web component contract: ${message}`);
}

function validateContract(contract, filename) {
  for (const key of [
    "name",
    "tagName",
    "elementClassName",
    "className",
    "modulePath",
    "description",
    "usage",
  ]) {
    if (typeof contract[key] !== "string" || contract[key].length === 0) {
      fail(`${filename} must define a non-empty ${key}`);
    }
  }

  if (!contract.tagName.includes("-")) {
    fail(`${filename} tagName must contain a hyphen`);
  }

  for (const key of [
    "attributes",
    "readonlyProperties",
    "slots",
    "cssParts",
    "examples",
  ]) {
    if (!Array.isArray(contract[key])) {
      fail(`${filename} must define ${key} as an array`);
    }
  }

  if (
    contract.notes !== undefined &&
    (!Array.isArray(contract.notes) ||
      contract.notes.some((note) => typeof note !== "string"))
  ) {
    fail(`${filename} notes must be an array of strings`);
  }

  if (
    contract.stylingExample !== undefined &&
    typeof contract.stylingExample !== "string"
  ) {
    fail(`${filename} stylingExample must be a string`);
  }

  const attributeNames = new Set();
  const propertyNames = new Set();

  for (const attribute of contract.attributes) {
    if (!attribute.name || !attribute.property || !attribute.description) {
      fail(
        `${filename} attributes must define name, property, and description`,
      );
    }
    if (!["boolean", "string"].includes(attribute.type)) {
      fail(
        `${filename} attribute ${attribute.name} has unsupported type ${attribute.type}`,
      );
    }
    if (
      attribute.phoenixName !== undefined &&
      typeof attribute.phoenixName !== "string"
    ) {
      fail(`${filename} attribute ${attribute.name} has invalid phoenixName`);
    }
    if (attributeNames.has(attribute.name)) {
      fail(`${filename} defines attribute ${attribute.name} more than once`);
    }
    if (propertyNames.has(attribute.property)) {
      fail(`${filename} defines property ${attribute.property} more than once`);
    }
    if (
      attribute.values &&
      (!Array.isArray(attribute.values) ||
        attribute.values.length === 0 ||
        attribute.values.some((value) => typeof value !== "string"))
    ) {
      fail(`${filename} attribute ${attribute.name} has invalid values`);
    }
    if (
      Object.hasOwn(attribute, "default") &&
      attribute.values &&
      !attribute.values.includes(attribute.default)
    ) {
      fail(
        `${filename} attribute ${attribute.name} default is not an allowed value`,
      );
    }

    attributeNames.add(attribute.name);
    propertyNames.add(attribute.property);
  }

  const exampleIds = new Set();
  for (const example of contract.examples) {
    if (
      !example.id ||
      !example.title ||
      !example.description ||
      !example.markup
    ) {
      fail(
        `${filename} examples must define id, title, description, and markup`,
      );
    }
    if (exampleIds.has(example.id)) {
      fail(`${filename} defines example ${example.id} more than once`);
    }
    exampleIds.add(example.id);
  }
}

function typescriptType(attribute) {
  if (attribute.values) {
    return attribute.values.map((value) => JSON.stringify(value)).join(" | ");
  }
  return attribute.type;
}

function typescriptPropertyType(attribute) {
  const type = typescriptType(attribute);
  return Object.hasOwn(attribute, "default") || attribute.type === "boolean"
    ? type
    : `${type} | undefined`;
}

function markdownCode(value) {
  return `\`${String(value).replaceAll("`", "\\`").replaceAll("|", "\\|")}\``;
}

function markdownCell(value) {
  return String(value).replaceAll("|", "\\|").replaceAll("\n", " ");
}

function defaultText(attribute) {
  if (!Object.hasOwn(attribute, "default")) return "None";
  return markdownCode(JSON.stringify(attribute.default));
}

function allowedValuesText(attribute) {
  if (attribute.type === "boolean") return markdownCode("boolean");
  if (!attribute.values) return markdownCode("string");
  return attribute.values.map(markdownCode).join(", ");
}

function renderTypes(contracts) {
  const blocks = contracts.map((contract) => {
    const slotDocs = contract.slots
      .map(
        (slot) =>
          ` * @slot${slot.name ? ` ${slot.name}` : ""} - ${slot.description}`,
      )
      .join("\n");
    const partDocs = contract.cssParts
      .map((part) => ` * @csspart ${part.name} - ${part.description}`)
      .join("\n");
    const publicAttributes = contract.attributes.filter(
      (attribute) => attribute.publicProperty !== false,
    );
    const fields = [
      ...publicAttributes.map(
        (attribute) =>
          `  /** ${attribute.description} */\n  ${attribute.property}: ${typescriptPropertyType(attribute)};`,
      ),
      ...contract.readonlyProperties.map(
        (property) =>
          `  /** ${property.description} */\n  readonly ${property.name}: ${property.type};`,
      ),
    ].join("\n");

    return `/**
 * ${contract.description}
 *
 * @element ${contract.tagName}
${slotDocs}
${partDocs}
 */
export class ${contract.elementClassName} extends HTMLElement {
${fields}
}

export function register${contract.elementClassName}(): void;`;
  });

  const tagNames = contracts
    .map(
      (contract) => `    "${contract.tagName}": ${contract.elementClassName};`,
    )
    .join("\n");

  return `// Generated by scripts/generate-web-components.js. Do not edit directly.

${blocks.join("\n\n")}

declare global {
  interface HTMLElementTagNameMap {
${tagNames}
  }
}
`;
}

function manifestAttribute(attribute) {
  const result = {
    name: attribute.name,
    description: attribute.description,
    type: { text: typescriptType(attribute) },
  };

  if (attribute.publicProperty !== false) {
    result.fieldName = attribute.property;
  }
  if (Object.hasOwn(attribute, "default")) {
    result.default = JSON.stringify(attribute.default);
  }
  return result;
}

function manifestMember(attribute) {
  const result = {
    kind: "field",
    name: attribute.property,
    description: attribute.description,
    type: { text: typescriptPropertyType(attribute) },
    attribute: attribute.name,
  };
  if (Object.hasOwn(attribute, "default")) {
    result.default = JSON.stringify(attribute.default);
  }
  return result;
}

function renderManifest(contracts) {
  const contractsByModule = new Map();
  for (const contract of contracts) {
    const moduleContracts = contractsByModule.get(contract.modulePath) ?? [];
    moduleContracts.push(contract);
    contractsByModule.set(contract.modulePath, moduleContracts);
  }

  const modules = Array.from(
    contractsByModule,
    ([modulePath, moduleContracts]) => ({
      kind: "javascript-module",
      path: modulePath,
      declarations: moduleContracts.map((contract) => {
        const publicAttributes = contract.attributes.filter(
          (attribute) => attribute.publicProperty !== false,
        );

        return {
          kind: "class",
          description: contract.description,
          name: contract.elementClassName,
          tagName: contract.tagName,
          customElement: true,
          superclass: { name: "LitElement", package: "lit" },
          members: [
            ...publicAttributes.map(manifestMember),
            ...contract.readonlyProperties.map((property) => ({
              kind: "field",
              name: property.name,
              description: property.description,
              type: { text: property.type },
              readonly: true,
            })),
          ],
          attributes: contract.attributes.map(manifestAttribute),
          slots: contract.slots.map((slot) => ({
            ...(slot.name ? { name: slot.name } : {}),
            description: slot.description,
          })),
          cssParts: contract.cssParts.map((part) => ({
            name: part.name,
            description: part.description,
          })),
        };
      }),
      exports: moduleContracts.flatMap((contract) => [
        {
          kind: "js",
          name: contract.elementClassName,
          declaration: {
            name: contract.elementClassName,
            module: modulePath,
          },
        },
        {
          kind: "custom-element-definition",
          name: contract.tagName,
          declaration: {
            name: contract.elementClassName,
            module: modulePath,
          },
        },
      ]),
    }),
  );

  return `${JSON.stringify(
    {
      schemaVersion: "1.0.0",
      readme: "./README.md",
      modules,
    },
    null,
    2,
  )}\n`;
}

function renderComponentDocumentation(contract) {
  const attributes = contract.attributes
    .map(
      (attribute) =>
        `| ${markdownCode(attribute.name)} | ${allowedValuesText(attribute)} | ${defaultText(attribute)} | ${markdownCell(attribute.description)} |`,
    )
    .join("\n");
  const properties = contract.readonlyProperties
    .map(
      (property) =>
        `| ${markdownCode(property.name)} | ${markdownCode(property.type)} | ${markdownCell(property.description)} |`,
    )
    .join("\n");
  const slots = contract.slots
    .map(
      (slot) =>
        `| ${markdownCode(slot.name || "default")} | ${markdownCell(slot.description)} |`,
    )
    .join("\n");
  const parts = contract.cssParts
    .map(
      (part) =>
        `| ${markdownCode(part.name)} | ${markdownCell(part.description)} |`,
    )
    .join("\n");
  const examples = contract.examples
    .map(
      (example) => `## ${example.title}

${example.description}

\`\`\`html
${example.markup}
\`\`\``,
    )
    .join("\n\n");
  const propertiesSection =
    contract.readonlyProperties.length === 0
      ? ""
      : `
## Read-only properties

| Property | Type | Description |
| --- | --- | --- |
${properties}
`;
  const slotsSection =
    contract.slots.length === 0
      ? ""
      : `
## Slots

| Slot | Description |
| --- | --- |
${slots}
`;
  const partsSection =
    contract.cssParts.length === 0
      ? ""
      : `
## Styling parts

| Part | Description |
| --- | --- |
${parts}
`;
  const stylingExample = contract.stylingExample
    ? `
Use the standard \`::part()\` selector when an application needs a targeted override:

\`\`\`css
${contract.stylingExample}
\`\`\`
`
    : "";
  const notes = (contract.notes ?? []).join("\n\n");

  return `${generatedNotice}

# ${contract.name}

${contract.description}

\`\`\`html
${contract.usage}
\`\`\`

## Attributes

| Attribute | Type or allowed values | Default | Description |
| --- | --- | --- | --- |
${attributes}
${propertiesSection}${slotsSection}${partsSection}${stylingExample}
${notes}

${examples}
`;
}

function renderIndexDocumentation(contracts) {
  const components = contracts
    .map(
      (contract) =>
        `- [${contract.name}](./components/${contract.name.toLowerCase()}.md): ${contract.description}`,
    )
    .join("\n");

  return `${generatedNotice}

# Noora web components

Install the public package from the npm package registry:

\`\`\`sh
npm install @tuist/noora
\`\`\`

Import the design tokens and the component registration bundle once in the browser entry point:

\`\`\`javascript
import "@tuist/noora/tokens.css";
import "@tuist/noora/web-components";
\`\`\`

The registration bundle defines every published Noora custom element. The package also includes \`custom-elements.json\` for tools that support the Custom Elements Manifest format and TypeScript declarations for the public element properties.

Component contracts are consumed during the build. Applications do not fetch the contract files at runtime.

## Components

${components}
`;
}

async function loadContracts() {
  const componentsDirectory = path.join(root, "components");
  const filenames = (await readdir(componentsDirectory))
    .filter((filename) => filename.endsWith(".json"))
    .sort();

  return Promise.all(
    filenames.map(async (filename) => {
      const contract = JSON.parse(
        await readFile(path.join(componentsDirectory, filename), "utf8"),
      );
      validateContract(contract, filename);
      return contract;
    }),
  );
}

async function emit(relativePath, content) {
  const absolutePath = path.join(root, relativePath);
  if (check) {
    let existing;
    try {
      existing = await readFile(absolutePath, "utf8");
    } catch {
      process.stderr.write(`${relativePath} is missing\n`);
      process.exitCode = 1;
      return;
    }
    if (existing !== content) {
      process.stderr.write(`${relativePath} is stale\n`);
      process.exitCode = 1;
    }
    return;
  }

  await mkdir(path.dirname(absolutePath), { recursive: true });
  await writeFile(absolutePath, content);
}

const contracts = await loadContracts();

await emit("types/web-components.d.ts", renderTypes(contracts));
await emit("custom-elements.json", renderManifest(contracts));
await emit("docs/web-components.md", renderIndexDocumentation(contracts));

for (const contract of contracts) {
  await emit(
    `docs/components/${contract.name.toLowerCase()}.md`,
    renderComponentDocumentation(contract),
  );
}