@ptx-showcase/utils 0.2.4 → 0.3.0

package/dist/build-query-params/index.d.ts

@@ -1 +1,22 @@
+/**
+ * Builds a URL query string from an object, ready to be appended to a URL.
+ *
+ * - `undefined`, `null`, `''` (empty string) and empty arrays are skipped
+ * - Other values (including `0`, `false`, non-empty arrays) are stringified
+ *   via `String(value)` and appended as-is — arrays become comma-separated
+ *   (e.g. `[1, 2, 3]` → `h=1%2C2%2C3`), not repeated `key=value` pairs
+ * - Returns `''` (not `'?'`) when there are no params left after filtering
+ *
+ * @param params - Object whose entries become query string params
+ * @returns The query string including a leading `?`, or `''` if empty
+ *
+ * @example
+ * ```ts
+ * buildQueryParams({ a: 1, b: '', c: null, d: [1, 2] })
+ * // => '?a=1&d=1%2C2'
+ *
+ * buildQueryParams({ a: undefined, b: '' })
+ * // => ''
+ * ```
+ */
 export declare const buildQueryParams: <T extends object>(params: T) => string;

package/dist/build-sort-param/index.d.ts

@@ -1 +1,21 @@
+/**
+ * Builds the next value of a comma-separated sort param string by cycling a
+ * field through ascending → descending → removed, e.g. for toggling sort on
+ * table column clicks: `"" → "name" → "-name" → ""`.
+ *
+ * Other fields already present in `prev` are left untouched and keep their
+ * relative order; a newly added field is placed at the front of the list.
+ *
+ * @param field - The field name to toggle (without the `-` prefix)
+ * @param prev - The current comma-separated sort string (e.g. `"id,-name"`), if any
+ * @returns The updated comma-separated sort string
+ *
+ * @example
+ * ```ts
+ * buildSortParam('name')                    // => 'name'
+ * buildSortParam('name', 'name')             // => '-name'
+ * buildSortParam('name', '-name')            // => ''
+ * buildSortParam('name', 'id,-surname')      // => 'name,id,-surname'
+ * ```
+ */
 export declare const buildSortParam: (field: string, prev?: string) => string;

package/dist/clean-object/index.d.ts

@@ -1,6 +1,26 @@
 type EmptyValue = undefined | null | '';
+/**
+ * Result type of {@link cleanObject} — same shape as `T`, but every property
+ * becomes optional and `undefined`/`null`/`''` are excluded from its value type,
+ * reflecting that empty values are stripped from the resulting object.
+ */
 export type CleanObjectResult<T extends Record<string, unknown>> = Partial<{
     [K in keyof T]: Exclude<T[K], EmptyValue>;
 }>;
+/**
+ * Returns a shallow copy of `obj` with all `undefined`, `null` and `''` (empty string)
+ * properties removed. Other falsy values (`0`, `false`, empty arrays, etc.) are kept.
+ *
+ * Useful for trimming objects before sending them as query params or request payloads,
+ * where empty fields shouldn't be included.
+ *
+ * @param obj - The object to clean
+ *
+ * @example
+ * ```ts
+ * cleanObject({ a: 1, b: '', c: null, d: false, e: undefined })
+ * // => { a: 1, d: false }
+ * ```
+ */
 export declare const cleanObject: <T extends Record<string, unknown>>(obj: T) => CleanObjectResult<T>;
 export {};

package/dist/cookies/index.d.ts

@@ -1,5 +1,35 @@
 export type CookieOptions = Cookies.CookieAttributes;
+/**
+ * Default options applied to every {@link setCookie} call: expires in 1 hour,
+ * `secure` and `sameSite: 'Strict'`. Can be overridden per-call via `options`.
+ */
 export declare const defaultCookieOptions: CookieOptions;
+/**
+ * Sets a cookie, merging the given `options` over {@link defaultCookieOptions}.
+ *
+ * @param name - Cookie name
+ * @param value - Cookie value
+ * @param options - Overrides for the default cookie attributes (e.g. `expires`, `secure`, `sameSite`, `path`)
+ *
+ * @example
+ * ```ts
+ * setCookie('token', '123')
+ * setCookie('token', '123', { expires: 7, secure: false })
+ * ```
+ */
 export declare const setCookie: (name: string, value: string, options?: CookieOptions) => void;
+/**
+ * Returns the value of the cookie with the given name, or `undefined` if it doesn't exist.
+ *
+ * @param name - Cookie name
+ */
 export declare const getCookie: (name: string) => string | undefined;
