@santi020k/lumen-astro 0.3.0 → 1.0.0

package/README.md

@@ -18,6 +18,10 @@ enhances all matching Lumen markup on the page.
 @import "@santi020k/lumen-astro/styles.css";
 ```
 
+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.
+
 With Tailwind, keep the Lumen import in the same shared CSS entry:
 
 ```css
@@ -47,6 +51,35 @@ import { Button, Card, Input } from '@santi020k/lumen-astro'
 </Card>
 ```
 
+## 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
@@ -61,6 +94,58 @@ import { Button, Icon } from '@santi020k/lumen-astro'
 <Icon name="search" label="Search" />
 ```
 
+## Long-form navigation
+
+`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, CopyButton, ScrollProgress } from '@santi020k/lumen-astro'
+---
+
+<ScrollProgress aria-label="Article reading progress" />
+<Anchor items={[
+  { depth: 2, href: '#install', label: 'Install' },
+  { depth: 3, href: '#astro', label: '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
+trends, and `PieChart` for a small part-to-whole breakdown. The chart components accept
+already-aggregated series, use Lumen data-color tokens, and include a revealable semantic data
+table by default.
+
+```astro
+---
+import { LineChart } from '@santi020k/lumen-astro'
+
+const series = [{
+  id: 'views',
+  label: 'Views',
+  data: [{ x: 'Mon', y: 42 }, { x: 'Tue', y: 68 }]
+}]
+---
+
+<LineChart aria-label="Views by day" heading="Website traffic" {series} />
+```
+
+`PieChart` accepts one `LumenChartSeries`; its data points become slices. It defaults to
+`variant="donut"` and also supports `variant="pie"`.
+
 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.
@@ -158,8 +243,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>
@@ -168,3 +252,17 @@ variants. The older `variant="glass"` form remains supported for cards. Overlay
 <DatePicker glass="subtle" />
 <Select glass="strong" options={['Astro', 'React']} />
 ```
+
+## Semantic stat roots
+
+`Stat` renders a `div` by default. Use `as="article"` when the metric and its supporting content
+form a standalone item, or `as="section"` when it is a labeled region in a larger view.
+
+```astro
+<Stat as="article" label="Active workspaces" value="1,234" variant="accent">
+  <p>Across all production organizations.</p>
+</Stat>
+```
+
+Use `variant="default"` for the original neutral surface, `variant="accent"` for a featured metric,
+or `variant="glass"` for selective translucency.

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,18 +1,28 @@
 ---
+import type { HTMLAttributes } from 'astro/types'
+
 import { resolveLumenAstroProps } from '@santi020k/lumen-core'
 
-import type { HTMLAttributes } from 'astro/types'
+type AnchorDepth = 1 | 2 | 3 | 4 | 5 | 6
 
-type AnchorLink = { href: string; label: string }
+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 = [],
@@ -28,13 +38,29 @@ 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 && (
     <ol>
       {items.map((item, index) => (
         <li>
-          <a data-active={index === 0 ? 'true' : 'false'} href={item.href}>{item.label}</a>
+          <a
+            aria-current={index === 0 ? 'location' : undefined}
+            data-active={index === 0 ? 'true' : 'false'}
+            data-depth={item.depth}
+            href={item.href}
+          >
+            {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>
       ))}
     </ol>

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)
 ---