@astronox/core 0.1.0

package/src/composition/SurfaceGroup/SurfaceGroup.css

@@ -0,0 +1,76 @@
+.surface-group {
+  container: nox-surface-group / inline-size;
+  display: flex;
+  min-width: 0;
+  min-height: 0;
+  flex-direction: column;
+}
+
+.surface-group > [data-sticky-sentinel] {
+  display: block;
+  min-width: 0;
+  block-size: 1px;
+  flex: 0 0 1px;
+  margin-block-end: -1px;
+  visibility: hidden;
+  pointer-events: none;
+}
+
+.surface-group:has(> [data-sticky-surface])::before {
+  --surface-group-sticky-occlusion-size: calc(
+    var(--nox-layout-gap) + var(--nox-section-responsive-block-size)
+  );
+
+  position: sticky;
+  z-index: 39;
+  top: 0;
+  display: block;
+  min-width: 0;
+  min-height: var(--surface-group-sticky-occlusion-size);
+  visibility: hidden;
+  flex: 0 0 var(--surface-group-sticky-occlusion-size);
+  margin-block-end: calc(-1 * var(--surface-group-sticky-occlusion-size));
+  background: var(--nox-page-background);
+  content: '';
+}
+
+.surface-group[data-sticky-active]::before {
+  visibility: visible;
+}
+
+.surface-group > [data-surface] {
+  flex: 0 0 auto;
+  min-width: 0;
+}
+
+.surface-group
+  > [data-surface]:not(
+    :has(~ [data-surface]),
+    [data-surface-sizing='content']
+  ),
+.surface-group
+  > [data-surface]:has(
+    + [data-surface][data-surface-sizing='content']
+  ) {
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
+.surface-group > [data-surface]:has(+ [data-surface]) {
+  border-end-start-radius: 0;
+  border-end-end-radius: 0;
+}
+
+.surface-group > [data-surface] + [data-surface] {
+  border-block-start-width: 0;
+  border-start-start-radius: 0;
+  border-start-end-radius: 0;
+}
+
+@container nox-surface-group (width < 32rem) {
+  .surface-group:has(> [data-sticky-surface])::before {
+    --surface-group-sticky-occlusion-size: calc(
+      var(--nox-layout-gap) + var(--nox-section-compact-block-size)
+    );
+  }
+}

package/src/composition/SurfaceGroup/stickySurfaceGroupController.ts

@@ -0,0 +1,89 @@
+const noop = () => {};
+
+const getScrollParent = (element: HTMLElement): HTMLElement | Window => {
+  let parent = element.parentElement;
+
+  while (parent) {
+    const styles = window.getComputedStyle(parent);
+
+    if (/(auto|scroll|overlay)/.test(styles.overflowY)) {
+      return parent;
+    }
+
+    parent = parent.parentElement;
+  }
+
+  return window;
+};
+
+export const initStickySurfaceGroup = (root: HTMLElement): (() => void) => {
+  if (root.hasAttribute('data-sticky-initialized')) {
+    return noop;
+  }
+
+  const stickySurface = Array.from(root.children).find(
+    (child): child is HTMLElement =>
+      child instanceof HTMLElement && child.hasAttribute('data-sticky-surface'),
+  );
+
+  if (!stickySurface) {
+    return noop;
+  }
+
+  const scrollParent = getScrollParent(root);
+  const sentinel = document.createElement('span');
+  sentinel.setAttribute('data-sticky-sentinel', '');
+  sentinel.setAttribute('aria-hidden', 'true');
+  stickySurface.before(sentinel);
+
+  let observer: IntersectionObserver | null = null;
+  let resizeFrame = 0;
+
+  const observe = () => {
+    resizeFrame = 0;
+    observer?.disconnect();
+
+    const stickyOffset =
+      Number.parseFloat(window.getComputedStyle(stickySurface).top) || 0;
+    observer = new IntersectionObserver(
+      ([entry]) => {
+        if (!entry) return;
+
+        const activationBoundary = entry.rootBounds?.top ?? stickyOffset;
+        root.toggleAttribute(
+          'data-sticky-active',
+          entry.boundingClientRect.top <= activationBoundary + 0.5,
+        );
+      },
+      {
+        root: scrollParent instanceof Window ? null : scrollParent,
+        rootMargin: `${-stickyOffset}px 0px 0px`,
+        threshold: 0,
+      },
+    );
+    observer.observe(sentinel);
+  };
+
+  const scheduleObserve = () => {
+    if (resizeFrame === 0) {
+      resizeFrame = window.requestAnimationFrame(observe);
+    }
+  };
+
+  root.setAttribute('data-sticky-initialized', 'true');
+  window.addEventListener('resize', scheduleObserve, { passive: true });
+  observe();
+
+  return () => {
+    window.removeEventListener('resize', scheduleObserve);
+    observer?.disconnect();
+    sentinel.remove();
+
+    if (resizeFrame !== 0) {
+      window.cancelAnimationFrame(resizeFrame);
+    }
+
+    root.removeAttribute('data-sticky-active');
+    root.removeAttribute('data-sticky-initialized');
+  };
+};

package/src/composition/index.ts

@@ -0,0 +1,6 @@
+export { default as Grid } from './Grid/Grid.astro';
+export { default as GridItem } from './GridItem/GridItem.astro';
+export { default as Inline } from './Inline/Inline.astro';
+export { default as Stack } from './Stack/Stack.astro';
+export { default as SurfaceGroup } from './SurfaceGroup/SurfaceGroup.astro';
+export * from './SurfaceGroup/stickySurfaceGroupController';

package/src/config/index.ts

@@ -0,0 +1,2 @@
+export * from './pageMeta';
+export * from './siteConfig';

package/src/config/pageMeta.ts

@@ -0,0 +1,55 @@
+export type PageRobots = {
+  index?: boolean;
+  follow?: boolean;
+  maxImagePreview?: 'large' | 'none' | 'standard';
+};
+
+export type PageOpenGraphType = 'article' | 'website';
+
+export type PageSeoType = 'article' | 'collection-page' | 'web-page';
+
+export type PageTitleBranding = 'append' | 'none';
+
+export type PageAlternate = {
+  lang: string;
+  href: string;
+};
+
+export type PageMeta = {
+  title: string;
+  titleBranding?: PageTitleBranding;
+  description?: string;
+  lang?: string;
+  canonical?: string;
+  socialImage?: string;
+  socialImageAlt?: string;
+  socialImageType?: string;
+  socialImageWidth?: number;
+  socialImageHeight?: number;
+  openGraphType?: PageOpenGraphType;
+  openGraphLocale?: string;
+  openGraphLocaleAlternates?: readonly string[];
+  alternates?: readonly PageAlternate[];
+  seoType?: PageSeoType;
+  datePublished?: string;
+  robots?: PageRobots;
+};
+
+export function formatRobotsDirective(
+  robots: PageRobots | undefined,
+): string | undefined {
+  if (!robots) {
+    return undefined;
+  }
+
+  const indexDirective = robots.index === false ? 'noindex' : 'index';
+  const followDirective = robots.follow === false ? 'nofollow' : 'follow';
+
+  const directives = [indexDirective, followDirective];
+
+  if (robots.maxImagePreview) {
+    directives.push(`max-image-preview:${robots.maxImagePreview}`);
+  }
+
+  return directives.join(', ');
+}

package/src/config/siteConfig.ts

@@ -0,0 +1,90 @@
+import type { PageMeta } from './pageMeta';
+
+export type SiteTextDirection = 'ltr' | 'rtl';
+
+export type SiteLocaleConfig = {
+  id: string;
+  urlCode: string;
+  languageTag: string;
+  nativeLabel: string;
+  intlLocale: string;
+  openGraphLocale: string;
+  direction: SiteTextDirection;
+};
+
+export type SiteIdentity = {
+  name: string;
+  shortName?: string;
+  logo?: {
+    src: string;
+    alt: string;
+    width: number;
+    height: number;
+  };
+};
+
+export type TwitterCardType = 'summary' | 'summary_large_image';
+
+export type SiteIconConfig = {
+  href: string;
+  type?: string;
+  sizes?: string;
+};
+
+export type SiteThemeColor = {
+  color: string;
+  media?: string;
+};
+
+export type SiteSeoConfig = {
+  siteUrl: string;
+  titleSeparator: string;
+  defaultSocialImage?: string;
+  defaultSocialImageAlt?: string;
+  defaultSocialImageType?: string;
+  defaultSocialImageWidth?: number;
+  defaultSocialImageHeight?: number;
+  icons?: readonly SiteIconConfig[];
+  appleTouchIcon?: SiteIconConfig;
+  webManifest?: string;
+  themeColors?: readonly SiteThemeColor[];
+  twitterCard: TwitterCardType;
+};
+
+export type SiteConfig = {
+  identity: SiteIdentity;
+  defaultLocale: string;
+  locales: readonly [SiteLocaleConfig, ...SiteLocaleConfig[]];
+  routing: {
+    prefixDefaultLocale: boolean;
+  };
+  defaultMeta: PageMeta & {
+    description: string;
+    lang: string;
+  };
+  seo: SiteSeoConfig;
+};
+
+export function defineSiteConfig<const TConfig extends SiteConfig>(
+  config: TConfig,
+): TConfig {
+  const localeIds = new Set<string>();
+  const urlCodes = new Set<string>();
+
+  for (const locale of config.locales) {
+    if (localeIds.has(locale.id)) {
+      throw new Error(`Duplicate site locale: ${locale.id}`);
+    }
+    if (urlCodes.has(locale.urlCode)) {
+      throw new Error(`Duplicate site locale URL code: ${locale.urlCode}`);
+    }
+    localeIds.add(locale.id);
+    urlCodes.add(locale.urlCode);
+  }
+
+  if (!localeIds.has(config.defaultLocale)) {
+    throw new Error(`Unknown default site locale: ${config.defaultLocale}`);
+  }
+
+  return config;
+}

package/src/data/collectionValidation.ts

@@ -0,0 +1,61 @@
+import type { ZodError, ZodType } from 'zod';
+
+export function validateCollectionData<TData>(
+  schema: ZodType<TData>,
+  rawData: unknown,
+  collectionName: string,
+): TData {
+  const result = schema.safeParse(rawData);
+
+  if (result.success) {
+    return result.data;
+  }
+
+  throw new Error(formatCollectionError(collectionName, result.error));
+}
+
+export function assertUniqueCollectionValues<TItem>(
+  items: readonly TItem[],
+  getValue: (item: TItem) => string,
+  collectionName: string,
+  fieldLabel: string,
+): void {
+  const seenValues = new Set<string>();
+  const duplicateValues = new Set<string>();
+
+  for (const item of items) {
+    const value = getValue(item);
+
+    if (seenValues.has(value)) {
+      duplicateValues.add(value);
+      continue;
+    }
+
+    seenValues.add(value);
+  }
+
+  if (duplicateValues.size === 0) {
+    return;
+  }
+
+  throw new Error(
+    `Invalid ${collectionName}: duplicate ${fieldLabel} value(s): ${[
+      ...duplicateValues,
+    ].join(', ')}`,
+  );
+}
+
+function formatCollectionError(
+  collectionName: string,
+  error: ZodError,
+): string {
+  const issues = error.issues
+    .map((issue) => {
+      const path = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+
+      return `- ${path}: ${issue.message}`;
+    })
+    .join('\n');
+
+  return `Invalid ${collectionName} data:\n${issues}`;
+}

package/src/data/index.ts

@@ -0,0 +1 @@
+export * from './collectionValidation';

package/src/display/contracts.ts

@@ -0,0 +1,284 @@
+import type { AstroComponent } from '../components/widgetTypes';
+import type { Tone } from '../theme/contracts';
+
+export type DisplayTextValue = string | number;
+
+export type TextPairLayout = 'stack' | 'inline' | 'split';
+export type TextColor = 'default' | 'inherit' | 'muted';
+export type TextSize = 'default' | 'small' | 'large';
+export type TextWeight = 'regular' | 'medium' | 'strong';
+
+export type DisplayMediaFit =
+  'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+export type DisplayMediaFraming = 'asset' | 'content';
+export type DisplayMediaRendering = 'auto' | 'pixelated';
+export type DisplayMediaShape = 'default' | 'circle';
+export type DisplayMediaUpscale = 'allow' | 'prevent';
+export type DisplayMediaVisualSize = 'default' | 'compact';
+export type DisplayMediaDecoding = 'async' | 'auto' | 'sync';
+export type DisplayMediaFetchPriority = 'auto' | 'high' | 'low';
+
+export type DisplayMediaContentBounds = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+export type DisplayBadge = {
+  label: string;
+  value?: DisplayTextValue;
+  description?: string;
+  href?: string;
+  tone?: Tone;
+};
+
+export type DisplayMedia = {
+  src: string;
+  alt: string;
+  width: number;
+  height: number;
+  contentBounds?: DisplayMediaContentBounds;
+  sizes?: string;
+  sources?: readonly {
+    src: string;
+    width: number;
+  }[];
+  caption?: string;
+  decoding?: DisplayMediaDecoding;
+  fetchPriority?: DisplayMediaFetchPriority;
+  fit?: DisplayMediaFit;
+  framing?: DisplayMediaFraming;
+  loading?: 'eager' | 'lazy';
+  rendering?: DisplayMediaRendering;
+  shape?: DisplayMediaShape;
+  upscale?: DisplayMediaUpscale;
+  visualSize?: DisplayMediaVisualSize;
+};
+
+export type DisplayTagAffix =
+  | {
+      icon: AstroComponent;
+      iconTone?: Tone;
+      media?: never;
+      value?: DisplayTextValue;
+    }
+  | {
+      icon?: never;
+      iconTone?: never;
+      media: DisplayMedia;
+      value?: DisplayTextValue;
+    }
+  | {
+      icon?: never;
+      iconTone?: never;
+      media?: never;
+      value?: DisplayTextValue;
+    };
+
+export type DisplayTag = {
+  active?: boolean;
+  href?: string;
+  label: string;
+  leading?: DisplayTagAffix;
+  trailing?: DisplayTagAffix;
+  tone?: Tone;
+};
+
+export type DisplayIconItem = {
+  icon: AstroComponent;
+  iconPosition?: 'start' | 'end';
+  label: string;
+  muted?: boolean;
+  tone?: Tone;
+  value?: DisplayTextValue;
+};
+
+export type BreadcrumbItem = {
+  label: string;
+  href: string;
+};
+
+type DisplayCardLinkContent = {
+  collapse?: 'none' | 'icon';
+  compactContent?: 'text' | 'media';
+  compactText?: DisplayTextValue;
+  compactVisual?: 'show' | 'hide';
+  iconTone?: Tone;
+  label: string;
+  title: string;
+  meta?: DisplayTextValue;
+  media?: DisplayMedia;
+  mediaPosition?: 'start' | 'end';
+  mediaSize?: 'default' | 'compact' | 'small';
+  direction?: 'previous' | 'next';
+  full?: boolean;
+  tone?: Tone;
+};
+
+export type DisplayCardLink =
+  | (DisplayCardLinkContent & {
+      mode?: 'link';
+      href?: string;
+      disabled?: boolean;
+    })
+  | (DisplayCardLinkContent & {
+      mode: 'static';
+      href?: never;
+      disabled?: boolean;
+    });
+
+type DisplayMetricBase = {
+  label: string;
+  description?: string;
+  tone?: Tone;
+};
+
+export type DisplayMetricIcon = {
+  component: AstroComponent;
+  label: string;
+  position?: 'start' | 'end';
+  tone?: Tone;
+};
+
+export type DisplayMetric = DisplayMetricBase &
+  (
+    | {
+        icon?: DisplayMetricIcon;
+        items?: never;
+        itemsLabel?: never;
+        unit?: string;
+        value: DisplayTextValue;
+      }
+    | {
+        icon?: never;
+        items: readonly DisplayIconItem[];
+        itemsLabel: string;
+        unit?: never;
+        value?: never;
+      }
+  );
+
+export type StageFlowItem = {
+  title: string;
+  tags?: readonly DisplayTag[];
+  href?: string;
+  media?: DisplayMedia;
+  active?: boolean;
+};
+
+export type StageFlowStep = {
+  options: readonly StageFlowItem[];
+};
+
+export type TableColumnRole =
+  | 'ordinal'
+  | 'media'
+  | 'primary'
+  | 'value'
+  | 'collection';
+export type TableColumnAlignment = 'start' | 'center' | 'end';
+
+export type TableColumn = {
+  id: string;
+  label: string;
+  role: TableColumnRole;
+  align?: TableColumnAlignment;
+  headerAlign?: TableColumnAlignment;
+  hiddenLabel?: boolean;
+  rowHeader?: boolean;
+  sizing?: 'content' | 'fill';
+  wrap?: boolean;
+  sort?: {
+    type: 'number' | 'text';
+    tieBreaker?: string;
+  };
+};
+
+export type TableCell = {
+  tooltip?: string;
+} & (
+  | {
+      kind: 'text';
+      value: DisplayTextValue;
+      description?: string;
+      layout?: TextPairLayout;
+      primaryColor?: TextColor;
+      primarySize?: TextSize;
+      primaryWeight?: TextWeight;
+      secondaryWeight?: TextWeight;
+    }
+  | {
+      kind: 'link';
+      label: string;
+      href: string;
+      description?: string;
+      layout?: TextPairLayout;
+      primaryColor?: TextColor;
+      primarySize?: TextSize;
+      primaryWeight?: TextWeight;
+      secondaryWeight?: TextWeight;
+    }
+  | {
+      kind: 'media';
+      media: DisplayMedia;
+      size?: 'default' | 'compact';
+    }
+  | {
+      kind: 'badges';
+      badges: readonly DisplayBadge[];
+    }
+  | {
+      kind: 'icons';
+      items: readonly DisplayIconItem[];
+      label?: string;
+      size?: 'small' | 'medium';
+    }
+  | {
+      kind: 'tags';
+      tags: readonly DisplayTag[];
+    }
+);
+
+export type TableRow = {
+  key?: string;
+  href?: string;
+  hidden?: boolean;
+  filters?: Readonly<Record<string, readonly string[]>>;
+  sortValues?: Readonly<Record<string, string | number | null>>;
+  cells: Readonly<Record<string, TableCell>>;
+};
+
+export type TablePaginationModel = {
+  page: number;
+  totalPages: number;
+  nextHref?: string;
+};
+
+type NavigationItemBase = {
+  active?: boolean;
+  id?: string;
+  label: string;
+  href?: string;
+  description?: string;
+  activeMatch?: 'exact' | 'prefix';
+  activePaths?: readonly string[];
+  disabled?: boolean;
+  rel?: string;
+  target?: '_blank' | '_self';
+  hreflang?: string;
+  media?: DisplayMedia;
+  mediaFrame?: 'bordered';
+  mediaShape?: 'circle' | 'rectangle';
+};
+
+export type NavigationLinkItem = NavigationItemBase & {
+  items?: undefined;
+};
+
+export type NavigationGroupItem = NavigationItemBase & {
+  id: string;
+  items: readonly [NavigationLinkItem, ...NavigationLinkItem[]];
+};
+
+export type NavigationItem = NavigationLinkItem | NavigationGroupItem;

package/src/display/index.ts

@@ -0,0 +1 @@
+export * from './contracts';

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './client/index';
+export * from './config/index';
+export * from './data/index';
+export * from './display/index';
+export * from './seo/index';
+export * from './theme/index';