@cosense-toolbox/parser 0.1.0-beta.1 → 0.1.0-beta.3

package/dist/html.d.mts

@@ -0,0 +1,274 @@
+import { A as TableCell, C as NodeOfType, D as ProjectLink, M as TextNode, N as TitleBlock, b as InternalLink, c as CodeLine, d as FormulaNode, f as Hashtag, h as InlineCode, j as TableRow, k as TableBlock, l as Decoration, m as ImageNode, p as IconNode, r as AnyNodeType, s as CodeBlock, t as AnyNode, u as ExternalLink, w as Page, x as LineBlock } from "./types-gWMrsXPX.mjs";
+import "./index-CrIlOW1k.mjs";
+import { Element, ElementContent, Root, Text } from "hast";
+//#region src/html/to-hast.d.ts
+/** `href` に入れて安全な URL だけを返す。script が動くスキームなら null。 */
+declare const safeHref: (url: string) => string | null;
+/** `src` に入れて安全な URL だけを返す。script が動くスキームなら null。 */
+declare const safeSrc: (url: string) => string | null;
+/** プロジェクト内のページを指すノード。Cosense Web ではアイコンもユーザーのページへのリンクになる。 */
+type PageRefNode = InternalLink | ProjectLink | Hashtag | IconNode;
+/**
+ * 出力する要素に付ける class 名。指定したキーだけが既定を上書きする。
+ * 空文字にすると class 属性自体を出さない。
+ */
+interface HtmlClassNames {
+  readonly page?: string;
+  readonly title?: string;
+  readonly line?: string;
+  /** 引用行の `<blockquote>` */
+  readonly quote?: string;
+  /** 等幅行の `<code>` */
+  readonly monospace?: string;
+  /** コードブロックに属する行 (ヘッダ行と本体行の両方) */
+  readonly codeBlock?: string;
+  /** ヘッダ行の `<code>` */
+  readonly codeStart?: string;
+  /** ヘッダ行に出るファイル名 */
+  readonly codeFilename?: string;
+  /** 本体行の `<code>` */
+  readonly codeBody?: string;
+  /** ハイライタを通した本体に追加で付く class */
+  readonly codeHighlight?: string;
+  readonly table?: string;
+  /** `showPads` のときだけ出る、インデントぶんの余白と中点をまとめる要素 */
+  readonly indentMark?: string;
+  /** インデント 1 段ぶんの余白 */
+  readonly pad?: string;
+  /** インデントの右端に置く中点 */
+  readonly dot?: string;
+  readonly internalLink?: string;
+  readonly externalLink?: string;
+  readonly projectLink?: string;
+  readonly hashtag?: string;
+  readonly inlineCode?: string;
+  readonly image?: string;
+  readonly icon?: string;
+  readonly formula?: string;
+  readonly decoration?: string;
+}
+/** 既定の class 名。接頭辞を持たないため、利用側の CSS と名前がぶつかりうる。 */
+declare const defaultClassNames: HtmlClassNames;
+/**
+ * HTML の文字列をそのまま入れるノード。`toHtml` はそのまま埋め込む (hast-util-to-html の raw ノード)。
+ * hast の型には無いので、ここで持つ。hast-util-to-html の型拡張に頼ると、
+ * `@types/hast` の版が分かれたときに型が合わなくなるため。
+ */
+interface RawNode {
+  readonly type: "raw";
+  readonly value: string;
+}
+/** ハンドラやハイライタが返せるノード。hast の要素の中身か、raw ノード。 */
+type HastContent = ElementContent | RawNode;
+/**
+ * コードブロックの中身を色付けする。
+ *
+ * `language` はファイル名から推測した名前 (`codeLanguageOf`)。
+ * null を返すと色付けせず、1 行ずつのまま出す。知らない言語のときに使う。
+ *
+ * shiki の `codeToHast` のように `pre > code` を返したときは、code の中身を使い、
+ * pre の class と style (テーマの背景色や文字色) をコードブロックの code に移す。
+ * 行の要素 (`div.line`) の中に置くので、pre そのものは出さない。
+ */
+type HastHighlighter = (code: string, language: string) => Root | HastContent[] | null;
+/**
+ * 既定のハンドラの振る舞いを変えるオプション。
+ *
+ * `pageUrl` / `iconImageUrl` / `highlight` は、**記法に書かれていないので AST から導けない**
+ * 情報を外から渡すためのもの。残りは出力の見た目を調整する。
+ */
+interface HastRenderOptions {
+  /**
+   * ページを指す記法 (`[title]` / `[/proj/page]` / `#tag` / `[user.icon]`) の遷移先。
+   * アイコンについてはリンク先だけを決め、画像は `iconImageUrl` が決める。
+   *
+   * `title` は記法に書かれたタイトルそのままで、`[title]` なら `title`、
+   * `[/proj/page]` なら `/proj/page`、`#tag` なら `tag`、`[user.icon]` なら `user`。
+   *
+   * @defaultValue `/{title}`。区切りを含むタイトルは区切りを残して各段を encode する
+   */
+  readonly pageUrl?: (title: string, node: PageRefNode) => string;
+  /**
+   * アイコンの画像 URL。null なら `<img>` を出さず、ユーザー名のテキストになる。
+   * リンク先のほうは `pageUrl` が決める。
+   *
+   * @defaultValue 常に null。Cosense Web の画像 URL (`/api/pages/{project}/{user}/icon`) は
+   * プロジェクト名を要するが、記法には書かれていないため
+   */
+  readonly iconImageUrl?: (node: IconNode) => string | null;
+  /**
+   * コードブロックの中身の色付け。渡すと、本体は 1 行 1 要素ではなく 1 つの要素にまとまる。
+   * ハイライタの出力が複数行にまたがる要素を含みうるため。
+   */
+  readonly highlight?: HastHighlighter;
+  /** 出力する要素に付ける class 名。 */
+  readonly classNames?: HtmlClassNames;
+  /**
+   * インデントを Cosense Web と同じ要素として書き出す。深さ 1 段につき `pad` が 1 つ並び、
+   * その右端に中点が付く。
+   *
+   * @defaultValue false。深さは行の `data-indent` 属性だけで表す
+   */
+  readonly showPads?: boolean;
+}
+/** オプションの既定値を埋めたもの。ハンドラは `ctx.options` でこれを読む。 */
+interface ResolvedHastOptions {
+  readonly pageUrl: (title: string, node: PageRefNode) => string;
+  readonly iconImageUrl: (node: IconNode) => string | null;
+  readonly highlight: HastHighlighter | null;
+  /** 既定の class 名に、指定したものを重ねたもの */
+  readonly classNames: HtmlClassNames;
+  readonly showPads: boolean;
+}
+/** ハンドラの中から再帰的に変換するための入口と、オプション。 */
+interface HastContext {
+  /**
+   * 今描いているノードの祖先。根 (`toHast` に渡したノード) から親までの順に並ぶ。
+   * 「テーブルのセルの中の text だけ」のように、どこにあるかで出力を変えるときに使う。
+   */
+  readonly ancestors: readonly AnyNode[];
+  /** ノード 1 つを変換する (そのノード型のハンドラを通る) */
+  readonly node: (node: AnyNode) => ElementContent[];
+  /** 子ノードをすべて変換し、平らな配列で返す */
+  readonly children: (node: AnyNode) => ElementContent[];
+  readonly options: ResolvedHastOptions;
+}
+type HastHandler<K extends AnyNodeType> = (node: NodeOfType<K>, ctx: HastContext) => HastContent | HastContent[];
+/**
+ * ノード型 → ハンドラの対応。`AnyNodeMap` から型を導出しているので、
+ * ノード型が増えたら (declaration merging を含む) ここも自動で新しいキーを受け入れる。
+ */
+type HastHandlers = { readonly [K in AnyNodeType]?: HastHandler<K>; };
+/**
+ * 描画の拡張の 1 段。そのノード型の、ここまでの出力 (既定のハンドラか `handlers`、
+ * 先に並べた拡張を通したもの) を受け取り、新しい出力を返す。
+ * vite の `transform` と同じく、前の段の出力をもらって加工するだけの関数にしている。
+ * 出力を一から作るのは `handlers` の役目なので、拡張では作り直さない。
+ */
+type RenderTransform<K extends AnyNodeType> = (output: ElementContent[], node: NodeOfType<K>, ctx: HastContext) => HastContent | HastContent[];
+/**
+ * 描画の拡張。ノード型ごとに `RenderTransform` を持つ。
+ * 行番号 (`codeLineNumbers`) のように、既定の出力に手を加えるものをまとめて配るための形。
+ */
+type RenderExtension = { readonly [K in AnyNodeType]?: RenderTransform<K>; };
+interface HastOptions extends HastRenderOptions {
+  /**
+   * ノード型ごとの出力の置き換え。指定した型だけが差し替わる。
+   * 出力を一から作りたいときに使う。できた出力に手を加えるだけなら `extensions` を使う。
+   */
+  readonly handlers?: HastHandlers;
+  /**
+   * 描画の拡張。`handlers` の後に、並べた順に出力を加工する。
+   * 前の拡張の出力が次の拡張に渡るので、同じノード型に触る拡張どうしも重ねられる。
+   */
+  readonly extensions?: readonly RenderExtension[];
+}
+/**
+ * コードブロックのファイル名から言語名を推測する。拡張子があればそれ、無ければファイル名全体。
+ * Cosense では `code:python` のように言語名だけを書くこともできるため。
+ * `highlight` に渡る言語名はこれで決めている。
+ */
+declare const codeLanguageOf: (filename: string) => string;
+/**
+ * `pageUrl` の既定の実装。`/proj/page` のように区切りを含むタイトルは、
+ * 区切りを残したまま各段を encode する。
+ */
+declare const defaultPageUrl: (title: string) => string;
+/**
+ * 既定のハンドラ一式。`toHast` はこれに `handlers` を重ねてから走らせる。
+ *
+ * cosense-x のように描画を組み立て直すライブラリが、既定の部品 (行の包み方など) を使い回すためのもの。
+ * 既定の出力に手を加えるだけなら、これを呼ばずに `extensions` を使う。
+ * オプションは `ctx.options` から読むので、呼ぶ側が渡し直さなくてよい。
+ */
+declare const defaultHastHandlers: {
+  page: (node: Page, ctx: HastContext) => Element[];
+  title: (node: TitleBlock, ctx: HastContext) => Element[];
+  line: (node: LineBlock, ctx: HastContext) => Element[];
+  codeBlock: (node: CodeBlock, ctx: HastContext) => ElementContent[];
+  codeLine: (node: CodeLine) => Text[];
+  table: (node: TableBlock, ctx: HastContext) => Element[];
+  tableRow: (node: TableRow, ctx: HastContext) => Element[];
+  tableCell: (node: TableCell, ctx: HastContext) => Element[];
+  text: (node: TextNode) => Text[];
+  internalLink: (node: InternalLink, ctx: HastContext) => Element[];
+  externalLink: (node: ExternalLink, ctx: HastContext) => Element[];
+  projectLink: (node: ProjectLink, ctx: HastContext) => Element[];
+  hashtag: (node: Hashtag, ctx: HastContext) => Element[];
+  inlineCode: (node: InlineCode, ctx: HastContext) => Element[];
+  image: (node: ImageNode, ctx: HastContext) => Element[];
+  icon: (node: IconNode, ctx: HastContext) => Element[];
+  formula: (node: FormulaNode, ctx: HastContext) => Element[];
+  decoration: (node: Decoration, ctx: HastContext) => Element[];
+};
+/**
+ * ページ (または任意のノード) を hast にする。
+ *
+ * 1 つのノードは「既定のハンドラ (`handlers` があれば置き換え)」で作り、`extensions` を並べた順に通す。
+ * テキストは hast のテキストノードに入れるだけなので、エスケープは文字列にする側 (`toHtml`) が行う。
+ * `javascript:` のようなスキームの URL は属性ごと落とす。
+ * ハンドラの無いノード型 (拡張が足した独自ノード) は、中身を落とさずに子だけを出す。
+ */
+declare const toHast: (node: AnyNode, options?: HastOptions) => Root;
+//#endregion
+//#region src/html/to-html.d.ts
+/**
+ * `& < > " '` を実体参照に置き換える。テキストと属性値のどちらにも使える。
+ * `highlight` に HTML の文字列を返すハイライタを渡すとき、色付けしない部分のエスケープに使う。
+ */
+declare const escapeHtml: (value: string) => string;
+/**
+ * コードブロックの中身を色付けする。`toHast` の `highlight` に加えて、HTML の文字列も返せる。
+ * **文字列はそのまま埋め込まれる**ため、エスケープは実装側の責任になる。
+ * highlight.js や Prism のように HTML の文字列を返すハイライタを、そのまま渡せるようにするため。
+ */
+type Highlighter = (code: string, language: string) => string | Root | HastContent[] | null;
+interface HtmlOptions extends Omit<HastOptions, "highlight"> {
+  /** コードブロックの中身の色付け。 */
+  readonly highlight?: Highlighter;
+  /**
+   * 出力の先頭に `<style>` 要素として差し込む CSS。
+   *
+   * @defaultValue undefined。`<style>` を出さない
+   */
+  readonly style?: string;
+}
+/**
+ * ページ (または任意のノード) を HTML 文字列にする。`hast-util-to-html(toHast(node, options))` と同じ。
+ *
+ * テキストと属性値はエスケープし、`javascript:` のようなスキームの URL は属性ごと落とす。
+ * `highlight` が返した文字列と、`handlers` が返した raw ノードはそのまま埋め込むので、
+ * そこでのエスケープは書いた人の責任になる。
+ */
+declare const toHtml: (node: AnyNode, options?: HtmlOptions) => string;
+//#endregion
+//#region src/html/code-line-numbers.d.ts
+/**
+ * コードブロックの本体行に、1 から数えた行番号 (`data-line`) と桁数 (`data-line-digits`) を付ける拡張。
+ *
+ * ```ts
+ * toHtml(page, { extensions: [codeLineNumbers()] })
+ * ```
+ *
+ * 番号を見せるのは CSS の役目 (`@cosense-toolbox/style` は `data-line` を見て行の左に番号を出す)。
+ * 色付けしてひと塊にまとめたブロックは、行と番号が対応しないので付けない。
+ */
+declare const codeLineNumbers: () => RenderExtension;
+//#endregion
+//#region src/html/table-cell-line-breaks.d.ts
+/**
+ * テーブルのセルの中の `marker` を `<br>` にする描画の拡張。
+ *
+ * 当てるのは、セルの中にある AST の text ノード (記法の外の地の文) だけ。
+ * コード・数式・リンクの表示は text ノードではないので、`classNames` や `handlers` で
+ * 出力を変えても、その中には当たらない。装飾の中身は text ノードなので当たる。
+ * `marker` は文字列そのままで探し (正規表現としては読まない)、区切った文字は通常どおりエスケープされる。
+ * `marker` が空文字なら何もしない。
+ *
+ * @example
+ * toHtml(page, { extensions: [tableCellLineBreaks('\\n')] })
+ */
+declare const tableCellLineBreaks: (marker: string) => RenderExtension;
+//#endregion
+export { type HastContent, type HastContext, type HastHandler, type HastHandlers, type HastHighlighter, type HastOptions, type HastRenderOptions, type Highlighter, type HtmlClassNames, type HtmlOptions, type PageRefNode, type RawNode, type RenderExtension, type RenderTransform, type ResolvedHastOptions, codeLanguageOf, codeLineNumbers, defaultClassNames, defaultHastHandlers, defaultPageUrl, escapeHtml, safeHref, safeSrc, tableCellLineBreaks, toHast, toHtml };
+//# sourceMappingURL=html.d.mts.map

