@zeyos/zx 4.3.0 → 4.4.0

package/src/components/app-sidebar/app-sidebar.css

@@ -1,4 +1,40 @@
+/*
+ * AppSidebar — the surface an application is judged by before it is read.
+ *
+ * Everything here hangs off one spacing scale declared on the root. Item height, icon gutter,
+ * row gap, group gap and indentation are derived from it rather than picked per rule, which is
+ * what makes a density switch a real change of rhythm instead of a smaller font.
+ *
+ * Two deliberate choices worth stating:
+ *
+ * - **Labels wrap, they never truncate.** German runs 20-35% longer than English and a nav is
+ *   where that shows first: "Belege & Rechnungen" is two lines in a 16.5rem sidebar. An ellipsis
+ *   there hides the word that distinguishes one destination from another, so the row grows
+ *   instead and the fixed icon column keeps the second line aligned under the first.
+ * - **The active state never rests on colour alone.** It is a filled pill, a marker docked to the
+ *   sidebar's outer edge, and a heavier label — three signals, one of which survives greyscale,
+ *   forced colours and a reduced-transparency page.
+ */
+
 .zx-app-sidebar {
+  /* The scale. `--zx-control-height` and `--zx-space-1..4` are density-aware, so compact
+     tightens the item, the gaps and the padding together while `--zx-space-5/6` hold the icon
+     column and the indent steady — a narrower rhythm, not a smaller one. */
+  --zx-app-sidebar-gutter: var(--zx-space-2);
+  --zx-app-sidebar-icon: var(--zx-space-6);
+  --zx-app-sidebar-item-gap: var(--zx-space-3);
+  --zx-app-sidebar-item-height: calc(var(--zx-control-height) + var(--zx-space-2));
+  --zx-app-sidebar-pad-x: var(--zx-space-3);
+  --zx-app-sidebar-row-gap: var(--zx-space-1);
+  --zx-app-sidebar-group-gap: var(--zx-space-4);
+  --zx-app-sidebar-indent: var(--zx-space-5);
+  --zx-app-sidebar-marker: 3px;
+  --zx-app-sidebar-radius: var(--zx-radius-xl);
+  /* One overlay expression for hover and press. Mixing the *text* colour into the surface moves
+     the fill away from the page in whichever direction the theme runs, so a single declaration
+     is correct in light and in dark instead of needing a per-theme override. */
+  --zx-app-sidebar-hover: color-mix(in srgb, var(--zx-color-text) 7%, transparent);
+  --zx-app-sidebar-press: color-mix(in srgb, var(--zx-color-text) 14%, transparent);
   display: flex;
   min-block-size: 0;
   border: 1px solid var(--zx-color-glass-border);
@@ -7,6 +43,11 @@
   color: var(--zx-color-text);
 }
 
+[data-zx-density="compact"] .zx-app-sidebar,
+.zx-app-sidebar[data-zx-density="compact"] {
+  --zx-app-sidebar-group-gap: var(--zx-space-3);
+}
+
 .zx-app-sidebar[data-orientation="horizontal"] {
   inline-size: 100%;
 }
@@ -29,57 +70,406 @@
 .zx-app-sidebar__expanded[hidden],
 .zx-app-sidebar__rail[hidden] { display: none; }
 
+/* The header carries no rule. It is a brand slot above a nav, not a boundary between two kinds
+   of content, and a hairline there reads as leftover scaffolding. The footer keeps its rule:
+   an identity control below navigation is a different region and the line is doing work. */
 .zx-app-sidebar__header {
   display: grid;
   grid-template-columns: minmax(0, 1fr) auto;
   align-items: center;
   gap: var(--zx-space-2);
-  min-block-size: calc(var(--zx-control-height) + var(--zx-space-3));
-  border-block-end: 1px solid var(--zx-color-border);
-  padding: var(--zx-space-2);
+  min-block-size: calc(var(--zx-control-height) + var(--zx-space-4));
+  padding: var(--zx-space-2) var(--zx-space-3);
 }
 
 .zx-app-sidebar__header-content { min-inline-size: 0; }
-.zx-app-sidebar__nav { min-block-size: 0; overflow: auto; padding: var(--zx-space-2); }
+
+/* The block padding is not decoration: the focus ring is a 3px outer glow, and a nav that padded
+   its scroll box by less would clip the ring off the first and last row. */
+.zx-app-sidebar__nav {
+  min-block-size: 0;
+  overflow: auto;
+  padding: var(--zx-space-2) var(--zx-app-sidebar-gutter) var(--zx-space-3);
+}
+
 .zx-app-sidebar__list,
