@ptx-showcase/utils 0.2.3 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@ Shared utilities for PTX Showcase projects.
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @ptx-showcase/utils
@@ -18,42 +18,128 @@ bun add @ptx-showcase/utils
 
 ---
 
-## 🚀 Usage
+## Usage
 
-### Cookie utilities
+All utilities can be imported from the root package or from a specific subpath.
+
+---
+
+### buildQueryParams
+
+Builds a URL query string from an object. Skips `null`, `undefined`, empty strings, and empty arrays.
+
+```ts
+// from root
+import { buildQueryParams } from '@ptx-showcase/utils'
+
+// from subpath
+import { buildQueryParams } from '@ptx-showcase/utils/build-query-params'
+
+buildQueryParams({ page: 1, search: 'test', empty: '' })
+// → '?page=1&search=test'
+
+buildQueryParams({ ids: [], status: 'active' })
+// → '?status=active'
+
+buildQueryParams({})
+// → ''
+```
+
+---
+
+### buildSortParam
+
+Builds a comma-separated sort string with toggle logic: first call adds the field, second toggles to descending (`-field`), third removes it.
+
+```ts
+// from root
+import { buildSortParam } from '@ptx-showcase/utils'
+
+// from subpath
+import { buildSortParam } from '@ptx-showcase/utils/build-sort-param'
+
+buildSortParam('name')              // → 'name'
+buildSortParam('name', 'name')      // → '-name'
+buildSortParam('name', '-name')     // → ''
+
+// combining with existing sort
+buildSortParam('age', 'name')       // → 'age,name'
+buildSortParam('age', 'age,name')   // → '-age,name'
+```
+
+---
+
+### Cookies
+
+Cookie helpers with secure defaults (`expires: 1h`, `secure: true`, `sameSite: Strict`).
 
 ```ts
+// from root
+import { setCookie, getCookie, deleteCookie } from '@ptx-showcase/utils'
+
+// from subpath
 import { setCookie, getCookie, deleteCookie } from '@ptx-showcase/utils/cookies'
 
-// set cookie
-setCookie('token', '123')
+// set (uses default options)
+setCookie('token', 'abc123')
+
+// set with custom options
+setCookie('session', 'xyz', { expires: 7, sameSite: 'Lax' })
 
-// get cookie
-const token = getCookie('token')
+// get
+const token = getCookie('token') // → 'abc123' | undefined
 
-// delete cookie
+// delete
 deleteCookie('token')
 ```
 
+Default options:
+
+| Option     | Value      |
+|------------|------------|
+| `expires`  | 1 hour     |
+| `secure`   | `true`     |
+| `sameSite` | `'Strict'` |
+
 ---
 
-## 📁 Available modules
+### downloadBlob
+
+Downloads a `Blob` as a file in the browser. Accepts either an explicit filename or a hash value (auto-generates a SHA-1 filename).
+
+```ts
+// from root
+import { downloadBlob } from '@ptx-showcase/utils'
 
-- `@ptx-showcase/utils` — base utilities
-- `@ptx-showcase/utils/cookie` — cookie helpers
+// from subpath
+import { downloadBlob } from '@ptx-showcase/utils/download-file'
+
+const blob = new Blob(['Hello, World!'], { type: 'text/plain' })
+
+// with explicit filename
+await downloadBlob(blob, { filename: 'report.txt' })
+
+// with auto-generated SHA-1 filename
+await downloadBlob(blob, { hash: 12345 })
+// → saves as e.g. '17b840d9...'
+```
 
 ---
 
-## 🧠 Features
+## Available modules
 
