# Utilities

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

## Available Exports

```ts
import { BASE, SR_ONLY, VARIANT, PARTS, shouldReduceMotion, canHover } from "svseeds";
import type { SVSClass, SVSVariant, SVSPart, SVSFieldValidation, SVSFieldConstraint, SVSContext, CollectionEvents, Position, Align, Vector } from "svseeds";
```

## Constants

These constants can be used with `SVSClass` objects for styling. See [Object for Styling](/docs/styling#object-for-styling) for details.

```ts
const BASE = "base";
const SR_ONLY =
  "position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip-path:inset(50%);white-space:nowrap;border:0;";
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",
});
```

`SR_ONLY` is a ready-made screen-reader-only CSS text for visually hidden content.

## Functions

### `shouldReduceMotion`

Checks whether the user prefers reduced motion. It returns `false` when `window` is unavailable, so motion is allowed by default under SSR.

```ts
function shouldReduceMotion(): boolean;
```

### `canHover`

Checks whether the primary pointer can hover. It returns `true` when `window` is unavailable, so hover is treated as available by default under SSR.

```ts
function canHover(): boolean;
```

## Types

### `SVSClass`

The `styling` prop type: a class string, or an object keyed by part. See [Object for Styling](/docs/styling#object-for-styling) for the full definition.

### `SVSVariant`

The component `variant` string: `VARIANT` values or any custom string.

```ts
type SVSVariant = (typeof VARIANT)[keyof typeof VARIANT] | (string & {});
```

### `SVSPart`

A component part name: `PARTS` values or any custom string.

```ts
type SVSPart = (typeof PARTS)[keyof typeof PARTS] | (string & {});
```

### `SVSFieldValidation`

A field validation callback returning an error message, or nullish when valid.

```ts
type SVSFieldValidation<V, E extends HTMLElement = HTMLInputElement> = (ctx: {
  value: V;
  validity: ValidityState;
  element: E;
}) => string | undefined | null;
```

### `SVSFieldConstraint`

A per-item constraint callback for collection-style fields.

```ts
type SVSFieldConstraint<E extends HTMLElement = HTMLInputElement> = (ctx: {
  value: string;
  values: string[];
  validity: ValidityState;
  element: E;
}) => string | undefined | null;
```

### `SVSContext`

The shared component context exposing `variant` and `styling`.

```ts
type SVSContext = {
  get variant(): SVSVariant;
  get styling(): SVSClass | undefined;
};
```

### `CollectionEvents<T>`

The `onadd` and `onremove` event contract for collection-style components. Return the subset to commit.

```ts
interface CollectionEvents<T> {
  // Return the subset to commit: undefined => all, [] => none.
  onadd?: (detail: { values: T[]; added: T[] }) => T[] | void;
  onremove?: (detail: { values: T[]; removed: T[] }) => T[] | void;
}
```

### `Position`

A box-side placement string used by positioning components.

```ts
type Position = "top" | "right" | "bottom" | "left";
```

### `Align`

Cross-axis alignment along the chosen side.

```ts
type Align = "start" | "center" | "end";
```

### `Vector`

A 2-D point / offset in pixels.

```ts
type Vector = { x: number; y: number };
```