srcdev-nuxt-components 9.6.11 → 9.6.13

package/app/components/01.atoms/content-wrappers/docs-pages/CONSUMER-STYLING.md

@@ -7,9 +7,12 @@ styles both the docs nav and the page nav, plus **per-side** forms (`--content-d
 `--content-docs-page-nav-*`) that fall back to the shared one when unset.
 
 > Changed 2026-09-27: defaults no longer call `light-dark()` themselves (unsupported on older iPad
-> Safari). Colours now come from the global scheme-aware tokens (`--colour-text-default`,
-> `--page-bg`, `--theme-surface-subtle`), so they still follow light/dark mode. The active-link
-> pill is a fixed green pair that reads the same in both.
+> Safari). Text and panel colours come from the global page tokens (`--colour-text-default`,
+> `--page-bg`); hover from `--theme-surface-subtle`.
+>
+> Changed 2026-10-18: the active-link pill was a fixed green pair (`--green-01` / `--green-10`). It
+> now follows the theme: `--theme-surface` with `--theme-on-surface` text. Set
+> `--content-docs-link-active-bg` / `-color` to keep the old look.
 
 ### Headings
 
@@ -39,14 +42,16 @@ styles both the docs nav and the page nav, plus **per-side** forms (`--content-d
 | `--content-docs-link-color` | `var(--colour-text-default)` | `-nav-link-color`, `-page-nav-link-color` |
 | `--content-docs-link-hover-bg` | `var(--theme-surface-subtle)` | `-nav-link-hover-bg`, `-page-nav-link-hover-bg` |
 | `--content-docs-link-hover-color` | the link colour | `-nav-link-hover-color`, `-page-nav-link-hover-color` |
-| `--content-docs-link-active-bg` | `var(--green-01)` | `-nav-link-active-bg`, `-page-nav-link-active-bg` |
-| `--content-docs-link-active-color` | `var(--green-10)` | `-nav-link-active-color`, `-page-nav-link-active-color` |
+| `--content-docs-link-active-bg` | `var(--theme-surface)` | `-nav-link-active-bg`, `-page-nav-link-active-bg` |
+| `--content-docs-link-active-color` | `var(--theme-on-surface)` | `-nav-link-active-color`, `-page-nav-link-active-color` |
 | `--content-docs-link-bg` | `transparent` | Shared only |
 | `--content-docs-link-font-size` | `1.4rem` | Shared only |
 | `--content-docs-link-padding-block` | `0.6rem` | Shared only |
 | `--content-docs-link-padding-inline` | `0.8rem` | Shared only |
 | `--content-docs-link-margin-block` | `0` | Shared only |
 | `--content-docs-link-border-radius` | `0.4rem` | Shared only |
+| `--content-docs-link-focus-outline-width` | `0.2rem` | Shared only. Keyboard focus ring, drawn inside the link (`outline-offset: -0.2rem`) |
+| `--content-docs-link-focus-outline-color` | `var(--theme-border-focus)` | Shared only |
 
 ### Link icons
 
@@ -70,11 +75,11 @@ styles both the docs nav and the page nav, plus **per-side** forms (`--content-d
 | `--content-docs-page-nav-column-width-tablet` | `20rem` | Page nav track at 768px–1023px |
 
 Link transitions also read the library-wide `--control-transition-duration` (`200ms`) and
-`--control-transition-ease` (`ease`); focus rings use `--theme-ring`.
+`--control-transition-ease` (`ease`).
 
-The `--_*` variables declared on `.content-docs` (e.g. `--_link-color`, `--_panel-bg`)
-are the resolved shared/per-side fallback chain: not public API. Set the `--content-docs-*`
-tokens instead.
+Private tokens (not public API), declared on `.content-docs`: `--_heading-*` and `--_link-color`,
+`--_link-hover-*`, `--_link-active-*`, `--_panel-bg` (the shared values each per-side token falls
+back to), and `--_link-focus-outline` (width + colour). Set the `--content-docs-*` tokens instead.
 
 ---
 
@@ -82,11 +87,28 @@ tokens instead.
 
 | Selector | When |
 |---|---|
-| `.docs-nav-link.is-active`, `.docs-page-nav-link.is-active` | The link matching `v-model:active-nav-item` / `v-model:active-page-nav-item` (also gets `aria-current="page"`) |
-
-Inner classes: `.content-docs-inner` (grid), `.docs-nav`, `.docs-content`, `.docs-page-nav` (grid
-areas), `.docs-nav-heading`, `.docs-page-nav-heading`, `.docs-nav-list`, `.docs-page-nav-list`
-(the `<nav>`s), `.docs-nav-link`, `.docs-page-nav-link`, `-link-icon`, `-link-label`.
+| `.content-docs-nav-link[aria-current="page"]`, `.content-docs-page-nav-link[aria-current="page"]` | The link whose `to` matches `v-model:active-nav-item` / `v-model:active-page-nav-item`. Every item sharing that `to` matches |
+
+Inner classes: `.content-docs-inner` (grid), `.content-docs-nav`, `.content-docs-content`,
+`.content-docs-page-nav` (grid areas, each `min-inline-size: 0`), `.content-docs-nav-heading`,
+`.content-docs-page-nav-heading`, `.content-docs-nav-list`, `.content-docs-page-nav-list` (the
+`<nav>`s; their `<ul>`s carry `role="list"`), `.content-docs-nav-link`, `.content-docs-page-nav-link`,
+and each link's `-icon` and `-label`.
+
+> **Changed 2026-10-18**: generic class names collided with consumer CSS (a docs site is the likeliest
+> place to already have a `.docs-nav`). Every inner class gained the `content-docs-` prefix:
+>
+> | Old | New |
+> |---|---|
+> | `.docs-nav`, `.docs-content`, `.docs-page-nav` | `.content-docs-nav`, `.content-docs-content`, `.content-docs-page-nav` |
+> | `.docs-nav-heading`, `.docs-page-nav-heading` | `.content-docs-nav-heading`, `.content-docs-page-nav-heading` |
+> | `.docs-nav-list`, `.docs-page-nav-list` | `.content-docs-nav-list`, `.content-docs-page-nav-list` |
+> | `.docs-nav-link`, `.docs-page-nav-link` (and `-icon`, `-label`) | `.content-docs-nav-link`, `.content-docs-page-nav-link` (and `-icon`, `-label`) |
+> | `.is-active` | removed: select `[aria-current="page"]` |
+>
+> The three grid areas now set `min-inline-size: 0` and the grid tracks are `minmax(0, 1fr)`, so a
+> consumer `min-width: 0` on them is no longer needed. `.content-docs-content` also sets
+> `overflow-wrap: break-word`. Token names are unchanged.
 
 The collapsible wrappers are `ExpandingPanelClassic` by default (`.expanding-panel-classic-*`
 classes) or `ExpandingPanel` with `panel-variant="modern"` (`.expanding-panel-*`). Style both if
@@ -105,6 +127,12 @@ Container queries on `.content-docs` (`container-name: contentDocs`), matched in
 | 768px–1023px | Page nav pinned open in a right-hand column; docs nav collapsible above content |
 | ≥ 1024px | Three columns, both navs pinned open |
 
+Labels and headings wrap anywhere (`overflow-wrap: anywhere`), so an unbroken label stays inside its
+column. Labels take their direction from their own text (`unicode-bidi: plaintext`), so a
+right-to-left label reads and aligns right-to-left even though the link sets `direction` for the
+icon-order trick. The page itself is assumed left-to-right: on a `dir="rtl"` page set both
+`-icon-order` tokens to `rtl` to put icons at the inline start.
+
 ---
 
 ## Local overrides

package/app/components/01.atoms/content-wrappers/docs-pages/ContentDocs.vue

@@ -1,10 +1,10 @@
 <template>
   <component :is="tag" ref="rootEl" class="content-docs" :class="[elementClasses]">
     <div class="content-docs-inner">
-      <div v-if="hasDocsContent()" class="docs-content">
+      <div v-if="hasDocsContent()" class="content-docs-content">
         <slot name="docsContent"></slot>
       </div>
-      <div v-if="hasDocsNav" class="docs-nav">
+      <div v-if="hasDocsNav" class="content-docs-nav">
         <component
           :is="panelComponent"
           v-model="docsNavPanelOpen"
@@ -14,25 +14,24 @@
           :content-is-on-top="docsNavOnTop"
         >
           <template #summary>
-            <h3 class="docs-nav-heading">{{ docsNavLabel }}</h3>
+            <h3 class="content-docs-nav-heading">{{ docsNavLabel }}</h3>
           </template>
           <template #content>
-            <nav class="docs-nav-list" :aria-label="docsNavAriaLabel">
-              <ul>
-                <li v-for="item in docsNavItems" :key="item.to">
+            <nav class="content-docs-nav-list" :aria-label="docsNavAriaLabel">
+              <ul role="list">
+                <li v-for="(item, index) in docsNavItems" :key="`${index}-${item.to}`">
                   <component
                     :is="NuxtLink"
                     :to="item.to"
-                    class="docs-nav-link"
-                    :class="{ 'is-active': item.to === activeNavItem }"
+                    class="content-docs-nav-link"
                     :aria-current="item.to === activeNavItem ? 'page' : undefined"
                     @click="
                       activeNavItem = item.to;
                       docsNavPanelOpen = false;
                     "
                   >
-                    <Icon v-if="item.icon" :name="item.icon" class="docs-nav-link-icon" aria-hidden="true" />
-                    <span class="docs-nav-link-label">{{ item.label }}</span>
+                    <Icon v-if="item.icon" :name="item.icon" class="content-docs-nav-link-icon" aria-hidden="true" />
+                    <span class="content-docs-nav-link-label">{{ item.label }}</span>
                   </component>
                 </li>
               </ul>
@@ -40,7 +39,7 @@
           </template>
         </component>
       </div>
-      <div v-if="hasDocsPageNav" class="docs-page-nav">
+      <div v-if="hasDocsPageNav" class="content-docs-page-nav">
         <component
           :is="panelComponent"
           v-model="docsPageNavPanelOpen"
@@ -50,25 +49,24 @@
           :content-is-on-top="docsPageNavOnTop"
         >
           <template #summary>
-            <h3 class="docs-page-nav-heading">{{ docsPageNavLabel }}</h3>
+            <h3 class="content-docs-page-nav-heading">{{ docsPageNavLabel }}</h3>
           </template>
           <template #content>
-            <nav class="docs-page-nav-list" :aria-label="docsPageNavAriaLabel">
-              <ul>
-                <li v-for="item in docsPageNavItems" :key="item.to">
+            <nav class="content-docs-page-nav-list" :aria-label="docsPageNavAriaLabel">
+              <ul role="list">
+                <li v-for="(item, index) in docsPageNavItems" :key="`${index}-${item.to}`">
                   <component
                     :is="NuxtLink"
                     :to="item.to"
-                    class="docs-page-nav-link"
-                    :class="{ 'is-active': item.to === activePageNavItem }"
+                    class="content-docs-page-nav-link"
                     :aria-current="item.to === activePageNavItem ? 'page' : undefined"
                     @click="
                       activePageNavItem = item.to;
                       docsPageNavPanelOpen = false;
                     "
                   >
-                    <Icon v-if="item.icon" :name="item.icon" class="docs-page-nav-link-icon" aria-hidden="true" />
-                    <span class="docs-page-nav-link-label">{{ item.label }}</span>
+                    <Icon v-if="item.icon" :name="item.icon" class="content-docs-page-nav-link-icon" aria-hidden="true" />
+                    <span class="content-docs-page-nav-link-label">{{ item.label }}</span>
                   </component>
                 </li>
               </ul>
@@ -167,36 +165,21 @@ const docsPageNavPanelName = computed(() => (isMobile.value ? panelGroupId : `${
     --_heading-padding-inline: var(--content-docs-heading-padding-inline, 0);
 
     --_panel-bg: var(--content-docs-panel-bg, var(--page-bg));
-    --_panel-padding-block: var(--content-docs-panel-padding-block, 0.8rem);
-    --_panel-padding-inline: var(--content-docs-panel-padding-inline, 0.8rem);
-    --_panel-border-radius: var(--content-docs-panel-border-radius, 0.5rem);
-
-    --_link-font-size: var(--content-docs-link-font-size, 1.4rem);
-    --_link-padding-block: var(--content-docs-link-padding-block, 0.6rem);
-    --_link-padding-inline: var(--content-docs-link-padding-inline, 0.8rem);
-    --_link-margin-block: var(--content-docs-link-margin-block, 0);
-    --_link-border-radius: var(--content-docs-link-border-radius, 0.4rem);
+
     --_link-color: var(--content-docs-link-color, var(--colour-text-default));
-    --_link-bg: var(--content-docs-link-bg, transparent);
     --_link-hover-bg: var(--content-docs-link-hover-bg, var(--theme-surface-subtle));
     --_link-hover-color: var(--content-docs-link-hover-color, var(--_link-color));
-    --_link-active-bg: var(--content-docs-link-active-bg, var(--green-01));
-    --_link-active-color: var(--content-docs-link-active-color, var(--green-10));
-
-    --_page-nav-heading-padding-block: var(
-      --content-docs-page-nav-heading-padding-block,
-      var(--_heading-padding-block)
-    );
-    --_page-nav-heading-padding-inline: var(
-      --content-docs-page-nav-heading-padding-inline,
-      var(--_heading-padding-inline)
-    );
+    --_link-active-bg: var(--content-docs-link-active-bg, var(--theme-surface));
+    --_link-active-color: var(--content-docs-link-active-color, var(--theme-on-surface));
+    --_link-focus-outline: var(--content-docs-link-focus-outline-width, 0.2rem) solid
+      var(--content-docs-link-focus-outline-color, var(--theme-border-focus));
 
     container-type: inline-size;
     container-name: contentDocs;
 
     .content-docs-inner {
       display: grid;
+      grid-template-columns: minmax(0, 1fr);
       grid-template-areas:
         "docsNav"
         "docsPageNav"
@@ -208,20 +191,20 @@ const docsPageNavPanelName = computed(() => (isMobile.value ? panelGroupId : `${
         grid-template-areas:
           "docsNav docsPageNav"
           "docsContent docsPageNav";
-        gap: 1.6rem;
-        grid-template-columns: 1fr var(--content-docs-page-nav-column-width-tablet, 20rem);
+        grid-template-columns: minmax(0, 1fr) var(--content-docs-page-nav-column-width-tablet, 20rem);
         grid-template-rows: auto 1fr;
       }
 
       @container contentDocs (width >= 1024px) {
-        grid-template-areas: "docsNav docsContent  docsPageNav";
-        gap: 1.6rem;
-        grid-template-columns: var(--content-docs-nav-column-width, 23rem) 1fr var(--content-docs-page-nav-column-width, 22rem);
+        grid-template-areas: "docsNav docsContent docsPageNav";
+        grid-template-columns:
+          var(--content-docs-nav-column-width, 23rem) minmax(0, 1fr)
+          var(--content-docs-page-nav-column-width, 22rem);
       }
 
-      .docs-nav {
+      .content-docs-nav {
         grid-area: docsNav;
-        align-items: start;
+        min-inline-size: 0;
 
         @container contentDocs (width >= 1024px) {
           .expanding-panel-summary,
@@ -230,13 +213,16 @@ const docsPageNavPanelName = computed(() => (isMobile.value ? panelGroupId : `${
           }
         }
       }
-      .docs-content {
+
+      .content-docs-content {
         grid-area: docsContent;
-        align-items: start;
+        min-inline-size: 0;
+        overflow-wrap: break-word;
       }
-      .docs-page-nav {
+
+      .content-docs-page-nav {
         grid-area: docsPageNav;
-        align-items: start;
+        min-inline-size: 0;
 
         @container contentDocs (width >= 768px) {
           .expanding-panel-summary,
@@ -247,7 +233,13 @@ const docsPageNavPanelName = computed(() => (isMobile.value ? panelGroupId : `${
       }
     }
 
-    .docs-nav-heading {
+    .content-docs-nav-heading,
+    .content-docs-page-nav-heading {
+      min-inline-size: 0;
+      overflow-wrap: anywhere;
+    }
+
+    .content-docs-nav-heading {
       font-size: var(--content-docs-nav-heading-font-size, var(--_heading-font-size));
       font-weight: var(--content-docs-nav-heading-font-weight, var(--_heading-font-weight));
       color: var(--content-docs-nav-heading-color, var(--_heading-color));
@@ -256,21 +248,22 @@ const docsPageNavPanelName = computed(() => (isMobile.value ? panelGroupId : `${
       padding-block: var(--content-docs-nav-heading-padding-block, var(--_heading-padding-block));
       padding-inline: var(--content-docs-nav-heading-padding-inline, var(--_heading-padding-inline));
     }
-    .docs-page-nav-heading {
+
+    .content-docs-page-nav-heading {
       font-size: var(--content-docs-page-nav-heading-font-size, var(--_heading-font-size));
       font-weight: var(--content-docs-page-nav-heading-font-weight, var(--_heading-font-weight));
       color: var(--content-docs-page-nav-heading-color, var(--_heading-color));
       background-color: var(--content-docs-page-nav-heading-bg, var(--_heading-bg));
       margin: var(--content-docs-page-nav-heading-margin, var(--_heading-margin));
-      padding-block: var(--_page-nav-heading-padding-block);
-      padding-inline: var(--_page-nav-heading-padding-inline);
+      padding-block: var(--content-docs-page-nav-heading-padding-block, var(--_heading-padding-block));
+      padding-inline: var(--content-docs-page-nav-heading-padding-inline, var(--_heading-padding-inline));
     }
 
-    .docs-nav-list {
-      border-radius: var(--_panel-border-radius);
-      padding-block: var(--_panel-padding-block);
-      padding-inline: var(--_panel-padding-inline);
-      background-color: var(--content-docs-nav-panel-bg, var(--_panel-bg));
+    .content-docs-nav-list,
+    .content-docs-page-nav-list {
+      border-radius: var(--content-docs-panel-border-radius, 0.5rem);
+      padding-block: var(--content-docs-panel-padding-block, 0.8rem);
+      padding-inline: var(--content-docs-panel-padding-inline, 0.8rem);
 
       ul {
         list-style: none;
@@ -281,103 +274,84 @@ const docsPageNavPanelName = computed(() => (isMobile.value ? panelGroupId : `${
         gap: 0.4rem;
       }
     }
-    .docs-page-nav-list {
-      border-radius: var(--_panel-border-radius);
-      padding-block: var(--_panel-padding-block);
-      padding-inline: var(--_panel-padding-inline);
-      background-color: var(--content-docs-page-nav-panel-bg, var(--_panel-bg));
 
-      ul {
-        list-style: none;
-        margin: 0;
-        padding: 0;
-        display: flex;
-        flex-direction: column;
-        gap: 0.4rem;
-      }
+    .content-docs-nav-list {
+      background-color: var(--content-docs-nav-panel-bg, var(--_panel-bg));
+    }
+
+    .content-docs-page-nav-list {
+      background-color: var(--content-docs-page-nav-panel-bg, var(--_panel-bg));
     }
 
-    .docs-nav-link {
+    .content-docs-nav-link,
+    .content-docs-page-nav-link {
       display: grid;
-      grid-template-columns: var(--content-docs-link-icon-size, 1.6rem) 1fr;
+      grid-template-columns: var(--content-docs-link-icon-size, 1.6rem) minmax(0, 1fr);
       align-items: center;
       gap: var(--content-docs-link-icon-gap, 0.6rem);
-      border-radius: var(--_link-border-radius);
-      font-size: var(--_link-font-size);
-      padding-block: var(--_link-padding-block);
-      padding-inline: var(--_link-padding-inline);
-      margin-block: var(--_link-margin-block);
-      background-color: var(--_link-bg);
+      border-radius: var(--content-docs-link-border-radius, 0.4rem);
+      font-size: var(--content-docs-link-font-size, 1.4rem);
+      padding-block: var(--content-docs-link-padding-block, 0.6rem);
+      padding-inline: var(--content-docs-link-padding-inline, 0.8rem);
+      margin-block: var(--content-docs-link-margin-block, 0);
+      background-color: var(--content-docs-link-bg, transparent);
       text-decoration: none;
-      direction: var(--content-docs-nav-link-icon-order, ltr);
-      color: var(--content-docs-nav-link-color, var(--_link-color));
       transition:
         background-color var(--control-transition-duration, 200ms) var(--control-transition-ease, ease),
         color var(--control-transition-duration, 200ms) var(--control-transition-ease, ease);
 
       &:focus-visible {
-        outline: 0.2rem solid var(--theme-ring, currentcolor);
+        outline: var(--_link-focus-outline);
         outline-offset: -0.2rem;
       }
+    }
+
+    .content-docs-nav-link {
+      direction: var(--content-docs-nav-link-icon-order, ltr);
+      color: var(--content-docs-nav-link-color, var(--_link-color));
 
       &:hover {
         background-color: var(--content-docs-nav-link-hover-bg, var(--_link-hover-bg));
         color: var(--content-docs-nav-link-hover-color, var(--_link-hover-color));
       }
 
-      &.is-active {
+      &[aria-current="page"] {
         background-color: var(--content-docs-nav-link-active-bg, var(--_link-active-bg));
         color: var(--content-docs-nav-link-active-color, var(--_link-active-color));
         font-weight: 600;
       }
     }
-    .docs-page-nav-link {
-      display: grid;
-      grid-template-columns: var(--content-docs-link-icon-size, 1.6rem) 1fr;
-      align-items: center;
-      gap: var(--content-docs-link-icon-gap, 0.6rem);
-      border-radius: var(--_link-border-radius);
-      font-size: var(--_link-font-size);
-      padding-block: var(--_link-padding-block);
-      padding-inline: var(--_link-padding-inline);
-      margin-block: var(--_link-margin-block);
-      background-color: var(--_link-bg);
-      text-decoration: none;
+
+    .content-docs-page-nav-link {
       direction: var(--content-docs-page-nav-link-icon-order, ltr);
       color: var(--content-docs-page-nav-link-color, var(--_link-color));
-      transition:
-        background-color var(--control-transition-duration, 200ms) var(--control-transition-ease, ease),
-        color var(--control-transition-duration, 200ms) var(--control-transition-ease, ease);
-
-      &:focus-visible {
-        outline: 0.2rem solid var(--theme-ring, currentcolor);
-        outline-offset: -0.2rem;
-      }
 
       &:hover {
         background-color: var(--content-docs-page-nav-link-hover-bg, var(--_link-hover-bg));
         color: var(--content-docs-page-nav-link-hover-color, var(--_link-hover-color));
       }
 
-      &.is-active {
+      &[aria-current="page"] {
         background-color: var(--content-docs-page-nav-link-active-bg, var(--_link-active-bg));
         color: var(--content-docs-page-nav-link-active-color, var(--_link-active-color));
         font-weight: 600;
       }
     }
 
-    .docs-nav-link-icon,
-    .docs-page-nav-link-icon {
+    .content-docs-nav-link-icon,
+    .content-docs-page-nav-link-icon {
       grid-column: 1;
       direction: ltr;
-      flex-shrink: 0;
       font-size: var(--content-docs-link-icon-size, 1.6rem);
     }
 
-    .docs-nav-link-label,
-    .docs-page-nav-link-label {
+    .content-docs-nav-link-label,
+    .content-docs-page-nav-link-label {
       grid-column: 2;
-      direction: ltr;
+      min-inline-size: 0;
+      overflow-wrap: anywhere;
+      unicode-bidi: plaintext;
+      text-align: start;
     }
   }
 }