@santi020k/lumen-astro 3.0.1 → 4.1.0

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/SourceCitation.astro

@@ -0,0 +1,18 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { resolveLumenCitationHref } from '@santi020k/lumen-core'
+
+import Link from './Link.astro'
+
+interface Props extends Omit<HTMLAttributes<'a'>, 'href'> { href: string, label: string }
+
+const { class: className, href, label, ...rest } = Astro.props
+const safeHref = resolveLumenCitationHref(href)
+---
+
+{safeHref ?
+<Link {...rest} class:list={['ui-source-citation', className]} href={safeHref} rel="noopener noreferrer">{label}<slot /></Link> :
+(
+<span class:list={['ui-source-citation', className]}>{label}<slot /></span>
+)}

package/components/Sparkline.astro

@@ -57,16 +57,15 @@ const endpoint = geometry.points[geometry.points.length - 1]
       ))
     }
     <path class="ui-sparkline__line" d={geometry.path} />
-    {
-      showEndpoint && endpoint && (
-        <circle
-          class="ui-sparkline__endpoint"
-          cx={endpoint.xCoordinate}
-          cy={endpoint.yCoordinate}
-          r="2.5"
-        />
-      )
-    }
   </svg>
+  {
+    showEndpoint && endpoint && (
+      <span
+        aria-hidden="true"
+        class="ui-sparkline__endpoint"
+        style={{ left: `${endpoint.xCoordinate / 120 * 100}%`, top: `${endpoint.yCoordinate / 40 * 100}%` }}
+      />
+    )
+  }
   <span class="ui-sr-only">{label}</span>
 </span>

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/components/Stack.astro

@@ -9,7 +9,7 @@ interface Props extends HTMLAttributes<'div'> {
   class?: string | null
   className?: string
   direction?: 'horizontal' | 'vertical'
-  gap?: 'lg' | 'md' | 'none' | 'sm' | 'xl'
+  gap?: '2xl' | '3xl' | 'group' | 'lg' | 'md' | 'none' | 'related' | 'section' | 'sm' | 'xl' | 'xs'
   justify?: 'between' | 'center' | 'end' | 'start'
   wrap?: boolean
 }
