@astronox/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gaudesp
+
+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,66 @@
+# AstroNox Core
+
+AstroNox Core is the shared Astro foundation used by AstroNox sites. It owns
+reusable components, composition primitives, interaction patterns, display
+contracts, SEO helpers, and the complete default stylesheet.
+
+Product data, product routes, branding, integrations, and business rules stay
+in the consuming site.
+
+## Installation
+
+```bash
+npm install @astronox/core
+```
+
+Astro is a peer dependency. Consumers must use a compatible Astro 7 release.
+
+## Usage
+
+Import components through the curated package entry points:
+
+```astro
+---
+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 stylesheet:
+
+```css
+@import '@astronox/core/styles.css';
+@import './site-theme.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.
+
+## Local Development
+
+`astronox-core` is the only source of truth. A consuming project may link this
+package locally while developing a shared change, but committed dependencies
+must always reference a released package version.
+
+The expected workflow is:
+
+1. Implement and commit the generic change in this repository.
+2. Validate it from the relevant linked consumer.
+3. Publish a prerelease or stable package version.
+4. Update consumers through their dependency management workflow.
+
+Do not edit installed package files or copy `src` folders between projects.
+
+## Releases
+
+AstroNox Core follows semantic versioning. Public entry points are compatibility
+boundaries; internal files may change without notice. The initial `0.x` series
+is reserved for stabilizing the API with the first production consumers.

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@astronox/core",
+  "version": "0.1.0",
+  "description": "Reusable Astro components, patterns, styles, and infrastructure for AstroNox sites.",
+  "license": "MIT",
+  "keywords": [
+    "astro",
+    "components",
+    "design-system",
+    "frontend",
+    "ui"
+  ],
+  "homepage": "https://github.com/gaudesp/astronox-core#readme",
+  "bugs": {
+    "url": "https://github.com/gaudesp/astronox-core/issues"
+  },
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "src",
+    "tsconfig.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client/index.ts",
+    "./components": "./src/components/index.ts",
+    "./composition": "./src/composition/index.ts",
+    "./config": "./src/config/index.ts",
+    "./data": "./src/data/index.ts",
+    "./display": "./src/display/index.ts",
+    "./layouts": "./src/layouts/index.ts",
+    "./patterns": "./src/patterns/index.ts",
+    "./primitives": "./src/primitives/index.ts",
+    "./seo": "./src/seo/index.ts",
+    "./theme": "./src/theme/index.ts",
+    "./styles.css": "./src/styles/style.css",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "check": "astro check",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint ."
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gaudesp/astronox-core.git"
+  },
+  "peerDependencies": {
+    "astro": "^7.0.0"
+  },
+  "dependencies": {
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@astrojs/check": "0.9.9",
+    "@eslint/js": "9.39.5",
+    "astro": "7.0.9",
+    "astro-eslint-parser": "1.4.0",
+    "eslint": "9.39.5",
+    "eslint-plugin-astro": "1.7.0",
+    "prettier": "3.9.5",
+    "prettier-plugin-astro": "0.14.1",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.64.0"
+  }
+}

package/src/client/clipboard.ts

@@ -0,0 +1,7 @@
+export async function copyText(value: string): Promise<void> {
+  if (!navigator.clipboard?.writeText) {
+    throw new Error('Clipboard API unavailable');
+  }
+
+  await navigator.clipboard.writeText(value);
+}

package/src/client/focus.ts

@@ -0,0 +1,17 @@
+const focusableSelector = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(',');
+
+export const getFocusableElements = (root: ParentNode): HTMLElement[] =>
+  Array.from(root.querySelectorAll<HTMLElement>(focusableSelector)).filter(
+    (element) =>
+      !element.hasAttribute('disabled') &&
+      element.getAttribute('aria-disabled') !== 'true' &&
+      element.tabIndex >= 0 &&
+      element.getClientRects().length > 0,
+  );

package/src/client/index.ts

@@ -0,0 +1,3 @@
+export * from './clipboard';
+export * from './focus';
+export * from './scroll';

