How to Use

Utilities

This section documents the utility functions, constants, and other helper elements used within SvSeeds components.

Available Exports

TypeScript
import {
  BASE,
  VARIANT,
  PARTS,
  fnClass,
  isNeutral,
  omit,
  debounce,
  throttle,
  UniqueId,
  elemId,
} from "svseeds";

Constants

These constants can be used with SVSClass objects for styling. See Object for Styling for details.

TypeScript
const BASE = "base";
const VARIANT = Object.freeze({ NEUTRAL: "neutral", ACTIVE: "active", INACTIVE: "inactive" });
const PARTS = Object.freeze({
  WHOLE: "whole",
  MIDDLE: "middle",
  MAIN: "main",
  TOP: "top",
  LEFT: "left",
  RIGHT: "right",
  BOTTOM: "bottom",
  LABEL: "label",
  AUX: "aux",
  EXTRA: "extra",
});

fnClass

Creates a function that dynamically generates CSS classes based on component parts and state. The optional styling parameter takes precedence over preset when provided. Compatible with the ClassValue type available in Svelte 5.16+ class attributes.

TypeScript
type ClassFn = (part: string, variant: string) => ClassValue | undefined;
function fnClass(preset: SVSClass, style?: SVSClass): ClassFn

Example

Svelte
<script>
  import { fnClass } from "svseeds";

  let { variant = $bindable("") } = $props();
  const cls = fnClass("default-class", "my-class");
</script>

<span class={cls("special-tag", variant)}>
  Hello
</span>

isNeutral

Determines whether a variant is in a neutral variant (neither active nor inactive).

TypeScript
function isNeutral(variant: string): boolean

isUnsignedInteger

Checks if a given number is an unsigned integer (non-negative integer).

TypeScript
function isUnsignedInteger(num: number): boolean

omit

Creates a new object with specified keys omitted from the original object. Returns an empty object if the input is undefined or null.

TypeScript
function omit<T extends object, K extends keyof T>(obj?: T, ...keys: K[]): Omit<T, K> | Record<string, never>

Example

TypeScript
const user = { id: 1, name: "John", email: "john@example.com" };
const publicUser = omit(user, "email"); // { id: 1, name: "John" }
const empty = omit(undefined, "key"); // {}

debounce

Creates a debounced function that delays invoking the provided function until after the specified delay has elapsed since the last invocation.

TypeScript
function debounce<Args extends unknown[], R>(delay: number, fn: (...args: Args) => R): (...args: Args) => void

Example

TypeScript
const debouncedSearch = debounce(300, (query: string) => {
  console.log("Searching for:", query);
});

debouncedSearch("hello"); // Will only execute after 300ms of no further calls
debouncedSearch("hello world"); // Cancels previous call, waits another 300ms

throttle

Creates a throttled function that invokes the provided function at most once per specified interval. Subsequent calls within the interval are queued and executed at the next available interval boundary.

TypeScript
function throttle<Args extends unknown[], R>(interval: number, fn: (...args: Args) => R): (...args: Args) => void

Example

TypeScript
const throttledScroll = throttle(100, (event: Event) => {
  console.log("Scroll event handled");
});

window.addEventListener("scroll", throttledScroll);
// Will execute at most once every 100ms, even if scroll events fire more frequently

UniqueId

A class that generates unique random alphabetic ID strings with collision detection. It uses a carefully selected character set of 50 letters (A-Y, a-y) to ensure uniform distribution with Math.random(), and provides reserved character space (Z, z) for manual ID injection without conflicts.

TypeScript
class UniqueId {
  // len:   The length of generated ID strings (minimum 3)
  // limit: Maximum number of IDs to store before clearing the internal store
  constructor(len: number = 3, limit: number = 100000) { ... }
  // Returns a new unique ID string.
  get id(): string { ... }
  // Conditionally generates a unique ID string based on the provided value.
  // Returns undefined if the value is falsy.
  get(v: unknown): string | undefined { ... }
}

Example

TypeScript
const generator = new UniqueId();
const id1 = generator.id; // "AbC"
const id2 = generator.get("hello"); // "XyA"
const id3 = generator.get(null); // undefined

elemId

A pre-configured instance of UniqueId used internally by SvSeeds components. Using elemId to generate IDs ensures no conflicts with ID attributes automatically generated by SvSeeds components.

TypeScript
const elemId = new UniqueId();