docs(nxdev): support x-priority schema options (#14405)

nx-dev/feature-package-schema-viewer/src/lib/parameter-view.tsx

@@ -18,7 +18,7 @@ export const ParameterView = (props: {
   lookup: Lookup;
 }) => (
   <div key={'property-' + props.name} className="mb-8">
-    <div className="mb-2 flex items-center">
+    <div className="mb-1 flex items-center">
       <Heading3 title={props.name} />
       <div className="ml-4 flex-grow space-x-2">
         {props.alias && (
@@ -46,8 +46,8 @@ export const ParameterView = (props: {
         )}
       </div>
     </div>
-    <div className="mb-2 text-sm">
-      <div className="mb-1 text-green-600">
+    <div className="mb-1 text-sm">
+      <div className="mb-0.5 text-green-600">
         <Type
           s={props.schema}
           reference={props.reference}
@@ -60,7 +60,7 @@ export const ParameterView = (props: {
       )}
     </div>
 
-    <div className="prose prose-slate dark:prose-invert max-w-none">
+    <div className="prose prose-slate dark:prose-invert -mt-4 max-w-none">
       {
         renderMarkdown(props.description, {
           filePath: '',
@@ -84,7 +84,7 @@ export const ParameterView = (props: {
 function ParameterMetadata({ schema }: { schema: JsonSchema }) {
   const data = getParameterMetadata(schema);
   return !!data.length ? (
-    <div className="mb-1">
+    <div className="mb-0.5">
       {data.map((i) => (
         <span key={i.key}>
           {i.name}: <code>{i.value}</code>
@@ -103,7 +103,7 @@ function ParameterEnums({
 }) {
   const potentialEnums = (getEnum(schema, lookup) as string[]) ?? [];
   return !!potentialEnums.length ? (
-    <div className="mb-1">
+    <div className="mb-0.5">
       Accepted values:{' '}
       {potentialEnums.map((e, i) => (
         <span key={'enums-' + e}>

nx-dev/feature-package-schema-viewer/src/lib/schema-viewer.tsx

@@ -2,12 +2,103 @@ import {
   getDescriptionForSchema,
   getSchemaFromResult,
   Lookup,
+  LookupResult,
 } from '@nrwl/nx-dev/data-access-packages';
 import { JsonSchema, JsonSchema1 } from '@nrwl/nx-dev/models-package';
 import { ParameterView } from './parameter-view';
 import { shouldShowInStage, Stage } from './stage';
 import { Type } from './types/type';
 
+interface PropertySchema extends JsonSchema1 {
+  alias?: string;
+  'x-deprecated'?: boolean;
+  'x-priority'?: 'important' | 'internal';
+}
+
+interface PropertyModel {
+  alias: string;
+  initialSchema: PropertySchema;
+  isRequired: boolean;
+  lookupResult: LookupResult;
+  propertyName: string;
+  propertyReference: string;
+}
+
+const isPropertyDeprecated = (schema: PropertySchema | JsonSchema): boolean =>
+  typeof schema === 'boolean' ? false : !!schema['x-deprecated'];
+const getPropertyAlias = (schema: PropertySchema | JsonSchema): string => {
+  if (typeof schema === 'boolean' || schema.alias === undefined) return '';
+  return String(schema.alias);
+};
+
+function getViewModel(
+  schema: JsonSchema1,
+  lookup: Lookup,
+  reference: string
+): PropertyModel[] {
+  const properties = schema.properties || {};
+  return Object.keys(properties)
+    .sort((a, b) => a[0].localeCompare(b[0])) // Sort properties alphabetically
+    .map((propertyName) => {
+      const propertySchema = properties[propertyName] as PropertySchema;
+      const lookupResult = lookup.getSchema(propertySchema);
+      return {
+        propertyName,
+        alias: propertySchema['alias'] ?? '',
+        initialSchema: propertySchema,
+        isRequired:
+          typeof schema.required !== 'undefined' &&
+          !!schema.required.find((n) => n === propertyName),
+        lookupResult,
+        propertyReference:
+          lookupResult?.baseReference ||
+          `${reference}/properties/${propertyName}`,
+      };
+    });
+}
+
+function extractPropertiesByImportance(properties: PropertyModel[]): {
+  required: PropertyModel[];
+  important: PropertyModel[];
+  internal: PropertyModel[];
+  rest: PropertyModel[];
+} {
+  const result: {
+    required: PropertyModel[];
+    important: PropertyModel[];
+    internal: PropertyModel[];
+    rest: PropertyModel[];
+  } = {
+    required: [],
+    important: [],
+    internal: [],
+    rest: [],
+  };
+  for (const property of properties) {
+    if (property.isRequired) {
+      result.required.push(property);
+      continue;
+    }
+    if (
+      property.initialSchema['x-priority'] &&
+      property.initialSchema['x-priority'] === 'important'
+    ) {
+      result.important.push(property);
+      continue;
+    }
+    if (
+      property.initialSchema['x-priority'] &&
+      property.initialSchema['x-priority'] === 'internal'
+    ) {
+      result.internal.push(property);
+      continue;
+    }
+    result.rest.push(property);
+  }
+
+  return result;
+}
+
 export function SchemaViewer({
   schema,
   reference,
@@ -19,38 +110,17 @@ export function SchemaViewer({
   lookup: Lookup;
   stage: Stage;
 }): JSX.Element {
-  const properties = schema.properties || {};
-  const isDeprecated = (schema: JsonSchema): boolean =>
-    typeof schema === 'boolean' ? false : !!schema['x-deprecated'];
-  const getAlias = (schema: JsonSchema): string =>
-    typeof schema === 'boolean' ? '' : (schema['alias'] as string);
+  const properties = getViewModel(schema, lookup, reference).filter((p) => {
+    if (p.lookupResult === undefined) {
+      return true;
+    }
+    return shouldShowInStage(stage, p.lookupResult.schema);
+  });
 
-  const renderedProps = Object.keys(properties)
-    .sort((a, b) => a[0].localeCompare(b[0])) // Sort properties alphabetically
-    .map((propertyName) => {
-      const propertySchema = properties[propertyName];
-      const lookupResult = lookup.getSchema(propertySchema);
-      return {
-        propertyName,
-        alias: ((properties[propertyName] as any)['alias'] as string) ?? '',
-        initialSchema: propertySchema,
-        lookupResult,
-        propertyReference:
-          lookupResult?.baseReference ||
-          `${reference}/properties/${propertyName}`,
-      };
-    })
-    .filter((p) => {
-      if (p.lookupResult === undefined) {
-        return true;
-      }
-      return shouldShowInStage(stage, p.lookupResult.schema);
-    })
-    .map((p) => {
-      const isRequired =
-        typeof schema.required !== 'undefined' &&
-        !!schema.required.find((n) => n === p.propertyName);
+  const categorizedProperties = extractPropertiesByImportance(properties);
 
+  function renderProps(properties: any[]): JSX.Element[] {
+    return properties.map((p) => {
       if (p.lookupResult) {
         return (
           <ParameterView
@@ -58,8 +128,8 @@ export function SchemaViewer({
             alias={p.alias}
             name={p.propertyName}
             description={getDescriptionForSchema(p.lookupResult.schema)}
-            required={isRequired}
-            deprecated={isDeprecated(p.lookupResult.schema)}
+            required={p.isRequired}
+            deprecated={isPropertyDeprecated(p.lookupResult.schema)}
             schema={p.lookupResult.schema}
             reference={p.propertyReference}
             lookup={lookup}
@@ -70,10 +140,10 @@ export function SchemaViewer({
           <ParameterView
             key={p.propertyName}
             alias={p.alias}
-            deprecated={isDeprecated(p.initialSchema)}
+            deprecated={isPropertyDeprecated(p.initialSchema)}
             name={p.propertyName}
             description={getDescriptionForSchema(p.initialSchema)}
-            required={isRequired}
+            required={p.isRequired}
             schema={p.initialSchema}
             reference={p.propertyReference}
             lookup={lookup}
@@ -81,6 +151,14 @@ export function SchemaViewer({
         );
       }
     });
+  }
+
+  const renderedProps = renderProps([
+    ...categorizedProperties.required,
+    ...categorizedProperties.important,
+    ...categorizedProperties.rest,
+    ...categorizedProperties.internal,
+  ]);
 
   const additionalProperties = new Array<JSX.Element>();
   if (typeof schema.additionalProperties === 'boolean') {
@@ -113,8 +191,8 @@ export function SchemaViewer({
           name="Additional Properties"
           description={getDescriptionForSchema(additionalPropertiesResult)}
           required={false}
-          alias={getAlias(additionalPropertiesResult.schema)}
-          deprecated={isDeprecated(additionalPropertiesResult.schema)}
+          alias={getPropertyAlias(additionalPropertiesResult.schema)}
+          deprecated={isPropertyDeprecated(additionalPropertiesResult.schema)}
           schema={additionalPropertiesResult.schema}
           reference={resolvedReference}
           lookup={lookup}
@@ -133,8 +211,8 @@ export function SchemaViewer({
         <ParameterView
           key={`pattern-properties-${i}`}
           name={`/${pattern}/ (keys of pattern)`}
-          alias={getAlias(currentSchema)}
-          deprecated={isDeprecated(currentSchema)}
+          alias={getPropertyAlias(currentSchema)}
+          deprecated={isPropertyDeprecated(currentSchema)}
           description={getDescriptionForSchema(schema)}
           required={false}
           schema={currentSchema}

nx-dev/models-package/src/lib/package.models.ts

@@ -79,9 +79,7 @@ export interface SchemaMetadata {
 }
 
 export interface NxSchema extends JsonSchema1 {
-  title: string;
   description: string;
-  presets: { name: string; keys: string[] }[];
   examplesFile: string;
   hidden: boolean;
 }