@quartz-community/bases-page 0.2.0

package/dist/registry.d.ts

@@ -0,0 +1,48 @@
+import { ViewRenderer, ViewTypeRegistration } from './types.js';
+import 'preact';
+import '@quartz-community/types';
+
+/**
+ * Central registry for Bases view types.
+ *
+ * Built-in views (table, list, cards, gallery, board) are registered at plugin
+ * init time. Community plugins can register additional view types by importing
+ * this singleton and calling {@link viewRegistry.register}.
+ *
+ * @example Community plugin registering a custom view:
+ * ```ts
+ * import { viewRegistry } from "@quartz-community/bases-page";
+ *
+ * viewRegistry.register({
+ *   id: "timeline",
+ *   name: "Timeline",
+ *   icon: "git-branch",
+ *   render: ({ entries, view }) => <div class="bases-timeline">...</div>,
+ * });
+ * ```
+ */
+declare class ViewRegistry {
+    private views;
+    /**
+     * 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: ViewTypeRegistration): void;
+    /** Look up a registered view type by ID. */
+    get(id: string): ViewTypeRegistration | undefined;
+    /** Return all registered view types (insertion order). */
+    getAll(): ViewTypeRegistration[];
+    /** Check whether a view type is registered. */
+    has(id: string): boolean;
+    /** Remove a view type registration. Returns true if it existed. */
+    unregister(id: string): boolean;
+}
+declare const viewRegistry: ViewRegistry;
+/**
+ * Convenience: bulk-register views from a `customViews` config record.
+ * Called during plugin init to merge user-provided renderers into the registry.
+ */
+declare function registerCustomViews(customs: Record<string, ViewRenderer>): void;
+
+export { registerCustomViews, viewRegistry };

package/dist/registry.js

@@ -0,0 +1,7 @@
+import { createRequire } from 'module';
+export { registerCustomViews, viewRegistry } from './chunk-2AUMER56.js';
+import './chunk-TDUJOYTU.js';
+
+createRequire(import.meta.url);
+//# sourceMappingURL=registry.js.map
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"registry.js"}

package/dist/types.d.ts

