@nextrap/nte-nav 1.2.0 → 2.0.0

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)`.

package/README.md

@@ -1,3 +1,112 @@
-# nte-nav
+# @nextrap/nte-nav
 
-A navigation element.
+Working draft for the future Nextrap navigation component. The existing `@nextrap/nte-nav` package remains unchanged; a future navbar is explicitly out of scope.
+
+## Import
+
+```ts
+import '@nextrap/nte-nav';
+```
+
+```scss
+@use '@nextrap/nte-nav' as nav;
+
+header nte-nav.style-default {
+  @include nav.default-style();
+  @include nav.horizontal();
+  @include nav.size-medium();
+}
+
+aside nte-nav.style-default {
+  @include nav.sub-navigation();
+  @include nav.vertical();
+}
+```
+
+`SetDefaultStyleMixin` adds `style-default` when no other `style-*` class is present. The component's Shadow DOM only contains functional layout, disclosure, positioning and transition CSS. Visual styling is supplied by the public mixins.
+
+## Basic API
+
+```html
+<nte-nav aria-label="Hauptnavigation">
+  <nte-nav-item submenu-popover>
+    <svg slot="icon" aria-hidden="true"><!-- … --></svg>
+    Leistungen
+
+    <nte-nav-item href="/leistungen/beratung">Beratung</nte-nav-item>
+    <nte-nav-item href="/leistungen/entwicklung">Entwicklung</nte-nav-item>
+  </nte-nav-item>
+
+  <nte-nav-item href="/ueber-uns" current="page">Über uns</nte-nav-item>
+</nte-nav>
+```
+
+Direct nested `nte-nav-item` children are automatically assigned to the private `submenu` slot. Consumer markup no longer contains a `ul/li/ul` tree. Each item owns its anchor, disclosure control, submenu container and CSS positioning inside its Shadow DOM.
+
+Parents with children are non-linking disclosures by default: omit `href` and the complete visible label toggles the submenu. Add `href` only when the parent page is a real destination of its own; the component then keeps the link and disclosure as two separate keyboard-focusable controls.
+
+## Attributes
+
+### `nte-nav`
+
+| Attribute | Type | Purpose |
+|---|---|---|
+| `aria-label` | string | Accessible name forwarded to the internal `nav` landmark. Recommended whenever multiple navigation landmarks exist. |
+
+### `nte-nav-item`
+
+| Attribute | Type | Purpose |
+|---|---|---|
+| `href` | string | Renders the item's internal anchor. If omitted on an item with children, the label itself becomes the disclosure button. |
+| `target` | string | Forwarded to the internal anchor. |
+| `rel` | string | Forwarded to the internal anchor. |
+| `download` | string | Forwarded to the internal anchor. |
+| `current` | ARIA current token | Forwarded as `aria-current` to the internal anchor. |
+| `--order` | CSS custom property | Sets the host's Flexbox `order`. Use sparingly because visual order does not change DOM or keyboard order. |
+| `submenu-popover` | boolean attribute | Manually renders nested items as declarative Popover markup for horizontal navigation. Omit for vertical inline `details`/`summary`. |
+| `submenu-label` | string | Prefix for the submenu disclosure's accessible name. Default: `Untermenü`. |
+
+## Slots
+
+| Component | Slot | Purpose |
+|---|---|---|
+| `nte-nav` | default | Top-level `nte-nav-item` elements. |
+| `nte-nav-item` | default | Visible rich-text label. |
+| `nte-nav-item` | `icon` | Optional icon rendered in the dedicated `icon` part. Decorative SVGs should use `aria-hidden="true"`. |
+| `nte-nav-item` | `submenu` | Internal target slot for nested items. Direct nested `nte-nav-item` elements are assigned automatically. |
+
+## Parts
+
+- `nte-nav`: `nav`, `list`
+- `nte-nav-item`: `item`, `details`, `link`, `text`, `disclosure`, `toggle`, `icon`, `label`, `indicator`, `submenu`, `submenu-inner`
+
+## Public mixins
+
+- `default-style()` – full default visual baseline
+- `main-navigation()` – complete, large main-navigation variant
+- `sub-navigation()` – complete, compact sub-navigation variant
+- `horizontal($justify, $gap)` – horizontal functional orientation
+- `vertical($gap)` – vertical functional orientation
+- `responsive($breakpoint, $horizontal-justify)` – vertical below and horizontal above a breakpoint
+- `size-small()`, `size-medium()`, `size-large()` – size presets that only set component variables
+
+## Orientation and native disclosure
+
+This is ordinary website navigation, not an application menu. It intentionally uses a `nav` landmark, list/listitem semantics, links and disclosure buttons rather than ARIA `menu`/`menubar` roles.
+
+Submenus are selected manually per item. The Shadow DOM CSS consumes orientation variables from the mixins; the markup variant is controlled by the public `submenu-popover` attribute:
+
+- For `horizontal()`, add `submenu-popover` to parent items with nested items. The component renders a native `<button popovertarget="submenu">` and `<div id="submenu" popover="auto">`, so the browser handles the Popover declaratively.
+- For `vertical()`, omit `submenu-popover`. The component renders native `details` / `summary`; the submenu stays in normal document flow, animates downwards and is indented as part of the navigation path.
+- `responsive()` changes only CSS orientation. With nested submenus and no JavaScript, the integration must manually add/remove `submenu-popover` or choose one authored variant.
+
+The optional icon slot is observed by `nextrap_element({ slotVisibility: true })`. Empty icon slots receive `.slot-empty` and are hidden entirely by the component CSS.
+
+## Deliberately deferred
+
+- Navbar, sticky header and brand layout
+- Burger/offcanvas content transfer from the legacy package
+- Optional arrow-key navigation beyond normal Tab/Shift+Tab behavior
+- Public imperative `showSubmenu()` / `hideSubmenu()` methods
+- SPA-router adapters and prefetch behavior
+- Public imperative `showSubmenu()` / `hideSubmenu()` methods beyond the internal Popover synchronization

package/index.d.ts

@@ -1,4 +1,2 @@
-export * from './lib/nte-nav';
-export * from './lib/nte-navbar';
-export * from './lib/nte-navbar-line';
-export * from './components/nte-nav-brand-relocator/nte-nav-brand-relocator';
+export * from './src/components/nte-nav/nte-nav';
+export * from './src/components/nte-nav-item/nte-nav-item';