@nextrap/ntl-card-row 2.0.0 → 2.0.1

package/.agents/skills/ntl-card-row-theming/SKILL.md

@@ -16,6 +16,7 @@ Nutze diesen Skill für Theme-SCSS und visuelle Varianten. Für Markup und Card-
 - Nutze für visuelle Anpassungen die Parts `container`, `header`, `main` und `footer` sowie vorhandene Mixins.
 - Setze `--gutter-x` und `--gutter-y` immer als echte Längenwerte mit Einheit, z. B. `0px`, `16px` oder `24px`, niemals als einheitsloses `0`.
 - Desktop-spezifische Regeln werden auf `[mode='desktop']` gescoped.
+- Für mobile Sequenzen `with-horizontal-flow()` verwenden; Themes dürfen dessen Flex-, Breiten- und Overflow-Regeln nicht nachbauen oder überschreiben.
 
 ## Vorhandene Mixins
 
@@ -24,6 +25,21 @@ Nutze diesen Skill für Theme-SCSS und visuelle Varianten. Für Markup und Card-
 | `default-style()` | Vollständige visuelle Baseline; optionaler `$cols`-Fallback |
 | `with-borderless-cards()` | Card-Rahmen und Innenabstand entfernen |
 | `with-footer-separators()` | Desktop-Trenner für Footer-Cards |
+| `with-horizontal-flow()` | Opt-in Horizontal-Scroll mit nativer Snap-Logik ausschließlich im Mobile-Modus |
 | `with-item-separators()` | Responsive Trenner zwischen Cards |
 | `with-raised-card()` | Einzelne Card hervorheben |
 | `with-modifier-classes()` | Vorbereitete Modifier-Klassen registrieren |
+
+## Horizontal-Flow konfigurieren
+
+```scss
+ntl-card-row.timeline {
+  @include cardRow.with-horizontal-flow(
+    $visible-cols-mobile: 1.25,
+    $gap: 1rem,
+    $snap: proximity
+  );
+}
+```
+
+`default-style()` registriert zusätzlich `.with-horizontal-flow` mit den Defaults. Öffentliche Instanzwerte sind `--visible-cols-mobile`, `--horizontal-flow-gap` und `--horizontal-flow-snap`; der vorhandene `main`-Part bleibt die Scrollfläche.

package/.agents/skills/ntl-card-row-usage/SKILL.md

@@ -53,7 +53,26 @@ Nutze immer die `trunkjs/content-pane`-Notation `{: layout="..."}`. Die Default-
 - Desktop verwendet feste Breiten von `--cols: 1` bis `--cols: 12`.
 - Ohne `--cols` an Row oder Card nutzt die Card die volle verfügbare Zeile.
 - Eine Card-Breite wächst oder schrumpft nicht; überbreiter Inhalt wird abgeschnitten.
-- Im Mobile-Modus stehen Cards immer untereinander in voller Breite.
+- Im Mobile-Modus stehen Cards standardmäßig untereinander in voller Breite.
+- `.with-horizontal-flow` aktiviert opt-in eine nativ horizontal scrollbare mobile Reihe; Desktop verwendet weiterhin `--cols`.
+- `--visible-cols-mobile` bestimmt dabei die sichtbare Kartenanzahl (Default `1.15`), `--horizontal-flow-gap` den Inline-Abstand und `--horizontal-flow-snap` die Snap-Stärke.
 - `--min-width` und `--max-width` sind standardmäßig `unset`.
 - `--gutter-x` und `--gutter-y` benötigen immer Längeneinheiten und dürfen nie als einheitsloses `0` gesetzt werden; verwende `0px`, `16px` oder andere echte Längenwerte.
 - Verwende keine `cols`-Attribut-API.
+
+## Horizontaler Mobile-Flow
+
+```markdown
+## Meilensteine
+{: layout="ntl-card-row.with-horizontal-flow" section-style="--cols: 3; --visible-cols-mobile: 1.2; --horizontal-flow-gap: 16px;"}
+
+### Analyse
+
+Gemeinsames Zielbild definieren.
+
+### Umsetzung
+
+Lösung ausliefern und messen.
+```
+
+Der Modifier ändert weder die DOM-Reihenfolge noch den Desktop-Contract. Native Touch- und Trackpad-Interaktion funktioniert ohne zusätzliche Slider-Controls.

package/.ai-usage-info.md

