@astronox/core 0.5.4 → 0.5.5

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.5",
   "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/Table/TableBody.astro

@@ -142,7 +142,13 @@ const stateMessage =
                       data-table-column={column.id}
                       data-table-column-role={column.role}
                       data-tooltip-trigger={
-                        cell?.tooltip?.trim() ? true : undefined
+                        (
+                          typeof cell?.tooltip === 'string'
+                            ? cell.tooltip.trim()
+                            : cell?.tooltip
+                        )
+                          ? true
+                          : undefined
                       }
                     >
                       <TableCellContent

package/src/patterns/Table/TableCell.astro

@@ -11,7 +11,8 @@ type Props = {
 };
 
 const { cell, rowHref, truncate = false, wrap = false }: Props = Astro.props;
-const tooltip = cell?.tooltip?.trim();
+const tooltip =
+  typeof cell?.tooltip === 'string' ? cell.tooltip.trim() : cell?.tooltip;
 const layout =
   cell?.kind === 'text' || cell?.kind === 'link' ? cell.layout : undefined;
 
@@ -37,6 +38,7 @@ const rootAttributes = cell
         <div {...rootAttributes}>
           <TableCellValue
             cell={cell}
+            interactive={false}
             rowHref={rowHref}
             truncate={truncate}
             wrap={wrap}

package/src/patterns/Table/TableCellValue.astro

@@ -10,12 +10,19 @@ import Button from '../../components/actions/Button/Button.astro';
 
 type Props = {
   cell: TableCell;
+  interactive?: boolean;
   rowHref?: string;
   truncate?: boolean;
   wrap: boolean;
 };
 
-const { cell, rowHref, truncate = false, wrap }: Props = Astro.props;
+const {
+  cell,
+  interactive = true,
+  rowHref,
+  truncate = false,
+  wrap,
+}: Props = Astro.props;
 
 const formatValue = (value: DisplayTextValue): string => String(value);
 ---
@@ -28,6 +35,7 @@ const formatValue = (value: DisplayTextValue): string => String(value);
       primarySize={cell.primarySize}
       primaryWeight={cell.primaryWeight ?? 'regular'}
       secondary={cell.description}
+      interactiveSecondary={interactive}
       secondaryWeight={cell.secondaryWeight}
       layout={cell.layout}
       truncate={truncate}
@@ -48,6 +56,7 @@ const formatValue = (value: DisplayTextValue): string => String(value);
         primarySize={cell.primarySize}
         primaryWeight={cell.primaryWeight}
         secondary={cell.description}
+        interactiveSecondary={false}
         secondaryWeight={cell.secondaryWeight}
         layout={cell.layout}
         truncate={truncate}

package/src/primitives/text/TextBlock/TextBlock.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 '../../../components/content/AnnotatedText/AnnotatedText.astro';
 
 type Props = HTMLAttributes<'p'> & {
   'data-tone'?: Tone;
   preserveBreaks?: boolean;
-  text: string;
+  text: string | DisplayAnnotatedText;
 };
 
 const {
@@ -15,7 +17,49 @@ const {
   text,
   ...attrs
 }: Props = Astro.props;
-const paragraphs = preserveBreaks ? text.split(/\r?\n(?:[ \t]*\r?\n)+/) : [];
+function splitParagraphs(
+  content: DisplayAnnotatedText,
+): DisplayAnnotatedText[] {
+  const text = content.map((span) => span.text).join('');
+  const result: DisplayAnnotatedText[] = [];
+  let spanIndex = 0;
+  let spanStart = 0;
+
+  // Slice the original annotations using offsets in the complete text. Paragraph
+  // separators may cross span boundaries, including between CR and LF.
+  const slice = (start: number, end: number): DisplayAnnotatedText => {
+    const spans: Array<DisplayAnnotatedText[number]> = [];
+    while (spanIndex < content.length && spanStart < end) {
+      const span = content[spanIndex]!;
+      const spanEnd = spanStart + span.text.length;
+      const from = Math.max(start, spanStart);
+      const to = Math.min(end, spanEnd);
+      if (from < to) {
+        spans.push({
+          ...span,
+          text: span.text.slice(from - spanStart, to - spanStart),
+        });
+      }
+      if (spanEnd > end) break;
+      spanStart = spanEnd;
+      spanIndex += 1;
+    }
+    return spans;
+  };
+
+  let start = 0;
+  for (const separator of text.matchAll(/\r?\n(?:[ \t]*\r?\n)+/g)) {
+    result.push(slice(start, separator.index));
+    start = separator.index + separator[0].length;
+  }
+  result.push(slice(start, text.length));
+  return result;
+}
+const paragraphs = !preserveBreaks
+  ? []
+  : typeof text === 'string'
+    ? text.split(/\r?\n(?:[ \t]*\r?\n)+/)
+    : splitParagraphs(text);
 ---
 
 {
@@ -28,7 +72,13 @@ const paragraphs = preserveBreaks ? text.split(/\r?\n(?:[ \t]*\r?\n)+/) : [];
       data-tone={dataTone}
     >
       {paragraphs.map((paragraph) => (
-        <p class="text-block__paragraph">{paragraph}</p>
+        <p class="text-block__paragraph">
+          {typeof paragraph === 'string' ? (
+            paragraph
+          ) : (
+            <AnnotatedText content={paragraph} />
+          )}
+        </p>
       ))}
     </div>
   ) : (
@@ -38,7 +88,7 @@ const paragraphs = preserveBreaks ? text.split(/\r?\n(?:[ \t]*\r?\n)+/) : [];
       data-widget="text-block"
       data-tone={dataTone}
     >
-      {text}
+      {typeof text === 'string' ? text : <AnnotatedText content={text} />}
     </p>
   )
 }

package/src/styles/style.css

@@ -28,6 +28,8 @@
 @import '../components/content/CardLink/CardLink.css' layer(components);
 @import '../components/content/InlineDefinition/InlineDefinition.css'
   layer(components);
+@import '../components/content/AnnotatedText/AnnotatedText.css'
+  layer(components);
 @import '../components/content/MarkdownContent/MarkdownContent.css'
   layer(components);
 @import '../components/data-display/BadgeList/BadgeList.css' layer(components);