@riebeckite/plugin-dataview 0.0.12 → 0.0.13

package/README.md

@@ -1,227 +1,227 @@
-# @riebeckite/plugin-dataview
-
-Evaluate declarative `dataview` code blocks against the content manifest at
-build time and render them as lists, tables, task lists, or calendars. No
-client-side JavaScript is required.
-
-[日本語](./README_ja.md)
-
-## Overview
-
-`dataviewPlugin()` recognises fenced blocks whose language is `dataview`:
-
-````md
-```dataview
-TABLE file.name AS "Name", status
-FROM #project
-WHERE status = "active"
-SORT file.name asc
-LIMIT 10
-```
-````
-
-and renders them from the manifest (every note's frontmatter, tags, links, and
-permalink). DataviewJS (`dataviewjs`) is **not** supported: those blocks stay
-code blocks and produce a diagnostic.
-
-## Usage
-
-```ts
-import { defineConfig } from "@riebeckite/core";
-import { dataviewPlugin } from "@riebeckite/plugin-dataview";
-
-export default defineConfig({
-  // ...
-  plugins: [dataviewPlugin()],
-});
-```
-
-## Query syntax
-
-A block starts with a query type (`LIST`, `TABLE`, `TASK`, or `CALENDAR`)
-followed by optional clauses:
-
-```
-LIST|TABLE|TASK|CALENDAR [expression or columns]
-FROM <source expression>
-WHERE <boolean expression>
-SORT <field> [asc|desc][, ...]
-GROUP BY <field>
-LIMIT <n>
-```
-
-Clauses are case-insensitive. Each clause starts on its own line, but a clause
-body may span multiple lines.
-
-### `LIST`
-
-`LIST` renders an unordered list of matching notes. An optional trailing
-expression is shown as metadata next to the link:
-
-```dataview
-LIST file.date
-FROM #diary
-SORT file.date desc
-```
-
-### `TABLE`
-
-`TABLE` renders a table. When no columns are given, a single `file.link` column
-is used. Columns are field paths, optionally renamed with `AS`:
-
-```dataview
-TABLE file.name AS "Name", status, priority
-FROM #project
-```
-
-### `TASK`
-
-`TASK` extracts the task list items (`- [ ]` / `- [x]`) from every matching
-note and renders them as `<ul class="rb-dataview__tasks">`. `FROM` and `WHERE`
-select the **pages**, not individual tasks:
-
-```dataview
-TASK
-FROM #project
-```
-
-### `CALENDAR`
-
-`CALENDAR` renders a month grid. The optional trailing expression selects the
-date field (default `date`). The month of the most recent matched date is shown:
-
-```dataview
-CALENDAR date
-FROM #project
-```
-
-## Clauses
-
-### `FROM`
-
-`FROM` selects candidate notes. Sources are:
-
-| Source | Meaning |
-| ------ | ------- |
-| `#tag` | Has the tag |
-| `"folder"` | Slug is the folder or lives under it |
-| `[[note]]` | Links to `note` (incoming links) |
-
-Combine sources with `and` / `or`, negate with `!` or `-`, and group with
-parentheses. Adjacent sources are treated as `and`.
-
-```dataview
-FROM (#project or #area) and "notes" and !#archive
-```
-
-### `WHERE`
-
-`WHERE` filters notes with a boolean expression over `file.*` and frontmatter
-fields.
-
-| Feature | Examples |
-| ------- | -------- |
-| Comparison | `status = "active"`, `priority > 2`, `date <= "2026-12-31"` |
-| Boolean | `status = "active" and !draft`, `a or b` |
-| `contains()` | `contains(file.tags, "#project")`, `contains(tags, "project")` |
-| `date()` | `date(due) >= date("2026-01-01")` |
-| `number()` / `string()` | `number(weight) > 3` |
-
-String `=`/`!=` comparisons and `contains()` are case-insensitive. `date()`
-returns a millisecond timestamp (or `null`), so `date(a) < date(b)` compares
-chronologically. `null`/missing values never satisfy `<`/`>` comparisons.
-
-`file.*` fields: `file.name`, `file.title`, `file.slug`, `file.path`,
-`file.folder`, `file.link`, `file.permalink`, `file.url`, `file.tags`,
-`file.date`, `file.created`, `file.updated`, `file.published`. Other frontmatter
-keys are read directly by name (`status`, `priority`, `due`, ...).
-
-### `SORT`
-
-`SORT` accepts a comma-separated list of fields with an optional direction
-(`asc`, the default, or `desc`). Notes with a missing field sort last.
-
-```dataview
-SORT priority desc, file.name asc
-```
-
-### `GROUP BY`
-
-`GROUP BY <field>` groups the matched notes. Each group is headed by the group
-value; `LIST` and `TASK` render one list per group, and `TABLE` inserts a group
-row. Groups keep the order established by `SORT`.
-
-### `LIMIT`
-
-`LIMIT <n>` caps the number of rendered notes (before grouping). It can also be
-set for every block with the `limit` option.
-
-## Options
-
-| Option | Type | Default | Description |
-| ------ | ---- | ------- | ----------- |
-| `className` | `string` | `"rb-dataview"` | Root CSS class |
-| `language` | `string` | `"dataview"` | Fence language to target |
-| `hideFallback` | `boolean` | `false` | Hide the raw-query `<details>` fallback |
-| `limit` | `number` | none | Default `LIMIT` when a block omits one |
-
-## Rendering
-
-Each block becomes:
-
-```html
-<div class="rb-dataview" data-dataview data-dataview-type="list">
-  <!-- list, table, task, or calendar output -->
-  <details class="rb-dataview__fallback">
-    <summary>Dataview query</summary>
-    <pre><code>LIST FROM #project</code></pre>
-  </details>
-</div>
-```
-
-The readable `<details>` fallback contains the raw query and can be disabled
-with `hideFallback`.
-
-## Diagnostics
-
-- `dataviewjs` blocks are left untouched and emit a
-  `dataview-unsupported-language` **warning**. The markdown-time remark
-  transform also records a `file.message` with
-  `source: "@riebeckite/plugin-dataview"`.
-- Blocks the parser or evaluator cannot handle render an inline error box and
-  emit a `dataview-invalid` **error** diagnostic. Unsupported syntax is also
-  reported through `file.message` while the markdown is parsed.
-
-## Limitations
-
-- **No DataviewJS.** `dataviewjs` is intentionally unsupported.
-- **No inline fields** (`field:: value`). Only frontmatter is read.
-- **`TABLE` columns are field paths**, not arbitrary expressions. Rename with
-  `AS "Label"`; computed columns (for example `file.size / 1024`) are not
-  supported.
-- **`TASK` filters pages, not tasks.** `WHERE`/`FROM` apply to the notes that
-  contain tasks.
-- **`CALENDAR` shows one month** — the month of the most recent matched date.
-- `file.size`, `file.mtime`, and `file.ctime` are not available from the
-  manifest and evaluate to `undefined`.
-- Results are fixed at build time and links produced by a dataview block are not
-  added to the content graph (backlinks). A full build always recomputes
-  correctly.
-
-## Exports
-
-- `dataviewPlugin(options?)` / `dataview(options?)` — plugin factory
-- `remarkDataview(options?)` — remark transform usable on its own
-- `parseDataview(source)` — parse a block body into a `DataviewSpec`
-- `selectDataviewEntries(spec, manifest, defaultLimit)` — matching engine
-- `evaluateDataviewExpression(expression, scope)` and
-  `matchesDataviewFrom(from, entry, manifest)` — expression helpers
-- `renderDataview(selection, spec, options, source)` — HTML renderer
-- `resolveDataviewOptions(options?)` — normalise plugin options
-- `DATAVIEW_ATTRIBUTE` — placeholder attribute name
-- Types: `DataviewOptions`, `DataviewSpec`, `DataviewQueryType`,
-  `DataviewExpression`, `DataviewFrom`, and friends
-
-## See also
-
-- [Plugin guide](../../../docs/en/plugin-system.md)
+# @riebeckite/plugin-dataview
+
+Evaluate declarative `dataview` code blocks against the content manifest at
+build time and render them as lists, tables, task lists, or calendars. No
+client-side JavaScript is required.
+
+[日本語](./README_ja.md)
+
+## Overview
+
+`dataviewPlugin()` recognises fenced blocks whose language is `dataview`:
+
+````md
+```dataview
+TABLE file.name AS "Name", status
+FROM #project
+WHERE status = "active"
+SORT file.name asc
+LIMIT 10
+```
+````
+
+and renders them from the manifest (every note's frontmatter, tags, links, and
+permalink). DataviewJS (`dataviewjs`) is **not** supported: those blocks stay
+code blocks and produce a diagnostic.
+
+## Usage
+
+```ts
+import { defineConfig } from "@riebeckite/core";
+import { dataviewPlugin } from "@riebeckite/plugin-dataview";
+
+export default defineConfig({
+  // ...
+  plugins: [dataviewPlugin()],
+});
+```
+
+## Query syntax
+
+A block starts with a query type (`LIST`, `TABLE`, `TASK`, or `CALENDAR`)
+followed by optional clauses:
+
+```
+LIST|TABLE|TASK|CALENDAR [expression or columns]
+FROM <source expression>
+WHERE <boolean expression>
+SORT <field> [asc|desc][, ...]
+GROUP BY <field>
+LIMIT <n>
+```
+
+Clauses are case-insensitive. Each clause starts on its own line, but a clause
+body may span multiple lines.
+
+### `LIST`
+
+`LIST` renders an unordered list of matching notes. An optional trailing
+expression is shown as metadata next to the link:
+
+```dataview
+LIST file.date
+FROM #diary
+SORT file.date desc
+```
+
+### `TABLE`
+
+`TABLE` renders a table. When no columns are given, a single `file.link` column
+is used. Columns are field paths, optionally renamed with `AS`:
+
+```dataview
+TABLE file.name AS "Name", status, priority
+FROM #project
+```
+
+### `TASK`
+
+`TASK` extracts the task list items (`- [ ]` / `- [x]`) from every matching
+note and renders them as `<ul class="rb-dataview__tasks">`. `FROM` and `WHERE`
+select the **pages**, not individual tasks:
+
+```dataview
+TASK
+FROM #project
+```
+
+### `CALENDAR`
+
+`CALENDAR` renders a month grid. The optional trailing expression selects the
+date field (default `date`). The month of the most recent matched date is shown:
+
+```dataview
+CALENDAR date
+FROM #project
+```
+
+## Clauses
+
+### `FROM`
+
+`FROM` selects candidate notes. Sources are:
+
+| Source | Meaning |
+| ------ | ------- |
+| `#tag` | Has the tag |
+| `"folder"` | Slug is the folder or lives under it |
+| `[[note]]` | Links to `note` (incoming links) |
+
+Combine sources with `and` / `or`, negate with `!` or `-`, and group with
+parentheses. Adjacent sources are treated as `and`.
+
+```dataview
+FROM (#project or #area) and "notes" and !#archive
+```
+
+### `WHERE`
+
+`WHERE` filters notes with a boolean expression over `file.*` and frontmatter
+fields.
+
+| Feature | Examples |
+| ------- | -------- |
+| Comparison | `status = "active"`, `priority > 2`, `date <= "2026-12-31"` |
+| Boolean | `status = "active" and !draft`, `a or b` |
+| `contains()` | `contains(file.tags, "#project")`, `contains(tags, "project")` |
+| `date()` | `date(due) >= date("2026-01-01")` |
+| `number()` / `string()` | `number(weight) > 3` |
+
+String `=`/`!=` comparisons and `contains()` are case-insensitive. `date()`
+returns a millisecond timestamp (or `null`), so `date(a) < date(b)` compares
+chronologically. `null`/missing values never satisfy `<`/`>` comparisons.
+
+`file.*` fields: `file.name`, `file.title`, `file.slug`, `file.path`,
+`file.folder`, `file.link`, `file.permalink`, `file.url`, `file.tags`,
+`file.date`, `file.created`, `file.updated`, `file.published`. Other frontmatter
+keys are read directly by name (`status`, `priority`, `due`, ...).
+
+### `SORT`
+
+`SORT` accepts a comma-separated list of fields with an optional direction
+(`asc`, the default, or `desc`). Notes with a missing field sort last.
+
+```dataview
+SORT priority desc, file.name asc
+```
+
+### `GROUP BY`
+
+`GROUP BY <field>` groups the matched notes. Each group is headed by the group
+value; `LIST` and `TASK` render one list per group, and `TABLE` inserts a group
+row. Groups keep the order established by `SORT`.
+
+### `LIMIT`
+
+`LIMIT <n>` caps the number of rendered notes (before grouping). It can also be
+set for every block with the `limit` option.
+
+## Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `className` | `string` | `"rb-dataview"` | Root CSS class |
+| `language` | `string` | `"dataview"` | Fence language to target |
+| `hideFallback` | `boolean` | `false` | Hide the raw-query `<details>` fallback |
+| `limit` | `number` | none | Default `LIMIT` when a block omits one |
+
+## Rendering
+
+Each block becomes:
+
+```html
+<div class="rb-dataview" data-dataview data-dataview-type="list">
+  <!-- list, table, task, or calendar output -->
+  <details class="rb-dataview__fallback">
+    <summary>Dataview query</summary>
+    <pre><code>LIST FROM #project</code></pre>
+  </details>
+</div>
+```
+
+The readable `<details>` fallback contains the raw query and can be disabled
+with `hideFallback`.
+
+## Diagnostics
+
+- `dataviewjs` blocks are left untouched and emit a
+  `dataview-unsupported-language` **warning**. The markdown-time remark
+  transform also records a `file.message` with
+  `source: "@riebeckite/plugin-dataview"`.
+- Blocks the parser or evaluator cannot handle render an inline error box and
+  emit a `dataview-invalid` **error** diagnostic. Unsupported syntax is also
+  reported through `file.message` while the markdown is parsed.
+
+## Limitations
+
+- **No DataviewJS.** `dataviewjs` is intentionally unsupported.
+- **No inline fields** (`field:: value`). Only frontmatter is read.
+- **`TABLE` columns are field paths**, not arbitrary expressions. Rename with
+  `AS "Label"`; computed columns (for example `file.size / 1024`) are not
+  supported.
+- **`TASK` filters pages, not tasks.** `WHERE`/`FROM` apply to the notes that
+  contain tasks.
+- **`CALENDAR` shows one month** — the month of the most recent matched date.
+- `file.size`, `file.mtime`, and `file.ctime` are not available from the
+  manifest and evaluate to `undefined`.
+- Results are fixed at build time and links produced by a dataview block are not
+  added to the content graph (backlinks). A full build always recomputes
+  correctly.
+
+## Exports
+
+- `dataviewPlugin(options?)` / `dataview(options?)` — plugin factory
+- `remarkDataview(options?)` — remark transform usable on its own
+- `parseDataview(source)` — parse a block body into a `DataviewSpec`
+- `selectDataviewEntries(spec, manifest, defaultLimit)` — matching engine
+- `evaluateDataviewExpression(expression, scope)` and
+  `matchesDataviewFrom(from, entry, manifest)` — expression helpers
+- `renderDataview(selection, spec, options, source)` — HTML renderer
+- `resolveDataviewOptions(options?)` — normalise plugin options
+- `DATAVIEW_ATTRIBUTE` — placeholder attribute name
+- Types: `DataviewOptions`, `DataviewSpec`, `DataviewQueryType`,
+  `DataviewExpression`, `DataviewFrom`, and friends
+
+## See also
+
+- [Plugin guide](../../../docs/en/reference/plugin-api.md)