package/src/client/scroll.ts

@@ -0,0 +1,15 @@
+type JumpToElementOptions = {
+  block?: ScrollLogicalPosition;
+  inline?: ScrollLogicalPosition;
+};
+
+export function jumpToElement(
+  element: Element,
+  { block = 'center', inline = 'nearest' }: JumpToElementOptions = {},
+): void {
+  element.scrollIntoView({
+    behavior: 'auto',
+    block,
+    inline,
+  });
+}

package/src/components/actions/ActionListItem/ActionListItem.astro

@@ -0,0 +1,78 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type ActionListItemAccent = 'start';
+type ActionListItemElement = 'auto' | 'button';
+
+type Props = Omit<HTMLAttributes<'a'>, 'href'> &
+  Omit<HTMLAttributes<'button'>, 'type'> & {
+    accent?: ActionListItemAccent;
+    active?: boolean;
+    as?: ActionListItemElement;
+    disabled?: boolean;
+    href?: string;
+    type?: HTMLAttributes<'button'>['type'];
+  };
+
+const hasActiveState = Astro.props.active !== undefined;
+const {
+  accent,
+  active = false,
+  as = 'auto',
+  class: className,
+  disabled = false,
+  href,
+  rel,
+  target,
+  type = 'button',
+  ...attrs
+} = Astro.props;
+const classes = ['action-list-item', className];
+const resolvedRel =
+  rel ?? (target === '_blank' ? 'noopener noreferrer' : undefined);
+const shouldRenderButton = as === 'button';
+---
+
+{
+  shouldRenderButton ? (
+    <button
+      {...attrs}
+      class:list={classes}
+      data-action-list-item
+      data-action-list-item-active={active ? true : undefined}
+      data-interaction-accent={accent}
+      data-interaction-accent-active={accent && active ? true : undefined}
+      aria-pressed={hasActiveState ? active : undefined}
+      disabled={disabled}
+      type={type}
+    >
+      <slot />
+    </button>
+  ) : href && !disabled ? (
+    <a
+      {...attrs}
+      class:list={classes}
+      data-action-list-item
+      data-action-list-item-active={active ? true : undefined}
+      data-interaction-accent={accent}
+      data-interaction-accent-active={accent && active ? true : undefined}
+      href={href}
+      rel={resolvedRel}
+      target={target}
+    >
+      <slot />
+    </a>
+  ) : (
+    <span
+      {...attrs}
+      class:list={classes}
+      data-action-list-item
+      data-action-list-item-active={active ? true : undefined}
+      data-interaction-accent={accent}
+      data-interaction-accent-active={accent && active ? true : undefined}
+      aria-disabled="true"
+    >
+      <slot />
+    </span>
+  )
+}

package/src/components/actions/ActionListItem/ActionListItem.css

@@ -0,0 +1,43 @@
+.action-list-item {
+  position: relative;
+  display: flex;
+  width: 100%;
+  min-width: 0;
+  min-height: 2.75rem;
+  align-items: center;
+  justify-content: flex-start;
+  padding: var(--nox-space-3) var(--nox-space-4);
+  border: 0;
+  border-radius: var(--nox-radius-sm);
+  background: transparent;
+  color: var(--nox-link-active);
+  font: inherit;
+  font-size: var(--nox-font-size-sm);
+  font-weight: var(--nox-font-weight-strong);
+  letter-spacing: var(--nox-letter-spacing-wide);
+  line-height: 1;
+  text-align: start;
+  text-decoration: none;
+  text-transform: uppercase;
+  cursor: pointer;
+}
+
+.action-list-item[data-action-list-item-active] {
+  color: var(--nox-link-active);
+}
+
+.action-list-item:focus-visible {
+  outline: var(--nox-focus-ring-width) solid var(--nox-focus-ring);
+  outline-offset: var(--nox-focus-ring-offset);
+}
+
+.action-list-item:where([aria-disabled='true'], [disabled]) {
+  color: var(--nox-text-disabled);
+  cursor: not-allowed;
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .action-list-item:where([href], button):hover {
+    color: var(--nox-link-hover);
+  }
+}

