@santi020k/lumen-astro 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Santiago Molina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# @santi020k/lumen-astro
+
+Production-ready Astro primitives for Lumen UI. The stylesheet is standalone CSS, so no Tailwind
+configuration is required to render the components.
+
+## Install
+
+```bash
+pnpm add @santi020k/lumen-astro
+```
+
+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
+enhances all matching Lumen markup on the page.
+
+```css
+@import "@santi020k/lumen-astro/styles.css";
+```
+
+With Tailwind, keep the Lumen import in the same shared CSS entry:
+
+```css
+@import "tailwindcss";
+@import "@santi020k/lumen-astro/styles.css";
+```
+
+```astro
+---
+import { UIPrimitives } from '@santi020k/lumen-astro'
+---
+
+<UIPrimitives />
+<slot />
+```
+
+```astro
+---
+import { Button, Card, Input } from '@santi020k/lumen-astro'
+---
+
+<Card>
+  <label for="email">Email</label>
+  <Input id="email" type="email" placeholder="you@example.com" />
+  <Button>Subscribe</Button>
+</Card>
+```
+
+Use `Icon` for Lucide icons by name across framework adapters.
+
+```astro
+---
+import { Button, Icon } from '@santi020k/lumen-astro'
+---
+
+<Button variant="secondary">
+  <Icon name="wand-sparkles" decorative />
+  Generate
+</Button>
+<Icon name="search" label="Search" />
+```
+
+## Optimized images
+
+Lumen's Astro `Image` delegates to `astro:assets`, so imported image metadata, responsive layouts,
+generated `srcset` values, output formats, quality, and remote-size inference stay available. It
+loads lazily by default. Use `loading="eager"` and `fetchpriority="high"` only for the single image
+that is likely to be the page's LCP image.
+
+```astro
+---
+import { Image } from '@santi020k/lumen-astro'
+import hero from '../assets/hero.jpg'
+---
+
+<Image
+  alt="Team collaborating around a table"
+  layout="full-width"
+  quality="high"
+  src={hero}
+/>
+```
+
+For monochrome artwork whose pixels were authored for a light background, add `invertOnDark`.
+Colorful photography should keep the default so its colors remain unchanged.
+
+`AnimatedLogo` accepts your own inline SVG rather than imposing brand artwork. Put the accessible
+name on the SVG itself.
+
+```astro
+---
+import { AnimatedLogo } from '@santi020k/lumen-astro'
+---
+
+<AnimatedLogo style="height: 3rem">
+  <svg aria-label="Acme" role="img" viewBox="0 0 120 32">
+    <!-- Your logo artwork -->
+  </svg>
+</AnimatedLogo>
+```
+
+For a choreographed logo, set `animation="sequence"` and mark individual SVG layers with
+`data-ui-logo-pop`, `data-ui-logo-draw`, or `data-ui-logo-reveal`. Timing can be adjusted per layer
+with `--ui-logo-delay`.
+
+The package ships the complete Astro primitive catalog plus a small progressive-enhancement runtime for dialogs, popovers, tabs, menus, command filtering, carousels, and toasts.
+
+## Motion
+
+Use the shared `fast`, `standard`, and `slow` duration vocabulary across motion primitives.
+`ScrollReveal` handles one entrance, `RevealGroup` staggers direct children, and `AnimatedNumber`
+animates a formatted metric while preserving a stable accessible value. All three keep their final
+content readable without JavaScript and honor reduced-motion preferences.
+
+```astro
+<ScrollReveal animation="slide-up" duration="slow">
+  <h2>Release highlights</h2>
+</ScrollReveal>
+
+<RevealGroup stagger={80}>
+  <Card>Plan</Card>
+  <Card>Build</Card>
+  <Card>Ship</Card>
+</RevealGroup>
+
+<AnimatedNumber decimals={1} suffix="%" value={99.8} />
+```
+
+## Glass surfaces
+
+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`.
+
+```astro
+<Card glass>Glass card</Card>
+<Dialog glass>Glass dialog</Dialog>
+<Popover glass>Glass popover</Popover>
+<DatePicker glass="subtle" />
+<Select glass="strong" options={['Astro', 'React']} />
+```

package/components/Accordion.astro

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

package/components/Affix.astro

@@ -0,0 +1,41 @@
+---
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+import type { HTMLAttributes } from 'astro/types'
+
+interface Props extends HTMLAttributes<'div'> {
+  class?: string
+  className?: string
+  offset?: number
+  offsetBottom?: number
+  offsetTop?: number
+  position?: 'top' | 'bottom'
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  offset = 0,
+  offsetBottom,
+  offsetTop,
+  position: positionProp,
+  ...rest
+} = Astro.props
+
+const position = positionProp ?? (offsetBottom !== undefined ? 'bottom' : 'top')
+const resolvedOffset = offsetBottom ?? offsetTop ?? offset
+
+const { classList, passthrough } = resolveLumenAstroProps(rest, [
+  'ui-affix',
+  position === 'bottom' && 'ui-affix--bottom'
+], classProp, className)
+---
+
+<div
+  class:list={classList}
+  data-position={position}
+  style={`--ui-affix-offset:${resolvedOffset}px`}
+  {...passthrough}
+>
+  <slot />
+</div>

package/components/Agenda.astro

@@ -0,0 +1,19 @@
+---
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+import type { HTMLAttributes } from 'astro/types'
+
+interface Props extends HTMLAttributes<'section'> {
+  class?: string
+  className?: string
+  glass?: boolean | 'subtle' | 'strong'
+}
+
+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)
+---
+
+<section class:list={classList} {...passthrough}>
+  <slot />
+</section>

package/components/Alert.astro

@@ -0,0 +1,38 @@
+---
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+import type { HTMLAttributes } from 'astro/types'
+
+interface Props extends HTMLAttributes<'aside'> {
+  class?: string
+  className?: string
+  glass?: boolean | 'subtle' | 'strong'
+  variant?: 'default' | 'destructive' | 'success' | 'warning'
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  glass = false,
+  variant = 'default',
+  ...rest
+} = 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'
+], classProp, className)
+---
+
+<aside
+  data-variant={variant}
+  class:list={classList}
+  {...passthrough}
+>
+  <slot />
+</aside>

package/components/AlertDialog.astro

@@ -0,0 +1,41 @@
+---
+import { resolveLumenAstroProps, resolveLumenGlass } from '@santi020k/lumen-core'
+
+import type { HTMLAttributes } from 'astro/types'
+
+interface Props extends HTMLAttributes<'dialog'> {
+  class?: string
+  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'
+], classProp, className)
+---
+
+<dialog
+  data-surface={resolvedGlass ? 'glass' : 'default'}
+  data-ui-alert-dialog
+  role="alertdialog"
+  class:list={classList}
+  {...passthrough}
+>
+  <slot />
+</dialog>

package/components/Anchor.astro

@@ -0,0 +1,43 @@
+---
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+import type { HTMLAttributes } from 'astro/types'
+
+type AnchorLink = { href: string; label: string }
+
+export interface Props extends HTMLAttributes<'nav'> {
+  class?: string
+  className?: string
+  items?: AnchorLink[]
+}
+
+const {
+  'aria-label': ariaLabel = 'On this page',
+  class: classProp = '',
+  className = '',
+  items = [],
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(rest, [
+  'ui-anchor'
+], classProp, className)
+---
+
+<nav
+  aria-label={ariaLabel}
+  class:list={classList}
+  data-ui-anchor
+  {...passthrough}
+>
+  {items.length > 0 && (
+    <ol>
+      {items.map((item, index) => (
+        <li>
+          <a data-active={index === 0 ? 'true' : 'false'} href={item.href}>{item.label}</a>
+        </li>
+      ))}
+    </ol>
+  )}
+  <slot />
+</nav>

package/components/AnimatedLogo.astro

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

package/components/AnimatedNumber.astro

@@ -0,0 +1,56 @@
+---
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+import type { HTMLAttributes } from 'astro/types'
+
+interface Props extends Omit<HTMLAttributes<'span'>, 'prefix'> {
+  class?: string
+  className?: string
+  decimals?: number
+  duration?: 'fast' | 'standard' | 'slow'
+  from?: number
+  locale?: string
+  prefix?: string
+  suffix?: string
+  value: number
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  decimals = 0,
+  duration = 'slow',
+  from = 0,
+  locale,
+  prefix = '',
+  suffix = '',
+  value,
+  ...rest
+} = 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}`
+], classProp, className)
+---
+
+<span
+  class:list={classList}
+  data-ui-animated-number
+  data-ui-animated-number-decimals={safeDecimals}
+  data-ui-animated-number-from={from}
+  data-ui-animated-number-locale={locale}
+  data-ui-animated-number-prefix={prefix}
+  data-ui-animated-number-suffix={suffix}
+  data-ui-animated-number-value={value}
+  {...passthrough}
+>
+  <span aria-hidden="true" data-ui-animated-number-output>{formattedValue}</span>
+  <span class="ui-sr-only">{formattedValue}</span>
+</span>

