@targoninc/jess-components 0.0.42 → 0.0.44

package/README.md

@@ -0,0 +1,23 @@
+# Example usage - Button
+
+```typescript
+import {button} from "@targoninc/jess-components";
+
+const disabled = signal(false);
+
+const element = button({
+    text: "Info",
+    disabled: disabled,
+    icon: {
+        icon: "/assets/buttonIcon.svg",
+        adaptive: true,
+        isUrl: true
+    },
+    onclick: () => {
+        console.log("button clicked");
+        disabled.value = true;
+    },
+});
+
+document.body.appendChild(element);
+```

package/dist/src/index.d.ts

@@ -1,2 +1,11 @@
+/**
+ * Entry point for the `jess-components` package.
+ *
+ * Re-exports all public component factories from `src/Components` and all
+ * shared type definitions from `src/Types` so consumers can import from the
+ * package root.
+ *
+ * @module jess-components
+ */
 export * from "./src/Components";
 export * from "./src/Types";

package/dist/src/src/Components.d.ts

@@ -1,18 +1,126 @@
 import type { BooleanConfig, ButtonConfig, ContainerConfig, HeadingConfig, IconConfig, InputConfig, SearchableSelectConfig, SelectConfig, SelectOptionConfig, TextareaConfig, TextConfig } from "./Types.ts";
 import { type AnyElement, Signal, type StringOrSignal } from "@targoninc/jess";
+/**
+ * Creates a button element.
+ *
+ * Renders optional icon and text, applies disabled styling from `config.disabled`,
+ * and wires the `onclick` handler.
+ *
+ * @param config - {@link ButtonConfig} for the button.
+ * @returns A Jess element representing a `<button>`.
+ */
 export declare function button(config: ButtonConfig): AnyElement;
+/**
+ * Creates a labeled input control with validation and optional debouncing.
+ *
+ * Shows error messages from `validators` and `required` when `touched`.
+ * Supports password visibility toggle when `type === InputType.password`.
+ *
+ * @typeParam T - Value type for the input component.
+ * @param config - {@link InputConfig} describing the input.
+ * @returns A Jess element representing the input control.
+ */
 export declare function input<T>(config: InputConfig<T>): AnyElement;
+/**
+ * Helper that renders an eye icon button used by password inputs.
+ *
+ * @param toggleState - Signal toggled when the button is clicked.
+ * @param onClick - Callback invoked on click.
+ * @returns A Jess element representing the eye icon button.
+ */
 export declare function eyeButton(toggleState: Signal<boolean>, onClick: Function): AnyElement;
+/**
+ * Creates a labeled `<textarea>` with validation handling.
+ *
+ * @param config - {@link TextareaConfig} for the textarea.
+ * @returns A Jess element representing the textarea control.
+ */
 export declare function textarea(config: TextareaConfig): AnyElement;
+/**
+ * Renders a list of validation errors.
+ *
+ * @param errors - Signal containing error messages.
+ * @returns A Jess element with error items.
+ */
 export declare function errorList(errors: Signal<string[]>): any;
+/**
+ * Renders a single error message.
+ *
+ * @param error - Error message content.
+ * @returns A Jess element representing the error line.
+ */
 export declare function error(error: StringOrSignal): AnyElement;
+/**
+ * Creates a simple bordered area container.
+ *
+ * @param config - {@link ContainerConfig} for the container.
+ * @returns A Jess element representing the area container.
+ */
 export declare function area(config: ContainerConfig): AnyElement;
+/**
+ * Creates a generic container element with provided `tag` and `children`.
+ *
+ * @param config - {@link ContainerConfig}.
+ * @returns A Jess element for the container.
+ */
 export declare function container(config: ContainerConfig): AnyElement;
+/**
+ * Renders text inside a given `tag` (e.g., `span`, `p`).
+ *
+ * @param config - {@link TextConfig}.
+ * @returns A Jess element for the text node.
+ */
 export declare function text(config: TextConfig): AnyElement;
+/**
+ * Renders a heading (h1-h6) based on `level`.
+ *
+ * @param config - {@link HeadingConfig}.
+ * @returns A Jess heading element.
+ */
 export declare function heading(config: HeadingConfig): AnyElement;
