@rcarls/rc-app-bar 0.0.0-next-20260921045401

package/CHANGELOG.md

@@ -0,0 +1,164 @@
+# @rcarls/rc-app-bar
+
+## 0.0.0-next-20260921045401
+
+### Minor Changes
+
+- 079e025: Standardize component styling contracts for the breaking 0.7 release.
+
+  BREAKING CHANGE: Rename the Markdown editor's `--rme-*` properties to
+  `--rc-markdown-editor-*`, `--rc-app-bar-background` to `--rc-app-bar-bg`,
+  `--rc-textarea-radius` to `--rc-textarea-border-radius`, the transfer-list
+  `--rc-transfer-list-panel-*` properties to `--rc-transfer-list-listbox-*`,
+  `--rc-chip-group-webkit-scrollbar-display` to
+  `--rc-chip-group-scrollbar-display`, and `--rc-text` to `--rc-field-text`.
+  Compatibility aliases are intentionally not provided.
+
+  BREAKING CHANGE: Replace `--rc-select-chip-padding-inline` and
+  `--rc-combobox-chip-padding-inline` with explicit `*-padding-inline-start` and
+  `*-padding-inline-end` tokens. Generated removable chips now reserve the full
+  remove target and its edge offset, so their indicator cannot overlap label text.
+
+  Add canonical app-bar elevation, transfer-list listbox radius, and textarea
+  line-action tokens. Add logical `rc-chip` inline-padding properties so themes
+  can implement Material's icon-aware spacing without overriding authored child
+  styles. Make `rc-field` consume the shared semantic token layer,
+  and place the `rc-chip` and `rc-search-bar` light-DOM structural styles in the
+  `rc-base` cascade layer so normal consumer rules override them.
+
+  Prevent decorative, `aria-hidden` trailing list content from intercepting a
+  whole-row action target, and keep segmented-list item geometry from leaking
+  into nested standard lists.
+
+  Remove unused Material navigation-rail toggle tokens and obsolete list-item
+  theme tokens. Register the segmented-button private theme seam and enforce
+  token ownership, documentation, removed-name, selector-budget, and cascade
+  layer contracts through the component architecture audit.
+
+- 6e548d9: Several components handle `prefers-reduced-motion: reduce` in their own
+  shadow styles, outside a theme's reach, and refine it the same way the theme
+  layer already does: spatial motion (`translate`, `scale`, `transform`,
+  `inline-size`, `block-size`) goes fully to zero, while effects motion (color,
+  opacity) shortens instead of disappearing.
+
+  `rc-app-bar` zeros its host's hide/show `translate` but shortens the
+  expanded title's fade-in. `rc-disclosure` keeps its panel's expand/collapse
+  zeroed, but its summary/content backstop for a theme-added transition now
+  shortens instead of zeroing it outright. `rc-list-item`'s row and
+  state-layer transition only color and opacity, so the whole sweep shortens.
+  `rc-fab-menu`'s popup mixes `scale` with opacity/overlay/display under one
+  shared duration; reduced motion now zeros the scale and shortens the rest.
+  `rc-switch`'s thumb mixes background-color with inline-size/block-size/
+  transform the same way; the icons and track, which each transition only one
+  kind of property, needed only the zero-or-shorten call. `rc-fab`'s
+  scroll-reveal is opacity/visibility only with no time-based duration to
+  shorten in its scroll-linked path, so reduced motion narrows the scroll
+  window instead of collapsing it to zero; its JS-transition fallback path
+  shortens the same fade rather than removing it. `rc-progress`'s determinate
+  fill transition, previously unguarded under reduced motion, is now zeroed;
+  its indeterminate loop, a continuous sweep with no meaningful shortened
+  form, stays fully stopped rather than shortened.
+
+### Patch Changes
+
+- Updated dependencies [50d5610]
+- Updated dependencies [4341311]
+  - @rcarls/rc-common@0.0.0-next-20260921045401
+
+## 0.6.0
+
+### Minor Changes
+
+- b6f52a2: Change the default `slot="center"` layout: it now fills the flexible space
+  between leading and trailing, capped by the new
+  `--rc-app-bar-center-max-inline-size` before it centers within available
+  space instead of continuing to stretch, rather than always mirroring the
+  leading/trailing edges to stay exactly viewport-centered. Add the new
+  `center-symmetric` attribute to keep the previous behavior (exact
+  viewport-centering regardless of asymmetric leading/trailing widths).
+
+### Patch Changes
+
+- b6f52a2: Defer app-bar layout measurements to animation frames, group geometry reads
+  before style writes, and remeasure when symmetric centering changes live.
+- Updated dependencies [6683eb9]
+- Updated dependencies [ee7ba6c]
+- Updated dependencies [30eb232]
+  - @rcarls/rc-common@0.6.0
+
+## 0.5.0
+
+### Minor Changes
+
+- d440edc: Add `--rc-app-bar-title-start-padding`, applied only when the leading slot is
+  empty. Per the M3 Top App Bar spec, a headline with no navigation icon should
+  align with the start margin of the content below the bar, not the bar's own
+  edge padding (which is calibrated for the leading icon button's touch
+  target). Defaults to `0px` (no behavior change for existing consumers).
+
+### Patch Changes
+
+- Updated dependencies [4ae2ef0]
+- Updated dependencies [689340c]
+  - @rcarls/rc-common@0.5.0
+
+## 0.4.2
+
+### Patch Changes
+
+- @rcarls/rc-common@0.4.2
+
+## 0.4.1
+
+### Patch Changes
+
+- @rcarls/rc-common@0.4.1
+
+## 0.4.0
+
+### Patch Changes
+
+- 468e009: Document `variant`, `scroll-behavior`, `scroll-target`, and `scroll-threshold`
+  attributes, and note the `data-scrolled`/`data-collapsed`/`data-hidden` and
+  `:state()` environment-driven output convention in the class JSDoc.
+- Updated dependencies [e57277f]
+- Updated dependencies [ccca8e2]
+- Updated dependencies [037b1b3]
+  - @rcarls/rc-common@0.4.0
+
+## 0.3.2
+
+### Patch Changes
+
+- Updated dependencies [88b4086]
+  - @rcarls/rc-common@0.3.2
+
+## 0.3.1
+
+### Patch Changes
+
+- @rcarls/rc-common@0.3.1
+
+## 0.3.0
+
+### Changed
+
+- Update package metadata, README intro, and docs links.
+
+### Fixed
+
+- Defer layout measurements to the next animation frame to avoid measurement loops.
+
+### Dependencies
+
+- Sync internal dependencies to 0.3.0.
+
+## 0.2.0
+
+### Minor Changes
+
+- Add rc-app-bar with headless grid layout, dual-mode scrolled state, and pinned/collapse/hide scroll behavior. Align strict TypeScript configuration, add dialog feature detection, and prepare all packages for public npm release with provenance publishing.
+
+### Patch Changes
+
+- @rcarls/rc-common@0.2.0

