native-document 1.0.165 → 1.0.168

package/src/components/splitter/Splitter.js

@@ -1,8 +1,24 @@
-import BaseComponent from "../BaseComponent";
-import HasEventEmitter from "../../core/utils/HasEventEmitter";
-import Validator from "../../core/utils/validator";
-import SplitterPanel from "./SplitterPanel";
-
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+import Validator from '../../core/utils/validator';
+import SplitterPanel from './SplitterPanel';
+import { $ } from '../../core/data/Observable';
+
+/**
+ * Resizable split-pane layout. Supports horizontal/vertical orientation, gutter size, collapsible panels, and dynamic panel management.
+ *
+ *
+ * @example
+ * const splitter = new Splitter()
+ *     .horizontal()
+ *     .gutterSize(6)
+ *     .panel(Div('Left content'), { minSize: '200px' })
+ *     .panel(Div('Right content'), { minSize: '300px' })
+ *     .onResize((sizes) => console.log(sizes));
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
+ */
 export default function Splitter(props = {}) {
     if(!(this instanceof Splitter)) {
         return new Splitter(props);
@@ -15,7 +31,7 @@ export default function Splitter(props = {}) {
         panels: [],
         gutterSize: 8,
         render: null,
-        props
+        props,
     };
 
     this.$element = null;
@@ -26,35 +42,68 @@ BaseComponent.use(Splitter, HasEventEmitter);
 
 Splitter.defaultTemplate = null;
 
+/**
+ * Registers the render template for Splitter.
+ * @param {(description: {
+ *     orientation: 'horizontal'|'vertical',
+ *     panels: SplitterPanel[]|Observable<SplitterPanel[]>,
+ *     gutterSize: number,
+ *     render: ((desc: *, instance: Splitter) => NdChild)|null,
+ *     props: GlobalAttributes,
+ * }, instance: Splitter) => NdChild} template
+ */
 Splitter.use = function(template) {
     Splitter.defaultTemplate = template;
 };
 
+/**
+ * @returns {this}
+ */
 Splitter.prototype.dynamic = function(){
     this.$description.panels = $.array([]);
     return this;
 };
 
+/**
+ * @param {string} orientation
+ * @returns {this}
+ */
 Splitter.prototype.orientation = function(orientation) {
     this.$description.orientation = orientation;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Splitter.prototype.horizontal = function() {
     this.$description.orientation = 'horizontal';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Splitter.prototype.vertical = function() {
     this.$description.orientation = 'vertical';
     return this;
 };
 
+/**
+ * @param {number} gutterSize
+ * @returns {this}
+ */
 Splitter.prototype.gutterSize = function(gutterSize) {
     this.$description.gutterSize = gutterSize;
     return this;
 };
 
+/**
+ * @param {SplitterPanel|NdChild} content
+ * @param {GlobalAttributes} [options={}]
+ * @param {GlobalAttributes} [props={}]
+ * @returns {this}
+ */
 Splitter.prototype.panel = function(content, options = {}, props = {}) {
     const panel = content instanceof SplitterPanel
         ? content
@@ -63,6 +112,10 @@ Splitter.prototype.panel = function(content, options = {}, props = {}) {
     return this;
 };
 
+/**
+ * @param {SplitterPanel[]} panels
+ * @returns {this}
+ */
 Splitter.prototype.panels = function(panels) {
     if(Validator.isObservable(this.$description.panels)) {
         this.$description.panels.clear();
@@ -73,29 +126,39 @@ Splitter.prototype.panels = function(panels) {
     return this;
 };
 
-
+/**
+ * @param {SplitterPanel} panel
+ * @returns {this}
+ */
 Splitter.prototype.removePanel = function(panel) {
     this.$description.panels.remove(panel);
     // TODO: remove the unnecessary gutter
     return this;
-}
+};
 
+/**
+ * @param {(sizes: number[]) => void} handler
+ * @returns {this}
+ */
 Splitter.prototype.onResize = function(handler) {
     this.on('resize', handler);
     return this;
 };
 
+/**
+ * @param {(panel: SplitterPanel) => void} handler
+ * @returns {this}
+ */
 Splitter.prototype.onPanelAdd = function(handler) {
     this.on('panelAdd', handler);
     return this;
 };
 
+/**
+ * @param {(panel: SplitterPanel) => void} handler
+ * @returns {this}
+ */
 Splitter.prototype.onPanelRemove = function(handler) {
     this.on('panelRemove', handler);
     return this;
-};
-
-Splitter.prototype.render = function(renderFn) {
-    this.$description.render = renderFn;
-    return this;
 };

package/src/components/splitter/SplitterGutter.js

@@ -1,8 +1,22 @@
-import BaseComponent from "../BaseComponent";
-import HasEventEmitter from "../../core/utils/HasEventEmitter";
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
 import { $ } from '../../core/data/Observable';
 
-
+/**
+ * The drag handle between two SplitterPanel instances.
+ *
+ *
+ * @example
+ * const gutter = new SplitterGutter(leftPanel, rightPanel)
+ *     .horizontal()
+ *     .size(8)
+ *     .onDragStart(() => console.log('drag start'));
+ *
+ * @constructor
+ * @param {SplitterPanel} [leftPanel]
+ * @param {SplitterPanel} [rightPanel]
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function SplitterGutter(leftPanel, rightPanel, props = {}) {
     if(!(this instanceof SplitterGutter)) {
         return new SplitterGutter(leftPanel, rightPanel, props);
@@ -17,7 +31,7 @@ export default function SplitterGutter(leftPanel, rightPanel, props = {}) {
         cursor: 'col-resize',
         size: 2,
         isDragging: $(false),
-        props
+        props,
     };
 }
 
@@ -26,52 +40,100 @@ BaseComponent.use(SplitterGutter, HasEventEmitter);
 
 SplitterGutter.defaultTemplate = null;
 
+/**
+ * Registers the render template for SplitterGutter.
+ * @param {(description: {
+ *     leftPanel: SplitterPanel|null,
+ *     rightPanel: SplitterPanel|null,
+ *     orientation: 'horizontal'|'vertical',
+ *     cursor: string,
+ *     size: number,
+ *     isDragging: Observable<boolean>,
+ *     props: GlobalAttributes,
+ * }, instance: SplitterGutter) => NdChild} template
+ */
 SplitterGutter.use = function(template) {
     SplitterGutter.defaultTemplate = template;
 };
 
+/**
+ * @returns {this}
+ */
 SplitterGutter.prototype.vertical = function() {
     this.$description.orientation = 'vertical';
     this.$description.cursor = 'row-resize';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 SplitterGutter.prototype.horizontal = function() {
     this.$description.orientation = 'horizontal';
     this.$description.cursor = 'col-resize';
     return this;
-}
+};
 
+/**
+ * @param {SplitterPanel} leftPanel
+ * @param {SplitterPanel} rightPanel
+ * @returns {this}
+ */
 SplitterGutter.prototype.panels = function(leftPanel, rightPanel) {
     this.$description.leftPanel = leftPanel;
     this.$description.rightPanel = rightPanel;
     return this;
 };
 
+/**
+ * @param {SplitterPanel} leftPanel
+ * @returns {this}
+ */
 SplitterGutter.prototype.leftPanel = function(leftPanel) {
     this.$description.leftPanel = leftPanel;
     return this;
 };
+
+/**
+ * @param {SplitterPanel} rightPanel
+ * @returns {this}
+ */
 SplitterGutter.prototype.rightPanel = function(rightPanel) {
     this.$description.rightPanel = rightPanel;
     return this;
 };
 
+/**
+ * @param {number} size
+ * @returns {this}
+ */
 SplitterGutter.prototype.size = function(size) {
     this.$description.size = size;
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 SplitterGutter.prototype.onDragStart = function(handler) {
     this.on('dragStart', handler);
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 SplitterGutter.prototype.onDrag = function(handler) {
     this.on('drag', handler);
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 SplitterGutter.prototype.onDragEnd = function(handler) {
     this.on('dragEnd', handler);
     return this;

package/src/components/splitter/SplitterPanel.js

@@ -1,6 +1,22 @@
-import BaseComponent from "../BaseComponent";
+import BaseComponent from '../BaseComponent';
 import { $ } from '../../core/data/Observable';
 
+/**
+ * A resizable panel inside a Splitter. Configures size constraints and collapsed/collapsible state.
+ *
+ *
+ * @example
+ * const panel = new SplitterPanel(Div('Panel content'))
+ *     .size('30%')
+ *     .minSize('150px')
+ *     .maxSize('60%')
+ *     .collapsible(true)
+ *     .collapsed(false);
+ *
+ * @constructor
+ * @param {NdChild} [content]
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function SplitterPanel(content, props = {}) {
     if(!(this instanceof SplitterPanel)) {
         return new SplitterPanel(content, props);
@@ -19,7 +35,7 @@ export default function SplitterPanel(content, props = {}) {
         resizable: true,
         data: null,
         render: null,
-        props
+        props,
     };
 }
 
@@ -27,49 +43,100 @@ BaseComponent.extends(SplitterPanel);
 
 SplitterPanel.defaultTemplate = null;
 
+/**
+ * Registers the render template for SplitterPanel.
+ * @param {(description: {
+ *     orientation: 'horizontal'|'vertical',
+ *     content: NdChild|null,
+ *     size: Observable<string|number|null>,
+ *     minSize: string|number|null,
+ *     maxSize: string|number|null,
+ *     collapsible: boolean,
+ *     collapsed: boolean,
+ *     resizable: boolean,
+ *     data: *|null,
+ *     render: ((desc: *, instance: SplitterPanel) => NdChild)|null,
+ *     props: GlobalAttributes,
+ * }, instance: SplitterPanel) => NdChild} template
+ */
 SplitterPanel.use = function(template) {
     SplitterPanel.defaultTemplate = template;
 };
 
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
 SplitterPanel.prototype.content = function(content) {
     this.$description.content = content;
     return this;
 };
 
+/**
+ * @param {number} size
+ * @returns {this}
+ */
 SplitterPanel.prototype.size = function(size) {
     this.$description.size.set(size);
     return this;
 };
 
+/**
+ * @param {number} size
+ * @returns {this}
+ */
 SplitterPanel.prototype.minSize = function(size) {
     this.$description.minSize = size;
     return this;
 };
 
+/**
+ * @param {number} size
+ * @returns {this}
+ */
 SplitterPanel.prototype.maxSize = function(size) {
     this.$description.maxSize = size;
     return this;
 };
 
+/**
+ * @param {boolean} [collapsible]
+ * @returns {this}
+ */
 SplitterPanel.prototype.collapsible = function(collapsible = true) {
     this.$description.collapsible = collapsible;
     return this;
 };
 
+/**
+ * @param {*} [collapsed]
+ * @returns {this}
+ */
 SplitterPanel.prototype.collapsed = function(collapsed = true) {
     this.$description.collapsed = collapsed;
     return this;
 };
 
+/**
+ * @param {*} [resizable]
+ * @returns {this}
+ */
 SplitterPanel.prototype.resizable = function(resizable = true) {
     this.$description.resizable = resizable;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 SplitterPanel.prototype.fixed = function() {
     return this.resizable(false);
 };
 
+/**
+ * @param {*} data
+ * @returns {this}
+ */
 SplitterPanel.prototype.data = function(data) {
     this.$description.data = data;
     return this;

package/src/components/splitter/index.js

@@ -1,10 +1,10 @@
-import Splitter from "./Splitter";
-import SplitterPanel from "./SplitterPanel";
-import SplitterGutter from "./SplitterGutter";
+import Splitter from './Splitter';
+import SplitterPanel from './SplitterPanel';
+import SplitterGutter from './SplitterGutter';
 
 
 export {
     Splitter,
     SplitterPanel,
-    SplitterGutter
-}
+    SplitterGutter,
+};

package/src/components/splitter/types/Splitter.d.ts

@@ -0,0 +1,38 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+import type { SplitterPanelInterface } from './SplitterPanel';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type SplitterDescription = {
+        orientation: 'horizontal' | 'vertical';
+        panels: SplitterPanelInterface[] | ObservableItem<SplitterPanelInterface[]>;
+        gutterSize: number;
+        render: ((desc: SplitterDescription, instance: SplitterInterface) => ValidChild) | null;
+        props: GlobalAttributes;
+    };
+
+export interface SplitterInterface extends BaseComponent {
+    dynamic(): this;
+    orientation(orientation: 'horizontal' | 'vertical'): this;
+    horizontal(): this;
+    vertical(): this;
+    gutterSize(gutterSize: number): this;
+    panel(content: SplitterPanelInterface | ValidChild, options?: Record<string, unknown>, props?: Record<string, unknown>): this;
+    panels(panels: SplitterPanelInterface[]): this;
+    removePanel(panel: SplitterPanelInterface): this;
+    onResize(handler: (sizes: number[]) => void): this;
+    onPanelAdd(handler: (panel: SplitterPanelInterface) => void): this;
+    onPanelRemove(handler: (panel: SplitterPanelInterface) => void): this;
+    render(renderFn: (desc: SplitterDescription, instance: SplitterInterface) => ValidChild): this;
+}
+
+
+export declare function Splitter(props?: Record<string, unknown>): SplitterInterface;
+export declare namespace Splitter {
+
+
+    function use(template: (description: SplitterDescription, instance: SplitterInterface) => ValidChild): void;
+
+
+}

package/src/components/splitter/types/SplitterGutter.d.ts

@@ -0,0 +1,38 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { BaseComponent } from '../../BaseComponent';
+import type { SplitterPanelInterface } from './SplitterPanel';
+import type { GlobalAttributes } from '../../../../types/globals';
+import {ObservableItem} from "../../../../types/observable";
+
+export type SplitterGutterDescription = {
+        leftPanel: SplitterPanelInterface | null;
+        rightPanel: SplitterPanelInterface | null;
+        orientation: 'horizontal' | 'vertical';
+        cursor: string;
+        size: number;
+        isDragging: ObservableItem<boolean>;
+        props: GlobalAttributes;
+    };
+
+export interface SplitterGutterInterface extends BaseComponent {
+    vertical(): this;
+    horizontal(): this;
+    panels(leftPanel: SplitterPanelInterface, rightPanel: SplitterPanelInterface): this;
+    leftPanel(leftPanel: SplitterPanelInterface): this;
+    rightPanel(rightPanel: SplitterPanelInterface): this;
+    size(size: number): this;
+    onDragStart(handler: (event: MouseEvent) => void): this;
+    onDrag(handler: (event: MouseEvent) => void): this;
+    onDragEnd(handler: () => void): this;
+    render(renderFn: (description: SplitterGutterDescription, instance: SplitterGutterInterface) => ValidChild): this;
+}
+
+
+export declare function SplitterGutter(leftPanel?: SplitterPanelInterface, rightPanel?: SplitterPanelInterface, props?: Record<string, unknown>): SplitterGutterInterface;
+export declare namespace SplitterGutter {
+
+
+    function use(template: (description: SplitterGutterDescription, instance: SplitterGutterInterface) => ValidChild): void;
+
+
+}

package/src/components/splitter/types/SplitterPanel.d.ts

@@ -0,0 +1,41 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type SplitterPanelDescription = {
+        orientation: 'horizontal' | 'vertical';
+        content: ValidChild | null;
+        size: ObservableItem<string | number | null>;
+        minSize: string | number | null;
+        maxSize: string | number | null;
+        collapsible: boolean;
+        collapsed: boolean;
+        resizable: boolean;
+        data: unknown | null;
+        render: ((desc: SplitterPanelDescription, instance: SplitterPanelInterface) => ValidChild) | null;
+        props: GlobalAttributes;
+    };
+
+export interface SplitterPanelInterface extends BaseComponent {
+    content(content: ValidChild): this;
+    size(size: string | number): this;
+    minSize(size: string | number): this;
+    maxSize(size: string | number): this;
+    collapsible(collapsible?: boolean): this;
+    collapsed(collapsed?: boolean): this;
+    resizable(resizable?: boolean): this;
+    fixed(): this;
+    data(data: unknown): this;
+    render(renderFn: (description: SplitterPanelDescription, instance: SplitterPanelInterface) => ValidChild): this;
+}
+
+
+export declare function SplitterPanel(content?: ValidChild, props?: Record<string, unknown>): SplitterPanelInterface;
+export declare namespace SplitterPanel {
+
+
+    function use(template: (description: SplitterPanelDescription, instance: SplitterPanelInterface) => ValidChild): void;
+
+
+}

package/src/components/stacks/AbsoluteStack.js

@@ -1,7 +1,14 @@
-import BaseComponent from "../BaseComponent";
-import PositionStack from "./PositionStack";
-import DebugManager from "../../core/utils/debug-manager";
+import BaseComponent from '../BaseComponent';
+import PositionStack from './PositionStack';
+import DebugManager from '../../core/utils/debug-manager';
 
+/**
+ *
+ *
+ * @constructor
+ * @param {NdChild} content
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function AbsoluteStack(content, props = {}) {
     if(!(this instanceof AbsoluteStack)) {
         return new AbsoluteStack(content, props);
@@ -14,10 +21,20 @@ BaseComponent.extends(AbsoluteStack, PositionStack);
 
 AbsoluteStack.defaultTemplate = null;
 
+/**
+ * Registers the render template for AbsoluteStack.
+ * @param {(description: {
+ *     [key: string]: *
+ * }, instance: AbsoluteStack) => NdChild} template
+ */
 AbsoluteStack.use = function(template) {
     AbsoluteStack.defaultTemplate = template;
 };
 
+/**
+ * @param {string} name
+ * @param {(s: AbsoluteStack) => AbsoluteStack} callback
+ */
 AbsoluteStack.preset = function(name, callback) {
     if(AbsoluteStack.prototype[name] || AbsoluteStack[name]) {
         DebugManager.warn(`Warning: the ${name} method already exists in AbsoluteStack.`);
@@ -26,6 +43,9 @@ AbsoluteStack.preset = function(name, callback) {
     AbsoluteStack[name] = (content, props) => callback(new AbsoluteStack(content, props));
 };
 
+/**
+ * @param {Record<string, (s: AbsoluteStack) => AbsoluteStack>} presets
+ */
 AbsoluteStack.presets = function(presets) {
     for(const name in presets) {
         AbsoluteStack.preset(name, presets[name]);

package/src/components/stacks/FixedStack.js

@@ -1,7 +1,14 @@
-import BaseComponent from "../BaseComponent";
-import PositionStack from "./PositionStack";
-import DebugManager from "../../core/utils/debug-manager";
+import BaseComponent from '../BaseComponent';
+import PositionStack from './PositionStack';
+import DebugManager from '../../core/utils/debug-manager';
 
+/**
+ *
+ *
+ * @constructor
+ * @param {NdChild} content
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function FixedStack(content, props = {}) {
     if(!(this instanceof FixedStack)) {
         return new FixedStack(content, props);
@@ -14,10 +21,20 @@ BaseComponent.extends(FixedStack, PositionStack);
 
 FixedStack.defaultTemplate = null;
 
+/**
+ * Registers the render template for FixedStack.
+ * @param {(description: {
+ *     [key: string]: *
+ * }, instance: FixedStack) => NdChild} template
+ */
 FixedStack.use = function(template) {
     FixedStack.defaultTemplate = template;
 };
 
+/**
+ * @param {string} name
+ * @param {(s: FixedStack) => FixedStack} callback
+ */
 FixedStack.preset = function(name, callback) {
     if(FixedStack.prototype[name] || FixedStack[name]) {
         DebugManager.warn(`Warning: the ${name} method already exists in FixedStack.`);
@@ -26,6 +43,9 @@ FixedStack.preset = function(name, callback) {
     FixedStack[name] = (content, props) => callback(new FixedStack(content, props));
 };
 
+/**
+ * @param {Record<string, (s: FixedStack) => FixedStack>} presets
+ */
 FixedStack.presets = function(presets) {
     for(const name in presets) {
         FixedStack.preset(name, presets[name]);