feat: extend pattern lab global types and descriptions

packages/engine-handlebars/src/lib/engine-handlebars.ts

@@ -74,7 +74,7 @@ export class EngineHandlebars implements PatternLabEngine {
  return partial;
  }
 
- spawnFile(config: PatternLabConfig, fileName: string): void {
+ private spawnFile(config: PatternLabConfig, fileName: string): void {
  const paths = config.paths;
  const metaFilePath = path.resolve(paths.source.meta, fileName);
  try {

packages/engine-liquid/src/lib/engine-liquid.ts

@@ -71,7 +71,7 @@ export class EngineLiquid implements PatternLabEngine {
  return foundPatternPartial.split(':')[0];
  }
 
- spawnFile(config: PatternLabConfig, fileName: string): void {
+ private spawnFile(config: PatternLabConfig, fileName: string): void {
  const paths = config.paths;
  const metaFilePath = path.resolve(paths.source.meta, fileName);
 

packages/engine-mustache/src/lib/engine-mustache.ts

@@ -80,7 +80,7 @@ export class EngineMustache implements PatternLabEngine {
  return foundPatternPartial.split(':')[0];
  }
 
- spawnFile(config: PatternLabConfig, fileName: string): void {
+ private spawnFile(config: PatternLabConfig, fileName: string): void {
  const paths = config.paths;
  const metaFilePath = path.resolve(paths.source.meta, fileName);
  try {

packages/engine-nunjucks/src/lib/engine-nunjucks.ts

@@ -95,7 +95,7 @@ export class EngineNunjucks implements PatternLabEngine {
  return '';
  }
 
- spawnFile(config: PatternLabConfig, fileName: string): void {
+ private spawnFile(config: PatternLabConfig, fileName: string): void {
  const paths = config.paths;
  const metaFilePath = path.resolve(paths.source.meta, fileName);
  try {

packages/engine-twig-php/src/lib/engine-twig-php.ts

@@ -160,7 +160,7 @@ export class EngineTwigPhp implements PatternLabEngine {
  }
  }
 
- spawnFile(config: PatternLabConfig, fileName: string): void {
+ private spawnFile(config: PatternLabConfig, fileName: string): void {
  const metaFilePath = path.resolve(config.paths.source.meta, fileName);
  try {
  fs.statSync(metaFilePath);

packages/engine-twig/src/lib/engine-twig.ts

@@ -51,17 +51,15 @@ export class EngineTwig implements PatternLabEngine {
  /({{#( )?)(list(I|i)tems.)(one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|thirteen|fourteen|fifteen|sixteen|seventeen|eighteen|nineteen|twenty)( )?}}/g;
 
  renderPattern(pattern: Pattern, data: PatternData, _partials?: PatternPartial): Promise<string> {
- let patternPath = pattern.basePattern ? pattern.basePattern.relPath : pattern.relPath;
+ let patternPath = pattern.basePattern?.relPath || pattern.relPath;
  if (this.metaPath && patternPath.lastIndexOf(this.metaPath) === 0) {
  patternPath = patternPath.substring(this.metaPath.length + 1);
  }
  return Promise.resolve(this.engine.render(patternPath, data));
  }
 
  registerPartial(pattern: Pattern): void {
- console.log(
- `registerPartial(${pattern.name} - ${pattern.patternPartial} - ${pattern.patternPath} - ${pattern.relPath})`,
- );
+ console.log(`registerPartial(${pattern.name} - ${pattern.patternPartial} - ${pattern.relPath})`);
  patternLabLoader.registerPartial(pattern);
  }
 
@@ -148,7 +146,7 @@ export class EngineTwig implements PatternLabEngine {
  }
  }
 
- spawnFile(config: PatternLabConfig, fileName: string): void {
+ private spawnFile(config: PatternLabConfig, fileName: string): void {
  const metaFilePath = path.resolve(config.paths.source.meta, fileName);
  try {
  fs.statSync(metaFilePath);

packages/engine-underscore/src/lib/engine-underscore.ts

@@ -167,7 +167,7 @@ export class EngineUnderscore implements PatternLabEngine {
  return partialIDWithQuotes.replace(edgeQuotesMatcher, '');
  }
 
- spawnFile(config: PatternLabConfig, fileName: string): void {
+ private spawnFile(config: PatternLabConfig, fileName: string): void {
  const paths = config.paths;
  const metaFilePath = path.resolve(paths.source.meta, fileName);
  try {

packages/types/src/lib/interfaces/engine.interface.ts

@@ -2,24 +2,101 @@ import { PatternLabConfig } from './pattern-lab-config.interface';
 import { Pattern, PatternData, PatternPartial } from './pattern.interface';
 
 export interface PatternLabEngine {
+ /**
+ * The unique name of the engine used to key out the engine in the pattern lab instance
+ */
  engineName: string;
+
+ /**
+ * The file extensions that this engine can render and by which patterns are loaded.
+ * e.g. ['.hbs', '.handlebars']
+ */
  engineFileExtension: string[];
+
+ /**
+ * Defines if the engine should look out for partials directly on the include sub pattern mechanism
+ * @deprecated is only used by mustache engine and will be removed in the future
+ * in favor of default behavior https://github.com/pattern-lab/patternlab-node/issues/1180
+ */
  expandPartials: boolean;
 
+ /**
+ * Render the pattern template with the given data and partials
+ * @param pattern the pattern to render
+ * @param data additional data to pass to the pattern template
+ * @param partials partials to pass to the pattern template or which need to be added to the engine)
+ * @returns the rendered pattern
+ */
  renderPattern: (pattern: Pattern, data: PatternData, partials?: PatternPartial) => Promise<string>;
+
+ /**
+ * Register a pattern to the engine so that it can be used in the render process later on
+ * @param pattern the pattern to register
+ */
  registerPartial: (pattern: Pattern) => void;
+
+ /**
+ * Fin all partials in the given pattern
+ * @param pattern the pattern to search for partials
+ * @returns the partials found in the pattern
+ */
  findPartials: (pattern: Pattern) => RegExpMatchArray | null;
+
+ /**
+ * Fin all partials with pattern parameters in the given pattern
+ * @param pattern the pattern to search for partials
+ * @returns the partials found in the pattern
+ * @deprecated is only used by mustache engine and will be removed in the future in favor
+ * of default behavior https://github.com/pattern-lab/patternlab-node/issues/1180
+ */
  findPartialsWithPatternParameters: (pattern: Pattern) => RegExpMatchArray | null;
+
+ /**
+ * Fin all list items in the given pattern
+ * @param pattern the pattern to search for list items
+ * @returns the list items found in the pattern
+ * @deprecated this feature is not supported anymore and will be removed in the future
+ * https://github.com/pattern-lab/patternlab-node/issues/1178
+ */
  findListItems: (pattern: Pattern) => RegExpMatchArray | null;
+
+ /**
+ * Fin a specific partial in the given pattern
+ * @param partialString the partial to search for
+ * @returns the pattern partial found in the pattern
+ */
  findPartial: (partialString: string) => string;
- spawnFile: (config: PatternLabConfig, fileName: string) => void;
+
+ /**
+ *
+ * @param config
+ * @returns
+ */
  spawnMeta: (config: PatternLabConfig) => void;
+
+ /**
+ *
+ * @param config
+ * @returns
+ */
  usePatternLabConfig: (config: PatternLabConfig) => void;
 }
 
 interface PatternEngineConfigBase {
+ /**
+ * The name of the npm package to load the engine from
+ */
  package: string;
+
+ /**
+ * The file extensions that this engine can render and by which patterns are loaded.
+ * e.g. ['.hbs', '.handlebars']
+ */
  fileExtensions: string[];
+
+ /**
+ * The location of extensions that should be loaded by the engine
+ */
  extend?: string | string[];
 }
 

packages/types/src/lib/interfaces/index.ts

@@ -1,3 +1,4 @@
 export * from './engine.interface';
 export * from './pattern.interface';
+export * from './pattern-lab.interface';
 export * from './pattern-lab-config.interface';

packages/types/src/lib/interfaces/pattern-lab.interface.ts

@@ -0,0 +1,16 @@
+import { PatternLabConfig } from './pattern-lab-config.interface';
+import { PatternData } from './pattern.interface';
+
+export interface PatternLab {
+ /**
+ * The configuration for this instance of Pattern Lab
+ */
+ config: PatternLabConfig;
+
+ /**
+ * The data for this instance of Pattern Lab.
+ * Functions as global data for all patterns if no local
+ * pattern specific data is provided.
+ */
+ data: PatternData;
+}