@book.dev/sdk 3.10.0 → 3.13.0

package/dist/database.d.ts

@@ -3,7 +3,7 @@
  * StoredPage}. A **database** is a collection of pages (its *rows*) managed by
  * typed *properties* and presented through one or more configurable *views*
  * (table, list, gallery, board, calendar, timeline, map, relationship graph,
- * or a bar/pie chart).
+ * form, or a bar/pie chart).
  *
  * Three ideas make OpenBook databases different from a plain spreadsheet:
  *
@@ -40,6 +40,43 @@ import type { PageSnapshot } from './types';
  * see {@link ./pageProperties}.
  */
 export type DatabasePropertyType = 'text' | 'number' | 'rating' | 'select' | 'multi_select' | 'status' | 'checkbox' | 'date' | 'url' | 'email' | 'phone' | 'location' | 'files' | 'relation' | 'dependency' | 'rollup' | 'created_time' | 'last_edited_time' | 'unique_id' | 'expr' | 'formula' | 'person' | 'verification' | 'backlinks';
+/**
+ * Whether a public form may write a property type in v1. This exhaustive map is
+ * the shared allowlist for builders and the submission validator. Reference,
+ * identity/attestation, computed, and server-managed properties fail closed.
+ */
+export declare const FORM_PROPERTY_TYPE_WRITABILITY: {
+    readonly text: true;
+    readonly number: true;
+    readonly rating: true;
+    readonly select: true;
+    readonly multi_select: true;
+    readonly status: true;
+    readonly checkbox: true;
+    readonly date: true;
+    readonly url: true;
+    readonly email: true;
+    readonly phone: true;
+    readonly location: true;
+    readonly files: true;
+    readonly relation: false;
+    readonly dependency: false;
+    readonly rollup: false;
+    readonly created_time: false;
+    readonly last_edited_time: false;
+    readonly unique_id: false;
+    readonly expr: false;
+    readonly formula: false;
+    readonly person: false;
+    readonly verification: false;
+    readonly backlinks: false;
+};
+/** Database property types accepted by public form fills. */
+export type FormWritablePropertyType = {
+    [Type in DatabasePropertyType]: typeof FORM_PROPERTY_TYPE_WRITABILITY[Type] extends true ? Type : never;
+}[DatabasePropertyType];
+/** True when `type` is safe for a public form fill in v1. */
+export declare function isFormWritablePropertyType(type: DatabasePropertyType): type is FormWritablePropertyType;
 /** Display formatting for `number`/`formula`/`expr` numeric values. */
 export type NumberFormat = 'plain' | 'integer' | 'decimal' | 'percent' | 'dollar' | 'euro' | 'pound' | 'yen' | 'rupee';
 /** How a number cell is visualised: as text, a horizontal bar, or a ring. */
