Update styling in List and Tables for platform-architecture-control-plane-data-plane-separation article

Author: webstackdev

_TODO.md

@@ -226,8 +226,6 @@ https://mermaid.js.org/config/directives.html
 
 - Improve `<abbr>` styling: https://codepen.io/ire/pen/NoqWpm
 
-- Moving the scroll bar up quickly with the mouse seems to make the header logic break - the Switcher component and Breadcrumbs are hidden under the header
-
 ## List Component
 
 - Task list checked variant Markdown in dark theme is awkward, it has a dark shadow
@@ -240,6 +238,8 @@ https://mermaid.js.org/config/directives.html
 
 - Need to improve the "squish" animation where the header reduces in size on scroll down, and returns to full size on scroll up. Maybe reduce and expand the text and search / themepicker / hamburger menu sizes in place, and then slide them horizontally.
 
+- Moving the scroll bar up quickly with the mouse seems to make the header logic break - the Switcher component and Breadcrumbs are hidden under the header
+
 ## Content Issues
 
 - Need an article on OpenStack
@@ -252,7 +252,7 @@ https://mermaid.js.org/config/directives.html
 
 - Add a "Preview Special" item to our Download CTA that lets the user know the Deep Dive content can be previewed in HTML format, and offer a switch to it.
 
-- How can we handle footnotes in List components? src/content/articles/kubernetes-multi-cluster-fleet-management-configuration/pdf.mdx line 80
+- Tags should break more evenly across two lines when there's a lot of them, instead of forcing the author name and date to break across two lines: platform-engineering-metrics-lead-time-developer-friction/index.mdx
 
 - Need to update Case Studies with lists and tables too
 

src/components/List/ListItem.astro

@@ -0,0 +1,9 @@
+---
+export type Props = {
+  lead?: string
+}
+
+const { lead } = Astro.props as Props
+---
+
+<wsb-list-item {...(lead ? { 'data-lead': lead } : {})}><slot /></wsb-list-item>

src/components/List/__fixtures__/mixedApi.fixture.astro

@@ -0,0 +1,16 @@
+---
+import List from '@components/List/index.astro'
+import ListItem from '@components/List/ListItem.astro'
+---
+
+<List
+  variant="chevron-list"
+  items={[
+    {
+      lead: 'Prop item',
+      text: 'This should fail because slot items are also provided.',
+    },
+  ]}
+>
+  <ListItem lead="Slot item">This should never render.</ListItem>
+</List>

src/components/List/__fixtures__/richItems.fixture.astro

@@ -0,0 +1,13 @@
+---
+import List from '@components/List/index.astro'
+import ListItem from '@components/List/ListItem.astro'
+---
+
+<List variant="chevron-list">
+  <ListItem lead="Network isolation">
+    Separate VPCs<sup data-footnote-ref="slot-demo">1</sup> can provide stronger boundaries.
+  </ListItem>
+  <ListItem lead="Compute isolation">
+    Dedicated node pools reduce resource contention.
+  </ListItem>
+</List>

src/components/List/__tests__/index.spec.ts

@@ -1,6 +1,8 @@
 import { beforeEach, describe, expect, test } from 'vitest'
 import { experimental_AstroContainer as AstroContainer } from 'astro/container'
 import { withJsdomEnvironment } from '@test/unit/helpers/litRuntime'
+import MixedApiFixture from '@components/List/__fixtures__/mixedApi.fixture.astro'
+import RichItemsFixture from '@components/List/__fixtures__/richItems.fixture.astro'
 
 describe('List (Astro)', () => {
   let container: AstroContainer
@@ -232,4 +234,25 @@ describe('List (Astro)', () => {
       expect(title?.textContent).toContain('Resource metrics')
     })
   })
+
+  test('renders rich ListItem children through the existing layout item API', async () => {
+    const renderedHtml = await container.renderToString(RichItemsFixture)
+
+    await withJsdomEnvironment(async ({ window }) => {
+      window.document.body.innerHTML = renderedHtml
+
+      const items = Array.from(window.document.querySelectorAll('ul > li'))
+      expect(items).toHaveLength(2)
+      expect(items[0]?.querySelector('em')?.textContent).toContain('Network isolation')
+      expect(items[0]?.querySelector('sup[data-footnote-ref="slot-demo"]')?.textContent).toBe('1')
+      expect(items[1]?.textContent).toContain('Dedicated node pools reduce resource contention.')
+      expect(window.document.querySelector('wsb-list-item')).toBeNull()
+    })
+  })
+
+  test('throws a BuildError when items and ListItem children are both provided', async () => {
+    await expect(container.renderToString(MixedApiFixture)).rejects.toThrow(
+      'List: received both the `items` prop and ListItem children. Use one API or the other.'
+    )
+  })
 })

