@unisphere/nx 3.14.0 → 3.17.0

package/dist/generators/add-documentation/USAGE.md

@@ -0,0 +1,64 @@
+# add-documentation
+
+Generate a Docusaurus documentation site for an experience.
+
+## Usage
+
+```bash
+npx nx g @unisphere/nx:add-documentation
+```
+
+The experience name is auto-resolved from `.unisphere` config.
+
+## Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--name` | string | auto from `.unisphere` | Override the experience name |
+| `--is-experience-level` | boolean | `false` | Skip sub-name prompt (top-level experience docs) |
+| `--sub-name` | string | prompted | Sub-name for the documentation site |
+
+## Examples
+
+**Sub-level docs (default)** — prompts for sub-name:
+
+```bash
+npx nx g @unisphere/nx:add-documentation
+# Experience name auto-resolved from .unisphere
+# Prompts: "What is the documentation sub-name?"
+# e.g. sub-name "models" → folder: unisphere/documentation/{experience}-models
+```
+
+**Sub-level docs with flags (no prompts):**
+
+```bash
+npx nx g @unisphere/nx:add-documentation --sub-name=models
+```
+
+**Experience-level docs (no sub-name):**
+
+```bash
+npx nx g @unisphere/nx:add-documentation --is-experience-level
+# → folder: unisphere/documentation/{experience}
+```
+
+**Override experience name:**
+
+```bash
+npx nx g @unisphere/nx:add-documentation --name=cs --sub-name=models
+# → folder: unisphere/documentation/cs-models
+```
+
+## Output
+
+- `unisphere/documentation/{name}/` — Full Docusaurus site
+- `.unisphere` — Updated with documentation entry
+- `.nxignore` — Updated to exclude documentation node_modules
+
+## After generation
+
+```bash
+cd unisphere/documentation/{name}
+npm install
+npx unisphere documentation serve {name}
+```

package/dist/generators/add-documentation/add-documentation.d.ts

@@ -1,5 +1,5 @@
 import { Tree } from '@nx/devkit';
 import { AddDocumentationGeneratorSchema } from './schema';
-export declare function addDocumentationGenerator(tree: Tree, options: AddDocumentationGeneratorSchema): Promise<() => void>;
+export declare function addDocumentationGenerator(tree: Tree, options: AddDocumentationGeneratorSchema): Promise<(() => void) | undefined>;
 export default addDocumentationGenerator;
 //# sourceMappingURL=add-documentation.d.ts.map

