@nextrap/nte-nav 1.2.0 → 2.0.1

package/.ai-usage-info.md

@@ -0,0 +1,65 @@
+# @nextrap/nte-nav
+
+Draft replacement for the navigation portion of `@nextrap/nte-nav`. Do not remove or change the legacy package and do not add navbar concerns here.
+
+## First reference
+
+Read the demo files before changing the API:
+
+- `demo/01-overview.md` explains the component model.
+- `demo/02-horizontal.html` demonstrates links, icons and nested submenus.
+- `demo/03-vertical.html` demonstrates the same markup under the vertical mixin.
+- `demo/04-responsive-order.html` demonstrates responsive orientation and Flexbox order.
+- `demo/05-variations.html` demonstrates sizes, visual variants and linked/non-linked parent items.
+- `demo/main.scss` is the authoritative example for binding public mixins to semantic contexts.
+
+## Markup
+
+```html
+<nte-nav aria-label="Hauptnavigation">
+  <nte-nav-item submenu-popover>
+    <svg slot="icon" aria-hidden="true"><!-- icon --></svg>
+    Leistungen
+    <nte-nav-item href="/leistungen/beratung">Beratung</nte-nav-item>
+  </nte-nav-item>
+  <nte-nav-item href="/ueber-uns" current="page">Über uns</nte-nav-item>
+</nte-nav>
+```
+
+- Consumers never author a `ul/li/ul` tree.
+- Direct nested items are automatically assigned to the parent item's `submenu` slot by the label slot-change handler.
+- Anchors and submenu controls stay inside each item's Shadow DOM.
+- Horizontal submenus use manual declarative Popover: add `submenu-popover` to the parent `nte-nav-item`; it renders `popover="auto"` and `popovertarget="submenu"` internally.
+- Vertical submenus must not use `submenu-popover`; they render native `details`/`summary` and stay inline.
+- A parent item should normally omit `href`, making its complete visible label the disclosure control.
+- An item with both `href` and children must keep link and disclosure as separate controls.
+- Do not add `menu`, `menubar` or `menuitem` roles for ordinary site navigation.
+- Horizontal orientation positions the Popover submenu with CSS Anchor Positioning; vertical orientation keeps it static and inline below its parent.
+- Orientation mixins do not add/remove attributes. For nested responsive submenus, the integration must manually add/remove `submenu-popover` or choose one authored variant.
+- Keep `nextrap_element({ slotVisibility: true })` and use `.slot-empty` for optional slots instead of component-authored icon state.
+
+## Styling
+
+```scss
+@use '@nextrap/nte-nav' as nav;
+
+.site-header nte-nav.style-default {
+  @include nav.default-style();
+  @include nav.responsive(48rem);
+}
+```
+
+- Keep Shadow DOM CSS functional only.
+- Visual styling belongs in the exported mixins and reaches internal markup through parts.
+- Orientation is a mixin/CSS-custom-property concern, not a component attribute.
+- Examples do not explicitly add `style-default`; `SetDefaultStyleMixin` adds it.
+- A non-default `style-*` variant must include its full visual baseline.
+- Feature classes, if introduced, start with `with-*`.
+
+## Accessibility checks
+
+- Give each `nte-nav` an `aria-label` when the page has multiple nav landmarks.
+- Preserve native link behavior and forward `current` to the anchor's `aria-current`.
+- Keep visible focus indicators on links and disclosure buttons.
+- Test Tab, Shift+Tab, Enter, Space, touch input and reduced motion.
+- Flex `order` changes only visual order; avoid it when that would make focus order confusing.

package/ARCHITECTURE.md

