@astronox/core 0.5.4 → 0.5.6

package/README.md

@@ -48,6 +48,19 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astronox/core",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Reusable Astro components, patterns, styles, and infrastructure for AstroNox sites.",
   "license": "MIT",
   "keywords": [

package/src/components/content/AnnotatedText/AnnotatedText.astro

@@ -0,0 +1,38 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import type { DisplayAnnotatedText } from '../../../display/annotatedText';
+import type { Tone } from '../../../theme/contracts';
+import Tooltip from '../../feedback/Tooltip/Tooltip.astro';
+import MarkedText from './MarkedText.astro';
+
+type Props = Omit<HTMLAttributes<'span'>, 'content'> & {
+  'data-tone'?: Tone;
+  content: DisplayAnnotatedText;
+  interactive?: boolean;
+};
+const { content, interactive = true, class: className, ...attrs } = Astro.props;
+---
+
+<span
+  {...attrs}
+  class:list={['annotated-text', className]}
+  data-widget="annotated-text"
+>
+  {
+    content.map((span) =>
+      span.tooltip && interactive && span.text.trim().length > 0 ? (
+        <Tooltip content={span.tooltip}>
+          <button
+            type="button"
+            class="annotated-text__term"
+            data-tooltip-trigger
+          >
+            {span.text}
+          </button>
+        </Tooltip>
+      ) : (
+        <MarkedText spans={[span]} />
+      ),
+    )
+  }
+</span>

package/src/components/content/AnnotatedText/AnnotatedText.css

@@ -0,0 +1,19 @@
+.annotated-text {
+  white-space: inherit;
+}
+
+.annotated-text__term {
+  display: inline;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--nox-tone-text);
+  font: inherit;
+  font-weight: var(--nox-font-weight-strong);
+  text-align: inherit;
+  white-space: inherit;
+  text-decoration: underline dotted;
+  text-underline-offset: 0.2em;
+  cursor: help;
+}

package/src/components/content/AnnotatedText/MarkedText.astro

@@ -0,0 +1,11 @@
+---
+import type { DisplayTextSpan } from '../../../display/annotatedText';
+type Props = { spans: readonly DisplayTextSpan[] };
+const { spans } = Astro.props;
+---
+
+{
+  spans.map((span) =>
+    span.emphasized ? <strong>{span.text}</strong> : span.text,
+  )
+}

package/src/components/content/InlineDefinition/InlineDefinition.astro

@@ -1,11 +1,13 @@
 ---
 import type { HTMLAttributes } from 'astro/types';
 import type { Tone } from '../../../theme/contracts';
