@santi020k/lumen-astro 1.6.0 → 1.7.0

package/README.md

@@ -9,6 +9,13 @@ configuration is required to render the components.
 pnpm add @santi020k/lumen-astro
 ```
 
+The adapter also exposes Lumen's discovery and diagnostics CLI:
+
+```bash
+pnpm exec lumen show Tabs
+pnpm exec lumen doctor
+```
+
 Import the CSS once in your root layout and mount `UIPrimitives` once in that same app shell if you
 use interactive components such as dialogs, menus, popovers, tabs, carousels, toggles, command
 lists, or toasts. Do not add `UIPrimitives` beside each component instance; one root include
@@ -18,6 +25,11 @@ enhances all matching Lumen markup on the page.
 @import "@santi020k/lumen-astro/styles.css";
 ```
 
+Applications using the essential forms, feedback, tabs, dialogs, calendar, and data-table surface
+can instead load `@santi020k/lumen-astro/styles/critical.css`. The generated entry is about 50 KiB
+raw versus 170 KiB for the complete catalog; switch to `styles.css` when using components outside
+that documented critical set.
+
 The stylesheet defaults `--ui-font` to `"Montserrat", "Avenir Next", "Segoe UI", sans-serif`.
 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.
@@ -32,7 +44,7 @@ With Tailwind, keep the Lumen import in the same shared CSS entry:
 
 ```astro
 ---
-import { UIPrimitives } from '@santi020k/lumen-astro'
+import UIPrimitives from '@santi020k/lumen-astro/runtime'
 ---
 
 <UIPrimitives />
@@ -52,20 +64,35 @@ import { Button, Card, Input } from '@santi020k/lumen-astro'
 ```
 
 `Input` and `NativeSelect` preserve the native numeric `size` attribute. Use `visualSize="sm"` or
-`visualSize="lg"` for presentation. The pre-1.0 `size="sm|lg"` visual alias remains available for
-incremental migrations, but new code should keep native behavior and visual styling separate.
+`visualSize="lg"` for presentation so native behavior and visual styling remain separate.
 
 ```astro
 <Input size={32} visualSize="sm" />
 <NativeSelect size={8} visualSize="lg" />
 ```
 
+`PhoneInput` generates localized country names, supplementary flags, and calling codes when custom
+`countries` are not provided. Mount `UIPrimitives` once to enable as-you-type formatting,
+metadata-backed validation, automatic country detection for pasted international numbers, and the
+`ui:phone-change` event with a `LumenPhoneNumber` detail.
+
+The phone metadata and normalization controller are selector-loaded only when a rendered page
+contains `PhoneInput`; pages without the component do not evaluate or download that controller.
+
+```astro
+<PhoneInput countryValue="CO" locale="en-US" name="hospitalPhone" />
+```
+
 ## Compound interactive components
 
 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.
 
+Tabs keep the selected trigger visible when a narrow tab list scrolls horizontally and emit a
+typed `ui:tabs-change` event. Import `LumenTabsChangeDetail` or `LumenTabsChangeEvent` from this
+package when application behavior follows the selected value.
+
 ```astro
 ---
 import {
@@ -171,6 +198,22 @@ const errors = result?.error && isInputError(result.error)
 
 See the [Astro Actions form guide](https://lumen.santi020k.com/docs/forms/astro-actions).
 
+## Error states
+
+Use `ErrorState` when a page or region cannot show its primary content. Pass recovery controls
+through the `actions` slot; the application still owns retry and logging behavior. Static states are
+not live regions by default, so set `announce="polite"` only when a newly rendered failure needs an
+announcement.
+
+```astro
+<ErrorState title="Could not load projects" description="Check your connection and try again.">
+  <Button slot="actions">Try again</Button>
+</ErrorState>
+```
+
+See the repository [Astro error-handling guide](../../docs/error-handling.md#astro) for the complete
+example, retry ownership, announcement behavior, and verification guidance.
+
 Use `Icon` for Lucide icons by name across framework adapters.
 
 ```astro
@@ -216,7 +259,9 @@ non-code content `Code` semantics.
 ## Data visualization
 
 Use `Sparkline` beside a metric, `BarChart` for categorical comparison, `LineChart` for ordered
-trends, and `PieChart` for a small part-to-whole breakdown. The chart components accept
+trends, `PieChart` for a small part-to-whole breakdown, `ScatterChart` for numeric relationships,
+`Heatmap` for a matrix, `RangeChart` for intervals, and `ComboChart` for a shared-domain mix of bars,
+lines, and areas. The chart components accept
 already-aggregated series, use Lumen data-color tokens, and include a revealable semantic data
 table by default.
 
