@nutin/cli 2.1.1 → 3.0.0

package/templates/features/markdown/src/app/markdown/markdown-routes.ts.hbs

@@ -0,0 +1,26 @@
+import { View } from '../../core/index.js';
+import { MarkdownGuards } from './markdown-guards.js';
+import { MarkdownManifestsService } from './markdown-manifests.service.js';
+
+export interface IMarkdownRoutesOptions {
+  // Builds the view of a folder's routes, e.g. a MarkdownView with your own components or a
+  // subclass of it. Called for every folder, with its id: return new MarkdownView({ id }) for
+  // the folders you don't customize. May return a Promise, to load the view lazily (see
+  // ViewFactory): e.g. import('./views/docs/docs.view.js').then((m) => new m.DocsView(id)).
+  view?: (id: string) => View | Promise<View>;
+}
+
+// One route per nutin.config.js "markdownSources" folder: '/<id>/:slug?', or
+// '/<id>/:section?/:slug?' with "sectionInPath: true". Spread into appRoutes; a route
+// written after the spread with the same path replaces the generated one.
+// By default, the routes are lazy: MarkdownView and its components are loaded on the first
+// visit to one of them, not with the rest of the app.
+export function markdownRoutes(options: IMarkdownRoutesOptions = {}): Nutin.Routes {
+  const view = options.view ?? ((id: string) => import('./view/markdown.view.js').then((m) => new m.MarkdownView({ id })));
+  return Object.fromEntries(
+    MarkdownManifestsService.all.map(({ id, sectionInPath }) => sectionInPath
+      ? [`/${id}/:section?/:slug?`, { view: () => view(id), guards: [MarkdownGuards.sectionPageExists(id)] }]
+      : [`/${id}/:slug?`, { view: () => view(id), guards: [MarkdownGuards.pageExists(id)] }]
+    )
+  );
+}

package/templates/features/markdown/src/app/markdown/markdown-sources.test.js.hbs

@@ -0,0 +1,22 @@
+import { resolveMarkdownSources } from '#root/dist/src/app/markdown/markdown-sources.js';
+
+describe('resolveMarkdownSources', () => {
+  // Same cases as tools/builder/core/markdown/markdown-compiler.test.js: the compiler names
+  // each manifest with this id, so both rules must agree.
+  it('derives manifest ids like the compiler does', () => {
+    const cases = [
+      ['content', 'content', false],
+      ['docs/My Guides', 'my-guides', false],
+      ['docs/guides/', 'guides', false],
+      [{ folder: 'x', routePrefix: 'api' }, 'api', false],
+      [{ folder: 'docs', sectionInPath: true }, 'docs', true],
+    ];
+    const sources = resolveMarkdownSources({ sourceFolders: cases.map(([entry]) => entry) });
+    expect(sources).toEqual(cases.map(([, id, sectionInPath]) => ({ id, sectionInPath })));
+  });
+
+  it('returns no sources when markdownSources is missing', () => {
+    expect(resolveMarkdownSources(undefined)).toEqual([]);
+    expect(resolveMarkdownSources({})).toEqual([]);
+  });
+});

package/templates/features/markdown/src/app/markdown/markdown-sources.ts.hbs

@@ -0,0 +1,42 @@
+import { IMarkdownSource } from './markdown-manifest.js';
+
+export type MarkdownSourceEntry = string | {
+  folder: string;
+  routePrefix?: string;
+  hubFiles?: string[];
+  sectionInPath?: boolean;
+  prefixReplacements?: [string, string][];
+  seo?: boolean;
+  ogImage?: string;
+  landing?: boolean | { title?: string; description?: string };
+};
+
+declare global {
+  // Set by the builder's esbuild define (tools/builder/core/prod-bundle/bundle-options.js):
+  // nutin.config.js's markdownSources.sourceFolders, as JSON. Undefined in tsc output (tests).
+  var __NUTIN_MARKDOWN_SOURCES__: string | undefined;
+}
+
+export interface IMarkdownSourcesConfig {
+  sourceFolders?: MarkdownSourceEntry[];
+}
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// Mirrors normalizeSource() in tools/builder/core/markdown/markdown-compiler.js, which names
+// each manifest: keep both id rules identical (the build validates entries, not this).
+export function resolveMarkdownSources(config: IMarkdownSourcesConfig | undefined): IMarkdownSource[] {
+  return (config?.sourceFolders ?? []).map((entry) => {
+    const options = typeof entry === 'string' ? { folder: entry } : entry;
+    const folderName = options.folder.replace(/[\\/]+$/, '').split(/[\\/]/).pop() ?? '';
+    return {
+      id: options.routePrefix ?? slugify(folderName),
+      sectionInPath: options.sectionInPath === true,
+    };
+  });
+}