@@ -0,0 +1,181 @@
+import { ComponentChild } from 'preact';
+export { BuildCtx, FilePath, FullSlug, GlobalConfiguration, PageGenerator, PageMatcher, ProcessedContent, QuartzComponent, QuartzComponentConstructor, QuartzComponentProps, QuartzPageTypePlugin, QuartzPageTypePluginInstance, QuartzPluginData, VirtualPage } from '@quartz-community/types';
+
+/** Props passed to every view renderer */
+interface ViewRendererProps {
+    entries: BasesEntry[];
+    view: BasesView;
+    basesData: BasesData;
+    total: number;
+    locale: string;
+    /** Slug of the page rendering this view (for resolving relative paths) */
+    slug: string;
+    /** All known slugs in the site (for `transformLink` with `shortest` strategy) */
+    allSlugs: string[];
+    /** Link resolution strategy ("absolute" | "relative" | "shortest"). Passed from plugin options. */
+    linkResolution: "absolute" | "relative" | "shortest";
+    /** Plugin-level options from the view type registration, if any. */
+    options?: Record<string, unknown>;
+}
+/** View renderer function signature */
+type ViewRenderer = (props: ViewRendererProps) => ComponentChild;
+/** Registration record for a view type */
+interface ViewTypeRegistration {
+    /** Unique view type identifier, e.g. "table", "board", "my-custom-view" */
+    id: string;
+    /** Human-readable display name shown in the view selector */
+    name: string;
+    /** Optional Lucide icon name */
+    icon?: string;
+    /** The render function producing Preact JSX */
+    render: ViewRenderer;
+    /**
+     * Optional CSS string injected once per page when this view type is active.
+     * Deduplicated by view type ID — only injected once even if multiple views
+     * of the same type appear on the page.
+     */
+    css?: string;
+    /**
+     * Optional client-side script injected once per page when this view type is
+     * active. Runs after the DOM is loaded, following the same lifecycle as
+     * `QuartzComponent.afterDOMLoaded`. Deduplicated by view type ID.
+     */
+    afterDOMLoaded?: string;
+    /**
+     * Optional user-supplied configuration for this view type. Community plugins
+     * can use this to accept plugin-level options (e.g. feature flags, CDN URLs)
+     * that are set once at registration time and passed through to every render
+     * invocation via `ViewRendererProps.options`.
+     */
+    options?: Record<string, unknown>;
+}
+/** Plugin options for BasesPage */
+interface BasesPageOptions {
+    /** Default view type when none specified. Default: "table" */
+    defaultViewType?: string;
+    /**
+     * Custom view renderers passed via TS config override.
+     * Keys are view type IDs. These are registered into the ViewRegistry
+     * at plugin init time, alongside (or overriding) built-in views.
+     */
+    customViews?: Record<string, ViewRenderer>;
+    /**
+     * How to resolve internal links in view renderers. Should match the
+     * `markdownLinkResolution` setting of the crawl-links plugin.
+     * Default: "shortest"
+     */
+    linkResolution?: "absolute" | "relative" | "shortest";
+}
+/** Sort direction */
+type SortDirection = "ASC" | "DESC";
+/** Sort entry — one column + direction pair */
+interface SortEntry {
+    property: string;
+    direction?: SortDirection;
+}
+/** Filter tree node — recursive and/or/not structure matching Obsidian spec */
+type FilterNode = string | {
+    and: FilterNode[];
+} | {
+    or: FilterNode[];
+} | {
+    not: FilterNode[];
+};
+/** Group-by configuration */
+interface GroupBy {
+    property: string;
+    direction?: SortDirection;
+}
+/** Summary type — built-in aggregation functions + extensible string for custom */
+type SummaryType = "Count" | "Average" | "Min" | "Max" | "Sum" | "Range" | "Median" | "Stddev" | "Earliest" | "Latest" | "Checked" | "Unchecked" | "Empty" | "Filled" | "Unique" | string;
+/** Property display configuration */
+interface PropertyConfig {
+    displayName?: string;
+}
+/** View definition from .base file YAML — matches full Obsidian spec */
+interface BasesView {
+    /** View type identifier */
+    type: string;
+    /** Display name for this view (shown in view selector tab) */
+    name?: string;
+    /** Maximum number of entries to display */
+    limit?: number;
+    /** Group entries by a property */
+    groupBy?: GroupBy;
+    /** View-specific filters (merged with global filters at resolve time) */
+    filters?: FilterNode;
+    /** Sort order — list of property paths in priority order */
+    order?: string[];
+    /** Multi-key sort with explicit direction per column */
+    sort?: SortEntry[];
+    /** Per-property summary aggregations */
+    summaries?: Record<string, SummaryType>;
+    /** Column widths in pixels, keyed by property path */
+    columnSize?: Record<string, number>;
+    /** Row height in pixels */
+    rowHeight?: number;
+    /** Property name containing the image URL/path */
+    image?: string;
+    /** Card width (unitless ratio or pixels depending on renderer) */
+    cardSize?: number;
+    /** Image aspect ratio (width:height, e.g. 1 for square). Obsidian spec field. */
+    imageAspectRatio?: number;
+    /** Image fit mode: "cover" (crop to fill) or "contain" (scale to fit). Default: "cover". */
+    imageFit?: "cover" | "contain";
+    /**
+     * @deprecated Use imageAspectRatio instead. Kept for backwards compatibility.
+     */
+    cardAspect?: number;
+    /** Property path for the date field */
+    date?: string;
+    /** Alias for date */
+    dateField?: string;
+    /** Alias for date */
+    dateProperty?: string;
+    /** Property to group board columns by (if not using groupBy) */
+    boardProperty?: string;
+    /** Escape hatch for future/unknown view-specific fields */
+    [key: string]: unknown;
+}
+/** Parsed .base file data — top-level YAML structure */
+interface BasesData {
+    /** Global filters applied to all views */
+    filters?: FilterNode;
+    /** Formula definitions — keys are formula names, values are expressions */
+    formulas?: Record<string, string>;
+    /** Property display configuration */
+    properties?: Record<string, PropertyConfig>;
+    /** Global summary configuration */
+    summaries?: Record<string, string>;
+    /** View definitions — each entry defines one tab/view */
+    views?: BasesView[];
+}
+/** Resolved entry — a single note that matched the base query */
+interface BasesEntry {
+    /** The note's slug (URL path) */
+    slug: string;
+    /** Display title */
+    title: string;
+    /** All frontmatter properties (raw) */
+    properties: Record<string, unknown>;
+    /** File metadata properties */
+    fileProperties: {
+        name: string;
+        basename: string;
+        path: string;
+        folder: string;
+        ext: string;
+        tags: string[];
+        links: string[];
+        embeds?: string[];
+        created?: string | Date;
+        modified?: string | Date;
+        ctime?: Date;
+        mtime?: Date;
+        size?: number;
+    };
+    /** Computed formula values */
+    formulaValues: Record<string, unknown>;
+}
+
+export type { BasesData, BasesEntry, BasesPageOptions, BasesView, FilterNode, GroupBy, PropertyConfig, SortDirection, SortEntry, SummaryType, ViewRenderer, ViewRendererProps, ViewTypeRegistration };

