Applies switch compontent

docs/_docset.yml

@@ -92,6 +92,7 @@ toc:
       - file: headings.md
       - file: admonitions.md
       - file: applies.md
+      - file: applies-switch.md
       - file: automated_settings.md
       - file: code.md
       - file: comments.md
@@ -156,4 +157,4 @@ toc:
           - file: bar.md
           - folder: baz
             children:
-              - file: qux.md
+              - file: qux.md

docs/syntax/applies-switch.md

@@ -0,0 +1,147 @@
+# Applies switch
+
+The applies-switch directive creates tabbed content where each tab displays an applies_to badge instead of a text title. This is useful for showing content that varies by deployment type, version, or other applicability criteria.
+
+## Basic usage
+
+::::::{tab-set}
+:::::{tab-item} Output
+
+::::{applies-switch}
+
+:::{applies-item} stack:
+Content for Stack
+:::
+
+:::{applies-item} serverless:
+Content for Serverless
+:::
+
+::::
+
+:::::
+:::::{tab-item} Markdown
+
+```markdown
+::::{applies-switch}
+
+:::{applies-item} stack:
+Content for Stack
+:::
+
+:::{applies-item} serverless:
+Content for Serverless
+:::
+
+::::
+```
+:::::
+::::::
+
+## Multiple `applies_to` definitions
+
+You can specify multiple `applies_to` definitions in a single `applies-item` using YAML object notation with curly braces `{}`.
+This is useful when content applies to multiple deployment types or versions simultaneously.
+
+::::::{tab-set}
+:::::{tab-item} Output
+
+::::{applies-switch}
+
+:::{applies-item} { ece:, ess: }
+Content for ECE and ECH
+:::
+
+:::{applies-item} serverless:
+Content for Serverless
+:::
+
+::::
+
+:::::
+:::::{tab-item} Markdown
+
+```markdown
+::::{applies-switch}
+
+:::{applies-item} { ece:, ess: }
+Content for ECE and ECH
+:::
+
+:::{applies-item} serverless:
+Content for Serverless
+:::
+
+::::
+```
+:::::
+::::::
+
+## Automatic grouping
+
+All applies switches on a page automatically sync together. When you select an applies_to definition in one switch, all other switches will switch to the same applies_to definition.
+
+The format of the applies_to definition doesn't matter - `stack: preview 9.1`, `{ "stack": "preview 9.1" }`, and `{ stack: "preview 9.1" }` all identify the same content and will sync together.
+
+In the following example, both switch sets are automatically grouped and will stay in sync.
+
+::::::{tab-set}
+:::::{tab-item} Output
+
+::::{applies-switch}
+:::{applies-item} { "stack": "preview 9.0" }
+Content for 9.0 version
+:::
+:::{applies-item} { "stack": "ga 9.1" }
+Content for 9.1 version
+:::
+::::
+
+::::{applies-switch}
+:::{applies-item} stack: preview 9.0
+Other content for 9.0 version
+:::
+:::{applies-item} stack: ga 9.1
+Other content for 9.1 version
+:::
+::::
+
+:::::
+:::::{tab-item} Markdown
+
+```markdown
+::::{applies-switch}
+:::{applies-item} { "stack": "preview 9.0" }
+Content for 9.0 version
+:::
+:::{applies-item} { "stack": "ga 9.1" }
+Content for 9.1 version
+:::
+::::
+
+::::{applies-switch}
+:::{applies-item} stack: preview 9.0
+Other content for 9.0 version
+:::
+:::{applies-item} stack: ga 9.1
+Other content for 9.1 version
+:::
+::::
+```
+:::::
+::::::
+
+## Supported `applies_to` definitions
+
+The `applies-item` directive accepts any valid applies_to definition that would work with the `{applies_to}` role.
+
+See the [](applies.md) page for more details on valid `applies_to` definitions.
+
+## When to use
+
+Use applies switches when:
+
+- Content varies significantly by deployment type, version, or other applicability criteria
+- You want to show applies_to badges as tab titles instead of text
+- You need to group related content that differs by applicability
+- You want to provide a clear visual indication of what each content section applies to

