@lapis-notes/bases 0.1.0

package/dist/bases-view/bases.svelte.d.ts

@@ -0,0 +1,569 @@
+import { BasesViewConfig as SharedBasesViewConfig, Component, TFile, type App, type BasesAllOptions } from "@lapis-notes/api";
+import { DateTime, Duration } from "luxon";
+import { Context, Decimal, type DType } from "peaql";
+import { type BasesDocument, type BasesViewBase } from "./models";
+import { type ColumnDefinition } from "./columns";
+import type { VaultRecord } from ".";
+export { BasesViewConfig } from "@lapis-notes/api";
+/**
+ * The three valid "sources" of a property in a Base.
+ *
+ * - `note`: Properties from the frontmatter of markdown files in the vault.
+ * - `formula`: Properties calculated by evaluating a formula from the base config
+ *   file.
+ * - `file`: Properties inherent to a file, such as the name, extension, size,
+ *   etc.
+ *
+ * @since 1.10.0
+ * @public
+ */
+export type BasesPropertyType = "note" | "formula" | "file";
+/**
+ * The full ID of a property, used in the bases config file. The prefixed
+ * {@link BasesPropertyType} disambiguates properties of the same name but from
+ * different sources.
+ *
+ * @since 1.10.0
+ * @public
+ */
+export type BasesPropertyId = string | `${BasesPropertyType}.${string}`;
+/**
+ * A parsed version of the {@link BasesPropertyId}.
+ *
+ * @since 1.10.0
+ * @public
+ */
+export interface BasesProperty {
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    type: BasesPropertyType;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    name: string;
+}
+/**
+ * @since 1.10.0
+ * @public
+ */
+export interface BaseOption {
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    key: string;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    type: string;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    displayName: string;
+}
+/**
+ * @since 1.10.0
+ * @public
+ */
+export type BasesSortConfig = {
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    property: BasesPropertyId;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    direction: "ASC" | "DESC";
+};
+/**
+ * The context in which a formula is evaluated. In most cases, {@link BasesEntry}
+ * is the specific type to use.
+ *
+ * @since 1.10.0
+ * @public
+ */
+export interface FormulaContext {
+}
+/**
+ * Represent a single "row" or file in a base.
+ *
+ * @since 1.10.0
+ * @public
+ */
+export declare class BasesEntry implements FormulaContext {
+    readonly id: string;
+    readonly file: TFile;
+    readonly context: Partial<Record<BasesPropertyId, Value>>;
+    constructor(id: string, file: TFile, context?: Partial<Record<BasesPropertyId, Value>>);
+    /**
+     * Get the value of the property.
+     *
+     * @since 1.10.0
+     * @throws Error if the property is a formula and cannot be evaluated.
+     * @public
+     */
+    getValue(propertyId: BasesPropertyId): Value | null;
+}
+/**
+ * Container type for data which can expose functions for retrieving, comparing,
+ * and rendering the data. Most commonly used in conjunction with formulas for
+ * Bases. Values can be used as formula parameters, intermediate values, and the
+ * result of evaluation.
+ *
+ * @since 1.10.0
+ * @public
+ */
+export declare abstract class Value {
+    abstract get value(): any;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    static equals(a: Value | null, b: Value | null): boolean;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    static looseEquals(a: Value | null, b: Value | null): boolean;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    abstract toString(): string;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    abstract isTruthy(): boolean;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    equals(other: this): boolean;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    looseEquals(other: Value): boolean;
+    /**
+     * Render this value into the provided HTMLElement.
+     *
+     * @since 1.10.0
+     * @public
+     */
+    renderTo(el: HTMLElement, ctx: any): void;
+}
+/**
+ * Base type for all non-null {@link Values}.
+ *
+ * @since 1.10.0
+ * @public
+ */
+export declare abstract class NotNullValue extends Value {
+}
+/**
+ * {@link Value} which represents null. NullValue is a singleton and
+ * `NullValue.value` should be used instead of calling the constructor.
+ *
+ * @since 1.10.0
+ * @public
+ */
+export declare class NullValue extends Value {
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    static value: NullValue;
+    get value(): null;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    toString(): string;
+    isTruthy(): boolean;
+    equals(other: this): boolean;
+    looseEquals(other: Value): boolean;
+}
+/**
+ * Base type for {@link Values} which wrap a single primitive.
+ *
+ * @since 1.10.0
+ * @public
+ */
+export declare abstract class PrimitiveValue<T> extends NotNullValue {
+    readonly value: T;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    constructor(value: T);
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    toString(): string;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    isTruthy(): boolean;
+    equals(other: this): boolean;
+    looseEquals(other: Value): boolean;
+}
+/**
+ * {@link Value} wrapping a boolean.
+ *
+ * @since 1.10.0
+ * @public
+ */
+export declare class BooleanValue extends PrimitiveValue<boolean> {
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    static type: string;
+    looseEquals(other: Value): boolean;
+}
+/**
+ * {@link Value} wrapping a number.
+ *
+ * @since 1.10.0
+ * @public
+ */
+export declare class NumberValue extends PrimitiveValue<number | Decimal> {
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    static type: string;
+    equals(other: this): boolean;
+    looseEquals(other: Value): boolean;
+    toString(): string;
+    get number(): number;
+}
+/**
+ * {@link Value} wrapping a string.
+ *
+ * @since 1.10.0
+ * @public
+ */
+export declare class StringValue extends PrimitiveValue<string> {
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    static type: string;
+}
+export declare class DateValue extends NotNullValue {
+    readonly value: DateTime;
+    constructor(value: DateTime | Date | number | string);
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    toString(): string;
+    /**
+     * @since 1.10.0
+     * @returns A new DateValue with any time portion in this DateValue removed.
+     * @public
+     */
+    dateOnly(): DateValue;
+    /**
+     * @since 1.10.0
+     * @returns A new {@link RelativeDateValue} based on this DateValue.
+     * @public
+     */
+    relative(): string;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    isTruthy(): boolean;
+    equals(other: this): boolean;
+    looseEquals(other: Value): boolean;
+    /**
+     * Create new DateValue from an input string.
+     *
+     * @since 1.10.0
+     * @example
+     *   parseFromString("2025-12-31");
+     *   parseFromString("2025-12-31T23:59");
+     *   parseFromString("2025-12-31T23:59:59");
+     *   parseFromString("2025-12-31T23:59:59Z-07");
+     *
+     * @param input - An ISO 8601 date or datetime string.
+     * @public
+     */
+    static parseFromString(input: string): DateValue | null;
+}
+export declare class DurationValue extends NotNullValue {
+    readonly value: Duration;
+    constructor(value: Duration);
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    toString(): string;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    isTruthy(): boolean;
+    /**
+     * Modifies the provided {@DateValue} by this duration.
+     *
+     * @since 1.10.0
+     * @public
+     */
+    addToDate(value: DateValue, subtract?: boolean): DateValue;
+    /**
+     * Convert this duration into milliseconds.
+     *
+     * @since 1.10.0
+     * @public
+     */
+    getMilliseconds(): number;
+    equals(other: this): boolean;
+    looseEquals(other: Value): boolean;
+    /**
+     * Create a new DurationValue using an ISO 8601 duration. See
+     * {@link https://en.wikipedia.org/wiki/ISO_8601#Durations} for duration format
+     * details.
+     *
+     * @since 1.10.0
+     * @public
+     */
+    static parseFromString(input: string): DurationValue | null;
+    /**
+     * Create a new DurationValue from milliseconds.
+     *
+     * @since 1.10.0
+     * @public
+     */
+    static fromMilliseconds(milliseconds: number): DurationValue;
+}
+export declare class FileValue extends NotNullValue {
+    readonly file: TFile;
+    constructor(file: TFile);
+    get value(): TFile;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    toString(): string;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    isTruthy(): boolean;
+    equals(other: this): boolean;
+    looseEquals(other: Value): boolean;
+}
+export declare class ObjectValue extends NotNullValue {
+    readonly value: any;
+    constructor(value: any);
+    equals(other: this): boolean;
+    looseEquals(other: Value): boolean;
+    toString(): string;
+    isTruthy(): boolean;
+}
+/**
+ * @since 1.10.0
+ * @public
+ */
+export interface BaseOption {
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    key: string;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    type: string;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    displayName: string;
+}
+export declare class QueryController extends Component {
+    #private;
+    readonly views: Map<string, BasesViewRegistration>;
+    readonly readOnly: boolean;
+    readonly app: App;
+    data: Array<VaultRecord>;
+    loadError: string | null;
+    doc: BasesDocument;
+    properties: Record<string, {
+        displayName: string;
+    }>;
+    formulas: Record<string, string>;
+    searchQuery: string;
+    searchPanelOpen: boolean;
+    columns: Record<string, ColumnDefinition>;
+    frontMatterTypes: Record<string, DType>;
+    db: Context;
+    selectedView: BasesViewBase;
+    private prevDoc;
+    private lastViewResults;
+    query: string;
+    metadataDependencies: import("./metadata-invalidation-core").MetadataDependencySet;
+    reloadSignature: string;
+    dataset: [Array<Record<string, unknown>>, Record<string, DType>];
+    queryResult: BasesQueryResult;
+    constructor(app: App, document: BasesDocument, views: Map<string, BasesViewRegistration>, onChange: (doc: BasesDocument) => void, readOnly?: boolean);
+    get view(): BasesView;
+    set view(view: BasesView);
+    private syncViewData;
+    get viewConfig(): BasesViewRegistration;
+    getRecords(qs: string): [Array<Record<string, unknown>>, Record<string, DType>];
+    getAllColumns(): ColumnDefinition[];
+    isVisible(id: BasesPropertyId): boolean;
+    toggleVisibility(id: BasesPropertyId): void;
+    getColumn(id: BasesPropertyId): ColumnDefinition;
+    get count(): number;
+    get searchCount(): number;
+    toggleSearchPanel(): void;
+    reload(): Promise<void>;
+}
+export declare abstract class BasesView extends Component {
+    readonly controller: QueryController;
+    private mountedView;
+    private mountedViewContainer;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    app: App;
+    /**
+     * The type ID of this view
+     *
+     * @since 1.10.0
+     * @public
+     */
+    abstract type: string;
+    /**
+     * The config object for this view.
+     *
+     * @since 1.10.0
+     * @public
+     */
+    config: SharedBasesViewConfig;
+    /**
+     * The most recent output from executing the bases query, applying filters,
+     * and evaluating formulas. This object will be replaced with a new result set
+     * when changes to the vault or Bases config occur, so views should not keep a
+     * reference to it. Also note the contained BasesEntry objects will be
+     * recreated.
+     *
+     * @since 1.10.0
+     * @public
+     */
+    data: BasesQueryResult;
+    protected constructor(controller: QueryController);
+    protected mountViewComponent(component: any, props: Record<string, unknown>, containerEl: HTMLElement): void;
+    protected unmountViewComponent(): void;
+    onunload(): void;
+    /**
+     * All available properties from the dataset.
+     *
+     * @since 1.10.0
+     * @public
+     */
+    get allProperties(): BasesPropertyId[];
+    createFileForView(baseFileName?: string, frontmatterProcessor?: (frontmatter: any) => void): Promise<void>;
+    /**
+     * Called when there is new data for the query. This view should rerender with
+     * the updated data.
+     *
+     * @since 1.10.0
+     * @public
+     */
+    abstract onDataUpdated(): void;
+}
+/**
+ * Implement this factory function in a {@link BasesViewRegistration} to create a
+ * new instance of a custom Bases view.
+ *
+ * @since 1.10.0
+ * @param containerEl - The container below the Bases toolbar where the view
+ *   will be displayed.
+ * @public
+ */
+export type BasesViewFactory = (controller: QueryController, containerEl: HTMLElement) => BasesView;
+/**
+ * Container for options when registering a new Bases view type.
+ *
+ * @since 1.10.0
+ * @public
+ */
+export interface BasesViewRegistration {
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    name: string;
+    /**
+     * Icon ID to be used in the Bases view selector. See
+     * {@link https://docs.obsidian.md/Plugins/User+interface/Icons} for available
+     * icons and how to add your own.
+     *
+     * @since 1.10.0
+     * @public
+     */
+    icon: string;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    factory: BasesViewFactory;
+    /**
+     * @since 1.10.0
+     * @public
+     */
+    options?: (config: SharedBasesViewConfig) => BasesAllOptions[];
+}
+/**
+ * A group of BasesEntry objects for a given value of the groupBy key. If there
+ * are entries in the results which do not have a value for the groupBy key, the
+ * key will be the {@link NullValue}.
+ *
+ * @since 1.10.0
+ * @public
+ */
+export declare class BasesEntryGroup {
+    readonly entries: BasesEntry[];
+    readonly key?: Value | undefined;
+    constructor(entries: BasesEntry[], key?: Value | undefined);
+    /**
+     * @since 1.10.0
+     * @returns True iff this entry group has a non-null key.
+     * @public
+     */
+    hasKey(): boolean;
+}
+/**
+ * The BasesQueryResult contains all of the available information from executing
+ * the bases query, applying filters, and evaluating formulas. The `data` or
+ * `groupedData` should be displayed by your view.
+ *
+ * @since 1.10.0
+ * @public
+ */
+export declare class BasesQueryResult {
+    readonly data: BasesEntry[];
+    readonly properties: BasesPropertyId[];
+    readonly groupBy?: BasesPropertyId | undefined;
+    constructor(data: BasesEntry[], properties: BasesPropertyId[], groupBy?: BasesPropertyId | undefined);
+    get groupedData(): BasesEntryGroup[];
+    getSummaryValue(queryController: QueryController, entries: BasesEntry[], prop: BasesPropertyId, summaryKey: string): Value;
+}