refactor(docs-infra): migrate @angular/docs from dev-infra into adev …

…directory (#57132) To increase the ease of development we are moving @angular/docs into the adev directory within this repo. While we are doing this to improve our development experience in the short term, efforts are also in place to maintain a division between this @angular/docs (shared) code and adev itself, so that it can be extracted back out in the future when components is ready to leverage it as well. PR Close #57132
angular · Jul 30, 2024 · 81b30dc · 81b30dc
1 parent 9304c45
commit 81b30dc
Show file tree

Hide file tree

Showing 353 changed files with 28,243 additions and 90 deletions.
diff --git a/adev/BUILD.bazel b/adev/BUILD.bazel
@@ -81,6 +81,7 @@ APPLICATION_DEPS = [
     "@npm//@lezer/common",
     "@npm//@stackblitz/sdk",
     "@npm//open-in-idx",
+    "@npm//@webcontainer/api",
     "@npm//@xterm/xterm",
     "@npm//@xterm/addon-fit",
     "@npm//algoliasearch",

diff --git a/adev/shared-docs/BUILD.bazel b/adev/shared-docs/BUILD.bazel
@@ -0,0 +1,49 @@
+load("//tools:defaults.bzl", "ng_module", "ng_package")
+
+package(default_visibility = ["//visibility:private"])
+
+ng_module(
+    name = "docs",
+    srcs = [
+        "index.ts",
+    ],
+    module_name = "@angular/docs",
+    deps = [
+        "//adev/shared-docs/components",
+        "//adev/shared-docs/constants",
+        "//adev/shared-docs/directives",
+        "//adev/shared-docs/interfaces",
+        "//adev/shared-docs/pipes",
+        "//adev/shared-docs/providers",
+        "//adev/shared-docs/services",
+        "//adev/shared-docs/utils",
+    ],
+)
+
+ng_package(
+    name = "npm_package",
+    srcs = [
+        "package.json",
+        "//adev/shared-docs/icons",
+        "//adev/shared-docs/pipeline:BUILD.bazel",
+        "//adev/shared-docs/pipeline:_guides.bzl",
+        "//adev/shared-docs/pipeline:_playground.bzl",
+        "//adev/shared-docs/pipeline:_stackblitz.bzl",
+        "//adev/shared-docs/pipeline:_tutorial.bzl",
+        "//adev/shared-docs/pipeline:guides.mjs",
+        "//adev/shared-docs/pipeline:guides-no-mermaid.mjs",
+        "//adev/shared-docs/pipeline:playground.mjs",
+        "//adev/shared-docs/pipeline:stackblitz.mjs",
+        "//adev/shared-docs/pipeline:tutorial.mjs",
+        "//adev/shared-docs/pipeline/examples/template:files",
+        "//adev/shared-docs/pipeline/tutorials/common:files",
+        "//adev/shared-docs/styles",
+        "//adev/shared-docs/testing",
+    ],
+    visibility = [
+        "//adev:__pkg__",
+    ],
+    deps = [
+        ":docs",
+    ],
+)
diff --git a/adev/shared-docs/components/BUILD.bazel b/adev/shared-docs/components/BUILD.bazel
@@ -0,0 +1,27 @@
+load("//tools:defaults.bzl", "ts_library")
+
+package(default_visibility = ["//visibility:private"])
+
+ts_library(
+    name = "components",
+    srcs = [
+        "index.ts",
+    ],
+    visibility = [
+        "//adev/shared-docs:__pkg__",
+    ],
+    deps = [
+        "//adev/shared-docs/components/algolia-icon",
+        "//adev/shared-docs/components/breadcrumb",
+        "//adev/shared-docs/components/cookie-popup",
+        "//adev/shared-docs/components/copy-source-code-button",
+        "//adev/shared-docs/components/icon",
+        "//adev/shared-docs/components/navigation-list",
+        "//adev/shared-docs/components/search-dialog",
+        "//adev/shared-docs/components/select",
+        "//adev/shared-docs/components/slide-toggle",
+        "//adev/shared-docs/components/table-of-contents",
+        "//adev/shared-docs/components/text-field",
+        "//adev/shared-docs/components/viewers",
+    ],
+)
diff --git a/adev/shared-docs/components/algolia-icon/BUILD.bazel b/adev/shared-docs/components/algolia-icon/BUILD.bazel
@@ -0,0 +1,20 @@
+load("//tools:defaults.bzl", "ng_module")
+
+package(default_visibility = ["//visibility:private"])
+
+ng_module(
+    name = "algolia-icon",
+    srcs = [
+        "algolia-icon.component.ts",
+    ],
+    assets = [
+        "algolia-icon.component.html",
+    ],
+    visibility = [
+        "//adev/shared-docs/components:__pkg__",
+        "//adev/shared-docs/components/search-dialog:__pkg__",
+    ],
+    deps = [
+        "//packages/core",
+    ],
+)
diff --git a/adev/shared-docs/components/algolia-icon/algolia-icon.component.html b/adev/shared-docs/components/algolia-icon/algolia-icon.component.html
@@ -0,0 +1,52 @@
+<!-- Algolia logo -->
+<svg
+id="Layer_1"
+class="docs-algolia-logo"
+xmlns="http://www.w3.org/2000/svg"
+viewBox="0 0 2196.2 500"
+>
+<defs>
+  <style>
+    .cls-1,
+    .cls-2 {
+      fill: #003dff;
+    }
+    .cls-2 {
+      fill-rule: evenodd;
+    }
+  </style>
+</defs>
+<path
+  class="cls-2"
+  d="M1070.38,275.3V5.91c0-3.63-3.24-6.39-6.82-5.83l-50.46,7.94c-2.87,.45-4.99,2.93-4.99,5.84l.17,273.22c0,12.92,0,92.7,95.97,95.49,3.33,.1,6.09-2.58,6.09-5.91v-40.78c0-2.96-2.19-5.51-5.12-5.84-34.85-4.01-34.85-47.57-34.85-54.72Z"
+/>
+<rect class="cls-1" x="1845.88" y="104.73" width="62.58" height="277.9" rx="5.9" ry="5.9" />
+<path
+  class="cls-2"
+  d="M1851.78,71.38h50.77c3.26,0,5.9-2.64,5.9-5.9V5.9c0-3.62-3.24-6.39-6.82-5.83l-50.77,7.95c-2.87,.45-4.99,2.92-4.99,5.83v51.62c0,3.26,2.64,5.9,5.9,5.9Z"
+/>
+<path
+  class="cls-2"
+  d="M1764.03,275.3V5.91c0-3.63-3.24-6.39-6.82-5.83l-50.46,7.94c-2.87,.45-4.99,2.93-4.99,5.84l.17,273.22c0,12.92,0,92.7,95.97,95.49,3.33,.1,6.09-2.58,6.09-5.91v-40.78c0-2.96-2.19-5.51-5.12-5.84-34.85-4.01-34.85-47.57-34.85-54.72Z"
+/>
+<path
+  class="cls-2"
+  d="M1631.95,142.72c-11.14-12.25-24.83-21.65-40.78-28.31-15.92-6.53-33.26-9.85-52.07-9.85-18.78,0-36.15,3.17-51.92,9.85-15.59,6.66-29.29,16.05-40.76,28.31-11.47,12.23-20.38,26.87-26.76,44.03-6.38,17.17-9.24,37.37-9.24,58.36,0,20.99,3.19,36.87,9.55,54.21,6.38,17.32,15.14,32.11,26.45,44.36,11.29,12.23,24.83,21.62,40.6,28.46,15.77,6.83,40.12,10.33,52.4,10.48,12.25,0,36.78-3.82,52.7-10.48,15.92-6.68,29.46-16.23,40.78-28.46,11.29-12.25,20.05-27.04,26.25-44.36,6.22-17.34,9.24-33.22,9.24-54.21,0-20.99-3.34-41.19-10.03-58.36-6.38-17.17-15.14-31.8-26.43-44.03Zm-44.43,163.75c-11.47,15.75-27.56,23.7-48.09,23.7-20.55,0-36.63-7.8-48.1-23.7-11.47-15.75-17.21-34.01-17.21-61.2,0-26.89,5.59-49.14,17.06-64.87,11.45-15.75,27.54-23.52,48.07-23.52,20.55,0,36.63,7.78,48.09,23.52,11.47,15.57,17.36,37.98,17.36,64.87,0,27.19-5.72,45.3-17.19,61.2Z"
+/>
+<path
+  class="cls-2"
+  d="M894.42,104.73h-49.33c-48.36,0-90.91,25.48-115.75,64.1-14.52,22.58-22.99,49.63-22.99,78.73,0,44.89,20.13,84.92,51.59,111.1,2.93,2.6,6.05,4.98,9.31,7.14,12.86,8.49,28.11,13.47,44.52,13.47,1.23,0,2.46-.03,3.68-.09,.36-.02,.71-.05,1.07-.07,.87-.05,1.75-.11,2.62-.2,.34-.03,.68-.08,1.02-.12,.91-.1,1.82-.21,2.73-.34,.21-.03,.42-.07,.63-.1,32.89-5.07,61.56-30.82,70.9-62.81v57.83c0,3.26,2.64,5.9,5.9,5.9h50.42c3.26,0,5.9-2.64,5.9-5.9V110.63c0-3.26-2.64-5.9-5.9-5.9h-56.32Zm0,206.92c-12.2,10.16-27.97,13.98-44.84,15.12-.16,.01-.33,.03-.49,.04-1.12,.07-2.24,.1-3.36,.1-42.24,0-77.12-35.89-77.12-79.37,0-10.25,1.96-20.01,5.42-28.98,11.22-29.12,38.77-49.74,71.06-49.74h49.33v142.83Z"
+/>
+<path
+  class="cls-2"
+  d="M2133.97,104.73h-49.33c-48.36,0-90.91,25.48-115.75,64.1-14.52,22.58-22.99,49.63-22.99,78.73,0,44.89,20.13,84.92,51.59,111.1,2.93,2.6,6.05,4.98,9.31,7.14,12.86,8.49,28.11,13.47,44.52,13.47,1.23,0,2.46-.03,3.68-.09,.36-.02,.71-.05,1.07-.07,.87-.05,1.75-.11,2.62-.2,.34-.03,.68-.08,1.02-.12,.91-.1,1.82-.21,2.73-.34,.21-.03,.42-.07,.63-.1,32.89-5.07,61.56-30.82,70.9-62.81v57.83c0,3.26,2.64,5.9,5.9,5.9h50.42c3.26,0,5.9-2.64,5.9-5.9V110.63c0-3.26-2.64-5.9-5.9-5.9h-56.32Zm0,206.92c-12.2,10.16-27.97,13.98-44.84,15.12-.16,.01-.33,.03-.49,.04-1.12,.07-2.24,.1-3.36,.1-42.24,0-77.12-35.89-77.12-79.37,0-10.25,1.96-20.01,5.42-28.98,11.22-29.12,38.77-49.74,71.06-49.74h49.33v142.83Z"
+/>
+<path
+  class="cls-2"
+  d="M1314.05,104.73h-49.33c-48.36,0-90.91,25.48-115.75,64.1-11.79,18.34-19.6,39.64-22.11,62.59-.58,5.3-.88,10.68-.88,16.14s.31,11.15,.93,16.59c4.28,38.09,23.14,71.61,50.66,94.52,2.93,2.6,6.05,4.98,9.31,7.14,12.86,8.49,28.11,13.47,44.52,13.47h0c17.99,0,34.61-5.93,48.16-15.97,16.29-11.58,28.88-28.54,34.48-47.75v50.26h-.11v11.08c0,21.84-5.71,38.27-17.34,49.36-11.61,11.08-31.04,16.63-58.25,16.63-11.12,0-28.79-.59-46.6-2.41-2.83-.29-5.46,1.5-6.27,4.22l-12.78,43.11c-1.02,3.46,1.27,7.02,4.83,7.53,21.52,3.08,42.52,4.68,54.65,4.68,48.91,0,85.16-10.75,108.89-32.21,21.48-19.41,33.15-48.89,35.2-88.52V110.63c0-3.26-2.64-5.9-5.9-5.9h-56.32Zm0,64.1s.65,139.13,0,143.36c-12.08,9.77-27.11,13.59-43.49,14.7-.16,.01-.33,.03-.49,.04-1.12,.07-2.24,.1-3.36,.1-1.32,0-2.63-.03-3.94-.1-40.41-2.11-74.52-37.26-74.52-79.38,0-10.25,1.96-20.01,5.42-28.98,11.22-29.12,38.77-49.74,71.06-49.74h49.33Z"
+/>
+<path
+  class="cls-1"
+  d="M249.83,0C113.3,0,2,110.09,.03,246.16c-2,138.19,110.12,252.7,248.33,253.5,42.68,.25,83.79-10.19,120.3-30.03,3.56-1.93,4.11-6.83,1.08-9.51l-23.38-20.72c-4.75-4.21-11.51-5.4-17.36-2.92-25.48,10.84-53.17,16.38-81.71,16.03-111.68-1.37-201.91-94.29-200.13-205.96,1.76-110.26,92-199.41,202.67-199.41h202.69V407.41l-115-102.18c-3.72-3.31-9.42-2.66-12.42,1.31-18.46,24.44-48.53,39.64-81.93,37.34-46.33-3.2-83.87-40.5-87.34-86.81-4.15-55.24,39.63-101.52,94-101.52,49.18,0,89.68,37.85,93.91,85.95,.38,4.28,2.31,8.27,5.52,11.12l29.95,26.55c3.4,3.01,8.79,1.17,9.63-3.3,2.16-11.55,2.92-23.58,2.07-35.92-4.82-70.34-61.8-126.93-132.17-131.26-80.68-4.97-148.13,58.14-150.27,137.25-2.09,77.1,61.08,143.56,138.19,145.26,32.19,.71,62.03-9.41,86.14-26.95l150.26,133.2c6.44,5.71,16.61,1.14,16.61-7.47V9.48C499.66,4.25,495.42,0,490.18,0H249.83Z"
+/>
+</svg>
diff --git a/adev/shared-docs/components/algolia-icon/algolia-icon.component.ts b/adev/shared-docs/components/algolia-icon/algolia-icon.component.ts
@@ -0,0 +1,18 @@
+/*!
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {ChangeDetectionStrategy, Component} from '@angular/core';
+
+@Component({
+  selector: 'docs-algolia-icon',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [],
+  templateUrl: './algolia-icon.component.html',
+})
+export class AlgoliaIcon {}
diff --git a/adev/shared-docs/components/breadcrumb/BUILD.bazel b/adev/shared-docs/components/breadcrumb/BUILD.bazel
@@ -0,0 +1,54 @@
+load("//tools:defaults.bzl", "karma_web_test_suite", "ng_module", "ts_library")
+load("@io_bazel_rules_sass//:defs.bzl", "sass_binary")
+
+package(default_visibility = ["//visibility:private"])
+
+ng_module(
+    name = "breadcrumb",
+    srcs = [
+        "breadcrumb.component.ts",
+    ],
+    assets = [
+        ":breadcrumb.component.css",
+        "breadcrumb.component.html",
+    ],
+    visibility = [
+        "//adev/shared-docs/components:__pkg__",
+        "//adev/shared-docs/components/viewers:__pkg__",
+    ],
+    deps = [
+        "//adev/shared-docs/interfaces",
+        "//adev/shared-docs/services",
+        "//packages/common",
+        "//packages/core",
+        "//packages/router",
+    ],
+)
+
+sass_binary(
+    name = "style",
+    src = "breadcrumb.component.scss",
+)
+
+ts_library(
+    name = "test_lib",
+    testonly = True,
+    srcs = glob(
+        ["*.spec.ts"],
+    ),
+    deps = [
+        ":breadcrumb",
+        "//adev/shared-docs/interfaces",
+        "//adev/shared-docs/services",
+        "//packages/core",
+        "//packages/core/testing",
+        "//packages/platform-browser",
+        "//packages/router",
+        "//packages/router/testing",
+    ],
+)
+
+karma_web_test_suite(
+    name = "test",
+    deps = [":test_lib"],
+)
diff --git a/adev/shared-docs/components/breadcrumb/breadcrumb.component.html b/adev/shared-docs/components/breadcrumb/breadcrumb.component.html
@@ -0,0 +1,13 @@
+@for (breadcrumb of breadcrumbItems(); track breadcrumb) {
+  <div class="docs-breadcrumb">
+    @if (breadcrumb.path) {
+      @if (breadcrumb.isExternal) {
+        <a [href]="breadcrumb.path">{{ breadcrumb.label }}</a>
+      } @else {
+        <a [routerLink]="'/' + breadcrumb.path">{{ breadcrumb.label }}</a>
+      }
+    } @else {
+      <span>{{ breadcrumb.label }}</span>
+    }
+  </div>
+}
diff --git a/adev/shared-docs/components/breadcrumb/breadcrumb.component.scss b/adev/shared-docs/components/breadcrumb/breadcrumb.component.scss
@@ -0,0 +1,25 @@
+:host {
+  display: flex;
+  align-items: center;
+  padding-block-end: 1.5rem;
+}
+
+.docs-breadcrumb {
+  span {
+    color: var(--quaternary-contrast);
+    font-size: 0.875rem;
+    display: flex;
+    align-items: center;
+  }
+
+  &:not(:last-child) {
+    span {
+      &::after {
+        content: 'chevron_right';
+        font-family: var(--icons);
+        margin-inline: 0.5rem;
+        color: var(--quinary-contrast);
+      }
+    }
+  }
+}
diff --git a/adev/shared-docs/components/breadcrumb/breadcrumb.component.spec.ts b/adev/shared-docs/components/breadcrumb/breadcrumb.component.spec.ts
@@ -0,0 +1,83 @@
+/*!
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {ComponentFixture, TestBed} from '@angular/core/testing';
+
+import {Breadcrumb} from './breadcrumb.component';
+import {NavigationState} from '../../services';
+import {NavigationItem} from '../../interfaces';
+import {By} from '@angular/platform-browser';
+import {RouterTestingModule} from '@angular/router/testing';
+import {provideExperimentalZonelessChangeDetection} from '@angular/core';
+
+describe('Breadcrumb', () => {
+  let fixture: ComponentFixture<Breadcrumb>;
+  let navigationStateSpy: jasmine.SpyObj<NavigationState>;
+
+  beforeEach(() => {
+    navigationStateSpy = jasmine.createSpyObj('NavigationState', ['activeNavigationItem']);
+
+    TestBed.configureTestingModule({
+      imports: [Breadcrumb, RouterTestingModule],
+      providers: [
+        provideExperimentalZonelessChangeDetection(),
+        {
+          provide: NavigationState,
+          useValue: navigationStateSpy,
+        },
+      ],
+    });
+    fixture = TestBed.createComponent(Breadcrumb);
+  });
+
+  it('should display proper breadcrumb structure based on navigation state', () => {
+    navigationStateSpy.activeNavigationItem.and.returnValue(item);
+
+    fixture.detectChanges();
+    const breadcrumbs = fixture.debugElement.queryAll(By.css('.docs-breadcrumb span'));
+
+    expect(breadcrumbs.length).toBe(2);
+    expect(breadcrumbs[0].nativeElement.innerText).toEqual('Grandparent');
+    expect(breadcrumbs[1].nativeElement.innerText).toEqual('Parent');
+  });
+
+  it('should display breadcrumb links when navigation item has got path', () => {
+    navigationStateSpy.activeNavigationItem.and.returnValue(exampleItemWithPath);
+
+    fixture.detectChanges();
+    const breadcrumbs = fixture.debugElement.queryAll(By.css('.docs-breadcrumb a'));
+
+    expect(breadcrumbs.length).toBe(1);
+    expect(breadcrumbs[0].nativeElement.innerText).toEqual('Parent');
+    expect(breadcrumbs[0].nativeElement.href).toEqual(`${window.origin}/example`);
+  });
+});
+
+const grandparent: NavigationItem = {
+  label: 'Grandparent',
+};
+
+const parent: NavigationItem = {
+  label: 'Parent',
+  parent: grandparent,
+};
+
+const item: NavigationItem = {
+  label: 'Active Item',
+  parent: parent,
+};
+
+const parentWithPath: NavigationItem = {
+  label: 'Parent',
+  path: '/example',
+};
+
+const exampleItemWithPath: NavigationItem = {
+  label: 'Active Item',
+  parent: parentWithPath,
+};