-- TypeScript support out of the box
-- ESM + CommonJS compatibility
-- Modular architecture (subpath imports)
-- Lightweight and reusable across projects
+| Subpath                                     | Exports                                              |
+|---------------------------------------------|------------------------------------------------------|
+| `@ptx-showcase/utils`                       | all utilities                                        |
+| `@ptx-showcase/utils/build-query-params`    | `buildQueryParams`                                   |
+| `@ptx-showcase/utils/build-sort-param`      | `buildSortParam`                                     |
+| `@ptx-showcase/utils/cookies`               | `setCookie`, `getCookie`, `deleteCookie`, `defaultCookieOptions` |
+| `@ptx-showcase/utils/download-file`         | `downloadBlob`                                       |
+| `@ptx-showcase/utils/types`                 | `TableColumnConfig`                                  |
 
 ---
 
-## 🔄 Versioning
+## Versioning
 
 This package follows [Semantic Versioning](https://semver.org/):
 
@@ -63,12 +149,12 @@ This package follows [Semantic Versioning](https://semver.org/):
 
 ---
 
-## 📜 Changelog
+## Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md) for all changes.
 
 ---
 
-## 📄 License
+## License
 
 MIT

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.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("file-saver");var t=async e=>{let t=new TextEncoder().encode(String(e)),n=await crypto.subtle.digest(`SHA-1`,t);return Array.from(new Uint8Array(n)).map(e=>e.toString(16).padStart(2,`0`)).join(``)},n=async(n,r)=>{if(!(n instanceof Blob))throw Error(`downloadBlob: expected Blob, got ${typeof n}`);(0,e.saveAs)(n,`filename`in r?r.filename:await t(r.hash))};exports.downloadBlob=n;

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

@@ -0,0 +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/download-file/index.js

@@ -0,0 +1,11 @@
+import { saveAs as e } from "file-saver";
+//#region src/download-file/index.ts
+var t = async (e) => {
+	let t = new TextEncoder().encode(String(e)), n = await crypto.subtle.digest("SHA-1", t);
+	return Array.from(new Uint8Array(n)).map((e) => e.toString(16).padStart(2, "0")).join("");
+}, n = async (n, r) => {
+	if (!(n instanceof Blob)) throw Error(`downloadBlob: expected Blob, got ${typeof n}`);
+	e(n, "filename" in r ? r.filename : await t(r.hash));
+};
+//#endregion
+export { n as downloadBlob };

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");exports.buildQueryParams=t.buildQueryParams,exports.buildSortParam=r.buildSortParam,exports.cleanObject=n.cleanObject,exports.defaultCookieOptions=e.t,exports.deleteCookie=e.n,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

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

package/dist/index.js

@@ -2,4 +2,6 @@ import { buildQueryParams as e } from "./build-query-params/index.js";
 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";
-export { e as buildQueryParams, o as buildSortParam, t as cleanObject, n as defaultCookieOptions, r as deleteCookie, i as getCookie, a as setCookie };
+import { downloadBlob as s } from "./download-file/index.js";
+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.3",
+	"version": "0.3.0",
 	"private": false,
 	"type": "module",
 	"license": "MIT",
@@ -51,6 +51,16 @@
 			"require": "./dist/clean-object/index.cjs",
 			"types": "./dist/clean-object/index.d.ts"
 		},
+		"./download-file": {
+			"import": "./dist/download-file/index.js",
+			"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",
@@ -67,16 +77,18 @@
 		"access": "public"
 	},
 	"devDependencies": {
-		"@types/node": "^25.9.1",
+		"@types/node": "^25.9.2",
 		"bumpp": "^11.1.0",
-		"oxlint": "^1.67.0",
+		"oxlint": "^1.68.0",
 		"typescript": "~6.0.3",
-		"vite": "^8.0.14",
-		"vite-plugin-dts": "^5.0.1",
-		"vitest": "^4.1.7"
+		"vite": "^8.0.16",
+		"vite-plugin-dts": "^5.0.2",
+		"vitest": "^4.1.8"
 	},
 	"dependencies": {
+		"@types/file-saver": "^2.0.7",
 		"@types/js-cookie": "^3.0.6",
-		"js-cookie": "^3.0.7"
+		"file-saver": "^2.0.5",
+		"js-cookie": "^3.0.8"
 	}
 }