@riebeckite/plugin-bases 0.0.27 → 0.0.28

package/README.md

@@ -2,181 +2,165 @@
 
 <!-- Generated from docs/docs/plugins/bases.md. Edit the canonical documentation in docs/docs/plugins and run `pnpm docs:sync`. -->
 
-Render Obsidian Bases definitions from fenced `base` code blocks. Filtering,
-sorting, and view composition run against the content manifest at build time, so
-no client-side JavaScript is required.
+Render a compatible, build-time subset of Obsidian Bases. `bases()` supports both
+fenced `base` blocks and referenced `.base` documents; no client-side evaluator
+is shipped.
 
 [日本語](./README_ja.md)
 
-## Overview
+## Setup
 
-`bases()` recognises fenced blocks
+```ts
+import { bases } from "@riebeckite/plugin-bases";
 
-````md
-```base
-filters:
-  and:
-    - file.hasTag("featured")
-properties:
-  file.name:
-    displayName: Title
-  file.tags:
-    displayName: Tags
-views:
-  - type: table
-    name: Featured
-    order:
-      - file.name
-      - file.tags
-    limit: 10
+export default { plugins: [bases()] };
 ```
-````
 
-and renders them using the content manifest (every note's frontmatter, tags,
-links, and permalink).
+## `.base` documents and publication
 
-## Usage
+A `.base` file becomes a PageType page at its extensionless path when a routable
+Markdown note links to it, for example `![views/Books.base](https://github.com/Rerurate514/riebeckite/blob/main/docs/docs/views/Books.base.md)` creates
+`/views/Books`. This uses the normal PageType API and does not install custom
+routing.
 
-```ts
-import { defineConfig } from "@riebeckite/core";
-import { bases } from "@riebeckite/plugin-bases";
-
-export default defineConfig({
-  // ...
-  plugins: [bases()],
-});
-```
+Document-page discovery uses Core's `publicEntries`, so a public or unlisted note
+may explicitly expose a referenced Base. Base rows use `discoverableEntries`:
+only public notes are listed automatically; unlisted notes remain routable only by
+their direct URL. Drafts and scheduled notes are excluded from both. A Base
+referenced only from non-public content is not published. Existing Markdown pages
+and public redirects win route collisions; the Base page is skipped with a
+`bases-invalid` warning.
 
-## Block syntax
-
-The block body is an Obsidian Base YAML document.
-
-| Field | Type | Description |
-| ----- | ---- | ----------- |
-| `filters` | expression \| list \| object | Top-level filter applied to every view (below) |
-| `properties` | object | Property id -> display name (or `{ displayName }`) |
-| `views` | object[] | One or more views |
-
-### Views
-
-| Field | Type | Description |
-| ----- | ---- | ----------- |
-| `type` | `"table"` \| `"cards"` | Output kind. Defaults to `table` |
-| `name` | string | Optional label rendered above the view |
-| `filters` | filter | Additional filter, combined with the top-level filter using AND |
-| `order` | string \| string[] | Columns (property ids) and their display order |
-| `columns` | string \| string[] | Alias for `order` |
-| `sort` | object \| object[] \| string | Sort keys (below) |
-| `limit` | number | Row cap for this view; still bounded by the `limit` option |
-
-`sort` accepts the Core shape `{ field, order }`, the Obsidian shape
-`{ property, direction }`, or a shorthand string (`"-file.name"` sorts
-descending). When a view omits `order`/`columns`, the columns are the keys of
-`properties` (in order), or `["file.name", "file.tags"]`.
-
-### Filter grammar
-
-A filter is an expression string, a list of expressions (treated as AND), or an
-object with `and` / `or` / `not` keys. `and` and `or` take a list; `not` takes an
-expression or a list (the list is ANDed, then negated). A plain object whose keys
-are property names is treated as equality.
-
-| Expression | Description |
-| ---------- | ----------- |
-| `file.hasTag("x")` | Has the tag `x` (or a subtag `x/...`). Case-insensitive |
-| `file.inFolder("x")` | Slug equals `x` or starts with `x/` |
-| `file.hasLink("x")` | Links to `x` (by resolved slug, raw target, or file name) |
-| `file.name` / `file.title` | Note title |
-| `file.path` / `file.slug` | Slug |
-| `file.folder` | Parent folder of the slug |
-| `file.link` / `file.permalink` | Permalink |
-| `file.tags` | Tags |
-| `note.key` / `key` | A frontmatter value |
-
-Comparisons use `==`, `!=`, `>`, `<`, `>=`, `<=`, and `contains`. String
-comparisons are case-insensitive; `contains` tests array membership or substring
-containment. Bare scalar lists are ANDed.
+## Example
 
 ```yaml
-filters:
-  and:
-    - file.hasTag("featured")
-    - or:
-        - note.status == "published"
-        - note.status == "review"
-    - not:
-        - file.hasTag("draft")
+filters: note.status == "published" && !file.hasTag("hidden")
+formulas:
+  label: 'note.author.name.upper() + " / " + note.score'
+summaries:
+  total: values.reduce(acc + value, 0)
+properties:
+  file.name: File
+  formula.label: Label
 views:
   - type: table
-    name: Featured
-    order: [file.name, note.status]
-    sort:
-      - property: file.name
-        direction: ASC
-    limit: 20
+    name: Books
+    order: [file.name, formula.label]
+    sort: [{ property: formula.label, direction: DESC }]
+    groupBy: { property: note.status, direction: ASC }
+    summaries: { formula.label: total }
+  - type: cards
+    name: Cards
+    order: [file.name, formula.label]
 ```
 
-## Options
-
-| Option | Type | Default | Description |
-| ------ | ---- | ------- | ----------- |
-| `className` | `string` | `"rb-bases"` | Root CSS class |
-| `language` | `string` | `"base"` | Fence language to target |
-| `limit` | `number` | `100` | Global row cap applied to every view |
-| `showFallback` | `boolean` | `true` | Render the raw Base definition in a `<details>` fallback |
-| `view` | `string` | none | Render only the view with this name when a Base defines several |
-
-## Output HTML / CSS hooks
-
-```html
-<div class="rb-bases" data-bases data-bases-view="table">
-  <section class="rb-bases__view" data-bases-view="table">
-    <h3 class="rb-bases__view-name">Featured</h3>
-    <table class="rb-bases__table"> ... </table>
-  </section>
-  <details class="rb-bases__fallback"> ... </details>
-</div>
-```
-
-Stable classes: `rb-bases`, `rb-bases__view`, `rb-bases__view-name`,
-`rb-bases__table`, `rb-bases__heading`, `rb-bases__cell`, `rb-bases__row`,
-`rb-bases__link`, `rb-bases__tags`, `rb-bases__tag`, `rb-bases__cards`,
-`rb-bases__card`, `rb-bases__card-title`, `rb-bases__fields`, `rb-bases__field`,
-`rb-bases__field-label`, `rb-bases__field-value`, `rb-bases__empty`,
-`rb-bases__fallback`, `rb-bases--error`. Stable attributes: `data-bases`,
-`data-bases-view`.
-
-## Diagnostics
-
-A block that is not valid YAML, or that uses an unsupported filter expression or
-view shape, is left as a code block and reported through `file.message(...)` with
-`source: "@riebeckite/plugin-bases"`.
-
-## Limitations
-
-This is an MVP subset of Obsidian Bases:
-
-- Only the `table` and `cards` view types are rendered.
-- Inline boolean operators (`&&`, `||`, `!`) are not supported; use the
-  `and` / `or` / `not` YAML structure.
-- `if()` / `filter()` and other Base formula functions are not supported.
-- Nested property paths and `file.mtime` / `file.ctime` are mapped onto `date`.
-- Property-to-property comparisons are not supported; the right-hand side is a
-  literal.
-- Results are fixed at build time. Rebuilding a host note when a queried note
-  changes is future work; a full build always recomputes correctly.
-
-## Exports
-
-- `bases(options?)` — plugin factory (alias: `basesPlugin`)
-- `remarkBases(options?)` — remark transform usable on its own (`options.language`
-  selects the fence language)
-- `parseBases(document)` — compiles a parsed YAML Base document to a spec
-- `matchesCondition(condition, entry)` — condition evaluator
-- Types: `BasesOptions`, `BasesSpec`, `BasesView`, `BasesViewType`,
-  `BasesCondition`, `BasesValueRef`, `BasesBuiltinValue`, `BasesOperator`,
-  `BasesLiteral`
-
-## See also
-
-- [Plugin guide](https://github.com/Rerurate514/riebeckite/blob/main/docs/docs/reference/plugin-api.md)
+The same YAML may be placed in a fenced `base` block or in a `.base` file.
+Top-level and view-local `filters` are combined with AND. Table and cards are
+rendered at build time; all dynamic values are escaped before HTML output.
+
+## Official syntax audit
+
+This implementation follows the documented YAML shape in the [Obsidian Bases
+syntax](https://help.obsidian.md/bases/syntax) and [views](https://help.obsidian.md/bases/views)
+references. Compatibility is deliberately scoped to deterministic static output.
+
+| Syntax or view capability | Status | Static behavior |
+| --- | --- | --- |
+| Root `filters`, `formulas`, `properties`, `summaries`, and `views` | Supported | Recursive `and`/`or`/`not` filters and `displayName` are accepted. |
+| View `type`, `name`, `limit`, `filters`, `order`, `sort`, `groupBy`, `groupOrder`, and `summaries` | Supported | `groupOrder` is exclusive: an empty list hides all groups, and listed missing values create empty groups. |
+| Table and cards layouts | Supported | Generated semantic HTML has no runtime evaluator. |
+| List, kanban, and map layouts | Unsupported | Their interactive and spatial behavior cannot be represented by this static renderer. |
+| Editing, property menus, resize, drag-and-drop, and collapse controls | Out of Scope | Bases is rendered during the site build. |
+
+## Expression and formula subset
+
+Expressions are parsed into an AST and interpreted directly. They never use
+`eval`, `Function`, or arbitrary JavaScript execution. Supported syntax includes
+literal values and arrays, nested member/index access, `!`, unary `-`, arithmetic,
+comparison, `&&`, `||`, parentheses, property-to-property comparisons, and
+`formula.name` references. Formula cycles evaluate to an empty value.
+
+Supported functions: `if`, `list`, `length`, `number`, `min`, `max`, `date`,
+`duration`, `isTruthy`, `isType`, `toString`, `escapeHTML`; string `lower`,
+`upper`, `title`, `contains`, `startsWith`, `endsWith`, `trim`, `split`,
+`replace`, `reverse`, `repeat`, `slice`, `isEmpty`; list `contains`, `containsAll`,
+`containsAny`, `join`, `unique`, `flat`, `sort`, `reverse`, `slice`, `isEmpty`,
+`mean`, `sum`, `min`, `max`, `map`, `filter`, `reduce`; number `round`, `floor`,
+`ceil`, `abs`, `toFixed`; object `isEmpty`, `keys`, `values`; UTC date fields,
+`date`, `time`, `format`; and `file.hasTag`, `file.hasLink`, `file.inFolder`,
+`file.hasProperty`.
+
+`date()` accepts only a UTC ISO timestamp, `YYYY-MM-DD`, a finite epoch
+millisecond value, or an existing Date. Date fields and formatting use UTC. This
+avoids host locale and ambiguous date parsing during static builds.
+
+Formula evaluation is bounded to 10,000 AST steps and 128 nested expressions per
+evaluation. Exceeding either limit stops deterministically, reports a
+`bases-invalid` diagnostic, and renders the Base error fallback. This prevents
+large or deeply nested higher-order expressions from making a static build
+unbounded; JavaScript callbacks are never executed.
+
+## File metadata
+
+`file.size` is the source file's byte size. `file.mtime` and `file.ctime` are
+UTC `Date` values sourced from the filesystem, so they can be used in properties,
+filters, formulas, sorting, grouping, summaries, and higher-order expressions.
+Missing or invalid source metadata evaluates to an empty value rather than being
+derived from rendered Markdown or build time. Date subtraction returns
+milliseconds; a Date can also be offset by a duration such as `"7 days"`.
+
+For filesystem content, `file.ctime` uses Node's `birthtime` value, not
+`stat.ctime` (which is a status-change time). Windows normally provides creation
+time. Linux filesystems may not expose a creation time; Node can report a
+filesystem-dependent fallback or no usable value, so portability-sensitive Bases
+should handle an empty `file.ctime`. Cached timestamps retain their UTC instant.
+
+## Incremental builds
+
+Bases records the properties read by filters, formulas, columns, sorting, grouping,
+and summaries in the persisted Output Inventory. This applies independently to fenced
+Bases and each referenced `.base` document. A change to one of those properties, to
+file metadata it reads, or to the discoverable candidate set regenerates only the
+Base output that reads it. This includes notes that change from not matching to
+matching a filter. Body-only and unrelated frontmatter edits reuse the Base output.
+
+Formula cycles, dynamic property access, and other dependencies that cannot be proven
+statically use a conservative per-Base fallback. The fallback never treats an unknown
+dependency as no dependency. Draft, scheduled, and unlisted entries remain excluded
+from Base rows and are not exposed through cached output.
+
+## Static view accessibility
+
+Tables retain column and row-group headers, include an off-screen result count,
+and are wrapped in a keyboard-focusable horizontal scroll region for narrow
+screens. Group labels include their row count; `groupOrder` entries without a
+matching row render an explicit empty group. Card groups use labelled lists,
+and summary values include an off-screen column label. These additions preserve
+the static, no-JavaScript output model.
+
+## Compatibility matrix
+
+| Obsidian Base feature | Status | Notes |
+| --- | --- | --- |
+| YAML root, `filters`, `properties`, `formulas`, `summaries`, `views` | Supported | Invalid YAML/specs produce a diagnostic. |
+| Table and cards | Supported | Other view types are not rendered. |
+| AST filters and formulas | Supported subset | See the function list above. |
+| Formula sorting and multiple stable sort keys | Supported | Empty values sort last. |
+| `groupBy` and `groupOrder` | Supported | Formula properties, ordered empty groups, table, and cards are supported. Interactive collapse is not. |
+| Table summaries | Supported subset | Named summaries and Empty, Filled, Unique, Checked, Unchecked, numeric, and date summaries are available. |
+| Card summaries | Out of Scope | Obsidian displays summaries in tables, not cards. |
+| `file.name`, `file.path`, `file.ext`, `file.folder`, `file.tags`, `file.links`, `file.properties`, `file.link` | Partial | Derived from the Markdown manifest; name/path use the `.md` source convention. |
+| `file.size`, `file.mtime`, `file.ctime` | Supported | Byte size, filesystem modification time, and filesystem creation-time equivalent. `ctime` can be unavailable on Linux; it is never mapped from `stat.ctime`, frontmatter, or build time. |
+| Backlinks, embeds | Unsupported | These values are empty. |
+| List `map`, `filter`, and `reduce` | Supported subset | Their expressions use the `value`, `index`, and `acc` scope with a bounded list size. |
+| Deterministic utility, object, date, and file-property functions | Partial | UTC dates, `duration`, collection/object helpers, and `file.hasProperty` are available; functions requiring a vault API or a rendered link are not. |
+| Incremental dependency tracking | Supported | Tracks filter candidates and AST-derived property dependencies; dynamic or cyclic formulas fall back per Base. |
+| Regex, object literals, `file()`, link/image/icon/HTML rendering, `now`, `today`, `random`, and relative dates | Unsupported | Static rendering does not execute JavaScript, depend on build time, or emit unsafe URLs. |
+| Editing, group collapse, and other interactive view controls | Out of Scope | Riebeckite renders static build output. |
+
+## Options and exports
+
+`className`, `language`, `limit`, `showFallback`, and `view` retain their existing
+meanings. The package exports `bases`, `basesPlugin`, `remarkBases`, `parseBases`,
+`parseBasesExpression`, `analyzeBasesDependencies`, `evaluateBasesExpression`, `matchesCondition`, and the
+public Bases types.

package/README_ja.md

@@ -2,156 +2,158 @@
 
 <!-- Generated from docs/docs/plugins/bases.ja.md. Edit the canonical documentation in docs/docs/plugins and run `pnpm docs:sync`. -->
 
-フェンスコードブロック `base` に書いた Obsidian Bases 定義を HTML にレンダリングします。フィルタ・ソート・ビューの組み立てはビルド時にコンテンツマニフェストに対して行われるため、クライアントサイド JavaScript は不要です。
+Obsidian Bases の互換サブセットをビルド時に描画します。`bases()` は fenced
+`base` ブロックと、参照された `.base` ドキュメントを扱います。クライアント側の
+評価器は含みません。
 
 [English](./README.md)
 
-## 概要
-
-`bases()` は次のようなフェンスブロックを認識します。
-
-````md
-```base
-filters:
-  and:
-    - file.hasTag("featured")
-properties:
-  file.name:
-    displayName: Title
-  file.tags:
-    displayName: Tags
-views:
-  - type: table
-    name: Featured
-    order:
-      - file.name
-      - file.tags
-    limit: 10
-```
-````
-
-レンダリングにはコンテンツマニフェスト（各ノートの frontmatter・タグ・リンク・パーマリンク）を使います。
-
-## 使い方
+## 設定
 
 ```ts
-import { defineConfig } from "@riebeckite/core";
 import { bases } from "@riebeckite/plugin-bases";
 
-export default defineConfig({
-  // ...
-  plugins: [bases()],
-});
+export default { plugins: [bases()] };
 ```
 
-## ブロックの構文
-
-ブロック本体は Obsidian Base の YAML ドキュメントです。
-
-| フィールド | 型 | 説明 |
-| ---------- | -- | ---- |
-| `filters` | 式 \| リスト \| オブジェクト | 全ビューに適用するトップレベルフィルタ（後述） |
-| `properties` | オブジェクト | プロパティ ID → 表示名（または `{ displayName }`） |
-| `views` | オブジェクト[] | 1 つ以上のビュー |
-
-### ビュー
-
-| フィールド | 型 | 説明 |
-| ---------- | -- | ---- |
-| `type` | `"table"` \| `"cards"` | 出力形式。既定は `table` |
-| `name` | string | ビュー上部に表示する任意のラベル |
-| `filters` | フィルタ | トップレベルフィルタに AND で合成する追加フィルタ |
-| `order` | string \| string[] | 列（プロパティ ID）と表示順 |
-| `columns` | string \| string[] | `order` の別名 |
-| `sort` | オブジェクト \| オブジェクト[] \| string | ソートキー（後述） |
-| `limit` | number | このビューの行数上限。`limit` オプション以下に制限される |
-
-`sort` は Core 形式 `{ field, order }`、Obsidian 形式 `{ property, direction }`、短縮文字列（`"-file.name"` で降順）のいずれかを受け付けます。ビューに `order` / `columns` がない場合、列は `properties` のキー（定義順）、それもなければ `["file.name", "file.tags"]` になります。
+## `.base` ドキュメントと公開範囲
 
-### フィルタの文法
+ルーティング可能な Markdown ノートから `.base` をリンクすると、拡張子を除いた
+パスに PageType ページが作られます。たとえば `![views/Books.base](https://github.com/Rerurate514/riebeckite/blob/main/docs/docs/views/Books.base.ja.md)` は
+`/views/Books` を作ります。既存の PageType API を使うため、独自のルーティングは
+追加しません。
 
-フィルタは式文字列、式のリスト（AND として扱う）、または `and` / `or` / `not` を持つオブジェクトです。`and` と `or` はリストを取り、`not` は式またはリスト（リストは AND でまとめてから否定）を取ります。プロパティ名をキーにした素のオブジェクトは等価比較として扱います。
+ドキュメントページの検出には Core の `publicEntries` を使うため、公開または限定公開
+ノートから参照した Base は明示的に公開できます。Base の行の検索には
+`discoverableEntries` を使います。自動一覧には公開ノートだけが入り、限定公開ノートは
+URL を直接指定した場合だけアクセスできます。下書きと公開予定ノートはいずれからも
+除外します。非公開のコンテンツからしか参照されない Base は公開しません。既存の
+Markdown ページまたは公開リダイレクトと競合した場合はそちらを優先し、Base ページを
+スキップして `bases-invalid` の警告を出します。
 
-| 式 | 説明 |
-| -- | ---- |
-| `file.hasTag("x")` | タグ `x`（またはサブタグ `x/...`）を持つ。大文字小文字は区別しない |
-| `file.inFolder("x")` | スラグが `x` に一致するか `x/` で始まる |
-| `file.hasLink("x")` | `x` へのリンクがある（解決済みスラグ・生のターゲット・ファイル名で照合） |
-| `file.name` / `file.title` | ノートのタイトル |
-| `file.path` / `file.slug` | スラグ |
-| `file.folder` | スラグの親フォルダ |
-| `file.link` / `file.permalink` | パーマリンク |
-| `file.tags` | タグ |
-| `note.key` / `key` | frontmatter の値 |
-
-比較演算子は `==`、`!=`、`>`、`<`、`>=`、`<=`、`contains` です。文字列比較は大文字小文字を区別せず、`contains` は配列の要素または文字列の部分一致を調べます。スカラーのリストは AND として扱います。
+## 例
 
 ```yaml
-filters:
-  and:
-    - file.hasTag("featured")
-    - or:
-        - note.status == "published"
-        - note.status == "review"
-    - not:
-        - file.hasTag("draft")
+filters: note.status == "published" && !file.hasTag("hidden")
+formulas:
+  label: 'note.author.name.upper() + " / " + note.score'
+summaries:
+  total: values.reduce(acc + value, 0)
+properties:
+  file.name: File
+  formula.label: Label
 views:
   - type: table
-    name: Featured
-    order: [file.name, note.status]
-    sort:
-      - property: file.name
-        direction: ASC
-    limit: 20
-```
-
-## オプション
-
-| オプション | 型 | 既定値 | 説明 |
-| ---------- | -- | ------ | ---- |
-| `className` | `string` | `"rb-bases"` | ルート CSS クラス |
-| `language` | `string` | `"base"` | 対象とするフェンス言語 |
-| `limit` | `number` | `100` | 全ビューに適用する行数上限 |
-| `showFallback` | `boolean` | `true` | 生の Base 定義を `<details>` のフォールバックに表示する |
-| `view` | `string` | なし | Base に複数ビューがあるとき、指定名のビューだけをレンダリングする |
-
-## 出力 HTML / CSS フック
-
-```html
-<div class="rb-bases" data-bases data-bases-view="table">
-  <section class="rb-bases__view" data-bases-view="table">
-    <h3 class="rb-bases__view-name">Featured</h3>
-    <table class="rb-bases__table"> ... </table>
-  </section>
-  <details class="rb-bases__fallback"> ... </details>
-</div>
+    name: Books
+    order: [file.name, formula.label]
+    sort: [{ property: formula.label, direction: DESC }]
+    groupBy: { property: note.status, direction: ASC }
+    summaries: { formula.label: total }
+  - type: cards
+    name: Cards
+    order: [file.name, formula.label]
 ```
 
-安定クラス: `rb-bases`、`rb-bases__view`、`rb-bases__view-name`、`rb-bases__table`、`rb-bases__heading`、`rb-bases__cell`、`rb-bases__row`、`rb-bases__link`、`rb-bases__tags`、`rb-bases__tag`、`rb-bases__cards`、`rb-bases__card`、`rb-bases__card-title`、`rb-bases__fields`、`rb-bases__field`、`rb-bases__field-label`、`rb-bases__field-value`、`rb-bases__empty`、`rb-bases__fallback`、`rb-bases--error`。安定属性: `data-bases`、`data-bases-view`。
-
-## 診断
-
-YAML として不正なブロック、未対応のフィルタ式やビュー形状を使ったブロックはコードブロックのまま残し、`source: "@riebeckite/plugin-bases"` を付けて `file.message(...)` で報告します。
-
-## 制限事項
-
-これは Obsidian Bases の MVP サブセットです。
-
-- レンダリングできるのは `table` と `cards` の 2 種類のビューだけです。
-- インラインの論理演算子（`&&`、`||`、`!`）は未対応です。`and` / `or` / `not` の YAML 構造を使ってください。
-- `if()` / `filter()` などの Base フォーミュラ関数は未対応です。
-- ネストしたプロパティパスと `file.mtime` / `file.ctime` は `date` にマップされます。
-- プロパティ同士の比較は未対応で、右辺はリテラルです。
-- 結果はビルド時に確定します。参照先ノートの変更に応じてホストノートだけを再ビルドするのは今後の課題で、フルビルドでは常に正しく再計算されます。
-
-## エクスポート
-
-- `bases(options?)` — プラグインファクトリ（別名: `basesPlugin`）
-- `remarkBases(options?)` — 単体で使える remark トランスフォーム（`options.language` でフェンス言語を選択）
-- `parseBases(document)` — パース済み YAML Base ドキュメントをスペックにコンパイル
-- `matchesCondition(condition, entry)` — 条件評価関数
-- 型: `BasesOptions`、`BasesSpec`、`BasesView`、`BasesViewType`、`BasesCondition`、`BasesValueRef`、`BasesBuiltinValue`、`BasesOperator`、`BasesLiteral`
-
-## 関連
-
-- [プラグインガイド](https://github.com/Rerurate514/riebeckite/blob/main/docs/docs/reference/plugin-api.ja.md)
+同じ YAML を fenced `base` ブロックまたは `.base` ファイルに書けます。トップ
+レベルとビューごとの `filters` は AND で結合します。Table と cards はビルド時に
+描画し、HTML に出す動的な値はすべてエスケープします。
+
+## 公式構文の監査
+
+Obsidian の [Bases 構文](https://help.obsidian.md/bases/syntax) と
+[ビュー](https://help.obsidian.md/bases/views) の YAML 形式を確認し、決定的な静的出力に
+範囲を限定して対応状況を整理しています。
+
+| 構文またはビュー機能 | 状態 | 静的出力での扱い |
+| --- | --- | --- |
+| ルートの `filters`、`formulas`、`properties`、`summaries`、`views` | 対応 | 再帰的な `and`／`or`／`not` filter と `displayName` を受け付けます。 |
+| ビューの `type`、`name`、`limit`、`filters`、`order`、`sort`、`groupBy`、`groupOrder`、`summaries` | 対応 | `groupOrder` は排他的です。空リストはすべてのグループを隠し、存在しない値を列挙すると空グループを作ります。 |
+| Table と cards のレイアウト | 対応 | 実行時の評価器を持たないセマンティック HTML を生成します。 |
+| List、kanban、map のレイアウト | 未対応 | 対話的・空間的な動作はこの静的レンダラーでは表現できません。 |
+| 編集、プロパティメニュー、列幅変更、ドラッグ＆ドロップ、折りたたみ操作 | 対象外 | Bases はサイトのビルド時に描画します。 |
+
+## 式と Formula のサブセット
+
+式は AST に構文解析して直接評価します。`eval`、`Function`、任意の JavaScript 実行は
+使いません。リテラル、配列、ネストしたメンバー・インデックス参照、`!`、単項 `-`、
+算術、比較、`&&`、`||`、括弧、プロパティ同士の比較、`formula.name` 参照に対応します。
+Formula の循環参照は空の値になります。
+
+対応する関数は `if`、`list`、`length`、`number`、`min`、`max`、`date`、`duration`、
+`isTruthy`、`isType`、`toString`、`escapeHTML`、文字列の `lower`、`upper`、`title`、
+`contains`、`startsWith`、`endsWith`、`trim`、`split`、`replace`、`reverse`、`repeat`、
+`slice`、`isEmpty`、リストの `contains`、`containsAll`、`containsAny`、`join`、`unique`、
+`flat`、`sort`、`reverse`、`slice`、`isEmpty`、`mean`、`sum`、`min`、`max`、`map`、
+`filter`、`reduce`、数値の `round`、`floor`、`ceil`、`abs`、`toFixed`、オブジェクトの
+`isEmpty`、`keys`、`values`、UTC の日付フィールド、`date`、`time`、`format`、
+`file.hasTag`、`file.hasLink`、`file.inFolder`、`file.hasProperty` です。
+
+`date()` は UTC の ISO タイムスタンプ、`YYYY-MM-DD`、有限の epoch ミリ秒値、または
+既存の Date だけを受け付けます。日付フィールドとフォーマットは UTC を使うため、静的
+ビルドでホストのロケールや曖昧な日付構文に依存しません。
+
+Formula の評価は、1回につき AST の 10,000 ステップとネストした式の 128 段階までです。
+いずれかを超えると決定的に停止し、`bases-invalid` 診断を出して Base のエラー表示に
+切り替えます。大きな高階式や深い式によって静的ビルドが無制限に実行されることを防ぎ、
+JavaScript のコールバックは実行しません。
+
+## ファイルメタデータ
+
+`file.size` はソースファイルのバイト数です。`file.mtime` と `file.ctime` は
+ファイルシステムから得る UTC の `Date` 値で、プロパティ、filter、Formula、ソート、
+グループ、集計、高階式で使えます。ソースのメタデータが欠落または不正な場合は、描画後の
+Markdown やビルド時刻から補わず、空の値として扱います。日付どうしの減算はミリ秒になり、
+`"7 days"` のような duration による Date の加減算もできます。
+
+ファイルシステムのコンテンツでは、`file.ctime` に Node の `birthtime` を使います。
+status-change time である `stat.ctime` は使いません。Windows では通常、作成時刻を取得
+できます。Linux のファイルシステムは作成時刻を持たないことがあり、Node が
+ファイルシステム依存の代替値を返すか、利用できる値がない場合があります。移植性が必要な
+Base では空の `file.ctime` を扱ってください。キャッシュした時刻は UTC の瞬間を保ちます。
+
+## 増分ビルド
+
+Bases は、filter、formula、column、sort、group、summary が読むプロパティを永続 Output
+Inventory に記録します。これは fenced Base と参照された各 `.base` ドキュメントに個別に適用されます。
+これらのプロパティ、参照するファイルメタデータ、または公開候補集合が変わった場合だけ、その値を読む Base 出力を
+再生成します。filter 不一致から一致への変更も検出します。本文だけの編集と無関係な frontmatter 編集では Base 出力を
+再利用します。
+
+formula の循環、動的なプロパティ参照など、静的に証明できない依存関係では Base 単位で保守的に再生成します。
+不明な依存関係を依存なしとして扱うことはありません。draft、scheduled、unlisted のエントリは Base の行から除外され、
+キャッシュ出力からも公開されません。
+
+## 静的ビューのアクセシビリティ
+
+Table は列と行グループの見出しを維持し、画面読み上げ用の件数を持ちます。狭い画面では
+キーボードでフォーカスできる横スクロール領域に収めます。グループ名には行数を示し、
+`groupOrder` にあるが一致する行がない値は空グループとして明示します。Card のグループは
+ラベル付きリストとし、集計値には画面読み上げ用の列名を加えます。いずれも JavaScript を
+使わない静的出力のままです。
+
+## 互換性マトリクス
+
+| Obsidian Base の機能 | 状態 | 備考 |
+| --- | --- | --- |
+| YAML ルート、`filters`、`properties`、`formulas`、`summaries`、`views` | 対応 | YAML または仕様が不正な場合は診断を出します。 |
+| Table と cards | 対応 | ほかのビュー種別は描画しません。 |
+| AST の filter と Formula | 一部対応 | 対応関数は上記のとおりです。 |
+| Formula によるソートと複数の安定ソートキー | 対応 | 空の値は末尾に並びます。 |
+| `groupBy` と `groupOrder` | 対応 | Formula プロパティ、順序付きの空グループ、Table、cards に対応します。対話的な折りたたみは対象外です。 |
+| Table の集計 | 一部対応 | 名前付き集計、Empty、Filled、Unique、Checked、Unchecked、数値、日付の集計を使えます。 |
+| Cards の集計 | 対象外 | Obsidian は集計を cards ではなく Table に表示します。 |
+| `file.name`、`file.path`、`file.ext`、`file.folder`、`file.tags`、`file.links`、`file.properties`、`file.link` | 一部対応 | Markdown マニフェストから導出します。name/path は `.md` のソース規則を使います。 |
+| `file.size`、`file.mtime`、`file.ctime` | 対応 | バイト数、ファイルシステムの更新時刻、作成時刻相当を使います。Linux では `ctime` が利用できないことがあります。`stat.ctime`、frontmatter、ビルド時刻へは置き換えません。 |
+| Backlinks、embeds | 未対応 | これらの値は空になります。 |
+| リストの `map`、`filter`、`reduce` | 一部対応 | `value`、`index`、`acc` スコープの式を使い、リスト長には上限があります。 |
+| 決定的な utility、object、date、file-property 関数 | 一部対応 | UTC 日付、`duration`、コレクション／object ヘルパー、`file.hasProperty` を使えます。Vault API や描画済みリンクを必要とする関数は使えません。 |
+| 増分依存追跡 | 対応 | filter 候補集合と AST から得たプロパティ依存を追跡し、動的・循環 formula は Base 単位でフォールバックします。 |
+| 正規表現、オブジェクトリテラル、`file()`、link/image/icon/HTML の描画、`now`、`today`、`random`、相対日付 | 未対応 | JavaScript を実行せず、ビルド時刻に依存せず、安全でない URL を出力しません。 |
+| 編集、グループの折りたたみなどの対話的なビュー操作 | 対象外 | Riebeckite は静的なビルド出力を描画します。 |
+
+## オプションとエクスポート
+
+`className`、`language`、`limit`、`showFallback`、`view` の意味は従来どおりです。
+パッケージは `bases`、`basesPlugin`、`remarkBases`、`parseBases`、
+`parseBasesExpression`、`analyzeBasesDependencies`、`evaluateBasesExpression`、`matchesCondition`、公開 Bases 型を
+エクスポートします。