@jackuait/blok 0.10.3 → 0.10.4

package/src/tools/database/types.ts

@@ -0,0 +1,152 @@
+import type { BlockToolData, OutputData } from '../../../types';
+
+// ─── Property types ───
+
+export type PropertyType = 'title' | 'text' | 'number' | 'select' | 'multiSelect' | 'date' | 'checkbox' | 'url' | 'richText';
+
+export interface SelectOption {
+  id: string;
+  label: string;
+  color?: string;
+  position: string;
+}
+
+export interface SelectPropertyConfig {
+  options: SelectOption[];
+}
+
+export type PropertyConfig = SelectPropertyConfig;
+
+export interface PropertyDefinition {
+  id: string;
+  name: string;
+  type: PropertyType;
+  position: string;
+  config?: PropertyConfig;
+}
+
+export type PropertyValue = string | number | boolean | string[] | OutputData | null;
+
+// ─── Rows ───
+
+export interface DatabaseRow {
+  id: string;
+  position: string;
+  properties: Record<string, PropertyValue>;
+}
+
+export interface DatabaseRowData extends BlockToolData {
+  properties: Record<string, PropertyValue>;
+  position: string;
+}
+
+// ─── View config ───
+
+export type ViewType = 'board' | 'table' | 'gallery' | 'list';
+
+export interface SortConfig {
+  propertyId: string;
+  direction: 'asc' | 'desc';
+}
+
+export interface FilterConfig {
+  propertyId: string;
+  operator: string;
+  value: PropertyValue;
+}
+
+export interface DatabaseViewConfig {
+  id: string;
+  name: string;
+  type: ViewType;
+  position: string;
+  groupBy?: string;
+  sorts: SortConfig[];
+  filters: FilterConfig[];
+  visibleProperties: string[];
+}
+
+// ─── Top-level saved data ───
+
+/**
+ * Data saved by the database block.
+ * Schema and views only — rows are child blocks (database-row type).
+ */
+export interface DatabaseData extends BlockToolData {
+  title?: string;
+  schema: PropertyDefinition[];
+  views: DatabaseViewConfig[];
+  activeViewId: string;
+}
+
+// ─── Adapter ───
+
+export interface DatabaseAdapter {
+  loadDatabase(): Promise<{
+    schema: PropertyDefinition[];
+    views: DatabaseViewConfig[];
+  }>;
+
+  createRow(params: {
+    id: string;
+    properties: Record<string, PropertyValue>;
+    position: string;
+  }): Promise<DatabaseRow>;
+
+  updateRow(params: {
+    rowId: string;
+    properties: Record<string, PropertyValue>;
+  }): Promise<DatabaseRow>;
+
+  moveRow(params: {
+    rowId: string;
+    position: string;
+  }): Promise<DatabaseRow>;
+
+  deleteRow(params: {
+    rowId: string;
+  }): Promise<void>;
+
+  createProperty(params: {
+    id: string;
+    name: string;
+    type: PropertyType;
+    position: string;
+    config?: PropertyConfig;
+  }): Promise<PropertyDefinition>;
+
+  updateProperty(params: {
+    propertyId: string;
+    changes: Partial<Pick<PropertyDefinition, 'name' | 'config'>>;
+  }): Promise<PropertyDefinition>;
+
+  deleteProperty(params: {
+    propertyId: string;
+  }): Promise<void>;
+
+  createView(params: {
+    id: string;
+    name: string;
+    type: ViewType;
+    position: string;
+    groupBy?: string;
+    sorts?: SortConfig[];
+    filters?: FilterConfig[];
+    visibleProperties?: string[];
+  }): Promise<DatabaseViewConfig>;
+
+  updateView(params: {
+    viewId: string;
+    changes: Partial<Pick<DatabaseViewConfig,
+      'name' | 'type' | 'position' | 'groupBy' | 'sorts' | 'filters' | 'visibleProperties'
+    >>;
+  }): Promise<DatabaseViewConfig>;
+
+  deleteView(params: {
+    viewId: string;
+  }): Promise<void>;
+}
+
+export interface DatabaseConfig {
+  adapter?: DatabaseAdapter;
+}

package/src/tools/database-row/index.ts

