`ng*Def` properties (such as `ngInjectorDef`) are not considered part of
the public API and should not appear in the API docs. This commit adds a
filter to remove these properties from the docs metadata.
PR Close#31378
The docs examples e2e tests have been quite flaky recently. This causes
the `test_docs_examples` and `test_docs_examples_ivy` CircleCI jobs to
often fail (and block PRs) without a real reason.
This commit adds support for re-running failed docs examples e2e tests
and configures the `test_docs_examples` and `test_docs_examples_ivy`
jobs to try running each test that fails a second time, before giving up
and marking it as failed.
Closes#31841Closes#31842
PR Close#32497
This avoids warning such as the following ([example][1]):
```
warn: Invalid tags found -
doc "platform-browser/ɵBROWSER_SANITIZATION_PROVIDERS__POST_R3__" (const)
from file "platform-browser/src/browser.ts"
```
[1]: https://circleci.com/gh/angular/angular/427064
PR Close#32207
This commit switches the default value of the enableIvy flag to true.
Applications that run ngc will now by default receive an Ivy build!
This does not affect the way Bazel builds in the Angular repo work, since
those are still switched based on the value of the --define=compile flag.
Additionally, projects using @angular/bazel still use View Engine builds
by default.
Since most of the Angular repo tests are still written against View Engine
(particularly because we still publish VE packages to NPM), this switch
also requires lots of `enableIvy: false` flags in tsconfigs throughout the
repo.
Congrats to the team for reaching this milestone!
PR Close#32219
Bundle size changed in both zone.js(legacy) and zone-evergreen.js
- zone.js(legacy) package increased a little because the following feature and fixes.
1. #31699, handle MSPointer events PR
2. https://github.com/angular/zone.js/pull/1219 to add __zone_symbol__ customization support
- zone-evergreen.js package decreased because
1. the MSPointer PR only for legacy
2. the Object.defineProperty patch is moved to legacy #31660
PR Close#31975
The `setup-local` npm script uses `NgPackagesInstaller` to replace the
Angular packages with the locally built ones. Previously, it would (a)
assume that the packages were built and (b) it would do anything if the
currently installed versions already correspond to locally built
packages (even if not the latest version).
This could lead to all sorts of errors, such as:
- Confusing error messages, `dist/packages-dist/` was missing.
- Using outdated build artifacts from `dist/packages-dist/` without a
warning.
- Not installing the latest locally built packages, because the ones
installed already corresponded to locally built (but older) ones.
This commit fixes these issues by ensuring that:
- The local packages are always built before being used by
`NgPackagesInstaller`.
- The local packages are installed, even if the ones install already
correspond to local packages.
NOTE: Special `*-ci` scripts are introduced (for use on CI) that skip
building the local packages, since that step would have been taken
care of (in a more efficient way) in a previous CI step.
PR Close#31985
Previously, when `NgPackagesInstaller` needed to install the local
Angular packages to a project, it assumed the `dist/packages-dist/`
would exist and contain up-to-date built packages. I.e. it was up to the
user to have built the packages first (by running the appropriate
script).
However, many people not familiar with the `aio/` infrastructure assumed
that `yarn build-local` or `yarn build-with-ivy` would take care of all
the necessary steps.
To avoid getting confusing errors (or worse yet, using outdated local
packages), `NgPackagesInstaller` now has an option to build the packages
before using them.
One caveat is that the build script does not currently work on Windows,
so a warning is printed instead, letting the user know they need to
(somehow) take care of it themselves.
NOTE 1: Since the build script is using bazel, running it should not be
expensive if the directory is up-to-date (i.e. no changes have
been made to source code after the last build).
NOTE 2: This commit adds support for `--build-packages`, but does not
change the default behavior (not building the packages). It will
be turned on in a subsequent commit.
PR Close#31985
- Change margin to the header so that the the label aligns with the header
- Make code in API pages pre-wrap so that you can see the actual text on the screen - helps with issue #27296
- Modified text to be title case in label API to be consistent with rest of app labels
- Removed unused table of contents SCSS file
- TOC SCSS file reorg cleanup
- Soften headers font-weight in API pages
- Make linenums ordered list inside code examples always show as numbers
PR Close#31013
- Update the `stackblitz.json` config files (used for generating
Stackblitz projects and ZIP archives) to include the correct files
(taking into account the current layout of the example projects).
- Update the boilerplate files for `testing` examples to match the
current layout of the example projects.
PR Close#31937
This commit updates the necessary config files to run the angular.io and
docs tooling unit tests in random order (and fixes the tests that were
failing due to their dependence on the previous ordered execution).
Besides being a good idea anyway, running tests in random order is the
new [default behavior in jasmine@3.0.0][1], so this commit is in
preparation of upgrading jasmine to the latest version.
[1]: https://github.com/jasmine/jasmine/blob/v3.0.0/release_notes/3.0.md#breaking-changes
PR Close#31527
Adds two new helper functions that can be used when unit testing Angular services
that depend upon upgraded AngularJS services, or vice versa.
The functions return a module (AngularJS or NgModule) that is configured to wire up
the Angular and AngularJS injectors without the need to actually bootstrap a full
hybrid application.
This makes it simpler and faster to unit test services.
PR Close#16848
These filters have generic names (e.g. `filterPipes`), which do not make
their purpose obvious. Moving them to a dedicated `auto-link-filters`
directory should help with that.
PR Close#31051
Previously, our auto-linking feature would match `http` in URLs (such as
`http://...`) to the `common/http` package and automatically create a
link to that, which was undesirable. While it is possible to work around
that via `<code class="no-auto-link">http://...</code>`, most people
didn't even realize the issue.
Since in this case it is possible to reliably know it is a false match,
this commit fixes it by applying a custom auto-link filter that ignores
all docs for `http`, if it comes before `://`.
Fixes#31012
PR Close#31051
Updates the NodeJS version to the latest stable version at the time of
writing (v10.16.0). We need to update our image to use a minimum NodeJS
version of v10.15.0 because new CLI apps automatically install a non-locked
version of selenium-webdriver that now requires NodeJS >= 10.15.0 since the
latest release of 17th June 2019 (4.0.0-alpha.3).
See CI failures: https://circleci.com/gh/angular/angular/359077
PR Close#31088
Previously we just logged a warning but we should fail
to prevent silently allowing the docs to look wrong if
something changes on the CLI side of things.
PR Close#30901
The "view" links were broken because the version used to
compute the git tag for the GitHub URL included a build SHA.
Now we clean that off before using it in the URL.
The links are to the JSON schema that defines the documentation for
the command. This is accurate but confusing because the content for the
long description is stored in a separate markdown file referenced from this
schema file.
This commit adds a second set of links for the long description, if it exists,
which links directly to the markdown file.
Closes#30700
PR Close#30889
Context:
As part of the `test_docs_examples_ivy` job, we run 5 concurrent builds
on each VM (each for a different example/project). Additionally, all
example projects share the same `node_modules/` (via a symlink to
`aio/tools/examples/shared/node_modules/`), so all concurrent builds
operate on the same files.
Previously, we pre-ran ngcc with `--properties module` to process the
fesm5 bundles. Since we have switched to es2015 in 661a57d9e, we now
need the esm2015 bundles. As a result, the initial ngcc run is
redundant and ngcc runs again during each build (to process the fesm2015
bundles). Since there are 5 concurrent builds, we often end up with
multiple ngcc instances processing the same package and trying to write
to the same directories at the same time, causing a
`file already exists` error
This commit fixes it by pre-processing the esm2015 bundles, so there is
no need to re-run ngcc during each concurrent build.
Fixes#30577
PR Close#30593
There is an encoding issue with using delta `Δ`, where the browser will attempt to detect the file encoding if the character set is not explicitly declared on a `<script/>` tag, and Chrome will find the `Δ` character and decide it is window-1252 encoding, which misinterprets the `Δ` character to be some other character that is not a valid JS identifier character
So back to the frog eyes we go.
```
__
/ɵɵ\
( -- ) - I am ineffable. I am forever.
_/ \_
/ \ / \
== == ==
```
PR Close#30546
Previously, the processor that excludes certain cli commands
(`filterHiddenCommand`) was being run after the `createSitemap`
processor, resulting in those commands to be present in `sitemap.xml`,
while the actual pages where missing. This also resulted in 404s, when
search engine crawlers tried to index the missing URLs.
This commit fixes it by ensuring that the `filterHiddenCommand`
processor is run before the `createSitemap` processor.
PR Close#30395
This commit also changes the config files and their layout to
(reasonably closely) match what the cli would generate for a new app.
Related Jira issue: [TOOL-815](https://angular-team.atlassian.net/browse/TOOL-815)
PR Close#29926
The `Δ` caused issue with other infrastructure, and we are temporarily
changing it to `ɵɵ`.
This commit also patches ts_api_guardian_test and AIO to understand `ɵɵ`.
PR Close#29850
The `announcements.json` file should not be included in the sitemap and
including it causes an error in Google Search Console (because the
generated URL does not exist).
(This is a follow-up to fbef94a8e.)
PR Close#29754
Now, one can add an `@alias` tag to API docs, which tells dgeni that this
API element (usually a `const`) is really just an alias for some API element
defined elsewhere.
Dgeni will then look up this API element and copy over the properties from
the alias to the current doc.
For example, we would like to privately export an Enum from `@angular/core`
but then publicly export this from `@angular/common`:
**packages/core/private_exports.ts**
```ts
/**
* Description of this document.
*/
export enum ɵSomeEnum { ... }
```
**packages/common/public_api.ts**
```ts
import {ɵSomeEnum} from '@angular/core';
/**
* @alias core/ɵSomeEnum
*/
export const SomeEnum = ɵSomeEnum;
```
In the generated docs there will be a page for `common/SomeEnum`, which
will be rendered as an enum, rather than a const, showing the description
extracted from the `core/ɵSomeEnum`.
---
The implementation of this feature required some refactoring of the other
processing:
1. Previously `ɵ` prefixed exports were not even considered.
2. Due to 1. some processors needed to have guards added to ignore such
private exports (`addMetadataAliases` and `checkContentRules`).
3. The processing of package pages had to be reworked (and split) so that
it picked up the aliased export docs after their alias proeprties had
been copied.
See FW-1207, FW-632, #29249
PR Close#29673
Currently our plan is to skip the publish, docgen, and update steps for this package.
During RC, we'll determine if the breaking change is too difficult for users, in which case we might restore the package for another major.
PR Close#29550
PhantomJS is [not being developed any more][1] and with modern
alternatives (such as Chrome headless) there is no reason to keep it as
a dependency.
[1]: https://github.com/ariya/phantomjs/issues/15344
PR Close#29611
The API changes are due to enabling strict checks in TypeScript (via `strict: true`).
The payload size changes in `polyfills.js` are due to more browser APIs being patched in recent versions (e.g. `fetch`, `customElement v1`).
PR Close#28219
Sometimes, in ESM5 code, aliases to exported variables are used internally
to refer to the exported value. This prevented some analysis from being
able to match up a reference to an export to the actual export itself.
For example in the following code:
```
var HttpClientXsrfModule = /** @class */ (function () {
function HttpClientXsrfModule() {
}
HttpClientXsrfModule_1 = HttpClientXsrfModule;
HttpClientXsrfModule.withOptions = function (options) {
if (options === void 0) { options = {}; }
return {
ngModule: HttpClientXsrfModule_1,
providers: [],
};
};
var HttpClientXsrfModule_1;
HttpClientXsrfModule = HttpClientXsrfModule_1 = tslib_1.__decorate([
NgModule({
providers: [],
})
], HttpClientXsrfModule);
return HttpClientXsrfModule;
}());
```
We were not able to tell that the `ngModule: HttpClientXsrfModule_1` property
assignment was actually meant to refer to the `function HttpClientXrsfModule()`
declaration. This caused the `ModuleWithProviders` processing to fail.
This commit ensures that we can compile typings files using the ESM5
format, so we can now update the examples boilerplate tool so that it
does not need to compile the ESM2015 format at all.
PR Close#29092
Now that we are using package.json properties to indicate which
entry-point format to compile, it turns out that we don't really
need to distinguish between flat and non-flat formats, unless we
are compiling `@angular/core`.
PR Close#29092
You can now specify a list of properties in the package.json that
should be considered (in order) to find the path to the format to compile.
The build marker system has been updated to store the markers in
the package.json rather than an additional external file.
Also instead of tracking the underlying bundle format that was compiled,
it now tracks the package.json property.
BREAKING CHANGE:
The `proertiesToConsider` option replaces the previous `formats` option,
which specified the final bundle format, rather than the property in the
package.json.
If you were using this option to compile only specific bundle formats,
you must now modify your usage to pass in the properties in the package.json
that map to the format that you wish to compile.
In the CLI, the `--formats` is no longer available. Instead use the
`--properties` option.
FW-1120
PR Close#29092
With 63fb6c08cf1d69f912a0a4e9a28846d6e6985d04, the bug that required
us to temporarily disable these two SystemJS JIT tests has been fixed.
Therefore we can re-enable these tests.
PR Close#29083
As a side effect of 09b34bae8655d4251516655c317b150c46cd3653,
we fixed that the docs systemjs examples currently do not run
with Ivy in JIT mode. This now uncovered new failures with the JIT
resource loading. e.g.
```
zone.js:665 Unhandled Promise rejection: Component 'PhoneListComponent' is not resolved:
- templateUrl: ./phone-list.template.html
Did you run and wait for 'resolveComponentResources()'? ; Zone: <root> ; Task: Promise.then ; Value: Error: Component 'PhoneListComponent' is not resolved:
- templateUrl: ./phone-list.template.html
Did you run and wait for 'resolveComponentResources()'?
at Function.get (directive.ts:54)
at getComponentDef (definition.ts:648)
at verifyDeclarationsHaveDefinitions (module.ts:185)
at Array.forEach (<anonymous>)
at verifySemanticsOfNgModuleDef (module.ts:159)
at Function.get (module.ts:132)
at getInjectorDef (defs.ts:181)
at R3Injector.processInjectorType (r3_injector.ts:230)
at eval (r3_injector.ts:114)
at eval (r3_injector.ts:451) Error: Component 'PhoneListComponent' is not resolved:
```
We temporarily disable these two failing SystemJS examples by adding them to the
`fixmeIvyExamples` list.
PR Close#28984
Currently when adding the example boilerplate to all
examples with Ivy enabled, we run Ngcc and transform
all found formats. This potentially slows down the build and
is not necessary as we only need the "fesm5" and "fesm2015" bundles.
PR Close#28984
Angular supports using <style> and <link> tags inline in component
templates, but previously such tags were not implemented within the ngtsc
compiler. This commit introduces that support.
FW-1069 #resolve
PR Close#28997
Previously, `ng-packages-installer` would replace the version ranges for
all dependencies that were peer dependencies of an Angular package with
the version range used in the Angular package. This effectively meant
that the pinned version (from `yarn.lock`) for that dependency was
ignored (even if the pinned version satisfied the new version range).
This commit reduces non-determinism in CI jobs using the locally built
Angular packages by always using pinned versions of dependencies for
Angular package peer dependencies if possible.
For example, assuming the following versions for the RxJS dependency:
- **aio/package.json**: `rxjs: ^6.3.0`
- **aio/yarn.lock**: `rxjs@^6.3.0: 6.3.3`
- **@angular/core#peerDependencies**: `rxjs: ^6.0.0`
...the following versions would be used with `ng-packages-installer`:
- Before this commit:
- **aio/package.json**: `rxjs: ^6.0.0`
- **node_modules/rxjs/**: `6.4.0` (latest version satisfying `^6.0.0`)
- After this commit:
- **aio/package.json**: `rxjs: ^6.3.0`
- **node_modules/rxjs/**: `6.3.3` (because it satisfies `^6.0.0`)
PR Close#28510
`ng-packages-installer` can be used to replace Angular packages with
locally built ones (from `dist/packages-dist/`) along with their peer
dependencies.
Previously, in order to achieve this, `yarn install` was called with the
`--no-lockfile` option, which resulted in installing the latest versions
of all dependencies (including transitive ones) permitted by the
corresponding version ranges in `package.json` files. As a result, newly
released versions would be picked, resulting in unexpected,
non-deterministic breakages in CI.
This commit calls `yarn install` with the `--pure-lockfile` option
instead. As a result, only the Angular packages (for which the locally
built ones are used) and their peer dependencies are unpinned; the
pinned versions from `yarn.lock` are used for all other (direct and
transitive) dependencies.
While this does not eliminate non-determinism across builds, it
significantly reduces it.
PR Close#28510
Since b43f8bc7d, RxJS does not need to be patched any more in the
top-level `node_modules/`, so we don't need to special-case RxJS in
`ng-package-installer` and use `node_modules/rxjs/`.
PR Close#28510
By default, `webdriver-manager update` will download the latest
ChromeDriver version, which might not be compatible with the Chrome
version included in the [docker image used on CI], causing CI failures.
Previously, we used to pin the ChromeDriver version on CI in
[ngcontainer's Dockerfile][2]. This was accidentally broken in #26691,
while moving from ngcontainer to default CircleCI docker images.
This commit fixes the issue by pinning ChromeDriver to a known
compatible version.
[1]: bfd48d156d/.circleci/config.yml (L16)
[2]: bfd48d156d/tools/ngcontainer/Dockerfile (L63)
PR Close#28494
Previously, cli-based docs examples were tested using `yarn e2e ...`. In
some cases, it might make sense to run different or additional checks
for a docs example (when running `yarn example-e2e` in `aio/`).
Currently, the only option is to define a custom project type and
overwrite the `e2e` yarn script in `package.json`. Doing so (in addition
to being cumbersome and verbose) would also end up in the `.zip` archive
that users can download to run the example locally. This would be
confusing, if these custom tests are specific to our CI needs.
This commit adds support for defining a custom list of commands per
example. These commands (if specified) would be run instead of the
default `yarn e2e ...`, when testing the docs examples on CI (via
`yarn example-e2e`).
(This feature will be used to verify that the
`service-worker-getting-started` example is set up correctly in a
subsequent commit, but can be useful in other cases as well.)
PR Close#28020
File overwrites:
- **angular.json**: Add `serviceWorker: true` to production config.
- **package.json**: Add `@angular/service-worker` to dependencies.
This will make any `service-worker` examples work out-of-the-box, when
downloading and running locally from the `.zip` archives.
PR Close#28020
Some engineers were already on Yarn 0.10.x which was permitted by the range in our package.json#engines
However this introduced 'integrity sha512' lines into the yarn.lock files.
Then when engineers use yarn 0.9 (in particular, Bazel did this) then the lock files get tons of meaningless edits.
We could force everyone back to yarn 0.9 but this commit chooses to instead advance everyone past 0.10
PR Close#27193
In some overloads, the parameter type can be a large anonymous
object type.
This change displays such types as `object`. It is then up to the
documentation author to put more information about the type in the
method usage notes.
PR Close#24976
* Make individual overloads collapsible
* Show only the first overload expanded, rest collapsed
* Text changes to 'collapse all' once 'show all' is clicked
* Fix chevron/carrot rotation animation when overloads / overload item is expanded or collapsed
PR Close#24976
Some of the text in CLI API docs were being auto-linked to API
pages. This was not correct, and in fact these blocks should not
have any auto links to Angular API at all.
Closes#26570
PR Close#26675
This commit includes the following changes:
* CLI version information is read from the CLI package from which
we read the help files.
* CLI API pages now contain GH links
* line numbers are not shown in GH links, if the doc does not
have a truthy `startingLine` value. This allows us to remove
hard coded checks for `guide` pages
* content pages and CLI api docs no longer have a `startingLine`
* the hard-coded `packages` path segment has been removed from
the templates; instead we now only use the `realProjectRelativePath`.
* the `realProjectRelativePath` has been updated accordingly for API
and CLI API docs.
PR Close#26515
Since #26396, the `title` property is ignored and `header` should be
used instead for specifying a code snippet's header.
This commit ensures that we don't accidentally set `title` have it be
silently ignored.
PR Close#26514
This commit also removes the extra jasminewd2 typings, since the changes
have been merged in the official typings with
DefinitelyTyped/DefinitelyTyped#28957.
PR Close#26139
Santosh Yadav
JiaLiPassion
George Kalpakas
Stephen Fluin
Joey Perrott
Alex Rickabaugh
JiaLiPassion
Stefanie Fluin
Adrien Crivelli
Pete Bacon Darwin
Rudolf Olah
Brandon
Kapunahele Wong
Paul Gschwendtner
Michael Head
Ben Lesh
jenniferfell
Jimmy Kasprzak
arjunyel
Dustin M. Eastway
Filipe Silva
Alex Eagle
Judy Bogart
Greg Magolan
Adam Plumer
Marc Laval
jithil-kore
Alan Agius
WilliamKoza
Alex Eagle
William Marques