@@ -20,7 +20,7 @@ const {
   class: classProp = '',
   className = '',
   direction = 'vertical',
-  gap = 'md',
+  gap = 'group',
   justify = 'start',
   wrap = false,
   ...rest

package/components/StreamMessage.astro

@@ -0,0 +1,26 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import type { LumenStreamStatus } from '@santi020k/lumen-core'
+
+import Message from './Message.astro'
+import Prose from './Prose.astro'
+import Stack from './Stack.astro'
+
+interface Props extends HTMLAttributes<'article'> {
+  label?: string
+  status?: LumenStreamStatus
+  statusLabel: string
+}
+
+const { class: className, label = 'Assistant', status = 'idle', statusLabel, ...rest } = Astro.props
+---
+
+<Message {...rest} aria-label={label} class:list={['ui-stream-message', className]} data-status={status} from="assistant">
+  <Prose aria-busy={status === 'streaming'} aria-live="off" data-ui-stream-content><slot /></Prose>
+  <Stack direction="horizontal" gap="related" wrap>
+    <span aria-live="polite" role="status">{statusLabel}</span>
+    <slot name="actions" />
+  </Stack>
+  <slot name="sources" />
+</Message>

package/components/Tabs.astro

@@ -7,6 +7,7 @@ interface Props extends HTMLAttributes<'div'> {
   class?: string | null
   className?: string
   glass?: boolean | 'subtle' | 'strong'
+  indicator?: boolean
   initialValue?: string
   storageKey?: string
 }
@@ -15,6 +16,7 @@ const {
   class: classProp = '',
   className = '',
   glass = false,
+  indicator = false,
   initialValue,
   storageKey,
   ...rest
@@ -29,6 +31,7 @@ const { classList, passthrough } = resolveLumenAstroProps(rest, [
 ---
 
 <div
+  data-ui-tab-indicator={indicator || undefined}
   data-initial-value={initialValue}
   data-storage-key={storageKey}
   data-ui-tabs

package/components/ToolActivity.astro

@@ -0,0 +1,17 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import type { LumenToolStatus } from '@santi020k/lumen-core'
+
+import Collapsible from './Collapsible.astro'
+import Stack from './Stack.astro'
+
+interface Props extends HTMLAttributes<'details'> { label: string, status?: LumenToolStatus, statusLabel: string }
+
+const { class: className, label, status = 'queued', statusLabel, ...rest } = Astro.props
+---
+
+<Collapsible {...rest} class:list={['ui-tool-activity', className]} data-status={status}>
+  <summary>{label}</summary>
+  <Stack gap="related"><span role="status">{statusLabel}</span><slot /></Stack>
+</Collapsible>

package/components/TreeSelect.astro

@@ -59,6 +59,7 @@ const { classList, passthrough } = resolveLumenAstroProps(rest, [
     <div class="ui-tree-select__tree" role="tree">
       {rows.map(row => (
         <button
+          aria-level={row.depth + 1}
           class="ui-tree-select__option"
           data-value={row.value}
           role="treeitem"

package/components/VirtualList.astro

@@ -7,14 +7,17 @@ interface Props extends HTMLAttributes<'div'> {
   class?: string | null
   className?: string
   glass?: boolean | 'subtle' | 'strong'
+  itemSize?: number | string
+  overscan?: number | string
+  mode?: 'data' | 'mounted'
 }
 
-const { class: classProp = '', className = '', glass = false, ...rest } = Astro.props
+const { class: classProp = '', className = '', glass = false, itemSize = 44, overscan = 4, mode = 'mounted', tabindex = 0, ...rest } = Astro.props
 
 const { classList, passthrough } = resolveLumenAstroProps(rest, ['ui-virtual-list', glass && 'ui-virtual-list--glass', glass === 'subtle' && 'ui-glass-subtle', glass === 'strong' && 'ui-glass-strong'
 ], classProp, className)
 ---
 
-<div class:list={classList} data-ui-virtual-list {...passthrough}>
+<div class:list={classList} data-ui-virtual-list data-ui-virtual-list-mode={mode} data-ui-item-size={itemSize} data-ui-overscan={overscan} tabindex={tabindex} {...passthrough}>
   <slot />
 </div>

package/components/VisualEffect.astro

@@ -0,0 +1,21 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { type LumenVisualEffectVariant, normalizeLumenEffectIntensity, resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'div'> {
+  animated?: boolean
+  class?: string | null
+  className?: string
+  intensity?: number
+  variant?: LumenVisualEffectVariant
+}
+
+const { animated = false, class: classProp, className, intensity = 0.5, style, variant = 'mesh', ...rest } = Astro.props
+const { classList, passthrough } = resolveLumenAstroProps(rest, ['ui-visual-effect'], classProp, className)
+const effectStyle = `${typeof style === 'string' ? style : ''};--ui-effect-intensity:${normalizeLumenEffectIntensity(intensity)}`
+---
+
+<div class:list={classList} data-ui-visual-effect={variant} data-ui-effect-animated={String(animated)} style={effectStyle} {...passthrough}>
+  <slot />
+</div>

package/components/WaterfallChart.astro

@@ -0,0 +1,27 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { createLumenWaterfallGeometry, type LumenChartLabels, type LumenWaterfallDatum, resolveLumenChartLabels } from '@santi020k/lumen-core'
+
+import IntervalChart from '../internal/IntervalChart.astro'
+
+interface Props extends HTMLAttributes<'figure'> {
+  caption?: string
+  class?: string | null
+  className?: string
+  data: readonly LumenWaterfallDatum[]
+  description?: string
+  formatValue?: (value: number) => string
+  heading?: string
+  labels?: Partial<LumenChartLabels>
+  presentation?: 'bare' | 'default'
+  showTable?: boolean
+  summary?: string
+  valueLabel?: string
+}
+
+const { data, class: classProp, className, formatValue = String, labels, valueLabel = resolveLumenChartLabels(labels).value, ...rest } = Astro.props
+const model = createLumenWaterfallGeometry(data, { formatValue })
+---
+
+<IntervalChart {...rest} class:list={['ui-waterfall-chart', classProp, className]} {model} {labels} {formatValue} formatBoundary={formatValue} {valueLabel} />

package/components/WorldMap.astro

@@ -0,0 +1,213 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import {
+  findLumenWorldMapCountry,
+  LUMEN_WORLD_MAP_VIEW_BOX,
+  type LumenWorldMapCountryGeometry,
+  type LumenWorldMapMarker,
+  type LumenWorldMapVariant,
+  normalizeLumenWorldMapCountries,
+  normalizeLumenWorldMapHighlightedCountries,
+  normalizeLumenWorldMapMarkers,
+  projectLumenWorldMapCoordinate,
+  resolveLumenAstroProps,
+  resolveLumenWorldMapCountryLabel
+} from '@santi020k/lumen-core'
+import { type LumenWorldMapZoomLabels, lumenWorldMapZoomLabels } from '@santi020k/lumen-core/world-map-zoom'
+
+import Button from './Button.astro'
+
+interface Props extends HTMLAttributes<'figure'> {
+  initialView?: 'world' | 'highlighted'
+  zoomable?: boolean
+  zoomLabels?: Partial<LumenWorldMapZoomLabels>
+  animated?: boolean
+  caption?: string
+  class?: string | null
+  className?: string
+  countries: readonly LumenWorldMapCountryGeometry[]
+  description?: string
+  heading?: string
+  highlightedCountries?: readonly string[]
+  interactive?: boolean
+  label: string
+  labels?: Readonly<Record<string, string>>
+  listLabel?: string
+  markers?: readonly LumenWorldMapMarker[]
+  selectedCountry?: string
+  variant?: LumenWorldMapVariant
+}
+
+const {
+  animated = true,
+  caption,
+  class: classProp = '',
+  className = '',
+  countries: inputCountries,
+  description,
+  heading,
+  highlightedCountries,
+  interactive = true,
+  label,
+  labels,
+  listLabel = 'Choose a country',
+  markers,
+  selectedCountry,
+  variant = 'dotted',
+  initialView = 'world',
+  zoomable = true,
+  zoomLabels,
+  ...rest
+} = Astro.props
+
+const countries = normalizeLumenWorldMapCountries(inputCountries)
+const highlightedIds = normalizeLumenWorldMapHighlightedCountries(highlightedCountries, countries)
+const highlightedSet = new Set(highlightedIds)
+const normalizedMarkers = normalizeLumenWorldMapMarkers(markers)
+const selected = findLumenWorldMapCountry(countries, selectedCountry)
+const zoomText = { ...lumenWorldMapZoomLabels, ...zoomLabels }
+const instanceId = `ui-world-map-${crypto.randomUUID()}`
+const neutralPatternId = `${instanceId}-dot-neutral`
+const highlightPatternId = `${instanceId}-dot-highlight`
+const { height: viewBoxHeight, width: viewBoxWidth } = LUMEN_WORLD_MAP_VIEW_BOX
+const { classList, passthrough } = resolveLumenAstroProps(rest, ['ui-world-map'], classProp, className)
+---
+
+<figure
+  class:list={classList}
+  data-animated={String(animated)}
+  data-interactive={String(interactive)}
+  data-ui-world-map
+  data-initial-view={initialView}
+  data-variant={variant}
+  id={instanceId}
+  {...passthrough}
+>
+  {
+    (heading || description) && (
+      <header class="ui-world-map__heading">
+        {heading && <h3>{heading}</h3>}
+        {description && <p>{description}</p>}
+      </header>
+    )
+  }
+  {zoomable && (
+    <div class="ui-world-map__zoom-controls">
+      <Button aria-label={zoomText.zoomOut} data-ui-world-map-zoom="out" disabled size="icon" variant="outline">−</Button>
+      <output aria-label={zoomText.level} aria-live="polite" data-ui-world-map-zoom-status>100%</output>
+      <Button aria-label={zoomText.zoomIn} data-ui-world-map-zoom="in" disabled size="icon" variant="outline">+</Button>
+      <Button data-ui-world-map-zoom="fit" disabled size="sm" variant="outline">{zoomText.fit}</Button>
+      <Button data-ui-world-map-zoom="reset" disabled size="sm" variant="outline">{zoomText.reset}</Button>
+    </div>
+  )}
+  <div class="ui-world-map__frame">
+    <div
+      aria-label={`${zoomText.viewport}: ${label}`}
+      class="ui-world-map__viewport"
+      data-ui-world-map-viewport
+      role="region"
+      tabindex={zoomable ? 0 : undefined}
+    >
+      <svg
+        aria-label={label}
+        class="ui-world-map__plot"
+        role="img"
+        viewBox={`0 0 ${viewBoxWidth} ${viewBoxHeight}`}
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        {
+          variant === 'dotted' && (
+            <defs>
+              <pattern height="4" id={neutralPatternId} patternUnits="userSpaceOnUse" width="4">
+                <circle class="ui-world-map__dot ui-world-map__dot--neutral" cx="2" cy="2" r="1.1" />
+              </pattern>
+              <pattern height="4" id={highlightPatternId} patternUnits="userSpaceOnUse" width="4">
+                <circle class="ui-world-map__dot ui-world-map__dot--highlight" cx="2" cy="2" r="1.1" />
+              </pattern>
+            </defs>
+          )
+        }
+        <g aria-hidden="true" class="ui-world-map__countries">
+          {countries.map(country => {
+            const isHighlighted = highlightedSet.has(country.id)
+            const isSelected = selected?.id === country.id
+            const countryLabel = resolveLumenWorldMapCountryLabel(country, labels)
+
+            return (
+              <path
+                class:list={[
+                  'ui-world-map__country',
+                  isHighlighted && 'ui-world-map__country--highlighted',
+                  isSelected && 'ui-world-map__country--selected'
+                ]}
+                d={country.path}
+                data-label={countryLabel}
+                data-label-x={country.labelX}
+                data-label-y={country.labelY}
+                data-ui-world-map-country={country.id}
+                fill={
+                  variant === 'dotted' ?
+                    `url(#${isHighlighted ? highlightPatternId : neutralPatternId})` :
+                    undefined
+                }
+                fill-rule="evenodd"
+              >
+                <title>{countryLabel}</title>
+              </path>
+            )
+          })}
+        </g>
+        {
+          normalizedMarkers.length > 0 && (
+            <g aria-hidden="true" class="ui-world-map__markers">
+              {normalizedMarkers.map(marker => {
+                const { x, y } = projectLumenWorldMapCoordinate(marker.longitude, marker.latitude)
+
+                return (
+                  <circle class="ui-world-map__marker" cx={x} cy={y} r="4">
+                    <title>{marker.label}</title>
+                  </circle>
+                )
+              })}
+            </g>
+          )
+        }
+        <path aria-hidden="true" class="ui-world-map__selection" d={selected?.path ?? ''} />
+      </svg>
+    </div>
+    <span class="ui-world-map__inspection" data-ui-world-map-inspection hidden />
+  </div>
+  {
+    interactive && (
+      <label class="ui-world-map__select-label">
+        <span>{listLabel}</span>
+        <select class="ui-select ui-world-map__select" data-ui-world-map-select disabled>
+          <option value="">{listLabel}</option>
+          {countries.map(country => (
+            <option selected={selected?.id === country.id} value={country.id}>
+              {resolveLumenWorldMapCountryLabel(country, labels)}
+            </option>
+          ))}
+        </select>
+      </label>
+    )
+  }
+  {
+    highlightedIds.length > 0 && (
+      <ul aria-label="Highlighted countries" class="ui-world-map__highlights" data-ui-world-map-highlights>
+        {highlightedIds.map(id => {
+          const country = findLumenWorldMapCountry(countries, id)
+
+          return country && <li>{resolveLumenWorldMapCountryLabel(country, labels)}</li>
+        })}
+      </ul>
+    )
+  }
+  {normalizedMarkers.length > 0 && (
+    <ul aria-label="Map markers" class="ui-sr-only">
+      {normalizedMarkers.map(marker => <li>{marker.label}</li>)}
+    </ul>
+  )}
+  {caption && <figcaption>{caption}</figcaption>}
+</figure>

package/forms.ts

@@ -10,11 +10,24 @@ export interface AstroActionErrorLike {
 
 export type LumenControlIdMap = Readonly<Record<string, string>>
 
-const isActionErrorLike = (error: unknown): error is AstroActionErrorLike => (
-  typeof error === 'object' &&
-  error !== null
+const isFieldMessages = (value: unknown): boolean => (
+  value === null || value === undefined || typeof value === 'string' ||
+  (Array.isArray(value) && value.every((message: unknown) => typeof message === 'string'))
 )
 
+const isActionFields = (value: unknown): value is NonNullable<AstroActionErrorLike['fields']> => (
+  typeof value === 'object' && value !== null && !Array.isArray(value) &&
+  Object.values(value).every(isFieldMessages)
+)
+
+const isActionErrorLike = (error: unknown): error is AstroActionErrorLike => {
+  if (typeof error !== 'object' || error === null) return false
+
+  if ('message' in error && error.message !== undefined && typeof error.message !== 'string') return false
+
+  return !('fields' in error) || error.fields === undefined || isActionFields(error.fields)
+}
+
 export const normalizeAstroActionErrors = (
   error: unknown,
   controlIds: LumenControlIdMap = {}
@@ -35,7 +48,7 @@ export const normalizeAstroActionErrors = (
   return {
     fields: normalized.fields.map(fieldError => ({
       ...fieldError,
-      ...(controlIds[fieldError.name] ?
+      ...(Object.hasOwn(controlIds, fieldError.name) && controlIds[fieldError.name] ?
         {
           controlId: controlIds[fieldError.name]
         } :