package/src/components/actions/Button/Button.astro

@@ -0,0 +1,100 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import type { Tone } from '../../../theme/contracts';
+
+type ButtonSize = 'sm' | 'md' | 'lg';
+
+type Props = Omit<HTMLAttributes<'button'>, 'size'> &
+  Omit<HTMLAttributes<'a'>, 'href'> & {
+    borderless?: boolean;
+    disabled?: boolean;
+    full?: boolean;
+    href?: string;
+    hoverTone?: Tone;
+    iconOnly?: boolean;
+    prominent?: boolean;
+    size?: ButtonSize;
+    tone?: Tone;
+  };
+
+const {
+  borderless = false,
+  class: className,
+  'data-tone': dataTone,
+  disabled = false,
+  full = false,
+  href,
+  hoverTone,
+  iconOnly = false,
+  prominent = false,
+  size = 'md',
+  target,
+  type = 'button',
+  rel,
+  tone,
+  ...attrs
+} = Astro.props;
+const hasLeading = Astro.slots.has('leading');
+const hasTrailing = Astro.slots.has('trailing');
+const resolvedRel =
+  rel ?? (target === '_blank' ? 'noopener noreferrer' : undefined);
+const resolvedTone = tone ?? dataTone;
+---
+
+{
+  href && !disabled ? (
+    <a
+      {...attrs}
+      class:list={['nox-button', className]}
+      data-button-borderless={borderless ? true : undefined}
+      data-button-full={full ? true : undefined}
+      data-button-hover-tone={hoverTone}
+      data-button-icon-only={iconOnly ? true : undefined}
+      data-button-prominent={prominent ? true : undefined}
+      data-button-size={size}
+      data-tone={resolvedTone}
+      href={href}
+      rel={resolvedRel}
+      target={target}
+    >
+      {hasLeading ? <slot name="leading" /> : null}
+      <slot />
+      {hasTrailing ? <slot name="trailing" /> : null}
+    </a>
+  ) : href ? (
+    <span
+      {...attrs}
+      aria-disabled="true"
+      class:list={['nox-button', className]}
+      data-button-borderless={borderless ? true : undefined}
+      data-button-full={full ? true : undefined}
+      data-button-hover-tone={hoverTone}
+      data-button-icon-only={iconOnly ? true : undefined}
+      data-button-prominent={prominent ? true : undefined}
+      data-button-size={size}
+      data-tone={resolvedTone}
+    >
+      {hasLeading ? <slot name="leading" /> : null}
+      <slot />
+      {hasTrailing ? <slot name="trailing" /> : null}
+    </span>
+  ) : (
+    <button
+      {...attrs}
+      class:list={['nox-button', className]}
+      data-button-borderless={borderless ? true : undefined}
+      data-button-full={full ? true : undefined}
+      data-button-hover-tone={hoverTone}
+      data-button-icon-only={iconOnly ? true : undefined}
+      data-button-prominent={prominent ? true : undefined}
+      data-button-size={size}
+      data-tone={resolvedTone}
+      disabled={disabled}
+      type={type}
+    >
+      {hasLeading ? <slot name="leading" /> : null}
+      <slot />
+      {hasTrailing ? <slot name="trailing" /> : null}
+    </button>
+  )
+}

package/src/components/actions/Button/Button.css

