@santi020k/lumen-astro 1.7.0-rc.0 → 1.7.0

package/README.md

@@ -9,6 +9,13 @@ configuration is required to render the components.
 pnpm add @santi020k/lumen-astro
 ```
 
+The adapter also exposes Lumen's discovery and diagnostics CLI:
+
+```bash
+pnpm exec lumen show Tabs
+pnpm exec lumen doctor
+```
+
 Import the CSS once in your root layout and mount `UIPrimitives` once in that same app shell if you
 use interactive components such as dialogs, menus, popovers, tabs, carousels, toggles, command
 lists, or toasts. Do not add `UIPrimitives` beside each component instance; one root include
@@ -18,6 +25,11 @@ enhances all matching Lumen markup on the page.
 @import "@santi020k/lumen-astro/styles.css";
 ```
 
+Applications using the essential forms, feedback, tabs, dialogs, calendar, and data-table surface
+can instead load `@santi020k/lumen-astro/styles/critical.css`. The generated entry is about 50 KiB
+raw versus 170 KiB for the complete catalog; switch to `styles.css` when using components outside
+that documented critical set.
+
 The stylesheet defaults `--ui-font` to `"Montserrat", "Avenir Next", "Segoe UI", sans-serif`.
 It declares the family stack but does not bundle or load font files. Load Montserrat once through
 your preferred delivery path, or override `--ui-font` in application CSS.
@@ -32,7 +44,7 @@ With Tailwind, keep the Lumen import in the same shared CSS entry:
 
 ```astro
 ---
-import { UIPrimitives } from '@santi020k/lumen-astro'
+import UIPrimitives from '@santi020k/lumen-astro/runtime'
 ---
 
 <UIPrimitives />
@@ -52,8 +64,7 @@ import { Button, Card, Input } from '@santi020k/lumen-astro'
 ```
 
 `Input` and `NativeSelect` preserve the native numeric `size` attribute. Use `visualSize="sm"` or
