@univerjs-pro/bases 0.25.0-insiders.20260608-e4336f7

package/lib/types/facade/f-permission.d.ts

@@ -0,0 +1,299 @@
+import type { IBaseFieldPermission, IBasePermissionService, IBasePermissionSnapshot, IBaseRecordPermission, IBaseTablePermission } from '../services/base-permission.service';
+/**
+ * Facade API for Base permission points.
+ *
+ * It exposes Base-local permission controls that are consumed by Base commands.
+ * Server-backed auth can hydrate the same points without changing facade callers.
+ *
+ * @example Configure permissions from server auth data
+ * ```ts
+ * const permission = base.getPermission();
+ * permission.setBasePermission({ createTable: false });
+ * permission.setTablePermission('tasks', { createRecord: false });
+ * permission.setFieldPermission('tasks', 'status', { edit: false });
+ * permission.setRecordPermission('tasks', 'task-1', { delete: false });
+ *
+ * console.log(permission.canCreateTable());
+ * console.log(permission.canEditCell('tasks', 'task-1', 'status'));
+ * console.log(permission.getSnapshot());
+ * ```
+ */
+export declare class FBasePermission {
+    private readonly _baseId;
+    private readonly _permissionService;
+    constructor(_baseId: string, _permissionService: IBasePermissionService);
+    /**
+     * Set Base-level permissions.
+     *
+     * Base-level permissions apply to the whole Base unit. They are the right
+     * place for permissions that do not belong to a specific table, field,
+     * record, or view.
+     *
+     * @param permission Permission patch. `createTable` controls whether new
+     * tables can be created in this Base.
+     * @param permission.createTable Optional flag for creating tables.
+     * @example
+     * ```ts
+     * base.getPermission().setBasePermission({ createTable: false });
+     * ```
+     */
+    setBasePermission(permission: {
+        createTable?: boolean;
+    }): void;
+    /**
+     * Set table-level permissions.
+     *
+     * Use this for permissions that affect table operations or all records,
+     * fields, and views under a table.
+     *
+     * @param tableId Target table id.
+     * @param permission Table permission patch, such as `delete`,
+     * `createField`, `createRecord`, or view management flags.
+     * @example
+     * ```ts
+     * permission.setTablePermission('tasks', { createRecord: false });
+     * ```
+     */
+    setTablePermission(tableId: string, permission: IBaseTablePermission): void;
+    /**
+     * Set field-level permissions.
+     *
+     * Field permissions are checked by field commands and by cell editing for
+     * the target field.
+     *
+     * @param tableId Target table id.
+     * @param fieldId Target field id.
+     * @param permission Field permission patch, such as edit/delete flags.
+     * @example
+     * ```ts
+     * permission.setFieldPermission('tasks', 'status', { edit: false });
+     * ```
+     */
+    setFieldPermission(tableId: string, fieldId: string, permission: IBaseFieldPermission): void;
+    /**
+     * Set record-level permissions.
+     *
+     * Record permissions are checked for record-specific operations such as
+     * delete and cell edits on that row.
+     *
+     * @param tableId Target table id.
+     * @param recordId Target record id.
+     * @param permission Record permission patch, such as delete/edit flags.
+     * @example
+     * ```ts
+     * permission.setRecordPermission('tasks', 'task-1', { delete: false });
+     * ```
+     */
+    setRecordPermission(tableId: string, recordId: string, permission: IBaseRecordPermission): void;
+    /**
+     * Clear Base-level permission overrides.
+     *
+     * @example
+     * ```ts
+     * permission.clearBasePermission();
+     * ```
+     */
+    clearBasePermission(): void;
+    /**
+     * Clear permission overrides for one table.
+     *
+     * @param tableId Target table id.
+     * @example
+     * ```ts
+     * permission.clearTablePermission('tasks');
+     * ```
+     */
+    clearTablePermission(tableId: string): void;
+    /**
+     * Clear permission overrides for one field.
+     *
+     * @param tableId Target table id.
+     * @param fieldId Target field id.
+     * @example
+     * ```ts
+     * permission.clearFieldPermission('tasks', 'status');
+     * ```
+     */
+    clearFieldPermission(tableId: string, fieldId: string): void;
+    /**
+     * Clear permission overrides for one record.
+     *
+     * @param tableId Target table id.
+     * @param recordId Target record id.
+     * @example
+     * ```ts
+     * permission.clearRecordPermission('tasks', 'task-1');
+     * ```
+     */
+    clearRecordPermission(tableId: string, recordId: string): void;
+    /**
+     * Check whether the Base can create tables.
+     * @returns `true` when table creation is allowed.
+     * @example
+     * ```ts
+     * if (permission.canCreateTable()) await base.createTable({ name: 'Tasks' });
+     * ```
+     */
+    canCreateTable(): boolean;
+    /**
+     * Check whether a table can be deleted.
+     * @param tableId Target table id.
+     * @returns `true` when table deletion is allowed.
+     * @example
+     * ```ts
+     * console.log(permission.canDeleteTable('tasks'));
+     * ```
+     */
+    canDeleteTable(tableId: string): boolean;
+    /**
+     * Check whether fields can be created in a table.
+     * @param tableId Target table id.
+     * @returns `true` when field creation is allowed.
+     * @example
+     * ```ts
+     * console.log(permission.canCreateField('tasks'));
+     * ```
+     */
+    canCreateField(tableId: string): boolean;
+    /**
+     * Check whether a field can be edited.
+     * @param tableId Target table id.
+     * @param fieldId Target field id.
+     * @returns `true` when field metadata edits are allowed.
+     * @example
+     * ```ts
+     * console.log(permission.canEditField('tasks', 'status'));
+     * ```
+     */
+    canEditField(tableId: string, fieldId: string): boolean;
+    /**
+     * Check whether a field can be deleted.
+     * @param tableId Target table id.
+     * @param fieldId Target field id.
+     * @returns `true` when field deletion is allowed.
+     * @example
+     * ```ts
+     * console.log(permission.canDeleteField('tasks', 'status'));
+     * ```
+     */
+    canDeleteField(tableId: string, fieldId: string): boolean;
+    /**
+     * Check whether records can be created in a table.
+     * @param tableId Target table id.
+     * @returns `true` when record creation is allowed.
+     * @example
+     * ```ts
+     * console.log(permission.canCreateRecord('tasks'));
+     * ```
+     */
+    canCreateRecord(tableId: string): boolean;
+    /**
+     * Check whether a record can be deleted.
+     * @param tableId Target table id.
+     * @param recordId Target record id.
+     * @returns `true` when record deletion is allowed.
+     * @example
+     * ```ts
+     * console.log(permission.canDeleteRecord('tasks', 'task-1'));
+     * ```
+     */
+    canDeleteRecord(tableId: string, recordId: string): boolean;
+    /**
+     * Check whether one cell can be edited.
+     *
+     * The effective result combines table, field, record, and readonly-style
+     * restrictions in the permission service.
+     *
+     * @param tableId Target table id.
+     * @param recordId Target record id.
+     * @param fieldId Target field id.
+     * @returns `true` when the cell edit is allowed.
+     * @example
+     * ```ts
+     * if (permission.canEditCell('tasks', 'task-1', 'status')) {
+     *   await table.setCellValue('task-1', 'status', 'done');
+     * }
+     * ```
+     */
+    canEditCell(tableId: string, recordId: string, fieldId: string): boolean;
+    /**
+     * Check whether one view can be managed.
+     * @param tableId Target table id.
+     * @param viewId Target view id.
+     * @returns `true` when view configuration, ordering, or deletion is allowed.
+     * @example
+     * ```ts
+     * console.log(permission.canManageView('tasks', 'grid-main'));
+     * ```
+     */
+    canManageView(tableId: string, viewId: string): boolean;
+    /**
+     * Get the current permission snapshot.
+     *
+     * Use this at the persistence boundary if Base-local permission overrides
+     * are stored with the server-side Base model.
+     *
+     * @returns Base permission snapshot.
+     * @example
+     * ```ts
+     * await savePermissionSnapshot(base.getId(), permission.getSnapshot());
+     * ```
+     */
+    getSnapshot(): IBasePermissionSnapshot;
+}
+/**
+ * Table-scoped permission facade returned by `table.getPermission()`.
+ *
+ * It is a convenience wrapper around `FBasePermission` for callers that already
+ * operate inside one table and do not want to pass `tableId` repeatedly.
+ */
+export declare class FTablePermission {
+    private readonly _tableId;
+    private readonly _permissionService;
+    constructor(_tableId: string, _permissionService: IBasePermissionService);
+    /**
+     * Set permission overrides for this table.
+     * @param permission Table permission patch.
+     * @example
+     * ```ts
+     * table.getPermission().setPermission({ createRecord: false });
+     * ```
+     */
+    setPermission(permission: IBaseTablePermission): void;
+    /**
+     * Clear permission overrides for this table.
+     * @example
+     * ```ts
+     * table.getPermission().clearPermission();
+     * ```
+     */
+    clearPermission(): void;
+    /**
+     * Check whether this table can be deleted.
+     * @returns `true` when table deletion is allowed.
+     */
+    canDeleteTable(): boolean;
+    /**
+     * Check whether fields can be created in this table.
+     * @returns `true` when field creation is allowed.
+     */
+    canCreateField(): boolean;
+    /**
+     * Check whether records can be created in this table.
+     * @returns `true` when record creation is allowed.
+     */
+    canCreateRecord(): boolean;
+    /**
+     * Check whether a view in this table can be managed.
+     * @param viewId Target view id.
+     * @returns `true` when view management is allowed.
+     */
+    canManageView(viewId: string): boolean;
+    /**
+     * Check whether one cell in this table can be edited.
+     * @param recordId Target record id.
+     * @param fieldId Target field id.
+     * @returns `true` when the cell edit is allowed.
+     */
+    canEditCell(recordId: string, fieldId: string): boolean;
+}

