Updates AIO and the live examples to 13.1.0 in order to resolve a build error when opened on Stackblitz. They were using TS 4.5 with Angular ~13.0.0 which doesn't support 4.5.
Fixes#44480.
PR Close#44487
add 'json' to the ignoreGenericWords set so that it doesn't get
wrongly linked to the jsonPipe during the aio docs generation
as it is a generic javarscript term
PR Close#44294
Adds support for TypeScript 4.5. Includes the following changes:
* Bumping the package versions.
* Fixing a few calls to `createExportSpecifier` and `createImportSpecifier` that require an extra parameter.
* Adding some missing methods to the TS compiler hosts.
* Fixing an issue in the TS mocks for the ngcc tests where a regex was too agressive and was trying to match a path like `/node_modules/@typescript/lib-es5`.
* Accounting for type-only import specifiers when reporting DI errors (see #43620).
Fixes#43620.
PR Close#44164
In #44214, the `package.json` used to install dependencies for docs
examples was updated, but the corresponding lockfile was not.
Update the lockfile to keep it in sync with `package.json`.
PR Close#44232
In PR #43975, the `Angular Elements` guide was updated to remove
mentions of the Custom Elements-related polyfills, since they are no
longer necessary in v13+ (due to all CLI projects being ES2015+ and all
supported browsers natively supporting Custom Elements).
This commit updates the related docs example boilerplate to not include
the unneeded `@webcomponents/custom-elements` polyfill.
PR Close#44214
If there were 1 or 2 additional overloads on a free-standing function in the API the overloads were not being shown.
Also the type of overload parameters were not being escaped correctly.
PR Close#44090
add 'number' to the ignoreGenericWords set so that it doesn't get
wrongly linked to the decimalPipe during the aio docs generation
as it is a generic typescript term
PR Close#44000
Linting has recently been removed from the examples provided in angular.io
(see PRs #43592 and #43746) such removal effects the downloadable and
stackblitz examples but linting is still generally used in the examples
in the aio project itself (they are being migrated from tslint to eslint in
PR #43218) thus eslint directive comments are still necessary in the code itself.
So the comments need to be present but need not to be exposed to the users
(not in the zips, stackblitzes nor docs themselves), these changes are
removing such comments during the examples' parsing phase (effectively
removing them from all three sources mentioned above).
Original discussion: https://github.com/angular/angular/pull/43218#discussion_r697305494resolves#43788
PR Close#43831
Previously, the SystemJS-based docs examples (typically `ngUpgrade`
examples) were not compatible with Angular v13 (due to the removal of
UMD bundles from the published packages).
This commit makes the examples compatible with Angular v13 and
re-enables the tests for all SystemJS-based examples on CI.
PR Close#43868
Due to an oversight, the `systemjs` package was previously not included
as a dependency in the boilerplate `package.json` file for
SystemJS-based docs examples, despite it being required by the app.
PR Close#43868
Use the cross-platform `copyfiles` package instead of using `cp` which fails on Windows machines when copying files in the `postbuild` script of the "schematics-for-libraries" example.
PR Close#30966
This commit updates the necessary config settings to allow `.mjs` files to be able to be parsed by the region parser. We configure the parser to use `inline-c-only` so that comments are generated in like the below
```
// #docregion
```
rather than
```
/* #docregion */
```
PR Close#44027
This commit changes the Stackblitz live examples to create "webcontainer" projects on Stackblitz.
This approach supports the new Angular v13 packaging formats but webcontainers are not supported on some browers. So this is a temporary solution.
PR Close#44041
This commit updates the docs examples to the latest prerelease versions
of Angular CLI, framework and CDK/Material.
It also updates the apps to more closely align with new apps CLI apps.
See also the [diff][1] between a basic v13.0.0-rc.0 CLI app and a
v13.0.0-rc.2 one.
[1]: cexbrayat/angular-cli-diff@13.0.0-rc.0...13.0.0-rc.2
PR Close#43583
This commit enable the `noImplicitOverride` and
`noPropertyAccessFromIndexSignature` TypeScript compiler options for
docs examples to better align with the default configuration of new
Angular CLI apps. It also makes the necessary changes to the docs
examples source code.
PR Close#43880
This commit updates the docs examples to Angular v13.0.0-rc.0. In
addition to updating the dependency versions, it also updates the
projects' structure and configs to more closely match what a new v13 CLI
app would look like. See, also, the [diff][1] between a basic v12.1.3
CLI app and a v13.0.0-rc.0 one.
(NOTE: v12.1.3 was the last version for which we aligned the projects
with how a new CLI app would look like.)
Additionlly:
- Since we now use RxJS v7 in docs examples, this commit removes the
extra CI steps to explicitly test the docs examples against RxJS v7.
- Since Angular v13 no longer supports IE, this commit removes an
IE-specific section from `upgrade-setup.md`.
[1]: https://github.com/cexbrayat/angular-cli-diff/compare/12.1.3..13.0.0-rc.0
PR Close#43880
Fix incorrect escape of special characters when rendering member heritage docs. Example: DefaultIterableDiffer docs incorrectly renders what this class implements - it does not fully display generic types of implemented interfaces.
PR Close#43956
This commit helps to make the section that describes an overview of the syntax of a CLI command stand out from the surrounding text.
Closes#26574
PR Close#43850
remove the deprecated tslint from the examples of type systemjs
note: eslint hasn't be applied and linting has been removed entirely
to follow angular's unopinionated view on linting
PR Close#43746
When the docs examples tests run with `--cliSpecsConcurrency` greater
than 1 (as happens on CI), the output of each process is [buffered][1]
(to avoid interleaved output from multiple, parallel processes) and is
only printed out once the process exits (either successfully or with an
error). However, in cases where a process did not exit, the buffered
output would be never printed out, thus making debugging the failure
harder. This is the case, for example, if a build error happens during
`ng e2e`. This can be seen in action in [this CI job][2], where the job
fails due to no output, but the error (which is an incompatible TS
version) is never printed out.
To make debugging such situations easier in the future, this commit
updates the `spawnExt()` helper to reject (causing the buffered output
to be printed out) if there is no output from the spawned process for
more than 5 minutes.
[1]: c721135e37/aio/tools/examples/run-example-e2e.mjs (L293)
[2]: https://circleci.com/gh/angular/angular/1061751
PR Close#43683
In the API docs, concrete classes do not list the "implementation" overload on a method, since this is not strictly part of its API.
We recently fixed the rendering of interfaces to display all the overloads, since there is no "implementation" overload.
This commit also fixes the rendering of "pseudo-classes", which are a combination of an interface
and a constant.
Fixes#43001
PR Close#43734
Bumps the minimum required TypeScript version to 4.4.2 and removes the integration tests for 4.1, 4.2 and 4.3.
BREAKING CHANGE:
TypeScript versions older than 4.4.2 are no longer supported.
PR Close#43642
remove the deprecated tslint from the examples of type cli
note: eslint hasn't be applied and linting has been removed entirely
to follow angular's unopinionated view on linting
PR Close#43592
This commit temporarily disables the SystemJS upgrade e2e tests. All of
the upgrade e2e tests (except for `phonecat-1-typescript`) rely on UMD
bundles. These are no longer available for the v13 Angular package
output, so we disable the tests for now.
These e2e tests can be re-enabled once we migrated the exampels from
UMD bundles to e.g. the CLI, or some custom rollup build. Alternatively
it might be even possible to use FESM bundles directly (depending on
browser support for the AIO examples; this is something the docs-infra
team will have to determine though).
PR Close#43431
Adding suites to the `IGNORED_EXAMPLES` array currently results
in an runtime exception because later when ignored examples are
printed to stdout, a non-existent variable is referenced back
from when there were examples disabled due to the Ivy migration.
This commit fixes the logic.
PR Close#43431
The CLI has been updated with various changes to support for ESM package
output of the framework. This commit updates to a next version of the
CLI v13 that contains these necessary changes, allowing us to test/validate
our package changes through integration tests or AIO examples.
This update also contains a fix for the adjust enum babel optimization
that broke with the latest rollup version.
PR Close#43431
In the API docs, concrete classes do not list the "implementation" overload on a method, since this is not strictly part of its API.
There is already a special case for abstract methods that do not have such an implementation overload.
But we were missing the case where the method was part of an interface. In interfaces none of the methods have implementation overloads.
Fixes#43001
PR Close#43614
Previously, deprecation notes for deprecated class/interface properties
were not shown in the API docs. This commit fixes it by ensuring that
deprecation notes are shown for properites (similar to how it works for
methods).
PR Close#43566
It is now possible to specify file paths in the `"boilerplate-override"`
property of `example-config.json` files to tell the example boilerplate
system to use the file in the example directory rather than overwriting the
example file with that from the boilerplate directory.
PR Close#43216
This change makes docplaster markers fit better with the surrounding code
that is being rendered. Instead of:
```
{
"a": 100,
// ...
"b": 200,
// ...
}
```
you can now get
```
{
"a": 100,
// ...
"b": 200,
// ...
}
```
PR Close#43216
Now JSON files should be commented using
```
// #docregion
```
rather than
```
/* #docregion */
```
There are currently no JSON files with either kind of comments so this change
has no impact yet.
But when we add some examples with such comments, they will also benefit
from `// ... ` style docplasters to join docregion fragments.
PR Close#43216
The HTML for the docs pages is generated by Dgeni based on some
[Nunjucks][1] templates.
Previously, these templates were set up in a way that introduced a lot
excess whitespace in the generated HTML, unnecessarily bloating the
corresponding JSON files that need to be downloaded in order to view a
certain docs page. This has been discussed in #28105 and was again
observed while investigating #43285.
This commit refactors some of the templates related to API docs (which
seem to be the most affected ones) to drastically reduce the amount of
excess whitespace. More specifically, the total size of all files in
`generated/docs/api/` was reduced from ~13MB to ~7MB.
Besides the reduced payload size for each API page, this change will
also reduce the amount of memory needed by the ServiceWorker to cache
the API pages that have been visited by a user.
NOTE:
The affected files are not eagerly downloaded when navigating to
angular.io. Instead, each file is downloaded individually, as soon as a
user visits the corresponding API docs page. Therefore, the impact of
this change will be relatively small for most users.
[1]: https://mozilla.github.io/nunjucks/
PR Close#43435
NOTE:
This [version][1] includes a breaking fix ([commit af59f343d][2]). More
specifically `github-slugger` will no longer trim the text of a heading
before generating an ID and (with whitespace converted to `-`) this
results in different heading IDs:
**Before:** `<h3> foo bar </h3>` --> `<h3 id="foo-bar">...`
**After:** `<h3> foo bar </h3>` --> `<h3 id="--foo-bar--">...`
The different IDs now break some of our anchor-links, becuase
`github-slugger` is used by [rehype-slug][3], which is in turn used by
our [autolinkHeadings][4] dgeni post-processor.
To avoid the issue with broken anchor links, we update the
`renderMethodDetail()` nunjucks macro to omit excess whitespace in
headings.
[1]: https://github.com/Flet/github-slugger/releases/tag/v1.4.0
[2]: af59f343dc
[3]: https://github.com/rehypejs/rehype-slug
[4]: 75a3c778b1/aio/tools/transforms/angular-base-package/post-processors/autolink-headings.js (L3)
PR Close#43435
This commit updates the docs examples to Angular v12.1.3. In addition to
updating the dependencies versions, it also updates the projects'
structure and configs to more closely match what a new v12 CLI app would
look like. See, also, the [diff][1] between a basic v11.2.11 CLI app and
a v12.1.3 one.
[1]: https://github.com/cexbrayat/angular-cli-diff/compare/11.2.11..12.1.3
PR Close#42949
Switch the JS script used for running the docs examples tests from
CommonJS to ESM format. This is necessary for upgrading the `globby`
dependency to [version 12.0.0][1] in a subsequent commit.
[1]: https://github.com/sindresorhus/globby/releases/v12.0.0
PR Close#42921
Switch the JS scripts used for generating StackBlitz projects and zips
from CommonJS to ESM format. This is necessary for upgrading the
`globby` dependency to [version 12.0.0][1] in a subsequent commit.
[1]: https://github.com/sindresorhus/globby/releases/v12.0.0
PR Close#42921
migrate aio to eslint as tslint has been deprecated, the migration is restricted to the aio app and
its e2e tests and does not include the other tools, for such reason both tslint and codelyzer have not
been removed (to be done in a next PR)
some minor tweaks needed to be applied to the code so that it would adhere to the new ESLinting behaviour
most TSLint rules have been substituted with their ESLint equivalent, with some exceptions:
* [whitespace] does not have an ESLint equivalent (suggested to be handled by prettier)
* [import-spacing] does not have an ESLint equivalent (suggested to be handled by prettier)
* [ban] replaced with [no-restricted-syntax] as there is no (official/included) ESLint equivalent
some rules have minor different behaviours compared to their TSLint counterparts:
* @typescript-eslint/naming-convention:
- typescript-eslint does not enforce uppercase for const only.
* @typescript-eslint/no-unused-expressions:
- The TSLint optional config "allow-new" is the default ESLint behavior and will no longer be ignored.
* arrow-body-style:
- ESLint will throw an error if the function body is multiline yet has a one-line return on it.
* eqeqeq:
- Option "smart" allows for comparing two literal values, evaluating the value of typeof and null comparisons.
* no-console:
- Custom console methods, if they exist, will no longer be allowed.
* no-invalid-this:
- Functions in methods will no longer be ignored.
* no-underscore-dangle:
- Leading and trailing underscores (_) on identifiers will now be ignored.
* prefer-arrow/prefer-arrow-functions:
- ESLint does not support allowing standalone function declarations.
- ESLint does not support allowing named functions defined with the function keyword.
* space-before-function-paren:
- Option "constructor" is not supported by ESLint.
- Option "method" is not supported by ESLint.
additional notes:
* the current typescript version used by the aio app is 4.3.5, which is not supported by typescript-eslint (the supported
versions are >=3.3.1 and <4.3.0). this causes a warning message to appear during linting, this issue should
likely/hopefully disappear in the future as typescript-eslint catches up
* The new "no-console" rule is not completely equivalent to what we had prior the migration, this is because TSLint's "no-console"
rule let you specify the methods you did not want to allow, whilst ESLint's "no-console" lets you specify the methods that you do
want to allow, so and in order not to have a very long list of methods in the ESLint rule it's been decided for the time being
to simply only allow the "log", "warn" and "error" methods
* 4 dependencies have been added as they have been considered necessary (see: https://github.com/angular/angular/pull/42820#discussion_r669978232)
extra:
* the migration has been performed by following: https://github.com/angular-eslint/angular-eslint#migrating-an-angular-cli-project-from-codelyzer-and-tslin
* more on typescript-eslint at: https://github.com/typescript-eslint/typescript-eslint
PR Close#42820
improve the @usageNotes message by adding the word "is"
(outcome: "Further information is available in...", compared to
"Further information available in...")
PR Close#42888