+import type { DisplayAnnotatedText } from '../../../display/annotatedText';
+import AnnotatedText from '../AnnotatedText/AnnotatedText.astro';
 
 type Props = HTMLAttributes<'p'> & {
   'data-tone'?: Tone;
   term: string;
-  text?: string;
+  text?: string | DisplayAnnotatedText;
 };
 
 const {
@@ -26,6 +28,13 @@ const hasText = text !== undefined && text.length > 0;
 >
   <strong class="inline-definition__term">{term}</strong>
   {hasText ? <span class="inline-definition__separator">:</span> : null}
-  {hasText ? <span class="inline-definition__text"> {text}</span> : null}
+  {
+    hasText && text !== undefined ? (
+      <span class="inline-definition__text">
+        {' '}
+        {typeof text === 'string' ? text : <AnnotatedText content={text} />}
+      </span>
+    ) : null
+  }
   {!hasText ? <slot /> : null}
 </p>

package/src/components/data-display/TextPair/TextPair.astro

@@ -1,5 +1,7 @@
 ---
 import type { HTMLAttributes } from 'astro/types';
+import type { DisplayAnnotatedText } from '../../../display/annotatedText';
+import AnnotatedText from '../../content/AnnotatedText/AnnotatedText.astro';
 import type {
   DisplayTextValue,
   TextColor,
@@ -13,7 +15,8 @@ type Props = HTMLAttributes<'span'> & {
   primaryColor?: TextColor;
   primarySize?: TextSize;
   primaryWeight?: TextWeight;
-  secondary?: DisplayTextValue;
+  secondary?: DisplayTextValue | DisplayAnnotatedText;
+  interactiveSecondary?: boolean;
   secondaryWeight?: TextWeight;
   layout?: TextPairLayout;
   truncate?: boolean;
@@ -27,6 +30,7 @@ const {
   primarySize = 'default',
   primaryWeight = 'strong',
   secondary,
+  interactiveSecondary = true,
   secondaryWeight = 'medium',
   truncate = false,
   ...attrs
@@ -56,7 +60,14 @@ const {
         data-part="text-pair-secondary"
         data-text-weight={secondaryWeight}
       >
-        {secondary}
+        {typeof secondary === 'object' ? (
+          <AnnotatedText
+            content={secondary}
+            interactive={interactiveSecondary}
+          />
+        ) : (
+          secondary
+        )}
       </span>
     ) : null
   }

package/src/components/feedback/Tooltip/Tooltip.astro

@@ -1,11 +1,13 @@
 ---
 import type { HTMLAttributes } from 'astro/types';
 import type { Tone } from '../../../theme/contracts';
+import type { DisplayTooltip } from '../../../display/annotatedText';
+import MarkedText from '../../content/AnnotatedText/MarkedText.astro';
 
-type Props = HTMLAttributes<'span'> & {
+type Props = Omit<HTMLAttributes<'span'>, 'content'> & {
   activation?: 'interactive' | 'hover';
   alignTo?: 'boundary' | 'trigger';
-  content: string;
+  content: string | DisplayTooltip;
   tone?: Tone;
   triggerScope?: 'ancestor' | 'content';
 };
@@ -40,7 +42,20 @@ const resolvedTone = tone ?? dataTone;
     popover="manual"
     role="tooltip"
   >
-    {content}
+    {
+      typeof content === 'string' ? (
+        content
+      ) : (
+        <>
+          {content.title ? (
+            <strong class="tooltip__title">{content.title}</strong>
+          ) : null}
+          <span class="tooltip__text">
+            <MarkedText spans={content.content} />
+          </span>
+        </>
+      )
+    }
   </span>
 </nox-tooltip>
 

package/src/components/feedback/Tooltip/Tooltip.css

@@ -50,6 +50,15 @@
   display: none;
 }
 
+.tooltip__title {
+  display: block;
+  margin-block-end: var(--nox-space-2);
+}
+
+.tooltip__text {
+  white-space: pre-line;
+}
+
 @media (width < 30rem) {
   .tooltip__panel {
     --tooltip-viewport-gap: var(--nox-space-3);

package/src/components/index.ts

@@ -11,6 +11,7 @@ export { default as CardHeader } from './content/CardHeader/CardHeader.astro';
 export { default as CardLink } from './content/CardLink/CardLink.astro';
 export { default as CodeBlock } from './content/CodeBlock/CodeBlock.astro';
 export { default as InlineDefinition } from './content/InlineDefinition/InlineDefinition.astro';
+export { default as AnnotatedText } from './content/AnnotatedText/AnnotatedText.astro';
 export { default as MarkdownContent } from './content/MarkdownContent/MarkdownContent.astro';
 export { default as BadgeList } from './data-display/BadgeList/BadgeList.astro';
 export { default as IconList } from './data-display/IconList/IconList.astro';

package/src/display/annotatedText.ts

@@ -0,0 +1,14 @@
+/** Content-only spans; tooltip bodies deliberately cannot contain interactions. */
+export type DisplayTextSpan = {
+  text: string;
+  emphasized?: boolean;
+};
+
+export type DisplayTooltip = {
+  title?: string;
+  content: readonly DisplayTextSpan[];
+};
+
+export type DisplayAnnotatedText = readonly (DisplayTextSpan & {
+  tooltip?: DisplayTooltip;
+})[];

package/src/display/contracts.ts

@@ -1,5 +1,6 @@
 import type { AstroComponent } from '../components/widgetTypes';
 import type { Tone } from '../theme/contracts';
+import type { DisplayAnnotatedText, DisplayTooltip } from './annotatedText';
 
 export type DisplayTextValue = string | number;
 
@@ -217,12 +218,12 @@ export type TableAction = TableActionBase &
   );
 
 export type TableCell = {
-  tooltip?: string;
+  tooltip?: string | DisplayTooltip;
 } & (
   | {
       kind: 'text';
       value: DisplayTextValue;
-      description?: string;
+      description?: string | DisplayAnnotatedText;
       layout?: TextPairLayout;
       primaryColor?: TextColor;
       primarySize?: TextSize;
@@ -233,7 +234,7 @@ export type TableCell = {
       kind: 'link';
       label: string;
       href: string;
-      description?: string;
+      description?: string | DisplayAnnotatedText;
       layout?: TextPairLayout;
       primaryColor?: TextColor;
       primarySize?: TextSize;

package/src/display/index.ts

@@ -1,3 +1,4 @@
 export * from './contracts';
+export * from './annotatedText';
 export * from './responsiveMedia';
 export * from './tableProgressive';

package/src/patterns/MagneticFieldPuzzle/MagneticFieldPuzzle.css

@@ -148,57 +148,6 @@
   overflow: visible;
 }
 
-.magnetic-field-puzzle__path-stream {
-  --field-path-rotation: 0deg;
-
-  position: relative;
-  z-index: 3;
-  grid-row: var(--field-path-row);
-  grid-column: var(--field-path-column);
-  min-inline-size: 0;
-  min-block-size: 0;
-  overflow: visible;
-  pointer-events: none;
-}
-
-.magnetic-field-puzzle__path-chevron {
-  --field-path-chevron-opacity: 0.38;
-
-  position: absolute;
-  display: grid;
-  inset-block-start: var(--field-path-static-block);
-  inset-inline-start: var(--field-path-static-inline);
-  inline-size: 1em;
-  block-size: 1em;
-  place-items: center;
-  color: var(--nox-source-tone-success);
-  font-size: var(--nox-font-size-xl);
-  opacity: var(--field-path-chevron-opacity);
-  pointer-events: none;
-  transform: translate(-50%, -50%) rotate(var(--field-path-rotation));
-}
-
-.magnetic-field-puzzle__path-chevron::before {
-  content: '';
-  inline-size: 0.46em;
-  block-size: 0.46em;
-  border-block-start: calc(var(--nox-border-width) * 2) solid currentColor;
-  border-inline-end: calc(var(--nox-border-width) * 2) solid currentColor;
-  transform: rotate(45deg);
-}
-
-.magnetic-field-puzzle__path-stream[data-field-path-direction='north'] {
-  --field-path-rotation: -90deg;
-}
-
-.magnetic-field-puzzle__path-stream[data-field-path-direction='south'] {
-  --field-path-rotation: 90deg;
-}
-
-.magnetic-field-puzzle__path-stream[data-field-path-direction='west'] {
-  --field-path-rotation: 180deg;
-}
-
 .magnetic-field-puzzle__piece {
   --piece-pupil-block-position: 35%;
   --piece-pupil-inline-position: 68%;
@@ -342,12 +291,6 @@
   .magnetic-field-puzzle__piece[data-piece-moved] {
     animation: magnetic-field-slide 260ms var(--nox-motion-easing-standard);
   }
-
-  .magnetic-field-puzzle__path-chevron {
-    animation: magnetic-field-path var(--field-path-duration) linear infinite
-      both;
-    animation-delay: calc(var(--field-path-chevron-index) * -700ms);
-  }
 }
 
 @keyframes magnetic-field-slide {
@@ -359,25 +302,3 @@
     );
   }
 }
-
-@keyframes magnetic-field-path {
-  0% {
-    inset-block-start: 50%;
-    inset-inline-start: 50%;
-    opacity: 0;
-    transform: translate(-50%, -50%) rotate(var(--field-path-rotation))
-      scale(0.9);
-  }
-
-  12%,
-  82% {
-    opacity: var(--field-path-chevron-opacity);
-  }
-
-  100% {
-    inset-block-start: var(--field-path-target-block);
-    inset-inline-start: var(--field-path-target-inline);
-    opacity: 0;
-    transform: translate(-50%, -50%) rotate(var(--field-path-rotation)) scale(1);
-  }
-}

package/src/patterns/MagneticFieldPuzzle/magneticFieldPuzzleController.ts

@@ -1,3 +1,12 @@
+import {
+  animatePieceMovement,
+  cancelDragFrame,
+  findDirectionalDropDestination,
+  hasLeftOriginCell,
+  renderPathStream,
+  scheduleDragFrame,
+  type PuzzleDrag,
+} from '../PuzzleGrid/movement';
 import {
   setPuzzleGridCellState,
   setPuzzleGridState,
@@ -5,7 +14,6 @@ import {
 import { initPuzzleSelectionDismissal } from '../PuzzleGrid/selectionDismissal';
 import type {
   MagneticFieldDirection,
-  MagneticFieldMovement,
   MagneticFieldPolarity,
   MagneticFieldPupilPosition,
   MagneticFieldPuzzleChangeDetail,
@@ -20,32 +28,14 @@ import {
   simulateMagneticFieldMove,
 } from './simulation';
 
-type MagneticFieldDrag = {
-  pointerId: number;
-  pieceId: string;
-  startX: number;
-  startY: number;
-  currentX: number;
-  currentY: number;
-  frameId: number | null;
-  element: HTMLButtonElement;
-  originCellBounds: DOMRect;
-  originCenterX: number;
-  originCenterY: number;
-  destinations: readonly HTMLButtonElement[] | null;
-  moved: boolean;
-};
-
 type MagneticFieldInstance = {
   activeIndex: number;
   selectedPieceId: string | null;
-  drag: MagneticFieldDrag | null;
+  drag: PuzzleDrag | null;
   ignoreNextClick: boolean;
 };
 
 const dragThreshold = 12;
-const pathChevronsPerCell = 3;
-const pathDurationPerCellMs = 2100;
 const instances = new WeakMap<HTMLElement, MagneticFieldInstance>();
 
 export function initMagneticFieldPuzzle(root: HTMLElement): void {
@@ -155,7 +145,7 @@ export function initMagneticFieldPuzzle(root: HTMLElement): void {
     drag.destinations ??= getDropDestinations(root);
     drag.currentX = event.clientX;
     drag.currentY = event.clientY;
-    scheduleDragFrame(root, drag);
+    scheduleDragFrame(drag, () => instances.get(root)?.drag === drag);
   });
 
   root.addEventListener('pointerup', (event) => {
@@ -295,7 +285,8 @@ function updateDestinations(root: HTMLElement): void {
 
   for (const movement of getMagneticFieldMoves(puzzle, state, pieceId)) {
     const directionLabel = readDirectionLabel(labels, movement.direction);
-    renderPathStream(panel, movement);
+    const board = panel.querySelector<HTMLElement>('[data-field-board]');
+    if (board) renderPathStream(board, movement);
 
     const destination = findCell(panel, movement.to);
     if (!destination) continue;
@@ -452,22 +443,6 @@ function renderState(
   }
 }
 
-function animatePieceMovement(
-  element: HTMLButtonElement,
-  initialBounds: DOMRect,
-): void {
-  const finalBounds = element.getBoundingClientRect();
-  element.style.setProperty(
-    '--piece-move-inline-distance',
-    `${initialBounds.left - finalBounds.left}px`,
-  );
-  element.style.setProperty(
-    '--piece-move-block-distance',
-    `${initialBounds.top - finalBounds.top}px`,
-  );
-  element.setAttribute('data-piece-moved', '');
-}
-
 function finishDrag(
   root: HTMLElement,
   event: PointerEvent,
@@ -508,41 +483,6 @@ function finishDrag(
   if (drag.moved) selectPiece(root, null);
 }
 
-function hasLeftOriginCell(
-  drag: MagneticFieldDrag,
-  deltaX: number,
-  deltaY: number,
-): boolean {
-  const centerX = drag.originCenterX + deltaX;
-  const centerY = drag.originCenterY + deltaY;
-  const { bottom, left, right, top } = drag.originCellBounds;
-
-  return centerX < left || centerX > right || centerY < top || centerY > bottom;
-}
-
-function scheduleDragFrame(root: HTMLElement, drag: MagneticFieldDrag): void {
-  if (drag.frameId !== null) return;
-  drag.frameId = window.requestAnimationFrame(() => {
-    drag.frameId = null;
-    if (instances.get(root)?.drag !== drag) return;
-
-    drag.element.style.setProperty(
-      '--piece-drag-x',
-      `${drag.currentX - drag.startX}px`,
-    );
-    drag.element.style.setProperty(
-      '--piece-drag-y',
-      `${drag.currentY - drag.startY}px`,
-    );
-  });
-}
-
-function cancelDragFrame(drag: MagneticFieldDrag): void {
-  if (drag.frameId === null) return;
-  window.cancelAnimationFrame(drag.frameId);
-  drag.frameId = null;
-}
-
 function getDropDestinations(root: HTMLElement): HTMLButtonElement[] {
   const panel = getActivePanel(root);
   if (!panel) return [];
@@ -552,30 +492,9 @@ function getDropDestinations(root: HTMLElement): HTMLButtonElement[] {
   ];
 }
 
-function findDirectionalDropDestination(
-  drag: MagneticFieldDrag,
-  deltaX: number,
-  deltaY: number,
-): HTMLButtonElement | null {
-  let direction: MagneticFieldDirection;
-  if (Math.abs(deltaX) >= Math.abs(deltaY)) {
-    direction = deltaX >= 0 ? 'east' : 'west';
-  } else {
-    direction = deltaY >= 0 ? 'south' : 'north';
-  }
-
-  return (
-    (drag.destinations ?? []).find(
-      (destination) =>
-        destination.dataset.destinationDirection === direction &&
-        destination.dataset.destinationPiece === drag.pieceId,
-    ) ?? null
-  );
-}
-
 function hideMovePreviews(panel: HTMLElement): void {
   for (const stream of panel.querySelectorAll<HTMLElement>(
-    '[data-field-path-stream]',
+    '[data-puzzle-path-stream]',
   )) {
     stream.remove();
   }
@@ -597,59 +516,6 @@ function hideMovePreviews(panel: HTMLElement): void {
   }
 }
 
-function renderPathStream(
-  panel: HTMLElement,
-  movement: MagneticFieldMovement,
-): void {
-  const board = panel.querySelector<HTMLElement>('[data-field-board]');
-  if (!board) return;
-
-  const rowDistance = movement.to.row - movement.from.row;
-  const columnDistance = movement.to.column - movement.from.column;
-  const cellDistance = Math.abs(rowDistance) + Math.abs(columnDistance);
-  const chevronCount = pathChevronsPerCell * cellDistance;
-  const stream = document.createElement('span');
-  stream.className = 'magnetic-field-puzzle__path-stream';
-  stream.dataset.fieldPathStream = '';
-  stream.dataset.fieldPathDirection = movement.direction;
-  stream.setAttribute('aria-hidden', 'true');
-  stream.style.setProperty('--field-path-row', String(movement.from.row + 1));
-  stream.style.setProperty(
-    '--field-path-column',
-    String(movement.from.column + 1),
-  );
-  stream.style.setProperty(
-    '--field-path-target-inline',
-    `${50 + columnDistance * 100}%`,
-  );
-  stream.style.setProperty(
-    '--field-path-target-block',
-    `${50 + rowDistance * 100}%`,
-  );
-  stream.style.setProperty(
-    '--field-path-duration',
-    `${pathDurationPerCellMs * cellDistance}ms`,
-  );
-
-  for (let index = 0; index < chevronCount; index += 1) {
-    const progress = (index + 0.5) / chevronCount;
-    const chevron = document.createElement('span');
-    chevron.className = 'magnetic-field-puzzle__path-chevron';
-    chevron.style.setProperty('--field-path-chevron-index', String(index));
-    chevron.style.setProperty(
-      '--field-path-static-inline',
-      `${50 + columnDistance * progress * 100}%`,
-    );
-    chevron.style.setProperty(
-      '--field-path-static-block',
-      `${50 + rowDistance * progress * 100}%`,
-    );
-    stream.append(chevron);
-  }
-
-  board.append(stream);
-}
-
 function findCell(
   panel: HTMLElement,
   position: { row: number; column: number },

package/src/patterns/PuzzleGrid/movement.css

@@ -0,0 +1,80 @@
+.puzzle-grid__path-stream {
+  --puzzle-path-rotation: 0deg;
+
+  position: relative;
+  z-index: 3;
+  grid-row: var(--puzzle-path-row);
+  grid-column: var(--puzzle-path-column);
+  min-inline-size: 0;
+  min-block-size: 0;
+  overflow: visible;
+  pointer-events: none;
+}
+
+.puzzle-grid__path-chevron {
+  --puzzle-path-chevron-opacity: 0.38;
+
+  position: absolute;
+  display: grid;
+  inset-block-start: var(--puzzle-path-static-block);
+  inset-inline-start: var(--puzzle-path-static-inline);
+  inline-size: 1em;
+  block-size: 1em;
+  place-items: center;
+  color: var(--nox-source-tone-success);
+  font-size: var(--nox-font-size-xl);
+  opacity: var(--puzzle-path-chevron-opacity);
+  pointer-events: none;
+  transform: translate(-50%, -50%) rotate(var(--puzzle-path-rotation));
+}
+
+.puzzle-grid__path-chevron::before {
+  content: '';
+  inline-size: 0.46em;
+  block-size: 0.46em;
+  border-block-start: calc(var(--nox-border-width) * 2) solid currentColor;
+  border-inline-end: calc(var(--nox-border-width) * 2) solid currentColor;
+  transform: rotate(45deg);
+}
+
+.puzzle-grid__path-stream[data-puzzle-path-direction='north'] {
+  --puzzle-path-rotation: -90deg;
+}
+
+.puzzle-grid__path-stream[data-puzzle-path-direction='south'] {
+  --puzzle-path-rotation: 90deg;
+}
+
+.puzzle-grid__path-stream[data-puzzle-path-direction='west'] {
+  --puzzle-path-rotation: 180deg;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .puzzle-grid__path-chevron {
+    animation: puzzle-grid-path var(--puzzle-path-duration) linear infinite both;
+    animation-delay: calc(var(--puzzle-path-chevron-index) * -700ms);
+  }
+}
+
+@keyframes puzzle-grid-path {
+  0% {
+    inset-block-start: 50%;
+    inset-inline-start: 50%;
+    opacity: 0;
+    transform: translate(-50%, -50%) rotate(var(--puzzle-path-rotation))
+      scale(0.9);
+  }
+
+  12%,
+  82% {
+    opacity: var(--puzzle-path-chevron-opacity);
+  }
+
+  100% {
+    inset-block-start: var(--puzzle-path-target-block);
+    inset-inline-start: var(--puzzle-path-target-inline);
+    opacity: 0;
+    transform: translate(-50%, -50%) rotate(var(--puzzle-path-rotation))
+      scale(1);
+  }
+}