src/components/List/index.astro

@@ -1,4 +1,5 @@
 ---
+import { BuildError } from '@lib/errors/BuildError'
 import AccentBorderLeftList from '@components/List/layouts/AccentBorderLeftList.astro'
 import BadgeList from '@components/List/layouts/BadgeList.astro'
 import CardGridList from '@components/List/layouts/CardGridList.astro'
@@ -14,9 +15,10 @@ import ThreeColumnIconList from '@components/List/layouts/ThreeColumnIconList.as
 import TwoColumnCheckIconsList from '@components/List/layouts/TwoColumnCheckIconsList.astro'
 import TwoColumnIconList from '@components/List/layouts/TwoColumnIconList.astro'
 import ZebraList from '@components/List/layouts/ZebraList.astro'
+import { getListItemsFromSlotMarkup } from '@components/List/server/slotItems'
 
 export type Props = {
-  items: {
+  items?: {
     title?: string
     lead?: string
     text: string
@@ -45,14 +47,33 @@ export type Props = {
   style?: Record<string, unknown>
 }
 
-const { items, size, color, startNumber, variant = 'default', classes, style } = Astro.props
+const { items, size, color, startNumber, variant = 'default', classes, style } = Astro.props as Props
+const hasItemsProp = Object.prototype.hasOwnProperty.call(Astro.props, 'items')
+const hasDefaultSlot = Astro.slots.has('default')
+
+if (hasItemsProp && hasDefaultSlot) {
+  throw new BuildError(
+    'List: received both the `items` prop and ListItem children. Use one API or the other.',
+    {
+      phase: 'compilation',
+      filePath: 'src/components/List/index.astro',
+      tool: 'list',
+    }
+  )
+}
+
+const slotMarkup = hasDefaultSlot ? await Astro.slots.render('default') : ''
+const normalizedItems = hasDefaultSlot
+  ? getListItemsFromSlotMarkup(slotMarkup, variant)
+  : (items ?? [])
+
 const classesProps = classes ? { classes } : {}
 const numericSizeProps = typeof size === 'number' ? { size } : {}
 const chatBubbleSizeProps = typeof size === 'string' ? { size } : {}
 const colorProps = typeof color === 'string' && color.trim().length > 0 ? { color } : {}
 const startNumberProps = typeof startNumber === 'number' ? { startNumber } : {}
 const styleProps = style ? { style } : {}
-const itemsWithColor = items as Array<{
+const itemsWithColor = normalizedItems as Array<{
   title?: string
   lead?: string
   text: string
@@ -61,32 +82,32 @@ const itemsWithColor = items as Array<{
   inverseColor?: string
   bgColor?: string
 }>
-const itemsWithIconAndColor = items as Array<{
+const itemsWithIconAndColor = normalizedItems as Array<{
   text: string
   icon: string
   color: string
   inverseColor?: string
   bgColor?: string
 }>
-const plainIconItems = items.filter((item): item is Props['items'][number] & { icon: string } => {
+const plainIconItems = normalizedItems.filter((item): item is NonNullable<Props['items']>[number] & { icon: string } => {
   return typeof item.icon === 'string' && item.icon.trim().length > 0
 })
 ---
 
 <div class:list={[classes?.wrapper ? classes.wrapper : 'mb-6']}>
-  {variant === 'accent-border-left-list' && <AccentBorderLeftList items={items} {...classesProps} {...styleProps} />}
-  {variant === 'badge-list' && <BadgeList items={items} {...classesProps} {...styleProps} />}
-  {variant === 'card-grid-list' && <CardGridList items={items} {...classesProps} {...styleProps} />}
-  {variant === 'chat-bubbles' && <ChatBubbles items={items} {...classesProps} {...chatBubbleSizeProps} />}
-  {variant === 'check-icons-list' && <CheckIconsList items={items} {...classesProps} {...styleProps} />}
-  {variant === 'chevron-list' && <ChevronList items={items} {...classesProps} {...styleProps} />}
+  {variant === 'accent-border-left-list' && <AccentBorderLeftList items={normalizedItems} {...classesProps} {...styleProps} />}
+  {variant === 'badge-list' && <BadgeList items={normalizedItems} {...classesProps} {...styleProps} />}
+  {variant === 'card-grid-list' && <CardGridList items={normalizedItems} {...classesProps} {...styleProps} />}
+  {variant === 'chat-bubbles' && <ChatBubbles items={normalizedItems} {...classesProps} {...chatBubbleSizeProps} />}
+  {variant === 'check-icons-list' && <CheckIconsList items={normalizedItems} {...classesProps} {...styleProps} />}
+  {variant === 'chevron-list' && <ChevronList items={normalizedItems} {...classesProps} {...styleProps} />}
   {variant === 'colored-marker-list' && <ColoredMarkerList items={itemsWithColor} {...classesProps} {...numericSizeProps} {...styleProps} />}
-  {variant === 'numbered-with-background-list' && <NumberedWithBackgroundList items={items} {...classesProps} {...colorProps} {...startNumberProps} {...styleProps} />}
+  {variant === 'numbered-with-background-list' && <NumberedWithBackgroundList items={normalizedItems} {...classesProps} {...colorProps} {...startNumberProps} {...styleProps} />}
   {variant === 'plain-icon-list' && <PlainIconList items={plainIconItems} {...classesProps} {...numericSizeProps} {...styleProps} />}
-  {variant === 'side-by-side-list' && <SideBySideList items={items} {...classesProps} {...styleProps} />}
-  {variant === 'timeline-list' && <TimelineList items={items} {...classesProps} {...styleProps} />}
-  {variant === 'two-column-check-icons-list' && <TwoColumnCheckIconsList items={items} {...classesProps} {...numericSizeProps} {...styleProps} />}
+  {variant === 'side-by-side-list' && <SideBySideList items={normalizedItems} {...classesProps} {...styleProps} />}
+  {variant === 'timeline-list' && <TimelineList items={normalizedItems} {...classesProps} {...styleProps} />}
+  {variant === 'two-column-check-icons-list' && <TwoColumnCheckIconsList items={normalizedItems} {...classesProps} {...numericSizeProps} {...styleProps} />}
   {variant === 'two-column-icon-list' && <TwoColumnIconList items={itemsWithIconAndColor} {...classesProps} {...numericSizeProps} {...styleProps} />}
   {variant === 'three-column-icon-list' && <ThreeColumnIconList items={itemsWithIconAndColor} {...classesProps} {...numericSizeProps} {...styleProps} />}
-  {variant === 'zebra-list' && <ZebraList items={items} {...classesProps} {...styleProps} />}
+  {variant === 'zebra-list' && <ZebraList items={normalizedItems} {...classesProps} {...styleProps} />}
 </div>

src/components/List/server/slotItems.ts

@@ -0,0 +1,65 @@
+import { JSDOM } from 'jsdom'
+import { BuildError } from '@lib/errors/BuildError'
+import type { Props as ListProps } from '@components/List/index.astro'
+
+type ListItemShape = NonNullable<ListProps['items']>[number]
+
+const unsupportedRichSlotVariants = new Set([
+  'plain-icon-list',
+  'two-column-icon-list',
+  'three-column-icon-list',
+])
+
+const buildErrorContext = {
+  phase: 'compilation',
+  filePath: 'src/components/List/index.astro',
+  tool: 'list',
+} as const
+
+/**
+ * Parse rendered ListItem slot markup into the existing List items shape.
+ */
+export function getListItemsFromSlotMarkup(markup: string, variant: string): ListItemShape[] {
+  if (unsupportedRichSlotVariants.has(variant)) {
+    throw new BuildError(
+      `List: rich ListItem children are not supported for the \`${variant}\` variant. Use the \`items\` prop for icon-based list variants.`,
+      buildErrorContext
+    )
+  }
+
+  const document = new JSDOM(`<!doctype html><html><body>${markup}</body></html>`).window.document
+  const meaningfulNodes = Array.from(document.body.childNodes).filter((node) => {
+    if (node.nodeType === node.TEXT_NODE) {
+      return node.textContent?.trim().length
+    }
+
+    return node.nodeType === node.ELEMENT_NODE
+  })
+
+  if (meaningfulNodes.length === 0) {
+    throw new BuildError(
+      'List: expected one or more ListItem children when using rich slot content.',
+      buildErrorContext
+    )
+  }
+
+  const invalidNode = meaningfulNodes.find((node) => {
+    return node.nodeType !== node.ELEMENT_NODE || (node as Element).tagName.toLowerCase() !== 'wsb-list-item'
+  })
+
+  if (invalidNode) {
+    throw new BuildError(
+      'List: rich slot content must contain only ListItem children. Use either the `items` prop or `<ListItem>` children.',
+      buildErrorContext
+    )
+  }
+
+  return meaningfulNodes.map((node) => {
+    const element = node as Element
+
+    return {
+      lead: element.getAttribute('data-lead') ?? undefined,
+      text: element.innerHTML.trim(),
+    }
+  })
+}

src/content/articles/kubernetes-multi-cluster-fleet-management-configuration/pdf.mdx

@@ -78,27 +78,32 @@ Organizations arrive at multi-cluster architectures for different reasons, and t
 
 Every multi-cluster strategy sits somewhere on a spectrum from "all clusters are identical" to "each cluster is independent." Neither extreme works well in practice.
 
-<List
-  variant="numbered-with-background-list"
-  items={[
-    {
-      lead: "Fully consistent",
-      text: "means all clusters get exactly the same configuration. This is simple to reason about and guarantees reproducibility, but it's inflexible. You end up over-provisioning dev and staging to match production, or you can't tune production for its actual load patterns. This approach only works for small fleets with simple applications.",
-    },
-    {
-      lead: "Layered configuration",
-      text: `uses a base configuration with environment-specific overrides. This is the sweet spot for most organizations. You define what's shared (security policies, monitoring stack, core add-ons) and what varies (replica counts, resource limits, feature flags). Kustomize overlays and Helm values files are the typical implementation. The risk is "override explosion"—so many layers of patches that nobody can trace what a cluster actually runs.`,
-    },
-    {
-      lead: "Policy-governed",
-      text: "configuration sets guardrails rather than identical configs. Teams can customize their clusters within bounds enforced by OPA/Gatekeeper[^opa-gatekeeper] or Kyverno[^kyverno]. This enables innovation and team autonomy, but drift happens within the policy bounds. Debugging becomes harder because clusters are intentionally different.",
-    },
-    {
-      lead: "Fully flexible",
-      text: "means each cluster is independent, with its own GitOps repo and configuration. Maximum autonomy, maximum chaos. Security risks emerge when teams deviate from baselines. This only works with truly autonomous teams who don't need cross-cluster consistency.",
-    },
-  ]}
-/>
+<List variant="numbered-with-background-list">
+  <ListItem lead="Fully consistent">
+    Means all clusters get exactly the same configuration. This is simple to reason about and guarantees
+    reproducibility, but it's inflexible. You end up over-provisioning dev and staging to match
+    production, or you can't tune production for its actual load patterns. This approach only works for
+    small fleets with simple applications.
+  </ListItem>
+  <ListItem lead="Layered configuration">
+    Uses a base configuration with environment-specific overrides. This is the sweet spot for most
+    organizations. You define what's shared (security policies, monitoring stack, core add-ons) and
+    what varies (replica counts, resource limits, feature flags). Kustomize overlays and Helm values
+    files are the typical implementation. The risk is "override explosion"—so many layers of patches
+    that nobody can trace what a cluster actually runs.
+  </ListItem>
+  <ListItem lead="Policy-governed">
+    Configuration sets guardrails rather than identical configs. Teams can customize their clusters
+    within bounds enforced by OPA/Gatekeeper[^opa-gatekeeper] or Kyverno[^kyverno]. This enables
+    innovation and team autonomy, but drift happens within the policy bounds. Debugging becomes harder
+    because clusters are intentionally different.
+  </ListItem>
+  <ListItem lead="Fully flexible">
+    Means each cluster is independent, with its own GitOps repo and configuration. Maximum autonomy,
+    maximum chaos. Security risks emerge when teams deviate from baselines. This only works with truly
+    autonomous teams who don't need cross-cluster consistency.
+  </ListItem>
+</List>
 
 [^opa-gatekeeper]: OPA (Open Policy Agent) is an open-source, general-purpose policy engine that unifies policy enforcement across the stack, using a declarative language called Rego to define complex rules. Gatekeeper is a specialized project that integrates OPA into Kubernetes — it acts as a validating admission controller, intercepting requests to the Kubernetes API and checking them against OPA policies before resources are created or modified.