@@ -237,6 +282,10 @@ const series = [{
 `PieChart` accepts one `LumenChartSeries`; its data points become slices. It defaults to
 `variant="donut"` and also supports `variant="pie"`.
 
+Every chart includes a factual screen-reader summary by default and accepts `summary` for more
+useful domain context. See [data visualization](../../docs/data-visualization.md) for selection,
+missing-data, live-data, and accessibility guidance.
+
 Lucide intentionally excludes brand marks. For GitHub and other project-specific icons, put the
 SVG in the default slot instead of passing an unsupported `name`; Astro warns about unknown named
 icons during development.

package/bin/lumen.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '@santi020k/lumen/cli'

package/components/BarChart.astro

@@ -3,6 +3,7 @@ import type { HTMLAttributes } from 'astro/types'
 
 import {
   createLumenBarGeometry,
+  formatLumenChartSummary,
   getLumenChartTicks,
   getLumenChartToneClassName,
   hasLumenChartData,
@@ -31,6 +32,7 @@ interface Props extends HTMLAttributes<'figure'> {
   series: readonly LumenChartSeries[]
   showLegend?: boolean
   showTable?: boolean
+  summary?: string
 }
 
 const {
@@ -49,6 +51,7 @@ const {
   series,
   showLegend = series.length > 1,
   showTable = true,
+  summary = formatLumenChartSummary(series, formatValue),
   ...rest
 } = Astro.props
 
@@ -72,7 +75,7 @@ const labelFor = (item: LumenChartSeries, category: number | string) => (
 const formattedValueFor = (item: LumenChartSeries, category: number | string) => {
   const value = valueFor(item, category)
 
-  return value === null ? 'Not available' : formatValue(value)
+  return value === null || !Number.isFinite(value) ? 'Not available' : formatValue(value)
 }
 
 const categoryLabelFor = (category: number | string) => {
@@ -92,6 +95,7 @@ const margin = orientation === 'horizontal' ?
   {description}
   {glass}
   {heading}
+  {summary}
   {...rest}
 >
   {

package/components/Chart.astro

@@ -11,6 +11,7 @@ interface Props extends HTMLAttributes<'figure'> {
   glass?: boolean | 'subtle' | 'strong'
   heading?: string
   presentation?: 'bare' | 'default'
+  summary?: string
   value?: string
 }
 
@@ -22,6 +23,7 @@ const {
   glass = false,
   heading,
   presentation = 'default',
+  summary,
   value,
   ...rest
 } = Astro.props
@@ -53,6 +55,7 @@ const { classList, passthrough } = resolveLumenAstroProps(rest, [
       </header>
     )
   }
+  {summary && <p class="ui-sr-only" data-ui-chart-summary>{summary}</p>}
   <slot />
   {caption && <figcaption>{caption}</figcaption>}
 </figure>

package/components/ComboChart.astro

@@ -0,0 +1,118 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import {
+  alignLumenChartSeries,
+  createLumenBarGeometry,
+  createLumenLineGeometry,
+  formatLumenChartSummary,
+  getLumenChartCategories,
+  getLumenChartDomain,
+  getLumenChartToneClassName,
+  hasLumenChartData,
+  type LumenChartDatum,
+  type LumenComboSeries,
+  resolveLumenChartTone } from '@santi020k/lumen-core'
+
+import Chart from './Chart.astro'
+
+interface Props extends HTMLAttributes<'figure'> {
+  caption?: string
+  class?: string | null
+  className?: string
+  description?: string
+  formatValue?: (value: number) => string
+  heading?: string
+  series: readonly LumenComboSeries[]
+  showLegend?: boolean
+  showTable?: boolean
+  summary?: string
+}
+
+const { caption, class: classProp = '', className = '', description, formatValue = String, heading, series, showLegend = true, showTable = true, summary = formatLumenChartSummary(series, formatValue), ...rest } = Astro.props
+const width = 640
+const height = 320
+const padding = 44
+const categories = getLumenChartCategories(series)
+
+const alignedSeries = series.map(item => ({
+  ...item,
+  data: alignLumenChartSeries(item, categories).data
+}))
+
+const domain = getLumenChartDomain(alignedSeries.flatMap(item => item.data.map(datum => datum.y)))
+const barSeries = alignedSeries.filter(item => item.mark === 'bar')
+const lineSeries = alignedSeries.filter(item => item.mark !== 'bar')
+const bars = createLumenBarGeometry(barSeries, { domain, height, width })
+
+const categoryPositions = new Map(
+  bars.categories.map(category => [`${typeof category.category}:${String(category.category)}`, category.x])
+)
+
+const drawableWidth = width - padding * 2
+
+const alignComboLineDatum = (datum: LumenChartDatum): LumenChartDatum => {
+  if (barSeries.length === 0) return datum
+
+  return {
+    ...datum,
+    x: ((categoryPositions.get(`${typeof datum.x}:${String(datum.x)}`) ?? padding) - padding) / drawableWidth
+  }
+}
+
+const lineGeometryOptions = {
+  domain,
+  height,
+  padding,
+  width,
+  ...(barSeries.length === 0 ?
+    {} :
+    {
+      xDomain: { max: 1, min: 0 },
+      xScale: 'linear' as const
+    })
+}
+
+const lines = lineSeries.map(item => createLumenLineGeometry(
+  item.data.map(alignComboLineDatum),
+  lineGeometryOptions
+))
+
+const hasData = hasLumenChartData(series)
+---
+
+<Chart class:list={['ui-combo-chart', classProp, className]} {caption} {description} {heading} {summary} {...rest}>
+  {showLegend && hasData && <ul class="ui-chart__legend" aria-label="Chart legend">{series.map((item, index) => <li class={getLumenChartToneClassName(item.tone, index)}><span aria-hidden="true" />{item.label}</li>)}</ul>}
+  {!hasData && <p class="ui-chart__empty" role="status">No chart data available.</p>}
+  <div class="ui-chart__plot" hidden={!hasData}><svg aria-hidden="true" viewBox={`0 0 ${width} ${height}`}><g class="
+    ui-bar-chart__marks
+  "
+                                                                                                           >{bars.marks.map(mark => <rect class={getLumenChartToneClassName(mark.tone)} height={mark.height} rx="4" width={mark.width} x={mark.x} y={mark.y}><title>{`${mark.seriesLabel}: ${formatValue(mark.value)}`}</title></rect>)}</g>{lines.map((geometry, index) => {
+ const item = lineSeries[index]
+
+ if (!item) return null
+
+ const tone = resolveLumenChartTone(item.tone, index + barSeries.length)
+
+ return (
+<g class:list={['ui-line-chart__series', getLumenChartToneClassName(tone)]}>{item.mark === 'area' && geometry.areaPaths.map(path => (
+<path
+class="ui-line-chart__area"
+d={path}
+/>
+)) }<path
+class="ui-line-chart__line"
+d={geometry.path}
+    /></g>
+)
+})}</svg></div>
+  {showTable && hasData && (
+<details class="ui-chart__data"><summary>View chart data</summary><div><table><thead><tr><th scope="col">Category</th>{series.map(item => <th scope="col">{item.label}</th>)}</tr></thead><tbody>{categories.map(category => (
+<tr><th scope="row">{String(category)}</th>{series.map(item => {
+ const datum = item.data.find(point => point.x === category)
+
+ return <td>{datum?.label ?? (datum?.y === undefined || datum.y === null || !Number.isFinite(datum.y) ? 'Not available' : formatValue(datum.y))}</td>
+})}</tr>
+))}</tbody></table></div></details>
+)}
+</Chart>

package/components/ErrorState.astro

@@ -0,0 +1,118 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import {
+  type LumenErrorStateAnnouncement,
+  type LumenErrorStateKind,
+  type LumenErrorStateLayout,
+  resolveLumenAstroProps
+} from '@santi020k/lumen-core'
+
+import Illustration from './Illustration.astro'
+
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6
+
+const headingTags = {
+  1: 'h1',
+  2: 'h2',
+  3: 'h3',
+  4: 'h4',
+  5: 'h5',
+  6: 'h6'
+} as const
+
+const resolveAnnouncementRole = (
+  announce: LumenErrorStateAnnouncement,
+  role: Props['role']
+): Props['role'] => {
+  if (role) return role
+
+  if (announce === 'assertive') return 'alert'
+
+  if (announce === 'polite') return 'status'
+
+  return undefined
+}
+
+interface Props extends HTMLAttributes<'section'> {
+  announce?: LumenErrorStateAnnouncement
+  class?: string | null
+  className?: string
+  description?: string
+  headingLevel?: HeadingLevel
+  kind?: LumenErrorStateKind
+  layout?: LumenErrorStateLayout
+  reference?: string
+  referenceLabel?: string
+  showGraphic?: boolean
+  title: string
+}
+
+const {
+  'aria-live': ariaLive,
+  announce = 'off',
+  class: classProp = '',
+  className = '',
+  description,
+  headingLevel = 2,
+  id,
+  kind = 'error',
+  layout = 'default',
+  reference,
+  referenceLabel = 'Reference',
+  role,
+  showGraphic = true,
+  title,
+  ...rest
+} = Astro.props
+
+const Heading = headingTags[headingLevel]
+const titleId = id ? `${id}-title` : undefined
+const resolvedLive = ariaLive ?? (announce === 'off' ? undefined : announce)
+const resolvedRole = resolveAnnouncementRole(announce, role)
+
+const { classList, passthrough } = resolveLumenAstroProps(rest, [
+  'ui-error-state',
+  `ui-error-state--${kind}`,
+  `ui-error-state--${layout}`
+], classProp, className)
+---
+
+<section
+  aria-label={titleId ? undefined : title}
+  aria-labelledby={titleId}
+  aria-live={resolvedLive}
+  class:list={classList}
+  data-kind={kind}
+  data-layout={layout}
+  data-ui-error-state
+  id={id}
+  role={resolvedRole}
+  {...passthrough}
+>
+  {showGraphic && (
+    <div class="ui-error-state__graphic" data-slot="error-state-graphic" aria-hidden="true">
+      {Astro.slots.has('graphic') ?
+        (<slot name="graphic" />) :
+        (
+          <Illustration
+            size={layout === 'compact' ? 'sm' : 'md'}
+            variant={kind}
+          />
+        )}
+    </div>
+  )}
+  <div class="ui-error-state__content" data-slot="error-state-content">
+    <Heading class="ui-error-state__title" data-slot="error-state-title" id={titleId}>{title}</Heading>
+    {description && <p class="ui-error-state__description" data-slot="error-state-description">{description}</p>}
+    {Astro.slots.has('default') && <div class="ui-error-state__details" data-slot="error-state-details"><slot /></div>}
+    {reference && (
+      <p class="ui-error-state__reference" data-slot="error-state-reference">
+        <span>{referenceLabel}:</span> <code>{reference}</code>
+      </p>
+    )}
+  </div>
+  {Astro.slots.has('actions') && (
+    <div class="ui-error-state__actions" data-slot="error-state-actions"><slot name="actions" /></div>
+  )}
+</section>

package/components/Heatmap.astro

@@ -0,0 +1,32 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { createLumenHeatmapGeometry, type LumenHeatmapDatum } from '@santi020k/lumen-core'
+
+import Chart from './Chart.astro'
+
+interface Props extends HTMLAttributes<'figure'> {
+  caption?: string
+  class?: string | null
+  className?: string
+  data: readonly LumenHeatmapDatum[]
+  description?: string
+  formatValue?: (value: number) => string
+  heading?: string
+  showTable?: boolean
+  summary?: string
+}
+
+const { caption, class: classProp = '', className = '', data, description, formatValue = String, heading, showTable = true, summary = `${data.filter(item => item.value !== null && Number.isFinite(item.value)).length} available heatmap cells.`, ...rest } = Astro.props
+const geometry = createLumenHeatmapGeometry(data)
+const hasData = geometry.cells.some(cell => cell.value !== null && Number.isFinite(cell.value))
+---
+
+<Chart class:list={['ui-heatmap', classProp, className]} {caption} {description} {heading} {summary} {...rest}>
+  {!hasData && <p class="ui-chart__empty" role="status">No chart data available.</p>}
+  <div class="ui-chart__plot" hidden={!hasData}><svg aria-hidden="true" viewBox={`0 0 ${geometry.width} ${geometry.height}`}><g class="
+    ui-heatmap__cells
+  "
+                                                                                                                             >{geometry.cells.filter(cell => cell.value !== null && Number.isFinite(cell.value)).map(cell => <rect height={Math.max(0, cell.height - 2)} opacity={Math.max(0.12, cell.ratio)} width={Math.max(0, cell.width - 2)} x={cell.xCoordinate + 1} y={cell.yCoordinate + 1}><title>{`${cell.xLabel ?? cell.x} · ${cell.yLabel ?? cell.y}: ${cell.label ?? formatValue(cell.value ?? 0)}`}</title></rect>)}</g></svg></div>
+  {showTable && <details class="ui-chart__data"><summary>View chart data</summary><div><table><thead><tr><th scope="col">Column</th><th scope="col">Row</th><th scope="col">Value</th></tr></thead><tbody>{data.map(cell => <tr><th scope="row">{cell.xLabel ?? cell.x}</th><td>{cell.yLabel ?? cell.y}</td><td>{cell.label ?? (cell.value === null || !Number.isFinite(cell.value) ? 'Not available' : formatValue(cell.value))}</td></tr>)}</tbody></table></div></details>}
+</Chart>

package/components/Illustration.astro

@@ -1,7 +1,10 @@
 ---
 import type { HTMLAttributes } from 'astro/types'
 
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+import {
+  renderLumenIllustrationSvg,
+  resolveLumenAstroProps
+} from '@santi020k/lumen-core'
 
 interface Props extends HTMLAttributes<'span'> {
   class?: string | null
@@ -28,6 +31,8 @@ const { classList, passthrough } = resolveLumenAstroProps(rest, [
   `ui-illustration--${tone}`,
   `ui-illustration--${size}`
 ], classProp, className)
+
+const artwork = renderLumenIllustrationSvg(variant)
 ---
 
 <span
@@ -36,32 +41,5 @@ const { classList, passthrough } = resolveLumenAstroProps(rest, [
   class:list={classList}
   role={label ? 'img' : undefined}
   {...passthrough}
->
-  <svg aria-hidden="true" fill="none" viewBox="0 0 120 120">
-    <circle class="ui-illustration__wash" cx="60" cy="60" r="48" />
-    {variant === 'empty' && (
-      <g>
-        <path d="M32 48h56l-7 35H39l-7-35Z" />
-        <path d="M43 48 49 36h22l6 12M47 66h26" />
-      </g>
-    )}
-    {variant === 'success' && (
-      <g>
-        <circle cx="60" cy="60" r="28" />
-        <path d="m45 60 10 10 21-23" />
-      </g>
-    )}
-    {variant === 'error' && (
-      <g>
-        <circle cx="60" cy="60" r="28" />
-        <path d="m49 49 22 22m0-22L49 71" />
-      </g>
-    )}
-    {variant === 'offline' && (
-      <g>
-        <path d="M37 74h44a14 14 0 0 0 1-28 23 23 0 0 0-42-4 16 16 0 0 0-3 32Z" />
-        <path d="m38 34 44 52" />
-      </g>
-    )}
-  </svg>
-</span>
+  set:html={artwork}
+/>

package/components/Image.astro

@@ -10,25 +10,32 @@ import { resolveLumenAstroProps } from '@santi020k/lumen-core'
 type Props = (LocalImageProps | RemoteImageProps) & {
   class?: string | null
   className?: string
+  fit?: 'contain' | 'cover'
   invertOnDark?: boolean
+  radius?: 'full' | 'lg' | 'md' | 'none' | 'sm'
 }
 
 const {
   class: classProp = '',
   className = '',
+  fit = 'cover',
   invertOnDark = false,
   loading = 'lazy',
+  radius = 'lg',
   ...rest
 } = Astro.props
 
 const { classList, passthrough } = resolveLumenAstroProps(rest, [
   'ui-image',
-  invertOnDark && 'ui-image--invert-dark'
+  invertOnDark && 'ui-image--invert-dark',
+  `ui-image--fit-${fit}`,
+  `ui-image--radius-${radius}`
 ], classProp, className)
 ---
 
 <AstroImage
   loading={loading}
   class:list={classList}
+  fit={fit}
   {...passthrough}
 />

package/components/LineChart.astro

@@ -4,6 +4,7 @@ import type { HTMLAttributes } from 'astro/types'
 import {
   alignLumenChartSeries,
   createLumenLineGeometry,
+  formatLumenChartSummary,
   getLumenChartCategories,
   getLumenChartDomain,
   getLumenChartTicks,
@@ -33,6 +34,7 @@ interface Props extends HTMLAttributes<'figure'> {
   series: readonly LumenChartSeries[]
   showLegend?: boolean
   showTable?: boolean
+  summary?: string
 }
 
 const {
@@ -51,6 +53,7 @@ const {
   series,
   showLegend = series.length > 1,
   showTable = true,
+  summary = formatLumenChartSummary(series, formatValue),
   ...rest
 } = Astro.props
 
@@ -99,6 +102,7 @@ const referenceY =
   {description}
   {glass}
   {heading}
+  {summary}
   {...rest}
 >
   {
@@ -227,7 +231,7 @@ const referenceY =
                     return (
                       <td>
                         {datum?.label ??
-                          (datum?.y === null || datum === undefined ?
+                          (datum?.y === undefined || datum.y === null || !Number.isFinite(datum.y) ?
                             'Not available' :
                             formatValue(datum.y))}
                       </td>