AstroNox Core

AstroNox Core is a reusable foundation for Astro applications. It provides components, composition primitives, interaction patterns, display contracts, internationalization and SEO infrastructure, and a complete shared stylesheet.

Product data, product routes, branding, integrations, and business rules stay in the consuming site.

Installation

npm install @astronox/core

Astro is a peer dependency. Firebase is an optional peer dependency used only by the dedicated Firebase entry points. Consumers must install the providers they activate.

Usage

Import components through the curated package entry points:

---
import { CardBody, CardHeader } from '@astronox/core/components';
import { Stack, SurfaceGroup } from '@astronox/core/composition';
---

<Stack gap="md">
  <SurfaceGroup>
    <CardHeader title="Example" />
    <CardBody>Content</CardBody>
  </SurfaceGroup>
</Stack>

Load the shared visual system once from the consuming application's root layout:

---
import '@astronox/core/styles.css';
---

Use the remaining entry points for layouts, patterns, primitives, display contracts, configuration, theme, client behavior, data validation, and SEO. Deep imports into the physical src tree are not part of the public API.

AnnotatedText renders DisplayAnnotatedText spans with optional emphasis and explanatory tooltips. Tooltip accepts either its existing string content or a DisplayTooltip with a title and non-interactive text spans. TextBlock, InlineDefinition and table descriptions also accept annotated text; table tooltip bodies never create nested interactions. These contracts contain no markup parser or product-specific vocabulary.

Annotated text inherits its tone and whitespace behavior from its context; data-tone can override the tone at its public root. Empty or whitespace-only segments never create tooltip buttons. TextBlock preserveBreaks applies the same paragraph boundaries to plain and annotated text, even when a separator crosses annotation boundaries, while retaining each segment's annotations.

Locale catalogs, localized routing, preference persistence, localized metadata, and responsive media presentation are available through the i18n, routing, seo, and display entry points. Consuming sites provide their own locale definitions, translations, route names, product metadata, and assets. Generic component labels can extend defaultCoreMessages through resolveCoreMessages() while retaining the English fallback.

Infrastructure

Seasonal themes accept disabled, always, or annual availability. Annual periods use inclusive start dates and exclusive end dates in the visitor's local time. The toggle includes every available season after light and dark, in ascending priority order; the highest priority sets the initial seasonal appearance. Manual choices persist without replacing the user's classic light/dark preference.

Reward calendar adapters can return canGenerate: false in their snapshot to keep gift previews available without displaying or accepting redemption controls. Availability and reward delivery remain the consuming application's responsibility.

• content: reusable ordered content and Markdown contracts.
• Firebase admin: authentication, claims, Firestore, and app-owned mappings.
• R2 publication: full provider snapshots and build-time public projection.
• AdSense: typed configuration, Privacy & Messaging policy, annotation exclusions, and deployment.
• release workflow: local links, verification, and consumer pinning order.