native-document 1.0.164 → 1.0.166

package/src/components/stacks/types/Stack.d.ts

@@ -0,0 +1,39 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { BaseComponent } from '../../BaseComponent';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type StackDescription = {
+        orientation: 'horizontal' | 'vertical';
+        content: ValidChild;
+        spacing: string | number | null;
+        alignment: string;
+        justifyContent: string;
+        wrap: boolean;
+        grow: boolean;
+        shrink: boolean;
+        reverse: boolean;
+        props: GlobalAttributes;
+    };
+
+export interface StackInterface extends BaseComponent {
+    wrap(enabled?: boolean): this;
+    grow(enabled?: boolean): this;
+    reverse(enabled?: boolean): this;
+    shrink(enabled?: boolean): this;
+    spacing(value: string | number): this;
+    alignLeading(): this;
+    alignCenter(): this;
+    alignTrailing(): this;
+    alignStretch(): this;
+    justifyStart(): this;
+    justifyCenter(): this;
+    justifyEnd(): this;
+    justifyBetween(): this;
+    justifyAround(): this;
+    center(): this;
+
+    render(renderFn: (description: StackDescription, instance: StackInterface) => ValidChild): this;
+}
+
+
+export declare function Stack(content: ValidChild, props?: Record<string, unknown>): StackInterface;

package/src/components/stacks/types/VStack.d.ts

@@ -0,0 +1,16 @@
+import type { ValidChild } from '../../../../types/elements';
+import type {StackDescription, StackInterface} from './Stack';
+
+export interface VStackInterface extends StackInterface {}
+
+
+export declare function VStack(content: ValidChild, props?: Record<string, unknown>): VStackInterface;
+export declare namespace VStack {
+
+
+    function use(template: (description: StackDescription, instance: VStackInterface) => ValidChild): void;
+    function preset(name: string, callback: (instance: VStackInterface) => VStackInterface): void;
+    function presets(presets: Record<string, (instance: VStackInterface) => VStackInterface>): void;
+
+
+}

package/src/components/stepper/Stepper.js

