@santi020k/lumen-astro 0.4.0 → 1.1.0

package/README.md

@@ -51,6 +51,44 @@ import { Button, Card, Input } from '@santi020k/lumen-astro'
 </Card>
 ```
 
+`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.
+
+```astro
+<Input size={32} visualSize="sm" />
+<NativeSelect size={8} visualSize="lg" />
+```
+
+## Forms and Astro Actions
+
+`Form` renders a semantic form and preserves native `method`, `action`, `enctype`, autocomplete,
+reset, and no-JavaScript submission. Compose it with `Field`, `Label`, `FieldError`, and
+`ErrorSummary`.
+
+Astro Actions remain application-owned. Use `accept: 'form'`, read the result with
+`Astro.getActionResult()`, and pass `ActionInputError` to `normalizeAstroActionErrors()` so field
+errors receive stable control IDs.
+
+```astro
+---
+import { actions, isInputError } from 'astro:actions'
+import { ErrorSummary, Form, normalizeAstroActionErrors } from '@santi020k/lumen-astro'
+
+const result = Astro.getActionResult(actions.updateProfile)
+const errors = result?.error && isInputError(result.error)
+  ? normalizeAstroActionErrors(result.error)
+  : normalizeAstroActionErrors(result?.error)
+---
+
+<Form action={actions.updateProfile} method="POST">
+  <ErrorSummary {errors} />
+  <!-- fields -->
+</Form>
+```
+
+See the [Astro Actions form guide](https://lumen.santi020k.com/docs/forms/astro-actions).
+
 Use `Icon` for Lucide icons by name across framework adapters.
 
 ```astro
@@ -67,13 +105,14 @@ import { Button, Icon } from '@santi020k/lumen-astro'
 
 ## Long-form navigation
 
-`Anchor` accepts an optional heading `depth` so article tables of contents can preserve their
-hierarchy. `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.
+`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.
+`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.
 
 ```astro
 ---
-import { Anchor, ScrollProgress } from '@santi020k/lumen-astro'
+import { Anchor, CopyButton, ScrollProgress } from '@santi020k/lumen-astro'
 ---
 
 <ScrollProgress aria-label="Article reading progress" />
@@ -83,6 +122,15 @@ import { Anchor, ScrollProgress } from '@santi020k/lumen-astro'
 ]} />
 ```
 
+`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.
+
+```astro
+<p id="invite">Join the Lumen workspace</p>
+<CopyButton target="#invite" toast>Copy invite</CopyButton>
+```
+
 ## Data visualization
 
 Use `Sparkline` beside a metric, `BarChart` for categorical comparison, `LineChart` for ordered
@@ -204,8 +252,7 @@ content readable without JavaScript and honor reduced-motion preferences.
 
 Lumen includes glassmorphism tokens and reusable classes in the shared stylesheet. Cards use a
 boolean prop, and overlays or navigation primitives use the same prop while preserving semantic
-variants. The older `variant="glass"` form remains supported for cards. Overlay
-`surface="glass"` props are deprecated compatibility aliases that map to `glass`.
+variants. The older `variant="glass"` form remains supported for cards.
 
 ```astro
 <Card glass>Glass card</Card>

package/components/Accordion.astro

@@ -1,8 +1,8 @@
 ---
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
-
 import type { HTMLAttributes } from 'astro/types'
 
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
 type AccordionVariant = 'default' | 'flush'
 
 interface Props extends HTMLAttributes<'div'> {
@@ -19,8 +19,8 @@ const {
 } = Astro.props
 
 const { classList, passthrough } = resolveLumenAstroProps(rest, [
-    'ui-accordion',
-    variant === 'flush' && 'ui-accordion--flush'
+  'ui-accordion',
+  variant === 'flush' && 'ui-accordion--flush'
 ], classProp, className)
 ---
 

package/components/Affix.astro

@@ -1,8 +1,8 @@
 ---
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
-
 import type { HTMLAttributes } from 'astro/types'
 
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
 interface Props extends HTMLAttributes<'div'> {
   class?: string | null
   className?: string

package/components/Agenda.astro

@@ -1,8 +1,8 @@
 ---
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
-
 import type { HTMLAttributes } from 'astro/types'
 
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
 interface Props extends HTMLAttributes<'section'> {
   class?: string | null
   className?: string
@@ -10,6 +10,7 @@ interface Props extends HTMLAttributes<'section'> {
 }
 
 const { class: classProp = '', className = '', glass = false, ...rest } = Astro.props
+
 const { classList, passthrough } = resolveLumenAstroProps(rest, ['ui-agenda', glass && 'ui-agenda--glass', glass === 'subtle' && 'ui-glass-subtle', glass === 'strong' && 'ui-glass-strong'
 ], classProp, className)
 ---

package/components/Alert.astro

@@ -1,8 +1,8 @@
 ---
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
-
 import type { HTMLAttributes } from 'astro/types'
 
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
 interface Props extends HTMLAttributes<'aside'> {
   class?: string | null
   className?: string
@@ -19,13 +19,13 @@ const {
 } = Astro.props
 
 const { classList, passthrough } = resolveLumenAstroProps(rest, [
-    'ui-alert',
-    variant === 'destructive' && 'ui-alert--destructive',
-    variant === 'success' && 'ui-alert--success',
-    variant === 'warning' && 'ui-alert--warning',
-    glass && 'ui-alert--glass',
-    glass === 'subtle' && 'ui-glass-subtle',
-    glass === 'strong' && 'ui-glass-strong'
+  'ui-alert',
+  variant === 'destructive' && 'ui-alert--destructive',
+  variant === 'success' && 'ui-alert--success',
+  variant === 'warning' && 'ui-alert--warning',
+  glass && 'ui-alert--glass',
+  glass === 'subtle' && 'ui-glass-subtle',
+  glass === 'strong' && 'ui-glass-strong'
 ], classProp, className)
 ---
 

package/components/AlertDialog.astro

@@ -1,37 +1,31 @@
 ---
-import { resolveLumenAstroProps, resolveLumenGlass } from '@santi020k/lumen-core'
-
 import type { HTMLAttributes } from 'astro/types'
 
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
 interface Props extends HTMLAttributes<'dialog'> {
   class?: string | null
   className?: string
   glass?: boolean | 'subtle' | 'strong'
-  /**
-   * @deprecated Use `glass` instead. `surface="glass"` maps to `glass={true}`.
-   */
-  surface?: 'default' | 'glass'
 }
 
 const {
   class: classProp = '',
   className = '',
   glass = false,
-  surface = 'default',
   ...rest
 } = Astro.props
 
-const resolvedGlass = resolveLumenGlass(glass, surface)
 const { classList, passthrough } = resolveLumenAstroProps(rest, [
-    'ui-dialog ui-alert-dialog',
-    resolvedGlass && 'ui-dialog--glass',
-    glass === 'subtle' && 'ui-glass-subtle',
-    glass === 'strong' && 'ui-glass-strong'
+  'ui-dialog ui-alert-dialog',
+  glass && 'ui-dialog--glass',
+  glass === 'subtle' && 'ui-glass-subtle',
+  glass === 'strong' && 'ui-glass-strong'
 ], classProp, className)
 ---
 
 <dialog
-  data-surface={resolvedGlass ? 'glass' : 'default'}
+  data-surface={glass ? 'glass' : 'default'}
   data-ui-alert-dialog
   role="alertdialog"
   class:list={classList}

package/components/Anchor.astro

@@ -1,24 +1,28 @@
 ---
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
-
 import type { HTMLAttributes } from 'astro/types'
 
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
 type AnchorDepth = 1 | 2 | 3 | 4 | 5 | 6
 
-type AnchorLink = {
+interface AnchorLink {
+  description?: string
   depth?: AnchorDepth
   href: string
+  index?: number | string
   label: string
 }
 
 export interface Props extends HTMLAttributes<'nav'> {
   class?: string | null
   className?: string
+  activationOffset?: number
   items?: AnchorLink[]
 }
 
 const {
   'aria-label': ariaLabel = 'On this page',
+  activationOffset = 96,
   class: classProp = '',
   className = '',
   items = [],
@@ -34,6 +38,7 @@ const { classList, passthrough } = resolveLumenAstroProps(rest, [
   aria-label={ariaLabel}
   class:list={classList}
   data-ui-anchor
+  data-ui-anchor-offset={Math.max(0, activationOffset)}
   {...passthrough}
 >
   {items.length > 0 && (
@@ -41,11 +46,20 @@ const { classList, passthrough } = resolveLumenAstroProps(rest, [
       {items.map((item, index) => (
         <li>
           <a
+            aria-current={index === 0 ? 'location' : undefined}
             data-active={index === 0 ? 'true' : 'false'}
             data-depth={item.depth}
             href={item.href}
           >
-            {item.label}
+            {item.index !== undefined && (
+              <span class="ui-anchor__index">{item.index}</span>
+            )}
+            <span class="ui-anchor__content">
+              <span class="ui-anchor__label">{item.label}</span>
+              {item.description && (
+                <span class="ui-anchor__description">{item.description}</span>
+              )}
+            </span>
           </a>
         </li>
       ))}

package/components/AnimatedLogo.astro

@@ -1,7 +1,8 @@
 ---
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
 import type { HTMLAttributes } from 'astro/types'
 
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
 interface Props extends HTMLAttributes<'span'> {
   animation?: 'reveal' | 'sequence'
   class?: string | null

package/components/AnimatedNumber.astro

@@ -1,8 +1,8 @@
 ---
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
-
 import type { HTMLAttributes } from 'astro/types'
 
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
 interface Props extends Omit<HTMLAttributes<'span'>, 'prefix'> {
   class?: string | null
   className?: string
@@ -29,11 +29,14 @@ const {
 } = Astro.props
 
 const safeDecimals = Math.max(0, Math.min(20, Math.floor(decimals)))
+
 const formatter = new Intl.NumberFormat(locale, {
   maximumFractionDigits: safeDecimals,
   minimumFractionDigits: safeDecimals
 })
+
 const formattedValue = `${prefix}${formatter.format(value)}${suffix}`
+
 const { classList, passthrough } = resolveLumenAstroProps(rest, [
   'ui-animated-number',
   `ui-motion-duration-${duration}`

package/components/AnimatedPortrait.astro

@@ -1,9 +1,10 @@
 ---
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
 import type { ImageMetadata } from 'astro'
+import type { HTMLAttributes } from 'astro/types'
+
 import { Picture } from 'astro:assets'
 
-import type { HTMLAttributes } from 'astro/types'
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
 
 interface Props extends HTMLAttributes<'div'> {
   alt: string
@@ -70,42 +71,48 @@ const { classList, passthrough } = resolveLumenAstroProps(rest, [
       aria-hidden="true"
       class="ui-animated-portrait__wash"
     />
-    {typeof src === 'string'
-      ? (
-          <Picture
-            alt={alt}
-            class="ui-animated-portrait__image"
-            decoding="sync"
-            fetchpriority="high"
-            formats={['avif', 'webp']}
-            height={440}
-            loading="eager"
-            sizes={sizes}
-            src={src}
-            width={352}
-            widths={widths}
-          />
-        )
-      : (
-          <Picture
-            alt={alt}
-            class="ui-animated-portrait__image"
-            decoding="sync"
-            fetchpriority="high"
-            formats={['avif', 'webp']}
-            height={440}
-            loading="eager"
-            sizes={sizes}
-            src={src}
-            width={352}
-            widths={widths}
-          />
-        )}
+    {typeof src === 'string' ?
+      (
+        <Picture
+          alt={alt}
+          class="ui-animated-portrait__image"
+          decoding="sync"
+          fetchpriority="high"
+          formats={['avif', 'webp']}
+          height={440}
+          loading="eager"
+          sizes={sizes}
+          src={src}
+          width={352}
+          widths={widths}
+        />
+      ) :
+      (
+        <Picture
+          alt={alt}
+          class="ui-animated-portrait__image"
+          decoding="sync"
+          fetchpriority="high"
+          formats={['avif', 'webp']}
+          height={440}
+          loading="eager"
+          sizes={sizes}
+          src={src}
+          width={352}
+          widths={widths}
+        />
+      )}
   </div>
 
   {showFloatingBadges && badgeProps?.location && (
-    <div class="ui-animated-portrait__badge ui-animated-portrait__badge--location">
-      <p class="ui-animated-portrait__label ui-animated-portrait__label--location">
+    <div class="
+      ui-animated-portrait__badge ui-animated-portrait__badge--location
+    "
+    >
+      <p class="
+        ui-animated-portrait__label ui-animated-portrait__label--location
+      "
+      >
         <span class="ui-animated-portrait__status" />
         {badgeProps.location.label}
       </p>
@@ -114,7 +121,10 @@ const { classList, passthrough } = resolveLumenAstroProps(rest, [
   )}
 
   {showFloatingBadges && badgeProps?.experience && (
-    <div class="ui-animated-portrait__badge ui-animated-portrait__badge--experience">
+    <div class="
+      ui-animated-portrait__badge ui-animated-portrait__badge--experience
+    "
+    >
       <p class="ui-animated-portrait__label">{badgeProps.experience.label}</p>
       <p class="ui-animated-portrait__experience">
         {badgeProps.experience.value}

package/components/AspectRatio.astro

@@ -1,8 +1,8 @@
 ---
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
-
 import type { HTMLAttributes } from 'astro/types'
 
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
 interface Props extends HTMLAttributes<'div'> {
   class?: string | null
   className?: string
@@ -17,16 +17,18 @@ const {
 } = Astro.props
 
 const { classList, passthrough } = resolveLumenAstroProps(rest, [
-    'ui-aspect-ratio'
+  'ui-aspect-ratio'
 ], classProp, className)
-const ratioValue = typeof ratio === 'number' && Number.isFinite(ratio)
-  ? String(ratio)
-  : typeof ratio === 'string'
-    ? ratio.trim()
-    : ''
+
+let ratioValue = ''
+
+if (typeof ratio === 'number' && Number.isFinite(ratio)) ratioValue = String(ratio)
+else if (typeof ratio === 'string') ratioValue = ratio.trim()
+
 const isValidRatio =
   /^\d+(\.\d+)?(\s*\/\s*\d+(\.\d+)?)?$/.test(ratioValue) &&
   ratioValue.split('/').every(value => Number(value.trim()) > 0)
+
 const safeRatio = isValidRatio ? ratioValue : '16 / 9'
 ---
 

package/components/Attachment.astro

@@ -1,8 +1,8 @@
 ---
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
-
 import type { HTMLAttributes } from 'astro/types'
 
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
 interface Props extends HTMLAttributes<'article'> {
   class?: string | null
   className?: string
@@ -19,28 +19,28 @@ const {
 } = Astro.props
 
 const { classList, passthrough } = resolveLumenAstroProps(rest, [
-          'ui-attachment',
-          glass && 'ui-attachment--glass',
-          glass === 'subtle' && 'ui-glass-subtle',
-          glass === 'strong' && 'ui-glass-strong'
+  'ui-attachment',
+  glass && 'ui-attachment--glass',
+  glass === 'subtle' && 'ui-glass-subtle',
+  glass === 'strong' && 'ui-glass-strong'
 ], classProp, className)
 ---
 
-{href
-  ? (
-      <a
-        href={href}
-        class:list={classList}
-        {...passthrough}
-      >
-        <slot />
-      </a>
-    )
-  : (
-      <article
-        class:list={classList}
-        {...passthrough}
-      >
-        <slot />
-      </article>
-    )}
+{href ?
+  (
+    <a
+      href={href}
+      class:list={classList}
+      {...passthrough}
+    >
+      <slot />
+    </a>
+  ) :
+  (
+    <article
+      class:list={classList}
+      {...passthrough}
+    >
+      <slot />
+    </article>
+  )}

package/components/Autocomplete.astro

@@ -1,8 +1,8 @@
 ---
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
-
 import type { HTMLAttributes } from 'astro/types'
 
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
 interface Props extends HTMLAttributes<'input'> {
   class?: string | null
   className?: string
@@ -10,6 +10,7 @@ interface Props extends HTMLAttributes<'input'> {
 }
 
 const { class: classProp = '', className = '', type = 'search', ...rest } = Astro.props
+
 const { classList, passthrough } = resolveLumenAstroProps(rest, ['ui-input', 'ui-autocomplete'
 ], classProp, className)
 ---

package/components/Avatar.astro

@@ -1,8 +1,8 @@
 ---
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
-
 import type { HTMLAttributes } from 'astro/types'
 
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
 interface Props extends HTMLAttributes<'span'> {
   class?: string | null
   className?: string
@@ -22,8 +22,9 @@ const {
 
 const hasDefaultSlot = Astro.slots.has('default')
 const fallbackText = fallback ?? (!src && !hasDefaultSlot ? '?' : undefined)
+
 const { classList, passthrough } = resolveLumenAstroProps(rest, [
-    'ui-avatar'
+  'ui-avatar'
 ], classProp, className)
 ---
 

package/components/BackToTop.astro

@@ -1,8 +1,8 @@
 ---
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
-
 import type { HTMLAttributes } from 'astro/types'
 
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
 interface Props extends HTMLAttributes<'button'> {
   class?: string | null
   className?: string

package/components/Badge.astro

@@ -1,8 +1,8 @@
 ---
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
-
 import type { HTMLAttributes } from 'astro/types'
 
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
 interface Props extends HTMLAttributes<'span'> {
   class?: string | null
   className?: string
@@ -17,13 +17,13 @@ const {
 } = Astro.props
 
 const { classList, passthrough } = resolveLumenAstroProps(rest, [
-    'ui-badge',
-    variant === 'default' && 'ui-badge--default',
-    variant === 'secondary' && 'ui-badge--secondary',
-    variant === 'outline' && 'ui-badge--outline',
-    variant === 'destructive' && 'ui-badge--destructive',
-    variant === 'success' && 'ui-badge--success',
-    variant === 'warning' && 'ui-badge--warning'
+  'ui-badge',
+  variant === 'default' && 'ui-badge--default',
+  variant === 'secondary' && 'ui-badge--secondary',
+  variant === 'outline' && 'ui-badge--outline',
+  variant === 'destructive' && 'ui-badge--destructive',
+  variant === 'success' && 'ui-badge--success',
+  variant === 'warning' && 'ui-badge--warning'
 ], classProp, className)
 ---