package/lib/types/facade/f-range.d.ts

@@ -0,0 +1,179 @@
+import type { BaseCellValue, BaseDataModel, IBaseCellData, ICommandService, IRange } from '@univerjs/core';
+export type BaseRangeValues = BaseCellValue[][];
+/**
+ * Facade API object bound to a rectangular Base table range.
+ *
+ * A Base range is addressed by row and column indexes over records and fields,
+ * similar to a spreadsheet range over worksheet cells.
+ *
+ * Row indexes resolve through the table's current `recordOrder`; column indexes
+ * resolve through `fieldOrder`. Writes are converted to Base cell updates under
+ * the hood, so the persisted snapshot still stores values by record id and
+ * field id.
+ *
+ * @example Read and write a rectangular block
+ * ```ts
+ * const range = table.getRange(0, 0, 2, 2);
+ * console.log(range.getValues());
+ * await range.setValues([
+ *   ['Task A', 'todo'],
+ *   ['Task B', 'done'],
+ * ]);
+ * const statusColumn = range.offset(0, 1, range.getNumRows(), 1);
+ * await statusColumn.clear();
+ * ```
+ */
+export declare class FBaseRange {
+    private readonly _base;
+    private readonly _tableId;
+    private readonly _range;
+    private readonly _commandService;
+    constructor(_base: BaseDataModel, _tableId: string, _range: IRange, _commandService: ICommandService);
+    /**
+     * Get the Base unit id.
+     * @returns The Base unit id.
+     * @example
+     * ```ts
+     * console.log(range.getUnitId());
+     * ```
+     */
+    getUnitId(): string;
+    /**
+     * Get the Base id.
+     * @returns The Base id.
+     * @example
+     * ```ts
+     * console.log(range.getBaseId());
+     * ```
+     */
+    getBaseId(): string;
+    /**
+     * Get the table id.
+     * @returns The table id.
+     * @example
+     * ```ts
+     * console.log(range.getTableId());
+     * ```
+     */
+    getTableId(): string;
+    /**
+     * Get the raw range position.
+     * @returns The range position.
+     * @example
+     * ```ts
+     * const position = range.getRange();
+     * ```
+     */
+    getRange(): IRange;
+    /**
+     * Get the first row index of this range.
+     * @returns The zero-based row index.
+     * @example
+     * ```ts
+     * console.log(range.getRow());
+     * ```
+     */
+    getRow(): number;
+    /**
+     * Get the first column index of this range.
+     * @returns The zero-based column index.
+     * @example
+     * ```ts
+     * console.log(range.getColumn());
+     * ```
+     */
+    getColumn(): number;
+    /**
+     * Get the number of rows in this range.
+     * @returns The row count.
+     * @example
+     * ```ts
+     * console.log(range.getNumRows());
+     * ```
+     */
+    getNumRows(): number;
+    /**
+     * Get the number of columns in this range.
+     * @returns The column count.
+     * @example
+     * ```ts
+     * console.log(range.getNumColumns());
+     * ```
+     */
+    getNumColumns(): number;
+    /**
+     * Get all values in this range.
+     *
+     * The outer array is rows and the inner array is columns. Empty cells are
+     * returned as `null`.
+     *
+     * @returns A two-dimensional array matching the range size.
+     * @example
+     * ```ts
+     * const values = table.getRange(0, 0, 2, 3).getValues();
+     * ```
+     */
+    getValues(): BaseRangeValues;
+    /**
+     * Get the first value in this range.
+     * @returns The top-left value.
+     * @example
+     * ```ts
+     * const value = table.getRange(0, 0).getValue();
+     * ```
+     */
+    getValue(): BaseCellValue;
+    /**
+     * Set the top-left value in this range.
+     * @param value The value to write. It may be a raw Base cell value, a full
+     * `IBaseCellData` object, or `null` to clear the cell.
+     * @example
+     * ```ts
+     * await table.getRange(0, 0).setValue('Task title');
+     * ```
+     */
+    setValue(value: BaseCellValue | IBaseCellData | null): Promise<void>;
+    /**
+     * Set all values in this range.
+     *
+     * The provided matrix must match `getNumRows()` by `getNumColumns()`.
+     * Passing the wrong shape throws before any command is executed.
+     *
+     * @param values A two-dimensional array matching the range size. Each cell
+     * may be a raw Base cell value, an `IBaseCellData` object, or `null`.
+     * @example
+     * ```ts
+     * await table.getRange(0, 1, 2, 2).setValues([
+     *   ['todo', 10],
+     *   ['done', 20],
+     * ]);
+     * ```
+     */
+    setValues(values: Array<Array<BaseCellValue | IBaseCellData | null>>): Promise<void>;
+    /**
+     * Clear all values in this range.
+     * @example
+     * ```ts
+     * await table.getRange(0, 0, 10, 3).clear();
+     * ```
+     */
+    clear(): Promise<void>;
+    /**
+     * Create a new range offset from this range.
+     *
+     * Offsets are validated against the table's current row and column bounds.
+     *
+     * @param rowOffset Number of rows to move. Positive values move down.
+     * @param columnOffset Number of columns to move. Positive values move right.
+     * @param numRows Number of rows in the returned range. Defaults to the current row count.
+     * @param numColumns Number of columns in the returned range. Defaults to the current column count.
+     * @returns The offset range facade.
+     * @example
+     * ```ts
+     * const nextColumn = range.offset(0, 1);
+     * ```
+     */
+    offset(rowOffset: number, columnOffset: number, numRows?: number, numColumns?: number): FBaseRange;
+    private _getTable;
+    private _assertInBounds;
+}