-.zx-app-sidebar__sublist { display: grid; gap: var(--zx-space-1); margin: 0; padding: 0; list-style: none; }
-.zx-app-sidebar__sublist { margin-block-start: var(--zx-space-1); }
+.zx-app-sidebar__sublist {
+  display: grid;
+  gap: var(--zx-app-sidebar-row-gap);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* A sidebar whose items carry no icons should not pay for an empty gutter; one that has even a
+   single icon keeps the column on every row so the labels stay in one line down the list. */
+.zx-app-sidebar__list:not(:has(.zx-app-sidebar__item-icon)) {
+  --zx-app-sidebar-icon: 0px;
+  --zx-app-sidebar-item-gap: 0px;
+}
+
+.zx-app-sidebar__sublist { position: relative; margin-block-start: var(--zx-app-sidebar-row-gap); }
 .zx-app-sidebar__sublist[hidden] { display: none; }
 
+/* The one rule in the component that carries meaning: a guide dropped from the centre of the
+   parent's icon that scopes the open branch to the row that opened it. */
+.zx-app-sidebar__sublist::before {
+  content: "";
+  position: absolute;
+  inset-block: var(--zx-space-1);
+  inset-inline-start: calc(var(--zx-app-sidebar-pad-x) + var(--zx-app-sidebar-icon) / 2);
+  inline-size: 1px;
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-border);
+}
+
+/* Groups are separated by space, not by rules: a top-level branch opens a group, and the row
+   after that group closes it. The first row never gets the gap. */
+.zx-app-sidebar__list > .zx-app-sidebar__row:has(> .zx-app-sidebar__sublist),
+.zx-app-sidebar__list > .zx-app-sidebar__row:has(> .zx-app-sidebar__sublist) + .zx-app-sidebar__row {
+  margin-block-start: var(--zx-app-sidebar-group-gap);
+}
+
+.zx-app-sidebar__list > .zx-app-sidebar__row:first-child { margin-block-start: 0; }
+
 .zx-app-sidebar__item {
+  position: relative;
   display: grid;
-  grid-template-columns: auto minmax(0, 1fr) auto auto;
+  /* The icon track is composed here and not in a variable on the root: a custom property
+     substitutes its `var()`s where it is declared, so a track precomputed on the component would
+     ignore the list-level override below and keep an empty 36px gutter on an icon-less sidebar. */
+  grid-template-columns: calc(var(--zx-app-sidebar-icon) + var(--zx-app-sidebar-item-gap)) minmax(0, 1fr) auto auto;
   align-items: center;
-  gap: var(--zx-space-2);
+  column-gap: 0;
   inline-size: 100%;
-  min-block-size: var(--zx-control-height);
-  border-color: transparent;
-  border-radius: var(--zx-radius-md);
+  min-block-size: var(--zx-app-sidebar-item-height);
+  border: 0;
+  border-radius: var(--zx-app-sidebar-radius);
   background: transparent;
-  padding-inline: var(--zx-space-3);
-  color: inherit;
+  padding-block: var(--zx-space-1);
+  padding-inline: var(--zx-app-sidebar-pad-x);
+  color: var(--zx-color-text);
+  font-size: var(--zx-text-md);
+  font-weight: 500;
+  line-height: 1.35;
   text-align: start;
   text-decoration: none;
 }
 
