// ==ORIGINAL==

type APIResponse<T> = { success: true, data: T } | { success: false };

function /*[#|*/get/*|]*/() {
    return Promise
        .resolve<APIResponse<{ email: string }>>({ success: true, data: { email: "" } })
        .catch<APIResponse<{ email: string }>>(() => ({ success: false }));
}

// ==ASYNC FUNCTION::Convert to async function==

type APIResponse<T> = { success: true, data: T } | { success: false };

async function get() {
    try {
        return await Promise
            .resolve<APIResponse<{ email: string; }>>({ success: true, data: { email: "" } });
    } catch {
        const result: APIResponse<{ email: string; }> = ({ success: false });
        return result;
    }
}


// ==ORIGINAL==

function /*[#|*/f/*|]*/(): Promise<void>{
    const result = getResult();
    return fetch('https://typescriptlang.org').then(([result]) => { console.log(result) });
}
// ==ASYNC FUNCTION::Convert to async function==

async function f(): Promise<void>{
    const result = getResult();
    const [result_1] = await fetch('https://typescriptlang.org');
    console.log(result_1);
}


// ==ORIGINAL==

type APIResponse<T> = { success: true, data: T } | { success: false };

function wrapResponse<T>(response: T): APIResponse<T> {
    return { success: true, data: response };
}

function /*[#|*/get/*|]*/() {
    return Promise.resolve(undefined!).then<APIResponse<{ email: string }>>(wrapResponse);
}

// ==ASYNC FUNCTION::Convert to async function==

type APIResponse<T> = { success: true, data: T } | { success: false };

function wrapResponse<T>(response: T): APIResponse<T> {
    return { success: true, data: response };
}

async function get() {
    const response = await Promise.resolve(undefined!);
    const result: APIResponse<{ email: string; }> = wrapResponse(response);
    return result;
}


currentDirectory:: /home/src/workspaces/project useCaseSensitiveFileNames:: false
Input::
//// [/home/src/tslibs/TS/Lib/lib.d.ts]
/// <reference no-default-lib="true"/>
interface Boolean {}
interface Function {}
interface CallableFunction {}
interface NewableFunction {}
interface IArguments {}
interface Number { toExponential: any; }
interface Object {}
interface RegExp {}
interface String { charAt: any; }
interface Array<T> { length: number; [n: number]: T; }
interface ReadonlyArray<T> {}
declare const console: { log(msg: any): void; };

/home/src/tslibs/TS/Lib/tsc.js --help --all
Output::
tsc: The TypeScript Compiler - Version FakeTSVersion

ALL COMPILER OPTIONS

### Command-line Options

--all
Show all compiler options.

--build, -b
Build one or more projects and their dependencies, if out of date

--help, -h
Print this message.

--help, -?

--init
Initializes a TypeScript project and creates a tsconfig.json file.

--listFilesOnly
Print names of files that are part of the compilation and then stop processing.

--locale
Set the language of the messaging from TypeScript. This does not affect emit.

--project, -p
Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.

--showConfig
Print the final configuration instead of building.

--version, -v
Print the compiler's version.

--watch, -w
Watch input files.

### Modules

--allowArbitraryExtensions
Enable importing files with any extension, provided a declaration file is present.
type: boolean
default: false

--allowImportingTsExtensions
Allow imports to include TypeScript file extensions. Requires '--moduleResolution bundler' and either '--noEmit' or '--emitDeclarationOnly' to be set.
type: boolean
default: false

--allowUmdGlobalAccess
Allow accessing UMD globals from modules.
type: boolean
default: false

--baseUrl
Specify the base directory to resolve non-relative module names.

--customConditions
Conditions to set in addition to the resolver-specific defaults when resolving imports.

--module, -m
Specify what module code is generated.
one of: none, commonjs, amd, umd, system, es6/es2015, es2020, es2022, esnext, node16, nodenext, preserve
default: undefined

--moduleResolution
Specify how TypeScript looks up a file from a given module specifier.
one of: classic, node10, node16, nodenext, bundler
default: module === `AMD` or `UMD` or `System` or `ES6`, then `Classic`, Otherwise `Node`

--moduleSuffixes
List of file name suffixes to search when resolving a module.

--noResolve
Disallow 'import's, 'require's or '<reference>'s from expanding the number of files TypeScript should add to a project.
type: boolean
default: false

--noUncheckedSideEffectImports
Check side effect imports.
type: boolean
default: false

--paths
Specify a set of entries that re-map imports to additional lookup locations.
default: undefined

--resolveJsonModule
Enable importing .json files.
type: boolean
default: false

--resolvePackageJsonExports
Use the package.json 'exports' field when resolving package imports.
type: boolean
default: `true` when 'moduleResolution' is 'node16', 'nodenext', or 'bundler'; otherwise `false`.

--resolvePackageJsonImports
Use the package.json 'imports' field when resolving imports.
type: boolean
default: `true` when 'moduleResolution' is 'node16', 'nodenext', or 'bundler'; otherwise `false`.

--rewriteRelativeImportExtensions
Rewrite '.ts', '.tsx', '.mts', and '.cts' file extensions in relative import paths to their JavaScript equivalent in output files.
type: boolean
default: false

--rootDir
Specify the root folder within your source files.
type: string
default: Computed from the list of input files

--rootDirs
Allow multiple folders to be treated as one when resolving modules.
one or more: string
default: Computed from the list of input files

--typeRoots
Specify multiple folders that act like './node_modules/@types'.

--types
Specify type package names to be included without being referenced in a source file.

### JavaScript Support

--allowJs
Allow JavaScript files to be a part of your program. Use the 'checkJS' option to get errors from these files.
type: boolean
default: false

--checkJs
Enable error reporting in type-checked JavaScript files.
type: boolean
default: false

--maxNodeModuleJsDepth
Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'.
type: number
default: 0

### Interop Constraints

--allowSyntheticDefaultImports
Allow 'import x from y' when a module doesn't have a default export.
type: boolean
default: module === "system" or esModuleInterop

--esModuleInterop
Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility.
type: boolean
default: false

--forceConsistentCasingInFileNames
Ensure that casing is correct in imports.
type: boolean
default: true

--isolatedDeclarations
Require sufficient annotation on exports so other tools can trivially generate declaration files.
type: boolean
default: false

--isolatedModules
Ensure that each file can be safely transpiled without relying on other imports.
type: boolean
default: false

--preserveSymlinks
Disable resolving symlinks to their realpath. This correlates to the same flag in node.
type: boolean
default: false

--verbatimModuleSyntax
Do not transform or elide any imports or exports not marked as type-only, ensuring they are written in the output file's format based on the 'module' setting.
type: boolean
default: false

### Type Checking

--allowUnreachableCode
Disable error reporting for unreachable code.
type: boolean
default: undefined

--allowUnusedLabels
Disable error reporting for unused labels.
type: boolean
default: undefined

--alwaysStrict
Ensure 'use strict' is always emitted.
type: boolean
default: `false`, unless `strict` is set

--exactOptionalPropertyTypes
Interpret optional property types as written, rather than adding 'undefined'.
type: boolean
default: false

--noFallthroughCasesInSwitch
Enable error reporting for fallthrough cases in switch statements.
type: boolean
default: false

--noImplicitAny
Enable error reporting for expressions and declarations with an implied 'any' type.
type: boolean
default: `false`, unless `strict` is set

--noImplicitOverride
Ensure overriding members in derived classes are marked with an override modifier.
type: boolean
default: false

--noImplicitReturns
Enable error reporting for codepaths that do not explicitly return in a function.
type: boolean
default: false

--noImplicitThis
Enable error reporting when 'this' is given the type 'any'.
type: boolean
default: `false`, unless `strict` is set

--noPropertyAccessFromIndexSignature
Enforces using indexed accessors for keys declared using an indexed type.
type: boolean
default: false

--noUncheckedIndexedAccess
Add 'undefined' to a type when accessed using an index.
type: boolean
default: false

--noUnusedLocals
Enable error reporting when local variables aren't read.
type: boolean
default: false