package/dist/generators/add-documentation/add-documentation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add-documentation.d.ts","sourceRoot":"","sources":["../../../src/generators/add-documentation/add-documentation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,IAAI,EAAiB,MAAM,YAAY,CAAC;AAI9D,OAAO,EAAE,+BAA+B,EAAE,MAAM,UAAU,CAAC;AAM3D,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,+BAA+B,uBA4GzC;AAED,eAAe,yBAAyB,CAAC"}
+{"version":3,"file":"add-documentation.d.ts","sourceRoot":"","sources":["../../../src/generators/add-documentation/add-documentation.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,IAAI,EAAiB,MAAM,YAAY,CAAC;AAG7E,OAAO,EAAE,+BAA+B,EAAE,MAAM,UAAU,CAAC;AAY3D,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,+BAA+B,qCAwJzC;AAED,eAAe,yBAAyB,CAAC"}

package/dist/generators/add-documentation/add-documentation.js

@@ -3,13 +3,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.addDocumentationGenerator = addDocumentationGenerator;
 const tslib_1 = require("tslib");
 const devkit_1 = require("@nx/devkit");
-const path = tslib_1.__importStar(require("path"));
 const child_process_1 = require("child_process");
-const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
 const utils_1 = require("../utils");
+async function getEnquirerPrompt() {
+    const enquirer = await import('enquirer');
+    return enquirer.prompt || enquirer.default?.prompt || enquirer;
+}
 async function addDocumentationGenerator(tree, options) {
     // Validate .unisphere configuration exists
-    (0, utils_1.validateUnisphereConfig)(tree);
+    const unisphereConfig = (0, utils_1.validateUnisphereConfig)(tree);
     // Check workspace pattern for documentation apps
     const rootPackageJsonPath = 'package.json';
     if (tree.exists(rootPackageJsonPath)) {
@@ -27,16 +30,52 @@ async function addDocumentationGenerator(tree, options) {
                 'This will update your workspace pattern to support documentation sites.');
         }
     }
-    const documentationName = options.name;
+    // Resolve experience name: use --name flag, or auto-resolve from .unisphere config
+    const documentationName = options.name || unisphereConfig.name;
     const documentationNameAsLowerDashCase = (0, devkit_1.names)(documentationName).fileName;
-    const projectRoot = `unisphere/documentation/${documentationNameAsLowerDashCase}`;
+    devkit_1.logger.info(`Using experience name: ${documentationNameAsLowerDashCase}`);
+    // If not experience-level, prompt for sub-name
+    let subName = options.subName;
+    if (!options.isExperienceLevel && !subName) {
+        const prompt = await getEnquirerPrompt();
+        const response = await prompt({
+            type: 'input',
+            name: 'subName',
+            message: 'What is the documentation sub-name? (letters, numbers, dashes and spaces allowed)',
+            validate: (value) => {
+                if (!value || !value.trim()) {
+                    return 'Sub-name is required for non-experience-level documentation sites';
+                }
+                if (!/^[a-zA-Z][a-zA-Z0-9\-\s]*$/.test(value)) {
+                    return 'Sub-name must start with a letter and contain only letters, numbers, dashes and spaces';
+                }
+                return true;
+            },
+        });
+        subName = response.subName;
+    }
+    // Build the full documentation name
+    const subNameAsLowerDashCase = subName ? (0, devkit_1.names)(subName).fileName : null;
+    const fullDocumentationName = subNameAsLowerDashCase
+        ? `${documentationNameAsLowerDashCase}-${subNameAsLowerDashCase}`
+        : documentationNameAsLowerDashCase;
+    const projectRoot = `unisphere/documentation/${fullDocumentationName}`;
     // Check if the documentation site already exists
     if (tree.exists(projectRoot)) {
-        throw new Error(`Documentation site "${documentationNameAsLowerDashCase}" already exists at ${projectRoot}.\n` +
+        throw new Error(`Documentation site "${fullDocumentationName}" already exists at ${projectRoot}.\n` +
             'Please choose a different name or remove the existing documentation site first.');
     }
+    // Generate files from template
+    const templateVariables = {
+        ...(0, utils_1.createNameTransforms)(fullDocumentationName, 'documentationName'),
+        ...(0, utils_1.createNameTransforms)(documentationNameAsLowerDashCase, 'experienceName'),
+        hasSubName: !!subNameAsLowerDashCase,
+        subNameKebab: subNameAsLowerDashCase || '',
+        tmpl: '',
+    };
+    (0, devkit_1.generateFiles)(tree, path.join(__dirname, 'templates'), projectRoot, templateVariables);
     // Update .unisphere configuration
-    (0, utils_1.updateUnisphereConfig)(tree, 'documentation', documentationNameAsLowerDashCase, {
+    (0, utils_1.updateUnisphereConfig)(tree, 'documentation', fullDocumentationName, {
         sourceRoot: projectRoot,
     });
     // Add documentation folder to .nxignore to prevent NX from scanning it
@@ -53,45 +92,45 @@ async function addDocumentationGenerator(tree, options) {
             : `# Documentation site (Docusaurus) - has its own node_modules\n${ignoreEntry}\n`;
         tree.write(nxIgnorePath, newContent);
     }
+    // Copy .npmrc from workspace root so npm install can authenticate with private registries
+    const npmrcPath = '.npmrc';
+    if (tree.exists(npmrcPath)) {
+        const npmrcContent = tree.read(npmrcPath, 'utf-8');
+        if (npmrcContent) {
+            tree.write(`${projectRoot}/.npmrc`, npmrcContent);
+        }
+    }
     await (0, devkit_1.formatFiles)(tree);
-    // Return a function that will be executed after all file operations are complete
+    devkit_1.logger.info('');
+    devkit_1.logger.info('Documentation site generated successfully!');
+    devkit_1.logger.info('');
+    devkit_1.logger.info(`Name: ${fullDocumentationName}`);
+    devkit_1.logger.info(`Type: Documentation Site (Docusaurus)`);
+    devkit_1.logger.info(`Location: ${projectRoot}`);
+    devkit_1.logger.info('');
+    if (options.skipInstall) {
+        devkit_1.logger.info('Skipping npm install (--skip-install).');
+        devkit_1.logger.info('');
+        devkit_1.logger.info(`To install: cd ${projectRoot} && npm install`);
+        devkit_1.logger.info(`To serve:   npx unisphere documentation serve ${fullDocumentationName}`);
+        devkit_1.logger.info(`To build:   npx unisphere documentation build ${fullDocumentationName}`);
+        devkit_1.logger.info('');
+        return;
+    }
+    // Return callback to run npm install after the tree is flushed to disk
+    const workspaceRoot = tree.root;
     return () => {
-        const workspaceRoot = process.cwd();
         const fullProjectPath = path.join(workspaceRoot, projectRoot);
+        devkit_1.logger.info('Installing dependencies...');
         devkit_1.logger.info('');
-        devkit_1.logger.info('Setting up Docusaurus documentation site...');
+        (0, child_process_1.execSync)('npm install', {
+            cwd: fullProjectPath,
+            stdio: 'inherit',
+        });
+        devkit_1.logger.info('');
+        devkit_1.logger.info(`To serve: npx unisphere documentation serve ${fullDocumentationName}`);
+        devkit_1.logger.info(`To build: npx unisphere documentation build ${fullDocumentationName}`);
         devkit_1.logger.info('');
-        try {
-            // Create the parent directory if it doesn't exist
-            const parentDir = path.dirname(fullProjectPath);
-            if (!fs.existsSync(parentDir)) {
-                fs.mkdirSync(parentDir, { recursive: true });
-            }
-            // Run Docusaurus CLI to scaffold the project
-            // Docusaurus creates a self-contained project with its own package.json
-            // No NX integration needed - we just delegate to Docusaurus CLI for serve/build
-            // Use public npm registry explicitly (workspaces may have private registry configured)
-            devkit_1.logger.info('Running Docusaurus CLI...');
-            (0, child_process_1.execSync)(`npx --yes --registry https://registry.npmjs.org create-docusaurus@3 "${fullProjectPath}" classic --typescript`, {
-                stdio: 'inherit',
-                cwd: workspaceRoot,
-            });
-            devkit_1.logger.info('');
-            devkit_1.logger.info('Documentation site generated successfully!');
-            devkit_1.logger.info('');
-            devkit_1.logger.info(`Name: ${documentationNameAsLowerDashCase}`);
-            devkit_1.logger.info(`Type: Documentation Site (Docusaurus)`);
-            devkit_1.logger.info(`Location: ${projectRoot}`);
-            devkit_1.logger.info('');
-            devkit_1.logger.info(`To serve: npx unisphere documentation serve ${documentationNameAsLowerDashCase}`);
-            devkit_1.logger.info(`To build: npx unisphere documentation build ${documentationNameAsLowerDashCase}`);
-            devkit_1.logger.info('');
-        }
-        catch (error) {
-            devkit_1.logger.error('Failed to create Docusaurus project:');
-            devkit_1.logger.error(error instanceof Error ? error.message : String(error));
-            throw error;
-        }
     };
 }
 exports.default = addDocumentationGenerator;

package/dist/generators/add-documentation/schema.d.ts

@@ -1,3 +1,6 @@
 export interface AddDocumentationGeneratorSchema {
-  name: string;
+  name?: string;
+  isExperienceLevel?: boolean;
+  subName?: string;
+  skipInstall?: boolean;
 }

package/dist/generators/add-documentation/schema.json

@@ -6,16 +6,25 @@
   "properties": {
     "name": {
       "type": "string",
-      "description": "The name of the documentation site to create",
-      "pattern": "^[a-zA-Z][a-zA-Z0-9\\-\\s]*$",
-      "$default": {
-        "$source": "argv",
-        "index": 0
-      },
-      "x-prompt": "What is the documentation site name? (letters, numbers, dashes and spaces allowed)"
+      "description": "Experience name. Auto-resolved from .unisphere config if not provided.",
+      "pattern": "^[a-zA-Z][a-zA-Z0-9\\-\\s]*$"
+    },
+    "isExperienceLevel": {
+      "type": "boolean",
+      "description": "Whether this is an experience-level documentation site (no sub-name needed)",
+      "default": false
+    },
+    "subName": {
+      "type": "string",
+      "description": "Sub-name for the documentation site (used when not experience-level)",
+      "pattern": "^[a-zA-Z][a-zA-Z0-9\\-\\s]*$"
+    },
+    "skipInstall": {
+      "type": "boolean",
+      "description": "Internal: skip npm install (used by unisphere create)",
+      "default": false,
+      "x-internal": true
     }
   },
-  "required": [
-    "name"
-  ]
+  "required": []
 }

package/dist/generators/add-documentation/templates/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

package/dist/generators/add-documentation/templates/docs/api/overview.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 1
+title: Overview
+---
+
+# API Reference
+
+API documentation will be added here.

package/dist/generators/add-documentation/templates/docs/changelog/overview.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 1
+title: Overview
+---
+
+# Changelog
+
+Release notes and version history will be documented here.

package/dist/generators/add-documentation/templates/docs/getting-started/overview.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 1
+title: Overview
+---
+
+# Getting Started
+
+Welcome to the documentation site. Start here to learn the basics.

package/dist/generators/add-documentation/templates/docusaurus.config.ts.template

@@ -0,0 +1,116 @@
+import { themes as prismThemes } from 'prism-react-renderer';
+import type { Config } from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const config: Config = {
+<% if (hasSubName) { -%>
+  title: '<%= experienceName__humanReadable %> | <%= subNameKebab %> Documentation',
+<% } else { -%>
+  title: '<%= experienceName__humanReadable %> Documentation',
+<% } -%>
+  tagline: '',
+  favicon: 'img/favicon.ico',
+
+  url: 'https://docs.kaltura.com',
+<% if (hasSubName) { -%>
+  baseUrl: '/_/<%= experienceName__lowerDashCase %>/<%= subNameKebab %>',
+<% } else { -%>
+  baseUrl: '/<%= experienceName__lowerDashCase %>',
+<% } -%>
+
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+
+  // Prevent search engine crawling and indexing
+  noIndex: true,
+
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          sidebarPath: './sidebars.ts',
+          exclude: [],
+        },
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+        // Disable sitemap generation
+        sitemap: {
+          ignorePatterns: ['**'],
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+  plugins: [],
+  themes: [
+    '@docusaurus/theme-mermaid',
+    [
+      '@easyops-cn/docusaurus-search-local',
+      {
+        hashed: true,
+        indexBlog: false,
+        forceIgnoreNoIndex: true,
+      },
+    ],
+  ],
+  markdown: {
+    mermaid: true,
+  },
+  themeConfig: {
+    colorMode: {
+      defaultMode: 'light',
+      disableSwitch: false,
+      respectPrefersColorScheme: true,
+    },
+    image: 'img/social-card.png',
+    navbar: {
+<% if (hasSubName) { -%>
+      title: '<%= experienceName__humanReadable %> | <%= subNameKebab %> Documentation',
+<% } else { -%>
+      title: '<%= experienceName__humanReadable %> Documentation',
+<% } -%>
+      logo: {
+        alt: 'Logo',
+        src: 'img/logo.svg',
+        srcDark: 'img/logo_dark.svg',
+      },
+      items: [
+        {
+          type: 'docSidebar',
+          sidebarId: 'gettingStarted',
+          position: 'left',
+          label: 'Getting Started',
+        },
+        {
+          type: 'docSidebar',
+          sidebarId: 'api',
+          position: 'left',
+          label: 'API',
+        },
+        {
+          type: 'docSidebar',
+          sidebarId: 'changelog',
+          position: 'left',
+          label: 'Changelog',
+        },
+      ],
+    },
+    footer: {
+      style: 'dark',
+      links: [],
+      copyright: `Copyright © ${new Date().getFullYear()} Kaltura. Built with Docusaurus.`,
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;

package/dist/generators/add-documentation/templates/package.json.template

@@ -0,0 +1,57 @@
+{
+  "name": "<%= documentationName__lowerDashCase %>",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve",
+    "write-translations": "docusaurus write-translations",
+    "write-heading-ids": "docusaurus write-heading-ids",
+    "typecheck": "tsc"
+  },
+  "dependencies": {
+    "@docusaurus/core": "^3.8.1",
+    "@docusaurus/preset-classic": "^3.8.1",
+    "@docusaurus/theme-mermaid": "^3.8.1",
+    "@easyops-cn/docusaurus-search-local": "^0.55.1",
+    "@heroicons/react": "^2.2.0",
+    "@mdx-js/react": "^3.0.0",
+    "@unisphere/notifications-core": "^1.24.0",
+    "@unisphere/runtime-js": "^1.83.0",
+    "autoprefixer": "^10.4.20",
+    "clsx": "^2.0.0",
+    "postcss": "^8.4.41",
+    "prism-react-renderer": "^2.3.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "tailwindcss": "^3.4.10"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "^3.8.1",
+    "@docusaurus/tsconfig": "^3.8.1",
+    "@docusaurus/types": "^3.8.1",
+    "docusaurus-plugin-typedoc": "^1.4.2",
+    "typedoc": "^0.28.17",
+    "typescript": "~5.2.2"
+  },
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 3 chrome version",
+      "last 3 firefox version",
+      "last 5 safari version"
+    ]
+  },
+  "engines": {
+    "node": ">=18.0"
+  }
+}

package/dist/generators/add-documentation/templates/postcss.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/dist/generators/add-documentation/templates/sidebars.ts

@@ -0,0 +1,9 @@
+import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
+
+const sidebars: SidebarsConfig = {
+  gettingStarted: [{ type: 'autogenerated', dirName: 'getting-started' }],
+  api: [{ type: 'autogenerated', dirName: 'api' }],
+  changelog: [{ type: 'autogenerated', dirName: 'changelog' }],
+};
+
+export default sidebars;

package/dist/generators/add-documentation/templates/src/components/demo-placeholder-card.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import { PlaygroundCard } from '@site/src/components/ui-shared/playground-card';
+
+const DemoPlaceholderCard: React.FC = () => {
+  const playIcon = (
+    <svg
+      width="48"
+      height="48"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      style={{
+        color: '#94a3b8',
+        opacity: 0.7
+      }}
+    >
+      <circle cx="12" cy="12" r="10" />
+      <polygon points="10,8 16,12 10,16 10,8" />
+    </svg>
+  );
+
+  return (
+    <PlaygroundCard
+      title="Live Demonstration"
+      icon={playIcon}
+    >
+      A live demonstration will be added here soon
+    </PlaygroundCard>
+  );
+};
+
+export default DemoPlaceholderCard;