@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/elements/heading/definition.ts

@@ -0,0 +1,64 @@
+import type { ElementDefinition, ElementNode } from '../definition.ts'
+
+/**
+ * `<ty-heading>`: the Heading's single source (spec: wave-1/heading.md).
+ *
+ * The document level (`level`, h1 to h6) and the visual step (`appearance`)
+ * are independent; unset, the step derives from the level (1 → h1, 2 → h2,
+ * 3 and deeper → h3). The convenience Subheading of the React component is
+ * this element with `level="2" appearance="h3"`. The optional `eyebrow`
+ * renders before, and outside, the heading element, so the heading's
+ * accessible name stays the heading text alone. The heading carries a
+ * stable id (`heading-id`, generated from the instance otherwise) so
+ * sections and dialogs can label themselves by it.
+ *
+ * The anatomy root is always the group wrapper (the React component renders
+ * it only with an eyebrow); it adds no box beyond the column gap, and
+ * keeping it unconditional lets every renderer express one tree.
+ */
+export const headingDefinition = {
+  tag: 'ty-heading',
+  name: 'TyHeading',
+  kind: 'enhancing',
+  doc: 'Section title whose document level (`level`, h1 to h6) and visual step (`appearance`: display, h1, h2, h3 or label) are set independently; unset, the step derives from the level. An optional `eyebrow` labels the section above the heading, outside the heading element. The heading id (`heading-id`, generated otherwise) lets a section or dialog reference it with `aria-labelledby`. `level="2" appearance="h3"` is the Subheading.',
+  props: {
+    level: { type: 'enum', values: ['1', '2', '3', '4', '5', '6'], default: '1', attribute: 'level', doc: 'Document outline level (1 to 6, as its attribute spelling); one h1 per page, no skipped levels.' },
+    appearance: { type: 'enum', values: ['display', 'h1', 'h2', 'h3', 'label'], attribute: 'appearance', doc: 'Visual step from the type scale of §2.2, decoupled from `level`; derived from the level when unset (1 → h1, 2 → h2, 3+ → h3).' },
+    eyebrow: { type: 'string', attribute: 'eyebrow', doc: 'Small uppercase label rendered before, and outside, the heading element (the §2.2 eyebrow token); the heading text alone stays the accessible name.' },
+    headingId: { type: 'string', attribute: 'heading-id', doc: 'Stable id of the heading element, for `aria-labelledby` of the enclosing section or dialog; `<instance>-heading` when unset.' },
+  },
+  events: [],
+  slots: {
+    default: { doc: 'The heading text.' },
+  },
+  anatomy: {
+    tag: 'div',
+    class: 'ty-heading-group',
+    children: [
+      { tag: 'p', class: 'ty-heading__eyebrow', when: ['eyebrow'], children: [{ text: { prop: 'eyebrow' } }] },
+      ...([1, 2, 3, 4, 5, 6] as const).map((n): ElementNode => ({
+        tag: `h${n}`,
+        class: 'ty-heading',
+        when: [`level:${n}`],
+        attrs: {
+          id: { idref: 'heading', prop: 'headingId' },
+          'data-appearance': {
+            prop: 'appearance',
+            kind: 'map',
+            values: { display: 'display', h1: 'h1', h2: 'h2', h3: 'h3', label: 'label' },
+            fallback: { prop: 'level', values: { '1': 'h1', '2': 'h2', '3': 'h3', '4': 'h3', '5': 'h3', '6': 'h3' } },
+          },
+        },
+        children: [{ slot: 'default' }],
+      })),
+    ],
+  },
+  examples: [
+    { name: 'page-title', props: {}, slots: { default: 'Sources' } },
+    { name: 'level-3', props: { level: '3' }, slots: { default: 'Field mapping' } },
+    { name: 'small-level-big-step', props: { level: '2', appearance: 'h1' }, slots: { default: 'Workspace' } },
+    { name: 'eyebrow', props: { level: '2', eyebrow: 'Datasets' }, slots: { default: 'Revenue by state' } },
+    { name: 'label-step', props: { level: '4', appearance: 'label' }, slots: { default: 'Owner' } },
+    { name: 'subheading', props: { level: '2', appearance: 'h3' }, slots: { default: 'Recent runs' } },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/heading/element.ts

@@ -0,0 +1,14 @@
+import { TyElement } from '../base.ts'
+import { headingDefinition } from './definition.ts'
+
+/**
+ * `<ty-heading>`. All presentation: the host framework renders the anatomy
+ * (the optional eyebrow and the heading of the chosen level) and the
+ * stylesheet draws the type steps, including the narrow h1 and the
+ * forced-colours fallback. Not a widget — no keyboard or events; the base
+ * class builds and patches the anatomy for plain-HTML use (swapping the
+ * heading tag when `level` changes) and keeps the bound attributes in step.
+ */
+export class TyHeadingElement extends TyElement {
+  static override definition = headingDefinition
+}

package/src/elements/index.ts

@@ -0,0 +1,146 @@
+// Tympan custom elements: one definition per component, consumed by React
+// (generated wrappers in ./react) and by plain HTML. See docs/design/single-source-components.md.
+
+import { defineTympanElement } from './base.ts'
+import { TyWheelPickerElement } from './wheel-picker/element.ts'
+import { TyToastElement } from './toast/element.ts'
+import { TyTagFieldElement } from './tag-field/element.ts'
+import { TyTabsElement } from './tabs/element.ts'
+import { TySkipLinkElement } from './skip-link/element.ts'
+import { TySegmentedControlElement } from './segmented-control/element.ts'
+import { TySectionHeadingElement } from './section-heading/element.ts'
+import { TyProgressBarElement } from './progress-bar/element.ts'
+import { TyPageHeaderElement } from './page-header/element.ts'
+import { TyNotificationCenterElement } from './notification-center/element.ts'
+import { TyMarkdownViewElement } from './markdown-view/element.ts'
+import { TyHeadingElement } from './heading/element.ts'
+import { TyDataTableElement } from './data-table/element.ts'
+import { TyCurrencyFieldElement } from './currency-field/element.ts'
+import { TyCommandPaletteElement } from './command-palette/element.ts'
+import { TyBreadcrumbsElement } from './breadcrumbs/element.ts'
+import { TyBrandWordmarkElement } from './brand-wordmark/element.ts'
+import { TyAvatarElement } from './avatar/element.ts'
+import { TyActionMenuElement } from './action-menu/element.ts'
+import { TyButtonElement } from './button/element.ts'
+import { TyCheckboxElement } from './checkbox/element.ts'
+import { TyDrawerElement } from './drawer/element.ts'
+import { TyGradientMarkElement } from './gradient-mark/element.ts'
+import { TyInlineNoticeElement } from './inline-notice/element.ts'
+import { TyLinkElement } from './link/element.ts'
+import { TyModalElement } from './modal/element.ts'
+import { TyPopoverElement } from './popover/element.ts'
+import { TyNativeSelectElement } from './native-select/element.ts'
+import { TySeparatorElement } from './separator/element.ts'
+import { TySkeletonElement } from './skeleton/element.ts'
+import { TySpinnerElement } from './spinner/element.ts'
+import { TyStatusPillElement } from './status-pill/element.ts'
+import { TySurfaceElement } from './surface/element.ts'
+import { TySwitchElement } from './switch/element.ts'
+import { TyTagElement } from './tag/element.ts'
+import { TyTextAreaElement } from './text-area/element.ts'
+import { TyTextFieldElement } from './text-field/element.ts'
+import { TyThemePaletteElement } from './theme-palette/element.ts'
+
+export { TyElement, defineTympanElement } from './base.ts'
+export { TyActionMenuElement } from './action-menu/element.ts'
+export { TyAvatarElement } from './avatar/element.ts'
+export { TyBrandWordmarkElement } from './brand-wordmark/element.ts'
+export { TyBreadcrumbsElement } from './breadcrumbs/element.ts'
+export { TyCommandPaletteElement } from './command-palette/element.ts'
+export { TyCurrencyFieldElement } from './currency-field/element.ts'
+export { TyDataTableElement } from './data-table/element.ts'
+export { TyHeadingElement } from './heading/element.ts'
+export { TyMarkdownViewElement } from './markdown-view/element.ts'
+export { TyNotificationCenterElement } from './notification-center/element.ts'
+export { TyPageHeaderElement } from './page-header/element.ts'
+export { TyProgressBarElement } from './progress-bar/element.ts'
+export { TySectionHeadingElement } from './section-heading/element.ts'
+export { TySegmentedControlElement } from './segmented-control/element.ts'
+export { TySkipLinkElement } from './skip-link/element.ts'
+export { TyTabsElement } from './tabs/element.ts'
+export { TyTagFieldElement } from './tag-field/element.ts'
+export { TyToastElement } from './toast/element.ts'
+export { TyWheelPickerElement } from './wheel-picker/element.ts'
+export { TyButtonElement } from './button/element.ts'
+export { TyCheckboxElement } from './checkbox/element.ts'
+export { TyDrawerElement } from './drawer/element.ts'
+export { TyGradientMarkElement } from './gradient-mark/element.ts'
+export { TyInlineNoticeElement } from './inline-notice/element.ts'
+export { TyLinkElement } from './link/element.ts'
+export { TyModalElement } from './modal/element.ts'
+export { TyPopoverElement } from './popover/element.ts'
+export { TyNativeSelectElement } from './native-select/element.ts'
+export { TySeparatorElement } from './separator/element.ts'
+export { TySkeletonElement } from './skeleton/element.ts'
+export { TySpinnerElement } from './spinner/element.ts'
+export { TyStatusPillElement } from './status-pill/element.ts'
+export { TySurfaceElement } from './surface/element.ts'
+export { TySwitchElement } from './switch/element.ts'
+export { TyTagElement } from './tag/element.ts'
+export { TyTextAreaElement } from './text-area/element.ts'
+export { TyTextFieldElement } from './text-field/element.ts'
+export { TyThemePaletteElement } from './theme-palette/element.ts'
+export { brandWordmarkDefinition } from './brand-wordmark/definition.ts'
+export { buttonDefinition } from './button/definition.ts'
+export { checkboxDefinition } from './checkbox/definition.ts'
+export { drawerDefinition } from './drawer/definition.ts'
+export { gradientMarkDefinition } from './gradient-mark/definition.ts'
+export { inlineNoticeDefinition } from './inline-notice/definition.ts'
+export { linkDefinition } from './link/definition.ts'
+export { modalDefinition } from './modal/definition.ts'
+export { nativeSelectDefinition } from './native-select/definition.ts'
+export { separatorDefinition } from './separator/definition.ts'
+export { skeletonDefinition } from './skeleton/definition.ts'
+export { spinnerDefinition } from './spinner/definition.ts'
+export { statusPillDefinition } from './status-pill/definition.ts'
+export { surfaceDefinition } from './surface/definition.ts'
+export { switchDefinition } from './switch/definition.ts'
+export { tagDefinition } from './tag/definition.ts'
+export { textAreaDefinition } from './text-area/definition.ts'
+export { textFieldDefinition } from './text-field/definition.ts'
+export { themePaletteDefinition } from './theme-palette/definition.ts'
+export { renderAnatomy, renderElement } from './anatomy.ts'
+export type { ElementDefinition, PropDef, EventDef, AnatomyNode, ElementNode, Example } from './definition.ts'
+export type { Appearance, Mode as ThemeMode, Density as ThemeDensity } from './theme-palette/model.ts'
+
+/** Register every Tympan custom element (idempotent; a no-op outside a browser). */
+export function defineTympanElements(): void {
+  defineTympanElement(TyActionMenuElement)
+  defineTympanElement(TyAvatarElement)
+  defineTympanElement(TyBrandWordmarkElement)
+  defineTympanElement(TyBreadcrumbsElement)
+  defineTympanElement(TyCommandPaletteElement)
+  defineTympanElement(TyCurrencyFieldElement)
+  defineTympanElement(TyDataTableElement)
+  defineTympanElement(TyHeadingElement)
+  defineTympanElement(TyMarkdownViewElement)
+  defineTympanElement(TyNotificationCenterElement)
+  defineTympanElement(TyPageHeaderElement)
+  defineTympanElement(TyProgressBarElement)
+  defineTympanElement(TySectionHeadingElement)
+  defineTympanElement(TySegmentedControlElement)
+  defineTympanElement(TySkipLinkElement)
+  defineTympanElement(TyTabsElement)
+  defineTympanElement(TyTagFieldElement)
+  defineTympanElement(TyToastElement)
+  defineTympanElement(TyWheelPickerElement)
+  defineTympanElement(TyButtonElement)
+  defineTympanElement(TyCheckboxElement)
+  defineTympanElement(TyDrawerElement)
+  defineTympanElement(TyGradientMarkElement)
+  defineTympanElement(TyInlineNoticeElement)
+  defineTympanElement(TyLinkElement)
+  defineTympanElement(TyModalElement)
+  defineTympanElement(TyPopoverElement)
+  defineTympanElement(TyNativeSelectElement)
+  defineTympanElement(TySeparatorElement)
+  defineTympanElement(TySkeletonElement)
+  defineTympanElement(TySpinnerElement)
+  defineTympanElement(TyStatusPillElement)
+  defineTympanElement(TySurfaceElement)
+  defineTympanElement(TySwitchElement)
+  defineTympanElement(TyTagElement)
+  defineTympanElement(TyTextAreaElement)
+  defineTympanElement(TyTextFieldElement)
+  defineTympanElement(TyThemePaletteElement)
+}

package/src/elements/inline-notice/definition.ts

@@ -0,0 +1,167 @@
+import type { ElementDefinition, ElementNode } from '../definition.ts'
+
+const TONES = ['danger', 'warning', 'info', 'success'] as const
+const TITLE_TAGS = ['p', 'h2', 'h3', 'h4'] as const
+
+const pascal = (s: string) => s[0]!.toUpperCase() + s.slice(1)
+
+/** The visually hidden tone word of one tone, in the title or, without a title, in the message. */
+const toneWordSpans = (withoutTitle: boolean): ElementNode[] =>
+  TONES.map((tone) => ({
+    tag: 'span',
+    class: 'ty-visually-hidden',
+    when: withoutTitle ? ['!slot:title', `tone:${tone}`] : [`tone:${tone}`],
+    children: [{ text: { prop: `toneWord${pascal(tone)}` } }],
+  }))
+
+/** A lucide glyph (ISC, THIRD_PARTY_NOTICES): every child carries a class so the element's patch pass can match it. */
+const glyph = (tag: string, attrs: Record<string, string>): ElementNode => ({
+  tag,
+  class: 'ty-notice__glyph',
+  attrs: Object.fromEntries(Object.entries(attrs).map(([name, value]) => [name, { value }])),
+})
+
+/** The tone's default icon, shown while the icon slot is empty. */
+const toneIcon = (tone: string, children: ElementNode[]): ElementNode => ({
+  tag: 'svg',
+  class: 'ty-icon',
+  when: ['!slot:icon', `tone:${tone}`],
+  attrs: {
+    viewBox: { value: '0 0 24 24' },
+    fill: { value: 'none' },
+    stroke: { value: 'currentColor' },
+    'stroke-width': { value: '2' },
+    'stroke-linecap': { value: 'round' },
+    'stroke-linejoin': { value: 'round' },
+    'aria-hidden': { value: 'true' },
+    focusable: { value: 'false' },
+  },
+  children,
+})
+
+const CIRCLE = glyph('circle', { cx: '12', cy: '12', r: '10' })
+
+/** `<ty-inline-notice>`: the InlineNotice's single source (spec: wave-1/inline-notice.md). */
+export const inlineNoticeDefinition = {
+  tag: 'ty-inline-notice',
+  name: 'TyInlineNotice',
+  kind: 'enhancing',
+  doc: 'Short message about the state of a form, section or page. Assertive tones (danger and warning unless `urgency` says otherwise) are `role="alert"`, polite ones `role="status"`; a visually hidden tone word precedes the message. Dismissal is the host\'s: the element emits `ty-dismiss` and moves focus to the next logical element.',
+  props: {
+    tone: { type: 'enum', values: TONES, default: 'info', attribute: 'tone', doc: 'Semantic tone; colours the surface and picks the default icon and tone word.' },
+    align: { type: 'enum', values: ['start', 'centre'], default: 'start', attribute: 'align', doc: '`centre` only for short single-message confirmations.' },
+    urgency: { type: 'enum', values: ['polite', 'assertive', 'none'], attribute: 'urgency', doc: 'How the notice is announced when it appears; unset: assertive for danger and warning, polite otherwise. `none` (no live role) for notices present on page load.' },
+    titleAs: { type: 'enum', values: TITLE_TAGS, default: 'p', attribute: 'title-as', doc: 'Element for the title; a plain strong paragraph unless configured.' },
+    dismissible: { type: 'boolean', attribute: 'dismissible', doc: 'Shows the dismiss button; the host removes the notice on `ty-dismiss`.' },
+    dismissLabel: { type: 'string', attribute: 'dismiss-label', default: 'Dismiss', doc: 'Accessible name of the dismiss button.' },
+    toneWordDanger: { type: 'string', attribute: 'tone-word-danger', default: 'Error: ', doc: 'Visually hidden word announced before a danger notice.' },
+    toneWordWarning: { type: 'string', attribute: 'tone-word-warning', default: 'Warning: ', doc: 'Visually hidden word announced before a warning notice.' },
+    toneWordInfo: { type: 'string', attribute: 'tone-word-info', default: 'Information: ', doc: 'Visually hidden word announced before an info notice.' },
+    toneWordSuccess: { type: 'string', attribute: 'tone-word-success', default: 'Success: ', doc: 'Visually hidden word announced before a success notice.' },
+  },
+  events: [
+    { type: 'ty-dismiss', kind: 'custom', reactProp: 'onDismiss', doc: 'The dismiss button was pressed; the host removes the notice. Focus has moved to the next logical element.' },
+  ],
+  slots: {
+    default: { doc: 'The message body.' },
+    title: { doc: 'Short heading above the message.' },
+    icon: { doc: "Overrides the tone's icon (decorative)." },
+    actions: { doc: 'Buttons or links below the message (up to two).' },
+  },
+  anatomy: {
+    tag: 'div',
+    class: 'ty-notice',
+    attrs: {
+      role: {
+        prop: 'urgency',
+        kind: 'map',
+        values: { assertive: 'alert', polite: 'status' },
+        fallback: { prop: 'tone', values: { danger: 'alert', warning: 'alert', info: 'status', success: 'status' } },
+      },
+      'data-tone': { prop: 'tone' },
+      'data-align': { prop: 'align' },
+    },
+    children: [
+      {
+        tag: 'span',
+        class: 'ty-notice__icon',
+        attrs: { 'aria-hidden': { value: 'true' } },
+        children: [
+          toneIcon('danger', [CIRCLE, glyph('line', { x1: '12', x2: '12', y1: '8', y2: '12' }), glyph('line', { x1: '12', x2: '12.01', y1: '16', y2: '16' })]),
+          toneIcon('warning', [
+            glyph('path', { d: 'm21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3' }),
+            glyph('path', { d: 'M12 9v4' }),
+            glyph('path', { d: 'M12 17h.01' }),
+          ]),
+          toneIcon('info', [CIRCLE, glyph('path', { d: 'M12 16v-4' }), glyph('path', { d: 'M12 8h.01' })]),
+          toneIcon('success', [CIRCLE, glyph('path', { d: 'm16 9-5.5 5.5L8 12' })]),
+          { slot: 'icon', when: ['slot:icon'] },
+        ],
+      },
+      {
+        tag: 'div',
+        class: 'ty-notice__body',
+        children: [
+          ...TITLE_TAGS.map(
+            (tag): ElementNode => ({
+              tag,
+              class: 'ty-notice__title',
+              when: ['slot:title', `titleAs:${tag}`],
+              children: [...toneWordSpans(false), { slot: 'title' }],
+            }),
+          ),
+          {
+            tag: 'div',
+            class: 'ty-notice__message',
+            children: [...toneWordSpans(true), { slot: 'default' }],
+          },
+          { tag: 'div', class: 'ty-notice__actions', when: ['slot:actions'], children: [{ slot: 'actions' }] },
+        ],
+      },
+      {
+        tag: 'button',
+        class: 'ty-button ty-notice__dismiss',
+        when: ['dismissible'],
+        attrs: {
+          type: { value: 'button' },
+          'data-variant': { value: 'quiet' },
+          'data-size': { value: 'compact' },
+          'data-icon-only': { value: '' },
+          'aria-label': { prop: 'dismissLabel' },
+        },
+        children: [
+          {
+            tag: 'span',
+            class: 'ty-button__icon',
+            attrs: { 'aria-hidden': { value: 'true' } },
+            children: [
+              {
+                tag: 'svg',
+                class: 'ty-icon',
+                attrs: {
+                  viewBox: { value: '0 0 24 24' },
+                  fill: { value: 'none' },
+                  stroke: { value: 'currentColor' },
+                  'stroke-width': { value: '2' },
+                  'stroke-linecap': { value: 'round' },
+                  'stroke-linejoin': { value: 'round' },
+                  'aria-hidden': { value: 'true' },
+                  focusable: { value: 'false' },
+                },
+                children: [glyph('path', { d: 'M18 6 6 18' }), glyph('path', { d: 'm6 6 12 12' })],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+  examples: [
+    { name: 'info', props: {}, slots: { default: 'Unseal the vault to run workflows that use credentials.' } },
+    { name: 'danger-title', props: { tone: 'danger' }, slots: { title: 'Vault sealed', default: 'Unseal it to run workflows that use credentials.' } },
+    { name: 'warning-heading', props: { tone: 'warning', titleAs: 'h3' }, slots: { title: 'Two sources unavailable', default: 'Results may be incomplete.' } },
+    { name: 'success-dismissible', props: { tone: 'success', dismissible: true }, slots: { default: 'Version 12 is live.' } },
+    { name: 'centred-actions', props: { align: 'centre', urgency: 'none' }, slots: { default: 'Nothing to review.', actions: 'Help' } },
+    { name: 'custom-icon', props: {}, slots: { icon: '★', default: 'Starred runs appear first.' } },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/inline-notice/element.ts

@@ -0,0 +1,36 @@
+import { TyElement } from '../base.ts'
+import { inlineNoticeDefinition } from './definition.ts'
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+/**
+ * `<ty-inline-notice>`. The notice is painted by the stylesheet from
+ * `tone`; the element adds dismissal: a press of the dismiss button emits
+ * `ty-dismiss` (the host removes the notice) and moves focus to the next
+ * logical element, not the document body.
+ */
+export class TyInlineNoticeElement extends TyElement {
+  static override definition = inlineNoticeDefinition
+
+  #dismiss = (event: Event) => {
+    const button = (event.target as Element | null)?.closest?.('.ty-notice__dismiss')
+    if (!button || !this.contains(button)) return
+    // Focus moves to the next logical element, not the document body.
+    const all = Array.from(document.querySelectorAll<HTMLElement>(FOCUSABLE))
+    const next =
+      all.find((el) => !this.contains(el) && this.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING) ??
+      [...all].reverse().find((el) => !this.contains(el)) ??
+      null
+    this.emit('ty-dismiss')
+    if (next) setTimeout(() => next.isConnected && next.focus(), 0)
+  }
+
+  protected override connected(): void {
+    this.addEventListener('click', this.#dismiss)
+  }
+
+  protected override disconnected(): void {
+    this.removeEventListener('click', this.#dismiss)
+  }
+}

package/src/elements/link/definition.ts

@@ -0,0 +1,70 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/** `<ty-link>`: the Link's single source (spec: wave-1/link.md). */
+export const linkDefinition = {
+  tag: 'ty-link',
+  name: 'TyLink',
+  kind: 'enhancing',
+  doc: 'Moves to another location. A native <a> inside, so focus, keyboard activation and opening in a new context are the platform\'s; an external destination opens in a new context with a safe rel, an icon and a screen-reader hint.',
+  props: {
+    href: { type: 'string', attribute: 'href', doc: 'Destination. The element is a navigation link; an inline action without one is a plain <button class="ty-link" data-action="">' },
+    emphasis: { type: 'enum', values: ['underlined', 'subtle'], default: 'underlined', attribute: 'emphasis', doc: '`subtle` hides the underline at rest (only where the context makes the link obvious).' },
+    external: { type: 'boolean', attribute: 'external', doc: 'Opens in a new context with `rel="noopener noreferrer"`, an icon and a screen-reader hint. Inferred on upgrade from absolute URLs to another origin; hosts render it explicitly.' },
+    current: { type: 'boolean', attribute: 'current', doc: 'Marks the link as the current page (`aria-current="page"`).' },
+    standalone: { type: 'boolean', attribute: 'standalone', doc: 'Standalone links (lists, footers) get a 44 px tall hit area; inline prose links do not.' },
+    newTabLabel: { type: 'string', attribute: 'new-tab-label', default: '(opens in a new tab)', doc: 'Screen-reader hint appended to an external link\'s name on upgrade; translate through this attribute.' },
+    accessibleLabel: { type: 'string', attribute: 'accessible-label', doc: 'Accessible name when the visible text is not enough (`aria-label`).' },
+    describedBy: { type: 'string', attribute: 'described-by', doc: 'Id of an element describing the link (`aria-describedby`).' },
+  },
+  events: [{ type: 'click', kind: 'native', reactProp: 'onClick', doc: 'The native click of the anchor.' }],
+  slots: {
+    default: { doc: 'The link text.' },
+  },
+  anatomy: {
+    tag: 'a',
+    class: 'ty-link',
+    attrs: {
+      href: { prop: 'href' },
+      target: { value: '_blank', when: ['external'] },
+      rel: { value: 'noopener noreferrer', when: ['external'] },
+      'aria-current': { value: 'page', when: ['current'] },
+      'aria-label': { prop: 'accessibleLabel' },
+      'aria-describedby': { prop: 'describedBy' },
+      'data-emphasis': { prop: 'emphasis' },
+      'data-standalone': { prop: 'standalone', kind: 'flag' },
+    },
+    children: [
+      { slot: 'default' },
+      {
+        tag: 'svg',
+        class: 'ty-icon ty-mirror-rtl ty-link__external',
+        when: ['external'],
+        attrs: {
+          'aria-hidden': { value: 'true' },
+          focusable: { value: 'false' },
+          width: { value: '24' },
+          height: { value: '24' },
+          viewBox: { value: '0 0 24 24' },
+          fill: { value: 'none' },
+          stroke: { value: 'currentColor' },
+          'stroke-width': { value: '2' },
+          'stroke-linecap': { value: 'round' },
+          'stroke-linejoin': { value: 'round' },
+        },
+        children: [
+          { tag: 'path', attrs: { d: { value: 'M15 3h6v6' } } },
+          { tag: 'path', attrs: { d: { value: 'M10 14 21 3' } } },
+          { tag: 'path', attrs: { d: { value: 'M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6' } } },
+        ],
+      },
+      { tag: 'span', class: 'ty-visually-hidden ty-link__hint', when: ['external'] },
+    ],
+  },
+  examples: [
+    { name: 'inline', props: { href: '/runs' }, slots: { default: 'Runs' } },
+    { name: 'subtle-standalone', props: { href: '/runs/01HX', emphasis: 'subtle', standalone: true }, slots: { default: 'Details' } },
+    { name: 'external', props: { href: 'https://example.org/report', external: true }, slots: { default: 'Report' } },
+    { name: 'current', props: { href: '/overview', current: true }, slots: { default: 'Overview' } },
+    { name: 'translated-hint', props: { href: 'https://example.org/relatorio', external: true, newTabLabel: '(abre em nova aba)', describedBy: 'report-hint' }, slots: { default: 'Relatório' } },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/link/element.ts

@@ -0,0 +1,40 @@
+import { TyElement } from '../base.ts'
+import type { Props } from '../definition.ts'
+import { linkDefinition } from './definition.ts'
+
+/** True for absolute http(s) URLs pointing to another origin (the React Link's `isExternalHref`). */
+function isExternalHref(href: string): boolean {
+  if (!/^https?:\/\//i.test(href)) return false
+  try {
+    const origin = typeof window !== 'undefined' ? window.location.origin : ''
+    return new URL(href).origin !== origin
+  } catch {
+    return false
+  }
+}
+
+/**
+ * `<ty-link>`. The native anchor inside does focus, keyboard activation and
+ * opening in a new context; the element keeps the bound attributes in step,
+ * infers `external` from absolute URLs to another origin (a host renders
+ * `external` itself when it knows) and fills the external link's
+ * screen-reader hint from `new-tab-label`.
+ */
+export class TyLinkElement extends TyElement {
+  static override definition = linkDefinition
+
+  override get props(): Props {
+    const props = super.props
+    if (!this.hasAttribute('external') && typeof props.href === 'string') props.external = isExternalHref(props.href)
+    return props
+  }
+
+  override sync(): void {
+    super.sync()
+    const hint = this.querySelector('.ty-link__hint')
+    if (!hint) return
+    const label = this.getAttribute('new-tab-label') ?? String(linkDefinition.props.newTabLabel.default)
+    const text = ` ${label}`
+    if (hint.textContent !== text) hint.textContent = text
+  }
+}

package/src/elements/markdown-view/definition.ts

@@ -0,0 +1,35 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/**
+ * `<ty-markdown-view>`: the MarkdownView's single source (spec:
+ * wave-2/markdown-view.md).
+ *
+ * Self-rendering: the whole subtree is data-driven — parsed from the `text`
+ * Markdown source on upgrade and on every attribute change — so the
+ * declarative anatomy cannot express it (no parsing, no repetition), and the
+ * wrappers render an empty host. The element shares the parser with the
+ * React MarkdownView (`components/markdown-view/parse.ts`): one grammar, one
+ * data tree, and no HTML string anywhere — the tree is built with
+ * `createElement` and text nodes only, so markup in the source can only ever
+ * reach the page as text. Links exist solely for absolute http(s) URLs (any
+ * other scheme renders as literal text), open in a new tab with
+ * `rel="noopener noreferrer"`, and carry the external icon and the hidden
+ * new-tab hint, as `<ty-link>` renders them. Examples stay empty: parity
+ * rendering does not apply to a self-rendering element.
+ */
+export const markdownViewDefinition = {
+  tag: 'ty-markdown-view',
+  name: 'TyMarkdownView',
+  kind: 'self-rendering',
+  doc: 'Safely renders a small, product-relevant subset of Markdown written by people or produced by models, without ever interpreting raw HTML: paragraphs, lists, headings (real `h2`–`h6`, offset by `headingBase`), fenced code blocks, and inline code, strong, emphasis and http(s) links; everything else is literal text. Static — links are the only focusable content, plus a code block that overflows (a labelled scroll region).',
+  props: {
+    text: { type: 'string', attribute: 'text', doc: 'Markdown source (the supported subset; anything else renders as literal text). Empty renders nothing.' },
+    headingBase: { type: 'number', default: 3, attribute: 'heading-base', doc: 'Level used for a Markdown level-1 heading (2 to 6); deeper levels follow, capped at 6.' },
+    density: { type: 'enum', values: ['regular', 'compact'], default: 'regular', attribute: 'density', doc: 'Spacing between blocks.' },
+    codeBlockLabel: { type: 'string', default: 'Code block', attribute: 'code-block-label', doc: 'Accessible name of a code block that overflows (a scroll region) when it has no language tag; translate through this attribute.' },
+    codeBlockLanguageLabel: { type: 'string', default: 'Code block, {language}', attribute: 'code-block-language-label', doc: 'Accessible name of an overflowing code block with a language tag; `{language}` is replaced by the tag.' },
+    newTabLabel: { type: 'string', default: '(opens in a new tab)', attribute: 'new-tab-label', doc: 'Screen-reader hint appended to every link (all links open in a new tab); translate through this attribute.' },
+  },
+  events: [],
+  examples: [],
+} as const satisfies ElementDefinition