-.zx-app-sidebar__row[data-level="2"] > .zx-app-sidebar__item { padding-inline-start: calc(var(--zx-space-3) + var(--zx-space-5)); }
-.zx-app-sidebar__row[data-level="3"] > .zx-app-sidebar__item { padding-inline-start: calc(var(--zx-space-3) + var(--zx-space-7)); }
-.zx-app-sidebar__item:hover,
-.zx-app-sidebar__item:focus-visible,
-.zx-app-sidebar__item[data-active-descendant="true"],
-.zx-app-sidebar__item[aria-current="page"] { background: var(--zx-color-bg-hover); color: var(--zx-color-accent); }
-.zx-app-sidebar__item[aria-disabled="true"] { color: var(--zx-color-text-muted); cursor: not-allowed; opacity: .65; }
-.zx-app-sidebar__item-icon,
-.zx-app-sidebar__item-disclosure { display: inline-flex; }
-.zx-app-sidebar__item-badge { color: var(--zx-color-text-muted); font-size: var(--zx-text-xs); }
+/* A nav is a touch target before it is a dense list. Compact tightens the drawn row, and a
+   coarse pointer puts the hit area back to 40px whatever the density says. */
+@media (pointer: coarse) {
+  .zx-app-sidebar__item { min-block-size: 40px; }
+}
+
+.zx-app-sidebar__row[data-level="2"] > .zx-app-sidebar__item { padding-inline-start: calc(var(--zx-app-sidebar-pad-x) + var(--zx-app-sidebar-indent)); }
+.zx-app-sidebar__row[data-level="3"] > .zx-app-sidebar__item { padding-inline-start: calc(var(--zx-app-sidebar-pad-x) + 2 * var(--zx-app-sidebar-indent)); }
+
+/* The active marker. It is anchored to the control and not to the row, because a row is the
+   branch *and everything open under it* — a marker measured against that would grow into a
+   bracket down the whole group. It sits in the nav's own gutter, docked to the sidebar's outer
+   edge, so every marker lines up whatever the nesting depth, and it is the signal that survives
+   when colour does not. A collapsed branch that merely *contains* the active route gets a short
+   stub of the same marker: the same vocabulary, a quieter sentence. */
+.zx-app-sidebar__item::before {
+  content: "";
+  position: absolute;
+  inset-block: 50%;
+  inset-inline-start: calc(-1 * var(--zx-app-sidebar-gutter));
+  inline-size: var(--zx-app-sidebar-marker);
+  border-start-end-radius: var(--zx-radius-full);
+  border-end-end-radius: var(--zx-radius-full);
+  background: var(--zx-color-accent);
+  opacity: 0;
+}
+
+.zx-app-sidebar[data-side="right"] .zx-app-sidebar__item::before {
+  inset-inline: auto calc(-1 * var(--zx-app-sidebar-gutter));
+  border-radius: 0;
+  border-start-start-radius: var(--zx-radius-full);
+  border-end-start-radius: var(--zx-radius-full);
+}
+
+.zx-app-sidebar__item[aria-current="page"]::before {
+  inset-block: 25%;
+  opacity: 1;
+}
+
+.zx-app-sidebar__item[data-active-descendant="true"][aria-expanded="false"]::before {
+  inset-block: 38%;
+  opacity: .55;
+}
+
+.zx-app-sidebar__item-icon {
+  grid-column: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: var(--zx-app-sidebar-icon);
+  color: var(--zx-color-text-muted);
+}
+
+/* No nowrap and no ellipsis: the row grows instead. `hyphens` is what makes that bearable for a
+   German compound — where the document declares a language the browser breaks "Rechnungsausgang"
+   at a syllable, and `overflow-wrap` is only the last resort behind it for a word that fits
+   nowhere at all. */
+.zx-app-sidebar__item-label {
+  grid-column: 2;
+  min-inline-size: 0;
+  hyphens: auto;
+  overflow-wrap: break-word;
+}
+
+.zx-app-sidebar__item-badge {
+  grid-column: 3;
+  margin-inline-start: var(--zx-space-2);
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-xs);
+  font-variant-numeric: tabular-nums;
+  line-height: 1;
+}
+
+.zx-app-sidebar__item-disclosure {
+  grid-column: 4;
+  display: inline-flex;
+  margin-inline-start: var(--zx-space-1);
+  color: var(--zx-color-text-muted);
+}
+
+.zx-app-sidebar__item:hover { background: var(--zx-app-sidebar-hover); }
+.zx-app-sidebar__item:hover .zx-app-sidebar__item-icon,
+.zx-app-sidebar__item:hover .zx-app-sidebar__item-disclosure { color: var(--zx-color-text); }
+.zx-app-sidebar__item:active { background: var(--zx-app-sidebar-press); }
+
+/* A branch that is closed over the active route keeps the accent in the label and the marker
+   stub outside it; a branch that is open says so with its chevron and needs neither. */
+.zx-app-sidebar__item[data-active-descendant="true"][aria-expanded="false"] {
+  color: var(--zx-color-accent);
+  font-weight: 600;
+}
+
+.zx-app-sidebar__item[aria-current="page"] {
+  background: var(--zx-color-accent);
+  color: var(--zx-color-on-accent);
+  font-weight: 600;
+}
+
+/* Hover and press on the pill move the fill toward the text colour, which raises the contrast
+   with `--zx-color-on-accent` in both polarities instead of dropping it in one of them. */
+.zx-app-sidebar__item[aria-current="page"]:hover {
+  background: color-mix(in srgb, var(--zx-color-text) 8%, var(--zx-color-accent));
+}
+
+.zx-app-sidebar__item[aria-current="page"]:active {
+  background: color-mix(in srgb, var(--zx-color-text) 16%, var(--zx-color-accent));
+}
+
+/* Focus is a ring, never a fill: a keyboard user arrowing past the active route must still be
+   able to tell which row is current. Ordinary rows take the shared `--zx-focus-ring` from
+   `base.css` untouched; only the filled pill needs help, because an accent glow around an accent
+   fill is a ring nobody can see. The inner line is drawn in the pill's own text colour, which the
+   preset contract already guarantees against that fill. */
+.zx-app-sidebar__item[aria-current="page"]:focus-visible {
+  box-shadow: inset 0 0 0 2px var(--zx-color-on-accent), var(--zx-focus-ring);
+}
+
+.zx-app-sidebar__item[aria-current="page"] .zx-app-sidebar__item-icon,
+.zx-app-sidebar__item[aria-current="page"] .zx-app-sidebar__item-badge,
+.zx-app-sidebar__item[aria-current="page"] .zx-app-sidebar__item-disclosure {
+  color: inherit;
+}
+
+/* Unavailable, and still readable. A blanket `opacity` on the row took the label under 3:1, which
+   is the one thing a destination a user cannot reach still has to do: say where it would go. The
+   icon carries the dimming instead, and the label keeps the muted text role. */
+.zx-app-sidebar__item[aria-disabled="true"] {
+  color: var(--zx-color-text-muted);
+  cursor: not-allowed;
+}
+
+.zx-app-sidebar__item[aria-disabled="true"] .zx-app-sidebar__item-icon { opacity: .55; }
+
+.zx-app-sidebar__item[aria-disabled="true"]:hover,
+.zx-app-sidebar__item[aria-disabled="true"]:active { background: transparent; }
 
 .zx-app-sidebar__footer {
   border-block-start: 1px solid var(--zx-color-border);
-  padding: var(--zx-space-2);
+  padding: var(--zx-space-2) var(--zx-space-3);
 }
 .zx-app-sidebar__footer[hidden] { display: none; }
