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

package/scripts/build.ts

@@ -0,0 +1,529 @@
+/*
+ * 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, { writeFile } from 'fs-extra';
+import Mustache from 'mustache';
+import componentDoc from '@siemens/ix/component-doc.json';
+import { convertDocsTagsToTSXElement } from './utils/docs-tags';
+import { generateTypeScriptDocs } from './typedoc-generator';
+import { escapeBackticks, parseJSDocsToMarkdown } from './utils/escape';
+import { collectHTMLExamples } from './collector/collectHTMLExamples';
+import { collectReactExamples } from './collector/collectReactExamples';
+import { collectVueExamples } from './collector/collectVueExamples';
+import { collectAngularExamples } from './collector/collectAngularExamples';
+
+type OutputType = 'html' | 'react' | 'angular' | 'angular_standalone' | 'vue';
+
+const version = 'v2';
+
+const __root = path.resolve(__dirname, '../');
+
+const __core = path.join(__dirname, '../node_modules', '@siemens', 'ix');
+const __packages = path.join(__dirname, '../node_modules');
+
+const __htmlTestAppRoot = path.join(__packages, 'html-test-app');
+const __htmlTestAppDist = path.join(__htmlTestAppRoot, 'dist');
+
+const __mobileTestAppDist = path.join(__packages, 'ionic-test-app', 'dist');
+
+const __htmlTestApp = path.join(
+  __packages,
+  'html-test-app',
+  'src',
+  'preview-examples'
+);
+
+const __reactTestAppRoot = path.join(__packages, 'react-test-app');
+const __reactTestApp = path.join(__reactTestAppRoot, 'src', 'preview-examples');
+
+const __angularTestApp = path.join(
+  __packages,
+  'angular-test-app',
+  'src',
+  'preview-examples'
+);
+const __angularStandaloneTestApp = path.join(
+  __packages,
+  'angular-standalone-test-app',
+  'src',
+  'preview-examples'
+);
+const __vueTestApp = path.join(
+  __packages,
+  'vue-test-app',
+  'src',
+  'preview-examples'
+);
+
+const __storybookStatic = path.join(
+  __packages,
+  'storybook-docs',
+  'storybook-static'
+);
+
+const __build = path.join(__root, 'build');
+
+const __docs = path.join(__build, 'docs');
+const __autogenerated = path.join(__docs, 'autogenerated');
+const __autogeneratedPrompt = path.join(__autogenerated, 'prompt');
+const __autogeneratedApi = path.join(__autogenerated, 'api');
+const __autogeneratedPlayground = path.join(__autogenerated, 'playground');
+const __autogeneratedUtils = path.join(__autogenerated, 'utils');
+const __changelog = path.join(__docs, 'home', 'releases', 'changelog.md');
+
+const __static = path.join(__build, 'static');
+const __demo = path.join(__static, 'demo', version);
+const __preview = path.join(__demo, 'preview');
+const __previewHtml = path.join(__preview, 'html');
+const __previewStorybook = path.join(__static, 'storybook-static');
+
+const __exampleCodeHtml = path.join(__demo, 'html');
+
+export const __componentUsageByComponentJson = path.join(
+  __htmlTestAppRoot,
+  'component-usage-by-component.json'
+);
+
+const __usage = path.join(__autogenerated, 'usage');
+
+const __templates = path.join(__dirname, 'templates');
+
+function kebabToCamelCase(str: string): string {
+  return str
+    .toLowerCase()
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('');
+}
+
+async function copyStaticFiles() {
+  console.log('Copying demo source');
+
+  fs.copyFileSync(
+    path.join(__htmlTestAppRoot, 'component-usage.json'),
+    path.join(__build, 'component-usage.json')
+  );
+
+  fs.copyFileSync(
+    __componentUsageByComponentJson,
+    path.join(__build, 'component-usage-by-component.json')
+  );
+
+  fs.copySync(__htmlTestAppDist, __previewHtml);
+  fs.copySync(__mobileTestAppDist, path.join(__demo, 'preview', 'mobile'));
+
+  fs.copySync(__htmlTestApp, __exampleCodeHtml);
+  fs.copySync(__reactTestApp, path.join(__demo, 'react'));
+  fs.copySync(__angularTestApp, path.join(__demo, 'angular'));
+  fs.copySync(
+    __angularStandaloneTestApp,
+    path.join(__demo, 'angular_standalone')
+  );
+  fs.copySync(__vueTestApp, path.join(__demo, 'vue'));
+}
+
+async function copyUsage() {
+  console.log('Generate usage markdown');
+
+  function stripComments(code: string) {
+    return code
+      .replace(/\/\*[^]*?\*\//gs, '')
+      .replace(/<!--[^]*?-->/gs, '')
+      .trim();
+  }
+
+  function generateSourceCodeMarkdown(testAppPath: string, type: OutputType) {
+    fs.readdirSync(testAppPath).forEach((file) => {
+      if (file.match(/.*.(html|css|tsx|ts|vue)/)) {
+        const code = stripComments(
+          fs.readFileSync(path.join(testAppPath, file), 'utf-8')
+        );
+        const fileType = file.split('.').pop();
+
+        const output = Mustache.render(
+          fs.readFileSync(path.join(__templates, 'usage.mustache'), 'utf-8'),
+          {
+            code,
+            type: fileType,
+          }
+        );
+
+        fs.ensureDirSync(path.join(__usage, type));
+        fs.writeFileSync(path.join(__usage, type, `${file}.md`), output);
+      }
+    });
+  }
+
+  generateSourceCodeMarkdown(__htmlTestApp, 'html');
+  generateSourceCodeMarkdown(__reactTestApp, 'react');
+  generateSourceCodeMarkdown(__angularTestApp, 'angular');
+  generateSourceCodeMarkdown(__angularStandaloneTestApp, 'angular_standalone');
+  generateSourceCodeMarkdown(__vueTestApp, 'vue');
+}
+
+async function generatePlaygroundMarkdown(extendedPlayground: string[] = []) {
+  const __playgroundTemplate = path.join(__templates, 'playground.mustache');
+  const playgroundFilesTemplate = fs.readFileSync(
+    path.join(__templates, 'playground-files.mustache'),
+    'utf-8'
+  );
+  const playgroundMarkdownTemplate = fs.readFileSync(
+    path.join(__templates, 'playground-markdown.mustache'),
+    'utf-8'
+  );
+  const playgroundTemplate = fs.readFileSync(__playgroundTemplate, 'utf-8');
+
+  const files = await fs.readdir(__htmlTestApp);
+  const demoFiles = files.filter((file) => file.endsWith('.html'));
+
+  extendedPlayground = extendedPlayground.map((f) => f + '.html');
+
+  for (const file of [...demoFiles, ...extendedPlayground]) {
+    const reactFiles: Record<string, string> = {};
+    const angularFiles: Record<string, string> = {};
+    const angularStandaloneFiles: Record<string, string> = {};
+    const vueFiles: Record<string, string> = {};
+    const htmlFiles: Record<string, string> = {};
+
+    let isPreviewAvailable = false;
+
+    const name = file.replace('.html', '');
+
+    const imports: string[] = [];
+
+    if (fs.existsSync(path.join(__reactTestApp, `${name}.tsx`))) {
+      reactFiles[`${name}.tsx`] = `react/${name}.tsx`;
+    }
+
+    if (fs.existsSync(path.join(__reactTestApp, `${name}.scoped.css`))) {
+      reactFiles[`${name}.scoped.css`] = `react/${name}.scoped.css`;
+    }
+
+    if (fs.existsSync(path.join(__angularTestApp, `${name}.ts`))) {
+      angularFiles[`${name}.ts`] = `angular/${name}.ts`;
+    }
+
+    if (fs.existsSync(path.join(__angularTestApp, `${name}.html`))) {
+      angularFiles[`${name}.html`] = `angular/${name}.html`;
+    }
+
+    if (fs.existsSync(path.join(__angularTestApp, `${name}.css`))) {
+      angularFiles[`${name}.css`] = `angular/${name}.css`;
+    }
+
+    if (fs.existsSync(path.join(__angularStandaloneTestApp, `${name}.ts`))) {
+      angularStandaloneFiles[`${name}.ts`] = `angular_standalone/${name}.ts`;
+    }
+
+    if (fs.existsSync(path.join(__angularStandaloneTestApp, `${name}.html`))) {
+      angularStandaloneFiles[
+        `${name}.html`
+      ] = `angular_standalone/${name}.html`;
+    }
+
+    if (fs.existsSync(path.join(__angularStandaloneTestApp, `${name}.css`))) {
+      angularStandaloneFiles[`${name}.css`] = `angular_standalone/${name}.css`;
+    }
+
+    if (fs.existsSync(path.join(__vueTestApp, `${name}.vue`))) {
+      vueFiles[`${name}.vue`] = `vue/${name}.vue`;
+    }
+
+    if (fs.existsSync(path.join(__vueTestApp, `${name}.css`))) {
+      vueFiles[`${name}.css`] = `vue/${name}.css`;
+    }
+
+    if (fs.existsSync(path.join(__htmlTestApp, `${name}.html`))) {
+      htmlFiles[`${name}.html`] = `html/${name}.html`;
+      isPreviewAvailable = true;
+    }
+
+    if (fs.existsSync(path.join(__htmlTestApp, `${name}.css`))) {
+      htmlFiles[`${name}.css`] = `html/${name}.css`;
+    }
+
+    function collectMarkdownImports(
+      files: Record<string, string>,
+      type: OutputType
+    ) {
+      Object.keys(files).forEach((key) => {
+        const importStatement = `import ${kebabToCamelCase(
+          key.replaceAll('.', '_')
+        )}_${type} from '@site/docs/autogenerated/usage/${type}/${key}.md';`;
+        imports.push(importStatement);
+      });
+    }
+
+    collectMarkdownImports(reactFiles, 'react');
+    collectMarkdownImports(angularFiles, 'angular');
+    collectMarkdownImports(angularStandaloneFiles, 'angular_standalone');
+    collectMarkdownImports(vueFiles, 'vue');
+    collectMarkdownImports(htmlFiles, 'html');
+
+    function mapValues(files: Record<string, string>) {
+      return Object.keys(files).map((key) => ({
+        key,
+        value: files[key],
+      }));
+    }
+
+    function mapMarkdownImports(
+      files: Record<string, string>,
+      type: OutputType
+    ) {
+      return Object.keys(files).map((key) => ({
+        key,
+        value: `${kebabToCamelCase(key.replaceAll('.', '_'))}_${type}`,
+      }));
+    }
+
+    const view = {
+      name,
+      imports,
+      isPreviewAvailable: !isPreviewAvailable,
+      react: mapValues(reactFiles),
+      angular: mapValues(angularFiles),
+      angular_standalone: mapValues(angularStandaloneFiles),
+      vue: mapValues(vueFiles),
+      html: mapValues(htmlFiles),
+
+      reactMarkdown: mapMarkdownImports(reactFiles, 'react'),
+      angularMarkdown: mapMarkdownImports(angularFiles, 'angular'),
+      angularStandaloneMarkdown: mapMarkdownImports(
+        angularStandaloneFiles,
+        'angular_standalone'
+      ),
+      vueMarkdown: mapMarkdownImports(vueFiles, 'vue'),
+      htmlMarkdown: mapMarkdownImports(htmlFiles, 'html'),
+    };
+
+    const output = Mustache.render(
+      playgroundTemplate,
+      view,
+      {
+        files: playgroundFilesTemplate,
+        markdown: playgroundMarkdownTemplate,
+      },
+      {
+        tags: ['<%', '%>'],
+      }
+    );
+
+    await fs.ensureDir(__autogeneratedPlayground);
+
+    await fs.writeFile(
+      path.join(__autogeneratedPlayground, `${name}.mdx`),
+      output
+    );
+  }
+}
+
+async function generateApiMarkdown() {
+  const components = componentDoc.components;
+
+  const __propertyTemplate = path.join(__templates, 'property-table.mustache');
+  const __eventTemplate = path.join(__templates, 'event-table.mustache');
+  const __slotTemplate = path.join(__templates, 'slot-table.mustache');
+  const __apiTemplate = path.join(__templates, 'api.mustache');
+  const __tagsTemplate = path.join(__templates, 'tags.mustache');
+  const propertyTemplate = fs.readFileSync(__propertyTemplate, 'utf-8');
+  const eventTemplate = fs.readFileSync(__eventTemplate, 'utf-8');
+  const slotTemplate = fs.readFileSync(__slotTemplate, 'utf-8');
+  const apiTemplate = fs.readFileSync(__apiTemplate, 'utf-8');
+  const tagsTemplate = fs.readFileSync(__tagsTemplate, 'utf-8');
+
+  for (const component of components) {
+    const { props, events, slots } = component;
+
+    const propertyOutput = Mustache.render(propertyTemplate, {
+      tag: component.tag,
+      props: props.map((prop) => ({
+        ...prop,
+        docsTags: convertDocsTagsToTSXElement(component.tag, prop.docsTags),
+        docs: parseJSDocsToMarkdown(escapeBackticks(prop.docs)),
+      })),
+    });
+
+    const eventOutput = Mustache.render(eventTemplate, {
+      tag: component.tag,
+      events: events.map((event) => ({
+        ...event,
+        docsTags: convertDocsTagsToTSXElement(component.tag, event.docsTags),
+        docs: parseJSDocsToMarkdown(escapeBackticks(event.docs)),
+      })),
+    });
+
+    const slotOutput = Mustache.render(slotTemplate, {
+      slots: slots.map((tag) => ({
+        ...tag,
+        docsTags: convertDocsTagsToTSXElement(component.tag, []),
+        docs: parseJSDocsToMarkdown(escapeBackticks(tag.docs)),
+      })),
+    });
+
+    const tagsOutput = Mustache.render(tagsTemplate, {
+      docsTags: convertDocsTagsToTSXElement(component.tag, component.docsTags),
+    });
+
+    const apiOutput = Mustache.render(apiTemplate, {
+      tag: component.tag,
+      hasSlots: slots.length > 0,
+      hasEvents: events.length > 0,
+      hasProps: props.length > 0,
+      properties: propertyOutput,
+      events: eventOutput,
+      slots: slotOutput,
+    });
+
+    const __component = path.join(__autogeneratedApi, component.tag);
+    await fs.ensureDir(__component);
+    await fs.writeFile(path.join(__component, `props.mdx`), propertyOutput);
+    await fs.writeFile(path.join(__component, `events.mdx`), eventOutput);
+    await fs.writeFile(path.join(__component, `slots.mdx`), slotOutput);
+    await fs.writeFile(path.join(__component, `api.mdx`), apiOutput);
+    await fs.writeFile(path.join(__component, `tags.mdx`), tagsOutput);
+  }
+}
+
+async function copyStorybook() {
+  await fs.copy(__storybookStatic, __previewStorybook, { overwrite: true });
+}
+
+async function copyComponentReadme() {
+  const components = componentDoc.components;
+
+  for (const component of components) {
+    const readmePath = path.join(__core, component.filePath, '..', 'readme.md');
+    const readme = await fs.readFile(readmePath, 'utf-8');
+
+    await fs.ensureDir(path.join(__autogeneratedPrompt, component.tag));
+
+    const htmlExampleMarkdown = await collectHTMLExamples(
+      __componentUsageByComponentJson,
+      __htmlTestAppRoot,
+      component.tag
+    );
+
+    const reactExampleMarkdown = await collectReactExamples(
+      __componentUsageByComponentJson,
+      __reactTestApp,
+      component.tag
+    );
+
+    const vueExampleMarkdown = await collectVueExamples(
+      __componentUsageByComponentJson,
+      __vueTestApp,
+      component.tag
+    );
+
+    const angularExampleMarkdown = await collectAngularExamples(
+      __componentUsageByComponentJson,
+      __angularTestApp,
+      component.tag
+    );
+
+    const angularStandaloneExampleMarkdown = await collectAngularExamples(
+      __componentUsageByComponentJson,
+      __angularStandaloneTestApp,
+      component.tag
+    );
+
+    const exampleMarkdown = [
+      `## HTML Examples\n\n${htmlExampleMarkdown}`,
+      `## React Examples\n\n${reactExampleMarkdown}`,
+      `## Vue Examples\n\n${vueExampleMarkdown}`,
+      `## Angular Examples\n\n${angularExampleMarkdown}`,
+      `## Angular Standalone Examples\n\n${angularStandaloneExampleMarkdown}`,
+    ].join('\n\n');
+
+    await fs.writeFile(
+      path.join(__autogeneratedPrompt, component.tag, 'readme.md'),
+      readme.replace(
+        `# ${component.tag}`,
+        `# ${component.tag}\n\n${exampleMarkdown}`
+      )
+    );
+  }
+}
+
+async function writeLibraryVersion() {
+  const pkgPath = path.join(__core, 'package.json');
+  const version = fs.readJSONSync(pkgPath).version;
+  await writeFile(
+    path.join(__autogenerated, 'version.json'),
+    JSON.stringify({ version })
+  );
+}
+
+(async () => {
+  await fs.remove(__autogenerated);
+  await fs.ensureDir(__autogenerated);
+  await fs.ensureDir(__autogeneratedUtils);
+
+  try {
+    const typeScriptDocsPromise = generateTypeScriptDocs(
+      [
+        path.join(
+          __root,
+          '..',
+          'core',
+          'src',
+          'components',
+          'utils',
+          'modal',
+          'modal.ts'
+        ),
+        path.join(
+          __root,
+          '..',
+          'angular',
+          'src',
+          'providers',
+          'modal',
+          'modal.service.ts'
+        ),
+        path.join(
+          __root,
+          '..',
+          'core',
+          'src',
+          'components',
+          'toast',
+          'toast-utils.ts'
+        ),
+        path.join(
+          __root,
+          '..',
+          'angular',
+          'src',
+          'providers',
+          'toast',
+          'toast.service.ts'
+        ),
+      ],
+      __autogenerated
+    );
+    const mainTasksPromise = [
+      copyStaticFiles(),
+      copyUsage(),
+      copyStorybook(),
+      generatePlaygroundMarkdown(['form-validation']),
+      generateApiMarkdown(),
+    ];
+    await Promise.all([typeScriptDocsPromise, ...mainTasksPromise]);
+    await copyComponentReadme();
+    await writeLibraryVersion();
+  } catch (e: any) {
+    console.error(e.message);
+    process.exit(1);
+  }
+
+  console.log('All documentation generation tasks completed');
+})();

package/scripts/collector/collectAngularExamples.ts

@@ -0,0 +1,50 @@
+import fs from 'fs-extra';
+import {
+  collectExamplesForTag,
+  resolveExampleFile,
+  readIfExists,
+  sectionedExample,
+} from './util';
+import { removeTypescriptHeaderComments } from '../utils/escape';
+
+export async function collectAngularExamples(
+  __componentUsageByComponentJson: string,
+  __angularTestAppRoot: string,
+  tag: string
+): Promise<string> {
+  return collectExamplesForTag(
+    __componentUsageByComponentJson,
+    tag,
+    async (exampleName) => {
+      // Mandatory .ts file
+      const tsFile = resolveExampleFile(
+        __angularTestAppRoot,
+        exampleName,
+        'ts'
+      );
+      if (!fs.existsSync(tsFile)) {
+        console.warn(`Example file not found: ${tsFile}`);
+        return null;
+      }
+      const tsContent = await fs.readFile(tsFile, 'utf-8');
+
+      const htmlContent = await readIfExists(
+        resolveExampleFile(__angularTestAppRoot, exampleName, 'html')
+      );
+
+      const combined = sectionedExample([
+        {
+          heading: 'Component typescript',
+          lang: 'typescript',
+          code: tsContent,
+        },
+        { heading: 'Component template', lang: 'html', code: htmlContent },
+      ]);
+
+      return {
+        exampleName,
+        example: removeTypescriptHeaderComments(combined).trim(),
+      };
+    }
+  );
+}

package/scripts/collector/collectHTMLExamples.ts

@@ -0,0 +1,29 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import { removeHTMLComments } from '../utils/escape';
+import { collectExamplesForTag } from './util';
+
+export async function collectHTMLExamples(
+  __componentUsageByComponentJson: string,
+  __htmlTestAppRoot: string,
+  tag: string
+): Promise<string> {
+  return collectExamplesForTag(
+    __componentUsageByComponentJson,
+    tag,
+    async (exampleName, relativeExamplePath) => {
+      const filePath = path.join(__htmlTestAppRoot, relativeExamplePath);
+      if (!fs.existsSync(filePath)) {
+        console.warn(`Example file not found: ${filePath}`);
+        return null;
+      }
+      const content = await fs.readFile(filePath, 'utf-8');
+      return {
+        exampleName,
+        example: ['```html', removeHTMLComments(content).trim(), '```'].join(
+          '\n'
+        ),
+      };
+    }
+  );
+}

package/scripts/collector/collectReactExamples.ts

@@ -0,0 +1,33 @@
+import fs from 'fs-extra';
+import {
+  collectExamplesForTag,
+  resolveExampleFile,
+} from './util';
+import { removeTypescriptHeaderComments } from '../utils/escape';
+
+export async function collectReactExamples(
+  __componentUsageByComponentJson: string,
+  __reactTestAppRoot: string,
+  tag: string
+): Promise<string> {
+  return collectExamplesForTag(
+    __componentUsageByComponentJson,
+    tag,
+    async (exampleName) => {
+      const tsxFile = resolveExampleFile(
+        __reactTestAppRoot,
+        exampleName,
+        'tsx'
+      );
+      if (!fs.existsSync(tsxFile)) {
+        console.warn(`Example file not found: ${tsxFile}`);
+        return null;
+      }
+      const content = await fs.readFile(tsxFile, 'utf-8');
+      return {
+        exampleName,
+        example: ['```tsx', removeTypescriptHeaderComments(content).trim(), '```'].join('\n'),
+      };
+    }
+  );
+}

package/scripts/collector/collectVueExamples.ts

@@ -0,0 +1,30 @@
+import fs from 'fs-extra';
+import { collectExamplesForTag, resolveExampleFile } from './util';
+import { removeHTMLComments } from '../utils/escape';
+
+export async function collectVueExamples(
+  __componentUsageByComponentJson: string,
+  __vueTestAppRoot: string,
+  tag: string
+): Promise<string> {
+  return collectExamplesForTag(
+    __componentUsageByComponentJson,
+    tag,
+    async (exampleName) => {
+      const vueFile = resolveExampleFile(
+        __vueTestAppRoot,
+        exampleName,
+        'vue'
+      );
+      if (!fs.existsSync(vueFile)) {
+        console.warn(`Example file not found: ${vueFile}`);
+        return null;
+      }
+      const content = await fs.readFile(vueFile, 'utf-8');
+      return {
+        exampleName,
+        example: ['```tsx', removeHTMLComments(content).trim(), '```'].join('\n'),
+      };
+    }
+  );
+}