package/templates/features/markdown/src/app/markdown/view/markdown.view.html.hbs

@@ -0,0 +1,4 @@
+<div class="markdown-view">
+  <aside data-component="markdown-nav"></aside>
+  <div data-component="markdown-content"></div>
+</div>

package/templates/features/markdown/src/app/markdown/view/markdown.view.scss.hbs

@@ -0,0 +1,19 @@
+// Every selector is wrapped in :where(), so it has no specificity: any rule of your own wins.
+// Adjust sizes through the custom properties below, e.g. in your own stylesheet:
+//   .markdown-view { --markdown-nav-width: 20rem; }
+:where(.markdown-view) {
+  --markdown-gap: 2rem;
+  --markdown-nav-width: 16rem;
+  --markdown-toc-width: 14rem;
+  --markdown-line-height: 1.7;
+
+  display: flex;
+  gap: var(--markdown-gap);
+  padding: 2rem 1rem;
+}
+
+@media (max-width: 700px) {
+  :where(.markdown-view) {
+    flex-direction: column;
+  }
+}

package/templates/features/markdown/src/app/markdown/view/markdown.view.test.js.hbs

@@ -0,0 +1,125 @@
+import { MarkdownView } from '#root/dist/src/app/markdown/view/markdown.view.js';
+import { MarkdownManifest } from '#root/dist/src/app/markdown/markdown-manifest.js';
+import { MarkdownManifestsService } from '#root/dist/src/app/markdown/markdown-manifests.service.js';
+import { MarkdownNavComponent } from '#root/dist/src/app/markdown/components/markdown-nav/markdown-nav.component.js';
+import { MarkdownContentComponent } from '#root/dist/src/app/markdown/components/markdown-content/markdown-content.component.js';
+
+const page = (slug, section, title) => ({
+  slug, section, title, description: `About ${title}`, group: null, order: 0, source: `${slug}.md`, headings: [], html: `<h1>${title}</h1>`,
+});
+
+const DATA = {
+  sections: [
+    { id: 'api', title: 'API', description: 'The API.', pages: ['a'] },
+    { id: 'tools', title: 'Tools', description: '', pages: ['b'] },
+  ],
+  pages: { a: page('a', 'api', 'Page A'), b: page('b', 'tools', 'Page B') },
+};
+
+// A fresh manifest per test: the service's own manifests are shared singletons.
+async function manifestOf(data, sectionInPath = false) {
+  const originalFetch = global.fetch;
+  global.fetch = () => Promise.resolve({ ok: true, status: 200, json: () => Promise.resolve(data) });
+  try {
+    const manifest = new MarkdownManifest({ id: 'docs', sectionInPath }, () => null);
+    await manifest.load();
+    return manifest;
+  } finally {
+    global.fetch = originalFetch;
+  }
+}
+
+function viewOf(manifest, params = {}, options = {}) {
+  const view = new MarkdownView({ id: MarkdownManifestsService.ids[0], ...options });
+  view.manifest = manifest;
+  view.setRouteParams(params);
+  return view;
+}
+
+describe('MarkdownView', () => {
+  let replaceSpy;
+  let view;
+
+  beforeEach(() => {
+    // NavigationManager.replaceState() ends in history.replaceState(state, title, url).
+    replaceSpy = spyOn(window.history, 'replaceState').andCallFake(() => {});
+  });
+
+  afterEach(() => {
+    view?.onExit();
+    view?.destroy();
+    view = null;
+    replaceSpy.restore();
+  });
+
+  it('renders the page of the route, and uses its title as the document title', async () => {
+    view = viewOf(await manifestOf(DATA), { slug: 'b' });
+    view.render();
+    expect(view.getElement().querySelector('.markdown-content__body h1').textContent).toBe('Page B');
+    expect(view.documentTitle()).toBe('Page B');
+  });
+
+  it('without a landing, renders the first page on the bare route and points the URL at it', async () => {
+    view = viewOf(await manifestOf(DATA));
+    view.render();
+    view.onEnter();
+    expect(view.getElement().querySelector('.markdown-content__body h1').textContent).toBe('Page A');
+    expect(replaceSpy.lastCall[2]).toBe('/docs/a');
+  });
+
+  it('with a landing, renders it on the bare route and keeps the URL', async () => {
+    view = viewOf(await manifestOf({ ...DATA, landing: { title: 'Docs', description: 'Everything.' } }));
+    view.render();
+    view.onEnter();
+    const element = view.getElement();
+    expect(element.querySelector('.markdown-landing__title').textContent).toBe('Docs');
+    expect(element.querySelector('.markdown-landing__description').textContent).toBe('Everything.');
+    expect([...element.querySelectorAll('.markdown-landing__link')].map((a) => a.getAttribute('href'))).toEqual(['/docs/a', '/docs/b']);
+    expect(element.querySelector('.markdown-content__body')).toBe(null);
+    expect(replaceSpy.callCount).toBe(0);
+    expect(view.documentTitle()).toBe('Docs');
+  });
+
+  it('with sections in the URL, the folder landing links each section and the nav lists them all', async () => {
+    view = viewOf(await manifestOf({ ...DATA, landing: { title: 'Docs', description: '' } }, true));
+    view.render();
+    const element = view.getElement();
+    expect([...element.querySelectorAll('.markdown-landing__link')].map((a) => a.getAttribute('href'))).toEqual(['/docs/api', '/docs/tools']);
+    expect([...element.querySelectorAll('.markdown-nav__section-title')].map((s) => s.textContent)).toEqual(['API', 'Tools']);
+  });
+
+  it('with sections in the URL, a section landing lists its pages under its own title', async () => {
+    view = viewOf(await manifestOf({ ...DATA, landing: { title: 'Docs', description: '' } }, true), { section: 'api' });
+    view.render();
+    const element = view.getElement();
+    expect(element.querySelector('.markdown-landing__title').textContent).toBe('API');
+    expect([...element.querySelectorAll('.markdown-landing__link')].map((a) => a.getAttribute('href'))).toEqual(['/docs/api/a']);
+    expect(view.documentTitle()).toBe('API');
+  });
+
+  it('uses the nav and content components passed as options', async () => {
+    class MyNav extends MarkdownNavComponent {
+      constructor(el, config) { super(el, config, () => '<nav class="my-nav"></nav>'); }
+    }
+    class MyContent extends MarkdownContentComponent {}
+    view = viewOf(await manifestOf(DATA), { slug: 'a' }, { navComponent: MyNav, contentComponent: MyContent });
+    view.render();
+    expect(view.getElement().querySelector('.my-nav')).toBeTruthy();
+    expect(view.getElement().querySelector('.markdown-nav')).toBe(null);
+    expect(view.getElement().querySelector('.markdown-content__body')).toBeTruthy();
+  });
+
+  it('calls onContentRendered with the content element and the page', async () => {
+    const calls = [];
+    view = viewOf(await manifestOf(DATA), { slug: 'a' }, { onContentRendered: (element, shown) => calls.push([element.className, shown.slug]) });
+    view.render();
+    expect(calls).toEqual([['markdown-content', 'a']]);
+  });
+
+  it('renders without a nav when the template has no nav placeholder', async () => {
+    view = viewOf(await manifestOf(DATA), { slug: 'a' }, { template: '<div><div data-component="markdown-content"></div></div>' });
+    view.render();
+    expect(view.getElement().querySelector('.markdown-nav')).toBe(null);
+    expect(view.getElement().querySelector('.markdown-content__body')).toBeTruthy();
+  });
+});

