@santi020k/lumen-astro 3.0.1 → 4.1.0

package/README.md

@@ -1,10 +1,79 @@
-# @santi020k/lumen-astro
+<p align="center">
+  <a href="https://lumen.santi020k.com">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/santi020k/lumen/main/docs/assets/readme/package-dark.svg">
+      <img src="https://raw.githubusercontent.com/santi020k/lumen/main/docs/assets/readme/package-light.svg" alt="Lumen UI — Web. Native. Thoughtfully connected." width="1200" height="184">
+    </picture>
+  </a>
+</p>
+
+<h1 align="center">Lumen UI · Astro</h1>
+
+<p align="center">Reference components · Progressive enhancement · Standalone CSS</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@santi020k/lumen-astro"><img src="https://img.shields.io/npm/v/@santi020k/lumen-astro?style=flat-square&color=0369a0" alt="npm version"></a>
+  <a href="https://github.com/santi020k/lumen/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-13967e?style=flat-square" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="https://lumen.santi020k.com/docs/frameworks/astro">Documentation</a>
+  ·
+  <a href="https://www.npmjs.com/package/@santi020k/lumen-astro">npm</a>
+  ·
+  <a href="https://github.com/santi020k/lumen/tree/main/packages/astro">Source</a>
+  ·
+  <a href="https://github.com/santi020k/lumen/issues">Issues</a>
+</p>
+
+**Package:** `@santi020k/lumen-astro`
+
+**On this page:** [Install](#install) · [Appearance presets](#appearance-presets) · [Resources](#resources)
+
+<details>
+<summary>Browse all sections</summary>
+
+- [Install](#install)
+- [Appearance presets](#appearance-presets)
+- [Compound interactive components](#compound-interactive-components)
+- [Context navigation](#context-navigation)
+- [Forms and Astro Actions](#forms-and-astro-actions)
+- [Error states](#error-states)
+- [Long-form navigation](#long-form-navigation)
+- [Data visualization](#data-visualization)
+- [Code tabs](#code-tabs)
+- [Optimized images](#optimized-images)
+- [Kanban boards](#kanban-boards)
+- [Motion](#motion)
+- [Glass surfaces](#glass-surfaces)
+- [Semantic stat roots](#semantic-stat-roots)
+- [Consumer composition recipes](#consumer-composition-recipes)
+- [Exact amount fields](#exact-amount-fields)
+- [Phone presentation in v4](#phone-presentation-in-v4)
+- [Combobox keyboard behavior](#combobox-keyboard-behavior)
+- [Content flow](#content-flow)
+- [Attachment composition](#attachment-composition)
+- [Chart datum actions](#chart-datum-actions)
+- [Dashboard composition](#dashboard-composition)
+- [Visual interactions and product blocks](#visual-interactions-and-product-blocks)
+- [Device demonstrations](#device-demonstrations)
+- [World map](#world-map)
+- [Studio media workspace](#studio-media-workspace)
+- [Resources](#resources)
+
+</details>
 
 Production-ready Astro primitives for Lumen UI. The stylesheet is standalone CSS, so no Tailwind
 configuration is required to render the components.
 
+Form controls use `visualSize` (`visual-size` in Elements) with `default`, `sm` and `lg`.
+Select, PhoneInput and Segmented follow Input and NativeSelect; numeric input/select `size` keeps
+its native meaning. See the [v4 migration guide](https://github.com/santi020k/lumen/blob/main/docs/migrating-v3-to-v4.md#form-control-visual-sizing).
+
 ## Install
 
+Requires Astro 5 or newer in the consuming application.
+
 ```bash
 pnpm add @santi020k/lumen-astro
 ```
@@ -53,11 +122,11 @@ import UIPrimitives from '@santi020k/lumen-astro/runtime'
 
 ```astro
 ---
-import { Button, Card, Input } from '@santi020k/lumen-astro'
+import { Button, Card, Input, Label } from '@santi020k/lumen-astro'
 ---
 
 <Card>
-  <label for="email">Email</label>
+  <Label for="email">Email</Label>
   <Input id="email" type="email" placeholder="you@example.com" />
   <Button>Subscribe</Button>
 </Card>
@@ -74,7 +143,10 @@ import { Button, Card, Input } from '@santi020k/lumen-astro'
 `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.
+`ui:phone-change` event with a `LumenPhoneNumber` detail. Validation messages and inherited locale
+resolve in the phone control's owning document, including after iframe adoption. Repeated runtime
+initialization binds adopted phone controls to their current reset root; reset synchronization follows
+the current form owner and honors cancellation without duplicating edit listeners.
 
 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.
@@ -83,16 +155,36 @@ contains `PhoneInput`; pages without the component do not evaluate or download t
 <PhoneInput countryValue="CO" locale="en-US" name="hospitalPhone" />
 ```
 
+## Appearance presets
+
+Set `data-lumen-preset="studio"` and an optional `data-lumen-scheme="light|dark"` on the application root. See [appearance presets](https://github.com/santi020k/lumen/blob/main/docs/appearance-presets.md) for Default, Studio, Glass and scoped customization.
+
 ## 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.
 
+Disclosure keyboard navigation skips hidden or inert regions, invisible controls, and native
+disabled controls, including a disabled fieldset. Available controls in a fieldset's first legend
+retain their native keyboard behavior; removing `inert` makes a region available again.
+
+Mentions keeps suggestion navigation on the textarea through `aria-activedescendant`; suggestion
+buttons are excluded from the Tab sequence. Returning focus before the delayed blur dismissal
+preserves reopened suggestions. Static Toast markup is enhanced again after client
+navigation, retaining Escape dismissal without duplicate listeners.
+
 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.
 
+Keyboard tab navigation skips disabled triggers and stays within the current group when tabs are nested.
+Dialogs preserve native `autofocus`, restore their connected opener on close, and dismiss only a
+backdrop press that starts and ends outside the dialog. Alert dialogs retain explicit dismissal.
+
 ```astro
 ---
 import {
@@ -211,7 +303,7 @@ announcement.
 </ErrorState>
 ```
 
-See the repository [Astro error-handling guide](../../docs/error-handling.md#astro) for the complete
+See the repository [Astro error-handling guide](https://github.com/santi020k/lumen/blob/main/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.
@@ -247,6 +339,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.
@@ -266,6 +376,17 @@ sync with the accessible label; free-form default children remain the idle prese
 
 ## Data visualization
 
+The web visualization milestone adds `WaterfallChart` for signed changes and explicit totals, and
+`Histogram` for precomputed numeric bins (`frequency="density"` for unequal widths). Line charts
+support explicit continuous axes, annotations, optional keyboard/pointer/touch inspection, and
+synchronized cursors. Heatmaps show labeled axes, a color legend, and explicit missing cells.
+See the [visualization contracts](https://github.com/santi020k/lumen/blob/main/docs/data-visualization.md) and
+[interactive web example](https://lumen.santi020k.com/docs/web/data-visualization).
+
+Set `interactive` on `LineChart` and mount `UIPrimitives` to enable inspection and legend buttons.
+Static charts continue to render without client JavaScript. After moving an enhanced chart into another
+document, rerun `UIPrimitives` initialization so cursor synchronization follows that document's peers.
+
 Use `Sparkline` beside a metric, `BarChart` for categorical comparison, `LineChart` for ordered
 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,
@@ -291,7 +412,7 @@ const series = [{
 `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,
+useful domain context. See [data visualization](https://github.com/santi020k/lumen/blob/main/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
@@ -395,6 +516,17 @@ content readable without JavaScript and honor reduced-motion preferences.
 <AnimatedNumber decimals={1} suffix="%" value={99.8} />
 ```
 
+With the optional motion stylesheet, native `Collapsible` and `Accordion` content smoothly expands and collapses in browsers supporting
+`::details-content` and `interpolate-size`. Other browsers retain the immediate native toggle.
+Dialogs, drawers, sheets, menus, and toasts retain their existing shared-token transitions.
+
+For optional insertion, removal, or state feedback, use
+[`animateLumenPresence`](https://github.com/santi020k/lumen/blob/main/packages/core/README.md#presence-motion) on a DOM reference. Applications keep
+ownership of state, focus, and DOM removal. Set `data-ui-motion="reduce"` on a container for a local
+reduced-motion preference; the system preference is always respected.
+Try dialogs, bottom drawers, and side sheets in the [motion playground](https://lumen.santi020k.com/docs/motion-playground).
+System reduced motion shortens both panel and backdrop transitions.
+
 ## Glass surfaces
 
 Lumen includes glassmorphism tokens and reusable classes in the shared stylesheet. Cards use a
@@ -425,7 +557,292 @@ or `variant="glass"` for selective translucency.
 
 ## Consumer composition recipes
 
-See [consumer UI recipes](../../docs/consumer-ui-recipes.md) for static React icons, responsive
+See [consumer UI recipes](https://github.com/santi020k/lumen/blob/main/docs/consumer-ui-recipes.md) for static React icons, responsive
 record tables, keyboard-aware native sheets, whole-unit amount fields, adaptive editors, and
 asynchronous action states. Each recipe identifies the public primitives and the behavior that
 remains owned by the application.
+
+## Exact amount fields
+
+`AmountField` formats an ASCII decimal-string `value` in the requested locale and submits a
+complete ungrouped value through its named hidden input. Include `UIPrimitives` for editing,
+validity and reset behavior. Domain validation and monetary units remain application-owned.
+
+```astro
+<AmountField name="amount" locale="es-CO" value="1234.50" aria-label="Amount COP" />
+<UIPrimitives />
+```
+
+See [consumer workflows](https://github.com/santi020k/lumen/blob/main/docs/consumer-ui-recipes.md#executable-consumer-workflows).
+
+### Accessible documentation controls
+
+`Code` and `CodeTabs` accept `copyLabel`, `copiedLabel`, `errorLabel`, and
+`codeLabel` strings. The first three customize clipboard controls and their live
+success/error feedback; `codeLabel` names the keyboard-focusable region for an
+unwrapped code block. A denied or unavailable clipboard reports the error label
+and keeps the source available for manual selection. `CodeTabs` forwards these
+labels to each code example.
+
+`Code` with `highlighted` enhances the supplied `pre` when the Astro runtime loads.
+For keyboard scrolling before JavaScript loads, give that `pre` `tabindex="0"`,
+`role="region"`, and an accessible name; existing attributes are preserved.
+Wrapped blocks do not add an extra tab stop.
+
+`NavigationMenu` contains ordinary site links, so every enabled link remains in
+native Tab order. Use `Menubar` or `Toolbar` for their documented composite-widget
+keyboard behavior. A `ThemeToggle` with `controlled` respects the host theme at
+initialization and leaves persistence and theme changes to its owner.
+
+### Virtual list and editor ownership
+
+`VirtualList` displays fixed-height rows with inert spacers that retain the full scroll extent.
+Rows stay mounted; use pagination when the initial DOM cost matters. Scrolling, resizing, sizing
+changes and direct row changes refresh the window. Focused rows remain available. After document
+adoption, rerun the standard initializer to rebind the controller to the destination document. See the
+[fixed-height list contract](https://github.com/santi020k/lumen/blob/main/docs/ai-usage.md#fixed-height-virtual-lists).
+
+External rich-text engines should handle the cancelable `ui:editor-command-request` event before
+execution and use `ui:editor-command` only for completion notifications. React also supports
+`useRichTextEditor({ commandHandler })`. Disable native toolbar state syncing when the external
+engine owns it. See the [editor guidance](https://github.com/santi020k/lumen/blob/main/docs/ai-usage.md).
+
+## Phone presentation in v4
+
+Phone inputs bundle the same offline flag artwork on every platform. The selected country shows
+its flag and calling code inside one continuous input border. Country names remain in the native
+picker and its accessible name; flags are supplementary. Unknown flag codes fall back to text.
+
+Astro and React `PhoneInput` accept `disabled`, `readOnly`, `required`, `errorMessage`,
+`showValidationError`, and `inputProps`. Their `id` targets the number input in v4; React also
+accepts `inputRef`. Web Components use `disabled`, `readonly`, `required`, `error-message`,
+`show-validation-error="false"`, and `input-id`, with native input attributes on the host.
+Both controls lock together and validation remains associated with the input. Astro forwards
+`inputProps.form` to the number input, country picker and read-only country fallback so external
+form submission and reset include every part.
+
+The `phone-input`, `phone-country`, and `country-flag` styling parts plus `--ui-phone-height`,
+`--ui-phone-padding`, and `--ui-phone-country-gap` replace consumer CSS overlays.
+
+Astro and React also export `CountryFlag` (`regionCode`, optional `decorative`) and `PhoneNumber`
+(`value: LumenPhoneNumber`, optional `link`). A telephone link is rendered only for a complete
+E.164 value. Use the model returned by the phone normalizer; keep domain persistence in your app.
+Artwork attribution is shipped with the core package in `PHONE_FLAG_LICENSE.txt`.
+
+## Combobox keyboard behavior
+
+In v4, Combobox retains input focus and exposes its active option through `aria-activedescendant`.
+Enter commits an active option; text editing and composition remain native. Escape dismisses one
+nested control at a time. See the [shared keyboard contract](https://github.com/santi020k/lumen/blob/main/docs/ai-usage.md#combobox-keyboard-behavior-in-v4)
+for dynamic options, controlled inputs and migration guidance.
+
+## Content flow
+
+Stack and Grid own sibling spacing. Their gap accepts `related`, `group` (default) and `section`,
+or canonical `none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl` sizes. Card owns the inset and gap
+between its visible parts; use `density="compact"`, `"comfortable"` (default) or `"spacious"`.
+Elements uses the same names as attributes. Use a nested Stack for CardContent groups and Field
+for label/control/feedback. See [content flow](https://github.com/santi020k/lumen/blob/main/docs/content-flow.md) and the
+[v4 migration guide](https://github.com/santi020k/lumen/blob/main/docs/migrating-to-lumen.md) for ownership and changed explicit gaps.
+
+### Reading and complete compositions
+
+Prose and Typography trim outer child margins and separate headings from preceding text.
+Container gutters grow from 16px to 32px with viewport width; override `--ui-container-gutter`
+when a product needs fixed gutters. Card allows interactive overflow; use AspectRatio to clip media.
+Install `content-flow-header`, `content-flow-settings`, `content-flow-list` or `content-flow-actions`
+with `lumen add <recipe> --target astro|react|elements`. MCP returns the same complete examples.
+Connect application actions and replace sample IDs before reuse. See
+[content flow](https://github.com/santi020k/lumen/blob/main/docs/content-flow.md) for composition and migration guidance.
+
+### Large fixed-height collections
+
+`VirtualList` supports an empty `mode="data"` root with the public Core data controller.
+Only the visible window, overscan and focused neighbors mount. Stable keys retain row identity;
+applications own offscreen editing state. See [data rendering](https://github.com/santi020k/lumen/blob/main/docs/virtual-list-data.md) for
+setup, lifecycle, accessibility and the mounted-mode tradeoff.
+
+Action-error normalization ignores malformed fields and non-string messages. Enhanced forms include
+externally associated native controls. Reinitialize with `LumenInitUiPrimitives(destination)` after
+adopting an enhanced form into another document so blur validation follows its owner, including
+controls created in another document. Timed toasts stay paused while hovered or focused.
+
+### Compound dialog tasks
+
+Use `DialogHeader`, `DialogTitle`, `DialogBody`, `DialogFooter`, and `DialogClose`
+for long forms. Associate the title explicitly so labeling works before enhancement.
+`DialogBody` must be a direct child of `Dialog` for independent scrolling. Footer
+submit actions target a form inside the body with the native `form` attribute.
+
+```astro
+<Dialog id="record-dialog" aria-labelledby="record-title">
+  <DialogHeader><DialogTitle id="record-title">Edit record</DialogTitle></DialogHeader>
+  <DialogBody><Form id="record-form"><Input name="name" aria-label="Name" /></Form></DialogBody>
+  <DialogFooter>
+    <DialogClose variant="outline">Cancel</DialogClose>
+    <Button type="submit" form="record-form">Save</Button>
+  </DialogFooter>
+</Dialog>
+```
+
+Mount `UIPrimitives` once and open the dialog with a button carrying
+`data-ui-dialog-trigger="record-dialog"`. Set `selectedFilesLabel="{count} files selected"`
+on `FileUpload` to supply localized multiple-file feedback; the single-file label is its filename.
+A trigger ignores its own click when that click arrives canceled (`event.preventDefault()`) or
+when the trigger matches `:disabled` or `[aria-disabled="true"]`, matching close control behavior.
+Register cancellation listeners before the runtime binds the trigger. Activating a trigger for an
+already open dialog preserves its mode and original focus-return target.
+
+### Rich description rows
+
+Use `Descriptions` with `DescriptionItem`, `DescriptionTerm`, and `DescriptionDetail`
+when a value contains links, badges, formatted dates, or actions. Astro renders a
+native `dl` containing `div`, `dt`, and `dd` elements. The existing `items` array
+remains available and can be combined with child rows.
+
+```astro
+<Descriptions>
+  <DescriptionItem>
+    <DescriptionTerm>Status</DescriptionTerm>
+    <DescriptionDetail><Badge variant="success">Active</Badge></DescriptionDetail>
+  </DescriptionItem>
+</Descriptions>
+```
+
+## Attachment composition
+
+Use `AttachmentList` to group native `li` children and `AttachmentPreview` for browser-owned images
+with localized loading, error, and unsupported-file states. Compose independent actions rather
+than nesting controls inside a linked Attachment. The application retains file validation,
+authorization, persistence, and object URL cleanup. See the
+[attachment composition recipe](https://github.com/santi020k/lumen/blob/main/docs/consumer-ui-recipes.md#attachment-previews-and-file-lists)
+for adapter props, slots, child contracts, retry identity, and safe state events.
+
+## Chart datum actions
+
+Set `drilldown` on BarChart, LineChart, PieChart, ScatterChart, ComboChart, Heatmap, or RangeChart
+and mount `UIPrimitives` once. Each available plotted datum has a corresponding native button in
+the actions disclosure, including when `showTable={false}`. Marks remain decorative to assistive
+technology. The figure emits `ui:chart-datum-activate` with a validated
+`LumenChartDatumActivationDetail`; apps decide whether to navigate, filter, or open a detail view.
+
+Translate `labels.exploreData` and `labels.formatDatumAction(context)`, and format visible values
+with the chart's existing formatters. Missing observations have no action; pie actions cover only
+positive slices. A line's `markers="none"` hides visible markers while retaining pointer targets
+and native keyboard actions. See [data visualization](https://github.com/santi020k/lumen/blob/main/docs/data-visualization.md#astro-chart-actions).
+
+## Dashboard composition
+
+`FilterBar` groups host-owned filtering controls, active criteria, reset actions, and a polite
+result announcement. `ChangeSummary` presents explicit before/after values and application-owned
+changed state. Neither component owns requests, persistence, parsing, or financial policy.
+
+ScatterChart supports independent X/Y formatting, explicit domains, logarithmic positive X values,
+and labeled reference lines/regions. Automatic domains leave room for complete bubbles; explicit
+domain limits stay exact and can intentionally crop marks. ComboChart and RangeChart include
+category labels and value scales. See [consumer UI recipes](https://github.com/santi020k/lumen/blob/main/docs/consumer-ui-recipes.md)
+for dashboard tables, freshness, import review, activity inbox, and persistent Kanban patterns.
+
+### Actual-versus-target charts
+
+`BulletChart` compares a nullable actual `value` with a finite `target` and optional
+labeled `ranges`. A strong actual bar, target marker, readable value labels, and expandable exact
+data work together. Domains include zero and all measurements; invalid inputs fail closed, including malformed range containers.
+Null values stay distinct from zero. See the [chart guide](https://github.com/santi020k/lumen/blob/main/docs/data-visualization.md#actual-values-and-targets)
+for the input, localization, and domain contracts.
+
+### Rankings and paired comparisons
+
+Use `LollipopChart` for zero-based rankings and `DumbbellChart` for paired measurements (native
+`LumenLollipopChart` and `LumenDumbbellChart`). Supply ordered comparison data with `id`, `label`,
+nullable `value`, optional nullable `reference`, and optional `tone`. Both charts preserve missing
+values and expose exact data. See the [shared visualization contract](https://github.com/santi020k/lumen/blob/main/docs/data-visualization.md#rankings-and-paired-comparisons).
+
+### Calendars, funnels, and distributions
+
+Use `CalendarHeatmap` for daily date-only observations with an explicit start/end range,
+`FunnelChart` for ordered nonnegative stages, and `BoxPlot` for precomputed quartiles, whiskers,
+and outliers. All retain missing values and expose exact data. See the
+[data visualization guide](https://github.com/santi020k/lumen/blob/main/docs/data-visualization.md#calendars-funnels-and-box-plots).
+
+Media controllers for ImageComparison and FileUpload load only when matching components are present.
+Keep mounting `UIPrimitives` once; no additional consumer setup is required. Image comparisons
+follow their current native form owner for reset and honor canceled resets. Reinitialize after
+document adoption to register destination reset delegation without duplicate input listeners.
+
+## Visual interactions and product blocks
+
+See [visual interactions](https://github.com/santi020k/lumen/blob/main/docs/visual-interactions.md) for keyed motion, semantic effects,
+chart continuity, AI surfaces, optional SDK integrations, and the four installable product recipes.
+Import `@santi020k/lumen/styles/motion.css` alongside the base stylesheet to opt into native
+disclosure height transitions and the CSS reduction scope. This small optional stylesheet works
+with Astro, React, and Elements and keeps those effects out of the default stylesheet. The presence
+helper's system and local reduced-motion checks work without this CSS import.
+
+## Device demonstrations
+
+`DeviceFrame` presents slotted HTML, an image, or a titled iframe inside `macbook-pro`, `macbook-air`, `imac`,
+`iphone`, `pixel`, and `ipad-pro` frames, with generic `laptop`, `desktop`, `android`, and `tablet` options.
+Device-specific enclosures include a MacBook Pro display notch and full front edge, a tapered MacBook Air deck, curved iMac
+stand and chin, rounded phone glass with separate rails and buttons, and an iPad Pro with even
+bezels and no Home button. The generic `tablet` retains its classic enclosure.
+Shells are decorative and do not emulate device hardware. `orientation` selects portrait or landscape; `tone` selects
+light or dark chrome independently of the screen content. Use `color="white"`,
+`color="black"`, or a 3-, 4-, 6-, or 8-digit hex color such as `color="#a9b8ac"` for
+a custom hardware finish. `color` takes precedence over `tone`; invalid values fall back to the
+tone. The finish stays independent of the content theme. For CSS-driven updates, set
+`--ui-device-color` to a CSS color on the frame.
+
+Iframe layouts use the preset screen viewport and scale to the available width. Override
+`screenWidth` and `screenHeight` for a custom viewport (1–16384 CSS pixels). Slotted HTML shares
+the host viewport; container queries can adapt it to the screen. Images preserve their proportions.
+`scroll={false}` clips HTML overflow; an iframe manages its own scrolling.
+
+Supply image alternative text and iframe titles. Consumers own iframe `sandbox`, `allow`,
+loading, and referrer policies. Remote sites can refuse embedding through their response headers.
+The decorative shell does not alter focus or intercept interactions. Camera and home-indicator
+details occupy separate chrome outside live HTML and iframe viewports. Direct phone images extend
+under the decorative camera and home indicator for a full-bleed presentation.
+Screen presets are 1280 × 800 for MacBook Pro and MacBook Air, 1440 × 810 for iMac, 390 × 844 for iPhone,
+412 × 915 for Pixel, and 834 × 1194 for iPad Pro (1194 × 834 in landscape). These are demonstration
+viewports, not physical display specifications.
+
+```astro
+---
+import { DeviceFrame } from '@santi020k/lumen-astro'
+---
+<DeviceFrame device="iphone">
+  <iframe src="/demo" title="Mobile application demo" loading="lazy"></iframe>
+</DeviceFrame>
+```
+
+The component bundles its resize behavior; `UIPrimitives` is not required for this frame.
+
+## World map
+
+WorldMap supports highlighted countries, location markers, dotted or solid styles, country selection,
+and theme customization. Use `initialView="highlighted"` (Elements: `initial-view`) to start with a
+regional view. Zoom toward the cursor with Ctrl/Cmd-scroll, or fit highlighted countries using the
+map controls. Adopted maps emit selection events in their current document; reinitialization follows
+interaction mode changes without duplicating listeners or resetting zoom. Import geography explicitly from
+`@santi020k/lumen-core/world-map-data`; it is excluded from root exports. See the
+[WorldMap usage guide](https://github.com/santi020k/lumen/blob/main/docs/world-map.md) for adapter examples, events, localization,
+accessibility, and customization.
+
+## Studio media workspace
+
+Compose MediaViewport, MediaThumbnail, MediaFilmstrip and ImageComparison modes with the
+[Studio media workspace recipes](https://github.com/santi020k/lumen/blob/main/docs/studio-media-workspaces.md). Applications retain
+media loading, selection, adjustment algorithms, processing, export and persistence.
+
+## Resources
+
+| Guide | What you will find |
+| --- | --- |
+| [Styling contract](https://github.com/santi020k/lumen/blob/main/docs/styling-contract.md) | Stable styling parts, component variables, and overrides. |
+| [Error handling](https://github.com/santi020k/lumen/blob/main/docs/error-handling.md) | Field feedback, summaries, alerts, and recovery surfaces. |
+| [Contributing](https://github.com/santi020k/lumen/blob/main/CONTRIBUTING.md) | Setup, checks, and contribution workflow. |
+| [Release history](https://github.com/santi020k/lumen/releases) | Published releases and version notes. |
+
+Part of [Lumen UI](https://lumen.santi020k.com), created by [Santiago Molina](https://santi020k.com).
+Licensed under [MIT](https://github.com/santi020k/lumen/blob/main/LICENSE); third-party artwork retains its own notices.

package/components/AmountField.astro

@@ -0,0 +1,21 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { formatLumenAmountDraft, getLumenAmountValue, type LumenAmountOptions, resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends Omit<HTMLAttributes<'input'>, 'value' | 'type' | 'min' | 'max' | 'step'>, LumenAmountOptions {
+  value?: string
+  defaultValue?: string
+  invalidMessage?: string
+  className?: string
+}
+
+const { value, defaultValue, locale = 'en-US', fractionDigits = 2, allowNegative = false, invalidMessage, name, form, disabled, class: classProp = '', className = '', ...rest } = Astro.props
+const initial = value ?? defaultValue ?? ''
+const { classList, passthrough } = resolveLumenAstroProps(rest, ['ui-input', 'ui-amount-field'], classProp, className)
+---
+
+<span data-ui-amount-field locale={locale} fraction-digits={fractionDigits} allow-negative={allowNegative ? '' : undefined} value={value} default-value={defaultValue ?? initial} invalid-message={invalidMessage}>
+  <input {...passthrough} class:list={classList} data-ui-amount-input type="text" inputmode="decimal" value={formatLumenAmountDraft(initial, { locale, fractionDigits, allowNegative })} form={form} disabled={disabled} />
+  <input data-ui-amount-value type="hidden" name={name} form={form} disabled={disabled} value={getLumenAmountValue(initial) ?? ''} />
+</span>

package/components/AnimatedNumber.astro

@@ -28,7 +28,7 @@ const {
   ...rest
 } = Astro.props
 
-const safeDecimals = Math.max(0, Math.min(20, Math.floor(decimals)))
+const safeDecimals = Math.max(0, Math.min(20, (Math.floor(decimals) || 0)))
 
 const formatter = new Intl.NumberFormat(locale, {
   maximumFractionDigits: safeDecimals,

package/components/ApprovalCard.astro

@@ -0,0 +1,30 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import type { LumenApprovalStatus } from '@santi020k/lumen-core'
+
+import Button from './Button.astro'
+import Card from './Card.astro'
+import Stack from './Stack.astro'
+
+interface Props extends HTMLAttributes<'div'> {
+  approveLabel?: string
+  disabled?: boolean
+  label: string
+  rejectLabel?: string
+  requestId: string
+  status?: LumenApprovalStatus
+  statusLabel: string
+}
+
+const { approveLabel = 'Approve', class: className, disabled = false, label, rejectLabel = 'Reject', requestId, status = 'pending', statusLabel, ...rest } = Astro.props
+---
+
+<Card {...rest} aria-label={label} class:list={['ui-approval-card', className]} data-disabled={String(disabled)} data-ui-approval-card data-request-id={requestId} data-status={status}>
+  <Stack gap="group"><strong>{label}</strong><slot /><span role="status">{statusLabel}</span>
+    <Stack direction="horizontal" gap="related" wrap>
+      <Button data-ui-approval-response="approve" disabled={disabled || status !== 'pending'} type="button">{approveLabel}</Button>
+      <Button data-ui-approval-response="reject" disabled={disabled || status !== 'pending'} type="button" variant="secondary">{rejectLabel}</Button>
+    </Stack>
+  </Stack>
+</Card>

package/components/AttachmentList.astro

@@ -0,0 +1,15 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'ul'> {
+  class?: string | null
+  className?: string
+}
+
+const { class: classProp = '', className = '', ...rest } = Astro.props
+const { classList, passthrough } = resolveLumenAstroProps(rest, ['ui-attachment-list'], classProp, className)
+---
+
+<ul class:list={classList} data-slot="attachment-list" {...passthrough}><slot /></ul>

package/components/AttachmentPreview.astro

@@ -0,0 +1,51 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import {
+  type LumenAttachmentPreviewLabels,
+  lumenAttachmentPreviewLabels,
+  type LumenAttachmentPreviewState,
+  resolveLumenAstroProps,
+  resolveLumenAttachmentPreviewState
+} from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'figure'> {
+  alt: string
+  class?: string | null
+  className?: string
+  contentType?: string
+  labels?: Partial<LumenAttachmentPreviewLabels>
+  retryKey?: number | string
+  src?: string
+  state?: LumenAttachmentPreviewState
+}
+
+const { alt, class: classProp = '', className = '', contentType, labels, retryKey, src, state: requested, ...rest } = Astro.props
+const state = resolveLumenAttachmentPreviewState(src, contentType, requested)
+const canPreview = resolveLumenAttachmentPreviewState(src, contentType) === 'ready'
+const copy = { ...lumenAttachmentPreviewLabels, ...labels }
+const { classList, passthrough } = resolveLumenAstroProps(rest, ['ui-attachment-preview'], classProp, className)
+---
+
+<figure
+class:list={classList}
+{...passthrough}
+aria-busy={state === 'loading'}
+data-state={state}
+  data-ui-attachment-preview
+data-ui-attachment-preview-state={requested}
+  data-ui-attachment-preview-content-type={contentType}
+data-ui-attachment-preview-retry-key={retryKey}
+  data-ui-attachment-preview-error-label={copy.error}
+data-ui-attachment-preview-loading-label={copy.loading}
+  data-ui-attachment-preview-unavailable-label={copy.unavailable}
+>
+  <div data-slot="attachment-preview-media" hidden={state !== 'ready'}>
+    {/* Browser-owned private URLs and object URLs must not enter Astro's server image optimizer. */}
+    {canPreview && <img src={src} alt={alt} data-ui-attachment-preview-image loading="eager" />}
+  </div>
+  <p role="status" data-slot="attachment-preview-fallback" data-ui-attachment-preview-message hidden={state === 'ready'}>{state === 'ready' ? '' : copy[state]}</p>
+  {Astro.slots.has('caption') && <figcaption><slot name="caption" /></figcaption>}
+  <slot />
+  {Astro.slots.has('actions') && <div data-slot="attachment-preview-actions"><slot name="actions" /></div>}
+</figure>

package/components/Avatar.astro

@@ -30,6 +30,8 @@ const { classList, passthrough } = resolveLumenAstroProps(rest, [
 
 <span
   class:list={classList}
+  role={!src && alt ? 'img' : undefined}
+  aria-label={!src && alt ? alt : undefined}
   {...passthrough}
 >
   {src ? <img alt={alt} src={src} /> : fallbackText && <span aria-hidden={fallback ? undefined : 'true'}>{fallbackText}</span>}