package/lib/types/facade/f-record.d.ts

@@ -0,0 +1,137 @@
+import type { BaseCellValue, BaseDataModel, ICommandService, IRecordSnapshot } from '@univerjs/core';
+/**
+ * Facade API object bound to a Base record.
+ *
+ * A Base record is equivalent to a row in a table.
+ * Record values are keyed by field id. Use field ids from `FField` or
+ * `table.getPrimaryFieldId()` instead of display names when reading or writing.
+ *
+ * @example Read, update, and duplicate a record
+ * ```ts
+ * const record = table.getRecord('task-1');
+ * if (record) {
+ *   await record.setValue('status', 'done');
+ *   await record.setValues({ progress: 100 });
+ *   const copy = await record.duplicate({
+ *     id: 'task-1-copy',
+ *     values: { ...record.getValues(), status: 'todo' },
+ *   });
+ *   console.log(copy.getId());
+ * }
+ * ```
+ */
+export declare class FRecord {
+    private readonly _base;
+    private readonly _tableId;
+    private readonly _recordId;
+    private readonly _commandService;
+    constructor(_base: BaseDataModel, _tableId: string, _recordId: string, _commandService: ICommandService);
+    /**
+     * Get the record id.
+     * @returns The record id.
+     * @example
+     * ```ts
+     * console.log(record.getId());
+     * ```
+     */
+    getId(): string;
+    /**
+     * Get the record snapshot.
+     * @returns The record snapshot.
+     * @example
+     * ```ts
+     * const rawRecord = record.getRecord();
+     * ```
+     */
+    getRecord(): IRecordSnapshot;
+    /**
+     * Get the record snapshot.
+     * @returns The record snapshot.
+     * @example
+     * ```ts
+     * const snapshot = record.getSnapshot();
+     * ```
+     */
+    getSnapshot(): IRecordSnapshot;
+    /**
+     * Get a field value from this record.
+     * @param fieldId The field id.
+     * @returns The field value, or null when empty.
+     * @example
+     * ```ts
+     * const title = record.getValue('title');
+     * ```
+     */
+    getValue(fieldId: string): BaseCellValue;
+    /**
+     * Get all values from this record.
+     * @returns A field-id keyed value map.
+     * @example
+     * ```ts
+     * const values = record.getValues();
+     * ```
+     */
+    getValues(): IRecordSnapshot['values'];
+    /**
+     * Set one field value in this record.
+     * @param fieldId The field id to write.
+     * @param value The new cell value. Pass `null` to clear the cell.
+     * @example
+     * ```ts
+     * await record.setValue('status', 'done');
+     * ```
+     */
+    setValue(fieldId: string, value: BaseCellValue): Promise<void>;
+    /**
+     * Set multiple field values in this record.
+     * @param values Field-id keyed values to write. Only the provided fields are
+     * patched; omitted fields keep their existing values.
+     * @example
+     * ```ts
+     * await record.setValues({ title: 'Ship beta', status: 'done' });
+     * ```
+     */
+    setValues(values: Record<string, BaseCellValue>): Promise<void>;
+    /**
+     * Delete this record.
+     * @example
+     * ```ts
+     * await record.delete();
+     * ```
+     */
+    delete(): Promise<void>;
+    /**
+     * Duplicate this record.
+     *
+     * The duplicated record starts with this record's values, then applies
+     * `input.values` as field-id keyed overrides.
+     *
+     * @param input Optional record id, values, and order key overrides.
+     * @param input.id Optional id for the duplicated record.
+     * @param input.values Optional field-id keyed values for the duplicated record.
+     * @param input.orderKey Optional order key for the duplicated record.
+     * @returns The duplicated record facade.
+     * @example
+     * ```ts
+     * const copy = await record.duplicate({
+     *   id: 'record-copy',
+     *   values: { title: 'Copy' },
+     * });
+     * ```
+     */
+    duplicate(input?: {
+        id?: string;
+        values?: Record<string, BaseCellValue>;
+        orderKey?: string;
+    }): Promise<FRecord>;
+    /**
+     * Set this record's order key.
+     * @param orderKey The new order key.
+     * @example
+     * ```ts
+     * await record.setOrderKey('a1');
+     * ```
+     */
+    setOrderKey(orderKey: string): Promise<void>;
+    private _getRecord;
+}