@@ -1,9 +1,30 @@
-import BaseComponent from "../BaseComponent";
-import HasEventEmitter from "../../core/utils/HasEventEmitter";
-import { $ } from "../../core/data/Observable";
-import DebugManager from "../../core/utils/debug-manager";
-import StepperStep from "./StepperStep";
-
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+import { $ } from '../../core/data/Observable';
+import DebugManager from '../../core/utils/debug-manager';
+import StepperStep from './StepperStep';
+
+/**
+ * Multi-step wizard. Supports linear/non-linear modes, horizontal/vertical orientation, editable steps, and step indicator rendering.
+ *
+ *
+ * @example
+ * const stepper = new Stepper()
+ *     .horizontal()
+ *     .linear()
+ *     .step(new StepperStep(Span('Account')).content(AccountForm()))
+ *     .step(new StepperStep(Span('Profile')).content(ProfileForm()))
+ *     .step(new StepperStep(Span('Confirm')).content(ConfirmForm()))
+ *     .onComplete(() => finalize())
+ *     .onStepChange((index) => console.log(\`step \${index}\`));
+ *
+ * Stepper.use((description, instance) => {
+ *     return Div({ class: 'stepper' });
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
+ */
 export default function Stepper(props = {}) {
     if(!(this instanceof Stepper)) {
         return new Stepper(props);
@@ -27,7 +48,7 @@ export default function Stepper(props = {}) {
         renderContent: null,
         render: null,
         position: 'bottom',
-        props
+        props,
     };
 
     this.$element = null;
@@ -38,10 +59,35 @@ BaseComponent.use(Stepper, HasEventEmitter);
 
 Stepper.defaultTemplate = null;
 
+/**
+ * Registers the render template for Stepper.
+ * @param {(description: {
+ *     steps: ObservableArray<StepperStep>,
+ *     visibleSteps: ObservableArray<StepperStep>,
+ *     currentStep: Observable<number>,
+ *     orientation: 'horizontal'|'vertical',
+ *     linear: boolean,
+ *     alternativeLabel: boolean,
+ *     editable: Observable<boolean>,
+ *     showNumbers: boolean,
+ *     showConnector: boolean,
+ *     data: *|null,
+ *     renderStepIndicator: ((step: StepperStep, index: number) => NdChild)|null,
+ *     renderStepIndicatorConnector: ((desc: *) => NdChild)|null,
+ *     renderContent: ((step: StepperStep) => NdChild)|null,
+ *     render: ((desc: *, instance: Stepper) => NdChild)|null,
+ *     position: 'top'|'bottom'|'leading'|'trailing',
+ *     props: GlobalAttributes,
+ * }, instance: Stepper) => NdChild} template
+ */
 Stepper.use = function(template) {
     Stepper.defaultTemplate = template;
 };
 
+/**
+ * @param {string} name
+ * @param {(s: Stepper) => Stepper} callback
+ */
 Stepper.preset = function(name, callback) {
     if (Stepper.prototype[name] || Stepper[name]) {
         DebugManager.warn(`Warning: the ${name} method already exist in Stepper.`);
@@ -50,6 +96,9 @@ Stepper.preset = function(name, callback) {
     Stepper[name] = (props) => callback(new Stepper(props));
 };
 
+/**
+ * @param {Record<string, (s: Stepper) => Stepper>} presets
+ */
 Stepper.presets = function(presets) {
     for (const name in presets) {
         Stepper.preset(name, presets[name]);
@@ -82,7 +131,7 @@ Stepper.prototype.$build = function() {
             for (let i = 0; i < visibleSteps.length; i++) {
                 const itemStep = visibleSteps.get(i);
                 if (steps.indexOf(itemStep) < originalIndex) {
-                    stepBefore = itemStep
+                    stepBefore = itemStep;
                     continue;
                 }
                 break;
@@ -103,6 +152,10 @@ Stepper.prototype.$build = function() {
     return this.$originalBuild();
 };
 
+/**
+ * @param {StepperStep|((step: StepperStep, stepper: Stepper) => void)} step
+ * @returns {this}
+ */
 Stepper.prototype.step = function(step) {
     let finalStep = null;
     if(typeof step === 'function') {
@@ -119,62 +172,104 @@ Stepper.prototype.step = function(step) {
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Stepper.prototype.clear = function() {
     this.$description.steps.clear();
     this.$description.visibleSteps.clear();
     return this;
 };
 
+/**
+ * @param {number} [step]
+ * @returns {number|this}
+ */
 Stepper.prototype.currentStep = function(step) {
     return this.$description.currentStep.val();
 };
 
+/**
+ * @param {string} orientation
+ * @returns {this}
+ */
 Stepper.prototype.orientation = function(orientation) {
     this.$description.orientation = orientation;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Stepper.prototype.horizontal = function() {
     this.$description.orientation = 'horizontal';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Stepper.prototype.vertical = function() {
     this.$description.orientation = 'vertical';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Stepper.prototype.linear = function() {
     this.$description.linear = true;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Stepper.prototype.nonLinear = function() {
     this.$description.linear = false;
     return this;
 };
 
+/**
+ * @param {*} [editable]
+ * @returns {this}
+ */
 Stepper.prototype.editable = function(editable = true) {
     this.$description.editable.set(editable);
     return this;
 };
 
+/**
+ * @param {*} [alternative]
+ * @returns {this}
+ */
 Stepper.prototype.alternativeLabel = function(alternative = true) {
     this.$description.alternativeLabel = alternative;
     return this;
 };
 
+/**
+ * @param {NdChild} [show]
+ * @returns {this}
+ */
 Stepper.prototype.showNumbers = function(show = true) {
     this.$description.showNumbers = show;
     return this;
 };
 
+/**
+ * @param {NdChild} [show]
+ * @returns {this}
+ */
 Stepper.prototype.showConnector = function(show = true) {
     this.$description.showConnector = show;
     return this;
 };
 
-
+/**
+ * @param {*} data
+ * @returns {this}
+ */
 Stepper.prototype.data = function(data) {
     this.$description.data = data;
     return this;
@@ -200,6 +295,9 @@ Stepper.prototype.next = async function() {
     return this.goToStep(currentIdx + 1);
 };
 
+/**
+ * @returns {this}
+ */
 Stepper.prototype.previous = function() {
     const currentIdx = this.$description.currentStep.val();
     return this.goToStep(currentIdx - 1);
@@ -254,66 +352,108 @@ Stepper.prototype.reset = function() {
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 Stepper.prototype.onStepChange = function(handler) {
     this.on('stepChange', handler);
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 Stepper.prototype.onNext = function(handler) {
     this.on('next', handler);
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 Stepper.prototype.onPrevious = function(handler) {
     this.on('previous', handler);
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 Stepper.prototype.onComplete = function(handler) {
     this.on('complete', handler);
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 Stepper.prototype.onReset = function(handler) {
     this.on('reset', handler);
     return this;
 };
 
+/**
+ * @param {(step: StepperStep, index: number) => NdChild} renderFn
+ * @returns {this}
+ */
 Stepper.prototype.renderStepIndicator = function(renderFn) {
     this.$description.renderStepIndicator = renderFn;
     return this;
 };
 
+/**
+ * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @returns {this}
+ */
 Stepper.prototype.renderStepIndicatorConnector = function(renderFn) {
     this.$description.renderStepIndicatorConnector = renderFn;
     return this;
 };
 
+/**
+ * @param {(step: StepperStep) => NdChild} renderFn
+ * @returns {this}
+ */
 Stepper.prototype.renderContent = function(renderFn) {
     this.$description.renderContent = renderFn;
     return this;
 };
 
-
+/**
+ * @returns {this}
+ */
 Stepper.prototype.navigationAtLeading = function() {
     this.$description.position = 'leading';
     this.vertical();
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Stepper.prototype.navigationAtBottom = function() {
     this.$description.position = 'bottom';
     this.horizontal();
     return this;
 };
 
-
+/**
+ * @returns {this}
+ */
 Stepper.prototype.navigationAtTop = function() {
     this.$description.position = 'top';
-    this.horizontal()
+    this.horizontal();
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Stepper.prototype.navigationAtTrailing = function() {
     this.$description.position = 'trailing';
     this.vertical();

package/src/components/stepper/StepperStep.js

@@ -1,8 +1,26 @@
-import BaseComponent from "../BaseComponent";
+import BaseComponent from '../BaseComponent';
 import { $ } from '../../core/data/Observable';
 
 const NO_VALIDATION = () => true;
 
+/**
+ * A single step inside a Stepper. Manages label, description, icon, status (pending/completed/error), optional flag, and async validation.
+ *
+ *
+ * @example
+ * const step = new StepperStep(Span('Payment'))
+ *     .description(Span('Enter payment details'))
+ *     .content(PaymentForm())
+ *     .optional(false)
+ *     .validator(async (step) => {
+ *         return await validatePayment();
+ *     })
+ *     .onComplete(() => console.log('step done'));
+ *
+ * @constructor
+ * @param {NdChild} label
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function StepperStep(label, props = {}) {
     if(!(this instanceof StepperStep)) {
         return new StepperStep(label, props);
@@ -27,7 +45,7 @@ export default function StepperStep(label, props = {}) {
         key: null,
         index: $(0),
         isVisible: $(true),
-        props
+        props,
     };
 }
 
@@ -35,6 +53,26 @@ BaseComponent.extends(StepperStep);
 
 StepperStep.defaultTemplate = null;
 
+/**
+ * Registers the render template for StepperStep.
+ * @param {(description: {
+ *     icon: NdChild|null,
+ *     label: NdChild,
+ *     description: NdChild|null,
+ *     content: NdChild|null,
+ *     status: Observable<'pending'|'completed'|'error'>,
+ *     optional: Observable<boolean>,
+ *     disabled: Observable<boolean>,
+ *     completed: Observable<boolean>,
+ *     error: Observable<boolean>,
+ *     data: *|null,
+ *     render: ((desc: *, instance: StepperStep) => NdChild)|null,
+ *     key: string|null,
+ *     index: Observable<number>,
+ *     isVisible: Observable<boolean>,
+ *     props: GlobalAttributes,
+ * }, instance: StepperStep) => NdChild} template
+ */
 StepperStep.use = function(template) {
     StepperStep.defaultTemplate = template;
 };
@@ -48,42 +86,72 @@ StepperStep.prototype.$setIndex = function(index) {
     return this;
 };
 
-
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
 StepperStep.prototype.icon = function(icon) {
     this.$description.icon = icon;
     return this;
 };
 
+/**
+ * @param {NdChild} label
+ * @returns {this}
+ */
 StepperStep.prototype.label = function(label) {
     this.$description.label = label;
     return this;
 };
 
+/**
+ * @param {NdChild} description
+ * @returns {this}
+ */
 StepperStep.prototype.description = function(description) {
     this.$description.description = description;
     return this;
 };
 
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
 StepperStep.prototype.content = function(content) {
     this.$description.content = content;
     return this;
 };
 
+/**
+ * @param {'pending'|'completed'|'error'} status
+ * @returns {this}
+ */
 StepperStep.prototype.status = function(status) {
     this.$description.status.set(status);
     return this;
 };
 
+/**
+ * @param {*} [optional]
+ * @returns {this}
+ */
 StepperStep.prototype.optional = function(optional = true) {
     this.$description.optional.set(optional);
     return this;
 };
 
+/**
+ * @param {boolean|Observable<boolean>} [disabled]
+ * @returns {this}
+ */
 StepperStep.prototype.disabled = function(disabled = true) {
     this.$description.disabled.set(disabled);
     return this;
 };
 
+/**
+ * @param {'pending'|'completed'|'error'} status
+ */
 StepperStep.prototype.updateStatus = function(status) {
     const isCompleted = status === 'completed';
     const isError = status === 'error';
@@ -94,42 +162,75 @@ StepperStep.prototype.updateStatus = function(status) {
     return this;
 };
 
+/**
+ * @param {*} [completed]
+ * @returns {this}
+ */
 StepperStep.prototype.completed = function(completed = true) {
     return this.updateStatus(completed ? 'completed' : 'pending');
 };
 
+/**
+ * @param {*} [error]
+ * @returns {this}
+ */
 StepperStep.prototype.error = function(error = true) {
     return this.updateStatus(error ? 'error' : 'pending');
 };
 
+/**
+ * @returns {this}
+ */
 StepperStep.prototype.reset = function() {
     return this.updateStatus('pending');
 };
 
+/**
+ * @param {*} data
+ * @returns {this}
+ */
 StepperStep.prototype.data = function(data) {
     this.$description.data = data;
     return this;
 };
 
+/**
+ * @param {string} key
+ * @returns {this}
+ */
 StepperStep.prototype.key = function(key) {
     this.$description.key = key;
     return this;
 };
 
+/**
+ * @returns {string}
+ */
 StepperStep.prototype.getKey = function() {
     return this.$description.key;
 };
 
+/**
+ * @param {Observable<boolean>|boolean|(() => Observable<boolean>)} condition
+ * @returns {this}
+ */
 StepperStep.prototype.visibility = function(condition) {
     this.$description.visibility = (typeof condition === 'function' ?  condition() : condition);
     return this;
 };
 
+/**
+ * @param {(step: StepperStep) => boolean|Promise<boolean>} validatorFn
+ * @returns {this}
+ */
 StepperStep.prototype.validator = function(validatorFn) {
     this.$description.validator = validatorFn;
     return this;
 };
 
+/**
+ * @returns {boolean}
+ */
 StepperStep.prototype.validate = function() {
     if (this.$description.validator) {
         const isValid = this.$description.validator(this);

package/src/components/stepper/index.js

@@ -1,8 +1,8 @@
-import Stepper from "./Stepper";
-import StepperStep from "./StepperStep";
+import Stepper from './Stepper';
+import StepperStep from './StepperStep';
 
 
 export {
     Stepper,
-    StepperStep
-}
+    StepperStep,
+};

package/src/components/stepper/types/Stepper.d.ts

@@ -0,0 +1,68 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+import type { StepperStepInterface } from './StepperStep';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type StepperDescription = {
+        steps: ObservableItem<StepperStepInterface[]>;
+        visibleSteps: ObservableItem<StepperStepInterface[]>;
+        currentStep: ObservableItem<number>;
+        orientation: 'horizontal' | 'vertical';
+        linear: boolean;
+        alternativeLabel: boolean;
+        editable: ObservableItem<boolean>;
+        showNumbers: boolean;
+        showConnector: boolean;
+        data: unknown | null;
+        renderStepIndicator: ((step: StepperStepInterface, index: number) => ValidChild) | null;
+        renderStepIndicatorConnector: ((desc: unknown) => ValidChild) | null;
+        renderContent: ((step: StepperStepInterface) => ValidChild) | null;
+        render: ((desc: StepperDescription, instance: StepperInterface) => ValidChild) | null;
+        position: 'top' | 'bottom' | 'leading' | 'trailing';
+        props: GlobalAttributes;
+    };
+
+export interface StepperInterface extends BaseComponent {
+    step(step: StepperStepInterface | ((step: StepperStepInterface, stepper: StepperInterface) => void)): this;
+    clear(): this;
+    currentStep(step?: number): number | this;
+    orientation(orientation: 'horizontal' | 'vertical'): this;
+    horizontal(): this;
+    vertical(): this;
+    linear(): this;
+    nonLinear(): this;
+    editable(editable?: boolean): this;
+    alternativeLabel(alternative?: boolean): this;
+    showNumbers(show?: boolean): this;
+    showConnector(show?: boolean): this;
+    data(data: unknown): this;
+    previous(): this;
+    reset(): this;
+    onStepChange(handler: (index: number) => void): this;
+    onNext(handler: () => void): this;
+    onPrevious(handler: () => void): this;
+    onComplete(handler: () => void): this;
+    onReset(handler: () => void): this;
+    renderStepIndicator(renderFn: (step: StepperStepInterface, index: number) => ValidChild): this;
+    renderStepIndicatorConnector(renderFn: (desc: unknown) => ValidChild): this;
+    renderContent(renderFn: (step: StepperStepInterface) => ValidChild): this;
+    navigationAtLeading(): this;
+    navigationAtBottom(): this;
+    navigationAtTop(): this;
+    navigationAtTrailing(): this;
+
+    render(renderFn: (description: StepperDescription, instance: StepperInterface) => ValidChild): this;
+}
+
+
+export declare function Stepper(props?: Record<string, unknown>): StepperInterface;
+export declare namespace Stepper {
+
+
+    function use(template: (description: StepperDescription, instance: StepperInterface) => ValidChild): void;
+    function preset(name: string, callback: (instance: StepperInterface) => StepperInterface): void;
+    function presets(presets: Record<string, (instance: StepperInterface) => StepperInterface>): void;
+
+
+}