+
 .zx-app-sidebar__rail-header { display: grid; gap: var(--zx-space-1); }
 
+/*
+ * The minimized rail. Only the presentation changes; the same vocabulary applies — filled pill,
+ * docked marker, badge that survives the loss of the label.
+ */
+.zx-app-sidebar__rail .zx-app-rail__item[aria-current="page"] {
+  background: var(--zx-color-accent);
+  color: var(--zx-color-on-accent);
+}
+
+.zx-app-sidebar__rail .zx-app-rail__item[aria-current="page"]:hover {
+  background: color-mix(in srgb, var(--zx-color-text) 8%, var(--zx-color-accent));
+}
+
+.zx-app-sidebar__rail .zx-app-rail__item:not([aria-current="page"]):hover,
+.zx-app-sidebar__rail .zx-app-rail__item:not([aria-current="page"])[aria-expanded="true"] {
+  background: var(--zx-app-sidebar-hover);
+  color: var(--zx-color-text);
+}
+
+.zx-app-sidebar__rail .zx-app-rail__item:not([aria-current="page"]):active {
+  background: var(--zx-app-sidebar-press);
+}
+
+.zx-app-sidebar__rail .zx-app-rail__item[aria-current="page"]:focus-visible {
+  box-shadow: inset 0 0 0 2px var(--zx-color-on-accent), var(--zx-focus-ring);
+}
+
+.zx-app-sidebar__rail .zx-app-rail__item::after {
+  content: "";
+  position: absolute;
+  inset-block: 22%;
+  inset-inline-start: calc(-1 * var(--zx-space-1));
+  inline-size: var(--zx-app-sidebar-marker);
+  border-start-end-radius: var(--zx-radius-full);
+  border-end-end-radius: var(--zx-radius-full);
+  background: var(--zx-color-accent);
+  opacity: 0;
+}
+
+.zx-app-sidebar[data-side="right"] .zx-app-rail__item::after {
+  inset-inline: auto calc(-1 * var(--zx-space-1));
+  border-radius: 0;
+  border-start-start-radius: var(--zx-radius-full);
+  border-end-start-radius: var(--zx-radius-full);
+}
+
+.zx-app-sidebar[data-orientation="horizontal"] .zx-app-rail__item::after {
+  inset-block: auto calc(-1 * var(--zx-space-1));
+  inset-inline: 22%;
+  inline-size: auto;
+  block-size: var(--zx-app-sidebar-marker);
+  border-radius: 0;
+  border-start-start-radius: var(--zx-radius-full);
+  border-start-end-radius: var(--zx-radius-full);
+}
+
+.zx-app-sidebar[data-side="bottom"] .zx-app-rail__item::after {
+  inset-block: calc(-1 * var(--zx-space-1)) auto;
+  border-radius: 0;
+  border-end-start-radius: var(--zx-radius-full);
+  border-end-end-radius: var(--zx-radius-full);
+}
+
+.zx-app-sidebar__rail .zx-app-rail__item[aria-current="page"]::after { opacity: 1; }
+.zx-app-sidebar__rail .zx-app-rail__item[data-active-descendant="true"]:not([aria-current="page"])::after {
+  inset-block: 34%;
+  opacity: .55;
+}
+
+.zx-app-sidebar[data-orientation="horizontal"] .zx-app-rail__item[data-active-descendant="true"]:not([aria-current="page"])::after {
+  inset-block: auto calc(-1 * var(--zx-space-1));
+  inset-inline: 34%;
+}
+
+/*
+ * The count a minimized rail would otherwise lose. `data-zx-badge` is set by the component from
+ * the item's own badge: a number that fits stays a number, and one that does not becomes a dot,
+ * because a three-digit pill on a 32px target stops being a badge and starts being a label. The
+ * figure itself moves into the control's accessible name either way, so nothing is dropped —
+ * only redrawn.
+ */
+.zx-app-sidebar__rail .zx-app-rail__item-badge {
+  inset-block-start: 0;
+  inset-inline-end: 0;
+  min-inline-size: var(--zx-space-4);
+  block-size: var(--zx-space-4);
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-accent);
+  box-shadow: 0 0 0 2px var(--zx-color-bg-surface);
+  padding-inline: var(--zx-space-1);
+  color: var(--zx-color-on-accent);
+  font-size: var(--zx-text-xs);
+  font-variant-numeric: tabular-nums;
+  font-weight: 600;
+  line-height: var(--zx-space-4);
+  text-align: center;
+}
+
+.zx-app-sidebar__rail .zx-app-rail__item-badge[data-zx-badge="dot"] {
+  min-inline-size: 0;
+  inline-size: var(--zx-space-2);
+  block-size: var(--zx-space-2);
+  padding: 0;
+  font-size: 0;
+  line-height: 0;
+}
+
+/* On the filled pill the badge would be accent-on-accent. Invert it so the count keeps a fill
+   of its own without introducing a third colour. */
+.zx-app-sidebar__rail .zx-app-rail__item[aria-current="page"] .zx-app-rail__item-badge {
+  background: var(--zx-color-on-accent);
+  box-shadow: none;
+  color: var(--zx-color-accent);
+}
+
+/*
+ * Motion. Everything here is decoration on a state change that is already expressed statically,
+ * so all of it is opt-in.
+ *
+ * The expanded tree is re-rendered wholesale on every branch toggle, which is why the disclosure
+ * animation is driven by `data-branch-motion` — an attribute the component sets on exactly the
+ * sublist it just opened, so the branches that were already open do not replay it.
+ */
+@media (prefers-reduced-motion: no-preference) {
+  .zx-app-sidebar__item,
+  .zx-app-sidebar__rail .zx-app-rail__item {
+    transition: background-color var(--zx-dur-fast) var(--zx-ease),
+      color var(--zx-dur-fast) var(--zx-ease),
+      box-shadow var(--zx-dur-fast) var(--zx-ease);
+  }
+
+  .zx-app-sidebar__item::before,
+  .zx-app-sidebar__rail .zx-app-rail__item::after {
+    transition: opacity var(--zx-dur-base) var(--zx-ease),
+      inset-block var(--zx-dur-base) var(--zx-ease);
+  }
+
+  .zx-app-sidebar__item:active,
+  .zx-app-sidebar__rail .zx-app-rail__item:active { transform: scale(.985); }
+
+  .zx-app-sidebar__expanded,
+  .zx-app-sidebar__rail { animation: zx-app-sidebar-mode var(--zx-dur-base) var(--zx-ease); }
+
+  .zx-app-sidebar__sublist[data-branch-motion="expand"] { animation: zx-app-sidebar-branch var(--zx-dur-base) var(--zx-ease); }
+}
+
+@keyframes zx-app-sidebar-mode {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@keyframes zx-app-sidebar-branch {
+  from { opacity: 0; transform: translateY(-4px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+/* Forced colours drop backgrounds and box-shadows, so the pill and the marker both disappear.
+   The system's own selected-item pair carries the state there instead. */
+@media (forced-colors: active) {
+  .zx-app-sidebar__item[aria-current="page"],
+  .zx-app-sidebar__rail .zx-app-rail__item[aria-current="page"],
+  .zx-app-sidebar__rail .zx-app-rail__item-badge {
+    background: Highlight;
+    color: HighlightText;
+  }
+
+  .zx-app-sidebar__item::before,
+  .zx-app-sidebar__rail .zx-app-rail__item::after { background: Highlight; }
+}
+
 @media (prefers-reduced-transparency: reduce) {
   .zx-app-sidebar {
     border-color: var(--zx-color-border);

package/src/components/app-sidebar/app-sidebar.js

@@ -1,5 +1,6 @@
 import { Component } from '../../core/component.js';
 import { h } from '../../core/dom.js';
+import { printf } from '../../core/i18n.js';
 import { icon } from '../../core/icons.js';
 import { uid } from '../../core/util.js';
 import {
@@ -99,8 +100,10 @@ export class AppSidebar extends Component {
   setItems(items) {
     this._items = normalizeAppItems(items);
     this._reconcileExpanded();
-    if (this._rail) this._rail.setItems(this._items);
-    else this._renderTree();
+    if (this._rail) {
+      this._rail.setItems(this._items);
+      this._decorateRail();
+    } else this._renderTree();
     return this;
   }
 
@@ -151,7 +154,10 @@ export class AppSidebar extends Component {
     const expanded = !this._expanded.has(key);
     if (expanded) this._expanded.add(key);
     else this._expanded.delete(key);
-    if (!this._rail) this._renderTree();
+    if (!this._rail) {
+      this._renderTree();
+      if (expanded) this._markBranchMotion(key);
+    }
     if (!silent) this.emit('branchchange', {
       item,
       id: item.id,
@@ -298,7 +304,7 @@ export class AppSidebar extends Component {
     const collapseButton = h('button', {
       class: 'zx-app-sidebar__collapse zx-icon-btn',
       type: 'button',
-      ariaLabel: 'Minimize application sidebar'
+      ariaLabel: this._message('appSidebar.minimize', 'Minimize application sidebar')
     }, icon(this._side === 'right' ? 'chevron-right' : 'chevron-left'));
     collapseButton.hidden = !this.options.collapsible;
     const footer = h('footer', { class: 'zx-app-sidebar__footer' });
@@ -330,7 +336,7 @@ export class AppSidebar extends Component {
       const expandButton = h('button', {
         class: 'zx-app-sidebar__rail-toggle zx-icon-btn',
         type: 'button',
-        ariaLabel: 'Expand application sidebar'
+        ariaLabel: this._message('appSidebar.expand', 'Expand application sidebar')
       }, icon(this._side === 'right' ? 'chevron-left' : 'chevron-right'));
       railHeader.append(expandButton);
       this._railExpandButton = expandButton;
@@ -356,6 +362,31 @@ export class AppSidebar extends Component {
     });
     this._listenMode(railHost, 'zx-select', (event) => event.stopPropagation());
     this._listenMode(railHost, 'zx-flyoutchange', (event) => event.stopPropagation());
+    this._decorateRail();
+  }
+
+  /**
+   * Keeps a minimized rail's counts readable and audible.
+   *
+   * A rail destination is icon-only, so its accessible name is the label alone and the badge the
+   * expanded tree showed as text is announced by nothing. Here the figure is folded back into the
+   * name, and `data-zx-badge` tells the stylesheet whether the count still fits the target or has
+   * to be drawn as a dot. Presentation only: no item, option, event, or listener is touched.
+   * @returns {void}
+   */
+  _decorateRail() {
+    const rail = this.refs.rail;
+    if (!rail) return;
+    for (const control of rail.querySelectorAll('.zx-app-rail__item[data-app-nav-value-id]')) {
+      const badge = control.querySelector(':scope > .zx-app-rail__item-badge');
+      if (!badge) continue;
+      const item = findItem(this._items, control.getAttribute('data-app-nav-value-id'));
+      if (!item || item.badge == null) continue;
+      const count = String(item.badge);
+      badge.dataset.zxBadge = count.length > 2 ? 'dot' : 'count';
+      control.setAttribute('aria-label',
+        this._message('appSidebar.itemBadge', '%1 (%2)', item.label, count));
+    }
   }
 
   /** @param {EventTarget} target @param {string} type @param {EventListener} listener @returns {void} */
@@ -494,6 +525,35 @@ export class AppSidebar extends Component {
     }
   }
 
+  /**
+   * Flags the sublist a branch toggle just opened so the stylesheet can animate that one branch.
+   *
+   * `_renderTree()` rebuilds every row on every toggle, so a transition declared on the sublist
+   * alone would replay on branches that never moved. The attribute is written after the rebuild
+   * and disappears with the element on the next one, which is why it needs no teardown.
+   * @param {string} key Branch id as a string.
+   * @returns {void}
+   */
+  _markBranchMotion(key) {
+    if (!this.refs.list) return;
+    const control = [...this.refs.list.querySelectorAll('[data-app-nav-id]')]
+      .find((candidate) => candidate.getAttribute('data-app-nav-id') === key) ?? null;
+    const sublist = control?.parentElement?.querySelector(':scope > .zx-app-sidebar__sublist');
+    if (sublist instanceof HTMLElement) sublist.dataset.branchMotion = 'expand';
+  }
+
+  /**
+   * Resolves a message through the host translator, falling back to the built-in English text.
+   * @param {string} key Message key.
+   * @param {string} fallback Built-in text, with `%1`-style placeholders.
+   * @param {...unknown} args Interpolation values.
+   * @returns {string}
+   */
+  _message(key, fallback, ...args) {
+    const message = this.msg(key, ...args);
+    return message === key ? printf(fallback, args) : message;
+  }
+
   /** @returns {void} */
   _reconcileExpanded() {
     const branchIds = new Set();

package/src/components/button/button.css

@@ -93,6 +93,14 @@
   display: inline-flex;
 }
 
+.zx-btn__shortcut {
+  font: inherit;
+  font-size: var(--zx-text-xs);
+  opacity: .7;
+  margin-inline-start: var(--zx-space-1);
+  white-space: nowrap;
+}
+
 .zx-btn-group > .zx-btn:not(:first-child) {
   margin-inline-start: -1px;
   border-start-start-radius: 0;

package/src/components/button/button.js

@@ -1,6 +1,8 @@
 import { h } from '../../core/dom.js';
 import { icon as createIcon } from '../../core/icons.js';
 
+/** @typedef {{label:string,keys:string}} ButtonShortcut Visible hint and ARIA key combination; the host binds the action. */
+
 /**
  * @typedef {Object} ButtonOptions
  * @property {string} [label=''] Visible button label.
@@ -9,6 +11,7 @@ import { icon as createIcon } from '../../core/icons.js';
  * @property {'md'|'sm'} [size='md'] Control size.
  * @property {boolean} [disabled=false] Whether the button is disabled.
  * @property {string} [title] Native title text.
+ * @property {ButtonShortcut} [shortcut] Keyboard hint; does not register a keyboard handler.
  * @property {(event: MouseEvent) => void} [onclick] Click callback.
  */
 
@@ -32,7 +35,8 @@ export function button(opts = {}) {
     class: 'zx-btn',
     type: 'button',
     disabled: Boolean(options.disabled),
-    title: options.title,
+    title: options.title ?? (options.shortcut ? `${options.label} (${options.shortcut.label})` : undefined),
+    ariaKeyshortcuts: options.shortcut?.keys,
     dataset: {
       kind: normalizeKind(options.kind),
       size: normalizeSize(options.size)
@@ -45,6 +49,7 @@ export function button(opts = {}) {
   if (options.label !== '') {
     element.append(h('span', { class: 'zx-btn__label' }, String(options.label)));
   }
+  if (options.shortcut) element.append(h('kbd', { class: 'zx-btn__shortcut', ariaHidden: 'true' }, options.shortcut.label));
   if (!options.label && options.title) element.setAttribute('aria-label', options.title);
   if (typeof options.onclick === 'function') element.onclick = options.onclick;
   return element;