package/templates/features/markdown/src/app/markdown/view/markdown.view.ts.hbs

@@ -0,0 +1,146 @@
+import { Component, Navigation, NavigationManager, View, html } from '../../../core/index.js';
+import { IMarkdownPage, IMarkdownSection, MarkdownManifest } from '../markdown-manifest.js';
+import { MarkdownManifestsService } from '../markdown-manifests.service.js';
+import { IMarkdownContentConfig, MarkdownContentComponent } from '../components/markdown-content/markdown-content.component.js';
+import { IMarkdownLandingConfig, MarkdownLandingComponent } from '../components/markdown-landing/markdown-landing.component.js';
+import { IMarkdownNavConfig, MarkdownNavComponent } from '../components/markdown-nav/markdown-nav.component.js';
+import { onMarkdownLanguageChange } from '../markdown-i18n.js';
+
+const defaultTemplate = html`__TEMPLATE_PLACEHOLDER__`;
+
+export type MarkdownComponentClass<C> = new (mountTarget: HTMLElement, config: C) => Component<HTMLElement, C>;
+
+export interface IMarkdownViewOptions {
+  // The source's id: its "routePrefix" in nutin.config.js, defaulting to the folder name.
+  id: string;
+  // A custom layout needs data-component="markdown-nav" and data-component="markdown-content"
+  // (the content placeholder also receives the landing). Leave out "markdown-nav" for no nav.
+  template?: Nutin.Template;
+  viewName?: string;
+  // Replace a part of the page with your own component class, e.g. a subclass with its own
+  // template (see the components' optional `templateFn` constructor argument).
+  navComponent?: MarkdownComponentClass<IMarkdownNavConfig>;
+  contentComponent?: MarkdownComponentClass<IMarkdownContentConfig>;
+  landingComponent?: MarkdownComponentClass<IMarkdownLandingConfig>;
+  // Called after a page's content is rendered, e.g. to highlight its code blocks.
+  onContentRendered?: (element: HTMLElement, page: IMarkdownPage) => void;
+}
+
+// Renders one page of a "markdownSources" folder. markdownRoutes() registers one per folder;
+// with "sectionInPath: true" the route carries ':section?' before ':slug?' (e.g.
+// '/docs/api/navigate'), the nav only lists that section and every URL includes it.
+// Subclass it to change more: its getters and helpers are protected.
+export class MarkdownView extends View {
+  protected readonly manifest: MarkdownManifest;
+  protected readonly options: IMarkdownViewOptions;
+  private stopLanguageSync: () => void = () => {};
+
+  constructor(options: IMarkdownViewOptions) {
+    const { id, template = defaultTemplate, viewName = id } = options;
+    super({ template, viewName });
+    this.options = options;
+    this.manifest = MarkdownManifestsService.get(id);
+  }
+
+  protected get section(): IMarkdownSection | undefined {
+    if (!this.manifest.sectionInPath) return undefined;
+    return this.manifest.getSection(this.getRouteParam('section') ?? '') ?? this.manifest.sections[0];
+  }
+
+  // A bare route (no slug) of a folder with "landing": its index is shown instead of a page.
+  protected get isLanding(): boolean {
+    return !!this.manifest.landing && !this.getRouteParam('slug');
+  }
+
+  // MarkdownGuards already loaded the manifest and checked this slug resolves to a real
+  // page (or that the folder has no pages yet) before the view is constructed.
+  protected get slug(): string {
+    if (this.isLanding) return '';
+    const fallback = this.manifest.sectionInPath ? this.manifest.firstSlugOf(this.section) : this.manifest.firstSlug;
+    return this.getRouteParam('slug') || fallback || '';
+  }
+
+  protected get page(): IMarkdownPage | undefined {
+    return this.slug ? this.manifest.getPage(this.slug) : undefined;
+  }
+
+  protected get navSections(): IMarkdownSection[] {
+    if (!this.manifest.sectionInPath) return this.manifest.sections;
+    // The folder's own landing lists every section, so its nav does too.
+    if (this.isLanding && !this.getRouteParam('section')) return this.manifest.sections;
+    return this.section ? [this.section] : [];
+  }
+
+  protected pageHref(slug: string): string {
+    const section = this.manifest.sectionInPath ? this.manifest.getPage(slug)?.section : undefined;
+    return section ? `/${this.manifest.id}/${section}/${slug}` : `/${this.manifest.id}/${slug}`;
+  }
+
+  // The landing shown: the folder's (every section), or one section's with "sectionInPath".
+  protected landingConfig(): IMarkdownLandingConfig {
+    const localized = (path: string) => NavigationManager.addLocalePrefix(path);
+    const sectionId = this.getRouteParam('section');
+    const section = sectionId ? this.manifest.getSection(sectionId) : undefined;
+    const pageHref = (slug: string) => localized(this.pageHref(slug));
+
+    if (section) {
+      return { title: section.title, description: section.description, sections: [section], manifest: this.manifest, pageHref };
+    }
+    const landing = this.manifest.landing ?? { title: this.viewName, description: '' };
+    return {
+      title: landing.title,
+      description: landing.description,
+      sections: this.manifest.sections,
+      manifest: this.manifest,
+      pageHref,
+      // With sections in the URL, each one has its own landing: link to it instead of listing its pages.
+      ...(this.manifest.sectionInPath ? { sectionHref: (id: string) => localized(`/${this.manifest.id}/${id}`) } : {}),
+    };
+  }
+
+  // document.title after each navigation: the page's (or landing's) title, as in its SEO page.
+  public override documentTitle(): string | undefined {
+    if (this.isLanding) return this.landingConfig().title;
+    return this.page?.title;
+  }
+
+  // The bare route (e.g. /content) renders the first page through the fallback above;
+  // point the URL at that page so reloads and bookmarks match what is shown.
+  public onEnter(): void {
+    if (!this.isLanding && !this.getRouteParam('slug') && this.slug) {
+      NavigationManager.replaceState(this.pageHref(this.slug));
+    }
+    // With i18n, a language change reloads the route: MarkdownGuards load the new
+    // language's manifest, and the same page renders in that language.
+    this.stopLanguageSync = onMarkdownLanguageChange(() => Navigation.reload());
+  }
+
+  public onExit(): void {
+    this.stopLanguageSync();
+  }
+
+  public registerChildren(): Nutin.ComponentConfig[] {
+    const Nav = this.options.navComponent ?? MarkdownNavComponent;
+    const Content = this.options.contentComponent ?? MarkdownContentComponent;
+    const Landing = this.options.landingComponent ?? MarkdownLandingComponent;
+
+    return [
+      {
+        selector: 'markdown-nav',
+        factory: (el) => new Nav(el, {
+          sections: this.navSections,
+          manifest: this.manifest,
+          currentSlug: this.slug,
+          // The links' hrefs carry the locale prefix with i18n (replaceState adds it itself).
+          pageHref: (slug) => NavigationManager.addLocalePrefix(this.pageHref(slug)),
+        }),
+      },
+      {
+        selector: 'markdown-content',
+        factory: (el) => this.isLanding
+          ? new Landing(el, this.landingConfig())
+          : new Content(el, { page: this.page, loadFailed: this.manifest.loadFailed, onRendered: this.options.onContentRendered }),
+      },
+    ];
+  }
+}