package/dist/html.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.mts","names":[],"sources":["../src/html/to-hast.ts","../src/html/to-html.ts","../src/html/code-line-numbers.ts","../src/html/table-cell-line-breaks.ts"],"mappings":";;;;;cA+Ca,WAAY;;cAGZ,UAAW;;KAcZ,cAAc,eAAe,cAAc,UAAU;;;;;UAMhD;WACN;WACA;WACA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;WACA;;WAEA;;WAEA;;WAEA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;;;cAIE,mBAAmB;;;;;;UA+Bf;WACN;WACA;;;KAIC,cAAc,iBAAiB;;;;;;;;;;;KAY/B,mBAAmB,cAAc,qBAAqB,OAAO;;;;;;;UAQxD;;;;;;;;;;WAUN,WAAW,eAAe,MAAM;;;;;;;;WAQhC,gBAAgB,MAAM;;;;;WAKtB,YAAY;;WAEZ,aAAa;;;;;;;WAOb;;;UAIM;WACN,UAAU,eAAe,MAAM;WAC/B,eAAe,MAAM;WACrB,WAAW;;WAEX,YAAY;WACZ;;;UAIM;;;;;WAKN,oBAAoB;;WAEpB,OAAO,MAAM,YAAY;;WAEzB,WAAW,MAAM,YAAY;WAC7B,SAAS;;KAGR,YAAY,UAAU,gBAChC,MAAM,WAAW,IACjB,KAAK,gBACF,cAAc;;;;;KAMP,2BACA,KAAK,eAAe,YAAY;;;;;;;KAShC,gBAAgB,UAAU,gBACpC,QAAQ,kBACR,MAAM,WAAW,IACjB,KAAK,gBACF,cAAc;;;;;KAMP,8BACA,KAAK,eAAe,gBAAgB;UAG/B,oBAAoB;;;;;WAK1B,WAAW;;;;;WAKX,sBAAsB;;;;;;;cAQpB,iBAAkB;;;;;cASlB,iBAAkB;;;;;;;;cAoQlB;eAAA;;;EA3DY,YAAA,MAAA,WAAS,KAAO,gBAAc;mBAAA;;;;;;;;;;;;;;;;;;;;;;;cAqN1C,SAAU,MAAM,SAAS,UAAS,gBAAmB;;;;;;;cCjqBrD,aAAc;;;;;;KAQf,eAAe,cAAc,8BAA8B,OAAO;UAE7D,oBAAoB,KAAK;;WAE/B,YAAY;;;;;;WAMZ;;;;;;;;;cAkBE,SAAU,MAAM,SAAS,UAAS;;;;;;;;;;;;;cCVlC,uBAAsB;;;;;;;;;;;;;;;cCItB,sBAAuB,mBAAiB"}