feat(app-bar): implement Material 3 app bar specification (#62)

all.js

@@ -4,6 +4,7 @@
  * WARNING: This import is intended for prototyping and development builds only.
  * Import only the individual components used for production.
  */
+import './app/bar.js'
 import './buttons/button.js'
 import './buttons/button-group.js'
 import './carousel/carousel.js'
@@ -39,6 +40,7 @@ import './text/text-field.js'
 // LINT.ThenChange(:exports)
 // LINT.IfChange(exports)
 // go/keep-sorted start
+export * from './app/bar.js'
 export * from './buttons/button.js'
 export * from './buttons/button-group.js'
 export * from './carousel/carousel.js'

app/README.md

@@ -1,6 +1,14 @@
 # App Bar
 
-A Material 3 top app bar component with an integrated search field.
+A Material 3 top app bar component implementing the [Material Design 3 App Bar specification](https://m3.material.io/components/app-bars/overview).
+
+Top app bars display information and actions related to the current screen, supporting:
+
+- **Small App Bar**: Standard 64px height with left-aligned headline.
+- **Center-Aligned App Bar**: 64px height with centered headline.
+- **Medium Flexible App Bar**: Two-row flexible layout (112px–136px) that collapses to 64px on scroll.
+- **Large Flexible App Bar**: Prominent two-row flexible layout (120px–152px) that collapses to 64px on scroll.
+- **Search App Bar**: Top bar with integrated search input field and actions.
 
 ## Import
 
@@ -22,30 +30,105 @@ import 'material/icon/icon.js'
 
 ## Usage
 
+### 1. Small App Bar (Default)
+
+```html
+<md-app-bar headline="Page Title" subtitle="Optional subtitle">
+  <md-icon-button slot="navigation-icon">
+    <md-icon>menu</md-icon>
+  </md-icon-button>
+  <div slot="action-items">
+    <md-icon-button><md-icon>search</md-icon></md-icon-button>
+    <md-icon-button><md-icon>more_vert</md-icon></md-icon-button>
+  </div>
+</md-app-bar>
+```
+
+### 2. Center-Aligned App Bar
+
+```html
+<md-app-bar type="center-aligned" headline="Center Aligned">
+  <md-icon-button slot="navigation-icon">
+    <md-icon>arrow_back</md-icon>
+  </md-icon-button>
+  <div slot="action-items">
+    <md-icon-button><md-icon>attach_file</md-icon></md-icon-button>
+  </div>
+</md-app-bar>
+```
+
+### 3. Medium & Large Flexible App Bars
+
+Flexible app bars support prominent headings and can automatically collapse to 64px when scrolled:
+
 ```html
-<md-app-bar id="appBar" label="Search">
-  <md-icon-button slot="leading-icon">
+<md-app-bar
+  type="medium-flexible"
+  headline="Medium Title"
+  subtitle="Descriptive subtitle"
+  scroll-behavior="collapse"
+  scroll-target="window">
+  <md-icon-button slot="navigation-icon">
     <md-icon>menu</md-icon>
   </md-icon-button>
-  <div slot="trailing-icon">
-    <md-icon-button>
-      <md-icon>more_vert</md-icon>
-    </md-icon-button>
+  <div slot="action-items">
+    <md-icon-button><md-icon>filter_list</md-icon></md-icon-button>
   </div>
 </md-app-bar>
 ```
 
-### Properties and Attributes
+For Large Flexible, use `type="large-flexible"`.
+
+### 4. Search App Bar
+
+```html
+<md-app-bar type="search" placeholder="Search...">
+  <md-icon-button slot="navigation-icon">
+    <md-icon>menu</md-icon>
+  </md-icon-button>
+  <div slot="action-items">
+    <md-icon-button><md-icon>mic</md-icon></md-icon-button>
+  </div>
+</md-app-bar>
+```
+
+## Properties and Attributes
+
+| Property         | Attribute         | Type      | Default    | Description                                                                                     |
+| ---------------- | ----------------- | --------- | ---------- | ----------------------------------------------------------------------------------------------- |
+| `type`           | `type`            | `string`  | `'small'`  | Variant: `'small'`, `'center-aligned'`, `'medium-flexible'`, `'large-flexible'`, or `'search'`. |
+| `variant`        | `variant`         | `string`  | `''`       | Alias for `type`.                                                                               |
+| `headline`       | `headline`        | `string`  | `''`       | Main headline / title text.                                                                     |
+| `title`          | `title`           | `string`  | `''`       | Alias for `headline`.                                                                           |
+| `subtitle`       | `subtitle`        | `string`  | `''`       | Optional subtitle text.                                                                         |
+| `centerAligned`  | `center-aligned`  | `boolean` | `false`    | Shorthand boolean to center-align the headline.                                                 |
+| `scrolled`       | `scrolled`        | `boolean` | `false`    | Reflects whether container color / elevation is in the scrolled state.                          |
+| `collapsed`      | `collapsed`       | `boolean` | `false`    | Whether a medium or large flexible bar is collapsed down to 64px.                               |
+| `scrollBehavior` | `scroll-behavior` | `string`  | `'none'`   | Auto-scroll mode: `'none'`, `'scroll'` (elevates on scroll), or `'collapse'` (also collapses).  |
+| `scrollTarget`   | `scroll-target`   | `string`  | `'window'` | CSS selector of the scroll container element, or `'window'`.                                    |
+| `placeholder`    | `placeholder`     | `string`  | `'Search'` | Placeholder for the search variant input field.                                                 |
+| `value`          | `value`           | `string`  | `''`       | Current text in the search input field.                                                         |
+
+## Slots
 
-| Property      | Attribute     | Type     | Default    | Description                                           |
-| ------------- | ------------- | -------- | ---------- | ----------------------------------------------------- |
-| `label`       | `label`       | `string` | `'Search'` | The label for the inner search text field.            |
-| `placeholder` | `placeholder` | `string` | `'Search'` | The placeholder text for the inner search text field. |
-| `type`        | `type`        | `string` | `'search'` | Input type for the inner search text field.           |
+| Slot                       | Description                                                                                |
+| -------------------------- | ------------------------------------------------------------------------------------------ |
+| `navigation-icon`          | Leading navigation button (e.g. hamburger menu icon or back arrow). Alias: `leading-icon`. |
+| `headline`                 | Custom HTML or component for the headline. Alias: `title`.                                 |
+| `subtitle`                 | Custom HTML or component for the subtitle.                                                 |
+| `action-items`             | Trailing action icon buttons or user avatar. Alias: `trailing-icon`.                       |
+| `search-field`             | Custom search input field override for the `search` variant.                               |
+| `leading-icon-text-field`  | Icon inside the search input field.                                                        |
+| `trailing-icon-text-field` | Clear or trailing icon inside the search input field.                                      |
+| `(default)`                | Additional under-bar content (such as tabs or divider).                                    |
 
-### Slots
+## CSS Custom Properties
 
-- `leading-icon`: Element placed before the search bar (e.g. navigation drawer menu button).
-- `trailing-icon`: Element placed after the search bar (e.g. profile avatar, action buttons).
-- `leading-icon-text-field`: Leading icon inside the search text field.
-- `trailing-icon-text-field`: Trailing icon inside the search text field.
+| Custom Property                         | Default Value                            | Description                           |
+| --------------------------------------- | ---------------------------------------- | ------------------------------------- |
+| `--md-app-bar-container-color`          | `var(--md-sys-color-surface)`            | Background color when unscrolled.     |
+| `--md-app-bar-scrolled-container-color` | `var(--md-sys-color-surface-container)`  | Background color when scrolled.       |
+| `--md-app-bar-headline-color`           | `var(--md-sys-color-on-surface)`         | Text color of the headline.           |
+| `--md-app-bar-subtitle-color`           | `var(--md-sys-color-on-surface-variant)` | Text color of the subtitle.           |
+| `--md-app-bar-leading-icon-color`       | `var(--md-sys-color-on-surface)`         | Color of the leading navigation icon. |
+| `--md-app-bar-trailing-icon-color`      | `var(--md-sys-color-on-surface-variant)` | Color of the trailing action icons.   |