package/templates/features/markdown/tools/builder/core/markdown/generate-markdown-pages.js.hbs

@@ -0,0 +1,71 @@
+import * as fs from 'fs';
+import path from 'path';
+import { print, ensureDeps, errorExit } from '../../../utils/index.js';
+import { PATHS } from '../app/paths.js';
+import { builderConfig } from '../../builder.config.js';
+import nutinConfig from '../../../../nutin.config.js';
+import { LANGUAGES, DEFAULT_LANGUAGE } from '../../../utils/languages.js';
+import { compileLanguages, normalizeSource, MarkdownCompileError } from './markdown-compiler.js';
+
+// Compiles every `markdownSources.sourceFolders` entry of nutin.config.js into
+// dist/generated/<routePrefix>.json — or, with i18n, <routePrefix>.<lang>.json per language —
+// fetched at runtime by a MarkdownManifest.
+// `--check` (the "markdown:check" script) compiles everything but writes nothing.
+
+const isCheck = process.argv.includes('--check');
+
+const sourceFolders = nutinConfig.markdownSources?.sourceFolders;
+if (!Array.isArray(sourceFolders)) {
+  errorExit('nutin.config.js "markdownSources.sourceFolders" must be an array.', 'markdown');
+}
+
+await ensureDeps({
+  feature: 'Markdown (markdownSources)',
+  deps: [
+    { name: 'marked', version: '^18.0.14' },
+    { name: 'gray-matter', version: '^4.0.3' },
+  ],
+  isProd: builderConfig.isProd,
+  origin: 'markdown',
+});
+
+// Loaded only now: they may have just been installed.
+const { Marked } = await import('marked');
+const matter = (await import('gray-matter')).default;
+
+const root = process.cwd();
+const outputDir = path.join(PATHS.tempSource, 'generated');
+
+try {
+  const sources = sourceFolders.map((entry) => normalizeSource(entry, root));
+
+  const seenIds = new Map();
+  for (const source of sources) {
+    if (seenIds.has(source.id)) {
+      throw new MarkdownCompileError(`"${seenIds.get(source.id)}" and "${source.folder}" both compile to "${source.id}.json" — give one a different "routePrefix"`);
+    }
+    seenIds.set(source.id, source.folder);
+  }
+
+  const languageOptions = { i18n: Boolean(nutinConfig.i18n), languages: LANGUAGES, defaultLanguage: DEFAULT_LANGUAGE };
+
+  for (const source of sources) {
+    const { manifests, warnings } = compileLanguages(source, { Marked, matter, root }, languageOptions);
+    warnings.forEach((warning) => print.warn(`markdown: ${warning}`));
+
+    for (const [lang, manifest] of Object.entries(manifests)) {
+      const fileName = lang ? `${source.id}.${lang}.json` : `${source.id}.json`;
+      const pageCount = Object.keys(manifest.pages).length;
+      if (isCheck) {
+        print.info(`markdown: "${source.folder}"${lang ? ` (${lang})` : ''} OK (${pageCount} pages)`);
+        continue;
+      }
+
+      fs.mkdirSync(outputDir, { recursive: true });
+      fs.writeFileSync(path.join(outputDir, fileName), JSON.stringify(manifest));
+      print.gray(`markdown: ${pageCount} pages from "${source.folder}" -> /generated/${fileName}`);
+    }
+  }
+} catch (err) {
+  errorExit(err instanceof MarkdownCompileError ? err.message : err, 'markdown');
+}