@quartz-community/bases-page 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `options` field on `ViewTypeRegistration` — community plugins can pass user-supplied configuration (e.g. feature flags) that gets forwarded to every render invocation via `ViewRendererProps.options`.
+- `options` field on `ViewRendererProps` — view renderers receive registration-time options as `Record<string, unknown>`.
+- `slug`, `allSlugs`, and `linkResolution` fields on `ViewRendererProps` — view renderers can now resolve internal links correctly.
+- `css` and `afterDOMLoaded` fields on `ViewTypeRegistration` — community view types can inject per-page styles and client-side scripts.
+- `linkResolution` plugin option (`"absolute" | "relative" | "shortest"`) — controls how internal links are resolved in view renderers, matching the crawl-links plugin setting.
+
+### Fixed
+
+- Added `yaml` and `unist-util-visit` to devDependencies (were listed as peer dependencies but missing from devDependencies, causing `tsc --noEmit` failures).
+- Respect the `file.data.unlisted` convention in `resolveBasesEntries`. Pages marked `unlisted: true` are now excluded from every rendered base view (table, list, board, cards, gallery, and any custom view registered via `viewRegistry`), regardless of whether the base's filter expression would otherwise match them. Fixes a privacy leak where encrypted-unlisted and plain-unlisted pages showed up in base views built from queries like `file.ext == "md"` that matched the entire content directory. Both the main entry loop and the internal `fileLookup` used by `.asFile()` method resolution are filtered, so unlisted pages also cannot be dereferenced from formulas on visible pages. The convention is the same one respected by `content-index`, `search`, `backlinks`, `recent-notes`, `folder-page`, and `tag-page`, and is written by `@quartz-community/unlisted-pages` and `@quartz-community/encrypted-pages` (when `unlistWhenEncrypted` or per-page `unlisted: true`/`stealth: true` is set).
+
+## [0.2.0]
+
+### Added
+
+- Initial Quartz community plugin template.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quartz Community
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,315 @@
+# @quartz-community/bases-page
+
+A page type and component plugin for Quartz v5 that renders Obsidian Bases (.base files) as database-like filtered views. This plugin (v0.2.0) provides a powerful way to visualize and interact with your Obsidian data in a structured format.
+
+## Installation
+
+```bash
+npx quartz plugin add github:quartz-community/bases-page
+```
+
+## Usage
+
+Enable the plugin in your Quartz configuration:
+
+```yaml title="quartz.config.yaml"
+plugins:
+  - source: github:quartz-community/bases-page
+    enabled: true
+```
+
+## Interaction with `unlisted` pages
+
+`bases-page` respects the `file.data.unlisted` convention. Pages marked `unlisted: true` (by `@quartz-community/unlisted-pages`, or by `@quartz-community/encrypted-pages` via `unlistWhenEncrypted: true` or per-page `unlisted: true` / `stealth: true`) are excluded from every rendered base view — table, list, board, cards, gallery, and any custom view registered via `viewRegistry`. Both the main entry loop and the internal `fileLookup` used by `.asFile()` method resolution skip unlisted pages, so they cannot be dereferenced from formulas on visible pages either.
+
+> [!note]
+> Base views are **server-side rendered** HTML baked at build time. They do not update client-side after a visitor successfully decrypts an encrypted page. Graph, explorer, and search all re-hydrate from the patched in-memory content index after decryption and show newly-unlocked pages for the rest of the browser session — base views do not, because they were materialized at build time with unlisted pages already excluded. A visitor who decrypts a revealable encrypted page will see it appear in graph, explorer, and search, but **not** in any base view on the site, until the site is rebuilt with that page listed. This is the same structural limitation that applies to backlinks, recent notes, folder listings, and tag listings.
+
+### TypeScript Override
+
+For advanced use cases (e.g. custom view renderers), you can override in TypeScript:
+
+```ts title="quartz.ts (override)"
+import * as ExternalPlugin from "./.quartz/plugins";
+
+ExternalPlugin.BasesPage({
+  defaultViewType: "table",
+  linkResolution: "shortest",
+  customViews: {
+    myView: ({
+      entries,
+      view,
+      basesData,
+      total,
+      locale,
+      slug,
+      allSlugs,
+      linkResolution,
+      options,
+    }) => {
+      // return JSX
+    },
+  },
+});
+```
+
+## Built-in Views
+
+- **Table**: Sortable columns with automatic type rendering for strings, numbers, booleans, arrays, and links. Supports custom column widths and row heights.
+- **List**: A compact list view displaying metadata chips for each entry.
+- **Cards**: A card-based layout with support for an optional image property and configurable card size or aspect ratio.
+- **Gallery**: An image-focused grid layout designed for visual content with configurable card sizes.
+- **Board**: A Kanban-style board that groups entries by a specific property (using boardProperty or groupBy), creating columns for each group value.
+
+## Features
+
+- Multiple views per .base file (switchable tabs)
+- Recursive filter trees (and/or/not)
+- Formulas (computed properties via expression engine)
+- Summaries (column aggregations: Count, Average, Min, Max, Sum, Range, Median, Stddev, Earliest, Latest, Checked, Unchecked, Empty, Filled, Unique)
+- Property display configuration
+- Wikilink and Markdown link rendering
+- Sort and grouping
+
+## Expression Engine
+
+The expression engine follows a pipeline of source, lexer, Pratt parser, AST, bytecode compiler, and stack interpreter.
+
+### Supported Types
+
+- Strings
+- Numbers
+- Booleans
+- Null
+- Lists
+
+### Operators
+
+- **Arithmetic**: +, -, \*, /
+- **Comparison**: ==, !=, >, <, >=, <=
+- **Logical**: and / &&, or / ||, not / !
+
+### Property Access
+
+- `note.property`: Access a property on the current note.
+- `file.name`: The name of the file.
+- `file.path`: The full path of the file.
+- `file.folder`: The folder containing the file.
+- `file.ext`: The file extension.
+- `file.tags`: A list of tags associated with the file.
+- `file.links`: A list of links in the file.
+- `file.created`: The creation date of the file.
+- `file.modified`: The last modification date of the file.
+- `formula.name`: Access the result of another formula.
+
+### Built-in Global Functions
+
+- `if(condition, then, else)`
+- `contains(container, item)`
+- `date(string)`
+- `duration(string)`
+- `now()`
+- `today()`
+- `number(value)`
+- `min(a, b, ...)`
+- `max(a, b, ...)`
+- `list(value)`
+- `link(path, display?)`
+- `image(url)`
+- `icon(name)`
+- `html(string)`
+- `escapeHTML(string)`
+- `file(path)`
+
+### Method Functions
+
+**Strings**
+
+- `contains(substring)`
+- `startsWith(prefix)`
+- `endsWith(suffix)`
+- `lower()`
+- `upper()`
+- `trim()`
+- `replace(pattern, replacement)`
+- `slice(start, end?)`
+- `isEmpty()`
+- `repeat(count)`
+- `reverse()`
+
+**Numbers**
+
+- `toFixed(digits)`
+- `round()`
+- `floor()`
+- `ceil()`
+- `abs()`
+
+**Dates**
+
+- `format(formatString)`
+- `year()`
+- `month()`
+- `day()`
+- `time()`
+- `relative()`
+- `isEmpty()`
+
+**Lists**
+
+- `sum()`
+- `mean()`
+- `count()`
+- `min()`
+- `max()`
+- `round()`
+
+**File**
+
+- `hasTag(tag)`
+- `hasLink(link)`
+- `inFolder(folder)`
+- `hasProperty(property)`
+
+## Extending with Custom Views
+
+Community extensions can register custom view types using the view registry.
+
+### Registering a View
+
+```typescript
+import { viewRegistry } from "@quartz-community/bases-page/registry";
+
+viewRegistry.register({
+  id: "my-custom-view",
+  name: "My Custom View",
+  icon: "star",
+  render: (props) => {
+    const { entries, view, basesData, total, locale, slug, allSlugs, linkResolution, options } =
+      props;
+    // Return your React/Preact component
+  },
+  css: `.my-custom-view { color: red; }`,
+  afterDOMLoaded: `console.log("My custom view loaded");`,
+  options: { enableFeatureX: true },
+});
+```
+
+### Interfaces
+
+**ViewTypeRegistration**
+
+```typescript
+interface ViewTypeRegistration {
+  id: string;
+  name: string;
+  icon?: string;
+  render: ViewRenderer;
+  css?: string;
+  afterDOMLoaded?: string;
+  options?: Record<string, unknown>;
+}
+```
+
+**ViewRendererProps**
+
+```typescript
+interface ViewRendererProps {
+  entries: BasesEntry[];
+  view: BasesView;
+  basesData: BasesData;
+  total: number;
+  locale: string;
+  slug: string;
+  allSlugs: string[];
+  linkResolution: "absolute" | "relative" | "shortest";
+  options?: Record<string, unknown>;
+}
+```
+
+### Passing Options to a Custom View
+
+Community plugins can use the `options` field to accept configuration at registration time. This is useful for feature flags, API keys, or other plugin-level settings.
+
+```typescript
+import { viewRegistry } from "@quartz-community/bases-page/registry";
+import type { LeafletMapPluginOptions } from "./types";
+
+const defaultOptions: LeafletMapPluginOptions = {
+  enableCopyTool: false,
+};
+
+export function registerLeafletMap(userOpts?: Partial<LeafletMapPluginOptions>): void {
+  const opts = { ...defaultOptions, ...userOpts };
+  viewRegistry.register({
+    ...leafletMapViewRegistration,
+    options: opts,
+  });
+}
+```
+
+In the renderer, these options are available via `props.options` and should be cast to the plugin's options type.
+
+## Compiler API
+
+The expression engine is available as a public API for advanced usage. Import from `@quartz-community/bases-page/compiler`.
+
+```typescript
+import {
+  compile,
+  evaluate,
+  evaluateFilter,
+  resolvePropertyValue,
+} from "@quartz-community/bases-page/compiler";
+
+// Compile an expression to bytecode
+const compiled = compile("note.price * 1.2");
+
+// Evaluate an expression in a context
+const result = evaluate("note.price * 1.2", context);
+
+// Evaluate a filter node
+const isMatch = evaluateFilter(filterNode, context);
+
+// Resolve a property path
+const value = resolvePropertyValue("file.name", context);
+```
+
+### EvalContext Shape
+
+```typescript
+interface EvalContext {
+  note: Record<string, unknown>;
+  file: {
+    name: string;
+    path: string;
+    folder: string;
+    ext: string;
+    tags: string[];
+    links: string[];
+    created?: string;
+    modified?: string;
+  };
+  formula: Record<string, unknown>;
+}
+```
+
+## Package Exports
+
+- `.`: Main plugin entry (BasesPage, BasesBody, viewRegistry, registerCustomViews, compiler API, types)
+- `./types`: All type definitions
+- `./components`: React/Preact components (BasesBody, ViewSelector)
+- `./registry`: View registry singleton and registerCustomViews helper
+- `./compiler`: Expression engine (compile, evaluate, evaluateFilter, resolvePropertyValue)
+
+## Configuration Options
+
+| Option            | Type                                     | Default      | Description                                                                                    |
+| :---------------- | :--------------------------------------- | :----------- | :--------------------------------------------------------------------------------------------- |
+| `defaultViewType` | `string`                                 | `"table"`    | The default view type used when none is specified in the .base file.                           |
+| `linkResolution`  | `"absolute" \| "relative" \| "shortest"` | `"shortest"` | How to resolve internal links in view renderers. Should match your crawl-links plugin setting. |
+| `customViews`     | `Record<string, ViewRenderer>`           | `{}`         | Custom view renderers provided via TypeScript override.                                        |
+
+## License
+
+MIT