@@ -0,0 +1,155 @@
+# NTE Nav 2 architecture
+
+## Native Popover only
+
+Die horizontale Submenu-Variante basiert vollständig auf dem nativen HTML
+Popover-Mechanismus.
+
+Ein `nte-nav-item` mit `submenu-popover` rendert intern ausschließlich
+deklaratives Popover-Markup:
+
+```html
+<button popovertarget="submenu">...</button>
+<div id="submenu" popover="auto">...</div>
+```
+
+Die Popover-Logik muss vom Browser kommen. `nte-nav` / `nte-nav-item` dürfen
+keine JavaScript-Popover-Logik implementieren:
+
+- kein `showPopover()`;
+- kein `hidePopover()`;
+- keine JS-Synchronisierung zwischen CSS-Orientation und Popover;
+- keine Resize-/Media-Query-Logik für Popover.
+
+Popover wird manuell durch das öffentliche `submenu-popover` Attribut am
+betroffenen `nte-nav-item` aktiviert oder durch Entfernen dieses Attributs
+deaktiviert.
+
+## Vertikale Navigation
+
+Die vertikale Variante darf kein Popover verwenden. Ein vertikales Submenu wird
+korrekt gerendert, indem am betroffenen `nte-nav-item` **kein**
+`submenu-popover` Attribut gesetzt wird.
+
+Dann rendert `nte-nav-item` intern native Disclosure-Struktur:
+
+```html
+<details id="details" part="details">
+  <summary id="disclosure" part="disclosure">...</summary>
+  <div id="submenu" part="submenu" role="list">...</div>
+</details>
+```
+
+Bei einem Elternpunkt mit eigenem `href` bleiben Link und Disclosure getrennt:
+
+```html
+<a id="link" part="link" href="...">...</a>
+<details id="details" part="details">
+  <summary id="toggle" part="toggle">...</summary>
+  <div id="submenu" part="submenu" role="list">...</div>
+</details>
+```
+
+Die vertikale Darstellung entsteht durch die `vertical()` SCSS-Variante. Sie
+setzt die Navigationsrichtung auf Spalte und die Submenu-Position auf normalen
+Dokumentfluss:
+
+- `--nte-nav-flow: column`;
+- `--nte-nav-submenu-position: static`;
+- `--nte-nav-submenu-inline-size: 100%`;
+- transparente Submenu-Fläche ohne Popover-Box, Border oder Shadow;
+- optionaler Einzug über `--nte-nav-inline-submenu-indent`.
+
+Das Submenu öffnet ausschließlich über den nativen `details[open]` Zustand. Die
+CSS-Regel für `#details[open] #submenu` macht den Inhalt sichtbar und klappt die
+Grid-Zeile von `0fr` auf `1fr` auf. Dadurch bleibt das Submenu inline unter dem
+Elterneintrag und erweitert die Navigation vertikal, statt als Overlay aus dem
+Layout herauszuspringen.
+
+Wichtig: Für vertikale Navigation darf weder das öffentliche
+`submenu-popover` Attribut noch intern `popover` oder `popovertarget` vorhanden
+sein.
+
+## CSS-Block- und Mixin-Dokumentation
+
+Vor jedem zusammengehörigen CSS-Block und vor jedem SCSS-Mixin muss ein kurzer
+Kommentar stehen, der seinen Zweck beschreibt. Der Kommentar muss erklären,
+welches Verhalten der Block beziehungsweise das Mixin steuert und — falls
+relevant — in welchem Zustand oder für welche Variante es gilt.
+
+Ein Block umfasst dabei alle direkt zusammengehörigen Regeln eines Elements,
+Parts oder Zustands. Einzelne CSS-Regeln innerhalb eines solchen Blocks
+benötigen keinen eigenen Kommentar. Reine technische Folge- oder Reset-Regeln
+können mit dem Kommentar des übergeordneten Blocks gruppiert werden.
+
+Die Regel gilt insbesondere für:
+
+- `:host`- und Komponentenblöcke;
+- `::part(...)`-Blöcke;
+- `:has(...)`-, Zustands- und Selektorblöcke;
+- responsive beziehungsweise über `tj-responsive` gesetzte Zustände;
+- jedes öffentliche SCSS-Mixin unter `src/scss/`.
+
+Kommentare dürfen nicht nur den Selektor wiederholen. Sie müssen den
+funktionalen Zweck des jeweiligen Blocks dokumentieren. Neue oder geänderte
+zweckorientierte CSS-Blöcke und Mixins ohne Zweckkommentar sind nicht zulässig.
+
+## Responsive Verhalten
+
+Responsive Änderungen werden nicht über CSS-Media-Queries in SCSS umgesetzt.
+Breakpoint-abhängige Zustände müssen über `tj-responsive` beziehungsweise
+`@trunkjs/responsive`-Klassen und Attribute gesteuert werden. Das gilt sowohl
+für die Umschaltung zwischen horizontaler und vertikaler Navigation als auch
+für responsive Sichtbarkeit, Reihenfolge und Layout-Eigenschaften.
+
+SCSS-Varianten dürfen ausschließlich die jeweils gesetzten Zustände stylen;
+eine eigene `@media`-Regel oder eine parallele Breakpoint-Logik innerhalb von
+`nte-nav` ist nicht zulässig.
+
+## Styling und Style-Varianten
+
+Das Shadow DOM enthält ausschließlich betriebsnotwendige Layout-, Disclosure-
+und Popover-Regeln. Visuelle Defaults und Varianten werden außerhalb des Shadow
+DOM über die öffentlichen Parts gestylt.
+
+Die Default-Baseline wird im Mixin `default-style()` definiert. Neue visuelle
+Varianten müssen dieses Mixin erweitern und unter `src/scss/styles/` angelegt
+werden. Beispiel:
+
+```scss
+@use '../default-style' as default;
+
+@mixin bordered-style() {
+  @include default.default-style();
+
+  & nte-nav-item::part(link),
+  & nte-nav-item::part(disclosure) {
+    border: var(--nt-border-width) solid var(--nt-border);
+  }
+}
+```
+
+Die Variante wird über eine eigene `style-*`-Klasse am Custom Element aktiviert
+und muss die vollständige Default-Baseline über das Default-Mixin erben:
+
+```scss
+nte-nav.style-bordered {
+  @include nav.bordered-style();
+}
+```
+
+Dabei gelten folgende Regeln:
+
+- Visuelles Styling immer über `::part(...)`, niemals durch zusätzliche
+  visuelle Regeln im Shadow DOM.
+- Globale Werte aus `@nextrap/style-base` über `--nt-*` Tokens beziehen.
+- Komponentenvariablen nur für betriebsnotwendiges Verhalten verwenden, etwa
+  Orientierung, Submenu-Positionierung und Animation.
+- Eine Style-Variante wird als eigenes Mixin unter `src/scss/styles/` angelegt
+  und in `index.scss` exportiert.
+- Pro `nte-nav` darf nur eine `style-*`-Klasse gesetzt sein.
+- Feature-Änderungen, die mit anderen Styles kombinierbar sein sollen, werden
+  als `with-*` Modifier und nicht als neue `style-*`-Variante umgesetzt.
+- Das Default-Mixin setzt für die Hauptnavigation keine Hintergrundfarbe. Das
+  horizontale Dropdown erhält seine Hintergrundfarbe separat über
+  `::part(submenu)`.