+/**
+ * Renders an icon element. If `isUrl` is truthy, renders an `<img>`; otherwise,
+ * renders an inline icon. When `adaptive` is true, adapts styles to context.
+ *
+ * @param config - {@link IconConfig} specifying icon source and behavior.
+ * @returns A signal of Jess element, allowing updates when icon-related signals change.
+ */
 export declare function icon(config: IconConfig): Signal<AnyElement>;
+/**
+ * Renders a non-searchable select control.
+ *
+ * @typeParam T - Type of the option value.
+ * @param config - {@link SelectConfig} for the select.
+ * @returns A Jess element for the select control.
+ */
 export declare function select<T = any>(config: SelectConfig<T>): AnyElement;
+/**
+ * Renders a searchable select control with a filterable dropdown.
+ *
+ * @typeParam T - Type of the option value.
+ * @param config - {@link SearchableSelectConfig} for the control.
+ * @returns A Jess element for the searchable select.
+ */
 export declare function searchableSelect<T = any>(config: SearchableSelectConfig<T>): AnyElement;
+/**
+ * Renders a single selectable option for the searchable select dropdown.
+ *
+ * @typeParam T - Type of the option value.
+ * @param config - {@link SelectOptionConfig} for the option.
+ * @returns A Jess element representing the option.
+ */
 export declare function searchSelectOption<T = any>(config: SelectOptionConfig<T>): AnyElement;
+/**
+ * Renders a checkbox control with label and validation support.
+ *
+ * @param config - {@link BooleanConfig}.
+ * @returns A Jess element for the checkbox.
+ */
 export declare function checkbox(config: BooleanConfig): AnyElement;
+/**
+ * Renders a binary on/off toggle switch with label and validation support.
+ *
+ * @param config - {@link BooleanConfig}.
+ * @returns A Jess element for the toggle switch.
+ */
 export declare function toggle(config: BooleanConfig): AnyElement;

package/dist/src/src/Debounce.d.ts

@@ -1 +1,9 @@
+/**
+ * Debounces the provided `func` by the specified `delay` using the unique
+ * `identifier`. If `delay` is `0` or falsy, `func` runs immediately.
+ *
+ * @param identifier - Unique key for the debounced action.
+ * @param func - Callback to execute after the delay.
+ * @param delay - Delay in milliseconds (default: `0`).
+ */
 export declare function debounce(identifier: any, func: () => void, delay?: number): void;

package/dist/src/src/Types.d.ts

@@ -1,6 +1,29 @@
+/**
+ * Shared type and interface definitions used by `jess-components`.
+ *
+ * These types model the configuration objects accepted by the component
+ * factory functions in `Components.ts` and are part of the public API.
+ *
+ * @module jess-components/types
+ */
 import { type CssClass, DomNode, type EventHandler, type HtmlPropertyValue, InputType, Signal, type StringOrSignal, type TypeOrSignal } from "@targoninc/jess";
+/**
+ * Utility type to enumerate numeric literal union `[0, 1, ..., N-1]`.
+ *
+ * @typeParam N - Upper bound (exclusive).
+ */
 type Enumerate<N extends number, Acc extends number[] = []> = Acc['length'] extends N ? Acc[number] : Enumerate<N, [...Acc, Acc['length']]>;
+/**
+ * Utility type that produces a numeric literal union from `F` (inclusive)
+ * up to `T` (exclusive).
+ *
+ * @typeParam F - Start of range (inclusive).
+ * @typeParam T - End of range (exclusive).
+ */
 type IntRange<F extends number, T extends number> = Exclude<Enumerate<T>, Enumerate<F>>;