package/dist/BasesBody-B4CEJjEp.d.ts

@@ -0,0 +1,6 @@
+import { QuartzComponent } from '@quartz-community/types';
+import { BasesPageOptions } from './types.js';
+
+declare const _default: (opts?: BasesPageOptions) => QuartzComponent;
+
+export { _default as _ };

package/dist/chunk-2AUMER56.js

@@ -0,0 +1,44 @@
+import { createRequire } from 'module';
+
+createRequire(import.meta.url);
+
+// src/registry.ts
+var REGISTRY_KEY = /* @__PURE__ */ Symbol.for("@quartz-community/bases-page/viewRegistry");
+var ViewRegistry = class {
+  views = /* @__PURE__ */ new Map();
+  /**
+   * Register a view type. If a view with the same ID already exists it is
+   * silently replaced — this lets config-level `customViews` override built-in
+   * renderers for the same type.
+   */
+  register(registration) {
+    this.views.set(registration.id, registration);
+  }
+  /** Look up a registered view type by ID. */
+  get(id) {
+    return this.views.get(id);
+  }
+  /** Return all registered view types (insertion order). */
+  getAll() {
+    return Array.from(this.views.values());
+  }
+  /** Check whether a view type is registered. */
+  has(id) {
+    return this.views.has(id);
+  }
+  /** Remove a view type registration. Returns true if it existed. */
+  unregister(id) {
+    return this.views.delete(id);
+  }
+};
+var g = globalThis;
+var viewRegistry = g[REGISTRY_KEY] ??= new ViewRegistry();
+function registerCustomViews(customs) {
+  for (const [id, render] of Object.entries(customs)) {
+    viewRegistry.register({ id, name: id, render });
+  }
+}
+
+export { registerCustomViews, viewRegistry };
+//# sourceMappingURL=chunk-2AUMER56.js.map
+//# sourceMappingURL=chunk-2AUMER56.js.map

