@siemens/ix-docs 0.0.0-pr-2238-20251103095443

package/scripts/collector/util.ts

@@ -0,0 +1,111 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Siemens AG
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import fs from 'fs-extra';
+import path from 'node:path';
+
+export function getExampleNameFromRelativePath(relativeExamplePath: string) {
+  const lastSegment = relativeExamplePath.split('/').pop();
+  if (!lastSegment) {
+    throw new Error(`Invalid example path: ${relativeExamplePath}`);
+  }
+  return lastSegment.replace('.html', '');
+}
+
+/*
+ * Generic helpers to de-duplicate logic across framework example collectors.
+ */
+export type BuildExampleFn = (
+  exampleName: string,
+  relativeExamplePath: string
+) => Promise<{ exampleName: string; example: string } | null>;
+
+/**
+ * Read and parse the usage JSON file which maps component tags to arrays of example paths.
+ */
+export async function readUsageJson(
+  componentUsageJsonPath: string
+): Promise<Record<string, string[]>> {
+  const exampleUsage = await fs.readFile(componentUsageJsonPath, 'utf-8');
+  return JSON.parse(exampleUsage) as Record<string, string[]>;
+}
+
+/**
+ * Collect examples for a tag using a provided build function.
+ * The build function is responsible for locating files and returning a markdown body.
+ */
+export async function collectExamplesForTag(
+  usageJsonPath: string,
+  tag: string,
+  buildExample: BuildExampleFn
+): Promise<string> {
+  const usage = await readUsageJson(usageJsonPath);
+  const examples = usage[tag];
+
+  if (!examples) {
+    console.log(`No examples found for ${tag}`);
+    return '';
+  }
+
+  const markdown: string[] = [];
+
+  for (const relativeExamplePath of examples) {
+    const exampleName = getExampleNameFromRelativePath(relativeExamplePath);
+    const built = await buildExample(exampleName, relativeExamplePath);
+    if (!built) continue; // build function logged reason (e.g., file not found)
+    markdown.push(
+      [`### Example: ${built.exampleName}`, built.example].join('\n')
+    );
+  }
+
+  return markdown.join('\n\n');
+}
+
+/**
+ * Helper to read file content if it exists; returns null when missing.
+ */
+export async function readIfExists(filePath: string): Promise<string | null> {
+  if (!fs.existsSync(filePath)) return null;
+  return fs.readFile(filePath, 'utf-8');
+}
+
+/**
+ * Compose fenced code blocks conveniently.
+ */
+export function fenced(lang: string, code: string): string {
+  return ['```' + lang, code, '```'].join('\n');
+}
+
+/**
+ * Build an example made of multiple named sections (e.g., Typescript / HTML / CSS)
+ */
+export function sectionedExample(
+  sections: Array<{
+    heading: string;
+    lang: string;
+    code: string | null;
+  }>
+): string {
+  return sections
+    .filter((s) => s.code)
+    .map((s) =>
+      [`#### ${s.heading}`, fenced(s.lang, s.code as string)].join('\n')
+    )
+    .join('\n');
+}
+
+/**
+ * Resolve a file by base name + extension inside a root directory.
+ */
+export function resolveExampleFile(
+  root: string,
+  exampleBaseName: string,
+  extension: string
+): string {
+  return path.join(root, `${exampleBaseName}.${extension}`);
+}

package/scripts/templates/api.mustache