--noUnusedParameters[


WatchInfo: /user/username/projects/myproject/package.json 2000 undefined File location affecting resolution
FileWatcher:: Close:: WatchInfo: /user/username/projects/package.json 2000 undefined File location affecting resolution
FileWatcher:: Close:: WatchInfo: /user/username/projects/myproject/node_modules/@types/node/ts3.6/package.json 2000 undefined File location affecting resolution
worker.ts:1:1 - error TS2580: Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node`.

1 process.on("uncaughtException");
  ~~~~~~~

[HH:MM:SS AM] Found 1 error. Watching for file changes.

//// [/user/username/projects/myproject/worker.js] file written with same contents

PolledWatches::
/user/username/projects/node_modules/@types:
  {"pollingInterval":500}

PolledWatches *deleted*::
/user/username/projects/myproject/node_modules/@types/node/package.json:
  {"pollingInterval":2000}
/user/username/projects/myproject/node_modules/@types/node/ts3.6/package.json:
  {"pollingInterval":2000}
/user/username/projects/myproject/node_modules/@types/package.json:
  {"pollingInterval":2000}
/user/username/projects/myproject/node_modules/package.json:
  {"pollingInterval":2000}
/user/username/projects/myproject/package.json:
  {"pollingInterval":2000}
/user/username/projects/package.json:
  {"pollingInterval":2000}

FsWatches::
/home/src/tslibs/TS/Lib/lib.d.ts:
  {}
/user/username/projects/myproject/tsconfig.json:
  {}
/user/username/projects/myproject/worker.ts:
  {}

FsWatches *deleted*::
/user/username/projects/myproject/node_modules/@types/node/base.d.ts:
  {}
/user/username/projects/myproject/node_modules/@types/node/globals.d.ts:
  {}
/user/username/projects/myproject/node_modules/@types/node/index.d.ts:
  {}
/user/username/projects/myproject/node_modules/@types/node/ts3.6/base.d.ts:
  {}

FsWatchesRecursive::
/user/username/projects/myproject:
  {}
/user/username/projects/myproject/node_modules:
  {}
/user/username/projects/myproject/node_modules/@types:
  {}

Program root files: [
  "/user/username/projects/myproject/worker.ts"
]
Program options: {
  "watch": true,
  "extendedDiagnostics": true,
  "configFilePath": "/user/username/projects/myproject/tsconfig.json"
}
Program structureReused: Not
Program files::
/home/src/tslibs/TS/Lib/lib.d.ts
/user/username/projects/myproject/worker.ts

Semantic diagnostics in builder refreshed for::
/home/src/tslibs/TS/Lib/lib.d.ts
/user/username/projects/myproject/worker.ts

Shape signatures in builder refreshed for::
/user/username/projects/myproject/worker.ts (computed .d.ts)

exitCode:: ExitStatus.undefined

Change:: npm ci step two: create atTypes but something else in the @types folder

Input::
//// [/user/username/projects/myproject/node_modules/@types/mocha/index.d.ts]
export const foo = 10;

Output::
DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types :: WatchInfo: /user/username/projects/myproject/node_modules/@types 1 undefined Type roots
Scheduling update
Scheduling invalidateFailedLookup
Elapsed:: *ms DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types :: WatchInfo: /user/username/projects/myproject/node_modules/@types 1 undefined Type roots
DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types :: WatchInfo: /user/username/projects/myproject/node_modules 1 undefined Failed Lookup Locations
Scheduling invalidateFailedLookup, Cancelled earlier one
Elapsed:: *ms DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types :: WatchInfo: /user/username/projects/myproject/node_modules 1 undefined Failed Lookup Locations
DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types :: WatchInfo: /user/username/projects/myproject 1 undefined Wild card directory
Scheduling update
Elapsed:: *ms DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types :: WatchInfo: /user/username/projects/myproject 1 undefined Wild card directory
DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/mocha :: WatchInfo: /user/username/projects/myproject/node_modules/@types 1 undefined Type roots
Scheduling update
Scheduling invalidateFailedLookup, Cancelled earlier one
Elapsed:: *ms DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/mocha :: WatchInfo: /user/username/projects/myproject/node_modules/@types 1 undefined Type roots
DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/mocha :: WatchInfo: /user/username/projects/myproject/node_modules 1 undefined Failed Lookup Locations
Scheduling invalidateFailedLookup, Cancelled earlier one
Elapsed:: *ms DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/mocha :: WatchInfo: /user/username/projects/myproject/node_modules 1 undefined Failed Lookup Locations
DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/mocha :: WatchInfo: /user/username/projects/myproject 1 undefined Wild card directory
Scheduling update
Elapsed:: *ms DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/mocha :: WatchInfo: /user/username/projects/myproject 1 undefined Wild card directory
DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/mocha/index.d.ts :: WatchInfo: /user/username/projects/myproject/node_modules/@types 1 undefined Type roots
Scheduling update
Scheduling invalidateFailedLookup, Cancelled earlier one
Elapsed:: *ms DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/mocha/index.d.ts :: WatchInfo: /user/username/projects/myproject/node_modules/@types 1 undefined Type roots
DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/mocha/index.d.ts :: WatchInfo: /user/username/projects/myproject/node_modules 1 undefined Failed Lookup Locations
Scheduling invalidateFailedLookup, Cancelled earlier one
Elapsed:: *ms DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/mocha/index.d.ts :: WatchInfo: /user/username/projects/myproject/node_modules 1 undefined Failed Lookup Locations
DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/mocha/index.d.ts :: WatchInfo: /user/username/projects/myproject 1 undefined Wild card directory
Scheduling update
Elapsed:: *ms DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/mocha/index.d.ts :: WatchInfo: /user/username/projects/myproject 1 undefined Wild card directory

Timeout callback:: count: 2
42: timerToInvalidateFailedLookupResolutions *new*
43: timerToUpdateProgram *new*

Before running Timeout callback:: count: 2
42: timerToInvalidateFailedLookupResolutions
43: timerToUpdateProgram

Host is moving to new time
After running Timeout callback:: count: 0
Output::
Reloading new file names and options
Synchronizing program
[HH:MM:SS AM] File change detected. Starting incremental compilation...

CreatingProgramWith::
  roots: ["/user/username/projects/myproject/worker.ts"]
  options: {"watch":true,"extendedDiagnostics":true,"configFilePath":"/user/username/projects/myproject/tsconfig.json"}
FileWatcher:: Added:: WatchInfo: /user/username/projects/myproject/node_modules/@types/mocha/index.d.ts 250 undefined Source file
FileWatcher:: Added:: WatchInfo: /user/username/projects/myproject/node_modules/@types/mocha/package.json 2000 undefined File location affecting resolution
FileWatcher:: Added:: WatchInfo: /user/username/projects/myproject/node_modules/@types/package.json 2000 undefined File location affecting resolution
FileWatcher:: Added:: WatchInfo: /user/username/projects/myproject/node_modules/package.json 2000 undefined File location affecting resolution
FileWatcher:: Added:: WatchInfo: /user/username/projects/myproject/package.json 2000 undefined File location affecting resolution
FileWatcher:: Added:: WatchInfo: /user/username/projects/package.json 2000 undefined File location affecting resolution
worker.ts:1:1[0


m - error TS2580: Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node`.

1 process.on("uncaughtException");
  ~~~~~~~

[HH:MM:SS AM] Found 1 error. Watching for file changes.

PolledWatches::
/user/username/projects/myproject/node_modules/@types/mocha/package.json: *new*
  {"pollingInterval":2000}
/user/username/projects/myproject/node_modules/@types/package.json: *new*
  {"pollingInterval":2000}
/user/username/projects/myproject/node_modules/package.json: *new*
  {"pollingInterval":2000}
/user/username/projects/myproject/package.json: *new*
  {"pollingInterval":2000}
/user/username/projects/node_modules/@types:
  {"pollingInterval":500}
/user/username/projects/package.json: *new*
  {"pollingInterval":2000}

FsWatches::
/home/src/tslibs/TS/Lib/lib.d.ts:
  {}
/user/username/projects/myproject/node_modules/@types/mocha/index.d.ts: *new*
  {}
/user/username/projects/myproject/tsconfig.json:
  {}
/user/username/projects/myproject/worker.ts:
  {}

FsWatchesRecursive::
/user/username/projects/myproject:
  {}
/user/username/projects/myproject/node_modules:
  {}
/user/username/projects/myproject/node_modules/@types:
  {}

Program root files: [
  "/user/username/projects/myproject/worker.ts"
]
Program options: {
  "watch": true,
  "extendedDiagnostics": true,
  "configFilePath": "/user/username/projects/myproject/tsconfig.json"
}
Program structureReused: SafeModules
Program files::
/home/src/tslibs/TS/Lib/lib.d.ts
/user/username/projects/myproject/worker.ts
/user/username/projects/myproject/node_modules/@types/mocha/index.d.ts

Semantic diagnostics in builder refreshed for::
/user/username/projects/myproject/node_modules/@types/mocha/index.d.ts

Shape signatures in builder refreshed for::
/user/username/projects/myproject/node_modules/@types/mocha/index.d.ts (used version)

exitCode:: ExitStatus.undefined

Change:: npm ci step three: create atTypes node folder

Input::

Output::
DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/node :: WatchInfo: /user/username/projects/myproject/node_modules/@types 1 undefined Type roots
Scheduling update
Scheduling invalidateFailedLookup
Elapsed:: *ms DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/node :: WatchInfo: /user/username/projects/myproject/node_modules/@types 1 undefined Type roots
DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/node :: WatchInfo: /user/username/projects/myproject/node_modules 1 undefined Failed Lookup Locations
Scheduling invalidateFailedLookup, Cancelled earlier one
Elapsed:: *ms DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/node :: WatchInfo: /user/username/projects/myproject/node_modules 1 undefined Failed Lookup Locations
DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/node :: WatchInfo: /user/username/projects/myproject 1 undefined Wild card directory
Scheduling update
Elapsed:: *ms DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/node :: WatchInfo: /user/username/projects/myproject 1 undefined Wild card directory

Timeout callback:: count: 2
46: timerToInvalidateFailedLookupResolutions *new*
47: timerToUpdateProgram *new*

Before running Timeout callback:: count: 2
46: timerToInvalidateFailedLookupResolutions
47: timerToUpdateProgram

Host is moving to new time
After running Timeout callback:: count: 0
Output::
Reloading new file names and options
Synchronizing program
[HH:MM:SS AM] File change detected. Starting incremental compilation...

CreatingProgramWith::
  roots: ["/user/username/projects/myproject/worker.ts"]
  options: {"watch":true,"extendedDiagnostics":true,"configFilePath":"/user/username/projects/myproject/tsconfig.json"}
DirectoryWatcher:: Added:: WatchInfo: /user/username/projects/node_modules 1 undefined Failed Lookup Locations
Elapsed:: *ms DirectoryWatcher:: Added:: WatchInfo: /user/username/projects/node_modules 1 undefined Failed Lookup Locations
error TS2688: Cannot find type definition file for 'node'.
  The file is in the program because:
    Entry point for implicit type library 'node'

[HH:MM:SS AM] Found 1 error. Watching for file changes.

PolledWatches::
/user/username/projects/myproject/node_modules/@types/mocha/package.json:
  {"pollingInterval":2000}
/user/username/projects/myproject/node_modules/@types/package.json:
  {"pollingInterval":2000}
/user/username/projects/myproject/node_modules/package.json:
  {"pollingInterval":2000}
/user/username/projects/myproject/package.json:
  {"pollingInterval":2000}
/user/username/projects/node_modules: *new*
  {"pollingInterval":500}
/user/username/projects/node_modules/@types:
  {"pollingInterval":500}
/user/username/projects/package.json:
  {"pollingInterval":2000}

FsWatches::
/home/src/tslibs/TS/Lib/lib.d.ts:
  {}
/user/username/projects/myproject/node_modules/@types/mocha/index.d.ts:
  {}
/user/username/projects/myproject/tsconfig.json:
  {}
/user/username/projects/myproject/worker.ts:
  {}

FsWatchesRecursive::
/user/username/projects/myproject:
  {}
/user/username/projects/myproject/node_modules:
  {}
/user/username/projects/myproject/node_modules/@types:
  {}

Program root files: [
  "/user/username/projects/myproject/worker.ts"
]
Program options: {
  "watch": true,
  "extendedDiagnostics": true,
  "configFilePath": "/user/username/projects/myproject/tsconfig.json"
}
Program structureReused: SafeModules
Program files::
/home/src/tslibs/TS/Lib/lib.d.ts
/user/username/projects/myproject/worker.ts
/user/username/projects/myproject/node_modules/@types/mocha/index.d.ts

Semantic diagnostics in builder refreshed for::

No shapes updated in the builder::

exitCode:: ExitStatus.undefined

Change:: npm ci step four: create atTypes write all the files but dont invoke watcher for index.d.ts

Input::
//// [/user/username/projects/myproject/node_modules/@types/node/base.d.ts]
// Base definitions for all NodeJS modules that are not specific to any version of TypeScript:
/// <reference path="ts3.6/base.d.ts" />

//// [/user/username/projects/myproject/node_modules/@types/node/index.d.ts]
/// <reference path="base.d.ts" />

//// [/user/username/projects/myproject/node_modules/@types/node/ts3.6/base.d.ts]
/// <reference path="../globals.d.ts" />

//// [/user/username/projects/myproject/node_modules/@types/node/globals.d.ts]
declare var process: NodeJS.Process;
declare namespace NodeJS {
    interface Process {
        on(msg: string): void;
    }
}

Output::
DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/node/base.d.ts :: WatchInfo: /user/username/projects/myproject/node_modules/@types 1 undefined Type roots
Scheduling update
Scheduling invalidateFailedLookup
Elapsed:: *ms DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/node/base.d.ts :: WatchInfo: /user/username/projects/myproject/node_modules/@types 1 undefined Type roots
DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/node/base.d.ts :: WatchInfo: /user/username/projects/myproject/node_modules 1 undefined Failed Lookup Locations
Scheduling invalidateFailedLookup, Cancelled earlier one
Elapsed:: *ms DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/node/base.d.ts :: WatchInfo: /user/username/projects/myproject/node_modules 1 undefined Failed Lookup Locations
DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/node/base.d.ts :: WatchInfo: /user/username/projects/myproject 1 undefined Wild card directory
Scheduling update
Elapsed:: *ms DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/node/base.d.ts :: WatchInfo: /user/username/projects/myproject 1 undefined Wild card directory
DirectoryWatcher:: Triggered with /user/username/projects/myproject/node_modules/@types/node/ts3.6 :: WatchInfo: /user


currentDirectory:: /user/username/workspace/solution/projects/projectc useCaseSensitiveFileNames:: false
Input::
//// [/user/username/workspace/solution/projects/project/app.ts]
let x = 1

//// [/user/username/workspace/solution/projects/project/tsconfig.json]
{
  "compilerOptions": {
    "types": [
      "node"
    ],
    "typeRoots": []
  }
}

//// [/user/username/workspace/solution/projects/project/node_modules/@types/node/index.d.ts]
declare var process: any

//// [/home/src/tslibs/TS/Lib/lib.d.ts]
/// <reference no-default-lib="true"/>
interface Boolean {}
interface Function {}
interface CallableFunction {}
interface NewableFunction {}
interface IArguments {}
interface Number { toExponential: any; }
interface Object {}
interface RegExp {}
interface String { charAt: any; }
interface Array<T> { length: number; [n: number]: T; }
interface ReadonlyArray<T> {}
declare const console: { log(msg: any): void; };

/home/src/tslibs/TS/Lib/tsc.js -w -p /user/username/workspace/solution/projects/project/tsconfig.json
Output::
>> Screen clear
[HH:MM:SS AM] Starting compilation in watch mode...

error TS2688: Cannot find type definition file for 'node'.
  The file is in the program because:
    Entry point of type library 'node' specified in compilerOptions

  ../project/tsconfig.json:4:7
    4       "node"
            ~~~~~~
    File is entry point of type library specified here.

[HH:MM:SS AM] Found 1 error. Watching for file changes.

//// [/user/username/workspace/solution/projects/project/app.js]
var x = 1;

FsWatches::
/home/src/tslibs/TS/Lib/lib.d.ts: *new*
  {}
/user/username/workspace/solution/projects/project/app.ts: *new*
  {}
/user/username/workspace/solution/projects/project/tsconfig.json: *new*
  {}

FsWatchesRecursive::
/user/username/workspace/solution/projects/project: *new*
  {}

Program root files: [
  "/user/username/workspace/solution/projects/project/app.ts"
]
Program options: {
  "types": [
    "node"
  ],
  "typeRoots": [],
  "watch": true,
  "project": "/user/username/workspace/solution/projects/project/tsconfig.json",
  "configFilePath": "/user/username/workspace/solution/projects/project/tsconfig.json"
}
Program structureReused: Not
Program files::
/home/src/tslibs/TS/Lib/lib.d.ts
/user/username/workspace/solution/projects/project/app.ts

No cached semantic diagnostics in the builder::

Shape signatures in builder refreshed for::
/home/src/tslibs/ts/lib/lib.d.ts (used version)
/user/username/workspace/solution/projects/project/app.ts (used version)

exitCode:: ExitStatus.undefined


### TypeScript

#### Typing
Avoid `any` where possible. If you find yourself using `any`, consider whether a generic may be
appropriate in your case.

For methods and properties that are part of a component's public API, all types must be explicitly
specified because our documentation tooling cannot currently infer types in places where TypeScript
can.

#### Fluent APIs
When creating a fluent or builder-pattern style API, use the `this` return type for methods:
```
class ConfigBuilder {
  withName(name: string): this {
    this.config.name = name;
    return this;
  }
}
```

#### Access modifiers
* Omit the `public` keyword as it is the default behavior.
* Use `private` when appropriate and possible, prefixing the name with an underscore.
* Use `protected` when appropriate and possible with no prefix.
* Prefix *library-internal* properties and methods with an underscore without using the `private`
keyword. This is necessary for anything that must be public (to be used by Angular), but should not
be part of the user-facing API. This typically applies to symbols used in template expressions,
`@ViewChildren` / `@ContentChildren` properties, host bindings, and `@Input` / `@Output` properties
(when using an alias).

Additionally, the `@docs-private` JsDoc annotation can be used to hide any symbol from the public
API docs.

#### Getters and Setters
* Only use getters and setters for `@Input` properties or when otherwise required for API
compatibility.
* Avoid long or complex getters and setters. If the logic of an accessor would take more than
three lines, introduce a new method to contain the logic.
* A getter should immediately precede its corresponding setter.
* Decorators such as `@Input` should be applied to the getter and not the setter.
* Always use a `readonly` property instead of a getter (with no setter) when possible.
  ```ts
  /** YES */
  readonly active: boolean;

  /** NO */
  get active(): boolean {
    // Using a getter solely to make the property read-only.
    return this._active;
  }
  ```

#### JsDoc comments

All public APIs must have user-facing comments. These are extracted and shown in the documentation
on [material.angular.io](https://material.angular.io).

Private and internal APIs should have JsDoc when they are not obvious. Ultimately it is the purview
of the code reviewer as to what is "obvious", but the rule of thumb is that *most* classes,
properties, and methods should have a JsDoc description.

Properties should have a concise description of what the property means:
```ts
  /** The label position relative to the checkbox. Defaults to 'after' */
  @Input() labelPosition: 'before' | 'after' = 'after';
```

Methods blocks should describe what the function does and provide a description for each parameter
and the return value:
```ts
  /**
   * Opens a modal dialog containing the given component.
   * @param component Type of the component to load into the dialog.
   * @param config Dialog configuration options.
   * @returns Reference to the newly-opened dialog.
   */
  open<T>(component: ComponentType<T>, config?: MatDialogConfig): MatDialogRef<T> { ... }
```

Boolean properties and return values should use "Whether..." as opposed to "True if...":
```ts
  /** Whether the button is disabled. */
  disabled: boolean = false;
```

#### Try-Catch

Avoid `try-catch` blocks, instead preferring to prevent an error from being thrown in the first
place. When impossible to avoid, the `try-catch` block must include a comment that explains the
specific error being caught and why it cannot be prevented.

#### Naming

##### General
* Prefer writing out words instead of using abbreviations.
* Prefer *exact* names to short names (within reason). E.g., `labelPosition` is better than
`align` because the former much more exactly communicates what the property means.
* Except for `@Input` properties, use `is` and `has` prefixes for boolean properties / methods.

##### Observables
* Don't suffix observables with `$`.

##### Classes
Classes should be named based on what they're responsible for. Names should capture what the code
*does*, not how it is used:
```
/** NO: */
class RadioService { }

/** YES: */
class UniqueSelectionDispatcher { }
```

Avoid suffixing a class with "Service", as it communicates nothing about what the class does. Try to
think of the class name as a person's job title.

Classes that correspond to a directive with an `mat-` prefix should also be prefixed with `Mat`.
CDK classes should only have a `Cdk` prefix when the class is a directive with a `cdk` selector
prefix.

##### Methods
The name of a method should capture the action that is performed *by* that method rather than
describing when the method will be called. For example,

```ts
/** AVOID: does not describe what the function does. */
handleClick() {
  // ...
}

/** PREFER: describes the action performed by the function. */
activateRipple() {
  // ...
}
```

##### Selectors
* Component selectors should be lowercase and delimited by hyphens. Components should use element
selectors except when the component API uses a native HTML element.
* Directive selectors should be camel cased. Exceptions may be made for directives that act like a
component but would have an empty template, or when the directive is intended to match some
existing attribute.

#### Inheritance

Avoid using inheritance to apply reusable behaviors to multiple components. This limits how many
behaviors can be composed. Instead, [TypeScript mixins][ts-mixins] can be used to compose multiple
common behaviors into a single component.

#### Coercion
Component and directive inputs for boolean and number values must use an input transform function
to coerce values to the expected type.
For example:
```ts
import {Input, booleanAttribute} from '@angular/core';

@Input({transform: booleanAttribute}) disabled: boolean = false;
```
The above code allows users to set `disabled` similar to how it can be set on native inputs:
```html
<component disabled></component>
```

#### Expose native inputs
Native inputs used in components should be exposed to developers through `ng-content`. This allows
developers to interact directly with the input and allows us to avoid providing custom
implementations for all the input's native behaviors.

For example:

**Do:**

Implementation
```html
<ng-content></ng-content>
```

Usage
```html
<your-component>
  <input>
</your-component>
```

**Don't:**

Implementation
```html
<input>
```

Usage
```html
<component></component>
```

### Angular

#### Host bindings
Prefer using the `host` object in the directive configuration instead of `@HostBinding` and
`@HostListener`. We do this because TypeScript preserves the type information of methods with
decorators, and when one of the arguments for the method is a native `Event` type, this preserved
type information can lead to runtime errors in non-browser environments (e.g., server-side
pre-rendering).


emTitle>;
    toggle(): void;
    _toggleOnInteraction(): void;
    togglePosition: MatListOptionTogglePosition;
    // (undocumented)
    _unscopedContent: ElementRef<HTMLSpanElement>;
    get value(): any;
    set value(newValue: any);
    // (undocumented)
    static ɵcmp: i0.ɵɵComponentDeclaration<MatListOption, "mat-list-option", ["matListOption"], { "togglePosition": { "alias": "togglePosition"; "required": false; }; "checkboxPosition": { "alias": "checkboxPosition"; "required": false; }; "color": { "alias": "color"; "required": false; }; "value": { "alias": "value"; "required": false; }; "selected": { "alias": "selected"; "required": false; }; }, { "selectedChange": "selectedChange"; }, ["_lines", "_titles"], ["[matListItemAvatar],[matListItemIcon]", "[matListItemTitle]", "[matListItemLine]", "*", "mat-divider"], true, never>;
    // (undocumented)
    static ɵfac: i0.ɵɵFactoryDeclaration<MatListOption, never>;
}

// @public
type MatListOptionTogglePosition = 'before' | 'after';
export { MatListOptionTogglePosition as MatListOptionCheckboxPosition }
export { MatListOptionTogglePosition }

// @public
export class MatListSubheaderCssMatStyler {
    // (undocumented)
    static ɵdir: i0.ɵɵDirectiveDeclaration<MatListSubheaderCssMatStyler, "[mat-subheader], [matSubheader]", never, {}, {}, never, never, true, never>;
    // (undocumented)
    static ɵfac: i0.ɵɵFactoryDeclaration<MatListSubheaderCssMatStyler, never>;
}

// @public (undocumented)
export class MatNavList extends MatListBase {
    // (undocumented)
    _isNonInteractive: boolean;
    // (undocumented)
    static ɵcmp: i0.ɵɵComponentDeclaration<MatNavList, "mat-nav-list", ["matNavList"], {}, {}, never, ["*"], true, never>;
    // (undocumented)
    static ɵfac: i0.ɵɵFactoryDeclaration<MatNavList, never>;
}

// @public (undocumented)
export class MatSelectionList extends MatListBase implements SelectionList, ControlValueAccessor, AfterViewInit, OnChanges, OnDestroy {
    constructor(...args: unknown[]);
    color: ThemePalette;
    compareWith: (o1: any, o2: any) => boolean;
    deselectAll(): MatListOption[];
    get disabled(): boolean;
    set disabled(value: BooleanInput);
    // (undocumented)
    _element: ElementRef<HTMLElement>;
    _emitChangeEvent(options: MatListOption[]): void;
    focus(options?: FocusOptions): void;
    _handleKeydown(event: KeyboardEvent): void;
    get hideSingleSelectionIndicator(): boolean;
    set hideSingleSelectionIndicator(value: BooleanInput);
    // (undocumented)
    _items: QueryList<MatListOption>;
    get multiple(): boolean;
    set multiple(value: BooleanInput);
    // (undocumented)
    ngAfterViewInit(): void;
    // (undocumented)
    ngOnChanges(changes: SimpleChanges): void;
    // (undocumented)
    ngOnDestroy(): void;
    _onTouched: () => void;
    get options(): QueryList<MatListOption>;
    registerOnChange(fn: (value: any) => void): void;
    registerOnTouched(fn: () => void): void;
    _reportValueChange(): void;
    selectAll(): MatListOption[];
    selectedOptions: SelectionModel<MatListOption>;
    readonly selectionChange: EventEmitter<MatSelectionListChange>;
    setDisabledState(isDisabled: boolean): void;
    _value: string[] | null;
    writeValue(values: string[]): void;
    // (undocumented)
    static ɵcmp: i0.ɵɵComponentDeclaration<MatSelectionList, "mat-selection-list", ["matSelectionList"], { "color": { "alias": "color"; "required": false; }; "compareWith": { "alias": "compareWith"; "required": false; }; "multiple": { "alias": "multiple"; "required": false; }; "hideSingleSelectionIndicator": { "alias": "hideSingleSelectionIndicator"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; }, { "selectionChange": "selectionChange"; }, ["_items"], ["*"], true, never>;
    // (undocumented)
    static ɵfac: i0.ɵɵFactoryDeclaration<MatSelectionList, never>;
}

// @public
export class MatSelectionListChange {
    constructor(
    source: MatSelectionList,
    options: MatListOption[]);
    options: MatListOption[];
    source: MatSelectionList;
}

// @public
export const SELECTION_LIST: InjectionToken<SelectionList>;

// @public
export interface SelectionList extends MatListBase {
    // (undocumented)
    color: ThemePalette;
    // (undocumented)
    compareWith: (o1: any, o2: any) => boolean;
    // (undocumented)
    _emitChangeEvent(options: MatListOption[]): void;
    // (undocumented)
    hideSingleSelectionIndicator: boolean;
    // (undocumented)
    multiple: boolean;
    // (undocumented)
    _onTouched(): void;
    // (undocumented)
    _reportValueChange(): void;
    // (undocumented)
    selectedOptions: SelectionModel<MatListOption>;
    // (undocumented)
    _value: string[] | null;
}

// (No @packageDocumentation comment for this package)

```


"@ampproject/remapping@2.3.0", "@ampproject/remapping@^2.2.0":
  version "2.3.0"
  resolved "https://registry.yarnpkg.com/@ampproject/remapping/-/remapping-2.3.0.tgz#ed441b6fa600072520ce18b43d2c8cc8caecc7f4"
  integrity sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw==
  dependencies:
    "@jridgewell/gen-mapping" "^0.3.5"
    "@jridgewell/trace-mapping" "^0.3.24"

"@angular-devkit/architect@0.1900.0-next.3":
  version "0.1900.0-next.3"
  resolved "https://registry.yarnpkg.com/@angular-devkit/architect/-/architect-0.1900.0-next.3.tgz#1e35eb39a11a93127001f53455e3377cbe8b8a83"
  integrity sha512-uEVpjcojOPWfLfpjCqmbO/nphBbOIo+qBwruOiUv9WACSXown+GMYPvQSIkeuLdpQTKSGETjegEKs09VWgwomA==
  dependencies:
    "@angular-devkit/core" "19.0.0-next.3"
    rxjs "7.8.1"

"@angular-devkit/build-angular@file:../../node_modules/@angular-devkit/build-angular":
  version "19.0.0-next.3"
  dependencies:
    "@ampproject/remapping" "2.3.0"
    "@angular-devkit/architect" "0.1900.0-next.3"
    "@angular-devkit/build-webpack" "0.1900.0-next.3"
    "@angular-devkit/core" "19.0.0-next.3"
    "@angular/build" "19.0.0-next.3"
    "@babel/core" "7.25.2"
    "@babel/generator" "7.25.6"
    "@babel/helper-annotate-as-pure" "7.24.7"
    "@babel/helper-split-export-declaration" "7.24.7"
    "@babel/plugin-transform-async-generator-functions" "7.25.4"
    "@babel/plugin-transform-async-to-generator" "7.24.7"
    "@babel/plugin-transform-runtime" "7.25.4"
    "@babel/preset-env" "7.25.4"
    "@babel/runtime" "7.25.6"
    "@discoveryjs/json-ext" "0.6.1"
    "@ngtools/webpack" "19.0.0-next.3"
    "@vitejs/plugin-basic-ssl" "1.1.0"
    ansi-colors "4.1.3"
    autoprefixer "10.4.20"
    babel-loader "9.1.3"
    browserslist "^4.21.5"
    copy-webpack-plugin "12.0.2"
    critters "0.0.24"
    css-loader "7.1.2"
    esbuild-wasm "0.23.1"
    fast-glob "3.3.2"
    http-proxy-middleware "3.0.2"
    https-proxy-agent "7.0.5"
    istanbul-lib-instrument "6.0.3"
    jsonc-parser "3.3.1"
    karma-source-map-support "1.4.0"
    less "4.2.0"
    less-loader "12.2.0"
    license-webpack-plugin "4.0.2"
    loader-utils "3.3.1"
    magic-string "0.30.11"
    mini-css-extract-plugin "2.9.1"
    mrmime "2.0.0"
    open "10.1.0"
    ora "5.4.1"
    parse5-html-rewriting-stream "7.0.0"
    picomatch "4.0.2"
    piscina "4.6.1"
    postcss "8.4.45"
    postcss-loader "8.1.1"
    resolve-url-loader "5.0.0"
    rxjs "7.8.1"
    sass "1.78.0"
    sass-loader "16.0.1"
    semver "7.6.3"
    source-map-loader "5.0.0"
    source-map-support "0.5.21"
    terser "5.31.6"
    tree-kill "1.2.2"
    tslib "2.7.0"
    vite "5.4.3"
    watchpack "2.4.2"
    webpack "5.94.0"
    webpack-dev-middleware "7.4.2"
    webpack-dev-server "5.1.0"
    webpack-merge "6.0.1"
    webpack-subresource-integrity "5.1.0"
  optionalDependencies:
    esbuild "0.23.1"

"@angular-devkit/build-webpack@0.1900.0-next.3":
  version "0.1900.0-next.3"
  resolved "https://registry.yarnpkg.com/@angular-devkit/build-webpack/-/build-webpack-0.1900.0-next.3.tgz#18102c548cd5cbc6ef21139ef2382ddb1940f196"
  integrity sha512-5R6Hi90OlngS0D3PmzczAAk/afm3FWpzz3tj9iYRGjUd3XhBfBVxsaNOljZc75JOeq267Bkh5Fwec2W3HfK+GA==
  dependencies:
    "@angular-devkit/architect" "0.1900.0-next.3"
    rxjs "7.8.1"

"@angular-devkit/core@19.0.0-next.3":
  version "19.0.0-next.3"
  resolved "https://registry.yarnpkg.com/@angular-devkit/core/-/core-19.0.0-next.3.tgz#fcfd9b1e53213dd5361ac4e047ee8cf265e9453c"
  integrity sha512-T8nrvv+lAz88/k/e9nHrhMq2W0JxuQEb4NztxYC8zbhdbO+rW9fHNne/bu96ck1vqHqSztTpsn50KXrbSNZVJQ==
  dependencies:
    ajv "8.17.1"
    ajv-formats "3.0.1"
    jsonc-parser "3.3.1"
    picomatch "4.0.2"
    rxjs "7.8.1"
    source-map "0.7.4"

"@angular-devkit/schematics@19.0.0-next.3":
  version "19.0.0-next.3"
  resolved "https://registry.yarnpkg.com/@angular-devkit/schematics/-/schematics-19.0.0-next.3.tgz#4c68d781a332397b0d686bdad9430d0a66cec16b"
  integrity sha512-wTkbkiI8RoudBL4nLfbs9rezwOomhwA7ZoVNqSP6FUzSJpBtgHTLB2NzcwhOuBKqAmoGwZqg9n8R7P7P3lotzA==
  dependencies:
    "@angular-devkit/core" "19.0.0-next.3"
    jsonc-parser "3.3.1"
    magic-string "0.30.11"
    ora "5.4.1"
    rxjs "7.8.1"

"@angular/animations@file:../../node_modules/@angular/animations":
  version "19.0.0-next.3"
  dependencies:
    tslib "^2.3.0"


<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>YarnPnpCompat</title>
  <base href="/">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" type="image/x-icon" href="favicon.ico">
  <link rel="preconnect" href="https://fonts.gstatic.com">
  <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500&display=swap" rel="stylesheet">
  <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
</head>
<body class="mat-typography">
  <app-root></app-root>
</body>
</html>


@use '@angular/material' as mat;

$primary: mat.m2-define-palette(mat.$m2-blue-palette);
$accent: mat.m2-define-palette(mat.$m2-grey-palette);
$theme: mat.m2-define-light-theme((
  color: (primary: $primary, accent: $accent),
  typography: mat.m2-define-typography-config(),
  density: 0
));

@include mat.all-component-themes($theme);

html,
body {
  height: 100%;
}

body {
  margin: 0;
  font-family: Roboto, 'Helvetica Neue', sans-serif;
}


/**
 * This file includes polyfills needed by Angular and is loaded before the app.
 * You can add your own extra polyfills to this file.
 *
 * This file is divided into 2 sections:
 *   1. Browser polyfills. These are applied before loading ZoneJS and are sorted by browsers.
 *   2. Application imports. Files imported after ZoneJS that should be loaded before your main
 *      file.
 *
 * The current setup is for so-called "evergreen" browsers; the last versions of browsers that
 * automatically update themselves. This includes recent versions of Safari, Chrome (including
 * Opera), Edge on the desktop, and iOS and Chrome on mobile.
 *
 * Learn more in https://angular.dev/reference/versions#browser-support
 */

/***************************************************************************************************
 * BROWSER POLYFILLS
 */

/**
 * By default, zone.js will patch all possible macroTask and DomEvents
 * user can disable parts of macroTask/DomEvents patch by setting following flags
 * because those flags need to be set before `zone.js` being loaded, and webpack
 * will put import in the top of bundle, so user need to create a separate file
 * in this directory (for example: zone-flags.ts), and put the following flags
 * into that file, and then add the following code before importing zone.js.
 * import './zone-flags';
 *
 * The flags allowed in zone-flags.ts are listed here.
 *
 * The following flags will work for all browsers.
 *
 * (window as any).__Zone_disable_requestAnimationFrame = true; // disable patch requestAnimationFrame
 * (window as any).__Zone_disable_on_property = true; // disable patch onProperty such as onclick
 * (window as any).__zone_symbol__UNPATCHED_EVENTS = ['scroll', 'mousemove']; // disable patch specified eventNames
 *
 *  in IE/Edge developer tools, the addEventListener will also be wrapped by zone.js
 *  with the following flag, it will bypass `zone.js` patch for IE/Edge
 *
 *  (window as any).__Zone_enable_cross_context_check = true;
 *
 */

/***************************************************************************************************
 * Zone JS is required by default for Angular itself.
 */
import 'zone.js'; // Included with Angular CLI.

/***************************************************************************************************
 * APPLICATION IMPORTS
 */


import {NgModule} from '@angular/core';
import {BrowserModule} from '@angular/platform-browser';
import {MatButtonModule} from '@angular/material/button';

import {AppComponent} from './app.component';
import {BrowserAnimationsModule} from '@angular/platform-browser/animations';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, BrowserAnimationsModule, MatButtonModule],
  bootstrap: [AppComponent],
})
export class AppModule {}


# Customizing Angular Material component styles

Angular Material supports customizing component styles via Sass API as described in the [theming
guide][]. This document provides guidance on defining custom CSS rules that directly style
Angular Material components.

[theming guide]: https://material.angular.io/guide/theming

## Targeting custom styles

### Component host elements

For any Angular Material component, you can safely define custom CSS for a component's host element
that affect the positioning or layout of that component, such as `margin`, `position`, `top`,
`left`, `transform`, and `z-index`. You should apply such styles by defining a custom CSS
class and applying that class to the component's host element.

Avoid defining custom styles that would affect the size or internal layout of the component, such as
`padding`, `height`, `width`, or `overflow`. You can specify `display: none` to hide a component,
but avoid specifying any other `display` value. Overriding these properties can break components
in unexpected ways as the internal styles change between releases.

### Internal component elements

Avoid any custom styles or overrides on internal elements within a Angular Material components.
The DOM structure and CSS classes applied for each component may change at any time, causing custom
styles to break.

## Applying styles to Angular Material components

While Angular Material does not support defining custom styles or CSS overrides on components'
internal elements, you might choose to do this anyway. There are three points to consider while
customizing styles for Angular Material components: view encapsulation, CSS specificity, and
rendering location.

### View encapsulation

By default, Angular scopes component styles to exclusively affect that component's view. This means
that the styles you author affect only the elements directly within your component template.
Encapsulated styles do *not* affect elements that are children of other components within your
template. You can read more about view encapsulation in the
[Angular documentation](https://angular.dev/guide/components/styling#style-scoping). You may
also wish to review
[_The State of CSS in Angular_](https://blog.angular.io/the-state-of-css-in-angular-4a52d4bd2700)
on the Angular blog.

#### Bypassing encapsulation

Angular Material disables style encapsulation for all components in the library. However, the
default style encapsulation in your own components still prevents custom styles from leaking into
Angular Material components.

If your component enables view encapsulation, your component styles will only
affect the elements explicitly defined in your template. To affect descendants of components used
in your template, you can use one of the following approaches:

1. Define custom styles in a global stylesheet declared in the `styles` array of your `angular.json`
configuration file.
2. Disable view encapsulation for your component. This approach effectively turns your component
styles into global CSS.
3. Apply the deprecated `::ng-deep` pseudo-class to a CSS rule. Any CSS rule with `::ng-deep`
becomes a global style. [See the Angular documentation for more on `::ng-deep`][ng-deep].

All of these approaches involve creating global CSS that isn't affected by style encapsulation.
Global CSS affects all elements in your application. Global CSS class names may collide with class
names defined by components. Global CSS is often a source of hard-to-diagnose bugs and is generally
difficult to maintain.

[ng-deep]: https://angular.dev/guide/components/styling#ng-deep

### CSS specificity

Each CSS declaration has a level of *specificity* based on the type and number of selectors used.
More specific styles take precedence over less specific styles. Angular Material generally attempts
to use the least specific selectors possible. However, Angular Material may change component style
specificity at any time, making custom overrides brittle and prone to breaking.

You can read more about specificity and how it is calculated on the
[MDN web docs](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity).

### Rendering location

Some Angular Material components render elements that are not direct DOM descendants of the
component's host element. In particular, overlay-based components such as `MatDialog`, `MatMenu`,
`MatTooltip`, etc. render into an overlay container element directly on the document body. Because
these components render elements outside of your application's components, component-specific styles
will not apply to these elements. You can define styles for these elements as global styles.

#### Styling overlay components

Overlay-based components have a `panelClass` property, or similar, that let you target the
overlay pane. The following example shows how to add an `outline` style with `MatDialog`.

```scss
// Add this to your global stylesheet after including theme mixins.
.my-outlined-dialog {
  outline: 2px solid purple;
}
```

```ts
this.dialog.open(MyDialogComponent, {panelClass: 'my-outlined-dialog'})
```

You should always apply an application-specific prefix to global CSS classes to avoid naming
collisions.


# Installation and Code Generation

Angular Material comes packaged with Angular CLI schematics to make
creating Material applications easier.

## Install Schematics

Schematics are included with both `@angular/cdk` and `@angular/material`. Once you install the npm
packages, they will be available through the Angular CLI.

Using the command below will install Angular Material, the [Component Dev Kit](https://material.angular.io/cdk) (CDK),
and [Angular Animations](https://angular.dev/guide/animations) in your project. Then it will run the
installation schematic.

```
ng add @angular/material
```

In case you just want to install the `@angular/cdk`, there are also schematics for the [Component Dev Kit](https://material.angular.io/cdk)

```
ng add @angular/cdk
```

The Angular Material `ng add` schematic helps you set up an Angular CLI project that uses Material. Running `ng add` will:

- Ensure [project dependencies](./getting-started#step-1-install-angular-material-angular-cdk-and-angular-animations) are placed in `package.json`
- Enable the [BrowserAnimationsModule](./getting-started#step-2-configure-animations) in your app module
- Add either a [prebuilt theme](./theming#pre-built-themes) or a [custom theme](./theming#defining-a-custom-theme)
- Add Roboto fonts to your `index.html`
- Add the [Material Icon font](./getting-started#step-6-optional-add-material-icons) to your `index.html`
- Add global styles to
  - Remove margins from `body`
  - Set `height: 100%` on `html` and `body`
  - Make Roboto the default font of your app

## Component schematics

In addition to the installation schematic, Angular Material comes with multiple schematics that can be
used to easily generate Material Design components:

| Name           | Description                                                                                |
|----------------|--------------------------------------------------------------------------------------------------------|
| `address-form` | Component with a form group that uses Material Design form controls to prompt for a shipping address   |
| `navigation`   | Creates a component with a responsive Material Design sidenav and a toolbar for showing the app name   |
| `dashboard`    | Component with multiple Material Design cards and menus which are aligned in a grid layout             |
| `table`        | Generates a component with a Material Design data table that supports sorting and pagination           |
| `tree`         | Component that interactively visualizes a nested folder structure by using the `<mat-tree>` component  |

Additionally, the Angular CDK also comes with a collection of component schematics:

| Name           | Description                                                                                |
|----------------|----------------------------------------------------------------------------------------------------|
| `drag-drop`    | Component that uses the `@angular/cdk/drag-drop` directives for creating an interactive to-do list |

### Address form schematic

Running the `address-form` schematic generates a new Angular component that can be used to get
started with a Material Design form group consisting of:

* Material Design form fields
* Material Design radio controls
* Material Design buttons

```
ng generate @angular/material:address-form <component-name>
```

### Navigation schematic

The `navigation` schematic will create a new component that includes
a toolbar with the app name, and a responsive side nav based on Material
breakpoints.

```
ng generate @angular/material:navigation <component-name>
```

### Table schematic

The table schematic will create a component that renders an Angular Material `<table>` which has
been pre-configured with a datasource for sorting and pagination.

```
ng generate @angular/material:table <component-name>
```

### Dashboard schematic

The `dashboard` schematic will create a new component that contains
a dynamic grid list of Material Design cards.

```
ng generate @angular/material:dashboard <component-name>
```

### Tree schematic

The `tree` schematic can be used to quickly generate an Angular component that uses the Angular
Material `<mat-tree>` component to visualize a nested folder structure.

```
ng generate @angular/material:tree <component-name>
```

### Drag and Drop schematic

The `drag-drop` schematic is provided by the `@angular/cdk` and can be used to generate a component
that uses the CDK drag and drop directives.

```
ng generate @angular/cdk:drag-drop <component-name>
```

### Material 3 Theme schematic

The `theme-color` schematic will generate a file with Material 3 palettes from the specified colors
that can be used in a theme file. It also generates high contrast color override mixins if
specified.

```
ng generate @angular/material:theme-color
```

Learn more about this schematic in its [documentation](https://github.com/angular/components/blob/main/src/material/schematics/ng-generate/theme-color/README.md).


# Theme your own components with Angular Material's theming system

You can use Angular Material's Sass-based theming system for your own custom components.

**Note: The information on this page is specific to Material 3, for Material 2
information on how to theme your components see the [Material 2 guide][material-2].**

[material-2]: https://material.angular.io/guide/material-2-theming#theming-your-components

## Reading values from a theme

As described in the [theming guide][theme-map], a theme is a Sass map that contains style values to
customize components. Angular Material provides APIs for reading values from this data structure.

[theme-map]: https://material.angular.io/guide/theming#defining-a-theme

### Reading tonal palette colors

To read a
[tonal palette color](https://m3.material.io/styles/color/system/how-the-system-works#3ce9da92-a118-4692-8b2c-c5c52a413fa6)
from the theme, use the `get-theme-color` function with three arguments:

| Argument   | Description                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `$theme`   | The M3 theme to read from.                                                                                |
| `$palette` | The name of the palette to read from. This can be any of the standard M3 palettes:

`primary`

`secondary`

`tertiary`

`error`

`neutral`

`neutral-variant`

                                                   |
| `$hue`     | The hue number to read within the palette. This can be any of the standard hues:

`0`

`10`

`20`

`30`

`40`

`50`

`60`

`70`

`80`

`90`

`95`

`99`

`100`

 |

### Reading color roles

To read a [color role](https://m3.material.io/styles/color/roles), use `get-theme-color` with two
arguments:

| Argument | Description                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$theme` | The M3 theme to read from.                                                                                |
| `$role`  | The name of the color role. This can be any of the M3 color roles:

`primary`

`on-primary`

`primary-container`

`on-primary-container`

`primary-fixed`

`primary-fixed-dim`

`on-primary-fixed`

`on-primary-fixed-variant`

`secondary`

`on-secondary`

`secondary-container`

`on-secondary-container`

`secondary-fixed`

`secondary-fixed-dim`

`on-secondary-fixed`

`on-secondary-fixed-variant`

`tertiary`

`on-tertiary`

`tertiary-container`

`on-tertiary-container`

`tertiary-fixed`

`tertiary-fixed-dim`

`on-tertiary-fixed`

`on-tertiary-fixed-variant`

`error`

`on-error`

`error-container`

`on-error-container`

`surface-dim`

`surface`

`surface-bright`

`surface-container-lowest`

`surface-container-low`

`surface-container`

`surface-container-high`

`surface-container-highest`

`on-surface`

`on-surface-variant`

`outline`

`outline-variant`

`inverse-surface`

`inverse-on-surface`

`inverse-primary`

`scrim`

`shadow`

 |

### Reading the theme type

To read the theme type (`light` or `dark`), call `get-theme-type` with a single argument:

| Argument | Description                |
| -------- | -------------------------- |
| `$theme` | The M3 theme to read from. |

### Reading typescale properties

To read a [typescale](https://m3.material.io/styles/typography/type-scale-tokens) property from the
theme, call `get-theme-typography` with three arguments:

| Argument    | Description                                                                                |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `$theme`    | The M3 theme to read from.                                                                                |
| `$level`    | The typescale level. This can be any of the M3 typescale levels:

`display-large`

`display-medium`

`display-small`

`headline-large`

`headline-medium`

`headline-small`

`title-large`

`title-medium`

`title-small`

`body-large`

`body-medium`

`body-small`

`label-large`

`label-medium`

`label-small`

 |
| `$property` | The CSS font property to get a value for. This can be one of the following CSS properties:

`font` (The CSS font shorthand, includes all font properties except letter-spacing)

`font-family`

`font-size`

`font-weight`

`line-height`

`letter-spacing`

                                                                                |

### Reading the density scale

To read the density scale (`0`, `-1`, `-2`, `-3`, `-4`, or `-5`) from the theme, call
`get-theme-density` with a single argument:

| Argument | Description                |
| -------- | -------------------------- |
| `$theme` | The M3 theme to read from. |

### Checking what dimensions are configured for a theme

Depending on how a theme was created, it may not have configuration data for all theming dimensions
(base, color, typography, density). You can check if a theme has a configuration for a particular
dimension by calling the `theme-has` Sass function, passing the theme and the dimension to check.

See the below example of checking the configured dimensions for a theme:

```scss
$theme: mat.define-theme(...);

$has-base: mat.theme-has($theme, base);
$has-color: mat.theme-has($theme, color);
$has-typography: mat.theme-has($theme, typography);
$has-density: mat.theme-has($theme, density);
```

## Separating theme styles

Angular Material components each have a Sass file that defines mixins for customizing
that component's color and typography. For example, `MatButton` has mixins for `button-color` and
`button-typography`. Each mixin emits all color and typography styles for that component,
respectively.

You can mirror this structure in your components by defining your own mixins. These mixins
should accept an Angular Material theme, from which they can read color and typography values. You
can then include these mixins in your application along with Angular Material's own mixins.


## Step-by-step example

To illustrate participation in Angular Material's theming system, we can look at an example of a
custom carousel component. The carousel starts with a single file, `carousel.scss`, that contains
structural, color, and typography styles. This file is included in the `styleUrls` of the component.

```scss
// carousel.scss

.my-carousel {
  display: flex;
  font-family: serif;
}

.my-carousel-button {
  border-radius: 50%;
  color: blue;
}
```

### Step 1: Extract theme-based styles to a separate file

To change this file to participate in Angular Material's theming system, we split the styles into
two files, with the color and typography styles moved into mixins. By convention, the new file
name ends with `-theme`. Additionally, the file starts with an underscore (`_`), indicating that
this is a Sass partial file. See the [Sass documentation][sass-partials] for more information about
partial files.

[sass-partials]: https://sass-lang.com/guide#topic-4

```scss
// carousel.scss

.my-carousel {
  display: flex;
}

.my-carousel-button {
  border-radius: 50%;
}
```

```scss
// _carousel-theme.scss

@mixin color($theme) {
  .my-carousel-button {
    color: blue;
  }
}

@mixin typography($theme) {
  .my-carousel {
    font-family: serif;
  }
}
```

### Step 2: Use values from the theme

Now that theme theme-based styles reside in mixins, we can extract the values we need from the
theme passed into the mixins.

```scss
// _carousel-theme.scss

@use 'sass:map';
@use '@angular/material' as mat;

@mixin color($theme) {
  .my-carousel-button {
    // Read the 50 hue from the primary color palette.
    color: mat.get-theme-color($theme, primary, 50);
  }
}

@mixin typography($theme) {
  .my-carousel {
    // Get the large headline font from the theme.
    font: mat.get-theme-typography($theme, headline-large, font);
  }
}
```

### Step 3: Add a theme mixin

For convenience, we can add a `theme` mixin that includes both color and typography.
This theme mixin should only emit the styles for each color and typography, respectively, if they
have a config specified.

```scss
// _carousel-theme.scss

@use 'sass:map';
@use '@angular/material' as mat;

@mixin color($theme) {
  .my-carousel-button {
    // Read the 50 hue from the primary color palette.
    color: mat.get-theme-color($theme, primary, 50);
  }
}

@mixin typography($theme) {
  .my-carousel {
    // Get the large headline font from the theme.
    font: mat.get-theme-typography($theme, headline-large, font);
  }
}

@mixin theme($theme) {
  @if mat.theme-has($theme, color) {
    @include color($theme);
  }

  @if mat.theme-has($theme, typography) {
    @include typography($theme);
  }
}
```

### Step 4: Include the theme mixin in your application

Now that you've defined the carousel component's theme mixin, you can include this mixin along with
the other theme mixins in your application.

```scss
@use '@angular/material' as mat;
@use './path/to/carousel-theme' as carousel;

$my-theme: mat.define-theme((
  color: (
    theme-type: light,
    primary: mat.$red-palette,
  ),
  typography: (
    brand-family: 'Comic Sans',
    bold-weight: 900,
  ),
));

html {
  @include mat.all-component-themes($my-theme);
  @include carousel.theme($my-theme);
}
```


# Getting Started with Angular Material

This guide explains how to set up your Angular project to begin using Angular Material. It includes
information on prerequisites, installing Angular Material, and optionally displaying a sample
Material component in your application to verify your setup.

This guide assumes that the [Angular CLI](https://angular.dev/tools/cli/setup-local#install-the-angular-cli) has already been installed.

## Install Angular Material

Add Angular Material to your application by running the following command:

```bash
ng add @angular/material
```

The `ng add` command will install Angular Material, the
[Component Dev Kit (CDK)](https://material.angular.io/cdk/categories),
[Angular Animations](https://angular.dev/guide/animations) and ask you the following questions to
determine which features to include:

1. Choose a prebuilt theme name, or "custom" for a custom theme:

   You can choose from [prebuilt material design themes](https://material.angular.io/guide/theming#pre-built-themes) or set up an extensible [custom theme](https://material.angular.io/guide/theming#defining-a-theme).

2. Set up global Angular Material typography styles:

   Whether to apply the global [typography](https://material.angular.io/guide/typography) styles to your application.

3. Set up browser animations for Angular Material:

   Importing the [`BrowserAnimationsModule`](https://angular.dev/api/platform-browser/animations/BrowserAnimationsModule) into your application enables Angular's [animation system](https://angular.dev/guide/animations). Declining this will disable most of Angular Material's animations.

The `ng add` command will additionally perform the following actions:

* Add project dependencies to `package.json`
* Add the Roboto font to your `index.html`
* Add the Material Design icon font to your `index.html`
* Add a few global CSS styles to:
  * Remove margins from `body`
  * Set `height: 100%` on `html` and `body`
  * Set Roboto as the default application font

You're done! Angular Material is now configured to be used in your application.

### Display a component

Let's display a slide toggle component in your app and verify that everything works.

You need to import the `MatSlideToggleModule` that you want to display by adding the following lines to
your standalone component's imports, or otherwise your component's `NgModule`.

```ts
import { MatSlideToggleModule } from '@angular/material/slide-toggle';

@Component ({
  imports: [
    MatSlideToggleModule,
  ]
})
class AppComponent {}
```

Add the `<mat-slide-toggle>` tag to the `app.component.html` like so:

```html
<mat-slide-toggle>Toggle me!</mat-slide-toggle>
```

Run your local dev server:

```bash
ng serve
```

Then point your browser to [http://localhost:4200](http://localhost:4200)

You should see the Material slide toggle component on the page.

In addition to the installation schematic, Angular Material comes with
[several other schematics](https://material.angular.io/guide/schematics) (like nav, table,
address-form, etc.) that can be used to easily generate pre-built components in your application.


# Theming Angular Material

## What is theming?

Angular Material's theming system lets you customize base, color, typography, and density styles for components in your application. The theming system is based on Google's
[Material Design 3][material-design-theming] specification which is the latest
iteration of Google's open-source design system, Material Design.

**For Material 2 specific documentation and how to update to Material 3, see the
[Material 2 guide][material-2].**

This document describes the concepts and APIs for customizing colors. For typography customization,
see [Angular Material Typography][mat-typography]. For guidance on building components to be
customizable with this system, see [Theming your own components][theme-your-own].

[material-design-theming]: https://m3.material.io/
[material-2]: https://material.angular.io/guide/material-2-theming
[mat-typography]: https://material.angular.io/guide/typography
[theme-your-own]: https://material.angular.io/guide/theming-your-components

### Sass

Angular Material's theming APIs are built with [Sass](https://sass-lang.com). This document assumes
familiarity with CSS and Sass basics, including variables, functions, and mixins.

### Custom themes with Sass

A **theme file** is a Sass file that calls Angular Material Sass mixins to output color,
typography, and density CSS styles.

#### Defining a theme

Angular Material represents a theme as a Sass map that contains your color, typography, and density
choices, as well as some base design system settings.

The simplest usage of the API, `$theme: mat.define-theme()` defines a theme with default values.
However, `define-theme` allows you to configure the appearance of your
Angular Material app along three theming dimensions: color, typography, and density, by passing a
theme configuration object. The configuration object may have the following properties.

| Property     | Description                                                                                |
| ------------ | --------------------------------------------------------------------------------------------------------------- |
| `color`      | [Optional] A map of color options. See [customizing your colors](#customizing-your-colors) for details.         |
| `typography` | [Optional] A map of typography options. See [customizing your typography](#customizing-your-typography) for details. |
| `density`    | [Optional] A map of density options. See [customizing your density](#customizing-your-density) for details.     |

<!-- TODO(mmalerba): Upgrade to embedded example -->

```scss
@use '@angular/material' as mat;

$theme: mat.define-theme((
  color: (
    theme-type: dark,
    primary: mat.$violet-palette,
  ),
  typography: (
    brand-family: 'Comic Sans',
    bold-weight: 900
  ),
  density: (
    scale: -1
  )
));
```

#### Customizing your colors

The following aspects of your app's colors can be customized via the `color` property of the theme
configuration object (see the [M3 color spec](https://m3.material.io/styles/color/roles) to learn
more about these terms):

| Color Property | Description                                                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `theme-type`   | [Optional] Specifies the type of theme, `light` or `dark`. The choice of a light versus a dark theme determines the background and foreground colors used throughout the components.                                                                                |
| `primary`      | [Optional] Specifies the palette to use for the app's primary color palette. (Note: the secondary, neutral, and neutral-variant palettes described in the M3 spec will be automatically chosen based on your primary palette, to ensure a harmonious color combination). |
| `tertiary`     | [Optional] Specifies the palette to use for the app's tertiary color palette.                                                                                |

##### Pre-built themes

Angular Material includes several pre-built theme CSS files, each with different palettes selected.
You can use one of these pre-built themes if you don't want to define a custom theme with Sass.

| Theme                  | Light or dark? | Specification                    |
|------------------------|----------------|----------------------------------|
| `azure-blue.css`       | Light          | Material Design 3                |
| `rose-red.css`         | Light          | Material Design 3                |
| `cyan-orange.css`      | Dark           | Material Design 3                |
| `magenta-violet.css`   | Dark           | Material Design 3                |
| `deeppurple-amber.css` | Light          | Material Design 2                |
| `indigo-pink.css`      | Light          | Material Design 2                |
| `pink-bluegrey.css`    | Dark           | Material Design 2                |
| `purple-green.css`     | Dark           | Material Design 2                |

These files include the CSS for every component in the library. To include only the CSS for a subset
of components, you must use the Sass API detailed in [Defining a theme](#defining-a-theme) above.
You can [reference the source code for these pre-built themes](https://github.com/angular/components/blob/main/src/material/core/theming/prebuilt) to see examples of complete theme definitions.

##### Pre-defined palettes

The pre-built themes are based on a set of pre-defined palettes that can be used with the `primary`
and `tertiary` options:

- `$red-palette`
- `$green-palette`
- `$blue-palette`
- `$yellow-palette`
- `$cyan-palette`
- `$magenta-palette`
- `$orange-palette`
- `$chartreuse-palette`
- `$spring-green-palette`
- `$azure-palette`
- `$violet-palette`
- `$rose-palette`

##### Custom theme
Alternatively, custom palettes can be generated with a custom color with the following schematic:

```shell
ng generate @angular/material:theme-color
```

This schematic integrates with [Material Color Utilities](https://github.com/material-foundation/material-color-utilities) to build palettes based on a single color. Optionally you can provide
additional custom colors for the secondary, tertiary, and neutral palettes.

The output of the schematic is a new Sass file that exports the palettes that can be provided to
a theme definition.

```scss
@use '@angular/material' as mat;
@use './path/to/my-theme'; // location of generated file

html {
  @include mat.theme(
    color: (
      primary: my-theme.$primary-palette,
      tertiary: my-theme.$tertiary-palette,
    ),
    typography: Roboto,
    density: 0,
  )
}
```

You can also optionally generate high contrast override mixins for your custom theme that allows for
a better accessibility experience. Learn more about this schematic in its [documentation](https://github.com/angular/components/blob/main/src/material/schematics/ng-generate/theme-color/README.md).

<!-- TODO(mmalerba): Illustrate palettes with example. -->

#### Customizing your typography

The following aspects of your app's typography can be customized via the `typography` property of
the theme configuration object.

| Typography Property | Description                                                          |
| ------------------- | -------------------------------------------------------------------- |
| `plain-family`      | [Optional] The font family to use for plain text, such as body text. |
| `brand-family`      | [Optional] The font family to use for brand text, such as headlines. |
| `bold-weight`       | [Optional] The font weight to use for bold text.                     |
| `medium-weight`     | [Optional] The font weight to use for medium text.                   |
| `regular-weight`    | [Optional] The font weight to use for regular text.                  |

See the [typography guide](https://material.angular.io/guide/typography) for more
information.

#### Customizing your density

The following aspects of your app's density can be customized via the `density` property of the
theme configuration object:

| Density Property | Description                                                                                |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| `scale`          | [Optional] The level of compactness of the components in your app, from `0` (most space) to `-5` (most compact). |


#### Applying a theme to components

The `core-theme` Sass mixin emits prerequisite styles for common features used by multiple
components, such as ripples. This mixin must be included once per theme.

Each Angular Material component has a mixin for each [theming dimension](#theming-dimensions): base,
color, typography, and density. For example, `MatButton` declares `button-base`, `button-color`,
`button-typography`, and `button-density`. Each mixin emits only the styles corresponding to that
dimension of customization.

Additionally, each component has a "theme" mixin that emits all styles that depend on the theme
config. This theme mixin only emits color, typography, or density styles if you provided a
corresponding configuration to `define-theme`, and it always emits the base styles.

Once you've created your theme, you can apply it using the same `-theme`, `-color`, `-typography`, `-density`, and `-base` mixins.

For M3 themes, these mixins make some guarantees about the emitted styles.

- The mixins emit properties under the exact selector you specify. They will _not_ add to the
  selector or increase the specificity of the rule.
- The mixins only emit
  [CSS custom property declarations](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)
  (e.g. `--some-prop: xyz`). They do _not_ emit any standard CSS properties such as `color`,
  `width`, etc.

Apply the styles for each of the components used in your application by including each of their
theme Sass mixins.

```scss
@use '@angular/material' as mat;

$my-theme: mat.define-theme((
 color: (
    theme-type: light,
    primary: mat.$violet-palette,
  ),
));

html {
  // Emit theme-dependent styles for common features used across multiple components.
  @include mat.core-theme($my-theme);

  // Emit styles for MatButton based on `$my-theme`. Because the configuration
  // passed to `define-theme` omits typography, `button-theme` will not
  // emit any typography styles.
  @include mat.button-theme($my-theme);

  // Include the theme mixins for other components you use here.
}
```

As an alternative to listing every component that your application uses, Angular Material offers
Sass mixins that includes styles for all components in the library: `all-component-bases`,
`all-component-colors`, `all-component-typographies`, `all-component-densities`, and
`all-component-themes`. These mixins behave the same as individual component mixins, except they
emit styles for `core-theme` and _all_ 35+ components in Angular Material. Unless your application
uses every single component, this will produce unnecessary CSS.

```scss
@use '@angular/material' as mat;

$my-theme: mat.define-theme((
 color: (
    theme-type: light,
    primary: mat.$violet-palette,
  ),
));

html {
  @include mat.all-component-themes($my-theme);
}
```

To include the emitted styles in your application, [add your theme file to the `styles` array of
your project's `angular.json` file][adding-styles].

[adding-styles]: https://angular.dev/reference/configs/workspace-config#styles-and-scripts-configuration

#### Theming dimensions

Angular Material themes are divided along four dimensions: base, color, typography, and density.

##### Base

Common base styles for the design system. These styles don't change based on your configured
colors, typography, or density, so they only need to be included once per application. These
mixins include structural styles such as border-radius, border-width, etc. All components have a base
mixin that can be used to include its base styles. (For example,
`@include mat.checkbox-base($theme)`)

##### Color

Styles related to the colors in your application. These style should be included at least once in
your application. Depending on your needs, you may need to include these styles multiple times
with different configurations. (For example, if your app supports light and dark theme colors.)
All components have a color mixin that can be used to include its color styles. (For example,
`@include mat.checkbox-color($theme)`)

##### Typography

Styles related to the fonts used in your application, including the font family, size, weight,
line-height, and letter-spacing. These style should be included at least once in your application.
Depending on your needs, you may need to include these styles multiple times with different
configurations. (For example, if your app supports reading content in either a serif or sans-serif
font.) All components  have a typography mixin that can be used to include its typography
styles. (For example, `@include mat.checkbox-typography($theme)`)

##### Density

Styles related to the size and spacing of elements in your application. These style should be
included at least once in your application. Depending on your needs, you may need to include these
styles multiple times with different configurations. (For example, if your app supports both a
normal and compact mode). All components have a density mixin that can be used to include its
density styles. (For example, `@include mat.checkbox-density($theme)`)

##### Theme mixin

All components also support a theme mixin that can be used to include the component's styles for all
theme dimensions at once. (For example, `@include mat.checkbox-theme($theme)`).

**The recommended approach is to rely on the `theme` mixins to lay down your base styles, and if
needed use the single dimension mixins to override particular aspects for parts of your app (see the
section on [Multiple themes in one file](#multiple-themes-in-one-file).)**

### Defining multiple themes

Using the Sass API described in [Defining a theme](#defining-a-theme), you can also define
_multiple_ themes by repeating the API calls multiple times. You can do this either in the same
theme file or in separate theme files.

#### Multiple themes in one file

Defining multiple themes in a single file allows you to support multiple themes without having to
manage loading of multiple CSS assets. The downside, however, is that your CSS will include more
styles than necessary.

To control which theme applies when, `@include` the mixins only within a context specified via
CSS rule declaration. See the [documentation for Sass mixins][sass-mixins] for further background.

[sass-mixins]: https://sass-lang.com/documentation/at-rules/mixin

```scss
@use '@angular/material' as mat;

// Define a dark theme
$dark-theme: mat.define-theme((
  color: (
    theme-type: dark,
    primary: mat.$violet-palette,
  ),
));

// Define a light theme
$light-theme: mat.define-theme((
  color: (
    theme-type: light,
    primary: mat.$violet-palette,
  ),
));

html {
  // Apply the dark theme by default
  @include mat.core-theme($dark-theme);
  @include mat.button-theme($dark-theme);

  // Apply the light theme only when the user prefers light themes.
  @media (prefers-color-scheme: light) {
    // Use the `-color` mixins to only apply color styles without reapplying the same
    // typography and density styles.
    @include mat.core-color($light-theme);
    @include mat.button-color($light-theme);
  }
}
```

#### Multiple themes across separate files

You can define multiple themes in separate files by creating multiple theme files per
[Defining a theme](#defining-a-theme), adding each of the files to the `styles` of your
`angular.json`. However, you must additionally set the `inject` option for each of these files to
`false` in order to prevent all the theme files from being loaded at the same time. When setting
this property to `false`, your application becomes responsible for manually loading the desired
file. The approach for this loading depends on your application.

### Application background color

By default, Angular Material does not apply any styles to your DOM outside
its own components. If you want to set your application's background color
to match the components' theme, you can either:
1. Put your application's main content inside `mat-sidenav-container`, assuming you're using
   `MatSidenav`, or
2. Apply the `mat-app-background` CSS class to your main content root element (typically `body`).


### Granular customizations with CSS custom properties

The CSS custom properties emitted by the theme mixins are derived from
[M3's design tokens](https://m3.material.io/foundations/design-tokens/overview). To further
customize your UI beyond the `define-theme` API, you can manually set these custom properties in
your styles.

The guarantees made by the theme mixins mean that you do not need to target internal selectors of
components or use excessive specificity to override any of these tokenized properties. Always apply
your base theme to your application's root element (typically `html` or `body`) and apply any
overrides on the highest-level selector where they apply.

<!-- TODO(mmalerba): Upgrade to embedded example -->

```html
<mat-sidenav-container>
  Some content...
  <mat-sidenav>
    Some sidenav content...
    <mat-checkbox class="danger">Enable admin mode</mat-checkbox>
  </mat-sidenav>
</mat-sidenav-container>
```

```scss
@use '@angular/material' as mat;

$light-theme: mat.define-theme();
$dark-theme: mat.define-theme((
  color: (
    theme-type: dark
  )
));

html {
  // Apply the base theme at the root, so it will be inherited by the whole app.
  @include mat.all-component-themes($light-theme);
}

mat-sidenav {
  // Override the colors to create a dark sidenav.
  @include mat.all-component-colors($dark-theme);
}

.danger {
  // Override the checkbox hover state to indicate that this is a dangerous setting. No need to
  // target the internal selectors for the elements that use these variables.
  --mdc-checkbox-unselected-hover-state-layer-color: red;
  --mdc-checkbox-unselected-hover-icon-color: red;
}
```

## Customizing density

Angular Material's density customization is based on the
[Material Design density guidelines][material-density]. This system defines a scale where zero
represents the default density. You can decrement the number for _more density_ and increment the
number for _less density_.

The density system is based on a *density scale*. The scale starts with the
default density of `0`. Each whole number step down (`-1`, `-2`, etc.) reduces
the affected sizes by `4dp`, down to the minimum size necessary for a component to render
coherently.

Components that appear in task-based or pop-up contexts, such as `MatDatepicker`, don't change their
size via the density system. The [Material Design density guidance][material-density] explicitly
discourages increasing density for such interactions because they don't compete for space in the
application's layout.

You can apply custom density setting to the entire library or to individual components using their
density Sass mixins.

```scss
// You can set a density setting in your theme to apply to all components.
$dark-theme: mat.define-theme((
  color: ...,
  typography: ...,
  density: (
    scale: -2
  ),
));

// Or you can selectively apply the Sass mixin to affect only specific parts of your application.
.the-dense-zone {
  @include mat.button-density(-1);
}
```

[material-density]: https://m3.material.io/foundations/layout/understanding-layout/spacing

## Strong focus indicators

By default, most components indicate browser focus by changing their background color as described
by the Material Design specification. This behavior, however, can fall short of accessibility
requirements, such as [WCAG][], which require a stronger indication of browser focus.

Angular Material supports rendering highly visible outlines on focused elements. Applications can
enable these strong focus indicators via two Sass mixins:
`strong-focus-indicators` and `strong-focus-indicators-theme`.

The `strong-focus-indicators` mixin emits structural indicator styles for all components. This mixin
should be included exactly once in an application, similar to the `core` mixin described above.

The `strong-focus-indicators-theme` mixin emits only the indicator's color styles. This mixin should
be included once per theme, similar to the theme mixins described above. Additionally, you can use
this mixin to change the color of the focus indicators in situations in which the default color
would not contrast sufficiently with the background color.

The following example includes strong focus indicator styles in an application alongside the rest of
the custom theme API.

```scss
@use '@angular/material' as mat;

@include mat.strong-focus-indicators();

$my-theme: mat.define-theme((
  color: (
    theme-type: light,
    primary: mat.$violet-palette,
  ),
));

html {
  @include mat.all-component-themes($my-theme);
  @include mat.strong-focus-indicators-theme($my-theme);
}
```

### Customizing strong focus indicators

You can pass a configuration map to `strong-focus-indicators` to customize the appearance of the
indicators. This configuration includes `border-style`, `border-width`, and `border-radius`.

You also can customize the color of indicators with `strong-focus-indicators-theme`. This mixin
accepts either a theme, as described earlier in this guide, or a CSS color value. When providing a
theme, the indicators will use the default hue of the primary palette.

The following example includes strong focus indicator styles with custom settings alongside the rest
of the custom theme API.

```scss
@use '@angular/material' as mat;

@include mat.strong-focus-indicators((
  border-style: dotted,
  border-width: 4px,
  border-radius: 2px,
));

$my-theme: mat.define-theme((
  color: (
    theme-type: light,
    primary: mat.$violet-palette,
  ),
));

html {
  @include mat.all-component-themes($my-theme);
  @include mat.strong-focus-indicators-theme(purple);
}
```

[WCAG]: https://www.w3.org/WAI/standards-guidelines/wcag/glance/

## Theming and style encapsulation

Angular Material assumes that, by default, all theme styles are loaded as global CSS. If you want
to use [Shadow DOM][shadow-dom] in your application, you must load the theme styles within each
shadow root that contains an Angular Material component. You can accomplish this by manually loading
the CSS in each shadow root, or by using [Constructable Stylesheets][constructable-css].

[shadow-dom]: https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM
[constructable-css]: https://developers.google.com/web/updates/2019/02/constructable-stylesheets

## User preference media queries

Angular Material does not apply styles based on user preference media queries, such as
`prefers-color-scheme` or `prefers-contrast`. Instead, Angular Material's Sass mixins give you the
flexibility to apply theme styles to based on the conditions that make the most sense for your
users. This may mean using media queries directly or reading a saved user preference.


# Theming Angular Material 2

## What is theming?

Angular Material's theming system lets you customize base, color, typography, and density styles for
components in your application. The theming system is based on Google's
[Material Design 2][material-design-theming] specification.

**This guide refers to Material 2, the previous version of Material. For the
latest Material 3 documentation, see the [theming guide][theming].**

**For information on how to update, see the section
on [how to migrate an app from Material 2 to Material 3](#how-to-migrate-an-app-from-material-2-to-material-3).**

This document describes the concepts and APIs for customizing colors. For typography customization,
see [Angular Material Typography][mat-typography]. For guidance on building components to be
customizable with this system, see [Theming your own components][theme-your-own].

[material-design-theming]: https://m2.material.io/design/material-theming/overview.html
[theming]: https://material.angular.io/guide/theming
[mat-typography]: https://material.angular.io/guide/typography
[theme-your-own]: https://material.angular.io/guide/theming-your-components

### Sass

Angular Material's theming APIs are built with [Sass](https://sass-lang.com). This document assumes
familiarity with CSS and Sass basics, including variables, functions, and mixins.

You can use Angular Material without Sass by using a pre-built theme, described in
[Using a pre-built theme](#using-a-pre-built-theme) below. However, using the library's Sass API
directly gives you the most control over the styles in your application.

## Palettes

A **palette** is a collection of colors representing a portion of color space. Each value in this
collection is called a **hue**. In Material Design, each hues in a palette has an identifier number.
These identifier numbers include 50, and then each 100 value between 100 and 900. The numbers order
hues within a palette from lightest to darkest.

Angular Material represents a palette as a [Sass map][sass-maps]. This map contains the
palette's hues and another nested map of contrast colors for each of the hues. The contrast colors
serve as text color when using a hue as a background color. The example below demonstrates the
structure of a palette. [See the Material Design color system for more background.][spec-colors]

```scss
$m2-indigo-palette: (
 50: #e8eaf6,
 100: #c5cae9,
 200: #9fa8da,
 300: #7986cb,
 // ... continues to 900
 contrast: (
   50: rgba(black, 0.87),
   100: rgba(black, 0.87),
   200: rgba(black, 0.87),
   300: white,
   // ... continues to 900
 )
);
```

[sass-maps]: https://sass-lang.com/documentation/values/maps
[spec-colors]: https://m2.material.io/design/color/the-color-system.html

### Create your own palette

You can create your own palette by defining a Sass map that matches the structure described in the
[Palettes](#palettes) section above. The map must define hues for 50 and each hundred between 100
and 900. The map must also define a `contrast` map with contrast colors for each hue.

You can use [the Material Design palette tool][palette-tool] to help choose the hues in your
palette.

[palette-tool]: https://m2.material.io/design/color/the-color-system.html#tools-for-picking-colors

### Predefined palettes

Angular Material offers predefined palettes based on the 2014 version of the Material Design
spec. See the [Material Design 2014 color palettes][2014-palettes] for a full list.

In addition to hues numbered from zero to 900, the 2014 Material Design palettes each include
distinct _accent_ hues numbered as `A100`, `A200`, `A400`, and `A700`. Angular Material does not
require these hues, but you can use these hues when defining a theme as described in
[Defining a theme](#defining-a-theme) below.

```scss
@use '@angular/material' as mat;

$my-palette: mat.$m2-indigo-palette;
```

[2014-palettes]: https://material.io/archive/guidelines/style/color.html#color-color-palette