package/dist/chunk-2AUMER56.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/registry.ts"],"names":[],"mappings":";;;;;AAWA,IAAM,YAAA,mBAAe,MAAA,CAAO,GAAA,CAAI,2CAA2C,CAAA;AAqB3E,IAAM,eAAN,MAAmB;AAAA,EACT,KAAA,uBAAY,GAAA,EAAkC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOtD,SAAS,YAAA,EAA0C;AACjD,IAAA,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,YAAA,CAAa,EAAA,EAAI,YAAY,CAAA;AAAA,EAC9C;AAAA;AAAA,EAGA,IAAI,EAAA,EAA8C;AAChD,IAAA,OAAO,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,EAAE,CAAA;AAAA,EAC1B;AAAA;AAAA,EAGA,MAAA,GAAiC;AAC/B,IAAA,OAAO,KAAA,CAAM,IAAA,CAAK,IAAA,CAAK,KAAA,CAAM,QAAQ,CAAA;AAAA,EACvC;AAAA;AAAA,EAGA,IAAI,EAAA,EAAqB;AACvB,IAAA,OAAO,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,EAAE,CAAA;AAAA,EAC1B;AAAA;AAAA,EAGA,WAAW,EAAA,EAAqB;AAC9B,IAAA,OAAO,IAAA,CAAK,KAAA,CAAM,MAAA,CAAO,EAAE,CAAA;AAAA,EAC7B;AACF,CAAA;AASA,IAAM,CAAA,GAAI,UAAA;AACH,IAAM,YAAA,GAA8B,CAAA,CAAE,YAAY,CAAA,KAAM,IAAI,YAAA;AAM5D,SAAS,oBAAoB,OAAA,EAA6C;AAC/E,EAAA,KAAA,MAAW,CAAC,EAAA,EAAI,MAAM,KAAK,MAAA,CAAO,OAAA,CAAQ,OAAO,CAAA,EAAG;AAClD,IAAA,YAAA,CAAa,SAAS,EAAE,EAAA,EAAI,IAAA,EAAM,EAAA,EAAI,QAAQ,CAAA;AAAA,EAChD;AACF","file":"chunk-2AUMER56.js","sourcesContent":["import type { ViewTypeRegistration, ViewRenderer } from \"./types\";\n\n/**\n * Symbol key for the global ViewRegistry singleton.\n *\n * Using a well-known Symbol on `globalThis` guarantees that all copies of this\n * module — whether loaded from different `node_modules` paths or from different\n * tsup entry points — share the exact same registry instance. Without this,\n * community plugins that bundle or install their own copy of bases-page would\n * register views into a private registry that the main bases-page never sees.\n */\nconst REGISTRY_KEY = Symbol.for(\"@quartz-community/bases-page/viewRegistry\");\n\n/**\n * Central registry for Bases view types.\n *\n * Built-in views (table, list, cards, gallery, board) are registered at plugin\n * init time. Community plugins can register additional view types by importing\n * this singleton and calling {@link viewRegistry.register}.\n *\n * @example Community plugin registering a custom view:\n * ```ts\n * import { viewRegistry } from \"@quartz-community/bases-page\";\n *\n * viewRegistry.register({\n *   id: \"timeline\",\n *   name: \"Timeline\",\n *   icon: \"git-branch\",\n *   render: ({ entries, view }) => <div class=\"bases-timeline\">...</div>,\n * });\n * ```\n */\nclass ViewRegistry {\n  private views = new Map<string, ViewTypeRegistration>();\n\n  /**\n   * Register a view type. If a view with the same ID already exists it is\n   * silently replaced — this lets config-level `customViews` override built-in\n   * renderers for the same type.\n   */\n  register(registration: ViewTypeRegistration): void {\n    this.views.set(registration.id, registration);\n  }\n\n  /** Look up a registered view type by ID. */\n  get(id: string): ViewTypeRegistration | undefined {\n    return this.views.get(id);\n  }\n\n  /** Return all registered view types (insertion order). */\n  getAll(): ViewTypeRegistration[] {\n    return Array.from(this.views.values());\n  }\n\n  /** Check whether a view type is registered. */\n  has(id: string): boolean {\n    return this.views.has(id);\n  }\n\n  /** Remove a view type registration. Returns true if it existed. */\n  unregister(id: string): boolean {\n    return this.views.delete(id);\n  }\n}\n\n/**\n * Singleton view registry instance, stored on `globalThis` via a well-known\n * Symbol so that all copies of this module share the same instance.\n *\n * Community plugins import this to register custom view types.\n * Built-in views are registered by `registerBuiltinViews()` during plugin init.\n */\nconst g = globalThis as unknown as Record<symbol, ViewRegistry>;\nexport const viewRegistry: ViewRegistry = (g[REGISTRY_KEY] ??= new ViewRegistry());\n\n/**\n * Convenience: bulk-register views from a `customViews` config record.\n * Called during plugin init to merge user-provided renderers into the registry.\n */\nexport function registerCustomViews(customs: Record<string, ViewRenderer>): void {\n  for (const [id, render] of Object.entries(customs)) {\n    viewRegistry.register({ id, name: id, render });\n  }\n}\n"]}