@@ -197,7 +234,11 @@ export interface RowTemplate {
  * select property; `calendar` lays rows out on a month grid by a date property;
  * `bar`/`pie` are charts that aggregate rows by a category property.
  */
-export type DatabaseViewType = 'table' | 'list' | 'gallery' | 'board' | 'calendar' | 'timeline' | 'map' | 'graph' | 'bar' | 'pie';
+export type DatabaseViewType = 'table' | 'list' | 'gallery' | 'board' | 'calendar' | 'timeline' | 'map' | 'graph' | 'form' | 'bar' | 'pie';
+/** Runtime list for fail-closed decoding of persisted view types. */
+export declare const KNOWN_DATABASE_VIEW_TYPES: readonly ["table", "list", "gallery", "board", "calendar", "timeline", "map", "graph", "form", "bar", "pie"];
+/** True only for view layouts this SDK knows how to interpret. */
+export declare function isDatabaseViewType(value: unknown): value is DatabaseViewType;
 /** How a chart (or a board column footer) aggregates a group of rows. */
 export interface ChartAggregate {
     /** `count` tallies rows; the others fold a numeric `propertyId`. */
@@ -260,6 +301,86 @@ export interface DatabaseMetric {
     /** Optional goal — when set, the card shows a progress bar of value/target. */
     target?: number;
 }
+/** Per-property presentation and validation metadata for a form view. */
+export interface DatabaseFormFieldValidation {
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+}
+export interface DatabaseFormField {
+    label?: string;
+    help?: string;
+    required?: boolean;
+    placeholder?: string;
+    /** Render a text property as a multi-line input. */
+    multiline?: boolean;
+    /** Constraints enforced by the public submission validator. */
+    validation?: DatabaseFormFieldValidation;
+}
+/** Post-submit behaviour for a database-view form. */
+export type DatabaseFormConfirmation = {
+    type: 'message';
+    message: string;
+} | {
+    type: 'redirect';
+    redirectUrl: string;
+};
+/** Form-wide copy and response state for a form view. */
+export interface DatabaseFormConfig {
+    title?: string;
+    description?: string;
+    submitLabel?: string;
+    confirmation?: DatabaseFormConfirmation;
+    acceptingResponses?: boolean;
+    closedMessage?: string;
+    /** Per-view response ceiling; absence uses the legacy public-form default. */
+    maxResponses?: number;
+}
+/** One deliberately projected public field; no other column shape is exposed. */
+export interface DatabaseFormDescriptorField {
+    propertyId: string;
+    type: FormWritablePropertyType;
+    label: string;
+    help: string;
+    required: boolean;
+    placeholder: string;
+    multiline?: boolean;
+    /** Display-safe constraints; pattern remains server-enforced only. */
+    validation?: Pick<DatabaseFormFieldValidation, 'min' | 'max' | 'minLength' | 'maxLength'>;
+    options?: DatabaseSelectOption[];
+    includeTime?: boolean;
+    dateRange?: boolean;
+    numberTarget?: number;
+}
+/** Capability-gated public rendering contract for one database form view. */
+export interface DatabaseFormDescriptor {
+    title: string;
+    description: string;
+    submitLabel: string;
+    acceptingResponses: boolean;
+    /** Present only for a closed form that configured custom copy. */
+    closedMessage?: string;
+    fields: DatabaseFormDescriptorField[];
+}
+/** Stable machine-readable failures returned by {@link validateRowAgainstForm}. */
+export declare const FORM_ROW_VALIDATION_ERROR_CODES: readonly ["view_type", "unknown_field", "required", "type", "min", "max", "minLength", "maxLength", "pattern", "option", "range", "too_large", "date_format", "email_format", "url_format", "phone_format"];
+export type FormRowValidationErrorCode = typeof FORM_ROW_VALIDATION_ERROR_CODES[number];
+export interface FormRowValidationError {
+    /** Empty only for a view-level failure such as validating a non-form view. */
+    propertyId: string;
+    code: FormRowValidationErrorCode;
+}
+/** A successful result contains only current, mapped, form-writable properties. */
+export type FormRowValidationResult = {
+    ok: true;
+    name?: string;
+    fields: Record<string, unknown>;
+} | {
+    ok: false;
+    errors: FormRowValidationError[];
+};
 /** A saved presentation of the database: a layout plus its filters and sorts. */
 export interface DatabaseView {
     id: string;
@@ -272,9 +393,16 @@ export interface DatabaseView {
     sorts: DatabaseSort[];
     /**
      * Property ids to show, in order. Empty/undefined shows every property. The
-     * title is always shown and is not listed here.
+     * title is always shown and is not listed here for ordinary views. A `form`
+     * view is deliberately stricter: only explicitly listed ids are fields, in
+     * this exact order, and the reserved `title` id maps the row name.
      */
     visiblePropertyIds?: string[];
+    /** Form-view field metadata, keyed by property id. Inclusion and order remain
+     *  owned by {@link visiblePropertyIds}; stale/non-visible entries are ignored. */
+    formFields?: Record<string, DatabaseFormField>;
+    /** Form-view copy and whether its already-published capability accepts fills. */
+    formConfig?: DatabaseFormConfig;
     /**
      * Property to group rows by. Drives the kanban columns (`board`) and the
      * category axis of a chart (`bar`/`pie`). Best paired with a `select`
@@ -623,12 +751,29 @@ export declare const STATUS_GROUPS: {
 /**
  * Remove a property from a schema and scrub **every** dangling reference to it:
  * each view's filters (flat list *and* the nested {@link filterRoot} tree),
- * sorts, visible columns, summaries, and the group-by / date / cover config; plus
- * any `rollup` on another property that aggregated through or over it. Pure —
- * returns a fresh schema — so it can be unit-tested and shared by the delete
- * action. (Renders already tolerate stale refs; this keeps the schema clean.)
+ * sorts, visible columns, form-field metadata, summaries, and the group-by /
+ * date / cover config; plus any `rollup` on another property that aggregated
+ * through or over it. Pure — returns a fresh schema — so it can be unit-tested
+ * and shared by the delete action. (Renders already tolerate stale refs; this
+ * keeps the schema clean.)
  */
 export declare function removeProperty(schema: DatabaseSchema, propertyId: string): DatabaseSchema;
+/** Conservative structural screen for common exponential-backtracking forms. */
+export declare function formPatternIsUnsafe(pattern: string): boolean;
+/**
+ * Project only the public rendering contract from a freshly loaded form view.
+ * Returns `null` for a non-form view so callers cannot accidentally serialize a
+ * normal database view through the public endpoint.
+ */
+export declare function projectDatabaseFormDescriptor(schema: DatabaseSchema, view: DatabaseView): DatabaseFormDescriptor | null;
+/**
+ * Validate an untrusted public fill against the database's current schema and
+ * form mapping. The allowlist is the form's explicit `visiblePropertyIds`
+ * intersected with current form-writable properties. Unknown, deleted,
+ * non-visible, computed, and managed fields are rejected; successful output is
+ * a fresh record containing only validated fields ready for row creation.
+ */
+export declare function validateRowAgainstForm(schema: DatabaseSchema, view: DatabaseView, fields: Record<string, unknown>): FormRowValidationResult;
 /** Format a numeric value for display per a {@link NumberFormat}. Non-numbers pass through as text. */
 export declare function formatNumber(value: unknown, format: NumberFormat | undefined): string;
 /**