@aiquants/markdown 13.3.0 → 13.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -11,7 +11,7 @@ Advanced Markdown renderer for React with support for various extensions and cus
11
11
  - **Dynamic Configuration**: Easily enable or disable custom extensions dynamically using parse options.
12
12
  - **Syntax Highlighting**: Code blocks with Shiki syntax highlighting, every token at a 7:1 contrast ratio or better in the GitHub, Zenn and None styles, light and dark (see [Code blocks](#code-blocks)).
13
13
  - **Text That Grows and Untrusted Text**: a text that grows renders block by block as the converter cuts it, keeping the reader's selection and a code block's place (see [Text that grows](#text-that-grows)), and a model's answer renders under its own allow list, its images and links handed to the host's components (see [Untrusted text](#untrusted-text)).
14
- - **Reader's Display Options**: one toolbar popover holds the document style, a reading width and colour pairs that keep every text at 7:1 or better in every built-in style (see [Reader's display options](#readers-display-options)).
14
+ - **Reader's Display Options**: one toolbar popover holds the document style, a reading width, colour pairs that keep every text at 7:1 or better in every built-in style, and the document fonts a host offers (see [Reader's display options](#readers-display-options)).
15
15
  - **TypeScript**: Full TypeScript support with comprehensive type definitions.
16
16
 
17
17
  ## Installation
@@ -593,19 +593,26 @@ With the `GitHub` and `Zenn` styles of `DEFAULT_MARKDOWN_STYLES`, a wide table o
593
593
 
594
594
  ### Reader's display options
595
595
 
596
- The toolbar's display button opens one popover with up to three sections. The viewer keeps none of the values: a host passes each one, stores what the reader chooses and passes it back. The button shows while a document shows and any section does.
596
+ The toolbar's display button opens one popover with up to four sections. The viewer keeps none of the values: a host passes each one, stores what the reader chooses and passes it back. The button shows while a document shows and any section does.
597
597
 
598
598
  | Section | Value | Reader's choice | Shown when |
599
599
  | --- | --- | --- | --- |
600
600
  | Style | `style`, from `availableStyles` | `onStyleChange` | `showStyle` (on by default) |
601
601
  | Width | `measure` (`ContentMeasure`: `fill`, `reading`) | `onMeasureChange` | `onMeasureChange` is given and `showMeasure` is on (the default) |
602
602
  | Colours | `contentColors` (`ContentColors`: `default`, `sepia`, `dark-low-glare`, `high-contrast`) | `onContentColorsChange` | `onContentColorsChange` is given and `showContentColors` is on (the default) |
603
+ | Font | `documentFont`, a key of `documentFontOptions`, or none | `onDocumentFontChange` | `documentFontOptions` lists a font, `onDocumentFontChange` is given and `showDocumentFont` is on (the default) |
603
604
 
604
- Each section lists its options as `aria-pressed` buttons of 44 px in a labelled group, and a choice closes an unpinned popover. A change of style, width or alignment, a host's own included, does not parse the document again and keeps the reader's place: the block nearest the scroller's top stays where it was (a host's `width` or `maxWidth`, like a resized pane, keeps none). The place is read just before the commit that brings the new value, however late the host passes it back, and kept for two frames after that commit, so nothing is held while a host takes its time.
605
+ Each section lists its options as `aria-pressed` buttons of 44 px in a labelled group, and a choice closes an unpinned popover. A change of style, width or alignment, a host's own included, does not parse the document again; a change of the document's font renders it again, as a change of `theme` does.
606
+ A change of any of the four keeps the reader's place: the block nearest the scroller's top stays where it was (a host's `width` or `maxWidth`, like a resized pane, keeps none, and nor does a font change in plain text, which the font does not reach). The place is read just before the commit that brings the new value, however late the host passes it back, and kept for two frames after that commit, so nothing is held while a host takes its time.
605
607
  The blocks are the children of `[data-aqmd-document]`, the renderer's root, and what lists, quotations, sections and open `details` hold, passing over anything not visible (plain text is one block, its `pre`); within any other long block the place is its top, so a reader deep inside one moves as the text above reflows. A reader's scroll, a click (where the jumps of the document and its table of contents start) or another document ends those frames, and a reader at the top of the document stays at the top.
606
608
  A jump with no click (a script's `location.hash`, `history.back()`) that opens a closed section within those frames reads as a reflow. The place reads the block axis of the viewer's own scroller, so vertical writing and a page whose window scrolls keep none.
607
609
  A `measure` or a `contentColors` that is not one of its values throws a `TypeError`; normalize a value read from outside with `toContentMeasure` and `toContentColors` (see [Settings without React](#settings-without-react)).
608
610
 
611
+ The font section names a font by its key and applies none. A host lists the fonts a reader may choose in `documentFontOptions` (`DocumentFontOption`: a `key` and a `label`, each a string that is not blank and is unique among the options; an object with more keys, such as `@aiquants/fonts`' `FontOption`, is taken as it is), keeps the key the reader chooses and passes it back as `documentFont`,
612
+ and resolves that key to the `documentFontFamily` it passes, the one font the viewer applies: the renderer sets it on the document root (`[data-aqmd-document]`) as `DOCUMENT_FONT_FAMILY_PROPERTY` (`--aqmd-document-font-family`), which the root's `font-family` reads, and, absent or blank, the document keeps the font of its display style. A host sanitizes any family a person typed before passing it.
613
+ The section opens with its default entry (`fontDefault`), which reports `undefined`, so a host drops the stored key and goes back to its own default font or none; a label is written in the page's language and read in it, as the style names are.
614
+ A `documentFontOptions` that is not an array of such objects throws a `TypeError`, and a blank or repeated key or label a `RangeError`, whether the section shows or not; a `documentFont` that is not a string throws a `TypeError`, and one that is not a listed key a `RangeError`, so a host passes a stored key only while it lists it.
615
+
609
616
  `contentColors` picks one of three colour pairs (WCAG 1.4.8); `default` keeps the document style's own colours and writes nothing:
610
617
 
611
618
  | Pair | Scheme | Ground | Text | Lowest text contrast |
@@ -1499,9 +1506,10 @@ The display popover's keys of `MarkdownViewerLabels`, all optional and all marke
1499
1506
  | `styleTitle` | The popover's heading | Display |
1500
1507
  | `selectStyleAria` | The display button | Display options |
1501
1508
  | `pinStyleAria`, `unpinStyleAria` | The pin button | Pin display options / Unpin display options |
1502
- | `styleSectionTitle`, `measureTitle`, `colorsTitle` | The sections' headings | Style / Width / Colors |
1509
+ | `styleSectionTitle`, `measureTitle`, `colorsTitle`, `fontTitle` | The sections' headings | Style / Width / Colors / Font |
1503
1510
  | `measureFill`, `measureReading` | The width options | Full width / Reading width |
1504
1511
  | `colorsDefault`, `colorsSepia`, `colorsDarkLowGlare`, `colorsHighContrast` | The colour options | Document colors / Sepia / Dark, low glare / High contrast |
1512
+ | `fontDefault` | The font section's first entry, which chooses none of the listed fonts | Default font |
1505
1513
 
1506
1514
  `missingImage` is the notice of an image that cannot be found (`missingImageLabel` on `MarkdownRenderer`; "Image not found", marked `lang="en"`).
1507
1515
 
@@ -1679,8 +1687,8 @@ converter built to WebAssembly, on hundreds of generated layouts and bodies.
1679
1687
  import { CODE_META_ATTRIBUTE, parseSpreadsheetOptions, planFencedBodyEdit } from "@aiquants/markdown/code-blocks"
1680
1688
  ```
1681
1689
 
1682
- `@aiquants/markdown/viewer-settings` exports the built-in document styles, the alignments, the measures and the colour pairs without loading React, for modules that also run on the server (configuration, validation): `DEFAULT_MARKDOWN_STYLES`, `DEFAULT_MARKDOWN_STYLE` (`"Zenn"`, the name of the built-in style a host starts a reader on when neither the host nor the reader chose one;
1683
- the viewer itself always shows the `style` it is given), `MarkdownStyleOption`, `ContentAlign`, `CONTENT_ALIGNS`, `DEFAULT_CONTENT_ALIGN`, `toContentAlign`, `ContentMeasure`, `CONTENT_MEASURES`, `DEFAULT_CONTENT_MEASURE` (`"fill"`), `toContentMeasure`, `ContentColors`, `CONTENT_COLORS`, `DEFAULT_CONTENT_COLORS` (`"default"`) and `toContentColors`. Each `to…` turns a value read from outside (a URL query, a stored preference) into a valid one, the default or a fallback you pass when it is not. `@aiquants/markdown` re-exports the same values.
1690
+ `@aiquants/markdown/viewer-settings` exports the built-in document styles, the document font's property and option, the alignments, the measures and the colour pairs without loading React, for modules that also run on the server (configuration, validation): `DEFAULT_MARKDOWN_STYLES`, `DEFAULT_MARKDOWN_STYLE` (`"Zenn"`, the name of the built-in style a host starts a reader on when neither the host nor the reader chose one;
1691
+ the viewer itself always shows the `style` it is given), `MarkdownStyleOption`, `DOCUMENT_FONT_FAMILY_PROPERTY`, `DocumentFontOption`, `ContentAlign`, `CONTENT_ALIGNS`, `DEFAULT_CONTENT_ALIGN`, `toContentAlign`, `ContentMeasure`, `CONTENT_MEASURES`, `DEFAULT_CONTENT_MEASURE` (`"fill"`), `toContentMeasure`, `ContentColors`, `CONTENT_COLORS`, `DEFAULT_CONTENT_COLORS` (`"default"`) and `toContentColors`. Each `to…` turns a value read from outside (a URL query, a stored preference) into a valid one, the default or a fallback you pass when it is not. `@aiquants/markdown` re-exports the same values.
1684
1692
 
1685
1693
  ```ts
1686
1694
  import { DEFAULT_MARKDOWN_STYLE, DEFAULT_MARKDOWN_STYLES, toContentAlign, toContentColors, toContentMeasure } from "@aiquants/markdown/viewer-settings"
@@ -44,6 +44,7 @@ type RendererProps = {
44
44
  iFrameAllowedDomains?: readonly string[];
45
45
  embeds?: MarkdownEmbeds;
46
46
  embedLabels?: MarkdownEmbedLabels;
47
+ documentFontFamily?: string;
47
48
  mermaidInteraction?: MermaidInteractionMode;
48
49
  mermaidModifier?: PanZoomModifier;
49
50
  mermaidLabels?: MermaidDiagramLabels;
@@ -79,5 +80,5 @@ type AllowlistProps = {
79
80
  readonly iFrameAllowedDomains?: undefined;
80
81
  };
81
82
  type Props = RendererProps & AllowlistProps;
82
- export declare const MarkdownRenderer: ({ htmlContent, blockOffsets, blockKeyEpoch, streaming, truncated, theme, topHeadingLevel, iFrameAllowedDomains, embeds, embedLabels, mermaidInteraction, mermaidModifier, mermaidLabels, mermaidDrawing, mermaidExporting, maxMermaidDiagrams, codeBlockLabels, displayMathLabels, spreadsheetEditor, spreadsheetLocale, spreadsheetLabels, spreadsheetTapScrollCircle, spreadsheetScrollBarControls, linkComponent: LinkComponent, missingImageLabel, blockFailedLabel, labelsLang, imageSource, svgImageLabels, onMathDiagnostics, allowlist, imageComponent: ImageComponent, idPrefix, }: Props) => import("react").JSX.Element;
83
+ export declare const MarkdownRenderer: ({ htmlContent, blockOffsets, blockKeyEpoch, streaming, truncated, theme, topHeadingLevel, iFrameAllowedDomains, embeds, embedLabels, documentFontFamily, mermaidInteraction, mermaidModifier, mermaidLabels, mermaidDrawing, mermaidExporting, maxMermaidDiagrams, codeBlockLabels, displayMathLabels, spreadsheetEditor, spreadsheetLocale, spreadsheetLabels, spreadsheetTapScrollCircle, spreadsheetScrollBarControls, linkComponent: LinkComponent, missingImageLabel, blockFailedLabel, labelsLang, imageSource, svgImageLabels, onMathDiagnostics, allowlist, imageComponent: ImageComponent, idPrefix, }: Props) => import("react").JSX.Element;
83
84
  export {};
@@ -1,7 +1,7 @@
1
1
  import { ScrollBarTapCircleOptions, SpreadsheetScrollBarControls } from "@aiquants/spreadsheet";
2
2
  import { MouseEvent, ReactNode } from "react";
3
3
  import { MarkdownEmbeds } from "../embeds/linkCards.ts";
4
- import { ContentAlign, ContentColors, ContentMeasure, MarkdownStyleOption } from "../viewer-settings.ts";
4
+ import { ContentAlign, ContentColors, ContentMeasure, DocumentFontOption, MarkdownStyleOption } from "../viewer-settings.ts";
5
5
  import { MarkdownScrollBarRenderer } from "./HostedScrollArea.tsx";
6
6
  import { MarkdownLinkComponent } from "./MarkdownRenderer.tsx";
7
7
  import { PanZoomModifier } from "./MermaidDiagram.tsx";
@@ -72,6 +72,10 @@ export interface MarkdownViewerProps {
72
72
  contentColors?: ContentColors;
73
73
  onContentColorsChange?: (colors: ContentColors) => void;
74
74
  showContentColors?: boolean;
75
+ documentFontOptions?: readonly DocumentFontOption[];
76
+ documentFont?: string;
77
+ onDocumentFontChange?: (key: string | undefined) => void;
78
+ showDocumentFont?: boolean;
75
79
  width?: string;
76
80
  maxWidth?: string;
77
81
  padding?: number;
@@ -87,6 +91,7 @@ export interface MarkdownViewerProps {
87
91
  spreadsheetTapScrollCircle?: ScrollBarTapCircleOptions;
88
92
  spreadsheetScrollBarControls?: SpreadsheetScrollBarControls;
89
93
  mermaidModifier?: PanZoomModifier;
94
+ documentFontFamily?: string;
90
95
  imageSource?: MarkdownImageSourceReader;
91
96
  emptyMessage?: string;
92
97
  toolbar?: MarkdownToolbarState;
@@ -94,4 +99,4 @@ export interface MarkdownViewerProps {
94
99
  scrollBarGutter?: number | string;
95
100
  scrollBarInlineSize?: number | string;
96
101
  }
97
- export declare function MarkdownViewer({ parseResult, content, error, isLoading, labels, labelsLang, theme, style, onStyleChange, availableStyles, align, onAlignChange, showToc, showStyle, showAlign, contentLang, measure, onMeasureChange, showMeasure, contentColors, onContentColorsChange, showContentColors, width, maxWidth, padding, iFrameAllowedDomains, embeds, fetch: hostFetch, emptyMessage, toolbar: toolbarProp, linkComponent, onHeadingSelect, headingHref, onMathDiagnostics, spreadsheetEditor, spreadsheetLocale, spreadsheetTapScrollCircle, spreadsheetScrollBarControls, mermaidModifier, imageSource, renderScrollBar, scrollBarGutter, scrollBarInlineSize, }: MarkdownViewerProps): import("react").JSX.Element;
102
+ export declare function MarkdownViewer({ parseResult, content, error, isLoading, labels, labelsLang, theme, style, onStyleChange, availableStyles, align, onAlignChange, showToc, showStyle, showAlign, contentLang, measure, onMeasureChange, showMeasure, contentColors, onContentColorsChange, showContentColors, documentFontOptions, documentFont, onDocumentFontChange, showDocumentFont, width, maxWidth, padding, iFrameAllowedDomains, embeds, fetch: hostFetch, emptyMessage, toolbar: toolbarProp, linkComponent, onHeadingSelect, headingHref, onMathDiagnostics, spreadsheetEditor, spreadsheetLocale, spreadsheetTapScrollCircle, spreadsheetScrollBarControls, mermaidModifier, documentFontFamily, imageSource, renderScrollBar, scrollBarGutter, scrollBarInlineSize, }: MarkdownViewerProps): import("react").JSX.Element;
@@ -7,6 +7,7 @@ export type ReadingPlaceKeeperProps = {
7
7
  readonly style: string;
8
8
  readonly measure: ContentMeasure;
9
9
  readonly align: ContentAlign;
10
+ readonly documentFontFamily: string | undefined;
10
11
  };
11
12
  type ReadingBlock = {
12
13
  readonly block: Element;
@@ -0,0 +1 @@
1
+ export declare const appliedDocumentFontFamily: (documentFontFamily: string | undefined) => string | undefined;
@@ -41,6 +41,8 @@ export interface MarkdownViewerLabels extends MermaidViewerLabels, SpreadsheetVi
41
41
  colorsSepia?: string;
42
42
  colorsDarkLowGlare?: string;
43
43
  colorsHighContrast?: string;
44
+ fontTitle?: string;
45
+ fontDefault?: string;
44
46
  openTocAria?: string;
45
47
  tocTitle?: string;
46
48
  pinTocAria?: string;