package/dist/types.js

@@ -0,0 +1,5 @@
+import { createRequire } from 'module';
+
+createRequire(import.meta.url);
+//# sourceMappingURL=types.js.map
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"types.js"}

package/package.json

@@ -0,0 +1,143 @@
+{
+  "name": "@quartz-community/bases-page",
+  "version": "0.2.0",
+  "description": "Obsidian Bases page type plugin for Quartz v5. Renders database-like filtered views of notes from .base files.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Quartz Community",
+  "homepage": "https://quartz.jzhao.xyz",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quartz-community/bases-page"
+  },
+  "keywords": [
+    "quartz",
+    "quartz-plugin",
+    "obsidian",
+    "bases",
+    "database",
+    "page-type"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components/index.js"
+    },
+    "./registry": {
+      "types": "./dist/registry.d.ts",
+      "import": "./dist/registry.js"
+    },
+    "./compiler": {
+      "types": "./dist/compiler/index.d.ts",
+      "import": "./dist/compiler/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint . --max-warnings=0",
+    "format": "prettier . --check",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm run lint && npm run format && npm run test",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@jackyzha0/quartz": "^5.0.0",
+    "preact": "^10.0.0",
+    "vfile": "^6.0.3"
+  },
+  "peerDependenciesMeta": {
+    "@jackyzha0/quartz": {
+      "optional": true
+    },
+    "preact": {
+      "optional": false
+    },
+    "vfile": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@quartz-community/types": "^0.2.1",
+    "@quartz-community/utils": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/hast": "^3.0.4",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^24.10.0",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "github-slugger": "^2.0.0",
+    "hast-util-from-html": "^2.0.3",
+    "hast-util-to-jsx-runtime": "^2.3.6",
+    "preact": "^10.28.2",
+    "preact-render-to-string": "^6.6.6",
+    "prettier": "^3.6.2",
+    "sass": "^1.97.3",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "unist-util-visit": "^5.1.0",
+    "vfile": "^6.0.3",
+    "vitest": "^2.1.9",
+    "yaml": "^2.8.1"
+  },
+  "quartz": {
+    "name": "bases-page",
+    "displayName": "Bases Page",
+    "category": [
+      "transformer",
+      "pageType",
+      "component"
+    ],
+    "version": "1.0.0",
+    "quartzVersion": ">=5.0.0",
+    "dependencies": [],
+    "defaultOrder": 50,
+    "defaultEnabled": true,
+    "defaultOptions": {
+      "defaultViewType": "table",
+      "linkResolution": "shortest"
+    },
+    "optionSchema": {
+      "defaultViewType": {
+        "type": "string"
+      },
+      "linkResolution": {
+        "type": "enum",
+        "values": [
+          "absolute",
+          "relative",
+          "shortest"
+        ]
+      }
+    }
+  },
+  "engines": {
+    "node": ">=22",
+    "npm": ">=10.9.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}