+/**
+ * Removes the cookie with the given name.
+ *
+ * @param name - Cookie name
+ * @param options - Attributes the cookie was set with (e.g. `path`, `domain`) —
+ * required if the cookie was set with non-default attributes, since removal
+ * must match them for the browser to find and delete the cookie
+ */
 export declare const deleteCookie: (name: string, options?: CookieOptions) => void;

package/dist/download-file/index.d.ts

@@ -1,7 +1,29 @@
+/**
+ * Options for {@link downloadBlob} that determine the resulting filename.
+ *
+ * - `filename` — uses the given name as-is
+ * - `hash` — derives the filename from the hex-encoded SHA-1 hash of the given
+ *   value, useful when the original filename is unknown or shouldn't be exposed
+ */
 type DownloadBlobOptions = {
     filename: string;
 } | {
     hash: string | number;
 };
+/**
+ * Triggers a browser download of the given `Blob`, saving it under either an
+ * explicit filename or a name derived from the SHA-1 hash of a given value.
+ *
+ * @param blob - The `Blob` to download
+ * @param options - Either `{ filename }` to use an explicit name, or `{ hash }`
+ * to derive the filename from the SHA-1 hash of the given string/number
+ * @throws {Error} If `blob` is not a `Blob` instance
+ *
+ * @example
+ * ```ts
+ * await downloadBlob(blob, { filename: 'report.pdf' })
+ * await downloadBlob(blob, { hash: userId })
+ * ```
+ */
 export declare const downloadBlob: (blob: Blob, options: DownloadBlobOptions) => Promise<void>;
 export {};

package/dist/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./chunks/cookies-BayERMbH.cjs"),t=require("./build-query-params/index.cjs"),n=require("./clean-object/index.cjs"),r=require("./build-sort-param/index.cjs"),i=require("./download-file/index.cjs");exports.buildQueryParams=t.buildQueryParams,exports.buildSortParam=r.buildSortParam,exports.cleanObject=n.cleanObject,exports.defaultCookieOptions=e.t,exports.deleteCookie=e.n,exports.downloadBlob=i.downloadBlob,exports.getCookie=e.r,exports.setCookie=e.i;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./chunks/cookies-BayERMbH.cjs"),t=require("./build-query-params/index.cjs"),n=require("./clean-object/index.cjs"),r=require("./build-sort-param/index.cjs"),i=require("./download-file/index.cjs"),a=require("./normalize-input/index.cjs");exports.buildQueryParams=t.buildQueryParams,exports.buildSortParam=r.buildSortParam,exports.cleanObject=n.cleanObject,exports.defaultCookieOptions=e.t,exports.deleteCookie=e.n,exports.downloadBlob=i.downloadBlob,exports.getCookie=e.r,exports.normalizeDecimalInput=a.normalizeDecimalInput,exports.normalizePhoneNumberInput=a.normalizePhoneNumberInput,exports.setCookie=e.i;

package/dist/index.d.ts

@@ -4,3 +4,4 @@ export * from './cookies';
 export type * from './types';
 export * from './build-sort-param';
 export * from './download-file';
+export * from './normalize-input';

package/dist/index.js

@@ -3,4 +3,5 @@ import { cleanObject as t } from "./clean-object/index.js";
 import { defaultCookieOptions as n, deleteCookie as r, getCookie as i, setCookie as a } from "./cookies/index.js";
 import { buildSortParam as o } from "./build-sort-param/index.js";
 import { downloadBlob as s } from "./download-file/index.js";
-export { e as buildQueryParams, o as buildSortParam, t as cleanObject, n as defaultCookieOptions, r as deleteCookie, s as downloadBlob, i as getCookie, a as setCookie };
+import { normalizeDecimalInput as c, normalizePhoneNumberInput as l } from "./normalize-input/index.js";
+export { e as buildQueryParams, o as buildSortParam, t as cleanObject, n as defaultCookieOptions, r as deleteCookie, s as downloadBlob, i as getCookie, c as normalizeDecimalInput, l as normalizePhoneNumberInput, a as setCookie };