package/README.md

@@ -0,0 +1,247 @@
+# `@rcarls/rc-app-bar`
+
+App bar modeled after the
+[Material 3 Top app bar](https://m3.material.io/components/top-app-bar/overview),
+with leading, title, center, trailing regions and optional scroll behavior.
+
+Docs: [https://richardcarls.github.io/rc-webcomponents/components/rc-app-bar](https://richardcarls.github.io/rc-webcomponents/components/rc-app-bar).
+
+Material 3 and Apple HIG inform the available structures and behaviors, but the
+default appearance remains deliberately UA-like: system colors, a thin
+scrolled divider, and no supplied action controls or decorative icons.
+
+## Installation
+
+```bash
+npm install @rcarls/rc-app-bar
+```
+
+```js
+import '@rcarls/rc-app-bar/define';
+```
+
+## Basic usage
+
+```html
+<header>
+  <rc-app-bar scroll-target="#content">
+    <button slot="leading" aria-label="Back">&larr;</button>
+    <span>Inbox</span>
+    <rc-toolbar slot="trailing" label="Actions">...</rc-toolbar>
+  </rc-app-bar>
+</header>
+<div id="content" class="scroll-area">...</div>
+```
+
+The default slot is the single title region. It may contain a title, subtitle,
+or any other consumer markup. The title node remains connected and is never
+duplicated while the bar changes layout.
+
+## Expanded and scroll behaviors
+
+`variant="expanded"` places the title in a flexible second row. Its height
+comes from the title content rather than a Material-specific fixed size.
+
+```html
+<rc-app-bar variant="expanded" scroll-behavior="collapse" scroll-target="#content">
+  <button slot="leading" aria-label="Back">&larr;</button>
+  <div>
+    <strong>Slow-Roasted Tomato Pasta</strong>
+    <small>Summer recipes</small>
+  </div>
+  <button slot="trailing" aria-label="Edit">Edit</button>
+</rc-app-bar>
+```
+
+Scroll behaviors are exclusive:
+
+- `pinned` keeps the current structure visible and only exposes scrolled state.
+- `collapse` continuously shrinks an expanded title row over its measured
+  height, then keeps the compact row visible.
+- `hide` hides the complete bar while scrolling down past `scroll-threshold`
+  and reveals it when scrolling up or returning near the top.
+
+The component never consumes, stops, or rewrites the document's scroll.
+
+## Center-slot composition
+
+The optional `center` slot, useful for desktop controls or an
+[`rc-search-bar`](../rc-search-bar/), fills the flexible space between leading
+and trailing by default:
+
+```html
+<rc-app-bar style="--rc-app-bar-center-max-inline-size: 32rem;">
+  <button slot="leading">Back</button>
+  <span>Recipes</span>
+  <rc-search-bar slot="center" placeholder="Search recipes">
+    <input type="search" aria-label="Search recipes" />
+  </rc-search-bar>
+  <button slot="trailing" aria-label="Account">Account</button>
+</rc-app-bar>
+```
+
+Uncapped, it stretches edge-to-edge like any other content in that space. Set
+`--rc-app-bar-center-max-inline-size` and it centers within the available
+space once it hits that width instead of continuing to stretch (centered
+between wherever leading ends and trailing begins, not on the bar's own
+viewport midpoint).
+
+For a control that must sit at the bar's exact geometric midpoint regardless
+of asymmetric leading/trailing widths, add `center-symmetric`:
+
+```html
+<rc-app-bar center-symmetric>
+  <button slot="leading">Long leading label</button>
+  <span>Recipes</span>
+  <rc-search-bar slot="center">...</rc-search-bar>
+  <button slot="trailing" aria-label="Account">Account</button>
+</rc-app-bar>
+```
+
+This mirrors the leading/trailing edge widths so the center slot stays
+viewport-centered even when the two sides differ, at the cost of extra reserved
+space on whichever side is narrower.
+
+Title and center content may coexist. The title is constrained before it can
+overlap the centered content. Without center content, the title uses all space
+between leading and trailing controls; consumers may apply
+`rc-app-bar::part(title) { text-align: center; }`.
+
+## Controlled state
+
+`scrolled` follows the library's controlled/uncontrolled convention:
+
+- Set `scrollTarget` or `scroll-target` for uncontrolled observation.
+- Assign `scrolled` to control the endpoint silently.
+- Assign `undefined` to release control back to observation.
+
+In controlled collapse mode, `true` snaps to compact and `false` restores the
+expanded row. Controlled hide mode remains visible because a boolean value
+cannot express scroll direction.
+
+State output is available as `data-scrolled`, `data-collapsed`, and
+`data-hidden`, with equivalent `:state(scrolled)`, `:state(collapsed)`, and
+`:state(hidden)` custom states.
+
+## View Transitions
+
+Document View Transitions are consumer-owned progressive enhancement. Assign a
+unique `view-transition-name` to the light-DOM title element, not
+`::part(title)` or the shadow-owned slot wrapper:
+
+```html
+<rc-app-bar id="recipe-bar" variant="expanded" scroll-behavior="collapse">
+  <h1 class="recipe-title">Slow-Roasted Tomato Pasta</h1>
+</rc-app-bar>
+```
+
+```css
+.recipe-title {
+  view-transition-name: recipe-app-bar-title;
+}
+
+::view-transition-old(recipe-app-bar-title) {
+  animation: 180ms ease-out both title-out;
+}
+
+::view-transition-new(recipe-app-bar-title) {
+  animation: 180ms 120ms ease-in both title-in;
+}
+
+@keyframes title-out {
+  to {
+    opacity: 0;
+    translate: 0 -1rem;
+  }
+}
+
+@keyframes title-in {
+  from {
+    opacity: 0;
+  }
+}
+```
+
+```js
+const bar = document.querySelector('#recipe-bar');
+const reduceMotion = matchMedia('(prefers-reduced-motion: reduce)');
+
+async function setCollapsed(collapsed) {
+  const update = async () => {
+    bar.scrolled = collapsed;
+    await bar.updateComplete;
+  };
+
+  if (!document.startViewTransition || reduceMotion.matches) {
+    await update();
+    return;
+  }
+
+  document.startViewTransition(update);
+}
+```
+
+The app bar never starts a document transition itself because the API is
+global and may conflict with navigation or unrelated components. Unsupported
+browsers receive the immediate endpoint change. Give concurrently rendered
+titles unique transition names.
+
+## Styling
+
+The component supplies no controls or action icons. The default scrolled
+separator is the `scroll-shadow` part, despite being rendered as a system-color
+border by default:
+
+```css
+rc-app-bar::part(scroll-shadow) {
+  border-block-end: 0;
+  box-shadow: 0 1px 4px rgb(0 0 0 / 0.2);
+}
+
+rc-app-bar.glass::part(root) {
+  background: color-mix(in srgb, Canvas 70%, transparent);
+  backdrop-filter: blur(18px);
+}
+```
+
+### CSS custom properties
+
+| Property                                | Default              | Description                                                                                                                                        |
+| --------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--rc-app-bar-bg`                       | `Canvas`             | Bar background                                                                                                                                     |
+| `--rc-app-bar-color`                    | `CanvasText`         | Bar text color                                                                                                                                     |
+| `--rc-app-bar-shadow`                   | `none`               | Bar box shadow                                                                                                                                     |
+| `--rc-app-bar-compact-min-height`       | `3rem`               | Compact row minimum height                                                                                                                         |
+| `--rc-app-bar-expanded-padding-block`   | `0.75em`             | Expanded title block padding                                                                                                                       |
+| `--rc-app-bar-padding-inline`           | `0.75em`             | Horizontal padding                                                                                                                                 |
+| `--rc-app-bar-gap`                      | `0.5em`              | Gap between regions                                                                                                                                |
+| `--rc-app-bar-center-max-inline-size`   | `100%`               | Max width of `slot="center"` content before it centers within the available space instead of filling it. No effect when `center-symmetric` is set. |
+| `--rc-app-bar-title-start-padding`      | `0px`                | Extra title inline-start padding when the leading slot is empty                                                                                    |
+| `--rc-app-bar-transition-duration`      | `200ms`              | Endpoint and hide transition duration                                                                                                              |
+| `--rc-app-bar-scroll-divider`           | `1px solid GrayText` | Scrolled separator border                                                                                                                          |
+| `--rc-app-bar-collapse-progress`        | `0`                  | Read-only collapse animation progress from 0 through 1                                                                                             |
+| `--rc-app-bar-title-font-size`          | unset                | Optional compact-row title font size; inherits when unset                                                                                          |
+| `--rc-app-bar-expanded-title-font-size` | unset                | Optional expanded-row title font size; inherits when unset                                                                                         |
+
+### CSS parts
+
+`root`, `leading`, `title`, `center`, `trailing`, `scroll-shadow`
+
+## Breaking migration
+
+- Replace `variant="small"` with `variant="compact"`.
+- Replace `variant="medium"` with `variant="expanded"`.
+- Remove `slot="expanded-title"` and keep one title in the default slot.
+- Replace old fixed height/title-font tokens and the `title-row`/`expanded`
+  parts with the structural API documented above.
+
+## Accessibility
+
+- The host has no implicit landmark role. Wrap a page-level instance in
+  `<header>` when appropriate.
+- Consumer-provided controls retain their native semantics and keyboard
+  behavior.
+- The single title remains connected and exposed to assistive technology in
+  every visual state.
+- Movement and fades are disabled under `prefers-reduced-motion: reduce`.
+- The default divider uses `GrayText` and remains visible in forced colors.