src/Elastic.Documentation.Site/Assets/applies-switch.ts

@@ -0,0 +1,88 @@
+// TODO: refactor to typescript. this was copied from the tabs implementation
+
+// @ts-check
+
+// Extra JS capability for selected applies switches to be synced
+// The selection is stored in local storage so that it persists across page loads.
+
+const as_id_to_elements = {}
+const storageKeyPrefix = 'sphinx-design-applies-switch-id-'
+
+function create_key(el: HTMLElement) {
+    const syncId = el.getAttribute('data-sync-id')
+    const syncGroup = el.getAttribute('data-sync-group')
+    if (!syncId || !syncGroup) return null
+    return [syncGroup, syncId, syncGroup + '--' + syncId]
+}
+
+/**
+ * Initialize the applies switch selection.
+ *
+ */
+function ready() {
+    // Find all applies switches with sync data
+
+    const groups = []
+
+    document.querySelectorAll('.applies-switch-label').forEach((label) => {
+        if (label instanceof HTMLElement) {
+            const data = create_key(label)
+            if (data) {
+                const [group, id, key] = data
+
+                // add click event listener
+                label.onclick = onAppliesSwitchLabelClick
+
+                // store map of key to elements
+                if (!as_id_to_elements[key]) {
+                    as_id_to_elements[key] = []
+                }
+                as_id_to_elements[key].push(label)
+
+                if (groups.indexOf(group) === -1) {
+                    groups.push(group)
+                    // Check if a specific switch has been selected via URL parameter
+                    const switchParam = new URLSearchParams(
+                        window.location.search
+                    ).get(group)
+                    if (switchParam) {
+                        window.sessionStorage.setItem(
+                            storageKeyPrefix + group,
+                            switchParam
+                        )
+                    }
+                }
+
+                // Check is a specific switch has been selected previously
+                const previousId = window.sessionStorage.getItem(
+                    storageKeyPrefix + group
+                )
+                if (previousId === id) {
+                    ;(
+                        label.previousElementSibling as HTMLInputElement
+                    ).checked = true
+                }
+            }
+        }
+    })
+}
+
+/**
+ *  Activate other switches with the same sync id.
+ *
+ * @this {HTMLElement} - The element that was clicked.
+ */
+function onAppliesSwitchLabelClick() {
+    const data = create_key(this)
+    if (!data) return
+    const [group, id, key] = data
+    for (const label of as_id_to_elements[key]) {
+        if (label === this) continue
+        label.previousElementSibling.checked = true
+    }
+    window.sessionStorage.setItem(storageKeyPrefix + group, id)
+}
+
+export function initAppliesSwitch() {
+    ready()
+}

src/Elastic.Documentation.Site/Assets/main.ts

@@ -1,3 +1,4 @@
+import { initAppliesSwitch } from './applies-switch'
 import { initCopyButton } from './copybutton'
 import { initHighlight } from './hljs'
 import { initImageCarousel } from './image-carousel'