package/dist/normalize-input/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=(e,t=2)=>{let n=e.target,r=n.value;r=r.replace(`,`,`.`),r=r.replace(/[^0-9.]/g,``);let i=r.indexOf(`.`);i!==-1&&(r=r.slice(0,i+1)+r.slice(i+1).replace(/\./g,``)),r.startsWith(`.`)&&(r=`0`+r);let[a,o]=r.split(`.`);o!==void 0&&(r=t>0?`${a}.${o.slice(0,t)}`:a),n.value=r},t=(e,t=15)=>{let n=e.target,r=n.value.replace(/\D/g,``).slice(0,t);n.value=r?`+`+r:``};exports.normalizeDecimalInput=e,exports.normalizePhoneNumberInput=t;

package/dist/normalize-input/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Sanitizes an input's value into a valid decimal number string in place,
+ * intended to be used as an `input`/`change` event handler.
+ *
+ * - Converts a comma decimal separator into a dot (`1,5` → `1.5`)
+ * - Strips any character that isn't a digit or a dot
+ * - Keeps only the first dot, removing subsequent ones (`1.2.3` → `1.23`)
+ * - Prefixes a leading dot with `0` (`.5` → `0.5`)
+ * - Truncates the decimal part to `decimals` digits (`1.2345` → `1.23`)
+ *
+ * @param e - The native `input`/`change` event from a text input
+ * @param decimals - Maximum number of digits allowed after the decimal point.
+ * Pass `0` to disallow decimals entirely (the dot is removed). Defaults to `2`.
+ *
+ * @example
+ * ```ts
+ * // Vue
+ * <input type="text" inputmode="decimal" @input="normalizeDecimalInput" />
+ *
+ * // React (wrap to access the native event)
+ * <input type="text" inputMode="decimal" onChange={(e) => normalizeDecimalInput(e.nativeEvent, 4)} />
+ * ```
+ */
+export declare const normalizeDecimalInput: (e: Event, decimals?: number) => void;
+/**
+ * Sanitizes an input's value into a valid phone number string in place,
+ * intended to be used as an `input`/`change` event handler.
+ *
+ * - Strips any character that isn't a digit
+ * - Truncates to `maxDigits` digits (`898812345678` → `89881234567`)
+ * - Prefixes the result with a `+` (`89991234567` → `+89991234567`)
+ * - Leaves the value empty when there are no digits left, so the field can be cleared
+ *
+ * @param e - The native `input`/`change` event from a text input
+ * @param maxDigits - Maximum number of digits allowed. Defaults to `15` (E.164 limit).
+ *
+ * @example
+ * ```ts
+ * // Vue
+ * <input type="text" inputmode="tel" @input="normalizePhoneNumberInput" />
+ *
+ * // React (wrap to access the native event)
+ * <input type="text" inputMode="tel" onChange={(e) => normalizePhoneNumberInput(e.nativeEvent, 11)} />
+ * ```
+ */
+export declare const normalizePhoneNumberInput: (e: Event, maxDigits?: number) => void;

package/dist/normalize-input/index.js

@@ -0,0 +1,14 @@
+//#region src/normalize-input/index.ts
+var e = (e, t = 2) => {
+	let n = e.target, r = n.value;
+	r = r.replace(",", "."), r = r.replace(/[^0-9.]/g, "");
+	let i = r.indexOf(".");
+	i !== -1 && (r = r.slice(0, i + 1) + r.slice(i + 1).replace(/\./g, "")), r.startsWith(".") && (r = "0" + r);
+	let [a, o] = r.split(".");
+	o !== void 0 && (r = t > 0 ? `${a}.${o.slice(0, t)}` : a), n.value = r;
+}, t = (e, t = 15) => {
+	let n = e.target, r = n.value.replace(/\D/g, "").slice(0, t);
+	n.value = r ? "+" + r : "";
+};
+//#endregion
+export { e as normalizeDecimalInput, t as normalizePhoneNumberInput };

package/package.json

@@ -2,7 +2,7 @@
 	"name": "@ptx-showcase/utils",
 	"author": "ptx-showcase",
 	"description": "Shared utilities for PTX Showcase projects",
-	"version": "0.2.4",
+	"version": "0.3.0",
 	"private": false,
 	"type": "module",
 	"license": "MIT",
@@ -56,6 +56,11 @@
 			"require": "./dist/download-file/index.cjs",
 			"types": "./dist/download-file/index.d.ts"
 		},
+		"./normalize-input": {
+			"import": "./dist/normalize-input/index.js",
+			"require": "./dist/normalize-input/index.cjs",
+			"types": "./dist/normalize-input/index.d.ts"
+		},
 		"./types": {
 			"import": "./dist/types/index.js",
 			"require": "./dist/types/index.cjs",