Closes#17245 and #17253
When the user selects a doc item in the side nav:
1) expand folder(s) leading to the selected doc item
2) on a wide display, keep other already expanded folders open
3) on narrow (mobile) display, collapse other expanded folders
Used to do (3) when wide. Issue #17245 asks for (2).
That logic was bypassed for selected node when we allowed headers to have content
because that unintentionally expanded the header’s folder when selected.
Because the selected node is no longer a header with content, removing this exclusion
also means that folders are expanded/collapsed with above logic even for API pages.
Rather than hard coding excludes into the dgeni config,
use the fact that we are already ignoring the boilerplate
and generated files via the .gitignore file.
Previously, the main content would always leave a 18% margin on the right to be
occupied by the ToC (even if there was no ToC).
This commit lets the main content expand to the right to occupy all the
available space when there is no ToC.
Fixes#17205Fixes#17270
Previously, when scrolling the ToC and reaching the top/bottom, further
mousewheel events would result in scrolling the window (and thus the main
content). This is standard browser behavior. In the case of the ToC though, the
`ScrollSpy` would detect scrolling in the main content and scroll the active ToC
to entry into view, thus resetting the scroll position of the ToC.
Reproduction:
1. Open `~/guide/template-syntax`.
2. Start scrolling through the long ToC.
3. Try to go to the bottom of the ToC.
4. Once you reach the bottom, the main content starts scrolling down.
5. The first section ("HTML in templates") becomes "active", so the ToC is
scrolled back up to make its corresponding entry visible.
6. Go back to step 2.
This commit improves the UX, by not allowing the main content to scroll when the
cursor is ovr the ToC and the user has scrolled all the way to the top/bottom of
it.
When navigating from a page with open SideNav to a page without closed SideNav,
the main content area animates from a non-zero left margin to zero left margin.
Additionally, the top-bar on the homepage is transparent, which allows the white
background behind the main content to be seen while the left margin is animated
to zero, making it appear as if something (e.g. the SideNav covers the top-bar).
This commit works around this issue, by not making the top-bar transparent
immediately when navigating to the homepage, but animating it from its blue
color to transparent with a delay.
Fixes#17248
An ellipsis was used to separate the most relevant search
results from the alphabetic list. The separator was confusing
because it was not clear what it represented.
This has been removed and the most relevant results are now
indicated by styling with a more bold font and a bit of whitespace
between them and the rest of the results.
To keep things consistent, if there are fewer than 5 results all the
results are now displayed as priorityPages.
Closes#17233
In the marketing pages we do not want to show heading anchors on hover.
Previously, this was achieved by using div rather than heading elements.
Now we can use semantically accurate headings while hiding the anchor.
Closes#17244Closes#17264
Previously, the top-bar's height wasn't taken into account when scrolling an
element into view. As a result, the element would be hidden behind the top-bar.
Taking the top-bar height into account was not necessary before #17155, because
the top-bar was not fixed (i.e. it scrolled away).
This commit fixes the scrolling behavior by accounting for the top-bar's height
when scrolling an element into view.
(This partially reverts #17102.)
Fixes#17219Fixes#17226
- Fixed topnav on all mobile
- Fixed topnav on all docs pages
- Absolute topnav on all marketing pages
- Cleanup and code consolidation for all top-menu styles
- Add styling to topnav links on focus
When more than one node matches a url, the last
node defined in the navigation.json file won. This
meant that, for instance, items in both the
TopBarNarrow and the Footer views would not
indicate that they were active.
Now, each url is associated with a map of current
nodes keyed off their view.
Closes#17022
Previously, the progress bar would be placed right under the static top bar. Now
that the top bar i not tatic any more, it makes more sense to place the progress
bar at the top of the page.
Fixes#17103
* Remove whitespace before type specifiers
* Generate `new` and `call` member info for interfaces
* Ensure that there is no double space after class names
Previously, the `#top-of-page` element (used when scrolling to top) was placed
inside the content section (which at the time had zero top margin and padding).
Furthermore, there was a top offset applied when scrolling that took the static
top bar's height into account. Since now the top bar is not static any more and
the content section has a non-zero top padding, scrolling to top does not work
as expected.
This commit fixes this by:
- Moving the `#top-of-page` element to the top of the `aio-shell`.
- Stop accounting for the top bar's top.
Fixes#17006
* fix(aio): make the search-pane larger
Fixes#17094
* feat(aio): give the search-box a type of "search"
This enables browsers to style it better (e.g. add an `x` button for clearing
the field, which allows users to quickly reset the search query and hide
results).
There seems to have been a bad rebase of #16228 on top of #16959, which affected
ToC styles from both PRs. This commit restores the horizontal line under `.h1`
elements and the vertical blue bar on the left-hand side of the ToC (with the
circle running along the bar to indicate the active section).
Fixes#17098
- Add styling for active TOC item
- Add sidenav styles
- Change header tags to divs from index marketing page to remove anchors
- Fix use of card mixin and create separate card-docs class
- Add marketing styling
- Topnav styling when on home landing page
- Remove hamburger menu on home page
- Add fully rounded border to top nav toolbar search input
- Add mobile styles
- Add title banner to other marketing pages
Use this file if we need to turn off the service worker in deployed sites
in an emergency where the worker has a bug that is blocking the application
from working.
Closes#16897
this means we'll be temporarily duplicating the helpers (onces included via scripts
and secondly imported via es imports) - once rxjs, core and material migrate over
to tslib, we can drop the scripts/global dupe.
The `TopBarNarrow` now only shows a single top level container, "About Angular",
and the original `TopBar` items will be children of this container.
The `TopBarNarrow` styling is changed to match the rest of the `SideNav`.
* refactor(aio): use explicit CSS class for TOC container
This makes the styling less fragile to changes in the HTML
* fix(aio): schedule TocComponent.activeIndex updates via AsapScheduler
We use the `asap` scheduler because updates to `activeItemIndex` are triggered by DOM changes,
which, in turn, are caused by the rendering that happened due to a ChangeDetection.
Without asap, we would be updating the model while still in a ChangeDetection handler,
which is disallowed by Angular.
* refactor(aio): do not instantiate floating ToC if not displayed
* feat(aio): display the h1 at the top of the floating TOC
Closes#16900
* refactor(aio): combine the TOC booleans flags into a "type" state
* refactor(aio): remove unnecessary `hostElement` property
* fix(aio): ensure that transition works on TOC
* fix(aio): use strict equality in ToC template
If there is a `TopBarNarrow` nav view then use this when the screen is narrow.
Otherwise just use the normal `TopBar`.
This commit also creates such a narrow topbar view where the "Docs" item is
in a different position
Closes#16940
Previously we hardcoded the current version into the navigation items.
Now only previous versions are included there. The current version is
computed from the currentVersion info.
Closes#16909
Based on optional title passed in from parent element such as CodeExample or CodeTabs.
Darkens uncovered copy button slightly as recommended for a11y.
PR #16808
- Use buttons for the TOC “Contents” label when embedded-and-expandable or TOC on the right to satisfy a11y.
- Add aria-pressed setting for the toggles in TOC and NavItem.
- Clicking the right panel TOC “Contents” button scrolls to top.
- When embedded use same rotating caret as sidebar
- When embedded and no secondaries, “Content” is just a label.
- Gray background for focused buttons rather than outline because can’t get carets to work with outline.
This commit was worked on by a number of people including
@filipesilva, @gkalpak and @wardbell. It contains changes that:
* remove unused files,
* fix the bootstrap approach to ensure that bootstrap is in the correct Zone
* fix unclosed code-example tags
* replace use of "we" with "you"
* remove broken dual router example
Related to angular/angular.io#3541
Lighthouse v1.6.5 treats localhost/1.2.7.0.0.1 as secure domains (i.e. as if they where HTTPS), so we need to stop handling the is-on-https audit specially.
In some cases (unclear when), traceviewer-js, used by Lighthouse under the hood,
assumes `atob`/`btoa` are defined in the global scope. This is true for browser
environments, but not on node.
As a result, some aggregations that required access to model-tracing failed to
produce results, dropping the overall PWA score.
This affected #16665 (e.g. commit 0de6eec7a).
If a usage of `{@link ...}` does not provide a title then
compute it based on the `title` and/or `name` properties
or set the link to invalid.
Closes#16811
Sidenav headers had been anchors w/o hrefs. These can’t take focus which makes you can’t navigate through them with keyboard. For a11y purposes, this PR turns them into buttons.
By reflex we began all component tests with an async `beforeEach` that called `compileComponents`.
In at least one case (`live-example.component.spec.ts`) that led to the `it` tests being async as well.
There is no need to call `.compileComponents` because CLI web pack + plugin inlines all templates and styles.
While `.compileComponents` was harmless, it added complexity and distraction which we should not inflict on future readers and testers.
Previously the logic for deciding when to display
the search result was spread between different
parts of the application and used non-intuitive logic
such as sending a blank results set to the searchResults.
This commit moves the management of displaying
the search results (and also setting focus of the
search input box) to the AppComponent. This makes
it easier to understand what happens and why; but
also allows the search UI components to be more
easily reused (such as embedding them in the 404
page).
(Coincidentally), this wasn't an issue before fdfeaaf1f, because
pre-verification was run after `test.sh`, during which `aio-builds-setup` was
built.
Now that `deploy-staging.sh` is being run before `test.sh`, we need to build
the `aio-builds-setup` scripts first.
Previously, `aio/aio-builds-setup/scripts/travis-preverify-pr.sh` was supposed
to exit with 1 if a PR did not meet the preconditions and 2 if an error occurred
during pre-verification.
It relied on the exit codes of the node script that did the actual work, but
didn't account for errors that would be thrown in the `sh` script itself (e.g.
if the node script was not available). This caused such errors to appear as
non-verified PRs, instead of real errors that should fail the build.
This commit swaps the exit codes, so that now a 2 means non-verified PR and 1
designates an error.
Since abb36e3cb, we no longer rely on the cli to set up ServiceWorker, but do it
manually as part of `yarn build`. When using `ng serve`, registering the
ServiceWorker fails, because we haven't created `ngsw-manifest.json` nor copied
`worker-basic.min.js` into dist.
This commit works around this, by only registering the service worker in
production mode (which is what the cli does too).
Caveat:
It is not possible to enable ServiceWorker with `ng serve`/`yarn start` and
using the `--prod` flag will try to register it, but fail because the necessary
files (`ngsw-manifest.json` and `worker-basic.min.js`) will not be available.
(As a work-around, you can use `yarn build` and serve the files in `dist/` with
`yarn http-server -- dist -p 4200`.)
Previously, no previews would be deployed for PRs that didn't touch files inside
`aio/`. Now, previews will be deployed for PRs that touch non-spec files inside
either `aio/` or `packages/` (as long as other preconditions are met).
Partially addresses #16526.
Only one h1 is allowed per document.
(Also took the opportunity to remove unnecessary blank lines from these
docs, and a bit of general tidying.)
Closes#16193
This fail behaviour is only turned on for `yarn docs`;
in `yarn docs-watch` you only receive a warning.
This is because you can get false errors when watching
since we don't parse all the docs in that case.
* fix(aio): allow code blocks to clear floated images
Previously the negative margin on the code headings were causing
floated images to overlay the start of a code block. Now all code block
successfully clear all floated elements.
* feat(aio): add a `.clear` class for clearing floating images
* fix(aio): tidy up image styles
The css rules for `img.right` and `img.left` allow authors easy
access to floating an image on the left or right, respectively.
The `.image-display` rule which was always found on a figure
has been simplified so that all figures have this styling. It is very
unlikely that a figure will be used outside the content area; and
at this time it seems like `figure` is as good an indicator that we
want this kind of styling as anything.
Now that images are all tagged with width and height values, we cannot
assume to modify these dimensions via CSS as it can cause the image to
lose its correct proportions. Until we find a better solition we must set
`height` to `auto` when the screen width is below 1300px to ensure that
these images maintain their proportions as they get shrunk to fit.
* docs(aio): general tidy up of image HTML in guides
Previously, the guides have a lot of inline image styling and unnecessary
use of the `image-display` css class.
Images over 700px are problematic for guide docs, so those have been given
specific widths and associated heights.
* docs(aio): use correct anchor for "back to the top" link
The `#toc` anchor does not work when the page is
wide enough that the TOC is floating to the side.
* build(aio): add `#top-of-page` to path variants for link checking
Since the `#top-of-page` is outside the rendered docs
the `checkAnchorLinks` processor doesn't find them
as valid targets for links.
Adding them as a `pathVariant` solves this problem
but will still catch links to docs that do not actually exist.
* fix(aio): ensure that headings clear floated images
* fix(aio): do not force live-example embedded image to 100% size
This made them look too big, generally. Leaving them with no size means
that they will look reasonable in large viewports and switch to 100% width
in narrow viewports.
closes#16608
Formerly, tried to navigate when user clicked an anchor with an image url (to view image in a new tab) resulting in 404.
Now ignores href URL with any extension and lets browser handle it.
closes#16603
As before this PR, when wide (side-by-side), the sidenav open/close status only changes when nav to/from marketing page in which case it opens for guide/api and closes for marketing page.
Fundamentals and Techniques nav groups we also links to pages. This caused
counterintuitive behaviour when clicking on them.
This commit moves each link from the group item to a children item, called
Introduction.
Closes#16604
The CSS rule for positioning the automated header links was too general,
causing other links inside headings to be positioned incorrectly.
Closes#16573
Previously the `hasToc` was initialised to true, which caused a flash of
unwanted "Contents" [sic] even if the page was not going to need a ToC.
Closes#16597
TOC appears in right panel when wide and hides embedded TOC
Right TOC panel height adjusts dynamically during scroll
Refactored `TocService` and its tests for clarity.
- Moved info bar section in pipe template to be the first section to match other templates
- Fixed label styling for type label
- Added label styling for status label
closes#16521
`LocationService` sends `GaService` a url stripped of fragment and query strings.
`GaService` already guards against re-send of the prior url so it will only report doc changes.
These utils support flexible, natural attribute interpretation as applied to code-example and code-pane. Then apply those utils to code-example and live-example
This contains a fix for the typescript module reader.
Previously, TS modules that were of the form:
```
a/b/index.ts
```
Would be given the name `index` and id of `a/b/index`.
This is not desirable, so the new version of dgeni-packages/typescript
removes this `index` from the id and name, which results in name of
`b` and id of `a/b`.
Update to in-memory-web-api should handle id=0.
Make sure this works by having a hero with id=0 in ToH.
Coincidentally delete lingering dead app/ folders
Todo: fix ToH images (which have to do anyway)
In the API docs there are occasions where we do not wish the code snippet
to have a copy button. This commit supports that by providing a new `hideCopy`
attribute.
Parse all `<img>` tags, during doc-gen, and insert the width and height of
the sourceed image, if neither are already specified.
Warnings are reported if the `<img>` tag has no `src` attribute or the image
cannot be loaded.
The work is done in the `addImageDimensions` post-processor, which must be
configured with a `basePath` so that it knows where to find the images.
Closes#15888
- Changed search result link hover state to white to be more legible
- Increased the max-height on search results container to remove the jitter
- Changed search results to have space-around vs space-between for more appropriate spacing
The autolinking is now done on the `renderedContent` which means it also
captures and autolinks headings that were generated outside of markdown.
PR Close#16336
Previously the CSS styling for material icons was too broad and affected
all instances of icons. This commit constrains the position of copy button
icons only to copy buttons.
Because:
1. `docs` feels like a "top level" page, similar to `features`, `resources`, `events` etc.
2. This enables the ServiceWorker to pre-fetch/cache the document (similar to what happens with all
other direct children of `content/docs/`), without the need for special-casing it in
`ngsw-manifest.json`.
- Banner class code consolidation for API pages
- Set up temporary table of contents class and file
- API pages title styling
- Add color styling to doc-type listed on each API details page
- Classes and SCSS variables refactor
- Mobile optimization on headers, info-banner, and API pages
- API page table custom styling
- API Class Overview template code overview into table format
- Content container now has a max width and made the body background the same offwhite color so the cut-off is not visible
- Sidenav will always remain at the left of the page
- Added a max width to the api banner of filter search inputs
- Left aligned content container so it is flush with sidenav
- Changed API filter width to match size of filter results
- Add snackbar and pointer cursor for copy code button inside aio-code components
- Flex cenetered content in features page
- Removed duplicate global css class
- Add styles to links inside of sub-sections
- Remove focus outline on top nav bar links
We were filtering this document from the docs list but
not removing it from the module export lists.
We can actually filter it out much easier at the TypeScript
parsing point, which means we do not need the
`filterIgnoredDocs` processor any more.
Closes#16287
The side nav and menu buttons need to appear early on in the loading of the page.
Currently we are using icon fonts with ligatures to get icons for these areas.
This can result in a flash of unstyled font.
By replacing these with SVG icons, we get a better user experience.
By overriding the `MdIconRegistry` we can inline the SVG source, which
means that there will never by a delay in rendering the icons.
The new `CustomMdIconRegistry` expects a multi-provider containing an array
of `SvgIconInfo` objects. These objects hold the name and SVG source of the
icon. When `MdIconComponent` requests an SVG icon we will get it from the
pre-loading cache, if available, before delegating back to the original
`MdIconRegistry`.
Note that SVG versions of `md-icon` do not apply the `material-icons` CSS
class to the element, so the styling for the icons that we are preloading
has been changed to use `.mat-icon` instead.
Closes#16100
This is to tidy up the `author-packagse`, which currently duplicates a
lot of the configuration in the main packages. We need to
DRY this up so that we don't fall foul of a change in one being missed in
the other.
closes#16125
API search still updates query params as sending someone a pre-filtered API search link is handy.
While typing in the search box no longer updates the URL in the addr bar, you can still create a link like `~/?search=animations` and it will open the search dialog and profile the search box as it may be useful to email such a thing to someone.
Previously, the path returned by `LocationService.path()` preserved leading
slashes, which resulted in requests with consequtive slashes in the URL. Such
requests would fail (with a 404) on staging.
This commit fixes it, by removing leading slashes from the path. It also
refactors `LocationService` a bit, converting path to an observable,
`currentPath` (similar to `currentUrl`), and applies certain clean-ups (e.g.
stripping slashes, query, hash) in one place, which simplifies consumption.
Closes#16230
Changed description from h3 to h2 to match the other header
Created api page classes for consistent styling
Add styles for info-bar section
Wrapped pre tags for code not to go off of screen
This helps to ensure that the full docs have been
generated before we begin watching.
You can disable this by providing the `--watch-only`
flag. E.g. `yarn docs-watch -- --watch-only`.
Dgeni is now providing the `id` for all the documents to be viewed. So we
no longer need to add this to the DocumentContents object.
There are some notable changes in the refactoring:
`DocumentService`:
* The id of the document to render is now obtained from `LocationService.path()`.
* The `getFileNotFoundDoc` and `getErrorDoc` methods have been extracted from
the `fetchDocument` method.
`AppComponent`:
* the `pageId` is now computed in a separate `setPageId` method.
`AppComponen` spec file:
* The `TestHttp` has had the hard coded documents removed and replaced with
a function that will generate docs as needed.
* Scrolls to hash element or top of page when no hash.
* Scrolls down a bit (80px) to account for top menu overhang.
* No longer scrolls when the hash element is not found.
* Adds `<a id="top-of-page"></a>` which will benefit future efforts to
navigate there from within a page.
Index: Changed h3s to h2s given hierarchy
Index: Aligned text and image blocks to be centered
Index: Announcement bar button darkened for appropriate contrast
Search Results: Changed to list items in unordered list to accommodate accessibility and updated styles accordingly
Fixed capitalization in sidenav menu items
Add min height property to sidenav-content for better viewing on short pages or high resolution screens
Add dividier between change log items as before to h2
Table adjustments to reduce off-screen items
Update home page banner text and icon change, and fix banner img and mobile alignment
Fix and add links in doc landing page and change card footer text to reflect correct name
Removed docs landing page to rebase with master
PR Close#16138
Angular change detection bug -> no page update on resize.
Reverting to `@HostListener('window:resize', ['$event.target.innerWidth'])` cures it.
Delete DeviceService which no longer serves a purpose.
Adjusted affected AppComponent and LiveExample tests.
PR Close#16143
There are external resources that link to the old URLs. In order to avoid
breaking them, the old URLs are redirected to the new ones.
Fixes#15795Closes#16133
PR Close#16162
Previously, due ot a limitation/bug in AoT compilation and `useValue`, the
`global` injected into `SwUpdateNotificationsService` was always undefined,
which prevented it from actually reloading the page after activating a
ServiceWorker update.
This commit fixes it by switching to `useFactory`, which works correctly with
AoT.
Aligned padding to fit beneath the top nav
Add scroll bar styling inside sidenav menu
Increased font size of h2 to be different from h3 for better legibility
Now if you specifically provide an empty `@title` tag
for a contents file, the doc-gen will not complain and
the browser will just display a reasonable default.
Add visually hidden class and apply to h2 in search results
Changed h2 group headers to h3s
Add roles to main and content
Fix API material icon placement
Image alt additions where needed
Add lang attribute to html tag
Add aria-label on search input
Georgios Kalpakas
Peter Bacon Darwin
Igor Minar
Jesús Rodríguez
Kapunahele Wong
Ward Bell
Igor Minar
Chuck Jazdzewski
Stefanie Fluin
Alex Rickabaugh
Jason Hodges
aravindfz
Souvik Basu
Will Howell
Kim Burgess
swseverance
Chris McKnight
Filipe Silva
Natalie Sidhom
cameronbriar
Santi