@@ -46,6 +46,21 @@ Text
 Wide highlighted card
 ```
 
+Horizontal mobile sequence with the regular desktop grid:
+
+```md
+## Milestones
+{: layout="ntl-card-row.with-horizontal-flow" section-style="--cols: 3; --visible-cols-mobile: 1.2; --horizontal-flow-gap: 16px;"}
+
+### Discover
+
+Define the goal.
+
+### Deliver
+
+Ship the result.
+```
+
 Demo/theme SCSS binds the visual baseline to `ntl-card-row.style-default`; examples do not add a `.default` class. Demo modifier classes should be defined on `ntl-card-row` in demo/theme SCSS and include mixins there:
 
 ```scss
@@ -64,7 +79,7 @@ ntl-card-row.with-item-separators {
 - Uses `SubLayoutApplyMixin` to assign direct headings to `header`, direct `footer` to `footer`, and direct `section` children to `nte-card`.
 - Desktop layout uses a 12-column model. Set `--cols: 1` through `--cols: 12` on `ntl-card-row` and optionally on individual cards.
 - A card-level `--cols` value overrides the inherited row value. Without either value, cards use the full available row width.
-- Fixed columns do not grow or shrink; overflowing content is clipped. Mobile mode stacks cards full-width.
+- Fixed columns do not grow or shrink; overflowing content is clipped. Mobile mode stacks cards full-width unless `.with-horizontal-flow` enables the opt-in native horizontal scroller.
 
 Important CSS variables:
 
@@ -73,6 +88,9 @@ Important CSS variables:
 - `--cols`: desktop card width from 1 through 12; inherited by cards and defaults to full width
 - `--min-width` / `--max-width`: optional card constraints; both default to `unset`
 - `--gutter-x` / `--gutter-y`: card gaps; always pass real length values with units, preferably `px` such as `0px`, `16px` or `24px`, never unitless values like `0`
+- `--visible-cols-mobile`: visible cards in the horizontal mobile flow, default `1.15`; values below `1` are clamped to `1`
+- `--horizontal-flow-gap`: inline gap in the horizontal mobile flow, default `var(--gutter-x)`
+- `--horizontal-flow-snap`: native scroll-snap strength (`none`, `proximity` or `mandatory`), default `proximity`
 
 ## CSS parts
 
@@ -94,18 +112,20 @@ Use `::part(container)`, `::part(header)`, `::part(main)` and `::part(footer)` f
 
 @include cardRow.with-borderless-cards();
 @include cardRow.with-footer-separators($separator-color: var(--nt-primary));
+@include cardRow.with-horizontal-flow($visible-cols-mobile: 1.2, $gap: 16px);
 @include cardRow.with-item-separators($separator-color: var(--nt-gray-400));
 @include cardRow.with-raised-card();
 @include cardRow.with-modifier-classes();
 ```
 
-`default-style()` includes modifier classes by default. Available classes: `.highlight` for raised cards and `.footer-separators` / legacy `.style-footer` for desktop footer separators.
+`default-style()` includes modifier classes by default. Available classes: `.with-horizontal-flow` for the mobile scroller, `.highlight` for raised cards and `.footer-separators` / legacy `.style-footer` for desktop footer separators.
 
 `$cols` is an optional theme fallback only. Prefer setting `--cols` in usage markup so the layout stays flexible; a card-level value overrides the inherited row value.
 
 When setting `--gutter-x` or `--gutter-y`, always include a length unit. Use `0px` instead of `0`, because the component uses gutter values in `calc()` expressions.
 
 - `with-borderless-cards()` sets `--border: none` and `--inner-padding: 0` for all direct `nte-card` children.
+- `with-horizontal-flow()` styles the existing `main` part and direct cards only in `mode="mobile"`; desktop and the unmodified mobile stack remain unchanged.
 - `with-item-separators()` adds separator pseudo-elements between direct `nte-card` children: vertical in desktop mode at half the horizontal gap, horizontal in mobile/tablet mode at half the vertical gap.
 
 Keep Shadow DOM styles functional only; visual row styles belong in these mixins.

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+## 2.0.1 (2026-09-10)
+
+### 🚀 Features
+
+- **ntl-card-row:** add mobile horizontal flow ([f533ebf](https://github.com/nextrap/nextrap-monorepo/commit/f533ebf))
+- add component theme and usage skills ([617cfde](https://github.com/nextrap/nextrap-monorepo/commit/617cfde))
+- **card-row:** add attribute-driven sizing ([6269960](https://github.com/nextrap/nextrap-monorepo/commit/6269960))
+- add list styles and footer demo for card row ([cacf6ac](https://github.com/nextrap/nextrap-monorepo/commit/cacf6ac))
+
+### 🩹 Fixes
+
+- declare external libraries as peers and retain test dependencies ([67c6ffa](https://github.com/nextrap/nextrap-monorepo/commit/67c6ffa))
+- **card-row:** keep cols as CSS variable ([036ebb0](https://github.com/nextrap/nextrap-monorepo/commit/036ebb0))
+- **card-row:** restore attribute column sizing ([d795aa3](https://github.com/nextrap/nextrap-monorepo/commit/d795aa3))
+- **card-row:** restore cross-browser CSS sizing ([2825d8b](https://github.com/nextrap/nextrap-monorepo/commit/2825d8b))
+- **ntl:** migrate ntl-card-row to nt-core ([f91b854](https://github.com/nextrap/nextrap-monorepo/commit/f91b854))
+- **layout:** keep layout packages separate ([c82b05a](https://github.com/nextrap/nextrap-monorepo/commit/c82b05a))
+- use aliasesExclude to avoid internal relative paths ([6b8123e](https://github.com/nextrap/nextrap-monorepo/commit/6b8123e))
+
+### ❤️ Thank You
+
+- Enzo Volkmann @evolkmann
+- Matthias Leuffen
+- Paul Buehler

package/README.md

@@ -20,6 +20,14 @@ import '@nextrap/ntl-card-row';
 ntl-card-row {
   @include cardRow.default-style();
 }
+
+ntl-card-row.timeline {
+  @include cardRow.with-horizontal-flow(
+    $visible-cols-mobile: 1.25,
+    $gap: 1rem,
+    $snap: proximity
+  );
+}
 ```
 
 Content-Pane example:
@@ -38,10 +46,31 @@ Content-Pane example:
 {: layout="nte-card"}
 ```
 
-The row follows Bootstrap's 12-column model. `--cols: 4` makes every card four columns wide; an individual card can override the inherited row value with its own `--cols`. Fixed columns neither grow nor shrink, and overflowing card content is clipped. Without `--cols`, a card uses the full available row width.
+Opt-in mobile horizontal flow with a visible preview of the next card:
+
+```markdown
+## Milestones
+{: layout="ntl-card-row.with-horizontal-flow" section-style="--cols: 3; --visible-cols-mobile: 1.2; --horizontal-flow-gap: 16px;"}
+
+### Discover
+
+Define the shared goal.
+
+### Prototype
+
+Test the first solution.
+
+### Deliver
+
+Ship and measure the result.
+```
+
+The row follows Bootstrap's 12-column model. `--cols: 4` makes every card four columns wide; an individual card can override the inherited row value with its own `--cols`. Fixed columns neither grow nor shrink, and overflowing card content is clipped. Without `--cols`, a card uses the full available row width. Mobile mode remains a full-width single column unless `.with-horizontal-flow` is present. The modifier creates a native horizontal scroller only in mobile mode; desktop keeps the 12-column layout.
 
 `--min-width` and `--max-width` optionally constrain cards and both default to `unset`.
 
+For `.with-horizontal-flow`, `--visible-cols-mobile` controls how many cards are visible (default `1.15`), `--horizontal-flow-gap` controls their inline gap, and `--horizontal-flow-snap` accepts `none`, `proximity` or `mandatory` (default `proximity`). Values below `1` for `--visible-cols-mobile` are clamped to `1` by the sizing rule.
+
 When setting `--gutter-x` or `--gutter-y`, always use real length values with units such as `0px`, `16px` or `24px`. Never use unitless `0`, because gutter values are used in `calc()` expressions.
 
 ```markdown

package/index.scss

@@ -1,6 +1,8 @@
+// Veröffentlicht die selektorunabhängigen Styling- und Feature-Mixins des Packages.
 @forward 'src/scss/default-style';
 @forward 'src/scss/with-borderless-cards';
 @forward 'src/scss/with-footer-separators';
+@forward 'src/scss/with-horizontal-flow';
 @forward 'src/scss/with-item-separators';
 @forward 'src/scss/with-modifier-classes';
 @forward 'src/scss/with-raised-card';

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@nextrap/ntl-card-row",
-    "version": "2.0.0",
+    "version": "2.0.1",
     "files": [
         "*.*",
-        "src",
-        ".agents"
+        ".agents",
+        "src"
     ],
     "main": "./index.js",
     "repository": {
@@ -13,16 +13,18 @@
         "url": "https://github.com/nextrap/nextrap-monorepo"
     },
     "dependencies": {
-        "@nextrap/nte-card": "^2.0.0",
         "@nextrap/nt-core": "^2.0.0",
-        "@nextrap/style-reset": "^2.0.0",
-        "lit": "^3.3.1"
+        "@nextrap/nte-card": "^2.0.0",
+        "@nextrap/style-reset": "^2.0.0"
     },
     "devDependencies": {
         "@nextrap/style-base": "^2.0.0",
         "@nextrap/style-utils": "^2.0.0",
         "@trunkjs/markdown-loader": "^1.0.0"
     },
+    "peerDependencies": {
+        "lit": "^3.3.1"
+    },
     "type": "module",
     "types": "./index.d.ts",
     "web-types": "./web-types.json"

package/src/scss/_with-horizontal-flow.scss

@@ -0,0 +1,42 @@
+// Aktiviert im mobilen Responsive-Modus eine horizontal scrollbare Kartenreihe,
+// ohne den bestehenden Desktop-Contract oder die mobile Einzelspalte zu verändern.
+@mixin with-horizontal-flow(
+  $visible-cols-mobile: 1.15,
+  $gap: var(--gutter-x, var(--nt-spacing-layout)),
+  $snap: proximity
+) {
+  --visible-cols-mobile: #{$visible-cols-mobile};
+  --horizontal-flow-gap: #{$gap};
+  --horizontal-flow-snap: #{$snap};
+
+  // Der vorhandene main-Part wird zur nativen Scrollfläche; zusätzliche Controls
+  // oder ein eigener Slider-Lifecycle sind für den Basis-Flow nicht erforderlich.
+  &[mode='mobile']::part(main) {
+    flex-flow: row nowrap;
+    justify-content: flex-start;
+    gap: 0 var(--horizontal-flow-gap, var(--gutter-x, 0px));
+    overflow-x: auto;
+    overflow-y: visible;
+    overscroll-behavior-inline: contain;
+    scroll-padding-inline: var(--horizontal-flow-gap, var(--gutter-x, 0px));
+    scroll-snap-type: x var(--horizontal-flow-snap, proximity);
+    -webkit-overflow-scrolling: touch;
+  }
+
+  // Die Kartenbasis berücksichtigt die sichtbare Kartenzahl und alle Zwischenräume.
+  // max(1, ...) verhindert bei Werten unter eins eine überbreite Scroll-Karte.
+  &[mode='mobile'] > nte-card {
+    flex: 0 0 calc(
+      (100% - (max(1, var(--visible-cols-mobile, 1.15)) - 1) * var(--horizontal-flow-gap, var(--gutter-x, 0px))) /
+        max(1, var(--visible-cols-mobile, 1.15))
+    );
+    width: calc(
+      (100% - (max(1, var(--visible-cols-mobile, 1.15)) - 1) * var(--horizontal-flow-gap, var(--gutter-x, 0px))) /
+        max(1, var(--visible-cols-mobile, 1.15))
+    );
+    min-width: 0;
+    max-width: none;
+    overflow: visible;
+    scroll-snap-align: start;
+  }
+}

package/src/scss/_with-modifier-classes.scss

@@ -1,12 +1,21 @@
 @use 'with-footer-separators' as footer-separators;
+@use 'with-horizontal-flow' as horizontal-flow;
 @use 'with-raised-card' as raised-card;
 
+// Registriert die mit der Default-Style-Baseline ausgelieferten Modifier-Klassen.
 @mixin with-modifier-classes {
+  // Der horizontale Flow bleibt ein explizites Opt-in am Row-Element.
+  &.with-horizontal-flow {
+    @include horizontal-flow.with-horizontal-flow();
+  }
+
+  // Bestehende Footer-Varianten bleiben als aktuelle und Legacy-Klasse verfügbar.
   &.footer-separators,
   &.style-footer {
     @include footer-separators.with-footer-separators();
   }
 
+  // Einzelne hervorgehobene Cards erhalten weiterhin das bestehende Raised-Mixin.
   > nte-card.highlight {
     @include raised-card.with-raised-card();
   }