package/README_ja.md

@@ -1,191 +1,191 @@
-# @riebeckite/plugin-dataview
-
-宣言的な `dataview` コードブロックをビルド時にコンテンツマニフェストへ照合し、リスト・表・タスク一覧・カレンダーとして描画するプラグインです。クライアント側の JavaScript は不要です。
-
-[English](./README.md)
-
-## できること
-
-`dataviewPlugin()` は、フェンス言語が `dataview` のコードブロックを検出します。
-
-````md
-```dataview
-TABLE file.name AS "Name", status
-FROM #project
-WHERE status = "active"
-SORT file.name asc
-LIMIT 10
-```
-````
-
-ブロックはマニフェスト（全ノートのフロントマター・タグ・リンク・パーマリンク）を使って描画されます。DataviewJS（`dataviewjs`）には対応しません。そのブロックはコードブロックのまま残り、診断を1件出します。
-
-## 設定
-
-```ts
-import { defineConfig } from "@riebeckite/core";
-import { dataviewPlugin } from "@riebeckite/plugin-dataview";
-
-export default defineConfig({
-  // ...
-  plugins: [dataviewPlugin()],
-});
-```
-
-## クエリの書き方
-
-ブロックはクエリ種別（`LIST`、`TABLE`、`TASK`、`CALENDAR`）で始まり、そのあとに任意の節が続きます。
-
-```
-LIST|TABLE|TASK|CALENDAR [式または列]
-FROM <ソース式>
-WHERE <真偽式>
-SORT <フィールド> [asc|desc][, ...]
-GROUP BY <フィールド>
-LIMIT <n>
-```
-
-節のキーワードは大文字小文字を区別しません。節はそれぞれ行頭から始めますが、節の内容は複数行にまたがってもかまいません。
-
-### `LIST`
-
-`LIST` は一致したノートを箇条書きにします。末尾に式を書くと、リンクの横にメタ情報として表示します。
-
-```dataview
-LIST file.date
-FROM #diary
-SORT file.date desc
-```
-
-### `TABLE`
-
-`TABLE` は表を描画します。列を省略すると `file.link` の1列だけになります。列はフィールドパスで、`AS` で見出しを付けられます。
-
-```dataview
-TABLE file.name AS "Name", status, priority
-FROM #project
-```
-
-### `TASK`
-
-`TASK` は一致した各ノートからタスク項目（`- [ ]` / `- [x]`）を取り出し、`<ul class="rb-dataview__tasks">` として描画します。`FROM` と `WHERE` が選ぶのは**ノート**であり、個々のタスクではありません。
-
-```dataview
-TASK
-FROM #project
-```
-
-### `CALENDAR`
-
-`CALENDAR` は月のグリッドを描画します。末尾の式で日付フィールドを指定できます（既定は `date`）。一致した日付のうち最も新しい月を表示します。
-
-```dataview
-CALENDAR date
-FROM #project
-```
-
-## 節
-
-### `FROM`
-
-`FROM` は候補となるノートを絞り込みます。使えるソースは次の3つです。
-
-| ソース | 意味 |
-| --- | --- |
-| `#tag` | そのタグを持つ |
-| `"folder"` | スラッグがそのフォルダ、またはその配下 |
-| `[[note]]` | `note` へリンクしている（被リンク） |
-
-ソースは `and` / `or` でつなぎ、`!` または `-` で否定し、`(` `)` でまとめられます。ソースを続けて書いた場合は `and` とみなします。
-
-```dataview
-FROM (#project or #area) and "notes" and !#archive
-```
-
-### `WHERE`
-
-`WHERE` は `file.*` とフロントマターのフィールドに対する真偽式でノートを絞り込みます。
-
-| 機能 | 例 |
-| --- | --- |
-| 比較 | `status = "active"`、`priority > 2`、`date <= "2026-12-31"` |
-| 論理 | `status = "active" and !draft`、`a or b` |
-| `contains()` | `contains(file.tags, "#project")`、`contains(tags, "project")` |
-| `date()` | `date(due) >= date("2026-01-01")` |
-| `number()` / `string()` | `number(weight) > 3` |
-
-文字列の `=` / `!=` と `contains()` は大文字小文字を区別しません。`date()` はミリ秒のタイムスタンプ（または `null`）を返すので、`date(a) < date(b)` は時系列で比較できます。`null` や未定義の値は `<` / `>` を満たしません。
-
-`file.*` で使えるフィールドは `file.name`、`file.title`、`file.slug`、`file.path`、`file.folder`、`file.link`、`file.permalink`、`file.url`、`file.tags`、`file.date`、`file.created`、`file.updated`、`file.published` です。それ以外はフロントマターのキーをそのまま名前で参照します（`status`、`priority`、`due` など）。
-
-### `SORT`
-
-`SORT` はフィールドをカンマ区切りで並べ、各フィールドに `asc`（既定）または `desc` を付けられます。値が無いノートは末尾に並びます。
-
-```dataview
-SORT priority desc, file.name asc
-```
-
-### `GROUP BY`
-
-`GROUP BY <フィールド>` は一致したノートをグループ化します。グループ値が見出しになり、`LIST` と `TASK` はグループごとにリストを、`TABLE` はグループ行を描画します。グループの順序は `SORT` の結果を保ちます。
-
-### `LIMIT`
-
-`LIMIT <n>` は描画するノート数を上限で打ち切ります（グループ化の前）。オプション `limit` を使えば全ブロックに既定の上限を設定できます。
-
-## オプション
-
-| オプション | 型 | 既定値 | 内容 |
-| --- | --- | --- | --- |
-| `className` | `string` | `"rb-dataview"` | ルート要素の CSS クラス |
-| `language` | `string` | `"dataview"` | 対象のフェンス言語 |
-| `hideFallback` | `boolean` | `false` | 生クエリの `<details>` フォールバックを隠す |
-| `limit` | `number` | なし | ブロックが `LIMIT` を省略したときの上限 |
-
-## 描画結果
-
-各ブロックは次のような HTML になります。
-
-```html
-<div class="rb-dataview" data-dataview data-dataview-type="list">
-  <!-- リスト・表・タスク・カレンダーのいずれか -->
-  <details class="rb-dataview__fallback">
-    <summary>Dataview query</summary>
-    <pre><code>LIST FROM #project</code></pre>
-  </details>
-</div>
-```
-
-`<details>` のフォールバックには元のクエリが入ります。`hideFallback` で非表示にできます。
-
-## 診断
-
-- `dataviewjs` のブロックはそのまま残し、`dataview-unsupported-language` の**警告**を出します。Markdown 解析時の remark 変換でも `source: "@riebeckite/plugin-dataview"` を付けた `file.message` を記録します。
-- パーサーや評価器が扱えないブロックは、その場にエラー表示を出しつつ `dataview-invalid` の**エラー**診断を生成します。対応していない構文は、Markdown 解析時にも `file.message` で報告されます。
-
-## 制限事項
-
-- **DataviewJS には対応しません。** `dataviewjs` は意図的に対象外です。
-- **インラインフィールド（`field:: value`）には対応しません。** 参照するのはフロントマターだけです。
-- **`TABLE` の列はフィールドパスです。** 任意の式は書けません。見出しの変更は `AS "Label"` だけです（`file.size / 1024` のような計算列は不可）。
-- **`TASK` が絞り込むのはノートです。** `FROM` / `WHERE` はタスクを含むノートに働きます。
-- **`CALENDAR` が表示するのは1か月分**です。一致した日付のうち最も新しい月を描画します。
-- `file.size`、`file.mtime`、`file.ctime` はマニフェストから取得できず `undefined` になります。
-- 結果はビルド時に確定します。dataview ブロックが生成したリンクはコンテンツグラフ（バックリンク）には含まれません。フルビルドでは常に正しく再計算されます。
-
-## エクスポート
-
-- `dataviewPlugin(options?)` / `dataview(options?)` — プラグインファクトリ
-- `remarkDataview(options?)` — Remark 変換だけを利用する場合の API
-- `parseDataview(source)` — ブロック本文を `DataviewSpec` に変換
-- `selectDataviewEntries(spec, manifest, defaultLimit)` — 照合エンジン
-- `evaluateDataviewExpression(expression, scope)` と `matchesDataviewFrom(from, entry, manifest)` — 式のヘルパー
-- `renderDataview(selection, spec, options, source)` — HTML レンダラー
-- `resolveDataviewOptions(options?)` — オプションの正規化
-- `DATAVIEW_ATTRIBUTE` — プレースホルダーの属性名
-- 型: `DataviewOptions`、`DataviewSpec`、`DataviewQueryType`、`DataviewExpression`、`DataviewFrom` ほか
-
-## 関連資料
-
-- [プラグインシステム](../../../docs/ja/plugin-system.md)
+# @riebeckite/plugin-dataview
+
+宣言的な `dataview` コードブロックをビルド時にコンテンツマニフェストへ照合し、リスト・表・タスク一覧・カレンダーとして描画するプラグインです。クライアント側の JavaScript は不要です。
+
+[English](./README.md)
+
+## できること
+
+`dataviewPlugin()` は、フェンス言語が `dataview` のコードブロックを検出します。
+
+````md
+```dataview
+TABLE file.name AS "Name", status
+FROM #project
+WHERE status = "active"
+SORT file.name asc
+LIMIT 10
+```
+````
+
+ブロックはマニフェスト（全ノートのフロントマター・タグ・リンク・パーマリンク）を使って描画されます。DataviewJS（`dataviewjs`）には対応しません。そのブロックはコードブロックのまま残り、診断を1件出します。
+
+## 設定
+
+```ts
+import { defineConfig } from "@riebeckite/core";
+import { dataviewPlugin } from "@riebeckite/plugin-dataview";
+
+export default defineConfig({
+  // ...
+  plugins: [dataviewPlugin()],
+});
+```
+
+## クエリの書き方
+
+ブロックはクエリ種別（`LIST`、`TABLE`、`TASK`、`CALENDAR`）で始まり、そのあとに任意の節が続きます。
+
+```
+LIST|TABLE|TASK|CALENDAR [式または列]
+FROM <ソース式>
+WHERE <真偽式>
+SORT <フィールド> [asc|desc][, ...]
+GROUP BY <フィールド>
+LIMIT <n>
+```
+
+節のキーワードは大文字小文字を区別しません。節はそれぞれ行頭から始めますが、節の内容は複数行にまたがってもかまいません。
+
+### `LIST`
+
+`LIST` は一致したノートを箇条書きにします。末尾に式を書くと、リンクの横にメタ情報として表示します。
+
+```dataview
+LIST file.date
+FROM #diary
+SORT file.date desc
+```
+
+### `TABLE`
+
+`TABLE` は表を描画します。列を省略すると `file.link` の1列だけになります。列はフィールドパスで、`AS` で見出しを付けられます。
+
+```dataview
+TABLE file.name AS "Name", status, priority
+FROM #project
+```
+
+### `TASK`
+
+`TASK` は一致した各ノートからタスク項目（`- [ ]` / `- [x]`）を取り出し、`<ul class="rb-dataview__tasks">` として描画します。`FROM` と `WHERE` が選ぶのは**ノート**であり、個々のタスクではありません。
+
+```dataview
+TASK
+FROM #project
+```
+
+### `CALENDAR`
+
+`CALENDAR` は月のグリッドを描画します。末尾の式で日付フィールドを指定できます（既定は `date`）。一致した日付のうち最も新しい月を表示します。
+
+```dataview
+CALENDAR date
+FROM #project
+```
+
+## 節
+
+### `FROM`
+
+`FROM` は候補となるノートを絞り込みます。使えるソースは次の3つです。
+
+| ソース | 意味 |
+| --- | --- |
+| `#tag` | そのタグを持つ |
+| `"folder"` | スラッグがそのフォルダ、またはその配下 |
+| `[[note]]` | `note` へリンクしている（被リンク） |
+
+ソースは `and` / `or` でつなぎ、`!` または `-` で否定し、`(` `)` でまとめられます。ソースを続けて書いた場合は `and` とみなします。
+
+```dataview
+FROM (#project or #area) and "notes" and !#archive
+```
+
+### `WHERE`
+
+`WHERE` は `file.*` とフロントマターのフィールドに対する真偽式でノートを絞り込みます。
+
+| 機能 | 例 |
+| --- | --- |
+| 比較 | `status = "active"`、`priority > 2`、`date <= "2026-12-31"` |
+| 論理 | `status = "active" and !draft`、`a or b` |
+| `contains()` | `contains(file.tags, "#project")`、`contains(tags, "project")` |
+| `date()` | `date(due) >= date("2026-01-01")` |
+| `number()` / `string()` | `number(weight) > 3` |
+
+文字列の `=` / `!=` と `contains()` は大文字小文字を区別しません。`date()` はミリ秒のタイムスタンプ（または `null`）を返すので、`date(a) < date(b)` は時系列で比較できます。`null` や未定義の値は `<` / `>` を満たしません。
+
+`file.*` で使えるフィールドは `file.name`、`file.title`、`file.slug`、`file.path`、`file.folder`、`file.link`、`file.permalink`、`file.url`、`file.tags`、`file.date`、`file.created`、`file.updated`、`file.published` です。それ以外はフロントマターのキーをそのまま名前で参照します（`status`、`priority`、`due` など）。
+
+### `SORT`
+
+`SORT` はフィールドをカンマ区切りで並べ、各フィールドに `asc`（既定）または `desc` を付けられます。値が無いノートは末尾に並びます。
+
+```dataview
+SORT priority desc, file.name asc
+```
+
+### `GROUP BY`
+
+`GROUP BY <フィールド>` は一致したノートをグループ化します。グループ値が見出しになり、`LIST` と `TASK` はグループごとにリストを、`TABLE` はグループ行を描画します。グループの順序は `SORT` の結果を保ちます。
+
+### `LIMIT`
+
+`LIMIT <n>` は描画するノート数を上限で打ち切ります（グループ化の前）。オプション `limit` を使えば全ブロックに既定の上限を設定できます。
+
+## オプション
+
+| オプション | 型 | 既定値 | 内容 |
+| --- | --- | --- | --- |
+| `className` | `string` | `"rb-dataview"` | ルート要素の CSS クラス |
+| `language` | `string` | `"dataview"` | 対象のフェンス言語 |
+| `hideFallback` | `boolean` | `false` | 生クエリの `<details>` フォールバックを隠す |
+| `limit` | `number` | なし | ブロックが `LIMIT` を省略したときの上限 |
+
+## 描画結果
+
+各ブロックは次のような HTML になります。
+
+```html
+<div class="rb-dataview" data-dataview data-dataview-type="list">
+  <!-- リスト・表・タスク・カレンダーのいずれか -->
+  <details class="rb-dataview__fallback">
+    <summary>Dataview query</summary>
+    <pre><code>LIST FROM #project</code></pre>
+  </details>
+</div>
+```
+
+`<details>` のフォールバックには元のクエリが入ります。`hideFallback` で非表示にできます。
+
+## 診断
+
+- `dataviewjs` のブロックはそのまま残し、`dataview-unsupported-language` の**警告**を出します。Markdown 解析時の remark 変換でも `source: "@riebeckite/plugin-dataview"` を付けた `file.message` を記録します。
+- パーサーや評価器が扱えないブロックは、その場にエラー表示を出しつつ `dataview-invalid` の**エラー**診断を生成します。対応していない構文は、Markdown 解析時にも `file.message` で報告されます。
+
+## 制限事項
+
+- **DataviewJS には対応しません。** `dataviewjs` は意図的に対象外です。
+- **インラインフィールド（`field:: value`）には対応しません。** 参照するのはフロントマターだけです。
+- **`TABLE` の列はフィールドパスです。** 任意の式は書けません。見出しの変更は `AS "Label"` だけです（`file.size / 1024` のような計算列は不可）。
+- **`TASK` が絞り込むのはノートです。** `FROM` / `WHERE` はタスクを含むノートに働きます。
+- **`CALENDAR` が表示するのは1か月分**です。一致した日付のうち最も新しい月を描画します。
+- `file.size`、`file.mtime`、`file.ctime` はマニフェストから取得できず `undefined` になります。
+- 結果はビルド時に確定します。dataview ブロックが生成したリンクはコンテンツグラフ（バックリンク）には含まれません。フルビルドでは常に正しく再計算されます。
+
+## エクスポート
+
+- `dataviewPlugin(options?)` / `dataview(options?)` — プラグインファクトリ
+- `remarkDataview(options?)` — Remark 変換だけを利用する場合の API
+- `parseDataview(source)` — ブロック本文を `DataviewSpec` に変換
+- `selectDataviewEntries(spec, manifest, defaultLimit)` — 照合エンジン
+- `evaluateDataviewExpression(expression, scope)` と `matchesDataviewFrom(from, entry, manifest)` — 式のヘルパー
+- `renderDataview(selection, spec, options, source)` — HTML レンダラー
+- `resolveDataviewOptions(options?)` — オプションの正規化
+- `DATAVIEW_ATTRIBUTE` — プレースホルダーの属性名
+- 型: `DataviewOptions`、`DataviewSpec`、`DataviewQueryType`、`DataviewExpression`、`DataviewFrom` ほか
+
+## 関連資料
+
+- [プラグインシステム](../../../docs/ja/reference/plugin-api.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/plugin-dataview",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   "dependencies": {
     "@types/mdast": "^4.0.4",
     "unist-util-visit": "^5.1.0",
-    "@riebeckite/core": "0.0.12"
+    "@riebeckite/core": "0.0.13"
   },
   "publishConfig": {
     "access": "public"