@@ -21,6 +22,7 @@ document.addEventListener('htmx:load', function (event) {
     initHighlight()
     initCopyButton()
     initTabs()
+    initAppliesSwitch()
 
     // We do this so that the navigation is not initialized twice
     if (isLazyLoadNavigationEnabled) {

src/Elastic.Documentation.Site/Assets/markdown/applies-switch.css

@@ -0,0 +1,64 @@
+@layer components {
+	.applies-switch {
+		@apply relative mt-4 flex flex-wrap overflow-hidden;
+
+		.applies-switch-label {
+			@apply text-ink-light border-grey-20 z-20 -mb-[1px] flex cursor-pointer items-center border-1 px-3 py-2;
+			&:not(:nth-of-type(1)) {
+				margin-left: -1px;
+			}
+
+			&:hover {
+				@apply bg-grey-10 border-b-1 border-b-black text-black;
+			}
+		}
+
+		.applies-item {
+			@apply cursor-pointer text-inherit;
+
+			&:hover {
+				@apply text-inherit;
+			}
+			.applicable-info {
+				@apply cursor-pointer border-none bg-transparent p-0;
+
+				&:not(:last-child):after {
+					content: ',';
+				}
+			}
+			.applicable-name,
+			.applicable-meta {
+				@apply text-base;
+			}
+		}
+
+		.applies-switch-input {
+			@apply absolute opacity-0;
+		}
+
+		.applies-switch-content {
+			@apply border-grey-20 z-0 order-99 hidden w-full border-1 px-6 pt-2 pb-6;
+		}
+
+		.applies-switch-input:checked
+			+ .applies-switch-label
+			+ .applies-switch-content {
+			@apply block;
+		}
+
+		.applies-switch-input:checked + .applies-switch-label,
+		.applies-switch-label:active {
+			@apply border-b-blue-elastic text-blue-elastic border-b-1;
+		}
+
+		.applies-switch-input:focus-visible + .applies-switch-label {
+			outline: var(--outline-size) var(--outline-style)
+				var(--outline-color);
+			outline-offset: var(--outline-offset, var(--outline-size));
+		}
+
+		.applies-switch-fallback {
+			@apply text-sm font-medium;
+		}
+	}
+}

src/Elastic.Documentation.Site/Assets/open-details-with-anchor.ts

@@ -1,6 +1,6 @@
 import { UAParser } from 'ua-parser-js'
 
-const { getBrowser } = new UAParser()
+const { browser } = UAParser()
 
 // This is a fix for anchors in details elements in non-Chrome browsers.
 export function openDetailsWithAnchor() {
@@ -9,7 +9,6 @@ export function openDetailsWithAnchor() {
         if (target) {
             const closestDetails = target.closest('details')
             if (closestDetails) {
-                const browser = getBrowser()
                 if (browser.name !== 'Chrome') {
                     closestDetails.open = true
                     target.scrollIntoView({

src/Elastic.Documentation.Site/Assets/styles.css

@@ -7,6 +7,7 @@
 @import './markdown/typography.css';
 @import './markdown/list.css';
 @import './markdown/tabs.css';
+@import './markdown/applies-switch.css';
 @import './markdown/code.css';
 @import './markdown/icons.css';
 @import './markdown/kbd.css';

src/Elastic.Markdown/Elastic.Markdown.csproj

@@ -43,4 +43,9 @@
     <EmbeddedResource Include="Myst\Roles\Icons\svgs\*.svg" />
   </ItemGroup>
 
+  <ItemGroup>
+    <UpToDateCheckInput Remove="Myst\Directives\AppliesSwitch\AppliesItemView.cshtml" />
+    <UpToDateCheckInput Remove="Myst\Directives\AppliesSwitch\AppliesSwitchView.cshtml" />
+  </ItemGroup>
+
 </Project>

src/Elastic.Markdown/Myst/Components/ApplicableToComponent.cshtml

@@ -2,7 +2,7 @@
 
 @foreach (var item in Model.GetApplicabilityItems())
 {
-		<span class="applicable-info" data-tippy-content="@(new HtmlString(item.RenderData.TooltipText))">
+		<span class="applicable-info" data-tippy-content="@(new HtmlString(Model.ShowTooltip ? item.RenderData.TooltipText : string.Empty))">
 			<span class="applicable-name">@item.Key</span>
 
 			@if (!string.IsNullOrEmpty(item.Key) && (item.RenderData.ShowLifecycleName || item.RenderData.ShowVersion || !string.IsNullOrEmpty(item.RenderData.BadgeLifecycleText)))

src/Elastic.Markdown/Myst/Components/ApplicableToViewModel.cs

@@ -13,6 +13,8 @@ public class ApplicableToViewModel
 	private readonly ApplicabilityRenderer _applicabilityRenderer = new();
 
 	public required bool Inline { get; init; }
+
+	public bool ShowTooltip { get; init; } = true;
 	public required ApplicableTo AppliesTo { get; init; }
 	public required VersionsConfiguration VersionsConfig { get; init; }
 
@@ -162,4 +164,3 @@ private IEnumerable<ApplicabilityItem> CombineItemsByKey(List<ApplicabilityItem>
 
 
 }
-