Skip to content

docs(material/toolbar): minor doc fixes #29227

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
andrewseguin merged 1 commit into from
Jun 17, 2024
Merged

docs(material/toolbar): minor doc fixes #29227

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions src/components-examples/material/toolbar/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
export {ToolbarBasicExample} from './toolbar-basic/toolbar-basic-example';
export {ToolbarMultirowExample} from './toolbar-multirow/toolbar-multirow-example';
export {ToolbarSimpleExample} from './toolbar-simple/toolbar-simple-example';
export {ToolbarOverviewExample} from './toolbar-overview/toolbar-overview-example';
export {ToolbarHarnessExample} from './toolbar-harness/toolbar-harness-example';
2 changes: 1 addition & 1 deletion src/components-examples/material/toolbar/toolbar-multirow/toolbar-multirow-example.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<mat-toolbar color="primary">
<mat-toolbar>
<!-- #docregion toolbar-row -->
<mat-toolbar-row>
<span>Custom Toolbar</span>
Expand Down
75 changes: 13 additions & 62 deletions src/components-examples/material/toolbar/toolbar-overview/toolbar-overview-example.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,62 +1,13 @@
<p>
<!-- #docregion toolbar-simple -->
<mat-toolbar>
<span>My Application</span>
</mat-toolbar>
<!-- #enddocregion toolbar-simple -->
</p>

<p>
<mat-toolbar>
<button mat-icon-button class="example-icon" aria-label="Example icon-button with menu icon">
<mat-icon>menu</mat-icon>
</button>
<span>My App</span>
<span class="example-spacer"></span>
<button mat-icon-button class="example-icon favorite-icon" aria-label="Example icon-button with heart icon">
<mat-icon>favorite</mat-icon>
</button>
<button mat-icon-button class="example-icon" aria-label="Example icon-button with share icon">
<mat-icon>share</mat-icon>
</button>
</mat-toolbar>
</p>

<p>
<mat-toolbar color="primary">
<button mat-icon-button class="example-icon" aria-label="Example icon-button with menu icon">
<mat-icon>menu</mat-icon>
</button>
<span>My App</span>
<span class="example-spacer"></span>
<button mat-icon-button class="example-icon favorite-icon" aria-label="Example icon-button with heart icon">
<mat-icon>favorite</mat-icon>
</button>
<button mat-icon-button class="example-icon" aria-label="Example icon-button with share icon">
<mat-icon>share</mat-icon>
</button>
</mat-toolbar>
</p>

<p>
<mat-toolbar color="primary">
<mat-toolbar-row>
<span>My App</span>
<span class="example-spacer"></span>
<button mat-icon-button class="example-icon" aria-label="Example icon-button with menu icon">
<mat-icon>menu</mat-icon>
</button>
</mat-toolbar-row>

<mat-toolbar-row>
<span>Second Line</span>
<span class="example-spacer"></span>
<button mat-icon-button class="example-icon favorite-icon" aria-label="Example icon-button with heart icon">
<mat-icon>favorite</mat-icon>
</button>
<button mat-icon-button class="example-icon" aria-label="Example icon-button with share icon">
<mat-icon>share</mat-icon>
</button>
</mat-toolbar-row>
</mat-toolbar>
</p>
<mat-toolbar>
<button mat-icon-button class="example-icon" aria-label="Example icon-button with menu icon">
<mat-icon>menu</mat-icon>
</button>
<span>My App</span>
<span class="example-spacer"></span>
<button mat-icon-button class="example-icon favorite-icon" aria-label="Example icon-button with heart icon">
<mat-icon>favorite</mat-icon>
</button>
<button mat-icon-button class="example-icon" aria-label="Example icon-button with share icon">
<mat-icon>share</mat-icon>
</button>
</mat-toolbar>
3 changes: 3 additions & 0 deletions src/components-examples/material/toolbar/toolbar-simple/toolbar-simple-example.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
<mat-toolbar>
<span>My Application</span>
</mat-toolbar>
13 changes: 13 additions & 0 deletions src/components-examples/material/toolbar/toolbar-simple/toolbar-simple-example.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
import {Component} from '@angular/core';
import {MatToolbarModule} from '@angular/material/toolbar';

/**
* @title Toolbar with just text
*/
@Component({
selector: 'toolbar-simple-example',
templateUrl: 'toolbar-simple-example.html',
standalone: true,
imports: [MatToolbarModule],
})
export class ToolbarSimpleExample {}
4 changes: 4 additions & 0 deletions src/dev-app/toolbar/toolbar-demo.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
<div class="demo-toolbar">
<p>
<toolbar-simple-example></toolbar-simple-example>
</p>

<p>
<toolbar-overview-example></toolbar-overview-example>
</p>
Expand Down
2 changes: 2 additions & 0 deletions src/dev-app/toolbar/toolbar-demo.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import {
ToolbarMultirowExample,
ToolbarOverviewExample,
} from '@angular/components-examples/material/toolbar';
import {ToolbarSimpleExample} from '@angular/components-examples/material/toolbar/toolbar-simple/toolbar-simple-example';
import {ChangeDetectionStrategy, Component} from '@angular/core';
import {MatButtonModule} from '@angular/material/button';
import {MatIconModule} from '@angular/material/icon';
Expand All @@ -29,6 +30,7 @@ import {MatToolbarModule} from '@angular/material/toolbar';
ToolbarBasicExample,
ToolbarMultirowExample,
ToolbarOverviewExample,
ToolbarSimpleExample,
ToolbarHarnessExample,
],
changeDetection: ChangeDetectionStrategy.OnPush,
Expand Down
18 changes: 5 additions & 13 deletions src/material/toolbar/toolbar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,24 +4,21 @@