package/components/AnimatedPortrait.astro

@@ -0,0 +1,124 @@
+---
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+import type { ImageMetadata } from 'astro'
+import { Picture } from 'astro:assets'
+
+import type { HTMLAttributes } from 'astro/types'
+
+interface Props extends HTMLAttributes<'div'> {
+  alt: string
+  badgeProps?: {
+    experience?: {
+      label: string
+      value: string
+    }
+    location?: {
+      label: string
+      text: string
+    }
+  }
+  class?: string
+  className?: string
+  showFloatingBadges?: boolean
+  sizes?: string
+  src: ImageMetadata | string
+  widths?: number[]
+}
+
+const {
+  alt,
+  badgeProps,
+  class: classProp = '',
+  className = '',
+  showFloatingBadges = false,
+  sizes = '(min-width: 1024px) 352px, 75vw',
+  src,
+  widths = [400, 600, 800],
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(rest, [
+  'ui-animated-portrait',
+  'relative isolate mx-auto w-full max-w-88 animate-reveal-lcp motion-reduce:animate-none'
+], classProp, className)
+---
+
+<div class:list={classList} {...passthrough}>
+  <div
+    aria-hidden="true"
+    class="ui-animated-portrait__glow"
+  />
+
+  <div
+    aria-hidden="true"
+    class="ui-animated-portrait__orbit ui-animated-portrait__orbit--outer"
+  />
+
+  <div
+    aria-hidden="true"
+    class="ui-animated-portrait__orbit ui-animated-portrait__orbit--inner"
+  />
+
+  <div
+    class="panel-card ui-animated-portrait__card"
+  >
+    <div
+      aria-hidden="true"
+      class="grid-fade ui-animated-portrait__grid"
+    />
+    <div
+      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}
+          />
+        )}
+  </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">
+        <span class="ui-animated-portrait__status" />
+        {badgeProps.location.label}
+      </p>
+      <p class="ui-animated-portrait__location">{badgeProps.location.text}</p>
+    </div>
+  )}
+
+  {showFloatingBadges && badgeProps?.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}
+      </p>
+    </div>
+  )}
+</div>

package/components/AspectRatio.astro

@@ -0,0 +1,39 @@
+---
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+import type { HTMLAttributes } from 'astro/types'
+
+interface Props extends HTMLAttributes<'div'> {
+  class?: string
+  className?: string
+  ratio?: number | string
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  ratio = '16 / 9',
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(rest, [
+    'ui-aspect-ratio'
+], classProp, className)
+const ratioValue = typeof ratio === 'number' && Number.isFinite(ratio)
+  ? String(ratio)
+  : typeof ratio === 'string'
+    ? 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'
+---
+
+<div
+  style={`aspect-ratio: ${safeRatio}`}
+  class:list={classList}
+  {...passthrough}
+>
+  <slot />
+</div>

package/components/Attachment.astro

@@ -0,0 +1,46 @@
+---
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+import type { HTMLAttributes } from 'astro/types'
+
+interface Props extends HTMLAttributes<'article'> {
+  class?: string
+  className?: string
+  glass?: boolean | 'subtle' | 'strong'
+  href?: string
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  glass = false,
+  href,
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(rest, [
+          '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>
+    )}