@@ -0,0 +1,165 @@
+.nox-button {
+  --nox-button-background: var(--nox-tone-background);
+  --nox-button-border-color: var(--nox-border);
+  --nox-button-color: var(--nox-tone-color);
+  --nox-button-hover-background: var(--nox-tone-hover-background);
+  --nox-button-active-background: var(--nox-tone-active-background);
+  --nox-button-focus-ring: var(--nox-tone-focus-ring);
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--nox-space-2);
+  border: var(--nox-border-width) solid var(--nox-button-border-color);
+  border-radius: var(--nox-radius-pill);
+  background: var(--nox-button-background);
+  color: var(--nox-button-color);
+  font: inherit;
+  font-size: var(--nox-font-size-sm);
+  font-weight: var(--nox-font-weight-strong);
+  letter-spacing: var(--nox-letter-spacing-wide);
+  line-height: 1;
+  text-align: center;
+  text-decoration: none;
+  text-transform: uppercase;
+  cursor: pointer;
+}
+
+.nox-button[data-button-hover-tone='neutral'] {
+  --nox-button-hover-tone-seed: var(--nox-source-tone-neutral);
+}
+
+.nox-button[data-button-hover-tone='primary'] {
+  --nox-button-hover-tone-seed: var(--nox-source-tone-primary);
+}
+
+.nox-button[data-button-hover-tone='info'] {
+  --nox-button-hover-tone-seed: var(--nox-source-tone-info);
+}
+
+.nox-button[data-button-hover-tone='success'] {
+  --nox-button-hover-tone-seed: var(--nox-source-tone-success);
+}
+
+.nox-button[data-button-hover-tone='warning'] {
+  --nox-button-hover-tone-seed: var(--nox-source-tone-warning);
+}
+
+.nox-button[data-button-hover-tone='danger'] {
+  --nox-button-hover-tone-seed: var(--nox-source-tone-danger);
+}
+
+.nox-button[data-button-size='sm'] {
+  min-height: 2.25rem;
+  padding: var(--nox-space-2) var(--nox-space-3);
+}
+
+.nox-button[data-button-size='md'] {
+  min-height: 2.625rem;
+  padding: var(--nox-space-2) var(--nox-space-4);
+}
+
+.nox-button[data-button-size='lg'] {
+  min-height: 3rem;
+  padding: var(--nox-space-3) var(--nox-space-5);
+}
+
+.nox-button[data-button-full] {
+  inline-size: 100%;
+  block-size: 100%;
+}
+
+.nox-button[data-button-icon-only] {
+  padding: 0;
+  aspect-ratio: 1;
+}
+
+.nox-button[data-button-icon-only] svg {
+  display: block;
+  inline-size: 2rem;
+  block-size: 2rem;
+}
+
+.nox-button[data-button-icon-only][data-button-size='sm'] svg {
+  inline-size: 1.5rem;
+  block-size: 1.5rem;
+}
+
+.nox-button[data-button-icon-only][data-button-size='lg'] svg {
+  inline-size: 2.25rem;
+  block-size: 2.25rem;
+}
+
+.nox-button[data-button-borderless] {
+  border: 0;
+  border-radius: 0;
+}
+
+.nox-button[data-button-borderless]:focus-visible {
+  outline-offset: calc(var(--nox-focus-ring-width) * -1);
+}
+
+.nox-button[data-button-prominent] {
+  --nox-button-background: var(--nox-tone-color);
+  --nox-button-border-color: var(--nox-tone-color);
+  --nox-button-color: var(--nox-text-inverse);
+  --nox-button-hover-background: var(--nox-tone-text);
+  --nox-button-active-background: var(--nox-tone-text);
+  --nox-button-focus-ring: var(--nox-tone-focus-ring);
+}
+
+.nox-button:focus-visible {
+  outline: var(--nox-focus-ring-width) solid var(--nox-button-focus-ring);
+  outline-offset: var(--nox-focus-ring-offset);
+}
+
+.nox-button[disabled],
+.nox-button[aria-disabled='true'] {
+  opacity: 0.58;
+  cursor: not-allowed;
+}
+
+@media (hover: hover) {
+  .nox-button:hover:not([disabled], [aria-disabled='true']) {
+    background: var(--nox-button-hover-background);
+  }
+
+  .nox-button[data-button-hover-tone]:hover:not(
+      [disabled],
+      [aria-disabled='true']
+    ) {
+    background: color-mix(
+      in srgb,
+      var(--nox-button-hover-tone-seed) 12%,
+      var(--nox-mix-light)
+    );
+    color: var(--nox-button-hover-tone-seed);
+  }
+}
+
+.nox-button:active:not([disabled], [aria-disabled='true']) {
+  background: var(--nox-button-active-background);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .nox-button {
+    transition:
+      background-color var(--nox-motion-duration-sm)
+        var(--nox-motion-easing-standard),
+      border-color var(--nox-motion-duration-sm)
+        var(--nox-motion-easing-standard),
+      color var(--nox-motion-duration-sm) var(--nox-motion-easing-standard),
+      transform var(--nox-motion-duration-sm) var(--nox-motion-easing-standard);
+  }
+
+  .nox-button:active:not([disabled], [aria-disabled='true']) {
+    transform: translateY(1px);
+  }
+
+  .nox-button[data-button-full][data-button-borderless]:active:not(
+      [disabled],
+      [aria-disabled='true']
+    ) {
+    transform: none;
+  }
+}