@@ -0,0 +1,24 @@
+import {SinceTag, DeprecatedTag} from '@site/src/components/UI/Tags';
+import FrameworkSelection from '@site/src/components/UI/FrameworkSelection';
+import ApiTable from '@site/src/components/ApiTable';
+import ReactMarkdown from 'react-markdown';
+
+## API for {{ tag }}{{#singleFramework}} ({{{ framework }}}){{/singleFramework}}
+
+{{#hasProps}}
+### Properties
+
+{{{ properties }}}
+{{/hasProps}}
+
+{{#hasEvents}}
+### Events
+
+{{{ events }}}
+{{/hasEvents}}
+
+{{#hasSlots}}
+### Slot
+
+{{{ slots }}}
+{{/hasSlots}}

package/scripts/templates/event-table.mustache

@@ -0,0 +1,21 @@
+{{#events}}
+<ApiTable id="event-{{event}}">
+  <ApiTable.EventHeader name="{{event}}">
+    {{#docsTags}}
+      {{{ rTag }}}
+    {{/docsTags}}
+  </ApiTable.EventHeader>
+
+  <ApiTable.Text name="Description">
+    <ReactMarkdown>{`{{{ docs }}}`}</ReactMarkdown>
+  </ApiTable.Text>
+
+  <ApiTable.Code name="Event">
+    {`{{{ event }}}`}
+  </ApiTable.Code>
+
+  <ApiTable.Code name="Detail">
+    {`{{{ detail }}}`}
+  </ApiTable.Code>
+</ApiTable>
+{{/events}}

package/scripts/templates/playground-files.mustache

@@ -0,0 +1,25 @@
+react: {
+<%#react%>
+  '<%key%>': '<%{value}%>',
+<%/react%>
+},
+angular: {
+<%#angular%>
+  '<%key%>': '<%{value}%>',
+<%/angular%>
+},
+angular_standalone: {
+<%#angular_standalone%>
+  '<%key%>': '<%{value}%>',
+<%/angular_standalone%>
+},
+vue: {
+<%#vue%>
+  '<%key%>': '<%{value}%>',
+<%/vue%>
+},
+html: {
+<%#html%>
+  '<%key%>': '<%{value}%>',
+<%/html%>
+}

package/scripts/templates/playground-markdown.mustache

@@ -0,0 +1,25 @@
+react: {
+<%#reactMarkdown%>
+  '<%key%>': <%{value}%>,
+<%/reactMarkdown%>
+},
+angular: {
+<%#angularMarkdown%>
+  '<%key%>': <%{value}%>,
+<%/angularMarkdown%>
+},
+angular_standalone: {
+<%#angularStandaloneMarkdown%>
+  '<%key%>': <%{value}%>,
+<%/angularStandaloneMarkdown%>
+},
+vue: {
+<%#vueMarkdown%>
+  '<%key%>': <%{value}%>,
+<%/vueMarkdown%>
+},
+html: {
+<%#htmlMarkdown%>
+  '<%key%>': <%{value}%>,
+<%/htmlMarkdown%>
+}

package/scripts/templates/playground.mustache

@@ -0,0 +1,14 @@
+import Playground from '@site/src/components/Playground'
+
+<%#imports%>
+<%{.}%>
+<%/imports%>
+
+<Playground
+  name="<%name%>"
+  <%#isPreviewAvailable%>noPreview<%/isPreviewAvailable%>
+  source={{<%> markdown%>}}
+  files={{<%> files%>}}
+  height={props.height}
+  onlyFramework={props.onlyFramework}
+></Playground>

package/scripts/templates/property-table.mustache

@@ -0,0 +1,30 @@
+{{#props}}
+<ApiTable id="property-{{name}}">
+  <ApiTable.PropertyHeader name="{{name}}" singleFramework="{{singleFramework}}">
+    {{#docsTags}}
+      {{{ rTag }}}
+    {{/docsTags}}
+  </ApiTable.PropertyHeader>
+
+  <ApiTable.Text name="Description">
+    <ReactMarkdown>{`{{{ docs }}}`}</ReactMarkdown>
+  </ApiTable.Text>
+
+  {{#attr}}
+  <ApiTable.Code name="Attribute">
+    {`{{{ attr }}}`}
+  </ApiTable.Code>
+  {{/attr}}
+
+  <ApiTable.Code name="Type">
+   {`{{{ type }}}`}
+  </ApiTable.Code>
+
+  {{#default}}
+  <ApiTable.Code name="Default">
+    {`{{{ default }}}`}
+  </ApiTable.Code>
+  {{/default}}
+
+</ApiTable>
+{{/props}}

package/scripts/templates/slot-table.mustache

@@ -0,0 +1,14 @@
+{{#slots}}
+<ApiTable id="slot-{{name}}">
+  <ApiTable.SlotHeader name="{{name}}">
+    {{#docsTags}}
+      {{{ rTag }}}
+    {{/docsTags}}
+  </ApiTable.SlotHeader>
+
+  <ApiTable.Text name="Description">
+    <ReactMarkdown>{ `{{{ docs }}}` }</ReactMarkdown>
+  </ApiTable.Text>
+</ApiTable>
+{{/slots}}
+

package/scripts/templates/tags.mustache

@@ -0,0 +1,9 @@
+import {
+  SinceTag,
+  DeprecatedTag,
+  FormReady,
+} from '@site/src/components/UI/Tags';
+
+{{#docsTags}}
+{{{ rTag }}}
+{{/docsTags}}

package/scripts/templates/usage.mustache

@@ -0,0 +1,3 @@
+```{{type}}
+{{{code}}}
+```

package/scripts/typedoc-generator.ts

@@ -0,0 +1,307 @@
+/**
+ * SPDX-FileCopyrightText: 2024 Siemens AG
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import path from 'path';
+import fs from 'fs-extra';
+import Mustache from 'mustache';
+import {
+  Application,
+  IntrinsicType,
+  ReferenceType,
+  TSConfigReader,
+  UnionType,
+} from 'typedoc';
+import { toKebabCase } from './utils/string-utils';
+
+export type TypeDocTarget = {
+  name: string;
+  properties: TypeDocProperty[];
+  type: 'Function' | 'Type';
+  source: string;
+};
+
+export type TypeDocProperty = {
+  name: string;
+  defaultValue?: string;
+  type: string;
+  comment: string;
+  tags: Array<{ tag: string; text?: string }>;
+};
+
+async function generateDocsForEntrypoint(
+  entrypoint: string,
+  targetPath: string
+) {
+  const __root = path.resolve(__dirname, '../');
+  const __templates = path.join(__dirname, 'templates');
+  const tsconfig = path.join(
+    __dirname,
+    '..',
+    '..',
+    '..',
+    'tsconfig.typedoc.json'
+  );
+
+  const app = await Application.bootstrap({
+    tsconfig: tsconfig,
+    skipErrorChecking: true,
+    entryPoints: [entrypoint],
+  });
+
+  app.options.addReader(new TSConfigReader());
+
+  const project = await app.convert();
+
+  if (!project) {
+    throw new Error(`No project generated for ${entrypoint}`);
+  }
+
+  const types = processProjectChildren(project, __root);
+  await generateTypeDocs(types, targetPath, __templates);
+}
+
+function getPropertyType(property: any): string {
+  if (property.type instanceof IntrinsicType) {
+    return property.type.name;
+  } else if (property.type instanceof ReferenceType) {
+    return property.type.qualifiedName;
+  } else if (property.type instanceof UnionType) {
+    return property.type.types
+      .filter((t: any) => 'name' in t)
+      .map((t: any) => t.name)
+      .join(' | ');
+  } else {
+    console.log(`=== Type ${property.name} is unknown`);
+    return 'unknown';
+  }
+}
+
+function extractCommentTags(
+  property: any
+): Array<{ tag: string; text?: string }> {
+  const tags: Array<{ tag: string; text?: string }> = [];
+
+  if (!property.comment?.blockTags) {
+    return tags;
+  }
+
+  for (const tag of property.comment.blockTags) {
+    const tagName = tag.tag.substring(1); // Remove @ symbol
+    const tagText = tag.content
+      .filter((content: any) => content.kind === 'text')
+      .map((content: any) => content.text)
+      .join('');
+
+    tags.push({ tag: tagName, text: tagText });
+  }
+
+  return tags;
+}
+
+function getCommentSummary(property: any): string {
+  const summary =
+    property?.comment?.summary ?? property?.signatures?.[0]?.comment?.summary;
+
+  if (summary) {
+    return summary
+      .filter((summary: any) => summary.kind === 'text')
+      .map((summary: any) => summary.text)
+      .join('');
+  }
+
+  return '';
+}
+
+function processProperties(child: any): TypeDocProperty[] {
+  const properties: TypeDocProperty[] = [];
+
+  if (!child?.children) {
+    return properties;
+  }
+
+  for (const property of child.children) {
+    const type = getPropertyType(property);
+    const tags = extractCommentTags(property);
+    const comment = getCommentSummary(property);
+
+    properties.push({
+      name: property.name,
+      defaultValue: property.defaultValue,
+      type,
+      comment,
+      tags,
+    });
+  }
+
+  return properties;
+}
+
+function processProjectChildren(
+  project: any,
+  rootPath: string
+): TypeDocTarget[] {
+  const types: TypeDocTarget[] = [];
+
+  if (!project.children) {
+    return types;
+  }
+
+  for (const child of project.children) {
+    const source = path.relative(rootPath, child.sources![0].fullFileName);
+
+    const properties = processProperties(child);
+
+    types.push({
+      name: child.name,
+      properties,
+      type: 'Type',
+      source,
+    });
+  }
+
+  return types;
+}
+
+function determineFramework(source: string): string | undefined {
+  const frameworks = ['react', 'angular', 'vue'];
+
+  for (const framework of frameworks) {
+    if (source.includes(framework)) {
+      return framework;
+    }
+  }
+
+  return undefined;
+}
+
+async function generateTypeDocs(
+  types: TypeDocTarget[],
+  targetPath: string,
+  templatesPath: string
+) {
+  const utilsPath = path.join(targetPath, 'utils');
+  await fs.ensureDir(utilsPath);
+
+  for (const typedoc of types) {
+    const current_framework = determineFramework(typedoc.source);
+    const mdxContent = generateStructuredMDX(
+      typedoc,
+      templatesPath,
+      current_framework
+    );
+
+    const outputPath = path.join(utilsPath, `${toKebabCase(typedoc.name)}.mdx`);
+    console.log(`Generating TypeDoc: ${outputPath}`);
+    await fs.writeFile(outputPath, mdxContent);
+
+    if (global.gc) {
+      global.gc();
+    }
+  }
+}
+
+function convertTagsToTSXElements(tags: Array<{ tag: string; text?: string }>) {
+  return tags
+    .map((tag) => {
+      if (tag.tag === 'deprecated') {
+        return {
+          rTag: `<DeprecatedTag message={\`${escapeBackticks(
+            tag.text || ''
+          )}\`} />`,
+        };
+      } else if (tag.tag === 'since') {
+        return {
+          rTag: `<SinceTag version={\`${escapeBackticks(tag.text || '')}\`} />`,
+        };
+      }
+      return null;
+    })
+    .filter(Boolean);
+}
+
+function generateStructuredMDX(
+  typedoc: TypeDocTarget,
+  templatesPath: string,
+  framework?: string
+): string {
+  const propertyTemplate = fs.readFileSync(
+    path.join(templatesPath, 'property-table.mustache'),
+    'utf-8'
+  );
+  const apiTemplate = fs.readFileSync(
+    path.join(templatesPath, 'api.mustache'),
+    'utf-8'
+  );
+
+  const kebabName = `ix-${toKebabCase(typedoc.name)}`;
+
+  const formattedProps = typedoc.properties.map((prop) => {
+    return {
+      name: prop.name,
+      singleFramework: framework,
+      docs: escapeBackticks(prop.comment),
+      type: escapeBackticks(prop.type),
+      default: prop.defaultValue
+        ? escapeBackticks(prop.defaultValue)
+        : undefined,
+      attr: prop.name,
+      docsTags: convertTagsToTSXElements(prop.tags),
+    };
+  });
+
+  const propertyOutput = Mustache.render(propertyTemplate, {
+    tag: kebabName,
+    props: formattedProps,
+  });
+
+  return Mustache.render(apiTemplate, {
+    tag: kebabName,
+    hasProps: typedoc.properties.length > 0,
+    hasEvents: false,
+    hasSlots: false,
+    singleFramework: framework,
+    framework: framework?.charAt(0).toUpperCase()! + framework?.slice(1),
+    properties: propertyOutput,
+    events: '',
+    slots: '',
+  });
+}
+
+function escapeBackticks(str: string): string {
+  if (!str) return '';
+  return str.replace(/`/g, '\\`');
+}
+
+export async function generateTypeScriptDocs(
+  classPaths: string[],
+  targetPath: string
+) {
+  console.log('Generating TypeScript API docs');
+
+  const BATCH_SIZE = 5;
+  const batches = [];
+
+  for (let i = 0; i < classPaths.length; i += BATCH_SIZE) {
+    batches.push(classPaths.slice(i, i + BATCH_SIZE));
+  }
+
+  for (let i = 0; i < batches.length; i++) {
+    const batch = batches[i];
+    console.log(
+      `Processing batch ${i + 1}/${batches.length} (${batch.length} files)`
+    );
+    for (const classPath of batch) {
+      await generateDocsForEntrypoint(classPath, targetPath);
+
+      if (global.gc) {
+        global.gc();
+      }
+    }
+  }
+}

package/scripts/utils/docs-tags.ts

@@ -0,0 +1,43 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Siemens AG
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { escapeMarkdown } from './escape';
+
+export function convertDocsTagsToTSXElement(
+  tagName: string,
+  docsTags: {
+    name: string;
+    text?: string;
+  }[]
+) {
+  return docsTags.map((tag) => {
+    const { name, text } = tag;
+    const escapedText = escapeMarkdown(text ?? '').replace(/`/g, '\\`');
+    let template = '';
+    if (name === 'since') {
+      template = `<SinceTag message={\`${escapedText}\`} />`;
+    }
+
+    if (name === 'deprecated') {
+      template = `<DeprecatedTag message={\`${escapedText}\`} />`;
+    }
+
+    if (name === 'form-ready') {
+      template = `<FormReady message={\`${escapedText}\`} />`;
+    }
+
+    if (template === '') {
+      console.warn(`Unknown tag: ${name} within ${tagName}`);
+    }
+
+    return {
+      rTag: template,
+    };
+  });
+}

package/scripts/utils/escape.ts

@@ -0,0 +1,54 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Siemens AG
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export function escapeMarkdown(markdown: string) {
+  let replacedMarkdown = markdown;
+  const replacemenets: [RegExp, string][] = [
+    [/`/g, '\\`'],
+    [/\*/g, '\\*'],
+    [/#/g, '\\#'],
+    [/\//g, '\\/'],
+    [/\(/g, '\\('],
+    [/\)/g, '\\)'],
+    [/\[/g, '\\['],
+    [/\]/g, '\\]'],
+    [/</g, '&lt;'],
+    [/>/g, '&gt;'],
+    [/_/g, '\\_'],
+    [/`/g, '\\`'],
+    [/\|/g, '\uff5c'],
+  ];
+
+  replacemenets.forEach((replace) => {
+    const [source, target] = replace;
+    replacedMarkdown = markdown.replace(source, target);
+  });
+
+  return replacedMarkdown;
+}
+
+export function removeTypescriptHeaderComments(str: string) {
+  return str.replaceAll(/\/\*[\s\S]*?\*\//g, '');
+}
+
+export function removeHTMLComments(str: string) {
+  return str.replaceAll(/<!--[\s\S]*?-->/g, '');
+}
+
+export function parseJSDocsToMarkdown(str: string) {
+  const linkRegex = /{\@link (.*?)}/g;
+  const markdown = str.replaceAll(linkRegex, (_, url) => {
+    return `[${url}](${url})`;
+  });
+
+  return markdown;
+}
+
+export function escapeBackticks(str: string) {
+  return str.replaceAll(/`/g, '\\`');
+}

package/scripts/utils/string-utils.ts

@@ -0,0 +1,7 @@
+export function toKebabCase(input: string) {
+  return input
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+    .trim()
+    .toLowerCase();
+}