@@ -0,0 +1,74 @@
+import type { BlockTool, BlockToolConstructorOptions } from '../../../types/tools/block-tool';
+import type { DatabaseRowData, PropertyValue } from '../database/types';
+
+/**
+ * DatabaseRowTool — lightweight block that stores a single database row.
+ *
+ * Not user-insertable (no toolbox entry). The parent DatabaseTool creates
+ * and manages row blocks; this tool's job is to hold properties and position
+ * as block data so rows participate in the block tree.
+ *
+ * Custom methods (updateProperties, updatePosition, getProperties, getPosition)
+ * are accessed by the parent DatabaseTool via block.call('methodName', params),
+ * which invokes tool instance methods by name through the Block adapter.
+ */
+export class DatabaseRowTool implements BlockTool {
+  private _data: DatabaseRowData;
+
+  constructor({ data }: BlockToolConstructorOptions<DatabaseRowData>) {
+    this._data = {
+      properties: data.properties ?? {},
+      position: data.position ?? 'a0',
+    };
+  }
+
+  public render(): HTMLDivElement {
+    const el = document.createElement('div');
+
+    el.setAttribute('data-blok-tool', 'database-row');
+
+    return el;
+  }
+
+  public save(_block: HTMLElement): DatabaseRowData {
+    return {
+      properties: this._data.properties,
+      position: this._data.position,
+    };
+  }
+
+  public validate(data: DatabaseRowData): boolean {
+    return data.properties !== null && data.properties !== undefined && typeof data.properties === 'object';
+  }
+
+  public updateProperties(changes: Record<string, PropertyValue>): void {
+    Object.assign(this._data.properties, changes);
+  }
+
+  public updatePosition(param: { position: string }): void {
+    this._data.position = param.position;
+  }
+
+  public getProperties(): Record<string, PropertyValue> {
+    return this._data.properties;
+  }
+
+  public getPosition(): string {
+    return this._data.position;
+  }
+
+  public static get isReadOnlySupported(): boolean {
+    return true;
+  }
+
+  /**
+   * No-op: DatabaseRowTool renders an invisible div with no interactive elements.
+   * Implementing this method enables the fast-path in-place read-only toggle in
+   * the ReadOnly module (which requires ALL tools to have setReadOnly()).
+   */
+  public setReadOnly(_state: boolean): void {
+    // intentionally empty
+  }
+}
+
+export type { DatabaseRowData };

package/src/tools/index.ts

@@ -26,6 +26,8 @@ export { ListItem as List } from './list';
 export { Table } from './table';
 export { ToggleItem as Toggle } from './toggle';
 export { CalloutTool as Callout } from './callout';
+export { DatabaseTool as Database } from './database';
+export { DatabaseRowTool as DatabaseRow } from './database-row';
 export { DividerTool as Divider } from './divider';
 export { Quote } from './quote';
 export { CodeTool as Code } from './code';
@@ -49,6 +51,8 @@ export const defaultBlockTools = {
   table: {},
   toggle: {},
   callout: {},
+  database: {},
+  'database-row': {},
   divider: {},
   quote: {},
   code: { inlineToolbar: false },

package/types/api/tools.d.ts

@@ -1,4 +1,16 @@
 import { BlockToolAdapter } from '../tools/adapters/block-tool-adapter';
+import { ToolConstructable, ToolSettings } from '../tools';
+import { ThemeMode } from './theme';
+
+/**
+ * Tools-related configuration that can be passed to a nested Blok instance.
+ */
+export interface ToolsConfig {
+  tools: { [toolName: string]: ToolConstructable | ToolSettings } | undefined;
+  inlineToolbar?: string[] | boolean;
+  tunes?: string[];
+  theme?: ThemeMode;
+}
 
 /**
  * Describes methods for accessing installed Blok tools
@@ -8,4 +20,10 @@ export interface Tools {
    * Returns all available Block Tools
    */
   getBlockTools(): BlockToolAdapter[];
+
+  /**
+   * Returns the tools-related configuration of the current editor instance.
+   * Useful for creating nested Blok editors with the same tools.
+   */
+  getToolsConfig(): ToolsConfig;
 }

package/types/configs/blok-config.d.ts