+/**
+ * Base configuration applied to most components.
+ */
 export interface BaseComponentConfig {
     classes?: StringOrSignal[];
     attributes?: StringOrSignal[];
@@ -12,13 +35,23 @@ export interface BaseComponentConfig {
     ariaLabel?: HtmlPropertyValue;
     css?: CssClass;
 }
+/**
+ * Configuration for a clickable button component.
+ */
 export interface ButtonConfig extends BaseComponentConfig {
     text?: StringOrSignal;
     onclick: EventHandler<MouseEvent>;
     icon?: IconConfig;
     disabled?: TypeOrSignal<boolean>;
 }
+/**
+ * Function used to validate values for changeable components.
+ * Should return an array of error messages or `null/undefined` if valid.
+ */
 export type ValidatorFunction<T> = (value: T) => (string[] | null | undefined) | Promise<string[] | null | undefined>;
+/**
+ * Base configuration for input-like components that can change value.
+ */
 export interface ChangeableConfig<T = any> extends BaseComponentConfig {
     onchange?: (value: T) => void;
     validators?: ValidatorFunction<T>[];
@@ -27,6 +60,11 @@ export interface ChangeableConfig<T = any> extends BaseComponentConfig {
     label?: HtmlPropertyValue;
     disabled?: TypeOrSignal<boolean>;
 }
+/**
+ * Configuration for the `input` component.
+ *
+ * @typeParam T - The value type of the input.
+ */
 export interface InputConfig<T> extends ChangeableConfig<T> {
     name: StringOrSignal;
     type: TypeOrSignal<InputType>;
@@ -38,6 +76,9 @@ export interface InputConfig<T> extends ChangeableConfig<T> {
     infoText?: StringOrSignal;
     debounce?: number;
 }
+/**
+ * Configuration for the `textarea` component.
+ */
 export interface TextareaConfig extends ChangeableConfig<string> {
     name: StringOrSignal;
     value: StringOrSignal;
@@ -45,26 +86,41 @@ export interface TextareaConfig extends ChangeableConfig<string> {
     rows?: TypeOrSignal<number>;
     resize?: "both" | "horizontal" | "vertical" | "none";
 }
+/**
+ * Configuration for a generic container/section component.
+ */
 export interface ContainerConfig extends BaseComponentConfig {
     tag: string;
     children: (DomNode)[];
 }
+/**
+ * Configuration for generic text elements (e.g., `span`, `p`).
+ */
 export interface TextConfig extends BaseComponentConfig {
     text: HtmlPropertyValue;
     tag: string;
 }
+/**
+ * Configuration for the `icon` component.
+ */
 export interface IconConfig extends BaseComponentConfig {
     icon: StringOrSignal;
     adaptive?: boolean;
     isUrl?: TypeOrSignal<boolean>;
     onclick?: Function;
 }
+/**
+ * Represents a single option for a select component.
+ */
 export interface SelectOption<T> extends BaseComponentConfig {
     image?: string;
     imageIsUrl?: boolean;
     name: any;
     id: any | T;
 }
+/**
+ * Internal configuration passed to `searchSelectOption`.
+ */
 export interface SelectOptionConfig<T> extends BaseComponentConfig {
     option: SelectOption<T>;
     value: Signal<any>;
@@ -72,15 +128,29 @@ export interface SelectOptionConfig<T> extends BaseComponentConfig {
     optionsVisible: Signal<boolean>;
     selectedId: Signal<any>;
 }
+/**
+ * Configuration for the `searchableSelect` and `select` components.
+ *
+ * @typeParam T - The type of the selected value.
+ */
 export interface SearchableSelectConfig<T = string> extends ChangeableConfig<T> {
     options: Signal<SelectOption<T>[]>;
     value: Signal<T>;
 }
+/**
+ * Alias for a simple select configuration.
+ */
 export type SelectConfig<T> = SearchableSelectConfig<T>;
+/**
+ * Configuration for the `heading` component.
+ */
 export interface HeadingConfig extends BaseComponentConfig {
     level?: IntRange<1, 6>;
     text: StringOrSignal;
 }
+/**
+ * Configuration for boolean components like `checkbox` and `toggle`.
+ */
 export interface BooleanConfig extends ChangeableConfig<boolean> {
     text: HtmlPropertyValue;
     checked: TypeOrSignal<boolean>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@targoninc/jess-components",
   "type": "module",
-  "version": "0.0.42",
+  "version": "0.0.44",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [