@santi020k/lumen-astro 4.0.0 → 4.3.0

package/README.md

@@ -103,12 +103,15 @@ The stylesheet defaults `--ui-font` to `"Montserrat", "Avenir Next", "Segoe UI",
 It declares the family stack but does not bundle or load font files. Load Montserrat once through
 your preferred delivery path, or override `--ui-font` in application CSS.
 
-With Tailwind, keep the Lumen import in the same shared CSS entry:
+With Tailwind CSS v4, keep the Lumen imports in the same shared CSS entry. The optional
+`tailwind.css` bridge (Lumen 4.3+) maps semantic colors to utilities such as `bg-surface` and
+`text-ink`, including nested themes. See the [Tailwind guide](https://lumen.santi020k.com/docs/web/tailwind):
 
 ```css
 @import "@santi020k/lumen-astro/layers.css";
 @import "tailwindcss";
 @import "@santi020k/lumen-astro/styles.css";
+@import "@santi020k/lumen-astro/tailwind.css";
 ```
 
 ```astro
@@ -161,6 +164,9 @@ Set `data-lumen-preset="studio"` and an optional `data-lumen-scheme="light|dark"
 
 ## Compound interactive components
 
+DatePicker, Calendar, and InputOTP enhancement skips markup marked `data-ui-owner`, such as the
+matching React controls, so those islands keep their ids, labels, and state before and after hydration.
+
 Popover, dropdown menu, tabs, and tooltip parts expose the DOM and ARIA contracts consumed by the
 shared progressive-enhancement runtime. Prefer these parts over recreating roles and `data-ui-*`
 attributes by hand.
@@ -321,6 +327,9 @@ import { Button, Icon } from '@santi020k/lumen-astro'
 
 `Anchor` accepts heading `depth`, `index`, and `description` metadata plus an `activationOffset`.
 Its current link stays synchronized on click and scroll, including at the end of the document.
+The activation line uses the greater of `activationOffset` and the root `scroll-padding-top` plus
+each heading's `scroll-margin-top`, with a one CSS pixel rounding tolerance. Styles are read live so
+text resizing and responsive headers keep native fragment links and the current section aligned.
 `ScrollProgress` derives reading progress from the document and pins the indicator to the top or
 bottom viewport edge. Both use the single root `UIPrimitives` runtime.
 
@@ -336,6 +345,24 @@ import { Anchor, CopyButton, ScrollProgress } from '@santi020k/lumen-astro'
 ]} />
 ```
 
+Enhanced `DatePicker` controls mirror native input `aria-invalid`, `aria-describedby`, and
+`aria-errormessage` attributes onto the visible trigger, including later attribute changes.
+Valid updates and uncanceled resets clear generated validation feedback while preserving explicit
+application errors.
+
+`Skeleton` accepts `shape` (`rectangle`, `text`, `circle`), `width`, `height`, and `animation`
+(`shimmer`, `pulse`, `none`). Numeric sizes are pixels; CSS lengths, percentages, and math or
+custom-property expressions also work. Explicit styles take precedence. Empty placeholders default
+to 1rem high, while text and element content can grow naturally. Reduced motion stops animations.
+Unnamed Skeletons and Spinners are decorative. Give a standalone indicator an accessible name, or
+wrap a group in one named status region with `VisuallyHidden` text.
+
+```astro
+<Skeleton shape="circle" width={40} />
+<Skeleton shape="text" width="80%" />
+<Skeleton animation="pulse" height={8} width="60%" />
+```
+
 `Progress` can be updated after hydration by dispatching `ui:progress-change` from its root with
 `{ value, max? }`. Use `CopyButton` to copy arbitrary text or a referenced element without giving
 non-code content `Code` semantics.

package/components/ListBox.astro

@@ -63,7 +63,8 @@ if (Array.isArray(value)) initialValues = value
 else if (value !== undefined) initialValues = [value]
 
 const selectedValues = new Set(initialValues)
-const controlId = id ?? `ui-list-box-${name ?? 'field'}`
+// Named lists keep their stable id; unnamed lists need a unique one so labels and options never collide.
+const controlId = id ?? (name ? `ui-list-box-${name}` : `ui-list-box-${Math.random().toString(36).slice(2)}`)
 const listId = `${controlId}-list`
 const { classList, passthrough } = resolveLumenAstroProps(rest, ['ui-list-box'], classProp, className)
 ---

package/components/Progress.astro