-`visualSize="lg"` for presentation. The pre-1.0 `size="sm|lg"` visual alias remains available for
-incremental migrations, but new code should keep native behavior and visual styling separate.
+`visualSize="lg"` for presentation so native behavior and visual styling remain separate.
 
 ```astro
 <Input size={32} visualSize="sm" />
@@ -65,6 +76,9 @@ incremental migrations, but new code should keep native behavior and visual styl
 metadata-backed validation, automatic country detection for pasted international numbers, and the
 `ui:phone-change` event with a `LumenPhoneNumber` detail.
 
+The phone metadata and normalization controller are selector-loaded only when a rendered page
+contains `PhoneInput`; pages without the component do not evaluate or download that controller.
+
 ```astro
 <PhoneInput countryValue="CO" locale="en-US" name="hospitalPhone" />
 ```
@@ -75,6 +89,10 @@ Popover, dropdown menu, tabs, and tooltip parts expose the DOM and ARIA contract
 shared progressive-enhancement runtime. Prefer these parts over recreating roles and `data-ui-*`
 attributes by hand.
 
+Tabs keep the selected trigger visible when a narrow tab list scrolls horizontally and emit a
+typed `ui:tabs-change` event. Import `LumenTabsChangeDetail` or `LumenTabsChangeEvent` from this
+package when application behavior follows the selected value.
+
 ```astro
 ---
 import {
@@ -180,6 +198,22 @@ const errors = result?.error && isInputError(result.error)
 
 See the [Astro Actions form guide](https://lumen.santi020k.com/docs/forms/astro-actions).
 
+## Error states
+
+Use `ErrorState` when a page or region cannot show its primary content. Pass recovery controls
+through the `actions` slot; the application still owns retry and logging behavior. Static states are
+not live regions by default, so set `announce="polite"` only when a newly rendered failure needs an
+announcement.
+
+```astro
+<ErrorState title="Could not load projects" description="Check your connection and try again.">
+  <Button slot="actions">Try again</Button>
+</ErrorState>
+```
+
+See the repository [Astro error-handling guide](../../docs/error-handling.md#astro) for the complete
+example, retry ownership, announcement behavior, and verification guidance.
+
 Use `Icon` for Lucide icons by name across framework adapters.
 
 ```astro

package/bin/lumen.mjs

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

package/components/ErrorState.astro

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

package/components/Sonner.astro

@@ -21,7 +21,8 @@ const {
 } = Astro.props
 
 const { classList, passthrough } = resolveLumenAstroProps(rest, [
-  'ui-sonner'
+  'ui-sonner',
+  'ui-tvp'
 ], classProp, className)
 ---
 
@@ -29,6 +30,7 @@ const { classList, passthrough } = resolveLumenAstroProps(rest, [
   aria-atomic={ariaAtomic}
   aria-live={ariaLive}
   data-ui-sonner
+  data-ui-toast-viewport
   data-ui-toast-max={maxCount}
   data-placement={placement}
   class:list={classList}

package/components/ToastViewport.astro

@@ -0,0 +1,38 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'div'> {
+  class?: string | null
+  className?: string
+  maxCount?: number
+  placement?: 'bottom-center' | 'bottom-left' | 'bottom-right' | 'top-center' | 'top-left' | 'top-right'
+}
+
+const {
+  'aria-atomic': ariaAtomic = 'false',
+  'aria-live': ariaLive = 'polite',
+  class: classProp = '',
+  className = '',
+  maxCount,
+  placement = 'bottom-right',
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(rest, [
+  'ui-tvp'
+], classProp, className)
+---
+
+<div
+  aria-atomic={ariaAtomic}
+  aria-live={ariaLive}
+  data-ui-toast-viewport
+  data-ui-toast-max={maxCount}
+  data-placement={placement}
+  class:list={classList}
+  {...passthrough}
+>
+  <slot />
+</div>

package/index.ts

@@ -58,6 +58,7 @@ export { default as DropdownMenuItem } from './components/DropdownMenuItem.astro
 export { default as DropdownMenuSeparator } from './components/DropdownMenuSeparator.astro'
 export { default as DropdownMenuTrigger } from './components/DropdownMenuTrigger.astro'
 export { default as Empty } from './components/Empty.astro'
+export { default as ErrorState } from './components/ErrorState.astro'
 export { default as ErrorSummary } from './components/ErrorSummary.astro'
 export { default as Eyebrow } from './components/Eyebrow.astro'
 export { default as Field } from './components/Field.astro'
@@ -129,7 +130,6 @@ export { default as Sidebar } from './components/Sidebar.astro'
 export { default as Skeleton } from './components/Skeleton.astro'
 export { default as SkipLink } from './components/SkipLink.astro'
 export { default as Slider } from './components/Slider.astro'
-export { default as Sonner } from './components/Sonner.astro'
 export { default as Sparkline } from './components/Sparkline.astro'
 export { default as SpeedDial } from './components/SpeedDial.astro'
 export { default as Spinner } from './components/Spinner.astro'
@@ -155,6 +155,9 @@ export { default as TimeField } from './components/TimeField.astro'
 export { default as Timeline } from './components/Timeline.astro'
 export { default as TimelineItem } from './components/TimelineItem.astro'
 export { default as Toast } from './components/Toast.astro'
+/** @deprecated Import ToastViewport instead. */
+export { default as Sonner } from './components/Sonner.astro'
+export { default as ToastViewport } from './components/ToastViewport.astro'
 export { default as Toggle } from './components/Toggle.astro'
 export { default as ToggleGroup } from './components/ToggleGroup.astro'
 export { default as Toolbar } from './components/Toolbar.astro'
@@ -174,4 +177,9 @@ export {
   type LumenControlIdMap,
   normalizeAstroActionErrors
 } from './forms.ts'
+/** @deprecated Import the default export from @santi020k/lumen-astro/runtime instead. */
 export { default as UIPrimitives } from './runtime/UIPrimitives.astro'
+export type {
+  LumenTabsChangeDetail,
+  LumenTabsChangeEvent
+} from '@santi020k/lumen-core'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@santi020k/lumen-astro",
-  "version": "1.7.0-rc.0",
+  "version": "1.7.0",
   "publishConfig": {
     "access": "public"
   },
@@ -8,6 +8,7 @@
   "type": "module",
   "sideEffects": [
     "./styles/lumen.css",
+    "./styles/critical.css",
     "./styles.css"
   ],
   "types": "./index.ts",
@@ -24,9 +25,11 @@
     "./runtime": "./runtime/UIPrimitives.astro",
     "./layers.css": "./styles/layers.css",
     "./styles.css": "./styles/lumen.css",
+    "./styles/critical.css": "./styles/critical.css",
     "./package.json": "./package.json"
   },
   "files": [
+    "bin",
     "components",
     "runtime",
     "styles",
@@ -35,10 +38,13 @@
     "README.md",
     "LICENSE"
   ],
+  "bin": {
+    "lumen": "./bin/lumen.mjs"
+  },
   "dependencies": {
     "uqr": "^0.1.3",
-    "@santi020k/lumen-core": "^1.7.0-rc.0",
-    "@santi020k/lumen": "^1.7.0-rc.0"
+    "@santi020k/lumen": "^1.7.0",
+    "@santi020k/lumen-core": "^1.7.0"
   },
   "devDependencies": {
     "@astrojs/ts-plugin": "^1.10.11",