### Single row

In the most situations, a toolbar will be placed at the top of your application and will only
In the simplest case, a toolbar may be placed at the top of your application and
have a single row that includes the title of your application.

<!-- example({"example":"toolbar-overview",
"file":"toolbar-overview-example.html",
"region":"toolbar-simple"}) -->
<!-- example(toolbar-simple) -->

### Multiple rows

The Material Design specifications describe that toolbars can also have multiple rows. Creating
toolbars with multiple rows in Angular Material can be done by placing `<mat-toolbar-row>` elements
inside of a `<mat-toolbar>`.
The Material Design spec used to describe toolbars with multiple rows. This can
be done by placing `<mat-toolbar-row>` elements inside a `<mat-toolbar>`.

<!-- example({"example":"toolbar-multirow",
"file":"toolbar-multirow-example.html",
"region":"toolbar-row"}) -->

**Note**: Placing content outside of a `<mat-toolbar-row>` when multiple rows are specified is not
**Note**: Placing content outside a `<mat-toolbar-row>` when multiple rows are specified is not
supported.

### Positioning toolbar content
Expand All @@ -39,11 +36,6 @@ easily accomplished with `display: flex`:
"file":"toolbar-multirow-example.css",
"region":"toolbar-position-content-style"}) -->

### Theming
Copy link
Contributor

@amysorto amysorto Jun 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't this doc comment be updated as well since that generates what is on the API tab? https://github.com/angular/components/blob/main/src/material/toolbar/toolbar.ts#L49.

Maybe something like: /** Palette color of the toolbar. Not recommended in M3, for more information see https://material.angular.io/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants. */

Copy link
Contributor Author

@andrewseguin andrewseguin Jun 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes definitely - I'm thinking we'll have one single PR that goes around to update all color inputs with some consistent message

Copy link

@blogcraft blogcraft Jun 17, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If color is not supported in MD3 or not recommended, then why keep using it in the angular material page? Its misguiding. (Also, I personally am against toolbar not having a pallete color, I find it hostile to how a business wants to present its brand.)

Copy link

@blogcraft blogcraft Jun 17, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in #28805 (comment) I made a comment of how to adapt theme colors to the toolbar.

Option 1:

@mixin app-theme($theme, $type: "light") {
  @if $type == "light" {
    @include mat.all-component-themes($theme);
    .mat-toolbar {
      --mat-toolbar-container-text-color: #{mat.get-theme-color(
          $theme,
          primary,
          100
        )};
      --mat-toolbar-container-background-color: #{mat.get-theme-color(
          $theme,
          primary
        )};
      --mdc-icon-button-icon-color: #{mat.get-theme-color(
          $theme,
          primary,
          100
        )};
    }
 } @else {
    @include mat.all-component-colors($theme);
    .mat-toolbar {
      --mat-toolbar-container-text-color: #{mat.get-theme-color(
          $theme,
          primary
        )};
      --mat-toolbar-container-background-color: #{mat.get-theme-color(
          $theme,
          primary
        )};
      --mdc-icon-button-icon-color: #{mat.get-theme-color($theme, primary, 20)};
    }
  }
}

html {
  // .app-light-theme (default)
  @include app-theme($app-light-theme, "light");

  .app-dark-theme {
    @include app-theme($app-dark-theme, "dark");
  }

  @media (prefers-color-scheme: light) {
    .app-auto-theme {
      @include app-theme($app-light-theme, "light");
    }
  }

  @media (prefers-color-scheme: dark) {
    .app-auto-theme {
      @include app-theme($app-dark-theme, "dark");
    }
  }
}

Option 2:

@mixin app-theme($theme, $type: "light") {
  @if $type == "light" {
    @include mat.all-component-themes($theme);
    .mat-toolbar {
      background: mat.get-theme-color($theme, primary);
      .mat-mdc-icon-button {
        color: mat.get-theme-color($theme, primary, 100);
      }
    }
 } @else {
    @include mat.all-component-colors($theme);
    .mat-toolbar {
      background: mat.get-theme-color($theme, primary);
      .mat-mdc-icon-button {
        color: mat.get-theme-color($theme, primary, 20);
      }
    }
  }
}

html {
  // .app-light-theme (default)
  @include app-theme($app-light-theme, "light");

  .app-dark-theme {
    @include app-theme($app-dark-theme, "dark");
  }

  @media (prefers-color-scheme: light) {
    .app-auto-theme {
      @include app-theme($app-light-theme, "light");
    }
  }

  @media (prefers-color-scheme: dark) {
    .app-auto-theme {
      @include app-theme($app-dark-theme, "dark");
    }
  }
}

Any Thoughts?

Copy link
Contributor Author

@andrewseguin andrewseguin Jun 17, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I empathize with wanting color in the toolbar - we also think it looks better for branding. However, we're beholden to the spec and designers here, and our goal is to match their direction

Copy link

@blogcraft blogcraft Jun 17, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the reply. I understand, is the Angular Material page be updated to adhere to the specs? As it is it, I believe it contributes to the confusion.

The color of a `<mat-toolbar>` can be changed by using the `color` property. By default, toolbars
use a neutral background color based on the current theme (light or dark). This can be changed to
`'primary'`, `'accent'`, or `'warn'`.

### Accessibility
By default, the toolbar assumes that it will be used in a purely decorative fashion and thus sets
no roles, ARIA attributes, or keyboard shortcuts. This is equivalent to having a sequence of `<div>`
Expand Down