@@ -183,4 +183,31 @@ export interface BlokConfig {
    * @param resolvedTheme - the resolved theme ('dark' or 'light')
    */
   onThemeChange?: (resolvedTheme: ResolvedTheme) => void;
+
+  /**
+   * Options for the automatic scroll-to-block behavior on hash navigation.
+   * When the page URL contains a hash (`#<blockId>`) that matches a block ID,
+   * the editor smooth-scrolls to that block once all blocks are rendered.
+   * This behavior is always active — this config object only controls offset.
+   * No-op if the URL contains no hash or the hash does not match any block ID.
+   */
+  scrollToBlock?: {
+    /**
+     * Pixels to leave above the block when scrolling into view.
+     * Useful when a sticky header is present.
+     * @default 0
+     */
+    topOffset?: number;
+  };
+
+  /**
+   * User identity for edit tracking.
+   * When set, the user's name is recorded on each block they edit.
+   */
+  user?: {
+    /**
+     * Display name shown in the "Last edited by" footer in block settings.
+     */
+    name: string;
+  };
 }

package/types/data-formats/output-data.d.ts

@@ -41,6 +41,19 @@ export interface OutputBlockData<Type extends string = string, Data extends obje
    * Omit if block has no children.
    */
   content?: BlockId[];
+
+  /**
+   * Timestamp (milliseconds since epoch) of the last edit to this block.
+   * Automatically tracked by the editor when content changes.
+   * Omit for legacy data or blocks that haven't been edited.
+   */
+  lastEditedAt?: number;
+
+  /**
+   * Display name of the user who last edited this block.
+   * Set from the `user.name` config option. Omit if no user is configured.
+   */
+  lastEditedBy?: string;
 }
 
 export interface OutputData {

package/types/index.d.ts

@@ -88,6 +88,23 @@ export {
 export * from './utils/popover';
 
 export { OutputData, OutputBlockData} from './data-formats/output-data';
+export {
+  PropertyType,
+  SelectOption,
+  SelectPropertyConfig,
+  PropertyConfig,
+  PropertyDefinition,
+  PropertyValue,
+  DatabaseRow,
+  ViewType,
+  SortConfig,
+  FilterConfig,
+  DatabaseViewConfig,
+  DatabaseRowData,
+  DatabaseData,
+  DatabaseAdapter,
+  DatabaseConfig,
+} from './tools/database';
 export { BlockId } from './data-formats/block-id';
 export {
   BlockAPI,

package/types/tools/database.d.ts

@@ -0,0 +1,152 @@
+import { BlockToolData } from './block-tool';
+import { OutputData } from '../data-formats/output-data';
+
+// ─── Property types ───
+
+export type PropertyType = 'title' | 'text' | 'number' | 'select' | 'multiSelect' | 'date' | 'checkbox' | 'url' | 'richText';
+
+export interface SelectOption {
+  id: string;
+  label: string;
+  color?: string;
+  position: string;
+}
+
+export interface SelectPropertyConfig {
+  options: SelectOption[];
+}
+
+export type PropertyConfig = SelectPropertyConfig;
+
+export interface PropertyDefinition {
+  id: string;
+  name: string;
+  type: PropertyType;
+  position: string;
+  config?: PropertyConfig;
+}
+
+export type PropertyValue = string | number | boolean | string[] | OutputData | null;
+
+// ─── Rows ───
+
+export interface DatabaseRow {
+  id: string;
+  position: string;
+  properties: Record<string, PropertyValue>;
+}
+
+export interface DatabaseRowData extends BlockToolData {
+  properties: Record<string, PropertyValue>;
+  position: string;
+}
+
+// ─── View config ───
+
+export type ViewType = 'board' | 'table' | 'gallery' | 'list';
+
+export interface SortConfig {
+  propertyId: string;
+  direction: 'asc' | 'desc';
+}
+
+export interface FilterConfig {
+  propertyId: string;
+  operator: string;
+  value: PropertyValue;
+}
+
+export interface DatabaseViewConfig {
+  id: string;
+  name: string;
+  type: ViewType;
+  position: string;
+  groupBy?: string;
+  sorts: SortConfig[];
+  filters: FilterConfig[];
+  visibleProperties: string[];
+}
+
+// ─── Top-level saved data ───
+
+/**
+ * Data saved by the database block.
+ * Schema and views only — rows are child blocks (database-row type).
+ */
+export interface DatabaseData extends BlockToolData {
+  schema: PropertyDefinition[];
+  views: DatabaseViewConfig[];
+  activeViewId: string;
+}
+
+// ─── Adapter ───
+
+export interface DatabaseAdapter {
+  loadDatabase(): Promise<{
+    schema: PropertyDefinition[];
+    views: DatabaseViewConfig[];
+  }>;
+
+  createRow(params: {
+    id: string;
+    properties: Record<string, PropertyValue>;
+    position: string;
+  }): Promise<DatabaseRow>;
+
+  updateRow(params: {
+    rowId: string;
+    properties: Record<string, PropertyValue>;
+  }): Promise<DatabaseRow>;
+
+  moveRow(params: {
+    rowId: string;
+    position: string;
+  }): Promise<DatabaseRow>;
+
+  deleteRow(params: {
+    rowId: string;
+  }): Promise<void>;
+
+  createProperty(params: {
+    id: string;
+    name: string;
+    type: PropertyType;
+    position: string;
+    config?: PropertyConfig;
+  }): Promise<PropertyDefinition>;
+
+  updateProperty(params: {
+    propertyId: string;
+    changes: Partial<Pick<PropertyDefinition, 'name' | 'config'>>;
+  }): Promise<PropertyDefinition>;
+
+  deleteProperty(params: {
+    propertyId: string;
+  }): Promise<void>;
+
+  createView(params: {
+    id: string;
+    name: string;
+    type: ViewType;
+    position: string;
+    groupBy?: string;
+    sorts?: SortConfig[];
+    filters?: FilterConfig[];
+    visibleProperties?: string[];
+  }): Promise<DatabaseViewConfig>;
+
+  updateView(params: {
+    viewId: string;
+    changes: Partial<Pick<DatabaseViewConfig,
+      'name' | 'type' | 'position' | 'groupBy' | 'sorts' | 'filters' | 'visibleProperties'
+    >>;
+  }): Promise<DatabaseViewConfig>;
+
+  deleteView(params: {
+    viewId: string;
+  }): Promise<void>;
+}
+
+export interface DatabaseConfig {
+  adapter?: DatabaseAdapter;
+}

package/types/tools-entry.d.ts

@@ -11,8 +11,9 @@ import { ToggleConstructable, ToggleData, ToggleConfig } from './tools/toggle';
 import { DividerConstructable, DividerData } from './tools/divider';
 import { CalloutConstructable, CalloutData, CalloutConfig } from './tools/callout';
 import { QuoteConstructable, QuoteData } from './tools/quote';
+import { BlockToolConstructable } from './tools/block-tool';
+import { DatabaseData, DatabaseConfig, DatabaseAdapter, DatabaseViewConfig, DatabaseRowData } from './tools/database';
 import { InlineToolConstructable } from './tools/inline-tool';
-import { BlockTuneConstructable } from './block-tunes';
 import { ToolSettings } from './tools';
 
 // Block tools
@@ -24,6 +25,8 @@ export const Toggle: ToggleConstructable;
 export const Divider: DividerConstructable;
 export const Callout: CalloutConstructable;
 export const Quote: QuoteConstructable;
+export const Database: BlockToolConstructable;
+export const DatabaseRow: BlockToolConstructable;  // DatabaseRowTool (block tool), distinct from DatabaseRow interface in types/tools/database.d.ts
 
 // Re-export data and config types for convenience
 export { HeaderData, HeaderConfig } from './tools/header';
@@ -34,6 +37,7 @@ export { ToggleData, ToggleConfig } from './tools/toggle';
 export { DividerData } from './tools/divider';
 export { CalloutData, CalloutConfig } from './tools/callout';
 export { QuoteData } from './tools/quote';
+export { DatabaseData, DatabaseConfig, DatabaseAdapter, DatabaseViewConfig, DatabaseRowData } from './tools/database';
 
 // Inline tools
 export const Bold: InlineToolConstructable;
@@ -44,9 +48,6 @@ export const Marker: InlineToolConstructable;
 export const Strikethrough: InlineToolConstructable;
 export const Underline: InlineToolConstructable;
 
-// Block tunes
-export const Delete: BlockTuneConstructable;
-
 /**
  * Default block tools configuration
  */
@@ -57,6 +58,8 @@ export const defaultBlockTools: {
   readonly table: {};
   readonly toggle: {};
   readonly callout: {};
+  readonly database: {};
+  readonly 'database-row': {};
   readonly divider: {};
   readonly quote: {};
 };

package/types/utils/popover/popover.d.ts

@@ -146,6 +146,12 @@ export interface PopoverNodes {
 
   /** Popover items wrapper */
   items: HTMLElement;
+
+  /** Top scroll haze gradient overlay */
+  scrollHazeTop: HTMLElement;
+
+  /** Bottom scroll haze gradient overlay */
+  scrollHazeBottom: HTMLElement;
 }
 
 /**