@@ -1,7 +1,7 @@
 ---
 import type { HTMLAttributes } from 'astro/types'
 
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+import { normalizeLumenProgress, resolveLumenAstroProps } from '@santi020k/lumen-core'
 
 interface Props extends HTMLAttributes<'div'> {
   class?: string | null
@@ -11,9 +11,7 @@ interface Props extends HTMLAttributes<'div'> {
 }
 
 const { class: classProp = '', className = '', max = 100, value = 0, ...rest } = Astro.props
-const safeMax = max > 0 ? max : 100
-const safeValue = Math.min(safeMax, Math.max(0, value))
-const percentage = (safeValue / safeMax) * 100
+const { max: safeMax, percentage, value: safeValue } = normalizeLumenProgress(max, value)
 
 const { classList, passthrough } = resolveLumenAstroProps(rest, [
   'ui-progress'

package/components/Skeleton.astro

@@ -1,36 +1,77 @@
 ---
 import type { HTMLAttributes } from 'astro/types'
 
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+import {
+  type LumenSkeletonAnimation,
+  type LumenSkeletonShape,
+  type LumenSkeletonSize,
+  resolveLumenAstroProps,
+  resolveLumenLoadingSemantics,
+  resolveLumenSkeletonAnimation,
+  resolveLumenSkeletonShape,
+  resolveLumenSkeletonSize
+} from '@santi020k/lumen-core'
 
 interface Props extends HTMLAttributes<'div'> {
+  /** `shimmer` (default) keeps the existing sweep; `pulse` fades; `none` is static. */
+  animation?: LumenSkeletonAnimation
   class?: string | null
   className?: string
+  /** Pixels for numbers, or a CSS length such as `0.75rem` or `60%`. */
+  height?: LumenSkeletonSize
+  shape?: LumenSkeletonShape
+  width?: LumenSkeletonSize
 }
 
 const {
+  animation,
   'aria-hidden': ariaHidden,
   'aria-label': ariaLabel,
   'aria-labelledby': ariaLabelledby,
   class: classProp = '',
   className = '',
+  height,
   role,
+  shape,
+  style,
+  width,
   ...rest
 } = Astro.props
 
-const isAccessible = Boolean(ariaLabel || ariaLabelledby)
+const semantics = resolveLumenLoadingSemantics({ ariaHidden, ariaLabel, ariaLabelledby, role })
+const resolvedShape = resolveLumenSkeletonShape(shape)
+const resolvedAnimation = resolveLumenSkeletonAnimation(animation)
+const sizeVariables: Record<string, string> = {}
+const resolvedHeight = resolveLumenSkeletonSize(height)
+const resolvedWidth = resolveLumenSkeletonSize(width)
+
+if (resolvedHeight) sizeVariables['--ui-skeleton-height'] = resolvedHeight
+
+if (resolvedWidth) sizeVariables['--ui-skeleton-width'] = resolvedWidth
+
+// Consumer styles follow the size variables so explicit declarations still win.
+const skeletonStyle = typeof style === 'object' && style !== null ?
+  { ...sizeVariables, ...style } :
+  [
+    ...Object.entries(sizeVariables).map(([name, value]) => `${name}:${value}`),
+    typeof style === 'string' ? style : ''
+  ].filter(Boolean).join(';')
 
 const { classList, passthrough } = resolveLumenAstroProps(rest, [
-  'ui-skeleton'
+  'ui-skeleton',
+  resolvedShape === 'rectangle' ? '' : `ui-skeleton--${resolvedShape}`,
+  resolvedAnimation === 'pulse' ? 'ui-skeleton--pulse' : '',
+  resolvedAnimation === 'none' ? 'ui-skeleton--static' : ''
 ], classProp, className)
 ---
 
 <div
-  aria-hidden={ariaHidden ?? (isAccessible ? undefined : 'true')}
+  aria-hidden={ariaHidden ?? semantics.ariaHidden}
   aria-label={ariaLabel}
   aria-labelledby={ariaLabelledby}
   class:list={classList}
-  role={role ?? (isAccessible ? 'status' : undefined)}
+  role={role ?? semantics.role}
+  style={skeletonStyle || undefined}
   {...passthrough}
 >
   <slot />

package/components/Spinner.astro

@@ -1,7 +1,7 @@
 ---
 import type { HTMLAttributes } from 'astro/types'
 
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+import { resolveLumenAstroProps, resolveLumenLoadingSemantics } from '@santi020k/lumen-core'
 
 interface Props extends HTMLAttributes<'span'> {
   class?: string | null
@@ -18,7 +18,7 @@ const {
   ...rest
 } = Astro.props
 
-const isAccessible = Boolean(ariaLabel || ariaLabelledby)
+const semantics = resolveLumenLoadingSemantics({ ariaHidden, ariaLabel, ariaLabelledby, role })
 
 const { classList, passthrough } = resolveLumenAstroProps(rest, [
   'ui-spinner'
@@ -26,11 +26,11 @@ const { classList, passthrough } = resolveLumenAstroProps(rest, [
 ---
 
 <span
-  aria-hidden={ariaHidden ?? (isAccessible ? undefined : 'true')}
+  aria-hidden={ariaHidden ?? semantics.ariaHidden}
   aria-label={ariaLabel}
   aria-labelledby={ariaLabelledby}
   class:list={classList}
-  role={role ?? (isAccessible ? 'status' : undefined)}
+  role={role ?? semantics.role}
   {...passthrough}
 >
   <slot />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@santi020k/lumen-astro",
-  "version": "4.0.0",
+  "version": "4.3.0",
   "publishConfig": {
     "access": "public"
   },
@@ -9,7 +9,9 @@
   "sideEffects": [
     "./styles/lumen.css",
     "./styles/critical.css",
-    "./styles.css"
+    "./styles.css",
+    "./styles/tailwind.css",
+    "./styles/layers.css"
   ],
   "types": "./index.ts",
   "exports": {
@@ -26,7 +28,8 @@
     "./layers.css": "./styles/layers.css",
     "./styles.css": "./styles/lumen.css",
     "./styles/critical.css": "./styles/critical.css",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./tailwind.css": "./styles/tailwind.css"
   },
   "files": [
     "bin",
@@ -43,8 +46,8 @@
     "lumen": "./bin/lumen.mjs"
   },
   "dependencies": {
-    "@santi020k/lumen": "^4.0.0",
-    "@santi020k/lumen-core": "^4.0.0",
+    "@santi020k/lumen": "^4.3.0",
+    "@santi020k/lumen-core": "^4.3.0",
     "uqr": "^0.1.3"
   },
   "devDependencies": {

package/runtime/UIPrimitives.astro

@@ -9,7 +9,7 @@
 ---
 
 <script>
-import { isLumenDateBoundsValid, parseLumenDate as parseCalendarDate, resolveLumenDateLabels, resolveLumenDateLocale } from '@santi020k/lumen-core'
+import { connectLumenFloatingPanel, isLumenDateBoundsValid, parseLumenDate as parseCalendarDate, resolveLumenDateLabels, resolveLumenDateLocale } from '@santi020k/lumen-core'
 import {
   coerceThemePreset,
   createLumenKanbanMoveDetail,
@@ -36,8 +36,10 @@ import {
 import { initAmountFields } from './controllers/amount-field'
 import { clearComboboxes, closeCombobox, initComboboxes } from './controllers/combobox'
 import { initDataTableSorting } from './controllers/data-table'
+import { bindListBoxProxy } from './controllers/list-box-proxy'
 import { initMessageFeeds } from './controllers/message-scroller'
 import { initOptionalMediaControllers } from './controllers/optional-media'
+import { initProgress } from './controllers/progress'
 
 /* eslint-disable complexity */
 /* Stateful DOM handlers stay local so Astro consumers do not need a framework runtime. */
@@ -773,9 +775,15 @@ const getListBoxSelectedValues = (select: HTMLSelectElement): string[] => [
   ...select.selectedOptions
 ].map(option => option.value)
 
+const isOwnedByAnotherAdapter = (root: Element): boolean => root.hasAttribute('data-ui-owner')
+// A bound root that was removed and inserted again follows its external labels once reinitialized.
+const listBoxResyncs = new WeakMap<HTMLElement, () => void>()
+
 const initListBoxes = (scope: ParentNode): void => {
   for (const root of scope.querySelectorAll<HTMLElement>('[data-ui-list-box]')) {
-    if (root.dataset.uiListBoxBound === 'true') continue
+    if (root.dataset.uiListBoxBound === 'true') listBoxResyncs.get(root)?.()
+
+    if (root.dataset.uiListBoxBound === 'true' || isOwnedByAnotherAdapter(root)) continue
 
     const select = root.querySelector<HTMLSelectElement>('[data-ui-list-box-native]')
     const list = root.querySelector<HTMLElement>('[data-ui-list-box-list]')
@@ -789,6 +797,8 @@ const initListBoxes = (scope: ParentNode): void => {
 
     list.hidden = false
 
+    const optionIdPrefix = select.id || nextRuntimeId('ui-list-box', root.ownerDocument)
+
     let activeIndex = Math.max(
       0, options.findIndex(option => option.getAttribute('aria-disabled') !== 'true')
     )
@@ -798,7 +808,7 @@ const initListBoxes = (scope: ParentNode): void => {
 
     const syncActive = (): void => {
       options.forEach((option, index) => {
-        option.id ||= `${select.id || 'ui-list-box'}-option-${index}`
+        option.id ||= `${optionIdPrefix}-option-${index}`
 
         option.dataset.active = index === activeIndex ? 'true' : 'false'
       })
@@ -929,19 +939,17 @@ const initListBoxes = (scope: ParentNode): void => {
       })
     })
 
-    select.addEventListener('change', syncSelected)
+    listBoxResyncs.set(root, bindListBoxProxy(root, select, list, () => nextRuntimeId('ui-list-box-label', root.ownerDocument), () => {
+      if (!options.length) return
 
-    select.form?.addEventListener('reset', () => {
-      window.setTimeout(() => {
-        syncSelected()
+      syncSelected()
 
-        activeIndex = Math.max(
-          0, options.findIndex(option => option.getAttribute('aria-selected') === 'true')
-        )
+      activeIndex = Math.max(0, options.findIndex(option => option.getAttribute('aria-selected') === 'true'))
 
-        syncActive()
-      })
-    })
+      syncActive()
+    }))
+
+    select.addEventListener('change', syncSelected)
 
     syncSelected()
 
@@ -1618,50 +1626,6 @@ const initCopyButtons = (scope: ParentNode): void => {
   }
 }
 
-interface ProgressChangeDetail {
-  max?: number
-  value?: number
-}
-
-const updateProgress = (
-  root: HTMLElement,
-  { max, value }: ProgressChangeDetail
-): void => {
-  const currentMax = Number(root.getAttribute('aria-valuemax')) || 100
-  const safeMax = max && max > 0 ? max : currentMax
-  const currentValue = Number(root.getAttribute('aria-valuenow')) || 0
-
-  const safeValue = Math.min(
-    safeMax, Math.max(0, Number.isFinite(value) ? (value ?? 0) : currentValue)
-  )
-
-  const indicator = root.querySelector<HTMLElement>(
-    '[data-slot="progress-indicator"]'
-  )
-
-  root.setAttribute('aria-valuemax', String(safeMax))
-
-  root.setAttribute('aria-valuenow', String(safeValue))
-
-  if (indicator) indicator.style.width = `${(safeValue / safeMax) * 100}%`
-}
-
-const initProgress = (scope: ParentNode): void => {
-  for (const root of scope.querySelectorAll<HTMLElement>('[data-ui-progress]')) {
-    if (root.dataset.uiProgressBound === 'true') continue
-
-    root.dataset.uiProgressBound = 'true'
-
-    root.addEventListener('ui:progress-change', event => {
-      const detail = event instanceof CustomEvent ?
-        (event.detail as ProgressChangeDetail) :
-        {}
-
-      updateProgress(root, detail)
-    })
-  }
-}
-
 const filterItems = (input: HTMLInputElement, items: HTMLElement[]): void => {
   const query = input.value.trim().toLowerCase()
 
@@ -2248,9 +2212,10 @@ const sanitizeOtpValue = (input: HTMLInputElement, value: string, length: number
   return normalized.slice(0, length)
 }
 
+// Markup whose behavior another adapter owns, such as a React island, is never enhanced here.
 const initInputOtpFields = (scope: ParentNode): void => {
   for (const root of scope.querySelectorAll<HTMLElement>('[data-ui-input-otp]')) {
-    if (root.dataset.uiBound === 'true') continue
+    if (root.dataset.uiBound === 'true' || isOwnedByAnotherAdapter(root)) continue
 
     const input = root.querySelector<HTMLInputElement>('[data-ui-input-otp-native]')
     const segments = [...root.querySelectorAll<HTMLButtonElement>('[data-ui-input-otp-segment]')]
@@ -2867,7 +2832,7 @@ const moveCalendarFocus = (root: HTMLElement, currentDate: Date, key: string): v
 
 const initCalendars = (scope: ParentNode): void => {
   for (const root of scope.querySelectorAll<HTMLElement>('[data-ui-calendar]')) {
-    if (root.dataset.uiBound === 'true') continue
+    if (root.dataset.uiBound === 'true' || isOwnedByAnotherAdapter(root)) continue
 
     const input = root.querySelector<HTMLInputElement>('[data-ui-calendar-input]')
 
@@ -3011,12 +2976,22 @@ const formatDatePickerValue = (value: string, placeholder: string, locale: strin
   }).format(date)
 }
 
+// Each open picker's shared floating-panel connection; closing disconnects it.
+const datePickerPanels = new WeakMap<HTMLElement, () => void>()
+
 const closeDatePicker = (root: HTMLElement, restoreFocus = false): void => {
+  if (isOwnedByAnotherAdapter(root)) return
+
   const trigger = root.querySelector<HTMLButtonElement>('[data-ui-date-picker-trigger]')
   const popover = root.querySelector<HTMLElement>('[data-ui-date-picker-popover]')
 
   if (!trigger || !popover) return
 
+  // Leave the top layer and restore the popover's inline styles before hiding it.
+  datePickerPanels.get(root)?.()
+
+  datePickerPanels.delete(root)
+
   popover.hidden = true
 
   popover.dataset.state = 'closed'
@@ -3026,6 +3001,24 @@ const closeDatePicker = (root: HTMLElement, restoreFocus = false): void => {
   if (restoreFocus) trigger.focus()
 }
 
+const invalidDatePickerInputs = new WeakSet<HTMLInputElement>()
+
+const syncDatePickerValidity = (native: HTMLInputElement, trigger: HTMLElement): void => {
+  if (native.validity.valid) invalidDatePickerInputs.delete(native)
+
+  const invalid = native.getAttribute('aria-invalid') ?? (invalidDatePickerInputs.has(native) ? 'true' : null)
+
+  if (invalid === null) trigger.removeAttribute('aria-invalid')
+  else trigger.setAttribute('aria-invalid', invalid)
+
+  for (const attribute of ['aria-label', 'aria-labelledby', 'aria-describedby', 'aria-errormessage']) {
+    const value = native.getAttribute(attribute)
+
+    if (value === null) trigger.removeAttribute(attribute)
+    else trigger.setAttribute(attribute, value)
+  }
+}
+
 const syncDatePickerValue = (root: HTMLElement): void => {
   const native = root.querySelector<HTMLInputElement>('[data-ui-date-picker-native]')
   const value = root.querySelector<HTMLElement>('[data-ui-date-picker-value]')
@@ -3043,9 +3036,9 @@ const syncDatePickerValue = (root: HTMLElement): void => {
     root.dataset.placeholder = 'true'
   }
 
-  if (native.validity.valid) {
-    root.querySelector<HTMLElement>('[data-ui-date-picker-trigger]')?.removeAttribute('aria-invalid')
-  }
+  const trigger = root.querySelector<HTMLElement>('[data-ui-date-picker-trigger]')
+
+  if (trigger) syncDatePickerValidity(native, trigger)
 }
 
 const openDatePicker = (root: HTMLElement): void => {
@@ -3081,6 +3074,14 @@ const openDatePicker = (root: HTMLElement): void => {
 
   popover.dataset.state = 'open'
 
+  datePickerPanels.get(root)?.()
+
+  datePickerPanels.set(root, connectLumenFloatingPanel(popover, trigger, {
+    onDismiss: () => {
+      closeDatePicker(root)
+    }
+  }))
+
   trigger.setAttribute('aria-expanded', 'true')
 
   window.requestAnimationFrame(() => {
@@ -3095,7 +3096,7 @@ const openDatePicker = (root: HTMLElement): void => {
 
 const initDatePickers = (scope: ParentNode): void => {
   for (const root of scope.querySelectorAll<HTMLElement>('[data-ui-date-picker]')) {
-    if (root.dataset.uiDatePickerBound === 'true') continue
+    if (root.dataset.uiDatePickerBound === 'true' || isOwnedByAnotherAdapter(root)) continue
 
     const native = root.querySelector<HTMLInputElement>('[data-ui-date-picker-native]')
     const control = root.querySelector<HTMLElement>('[data-ui-date-picker-control]')
@@ -3147,13 +3148,13 @@ const initDatePickers = (scope: ParentNode): void => {
 
     syncState()
 
-    const observer = new MutationObserver(() => {
-      closeDatePicker(root)
+    const observer = new MutationObserver(mutations => {
+      if (mutations.some(mutation => !mutation.attributeName?.startsWith('aria-'))) closeDatePicker(root)
 
       syncState()
     })
 
-    observer.observe(native, { attributes: true, attributeFilter: ['disabled', 'readonly', 'required', 'value', 'min', 'max', 'placeholder'] })
+    observer.observe(native, { attributes: true, attributeFilter: ['disabled', 'readonly', 'required', 'value', 'min', 'max', 'placeholder', 'aria-invalid', 'aria-errormessage', 'aria-describedby', 'aria-label', 'aria-labelledby'] })
 
     observer.observe(root, { attributes: true, attributeFilter: ['locale', 'lang', 'data-locale', 'data-choose-date-label'] })
 
@@ -3207,7 +3208,9 @@ const initDatePickers = (scope: ParentNode): void => {
     native.addEventListener('invalid', event => {
       event.preventDefault()
 
-      trigger.setAttribute('aria-invalid', 'true')
+      invalidDatePickerInputs.add(native)
+
+      syncDatePickerValidity(native, trigger)
 
       trigger.focus()
     })
@@ -3216,6 +3219,8 @@ const initDatePickers = (scope: ParentNode): void => {
       globalThis.setTimeout(() => {
         if (event.defaultPrevented || !root.isConnected) return
 
+        invalidDatePickerInputs.delete(native)
+
         syncDatePickerValue(root)
 
         closeDatePicker(root)

package/runtime/controllers/document-navigation.ts

@@ -1,11 +1,4 @@
-const decodeFragment = (fragment: string): string => {
-  try {
-    return decodeURIComponent(fragment)
-  } catch {
-    // A literal percent sign can still identify a section; isolate malformed escapes.
-    return fragment
-  }
-}
+import { decodeLumenAnchorFragment, getLumenActiveAnchorIndex } from '@santi020k/lumen-core'
 
 interface AnchorDispatcher {
   callbacks: WeakMap<HTMLElement, () => void>
@@ -56,7 +49,7 @@ const initAnchors = (scope: ParentNode): void => {
 
     for (const link of links) {
       const fragment = link.getAttribute('href')?.slice(1) ?? ''
-      const id = decodeFragment(fragment)
+      const id = decodeLumenAnchorFragment(fragment)
       const target = id ? ownerDocument.getElementById(id) : null
 
       if (target) {
@@ -66,6 +59,8 @@ const initAnchors = (scope: ParentNode): void => {
 
     if (!targets.length) continue
 
+    const headings = targets.map(({ target }) => target)
+
     const setActive = (active: HTMLAnchorElement): void => {
       for (const link of links) {
         const isActive = link === active
@@ -81,21 +76,8 @@ const initAnchors = (scope: ParentNode): void => {
     }
 
     const update = (): void => {
-      const scrollingElement = ownerDocument.scrollingElement ?? ownerDocument.documentElement
-      const maximum = scrollingElement.scrollHeight - scrollingElement.clientHeight
-      const atEnd = maximum > 0 && scrollingElement.scrollTop >= maximum - 1
-      const offset = Number(root.dataset.uiAnchorOffset) || 0
-      let active = targets[0]?.link
-
-      if (atEnd) {
-        active = targets.at(-1)?.link
-      } else {
-        for (const item of targets) {
-          if (item.target.getBoundingClientRect().top > offset) break
-
-          active = item.link
-        }
-      }
+      const index = getLumenActiveAnchorIndex(headings, Number(root.dataset.uiAnchorOffset))
+      const active = targets[index]?.link
 
       if (active) setActive(active)
     }

package/runtime/controllers/list-box-proxy.ts

@@ -0,0 +1,209 @@
+const forwardedAttributes = ['aria-label', 'aria-labelledby', 'aria-describedby', 'aria-errormessage'] as const
+// A new select id changes which labels name it.
+const observedAttributes = [...forwardedAttributes, 'aria-invalid', 'disabled', 'form', 'id', 'required']
+
+// The first invalid control owns focus so several invalid fields do not race for it.
+const isFirstInvalidControl = (select: HTMLSelectElement): boolean => {
+  const form = select.form
+
+  if (!form) return true
+
+  for (const element of form.elements) {
+    if (element.matches(':invalid') && element.tagName !== 'FIELDSET') return element === select
+  }
+
+  return true
+}
+
+const setOptionalAttribute = (element: HTMLElement, name: string, value: string | null): void => {
+  if (value === null) element.removeAttribute(name)
+  else element.setAttribute(name, value)
+}
+
+const syncListBoxName = (
+  root: HTMLElement,
+  select: HTMLSelectElement,
+  list: HTMLElement,
+  listOwned: ReadonlySet<string>,
+  createLabelId: () => string
+): void => {
+  for (const name of forwardedAttributes) {
+    if (listOwned.has(name)) continue
+
+    setOptionalAttribute(list, name, select.getAttribute(name) ?? (name === 'aria-label' ? root.getAttribute('aria-label') : null))
+  }
+
+  if (listOwned.has('aria-labelledby') || list.hasAttribute('aria-label') || list.hasAttribute('aria-labelledby')) return
+
+  const labelIds = [...select.labels].map(label => {
+    label.id ||= createLabelId()
+
+    return label.id
+  })
+
+  if (labelIds.length) list.setAttribute('aria-labelledby', labelIds.join(' '))
+}
+
+const mayHoldListBoxLabel = (node: Node, root: HTMLElement): boolean => {
+  // Adoption preserves a node's original realm, so instanceof the destination Element is insufficient.
+  if (node.nodeType !== 1) return false
+
+  const element = node as Element
+
+  return ['LABEL', 'FORM'].includes(element.nodeName) || element.contains(root) || element.querySelector('label, form') !== null
+}
+
+// Only label insertions, removals, `for` or `id` changes, or moving the list itself can change its labels.
+const affectsListBoxLabels = (
+  records: readonly MutationRecord[],
+  root: HTMLElement
+): boolean => (
+  records.some(record => record.type === 'attributes' ?
+    ['LABEL', 'FORM', 'SELECT'].includes(record.target.nodeName) :
+    [...record.addedNodes, ...record.removedNodes].some(node => mayHoldListBoxLabel(node, root)))
+)
+
+/**
+ * Once a list box is enhanced the visible list is its only focus stop and accessible control, while the
+ * native select keeps form submission, validation, and reset. Naming, description, error, required, and
+ * disabled semantics follow the select as they change, focus that reaches the select moves to the list,
+ * and native invalid events mark the list invalid until a valid change or an accepted reset. Consumer
+ * `aria-invalid` on the select always wins over generated state. External labels are followed while the root
+ * is connected; the returned function resynchronizes a root that was removed and inserted again.
+ */
+export const bindListBoxProxy = (
+  root: HTMLElement,
+  select: HTMLSelectElement,
+  list: HTMLElement,
+  createLabelId: () => string,
+  onResetAccepted?: () => void
+): (() => void) => {
+  // Attributes authored on the list itself stay under the author's control.
+  const listOwned = new Set<string>(forwardedAttributes.filter(name => list.hasAttribute(name)))
+  let generatedInvalid = false
+  let resetForm: HTMLFormElement | null = null
+
+  const syncState = (): void => {
+    select.tabIndex = -1
+
+    select.setAttribute('aria-hidden', 'true')
+
+    syncListBoxName(root, select, list, listOwned, createLabelId)
+
+    setOptionalAttribute(list, 'aria-required', select.required ? 'true' : null)
+
+    // A select that is valid again or barred from validation, such as disabled or no longer required, is not invalid.
+    if (!select.willValidate || select.validity.valid) generatedInvalid = false
+
+    setOptionalAttribute(list, 'aria-invalid', select.getAttribute('aria-invalid') ?? (generatedInvalid ? 'true' : null))
+
+    list.tabIndex = select.disabled ? -1 : 0
+
+    setOptionalAttribute(list, 'aria-disabled', select.disabled ? 'true' : null)
+  }
+
+  const onReset = (event: Event): void => {
+    const form = event.currentTarget
+
+    globalThis.setTimeout(() => {
+      if (event.defaultPrevented || select.form !== form) return
+
+      generatedInvalid = false
+
+      syncState()
+
+      onResetAccepted?.()
+    })
+  }
+
+  const followForm = (): void => {
+    const next = root.isConnected ? select.form : null
+
+    if (next === resetForm) return
+
+    resetForm?.removeEventListener('reset', onReset)
+
+    resetForm = next
+
+    resetForm?.addEventListener('reset', onReset)
+  }
+
+  const sync = (): void => {
+    followForm()
+
+    syncState()
+  }
+
+  let labelObserver: MutationObserver | undefined
+  let observedDocument: Document | undefined
+
+  // The document observer stops once the root leaves, so a removed list box is not kept alive by it.
+  const followLabels = (): void => {
+    if (observedDocument !== root.ownerDocument) {
+      labelObserver?.disconnect()
+
+      labelObserver = undefined
+    }
+
+    const view = root.ownerDocument.defaultView
+
+    if (labelObserver || !view || !root.isConnected) return
+
+    observedDocument = root.ownerDocument
+
+    labelObserver = new view.MutationObserver(records => {
+      if (observedDocument !== root.ownerDocument) {
+        followLabels()
+
+        sync()
+      } else if (!root.isConnected) {
+        followForm()
+
+        labelObserver?.disconnect()
+
+        labelObserver = undefined
+      } else if (affectsListBoxLabels(records, root)) {
+        sync()
+      }
+    })
+
+    labelObserver.observe(root.ownerDocument, {
+      attributeFilter: ['for', 'form', 'id'], attributes: true, childList: true, subtree: true
+    })
+  }
+
+  sync()
+
+  followLabels()
+
+  new MutationObserver(sync).observe(select, { attributeFilter: observedAttributes, attributes: true })
+
+  select.addEventListener('focus', () => {
+    // Only real select focus, such as a label click, moves to the list; focus moved elsewhere stays put.
+    if (select.ownerDocument.activeElement === select && !select.disabled) list.focus({ preventScroll: true })
+  })
+
+  select.addEventListener('invalid', event => {
+    event.preventDefault()
+
+    generatedInvalid = true
+
+    sync()
+
+    if (isFirstInvalidControl(select) && !select.disabled) list.focus()
+  })
+
+  select.addEventListener('change', () => {
+    if (!select.validity.valid) return
+
+    generatedInvalid = false
+
+    sync()
+  })
+
+  return () => {
+    followLabels()
+
+    sync()
+  }
+}

package/runtime/controllers/progress.ts

@@ -0,0 +1,52 @@
+import { normalizeLumenProgress } from '@santi020k/lumen-core'
+
+interface ProgressChangeDetail {
+  max?: number | undefined
+  value?: number | undefined
+}
+
+export const readProgressChangeDetail = (detail: unknown): ProgressChangeDetail => {
+  if (typeof detail !== 'object' || detail === null) return {}
+
+  const max = 'max' in detail && typeof detail.max === 'number' ? detail.max : undefined
+  const value = 'value' in detail && typeof detail.value === 'number' ? detail.value : undefined
+
+  return { max, value }
+}
+
+const updateProgress = (
+  root: HTMLElement,
+  { max, value }: ProgressChangeDetail
+): void => {
+  const current = normalizeLumenProgress(
+    root.getAttribute('aria-valuemax'), root.getAttribute('aria-valuenow')
+  )
+
+  // Omitted or invalid fields keep the current state instead of resetting it.
+  const next = normalizeLumenProgress(
+    max !== undefined && Number.isFinite(max) && max > 0 ? max : current.max,
+    value !== undefined && Number.isFinite(value) ? value : current.value
+  )
+
+  const indicator = root.querySelector<HTMLElement>(
+    '[data-slot="progress-indicator"]'
+  )
+
+  root.setAttribute('aria-valuemax', String(next.max))
+
+  root.setAttribute('aria-valuenow', String(next.value))
+
+  if (indicator) indicator.style.width = `${next.percentage}%`
+}
+
+export const initProgress = (scope: ParentNode): void => {
+  for (const root of scope.querySelectorAll<HTMLElement>('[data-ui-progress]')) {
+    if (root.dataset.uiProgressBound === 'true') continue
+
+    root.dataset.uiProgressBound = 'true'
+
+    root.addEventListener('ui:progress-change', event => {
+      updateProgress(root, readProgressChangeDetail(event instanceof CustomEvent ? event.detail : undefined))
+    })
+  }
+}

package/styles/critical.css

@@ -172,6 +172,17 @@
   }
 }
 
+@keyframes ui-skeleton-pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+
+  50% {
+    opacity: 0.55;
+  }
+}
+
 @keyframes ui-spin {
   to {
     transform: rotate(360deg);
@@ -790,15 +801,21 @@
   background-image:
     linear-gradient(45deg, transparent 50%, hsl(var(--ink-muted)) 50%),
     linear-gradient(135deg, hsl(var(--ink-muted)) 50%, transparent 50%);
-  background-position:
-    calc(100% - 1rem) 50%,
-    calc(100% - 0.72rem) 50%;
+  background-position: var(--_ui-select-chevron, calc(100% - 1rem) 50%, calc(100% - 0.72rem) 50%);
   background-size:
     0.32rem 0.32rem,
     0.32rem 0.32rem;
   background-repeat: no-repeat;
 }
 
+[dir="rtl"] {
+  --_ui-select-chevron: 0.72rem 50%, 1rem 50%;
+}
+
+[dir="ltr"] {
+  --_ui-select-chevron: calc(100% - 1rem) 50%, calc(100% - 0.72rem) 50%;
+}
+
 .ui-label {
   color: hsl(var(--ink));
   font-size: 0.875rem;
@@ -820,6 +837,10 @@
   width: min(100%, 34rem);
 }
 
+lumen-date-picker.ui-date-picker-field {
+  display: block;
+}
+
 .ui-combobox > .ui-input {
   width: 100%;
 }
@@ -1007,7 +1028,9 @@
 }
 
 .ui-skeleton {
-  min-height: 1rem;
+  /* A default height, not a minimum, lets explicit styles and classes size placeholders below 1rem. */
+  width: var(--ui-skeleton-width, auto);
+  height: var(--ui-skeleton-height, 1rem);
   border-radius: var(--ui-radius-sm);
   background: linear-gradient(
     90deg,
@@ -1019,6 +1042,42 @@
   animation: ui-shimmer 2.2s linear infinite;
 }
 
+.ui-skeleton:where(:not(:empty)) {
+  height: var(--ui-skeleton-height, auto);
+  min-height: 1rem;
+}
+
+lumen-skeleton.ui-skeleton,
+lumen-progress.ui-progress {
+  display: block;
+}
+
+.ui-skeleton--text {
+  height: var(--ui-skeleton-height, 0.75rem);
+}
+
+.ui-skeleton--circle {
+  flex: 0 0 auto;
+  width: var(--ui-skeleton-width, var(--ui-skeleton-height, 2.5rem));
+  height: var(--ui-skeleton-height, var(--ui-skeleton-width, 2.5rem));
+  border-radius: 50%;
+}
+
+.ui-skeleton--pulse {
+  background: hsl(var(--surface-strong));
+  animation: ui-skeleton-pulse 1.6s ease-in-out infinite;
+}
+
+.ui-skeleton--static {
+  animation: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+.ui-skeleton {
+    animation: none;
+  }
+}
+
 .ui-spinner {
   box-sizing: border-box;
   display: inline-block;
@@ -1586,7 +1645,9 @@ lumen-dialog.ui-dialog:not([hidden]):has(> [data-slot="dialog-body"]) {
 
 .ui-input-otp__native[data-ui-enhanced="true"] {
   position: absolute;
-  width: 1px;
+  inset-block-start: 0;
+  inset-inline-start: 0;
+  width: 100%;
   height: 1px;
   overflow: hidden;
   clip-path: inset(50%);

package/styles/tailwind.css

@@ -0,0 +1 @@
+@import "@santi020k/lumen/tailwind.css";