Cleans up AIO's Sass files by:
* Switching them all over to the `@use`-based API from Angular Material.
* Removing the import of the Material theming API in a bunch of places that weren't using it.
* Migrating the new usages of Sass utility functions to the new syntax (e.g. `map.get` vs `map-get`).
* Fixing a few files that were using 4 spaces for indentation instead of 2.
PR Close#42442
This commit removes the `_typography-theme.scss` file that is currently
not used. The file contains a single Sass mixin
(`docs-site-typography-theme()`), which is never called.
PR Close#42396
This commit includes some minor refactorings and style changes as a
follow-up to PR #41129. (The changes were minor enough that didn't
warrant blocking the PR.)
PR Close#42396
This commit fixes some linting warning that were printed when running
`ng lint`. The warnings can be seen in the `lint` step of
[this CI job][1].
Most of the warnings were related to the deprecation of passing context
to Jasmine matchers in favor of using the [withContext()][2] matcher
(introduced in Jasmine v3.3.0).
[1]: https://circleci.com/gh/angular/angular/995543
[2]: https://jasmine.github.io/api/3.3/matchers.html#withContext
PR Close#42359
I intentionally did not change the font size as discussed in #41196
because the current
font size is already about the same as the normal text size.
Fixes#41196
PR Close#42297
It is important to use the correct major version of the Angular CLI when
following the examples in the tutorials. This commit provides a custom
element that renders an appropriate dist-tag in the setup step of
the tutorial when the docs are not in "stable" mode.
Fixes#39821
PR Close#41991
After the changes to the `lang-none` styling in #41335, code snippets marked with
```
language="none" class="code-shell"
```
were being styled with the same foreground and background colours.
It turns out that most of these ought to be marked `language="sh"`
in which case the `code-shell` style became redundant and has been
removed.
Fixes#41984
PR Close#41986
This commit adds support for skipping formatting in `<aio-code>`
elements (which are used by `<code-example>` and `<code-pane>` elements
under the hood) by specifying the `language` option as `'root'`.
This is useful for code-snippets that include plain text.
PR Close#41335
With this change we add the `assert` polyfill which is required because `timezone-mock` is a Node.JS library which is being used in Browser.
PR Close#41764
This commit simplifies a regex used in angular.io's search WebWorker. It
also updates some comments to add more context on what the code does.
PR Close#41693
Previously, the search index info file contained an array of strings that is
the dictionary of terms in the corpus.
Storing this as a space separated string reduces the size of the file.
PR Close#41447
The AIO search index is built in a WebWorker on the browser from a set
of page information that is downloaded as a JSON file (`search-data.json`).
We want to keep this file as small as possible while providing enough
data to generate a useful index to query against.
Previously, we only included one copy of each (non-ignored) term from each
doc but this prevents more subtle ranking of query results, since the number
of occurences of a term in a doc is lost.
This commit changes the generated file in the following ways:
- All non-ignored terms are now included in the order in which they appear
in the doc.
- The terms are indexed into a dictonary to avoid the text of the term being
repeated in every doc that contains the term.
- Each term is pre-"stemmed" using the same Porter Stemming algorith that the
Lunr search engine uses.
The web-worker has been updated to decode the new format of the file.
Now that all terms are included, it may enable some level of phrase based
matching in the future.
The size of the generated file is considerably larger than previously, but
on production HTTP servers the data is sent compressed, which reduces the
size dramatically.
PR Close#41368
This commit tries to improve the search results by processing
the query and attempting progressively less restrictive searches
until a non-zero set of pages is matched.
The new procesing includes:
* stripping off quote marks, which were causing searches to fail
* first attempting to match pages where ALL the query terms exist
* second attempting to match pages where ANY of the query terms exist
* third attempting to match pages where the title contains partial word matches
The first query attempt approximates, quite well, the idea of searching
for multi-word phrases. This is given the technical nature of the terms
and the fairly small size of the corpus.
PR Close#41368
Previously, the max width of the `file-not-found` page was limited to
50rem (800px by default). This allowed little space for showing
potentially helpful search results, which are shown in columns).
This commit increases the max width of the `file-not-found` page to
84rem (1344px by default) to allow search results to be visible without
requiring scrolling. This will not negatively affect UX, because the
page uses a multi-column layout and therefore there will rarely be long
lines of text to scan.
PR Close#41275
Before #41162, angular.io was broken on IE 11 due to missing a polyfill
for an API (`Reflect.construct()`) needed by the Custom Elements ES5
shim. #41162 tried to fix this by loading the necessary polyfill
(`es.reflect.construct.js`) on browsers that do not support ES2015
modules (including IE 11).
It turns out that the fix in #41162 was itself broken, because the
`es.reflect.consruct.js` script (included directly in the page via a
`<script>` tag) was in CommonJS format (which cannot run in the browser
as is). By chance, this still allowed browsers that supported neither
Custom Elements nor ES2015 modules (such as IE 11) to work correctly as
a side-effect of loading the `@webcomponents/custom-elements` polyfill
after the Custom Elements ES5 shim (`native-shim.js`). However, on the
few browsers that natively support Custom Elements but not ES2015
modules, angular.io would still be broken.
This commit correctly fixes angular.io on all browsers by properly
bundling the polyfills and transpiling to ES5.
Implementation-wise, we use [esbuild][1] for bundling the polyfills (and
converting from CommonJS to a browser-compatible, IIFE-based format) and
[swc][2] for downleveling the code to ES5 (since `esbuild` only supports
ES2015+).
[1]: https://esbuild.github.io/
[2]: https://swc.rs/
PR Close#41183
Previously, the generated `404.html` page did not include a `<body>`
tag. In some browsers (such as IE 11), this was causing warnings in the
console.
This commit ensures the generated page contains a `<body>` tag. It also
fixes the indentation in the generated page.
PR Close#41163
Previously, the angular.io app was broken on IE 11. In particular, pages
that included Custom Elements would fail to load, because the
`Reflect.construct()` method (which the Custom Elements ES5 shim relies
on) was not available.
This commit fixes this by loading the polyfill for `Reflect.construct()`
on browsers that do not support ES2015 (including IE 11).
PR Close#41162
The custom elements spec is not compatible with ES5 style classes. This
means ES2015 code compiled to ES5 will not work with a native
implementation of Custom Elements. To support browsers that natively
support Custom Elements but not ES2015 modules, we load
`@webcomponents/custom-elements/src/native-shim.js`, which minimally
augments the native implementation to be compatible with ES5 code.
(See [here][1] for more details.)
Previously, the shim was included in `polyfills.ts`, which meant it was
loaded in all browsers (even those supporting ES2015 modules and thus
not needing the shim).
This commit moves the shim from `polyfills.ts` to a `nomodule` script
tag in `index.html`. This will ensure that it is only loaded in browsers
that do not support ES2015 modules and thus do not needed the shim.
NOTE:
This commit also reduces size of the polyfills bundle by ~400B
(52609B --> 52215B).
[1]: https://www.npmjs.com/package/@webcomponents/custom-elements#es5-vs-es2015
PR Close#41162
Previously, the indentation of code snippets in the "Cheat sheet" guide
was done using `<br>` elements (for line breaks) and ` ` HTML
entities (for space). This was laborious and put the onus on the author
to remember to use these symbols (instead of regular whitespace
characters).
(Discussed in
https://github.com/angular/angular/pull/41051#discussion_r585651621.)
This commit changes the way `<code>` elements are styles inside the
"Cheat sheet" guide to allow using regular whitespace characters in code
snippets. It also changes all `<br>`/` ` occurrences to `\n`/` `
respectively to make code snippets more readable in the source code.
PR Close#41051
The "Features" page organizes features in groups/rows of 3 features
each. On wide screens, all 3 paragraphs of a group/row can be shown next
to each other. On narrow screens (between 768px and 1057px), the layout
changes to stack the paragraphs vertically. On medium screens, however,
there is not enough space to show more than two paragraphs next to each
other.
Previously, the 3rd paragraph was wrapped over to the next line.
This commit improves the layout on medium screens by switching to
immediately stacking the paragraphs vertically as soon as there is not
enough space for them to be displayed in one row. Since the total width
is still too much for one paragraph, the paragraphs are limited to 80%
of the total width.
Before (on 1000px width): [features page (on 1000px) before][1]
After (on 1000px width): [features page (on 1000px) after][2]
[1]: https://user-images.githubusercontent.com/8604205/109825316-62128a00-7c42-11eb-8391-650201257274.png
[2]: https://user-images.githubusercontent.com/8604205/109825323-6343b700-7c42-11eb-86c1-e8307c5a727a.png
PR Close#41051
Previously, with the min width of 220px per item, several API list items
were truncated.
This commit increases the min width per item to 330px, which allows
almost all items to have their full text shown. It also increases the
API list page's max content width from 50em (800px) to 62.5em (1000px)
to allow items to be shown on three columns despite their increased
width. This increase in the content width shouldn't negatively affect
UX, since the API list page uses a multi-column layout (i.e. it does not
contain 1000px-lines of text.)
Before: ![api-list before][1]
After: ![api-list after][2]
[1]: https://user-images.githubusercontent.com/8604205/109396457-5f5e1f00-793a-11eb-80cf-1418f409325a.png
[2]: https://user-images.githubusercontent.com/8604205/109396659-499d2980-793b-11eb-95d3-f54250f7fab5.png
PR Close#41051
Previously, each marketing page used a different limit for its content's
width (if it had a limit at all) and implemented the width limiting in a
different way. Besides resulting in an inconsistent UX, this also made
it difficult to apply site-wide layout changes.
This commit makes the limit for most marketing pages consistent and uses
the same CSS class to make it easier to apply site-wide changes in the
future. The chosen limit is slightly larger than that of docs pages
(62.5em/1000px vs 50em/800px), because marketing pages have a different
type of content and layout (i.e. images, multi-column layout, etc.).
Finally, this commit also removes obsolete wrapper elements, CSS classes
and CSS styles, that are no longer necessary after the changes.
Notably, the homepage (`/`) and the "Contributors" page (`/about`) have
remained unchanged, because the former has its own layout that is
different from other marketing pages and the latter would offer a worse
UX with a small content width limit (as the one used on other marketing
pages).
The content widths of the rest of the marketing pages change slightly as
a result of the changes in this commit, but not in a way that would have
a negative impact on UX. More specifically:
| Page (URL) | Size before | Size after |
|:--------------|------------:|-----------:|
| `/contribute` | 880px | 1000px |
| `/events` | unlimited | 1000px |
| `/features` | 996px | 1000px |
| `/presskit` | 800px | 1000px |
| `/resources` | 800px | 1000px |
PR Close#41051
This commit removes an unnecessary wrapper `<div>` from the
"Cheat sheet" guide. The CSS styles that referenced the element's ID
(`#cheatsheet`) have been updated to use `.page-guide-cheatsheet`
instead.
PR Close#41051
Previously, styling of `<code>` elements utilized the `:not()` CSS
pseudo-class with multiple selectors (`:not(h1, h2, ...)`). It turns out
that older browsers (such as IE11) do not support multiple selectors in
a single `:not()` instance.
(See [MDN][1] and [CanIUse][2] for more info.)
This commit fixes `<code>` styling to use multiple separate `:not()`
instances instead (`:not(h1):not(h2)...`), so that they are styled
correctly on older browsers as well.
NOTE:
This change seems to trigger some kind of bug in LightHouse that causes
the a11y score of `/start` to be calculated as 0 (which is clearly
wrong). This happens on Linux (tested on CI and locally using the
Windows Subsystem for Linux (WSL)) - on Windows the score is computed
correctly as 98/100.
([Example failure][3])
The bug seems to be related to the layout of the content and goes away
if we change the viewport size (for example, switching to LightHouse's
`desktop` config) or make another change that affects the content's
layout (for example, reducing the padding of `<code>` elements).
To work around the issue, this commit updates the `test-aio-a11y.js`
script to test `/start-routing` instead of `/start`.
[1]: https://developer.mozilla.org/en-US/docs/Web/CSS/:not#description:~:text=Using%20two%20selectors
[2]: https://caniuse.com/css-not-sel-list
[3]: https://circleci.com/gh/angular/angular/931038
PR Close#41051