package/src/components/actions/CardAction/CardAction.astro

@@ -0,0 +1,97 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import type { AstroComponent } from '../../widgetTypes';
+import type { DisplayMedia } from '../../../display/contracts';
+import type { Tone } from '../../../theme/contracts';
+import Media from '../../../primitives/media/Media/Media.astro';
+
+type Props = Omit<HTMLAttributes<'button'>, 'type'> &
+  Omit<HTMLAttributes<'a'>, 'href'> & {
+    compactLabel?: string;
+    disabled?: boolean;
+    href?: string;
+    hoverTone?: Tone;
+    icon?: AstroComponent;
+    iconTone?: Tone;
+    label: string;
+    labelTreatment?: 'default' | 'heading';
+    media?: DisplayMedia;
+    tone?: Tone;
+    type?: 'button' | 'submit' | 'reset';
+    visualPosition?: 'start' | 'end';
+  };
+
+const {
+  class: className,
+  'data-tone': dataTone,
+  compactLabel,
+  disabled = false,
+  href,
+  hoverTone,
+  icon: Icon,
+  iconTone,
+  label,
+  labelTreatment = 'default',
+  media,
+  rel,
+  target,
+  tone,
+  type = 'button',
+  visualPosition = 'start',
+  ...attrs
+}: Props = Astro.props;
+const resolvedRel =
+  rel ?? (target === '_blank' ? 'noopener noreferrer' : undefined);
+const resolvedTone = tone ?? dataTone;
+const hasVisual = Boolean(Icon || media);
+const isLink = Boolean(href);
+const isDisabledLink = isLink && disabled;
+const Root = isLink ? (isDisabledLink ? 'span' : 'a') : 'button';
+---
+
+<Root
+  {...attrs}
+  aria-disabled={isDisabledLink ? 'true' : undefined}
+  class:list={['card-action', className]}
+  data-card-action-compact-label={compactLabel ? true : undefined}
+  data-card-action-hover-tone={hoverTone}
+  data-card-action-label-treatment={labelTreatment}
+  data-card-action-visual-position={hasVisual ? visualPosition : undefined}
+  data-has-visual={hasVisual ? true : undefined}
+  data-surface
+  data-tone={resolvedTone}
+  data-widget="card-action"
+  disabled={!isLink ? disabled : undefined}
+  href={isLink && !disabled ? href : undefined}
+  rel={isLink && !disabled ? resolvedRel : undefined}
+  role={isDisabledLink ? 'link' : undefined}
+  target={isLink && !disabled ? target : undefined}
+  type={!isLink ? type : undefined}
+>
+  {
+    hasVisual ? (
+      <span class="card-action__visual" aria-hidden="true">
+        {Icon ? (
+          <Icon class="card-action__icon" data-tone={iconTone} />
+        ) : media ? (
+          <Media
+            class="card-action__media"
+            media={media}
+            fit="contain"
+            size="intrinsic"
+          />
+        ) : null}
+      </span>
+    ) : null
+  }
+  <span class="card-action__label">
+    <span class="card-action__label-full">{label}</span>
+    {
+      compactLabel ? (
+        <span class="card-action__label-compact" aria-hidden="true">
+          {compactLabel}
+        </span>
+      ) : null
+    }
+  </span>
+</Root>