);
}
// Usage
// Renders: "Location not available"
```
### Example: Resetting coordinates [#example-resetting-coordinates]
```typescript
import { DEFAULT_COORDINATE } from '@accelint/constants/coordinates';
class LocationTracker {
private location: [number, number] = DEFAULT_COORDINATE;
setLocation(lat: number, lon: number): void {
this.location = [lat, lon];
}
clearLocation(): void {
this.location = DEFAULT_COORDINATE;
}
hasLocation(): boolean {
return !Number.isNaN(this.location[0]) && !Number.isNaN(this.location[1]);
}
}
```
### Example: Type-safe coordinate handling [#example-type-safe-coordinate-handling]
```typescript
import { DEFAULT_COORDINATE } from '@accelint/constants/coordinates';
type Coordinate = [number, number];
type ValidCoordinate = [lat: number, lon: number];
function normalizeCoordinate(coord: Coordinate): ValidCoordinate | null {
if (Number.isNaN(coord[0]) || Number.isNaN(coord[1])) {
return null;
}
// Clamp latitude to [-90, 90]
const lat = Math.max(-90, Math.min(90, coord[0]));
// Normalize longitude to [-180, 180]
const lon = ((coord[1] + 180) % 360) - 180;
return [lat, lon];
}
normalizeCoordinate(DEFAULT_COORDINATE); // null
normalizeCoordinate([40.7128, -74.0060]); // [40.7128, -74.0060]
```
## Related [#related]
* [Null Island](https://en.wikipedia.org/wiki/Null_Island) - Wikipedia article on the \[0,0] coordinate
* [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API) - MDN documentation
# Overview (/docs/packages/constants)
## Installation [#installation]
```bash
pnpm add @accelint/constants
```
## Usage [#usage]
```typescript
// Import from root (all exports)
import {
CSS_RGBA_LEGACY_REGEX,
DEFAULT_COORDINATE,
DISTANCE_UNIT_SYMBOLS
} from '@accelint/constants';
// Import from sub-modules
import { HEX_REGEX } from '@accelint/constants/color';
import { DISTANCE_UNIT_BY_SYMBOL } from '@accelint/constants/units';
```
## Available Exports [#available-exports]
| Export Path | Description |
| ---------------------------- | ------------------------------------------------------------------------- |
| [color](./color) | Regular expressions for validating CSS rgba() and hex color formats |
| [coordinates](./coordinates) | Default empty coordinate value using NaN to avoid "Null Island" at \[0,0] |
| [units](./units) | SI-compliant display symbols for distance units and bidirectional mapping |
## Related [#related]
* [@accelint/converters](../converters/index.md) - Color format converters
* [@accelint/predicates](../predicates/index.md) - Validation predicates
* [GitHub Repository](https://github.com/gohypergiant/standard-toolkit) - Source code
# Distances (/docs/packages/constants/units)
## Usage [#usage]
```typescript
import {
DISTANCE_UNIT_SYMBOLS,
DISTANCE_UNIT_BY_SYMBOL,
METERS_PER_UNIT,
type DistanceUnit,
type DistanceUnitSymbol,
} from '@accelint/constants/units';
// Get display symbol for a unit
const symbol = DISTANCE_UNIT_SYMBOLS.kilometers; // 'km'
// Get unit name from display symbol
const unit = DISTANCE_UNIT_BY_SYMBOL['km']; // 'kilometers'
// Convert meters to a unit
const nauticalMiles = 3704 / METERS_PER_UNIT.nauticalmiles; // 2
// Format distance with correct symbol
const distance = 42.195;
const label = `${distance} ${DISTANCE_UNIT_SYMBOLS.kilometers}`; // '42.195 km'
```
## Reference [#reference]
### DISTANCE\_UNIT\_SYMBOLS [#distance_unit_symbols]
```typescript
const DISTANCE_UNIT_SYMBOLS: {
readonly kilometers: 'km';
readonly meters: 'm';
readonly nauticalmiles: 'NM';
readonly miles: 'mi';
readonly feet: 'ft';
};
```
Maps Turf.js-compatible unit names to their correct display symbols per the International System of Units (SI) and international standards.
**Key distinctions from informal abbreviations:**
* `km` not `KM` - SI uses lowercase k for kilo prefix, lowercase m for meters
* `m` not `M` - SI uppercase M is the mega prefix, not meters
* `NM` for nautical miles - ICAO/IMO aviation/maritime convention
* `mi` and `ft` - Not SI units but follow conventional lowercase
**Available units:**
* `kilometers` → `'km'` (SI unit)
* `meters` → `'m'` (SI unit)
* `nauticalmiles` → `'NM'` (ICAO/IMO standard)
* `miles` → `'mi'` (Imperial unit)
* `feet` → `'ft'` (Imperial unit)
### DISTANCE\_UNIT\_BY\_SYMBOL [#distance_unit_by_symbol]
```typescript
const DISTANCE_UNIT_BY_SYMBOL: Record;
```
Reverse lookup map from display symbol to Turf.js unit name.
```typescript
DISTANCE_UNIT_BY_SYMBOL['km'] // 'kilometers'
DISTANCE_UNIT_BY_SYMBOL['m'] // 'meters'
DISTANCE_UNIT_BY_SYMBOL['NM'] // 'nauticalmiles'
DISTANCE_UNIT_BY_SYMBOL['mi'] // 'miles'
DISTANCE_UNIT_BY_SYMBOL['ft'] // 'feet'
```
### METERS\_PER\_UNIT [#meters_per_unit]
```typescript
const METERS_PER_UNIT: {
readonly kilometers: 1000;
readonly meters: 1;
readonly nauticalmiles: 1852;
readonly miles: 1609.344;
readonly feet: 0.3048;
};
```
Meters in one of each supported distance unit. This is the single conversion table for distance formatting across packages. Divide a distance in meters by the factor to convert to the unit, or multiply to convert back to meters.
```typescript
METERS_PER_UNIT.kilometers // 1000
METERS_PER_UNIT.meters // 1
METERS_PER_UNIT.nauticalmiles // 1852
METERS_PER_UNIT.miles // 1609.344
METERS_PER_UNIT.feet // 0.3048
```
The object is declared `as const satisfies Record`, so it has exactly one entry per `DistanceUnit` and each value is a literal type.
### DistanceUnit [#distanceunit]
```typescript
type DistanceUnit = 'kilometers' | 'meters' | 'nauticalmiles' | 'miles' | 'feet';
```
Turf.js-compatible unit names for distance calculations.
### DistanceUnitSymbol [#distanceunitsymbol]
```typescript
type DistanceUnitSymbol = 'km' | 'm' | 'NM' | 'mi' | 'ft';
```
Display symbol for a distance unit.
> **Good to know:** These symbols follow SI conventions where applicable. Using the correct symbol (lowercase `km` not uppercase `KM`) matters for scientific accuracy and internationalization.
## Examples [#examples]
### Example: Formatting distance with correct symbols [#example-formatting-distance-with-correct-symbols]
```typescript
import { DISTANCE_UNIT_SYMBOLS } from '@accelint/constants/units';
function formatDistance(value: number, unit: keyof typeof DISTANCE_UNIT_SYMBOLS): string {
const symbol = DISTANCE_UNIT_SYMBOLS[unit];
return `${value.toFixed(2)} ${symbol}`;
}
formatDistance(42.195, 'kilometers'); // '42.19 km'
formatDistance(26.219, 'miles'); // '26.22 mi'
formatDistance(1852, 'meters'); // '1852.00 m'
formatDistance(22.24, 'nauticalmiles'); // '22.24 NM'
```
### Example: Converting between meters and a unit [#example-converting-between-meters-and-a-unit]
```typescript
import { METERS_PER_UNIT, type DistanceUnit } from '@accelint/constants/units';
function metersToUnit(meters: number, unit: DistanceUnit): number {
return meters / METERS_PER_UNIT[unit];
}
function unitToMeters(value: number, unit: DistanceUnit): number {
return value * METERS_PER_UNIT[unit];
}
metersToUnit(3704, 'nauticalmiles'); // 2
metersToUnit(42300, 'kilometers'); // 42.3
unitToMeters(2, 'nauticalmiles'); // 3704
unitToMeters(1, 'miles'); // 1609.344
```
### Example: Parsing user input with symbol lookup [#example-parsing-user-input-with-symbol-lookup]
```typescript
import { DISTANCE_UNIT_BY_SYMBOL, type DistanceUnitSymbol } from '@accelint/constants/units';
function parseDistance(input: string): { value: number; unit: string } | null {
const match = input.match(/^([\d.]+)\s*([a-zA-Z]+)$/);
if (!match) return null;
const [, valueStr, symbolStr] = match;
const value = parseFloat(valueStr);
const symbol = symbolStr as DistanceUnitSymbol;
const unit = DISTANCE_UNIT_BY_SYMBOL[symbol];
return unit ? { value, unit } : null;
}
parseDistance('100 km'); // { value: 100, unit: 'kilometers' }
parseDistance('5.5 mi'); // { value: 5.5, unit: 'miles' }
parseDistance('1852 m'); // { value: 1852, unit: 'meters' }
parseDistance('10 NM'); // { value: 10, unit: 'nauticalmiles' }
parseDistance('100 KM'); // null (incorrect case)
```
### Example: Unit converter with Turf.js [#example-unit-converter-with-turfjs]
```typescript
import { DISTANCE_UNIT_SYMBOLS, type DistanceUnit } from '@accelint/constants/units';
import { convertLength } from '@turf/helpers';
function convertDistance(
value: number,
from: DistanceUnit,
to: DistanceUnit,
): string {
const converted = convertLength(value, from, to);
const symbol = DISTANCE_UNIT_SYMBOLS[to];
return `${converted.toFixed(2)} ${symbol}`;
}
convertDistance(1, 'kilometers', 'meters'); // '1000.00 m'
convertDistance(1, 'miles', 'kilometers'); // '1.61 km'
convertDistance(1, 'nauticalmiles', 'kilometers'); // '1.85 km'
```
### Example: Distance unit selector UI [#example-distance-unit-selector-ui]
```typescript
import { DISTANCE_UNIT_SYMBOLS, type DistanceUnit } from '@accelint/constants/units';
function DistanceUnitSelect({ value, onChange }: {
value: DistanceUnit;
onChange: (unit: DistanceUnit) => void;
}) {
return (
);
}
```
### Example: Aviation distance calculator [#example-aviation-distance-calculator]
```typescript
import {
DISTANCE_UNIT_SYMBOLS,
DISTANCE_UNIT_BY_SYMBOL
} from '@accelint/constants/units';
import { distance } from '@turf/distance';
function calculateFlightDistance(
from: [number, number],
to: [number, number],
): string {
// Aviation uses nautical miles
const nm = distance(from, to, { units: 'nauticalmiles' });
const symbol = DISTANCE_UNIT_SYMBOLS.nauticalmiles;
return `${nm.toFixed(1)} ${symbol}`;
}
calculateFlightDistance([40.7128, -74.0060], [51.5074, -0.1278]);
// "3000.5 NM" (New York to London)
```
### Example: Type-safe unit validation [#example-type-safe-unit-validation]
```typescript
import {
DISTANCE_UNIT_SYMBOLS,
type DistanceUnit,
type DistanceUnitSymbol,
} from '@accelint/constants/units';
function isValidUnit(unit: string): unit is DistanceUnit {
return unit in DISTANCE_UNIT_SYMBOLS;
}
function isValidSymbol(symbol: string): symbol is DistanceUnitSymbol {
return Object.values(DISTANCE_UNIT_SYMBOLS).includes(symbol as DistanceUnitSymbol);
}
isValidUnit('kilometers'); // true
isValidUnit('invalid'); // false
isValidSymbol('km'); // true
isValidSymbol('KM'); // false
```
### Example: Map viewport labeling [#example-map-viewport-labeling]
```typescript
import { DISTANCE_UNIT_SYMBOLS } from '@accelint/constants/units';
interface ViewportScale {
width: number;
height: number;
unit: keyof typeof DISTANCE_UNIT_SYMBOLS;
}
function formatViewport(scale: ViewportScale): string {
const symbol = DISTANCE_UNIT_SYMBOLS[scale.unit];
return `Viewport: ${scale.width} × ${scale.height} ${symbol}`;
}
formatViewport({ width: 600, height: 400, unit: 'nauticalmiles' });
// "Viewport: 600 × 400 NM"
```
## Related [#related]
* [formatBearing & formatDistance](../formatters/bearing.md) - Formatters that consume `METERS_PER_UNIT` and `DISTANCE_UNIT_SYMBOLS`
* [International System of Units (SI)](https://en.wikipedia.org/wiki/International_System_of_Units) - SI unit standards
* [@turf/helpers](https://turfjs.org/docs/api/helpers) - Turf.js unit conversion utilities
* [ICAO standards](https://www.icao.int/) - Aviation unit conventions
# booleanToNumber (/docs/packages/converters/boolean-to-number)
Convert a boolean to an integer using bitwise operations.
## Usage [#usage]
```typescript
import { booleanToNumber } from '@accelint/converters/boolean-to-number';
const one = booleanToNumber(true);
// 1
const zero = booleanToNumber(false);
// 0
```
## Reference [#reference]
```typescript
function booleanToNumber(val: boolean): number
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | --------- | ----------------------------------------- |
| `val` | `boolean` | The boolean value to convert to a number. |
### Returns [#returns]
Returns `1` if `true`, `0` if `false`.
## Examples [#examples]
### Example: Basic conversion [#example-basic-conversion]
```typescript
import { booleanToNumber } from '@accelint/converters/boolean-to-number';
console.log(booleanToNumber(true));
// 1
console.log(booleanToNumber(false));
// 0
```
### Example: Array transformation [#example-array-transformation]
```typescript
import { booleanToNumber } from '@accelint/converters/boolean-to-number';
const flags = [true, false, true, true, false];
const numbers = flags.map(booleanToNumber);
console.log(numbers);
// [1, 0, 1, 1, 0]
```
### Example: Conditional arithmetic [#example-conditional-arithmetic]
```typescript
import { booleanToNumber } from '@accelint/converters/boolean-to-number';
function countActive(items: { active: boolean }[]): number {
return items.reduce((sum, item) => sum + booleanToNumber(item.active), 0);
}
const items = [
{ active: true },
{ active: false },
{ active: true }
];
console.log(countActive(items));
// 2
```
### Example: Bitwise operations [#example-bitwise-operations]
```typescript
import { booleanToNumber } from '@accelint/converters/boolean-to-number';
// Create bit flags
const hasRead = true;
const hasWrite = false;
const hasExecute = true;
const permissions =
(booleanToNumber(hasRead) << 2) |
(booleanToNumber(hasWrite) << 1) |
booleanToNumber(hasExecute);
console.log(permissions.toString(2).padStart(3, '0'));
// "101"
```
> **Good to know:** This function uses bitwise OR with 0 (`| 0`) for efficient conversion. It's faster than using the ternary operator (`val ? 1 : 0`) or unary plus (`+val`).
## Related [#related]
* [toBoolean](../to-boolean/index.md) - Convert various values to boolean
# CSS RGBA Converters (/docs/packages/converters/css-rgba)
Convert between CSS rgba formats (strings, tuples, objects) and RGBA 0-255 tuples. Supports CSS Color Module Level 4 spec including legacy and modern syntax.
## cssRgbaStringToRgba255Tuple [#cssrgbastringtorgba255tuple]
Parse a CSS rgba/rgb string to a Rgba255Tuple.
### Usage [#usage]
```typescript
import { cssRgbaStringToRgba255Tuple } from '@accelint/converters/css-rgba';
// Legacy comma-separated syntax
const color = cssRgbaStringToRgba255Tuple('rgba(255, 128, 64, 0.5)');
// [255, 128, 64, 128]
// Modern space-separated syntax
const modernColor = cssRgbaStringToRgba255Tuple('rgb(255 128 64 / 50%)');
// [255, 128, 64, 128]
```
### Reference [#reference]
```typescript
function cssRgbaStringToRgba255Tuple(css: string): Rgba255Tuple
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------- | ------------------------------------------------------------------------------------------- |
| `css` | `string` | The CSS string to parse. Supports legacy comma-separated and modern space-separated syntax. |
#### Returns [#returns]
Returns a Rgba255Tuple `[r, g, b, a]` where all values are 0-255.
#### Throws [#throws]
Throws `Error` if:
* The CSS string is invalid
* Values are out of range
* RGB values mix integers and percentages
### Examples [#examples]
#### Example: Legacy comma-separated syntax [#example-legacy-comma-separated-syntax]
```typescript
import { cssRgbaStringToRgba255Tuple } from '@accelint/converters/css-rgba';
const color = cssRgbaStringToRgba255Tuple('rgba(255, 128, 64, 0.5)');
console.log(color);
// [255, 128, 64, 128]
const rgb = cssRgbaStringToRgba255Tuple('rgb(255, 128, 64)');
console.log(rgb);
// [255, 128, 64, 255]
```
#### Example: Modern space-separated syntax [#example-modern-space-separated-syntax]
```typescript
import { cssRgbaStringToRgba255Tuple } from '@accelint/converters/css-rgba';
const color = cssRgbaStringToRgba255Tuple('rgb(255 128 64)');
console.log(color);
// [255, 128, 64, 255]
const colorWithAlpha = cssRgbaStringToRgba255Tuple('rgb(255 128 64 / 0.5)');
console.log(colorWithAlpha);
// [255, 128, 64, 128]
```
#### Example: Percentage values [#example-percentage-values]
```typescript
import { cssRgbaStringToRgba255Tuple } from '@accelint/converters/css-rgba';
// RGB percentages
const color = cssRgbaStringToRgba255Tuple('rgb(100% 50% 25%)');
console.log(color);
// [255, 128, 64, 255]
// Alpha percentage
const colorWithAlpha = cssRgbaStringToRgba255Tuple('rgba(255, 128, 64, 50%)');
console.log(colorWithAlpha);
// [255, 128, 64, 128]
```
> **Good to know:** RGB values must all be integers or all be percentages—no mixing. Alpha can be decimal (0-1) or percentage (0-100%) regardless of RGB format. If alpha is omitted, it defaults to 255 (fully opaque).
## rgba255TupleToCssRgbaString [#rgba255tupletocssrgbastring]
Convert a Rgba255Tuple to a CSS rgba string.
### Usage [#usage-1]
```typescript
import { rgba255TupleToCssRgbaString } from '@accelint/converters/css-rgba';
const cssString = rgba255TupleToCssRgbaString([255, 128, 64, 128]);
// "rgba(255, 128, 64, 0.5)"
```
### Reference [#reference-1]
```typescript
function rgba255TupleToCssRgbaString(color: Rgba255Tuple): string
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | -------------- | ---------------------------------------------------------- |
| `color` | `Rgba255Tuple` | The Rgba255Tuple \[r, g, b, a] where all values are 0-255. |
#### Returns [#returns-1]
Returns a CSS rgba string using legacy comma-separated syntax (e.g., "rgba(255, 128, 64, 0.5)").
### Examples [#examples-1]
#### Example: Basic conversion [#example-basic-conversion]
```typescript
import { rgba255TupleToCssRgbaString } from '@accelint/converters/css-rgba';
const cssString = rgba255TupleToCssRgbaString([255, 128, 64, 255]);
console.log(cssString);
// "rgba(255, 128, 64, 1)"
```
#### Example: With alpha transparency [#example-with-alpha-transparency]
```typescript
import { rgba255TupleToCssRgbaString } from '@accelint/converters/css-rgba';
const cssString = rgba255TupleToCssRgbaString([255, 128, 64, 128]);
console.log(cssString);
// "rgba(255, 128, 64, 0.5)"
```
## cssRgbaTupleToRgba255Tuple [#cssrgbatupletorgba255tuple]
Parse a CSS rgba tuple to a Rgba255Tuple.
### Usage [#usage-2]
```typescript
import { cssRgbaTupleToRgba255Tuple } from '@accelint/converters/css-rgba';
// CSS rgba tuple has alpha in 0-1 range
const rgba255 = cssRgbaTupleToRgba255Tuple([255, 128, 64, 0.5]);
// [255, 128, 64, 128]
```
### Reference [#reference-2]
```typescript
function cssRgbaTupleToRgba255Tuple(tuple: CssRgbaTuple): Rgba255Tuple
type CssRgbaTuple = readonly [
r: number, // 0-255
g: number, // 0-255
b: number, // 0-255
a: number, // 0-1
]
```
#### Parameters [#parameters-2]
| Parameter | Type | Description |
| --------- | -------------- | ---------------------------------------------------------------------- |
| `tuple` | `CssRgbaTuple` | The CSS rgba tuple \[r, g, b, a] where RGB are 0-255 and alpha is 0-1. |
#### Returns [#returns-2]
Returns a Rgba255Tuple `[r, g, b, a]` where all values are 0-255.
#### Throws [#throws-1]
Throws `Error` if the tuple is invalid or values are out of range.
### Examples [#examples-2]
#### Example: Converting CSS tuple format [#example-converting-css-tuple-format]
```typescript
import { cssRgbaTupleToRgba255Tuple } from '@accelint/converters/css-rgba';
// CSS format: RGB 0-255, alpha 0-1
const cssFormat = [255, 128, 64, 0.5] as const;
const rgba255 = cssRgbaTupleToRgba255Tuple(cssFormat);
console.log(rgba255);
// [255, 128, 64, 128]
```
> **Good to know:** CSS rgba tuples use 0-1 for alpha (matching CSS standard) while Rgba255Tuple uses 0-255 for all channels. This function converts alpha from 0-1 to 0-255.
## rgba255TupleToCssRgbaTuple [#rgba255tupletocssrgbatuple]
Convert a Rgba255Tuple to a CSS rgba tuple.
### Usage [#usage-3]
```typescript
import { rgba255TupleToCssRgbaTuple } from '@accelint/converters/css-rgba';
const cssTuple = rgba255TupleToCssRgbaTuple([255, 128, 64, 128]);
// [255, 128, 64, 0.5019607843137255]
```
### Reference [#reference-3]
```typescript
function rgba255TupleToCssRgbaTuple(color: Rgba255Tuple): CssRgbaTuple
type CssRgbaTuple = readonly [
r: number, // 0-255
g: number, // 0-255
b: number, // 0-255
a: number, // 0-1
]
```
#### Parameters [#parameters-3]
| Parameter | Type | Description |
| --------- | -------------- | ---------------------------------------------------------- |
| `color` | `Rgba255Tuple` | The Rgba255Tuple \[r, g, b, a] where all values are 0-255. |
#### Returns [#returns-3]
Returns a CSS rgba tuple `[r, g, b, a]` where RGB are 0-255 and alpha is 0-1.
### Examples [#examples-3]
#### Example: Converting to CSS tuple format [#example-converting-to-css-tuple-format]
```typescript
import { rgba255TupleToCssRgbaTuple } from '@accelint/converters/css-rgba';
const rgba255 = [255, 128, 64, 128] as const;
const cssTuple = rgba255TupleToCssRgbaTuple(rgba255);
console.log(cssTuple);
// [255, 128, 64, 0.5019607843137255]
```
## cssRgbaObjectToRgba255Tuple [#cssrgbaobjecttorgba255tuple]
Convert a CssRgbaObject to a Rgba255Tuple.
### Usage [#usage-4]
```typescript
import { cssRgbaObjectToRgba255Tuple } from '@accelint/converters/css-rgba';
const rgba255 = cssRgbaObjectToRgba255Tuple({
r: 255,
g: 128,
b: 64,
a: 0.5
});
// [255, 128, 64, 128]
```
### Reference [#reference-4]
```typescript
function cssRgbaObjectToRgba255Tuple(obj: CssRgbaObject): Rgba255Tuple
```
#### Parameters [#parameters-4]
| Parameter | Type | Description |
| --------- | --------------- | ------------------------------------------------------- |
| `obj` | `CssRgbaObject` | The CssRgbaObject where RGB are 0-255 and alpha is 0-1. |
#### Returns [#returns-4]
Returns a Rgba255Tuple `[r, g, b, a]` where all values are 0-255.
#### Throws [#throws-2]
Throws `Error` if any values are out of range.
### Examples [#examples-4]
#### Example: Converting object format [#example-converting-object-format]
```typescript
import { cssRgbaObjectToRgba255Tuple } from '@accelint/converters/css-rgba';
const cssObject = { r: 255, g: 128, b: 64, a: 1 };
const rgba255 = cssRgbaObjectToRgba255Tuple(cssObject);
console.log(rgba255);
// [255, 128, 64, 255]
```
## rgba255TupleToCssRgbaObject [#rgba255tupletocssrgbaobject]
Convert a Rgba255Tuple to a CssRgbaObject.
### Usage [#usage-5]
```typescript
import { rgba255TupleToCssRgbaObject } from '@accelint/converters/css-rgba';
const cssObject = rgba255TupleToCssRgbaObject([255, 128, 64, 128]);
// { r: 255, g: 128, b: 64, a: 0.5019607843137255 }
```
### Reference [#reference-5]
```typescript
function rgba255TupleToCssRgbaObject(color: Rgba255Tuple): CssRgbaObject
```
#### Parameters [#parameters-5]
| Parameter | Type | Description |
| --------- | -------------- | ---------------------------------------------------------- |
| `color` | `Rgba255Tuple` | The Rgba255Tuple \[r, g, b, a] where all values are 0-255. |
#### Returns [#returns-5]
Returns a CssRgbaObject `{r, g, b, a}` where RGB are 0-255 and alpha is 0-1.
### Examples [#examples-5]
#### Example: Converting to object format [#example-converting-to-object-format]
```typescript
import { rgba255TupleToCssRgbaObject } from '@accelint/converters/css-rgba';
const rgba255 = [255, 128, 64, 255] as const;
const cssObject = rgba255TupleToCssRgbaObject(rgba255);
console.log(cssObject);
// { r: 255, g: 128, b: 64, a: 1 }
```
#### Example: Round-trip conversion [#example-round-trip-conversion]
```typescript
import {
cssRgbaObjectToRgba255Tuple,
rgba255TupleToCssRgbaObject
} from '@accelint/converters/css-rgba';
const original = { r: 255, g: 128, b: 64, a: 0.5 };
const tuple = cssRgbaObjectToRgba255Tuple(original);
const converted = rgba255TupleToCssRgbaObject(tuple);
console.log(converted.r === original.r); // true
console.log(converted.g === original.g); // true
console.log(converted.b === original.b); // true
console.log(Math.abs(converted.a - original.a) < 0.01); // true (floating point precision)
```
## Related [#related]
* [hexToRgba255Tuple](../hex/index.md) - Parse hex color strings
* [rgba255TupleToHex](../hex/index.md) - Convert to hex strings
* [glslToRgba255Tuple](../glsl/index.md) - Convert from GLSL normalized colors
# GLSL Converters (/docs/packages/converters/glsl)
## rgba255TupleToGlsl [#rgba255tupletoglsl]
Convert a Rgba255Tuple from deck.gl format (0-255) to GLSL format (0-1).
### Usage [#usage]
```typescript
import { rgba255TupleToGlsl } from '@accelint/converters/glsl';
const glslColor = rgba255TupleToGlsl([255, 128, 64, 255]);
// [1, 0.5019607843137255, 0.25098039215686274, 1]
```
### Reference [#reference]
```typescript
function rgba255TupleToGlsl(color: Rgba255Tuple): GlslRgbaTuple
type GlslRgbaTuple = readonly [
r: number, // 0-1
g: number, // 0-1
b: number, // 0-1
a: number, // 0-1
]
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------------- | ---------------------------------------------------------- |
| `color` | `Rgba255Tuple` | The Rgba255Tuple \[r, g, b, a] where all values are 0-255. |
#### Returns [#returns]
Returns a GlslRgbaTuple `[r, g, b, a]` where all values are normalized to 0-1.
### Examples [#examples]
#### Example: Basic conversion [#example-basic-conversion]
```typescript
import { rgba255TupleToGlsl } from '@accelint/converters/glsl';
const rgba255 = [255, 128, 64, 255] as const;
const glsl = rgba255TupleToGlsl(rgba255);
console.log(glsl);
// [1, 0.5019607843137255, 0.25098039215686274, 1]
```
#### Example: Using in WebGL shader [#example-using-in-webgl-shader]
```typescript
import { rgba255TupleToGlsl } from '@accelint/converters/glsl';
const color = [255, 128, 64, 255] as const;
const [r, g, b, a] = rgba255TupleToGlsl(color);
// Pass to shader uniform
gl.uniform4f(colorUniformLocation, r, g, b, a);
```
#### Example: With deck.gl layers [#example-with-deckgl-layers]
```typescript
import { rgba255TupleToGlsl } from '@accelint/converters/glsl';
import { ScatterplotLayer } from '@deck.gl/layers';
const deckColor = [255, 128, 64, 255] as const;
const glslColor = rgba255TupleToGlsl(deckColor);
// Use in custom shader
const layer = new ScatterplotLayer({
data: points,
getFillColor: d => deckColor, // deck.gl uses 0-255
getLineColor: glslColor, // Custom shader uses 0-1
updateTriggers: {
getLineColor: glslColor
}
});
```
> **Good to know:** GLSL shaders expect colors in 0-1 range. This function normalizes by dividing each channel by 255. Precision is preserved with full floating point values.
## glslToRgba255Tuple [#glsltorgba255tuple]
Convert a GlslRgbaTuple from GLSL format (0-1) to deck.gl format (0-255).
### Usage [#usage-1]
```typescript
import { glslToRgba255Tuple } from '@accelint/converters/glsl';
const rgba255 = glslToRgba255Tuple([1, 0.5, 0.25, 1]);
// [255, 128, 64, 255]
```
### Reference [#reference-1]
```typescript
function glslToRgba255Tuple(color: GlslRgbaTuple): Rgba255Tuple
type GlslRgbaTuple = readonly [
r: number, // 0-1
g: number, // 0-1
b: number, // 0-1
a: number, // 0-1
]
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | --------------- | --------------------------------------------------------- |
| `color` | `GlslRgbaTuple` | The GlslRgbaTuple \[r, g, b, a] where all values are 0-1. |
#### Returns [#returns-1]
Returns a Rgba255Tuple `[r, g, b, a]` where all values are clamped to 0-255 and rounded.
### Examples [#examples-1]
#### Example: Basic conversion [#example-basic-conversion-1]
```typescript
import { glslToRgba255Tuple } from '@accelint/converters/glsl';
const glsl = [1, 0.5, 0.25, 1] as const;
const rgba255 = glslToRgba255Tuple(glsl);
console.log(rgba255);
// [255, 128, 64, 255]
```
#### Example: Handling out-of-range values [#example-handling-out-of-range-values]
```typescript
import { glslToRgba255Tuple } from '@accelint/converters/glsl';
// Values are clamped to 0-1 range before conversion
const glsl = [1.5, -0.2, 0.5, 0.8] as const;
const rgba255 = glslToRgba255Tuple(glsl);
console.log(rgba255);
// [255, 0, 128, 204]
```
#### Example: Round-trip conversion [#example-round-trip-conversion]
```typescript
import {
rgba255TupleToGlsl,
glslToRgba255Tuple
} from '@accelint/converters/glsl';
const original = [255, 128, 64, 255] as const;
const glsl = rgba255TupleToGlsl(original);
const converted = glslToRgba255Tuple(glsl);
console.log(converted);
// [255, 128, 64, 255] (matches original)
```
> **Good to know:** Values are clamped to 0-1 range before conversion and rounded to nearest integer. This prevents invalid RGB values from out-of-range GLSL colors.
## Related [#related]
* [hexToRgba255Tuple](../hex/index.md) - Parse hex color strings
* [cssRgbaStringToRgba255Tuple](../css-rgba/index.md) - Parse CSS rgba strings
* [rgba255TupleToHex](../hex/index.md) - Convert to hex strings
# Hex Converters (/docs/packages/converters/hex)
## hexToRgba255Tuple [#hextorgba255tuple]
Parse a hex color string to a Rgba255Tuple.
### Usage [#usage]
```typescript
import { hexToRgba255Tuple } from '@accelint/converters/hex';
// 6-character hex
const color = hexToRgba255Tuple('#FF8040');
// [255, 128, 64, 255]
// 3-character shorthand
const shortColor = hexToRgba255Tuple('#F84');
// [255, 136, 68, 255]
```
### Reference [#reference]
```typescript
function hexToRgba255Tuple(hex: string): Rgba255Tuple
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------- | -------------------------------------------------------------------------------------------- |
| `hex` | `string` | The hex string to parse. Supports "#RGB", "#RGBA", "#RRGGBB", "#RRGGBBAA". Hash is optional. |
#### Returns [#returns]
Returns a Rgba255Tuple `[r, g, b, a]` where all values are 0-255.
#### Throws [#throws]
Throws `Error` if the hex string is invalid.
### Examples [#examples]
#### Example: Standard 6-character hex [#example-standard-6-character-hex]
```typescript
import { hexToRgba255Tuple } from '@accelint/converters/hex';
const color = hexToRgba255Tuple('#FF8040');
console.log(color);
// [255, 128, 64, 255]
```
#### Example: 3-character shorthand [#example-3-character-shorthand]
```typescript
import { hexToRgba255Tuple } from '@accelint/converters/hex';
// Each digit doubles: #F84 → #FF8844
const color = hexToRgba255Tuple('#F84');
console.log(color);
// [255, 136, 68, 255]
```
#### Example: With alpha channel [#example-with-alpha-channel]
```typescript
import { hexToRgba255Tuple } from '@accelint/converters/hex';
// 8-character hex includes alpha
const color = hexToRgba255Tuple('#FF804080');
console.log(color);
// [255, 128, 64, 128]
// 4-character shorthand with alpha
const shortColor = hexToRgba255Tuple('#F840');
console.log(shortColor);
// [255, 136, 68, 0]
```
#### Example: Without hash prefix [#example-without-hash-prefix]
```typescript
import { hexToRgba255Tuple } from '@accelint/converters/hex';
// Hash is optional
const color = hexToRgba255Tuple('FF8040');
console.log(color);
// [255, 128, 64, 255]
```
> **Good to know:** 3-character hex values are expanded by doubling each digit (#RGB → #RRGGBB). 4-character hex values include alpha (#RGBA → #RRGGBBAA). If no alpha is specified, it defaults to 255 (fully opaque).
## rgba255TupleToHex [#rgba255tupletohex]
Convert a Rgba255Tuple to a hex string.
### Usage [#usage-1]
```typescript
import { rgba255TupleToHex } from '@accelint/converters/hex';
// Convert to hex without alpha
const hex = rgba255TupleToHex([255, 128, 64, 255]);
// "#FF8040"
// Include alpha channel
const hexWithAlpha = rgba255TupleToHex([255, 128, 64, 128], true);
// "#FF804080"
```
### Reference [#reference-1]
```typescript
function rgba255TupleToHex(
color: Rgba255Tuple,
includeAlpha?: boolean
): string
```
#### Parameters [#parameters-1]
| Parameter | Type | Default | Description |
| -------------- | -------------- | ------- | ---------------------------------------------------------- |
| `color` | `Rgba255Tuple` | - | The Rgba255Tuple \[r, g, b, a] where all values are 0-255. |
| `includeAlpha` | `boolean` | `false` | Whether to include alpha channel in output. |
#### Returns [#returns-1]
Returns a hex string (e.g., "#FF8040" or "#FF804080").
### Examples [#examples-1]
#### Example: Basic conversion [#example-basic-conversion]
```typescript
import { rgba255TupleToHex } from '@accelint/converters/hex';
const hex = rgba255TupleToHex([255, 128, 64, 255]);
console.log(hex);
// "#FF8040"
```
#### Example: Including alpha channel [#example-including-alpha-channel]
```typescript
import { rgba255TupleToHex } from '@accelint/converters/hex';
const hexWithAlpha = rgba255TupleToHex([255, 128, 64, 128], true);
console.log(hexWithAlpha);
// "#FF804080"
```
#### Example: Round-trip conversion [#example-round-trip-conversion]
```typescript
import { hexToRgba255Tuple, rgba255TupleToHex } from '@accelint/converters/hex';
const original = '#FF8040';
const tuple = hexToRgba255Tuple(original);
const converted = rgba255TupleToHex(tuple);
console.log(converted === original);
// true
```
> **Good to know:** By default, the alpha channel is omitted from the output. Set `includeAlpha: true` to include it. All hex values are uppercase.
## Related [#related]
* [cssRgbaStringToRgba255Tuple](../css-rgba/index.md) - Parse CSS rgba strings
* [rgba255TupleToCssRgbaString](../css-rgba/index.md) - Convert to CSS rgba strings
* [glslToRgba255Tuple](../glsl/index.md) - Convert from GLSL normalized colors
# Overview (/docs/packages/converters)
## Installation [#installation]
```bash
pnpm add @accelint/converters
```
## Usage [#usage]
```typescript
// Import from root (all exports)
import {
hexToRgba255Tuple,
rgba255TupleToHex,
booleanToNumber,
toBoolean
} from '@accelint/converters';
// Import from sub-modules
import { hexToRgba255Tuple } from '@accelint/converters/hex';
import { cssRgbaStringToRgba255Tuple } from '@accelint/converters/css-rgba';
import { glslToRgba255Tuple } from '@accelint/converters/glsl';
```
## Available Exports [#available-exports]
| Export Path | Description |
| ---------------------------------------- | ------------------------------------------------------------------ |
| [boolean-to-number](./boolean-to-number) | Convert boolean values to numeric representations (0/1) |
| [css-rgba](./css-rgba) | Convert between CSS rgba strings/objects and RGBA 0-255 tuples |
| [glsl](./glsl) | Convert between GLSL normalized colors (0-1) and RGBA 0-255 tuples |
| [hex](./hex) | Convert between hex color strings and RGBA 0-255 tuples |
| [to-boolean](./to-boolean) | Convert various value types to boolean |
| [zxy-to-bbox](./zxy-to-bbox) | Convert map tile coordinates (z/x/y) to bounding box coordinates |
## Related [#related]
* [@accelint/constants](../constants) - Color and coordinate constants
* [@accelint/predicates](../predicates) - Value validation predicates
* [GitHub Repository](https://github.com/gohypergiant/standard-toolkit) - Source code
# toBoolean (/docs/packages/converters/to-boolean)
Returns true for any value not found to be a "false" value. Handles numeric zeros, string literals, and all JavaScript falsy values.
## Usage [#usage]
```typescript
import { toBoolean } from '@accelint/converters/to-boolean';
console.log(toBoolean(1)); // true
console.log(toBoolean(' FaLsE ')); // false
console.log(toBoolean(' true')); // true
console.log(toBoolean('000.000')); // false
```
## Reference [#reference]
```typescript
function toBoolean(val: unknown): boolean
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | --------- | ---------------------------------- |
| `val` | `unknown` | The value to convert to a boolean. |
### Returns [#returns]
Returns `true` if the value is truthy, `false` otherwise.
### False Values [#false-values]
The following are considered "false" values:
* **Inherently false**: `''` (empty string), `0`, `false`, `undefined`, `null`, `NaN`
* **Numeric zero**: `'0.000'` - any number of leading or trailing zeros
* **String literal**: `'false'` - any capitalizations or space-padding
## Examples [#examples]
### Example: Basic truthy/falsy [#example-basic-truthyfalsy]
```typescript
import { toBoolean } from '@accelint/converters/to-boolean';
// Inherently falsy values
console.log(toBoolean(false)); // false
console.log(toBoolean(0)); // false
console.log(toBoolean('')); // false
console.log(toBoolean(null)); // false
console.log(toBoolean(undefined)); // false
console.log(toBoolean(NaN)); // false
// Truthy values
console.log(toBoolean(true)); // true
console.log(toBoolean(1)); // true
console.log(toBoolean('hello')); // true
console.log(toBoolean([])); // true
console.log(toBoolean({})); // true
```
### Example: Numeric zero detection [#example-numeric-zero-detection]
```typescript
import { toBoolean } from '@accelint/converters/to-boolean';
// Various representations of zero
console.log(toBoolean('0')); // false
console.log(toBoolean('0.0')); // false
console.log(toBoolean('0.000')); // false
console.log(toBoolean('000')); // false
console.log(toBoolean('00.00')); // false
// Non-zero numbers
console.log(toBoolean('1')); // true
console.log(toBoolean('0.1')); // true
console.log(toBoolean('-1')); // true
```
### Example: String literal 'false' [#example-string-literal-false]
```typescript
import { toBoolean } from '@accelint/converters/to-boolean';
// Various forms of the string 'false'
console.log(toBoolean('false')); // false
console.log(toBoolean('False')); // false
console.log(toBoolean('FALSE')); // false
console.log(toBoolean(' false ')); // false
console.log(toBoolean(' FaLsE ')); // false
// Other strings are truthy
console.log(toBoolean('true')); // true
console.log(toBoolean('True')); // true
console.log(toBoolean('yes')); // true
console.log(toBoolean('no')); // true (not special-cased)
```
### Example: Environment variables [#example-environment-variables]
```typescript
import { toBoolean } from '@accelint/converters/to-boolean';
// Parse environment variable flags
const enableFeature = toBoolean(process.env.ENABLE_FEATURE);
const debugMode = toBoolean(process.env.DEBUG);
// Works with various formats:
// ENABLE_FEATURE=true
// ENABLE_FEATURE=1
// ENABLE_FEATURE=yes
// DEBUG=false
// DEBUG=0
```
### Example: Form input validation [#example-form-input-validation]
```typescript
import { toBoolean } from '@accelint/converters/to-boolean';
function validateCheckbox(input: string | undefined): boolean {
// Handles: "true", "1", "on", or any truthy value
// Rejects: "false", "0", "", undefined, null
return toBoolean(input);
}
console.log(validateCheckbox('on')); // true
console.log(validateCheckbox('true')); // true
console.log(validateCheckbox('1')); // true
console.log(validateCheckbox('false')); // false
console.log(validateCheckbox('0')); // false
console.log(validateCheckbox(undefined)); // false
```
> **Good to know:** This function is lenient by design. For more restrictive boolean parsing (e.g., only accepting true/false/on/off/yes/no), see the predicates package (`@accelint/predicates`).
## Related [#related]
* [booleanToNumber](../boolean-to-number/index.md) - Convert boolean to 1 or 0
# zxyToBbox (/docs/packages/converters/zxy-to-bbox)
Converts a slippy map tile (z, x, y) to a geographic bounding box (west, south, east, north).
## Usage [#usage]
```typescript
import { zxyToBbox } from '@accelint/converters/zxy-to-bbox';
const bbox = zxyToBbox([8, 71, 96]);
// [west, south, east, north]
```
## Reference [#reference]
```typescript
function zxyToBbox(tile: ZxyTuple): BoundingBoxTuple
type ZxyTuple = [z: number, x: number, y: number]
type BoundingBoxTuple = [
west: number, // left longitude
south: number, // bottom latitude
east: number, // right longitude
north: number // top latitude
]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---------- | --------------------------------------------------------------------------------------------- |
| `tile` | `ZxyTuple` | A tuple containing \[z, x, y] tile coordinates following the slippy map tilenames convention. |
### Returns [#returns]
Returns a BoundingBoxTuple `[west, south, east, north]` representing the geographic bounds of the tile in decimal degrees.
## Examples [#examples]
### Example: Basic tile conversion [#example-basic-tile-conversion]
```typescript
import { zxyToBbox } from '@accelint/converters/zxy-to-bbox';
// Zoom level 8, tile (71, 96)
const bbox = zxyToBbox([8, 71, 96]);
console.log(bbox);
// [west, south, east, north] in decimal degrees
```
### Example: Web map tile integration [#example-web-map-tile-integration]
```typescript
import { zxyToBbox } from '@accelint/converters/zxy-to-bbox';
// Get bounds for a tile at zoom 12
const zoom = 12;
const tileX = 1234;
const tileY = 5678;
const [west, south, east, north] = zxyToBbox([zoom, tileX, tileY]);
console.log(`Tile bounds:`);
console.log(` West: ${west}°`);
console.log(` South: ${south}°`);
console.log(` East: ${east}°`);
console.log(` North: ${north}°`);
```
### Example: Tile viewport calculation [#example-tile-viewport-calculation]
```typescript
import { zxyToBbox } from '@accelint/converters/zxy-to-bbox';
interface TileViewport {
zoom: number;
tileX: number;
tileY: number;
bounds: {
west: number;
south: number;
east: number;
north: number;
};
}
function getTileViewport(
zoom: number,
tileX: number,
tileY: number
): TileViewport {
const [west, south, east, north] = zxyToBbox([zoom, tileX, tileY]);
return {
zoom,
tileX,
tileY,
bounds: { west, south, east, north }
};
}
const viewport = getTileViewport(10, 512, 768);
console.log(viewport);
```
### Example: Batch tile processing [#example-batch-tile-processing]
```typescript
import { zxyToBbox } from '@accelint/converters/zxy-to-bbox';
// Get bounds for multiple tiles
const tiles = [
[8, 71, 96],
[8, 72, 96],
[8, 71, 97],
[8, 72, 97]
] as const;
const bounds = tiles.map(tile => ({
tile,
bbox: zxyToBbox(tile)
}));
console.log(bounds);
```
### Example: Checking if point is in tile [#example-checking-if-point-is-in-tile]
```typescript
import { zxyToBbox } from '@accelint/converters/zxy-to-bbox';
function isPointInTile(
lon: number,
lat: number,
tile: readonly [number, number, number]
): boolean {
const [west, south, east, north] = zxyToBbox(tile);
return lon >= west && lon <= east && lat >= south && lat <= north;
}
const tile = [10, 512, 768] as const;
console.log(isPointInTile(-122.4194, 37.7749, tile));
// true if San Francisco is in this tile
```
> **Good to know:** This function follows the [OpenStreetMap slippy map tilenames convention](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames). Tile coordinates use a top-left origin, while geographic coordinates use bottom-left (south-west). The function handles the coordinate system conversion automatically.
## Related [#related]
* [Slippy map tilenames (OSM Wiki)](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames)
# Overview (/docs/packages/core)
## Installation [#installation]
```bash
pnpm add @accelint/core
```
## Main Export [#main-export]
```typescript
import { map, filter, pipe } from '@accelint/core';
// Or import from subpaths for better tree-shaking
import { map } from '@accelint/core/array/map';
import { pipe } from '@accelint/core/composition/pipe';
```
## Categories [#categories]
### Array Functions [#array-functions]
Curried array manipulation functions that never mutate the original array:
* **[map](./array/map/index.md)** - Transform array elements
* **[filter](./array/filter/index.md)** - Filter elements by predicate
* **[reduce](./array/reduce/index.md)** - Reduce array to single value
* **[find](./array/find/index.md)** - Find first matching element
* **[every](./array/every/index.md)** - Test if all elements pass
* **[some](./array/some/index.md)** - Test if any element passes
* **[concat](./array/concat/index.md)** - Concatenate arrays
* `findIndex`, `findLast`, `findLastIndex`, `includes`, `indexOf`, `push`, `reduceRight`, `reverse`, `shift`, `slice`, `unshift`
### Composition Functions [#composition-functions]
Function composition and currying utilities:
* **[pipe](./composition/pipe/index.md)** - Compose functions left-to-right
* **[compose](./composition/compose/index.md)** - Compose functions right-to-left
* **[autoCurry](./composition/curry/index.md)** - Transform function to accept partial application
### Combinators [#combinators]
Fundamental functional programming primitives:
* `identity` - Returns input unchanged
* `constant` - Returns constant value ignoring input
* `apply` - Apply function to arguments
* `applyTo` - Apply value to function
* `fork` - Apply multiple functions to same input
* `composition` - Compose two functions
* `inverseConstant` - Returns input ignoring constant
### Logical Operators [#logical-operators]
Functional alternatives to logical operators:
* `and`, `or`, `not`, `xor` - Boolean logic operations
* `nand`, `nor` - Negated logic operations
* `equality` - Curried equality comparison
* `nullishOr` - Nullish coalescing operator
### SafeEnum [#safeenum]
Type-safe enum pattern avoiding TypeScript enum pitfalls:
* **[SafeEnum](./safe-enum/safe-enum/index.md)** - Type for creating safe enums
* **[getSafeEnumValues](./safe-enum/get-safe-enum-values/index.md)** - Extract enum values as array
* `IsLiteralEnum` - Type guard for literal enums
* `ValidEnumStructures` - Base constraint for enums
### Object Manipulation [#object-manipulation]
Immutable object transformation utilities:
* `lens` - Functional lens for deep property access
* `get`, `set` - Get/set values using lenses
* `prop`, `property` - Property accessor functions
* `assoc`, `associate` - Associate values with keys
* `composeLens`, `lensProp`, `lensOptionalProp` - Lens composition
### Iterables [#iterables]
Functional approaches to iteration:
* `createIterable` - Create custom iterables
* `range` - Generate number ranges
### Utility Functions [#utility-functions]
General-purpose utilities:
* `lookup` - Safe property lookup
* `noop` - No-operation function
* `once` - Execute function only once
* `tap` - Tap into pipeline for side effects
* `uuid` - Generate UUIDs
* `isUUID` - Validate UUID format
## Design Principles [#design-principles]
### Currying [#currying]
All functions are curried for easy partial application and composition:
```typescript
import { map, filter, pipe } from '@accelint/core';
// Partial application
const double = map((x: number) => x * 2);
double([1, 2, 3]); // [2, 4, 6]
// Composition
const processNumbers = pipe(
filter((x: number) => x > 0),
map((x: number) => x * 2)
);
processNumbers([-1, 0, 1, 2]); // [2, 4]
```
### Purity [#purity]
All functions are pure with no side effects:
```typescript
import { map } from '@accelint/core';
const original = [1, 2, 3];
const doubled = map((x: number) => x * 2)(original);
console.log(original); // [1, 2, 3] - unchanged
console.log(doubled); // [2, 4, 6] - new array
```
### Type Safety [#type-safety]
Full TypeScript support with precise type inference:
```typescript
import { pipe } from '@accelint/core/composition/pipe';
// Types flow through the pipeline
const transform = pipe(
(x: number) => x * 2, // number => number
(x: number) => x.toString(), // number => string
(x: string) => x.length // string => number
);
const result: number = transform(5); // Type: number
```
## Examples [#examples]
### Example: Data transformation pipeline [#example-data-transformation-pipeline]
```typescript
import { pipe } from '@accelint/core/composition/pipe';
import { filter } from '@accelint/core/array/filter';
import { map } from '@accelint/core/array/map';
import { reduce } from '@accelint/core/array/reduce';
interface Product {
name: string;
price: number;
inStock: boolean;
}
const products: Product[] = [
{ name: 'Widget', price: 10, inStock: true },
{ name: 'Gadget', price: 20, inStock: false },
{ name: 'Doohickey', price: 15, inStock: true }
];
const totalInStockValue = pipe(
filter((p: Product) => p.inStock),
map((p: Product) => p.price),
reduce((sum: number, price: number) => sum + price)(0)
);
totalInStockValue(products); // 25
```
### Example: Safe enum usage [#example-safe-enum-usage]
```typescript
import type { SafeEnum } from '@accelint/core/safe-enum/safe-enum';
import { getSafeEnumValues } from '@accelint/core/safe-enum/get-safe-enum-values';
export const UserRole = Object.freeze({
Admin: 'admin',
Editor: 'editor',
Viewer: 'viewer',
} as const);
export type UserRole = SafeEnum;
function hasPermission(role: UserRole, action: string): boolean {
if (role === UserRole.Admin) return true;
if (role === UserRole.Editor && action === 'edit') return true;
return false;
}
// Validate user input
const validRoles = getSafeEnumValues(UserRole);
function isValidRole(input: string): input is UserRole {
return validRoles.includes(input as UserRole);
}
```
### Example: Function composition [#example-function-composition]
```typescript
import { pipe } from '@accelint/core/composition/pipe';
import { autoCurry } from '@accelint/core/composition/curry';
// Build a flexible greeting function
const greet = autoCurry(
(greeting: string, name: string, punctuation: string) =>
`${greeting}, ${name}${punctuation}`
);
const hello = greet('Hello');
const helloWorld = hello('World');
helloWorld('!'); // "Hello, World!"
helloWorld('?'); // "Hello, World?"
```
## Related Packages [#related-packages]
* `@accelint/converters` - Type conversion utilities
* `@accelint/math` - Mathematical operations
* `@accelint/temporal` - Time and date utilities
* `@accelint/bus` - Event bus system
## License [#license]
Apache-2.0
# Overview (/docs/packages/dataset)
## Installation [#installation]
```bash
pnpm add @accelint/dataset
```
## Usage [#usage]
```typescript
import {
// Type definitions
type AnyDataset,
type GeoJsonWFSDataset,
type LayerDatasetMetadata,
// Lens accessors
datasetId,
datasetName,
datasetTable,
datasetServiceUrls,
datasetGeometryProperty,
// Validation
validateDatasetConfig,
anyDatasetSchema,
} from '@accelint/dataset';
// Define a dataset with type safety
const dataset: GeoJsonWFSDataset = {
id: 'weather-stations',
level: 'generated',
visible: true,
mutatable: false,
name: 'Weather Stations',
description: 'Real-time weather monitoring stations',
serviceType: 'WFS',
dataType: 'GEOJSON',
presentationTypes: { temperature: ['icon', 'point'] },
fields: [
{
id: 'temp',
visible: true,
nullable: false,
type: 'f32',
label: 'Temperature (°C)',
},
],
metadata: {
table: 'weather_stations',
serviceUrls: ['https://api.weather.gov/geoserver/wfs'],
geometryProperty: 'location',
defaultFields: ['station_id', 'temp', 'location'],
},
};
// Extract properties using lenses
const id = datasetId(dataset);
const name = datasetName(dataset);
const tableName = datasetTable(dataset);
// Validate dataset configuration
const validatedDataset = validateDatasetConfig(rawConfig);
```
## Features [#features]
### Type Safety [#type-safety]
Comprehensive TypeScript types covering all dataset configurations:
* **Service Types**: WFS, WMS, VTS, REST, FS, Unknown
* **Data Formats**: GeoJSON, Apache Arrow, Unknown
* **Field Types**: Primitives, temporal types, geometry types
* **Discriminated Unions**: Type-safe handling of different dataset combinations
### Lens-Based Accessors [#lens-based-accessors]
Functional lens utilities for extracting dataset properties:
* **Root Properties**: id, name, description, visibility, mutability
* **Service Configuration**: serviceType, dataType, serviceUrls, serviceVersion
* **Metadata Properties**: table, geometryProperty, zoom levels, batch size
* **Composed Lenses**: Navigate dataset → metadata → property in one call
* **Type-Safe Generics**: Compile-time property key validation
### Validation [#validation]
Zod-based schema validation with formatted error messages:
* **Schema Validation**: Comprehensive anyDatasetSchema
* **Field Validation**: All field types, availableValues, nullability
* **Metadata Validation**: Required/optional properties, format constraints
* **Error Formatting**: Full property paths for debugging
* **Curried Validators**: Reusable validation functions
## Package Structure [#package-structure]
### [Types](./types/datasets.mdx) [#types]
Complete TypeScript type definitions for datasets, fields, and metadata. Includes:
* `LayerDataset` - Generic dataset type
* `AnyDataset`, `AnyWFSDataset`, `AnyGeoJsonDataset` - Union types
* `LayerDatasetField`, `LayerDatasetMetadata` - Configuration types
* Concrete types for all service/data combinations
### [Lenses](./lenses.mdx) [#lenses]
Lens-based accessors for type-safe property extraction. Includes:
* **Root Property Lenses**: `datasetId`, `datasetName`, `datasetServiceType`
* **Metadata Lenses**: `metaDataTable`, `metaDataServiceUrls`, `metaDataBackend`
* **Composed Lenses**: `datasetTable`, `datasetServiceUrls`, `datasetGeometryProperty`
* **Generic Lenses**: `datasetIdProperty`, `datasetGeometryProperty`
### [Validation](./validation.mdx) [#validation-1]
Zod schema validation with error formatting. Includes:
* `anyDatasetSchema` - Complete dataset validation schema
* `validateDatasetConfig` - Pre-configured dataset validator
* `validateSchema` - Curried validation function for any schema
## Core Concepts [#core-concepts]
### Dataset Configuration [#dataset-configuration]
A dataset combines service integration with data specification:
```typescript
type LayerDataset = {
// Identification
id: string;
name: string;
description: string;
// Service integration
readonly serviceType: ServiceType;
readonly dataType: DataType;
// Visualization
presentationTypes: Record;
// Schema
fields: LayerDatasetField[];
// Service metadata
metadata: LayerDatasetMetadata;
}
```
### Service Types [#service-types]
Datasets support multiple service protocols:
* **VTS** - Vector Tile Service (pre-processed tiles)
* **WFS** - Web Feature Service (query-capable vector data)
* **WMS** - Web Map Service (raster tiles)
* **REST** - RESTful API endpoints
* **FS** - File System (local/CDN files)
* **Unknown** - Fallback for unrecognized sources
### Data Formats [#data-formats]
Datasets support multiple data formats:
* **GEOJSON** - RFC 7946 JSON format (universal, human-readable)
* **ARROW** - Apache Arrow columnar format (high performance)
* **Unknown** - Format detection pending or unsupported
### Metadata Configuration [#metadata-configuration]
Metadata contains service-specific configuration:
```typescript
type LayerDatasetMetadata = {
// Required
table: string;
geometryProperty: string;
defaultFields: string[];
// Service integration
serviceUrls?: string[];
serviceVersion?: SemVerVersion;
backend?: string;
vendorParams?: Record;
// Rendering
minZoom?: number;
maxZoom?: number;
positionFormat?: 'XY' | 'XYZ';
// Performance
maxRequests?: number;
refetchInterval?: number;
batchSize?: number;
// Querying
filterDialect?: 'cql' | 'gml';
}
```
## Examples [#examples]
### Example: Complete dataset configuration [#example-complete-dataset-configuration]
```typescript
import type { GeoJsonWFSDataset } from '@accelint/dataset';
const dataset: GeoJsonWFSDataset = {
id: 'earthquake-data-2024',
level: 'generated',
visible: true,
mutatable: false,
name: 'Recent Earthquakes',
description: 'Earthquake events from the last 30 days',
serviceType: 'WFS',
dataType: 'GEOJSON',
presentationTypes: {
magnitude: ['point', 'icon'],
depth: ['point'],
},
fields: [
{
id: 'magnitude',
visible: true,
nullable: false,
type: 'f32',
label: 'Magnitude',
},
{
id: 'depth',
visible: true,
nullable: false,
type: 'f32',
label: 'Depth (km)',
},
{
id: 'region',
visible: true,
nullable: true,
type: 'str',
label: 'Region',
},
],
metadata: {
table: 'earthquakes',
serviceUrls: ['https://earthquake.usgs.gov/geoserver/wfs'],
serviceVersion: '2.0.0',
backend: 'geoserver',
vendorParams: {
viewparams: 'minMagnitude:3.0',
},
geometryProperty: 'location',
idProperty: 'event_id',
minZoom: 2,
maxZoom: 18,
positionFormat: 'XYZ',
defaultFields: ['event_id', 'magnitude', 'depth', 'location'],
filterDialect: 'cql',
},
};
```
### Example: Using lenses for property extraction [#example-using-lenses-for-property-extraction]
```typescript
import {
datasetName,
datasetServiceUrls,
datasetTable,
datasetDefaultFields,
datasetGeometryProperty,
} from '@accelint/dataset';
function buildQueryUrl(dataset: AnyDataset): string {
const urls = datasetServiceUrls(dataset);
const table = datasetTable(dataset);
const fields = datasetDefaultFields(dataset);
const baseUrl = urls?.[0] || '';
const params = new URLSearchParams({
typeName: table,
propertyName: fields.join(','),
});
return `${baseUrl}?${params}`;
}
type Feature = { id: number; geom: Point };
const geomKey = datasetGeometryProperty(dataset);
const coordinates = feature[geomKey];
```
### Example: Validating dataset configurations [#example-validating-dataset-configurations]
```typescript
import { validateDatasetConfig } from '@accelint/dataset';
async function loadDataset(id: string) {
const response = await fetch(`/api/datasets/${id}`);
const rawData = await response.json();
try {
const dataset = validateDatasetConfig(rawData);
return { success: true, dataset };
} catch (error) {
console.error('Validation failed:', error.message);
return { success: false, error: error.message };
}
}
```
### Example: Type-safe dataset handling [#example-type-safe-dataset-handling]
```typescript
import type { AnyDataset, AnyArrowDataset } from '@accelint/dataset';
function isArrowDataset(dataset: AnyDataset): dataset is AnyArrowDataset {
return dataset.dataType === 'ARROW';
}
function selectParser(dataset: AnyDataset) {
if (isArrowDataset(dataset)) {
// TypeScript knows this is AnyArrowDataset
return new ArrowParser({ batchSize: dataset.metadata.batchSize });
}
return new GeoJsonParser();
}
```
> **Good to know:** The package uses functional lenses from `@accelint/core` for immutable property access. All lens functions are pure and return new values without modifying inputs. The type system enforces valid service/data type combinations at compile time through generic constraints.
## Related [#related]
* [@accelint/core](../core/index.mdx) - Lens utilities (lensProp, composeLens, get)
* [Zod Documentation](https://zod.dev/) - Schema validation library
* [Deck.gl Documentation](https://deck.gl/) - Visualization layer reference
# Lenses (/docs/packages/dataset/lenses)
## Usage [#usage]
```typescript
import {
datasetId,
datasetName,
datasetTable,
datasetServiceUrls,
datasetGeometryProperty,
} from '@accelint/dataset';
// Extract root properties
const id = datasetId(dataset);
const name = datasetName(dataset);
// Extract metadata properties (composed lenses)
const tableName = datasetTable(dataset);
const urls = datasetServiceUrls(dataset);
// Type-safe property extraction with generics
type Feature = { id: number; location: Point };
const geomKey = datasetGeometryProperty(dataset); // 'location'
const coords = feature[geomKey];
```
## Reference [#reference]
The package exports two categories of lens functions: **Root Property Lenses** for direct dataset properties and **Composed Lenses** for nested metadata properties.
### Root Property Lenses [#root-property-lenses]
Extract top-level dataset properties directly.
#### datasetId [#datasetid]
```typescript
function datasetId(dataset: AnyDataset): string
```
Extracts the unique identifier from a dataset.
**Parameters:**
* `dataset` - The dataset to extract id from
**Returns:** The unique dataset identifier string
#### datasetLevel [#datasetlevel]
```typescript
function datasetLevel(dataset: AnyDataset): 'generated' | 'user'
```
Extracts the provenance level from a dataset.
**Parameters:**
* `dataset` - The dataset to extract level from
**Returns:** `'generated'` for system-created datasets or `'user'` for user-uploaded datasets
#### datasetVisible [#datasetvisible]
```typescript
function datasetVisible(dataset: AnyDataset): boolean
```
Extracts the visibility state from a dataset.
**Parameters:**
* `dataset` - The dataset to extract visibility from
**Returns:** Boolean indicating initial visibility
#### datasetMutatable [#datasetmutatable]
```typescript
function datasetMutatable(dataset: AnyDataset): boolean
```
Extracts the mutability flag from a dataset.
**Parameters:**
* `dataset` - The dataset to extract mutability from
**Returns:** Boolean indicating if dataset can be modified
#### datasetName [#datasetname]
```typescript
function datasetName(dataset: AnyDataset): string
```
Extracts the display name from a dataset.
**Parameters:**
* `dataset` - The dataset to extract name from
**Returns:** Human-readable dataset name
#### datasetDescription [#datasetdescription]
```typescript
function datasetDescription(dataset: AnyDataset): string
```
Extracts the description from a dataset.
**Parameters:**
* `dataset` - The dataset to extract description from
**Returns:** Detailed dataset description string
#### datasetServiceType [#datasetservicetype]
```typescript
function datasetServiceType(dataset: AnyDataset): LayerServiceType
```
Extracts the service type from a dataset.
**Parameters:**
* `dataset` - The dataset to extract service type from
**Returns:** The service protocol type: `'VTS'` | `'WMS'` | `'WFS'` | `'REST'` | `'FS'` | `'Unknown'`
#### datasetDataType [#datasetdatatype]
```typescript
function datasetDataType(dataset: AnyDataset): LayerDataType
```
Extracts the data format type from a dataset.
**Parameters:**
* `dataset` - The dataset to extract data type from
**Returns:** The data format type: `'GEOJSON'` | `'ARROW'` | `'Unknown'`
#### datasetPresentationTypes [#datasetpresentationtypes]
```typescript
function datasetPresentationTypes(
dataset: AnyDataset
): Record
```
Extracts presentation types from a dataset.
**Parameters:**
* `dataset` - The dataset to extract presentation types from
**Returns:** Record mapping field names to available visualization types
#### datasetFields [#datasetfields]
```typescript
function datasetFields(dataset: AnyDataset): LayerDatasetField[]
```
Extracts field definitions from a dataset.
**Parameters:**
* `dataset` - The dataset to extract fields from
**Returns:** Array of `LayerDatasetField` objects
#### datasetMetaData [#datasetmetadata]
```typescript
function datasetMetaData(dataset: AnyDataset): LayerDatasetMetadata
```
Extracts metadata from a dataset.
**Parameters:**
* `dataset` - The dataset to extract metadata from
**Returns:** The `LayerDatasetMetadata` object
### Metadata Property Lenses (Direct Access) [#metadata-property-lenses-direct-access]
Extract properties from `LayerDatasetMetadata` objects directly.
#### metaDataTable [#metadatatable]
```typescript
function metaDataTable(metadata: LayerDatasetMetadata): string
```
Extracts the table name from metadata.
**Parameters:**
* `metadata` - The metadata object to extract from
**Returns:** The database table name
#### metaDataServiceUrls [#metadataserviceurls]
```typescript
function metaDataServiceUrls(metadata: LayerDatasetMetadata): string[] | undefined
```
Extracts service URLs from metadata.
**Parameters:**
* `metadata` - The metadata object to extract from
**Returns:** Array of service endpoint URLs or undefined
#### metaDataServiceVersion [#metadataserviceversion]
```typescript
function metaDataServiceVersion(metadata: LayerDatasetMetadata): SemVerVersion | undefined
```
Extracts the service version from metadata.
**Parameters:**
* `metadata` - The metadata object to extract from
**Returns:** The service version string or undefined
#### metaDataServiceLayer [#metadataservicelayer]
```typescript
function metaDataServiceLayer(metadata: LayerDatasetMetadata): string | undefined
```
Extracts the service layer identifier from metadata.
**Parameters:**
* `metadata` - The metadata object to extract from
**Returns:** The service layer identifier or undefined
#### metaDataBackend [#metadatabackend]
```typescript
function metaDataBackend(metadata: LayerDatasetMetadata): string | undefined
```
Extracts the backend implementation identifier from metadata.
**Parameters:**
* `metadata` - The metadata object to extract from
**Returns:** Backend identifier string or undefined
#### metaDataVendorParams [#metadatavendorparams]
```typescript
function metaDataVendorParams(metadata: LayerDatasetMetadata): Record | undefined
```
Extracts backend-specific vendor parameters from metadata.
**Parameters:**
* `metadata` - The metadata object to extract from
**Returns:** Record of vendor-specific parameters or undefined
### Composed Dataset Lenses [#composed-dataset-lenses]
Extract metadata properties directly from dataset objects using composed lenses (dataset → metadata → property).
#### datasetTable [#datasettable]
```typescript
function datasetTable(dataset: AnyDataset): string
```
Extracts the table name directly from a dataset.
**Parameters:**
* `dataset` - The dataset to extract table name from
**Returns:** The database table name
#### datasetServiceUrls [#datasetserviceurls]
```typescript
function datasetServiceUrls(dataset: AnyDataset): string[] | undefined
```
Extracts service URLs directly from a dataset.
**Parameters:**
* `dataset` - The dataset to extract service URLs from
**Returns:** Array of service endpoint URLs or undefined
#### datasetServiceVersion [#datasetserviceversion]
```typescript
function datasetServiceVersion(dataset: AnyDataset): SemVerVersion | undefined
```
Extracts the service version directly from a dataset.
**Parameters:**
* `dataset` - The dataset to extract service version from
**Returns:** The service version string or undefined
#### datasetServiceLayer [#datasetservicelayer]
```typescript
function datasetServiceLayer(dataset: AnyDataset): string | undefined
```
Extracts the service layer identifier directly from a dataset.
**Parameters:**
* `dataset` - The dataset to extract service layer from
**Returns:** The service layer identifier or undefined
#### datasetBackend [#datasetbackend]
```typescript
function datasetBackend(dataset: AnyDataset): string | undefined
```
Extracts the backend implementation identifier directly from a dataset.
**Parameters:**
* `dataset` - The dataset to extract backend from
**Returns:** Backend identifier string or undefined
#### datasetVendorParams [#datasetvendorparams]
```typescript
function datasetVendorParams(dataset: AnyDataset): Record | undefined
```
Extracts backend-specific vendor parameters directly from a dataset.
**Parameters:**
* `dataset` - The dataset to extract vendor params from
**Returns:** Record of vendor-specific parameters or undefined
#### datasetIdProperty [#datasetidproperty]
```typescript
function datasetIdProperty(dataset: AnyDataset): keyof T
```
Extracts the feature identifier property name directly from a dataset.
**Type Parameters:**
* `T` - The expected feature type with typed property keys
**Parameters:**
* `dataset` - The dataset to extract id property from
**Returns:** The id property name as a key of T
#### datasetGeometryProperty [#datasetgeometryproperty]
```typescript
function datasetGeometryProperty(dataset: AnyDataset): keyof T
```
Extracts the geometry property name directly from a dataset.
**Type Parameters:**
* `T` - The expected feature type with typed property keys
**Parameters:**
* `dataset` - The dataset to extract geometry property from
**Returns:** The geometry property name as a key of T
#### datasetMinZoom [#datasetminzoom]
```typescript
function datasetMinZoom(dataset: AnyDataset): number | undefined
```
Extracts the minimum zoom level directly from a dataset.
**Parameters:**
* `dataset` - The dataset to extract min zoom from
**Returns:** The minimum zoom level or undefined
#### datasetMaxZoom [#datasetmaxzoom]
```typescript
function datasetMaxZoom(dataset: AnyDataset): number | undefined
```
Extracts the maximum zoom level directly from a dataset.
**Parameters:**
* `dataset` - The dataset to extract max zoom from
**Returns:** The maximum zoom level or undefined
#### datasetPositionFormat [#datasetpositionformat]
```typescript
function datasetPositionFormat(dataset: AnyDataset): 'XY' | 'XYZ' | undefined
```
Extracts the position format directly from a dataset.
**Parameters:**
* `dataset` - The dataset to extract position format from
**Returns:** `'XY'` | `'XYZ'` | undefined
#### datasetMaxRequests [#datasetmaxrequests]
```typescript
function datasetMaxRequests(dataset: AnyDataset): number | undefined
```
Extracts the maximum concurrent requests directly from a dataset.
**Parameters:**
* `dataset` - The dataset to extract max requests from
**Returns:** The max requests limit or undefined
#### datasetRefetchInterval [#datasetrefetchinterval]
```typescript
function datasetRefetchInterval(dataset: AnyDataset): number | undefined
```
Extracts the refetch interval directly from a dataset.
**Parameters:**
* `dataset` - The dataset to extract refetch interval from
**Returns:** The refetch interval in milliseconds or undefined
#### datasetDefaultFields [#datasetdefaultfields]
```typescript
function datasetDefaultFields(dataset: AnyDataset): string[]
```
Extracts the default fields array directly from a dataset.
**Parameters:**
* `dataset` - The dataset to extract default fields from
**Returns:** Array of field names
#### datasetBatchSize [#datasetbatchsize]
```typescript
function datasetBatchSize(dataset: AnyDataset): number | undefined
```
Extracts the batch size directly from a dataset.
**Parameters:**
* `dataset` - The dataset to extract batch size from
**Returns:** The batch size or undefined
#### datasetFilterDialect [#datasetfilterdialect]
```typescript
function datasetFilterDialect(dataset: AnyDataset): FilterDialect | undefined
```
Extracts the filter dialect directly from a dataset.
**Parameters:**
* `dataset` - The dataset to extract filter dialect from
**Returns:** `'cql'` | `'gml'` | undefined
## Examples [#examples]
### Example: Building a dataset display component [#example-building-a-dataset-display-component]
```typescript
import {
datasetId,
datasetName,
datasetDescription,
datasetServiceType,
datasetVisible,
} from '@accelint/dataset';
function DatasetCard({ dataset }: { dataset: AnyDataset }) {
const id = datasetId(dataset);
const name = datasetName(dataset);
const description = datasetDescription(dataset);
const serviceType = datasetServiceType(dataset);
const isVisible = datasetVisible(dataset);
return (
{name}
{description}
Service: {serviceType}
{isVisible && Currently visible}
);
}
```
### Example: Building service endpoint URLs [#example-building-service-endpoint-urls]
```typescript
import {
datasetServiceUrls,
datasetServiceVersion,
datasetServiceLayer,
datasetTable,
} from '@accelint/dataset';
function buildWFSUrl(dataset: AnyDataset): string {
const urls = datasetServiceUrls(dataset);
const version = datasetServiceVersion(dataset);
const layer = datasetServiceLayer(dataset);
const table = datasetTable(dataset);
const baseUrl = urls?.[0] || '';
const queryParams = new URLSearchParams({
service: 'WFS',
version: version || '2.0.0',
request: 'GetFeature',
typeName: layer || table,
outputFormat: 'application/json',
});
return `${baseUrl}?${queryParams}`;
}
```
### Example: Type-safe feature property access [#example-type-safe-feature-property-access]
```typescript
import { datasetIdProperty, datasetGeometryProperty } from '@accelint/dataset';
type WeatherFeature = {
// biome-ignore lint/style/useNamingConvention: API response format
station_id: string;
temperature: number;
humidity: number;
location: [number, number];
};
function extractFeatureData(
dataset: AnyDataset,
feature: WeatherFeature
) {
// Type-safe property extraction
const idKey = datasetIdProperty(dataset); // 'station_id'
const geomKey = datasetGeometryProperty(dataset); // 'location'
return {
id: feature[idKey],
coordinates: feature[geomKey],
temperature: feature.temperature,
};
}
```
### Example: Configuring data fetching [#example-configuring-data-fetching]
```typescript
import {
datasetMaxRequests,
datasetRefetchInterval,
datasetBatchSize,
datasetDefaultFields,
} from '@accelint/dataset';
function createFetchConfig(dataset: AnyDataset) {
const maxRequests = datasetMaxRequests(dataset) || 6;
const refetchInterval = datasetRefetchInterval(dataset);
const batchSize = datasetBatchSize(dataset) || 10000;
const fields = datasetDefaultFields(dataset);
return {
concurrency: maxRequests,
polling: refetchInterval ? { interval: refetchInterval } : null,
pagination: { pageSize: batchSize },
fields: fields.join(','),
};
}
```
### Example: Handling backend-specific configuration [#example-handling-backend-specific-configuration]
```typescript
import {
datasetBackend,
datasetVendorParams,
datasetFilterDialect,
} from '@accelint/dataset';
function buildBackendConfig(dataset: AnyDataset) {
const backend = datasetBackend(dataset);
const vendorParams = datasetVendorParams(dataset);
const filterDialect = datasetFilterDialect(dataset);
if (backend === 'geoserver' && vendorParams) {
return {
backend,
formatOptions: vendorParams.formatOptions,
viewparams: vendorParams.viewparams,
filterFormat: filterDialect || 'cql',
};
}
return { backend, filterFormat: filterDialect || 'cql' };
}
```
### Example: Rendering field-based visualizations [#example-rendering-field-based-visualizations]
```typescript
import {
datasetFields,
datasetPresentationTypes,
datasetDataType,
} from '@accelint/dataset';
function selectVisualization(dataset: AnyDataset, fieldName: string) {
const fields = datasetFields(dataset);
const presentationTypes = datasetPresentationTypes(dataset);
const dataType = datasetDataType(dataset);
const field = fields.find(f => f.id === fieldName);
const availableTypes = presentationTypes[fieldName];
if (!field || !availableTypes) {
return null;
}
// Choose appropriate visualization based on field type and data format
if (dataType === 'ARROW' && availableTypes.includes('point')) {
return { type: 'point', field: field.id, label: field.label };
}
return { type: availableTypes[0], field: field.id, label: field.label };
}
```
> **Good to know:** All lens functions are pure and do not modify the input dataset. Optional properties return `undefined` when not present. The generic type parameters on `datasetIdProperty` and `datasetGeometryProperty` provide compile-time type safety for feature property access.
## Related [#related]
* [types/datasets](./types/datasets.mdx) - Dataset type definitions and unions
* [validation](./validation.mdx) - Dataset configuration validation
* [@accelint/core](../../core/index.mdx) - Lens utilities (lensProp, composeLens, get)
# Types (/docs/packages/dataset/types)
## Usage [#usage]
```typescript
import type {
AnyDataset,
LayerDataset,
GeoJsonWFSDataset,
ArrowRESTDataset,
LayerDatasetMetadata,
LayerDatasetField,
} from '@accelint/dataset';
// Use specific dataset types for type safety
const wfsDataset: GeoJsonWFSDataset = {
id: 'weather-stations',
level: 'generated',
visible: true,
mutatable: false,
name: 'Weather Stations',
description: 'Real-time weather monitoring stations',
serviceType: 'WFS',
dataType: 'GEOJSON',
presentationTypes: { temperature: ['icon', 'point'] },
fields: [],
metadata: {
table: 'weather_stations',
geometryProperty: 'location',
defaultFields: ['id', 'temp', 'location'],
},
};
// Use AnyDataset for generic handling
function processDataset(dataset: AnyDataset) {
// Works with any dataset type
}
```
## Reference [#reference]
### Core Types [#core-types]
#### LayerDataset [#layerdataset]
```typescript
type LayerDataset<
DataType extends LayerDataType,
ServiceType extends LayerServiceType,
ExtensionType = ''
>
```
Core dataset configuration combining service integration and data specification. Generic type with compile-time validation of service/data type combinations.
**Type Parameters:**
* `DataType` - Must extend `LayerDataType` (`'GEOJSON'` | `'ARROW'` | `'Unknown'`)
* `ServiceType` - Must extend `LayerServiceType` (`'VTS'` | `'WMS'` | `'WFS'` | `'REST'` | `'FS'` | `'Unknown'`)
* `ExtensionType` - String union of available visual extension types (default: `''`)
**Properties:**
* `id: string` - Unique dataset identifier
* `level: 'generated' | 'user'` - Dataset provenance indicator
* `visible: boolean` - Initial visibility state
* `mutatable: boolean` - Mutability flag for dataset modifications
* `name: string` - Human-readable dataset name
* `description: string` - Detailed dataset description
* `readonly serviceType: ServiceType` - Service integration type
* `readonly dataType: DataType` - Expected response data format
* `presentationTypes: Record` - Available presentation modes per field
* `fields: LayerDatasetField[]` - Complete field schema
* `metadata: LayerDatasetMetadata` - Service integration and rendering metadata
#### LayerServiceType [#layerservicetype]
```typescript
type LayerServiceType = 'VTS' | 'WMS' | 'WFS' | 'REST' | 'FS' | 'Unknown'
```
Service protocols supported for dataset integration.
* **`'VTS'`** - Vector Tile Service (high performance, pre-processed tiles)
* **`'WMS'`** - Web Map Service (raster tiles with feature information)
* **`'WFS'`** - Web Feature Service (vector feature data with query capabilities)
* **`'REST'`** - RESTful Service (generic resource-oriented endpoints)
* **`'FS'`** - File System (static files, local uploads, CDN-hosted data)
* **`'Unknown'`** - Fallback for unrecognized or pending service detection
#### LayerDataType [#layerdatatype]
```typescript
type LayerDataType = 'GEOJSON' | 'ARROW' | 'Unknown'
```
Supported data formats for dataset responses and processing.
* **`'GEOJSON'`** - RFC 7946 compliant JSON format, universally supported, human-readable
* **`'ARROW'`** - Apache Arrow columnar format, high performance, efficient memory usage
* **`'Unknown'`** - Format detection pending, error state, or unsupported formats
#### LayerConfigType [#layerconfigtype]
```typescript
type LayerConfigType = 'icon' | 'point' | 'path' | 'polygon' | 'raster'
```
Built-in layer types for Deck.gl visualization layers.
* **`'icon'`** - MaskedIconLayer for point data with custom symbols
* **`'point'`** - ScatterplotLayer for simple circular point visualization
* **`'path'`** - PathLayer for line/polyline data
* **`'polygon'`** - PolygonLayer for filled area shapes
* **`'raster'`** - Raster layer for image-based rendering
Custom layer types can be added via extension without modifying this core type.
#### SemVerVersion [#semverversion]
```typescript
type SemVerVersion = `${string}.${string}.${string}`
```
Supported semver style protocol versions for WMS/WFS service endpoints.
Version selection affects available request parameters, response formats, spatial reference system support, query capabilities, and performance characteristics.
#### FilterDialect [#filterdialect]
```typescript
type FilterDialect = 'cql' | 'gml'
```
Query language dialect for server-side spatial filtering operations.
* **`'cql'`** - Common Query Language (ECQL), text-based syntax (e.g., `temperature > 20 AND status = 'active'`)
* **`'gml'`** - OGC Filter Encoding, XML-based GML format
### Field Configuration [#field-configuration]
#### LayerDatasetField [#layerdatasetfield]
```typescript
type LayerDatasetField = {
id: string;
visible: boolean;
nullable: boolean;
type: LayerDatasetFieldTypes;
label: string;
availableValues?: { name: string; label: string }[];
}
```
Configuration for a single field within a dataset. Defines field metadata, visibility, and data constraints.
**Properties:**
* `id` - Unique identifier for this field
* `visible` - Controls field visibility in filter UI components
* `nullable` - Whether this field accepts null/undefined values
* `type` - Data type specification (see `LayerDatasetFieldTypes`)
* `label` - Human-readable display name
* `availableValues` - Predefined options for select/dropdown components (optional)
#### LayerDatasetFieldTypes [#layerdatasetfieldtypes]
```typescript
type LayerDatasetFieldTypes =
| 'bool' | 'date' | 'datetime' | 'f32' | 'f64'
| 'i32' | 'i64' | 'linestring' | 'multilinestring'
| 'multipoint' | 'multipolygon' | 'point'
| 'polygon' | 'str' | 'time'
```
Supported data types for layer dataset fields.
**Primitive types:** `bool`, `i32`, `i64`, `str`, `f32`, `f64`
**Temporal types:** `date`, `datetime`, `time`
**Geometry types:** `point`, `multipoint`, `linestring`, `multilinestring`, `polygon`, `multipolygon`
### Metadata Configuration [#metadata-configuration]
#### LayerDatasetMetadata [#layerdatasetmetadata]
```typescript
type LayerDatasetMetadata = {
table: string;
serviceUrls?: string[];
serviceVersion?: SemVerVersion;
backend?: string;
vendorParams?: Record;
serviceLayer?: string;
idProperty?: string;
geometryProperty: string;
minZoom?: number;
maxZoom?: number;
positionFormat?: 'XYZ' | 'XY';
maxRequests?: number;
refetchInterval?: number;
defaultFields: string[];
batchSize?: number;
filterDialect?: FilterDialect;
}
```
Metadata configuration for dataset service integration and rendering. Contains service endpoint information, zoom constraints, and field specifications.
**Required Properties:**
* `table` - Original database table name
* `geometryProperty` - Primary geometry field name
* `defaultFields` - Essential fields for client-side operations
**Optional Properties:**
* `serviceUrls` - List of service endpoint URL templates
* `serviceVersion` - Geoserver service version override
* `backend` - Backend implementation identifier (e.g., `'geoserver'`, `'mapserver'`)
* `vendorParams` - Backend-specific vendor parameters
* `serviceLayer` - Layer identifier for service requests
* `idProperty` - Unique feature identifier property name
* `minZoom` / `maxZoom` - Zoom level constraints
* `positionFormat` - Coordinate system format (`'XY'` or `'XYZ'`)
* `maxRequests` - Concurrent request limit (default: 6)
* `refetchInterval` - Data refresh interval in milliseconds
* `batchSize` - Batch size for Arrow data requests (default: 10000)
* `filterDialect` - Filter expression dialect (default: `'cql'`)
### Concrete Dataset Types [#concrete-dataset-types]
#### GeoJSON Dataset Variants [#geojson-dataset-variants]
```typescript
type GeoJsonFSDataset = LayerDataset<'GEOJSON', 'FS', ExtensionType>
type GeoJsonUnknownDataset = LayerDataset<'GEOJSON', 'Unknown', ExtensionType>
type GeoJsonVTSDataset = LayerDataset<'GEOJSON', 'VTS', ExtensionType>
type GeoJsonWFSDataset = LayerDataset<'GEOJSON', 'WFS', ExtensionType>
type GeoJsonWMSDataset = LayerDataset<'GEOJSON', 'WMS', ExtensionType>
type GeoJsonRESTDataset = LayerDataset<'GEOJSON', 'REST', ExtensionType>
```
Specific GeoJSON dataset types for each service protocol.
#### Arrow Dataset Variants [#arrow-dataset-variants]
```typescript
type ArrowFSDataset = LayerDataset<'ARROW', 'FS', ExtensionType>
type ArrowUnknownDataset = LayerDataset<'ARROW', 'Unknown', ExtensionType>
type ArrowVTSDataset = LayerDataset<'ARROW', 'VTS', ExtensionType>
type ArrowWFSDataset = LayerDataset<'ARROW', 'WFS', ExtensionType>
type ArrowWMSDataset = LayerDataset<'ARROW', 'WMS', ExtensionType>
type ArrowRESTDataset = LayerDataset<'ARROW', 'REST', ExtensionType>
```
Specific Arrow dataset types for each service protocol.
#### Unknown Data Type Variants [#unknown-data-type-variants]
```typescript
type UnknownFSDataset = LayerDataset<'Unknown', 'FS', ExtensionType>
type UnknownUnknownDataset = LayerDataset<'Unknown', 'Unknown', ExtensionType>
type UnknownVTSDataset = LayerDataset<'Unknown', 'VTS', ExtensionType>
type UnknownWFSDataset = LayerDataset<'Unknown', 'WFS', ExtensionType>
type UnknownWMSDataset = LayerDataset<'Unknown', 'WMS', ExtensionType>
type UnknownRESTDataset = LayerDataset<'Unknown', 'REST', ExtensionType>
```
Dataset types with unknown data format (format detection pending, error states, unsupported formats).
### Union Types [#union-types]
#### Service Type Unions [#service-type-unions]
```typescript
type AnyVTSDataset =
| GeoJsonVTSDataset
| ArrowVTSDataset
| UnknownVTSDataset
type AnyWFSDataset =
| GeoJsonWFSDataset
| ArrowWFSDataset
| UnknownWFSDataset
type AnyWMSDataset =
| GeoJsonWMSDataset
| ArrowWMSDataset
| UnknownWMSDataset
type AnyRESTDataset =
| GeoJsonRESTDataset
| ArrowRESTDataset
| UnknownRESTDataset
type AnyFSDataset =
| GeoJsonFSDataset
| ArrowFSDataset
| UnknownFSDataset
type AnyUnknownDataset =
| GeoJsonUnknownDataset
| ArrowUnknownDataset
| UnknownUnknownDataset
```
Unions grouping datasets by service type, accepting any data format.
#### Data Type Unions [#data-type-unions]
```typescript
type AnyGeoJsonDataset =
| GeoJsonFSDataset
| GeoJsonUnknownDataset
| GeoJsonVTSDataset
| GeoJsonWFSDataset
| GeoJsonWMSDataset
| GeoJsonRESTDataset
type AnyArrowDataset =
| ArrowFSDataset
| ArrowUnknownDataset
| ArrowVTSDataset
| ArrowWFSDataset
| ArrowWMSDataset
| ArrowRESTDataset
type AnyUnknownDataDataset =
| UnknownFSDataset
| UnknownUnknownDataset
| UnknownVTSDataset
| UnknownWFSDataset
| UnknownWMSDataset
| UnknownRESTDataset
```
Unions grouping datasets by data format, accepting any service type.
#### AnyDataset [#anydataset]
```typescript
type AnyDataset =
| AnyArrowDataset
| AnyGeoJsonDataset
| AnyUnknownDataDataset
```
Complete union of all possible dataset type combinations. Use for generic dataset handling where specific type constraints are not required.
## Examples [#examples]
### Example: Defining a WFS dataset [#example-defining-a-wfs-dataset]
```typescript
import type { GeoJsonWFSDataset } from '@accelint/dataset';
const weatherDataset: GeoJsonWFSDataset = {
id: 'weather-stations-2024',
level: 'generated',
visible: true,
mutatable: false,
name: 'Weather Stations',
description: 'Real-time weather monitoring stations across the region',
serviceType: 'WFS',
dataType: 'GEOJSON',
presentationTypes: {
temperature: ['icon', 'point'],
humidity: ['point'],
},
fields: [
{
id: 'temp',
visible: true,
nullable: false,
type: 'f32',
label: 'Temperature (°C)',
},
{
id: 'humidity',
visible: true,
nullable: false,
type: 'f32',
label: 'Humidity (%)',
},
{
id: 'status',
visible: true,
nullable: true,
type: 'str',
label: 'Status',
availableValues: [
{ name: 'active', label: 'Active' },
{ name: 'inactive', label: 'Inactive' },
],
},
],
metadata: {
table: 'weather_stations',
serviceUrls: ['https://api.weather.gov/geoserver/wfs'],
serviceVersion: '2.0.0',
backend: 'geoserver',
vendorParams: {
formatOptions: 'includeFids:false;batchSize:10000',
},
geometryProperty: 'location',
idProperty: 'station_id',
minZoom: 5,
maxZoom: 18,
defaultFields: ['station_id', 'temp', 'humidity', 'location'],
filterDialect: 'cql',
},
};
```
### Example: Type-safe dataset handling with discriminated unions [#example-type-safe-dataset-handling-with-discriminated-unions]
```typescript
import type { AnyDataset } from '@accelint/dataset';
function getDataSourceLabel(dataset: AnyDataset): string {
switch (dataset.serviceType) {
case 'WFS':
return 'Web Feature Service';
case 'WMS':
return 'Web Map Service';
case 'VTS':
return 'Vector Tile Service';
case 'REST':
return 'REST API';
case 'FS':
return 'File System';
case 'Unknown':
return 'Unknown Source';
}
}
function getFormatLabel(dataset: AnyDataset): string {
switch (dataset.dataType) {
case 'GEOJSON':
return 'GeoJSON';
case 'ARROW':
return 'Apache Arrow';
case 'Unknown':
return 'Unknown Format';
}
}
```
### Example: Generic dataset processing [#example-generic-dataset-processing]
```typescript
import type { AnyDataset, AnyWFSDataset } from '@accelint/dataset';
function isWFSDataset(dataset: AnyDataset): dataset is AnyWFSDataset {
return dataset.serviceType === 'WFS';
}
function processDataset(dataset: AnyDataset) {
if (isWFSDataset(dataset)) {
// TypeScript knows this is AnyWFSDataset
const version = dataset.metadata.serviceVersion || '2.0.0';
console.log(`Processing WFS ${version} dataset`);
}
}
```
### Example: Building metadata with optional properties [#example-building-metadata-with-optional-properties]
```typescript
import type { LayerDatasetMetadata } from '@accelint/dataset';
function createMetadata(
table: string,
geometryProperty: string,
defaultFields: string[],
options?: {
serviceUrls?: string[];
backend?: string;
minZoom?: number;
maxZoom?: number;
}
): LayerDatasetMetadata {
return {
table,
geometryProperty,
defaultFields,
...options,
};
}
const metadata = createMetadata(
'cities',
'geom',
['id', 'name', 'geom'],
{
serviceUrls: ['https://geoserver.example.com/wfs'],
backend: 'geoserver',
minZoom: 3,
maxZoom: 15,
}
);
```
### Example: Field configuration with available values [#example-field-configuration-with-available-values]
```typescript
import type { LayerDatasetField } from '@accelint/dataset';
const statusField: LayerDatasetField = {
id: 'status',
visible: true,
nullable: true,
type: 'str',
label: 'Status',
availableValues: [
{ name: 'active', label: 'Active' },
{ name: 'inactive', label: 'Inactive' },
{ name: 'pending', label: 'Pending Review' },
{ name: 'archived', label: 'Archived' },
],
};
const temperatureField: LayerDatasetField = {
id: 'temp_celsius',
visible: true,
nullable: false,
type: 'f32',
label: 'Temperature (°C)',
};
```
### Example: Extension types for custom layers [#example-extension-types-for-custom-layers]
```typescript
import type { LayerDataset } from '@accelint/dataset';
// Define custom extension types
type CustomLayerTypes = 'heatmap' | 'contour' | '3d-surface';
// Use with dataset type
type CustomGeoJsonWFS = LayerDataset<'GEOJSON', 'WFS', CustomLayerTypes>;
const customDataset: CustomGeoJsonWFS = {
id: 'elevation-data',
level: 'generated',
visible: true,
mutatable: false,
name: 'Elevation Data',
description: 'Terrain elevation with custom visualizations',
serviceType: 'WFS',
dataType: 'GEOJSON',
presentationTypes: {
elevation: ['heatmap', 'contour', '3d-surface', 'polygon'],
},
fields: [],
metadata: {
table: 'elevation',
geometryProperty: 'geom',
defaultFields: ['elevation', 'geom'],
},
};
```
> **Good to know:** The type system uses generics to enforce valid service/data type combinations at compile time. The `readonly` modifiers on `serviceType` and `dataType` prevent accidental mutation after creation. Union types like `AnyDataset` provide flexibility for generic handling while specific types like `GeoJsonWFSDataset` enable precise type checking.
## Related [#related]
* [lenses](../lenses.mdx) - Lens-based property accessors
* [validation](../validation.mdx) - Zod schema validation for datasets
* [Deck.gl Layer Documentation](https://deck.gl/docs/api-reference/layers) - Visualization layer reference
# Validation (/docs/packages/dataset/validation)
## Usage [#usage]
```typescript
import { validateDatasetConfig, validateSchema, anyDatasetSchema } from '@accelint/dataset';
// Validate a dataset configuration
const dataset = validateDatasetConfig(rawConfig);
// Create reusable validators for any schema
const validateCustom = validateSchema(customSchema);
const result = validateCustom(data);
```
## Reference [#reference]
### anyDatasetSchema [#anydatasetschema]
```typescript
const anyDatasetSchema: z.ZodObject<{
id: z.ZodString;
level: z.ZodEnum<['generated', 'user']>;
visible: z.ZodBoolean;
mutatable: z.ZodBoolean;
name: z.ZodString;
description: z.ZodString;
serviceType: z.ZodEnum<['VTS', 'WMS', 'WFS', 'FS', 'Unknown']>;
dataType: z.ZodEnum<['GEOJSON', 'ARROW', 'Unknown']>;
presentationTypes: z.ZodRecord>>;
fields: z.ZodArray>;
metadata: z.ZodObject<...>;
}>
```
Complete Zod schema for validating dataset configurations. Validates structure, enums, types, and nested metadata.
**Supported service types:** `'VTS'` | `'WMS'` | `'WFS'` | `'FS'` | `'REST'` | `'Unknown'`
**Supported data types:** `'GEOJSON'` | `'ARROW'` | `'Unknown'`
**Field types:** `'bool'`, `'date'`, `'datetime'`, `'f32'`, `'f64'`, `'i32'`, `'i64'`, `'linestring'`, `'multilinestring'`, `'multipoint'`, `'multipolygon'`, `'point'`, `'polygon'`, `'str'`, `'time'`
**Metadata validation includes:**
* Required: `table`, `geometryProperty`, `defaultFields`
* Optional: `serviceUrls`, `serviceVersion`, `serviceLayer`, `backend`, `vendorParams`, `idProperty`, `minZoom`, `maxZoom`, `positionFormat`, `maxRequests`, `refetchInterval`, `batchSize`, `filterDialect`
* Version format: Must be `x.y.z` semver format
* Position format: `'XY'` | `'XYZ'`
* Filter dialect: `'cql'` | `'gml'`
### validateSchema [#validateschema]
```typescript
function validateSchema(schema: z.ZodType): (data: unknown) => T
```
Curried validation function for any Zod schema with consistent error handling.
**Type Parameters:**
* `T` - The expected output type after successful validation
**Parameters:**
* `schema` - Zod schema to validate against
**Returns:** Function that accepts data and returns validated result
**Throws:** Error with formatted path and message details
Provides consistent error formatting across all validation operations. Error messages include full property paths for easy debugging.
### validateDatasetConfig [#validatedatasetconfig]
```typescript
function validateDatasetConfig(data: unknown): AnyDataset
```
Pre-configured validator for dataset configurations. Convenience export that pre-applies `anyDatasetSchema` to the `validateSchema` function.
**Parameters:**
* `data` - Raw dataset configuration to validate
**Returns:** Validated `AnyDataset` object
**Throws:** Error with formatted validation errors
## Examples [#examples]
### Example: Validating dataset from API response [#example-validating-dataset-from-api-response]
```typescript
import { validateDatasetConfig } from '@accelint/dataset';
async function fetchDataset(id: string) {
const response = await fetch(`/api/datasets/${id}`);
const rawData = await response.json();
try {
const dataset = validateDatasetConfig(rawData);
return { success: true, dataset };
} catch (error) {
console.error('Invalid dataset:', error.message);
return { success: false, error: error.message };
}
}
```
### Example: Validating user-uploaded configuration [#example-validating-user-uploaded-configuration]
```typescript
import { validateDatasetConfig } from '@accelint/dataset';
function handleFileUpload(file: File) {
const reader = new FileReader();
reader.onload = (e) => {
try {
const rawConfig = JSON.parse(e.target?.result as string);
const validDataset = validateDatasetConfig(rawConfig);
console.log('Valid dataset:', validDataset.name);
saveDataset(validDataset);
} catch (error) {
showError(`Invalid configuration: ${error.message}`);
}
};
reader.readAsText(file);
}
```
### Example: Creating reusable validators [#example-creating-reusable-validators]
```typescript
import { validateSchema } from '@accelint/dataset';
import { z } from 'zod';
// Define custom schemas
const userSchema = z.object({
name: z.string(),
age: z.number(),
email: z.string().email(),
});
const configSchema = z.object({
apiKey: z.string(),
timeout: z.number().min(1000),
retries: z.number().max(5),
});
// Create validators
const validateUser = validateSchema(userSchema);
const validateConfig = validateSchema(configSchema);
// Use validators multiple times
const user1 = validateUser(rawUserData1);
const user2 = validateUser(rawUserData2);
const config = validateConfig(rawConfigData);
```
### Example: Handling validation errors gracefully [#example-handling-validation-errors-gracefully]
```typescript
import { validateDatasetConfig } from '@accelint/dataset';
function processDatasets(rawDatasets: unknown[]) {
const results = rawDatasets.map((raw, index) => {
try {
const dataset = validateDatasetConfig(raw);
return { index, status: 'valid', dataset };
} catch (error) {
return {
index,
status: 'invalid',
errors: error.message.split('\n').filter(Boolean),
};
}
});
const valid = results.filter(r => r.status === 'valid');
const invalid = results.filter(r => r.status === 'invalid');
console.log(`Validated ${valid.length} datasets`);
console.log(`Rejected ${invalid.length} datasets`);
return { valid, invalid };
}
```
### Example: Validating partial updates [#example-validating-partial-updates]
```typescript
import { validateSchema } from '@accelint/dataset';
import { z } from 'zod';
import { anyDatasetSchema } from '@accelint/dataset';
// Create schema for partial updates
const datasetUpdateSchema = anyDatasetSchema.partial();
const validateUpdate = validateSchema(datasetUpdateSchema);
function updateDataset(existingDataset: AnyDataset, updates: unknown) {
// Validate the updates
const validUpdates = validateUpdate(updates);
// Merge with existing dataset
const updated = { ...existingDataset, ...validUpdates };
// Validate complete dataset
return validateDatasetConfig(updated);
}
```
### Example: Custom validation with refinements [#example-custom-validation-with-refinements]
```typescript
import { validateSchema } from '@accelint/dataset';
import { z } from 'zod';
const datasetWithBusinessRules = z.object({
id: z.string(),
name: z.string().min(3, 'Name must be at least 3 characters'),
visible: z.boolean(),
metadata: z.object({
table: z.string(),
geometryProperty: z.string(),
defaultFields: z.array(z.string()).min(1, 'At least one field required'),
}),
}).refine(
(data) => {
// Business rule: geometry property must be in default fields
return data.metadata.defaultFields.includes(data.metadata.geometryProperty);
},
{
message: 'geometryProperty must be included in defaultFields',
path: ['metadata', 'geometryProperty'],
}
);
const validateWithRules = validateSchema(datasetWithBusinessRules);
```
### Example: Batch validation with error collection [#example-batch-validation-with-error-collection]
```typescript
import { validateDatasetConfig } from '@accelint/dataset';
function validateBatch(rawDatasets: unknown[]) {
const errors: Array<{ index: number; id: string; errors: string[] }> = [];
const validated: AnyDataset[] = [];
for (const [index, raw] of rawDatasets.entries()) {
try {
const dataset = validateDatasetConfig(raw);
validated.push(dataset);
} catch (error) {
errors.push({
index,
id: (raw as any)?.id || 'unknown',
errors: error.message
.split('\n')
.filter((line: string) => line.trim()),
});
}
}
return {
validated,
errors,
summary: {
total: rawDatasets.length,
valid: validated.length,
invalid: errors.length,
},
};
}
```
> **Good to know:** The validation functions throw errors on invalid data. Always wrap validation calls in try-catch blocks when handling user input or API responses. Error messages include full property paths (e.g., `metadata.serviceVersion: Invalid version: must be x.y.z`) for precise debugging.
## Related [#related]
* [types/datasets](./types/datasets.mdx) - Dataset type definitions
* [lenses](./lenses.mdx) - Lens-based property accessors
* [Zod Documentation](https://zod.dev/) - Schema validation library
# Overview (/docs/packages/design-foundation)
## Installation [#installation]
```bash
pnpm add @accelint/design-foundation
```
## Usage [#usage]
```typescript
// Import design tokens
import { tokens } from '@accelint/design-foundation/tokens';
// Import CSS utilities
import { css } from '@accelint/design-foundation/lib/css';
import { utils } from '@accelint/design-foundation/lib/utils';
```
```css
/* Import styles */
@import '@accelint/design-foundation/styles';
```
## Available Exports [#available-exports]
| Export Path | Description |
| --------------------------- | ------------------------------------------------------------------------------------------- |
| [tokens](./tokens/index.md) | Complete design token system including colors, typography, spacing, shadows, and animations |
| [lib/css](./lib/css.md) | CSS utilities and helpers |
| [lib/utils](./lib/utils.md) | JavaScript utility functions for design tokens |
| styles | Core CSS styles and variables |
## Related [#related]
* [@accelint/design-toolkit](../../toolkits/design-toolkit/index.md) - React component library
* [GitHub Repository](https://github.com/gohypergiant/standard-toolkit) - Source code
# designTokens (/docs/packages/design-foundation/tokens)
Complete design token system providing colors, typography, spacing, radius, shadows, and animations as deck.gl-compatible RGBA tuples and numeric values.
## Usage [#usage]
```typescript
import { designTokens } from '@accelint/design-foundation/tokens';
import { ScatterplotLayer } from '@deck.gl/layers';
// Use semantic tokens for themed colors
const layer = new ScatterplotLayer({
id: 'points',
data,
// Colors in deck.gl RGBA format: [R, G, B, A] all 0-255
getFillColor: designTokens.dark.bg.accent.primary.bold,
// [0, 79, 126, 255]
});
// Access primitive colors
const brandColor = designTokens.primitive.accent.primary['700'];
// [0, 79, 126, 255]
// Use spacing and typography tokens
const padding = designTokens.spacing.m; // 12
const fontSize = designTokens.typography.size.body.m; // 14
```
## Reference [#reference]
```typescript
const designTokens: ThemeTokens
```
Frozen object containing the complete design token system. All color values use deck.gl RGBA format with alpha channel 0-255.
### Token Structure [#token-structure]
**Theme Tokens** (`dark`, `light`):
* `bg` - Background colors (surface, interactive, accent, utility states)
* `fg` - Foreground/text colors (primary, inverse, accent, utility states)
* `outline` - Border and outline colors (static, interactive, accent, utility states)
* `shadow` - Box shadow definitions (elevation.raised, elevation.overlay)
**Primitive Tokens** (`primitive`):
* `neutral` - Grayscale palette (`'50'` through `'950'`)
* `alpha` - Transparent black/white overlays (`'100'` through `'500'`)
* `accent` - Brand colors (primary, secondary, tertiary)
* `utility` - Semantic colors (info, advisory, normal, serious, critical)
* `on` - Colors for text on colored backgrounds
**Domain Tokens** (`domain`):
* `classification` - Security classification colors
* `roe` - Rules of engagement status colors
**Typography Tokens** (`typography`):
* `height` - Line heights for header/body/button (xxl, xl, l, m, s, xs, xxs)
* `size` - Font sizes for header/body/button
* `spacing` - Letter spacing for header/body/button
* `weight` - Font weights for header/body/button
**Spacing Tokens** (`spacing`):
* Standard spacing scale: `'0'`, `base`, `none`, `xxs`, `xs`, `s`, `m`, `l`, `xl`, `xxl`, `oversized`
**Radius Tokens** (`radius`):
* Border radius values: `none`, `small`, `medium`, `large`, `round`
**Shadow Tokens** (`shadow`):
* Elevation shadows: `elevation.default`, `elevation.overlay.bold/muted`, `elevation.raised.bold/muted`
**Animation Tokens** (`animation`):
* `duration` - Timing values: `instant`, `fast`, `normal`, `slow`
* `easing` - Cubic bezier curves: `standard`, `decelerate`, `accelerate`
### Color Format [#color-format]
All colors use **deck.gl RGBA format**: `[R, G, B, A]` where all channels are 0-255.
This differs from CSS rgba where alpha is 0-1. For CSS usage, import the generated CSS variables instead (see Related section).
> **Good to know:** The design token system ensures consistency between CSS and JavaScript. All tokens are generated from a single source of truth in `primitive.json` and `semantic.json`. When importing `designTokens` directly, you must specify the theme (`dark` or `light`) explicitly. For React components that need theme-aware tokens, use the `useTheme()` hook from `@accelint/design-foundation` instead.
## Examples [#examples]
### Example: Using semantic colors in deck.gl [#example-using-semantic-colors-in-deckgl]
```typescript
import { designTokens } from '@accelint/design-foundation/tokens';
import { ScatterplotLayer } from '@deck.gl/layers';
const layer = new ScatterplotLayer({
id: 'status-points',
data: statusData,
getFillColor: (d) => {
switch (d.status) {
case 'normal':
return designTokens.dark.bg.normal.bold;
case 'warning':
return designTokens.dark.bg.serious.bold;
case 'critical':
return designTokens.dark.bg.critical.bold;
default:
return designTokens.dark.bg.info.bold;
}
},
getLineColor: designTokens.dark.outline.static,
radiusScale: designTokens.spacing.s,
});
```
### Example: Themed color palette selection [#example-themed-color-palette-selection]
```typescript
import { designTokens } from '@accelint/design-foundation/tokens';
function getThemeColors(theme: 'dark' | 'light') {
const tokens = designTokens[theme];
return {
background: tokens.bg.surface.default,
foreground: tokens.fg.primary.bold,
accent: tokens.bg.accent.primary.bold,
border: tokens.outline.static,
};
}
// Dark theme
const darkColors = getThemeColors('dark');
// {
// background: [21, 21, 23, 255],
// foreground: [255, 255, 255, 255],
// accent: [0, 79, 126, 255],
// border: [65, 66, 69, 255],
// }
```
### Example: Using primitive colors for data visualization [#example-using-primitive-colors-for-data-visualization]
```typescript
import { designTokens } from '@accelint/design-foundation/tokens';
// Create a categorical color scale
const categoryColors = [
designTokens.primitive.accent.primary['500'],
designTokens.primitive.accent.secondary['500'],
designTokens.primitive.accent.tertiary['500'],
designTokens.primitive.utility.advisory['500'],
designTokens.primitive.utility.normal['500'],
];
// Use in chart
const chartData = categories.map((category, index) => ({
category,
color: categoryColors[index % categoryColors.length],
}));
```
### Example: Domain-specific colors [#example-domain-specific-colors]
```typescript
import { designTokens } from '@accelint/design-foundation/tokens';
function getClassificationColor(level: string) {
const colors = designTokens.domain.classification;
switch (level.toUpperCase()) {
case 'UNCLASS':
return colors.unclass;
case 'CUI':
return colors.cui;
case 'CONFIDENTIAL':
return colors.confidential;
case 'SECRET':
return colors.secret;
case 'TOP SECRET':
return colors['top-secret'];
case 'TS/SCI':
return colors['ts-sci'];
default:
return colors.missing;
}
}
// ROE status colors
function getRoeColor(status: string) {
const colors = designTokens.domain.roe;
const statusMap = {
pending: colors.pending,
friend: colors.friend,
'assumed-friend': colors['assumed-friend'],
neutral: colors.neutral,
unknown: colors.unknown,
suspect: colors.suspect,
hostile: colors.hostile,
};
return statusMap[status] || colors['no-statement'];
}
```
### Example: Typography scale [#example-typography-scale]
```typescript
import { designTokens } from '@accelint/design-foundation/tokens';
const typography = designTokens.typography;
// Generate text style objects
const headerStyles = {
xxl: {
fontSize: typography.size.header.xxl, // 32
lineHeight: typography.height.header.xxl, // 40
fontWeight: typography.weight.header.xxl, // 500
letterSpacing: typography.spacing.header.xxl, // 0
},
xl: {
fontSize: typography.size.header.xl,
lineHeight: typography.height.header.xl,
fontWeight: typography.weight.header.xl,
letterSpacing: typography.spacing.header.xl,
},
// ... more sizes
};
// Use in canvas rendering
function drawText(ctx: CanvasRenderingContext2D, text: string, size: 'xxl' | 'xl' | 'l') {
const style = headerStyles[size];
ctx.font = `${style.fontWeight} ${style.fontSize}px Roboto Flex`;
ctx.letterSpacing = `${style.letterSpacing}px`;
ctx.fillText(text, 0, 0);
}
```
### Example: Spacing and layout [#example-spacing-and-layout]
```typescript
import { designTokens } from '@accelint/design-foundation/tokens';
const spacing = designTokens.spacing;
// Create a layout grid
const layoutConfig = {
padding: spacing.l, // 16
gap: spacing.m, // 12
margin: spacing.xl, // 24
buttonSpacing: spacing.s, // 8
};
// Use in WebGL/Canvas positioning
function positionElements(elements: Element[]) {
let y = layoutConfig.margin;
for (const element of elements) {
element.y = y;
y += element.height + layoutConfig.gap;
}
}
```
### Example: Border radius for shapes [#example-border-radius-for-shapes]
```typescript
import { designTokens } from '@accelint/design-foundation/tokens';
const radius = designTokens.radius;
// Use in canvas drawing
function drawRoundedRect(
ctx: CanvasRenderingContext2D,
x: number,
y: number,
width: number,
height: number,
cornerRadius: 'small' | 'medium' | 'large' | 'round'
) {
const r = radius[cornerRadius];
ctx.beginPath();
ctx.moveTo(x + r, y);
ctx.lineTo(x + width - r, y);
ctx.arcTo(x + width, y, x + width, y + r, r);
ctx.lineTo(x + width, y + height - r);
ctx.arcTo(x + width, y + height, x + width - r, y + height, r);
ctx.lineTo(x + r, y + height);
ctx.arcTo(x, y + height, x, y + height - r, r);
ctx.lineTo(x, y + r);
ctx.arcTo(x, y, x + r, y, r);
ctx.closePath();
}
```
### Example: Animation timing [#example-animation-timing]
```typescript
import { designTokens } from '@accelint/design-foundation/tokens';
const animation = designTokens.animation;
// Use in GSAP or custom animation
function animateElement(element: HTMLElement) {
element.style.transition = `all ${animation.duration.normal} ${animation.easing.standard}`;
}
// Keyframe timing
const keyframes = {
fast: parseInt(animation.duration.fast), // 80ms
normal: parseInt(animation.duration.normal), // 160ms
slow: parseInt(animation.duration.slow), // 320ms
};
// Easing curves for canvas animations
const easingFunctions = {
standard: parseEasing(animation.easing.standard),
decelerate: parseEasing(animation.easing.decelerate),
accelerate: parseEasing(animation.easing.accelerate),
};
```
## Related [#related]
* [ThemeTokens](../types/index.md) - TypeScript type definitions for design tokens
* [Design Tokens README](https://github.com/gohypergiant/standard-toolkit/blob/main/packages/design-foundation/src/tokens/README.md) - Token generation system documentation
* [useTheme hook](../../design-toolkit/hooks/use-theme/index.md) - React hook for theme-aware tokens
* [tokens.css](https://github.com/gohypergiant/standard-toolkit/blob/main/packages/design-foundation/src/tokens/tokens.css) - Generated CSS variables for CSS-based styling
* [deck.gl Color Format](https://deck.gl/docs/developer-guide/using-layers#colors) - deck.gl RGBA format documentation
# clsx (/docs/packages/design-foundation/utils)
## Usage [#usage]
```typescript
import { clsx } from '@accelint/design-foundation/lib/utils';
// Basic usage
const className = clsx('btn', 'btn-primary');
// 'btn btn-primary'
// Conditional classes
const className = clsx('btn', isActive && 'btn-active');
// 'btn btn-active' (if isActive is true)
// 'btn' (if isActive is false)
// Object syntax
const className = clsx({
'btn': true,
'btn-active': isActive,
'btn-disabled': isDisabled,
});
```
## Reference [#reference]
```typescript
const clsx: (...inputs: ClassValue[]) => string
```
Re-export of the `clsx` utility from the `clsx` package. Provides a standard interface for conditionally joining class names.
### Parameters [#parameters]
| Parameter | Type | Description |
| ----------- | -------------- | ------------------------------------------------------------------------------ |
| `...inputs` | `ClassValue[]` | Any number of class values: strings, numbers, objects, arrays, or falsy values |
### Returns [#returns]
Returns a single string with all valid class names joined by spaces. Falsy values are filtered out.
### Supported Input Types [#supported-input-types]
* **String**: `'btn btn-primary'`
* **Number**: `1` (converted to `'1'`)
* **Object**: `{ 'btn-active': true, 'btn-disabled': false }` (only keys with truthy values included)
* **Array**: `['btn', { 'btn-active': isActive }]` (recursively flattened)
* **Falsy values**: `null`, `undefined`, `false`, `''`, `0` (filtered out)
> **Good to know:** This is a re-export from the `clsx` package maintained as a stable entrypoint. If internal behavior needs customization in the future, it can be modified here without changing the import path.
## Examples [#examples]
### Example: Conditional styling with boolean flags [#example-conditional-styling-with-boolean-flags]
```typescript
import { clsx } from '@accelint/design-foundation/lib/utils';
function Button({ primary, disabled, children }) {
return (
);
}
```
### Example: Object syntax for state classes [#example-object-syntax-for-state-classes]
```typescript
import { clsx } from '@accelint/design-foundation/lib/utils';
function Card({ isActive, isHovered, isDisabled }) {
return (
);
}
```
### Example: Combining with Tailwind utility classes [#example-combining-with-tailwind-utility-classes]
```typescript
import { clsx } from '@accelint/design-foundation/lib/utils';
function Alert({ variant, fullWidth, className }) {
return (
);
}
```
### Example: Nested arrays and complex conditions [#example-nested-arrays-and-complex-conditions]
```typescript
import { clsx } from '@accelint/design-foundation/lib/utils';
function Menu({ items, activeId }) {
return (
{items.map(item => (
{item.label}
))}
);
}
```
### Example: Dynamic component variants [#example-dynamic-component-variants]
```typescript
import { clsx } from '@accelint/design-foundation/lib/utils';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonVariant = 'primary' | 'secondary' | 'outline';
function Button({
size = 'md',
variant = 'primary',
disabled = false,
children
}: {
size?: ButtonSize;
variant?: ButtonVariant;
disabled?: boolean;
children: React.ReactNode;
}) {
return (
);
}
```
### Example: Filtering out falsy values [#example-filtering-out-falsy-values]
```typescript
import { clsx } from '@accelint/design-foundation/lib/utils';
const className = clsx(
'btn',
null, // filtered out
undefined, // filtered out
false, // filtered out
'', // filtered out
0, // filtered out
'btn-primary', // kept
);
// Result: 'btn btn-primary'
```
## Related [#related]
* [clsx package](https://github.com/lukeed/clsx) - Original package documentation
* [classnames](https://github.com/JedWatson/classnames) - Alternative library with similar API
* [Tailwind CSS](https://tailwindcss.com/) - CSS framework commonly used with clsx
# formatBearing & formatDistance (/docs/packages/formatters/bearing)
## Usage [#usage]
```typescript
import { formatBearing, formatDistance } from '@accelint/formatters/bearing';
// Bearing: wrapped into 0–360, rounded to a whole degree, zero-padded
formatBearing(45); // "045°"
formatBearing(-10); // "350°"
formatBearing(359.6); // "000°"
// Distance: meters in, one decimal place and a unit symbol out
formatDistance(42300, 'kilometers'); // "42.3 km"
formatDistance(42300, ['kilometers', 'nauticalmiles']); // "42.3 km / 22.8 NM"
```
Both functions are pure. Conversion factors come from `METERS_PER_UNIT` and symbols from `DISTANCE_UNIT_SYMBOLS`, both in `@accelint/constants/units`.
## formatBearing [#formatbearing]
Format a bearing in degrees as a zero-padded 3-digit string with a trailing degree symbol. Uses true north reference per NTDS/C2 tactical display conventions.
### Reference [#reference]
```typescript
function formatBearing(degrees: number): string
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------- | ------------------------------------------------------------ |
| `degrees` | `number` | The bearing in degrees. May be negative or greater than 360. |
#### Returns [#returns]
A zero-padded 3-digit string with a trailing degree symbol, e.g. `"045°"`. The value is rounded to the nearest whole degree and wrapped into the `0–360` range, so the output is always `"000°"` through `"359°"`.
#### Throws [#throws]
* `RangeError` - `degrees must be a finite number.` when `degrees` is `NaN`, `Infinity`, or `-Infinity`.
### Examples [#examples]
#### Example: Formatting whole-degree bearings [#example-formatting-whole-degree-bearings]
```typescript
import { formatBearing } from '@accelint/formatters/bearing';
formatBearing(45); // "045°"
formatBearing(0); // "000°"
formatBearing(180); // "180°"
```
#### Example: Wrapping out-of-range bearings [#example-wrapping-out-of-range-bearings]
```typescript
import { formatBearing } from '@accelint/formatters/bearing';
formatBearing(-10); // "350°"
formatBearing(370); // "010°"
formatBearing(360); // "000°"
formatBearing(-360); // "000°"
```
#### Example: Rounding fractional bearings [#example-rounding-fractional-bearings]
```typescript
import { formatBearing } from '@accelint/formatters/bearing';
formatBearing(44.5); // "045°"
formatBearing(0.4); // "000°"
formatBearing(-0.4); // "000°"
formatBearing(359.6); // "000°" (rounds to 360, then wraps)
```
#### Example: Rejecting non-finite input [#example-rejecting-non-finite-input]
```typescript
import { formatBearing } from '@accelint/formatters/bearing';
formatBearing(Number.NaN); // RangeError: degrees must be a finite number.
formatBearing(Number.POSITIVE_INFINITY); // RangeError: degrees must be a finite number.
```
> **Good to know:** Rounding happens before wrapping, so a bearing that rounds up to exactly 360 renders as `"000°"`. Bearings 360 degrees apart always produce the same string.
## formatDistance [#formatdistance]
Format a distance in meters as a string with one decimal place and a unit symbol. Pass a single `DistanceUnit` or an array of one or two units; two units are joined with `" / "`.
Supported units: `kilometers`, `meters`, `nauticalmiles`, `miles`, `feet`.
### Reference [#reference-1]
```typescript
function formatDistance(
meters: number,
units: DistanceUnit | DistanceUnit[],
): string
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | -------------------------------- | ------------------------------------------------------------------------- |
| `meters` | `number` | The distance in meters. |
| `units` | `DistanceUnit \| DistanceUnit[]` | A single `DistanceUnit`, or an array of one or two `DistanceUnit` values. |
#### Returns [#returns-1]
A formatted distance string with unit symbol(s). Each value is `meters / METERS_PER_UNIT[unit]`, rounded to one decimal place and followed by `DISTANCE_UNIT_SYMBOLS[unit]`. A single-element array formats the same as a bare unit.
#### Throws [#throws-1]
* `RangeError` - `meters must be a finite number.` when `meters` is `NaN`, `Infinity`, or `-Infinity`.
* `Error` - `formatDistance accepts 1 or 2 units.` when `units` is an empty array or has more than two entries.
* `Error` - `Unsupported distance unit: ` when a unit is not a key of `METERS_PER_UNIT`.
### Examples [#examples-1]
#### Example: Formatting a single unit [#example-formatting-a-single-unit]
```typescript
import { formatDistance } from '@accelint/formatters/bearing';
formatDistance(42300, 'kilometers'); // "42.3 km"
formatDistance(42336, 'nauticalmiles'); // "22.9 NM"
formatDistance(500, 'meters'); // "500.0 m"
formatDistance(1609.344, 'miles'); // "1.0 mi"
formatDistance(30.48, 'feet'); // "100.0 ft"
formatDistance(0, 'kilometers'); // "0.0 km"
```
#### Example: Formatting dual units for a range readout [#example-formatting-dual-units-for-a-range-readout]
```typescript
import { formatDistance } from '@accelint/formatters/bearing';
formatDistance(42300, ['kilometers', 'nauticalmiles']); // "42.3 km / 22.8 NM"
formatDistance(1609.344, ['miles', 'feet']); // "1.0 mi / 5280.0 ft"
formatDistance(0, ['kilometers', 'nauticalmiles']); // "0.0 km / 0.0 NM"
```
#### Example: Passing a single-element array [#example-passing-a-single-element-array]
```typescript
import { formatDistance } from '@accelint/formatters/bearing';
formatDistance(42300, ['kilometers']); // "42.3 km" (same as the bare unit)
```
#### Example: Combining with formatBearing for a bearing/range label [#example-combining-with-formatbearing-for-a-bearingrange-label]
```typescript
import { formatBearing, formatDistance } from '@accelint/formatters/bearing';
function formatBearingRange(degrees: number, meters: number): string {
return `${formatBearing(degrees)} ${formatDistance(meters, ['kilometers', 'nauticalmiles'])}`;
}
formatBearingRange(44.5, 42300); // "045° 42.3 km / 22.8 NM"
```
#### Example: Rejecting invalid input [#example-rejecting-invalid-input]
```typescript
import { formatDistance } from '@accelint/formatters/bearing';
formatDistance(42300, []); // Error: formatDistance accepts 1 or 2 units.
formatDistance(42300, ['kilometers', 'miles', 'feet']); // Error: formatDistance accepts 1 or 2 units.
formatDistance(Number.NaN, 'kilometers'); // RangeError: meters must be a finite number.
```
> **Good to know:** Output always has exactly one decimal place, even for whole numbers (`"1.0 mi"`, not `"1 mi"`). Symbols follow SI and ICAO/IMO conventions (`km`, `m`, `NM`, `mi`, `ft`).
## Related [#related]
* [IFF Formatters](./iff.md) - Format IFF transponder mode codes
* [Distances](../constants/units.md) - `DISTANCE_UNIT_SYMBOLS`, `METERS_PER_UNIT`, and `DistanceUnit` from `@accelint/constants/units`
* [round](../math/round.md) - Round to a fixed number of decimal places
# IFF Formatters (/docs/packages/formatters/iff)
## Usage [#usage]
```typescript
import { formatM1, formatM2, formatM3A, formatM4, formatM5 } from '@accelint/formatters/iff';
// Mode 1: 2-digit mission/type code
const m1 = formatM1(5); // '05'
const m1 = formatM1(); // '--'
// Mode 2: 4-digit unit code
const m2 = formatM2(123); // '0123'
const m2 = formatM2(); // '----'
// Mode 3A: 4-digit squawk code
const m3a = formatM3A(1200); // '1200'
const m3a = formatM3A(7700); // '7700' (emergency)
const m3a = formatM3A(); // '----'
// Mode 4: 4-digit encrypted challenge
const m4 = formatM4(123); // '0123'
// Mode 5: 4-digit cryptographic GPS position
const m5 = formatM5(7654); // '7654'
```
## formatM1 [#formatm1]
Format a 2-digit octal IFF Mode 1 code. Mode 1 identifies the aircraft's mission or type and is only used by military aircraft.
### Reference [#reference]
```typescript
function formatM1(value?: string | number): string
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ------------------------------- | ---------------------------------------------------------- |
| `value` | `string \| number \| undefined` | The IFF Mode 1 code to format. Accepts numbers or strings. |
#### Returns [#returns]
A 2-digit zero-padded string, or `'--'` if value is null/undefined/empty string.
### Examples [#examples]
#### Example: Formatting single-digit codes [#example-formatting-single-digit-codes]
```typescript
import { formatM1 } from '@accelint/formatters/iff';
const code = formatM1(5); // '05'
const code = formatM1('5'); // '05'
const code = formatM1(9); // '09'
```
#### Example: Formatting two-digit codes [#example-formatting-two-digit-codes]
```typescript
import { formatM1 } from '@accelint/formatters/iff';
const code = formatM1(42); // '42'
const code = formatM1(10); // '10'
```
#### Example: Handling missing values [#example-handling-missing-values]
```typescript
import { formatM1 } from '@accelint/formatters/iff';
const code = formatM1(); // '--'
const code = formatM1(undefined); // '--'
const code = formatM1(''); // '--'
```
> **Good to know:** Mode 1 is a 2-digit octal code (0-77). Values greater than 2 digits are not truncated—they will be returned as-is without validation. Zero values are treated as falsy and return the default value `'--'`.
## formatM2 [#formatm2]
Format a 4-digit octal IFF Mode 2 code. Mode 2 identifies the aircraft's unit code or tail number and is only used by military aircraft.
### Reference [#reference-1]
```typescript
function formatM2(value?: string | number): string
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | ------------------------------- | ---------------------------------------------------------- |
| `value` | `string \| number \| undefined` | The IFF Mode 2 code to format. Accepts numbers or strings. |
#### Returns [#returns-1]
A 4-digit zero-padded string, or `'----'` if value is null/undefined/empty string.
### Examples [#examples-1]
#### Example: Formatting unit codes [#example-formatting-unit-codes]
```typescript
import { formatM2 } from '@accelint/formatters/iff';
const code = formatM2(123); // '0123'
const code = formatM2('123'); // '0123'
const code = formatM2(7654); // '7654'
const code = formatM2(1); // '0001'
```
#### Example: Handling missing values [#example-handling-missing-values-1]
```typescript
import { formatM2 } from '@accelint/formatters/iff';
const code = formatM2(); // '----'
const code = formatM2(undefined); // '----'
const code = formatM2(''); // '----'
```
> **Good to know:** Mode 2 is a 4-digit octal code (0000-7777). Values greater than 4 digits are not truncated. Zero values are treated as falsy and return the default value `'----'`.
## formatM3A [#formatm3a]
Format a 4-digit octal IFF Mode 3A code (squawk code). Mode 3A identifies the aircraft and is used by both military and civilian aircraft. Air traffic controllers assign these codes.
### Reference [#reference-2]
```typescript
function formatM3A(value?: string | number): string
```
#### Parameters [#parameters-2]
| Parameter | Type | Description |
| --------- | ------------------------------- | ------------------------------------------------------------------ |
| `value` | `string \| number \| undefined` | The IFF Mode 3A squawk code to format. Accepts numbers or strings. |
#### Returns [#returns-2]
A 4-digit zero-padded string, or `'----'` if value is null/undefined/empty string.
### Examples [#examples-2]
#### Example: Standard squawk codes [#example-standard-squawk-codes]
```typescript
import { formatM3A } from '@accelint/formatters/iff';
const code = formatM3A(1200); // '1200' (VFR)
const code = formatM3A(1201); // '1201'
const code = formatM3A('1200'); // '1200'
```
#### Example: Emergency squawk codes [#example-emergency-squawk-codes]
```typescript
import { formatM3A } from '@accelint/formatters/iff';
const hijack = formatM3A(7500); // '7500' (hijack/unlawful interference)
const radio = formatM3A(7600); // '7600' (radio failure)
const emergency = formatM3A(7700); // '7700' (general emergency)
```
#### Example: Handling missing values [#example-handling-missing-values-2]
```typescript
import { formatM3A } from '@accelint/formatters/iff';
const code = formatM3A(); // '----'
const code = formatM3A(undefined); // '----'
const code = formatM3A(''); // '----'
```
> **Good to know:** Mode 3A is a 4-digit octal code (0000-7777). Common codes include 1200 (VFR in the US), 7500 (hijack), 7600 (radio failure), and 7700 (emergency). Zero values are treated as falsy and return the default value `'----'`.
## formatM4 [#formatm4]
Format a 4-digit IFF Mode 4 code. Mode 4 uses an encrypted challenge-response system to determine the delay. This mode is only used by military aircraft.
### Reference [#reference-3]
```typescript
function formatM4(value: string | number): string
```
#### Parameters [#parameters-3]
| Parameter | Type | Description |
| --------- | ------------------ | ---------------------------------------------------------- |
| `value` | `string \| number` | The IFF Mode 4 code to format. Accepts numbers or strings. |
#### Returns [#returns-3]
A 4-digit zero-padded string, or `'----'` if value is an empty string.
### Examples [#examples-3]
#### Example: Formatting Mode 4 codes [#example-formatting-mode-4-codes]
```typescript
import { formatM4 } from '@accelint/formatters/iff';
const code = formatM4(123); // '0123'
const code = formatM4('7654'); // '7654'
const code = formatM4(1); // '0001'
```
#### Example: Handling empty strings [#example-handling-empty-strings]
```typescript
import { formatM4 } from '@accelint/formatters/iff';
const code = formatM4(''); // '----'
```
> **Good to know:** Mode 4 format verification is pending (see source TODO). Unlike other modes, formatM4 requires a value parameter. Zero values are treated as falsy and return the default value `'----'`.
## formatM5 [#formatm5]
Format a 4-digit IFF Mode 5 code. Mode 5 is a cryptographically secured version of Mode S and ADS-B GPS position. This mode is only used by military aircraft.
### Reference [#reference-4]
```typescript
function formatM5(value: string | number): string
```
#### Parameters [#parameters-4]
| Parameter | Type | Description |
| --------- | ------------------ | ---------------------------------------------------------- |
| `value` | `string \| number` | The IFF Mode 5 code to format. Accepts numbers or strings. |
#### Returns [#returns-4]
A 4-digit zero-padded string, or `'----'` if value is an empty string.
### Examples [#examples-4]
#### Example: Formatting Mode 5 codes [#example-formatting-mode-5-codes]
```typescript
import { formatM5 } from '@accelint/formatters/iff';
const code = formatM5(123); // '0123'
const code = formatM5('7654'); // '7654'
const code = formatM5(1); // '0001'
```
#### Example: Handling empty strings [#example-handling-empty-strings-1]
```typescript
import { formatM5 } from '@accelint/formatters/iff';
const code = formatM5(''); // '----'
```
> **Good to know:** Mode 5 format verification is pending (see source TODO). Unlike other modes, formatM5 requires a value parameter. Zero values are treated as falsy and return the default value `'----'`.
## Related [#related]
* [formatM1](#formatm1) - Format 2-digit Mode 1 mission/type codes
* [formatM2](#formatm2) - Format 4-digit Mode 2 unit codes
* [formatM3A](#formatm3a) - Format 4-digit Mode 3A squawk codes
* [formatM4](#formatm4) - Format 4-digit Mode 4 encrypted codes
* [formatM5](#formatm5) - Format 4-digit Mode 5 cryptographic codes
# Overview (/docs/packages/formatters)
## Installation [#installation]
```bash
pnpm add @accelint/formatters
```
## Usage [#usage]
```typescript
// Import from root (all exports)
import { formatBearing, formatDistance, formatM3A } from '@accelint/formatters';
// Import from sub-modules
import { formatBearing, formatDistance } from '@accelint/formatters/bearing';
import { formatM1 } from '@accelint/formatters/iff';
```
## Available Exports [#available-exports]
| Export Path | Description |
| ----------------------- | ---------------------------------------------------------------------------------------------------- |
| [bearing](./bearing.md) | Format tactical bearing readouts as zero-padded degrees and distances in meters with SI unit symbols |
| [iff](./iff/index.md) | Format IFF (Identification Friend or Foe) transponder mode codes with proper zero-padding |
## Related [#related]
* [@accelint/converters](../converters/index.md) - Format conversion utilities
* [GitHub Repository](https://github.com/gohypergiant/standard-toolkit) - Source code
# Overview (/docs/packages/geo)
## Installation [#installation]
```bash
pnpm add @accelint/geo
```
## Usage [#usage]
```typescript
// Import coordinate utilities
import { createCoordinate, coordinateSystems } from '@accelint/geo';
// Import formatters and parsers
import { formatDecimalDegrees, parseDecimalDegrees } from '@accelint/geo';
import { parseMGRS, parseUTM } from '@accelint/geo';
// Import geodesy functions
import { bearing, distance, greatCirclePoints, midpoint } from '@accelint/geo/geodesy';
```
## Available Exports [#available-exports]
| Export Path | Description |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [coordinates/coordinate](./coordinates/coordinate.md) | Parse, validate, convert, and format geographic coordinates across multiple notation systems |
| [coordinates/latlon/decimal-degrees](./coordinates/latlon/decimal-degrees/) | Format and parse latitude/longitude in decimal degrees notation |
| [coordinates/latlon/degrees-decimal-minutes](./coordinates/latlon/degrees-decimal-minutes/) | Format and parse coordinates in degrees decimal minutes notation |
| [coordinates/latlon/degrees-minutes-seconds](./coordinates/latlon/degrees-minutes-seconds/) | Format and parse coordinates in degrees minutes seconds notation |
| [coordinates/mgrs/parser](./coordinates/mgrs/parser.md) | Parse Military Grid Reference System (MGRS) coordinate strings |
| [coordinates/utm/parser](./coordinates/utm/parser.md) | Parse Universal Transverse Mercator (UTM) coordinate strings |
| [geodesy](./geodesy/) | Great-circle bearing, distance, midpoint, and path sampling between two `[longitude, latitude]` points |
## Geodesy [#geodesy]
Compute great-circle relationships between two `[longitude, latitude]` points on a spherical Earth. All geodesy functions take `LonLatTuple` values (GeoJSON order), which is the reverse of the `[latitude, longitude]` order used by `createCoordinate`.
* [bearing](./geodesy/bearing.md) - Initial bearing in degrees clockwise from true north, `[0, 360)`
* [distance](./geodesy/distance.md) - Distance in meters
* [midpoint](./geodesy/midpoint.md) - Midpoint along the shortest great-circle path
* [greatCirclePoints](./geodesy/great-circle-points.md) - Evenly spaced vertices along the path, with unwrapped longitudes for drawing
* [toSphericalPoints](./geodesy/to-spherical-points.md) - Shared validation step that returns `LatLonSpherical` points
## Related [#related]
* [@accelint/constants](../constants/index.md) - Coordinate constants and defaults
* [@accelint/predicates](../predicates/index.md) - Coordinate validation predicates
* [GitHub Repository](https://github.com/gohypergiant/standard-toolkit) - Source code
# Overview (/docs/packages/hotkey-manager)
## Usage [#usage]
```typescript
import { registerHotkey, globalBind, Keycode } from '@accelint/hotkey-manager';
// Bind global listeners once
globalBind();
// Register a save hotkey (Cmd+S on Mac, Ctrl+S elsewhere)
const saveHotkey = registerHotkey({
key: {
code: Keycode.KeyS,
ctrl: true,
autoMacStyle: true,
},
onKeyUp: () => console.log('Save triggered'),
});
// Activate the hotkey
const unbind = saveHotkey.bind();
// Later, clean up
unbind();
```
## globalBind [#globalbind]
Binds keyboard event listeners to the global window object. Safe to call on the server (no-op if not in browser). Only binds once—subsequent calls are ignored until `globalUnbind` is called.
### Usage [#usage-1]
```typescript
import { globalBind } from '@accelint/hotkey-manager';
// Call once at application startup
globalBind();
```
### Reference [#reference]
```typescript
function globalBind(): void
```
Attaches `keydown` and `keyup` listeners to `window`. Tracks binding state internally to prevent duplicate listeners.
### Examples [#examples]
#### Example: Initialize in app entry point [#example-initialize-in-app-entry-point]
```typescript
import { globalBind } from '@accelint/hotkey-manager';
// In your main.ts or App.tsx
globalBind();
```
#### Example: Conditional binding in framework apps [#example-conditional-binding-in-framework-apps]
```typescript
import { globalBind } from '@accelint/hotkey-manager';
import { useEffect } from 'react';
function App() {
useEffect(() => {
globalBind();
}, []);
return
My App
;
}
```
> **Good to know:** `globalBind` is idempotent—calling it multiple times has no effect until `globalUnbind` is called. It's safe to call on the server; it will silently return.
## globalUnbind [#globalunbind]
Unbinds keyboard event listeners from the global window object. Safe to call on the server (no-op if not in browser).
### Usage [#usage-2]
```typescript
import { globalUnbind } from '@accelint/hotkey-manager';
// Remove global listeners
globalUnbind();
```
### Reference [#reference-1]
```typescript
function globalUnbind(): void
```
Removes `keydown` and `keyup` listeners from `window`. Only removes listeners if they were previously bound via `globalBind`.
### Examples [#examples-1]
#### Example: Cleanup on app unmount [#example-cleanup-on-app-unmount]
```typescript
import { globalBind, globalUnbind } from '@accelint/hotkey-manager';
import { useEffect } from 'react';
function App() {
useEffect(() => {
globalBind();
return () => globalUnbind();
}, []);
return
My App
;
}
```
#### Example: Toggle hotkeys on/off [#example-toggle-hotkeys-onoff]
```typescript
import { globalBind, globalUnbind } from '@accelint/hotkey-manager';
function enableHotkeys() {
globalBind();
}
function disableHotkeys() {
globalUnbind();
}
```
> **Good to know:** `globalUnbind` only removes listeners if `globalBind` was called first. It's safe to call multiple times.
## registerHotkey [#registerhotkey]
Registers a keyboard shortcut and returns a manager object to control its activation. Supports single keys, modifier combinations, and chord sequences.
### Usage [#usage-3]
```typescript
import { registerHotkey, Keycode } from '@accelint/hotkey-manager';
const saveHotkey = registerHotkey({
key: {
code: Keycode.KeyS,
meta: true,
},
onKeyUp: () => console.log('Saved'),
});
// Activate the hotkey
const unbind = saveHotkey.bind();
```
### Reference [#reference-2]
```typescript
function registerHotkey(options: HotkeyOptions): HotkeyManager
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | --------------- | --------------------------------------------------------------------- |
| `options` | `HotkeyOptions` | Hotkey configuration including key combination(s) and event handlers. |
#### `HotkeyOptions` [#hotkeyoptions]
```typescript
type HotkeyOptions = {
key: KeyOption | KeyOption[];
id?: string;
triggerOnInput?: boolean;
} & RequireAtLeastOne<{
onKeyDown?: HotkeyAction;
onKeyUp?: HotkeyAction;
}>;
```
| Property | Type | Default | Description |
| ---------------- | -------------------------- | -------------- | ---------------------------------------------------- |
| `key` | `KeyOption \| KeyOption[]` | - | Single key combination or array for chord sequences. |
| `id` | `string` | auto-generated | Optional unique identifier for the hotkey. |
| `triggerOnInput` | `boolean` | `false` | Whether to trigger when focused on input elements. |
| `onKeyDown` | `HotkeyAction` | - | Handler called on keydown. |
| `onKeyUp` | `HotkeyAction` | - | Handler called on keyup. |
At least one of `onKeyDown` or `onKeyUp` must be provided.
#### `KeyOption` [#keyoption]
```typescript
type KeyOption = {
code: Keycode;
ctrl?: boolean;
alt?: boolean;
shift?: boolean;
meta?: boolean;
autoMacStyle?: boolean;
};
```
| Property | Type | Default | Description |
| -------------- | --------- | ------- | --------------------------------------------- |
| `code` | `Keycode` | - | The primary key code (use `Keycode` enum). |
| `ctrl` | `boolean` | `false` | Require Control key. |
| `alt` | `boolean` | `false` | Require Alt/Option key. |
| `shift` | `boolean` | `false` | Require Shift key. |
| `meta` | `boolean` | `false` | Require Command (Mac) or Windows key. |
| `autoMacStyle` | `boolean` | `false` | On Mac, swap `ctrl` to `meta` and vice versa. |
### Returns [#returns]
Returns a `HotkeyManager` object:
```typescript
type HotkeyManager = {
id: HotkeyId;
config: HotkeyConfig;
bind(): CleanupFunction;
forceBind(): CleanupFunction;
forceUnbind(): void;
readonly isBound: boolean;
};
```
| Property | Description |
| --------------- | ------------------------------------------------------------------ |
| `id` | Unique identifier for the hotkey. |
| `config` | Full normalized configuration. |
| `bind()` | Activate with ref-counting. Returns cleanup function. |
| `forceBind()` | Force activation, ignoring ref-counting. Returns cleanup function. |
| `forceUnbind()` | Force deactivation, clearing all activations. |
| `isBound` | Whether the hotkey is currently active. |
### Examples [#examples-2]
#### Example: Basic keyboard shortcut [#example-basic-keyboard-shortcut]
```typescript
import { registerHotkey, Keycode } from '@accelint/hotkey-manager';
const escapeHotkey = registerHotkey({
key: { code: Keycode.Escape },
onKeyUp: () => closeModal(),
});
const unbind = escapeHotkey.bind();
```
#### Example: Modifier key combinations [#example-modifier-key-combinations]
```typescript
import { registerHotkey, Keycode } from '@accelint/hotkey-manager';
// Ctrl+Shift+P for command palette
const paletteHotkey = registerHotkey({
key: {
code: Keycode.KeyP,
ctrl: true,
shift: true,
},
onKeyUp: () => openCommandPalette(),
});
```
#### Example: Platform-aware shortcuts with autoMacStyle [#example-platform-aware-shortcuts-with-automacstyle]
```typescript
import { registerHotkey, Keycode } from '@accelint/hotkey-manager';
// Ctrl+S on Windows/Linux, Cmd+S on Mac
const saveHotkey = registerHotkey({
key: {
code: Keycode.KeyS,
ctrl: true,
autoMacStyle: true, // Swaps to Cmd on Mac
},
onKeyUp: () => save(),
});
```
#### Example: Chord sequences (multi-key combinations) [#example-chord-sequences-multi-key-combinations]
```typescript
import { registerHotkey, Keycode } from '@accelint/hotkey-manager';
// Vim-style "g d" (go to definition)
const gotoDefHotkey = registerHotkey({
key: [
{ code: Keycode.KeyG },
{ code: Keycode.KeyD },
],
onKeyUp: () => goToDefinition(),
});
```
#### Example: Ref-counted binding [#example-ref-counted-binding]
```typescript
import { registerHotkey, Keycode } from '@accelint/hotkey-manager';
const hotkey = registerHotkey({
key: { code: Keycode.KeyA },
onKeyUp: () => console.log('A pressed'),
});
// Multiple components can bind the same hotkey
const unbind1 = hotkey.bind();
const unbind2 = hotkey.bind();
// Hotkey remains active until all bindings are cleaned up
unbind1();
console.log(hotkey.isBound); // true
unbind2();
console.log(hotkey.isBound); // false
```
#### Example: Force binding and unbinding [#example-force-binding-and-unbinding]
```typescript
import { registerHotkey, Keycode } from '@accelint/hotkey-manager';
const hotkey = registerHotkey({
key: { code: Keycode.KeyB },
onKeyUp: () => console.log('B pressed'),
});
hotkey.bind();
hotkey.bind();
console.log(hotkey.isBound); // true
// Force unbind clears all activations immediately
hotkey.forceUnbind();
console.log(hotkey.isBound); // false
```
#### Example: Trigger on input fields [#example-trigger-on-input-fields]
```typescript
import { registerHotkey, Keycode } from '@accelint/hotkey-manager';
// Escape works even when focused on input
const cancelHotkey = registerHotkey({
key: { code: Keycode.Escape },
triggerOnInput: true,
onKeyUp: () => cancelForm(),
});
```
#### Example: Both keydown and keyup handlers [#example-both-keydown-and-keyup-handlers]
```typescript
import { registerHotkey, Keycode } from '@accelint/hotkey-manager';
const spaceHotkey = registerHotkey({
key: { code: Keycode.Space },
onKeyDown: () => console.log('Space pressed'),
onKeyUp: () => console.log('Space released'),
});
```
> **Good to know:** Hotkeys are registered globally but only active when bound. Use `bind()` for ref-counted activation suitable for component lifecycles, or `forceBind()` for imperative control.
## unregisterHotkey [#unregisterhotkey]
Unregisters a hotkey, removing it from the internal registry. Accepts a hotkey ID, config, or manager object.
### Usage [#usage-4]
```typescript
import { registerHotkey, unregisterHotkey, Keycode } from '@accelint/hotkey-manager';
const hotkey = registerHotkey({
key: { code: Keycode.KeyA },
onKeyUp: () => console.log('A pressed'),
});
// Unregister by manager
unregisterHotkey(hotkey);
```
### Reference [#reference-3]
```typescript
function unregisterHotkey(id: HotkeyId): void
function unregisterHotkey(config: HotkeyConfig): void
function unregisterHotkey(manager: HotkeyManager): void
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | --------------- | ------------------------------------------------ |
| `id` | `HotkeyId` | The hotkey identifier string. |
| `config` | `HotkeyConfig` | The full hotkey configuration object. |
| `manager` | `HotkeyManager` | The hotkey manager returned by `registerHotkey`. |
### Examples [#examples-3]
#### Example: Unregister by manager [#example-unregister-by-manager]
```typescript
import { registerHotkey, unregisterHotkey, Keycode } from '@accelint/hotkey-manager';
const hotkey = registerHotkey({
key: { code: Keycode.KeyA },
onKeyUp: () => console.log('A pressed'),
});
unregisterHotkey(hotkey);
```
#### Example: Unregister by ID [#example-unregister-by-id]
```typescript
import { registerHotkey, unregisterHotkey, Keycode } from '@accelint/hotkey-manager';
const hotkey = registerHotkey({
id: 'my-custom-hotkey',
key: { code: Keycode.KeyA },
onKeyUp: () => console.log('A pressed'),
});
unregisterHotkey('my-custom-hotkey');
```
> **Good to know:** Unregistering a hotkey automatically unbinds it. Any existing cleanup functions will still work but will be no-ops.
## Keycode [#keycode]
Frozen object containing standard KeyboardEvent code values. Provides type-safe access to all keyboard codes.
### Usage [#usage-5]
```typescript
import { Keycode, registerHotkey } from '@accelint/hotkey-manager';
const hotkey = registerHotkey({
key: {
code: Keycode.KeyS,
meta: true,
},
onKeyUp: () => console.log('Save triggered'),
});
```
### Reference [#reference-4]
```typescript
const Keycode: {
readonly KeyA: 'KeyA';
readonly KeyB: 'KeyB';
// ... all keys
}
type Keycode = SafeEnum;
```
### Available Values [#available-values]
**Letter keys:** `KeyA` through `KeyZ`
**Number keys:** `Digit0` through `Digit9`
**Function keys:** `F1` through `F12`
**Arrow keys:** `ArrowLeft`, `ArrowRight`, `ArrowUp`, `ArrowDown`
**Modifier keys:**
* `ShiftLeft`, `ShiftRight`
* `ControlLeft`, `ControlRight`
* `AltLeft`, `AltRight`
* `MetaLeft`, `MetaRight`
**Navigation keys:** `Home`, `End`, `PageUp`, `PageDown`, `Insert`, `Delete`
**Special keys:** `Enter`, `Escape`, `Tab`, `Space`, `Backspace`, `Backquote`, `CapsLock`
**Punctuation:** `Slash`, `IntlBackslash`, `Equal`, `Minus`, `BracketLeft`, `BracketRight`, `Quote`, `Semicolon`
**Numpad keys:**
* `Numpad0` through `Numpad9`
* `NumpadAdd`, `NumpadSubtract`, `NumpadMultiply`, `NumpadDivide`
* `NumpadDecimal`, `NumpadEnter`, `NumpadEqual`, `NumpadComma`
* `NumLock`
**Media keys:** `AudioVolumeUp`, `AudioVolumeDown`, `AudioVolumeMute`
**International:** `IntlYen`, `IntlRo`
### Examples [#examples-4]
#### Example: Arrow key navigation [#example-arrow-key-navigation]
```typescript
import { Keycode, registerHotkey } from '@accelint/hotkey-manager';
const navigation = [
registerHotkey({
key: { code: Keycode.ArrowUp },
onKeyUp: () => moveFocusUp(),
}),
registerHotkey({
key: { code: Keycode.ArrowDown },
onKeyUp: () => moveFocusDown(),
}),
];
```
#### Example: Function keys [#example-function-keys]
```typescript
import { Keycode, registerHotkey } from '@accelint/hotkey-manager';
const f2Hotkey = registerHotkey({
key: { code: Keycode.F2 },
onKeyUp: () => startRename(),
});
```
> **Good to know:** These values match the standard [KeyboardEvent.code](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values) specification. Use `code` rather than `key` for reliable cross-keyboard layout detection.
## isMac [#ismac]
Boolean constant that is `true` when running client-side on macOS, `false` otherwise.
### Usage [#usage-6]
```typescript
import { isMac } from '@accelint/hotkey-manager';
if (isMac) {
console.log('Show ⌘ symbol');
} else {
console.log('Show Ctrl key');
}
```
### Reference [#reference-5]
```typescript
const isMac: boolean
```
Detects macOS by checking `window.navigator.userAgent` for "Mac". Returns `false` on the server.
### Examples [#examples-5]
#### Example: Platform-specific UI hints [#example-platform-specific-ui-hints]
```typescript
import { isMac } from '@accelint/hotkey-manager';
function ShortcutHint() {
return (
{isMac ? '⌘' : 'Ctrl'} + S to save
);
}
```
#### Example: Conditional hotkey registration [#example-conditional-hotkey-registration]
```typescript
import { isMac, registerHotkey, Keycode } from '@accelint/hotkey-manager';
const hotkey = registerHotkey({
key: {
code: Keycode.KeyS,
...(isMac ? { meta: true } : { ctrl: true }),
},
onKeyUp: () => save(),
});
```
> **Good to know:** Use `autoMacStyle: true` in your hotkey configuration for automatic platform handling instead of manually checking `isMac`.
## keyToId [#keytoid]
Converts a key combination to a standard internal identifier string. Handles `autoMacStyle` transformation on macOS.
### Usage [#usage-7]
```typescript
import { keyToId } from '@accelint/hotkey-manager';
const id = keyToId({
code: 'KeyS',
ctrl: true,
alt: false,
shift: false,
meta: false,
autoMacStyle: false,
id: '',
});
// "KeyS|no-alt|ctrl|no-meta|no-shift"
```
### Reference [#reference-6]
```typescript
function keyToId(key: KeyCombination): KeyCombinationId
```
#### Parameters [#parameters-2]
| Parameter | Type | Description |
| --------- | ---------------- | ---------------------------------------------------- |
| `key` | `KeyCombination` | Key combination object with code and modifier flags. |
### Returns [#returns-1]
Returns a pipe-delimited string identifier in the format:
`{code}|{alt}|{ctrl}|{meta}|{shift}`
### Examples [#examples-6]
#### Example: Generate key identifier [#example-generate-key-identifier]
```typescript
import { keyToId, Keycode } from '@accelint/hotkey-manager';
const id = keyToId({
code: Keycode.KeyA,
ctrl: true,
alt: false,
shift: true,
meta: false,
autoMacStyle: false,
id: '',
});
console.log(id); // "KeyA|no-alt|ctrl|no-meta|shift"
```
#### Example: Platform-aware ID with autoMacStyle [#example-platform-aware-id-with-automacstyle]
```typescript
import { keyToId, Keycode, isMac } from '@accelint/hotkey-manager';
const id = keyToId({
code: Keycode.KeyS,
ctrl: true,
alt: false,
shift: false,
meta: false,
autoMacStyle: true,
id: '',
});
// On Mac: "KeyS|no-alt|no-ctrl|meta|no-shift"
// On Windows/Linux: "KeyS|no-alt|ctrl|no-meta|no-shift"
```
> **Good to know:** This function is used internally by `registerHotkey`. You typically don't need to call it directly unless building custom hotkey abstractions.
## keyToString [#keytostring]
Converts a key combination to a human-readable string representation with modifier symbols.
### Usage [#usage-8]
```typescript
import { keyToString } from '@accelint/hotkey-manager';
const str = keyToString({
code: 'KeyS',
ctrl: false,
alt: false,
shift: false,
meta: true,
autoMacStyle: false,
id: '',
});
// "[Win/⌘] + [KeyS]"
```
### Reference [#reference-7]
```typescript
function keyToString(key: KeyCombination): string
```
#### Parameters [#parameters-3]
| Parameter | Type | Description |
| --------- | ---------------- | ---------------------------------------------------- |
| `key` | `KeyCombination` | Key combination object with code and modifier flags. |
### Returns [#returns-2]
Returns a human-readable string like `"[CTRL] + [SHIFT] + [KeyA]"`.
### Examples [#examples-7]
#### Example: Display hotkey hint [#example-display-hotkey-hint]
```typescript
import { keyToString, Keycode } from '@accelint/hotkey-manager';
const hotkey = {
code: Keycode.KeyS,
ctrl: true,
alt: false,
shift: true,
meta: false,
autoMacStyle: false,
id: '',
};
console.log(keyToString(hotkey));
// "[CTRL] + [SHIFT] + [KeyS]"
```
#### Example: Generate tooltip text [#example-generate-tooltip-text]
```typescript
import { keyToString, registerHotkey, Keycode } from '@accelint/hotkey-manager';
const saveHotkey = registerHotkey({
key: {
code: Keycode.KeyS,
ctrl: true,
},
onKeyUp: () => save(),
});
const tooltipText = `Save file: ${keyToString(saveHotkey.config.key[0])}`;
```
> **Good to know:** This function is primarily for debugging and user-facing displays. The output format is not customizable—it always uses the pattern `[MODIFIER] + [KEY]`.
## Related [#related]
* [useHotkey](./react/use-hotkey.md) - React hook for binding hotkeys in components
* [KeyboardEvent.code](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code) - MDN documentation for keyboard codes
# React Hooks (/docs/packages/hotkey-manager/react)
## Usage [#usage]
```tsx
import { registerHotkey, Keycode } from '@accelint/hotkey-manager';
import { useHotkey } from '@accelint/hotkey-manager/react';
const saveHotkey = registerHotkey({
key: { code: Keycode.KeyS, meta: true },
onKeyUp: () => console.log('Save triggered'),
});
function Editor() {
useHotkey(saveHotkey);
return ;
}
```
## useHotkey [#usehotkey]
Binds a hotkey manager when the component mounts and automatically unbinds when it unmounts.
### Reference [#reference]
```typescript
function useHotkey(manager: HotkeyManager): void
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | --------------- | ------------------------------------------------ |
| `manager` | `HotkeyManager` | The hotkey manager returned by `registerHotkey`. |
### Examples [#examples]
#### Example: Component-scoped hotkey [#example-component-scoped-hotkey]
```tsx
import { registerHotkey, Keycode } from '@accelint/hotkey-manager';
import { useHotkey } from '@accelint/hotkey-manager/react';
const escapeHotkey = registerHotkey({
key: { code: Keycode.Escape },
onKeyUp: () => console.log('Escape pressed'),
});
function Modal() {
useHotkey(escapeHotkey);
return
Press Escape to close
;
}
```
#### Example: Multiple hotkeys in one component [#example-multiple-hotkeys-in-one-component]
```tsx
import { registerHotkey, Keycode } from '@accelint/hotkey-manager';
import { useHotkey } from '@accelint/hotkey-manager/react';
const saveHotkey = registerHotkey({
key: { code: Keycode.KeyS, ctrl: true, autoMacStyle: true },
onKeyUp: () => save(),
});
const undoHotkey = registerHotkey({
key: { code: Keycode.KeyZ, ctrl: true, autoMacStyle: true },
onKeyUp: () => undo(),
});
function Editor() {
useHotkey(saveHotkey);
useHotkey(undoHotkey);
return ;
}
```
#### Example: Conditional hotkey binding [#example-conditional-hotkey-binding]
```tsx
import { registerHotkey, Keycode } from '@accelint/hotkey-manager';
import { useHotkey } from '@accelint/hotkey-manager/react';
import { useState } from 'react';
const submitHotkey = registerHotkey({
key: { code: Keycode.Enter, ctrl: true },
onKeyUp: () => submit(),
});
function Form() {
const [isEnabled, setIsEnabled] = useState(true);
// Only bind when enabled
if (isEnabled) {
useHotkey(submitHotkey);
}
return ;
}
```
> **Good to know:** The hotkey manager is automatically bound on mount and unbound on unmount. If the same manager is used in multiple components, ref-counting ensures it remains active until all components unmount.
#### Example: Dynamic hotkey creation [#example-dynamic-hotkey-creation]
```tsx
import { registerHotkey, Keycode } from '@accelint/hotkey-manager';
import { useHotkey } from '@accelint/hotkey-manager/react';
import { useMemo } from 'react';
function SearchModal({ onClose }: { onClose: () => void }) {
const closeHotkey = useMemo(
() =>
registerHotkey({
key: { code: Keycode.Escape },
onKeyUp: onClose,
}),
[onClose],
);
useHotkey(closeHotkey);
return
Search...
;
}
```
## createUseHotkey [#createusehotkey]
Creates a custom React hook from a HotkeyManager for module-level usage. Useful when you want to define the hotkey at module scope and use it as a reusable hook.
### Reference [#reference-1]
```typescript
function createUseHotkey(manager: HotkeyManager): () => void
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | --------------- | --------------------------- |
| `manager` | `HotkeyManager` | The hotkey manager to wrap. |
### Returns [#returns]
Returns a React hook function that binds the hotkey on mount.
### Examples [#examples-1]
#### Example: Module-level hotkey definition [#example-module-level-hotkey-definition]
```tsx
import { registerHotkey, Keycode } from '@accelint/hotkey-manager';
import { createUseHotkey } from '@accelint/hotkey-manager/react';
// Define at module scope
const helpHotkey = registerHotkey({
key: { code: Keycode.Slash, shift: true },
onKeyUp: () => openHelp(),
});
// Create a custom hook
const useHelpHotkey = createUseHotkey(helpHotkey);
// Use in any component
function App() {
useHelpHotkey();
return
Press ? for help
;
}
```
#### Example: Shared hotkey across components [#example-shared-hotkey-across-components]
```tsx
import { registerHotkey, Keycode } from '@accelint/hotkey-manager';
import { createUseHotkey } from '@accelint/hotkey-manager/react';
const paletteHotkey = registerHotkey({
key: { code: Keycode.KeyP, ctrl: true, shift: true },
onKeyUp: () => openCommandPalette(),
});
export const useCommandPalette = createUseHotkey(paletteHotkey);
// Use in multiple components
function Layout() {
useCommandPalette();
return
Layout
;
}
function Editor() {
useCommandPalette();
return ;
}
```
> **Good to know:** `createUseHotkey` is ideal for library authors distributing hotkey hooks. The manager is captured in a stable closure, eliminating the need to pass it through dependencies.
## Related [#related]
* [registerHotkey](../index.md#registerhotkey) - Register a keyboard shortcut
* [globalBind](../index.md#globalbind) - Bind global event listeners
* [HotkeyManager](../index.md#registerhotkey) - Type definition and API reference
# Overview (/docs/packages/icons)
## Usage [#usage]
```tsx
import { Add, Bell, Check } from '@accelint/icons';
export function MyComponent() {
return (
);
}
```
## Reference [#reference]
All icon components share the same API:
```typescript
interface SVGRProps {
title?: string;
titleId?: string;
}
type IconComponent = (
props: SVGProps & SVGRProps
) => JSX.Element;
```
### Props [#props]
| Prop | Type | Default | Required |
| ----------- | ------------------ | ------- | -------- |
| `width` | `number \| string` | - | No |
| `height` | `number \| string` | - | No |
| `className` | `string` | - | No |
| `style` | `CSSProperties` | - | No |
| `fill` | `string` | - | No |
| `title` | `string` | - | No |
| `titleId` | `string` | - | No |
All standard SVG element props are supported via `SVGProps`.
#### `title` [#title]
Provides accessible text description for screen readers. When provided, renders a `` element inside the SVG.
#### `titleId` [#titleid]
Custom ID for the title element. Used with `aria-labelledby` for accessibility. Auto-generated if `title` is provided without `titleId`.
### Icon Sizing [#icon-sizing]
Icons use `currentColor` for fill, inheriting text color from parent elements. Size should be controlled via `width` and `height` props or CSS.
## Available Icons [#available-icons]
### Navigation & Actions [#navigation--actions]
`Add`, `AddFill`, `AddToList`, `Remove`, `RemoveFill`, `RemoveFromList`, `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`, `Arrow`, `ArrowNortheast`, `ArrowNorthwest`, `ArrowSoutheast`, `ArrowSouthwest`, `ChevronUp`, `ChevronDown`, `ChevronLeft`, `ChevronRight`, `ChevronFillUp`, `ChevronFillDown`, `ChevronFillLeft`, `ChevronFillRight`, `Cancel`, `CancelFill`, `Check`, `Edit`, `Delete`, `Duplicate`, `Undo`, `Move`, `Expand`, `ExpandAll`, `ExpandLeft`, `ExpandRight`, `ExpandWindow`, `ExpandLeftPanel`, `Collapse`, `CollapseAll`, `CollapseWindow`, `Condense`
### Media Controls [#media-controls]
`Play`, `Pause`, `Stop`, `Record`, `FastForward`, `FastRewind`, `JumpTo`, `JumpToStart`, `JumpToEnd`, `Loop`, `Reverse`, `Playback`
### UI Elements [#ui-elements]
`Bell`, `Dashboard`, `Filter`, `Search`, `Settings`, `Help`, `Information`, `Hamburger`, `Kebab`, `Waffle`, `Grid`, `Calendar`, `Time`, `Timer`, `Plus`, `Minus`, `CopyToClipboard`, `PasteFromClipboard`, `Screenshot`, `AttachFile`, `Link`, `Share`, `GlobalShare`, `Flag`, `Pin`, `Note`, `Message`, `Phone`, `Label`, `Tag`
### Tools & Drawing [#tools--drawing]
`CircleTool`, `EllipseTool`, `LineTool`, `PolygonTool`, `RectangleTool`, `RectangleSelect`, `Lasso`, `PolygonLasso`, `ColorPicker`, `CursorDefault`, `CursorCrosshair`, `CursorDrag`, `DragHorz`, `DragVert`
### Status & Indicators [#status--indicators]
`Alert`, `AlertBase`, `Warning`, `Success`, `Problem`, `Hide`, `Show`, `Lock`, `LockFill`, `LockOutline`, `Live`, `Connection`, `ConnectionLost`, `BadData`, `NonEditable`, `None`, `Placeholder`
### Data & Visualization [#data--visualization]
`Data`, `ExploreData`, `InsertChart`, `ChartStackedBar`, `Gantt`, `Plots`, `Feed`, `Layers`, `LayerGroup`, `Overlays`, `Attributes`, `ArrangeTable`, `SelectionList`, `StackCards`, `Stack`, `Newspaper`, `TrackChanges`
### Geography & Mapping [#geography--mapping]
`Airport`, `MilitaryAirfield`, `Airspaces`, `Terrain`, `Weather`, `Wind`, `Radar`, `RadarSite`, `RadarAnomaly`, `Region`, `Sector`, `MapPin`, `Marker`, `LocationFill`, `LocationStroke`, `MercatorProjection`, `Coverage`, `CenterOn`, `ZoomIn`, `ZoomOut`, `ZoomTo`, `Focus`, `Spotlight`
### Military & Defense [#military--defense]
`Target`, `PresumedTarget`, `DefendedPointCaalDal`, `Missile`, `Missiles`, `ThreatAssess`, `BattleStation`, `WatchTower`, `CommonTrack`, `CommonAirTrack`, `CommonOperatingPic`, `AirTrackHistory`, `TrackHistory`, `TrackEta`, `TrackEtaEndpoint`, `FlightPlan`, `Mission`, `Assignment`, `Handover`, `Handshake`, `CreateCoa`, `CopSettings`, `InterceptPoint`, `Hold`, `Tether`
### Vehicles & Assets [#vehicles--assets]
`Car`, `Helicopter`, `Uas`, `UasHomePoint`, `LargeJet`, `SmallJet`, `Prop`, `CommercialShip`, `MilitaryVessel`, `PersonalBoat`, `Birds`, `Landmine`, `Skull`
### Infrastructure [#infrastructure]
`Building`, `Stadium`, `Artcc`, `ConnectingAirports`, `SensorHealth`, `UnscheduledMaintenance`, `ElectromagneticSpectrum`, `Radio`, `Remote`
### Interface Elements [#interface-elements]
`PanelOpen`, `PanelClosed`, `OpenContainer`, `FullScreen`, `PopOut`, `PopBackIn`, `Appearance`, `Brightness`, `Contrast`, `Mode`, `Keyboard`, `ArrowKeys`, `MouseLeftClick`, `MouseMiddleClick`, `MouseRightClick`, `MouseScroll`, `ScrollClick`
### User & Access [#user--access]
`Person`, `Login`, `Logout`, `Ticket`, `UserManual`, `WhatsNew`, `BugReport`
### Shapes & Geometry [#shapes--geometry]
`PointFill`, `PointOutline`, `SquareFill`, `SquareOutline`, `TriangleFill`, `TriangleOutline`, `CircleTool`, `Slash`, `Star`, `Wheel`
### Media & Audio [#media--audio]
`SoundAudible`, `SoundMute`, `Mute`, `Bolt`, `BoltNotVisible`
### Organization [#organization]
`Group`, `Land`, `Ascending`, `Descending`
### Other [#other]
`Import`, `Duplicate`, `Slash`, `None`
## Examples [#examples]
### Example: Basic icon usage [#example-basic-icon-usage]
```tsx
import { Add } from '@accelint/icons';
<Add width={24} height={24} />
```
### Example: Icon with color [#example-icon-with-color]
Icons inherit `currentColor` by default:
```tsx
import { Bell } from '@accelint/icons';
<div style={{ color: '#ff0000' }}>
<Bell width={24} height={24} />
</div>
```
Or override with className:
```tsx
import { Check } from '@accelint/icons';
<Check width={24} height={24} className="text-green-500" />
```
### Example: Icon with accessibility [#example-icon-with-accessibility]
```tsx
import { Settings } from '@accelint/icons';
<Settings
width={24}
height={24}
title="Open settings"
aria-label="Open settings"
/>
```
### Example: Icon in button [#example-icon-in-button]
```tsx
import { Add } from '@accelint/icons';
import { Button } from '@accelint/design-toolkit';
<Button>
<Add width={16} height={16} />
Add Item
</Button>
```
### Example: Icon with custom styling [#example-icon-with-custom-styling]
```tsx
import { Warning } from '@accelint/icons';
<Warning
width={32}
height={32}
style={{
fill: 'orange',
filter: 'drop-shadow(0 2px 4px rgba(0,0,0,0.1))'
}}
/>
```
### Example: Dynamic icon selection [#example-dynamic-icon-selection]
```tsx
import * as Icons from '@accelint/icons';
interface IconDisplayProps {
name: keyof typeof Icons;
size?: number;
}
export function IconDisplay({ name, size = 24 }: IconDisplayProps) {
const IconComponent = Icons[name];
return <IconComponent width={size} height={size} />;
}
// Usage
<IconDisplay name="Add" size={32} />
<IconDisplay name="Bell" size={24} />
```
### Example: Icon with responsive sizing [#example-icon-with-responsive-sizing]
```tsx
import { Dashboard } from '@accelint/icons';
<Dashboard
className="w-6 h-6 md:w-8 md:h-8"
style={{ width: '1.5rem', height: '1.5rem' }}
/>
```
### Example: Icon in design system [#example-icon-in-design-system]
```tsx
import { Icon } from '@accelint/design-toolkit';
import { Settings } from '@accelint/icons';
// Icon component automatically sizes based on context
<Icon>
<Settings />
</Icon>
```
> **Good to know:** All icons are 24×24 viewBox by default. When using with the design system's `Icon` component, size is controlled by context and you don't need to specify width/height.
## Related [#related]
* [Icon](../../toolkits/design-toolkit/components/icon/index.mdx) - Design system Icon component with automatic sizing
* [Button](../../toolkits/design-toolkit/components/button/index.mdx) - Button component that works with icons
# Log Level Constants (/docs/packages/logger/definitions)
## Usage [#usage]
```typescript
import { getLogger, DEBUG, INFO, WARN, ERROR } from '@accelint/logger';
// Use constants for type safety
const devLogger = getLogger({ enabled: true, level: DEBUG });
const prodLogger = getLogger({ enabled: true, level: WARN });
```
## Reference [#reference]
```typescript
const TRACE: LogLevelType = 'trace';
const DEBUG: LogLevelType = 'debug';
const INFO: LogLevelType = 'info';
const WARN: LogLevelType = 'warn';
const ERROR: LogLevelType = 'error';
const FATAL: LogLevelType = 'fatal';
type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
```
### Constants [#constants]
## TRACE [#trace]
Use for fine-grained debugging information, more verbose than debug.
```typescript
import { getLogger, TRACE } from '@accelint/logger';
const logger = getLogger({ level: TRACE, enabled: true });
logger.trace('Entering function', { args: [1, 2, 3] });
```
## DEBUG [#debug]
Use for detailed diagnostic information useful during development.
```typescript
import { getLogger, DEBUG } from '@accelint/logger';
const logger = getLogger({ level: DEBUG, enabled: true });
logger.debug('Cache miss', { key: 'user:123' });
```
## INFO [#info]
Use for general informational messages about application progress.
```typescript
import { getLogger, INFO } from '@accelint/logger';
const logger = getLogger({ level: INFO, enabled: true });
logger.info('Server started', { port: 3000 });
```
## WARN [#warn]
Use for potentially harmful situations that don't prevent execution.
```typescript
import { getLogger, WARN } from '@accelint/logger';
const logger = getLogger({ level: WARN, enabled: true });
logger.warn('API rate limit approaching', { remaining: 10 });
```
## ERROR [#error]
Use for critical errors that require immediate attention.
```typescript
import { getLogger, ERROR } from '@accelint/logger';
const logger = getLogger({ level: ERROR, enabled: true });
logger.error('Payment processing failed', { orderId: 'ord_123' });
```
## FATAL [#fatal]
Use for severe errors that may cause the application to terminate.
```typescript
import { getLogger, FATAL } from '@accelint/logger';
const logger = getLogger({ level: FATAL, enabled: true });
logger.fatal('Database connection lost', { error });
```
## LogLevel Type [#loglevel-type]
The `LogLevel` type represents all valid log level strings. Use this for type annotations when accepting log levels as parameters.
```typescript
import type { LogLevel } from '@accelint/logger';
function createLogger(level: LogLevel) {
return getLogger({ enabled: true, level });
}
createLogger('info'); // ✓ Valid
createLogger('verbose'); // ✗ Type error
```
## LoggerOptions Type [#loggeroptions-type]
Configuration options for the logger.
```typescript
type LoggerOptions = {
enabled: boolean;
level?: LogLevel;
env?: 'production' | 'development';
pretty?: boolean;
prefix?: string;
plugins?: LogLayerPlugin[];
transports?: LogLayerTransport[];
groups?: LogGroupsConfig;
}
```
### Properties [#properties]
| Property | Type | Default | Description |
| ------------ | ------------------------------- | --------------- | ------------------------------------------------------------ |
| `enabled` | `boolean` | Required | Whether logging is enabled; `false` makes all calls no-ops |
| `level` | `LogLevel` | `'debug'` | Minimum log level to output |
| `env` | `'production' \| 'development'` | `'development'` | Runtime environment; controls server detection |
| `pretty` | `boolean` | `true` | Use pretty console output; `false` emits structured JSON |
| `prefix` | `string` | `''` | String prepended to all log messages |
| `plugins` | `LogLayerPlugin[]` | `[]` | Additional plugins applied after the built-in ones |
| `transports` | `LogLayerTransport[]` | `[]` | Custom transports that replace the default console transport |
| `groups` | `LogGroupsConfig` | `{}` | Named group configuration for conditional group logging |
## Examples [#examples]
### Example: Log level hierarchy [#example-log-level-hierarchy]
```typescript
import { getLogger, WARN } from '@accelint/logger';
// Logger set to WARN level
const logger = getLogger({ enabled: true, level: WARN });
logger.trace('Not logged'); // Below threshold
logger.debug('Not logged'); // Below threshold
logger.info('Not logged'); // Below threshold
logger.warn('Logged'); // At threshold
logger.error('Logged'); // Above threshold
logger.fatal('Logged'); // Above threshold
```
### Example: Dynamic log level [#example-dynamic-log-level]
```typescript
import { getLogger, DEBUG, INFO, WARN, type LogLevel } from '@accelint/logger';
function getLogLevel(): LogLevel {
if (process.env.DEBUG === 'true') return DEBUG;
if (process.env.NODE_ENV === 'production') return WARN;
return INFO;
}
const logger = getLogger({
enabled: true,
level: getLogLevel(),
});
```
### Example: Type-safe logger configuration [#example-type-safe-logger-configuration]
```typescript
import type { LoggerOptions } from '@accelint/logger';
import { getLogger, WARN } from '@accelint/logger';
const config: LoggerOptions = {
enabled: process.env.LOGGING_ENABLED === 'true',
level: WARN,
env: process.env.NODE_ENV as 'production' | 'development',
prefix: '[API]',
};
const logger = getLogger(config);
```
> **Good to know:** Log levels are hierarchical. Setting the logger to a specific level enables that level and all higher (more severe) levels. For example, setting `level: WARN` will output warn, error, and fatal logs, but suppress trace, debug, and info logs.
## Related [#related]
* [getLogger](./default/index.md) - Singleton logger factory
* [bootstrap](./default/bootstrap.md) - Direct logger initialization
* [LogLayer Log Levels](https://loglayer.dev/logging-api/adjusting-log-levels.html) - Upstream documentation
# Overview (/docs/packages/logger)
## Usage [#usage]
```typescript
import { getLogger } from '@accelint/logger';
// Create a singleton logger instance
const logger = getLogger({
enabled: true,
env: process.env.NODE_ENV as 'production' | 'development',
level: 'info',
prefix: '[MyApp]',
});
logger.info('Application started');
logger.withMetadata({ userId: 123 }).warn('Token expiring soon');
```
## Exports [#exports]
### Functions [#functions]
* [getLogger](./default/index.md) - Returns a singleton LogLayer logger instance
* [bootstrap](./default/bootstrap.md) - Initializes a new LogLayer instance with default plugins
### Constants [#constants]
* [DEBUG](./definitions.md#debug) - Log level constant for debug messages
* [ERROR](./definitions.md#error) - Log level constant for error messages
* [FATAL](./definitions.md#fatal) - Log level constant for fatal error messages
* [INFO](./definitions.md#info) - Log level constant for informational messages
* [TRACE](./definitions.md#trace) - Log level constant for trace messages
* [WARN](./definitions.md#warn) - Log level constant for warning messages
### Plugins [#plugins]
* [callsitePlugin](./plugins/callsite.md) - Tracks and injects source code location into log data
* [environmentPlugin](./plugins/environment.md) - Injects environment context (server/browser) into log data
### Transports [#transports]
* [prettyTransport](./transports/pretty.md) - Pretty-printed console transport
* [structuredTransport](./transports/structured.md) - Structured JSON log transport
### Types [#types]
* `LogLevel` - The log level type: `'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'`
* `LoggerOptions` - Configuration options for the logger
* `CallsitePluginOptions` - Options for callsite tracking plugin
* `EnvironmentPluginOptions` - Options for environment detection plugin
## Examples [#examples]
### Example: Basic logger setup [#example-basic-logger-setup]
```typescript
import { getLogger, INFO } from '@accelint/logger';
const logger = getLogger({
enabled: true,
level: INFO,
env: 'production',
});
logger.info('Server started', { port: 3000 });
```
### Example: Development logger with pretty output [#example-development-logger-with-pretty-output]
```typescript
import { getLogger, DEBUG } from '@accelint/logger';
const logger = getLogger({
enabled: true,
level: DEBUG,
env: 'development',
pretty: true,
prefix: '[Dev]',
});
logger.debug('Cache miss', { key: 'user:123' });
```
### Example: Production logger with structured JSON [#example-production-logger-with-structured-json]
```typescript
import { getLogger, WARN } from '@accelint/logger';
const logger = getLogger({
enabled: true,
level: WARN,
env: 'production',
pretty: false, // Outputs JSON
});
logger.error('Payment failed', { orderId: 'ord_123', reason: 'insufficient_funds' });
```
### Example: Custom plugins [#example-custom-plugins]
```typescript
import { getLogger } from '@accelint/logger';
import type { LogLayerPlugin } from '@loglayer/shared';
const timingPlugin: LogLayerPlugin = {
id: 'timing',
onBeforeDataOut({ data }) {
return {
...data,
timestamp: Date.now(),
};
},
};
const logger = getLogger({
enabled: true,
plugins: [timingPlugin],
});
```
### Example: Custom transports [#example-custom-transports]
```typescript
import { getLogger, prettyTransport, structuredTransport } from '@accelint/logger';
// Multiple transports: pretty console + structured JSON
const logger = getLogger({
enabled: true,
transports: [
prettyTransport({ level: 'debug' }),
structuredTransport({ level: 'info' }),
],
});
logger.info('Logged to both transports');
```
### Example: Log groups [#example-log-groups]
```typescript
import { getLogger } from '@accelint/logger';
const logger = getLogger({
enabled: true,
groups: {
database: { enabled: true },
network: { enabled: false }, // Network logs disabled
},
});
logger.withGroup('database').info('Query executed');
logger.withGroup('network').info('This will not log');
```
> **Good to know:** `getLogger` returns a singleton. The first call initializes the logger with the provided options; subsequent calls return the same instance and ignore new options. Use `bootstrap` directly if you need multiple independent logger instances.
## Related [#related]
* [LogLayer Documentation](https://loglayer.dev/) - Upstream library documentation
* [getLogger](./default/index.md) - Singleton logger factory
* [bootstrap](./default/bootstrap.md) - Direct logger initialization
# clamp (/docs/packages/math/clamp)
## Usage [#usage]
```typescript
import { clamp } from '@accelint/math';
const result = clamp(5, 15, 10);
// 10
const belowMin = clamp(5, 15, 2);
// 5
const aboveMax = clamp(5, 15, 20);
// 15
```
## Reference [#reference]
```typescript
function clamp(min: number, max: number, value: number): number
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------- | --------------------------------------------- |
| `min` | `number` | The lower bound to clamp to. |
| `max` | `number` | The upper bound to clamp to. |
| `value` | `number` | The number value to clamp to the given range. |
### Returns [#returns]
Returns the clamped value. If `value` is below `min`, returns `min`. If `value` is above `max`, returns `max`. Otherwise returns `value`.
### Throws [#throws]
* `RangeError` - Throws if `min > max`.
## Examples [#examples]
### Example: Clamping below minimum [#example-clamping-below-minimum]
```typescript
import { clamp } from '@accelint/math';
const result = clamp(1, 2, 0);
// 1
```
### Example: Clamping above maximum [#example-clamping-above-maximum]
```typescript
import { clamp } from '@accelint/math';
const result = clamp(1, 2, 3);
// 2
```
### Example: Value within range [#example-value-within-range]
```typescript
import { clamp } from '@accelint/math';
const result = clamp(1, 3, 2);
// 2
```
> **Good to know:** The function validates that `min` does not exceed `max` and throws a `RangeError` if this constraint is violated.
## Related [#related]
* [round](../round) - Rounds a number to specified precision
# Overview (/docs/packages/math)
## Installation [#installation]
```bash
pnpm add @accelint/math
```
## Usage [#usage]
```typescript
// Import from root (all exports)
import { clamp, random, randomInt, round } from '@accelint/math';
// Import from sub-modules
import { clamp } from '@accelint/math/clamp';
import { random, randomInt } from '@accelint/math/random';
import { round } from '@accelint/math/round';
```
## Available Exports [#available-exports]
| Export Path | Description |
| ------------------ | ------------------------------------------------------------ |
| [clamp](./clamp) | Clamps a number within the specified bounds |
| [random](./random) | Generate random numbers and integers within specified bounds |
| [round](./round) | Rounds a number to a specified precision |
## Related [#related]
* [@accelint/core](../core) - Core functional utilities
* [GitHub Repository](https://github.com/gohypergiant/standard-toolkit) - Source code
# random (/docs/packages/math/random)
## random [#random]
Generate a random number within the given bounds.
### Usage [#usage]
```typescript
import { random } from '@accelint/math';
const value = random(0, 10);
// value >= 0 && value <= 10
```
### Reference [#reference]
```typescript
function random(min: number, max: number): number
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------- | ------------------------------------------- |
| `min` | `number` | The minimum value in the range (inclusive). |
| `max` | `number` | The maximum value in the range (inclusive). |
#### Returns [#returns]
Returns a random number between `min` and `max` (inclusive).
#### Throws [#throws]
* `RangeError` - Throws if `min > max`.
### Examples [#examples]
#### Example: Generating random decimal [#example-generating-random-decimal]
```typescript
import { random } from '@accelint/math';
const value = random(0, 1);
// A decimal between 0 and 1 (inclusive)
```
#### Example: Negative range [#example-negative-range]
```typescript
import { random } from '@accelint/math';
const value = random(-10, -5);
// A decimal between -10 and -5 (inclusive)
```
#### Example: Same min and max [#example-same-min-and-max]
```typescript
import { random } from '@accelint/math';
const value = random(5, 5);
// Approximately 5
```
> **Good to know:** Both bounds are inclusive. The function adds `Number.EPSILON` to ensure the maximum value can be generated.
***
## randomInt [#randomint]
Generate a random integer within the given bounds.
### Usage [#usage-1]
```typescript
import { randomInt } from '@accelint/math';
const value = randomInt(0, 10);
// An integer: 0, 1, 2, ..., 9, or 10
```
### Reference [#reference-1]
```typescript
function randomInt(min: number, max: number): number
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | -------- | ------------------------------------------- |
| `min` | `number` | The minimum value in the range (inclusive). |
| `max` | `number` | The maximum value in the range (inclusive). |
#### Returns [#returns-1]
Returns a random integer between `min` and `max` (inclusive).
#### Throws [#throws-1]
* `RangeError` - Throws if `min > max`.
### Examples [#examples-1]
#### Example: Generating dice roll [#example-generating-dice-roll]
```typescript
import { randomInt } from '@accelint/math';
const roll = randomInt(1, 6);
// A whole number: 1, 2, 3, 4, 5, or 6
```
#### Example: Floating point boundaries [#example-floating-point-boundaries]
```typescript
import { randomInt } from '@accelint/math';
const value = randomInt(0.5, 10.5);
// Integer between Math.ceil(0.5) and Math.floor(10.5)
// Result: 1, 2, 3, ..., 9, or 10
```
#### Example: Same min and max [#example-same-min-and-max-1]
```typescript
import { randomInt } from '@accelint/math';
const value = randomInt(5, 5);
// Always returns 5
```
> **Good to know:** When given floating point boundaries, the function uses `Math.ceil` on `min` and `Math.floor` on `max` to ensure integer results.
## Related [#related]
* [clamp](../clamp) - Clamps a number within specified bounds
# round (/docs/packages/math/round)
## Usage [#usage]
```typescript
import { round } from '@accelint/math';
const result = round(1, 1.2345);
// 1.2
const result = round(2, 1.2345);
// 1.23
const result = round(3, 1.2345);
// 1.235
```
## Reference [#reference]
```typescript
function round(precision: number, value: number): number
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `precision` | `number` | The precision of the rounded output. Must be an integer. Positive values round to decimal places; negative values round to positions left of the decimal point. |
| `value` | `number` | The value to round. |
### Returns [#returns]
Returns the rounded value.
### Throws [#throws]
* `Error` - Throws if `precision` is not an integer.
## Examples [#examples]
### Example: Positive precision (decimal places) [#example-positive-precision-decimal-places]
```typescript
import { round } from '@accelint/math';
const value = 1.2345;
round(1, value); // 1.2
round(2, value); // 1.23
round(3, value); // 1.235
round(4, value); // 1.2345
```
### Example: Zero precision (round to integer) [#example-zero-precision-round-to-integer]
```typescript
import { round } from '@accelint/math';
const result = round(0, 1.2345);
// 1
```
### Example: Negative precision (round left of decimal) [#example-negative-precision-round-left-of-decimal]
```typescript
import { round } from '@accelint/math';
const value = 12345.6789;
round(-1, value); // 12350
round(-2, value); // 12300
round(-3, value); // 12000
round(-4, value); // 10000
```
> **Good to know:** Precision must be an integer. Positive values round to decimal places (e.g., `1` = tenths, `2` = hundredths). Negative values round to positions left of the decimal point (e.g., `-1` = tens, `-2` = hundreds).
## Related [#related]
* [clamp](../clamp) - Clamps a number within specified bounds
# Color Constants (/docs/packages/ntds/constants)
Standard NTDS (Naval Tactical Data System) color values used for classifying and displaying entity affiliations in tactical displays.
## Usage [#usage]
```typescript
import {
NTDS_COLOR_FRIEND,
NTDS_COLOR_HOSTILE,
NTDS_COLOR_UNKNOWN,
} from '@accelint/ntds/constants';
function EntityIcon({ affiliation }) {
const color = affiliation === 'friend'
? NTDS_COLOR_FRIEND
: NTDS_COLOR_HOSTILE;
return <SvgAirFriend fill={color} />;
}
```
## Reference [#reference]
### NTDS\_COLOR\_ASSUMED\_FRIEND [#ntds_color_assumed_friend]
```typescript
const NTDS_COLOR_ASSUMED_FRIEND: '#0E8F37';
```
Green color indicating units that are likely friendly based on available intelligence but not definitively confirmed.
**Value:** `#0E8F37`
### NTDS\_COLOR\_FRIEND [#ntds_color_friend]
```typescript
const NTDS_COLOR_FRIEND: '#1484F4';
```
Blue color indicating units that are confirmed as friendly forces.
**Value:** `#1484F4`
### NTDS\_COLOR\_HOSTILE [#ntds_color_hostile]
```typescript
const NTDS_COLOR_HOSTILE: '#FF0033';
```
Red color indicating units that are confirmed as hostile or enemy forces.
**Value:** `#FF0033`
### NTDS\_COLOR\_NEUTRAL [#ntds_color_neutral]
```typescript
const NTDS_COLOR_NEUTRAL: '#5B137A';
```
Purple color indicating units that are confirmed as neutral, neither friendly nor hostile.
**Value:** `#5B137A`
### NTDS\_COLOR\_PENDING [#ntds_color_pending]
```typescript
const NTDS_COLOR_PENDING: '#404040';
```
Dark gray color indicating units whose status is pending classification or awaiting further information.
**Value:** `#404040`
### NTDS\_COLOR\_SUSPECT [#ntds_color_suspect]
```typescript
const NTDS_COLOR_SUSPECT: '#FFAD38';
```
Orange color indicating units that are suspected to be hostile but not yet confirmed.
**Value:** `#FFAD38`
### NTDS\_COLOR\_UNKNOWN [#ntds_color_unknown]
```typescript
const NTDS_COLOR_UNKNOWN: '#EDDA0A';
```
Yellow color indicating units whose affiliation or status is completely unknown.
**Value:** `#EDDA0A`
## Examples [#examples]
### Example: Dynamic color selection [#example-dynamic-color-selection]
```typescript
import {
NTDS_COLOR_FRIEND,
NTDS_COLOR_HOSTILE,
NTDS_COLOR_NEUTRAL,
NTDS_COLOR_UNKNOWN,
} from '@accelint/ntds/constants';
type Affiliation = 'friend' | 'hostile' | 'neutral' | 'unknown';
function getAffiliationColor(affiliation: Affiliation): string {
switch (affiliation) {
case 'friend':
return NTDS_COLOR_FRIEND;
case 'hostile':
return NTDS_COLOR_HOSTILE;
case 'neutral':
return NTDS_COLOR_NEUTRAL;
case 'unknown':
return NTDS_COLOR_UNKNOWN;
}
}
```
### Example: Color mapping for all classifications [#example-color-mapping-for-all-classifications]
```typescript
import {
NTDS_COLOR_ASSUMED_FRIEND,
NTDS_COLOR_FRIEND,
NTDS_COLOR_HOSTILE,
NTDS_COLOR_NEUTRAL,
NTDS_COLOR_PENDING,
NTDS_COLOR_SUSPECT,
NTDS_COLOR_UNKNOWN,
} from '@accelint/ntds/constants';
const AFFILIATION_COLORS = {
assumedFriend: NTDS_COLOR_ASSUMED_FRIEND,
friend: NTDS_COLOR_FRIEND,
hostile: NTDS_COLOR_HOSTILE,
neutral: NTDS_COLOR_NEUTRAL,
pending: NTDS_COLOR_PENDING,
suspect: NTDS_COLOR_SUSPECT,
unknown: NTDS_COLOR_UNKNOWN,
} as const;
```
### Example: Using with NTDS icons [#example-using-with-ntds-icons]
```typescript
import { NTDS_COLOR_HOSTILE } from '@accelint/ntds/constants';
import { SvgAirHostile } from '@accelint/ntds/core/air-hostile';
function HostileAircraft() {
return (
<SvgAirHostile
fill={NTDS_COLOR_HOSTILE}
width={32}
height={32}
/>
);
}
```
### Example: CSS custom properties [#example-css-custom-properties]
```typescript
import { NTDS_COLOR_FRIEND, NTDS_COLOR_HOSTILE } from '@accelint/ntds/constants';
const styles = {
'--color-friend': NTDS_COLOR_FRIEND,
'--color-hostile': NTDS_COLOR_HOSTILE,
} as React.CSSProperties;
function TacticalDisplay() {
return (
<div style={styles}>
{/* Elements can reference CSS vars */}
</div>
);
}
```
## Related [#related]
* [SvgAirFriend](./core/air-friend.mdx) - Friendly air entity icon component
* [SvgAirHostile](./core/air-hostile.mdx) - Hostile air entity icon component
* [Spritesheet Constants](./spritesheets/masked.mdx) - Spritesheet ID constants for COP usage
# Icon Components (/docs/packages/ntds/core)
React SVG icon components representing NTDS (Naval Tactical Data System) tactical symbols for military entities. Each component renders a 24×24 SVG with customizable fill color and accessibility support.
## Usage [#usage]
```tsx
import { SvgAirFriend } from '@accelint/ntds/core/air-friend';
import { NTDS_COLOR_FRIEND } from '@accelint/ntds/constants';
function TacticalDisplay() {
return (
<SvgAirFriend
fill={NTDS_COLOR_FRIEND}
width={32}
height={32}
title="Friendly Aircraft"
/>
);
}
```
## Reference [#reference]
All NTDS SVG components share a common interface:
```typescript
interface Props {
title?: string;
titleId?: string;
}
type SvgComponent = (props: SVGProps<SVGSVGElement> & Props) => JSX.Element;
```
### Props [#props]
| Prop | Type | Default | Required |
| ----------- | ------------------ | --------- | -------- |
| `fill` | `string` | `#FF69B4` | No |
| `width` | `number \| string` | `24` | No |
| `height` | `number \| string` | `24` | No |
| `title` | `string` | - | No |
| `titleId` | `string` | - | No |
| `className` | `string` | - | No |
| `style` | `CSSProperties` | - | No |
#### `fill` [#fill]
Color value for the SVG path fills. Defaults to hot pink (`#FF69B4`) as a visual indicator that fill should be explicitly set.
Use with NTDS color constants for proper affiliation colors:
* `NTDS_COLOR_FRIEND` - Blue for friendly entities
* `NTDS_COLOR_HOSTILE` - Red for hostile entities
* `NTDS_COLOR_UNKNOWN` - Yellow for unknown entities
* And other NTDS standard colors
#### `title` [#title]
Accessible title for screen readers. When provided, the SVG element includes an `aria-labelledby` attribute referencing the title.
> **Good to know:** Always provide a `title` prop when the icon conveys important information, especially in interactive contexts.
#### `titleId` [#titleid]
Custom ID for the `<title>` element. Defaults to automatic ID generation if not provided. Useful for ensuring unique IDs when multiple instances exist on the page.
### Inherited Props [#inherited-props]
All components accept standard SVGSVGElement props including:
* `className` - CSS class name
* `style` - Inline styles
* `onClick` - Click handler
* `onMouseEnter` / `onMouseLeave` - Mouse events
* `aria-*` - Additional ARIA attributes
## Available Components [#available-components]
### Air Entities [#air-entities]
| Component | Import Path | Description |
| ---------------------- | ---------------------------------------- | ------------------- |
| `SvgAirFriend` | `@accelint/ntds/core/air-friend` | Friendly aircraft |
| `SvgAirHostile` | `@accelint/ntds/core/air-hostile` | Hostile aircraft |
| `SvgAirUnknown` | `@accelint/ntds/core/air-unknown` | Unknown aircraft |
| `SvgAirBaseFriend` | `@accelint/ntds/core/air-base-friend` | Friendly air base |
| `SvgAirBaseHostile` | `@accelint/ntds/core/air-base-hostile` | Hostile air base |
| `SvgAirBaseUnknown` | `@accelint/ntds/core/air-base-unknown` | Unknown air base |
| `SvgAirGroupFriend` | `@accelint/ntds/core/air-group-friend` | Friendly air group |
| `SvgAirGroupHostile` | `@accelint/ntds/core/air-group-hostile` | Hostile air group |
| `SvgAirGroupUnknown` | `@accelint/ntds/core/air-group-unknown` | Unknown air group |
| `SvgHelicopterFriend` | `@accelint/ntds/core/helicopter-friend` | Friendly helicopter |
| `SvgHelicopterHostile` | `@accelint/ntds/core/helicopter-hostile` | Hostile helicopter |
| `SvgHelicopterUnknown` | `@accelint/ntds/core/helicopter-unknown` | Unknown helicopter |
### Surface Entities [#surface-entities]
| Component | Import Path | Description |
| ------------------------ | ------------------------------------------- | ---------------------- |
| `SvgSurfaceFriend` | `@accelint/ntds/core/surface-friend` | Friendly surface unit |
| `SvgSurfaceHostile` | `@accelint/ntds/core/surface-hostile` | Hostile surface unit |
| `SvgSurfaceUnknown` | `@accelint/ntds/core/surface-unknown` | Unknown surface unit |
| `SvgSurfaceGroupFriend` | `@accelint/ntds/core/surface-group-friend` | Friendly surface group |
| `SvgSurfaceGroupHostile` | `@accelint/ntds/core/surface-group-hostile` | Hostile surface group |
| `SvgSurfaceGroupUnknown` | `@accelint/ntds/core/surface-group-unknown` | Unknown surface group |
| `SvgCarrierFriend` | `@accelint/ntds/core/carrier-friend` | Friendly carrier |
| `SvgCarrierHostile` | `@accelint/ntds/core/carrier-hostile` | Hostile carrier |
| `SvgCarrierUnknown` | `@accelint/ntds/core/carrier-unknown` | Unknown carrier |
### Subsurface Entities [#subsurface-entities]
| Component | Import Path | Description |
| ---------------------- | ----------------------------------------- | ------------------------ |
| `SvgSubSurfaceFriend` | `@accelint/ntds/core/sub-surface-friend` | Friendly submarine |
| `SvgSubSurfaceHostile` | `@accelint/ntds/core/sub-surface-hostile` | Hostile submarine |
| `SvgSubSurfaceUnknown` | `@accelint/ntds/core/sub-surface-unknown` | Unknown submarine |
| `SvgSubGroupFriend` | `@accelint/ntds/core/sub-group-friend` | Friendly submarine group |
| `SvgSubGroupHostile` | `@accelint/ntds/core/sub-group-hostile` | Hostile submarine group |
| `SvgSubGroupUnknown` | `@accelint/ntds/core/sub-group-unknown` | Unknown submarine group |
### Land Entities [#land-entities]
| Component | Import Path | Description |
| ---------------- | ---------------------------------- | ------------------ |
| `SvgLandFriend` | `@accelint/ntds/core/land-friend` | Friendly land unit |
| `SvgLandHostile` | `@accelint/ntds/core/land-hostile` | Hostile land unit |
| `SvgLandUnknown` | `@accelint/ntds/core/land-unknown` | Unknown land unit |
| `SvgBaseFriend` | `@accelint/ntds/core/base-friend` | Friendly base |
| `SvgBaseHostile` | `@accelint/ntds/core/base-hostile` | Hostile base |
| `SvgBaseUnknown` | `@accelint/ntds/core/base-unknown` | Unknown base |
### Weapons & Ordnance [#weapons--ordnance]
| Component | Import Path | Description |
| ------------------- | ------------------------------------- | --------------------------- |
| `SvgMissileFriend` | `@accelint/ntds/core/missile-friend` | Friendly missile |
| `SvgMissileHostile` | `@accelint/ntds/core/missile-hostile` | Hostile missile |
| `SvgMissileUnknown` | `@accelint/ntds/core/missile-unknown` | Unknown missile |
| `SvgTorpedoFriend` | `@accelint/ntds/core/torpedo-friend` | Friendly torpedo |
| `SvgTorpedoHostile` | `@accelint/ntds/core/torpedo-hostile` | Hostile torpedo |
| `SvgTorpedoUnknown` | `@accelint/ntds/core/torpedo-unknown` | Unknown torpedo |
| `SvgTarget` | `@accelint/ntds/core/target` | Target designator |
| `SvgSam` | `@accelint/ntds/core/sam` | Surface-to-air missile site |
| `SvgMineField` | `@accelint/ntds/core/mine-field` | Mine field |
### Infrastructure & Facilities [#infrastructure--facilities]
| Component | Import Path | Description |
| ------------------- | ------------------------------------ | ---------------------------------------- |
| `SvgPort` | `@accelint/ntds/core/port` | Port facility |
| `SvgRunway` | `@accelint/ntds/core/runway` | Runway |
| `SvgStructure` | `@accelint/ntds/core/structure` | Generic structure |
| `SvgPol` | `@accelint/ntds/core/pol` | Petroleum, oils, and lubricants facility |
| `SvgCommunications` | `@accelint/ntds/core/communications` | Communications facility |
## Examples [#examples]
### Example: Entity with standard color [#example-entity-with-standard-color]
```tsx
import { SvgAirFriend } from '@accelint/ntds/core/air-friend';
import { NTDS_COLOR_FRIEND } from '@accelint/ntds/constants';
function FriendlyAircraft() {
return (
<SvgAirFriend
fill={NTDS_COLOR_FRIEND}
title="Friendly F-16"
/>
);
}
```
### Example: Dynamic affiliation rendering [#example-dynamic-affiliation-rendering]
```tsx
import { NTDS_COLOR_FRIEND, NTDS_COLOR_HOSTILE } from '@accelint/ntds/constants';
import { SvgAirFriend } from '@accelint/ntds/core/air-friend';
import { SvgAirHostile } from '@accelint/ntds/core/air-hostile';
type Entity = {
id: string;
affiliation: 'friend' | 'hostile';
};
function EntityIcon({ entity }: { entity: Entity }) {
if (entity.affiliation === 'hostile') {
return (
<SvgAirHostile
fill={NTDS_COLOR_HOSTILE}
title={`Hostile aircraft ${entity.id}`}
/>
);
}
return (
<SvgAirFriend
fill={NTDS_COLOR_FRIEND}
title={`Friendly aircraft ${entity.id}`}
/>
);
}
```
### Example: Custom sizing [#example-custom-sizing]
```tsx
import { SvgSurfaceFriend } from '@accelint/ntds/core/surface-friend';
import { NTDS_COLOR_FRIEND } from '@accelint/ntds/constants';
function LargeShipIcon() {
return (
<SvgSurfaceFriend
fill={NTDS_COLOR_FRIEND}
width={48}
height={48}
title="USS Enterprise"
/>
);
}
```
### Example: Interactive icon with events [#example-interactive-icon-with-events]
```tsx
import { SvgHelicopterFriend } from '@accelint/ntds/core/helicopter-friend';
import { NTDS_COLOR_FRIEND } from '@accelint/ntds/constants';
function InteractiveHelicopter({ onSelect }) {
const [isHovered, setIsHovered] = useState(false);
return (
<SvgHelicopterFriend
fill={isHovered ? '#00A0FF' : NTDS_COLOR_FRIEND}
width={32}
height={32}
title="Helicopter Unit 12"
onClick={onSelect}
onMouseEnter={() => setIsHovered(true)}
onMouseLeave={() => setIsHovered(false)}
style={{ cursor: 'pointer', transition: 'fill 0.2s' }}
/>
);
}
```
### Example: Multiple entities on tactical map [#example-multiple-entities-on-tactical-map]
```tsx
import { SvgAirFriend } from '@accelint/ntds/core/air-friend';
import { SvgSurfaceHostile } from '@accelint/ntds/core/surface-hostile';
import { SvgSubSurfaceUnknown } from '@accelint/ntds/core/sub-surface-unknown';
import {
NTDS_COLOR_FRIEND,
NTDS_COLOR_HOSTILE,
NTDS_COLOR_UNKNOWN,
} from '@accelint/ntds/constants';
function TacticalMap({ entities }) {
return (
<svg width={800} height={600}>
{entities.map((entity) => {
const Icon = getIconComponent(entity.type, entity.affiliation);
const color = getAffiliationColor(entity.affiliation);
return (
<g key={entity.id} transform={`translate(${entity.x}, ${entity.y})`}>
<Icon
fill={color}
title={entity.callsign}
/>
</g>
);
})}
</svg>
);
}
```
### Example: All affiliation states [#example-all-affiliation-states]
```tsx
import { SvgMissileFriend } from '@accelint/ntds/core/missile-friend';
import { SvgMissileHostile } from '@accelint/ntds/core/missile-hostile';
import { SvgMissileUnknown } from '@accelint/ntds/core/missile-unknown';
import {
NTDS_COLOR_FRIEND,
NTDS_COLOR_HOSTILE,
NTDS_COLOR_UNKNOWN,
} from '@accelint/ntds/constants';
function MissileLegend() {
return (
<div className="legend">
<div>
<SvgMissileFriend fill={NTDS_COLOR_FRIEND} />
<span>Friendly</span>
</div>
<div>
<SvgMissileHostile fill={NTDS_COLOR_HOSTILE} />
<span>Hostile</span>
</div>
<div>
<SvgMissileUnknown fill={NTDS_COLOR_UNKNOWN} />
<span>Unknown</span>
</div>
</div>
);
}
```
## Related [#related]
* [NTDS Color Constants](../constants.mdx) - Standard NTDS affiliation colors
* [Spritesheet Constants](../spritesheets/masked.mdx) - Spritesheet IDs for COP rendering
# Overview (/docs/packages/ntds)
## Overview [#overview]
The `@accelint/ntds` package provides two rendering approaches for NTDS tactical symbols:
1. **React SVG Components** - Individual components for flexible UI integration
2. **Spritesheet Constants** - Numeric IDs for efficient canvas/WebGL rendering
All symbols follow NTDS (Naval Tactical Data System) standards for military tactical displays.
## Installation [#installation]
```bash
pnpm add @accelint/ntds react react-dom
```
## Quick Start [#quick-start]
### Using SVG Components [#using-svg-components]
```tsx
import { SvgAirFriend } from '@accelint/ntds/core/air-friend';
import { NTDS_COLOR_FRIEND } from '@accelint/ntds/constants';
function TacticalIcon() {
return (
<SvgAirFriend
fill={NTDS_COLOR_FRIEND}
width={32}
height={32}
title="Friendly F-16"
/>
);
}
```
### Using Spritesheet Constants [#using-spritesheet-constants]
```typescript
import { AIR_FRIEND, SURFACE_HOSTILE } from '@accelint/ntds/spritesheets/masked';
// Use sprite IDs with your rendering engine
const friendlyAircraftSprite = spritesheet.getFrame(AIR_FRIEND);
const hostileShipSprite = spritesheet.getFrame(SURFACE_HOSTILE);
```
## Package Exports [#package-exports]
### Color Constants [#color-constants]
Standard NTDS affiliation colors:
```typescript
import {
NTDS_COLOR_FRIEND, // Blue (#1484F4)
NTDS_COLOR_HOSTILE, // Red (#FF0033)
NTDS_COLOR_UNKNOWN, // Yellow (#EDDA0A)
NTDS_COLOR_NEUTRAL, // Purple (#5B137A)
NTDS_COLOR_ASSUMED_FRIEND, // Green (#0E8F37)
NTDS_COLOR_SUSPECT, // Orange (#FFAD38)
NTDS_COLOR_PENDING, // Dark gray (#404040)
} from '@accelint/ntds/constants';
```
[View full documentation →](./constants.mdx)
### SVG Components [#svg-components]
47 React components for NTDS tactical symbols:
**Air Domain:**
* `SvgAirFriend`, `SvgAirHostile`, `SvgAirUnknown`
* `SvgAirBaseFriend`, `SvgAirBaseHostile`, `SvgAirBaseUnknown`
* `SvgAirGroupFriend`, `SvgAirGroupHostile`, `SvgAirGroupUnknown`
* `SvgHelicopterFriend`, `SvgHelicopterHostile`, `SvgHelicopterUnknown`
**Surface Domain:**
* `SvgSurfaceFriend`, `SvgSurfaceHostile`, `SvgSurfaceUnknown`
* `SvgSurfaceGroupFriend`, `SvgSurfaceGroupHostile`, `SvgSurfaceGroupUnknown`
* `SvgCarrierFriend`, `SvgCarrierHostile`, `SvgCarrierUnknown`
**Subsurface Domain:**
* `SvgSubSurfaceFriend`, `SvgSubSurfaceHostile`, `SvgSubSurfaceUnknown`
* `SvgSubGroupFriend`, `SvgSubGroupHostile`, `SvgSubGroupUnknown`
**Land Domain:**
* `SvgLandFriend`, `SvgLandHostile`, `SvgLandUnknown`
* `SvgBaseFriend`, `SvgBaseHostile`, `SvgBaseUnknown`
**Weapons & Infrastructure:**
* `SvgMissileFriend`, `SvgMissileHostile`, `SvgMissileUnknown`
* `SvgTorpedoFriend`, `SvgTorpedoHostile`, `SvgTorpedoUnknown`
* `SvgTarget`, `SvgSam`, `SvgMineField`
* `SvgPort`, `SvgRunway`, `SvgStructure`, `SvgPol`, `SvgCommunications`
[View full documentation →](./core.mdx)
### Spritesheet Constants [#spritesheet-constants]
64 numeric string identifiers for sprite-based rendering:
```typescript
import {
AIR_FRIEND,
AIR_HOSTILE,
SURFACE_FRIEND,
SURFACE_HOSTILE,
// ... and 60 more constants
} from '@accelint/ntds/spritesheets/masked';
```
[View full documentation →](./spritesheets/masked.mdx)
## Usage Patterns [#usage-patterns]
### Pattern: Dynamic Entity Rendering [#pattern-dynamic-entity-rendering]
```tsx
import { NTDS_COLOR_FRIEND, NTDS_COLOR_HOSTILE } from '@accelint/ntds/constants';
import { SvgAirFriend } from '@accelint/ntds/core/air-friend';
import { SvgAirHostile } from '@accelint/ntds/core/air-hostile';
type Entity = {
id: string;
type: 'air' | 'surface' | 'subsurface';
affiliation: 'friend' | 'hostile';
position: { x: number; y: number };
};
function EntityIcon({ entity }: { entity: Entity }) {
const Component = entity.affiliation === 'friend'
? SvgAirFriend
: SvgAirHostile;
const color = entity.affiliation === 'friend'
? NTDS_COLOR_FRIEND
: NTDS_COLOR_HOSTILE;
return <Component fill={color} title={entity.id} />;
}
```
### Pattern: Tactical Map with Multiple Entities [#pattern-tactical-map-with-multiple-entities]
```tsx
import { SvgAirFriend, SvgSurfaceHostile } from '@accelint/ntds';
import { NTDS_COLOR_FRIEND, NTDS_COLOR_HOSTILE } from '@accelint/ntds/constants';
function TacticalMap({ entities }) {
return (
<svg width={800} height={600} viewBox="0 0 800 600">
{entities.map((entity) => (
<g
key={entity.id}
transform={`translate(${entity.x}, ${entity.y})`}
>
{entity.type === 'air' && entity.affiliation === 'friend' && (
<SvgAirFriend fill={NTDS_COLOR_FRIEND} />
)}
{entity.type === 'surface' && entity.affiliation === 'hostile' && (
<SvgSurfaceHostile fill={NTDS_COLOR_HOSTILE} />
)}
</g>
))}
</svg>
);
}
```
### Pattern: Spritesheet Rendering for Performance [#pattern-spritesheet-rendering-for-performance]
```typescript
import { AIR_FRIEND, SURFACE_HOSTILE } from '@accelint/ntds/spritesheets/masked';
class HighPerformanceCop {
private spritesheet: HTMLImageElement;
private spriteData: SpritesheetData;
renderEntities(entities: Entity[], ctx: CanvasRenderingContext2D): void {
for (const entity of entities) {
const spriteId = this.getSpriteId(entity);
const sprite = this.spriteData.frames[spriteId];
ctx.drawImage(
this.spritesheet,
sprite.frame.x,
sprite.frame.y,
sprite.frame.w,
sprite.frame.h,
entity.x,
entity.y,
24,
24
);
}
}
}
```
## Type Safety [#type-safety]
All exports are fully typed:
```typescript
import type { SVGProps } from 'react';
// Component props type
type IconProps = SVGProps<SVGSVGElement> & {
title?: string;
titleId?: string;
};
// Sprite ID type (from constants)
type SpriteId = string;
// Color type (from constants)
type NtdsColor = string; // hex color strings
```
## Browser Support [#browser-support]
* Modern browsers with SVG support
* React 19+
* Canvas/WebGL for spritesheet rendering
## Performance Considerations [#performance-considerations]
**Use SVG Components when:**
* Building React UIs with moderate entity counts (\< 100 entities)
* Need interactive icons with hover states, clicks
* Styling flexibility is important
* Accessibility features (titles, ARIA labels) are required
**Use Spritesheet Constants when:**
* Rendering hundreds or thousands of entities
* Building canvas/WebGL-based tactical displays
* Performance is critical
* COP or real-time tracking applications
## Examples [#examples]
### Example: Legend Component [#example-legend-component]
```tsx
import { SvgAirFriend, SvgSurfaceHostile } from '@accelint/ntds';
import { NTDS_COLOR_FRIEND, NTDS_COLOR_HOSTILE } from '@accelint/ntds/constants';
function TacticalLegend() {
return (
<div className="legend">
<h3>Entity Types</h3>
<div className="legend-item">
<SvgAirFriend fill={NTDS_COLOR_FRIEND} />
<span>Friendly Aircraft</span>
</div>
<div className="legend-item">
<SvgSurfaceHostile fill={NTDS_COLOR_HOSTILE} />
<span>Hostile Surface Vessel</span>
</div>
</div>
);
}
```
### Example: Interactive Selectable Entity [#example-interactive-selectable-entity]
```tsx
import { useState } from 'react';
import { SvgHelicopterFriend } from '@accelint/ntds/core/helicopter-friend';
import { NTDS_COLOR_FRIEND } from '@accelint/ntds/constants';
function SelectableEntity({ entity, onSelect }) {
const [isHovered, setIsHovered] = useState(false);
return (
<SvgHelicopterFriend
fill={isHovered ? '#00A0FF' : NTDS_COLOR_FRIEND}
width={32}
height={32}
title={entity.callsign}
onClick={() => onSelect(entity)}
onMouseEnter={() => setIsHovered(true)}
onMouseLeave={() => setIsHovered(false)}
style={{
cursor: 'pointer',
transition: 'fill 0.2s',
}}
/>
);
}
```
## Contributing [#contributing]
This package is generated from NTDS-compliant SVG source files using the `smeegl` tool. To add new symbols:
1. Add SVG files to `packages/ntds/icons/core/` or `packages/ntds/icons/masked/`
2. Run `pnpm build` to regenerate components and spritesheet
3. Run `pnpm index` to update package exports
## License [#license]
Apache-2.0
## Related Packages [#related-packages]
* `@accelint/design-toolkit` - UI component library
* `@accelint/icons` - General purpose icon library
# Icon Constants (/docs/packages/ntds/masked)
Numeric string identifiers for NTDS tactical symbols in spritesheet format. These constants are used for efficient rendering in Common Operating Picture (COP) applications where sprite-based rendering is preferred over individual SVG components.
## Usage [#usage]
```typescript
import { AIR_FRIEND, SURFACE_HOSTILE } from '@accelint/ntds/spritesheets/masked';
// Reference sprites by ID in COP rendering engine
const friendlyAircraftSprite = spritesheet.getSprite(AIR_FRIEND);
const hostileShipSprite = spritesheet.getSprite(SURFACE_HOSTILE);
```
## Reference [#reference]
All constants are numeric string identifiers generated using CRC-32 hashing:
```typescript
const CONSTANT_NAME: string; // e.g., '978699787'
```
Each constant represents a unique sprite frame in the NTDS spritesheet. The numeric IDs are deterministic and stable across builds.
> **Good to know:** These constants are generated by the `smeegl` tool with CRC-32 decimal encoding. The IDs remain consistent as long as the source SVG files don't change.
## Available Constants [#available-constants]
### Air Domain [#air-domain]
**Standard Air Entities:**
* `AIR_FRIEND` - Friendly aircraft
* `AIR_HOSTILE` - Hostile aircraft
* `AIR_UNKNOWN` - Unknown aircraft
* `AIR_ASSUMED_FRIEND` - Assumed friendly aircraft
* `AIR_NEUTRAL` - Neutral aircraft
* `AIR_PENDING` - Pending classification aircraft
* `AIR_SUSPECT` - Suspect aircraft
**Air Bases:**
* `AIR_BASE_FRIEND` - Friendly air base
* `AIR_BASE_HOSTILE` - Hostile air base
* `AIR_BASE_UNKNOWN` - Unknown air base
**Air Groups:**
* `AIR_GROUP_FRIEND` - Friendly air group
* `AIR_GROUP_HOSTILE` - Hostile air group
* `AIR_GROUP_UNKNOWN` - Unknown air group
**Helicopters:**
* `HELICOPTER_FRIEND` - Friendly helicopter
* `HELICOPTER_HOSTILE` - Hostile helicopter
* `HELICOPTER_UNKNOWN` - Unknown helicopter
### Surface Domain [#surface-domain]
**Standard Surface Units:**
* `SURFACE_FRIEND` - Friendly surface unit
* `SURFACE_HOSTILE` - Hostile surface unit
* `SURFACE_UNKNOWN` - Unknown surface unit
* `SURFACE_ASSUMED_FRIEND` - Assumed friendly surface unit
* `SURFACE_NEUTRAL` - Neutral surface unit
* `SURFACE_PENDING` - Pending classification surface unit
* `SURFACE_SUSPECT` - Suspect surface unit
**Surface Groups:**
* `SURFACE_GROUP_FRIEND` - Friendly surface group
* `SURFACE_GROUP_HOSTILE` - Hostile surface group
* `SURFACE_GROUP_UNKNOWN` - Unknown surface group
**Carriers:**
* `CARRIER_FRIEND` - Friendly carrier
* `CARRIER_HOSTILE` - Hostile carrier
* `CARRIER_UNKNOWN` - Unknown carrier
### Subsurface Domain [#subsurface-domain]
**Standard Subsurface Units:**
* `SUB_SURFACE_FRIEND` - Friendly submarine
* `SUB_SURFACE_HOSTILE` - Hostile submarine
* `SUB_SURFACE_UNKNOWN` - Unknown submarine
* `SUB_SURFACE_ASSUMED_FRIEND` - Assumed friendly submarine
* `SUB_SURFACE_NEUTRAL` - Neutral submarine
* `SUB_SURFACE_PENDING` - Pending classification submarine
* `SUB_SURFACE_SUSPECT` - Suspect submarine
**Submarine Groups:**
* `SUB_GROUP_FRIEND` - Friendly submarine group
* `SUB_GROUP_HOSTILE` - Hostile submarine group
* `SUB_GROUP_UNKNOWN` - Unknown submarine group
### Land Domain [#land-domain]
**Land Units:**
* `LAND_FRIEND` - Friendly land unit
* `LAND_HOSTILE` - Hostile land unit
* `LAND_UNKNOWN` - Unknown land unit
* `LAND_ASSUMED_FRIEND` - Assumed friendly land unit
* `LAND_NEUTRAL` - Neutral land unit
* `LAND_PENDING` - Pending classification land unit
* `LAND_SUSPECT` - Suspect land unit
**Bases:**
* `BASE_FRIEND` - Friendly base
* `BASE_HOSTILE` - Hostile base
* `BASE_UNKNOWN` - Unknown base
### Weapons & Ordnance [#weapons--ordnance]
**Missiles:**
* `MISSILE_FRIEND` - Friendly missile
* `MISSILE_HOSTILE` - Hostile missile
* `MISSILE_UNKNOWN` - Unknown missile
**Torpedoes:**
* `TORPEDO_FRIEND` - Friendly torpedo
* `TORPEDO_HOSTILE` - Hostile torpedo
* `TORPEDO_UNKNOWN` - Unknown torpedo
**Other Weapons:**
* `SAM` - Surface-to-air missile site
* `MINE_FIELD` - Mine field
* `TARGET` - Target designator
### Infrastructure & Facilities [#infrastructure--facilities]
* `PORT` - Port facility
* `RUNWAY` - Runway
* `STRUCTURE` - Generic structure
* `POL` - Petroleum, oils, and lubricants facility
* `COMMUNICATIONS` - Communications facility
## Examples [#examples]
### Example: Sprite lookup in rendering engine [#example-sprite-lookup-in-rendering-engine]
```typescript
import { AIR_FRIEND, SURFACE_HOSTILE } from '@accelint/ntds/spritesheets/masked';
class CopRenderer {
private spritesheet: Spritesheet;
renderEntity(entity: Entity): void {
const spriteId = this.getSpriteId(entity);
const sprite = this.spritesheet.getSprite(spriteId);
this.drawSprite(sprite, entity.x, entity.y);
}
private getSpriteId(entity: Entity): string {
if (entity.domain === 'air' && entity.affiliation === 'friend') {
return AIR_FRIEND;
}
if (entity.domain === 'surface' && entity.affiliation === 'hostile') {
return SURFACE_HOSTILE;
}
// ... more mappings
}
}
```
### Example: Sprite ID mapping table [#example-sprite-id-mapping-table]
```typescript
import {
AIR_FRIEND,
AIR_HOSTILE,
AIR_UNKNOWN,
SURFACE_FRIEND,
SURFACE_HOSTILE,
SURFACE_UNKNOWN,
} from '@accelint/ntds/spritesheets/masked';
type Domain = 'air' | 'surface';
type Affiliation = 'friend' | 'hostile' | 'unknown';
const SPRITE_MAP: Record<Domain, Record<Affiliation, string>> = {
air: {
friend: AIR_FRIEND,
hostile: AIR_HOSTILE,
unknown: AIR_UNKNOWN,
},
surface: {
friend: SURFACE_FRIEND,
hostile: SURFACE_HOSTILE,
unknown: SURFACE_UNKNOWN,
},
};
function getSpriteId(domain: Domain, affiliation: Affiliation): string {
return SPRITE_MAP[domain][affiliation];
}
```
### Example: Canvas rendering with sprites [#example-canvas-rendering-with-sprites]
```typescript
import { AIR_FRIEND } from '@accelint/ntds/spritesheets/masked';
function renderTacticalIcon(
ctx: CanvasRenderingContext2D,
spritesheet: HTMLImageElement,
spriteData: SpritesheetData,
x: number,
y: number
): void {
const sprite = spriteData.frames[AIR_FRIEND];
ctx.drawImage(
spritesheet,
sprite.frame.x,
sprite.frame.y,
sprite.frame.w,
sprite.frame.h,
x,
y,
sprite.frame.w,
sprite.frame.h
);
}
```
### Example: WebGL sprite rendering [#example-webgl-sprite-rendering]
```typescript
import { SURFACE_GROUP_HOSTILE } from '@accelint/ntds/spritesheets/masked';
interface SpriteInstance {
spriteId: string;
x: number;
y: number;
scale: number;
}
class WebGLCopRenderer {
private spritesheet: WebGLTexture;
private spriteData: SpritesheetData;
renderBatch(instances: SpriteInstance[]): void {
const vertices = instances.flatMap((instance) => {
const sprite = this.spriteData.frames[instance.spriteId];
return this.createQuad(sprite, instance.x, instance.y, instance.scale);
});
this.drawVertices(vertices);
}
}
// Usage
const hostileFleet: SpriteInstance[] = [
{ spriteId: SURFACE_GROUP_HOSTILE, x: 100, y: 200, scale: 1.0 },
{ spriteId: SURFACE_GROUP_HOSTILE, x: 150, y: 220, scale: 1.0 },
];
```
### Example: Dynamic affiliation state changes [#example-dynamic-affiliation-state-changes]
```typescript
import {
SURFACE_UNKNOWN,
SURFACE_SUSPECT,
SURFACE_HOSTILE,
} from '@accelint/ntds/spritesheets/masked';
class TrackedEntity {
private currentSpriteId: string;
constructor() {
this.currentSpriteId = SURFACE_UNKNOWN;
}
updateAffiliation(confidence: number): void {
if (confidence > 0.8) {
this.currentSpriteId = SURFACE_HOSTILE;
} else if (confidence > 0.5) {
this.currentSpriteId = SURFACE_SUSPECT;
} else {
this.currentSpriteId = SURFACE_UNKNOWN;
}
}
getSpriteId(): string {
return this.currentSpriteId;
}
}
```
### Example: Sprite preloading [#example-sprite-preloading]
```typescript
import * as SPRITES from '@accelint/ntds/spritesheets/masked';
class SpritesheetManager {
private loadedSprites = new Set<string>();
async preloadCommonSprites(): Promise<void> {
const commonSprites = [
SPRITES.AIR_FRIEND,
SPRITES.AIR_HOSTILE,
SPRITES.SURFACE_FRIEND,
SPRITES.SURFACE_HOSTILE,
SPRITES.SUB_SURFACE_UNKNOWN,
];
await Promise.all(
commonSprites.map((spriteId) => this.loadSprite(spriteId))
);
}
private async loadSprite(spriteId: string): Promise<void> {
// Load sprite data
this.loadedSprites.add(spriteId);
}
}
```
### Example: Type-safe sprite selection [#example-type-safe-sprite-selection]
```typescript
import type * as SPRITES from '@accelint/ntds/spritesheets/masked';
type SpriteId = typeof SPRITES[keyof typeof SPRITES];
function renderSprite(spriteId: SpriteId, x: number, y: number): void {
// Type-safe sprite ID
console.log(`Rendering sprite ${spriteId} at (${x}, ${y})`);
}
// Valid
renderSprite(SPRITES.AIR_FRIEND, 10, 20);
// Type error - invalid sprite ID
// renderSprite('invalid-id', 10, 20);
```
## Related [#related]
* [NTDS Color Constants](../constants.mdx) - Standard NTDS affiliation colors
* [SVG Icon Components](../core.mdx) - Individual React SVG components for general usage
# Overview (/docs/packages/postcss-tailwind-css-modules)
PostCSS plugin that wraps Tailwind CSS `group/` and `peer/` classes in `:global()` pseudo-class to fix compatibility issues with CSS Modules.
## Usage [#usage]
```typescript
// postcss.config.js
export default {
plugins: {
'@tailwindcss/postcss': {},
'@accelint/postcss-tailwind-css-modules': {},
},
};
```
## Reference [#reference]
```typescript
function tailwindCssModulesPlugin(): Plugin
```
### Returns [#returns]
Returns a PostCSS plugin instance configured to transform `group/` and `peer/` classes.
The plugin:
* Only processes files ending in `.module.css`
* Wraps Tailwind `group/` and `peer/` classes in `:global()` pseudo-class
* Prevents duplicate transformations using symbol-based tracking
### Plugin Behavior [#plugin-behavior]
The plugin automatically identifies and transforms selectors containing:
* Classes starting with `group/` (e.g., `group/sidebar`, `group/header`)
* Classes starting with `peer/` (e.g., `peer/checked`, `peer/focus`)
## Examples [#examples]
### Example: Basic configuration with Turbo and Webpack [#example-basic-configuration-with-turbo-and-webpack]
```javascript
// postcss.config.js
export default {
plugins: {
'@tailwindcss/postcss': {},
'@accelint/postcss-tailwind-css-modules': {},
},
};
```
### Example: Configuration with Vite [#example-configuration-with-vite]
```javascript
// postcss.config.js
export default {
plugins: {
'@accelint/postcss-tailwind-css-modules': {},
},
};
```
> **Good to know:** When using Vite, the Tailwind Vite plugin handles Tailwind's PostCSS processing, so you only need this plugin in your PostCSS config. Do not use array syntax (`plugins: ['...']`) as it will cause errors with Vite—use the object syntax shown above.
### Example: CSS transformation [#example-css-transformation]
**Input:**
```css
/* styles.module.css */
.group/sidebar {
color: red;
}
.peer/checked {
color: blue;
}
```
**Output:**
```css
:global(.group/sidebar) {
color: red;
}
:global(.peer/checked) {
color: blue;
}
```
### Example: Complex selectors [#example-complex-selectors]
The plugin handles complex selectors including pseudo-classes, pseudo-elements, and descendant selectors:
```css
/* Input */
.container .group/sidebar:hover > .item { }
.peer/checked:focus::after { }
/* Output */
.container :global(.group/sidebar):hover > .item { }
:global(.peer/checked):focus::after { }
```
### Example: Multiple classes in one selector [#example-multiple-classes-in-one-selector]
```css
/* Input */
.group/header.group/nav { }
/* Output */
:global(.group/header):global(.group/nav) { }
```
> **Good to know:** The plugin only transforms classes that start with `group/` or `peer/` followed by a forward slash. Classes like `.group` or `.peer` (without the slash) are not transformed. Regular CSS Modules classes in the same selector remain unaffected.
## Related [#related]
* [PostCSS Documentation](https://postcss.org/)
* [postcss-selector-parser](https://www.npmjs.com/package/postcss-selector-parser) - Used internally for selector transformation
* [Tailwind CSS - Parent State](https://tailwindcss.com/docs/hover-focus-and-other-states#styling-based-on-parent-state)
* [Tailwind CSS - Sibling State](https://tailwindcss.com/docs/hover-focus-and-other-states#styling-based-on-sibling-state)
# doesEndWith (/docs/packages/predicates/does-end-with)
Creates a predicate function that determines if a string ends with a specific suffix.
## Usage [#usage]
```typescript
import { doesEndWith } from '@accelint/predicates';
const isJsFile = doesEndWith('.js');
isJsFile('app.js'); // true
isJsFile('style.css'); // false
```
## Reference [#reference]
```typescript
function doesEndWith(suffix: string): (input: string) => boolean
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------- | ---------------------------------- |
| `suffix` | `string` | The substring to use as the suffix |
### Returns [#returns]
Curried function that accepts a string and returns `true` if it ends with the suffix.
## Examples [#examples]
### Example: File extension filtering [#example-file-extension-filtering]
```typescript
import { doesEndWith } from '@accelint/predicates';
const isImageFile = doesEndWith('.jpg');
const isConfigFile = doesEndWith('.json');
const files = ['avatar.jpg', 'config.json', 'script.js', 'photo.jpg'];
const images = files.filter(doesEndWith('.jpg'));
// ['avatar.jpg', 'photo.jpg']
```
### Example: Email domain validation [#example-email-domain-validation]
```typescript
import { doesEndWith } from '@accelint/predicates';
const isCompanyEmail = doesEndWith('@company.com');
function validateEmail(email: string): boolean {
return isCompanyEmail(email);
}
validateEmail('user@company.com'); // true
validateEmail('user@external.com'); // false
```
> **Good to know:** Comparisons are case-sensitive. Use native String methods like `.toLowerCase()` before applying this predicate if case-insensitive matching is needed.
## Related [#related]
* [doesStartWith](./does-start-with) - Check if string starts with prefix
* [doesNotStartWith](./does-not-start-with) - Check if string does not start with prefix
* [doesNotEndWith](./does-not-end-with) - Negated version of this function
* [isLike](../is-like/index.md) - Pattern matching with RegExp
* [isNotLike](../is-not-like/index.md) - Negated pattern matching
* [isString](../is-string/index.md) - Type guard for strings
# doesNotEndWith (/docs/packages/predicates/does-not-end-with)
Creates a predicate function that determines if a string does **not** end with a specific suffix.
## Usage [#usage]
```typescript
import { doesNotEndWith } from '@accelint/predicates';
const isNotBackup = doesNotEndWith('.bak');
const files = ['data.json', 'data.json.bak', 'config.yaml', 'config.yaml.bak'];
const active = files.filter(isNotBackup);
// ['data.json', 'config.yaml']
```
## Reference [#reference]
```typescript
function doesNotEndWith(suffix: string): (input: string) => boolean
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------- | ---------------------------------- |
| `suffix` | `string` | The substring to use as the suffix |
### Returns [#returns]
Curried function that accepts a string and returns `true` if it does **not** end with the suffix.
## Examples [#examples]
### Example: Excluding backup files [#example-excluding-backup-files]
```typescript
import { doesNotEndWith } from '@accelint/predicates';
const isNotBackup = doesNotEndWith('.bak');
const files = ['data.json', 'data.json.bak', 'config.yaml', 'config.yaml.bak'];
const active = files.filter(isNotBackup);
// ['data.json', 'config.yaml']
```
> **Good to know:** Comparisons are case-sensitive. Use native String methods like `.toLowerCase()` before applying this predicate if case-insensitive matching is needed.
## Related [#related]
* [doesEndWith](./does-end-with) - Positive version of this function
* [doesStartWith](./does-start-with) - Check if string starts with prefix
* [doesNotStartWith](./does-not-start-with) - Check if string does not start with prefix
* [isLike](../is-like/index.md) - Pattern matching with RegExp
* [isNotLike](../is-not-like/index.md) - Negated pattern matching
* [isString](../is-string/index.md) - Type guard for strings
# doesNotStartWith (/docs/packages/predicates/does-not-start-with)
Creates a predicate function that determines if a string does **not** start with a specific prefix.
## Usage [#usage]
```typescript
import { doesNotStartWith } from '@accelint/predicates';
const isNotHidden = doesNotStartWith('.');
const files = ['.git', '.env', 'README.md', '.gitignore', 'src'];
const visible = files.filter(isNotHidden);
// ['README.md', 'src']
```
## Reference [#reference]
```typescript
function doesNotStartWith(prefix: string): (input: string) => boolean
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------- | ---------------------------------- |
| `prefix` | `string` | The substring to use as the prefix |
### Returns [#returns]
Curried function that accepts a string and returns `true` if it does **not** start with the prefix.
## Examples [#examples]
### Example: Excluding system files [#example-excluding-system-files]
```typescript
import { doesNotStartWith } from '@accelint/predicates';
const isNotHidden = doesNotStartWith('.');
const files = ['.git', '.env', 'README.md', '.gitignore', 'src'];
const visible = files.filter(isNotHidden);
// ['README.md', 'src']
```
> **Good to know:** Comparisons are case-sensitive. Use native String methods like `.toLowerCase()` before applying this predicate if case-insensitive matching is needed.
## Related [#related]
* [doesStartWith](./does-start-with) - Positive version of this function
* [doesEndWith](./does-end-with) - Check if string ends with suffix
* [doesNotEndWith](./does-not-end-with) - Check if string does not end with suffix
* [isLike](../is-like/index.md) - Pattern matching with RegExp
* [isNotLike](../is-not-like/index.md) - Negated pattern matching
* [isString](../is-string/index.md) - Type guard for strings
# doesStartWith (/docs/packages/predicates/does-start-with)
Creates a predicate function that determines if a string starts with a specific prefix.
## Usage [#usage]
```typescript
import { doesStartWith } from '@accelint/predicates';
const isHttpUrl = doesStartWith('http');
isHttpUrl('https://example.com'); // true
isHttpUrl('ftp://example.com'); // false
```
## Reference [#reference]
```typescript
function doesStartWith(prefix: string): (input: string) => boolean
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------- | ---------------------------------- |
| `prefix` | `string` | The substring to use as the prefix |
### Returns [#returns]
Curried function that accepts a string and returns `true` if it starts with the prefix.
## Examples [#examples]
### Example: URL validation [#example-url-validation]
```typescript
import { doesStartWith } from '@accelint/predicates';
const isHttps = doesStartWith('https://');
const isHttp = doesStartWith('http://');
function isSecureUrl(url: string): boolean {
return isHttps(url);
}
isSecureUrl('https://example.com'); // true
isSecureUrl('http://example.com'); // false
```
### Example: Filtering file paths [#example-filtering-file-paths]
```typescript
import { doesStartWith } from '@accelint/predicates';
const paths = [
'/home/user/documents',
'/var/log/system',
'/home/user/downloads',
'/etc/config'
];
const userPaths = paths.filter(doesStartWith('/home/user'));
// ['/home/user/documents', '/home/user/downloads']
```
> **Good to know:** Comparisons are case-sensitive. Use native String methods like `.toLowerCase()` before applying this predicate if case-insensitive matching is needed.
## Related [#related]
* [doesEndWith](./does-end-with) - Check if string ends with suffix
* [doesNotStartWith](./does-not-start-with) - Negated version of this function
* [doesNotEndWith](./does-not-end-with) - Check if string does not end with suffix
* [isLike](../is-like/index.md) - Pattern matching with RegExp
* [isNotLike](../is-not-like/index.md) - Negated pattern matching
* [isString](../is-string/index.md) - Type guard for strings
# Overview (/docs/packages/predicates)
## Installation [#installation]
```bash
pnpm add @accelint/predicates
```
## Categories [#categories]
### Type Guards [#type-guards]
Core type checking predicates:
* [isString](./is-string/index.md) - Type guard for string values
* [isNumber](./is-number/index.md) - Number type guards including finite checks
* [isNothing](./is-nothing/index.md) - Check for null or undefined
* [isSomething](./is-something/index.md) - Check for defined values
### Boolean-like Values [#boolean-like-values]
Parse and validate truthy/falsy string representations:
* [is-noyes](./is-noyes/index.md) - Yes/no, on/off, true/false predicates
* `isTrue`, `isFalse`, `isYes`, `isNo`, `isOn`, `isOff`
* `isAnyTruthy`, `isAnyFalsy`
### String Patterns [#string-patterns]
Test strings for prefixes, suffixes, and patterns:
* [does-start-with](./does-start-with/index.md) - String prefix/suffix predicates
* `doesStartWith`, `doesEndWith`
* `doesNotStartWith`, `doesNotEndWith`
* [is-like](./is-like/index.md) - Pattern matching with RegExp
* `isLike`, `isNotLike`
### Comparison [#comparison]
Numeric and lexicographic comparisons:
* [is-equal](./is-equal/index.md) - Comparison predicates
* `isEqual`, `isNotEqual`
* `isGreater`, `isGreaterEqual`
* `isLesser`, `isLesserEqual`
* [is-between](./is-between/index.md) - Range validation
* `isBetween`, `isNotBetween`
### Array Membership [#array-membership]
Test if values exist in arrays:
* [is-in](./is-in/index.md) - Array membership predicates
* `isIn`, `isNotIn`
### Colors [#colors]
Validate color format representations:
* [is-hex-color](./is-hex-color/index.md) - Color format predicates
* `isHexColor` - Hex color strings
* `isCssRgbaString` - CSS rgb/rgba strings
* `isCssRgbaObject` - React Aria RGBA objects
* `isRgba255Tuple` - deck.gl RGBA tuples
* `isValid255Channel` - Channel validation
### Geographic Coordinates [#geographic-coordinates]
Validate latitude, longitude, and bounding boxes:
* [is-latitude](./is-latitude/index.md) - Geographic predicates
* `isLatitude` - Latitude validation (-90 to 90)
* `isLongitude` - Longitude validation (-180 to 180)
* `isBbox` - Bounding box validation
### Web APIs [#web-apis]
Browser API instance checks:
* [is-worker](./is-worker/index.md) - Web Worker predicates
* `isWorker` - Worker instance check
* `isSharedWorker` - SharedWorker instance check
## Usage Patterns [#usage-patterns]
### Basic Usage [#basic-usage]
```typescript
import { isString, isNumber } from '@accelint/predicates';
isString('hello'); // true
isNumber(123); // true
```
### Array Filtering [#array-filtering]
```typescript
import { isString, isNothing } from '@accelint/predicates';
const mixed = ['hello', null, 42, 'world', undefined];
const strings = mixed.filter(isString);
// ['hello', 'world']
const defined = mixed.filter(v => !isNothing(v));
// ['hello', 42, 'world']
```
### Curried Predicates [#curried-predicates]
```typescript
import { isGreater, isIn } from '@accelint/predicates';
const isAdult = isGreater Equal(18);
isAdult(21); // true
isAdult(16); // false
const isValidStatus = isIn(['pending', 'approved', 'rejected']);
isValidStatus('pending'); // true
isValidStatus('unknown'); // false
```
### Type Narrowing [#type-narrowing]
```typescript
import { isNumber } from '@accelint/predicates';
function processValue(val: unknown) {
if (isNumber(val)) {
// TypeScript knows val is number here
return val.toFixed(2);
}
throw new Error('Expected number');
}
```
### Functional Composition [#functional-composition]
```typescript
import { isGreaterEqual, isLesserEqual } from '@accelint/predicates';
import { andFn } from '@accelint/core';
const isValidScore = andFn(
isGreaterEqual(0),
isLesserEqual(100)
);
isValidScore(50); // true
isValidScore(150); // false
```
## Design Principles [#design-principles]
### Pure Functions [#pure-functions]
All predicates are pure functions with no side effects:
```typescript
const isEven = (n: number) => n % 2 === 0;
isEven(4); // true (always returns same result for same input)
```
### Curried by Default [#curried-by-default]
Most predicates are curried for partial application:
```typescript
import { isGreater } from '@accelint/predicates';
// Create specialized predicates
const isAdult = isGreaterEqual(18);
const isRetired = isGreaterEqual(65);
ages.filter(isAdult);
ages.filter(isRetired);
```
### Type Safety [#type-safety]
Predicates provide runtime validation and TypeScript type guards:
```typescript
import { isNumber } from '@accelint/predicates';
function double(val: unknown): number {
if (!isNumber(val)) {
throw new Error('Expected number');
}
return val * 2; // TypeScript knows val is number
}
```
## Related Packages [#related-packages]
* [@accelint/core](../core/index.md) - Functional utilities for composition
* [@accelint/converters](../converters/index.md) - Type conversion utilities
* [@accelint/constants](../constants/index.md) - Shared constants and regex patterns
# isBbox (/docs/packages/predicates/is-bbox)
Validates bounding box as array of 4 finite numbers: `[minLon, minLat, maxLon, maxLat]`.
## Usage [#usage]
```typescript
import { isBbox } from '@accelint/predicates';
isBbox([-122.5, 37.7, -122.4, 37.8]); // true (San Francisco area)
isBbox([-180, -90, 180, 90]); // true (entire world)
isBbox([1, 2, 3]); // false (wrong length)
```
## Reference [#reference]
```typescript
function isBbox(bbox: unknown): boolean
```
Format: `[minLongitude, minLatitude, maxLongitude, maxLatitude]`
## Examples [#examples]
```typescript
import { isBbox } from '@accelint/predicates/is-bbox';
// Valid bounding boxes
isBbox([-180, -90, 180, 90]); // true (entire world)
isBbox([-122.5, 37.7, -122.4, 37.8]); // true (San Francisco area)
// Invalid bounding boxes
isBbox([1, 2, 3]); // false (wrong length)
isBbox([1, 2, 3, 'four']); // false (non-number)
isBbox([1, 2, NaN, 4]); // false (NaN not allowed)
isBbox(null); // false
```
### Example: Map bounds validation [#example-map-bounds-validation]
```typescript
import { isBbox } from '@accelint/predicates/is-bbox';
function setMapBounds(bounds: unknown) {
if (!isBbox(bounds)) {
throw new Error('Invalid bounding box format');
}
const [minLon, minLat, maxLon, maxLat] = bounds;
// Set map bounds...
}
setMapBounds([-122.5, 37.7, -122.4, 37.8]); // OK
setMapBounds([1, 2, 3]); // Error: Invalid bounding box format
```
## Real-World Example: Complete bounding box validation [#real-world-example-complete-bounding-box-validation]
```typescript
import { isLatitude } from '@accelint/predicates/is-latitude';
import { isLongitude } from '@accelint/predicates/is-longitude';
import { isBbox } from '@accelint/predicates/is-bbox';
function isValidBounds(bounds: unknown): bounds is [number, number, number, number] {
if (!isBbox(bounds)) {
return false;
}
const [minLon, minLat, maxLon, maxLat] = bounds;
return (
isLongitude(minLon) &&
isLatitude(minLat) &&
isLongitude(maxLon) &&
isLatitude(maxLat) &&
minLon < maxLon &&
minLat < maxLat
);
}
const sfBounds = [-122.5, 37.7, -122.4, 37.8];
isValidBounds(sfBounds); // true
```
> **Good to know:** `isBbox` currently validates array length and numeric types but does not validate coordinate ranges. Use `isLatitude` and `isLongitude` for range validation as shown in the example above.
## Related [#related]
* [isLatitude](./is-latitude) - Validates latitude values
* [isLongitude](./is-longitude) - Validates longitude values
* [isBetween](../is-between/index.md) - Range validation for numbers
* [isNumber](../is-number/index.md) - Type guard for numbers
* \[isFiniteNumber]\(../is-number/index.md#isfinite number) - Finite number validation
# isBetween (/docs/packages/predicates/is-between)
Creates a curried predicate function that determines if a number is between two bounds (inclusive).
## Usage [#usage]
```typescript
import { isBetween } from '@accelint/predicates';
const isValidScore = isBetween([0, 100]);
isValidScore(89); // true
isValidScore(150); // false
isValidScore(0); // true (inclusive)
isValidScore(100); // true (inclusive)
// Order doesn't matter
const isInRange = isBetween([100, 0]);
isInRange(50); // true
```
## Reference [#reference]
```typescript
function isBetween(bounds: [number, number]): (value: number) => boolean
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ------------------ | -------------------------------------------------------------- |
| `bounds` | `[number, number]` | Tuple containing lower and upper bounds (order doesn't matter) |
### Returns [#returns]
Curried function that accepts a number and returns `true` if the number is between the bounds (inclusive), `false` otherwise.
## Examples [#examples]
### Example: Validating user input [#example-validating-user-input]
```typescript
import { isBetween } from '@accelint/predicates';
const isValidAge = isBetween([0, 120]);
const isValidPercentage = isBetween([0, 100]);
function validateInput(age: number, score: number): boolean {
return isValidAge(age) && isValidPercentage(score);
}
validateInput(25, 85); // true
validateInput(150, 85); // false
validateInput(25, 150); // false
```
### Example: Filtering arrays [#example-filtering-arrays]
```typescript
import { isBetween } from '@accelint/predicates';
const temperatures = [-5, 15, 25, 35, 45];
const comfortable = temperatures.filter(isBetween([18, 28]));
// [25]
```
### Example: Validating geographic coordinates (with other predicates) [#example-validating-geographic-coordinates-with-other-predicates]
```typescript
import { isBetween } from '@accelint/predicates';
const isValidLatitude = isBetween([-90, 90]);
const isValidLongitude = isBetween([-180, 180]);
function isValidCoordinate(lat: number, lon: number): boolean {
return isValidLatitude(lat) && isValidLongitude(lon);
}
isValidCoordinate(37.7749, -122.4194); // true (San Francisco)
isValidCoordinate(100, 200); // false
```
### Example: Range validation for sliders [#example-range-validation-for-sliders]
```typescript
import { isBetween } from '@accelint/predicates';
const isValidVolume = isBetween([0, 100]);
const isValidBrightness = isBetween([0, 100]);
function updateSettings(volume: number, brightness: number) {
if (!isValidVolume(volume)) {
throw new Error(`Volume must be between 0 and 100, got ${volume}`);
}
if (!isValidBrightness(brightness)) {
throw new Error(`Brightness must be between 0 and 100, got ${brightness}`);
}
// Update settings...
}
```
> **Good to know:** The bounds are automatically sorted, so `isBetween([100, 0])` and `isBetween([0, 100])` are equivalent. The check is inclusive on both ends (`>=` lower and `<=` upper).
## Related [#related]
* [isNotBetween](../is-not-between/index.md) - Opposite check: value is outside the range
* [isGreater](../is-greater/index.md) - Check if value is greater than threshold
* [isLesser](../is-lesser/index.md) - Check if value is less than threshold
* [isGreaterEqual](../is-greater-equal/index.md) - Check if value is greater than or equal to threshold
* [isLesserEqual](../is-lesser-equal/index.md) - Check if value is less than or equal to threshold
# isCssRgbaObject (/docs/packages/predicates/is-css-rgba-object)
Validates CSS-style RGBA color object (React Aria Components format).
## Usage [#usage]
```typescript
import { isCssRgbaObject } from '@accelint/predicates/is-css-rgba-object';
isCssRgbaObject({ r: 255, g: 128, b: 64, a: 1 }); // true
isCssRgbaObject({ r: 255, g: 128, b: 64, a: 0.5 }); // true
isCssRgbaObject({ r: 255, g: 128, b: 64 }); // false (missing alpha)
isCssRgbaObject([255, 128, 64, 255]); // false (array, not object)
isCssRgbaObject({ r: 256, g: 128, b: 64, a: 1 }); // false (r out of range)
```
## Reference [#reference]
```typescript
type CssRgbaObject = {
readonly r: number; // 0-255
readonly g: number; // 0-255
readonly b: number; // 0-255
readonly a: number; // 0-1
};
function isCssRgbaObject(value: unknown): value is CssRgbaObject
```
RGB channels: 0-255, Alpha channel: 0-1
## Examples [#examples]
```typescript
import { isCssRgbaObject } from '@accelint/predicates/is-css-rgba-object';
// Valid RGBA objects
isCssRgbaObject({ r: 255, g: 128, b: 64, a: 1 }); // true
isCssRgbaObject({ r: 255, g: 128, b: 64, a: 0.5 }); // true
isCssRgbaObject({ r: 0, g: 0, b: 0, a: 0 }); // true
// Missing properties
isCssRgbaObject({ r: 255, g: 128, b: 64 }); // false (missing alpha)
isCssRgbaObject({ r: 255, g: 128, a: 1 }); // false (missing blue)
// Wrong types
isCssRgbaObject([255, 128, 64, 1]); // false (array, not object)
isCssRgbaObject('rgba(255, 128, 64, 1)'); // false (string, not object)
// Out of range values
isCssRgbaObject({ r: 256, g: 128, b: 64, a: 1 }); // false (r > 255)
isCssRgbaObject({ r: -1, g: 128, b: 64, a: 1 }); // false (r < 0)
isCssRgbaObject({ r: 255, g: 128, b: 64, a: 2 }); // false (a > 1)
isCssRgbaObject({ r: 255, g: 128, b: 64, a: -0.1 }); // false (a < 0)
// Extra properties are allowed
isCssRgbaObject({ r: 255, g: 128, b: 64, a: 1, format: 'css' }); // true
```
## Real-World Example: React Aria ColorPicker integration [#real-world-example-react-aria-colorpicker-integration]
```typescript
import { isCssRgbaObject } from '@accelint/predicates/is-css-rgba-object';
import type { Color } from 'react-aria-components';
function normalizeColorValue(color: unknown): CssRgbaObject {
if (isCssRgbaObject(color)) {
return color;
}
throw new Error('Invalid color: expected CssRgbaObject format');
}
function ColorDisplay({ value }: { value: unknown }) {
const color = normalizeColorValue(value);
return (
<div style={{
backgroundColor: `rgba(${color.r}, ${color.g}, ${color.b}, ${color.a})`
}}>
R: {color.r}, G: {color.g}, B: {color.b}, A: {color.a}
</div>
);
}
```
> **Good to know:** `isCssRgbaObject` uses alpha 0-1 (CSS standard), while `isRgba255Tuple` uses alpha 0-255 (deck.gl format). This matches React Aria Components conventions.
## Related [#related]
* [isRgba255Tuple](./is-rgba-255-tuple) - Type guard for RGBA tuples (alpha 0-255)
* [isHexColor](./is-hex-color) - Type guard for hex color strings
* [isCssRgbaString](./is-css-rgba-string) - Type guard for CSS rgb/rgba strings
* [isValid255Channel](./is-valid-255-channel) - Validate individual color channels
* [isObject](./is-object) - Type guard for objects
# isCssRgbaString (/docs/packages/predicates/is-css-rgba-string)
Validates CSS rgb/rgba string format (legacy and modern syntax).
## Usage [#usage]
```typescript
import { isCssRgbaString } from '@accelint/predicates/is-css-rgba-string';
// Legacy syntax
isCssRgbaString('rgba(255, 128, 64, 0.5)'); // true
isCssRgbaString('rgb(255, 128, 64)'); // true
// Modern syntax (CSS Color Module Level 4)
isCssRgbaString('rgb(255 128 64 / 50%)'); // true
isCssRgbaString('rgb(255 128 64)'); // true
isCssRgbaString('#FF8040'); // false
```
## Reference [#reference]
```typescript
function isCssRgbaString(value: unknown): value is string
```
Supports:
* Legacy: `rgb(255, 128, 64)`, `rgba(255, 128, 64, 0.5)`
* Modern: `rgb(255 128 64)`, `rgb(255 128 64 / 0.5)`
## Examples [#examples]
```typescript
import { isCssRgbaString } from '@accelint/predicates/is-css-rgba-string';
// Legacy comma-separated syntax
isCssRgbaString('rgb(255, 128, 64)'); // true
isCssRgbaString('rgba(255, 128, 64, 0.5)'); // true
isCssRgbaString('rgba(255, 128, 64, 1)'); // true
// Modern space-separated syntax (CSS Color Module Level 4)
isCssRgbaString('rgb(255 128 64)'); // true
isCssRgbaString('rgb(255 128 64 / 0.5)'); // true
isCssRgbaString('rgb(255 128 64 / 50%)'); // true
// Whitespace variations
isCssRgbaString('rgb( 255 , 128 , 64 )'); // true
isCssRgbaString('rgb(255 128 64)'); // true
// Invalid formats
isCssRgbaString('#FF8040'); // false
isCssRgbaString('hsl(30, 100%, 50%)'); // false
isCssRgbaString('255, 128, 64'); // false (missing rgb())
```
## Real-World Example: CSS color string parser [#real-world-example-css-color-string-parser]
```typescript
import { isCssRgbaString } from '@accelint/predicates/is-css-rgba-string';
function parseCssColor(value: unknown): { r: number; g: number; b: number; a: number } | null {
if (!isCssRgbaString(value)) {
return null;
}
// Extract numbers from the CSS string
const match = value.match(/rgba?\(([^)]+)\)/);
if (!match) return null;
const parts = match[1].split(/[,\s/]+/).map(Number);
return {
r: parts[0] ?? 0,
g: parts[1] ?? 0,
b: parts[2] ?? 0,
a: parts[3] ?? 1
};
}
parseCssColor('rgba(255, 128, 64, 0.5)'); // { r: 255, g: 128, b: 64, a: 0.5 }
```
> **Good to know:** This predicate supports both legacy comma-separated and modern space-separated CSS color syntax.
## Related [#related]
* [isHexColor](./is-hex-color) - Type guard for hex color strings
* [isCssRgbaObject](./is-css-rgba-object) - Type guard for CSS RGBA objects
* [isRgba255Tuple](./is-rgba-255-tuple) - Type guard for RGBA tuples
* [isString](./is-string) - Type guard for strings
# isEqual (/docs/packages/predicates/is-equal)
Creates a predicate that determines if a value is strictly equal to a reference value.
## Reference [#reference]
```typescript
function isEqual<T>(reference: T): (value: T) => boolean
```
## Examples [#examples]
```typescript
import { isEqual } from '@accelint/predicates';
const isZero = isEqual(0);
isZero(0); // true
isZero('0'); // false (strict equality)
// Array filtering
const numbers = [1, 2, 3, 2, 4];
const twos = numbers.filter(isEqual(2)); // [2, 2]
```
> **Good to know:** This uses strict equality (`===`). For value equality of objects, use a deep equality function instead.
## Related [#related]
* [isNotEqual](./is-not-equal) - Check if value is not equal to reference
* [isGreater](./is-greater) - Check if value is greater than threshold
* [isGreaterEqual](./is-greater-equal) - Check if value is greater than or equal to threshold
* [isLesser](./is-lesser) - Check if value is less than threshold
* [isLesserEqual](./is-lesser-equal) - Check if value is less than or equal to threshold
* [isIn](./is-in) - Check if value exists in an array
* [isNotIn](./is-not-in) - Check if value doesn't exist in an array
# isGreaterEqual (/docs/packages/predicates/is-greater-equal)
Creates a predicate that determines if a value is greater than or equal to a threshold.
## Reference [#reference]
```typescript
function isGreaterEqual<T extends number | string>(threshold: T): (value: T) => boolean
```
## Examples [#examples]
```typescript
import { isGreaterEqual } from '@accelint/predicates';
const isAtLeast18 = isGreaterEqual(18);
isAtLeast18(21); // true
isAtLeast18(18); // true (inclusive)
isAtLeast18(16); // false
// Passing grade filter
const scores = [45, 78, 92, 65, 88];
const passing = scores.filter(isGreaterEqual(70)); // [78, 92, 88]
```
### Combined Example: Range Validation [#combined-example-range-validation]
```typescript
import { isGreaterEqual, isLesserEqual } from '@accelint/predicates';
import { andFn } from '@accelint/core';
// Create a range validator by composing predicates
const isBetween0And100 = andFn(
isGreaterEqual(0),
isLesserEqual(100)
);
isBetween0And100(50); // true
isBetween0And100(150); // false
isBetween0And100(-10); // false
```
> **Good to know:** The threshold is inclusive. Use `isGreater` for exclusive comparison.
## Related [#related]
* [isGreater](./is-greater) - Check if value is greater than threshold (exclusive)
* [isLesserEqual](./is-lesser-equal) - Check if value is less than or equal to threshold
* [isLesser](./is-lesser) - Check if value is less than threshold
* [isEqual](./is-equal) - Check if value is equal to reference
* [isNotEqual](./is-not-equal) - Check if value is not equal to reference
* [isBetween](./is-between) - Check if value is in a range (inclusive)
# isGreater (/docs/packages/predicates/is-greater)
Creates a predicate that determines if a value is greater than a threshold.
## Reference [#reference]
```typescript
function isGreater<T extends number | string>(threshold: T): (value: T) => boolean
```
## Examples [#examples]
```typescript
import { isGreater } from '@accelint/predicates';
const isGreaterThan10 = isGreater(10);
isGreaterThan10(15); // true
isGreaterThan10(5); // false
// String comparison (lexicographic)
const isAfterM = isGreater('M');
isAfterM('Z'); // true
isAfterM('A'); // false
// Array filtering
const numbers = [1, 5, 10, 15, 20];
const greaterThan10 = numbers.filter(isGreater(10)); // [15, 20]
```
> **Good to know:** String comparisons use lexicographic ordering. For case-insensitive comparisons, convert strings to the same case before applying predicates.
## Related [#related]
* [isGreaterEqual](./is-greater-equal) - Check if value is greater than or equal to threshold (inclusive)
* [isLesser](./is-lesser) - Check if value is less than threshold
* [isLesserEqual](./is-lesser-equal) - Check if value is less than or equal to threshold
* [isEqual](./is-equal) - Check if value is equal to reference
* [isNotEqual](./is-not-equal) - Check if value is not equal to reference
* [isBetween](./is-between) - Check if value is in a range (inclusive)
# isHexColor (/docs/packages/predicates/is-hex-color)
Validates hex color strings with optional alpha channel.
## Usage [#usage]
```typescript
import { isHexColor } from '@accelint/predicates/is-hex-color';
isHexColor('#FF8040'); // true
isHexColor('#F84'); // true
isHexColor('FF8040'); // true (hash optional)
isHexColor('#FF8040FF'); // true (with alpha)
isHexColor('rgb(255, 128, 64)'); // false
```
## Reference [#reference]
```typescript
function isHexColor(value: unknown): value is string
```
Supports formats: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA` (hash optional)
## Examples [#examples]
```typescript
import { isHexColor } from '@accelint/predicates/is-hex-color';
// Standard 6-digit hex
isHexColor('#FF8040'); // true
isHexColor('FF8040'); // true (hash optional)
// Short 3-digit hex
isHexColor('#F84'); // true
isHexColor('F84'); // true
// With alpha channel
isHexColor('#FF8040FF'); // true (8-digit)
isHexColor('#F84F'); // true (4-digit)
// Invalid formats
isHexColor('rgb(255, 128, 64)'); // false
isHexColor('#GG8040'); // false (invalid hex chars)
isHexColor('#FF804'); // false (wrong length)
```
## Real-World Example: Accepting multiple color formats [#real-world-example-accepting-multiple-color-formats]
```typescript
import { isHexColor } from '@accelint/predicates/is-hex-color';
import { isCssRgbaString } from '@accelint/predicates/is-css-rgba-string';
function parseColorInput(color: unknown): string {
if (isHexColor(color)) {
// Normalize to include hash
return color.startsWith('#') ? color : `#${color}`;
}
if (isCssRgbaString(color)) {
// Convert CSS rgba to hex
// Implementation omitted for brevity
}
throw new Error('Invalid color format');
}
```
> **Good to know:** The hash prefix is optional. Both `#FF8040` and `FF8040` are valid.
## Related [#related]
* [isCssRgbaString](./is-css-rgba-string) - Type guard for CSS rgb/rgba strings
* [isCssRgbaObject](./is-css-rgba-object) - Type guard for CSS RGBA objects
* [isRgba255Tuple](./is-rgba-255-tuple) - Type guard for RGBA tuples
* [isString](./is-string) - Type guard for strings
# isIn (/docs/packages/predicates/is-in)
Creates a predicate that determines if a value exists in a given array.
## Usage [#usage]
```typescript
import { isIn } from '@accelint/predicates';
const isValidStatus = isIn(['pending', 'approved', 'rejected']);
isValidStatus('pending'); // true
isValidStatus('unknown'); // false
```
## Reference [#reference]
```typescript
function isIn<T>(array: T[]): (value: T) => boolean
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ----- | ---------------------- |
| `array` | `T[]` | Array to search within |
### Returns [#returns]
Curried function that accepts a value and returns `true` if the value exists in the array (using strict equality).
## Examples [#examples]
### Example: Status validation [#example-status-validation]
```typescript
import { isIn } from '@accelint/predicates';
const VALID_STATUSES = ['draft', 'published', 'archived'];
const isValidStatus = isIn(VALID_STATUSES);
function validatePost(status: string): boolean {
return isValidStatus(status);
}
validatePost('published'); // true
validatePost('deleted'); // false
```
### Example: Permission checking [#example-permission-checking]
```typescript
import { isIn } from '@accelint/predicates';
const userPermissions = ['read', 'write', 'delete'];
const hasPermission = isIn(userPermissions);
hasPermission('read'); // true
hasPermission('admin'); // false
```
### Example: Filtering valid IDs [#example-filtering-valid-ids]
```typescript
import { isIn } from '@accelint/predicates';
const allowedIds = [101, 102, 103, 104];
const isAllowedId = isIn(allowedIds);
const requestIds = [101, 105, 102, 106];
const validRequests = requestIds.filter(isAllowedId);
// [101, 102]
```
## Real-World Example: Role-based access control [#real-world-example-role-based-access-control]
```typescript
import { isIn, isNotIn } from '@accelint/predicates';
const ADMIN_ROLES = ['admin', 'super-admin'];
const RESTRICTED_ACTIONS = ['delete-user', 'modify-permissions'];
const isAdmin = isIn(ADMIN_ROLES);
const isNotRestricted = isNotIn(RESTRICTED_ACTIONS);
function canPerformAction(userRole: string, action: string): boolean {
if (isAdmin(userRole)) {
return true; // Admins can do anything
}
return isNotRestricted(action);
}
canPerformAction('admin', 'delete-user'); // true
canPerformAction('user', 'view-dashboard'); // true
canPerformAction('user', 'delete-user'); // false
```
> **Good to know:** This predicate uses `Array.prototype.includes()` internally, which uses strict equality (`===`). For deep equality or custom comparison logic, use a different approach or preprocess your data.
## Related [#related]
* [isNotIn](../is-not-in/index.md) - Inverse array membership predicate
* [isEqual](../is-equal/index.md) - Strict equality comparison
* [isNotEqual](../is-not-equal/index.md) - Strict inequality comparison
* [isBetween](../is-between/index.md) - Range membership for numbers
* [isLike](../is-like/index.md) - Pattern matching with RegExp
# isLatitude (/docs/packages/predicates/is-latitude)
Validates latitude values between -90 and 90 degrees.
## Usage [#usage]
```typescript
import { isLatitude } from '@accelint/predicates';
isLatitude(37.7749); // true (San Francisco)
isLatitude(-90); // true (South Pole)
isLatitude(100); // false (out of range)
```
## Reference [#reference]
```typescript
function isLatitude(val: unknown): boolean
```
Valid range: -90 to 90 (inclusive)
## Examples [#examples]
```typescript
import { isLatitude } from '@accelint/predicates/is-latitude';
isLatitude(-90); // true (South Pole)
isLatitude(0); // true (Equator)
isLatitude(90); // true (North Pole)
isLatitude(37.7749); // true (San Francisco)
isLatitude(-100); // false (out of range)
isLatitude(NaN); // false
```
### Example: Coordinate validation [#example-coordinate-validation]
```typescript
import { isLatitude } from '@accelint/predicates/is-latitude';
interface Coordinate {
lat: number;
lon: number;
}
function validateLatitude(coord: Coordinate): boolean {
return isLatitude(coord.lat);
}
validateLatitude({ lat: 37.7749, lon: -122.4194 }); // true
validateLatitude({ lat: 100, lon: -122.4194 }); // false
```
## Real-World Example: Location validation [#real-world-example-location-validation]
```typescript
import { isLatitude } from '@accelint/predicates/is-latitude';
import { isLongitude } from '@accelint/predicates/is-longitude';
interface Location {
latitude: number;
longitude: number;
}
function isValidLocation(loc: Location): boolean {
return isLatitude(loc.latitude) && isLongitude(loc.longitude);
}
const sanFrancisco: Location = { latitude: 37.7749, longitude: -122.4194 };
isValidLocation(sanFrancisco); // true
```
## Related [#related]
* [isLongitude](./is-longitude) - Validates longitude values
* [isBbox](./is-bbox) - Validates bounding box arrays
* [isBetween](../is-between/index.md) - Range validation for numbers
* [isNumber](../is-number/index.md) - Type guard for numbers
# isLesserEqual (/docs/packages/predicates/is-lesser-equal)
Creates a predicate that determines if a value is less than or equal to a threshold.
## Reference [#reference]
```typescript
function isLesserEqual<T extends number | string>(threshold: T): (value: T) => boolean
```
## Examples [#examples]
```typescript
import { isLesserEqual } from '@accelint/predicates';
const isAtMost100 = isLesserEqual(100);
isAtMost100(50); // true
isAtMost100(100); // true (inclusive)
isAtMost100(150); // false
// Age filtering
const ages = [16, 18, 21, 25, 30];
const underAge = ages.filter(isLesserEqual(20)); // [16, 18]
```
> **Good to know:** The threshold is inclusive. Use `isLesser` for exclusive comparison.
## Related [#related]
* [isLesser](./is-lesser) - Check if value is less than threshold (exclusive)
* [isGreaterEqual](./is-greater-equal) - Check if value is greater than or equal to threshold
* [isGreater](./is-greater) - Check if value is greater than threshold
* [isEqual](./is-equal) - Check if value is equal to reference
* [isNotEqual](./is-not-equal) - Check if value is not equal to reference
* [isBetween](./is-between) - Check if value is in a range (inclusive)
# isLesser (/docs/packages/predicates/is-lesser)
Creates a predicate that determines if a value is less than a threshold.
## Reference [#reference]
```typescript
function isLesser<T extends number | string>(threshold: T): (value: T) => boolean
```
## Examples [#examples]
```typescript
import { isLesser } from '@accelint/predicates';
const isBelowLimit = isLesser(100);
isBelowLimit(50); // true
isBelowLimit(150); // false
// Temperature filtering
const temperatures = [15, 25, 35, 45];
const cool = temperatures.filter(isLesser(30)); // [15, 25]
```
> **Good to know:** String comparisons use lexicographic ordering. For case-insensitive comparisons, convert strings to the same case before applying predicates.
## Related [#related]
* [isLesserEqual](./is-lesser-equal) - Check if value is less than or equal to threshold (inclusive)
* [isGreater](./is-greater) - Check if value is greater than threshold
* [isGreaterEqual](./is-greater-equal) - Check if value is greater than or equal to threshold
* [isEqual](./is-equal) - Check if value is equal to reference
* [isNotEqual](./is-not-equal) - Check if value is not equal to reference
* [isBetween](./is-between) - Check if value is in a range (inclusive)
# isLike (/docs/packages/predicates/is-like)
Creates a predicate that determines if a string matches a given pattern or regular expression.
## Usage [#usage]
```typescript
import { isLike } from '@accelint/predicates';
const isEmail = isLike(/^[^\s@]+@[^\s@]+\.[^\s@]+$/);
isEmail('user@example.com'); // true
isEmail('invalid-email'); // false
```
## Reference [#reference]
```typescript
function isLike(pattern: string | RegExp): (input: string) => boolean
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ------------------ | -------------------------------------------------- |
| `pattern` | `string \| RegExp` | Pattern to match (strings are converted to RegExp) |
### Returns [#returns]
Curried function that accepts a string and returns `true` if it matches the pattern.
## Examples [#examples]
### Example: Email validation [#example-email-validation]
```typescript
import { isLike } from '@accelint/predicates';
const isEmail = isLike(/^[^\s@]+@[^\s@]+\.[^\s@]+$/);
isEmail('user@example.com'); // true
isEmail('invalid-email'); // false
isEmail('user@domain.co.uk'); // true
```
### Example: File extension filtering [#example-file-extension-filtering]
```typescript
import { isLike } from '@accelint/predicates';
const isScriptFile = isLike(/\.(js|ts|jsx|tsx)$/);
const files = ['app.js', 'style.css', 'main.ts', 'README.md'];
const scripts = files.filter(isScriptFile);
// ['app.js', 'main.ts']
```
### Example: URL validation [#example-url-validation]
```typescript
import { isLike } from '@accelint/predicates';
const isHttpUrl = isLike(/^https?:\/\/.+/);
isHttpUrl('https://example.com'); // true
isHttpUrl('http://example.com'); // true
isHttpUrl('ftp://example.com'); // false
```
### Example: Phone number pattern [#example-phone-number-pattern]
```typescript
import { isLike } from '@accelint/predicates';
const isPhoneNumber = isLike(/^\d{3}-\d{3}-\d{4}$/);
isPhoneNumber('555-123-4567'); // true
isPhoneNumber('555.123.4567'); // false
isPhoneNumber('5551234567'); // false
```
### Example: Using string patterns [#example-using-string-patterns]
```typescript
import { isLike } from '@accelint/predicates';
// String patterns are converted to RegExp
const hasNumbers = isLike('[0-9]');
hasNumbers('abc123'); // true
hasNumbers('abcdef'); // false
```
> **Good to know:** When passing strings as patterns, they are converted to `RegExp` using `new RegExp(pattern)`. Use `RegExp` objects directly for better control over flags like case-insensitivity (`/pattern/i`).
## Related [#related]
* [isNotLike](../is-not-like/index.md) - Inverted pattern matching predicate
* [doesStartWith](../does-start-with/index.md) - Check string prefix
* [doesEndWith](../does-end-with/index.md) - Check string suffix
* [isString](../is-string/index.md) - Type guard for strings
* [isIn](../is-in/index.md) - Array membership check
# isLongitude (/docs/packages/predicates/is-longitude)
Validates longitude values between -180 and 180 degrees.
## Usage [#usage]
```typescript
import { isLongitude } from '@accelint/predicates';
isLongitude(-122.4194); // true (San Francisco)
isLongitude(0); // true (Prime Meridian)
isLongitude(200); // false (out of range)
```
## Reference [#reference]
```typescript
function isLongitude(val: unknown): boolean
```
Valid range: -180 to 180 (inclusive)
## Examples [#examples]
```typescript
import { isLongitude } from '@accelint/predicates/is-longitude';
isLongitude(-180); // true (International Date Line, west)
isLongitude(0); // true (Prime Meridian)
isLongitude(180); // true (International Date Line, east)
isLongitude(-122.4194); // true (San Francisco)
isLongitude(-190); // false (out of range)
isLongitude(NaN); // false
```
### Example: Coordinate validation [#example-coordinate-validation]
```typescript
import { isLongitude } from '@accelint/predicates/is-longitude';
interface Coordinate {
lat: number;
lon: number;
}
function validateLongitude(coord: Coordinate): boolean {
return isLongitude(coord.lon);
}
validateLongitude({ lat: 37.7749, lon: -122.4194 }); // true
validateLongitude({ lat: 37.7749, lon: 200 }); // false
```
## Real-World Example: Location validation [#real-world-example-location-validation]
```typescript
import { isLatitude } from '@accelint/predicates/is-latitude';
import { isLongitude } from '@accelint/predicates/is-longitude';
interface Location {
latitude: number;
longitude: number;
}
function isValidLocation(loc: Location): boolean {
return isLatitude(loc.latitude) && isLongitude(loc.longitude);
}
const sanFrancisco: Location = { latitude: 37.7749, longitude: -122.4194 };
isValidLocation(sanFrancisco); // true
```
## Related [#related]
* [isLatitude](./is-latitude) - Validates latitude values
* [isBbox](./is-bbox) - Validates bounding box arrays
* [isBetween](../is-between/index.md) - Range validation for numbers
* [isNumber](../is-number/index.md) - Type guard for numbers
# isNotBetween (/docs/packages/predicates/is-not-between)
Creates a curried predicate function that determines if a number is not between two bounds (exclusive of range).
## Usage [#usage]
```typescript
import { isNotBetween } from '@accelint/predicates';
const isOutOfRange = isNotBetween([10, 90]);
isOutOfRange(5); // true (below range)
isOutOfRange(95); // true (above range)
isOutOfRange(50); // false (within range)
isOutOfRange(10); // false (on boundary, inclusive)
// Order doesn't matter
const isOutlier = isNotBetween([90, 10]);
isOutlier(5); // true
```
## Reference [#reference]
```typescript
function isNotBetween(bounds: [number, number]): (value: number) => boolean
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ------------------ | -------------------------------------------------------------- |
| `bounds` | `[number, number]` | Tuple containing lower and upper bounds (order doesn't matter) |
### Returns [#returns]
Curried function that accepts a number and returns `true` if the number is not between the bounds, `false` otherwise.
### Implementation [#implementation]
This predicate is implemented as the negation of `isBetween` using functional composition:
```typescript
import { compose, not } from '@accelint/core';
import { isBetween } from '../is-between';
export const isNotBetween = (bounds: [number, number]) =>
compose(not, isBetween(bounds));
```
## Examples [#examples]
### Example: Detecting outliers [#example-detecting-outliers]
```typescript
import { isNotBetween } from '@accelint/predicates';
const scores = [5, 25, 75, 95, 105];
const outliers = scores.filter(isNotBetween([0, 100]));
// [105]
```
### Example: Validating exclusion zones [#example-validating-exclusion-zones]
```typescript
import { isNotBetween } from '@accelint/predicates';
const isOutsideRestrictedZone = isNotBetween([100, 200]);
function canAccessArea(position: number): boolean {
return isOutsideRestrictedZone(position);
}
canAccessArea(50); // true (before restricted zone)
canAccessArea(150); // false (inside restricted zone)
canAccessArea(250); // true (after restricted zone)
```
### Example: Filtering invalid data [#example-filtering-invalid-data]
```typescript
import { isNotBetween } from '@accelint/predicates';
const temperatures = [-100, -5, 15, 25, 35, 150];
const normalRange = isNotBetween([-50, 50]);
const abnormalReadings = temperatures.filter(normalRange);
// [-100, 150]
```
### Example: Business rule validation [#example-business-rule-validation]
```typescript
import { isNotBetween } from '@accelint/predicates';
const isWeekend = isNotBetween([1, 5]); // Mon=1, Fri=5
function isBusinessDay(dayOfWeek: number): boolean {
// Returns false for Sat (6) and Sun (0)
return !isWeekend(dayOfWeek);
}
isBusinessDay(3); // true (Wednesday)
isBusinessDay(6); // false (Saturday)
```
> **Good to know:** Like `isBetween`, the bounds are automatically sorted, so order doesn't matter. The check is inclusive on both ends, meaning values exactly on the boundaries are considered "between" and will return `false`.
## Related [#related]
* [isBetween](../is-between/index.md) - Opposite check: value is within the range
* [isGreater](../is-greater/index.md) - Check if value is greater than threshold
* [isLesser](../is-lesser/index.md) - Check if value is less than threshold
* [isNotEqual](../is-not-equal/index.md) - Strict inequality comparison
* [isNotIn](../is-not-in/index.md) - Array exclusion predicate
# isNotEqual (/docs/packages/predicates/is-not-equal)
Creates a predicate that determines if a value is **not** strictly equal to a reference value.
## Reference [#reference]
```typescript
function isNotEqual<T>(reference: T): (value: T) => boolean
```
## Examples [#examples]
```typescript
import { isNotEqual } from '@accelint/predicates';
const isNotZero = isNotEqual(0);
isNotZero(5); // true
isNotZero(0); // false
// Removing null values
const values = [1, null, 2, null, 3];
const nonNull = values.filter(isNotEqual(null)); // [1, 2, 3]
```
> **Good to know:** This uses strict inequality (`!==`). For filtering arrays, this is more efficient than using `!isEqual(x)`.
## Related [#related]
* [isEqual](./is-equal) - Check if value is equal to reference
* [isGreater](./is-greater) - Check if value is greater than threshold
* [isGreaterEqual](./is-greater-equal) - Check if value is greater than or equal to threshold
* [isLesser](./is-lesser) - Check if value is less than threshold
* [isLesserEqual](./is-lesser-equal) - Check if value is less than or equal to threshold
* [isIn](./is-in) - Check if value exists in an array
* [isNotIn](./is-not-in) - Check if value doesn't exist in an array
# isNotIn (/docs/packages/predicates/is-not-in)
Creates a predicate that determines if a value does **not** exist in a given array.
## Usage [#usage]
```typescript
import { isNotIn } from '@accelint/predicates';
const isInvalidStatus = isNotIn(['pending', 'approved', 'rejected']);
isInvalidStatus('unknown'); // true
isInvalidStatus('pending'); // false
```
## Reference [#reference]
```typescript
function isNotIn<T>(array: T[]): (value: T) => boolean
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ----- | ---------------------- |
| `array` | `T[]` | Array to search within |
### Returns [#returns]
Curried function that accepts a value and returns `true` if the value does **not** exist in the array.
## Examples [#examples]
### Example: Filtering unauthorized requests [#example-filtering-unauthorized-requests]
```typescript
import { isNotIn } from '@accelint/predicates';
const blockedUsers = [101, 205, 399];
const isNotBlocked = isNotIn(blockedUsers);
const incomingRequests = [101, 102, 205, 300];
const allowed = incomingRequests.filter(isNotBlocked);
// [102, 300]
```
### Example: Excluding reserved keywords [#example-excluding-reserved-keywords]
```typescript
import { isNotIn } from '@accelint/predicates';
const RESERVED_WORDS = ['class', 'function', 'return', 'if', 'else'];
const isNotReserved = isNotIn(RESERVED_WORDS);
function isValidIdentifier(name: string): boolean {
return isNotReserved(name) && /^[a-zA-Z_]\w*$/.test(name);
}
isValidIdentifier('myVariable'); // true
isValidIdentifier('class'); // false
```
### Example: Finding new items [#example-finding-new-items]
```typescript
import { isNotIn } from '@accelint/predicates';
const existingIds = [1, 2, 3, 4, 5];
const isNewId = isNotIn(existingIds);
const incomingIds = [4, 5, 6, 7];
const newItems = incomingIds.filter(isNewId);
// [6, 7]
```
## Real-World Example: Role-based access control [#real-world-example-role-based-access-control]
```typescript
import { isIn, isNotIn } from '@accelint/predicates';
const ADMIN_ROLES = ['admin', 'super-admin'];
const RESTRICTED_ACTIONS = ['delete-user', 'modify-permissions'];
const isAdmin = isIn(ADMIN_ROLES);
const isNotRestricted = isNotIn(RESTRICTED_ACTIONS);
function canPerformAction(userRole: string, action: string): boolean {
if (isAdmin(userRole)) {
return true; // Admins can do anything
}
return isNotRestricted(action);
}
canPerformAction('admin', 'delete-user'); // true
canPerformAction('user', 'view-dashboard'); // true
canPerformAction('user', 'delete-user'); // false
```
> **Good to know:** This predicate uses `Array.prototype.includes()` internally, which uses strict equality (`===`). For deep equality or custom comparison logic, use a different approach or preprocess your data.
## Related [#related]
* [isIn](../is-in/index.md) - Array membership predicate
* [isEqual](../is-equal/index.md) - Strict equality comparison
* [isNotEqual](../is-not-equal/index.md) - Strict inequality comparison
* [isBetween](../is-between/index.md) - Range membership for numbers
* [isNotLike](../is-not-like/index.md) - Pattern non-matching with RegExp
# isNotLike (/docs/packages/predicates/is-not-like)
Creates a predicate that determines if a string does **not** match a given pattern or regular expression.
## Usage [#usage]
```typescript
import { isNotLike } from '@accelint/predicates';
const isNotEmail = isNotLike(/^[^\s@]+@[^\s@]+\.[^\s@]+$/);
isNotEmail('invalid-email'); // true
isNotEmail('user@example.com'); // false
```
## Reference [#reference]
```typescript
function isNotLike(pattern: string | RegExp): (input: string) => boolean
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ------------------ | -------------------------------------------------- |
| `pattern` | `string \| RegExp` | Pattern to match (strings are converted to RegExp) |
### Returns [#returns]
Curried function that accepts a string and returns `true` if it does **not** match the pattern.
## Examples [#examples]
### Example: Excluding test files [#example-excluding-test-files]
```typescript
import { isNotLike } from '@accelint/predicates';
const isNotTestFile = isNotLike(/\.test\.(js|ts)$/);
const files = ['app.js', 'app.test.js', 'utils.ts', 'utils.test.ts'];
const sourceFiles = files.filter(isNotTestFile);
// ['app.js', 'utils.ts']
```
### Example: Filtering non-numeric strings [#example-filtering-non-numeric-strings]
```typescript
import { isNotLike } from '@accelint/predicates';
const hasNoNumbers = isNotLike(/\d/);
const items = ['abc', '123', 'def', 'a1b2'];
const textOnly = items.filter(hasNoNumbers);
// ['abc', 'def']
```
### Example: Excluding special characters [#example-excluding-special-characters]
```typescript
import { isNotLike } from '@accelint/predicates';
const hasNoSpecialChars = isNotLike(/[^a-zA-Z0-9]/);
function isValidUsername(name: string): boolean {
return hasNoSpecialChars(name) && name.length >= 3;
}
isValidUsername('john123'); // true
isValidUsername('john@123'); // false
isValidUsername('jd'); // false
```
### Example: File processing pipeline [#example-file-processing-pipeline]
```typescript
import { isLike, isNotLike } from '@accelint/predicates';
const isSourceFile = isLike(/\.(ts|tsx)$/);
const isNotTestFile = isNotLike(/\.(test|spec)\.(ts|tsx)$/);
const isNotConfigFile = isNotLike(/^(tsconfig|vite\.config|vitest\.config)/);
function getSourceFiles(files: string[]): string[] {
return files
.filter(isSourceFile)
.filter(isNotTestFile)
.filter(isNotConfigFile);
}
const allFiles = [
'src/app.ts',
'src/app.test.ts',
'src/utils.ts',
'tsconfig.json',
'vite.config.ts'
];
const sources = getSourceFiles(allFiles);
// ['src/app.ts', 'src/utils.ts']
```
> **Good to know:** When passing strings as patterns, they are converted to `RegExp` using `new RegExp(pattern)`. Use `RegExp` objects directly for better control over flags like case-insensitivity (`/pattern/i`).
## Related [#related]
* [isLike](../is-like/index.md) - Pattern matching predicate
* [isNotIn](../is-not-in/index.md) - Array exclusion check
* [doesStartWith](../does-start-with/index.md) - Check string prefix
* [doesEndWith](../does-end-with/index.md) - Check string suffix
* [isString](../is-string/index.md) - Type guard for strings
# isNothing (/docs/packages/predicates/is-nothing)
## Usage [#usage]
```typescript
import { isNothing } from '@accelint/predicates/is-nothing';
isNothing(null); // true
isNothing(undefined); // true
isNothing(0); // false
isNothing(''); // false
isNothing(false); // false
```
## Reference [#reference]
```typescript
function isNothing(val: unknown): boolean
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | --------- | -------------- |
| `val` | `unknown` | Value to check |
### Returns [#returns]
Returns `true` if the value is `null` or `undefined`, `false` otherwise.
## Examples [#examples]
### Example: Early return for missing values [#example-early-return-for-missing-values]
```typescript
import { isNothing } from '@accelint/predicates/is-nothing';
function processUser(user: User | null | undefined) {
if (isNothing(user)) {
console.log('No user provided');
return;
}
// Safe to use user here
console.log(user.name);
}
```
### Example: Filtering out null/undefined from arrays [#example-filtering-out-nullundefined-from-arrays]
```typescript
import { isNothing } from '@accelint/predicates/is-nothing';
const values = [1, null, 2, undefined, 3, 0, false];
const notNull = values.filter(v => !isNothing(v));
// [1, 2, 3, 0, false]
```
### Example: Validating required fields [#example-validating-required-fields]
```typescript
import { isNothing } from '@accelint/predicates/is-nothing';
interface FormData {
name?: string;
email?: string;
phone?: string;
}
function validateRequired(data: FormData): boolean {
return !isNothing(data.name) && !isNothing(data.email);
}
validateRequired({ name: 'John', email: 'john@example.com' }); // true
validateRequired({ name: 'John' }); // false
validateRequired({ email: 'john@example.com' }); // false
```
### Example: Default value assignment [#example-default-value-assignment]
```typescript
import { isNothing } from '@accelint/predicates/is-nothing';
function getConfigValue(value: string | null | undefined): string {
if (isNothing(value)) {
return 'default-config';
}
return value;
}
getConfigValue(null); // "default-config"
getConfigValue(undefined); // "default-config"
getConfigValue('custom'); // "custom"
getConfigValue(''); // "" (empty string is not nothing)
```
> **Good to know:** Uses loose equality (`==`) rather than strict equality (`===`), so it matches both `null` and `undefined` with a single comparison. This is one of the rare cases where loose equality is preferred for brevity.
## Related [#related]
* [isSomething](../is-something/index.md) - Opposite check: value is not null or undefined
* [isString](../is-string/index.md) - Check if value is a string
* [isNumber](../is-number/index.md) - Check if value is a number
# Boolean Predicates (/docs/packages/predicates/is-noyes)
## Usage [#usage]
```typescript
import {
isTrue,
isFalse,
isYes,
isNo,
isOn,
isOff,
isAnyTruthy,
isAnyFalsy
} from '@accelint/predicates/is-noyes';
isTrue(1); // true
isTrue('true'); // true
isYes('yes'); // true
isOn('on'); // true
isFalse(0); // true
isFalse('false'); // true
isNo('no'); // true
isOff('off'); // true
isAnyTruthy('yes'); // true
isAnyFalsy('off'); // true
```
## Value Lists [#value-lists]
### True Values [#true-values]
`['1', 'true']`
### False Values [#false-values]
`['', '0', 'false', 'nan', 'null', 'undefined']`
### Yes Values [#yes-values]
`['y', 'yes', '1', 'true']`
### No Values [#no-values]
`['n', 'no', '', '0', 'false', 'nan', 'null', 'undefined']`
### On Values [#on-values]
`['on', '1', 'true']`
### Off Values [#off-values]
`['off', '', '0', 'false', 'nan', 'null', 'undefined']`
## isTrue [#istrue]
Tests if a value matches the true values list.
### Reference [#reference]
```typescript
function isTrue(val: unknown): boolean
```
### Examples [#examples]
```typescript
import { isTrue } from '@accelint/predicates/is-noyes';
isTrue(1); // true
isTrue('1'); // true
isTrue('true'); // true
isTrue('TRUE'); // true (case-insensitive)
isTrue(true); // true
isTrue(0); // false
isTrue('yes'); // false (use isYes for this)
```
## isFalse [#isfalse]
Tests if a value matches the false values list.
### Reference [#reference-1]
```typescript
function isFalse(val: unknown): boolean
```
### Examples [#examples-1]
```typescript
import { isFalse } from '@accelint/predicates/is-noyes';
isFalse(0); // true
isFalse('0'); // true
isFalse(''); // true
isFalse('false'); // true
isFalse('FALSE'); // true
isFalse('null'); // true
isFalse(1); // false
```
## isYes [#isyes]
Tests if a value matches the yes values list.
### Reference [#reference-2]
```typescript
function isYes(val: unknown): boolean
```
### Examples [#examples-2]
```typescript
import { isYes } from '@accelint/predicates/is-noyes';
isYes('yes'); // true
isYes('YES'); // true
isYes('y'); // true
isYes('Y'); // true
isYes(1); // true
isYes('true'); // true
isYes('no'); // false
```
## isNo [#isno]
Tests if a value matches the no values list.
### Reference [#reference-3]
```typescript
function isNo(val: unknown): boolean
```
### Examples [#examples-3]
```typescript
import { isNo } from '@accelint/predicates/is-noyes';
isNo('no'); // true
isNo('NO'); // true
isNo('n'); // true
isNo('N'); // true
isNo(0); // true
isNo(''); // true
isNo('false'); // true
isNo('yes'); // false
```
## isOn [#ison]
Tests if a value matches the on values list.
### Reference [#reference-4]
```typescript
function isOn(val: unknown): boolean
```
### Examples [#examples-4]
```typescript
import { isOn } from '@accelint/predicates/is-noyes';
isOn('on'); // true
isOn('ON'); // true
isOn(1); // true
isOn('true'); // true
isOn('off'); // false
isOn(0); // false
```
## isOff [#isoff]
Tests if a value matches the off values list.
### Reference [#reference-5]
```typescript
function isOff(val: unknown): boolean
```
### Examples [#examples-5]
```typescript
import { isOff } from '@accelint/predicates/is-noyes';
isOff('off'); // true
isOff('OFF'); // true
isOff(0); // true
isOff(''); // true
isOff('false'); // true
isOff('on'); // false
```
## isAnyTruthy [#isanytruthy]
Tests if a value matches any truthy variant (true, yes, or on).
### Reference [#reference-6]
```typescript
function isAnyTruthy(val: unknown): boolean
```
### Examples [#examples-6]
```typescript
import { isAnyTruthy } from '@accelint/predicates/is-noyes';
isAnyTruthy(1); // true
isAnyTruthy('true'); // true
isAnyTruthy('yes'); // true
isAnyTruthy('on'); // true
isAnyTruthy(0); // false
isAnyTruthy('off'); // false
```
## isAnyFalsy [#isanyfalsy]
Tests if a value matches any falsy variant (false, no, or off).
### Reference [#reference-7]
```typescript
function isAnyFalsy(val: unknown): boolean
```
### Examples [#examples-7]
```typescript
import { isAnyFalsy } from '@accelint/predicates/is-noyes';
isAnyFalsy(0); // true
isAnyFalsy('false'); // true
isAnyFalsy('no'); // true
isAnyFalsy('off'); // true
isAnyFalsy(1); // false
isAnyFalsy('yes'); // false
```
## Real-World Examples [#real-world-examples]
### Example: Parsing environment variables [#example-parsing-environment-variables]
```typescript
import { isAnyTruthy } from '@accelint/predicates/is-noyes';
const DEBUG = process.env.DEBUG;
const isDebugMode = isAnyTruthy(DEBUG);
if (isDebugMode) {
console.log('Debug mode enabled');
}
// Works with: DEBUG=1, DEBUG=true, DEBUG=yes, DEBUG=on
```
### Example: Feature flag validation [#example-feature-flag-validation]
```typescript
import { isOn, isOff } from '@accelint/predicates/is-noyes';
interface FeatureFlags {
newUI: string;
betaFeatures: string;
}
function parseFeatureFlags(flags: FeatureFlags) {
return {
newUI: isOn(flags.newUI),
betaFeatures: isOn(flags.betaFeatures)
};
}
const flags = parseFeatureFlags({ newUI: 'on', betaFeatures: 'off' });
// { newUI: true, betaFeatures: false }
```
### Example: Form checkbox parsing [#example-form-checkbox-parsing]
```typescript
import { isYes, isNo } from '@accelint/predicates/is-noyes';
function parseFormData(data: Record<string, string>) {
return {
newsletter: isYes(data.newsletter),
notifications: !isNo(data.notifications)
};
}
const form = { newsletter: 'yes', notifications: '' };
const parsed = parseFormData(form);
// { newsletter: true, notifications: false }
```
> **Good to know:** All comparisons are case-insensitive and trim whitespace. These predicates are more lenient than `toBoolean` from `@accelint/converters` — use converters for strict boolean coercion.
## Related [#related]
* [isNothing](../is-nothing/index.md) - Check for null or undefined
* [isSomething](../is-something/index.md) - Check for defined values
* [isString](../is-string/index.md) - Type guard for strings
# Number Predicates (/docs/packages/predicates/is-number)
Type guards for validating numbers and numeric values with support for finite checks, string parsing, and special numeric values.
## Usage [#usage]
```typescript
import {
isNumber,
isFiniteNumber,
isNumeric,
isFiniteNumeric
} from '@accelint/predicates/is-number';
// Basic number validation
isNumber(123); // true
isNumber(Infinity); // true
isNumber(NaN); // true
isNumber('123'); // false
// Finite numbers only
isFiniteNumber(123); // true
isFiniteNumber(Infinity); // false
isFiniteNumber(NaN); // false
// Numeric strings accepted
isNumeric('123'); // true
isNumeric('Infinity'); // true
isFiniteNumeric('123'); // true
isFiniteNumeric('Infinity'); // false
```
## isNumber [#isnumber]
Determines if a value is a number type, including Infinities and NaN.
### Reference [#reference]
```typescript
function isNumber(val: unknown): val is number
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | --------- | -------------- |
| `val` | `unknown` | Value to check |
#### Returns [#returns]
Type guard that narrows the type to `number`. Returns `true` for all number values including `Infinity`, `-Infinity`, and `NaN`.
### Examples [#examples]
#### Example: Type narrowing with numbers [#example-type-narrowing-with-numbers]
```typescript
import { isNumber } from '@accelint/predicates/is-number';
function processValue(val: unknown) {
if (isNumber(val)) {
// TypeScript knows val is number here
return val.toFixed(2);
}
throw new Error('Expected number');
}
processValue(1.23); // "1.23"
processValue(Infinity); // "Infinity"
processValue('123'); // Error: Expected number
```
#### Example: Filtering arrays [#example-filtering-arrays]
```typescript
import { isNumber } from '@accelint/predicates/is-number';
const mixed = [1, '2', 3, null, 4, undefined, NaN];
const numbers = mixed.filter(isNumber);
// [1, 3, 4, NaN]
```
> **Good to know:** This predicate includes `NaN` and infinities. Use `isFiniteNumber` to exclude these special values.
## isFiniteNumber [#isfinitenumber]
Determines if a value is a finite number, excluding Infinities, NaN, and strings.
### Reference [#reference-1]
```typescript
function isFiniteNumber(val: unknown): val is number
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | --------- | -------------- |
| `val` | `unknown` | Value to check |
#### Returns [#returns-1]
Type guard that narrows to `number`. Returns `true` only for finite numeric values.
### Examples [#examples-1]
#### Example: Validating calculation results [#example-validating-calculation-results]
```typescript
import { isFiniteNumber } from '@accelint/predicates/is-number';
function safeDivide(a: number, b: number) {
const result = a / b;
if (isFiniteNumber(result)) {
return result;
}
throw new Error('Division resulted in non-finite value');
}
safeDivide(10, 2); // 5
safeDivide(10, 0); // Error: Division resulted in non-finite value
```
#### Example: Filtering valid coordinates [#example-filtering-valid-coordinates]
```typescript
import { isFiniteNumber } from '@accelint/predicates/is-number';
const coordinates = [
{ x: 10, y: 20 },
{ x: NaN, y: 30 },
{ x: Infinity, y: 40 },
{ x: 15, y: 25 }
];
const valid = coordinates.filter(coord =>
isFiniteNumber(coord.x) && isFiniteNumber(coord.y)
);
// [{ x: 10, y: 20 }, { x: 15, y: 25 }]
```
## isNumeric [#isnumeric]
Determines if a value is a number or a string that parses to a number, including special values.
### Reference [#reference-2]
```typescript
function isNumeric(val: unknown): val is number
```
#### Parameters [#parameters-2]
| Parameter | Type | Description |
| --------- | --------- | -------------- |
| `val` | `unknown` | Value to check |
#### Returns [#returns-2]
Type guard narrowing to `number`. Accepts numeric strings including `'Infinity'`, `'-Infinity'`, and `'NaN'`.
### Examples [#examples-2]
#### Example: Parsing user input [#example-parsing-user-input]
```typescript
import { isNumeric } from '@accelint/predicates/is-number';
function parseUserInput(input: unknown): number {
if (isNumeric(input)) {
return typeof input === 'string' ? parseFloat(input) : input;
}
throw new Error('Not a numeric value');
}
parseUserInput(123); // 123
parseUserInput('456'); // 456
parseUserInput('Infinity'); // Infinity
parseUserInput('hello'); // Error: Not a numeric value
```
#### Example: Validating form fields [#example-validating-form-fields]
```typescript
import { isNumeric } from '@accelint/predicates/is-number';
const formData = {
age: '25',
height: '175.5',
weight: 'invalid'
};
const validFields = Object.entries(formData)
.filter(([_, value]) => isNumeric(value))
.map(([key, value]) => [key, parseFloat(value as string)]);
// [['age', 25], ['height', 175.5]]
```
## isFiniteNumeric [#isfinitenumeric]
Determines if a value is a finite number or a string that parses to a finite number.
### Reference [#reference-3]
```typescript
function isFiniteNumeric(val: unknown): val is number
```
#### Parameters [#parameters-3]
| Parameter | Type | Description |
| --------- | --------- | -------------- |
| `val` | `unknown` | Value to check |
#### Returns [#returns-3]
Type guard narrowing to `number`. Excludes infinities and NaN, but accepts valid numeric strings.
### Examples [#examples-3]
#### Example: Safe numeric parsing [#example-safe-numeric-parsing]
```typescript
import { isFiniteNumeric } from '@accelint/predicates/is-number';
function safeParseNumber(input: unknown): number | null {
if (isFiniteNumeric(input)) {
return typeof input === 'string' ? parseFloat(input) : input;
}
return null;
}
safeParseNumber('42'); // 42
safeParseNumber(123); // 123
safeParseNumber('Infinity'); // null
safeParseNumber('hello'); // null
```
#### Example: Validating measurement data [#example-validating-measurement-data]
```typescript
import { isFiniteNumeric } from '@accelint/predicates/is-number';
interface Measurement {
value: unknown;
unit: string;
}
function validateMeasurements(measurements: Measurement[]) {
return measurements.filter(m => isFiniteNumeric(m.value));
}
const data = [
{ value: '25.5', unit: 'cm' },
{ value: Infinity, unit: 'cm' },
{ value: '30', unit: 'cm' },
{ value: 'N/A', unit: 'cm' }
];
const valid = validateMeasurements(data);
// [{ value: '25.5', unit: 'cm' }, { value: '30', unit: 'cm' }]
```
## Related [#related]
* [isString](../is-string/index.md) - Type guard for string values
* [isFiniteNumeric](#isfiniteNumeric) - Finite number or numeric string validator
* [isNothing](../is-nothing/index.md) - Check for null or undefined values
# isRgba255Tuple (/docs/packages/predicates/is-rgba-255-tuple)
Validates RGBA tuple where all channels are 0-255 (deck.gl format).
## Usage [#usage]
```typescript
import { isRgba255Tuple } from '@accelint/predicates/is-rgba-255-tuple';
isRgba255Tuple([255, 128, 64, 255]); // true
isRgba255Tuple([255, 128, 64, 128]); // true (alpha as 0-255)
isRgba255Tuple([255, 128, 64]); // false (missing alpha)
isRgba255Tuple('rgba(255, 128, 64, 1)'); // false (string, not tuple)
isRgba255Tuple([256, 128, 64, 255]); // false (r out of range)
```
## Reference [#reference]
```typescript
type Rgba255Tuple = readonly [
r: number, // 0-255
g: number, // 0-255
b: number, // 0-255
a: number, // 0-255
];
function isRgba255Tuple(value: unknown): value is Rgba255Tuple
```
## Examples [#examples]
```typescript
import { isRgba255Tuple } from '@accelint/predicates/is-rgba-255-tuple';
// Valid RGBA tuples
isRgba255Tuple([255, 128, 64, 255]); // true (opaque)
isRgba255Tuple([255, 128, 64, 128]); // true (50% alpha)
isRgba255Tuple([0, 0, 0, 0]); // true (transparent black)
// Wrong length
isRgba255Tuple([255, 128, 64]); // false (missing alpha)
isRgba255Tuple([255, 128, 64, 255, 0]); // false (too many values)
// Wrong types
isRgba255Tuple('rgba(255, 128, 64, 1)'); // false (string, not array)
isRgba255Tuple({ r: 255, g: 128, b: 64, a: 255 }); // false (object, not array)
// Out of range values
isRgba255Tuple([256, 128, 64, 255]); // false (r > 255)
isRgba255Tuple([-1, 128, 64, 255]); // false (r < 0)
isRgba255Tuple([255, 128, 64, 256]); // false (a > 255)
// Non-integer values
isRgba255Tuple([255.5, 128, 64, 255]); // false (non-integer)
isRgba255Tuple([NaN, 128, 64, 255]); // false (NaN)
```
## Real-World Example: deck.gl layer colors [#real-world-example-deckgl-layer-colors]
```typescript
import { isRgba255Tuple } from '@accelint/predicates/is-rgba-255-tuple';
import { ScatterplotLayer } from '@deck.gl/layers';
type LayerColor = Rgba255Tuple | ((d: DataPoint) => Rgba255Tuple);
function createColoredLayer(
data: DataPoint[],
color: unknown
): ScatterplotLayer {
// Validate static color
if (isRgba255Tuple(color)) {
return new ScatterplotLayer({
id: 'points',
data,
getFillColor: color
});
}
throw new Error('Invalid color: expected Rgba255Tuple format');
}
// Usage with deck.gl
const layer = createColoredLayer(points, [255, 128, 64, 200]);
```
> **Good to know:** `isRgba255Tuple` uses alpha 0-255 (deck.gl format), while `isCssRgbaObject` uses alpha 0-1 (CSS standard). Always convert between formats when needed.
## Related [#related]
* [isCssRgbaObject](./is-css-rgba-object) - Type guard for CSS RGBA objects (alpha 0-1)
* [isHexColor](./is-hex-color) - Type guard for hex color strings
* [isCssRgbaString](./is-css-rgba-string) - Type guard for CSS rgb/rgba strings
* [isValid255Channel](./is-valid-255-channel) - Validate individual color channels
* [isArray](./is-array) - Type guard for arrays
# isSomething (/docs/packages/predicates/is-something)
## Usage [#usage]
```typescript
import { isSomething } from '@accelint/predicates/is-something';
isSomething(0); // true
isSomething(''); // true
isSomething(false); // true
isSomething(null); // false
isSomething(undefined); // false
```
## Reference [#reference]
```typescript
function isSomething(val: unknown): boolean
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | --------- | -------------- |
| `val` | `unknown` | Value to check |
### Returns [#returns]
Returns `true` if the value is not `null` or `undefined`, `false` otherwise.
## Examples [#examples]
### Example: Happy path validation [#example-happy-path-validation]
```typescript
import { isSomething } from '@accelint/predicates/is-something';
function processUser(user: User | null | undefined) {
if (isSomething(user)) {
// Happy path - safe to use user
console.log(user.name);
return;
}
console.log('No user provided');
}
```
### Example: Filtering arrays [#example-filtering-arrays]
```typescript
import { isSomething } from '@accelint/predicates/is-something';
const values = [1, null, 2, undefined, 3, 0, ''];
const defined = values.filter(isSomething);
// [1, 2, 3, 0, '']
```
### Example: Type narrowing for optional properties [#example-type-narrowing-for-optional-properties]
```typescript
import { isSomething } from '@accelint/predicates/is-something';
interface Config {
apiKey?: string;
timeout?: number;
}
function validateConfig(config: Config) {
const hasApiKey = isSomething(config.apiKey);
const hasTimeout = isSomething(config.timeout);
return hasApiKey && hasTimeout;
}
```
> **Good to know:** This is a composed function using `compose(not, isNothing)`, demonstrating functional composition. Falsy values like `0`, `''`, and `false` return `true` because they are defined values.
## Related [#related]
* [isNothing](../is-nothing/index.md) - Opposite check: value is null or undefined
* [isString](../is-string/index.md) - Check if value is a string
* [isNumber](../is-number/index.md) - Check if value is a number
# isString (/docs/packages/predicates/is-string)
Type guard that determines if a value is a string, including both primitive strings and String object instances.
## Usage [#usage]
```typescript
import { isString } from '@accelint/predicates/is-string';
isString('hello'); // true
isString(new String('hi')); // true
isString(123); // false
isString(null); // false
```
## Reference [#reference]
```typescript
function isString(val: unknown): val is string
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | --------- | -------------- |
| `val` | `unknown` | Value to check |
### Returns [#returns]
Type guard that narrows the type to `string`. Returns `true` for both primitive strings and String object instances.
## Examples [#examples]
### Example: Type narrowing for string operations [#example-type-narrowing-for-string-operations]
```typescript
import { isString } from '@accelint/predicates/is-string';
function processValue(val: unknown) {
if (isString(val)) {
// TypeScript knows val is string here
return val.toUpperCase();
}
throw new Error('Expected string');
}
processValue('hello'); // "HELLO"
processValue(new String('hi')); // "HI"
processValue(123); // Error: Expected string
```
### Example: Filtering mixed arrays [#example-filtering-mixed-arrays]
```typescript
import { isString } from '@accelint/predicates/is-string';
const mixed = ['hello', 42, 'world', null, undefined, true, 'test'];
const strings = mixed.filter(isString);
// ['hello', 'world', 'test']
```
### Example: Safe string concatenation [#example-safe-string-concatenation]
```typescript
import { isString } from '@accelint/predicates/is-string';
function safeConcat(...values: unknown[]): string {
const strings = values.filter(isString);
return strings.join(' ');
}
safeConcat('Hello', 'world', 123, null, '!');
// "Hello world !"
```
### Example: Validating object properties [#example-validating-object-properties]
```typescript
import { isString } from '@accelint/predicates/is-string';
interface Config {
name: unknown;
path: unknown;
}
function validateConfig(config: Config): config is { name: string; path: string } {
return isString(config.name) && isString(config.path);
}
const config = { name: 'app', path: '/home/user' };
if (validateConfig(config)) {
// TypeScript knows name and path are strings
console.log(config.name.toUpperCase());
}
```
> **Good to know:** This predicate returns `true` for both `typeof val === 'string'` (primitive) and `val instanceof String` (object wrapper). Most JavaScript code uses primitive strings, but this predicate handles both cases.
## Related [#related]
* [isNumber](../is-number/index.md) - Type guard for number values
* [isNothing](../is-nothing/index.md) - Check for null or undefined values
* [isSomething](../is-something/index.md) - Check for non-null/undefined values
# isValid255Channel (/docs/packages/predicates/is-valid-255-channel)
## Usage [#usage]
```typescript
import { isValid255Channel } from '@accelint/predicates/is-valid-255-channel';
isValid255Channel(0); // true
isValid255Channel(128); // true
isValid255Channel(255); // true
isValid255Channel(256); // false
isValid255Channel(-1); // false
isValid255Channel(NaN); // false
```
## Reference [#reference]
```typescript
function isValid255Channel(n: number): boolean
```
## Examples [#examples]
```typescript
import { isValid255Channel } from '@accelint/predicates/is-valid-255-channel';
// Valid channel values
isValid255Channel(0); // true (minimum)
isValid255Channel(128); // true (mid-range)
isValid255Channel(255); // true (maximum)
// Out of range
isValid255Channel(256); // false (too high)
isValid255Channel(-1); // false (negative)
// Invalid numbers
isValid255Channel(NaN); // false
isValid255Channel(Infinity); // false
isValid255Channel(-Infinity); // false
// Non-integers
isValid255Channel(128.5); // false (not an integer)
isValid255Channel(0.5); // false
```
## Real-World Example: Color channel validation [#real-world-example-color-channel-validation]
```typescript
import { isValid255Channel } from '@accelint/predicates/is-valid-255-channel';
function createRgbaObject(
r: number,
g: number,
b: number,
a: number
): { r: number; g: number; b: number; a: number } {
// Validate RGB channels (0-255)
if (!isValid255Channel(r)) {
throw new Error(`Invalid red channel: ${r} (must be 0-255)`);
}
if (!isValid255Channel(g)) {
throw new Error(`Invalid green channel: ${g} (must be 0-255)`);
}
if (!isValid255Channel(b)) {
throw new Error(`Invalid blue channel: ${b} (must be 0-255)`);
}
// Alpha channel is 0-1 in CSS format
if (a < 0 || a > 1 || Number.isNaN(a)) {
throw new Error(`Invalid alpha channel: ${a} (must be 0-1)`);
}
return { r, g, b, a };
}
// Valid
createRgbaObject(255, 128, 64, 0.5); // { r: 255, g: 128, b: 64, a: 0.5 }
// Throws error
createRgbaObject(256, 128, 64, 0.5); // Error: Invalid red channel: 256
```
## Real-World Example: Building color validators [#real-world-example-building-color-validators]
```typescript
import { isValid255Channel } from '@accelint/predicates/is-valid-255-channel';
function validateRgbTuple(value: unknown): value is [number, number, number] {
if (!Array.isArray(value) || value.length !== 3) {
return false;
}
return value.every(channel =>
typeof channel === 'number' && isValid255Channel(channel)
);
}
validateRgbTuple([255, 128, 64]); // true
validateRgbTuple([256, 128, 64]); // false (r out of range)
```
> **Good to know:** This validator checks for integer values between 0-255, rejecting floats, NaN, and infinity. Use it as a building block for more complex color validators.
## Related [#related]
* [isCssRgbaObject](./is-css-rgba-object) - Type guard for CSS RGBA objects
* [isRgba255Tuple](./is-rgba-255-tuple) - Type guard for RGBA tuples
* [isNumber](./is-number) - Type guard for numbers
# Worker Predicates (/docs/packages/predicates/is-worker)
## Usage [#usage]
```typescript
import { isWorker, isSharedWorker } from '@accelint/predicates/is-worker';
const worker = new Worker(new URL('./worker.ts', import.meta.url));
isWorker(worker); // true
isSharedWorker(worker); // false
const shared = new SharedWorker(new URL('./shared.ts', import.meta.url));
isSharedWorker(shared); // true
isWorker(shared); // false
```
## isWorker [#isworker]
Determines if a value is a Worker instance.
### Reference [#reference]
```typescript
function isWorker(val: unknown): boolean
```
### Examples [#examples]
#### Example: Worker type validation [#example-worker-type-validation]
```typescript
import { isWorker } from '@accelint/predicates/is-worker';
const worker = new Worker(new URL('./my-worker.ts', import.meta.url));
if (isWorker(worker)) {
worker.postMessage({ type: 'start', data: [1, 2, 3] });
}
isWorker(worker); // true
isWorker(new SharedWorker(new URL('./shared.ts', import.meta.url))); // false
isWorker({}); // false
```
#### Example: Validating worker pool [#example-validating-worker-pool]
```typescript
import { isWorker } from '@accelint/predicates/is-worker';
class WorkerPool {
private workers: Worker[] = [];
addWorker(worker: unknown) {
if (!isWorker(worker)) {
throw new Error('Invalid worker instance');
}
this.workers.push(worker);
}
}
const pool = new WorkerPool();
pool.addWorker(new Worker(new URL('./worker.ts', import.meta.url))); // OK
pool.addWorker({}); // Error: Invalid worker instance
```
## isSharedWorker [#issharedworker]
Determines if a value is a SharedWorker instance.
### Reference [#reference-1]
```typescript
function isSharedWorker(val: unknown): boolean
```
### Examples [#examples-1]
#### Example: SharedWorker type validation [#example-sharedworker-type-validation]
```typescript
import { isSharedWorker } from '@accelint/predicates/is-worker';
const sharedWorker = new SharedWorker(new URL('./shared.ts', import.meta.url));
if (isSharedWorker(sharedWorker)) {
sharedWorker.port.postMessage({ type: 'connect' });
}
isSharedWorker(sharedWorker); // true
isSharedWorker(new Worker(new URL('./worker.ts', import.meta.url))); // false
isSharedWorker({}); // false
```
#### Example: Creating worker manager [#example-creating-worker-manager]
```typescript
import { isWorker, isSharedWorker } from '@accelint/predicates/is-worker';
type AnyWorker = Worker | SharedWorker;
function postMessage(worker: AnyWorker, message: unknown) {
if (isWorker(worker)) {
worker.postMessage(message);
} else if (isSharedWorker(worker)) {
worker.port.postMessage(message);
} else {
throw new Error('Invalid worker type');
}
}
const worker = new Worker(new URL('./worker.ts', import.meta.url));
const shared = new SharedWorker(new URL('./shared.ts', import.meta.url));
postMessage(worker, { action: 'process' }); // Uses worker.postMessage
postMessage(shared, { action: 'process' }); // Uses worker.port.postMessage
```
## Real-World Example: Worker factory [#real-world-example-worker-factory]
```typescript
import { isWorker, isSharedWorker } from '@accelint/predicates/is-worker';
interface WorkerConfig {
type: 'worker' | 'shared';
script: string;
}
class WorkerFactory {
create(config: WorkerConfig): Worker | SharedWorker {
const url = new URL(config.script, import.meta.url);
if (config.type === 'shared') {
return new SharedWorker(url);
}
return new Worker(url);
}
terminate(worker: Worker | SharedWorker) {
if (isWorker(worker)) {
worker.terminate();
} else if (isSharedWorker(worker)) {
worker.port.close();
}
}
postMessage(worker: Worker | SharedWorker, message: unknown) {
if (isWorker(worker)) {
worker.postMessage(message);
} else if (isSharedWorker(worker)) {
worker.port.postMessage(message);
}
}
}
const factory = new WorkerFactory();
const worker = factory.create({ type: 'worker', script: './worker.ts' });
factory.postMessage(worker, { action: 'start' });
factory.terminate(worker);
```
> **Good to know:** Workers and SharedWorkers have different message APIs. Workers use `postMessage()` directly, while SharedWorkers use `port.postMessage()`. Use these type guards to handle both cases correctly.
## Related [#related]
* [isString](../is-string/index.md) - Type guard for strings
* [isNothing](../is-nothing/index.md) - Check for null or undefined
* [isSomething](../is-something/index.md) - Check for defined values
# Overview (/docs/packages/websocket)
> **Under Construction**: This package is currently in development and does not yet export any functionality.
## Installation [#installation]
```bash
pnpm add @accelint/websocket
```
## Status [#status]
This package is currently a placeholder and will provide utilities for working with WebSockets in the future.
## Related [#related]
* [@accelint/bus](../bus/index.md) - Event bus with BroadcastChannel support
* [@accelint/web-worker](../worker.md) - Web Worker utilities
# Overview (/docs/packages/temporal)
## Installation [#installation]
```bash
pnpm add @accelint/temporal
```
## Usage [#usage]
```typescript
// Import from root (all exports)
import { setClockInterval, setClockTimeout } from '@accelint/temporal';
// Import from sub-modules
import { setClockInterval, setClockTimeout } from '@accelint/temporal/timers';
```
## Available Exports [#available-exports]
### Timers [#timers]
| Function | Description |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| [setClockInterval](./set-clock-interval.mdx) | Execute a callback repeatedly at specified intervals, starting at the next clock second boundary |
| [setClockTimeout](./set-clock-timeout.mdx) | Execute a callback once after a specified delay, starting from the next clock second boundary |
## Examples [#examples]
### Example: Clock display [#example-clock-display]
```typescript
import { setClockInterval } from '@accelint/temporal';
function startClock(element: HTMLElement) {
const cleanup = setClockInterval(() => {
element.textContent = new Date().toLocaleTimeString();
}, 1000);
return cleanup;
}
// Start the clock
const cleanup = startClock(document.getElementById('clock'));
// Stop when done
cleanup();
```
### Example: Scheduled task [#example-scheduled-task]
```typescript
import { setClockTimeout } from '@accelint/temporal';
function scheduleNotification(message: string, delayMs: number) {
const cleanup = setClockTimeout(() => {
console.log(message);
}, delayMs);
return cleanup;
}
// Schedule for 5 seconds from next clock second
const cancel = scheduleNotification('Task complete!', 5000);
// Cancel if needed
cancel();
```
## Related [#related]
* [@accelint/core](../core/index.mdx) - Core functional utilities
* [GitHub Repository](https://github.com/gohypergiant/standard-toolkit) - Source code
# setClockInterval (/docs/packages/temporal/set-clock-interval)
## Usage [#usage]
```typescript
import { setClockInterval } from '@accelint/temporal';
const cleanup = setClockInterval(() => {
console.log('Tick:', new Date().toISOString());
}, 1000);
// Later, stop the interval
cleanup();
```
## Reference [#reference]
```typescript
function setClockInterval(
cb: () => void,
ms: number
): () => void
```
Executes a callback repeatedly at a specified interval, aligned to clock second boundaries. Unlike standard `setInterval`, this function waits until the next clock second before starting, then automatically corrects for any execution drift on each iteration.
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ------------ | ------------------------------------------------------------------------------------------- |
| `cb` | `() => void` | Callback function to execute at the next clock second, then repeatedly after each interval. |
| `ms` | `number` | Time in milliseconds between callback executions. |
### Returns [#returns]
Returns a cleanup function that clears the interval when called. Safe to call multiple times.
## Examples [#examples]
### Example: Updating a clock display [#example-updating-a-clock-display]
```typescript
import { setClockInterval } from '@accelint/temporal';
function updateClock(element: HTMLElement) {
const cleanup = setClockInterval(() => {
element.textContent = new Date().toLocaleTimeString();
}, 1000);
return cleanup;
}
const cleanup = updateClock(document.getElementById('clock'));
// Updates every second, synchronized to system clock
```
### Example: Polling API with drift correction [#example-polling-api-with-drift-correction]
```typescript
import { setClockInterval } from '@accelint/temporal';
async function pollEndpoint(url: string, intervalMs: number) {
const cleanup = setClockInterval(async () => {
try {
const response = await fetch(url);
const data = await response.json();
console.log('Polled data:', data);
} catch (error) {
console.error('Poll failed:', error);
}
}, intervalMs);
return cleanup;
}
const cleanup = await pollEndpoint('/api/status', 5000);
// Polls every 5 seconds, correcting for any execution drift
```
### Example: Animation frame synchronization [#example-animation-frame-synchronization]
```typescript
import { setClockInterval } from '@accelint/temporal';
function animateCounter(element: HTMLElement, interval: number) {
let count = 0;
const cleanup = setClockInterval(() => {
count++;
element.textContent = String(count);
}, interval);
return cleanup;
}
const cleanup = animateCounter(document.getElementById('counter'), 250);
// Increments counter every 250ms, aligned to clock boundaries
```
### Example: Drift correction demonstration [#example-drift-correction-demonstration]
```typescript
import { setClockInterval } from '@accelint/temporal';
let lastTime = Date.now();
const cleanup = setClockInterval(() => {
const now = Date.now();
const elapsed = now - lastTime;
console.log(`Elapsed: ${elapsed}ms`);
lastTime = now;
}, 1000);
// Output stays consistent at ~1000ms despite callback execution time
// Standard setInterval would accumulate drift over time
```
> **Good to know:** The first callback execution happens at the next clock second boundary, not immediately. For immediate execution, use standard `setInterval`. The interval automatically corrects for drift by recalculating the delay on each iteration using internal timing utilities.
## Related [#related]
* [setClockTimeout](./set-clock-timeout.mdx) - Execute callback once after delay
* [callNextSecond](./timers/utils.md#callnextsecond) - Execute callback at next clock second
* [remainder](./timers/utils.md#remainder) - Calculate time until next interval boundary
# setClockTimeout (/docs/packages/temporal/set-clock-timeout)
## Usage [#usage]
```typescript
import { setClockTimeout } from '@accelint/temporal';
const cleanup = setClockTimeout(() => {
console.log('Executed at:', new Date().toISOString());
}, 5000);
// Cancel if needed before execution
cleanup();
```
## Reference [#reference]
```typescript
function setClockTimeout(
cb: () => void,
ms: number
): () => void
```
Executes a callback once after a specified delay, aligned to clock second boundaries. Unlike standard `setTimeout`, this function waits until the next clock second before starting the countdown.
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ------------ | ----------------------------------------------------------- |
| `cb` | `() => void` | Callback function to execute after the delay. |
| `ms` | `number` | Time in milliseconds to wait before executing the callback. |
### Returns [#returns]
Returns a cleanup function that cancels the timeout when called. Safe to call multiple times.
## Examples [#examples]
### Example: Delayed notification [#example-delayed-notification]
```typescript
import { setClockTimeout } from '@accelint/temporal';
function showNotification(message: string, delayMs: number) {
const cleanup = setClockTimeout(() => {
alert(message);
}, delayMs);
return cleanup;
}
const cancel = showNotification('Time is up!', 10000);
// Shows notification after 10 seconds, starting at next clock second
// User can cancel before it fires
document.getElementById('cancel')?.addEventListener('click', cancel);
```
### Example: Debounced action with clock alignment [#example-debounced-action-with-clock-alignment]
```typescript
import { setClockTimeout } from '@accelint/temporal';
function createDebouncedSave<T>(saveFn: (data: T) => void, delayMs: number) {
let cleanup: (() => void) | undefined;
return (data: T) => {
if (cleanup) cleanup();
cleanup = setClockTimeout(() => {
saveFn(data);
}, delayMs);
return cleanup;
};
}
const debouncedSave = createDebouncedSave(
(data: { value: number }) => console.log('Saving:', data),
2000
);
// Only the last call will execute (after 2 seconds from next clock second)
debouncedSave({ value: 1 });
debouncedSave({ value: 2 });
debouncedSave({ value: 3 });
```
### Example: Scheduled task execution [#example-scheduled-task-execution]
```typescript
import { setClockTimeout } from '@accelint/temporal';
async function scheduleTask(taskFn: () => Promise<void>, delayMs: number) {
const cleanup = setClockTimeout(async () => {
try {
await taskFn();
console.log('Task completed successfully');
} catch (error) {
console.error('Task failed:', error);
}
}, delayMs);
return cleanup;
}
const cleanup = await scheduleTask(
async () => {
await fetch('/api/cleanup');
},
60000
);
// Executes cleanup task 1 minute after next clock second
```
### Example: Coordinated timeout with clock alignment [#example-coordinated-timeout-with-clock-alignment]
```typescript
import { setClockTimeout } from '@accelint/temporal';
function coordinatedTimeout(callbacks: Array<() => void>, delayMs: number) {
const cleanups = callbacks.map(cb =>
setClockTimeout(cb, delayMs)
);
return () => cleanups.forEach(cleanup => cleanup());
}
// All callbacks execute at the same time, aligned to clock
const cancel = coordinatedTimeout([
() => console.log('First'),
() => console.log('Second'),
() => console.log('Third'),
], 3000);
```
> **Good to know:** Execution starts counting from the next clock second boundary, not immediately. For immediate execution, use standard `setTimeout`. Zero or negative delays are treated as immediate execution after reaching the next clock second.
## Related [#related]
* [setClockInterval](./set-clock-interval.mdx) - Execute callback repeatedly at intervals
* [callNextSecond](./timers/utils.md#callnextsecond) - Execute callback at next clock second
* [remainder](./timers/utils.md#remainder) - Calculate time until next interval boundary
# Utilities (/docs/packages/temporal/utils)
## remainder [#remainder]
Calculates the remaining time until the next interval boundary based on the current time.
### Usage [#usage]
```typescript
import { remainder } from '@accelint/temporal/timers/utils';
const msUntilNextSecond = remainder(1000);
console.log(msUntilNextSecond); // e.g., 347ms
```
### Reference [#reference]
```typescript
function remainder(interval: number): number
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| ---------- | -------- | -------------------------------------- |
| `interval` | `number` | The interval duration in milliseconds. |
#### Returns [#returns]
Returns the number of milliseconds remaining until the current time aligns with the next multiple of the specified interval.
### Examples [#examples]
#### Example: Calculate time until next second [#example-calculate-time-until-next-second]
```typescript
import { remainder } from '@accelint/temporal/timers/utils';
const msLeft = remainder(1000);
console.log(`${msLeft}ms until next second`);
// Output: "347ms until next second" (example value)
```
#### Example: Custom interval boundaries [#example-custom-interval-boundaries]
```typescript
import { remainder } from '@accelint/temporal/timers/utils';
// Calculate time until next 5-second boundary
const msUntilNext5Seconds = remainder(5000);
console.log(`${msUntilNext5Seconds}ms until next 5-second mark`);
// Calculate time until next 250ms boundary
const msUntilNextQuarterSecond = remainder(250);
console.log(`${msUntilNextQuarterSecond}ms until next quarter second`);
```
#### Example: Synchronizing multiple timers [#example-synchronizing-multiple-timers]
```typescript
import { remainder } from '@accelint/temporal/timers/utils';
function syncTimers(intervals: number[]) {
return intervals.map(interval => ({
interval,
msUntilNext: remainder(interval),
}));
}
const timings = syncTimers([1000, 500, 250]);
console.log(timings);
// [
// { interval: 1000, msUntilNext: 347 },
// { interval: 500, msUntilNext: 347 },
// { interval: 250, msUntilNext: 97 }
// ]
```
> **Good to know:** This function uses `Date.now() % interval` to calculate the current position within an interval cycle. At exact interval boundaries (when `Date.now() % interval === 0`), it returns the full interval value. For zero or NaN intervals, the function returns NaN. For negative intervals, it returns negative values.
***
## callNextSecond [#callnextsecond]
Executes a callback precisely at the start of the next clock second (when milliseconds are 0).
### Usage [#usage-1]
```typescript
import { callNextSecond } from '@accelint/temporal/timers/utils';
callNextSecond(() => {
console.log('Executed at second boundary');
});
```
### Reference [#reference-1]
```typescript
function callNextSecond(callback: () => void): void
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| ---------- | ------------ | ------------------------------------------------ |
| `callback` | `() => void` | Function to execute at the next second boundary. |
#### Returns [#returns-1]
This function does not return a value. The timeout is automatically cleared after execution.
### Examples [#examples-1]
#### Example: Synchronize action to clock seconds [#example-synchronize-action-to-clock-seconds]
```typescript
import { callNextSecond } from '@accelint/temporal/timers/utils';
callNextSecond(() => {
const now = new Date();
console.log(`Milliseconds: ${now.getMilliseconds()}`);
// Always outputs: "Milliseconds: 0" (or very close to 0)
});
```
#### Example: Start animation at second boundary [#example-start-animation-at-second-boundary]
```typescript
import { callNextSecond } from '@accelint/temporal/timers/utils';
function startAnimationOnSecond(element: HTMLElement) {
callNextSecond(() => {
element.classList.add('animate');
console.log('Animation started at:', new Date().toISOString());
});
}
startAnimationOnSecond(document.getElementById('box'));
```
#### Example: Coordinate multiple actions [#example-coordinate-multiple-actions]
```typescript
import { callNextSecond } from '@accelint/temporal/timers/utils';
async function coordinatedStart(tasks: Array<() => void>) {
callNextSecond(() => {
console.log('Starting all tasks at:', new Date().toISOString());
tasks.forEach(task => task());
});
}
await coordinatedStart([
() => console.log('Task 1'),
() => console.log('Task 2'),
() => console.log('Task 3'),
]);
// All tasks execute simultaneously at the next second boundary
```
#### Example: Building a synchronized interval [#example-building-a-synchronized-interval]
```typescript
import { callNextSecond } from '@accelint/temporal/timers/utils';
function customClockInterval(cb: () => void, ms: number) {
callNextSecond(() => {
cb(); // First execution at second boundary
// Subsequent executions
setInterval(cb, ms);
});
}
customClockInterval(() => {
console.log('Tick');
}, 1000);
```
> **Good to know:** This function calculates the delay using the `remainder` function with a 1000ms interval. It executes exactly once and automatically clears its timeout. If the callback throws an error, it propagates to the caller—there is no built-in error handling. When exactly on a second boundary (`Date.now() % 1000 === 0`), it waits a full second.
## Related [#related]
* [setClockInterval](./index.md#setclockinterval) - Repeat callback at intervals, aligned to clock seconds
* [setClockTimeout](./index.md#setclocktimeout) - Execute callback once after delay, aligned to clock seconds
# Overview (/docs/packages/worker)
## create [#create]
Creates a type-safe interface for communicating with a Web Worker or SharedWorker.
### Usage [#usage]
```typescript
import { create } from '@accelint/worker';
// Define the worker's function signatures
type WorkerFunctions = {
add: (a: number, b: number) => number;
processData: (data: string[]) => string;
};
// Create a worker interface
const worker = create<WorkerFunctions>(
() => new Worker(new URL('./my-worker.ts', import.meta.url))
);
// Call worker functions with type safety
const sum = await worker.run('add', 5, 3); // Returns: 8
const result = await worker.run('processData', ['a', 'b', 'c']);
// Clean up when done
worker.destroy();
```
### Reference [#reference]
```typescript
function create<Functions extends Actions>(
createFn: () => Worker | SharedWorker,
): {
run: <FunctionName extends keyof Functions, FunctionCall extends Functions[FunctionName]>(
functionName: FunctionName,
...args: Parameters<FunctionCall>
) => Promise<ReturnType<FunctionCall>>;
destroy: () => void;
instance: Worker | SharedWorker;
}
```
#### Type Parameters [#type-parameters]
* `Functions` - An object type mapping function names to their signatures
#### Parameters [#parameters]
| Parameter | Type | Description |
| ---------- | ------------------------------ | --------------------------------------------------------------------------- |
| `createFn` | `() => Worker \| SharedWorker` | Factory function that creates and returns a Worker or SharedWorker instance |
#### Returns [#returns]
Returns an object with three properties:
| Property | Type | Description |
| ---------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| `run` | `<FunctionName, FunctionCall>(functionName, ...args) => Promise<ReturnType<FunctionCall>>` | Execute worker functions with type-safe parameters and return values |
| `destroy` | `() => void` | Terminate the worker and clean up event listeners |
| `instance` | `Worker \| SharedWorker` | The underlying Worker or SharedWorker instance |
The `run` method uses an event emitter internally to match requests with responses, providing a promise-based API for worker communication.
### Examples [#examples]
#### Example: Using with SharedWorker [#example-using-with-sharedworker]
```typescript
import { create } from '@accelint/worker';
type SharedFunctions = {
getState: () => Record<string, unknown>;
setState: (key: string, value: unknown) => void;
};
const sharedWorker = create<SharedFunctions>(
() => new SharedWorker(new URL('./shared-worker.ts', import.meta.url))
);
await sharedWorker.run('setState', 'count', 42);
const state = await sharedWorker.run('getState');
```
#### Example: Heavy computation offloading [#example-heavy-computation-offloading]
```typescript
import { create } from '@accelint/worker';
type ComputeWorker = {
fibonacci: (n: number) => number;
factorial: (n: number) => number;
};
const computeWorker = create<ComputeWorker>(
() => new Worker(new URL('./compute-worker.ts', import.meta.url))
);
// Offload CPU-intensive tasks
const fib40 = await computeWorker.run('fibonacci', 40);
const fact20 = await computeWorker.run('factorial', 20);
// Clean up when done
computeWorker.destroy();
```
#### Example: Processing large datasets [#example-processing-large-datasets]
```typescript
import { create } from '@accelint/worker';
type DataWorker = {
processCSV: (csv: string) => Record<string, unknown>[];
filterData: (data: unknown[], predicate: string) => unknown[];
};
const dataWorker = create<DataWorker>(
() => new Worker(new URL('./data-worker.ts', import.meta.url))
);
const csvContent = await fetch('/data.csv').then(r => r.text());
const parsed = await dataWorker.run('processCSV', csvContent);
const filtered = await dataWorker.run('filterData', parsed, 'active === true');
```
#### Example: Error handling [#example-error-handling]
```typescript
import { create } from '@accelint/worker';
type WorkerFunctions = {
riskyOperation: (data: string) => string;
};
const worker = create<WorkerFunctions>(
() => new Worker(new URL('./worker.ts', import.meta.url))
);
try {
const result = await worker.run('riskyOperation', 'input');
console.log('Success:', result);
} catch (error) {
console.error('Worker error:', error);
}
```
> **Good to know:** The worker instance is set to `undefined` after calling `destroy()`. Attempting to call `run()` after destruction will return a rejected promise with "Worker terminated".
***
## expose [#expose]
Exposes a set of functions to be called from the main thread.
### Usage [#usage-1]
```typescript
// my-worker.ts - Regular Worker
import { expose } from '@accelint/worker/worker';
import type { Action } from '@accelint/worker';
expose({
add: async (a: number, b: number): Promise<Action<number>> => {
return [a + b, []];
},
multiply: async (a: number, b: number): Promise<Action<number>> => {
return [a * b, []];
},
processBuffer: async (buffer: ArrayBuffer): Promise<Action<ArrayBuffer>> => {
// Process the buffer
const result = new ArrayBuffer(buffer.byteLength);
// ... processing logic ...
// Return with transferable to avoid copying
return [result, [result]];
}
});
```
### Reference [#reference-1]
```typescript
function expose(
actions: Actions,
shared?: boolean
): void
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `actions` | `Record<string, (...args: any[]) => any>` | Object mapping function names to their implementations. Each function can return either a direct value or an Action tuple \[value, transferables]. |
| `shared` | `boolean` | Whether this is a SharedWorker. Defaults to false. |
#### Returns [#returns-1]
Returns `void`. This function sets up message listeners and does not return a value.
### Examples [#examples-1]
#### Example: SharedWorker with shared state [#example-sharedworker-with-shared-state]
```typescript
// shared-worker.ts
import { expose } from '@accelint/worker/worker';
import type { Action } from '@accelint/worker';
const state: Record<string, unknown> = {};
expose({
getState: async (): Promise<Action<Record<string, unknown>>> => {
return [state, []];
},
setState: async (key: string, value: unknown): Promise<Action<void>> => {
state[key] = value;
return [undefined, []];
}
}, true); // Note: second parameter is true for SharedWorker
```
#### Example: Using transferable objects [#example-using-transferable-objects]
```typescript
// buffer-worker.ts
import { expose } from '@accelint/worker/worker';
import type { Action } from '@accelint/worker';
expose({
processBuffer: async (buffer: ArrayBuffer): Promise<Action<ArrayBuffer>> => {
const result = new ArrayBuffer(buffer.byteLength);
const view = new Uint8Array(result);
const sourceView = new Uint8Array(buffer);
for (let i = 0; i < sourceView.length; i++) {
view[i] = sourceView[i] * 2;
}
// Return with transferable to avoid copying
return [result, [result]];
}
});
```
#### Example: Void actions [#example-void-actions]
```typescript
// logger-worker.ts
import { expose } from '@accelint/worker/worker';
import type { Action } from '@accelint/worker';
expose({
log: async (message: string): Promise<Action<void>> => {
console.log('[Worker]', message);
// Void actions don't need to return data
return [undefined, []];
},
clearCache: async (): Promise<Action<void>> => {
// Clear internal cache
return [undefined, []];
}
});
```
#### Example: Error handling in worker [#example-error-handling-in-worker]
```typescript
// worker.ts
import { expose } from '@accelint/worker/worker';
import type { Action } from '@accelint/worker';
expose({
parseJSON: async (jsonString: string): Promise<Action<unknown>> => {
try {
const parsed = JSON.parse(jsonString);
return [parsed, []];
} catch (error) {
// Errors are automatically caught and sent to main thread
throw new Error(`Invalid JSON: ${error.message}`);
}
}
});
```
#### Example: Image processing [#example-image-processing]
```typescript
// image-worker.ts
import { expose } from '@accelint/worker/worker';
import type { Action } from '@accelint/worker';
expose({
applyGrayscale: async (imageData: ImageData): Promise<Action<ImageData>> => {
const data = imageData.data;
for (let i = 0; i < data.length; i += 4) {
const avg = (data[i] + data[i + 1] + data[i + 2]) / 3;
data[i] = avg; // R
data[i + 1] = avg; // G
data[i + 2] = avg; // B
}
return [imageData, []];
}
});
```
> **Good to know:** The `expose` function automatically handles message routing, error propagation, and supports both regular Workers and SharedWorkers. For SharedWorkers, it listens for `connect` events and routes messages through the port.
***
## Action [#action]
Represents an action result with optional transferable objects.
### Usage [#usage-2]
```typescript
import type { Action } from '@accelint/worker';
// Simple value with no transferables
const result: Action<string> = ['hello', []];
// ArrayBuffer with transferable
const buffer = new ArrayBuffer(1024);
const result: Action<ArrayBuffer> = [buffer, [buffer]];
```
### Reference [#reference-2]
```typescript
type Action<T> = [T, Transferable[]];
```
This type is a tuple containing:
1. The return value of type `T`
2. An array of transferable objects (like `ArrayBuffer`, `MessagePort`) that can be efficiently transferred to the main thread without copying
#### Type Parameters [#type-parameters-1]
* `T` - The type of the return value
### Examples [#examples-2]
#### Example: Simple value [#example-simple-value]
```typescript
import type { Action } from '@accelint/worker';
async function getMessage(): Promise<Action<string>> {
return ['Hello, World!', []];
}
```
#### Example: Multiple transferables [#example-multiple-transferables]
```typescript
import type { Action } from '@accelint/worker';
async function createBuffers(): Promise<Action<ArrayBuffer[]>> {
const buffer1 = new ArrayBuffer(512);
const buffer2 = new ArrayBuffer(1024);
// Transfer both buffers
return [[buffer1, buffer2], [buffer1, buffer2]];
}
```
#### Example: ImageData with underlying buffer [#example-imagedata-with-underlying-buffer]
```typescript
import type { Action } from '@accelint/worker';
async function processImage(imageData: ImageData): Promise<Action<ImageData>> {
// Process imageData...
// Transfer the underlying ArrayBuffer
return [imageData, [imageData.data.buffer]];
}
```
#### Example: Void return type [#example-void-return-type]
```typescript
import type { Action } from '@accelint/worker';
async function logMessage(message: string): Promise<Action<void>> {
console.log(message);
return [undefined, []];
}
```
> **Good to know:** Transferable objects can only be transferred once. After transfer, the original reference becomes detached and cannot be used in the worker. This zero-copy transfer is much more efficient than cloning for large data structures.
## Related [#related]
* [mitt](https://github.com/developit/mitt) - Event emitter used internally for message routing
* [Web Workers API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) - MDN documentation
* [SharedWorker API](https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker) - MDN documentation
* [Transferable Objects](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) - MDN documentation
# Analyzer Configuration (/docs/tooling/biome-config/analyzer)
## Usage [#usage]
Import the analyzer configuration in your `biome.json`:
```json
{
"$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
"extends": ["@accelint/biome-config/analyzer"]
}
```
## Features [#features]
### Import Organization [#import-organization]
Automatically organizes imports when using Biome's source actions.
#### Configuration [#configuration]
* **Level**: On (enabled)
* **Type Imports Grouping**: false (types are not grouped separately)
#### Behavior [#behavior]
Organizes imports alphabetically within their categories without separating type imports:
```typescript
// Before organization
import { useEffect } from 'react';
import type { User } from './types';
import { formatDate } from './utils';
import { useState } from 'react';
import type { Config } from './config';
// After organization
import { useEffect, useState } from 'react';
import type { Config } from './config';
import type { User } from './types';
import { formatDate } from './utils';
```
### Editor Integration [#editor-integration]
#### VSCode [#vscode]
Configure automatic import organization on save in `.vscode/settings.json`:
```json
{
"editor.codeActionsOnSave": {
"source.organizeImports.biome": "explicit"
}
}
```
#### On Demand [#on-demand]
Trigger import organization through your editor's code actions menu (usually Cmd+. or Ctrl+.).
### CLI Usage [#cli-usage]
Organize imports using the Biome CLI:
```bash
# Check and fix all files
pnpm biome check --write .
# Fix specific files
pnpm biome check --write src/**/*.ts
```
The `check` command runs all enabled checks including import organization.
## Import Organization Rules [#import-organization-rules]
### Grouping [#grouping]
Imports are organized into groups:
1. **External dependencies** (node\_modules)
2. **Internal absolute imports** (using path aliases)
3. **Relative imports** (./ and ../)
```typescript
// ✅ Organized imports
import { useState, useEffect } from 'react';
import { formatISO } from 'date-fns';
import { useAuth } from '@/hooks/useAuth';
import type { User } from '@/types';
import { formatDate } from './utils';
import { Button } from './Button';
```
### Sorting [#sorting]
Within each group, imports are sorted:
1. **Side-effect imports** (no specifiers)
2. **Named imports** (alphabetically by module)
3. **Type imports** (not separated, mixed with value imports)
```typescript
// ✅ Sorted within group
import './styles.css';
import { Button } from './components/Button';
import { Input } from './components/Input';
import type { Theme } from './components/types';
import { formatDate, parseDate } from './utils';
```
### Combining Imports [#combining-imports]
Imports from the same module are automatically combined:
```typescript
// ❌ Before
import { useState } from 'react';
import { useEffect } from 'react';
import type { FC } from 'react';
// ✅ After
import { useEffect, useState } from 'react';
import type { FC } from 'react';
```
## Customization [#customization]
### Separate Type Imports [#separate-type-imports]
Enable type import grouping in your `biome.json`:
```json
{
"extends": ["@accelint/biome-config/analyzer"],
"assist": {
"actions": {
"source": {
"organizeImports": {
"level": "on",
"options": {
"groups": [{ "type": true }]
}
}
}
}
}
}
```
With type grouping enabled:
```typescript
// Type imports grouped separately
import { useState, useEffect } from 'react';
import type { FC, ReactNode } from 'react';
import type { User } from './types';
```
### Disable Import Organization [#disable-import-organization]
Disable for specific files using overrides:
```json
{
"extends": ["@accelint/biome-config/analyzer"],
"overrides": [
{
"include": ["**/*.test.ts"],
"assist": {
"actions": {
"source": {
"organizeImports": {
"level": "off"
}
}
}
}
}
]
}
```
## Example: Before and After [#example-before-and-after]
### Before Organization [#before-organization]
```typescript
import { formatDate } from './utils';
import type { User } from './types';
import { Button } from './components/Button';
import { useEffect, useState } from 'react';
import type { Config } from './config';
import { Input } from './components/Input';
import './styles.css';
```
### After Organization [#after-organization]
```typescript
import { useEffect, useState } from 'react';
import './styles.css';
import { Button } from './components/Button';
import { Input } from './components/Input';
import type { Config } from './config';
import type { User } from './types';
import { formatDate } from './utils';
```
## Integration with Linter [#integration-with-linter]
The analyzer works alongside the linter configuration. When both are enabled:
1. **Linter** catches `noUnusedImports` violations
2. **Analyzer** removes unused imports automatically
3. **Linter** validates import order and grouping
```json
{
"extends": [
"@accelint/biome-config/linter",
"@accelint/biome-config/analyzer"
]
}
```
## Troubleshooting [#troubleshooting]
### Imports Not Organizing [#imports-not-organizing]
Ensure source actions are enabled in your editor:
**VSCode**:
```json
{
"editor.codeActionsOnSave": {
"source.organizeImports.biome": "explicit"
}
}
```
### Conflicting with Other Tools [#conflicting-with-other-tools]
If using multiple import organizers (e.g., ESLint, TypeScript), disable them to prevent conflicts:
```json
{
"eslint.codeActionsOnSave.rules": null,
"typescript.preferences.organizeImportsOnSave": false
}
```
## Related [#related]
* [Biome Assist Actions](https://biomejs.dev/analyzer/)
* [Linter Configuration](./linter)
* [Formatter Configuration](./formatter)
* [ESLint Configuration](../eslint-config)
# Formatter Configuration (/docs/tooling/biome-config/formatter)
## Usage [#usage]
Import the formatter configuration in your `biome.json`:
```json
{
"$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
"extends": ["@accelint/biome-config/formatter"]
}
```
## General Settings [#general-settings]
### Indentation [#indentation]
* **Style**: Spaces
* **Width**: 2 spaces
```typescript
// ✅ Formatted output
function example() {
return {
nested: {
value: 'two-space indentation'
}
};
}
```
### Line Width [#line-width]
* **Maximum**: 80 characters
* Helps maintain readability and enables side-by-side diffs
```typescript
// ✅ Within line width
const message = 'Short message';
// ✅ Long lines are wrapped
const longMessage =
'This is a very long message that exceeds 80 characters and will be wrapped';
```
### Line Endings [#line-endings]
* **Style**: LF (Unix-style)
* Ensures consistent line endings across platforms
### Attribute Position [#attribute-position]
* **Setting**: Auto
* Automatically determines optimal JSX attribute positioning
### Format With Errors [#format-with-errors]
* **Enabled**: false
* Prevents formatting files with syntax errors
## JavaScript/TypeScript Settings [#javascripttypescript-settings]
### Semicolons [#semicolons]
* **Style**: Always
* Explicit semicolons prevent ASI edge cases
```typescript
// ✅ Explicit semicolons
const value = 42;
return value;
// ❌ Would be formatted with semicolons
const value = 42
return value
```
### Quote Style [#quote-style]
* **JavaScript/TypeScript**: Single quotes
* **JSX**: Single quotes
```typescript
// ✅ Single quotes
const message = 'Hello world';
const name = 'John';
// ✅ JSX with single quotes
<Button label='Click me' />
```
### Quote Properties [#quote-properties]
* **Style**: As needed
* Quotes object properties only when required
```typescript
// ✅ Unquoted when possible
const config = {
apiKey: 'key',
maxRetries: 3
};
// ✅ Quoted when necessary
const config = {
'api-key': 'key',
'max-retries': 3
};
```
### Trailing Commas [#trailing-commas]
* **Style**: All
* Includes trailing commas in arrays, objects, and function parameters
```typescript
// ✅ Trailing commas
const items = [
'first',
'second',
'third',
];
const config = {
apiKey: 'key',
timeout: 1000,
};
function example(
param1: string,
param2: number,
) {
// ...
}
```
### Arrow Parentheses [#arrow-parentheses]
* **Style**: Always
* Always include parentheses around arrow function parameters
```typescript
// ✅ Always parentheses
const double = (x) => x * 2;
const identity = (x) => x;
// ❌ Would be formatted with parentheses
const double = x => x * 2;
```
### Bracket Spacing [#bracket-spacing]
* **Enabled**: true
* Adds spaces inside object literal braces
```typescript
// ✅ Spacing enabled
const config = { apiKey: 'key', timeout: 1000 };
// ❌ Without spacing
const config = {apiKey: 'key', timeout: 1000};
```
### Bracket Same Line [#bracket-same-line]
* **Enabled**: false
* Places closing JSX bracket on new line
```tsx
// ✅ Bracket on new line
<Component
prop1='value1'
prop2='value2'
>
Content
</Component>
// ❌ Bracket on same line
<Component
prop1='value1'
prop2='value2'>
Content
</Component>
```
## JSON Settings [#json-settings]
### Parser Options [#parser-options]
* **Allow Comments**: false
* **Allow Trailing Commas**: false
Enforces strict JSON standards for interoperability.
```json
{
"name": "package",
"version": "1.0.0"
}
```
### Trailing Commas [#trailing-commas-1]
* **Style**: None
* No trailing commas in JSON files
```json
{
"dependencies": {
"react": "^18.0.0"
}
}
```
## Example: Before and After [#example-before-and-after]
### Before Formatting [#before-formatting]
```typescript
const config={apiKey:"key",maxRetries:3,timeout:5000}
function fetchData(url,options)
{
return fetch(url,{...options,headers:{'Content-Type':'application/json'}})
.then(response=>response.json())
}
const items=['first','second','third']
```
### After Formatting [#after-formatting]
```typescript
const config = { apiKey: 'key', maxRetries: 3, timeout: 5000 };
function fetchData(url, options) {
return fetch(url, {
...options,
headers: { 'Content-Type': 'application/json' },
}).then((response) => response.json());
}
const items = ['first', 'second', 'third'];
```
## Customization [#customization]
Override formatting settings in your `biome.json`:
```json
{
"extends": ["@accelint/biome-config/formatter"],
"formatter": {
"lineWidth": 100,
"indentWidth": 4
},
"javascript": {
"formatter": {
"quoteStyle": "double",
"trailingCommas": "es5"
}
}
}
```
## Editor Integration [#editor-integration]
### Format on Save [#format-on-save]
Configure your editor to format on save:
**VSCode** (`.vscode/settings.json`):
```json
{
"editor.defaultFormatter": "biomejs.biome",
"editor.formatOnSave": true
}
```
### Format Selection [#format-selection]
Most editors support formatting a selection. Check your editor's Biome integration documentation.
## CLI Usage [#cli-usage]
```bash
# Format all files
pnpm biome format --write .
# Check formatting without changes
pnpm biome format .
# Format specific files
pnpm biome format --write src/**/*.ts
```
## Related [#related]
* [Biome Formatter](https://biomejs.dev/formatter/)
* [Linter Configuration](./linter)
* [Analyzer Configuration](./analyzer)
* [Prettier Configuration](../prettier-config)
# Overview (/docs/tooling/biome-config)
## Installation [#installation]
```bash
pnpm add -D @accelint/biome-config
```
```bash
npm install --save-dev @accelint/biome-config
```
```bash
yarn add -D @accelint/biome-config
```
## Usage [#usage]
### Complete Configuration [#complete-configuration]
Import all configuration presets in your `biome.json`:
```json
{
"$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
"extends": [
"@accelint/biome-config/linter",
"@accelint/biome-config/formatter",
"@accelint/biome-config/analyzer"
]
}
```
### Selective Import [#selective-import]
Import only the presets you need:
```json
{
"$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
"extends": ["@accelint/biome-config/linter"]
}
```
## Available Configurations [#available-configurations]
### Linter [#linter]
Strict linting rules with cognitive complexity limits, naming conventions, and React hooks enforcement.
See [Linter Configuration](./linter) for details.
### Formatter [#formatter]
Consistent code formatting settings including indentation, line width, semicolons, and quote styles.
See [Formatter Configuration](./formatter) for details.
### Analyzer [#analyzer]
Code analysis settings for import organization and better maintainability.
See [Analyzer Configuration](./analyzer) for details.
## Customization [#customization]
Override any rule in your project's `biome.json`:
```json
{
"extends": ["@accelint/biome-config/linter"],
"linter": {
"rules": {
"complexity": {
"noExcessiveCognitiveComplexity": {
"options": {
"maxAllowedComplexity": 20
}
}
}
}
}
}
```
## Scripts [#scripts]
Add these scripts to your `package.json`:
```json
{
"scripts": {
"lint": "biome lint .",
"lint:fix": "biome lint --write .",
"format": "biome format --write .",
"format:check": "biome format .",
"check": "biome check --write ."
}
}
```
## Editor Integration [#editor-integration]
### VSCode [#vscode]
Install the [Biome VSCode extension](https://marketplace.visualstudio.com/items?itemName=biomejs.biome):
```json
{
"editor.defaultFormatter": "biomejs.biome",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"quickfix.biome": "explicit"
}
}
```
### Other Editors [#other-editors]
See [Biome editor integrations](https://biomejs.dev/guides/integrate-in-editor/) for setup instructions.
## CI/CD Integration [#cicd-integration]
### GitHub Actions [#github-actions]
```yaml
- name: Check code quality
run: pnpm biome check .
```
### GitLab CI [#gitlab-ci]
```yaml
biome:
script:
- pnpm biome check .
```
## Related [#related]
* [Biome Documentation](https://biomejs.dev/)
* [ESLint Configuration](../eslint-config)
* [Prettier Configuration](../prettier-config)
* [TypeScript Configuration](../typescript-config)
# Linter Configuration (/docs/tooling/biome-config/linter)
## Usage [#usage]
Import the linter configuration in your `biome.json`:
```json
{
"$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
"extends": ["@accelint/biome-config/linter"]
}
```
## Rules Overview [#rules-overview]
### Complexity Rules [#complexity-rules]
Enforces limits on code complexity and encourages simplified logic:
* **noExcessiveCognitiveComplexity**: Maximum cognitive complexity of 15 (error)
* **useSimplifiedLogicExpression**: Simplify boolean expressions (error)
```typescript
// ❌ Avoid: High cognitive complexity
function processData(data, options) {
if (data) {
if (options.validate) {
if (options.strict) {
if (data.length > 0) {
if (data[0].id) {
// ... deeply nested logic
}
}
}
}
}
}
// ✅ Prefer: Reduced complexity with early returns
function processData(data, options) {
if (!data) return;
if (!options.validate) return;
if (!options.strict) return;
if (data.length === 0) return;
if (!data[0].id) return;
// ... main logic
}
```
### Correctness Rules [#correctness-rules]
Catches common programming errors and enforces React best practices:
* **noUndeclaredVariables**: Prevent use of undeclared variables (error)
* **useExhaustiveDependencies**: Ensure React hooks have complete dependency arrays (warning)
* **noUnusedImports**: Remove unused imports (error)
* **noUnusedVariables**: Remove unused variables, allowing rest siblings (error)
* **useHookAtTopLevel**: React hooks must be called at the top level (error)
```typescript
// ❌ Avoid: Missing dependencies
useEffect(() => {
console.log(userName);
}, []); // Missing userName dependency
// ✅ Prefer: Complete dependencies
useEffect(() => {
console.log(userName);
}, [userName]);
// ❌ Avoid: Unused imports
import { useState, useEffect } from 'react';
function Counter() {
const [count, setCount] = useState(0);
return <div>{count}</div>;
}
// ✅ Prefer: Only imported what's used
import { useState } from 'react';
function Counter() {
const [count, setCount] = useState(0);
return <div>{count}</div>;
}
```
### Performance Rules [#performance-rules]
Optimizes for better runtime performance:
* **noReExportAll**: Prevent re-export all statements (error)
```typescript
// ❌ Avoid: Re-export all
export * from './utils';
// ✅ Prefer: Explicit exports
export { formatDate, parseDate } from './utils';
```
### Style Rules [#style-rules]
Enforces consistent coding style and conventions:
* **noNegationElse**: Avoid negation in else clauses (error)
* **useCollapsedElseIf**: Use collapsed else-if statements (error)
* **useBlockStatements**: Prefer block statements (warning)
* **useConsistentArrayType**: Use shorthand array type syntax (warning)
* **noParameterAssign**: Prevent parameter reassignment (error)
* **useNamingConvention**: Enforce camelCase/CONSTANT\_CASE with ASCII-only (error)
```typescript
// ❌ Avoid: Negation in else
if (!isValid) {
return error;
} else {
return success;
}
// ✅ Prefer: Positive condition
if (isValid) {
return success;
} else {
return error;
}
// ❌ Avoid: Array<T> syntax
const items: Array<string> = [];
// ✅ Prefer: Shorthand syntax
const items: string[] = [];
// ❌ Avoid: Parameter reassignment
function updateUser(user: User) {
user.name = 'Updated'; // Mutates parameter
return user;
}
// ✅ Prefer: Return new object
function updateUser(user: User) {
return { ...user, name: 'Updated' };
}
```
### Suspicious Pattern Detection [#suspicious-pattern-detection]
Detects potentially problematic code patterns:
* **noArrayIndexKey**: Warn against using array index as React key (warning)
* **noEmptyBlockStatements**: Prevent empty block statements (error)
* **useAwait**: Async functions must use await (error)
* **noExplicitAny**: Discourage explicit `any` types (warning)
* **noDuplicateElseIf**: Prevent duplicate else-if conditions (error)
```typescript
// ❌ Avoid: Array index as key
items.map((item, index) => <div key={index}>{item}</div>);
// ✅ Prefer: Stable unique identifier
items.map((item) => <div key={item.id}>{item}</div>);
// ❌ Avoid: Async function without await
async function fetchData() {
return data; // No await used
}
// ✅ Prefer: Use await or remove async
async function fetchData() {
return await api.getData();
}
```
## Naming Conventions [#naming-conventions]
Enforces strict naming conventions with ASCII-only characters:
* **Object properties**: CONSTANT\_CASE or camelCase
* **Variables**: camelCase or CONSTANT\_CASE
```typescript
// ✅ Valid naming
const userName = 'John';
const MAX_RETRIES = 3;
const config = { apiKey: 'key', maxTimeout: 1000 };
// ❌ Invalid naming
const user_name = 'John'; // Use camelCase
const max_retries = 3; // Use CONSTANT_CASE
const config = { api_key: 'key' }; // Use camelCase
```
## Customization [#customization]
Override specific rules in your `biome.json`:
```json
{
"extends": ["@accelint/biome-config/linter"],
"linter": {
"rules": {
"complexity": {
"noExcessiveCognitiveComplexity": {
"level": "error",
"options": {
"maxAllowedComplexity": 20
}
}
},
"correctness": {
"useExhaustiveDependencies": "error"
}
}
}
}
```
## Disabling Rules [#disabling-rules]
Disable rules for specific files or directories:
```json
{
"extends": ["@accelint/biome-config/linter"],
"overrides": [
{
"include": ["**/*.test.ts"],
"linter": {
"rules": {
"suspicious": {
"noExplicitAny": "off"
}
}
}
}
]
}
```
## Related [#related]
* [Biome Linter Rules](https://biomejs.dev/linter/rules/)
* [Formatter Configuration](./formatter)
* [Analyzer Configuration](./analyzer)
* [TypeScript Configuration](../typescript-config)
# Overview (/docs/tooling/eslint-config)
> **Deprecated**: This package is a placeholder. The standard-toolkit repository has migrated to [Biome](https://biomejs.dev/) for linting and formatting. Use [@accelint/biome-config](../biome-config/index.mdx) instead.
## Status [#status]
This package is currently a placeholder with no active configuration. Accelint projects have migrated to Biome for improved performance and integrated formatting.
## Migration to Biome [#migration-to-biome]
Biome provides:
* Faster linting and formatting than ESLint + Prettier
* Single tool for both linting and formatting
* Better compatibility with modern JavaScript/TypeScript
* Unified configuration
## Installation [#installation]
```bash
# Using pnpm (recommended)
pnpm add -D @accelint/eslint-config
```
> **Note**: Installing this package is not recommended. It contains no configuration files and exists only for backward compatibility.
## Recommended Alternative [#recommended-alternative]
Use [@accelint/biome-config](../biome-config/index.mdx) for new projects:
```bash
# Install Biome configuration
pnpm add -D @accelint/biome-config @biomejs/biome
```
Create a `biome.json` in your project root:
```json
{
"extends": ["@accelint/biome-config"]
}
```
## Future Plans [#future-plans]
This package may be fully deprecated in a future release. All new projects should use [@accelint/biome-config](../biome-config/index.mdx).
## Related [#related]
* [@accelint/biome-config](../biome-config/index.mdx) - Active linting configuration
* [@accelint/typescript-config](../typescript-config/index.mdx) - TypeScript configuration
* [@accelint/prettier-config](../../prettier-config/index.mdx) - Prettier configuration (also deprecated in favor of Biome)
# Overview (/docs/tooling/prettier-config)
## Usage [#usage]
```json
{
"prettier": "@accelint/prettier-config/config"
}
```
## Reference [#reference]
```typescript
import type { Config } from 'prettier';
const config: Config = {
plugins: ['prettier-plugin-tailwindcss'],
requirePragma: true,
overrides: [
{
files: ['*.css', '*.module.css'],
options: {
requirePragma: false,
singleQuote: true,
},
},
],
};
```
The configuration exports a Prettier config object with three key features:
### Plugins [#plugins]
* **prettier-plugin-tailwindcss**: Automatically sorts Tailwind CSS classes according to the official [recommended class order](https://tailwindcss.com/blog/automatic-class-sorting-with-prettier)
### Core Settings [#core-settings]
* **requirePragma**: `true` - Files must include `/** @format */` comment to be formatted. Prevents accidental formatting of legacy or intentionally unformatted code.
### Overrides [#overrides]
Special handling for CSS files (`*.css`, `*.module.css`):
* **requirePragma**: `false` - CSS files are formatted by default without pragma
* **singleQuote**: `true` - Enforces single quotes in CSS for consistency
> **Good to know:** The pragma requirement prevents Prettier from reformatting files that haven't been opted in. This is especially useful in large codebases with mixed formatting conventions or during gradual Prettier adoption.
## Examples [#examples]
### Example: Basic setup [#example-basic-setup]
```json
{
"name": "my-app",
"prettier": "@accelint/prettier-config/config"
}
```
### Example: Adding format pragma [#example-adding-format-pragma]
Add this comment to the top of any file you want Prettier to format:
```typescript
/** @format */
export function myFunction() {
return 'This file will be formatted';
}
```
### Example: Extending the configuration [#example-extending-the-configuration]
Create a `prettier.config.js` to customize settings:
```javascript
import baseConfig from '@accelint/prettier-config/config';
export default {
...baseConfig,
semi: false,
printWidth: 100,
// Disable pragma requirement for your project
requirePragma: false,
};
```
### Example: Tailwind CSS class sorting [#example-tailwind-css-class-sorting]
The configuration automatically sorts Tailwind classes:
```tsx
/** @format */
// Before formatting
<Button className="px-4 py-2 bg-blue-500 text-white rounded-lg hover:bg-blue-600" />
// After formatting (classes sorted by Tailwind conventions)
<Button className="rounded-lg bg-blue-500 px-4 py-2 text-white hover:bg-blue-600" />
```
### Example: CSS file formatting [#example-css-file-formatting]
CSS files are formatted by default without requiring pragma:
```css
/* No @format comment needed for CSS */
.button {
background-color: 'blue';
padding: '1rem';
}
/* After formatting */
.button {
background-color: 'blue';
padding: '1rem';
}
```
### Example: Format scripts [#example-format-scripts]
Add these npm scripts to format your codebase:
```json
{
"scripts": {
"format": "prettier --write .",
"format:check": "prettier --check ."
}
}
```
### Example: VSCode integration [#example-vscode-integration]
Configure VSCode to format on save in `.vscode/settings.json`:
```json
{
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true,
"[typescript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[typescriptreact]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
}
}
```
### Example: Pre-commit hook [#example-pre-commit-hook]
Using [lefthook](https://github.com/evilmartians/lefthook) to format staged files:
```yaml
pre-commit:
commands:
prettier:
glob: "*.{js,ts,jsx,tsx,json,css,md}"
run: prettier --write {staged_files}
stage_fixed: true
```
### Example: CI validation [#example-ci-validation]
Validate formatting in CI pipeline:
```yaml
- name: Check Code Formatting
run: |
pnpm install
pnpm prettier --check .
```
## Related [#related]
* [prettier](https://prettier.io/docs/en/configuration.html) - Prettier configuration documentation
* [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss) - Tailwind CSS class sorting plugin
# buildReactFiles (/docs/tooling/smeegl/build-react-files)
## Usage [#usage]
```typescript
import { buildReactFiles } from '@accelint/smeegl/build-react-files';
import { findSprites } from '@accelint/smeegl/utils/find-sprites';
// First find sprites
const findResult = await findSprites('**/*.svg', './icons', process.cwd(), tmpDir);
// Generate React components
buildReactFiles(
findResult,
'./icons', // Input directory
'./components/svg' // Output directory
);
```
## Reference [#reference]
```typescript
function buildReactFiles(
findSpriteResult: FindSpritesResult,
inputPath: string,
outputPath: string
): void
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ------------------ | ------------------- | ----------------------------------------------------------------------------------- |
| `findSpriteResult` | `FindSpritesResult` | Result from `findSprites` containing sprite metadata. |
| `inputPath` | `string` | Original input directory path, used for determining component naming prefixes. |
| `outputPath` | `string` | Directory where React component files will be written. Created if it doesn't exist. |
### Returns [#returns]
Returns `void`. Components are written to the file system synchronously.
### Type Parameters [#type-parameters]
```typescript
type FindSpritesResult = Result<FindSpritesOutput, ErrorPath>;
```
## Examples [#examples]
### Example: Generate components from directory [#example-generate-components-from-directory]
```typescript
import { buildReactFiles } from '@accelint/smeegl/build-react-files';
import { findSprites } from '@accelint/smeegl/utils/find-sprites';
import { makeTempDirectory } from '@accelint/smeegl/utils/make-temp-directory';
const tmpDir = await makeTempDirectory();
const findResult = await findSprites('', './assets/icons', process.cwd(), tmpDir);
buildReactFiles(
findResult,
'./assets/icons',
'./src/components/icons'
);
// Output:
// - SvgArrow.tsx
// - SvgArrowDown.tsx
// - index.ts (barrel export)
```
### Example: Component structure [#example-component-structure]
Generated components follow this pattern:
```tsx
// SvgArrow.tsx
import type { SVGProps } from 'react';
interface Props {
title?: string;
titleId?: string;
}
export const SvgArrow = ({
title,
titleId,
...props
}: SVGProps<SVGSVGElement> & Props) => {
const { fill } = props;
const fillColor = fill ?? '#FF69B4';
const hasTitle = typeof title === 'string' && Boolean(title.trim());
return (
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none">
{hasTitle && <title id={titleId}>{title}}
);
};
```
### Example: Using generated components [#example-using-generated-components]
```tsx
import { SvgArrow, SvgArrowDown } from './components/icons';
function App() {
return (
);
}
```
### Example: Nested directory structure [#example-nested-directory-structure]
```typescript
import { buildReactFiles } from '@accelint/smeegl/build-react-files';
// Input structure:
// ./icons/
// ui/arrow.svg
// ui/chevron.svg
// social/github.svg
buildReactFiles(findResult, './icons', './components');
// Output:
// - SvgUiArrow.tsx
// - SvgUiChevron.tsx
// - SvgSocialGithub.tsx
// - index.ts
```
> **Good to know:** The function assumes SVG files have a single fill color set to `#FF69B4` or any non-`none` value, which will be replaced with the component's `fill` prop. SVG attributes are automatically converted from kebab-case to camelCase.
## Generated Files [#generated-files]
### Component Files [#component-files]
Each SVG generates a TypeScript React component with:
* TypeScript strict mode support
* SVG props inheritance
* Optional `title` and `titleId` for accessibility
* Customizable `fill` color (defaults to `#FF69B4`)
### index.ts [#indexts]
Barrel export file:
```typescript
export { SvgArrow } from './arrow';
export { SvgArrowDown } from './arrow-down';
```
## Component Naming [#component-naming]
Components are named using PascalCase with "Svg" prefix:
* `arrow.svg` → `SvgArrow`
* `arrow-down.svg` → `SvgArrowDown`
* `ui/arrow.svg` → `SvgUiArrow`
Parent directory names are included when present to ensure unique component names.
## Related [#related]
* [buildSpritesheet](./build-spritesheet.mdx) - Generate spritesheet files
* [findSprites](./utils/find-sprites.mdx) - Find and catalog SVG files
* [mergeSvgIntoReactTemplate](./utils/merge-svg-into-react-template.mdx) - SVG to React transformation
* [pascalCase](./utils/pascal-case.mdx) - Component name formatting
# buildSpritesheet (/docs/tooling/smeegl/build-spritesheet)
Generate spritesheet files (JSON, PNG, and TypeScript constants) from SVG sprites using the spreet tool.
## Usage [#usage]
```typescript
import { buildSpritesheet } from '@accelint/smeegl/build-spritesheet';
import { findSprites } from '@accelint/smeegl/utils/find-sprites';
// First find sprites
const findResult = await findSprites('**/*.svg', './icons', process.cwd(), tmpDir);
// Then build spritesheet
await buildSpritesheet(
findResult, // Result from findSprites
'HEX', // CRC naming mode
'spreet', // Spreet binary path
'./output/atlas' // Output path
);
```
## Reference [#reference]
```typescript
async function buildSpritesheet(
findSpriteResult: FindSpritesResult,
crcMode: CrcType | null,
cmd: string,
out: string
): Promise
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ------------------ | ------------------- | -------------------------------------------------------------------------------------------- |
| `findSpriteResult` | `FindSpritesResult` | Result from `findSprites` containing sprite metadata and temp directory path. |
| `crcMode` | `CrcType \| null` | Enable CRC32 naming: `'DEC'` (decimal) or `'HEX'` (hexadecimal). `null` disables CRC naming. |
| `cmd` | `string` | Path or command name for the spreet binary (e.g., `'spreet'` or `'./bin/spreet'`). |
| `out` | `string` | Output path without extension. Generates `{out}.json`, `{out}.png`, and `{out}.ts`. |
### Returns [#returns]
Returns a `Promise`. The function orchestrates the spritesheet generation pipeline and handles cleanup automatically.
### Type Parameters [#type-parameters]
```typescript
type CrcType = 'DEC' | 'HEX';
type FindSpritesResult = Result;
```
## Examples [#examples]
### Example: Generate spritesheet with default naming [#example-generate-spritesheet-with-default-naming]
```typescript
import { buildSpritesheet } from '@accelint/smeegl/build-spritesheet';
import { findSprites } from '@accelint/smeegl/utils/find-sprites';
import { makeTempDirectory } from '@accelint/smeegl/utils/make-temp-directory';
const tmpDir = await makeTempDirectory();
const findResult = await findSprites('**/*.svg', './icons', process.cwd(), tmpDir);
await buildSpritesheet(
findResult,
null, // Use original sprite names
'spreet',
'./atlas'
);
// Output files:
// - atlas.json (sprite coordinates)
// - atlas.png (packed image)
// - atlas.ts (TypeScript constants)
```
### Example: Generate with CRC32 hexadecimal naming [#example-generate-with-crc32-hexadecimal-naming]
```typescript
import { buildSpritesheet } from '@accelint/smeegl/build-spritesheet';
await buildSpritesheet(
findResult,
'HEX', // Convert names to hex CRC32
'spreet',
'./atlas'
);
// atlas.ts exports:
// export const SPRITE_A1B2C3D4 = 'a1b2c3d4';
```
### Example: Using custom spreet binary [#example-using-custom-spreet-binary]
```typescript
import { buildSpritesheet } from '@accelint/smeegl/build-spritesheet';
await buildSpritesheet(
findResult,
null,
'/usr/local/bin/spreet', // Custom binary path
'./output/sprites'
);
```
### Example: Complete workflow [#example-complete-workflow]
```typescript
import { buildSpritesheet } from '@accelint/smeegl/build-spritesheet';
import { findSprites } from '@accelint/smeegl/utils/find-sprites';
import { makeTempDirectory } from '@accelint/smeegl/utils/make-temp-directory';
async function generateSprites() {
const tmpDir = await makeTempDirectory();
const findResult = await findSprites(
'', // No glob
'./src/assets/icons',
process.cwd(),
tmpDir
);
await buildSpritesheet(
findResult,
null,
'spreet',
'./public/atlas'
);
console.log('Spritesheet generated successfully!');
}
```
> **Good to know:** The function automatically handles temporary directory cleanup on success or failure. The spreet binary must be installed and accessible at the specified path.
## Output Files [#output-files]
### atlas.json [#atlasjson]
Sprite index file with coordinates:
```json
{
"arrow": {"height": 48, "pixelRatio": 2, "width": 48, "x": 0, "y": 0},
"arrow-down": {"height": 48, "pixelRatio": 2, "width": 48, "x": 0, "y": 48}
}
```
### atlas.png [#atlaspng]
Packed spritesheet image containing all sprites.
### atlas.ts [#atlasts]
TypeScript constants for sprite names:
```typescript
export const ARROW = 'arrow';
export const ARROW_DOWN = 'arrow-down';
```
## Related [#related]
* [buildReactFiles](./build-react-files.mdx) - Generate React SVG components
* [findSprites](./utils/find-sprites.mdx) - Find and catalog SVG files
* [makeTempDirectory](./utils/make-temp-directory.mdx) - Create temporary working directory
# Overview (/docs/tooling/smeegl)
## Installation [#installation]
### Prerequisites [#prerequisites]
The [spreet](https://github.com/flother/spreet) utility is required. Install via:
```bash
# Homebrew
brew install flother/taps/spreet
# Cargo
cargo install spreet
```
For other installation methods, see the [official instructions](https://github.com/flother/spreet?tab=readme-ov-file#installation).
### Install smeegl [#install-smeegl]
```bash
# Global installation
npm install -g @accelint/smeegl
# Local installation
pnpm install @accelint/smeegl
```
## Usage [#usage]
```bash
# Generate spritesheet from directory
smeegl --in ~/icons --out ~/atlas --target SPRITESHEET
# Generate React components from directory
smeegl --in ~/icons --out ~/components --target REACT
# Use glob pattern (no ~/ support)
smeegl --glob "/Users/me/icons/**/*.svg" --out ~/atlas --target SPRITESHEET
```
### CLI Options [#cli-options]
| Option | Description | Choices | Default |
| ---------- | ----------------------------- | ---------------------- | ------------- |
| `--target` | Output type | `SPRITESHEET`, `REACT` | `SPRITESHEET` |
| `--in` | Input directory path | | |
| `--out` | Output directory path | | `./atlas` |
| `--glob` | SVG glob pattern | | |
| `--crc` | Convert sprite names to CRC32 | `DEC`, `HEX` | |
| `--spreet` | Path to spreet binary | | `spreet` |
## Output Formats [#output-formats]
### Spritesheet Output [#spritesheet-output]
Generates three files:
**1. atlas.png** - Sprite atlas texture
**2. atlas.json** - Sprite index with coordinates
```json
{
"arrow": {"height": 48, "pixelRatio": 2, "width": 48, "x": 0, "y": 0},
"arrow-down": {"height": 48, "pixelRatio": 2, "width": 48, "x": 0, "y": 48}
}
```
**3. atlas.ts** - TypeScript constants
```typescript
export const ARROW = 'arrow'
export const ARROW_DOWN = 'arrow-down'
```
### React Component Output [#react-component-output]
Generates a folder of React SVG components with TypeScript types:
```tsx
// arrow.tsx
export const SvgArrow = ({
title,
titleId,
...props
}: SVGProps & Props) => {
const { fill } = props;
const fillColor = fill ?? '#FF69B4'
const hasTitle = typeof title === 'string' && Boolean(title.trim());
return (
)
};
```
```typescript
// index.ts
export { SvgArrow } from './arrow';
export { SvgArrowDown } from './arrow-down';
```
## File Naming Rules [#file-naming-rules]
### Character Normalization [#character-normalization]
* **Constants file**: `CONSTANT_CASE` (e.g., `ARROW_DOWN`)
* **Index file**: `snake_case` (e.g., `arrow_down`)
* Directory separators and spaces → single underscore `_`
* Parentheses are removed
### Directory Structure Handling [#directory-structure-handling]
**Flat directory** (no subfolders):
```
icons/
├── a.svg
└── b.svg
```
```typescript
export const A = 'a'
export const B = 'b'
```
**Nested directories**:
```
icons/
├── group1/
│ ├── a.svg
│ └── b.svg
└── group2/
├── c.svg
└── d.svg
```
```typescript
export const GROUP1_A = 'group1_a'
export const GROUP1_B = 'group1_b'
export const GROUP2_C = 'group2_c'
export const GROUP2_D = 'group2_d'
```
## Programmatic Usage [#programmatic-usage]
The core functions are also available as a library for programmatic usage. See the individual API pages for details:
* [buildSpritesheet](./build-spritesheet.mdx) - Generate spritesheet files programmatically
* [buildReactFiles](./build-react-files.mdx) - Generate React components programmatically
## SVG Requirements [#svg-requirements]
For React component generation:
* Icons should use a single fill color
* Fill colors (except `none`) are replaced with component prop
* Default fill: `#FF69B4` (can be overridden)
* SVG attributes are converted from `kebab-case` to `camelCase`
* `` element added for accessibility
## Examples [#examples]
### Example 1: Generate Deck.gl Spritesheet [#example-1-generate-deckgl-spritesheet]
```bash
smeegl \
--in ~/design-system/icons \
--out ~/app/public/sprites/ui \
--target SPRITESHEET
```
### Example 2: Generate React Icon Library [#example-2-generate-react-icon-library]
```bash
smeegl \
--in ~/figma-exports/icons \
--out ~/app/src/components/icons \
--target REACT
```
### Example 3: Use Glob with CRC Names [#example-3-use-glob-with-crc-names]
```bash
smeegl \
--glob "/Users/me/assets/**/*.svg" \
--out ~/sprites/hashed \
--target SPRITESHEET \
--crc HEX
```
### Example 4: Custom Spreet Binary [#example-4-custom-spreet-binary]
```bash
smeegl \
--in ~/icons \
--out ~/atlas \
--spreet ./bin/spreet-custom
```
## Related [#related]
* [buildSpritesheet](./build-spritesheet.mdx) - Spritesheet generation core
* [buildReactFiles](./build-react-files.mdx) - React component generation core
* [smeegl](./lib.mdx) - Programmatic API
* [validateInput](./validate-input.mdx) - Input validation utilities
* [logMsg](./log-messages.mdx) - Logging utilities
# smeegl (/docs/tooling/smeegl/lib)
## Usage [#usage]
```typescript
import { smeegl } from '@accelint/smeegl/lib';
// Generate spritesheet
await smeegl(
process.cwd(),
'**/*.svg',
'./atlas',
'spreet',
null,
'./icons',
'',
'SPRITESHEET'
);
// Generate React components
await smeegl(
process.cwd(),
'',
'./components',
'spreet',
null,
'./icons',
'',
'REACT'
);
```
## Reference [#reference]
```typescript
async function smeegl(
rootPath: string,
glob: string,
out: string,
spreet?: string,
crcMode?: CrcType | null,
inOpt?: string,
outOpt?: string,
target?: TargetType
): Promise<void>
```
### Parameters [#parameters]
| Parameter | Type | Description | Default |
| ---------- | ----------------------- | ------------------------------------------------------------------------ | --------------- |
| `rootPath` | `string` | Root directory path for resolving relative paths | |
| `glob` | `string` | Glob pattern for finding SVG files. Can be blank if `inOpt` is provided. | |
| `out` | `string` | Base output path for generated files | |
| `spreet` | `string` \| `undefined` | Path to spreet binary | `'spreet'` |
| `crcMode` | `CrcType` \| `null` | Convert sprite names to CRC32 (`'DEC'` or `'HEX'`) | `null` |
| `inOpt` | `string` | Input directory to scan for SVG files (alternative to glob) | `''` |
| `outOpt` | `string` | Override output path (takes precedence over `out`) | `''` |
| `target` | `TargetType` | Output type: `'SPRITESHEET'` or `'REACT'` | `'SPRITESHEET'` |
### Returns [#returns]
Returns a `Promise<void>` that resolves when generation is complete.
### Type Parameters [#type-parameters]
**CrcType**: `'DEC' | 'HEX'`
* Controls whether CRC32 sprite names use decimal or hexadecimal encoding
**TargetType**: `'SPRITESHEET' | 'REACT'`
* `SPRITESHEET` - Generates PNG atlas + JSON index + TypeScript constants
* `REACT` - Generates folder of React SVG components
## Examples [#examples]
### Example: Generate spritesheet with glob pattern [#example-generate-spritesheet-with-glob-pattern]
```typescript
import { smeegl } from '@accelint/smeegl/lib';
import { fileURLToPath } from 'node:url';
import { dirname } from 'node:path';
const __dirname = dirname(fileURLToPath(import.meta.url));
await smeegl(
__dirname, // rootPath
'assets/icons/**/*.svg', // glob pattern
'./public/sprites', // output path
'spreet', // spreet binary
null, // no CRC encoding
'', // no input dir (using glob)
'', // no output override
'SPRITESHEET' // target type
);
// Generates:
// ./public/sprites/atlas.png
// ./public/sprites/atlas.json
// ./public/sprites/atlas.ts
```
### Example: Generate React components from directory [#example-generate-react-components-from-directory]
```typescript
import { smeegl } from '@accelint/smeegl/lib';
await smeegl(
process.cwd(),
'', // no glob (using directory)
'./src/components/icons', // output path
'spreet',
null,
'./design-system/icons', // input directory
'',
'REACT'
);
// Generates:
// ./src/components/icons/arrow.tsx
// ./src/components/icons/arrow-down.tsx
// ./src/components/icons/index.ts
```
### Example: CRC-encoded sprite names [#example-crc-encoded-sprite-names]
```typescript
import { smeegl } from '@accelint/smeegl/lib';
await smeegl(
process.cwd(),
'icons/**/*.svg',
'./sprites',
'spreet',
'HEX', // Use hexadecimal CRC32
'',
'',
'SPRITESHEET'
);
// Sprite names become CRC32 hashes:
// arrow.svg → a3f2d4e1
// arrow-down.svg → b7c8e9f3
```
### Example: Custom spreet binary path [#example-custom-spreet-binary-path]
```typescript
import { smeegl } from '@accelint/smeegl/lib';
await smeegl(
process.cwd(),
'icons/**/*.svg',
'./atlas',
'/usr/local/bin/spreet-custom', // Custom binary
null,
'',
'',
'SPRITESHEET'
);
```
### Example: Build script integration [#example-build-script-integration]
```typescript
// build-sprites.ts
import { smeegl } from '@accelint/smeegl/lib';
async function buildSprites() {
console.log('Building spritesheets...');
await smeegl(
process.cwd(),
'assets/ui/**/*.svg',
'./public/sprites/ui',
'spreet',
null,
'',
'',
'SPRITESHEET'
);
await smeegl(
process.cwd(),
'assets/markers/**/*.svg',
'./public/sprites/markers',
'spreet',
'HEX',
'',
'',
'SPRITESHEET'
);
console.log('✓ Spritesheets built');
}
buildSprites().catch(console.error);
```
> **Good to know:** The function validates input parameters and creates temporary directories automatically. Errors during generation are thrown as exceptions.
> **Good to know:** When `glob` is empty, `inOpt` must be a valid directory path. When `glob` is provided, it takes precedence over `inOpt`.
## Related [#related]
* [buildSpritesheet](./build-spritesheet.mdx) - Core spritesheet generation logic
* [buildReactFiles](./build-react-files.mdx) - Core React component generation logic
* [validateInput](./validate-input.mdx) - Input validation utilities
# log-messages (/docs/tooling/smeegl/log-messages)
## Usage [#usage]
```typescript
import { logMsg, logWarning } from '@accelint/smeegl/log-messages';
import ora from 'ora';
const spinner = ora('Processing...');
// Log success message
logMsg('Processing complete', spinner);
// Log warning message
logWarning('File already exists, skipping', spinner);
// Without spinner
logMsg('Operation successful', null);
```
## Reference [#reference]
### logMsg [#logmsg]
```typescript
function logMsg(
msg: string,
spinner: Ora | null | undefined
): void
```
Logs a success message. With a spinner, updates the spinner text and shows a success indicator. Without a spinner, logs to console with a checkmark prefix.
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------------------------- | ------------------------------------------------------------------------- |
| `msg` | `string` | The message to log. |
| `spinner` | `Ora \| null \| undefined` | Optional ora spinner instance. If provided, uses spinner's success state. |
### logWarning [#logwarning]
```typescript
function logWarning(
msg: string,
spinner: Ora | null | undefined
): void
```
Logs a warning message. With a spinner, updates the spinner text and shows a warning indicator. Without a spinner, logs to console with a warning emoji prefix.
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | -------------------------- | ---------------------------------------------------------------------- |
| `msg` | `string` | The warning message to log. |
| `spinner` | `Ora \| null \| undefined` | Optional ora spinner instance. If provided, uses spinner's warn state. |
## Examples [#examples]
### Example: Using with spinner [#example-using-with-spinner]
```typescript
import { logMsg, logWarning } from '@accelint/smeegl/log-messages';
import ora from 'ora';
async function processFiles() {
const spinner = ora('Finding files').start();
// ... file search logic ...
logMsg('Found 42 files', spinner);
spinner.text = 'Processing files';
spinner.start();
// ... processing logic ...
logWarning('Skipped 3 invalid files', spinner);
logMsg('Successfully processed 39 files', spinner);
}
```
### Example: Console-only logging [#example-console-only-logging]
```typescript
import { logMsg, logWarning } from '@accelint/smeegl/log-messages';
function validateConfig(config: unknown) {
if (!config) {
logWarning('Config is empty, using defaults', null);
// Output: ⚠️ Config is empty, using defaults
}
logMsg('Configuration validated', null);
// Output: ✅ Configuration validated
}
```
### Example: Conditional spinner usage [#example-conditional-spinner-usage]
```typescript
import { logMsg } from '@accelint/smeegl/log-messages';
import ora from 'ora';
function log(message: string, useSpinner: boolean) {
const spinner = useSpinner ? ora().start() : null;
logMsg(message, spinner);
}
// With spinner
log('Processing...', true);
// Without spinner
log('Done', false);
```
### Example: Multiple messages with single spinner [#example-multiple-messages-with-single-spinner]
```typescript
import { logMsg, logWarning } from '@accelint/smeegl/log-messages';
import ora from 'ora';
async function build() {
const spinner = ora();
spinner.text = 'Compiling TypeScript';
spinner.start();
await compileTypeScript();
logMsg('TypeScript compiled', spinner);
spinner.text = 'Bundling assets';
spinner.start();
await bundleAssets();
logWarning('Some assets were already bundled', spinner);
spinner.text = 'Copying files';
spinner.start();
await copyFiles();
logMsg('Build complete', spinner);
}
```
> **Good to know:** When a spinner is provided, the function calls `spinner.start()` before showing the message. This ensures the spinner is active even if it was previously stopped.
## Output Format [#output-format]
### With Spinner [#with-spinner]
* `logMsg`: Updates spinner with success state (green checkmark)
* `logWarning`: Updates spinner with warning state (yellow warning icon)
### Without Spinner [#without-spinner]
* `logMsg`: `✅ {message}`
* `logWarning`: `⚠️ {message}`
## Related [#related]
* [buildSpritesheet](./build-spritesheet.mdx) - Uses logging for build progress
* [buildReactFiles](./build-react-files.mdx) - Uses logging for generation progress
# validateInput (/docs/tooling/smeegl/validate-input)
Validate glob pattern and input directory parameters, ensuring only one input method is provided and that inputs meet requirements.
## Usage [#usage]
```typescript
import { validateInput } from '@accelint/smeegl/validate-input';
// Valid: using glob pattern
validateInput('src/icons/**/*.svg', null);
// Valid: using input directory
validateInput(null, './icons');
// Invalid: both provided (exits process)
validateInput('**/*.svg', './icons'); // Error: Both glob pattern and input directory provided
```
## Reference [#reference]
```typescript
function validateInput(
glob: string | null,
inputPath: string | null
): void
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ----------- | ---------------- | ------------------------------------------------------------------------------------ |
| `glob` | `string \| null` | Glob pattern for matching SVG files. Should end with `.svg`. Cannot use `~/` prefix. |
| `inputPath` | `string \| null` | Directory path to scan for SVG files. Must exist on the filesystem. |
### Returns [#returns]
Returns `void`. Exits the process with `process.exit(1)` if validation fails.
## Examples [#examples]
### Example: Valid glob pattern [#example-valid-glob-pattern]
```typescript
import { validateInput } from '@accelint/smeegl/validate-input';
// Valid glob patterns
validateInput('src/icons/**/*.svg', null);
validateInput('/absolute/path/icons/**/*.svg', null);
```
### Example: Valid input directory [#example-valid-input-directory]
```typescript
import { validateInput } from '@accelint/smeegl/validate-input';
// Valid directory paths
validateInput(null, './src/icons');
validateInput(null, '/absolute/path/icons');
```
### Example: Validation errors [#example-validation-errors]
```typescript
import { validateInput } from '@accelint/smeegl/validate-input';
// Error: Both provided
validateInput('**/*.svg', './icons');
// Output: Error: Both glob pattern and input directory provided; Please use only one
// Process exits with code 1
// Error: Neither provided
validateInput(null, null);
// Output: Error: No glob pattern or input directory provided
// Process exits with code 1
// Error: Tilde in glob pattern
validateInput('~/icons/**/*.svg', null);
// Output: Error: Please expand the glob pattern to an absolute path before running this command.
// Process exits with code 1
// Warning: Missing .svg extension
validateInput('icons/**/*', null);
// Output: Warning: The glob pattern should end with .svg for best results
// Continues execution
// Error: Directory doesn't exist
validateInput(null, './nonexistent');
// Output: Error: The specified input directory does not exist
// Process exits with code 1
```
## Validation Rules [#validation-rules]
### Mutual Exclusivity [#mutual-exclusivity]
* **Cannot provide both** glob and inputPath
* **Must provide one** of glob or inputPath
### Glob Pattern Rules [#glob-pattern-rules]
* **Should end with `.svg`** (warning if missing)
* **Cannot start with `~/`** (tilde expansion not supported)
* Use absolute paths or relative paths starting with `./` or `../`
### Input Directory Rules [#input-directory-rules]
* **Must exist** on the filesystem
* Checked with `fs.existsSync()`
> **Good to know:** This function calls `process.exit(1)` on validation failure. Use it in CLI contexts, not in library code where you need to handle errors programmatically.
## Error Messages [#error-messages]
| Condition | Message | Exit Code |
| -------------------------------- | ---------------------------------------------------------------------------------------- | -------------- |
| Both glob and inputPath provided | "Error: Both glob pattern and input directory provided; Please use only one" | 1 |
| Neither provided | "Error: No glob pattern or input directory provided" | 1 |
| Glob starts with `~/` | "Error: Please expand the glob pattern to an absolute path before running this command." | 1 |
| Directory doesn't exist | "Error: The specified input directory does not exist" | 1 |
| Glob missing `.svg` | "Warning: The glob pattern should end with .svg for best results" | None (warning) |
## Related [#related]
* [smeegl](./lib.mdx) - Main entry point that uses validation
* [findSprites](./utils/find-sprites.mdx) - Find sprites after validation passes
# Bundler Configurations (/docs/tooling/typescript-config/bundler)
## Usage [#usage]
Use bundler configurations when your project:
* Uses Vite, Webpack, esbuild, Rollup, or similar bundlers
* Only needs TypeScript for type checking (bundler handles compilation)
* Doesn't output JavaScript from `tsc`
* Wants faster type checking (no emit)
```json
{
"extends": "@accelint/typescript-config/bundler/dom/app",
"compilerOptions": {
"jsx": "react-jsx"
},
"include": ["src"]
}
```
## Available Configurations [#available-configurations]
### DOM (Browser) Environments [#dom-browser-environments]
#### `bundler/dom` (alias: `bundler/dom/app`) [#bundlerdom-alias-bundlerdomapp]
For web applications using bundlers.
```json
{
"extends": "@accelint/typescript-config/bundler/dom"
}
```
**Key settings:**
* `module: "preserve"` - Preserves import/export syntax for bundler
* `noEmit: true` - No JavaScript output (bundler handles this)
* `lib: ["es2022", "dom", "dom.iterable"]` - Browser APIs available
**Use for:** Vite apps, Webpack apps, React/Vue/Svelte projects
> **Good to know:** `bundler/dom` and `bundler/dom/app` point to the same configuration file. Use whichever path is clearer in your project.
#### `bundler/dom/library` [#bundlerdomlibrary]
For browser libraries compiled by bundlers.
```json
{
"extends": "@accelint/typescript-config/bundler/dom/library"
}
```
**Key settings:**
* Same as `bundler/dom` plus:
* `declaration: true` - Generates `.d.ts` files (even with `noEmit`)
* Type-only output for consumers
**Use for:** React component libraries built with Vite, UI kits with Rollup
#### `bundler/dom/library-monorepo` [#bundlerdomlibrary-monorepo]
For browser libraries within a monorepo using bundlers.
```json
{
"extends": "@accelint/typescript-config/bundler/dom/library-monorepo"
}
```
**Key settings:**
* Same as `bundler/dom/library` plus:
* `composite: true` - Enables project references
* `incremental: true` - Faster rebuilds
**Use for:** Design systems, component libraries in monorepos
### No-DOM (Node.js) Environments [#no-dom-nodejs-environments]
#### `bundler/no-dom` (alias: `bundler/no-dom/app`) [#bundlerno-dom-alias-bundlerno-domapp]
For Node.js applications using bundlers.
```json
{
"extends": "@accelint/typescript-config/bundler/no-dom"
}
```
**Key settings:**
* `module: "preserve"` - Preserves import/export syntax
* `noEmit: true` - No JavaScript output
* `lib: ["es2022"]` - No DOM types (Node.js only)
**Use for:** Node.js apps bundled with esbuild, serverless functions
> **Good to know:** `bundler/no-dom` and `bundler/no-dom/app` point to the same configuration file.
#### `bundler/no-dom/library` [#bundlerno-domlibrary]
For Node.js libraries compiled by bundlers.
```json
{
"extends": "@accelint/typescript-config/bundler/no-dom/library"
}
```
**Key settings:**
* Same as `bundler/no-dom` plus:
* `declaration: true` - Generates `.d.ts` files
**Use for:** Node.js packages built with bundlers
#### `bundler/no-dom/library-monorepo` [#bundlerno-domlibrary-monorepo]
For Node.js libraries within a monorepo using bundlers.
```json
{
"extends": "@accelint/typescript-config/bundler/no-dom/library-monorepo"
}
```
**Key settings:**
* Same as `bundler/no-dom/library` plus:
* `composite: true` - Enables project references
* `incremental: true` - Faster rebuilds
**Use for:** Backend monorepo packages, shared utilities built with bundlers
## Key Compiler Options [#key-compiler-options]
All bundler configurations include:
```json
{
"compilerOptions": {
"module": "preserve",
"noEmit": true
}
}
```
| Option | Value | Reason |
| -------- | ------------ | ----------------------------------------------------- |
| `module` | `"preserve"` | Preserves ESM syntax for bundler to handle |
| `noEmit` | `true` | No JS output - bundler compiles, tsc only type checks |
> **Good to know:** `module: "preserve"` is a TypeScript 5.4+ option that preserves your exact import/export syntax, letting the bundler handle module transformation. This is faster than `tsc` emitting JavaScript.
## Examples [#examples]
### Example: Vite + React application [#example-vite--react-application]
```json
{
"extends": "@accelint/typescript-config/bundler/dom/app",
"compilerOptions": {
"jsx": "react-jsx",
"paths": {
"@/*": ["./src/*"]
}
},
"include": ["src"]
}
```
**package.json scripts:**
```json
{
"scripts": {
"dev": "vite",
"build": "tsc --noEmit && vite build",
"preview": "vite preview"
}
}
```
### Example: Next.js application [#example-nextjs-application]
```json
{
"extends": "@accelint/typescript-config/bundler/dom/app",
"compilerOptions": {
"jsx": "preserve",
"plugins": [
{
"name": "next"
}
],
"paths": {
"@/*": ["./src/*"]
}
},
"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
"exclude": ["node_modules"]
}
```
### Example: Svelte + Vite application [#example-svelte--vite-application]
```json
{
"extends": "@accelint/typescript-config/bundler/dom/app",
"compilerOptions": {
"types": ["vite/client"]
},
"include": ["src/**/*.ts", "src/**/*.svelte"],
"exclude": ["node_modules"]
}
```
### Example: React component library (tsup) [#example-react-component-library-tsup]
```json
{
"extends": "@accelint/typescript-config/bundler/dom/library",
"compilerOptions": {
"jsx": "react-jsx",
"outDir": "./dist",
"declarationDir": "./dist/types"
},
"include": ["src"]
}
```
**tsup.config.ts:**
```typescript
import { defineConfig } from 'tsup';
export default defineConfig({
entry: ['src/index.ts'],
format: ['esm', 'cjs'],
dts: false, // TypeScript handles .d.ts via declaration: true
splitting: false,
sourcemap: true,
clean: true,
});
```
### Example: Node.js serverless function (esbuild) [#example-nodejs-serverless-function-esbuild]
```json
{
"extends": "@accelint/typescript-config/bundler/no-dom/app",
"compilerOptions": {
"types": ["node"]
},
"include": ["src"]
}
```
**esbuild command:**
```bash
esbuild src/index.ts --bundle --platform=node --outfile=dist/index.js
```
### Example: Monorepo component library (Vite) [#example-monorepo-component-library-vite]
```json
{
"extends": "@accelint/typescript-config/bundler/dom/library-monorepo",
"compilerOptions": {
"jsx": "react-jsx",
"composite": true,
"outDir": "./dist",
"declarationDir": "./dist/types"
},
"include": ["src"],
"references": [
{ "path": "../design-tokens" },
{ "path": "../utils" }
]
}
```
### Example: Webpack + TypeScript [#example-webpack--typescript]
```json
{
"extends": "@accelint/typescript-config/bundler/dom/app",
"compilerOptions": {
"jsx": "react-jsx",
"baseUrl": ".",
"paths": {
"@components/*": ["src/components/*"],
"@utils/*": ["src/utils/*"]
}
},
"include": ["src"]
}
```
**webpack.config.js:**
```javascript
module.exports = {
module: {
rules: [
{
test: /\.tsx?$/,
use: 'ts-loader',
exclude: /node_modules/,
},
],
},
resolve: {
extensions: ['.tsx', '.ts', '.js'],
},
};
```
### Example: Astro project [#example-astro-project]
```json
{
"extends": "@accelint/typescript-config/bundler/dom/app",
"compilerOptions": {
"jsx": "preserve",
"types": ["astro/client"]
},
"include": ["src/**/*"],
"exclude": ["dist", "node_modules"]
}
```
## Common Overrides [#common-overrides]
### Enable Type-Only Declarations [#enable-type-only-declarations]
For libraries that need `.d.ts` files but use a bundler:
```json
{
"extends": "@accelint/typescript-config/bundler/dom/library",
"compilerOptions": {
"declaration": true,
"declarationDir": "./dist/types",
"emitDeclarationOnly": true
}
}
```
### Add Custom Path Aliases [#add-custom-path-aliases]
```json
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"],
"@components/*": ["./src/components/*"],
"@utils/*": ["./src/utils/*"],
"@hooks/*": ["./src/hooks/*"]
}
}
}
```
**Vite config** (must mirror paths):
```typescript
import { defineConfig } from 'vite';
import path from 'path';
export default defineConfig({
resolve: {
alias: {
'@': path.resolve(__dirname, './src'),
'@components': path.resolve(__dirname, './src/components'),
'@utils': path.resolve(__dirname, './src/utils'),
'@hooks': path.resolve(__dirname, './src/hooks'),
},
},
});
```
### Configure JSX [#configure-jsx]
For React 17+ (automatic runtime):
```json
{
"compilerOptions": {
"jsx": "react-jsx"
}
}
```
For React 17 or older (classic runtime):
```json
{
"compilerOptions": {
"jsx": "react"
}
}
```
For Preact:
```json
{
"compilerOptions": {
"jsx": "react-jsx",
"jsxImportSource": "preact"
}
}
```
### Add Bundler-Specific Types [#add-bundler-specific-types]
For Vite:
```json
{
"compilerOptions": {
"types": ["vite/client"]
}
}
```
For Webpack:
```json
{
"compilerOptions": {
"types": ["webpack-env"]
}
}
```
## Bundler vs TSC: When to Use Each [#bundler-vs-tsc-when-to-use-each]
| Scenario | Use Bundler Config | Use TSC Config |
| ---------------------------------- | ------------------------------- | ----------------- |
| Vite/Webpack project | ✅ Yes | ❌ No |
| Need `.d.ts` files for npm package | ⚠️ Yes (library variant) | ✅ Yes (preferred) |
| Fast type checking only | ✅ Yes | ❌ No |
| Compile to multiple module formats | ❌ No | ✅ Yes |
| Next.js / Astro / SvelteKit | ✅ Yes | ❌ No |
| Pure Node.js CLI (no bundler) | ❌ No | ✅ Yes |
| Monorepo with incremental builds | ✅ Either (use library-monorepo) | ✅ Either |
> **Good to know:** Bundler configs are faster for type checking because `noEmit: true` skips JavaScript generation. However, TSC configs give you more control over output formats and declaration files.
## Related [#related]
* [TSC Configurations](./tsc.mdx) - For projects using TypeScript Compiler directly
* [Overview](./) - Decision guide and core options
* [Vite Configuration](https://vitejs.dev/config/) - Vite official docs
* [Webpack TypeScript Guide](https://webpack.js.org/guides/typescript/) - Webpack integration
# Overview (/docs/tooling/typescript-config)
## Installation [#installation]
```bash
# Using pnpm (recommended)
pnpm add -D @accelint/typescript-config
# Using npm
npm install --save-dev @accelint/typescript-config
# Using yarn
yarn add -D @accelint/typescript-config
```
## Usage [#usage]
Extend the appropriate configuration in your `tsconfig.json`:
```json
{
"extends": "@accelint/typescript-config/bundler/dom/app",
"compilerOptions": {
"outDir": "./dist"
},
"include": ["src"]
}
```
## Which Configuration Should I Use? [#which-configuration-should-i-use]
Choose based on three factors:
### 1. Build Tool [#1-build-tool]
**Do you use `tsc` for compilation, or a bundler?**
* **[TSC](./tsc.mdx)** - Projects using TypeScript Compiler directly
* Outputs JavaScript files
* Generates declaration files (`.d.ts`)
* Full type checking + compilation
* **[Bundler](./bundler.mdx)** - Projects using Vite, Webpack, esbuild, etc.
* Type checking only (bundler handles compilation)
* No JavaScript output from tsc
* Faster type checking
### 2. Runtime Environment [#2-runtime-environment]
**Does your code run in the browser or Node.js?**
* **DOM** - Browser environments (web apps, client-side libraries)
* Includes DOM type definitions
* `window`, `document`, Web APIs available
* **No-DOM** - Node.js environments (servers, CLI tools, backend libraries)
* No browser APIs
* Node.js-specific types only
### 3. Project Type [#3-project-type]
**Is this an application or a publishable package?**
* **App** - Applications (not published to npm)
* No declaration file generation
* Faster builds
* **Library** - Standalone packages (published to npm)
* Generates `.d.ts` files
* Strict settings for consumers
* **Library-Monorepo** - Packages within a monorepo
* Composite project support
* Incremental builds
* Project references
## Configuration Reference [#configuration-reference]
| Configuration | Build Tool | Environment | Project Type |
| --------------------------------- | ---------- | ----------- | ---------------- |
| `tsc/dom/app` | TSC | Browser | Application |
| `tsc/dom/library` | TSC | Browser | Library |
| `tsc/dom/library-monorepo` | TSC | Browser | Monorepo Package |
| `tsc/no-dom/app` | TSC | Node.js | Application |
| `tsc/no-dom/library` | TSC | Node.js | Library |
| `tsc/no-dom/library-monorepo` | TSC | Node.js | Monorepo Package |
| `bundler/dom` | Bundler | Browser | Application |
| `bundler/dom/app` | Bundler | Browser | Application |
| `bundler/dom/library` | Bundler | Browser | Library |
| `bundler/dom/library-monorepo` | Bundler | Browser | Monorepo Package |
| `bundler/no-dom` | Bundler | Node.js | Application |
| `bundler/no-dom/app` | Bundler | Node.js | Application |
| `bundler/no-dom/library` | Bundler | Node.js | Library |
| `bundler/no-dom/library-monorepo` | Bundler | Node.js | Monorepo Package |
> **Good to know:** `bundler/dom` and `bundler/dom/app` are aliases pointing to the same configuration file. Choose whichever path is clearer in your project.
## Core Compiler Options [#core-compiler-options]
All configurations share these strict, production-ready settings:
```json
{
"compilerOptions": {
"strict": true,
"noUncheckedIndexedAccess": true,
"noImplicitOverride": true,
"esModuleInterop": true,
"skipLibCheck": true,
"target": "es2022",
"allowJs": true,
"resolveJsonModule": true,
"moduleDetection": "force",
"isolatedModules": true,
"verbatimModuleSyntax": true
}
}
```
### What These Options Do [#what-these-options-do]
| Option | Purpose |
| -------------------------------- | -------------------------------------------------------- |
| `strict: true` | Enables all strict type checking options |
| `noUncheckedIndexedAccess: true` | Array/index access returns `T \| undefined` |
| `noImplicitOverride: true` | Requires explicit `override` keyword on subclass methods |
| `esModuleInterop: true` | Enables CommonJS/ESM interoperability |
| `skipLibCheck: true` | Skips type checking of declaration files (faster builds) |
| `target: "es2022"` | Outputs ES2022 JavaScript |
| `allowJs: true` | Allows JavaScript files in the project |
| `resolveJsonModule: true` | Allows importing JSON files |
| `moduleDetection: "force"` | Forces all files to be treated as modules |
| `isolatedModules: true` | Each file can be transpiled independently |
| `verbatimModuleSyntax: true` | Preserves import/export syntax exactly as written |
## Examples [#examples]
### Example: React application with Vite [#example-react-application-with-vite]
```json
{
"extends": "@accelint/typescript-config/bundler/dom/app",
"compilerOptions": {
"jsx": "react-jsx",
"paths": {
"@/*": ["./src/*"]
}
},
"include": ["src"]
}
```
### Example: Node.js CLI tool [#example-nodejs-cli-tool]
```json
{
"extends": "@accelint/typescript-config/tsc/no-dom/app",
"compilerOptions": {
"outDir": "./dist",
"module": "NodeNext",
"moduleResolution": "NodeNext"
},
"include": ["src"]
}
```
### Example: Publishable React component library [#example-publishable-react-component-library]
```json
{
"extends": "@accelint/typescript-config/tsc/dom/library",
"compilerOptions": {
"outDir": "./dist",
"declarationDir": "./dist/types",
"jsx": "react-jsx"
},
"include": ["src"]
}
```
### Example: Next.js application [#example-nextjs-application]
```json
{
"extends": "@accelint/typescript-config/bundler/dom/app",
"compilerOptions": {
"jsx": "preserve",
"plugins": [{ "name": "next" }],
"paths": {
"@/*": ["./src/*"]
}
},
"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
"exclude": ["node_modules"]
}
```
## Related [#related]
* [TSC Configurations](./tsc.mdx) - Configurations for projects using TypeScript Compiler
* [Bundler Configurations](./bundler.mdx) - Configurations for projects using Vite, Webpack, etc.
* [TypeScript Documentation](https://www.typescriptlang.org/docs/) - Official TypeScript docs
* [TSConfig Reference](https://www.typescriptlang.org/tsconfig) - Complete compiler options reference
* [@accelint/biome-config](../biome-config/index.mdx) - Shared Biome configuration
# TSC Configurations (/docs/tooling/typescript-config/tsc)
## Usage [#usage]
Use TSC configurations when your project:
* Compiles TypeScript with `tsc` directly
* Outputs JavaScript files to a `dist/` folder
* Generates declaration files (`.d.ts`) for consumers
* Doesn't use a bundler (Vite, Webpack, etc.)
```json
{
"extends": "@accelint/typescript-config/tsc/dom/app",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src"]
}
```
## Available Configurations [#available-configurations]
### DOM (Browser) Environments [#dom-browser-environments]
#### `tsc/dom/app` [#tscdomapp]
For web applications compiled with tsc.
```json
{
"extends": "@accelint/typescript-config/tsc/dom/app"
}
```
**Key settings:**
* `module: "esnext"` - ESNext module system
* `moduleResolution: "bundler"` - Modern module resolution
* `lib: ["es2023", "dom", "dom.iterable"]` - Browser APIs available
* `sourceMap: true` - Generates source maps
* No declaration file generation (apps don't need `.d.ts` files)
**Use for:** Single-page applications, web apps, browser-based tools
#### `tsc/dom/library` [#tscdomlibrary]
For standalone libraries targeting the browser.
```json
{
"extends": "@accelint/typescript-config/tsc/dom/library"
}
```
**Key settings:**
* Same as `tsc/dom/app` plus:
* `declaration: true` - Generates `.d.ts` files
* `declarationMap: true` - Generates `.d.ts.map` files
**Use for:** npm packages, UI component libraries, browser SDKs
#### `tsc/dom/library-monorepo` [#tscdomlibrary-monorepo]
For browser libraries within a monorepo.
```json
{
"extends": "@accelint/typescript-config/tsc/dom/library-monorepo"
}
```
**Key settings:**
* Same as `tsc/dom/library` plus:
* `composite: true` - Enables project references
* `incremental: true` - Faster rebuilds
**Use for:** Packages in a pnpm/yarn/npm workspace, Turborepo projects
### No-DOM (Node.js) Environments [#no-dom-nodejs-environments]
#### `tsc/no-dom/app` [#tscno-domapp]
For Node.js applications compiled with tsc.
```json
{
"extends": "@accelint/typescript-config/tsc/no-dom/app"
}
```
**Key settings:**
* `module: "esnext"` - ESNext module system
* `moduleResolution: "bundler"` - Modern module resolution
* `lib: ["es2023"]` - No DOM types (Node.js only)
* `sourceMap: true` - Generates source maps
* No declaration file generation
**Use for:** Express servers, CLI tools, backend services, scripts
#### `tsc/no-dom/library` [#tscno-domlibrary]
For standalone Node.js libraries.
```json
{
"extends": "@accelint/typescript-config/tsc/no-dom/library"
}
```
**Key settings:**
* Same as `tsc/no-dom/app` plus:
* `declaration: true` - Generates `.d.ts` files
* `declarationMap: true` - Generates `.d.ts.map` files
**Use for:** npm packages for Node.js, backend SDKs, utility libraries
#### `tsc/no-dom/library-monorepo` [#tscno-domlibrary-monorepo]
For Node.js libraries within a monorepo.
```json
{
"extends": "@accelint/typescript-config/tsc/no-dom/library-monorepo"
}
```
**Key settings:**
* Same as `tsc/no-dom/library` plus:
* `composite: true` - Enables project references
* `incremental: true` - Faster rebuilds
**Use for:** Backend packages in a monorepo, shared utilities, microservices
## Key Compiler Options [#key-compiler-options]
All TSC configurations include:
```json
{
"compilerOptions": {
"module": "esnext",
"moduleResolution": "bundler",
"sourceMap": true
}
}
```
| Option | Value | Reason |
| ------------------ | ----------- | ---------------------------------------- |
| `module` | `"esnext"` | Modern ESM output with latest features |
| `moduleResolution` | `"bundler"` | Handles package.json `exports` correctly |
| `sourceMap` | `true` | Enables debugging in original TypeScript |
> **Good to know:** TSC configurations use `moduleResolution: "bundler"` (not `"node"` or `"nodenext"`) because it correctly handles modern `package.json` export maps and is more lenient with import extensions.
## Examples [#examples]
### Example: Express API server [#example-express-api-server]
```json
{
"extends": "@accelint/typescript-config/tsc/no-dom/app",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src"],
"exclude": ["**/*.test.ts"]
}
```
### Example: React component library (publishable) [#example-react-component-library-publishable]
```json
{
"extends": "@accelint/typescript-config/tsc/dom/library",
"compilerOptions": {
"outDir": "./dist",
"declarationDir": "./dist/types",
"jsx": "react-jsx"
},
"include": ["src"]
}
```
### Example: CLI tool with Node.js [#example-cli-tool-with-nodejs]
```json
{
"extends": "@accelint/typescript-config/tsc/no-dom/app",
"compilerOptions": {
"outDir": "./dist",
"module": "NodeNext",
"moduleResolution": "NodeNext"
},
"include": ["src"]
}
```
### Example: Monorepo utility package [#example-monorepo-utility-package]
```json
{
"extends": "@accelint/typescript-config/tsc/no-dom/library-monorepo",
"compilerOptions": {
"outDir": "./dist",
"composite": true,
"rootDir": "./src"
},
"include": ["src"],
"references": [
{ "path": "../logger" },
{ "path": "../core" }
]
}
```
### Example: Dual ESM/CommonJS package [#example-dual-esmcommonjs-package]
For a library that supports both ESM and CommonJS:
**tsconfig.json** (ESM build):
```json
{
"extends": "@accelint/typescript-config/tsc/no-dom/library",
"compilerOptions": {
"outDir": "./dist/esm",
"module": "esnext",
"declaration": true,
"declarationDir": "./dist/types"
},
"include": ["src"]
}
```
**tsconfig.cjs.json** (CJS build):
```json
{
"extends": "./tsconfig.json",
"compilerOptions": {
"outDir": "./dist/cjs",
"module": "commonjs",
"declaration": false
}
}
```
### Example: Browser SDK with custom paths [#example-browser-sdk-with-custom-paths]
```json
{
"extends": "@accelint/typescript-config/tsc/dom/library",
"compilerOptions": {
"outDir": "./dist",
"declarationDir": "./dist/types",
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"],
"@utils/*": ["./src/utils/*"]
}
},
"include": ["src"]
}
```
## Common Overrides [#common-overrides]
### Change Module System [#change-module-system]
Override for Node.js native ESM:
```json
{
"extends": "@accelint/typescript-config/tsc/no-dom/app",
"compilerOptions": {
"module": "NodeNext",
"moduleResolution": "NodeNext"
}
}
```
### Add JSX Support [#add-jsx-support]
For React projects:
```json
{
"compilerOptions": {
"jsx": "react-jsx" // React 17+ automatic runtime
}
}
```
For Preact:
```json
{
"compilerOptions": {
"jsx": "react-jsx",
"jsxImportSource": "preact"
}
}
```
### Configure Declaration Output [#configure-declaration-output]
```json
{
"compilerOptions": {
"declaration": true,
"declarationDir": "./types",
"declarationMap": true,
"emitDeclarationOnly": false
}
}
```
## Related [#related]
* [Bundler Configurations](./bundler.mdx) - For Vite, Webpack, esbuild projects
* [Overview](./) - Decision guide and core options
* [TypeScript Compiler Options](https://www.typescriptlang.org/tsconfig) - Official reference
# dom (/docs/tooling/vitest-config/dom)
Vitest configuration preset for testing React components and DOM-dependent code. Extends the base configuration with React plugin support.
## Usage [#usage]
```typescript
import { defineConfig, mergeConfig } from 'vitest/config';
import baseConfig from '@accelint/vitest-config/dom';
export default mergeConfig(
baseConfig,
defineConfig({
test: {
globals: true,
environment: 'jsdom',
},
}),
);
```
## Reference [#reference]
```javascript
export default mergeConfig(
base,
defineConfig({
plugins: [react()],
}),
);
```
The DOM configuration merges the [no-dom](./no-dom.mdx) base configuration with the React plugin from `@vitejs/plugin-react`.
### Included Plugins [#included-plugins]
| Plugin | Purpose |
| ---------------------- | ------------------------------------------------------ |
| `@vitejs/plugin-react` | Enables React Fast Refresh and JSX transformation |
| `vite-tsconfig-paths` | Resolves TypeScript path aliases (inherited from base) |
### Configuration Settings [#configuration-settings]
All settings from [no-dom](./no-dom.mdx) plus:
* React Fast Refresh for component hot reloading
* JSX transformation for `.tsx` files
* Automatic React import injection
## Examples [#examples]
### Example: Simple re-export [#example-simple-re-export]
For projects that don't need custom configuration:
```typescript
// vitest.config.ts
export { default } from '@accelint/vitest-config/dom';
```
### Example: React component testing with jsdom [#example-react-component-testing-with-jsdom]
```typescript
import { defineConfig, mergeConfig } from 'vitest/config';
import baseConfig from '@accelint/vitest-config/dom';
export default mergeConfig(
baseConfig,
defineConfig({
test: {
globals: true,
environment: 'jsdom',
setupFiles: ['./tests/setup.ts'],
},
}),
);
```
### Example: Adding custom React plugin options [#example-adding-custom-react-plugin-options]
```typescript
import react from '@vitejs/plugin-react';
import { defineConfig, mergeConfig } from 'vitest/config';
import baseConfig from '@accelint/vitest-config/no-dom';
// Use no-dom as base and add React with custom options
export default mergeConfig(
baseConfig,
defineConfig({
plugins: [
react({
jsxRuntime: 'automatic',
babel: {
plugins: ['babel-plugin-styled-components'],
},
}),
],
}),
);
```
### Example: Component test with React Testing Library [#example-component-test-with-react-testing-library]
```typescript
import { render, screen } from '@testing-library/react';
import { describe, it, expect } from 'vitest';
import { Button } from './Button';
describe('Button', () => {
it('renders children correctly', () => {
render(<Button>Click me</Button>);
expect(screen.getByRole('button')).toHaveTextContent('Click me');
});
});
```
> **Good to know:** The DOM configuration inherits all settings from the [no-dom](./no-dom.mdx) base configuration, including coverage, TypeScript paths, and mock behavior. Use this preset when testing React components or browser APIs.
## Related [#related]
* [no-dom](./no-dom.mdx) - Base Vitest configuration without React
* [mockBroadcastChannel](./mocks/broadcast-channel.mdx) - Mock for BroadcastChannel API
# @accelint/vitest-config (/docs/tooling/vitest-config)
Shared [Vitest](https://vitest.dev/) configuration used across Accelint projects. Provides standardized testing setup with coverage, TypeScript path support, and React integration.
## Installation [#installation]
```bash
pnpm add -D @accelint/vitest-config
```
## Available Configurations [#available-configurations]
| Export | Description |
| -------------------------------------------------------- | ----------------------------------------------- |
| [dom](./dom.mdx) | React/browser testing with React plugin enabled |
| [no-dom](./no-dom.mdx) | Node.js testing without React dependencies |
| [mocks/broadcast-channel](./mocks/broadcast-channel.mdx) | Mock implementation of BroadcastChannel API |
## Features [#features]
* **Pre-configured Coverage**: Istanbul provider with JSON, LCOV, and text reporters
* **TypeScript Path Resolution**: Automatic tsconfig path alias support via vite-tsconfig-paths
* **React Integration**: DOM preset includes @vitejs/plugin-react
* **Mock Auto-reset**: Automatic mock clearing and restoration between tests
* **Zero Watch Mode**: Tests run once by default (override with `--watch`)
## Quick Start [#quick-start]
### React Component Testing [#react-component-testing]
```typescript
import { defineConfig, mergeConfig } from 'vitest/config';
import baseConfig from '@accelint/vitest-config/dom';
export default mergeConfig(
baseConfig,
defineConfig({
test: {
globals: true,
environment: 'jsdom',
},
}),
);
```
### Node.js Library Testing [#nodejs-library-testing]
```typescript
import { defineConfig, mergeConfig } from 'vitest/config';
import baseConfig from '@accelint/vitest-config/no-dom';
export default mergeConfig(
baseConfig,
defineConfig({
test: {
// Your custom test config
},
}),
);
```
### Simple Re-export [#simple-re-export]
If you don't need custom configuration:
```typescript
export { default } from '@accelint/vitest-config/dom';
```
## Package Scripts [#package-scripts]
Add these scripts to your `package.json`:
```json
{
"scripts": {
"test": "vitest run",
"test:watch": "vitest",
"test:coverage": "vitest run --coverage"
}
}
```
## Related [#related]
* [Vitest Documentation](https://vitest.dev)
* [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react)
* [vite-tsconfig-paths](https://github.com/aleclarson/vite-tsconfig-paths)
# no-dom (/docs/tooling/vitest-config/no-dom)
Base Vitest configuration for testing Node.js code and libraries without DOM dependencies. Includes TypeScript path resolution, Istanbul coverage, and sensible test defaults.
## Usage [#usage]
```typescript
import { defineConfig, mergeConfig } from 'vitest/config';
import baseConfig from '@accelint/vitest-config/no-dom';
export default mergeConfig(
baseConfig,
defineConfig({
test: {
// Your custom test configuration
},
}),
);
```
## Reference [#reference]
```javascript
export default defineConfig({
plugins: [tsconfigPaths()],
test: {
watch: false,
coverage: {
provider: 'istanbul',
reporter: ['json', 'json-summary', 'lcov', 'text'],
reportsDirectory: './coverage',
enabled: true,
clean: true,
passWithNoTests: true,
},
clearMocks: true,
mockReset: true,
restoreMocks: true,
passWithNoTests: true,
},
});
```
### Plugins [#plugins]
| Plugin | Purpose |
| --------------------- | ----------------------------------------------------- |
| `vite-tsconfig-paths` | Resolves TypeScript path aliases from `tsconfig.json` |
### Test Configuration [#test-configuration]
| Setting | Value | Description |
| ----------------- | ------- | --------------------------------------------- |
| `watch` | `false` | Disables watch mode (run once) |
| `clearMocks` | `true` | Clears mock calls between tests |
| `mockReset` | `true` | Resets mock implementations between tests |
| `restoreMocks` | `true` | Restores original implementations after tests |
| `passWithNoTests` | `true` | Succeeds when no test files found |
### Coverage Configuration [#coverage-configuration]
| Setting | Value | Description |
| ------------------ | ------------------------------------------ | --------------------------------------- |
| `provider` | `'istanbul'` | Uses Istanbul coverage provider |
| `reporter` | `['json', 'json-summary', 'lcov', 'text']` | Generates multiple coverage formats |
| `reportsDirectory` | `'./coverage'` | Output directory for coverage reports |
| `enabled` | `true` | Coverage enabled by default |
| `clean` | `true` | Clears previous coverage before running |
| `passWithNoTests` | `true` | Coverage passes when no tests exist |
## Examples [#examples]
### Example: Simple re-export [#example-simple-re-export]
For projects that don't need custom configuration:
```typescript
// vitest.config.ts
export { default } from '@accelint/vitest-config/no-dom';
```
### Example: Library testing with custom paths [#example-library-testing-with-custom-paths]
```typescript
import { defineConfig, mergeConfig } from 'vitest/config';
import baseConfig from '@accelint/vitest-config/no-dom';
export default mergeConfig(
baseConfig,
defineConfig({
test: {
include: ['src/**/*.test.ts'],
exclude: ['**/node_modules/**', '**/dist/**'],
},
}),
);
```
### Example: Adding coverage thresholds [#example-adding-coverage-thresholds]
```typescript
import { defineConfig, mergeConfig } from 'vitest/config';
import baseConfig from '@accelint/vitest-config/no-dom';
export default mergeConfig(
baseConfig,
defineConfig({
test: {
coverage: {
thresholds: {
lines: 80,
functions: 80,
branches: 80,
statements: 80,
},
exclude: [
'**/*.config.*',
'**/mocks/**',
'**/*.test.ts',
],
},
},
}),
);
```
### Example: TypeScript path resolution [#example-typescript-path-resolution]
With this `tsconfig.json`:
```json
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"],
"@utils/*": ["./src/utils/*"]
}
}
}
```
Paths resolve automatically in tests:
```typescript
import { helper } from '@/utils/helper';
import { format } from '@utils/format';
describe('helper', () => {
it('works with path aliases', () => {
expect(helper()).toBeDefined();
});
});
```
### Example: Running tests [#example-running-tests]
```bash
# Run tests once
vitest run
# Run with UI
vitest --ui
# Run with coverage
vitest run --coverage
# Watch mode (overrides config)
vitest
```
> **Good to know:** The no-dom configuration is the foundation for the [dom](./dom.mdx) preset. Use this preset for Node.js libraries, utilities, and backend code. For React components or browser APIs, use the [dom](./dom.mdx) preset instead.
## Related [#related]
* [dom](./dom.mdx) - Extended configuration with React plugin
* [mockBroadcastChannel](./mocks/broadcast-channel.mdx) - Mock for BroadcastChannel API
# Camera (/docs/toolkits/map-toolkit/camera)
## cameraStore [#camerastore]
Global store managing camera state for all map instances. Listens to camera bus events and provides reactive state updates.
### Usage [#usage]
```tsx
import { cameraStore } from '@accelint/map-toolkit/camera';
function CameraInfo({ mapId }: { mapId: string }) {
const { state, setCameraState } = cameraStore.use(mapId);
return (
<div>
Position: {state.latitude.toFixed(2)}, {state.longitude.toFixed(2)}
Zoom: {state.zoom}
</div>
);
}
```
### Reference [#reference]
```typescript
const cameraStore: MapStore<CameraState, CameraActions>;
type CameraState = CameraState2D | CameraState3D | CameraState2Point5D;
type CameraState2D = {
latitude: number;
longitude: number;
zoom: number;
pitch: 0;
rotation: number;
projection: 'mercator';
view: '2D';
};
type CameraState3D = {
latitude: number;
longitude: number;
zoom: number;
pitch: 0;
rotation: number;
projection: 'globe';
view: '3D';
};
type CameraState2Point5D = {
latitude: number;
longitude: number;
zoom: number;
pitch: number;
rotation: number;
projection: 'mercator';
view: '2.5D';
};
```
Camera state is a discriminated union based on the view mode. Each view mode has different constraints for pitch and projection.
### Examples [#examples]
#### Example: Monitoring camera state [#example-monitoring-camera-state]
```tsx
import { cameraStore } from '@accelint/map-toolkit/camera';
function CameraDebug({ mapId }: { mapId: string }) {
const { state } = cameraStore.use(mapId);
return (
<pre>
{JSON.stringify(state, null, 2)}
</pre>
);
}
```
## useMapCamera [#usemapcamera]
Hook to subscribe to camera state changes and access camera controls for a specific map.
### Usage [#usage-1]
```tsx
import { useMapCamera } from '@accelint/map-toolkit/camera';
function MapControls({ mapId }: { mapId: string }) {
const { cameraState, setCameraState } = useMapCamera(mapId, {
latitude: 37.7749,
longitude: -122.4194,
zoom: 10,
});
return (
<button onClick={() => setCameraState({ zoom: cameraState.zoom + 1 })}>
Zoom In
</button>
);
}
```
### Reference [#reference-1]
```typescript
function useMapCamera(
mapId: UniqueId,
initialCameraState?: CameraStateInput
): {
cameraState: CameraState;
setCameraState: (state: Partial<CameraState>) => void;
}
type CameraStateInput = {
latitude?: number;
longitude?: number;
zoom?: number;
pitch?: number;
rotation?: number;
projection?: ProjectionType;
view?: ViewType;
};
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| -------------------- | ------------------ | ------------------------------------------------------- |
| `mapId` | `UniqueId` | Unique identifier for the map instance |
| `initialCameraState` | `CameraStateInput` | Optional initial camera state (only used on first call) |
#### Returns [#returns]
Returns an object with:
* `cameraState` - Current camera state matching one of the discriminated union variants
* `setCameraState` - Function to update camera state directly
### Examples [#examples-1]
#### Example: Initializing with custom position [#example-initializing-with-custom-position]
```tsx
import { useMapCamera } from '@accelint/map-toolkit/camera';
function Map() {
const mapId = 'map-1';
const { cameraState } = useMapCamera(mapId, {
latitude: 40.7128,
longitude: -74.0060,
zoom: 12,
view: '2D',
});
return <div>Camera initialized at New York City</div>;
}
```
#### Example: Implementing zoom controls [#example-implementing-zoom-controls]
```tsx
import { useMapCamera } from '@accelint/map-toolkit/camera';
function ZoomControls({ mapId }: { mapId: string }) {
const { cameraState, setCameraState } = useMapCamera(mapId);
const zoomIn = () => setCameraState({ zoom: cameraState.zoom + 1 });
const zoomOut = () => setCameraState({ zoom: cameraState.zoom - 1 });
return (
<div>
<button onClick={zoomIn}>+</button>
<span>Zoom: {cameraState.zoom.toFixed(1)}</span>
<button onClick={zoomOut}>-</button>
</div>
);
}
```
#### Example: Switching between view modes [#example-switching-between-view-modes]
```tsx
import { useMapCamera } from '@accelint/map-toolkit/camera';
function ViewModeSelector({ mapId }: { mapId: string }) {
const { cameraState, setCameraState } = useMapCamera(mapId);
return (
<div>
<button onClick={() => setCameraState({ view: '2D' })}>
2D View
</button>
<button onClick={() => setCameraState({ view: '2.5D', pitch: 45 })}>
2.5D View
</button>
<button onClick={() => setCameraState({ view: '3D' })}>
3D Globe
</button>
<div>Current: {cameraState.view}</div>
</div>
);
}
```
> **Good to know:** Initializing camera state before subscribing prevents MapLibre from rendering at default (0,0,0) and firing onMove events that would overwrite the initialized state.
## CameraEventTypes [#cameraeventtypes]
Event type constants for camera operations via the broadcast bus.
### Usage [#usage-2]
```typescript
import { Broadcast } from '@accelint/bus';
import { CameraEventTypes } from '@accelint/map-toolkit/camera';
import type { CameraEvent } from '@accelint/map-toolkit/camera';
const bus = Broadcast.getInstance<CameraEvent>();
// Set camera center
bus.emit(CameraEventTypes.setCenter, {
id: 'map-1',
latitude: 37.7749,
longitude: -122.4194,
zoom: 10,
});
```
### Reference [#reference-2]
```typescript
const CameraEventTypes = {
setView: 'camera:setView',
setProjection: 'camera:setProjection',
setZoom: 'camera:setZoom',
setRotation: 'camera:setRotation',
setPitch: 'camera:setPitch',
setCenter: 'camera:setCenter',
fitBounds: 'camera:fitBounds',
reset: 'camera:reset',
} as const;
```
### Examples [#examples-2]
#### Example: Setting camera center [#example-setting-camera-center]
```typescript
import { Broadcast } from '@accelint/bus';
import { CameraEventTypes } from '@accelint/map-toolkit/camera';
import type { CameraEvent } from '@accelint/map-toolkit/camera';
const bus = Broadcast.getInstance<CameraEvent>();
bus.emit(CameraEventTypes.setCenter, {
id: 'map-1',
latitude: 37.7749,
longitude: -122.4194,
zoom: 10,
heading: 45,
});
```
#### Example: Fitting to bounds [#example-fitting-to-bounds]
```typescript
import { Broadcast } from '@accelint/bus';
import { CameraEventTypes } from '@accelint/map-toolkit/camera';
import type { CameraEvent } from '@accelint/map-toolkit/camera';
const bus = Broadcast.getInstance<CameraEvent>();
// Fit camera to show San Francisco Bay Area
bus.emit(CameraEventTypes.fitBounds, {
id: 'map-1',
bounds: [-122.5, 37.7, -122.3, 37.9],
width: 800,
height: 600,
padding: 20,
});
```
#### Example: Changing view mode [#example-changing-view-mode]
```typescript
import { Broadcast } from '@accelint/bus';
import { CameraEventTypes } from '@accelint/map-toolkit/camera';
import type { CameraEvent } from '@accelint/map-toolkit/camera';
const bus = Broadcast.getInstance<CameraEvent>();
// Switch to 2.5D tilted view
bus.emit(CameraEventTypes.setView, {
id: 'map-1',
view: '2.5D',
});
```
#### Example: Resetting camera [#example-resetting-camera]
```typescript
import { Broadcast } from '@accelint/bus';
import { CameraEventTypes } from '@accelint/map-toolkit/camera';
import type { CameraEvent } from '@accelint/map-toolkit/camera';
const bus = Broadcast.getInstance<CameraEvent>();
// Full reset to initial state
bus.emit(CameraEventTypes.reset, {
id: 'map-1',
});
// Reset but preserve current zoom
bus.emit(CameraEventTypes.reset, {
id: 'map-1',
zoom: false,
});
```
> **Good to know:** Camera events are processed asynchronously through the broadcast bus, enabling decoupled control of camera state from anywhere in your application.
## clearCameraState [#clearcamerastate]
Manually clears camera state for a specific map instance, removing all cached state and subscription tracking.
### Usage [#usage-3]
```typescript
import { clearCameraState } from '@accelint/map-toolkit/camera';
// Clean up when removing a map
clearCameraState('map-1');
```
### Reference [#reference-3]
```typescript
function clearCameraState(mapId: UniqueId): void
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | ---------- | --------------------------------------------------- |
| `mapId` | `UniqueId` | The unique identifier for the map instance to clear |
### Examples [#examples-3]
#### Example: Cleanup in tests [#example-cleanup-in-tests]
```typescript
import { clearCameraState } from '@accelint/map-toolkit/camera';
import { afterEach } from 'vitest';
afterEach(() => {
clearCameraState('test-map-id');
});
```
#### Example: Dynamic map removal [#example-dynamic-map-removal]
```typescript
import { clearCameraState } from '@accelint/map-toolkit/camera';
function removeMap(mapId: UniqueId) {
clearCameraState(mapId);
// ... remove map component
}
```
> **Good to know:** In most cases, cleanup happens automatically when all subscribers unmount. Use this function only for manual cleanup when dynamically destroying map instances or in test environments.
## ViewType [#viewtype]
Camera view modes defining perspective and interaction capabilities.
### Reference [#reference-4]
```typescript
type ViewType = '2D' | '2.5D' | '3D';
```
* `'2D'` - Traditional flat map view with rotation (mercator projection)
* `'2.5D'` - Tilted perspective view with pitch and rotation (mercator projection)
* `'3D'` - Globe view with fixed orientation (globe projection)
## ProjectionType [#projectiontype]
Map projection types supported by the camera system.
### Reference [#reference-5]
```typescript
type ProjectionType = 'mercator' | 'globe';
```
* `'mercator'` - Web Mercator projection for 2D and 2.5D views
* `'globe'` - Spherical globe projection for 3D views
## Related [#related]
* [Viewport](../viewport/index.md) - Viewport state management (bounds, dimensions)
* [MapEvents](../deckgl/base-map/events.md) - Event types for map interactions
* [createMapStore](../shared/create-map-store.md) - Underlying store pattern
# toLonLat (/docs/toolkits/map-toolkit/coordinates)
## Usage [#usage]
```typescript
import { toLonLat } from '@accelint/map-toolkit/shared/coordinates';
import type { PickingInfo } from '@deck.gl/core';
// `info.coordinate` is `number[] | undefined`; normalize before storing it.
function onHover(info: PickingInfo) {
const coordinate = toLonLat(info.coordinate);
if (coordinate) {
setCoordinate(coordinate);
}
}
```
## Reference [#reference]
```typescript
function toLonLat(value?: number[] | null): [number, number] | null
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ------------------------------- | ------------------------------------------------------------------- |
| `value` | `number[] \| null \| undefined` | Picked coordinate to normalize, typically `PickingInfo.coordinate`. |
### Returns [#returns]
Returns a new `[longitude, latitude]` tuple when the first two entries are finite numbers, otherwise `null`. A trailing `z` entry is dropped.
deck.gl's `PickingInfo.coordinate` is typed `number[]` and can be empty, non-finite, or three-element (`[longitude, latitude, z]` when any layer is `pickable: '3d'`), so pass it through `toLonLat` before treating it as a coordinate.
> **Good to know:** `toLonLat` is a pure function and always returns a fresh tuple; it never returns the input array. It runs on every hover and drag inside `BaseMap`, so it performs two direct checks with no callback allocation.
## Examples [#examples]
### Example: Guarding a bus payload [#example-guarding-a-bus-payload]
```typescript
import { toLonLat } from '@accelint/map-toolkit/shared/coordinates';
const coordinate = toLonLat(info.coordinate);
// Skip the emit when the pointer is off the globe.
if (coordinate) {
emitDragStart({ id, coordinate, shiftKey, ctrlKey, altKey });
}
```
### Example: Dropping a z component [#example-dropping-a-z-component]
```typescript
import { toLonLat } from '@accelint/map-toolkit/shared/coordinates';
toLonLat([-97.74, 30.27, 120]);
// [-97.74, 30.27]
```
### Example: Rejecting invalid input [#example-rejecting-invalid-input]
```typescript
import { toLonLat } from '@accelint/map-toolkit/shared/coordinates';
toLonLat(undefined); // null
toLonLat(null); // null
toLonLat([]); // null
toLonLat([Number.NaN, 30.27]); // null
toLonLat([-97.74]); // null
```
## Related [#related]
* [BaseMap](./deckgl/base-map.mdx) - Normalizes drag coordinates with `toLonLat` before emitting `map:dragStart` / `map:drag` / `map:dragEnd`
* [Measurement Layer](./deckgl/measurement-layer.mdx) - Applies `toLonLat` to `pointA` / `pointB` so non-finite points render nothing
* [cursor-coordinates](./cursor-coordinates.mdx) - Track and format cursor coordinates in multiple systems
# Cursor Coordinates (/docs/toolkits/map-toolkit/cursor-coordinates)
Hook for tracking and displaying formatted cursor coordinates on map components with support for multiple coordinate systems including Decimal Degrees, DMS, MGRS, and UTM.
## useCursorCoordinates [#usecursorcoordinates]
Tracks and formats cursor hover position coordinates on a map in real-time.
### Usage [#usage]
```tsx
import { useCursorCoordinates } from '@accelint/map-toolkit/cursor-coordinates';
function CoordinateDisplay({ mapId }: { mapId: string }) {
const { formattedCoord, setFormat } = useCursorCoordinates(mapId);
return (
<div>
<select onChange={(e) => setFormat(e.target.value as CoordinateFormatTypes)}>
<option value="dd">Decimal Degrees</option>
<option value="dms">Degrees Minutes Seconds</option>
<option value="mgrs">MGRS</option>
</select>
<div>{formattedCoord}</div>
</div>
);
}
```
### Reference [#reference]
```typescript
function useCursorCoordinates(
id?: UniqueId,
options?: UseCursorCoordinatesOptions
): UseCursorCoordinatesReturn
interface UseCursorCoordinatesOptions {
formatter?: CoordinateFormatter;
}
interface UseCursorCoordinatesReturn {
formattedCoord: string;
setFormat: (format: CoordinateFormatTypes) => void;
rawCoord: RawCoordinate;
currentFormat: CoordinateFormatTypes;
}
type CoordinateFormatTypes = 'dd' | 'ddm' | 'dms' | 'mgrs' | 'utm';
type RawCoordinate = {
longitude: number;
latitude: number;
} | null;
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ----------------------------- | --------------------------------------------------------------------------- |
| `id` | `UniqueId` | Optional map instance ID. If not provided, uses ID from MapProvider context |
| `options` | `UseCursorCoordinatesOptions` | Optional configuration |
#### Options [#options]
| Option | Type | Description |
| ----------- | --------------------- | -------------------------------------------------------- |
| `formatter` | `CoordinateFormatter` | Custom formatter function that overrides built-in format |
#### Returns [#returns]
| Property | Type | Description |
| ---------------- | ----------------------------------------- | -------------------------------------------------------------------- |
| `formattedCoord` | `string` | Formatted coordinate string using current format or custom formatter |
| `setFormat` | `(format: CoordinateFormatTypes) => void` | Function to change coordinate format system |
| `rawCoord` | `RawCoordinate` | Raw coordinate data (longitude/latitude) or null |
| `currentFormat` | `CoordinateFormatTypes` | Current active format type |
### Examples [#examples]
#### Example: Basic coordinate display [#example-basic-coordinate-display]
```tsx
import { useCursorCoordinates } from '@accelint/map-toolkit/cursor-coordinates';
function CoordinateDisplay({ mapId }: { mapId: string }) {
const { formattedCoord } = useCursorCoordinates(mapId);
return <div>{formattedCoord}</div>;
}
// Displays: "45.500000° N / 30.250000° E" (default DD format)
```
#### Example: Format selector [#example-format-selector]
```tsx
import { useCursorCoordinates } from '@accelint/map-toolkit/cursor-coordinates';
import type { CoordinateFormatTypes } from '@accelint/map-toolkit/cursor-coordinates';
function CoordinateSelector({ mapId }: { mapId: string }) {
const { formattedCoord, setFormat, currentFormat } = useCursorCoordinates(mapId);
return (
<div>
<select
value={currentFormat}
onChange={(e) => setFormat(e.target.value as CoordinateFormatTypes)}
>
<option value="dd">Decimal Degrees</option>
<option value="ddm">Degrees Decimal Minutes</option>
<option value="dms">Degrees Minutes Seconds</option>
<option value="mgrs">MGRS</option>
<option value="utm">UTM</option>
</select>
<div>{formattedCoord}</div>
</div>
);
}
```
#### Example: Custom formatter [#example-custom-formatter]
```tsx
import { useCursorCoordinates } from '@accelint/map-toolkit/cursor-coordinates';
function CustomCoordinateDisplay({ mapId }: { mapId: string }) {
const { formattedCoord } = useCursorCoordinates(mapId, {
formatter: (coord) =>
`Lat: ${coord.latitude.toFixed(6)}° Lng: ${coord.longitude.toFixed(6)}°`,
});
return <div>{formattedCoord}</div>;
}
// Displays: "Lat: 45.500000° Lng: 30.250000°"
```
#### Example: Accessing raw coordinates [#example-accessing-raw-coordinates]
```tsx
import { useCursorCoordinates } from '@accelint/map-toolkit/cursor-coordinates';
function RawCoordinateDisplay({ mapId }: { mapId: string }) {
const { rawCoord } = useCursorCoordinates(mapId);
if (!rawCoord) {
return <div>Move cursor over map</div>;
}
return (
<div>
<div>Longitude: {rawCoord.longitude.toFixed(6)}°</div>
<div>Latitude: {rawCoord.latitude.toFixed(6)}°</div>
</div>
);
}
```
#### Example: Within MapProvider context [#example-within-mapprovider-context]
```tsx
import { useCursorCoordinates } from '@accelint/map-toolkit/cursor-coordinates';
import { MapProvider } from '@accelint/map-toolkit/deckgl/base-map';
function CoordinateWidget() {
// No need to pass mapId when inside MapProvider
const { formattedCoord } = useCursorCoordinates();
return <div>{formattedCoord}</div>;
}
function App() {
return (
<MapProvider mapId="map-1">
<CoordinateWidget />
</MapProvider>
);
}
```
> **Good to know:** UTM and MGRS coordinate systems are only valid between 80°S and 84°N. Coordinates outside this range (e.g., polar regions) will display the default placeholder `-- / --`. Other formats (DD, DDM, DMS) work correctly at all latitudes.
#### Example: Error handling for custom formatter [#example-error-handling-for-custom-formatter]
```tsx
import { useCursorCoordinates } from '@accelint/map-toolkit/cursor-coordinates';
function SafeCoordinateDisplay({ mapId }: { mapId: string }) {
const { formattedCoord } = useCursorCoordinates(mapId, {
formatter: (coord) => {
// Custom formatter errors are caught and logged
// Falls back to default placeholder
if (coord.latitude > 90) {
throw new Error('Invalid latitude');
}
return `${coord.latitude}, ${coord.longitude}`;
},
});
return <div>{formattedCoord}</div>;
}
```
## CoordinateFormatTypes [#coordinateformattypes]
Supported coordinate format types for displaying map coordinates.
### Reference [#reference-1]
```typescript
type CoordinateFormatTypes = 'dd' | 'ddm' | 'dms' | 'mgrs' | 'utm';
```
* `'dd'` - Decimal Degrees (e.g., "45.500000° N / 30.250000° E")
* `'ddm'` - Degrees Decimal Minutes (e.g., "45° 30.0000' N / 30° 15.0000' E")
* `'dms'` - Degrees Minutes Seconds (e.g., "45° 30' 0.00" N / 30° 15' 0.00" E")
* `'mgrs'` - Military Grid Reference System (e.g., "31U DQ 48251 11932")
* `'utm'` - Universal Transverse Mercator (e.g., "31N 448251 5411932")
### Precision [#precision]
Each format uses precision matching the CoordinateField component:
* DD: 6 decimal places
* DDM: 4 decimal places for minutes
* DMS: 2 decimal places for seconds
## cursorCoordinateStore [#cursorcoordinatestore]
Global store managing cursor coordinate state for all map instances.
### Usage [#usage-1]
```tsx
import { cursorCoordinateStore } from '@accelint/map-toolkit/cursor-coordinates';
function CoordinateInfo({ mapId }: { mapId: string }) {
const { state, setFormat } = cursorCoordinateStore.use(mapId);
return (
<div>
Format: {state.format}
Coordinate: {state.coordinate?.join(', ') ?? 'None'}
</div>
);
}
```
### Reference [#reference-2]
```typescript
const cursorCoordinateStore: MapStore<CursorCoordinateState, CursorCoordinateActions>;
interface CursorCoordinateState {
coordinate: [number, number] | null;
format: CoordinateFormatTypes;
}
```
State is updated automatically from map hover events via the broadcast bus.
## clearCursorCoordinateState [#clearcursorcoordinatestate]
Manually clears cursor coordinate state for a specific map instance.
### Usage [#usage-2]
```typescript
import { clearCursorCoordinateState } from '@accelint/map-toolkit/cursor-coordinates';
clearCursorCoordinateState('map-1');
```
### Reference [#reference-3]
```typescript
function clearCursorCoordinateState(mapId: UniqueId): void
```
> **Good to know:** Cleanup happens automatically when all subscribers unmount. Use this only for manual cleanup in tests or when dynamically destroying map instances.
## Related [#related]
* [Viewport](../viewport/index.md) - Viewport state management
* [MapEvents](../deckgl/base-map/events.md) - Event types including hover events
* [createMapStore](../shared/create-map-store.md) - Underlying store pattern
# Overview (/docs/toolkits/map-toolkit)
## Installation [#installation]
```bash
pnpm add @accelint/map-toolkit
```
## Overview [#overview]
The Map Toolkit provides React components and utilities for building interactive geospatial applications. Built on top of Deck.gl and MapLibre GL, it offers a comprehensive set of tools for:
* **Base Maps** - Deck.gl-powered maps with MapLibre GL integration
* **State Management** - Coordinated camera, cursor, and mode management
* **Visualization Layers** - Symbol layers, grid layers (GARS, MGRS), and shape drawing
* **Interactive Tools** - Drawing, editing, and selecting shapes
* **Widgets** - HTML overlay system for custom UI elements
## Main Entry Points [#main-entry-points]
| Export Path | Description |
| ---------------------------------------------- | --------------------------------------------------------- |
| [camera](./camera.mdx) | Camera state management and coordinate system operations |
| [cursor-coordinates](./cursor-coordinates.mdx) | Track and format cursor coordinates in multiple systems |
| [deckgl](./deckgl/index.mdx) | Deck.gl base map, layers, extensions, and widgets |
| [map-cursor](./map-cursor.mdx) | Cursor state management and custom cursor icons |
| [map-mode](./map-mode.mdx) | Map interaction mode management (pan, draw, select, etc.) |
| [maplibre](./maplibre.mdx) | MapLibre GL integration and custom handlers |
| [viewport](./viewport.mdx) | Viewport state management and responsive sizing |
## Quick Start [#quick-start]
```tsx
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { useCamera } from '@accelint/map-toolkit/camera';
import { uuid } from '@accelint/core';
const MAP_ID = uuid();
export function MapView() {
// Access camera state
const camera = useCamera(MAP_ID);
return (
<div className="relative w-full h-screen">
<BaseMap id={MAP_ID} className="w-full h-full" />
{/* Display current coordinates */}
<div className="absolute top-4 left-4 bg-white p-2 rounded shadow">
Lat: {camera.latitude.toFixed(4)},
Lon: {camera.longitude.toFixed(4)},
Zoom: {camera.zoom.toFixed(2)}
</div>
</div>
);
}
```
## Architecture [#architecture]
The toolkit uses a **centralized event bus pattern** for coordinating state across components:
1. **Event Bus** - All map interactions flow through `@accelint/bus`
2. **Stores** - Each subsystem (camera, cursor, mode) maintains its own store
3. **Hooks** - React hooks subscribe to store updates and emit events
4. **Components** - Map components emit and respond to events
This architecture enables:
* Multiple map instances with isolated state
* Coordinated interactions across components
* Custom UI that responds to map state changes
* Easy integration with existing event-driven systems
## Related [#related]
* [@accelint/bus](../packages/bus/index.mdx) - Event bus for component coordination
* [@accelint/hotkey-manager](../packages/hotkey-manager/index.mdx) - Keyboard shortcut management
* [@accelint/geo](../packages/geo/index.mdx) - Geographic coordinate utilities
* [Deck.gl Documentation](https://deck.gl) - Official Deck.gl docs
* [MapLibre GL Documentation](https://maplibre.org) - Official MapLibre GL docs
# Map Cursor (/docs/toolkits/map-toolkit/map-cursor)
## Usage [#usage]
```tsx
import { useMapCursor, useMapCursorEffect } from '@accelint/map-toolkit/map-cursor';
import type { UniqueId } from '@accelint/core';
import type { PickingInfo } from '@deck.gl/core';
// Inside MapProvider - read and update cursor
function InteractiveLayer() {
const { cursor, requestCursorChange, clearCursor } = useMapCursor();
const handleHover = (info: PickingInfo) => {
if (info.object) {
requestCursorChange('pointer', 'layer-id');
} else {
clearCursor('layer-id');
}
};
return <ScatterplotLayer onHover={handleHover} />;
}
// Lifecycle-based cursor (auto-cleanup on unmount)
function DrawingMode() {
useMapCursorEffect('crosshair', 'drawing-mode');
return <div>Drawing active</div>;
}
```
## Reference [#reference]
### `useMapCursor(id?: UniqueId): UseMapCursorReturn` [#usemapcursorid-uniqueid-usemapcursorreturn]
Hook to access cursor state and actions. Uses `useSyncExternalStore` for concurrent-safe updates with a fan-out pattern.
**Owner-based Priority System:**
* Mode owners (from MapModeStore) have highest priority
* Non-owners can set cursors only in default/ownerless modes
* Rejected requests emit events with rejection reasons
#### Parameters [#parameters]
* `id` (optional) - Map instance ID. If omitted, uses `MapContext` (requires being within `MapProvider`).
#### Returns [#returns]
```typescript
type UseMapCursorReturn = {
cursor: CSSCursorType;
requestCursorChange: (cursor: CSSCursorType, requestOwner: string) => void;
clearCursor: (owner: string) => void;
};
```
* `cursor` - Current active cursor (CSS cursor string)
* `requestCursorChange` - Request cursor change with ownership
* `clearCursor` - Clear cursor for specific owner
#### Throws [#throws]
Error if no `id` is provided and hook is used outside `MapProvider`.
### `useMapCursorEffect(cursorType: CSSCursorType, owner: string, id?: UniqueId): void` [#usemapcursoreffectcursortype-csscursortype-owner-string-id-uniqueid-void]
Lifecycle hook that automatically manages cursor for a component.
Requests cursor on mount, maintains it while mounted, and clears on unmount. Does NOT re-render on cursor state changes—use `useMapCursor` if you need to read current cursor value.
#### Parameters [#parameters-1]
* `cursorType` - The CSS cursor string to request
* `owner` - Owner identifier for priority management
* `id` (optional) - Map instance ID
#### Throws [#throws-1]
Error if no `id` is provided and hook is used outside `MapProvider`.
### Events [#events]
Cursor management uses event-driven coordination:
#### `MapCursorEvents.changeRequest` [#mapcursoreventschangerequest]
Emitted when cursor change is requested.
```typescript
type CursorChangeRequestPayload = {
cursor: CSSCursorType;
owner: string;
id: UniqueId;
};
```
#### `MapCursorEvents.changed` [#mapcursoreventschanged]
Emitted when cursor successfully changes.
```typescript
type CursorChangedPayload = {
previousCursor: CSSCursorType;
currentCursor: CSSCursorType;
owner: string;
id: UniqueId;
};
```
#### `MapCursorEvents.rejected` [#mapcursoreventsrejected]
Emitted when cursor request is rejected due to priority.
```typescript
type CursorRejectionPayload = {
rejectedCursor: CSSCursorType;
rejectedOwner: string;
currentOwner: string;
reason: string;
id: UniqueId;
};
```
### Store Functions [#store-functions]
```typescript
// Get current cursor
getCursor(id: UniqueId): CSSCursorType;
// Clear state for cleanup
clearCursorState(id: UniqueId): void;
// Low-level store access
cursorStore.useSelector(id: UniqueId, selector: (state) => T): T;
cursorStore.actions(id: UniqueId): { requestCursorChange, clearCursor };
```
### Types [#types]
```typescript
// CSS cursor string from React CSSProperties
type CSSCursorType = NonNullable<React.CSSProperties['cursor']>;
```
Includes all standard CSS cursor keywords (`pointer`, `crosshair`, `move`, etc.) and custom `url()` syntax.
## Examples [#examples]
### Example: Hover-based cursor change [#example-hover-based-cursor-change]
```tsx
import { useMapCursor } from '@accelint/map-toolkit/map-cursor';
import { ScatterplotLayer } from '@deck.gl/layers';
import type { PickingInfo } from '@deck.gl/core';
function PointLayer() {
const { requestCursorChange, clearCursor } = useMapCursor();
const handleHover = (info: PickingInfo) => {
if (info.object) {
// Show pointer when hovering over a point
requestCursorChange('pointer', 'point-layer');
} else {
// Clear cursor when not hovering
clearCursor('point-layer');
}
};
return (
<ScatterplotLayer
id="points"
data={points}
onHover={handleHover}
getPosition={(d) => d.position}
getRadius={10}
/>
);
}
```
### Example: Mode-coordinated cursor [#example-mode-coordinated-cursor]
```tsx
import { useMapMode } from '@accelint/map-toolkit/map-mode';
import { useMapCursorEffect } from '@accelint/map-toolkit/map-cursor';
function DrawingMode() {
const { mode } = useMapMode();
// Automatically set crosshair cursor when in drawing mode
useMapCursorEffect(
mode === 'drawing' ? 'crosshair' : 'default',
'drawing-mode'
);
return mode === 'drawing' ? <DrawControls /> : null;
}
```
### Example: Custom cursor with icon [#example-custom-cursor-with-icon]
```tsx
import { useMapCursor } from '@accelint/map-toolkit/map-cursor';
function CustomCursorControl() {
const { requestCursorChange } = useMapCursor();
const setCustomCursor = () => {
// Use custom cursor image
requestCursorChange(
'url(/cursors/crosshair.svg) 16 16, crosshair',
'custom-control'
);
};
return <button onClick={setCustomCursor}>Use Custom Cursor</button>;
}
```
### Example: Priority-aware cursor management [#example-priority-aware-cursor-management]
```tsx
import { useMapMode } from '@accelint/map-toolkit/map-mode';
import { useMapCursor } from '@accelint/map-toolkit/map-cursor';
import { useEffect } from 'react';
function ModeAwareCursor() {
const { mode } = useMapMode();
const { requestCursorChange, clearCursor } = useMapCursor();
useEffect(() => {
// Mode owners have priority
if (mode === 'editing') {
requestCursorChange('move', 'editing-mode');
} else {
clearCursor('editing-mode');
}
}, [mode, requestCursorChange, clearCursor]);
return null;
}
```
### Example: Listening to cursor rejections [#example-listening-to-cursor-rejections]
```tsx
import { useOn } from '@accelint/bus/react';
import { MapCursorEvents } from '@accelint/map-toolkit/map-cursor';
import type { CursorRejectedEvent } from '@accelint/map-toolkit/map-cursor';
function CursorRejectionLogger({ mapId }: { mapId: UniqueId }) {
useOn<CursorRejectedEvent>(MapCursorEvents.rejected, (event) => {
if (event.payload.id === mapId) {
console.warn(
`Cursor request rejected: ${event.payload.reason}`,
`Owner: ${event.payload.rejectedOwner}`
);
}
});
return null;
}
```
### Example: Conditional cursor in layer [#example-conditional-cursor-in-layer]
```tsx
import { useMapCursor } from '@accelint/map-toolkit/map-cursor';
import { IconLayer } from '@deck.gl/layers';
import type { PickingInfo } from '@deck.gl/core';
function IconMarkerLayer({ editable }: { editable: boolean }) {
const { requestCursorChange, clearCursor } = useMapCursor();
const handleHover = (info: PickingInfo) => {
if (!editable) return;
if (info.object) {
requestCursorChange('grab', 'icon-layer');
} else {
clearCursor('icon-layer');
}
};
return (
<IconLayer
id="markers"
data={markers}
onHover={handleHover}
getPosition={(d) => d.position}
getIcon={() => 'marker'}
/>
);
}
```
> **Good to know:** Cursor changes respect map mode ownership. If a mode owner sets a cursor, non-owners' requests will be rejected until the mode changes.
## Related [#related]
* [BaseMap](../deckgl/base-map/index.mdx) - Automatically creates MapProvider for cursor management
* [useMapMode](../map-mode/index.mdx) - Coordinate map modes with cursor ownership
* [@accelint/bus](../../../packages/bus/index.mdx) - Event bus used for cursor coordination
# Map Mode (/docs/toolkits/map-toolkit/map-mode)
## Usage [#usage]
```tsx
import { useMapMode } from '@accelint/map-toolkit/map-mode';
import type { UniqueId } from '@accelint/core';
// Inside MapProvider (Deck.gl layer component)
function CustomLayer() {
const { mode, requestModeChange } = useMapMode();
return mode === 'editing' ? <EditableLayer /> : <ReadOnlyLayer />;
}
// Outside MapProvider (UI control)
function ModeControl({ mapId }: { mapId: UniqueId }) {
const { mode, requestModeChange } = useMapMode(mapId);
return (
<button onClick={() => requestModeChange('drawing', 'toolbar')}>
Switch to Drawing Mode
</button>
);
}
```
## Reference [#reference]
### `useMapMode(id?: UniqueId): UseMapModeReturn` [#usemapmodeid-uniqueid-usemapmodereturn]
Hook to access the map mode state and actions. Uses `useSyncExternalStore` for concurrent-safe updates with a fan-out pattern where one bus listener per map notifies N React subscribers.
#### Parameters [#parameters]
* `id` (optional) - Map instance ID. If omitted, uses `MapContext` (requires being within `MapProvider`).
#### Returns [#returns]
```typescript
type UseMapModeReturn = {
mode: string;
requestModeChange: (desiredMode: string, requestOwner: string) => void;
};
```
* `mode` - Current active map mode string
* `requestModeChange` - Function to request mode change with ownership
#### Throws [#throws]
Error if no `id` is provided and hook is used outside `MapProvider`.
### Events [#events]
Map mode uses an event-driven approval flow for coordinating mode changes:
#### `MapModeEvents.changeRequest` [#mapmodeeventschangerequest]
Emitted when a component requests a mode change.
```typescript
type ModeChangeRequestPayload = {
desiredMode: string;
owner: string;
id: UniqueId;
};
```
#### `MapModeEvents.changeAuthorization` [#mapmodeeventschangeauthorization]
Sent to current mode owner to approve/reject the request.
```typescript
type ModeChangeAuthorizationPayload = {
authId: string;
desiredMode: string;
currentMode: string;
id: UniqueId;
};
```
#### `MapModeEvents.changeDecision` [#mapmodeeventschangedecision]
Response from current owner approving or rejecting the change.
```typescript
type ModeChangeDecisionPayload = {
authId: string;
approved: boolean;
owner: string;
reason?: string;
id: UniqueId;
};
```
#### `MapModeEvents.changed` [#mapmodeeventschanged]
Emitted when mode successfully changes.
```typescript
type ModeChangedPayload = {
previousMode: string;
currentMode: string;
id: UniqueId;
};
```
### Store Functions [#store-functions]
```typescript
// Get current mode and owner
getMode(id: UniqueId): string;
getCurrentModeOwner(id: UniqueId): string;
// Clear state for cleanup
clearMapModeState(id: UniqueId): void;
// Low-level store access
modeStore.useSelector(id: UniqueId, selector: (state) => T): T;
modeStore.actions(id: UniqueId): { requestModeChange };
```
## Examples [#examples]
### Example: Toolbar with multiple mode buttons [#example-toolbar-with-multiple-mode-buttons]
```tsx
import { useMapMode } from '@accelint/map-toolkit/map-mode';
import type { UniqueId } from '@accelint/core';
function MapToolbar({ mapId }: { mapId: UniqueId }) {
const { mode, requestModeChange } = useMapMode(mapId);
const modes = [
{ id: 'default', label: 'Navigate' },
{ id: 'drawing', label: 'Draw' },
{ id: 'editing', label: 'Edit' },
{ id: 'measuring', label: 'Measure' },
];
return (
<div className="flex gap-2">
{modes.map((m) => (
<button
key={m.id}
disabled={mode === m.id}
onClick={() => requestModeChange(m.id, 'toolbar')}
>
{m.label} {mode === m.id && '✓'}
</button>
))}
</div>
);
}
```
### Example: Conditionally rendering layer based on mode [#example-conditionally-rendering-layer-based-on-mode]
```tsx
import { useMapMode } from '@accelint/map-toolkit/map-mode';
import { ScatterplotLayer } from '@deck.gl/layers';
function ConditionalLayer() {
const { mode } = useMapMode();
// Only render when in specific mode
if (mode !== 'analysis') {
return null;
}
return (
<ScatterplotLayer
id="analysis-points"
data={analysisData}
getPosition={(d) => d.position}
getRadius={5}
/>
);
}
```
### Example: Listening to mode changes with event bus [#example-listening-to-mode-changes-with-event-bus]
```tsx
import { useOn } from '@accelint/bus/react';
import { MapModeEvents } from '@accelint/map-toolkit/map-mode';
import type { ModeChangedEvent } from '@accelint/map-toolkit/map-mode';
function ModeLogger({ mapId }: { mapId: UniqueId }) {
useOn<ModeChangedEvent>(MapModeEvents.changed, (event) => {
if (event.payload.id === mapId) {
console.log(
`Mode changed: ${event.payload.previousMode} → ${event.payload.currentMode}`
);
}
});
return null;
}
```
### Example: Implementing approval logic [#example-implementing-approval-logic]
```tsx
import { useEffect } from 'react';
import { useOn, useEmit } from '@accelint/bus/react';
import { MapModeEvents } from '@accelint/map-toolkit/map-mode';
import type {
ModeChangeAuthorizationEvent,
ModeChangeDecisionPayload,
} from '@accelint/map-toolkit/map-mode';
function DrawingModeOwner({ mapId, ownerId }: Props) {
const emitDecision = useEmit<ModeChangeDecisionPayload>(
MapModeEvents.changeDecision
);
useOn<ModeChangeAuthorizationEvent>(
MapModeEvents.changeAuthorization,
(event) => {
if (event.payload.id !== mapId) return;
// Only respond if we own the current mode
if (event.payload.currentMode !== 'drawing') return;
// Check if we have unsaved changes
const hasUnsavedChanges = checkForUnsavedChanges();
if (hasUnsavedChanges) {
// Reject the mode change
emitDecision({
authId: event.payload.authId,
approved: false,
owner: ownerId,
reason: 'Unsaved changes in drawing mode',
id: mapId,
});
} else {
// Approve the mode change
emitDecision({
authId: event.payload.authId,
approved: true,
owner: ownerId,
id: mapId,
});
}
}
);
return null;
}
```
### Example: Multiple map instances [#example-multiple-map-instances]
```tsx
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { useMapMode } from '@accelint/map-toolkit/map-mode';
import { uuid } from '@accelint/core';
const MAP_1_ID = uuid();
const MAP_2_ID = uuid();
function SharedToolbar() {
const map1 = useMapMode(MAP_1_ID);
const map2 = useMapMode(MAP_2_ID);
return (
<div>
<button onClick={() => map1.requestModeChange('editing', 'toolbar')}>
Edit Map 1 (current: {map1.mode})
</button>
<button onClick={() => map2.requestModeChange('editing', 'toolbar')}>
Edit Map 2 (current: {map2.mode})
</button>
</div>
);
}
export function DualMapView() {
return (
<>
<SharedToolbar />
<BaseMap id={MAP_1_ID} className="w-1/2 h-full" />
<BaseMap id={MAP_2_ID} className="w-1/2 h-full" />
</>
);
}
```
> **Good to know:** Each map instance maintains independent mode state. Use shared IDs at module level to coordinate between UI controls and map instances.
## Related [#related]
* [BaseMap](../deckgl/base-map/index.mdx) - Automatically creates MapProvider for mode management
* [useMapCursor](../map-cursor/index.mdx) - Manage cursor styles coordinated with map modes
* [@accelint/bus](../../../packages/bus/index.mdx) - Event bus used for mode coordination
# MapLibre (/docs/toolkits/map-toolkit/maplibre)
## Installation [#installation]
```bash
pnpm add @accelint/map-toolkit maplibre-gl
```
## Usage [#usage]
```typescript
// Import hook
import { useMapLibre } from '@accelint/map-toolkit/maplibre';
// Import RBZ handler
import { RbzHandler, DEFAULT_RBZ_STYLE } from '@accelint/map-toolkit/maplibre';
// Import constants
import { DEFAULT_VIEW_STATE } from '@accelint/map-toolkit/maplibre';
```
## Available Exports [#available-exports]
### Hooks [#hooks]
| Export | Description |
| ------------- | ----------------------------------------------------------- |
| `useMapLibre` | React hook for creating and managing a MapLibre GL instance |
### Handlers [#handlers]
| Export | Description |
| ------------ | -------------------------------------------------------------------------- |
| `RbzHandler` | Custom MapLibre handler for rubber band zoom (click-drag rectangular zoom) |
### Constants [#constants]
| Export | Description |
| -------------------- | ----------------------------------------------------- |
| `DEFAULT_VIEW_STATE` | Default map view state (center, zoom, pitch, bearing) |
| `DEFAULT_RBZ_STYLE` | Default styling for rubber band zoom rectangle |
### Types [#types]
| Export | Description |
| ----------------- | ---------------------------------------------- |
| `RbzOptions` | Configuration options for RbzHandler |
| `RbzStyleOptions` | Styling options for rubber band zoom rectangle |
| `RbzBuffer` | Buffer dimensions for zoom rectangle |
| `RbzOrigin` | Origin point for rubber band zoom |
## Quick Start [#quick-start]
### Basic MapLibre Integration [#basic-maplibre-integration]
```tsx
import { useMapLibre, DEFAULT_VIEW_STATE } from '@accelint/map-toolkit/maplibre';
import { useEffect, useRef } from 'react';
import 'maplibre-gl/dist/maplibre-gl.css';
export function SimpleMap() {
const containerRef = useRef<HTMLDivElement>(null);
const map = useMapLibre({
container: containerRef.current,
style: 'https://demotiles.maplibre.org/style.json',
...DEFAULT_VIEW_STATE,
});
useEffect(() => {
if (!map) return;
// Add custom layer or markers
map.on('load', () => {
map.addSource('my-data', {
type: 'geojson',
data: {
type: 'FeatureCollection',
features: [],
},
});
});
}, [map]);
return <div ref={containerRef} className="w-full h-full" />;
}
```
### Rubber Band Zoom [#rubber-band-zoom]
```tsx
import { useMapLibre, RbzHandler, DEFAULT_RBZ_STYLE } from '@accelint/map-toolkit/maplibre';
import { useEffect, useRef } from 'react';
import 'maplibre-gl/dist/maplibre-gl.css';
export function MapWithRbz() {
const containerRef = useRef<HTMLDivElement>(null);
const map = useMapLibre({
container: containerRef.current,
style: 'https://demotiles.maplibre.org/style.json',
center: [0, 0],
zoom: 2,
});
useEffect(() => {
if (!map) return;
// Add rubber band zoom handler
const rbzHandler = new RbzHandler({
map,
style: {
...DEFAULT_RBZ_STYLE,
fillColor: 'rgba(0, 123, 255, 0.1)',
strokeColor: 'rgba(0, 123, 255, 0.8)',
},
});
map.addHandler('rbz', rbzHandler);
return () => {
map.removeHandler('rbz');
};
}, [map]);
return (
<div className="relative w-full h-full">
<div ref={containerRef} className="w-full h-full" />
<div className="absolute top-4 left-4 bg-white p-2 rounded shadow">
Hold Shift + Click and drag to zoom to a rectangle
</div>
</div>
);
}
```
### With BaseMap Integration [#with-basemap-integration]
While BaseMap uses Deck.gl, MapLibre GL provides the base map tiles and 2D vector features:
```tsx
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { LIGHT_BASE_MAP_STYLE } from '@accelint/map-toolkit/deckgl';
import { uuid } from '@accelint/core';
const MAP_ID = uuid();
export function HybridMap() {
return (
<BaseMap
id={MAP_ID}
className="w-full h-full"
mapStyle={LIGHT_BASE_MAP_STYLE}
/>
);
}
```
## Architecture Notes [#architecture-notes]
* **BaseMap** internally uses MapLibre GL for base map tiles
* Deck.gl renders 3D visualizations on top of the MapLibre layer
* `useMapLibre` hook is for standalone MapLibre usage without Deck.gl
* `RbzHandler` can be added to either standalone MapLibre or BaseMap instances
## Related [#related]
* [deckgl](./deckgl/index.mdx) - Deck.gl integration with MapLibre
* [deckgl/base-map](./deckgl/base-map.mdx) - Combined Deck.gl + MapLibre component
* [MapLibre GL JS Documentation](https://maplibre.org/maplibre-gl-js-docs/api/) - Official MapLibre docs
# Viewport (/docs/toolkits/map-toolkit/viewport)
## viewportStore [#viewportstore]
Global store managing viewport state for all map instances. Automatically subscribes to `MapEvents.viewport` bus events.
### Usage [#usage]
```tsx
import { viewportStore } from '@accelint/map-toolkit/viewport';
function MapInfo({ mapId }: { mapId: string }) {
const { state } = viewportStore.use(mapId);
return (
<div>
Lat: {state.latitude.toFixed(2)}, Lon: {state.longitude.toFixed(2)}
</div>
);
}
```
### Reference [#reference]
```typescript
const viewportStore: MapStore<ViewportState, ViewportActions>;
interface ViewportState {
id: UniqueId;
bounds?: [minLon: number, minLat: number, maxLon: number, maxLat: number];
latitude: number;
longitude: number;
zoom: number;
width: number;
height: number;
}
```
State is read-only and updated automatically from map events. Uninitialized values use `NaN` for lat/lon/zoom and `undefined` for bounds.
## useMapViewport [#usemapviewport]
Hook to subscribe to viewport state changes for a specific map.
### Usage [#usage-1]
```tsx
import { useMapViewport } from '@accelint/map-toolkit/viewport';
function MapInfo({ mapId }: { mapId: string }) {
const viewport = useMapViewport(mapId);
return (
<div>
Lat: {viewport.latitude.toFixed(2)},
Lon: {viewport.longitude.toFixed(2)},
Zoom: {viewport.zoom}
</div>
);
}
```
### Reference [#reference-1]
```typescript
function useMapViewport(mapId: UniqueId): ViewportState
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---------- | -------------------------------------- |
| `mapId` | `UniqueId` | Unique identifier for the map instance |
#### Returns [#returns]
Returns current viewport state including bounds, latitude, longitude, zoom, width, and height. Returns default state with `NaN` values if viewport not yet initialized.
### Examples [#examples]
#### Example: Displaying viewport coordinates [#example-displaying-viewport-coordinates]
```tsx
import { useMapViewport } from '@accelint/map-toolkit/viewport';
function CoordinateDisplay({ mapId }: { mapId: string }) {
const { latitude, longitude } = useMapViewport(mapId);
if (Number.isNaN(latitude) || Number.isNaN(longitude)) {
return <div>Loading viewport...</div>;
}
return (
<div>
Position: {latitude.toFixed(4)}°, {longitude.toFixed(4)}°
</div>
);
}
```
#### Example: Checking viewport bounds [#example-checking-viewport-bounds]
```tsx
import { useMapViewport } from '@accelint/map-toolkit/viewport';
function BoundsDisplay({ mapId }: { mapId: string }) {
const { bounds } = useMapViewport(mapId);
if (!bounds) {
return <div>No bounds available</div>;
}
const [minLon, minLat, maxLon, maxLat] = bounds;
return (
<div>
Bounds: [{minLon.toFixed(2)}, {minLat.toFixed(2)}] to
[{maxLon.toFixed(2)}, {maxLat.toFixed(2)}]
</div>
);
}
```
## ViewportSize [#viewportsize]
Component displaying the current viewport bounds in a specified unit.
### Usage [#usage-2]
```tsx
import { ViewportSize } from '@accelint/map-toolkit/viewport';
function MapFooter({ mapId }: { mapId: string }) {
return (
<footer>
<ViewportSize instanceId={mapId} />
</footer>
);
}
```
### Reference [#reference-2]
```typescript
interface ViewportSizeProps extends ComponentPropsWithRef<'span'> {
instanceId: UniqueId;
unit?: DistanceUnitSymbol;
}
```
#### Props [#props]
| Prop | Type | Default | Required |
| ------------ | ------------------------------------- | ------- | -------- |
| `instanceId` | `UniqueId` | - | Yes |
| `unit` | `'km' \| 'm' \| 'NM' \| 'mi' \| 'ft'` | `'NM'` | No |
| `className` | `string` | - | No |
Inherits all standard `<span>` HTML attributes.
### Examples [#examples-1]
#### Example: Basic usage with default nautical miles [#example-basic-usage-with-default-nautical-miles]
```tsx
import { ViewportSize } from '@accelint/map-toolkit/viewport';
<ViewportSize instanceId={mapId} />
// Renders: "660 x 1,801 NM"
```
#### Example: Custom unit and styling [#example-custom-unit-and-styling]
```tsx
import { ViewportSize } from '@accelint/map-toolkit/viewport';
<ViewportSize
instanceId={mapId}
unit="km"
className="text-sm text-gray-600"
/>
// Renders: "1,223 x 3,339 km"
```
#### Example: Multiple units in a dashboard [#example-multiple-units-in-a-dashboard]
```tsx
import { ViewportSize } from '@accelint/map-toolkit/viewport';
function ViewportMetrics({ mapId }: { mapId: string }) {
return (
<div>
<div>Nautical: <ViewportSize instanceId={mapId} unit="NM" /></div>
<div>Metric: <ViewportSize instanceId={mapId} unit="km" /></div>
<div>Imperial: <ViewportSize instanceId={mapId} unit="mi" /></div>
</div>
);
}
```
> **Good to know:** ViewportSize displays `-- x -- {unit}` when the viewport is not yet initialized or has invalid bounds.
## getViewportSize [#getviewportsize]
Calculates and formats viewport dimensions in a specified unit.
### Usage [#usage-3]
```typescript
import { getViewportSize } from '@accelint/map-toolkit/viewport';
const size = getViewportSize({
bounds: [-82, 22, -71, 52],
zoom: 5,
width: 800,
height: 600,
unit: 'NM'
});
// Returns "612 x 459 NM"
```
### Reference [#reference-3]
```typescript
function getViewportSize(args: GetViewportSizeArgs): string
interface GetViewportSizeArgs {
bounds?: [minLon: number, minLat: number, maxLon: number, maxLat: number];
zoom: number;
width: number;
height: number;
unit?: DistanceUnitSymbol;
formatter?: Intl.NumberFormat;
}
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| ----------- | ---------------------------------- | ---------------------------------------------------------------------- |
| `bounds` | `[number, number, number, number]` | Geographic bounds \[minLon, minLat, maxLon, maxLat] |
| `zoom` | `number` | Map zoom level for meters-per-pixel calculation |
| `width` | `number` | Viewport width in pixels |
| `height` | `number` | Viewport height in pixels |
| `unit` | `DistanceUnitSymbol` | Unit symbol: `'km' \| 'm' \| 'NM' \| 'mi' \| 'ft'`. Defaults to `'NM'` |
| `formatter` | `Intl.NumberFormat` | Number formatter for localization. Defaults to `en-US` |
#### Returns [#returns-1]
Returns formatted string like `"660 x 1,801 NM"` or `"-- x -- {unit}"` if inputs are invalid.
### Examples [#examples-2]
#### Example: Calculating viewport size in different units [#example-calculating-viewport-size-in-different-units]
```typescript
import { getViewportSize } from '@accelint/map-toolkit/viewport';
const args = {
bounds: [-82, 22, -71, 52],
zoom: 5,
width: 800,
height: 600
};
getViewportSize({ ...args, unit: 'NM' }); // "612 x 459 NM"
getViewportSize({ ...args, unit: 'km' }); // "1,134 x 851 km"
getViewportSize({ ...args, unit: 'mi' }); // "705 x 529 mi"
```
#### Example: Custom number formatting [#example-custom-number-formatting]
```typescript
import { getViewportSize } from '@accelint/map-toolkit/viewport';
const formatter = new Intl.NumberFormat('de-DE');
getViewportSize({
bounds: [-82, 22, -71, 52],
zoom: 5,
width: 800,
height: 600,
unit: 'km',
formatter
});
// Returns "1.134 x 851 km" (German formatting)
```
#### Example: Handling cross-antimeridian bounds [#example-handling-cross-antimeridian-bounds]
```typescript
import { getViewportSize } from '@accelint/map-toolkit/viewport';
// Pacific view crossing 180° meridian
getViewportSize({
bounds: [170, 50, -170, 60],
zoom: 4,
width: 1024,
height: 768,
unit: 'NM'
});
// Returns accurate calculation despite longitude wrap
```
> **Good to know:** The calculation uses the Web Mercator projection formula with zoom level and pixel dimensions, providing stable results without edge cases from bounds-based calculations.
## clearViewportState [#clearviewportstate]
Manually clears viewport state for a specific map instance.
### Usage [#usage-4]
```typescript
import { clearViewportState } from '@accelint/map-toolkit/viewport';
// Cleanup when unmounting
clearViewportState(mapId);
```
### Reference [#reference-4]
```typescript
function clearViewportState(mapId: UniqueId): void
```
#### Parameters [#parameters-2]
| Parameter | Type | Description |
| --------- | ---------- | --------------------------------------------------- |
| `mapId` | `UniqueId` | The unique identifier for the map instance to clear |
> **Good to know:** This is typically not needed as cleanup happens automatically when all subscribers unmount. Use this only for manual cleanup in edge cases.
## Related [#related]
* [BaseMap](../deckgl/base-map/index.md) - Map component that emits viewport events
* [MapEvents](../deckgl/base-map/events.md) - Event types including viewport updates
* [createMapStore](../shared/create-map-store.md) - Underlying store pattern used by viewport
# applyTo (/docs/packages/core/combinators/apply-to)
## Usage [#usage]
```typescript
import { applyTo } from '@accelint/core';
// Apply function to value
const result = applyTo(6)((x: number) => x * 2);
// 12
// Partial application
const with10 = applyTo(10);
with10((x: number) => x + 5); // 15
```
## Reference [#reference]
```typescript
function applyTo<A>(
a: A
): <B>(b: (x: A) => B) => B
```
Lambda calculus: `λab.ba`\
Type signature: `applyTo :: a → (a → b) → b`
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---- | ---------------------------------- |
| `a` | `A` | The value to pass to the function. |
### Returns [#returns]
Returns a curried function that accepts a unary function and applies it to the value.
### Type Parameters [#type-parameters]
* `A` - The type of the input value
* `B` - The return type of the function
## Examples [#examples]
### Example: Data transformation pipeline [#example-data-transformation-pipeline]
```typescript
import { applyTo } from '@accelint/core';
interface User {
name: string;
age: number;
}
const user: User = { name: 'Alice', age: 30 };
// Pass data through transformations
const greeting = applyTo(user)((u) => `Hello, ${u.name}!`);
// "Hello, Alice!"
```
### Example: Method chaining alternative [#example-method-chaining-alternative]
```typescript
import { applyTo } from '@accelint/core';
const data = [1, 2, 3, 4, 5];
// Instead of: data.map(x => x * 2).filter(x => x > 5)
const result = applyTo(data)(
(arr) => arr.map((x) => x * 2)
)(
(arr) => arr.filter((x) => x > 5)
);
// Type error - need proper composition
// Better with pipe:
import { pipe } from '@accelint/core';
const process = pipe(
(arr: number[]) => arr.map((x) => x * 2),
(arr: number[]) => arr.filter((x) => x > 5)
);
process(data); // [6, 8, 10]
```
### Example: Dependency injection pattern [#example-dependency-injection-pattern]
```typescript
import { applyTo } from '@accelint/core';
interface Config {
apiUrl: string;
timeout: number;
}
const config: Config = {
apiUrl: 'https://api.example.com',
timeout: 5000
};
// Pass config to functions that need it
const makeRequest = applyTo(config)((cfg) => {
return `Requesting ${cfg.apiUrl} with ${cfg.timeout}ms timeout`;
});
```
> **Good to know:** This combinator is the inverse of `apply`. It's useful when you have a value first and want to pass it through various functions. For composing multiple functions, use `pipe` or `compose` instead.
## Related [#related]
* [apply](../apply/index.md) - Apply function to value (normal order)
* [pipe](../../composition/pipe/index.md) - Compose functions left-to-right
* [identity](../identity/index.md) - Return value unchanged
# apply (/docs/packages/core/combinators/apply)
Takes a unary function and applies it to a value. Also known as the A combinator in lambda calculus.
## Usage [#usage]
```typescript
import { apply } from '@accelint/core';
// Apply function to value
const result = apply((a: number) => a + 6)(3);
// 9
// Partial application
const applyDouble = apply((x: number) => x * 2);
applyDouble(5); // 10
```
## Reference [#reference]
```typescript
function apply<T, R>(
f: (x: T) => R
): (x: T) => R
```
Lambda calculus: `λab.ab`\
Type signature: `apply :: (a → b) → a → b`
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ------------- | ----------------------------------- |
| `f` | `(x: T) => R` | The function to apply to the value. |
### Returns [#returns]
Returns a curried function that accepts a value and applies the function to it.
### Type Parameters [#type-parameters]
* `T` - The type of the input value
* `R` - The return type of the function
## Examples [#examples]
### Example: Function application [#example-function-application]
```typescript
import { apply } from '@accelint/core';
const double = (x: number) => x * 2;
const addTen = (x: number) => x + 10;
apply(double)(5); // 10
apply(addTen)(5); // 15
```
### Example: With complex types [#example-with-complex-types]
```typescript
import { apply } from '@accelint/core';
interface User {
name: string;
age: number;
}
const getAge = (user: User) => user.age;
const getName = (user: User) => user.name;
const user: User = { name: 'Alice', age: 30 };
apply(getAge)(user); // 30
apply(getName)(user); // 'Alice'
```
### Example: Mapping over arrays [#example-mapping-over-arrays]
```typescript
import { apply, map } from '@accelint/core';
const functions = [
(x: number) => x + 1,
(x: number) => x * 2,
(x: number) => x - 3
];
// Apply each function to a value
const results = map((fn: (x: number) => number) => apply(fn)(5))(functions);
// [6, 10, 2]
```
> **Good to know:** This is equivalent to standard function application `f(x)`, but in curried form. It's useful for composing with higher-order functions or when you need to pass function application as a value.
## Related [#related]
* [applyTo](../apply-to/index.md) - Apply value to function (inverse)
* [identity](../identity/index.md) - Return value unchanged
* [pipe](../../composition/pipe/index.md) - Compose functions left-to-right
# composition (/docs/packages/core/combinators/composition)
Composes two functions, applying the second function first and passing its result to the first function. Also known as the B combinator in lambda calculus.
## Usage [#usage]
```typescript
import { composition } from '@accelint/core';
// Compose two functions
const result = composition((x: number) => x + 8)((x: number) => x * 3)(4);
// 20 (4 * 3 = 12, 12 + 8 = 20)
// Partial application
const multiplyThenAdd = composition((x: number) => x + 10);
multiplyThenAdd((x: number) => x * 2)(5); // 20
```
## Reference [#reference]
```typescript
function composition<A, B>(
f: (z: A) => B
): <C>(g: (y: C) => A) => (x: C) => B
```
Lambda calculus: `λabc.a(bc)`\
Type signature: `composition :: (a → b) → (c → a) → c → b`
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ------------- | ------------------------------------------------------ |
| `f` | `(z: A) => B` | The second function in the composition (applied last). |
| `g` | `(y: C) => A` | The first function in the composition (applied first). |
| `x` | `C` | The value to pass to `g`. |
### Returns [#returns]
Returns the result of `f(g(x))`.
### Type Parameters [#type-parameters]
* `A` - The return type of `g` and input type of `f`
* `B` - The return type of `f`
* `C` - The input type of `g`
## Examples [#examples]
### Example: Data transformation [#example-data-transformation]
```typescript
import { composition } from '@accelint/core';
const trim = (s: string) => s.trim();
const toUpperCase = (s: string) => s.toUpperCase();
const trimAndUpper = composition(toUpperCase)(trim);
trimAndUpper(' hello '); // 'HELLO'
```
### Example: Mathematical operations [#example-mathematical-operations]
```typescript
import { composition } from '@accelint/core';
const square = (x: number) => x * x;
const increment = (x: number) => x + 1;
// Square then increment
const squareThenInc = composition(increment)(square);
squareThenInc(5); // 26 (5² = 25, 25 + 1 = 26)
// Increment then square
const incThenSquare = composition(square)(increment);
incThenSquare(5); // 36 (5 + 1 = 6, 6² = 36)
```
### Example: Object transformations [#example-object-transformations]
```typescript
import { composition } from '@accelint/core';
interface User {
firstName: string;
lastName: string;
}
interface FullName {
fullName: string;
}
const getFullName = (u: User): string =>
`${u.firstName} ${u.lastName}`;
const toNameObject = (name: string): FullName => ({ fullName: name });
const transform = composition(toNameObject)(getFullName);
const user: User = { firstName: 'John', lastName: 'Doe' };
transform(user); // { fullName: 'John Doe' }
```
### Example: Validation pipeline [#example-validation-pipeline]
```typescript
import { composition } from '@accelint/core';
const isNotEmpty = (s: string): boolean => s.length > 0;
const hasMinLength = (min: number) => (s: string): boolean => s.length >= min;
// Check string after trimming
const validateAfterTrim = (min: number) =>
composition(hasMinLength(min))((s: string) => s.trim());
validateAfterTrim(3)(' ab '); // false (trimmed length is 2)
validateAfterTrim(3)(' abc '); // true (trimmed length is 3)
```
> **Good to know:** This combinator applies functions right-to-left (`f(g(x))`). For left-to-right composition, use [pipe](../../composition/pipe/index.md). For composing more than two functions, use [compose](../../composition/compose/index.md).
## Related [#related]
* [pipe](../../composition/pipe/index.md) - Compose functions left-to-right
* [compose](../../composition/compose/index.md) - Compose multiple functions right-to-left
* [apply](../apply/index.md) - Apply function to value
# constant (/docs/packages/core/combinators/constant)
Takes two arguments and always returns the first, ignoring the second. Corresponds to the encoding of `true` in lambda calculus. Also known as the K combinator.
## Usage [#usage]
```typescript
import { constant } from '@accelint/core';
// Always returns first argument
const result = constant(1)(2);
// 1
// Partial application - create a constant function
const alwaysFive = constant(5);
alwaysFive(10); // 5
alwaysFive('hello'); // 5
```
## Reference [#reference]
```typescript
function constant<A>(
a: A
): <B>(_: B) => A
```
Lambda calculus: `λab.a`\
Type signature: `constant :: a → b → a`
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---- | -------------------- |
| `a` | `A` | The value to return. |
| `_` | `B` | The value to ignore. |
### Returns [#returns]
Returns the first argument, regardless of the second.
### Type Parameters [#type-parameters]
* `A` - The type of the returned value
* `B` - The type of the ignored value
## Examples [#examples]
### Example: Default values [#example-default-values]
```typescript
import { constant } from '@accelint/core';
const defaultConfig = { timeout: 5000, retries: 3 };
// Always return default config
const getConfig = constant(defaultConfig);
getConfig(null); // { timeout: 5000, retries: 3 }
getConfig(undefined); // { timeout: 5000, retries: 3 }
```
### Example: Mapping to constant [#example-mapping-to-constant]
```typescript
import { constant, map } from '@accelint/core';
const items = ['a', 'b', 'c', 'd'];
// Map all elements to the same value
const zeros = map(constant(0))(items);
// [0, 0, 0, 0]
```
### Example: Boolean logic (true encoding) [#example-boolean-logic-true-encoding]
```typescript
import { constant, inverseConstant } from '@accelint/core';
// In lambda calculus, constant represents "true"
const ifThenElse = <T>(condition: boolean) =>
condition ? constant<T> : inverseConstant<T>;
const chooseFirst = ifThenElse<number>(true);
chooseFirst(10)(20); // 10
const chooseSecond = ifThenElse<number>(false);
chooseSecond(10)(20); // 20
```
### Example: Ignoring function results [#example-ignoring-function-results]
```typescript
import { constant } from '@accelint/core';
interface Logger {
log: (message: string) => void;
}
// Create a no-op logger that always returns undefined
const noopLogger: Logger = {
log: constant(undefined)
};
noopLogger.log('This is ignored'); // undefined
```
### Example: Fixed responses [#example-fixed-responses]
```typescript
import { constant } from '@accelint/core';
type Handler<T> = (req: unknown) => T;
const notFoundHandler: Handler<{ error: string }> =
constant({ error: 'Not Found' });
notFoundHandler({}); // { error: 'Not Found' }
notFoundHandler({ id: 123 }); // { error: 'Not Found' }
```
> **Good to know:** This combinator is fundamental in lambda calculus and represents the boolean value `true`. Its inverse, [inverseConstant](../inverse-constant/index.md), represents `false`.
## Related [#related]
* [inverseConstant](../inverse-constant/index.md) - Return second argument (false)
* [identity](../identity/index.md) - Return value unchanged
* [noop](../../utility/noop/index.md) - No-operation function
# fork (/docs/packages/core/combinators/fork)
Passes a value through two different functions and combines their results with a binary function. Also known as the Phi (Φ) combinator in lambda calculus.
## Usage [#usage]
```typescript
import { fork } from '@accelint/core';
// Fork a value through two functions
const result = fork((x: number) => (y: number) => x + y)
((x: number) => x + 3)
((x: number) => x - 2)
(9);
// 19 (9+3=12, 9-2=7, 12+7=19)
// Partial application
const computeSum = fork((x: number) => (y: number) => x + y);
computeSum((x: number) => x * 2)((x: number) => x + 1)(5);
// 16 (5*2=10, 5+1=6, 10+6=16)
```
## Reference [#reference]
```typescript
function fork<A, B, C>(
a: (x: A) => (y: B) => C
): <D>(b: (x: D) => A) => (c: (x: D) => B) => (d: D) => C
```
Lambda calculus: `λabcd.a(bd)(cd)`\
Type signature: `fork :: (a → b → c) → (d → a) → (d → b) → d → c`
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ----------------------- | ---------------------------------------------- |
| `a` | `(x: A) => (y: B) => C` | The binary function that combines the results. |
| `b` | `(x: D) => A` | The first function to apply to the value. |
| `c` | `(x: D) => B` | The second function to apply to the value. |
| `d` | `D` | The value to fork through both functions. |
### Returns [#returns]
Returns the result of `a(b(d))(c(d))`.
### Type Parameters [#type-parameters]
* `A` - The return type of function `b` and first input to `a`
* `B` - The return type of function `c` and second input to `a`
* `C` - The return type of the combining function `a`
* `D` - The type of the input value
## Examples [#examples]
### Example: Computing statistics [#example-computing-statistics]
```typescript
import { fork } from '@accelint/core';
const stats = fork((sum: number) => (count: number) => ({
sum,
count,
average: count > 0 ? sum / count : 0
}));
const computeStats = (numbers: number[]) =>
stats
((arr: number[]) => arr.reduce((a, b) => a + b, 0))
((arr: number[]) => arr.length)
(numbers);
computeStats([1, 2, 3, 4, 5]);
// { sum: 15, count: 5, average: 3 }
```
### Example: Validation with multiple rules [#example-validation-with-multiple-rules]
```typescript
import { fork } from '@accelint/core';
interface ValidationResult {
hasMinLength: boolean;
hasMaxLength: boolean;
isValid: boolean;
}
const validateString = fork((min: boolean) => (max: boolean): ValidationResult => ({
hasMinLength: min,
hasMaxLength: max,
isValid: min && max
}));
const validate = validateString
((s: string) => s.length >= 3)
((s: string) => s.length <= 10);
validate('hi'); // { hasMinLength: false, hasMaxLength: true, isValid: false }
validate('hello'); // { hasMinLength: true, hasMaxLength: true, isValid: true }
```
### Example: Parallel transformations [#example-parallel-transformations]
```typescript
import { fork } from '@accelint/core';
interface User {
firstName: string;
lastName: string;
}
const formatUser = fork((first: string) => (last: string) => `${first} ${last}`);
const getFormattedName = formatUser
((u: User) => u.firstName.toUpperCase())
((u: User) => u.lastName.toUpperCase());
getFormattedName({ firstName: 'john', lastName: 'doe' });
// 'JOHN DOE'
```
### Example: Combining calculations [#example-combining-calculations]
```typescript
import { fork } from '@accelint/core';
const calculateDiscount = fork((price: number) => (discount: number) => price * (1 - discount));
interface Product {
price: number;
category: string;
}
const getCategoryDiscount = (category: string): number => {
return category === 'electronics' ? 0.1 : 0.05;
};
const applyDiscount = calculateDiscount
((p: Product) => p.price)
((p: Product) => getCategoryDiscount(p.category));
applyDiscount({ price: 100, category: 'electronics' });
// 90 (10% discount)
```
> **Good to know:** The fork combinator is useful when you need to apply multiple transformations to the same input and combine their results. It avoids recomputing the input or storing intermediate values.
## Related [#related]
* [composition](../composition/index.md) - Compose two functions
* [apply](../apply/index.md) - Apply function to value
* [pipe](../../composition/pipe/index.md) - Compose functions left-to-right
# identity (/docs/packages/core/combinators/identity)
## Usage [#usage]
```typescript
import { identity } from '@accelint/core';
// Returns the same value
identity(4); // 4
identity('hello'); // 'hello'
identity([1, 2, 3]); // [1, 2, 3]
```
## Reference [#reference]
```typescript
function identity<A>(x: A): A
```
Lambda calculus: `λa.a`\
Type signature: `identity :: a → a`
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---- | -------------------- |
| `x` | `A` | The value to return. |
### Returns [#returns]
Returns the input value unchanged.
### Type Parameters [#type-parameters]
* `A` - The type of the input and output value
## Examples [#examples]
### Example: Default mapping function [#example-default-mapping-function]
```typescript
import { identity, map } from '@accelint/core';
const numbers = [1, 2, 3, 4, 5];
// Identity mapping - returns a shallow copy
const copy = map(identity)(numbers);
// [1, 2, 3, 4, 5]
```
### Example: Filtering with identity [#example-filtering-with-identity]
```typescript
import { identity, filter } from '@accelint/core';
const mixed: (number | null | undefined)[] = [1, null, 2, undefined, 3, 0, 4];
// Filter truthy values
const truthy = filter(identity)(mixed);
// [1, 2, 3, 4] (removes null, undefined, and 0)
```
### Example: Function composition identity [#example-function-composition-identity]
```typescript
import { identity, pipe } from '@accelint/core';
// Identity is the neutral element for composition
const double = (x: number) => x * 2;
// compose(identity, f) === f
pipe(identity, double)(5); // 10
pipe(double, identity)(5); // 10
```
### Example: Conditional transformation [#example-conditional-transformation]
```typescript
import { identity } from '@accelint/core';
function transform<T>(
value: T,
shouldTransform: boolean,
transformer: (v: T) => T
): T {
return shouldTransform ? transformer(value) : identity(value);
}
transform(10, true, (x) => x * 2); // 20
transform(10, false, (x) => x * 2); // 10
```
### Example: Type assertions [#example-type-assertions]
```typescript
import { identity } from '@accelint/core';
// Identity can help with type narrowing
const value: unknown = 'hello';
// Type assertion
const str = identity(value as string);
// str: string
```
### Example: Placeholder function [#example-placeholder-function]
```typescript
import { identity } from '@accelint/core';
interface Config {
transform?: <T>(value: T) => T;
}
const config: Config = {
// Use identity as default transform (no-op)
transform: identity
};
const result = config.transform?.(42) ?? 42;
// 42
```
> **Good to know:** The identity function is the neutral element for function composition. It's often used as a default or placeholder when a transformation function is optional, or for type-level operations.
## Related [#related]
* [constant](../constant/index.md) - Return first argument
* [noop](../../utility/noop/index.md) - No-operation function
* [tap](../../utility/tap/index.md) - Execute side effect and return value
# inverseConstant (/docs/packages/core/combinators/inverse-constant)
Takes two arguments and always returns the second, ignoring the first. Corresponds to the encoding of `false` in lambda calculus. Inverse of `constant`. Also known as the KI combinator.
## Usage [#usage]
```typescript
import { inverseConstant } from '@accelint/core';
// Always returns second argument
const result = inverseConstant(1)(2);
// 2
// Partial application
const ignoreFirst = inverseConstant('ignored');
ignoreFirst(10); // 10
ignoreFirst('hello'); // 'hello'
```
## Reference [#reference]
```typescript
function inverseConstant<A>(
_: A
): <B>(b: B) => B
```
Lambda calculus: `λab.b`\
Type signature: `inverseConstant :: a → b → b`
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---- | -------------------- |
| `_` | `A` | The value to ignore. |
| `b` | `B` | The value to return. |
### Returns [#returns]
Returns the second argument, regardless of the first.
### Type Parameters [#type-parameters]
* `A` - The type of the ignored value
* `B` - The type of the returned value
## Examples [#examples]
### Example: Boolean logic (false encoding) [#example-boolean-logic-false-encoding]
```typescript
import { constant, inverseConstant } from '@accelint/core';
// In lambda calculus, inverseConstant represents "false"
const ifThenElse = <T>(condition: boolean) =>
condition ? constant<T> : inverseConstant<T>;
const chooseFirst = ifThenElse<number>(true);
chooseFirst(10)(20); // 10
const chooseSecond = ifThenElse<number>(false);
chooseSecond(10)(20); // 20
```
### Example: Fallback values [#example-fallback-values]
```typescript
import { inverseConstant } from '@accelint/core';
const useFallback = inverseConstant(null);
useFallback('default'); // 'default'
useFallback(42); // 42
```
### Example: Ignoring side effects [#example-ignoring-side-effects]
```typescript
import { inverseConstant } from '@accelint/core';
function performAction<T>(
action: () => void,
value: T
): T {
return inverseConstant(action())(value);
}
let called = false;
const result = performAction(() => { called = true; }, 42);
// called: true
// result: 42
```
### Example: Pipeline with discarded steps [#example-pipeline-with-discarded-steps]
```typescript
import { inverseConstant } from '@accelint/core';
interface Logger {
log: (message: string) => void;
}
const logger: Logger = {
log: (msg) => console.log(msg)
};
// Log but return original value
const logAndReturn = <T>(message: string) => (value: T): T =>
inverseConstant(logger.log(message))(value);
const process = logAndReturn('Processing...');
process(42); // Logs "Processing..." and returns 42
```
### Example: Default second argument [#example-default-second-argument]
```typescript
import { inverseConstant } from '@accelint/core';
// Create a function that always uses the second argument
const alwaysSecond = <T>() => inverseConstant<unknown, T>(undefined);
const getSecond = alwaysSecond<string>();
getSecond(123)('hello'); // 'hello'
getSecond({ a: 1 })('world'); // 'world'
```
> **Good to know:** This combinator is the dual of [constant](../constant/index.md) and represents the boolean value `false` in lambda calculus. It's useful for ignoring the first argument while preserving the second.
## Related [#related]
* [constant](../constant/index.md) - Return first argument (true)
* [identity](../identity/index.md) - Return value unchanged
* [noop](../../utility/noop/index.md) - No-operation function
# concat (/docs/packages/core/array/concat)
## Usage [#usage]
```typescript
import { concat } from '@accelint/core/array/concat';
// Basic usage
const combined = concat([1, 2, 3])([4, 5, 6]);
// [1, 2, 3, 4, 5, 6]
// Partial application
const appendTo123 = concat([1, 2, 3]);
appendTo123([4, 5]); // [1, 2, 3, 4, 5]
```
## Reference [#reference]
```typescript
function concat<T>(
concatable: T[]
): (newValue: T[]) => T[]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ------------ | ----- | ----------------------------------------------------- |
| `concatable` | `T[]` | The first array (will be at the beginning of result). |
### Returns [#returns]
Returns a curried function that accepts a second array and returns a new array with all elements from both arrays.
### Type Parameters [#type-parameters]
* `T` - The type of elements in both arrays
## Examples [#examples]
### Example: Merging arrays of objects [#example-merging-arrays-of-objects]
```typescript
import { concat } from '@accelint/core/array/concat';
interface Item {
id: number;
name: string;
}
const first: Item[] = [{ id: 1, name: 'A' }];
const second: Item[] = [{ id: 2, name: 'B' }];
const merged = concat(first)(second);
// [{ id: 1, name: 'A' }, { id: 2, name: 'B' }]
```
### Example: Building arrays incrementally [#example-building-arrays-incrementally]
```typescript
import { concat } from '@accelint/core/array/concat';
import { pipe } from '@accelint/core/composition/pipe';
const buildArray = pipe(
concat([1, 2]),
concat([3, 4])
);
buildArray([5, 6]);
// [3, 4, 1, 2, 5, 6]
```
> **Good to know:** The original arrays are not modified—a new array is always returned. Elements are copied, not deeply cloned. This is a pure function with no side effects.
## Related [#related]
* [push](../push/index.md) - Add element to end of array
* [unshift](../unshift/index.md) - Add element to start of array
* [slice](../slice/index.md) - Extract portion of array
# every (/docs/packages/core/array/every)
## Usage [#usage]
```typescript
import { every } from '@accelint/core/array/every';
// Check if all numbers are even
const allEven = every((x: number) => x % 2 === 0)([2, 4, 6, 8]);
// true
const notAllEven = every((x: number) => x % 2 === 0)([2, 3, 4]);
// false
```
## Reference [#reference]
```typescript
function every<T>(
comparator: (element: T) => boolean
): (arr: T[]) => boolean
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `comparator` | `(element: T) => boolean` | Function called for each element. Returns `true` if element passes test, `false` otherwise. |
### Returns [#returns]
Returns a curried function that accepts an array and returns `true` if all elements pass the comparator, `false` otherwise.
### Type Parameters [#type-parameters]
* `T` - The type of elements in the array
## Examples [#examples]
### Example: Validating objects [#example-validating-objects]
```typescript
import { every } from '@accelint/core/array/every';
interface User {
id: number;
verified: boolean;
}
const users: User[] = [
{ id: 1, verified: true },
{ id: 2, verified: true }
];
const allVerified = every((u: User) => u.verified)(users);
// true
```
### Example: Type guards [#example-type-guards]
```typescript
import { every } from '@accelint/core/array/every';
const values: Array<string | number> = ['a', 'b', 'c'];
const allStrings = every((v: string | number) => typeof v === 'string')(values);
// true
```
> **Good to know:** Returns `true` for an empty array. Short-circuits on first failing element, providing early exit optimization. This is a pure function with no side effects.
## Related [#related]
* [some](../some/index.md) - Test if any element passes comparator
* [filter](../filter/index.md) - Get all elements matching predicate
* [find](../find/index.md) - Find first element matching predicate
# filter (/docs/packages/core/array/filter)
## Usage [#usage]
```typescript
import { filter } from '@accelint/core/array/filter';
// Basic usage - filter even numbers
const evens = filter((x: number) => x % 2 === 0)([1, 2, 3, 4, 5]);
// [2, 4]
// Partial application
const isEven = filter((x: number) => x % 2 === 0);
isEven([1, 2, 3, 4, 5]); // [2, 4]
```
## Reference [#reference]
```typescript
function filter<T>(
predicate: (element: T, index: number) => boolean
): (arr: T[]) => T[]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ----------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `predicate` | `(element: T, index: number) => boolean` | Function called for each element. Returns `true` to keep the element, `false` to exclude it. Receives the element and its index. |
### Returns [#returns]
Returns a curried function that accepts an array and returns a new array containing only elements that satisfy the predicate.
### Type Parameters [#type-parameters]
* `T` - The type of elements in the array
## Examples [#examples]
### Example: Filtering objects [#example-filtering-objects]
```typescript
import { filter } from '@accelint/core/array/filter';
interface User {
id: number;
active: boolean;
}
const users: User[] = [
{ id: 1, active: true },
{ id: 2, active: false },
{ id: 3, active: true }
];
const activeUsers = filter((user: User) => user.active)(users);
// [{ id: 1, active: true }, { id: 3, active: true }]
```
### Example: Using index parameter [#example-using-index-parameter]
```typescript
import { filter } from '@accelint/core/array/filter';
// Keep only even-indexed elements
const evenIndexed = filter((_: string, index: number) => index % 2 === 0);
evenIndexed(['a', 'b', 'c', 'd', 'e']);
// ['a', 'c', 'e']
```
### Example: Filtering null/undefined values [#example-filtering-nullundefined-values]
```typescript
import { filter } from '@accelint/core/array/filter';
const values = [1, null, 2, undefined, 3];
const defined = filter((x: number | null | undefined) => x != null)(values);
// [1, 2, 3]
```
### Example: Composing with map [#example-composing-with-map]
```typescript
import { filter } from '@accelint/core/array/filter';
import { map } from '@accelint/core/array/map';
import { pipe } from '@accelint/core/composition/pipe';
const processNumbers = pipe(
filter((x: number) => x > 0),
map((x: number) => x * 2)
);
processNumbers([-2, -1, 0, 1, 2, 3]);
// [2, 4, 6]
```
> **Good to know:** The predicate function is called for every element in the array until the end is reached. The original array is not modified—a new array is always returned. This is a pure function with no side effects.
## Related [#related]
* [map](../map/index.md) - Transform array elements
* [find](../find/index.md) - Find first element matching predicate
* [every](../every/index.md) - Test if all elements pass predicate
* [some](../some/index.md) - Test if any element passes predicate
# findIndex (/docs/packages/core/array/find-index)
## Usage [#usage]
```typescript
import { findIndex } from '@accelint/core';
// Find index of first even number
const firstEvenIndex = findIndex((x: number) => x % 2 === 0)([1, 2, 3, 4, 5]);
// 1
// Partial application
const findNegative = findIndex((x: number) => x < 0);
findNegative([5, 10, -3, 8]); // 2
```
## Reference [#reference]
```typescript
function findIndex<T>(
predicate: (element: T, index: number) => boolean
): (arr: T[]) => number
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ----------- | ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| `predicate` | `(element: T, index: number) => boolean` | Function called for each element until it returns `true`. Receives the element and its index. |
### Returns [#returns]
Returns a curried function that accepts an array and returns the index of the first matching element, or `-1` if no match is found.
### Type Parameters [#type-parameters]
* `T` - The type of elements in the array
## Examples [#examples]
### Example: Finding by property value [#example-finding-by-property-value]
```typescript
import { findIndex } from '@accelint/core';
interface Product {
id: number;
name: string;
inStock: boolean;
}
const products: Product[] = [
{ id: 1, name: 'Laptop', inStock: false },
{ id: 2, name: 'Mouse', inStock: true },
{ id: 3, name: 'Keyboard', inStock: true }
];
const firstInStockIndex = findIndex((p: Product) => p.inStock)(products);
// 1
```
### Example: Using index parameter [#example-using-index-parameter]
```typescript
import { findIndex } from '@accelint/core';
// Find first element greater than its index
const data = [0, 0, 5, 2, 10];
const index = findIndex((value: number, idx: number) => value > idx)(data);
// 2 (value 5 > index 2)
```
### Example: Element not found [#example-element-not-found]
```typescript
import { findIndex } from '@accelint/core';
const numbers = [1, 3, 5, 7, 9];
const evenIndex = findIndex((x: number) => x % 2 === 0)(numbers);
// -1 (no even numbers found)
```
> **Good to know:** The predicate is called only until a matching element is found. Once found, iteration stops immediately and the index is returned.
## Related [#related]
* [find](../find/index.md) - Find the first matching element
* [findLastIndex](../find-last-index/index.md) - Find index from the end of array
* [indexOf](../index-of/index.md) - Find index by value equality
* [filter](../filter/index.md) - Find all matching elements
# findLastIndex (/docs/packages/core/array/find-last-index)
## Usage [#usage]
```typescript
import { findLastIndex } from '@accelint/core';
// Find index of last even number
const lastEvenIndex = findLastIndex((x: number) => x % 2 === 0)([1, 2, 3, 4, 5]);
// 3
// Partial application
const findLastNegative = findLastIndex((x: number) => x < 0);
findLastNegative([5, -3, 10, -8]); // 3
```
## Reference [#reference]
```typescript
function findLastIndex<T>(
predicate: (element: T, index: number) => boolean
): (arr: T[]) => number
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ----------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `predicate` | `(element: T, index: number) => boolean` | Function called for each element from the end until it returns `true`. Receives the element and its index. |
### Returns [#returns]
Returns a curried function that accepts an array and returns the index of the last matching element, or `-1` if no match is found.
### Type Parameters [#type-parameters]
* `T` - The type of elements in the array
## Examples [#examples]
### Example: Finding last occurrence [#example-finding-last-occurrence]
```typescript
import { findLastIndex } from '@accelint/core';
const data = [1, 2, 3, 2, 1];
const lastTwoIndex = findLastIndex((x: number) => x === 2)(data);
// 3 (finds the second occurrence of 2)
```
### Example: Finding by complex condition [#example-finding-by-complex-condition]
```typescript
import { findLastIndex } from '@accelint/core';
interface Task {
id: number;
completed: boolean;
priority: 'low' | 'medium' | 'high';
}
const tasks: Task[] = [
{ id: 1, completed: true, priority: 'high' },
{ id: 2, completed: false, priority: 'medium' },
{ id: 3, completed: true, priority: 'low' }
];
const lastCompletedIndex = findLastIndex((t: Task) => t.completed)(tasks);
// 2
```
### Example: Using index parameter [#example-using-index-parameter]
```typescript
import { findLastIndex } from '@accelint/core';
// Find last element where value equals index
const data = [0, 2, 2, 3, 5];
const index = findLastIndex((value: number, idx: number) => value === idx)(data);
// 3 (value 3 at index 3)
```
> **Good to know:** The search starts from the end of the array and moves backward. The predicate is called only until a matching element is found, then iteration stops immediately.
## Related [#related]
* [findIndex](../find-index/index.md) - Find index from the start of array
* [findLast](../find-last/index.md) - Find the last matching element
* [find](../find/index.md) - Find the first matching element
# findLast (/docs/packages/core/array/find-last)
## Usage [#usage]
```typescript
import { findLast } from '@accelint/core';
// Find last even number
const lastEven = findLast((x: number) => x % 2 === 0)([1, 2, 3, 4, 5]);
// 4
// Partial application
const findLastNegative = findLast((x: number) => x < 0);
findLastNegative([5, -3, 10, -8]); // -8
```
## Reference [#reference]
```typescript
function findLast<T>(
predicate: (element: T, index: number) => boolean
): (arr: T[]) => T | null
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ----------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `predicate` | `(element: T, index: number) => boolean` | Function called for each element from the end until it returns `true`. Receives the element and its index. |
### Returns [#returns]
Returns a curried function that accepts an array and returns the last matching element, or `null` if no match is found.
### Type Parameters [#type-parameters]
* `T` - The type of elements in the array
## Examples [#examples]
### Example: Finding last occurrence [#example-finding-last-occurrence]
```typescript
import { findLast } from '@accelint/core';
const data = [1, 2, 3, 2, 1];
const lastTwo = findLast((x: number) => x === 2)(data);
// 2 (finds the second occurrence)
```
### Example: Finding by complex condition [#example-finding-by-complex-condition]
```typescript
import { findLast } from '@accelint/core';
interface Order {
id: number;
status: 'pending' | 'completed' | 'cancelled';
amount: number;
}
const orders: Order[] = [
{ id: 1, status: 'completed', amount: 100 },
{ id: 2, status: 'pending', amount: 50 },
{ id: 3, status: 'completed', amount: 200 }
];
const lastCompleted = findLast((o: Order) => o.status === 'completed')(orders);
// { id: 3, status: 'completed', amount: 200 }
```
### Example: No match returns null [#example-no-match-returns-null]
```typescript
import { findLast } from '@accelint/core';
const numbers = [1, 3, 5, 7, 9];
const lastEven = findLast((x: number) => x % 2 === 0)(numbers);
// null
```
> **Good to know:** The search starts from the end of the array and moves backward. The predicate is called only until a matching element is found, then iteration stops immediately.
## Related [#related]
* [find](../find/index.md) - Find the first matching element
* [findLastIndex](../find-last-index/index.md) - Find the index of the last matching element
* [filter](../filter/index.md) - Find all matching elements
# find (/docs/packages/core/array/find)
## Usage [#usage]
```typescript
import { find } from '@accelint/core/array/find';
// Basic usage - find first even number
const firstEven = find((x: number) => x % 2 === 0)([1, 2, 3, 4, 5]);
// 2
// Not found returns null
const notFound = find((x: number) => x > 10)([1, 2, 3]);
// null
```
## Reference [#reference]
```typescript
function find<T>(
predicate: (element: T, index: number) => boolean
): (arr: T[]) => T | null
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ----------- | ---------------------------------------- | -------------------------------------------------------------------------------------- |
| `predicate` | `(element: T, index: number) => boolean` | Function called for each element until one passes. Receives the element and its index. |
### Returns [#returns]
Returns a curried function that accepts an array and returns the first element that satisfies the predicate, or `null` if none found.
### Type Parameters [#type-parameters]
* `T` - The type of elements in the array
## Examples [#examples]
### Example: Finding an object [#example-finding-an-object]
```typescript
import { find } from '@accelint/core/array/find';
interface User {
id: number;
name: string;
}
const users: User[] = [
{ id: 1, name: 'Alice' },
{ id: 2, name: 'Bob' }
];
const user = find((u: User) => u.id === 2)(users);
// { id: 2, name: 'Bob' }
```
### Example: Using index parameter [#example-using-index-parameter]
```typescript
import { find } from '@accelint/core/array/find';
// Find first element at an even index
const evenIndexed = find((_: string, index: number) => index % 2 === 0);
evenIndexed(['a', 'b', 'c', 'd']);
// 'a' (index 0)
```
> **Good to know:** Returns `null` (not `undefined`) when no element matches. The predicate stops executing once a match is found, providing early exit optimization. This is a pure function with no side effects.
## Related [#related]
* [filter](../filter/index.md) - Get all elements matching predicate
* [find-index](../find-index/index.md) - Get index of first matching element
* [find-last](../find-last/index.md) - Find from the end of the array
* [some](../some/index.md) - Test if any element passes predicate
# includes (/docs/packages/core/array/includes)
## Usage [#usage]
```typescript
import { includes } from '@accelint/core';
// Check if array includes a value
const hasThree = includes(3)([1, 2, 3, 4, 5]);
// true
// Partial application
const hasApple = includes('apple');
hasApple(['banana', 'orange', 'apple']); // true
```
## Reference [#reference]
```typescript
function includes<T>(
x: T
): (arr: T[]) => boolean
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---- | ------------------------------------- |
| `x` | `T` | The value to search for in the array. |
### Returns [#returns]
Returns a curried function that accepts an array and returns `true` if the array includes the value, `false` otherwise.
### Type Parameters [#type-parameters]
* `T` - The type of elements in the array and the value to search for
## Examples [#examples]
### Example: Checking primitive values [#example-checking-primitive-values]
```typescript
import { includes } from '@accelint/core';
const numbers = [1, 2, 3, 4, 5];
includes(3)(numbers); // true
includes(10)(numbers); // false
const strings = ['hello', 'world'];
includes('hello')(strings); // true
```
### Example: Strict equality comparison [#example-strict-equality-comparison]
```typescript
import { includes } from '@accelint/core';
// Objects are compared by reference
const obj = { id: 1 };
const arr = [obj, { id: 2 }];
includes(obj)(arr); // true
includes({ id: 1 })(arr); // false (different object reference)
```
### Example: Type safety [#example-type-safety]
```typescript
import { includes } from '@accelint/core';
const values: (string | number)[] = ['a', 1, 'b', 2];
// Type-safe usage
includes('a')(values); // true
includes(1)(values); // true
```
### Example: Composing with other functions [#example-composing-with-other-functions]
```typescript
import { includes, filter } from '@accelint/core';
const validIds = [1, 2, 3, 4, 5];
const items = [
{ id: 1, name: 'A' },
{ id: 6, name: 'B' },
{ id: 3, name: 'C' }
];
const filterValid = filter((item: typeof items[0]) =>
includes(item.id)(validIds)
);
filterValid(items);
// [{ id: 1, name: 'A' }, { id: 3, name: 'C' }]
```
> **Good to know:** This function uses strict equality (`===`) for comparison. For object comparisons, it checks reference equality, not deep equality.
## Related [#related]
* [indexOf](../index-of/index.md) - Find the index of an element
* [find](../find/index.md) - Find element by predicate
* [some](../some/index.md) - Test if any element matches predicate
# indexOf (/docs/packages/core/array/index-of)
## Usage [#usage]
```typescript
import { indexOf } from '@accelint/core';
// Find index of a value
const index = indexOf(3)([1, 2, 3, 4, 5]);
// 2
// Partial application
const findAppleIndex = indexOf('apple');
findAppleIndex(['banana', 'orange', 'apple']); // 2
```
## Reference [#reference]
```typescript
function indexOf<T>(
x: T
): (arr: T[]) => number
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---- | ------------------------------------- |
| `x` | `T` | The value to search for in the array. |
### Returns [#returns]
Returns a curried function that accepts an array and returns the index of the first occurrence of the value, or `-1` if not found.
### Type Parameters [#type-parameters]
* `T` - The type of elements in the array and the value to search for
## Examples [#examples]
### Example: Finding first occurrence [#example-finding-first-occurrence]
```typescript
import { indexOf } from '@accelint/core';
const data = [1, 2, 3, 2, 1];
indexOf(2)(data); // 1 (first occurrence)
```
### Example: Element not found [#example-element-not-found]
```typescript
import { indexOf } from '@accelint/core';
const numbers = [1, 2, 3, 4, 5];
indexOf(10)(numbers); // -1
```
### Example: Strict equality comparison [#example-strict-equality-comparison]
```typescript
import { indexOf } from '@accelint/core';
// Objects are compared by reference
const obj = { id: 1 };
const arr = [obj, { id: 2 }, { id: 3 }];
indexOf(obj)(arr); // 0
indexOf({ id: 1 })(arr); // -1 (different object reference)
```
### Example: Working with different types [#example-working-with-different-types]
```typescript
import { indexOf } from '@accelint/core';
const mixed: (string | number)[] = ['a', 1, 'b', 2];
indexOf('b')(mixed); // 2
indexOf(1)(mixed); // 1
```
### Example: Checking if element exists [#example-checking-if-element-exists]
```typescript
import { indexOf } from '@accelint/core';
const hasElement = (value: number) => (arr: number[]) =>
indexOf(value)(arr) !== -1;
const numbers = [1, 2, 3, 4, 5];
hasElement(3)(numbers); // true
hasElement(10)(numbers); // false
```
> **Good to know:** This function uses strict equality (`===`) for comparison. For predicate-based searches, use [findIndex](../find-index/index.md) instead.
## Related [#related]
* [findIndex](../find-index/index.md) - Find index by predicate
* [includes](../includes/index.md) - Check if array includes element
* [find](../find/index.md) - Find element by predicate
# map (/docs/packages/core/array/map)
## Usage [#usage]
```typescript
import { map } from '@accelint/core/array/map';
// Basic usage
const doubled = map((x: number) => x * 2)([1, 2, 3, 4, 5]);
// [2, 4, 6, 8, 10]
// Partial application
const double = map((x: number) => x * 2);
double([1, 2, 3]); // [2, 4, 6]
```
## Reference [#reference]
```typescript
function map<T, R>(
map: (element: T, index: number) => R
): (arr: T[]) => R[]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---------------------------------- | --------------------------------------------------------------------- |
| `map` | `(element: T, index: number) => R` | Function called for each element. Receives the element and its index. |
### Returns [#returns]
Returns a curried function that accepts an array and returns a new array with transformed elements.
### Type Parameters [#type-parameters]
* `T` - The type of elements in the input array
* `R` - The return type of the mapping function (type of elements in output array)
## Examples [#examples]
### Example: Transforming objects [#example-transforming-objects]
```typescript
import { map } from '@accelint/core/array/map';
interface User {
id: number;
name: string;
}
const users: User[] = [
{ id: 1, name: 'Alice' },
{ id: 2, name: 'Bob' }
];
const names = map((user: User) => user.name)(users);
// ['Alice', 'Bob']
```
### Example: Using index parameter [#example-using-index-parameter]
```typescript
import { map } from '@accelint/core/array/map';
const addIndex = map((value: string, index: number) => `${index}: ${value}`);
addIndex(['a', 'b', 'c']);
// ['0: a', '1: b', '2: c']
```
### Example: Composing with pipe [#example-composing-with-pipe]
```typescript
import { map } from '@accelint/core/array/map';
import { filter } from '@accelint/core/array/filter';
import { pipe } from '@accelint/core/composition/pipe';
const processNumbers = pipe(
filter((x: number) => x > 0),
map((x: number) => x * 2)
);
processNumbers([-1, 0, 1, 2, 3]);
// [2, 4, 6]
```
> **Good to know:** The mapping function is called for every element in the array. The original array is not modified—a new array is always returned. This is a pure function with no side effects.
## Related [#related]
* [filter](../filter/index.md) - Filter array elements by predicate
* [reduce](../reduce/index.md) - Reduce array to single value
* [pipe](../../composition/pipe/index.md) - Compose functions left-to-right
# push (/docs/packages/core/array/push)
## Usage [#usage]
```typescript
import { push } from '@accelint/core';
// Add element to end
const withFive = push([1, 2, 3, 4])(5);
// [1, 2, 3, 4, 5]
// Partial application
const addToNumbers = push([1, 2, 3]);
addToNumbers(4); // [1, 2, 3, 4]
```
## Reference [#reference]
```typescript
function push<T>(
arr: T[]
): (x: T) => T[]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ----- | ------------------------------- |
| `arr` | `T[]` | The array to add an element to. |
### Returns [#returns]
Returns a curried function that accepts a value and returns a new array with that value added to the end.
### Type Parameters [#type-parameters]
* `T` - The type of elements in the array
## Examples [#examples]
### Example: Building arrays immutably [#example-building-arrays-immutably]
```typescript
import { push } from '@accelint/core';
let numbers: number[] = [];
numbers = push(numbers)(1);
numbers = push(numbers)(2);
numbers = push(numbers)(3);
// [1, 2, 3]
// Original array unchanged
const original = [1, 2, 3];
const extended = push(original)(4);
// original: [1, 2, 3]
// extended: [1, 2, 3, 4]
```
### Example: Composing with pipe [#example-composing-with-pipe]
```typescript
import { push, map, pipe } from '@accelint/core';
const processAndAdd = pipe(
map((x: number) => x * 2),
push([10])
);
processAndAdd([1, 2, 3]);
// [10, 2, 4, 6]
```
### Example: Working with different types [#example-working-with-different-types]
```typescript
import { push } from '@accelint/core';
interface Task {
id: number;
title: string;
}
const tasks: Task[] = [
{ id: 1, title: 'Task 1' }
];
const withNewTask = push(tasks)({ id: 2, title: 'Task 2' });
// [{ id: 1, title: 'Task 1' }, { id: 2, title: 'Task 2' }]
```
> **Good to know:** This is a pure function that always returns a new array. The original array is never modified.
## Related [#related]
* [unshift](../unshift/index.md) - Add element to the start
* [concat](../concat/index.md) - Concatenate multiple arrays
* [slice](../slice/index.md) - Extract portion of array
# reduceRight (/docs/packages/core/array/reduce-right)
Calls the accumulator function with each element of an array, starting from the last element and moving toward the first. Returns the final accumulated result.
## Usage [#usage]
```typescript
import { reduceRight } from '@accelint/core';
// Concatenate from right to left
const reversed = reduceRight((acc: string, s: string) => `${acc}${s}`)('')(['a', 'b', 'c', 'd', 'e']);
// 'edcba'
// Partial application
const sumFromRight = reduceRight((acc: number, n: number) => acc + n)(0);
sumFromRight([1, 2, 3, 4, 5]); // 15
```
## Reference [#reference]
```typescript
function reduceRight<T, R>(
fn: (accumulator: R, element: T) => R
): (initVal: R) => (arr: T[]) => R
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `fn` | `(accumulator: R, element: T) => R` | The accumulator function called for each element. Receives the accumulated value and current element. |
| `initVal` | `R` | The initial value of the accumulation. |
### Returns [#returns]
Returns a curried function that accepts an initial value, which returns another function that accepts an array and returns the final accumulated result.
### Type Parameters [#type-parameters]
* `T` - The type of elements in the array
* `R` - The type of the accumulated result
## Examples [#examples]
### Example: Building strings from right [#example-building-strings-from-right]
```typescript
import { reduceRight } from '@accelint/core';
const words = ['world', 'hello'];
const sentence = reduceRight((acc: string, word: string) =>
acc ? `${acc} ${word}` : word
)('')(words);
// 'hello world'
```
### Example: Flattening nested arrays [#example-flattening-nested-arrays]
```typescript
import { reduceRight } from '@accelint/core';
const nested = [[1, 2], [3, 4], [5, 6]];
const flattened = reduceRight((acc: number[], arr: number[]) =>
[...arr, ...acc]
)([])(nested);
// [5, 6, 3, 4, 1, 2]
```
### Example: Building object from right [#example-building-object-from-right]
```typescript
import { reduceRight } from '@accelint/core';
interface Item {
key: string;
value: number;
}
const items: Item[] = [
{ key: 'a', value: 1 },
{ key: 'b', value: 2 },
{ key: 'a', value: 3 } // Overwrites first 'a'
];
const toObject = reduceRight((acc: Record<string, number>, item: Item) => ({
...acc,
[item.key]: item.value
}))({})(items);
// { b: 2, a: 1 } (first 'a' wins because we iterate from right)
```
### Example: Composing functions from right [#example-composing-functions-from-right]
```typescript
import { reduceRight } from '@accelint/core';
type UnaryFn<T> = (x: T) => T;
const composeFunctions = <T>(fns: UnaryFn<T>[]) =>
reduceRight((composed: UnaryFn<T>, fn: UnaryFn<T>) =>
(x: T) => composed(fn(x))
)((x: T) => x)(fns);
const add1 = (x: number) => x + 1;
const mult2 = (x: number) => x * 2;
const composed = composeFunctions([add1, mult2]);
composed(5); // 11 (mult2(5) = 10, then add1(10) = 11)
```
### Example: Difference from reduce [#example-difference-from-reduce]
```typescript
import { reduce, reduceRight } from '@accelint/core';
const data = ['a', 'b', 'c'];
// reduce: left to right
reduce((acc: string, s: string) => `${acc}${s}`)('')(data);
// 'abc'
// reduceRight: right to left
reduceRight((acc: string, s: string) => `${acc}${s}`)('')(data);
// 'cba'
```
> **Good to know:** The accumulator function receives parameters in the same order as `reduce` (accumulator first, element second), but the array is processed from right to left.
## Related [#related]
* [reduce](../reduce/index.md) - Reduce from left to right
* [reverse](../reverse/index.md) - Reverse array order
* [map](../map/index.md) - Transform array elements
# reduce (/docs/packages/core/array/reduce)
## Usage [#usage]
```typescript
import { reduce } from '@accelint/core/array/reduce';
// Basic usage - sum numbers
const sum = reduce((total: number, n: number) => total + n)(0)([1, 2, 3, 4, 5]);
// 15
// Partial application
const sumNumbers = reduce((total: number, n: number) => total + n)(0);
sumNumbers([1, 2, 3]); // 6
```
## Reference [#reference]
```typescript
function reduce<T, R>(
fn: (accumulator: R, element: T) => R
): (initVal: R) => (arr: T[]) => R
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `fn` | `(accumulator: R, element: T) => R` | Accumulator function called for each element. Receives the accumulator and current element, returns the new accumulator value. |
### Returns [#returns]
Returns a curried function that first accepts an initial value, then accepts an array, and finally returns the accumulated result.
### Type Parameters [#type-parameters]
* `T` - The type of array elements
* `R` - The type of the accumulator and return value
## Examples [#examples]
### Example: Building an object from array [#example-building-an-object-from-array]
```typescript
import { reduce } from '@accelint/core/array/reduce';
interface User {
id: number;
name: string;
}
const users: User[] = [
{ id: 1, name: 'Alice' },
{ id: 2, name: 'Bob' }
];
const userById = reduce(
(acc: Record<number, User>, user: User) => {
acc[user.id] = user;
return acc;
}
)({} as Record<number, User>)(users);
// { 1: { id: 1, name: 'Alice' }, 2: { id: 2, name: 'Bob' } }
```
### Example: Flattening arrays [#example-flattening-arrays]
```typescript
import { reduce } from '@accelint/core/array/reduce';
const nested = [[1, 2], [3, 4], [5]];
const flat = reduce(
(acc: number[], arr: number[]) => acc.concat(arr)
)([])(nested);
// [1, 2, 3, 4, 5]
```
### Example: Counting occurrences [#example-counting-occurrences]
```typescript
import { reduce } from '@accelint/core/array/reduce';
const words = ['apple', 'banana', 'apple', 'cherry', 'banana', 'apple'];
const counts = reduce(
(acc: Record<string, number>, word: string) => {
acc[word] = (acc[word] || 0) + 1;
return acc;
}
)({} as Record<string, number>)(words);
// { apple: 3, banana: 2, cherry: 1 }
```
### Example: Finding max value [#example-finding-max-value]
```typescript
import { reduce } from '@accelint/core/array/reduce';
const numbers = [5, 2, 9, 1, 7];
const max = reduce(
(acc: number, n: number) => Math.max(acc, n)
)(-Infinity)(numbers);
// 9
```
> **Good to know:** The accumulator function is called for every element in the array, left to right. The initial value is crucial—choose it carefully based on your accumulation logic. This is a pure function with no side effects.
## Related [#related]
* [map](../map/index.md) - Transform array elements
* [filter](../filter/index.md) - Filter array elements by predicate
* [reduce-right](../reduce-right/index.md) - Reduce array from right to left
# reverse (/docs/packages/core/array/reverse)
Returns a new array with the order of elements reversed. Does not mutate the original array.
## Usage [#usage]
```typescript
import { reverse } from '@accelint/core';
// Reverse an array
const reversed = reverse([1, 2, 3, 4, 5]);
// [5, 4, 3, 2, 1]
```
## Reference [#reference]
```typescript
function reverse<T>(
arr: T[]
): T[]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ----- | --------------------- |
| `arr` | `T[]` | The array to reverse. |
### Returns [#returns]
Returns a new array with elements in reversed order.
### Type Parameters [#type-parameters]
* `T` - The type of elements in the array
## Examples [#examples]
### Example: Reversing different types [#example-reversing-different-types]
```typescript
import { reverse } from '@accelint/core';
const numbers = reverse([1, 2, 3, 4, 5]);
// [5, 4, 3, 2, 1]
const strings = reverse(['a', 'b', 'c']);
// ['c', 'b', 'a']
```
### Example: Original array unchanged [#example-original-array-unchanged]
```typescript
import { reverse } from '@accelint/core';
const original = [1, 2, 3];
const reversed = reverse(original);
console.log(original); // [1, 2, 3]
console.log(reversed); // [3, 2, 1]
```
### Example: Processing in reverse order [#example-processing-in-reverse-order]
```typescript
import { reverse } from '@accelint/core';
interface Event {
id: number;
timestamp: Date;
}
const events: Event[] = [
{ id: 1, timestamp: new Date('2026-07-13T10:00:00') },
{ id: 2, timestamp: new Date('2026-07-13T11:00:00') },
{ id: 3, timestamp: new Date('2026-07-13T12:00:00') }
];
// Show most recent first
const recentFirst = reverse(events);
// [{ id: 3, ... }, { id: 2, ... }, { id: 1, ... }]
```
### Example: Composing with other functions [#example-composing-with-other-functions]
```typescript
import { reverse, map, pipe } from '@accelint/core';
const processInReverse = pipe(
reverse,
map((x: number) => x * 2)
);
processInReverse([1, 2, 3, 4]);
// [8, 6, 4, 2]
```
### Example: Palindrome check [#example-palindrome-check]
```typescript
import { reverse } from '@accelint/core';
function isPalindrome(arr: number[]): boolean {
const reversed = reverse(arr);
return arr.every((val, idx) => val === reversed[idx]);
}
isPalindrome([1, 2, 3, 2, 1]); // true
isPalindrome([1, 2, 3, 4, 5]); // false
```
> **Good to know:** This is a pure function that always returns a new array. The original array is never modified.
## Related [#related]
* [slice](../slice/index.md) - Extract portion of array
* [map](../map/index.md) - Transform array elements
* [reduceRight](../reduce-right/index.md) - Reduce from right to left
# shift (/docs/packages/core/array/shift)
Returns a tuple containing the first element (head) and the remaining elements (tail) of an array.
## Usage [#usage]
```typescript
import { shift } from '@accelint/core';
// Destructure head and tail
const [head, tail] = shift([1, 2, 3, 4, 5]);
// head: 1
// tail: [2, 3, 4, 5]
```
## Reference [#reference]
```typescript
function shift<T>(
arr: T[]
): [T, T[]]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ----- | ---------------------------------------- |
| `arr` | `T[]` | The array to extract head and tail from. |
### Returns [#returns]
Returns a tuple where the first element is the head (first element) and the second element is the tail (remaining elements).
### Type Parameters [#type-parameters]
* `T` - The type of elements in the array
## Examples [#examples]
### Example: Processing first element separately [#example-processing-first-element-separately]
```typescript
import { shift } from '@accelint/core';
const [first, rest] = shift([10, 20, 30, 40]);
console.log(`First: ${first}`); // "First: 10"
console.log(`Rest: ${rest}`); // "Rest: [20, 30, 40]"
```
### Example: Recursive pattern [#example-recursive-pattern]
```typescript
import { shift } from '@accelint/core';
function sumArray(arr: number[]): number {
if (arr.length === 0) return 0;
const [head, tail] = shift(arr);
return head + sumArray(tail);
}
sumArray([1, 2, 3, 4, 5]); // 15
```
### Example: Pattern matching style [#example-pattern-matching-style]
```typescript
import { shift } from '@accelint/core';
interface Item {
id: number;
value: string;
}
const items: Item[] = [
{ id: 1, value: 'first' },
{ id: 2, value: 'second' },
{ id: 3, value: 'third' }
];
const [current, remaining] = shift(items);
// current: { id: 1, value: 'first' }
// remaining: [{ id: 2, value: 'second' }, { id: 3, value: 'third' }]
```
### Example: Queue operations [#example-queue-operations]
```typescript
import { shift, push } from '@accelint/core';
// Dequeue operation
let queue = [1, 2, 3, 4];
const [item, newQueue] = shift(queue);
queue = newQueue;
// item: 1
// queue: [2, 3, 4]
// Enqueue operation
queue = push(queue)(5);
// queue: [2, 3, 4, 5]
```
> **Good to know:** This function does not handle empty arrays. Ensure the array has at least one element before calling `shift`.
## Related [#related]
* [unshift](../unshift/index.md) - Add element to the start
* [push](../push/index.md) - Add element to the end
* [slice](../slice/index.md) - Extract portion of array
# slice (/docs/packages/core/array/slice)
Returns a new array containing elements between `start` (inclusive) and `end` (exclusive) indices from the original array.
## Usage [#usage]
```typescript
import { slice } from '@accelint/core';
// Extract middle elements
const middle = slice(1)(4)([1, 2, 3, 4, 5, 6]);
// [2, 3, 4]
// Partial application
const firstThree = slice(0)(3);
firstThree([1, 2, 3, 4, 5]); // [1, 2, 3]
```
## Reference [#reference]
```typescript
function slice(
start: number
): (end: number) => <T>(arr: T[]) => T[]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------- | ---------------------------------- |
| `start` | `number` | The index to start at (inclusive). |
| `end` | `number` | The index to end at (exclusive). |
### Returns [#returns]
Returns a curried function that accepts an end index, which returns another function that accepts an array and returns the sliced portion.
## Examples [#examples]
### Example: Extracting portions [#example-extracting-portions]
```typescript
import { slice } from '@accelint/core';
const data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
slice(0)(5)(data); // [1, 2, 3, 4, 5]
slice(5)(10)(data); // [6, 7, 8, 9, 10]
slice(2)(7)(data); // [3, 4, 5, 6, 7]
```
### Example: Bounds handling [#example-bounds-handling]
```typescript
import { slice } from '@accelint/core';
const numbers = [1, 2, 3, 4, 5];
// End beyond array length
slice(0)(100)(numbers); // [1, 2, 3, 4, 5]
// Start and end beyond length
slice(10)(20)(numbers); // []
```
### Example: Pagination pattern [#example-pagination-pattern]
```typescript
import { slice } from '@accelint/core';
const items = Array.from({ length: 100 }, (_, i) => i + 1);
const getPage = (pageNumber: number, pageSize: number) => {
const start = pageNumber * pageSize;
const end = start + pageSize;
return slice(start)(end);
};
getPage(0, 10)(items); // [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
getPage(1, 10)(items); // [11, 12, 13, 14, 15, 16, 17, 18, 19, 20]
```
### Example: Composing with other functions [#example-composing-with-other-functions]
```typescript
import { slice, map, pipe } from '@accelint/core';
const processMiddle = pipe(
slice(2)(5),
map((x: number) => x * 2)
);
processMiddle([1, 2, 3, 4, 5, 6, 7]);
// [6, 8, 10] (elements [3, 4, 5] doubled)
```
> **Good to know:** If `end` exceeds the array length, the slice will include all elements from `start` to the end of the array.
## Related [#related]
* [concat](../concat/index.md) - Concatenate arrays
* [filter](../filter/index.md) - Filter elements by predicate
* [map](../map/index.md) - Transform array elements
# some (/docs/packages/core/array/some)
## Usage [#usage]
```typescript
import { some } from '@accelint/core/array/some';
// Check if any number is even
const hasEven = some((x: number) => x % 2 === 0)([1, 3, 4, 5]);
// true
const noEvens = some((x: number) => x % 2 === 0)([1, 3, 5]);
// false
```
## Reference [#reference]
```typescript
function some<T>(
comparator: (element: T) => boolean
): (arr: T[]) => boolean
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `comparator` | `(element: T) => boolean` | Function called for each element. Returns `true` if element passes test, `false` otherwise. |
### Returns [#returns]
Returns a curried function that accepts an array and returns `true` if any element passes the comparator, `false` otherwise.
### Type Parameters [#type-parameters]
* `T` - The type of elements in the array
## Examples [#examples]
### Example: Checking for conditions [#example-checking-for-conditions]
```typescript
import { some } from '@accelint/core/array/some';
interface Product {
name: string;
inStock: boolean;
}
const products: Product[] = [
{ name: 'Widget', inStock: false },
{ name: 'Gadget', inStock: true }
];
const anyAvailable = some((p: Product) => p.inStock)(products);
// true
```
### Example: Finding specific values [#example-finding-specific-values]
```typescript
import { some } from '@accelint/core/array/some';
const numbers = [1, 2, 3, 4, 5];
const hasNegative = some((n: number) => n < 0)(numbers);
// false
```
> **Good to know:** Returns `false` for an empty array. Short-circuits on first passing element, providing early exit optimization. This is a pure function with no side effects.
## Related [#related]
* [every](../every/index.md) - Test if all elements pass comparator
* [filter](../filter/index.md) - Get all elements matching predicate
* [find](../find/index.md) - Find first element matching predicate
# unshift (/docs/packages/core/array/unshift)
## Usage [#usage]
```typescript
import { unshift } from '@accelint/core';
// Add element to start
const withZero = unshift([1, 2, 3, 4])(0);
// [0, 1, 2, 3, 4]
// Partial application
const addToNumbers = unshift([2, 3, 4]);
addToNumbers(1); // [1, 2, 3, 4]
```
## Reference [#reference]
```typescript
function unshift<T>(
arr: T[]
): (x: T) => T[]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ----- | ------------------------------- |
| `arr` | `T[]` | The array to add an element to. |
### Returns [#returns]
Returns a curried function that accepts a value and returns a new array with that value added to the start.
### Type Parameters [#type-parameters]
* `T` - The type of elements in the array
## Examples [#examples]
### Example: Building arrays immutably [#example-building-arrays-immutably]
```typescript
import { unshift } from '@accelint/core';
let numbers: number[] = [];
numbers = unshift(numbers)(3);
numbers = unshift(numbers)(2);
numbers = unshift(numbers)(1);
// [1, 2, 3]
// Original array unchanged
const original = [2, 3, 4];
const extended = unshift(original)(1);
// original: [2, 3, 4]
// extended: [1, 2, 3, 4]
```
### Example: Stack operations [#example-stack-operations]
```typescript
import { unshift, shift } from '@accelint/core';
// Push to stack
let stack: number[] = [2, 3, 4];
stack = unshift(stack)(1);
// [1, 2, 3, 4]
// Pop from stack
const [top, newStack] = shift(stack);
// top: 1
// newStack: [2, 3, 4]
```
### Example: Prepending headers [#example-prepending-headers]
```typescript
import { unshift } from '@accelint/core';
interface LogEntry {
timestamp: Date;
message: string;
}
const logs: LogEntry[] = [
{ timestamp: new Date('2026-07-13T10:00:00'), message: 'Event 1' },
{ timestamp: new Date('2026-07-13T10:01:00'), message: 'Event 2' }
];
const newLog = { timestamp: new Date('2026-07-13T09:59:00'), message: 'Event 0' };
const updatedLogs = unshift(logs)(newLog);
// newLog is now at the start
```
### Example: Composing with pipe [#example-composing-with-pipe]
```typescript
import { unshift, map, pipe } from '@accelint/core';
const addHeaderAndDouble = (header: number) =>
pipe(
map((x: number) => x * 2),
unshift(header)
);
addHeaderAndDouble(0)([1, 2, 3]);
// [0, 2, 4, 6]
```
> **Good to know:** This is a pure function that always returns a new array. The original array is never modified.
## Related [#related]
* [push](../push/index.md) - Add element to the end
* [shift](../shift/index.md) - Extract first element and tail
* [concat](../concat/index.md) - Concatenate multiple arrays
# compose (/docs/packages/core/composition/compose)
## Usage [#usage]
```typescript
import { compose } from '@accelint/core/composition/compose';
// Basic usage - read from right to left
const transform = compose(
(x: number) => x.toString(),
(x: number) => x + 3,
(x: number) => x * 2
);
transform(5); // "13"
```
## Reference [#reference]
```typescript
function compose<Fns extends CompositionArray>(
...fns: Fns
): (...args: ComposeParams<Fns>) => ComposeReturn<Fns>
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------------- | ------------------------------------------------------------------------------------------------------ |
| `...fns` | Function array | The functions to compose. All functions except the last must be unary. The last function can be n-ary. |
### Returns [#returns]
Returns a function that executes the composed functions right-to-left, passing each result to the next function.
### Type Parameters [#type-parameters]
* `Fns` - Array of functions where all except the last must be unary
* `ComposeParams<Fns>` - Inferred parameter types of the last function
* `ComposeReturn<Fns>` - Inferred return type of the first function
## Examples [#examples]
### Example: Mathematical composition [#example-mathematical-composition]
```typescript
import { compose } from '@accelint/core/composition/compose';
// Traditional math notation: f(g(x))
const double = (x: number) => x * 2;
const addTen = (x: number) => x + 10;
const square = (x: number) => x * x;
const f = compose(square, addTen, double);
f(5); // 400 (square(addTen(double(5))) = (10 + 10)² = 400)
```
### Example: Data processing pipeline [#example-data-processing-pipeline]
```typescript
import { compose } from '@accelint/core/composition/compose';
const uppercase = (s: string) => s.toUpperCase();
const addExclamation = (s: string) => `${s}!`;
const trim = (s: string) => s.trim();
const shout = compose(uppercase, addExclamation, trim);
shout(' hello '); // "HELLO!"
```
> **Good to know:** `compose` executes right-to-left (mathematical composition order), while `pipe` executes left-to-right (reading order). They solve the same problem with different execution orders. Choose `pipe` for more readable data transformation pipelines, or `compose` when following mathematical notation.
## Related [#related]
* [pipe](../pipe/index.md) - Compose functions left-to-right
* [curry](../curry/index.md) - Transform multi-argument function into curried function
# autoCurry (/docs/packages/core/composition/curry)
## Usage [#usage]
```typescript
import { autoCurry } from '@accelint/core/composition/curry';
// Basic usage
const add = (a: number, b: number, c: number) => a + b + c;
const curried = autoCurry(add);
// All equivalent ways to call it
curried(1)(2)(3); // 6
curried(1, 2)(3); // 6
curried(1)(2, 3); // 6
curried(1, 2, 3); // 6
```
## Reference [#reference]
```typescript
function autoCurry<T extends (...args: any[]) => any>(
fn: T
): Curried<Parameters<T>, ReturnType<T>>
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------- | --------------------------------------------------------- |
| `fn` | Function | The function to curry. Can have any number of parameters. |
### Returns [#returns]
Returns a curried version that can accept arguments one at a time or in any grouping until all parameters are satisfied.
### Type Parameters [#type-parameters]
* `T` - The function type being curried
* `Parameters<T>` - The parameter types of the function
* `ReturnType<T>` - The return type of the function
## Examples [#examples]
### Example: Partial application [#example-partial-application]
```typescript
import { autoCurry } from '@accelint/core/composition/curry';
const multiply = (a: number, b: number, c: number) => a * b * c;
const curried = autoCurry(multiply);
// Create specialized functions
const double = curried(2);
const doubleAndTriple = double(3);
doubleAndTriple(5); // 30 (2 * 3 * 5)
```
### Example: Building configuration functions [#example-building-configuration-functions]
```typescript
import { autoCurry } from '@accelint/core/composition/curry';
const createConfig = (env: string, debug: boolean, port: number) => ({
environment: env,
debug,
port
});
const curried = autoCurry(createConfig);
// Create environment-specific builders
const prodConfig = curried('production')(false);
prodConfig(8080); // { environment: 'production', debug: false, port: 8080 }
const devConfig = curried('development', true);
devConfig(3000); // { environment: 'development', debug: true, port: 3000 }
```
### Example: Event handler builders [#example-event-handler-builders]
```typescript
import { autoCurry } from '@accelint/core/composition/curry';
const logEvent = (level: string, category: string, message: string) => {
console.log(`[${level}] ${category}: ${message}`);
};
const curried = autoCurry(logEvent);
// Create specialized loggers
const errorLog = curried('ERROR');
const errorAuth = errorLog('AUTH');
errorAuth('Login failed'); // [ERROR] AUTH: Login failed
```
> **Good to know:** Unlike manual currying (which requires strict one-argument-at-a-time application), `autoCurry` is flexible and accepts any number of arguments at each step until all parameters are satisfied. The function executes once all required arguments are provided.
## Related [#related]
* [pipe](../pipe/index.md) - Compose functions left-to-right
* [compose](../compose/index.md) - Compose functions right-to-left
* [map](../../array/map/index.md) - Pre-curried array transformation
# pipe (/docs/packages/core/composition/pipe)
## Usage [#usage]
```typescript
import { pipe } from '@accelint/core/composition/pipe';
// Basic usage
const transform = pipe(
(x: number) => x * 2,
(x: number) => x + 3,
(x: number) => x.toString()
);
transform(5); // "13"
```
## Reference [#reference]
```typescript
function pipe<Fns extends PipeArray>(
...fns: Fns
): (...args: PipeParams<Fns>) => PipeReturn<Fns>
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------------- | ----------------------------------------------------------------------------------------------- |
| `...fns` | Function array | The functions to pipe. The first function can be n-ary, all subsequent functions must be unary. |
### Returns [#returns]
Returns a function that executes the piped functions left-to-right, passing each result to the next function.
### Type Parameters [#type-parameters]
* `Fns` - Array of functions where the first may be n-ary and the rest must be unary
* `PipeParams<Fns>` - Inferred parameter types of the first function
* `PipeReturn<Fns>` - Inferred return type of the last function
## Examples [#examples]
### Example: Data transformation pipeline [#example-data-transformation-pipeline]
```typescript
import { pipe } from '@accelint/core/composition/pipe';
import { filter } from '@accelint/core/array/filter';
import { map } from '@accelint/core/array/map';
interface User {
id: number;
name: string;
active: boolean;
}
const getActiveUserNames = pipe(
filter((u: User) => u.active),
map((u: User) => u.name)
);
const users: User[] = [
{ id: 1, name: 'Alice', active: true },
{ id: 2, name: 'Bob', active: false },
{ id: 3, name: 'Charlie', active: true }
];
getActiveUserNames(users);
// ['Alice', 'Charlie']
```
### Example: N-ary first function [#example-n-ary-first-function]
```typescript
import { pipe } from '@accelint/core/composition/pipe';
// First function takes multiple arguments
const calculate = pipe(
(a: number, b: number) => a + b,
(sum: number) => sum * 2,
(result: number) => `Result: ${result}`
);
calculate(5, 3); // "Result: 16"
```
### Example: Complex transformations [#example-complex-transformations]
```typescript
import { pipe } from '@accelint/core/composition/pipe';
const processText = pipe(
(text: string) => text.toLowerCase(),
(text: string) => text.trim(),
(text: string) => text.split(' '),
(words: string[]) => words.filter(w => w.length > 3),
(words: string[]) => words.join(', ')
);
processText(' Hello World From TypeScript ');
// "hello, world, from, typescript"
```
### Example: Composing with reduce [#example-composing-with-reduce]
```typescript
import { pipe } from '@accelint/core/composition/pipe';
import { reduce } from '@accelint/core/array/reduce';
import { map } from '@accelint/core/array/map';
const sumSquares = pipe(
map((x: number) => x * x),
reduce((acc: number, n: number) => acc + n)(0)
);
sumSquares([1, 2, 3, 4]);
// 30 (1 + 4 + 9 + 16)
```
> **Good to know:** `pipe` executes left-to-right (reading order), while `compose` executes right-to-left (mathematical composition). The first function can accept multiple arguments, but all subsequent functions must be unary since they receive the previous function's single return value.
## Related [#related]
* [compose](../compose/index.md) - Compose functions right-to-left
* [curry](../curry/index.md) - Transform multi-argument function into curried function
* [map](../../array/map/index.md) - Transform array elements
* [filter](../../array/filter/index.md) - Filter array elements
* [reduce](../../array/reduce/index.md) - Reduce array to single value
# createIterable (/docs/packages/core/iterable/create-iterable)
Creates an iterable iterator object with a custom callback as the `next` method. Enables building custom iterators that work with `for...of` loops and spread syntax.
## Usage [#usage]
```typescript
import { createIterable } from '@accelint/core';
// Simple counter iterator
let count = 0;
const counter = createIterable(() =>
count < 3 ? { value: count++, done: false } : { value: undefined, done: true }
);
for (const num of counter) {
console.log(num); // 0, 1, 2
}
```
## Reference [#reference]
```typescript
function createIterable<T>(
iterCb: () => IteratorResult<T>
): IterableIterator<T>
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `iterCb` | `() => IteratorResult<T>` | The callback function called for each iteration. Returns `{ value: T, done: false }` to yield a value, or `{ value: T \| undefined, done: true }` to end iteration. |
### Returns [#returns]
Returns an iterable iterator object that can be used with `for...of` loops, spread syntax, and other iteration protocols.
### Type Parameters [#type-parameters]
* `T` - The type of values yielded by the iterator
## Examples [#examples]
### Example: Finite sequence [#example-finite-sequence]
```typescript
import { createIterable } from '@accelint/core';
const countdown = (from: number) => {
let current = from;
return createIterable(() => {
if (current >= 0) {
return { value: current--, done: false };
}
return { value: undefined, done: true };
});
};
const sequence = countdown(3);
[...sequence]; // [3, 2, 1, 0]
```
### Example: Custom data structure iteration [#example-custom-data-structure-iteration]
```typescript
import { createIterable } from '@accelint/core';
interface LinkedNode<T> {
value: T;
next: LinkedNode<T> | null;
}
function iterateList<T>(head: LinkedNode<T> | null) {
let current = head;
return createIterable(() => {
if (current === null) {
return { value: undefined, done: true };
}
const value = current.value;
current = current.next;
return { value, done: false };
});
}
const list = {
value: 1,
next: { value: 2, next: { value: 3, next: null } }
};
[...iterateList(list)]; // [1, 2, 3]
```
### Example: Infinite sequence with early termination [#example-infinite-sequence-with-early-termination]
```typescript
import { createIterable } from '@accelint/core';
const fibonacci = () => {
let a = 0, b = 1;
return createIterable(() => {
const value = a;
[a, b] = [b, a + b];
return { value, done: false }; // Never done - infinite sequence
});
};
// Take first 10 fibonacci numbers
const fib = fibonacci();
const first10 = [];
for (const num of fib) {
if (first10.length >= 10) break;
first10.push(num);
}
// [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
```
### Example: Async-style iteration (synchronous) [#example-async-style-iteration-synchronous]
```typescript
import { createIterable } from '@accelint/core';
function* generateIds() {
let id = 1;
while (true) yield id++;
}
const idGenerator = generateIds();
const getNextIds = (count: number) => {
const ids: number[] = [];
return createIterable(() => {
if (ids.length < count) {
return { value: idGenerator.next().value as number, done: false };
}
return { value: undefined, done: true };
});
};
[...getNextIds(5)]; // [1, 2, 3, 4, 5]
```
> **Good to know:** The callback function captures state via closure. For infinite sequences, the iterator never returns `done: true`. Use early breaks or limits to prevent infinite loops.
## Related [#related]
* [range](../range/index.md) - Create numeric range iterator
* [map](../../array/map/index.md) - Transform array elements
* [reduce](../../array/reduce/index.md) - Reduce array to single value
# range (/docs/packages/core/iterable/range)
Creates an iterator that yields numbers from `start` to `end` (both inclusive). Useful for generating numeric sequences without creating intermediate arrays.
## Usage [#usage]
```typescript
import { range } from '@accelint/core';
// Iterate from 1 to 10
for (const n of range(1, 10)) {
console.log(n);
}
// 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
// Convert to array
const rangeArr = [...range(1, 5)];
// [1, 2, 3, 4, 5]
```
## Reference [#reference]
```typescript
function range(
start: number,
end: number
): IterableIterator<number>
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------- | ----------------------------------- |
| `start` | `number` | The start of the range (inclusive). |
| `end` | `number` | The end of the range (inclusive). |
### Returns [#returns]
Returns an iterable iterator that yields numbers from `start` to `end`.
## Examples [#examples]
### Example: Basic numeric sequences [#example-basic-numeric-sequences]
```typescript
import { range } from '@accelint/core';
[...range(1, 5)]; // [1, 2, 3, 4, 5]
[...range(0, 3)]; // [0, 1, 2, 3]
[...range(10, 15)]; // [10, 11, 12, 13, 14, 15]
```
### Example: Single element range [#example-single-element-range]
```typescript
import { range } from '@accelint/core';
[...range(5, 5)]; // [5]
```
### Example: Memory-efficient iteration [#example-memory-efficient-iteration]
```typescript
import { range } from '@accelint/core';
// Instead of creating an array with 1 million elements
// const arr = Array.from({ length: 1000000 }, (_, i) => i);
// Use range to iterate without allocating the array
let sum = 0;
for (const n of range(0, 999999)) {
sum += n;
}
// Iterates efficiently without creating a large array
```
### Example: Generating test data [#example-generating-test-data]
```typescript
import { range } from '@accelint/core';
interface User {
id: number;
name: string;
}
const generateUsers = (count: number): User[] => {
const users: User[] = [];
for (const id of range(1, count)) {
users.push({ id, name: `User ${id}` });
}
return users;
};
generateUsers(3);
// [
// { id: 1, name: 'User 1' },
// { id: 2, name: 'User 2' },
// { id: 3, name: 'User 3' }
// ]
```
### Example: Pagination indices [#example-pagination-indices]
```typescript
import { range } from '@accelint/core';
const pageSize = 10;
const totalItems = 47;
const totalPages = Math.ceil(totalItems / pageSize);
const pageNumbers = [...range(1, totalPages)];
// [1, 2, 3, 4, 5]
```
### Example: Composing with array operations [#example-composing-with-array-operations]
```typescript
import { range } from '@accelint/core';
// Map over range
const squares = [...range(1, 5)].map(n => n * n);
// [1, 4, 9, 16, 25]
// Filter range
const evenNumbers = [...range(1, 10)].filter(n => n % 2 === 0);
// [2, 4, 6, 8, 10]
```
### Example: Reverse ranges [#example-reverse-ranges]
```typescript
import { range, reverse } from '@accelint/core';
// range doesn't support descending directly
// Use reverse to get descending order
const descending = reverse([...range(1, 5)]);
// [5, 4, 3, 2, 1]
```
> **Good to know:** Both `start` and `end` are inclusive. For descending ranges, first create an ascending range then reverse it. The iterator is lazy and only generates values as needed.
## Related [#related]
* [createIterable](../create-iterable/index.md) - Create custom iterators
* [map](../../array/map/index.md) - Transform array elements
* [reverse](../../array/reverse/index.md) - Reverse array order
# and (/docs/packages/core/logical/and)
## Usage [#usage]
```typescript
import { and, andFn } from '@accelint/core';
// Value-based conjunction
and(true)(1);
// true
and(true)(0);
// false
// Function-based conjunction
const isPositive = (x: number) => x > 0;
const isLessThan10 = (x: number) => x < 10;
andFn(isPositive)(isLessThan10)(5);
// true
andFn(isPositive)(isLessThan10)(15);
// false
```
## Reference [#reference]
### and [#and]
```typescript
function and<A>(a: A): <B>(b: B) => boolean
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---- | -------------------------- |
| `a` | `A` | The first value to compare |
#### Returns [#returns]
Returns a curried function that accepts a second value and returns `true` if both values are truthy, `false` otherwise.
#### Type Parameters [#type-parameters]
* `A` - The type of the first input value
* `B` - The type of the second input value
### andFn [#andfn]
```typescript
function andFn<T, A>(
a: (x: T) => A
): <B>(b: (y: T) => B) => (c: T) => boolean
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | ------------- | ------------------------------ |
| `a` | `(x: T) => A` | The first function to evaluate |
#### Returns [#returns-1]
Returns a curried function that accepts a second function, then accepts a value to pass to both functions, returning `true` if both function results are truthy, `false` otherwise.
#### Type Parameters [#type-parameters-1]
* `T` - The type of the input value passed to both functions
* `A` - The return type of the first function
* `B` - The return type of the second function
## Examples [#examples]
### Example: Validating conditions [#example-validating-conditions]
```typescript
import { and } from '@accelint/core';
const hasValue = (value: string | null) => value !== null;
const isNonEmpty = (value: string) => value.length > 0;
// Both conditions must be true
const value = "hello";
const isValid = and(hasValue(value))(isNonEmpty(value));
// true
```
### Example: Combining predicates [#example-combining-predicates]
```typescript
import { andFn } from '@accelint/core';
const isEven = (x: number) => x % 2 === 0;
const isPositive = (x: number) => x > 0;
const isEvenAndPositive = andFn(isEven)(isPositive);
isEvenAndPositive(4);
// true
isEvenAndPositive(-4);
// false
isEvenAndPositive(3);
// false
```
### Example: Partial application [#example-partial-application]
```typescript
import { and } from '@accelint/core';
// Create a reusable validator
const isEnabled = and(true);
isEnabled(someCondition);
// true if someCondition is truthy
```
> **Good to know:** Both `and` and `andFn` convert their operands to boolean values using `Boolean()`, so they work with any truthy/falsy values.
## Related [#related]
* [or](../or/index.md) - Logical disjunction (||)
* [not](../not/index.md) - Logical negation (!)
* [nand](../nand/index.md) - Logical NAND (!(a && b))
* [xor](../xor/index.md) - Logical exclusive OR
# equality (/docs/packages/core/logical/equality)
## Usage [#usage]
```typescript
import { equality, equalityFn } from '@accelint/core';
// Value-based equality
equality(4)(4);
// true
equality(4)(8);
// false
// Function-based equality
const getLength = (arr: unknown[]) => arr.length;
const getSum = (arr: number[]) => arr.reduce((a, b) => a + b, 0);
equalityFn(getLength)(getSum)([1, 2, 3]);
// false (3 !== 6)
equalityFn(getLength)(getSum)([1, 1, 1]);
// true (3 === 3)
```
## Reference [#reference]
### equality [#equality]
```typescript
function equality(a: unknown): (b: unknown) => boolean
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | --------- | -------------------------- |
| `a` | `unknown` | The first value to compare |
#### Returns [#returns]
Returns a curried function that accepts a second value and returns `true` if both values are strictly equal (`===`), `false` otherwise.
### equalityFn [#equalityfn]
```typescript
function equalityFn<T>(
a: (x: T) => unknown
): (b: (x: T) => unknown) => (c: T) => boolean
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | ------------------- | ------------------------------ |
| `a` | `(x: T) => unknown` | The first function to evaluate |
#### Returns [#returns-1]
Returns a curried function that accepts a second function, then accepts a value to pass to both functions, returning `true` if both function results are strictly equal, `false` otherwise.
#### Type Parameters [#type-parameters]
* `T` - The type of the input value passed to both functions
## Examples [#examples]
### Example: Creating equality predicates [#example-creating-equality-predicates]
```typescript
import { equality } from '@accelint/core';
const isZero = equality(0);
isZero(0);
// true
isZero(1);
// false
```
### Example: Comparing function results [#example-comparing-function-results]
```typescript
import { equalityFn } from '@accelint/core';
const getFirstChar = (s: string) => s[0];
const getLastChar = (s: string) => s[s.length - 1];
// Check if string is a palindrome (single character case)
const isPalindrome = equalityFn(getFirstChar)(getLastChar);
isPalindrome('a');
// true
isPalindrome('abc');
// false
```
### Example: Validation with modulo [#example-validation-with-modulo]
```typescript
import { equalityFn } from '@accelint/core';
const mod2 = (x: number) => x % 2;
const mod3 = (x: number) => x % 3;
// Check if remainders are equal
const hasSameRemainder = equalityFn(mod2)(mod3);
hasSameRemainder(6);
// true (0 === 0)
hasSameRemainder(5);
// false (1 !== 2)
```
### Example: Logical biconditional [#example-logical-biconditional]
```typescript
import { equality } from '@accelint/core';
// Logical XNOR (exclusive NOR)
// Returns true when both are true OR both are false
const xnor = (a: boolean, b: boolean) => equality(a)(b);
xnor(true, true);
// true
xnor(false, false);
// true
xnor(true, false);
// false
```
> **Good to know:** `equality` uses strict equality (`===`), so objects and arrays are compared by reference, not by value. For deep equality, use a dedicated deep equality function.
## Related [#related]
* [xor](../xor/index.md) - Logical exclusive OR (opposite of equality)
* [and](../and/index.md) - Logical conjunction (&&)
* [or](../or/index.md) - Logical disjunction (||)
* [not](../not/index.md) - Logical negation (!)
# nand (/docs/packages/core/logical/nand)
## Usage [#usage]
```typescript
import { nand, nandFn } from '@accelint/core';
// Value-based NAND
nand(true)(false);
// true
nand(true)(true);
// false
// Function-based NAND
const isPositive = (x: number) => x > 0;
const isLessThan10 = (x: number) => x < 10;
nandFn(isPositive)(isLessThan10)(5);
// false (both true, so NAND is false)
nandFn(isPositive)(isLessThan10)(15);
// true (second is false, so NAND is true)
```
## Reference [#reference]
### nand [#nand]
```typescript
function nand<A>(a: A): <B>(b: B) => boolean
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---- | -------------------------- |
| `a` | `A` | The first value to compare |
#### Returns [#returns]
Returns a curried function that accepts a second value and returns `true` if not both values are truthy, `false` if both are truthy.
#### Type Parameters [#type-parameters]
* `A` - The type of the first input value
* `B` - The type of the second input value
### nandFn [#nandfn]
```typescript
function nandFn<T, A>(
a: (x: T) => A
): <B>(b: (y: T) => B) => (c: T) => boolean
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | ------------- | ------------------------------ |
| `a` | `(x: T) => A` | The first function to evaluate |
#### Returns [#returns-1]
Returns a curried function that accepts a second function, then accepts a value to pass to both functions, returning `true` if not both function results are truthy, `false` if both are truthy.
#### Type Parameters [#type-parameters-1]
* `T` - The type of the input value passed to both functions
* `A` - The return type of the first function
* `B` - The return type of the second function
## Examples [#examples]
### Example: Validation constraints [#example-validation-constraints]
```typescript
import { nand } from '@accelint/core';
// User cannot have both admin AND guest roles simultaneously
const isAdmin = true;
const isGuest = false;
const rolesValid = nand(isAdmin)(isGuest);
// true (not both are true)
```
### Example: Exclusion logic with predicates [#example-exclusion-logic-with-predicates]
```typescript
import { nandFn } from '@accelint/core';
const isWeekend = (date: Date) => [0, 6].includes(date.getDay());
const isHoliday = (date: Date) => holidays.includes(date.toDateString());
// Business day logic: not (weekend AND holiday)
const canSchedule = nandFn(isWeekend)(isHoliday);
canSchedule(new Date('2024-07-04')); // Thursday, holiday
// true (only one condition is true)
```
### Example: NAND truth table [#example-nand-truth-table]
```typescript
import { nand } from '@accelint/core';
// NAND truth table (opposite of AND)
nand(false)(false); // true
nand(false)(true); // true
nand(true)(false); // true
nand(true)(true); // false
```
> **Good to know:** NAND is the logical inverse of AND. It's functionally complete—all other logical operations can be constructed from NAND alone. This implementation uses `not(and(a)(b))` internally.
## Related [#related]
* [and](../and/index.md) - Logical conjunction (&&)
* [nor](../nor/index.md) - Logical NOR (!(a || b))
* [not](../not/index.md) - Logical negation (!)
* [xor](../xor/index.md) - Logical exclusive OR
# nor (/docs/packages/core/logical/nor)
## Usage [#usage]
```typescript
import { nor, norFn } from '@accelint/core';
// Value-based NOR
nor(false)(false);
// true
nor(true)(false);
// false
// Function-based NOR
const isEmpty = (arr: unknown[]) => arr.length === 0;
const isNull = (arr: unknown[] | null) => arr === null;
norFn(isEmpty)(isNull)([1, 2, 3]);
// false (first is false, second is false, so NOR is false)
norFn(isEmpty)(isNull)([]);
// false (first is true, so NOR is false)
```
## Reference [#reference]
### nor [#nor]
```typescript
function nor<A>(a: A): <B>(b: B) => boolean
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---- | -------------------------- |
| `a` | `A` | The first value to compare |
#### Returns [#returns]
Returns a curried function that accepts a second value and returns `true` if neither value is truthy, `false` if either is truthy.
#### Type Parameters [#type-parameters]
* `A` - The type of the first input value
* `B` - The type of the second input value
### norFn [#norfn]
```typescript
function norFn<T, A>(
a: (x: T) => A
): <B>(b: (y: T) => B) => (c: T) => boolean
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | ------------- | ------------------------------ |
| `a` | `(x: T) => A` | The first function to evaluate |
#### Returns [#returns-1]
Returns a curried function that accepts a second function, then accepts a value to pass to both functions, returning `true` if neither function result is truthy, `false` if either is truthy.
#### Type Parameters [#type-parameters-1]
* `T` - The type of the input value passed to both functions
* `A` - The return type of the first function
* `B` - The return type of the second function
## Examples [#examples]
### Example: Absence validation [#example-absence-validation]
```typescript
import { nor } from '@accelint/core';
const hasEmail = false;
const hasPhone = false;
// User has neither contact method
const noContactInfo = nor(hasEmail)(hasPhone);
// true
```
### Example: Checking for empty states [#example-checking-for-empty-states]
```typescript
import { norFn } from '@accelint/core';
const hasItems = (cart: Cart) => cart.items.length > 0;
const hasCoupon = (cart: Cart) => Boolean(cart.coupon);
// Cart is completely empty (no items and no coupon)
const isEmptyCart = norFn(hasItems)(hasCoupon);
isEmptyCart({ items: [], coupon: null });
// true
isEmptyCart({ items: [], coupon: 'SAVE10' });
// false (has coupon)
```
### Example: NOR truth table [#example-nor-truth-table]
```typescript
import { nor } from '@accelint/core';
// NOR truth table (opposite of OR)
nor(false)(false); // true
nor(false)(true); // false
nor(true)(false); // false
nor(true)(true); // false
```
> **Good to know:** NOR is the logical inverse of OR. It's functionally complete—all other logical operations can be constructed from NOR alone. This implementation uses `not(or(a)(b))` internally.
## Related [#related]
* [or](../or/index.md) - Logical disjunction (||)
* [nand](../nand/index.md) - Logical NAND (!(a && b))
* [not](../not/index.md) - Logical negation (!)
* [and](../and/index.md) - Logical conjunction (&&)
# not (/docs/packages/core/logical/not)
## Usage [#usage]
```typescript
import { not, notFn } from '@accelint/core';
// Value negation
not(true);
// false
not(0);
// true
// Function result negation
const isEven = (x: number) => x % 2 === 0;
const isOdd = notFn(isEven);
isOdd(4);
// false
isOdd(5);
// true
```
## Reference [#reference]
### not [#not]
```typescript
function not<T>(x: T): boolean
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---- | ------------------- |
| `x` | `T` | The value to negate |
#### Returns [#returns]
Returns the negated boolean value of the input.
#### Type Parameters [#type-parameters]
* `T` - The type of the input value
### notFn [#notfn]
```typescript
function notFn<T>(a: (x: T) => unknown): (b: T) => boolean
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | ------------------- | ----------------------------------- |
| `a` | `(x: T) => unknown` | The function whose result to negate |
#### Returns [#returns-1]
Returns a function that accepts a value, passes it to the given function, and returns the negated boolean result.
#### Type Parameters [#type-parameters-1]
* `T` - The type of the input value passed to the function
## Examples [#examples]
### Example: Creating inverse predicates [#example-creating-inverse-predicates]
```typescript
import { notFn } from '@accelint/core';
const isEmpty = (arr: unknown[]) => arr.length === 0;
const hasItems = notFn(isEmpty);
hasItems([1, 2, 3]);
// true
hasItems([]);
// false
```
### Example: Filtering with negation [#example-filtering-with-negation]
```typescript
import { notFn, filter } from '@accelint/core';
const isNull = (x: unknown) => x === null;
const notNull = notFn(isNull);
filter(notNull)([1, null, 2, null, 3]);
// [1, 2, 3]
```
### Example: Boolean conversion [#example-boolean-conversion]
```typescript
import { not } from '@accelint/core';
// All falsy values become true
not(0); // true
not(''); // true
not(null); // true
not(undefined);// true
not(false); // true
// All truthy values become false
not(1); // false
not('hello'); // false
not({}); // false
not([]); // false
```
> **Good to know:** `not` and `notFn` use JavaScript's standard truthiness evaluation. The value is first converted to a boolean before negation.
## Related [#related]
* [and](../and/index.md) - Logical conjunction (&&)
* [or](../or/index.md) - Logical disjunction (||)
* [nand](../nand/index.md) - Logical NAND (!(a && b))
* [nor](../nor/index.md) - Logical NOR (!(a || b))
# nullishOr (/docs/packages/core/logical/nullish-or)
## Usage [#usage]
```typescript
import { nullishOr, nullishOrFn, swappedNullishOr, swappedNullishOrFn } from '@accelint/core';
// Value-based nullish coalescing
nullishOr(null)(42);
// 42
nullishOr(0)(42);
// 0 (0 is not nullish)
// Function-based nullish coalescing
const getFromCache = (key: string): number | null => cache.get(key);
const computeValue = (key: string): number => expensiveCalculation(key);
const getValue = nullishOrFn(getFromCache)(computeValue);
getValue('user-123');
// Returns cached value, or computes if cache is null/undefined
```
## Reference [#reference]
### nullishOr [#nullishor]
```typescript
function nullishOr<A>(a: A): <B>(b: B) => A | B
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---- | -------------------------- |
| `a` | `A` | The possibly nullish value |
#### Returns [#returns]
Returns a curried function that accepts a fallback value and returns the first value if not nullish, otherwise the fallback.
#### Type Parameters [#type-parameters]
* `A` - The type of the first input value
* `B` - The type of the second input value
### nullishOrFn [#nullishorfn]
```typescript
function nullishOrFn<T, A>(
a: (x: T) => A
): <B>(b: (y: T) => B) => (c: T) => A | B
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | ------------- | ------------------------------------ |
| `a` | `(x: T) => A` | The function that may return nullish |
#### Returns [#returns-1]
Returns a curried function that accepts a fallback function, then accepts a value to pass to both functions, returning the first function result if not nullish, otherwise the second.
#### Type Parameters [#type-parameters-1]
* `T` - The type of the input value passed to both functions
* `A` - The return type of the first function
* `B` - The return type of the second function
### swappedNullishOr [#swappednullishor]
```typescript
function swappedNullishOr<A>(a: A): <B>(b: B) => A | B
```
Evaluates `b ?? a` instead of `a ?? b`.
### swappedNullishOrFn [#swappednullishorfn]
```typescript
function swappedNullishOrFn<T, A>(
a: (x: T) => A
): <B>(b: (y: T) => B) => (c: T) => A | B
```
Evaluates `b(x) ?? a(x)` instead of `a(x) ?? b(x)`.
## Examples [#examples]
### Example: Default values for optional fields [#example-default-values-for-optional-fields]
```typescript
import { nullishOr } from '@accelint/core';
interface User {
name: string;
age?: number;
}
const getAge = (user: User) =>
nullishOr(user.age)(18);
getAge({ name: 'Alice', age: 25 });
// 25
getAge({ name: 'Bob' });
// 18
getAge({ name: 'Charlie', age: 0 });
// 0 (not nullish, so 0 is returned)
```
### Example: Fallback computation [#example-fallback-computation]
```typescript
import { nullishOrFn } from '@accelint/core';
const getUserPreference = (user: User): Theme | null =>
user.preferences?.theme ?? null;
const getSystemTheme = (): Theme =>
window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
const getTheme = nullishOrFn(getUserPreference)(getSystemTheme);
getTheme(user);
// User theme if set, otherwise system theme
```
### Example: Difference from logical OR [#example-difference-from-logical-or]
```typescript
import { nullishOr, or } from '@accelint/core';
// nullishOr preserves falsy values (except null/undefined)
nullishOr(0)('fallback');
// 0
nullishOr(false)('fallback');
// false
nullishOr('')('fallback');
// ''
// or converts to boolean
or(0)('fallback');
// 'fallback'
```
> **Good to know:** Unlike `or`, `nullishOr` only treats `null` and `undefined` as absent values. Falsy values like `0`, `false`, and `''` are preserved. This matches JavaScript's `??` operator.
## Related [#related]
* [or](../or/index.md) - Logical disjunction (||) with truthiness
* [and](../and/index.md) - Logical conjunction (&&)
* [not](../not/index.md) - Logical negation (!)
# or (/docs/packages/core/logical/or)
## Usage [#usage]
```typescript
import { or, orFn, swappedOr, swappedOrFn } from '@accelint/core';
// Value-based disjunction
or(true)(0);
// true
or(false)(false);
// false
// Function-based disjunction
const isEmpty = (s: string) => s.length === 0;
const isWhitespace = (s: string) => s.trim().length === 0;
orFn(isEmpty)(isWhitespace)(" ");
// true
// Swapped variants evaluate right operand first
swappedOr(0)(true);
// true
```
## Reference [#reference]
### or [#or]
```typescript
function or<A>(a: A): <B>(b: B) => boolean
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---- | --------------------------- |
| `a` | `A` | The first value to evaluate |
#### Returns [#returns]
Returns a curried function that accepts a second value and returns `true` if either value is truthy, `false` otherwise.
### orFn [#orfn]
```typescript
function orFn<T, A>(
a: (x: T) => A
): <B>(b: (y: T) => B) => (c: T) => boolean
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | ------------- | ------------------------------ |
| `a` | `(x: T) => A` | The first function to evaluate |
#### Returns [#returns-1]
Returns a curried function that accepts a second function, then accepts a value to pass to both functions, returning `true` if either function result is truthy, `false` otherwise.
### swappedOr [#swappedor]
```typescript
function swappedOr<A>(a: A): <B>(b: B) => boolean
```
Evaluates `b || a` instead of `a || b`.
#### Parameters [#parameters-2]
| Parameter | Type | Description |
| --------- | ---- | ------------------ |
| `a` | `A` | The fallback value |
#### Returns [#returns-2]
Returns a curried function that accepts a value and returns `true` if that value OR the first value is truthy.
### swappedOrFn [#swappedorfn]
```typescript
function swappedOrFn<T, A>(
a: (x: T) => A
): <B>(b: (y: T) => B) => (c: T) => boolean
```
Evaluates `b(x) || a(x)` instead of `a(x) || b(x)`.
## Examples [#examples]
### Example: Default values [#example-default-values]
```typescript
import { or } from '@accelint/core';
const getUserName = (user: { name?: string }) =>
or(user.name)("Anonymous");
// Returns user.name if truthy, otherwise "Anonymous"
```
### Example: Combining validation rules [#example-combining-validation-rules]
```typescript
import { orFn } from '@accelint/core';
const isAdmin = (user: User) => user.role === 'admin';
const isModerator = (user: User) => user.role === 'moderator';
const canModerate = orFn(isAdmin)(isModerator);
canModerate({ role: 'admin' });
// true
canModerate({ role: 'user' });
// false
```
### Example: Swapped evaluation order [#example-swapped-evaluation-order]
```typescript
import { swappedOr } from '@accelint/core';
// Useful when you want to check the second argument first
const hasValue = swappedOr("default");
hasValue(null);
// "default"
hasValue("custom");
// "custom"
```
> **Good to know:** All variants convert their operands to boolean values using `Boolean()`, so they work with any truthy/falsy values. The swapped variants are useful when the evaluation order matters semantically.
## Related [#related]
* [and](../and/index.md) - Logical conjunction (&&)
* [not](../not/index.md) - Logical negation (!)
* [nor](../nor/index.md) - Logical NOR (!(a || b))
* [xor](../xor/index.md) - Logical exclusive OR
* [nullish-or](../nullish-or/index.md) - Nullish coalescing (??)
# xor (/docs/packages/core/logical/xor)
Logical exclusive OR (XOR) for values and function results. Returns `true` if exactly one operand is truthy.
## Usage [#usage]
```typescript
import { xor, xorFn } from '@accelint/core';
// Value-based XOR
xor(true)(false);
// true
xor(true)(true);
// false
xor(false)(false);
// false
// Function-based XOR
const isEven = (x: number) => x % 2 === 0;
const isDivisibleBy3 = (x: number) => x % 3 === 0;
xorFn(isEven)(isDivisibleBy3)(6);
// false (both true)
xorFn(isEven)(isDivisibleBy3)(4);
// true (only first is true)
```
## Reference [#reference]
### xor [#xor]
```typescript
function xor(a: unknown): (b: unknown) => boolean
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | --------- | -------------------------- |
| `a` | `unknown` | The first value to compare |
#### Returns [#returns]
Returns a curried function that accepts a second value and returns `true` if exactly one value is truthy, `false` otherwise.
### xorFn [#xorfn]
```typescript
function xorFn<T>(
a: (x: T) => unknown
): (b: (x: T) => unknown) => (c: T) => boolean
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | ------------------- | ------------------------------ |
| `a` | `(x: T) => unknown` | The first function to evaluate |
#### Returns [#returns-1]
Returns a curried function that accepts a second function, then accepts a value to pass to both functions, returning `true` if exactly one function result is truthy, `false` otherwise.
#### Type Parameters [#type-parameters]
* `T` - The type of the input value passed to both functions
## Examples [#examples]
### Example: Toggle logic [#example-toggle-logic]
```typescript
import { xor } from '@accelint/core';
const hasPermissionA = true;
const hasPermissionB = false;
// User must have exactly one permission (not both, not neither)
const isValid = xor(hasPermissionA)(hasPermissionB);
// true
```
### Example: Validation with mutually exclusive conditions [#example-validation-with-mutually-exclusive-conditions]
```typescript
import { xorFn } from '@accelint/core';
const hasEmail = (user: User) => Boolean(user.email);
const hasPhone = (user: User) => Boolean(user.phone);
// User must have either email OR phone, but not both
const hasValidContact = xorFn(hasEmail)(hasPhone);
hasValidContact({ email: 'test@example.com', phone: null });
// true
hasValidContact({ email: 'test@example.com', phone: '555-0100' });
// false (has both)
hasValidContact({ email: null, phone: null });
// false (has neither)
```
### Example: Bitwise XOR truth table [#example-bitwise-xor-truth-table]
```typescript
import { xor } from '@accelint/core';
// XOR truth table
xor(false)(false); // false
xor(false)(true); // true
xor(true)(false); // true
xor(true)(true); // false
```
> **Good to know:** XOR converts operands to boolean values before comparison. It returns `true` only when the operands have different truthiness—one is truthy and the other is falsy.
## Related [#related]
* [and](../and/index.md) - Logical conjunction (&&)
* [or](../or/index.md) - Logical disjunction (||)
* [not](../not/index.md) - Logical negation (!)
* [equality](../equality/index.md) - Logical equality (XNOR)
# associate (/docs/packages/core/object/associate)
Immutably set object properties, returning a new copy with the updated value. Provides both shallow (`associate`) and deep (`associateDeep`) cloning variants.
## Usage [#usage]
```typescript
import { associate, associateDeep, assoc, assocDeep } from '@accelint/core';
const person = {
name: 'Alice',
address: {
city: 'New York',
street: '123 Main St'
}
};
// Shallow copy
const updated = associate(person)('name')('Bob');
// { name: 'Bob', address: { city: 'New York', street: '123 Main St' } }
// Note: address reference is shared
// Deep copy
const deepUpdated = associateDeep(person)('address')({
city: 'Austin',
street: '987 Sample St'
});
// { name: 'Alice', address: { city: 'Austin', street: '987 Sample St' } }
// Note: address is a new object
```
## Reference [#reference]
### associate [#associate]
```typescript
function associate<T extends object>(
obj: T
): <K extends keyof T>(prop: K) => (val: T[K]) => T
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ------------------ | -------------------- |
| `obj` | `T extends object` | The object to update |
#### Returns [#returns]
Returns a curried function that accepts a property name, then accepts a value, returning a new shallow copy of the object with the updated property.
#### Type Parameters [#type-parameters]
* `T` - The type of the input object
* `K` - The property key type
#### Aliases [#aliases]
* `assoc` - Shorter alias for `associate`
### associateDeep [#associatedeep]
```typescript
function associateDeep<T extends object>(
obj: T
): <K extends keyof T>(prop: K) => (val: T[K]) => T
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | ------------------ | -------------------- |
| `obj` | `T extends object` | The object to update |
#### Returns [#returns-1]
Returns a curried function that accepts a property name, then accepts a value, returning a new deep copy of the object with the updated property.
Uses `structuredClone()` internally for deep cloning.
#### Aliases [#aliases-1]
* `assocDeep` - Shorter alias for `associateDeep`
## Examples [#examples]
### Example: Updating nested state [#example-updating-nested-state]
```typescript
import { associate } from '@accelint/core';
const state = {
user: { id: 1, name: 'Alice' },
settings: { theme: 'dark' }
};
// Create updater for user property
const setUser = associate(state)('user');
const newState = setUser({ id: 1, name: 'Bob' });
// { user: { id: 1, name: 'Bob' }, settings: { theme: 'dark' } }
```
### Example: Partial application for reusable setters [#example-partial-application-for-reusable-setters]
```typescript
import { associateDeep } from '@accelint/core';
interface Config {
apiKey: string;
endpoint: string;
timeout: number;
}
const config: Config = {
apiKey: 'abc123',
endpoint: 'https://api.example.com',
timeout: 5000
};
// Create reusable setter
const updateTimeout = associateDeep(config)('timeout');
updateTimeout(10000);
// { apiKey: 'abc123', endpoint: 'https://api.example.com', timeout: 10000 }
```
### Example: Shallow vs deep cloning [#example-shallow-vs-deep-cloning]
```typescript
import { associate, associateDeep } from '@accelint/core';
const original = {
data: { values: [1, 2, 3] },
meta: { count: 3 }
};
// Shallow: nested objects are shared
const shallow = associate(original)('meta')({ count: 5 });
original.data === shallow.data; // true (same reference)
// Deep: nested objects are cloned
const deep = associateDeep(original)('meta')({ count: 5 });
original.data === deep.data; // false (different reference)
```
### Example: Composing with pipe [#example-composing-with-pipe]
```typescript
import { pipe, associateDeep } from '@accelint/core';
interface User {
name: string;
email: string;
active: boolean;
}
const updateUser = pipe(
associateDeep<User>({ name: '', email: '', active: false })('name'),
(user) => associateDeep(user)('active')(true)
);
updateUser('Alice');
// { name: 'Alice', email: '', active: true }
```
> **Good to know:** `associate` creates a shallow copy using spread (`{ ...obj }`), while `associateDeep` uses `structuredClone()` for full deep cloning. Use shallow for performance when nested objects don't need independent copies. Use deep when you need complete immutability.
## Related [#related]
* [property](../property/index.md) - Get object property values
* [lens](../lens/index.md) - Functional lens for getting and setting nested values
# lens (/docs/packages/core/object/lens)
## Usage [#usage]
```typescript
import { lens, get, set, lensProp, composeLens } from '@accelint/core';
interface Person {
name: string;
address: {
city: string;
street: string;
};
}
const person: Person = {
name: 'Alice',
address: {
city: 'New York',
street: '123 Main St'
}
};
// Create a simple lens
const nameLens = lensProp<Person>()('name');
get(nameLens)(person);
// 'Alice'
const updated = set(nameLens)('Bob')(person);
// { name: 'Bob', address: { ... } }
// Compose lenses for nested access
const addressLens = lensProp<Person>()('address');
const cityLens = lensProp<Address>()('city');
const personCityLens = composeLens(addressLens, cityLens);
get(personCityLens)(person);
// 'New York'
```
## Reference [#reference]
### lens [#lens]
```typescript
function lens<T, V>(
getter: (source: T) => V,
setter: (source: T) => (value: V) => T
): Lens<T, V>
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------------------------------- | ------------------------------------------------------ |
| `getter` | `(source: T) => V` | Function to extract the focused value |
| `setter` | `(source: T) => (value: V) => T` | Curried function to update the focused value immutably |
#### Returns [#returns]
Returns a `Lens<T, V>` object with `get` and `set` functions.
#### Type Parameters [#type-parameters]
* `T` - The type of the object being inspected
* `V` - The type of the property value
### Lens Type [#lens-type]
```typescript
type Lens<T, V> = {
get: (source: T) => V;
set: (source: T) => (value: V) => T;
};
```
### composeLens [#composelens]
```typescript
function composeLens<A, B, C>(
ab: Lens<A, B>,
bc: Lens<B, C>
): Lens<A, C>
```
Compose two lenses together. Given a lens `A ⭢ B` and a lens `B ⭢ C`, produces a lens `A ⭢ C`.
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | ------------ | -------------------- |
| `ab` | `Lens<A, B>` | The lens from A to B |
| `bc` | `Lens<B, C>` | The lens from B to C |
#### Returns [#returns-1]
Returns a composed lens from A to C.
### get [#get]
```typescript
function get<T, V>(lensVal: Lens<T, V>): (obj: T) => V
```
Wrapper function to access the `get` of a lens with the given object.
### set [#set]
```typescript
function set<T, V>(lensVal: Lens<T, V>): (value: V) => (obj: T) => T
```
Wrapper function to access the `set` of a lens with the given object.
### lensProp [#lensprop]
```typescript
function lensProp<T extends object>(): <K extends keyof T>(prop: K) => Lens<T, T[K]>
```
Short-hand to create a simple get/set lens for a property.
### lensOptionalProp [#lensoptionalprop]
```typescript
function lensOptionalProp<T extends object>(): <K extends keyof T>(prop: K) => Lens<T, T[K] | undefined>
```
Short-hand to create an optional get/set lens for a property.
## Examples [#examples]
### Example: Basic lens creation [#example-basic-lens-creation]
```typescript
import { lens, property, associateDeep } from '@accelint/core';
interface User {
id: number;
email: string;
}
const emailLens = lens(
(user: User) => property(user)('email'),
(user) => (email) => associateDeep(user)('email')(email)
);
const user = { id: 1, email: 'old@example.com' };
emailLens.get(user);
// 'old@example.com'
emailLens.set(user)('new@example.com');
// { id: 1, email: 'new@example.com' }
```
### Example: Composing nested lenses [#example-composing-nested-lenses]
```typescript
import { lensProp, composeLens, get, set } from '@accelint/core';
interface Address {
city: string;
zipCode: string;
}
interface Person {
name: string;
address: Address;
}
const addressLens = lensProp<Person>()('address');
const cityLens = lensProp<Address>()('city');
// Compose to access nested city
const personCityLens = composeLens(addressLens, cityLens);
const person: Person = {
name: 'Alice',
address: { city: 'New York', zipCode: '10001' }
};
get(personCityLens)(person);
// 'New York'
set(personCityLens)('San Francisco')(person);
// { name: 'Alice', address: { city: 'San Francisco', zipCode: '10001' } }
```
### Example: Lens laws (SetGet, GetSet, SetSet) [#example-lens-laws-setget-getset-setset]
```typescript
import { lensProp } from '@accelint/core';
interface User {
name: string;
}
const nameLens = lensProp<User>()('name');
const user = { name: 'Alice' };
// Law 1: SetGet - Getting after setting returns the set value
nameLens.get(nameLens.set(user)('Bob'));
// 'Bob'
// Law 2: GetSet - Setting with the current value doesn't change the object
nameLens.set(user)(nameLens.get(user));
// { name: 'Alice' } (structurally equal to user)
// Law 3: SetSet - Setting twice is same as setting once with the final value
nameLens.set(nameLens.set(user)('Bob'))('Charlie');
// Equivalent to:
nameLens.set(user)('Charlie');
```
### Example: Multiple lens composition [#example-multiple-lens-composition]
```typescript
import { lensProp, composeLens, get } from '@accelint/core';
interface City { name: string; }
interface Address { city: City; }
interface Person { address: Address; }
interface User { profile: Person; }
const user: User = {
profile: {
address: {
city: { name: 'Boston' }
}
}
};
const profileLens = lensProp<User>()('profile');
const addressLens = lensProp<Person>()('address');
const cityLens = lensProp<Address>()('city');
const cityNameLens = lensProp<City>()('name');
// Compose all the way down
const userCityNameLens = composeLens(
composeLens(
composeLens(profileLens, addressLens),
cityLens
),
cityNameLens
);
get(userCityNameLens)(user);
// 'Boston'
```
### Example: Optional property lenses [#example-optional-property-lenses]
```typescript
import { lensOptionalProp, get } from '@accelint/core';
interface User {
name: string;
email?: string;
}
const emailLens = lensOptionalProp<User>()('email');
const withEmail = { name: 'Alice', email: 'alice@example.com' };
const withoutEmail = { name: 'Bob' };
get(emailLens)(withEmail);
// 'alice@example.com'
get(emailLens)(withoutEmail);
// undefined
```
> **Good to know:** Lenses satisfy three laws: SetGet (get after set returns the set value), GetSet (set with current value doesn't change object), and SetSet (setting twice is same as setting once). All lens operations use deep cloning via `associateDeep`, ensuring immutability.
## Related [#related]
* [property](../property/index.md) - Get object property values
* [associate](../associate/index.md) - Immutably set object properties
* [compose](../../composition/compose/index.md) - Function composition
# property (/docs/packages/core/object/property)
## Usage [#usage]
```typescript
import { property, optionalProperty, prop, optionalProp } from '@accelint/core';
const person = {
name: 'Alice',
address: {
city: 'New York'
}
};
// Required property access
property(person)('name');
// 'Alice'
// Optional property access
optionalProperty(person)('address');
// { city: 'New York' }
optionalProperty(undefined)('address');
// undefined
// Array index support
const arr = [1, 2, 3];
property(arr)(0);
// 1
```
## Reference [#reference]
### property [#property]
```typescript
function property<T extends object>(
obj: T
): <K extends keyof T>(prop: K) => T[K]
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ------------------ | -------------------------------- |
| `obj` | `T extends object` | The object to get the value from |
#### Returns [#returns]
Returns a curried function that accepts a property name and returns the value of that property.
#### Type Parameters [#type-parameters]
* `T` - The type of the input object
* `K` - The property key type
#### Aliases [#aliases]
* `prop` - Shorter alias for `property`
### optionalProperty [#optionalproperty]
```typescript
function optionalProperty<T extends object>(
obj?: T
): <K extends keyof T>(prop: K) => T[K] | undefined
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | ---------------- | ----------------------------- |
| `obj` | `T \| undefined` | The possibly undefined object |
#### Returns [#returns-1]
Returns a curried function that accepts a property name and returns the value of that property, or `undefined` if the object is nullish.
#### Aliases [#aliases-1]
* `optionalProp` - Shorter alias for `optionalProperty`
## Examples [#examples]
### Example: Extracting nested values [#example-extracting-nested-values]
```typescript
import { property } from '@accelint/core';
interface User {
profile: {
email: string;
phone?: string;
};
}
const user: User = {
profile: {
email: 'alice@example.com'
}
};
const getProfile = property(user);
getProfile('profile');
// { email: 'alice@example.com' }
```
### Example: Array index access [#example-array-index-access]
```typescript
import { property } from '@accelint/core';
const colors = ['red', 'green', 'blue'];
const getColor = property(colors);
getColor(0); // 'red'
getColor(1); // 'green'
getColor(2); // 'blue'
// Uses Array.prototype.at() internally, so negative indices work
property(colors)(-1); // 'blue'
```
### Example: Safe optional access [#example-safe-optional-access]
```typescript
import { optionalProperty } from '@accelint/core';
interface Config {
apiKey?: string;
endpoint: string;
}
const config: Config | undefined = loadConfig();
// Safe access without runtime errors
const apiKey = optionalProperty(config)('apiKey');
// string | undefined
```
### Example: Composing with map [#example-composing-with-map]
```typescript
import { property, map } from '@accelint/core';
interface Product {
name: string;
price: number;
}
const products: Product[] = [
{ name: 'Widget', price: 9.99 },
{ name: 'Gadget', price: 19.99 }
];
// Extract all names
const names = map((p: Product) => property(p)('name'))(products);
// ['Widget', 'Gadget']
```
### Example: Creating property getters [#example-creating-property-getters]
```typescript
import { property } from '@accelint/core';
interface User {
id: number;
name: string;
email: string;
}
// Create reusable getters
const getId = <T extends { id: number }>(obj: T) => property(obj)('id');
const getName = <T extends { name: string }>(obj: T) => property(obj)('name');
const user: User = { id: 1, name: 'Alice', email: 'alice@example.com' };
getId(user); // 1
getName(user); // 'Alice'
```
> **Good to know:** When used with arrays, `property` detects numeric indices and uses `Array.prototype.at()` for access, which supports negative indices. For objects, it uses standard bracket notation.
## Related [#related]
* [associate](../associate/index.md) - Immutably set object properties
* [lens](../lens/index.md) - Functional lens for getting and setting nested values
* [optionalProperty](../property/index.md) - Optional property access
# getSafeEnumValues (/docs/packages/core/safe-enum/get-safe-enum-values)
## Usage [#usage]
```typescript
import { getSafeEnumValues } from '@accelint/core/safe-enum/get-safe-enum-values';
const Status = Object.freeze({
Active: 'active',
Inactive: 'inactive',
Pending: 'pending',
} as const);
const values = getSafeEnumValues(Status);
// ['active', 'inactive', 'pending']
```
## Reference [#reference]
```typescript
function getSafeEnumValues<TSafeEnum extends ValidEnumStructures>(
safeEnum: TSafeEnum
): readonly [SafeEnum<TSafeEnum>, ...SafeEnum<TSafeEnum>[]]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ---------- | --------------------- | --------------------------------------------- |
| `safeEnum` | `ValidEnumStructures` | The frozen enum object to extract values from |
### Returns [#returns]
Returns a frozen array containing all enum values with proper non-empty array typing.
### Type Parameters [#type-parameters]
* `TSafeEnum` - The enum object type extending ValidEnumStructures
* Return type is `readonly [Value, ...Value[]]` - a non-empty readonly tuple
## Examples [#examples]
### Example: Validating user input [#example-validating-user-input]
```typescript
import { getSafeEnumValues } from '@accelint/core/safe-enum/get-safe-enum-values';
import type { SafeEnum } from '@accelint/core/safe-enum/safe-enum';
const Role = Object.freeze({
Admin: 'admin',
User: 'user',
Guest: 'guest',
} as const);
type Role = SafeEnum<typeof Role>;
const validRoles = getSafeEnumValues(Role);
function isValidRole(input: string): input is Role {
return validRoles.includes(input as Role);
}
isValidRole('admin'); // true
isValidRole('invalid'); // false
```
### Example: Building select options [#example-building-select-options]
```typescript
import { getSafeEnumValues } from '@accelint/core/safe-enum/get-safe-enum-values';
const Priority = Object.freeze({
Low: 'low',
Medium: 'medium',
High: 'high',
Urgent: 'urgent',
} as const);
const priorities = getSafeEnumValues(Priority);
const options = priorities.map(value => ({
value,
label: value.charAt(0).toUpperCase() + value.slice(1)
}));
// [
// { value: 'low', label: 'Low' },
// { value: 'medium', label: 'Medium' },
// ...
// ]
```
### Example: Iterating over enum values [#example-iterating-over-enum-values]
```typescript
import { getSafeEnumValues } from '@accelint/core/safe-enum/get-safe-enum-values';
const Status = Object.freeze({
Draft: 'draft',
Published: 'published',
Archived: 'archived',
} as const);
const statuses = getSafeEnumValues(Status);
for (const status of statuses) {
console.log(`Processing status: ${status}`);
}
```
> **Good to know:** The returned array is frozen (immutable) to prevent accidental modification. Type inference ensures the array is typed as non-empty. Use this function when you need runtime access to enum values, such as for validation, iteration, or building UI elements.
## Related [#related]
* [SafeEnum](../safe-enum/index.md) - Type-safe enum pattern
* [isLiteralEnum](../is-literal-enum/index.md) - Type guard for literal enums
# SafeEnum (/docs/packages/core/safe-enum/safe-enum)
## Usage [#usage]
```typescript
import type { SafeEnum } from '@accelint/core/safe-enum/safe-enum';
// Define the value object
export const Status = Object.freeze({
Active: 'active',
Inactive: 'inactive',
Pending: 'pending',
} as const);
// Extract the type
export type Status = SafeEnum<typeof Status>;
// Use in code
const currentStatus: Status = Status.Active; // 'active'
```
## Reference [#reference]
```typescript
type SafeEnum<TObject extends ValidEnumStructures> =
IsLiteralEnum<TObject> extends true
? TObject[keyof TObject]
: '[SafeEnum Error] Enum is not `as const` or has mixed values';
```
### Type Parameters [#type-parameters]
| Parameter | Description |
| --------- | ------------------------------------------------------------------ |
| `TObject` | The frozen object created with `as const` representing enum values |
### Returns [#returns]
Returns a union type of all the enum values, or a helpful error message if the enum is improperly structured.
## Examples [#examples]
### Example: String enum [#example-string-enum]
```typescript
import type { SafeEnum } from '@accelint/core/safe-enum/safe-enum';
export const LogLevel = Object.freeze({
Debug: 'debug',
Info: 'info',
Warn: 'warn',
Error: 'error',
} as const);
export type LogLevel = SafeEnum<typeof LogLevel>;
function log(level: LogLevel, message: string) {
console.log(`[${level}] ${message}`);
}
log(LogLevel.Info, 'Application started'); // ✓ Valid
log('info', 'Direct string'); // ✓ Valid - structural typing
log('invalid', 'Bad level'); // ✗ Type error
```
### Example: Number enum [#example-number-enum]
```typescript
import type { SafeEnum } from '@accelint/core/safe-enum/safe-enum';
export const HttpStatus = Object.freeze({
Ok: 200,
NotFound: 404,
ServerError: 500,
} as const);
export type HttpStatus = SafeEnum<typeof HttpStatus>;
function handleResponse(status: HttpStatus) {
if (status === HttpStatus.Ok) {
return 'Success';
}
if (status === 404) { // ✓ Direct number comparison works
return 'Not found';
}
}
```
### Example: Enum values extraction [#example-enum-values-extraction]
```typescript
import type { SafeEnum } from '@accelint/core/safe-enum/safe-enum';
import { getSafeEnumValues } from '@accelint/core/safe-enum/get-safe-enum-values';
export const Color = Object.freeze({
Red: 'red',
Green: 'green',
Blue: 'blue',
} as const);
export type Color = SafeEnum<typeof Color>;
// Get all values as array
const colors = getSafeEnumValues(Color);
// ['red', 'green', 'blue']
// Validate user input
function isValidColor(input: string): input is Color {
return colors.includes(input as Color);
}
```
### Example: Compile-time error detection [#example-compile-time-error-detection]
```typescript
import type { SafeEnum } from '@accelint/core/safe-enum/safe-enum';
// ✗ Missing `as const` - compile error
const BadEnum1 = Object.freeze({
A: 'a',
B: 'b',
});
type BadEnum1 = SafeEnum<typeof BadEnum1>;
// Type: '[SafeEnum Error] Enum is not `as const` or has mixed values'
// ✗ Mixed value types - compile error
const BadEnum2 = Object.freeze({
A: 'a',
B: 123,
} as const);
type BadEnum2 = SafeEnum<typeof BadEnum2>;
// Type: '[SafeEnum Error] Enum is not `as const` or has mixed values'
// ✓ Properly structured
const GoodEnum = Object.freeze({
A: 'a',
B: 'b',
} as const);
type GoodEnum = SafeEnum<typeof GoodEnum>;
// Type: 'a' | 'b'
```
> **Good to know:** SafeEnum solves TypeScript enum problems: reverse mappings pollution, numeric enum coercion bugs, and incompatibility with structural typing. The `Object.freeze()` is recommended but not required—`as const` is sufficient for type safety. Values can be used directly (e.g., `'active'`) thanks to structural typing.
## Why SafeEnum over TypeScript Enums? [#why-safeenum-over-typescript-enums]
**Problems with TypeScript enums:**
1. **Reverse mappings**: Numeric enums create unwanted reverse key-value pairs
2. **Type coercion**: Numbers are silently coerced, causing runtime bugs
3. **Structural incompatibility**: Enums use nominal typing, breaking interop with plain values
4. **Bundle size**: Generates extra runtime code
**SafeEnum advantages:**
* Pure TypeScript types, zero runtime overhead
* Structural typing—works with plain strings/numbers
* No reverse mapping pollution
* No silent coercion
* Tree-shakeable
* Compile-time validation with helpful error messages
## Related [#related]
* [getSafeEnumValues](../get-safe-enum-values/index.md) - Extract enum values as array
* [isLiteralEnum](../is-literal-enum/index.md) - Type guard for literal enums
* [ValidEnumStructures](../valid-enum-structures/index.md) - Base constraint for valid enums
# lookup (/docs/packages/core/utility/lookup)
Create a lookup function from a record object with optional default fallback for missing keys.
## Usage [#usage]
```typescript
import { lookup } from '@accelint/core';
const colorTable = {
red: '#FF0000',
green: '#00FF00',
blue: '#0000FF'
};
// Basic lookup
const getColor = lookup(colorTable);
getColor('red');
// '#FF0000'
// With default fallback
const getColorSafe = lookup(colorTable, (x) => x ?? '#000000');
getColorSafe('purple');
// '#000000'
```
## Reference [#reference]
```typescript
function lookup<A extends Record<string | number | symbol, unknown>, B extends (...args: any[]) => any>(
obj: A,
def?: B
): <C extends keyof A>(prop: string | number | symbol) => A[C]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ----------------------- | -------------------------------------------------------------------------- |
| `obj` | `A extends Record<...>` | The lookup table object |
| `def` | `B \| undefined` | Optional function to handle default values when lookup returns `undefined` |
### Returns [#returns]
Returns a function that accepts a key and returns the looked-up value, optionally processed by the default function.
### Type Parameters [#type-parameters]
* `A` - The type of the record used as a lookup table
* `B` - The type of the default function
* `C` - The key type for the lookup
## Examples [#examples]
### Example: Simple lookup table [#example-simple-lookup-table]
```typescript
import { lookup } from '@accelint/core';
const statusCodes = {
200: 'OK',
404: 'Not Found',
500: 'Internal Server Error'
};
const getStatus = lookup(statusCodes);
getStatus(200);
// 'OK'
getStatus(404);
// 'Not Found'
```
### Example: Lookup with default fallback [#example-lookup-with-default-fallback]
```typescript
import { lookup } from '@accelint/core';
const priorities = {
high: 1,
medium: 2,
low: 3
};
// Fallback to medium priority for unknown values
const getPriority = lookup(priorities, (x) => x ?? 2);
getPriority('high');
// 1
getPriority('critical'); // Not in table
// 2 (default)
```
### Example: Color lookup with RGBA arrays [#example-color-lookup-with-rgba-arrays]
```typescript
import { lookup } from '@accelint/core';
const colorTable = {
FOO: [0, 0, 255, 155],
BAR: [255, 0, 255, 155],
FIZZ: [230, 0, 0, 155],
BUZZ: [0, 128, 0, 155]
};
// Default to gray for unknown colors
const colorLookup = lookup(colorTable, (x) => x ?? [128, 128, 128, 155]);
colorLookup('FOO');
// [0, 0, 255, 155]
colorLookup('UNKNOWN');
// [128, 128, 128, 155]
```
### Example: Configuration lookup [#example-configuration-lookup]
```typescript
import { lookup } from '@accelint/core';
const envConfig = {
development: { apiUrl: 'http://localhost:3000', debug: true },
staging: { apiUrl: 'https://staging.example.com', debug: true },
production: { apiUrl: 'https://api.example.com', debug: false }
};
const getConfig = lookup(
envConfig,
() => envConfig.development // Default to dev config
);
getConfig('production');
// { apiUrl: 'https://api.example.com', debug: false }
getConfig('unknown');
// { apiUrl: 'http://localhost:3000', debug: true }
```
### Example: Using with map [#example-using-with-map]
```typescript
import { lookup, map } from '@accelint/core';
const rolePermissions = {
admin: ['read', 'write', 'delete'],
editor: ['read', 'write'],
viewer: ['read']
};
const getPermissions = lookup(rolePermissions, (x) => x ?? []);
const roles = ['admin', 'viewer', 'guest'];
const permissions = map(getPermissions)(roles);
// [['read', 'write', 'delete'], ['read'], []]
```
> **Good to know:** If no default function is provided, the lookup uses the `identity` function, which returns the value as-is (including `undefined` for missing keys). Provide a default function to handle missing keys gracefully.
## Related [#related]
* [property](../../object/property/index.md) - Get object property values
* [identity](../../combinators/identity/index.md) - Identity combinator
# noop (/docs/packages/core/utility/noop)
## Usage [#usage]
```typescript
import { noop } from '@accelint/core';
// Does nothing
noop();
// Accepts any argument but ignores it
noop('ignored');
noop(42);
noop({ data: 'also ignored' });
```
## Reference [#reference]
```typescript
function noop(_x?: unknown): void
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---------------------- | ---------------------------------- |
| `_x` | `unknown \| undefined` | Optional parameter that is ignored |
### Returns [#returns]
Returns `void` (nothing).
## Examples [#examples]
### Example: Placeholder callback [#example-placeholder-callback]
```typescript
import { noop } from '@accelint/core';
function fetchData(
url: string,
onSuccess: (data: unknown) => void = noop,
onError: (error: Error) => void = noop
) {
fetch(url)
.then(onSuccess)
.catch(onError);
}
// Use without callbacks
fetchData('https://api.example.com/data');
```
### Example: Disabling logging [#example-disabling-logging]
```typescript
import { noop } from '@accelint/core';
const logger = process.env.NODE_ENV === 'production'
? noop
: console.log;
logger('Debug message'); // Logged in dev, silent in prod
```
### Example: Optional event handlers [#example-optional-event-handlers]
```typescript
import { noop } from '@accelint/core';
interface ButtonProps {
onClick?: () => void;
onHover?: () => void;
}
function Button({ onClick = noop, onHover = noop }: ButtonProps) {
return (
<button
onClick={onClick}
onMouseEnter={onHover}
>
Click Me
</button>
);
}
```
### Example: Testing with stubbed functions [#example-testing-with-stubbed-functions]
```typescript
import { noop } from '@accelint/core';
function processData(
data: unknown[],
onProgress: (percent: number) => void = noop
) {
for (let i = 0; i < data.length; i++) {
// Process data...
onProgress((i / data.length) * 100);
}
}
// Test without progress callback
processData([1, 2, 3]); // No errors, progress updates ignored
```
### Example: Conditional operations [#example-conditional-operations]
```typescript
import { noop } from '@accelint/core';
const debug = process.env.DEBUG === 'true'
? console.log.bind(console)
: noop;
debug('This appears only when DEBUG=true');
```
> **Good to know:** `noop` is useful as a default value for optional callback parameters, allowing callers to omit callbacks without requiring `undefined` checks. It's also commonly used to disable logging or other side effects in production builds.
## Related [#related]
* [identity](../../combinators/identity/index.md) - Returns its input unchanged
* [tap](../tap/index.md) - Execute a function but return the original value
# once (/docs/packages/core/utility/once)
## Usage [#usage]
```typescript
import { once } from '@accelint/core';
let count = 0;
const increment = () => { count++; };
const incrementOnce = once(increment);
incrementOnce(); // count = 1
incrementOnce(); // count = 1 (not called again)
incrementOnce(); // count = 1 (still not called)
```
## Reference [#reference]
```typescript
function once<T extends (...args: any[]) => any>(
fn: T
): (...args: Parameters<T>) => void
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------------------- | ------------------------- |
| `fn` | `T extends Function` | The function to call once |
### Returns [#returns]
Returns a wrapped function that executes only on the first call. Subsequent calls do nothing.
### Type Parameters [#type-parameters]
* `T` - The type of the function to wrap
## Examples [#examples]
### Example: Initialization function [#example-initialization-function]
```typescript
import { once } from '@accelint/core';
const initializeDatabase = once(() => {
console.log('Connecting to database...');
// Expensive initialization
});
// First call executes
initializeDatabase(); // Logs: "Connecting to database..."
// Subsequent calls do nothing
initializeDatabase(); // No output
initializeDatabase(); // No output
```
### Example: Event listener setup [#example-event-listener-setup]
```typescript
import { once } from '@accelint/core';
const setupEventListeners = once(() => {
window.addEventListener('resize', handleResize);
window.addEventListener('scroll', handleScroll);
console.log('Event listeners attached');
});
// Safe to call multiple times
setupEventListeners(); // Listeners attached
setupEventListeners(); // No duplicate listeners
```
### Example: Singleton pattern [#example-singleton-pattern]
```typescript
import { once } from '@accelint/core';
class Service {
constructor() {
console.log('Service initialized');
}
}
let instance: Service;
const createInstance = once(() => {
instance = new Service();
});
createInstance(); // Logs: "Service initialized"
createInstance(); // No output, instance already created
```
### Example: With parameters [#example-with-parameters]
```typescript
import { once } from '@accelint/core';
let globalValue = 10;
const addToGlobal = (n: number) => {
globalValue += n;
console.log(`Added ${n}, total: ${globalValue}`);
};
const addOnce = once(addToGlobal);
addOnce(5); // Logs: "Added 5, total: 15"
addOnce(10); // No output (not called)
addOnce(20); // No output (not called)
console.log(globalValue); // 15
```
### Example: Cleanup on unmount [#example-cleanup-on-unmount]
```typescript
import { once } from '@accelint/core';
function useEffect(cleanup: () => void) {
// Ensure cleanup only runs once
const cleanupOnce = once(cleanup);
return () => {
cleanupOnce();
};
}
const unmount = useEffect(() => {
console.log('Cleaning up resources');
// Remove event listeners, close connections, etc.
});
unmount(); // Logs: "Cleaning up resources"
unmount(); // No output
```
### Example: Logging warning once [#example-logging-warning-once]
```typescript
import { once } from '@accelint/core';
const warnDeprecated = once((feature: string) => {
console.warn(`DEPRECATED: ${feature} will be removed in the next version`);
});
function oldApi() {
warnDeprecated('oldApi');
// Implementation...
}
oldApi(); // Logs warning
oldApi(); // No warning
oldApi(); // No warning
```
> **Good to know:** The wrapped function ignores all parameters on subsequent calls. Only the first invocation receives and uses the arguments. Use `once` for initialization, setup, or operations that should never repeat.
## Related [#related]
* [tap](../tap/index.md) - Execute a function but return the original value
* [noop](../noop/index.md) - No-operation function
* [identity](../../combinators/identity/index.md) - Returns its input unchanged
# tap (/docs/packages/core/utility/tap)
## Usage [#usage]
```typescript
import { tap } from '@accelint/core';
// Basic logging
tap(console.log)('hello');
// Logs: "hello"
// Returns: "hello"
// In a pipeline
pipe(
getValue,
tap(console.log), // Log intermediate value
transform,
tap(console.log), // Log result
);
```
## Reference [#reference]
```typescript
function tap<T, R>(fn: (v: T) => R): (val: T) => T
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ------------- | ----------------------------------- |
| `fn` | `(v: T) => R` | The function to call with the value |
### Returns [#returns]
Returns a curried function that accepts a value, passes it to the given function, and returns the value unchanged.
### Type Parameters [#type-parameters]
* `T` - The type of the input value
* `R` - The return type of the given function (ignored)
## Examples [#examples]
### Example: Debugging pipelines [#example-debugging-pipelines]
```typescript
import { tap, pipe, map, filter } from '@accelint/core';
const processNumbers = pipe(
tap((x) => console.log('Input:', x)),
map((x: number) => x * 2),
tap((x) => console.log('After map:', x)),
filter((x: number) => x > 10),
tap((x) => console.log('After filter:', x))
);
processNumbers([1, 5, 8, 12]);
// Logs:
// Input: [1, 5, 8, 12]
// After map: [2, 10, 16, 24]
// After filter: [16, 24]
// Returns: [16, 24]
```
### Example: Logging in method chains [#example-logging-in-method-chains]
```typescript
import { tap } from '@accelint/core';
const result = [1, 2, 3, 4, 5]
.map((x) => x * 2)
.map(tap(console.log)) // Log each value
.filter((x) => x > 5);
// Logs: 2, 4, 6, 8, 10
// Returns: [6, 8, 10]
```
### Example: Side effects without breaking flow [#example-side-effects-without-breaking-flow]
```typescript
import { tap } from '@accelint/core';
const analytics: number[] = [];
const trackValue = tap((value: number) => {
analytics.push(value);
});
const result = [1, 2, 3, 4, 5]
.map(trackValue)
.reduce((a, b) => a + b, 0);
console.log(analytics); // [1, 2, 3, 4, 5]
console.log(result); // 15
```
### Example: Validation logging [#example-validation-logging]
```typescript
import { tap, pipe } from '@accelint/core';
interface User {
id: number;
name: string;
email: string;
}
const validateUser = pipe(
tap((user: User) => {
if (!user.email.includes('@')) {
console.warn(`Invalid email for user ${user.id}`);
}
}),
tap((user: User) => {
if (user.name.length < 2) {
console.warn(`Short name for user ${user.id}`);
}
})
);
const user = { id: 1, name: 'A', email: 'invalid' };
validateUser(user);
// Logs warnings but returns user unchanged
```
### Example: Database operation logging [#example-database-operation-logging]
```typescript
import { tap } from '@accelint/core';
const logQuery = tap((query: string) => {
console.log(`[SQL] ${query}`);
});
const executeQuery = (query: string) =>
logQuery(query); // Log and pass through
executeQuery('SELECT * FROM users');
// Logs: "[SQL] SELECT * FROM users"
// Returns: "SELECT * FROM users"
```
### Example: Conditional logging [#example-conditional-logging]
```typescript
import { tap } from '@accelint/core';
const debugLog = process.env.DEBUG === 'true'
? tap(console.log)
: <T>(x: T) => x; // No-op in production
const result = pipe(
getValue,
debugLog, // Only logs in debug mode
transform
);
```
> **Good to know:** `tap` is designed for side effects—the return value of the tapped function is ignored. The original value always passes through unchanged. This makes it perfect for logging, debugging, and analytics without disrupting data flow.
## Related [#related]
* [pipe](../../composition/pipe/index.md) - Compose functions left-to-right
* [compose](../../composition/compose/index.md) - Compose functions right-to-left
* [identity](../../combinators/identity/index.md) - Returns its input unchanged
* [noop](../noop/index.md) - No-operation function
# uuid (/docs/packages/core/utility/uuid)
Generate and validate UUIDs (Universally Unique Identifiers). Supports both random UUIDs (v4) and stable deterministic UUIDs (v5).
## Usage [#usage]
```typescript
import { uuid, isUUID } from '@accelint/core';
// Generate random UUID
const id = uuid();
// '550e8400-e29b-41d4-a716-446655440000'
// Generate stable UUID from path
const stableId = uuid({ path: ['user', '123'] });
// Always produces the same UUID for this path
// Validate UUID
isUUID('550e8400-e29b-41d4-a716-446655440000');
// true
isUUID('not-a-uuid');
// false
```
## Reference [#reference]
### uuid [#uuid]
```typescript
function uuid(options?: UniqueIdOptions): UniqueId
```
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ------------------------------ | ------------------------------------------ |
| `options` | `UniqueIdOptions \| undefined` | Optional configuration for UUID generation |
#### UniqueIdOptions [#uniqueidoptions]
```typescript
type UniqueIdOptions = {
namespace?: UniqueId;
path?: (number | string)[];
};
```
| Property | Type | Description |
| ----------- | ----------------------------------- | ---------------------------------------------------- |
| `namespace` | `UniqueId \| undefined` | Namespace UUID for v5 generation (default: `v5.URL`) |
| `path` | `(number \| string)[] \| undefined` | Path components for deterministic generation |
#### Returns [#returns]
Returns a `UniqueId` (tagged string type representing a UUID).
### isUUID [#isuuid]
```typescript
function isUUID(value: unknown): value is UniqueId
```
#### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | --------- | --------------------- |
| `value` | `unknown` | The value to validate |
#### Returns [#returns-1]
Returns `true` if the value is a valid UUID, `false` otherwise. Acts as a type guard.
### Types [#types]
```typescript
type UniqueId = Tagged<string, 'UUID'>;
```
## Examples [#examples]
### Example: Random UUIDs [#example-random-uuids]
```typescript
import { uuid } from '@accelint/core';
// Generate unique IDs
const id1 = uuid();
const id2 = uuid();
id1 === id2; // false (different every time)
```
### Example: Stable deterministic UUIDs [#example-stable-deterministic-uuids]
```typescript
import { uuid } from '@accelint/core';
// Same path always produces same UUID
const userId = uuid({ path: ['user', '123'] });
const userId2 = uuid({ path: ['user', '123'] });
userId === userId2; // true (deterministic)
// Different path produces different UUID
const postId = uuid({ path: ['post', '456'] });
userId === postId; // false
```
### Example: Namespaced UUIDs [#example-namespaced-uuids]
```typescript
import { uuid } from '@accelint/core';
// Create a namespace
const appNamespace = uuid({ path: ['my', 'app'] });
// Generate IDs within that namespace
const id1 = uuid({ namespace: appNamespace, path: ['user', '1'] });
const id2 = uuid({ namespace: appNamespace, path: ['user', '2'] });
// Same namespace + path = same UUID
const id3 = uuid({ namespace: appNamespace, path: ['user', '1'] });
id1 === id3; // true
```
### Example: Dynamic stable IDs [#example-dynamic-stable-ids]
```typescript
import { uuid } from '@accelint/core';
interface Entity {
type: string;
id: number;
}
function getEntityId(entity: Entity) {
return uuid({ path: [entity.type, entity.id] });
}
const user = { type: 'user', id: 123 };
const id1 = getEntityId(user);
const id2 = getEntityId(user);
id1 === id2; // true (stable for same input)
```
### Example: Validating UUIDs [#example-validating-uuids]
```typescript
import { uuid, isUUID } from '@accelint/core';
function processId(id: string) {
if (!isUUID(id)) {
throw new Error('Invalid UUID');
}
// TypeScript knows id is UniqueId here
return id;
}
const validId = uuid();
processId(validId); // OK
processId('not-a-uuid'); // Throws error
```
### Example: Database primary keys [#example-database-primary-keys]
```typescript
import { uuid } from '@accelint/core';
interface User {
id: string;
name: string;
email: string;
}
function createUser(name: string, email: string): User {
return {
id: uuid(), // Random UUID
name,
email
};
}
const user = createUser('Alice', 'alice@example.com');
// { id: '...uuid...', name: 'Alice', email: 'alice@example.com' }
```
### Example: Idempotency keys [#example-idempotency-keys]
```typescript
import { uuid } from '@accelint/core';
interface Payment {
amount: number;
userId: string;
}
function createIdempotencyKey(payment: Payment) {
// Same payment details = same idempotency key
return uuid({
path: ['payment', payment.userId, String(payment.amount)]
});
}
const payment = { amount: 100, userId: 'user-123' };
const key1 = createIdempotencyKey(payment);
const key2 = createIdempotencyKey(payment);
key1 === key2; // true (prevents duplicate charges)
```
> **Good to know:** When `path` is provided, `uuid` generates a deterministic v5 UUID based on the namespace and path. When `path` is empty or omitted, it generates a random v4 UUID. Use deterministic UUIDs for stable IDs based on content, and random UUIDs for true uniqueness.
## Related [#related]
* [noop](../noop/index.md) - No-operation function
* [once](../once/index.md) - Ensure a function is only called once
# Coordinate System (/docs/packages/geo/coordinates/coordinate)
Parse, validate, convert, and format geographic coordinates across multiple notation systems including Decimal Degrees, Degrees Decimal Minutes, Degrees Minutes Seconds, MGRS, and UTM.
## coordinateSystems [#coordinatesystems]
Available coordinate systems for parsing, converting, and formatting geographic coordinates.
### Usage [#usage]
```typescript
import { coordinateSystems, createCoordinate } from '@accelint/geo';
// Create a coordinate parser for Decimal Degrees
const create = createCoordinate(coordinateSystems.dd, 'LATLON');
const coord = create('40.7128 / -74.0060');
```
### Reference [#reference]
```typescript
const coordinateSystems: {
readonly dd: CoordinateSystem;
readonly ddm: CoordinateSystem;
readonly dms: CoordinateSystem;
readonly mgrs: CoordinateSystem;
readonly utm: CoordinateSystem;
};
```
Provides five coordinate notation systems:
* `dd` - Decimal Degrees (e.g., 40.7128° N)
* `ddm` - Degrees Decimal Minutes (e.g., 40° 42.768' N)
* `dms` - Degrees Minutes Seconds (e.g., 40° 42' 46" N)
* `mgrs` - Military Grid Reference System (e.g., 18T WL 80000 00000)
* `utm` - Universal Transverse Mercator (e.g., 18 N 585628 4511322)
### Examples [#examples]
#### Example: Using Decimal Degrees [#example-using-decimal-degrees]
```typescript
import { coordinateSystems, createCoordinate } from '@accelint/geo';
const create = createCoordinate(coordinateSystems.dd, 'LATLON');
const coord = create('40.7128 / -74.0060');
coord.dd(); // '40.7128 N / 74.006 W'
coord.dms(); // '40 42 46.08 N / 74 0 21.6 W'
```
#### Example: Using MGRS [#example-using-mgrs]
```typescript
import { coordinateSystems, createCoordinate } from '@accelint/geo';
const createMGRS = createCoordinate(coordinateSystems.mgrs);
const coord = createMGRS('18T WL 80000 00000');
coord.mgrs(); // '18T WL 80000 00000'
coord.dd(); // Converts to Decimal Degrees
```
#### Example: Using UTM [#example-using-utm]
```typescript
import { coordinateSystems, createCoordinate } from '@accelint/geo';
const createUTM = createCoordinate(coordinateSystems.utm, 'LATLON');
const coord = createUTM('18 N 585628 4511322');
coord.utm(); // '18N 585628 4511322'
coord.dd(); // '40.74839601188732 N / 73.98570490632135 W'
```
## createCoordinate [#createcoordinate]
Creates a coordinate object enabling lexing, parsing, validation, and formatting across multiple coordinate systems.
### Usage [#usage-1]
```typescript
import { createCoordinate, coordinateSystems } from '@accelint/geo';
// Create with default Decimal Degrees and LATLON format
const create = createCoordinate();
const coord = create('40.7128 / -74.0060');
coord.dd(); // '40.7128 N / 74.006 W'
coord.dms(); // '40 42 46.08 N / 74 0 21.6 W'
```
### Reference [#reference-1]
```typescript
function createCoordinate(
initSystem?: CoordinateSystem,
initFormat?: 'LATLON' | 'LONLAT'
): (input: CoordinateInput) => Coordinate
type CoordinateInput =
| string
| [number, number]
| CoordinateObject
interface CoordinateObject {
lat?: number;
latitude?: number;
LAT?: number;
LATITUDE?: number;
lon?: number;
longitude?: number;
LON?: number;
LONGITUDE?: number;
}
interface Coordinate {
dd(format?: 'LATLON' | 'LONLAT'): string;
ddm(format?: 'LATLON' | 'LONLAT'): string;
dms(format?: 'LATLON' | 'LONLAT'): string;
mgrs(format?: 'LATLON' | 'LONLAT'): string;
utm(format?: 'LATLON' | 'LONLAT'): string;
errors: string[];
raw: { LAT: number; LON: number };
valid: boolean;
}
```
### Parameters [#parameters]
| Parameter | Type | Default | Description |
| ------------ | ---------------------- | ---------------------- | ----------------------------------------------------------------- |
| `initSystem` | `CoordinateSystem` | `coordinateSystems.dd` | Coordinate system to use for parsing (dd, ddm, dms, mgrs, or utm) |
| `initFormat` | `'LATLON' \| 'LONLAT'` | `'LATLON'` | Coordinate format ordering |
### Returns [#returns]
Returns a function that accepts coordinate input (string, tuple, or object) and returns a `Coordinate` object with formatters and validation state.
### Examples [#examples-1]
#### Example: Parsing string coordinates [#example-parsing-string-coordinates]
```typescript
import { createCoordinate, coordinateSystems } from '@accelint/geo';
const create = createCoordinate(coordinateSystems.dd, 'LATLON');
const coord = create('40.7128 / -74.0060');
coord.valid; // true
coord.dd(); // '40.7128 N / 74.006 W'
coord.dms(); // '40 42 46.08 N / 74 0 21.6 W'
```
#### Example: Parsing numeric tuples [#example-parsing-numeric-tuples]
```typescript
import { createCoordinate } from '@accelint/geo';
const create = createCoordinate();
const coord = create([40.7128, -74.0060]);
coord.valid; // true
coord.raw; // { LAT: 40.7128, LON: -74.0060 }
```
#### Example: Parsing coordinate objects [#example-parsing-coordinate-objects]
```typescript
import { createCoordinate } from '@accelint/geo';
const create = createCoordinate();
const coord = create({ lat: 40.7128, lon: -74.0060 });
coord.valid; // true
coord.dd(); // '40.7128 N / 74.006 W'
```
#### Example: Converting between formats [#example-converting-between-formats]
```typescript
import { createCoordinate, coordinateSystems } from '@accelint/geo';
const create = createCoordinate(coordinateSystems.ddm, 'LONLAT');
const coord = create('-74 0.36 / 40 42.768');
// Convert to different format ordering
coord.ddm('LATLON'); // '40 42.768 N / 74 0.36 W'
```
#### Example: Converting between systems [#example-converting-between-systems]
```typescript
import { createCoordinate, coordinateSystems } from '@accelint/geo';
const create = createCoordinate(coordinateSystems.dd, 'LATLON');
const coord = create('89.765432109 / 123.456789012');
// Original format honored
coord.dd(); // '89.765432109 N / 123.456789012 E'
coord.ddm(); // '89 45.92592654 N / 123 27.40734072 E'
coord.dms(); // '89 45 55.5555924 N / 123 27 24.4404432 E'
// Change format to LONLAT
coord.dms('LONLAT'); // '123 27 24.4404432 E / 89 45 55.5555924 N'
```
#### Example: Error handling [#example-error-handling]
```typescript
import { createCoordinate } from '@accelint/geo';
const create = createCoordinate();
const coord = create('91 / 0'); // Invalid latitude
coord.valid; // false
coord.errors; // ['[ERROR] Degrees value (91) exceeds max value (90).']
```
#### Example: LONLAT format ordering [#example-lonlat-format-ordering]
```typescript
import { createCoordinate, coordinateSystems } from '@accelint/geo';
const create = createCoordinate(coordinateSystems.dd, 'LONLAT');
const coord = create('90.5 W / 45.5 N');
coord.raw; // { LAT: 45.5, LON: -90.5 }
```
> **Good to know:** The original coordinate system and format are preserved without conversion to prevent rounding errors. All alternative values are computed from a common internal representation in Decimal Degrees.
> **Good to know:** Coordinate objects support case-insensitive keys: `lat`/`LAT`/`latitude`/`LATITUDE` and `lon`/`LON`/`longitude`/`LONGITUDE`.
## Related [#related]
* [formatDecimalDegrees](./latlon/decimal-degrees/formatter.md) - Format coordinates in Decimal Degrees notation
* [parseDecimalDegrees](./latlon/decimal-degrees/parser.md) - Parse Decimal Degrees coordinate strings
* [parseMGRS](./mgrs/parser.md) - Parse Military Grid Reference System coordinates
* [parseUTM](./utm/parser.md) - Parse Universal Transverse Mercator coordinates
# bearing (/docs/packages/geo/geodesy/bearing)
## Usage [#usage]
```typescript
import { bearing } from '@accelint/geo/geodesy';
bearing([0, 0], [0, 1]); // 0 — due north
bearing([0, 0], [1, 0]); // 90 — due east
bearing([0, 1], [0, 0]); // 180 — due south
bearing([0, 0], [-1, 0]); // 270 — due west
```
## Reference [#reference]
```typescript
function bearing(origin: LonLatTuple, destination: LonLatTuple): number
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ------------- | ------------- | ------------------------------------------------------------------ |
| `origin` | `LonLatTuple` | Starting coordinate as `[longitude, latitude]` in decimal degrees. |
| `destination` | `LonLatTuple` | Ending coordinate as `[longitude, latitude]` in decimal degrees. |
### Returns [#returns]
Returns the initial bearing in degrees clockwise from true north, in `[0, 360)`. Returns `0` when `origin` and `destination` coincide (within `Number.EPSILON` degrees).
### Throws [#throws]
* `RangeError` when any coordinate component is not a finite number. The message names the function: `bearing requires finite [longitude, latitude] coordinates.`
## Examples [#examples]
### Example: Bearing between two cities [#example-bearing-between-two-cities]
```typescript
import { bearing } from '@accelint/geo/geodesy';
const london = [-0.1278, 51.5074] as const;
const paris = [2.3522, 48.8566] as const;
bearing(london, paris);
// ~148.1 — southeast
```
### Example: Crossing the antimeridian [#example-crossing-the-antimeridian]
```typescript
import { bearing } from '@accelint/geo/geodesy';
// 179°E to 179°W is 2° east along the equator, not 358° west
bearing([179, 0], [-179, 0]);
// ~90
```
### Example: Identical points [#example-identical-points]
```typescript
import { bearing } from '@accelint/geo/geodesy';
bearing([10, 20], [10, 20]);
// 0
```
### Example: Rejecting non-finite input [#example-rejecting-non-finite-input]
```typescript
import { bearing } from '@accelint/geo/geodesy';
bearing([Number.NaN, 0], [1, 1]);
// throws RangeError: bearing requires finite [longitude, latitude] coordinates.
```
> **Good to know:** Longitude and latitude are not range-checked. Map libraries such as deck.gl pass longitudes beyond ±180 when the map wraps, and the spherical math is periodic, so those values still produce the correct bearing. For antipodal points (such as pole to pole) the bearing is mathematically undefined; the function still returns a finite value in `[0, 360)`.
## Related [#related]
* [distance](./distance.md) - Great-circle distance in meters
* [midpoint](./midpoint.md) - Great-circle midpoint between two points
* [greatCirclePoints](./great-circle-points.md) - Sample vertices along the great-circle path
* [toSphericalPoints](./to-spherical-points.md) - Shared validation and conversion step
# distance (/docs/packages/geo/geodesy/distance)
## Usage [#usage]
```typescript
import { distance } from '@accelint/geo/geodesy';
// London to Paris
distance([-0.1278, 51.5074], [2.3522, 48.8566]);
// ~343556 — meters (~343.6 km)
// One degree of latitude at the equator
distance([0, 0], [0, 1]);
// ~111195
```
## Reference [#reference]
```typescript
function distance(origin: LonLatTuple, destination: LonLatTuple): number
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ------------- | ------------- | ------------------------------------------------------------------ |
| `origin` | `LonLatTuple` | Starting coordinate as `[longitude, latitude]` in decimal degrees. |
| `destination` | `LonLatTuple` | Ending coordinate as `[longitude, latitude]` in decimal degrees. |
### Returns [#returns]
Returns the great-circle distance in meters on a sphere with a mean radius of 6371 km. Returns `0` when the two points are identical. The result is symmetric: `distance(a, b)` equals `distance(b, a)`.
### Throws [#throws]
* `RangeError` when any coordinate component is not a finite number. The message names the function: `distance requires finite [longitude, latitude] coordinates.`
## Examples [#examples]
### Example: Crossing the antimeridian [#example-crossing-the-antimeridian]
```typescript
import { distance } from '@accelint/geo/geodesy';
// 2 degrees of longitude at the equator, measured the short way around
distance([179, 0], [-179, 0]);
// ~222390
```
### Example: Antipodal and near-antipodal points [#example-antipodal-and-near-antipodal-points]
```typescript
import { distance } from '@accelint/geo/geodesy';
// Pole to pole is half the Earth's circumference
distance([0, 90], [0, -90]);
// ~20015087 — Math.PI * 6371e3
// Near-antipodal pairs where the underlying haversine would return NaN
// resolve to the same value instead
distance(
[165.56831887102487, 20.542180502772695],
[-14.43168138306451, -20.542180512793223],
);
// ~20015087
```
### Example: Wrapped-map longitudes [#example-wrapped-map-longitudes]
```typescript
import { distance } from '@accelint/geo/geodesy';
// Longitudes beyond ±180 are not rejected; the math is periodic
distance([360, 0], [0, 1]);
// ~111195 — same as distance([0, 0], [0, 1])
```
### Example: Rejecting non-finite input [#example-rejecting-non-finite-input]
```typescript
import { distance } from '@accelint/geo/geodesy';
distance([Number.NaN, 0], [1, 1]);
// throws RangeError: distance requires finite [longitude, latitude] coordinates.
```
> **Good to know:** The Haversine formula takes `sqrt(1 - a)`, and floating-point rounding can push `a` just past 1 for near-antipodal pairs, which the `geodesy` library reports as `NaN`. `distance` clamps that band to half the circumference (`Math.PI * 6371e3`, about 20,015 km), which is the true value there.
## Related [#related]
* [bearing](./bearing.md) - Initial great-circle bearing
* [midpoint](./midpoint.md) - Great-circle midpoint between two points
* [greatCirclePoints](./great-circle-points.md) - Draw the route this function measures
* [toSphericalPoints](./to-spherical-points.md) - Shared validation and conversion step
# greatCirclePoints (/docs/packages/geo/geodesy/great-circle-points)
## Usage [#usage]
```typescript
import { greatCirclePoints } from '@accelint/geo/geodesy';
// Four segments across the antimeridian: longitudes stay monotonic
greatCirclePoints([179, 0], [-179, 0], 4);
// [[179, 0], [179.5, 0], [180, 0], [180.5, 0], [181, 0]]
// Default of 64 segments yields 65 vertices
greatCirclePoints([-74, 40.7], [139.7, 35.7]).length;
// 65
```
## Reference [#reference]
```typescript
function greatCirclePoints(
origin: LonLatTuple,
destination: LonLatTuple,
segments?: number,
): [number, number][]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ------------- | ------------- | ----------------------------------------------------------------------------------------- |
| `origin` | `LonLatTuple` | Starting point as `[longitude, latitude]` in decimal degrees. |
| `destination` | `LonLatTuple` | Ending point as `[longitude, latitude]` in decimal degrees. |
| `segments` | `number` | Number of segments to divide the path into. Must be a positive integer. Defaults to `64`. |
### Returns [#returns]
Returns `segments + 1` vertices as `[longitude, latitude]` tuples, evenly spaced along the geodesic. The first vertex is `origin` exactly as given and the last is `destination`. Each longitude is shifted by whole turns of 360° so it sits within 180° of the previous vertex, so a path that crosses the antimeridian runs 179 → 181 rather than 179 → -179. When `origin` and `destination` are identical, returns the two endpoints as given regardless of `segments`.
### Throws [#throws]
* `RangeError` when `segments` is not a positive integer (zero, negative, or fractional): `greatCirclePoints requires a positive integer segment count.`
* `RangeError` when any coordinate component is not a finite number: `greatCirclePoints requires finite [longitude, latitude] coordinates.`
## Examples [#examples]
### Example: Drawing a route as one polyline [#example-drawing-a-route-as-one-polyline]
```typescript
import { PathLayer } from '@deck.gl/layers';
import { greatCirclePoints } from '@accelint/geo/geodesy';
// New York to Tokyo
const points = greatCirclePoints([-74, 40.7], [139.7, 35.7], 8);
points.length; // 9
points[0]; // [-74, 40.7]
points[8]; // [-220.3, 35.7] — 139.7 - 360, since the route runs west over the Pacific
// Feed directly to a path layer; no split at the antimeridian is needed
new PathLayer({ data: [{ path: points }], getPath: (route) => route.path });
```
### Example: The middle vertex is the geodesic midpoint [#example-the-middle-vertex-is-the-geodesic-midpoint]
```typescript
import { greatCirclePoints, midpoint } from '@accelint/geo/geodesy';
const origin = [-74, 40.7] as const;
const destination = [139.7, 35.7] as const;
const points = greatCirclePoints(origin, destination, 8);
const [longitude, latitude] = midpoint(origin, destination);
points[4]; // [~longitude, ~latitude]
```
### Example: Identical points [#example-identical-points]
```typescript
import { greatCirclePoints } from '@accelint/geo/geodesy';
greatCirclePoints([10, 20], [10, 20], 4);
// [[10, 20], [10, 20]]
```
### Example: Rejecting an invalid segment count [#example-rejecting-an-invalid-segment-count]
```typescript
import { greatCirclePoints } from '@accelint/geo/geodesy';
greatCirclePoints([0, 0], [1, 1], 0); // throws RangeError
greatCirclePoints([0, 0], [1, 1], -2); // throws RangeError
greatCirclePoints([0, 0], [1, 1], 2.5); // throws RangeError
```
> **Good to know:** Longitude and latitude are not range-checked, matching `bearing` and `distance`. Returned longitudes are unwrapped, not normalized, so they can fall outside `[-180, 180]`; normalize them yourself if a consumer requires that range. Antipodal pairs have no unique great circle, so their vertices are not meaningful; see `midpoint` for how that case resolves.
## Related [#related]
* [distance](./distance.md) - The great-circle length this function samples
* [midpoint](./midpoint.md) - Great-circle midpoint between two points
* [bearing](./bearing.md) - Initial great-circle bearing
* [toSphericalPoints](./to-spherical-points.md) - Shared validation and conversion step
# Geodesy (/docs/packages/geo/geodesy)
## Installation [#installation]
```bash
pnpm add @accelint/geo
```
## Usage [#usage]
```typescript
// Import from the geodesy sub-module
import { bearing, distance, greatCirclePoints, midpoint } from '@accelint/geo/geodesy';
// Or from the package root
import { bearing, distance, greatCirclePoints, midpoint } from '@accelint/geo';
// London to Paris
const london = [-0.1278, 51.5074] as const;
const paris = [2.3522, 48.8566] as const;
bearing(london, paris); // ~148.1 — degrees clockwise from true north
distance(london, paris); // ~343556 — meters
midpoint(london, paris); // [~1.15, ~50.19]
greatCirclePoints(london, paris, 8).length; // 9 vertices along the route
```
## Coordinate Order [#coordinate-order]
Every function takes `LonLatTuple` values: `[longitude, latitude]` in decimal degrees (GeoJSON order). This is the reverse of the `[latitude, longitude]` order that `createCoordinate` and the standalone formatters accept, so check the order when passing coordinates between the two APIs.
Longitude and latitude are not range-checked. Map libraries such as deck.gl hand these functions longitudes beyond ±180 when the map wraps, and the spherical math is periodic, so out-of-range values still produce correct results. Every function throws a `RangeError` when any coordinate component is `NaN` or infinite.
## Available Exports [#available-exports]
| Export Path | Description |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| [bearing](./bearing.md) | Initial great-circle bearing in degrees clockwise from true north, `[0, 360)` |
| [distance](./distance.md) | Great-circle distance in meters, clamped to half the Earth's circumference for near-antipodal pairs |
| [midpoint](./midpoint.md) | Great-circle midpoint along the shortest path, longitude normalized to `[-180, 180]` |
| [greatCirclePoints](./great-circle-points.md) | `segments + 1` evenly spaced vertices along the geodesic, with unwrapped longitudes for drawing |
| [toSphericalPoints](./to-spherical-points.md) | Shared validation step that converts both tuples to `LatLonSpherical` points; not part of the `@accelint/geo/geodesy` barrel |
All functions use the spherical Earth model from the `geodesy` library with a mean radius of 6371 km.
## Related [#related]
* [@accelint/geo](../index.md) - Package overview
* [createCoordinate](../coordinates/coordinate.md) - Parse, validate, convert, and format coordinates
* [@accelint/formatters](../../formatters/bearing.md) - `formatBearing` and `formatDistance` for display
# midpoint (/docs/packages/geo/geodesy/midpoint)
## Usage [#usage]
```typescript
import { midpoint } from '@accelint/geo/geodesy';
midpoint([0, 0], [0, 10]);
// [0, 5] — halfway along a meridian
midpoint([0, 0], [10, 0]);
// [5, 0] — halfway along the equator
midpoint([179, 0], [-179, 0]);
// [180, 0] — crosses the antimeridian rather than the prime meridian
```
## Reference [#reference]
```typescript
function midpoint(origin: LonLatTuple, destination: LonLatTuple): [number, number]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ------------- | ------------- | ------------------------------------------------------------------ |
| `origin` | `LonLatTuple` | Starting coordinate as `[longitude, latitude]` in decimal degrees. |
| `destination` | `LonLatTuple` | Ending coordinate as `[longitude, latitude]` in decimal degrees. |
### Returns [#returns]
Returns the midpoint as `[longitude, latitude]` in decimal degrees. The point lies on the shortest great-circle path and is equidistant from both endpoints. Longitude is normalized to `[-180, 180]` by the underlying `geodesy` library. When `origin` and `destination` are identical, returns the point itself.
### Throws [#throws]
* `RangeError` when any coordinate component is not a finite number. The message names the function: `midpoint requires finite [longitude, latitude] coordinates.`
## Examples [#examples]
### Example: Midpoint between two cities [#example-midpoint-between-two-cities]
```typescript
import { midpoint } from '@accelint/geo/geodesy';
const london = [-0.1278, 51.5074] as const;
const paris = [2.3522, 48.8566] as const;
midpoint(london, paris);
// [~1.15, ~50.19]
```
### Example: Normalizing wrapped-map longitudes [#example-normalizing-wrapped-map-longitudes]
```typescript
import { midpoint } from '@accelint/geo/geodesy';
// Inputs beyond ±180 are accepted; the result is normalized to [-180, 180]
midpoint([190, 0], [200, 0]);
// [-165, 0]
```
### Example: Antipodal points [#example-antipodal-points]
```typescript
import { midpoint } from '@accelint/geo/geodesy';
// No unique midpoint exists; the result is on the equator, 90° of longitude
// from the origin, in the direction of (destination - origin)
midpoint([0, 0], [180, 0]);
// [90, 0]
midpoint([10, 45], [-170, -45]);
// [-80, 0]
// Pole to pole along one meridian keeps the origin longitude
midpoint([0, 90], [0, -90]);
// [0, 0]
```
### Example: Identical points [#example-identical-points]
```typescript
import { midpoint } from '@accelint/geo/geodesy';
midpoint([10, 20], [10, 20]);
// [10, 20]
```
### Example: Rejecting non-finite input [#example-rejecting-non-finite-input]
```typescript
import { midpoint } from '@accelint/geo/geodesy';
midpoint([Number.NaN, 0], [1, 1]);
// throws RangeError: midpoint requires finite [longitude, latitude] coordinates.
```
> **Good to know:** For antipodal pairs every great circle through the two points is a candidate path, so the midpoint is not unique. The formula degrades to `atan2(≈0, 0)` and the library returns an equatorial point 90° of longitude from `origin`. Pairs that are merely close to antipodal are ill-conditioned; the package's property tests stay 1 km clear of that limit when asserting equidistance.
## Related [#related]
* [bearing](./bearing.md) - Initial great-circle bearing
* [distance](./distance.md) - Great-circle distance in meters
* [greatCirclePoints](./great-circle-points.md) - Sample vertices along the great-circle path
* [toSphericalPoints](./to-spherical-points.md) - Shared validation and conversion step
# toSphericalPoints (/docs/packages/geo/geodesy/to-spherical-points)
## Usage [#usage]
```typescript
import { toSphericalPoints } from '@accelint/geo/geodesy/to-spherical-points';
// or: import { toSphericalPoints } from '@accelint/geo';
const [originPoint, destinationPoint] = toSphericalPoints([0, 0], [0, 1], 'bearing');
originPoint.initialBearingTo(destinationPoint);
// 0
```
`toSphericalPoints` is exported from the package root and from its own sub-path. It is not part of the `@accelint/geo/geodesy` barrel.
## Reference [#reference]
```typescript
function toSphericalPoints(
origin: LonLatTuple,
destination: LonLatTuple,
caller: string,
): [LatLonSpherical, LatLonSpherical]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ------------- | ------------- | ------------------------------------------------------------------ |
| `origin` | `LonLatTuple` | Starting coordinate as `[longitude, latitude]` in decimal degrees. |
| `destination` | `LonLatTuple` | Ending coordinate as `[longitude, latitude]` in decimal degrees. |
| `caller` | `string` | Name of the calling function, used in the thrown error message. |
### Returns [#returns]
Returns the origin and destination as `LatLonSpherical` points from the `geodesy` library, in that order. Each point exposes the input as `.lat` and `.lon`.
### Throws [#throws]
* `RangeError` when any of the four coordinate components is `NaN`, `Infinity`, or `-Infinity`. The message is `${caller} requires finite [longitude, latitude] coordinates.`
## Examples [#examples]
### Example: Calling other LatLonSpherical methods on validated input [#example-calling-other-latlonspherical-methods-on-validated-input]
```typescript
import { toSphericalPoints } from '@accelint/geo/geodesy/to-spherical-points';
const [originPoint, destinationPoint] = toSphericalPoints(
[-0.1278, 51.5074],
[2.3522, 48.8566],
'finalBearing',
);
// Methods that @accelint/geo does not wrap directly
originPoint.finalBearingTo(destinationPoint);
originPoint.destinationPoint(1000, 90);
```
### Example: Reading the converted points [#example-reading-the-converted-points]
```typescript
import { toSphericalPoints } from '@accelint/geo/geodesy/to-spherical-points';
const [originPoint, destinationPoint] = toSphericalPoints([10, 20], [30, 40], 'caller');
[originPoint.lat, originPoint.lon]; // [20, 10]
[destinationPoint.lat, destinationPoint.lon]; // [40, 30]
```
### Example: Naming the caller in the error [#example-naming-the-caller-in-the-error]
```typescript
import { toSphericalPoints } from '@accelint/geo/geodesy/to-spherical-points';
toSphericalPoints([Number.NaN, 0], [1, 1], 'someFunction');
// throws RangeError: someFunction requires finite [longitude, latitude] coordinates.
toSphericalPoints([0, 0], [1, Number.POSITIVE_INFINITY], 'someFunction');
// throws RangeError: someFunction requires finite [longitude, latitude] coordinates.
```
> **Good to know:** This is the shared preamble behind `bearing`, `distance`, `midpoint`, and `greatCirclePoints`. Longitude and latitude are not range-checked, only checked for finiteness, so longitudes beyond ±180 from a wrapped map pass through unchanged.
## Related [#related]
* [bearing](./bearing.md) - Initial great-circle bearing
* [distance](./distance.md) - Great-circle distance in meters
* [midpoint](./midpoint.md) - Great-circle midpoint between two points
* [greatCirclePoints](./great-circle-points.md) - Sample vertices along the great-circle path
# bootstrap (/docs/packages/logger/default/bootstrap)
## Usage [#usage]
```typescript
import { bootstrap } from '@accelint/logger';
// Create an independent logger instance
const logger = bootstrap({
enabled: true,
level: 'warn',
env: process.env.NODE_ENV as 'production' | 'development',
prefix: '[MyModule]',
});
logger.withMetadata({ requestId: 'req_123' }).warn('Token expiring soon');
```
## Reference [#reference]
```typescript
function bootstrap(options: LoggerOptions): LogLayer
```
### Parameters [#parameters]
| Parameter | Type | Description |
| -------------------- | ------------------------------- | -------------------------------------------------------------------------- |
| `options` | `LoggerOptions` | Logger configuration options |
| `options.enabled` | `boolean` | Whether logging is active; `false` makes all calls no-ops |
| `options.level` | `LogLevel` | Minimum log level to output (default: `'debug'`) |
| `options.env` | `'production' \| 'development'` | Runtime environment; controls server detection (default: `'development'`) |
| `options.pretty` | `boolean` | Use pretty console output; `false` emits structured JSON (default: `true`) |
| `options.prefix` | `string` | String prepended to all log messages (default: `''`) |
| `options.plugins` | `LogLayerPlugin[]` | Additional plugins applied after the built-in ones |
| `options.transports` | `LogLayerTransport[]` | Custom transports that replace the default console transport |
| `options.groups` | `LogGroupsConfig` | Named group configuration for conditional group logging |
### Returns [#returns]
Returns a configured LogLayer instance.
Built-in plugins are applied in this order before any user-supplied plugins:
1. `callsitePlugin` — injects source file location into every log entry
2. `environmentPlugin` — injects server/browser context into every log entry
The returned instance uses a one-way log level manager: the level can only be raised (made more restrictive) after initialization, never lowered.
> **Good to know:** Unlike [`getLogger`](./index.md), `bootstrap` creates a new logger instance on every call. Use `bootstrap` when you need multiple independent loggers with different configurations, or when you want to avoid the singleton pattern.
## Examples [#examples]
### Example: Module-specific logger [#example-module-specific-logger]
```typescript
import { bootstrap } from '@accelint/logger';
// Create a dedicated logger for a specific module
const dbLogger = bootstrap({
enabled: true,
level: 'debug',
prefix: '[Database]',
});
const cacheLogger = bootstrap({
enabled: true,
level: 'info',
prefix: '[Cache]',
});
dbLogger.debug('Query executed', { duration: 42 });
cacheLogger.info('Cache miss', { key: 'user:123' });
```
### Example: Testing with isolated logger [#example-testing-with-isolated-logger]
```typescript
import { bootstrap } from '@accelint/logger';
import { describe, test, expect } from 'vitest';
describe('Payment service', () => {
test('should log payment success', () => {
// Create isolated logger for this test
const logger = bootstrap({
enabled: true,
level: 'info',
});
processPayment(logger);
// Test logger output without affecting other tests
});
});
```
### Example: Production logger with structured JSON [#example-production-logger-with-structured-json]
```typescript
import { bootstrap } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
level: 'warn',
env: 'production',
pretty: false, // JSON output for log aggregation
});
logger.error('Payment failed', {
orderId: 'ord_abc123',
error: new Error('Insufficient funds'),
});
```
### Example: Custom transport for external logging service [#example-custom-transport-for-external-logging-service]
```typescript
import { bootstrap } from '@accelint/logger';
import type { LogLayerTransport } from '@loglayer/shared';
const externalTransport: LogLayerTransport = {
log(level, message, data) {
// Send logs to external service
fetch('https://logs.example.com/ingest', {
method: 'POST',
body: JSON.stringify({ level, message, data }),
});
},
};
const logger = bootstrap({
enabled: true,
transports: [externalTransport],
});
logger.info('External logging enabled');
```
### Example: Environment-specific configuration [#example-environment-specific-configuration]
```typescript
import { bootstrap } from '@accelint/logger';
const isDevelopment = process.env.NODE_ENV === 'development';
const logger = bootstrap({
enabled: true,
level: isDevelopment ? 'debug' : 'warn',
env: isDevelopment ? 'development' : 'production',
pretty: isDevelopment,
prefix: isDevelopment ? '[Dev]' : '',
});
logger.debug('Development-only debug log');
logger.warn('This logs in all environments');
```
### Example: Multiple transports [#example-multiple-transports]
```typescript
import { bootstrap, prettyTransport, structuredTransport } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
transports: [
prettyTransport({ level: 'debug' }),
structuredTransport({ level: 'warn' }),
],
});
logger.debug('Pretty console only');
logger.warn('Both pretty console and JSON');
logger.error('Both pretty console and JSON');
```
### Example: Custom plugins for request tracking [#example-custom-plugins-for-request-tracking]
```typescript
import { bootstrap } from '@accelint/logger';
import type { LogLayerPlugin } from '@loglayer/shared';
let requestCounter = 0;
const requestIdPlugin: LogLayerPlugin = {
id: 'request-id',
onBeforeDataOut({ data }) {
return {
...data,
requestId: `req_${++requestCounter}`,
};
},
};
const logger = bootstrap({
enabled: true,
plugins: [requestIdPlugin],
});
logger.info('First request'); // requestId: req_1
logger.info('Second request'); // requestId: req_2
```
### Example: Disabling plugins for minimal overhead [#example-disabling-plugins-for-minimal-overhead]
```typescript
import { bootstrap } from '@accelint/logger';
// Create logger with only essential features
const minimalLogger = bootstrap({
enabled: true,
plugins: [], // No user plugins (built-in plugins still run)
});
// For even lower overhead, disable logging entirely
const noOpLogger = bootstrap({
enabled: false, // All log calls become no-ops
});
```
### Example: Log groups for feature flags [#example-log-groups-for-feature-flags]
```typescript
import { bootstrap } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
groups: {
'feature-x': { enabled: true },
'feature-y': { enabled: false },
'experiment-z': { enabled: true },
},
});
logger.withGroup('feature-x').info('Feature X is active');
logger.withGroup('feature-y').info('This will not log');
logger.withGroup('experiment-z').debug('Experiment Z running');
```
### Example: Server-side rendering logger [#example-server-side-rendering-logger]
```typescript
import { bootstrap } from '@accelint/logger';
const isServer = typeof window === 'undefined';
const logger = bootstrap({
enabled: true,
env: isServer ? 'production' : 'development',
pretty: !isServer, // Pretty in browser, JSON on server
prefix: isServer ? '[Server]' : '[Client]',
});
logger.info('Rendering component');
// [Server] Rendering component (on server)
// [Client] Rendering component (in browser)
```
### Example: One-way log level restriction [#example-one-way-log-level-restriction]
```typescript
import { bootstrap, WARN, ERROR } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
level: WARN,
});
logger.warn('This logs');
// Raise the level to ERROR (more restrictive)
logger.setLogLevel(ERROR);
logger.warn('This no longer logs');
logger.error('This still logs');
// Attempting to lower to WARN would be ignored (one-way manager)
```
> **Good to know:** `bootstrap` is the foundation of `getLogger`. While `getLogger` implements singleton pattern for application-wide logging, `bootstrap` gives you full control to create as many independent logger instances as needed.
## Related [#related]
* [getLogger](./index.md) - Singleton logger factory
* [callsitePlugin](../plugins/callsite.md) - Source location tracking
* [environmentPlugin](../plugins/environment.md) - Server/browser context
* [prettyTransport](../transports/pretty.md) - Pretty console output
* [structuredTransport](../transports/structured.md) - JSON output
* [LogLayer Plugin System](https://loglayer.dev/configuration.html#plugin-system) - Upstream documentation
# getLogger (/docs/packages/logger/default)
## Usage [#usage]
```typescript
import { getLogger } from '@accelint/logger';
const logger = getLogger({
enabled: true,
env: process.env.NODE_ENV as 'production' | 'development',
level: 'info',
prefix: '[MyApp]',
});
logger.info('Application started');
logger.withMetadata({ userId: 123 }).warn('Token expiring soon');
```
## Reference [#reference]
```typescript
function getLogger(opts: LoggerOptions): LogLayer
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ----------------- | ------------------------------- | -------------------------------------------------------------------------- |
| `opts` | `LoggerOptions` | Logger configuration options |
| `opts.enabled` | `boolean` | Whether logging is active; `false` makes all calls no-ops |
| `opts.level` | `LogLevel` | Minimum log level to output (default: `'debug'`) |
| `opts.env` | `'production' \| 'development'` | Runtime environment; controls server detection (default: `'development'`) |
| `opts.pretty` | `boolean` | Use pretty console output; `false` emits structured JSON (default: `true`) |
| `opts.prefix` | `string` | String prepended to all log messages (default: `''`) |
| `opts.plugins` | `LogLayerPlugin[]` | Additional plugins applied after the built-in ones |
| `opts.transports` | `LogLayerTransport[]` | Custom transports that replace the default console transport |
| `opts.groups` | `LogGroupsConfig` | Named group configuration for conditional group logging |
### Returns [#returns]
Returns a configured LogLayer instance with the following built-in features:
* **Callsite tracking** - Adds source file location to every log entry
* **Environment detection** - Adds server/browser context to every log entry
* **Error serialization** - Automatically serializes Error objects via serialize-error
* **One-way log level manager** - Log level can only be raised (made more restrictive) after initialization
> **Good to know:** This function implements the singleton pattern. The first call creates and configures the logger with the provided options. All subsequent calls return the same instance and ignore new options. If you need multiple independent logger instances, use [`bootstrap`](./bootstrap.md) directly.
## Examples [#examples]
### Example: Basic application logger [#example-basic-application-logger]
```typescript
import { getLogger } from '@accelint/logger';
const logger = getLogger({
enabled: true,
env: process.env.NODE_ENV as 'production' | 'development',
level: 'info',
prefix: '[API]',
});
logger.info('Server listening', { port: 3000 });
logger.error('Request failed', { statusCode: 500, path: '/api/users' });
```
### Example: Development logger with debug output [#example-development-logger-with-debug-output]
```typescript
import { getLogger, DEBUG } from '@accelint/logger';
const logger = getLogger({
enabled: true,
level: DEBUG,
env: 'development',
pretty: true,
});
logger.debug('Request received', {
method: 'POST',
path: '/api/auth/login',
headers: { 'content-type': 'application/json' },
});
```
### Example: Production logger with structured JSON [#example-production-logger-with-structured-json]
```typescript
import { getLogger, WARN } from '@accelint/logger';
const logger = getLogger({
enabled: true,
level: WARN,
env: 'production',
pretty: false, // Outputs JSON for log aggregation
});
logger.warn('High memory usage', {
memoryUsage: process.memoryUsage(),
threshold: 0.8,
});
```
### Example: Logger with metadata context [#example-logger-with-metadata-context]
```typescript
import { getLogger } from '@accelint/logger';
const logger = getLogger({ enabled: true });
// Add context that persists across log calls
const requestLogger = logger.withMetadata({
requestId: 'req_abc123',
userId: 'usr_456',
});
requestLogger.info('Processing request');
requestLogger.info('Request completed');
// Both logs include requestId and userId
```
### Example: Disabling logging entirely [#example-disabling-logging-entirely]
```typescript
import { getLogger } from '@accelint/logger';
const logger = getLogger({
enabled: false, // All log calls become no-ops
level: 'debug',
});
logger.info('This will not log');
logger.error('Neither will this');
```
### Example: Custom plugins [#example-custom-plugins]
```typescript
import { getLogger } from '@accelint/logger';
import type { LogLayerPlugin } from '@loglayer/shared';
const performancePlugin: LogLayerPlugin = {
id: 'performance',
onBeforeDataOut({ data }) {
return {
...data,
timestamp: Date.now(),
memory: process.memoryUsage().heapUsed,
};
},
};
const logger = getLogger({
enabled: true,
plugins: [performancePlugin],
});
logger.info('Custom plugin data included in every log');
```
### Example: Multiple custom transports [#example-multiple-custom-transports]
```typescript
import { getLogger, prettyTransport, structuredTransport } from '@accelint/logger';
// Log to console (pretty) and JSON (for log aggregation)
const logger = getLogger({
enabled: true,
transports: [
prettyTransport({ level: 'debug' }),
structuredTransport({ level: 'info' }),
],
});
logger.debug('Only in pretty console');
logger.info('In both pretty console and JSON');
```
### Example: Log groups for conditional logging [#example-log-groups-for-conditional-logging]
```typescript
import { getLogger } from '@accelint/logger';
const logger = getLogger({
enabled: true,
groups: {
database: { enabled: true },
cache: { enabled: true },
network: { enabled: false }, // Network logs disabled
},
});
logger.withGroup('database').info('Query executed'); // Logs
logger.withGroup('cache').info('Cache hit'); // Logs
logger.withGroup('network').info('HTTP request'); // Does not log
```
### Example: Singleton behavior [#example-singleton-behavior]
```typescript
import { getLogger } from '@accelint/logger';
// First call: creates logger with these options
const logger1 = getLogger({ enabled: true, level: 'debug' });
// Second call: returns same instance, ignores new options
const logger2 = getLogger({ enabled: true, level: 'error' });
console.log(logger1 === logger2); // true
// Both references point to the same logger instance configured with level: 'debug'
```
### Example: Module-specific prefix [#example-module-specific-prefix]
```typescript
import { getLogger } from '@accelint/logger';
const logger = getLogger({
enabled: true,
prefix: '[AuthService]',
});
logger.info('User authenticated'); // [AuthService] User authenticated
logger.error('Authentication failed'); // [AuthService] Authentication failed
```
> **Good to know:** The logger automatically includes callsite information (file:line:column) in the log data, making it easy to trace where log calls originate. This feature uses the `callsitePlugin` which is enabled by default.
## Related [#related]
* [bootstrap](./bootstrap.md) - Create independent logger instances (bypasses singleton)
* [callsitePlugin](../plugins/callsite.md) - Source location tracking
* [environmentPlugin](../plugins/environment.md) - Server/browser context
* [prettyTransport](../transports/pretty.md) - Pretty console output
* [structuredTransport](../transports/structured.md) - JSON output
* [LogLayer Configuration](https://loglayer.dev/configuration.html) - Upstream documentation
# callsitePlugin (/docs/packages/logger/plugins/callsite)
## Usage [#usage]
```typescript
import { callsitePlugin } from '@accelint/logger/plugins/callsite';
const plugin = callsitePlugin({ isProductionEnv: false });
// Log output will include: callSite: "src/services/user.ts:42:5"
```
## Reference [#reference]
```typescript
function callsitePlugin(options: CallsitePluginOptions): LogLayerPlugin
type CallsitePluginOptions = LogLayerPluginParams & {
isProductionEnv: boolean;
}
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ------------------------- | ----------------------- | ------------------------------------------------ |
| `options` | `CallsitePluginOptions` | Plugin configuration options |
| `options.isProductionEnv` | `boolean` | Reserved for future use; currently has no effect |
| `options.id` | `string` | Optional plugin ID |
| `options.disabled` | `boolean` | Optional flag to disable the plugin |
### Returns [#returns]
Returns a LogLayer plugin instance that automatically captures file, line number, and column where each log call originates, adding a `callSite` property to the log data.
### How It Works [#how-it-works]
The plugin analyzes the JavaScript call stack to locate the frame where the log method (`.info()`, `.error()`, etc.) was called. It then extracts:
* File path (or eval origin in bundled environments)
* Line number
* Column number
The result is formatted as `file:line:column` and included in every log entry.
> **Good to know:** This plugin is enabled by default in both `getLogger` and `bootstrap`. The callsite resolution handles various runtime environments including development builds with sourcemaps, production bundles, server contexts, and browser contexts.
## Examples [#examples]
### Example: Basic callsite tracking [#example-basic-callsite-tracking]
```typescript
import { bootstrap, callsitePlugin } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
plugins: [callsitePlugin({ isProductionEnv: false })],
});
logger.info('User logged in');
// Output includes: { callSite: "src/auth/login.ts:23:8", message: "User logged in" }
```
### Example: Development vs. production [#example-development-vs-production]
```typescript
import { bootstrap, callsitePlugin } from '@accelint/logger';
const isProduction = process.env.NODE_ENV === 'production';
const logger = bootstrap({
enabled: true,
plugins: [callsitePlugin({ isProductionEnv: isProduction })],
});
logger.error('Something went wrong');
// callSite helps trace the exact source location in both environments
```
### Example: Disabling callsite tracking [#example-disabling-callsite-tracking]
```typescript
import { bootstrap, callsitePlugin } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
plugins: [
callsitePlugin({
isProductionEnv: false,
disabled: true, // Disable callsite tracking
}),
],
});
logger.info('No callSite in output');
```
### Example: Custom plugin ID [#example-custom-plugin-id]
```typescript
import { bootstrap, callsitePlugin } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
plugins: [
callsitePlugin({
id: 'my-callsite-tracker',
isProductionEnv: false,
}),
],
});
```
### Example: Callsite in structured logs [#example-callsite-in-structured-logs]
```typescript
import { bootstrap, callsitePlugin } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
pretty: false, // JSON output
plugins: [callsitePlugin({ isProductionEnv: false })],
});
logger.error('Database connection failed', { error: new Error('timeout') });
// JSON output:
// {
// "level": "error",
// "message": "Database connection failed",
// "callSite": "src/db/connection.ts:67:12",
// "error": { ... },
// "server": true
// }
```
### Example: Tracing errors across modules [#example-tracing-errors-across-modules]
```typescript
// src/services/payment.ts
import { getLogger } from '@accelint/logger';
const logger = getLogger({ enabled: true });
export function processPayment(amount: number) {
logger.info('Processing payment', { amount });
// callSite: "src/services/payment.ts:8:10"
if (amount <= 0) {
logger.error('Invalid amount', { amount });
// callSite: "src/services/payment.ts:12:12"
throw new Error('Amount must be positive');
}
}
```
### Example: Combining with other plugins [#example-combining-with-other-plugins]
```typescript
import { bootstrap, callsitePlugin } from '@accelint/logger';
import type { LogLayerPlugin } from '@loglayer/shared';
const timestampPlugin: LogLayerPlugin = {
id: 'timestamp',
onBeforeDataOut({ data }) {
return { ...data, timestamp: Date.now() };
},
};
const logger = bootstrap({
enabled: true,
plugins: [
callsitePlugin({ isProductionEnv: false }),
timestampPlugin,
],
});
logger.info('Multiple plugins active');
// Output includes: { callSite: "...", timestamp: 1234567890, ... }
```
> **Good to know:** Callsite resolution is implemented using the [callsites](https://www.npmjs.com/package/callsites) package. It searches the stack for frames matching log level method names (`info`, `warn`, `error`, etc.) and returns the frame immediately following, which represents the actual call location.
## Related [#related]
* [environmentPlugin](./environment.md) - Adds server/browser context
* [getLogger](../default/index.md) - Includes callsitePlugin by default
* [bootstrap](../default/bootstrap.md) - Includes callsitePlugin by default
* [LogLayer Plugin System](https://loglayer.dev/configuration.html#plugin-system) - Upstream documentation
# environmentPlugin (/docs/packages/logger/plugins/environment)
## Usage [#usage]
```typescript
import { environmentPlugin } from '@accelint/logger/plugins/environment';
const plugin = environmentPlugin({
isServer: typeof window === 'undefined',
isProductionEnv: false,
});
// Log output will include: server: true (or false in browser)
```
## Reference [#reference]
```typescript
function environmentPlugin(options: EnvironmentPluginOptions): LogLayerPlugin
type EnvironmentPluginOptions = LogLayerPluginParams & {
isServer: boolean;
isProductionEnv: boolean;
}
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ------------------------- | -------------------------- | -------------------------------------------------------------------------- |
| `options` | `EnvironmentPluginOptions` | Plugin configuration options |
| `options.isServer` | `boolean` | True when running in Node.js environment (`typeof window === 'undefined'`) |
| `options.isProductionEnv` | `boolean` | Reserved for future use; currently has no effect |
| `options.id` | `string` | Optional plugin ID |
| `options.disabled` | `boolean` | Optional flag to disable the plugin |
### Returns [#returns]
Returns a LogLayer plugin instance that adds a `server` boolean property to all log output, indicating whether the log originated from a server or browser context.
> **Good to know:** This plugin is enabled by default in both `getLogger` and `bootstrap`. The `isServer` flag is automatically determined by checking `typeof window === 'undefined'`.
## Examples [#examples]
### Example: Basic environment detection [#example-basic-environment-detection]
```typescript
import { bootstrap, environmentPlugin } from '@accelint/logger';
const isServer = typeof window === 'undefined';
const logger = bootstrap({
enabled: true,
plugins: [
environmentPlugin({
isServer,
isProductionEnv: false,
}),
],
});
logger.info('Application started');
// Server: { server: true, message: "Application started" }
// Browser: { server: false, message: "Application started" }
```
### Example: Universal/isomorphic code logging [#example-universalisomorphic-code-logging]
```typescript
import { getLogger } from '@accelint/logger';
const logger = getLogger({
enabled: true,
env: process.env.NODE_ENV as 'production' | 'development',
});
export function fetchUserData(userId: string) {
logger.info('Fetching user data', { userId });
// Automatically tagged with server: true/false
// ... fetch logic
}
// Same code runs on server and client
// Logs clearly indicate execution context
```
### Example: Filtering server-only logs [#example-filtering-server-only-logs]
```typescript
import { bootstrap, environmentPlugin } from '@accelint/logger';
const isServer = typeof window === 'undefined';
const logger = bootstrap({
enabled: true,
plugins: [
environmentPlugin({
isServer,
isProductionEnv: false,
}),
],
});
// In log aggregation, filter by server: true
if (isServer) {
logger.info('Server-side operation', { pid: process.pid });
}
```
### Example: Next.js server and client logging [#example-nextjs-server-and-client-logging]
```typescript
import { getLogger } from '@accelint/logger';
const logger = getLogger({
enabled: true,
env: process.env.NODE_ENV as 'production' | 'development',
});
// Server Component
export async function ServerComponent() {
logger.info('Rendering on server');
// Output: { server: true, message: "Rendering on server" }
// ... component logic
}
// Client Component
'use client';
export function ClientComponent() {
logger.info('Rendering in browser');
// Output: { server: false, message: "Rendering in browser" }
// ... component logic
}
```
### Example: Disabling environment plugin [#example-disabling-environment-plugin]
```typescript
import { bootstrap, environmentPlugin } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
plugins: [
environmentPlugin({
isServer: true,
isProductionEnv: false,
disabled: true, // Disable environment tagging
}),
],
});
logger.info('No server field in output');
```
### Example: Custom plugin ID [#example-custom-plugin-id]
```typescript
import { bootstrap, environmentPlugin } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
plugins: [
environmentPlugin({
id: 'my-env-detector',
isServer: typeof window === 'undefined',
isProductionEnv: false,
}),
],
});
```
### Example: Production environment detection [#example-production-environment-detection]
```typescript
import { bootstrap, environmentPlugin } from '@accelint/logger';
const isProduction = process.env.NODE_ENV === 'production';
const isServer = typeof window === 'undefined';
const logger = bootstrap({
enabled: true,
plugins: [
environmentPlugin({
isServer,
isProductionEnv: isProduction,
}),
],
});
// Currently isProductionEnv is reserved for future use
// The server field is always added to logs
```
### Example: Structured JSON with environment context [#example-structured-json-with-environment-context]
```typescript
import { bootstrap, environmentPlugin } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
pretty: false, // JSON output
plugins: [
environmentPlugin({
isServer: true,
isProductionEnv: false,
}),
],
});
logger.error('API request failed', { statusCode: 500 });
// JSON output:
// {
// "level": "error",
// "message": "API request failed",
// "server": true,
// "statusCode": 500,
// "callSite": "..."
// }
```
### Example: Combining with custom plugins [#example-combining-with-custom-plugins]
```typescript
import { bootstrap, environmentPlugin } from '@accelint/logger';
import type { LogLayerPlugin } from '@loglayer/shared';
const deploymentPlugin: LogLayerPlugin = {
id: 'deployment',
onBeforeDataOut({ data }) {
return {
...data,
region: process.env.AWS_REGION,
version: process.env.APP_VERSION,
};
},
};
const logger = bootstrap({
enabled: true,
plugins: [
environmentPlugin({
isServer: true,
isProductionEnv: true,
}),
deploymentPlugin,
],
});
logger.info('Deployment context included');
// Output: { server: true, region: "us-east-1", version: "1.2.3", ... }
```
### Example: Conditional logging based on environment [#example-conditional-logging-based-on-environment]
```typescript
import { getLogger } from '@accelint/logger';
const isServer = typeof window === 'undefined';
const logger = getLogger({ enabled: true });
function logEnvironmentSpecific() {
if (isServer) {
logger.info('Server-specific operation', { hostname: process.env.HOSTNAME });
} else {
logger.info('Client-specific operation', { userAgent: navigator.userAgent });
}
// Both automatically tagged with server: true/false
}
```
> **Good to know:** The `server` field is particularly useful in universal applications (Next.js, Remix, etc.) where the same code runs in both Node.js and browser contexts. It helps trace whether logs originated from server-side rendering, API routes, or client-side interactions.
## Related [#related]
* [callsitePlugin](./callsite.md) - Adds source location tracking
* [getLogger](../default/index.md) - Includes environmentPlugin by default
* [bootstrap](../default/bootstrap.md) - Includes environmentPlugin by default
* [LogLayer Plugin System](https://loglayer.dev/configuration.html#plugin-system) - Upstream documentation
# prettyTransport (/docs/packages/logger/transports/pretty)
## Usage [#usage]
```typescript
import { prettyTransport } from '@accelint/logger/transports/pretty';
const transport = prettyTransport({ level: 'debug' });
```
## Reference [#reference]
```typescript
function prettyTransport(options: PrettyTransportProps): LogLayerTransport
type PrettyTransportProps = {
level: LogLevel;
}
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------------- | ---------------------- | ------------------------------- |
| `options` | `PrettyTransportProps` | Transport configuration options |
| `options.level` | `LogLevel` | Minimum log level to output |
### Returns [#returns]
Returns a configured LogLayer transport instance that outputs formatted, colorized logs to the console using `message-only` view mode and browser runtime settings.
### Configuration Details [#configuration-details]
The transport is configured with:
* **viewMode**: `'message-only'` - Focuses on the message, minimizing visual clutter
* **runtime**: `'browser'` - Uses browser-style formatting for consistent output
* **includeDataInBrowserConsole**: `true` - Always includes log data in the output
> **Good to know:** This transport is the default when `pretty: true` (the default) in `getLogger` or `bootstrap`. It provides a good balance between readability and information density, even on the server.
## Examples [#examples]
### Example: Basic pretty transport [#example-basic-pretty-transport]
```typescript
import { bootstrap, prettyTransport } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
transports: [prettyTransport({ level: 'debug' })],
});
logger.info('User logged in', { userId: 'usr_123' });
// Console output:
// ℹ️ User logged in { userId: 'usr_123' }
```
### Example: Development logger with debug level [#example-development-logger-with-debug-level]
```typescript
import { bootstrap, prettyTransport, DEBUG } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
transports: [prettyTransport({ level: DEBUG })],
});
logger.trace('Not logged - below debug threshold');
logger.debug('Cache miss', { key: 'user:123' });
logger.info('Request completed', { duration: 42 });
```
### Example: Multiple transports with different levels [#example-multiple-transports-with-different-levels]
```typescript
import { bootstrap, prettyTransport, structuredTransport, DEBUG, WARN } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
transports: [
prettyTransport({ level: DEBUG }), // Console shows everything
structuredTransport({ level: WARN }), // JSON only for warnings/errors
],
});
logger.debug('Verbose debug info'); // Only in pretty console
logger.warn('Something concerning'); // In both transports
logger.error('Critical error'); // In both transports
```
### Example: Production logger with warning threshold [#example-production-logger-with-warning-threshold]
```typescript
import { bootstrap, prettyTransport, WARN } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
env: 'production',
transports: [prettyTransport({ level: WARN })],
});
logger.info('Not logged');
logger.warn('Token expiring soon'); // Logged
logger.error('Payment failed'); // Logged
```
### Example: Custom transport configuration for testing [#example-custom-transport-configuration-for-testing]
```typescript
import { bootstrap, prettyTransport } from '@accelint/logger';
import { describe, test, expect } from 'vitest';
describe('Payment service', () => {
test('should log payment events', () => {
const logger = bootstrap({
enabled: true,
transports: [prettyTransport({ level: 'info' })],
});
logger.info('Payment processed');
// Readable output for debugging test failures
});
});
```
### Example: Next.js development logger [#example-nextjs-development-logger]
```typescript
import { bootstrap, prettyTransport } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
env: 'development',
transports: [prettyTransport({ level: 'debug' })],
prefix: '[Next.js]',
});
logger.debug('API route called', { method: 'POST', path: '/api/users' });
// Console output:
// 🐛 [Next.js] API route called { method: 'POST', path: '/api/users' }
```
### Example: Error logging with stack traces [#example-error-logging-with-stack-traces]
```typescript
import { bootstrap, prettyTransport } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
transports: [prettyTransport({ level: 'error' })],
});
try {
throw new Error('Database connection failed');
} catch (error) {
logger.error('Critical error', { error });
// Pretty output includes serialized error with stack trace
}
```
### Example: Combining with external logging service [#example-combining-with-external-logging-service]
```typescript
import { bootstrap, prettyTransport } from '@accelint/logger';
import type { LogLayerTransport } from '@loglayer/shared';
const externalTransport: LogLayerTransport = {
log(level, message, data) {
fetch('https://logs.example.com/ingest', {
method: 'POST',
body: JSON.stringify({ level, message, data }),
});
},
};
const logger = bootstrap({
enabled: true,
transports: [
prettyTransport({ level: 'debug' }), // Local console
externalTransport, // Remote service
],
});
logger.info('Logged locally and remotely');
```
### Example: Conditional transport based on environment [#example-conditional-transport-based-on-environment]
```typescript
import { bootstrap, prettyTransport, structuredTransport } from '@accelint/logger';
const isDevelopment = process.env.NODE_ENV === 'development';
const logger = bootstrap({
enabled: true,
transports: [
isDevelopment
? prettyTransport({ level: 'debug' })
: structuredTransport({ level: 'warn' }),
],
});
logger.debug('Development-only debug info');
```
### Example: Using default transport implicitly [#example-using-default-transport-implicitly]
```typescript
import { getLogger } from '@accelint/logger';
// Pretty transport is used automatically when pretty: true (default)
const logger = getLogger({
enabled: true,
pretty: true,
level: 'info',
});
logger.info('Using default pretty transport');
```
> **Good to know:** The `message-only` view mode focuses output on the log message and data, hiding LogLayer's internal metadata. The `browser` runtime setting provides consistent colorized output across Node.js and browser environments.
## Related [#related]
* [structuredTransport](./structured.md) - JSON log transport
* [getLogger](../default/index.md) - Uses prettyTransport by default when `pretty: true`
* [bootstrap](../default/bootstrap.md) - Uses prettyTransport by default when `pretty: true`
* [LogLayer Transport Configuration](https://loglayer.dev/configuration.html#transport-configuration) - Upstream documentation
# structuredTransport (/docs/packages/logger/transports/structured)
## Usage [#usage]
```typescript
import { structuredTransport } from '@accelint/logger/transports/structured';
const transport = structuredTransport({ level: 'info' });
```
## Reference [#reference]
```typescript
function structuredTransport(options: StructuredTransportProps): StructuredTransport
type StructuredTransportProps = {
level: LogLevel;
}
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------------- | -------------------------- | ------------------------------- |
| `options` | `StructuredTransportProps` | Transport configuration options |
| `options.level` | `LogLevel` | Minimum log level to output |
### Returns [#returns]
Returns a configured LogLayer `StructuredTransport` instance that emits JSON-formatted log entries to `console`. Use when machine-readable log output is needed (e.g., production log aggregation pipelines).
> **Good to know:** This transport is the default when `pretty: false` in `getLogger` or `bootstrap`. It outputs JSON to the console, making logs easy to parse by log aggregation services like CloudWatch, Datadog, or Splunk.
## Examples [#examples]
### Example: Basic structured transport [#example-basic-structured-transport]
```typescript
import { bootstrap, structuredTransport } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
transports: [structuredTransport({ level: 'info' })],
});
logger.info('User logged in', { userId: 'usr_123' });
// Console output (JSON):
// {"level":"info","message":"User logged in","userId":"usr_123","server":true,"callSite":"..."}
```
### Example: Production logger with JSON output [#example-production-logger-with-json-output]
```typescript
import { bootstrap, structuredTransport, WARN } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
env: 'production',
transports: [structuredTransport({ level: WARN })],
});
logger.info('Not logged');
logger.warn('Token expiring soon', { userId: 'usr_123' });
logger.error('Payment failed', { orderId: 'ord_abc' });
// JSON output for warn and error only
```
### Example: CloudWatch-compatible logs [#example-cloudwatch-compatible-logs]
```typescript
import { bootstrap, structuredTransport } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
env: 'production',
transports: [structuredTransport({ level: 'info' })],
prefix: '',
});
logger.info('Lambda function invoked', {
requestId: 'req_123',
functionName: 'process-payment',
region: 'us-east-1',
});
// JSON output ingested by CloudWatch Logs
```
### Example: Multiple transports for development and production [#example-multiple-transports-for-development-and-production]
```typescript
import { bootstrap, prettyTransport, structuredTransport, DEBUG, INFO } from '@accelint/logger';
const isDevelopment = process.env.NODE_ENV === 'development';
const logger = bootstrap({
enabled: true,
transports: [
isDevelopment
? prettyTransport({ level: DEBUG })
: structuredTransport({ level: INFO }),
],
});
logger.debug('Development debug info');
logger.info('Production JSON log');
```
### Example: Dual output for debugging production [#example-dual-output-for-debugging-production]
```typescript
import { bootstrap, prettyTransport, structuredTransport, DEBUG, WARN } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
transports: [
prettyTransport({ level: DEBUG }), // Human-readable console
structuredTransport({ level: WARN }), // JSON for log aggregation
],
});
logger.debug('Debug info - pretty only');
logger.warn('Warning - both formats');
logger.error('Error - both formats');
```
### Example: Error logging with structured output [#example-error-logging-with-structured-output]
```typescript
import { bootstrap, structuredTransport } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
transports: [structuredTransport({ level: 'error' })],
});
try {
throw new Error('Database connection failed');
} catch (error) {
logger.error('Critical error', { error, timestamp: Date.now() });
// JSON output with serialized error
}
```
### Example: API request logging [#example-api-request-logging]
```typescript
import { bootstrap, structuredTransport } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
transports: [structuredTransport({ level: 'info' })],
});
export async function logRequest(req: Request, res: Response) {
logger.info('API request', {
method: req.method,
path: req.path,
statusCode: res.statusCode,
duration: res.responseTime,
userAgent: req.get('user-agent'),
});
// Structured JSON for analytics
}
```
### Example: Custom log aggregation transport [#example-custom-log-aggregation-transport]
```typescript
import { bootstrap, structuredTransport } from '@accelint/logger';
import type { LogLayerTransport } from '@loglayer/shared';
const datadogTransport: LogLayerTransport = {
log(level, message, data) {
fetch('https://http-intake.logs.datadoghq.com/v1/input', {
method: 'POST',
headers: {
'DD-API-KEY': process.env.DATADOG_API_KEY!,
'Content-Type': 'application/json',
},
body: JSON.stringify({
level,
message,
...data,
service: 'my-app',
ddsource: 'nodejs',
}),
});
},
};
const logger = bootstrap({
enabled: true,
transports: [
structuredTransport({ level: 'info' }), // Local console JSON
datadogTransport, // Datadog ingestion
],
});
logger.info('Logged to console and Datadog');
```
### Example: Next.js production logging [#example-nextjs-production-logging]
```typescript
import { bootstrap, structuredTransport, WARN } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
env: 'production',
transports: [structuredTransport({ level: WARN })],
prefix: '',
});
export default async function handler(req, res) {
logger.warn('API rate limit approaching', {
ip: req.socket.remoteAddress,
remaining: 10,
path: req.url,
});
// JSON output for Vercel log drains
}
```
### Example: Conditional structured output [#example-conditional-structured-output]
```typescript
import { getLogger } from '@accelint/logger';
const logger = getLogger({
enabled: true,
pretty: false, // Uses structuredTransport automatically
level: 'info',
});
logger.info('Structured JSON output', { event: 'app.started' });
```
### Example: Container logging [#example-container-logging]
```typescript
import { bootstrap, structuredTransport } from '@accelint/logger';
const logger = bootstrap({
enabled: true,
transports: [structuredTransport({ level: 'debug' })],
});
logger.info('Container started', {
containerId: process.env.HOSTNAME,
podName: process.env.POD_NAME,
namespace: process.env.NAMESPACE,
});
// JSON output captured by container runtime (Docker, Kubernetes)
```
### Example: Testing with structured logs [#example-testing-with-structured-logs]
```typescript
import { bootstrap, structuredTransport } from '@accelint/logger';
import { describe, test, expect, vi } from 'vitest';
describe('Payment service', () => {
test('should log structured payment data', () => {
const consoleSpy = vi.spyOn(console, 'log');
const logger = bootstrap({
enabled: true,
transports: [structuredTransport({ level: 'info' })],
});
logger.info('Payment processed', { orderId: 'ord_123', amount: 100 });
expect(consoleSpy).toHaveBeenCalledWith(
expect.stringContaining('"orderId":"ord_123"')
);
});
});
```
> **Good to know:** Structured logs include all metadata from plugins (callsite, environment, etc.) in the JSON output. This makes them ideal for querying and filtering in log aggregation systems.
## Related [#related]
* [prettyTransport](./pretty.md) - Pretty-printed console transport
* [getLogger](../default/index.md) - Uses structuredTransport when `pretty: false`
* [bootstrap](../default/bootstrap.md) - Uses structuredTransport when `pretty: false`
* [LogLayer Transport Configuration](https://loglayer.dev/configuration.html#transport-configuration) - Upstream documentation
# BroadcastChannel Mock (/docs/tooling/vitest-config/mocks/broadcast-channel)
Mock implementation of the BroadcastChannel API for testing browser-based messaging in Vitest. Simulates message broadcasting across channels with the same name.
## Usage [#usage]
```typescript
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { mockBroadcastChannel, resetMockBroadcastChannel } from '@accelint/vitest-config/mocks/broadcast-channel';
describe('BroadcastChannel tests', () => {
beforeEach(() => {
mockBroadcastChannel();
});
afterEach(() => {
resetMockBroadcastChannel();
});
it('broadcasts messages between channels', () => {
const channel1 = new BroadcastChannel('test');
const channel2 = new BroadcastChannel('test');
const handler = vi.fn();
channel2.addEventListener('message', handler);
channel1.postMessage({ data: 'hello' });
expect(handler).toHaveBeenCalled();
});
});
```
## Reference [#reference]
### mockBroadcastChannel [#mockbroadcastchannel]
```typescript
function mockBroadcastChannel(): void
```
Installs a mock BroadcastChannel implementation on `globalThis`. Call this in `beforeEach` or test setup to enable BroadcastChannel testing.
**Side effects:**
* Replaces `globalThis.BroadcastChannel` with mock implementation
* Creates internal channel registry for message routing
### resetMockBroadcastChannel [#resetmockbroadcastchannel]
```typescript
function resetMockBroadcastChannel(): void
```
Removes the mock implementation and clears all registered channels. Call this in `afterEach` to clean up after tests.
**Side effects:**
* Clears channel registry
* Deletes `globalThis.BroadcastChannel`
### Mock Interface [#mock-interface]
The mock BroadcastChannel implements:
```typescript
interface MockChannel {
name: string;
onmessage: ((event: MessageEvent) => void) | null;
onmessageerror: ((event: MessageEvent) => void) | null;
addEventListener: MockFunctionResult;
removeEventListener: MockFunctionResult;
postMessage: MockFunctionResult;
close: MockFunctionResult;
}
```
All methods are Vitest mock functions (`vi.fn()`), allowing assertion on calls and behavior.
## Examples [#examples]
### Example: Basic message passing [#example-basic-message-passing]
```typescript
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { mockBroadcastChannel, resetMockBroadcastChannel } from '@accelint/vitest-config/mocks/broadcast-channel';
describe('BroadcastChannel', () => {
beforeEach(() => {
mockBroadcastChannel();
});
afterEach(() => {
resetMockBroadcastChannel();
});
it('sends messages to other channels', () => {
const sender = new BroadcastChannel('app');
const receiver = new BroadcastChannel('app');
const handler = vi.fn();
receiver.addEventListener('message', handler);
sender.postMessage({ type: 'update', value: 42 });
expect(handler).toHaveBeenCalledWith(
expect.objectContaining({
data: { type: 'update', value: 42 },
})
);
});
});
```
### Example: Multiple listeners on same channel [#example-multiple-listeners-on-same-channel]
```typescript
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { mockBroadcastChannel, resetMockBroadcastChannel } from '@accelint/vitest-config/mocks/broadcast-channel';
describe('Multiple listeners', () => {
beforeEach(() => {
mockBroadcastChannel();
});
afterEach(() => {
resetMockBroadcastChannel();
});
it('broadcasts to all listeners', () => {
const channel = new BroadcastChannel('notifications');
const handler1 = vi.fn();
const handler2 = vi.fn();
channel.addEventListener('message', handler1);
channel.addEventListener('message', handler2);
channel.postMessage({ text: 'New notification' });
expect(handler1).toHaveBeenCalled();
expect(handler2).toHaveBeenCalled();
});
});
```
### Example: Isolated channel names [#example-isolated-channel-names]
```typescript
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { mockBroadcastChannel, resetMockBroadcastChannel } from '@accelint/vitest-config/mocks/broadcast-channel';
describe('Channel isolation', () => {
beforeEach(() => {
mockBroadcastChannel();
});
afterEach(() => {
resetMockBroadcastChannel();
});
it('does not broadcast across different channel names', () => {
const channel1 = new BroadcastChannel('app');
const channel2 = new BroadcastChannel('other');
const handler = vi.fn();
channel2.addEventListener('message', handler);
channel1.postMessage({ data: 'test' });
expect(handler).not.toHaveBeenCalled();
});
});
```
### Example: Using onmessage handler [#example-using-onmessage-handler]
```typescript
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { mockBroadcastChannel, resetMockBroadcastChannel } from '@accelint/vitest-config/mocks/broadcast-channel';
describe('onmessage handler', () => {
beforeEach(() => {
mockBroadcastChannel();
});
afterEach(() => {
resetMockBroadcastChannel();
});
it('calls onmessage when message received', () => {
const sender = new BroadcastChannel('chat');
const receiver = new BroadcastChannel('chat');
const messages: unknown[] = [];
receiver.onmessage = (event) => {
messages.push(event.data);
};
sender.postMessage({ text: 'Hello' });
sender.postMessage({ text: 'World' });
expect(messages).toEqual([
{ text: 'Hello' },
{ text: 'World' },
]);
});
});
```
### Example: Asserting postMessage calls [#example-asserting-postmessage-calls]
```typescript
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { mockBroadcastChannel, resetMockBroadcastChannel } from '@accelint/vitest-config/mocks/broadcast-channel';
describe('Message assertions', () => {
beforeEach(() => {
mockBroadcastChannel();
});
afterEach(() => {
resetMockBroadcastChannel();
});
it('tracks postMessage calls', () => {
const channel = new BroadcastChannel('events');
channel.postMessage({ event: 'start' });
channel.postMessage({ event: 'progress', value: 50 });
channel.postMessage({ event: 'complete' });
expect(channel.postMessage).toHaveBeenCalledTimes(3);
expect(channel.postMessage).toHaveBeenNthCalledWith(2, {
event: 'progress',
value: 50,
});
});
});
```
### Example: Setup file integration [#example-setup-file-integration]
```typescript
// tests/setup.ts
import { beforeEach, afterEach } from 'vitest';
import { mockBroadcastChannel, resetMockBroadcastChannel } from '@accelint/vitest-config/mocks/broadcast-channel';
beforeEach(() => {
mockBroadcastChannel();
});
afterEach(() => {
resetMockBroadcastChannel();
});
```
```typescript
// vitest.config.ts
import { defineConfig, mergeConfig } from 'vitest/config';
import baseConfig from '@accelint/vitest-config/dom';
export default mergeConfig(
baseConfig,
defineConfig({
test: {
setupFiles: ['./tests/setup.ts'],
},
}),
);
```
> **Good to know:** The mock simulates message broadcasting by routing messages to all channels with matching names. Messages are delivered synchronously within the same test context, making assertions straightforward.
## Related [#related]
* [dom](../dom.mdx) - Vitest configuration for React/DOM testing
* [no-dom](../no-dom.mdx) - Base Vitest configuration
* [BroadcastChannel API](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel) - MDN documentation
# Accordion (/docs/toolkits/design-toolkit/components/accordion)
## Usage [#usage]
```tsx
import {
Accordion,
AccordionHeader,
AccordionTrigger,
AccordionPanel
} from '@accelint/design-toolkit';
export function MyComponent() {
return (
<Accordion>
<AccordionHeader>
<AccordionTrigger>Section Title</AccordionTrigger>
</AccordionHeader>
<AccordionPanel>
<p>Content goes here</p>
</AccordionPanel>
</Accordion>
);
}
```
## Reference [#reference]
### Accordion [#accordion]
```typescript
interface AccordionProps extends DisclosureProps {
variant?: 'compact' | 'cozy';
isDisabled?: boolean;
children?: React.ReactNode;
className?: string | ((props: RenderProps) => string);
}
```
#### Props [#props]
| Prop | Type | Default | Required |
| ------------ | ------------------------------------------ | -------- | -------- |
| `variant` | `'compact' \| 'cozy'` | `'cozy'` | No |
| `isDisabled` | `boolean` | `false` | No |
| `children` | `React.ReactNode` | - | Yes |
| `className` | `string \| (props: RenderProps) => string` | - | No |
#### `variant` [#variant]
Visual density variant:
* `cozy` - Spacious layout with larger touch targets (default)
* `compact` - Dense layout for information-heavy interfaces
### AccordionGroup [#accordiongroup]
Container component for grouping multiple accordions with shared configuration.
```typescript
interface AccordionGroupProps extends DisclosureGroupProps {
variant?: 'compact' | 'cozy';
isDisabled?: boolean;
children?: React.ReactNode;
className?: string | ((props: RenderProps) => string);
}
```
#### Props [#props-1]
| Prop | Type | Default | Required |
| ------------ | ------------------------------------------ | -------- | -------- |
| `variant` | `'compact' \| 'cozy'` | `'cozy'` | No |
| `isDisabled` | `boolean` | `false` | No |
| `children` | `React.ReactNode` | - | Yes |
| `className` | `string \| (props: RenderProps) => string` | - | No |
### AccordionHeader [#accordionheader]
Header component that provides context and styling for the accordion trigger.
```typescript
interface AccordionHeaderProps extends ComponentPropsWithRef<'header'> {
children?: React.ReactNode;
className?: string;
}
```
### AccordionTrigger [#accordiontrigger]
Clickable button that toggles the accordion panel visibility. Includes an animated chevron icon.
```typescript
interface AccordionTriggerProps extends Omit<ComponentPropsWithRef<typeof Heading>, 'className'> {
children?: React.ReactNode;
classNames?: {
heading?: string;
trigger?: string | ((props: ButtonRenderProps) => string);
};
}
```
### AccordionPanel [#accordionpanel]
Collapsible content panel that is shown or hidden when the trigger is activated.
```typescript
interface AccordionPanelProps extends DisclosurePanelProps {
children?: React.ReactNode;
className?: string | ((props: RenderProps) => string);
}
```
### Inherited Props [#inherited-props]
Accordion inherits all props from React Aria's `Disclosure` component, including:
* `defaultExpanded` - Whether the accordion is expanded by default
* `isExpanded` - Controlled expanded state
* `onExpandedChange` - Called when the expanded state changes
AccordionGroup inherits all props from React Aria's `DisclosureGroup` component, including:
* `allowsMultipleExpanded` - Allow multiple accordions to be expanded simultaneously
See [React Aria Disclosure](https://react-spectrum.adobe.com/react-aria/Disclosure.html) for full API reference.
## Examples [#examples]
### Example: Basic accordion [#example-basic-accordion]
```tsx
import {
Accordion,
AccordionHeader,
AccordionTrigger,
AccordionPanel
} from '@accelint/design-toolkit';
<Accordion>
<AccordionHeader>
<AccordionTrigger>Details</AccordionTrigger>
</AccordionHeader>
<AccordionPanel>
<p>This content can be expanded and collapsed.</p>
</AccordionPanel>
</Accordion>
```
### Example: Compact variant [#example-compact-variant]
```tsx
import {
Accordion,
AccordionHeader,
AccordionTrigger,
AccordionPanel
} from '@accelint/design-toolkit';
<Accordion variant="compact">
<AccordionHeader>
<AccordionTrigger>Compact Section</AccordionTrigger>
</AccordionHeader>
<AccordionPanel>
<p>Dense layout for information-heavy interfaces.</p>
</AccordionPanel>
</Accordion>
```
### Example: With icon [#example-with-icon]
```tsx
import {
Accordion,
AccordionHeader,
AccordionTrigger,
AccordionPanel,
Icon
} from '@accelint/design-toolkit';
import { Document } from '@accelint/icons';
<Accordion>
<AccordionHeader>
<AccordionTrigger>
<Icon><Document /></Icon>
Document Settings
</AccordionTrigger>
</AccordionHeader>
<AccordionPanel>
<p>Configure document preferences here.</p>
</AccordionPanel>
</Accordion>
```
### Example: With menu actions [#example-with-menu-actions]
```tsx
import {
Accordion,
AccordionHeader,
AccordionTrigger,
AccordionPanel,
Button,
Menu,
MenuItem,
MenuTrigger
} from '@accelint/design-toolkit';
<Accordion>
<AccordionHeader>
<AccordionTrigger>Section with Actions</AccordionTrigger>
<MenuTrigger>
<Button />
<Menu>
<MenuItem>Edit</MenuItem>
<MenuItem>Delete</MenuItem>
</Menu>
</MenuTrigger>
</AccordionHeader>
<AccordionPanel>
<p>Content with additional menu actions.</p>
</AccordionPanel>
</Accordion>
```
> **Good to know:** The `Button` in the `AccordionHeader` automatically receives kebab menu icon styling through context.
### Example: Controlled state [#example-controlled-state]
```tsx
import { useState } from 'react';
import {
Accordion,
AccordionHeader,
AccordionTrigger,
AccordionPanel
} from '@accelint/design-toolkit';
function ControlledAccordion() {
const [isExpanded, setIsExpanded] = useState(false);
return (
<Accordion
isExpanded={isExpanded}
onExpandedChange={setIsExpanded}
>
<AccordionHeader>
<AccordionTrigger>Controlled Section</AccordionTrigger>
</AccordionHeader>
<AccordionPanel>
<p>Expanded state is controlled externally.</p>
</AccordionPanel>
</Accordion>
);
}
```
### Example: Grouped accordions [#example-grouped-accordions]
```tsx
import {
AccordionGroup,
Accordion,
AccordionHeader,
AccordionTrigger,
AccordionPanel
} from '@accelint/design-toolkit';
<AccordionGroup variant="compact">
<Accordion>
<AccordionHeader>
<AccordionTrigger>First Section</AccordionTrigger>
</AccordionHeader>
<AccordionPanel>
<p>First section content.</p>
</AccordionPanel>
</Accordion>
<Accordion>
<AccordionHeader>
<AccordionTrigger>Second Section</AccordionTrigger>
</AccordionHeader>
<AccordionPanel>
<p>Second section content.</p>
</AccordionPanel>
</Accordion>
<Accordion>
<AccordionHeader>
<AccordionTrigger>Third Section</AccordionTrigger>
</AccordionHeader>
<AccordionPanel>
<p>Third section content.</p>
</AccordionPanel>
</Accordion>
</AccordionGroup>
```
### Example: Disabled state [#example-disabled-state]
```tsx
import {
Accordion,
AccordionHeader,
AccordionTrigger,
AccordionPanel
} from '@accelint/design-toolkit';
<Accordion isDisabled>
<AccordionHeader>
<AccordionTrigger>Disabled Section</AccordionTrigger>
</AccordionHeader>
<AccordionPanel>
<p>This content cannot be expanded.</p>
</AccordionPanel>
</Accordion>
```
## Related [#related]
* [Dialog](../dialog/index.md) - Modal dialog component for layered content
* [Tabs](../tabs/index.md) - Tab panel component for organizing content in named sections
* [Button](../button/index.md) - Button component used in accordion headers
# ActionBar (/docs/toolkits/design-toolkit/components/action-bar)
## Usage [#usage]
```tsx
import { ActionBar, Button, Icon } from '@accelint/design-toolkit';
import { Copy, Delete } from '@accelint/icons';
export function MyComponent() {
return (
<ActionBar>
<Button><Icon><Copy /></Icon></Button>
<Button><Icon><Delete /></Icon></Button>
</ActionBar>
);
}
```
## Reference [#reference]
```typescript
interface ActionBarProps extends HTMLAttributes<HTMLDivElement> {
elevation?: 'flat' | 'overlay' | 'raised';
size?: 'medium' | 'small';
children?: React.ReactNode;
className?: string;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ----------- | --------------------------------- | ----------- | -------- |
| `elevation` | `'flat' \| 'overlay' \| 'raised'` | `'overlay'` | No |
| `size` | `'medium' \| 'small'` | `'medium'` | No |
| `children` | `React.ReactNode` | - | Yes |
| `className` | `string` | - | No |
#### `elevation` [#elevation]
Visual elevation style for the action bar:
* `flat` - No shadow, embedded appearance for use within panels or cards
* `overlay` - Subtle shadow, floating appearance (default)
* `raised` - Prominent shadow for primary toolbars
#### `size` [#size]
Controls the size of action buttons within the bar. The ActionBar automatically applies `variant="icon"` to all child Button and ToggleButton components through context.
## Examples [#examples]
### Example: Basic action bar [#example-basic-action-bar]
```tsx
import { ActionBar, Button, Icon } from '@accelint/design-toolkit';
import { Copy, Paste, Cut } from '@accelint/icons';
<ActionBar>
<Button onPress={() => console.log('Copy')}>
<Icon><Copy /></Icon>
</Button>
<Button onPress={() => console.log('Paste')}>
<Icon><Paste /></Icon>
</Button>
<Button onPress={() => console.log('Cut')}>
<Icon><Cut /></Icon>
</Button>
</ActionBar>
```
### Example: Text editor toolbar [#example-text-editor-toolbar]
```tsx
import { ActionBar, ToggleButton, Icon } from '@accelint/design-toolkit';
import { Bold, Italic, Underline } from '@accelint/icons';
<ActionBar>
<ToggleButton>
<Icon><Bold /></Icon>
</ToggleButton>
<ToggleButton>
<Icon><Italic /></Icon>
</ToggleButton>
<ToggleButton>
<Icon><Underline /></Icon>
</ToggleButton>
</ActionBar>
```
### Example: Flat elevation [#example-flat-elevation]
```tsx
import { ActionBar, Button, Icon } from '@accelint/design-toolkit';
import { Settings, Help } from '@accelint/icons';
<ActionBar elevation="flat">
<Button><Icon><Settings /></Icon></Button>
<Button><Icon><Help /></Icon></Button>
</ActionBar>
```
### Example: Raised elevation [#example-raised-elevation]
```tsx
import { ActionBar, Button, Icon } from '@accelint/design-toolkit';
import { Save, Upload, Download } from '@accelint/icons';
<ActionBar elevation="raised">
<Button><Icon><Save /></Icon></Button>
<Button><Icon><Upload /></Icon></Button>
<Button><Icon><Download /></Icon></Button>
</ActionBar>
```
### Example: Small size [#example-small-size]
```tsx
import { ActionBar, Button, Icon } from '@accelint/design-toolkit';
import { Zoom In, ZoomOut } from '@accelint/icons';
<ActionBar size="small">
<Button><Icon><ZoomIn /></Icon></Button>
<Button><Icon><ZoomOut /></Icon></Button>
</ActionBar>
```
### Example: With accessibility labels [#example-with-accessibility-labels]
```tsx
import { ActionBar, Button, Icon } from '@accelint/design-toolkit';
import { Copy, Delete } from '@accelint/icons';
<ActionBar>
<Button aria-label="Copy to clipboard">
<Icon><Copy /></Icon>
</Button>
<Button aria-label="Delete item">
<Icon><Delete /></Icon>
</Button>
</ActionBar>
```
> **Good to know:** Always provide `aria-label` props on icon-only buttons to ensure accessibility for screen reader users.
## Related [#related]
* [Button](../button/index.md) - Button component for actions
* [Icon](../icon/index.md) - Icon component for visual indicators
# Audio (/docs/toolkits/design-toolkit/components/audio)
## Usage [#usage]
```tsx
import { Audio } from '@accelint/design-toolkit';
export function MyComponent() {
return <Audio src="audio.mp3" title="My Audio File" />;
}
```
## Reference [#reference]
```typescript
interface AudioProps extends Omit<ComponentPropsWithRef<'audio'>, 'children' | 'onEnded' | 'onTimeUpdate' | 'onError' | 'src' | 'className'> {
src: string;
title?: string;
isDisabled?: boolean;
children?: React.ReactNode;
classNames?: {
container?: string;
title?: string;
mediaControls?: string;
timeRow?: string;
controlsRow?: string;
};
onEnded?: () => void;
onTimeUpdate?: (currentTime: number) => void;
onError?: (error: MediaError) => void;
playbackRates?: number[];
noHotkeys?: boolean;
hotkeys?: Record<string, string>;
noVolumePref?: boolean;
noMutedPref?: boolean;
lang?: string;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| --------------- | ---------------------------------- | ------------ | -------- |
| `src` | `string` | - | Yes |
| `title` | `string` | - | No |
| `isDisabled` | `boolean` | `false` | No |
| `children` | `React.ReactNode` | - | No |
| `classNames` | `object` | - | No |
| `autoPlay` | `boolean` | `false` | No |
| `loop` | `boolean` | `false` | No |
| `muted` | `boolean` | `false` | No |
| `preload` | `'none' \| 'metadata' \| 'auto'` | `'metadata'` | No |
| `crossOrigin` | `'anonymous' \| 'use-credentials'` | - | No |
| `playbackRates` | `number[]` | `[1, 2, 3]` | No |
| `onEnded` | `() => void` | - | No |
| `onTimeUpdate` | `(currentTime: number) => void` | - | No |
| `onError` | `(error: MediaError) => void` | - | No |
| `noHotkeys` | `boolean` | `false` | No |
| `noVolumePref` | `boolean` | `false` | No |
| `noMutedPref` | `boolean` | `false` | No |
#### `src` [#src]
Audio source URL. Must be accessible to the browser. If loading from a different origin, ensure the server sends appropriate CORS headers (`Access-Control-Allow-Origin`) or use the `crossOrigin` prop.
#### `crossOrigin` [#crossorigin]
CORS setting required when loading audio from a different origin that requires credentials or when using canvas to analyze audio. Without proper CORS configuration, the audio may fail to load.
#### `playbackRates` [#playbackrates]
Array of playback speed multipliers. Only positive finite numbers are accepted; invalid values are filtered out.
#### `classNames` [#classnames]
Custom class names for sub-elements:
* `container` - The outer MediaController wrapper
* `title` - The title row element
* `mediaControls` - The controls container
* `timeRow` - The time display and seek bar row
* `controlsRow` - The playback controls row
### Default Controls [#default-controls]
When no `children` are provided, the Audio component renders a complete control layout:
* Time display (current time / duration)
* Seek bar (TimeRange)
* Volume controls (mute button + volume slider)
* Playback controls (seek backward, play/pause, seek forward)
* Playback rate button
### Custom Controls [#custom-controls]
Pass children to render custom controls using the MediaControls sub-components:
* `PlayButton` - Play/pause toggle
* `MuteButton` - Mute/unmute toggle
* `SeekButton` - Skip forward/backward
* `TimeDisplay` - Current time or duration
* `TimeRange` - Seek bar
* `VolumeSlider` - Volume control
* `PlaybackRateButton` - Playback speed selector
## Examples [#examples]
### Example: Basic audio player [#example-basic-audio-player]
```tsx
import { Audio } from '@accelint/design-toolkit';
<Audio src="podcast.mp3" title="Episode 42: TypeScript Deep Dive" />
```
### Example: Autoplay and loop [#example-autoplay-and-loop]
```tsx
import { Audio } from '@accelint/design-toolkit';
<Audio
src="background-music.mp3"
autoPlay
loop
muted
/>
```
### Example: With event callbacks [#example-with-event-callbacks]
```tsx
import { Audio } from '@accelint/design-toolkit';
<Audio
src="audio.mp3"
title="My Audio File"
onPlay={() => console.log('Playing')}
onPause={() => console.log('Paused')}
onEnded={() => console.log('Ended')}
onTimeUpdate={(time) => console.log('Current time:', time)}
/>
```
### Example: Custom playback rates [#example-custom-playback-rates]
```tsx
import { Audio } from '@accelint/design-toolkit';
<Audio
src="lecture.mp3"
playbackRates={[0.5, 0.75, 1, 1.25, 1.5, 2]}
/>
```
### Example: Loading from external origin [#example-loading-from-external-origin]
```tsx
import { Audio } from '@accelint/design-toolkit';
<Audio
src="https://example.com/audio.mp3"
crossOrigin="anonymous"
onError={(error) => {
console.error('Failed to load audio:', error);
}}
/>
```
> **Good to know:** When loading audio from a different origin, the server must send CORS headers. Without them, the audio will fail to load silently.
### Example: Custom controls layout [#example-custom-controls-layout]
```tsx
import {
Audio,
PlayButton,
TimeRange
} from '@accelint/design-toolkit';
<Audio src="audio.mp3">
<PlayButton />
<TimeRange />
</Audio>
```
### Example: Minimal controls [#example-minimal-controls]
```tsx
import {
Audio,
PlayButton,
TimeDisplay
} from '@accelint/design-toolkit';
<Audio src="audio.mp3">
<div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
<PlayButton />
<TimeDisplay mode="current" /> / <TimeDisplay mode="duration" />
</div>
</Audio>
```
### Example: Disabled state [#example-disabled-state]
```tsx
import { Audio } from '@accelint/design-toolkit';
<Audio
src="audio.mp3"
isDisabled
/>
```
## Related [#related]
* [Video](../video/index.md) - Video player component with similar controls
* [MediaControls](../media-controls/index.md) - Individual media control components
# Avatar (/docs/toolkits/design-toolkit/components/avatar)
Displays a user's profile image with automatic fallback support. Built on Radix UI Avatar with support for custom fallbacks, status badges, and multiple sizes.
## Usage [#usage]
```tsx
import { Avatar } from '@accelint/design-toolkit';
export function UserProfile() {
return <Avatar imageProps={{ src: '/user.jpg', alt: 'User Name' }} />;
}
```
## Reference [#reference]
```typescript
interface AvatarProps {
imageProps?: { src: string; alt: string };
fallbackProps?: { children?: React.ReactNode };
size?: 'medium' | 'small';
children?: React.ReactNode;
classNames?: {
avatar?: string;
image?: string;
fallback?: string;
content?: string;
};
}
```
### Props [#props]
| Prop | Type | Default | Required |
| --------------- | -------------------------------- | ---------- | -------- |
| `imageProps` | `{ src: string; alt: string }` | - | No |
| `fallbackProps` | `{ children?: React.ReactNode }` | - | No |
| `size` | `'medium' \| 'small'` | `'medium'` | No |
| `children` | `React.ReactNode` | - | No |
| `classNames` | `object` | - | No |
#### `imageProps` [#imageprops]
Props passed to the underlying image element. Must include `src` for the image URL and `alt` for accessibility.
#### `fallbackProps` [#fallbackprops]
Props for the fallback element displayed when the image fails to load. If `children` is not provided, defaults to a person icon.
#### `size` [#size]
Controls the visual size of the avatar:
* `medium` - Default size (larger)
* `small` - Compact size
#### `children` [#children]
Optional content to overlay on the avatar, typically a Badge component for status indicators or notification counts.
#### `classNames` [#classnames]
Custom class names for sub-elements:
* `avatar` - The root element
* `image` - The image element
* `fallback` - The fallback element
* `content` - The content wrapper for children
### Inherited Props [#inherited-props]
Avatar inherits props from Radix UI's Avatar component. See [Radix UI Avatar](https://www.radix-ui.com/primitives/docs/components/avatar) for additional options.
## Examples [#examples]
### Example: Basic avatar with image [#example-basic-avatar-with-image]
```tsx
import { Avatar } from '@accelint/design-toolkit';
<Avatar imageProps={{ src: '/avatars/alice.jpg', alt: 'Alice Johnson' }} />
```
### Example: Avatar with initials fallback [#example-avatar-with-initials-fallback]
```tsx
import { Avatar } from '@accelint/design-toolkit';
<Avatar
imageProps={{ src: '/avatars/bob.jpg', alt: 'Bob Smith' }}
fallbackProps={{ children: 'BS' }}
/>
```
### Example: Small avatar [#example-small-avatar]
```tsx
import { Avatar } from '@accelint/design-toolkit';
<Avatar
size="small"
imageProps={{ src: '/avatars/carol.jpg', alt: 'Carol White' }}
/>
```
### Example: Avatar with status badge [#example-avatar-with-status-badge]
```tsx
import { Avatar, Badge } from '@accelint/design-toolkit';
<Avatar imageProps={{ src: '/avatars/dave.jpg', alt: 'Dave Brown' }}>
<Badge color="critical">3</Badge>
</Avatar>
```
### Example: Avatar with online status [#example-avatar-with-online-status]
```tsx
import { Avatar, Badge } from '@accelint/design-toolkit';
<Avatar imageProps={{ src: '/avatars/eve.jpg', alt: 'Eve Davis' }}>
<Badge color="success" />
</Avatar>
```
### Example: Avatar without image (icon fallback) [#example-avatar-without-image-icon-fallback]
```tsx
import { Avatar } from '@accelint/design-toolkit';
<Avatar fallbackProps={{ children: undefined }} />
```
This displays the default person icon when no image is provided.
### Example: Avatar with custom icon fallback [#example-avatar-with-custom-icon-fallback]
```tsx
import { Avatar, Icon } from '@accelint/design-toolkit';
import { Star } from '@accelint/icons';
<Avatar
imageProps={{ src: '/broken-image.jpg', alt: 'User' }}
fallbackProps={{
children: (
<Icon>
<Star />
</Icon>
),
}}
/>
```
### Example: Custom styled avatar [#example-custom-styled-avatar]
```tsx
import { Avatar } from '@accelint/design-toolkit';
<Avatar
imageProps={{ src: '/avatars/user.jpg', alt: 'User' }}
classNames={{
avatar: 'ring-2 ring-blue-500 ring-offset-2',
image: 'object-cover',
}}
/>
```
### Example: Avatar list [#example-avatar-list]
```tsx
import { Avatar } from '@accelint/design-toolkit';
const users = [
{ id: 1, name: 'Alice', avatar: '/avatars/alice.jpg' },
{ id: 2, name: 'Bob', avatar: '/avatars/bob.jpg' },
{ id: 3, name: 'Carol', avatar: '/avatars/carol.jpg' },
];
<div className="flex -space-x-2">
{users.map((user) => (
<Avatar
key={user.id}
size="small"
imageProps={{ src: user.avatar, alt: user.name }}
classNames={{ avatar: 'ring-2 ring-white' }}
/>
))}
</div>
```
> **Good to know:** The Avatar component automatically handles image loading errors and displays the fallback. If no fallback children are provided, a person icon is shown by default.
## Related [#related]
* [Badge](../badge/index.md) - Badge component for status overlays
* [Icon](../icon/index.md) - Icon component used in fallback
# Badge (/docs/toolkits/design-toolkit/components/badge)
## Usage [#usage]
```tsx
import { Badge } from '@accelint/design-toolkit';
export function MyComponent() {
return <Badge>New</Badge>;
}
```
## Reference [#reference]
```typescript
interface BadgeProps extends ComponentPropsWithRef<'span'> {
children?: string | number | boolean | null;
color?: 'info' | 'advisory' | 'normal' | 'serious' | 'critical';
offset?: number | { x?: number; y?: number };
placement?: Axis | 'top left' | 'top right' | 'bottom left' | 'bottom right';
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ----------- | ---------------------------------------------------------------------- | -------- | -------- |
| `children` | `string \| number \| boolean \| null` | - | No |
| `color` | `'info' \| 'advisory' \| 'normal' \| 'serious' \| 'critical'` | `'info'` | No |
| `placement` | `Axis \| 'top left' \| 'top right' \| 'bottom left' \| 'bottom right'` | - | No |
| `offset` | `number \| { x?: number; y?: number }` | - | No |
| `className` | `string` | - | No |
#### `color` [#color]
Semantic color variant:
* `info` - Informational status (default)
* `advisory` - Advisory or warning status
* `normal` - Normal/success status
* `serious` - Serious warnings
* `critical` - Critical errors or alerts
#### `placement` [#placement]
Position relative to container. Useful for notification badges on avatars or icons:
* `'top left'` - Top-left corner
* `'top right'` - Top-right corner
* `'bottom left'` - Bottom-left corner
* `'bottom right'` - Bottom-right corner
* `'top'` or `'bottom'` - Centered on top/bottom edge
#### `offset` [#offset]
Fine-tune positioning when using `placement`:
* Number: Applies same offset to both x and y axes
* Object: Separate x and y offset values
#### Dot indicator [#dot-indicator]
When `children` is empty or omitted, Badge renders as a small dot indicator without text.
## Examples [#examples]
### Example: Basic badge [#example-basic-badge]
```tsx
import { Badge } from '@accelint/design-toolkit';
<Badge>New</Badge>
```
### Example: Color variants [#example-color-variants]
```tsx
import { Badge } from '@accelint/design-toolkit';
<>
<Badge color="info">Info</Badge>
<Badge color="advisory">Advisory</Badge>
<Badge color="normal">Success</Badge>
<Badge color="serious">Warning</Badge>
<Badge color="critical">Error</Badge>
</>
```
### Example: Numeric badge [#example-numeric-badge]
```tsx
import { Badge } from '@accelint/design-toolkit';
<Badge color="critical">5</Badge>
```
### Example: Dot indicator [#example-dot-indicator]
```tsx
import { Badge } from '@accelint/design-toolkit';
<Badge color="normal" />
```
### Example: Positioned notification badge [#example-positioned-notification-badge]
```tsx
import { Badge, Avatar } from '@accelint/design-toolkit';
<div style={{ position: 'relative' }}>
<Avatar src="/avatar.jpg" />
<Badge
placement="top right"
offset={4}
color="critical"
>
3
</Badge>
</div>
```
### Example: Badge with custom offset [#example-badge-with-custom-offset]
```tsx
import { Badge } from '@accelint/design-toolkit';
<Badge
placement="top right"
offset={{ x: 8, y: -4 }}
color="advisory"
>
12
</Badge>
```
> **Good to know:** When using positioned badges, ensure the parent container has `position: relative` for correct positioning.
## Related [#related]
* [Avatar](../avatar/index.md) - Avatar component often used with badges
* [Icon](../icon/index.md) - Icon component for badge-like indicators
* [Chip](../chip/index.md) - Larger tag/chip component for labels
# Breadcrumbs (/docs/toolkits/design-toolkit/components/breadcrumbs)
Accessible breadcrumb navigation that displays the user's location within an application hierarchy and provides links back to parent pages. The final item represents the current page.
## Usage [#usage]
```tsx
import { Breadcrumbs, BreadcrumbItem } from '@accelint/design-toolkit';
export function MyPage() {
return (
<Breadcrumbs>
<BreadcrumbItem linkProps={{ href: '/' }}>Home</BreadcrumbItem>
<BreadcrumbItem linkProps={{ href: '/products' }}>Products</BreadcrumbItem>
<BreadcrumbItem>Current Product</BreadcrumbItem>
</Breadcrumbs>
);
}
```
## Reference [#reference]
### Breadcrumbs [#breadcrumbs]
```typescript
interface BreadcrumbsProps {
children: React.ReactNode;
className?: string;
}
```
#### Props [#props]
| Prop | Type | Default | Required |
| ----------- | ----------------- | ------- | -------- |
| `children` | `React.ReactNode` | - | Yes |
| `className` | `string` | - | No |
### BreadcrumbItem [#breadcrumbitem]
```typescript
interface BreadcrumbItemProps {
children: React.ReactNode;
linkProps?: { href: string };
classNames?: {
item?: string;
link?: string;
separator?: string;
};
}
```
#### Props [#props-1]
| Prop | Type | Default | Required |
| ------------ | ------------------ | ------- | -------- |
| `children` | `React.ReactNode` | - | Yes |
| `linkProps` | `{ href: string }` | - | No |
| `classNames` | `object` | - | No |
#### `linkProps` [#linkprops]
Props passed to the Link component. Omit for the current page (which should not be a link).
#### `classNames` [#classnames]
Custom class names for sub-elements:
* `item` - The breadcrumb item container
* `link` - The link element (when linkProps is provided)
* `separator` - The chevron separator icon
### Inherited Props [#inherited-props]
Breadcrumbs inherits props from React Aria's `Breadcrumbs` component. See [React Aria Breadcrumbs](https://react-spectrum.adobe.com/react-aria/Breadcrumbs.html) for full API reference.
## Examples [#examples]
### Example: Basic breadcrumbs [#example-basic-breadcrumbs]
```tsx
import { Breadcrumbs, BreadcrumbItem } from '@accelint/design-toolkit';
<Breadcrumbs>
<BreadcrumbItem linkProps={{ href: '/' }}>Home</BreadcrumbItem>
<BreadcrumbItem linkProps={{ href: '/docs' }}>Documentation</BreadcrumbItem>
<BreadcrumbItem>Getting Started</BreadcrumbItem>
</Breadcrumbs>
```
### Example: Multi-level navigation [#example-multi-level-navigation]
```tsx
import { Breadcrumbs, BreadcrumbItem } from '@accelint/design-toolkit';
<Breadcrumbs>
<BreadcrumbItem linkProps={{ href: '/' }}>Home</BreadcrumbItem>
<BreadcrumbItem linkProps={{ href: '/settings' }}>Settings</BreadcrumbItem>
<BreadcrumbItem linkProps={{ href: '/settings/account' }}>Account</BreadcrumbItem>
<BreadcrumbItem>Profile</BreadcrumbItem>
</Breadcrumbs>
```
### Example: With router integration [#example-with-router-integration]
```tsx
import { Breadcrumbs, BreadcrumbItem } from '@accelint/design-toolkit';
import { useNavigate } from 'react-router-dom';
export function RouterBreadcrumbs() {
const navigate = useNavigate();
return (
<Breadcrumbs>
<BreadcrumbItem
linkProps={{
href: '/',
onPress: (e) => {
e.preventDefault();
navigate('/');
},
}}
>
Home
</BreadcrumbItem>
<BreadcrumbItem
linkProps={{
href: '/products',
onPress: (e) => {
e.preventDefault();
navigate('/products');
},
}}
>
Products
</BreadcrumbItem>
<BreadcrumbItem>Details</BreadcrumbItem>
</Breadcrumbs>
);
}
```
### Example: Custom styling [#example-custom-styling]
```tsx
import { Breadcrumbs, BreadcrumbItem } from '@accelint/design-toolkit';
<Breadcrumbs className="bg-gray-100 p-4 rounded">
<BreadcrumbItem
linkProps={{ href: '/' }}
classNames={{
link: 'text-blue-600 hover:text-blue-800 font-semibold',
separator: 'text-gray-400',
}}
>
Home
</BreadcrumbItem>
<BreadcrumbItem classNames={{ item: 'text-gray-900 font-bold' }}>
Current Page
</BreadcrumbItem>
</Breadcrumbs>
```
### Example: E-commerce navigation [#example-e-commerce-navigation]
```tsx
import { Breadcrumbs, BreadcrumbItem } from '@accelint/design-toolkit';
<Breadcrumbs>
<BreadcrumbItem linkProps={{ href: '/' }}>Home</BreadcrumbItem>
<BreadcrumbItem linkProps={{ href: '/shop' }}>Shop</BreadcrumbItem>
<BreadcrumbItem linkProps={{ href: '/shop/electronics' }}>Electronics</BreadcrumbItem>
<BreadcrumbItem linkProps={{ href: '/shop/electronics/laptops' }}>Laptops</BreadcrumbItem>
<BreadcrumbItem>MacBook Pro 16"</BreadcrumbItem>
</Breadcrumbs>
```
### Example: Documentation site [#example-documentation-site]
```tsx
import { Breadcrumbs, BreadcrumbItem } from '@accelint/design-toolkit';
<Breadcrumbs>
<BreadcrumbItem linkProps={{ href: '/docs' }}>Docs</BreadcrumbItem>
<BreadcrumbItem linkProps={{ href: '/docs/components' }}>Components</BreadcrumbItem>
<BreadcrumbItem linkProps={{ href: '/docs/components/navigation' }}>Navigation</BreadcrumbItem>
<BreadcrumbItem>Breadcrumbs</BreadcrumbItem>
</Breadcrumbs>
```
> **Good to know:** The final breadcrumb item should not have `linkProps` as it represents the current page. A chevron separator is automatically added between items, but not after the final item.
### Example: Minimal breadcrumbs [#example-minimal-breadcrumbs]
```tsx
import { Breadcrumbs, BreadcrumbItem } from '@accelint/design-toolkit';
<Breadcrumbs>
<BreadcrumbItem linkProps={{ href: '/' }}>Home</BreadcrumbItem>
<BreadcrumbItem>Current</BreadcrumbItem>
</Breadcrumbs>
```
## Related [#related]
* [Link](../link/index.md) - Link component used internally
* [Icon](../icon/index.md) - Icon component for separators
# Button (/docs/toolkits/design-toolkit/components/button)
## Usage [#usage]
```tsx
import { Button } from '@accelint/design-toolkit';
export function MyComponent() {
return <Button>Click me</Button>;
}
```
## Reference [#reference]
```typescript
interface ButtonProps extends AriaButtonProps {
color?: 'mono-muted' | 'mono-bold' | 'accent' | 'serious' | 'critical';
size?: 'xsmall' | 'small' | 'medium' | 'large';
variant?: 'filled' | 'outline' | 'flat' | 'icon';
className?: string;
children?: React.ReactNode;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ------------ | -------------------------------------------------------------------- | -------------- | -------- |
| `children` | `React.ReactNode` | - | No |
| `color` | `'mono-muted' \| 'mono-bold' \| 'accent' \| 'serious' \| 'critical'` | `'mono-muted'` | No |
| `size` | `'xsmall' \| 'small' \| 'medium' \| 'large'` | `'medium'` | No |
| `variant` | `'filled' \| 'outline' \| 'flat' \| 'icon'` | `'filled'` | No |
| `className` | `string` | - | No |
| `onPress` | `(e: PressEvent) => void` | - | No |
| `isDisabled` | `boolean` | `false` | No |
#### `color` [#color]
Semantic color variant that controls the button's visual appearance:
* `mono-muted` - Default neutral styling
* `mono-bold` - Bold neutral styling
* `accent` - Accent color emphasis
* `serious` - Warning or important actions
* `critical` - Destructive or high-impact actions
#### `variant` [#variant]
Visual style variant:
* `filled` - Solid background (default)
* `outline` - Border with transparent background
* `flat` - No border or background, text only
* `icon` - Icon-only button with minimal chrome
#### `size` [#size]
Controls button padding and font size. The `size` prop also automatically sizes nested `Icon` components via context.
Available sizes: `xsmall`, `small`, `medium`, `large`
### Inherited Props [#inherited-props]
Button inherits all props from React Aria's `Button` component, including:
* `onPress` - Called when the button is pressed
* `isDisabled` - Disables the button
* `type` - HTML button type (`button`, `submit`, `reset`)
* `form` - Associates button with a form by ID
See [React Aria Button](https://react-spectrum.adobe.com/react-aria/Button.html) for full API reference.
## Examples [#examples]
### Example: Primary action button [#example-primary-action-button]
```tsx
import { Button } from '@accelint/design-toolkit';
<Button variant="filled" color="accent" onPress={() => console.log('Saved')}>
Save Changes
</Button>
```
### Example: Destructive action [#example-destructive-action]
```tsx
import { Button } from '@accelint/design-toolkit';
<Button variant="outline" color="critical" onPress={() => handleDelete()}>
Delete Account
</Button>
```
### Example: Button with icon [#example-button-with-icon]
```tsx
import { Button, Icon } from '@accelint/design-toolkit';
import { Plus } from '@accelint/icons';
<Button variant="flat">
<Icon><Plus /></Icon>
Add Item
</Button>
```
### Example: Icon-only button [#example-icon-only-button]
```tsx
import { Button, Icon } from '@accelint/design-toolkit';
import { Settings } from '@accelint/icons';
<Button variant="icon" aria-label="Settings">
<Icon><Settings /></Icon>
</Button>
```
> **Good to know:** When using the `icon` variant, always provide an `aria-label` for accessibility since there's no visible text.
### Example: Different sizes [#example-different-sizes]
```tsx
import { Button } from '@accelint/design-toolkit';
<>
<Button size="xsmall">Extra Small</Button>
<Button size="small">Small</Button>
<Button size="medium">Medium</Button>
<Button size="large">Large</Button>
</>
```
### Example: Disabled state [#example-disabled-state]
```tsx
import { Button } from '@accelint/design-toolkit';
<Button isDisabled onPress={() => console.log('Never called')}>
Unavailable
</Button>
```
## Related [#related]
* [LinkButton](./link.md) - Link styled as a button
* [ToggleButton](./toggle.md) - Toggle button component
* [Icon](../../icon/index.md) - Icon component with automatic sizing from Button context
# Checkbox (/docs/toolkits/design-toolkit/components/checkbox)
## Usage [#usage]
```tsx
import { Checkbox } from '@accelint/design-toolkit';
export function MyComponent() {
return (
<Checkbox>
Accept terms and conditions
</Checkbox>
);
}
```
## Reference [#reference]
```typescript
interface CheckboxProps extends AriaCheckboxProps {
classNames?: {
checkbox?: string;
control?: string;
label?: string;
};
labelPosition?: 'start' | 'end';
children?: React.ReactNode;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ----------------- | ------------------------------- | ------- | -------- |
| `children` | `React.ReactNode` | - | No |
| `isSelected` | `boolean` | `false` | No |
| `isIndeterminate` | `boolean` | `false` | No |
| `isDisabled` | `boolean` | `false` | No |
| `labelPosition` | `'start' \| 'end'` | `'end'` | No |
| `value` | `string` | - | No |
| `onChange` | `(isSelected: boolean) => void` | - | No |
| `classNames` | `object` | - | No |
#### `isIndeterminate` [#isindeterminate]
When `true`, displays a minus icon indicating partial selection. Commonly used for "select all" checkboxes when only some items are selected.
#### `labelPosition` [#labelposition]
Controls whether the label appears before (`start`) or after (`end`) the checkbox control. Default is `end` (label on the right).
#### `classNames` [#classnames]
Granular styling control:
* `checkbox` - The outer label wrapper
* `control` - The checkbox indicator box
* `label` - The label text wrapper
### Inherited Props [#inherited-props]
Checkbox inherits all props from React Aria's `Checkbox` component, including:
* `isSelected` - Whether the checkbox is checked
* `isDisabled` - Whether the checkbox is disabled
* `isReadOnly` - Whether the checkbox is read-only
* `value` - Value for the checkbox (used in groups)
* `onChange` - Called when selection changes
See [React Aria Checkbox](https://react-spectrum.adobe.com/react-aria/Checkbox.html) for full API reference.
## Examples [#examples]
### Example: Basic checkbox [#example-basic-checkbox]
```tsx
import { Checkbox } from '@accelint/design-toolkit';
<Checkbox>
Accept terms and conditions
</Checkbox>
```
### Example: Controlled checkbox [#example-controlled-checkbox]
```tsx
import { Checkbox } from '@accelint/design-toolkit';
import { useState } from 'react';
function MyComponent() {
const [isSelected, setIsSelected] = useState(false);
return (
<Checkbox
isSelected={isSelected}
onChange={setIsSelected}
>
Receive notifications
</Checkbox>
);
}
```
### Example: Checkbox group [#example-checkbox-group]
```tsx
import { CheckboxGroup, Checkbox } from '@accelint/design-toolkit';
<CheckboxGroup label="Select preferences">
<Checkbox value="notifications">Email notifications</Checkbox>
<Checkbox value="marketing">Marketing emails</Checkbox>
<Checkbox value="updates">Product updates</Checkbox>
</CheckboxGroup>
```
### Example: Indeterminate state [#example-indeterminate-state]
```tsx
import { Checkbox } from '@accelint/design-toolkit';
<Checkbox isIndeterminate>
Select all items (3 of 10 selected)
</Checkbox>
```
### Example: Disabled checkbox [#example-disabled-checkbox]
```tsx
import { Checkbox } from '@accelint/design-toolkit';
<Checkbox isDisabled>
Unavailable option
</Checkbox>
```
### Example: Label position [#example-label-position]
```tsx
import { Checkbox } from '@accelint/design-toolkit';
<>
<Checkbox labelPosition="start">Label before control</Checkbox>
<Checkbox labelPosition="end">Label after control</Checkbox>
</>
```
### Example: Custom styling [#example-custom-styling]
```tsx
import { Checkbox } from '@accelint/design-toolkit';
<Checkbox
classNames={{
checkbox: 'gap-4',
control: 'border-2 border-accent',
label: 'font-bold'
}}
>
Styled checkbox
</Checkbox>
```
> **Good to know:** The indeterminate state is purely visual and does not affect the checkbox's value. It's typically used to indicate partial selection in a group.
## Related [#related]
* [CheckboxGroup](./group.md) - Group multiple checkboxes together
* [Radio](../radio/index.md) - Radio button component for single selection
* [Switch](../switch/index.md) - Toggle switch for binary states
# Chip (/docs/toolkits/design-toolkit/components/chip)
Compact element for displaying tags, filters, or selectable items with keyboard navigation and accessibility features.
## Usage [#usage]
```tsx
import { Chip } from '@accelint/design-toolkit';
export function Tags() {
return <Chip>JavaScript</Chip>;
}
```
## Reference [#reference]
```typescript
interface ChipProps {
children: React.ReactNode;
className?: string;
color?: 'info' | 'advisory' | 'normal' | 'serious' | 'critical';
size?: 'small' | 'medium';
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ----------- | ------------------------------------------------------------- | ---------- | -------- |
| `children` | `React.ReactNode` | - | Yes |
| `className` | `string` | - | No |
| `color` | `'info' \| 'advisory' \| 'normal' \| 'serious' \| 'critical'` | `'info'` | No |
| `size` | `'small' \| 'medium'` | `'medium'` | No |
#### `color` [#color]
Semantic color variant:
* `info` - Informational (default, blue)
* `advisory` - Warning or advisory (yellow)
* `normal` - Success or normal state (green)
* `serious` - Serious caution (orange)
* `critical` - Error or critical state (red)
#### `size` [#size]
Controls chip dimensions and font size:
* `medium` - Default size for standard use
* `small` - Compact size for dense layouts
The `size` prop automatically sizes nested `Icon` components.
## Examples [#examples]
### Example: Basic chips with colors [#example-basic-chips-with-colors]
```tsx
import { Chip } from '@accelint/design-toolkit';
<>
<Chip color="info">Info</Chip>
<Chip color="advisory">Warning</Chip>
<Chip color="normal">Success</Chip>
<Chip color="serious">Caution</Chip>
<Chip color="critical">Error</Chip>
</>
```
### Example: Chip with icon [#example-chip-with-icon]
```tsx
import { Chip, Icon } from '@accelint/design-toolkit';
import { Tag } from '@accelint/icons';
<Chip color="info">
<Icon><Tag /></Icon>
Tagged Item
</Chip>
```
### Example: Small chips [#example-small-chips]
```tsx
import { Chip } from '@accelint/design-toolkit';
<>
<Chip size="small">Compact</Chip>
<Chip size="small" color="normal">Small Success</Chip>
</>
```
### Example: Chip list for multiple tags [#example-chip-list-for-multiple-tags]
```tsx
import { ChipList, Chip } from '@accelint/design-toolkit';
<ChipList>
<Chip color="info">React</Chip>
<Chip color="advisory">TypeScript</Chip>
<Chip color="normal">Node.js</Chip>
</ChipList>
```
### Example: Deletable chips [#example-deletable-chips]
```tsx
import { ChipList, DeletableChip } from '@accelint/design-toolkit';
<ChipList onRemove={(keys) => console.log('Removed:', keys)}>
<DeletableChip id="tag1">Removable Tag 1</DeletableChip>
<DeletableChip id="tag2" color="normal">Removable Tag 2</DeletableChip>
</ChipList>
```
### Example: Selectable chips [#example-selectable-chips]
```tsx
import { ChipList, SelectableChip } from '@accelint/design-toolkit';
import { useState } from 'react';
function FilterChips() {
const [selected, setSelected] = useState(new Set(['active']));
return (
<ChipList
selectionMode="multiple"
selectedKeys={selected}
onSelectionChange={setSelected}
>
<SelectableChip id="active" color="normal">Active</SelectableChip>
<SelectableChip id="pending" color="advisory">Pending</SelectableChip>
<SelectableChip id="failed" color="critical">Failed</SelectableChip>
</ChipList>
);
}
```
### Example: Single selection mode [#example-single-selection-mode]
```tsx
import { ChipList, SelectableChip } from '@accelint/design-toolkit';
<ChipList selectionMode="single">
<SelectableChip id="all">All</SelectableChip>
<SelectableChip id="active">Active</SelectableChip>
<SelectableChip id="archived">Archived</SelectableChip>
</ChipList>
```
## Multi-Part Structure [#multi-part-structure]
Chip has several related components:
* **Chip** - Basic non-interactive chip
* **ChipList** - Container for multiple chips with keyboard navigation
* **DeletableChip** - Chip with remove button
* **SelectableChip** - Chip that can be selected/deselected
> **Good to know:** When using `DeletableChip` or `SelectableChip`, always wrap them in a `ChipList` to enable proper keyboard navigation and state management.
## Related [#related]
* [ChipList](./list.mdx) - Container component for chip collections
* [DeletableChip](./deletable-chip.mdx) - Chip variant with removal
* [SelectableChip](./selectable-chip.mdx) - Chip variant with selection
* [Icon](../icon/index.mdx) - Icon component for chip decorations
# ColorPicker (/docs/toolkits/design-toolkit/components/color-picker)
## Usage [#usage]
```tsx
import { ColorPicker } from '@accelint/design-toolkit';
const colors = ['#ff0000', '#00ff00', '#0000ff'];
export function MyComponent() {
return (
<ColorPicker
items={colors}
label="Choose a color"
onChange={(color) => console.log('Selected:', color)}
/>
);
}
```
## Reference [#reference]
```typescript
interface ColorPickerProps {
items: (string | Color | Rgba255Tuple)[];
label?: string;
value?: string | Color | Rgba255Tuple;
defaultValue?: string | Color | Rgba255Tuple;
onChange?: (color: Color) => void;
isRequired?: boolean;
isDisabled?: boolean;
classNames?: {
container?: string;
label?: string;
picker?: string;
item?: string;
swatch?: string;
};
}
```
### Props [#props]
| Prop | Type | Default | Required |
| -------------- | ---------------------------------------- | ------- | -------- |
| `items` | `Array<string \| Color \| Rgba255Tuple>` | - | Yes |
| `label` | `string` | - | No |
| `value` | `string \| Color \| Rgba255Tuple` | - | No |
| `defaultValue` | `string \| Color \| Rgba255Tuple` | - | No |
| `onChange` | `(color: Color) => void` | - | No |
| `isRequired` | `boolean` | `false` | No |
| `isDisabled` | `boolean` | `false` | No |
| `classNames` | `object` | - | No |
#### `items` [#items]
Array of color values to display as selectable swatches. Supports multiple color formats:
* Hex strings: `'#ff0000'`, `'#f00'`
* Color objects: React Aria Color instances
* RGBA 255 tuples: `[255, 0, 0, 255]`
#### `value` / `defaultValue` [#value--defaultvalue]
The selected color value. Use `value` for controlled components and `defaultValue` for uncontrolled components. Supports the same formats as `items`.
#### `classNames` [#classnames]
Custom class names for sub-elements:
* `container` - The outer container element
* `label` - The label element
* `picker` - The picker container with all swatches
* `item` - Individual swatch items
* `swatch` - The color swatch elements
### Inherited Props [#inherited-props]
ColorPicker inherits all props from React Aria's `ColorSwatchPicker` component, including:
* `onFocusChange` - Called when focus changes
* `onHoverChange` - Called when hover state changes
See [React Aria ColorSwatchPicker](https://react-spectrum.adobe.com/react-aria/ColorSwatchPicker.html) for full API reference.
## Examples [#examples]
### Example: Basic color picker [#example-basic-color-picker]
```tsx
import { ColorPicker } from '@accelint/design-toolkit';
const colors = ['#ff0000', '#00ff00', '#0000ff'];
<ColorPicker
items={colors}
label="Choose a color"
onChange={(color) => console.log('Selected:', color)}
/>
```
### Example: Controlled value [#example-controlled-value]
```tsx
import { ColorPicker } from '@accelint/design-toolkit';
import { parseColor } from '@react-stately/color';
import { useState } from 'react';
const colors = ['#ff0000', '#00ff00', '#0000ff', '#ffff00', '#ff00ff', '#00ffff'];
export function ControlledColorPicker() {
const [selectedColor, setSelectedColor] = useState(parseColor('#ff0000'));
return (
<div>
<ColorPicker
items={colors}
label="Select color"
value={selectedColor}
onChange={setSelectedColor}
/>
<p>Selected: {selectedColor.toString('hex')}</p>
</div>
);
}
```
### Example: Using RGBA tuples [#example-using-rgba-tuples]
```tsx
import { ColorPicker } from '@accelint/design-toolkit';
const colors = [
[255, 0, 0, 255], // Red
[0, 255, 0, 255], // Green
[0, 0, 255, 255], // Blue
[255, 255, 0, 255], // Yellow
];
<ColorPicker
items={colors}
label="Choose a color"
defaultValue={[255, 0, 0, 255]}
/>
```
### Example: Custom styling [#example-custom-styling]
```tsx
import { ColorPicker } from '@accelint/design-toolkit';
const colors = ['#ff0000', '#00ff00', '#0000ff', '#ffff00', '#ff00ff', '#00ffff'];
<ColorPicker
items={colors}
label="Pick your favorite"
classNames={{
container: 'p-4',
picker: 'gap-4',
item: 'rounded-lg hover:scale-110 transition-transform',
swatch: 'w-12 h-12 border-2 border-white shadow-lg',
}}
/>
```
### Example: Required field [#example-required-field]
```tsx
import { ColorPicker } from '@accelint/design-toolkit';
const colors = ['#ff0000', '#00ff00', '#0000ff'];
<ColorPicker
items={colors}
label="Primary Color"
isRequired
onChange={(color) => console.log('Required color selected:', color)}
/>
```
### Example: Large color palette [#example-large-color-palette]
```tsx
import { ColorPicker } from '@accelint/design-toolkit';
const colors = [
'#000000', '#333333', '#666666', '#999999', '#cccccc', '#ffffff',
'#ff0000', '#ff6600', '#ffcc00', '#ffff00', '#ccff00', '#66ff00',
'#00ff00', '#00ff66', '#00ffcc', '#00ffff', '#00ccff', '#0066ff',
'#0000ff', '#6600ff', '#cc00ff', '#ff00ff', '#ff00cc', '#ff0066',
];
<ColorPicker
items={colors}
label="Extended palette"
classNames={{
picker: 'grid grid-cols-6 gap-2',
swatch: 'w-10 h-10',
}}
/>
```
### Example: Disabled state [#example-disabled-state]
```tsx
import { ColorPicker } from '@accelint/design-toolkit';
const colors = ['#ff0000', '#00ff00', '#0000ff'];
<ColorPicker
items={colors}
label="Locked Color"
value="#ff0000"
isDisabled
/>
```
> **Good to know:** The ColorPicker automatically handles color parsing and validation. RGBA 255 tuples are automatically converted to hex format internally for consistency.
## Related [#related]
* [Label](../label/index.md) - Label component used internally
# ComboBoxField (/docs/toolkits/design-toolkit/components/combobox-field)
## Usage [#usage]
```tsx
import { ComboBoxField, OptionsItem } from '@accelint/design-toolkit';
export function MyForm() {
const countries = [
{ id: 'us', name: 'United States' },
{ id: 'ca', name: 'Canada' },
{ id: 'mx', name: 'Mexico' },
];
return (
<ComboBoxField label="Country" defaultItems={countries}>
{(item) => <OptionsItem>{item.name}</OptionsItem>}
</ComboBoxField>
);
}
```
## Reference [#reference]
```typescript
interface ComboBoxFieldProps<T extends OptionsDataItem> extends Omit<ComboBoxProps<T>, 'children' | 'className'> {
label?: string;
description?: string;
errorMessage?: string;
size?: 'small' | 'medium';
isClearable?: boolean;
isReadOnly?: boolean;
inputProps?: Omit<InputProps, 'className'>;
layoutOptions?: ListLayoutOptions;
classNames?: {
field?: ComboBoxProps<T>['className'];
label?: LabelProps['className'];
control?: string;
input?: InputProps['className'];
clear?: ButtonProps['className'];
trigger?: ButtonProps['className'];
description?: string;
error?: FieldErrorProps['className'];
popover?: PopoverProps['className'];
};
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ------------------- | -------------------------------- | ---------- | -------- |
| `label` | `string` | - | No |
| `description` | `string` | - | No |
| `errorMessage` | `string` | - | No |
| `size` | `'small' \| 'medium'` | `'medium'` | No |
| `isClearable` | `boolean` | `true` | No |
| `isReadOnly` | `boolean` | `false` | No |
| `menuTrigger` | `'focus' \| 'input' \| 'manual'` | `'focus'` | No |
| `inputValue` | `string` | - | No |
| `defaultInputValue` | `string` | `''` | No |
| `onInputChange` | `(value: string) => void` | - | No |
| `layoutOptions` | `ListLayoutOptions` | - | No |
#### `label` [#label]
Label text displayed above the combobox. Automatically associates with the input for accessibility. Hidden when `size="small"`.
#### `description` [#description]
Helper text displayed below the combobox. Hidden when `size="small"`, `isReadOnly`, or when the field is invalid.
#### `errorMessage` [#errormessage]
Error message displayed when validation fails. Automatically sets `isInvalid` to `true` when provided.
#### `size` [#size]
Controls field sizing and visibility of label and description:
* `medium` - Standard size with visible label and description (default)
* `small` - Compact size, hides label and description
#### `isClearable` [#isclearable]
Shows a clear button (X icon) when the input has a value. Pressing Escape also clears the input when `isClearable` is `true`. Not shown when `isReadOnly` is `true`.
#### `isReadOnly` [#isreadonly]
Displays the selected value without allowing dropdown interaction or input editing. Hides the trigger button and clear button.
#### `menuTrigger` [#menutrigger]
Controls when the dropdown menu opens:
* `focus` - Opens on focus (default)
* `input` - Opens only when typing
* `manual` - Opens only when trigger button is clicked
#### `inputValue` / `defaultInputValue` [#inputvalue--defaultinputvalue]
Controls the text input value independently from the selected option. Useful for autocomplete scenarios where users can type custom values.
#### `layoutOptions` [#layoutoptions]
Virtualizer layout options for rendering large lists efficiently:
```typescript
layoutOptions={{
estimatedRowHeight: 40,
}}
```
### Inherited Props [#inherited-props]
ComboBoxField inherits all props from React Aria's `ComboBox` component, including:
* `selectedKey` / `defaultSelectedKey` - Controlled/uncontrolled selection
* `onSelectionChange` - Called when selection changes (receives key)
* `items` / `defaultItems` - Collection items for dynamic rendering
* `allowsCustomValue` - Allows freeform text entry
* `disabledKeys` - Array of disabled option keys
See [React Aria ComboBox](https://react-spectrum.adobe.com/react-aria/ComboBox.html) for full API reference.
## Examples [#examples]
### Example: Basic combobox [#example-basic-combobox]
```tsx
import { ComboBoxField, OptionsItem } from '@accelint/design-toolkit';
const fruits = [
{ id: 'apple', name: 'Apple' },
{ id: 'banana', name: 'Banana' },
{ id: 'orange', name: 'Orange' },
];
<ComboBoxField label="Fruit" defaultItems={fruits}>
{(item) => <OptionsItem>{item.name}</OptionsItem>}
</ComboBoxField>
```
### Example: With description [#example-with-description]
```tsx
import { ComboBoxField, OptionsItem } from '@accelint/design-toolkit';
<ComboBoxField
label="Timezone"
description="Select your local timezone"
defaultItems={timezones}
>
{(item) => <OptionsItem>{item.name}</OptionsItem>}
</ComboBoxField>
```
### Example: Required with validation [#example-required-with-validation]
```tsx
import { ComboBoxField, OptionsItem } from '@accelint/design-toolkit';
<ComboBoxField
label="Country"
isRequired
errorMessage={!selectedCountry ? 'Please select a country' : undefined}
defaultItems={countries}
>
{(item) => <OptionsItem>{item.name}</OptionsItem>}
</ComboBoxField>
```
### Example: Read-only display [#example-read-only-display]
```tsx
import { ComboBoxField, OptionsItem } from '@accelint/design-toolkit';
<ComboBoxField
label="Account Type"
selectedKey="premium"
isReadOnly
defaultItems={accountTypes}
>
{(item) => <OptionsItem>{item.name}</OptionsItem>}
</ComboBoxField>
```
> **Good to know:** Read-only mode displays the selected value without interaction. Use `isDisabled` for temporarily unavailable fields.
### Example: Small size variant [#example-small-size-variant]
```tsx
import { ComboBoxField, OptionsItem } from '@accelint/design-toolkit';
<ComboBoxField
size="small"
placeholder="Filter..."
defaultItems={filters}
>
{(item) => <OptionsItem>{item.name}</OptionsItem>}
</ComboBoxField>
```
### Example: Allow custom values [#example-allow-custom-values]
```tsx
import { ComboBoxField, OptionsItem } from '@accelint/design-toolkit';
<ComboBoxField
label="Email"
allowsCustomValue
defaultItems={recentEmails}
>
{(item) => <OptionsItem>{item.email}</OptionsItem>}
</ComboBoxField>
```
### Example: Rich options with descriptions [#example-rich-options-with-descriptions]
```tsx
import { ComboBoxField, OptionsItem, OptionsItemLabel, OptionsItemDescription } from '@accelint/design-toolkit';
<ComboBoxField label="Plan" defaultItems={plans}>
{(plan) => (
<OptionsItem textValue={plan.name}>
<OptionsItemLabel>{plan.name}</OptionsItemLabel>
<OptionsItemDescription>{plan.description}</OptionsItemDescription>
</OptionsItem>
)}
</ComboBoxField>
```
### Example: Controlled input value [#example-controlled-input-value]
```tsx
import { useState } from 'react';
import { ComboBoxField, OptionsItem } from '@accelint/design-toolkit';
export function ControlledExample() {
const [inputValue, setInputValue] = useState('');
const [selectedKey, setSelectedKey] = useState(null);
return (
<ComboBoxField
label="Search"
inputValue={inputValue}
onInputChange={setInputValue}
selectedKey={selectedKey}
onSelectionChange={setSelectedKey}
defaultItems={items}
>
{(item) => <OptionsItem>{item.name}</OptionsItem>}
</ComboBoxField>
);
}
```
### Example: Menu trigger on input [#example-menu-trigger-on-input]
```tsx
import { ComboBoxField, OptionsItem } from '@accelint/design-toolkit';
<ComboBoxField
label="Country"
menuTrigger="input"
placeholder="Start typing..."
defaultItems={countries}
>
{(item) => <OptionsItem>{item.name}</OptionsItem>}
</ComboBoxField>
```
> **Good to know:** `menuTrigger="input"` only opens the dropdown when the user types, useful for search-heavy interfaces.
### Example: Virtualized large list [#example-virtualized-large-list]
```tsx
import { ComboBoxField, OptionsItem } from '@accelint/design-toolkit';
const countries = [...]; // 200+ countries
<ComboBoxField
label="Country"
items={countries}
layoutOptions={{ estimatedRowHeight: 40 }}
>
{(country) => <OptionsItem>{country.name}</OptionsItem>}
</ComboBoxField>
```
### Example: Disabled options [#example-disabled-options]
```tsx
import { ComboBoxField, OptionsItem } from '@accelint/design-toolkit';
<ComboBoxField
label="Status"
disabledKeys={['pending']}
defaultItems={statuses}
>
{(item) => <OptionsItem>{item.name}</OptionsItem>}
</ComboBoxField>
```
### Example: Without clear button [#example-without-clear-button]
```tsx
import { ComboBoxField, OptionsItem } from '@accelint/design-toolkit';
<ComboBoxField
label="Priority"
isClearable={false}
defaultItems={priorities}
>
{(item) => <OptionsItem>{item.name}</OptionsItem>}
</ComboBoxField>
```
## Related [#related]
* [SelectField](../select-field/index.md) - Non-searchable select dropdown
* [SearchField](../search-field/index.md) - Search input without options
* [OptionsItem](../options/item.md) - Combobox option component
* [OptionsItemLabel](../options/item-label.md) - Option label component
* [OptionsItemDescription](../options/item-description.md) - Option description component
# DateField (/docs/toolkits/design-toolkit/components/date-field)
A comprehensive date input component with segmented editing, providing accessible date input with separate segments for day, month, and year. Includes calendar icon, validation states, and international date format support with keyboard navigation between segments.
## Usage [#usage]
```tsx
import { DateField } from '@accelint/design-toolkit';
export function MyForm() {
return <DateField label="Birth Date" />;
}
```
## Reference [#reference]
```typescript
interface DateFieldProps<T extends DateValue> {
label?: string;
description?: string;
errorMessage?: string;
size?: 'small' | 'medium';
shortMonth?: boolean;
shouldForceLeadingZeros?: boolean;
isDisabled?: boolean;
isInvalid?: boolean;
isRequired?: boolean;
isReadOnly?: boolean;
value?: T;
defaultValue?: T;
onChange?: (value: T) => void;
classNames?: {
field?: string;
label?: string;
control?: string;
input?: string;
segment?: string;
description?: string;
error?: string;
};
inputProps?: Omit<DateInputProps, 'children' | 'className'>;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ------------------------- | ---------------------------- | ---------- | -------- |
| `label` | `string` | - | No |
| `description` | `string` | - | No |
| `errorMessage` | `string` | - | No |
| `size` | `'small' \| 'medium'` | `'medium'` | No |
| `shortMonth` | `boolean` | `true` | No |
| `shouldForceLeadingZeros` | `boolean` | `true` | No |
| `isDisabled` | `boolean` | `false` | No |
| `isInvalid` | `boolean` | `false` | No |
| `isRequired` | `boolean` | `false` | No |
| `isReadOnly` | `boolean` | `false` | No |
| `value` | `DateValue` | - | No |
| `defaultValue` | `DateValue` | - | No |
| `onChange` | `(value: DateValue) => void` | - | No |
| `classNames` | `object` | - | No |
| `inputProps` | `DateInputProps` | - | No |
#### `size` [#size]
Controls the visual size of the date field:
* `medium` - Default size with calendar icon and full label
* `small` - Compact size without calendar icon or visible label (label used for aria-label only)
#### `shortMonth` [#shortmonth]
When `true`, displays month as a 3-letter abbreviation (e.g., "JAN", "FEB") when the month segment is not focused. When focused, displays numeric value for editing.
#### `shouldForceLeadingZeros` [#shouldforceleadingzeros]
Whether to force leading zeros in date segments. For example, `01/05/2024` vs `1/5/2024`.
#### `classNames` [#classnames]
Custom class names for sub-elements:
* `field` - The outer field container
* `label` - The label element
* `control` - The control wrapper containing icon and input
* `input` - The date input element
* `segment` - Individual date segments (day, month, year)
* `description` - The description text
* `error` - The error message element
### Inherited Props [#inherited-props]
DateField inherits all props from React Aria's `DateField` component, including:
* `minValue` - Minimum allowed date
* `maxValue` - Maximum allowed date
* `placeholderValue` - Placeholder date shown when empty
* `granularity` - Which fields to display (e.g., "day", "hour", "minute")
See [React Aria DateField](https://react-spectrum.adobe.com/react-aria/DateField.html) for full API reference.
## Examples [#examples]
### Example: Basic date field [#example-basic-date-field]
```tsx
import { DateField } from '@accelint/design-toolkit';
<DateField label="Birth Date" />
```
### Example: Required with validation [#example-required-with-validation]
```tsx
import { DateField } from '@accelint/design-toolkit';
import { parseDate } from '@internationalized/date';
<DateField
label="Event Date"
isRequired
minValue={parseDate('2024-01-01')}
errorMessage="Please select a valid date after January 1, 2024"
/>
```
### Example: Controlled value [#example-controlled-value]
```tsx
import { DateField } from '@accelint/design-toolkit';
import { parseDate } from '@internationalized/date';
import { useState } from 'react';
export function ControlledDateField() {
const [date, setDate] = useState(parseDate('2024-06-15'));
return (
<DateField
label="Selected Date"
value={date}
onChange={setDate}
/>
);
}
```
### Example: Compact size [#example-compact-size]
```tsx
import { DateField } from '@accelint/design-toolkit';
<DateField
label="Due Date"
size="small"
description="When is this task due?"
/>
```
> **Good to know:** In `small` size, the label is not visually displayed but is used for the `aria-label` attribute for accessibility.
### Example: Full month names [#example-full-month-names]
```tsx
import { DateField } from '@accelint/design-toolkit';
<DateField
label="Meeting Date"
shortMonth={false}
/>
```
### Example: Read-only state [#example-read-only-state]
```tsx
import { DateField } from '@accelint/design-toolkit';
import { parseDate } from '@internationalized/date';
<DateField
label="Created At"
value={parseDate('2024-01-15')}
isReadOnly
/>
```
### Example: With description and error [#example-with-description-and-error]
```tsx
import { DateField } from '@accelint/design-toolkit';
import { useState } from 'react';
export function ValidatedDateField() {
const [isInvalid, setIsInvalid] = useState(false);
return (
<DateField
label="Appointment Date"
description="Select a date for your appointment"
isInvalid={isInvalid}
errorMessage={isInvalid ? 'Date is outside available range' : undefined}
onChange={(value) => {
// Validate date
setIsInvalid(value.year < 2024);
}}
/>
);
}
```
### Example: Custom styling [#example-custom-styling]
```tsx
import { DateField } from '@accelint/design-toolkit';
<DateField
label="Custom Styled Date"
classNames={{
field: 'custom-field-class',
input: 'custom-input-class',
segment: 'custom-segment-class',
}}
/>
```
## Related [#related]
* [TimeField](../time-field/index.md) - Time input with segmented editing
* [Label](../label/index.md) - Label component used internally
* [Icon](../icon/index.md) - Icon component for calendar icon
# Dialog (/docs/toolkits/design-toolkit/components/dialog)
## Usage [#usage]
```tsx
import { Dialog, DialogTrigger, DialogTitle, DialogContent, DialogFooter, Button } from '@accelint/design-toolkit';
export function MyComponent() {
return (
<DialogTrigger>
<Button>Open Dialog</Button>
<Dialog>
<DialogTitle>Confirm Action</DialogTitle>
<DialogContent>
<p>Are you sure you want to continue?</p>
</DialogContent>
<DialogFooter>
<Button variant="flat">Cancel</Button>
<Button>Confirm</Button>
</DialogFooter>
</Dialog>
</DialogTrigger>
);
}
```
## Reference [#reference]
```typescript
interface DialogProps extends Omit<ModalOverlayProps, 'children' | 'className'> {
children?: React.ReactNode | ((opts: { close: () => void }) => React.ReactNode);
classNames?: {
overlay?: string;
modal?: string;
dialog?: string;
};
parentRef?: RefObject<HTMLElement | null>;
size?: 'small' | 'large';
isDismissable?: boolean;
isKeyboardDismissDisabled?: boolean;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| --------------------------- | ----------------------------------------------------------------------- | --------- | -------- |
| `children` | `React.ReactNode \| ((opts: { close: () => void }) => React.ReactNode)` | - | Yes |
| `size` | `'small' \| 'large'` | `'small'` | No |
| `classNames` | `{ overlay?: string; modal?: string; dialog?: string }` | - | No |
| `parentRef` | `RefObject<HTMLElement \| null>` | - | No |
| `isDismissable` | `boolean` | `true` | No |
| `isKeyboardDismissDisabled` | `boolean` | `false` | No |
#### `size` [#size]
Controls the width and padding of the dialog:
* `small` - Compact width, suitable for simple confirmations and short forms
* `large` - Wider width, suitable for complex forms and detailed content
#### `children` [#children]
Can be static React elements or a render function that receives a `close` callback for programmatic dismissal.
#### `classNames` [#classnames]
Custom class names for styling sub-elements:
* `overlay` - The backdrop behind the dialog
* `modal` - The modal container
* `dialog` - The dialog content wrapper
#### `parentRef` [#parentref]
Reference to a parent element for portal rendering. When provided, the dialog renders into the specified container instead of document body.
#### `isDismissable` [#isdismissable]
When `true`, clicking the backdrop or pressing Escape closes the dialog. Set to `false` for critical dialogs that require explicit user action.
### Inherited Props [#inherited-props]
Dialog inherits props from React Aria's `ModalOverlay`, including:
* `onOpenChange` - Called when dialog opens or closes
* `isOpen` - Controlled open state (use with `DialogTrigger`)
See [React Aria Modal](https://react-spectrum.adobe.com/react-aria/Modal.html) for full API reference.
## Sub-components [#sub-components]
### DialogTrigger [#dialogtrigger]
Manages dialog open/close state and trigger behavior.
```tsx
<DialogTrigger>
<Button>Open</Button>
<Dialog>...</Dialog>
</DialogTrigger>
```
### DialogTitle [#dialogtitle]
Semantic heading element for dialog titles. Renders as `<h2>` with proper accessibility attributes.
```tsx
<DialogTitle>Confirm Action</DialogTitle>
```
### DialogContent [#dialogcontent]
Wrapper for the main dialog content with appropriate spacing and styling.
```tsx
<DialogContent>
<p>Your content goes here...</p>
</DialogContent>
```
### DialogFooter [#dialogfooter]
Container for dialog action buttons. Automatically sizes child Button components based on dialog size and wires up default close behavior.
```tsx
<DialogFooter>
<Button variant="flat">Cancel</Button>
<Button>Confirm</Button>
</DialogFooter>
```
## Examples [#examples]
### Example: Basic confirmation dialog [#example-basic-confirmation-dialog]
```tsx
import { Dialog, DialogTrigger, DialogTitle, DialogContent, DialogFooter, Button } from '@accelint/design-toolkit';
<DialogTrigger>
<Button color="critical">Delete Account</Button>
<Dialog>
<DialogTitle>Delete Account</DialogTitle>
<DialogContent>
<p>This action cannot be undone. Are you sure you want to delete your account?</p>
</DialogContent>
<DialogFooter>
<Button variant="flat">Cancel</Button>
<Button color="critical">Delete</Button>
</DialogFooter>
</Dialog>
</DialogTrigger>
```
### Example: Large dialog with form [#example-large-dialog-with-form]
```tsx
import { Dialog, DialogTrigger, DialogTitle, DialogContent, DialogFooter, Button, TextField } from '@accelint/design-toolkit';
<DialogTrigger>
<Button>Edit Profile</Button>
<Dialog size="large">
<DialogTitle>Edit Profile</DialogTitle>
<DialogContent>
<TextField label="Full Name" defaultValue="John Doe" />
<TextField label="Email" type="email" defaultValue="john@example.com" />
<TextField label="Bio" defaultValue="..." />
</DialogContent>
<DialogFooter>
<Button variant="flat">Cancel</Button>
<Button>Save Changes</Button>
</DialogFooter>
</Dialog>
</DialogTrigger>
```
### Example: Using close callback [#example-using-close-callback]
```tsx
import { Dialog, DialogTrigger, DialogTitle, DialogContent, DialogFooter, Button } from '@accelint/design-toolkit';
<DialogTrigger>
<Button>Show Dialog</Button>
<Dialog>
{({ close }) => (
<>
<DialogTitle>Custom Close Behavior</DialogTitle>
<DialogContent>
<p>You can access the close function directly.</p>
</DialogContent>
<DialogFooter>
<Button onPress={() => {
console.log('Custom logic here');
close();
}}>
Close with Custom Logic
</Button>
</DialogFooter>
</>
)}
</Dialog>
</DialogTrigger>
```
### Example: Non-dismissable dialog [#example-non-dismissable-dialog]
```tsx
import { Dialog, DialogTrigger, DialogTitle, DialogContent, DialogFooter, Button } from '@accelint/design-toolkit';
<DialogTrigger>
<Button>Start Process</Button>
<Dialog isDismissable={false}>
<DialogTitle>Processing...</DialogTitle>
<DialogContent>
<p>This dialog cannot be dismissed until the process completes.</p>
</DialogContent>
<DialogFooter>
<Button>Complete</Button>
</DialogFooter>
</Dialog>
</DialogTrigger>
```
> **Good to know:** When `isDismissable={false}`, users cannot close the dialog by clicking the backdrop or pressing Escape. Always provide an explicit action button to close the dialog.
### Example: Controlled dialog state [#example-controlled-dialog-state]
```tsx
import { useState } from 'react';
import { Dialog, DialogTrigger, DialogTitle, DialogContent, DialogFooter, Button } from '@accelint/design-toolkit';
function ControlledDialog() {
const [open, setOpen] = useState(false);
return (
<>
<Button onPress={() => setOpen(true)}>Open Dialog</Button>
<DialogTrigger isOpen={open} onOpenChange={setOpen}>
<Button isDisabled>Trigger (Disabled)</Button>
<Dialog>
<DialogTitle>Controlled Dialog</DialogTitle>
<DialogContent>
<p>This dialog is controlled by external state.</p>
</DialogContent>
<DialogFooter>
<Button>Close</Button>
</DialogFooter>
</Dialog>
</DialogTrigger>
</>
);
}
```
### Example: Custom portal target [#example-custom-portal-target]
```tsx
import { useRef } from 'react';
import { Dialog, DialogTrigger, DialogTitle, DialogContent, DialogFooter, Button } from '@accelint/design-toolkit';
function PortalDialog() {
const containerRef = useRef<HTMLDivElement>(null);
return (
<div className="flex">
<div>
<DialogTrigger>
<Button>Open Dialog</Button>
<Dialog parentRef={containerRef}>
<DialogTitle>Local Portal</DialogTitle>
<DialogContent>
<p>This dialog renders into a custom container.</p>
</DialogContent>
<DialogFooter>
<Button>Close</Button>
</DialogFooter>
</Dialog>
</DialogTrigger>
</div>
<div ref={containerRef} className="relative" />
</div>
);
}
```
### Example: Custom styling [#example-custom-styling]
```tsx
import { Dialog, DialogTrigger, DialogTitle, DialogContent, DialogFooter, Button } from '@accelint/design-toolkit';
<DialogTrigger>
<Button>Open Styled Dialog</Button>
<Dialog
classNames={{
overlay: 'bg-black/80',
modal: 'backdrop-blur-sm',
dialog: 'border-2 border-primary shadow-2xl'
}}
>
<DialogTitle>Custom Styled</DialogTitle>
<DialogContent>
<p>This dialog has custom styling applied.</p>
</DialogContent>
<DialogFooter>
<Button>Close</Button>
</DialogFooter>
</Dialog>
</DialogTrigger>
```
## Related [#related]
* [Button](../button/index.md) - Primary action component used in dialog triggers and footers
* [TextField](../text-field/index.md) - Form input component for dialog content
* [Popover](../popover/index.md) - Non-modal overlay for contextual content
# Divider (/docs/toolkits/design-toolkit/components/divider)
A visual separator component for creating clear boundaries between content sections. Supports both horizontal and vertical orientations with automatic flexbox detection.
## Usage [#usage]
```tsx
import { Divider } from '@accelint/design-toolkit';
export function MyLayout() {
return (
<div>
<section>Content above</section>
<Divider />
<section>Content below</section>
</div>
);
}
```
## Reference [#reference]
```typescript
interface DividerProps {
orientation?: 'horizontal' | 'vertical';
className?: string;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ------------- | ---------------------------- | -------------- | -------- |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | No |
| `className` | `string` | - | No |
#### `orientation` [#orientation]
Controls the divider's orientation:
* `horizontal` - Horizontal line separator (default)
* `vertical` - Vertical line separator
> **Good to know:** The Divider automatically detects when its parent uses flexbox layout and adjusts its stretching behavior accordingly for proper sizing in vertical orientation.
## Examples [#examples]
### Example: Basic horizontal divider [#example-basic-horizontal-divider]
```tsx
import { Divider } from '@accelint/design-toolkit';
<div>
<p>First paragraph</p>
<Divider />
<p>Second paragraph</p>
</div>
```
### Example: Vertical divider [#example-vertical-divider]
```tsx
import { Divider } from '@accelint/design-toolkit';
<div className="flex items-center gap-4">
<span>Left content</span>
<Divider orientation="vertical" />
<span>Right content</span>
</div>
```
### Example: In a navigation bar [#example-in-a-navigation-bar]
```tsx
import { Divider } from '@accelint/design-toolkit';
<nav className="flex items-center gap-4">
<a href="/home">Home</a>
<Divider orientation="vertical" />
<a href="/about">About</a>
<Divider orientation="vertical" />
<a href="/contact">Contact</a>
</nav>
```
### Example: Sectioning content [#example-sectioning-content]
```tsx
import { Divider } from '@accelint/design-toolkit';
<article>
<header>
<h1>Article Title</h1>
</header>
<Divider />
<section>
<h2>Introduction</h2>
<p>Content here...</p>
</section>
<Divider />
<section>
<h2>Main Content</h2>
<p>More content...</p>
</section>
<Divider />
<footer>
<p>Article footer</p>
</footer>
</article>
```
### Example: Custom styled divider [#example-custom-styled-divider]
```tsx
import { Divider } from '@accelint/design-toolkit';
<Divider className="border-t-2 border-dashed border-blue-500 my-8" />
```
### Example: In a card layout [#example-in-a-card-layout]
```tsx
import { Divider } from '@accelint/design-toolkit';
<div className="card">
<div className="card-header">
<h3>Card Title</h3>
</div>
<Divider />
<div className="card-body">
<p>Card content goes here</p>
</div>
<Divider />
<div className="card-footer">
<button>Action</button>
</div>
</div>
```
### Example: Flex container with vertical dividers [#example-flex-container-with-vertical-dividers]
```tsx
import { Divider } from '@accelint/design-toolkit';
<div className="flex h-64">
<div className="flex-1 p-4">Column 1</div>
<Divider orientation="vertical" />
<div className="flex-1 p-4">Column 2</div>
<Divider orientation="vertical" />
<div className="flex-1 p-4">Column 3</div>
</div>
```
> **Good to know:** When a Divider with `orientation="vertical"` is placed in a flex container, it automatically detects the flexbox layout and adjusts its height to stretch appropriately.
## Related [#related]
* [Menu](../menu/index.md) - Menu component that uses dividers for separating groups
# Drawer (/docs/toolkits/design-toolkit/components/drawer)
## Usage [#usage]
```tsx
import {
Drawer,
DrawerLayout,
DrawerLayoutMain,
DrawerPanel,
DrawerView,
DrawerHeader,
DrawerContent,
DrawerTrigger,
Button
} from '@accelint/design-toolkit';
import { uuid } from '@accelint/core';
const ids = { drawer: uuid(), view: uuid() };
export function MyDrawer() {
return (
<DrawerLayout push="left">
<DrawerLayoutMain>
<DrawerTrigger for={`open:${ids.view}`}>
<Button>Open Drawer</Button>
</DrawerTrigger>
</DrawerLayoutMain>
<Drawer id={ids.drawer} defaultView={ids.view}>
<DrawerPanel>
<DrawerView id={ids.view}>
<DrawerHeader title="Drawer Title" />
<DrawerContent>Your content here</DrawerContent>
</DrawerView>
</DrawerPanel>
</Drawer>
</DrawerLayout>
);
}
```
## Reference [#reference]
```typescript
interface DrawerProps {
id: UniqueId;
children: React.ReactNode;
className?: string;
defaultView?: UniqueId;
placement?: 'left' | 'right' | 'top' | 'bottom';
size?: 'small' | 'medium' | 'large';
onChange?: (view: UniqueId | null) => void;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ------------- | ---------------------------------------- | ---------- | -------- |
| `id` | `UniqueId` | - | Yes |
| `children` | `React.ReactNode` | - | Yes |
| `className` | `string` | - | No |
| `defaultView` | `UniqueId` | - | No |
| `placement` | `'left' \| 'right' \| 'top' \| 'bottom'` | `'left'` | No |
| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | No |
| `onChange` | `(view: UniqueId \| null) => void` | - | No |
#### `id` [#id]
Unique identifier for the drawer. Required for event handling and targeted control from outside the drawer's context.
#### `defaultView` [#defaultview]
ID of the view to display initially when the drawer opens. Must match the `id` of a `DrawerView` child component.
#### `placement` [#placement]
Edge of the viewport the drawer slides from:
* `left` - Slides from the left edge (default)
* `right` - Slides from the right edge
* `top` - Slides from the top edge
* `bottom` - Slides from the bottom edge
#### `size` [#size]
Controls the drawer panel dimensions:
* `small` - Narrower panel for simple content
* `medium` - Default balanced width
* `large` - Wider panel for complex content
#### `onChange` [#onchange]
Callback invoked when the active view changes. Receives the new view ID or `null` when all views are closed.
## Examples [#examples]
### Example: Basic drawer with trigger [#example-basic-drawer-with-trigger]
```tsx
import {
Drawer,
DrawerLayout,
DrawerLayoutMain,
DrawerPanel,
DrawerView,
DrawerHeader,
DrawerContent,
DrawerTrigger,
Button
} from '@accelint/design-toolkit';
import { uuid } from '@accelint/core';
const ids = { drawer: uuid(), view: uuid() };
<DrawerLayout>
<DrawerLayoutMain>
<DrawerTrigger for={`open:${ids.view}`}>
<Button>Open</Button>
</DrawerTrigger>
</DrawerLayoutMain>
<Drawer id={ids.drawer} defaultView={ids.view}>
<DrawerPanel>
<DrawerView id={ids.view}>
<DrawerHeader title="Settings" />
<DrawerContent>
<p>Drawer content goes here</p>
</DrawerContent>
</DrawerView>
</DrawerPanel>
</Drawer>
</DrawerLayout>
```
### Example: Right-side drawer [#example-right-side-drawer]
```tsx
import { Drawer, DrawerPanel, DrawerView, DrawerHeader, DrawerContent } from '@accelint/design-toolkit';
import { uuid } from '@accelint/core';
const ids = { drawer: uuid(), view: uuid() };
<Drawer id={ids.drawer} defaultView={ids.view} placement="right">
<DrawerPanel>
<DrawerView id={ids.view}>
<DrawerHeader title="Notifications" />
<DrawerContent>
<p>Your notifications</p>
</DrawerContent>
</DrawerView>
</DrawerPanel>
</Drawer>
```
### Example: Multiple stacked views [#example-multiple-stacked-views]
```tsx
import {
Drawer,
DrawerPanel,
DrawerView,
DrawerHeader,
DrawerContent,
DrawerTrigger,
Button
} from '@accelint/design-toolkit';
import { uuid } from '@accelint/core';
const ids = {
drawer: uuid(),
main: uuid(),
settings: uuid()
};
<Drawer id={ids.drawer} defaultView={ids.main}>
<DrawerPanel>
<DrawerView id={ids.main}>
<DrawerHeader title="Menu" />
<DrawerContent>
<DrawerTrigger for={ids.settings}>
<Button>Open Settings</Button>
</DrawerTrigger>
</DrawerContent>
</DrawerView>
<DrawerView id={ids.settings}>
<DrawerHeader title="Settings" />
<DrawerContent>
<p>Settings content</p>
</DrawerContent>
</DrawerView>
</DrawerPanel>
</Drawer>
```
### Example: Controlled drawer state [#example-controlled-drawer-state]
```tsx
import { Drawer, DrawerPanel, DrawerView, DrawerHeader, DrawerContent } from '@accelint/design-toolkit';
import { uuid } from '@accelint/core';
import { useState } from 'react';
function ControlledDrawer() {
const ids = { drawer: uuid(), view: uuid() };
const [activeView, setActiveView] = useState(ids.view);
return (
<Drawer
id={ids.drawer}
defaultView={ids.view}
onChange={setActiveView}
>
<DrawerPanel>
<DrawerView id={ids.view}>
<DrawerHeader title="Controlled" />
<DrawerContent>
<p>Active: {activeView}</p>
</DrawerContent>
</DrawerView>
</DrawerPanel>
</Drawer>
);
}
```
### Example: Large drawer with push behavior [#example-large-drawer-with-push-behavior]
```tsx
import {
Drawer,
DrawerLayout,
DrawerLayoutMain,
DrawerPanel,
DrawerView,
DrawerHeader,
DrawerContent
} from '@accelint/design-toolkit';
import { uuid } from '@accelint/core';
const ids = { drawer: uuid(), view: uuid() };
<DrawerLayout push="left">
<DrawerLayoutMain>
<p>Main content is pushed when drawer opens</p>
</DrawerLayoutMain>
<Drawer id={ids.drawer} defaultView={ids.view} size="large">
<DrawerPanel>
<DrawerView id={ids.view}>
<DrawerHeader title="Wide Panel" />
<DrawerContent>
<p>Large drawer content</p>
</DrawerContent>
</DrawerView>
</DrawerPanel>
</Drawer>
</DrawerLayout>
```
### Example: Drawer with menu navigation [#example-drawer-with-menu-navigation]
```tsx
import {
Drawer,
DrawerPanel,
DrawerView,
DrawerMenu,
DrawerMenuItem,
DrawerHeader,
DrawerContent,
Icon
} from '@accelint/design-toolkit';
import { Settings, Home } from '@accelint/icons';
import { uuid } from '@accelint/core';
const ids = {
drawer: uuid(),
home: uuid(),
settings: uuid()
};
<Drawer id={ids.drawer} defaultView={ids.home}>
<DrawerMenu>
<DrawerMenuItem for={ids.home} textValue="Home">
<Icon><Home /></Icon>
</DrawerMenuItem>
<DrawerMenuItem for={ids.settings} textValue="Settings">
<Icon><Settings /></Icon>
</DrawerMenuItem>
</DrawerMenu>
<DrawerPanel>
<DrawerView id={ids.home}>
<DrawerHeader title="Home" />
<DrawerContent>Home content</DrawerContent>
</DrawerView>
<DrawerView id={ids.settings}>
<DrawerHeader title="Settings" />
<DrawerContent>Settings content</DrawerContent>
</DrawerView>
</DrawerPanel>
</Drawer>
```
## Multi-Part Structure [#multi-part-structure]
Drawer is a multi-part component composed of several sub-components:
* **Drawer** - Root container that manages view state and event handling
* **DrawerLayout** - Layout wrapper that configures drawer positioning behavior
* **DrawerLayoutMain** - Main content area adjacent to drawers
* **DrawerPanel** - Container for drawer views
* **DrawerView** - Individual stacked view within the drawer
* **DrawerHeader** - Header section with title and optional actions
* **DrawerContent** - Scrollable content area
* **DrawerFooter** - Footer section for actions
* **DrawerMenu** - Icon-based navigation menu
* **DrawerMenuItem** - Individual menu item
* **DrawerTrigger** - Button that controls drawer open/close/navigation
* **DrawerClose** - Close button component
* **DrawerBack** - Back navigation button
See individual component pages for detailed documentation.
## Event System [#event-system]
Drawer uses a global event bus for programmatic control:
### Simple Events (context-aware) [#simple-events-context-aware]
* `'back'` - Navigate to previous view in stack
* `'clear'` - Clear all views from stack
* `'close'` - Close the current drawer
* `'reset'` - Reset stack to default view
* `viewId` - Push a specific view onto the stack
### Targeted Events (external control) [#targeted-events-external-control]
* `'open:${viewId}'` - Clear stack and open specific view
* `'close:${drawerId}'` - Close specific drawer
* `'toggle:${viewId}'` - Toggle view open/closed
* `'back:${drawerId}'` - Navigate back in specific drawer
* `'clear:${drawerId}'` - Clear specific drawer stack
* `'reset:${drawerId}'` - Reset specific drawer stack
### Chained Events [#chained-events]
Pass an array to trigger multiple events sequentially:
```tsx
<DrawerTrigger for={['reset', ids.settings, ids.profile]}>
<Button>Reset & Open Settings</Button>
</DrawerTrigger>
```
> **Good to know:** Simple events only work within the context of a Drawer. Use targeted events to control drawers from outside their component tree.
## Related [#related]
* [DrawerLayout](./layout.mdx) - Layout configuration component
* [DrawerView](./view.mdx) - Individual stacked view
* [DrawerTrigger](./trigger.mdx) - Trigger button component
* [ViewStack](../view-stack/index.mdx) - Underlying view stack implementation
# FloatingCard (/docs/toolkits/design-toolkit/components/floating-card)
Renders children into a resizable, draggable floating panel using React portals. Requires `FloatingCardProvider` as an ancestor.
## Usage [#usage]
```tsx
import { FloatingCard, FloatingCardProvider } from '@accelint/design-toolkit';
import { uuid } from '@accelint/core';
import { useState } from 'react';
const cardId = uuid();
export function App() {
const [isOpen, setIsOpen] = useState(true);
return (
<FloatingCardProvider>
<FloatingCard
id={cardId}
title="Settings Panel"
isOpen={isOpen}
>
<p>Panel content goes here</p>
</FloatingCard>
<button onClick={() => setIsOpen(!isOpen)}>
Toggle Panel
</button>
</FloatingCardProvider>
);
}
```
## Reference [#reference]
```typescript
interface FloatingCardProps {
id: UniqueId;
children: React.ReactNode;
title?: string;
isOpen?: boolean;
initialDimensions?: { width: number; height: number };
initialPosition?: { x: number; y: number };
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ------------------- | ----------------------------------- | ----------------------------- | -------- |
| `id` | `UniqueId` | - | Yes |
| `children` | `React.ReactNode` | - | Yes |
| `title` | `string` | - | No |
| `isOpen` | `boolean` | `true` | No |
| `initialDimensions` | `{ width: number; height: number }` | `{ width: 300, height: 400 }` | No |
| `initialPosition` | `{ x: number; y: number }` | - | No |
#### `id` [#id]
Unique identifier for the floating card. Must be stable across renders.
#### `title` [#title]
Title displayed in the floating card header. When omitted the header shows no title and the card is announced as "Floating card".
#### `isOpen` [#isopen]
Controls whether the floating card is rendered. When `false`, the card is closed and removed from the DOM.
#### `initialDimensions` [#initialdimensions]
Initial width and height of the floating card in pixels.
#### `initialPosition` [#initialposition]
Initial x and y coordinates for the floating card's top-left corner. If not specified, the card appears at a default position.
## Examples [#examples]
### Example: Basic floating card [#example-basic-floating-card]
```tsx
import { FloatingCard, FloatingCardProvider } from '@accelint/design-toolkit';
import { uuid } from '@accelint/core';
const cardId = uuid();
<FloatingCardProvider>
<FloatingCard id={cardId} title="My Panel">
<div className="p-4">
<h2>Panel Content</h2>
<p>This is a floating panel</p>
</div>
</FloatingCard>
</FloatingCardProvider>
```
### Example: Custom dimensions [#example-custom-dimensions]
```tsx
import { FloatingCard, FloatingCardProvider } from '@accelint/design-toolkit';
import { uuid } from '@accelint/core';
const cardId = uuid();
<FloatingCardProvider>
<FloatingCard
id={cardId}
title="Wide Panel"
initialDimensions={{ width: 600, height: 400 }}
>
<p>This panel is 600x400 pixels</p>
</FloatingCard>
</FloatingCardProvider>
```
### Example: Positioned card [#example-positioned-card]
```tsx
import { FloatingCard, FloatingCardProvider } from '@accelint/design-toolkit';
import { uuid } from '@accelint/core';
const cardId = uuid();
<FloatingCardProvider>
<FloatingCard
id={cardId}
title="Positioned Panel"
initialPosition={{ x: 100, y: 100 }}
>
<p>This panel starts at (100, 100)</p>
</FloatingCard>
</FloatingCardProvider>
```
### Example: Controlled visibility [#example-controlled-visibility]
```tsx
import { FloatingCard, FloatingCardProvider, Button } from '@accelint/design-toolkit';
import { uuid } from '@accelint/core';
import { useState } from 'react';
function ControlledPanel() {
const cardId = uuid();
const [isOpen, setIsOpen] = useState(false);
return (
<FloatingCardProvider>
<Button onPress={() => setIsOpen(true)}>
Open Panel
</Button>
<FloatingCard
id={cardId}
title="Controlled Panel"
isOpen={isOpen}
>
<div className="p-4">
<p>Panel content</p>
<Button onPress={() => setIsOpen(false)}>
Close
</Button>
</div>
</FloatingCard>
</FloatingCardProvider>
);
}
```
### Example: Multiple floating cards [#example-multiple-floating-cards]
```tsx
import { FloatingCard, FloatingCardProvider } from '@accelint/design-toolkit';
import { uuid } from '@accelint/core';
const ids = {
card1: uuid(),
card2: uuid(),
card3: uuid(),
};
<FloatingCardProvider>
<FloatingCard
id={ids.card1}
title="Panel 1"
initialPosition={{ x: 50, y: 50 }}
>
<p>First panel</p>
</FloatingCard>
<FloatingCard
id={ids.card2}
title="Panel 2"
initialPosition={{ x: 400, y: 50 }}
>
<p>Second panel</p>
</FloatingCard>
<FloatingCard
id={ids.card3}
title="Panel 3"
initialPosition={{ x: 750, y: 50 }}
>
<p>Third panel</p>
</FloatingCard>
</FloatingCardProvider>
```
### Example: Large settings panel [#example-large-settings-panel]
```tsx
import { FloatingCard, FloatingCardProvider } from '@accelint/design-toolkit';
import { uuid } from '@accelint/core';
const cardId = uuid();
<FloatingCardProvider>
<FloatingCard
id={cardId}
title="Application Settings"
initialDimensions={{ width: 800, height: 600 }}
>
<div className="p-6 space-y-4">
<section>
<h3>General</h3>
{/* Settings controls */}
</section>
<section>
<h3>Advanced</h3>
{/* More settings */}
</section>
</div>
</FloatingCard>
</FloatingCardProvider>
```
## Behavior [#behavior]
### Registration and Lifecycle [#registration-and-lifecycle]
FloatingCard registers itself with the floating card engine on mount and:
1. Creates a floating panel if `isOpen` is `true`
2. Updates the panel title when `title` prop changes
3. Closes the panel when `isOpen` becomes `false`
4. Cleans up when unmounted (handled at provider level)
### Portal Rendering [#portal-rendering]
Children are rendered into the floating card's DOM node via React portals, allowing content to "escape" its parent container while maintaining React context.
### Drag and Resize [#drag-and-resize]
Floating cards are:
* **Draggable** - Users can drag the header to reposition
* **Resizable** - Users can drag edges/corners to resize
* **Stackable** - Multiple cards can overlap, with z-index management
### Lock Behavior [#lock-behavior]
Floating cards have `locked: 'no-drop-target'` preventing them from being docked into other layouts. They remain free-floating at all times.
## Requirements [#requirements]
### FloatingCardProvider [#floatingcardprovider]
FloatingCard must be used within a `FloatingCardProvider`:
```tsx
import { FloatingCardProvider } from '@accelint/design-toolkit';
<FloatingCardProvider>
{/* Your app with FloatingCard components */}
</FloatingCardProvider>
```
Without the provider, floating cards will not render.
### Stable IDs [#stable-ids]
Use stable unique IDs (via `uuid()` or similar) defined outside component render:
```tsx
// ✅ Good - stable ID
const cardId = uuid();
function App() {
return <FloatingCard id={cardId} />;
}
// ❌ Bad - new ID every render
function App() {
return <FloatingCard id={uuid()} />;
}
```
## Related [#related]
* [FloatingCardProvider](./provider.mdx) - Required context provider
# Hero (/docs/toolkits/design-toolkit/components/hero)
## Usage [#usage]
```tsx
import { Hero, HeroTitle, HeroSubtitle, Icon } from '@accelint/design-toolkit';
import { Placeholder } from '@accelint/icons';
export function PageHeader() {
return (
<Hero>
<Icon><Placeholder /></Icon>
<HeroTitle>Primary Title</HeroTitle>
<HeroSubtitle>Secondary information</HeroSubtitle>
</Hero>
);
}
```
## Reference [#reference]
```typescript
interface HeroProps {
children: React.ReactNode;
classNames?: {
hero?: string;
icon?: string;
title?: string;
subtitle?: string;
};
compact?: boolean;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ------------ | ----------------- | ------- | -------- |
| `children` | `React.ReactNode` | - | Yes |
| `classNames` | `object` | - | No |
| `compact` | `boolean` | `false` | No |
#### `children` [#children]
Child components are automatically organized by type:
* **Icon** - Only one allowed, displayed prominently
* **HeroTitle** - Only one allowed, primary heading
* **HeroSubtitle** - Any number allowed, secondary content
#### `classNames` [#classnames]
Custom CSS classes for Hero sub-elements:
* `hero` - Root container
* `icon` - Icon wrapper
* `title` - Title heading
* `subtitle` - Subtitle text elements
#### `compact` [#compact]
Controls layout mode:
* `false` - Stack layout with vertical arrangement and larger icon (default)
* `true` - Grid layout with horizontal arrangement and smaller icon
## Examples [#examples]
### Example: Basic hero with icon and content [#example-basic-hero-with-icon-and-content]
```tsx
import { Hero, HeroTitle, HeroSubtitle, Icon } from '@accelint/design-toolkit';
import { Settings } from '@accelint/icons';
<Hero>
<Icon><Settings /></Icon>
<HeroTitle>Settings</HeroTitle>
<HeroSubtitle>Manage your application preferences</HeroSubtitle>
</Hero>
```
### Example: Compact grid layout [#example-compact-grid-layout]
```tsx
import { Hero, HeroTitle, HeroSubtitle, Icon } from '@accelint/design-toolkit';
import { User } from '@accelint/icons';
<Hero compact>
<Icon><User /></Icon>
<HeroTitle>Profile</HeroTitle>
<HeroSubtitle>View and edit your profile information</HeroSubtitle>
</Hero>
```
### Example: Multiple subtitle lines [#example-multiple-subtitle-lines]
```tsx
import { Hero, HeroTitle, HeroSubtitle, Icon } from '@accelint/design-toolkit';
import { Dashboard } from '@accelint/icons';
<Hero>
<Icon><Dashboard /></Icon>
<HeroTitle>Dashboard</HeroTitle>
<HeroSubtitle>Welcome back, John Doe</HeroSubtitle>
<HeroSubtitle>Last login: 2 hours ago</HeroSubtitle>
</Hero>
```
### Example: Custom styling [#example-custom-styling]
```tsx
import { Hero, HeroTitle, HeroSubtitle, Icon } from '@accelint/design-toolkit';
import { Info } from '@accelint/icons';
<Hero
classNames={{
hero: 'bg-blue-50 p-4 rounded',
title: 'text-blue-900',
subtitle: 'text-blue-700'
}}
>
<Icon><Info /></Icon>
<HeroTitle>Information</HeroTitle>
<HeroSubtitle>Important details about your account</HeroSubtitle>
</Hero>
```
### Example: Without icon [#example-without-icon]
```tsx
import { Hero, HeroTitle, HeroSubtitle } from '@accelint/design-toolkit';
<Hero>
<HeroTitle>Text Only Header</HeroTitle>
<HeroSubtitle>No icon required for simple headers</HeroSubtitle>
</Hero>
```
## Layout Modes [#layout-modes]
### Stack Layout (default) [#stack-layout-default]
Vertical arrangement with larger icon:
```
┌─────────────┐
│ [Icon] │
│ (large) │
├─────────────┤
│ Title │
├─────────────┤
│ Subtitle │
└─────────────┘
```
### Grid Layout (compact) [#grid-layout-compact]
Horizontal arrangement with smaller icon:
```
┌──────┬────────────┐
│ │ Title │
│[Icon]├────────────┤
│ │ Subtitle │
└──────┴────────────┘
```
## Multi-Part Structure [#multi-part-structure]
Hero is composed of several sub-components:
* **Hero** - Root container with layout management
* **HeroTitle** - Primary heading (automatically uses h2)
* **HeroSubtitle** - Secondary content (can have multiple)
> **Good to know:** Hero automatically provides context for Icon sizing and Heading level, so you don't need to specify these props manually.
## Related [#related]
* [HeroTitle](./title.mdx) - Primary heading component
* [HeroSubtitle](./subtitle.mdx) - Secondary content component
* [Icon](../icon/index.mdx) - Icon component with automatic sizing
# Icon (/docs/toolkits/design-toolkit/components/icon)
## Usage [#usage]
```tsx
import { Icon } from '@accelint/design-toolkit';
import { Settings } from '@accelint/icons';
export function MyComponent() {
return (
<Icon>
<Settings />
</Icon>
);
}
```
## Reference [#reference]
```typescript
interface IconProps extends ComponentPropsWithRef<'span'> {
size?: 'xsmall' | 'small' | 'medium' | 'large';
children: React.ReactNode;
className?: string;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ----------- | -------------------------------------------- | ---------- | -------- |
| `children` | `React.ReactNode` | - | Yes |
| `size` | `'xsmall' \| 'small' \| 'medium' \| 'large'` | `'medium'` | No |
| `className` | `string` | - | No |
#### `size` [#size]
Controls the icon dimensions. Available sizes:
* `xsmall` - Extra small for compact UI elements
* `small` - Small for inline text or dense layouts
* `medium` - Default size for most use cases
* `large` - Large for prominent visual elements
#### Context-aware sizing [#context-aware-sizing]
Icon automatically inherits sizing from parent components like Button via `IconProvider`. When used inside a Button, the icon size matches the button size automatically.
## Examples [#examples]
### Example: Basic icon [#example-basic-icon]
```tsx
import { Icon } from '@accelint/design-toolkit';
import { Home } from '@accelint/icons';
<Icon>
<Home />
</Icon>
```
### Example: Different sizes [#example-different-sizes]
```tsx
import { Icon } from '@accelint/design-toolkit';
import { Star } from '@accelint/icons';
<>
<Icon size="xsmall"><Star /></Icon>
<Icon size="small"><Star /></Icon>
<Icon size="medium"><Star /></Icon>
<Icon size="large"><Star /></Icon>
</>
```
### Example: Icon in button (automatic sizing) [#example-icon-in-button-automatic-sizing]
```tsx
import { Button, Icon } from '@accelint/design-toolkit';
import { Plus, Save } from '@accelint/icons';
<>
<Button size="small">
<Icon><Plus /></Icon>
Add
</Button>
<Button size="large">
<Icon><Save /></Icon>
Save Changes
</Button>
</>
```
> **Good to know:** When Icon is used inside a Button, the icon automatically inherits the button's size. No need to set the size prop manually.
### Example: Custom styling [#example-custom-styling]
```tsx
import { Icon } from '@accelint/design-toolkit';
import { Alert } from '@accelint/icons';
<Icon className="text-critical">
<Alert />
</Icon>
```
### Example: Icon-only button [#example-icon-only-button]
```tsx
import { Button, Icon } from '@accelint/design-toolkit';
import { Settings } from '@accelint/icons';
<Button variant="icon" aria-label="Settings">
<Icon><Settings /></Icon>
</Button>
```
## Related [#related]
* [Button](../button/index.md) - Button component that provides icon sizing context
* [IconProvider](./context.md) - Context provider for managing icon sizes
* [@accelint/icons](../../packages/icons/index.md) - Icon library package
# Input (/docs/toolkits/design-toolkit/components/input)
A flexible text input component with enhanced features including auto-sizing, clear functionality, and integrated validation states.
## Usage [#usage]
```tsx
import { Input } from '@accelint/design-toolkit';
export function MyComponent() {
return <Input placeholder="Enter text..." />;
}
```
## Reference [#reference]
```typescript
interface InputProps extends AriaInputProps {
classNames?: {
container?: string;
sizer?: string;
input?: string;
clear?: string;
prefix?: string;
suffix?: string;
};
autoSize?: boolean;
prefix?: ReactNode;
size?: 'medium' | 'small';
suffix?: ReactNode;
isClearable?: boolean;
isInvalid?: boolean;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| -------------- | -------------------------------------------- | ---------- | -------- |
| `placeholder` | `string` | - | No |
| `value` | `string` | - | No |
| `defaultValue` | `string` | `''` | No |
| `size` | `'small' \| 'medium'` | `'medium'` | No |
| `isClearable` | `boolean` | `true` | No |
| `isInvalid` | `boolean` | `false` | No |
| `autoSize` | `boolean` | `false` | No |
| `prefix` | `ReactNode` | - | No |
| `suffix` | `ReactNode` | - | No |
| `classNames` | `object` | - | No |
| `disabled` | `boolean` | `false` | No |
| `readOnly` | `boolean` | `false` | No |
| `required` | `boolean` | `false` | No |
| `type` | `string` | `'text'` | No |
| `onChange` | `(e: ChangeEvent<HTMLInputElement>) => void` | - | No |
#### `size` [#size]
Controls input padding and font size:
* `small` - Compact size for space-constrained layouts
* `medium` - Default size for most use cases
#### `isClearable` [#isclearable]
When `true`, displays a clear button (×) when the input has a value. The button can be pressed to clear the input. Pressing Escape also clears the input when `isClearable` is enabled.
#### `autoSize` [#autosize]
When `true`, the input automatically adjusts its width based on content length. Useful for inline editing scenarios where the input should expand/contract with text.
#### `prefix` and `suffix` [#prefix-and-suffix]
Display content before or after the input. Commonly used for icons, labels, or units:
```tsx
<Input prefix={<Icon><Search /></Icon>} placeholder="Search..." />
<Input suffix="kg" type="number" />
```
#### `classNames` [#classnames]
Granular control over styling for each subcomponent:
* `container` - Outer wrapper
* `sizer` - Internal sizing wrapper
* `input` - The input element itself
* `clear` - Clear button
* `prefix` - Prefix content wrapper
* `suffix` - Suffix content wrapper
### Inherited Props [#inherited-props]
Input inherits all props from React Aria's `Input` component. See [React Aria Input](https://react-spectrum.adobe.com/react-aria/TextField.html) for additional props.
## Examples [#examples]
### Example: Basic input [#example-basic-input]
```tsx
import { Input } from '@accelint/design-toolkit';
<Input placeholder="Enter your name" />
```
### Example: Controlled input [#example-controlled-input]
```tsx
import { Input } from '@accelint/design-toolkit';
import { useState } from 'react';
function MyComponent() {
const [value, setValue] = useState('');
return (
<Input
value={value}
onChange={(e) => setValue(e.target.value)}
placeholder="Type something..."
/>
);
}
```
### Example: Input with prefix icon [#example-input-with-prefix-icon]
```tsx
import { Input, Icon } from '@accelint/design-toolkit';
import { Search } from '@accelint/icons';
<Input
prefix={<Icon><Search /></Icon>}
placeholder="Search..."
/>
```
### Example: Input with suffix unit [#example-input-with-suffix-unit]
```tsx
import { Input } from '@accelint/design-toolkit';
<Input
type="number"
suffix="kg"
placeholder="Enter weight"
/>
```
### Example: Auto-sizing input [#example-auto-sizing-input]
```tsx
import { Input } from '@accelint/design-toolkit';
<Input
autoSize
defaultValue="This input grows with content"
placeholder="Type here..."
/>
```
### Example: Non-clearable input [#example-non-clearable-input]
```tsx
import { Input } from '@accelint/design-toolkit';
<Input
isClearable={false}
defaultValue="Cannot clear this"
/>
```
### Example: Invalid state [#example-invalid-state]
```tsx
import { Input } from '@accelint/design-toolkit';
<Input
isInvalid
defaultValue="invalid@"
placeholder="Enter email"
/>
```
### Example: Custom styling with classNames [#example-custom-styling-with-classnames]
```tsx
import { Input } from '@accelint/design-toolkit';
<Input
classNames={{
container: 'border-2 border-accent',
input: 'font-mono',
clear: 'text-critical'
}}
placeholder="Styled input"
/>
```
> **Good to know:** When `readOnly` is true, the clear button is hidden even if `isClearable` is true.
## Related [#related]
* [TextField](../text-field/index.md) - Complete form field with label and validation
* [SearchField](../search-field/index.md) - Specialized input for search functionality
* [Icon](../icon/index.md) - Icon component for prefix/suffix content
# Label (/docs/toolkits/design-toolkit/components/label)
A semantic label component for form elements with automatic handling of required/optional states. Integrates with React Aria form components to ensure proper accessibility and screen reader support.
## Usage [#usage]
```tsx
import { Label } from '@accelint/design-toolkit';
export function MyForm() {
return <Label>Username</Label>;
}
```
## Reference [#reference]
```typescript
interface LabelProps {
children: React.ReactNode;
className?: string;
isDisabled?: boolean;
isRequired?: boolean;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ------------ | ----------------- | ------- | -------- |
| `children` | `React.ReactNode` | - | Yes |
| `className` | `string` | - | No |
| `isDisabled` | `boolean` | `false` | No |
| `isRequired` | `boolean` | `false` | No |
#### `isRequired` [#isrequired]
Controls the required/optional indicator:
* When `true`: No text is appended (assumes required fields don't need explicit indication)
* When `false`: Appends " (optional)" to the label text
#### `isDisabled` [#isdisabled]
Sets the label to a disabled visual state, typically used when the associated form control is disabled.
### Inherited Props [#inherited-props]
Label inherits all props from React Aria's `Label` component, including:
* `htmlFor` - Associates label with a form control by ID
* `id` - Unique identifier for the label
See [React Aria Label](https://react-spectrum.adobe.com/react-aria/Label.html) for full API reference.
## Examples [#examples]
### Example: Basic label [#example-basic-label]
```tsx
import { Label } from '@accelint/design-toolkit';
<Label>Username</Label>
```
### Example: Required field [#example-required-field]
```tsx
import { Label } from '@accelint/design-toolkit';
<Label isRequired>Email Address</Label>
```
> **Good to know:** When `isRequired` is `true`, the label displays only the text without any suffix. The design philosophy is that required fields should be unmarked, while optional fields are explicitly indicated.
### Example: Optional field [#example-optional-field]
```tsx
import { Label } from '@accelint/design-toolkit';
<Label>Phone Number</Label>
```
This automatically appends " (optional)" to indicate the field is not required.
### Example: Disabled label [#example-disabled-label]
```tsx
import { Label } from '@accelint/design-toolkit';
<Label isDisabled>Inactive Field</Label>
```
### Example: With TextField [#example-with-textfield]
```tsx
import { Label, TextField } from '@accelint/design-toolkit';
<TextField label="Email" isRequired>
<Label isRequired>Email</Label>
<Input type="email" />
</TextField>
```
> **Good to know:** Most form components like `TextField`, `DateField`, and `SelectField` use Label internally, so you typically don't need to render it directly.
### Example: Custom styling [#example-custom-styling]
```tsx
import { Label } from '@accelint/design-toolkit';
<Label className="text-lg font-bold text-blue-600">
Custom Styled Label
</Label>
```
### Example: Explicitly associated with input [#example-explicitly-associated-with-input]
```tsx
import { Label } from '@accelint/design-toolkit';
<div>
<Label htmlFor="email-input" isRequired>Email</Label>
<input id="email-input" type="email" />
</div>
```
## Related [#related]
* [TextField](../text-field/index.md) - Text input with built-in label
* [DateField](../date-field/index.md) - Date input with built-in label
* [SelectField](../select-field/index.md) - Select input with built-in label
# Link (/docs/toolkits/design-toolkit/components/link)
## Usage [#usage]
```tsx
import { Link } from '@accelint/design-toolkit';
export function MyNav() {
return <Link href="/dashboard">Go to Dashboard</Link>;
}
```
## Reference [#reference]
```typescript
interface LinkProps {
href: string;
children: React.ReactNode;
className?: string;
allowsVisited?: boolean;
isVisited?: boolean;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| --------------- | ----------------- | ------- | -------- |
| `href` | `string` | - | Yes |
| `children` | `React.ReactNode` | - | Yes |
| `className` | `string` | - | No |
| `allowsVisited` | `boolean` | `false` | No |
| `isVisited` | `boolean` | `false` | No |
#### `allowsVisited` [#allowsvisited]
When `true`, enables visited state styling. Must be combined with `isVisited` to actually apply visited styles.
#### `isVisited` [#isvisited]
Controls whether the link displays in a visited state. Only takes effect when `allowsVisited` is also `true`.
### Inherited Props [#inherited-props]
Link inherits all props from React Aria's `Link` component, including:
* `target` - Specifies where to open the linked document (`_blank`, `_self`, etc.)
* `rel` - Relationship between current and linked document
* `download` - Prompts to download the linked URL
* `isDisabled` - Disables the link
See [React Aria Link](https://react-spectrum.adobe.com/react-aria/Link.html) for full API reference.
## Examples [#examples]
### Example: Basic internal link [#example-basic-internal-link]
```tsx
import { Link } from '@accelint/design-toolkit';
<Link href="/about">About Us</Link>
```
### Example: External link [#example-external-link]
```tsx
import { Link } from '@accelint/design-toolkit';
<Link href="https://example.com" target="_blank" rel="noopener noreferrer">
Visit Example
</Link>
```
> **Good to know:** When using `target="_blank"`, always include `rel="noopener noreferrer"` for security.
### Example: Link with visited state [#example-link-with-visited-state]
```tsx
import { Link } from '@accelint/design-toolkit';
import { useState } from 'react';
export function VisitedLink() {
const [visited, setVisited] = useState(false);
return (
<Link
href="/page"
allowsVisited
isVisited={visited}
onPress={() => setVisited(true)}
>
Click to visit
</Link>
);
}
```
### Example: Disabled link [#example-disabled-link]
```tsx
import { Link } from '@accelint/design-toolkit';
<Link href="/unavailable" isDisabled>
Coming Soon
</Link>
```
### Example: Link with icon [#example-link-with-icon]
```tsx
import { Link, Icon } from '@accelint/design-toolkit';
import { ExternalLink } from '@accelint/icons';
<Link href="https://example.com" target="_blank" rel="noopener noreferrer">
Visit Site
<Icon size="small">
<ExternalLink />
</Icon>
</Link>
```
### Example: Download link [#example-download-link]
```tsx
import { Link } from '@accelint/design-toolkit';
<Link href="/files/document.pdf" download>
Download PDF
</Link>
```
### Example: Navigation link with custom styling [#example-navigation-link-with-custom-styling]
```tsx
import { Link } from '@accelint/design-toolkit';
<Link
href="/dashboard"
className="font-bold text-blue-600 hover:text-blue-800 underline"
>
Dashboard
</Link>
```
### Example: Router integration [#example-router-integration]
```tsx
import { Link } from '@accelint/design-toolkit';
import { useNavigate } from 'react-router-dom';
export function RouterLink() {
const navigate = useNavigate();
return (
<Link
href="/profile"
onPress={(e) => {
e.preventDefault();
navigate('/profile');
}}
>
View Profile
</Link>
);
}
```
> **Good to know:** The Link component uses `onPress` from React Aria, which handles both mouse clicks and keyboard activation (Enter/Space), providing better accessibility than `onClick`.
## Related [#related]
* [Button](../button/index.md) - Button component for actions
* [Icon](../icon/index.md) - Icon component for link decorations
# List (/docs/toolkits/design-toolkit/components/list)
Flexible grid list component for selectable items with rich content, selection support, and keyboard navigation.
## Usage [#usage]
```tsx
import { List, ListItem, ListItemContent, ListItemTitle } from '@accelint/design-toolkit';
export function FileList() {
return (
<List aria-label="Files">
<ListItem>
<ListItemContent>
<ListItemTitle>Document.pdf</ListItemTitle>
</ListItemContent>
</ListItem>
<ListItem>
<ListItemContent>
<ListItemTitle>Spreadsheet.xlsx</ListItemTitle>
</ListItemContent>
</ListItem>
</List>
);
}
```
## Reference [#reference]
```typescript
interface ListProps<T> {
children: React.ReactNode | ((item: T) => React.ReactNode);
className?: string;
variant?: 'cozy' | 'compact' | 'crammed';
selectionMode?: 'none' | 'single' | 'multiple';
'aria-label': string;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| --------------- | --------------------------------------------------- | -------- | -------- |
| `children` | `React.ReactNode \| ((item: T) => React.ReactNode)` | - | Yes |
| `className` | `string` | - | No |
| `variant` | `'cozy' \| 'compact' \| 'crammed'` | `'cozy'` | No |
| `selectionMode` | `'none' \| 'single' \| 'multiple'` | - | No |
| `aria-label` | `string` | - | Yes |
#### `variant` [#variant]
Visual density variant that controls spacing and sizing:
* `cozy` - Default comfortable spacing with large icons
* `compact` - Reduced spacing for denser layouts
* `crammed` - Minimal spacing for maximum density with small icons
The `variant` automatically sizes nested `Icon` components via context.
#### `selectionMode` [#selectionmode]
Controls item selection behavior:
* `none` - No selection allowed (default)
* `single` - Only one item can be selected
* `multiple` - Multiple items can be selected
#### `aria-label` [#aria-label]
Required accessible label for the list. Describes the list's purpose to screen readers.
## Examples [#examples]
### Example: Basic list with items [#example-basic-list-with-items]
```tsx
import { List, ListItem, ListItemContent, ListItemTitle } from '@accelint/design-toolkit';
<List aria-label="Tasks">
<ListItem>
<ListItemContent>
<ListItemTitle>Complete documentation</ListItemTitle>
</ListItemContent>
</ListItem>
<ListItem>
<ListItemContent>
<ListItemTitle>Review pull requests</ListItemTitle>
</ListItemContent>
</ListItem>
</List>
```
### Example: List with descriptions and icons [#example-list-with-descriptions-and-icons]
```tsx
import { List, ListItem, ListItemContent, ListItemTitle, ListItemDescription, Icon } from '@accelint/design-toolkit';
import { File, Folder } from '@accelint/icons';
<List aria-label="Files" variant="cozy">
<ListItem>
<Icon><Folder /></Icon>
<ListItemContent>
<ListItemTitle>Projects</ListItemTitle>
<ListItemDescription>24 items</ListItemDescription>
</ListItemContent>
</ListItem>
<ListItem>
<Icon><File /></Icon>
<ListItemContent>
<ListItemTitle>README.md</ListItemTitle>
<ListItemDescription>2.4 KB</ListItemDescription>
</ListItemContent>
</ListItem>
</List>
```
### Example: Selectable list [#example-selectable-list]
```tsx
import { List, ListItem, ListItemContent, ListItemTitle } from '@accelint/design-toolkit';
import { useState } from 'react';
function SelectableFileList() {
const [selected, setSelected] = useState(new Set());
return (
<List
aria-label="Files"
selectionMode="multiple"
selectedKeys={selected}
onSelectionChange={setSelected}
>
<ListItem id="file1">
<ListItemContent>
<ListItemTitle>File 1.txt</ListItemTitle>
</ListItemContent>
</ListItem>
<ListItem id="file2">
<ListItemContent>
<ListItemTitle>File 2.txt</ListItemTitle>
</ListItemContent>
</ListItem>
</List>
);
}
```
### Example: Compact variant [#example-compact-variant]
```tsx
import { List, ListItem, ListItemContent, ListItemTitle } from '@accelint/design-toolkit';
<List aria-label="Compact list" variant="compact">
<ListItem>
<ListItemContent>
<ListItemTitle>Compact Item 1</ListItemTitle>
</ListItemContent>
</ListItem>
<ListItem>
<ListItemContent>
<ListItemTitle>Compact Item 2</ListItemTitle>
</ListItemContent>
</ListItem>
</List>
```
### Example: Dynamic list with data [#example-dynamic-list-with-data]
```tsx
import { List, ListItem, ListItemContent, ListItemTitle } from '@accelint/design-toolkit';
const files = [
{ id: '1', name: 'Document.pdf', size: '1.2 MB' },
{ id: '2', name: 'Image.png', size: '3.4 MB' },
{ id: '3', name: 'Video.mp4', size: '24.5 MB' },
];
<List items={files} aria-label="Files">
{(file) => (
<ListItem id={file.id}>
<ListItemContent>
<ListItemTitle>{file.name}</ListItemTitle>
<ListItemDescription>{file.size}</ListItemDescription>
</ListItemContent>
</ListItem>
)}
</List>
```
### Example: List with actions [#example-list-with-actions]
```tsx
import { List, ListItem, ListItemContent, ListItemTitle, ListItemActions, Button } from '@accelint/design-toolkit';
import { Delete, Edit } from '@accelint/icons';
<List aria-label="Tasks with actions">
<ListItem>
<ListItemContent>
<ListItemTitle>Task 1</ListItemTitle>
</ListItemContent>
<ListItemActions>
<Button variant="icon" aria-label="Edit">
<Icon><Edit /></Icon>
</Button>
<Button variant="icon" aria-label="Delete">
<Icon><Delete /></Icon>
</Button>
</ListItemActions>
</ListItem>
</List>
```
## Multi-Part Structure [#multi-part-structure]
List is composed of several sub-components:
* **List** - Root container with selection and keyboard navigation
* **ListItem** - Individual list item
* **ListItemContent** - Content wrapper for titles and descriptions
* **ListItemTitle** - Primary text label
* **ListItemDescription** - Secondary description text
* **ListItemActions** - Action buttons visible on hover/focus
> **Good to know:** List must have an explicit height constraint. Wrap it in a container with defined dimensions or use utility classes like `h-[400px]`.
## Related [#related]
* [ListItem](./item.mdx) - Individual list item component
* [ListItemContent](./item-content.mdx) - Content wrapper
* [Icon](../icon/index.mdx) - Icon component with automatic sizing
# MediaControls (/docs/toolkits/design-toolkit/components/media-controls)
Container for media playback controls that composes sub-components into a cohesive control bar. Must be used within a MediaProvider context from media-chrome.
## Usage [#usage]
```tsx
import { MediaProvider, MediaControls, PlayButton, TimeDisplay, TimeRange } from '@accelint/design-toolkit';
export function VideoPlayer() {
return (
<MediaProvider>
<video slot="media" src="/video.mp4" />
<MediaControls>
<PlayButton />
<TimeDisplay mode="current" />
<TimeRange />
<TimeDisplay mode="duration" />
</MediaControls>
</MediaProvider>
);
}
```
## Reference [#reference]
```typescript
interface MediaControlsProps {
children: React.ReactNode;
className?: string;
classNames?: {
container?: string;
};
isDisabled?: boolean;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ------------ | ------------------------ | ------- | -------- |
| `children` | `React.ReactNode` | - | Yes |
| `className` | `string` | - | No |
| `classNames` | `{ container?: string }` | - | No |
| `isDisabled` | `boolean` | `false` | No |
#### `children` [#children]
Media control sub-components to compose into the control bar. Common components include:
* `PlayButton` - Play/pause toggle
* `SeekButton` - Skip forward/backward
* `TimeDisplay` - Current time or duration
* `TimeRange` - Seek slider
* `MuteButton` - Mute/unmute toggle
* `VolumeSlider` - Volume control
* `PlaybackRateButton` - Playback speed selector
#### `isDisabled` [#isdisabled]
When `true`, disables all child controls via context. Useful for loading states or when media is unavailable.
#### `classNames` [#classnames]
Custom CSS classes for sub-elements:
* `container` - Root container element
## Examples [#examples]
### Example: Basic video controls [#example-basic-video-controls]
```tsx
import {
MediaProvider,
MediaControls,
PlayButton,
TimeDisplay,
TimeRange,
MuteButton
} from '@accelint/design-toolkit';
<MediaProvider>
<video slot="media" src="/video.mp4" />
<MediaControls>
<PlayButton />
<TimeDisplay mode="current" />
<TimeRange />
<TimeDisplay mode="duration" />
<MuteButton />
</MediaControls>
</MediaProvider>
```
### Example: Audio player with seek controls [#example-audio-player-with-seek-controls]
```tsx
import {
MediaProvider,
MediaControls,
SeekButton,
PlayButton,
TimeDisplay,
PlaybackRateButton
} from '@accelint/design-toolkit';
<MediaProvider>
<audio slot="media" src="/audio.mp3" />
<MediaControls>
<SeekButton direction="backward" seekOffset={15} />
<PlayButton />
<SeekButton direction="forward" seekOffset={15} />
<TimeDisplay mode="current" />
<PlaybackRateButton rates={[0.5, 1, 1.5, 2]} />
</MediaControls>
</MediaProvider>
```
### Example: Full-featured video player [#example-full-featured-video-player]
```tsx
import {
MediaProvider,
MediaControls,
PlayButton,
SeekButton,
TimeDisplay,
TimeRange,
MuteButton,
VolumeSlider,
PlaybackRateButton,
FullscreenButton
} from '@accelint/design-toolkit';
<MediaProvider>
<video slot="media" src="/video.mp4" />
<MediaControls>
<PlayButton />
<SeekButton direction="backward" seekOffset={10} />
<SeekButton direction="forward" seekOffset={10} />
<TimeDisplay mode="current" />
<TimeRange />
<TimeDisplay mode="duration" />
<MuteButton />
<VolumeSlider />
<PlaybackRateButton rates={[0.5, 0.75, 1, 1.25, 1.5, 2]} />
<FullscreenButton />
</MediaControls>
</MediaProvider>
```
### Example: Disabled controls [#example-disabled-controls]
```tsx
import { MediaProvider, MediaControls, PlayButton, TimeRange } from '@accelint/design-toolkit';
<MediaProvider>
<video slot="media" src="/video.mp4" />
<MediaControls isDisabled>
<PlayButton />
<TimeRange />
</MediaControls>
</MediaProvider>
```
### Example: Custom styled controls [#example-custom-styled-controls]
```tsx
import { MediaProvider, MediaControls, PlayButton, TimeRange } from '@accelint/design-toolkit';
<MediaProvider>
<video slot="media" src="/video.mp4" />
<MediaControls
className="bg-gray-900 rounded-lg p-2"
classNames={{ container: 'gap-4' }}
>
<PlayButton />
<TimeRange />
</MediaControls>
</MediaProvider>
```
### Example: Minimal audio controls [#example-minimal-audio-controls]
```tsx
import { MediaProvider, MediaControls, PlayButton, TimeDisplay } from '@accelint/design-toolkit';
<MediaProvider>
<audio slot="media" src="/audio.mp3" />
<MediaControls>
<PlayButton />
<TimeDisplay mode="current" />
</MediaControls>
</MediaProvider>
```
### Example: Podcast player [#example-podcast-player]
```tsx
import {
MediaProvider,
MediaControls,
SeekButton,
PlayButton,
TimeDisplay,
TimeRange,
PlaybackRateButton
} from '@accelint/design-toolkit';
<MediaProvider>
<audio slot="media" src="/podcast.mp3" />
<MediaControls>
<SeekButton direction="backward" seekOffset={30} />
<PlayButton />
<SeekButton direction="forward" seekOffset={30} />
<div className="flex-1">
<TimeRange />
<div className="flex justify-between text-sm">
<TimeDisplay mode="current" />
<TimeDisplay mode="duration" />
</div>
</div>
<PlaybackRateButton rates={[1, 1.25, 1.5, 1.75, 2]} />
</MediaControls>
</MediaProvider>
```
## Control Components [#control-components]
MediaControls works with these sub-components:
* **PlayButton** - Play/pause toggle button
* **SeekButton** - Skip forward or backward by seconds
* **TimeDisplay** - Show current time or duration
* **TimeRange** - Seek slider for scrubbing
* **MuteButton** - Mute/unmute toggle
* **VolumeSlider** - Volume control slider
* **PlaybackRateButton** - Playback speed selector
* **FullscreenButton** - Fullscreen toggle
All control components automatically connect to the media element via MediaProvider context.
## Requirements [#requirements]
### MediaProvider [#mediaprovider]
MediaControls must be used within a `MediaProvider` from media-chrome:
```tsx
import { MediaProvider } from '@accelint/design-toolkit';
<MediaProvider>
<video slot="media" src="/video.mp4" />
<MediaControls>
{/* controls */}
</MediaControls>
</MediaProvider>
```
The component will throw an error if used outside this context.
### Media Element [#media-element]
The `MediaProvider` requires a media element (audio or video) with `slot="media"`:
```tsx
<MediaProvider>
<video slot="media" src="/video.mp4" />
{/* or */}
<audio slot="media" src="/audio.mp3" />
<MediaControls>{/* controls */}</MediaControls>
</MediaProvider>
```
## Behavior [#behavior]
### Context Propagation [#context-propagation]
MediaControls provides context to child components via `MediaControlsProvider`, propagating:
* `isDisabled` state to all child controls
* Media state from MediaProvider (play/pause, time, volume, etc.)
### Automatic State Binding [#automatic-state-binding]
Control components automatically bind to media state:
* **PlayButton** reflects playing/paused state
* **TimeDisplay** updates with current time
* **TimeRange** reflects and controls playback position
* **MuteButton** reflects muted state
* **VolumeSlider** reflects and controls volume level
> **Good to know:** MediaControls uses media-chrome under the hood for robust media state management and accessibility features.
## Related [#related]
* [PlayButton](./play-button.mdx) - Play/pause control
* [TimeRange](./time-range.mdx) - Seek slider
* [MediaProvider](./provider.mdx) - Required context provider
* [media-chrome](https://www.media-chrome.org/) - Underlying media controls library
# Menu (/docs/toolkits/design-toolkit/components/menu)
Menu is composed of multiple subcomponents: `Menu`, `MenuTrigger`, `MenuItem`, `MenuItemLabel`, `MenuItemDescription`, `MenuSeparator`, `MenuSection`, and `MenuSubmenu`. Compose with `Hotkey` and `Icon` components for enhanced functionality.
> **Good to know:** Menu includes its own internal Popover. Do NOT wrap Menu in a Popover component—use the `popoverProps` prop to configure placement and positioning.
## Usage [#usage]
```tsx
import {
Menu,
MenuTrigger,
MenuItem,
MenuItemLabel,
Button,
} from '@accelint/design-toolkit';
<MenuTrigger>
<Button>Open Menu</Button>
<Menu>
<MenuItem>
<MenuItemLabel>Edit</MenuItemLabel>
</MenuItem>
<MenuItem>
<MenuItemLabel>Copy</MenuItemLabel>
</MenuItem>
<MenuItem>
<MenuItemLabel>Delete</MenuItemLabel>
</MenuItem>
</Menu>
</MenuTrigger>
```
## Reference [#reference]
### Menu [#menu]
```typescript
interface MenuProps<T> extends AriaMenuProps<T> {
classNames?: {
menu?: AriaMenuProps<T>['className'];
popover?: PopoverProps['className'];
};
popoverProps?: Omit<AriaPopoverProps, 'children' | 'className'>;
variant?: 'compact' | 'cozy';
ref?: RefAttributes<HTMLDivElement>;
}
```
#### Props [#props]
| Prop | Type | Default | Required |
| --------------- | ----------------------------------------------- | ---------- | -------- |
| `children` | `ReactNode` | - | Yes |
| `variant` | `'cozy' \| 'compact'` | `'cozy'` | No |
| `selectionMode` | `'none' \| 'single' \| 'multiple'` | `'single'` | No |
| `popoverProps` | `Omit<PopoverProps, 'children' \| 'className'>` | - | No |
| `classNames` | `{ menu?, popover? }` | - | No |
| `onAction` | `(key: Key) => void` | - | No |
| `onClose` | `() => void` | - | No |
#### `variant` [#variant]
Controls visual density:
* `cozy` - Comfortable spacing for desktop applications
* `compact` - Reduced padding for space-constrained interfaces
#### `popoverProps` [#popoverprops]
Configure placement, offset, and positioning of the menu popover. Accepts all React Aria Popover props except `children` and `className`.
Common properties:
* `placement` - Position relative to trigger (e.g., `'bottom start'`, `'top end'`)
* `offset` - Distance in pixels from trigger
### MenuItem [#menuitem]
```typescript
interface MenuItemProps extends AriaMenuItemProps {
classNames?: {
item?: AriaMenuItemProps['className'];
text?: AriaTextProps['className'];
more?: IconProps['className'];
icon?: IconProps['className'];
hotkey?: string;
};
color?: 'info' | 'serious' | 'critical';
}
```
#### Props [#props-1]
| Prop | Type | Default | Required |
| ------------ | ----------------------------------------- | -------- | -------- |
| `children` | `ReactNode` | - | Yes |
| `color` | `'info' \| 'serious' \| 'critical'` | `'info'` | No |
| `isDisabled` | `boolean` | `false` | No |
| `classNames` | `{ item?, icon?, hotkey?, more?, text? }` | - | No |
#### `color` [#color]
Semantic color variants:
* `info` - Default neutral styling
* `serious` - Warning or cautionary actions
* `critical` - Destructive actions (delete, remove)
> **Good to know:** String children are automatically wrapped in a `MenuItemLabel`. For complex layouts, use `MenuItemLabel` and `MenuItemDescription` explicitly.
### MenuItemLabel [#menuitemlabel]
Primary text label for menu items. Renders as a Text component with the `label` slot.
#### Props [#props-2]
| Prop | Type | Default | Required |
| ----------- | ----------- | ------- | -------- |
| `children` | `ReactNode` | - | Yes |
| `className` | `string` | - | No |
### MenuItemDescription [#menuitemdescription]
Secondary descriptive text for menu items. Renders as a Text component with the `description` slot.
#### Props [#props-3]
| Prop | Type | Default | Required |
| ----------- | ----------- | ------- | -------- |
| `children` | `ReactNode` | - | Yes |
| `className` | `string` | - | No |
### MenuSection [#menusection]
Groups related menu items with an optional header.
```typescript
interface MenuSectionProps<T> extends AriaMenuSectionProps<T> {
classNames?: {
section?: AriaMenuSectionProps<T>['className'];
header?: string;
};
title?: string | ReactElement;
}
```
#### Props [#props-4]
| Prop | Type | Default | Required |
| ------------ | ------------------------ | ------- | -------- |
| `children` | `ReactNode` | - | Yes |
| `title` | `string \| ReactElement` | - | No |
| `classNames` | `{ section?, header? }` | - | No |
#### `title` [#title]
Section header displayed above grouped items. Accepts strings or React elements for custom formatting.
### MenuSeparator [#menuseparator]
Visual divider between menu items or sections.
#### Props [#props-5]
| Prop | Type | Default | Required |
| ----------- | -------- | ------- | -------- |
| `className` | `string` | - | No |
### MenuTrigger [#menutrigger]
Manages open/close state and anchors menu position. Wraps a trigger element (typically a Button) and the Menu component.
Re-exports React Aria's `MenuTrigger`. See [React Aria MenuTrigger](https://react-spectrum.adobe.com/react-aria/Menu.html#menutrigger) for full API reference.
### MenuSubmenu [#menusubmenu]
Trigger for nested submenu flyouts. Wraps a MenuItem and nested Menu to create hierarchical navigation.
Re-exports React Aria's `SubmenuTrigger`. See [React Aria Submenu](https://react-spectrum.adobe.com/react-aria/Menu.html#submenu) for full API reference.
## Examples [#examples]
### Example: Basic menu [#example-basic-menu]
```tsx
<MenuTrigger>
<Button>Open Menu</Button>
<Menu>
<MenuItem>
<MenuItemLabel>Item 1</MenuItemLabel>
</MenuItem>
<MenuSeparator />
<MenuItem>
<MenuItemLabel>Item 2</MenuItemLabel>
</MenuItem>
</Menu>
</MenuTrigger>
```
### Example: Custom placement [#example-custom-placement]
```tsx
<MenuTrigger>
<Button>Open Menu</Button>
<Menu popoverProps={{ placement: 'top end' }}>
<MenuItem>
<MenuItemLabel>Item 1</MenuItemLabel>
</MenuItem>
<MenuItem>
<MenuItemLabel>Item 2</MenuItemLabel>
</MenuItem>
</Menu>
</MenuTrigger>
```
Available placements: `'bottom'`, `'bottom start'`, `'bottom end'`, `'top'`, `'top start'`, `'top end'`, `'left'`, `'right'`, etc.
### Example: Offset control [#example-offset-control]
```tsx
<MenuTrigger>
<Button>Open Menu</Button>
<Menu popoverProps={{ placement: 'bottom', offset: 8 }}>
<MenuItem>
<MenuItemLabel>Item</MenuItemLabel>
</MenuItem>
</Menu>
</MenuTrigger>
```
### Example: Action handler [#example-action-handler]
```tsx
<MenuTrigger>
<Button>Actions</Button>
<Menu onAction={(key) => console.log('Selected:', key)}>
<MenuItem id="edit">
<MenuItemLabel>Edit</MenuItemLabel>
</MenuItem>
<MenuItem id="delete">
<MenuItemLabel>Delete</MenuItemLabel>
</MenuItem>
</Menu>
</MenuTrigger>
```
Each `MenuItem` requires an `id` prop when using `onAction`.
### Example: Selection modes [#example-selection-modes]
```tsx
// Single selection
<MenuTrigger>
<Button>Select One</Button>
<Menu
selectionMode="single"
selectedKeys={selectedKeys}
onSelectionChange={setSelectedKeys}
>
<MenuItem id="item-1">
<MenuItemLabel>Item 1</MenuItemLabel>
</MenuItem>
<MenuItem id="item-2">
<MenuItemLabel>Item 2</MenuItemLabel>
</MenuItem>
</Menu>
</MenuTrigger>
// Multiple selection
<MenuTrigger>
<Button>Select Multiple</Button>
<Menu
selectionMode="multiple"
selectedKeys={selectedKeys}
onSelectionChange={setSelectedKeys}
>
<MenuItem id="item-1">
<MenuItemLabel>Item 1</MenuItemLabel>
</MenuItem>
<MenuItem id="item-2">
<MenuItemLabel>Item 2</MenuItemLabel>
</MenuItem>
</Menu>
</MenuTrigger>
```
### Example: Sections and separators [#example-sections-and-separators]
```tsx
<MenuTrigger>
<Button>Open</Button>
<Menu>
<MenuSection title="File Actions">
<MenuItem>
<MenuItemLabel>New File</MenuItemLabel>
</MenuItem>
<MenuItem>
<MenuItemLabel>Open File</MenuItemLabel>
</MenuItem>
</MenuSection>
<MenuSeparator />
<MenuItem>
<MenuItemLabel>Settings</MenuItemLabel>
</MenuItem>
</Menu>
</MenuTrigger>
```
### Example: Color variants [#example-color-variants]
```tsx
<Menu>
<MenuItem color="info">
<MenuItemLabel>Info Action</MenuItemLabel>
</MenuItem>
<MenuItem color="serious">
<MenuItemLabel>Warning Action</MenuItemLabel>
</MenuItem>
<MenuItem color="critical">
<MenuItemLabel>Delete</MenuItemLabel>
</MenuItem>
</Menu>
```
### Example: Disabled items [#example-disabled-items]
```tsx
<Menu>
<MenuItem>
<MenuItemLabel>Available Action</MenuItemLabel>
</MenuItem>
<MenuItem isDisabled>
<MenuItemLabel>Disabled Action</MenuItemLabel>
</MenuItem>
</Menu>
```
### Example: With icons and descriptions [#example-with-icons-and-descriptions]
```tsx
import { Icon } from '@accelint/design-toolkit';
import { Placeholder } from '@accelint/icons';
<Menu>
<MenuItem>
<Icon>
<Placeholder />
</Icon>
<MenuItemLabel>Blue Jay</MenuItemLabel>
<MenuItemDescription>Cyanocitta cristata</MenuItemDescription>
</MenuItem>
</Menu>
```
### Example: Submenu [#example-submenu]
```tsx
<MenuTrigger>
<Button>Actions</Button>
<Menu>
<MenuItem>
<MenuItemLabel>New File</MenuItemLabel>
</MenuItem>
<MenuSubmenu>
<MenuItem>
<MenuItemLabel>Export</MenuItemLabel>
</MenuItem>
<Menu>
<MenuItem>
<MenuItemLabel>Export as PDF</MenuItemLabel>
</MenuItem>
<MenuItem>
<MenuItemLabel>Export as CSV</MenuItemLabel>
</MenuItem>
<MenuItem>
<MenuItemLabel>Export as JSON</MenuItemLabel>
</MenuItem>
</Menu>
</MenuSubmenu>
<MenuItem>
<MenuItemLabel>Delete</MenuItemLabel>
</MenuItem>
</Menu>
</MenuTrigger>
```
### Example: Dynamic section header [#example-dynamic-section-header]
```tsx
const CustomHeader = () => (
<div>
<div>Section Title</div>
<div>Subheader text</div>
</div>
);
<MenuTrigger>
<Button>Open Menu</Button>
<Menu>
<MenuItem>
<MenuItemLabel>Item</MenuItemLabel>
</MenuItem>
<MenuSection title={<CustomHeader />}>
<MenuItem>
<MenuItemLabel>Section Item</MenuItemLabel>
</MenuItem>
</MenuSection>
</Menu>
</MenuTrigger>
```
## Accessibility [#accessibility]
* Full keyboard navigation with Arrow keys
* Type-ahead selection support
* Submenu navigation with Arrow Left/Right
* Escape closes menu and returns focus to trigger
* Screen reader announcements for selection changes
* ARIA roles and attributes for menu structure
## Related [#related]
* [Button](../button/index.md)
* [Icon](../icon/index.md)
* [Hotkey](../hotkey/index.md)
# Notice (/docs/toolkits/design-toolkit/components/notice)
Notification component for temporary messages and alerts with optional action buttons, automatic severity icons, and close functionality.
## Usage [#usage]
```tsx
import { Notice } from '@accelint/design-toolkit';
export function Notification() {
return (
<Notice
id="notice-1"
message="Operation completed successfully"
color="normal"
/>
);
}
```
## Reference [#reference]
```typescript
interface NoticeProps {
id: string;
message: string;
classNames?: {
notice?: string;
content?: string;
message?: string;
actions?: string;
};
color?: 'normal' | 'advisory' | 'info' | 'serious' | 'critical';
primary?: ButtonProps & { children: React.ReactNode };
secondary?: ButtonProps & { children: React.ReactNode };
hideIcon?: boolean;
showClose?: boolean;
shouldCloseOnAction?: boolean;
size?: 'small' | 'medium';
onPrimaryAction?: () => void;
onSecondaryAction?: () => void;
onClose?: () => void;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| --------------------- | ------------------------------------------------------------- | ---------- | -------- |
| `id` | `string` | - | Yes |
| `message` | `string` | - | Yes |
| `classNames` | `object` | - | No |
| `color` | `'normal' \| 'advisory' \| 'info' \| 'serious' \| 'critical'` | `'info'` | No |
| `primary` | `ButtonProps & { children: ReactNode }` | - | No |
| `secondary` | `ButtonProps & { children: ReactNode }` | - | No |
| `hideIcon` | `boolean` | `false` | No |
| `showClose` | `boolean` | `false` | No |
| `shouldCloseOnAction` | `boolean` | `false` | No |
| `size` | `'small' \| 'medium'` | `'medium'` | No |
| `onPrimaryAction` | `() => void` | - | No |
| `onSecondaryAction` | `() => void` | - | No |
| `onClose` | `() => void` | - | No |
#### `id` [#id]
Unique identifier for the notice. Used for view transitions and managing multiple notices.
#### `message` [#message]
Text content to display in the notification.
#### `color` [#color]
Severity level that determines visual styling and icon:
* `normal` - Success or positive messages (green)
* `advisory` - Warnings or cautionary messages (yellow)
* `info` - Informational messages (blue, default)
* `serious` - Important cautions (orange)
* `critical` - Errors or critical issues (red)
Icons are automatically displayed based on the color variant unless `hideIcon` is true.
#### `primary` / `secondary` [#primary--secondary]
Action button configurations. Accepts Button props plus required `children` for button text. Buttons are styled to match the notice color.
#### `shouldCloseOnAction` [#shouldcloseonaction]
When `true`, the notice automatically closes after any action button is pressed. Useful for dismissing notifications after user interaction.
#### `size` [#size]
Controls notice dimensions and font size. Icons are only displayed in `medium` size.
## Examples [#examples]
### Example: Success notification [#example-success-notification]
```tsx
import { Notice } from '@accelint/design-toolkit';
<Notice
id="success-1"
message="Your changes have been saved"
color="normal"
showClose
/>
```
### Example: Warning with action [#example-warning-with-action]
```tsx
import { Notice } from '@accelint/design-toolkit';
<Notice
id="warning-1"
message="Your session will expire in 5 minutes"
color="advisory"
primary={{ children: 'Extend Session' }}
onPrimaryAction={() => console.log('Extending session')}
/>
```
### Example: Error with retry [#example-error-with-retry]
```tsx
import { Notice } from '@accelint/design-toolkit';
<Notice
id="error-1"
message="Failed to save changes"
color="critical"
primary={{ children: 'Retry' }}
secondary={{ children: 'Cancel' }}
shouldCloseOnAction
onPrimaryAction={() => console.log('Retrying')}
onSecondaryAction={() => console.log('Cancelled')}
/>
```
### Example: Info with multiple actions [#example-info-with-multiple-actions]
```tsx
import { Notice } from '@accelint/design-toolkit';
<Notice
id="info-1"
message="A new version is available"
color="info"
primary={{ children: 'Update Now' }}
secondary={{ children: 'Later' }}
showClose
onPrimaryAction={() => console.log('Updating')}
onClose={() => console.log('Dismissed')}
/>
```
### Example: Serious warning [#example-serious-warning]
```tsx
import { Notice } from '@accelint/design-toolkit';
<Notice
id="serious-1"
message="This action cannot be undone"
color="serious"
primary={{ children: 'Proceed' }}
secondary={{ children: 'Cancel' }}
onPrimaryAction={() => console.log('Proceeding')}
/>
```
### Example: Small notice without icon [#example-small-notice-without-icon]
```tsx
import { Notice } from '@accelint/design-toolkit';
<Notice
id="compact-1"
message="Quick update"
color="info"
size="small"
hideIcon
showClose
/>
```
### Example: Custom styled notice [#example-custom-styled-notice]
```tsx
import { Notice } from '@accelint/design-toolkit';
<Notice
id="custom-1"
message="Custom styled notification"
color="normal"
classNames={{
notice: 'shadow-lg rounded-lg',
message: 'font-semibold'
}}
/>
```
## Behavior [#behavior]
### Auto-closing [#auto-closing]
Notices don't auto-close by default. Implement auto-dismiss logic in your notification manager:
```tsx
import { Notice } from '@accelint/design-toolkit';
import { useEffect } from 'react';
function AutoDismissNotice({ id, message, duration = 5000 }) {
const [show, setShow] = useState(true);
useEffect(() => {
const timer = setTimeout(() => setShow(false), duration);
return () => clearTimeout(timer);
}, [duration]);
if (!show) return null;
return (
<Notice
id={id}
message={message}
onClose={() => setShow(false)}
showClose
/>
);
}
```
### View Transitions [#view-transitions]
The `id` prop is used for view transition names, enabling smooth animations when notices appear/disappear in supported browsers.
## Related [#related]
* [NoticeIcon](./notice-icon.mdx) - Icon component for severity indicators
* [Button](../button/index.mdx) - Button component used for actions
* [Toast](../toast/index.mdx) - Underlying toast implementation
# Pagination (/docs/toolkits/design-toolkit/components/pagination)
Lightweight page navigation component with prev/next controls. Displays up to 5 page numbers at a time, automatically adjusting the visible range as the user navigates.
## Usage [#usage]
```tsx
import { Pagination } from '@accelint/design-toolkit';
import { useState } from 'react';
export function MyTable() {
const [currentPage, setCurrentPage] = useState(1);
return <Pagination value={currentPage} total={10} onChange={setCurrentPage} />;
}
```
## Reference [#reference]
```typescript
interface PaginationProps {
total: number;
value?: number;
defaultValue?: number;
onChange?: (page: number) => void;
isLoading?: boolean;
classNames?: {
container?: string;
prev?: string;
pages?: string;
next?: string;
};
}
```
### Props [#props]
| Prop | Type | Default | Required |
| -------------- | ------------------------ | ------- | -------- |
| `total` | `number` | - | Yes |
| `value` | `number` | - | No |
| `defaultValue` | `number` | `1` | No |
| `onChange` | `(page: number) => void` | - | No |
| `isLoading` | `boolean` | `false` | No |
| `classNames` | `object` | - | No |
#### `total` [#total]
Total number of pages available. Determines the range of page numbers displayed.
#### `value` / `defaultValue` [#value--defaultvalue]
Current page number (1-indexed). Use `value` with `onChange` for controlled mode, or `defaultValue` for uncontrolled mode.
#### `onChange` [#onchange]
Callback fired when the user navigates to a different page. Receives the new page number (1-indexed).
#### `isLoading` [#isloading]
When `true`, disables all pagination controls to indicate loading state.
#### `classNames` [#classnames]
Custom class names for sub-elements:
* `container` - The nav container element
* `prev` - The previous button
* `pages` - The page number buttons
* `next` - The next button
## Examples [#examples]
### Example: Basic pagination [#example-basic-pagination]
```tsx
import { Pagination } from '@accelint/design-toolkit';
import { useState } from 'react';
export function BasicPagination() {
const [page, setPage] = useState(1);
return <Pagination value={page} total={10} onChange={setPage} />;
}
```
### Example: Uncontrolled pagination [#example-uncontrolled-pagination]
```tsx
import { Pagination } from '@accelint/design-toolkit';
<Pagination defaultValue={1} total={5} onChange={(page) => console.log('Page:', page)} />
```
### Example: With data fetching [#example-with-data-fetching]
```tsx
import { Pagination } from '@accelint/design-toolkit';
import { useState, useEffect } from 'react';
export function DataPagination() {
const [page, setPage] = useState(1);
const [isLoading, setIsLoading] = useState(false);
const [data, setData] = useState([]);
useEffect(() => {
setIsLoading(true);
fetchData(page)
.then(setData)
.finally(() => setIsLoading(false));
}, [page]);
return (
<>
<DataTable data={data} />
<Pagination
value={page}
total={20}
onChange={setPage}
isLoading={isLoading}
/>
</>
);
}
```
### Example: Large page count [#example-large-page-count]
```tsx
import { Pagination } from '@accelint/design-toolkit';
import { useState } from 'react';
export function LargePageCount() {
const [page, setPage] = useState(1);
return <Pagination value={page} total={100} onChange={setPage} />;
}
```
> **Good to know:** Pagination automatically shows up to 5 page numbers at a time, with ellipsis (...) indicating hidden pages. The visible range adjusts to keep the current page centered when possible.
### Example: Custom styling [#example-custom-styling]
```tsx
import { Pagination } from '@accelint/design-toolkit';
import { useState } from 'react';
export function StyledPagination() {
const [page, setPage] = useState(1);
return (
<Pagination
value={page}
total={10}
onChange={setPage}
classNames={{
container: 'bg-gray-100 p-4 rounded-lg',
prev: 'text-blue-600',
pages: 'font-bold',
next: 'text-blue-600',
}}
/>
);
}
```
### Example: With table [#example-with-table]
```tsx
import { Pagination, Table } from '@accelint/design-toolkit';
import { useState } from 'react';
export function PaginatedTable() {
const [page, setPage] = useState(1);
const pageSize = 10;
const columns = [
{ accessorKey: 'name', header: 'Name' },
{ accessorKey: 'email', header: 'Email' },
];
const allData = [...]; // Your full dataset
const paginatedData = allData.slice(
(page - 1) * pageSize,
page * pageSize
);
return (
<div>
<Table columns={columns} data={paginatedData} />
<Pagination
value={page}
total={Math.ceil(allData.length / pageSize)}
onChange={setPage}
/>
</div>
);
}
```
### Example: Disabled state [#example-disabled-state]
```tsx
import { Pagination } from '@accelint/design-toolkit';
<Pagination value={1} total={10} isLoading />
```
### Example: Single page (no navigation needed) [#example-single-page-no-navigation-needed]
```tsx
import { Pagination } from '@accelint/design-toolkit';
<Pagination value={1} total={1} onChange={() => {}} />
```
When `total` is 1, the prev/next buttons are automatically disabled.
### Example: Starting at different page [#example-starting-at-different-page]
```tsx
import { Pagination } from '@accelint/design-toolkit';
import { useState } from 'react';
export function StartMiddlePage() {
const [page, setPage] = useState(5);
return <Pagination value={page} total={10} onChange={setPage} />;
}
```
## Related [#related]
* [Button](../button/index.md) - Button component used for prev/next/page controls
* [Table](../table/index.md) - Table component that can use pagination
# Popover (/docs/toolkits/design-toolkit/components/popover)
## Usage [#usage]
```tsx
import { Popover, PopoverTrigger, PopoverTitle, PopoverContent, Button } from '@accelint/design-toolkit';
export function MyComponent() {
return (
<PopoverTrigger>
<Button>Show Info</Button>
<Popover>
<PopoverTitle>Information</PopoverTitle>
<PopoverContent>
<p>Additional information appears here</p>
</PopoverContent>
</Popover>
</PopoverTrigger>
);
}
```
## Reference [#reference]
```typescript
interface PopoverProps extends Omit<AriaPopoverProps, 'children' | 'className'> {
children?: React.ReactNode | ((opts: { close: () => void }) => React.ReactNode);
classNames?: {
popover?: string;
dialog?: string;
};
dialogProps?: Omit<DialogProps, 'children' | 'className'>;
placement?: 'top' | 'bottom' | 'left' | 'right' | 'top start' | 'top end' | 'bottom start' | 'bottom end';
offset?: number;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ------------- | ----------------------------------------------------------------------- | ---------- | -------- |
| `children` | `React.ReactNode \| ((opts: { close: () => void }) => React.ReactNode)` | - | Yes |
| `placement` | `'top' \| 'bottom' \| 'left' \| 'right' \| ...` | `'bottom'` | No |
| `offset` | `number` | `8` | No |
| `classNames` | `{ popover?: string; dialog?: string }` | - | No |
| `dialogProps` | `Omit<DialogProps, 'children' \| 'className'>` | - | No |
#### `placement` [#placement]
Controls where the popover appears relative to the trigger element. Supports basic positions (`top`, `bottom`, `left`, `right`) and alignment modifiers (`start`, `end`).
#### `children` [#children]
Can be static React elements or a render function that receives a `close` callback for programmatic dismissal.
#### `classNames` [#classnames]
Custom class names for styling sub-elements:
* `popover` - The floating popover container
* `dialog` - The dialog content wrapper
#### `offset` [#offset]
Distance in pixels between the popover and its trigger element.
### Inherited Props [#inherited-props]
Popover inherits props from React Aria's `Popover`, including:
* `shouldFlip` - Whether to flip placement when space is limited
* `containerPadding` - Minimum padding from viewport edges
See [React Aria Popover](https://react-spectrum.adobe.com/react-aria/Popover.html) for full API reference.
## Sub-components [#sub-components]
### PopoverTrigger [#popovertrigger]
Root component that manages popover state and positioning. Wraps a trigger element (first child) and the Popover (second child).
```tsx
<PopoverTrigger>
<Button>Open</Button>
<Popover>...</Popover>
</PopoverTrigger>
```
### PopoverTitle [#popovertitle]
Semantic heading element for popover titles. Provides proper accessibility attributes.
```tsx
<PopoverTitle>User Settings</PopoverTitle>
```
### PopoverContent [#popovercontent]
Main content area wrapper with appropriate spacing and styling.
```tsx
<PopoverContent>
<p>Your content goes here...</p>
</PopoverContent>
```
### PopoverFooter [#popoverfooter]
Footer area for actions or additional content.
```tsx
<PopoverFooter>
<Button>Cancel</Button>
<Button>Apply</Button>
</PopoverFooter>
```
## Examples [#examples]
### Example: Information popover [#example-information-popover]
```tsx
import { Popover, PopoverTrigger, PopoverTitle, PopoverContent, Icon } from '@accelint/design-toolkit';
import { Information } from '@accelint/icons';
<PopoverTrigger>
<Icon className="fg-primary-bold">
<Information />
</Icon>
<Popover>
<PopoverTitle>Help</PopoverTitle>
<PopoverContent>
<p>Click here to access additional information about this feature.</p>
</PopoverContent>
</Popover>
</PopoverTrigger>
```
### Example: Confirmation popover with actions [#example-confirmation-popover-with-actions]
```tsx
import { Popover, PopoverTrigger, PopoverTitle, PopoverContent, PopoverFooter, Button, Icon } from '@accelint/design-toolkit';
import { Delete } from '@accelint/icons';
<PopoverTrigger>
<Button variant="icon">
<Icon><Delete /></Icon>
</Button>
<Popover>
{({ close }) => (
<>
<PopoverTitle>Delete Item</PopoverTitle>
<PopoverContent>
<p>Are you sure you want to delete this item?</p>
</PopoverContent>
<PopoverFooter>
<Button variant="flat" onPress={close}>Cancel</Button>
<Button color="critical" onPress={close}>Delete</Button>
</PopoverFooter>
</>
)}
</Popover>
</PopoverTrigger>
```
### Example: Settings popover with form controls [#example-settings-popover-with-form-controls]
```tsx
import { Popover, PopoverTrigger, PopoverTitle, PopoverContent, Checkbox, Button } from '@accelint/design-toolkit';
<PopoverTrigger>
<Button>Settings</Button>
<Popover classNames={{ popover: 'min-w-sm' }}>
<PopoverTitle>Notification Settings</PopoverTitle>
<PopoverContent className="space-y-s">
<Checkbox>Email Notifications</Checkbox>
<Checkbox>Push Notifications</Checkbox>
<Checkbox>SMS Notifications</Checkbox>
</PopoverContent>
</Popover>
</PopoverTrigger>
```
### Example: Different placements [#example-different-placements]
```tsx
import { Popover, PopoverTrigger, PopoverContent, Button } from '@accelint/design-toolkit';
<div className="flex gap-m">
<PopoverTrigger>
<Button>Top</Button>
<Popover placement="top">
<PopoverContent>Appears above</PopoverContent>
</Popover>
</PopoverTrigger>
<PopoverTrigger>
<Button>Bottom</Button>
<Popover placement="bottom">
<PopoverContent>Appears below</PopoverContent>
</Popover>
</PopoverTrigger>
<PopoverTrigger>
<Button>Left</Button>
<Popover placement="left">
<PopoverContent>Appears to the left</PopoverContent>
</Popover>
</PopoverTrigger>
<PopoverTrigger>
<Button>Right</Button>
<Popover placement="right">
<PopoverContent>Appears to the right</PopoverContent>
</Popover>
</PopoverTrigger>
</div>
```
### Example: Custom trigger element [#example-custom-trigger-element]
```tsx
import { Popover, PopoverTrigger, PopoverContent } from '@accelint/design-toolkit';
<PopoverTrigger>
<span className="fg-primary-bold cursor-pointer">
Click for details
</span>
<Popover>
<PopoverContent>
<p>This popover can be triggered by any element.</p>
</PopoverContent>
</Popover>
</PopoverTrigger>
```
### Example: Custom offset [#example-custom-offset]
```tsx
import { Popover, PopoverTrigger, PopoverContent, Button } from '@accelint/design-toolkit';
<PopoverTrigger>
<Button>Show Popover</Button>
<Popover offset={20}>
<PopoverContent>
<p>This popover has 20px offset from the trigger.</p>
</PopoverContent>
</Popover>
</PopoverTrigger>
```
### Example: Controlled popover state [#example-controlled-popover-state]
```tsx
import { useState } from 'react';
import { Popover, PopoverTrigger, PopoverContent, Button } from '@accelint/design-toolkit';
function ControlledPopover() {
const [isOpen, setIsOpen] = useState(false);
return (
<>
<Button onPress={() => setIsOpen(true)}>Open Popover</Button>
<PopoverTrigger isOpen={isOpen} onOpenChange={setIsOpen}>
<Button isDisabled>Trigger (Disabled)</Button>
<Popover>
<PopoverContent>
<p>Controlled by external state</p>
<Button onPress={() => setIsOpen(false)}>Close</Button>
</PopoverContent>
</Popover>
</PopoverTrigger>
</>
);
}
```
> **Good to know:** Unlike Dialog, Popover is non-modal and doesn't block interaction with the rest of the page. Use Dialog for critical actions that require full user attention.
## Related [#related]
* [Dialog](../dialog/index.md) - Modal overlay for critical interactions
* [Tooltip](../tooltip/index.md) - Simple hover-based information overlay
* [Menu](../menu/index.md) - Popover-based action menu component
* [Button](../button/index.md) - Common trigger element for popovers
# Radio & RadioGroup (/docs/toolkits/design-toolkit/components/radio)
## Usage [#usage]
```tsx
import { RadioGroup, Radio } from '@accelint/design-toolkit';
export function MyForm() {
return (
<RadioGroup label="Size" onChange={(value) => setSize(value)}>
<Radio value="small">Small</Radio>
<Radio value="medium">Medium</Radio>
<Radio value="large">Large</Radio>
</RadioGroup>
);
}
```
## Reference [#reference]
### RadioGroup [#radiogroup]
```typescript
interface RadioGroupProps extends Omit<AriaRadioGroupProps, 'className'> {
label?: string;
labelPosition?: 'start' | 'end';
classNames?: {
group?: AriaRadioGroupProps['className'];
label?: LabelProps['className'];
};
}
```
#### Props [#props]
| Prop | Type | Default | Required |
| --------------- | ------------------------- | ------- | -------- |
| `label` | `string` | - | No |
| `labelPosition` | `'start' \| 'end'` | `'end'` | No |
| `classNames` | `RadioGroupClassNames` | - | No |
| `value` | `string` | - | No |
| `defaultValue` | `string` | - | No |
| `onChange` | `(value: string) => void` | - | No |
| `isDisabled` | `boolean` | `false` | No |
| `isRequired` | `boolean` | `false` | No |
### Radio [#radio]
```typescript
interface RadioProps extends Omit<AriaRadioProps, 'className'> {
labelPosition?: 'start' | 'end';
classNames?: {
radio?: AriaRadioProps['className'];
control?: string;
label?: string;
};
}
```
#### Props [#props-1]
| Prop | Type | Default | Required |
| --------------- | ------------------ | ------- | -------- |
| `value` | `string` | - | Yes |
| `children` | `React.ReactNode` | - | Yes |
| `labelPosition` | `'start' \| 'end'` | `'end'` | No |
| `classNames` | `RadioClassNames` | - | No |
| `isDisabled` | `boolean` | `false` | No |
#### `value` [#value]
Unique identifier for the radio option. Used to track selection in the RadioGroup.
#### `labelPosition` [#labelposition]
Controls the position of the label text relative to the radio control:
* `end` - Label appears after the radio control (default)
* `start` - Label appears before the radio control
When set on RadioGroup, applies to all child Radio components. Individual Radio `labelPosition` overrides the group setting.
#### `children` [#children]
Label content for the radio button. Can be text or other React elements.
### Inherited Props [#inherited-props]
RadioGroup inherits all props from React Aria's `RadioGroup` component, including:
* `value` / `defaultValue` - Controlled/uncontrolled selection
* `onChange` - Called when selection changes (receives value string)
* `isDisabled` - Disables all radio buttons in the group
* `isRequired` - Marks the group as required
* `name` - Form field name
See [React Aria RadioGroup](https://react-spectrum.adobe.com/react-aria/RadioGroup.html) for full API reference.
## Examples [#examples]
### Example: Basic radio group [#example-basic-radio-group]
```tsx
import { RadioGroup, Radio } from '@accelint/design-toolkit';
<RadioGroup label="Shipping method">
<Radio value="standard">Standard (5-7 days)</Radio>
<Radio value="express">Express (2-3 days)</Radio>
<Radio value="overnight">Overnight</Radio>
</RadioGroup>
```
### Example: Required selection [#example-required-selection]
```tsx
import { RadioGroup, Radio } from '@accelint/design-toolkit';
<RadioGroup label="Payment method" isRequired>
<Radio value="credit">Credit Card</Radio>
<Radio value="debit">Debit Card</Radio>
<Radio value="paypal">PayPal</Radio>
</RadioGroup>
```
### Example: Disabled options [#example-disabled-options]
```tsx
import { RadioGroup, Radio } from '@accelint/design-toolkit';
<RadioGroup label="Subscription tier">
<Radio value="free">Free</Radio>
<Radio value="pro">Pro</Radio>
<Radio value="enterprise" isDisabled>Enterprise (Contact sales)</Radio>
</RadioGroup>
```
### Example: Disabled group [#example-disabled-group]
```tsx
import { RadioGroup, Radio } from '@accelint/design-toolkit';
<RadioGroup label="Read-only selection" isDisabled value="medium">
<Radio value="small">Small</Radio>
<Radio value="medium">Medium</Radio>
<Radio value="large">Large</Radio>
</RadioGroup>
```
### Example: Label position - start [#example-label-position---start]
```tsx
import { RadioGroup, Radio } from '@accelint/design-toolkit';
<RadioGroup label="Notification settings" labelPosition="start">
<Radio value="all">All notifications</Radio>
<Radio value="important">Important only</Radio>
<Radio value="none">None</Radio>
</RadioGroup>
```
### Example: Controlled selection [#example-controlled-selection]
```tsx
import { useState } from 'react';
import { RadioGroup, Radio } from '@accelint/design-toolkit';
export function ControlledExample() {
const [selected, setSelected] = useState('medium');
return (
<>
<RadioGroup
label="Size"
value={selected}
onChange={setSelected}
>
<Radio value="small">Small</Radio>
<Radio value="medium">Medium</Radio>
<Radio value="large">Large</Radio>
</RadioGroup>
<p>Selected: {selected}</p>
</>
);
}
```
### Example: Without group label [#example-without-group-label]
```tsx
import { RadioGroup, Radio } from '@accelint/design-toolkit';
<RadioGroup aria-label="Theme">
<Radio value="light">Light</Radio>
<Radio value="dark">Dark</Radio>
<Radio value="auto">Auto</Radio>
</RadioGroup>
```
> **Good to know:** When omitting the visible `label`, always provide an `aria-label` for accessibility.
### Example: Custom styling [#example-custom-styling]
```tsx
import { RadioGroup, Radio } from '@accelint/design-toolkit';
<RadioGroup
label="Priority"
classNames={{
group: 'flex gap-4',
label: 'font-bold',
}}
>
<Radio
value="low"
classNames={{
radio: 'hover:bg-gray-100',
control: 'border-2',
}}
>
Low
</Radio>
<Radio value="medium">Medium</Radio>
<Radio value="high">High</Radio>
</RadioGroup>
```
### Example: Rich content labels [#example-rich-content-labels]
```tsx
import { RadioGroup, Radio } from '@accelint/design-toolkit';
<RadioGroup label="Plan">
<Radio value="free">
<div>
<strong>Free</strong>
<div className="text-sm text-gray-500">$0/month</div>
</div>
</Radio>
<Radio value="pro">
<div>
<strong>Pro</strong>
<div className="text-sm text-gray-500">$29/month</div>
</div>
</Radio>
</RadioGroup>
```
## Related [#related]
* [RadioGroup](./group.md) - Container component for Radio buttons
* [Checkbox](../checkbox/index.md) - Multi-selection alternative
* [Switch](../switch/index.md) - Binary on/off toggle
# SearchField (/docs/toolkits/design-toolkit/components/search-field)
## Usage [#usage]
```tsx
import { SearchField } from '@accelint/design-toolkit';
export function MyComponent() {
return (
<SearchField
placeholder="Search items..."
onChange={(value) => setQuery(value)}
/>
);
}
```
## Reference [#reference]
```typescript
interface SearchFieldProps extends Omit<AriaSearchFieldProps, 'className' | 'pattern' | 'type'> {
variant?: 'filled' | 'outline';
isLoading?: boolean;
inputProps?: Omit<InputProps, 'type'>;
classNames?: {
field?: AriaSearchFieldProps['className'];
input?: InputProps['className'];
clear?: ButtonProps['className'];
loading?: IconProps['className'];
search?: IconProps['className'];
};
}
```
### Props [#props]
| Prop | Type | Default | Required |
| -------------- | ------------------------- | ----------- | -------- |
| `variant` | `'filled' \| 'outline'` | `'outline'` | No |
| `isLoading` | `boolean` | `false` | No |
| `inputProps` | `InputProps` | - | No |
| `classNames` | `SearchFieldClassNames` | - | No |
| `value` | `string` | - | No |
| `defaultValue` | `string` | - | No |
| `onChange` | `(value: string) => void` | - | No |
| `onSubmit` | `(value: string) => void` | - | No |
| `isDisabled` | `boolean` | `false` | No |
#### `variant` [#variant]
Visual style variant:
* `outline` - Border with transparent background (default)
* `filled` - Solid background with subtle border
#### `isLoading` [#isloading]
Displays a loading spinner instead of the clear button when `true`. Useful for showing async search progress.
#### `inputProps` [#inputprops]
Props passed directly to the underlying `Input` component, including:
* `placeholder` - Placeholder text
* `autoComplete` - Browser autocomplete hint
* `maxLength` - Maximum character length
#### `classNames` [#classnames]
Custom CSS class names for search field elements:
* `field` - Container element
* `input` - Input element
* `clear` - Clear button element
* `loading` - Loading spinner icon element
* `search` - Search icon element
### Inherited Props [#inherited-props]
SearchField inherits all props from React Aria's `SearchField` component, including:
* `value` / `defaultValue` - Controlled/uncontrolled value
* `onChange` - Called when value changes (receives string)
* `onSubmit` - Called when Enter is pressed or search is submitted
* `onClear` - Called when clear button is pressed
* `isDisabled` - Disables the search field
See [React Aria SearchField](https://react-spectrum.adobe.com/react-aria/SearchField.html) for full API reference.
## Examples [#examples]
### Example: Basic search field [#example-basic-search-field]
```tsx
import { SearchField } from '@accelint/design-toolkit';
<SearchField
placeholder="Search..."
onChange={(value) => setQuery(value)}
/>
```
### Example: Filled variant [#example-filled-variant]
```tsx
import { SearchField } from '@accelint/design-toolkit';
<SearchField
variant="filled"
placeholder="Search products..."
onChange={(value) => handleSearch(value)}
/>
```
### Example: With loading state [#example-with-loading-state]
```tsx
import { useState } from 'react';
import { SearchField } from '@accelint/design-toolkit';
export function AsyncSearch() {
const [query, setQuery] = useState('');
const [isLoading, setIsLoading] = useState(false);
const handleSearch = async (value: string) => {
setQuery(value);
setIsLoading(true);
try {
const results = await searchApi(value);
setResults(results);
} finally {
setIsLoading(false);
}
};
return (
<SearchField
value={query}
onChange={handleSearch}
isLoading={isLoading}
placeholder="Search..."
/>
);
}
```
### Example: With submit handler [#example-with-submit-handler]
```tsx
import { SearchField } from '@accelint/design-toolkit';
<SearchField
placeholder="Search..."
onSubmit={(value) => {
console.log('Searching for:', value);
performSearch(value);
}}
/>
```
> **Good to know:** `onSubmit` is called when the user presses Enter or clicks a submit button. Use this for explicit search actions.
### Example: Controlled search [#example-controlled-search]
```tsx
import { useState } from 'react';
import { SearchField } from '@accelint/design-toolkit';
export function ControlledSearch() {
const [query, setQuery] = useState('');
return (
<>
<SearchField
value={query}
onChange={setQuery}
placeholder="Type to search..."
/>
<p>Current query: {query}</p>
</>
);
}
```
### Example: With clear handler [#example-with-clear-handler]
```tsx
import { SearchField } from '@accelint/design-toolkit';
<SearchField
placeholder="Search..."
onChange={(value) => setQuery(value)}
onClear={() => {
console.log('Search cleared');
resetResults();
}}
/>
```
### Example: Disabled state [#example-disabled-state]
```tsx
import { SearchField } from '@accelint/design-toolkit';
<SearchField
placeholder="Search disabled"
isDisabled
/>
```
### Example: With aria-label [#example-with-aria-label]
```tsx
import { SearchField } from '@accelint/design-toolkit';
<SearchField
aria-label="Search products"
placeholder="Enter product name..."
/>
```
> **Good to know:** Always provide an `aria-label` or visible label for accessibility.
### Example: Debounced search [#example-debounced-search]
```tsx
import { useState, useEffect } from 'react';
import { SearchField } from '@accelint/design-toolkit';
export function DebouncedSearch() {
const [query, setQuery] = useState('');
const [isLoading, setIsLoading] = useState(false);
useEffect(() => {
if (!query) return;
const timeoutId = setTimeout(async () => {
setIsLoading(true);
try {
await performSearch(query);
} finally {
setIsLoading(false);
}
}, 300);
return () => clearTimeout(timeoutId);
}, [query]);
return (
<SearchField
value={query}
onChange={setQuery}
isLoading={isLoading}
placeholder="Type to search..."
/>
);
}
```
### Example: Custom styling [#example-custom-styling]
```tsx
import { SearchField } from '@accelint/design-toolkit';
<SearchField
variant="filled"
classNames={{
field: 'rounded-full',
input: 'text-lg',
search: 'text-blue-500',
clear: 'hover:bg-red-100',
}}
placeholder="Custom search..."
/>
```
### Example: Search with icon customization [#example-search-with-icon-customization]
```tsx
import { SearchField } from '@accelint/design-toolkit';
<SearchField
placeholder="Search..."
classNames={{
search: 'text-primary',
loading: 'text-blue-500 animate-spin',
}}
isLoading={isSearching}
/>
```
## Related [#related]
* [TextField](../text-field/index.md) - Single-line text input
* [Input](../input/index.md) - Base input component
* [Icon](../icon/index.md) - Icon component for search and clear icons
* [ComboBoxField](../combobox-field/index.md) - Searchable select with autocomplete
# SelectField (/docs/toolkits/design-toolkit/components/select-field)
## Usage [#usage]
```tsx
import { SelectField, OptionsItem } from '@accelint/design-toolkit';
export function MyForm() {
return (
<SelectField label="Country" onSelectionChange={(key) => setCountry(key)}>
<OptionsItem id="us">United States</OptionsItem>
<OptionsItem id="ca">Canada</OptionsItem>
<OptionsItem id="mx">Mexico</OptionsItem>
</SelectField>
);
}
```
## Reference [#reference]
```typescript
interface SelectFieldProps extends Omit<AriaSelectProps, 'className'> {
label?: string;
description?: string;
errorMessage?: string;
size?: 'medium' | 'small';
isReadOnly?: boolean;
layoutOptions?: ListLayoutOptions;
classNames?: {
field?: string;
label?: LabelProps['className'];
trigger?: ButtonProps['className'];
value?: string;
description?: string;
error?: FieldErrorProps['className'];
popover?: PopoverProps['className'];
};
}
```
### Props [#props]
| Prop | Type | Default | Required |
| --------------- | ----------------------- | ---------- | -------- |
| `label` | `string` | - | No |
| `description` | `string` | - | No |
| `errorMessage` | `string` | - | No |
| `size` | `'medium' \| 'small'` | `'medium'` | No |
| `isReadOnly` | `boolean` | `false` | No |
| `layoutOptions` | `ListLayoutOptions` | - | No |
| `classNames` | `SelectFieldClassNames` | - | No |
| `isInvalid` | `boolean` | `false` | No |
| `isDisabled` | `boolean` | `false` | No |
| `isRequired` | `boolean` | `false` | No |
#### `label` [#label]
Label text displayed above the select trigger. Automatically associates with the select for accessibility. Hidden when `size="small"`.
#### `description` [#description]
Helper text displayed below the select trigger. Hidden when `size="small"`, `isReadOnly`, or when the field is invalid.
#### `errorMessage` [#errormessage]
Error message displayed when validation fails. Automatically sets `isInvalid` to `true` when provided.
#### `size` [#size]
Controls field sizing and visibility of label and description:
* `medium` - Standard size with visible label and description (default)
* `small` - Compact size, hides label and description
#### `isReadOnly` [#isreadonly]
Displays the selected value without allowing dropdown interaction. Useful for read-only forms or disabled states where you want to show the current value.
#### `layoutOptions` [#layoutoptions]
Virtualizer layout options for rendering large lists efficiently. Enables rendering thousands of options without performance degradation.
```typescript
layoutOptions={{
estimatedRowHeight: 40,
}}
```
#### `classNames` [#classnames]
Custom CSS class names for select elements:
* `field` - Container element
* `label` - Label element
* `trigger` - Trigger button element
* `value` - Selected value display element
* `description` - Description text element
* `error` - Error message element
* `popover` - Dropdown popover element
### Inherited Props [#inherited-props]
SelectField inherits all props from React Aria's `Select` component, including:
* `selectedKey` / `defaultSelectedKey` - Controlled/uncontrolled selection
* `onSelectionChange` - Called when selection changes (receives key)
* `disabledKeys` - Array of disabled option keys
* `items` - Collection items for dynamic rendering
* `onOpenChange` - Called when dropdown opens/closes
See [React Aria Select](https://react-spectrum.adobe.com/react-aria/Select.html) for full API reference.
## Examples [#examples]
### Example: Basic select [#example-basic-select]
```tsx
import { SelectField, OptionsItem } from '@accelint/design-toolkit';
<SelectField label="Fruit" placeholder="Select a fruit">
<OptionsItem id="apple">Apple</OptionsItem>
<OptionsItem id="banana">Banana</OptionsItem>
<OptionsItem id="orange">Orange</OptionsItem>
</SelectField>
```
### Example: With description [#example-with-description]
```tsx
import { SelectField, OptionsItem } from '@accelint/design-toolkit';
<SelectField
label="Timezone"
description="Select your local timezone"
onSelectionChange={(key) => setTimezone(key)}
>
<OptionsItem id="pst">Pacific Standard Time</OptionsItem>
<OptionsItem id="mst">Mountain Standard Time</OptionsItem>
<OptionsItem id="est">Eastern Standard Time</OptionsItem>
</SelectField>
```
### Example: Required with validation [#example-required-with-validation]
```tsx
import { SelectField, OptionsItem } from '@accelint/design-toolkit';
<SelectField
label="Country"
isRequired
isInvalid={!selectedCountry}
errorMessage="Please select a country"
>
<OptionsItem id="us">United States</OptionsItem>
<OptionsItem id="ca">Canada</OptionsItem>
<OptionsItem id="mx">Mexico</OptionsItem>
</SelectField>
```
### Example: Disabled options [#example-disabled-options]
```tsx
import { SelectField, OptionsItem } from '@accelint/design-toolkit';
<SelectField label="Status" disabledKeys={['pending']}>
<OptionsItem id="active">Active</OptionsItem>
<OptionsItem id="pending">Pending (unavailable)</OptionsItem>
<OptionsItem id="completed">Completed</OptionsItem>
</SelectField>
```
### Example: Read-only display [#example-read-only-display]
```tsx
import { SelectField, OptionsItem } from '@accelint/design-toolkit';
<SelectField
label="Account Type"
selectedKey="premium"
isReadOnly
>
<OptionsItem id="free">Free</OptionsItem>
<OptionsItem id="premium">Premium</OptionsItem>
<OptionsItem id="enterprise">Enterprise</OptionsItem>
</SelectField>
```
> **Good to know:** Read-only mode displays the selected value without allowing interaction. Use `isDisabled` if you want to indicate the field is temporarily unavailable.
### Example: Small size variant [#example-small-size-variant]
```tsx
import { SelectField, OptionsItem } from '@accelint/design-toolkit';
<SelectField size="small" placeholder="Filter by status...">
<OptionsItem id="all">All</OptionsItem>
<OptionsItem id="active">Active</OptionsItem>
<OptionsItem id="archived">Archived</OptionsItem>
</SelectField>
```
### Example: Rich options with descriptions [#example-rich-options-with-descriptions]
```tsx
import { SelectField, OptionsItem, OptionsItemLabel, OptionsItemDescription } from '@accelint/design-toolkit';
<SelectField label="Plan">
<OptionsItem id="free">
<OptionsItemLabel>Free</OptionsItemLabel>
<OptionsItemDescription>Perfect for getting started</OptionsItemDescription>
</OptionsItem>
<OptionsItem id="pro">
<OptionsItemLabel>Pro</OptionsItemLabel>
<OptionsItemDescription>For professional use</OptionsItemDescription>
</OptionsItem>
<OptionsItem id="enterprise">
<OptionsItemLabel>Enterprise</OptionsItemLabel>
<OptionsItemDescription>Advanced features and support</OptionsItemDescription>
</OptionsItem>
</SelectField>
```
### Example: Virtualized large list [#example-virtualized-large-list]
```tsx
import { SelectField, OptionsItem } from '@accelint/design-toolkit';
const countries = [...]; // 200+ countries
<SelectField
label="Country"
items={countries}
layoutOptions={{ estimatedRowHeight: 40 }}
>
{(country) => (
<OptionsItem id={country.code}>
{country.name}
</OptionsItem>
)}
</SelectField>
```
> **Good to know:** Virtualization automatically renders only visible items, enabling smooth scrolling through thousands of options.
### Example: Controlled selection [#example-controlled-selection]
```tsx
import { useState } from 'react';
import { SelectField, OptionsItem } from '@accelint/design-toolkit';
export function ControlledExample() {
const [selected, setSelected] = useState('apple');
return (
<SelectField
label="Fruit"
selectedKey={selected}
onSelectionChange={setSelected}
>
<OptionsItem id="apple">Apple</OptionsItem>
<OptionsItem id="banana">Banana</OptionsItem>
<OptionsItem id="orange">Orange</OptionsItem>
</SelectField>
);
}
```
## Related [#related]
* [OptionsItem](../options/item.md) - Select option component
* [OptionsItemLabel](../options/item-label.md) - Option label component
* [OptionsItemDescription](../options/item-description.md) - Option description component
* [ComboBoxField](../combobox-field/index.md) - Searchable select with autocomplete
# Sidenav (/docs/toolkits/design-toolkit/components/sidenav)
Collapsible side navigation panel with hierarchical menu structure, headers, avatars, and event-based control intended for use inside DrawerLayout.
## Usage [#usage]
```tsx
import {
Sidenav,
SidenavHeader,
SidenavContent,
SidenavItem,
Icon,
DrawerLayout,
DrawerLayoutMain
} from '@accelint/design-toolkit';
import { Home, Settings } from '@accelint/icons';
export function AppNav() {
return (
<DrawerLayout push="left">
<DrawerLayoutMain>
<p>Main content</p>
</DrawerLayoutMain>
<Sidenav id="main-nav">
<SidenavContent>
<SidenavItem>
<Icon><Home /></Icon>
<Text>Home</Text>
</SidenavItem>
<SidenavItem>
<Icon><Settings /></Icon>
<Text>Settings</Text>
</SidenavItem>
</SidenavContent>
</Sidenav>
</DrawerLayout>
);
}
```
## Reference [#reference]
```typescript
interface SidenavProps {
id: UniqueId;
children: React.ReactNode;
className?: string;
isHiddenWhenClosed?: boolean;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| -------------------- | ----------------- | ------- | -------- |
| `id` | `UniqueId` | - | Yes |
| `children` | `React.ReactNode` | - | Yes |
| `className` | `string` | - | No |
| `isHiddenWhenClosed` | `boolean` | `false` | No |
#### `id` [#id]
Unique identifier for the sidenav. Used for event-based control from triggers and other components.
#### `isHiddenWhenClosed` [#ishiddenwhenclosed]
When `true`, the sidenav element is removed from the DOM when closed. When `false`, the sidenav remains in the DOM but visually collapses.
## Examples [#examples]
### Example: Basic sidenav with items [#example-basic-sidenav-with-items]
```tsx
import { Sidenav, SidenavContent, SidenavItem, Icon, Text } from '@accelint/design-toolkit';
import { Home, Settings, Profile } from '@accelint/icons';
<Sidenav id="nav">
<SidenavContent>
<SidenavItem>
<Icon><Home /></Icon>
<Text>Home</Text>
</SidenavItem>
<SidenavItem isSelected>
<Icon><Settings /></Icon>
<Text>Settings</Text>
</SidenavItem>
<SidenavItem>
<Icon><Profile /></Icon>
<Text>Profile</Text>
</SidenavItem>
</SidenavContent>
</Sidenav>
```
### Example: With header and footer [#example-with-header-and-footer]
```tsx
import {
Sidenav,
SidenavHeader,
SidenavContent,
SidenavFooter,
SidenavAvatar,
SidenavItem,
Heading,
Text,
Icon
} from '@accelint/design-toolkit';
import { AppLogo, Home, User } from '@accelint/icons';
<Sidenav id="nav">
<SidenavHeader>
<SidenavAvatar>
<Icon><AppLogo /></Icon>
<Heading>My Application</Heading>
<Text>v1.0.0</Text>
</SidenavAvatar>
</SidenavHeader>
<SidenavContent>
<SidenavItem>
<Icon><Home /></Icon>
<Text>Home</Text>
</SidenavItem>
</SidenavContent>
<SidenavFooter>
<SidenavAvatar>
<Icon><User /></Icon>
<Heading>John Doe</Heading>
<Text>john@example.com</Text>
</SidenavAvatar>
</SidenavFooter>
</Sidenav>
```
### Example: Nested menu [#example-nested-menu]
```tsx
import {
Sidenav,
SidenavContent,
SidenavMenu,
SidenavMenuItem,
SidenavItem,
Icon,
Text,
Heading,
Divider
} from '@accelint/design-toolkit';
import { Home, Settings, Menu } from '@accelint/icons';
<Sidenav id="nav">
<SidenavContent>
<Heading>Navigation</Heading>
<SidenavItem>
<Icon><Home /></Icon>
<Text>Home</Text>
</SidenavItem>
<Divider />
<SidenavMenu title="More Options" icon={<Icon><Menu /></Icon>}>
<SidenavMenuItem>
<Text>Sub Item 1</Text>
</SidenavMenuItem>
<SidenavMenuItem>
<Text>Sub Item 2</Text>
</SidenavMenuItem>
</SidenavMenu>
<Divider />
<SidenavItem>
<Icon><Settings /></Icon>
<Text>Settings</Text>
</SidenavItem>
</SidenavContent>
</Sidenav>
```
### Example: With toggle trigger [#example-with-toggle-trigger]
```tsx
import {
Sidenav,
SidenavTrigger,
SidenavContent,
SidenavItem,
DrawerLayout,
DrawerLayoutMain,
Button,
Icon,
Text
} from '@accelint/design-toolkit';
import { Menu, Home } from '@accelint/icons';
<DrawerLayout push="left">
<DrawerLayoutMain>
<SidenavTrigger>
<Button variant="icon">
<Icon><Menu /></Icon>
</Button>
</SidenavTrigger>
</DrawerLayoutMain>
<Sidenav id="main-nav">
<SidenavContent>
<SidenavItem>
<Icon><Home /></Icon>
<Text>Home</Text>
</SidenavItem>
</SidenavContent>
</Sidenav>
</DrawerLayout>
```
### Example: Hidden when closed [#example-hidden-when-closed]
```tsx
import { Sidenav, SidenavContent, SidenavItem } from '@accelint/design-toolkit';
<Sidenav id="nav" isHiddenWhenClosed>
<SidenavContent>
<SidenavItem>
<Text>This nav is removed from DOM when closed</Text>
</SidenavItem>
</SidenavContent>
</Sidenav>
```
## Event System [#event-system]
Sidenav responds to global events for programmatic control:
### Event Types [#event-types]
* `Sidenav:open` - Opens the sidenav (payload: `{ id }`)
* `Sidenav:close` - Closes the sidenav (payload: `{ id }`)
* `Sidenav:toggle` - Toggles open/closed state (payload: `{ id }`)
```tsx
import { emit } from '@accelint/bus';
import { SidenavEventTypes } from '@accelint/design-toolkit';
// Open sidenav
emit({ type: SidenavEventTypes.open, payload: { id: 'main-nav' } });
// Close sidenav
emit({ type: SidenavEventTypes.close, payload: { id: 'main-nav' } });
// Toggle sidenav
emit({ type: SidenavEventTypes.toggle, payload: { id: 'main-nav' } });
```
## Multi-Part Structure [#multi-part-structure]
Sidenav is composed of several sub-components:
* **Sidenav** - Root container with event handling
* **SidenavHeader** - Header section for branding or app info
* **SidenavContent** - Scrollable navigation items area
* **SidenavFooter** - Footer section for user info or actions
* **SidenavAvatar** - Avatar display with icon and text
* **SidenavItem** - Individual navigation item
* **SidenavMenu** - Collapsible sub-menu container
* **SidenavMenuItem** - Item within a sub-menu
* **SidenavTrigger** - Button to control sidenav open/close
> **Good to know:** Sidenav is designed to work within `DrawerLayout` for proper push/overlay behavior. Use `SidenavTrigger` for consistent event-based control.
## Related [#related]
* [SidenavItem](./item.mdx) - Navigation item component
* [SidenavMenu](./menu.mdx) - Collapsible sub-menu
* [SidenavTrigger](./trigger.mdx) - Control trigger
* [DrawerLayout](../drawer/layout.mdx) - Layout container for drawers and sidenavs
# Skeleton (/docs/toolkits/design-toolkit/components/skeleton)
Placeholder content component for loading states. Displays a pulsing placeholder while content is being fetched, providing visual feedback during asynchronous operations.
## Usage [#usage]
```tsx
import { Skeleton } from '@accelint/design-toolkit';
export function LoadingCard() {
return (
<div>
<Skeleton variant="rectangle" style={{ width: 200, height: 20, marginBottom: 8 }} />
<Skeleton variant="rectangle" style={{ width: 150, height: 16 }} />
</div>
);
}
```
## Reference [#reference]
```typescript
interface SkeletonProps {
variant?: 'rectangle' | 'circle';
className?: string;
style?: React.CSSProperties;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ----------- | ------------------------- | ------------- | -------- |
| `variant` | `'rectangle' \| 'circle'` | `'rectangle'` | No |
| `className` | `string` | - | No |
| `style` | `React.CSSProperties` | - | No |
#### `variant` [#variant]
Controls the shape of the skeleton:
* `rectangle` - Rectangular placeholder (default)
* `circle` - Circular placeholder, useful for avatars
> **Good to know:** Use inline styles or className to set the size of the skeleton. The component does not have default dimensions.
## Examples [#examples]
### Example: Basic text placeholder [#example-basic-text-placeholder]
```tsx
import { Skeleton } from '@accelint/design-toolkit';
<div>
<Skeleton variant="rectangle" style={{ width: 200, height: 20 }} />
<Skeleton variant="rectangle" style={{ width: 180, height: 20, marginTop: 8 }} />
<Skeleton variant="rectangle" style={{ width: 160, height: 20, marginTop: 8 }} />
</div>
```
### Example: Avatar placeholder [#example-avatar-placeholder]
```tsx
import { Skeleton } from '@accelint/design-toolkit';
<Skeleton variant="circle" style={{ width: 48, height: 48 }} />
```
### Example: Card loading state [#example-card-loading-state]
```tsx
import { Skeleton } from '@accelint/design-toolkit';
<div className="card">
<Skeleton variant="circle" style={{ width: 40, height: 40, marginBottom: 16 }} />
<Skeleton variant="rectangle" style={{ width: '100%', height: 24, marginBottom: 8 }} />
<Skeleton variant="rectangle" style={{ width: '80%', height: 16, marginBottom: 8 }} />
<Skeleton variant="rectangle" style={{ width: '60%', height: 16 }} />
</div>
```
### Example: List loading state [#example-list-loading-state]
```tsx
import { Skeleton } from '@accelint/design-toolkit';
<div className="space-y-4">
{[1, 2, 3].map((i) => (
<div key={i} className="flex items-center gap-4">
<Skeleton variant="circle" style={{ width: 40, height: 40 }} />
<div className="flex-1">
<Skeleton variant="rectangle" style={{ width: '100%', height: 20, marginBottom: 8 }} />
<Skeleton variant="rectangle" style={{ width: '70%', height: 16 }} />
</div>
</div>
))}
</div>
```
### Example: Table row placeholder [#example-table-row-placeholder]
```tsx
import { Skeleton } from '@accelint/design-toolkit';
<tr>
<td><Skeleton variant="rectangle" style={{ width: 100, height: 16 }} /></td>
<td><Skeleton variant="rectangle" style={{ width: 150, height: 16 }} /></td>
<td><Skeleton variant="rectangle" style={{ width: 80, height: 16 }} /></td>
</tr>
```
### Example: Conditional loading [#example-conditional-loading]
```tsx
import { Skeleton } from '@accelint/design-toolkit';
import { useState, useEffect } from 'react';
export function UserProfile() {
const [user, setUser] = useState(null);
const [isLoading, setIsLoading] = useState(true);
useEffect(() => {
fetchUser().then((data) => {
setUser(data);
setIsLoading(false);
});
}, []);
if (isLoading) {
return (
<div>
<Skeleton variant="circle" style={{ width: 64, height: 64, marginBottom: 16 }} />
<Skeleton variant="rectangle" style={{ width: 200, height: 24, marginBottom: 8 }} />
<Skeleton variant="rectangle" style={{ width: 150, height: 16 }} />
</div>
);
}
return (
<div>
<img src={user.avatar} alt={user.name} />
<h2>{user.name}</h2>
<p>{user.email}</p>
</div>
);
}
```
### Example: Custom styled skeleton [#example-custom-styled-skeleton]
```tsx
import { Skeleton } from '@accelint/design-toolkit';
<Skeleton
variant="rectangle"
className="rounded-lg"
style={{ width: 300, height: 200 }}
/>
```
### Example: Media content placeholder [#example-media-content-placeholder]
```tsx
import { Skeleton } from '@accelint/design-toolkit';
<div className="media-card">
<Skeleton variant="rectangle" style={{ width: '100%', height: 200, marginBottom: 16 }} />
<Skeleton variant="rectangle" style={{ width: '100%', height: 24, marginBottom: 8 }} />
<Skeleton variant="rectangle" style={{ width: '80%', height: 16, marginBottom: 8 }} />
<Skeleton variant="rectangle" style={{ width: '90%', height: 16 }} />
</div>
```
### Example: Variable width text [#example-variable-width-text]
```tsx
import { Skeleton } from '@accelint/design-toolkit';
<div>
<Skeleton variant="rectangle" style={{ width: '100%', height: 20, marginBottom: 8 }} />
<Skeleton variant="rectangle" style={{ width: '95%', height: 20, marginBottom: 8 }} />
<Skeleton variant="rectangle" style={{ width: '88%', height: 20, marginBottom: 8 }} />
<Skeleton variant="rectangle" style={{ width: '75%', height: 20 }} />
</div>
```
> **Good to know:** The Skeleton component includes a pulsing animation by default. This animation runs automatically and requires no configuration.
## Related [#related]
* [Avatar](../avatar/index.md) - Avatar component that can show skeleton during image load
* [Table](../table/index.md) - Table component that can use skeletons for loading rows
# Slider (/docs/toolkits/design-toolkit/components/slider)
## Usage [#usage]
```tsx
import { Slider } from '@accelint/design-toolkit';
export function VolumeControl() {
return (
<Slider
label="Volume"
defaultValue={50}
minValue={0}
maxValue={100}
onChange={(value) => setVolume(value)}
/>
);
}
```
## Reference [#reference]
```typescript
interface SliderProps extends Omit<AriaSliderProps, 'children' | 'className'> {
label: string;
layout?: 'grid' | 'stack';
markers?: SliderMarkersConfig;
showInput?: boolean;
showLabel?: boolean;
showMarkerLabels?: boolean;
showValueLabels?: boolean;
snapToMarkers?: boolean;
classNames?: {
slider?: AriaSliderProps['className'];
label?: LabelProps['className'];
inputs?: string;
input?: string;
track?: SliderTrackProps['className'];
trackBackground?: string;
trackValue?: string;
thumb?: SliderThumbProps['className'];
minValue?: string;
maxValue?: string;
markers?: string;
marker?: string;
markerDot?: string;
markerLabel?: string;
};
}
type SliderMarkersConfig = number | SliderMarker[] | number[];
interface SliderMarker {
value: number;
label?: string;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ------------------ | ------------------------------------- | -------------- | -------- |
| `label` | `string` | - | Yes |
| `defaultValue` | `number \| number[]` | `[minValue]` | No |
| `value` | `number \| number[]` | - | No |
| `minValue` | `number` | `0` | No |
| `maxValue` | `number` | `100` | No |
| `step` | `number` | - | No |
| `layout` | `'grid' \| 'stack'` | `'grid'` | No |
| `markers` | `SliderMarkersConfig` | - | No |
| `showInput` | `boolean` | `false` | No |
| `showLabel` | `boolean` | `true` | No |
| `showMarkerLabels` | `boolean` | `false` | No |
| `showValueLabels` | `boolean` | `true` | No |
| `snapToMarkers` | `boolean` | `false` | No |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | No |
| `onChange` | `(value: number \| number[]) => void` | - | No |
| `onChangeEnd` | `(value: number \| number[]) => void` | - | No |
#### `label` [#label]
Label text for the slider. Required for accessibility. Hidden when `showLabel={false}`, but still used for `aria-label`.
#### `defaultValue` / `value` [#defaultvalue--value]
Single number for a single-value slider, or array of two numbers for a range slider. Range sliders render two thumbs.
```tsx
// Single value
<Slider defaultValue={50} />
// Range
<Slider defaultValue={[20, 80]} />
```
#### `layout` [#layout]
Controls the arrangement of slider elements:
* `grid` - Label, input fields, track, and values arranged in a grid layout (default)
* `stack` - Elements stacked vertically in document order
#### `markers` [#markers]
Configures discrete marker points on the slider track:
```tsx
// Number: evenly spaced markers (e.g., 5 creates markers at 0%, 25%, 50%, 75%, 100%)
<Slider markers={5} />
// Array of values
<Slider markers={[0, 25, 50, 75, 100]} />
// Array of marker objects with labels
<Slider
markers={[
{ value: 0, label: 'Low' },
{ value: 50, label: 'Medium' },
{ value: 100, label: 'High' },
]}
showMarkerLabels
/>
```
#### `showInput` [#showinput]
Displays numeric input fields for direct value entry. Inputs debounce changes by 500ms for smooth interaction. Single-value sliders show one input; range sliders show two.
#### `showMarkerLabels` [#showmarkerlabels]
Shows labels on markers that have a `label` property. Only applies when using marker objects with labels.
#### `showValueLabels` [#showvaluelabels]
Shows min/max value labels at track ends. Automatically hidden when a labeled marker exists at that position (prevents duplicate labels).
#### `snapToMarkers` [#snaptomarkers]
When `true`, the slider can only be set to marker values. The thumb snaps to the nearest marker during drag and on release. Requires `markers` prop.
#### `onChangeEnd` [#onchangeend]
Called when the user finishes dragging the thumb (on pointer up or blur). Useful for triggering API calls or expensive operations after interaction completes.
### Inherited Props [#inherited-props]
Slider inherits all props from React Aria's `Slider` component, including:
* `isDisabled` - Disables the slider
* `formatOptions` - Number formatting options
* `name` - Form field name
See [React Aria Slider](https://react-spectrum.adobe.com/react-aria/Slider.html) for full API reference.
## Examples [#examples]
### Example: Basic slider [#example-basic-slider]
```tsx
import { Slider } from '@accelint/design-toolkit';
<Slider
label="Volume"
defaultValue={50}
minValue={0}
maxValue={100}
/>
```
### Example: Range slider [#example-range-slider]
```tsx
import { Slider } from '@accelint/design-toolkit';
<Slider
label="Price range"
defaultValue={[20, 80]}
minValue={0}
maxValue={100}
/>
```
### Example: With input fields [#example-with-input-fields]
```tsx
import { Slider } from '@accelint/design-toolkit';
<Slider
label="Temperature"
defaultValue={72}
minValue={60}
maxValue={85}
showInput
/>
```
### Example: With evenly spaced markers [#example-with-evenly-spaced-markers]
```tsx
import { Slider } from '@accelint/design-toolkit';
<Slider
label="Quality"
defaultValue={3}
minValue={1}
maxValue={5}
markers={5}
step={1}
/>
```
### Example: With labeled markers [#example-with-labeled-markers]
```tsx
import { Slider } from '@accelint/design-toolkit';
<Slider
label="Priority"
defaultValue={2}
minValue={1}
maxValue={5}
markers={[
{ value: 1, label: 'Low' },
{ value: 2, label: 'Medium' },
{ value: 3, label: 'High' },
{ value: 4, label: 'Critical' },
{ value: 5, label: 'Urgent' },
]}
showMarkerLabels
snapToMarkers
/>
```
> **Good to know:** When using `snapToMarkers` with labeled markers, the slider becomes a discrete selector — perfect for priority levels, quality settings, or rating scales.
### Example: Snap to markers [#example-snap-to-markers]
```tsx
import { Slider } from '@accelint/design-toolkit';
<Slider
label="CPU cores"
defaultValue={4}
minValue={1}
maxValue={16}
markers={[1, 2, 4, 8, 16]}
snapToMarkers
/>
```
### Example: Custom step [#example-custom-step]
```tsx
import { Slider } from '@accelint/design-toolkit';
<Slider
label="Percentage"
defaultValue={50}
minValue={0}
maxValue={100}
step={5}
/>
```
### Example: Controlled slider [#example-controlled-slider]
```tsx
import { useState } from 'react';
import { Slider } from '@accelint/design-toolkit';
export function ControlledExample() {
const [value, setValue] = useState(50);
return (
<>
<Slider
label="Brightness"
value={value}
onChange={setValue}
minValue={0}
maxValue={100}
/>
<p>Current: {value}%</p>
</>
);
}
```
### Example: Disabled slider [#example-disabled-slider]
```tsx
import { Slider } from '@accelint/design-toolkit';
<Slider
label="Read-only setting"
value={75}
isDisabled
minValue={0}
maxValue={100}
/>
```
### Example: Stack layout [#example-stack-layout]
```tsx
import { Slider } from '@accelint/design-toolkit';
<Slider
label="Zoom"
defaultValue={100}
minValue={50}
maxValue={200}
layout="stack"
showInput
/>
```
### Example: With onChange and onChangeEnd [#example-with-onchange-and-onchangeend]
```tsx
import { Slider } from '@accelint/design-toolkit';
<Slider
label="Volume"
defaultValue={50}
minValue={0}
maxValue={100}
onChange={(value) => {
// Called during drag
console.log('Dragging:', value);
}}
onChangeEnd={(value) => {
// Called on release
console.log('Final value:', value);
saveToApi(value);
}}
/>
```
> **Good to know:** Use `onChangeEnd` for expensive operations like API calls to avoid triggering them repeatedly during drag.
### Example: Without visible label [#example-without-visible-label]
```tsx
import { Slider } from '@accelint/design-toolkit';
<Slider
label="Volume"
showLabel={false}
defaultValue={50}
minValue={0}
maxValue={100}
/>
```
> **Good to know:** Even with `showLabel={false}`, the label text is still used for `aria-label` to ensure accessibility.
### Example: Hide min/max values [#example-hide-minmax-values]
```tsx
import { Slider } from '@accelint/design-toolkit';
<Slider
label="Opacity"
defaultValue={0.5}
minValue={0}
maxValue={1}
step={0.1}
showValueLabels={false}
/>
```
### Example: Custom markers (uneven spacing) [#example-custom-markers-uneven-spacing]
```tsx
import { Slider } from '@accelint/design-toolkit';
<Slider
label="Response time"
defaultValue={100}
minValue={0}
maxValue={1000}
markers={[0, 50, 100, 200, 500, 1000]}
snapToMarkers
/>
```
## Related [#related]
* [TextField](../text-field/index.md) - Single-line text input
* [Input](../input/index.md) - Base input component
* [Tooltip](../tooltip/index.md) - Used for displaying thumb values on hover
# StatusIndicator (/docs/toolkits/design-toolkit/components/status-indicator)
Visual indicator for displaying connection or service status with three severity states: good, degraded, or poor.
## Usage [#usage]
```tsx
import { StatusIndicator } from '@accelint/design-toolkit';
export function ConnectionStatus() {
return <StatusIndicator status="good" />;
}
```
## Reference [#reference]
```typescript
interface StatusIndicatorProps {
className?: string;
status?: 'good' | 'degraded' | 'poor';
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ----------- | -------------------------------- | -------- | -------- |
| `className` | `string` | - | No |
| `status` | `'good' \| 'degraded' \| 'poor'` | `'good'` | No |
#### `status` [#status]
Visual state indicator:
* `good` - Healthy status (green)
* `degraded` - Partial functionality or warning (yellow)
* `poor` - Critical issue or offline (red)
## Examples [#examples]
### Example: Good status [#example-good-status]
```tsx
import { StatusIndicator } from '@accelint/design-toolkit';
<StatusIndicator status="good" />
```
### Example: Degraded status [#example-degraded-status]
```tsx
import { StatusIndicator } from '@accelint/design-toolkit';
<StatusIndicator status="degraded" />
```
### Example: Poor status [#example-poor-status]
```tsx
import { StatusIndicator } from '@accelint/design-toolkit';
<StatusIndicator status="poor" />
```
### Example: With label text [#example-with-label-text]
```tsx
import { StatusIndicator } from '@accelint/design-toolkit';
<div className="flex items-center gap-2">
<StatusIndicator status="good" />
<span>All systems operational</span>
</div>
```
### Example: Dynamic status [#example-dynamic-status]
```tsx
import { StatusIndicator } from '@accelint/design-toolkit';
function ServiceStatus({ isOnline, hasIssues }) {
const status = !isOnline ? 'poor' : hasIssues ? 'degraded' : 'good';
return (
<div className="flex items-center gap-2">
<StatusIndicator status={status} />
<span>
{status === 'good' && 'Connected'}
{status === 'degraded' && 'Limited connectivity'}
{status === 'poor' && 'Disconnected'}
</span>
</div>
);
}
```
### Example: Status list [#example-status-list]
```tsx
import { StatusIndicator } from '@accelint/design-toolkit';
const services = [
{ name: 'API Server', status: 'good' },
{ name: 'Database', status: 'good' },
{ name: 'Cache', status: 'degraded' },
{ name: 'Queue', status: 'poor' },
];
<ul className="space-y-2">
{services.map(service => (
<li key={service.name} className="flex items-center gap-2">
<StatusIndicator status={service.status} />
<span>{service.name}</span>
</li>
))}
</ul>
```
### Example: Inline with text [#example-inline-with-text]
```tsx
import { StatusIndicator } from '@accelint/design-toolkit';
<p className="flex items-center gap-1">
Connection:
<StatusIndicator status="degraded" />
Reconnecting...
</p>
```
## Accessibility [#accessibility]
StatusIndicator is purely presentational. Always provide accompanying text or aria-labels for accessibility:
```tsx
<div role="status" aria-label="Service status: operational">
<StatusIndicator status="good" />
<span aria-hidden="true">Operational</span>
</div>
```
## Use Cases [#use-cases]
* **System health dashboards** - Show service or component status
* **Connection indicators** - Display network connectivity state
* **Resource availability** - Indicate resource health or capacity
* **Real-time monitoring** - Visualize live system metrics
> **Good to know:** StatusIndicator is a presentational component only. It does not include text labels or tooltips — compose it with your own text or UI elements.
## Related [#related]
* [Badge](../badge/index.mdx) - Text badge with status colors
* [Chip](../chip/index.mdx) - Tag component with color variants
* [Notice](../notice/index.mdx) - Notification component with severity levels
# Stepper (/docs/toolkits/design-toolkit/components/stepper)
A component family for building multi-step workflows with sequential navigation, completion tracking, and accessibility features.
## Usage [#usage]
```tsx
import { Stepper, StepperList, StepperStep, StepperPanel, StepperNext, StepperBack } from '@accelint/design-toolkit';
export function MyComponent() {
return (
<Stepper defaultStep="account">
<StepperList>
<StepperStep id="account">Account</StepperStep>
<StepperStep id="profile">Profile</StepperStep>
<StepperStep id="preferences">Preferences</StepperStep>
</StepperList>
<StepperPanel id="account">
<h2>Account Information</h2>
<p>Enter your account details</p>
<StepperNext>Next</StepperNext>
</StepperPanel>
<StepperPanel id="profile">
<h2>Profile Setup</h2>
<p>Complete your profile</p>
<StepperBack>Back</StepperBack>
<StepperNext>Next</StepperNext>
</StepperPanel>
<StepperPanel id="preferences">
<h2>Preferences</h2>
<p>Set your preferences</p>
<StepperBack>Back</StepperBack>
<button>Finish</button>
</StepperPanel>
</Stepper>
);
}
```
## Reference [#reference]
```typescript
interface StepperProps {
children?: React.ReactNode;
className?: string;
style?: React.CSSProperties;
orientation?: 'horizontal' | 'vertical';
// Controlled mode
currentStep?: Key;
onStepChange?: (key: Key) => void;
// Uncontrolled mode
defaultStep?: Key;
// Validation
onBeforeStepChange?: (fromKey: Key, toKey: Key) => boolean;
// Completion tracking
completedSteps?: Set<Key>;
defaultCompletedSteps?: Set<Key>;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ----------------------- | --------------------------------- | -------------- | -------- |
| `children` | `React.ReactNode` | - | Yes |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | No |
| `currentStep` | `Key` | - | No |
| `defaultStep` | `Key` | - | No |
| `onStepChange` | `(key: Key) => void` | - | No |
| `onBeforeStepChange` | `(from: Key, to: Key) => boolean` | - | No |
| `completedSteps` | `Set<Key>` | - | No |
| `defaultCompletedSteps` | `Set<Key>` | - | No |
| `className` | `string` | - | No |
| `style` | `React.CSSProperties` | - | No |
#### `orientation` [#orientation]
Controls layout direction of the steps:
* `horizontal` - Steps appear in a row (default)
* `vertical` - Steps appear in a column
#### State Control [#state-control]
**Uncontrolled mode** (default):
* Use `defaultStep` to set initial step
* Use `defaultCompletedSteps` to mark steps as pre-completed
* Stepper manages its own state internally
**Controlled mode**:
* Use `currentStep` + `onStepChange` to control active step externally
* Use `completedSteps` to control completion state externally
* Useful for forms with external validation or URL synchronization
#### `onBeforeStepChange` [#onbeforestepchange]
Synchronous validation callback that can block navigation by returning `false`. Called before any navigation occurs (forward, backward, or direct).
```tsx
<Stepper
onBeforeStepChange={(from, to) => {
// Validate before allowing navigation
if (from === 'payment' && !isPaymentValid()) {
return false; // Blocks navigation
}
return true; // Allows navigation
}}
>
```
> **Note:** Only synchronous validation is supported. For async validation, disable navigation buttons while validating and enable them once complete.
#### Completion Tracking [#completion-tracking]
Steps are marked as "visited" bidirectionally:
* **Forward navigation**: marks the departed step as visited
* **Backward navigation**: removes visited state from destination step and all steps after it
* **Current step**: never marked as visited (current and visited are mutually exclusive)
This provides clear "undo" semantics when users navigate backward to edit previous steps.
## Sub-components [#sub-components]
### StepperList [#stepperlist]
Container for StepperStep components. Handles keyboard navigation with arrow keys.
```tsx
<StepperList>
<StepperStep id="one">First</StepperStep>
<StepperStep id="two">Second</StepperStep>
</StepperList>
```
**Props:**
* Inherits standard React props (`className`, `style`)
* Orientation and keyboard behavior inherit from parent Stepper
### StepperStep [#stepperstep]
Individual step button. The `id` prop must match the corresponding StepperPanel.
```tsx
<StepperStep id="profile" isDisabled>Profile</StepperStep>
```
**Props:**
| Prop | Type | Default | Required |
| ------------ | ------------------------------- | -------------- | -------- |
| `id` | `Key` | auto-generated | No |
| `isDisabled` | `boolean` | `false` | No |
| `children` | `React.ReactNode` | - | Yes |
| `className` | `string \| ((state) => string)` | - | No |
**Data attributes** (for CSS styling):
* `data-current="true"` - Applied when step is active
* `data-visited="true"` - Applied when step was visited (not current)
* `data-disabled="true"` - Applied when step is disabled
### StepperPanel [#stepperpanel]
Content panel displayed when its corresponding StepperStep is active. The `id` prop must match a StepperStep. Inactive panels are unmounted from the DOM.
```tsx
<StepperPanel id="profile">
<h2>Profile Information</h2>
<p>Complete your profile</p>
</StepperPanel>
```
**Props:**
| Prop | Type | Default | Required |
| ----------- | ----------------- | ------- | -------- |
| `id` | `Key` | - | Yes |
| `children` | `React.ReactNode` | - | Yes |
| `className` | `string` | - | No |
> **State preservation:** Inactive panels are unmounted, so form state is not preserved by default. Lift state to a parent component if preservation is needed.
### StepperNext / StepperBack [#steppernext--stepperback]
Context-aware navigation buttons that automatically disable at boundaries and respect validation.
```tsx
<StepperBack>Previous</StepperBack>
<StepperNext>Continue</StepperNext>
```
**Behavior:**
* `StepperBack` - Disabled at first step
* `StepperNext` - Disabled at last step or when next step is disabled
* Both respect `onBeforeStepChange` validation
* Can be overridden with explicit `isDisabled` prop
## Examples [#examples]
### Example: Basic linear stepper [#example-basic-linear-stepper]
```tsx
import { Stepper, StepperList, StepperStep, StepperPanel, StepperNext, StepperBack } from '@accelint/design-toolkit';
<Stepper defaultStep="personal">
<StepperList>
<StepperStep id="personal">Personal Info</StepperStep>
<StepperStep id="address">Address</StepperStep>
<StepperStep id="review">Review</StepperStep>
</StepperList>
<StepperPanel id="personal">
<h2>Personal Information</h2>
<input placeholder="Name" />
<StepperNext>Next</StepperNext>
</StepperPanel>
<StepperPanel id="address">
<h2>Address</h2>
<input placeholder="Street" />
<StepperBack>Back</StepperBack>
<StepperNext>Next</StepperNext>
</StepperPanel>
<StepperPanel id="review">
<h2>Review & Submit</h2>
<StepperBack>Back</StepperBack>
<button>Submit</button>
</StepperPanel>
</Stepper>
```
### Example: Controlled stepper with URL sync [#example-controlled-stepper-with-url-sync]
```tsx
import { useRouter, useSearchParams } from 'next/navigation';
import { Stepper, StepperList, StepperStep, StepperPanel } from '@accelint/design-toolkit';
function OnboardingFlow() {
const router = useRouter();
const searchParams = useSearchParams();
const currentStep = searchParams.get('step') || 'welcome';
return (
<Stepper
currentStep={currentStep}
onStepChange={(key) => {
router.push(`?step=${key}`);
}}
>
<StepperList>
<StepperStep id="welcome">Welcome</StepperStep>
<StepperStep id="setup">Setup</StepperStep>
<StepperStep id="done">Done</StepperStep>
</StepperList>
<StepperPanel id="welcome">Welcome content</StepperPanel>
<StepperPanel id="setup">Setup content</StepperPanel>
<StepperPanel id="done">Done content</StepperPanel>
</Stepper>
);
}
```
### Example: Form validation with onBeforeStepChange [#example-form-validation-with-onbeforestepchange]
```tsx
import { useState } from 'react';
import { Stepper, StepperList, StepperStep, StepperPanel, StepperNext } from '@accelint/design-toolkit';
function FormStepper() {
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
return (
<Stepper
defaultStep="account"
onBeforeStepChange={(from, to) => {
// Validate before allowing navigation forward
if (from === 'account' && !email.includes('@')) {
alert('Please enter a valid email');
return false;
}
if (from === 'password' && password.length < 8) {
alert('Password must be at least 8 characters');
return false;
}
return true;
}}
>
<StepperList>
<StepperStep id="account">Account</StepperStep>
<StepperStep id="password">Password</StepperStep>
<StepperStep id="confirm">Confirm</StepperStep>
</StepperList>
<StepperPanel id="account">
<input
type="email"
value={email}
onChange={(e) => setEmail(e.target.value)}
placeholder="Email"
/>
<StepperNext>Next</StepperNext>
</StepperPanel>
<StepperPanel id="password">
<input
type="password"
value={password}
onChange={(e) => setPassword(e.target.value)}
placeholder="Password"
/>
<StepperNext>Next</StepperNext>
</StepperPanel>
<StepperPanel id="confirm">
<p>Email: {email}</p>
<button>Create Account</button>
</StepperPanel>
</Stepper>
);
}
```
### Example: Non-linear stepper with disabled steps [#example-non-linear-stepper-with-disabled-steps]
```tsx
import { useState } from 'react';
import { Stepper, StepperList, StepperStep, StepperPanel } from '@accelint/design-toolkit';
function ConditionalStepper() {
const [hasAccount, setHasAccount] = useState(false);
return (
<Stepper defaultStep="check">
<StepperList>
<StepperStep id="check">Check Account</StepperStep>
<StepperStep id="create" isDisabled={hasAccount}>Create Account</StepperStep>
<StepperStep id="login" isDisabled={!hasAccount}>Login</StepperStep>
<StepperStep id="dashboard">Dashboard</StepperStep>
</StepperList>
<StepperPanel id="check">
<button onClick={() => setHasAccount(true)}>I have an account</button>
<button onClick={() => setHasAccount(false)}>Create new account</button>
</StepperPanel>
<StepperPanel id="create">Create account form</StepperPanel>
<StepperPanel id="login">Login form</StepperPanel>
<StepperPanel id="dashboard">Dashboard content</StepperPanel>
</Stepper>
);
}
```
### Example: Vertical stepper [#example-vertical-stepper]
```tsx
import { Stepper, StepperList, StepperStep, StepperPanel } from '@accelint/design-toolkit';
<Stepper orientation="vertical" defaultStep="shipping">
<StepperList>
<StepperStep id="shipping">Shipping</StepperStep>
<StepperStep id="payment">Payment</StepperStep>
<StepperStep id="review">Review</StepperStep>
</StepperList>
<div>
<StepperPanel id="shipping">Shipping form</StepperPanel>
<StepperPanel id="payment">Payment form</StepperPanel>
<StepperPanel id="review">Order review</StepperPanel>
</div>
</Stepper>
```
### Example: Using useStepperState for custom controls [#example-using-usestepperstate-for-custom-controls]
```tsx
import { Stepper, useStepperState, StepperList, StepperStep, StepperPanel } from '@accelint/design-toolkit';
function CustomStepper() {
return (
<Stepper defaultStep="start">
<CustomProgress />
<StepperList>
<StepperStep id="start">Start</StepperStep>
<StepperStep id="middle">Middle</StepperStep>
<StepperStep id="end">End</StepperStep>
</StepperList>
<StepperPanel id="start">Start content</StepperPanel>
<StepperPanel id="middle">Middle content</StepperPanel>
<StepperPanel id="end">End content</StepperPanel>
</Stepper>
);
}
function CustomProgress() {
const state = useStepperState();
const totalSteps = state.steps.size;
const completedCount = state.completedSteps.size;
const progress = (completedCount / totalSteps) * 100;
return (
<div>
<div>Progress: {Math.round(progress)}%</div>
<button onClick={() => state.goToStep('start')}>Reset</button>
</div>
);
}
```
## Accessibility [#accessibility]
The Stepper component implements the ARIA wizard pattern with comprehensive keyboard and screen reader support:
### Keyboard Navigation [#keyboard-navigation]
* **Arrow Keys** (Left/Right for horizontal, Up/Down for vertical): Navigate between steps
* **Enter / Space**: Activate focused step
* **Tab**: Move focus through interactive elements in the panel
### Screen Reader Support [#screen-reader-support]
* Step changes are announced via ARIA live regions (e.g., "Step 2 of 3: Payment")
* Validation failures are announced when `onBeforeStepChange` blocks navigation
* Each step announces its position and label (e.g., "Step 1 of 3: Account Information")
### ARIA Attributes [#aria-attributes]
* Stepper container: `role="group"` with descriptive `aria-label`
* StepperList: `role="navigation"` with `aria-label="Steps"`
* StepperStep: `role="button"` with `aria-current="step"` when active
* StepperPanel: `role="tabpanel"` with `aria-labelledby` linking to its step
## Styling [#styling]
The Stepper uses data attributes for state-based styling:
```css
/* Current step */
[data-current="true"] {
font-weight: bold;
color: var(--color-primary);
}
/* Visited (completed) step */
[data-visited="true"] {
opacity: 0.7;
}
/* Disabled step */
[data-disabled="true"] {
opacity: 0.4;
cursor: not-allowed;
}
/* Step connectors (lines between steps) */
.step:not(:last-child)::after {
content: '';
border-top: 1px solid var(--color-border);
}
/* Completed step connectors */
[data-visited="true"]::after {
border-color: var(--color-primary);
}
```
## Best Practices [#best-practices]
### ✅ Do [#-do]
* Use `defaultStep` for uncontrolled forms where the stepper manages its own state
* Use `currentStep` + `onStepChange` when you need to sync with URL parameters or external state
* Provide clear, descriptive labels for each step
* Use `onBeforeStepChange` for synchronous validation before navigation
* Lift form state to parent components if you need to preserve values across panel unmounting
### ❌ Don't [#-dont]
* Don't mix controlled and uncontrolled props (`currentStep` with `defaultStep`)
* Don't rely on panel state persisting when navigating away (panels unmount)
* Don't use async functions in `onBeforeStepChange` (only synchronous validation is supported)
* Don't nest Stepper components
* Don't auto-skip disabled steps (they explicitly block navigation as designed)
## Related [#related]
* [Tabs](/docs/toolkits/design-toolkit/components/tabs) - For organizing content without workflow semantics
* [Button](/docs/toolkits/design-toolkit/components/button) - Used by StepperNext/StepperBack internally
# Switch (/docs/toolkits/design-toolkit/components/switch)
## Usage [#usage]
```tsx
import { Switch } from '@accelint/design-toolkit';
export function Settings() {
return (
<Switch isSelected={enabled} onChange={setEnabled}>
Enable notifications
</Switch>
);
}
```
## Reference [#reference]
```typescript
interface SwitchProps extends Omit<AriaSwitchProps, 'className'> {
labelPosition?: 'start' | 'end';
classNames?: {
switch?: AriaSwitchProps['className'];
control?: string;
label?: string;
};
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ----------------- | ------------------------------- | ------- | -------- |
| `children` | `React.ReactNode` | - | No |
| `labelPosition` | `'start' \| 'end'` | `'end'` | No |
| `classNames` | `SwitchClassNames` | - | No |
| `isSelected` | `boolean` | `false` | No |
| `defaultSelected` | `boolean` | `false` | No |
| `onChange` | `(isSelected: boolean) => void` | - | No |
| `isDisabled` | `boolean` | `false` | No |
#### `children` [#children]
Label content for the switch. Can be text or other React elements. Optional - if omitted, renders a standalone switch control.
#### `labelPosition` [#labelposition]
Controls the position of the label text relative to the switch control:
* `end` - Label appears after the switch control (default)
* `start` - Label appears before the switch control
#### `classNames` [#classnames]
Custom CSS class names for switch elements:
* `switch` - Container label element
* `control` - Visual toggle control element
* `label` - Label text element
### Inherited Props [#inherited-props]
Switch inherits all props from React Aria's `Switch` component, including:
* `isSelected` / `defaultSelected` - Controlled/uncontrolled toggle state
* `onChange` - Called when toggle state changes (receives boolean)
* `isDisabled` - Disables the switch
* `isReadOnly` - Makes the switch read-only
* `name` - Form field name
* `value` - Form value when checked
See [React Aria Switch](https://react-spectrum.adobe.com/react-aria/Switch.html) for full API reference.
## Examples [#examples]
### Example: Basic switch [#example-basic-switch]
```tsx
import { Switch } from '@accelint/design-toolkit';
<Switch>
Enable dark mode
</Switch>
```
### Example: Controlled switch [#example-controlled-switch]
```tsx
import { useState } from 'react';
import { Switch } from '@accelint/design-toolkit';
export function ControlledExample() {
const [enabled, setEnabled] = useState(false);
return (
<Switch isSelected={enabled} onChange={setEnabled}>
Enable notifications
</Switch>
);
}
```
### Example: Disabled switch [#example-disabled-switch]
```tsx
import { Switch } from '@accelint/design-toolkit';
<Switch isDisabled isSelected>
Feature locked (Pro plan only)
</Switch>
```
### Example: Read-only switch [#example-read-only-switch]
```tsx
import { Switch } from '@accelint/design-toolkit';
<Switch isReadOnly isSelected>
System setting (cannot be changed)
</Switch>
```
### Example: Label position - start [#example-label-position---start]
```tsx
import { Switch } from '@accelint/design-toolkit';
<Switch labelPosition="start">
Auto-save
</Switch>
```
### Example: Standalone switch (no label) [#example-standalone-switch-no-label]
```tsx
import { Switch } from '@accelint/design-toolkit';
<Switch aria-label="Toggle feature" />
```
> **Good to know:** When omitting the visible label, always provide an `aria-label` for accessibility.
### Example: Form integration [#example-form-integration]
```tsx
import { Switch } from '@accelint/design-toolkit';
<form onSubmit={handleSubmit}>
<Switch name="newsletter" value="yes">
Subscribe to newsletter
</Switch>
<Switch name="terms" value="accepted" isRequired>
I accept the terms and conditions
</Switch>
<button type="submit">Submit</button>
</form>
```
### Example: Multiple settings [#example-multiple-settings]
```tsx
import { useState } from 'react';
import { Switch } from '@accelint/design-toolkit';
export function SettingsPanel() {
const [settings, setSettings] = useState({
notifications: true,
emails: false,
analytics: true,
});
const updateSetting = (key: string) => (value: boolean) => {
setSettings(prev => ({ ...prev, [key]: value }));
};
return (
<div>
<Switch
isSelected={settings.notifications}
onChange={updateSetting('notifications')}
>
Push notifications
</Switch>
<Switch
isSelected={settings.emails}
onChange={updateSetting('emails')}
>
Email updates
</Switch>
<Switch
isSelected={settings.analytics}
onChange={updateSetting('analytics')}
>
Usage analytics
</Switch>
</div>
);
}
```
### Example: Custom styling [#example-custom-styling]
```tsx
import { Switch } from '@accelint/design-toolkit';
<Switch
classNames={{
switch: 'flex items-center gap-2',
control: 'bg-blue-500',
label: 'font-medium text-gray-700',
}}
>
Custom styled switch
</Switch>
```
### Example: Rich content label [#example-rich-content-label]
```tsx
import { Switch } from '@accelint/design-toolkit';
<Switch>
<div>
<strong>Premium features</strong>
<div className="text-sm text-gray-500">
Access advanced tools and analytics
</div>
</div>
</Switch>
```
## Related [#related]
* [Checkbox](../checkbox/index.md) - Multi-selection alternative
* [Radio](../radio/index.md) - Single-selection from multiple options
* [RadioGroup](../radio/group.md) - Container for Radio buttons
# Table (/docs/toolkits/design-toolkit/components/table)
## Usage [#usage]
```tsx
import { Table } from '@accelint/design-toolkit';
const columns = [
{ accessorKey: 'name', header: 'Name' },
{ accessorKey: 'email', header: 'Email' },
];
const data = [
{ id: '1', name: 'John Doe', email: 'john@example.com' },
{ id: '2', name: 'Jane Smith', email: 'jane@example.com' },
];
export function MyTable() {
return <Table columns={columns} data={data} enableSorting showCheckbox />;
}
```
## Reference [#reference]
```typescript
interface TableProps<T extends { id: Key }> {
columns: ColumnDef<T>[];
data: T[];
variant?: 'cozy' | 'compact' | 'crammed';
showCheckbox?: boolean;
rowSelection?: RowSelectionState;
defaultRowSelection?: RowSelectionState;
rowPinning?: RowPinningState;
defaultRowPinning?: RowPinningState;
kebabPosition?: 'left' | 'right';
persistRowKebabMenu?: boolean;
persistHeaderKebabMenu?: boolean;
persistNumerals?: boolean;
enableSorting?: boolean;
enableColumnReordering?: boolean;
enableRowActions?: boolean;
manualSorting?: boolean;
sort?: SortingState;
defaultSort?: SortingState;
columnOrder?: ColumnOrderState;
defaultColumnOrder?: ColumnOrderState;
fullWidth?: boolean;
pageSize?: number;
page?: number;
defaultPage?: number;
onSortChange?: (sort: SortingState) => void;
onColumnReorderChange?: (index: number) => void;
onColumnOrderChange?: (columnOrder: ColumnOrderState) => void;
onRowSelectionChange?: (rowSelection: RowSelectionState) => void;
onRowPinningChange?: (rowPinning: RowPinningState) => void;
onPageChange?: (page: number) => void;
}
```
`RowSelectionState`, `RowPinningState`, `SortingState`, and `ColumnOrderState` are TanStack Table types. Import them from `@tanstack/react-table`; the design toolkit does not re-export them.
### Props [#props]
| Prop | Type | Default | Required |
| ------------------------ | ---------------------------------- | ------------------------- | -------- |
| `columns` | `ColumnDef<T>[]` | - | Yes |
| `data` | `T[]` | - | Yes |
| `variant` | `'cozy' \| 'compact' \| 'crammed'` | `'cozy'` | No |
| `showCheckbox` | `boolean` | `false` | No |
| `rowSelection` | `RowSelectionState` | - | No |
| `defaultRowSelection` | `RowSelectionState` | `{}` | No |
| `rowPinning` | `RowPinningState` | - | No |
| `defaultRowPinning` | `RowPinningState` | `{ top: [], bottom: [] }` | No |
| `kebabPosition` | `'left' \| 'right'` | `'right'` | No |
| `persistRowKebabMenu` | `boolean` | `true` | No |
| `persistHeaderKebabMenu` | `boolean` | `true` | No |
| `persistNumerals` | `boolean` | `false` | No |
| `enableSorting` | `boolean` | `true` | No |
| `enableColumnReordering` | `boolean` | `true` | No |
| `enableRowActions` | `boolean` | `true` | No |
| `manualSorting` | `boolean` | `false` | No |
| `sort` | `SortingState` | - | No |
| `defaultSort` | `SortingState` | `[]` | No |
| `columnOrder` | `ColumnOrderState` | - | No |
| `defaultColumnOrder` | `ColumnOrderState` | `[]` | No |
| `fullWidth` | `boolean` | `false` | No |
| `pageSize` | `number` | - | No |
| `page` | `number` | - | No |
| `defaultPage` | `number` | `1` | No |
| `onSortChange` | `function` | - | No |
| `onColumnReorderChange` | `function` | - | No |
| `onColumnOrderChange` | `function` | - | No |
| `onRowSelectionChange` | `function` | - | No |
| `onRowPinningChange` | `function` | - | No |
| `onPageChange` | `function` | - | No |
#### `columns` [#columns]
Array of TanStack Table column definitions. Each column defines how to access and display data:
```typescript
{
accessorKey: 'fieldName', // Field to access in data object
header: 'Display Name', // Column header text
cell: ({ row }) => <CustomCell value={row.original.field} />, // Optional custom cell renderer
}
```
#### `data` [#data]
Array of data objects. Each object must have a unique `id` property of type `string` or `number`.
#### `variant` [#variant]
Visual density variant that controls the padding of header and body cells:
* `cozy` - 12px cell padding, the default
* `compact` - 8px cell padding for denser layouts
* `crammed` - 2px cell padding with single-line cells for maximum density
Meta columns (row numerals, selection checkbox, kebab menu) follow the same
padding step, and row height follows the cells. The row and header kebab
menus inherit the density, clamped to the `Menu` component's `cozy | compact`
subset, so `crammed` tables open `compact` menus.
With `fullWidth` (fixed layout), `crammed` truncates text wider than its
column with an ellipsis; set a TanStack column `size` to control the cutoff.
Custom cell content that intentionally extends beyond the cell edge is also
clipped at `crammed`; portaled overlays (menus, tooltips) are unaffected.
Only data mode (`columns` + `data`) accepts `variant`. Custom-children mode
renders `cozy`; wrap the cells in `TableContext.Provider` to hand-compose a
denser table.
#### `showCheckbox` [#showcheckbox]
When `true`, displays a checkbox column for row selection. The header checkbox selects/deselects all rows.
#### `rowSelection` / `defaultRowSelection` [#rowselection--defaultrowselection]
Controlled and uncontrolled row selection state. An object mapping row IDs to their selection state:
```typescript
{ 'row-1': true, 'row-2': true } // Rows 1 and 2 are selected
```
Selection is controlled while `rowSelection` is provided; pair it with `onRowSelectionChange` to apply changes, otherwise the selection stays frozen at that value. Use `defaultRowSelection` to seed an uncontrolled table; it is ignored while `rowSelection` is provided.
#### `onRowSelectionChange` [#onrowselectionchange]
Called with the plain next `RowSelectionState` whenever selection changes. Functional updaters from the table engine are resolved internally and never reach this callback.
#### `rowPinning` / `defaultRowPinning` [#rowpinning--defaultrowpinning]
Controlled and uncontrolled row pinning state: arrays of row IDs pinned to the top and bottom of the table:
```typescript
{ top: ['row-1'], bottom: [] }
```
Pinning is controlled while `rowPinning` is provided; pair it with `onRowPinningChange` to apply changes, otherwise the pinning stays frozen at that value. IDs absent from `data` are skipped when rendering, never pruned - the controlling owner is responsible for pruning stale IDs.
#### `onRowPinningChange` [#onrowpinningchange]
Called with the plain next `RowPinningState` when pinning changes (for example via the row kebab menu's Pin / Unpin actions). Functional updaters from the table engine are resolved internally and never reach this callback.
#### `kebabPosition` [#kebabposition]
Controls where the row action menu (kebab menu) appears:
* `left` - Before data columns
* `right` - After data columns (default)
#### `persistRowKebabMenu` [#persistrowkebabmenu]
When `true`, the row kebab menu is always visible. When `false`, only visible on row hover.
#### `persistHeaderKebabMenu` [#persistheaderkebabmenu]
When `true`, the header kebab menu is always visible. When `false`, only visible on hover.
#### `persistNumerals` [#persistnumerals]
When `true`, row number column is always visible. When `false`, only visible on row hover.
#### `enableSorting` [#enablesorting]
Enables column sorting. Use the column header menu (kebab) to sort ascending, sort descending, or clear sorting.
#### `enableColumnReordering` [#enablecolumnreordering]
Enables column reordering through the header kebab menu's Move Column Left / Right actions. The items are disabled at the first and last of your columns.
#### `enableRowActions` [#enablerowactions]
Enables row actions through the kebab menu, including:
* Pin/unpin row
* Move row up/down
#### `manualSorting` [#manualsorting]
When `true`, assumes data is already sorted (for server-side sorting). Disables client-side sorting; the header menu still updates the sort state and indicators, and `onSortChange` still receives the plain next `SortingState`.
#### `sort` / `defaultSort` [#sort--defaultsort]
Controlled and uncontrolled sort state. An array of `{ id, desc }` entries keyed by column id; the header menu writes at most one entry (no multi-column sort):
```typescript
[{ id: 'age', desc: true }]
```
Sorting is controlled while `sort` is provided; pair it with `onSortChange` to apply changes, otherwise the sort stays frozen at that value. This applies in both client-side and `manualSorting` modes. Use `defaultSort` to seed an uncontrolled table; it is ignored while `sort` is provided.
#### `onSortChange` [#onsortchange]
Called with the plain next `SortingState` whenever sorting changes: `[{ id, desc }]`, or `[]` when sorting is cleared. Functional updaters from the table engine are resolved internally and never reach this callback.
#### `columnOrder` / `defaultColumnOrder` [#columnorder--defaultcolumnorder]
Controlled and uncontrolled column order. An array of your column ids in display order:
```typescript
['age', 'name', 'id']
```
Only your own column ids belong in the array. The numeral, selection, and kebab columns the table adds stay in their configured positions. Columns missing from the array are appended after the named ones in `columns` definition order, and unknown ids are ignored. An empty array means `columns` definition order.
Column order is controlled while `columnOrder` is provided; pair it with `onColumnOrderChange` to apply changes, otherwise the order stays frozen at that value. Use `defaultColumnOrder` to seed an uncontrolled table; it is ignored while `columnOrder` is provided.
#### `onColumnOrderChange` [#oncolumnorderchange]
Called with the plain next `ColumnOrderState` when the order changes (for example via the header kebab menu's Move Column Left / Right actions). The array always lists every one of your columns in display order, even when `columnOrder` was partial. Functional updaters from the table engine are resolved internally and never reach this callback.
#### `onColumnReorderChange` [#oncolumnreorderchange]
Deprecated. Called with the column's index among all visible columns before the move. Use `onColumnOrderChange` instead, which receives the resulting order.
#### `fullWidth` [#fullwidth]
When `true`, applies `w-full table-fixed` classes for full-width table with fixed layout.
#### `pageSize` [#pagesize]
Number of rows per page. Enables built-in pagination when set.
#### `page` / `defaultPage` [#page--defaultpage]
Controlled and uncontrolled page number (1-indexed). Use `page` with `onPageChange` for controlled pagination, or `defaultPage` for uncontrolled.
### Row Actions [#row-actions]
The kebab menu provides these actions for each row:
* **Pin/Unpin** - Pin row to top of table
* **Move Up** - Move row up one position (disabled for pinned rows and first row)
* **Move Down** - Move row down one position (disabled for pinned rows and last row)
When rows are selected via checkboxes, move actions apply to all selected rows.
## Examples [#examples]
### Example: Basic table with sorting [#example-basic-table-with-sorting]
```tsx
import { Table } from '@accelint/design-toolkit';
const columns = [
{ accessorKey: 'name', header: 'Name' },
{ accessorKey: 'role', header: 'Role' },
{ accessorKey: 'status', header: 'Status' },
];
const data = [
{ id: '1', name: 'Alice', role: 'Engineer', status: 'Active' },
{ id: '2', name: 'Bob', role: 'Designer', status: 'Active' },
{ id: '3', name: 'Carol', role: 'Manager', status: 'Inactive' },
];
<Table columns={columns} data={data} enableSorting />
```
### Example: Table with checkboxes and row selection [#example-table-with-checkboxes-and-row-selection]
```tsx
import { Table } from '@accelint/design-toolkit';
import type { RowSelectionState } from '@tanstack/react-table';
import { useState } from 'react';
export function SelectableTable() {
const [selection, setSelection] = useState<RowSelectionState>({});
const columns = [
{ accessorKey: 'name', header: 'Name' },
{ accessorKey: 'email', header: 'Email' },
];
const data = [
{ id: '1', name: 'John Doe', email: 'john@example.com' },
{ id: '2', name: 'Jane Smith', email: 'jane@example.com' },
];
return (
<Table
columns={columns}
data={data}
showCheckbox
rowSelection={selection}
onRowSelectionChange={setSelection}
/>
);
}
```
### Example: Full-width table with pagination [#example-full-width-table-with-pagination]
```tsx
import { Table } from '@accelint/design-toolkit';
import { useState } from 'react';
export function PaginatedTable() {
const [currentPage, setCurrentPage] = useState(1);
const columns = [
{ accessorKey: 'id', header: 'ID' },
{ accessorKey: 'name', header: 'Name' },
];
const data = Array.from({ length: 50 }, (_, i) => ({
id: `${i + 1}`,
name: `Item ${i + 1}`,
}));
return (
<Table
columns={columns}
data={data}
fullWidth
pageSize={10}
page={currentPage}
onPageChange={setCurrentPage}
/>
);
}
```
### Example: Server-side sorting [#example-server-side-sorting]
```tsx
import { Table } from '@accelint/design-toolkit';
import type { SortingState } from '@tanstack/react-table';
import { useState } from 'react';
export function ServerSortedTable() {
const [sort, setSort] = useState<SortingState>([]);
const columns = [
{ accessorKey: 'name', header: 'Name' },
{ accessorKey: 'date', header: 'Date' },
];
const handleSortChange = (nextSort: SortingState) => {
setSort(nextSort);
// Fetch sorted data from the server
fetchSortedData(nextSort[0]?.id, nextSort[0]?.desc);
};
return (
<Table
columns={columns}
data={data}
manualSorting
sort={sort}
onSortChange={handleSortChange}
/>
);
}
```
### Example: Custom cell renderer [#example-custom-cell-renderer]
```tsx
import { Table } from '@accelint/design-toolkit';
import { Badge } from '@accelint/design-toolkit';
const columns = [
{ accessorKey: 'name', header: 'Name' },
{
accessorKey: 'status',
header: 'Status',
cell: ({ row }) => (
<Badge color={row.original.status === 'active' ? 'success' : 'muted'}>
{row.original.status}
</Badge>
),
},
];
const data = [
{ id: '1', name: 'Project A', status: 'active' },
{ id: '2', name: 'Project B', status: 'inactive' },
];
<Table columns={columns} data={data} />
```
### Example: Left-positioned kebab menu [#example-left-positioned-kebab-menu]
```tsx
import { Table } from '@accelint/design-toolkit';
<Table
columns={columns}
data={data}
kebabPosition="left"
enableRowActions
/>
```
### Example: Minimal row chrome [#example-minimal-row-chrome]
```tsx
import { Table } from '@accelint/design-toolkit';
<Table
columns={columns}
data={data}
persistRowKebabMenu={false}
persistNumerals={false}
/>
```
> **Good to know:** When `persistRowKebabMenu` and `persistNumerals` are `false`, these elements only appear on row hover, creating a cleaner visual appearance.
### Example: Disable specific features [#example-disable-specific-features]
```tsx
import { Table } from '@accelint/design-toolkit';
<Table
columns={columns}
data={data}
enableSorting={false}
enableColumnReordering={false}
enableRowActions={false}
/>
```
## Related [#related]
* [Button](../button/index.md) - Used for row action triggers
* [Checkbox](../checkbox/index.md) - Used for row selection
* [Menu](../menu/index.md) - Used for row and column actions
* [Icon](../icon/index.md) - Used for action icons
# Tabs (/docs/toolkits/design-toolkit/components/tabs)
Tab navigation component for organizing content into multiple sections with support for horizontal and vertical orientations.
## Usage [#usage]
```tsx
import { Tabs, TabList, Tab, TabPanel } from '@accelint/design-toolkit';
export function MyComponent() {
return (
<Tabs>
<TabList>
<Tab id="overview">Overview</Tab>
<Tab id="settings">Settings</Tab>
<Tab id="help">Help</Tab>
</TabList>
<TabPanel id="overview">
<h2>Overview</h2>
<p>Overview content goes here</p>
</TabPanel>
<TabPanel id="settings">
<h2>Settings</h2>
<p>Settings content goes here</p>
</TabPanel>
<TabPanel id="help">
<h2>Help</h2>
<p>Help content goes here</p>
</TabPanel>
</Tabs>
);
}
```
## Reference [#reference]
```typescript
interface TabsProps extends AriaTabsProps {
children?: React.ReactNode;
className?: string;
orientation?: 'horizontal' | 'vertical';
// When orientation is 'horizontal':
align?: 'start' | 'center' | 'end';
flex?: boolean;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| -------------------- | ------------------------------ | -------------- | -------- |
| `children` | `React.ReactNode` | - | Yes |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | No |
| `align` | `'start' \| 'center' \| 'end'` | `'start'` | No |
| `flex` | `boolean` | `true` | No |
| `className` | `string` | - | No |
| `defaultSelectedKey` | `Key` | - | No |
| `selectedKey` | `Key` | - | No |
| `onSelectionChange` | `(key: Key) => void` | - | No |
| `isDisabled` | `boolean` | `false` | No |
#### `orientation` [#orientation]
Controls layout direction of the tabs:
* `horizontal` - Tabs appear in a row above content (default)
* `vertical` - Tabs appear in a column beside content
#### `align` [#align]
Content alignment within each tab. Only applicable when `orientation` is `'horizontal'`.
* `start` - Left-aligned content (default)
* `center` - Center-aligned content
* `end` - Right-aligned content
#### `flex` [#flex]
When `true`, tabs flex to fill available space up to a maximum width. Only applicable when `orientation` is `'horizontal'`.
### Inherited Props [#inherited-props]
Tabs inherits props from React Aria's `Tabs`, including:
* `selectedKey` / `defaultSelectedKey` - Control selected tab
* `onSelectionChange` - Called when selection changes
* `isDisabled` - Disables all tabs
See [React Aria Tabs](https://react-spectrum.adobe.com/react-aria/Tabs.html) for full API reference.
## Sub-components [#sub-components]
### TabList [#tablist]
Container for Tab components. Must be a direct child of Tabs.
```tsx
<TabList>
<Tab id="one">First</Tab>
<Tab id="two">Second</Tab>
</TabList>
```
### Tab [#tab]
Individual tab element. The `id` prop must match the corresponding TabPanel.
```tsx
<Tab id="profile" isDisabled>Profile</Tab>
```
### TabPanel [#tabpanel]
Content panel displayed when its corresponding Tab is selected. The `id` prop must match a Tab.
```tsx
<TabPanel id="profile">
<h2>Profile Information</h2>
<p>User profile content</p>
</TabPanel>
```
## Examples [#examples]
### Example: Basic tabs [#example-basic-tabs]
```tsx
import { Tabs, TabList, Tab, TabPanel } from '@accelint/design-toolkit';
<Tabs>
<TabList>
<Tab id="home">Home</Tab>
<Tab id="profile">Profile</Tab>
<Tab id="messages">Messages</Tab>
</TabList>
<TabPanel id="home">Home content</TabPanel>
<TabPanel id="profile">Profile content</TabPanel>
<TabPanel id="messages">Messages content</TabPanel>
</Tabs>
```
### Example: Tabs with icons [#example-tabs-with-icons]
```tsx
import { Tabs, TabList, Tab, TabPanel, Icon } from '@accelint/design-toolkit';
import { Add, Check, Group } from '@accelint/icons';
<Tabs>
<TabList>
<Tab id="create">
<Icon><Add /></Icon>
Create
</Tab>
<Tab id="review">
<Icon><Check /></Icon>
Review
</Tab>
<Tab id="team">
<Icon><Group /></Icon>
Team
</Tab>
</TabList>
<TabPanel id="create">Create content</TabPanel>
<TabPanel id="review">Review content</TabPanel>
<TabPanel id="team">Team content</TabPanel>
</Tabs>
```
### Example: Icon-only tabs [#example-icon-only-tabs]
```tsx
import { Tabs, TabList, Tab, TabPanel, Icon } from '@accelint/design-toolkit';
import { Home, Settings, Bell } from '@accelint/icons';
<Tabs>
<TabList>
<Tab id="home" aria-label="Home">
<Icon><Home /></Icon>
</Tab>
<Tab id="settings" aria-label="Settings">
<Icon><Settings /></Icon>
</Tab>
<Tab id="notifications" aria-label="Notifications">
<Icon><Bell /></Icon>
</Tab>
</TabList>
<TabPanel id="home">Home content</TabPanel>
<TabPanel id="settings">Settings content</TabPanel>
<TabPanel id="notifications">Notifications content</TabPanel>
</Tabs>
```
> **Good to know:** When using icon-only tabs, always provide an `aria-label` on each Tab for accessibility.
### Example: Vertical orientation [#example-vertical-orientation]
```tsx
import { Tabs, TabList, Tab, TabPanel } from '@accelint/design-toolkit';
<Tabs orientation="vertical">
<TabList>
<Tab id="general">General</Tab>
<Tab id="security">Security</Tab>
<Tab id="notifications">Notifications</Tab>
</TabList>
<TabPanel id="general">General settings</TabPanel>
<TabPanel id="security">Security settings</TabPanel>
<TabPanel id="notifications">Notification preferences</TabPanel>
</Tabs>
```
### Example: Center-aligned tabs [#example-center-aligned-tabs]
```tsx
import { Tabs, TabList, Tab, TabPanel } from '@accelint/design-toolkit';
<Tabs align="center">
<TabList>
<Tab id="one">First</Tab>
<Tab id="two">Second</Tab>
<Tab id="three">Third</Tab>
</TabList>
<TabPanel id="one">First panel</TabPanel>
<TabPanel id="two">Second panel</TabPanel>
<TabPanel id="three">Third panel</TabPanel>
</Tabs>
```
### Example: Non-flexing tabs [#example-non-flexing-tabs]
```tsx
import { Tabs, TabList, Tab, TabPanel } from '@accelint/design-toolkit';
<Tabs flex={false}>
<TabList>
<Tab id="short">A</Tab>
<Tab id="medium">Medium</Tab>
<Tab id="long">Very Long Tab Name</Tab>
</TabList>
<TabPanel id="short">Short panel</TabPanel>
<TabPanel id="medium">Medium panel</TabPanel>
<TabPanel id="long">Long panel</TabPanel>
</Tabs>
```
### Example: Controlled tabs [#example-controlled-tabs]
```tsx
import { useState } from 'react';
import { Tabs, TabList, Tab, TabPanel, Button } from '@accelint/design-toolkit';
function ControlledTabs() {
const [selectedTab, setSelectedTab] = useState('overview');
return (
<>
<div className="mb-m flex gap-s">
<Button onPress={() => setSelectedTab('overview')}>Show Overview</Button>
<Button onPress={() => setSelectedTab('details')}>Show Details</Button>
</div>
<Tabs selectedKey={selectedTab} onSelectionChange={setSelectedTab}>
<TabList>
<Tab id="overview">Overview</Tab>
<Tab id="details">Details</Tab>
<Tab id="history">History</Tab>
</TabList>
<TabPanel id="overview">Overview content</TabPanel>
<TabPanel id="details">Details content</TabPanel>
<TabPanel id="history">History content</TabPanel>
</Tabs>
</>
);
}
```
### Example: Disabled tabs [#example-disabled-tabs]
```tsx
import { Tabs, TabList, Tab, TabPanel } from '@accelint/design-toolkit';
<Tabs>
<TabList>
<Tab id="active">Active Tab</Tab>
<Tab id="disabled" isDisabled>Disabled Tab</Tab>
<Tab id="another">Another Tab</Tab>
</TabList>
<TabPanel id="active">Active content</TabPanel>
<TabPanel id="disabled">Disabled content</TabPanel>
<TabPanel id="another">Another content</TabPanel>
</Tabs>
```
### Example: Tabs with default selection [#example-tabs-with-default-selection]
```tsx
import { Tabs, TabList, Tab, TabPanel } from '@accelint/design-toolkit';
<Tabs defaultSelectedKey="settings">
<TabList>
<Tab id="profile">Profile</Tab>
<Tab id="settings">Settings</Tab>
<Tab id="billing">Billing</Tab>
</TabList>
<TabPanel id="profile">Profile content</TabPanel>
<TabPanel id="settings">Settings content (default)</TabPanel>
<TabPanel id="billing">Billing content</TabPanel>
</Tabs>
```
### Example: Responding to selection changes [#example-responding-to-selection-changes]
```tsx
import { Tabs, TabList, Tab, TabPanel } from '@accelint/design-toolkit';
<Tabs onSelectionChange={(key) => console.log('Selected:', key)}>
<TabList>
<Tab id="analytics">Analytics</Tab>
<Tab id="reports">Reports</Tab>
<Tab id="exports">Exports</Tab>
</TabList>
<TabPanel id="analytics">Analytics content</TabPanel>
<TabPanel id="reports">Reports content</TabPanel>
<TabPanel id="exports">Exports content</TabPanel>
</Tabs>
```
## Related [#related]
* [Button](../button/index.md) - Action component sometimes used in tab panels
* [Icon](../icon/index.md) - Used for icon tabs
# TextAreaField (/docs/toolkits/design-toolkit/components/text-area-field)
## Usage [#usage]
```tsx
import { TextAreaField } from '@accelint/design-toolkit';
export function MyForm() {
return (
<TextAreaField
label="Description"
placeholder="Enter a detailed description..."
onChange={(value) => setDescription(value)}
/>
);
}
```
## Reference [#reference]
```typescript
interface TextAreaFieldProps extends Omit<TextFieldProps, 'children' | 'className'> {
label?: string;
description?: string;
errorMessage?: string;
size?: 'medium' | 'small';
inputProps?: Omit<TextAreaProps, 'className'>;
classNames?: {
field?: TextFieldProps['className'];
label?: string;
input?: TextAreaProps['className'];
description?: string;
error?: FieldErrorProps['className'];
};
}
```
### Props [#props]
| Prop | Type | Default | Required |
| -------------- | ------------------------- | ---------- | -------- |
| `label` | `string` | - | No |
| `description` | `string` | - | No |
| `errorMessage` | `string` | - | No |
| `size` | `'medium' \| 'small'` | `'medium'` | No |
| `inputProps` | `TextAreaProps` | - | No |
| `classNames` | `TextAreaFieldClassNames` | - | No |
| `isInvalid` | `boolean` | `false` | No |
| `isDisabled` | `boolean` | `false` | No |
| `isRequired` | `boolean` | `false` | No |
#### `label` [#label]
Label text displayed above the textarea. Automatically associates with the input for accessibility. Hidden when `size="small"`.
#### `description` [#description]
Helper text displayed below the textarea. Hidden when `size="small"` or when the field is invalid.
#### `errorMessage` [#errormessage]
Error message displayed when validation fails. Automatically sets `isInvalid` to `true` when provided.
#### `size` [#size]
Controls field sizing and visibility of label and description:
* `medium` - Standard size with visible label and description (default)
* `small` - Compact size, hides label and description
#### `inputProps` [#inputprops]
Props passed directly to the underlying `TextArea` component, including:
* `placeholder` - Placeholder text
* `rows` - Number of visible text rows
* `maxLength` - Maximum character length
* `autoResize` - Auto-resize to fit content
#### `classNames` [#classnames]
Custom CSS class names for field elements:
* `field` - Container element
* `label` - Label element
* `input` - TextArea element
* `description` - Description text element
* `error` - Error message element
### Inherited Props [#inherited-props]
TextAreaField inherits all props from React Aria's `TextField` component, including:
* `value` / `defaultValue` - Controlled/uncontrolled value
* `onChange` - Called when value changes (receives string)
* `onBlur` / `onFocus` - Focus event handlers
* `validate` - Custom validation function
* `name` - Form field name
See [React Aria TextField](https://react-spectrum.adobe.com/react-aria/TextField.html) for full API reference.
## Examples [#examples]
### Example: Basic textarea [#example-basic-textarea]
```tsx
import { TextAreaField } from '@accelint/design-toolkit';
<TextAreaField
label="Comments"
placeholder="Add your comments here..."
onChange={(value) => setComments(value)}
/>
```
### Example: With description [#example-with-description]
```tsx
import { TextAreaField } from '@accelint/design-toolkit';
<TextAreaField
label="Bio"
description="Tell us about yourself (max 500 characters)"
inputProps={{ maxLength: 500 }}
/>
```
### Example: Required field with validation [#example-required-field-with-validation]
```tsx
import { TextAreaField } from '@accelint/design-toolkit';
<TextAreaField
label="Feedback"
isRequired
validate={(value) => {
if (value.length < 10) {
return 'Feedback must be at least 10 characters';
}
}}
/>
```
### Example: With error message [#example-with-error-message]
```tsx
import { TextAreaField } from '@accelint/design-toolkit';
<TextAreaField
label="Message"
isInvalid
errorMessage="Message cannot be empty"
/>
```
### Example: Disabled state [#example-disabled-state]
```tsx
import { TextAreaField } from '@accelint/design-toolkit';
<TextAreaField
label="System log"
value={logContent}
isDisabled
description="Read-only system log"
/>
```
### Example: Custom rows [#example-custom-rows]
```tsx
import { TextAreaField } from '@accelint/design-toolkit';
<TextAreaField
label="Code snippet"
inputProps={{ rows: 10 }}
placeholder="Paste your code here..."
/>
```
### Example: Small size variant [#example-small-size-variant]
```tsx
import { TextAreaField } from '@accelint/design-toolkit';
<TextAreaField
size="small"
placeholder="Quick note..."
inputProps={{ rows: 3 }}
/>
```
> **Good to know:** The `small` size hides the label and description to create a compact textarea. Always provide a `placeholder` for context.
### Example: Controlled value [#example-controlled-value]
```tsx
import { useState } from 'react';
import { TextAreaField } from '@accelint/design-toolkit';
export function ControlledExample() {
const [value, setValue] = useState('');
return (
<TextAreaField
label="Notes"
value={value}
onChange={setValue}
description={`${value.length} characters`}
/>
);
}
```
### Example: Character counter [#example-character-counter]
```tsx
import { useState } from 'react';
import { TextAreaField } from '@accelint/design-toolkit';
export function CharacterCounter() {
const [value, setValue] = useState('');
const maxLength = 280;
return (
<TextAreaField
label="Tweet"
value={value}
onChange={setValue}
inputProps={{ maxLength }}
description={`${value.length}/${maxLength} characters`}
/>
);
}
```
### Example: With validation [#example-with-validation]
```tsx
import { TextAreaField } from '@accelint/design-toolkit';
<TextAreaField
label="Description"
validate={(value) => {
if (!value.trim()) {
return 'Description is required';
}
if (value.length < 20) {
return 'Description must be at least 20 characters';
}
if (value.length > 500) {
return 'Description must be less than 500 characters';
}
}}
/>
```
### Example: Custom styling [#example-custom-styling]
```tsx
import { TextAreaField } from '@accelint/design-toolkit';
<TextAreaField
label="Custom Field"
classNames={{
field: 'mb-4',
label: 'font-bold',
input: 'rounded-lg min-h-32',
error: 'text-sm',
}}
/>
```
## Related [#related]
* [TextField](../text-field/index.md) - Single-line text input
* [Label](../label/index.md) - Label component with required indicator
* [Input](../input/index.md) - Base input component
# TextField (/docs/toolkits/design-toolkit/components/text-field)
## Usage [#usage]
```tsx
import { TextField } from '@accelint/design-toolkit';
export function MyForm() {
return (
<TextField
label="Email"
type="email"
description="We'll never share your email"
onChange={(value) => console.log(value)}
/>
);
}
```
## Reference [#reference]
```typescript
interface TextFieldProps extends Omit<AriaTextFieldProps, 'children' | 'className' | 'type' | 'pattern'> {
label?: string;
description?: string;
errorMessage?: string;
size?: 'medium' | 'small';
inputProps?: InputProps;
classNames?: {
field?: AriaTextFieldProps['className'];
label?: LabelProps['className'];
input?: InputProps['classNames'];
description?: string;
error?: FieldErrorProps['className'];
};
}
```
### Props [#props]
| Prop | Type | Default | Required |
| -------------- | --------------------- | ---------- | -------- |
| `label` | `string` | - | No |
| `description` | `string` | - | No |
| `errorMessage` | `string` | - | No |
| `size` | `'medium' \| 'small'` | `'medium'` | No |
| `inputProps` | `InputProps` | - | No |
| `classNames` | `TextFieldClassNames` | - | No |
| `isInvalid` | `boolean` | `false` | No |
| `isDisabled` | `boolean` | `false` | No |
| `isRequired` | `boolean` | `false` | No |
#### `label` [#label]
Label text displayed above the input. Automatically associates with the input for accessibility. Hidden when `size="small"`.
#### `description` [#description]
Helper text displayed below the input. Hidden when `size="small"` or when the field is invalid.
#### `errorMessage` [#errormessage]
Error message displayed when validation fails. Automatically sets `isInvalid` to `true` when provided.
#### `size` [#size]
Controls field sizing and visibility of label and description:
* `medium` - Standard size with visible label and description (default)
* `small` - Compact size, hides label and description
#### `inputProps` [#inputprops]
Props passed directly to the underlying `Input` component, including:
* `placeholder` - Placeholder text
* `type` - HTML input type (text, email, password, etc.)
* `autoComplete` - Browser autocomplete hint
* `maxLength` - Maximum character length
See [Input](../input/index.md) for full props reference.
#### `classNames` [#classnames]
Custom CSS class names for field elements:
* `field` - Container element
* `label` - Label element
* `input` - Input element (supports nested classNames)
* `description` - Description text element
* `error` - Error message element
### Inherited Props [#inherited-props]
TextField inherits all props from React Aria's `TextField` component, including:
* `value` / `defaultValue` - Controlled/uncontrolled value
* `onChange` - Called when value changes (receives string)
* `onBlur` / `onFocus` - Focus event handlers
* `validate` - Custom validation function
* `name` - Form field name
See [React Aria TextField](https://react-spectrum.adobe.com/react-aria/TextField.html) for full API reference.
## Examples [#examples]
### Example: Basic text field [#example-basic-text-field]
```tsx
import { TextField } from '@accelint/design-toolkit';
<TextField
label="Username"
placeholder="Enter username"
onChange={(value) => setUsername(value)}
/>
```
### Example: Email with validation [#example-email-with-validation]
```tsx
import { TextField } from '@accelint/design-toolkit';
<TextField
label="Email"
type="email"
description="We'll never share your email"
validate={(value) => {
if (!value.includes('@')) {
return 'Please enter a valid email';
}
}}
/>
```
### Example: Required field [#example-required-field]
```tsx
import { TextField } from '@accelint/design-toolkit';
<TextField
label="Full Name"
isRequired
errorMessage="Name is required"
/>
```
### Example: Disabled state [#example-disabled-state]
```tsx
import { TextField } from '@accelint/design-toolkit';
<TextField
label="Account ID"
value="12345"
isDisabled
description="Cannot be changed"
/>
```
### Example: Small size variant [#example-small-size-variant]
```tsx
import { TextField } from '@accelint/design-toolkit';
<TextField
size="small"
placeholder="Search..."
inputProps={{ type: 'search' }}
/>
```
> **Good to know:** The `small` size hides the label and description to create a compact input. Always provide a `placeholder` for context.
### Example: Password with error [#example-password-with-error]
```tsx
import { TextField } from '@accelint/design-toolkit';
<TextField
label="Password"
type="password"
isInvalid
errorMessage="Password must be at least 8 characters"
/>
```
### Example: Controlled value [#example-controlled-value]
```tsx
import { useState } from 'react';
import { TextField } from '@accelint/design-toolkit';
export function ControlledExample() {
const [value, setValue] = useState('');
return (
<TextField
label="Message"
value={value}
onChange={setValue}
description={`${value.length} characters`}
/>
);
}
```
### Example: Custom styling [#example-custom-styling]
```tsx
import { TextField } from '@accelint/design-toolkit';
<TextField
label="Custom Field"
classNames={{
field: 'mb-4',
label: 'font-bold',
input: { sizer: 'rounded-lg' },
error: 'text-sm',
}}
/>
```
## Related [#related]
* [Input](../input/index.md) - Underlying input component
* [Label](../label/index.md) - Label component with required indicator
* [TextAreaField](../text-area-field/index.md) - Multi-line text input
# TimeField (/docs/toolkits/design-toolkit/components/time-field)
A time input component with segmented editing, providing accessible time input with separate segments for hours, minutes, and seconds. Includes time icon, validation states, configurable granularity, and support for both 12-hour and 24-hour formats with keyboard navigation between segments.
## Usage [#usage]
```tsx
import { TimeField } from '@accelint/design-toolkit';
export function MyForm() {
return <TimeField label="Start time" granularity="minute" />;
}
```
## Reference [#reference]
```typescript
interface TimeFieldProps<T extends TimeValue> {
label?: string;
description?: string;
errorMessage?: string;
size?: 'small' | 'medium';
granularity?: 'hour' | 'minute' | 'second';
hourCycle?: 12 | 24;
shouldForceLeadingZeros?: boolean;
isDisabled?: boolean;
isInvalid?: boolean;
isRequired?: boolean;
isReadOnly?: boolean;
value?: T;
defaultValue?: T;
onChange?: (value: T) => void;
classNames?: {
field?: string;
label?: string;
control?: string;
input?: string;
segment?: string;
description?: string;
error?: string;
};
inputProps?: Omit<DateInputProps, 'children' | 'className'>;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ------------------------- | -------------------------------- | ---------- | -------- |
| `label` | `string` | - | No |
| `description` | `string` | - | No |
| `errorMessage` | `string` | - | No |
| `size` | `'small' \| 'medium'` | `'medium'` | No |
| `granularity` | `'hour' \| 'minute' \| 'second'` | `'second'` | No |
| `hourCycle` | `12 \| 24` | `24` | No |
| `shouldForceLeadingZeros` | `boolean` | `true` | No |
| `isDisabled` | `boolean` | `false` | No |
| `isInvalid` | `boolean` | `false` | No |
| `isRequired` | `boolean` | `false` | No |
| `isReadOnly` | `boolean` | `false` | No |
| `value` | `TimeValue` | - | No |
| `defaultValue` | `TimeValue` | - | No |
| `onChange` | `(value: TimeValue) => void` | - | No |
| `classNames` | `object` | - | No |
| `inputProps` | `DateInputProps` | - | No |
#### `granularity` [#granularity]
Controls which time segments are displayed:
* `hour` - Only hour segment
* `minute` - Hour and minute segments
* `second` - Hour, minute, and second segments (default)
#### `hourCycle` [#hourcycle]
Controls whether to use 12-hour or 24-hour time format:
* `12` - 12-hour format with AM/PM
* `24` - 24-hour format (default)
#### `size` [#size]
Controls the visual size of the time field:
* `medium` - Default size with time icon and full label
* `small` - Compact size without time icon or visible label (label used for aria-label only)
#### `shouldForceLeadingZeros` [#shouldforceleadingzeros]
Whether to force leading zeros in time segments. For example, `09:05:03` vs `9:5:3`.
#### `classNames` [#classnames]
Custom class names for sub-elements:
* `field` - The outer field container
* `label` - The label element
* `control` - The control wrapper containing icon and input
* `input` - The time input element
* `segment` - Individual time segments (hour, minute, second, dayPeriod)
* `description` - The description text
* `error` - The error message element
### Inherited Props [#inherited-props]
TimeField inherits all props from React Aria's `TimeField` component, including:
* `minValue` - Minimum allowed time
* `maxValue` - Maximum allowed time
* `placeholderValue` - Placeholder time shown when empty
See [React Aria TimeField](https://react-spectrum.adobe.com/react-aria/TimeField.html) for full API reference.
## Examples [#examples]
### Example: Basic time field [#example-basic-time-field]
```tsx
import { TimeField } from '@accelint/design-toolkit';
<TimeField label="Meeting Time" granularity="minute" />
```
### Example: 12-hour format [#example-12-hour-format]
```tsx
import { TimeField } from '@accelint/design-toolkit';
<TimeField
label="Appointment Time"
hourCycle={12}
granularity="minute"
/>
```
### Example: Controlled value [#example-controlled-value]
```tsx
import { TimeField } from '@accelint/design-toolkit';
import { parseTime } from '@internationalized/date';
import { useState } from 'react';
export function ControlledTimeField() {
const [time, setTime] = useState(parseTime('14:30:00'));
return (
<TimeField
label="Selected Time"
value={time}
onChange={setTime}
granularity="minute"
/>
);
}
```
### Example: Hour only [#example-hour-only]
```tsx
import { TimeField } from '@accelint/design-toolkit';
<TimeField
label="Hour"
granularity="hour"
/>
```
### Example: Required with validation [#example-required-with-validation]
```tsx
import { TimeField } from '@accelint/design-toolkit';
import { parseTime } from '@internationalized/date';
<TimeField
label="Office Hours"
isRequired
minValue={parseTime('09:00:00')}
maxValue={parseTime('17:00:00')}
errorMessage="Please select a time between 9 AM and 5 PM"
/>
```
### Example: Compact size [#example-compact-size]
```tsx
import { TimeField } from '@accelint/design-toolkit';
<TimeField
label="Time"
size="small"
granularity="minute"
/>
```
> **Good to know:** In `small` size, the label is not visually displayed but is used for the `aria-label` attribute for accessibility.
### Example: Read-only state [#example-read-only-state]
```tsx
import { TimeField } from '@accelint/design-toolkit';
import { parseTime } from '@internationalized/date';
<TimeField
label="Scheduled At"
value={parseTime('14:30:00')}
isReadOnly
granularity="minute"
/>
```
### Example: With description and error [#example-with-description-and-error]
```tsx
import { TimeField } from '@accelint/design-toolkit';
import { useState } from 'react';
export function ValidatedTimeField() {
const [isInvalid, setIsInvalid] = useState(false);
return (
<TimeField
label="Delivery Time"
description="Select a time for delivery"
granularity="minute"
isInvalid={isInvalid}
errorMessage={isInvalid ? 'Time must be between 9 AM and 5 PM' : undefined}
onChange={(value) => {
// Validate time
setIsInvalid(value.hour < 9 || value.hour >= 17);
}}
/>
);
}
```
> **Good to know:** The TimeField automatically appends "Z" to indicate UTC timezone in the display.
## Related [#related]
* [DateField](../date-field/index.md) - Date input with segmented editing
* [Label](../label/index.md) - Label component used internally
* [Icon](../icon/index.md) - Icon component for time icon
# Tooltip (/docs/toolkits/design-toolkit/components/tooltip)
Contextual popup that displays on hover or focus with automatic positioning and accessibility support.
## Usage [#usage]
```tsx
import { Tooltip, TooltipTrigger, Button } from '@accelint/design-toolkit';
export function MyComponent() {
return (
<TooltipTrigger>
<Button>Hover me</Button>
<Tooltip>Additional information</Tooltip>
</TooltipTrigger>
);
}
```
## Reference [#reference]
```typescript
interface TooltipProps extends AriaTooltipProps {
children?: React.ReactNode;
parentRef?: RefObject<HTMLElement | null>;
className?: string;
offset?: number;
placement?: 'top' | 'bottom' | 'left' | 'right' | 'top start' | 'top end' | 'bottom start' | 'bottom end';
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ----------- | ----------------------------------------------- | ---------- | -------- |
| `children` | `React.ReactNode` | - | Yes |
| `placement` | `'top' \| 'bottom' \| 'left' \| 'right' \| ...` | `'bottom'` | No |
| `offset` | `number` | `5` | No |
| `className` | `string` | - | No |
| `parentRef` | `RefObject<HTMLElement \| null>` | - | No |
#### `placement` [#placement]
Controls where the tooltip appears relative to the trigger element. Supports basic positions and alignment modifiers.
#### `offset` [#offset]
Distance in pixels between the tooltip and its trigger element.
#### `parentRef` [#parentref]
Reference to a parent element for portal rendering. When provided, the tooltip renders into the specified container instead of document body.
### Inherited Props [#inherited-props]
Tooltip inherits props from React Aria's `Tooltip`, including:
* `isEntering` - Whether tooltip is entering (for animations)
* `isExiting` - Whether tooltip is exiting (for animations)
See [React Aria Tooltip](https://react-spectrum.adobe.com/react-aria/Tooltip.html) for full API reference.
## Sub-components [#sub-components]
### TooltipTrigger [#tooltiptrigger]
Wrapper that manages tooltip display on hover or focus. Provides delay and timing controls.
```tsx
<TooltipTrigger delay={500}>
<Button>Trigger</Button>
<Tooltip>Content</Tooltip>
</TooltipTrigger>
```
#### TooltipTrigger Props [#tooltiptrigger-props]
| Prop | Type | Default | Required |
| ------------ | -------- | ------- | -------- |
| `delay` | `number` | `250` | No |
| `closeDelay` | `number` | `0` | No |
* `delay` - Delay in milliseconds before showing the tooltip on hover/focus
* `closeDelay` - Delay in milliseconds before hiding the tooltip
## Examples [#examples]
### Example: Basic tooltip [#example-basic-tooltip]
```tsx
import { Tooltip, TooltipTrigger, Button } from '@accelint/design-toolkit';
<TooltipTrigger>
<Button>Save</Button>
<Tooltip>Save your changes</Tooltip>
</TooltipTrigger>
```
### Example: Tooltip with icon [#example-tooltip-with-icon]
```tsx
import { Tooltip, TooltipTrigger, Icon } from '@accelint/design-toolkit';
import { Information } from '@accelint/icons';
<TooltipTrigger>
<Icon className="fg-primary-bold h-xl w-xl">
<Information />
</Icon>
<Tooltip>Additional information about this feature</Tooltip>
</TooltipTrigger>
```
### Example: Long tooltip text [#example-long-tooltip-text]
```tsx
import { Tooltip, TooltipTrigger } from '@accelint/design-toolkit';
<TooltipTrigger>
<span className="fg-primary-bold">More Info</span>
<Tooltip>
A floating label used to explain an element or provide additional context
</Tooltip>
</TooltipTrigger>
```
### Example: Different placements [#example-different-placements]
```tsx
import { Tooltip, TooltipTrigger, Button } from '@accelint/design-toolkit';
<div className="flex gap-m">
<TooltipTrigger>
<Button>Top</Button>
<Tooltip placement="top">Appears above</Tooltip>
</TooltipTrigger>
<TooltipTrigger>
<Button>Bottom</Button>
<Tooltip placement="bottom">Appears below</Tooltip>
</TooltipTrigger>
<TooltipTrigger>
<Button>Left</Button>
<Tooltip placement="left">Appears to the left</Tooltip>
</TooltipTrigger>
<TooltipTrigger>
<Button>Right</Button>
<Tooltip placement="right">Appears to the right</Tooltip>
</TooltipTrigger>
</div>
```
### Example: Custom delay [#example-custom-delay]
```tsx
import { Tooltip, TooltipTrigger, Button } from '@accelint/design-toolkit';
<TooltipTrigger delay={1000} closeDelay={500}>
<Button>Slow Tooltip</Button>
<Tooltip>This tooltip appears after 1 second</Tooltip>
</TooltipTrigger>
```
### Example: Custom offset [#example-custom-offset]
```tsx
import { Tooltip, TooltipTrigger, Button } from '@accelint/design-toolkit';
<TooltipTrigger>
<Button>More Space</Button>
<Tooltip offset={15}>
This tooltip has increased spacing from the trigger
</Tooltip>
</TooltipTrigger>
```
### Example: Tooltip with custom styling [#example-tooltip-with-custom-styling]
```tsx
import { Tooltip, TooltipTrigger, Button } from '@accelint/design-toolkit';
<TooltipTrigger>
<Button>Styled Tooltip</Button>
<Tooltip className="bg-critical-bold fg-white border-critical-subtle">
Critical warning information
</Tooltip>
</TooltipTrigger>
```
### Example: Tooltip on disabled button [#example-tooltip-on-disabled-button]
```tsx
import { Tooltip, TooltipTrigger, Button } from '@accelint/design-toolkit';
<TooltipTrigger>
<div>
<Button isDisabled>Disabled Action</Button>
</div>
<Tooltip>This action is currently unavailable</Tooltip>
</TooltipTrigger>
```
> **Good to know:** Wrap disabled elements in a `<div>` to ensure the tooltip trigger works, since disabled elements don't fire pointer events.
### Example: Icon button with tooltip [#example-icon-button-with-tooltip]
```tsx
import { Tooltip, TooltipTrigger, Button, Icon } from '@accelint/design-toolkit';
import { Settings } from '@accelint/icons';
<TooltipTrigger>
<Button variant="icon" aria-label="Settings">
<Icon><Settings /></Icon>
</Button>
<Tooltip>Open Settings</Tooltip>
</TooltipTrigger>
```
> **Good to know:** Always provide both `aria-label` on icon buttons AND a tooltip for the best accessibility. The `aria-label` is for screen readers, while the tooltip helps sighted users.
## Related [#related]
* [Popover](../popover/index.md) - Non-modal overlay for interactive content
* [Dialog](../dialog/index.md) - Modal overlay for critical interactions
* [Button](../button/index.md) - Common trigger element for tooltips
* [Icon](../icon/index.md) - Common tooltip trigger for information indicators
# Tree (/docs/toolkits/design-toolkit/components/tree)
## Usage [#usage]
```tsx
import { Tree, TreeItem, TreeItemContent, TreeItemLabel } from '@accelint/design-toolkit';
export function FileExplorer() {
return (
<Tree>
<TreeItem id="root" textValue="Root">
<TreeItemContent>
<TreeItemLabel>Root Folder</TreeItemLabel>
</TreeItemContent>
<TreeItem id="child" textValue="Child">
<TreeItemContent>
<TreeItemLabel>Child Folder</TreeItemLabel>
</TreeItemContent>
</TreeItem>
</TreeItem>
</Tree>
);
}
```
## Reference [#reference]
```typescript
interface TreeProps<T> {
children: React.ReactNode | ((item: TreeNode<T>) => React.ReactNode);
className?: string;
disabledKeys?: Set<Key>;
dragAndDropConfig?: DragAndDropConfig;
expandedKeys?: Set<Key>;
items?: Iterable<TreeNode<T>>;
selectedKeys?: Set<Key>;
selectionMode?: 'none' | 'single' | 'multiple';
showRuleLines?: boolean;
showVisibility?: boolean;
variant?: 'cozy' | 'compact' | 'crammed';
visibleKeys?: Set<Key>;
onSelectionChange?: (keys: Set<Key>) => void;
onVisibilityChange?: (keys: Set<Key>) => void;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| -------------------- | ------------------------------------------------------------- | ------------ | -------- |
| `children` | `React.ReactNode \| ((item: TreeNode<T>) => React.ReactNode)` | - | Yes |
| `className` | `string` | - | No |
| `disabledKeys` | `Set<Key>` | - | No |
| `dragAndDropConfig` | `DragAndDropConfig` | - | No |
| `expandedKeys` | `Set<Key>` | - | No |
| `items` | `Iterable<TreeNode<T>>` | - | No |
| `selectedKeys` | `Set<Key>` | - | No |
| `selectionMode` | `'none' \| 'single' \| 'multiple'` | `'multiple'` | No |
| `showRuleLines` | `boolean` | `true` | No |
| `showVisibility` | `boolean` | `true` | No |
| `variant` | `'cozy' \| 'compact' \| 'crammed'` | `'cozy'` | No |
| `visibleKeys` | `Set<Key>` | - | No |
| `onSelectionChange` | `(keys: Set<Key>) => void` | - | No |
| `onVisibilityChange` | `(keys: Set<Key>) => void` | - | No |
#### `children` [#children]
For static trees, pass TreeItem components directly as children. For dynamic trees (when using `items`), provide a render function that receives a `TreeNode<T>` and returns a TreeItem.
#### `items` [#items]
Data source for dynamic collections. When provided, `children` must be a render function. Creates a data-driven tree from an external data structure.
> **Good to know:** Tree should only be controlled with state from either `items` (dynamic) or keys props (static), not both. Mixing these patterns will throw an error.
#### `selectionMode` [#selectionmode]
Controls how items can be selected:
* `none` - Selection disabled
* `single` - Only one item can be selected at a time
* `multiple` - Multiple items can be selected (default)
#### `variant` [#variant]
Visual density variant that controls spacing and sizing:
* `cozy` - Default comfortable spacing
* `compact` - Reduced spacing for denser layouts
* `crammed` - Minimal spacing for maximum density
The `variant` prop automatically flows through context to all TreeItem components.
#### `showRuleLines` [#showrulelines]
Whether to show connecting lines between tree items. These lines help visualize the hierarchical structure.
#### `showVisibility` [#showvisibility]
Whether to show visibility toggle buttons on each item. When enabled, users can toggle item visibility, which cascades to child items.
#### `dragAndDropConfig` [#draganddropconfig]
Configuration object for drag-and-drop behavior. Enables reordering and moving items within the tree or between trees.
### Type Parameters [#type-parameters]
* `T` - The type of custom values stored in tree nodes (accessed via `node.values`). Use this to attach application-specific data to each tree node.
## Examples [#examples]
### Example: Static tree with nested items [#example-static-tree-with-nested-items]
```tsx
import { Tree, TreeItem, TreeItemContent, TreeItemLabel } from '@accelint/design-toolkit';
<Tree>
<TreeItem id="documents" textValue="Documents">
<TreeItemContent>
<TreeItemLabel>Documents</TreeItemLabel>
</TreeItemContent>
<TreeItem id="readme" textValue="README.md">
<TreeItemContent>
<TreeItemLabel>README.md</TreeItemLabel>
</TreeItemContent>
</TreeItem>
<TreeItem id="license" textValue="LICENSE">
<TreeItemContent>
<TreeItemLabel>LICENSE</TreeItemLabel>
</TreeItemContent>
</TreeItem>
</TreeItem>
</Tree>
```
### Example: Dynamic tree with data source [#example-dynamic-tree-with-data-source]
```tsx
import { Tree, TreeItem, TreeItemContent, TreeItemLabel } from '@accelint/design-toolkit';
const items = [
{
key: 'src',
label: 'src',
children: [
{ key: 'index.ts', label: 'index.ts' },
{ key: 'utils.ts', label: 'utils.ts' },
],
},
];
<Tree items={items}>
{(node) => (
<TreeItem id={node.key} textValue={node.label}>
<TreeItemContent>
<TreeItemLabel>{node.label}</TreeItemLabel>
</TreeItemContent>
</TreeItem>
)}
</Tree>
```
### Example: Controlled selection [#example-controlled-selection]
```tsx
import { Tree, TreeItem, TreeItemContent, TreeItemLabel } from '@accelint/design-toolkit';
import { useState } from 'react';
function ControlledTree() {
const [selectedKeys, setSelectedKeys] = useState(new Set(['readme']));
return (
<Tree
selectedKeys={selectedKeys}
onSelectionChange={setSelectedKeys}
selectionMode="multiple"
>
<TreeItem id="readme" textValue="README">
<TreeItemContent>
<TreeItemLabel>README.md</TreeItemLabel>
</TreeItemContent>
</TreeItem>
<TreeItem id="license" textValue="LICENSE">
<TreeItemContent>
<TreeItemLabel>LICENSE</TreeItemLabel>
</TreeItemContent>
</TreeItem>
</Tree>
);
}
```
### Example: Tree with custom node values [#example-tree-with-custom-node-values]
```tsx
import { Tree, TreeItem, TreeItemContent, TreeItemLabel, TreeItemPrefixIcon } from '@accelint/design-toolkit';
import { Folder } from '@accelint/icons';
type FileMetadata = {
icon: React.ReactNode;
size?: string;
};
const items: TreeNode<FileMetadata>[] = [
{
key: 'documents',
label: 'Documents',
values: {
icon: <Folder />,
},
},
];
<Tree items={items}>
{(node) => (
<TreeItem id={node.key} textValue={node.label}>
<TreeItemContent>
<TreeItemPrefixIcon>{node.values.icon}</TreeItemPrefixIcon>
<TreeItemLabel>{node.label}</TreeItemLabel>
</TreeItemContent>
</TreeItem>
)}
</Tree>
```
### Example: Compact variant for dense layouts [#example-compact-variant-for-dense-layouts]
```tsx
import { Tree, TreeItem, TreeItemContent, TreeItemLabel } from '@accelint/design-toolkit';
<Tree variant="compact" showRuleLines={false}>
<TreeItem id="root" textValue="Root">
<TreeItemContent>
<TreeItemLabel>Compact Item</TreeItemLabel>
</TreeItemContent>
</TreeItem>
</Tree>
```
### Example: Single selection mode [#example-single-selection-mode]
```tsx
import { Tree, TreeItem, TreeItemContent, TreeItemLabel } from '@accelint/design-toolkit';
<Tree selectionMode="single">
<TreeItem id="option1" textValue="Option 1">
<TreeItemContent>
<TreeItemLabel>Option 1</TreeItemLabel>
</TreeItemContent>
</TreeItem>
<TreeItem id="option2" textValue="Option 2">
<TreeItemContent>
<TreeItemLabel>Option 2</TreeItemLabel>
</TreeItemContent>
</TreeItem>
</Tree>
```
### Example: Visibility control [#example-visibility-control]
```tsx
import { Tree, TreeItem, TreeItemContent, TreeItemLabel } from '@accelint/design-toolkit';
import { useState } from 'react';
function VisibilityTree() {
const [visibleKeys, setVisibleKeys] = useState(new Set(['item1', 'item2']));
return (
<Tree
showVisibility
visibleKeys={visibleKeys}
onVisibilityChange={setVisibleKeys}
>
<TreeItem id="item1" textValue="Item 1">
<TreeItemContent>
<TreeItemLabel>Item 1</TreeItemLabel>
</TreeItemContent>
</TreeItem>
<TreeItem id="item2" textValue="Item 2">
<TreeItemContent>
<TreeItemLabel>Item 2</TreeItemLabel>
</TreeItemContent>
</TreeItem>
</Tree>
);
}
```
## Multi-Part Structure [#multi-part-structure]
Tree is a multi-part component composed of several sub-components:
* **Tree** - Root container that manages state and context
* **TreeItem** - Individual node in the hierarchy
* **TreeItemContent** - Content wrapper for item children
* **TreeItemLabel** - Primary text label for the item
* **TreeItemDescription** - Optional secondary description text
* **TreeItemPrefixIcon** - Optional icon displayed before the label
* **TreeItemActions** - Action buttons displayed on hover/focus
See individual component pages for detailed documentation.
## Related [#related]
* [TreeItem](./item.mdx) - Individual tree node component
* [TreeItemContent](./item-content.mdx) - Content wrapper component
* [TreeItemLabel](./item-label.mdx) - Label component
* [useTree](../../../hooks/use-tree.mdx) - Hook for tree state management
# BaseMap (/docs/toolkits/map-toolkit/deckgl/base-map)
## Usage [#usage]
```tsx
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { uuid } from '@accelint/core';
// Create id at module level for stability and easy sharing
const MAIN_MAP_ID = uuid();
export function MapView() {
return <BaseMap className="w-full h-full" id={MAIN_MAP_ID} />;
}
```
## Reference [#reference]
```typescript
interface BaseMapProps extends Omit<DeckglProps, 'onLoad'> {
// Required
id: UniqueId;
// Layout
className?: string;
// Map configuration
defaultView?: '2D' | '2.5D' | '3D';
styleUrl?: string;
initialViewState?: Partial<ViewState>;
mapLibreOptions?: MapLibreOptions;
// Interaction
enableControlEvents?: boolean;
boxZoom?: boolean;
enableRbz?: boolean;
rbzOptions?: RbzOptions;
// Event handlers
onClick?: (info: PickingInfo, event: MjolnirGestureEvent) => void;
onHover?: (info: PickingInfo, event: MjolnirPointerEvent) => void;
onDragStart?: (info: PickingInfo, event: MjolnirGestureEvent) => void;
onDrag?: (info: PickingInfo, event: MjolnirGestureEvent) => void;
onDragEnd?: (info: PickingInfo, event: MjolnirGestureEvent) => void;
onViewStateChange?: (params: ViewStateChangeParameters) => void;
onLoad?: () => void;
// All other Deck.gl props (controller, parameters, layers, etc.)
}
```
### Props [#props]
| Prop | Type | Default | Required |
| --------------------- | ------------------------ | ----------------------------- | -------- |
| `id` | `UniqueId` | - | **Yes** |
| `className` | `string` | - | No |
| `children` | `React.ReactNode` | - | No |
| `defaultView` | `'2D' \| '2.5D' \| '3D'` | `'2D'` | No |
| `styleUrl` | `string` | Dark Matter style | No |
| `initialViewState` | `Partial<ViewState>` | `{ zoom: 2, lat: 0, lon: 0 }` | No |
| `enableControlEvents` | `boolean` | `true` | No |
| `boxZoom` | `boolean` | `true` (unless RBZ enabled) | No |
| `enableRbz` | `boolean` | `false` | No |
| `rbzOptions` | `RbzOptions` | - | No |
| `onClick` | `(info, event) => void` | - | No |
| `onHover` | `(info, event) => void` | - | No |
| `onDragStart` | `(info, event) => void` | - | No |
| `onDrag` | `(info, event) => void` | - | No |
| `onDragEnd` | `(info, event) => void` | - | No |
| `onViewStateChange` | `(params) => void` | - | No |
| `onLoad` | `() => void` | - | No |
| `mapLibreOptions` | `MapLibreOptions` | - | No |
#### `id` [#id]
**Required.** Unique identifier for this map instance. Used to isolate map mode state between multiple map instances (e.g., main map vs minimap).
Must be a UUID generated using `uuid()` from `@accelint/core`. Should be a module-level constant for stability and easy sharing with `useMapMode()`.
#### `defaultView` [#defaultview]
Initial view mode for the map:
* `'2D'` - Flat map with no pitch (default)
* `'2.5D'` - Slight pitch for depth perception
* `'3D'` - Full 3D navigation with pitch and rotation
#### `styleUrl` [#styleurl]
MapLibre style URL for base map tiles. Defaults to Carto's Dark Matter style.
Common options:
* `'https://tiles.basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json'` (default)
* `'https://tiles.basemaps.cartocdn.com/gl/positron-gl-style/style.json'` (light)
* Custom Mapbox or MapLibre style URLs
#### `enableRbz` & `rbzOptions` [#enablerbz--rbzoptions]
Enable rubber band zoom (Shift + drag to select area for zoom). Automatically disables `boxZoom` when enabled.
**Important:** These options are read once on map load. To change dynamically, update the map's `key` prop to force a remount.
```typescript
type RbzOptions = {
fillColor?: string;
strokeColor?: string;
strokeWidth?: number;
shouldActivate?: () => boolean;
};
```
#### `mapLibreOptions` [#maplibreoptions]
Additional MapLibre `MapOptions` forwarded to the underlying map (e.g., `transformRequest`, `maxBounds`, `minZoom`, `maxZoom`).
Keys BaseMap manages internally are stripped:
* Camera/view state: `center`, `zoom`, `pitch`, `bearing`, `projection`, `bounds`, `fitBoundsOptions`
* Controller gestures: `doubleClickZoom`, `dragRotate`, `pitchWithRotate`, `rollEnabled`, `boxZoom`
* WebGL context: `canvasContextAttributes`
* Already exposed props: `style`, `container`, `maxPitch`
#### `onLoad` [#onload]
Fires once when the MapLibre map has loaded, after BaseMap applies the projection and finishes its own load work. Typed `() => void`; it receives no arguments.
BaseMap runs it from MapLibre's `load` event, not deck's `onLoad` prop. It is not forwarded to the deck overlay: deck may not be initialized yet when it fires, so do not call deck viewport methods from it. (An `onLoad` passed through the overlay could overwrite the overlay's own load wrapper and freeze deck's picking viewport at the initial frame.)
#### `onDragStart`, `onDrag` & `onDragEnd` [#ondragstart-ondrag--ondragend]
Standard Deck.gl drag handlers, called first with the full `PickingInfo` and gesture event. After each handler runs, BaseMap emits the matching `map:dragStart` / `map:drag` / `map:dragEnd` bus event for plain drags; see [Drag events](#drag-events).
### Map Mode Integration [#map-mode-integration]
BaseMap automatically creates a `MapProvider` internally, setting up map mode state management for this instance.
**Children vs Siblings:**
* **Children**: Only Deck.gl layer components can be children. They use `useMapMode()` without parameters (context-based).
* **Siblings**: UI components (buttons, toolbars) must be siblings and pass `id` to `useMapMode(id)`.
```tsx
// ✅ Correct: Deck.gl layer as child
<BaseMap id={mapId}>
<ScatterplotLayer {...props} />
</BaseMap>
// ✅ Correct: UI as sibling
<>
<Toolbar mapId={mapId} />
<BaseMap id={mapId} />
</>
// ❌ Wrong: UI as child
<BaseMap id={mapId}>
<Toolbar /> {/* Won't render - not a Deck.gl layer */}
</BaseMap>
```
### Event Bus [#event-bus]
Click, hover, viewport, and drag events are emitted through the event bus with `id` included in the payload, allowing multiple map instances to coexist without interference.
```typescript
// Events
MapEvents.click // MapClickEvent
MapEvents.hover // MapHoverEvent
MapEvents.viewport // MapViewportEvent
MapEvents.dragStart // MapDragStartEvent
MapEvents.drag // MapDragEvent
MapEvents.dragEnd // MapDragEndEvent
// Control events
MapEvents.enablePan
MapEvents.disablePan
MapEvents.enableZoom
MapEvents.disableZoom
```
#### Drag events [#drag-events]
`map:dragStart` and `map:drag` carry a `MapDragPayload`; `map:dragEnd` carries a `MapDragEndPayload`. The modifier flags let subscribers decide whether to claim a gesture (the [Measurement Layer](./measurement-layer.mdx)'s `useMeasurement` hook is built on these events).
```typescript
type MapDragPayload = {
id: UniqueId;
coordinate: [number, number]; // Unprojected [longitude, latitude] at the drag position
shiftKey: boolean;
ctrlKey: boolean;
altKey: boolean;
};
type MapDragEndPayload = Omit<MapDragPayload, 'coordinate'> & {
coordinate: [number, number] | null; // null when the release position is off the globe
};
```
* `map:dragStart` and `map:drag` fire after the corresponding `onDragStart` / `onDrag` prop, and only when the pointer position unprojects to finite map coordinates. Drags that start or move off the globe are skipped, so `coordinate` is always a finite tuple.
* `map:dragEnd` is always emitted for a plain drag, so subscribers that claimed the gesture can always release it. Its `coordinate` is `null` when the release position does not unproject to finite coordinates (for example, released off the globe in 3D view); check for `null` before using it.
* Tilt gestures (right-drag, or Ctrl + left-drag) rotate and pitch the camera and emit none of the three drag events. `ctrlKey` is therefore only `true` for other button combinations.
The payload types and their `Payload` wrappers (`MapDragPayload`, `MapDragEndPayload`, `MapDragStartEvent`, `MapDragEvent`, `MapDragEndEvent`) are exported from `@accelint/map-toolkit/deckgl` alongside the other `Map*` event types.
#### Control events [#control-events]
BaseMap listens for control events when `enableControlEvents` is `true` and applies them to the MapLibre map for the `id` in the payload:
* `map:disablePan` disables MapLibre's `dragPan` handler; `map:enablePan` re-enables it.
* `map:disableZoom` turns off scroll zoom and native box zoom and, when `enableRbz` is set, stops the rubber band zoom handler listening for Shift.
* `map:enableZoom` restores only what BaseMap configured: scroll zoom always, native box zoom only when the `boxZoom` prop resolves to `true` (it is `false` while `enableRbz` is set), and RBZ listening only if `map:disableZoom` stopped it. Double-click zoom is never touched; BaseMap locks it off.
BaseMap passes its resolved `boxZoom` to the internal `MapControls` component, which accepts an optional `boxZoom` prop (default `true`) for this purpose.
### Inherited Props [#inherited-props]
BaseMap inherits all props from Deck.gl's `DeckglProps`, including:
* `controller` - Enable/disable map controls
* `interleaved` - Interleaved rendering with MapLibre
* `parameters` - WebGL parameters
* `widgets` - Deck.gl widgets
* `useDevicePixels` - High-DPI rendering
* `pickingRadius` - Picking tolerance in pixels
See [Deck.gl Documentation](https://deck.gl/docs/api-reference/core/deck) for full API.
## Examples [#examples]
### Example: Basic map with id [#example-basic-map-with-id]
```tsx
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { uuid } from '@accelint/core';
// Module-level constant for stability
const MAIN_MAP_ID = uuid();
export function SimpleMap() {
return (
<div className="w-full h-screen">
<BaseMap id={MAIN_MAP_ID} className="w-full h-full" />
</div>
);
}
```
### Example: With event handlers and mode management [#example-with-event-handlers-and-mode-management]
```tsx
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { useMapMode } from '@accelint/map-toolkit/map-mode';
import { uuid } from '@accelint/core';
import type { PickingInfo } from '@deck.gl/core';
import type { MjolnirGestureEvent } from 'mjolnir.js';
const MAIN_MAP_ID = uuid();
function Toolbar() {
const { mode, requestModeChange } = useMapMode(MAIN_MAP_ID);
return (
<div className="absolute top-4 left-4 z-10">
<button onClick={() => requestModeChange('default', 'toolbar')}>
Navigate
</button>
<button onClick={() => requestModeChange('drawing', 'toolbar')}>
Draw
</button>
<div>Current mode: {mode}</div>
</div>
);
}
export function InteractiveMap() {
const handleClick = (info: PickingInfo, event: MjolnirGestureEvent) => {
if (info.object) {
console.log('Clicked:', info.object);
}
};
const handleHover = (info: PickingInfo) => {
console.log('Hovering:', info.coordinate);
};
return (
<div className="relative w-full h-screen">
<Toolbar />
<BaseMap
id={MAIN_MAP_ID}
className="w-full h-full"
onClick={handleClick}
onHover={handleHover}
/>
</div>
);
}
```
### Example: With custom initial view [#example-with-custom-initial-view]
```tsx
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { uuid } from '@accelint/core';
const MAP_ID = uuid();
export function CenteredMap() {
return (
<BaseMap
id={MAP_ID}
className="w-full h-full"
defaultView="2.5D"
initialViewState={{
latitude: 37.7749,
longitude: -122.4194,
zoom: 12,
}}
/>
);
}
```
### Example: With Deck.gl layers [#example-with-deckgl-layers]
```tsx
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { ScatterplotLayer } from '@deck.gl/layers';
import { uuid } from '@accelint/core';
const MAP_ID = uuid();
const data = [
{ position: [-122.4, 37.8], name: 'San Francisco' },
{ position: [-74.0, 40.7], name: 'New York' },
];
export function MapWithLayers() {
return (
<BaseMap id={MAP_ID} className="w-full h-full">
<ScatterplotLayer
id="cities"
data={data}
getPosition={(d) => d.position}
getRadius={10000}
getFillColor={[255, 0, 0]}
/>
</BaseMap>
);
}
```
### Example: Listening to viewport changes [#example-listening-to-viewport-changes]
```tsx
import { useOn } from '@accelint/bus/react';
import { MapEvents } from '@accelint/map-toolkit/deckgl';
import type { MapViewportEvent } from '@accelint/map-toolkit/deckgl';
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { uuid } from '@accelint/core';
const MAP_ID = uuid();
function ViewportLogger() {
useOn<MapViewportEvent>(MapEvents.viewport, (event) => {
if (event.payload.id === MAP_ID) {
console.log('Viewport:', {
zoom: event.payload.zoom,
bounds: event.payload.bounds,
center: [event.payload.latitude, event.payload.longitude],
});
}
});
return null;
}
export function TrackedMap() {
return (
<>
<ViewportLogger />
<BaseMap id={MAP_ID} className="w-full h-full" />
</>
);
}
```
### Example: Listening to drag events [#example-listening-to-drag-events]
```tsx
import { useOn } from '@accelint/bus/react';
import { BaseMap, MapEvents } from '@accelint/map-toolkit/deckgl';
import type { MapDragEndEvent, MapDragStartEvent } from '@accelint/map-toolkit/deckgl';
import { uuid } from '@accelint/core';
const MAP_ID = uuid();
function DragLogger() {
useOn<MapDragStartEvent>(MapEvents.dragStart, (event) => {
if (event.payload.id === MAP_ID && event.payload.altKey) {
console.log('Alt+drag started at', event.payload.coordinate);
}
});
useOn<MapDragEndEvent>(MapEvents.dragEnd, (event) => {
if (event.payload.id !== MAP_ID || event.payload.coordinate === null) {
return; // other map, or released off the globe
}
const [longitude, latitude] = event.payload.coordinate;
console.log('Drag ended at', longitude, latitude);
});
return null;
}
export function DragTrackedMap() {
return (
<>
<DragLogger />
<BaseMap id={MAP_ID} className="w-full h-full" />
</>
);
}
```
### Example: Running setup once the map has loaded [#example-running-setup-once-the-map-has-loaded]
```tsx
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { uuid } from '@accelint/core';
const MAP_ID = uuid();
export function LoadedMap() {
return (
<BaseMap
id={MAP_ID}
className="w-full h-full"
onLoad={() => {
console.log('MapLibre loaded; projection applied');
}}
/>
);
}
```
> **Good to know:** `onLoad` fires from MapLibre's `load` event. Deck may not be initialized yet at that point, so do not call deck viewport methods from it.
### Example: Multiple map instances [#example-multiple-map-instances]
```tsx
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { uuid } from '@accelint/core';
const MAIN_MAP_ID = uuid();
const MINI_MAP_ID = uuid();
export function DualMapView() {
return (
<div className="flex h-screen">
<div className="flex-1">
<BaseMap id={MAIN_MAP_ID} className="w-full h-full" />
</div>
<div className="w-64">
<BaseMap
id={MINI_MAP_ID}
className="w-full h-full"
initialViewState={{ zoom: 0 }}
/>
</div>
</div>
);
}
```
### Example: With rubber band zoom [#example-with-rubber-band-zoom]
```tsx
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { uuid } from '@accelint/core';
const MAP_ID = uuid();
export function RbzMap() {
return (
<BaseMap
id={MAP_ID}
className="w-full h-full"
enableRbz={true}
rbzOptions={{
fillColor: 'rgba(0, 120, 255, 0.1)',
strokeColor: '#0078ff',
strokeWidth: 2,
}}
/>
);
}
```
> **Good to know:** When `enableRbz` is true, `boxZoom` is automatically disabled to prevent gesture conflicts.
### Example: Custom MapLibre options [#example-custom-maplibre-options]
```tsx
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { uuid } from '@accelint/core';
const MAP_ID = uuid();
export function RestrictedMap() {
return (
<BaseMap
id={MAP_ID}
className="w-full h-full"
mapLibreOptions={{
maxBounds: [[-130, 20], [-60, 55]], // Restrict to US
minZoom: 4,
maxZoom: 18,
transformRequest: (url, resourceType) => {
// Add auth headers for custom tile server
if (url.startsWith('https://tiles.example.com/')) {
return {
url,
headers: { Authorization: `Bearer ${token}` },
};
}
return { url };
},
}}
/>
);
}
```
## Related [#related]
* [useMapMode](../map-mode/index.mdx) - Access map mode state within or outside BaseMap
* [useMapCursor](../map-cursor/index.mdx) - Coordinate cursor styles across features
* [useMapCamera](../camera/index.mdx) - Control camera position and view state
* [Measurement Layer](./measurement-layer.mdx) - Drag-to-measure tool built on the `map:drag*` events
* [toLonLat](../coordinates.mdx) - Coordinate normalization applied to drag payloads
* [@accelint/bus](../../../packages/bus/index.mdx) - Event bus for map event coordination
# DeckGL (/docs/toolkits/map-toolkit/deckgl)
## Installation [#installation]
```bash
pnpm add @accelint/map-toolkit
```
## Usage [#usage]
```typescript
// Import base map
import { BaseMap } from '@accelint/map-toolkit/deckgl';
// Import layers
import { DisplayShapeLayer, SymbolLayer } from '@accelint/map-toolkit/deckgl';
// Import extensions
import { CoffinCornerExtension } from '@accelint/map-toolkit/deckgl';
// Import widgets
import { HtmlOverlayWidget, useHtmlOverlay } from '@accelint/map-toolkit/deckgl';
// Import utilities
import { createSavedViewport } from '@accelint/map-toolkit/deckgl';
```
## Available Exports [#available-exports]
### Components [#components]
| Export | Description |
| ------------------------- | ----------------------------------------------------- |
| [BaseMap](./base-map.mdx) | Deck.gl-powered base map with MapLibre GL integration |
### Layers [#layers]
| Export | Description |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| [DisplayShapeLayer](./shapes/display-shape-layer.mdx) | Display shapes (circles, ellipses, polygons) with custom styling |
| [Measurement Layer](./measurement-layer.mdx) | Drag to measure great-circle distance and bearing (imported from `@accelint/map-toolkit/deckgl/measurement-layer`, not the barrel) |
| [SymbolLayer](./symbol-layer.mdx) | Display military symbols using MIL-STD-2525 iconography |
### Extensions [#extensions]
| Export Path | Description |
| ---------------------------------------------------------- | ----------------------------------------------------------- |
| [extensions](./extensions/index.mdx) | Deck.gl layer extensions |
| [extensions/coffin-corner](./extensions/coffin-corner.mdx) | Extension for handling entity positioning at map boundaries |
### Grid Layers [#grid-layers]
| Export Path | Description |
| ------------------------------------------ | ------------------------------------------------ |
| [grid-layers](./grid-layers/index.mdx) | Military grid reference system layers |
| [grid-layers/gars](./grid-layers/gars.mdx) | Global Area Reference System (GARS) grid layer |
| [grid-layers/mgrs](./grid-layers/mgrs.mdx) | Military Grid Reference System (MGRS) grid layer |
### Shapes [#shapes]
| Export Path | Description |
| -------------------------------------------------------------- | -------------------------------- |
| [shapes](./shapes/index.mdx) | Shape drawing and editing system |
| [shapes/display-shape-layer](./shapes/display-shape-layer.mdx) | Display shapes with styling |
| [shapes/draw-shape-layer](./shapes/draw-shape-layer.mdx) | Interactive shape drawing |
| [shapes/edit-shape-layer](./shapes/edit-shape-layer.mdx) | Edit existing shapes |
### Widgets [#widgets]
| Export Path | Description |
| -------------------------------------------------- | -------------------------------------------------- |
| [widgets](./widgets/index.mdx) | HTML overlay widgets |
| [widgets/html-overlay](./widgets/html-overlay.mdx) | Position HTML elements relative to map coordinates |
### Utilities [#utilities]
| Export | Description |
| ---------------------------------------- | ------------------------------------------- |
| [saved-viewports](./saved-viewports.mdx) | Save and restore map viewports with hotkeys |
### Events [#events]
| Export | Description |
| -------------------- | -------------------------------------- |
| `MapEvents` | Event constants for map interactions |
| `MapEventsNamespace` | Type-safe event namespace |
| `ShapeEvents` | Event constants for shape interactions |
### Constants [#constants]
| Export | Description |
| -------------------------- | ----------------------------------- |
| `DARK_BASE_MAP_STYLE` | Dark mode MapLibre style URL |
| `LIGHT_BASE_MAP_STYLE` | Light mode MapLibre style URL |
| `PARAMETERS` | Default Deck.gl parameters |
| `DASH_ARRAYS` | Predefined dash patterns for lines |
| `DEFAULT_COLORS` | Default color palette for shapes |
| `DEFAULT_STYLE_PROPERTIES` | Default style properties for shapes |
| `LINE_PATTERNS` | Line pattern constants |
| `LINE_WIDTHS` | Standard line width values |
| `SHAPE_LAYER_IDS` | Layer ID constants for shape layers |
## Quick Start [#quick-start]
### Basic Map with Symbol Layer [#basic-map-with-symbol-layer]
```tsx
import { BaseMap, SymbolLayer } from '@accelint/map-toolkit/deckgl';
import { uuid } from '@accelint/core';
const MAP_ID = uuid();
const data = [
{
id: '1',
sidc: 'SFGPUCI----E---',
position: [-122.4, 37.8],
size: 32,
},
];
export function MapWithSymbols() {
return (
<BaseMap id={MAP_ID} className="w-full h-full">
<SymbolLayer id="symbols" data={data} />
</BaseMap>
);
}
```
### Drawing Shapes [#drawing-shapes]
```tsx
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { DrawShapeLayer } from '@accelint/map-toolkit/deckgl/shapes';
import { useDrawShape } from '@accelint/map-toolkit/deckgl/shapes/draw-shape-layer';
import { uuid } from '@accelint/core';
const MAP_ID = uuid();
export function DrawingMap() {
const { mode, setMode, shapes } = useDrawShape(MAP_ID);
return (
<div className="relative w-full h-full">
<BaseMap id={MAP_ID} className="w-full h-full">
<DrawShapeLayer id="drawing" mode={mode} />
</BaseMap>
<div className="absolute top-4 right-4 flex gap-2">
<button onClick={() => setMode('drawPolygon')}>Draw Polygon</button>
<button onClick={() => setMode('drawCircle')}>Draw Circle</button>
<button onClick={() => setMode('select')}>Select</button>
</div>
</div>
);
}
```
### HTML Overlay [#html-overlay]
```tsx
import { BaseMap, HtmlOverlayWidget, HtmlOverlayItem } from '@accelint/map-toolkit/deckgl';
import { uuid } from '@accelint/core';
const MAP_ID = uuid();
const markers = [
{ id: '1', position: [-122.4, 37.8], label: 'San Francisco' },
{ id: '2', position: [-118.2, 34.0], label: 'Los Angeles' },
];
export function MapWithOverlay() {
return (
<BaseMap id={MAP_ID} className="w-full h-full">
<HtmlOverlayWidget>
{markers.map(marker => (
<HtmlOverlayItem
key={marker.id}
coordinates={marker.position}
>
<div className="bg-white px-2 py-1 rounded shadow">
{marker.label}
</div>
</HtmlOverlayItem>
))}
</HtmlOverlayWidget>
</BaseMap>
);
}
```
## Related [#related]
* [camera](../camera.mdx) - Camera state management
* [map-mode](../map-mode.mdx) - Map interaction mode management
* [viewport](../viewport.mdx) - Viewport state management
* [Deck.gl Documentation](https://deck.gl) - Official Deck.gl docs
# Measurement Layer (/docs/toolkits/map-toolkit/deckgl/measurement-layer)
## Usage [#usage]
```tsx
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { MeasurementTool } from '@accelint/map-toolkit/deckgl/measurement-layer';
import { uuid } from '@accelint/core';
const MAP_ID = uuid();
export function MapWithMeasurement() {
return (
<BaseMap id={MAP_ID}>
<MeasurementTool requiresModifier="alt" />
</BaseMap>
);
}
```
Alt+drag draws a dashed great-circle line between the drag origin and the pointer, with circular endpoints and a readout at the midpoint formatted as `"42.3 km / 22.8 NM | BRG: 321°"`. Plain drag keeps panning the map.
The module is not part of the `@accelint/map-toolkit/deckgl` barrel. Import everything from `@accelint/map-toolkit/deckgl/measurement-layer`; register the `<measurementLayer />` fiber element with a one-time side-effect import of `@accelint/map-toolkit/deckgl/measurement-layer/fiber`.
```tsx
import {
MeasurementLayer,
MeasurementTool,
measurementStore,
useMeasurement,
MeasurementEvents,
MeasurementEventsNamespace,
MEASUREMENT_LAYER_ID,
MEASUREMENT_MODE,
type MeasurementLayerProps,
type MeasurementToolProps,
type RequiresModifier,
type MeasurementState,
type MeasurementActions,
type UseMeasurementReturn,
type MeasurementPayload,
type MeasurementStartEvent,
type MeasurementUpdateEvent,
type MeasurementCompletePayload,
type MeasurementCompleteEvent,
type MeasurementClearPayload,
type MeasurementClearEvent,
type MeasurementEventType,
} from '@accelint/map-toolkit/deckgl/measurement-layer';
```
`@accelint/geo` and `@accelint/formatters` are required peer dependencies of `@accelint/map-toolkit`; install them alongside the toolkit.
```bash
pnpm add @accelint/map-toolkit @accelint/geo @accelint/formatters
```
## MeasurementTool [#measurementtool]
Convenience component that wires `useMeasurement` and `MeasurementLayer` together. Renders the layer only while a drag is active and both points are set, so the tool has no visual overhead when idle. Render it as a child of `BaseMap`; the map ID comes from context.
```tsx
import { MeasurementTool } from '@accelint/map-toolkit/deckgl/measurement-layer';
<BaseMap id={MAP_ID}>
<MeasurementTool />
</BaseMap>
```
### Reference [#reference]
```typescript
type MeasurementToolProps = Pick<
MeasurementLayerProps,
'showLabel' | 'units' | 'getLabel' | 'lineColor' | 'endpointColor'
> & {
mapId?: UniqueId;
requiresModifier?: RequiresModifier;
};
function MeasurementTool(props: MeasurementToolProps): ReactNode
```
### Props [#props]
| Prop | Type | Default | Required |
| ------------------ | ----------------------------------- | --------------------------------- | -------- |
| `mapId` | `UniqueId` | `MapContext` | No |
| `requiresModifier` | `RequiresModifier` | `undefined` | No |
| `showLabel` | `boolean` | `true` | No |
| `units` | `DistanceUnit \| DistanceUnit[]` | `['kilometers', 'nauticalmiles']` | No |
| `getLabel` | `(pointA, pointB, units) => string` | - | No |
| `lineColor` | `Color` | `[255, 255, 255, 200]` | No |
| `endpointColor` | `Color` | `[255, 255, 255, 255]` | No |
#### `mapId` [#mapid]
Map instance ID. Falls back to the surrounding `MapProvider` (the `BaseMap` the tool is rendered inside). Required when the tool is rendered outside `BaseMap` children.
#### `requiresModifier` [#requiresmodifier]
Modifier key that must be held for a drag to count as a measurement. Without it, every drag measures and the map no longer pans by dragging. See [RequiresModifier](#requiresmodifier).
The remaining props are forwarded to `MeasurementLayer` unchanged. The rendered layer uses the fixed ID `measurement-tool-layer`.
## useMeasurement [#usemeasurement]
Hook that exposes the per-map measurement state and the `start` / `clear` actions. Use it directly when you need the numbers outside the map (a sidebar readout) or want full control over the layer props.
```tsx
import { useMeasurement } from '@accelint/map-toolkit/deckgl/measurement-layer';
import { formatBearing, formatDistance } from '@accelint/formatters/bearing';
function MeasurementReadout() {
const { isMeasuring, distanceMeters, bearingDeg, clear } = useMeasurement(MAP_ID);
if (!isMeasuring) {
return null;
}
return (
<p>
{formatDistance(distanceMeters, ['kilometers', 'nauticalmiles'])} · {formatBearing(bearingDeg)}
<button onClick={clear}>Clear</button>
</p>
);
}
```
### Reference [#reference-1]
```typescript
function useMeasurement(
mapId?: UniqueId,
requiresModifier?: RequiresModifier,
): UseMeasurementReturn
type UseMeasurementReturn = {
isMeasuring: boolean;
pointA: [number, number] | null;
pointB: [number, number] | null;
distanceMeters: number;
bearingDeg: number;
start: (pointA: [number, number]) => void;
clear: () => void;
};
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mapId` | `UniqueId` | Map instance ID. Falls back to the surrounding `MapProvider`; required outside of `BaseMap` children. |
| `requiresModifier` | `RequiresModifier` | Modifier key a drag must hold to count as a measurement. Stored per map: pass it from the hook that configures the tool; omit it to inherit the map's current value. |
Throws if no `mapId` is given and the hook is used outside of a `MapProvider`.
### Returns [#returns]
| Property | Type | Description |
| ---------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isMeasuring` | `boolean` | Whether a measurement drag is in progress. |
| `pointA` | `[number, number] \| null` | Origin coordinate, or `null` when idle. |
| `pointB` | `[number, number] \| null` | Destination coordinate, or `null` before the first drag move. |
| `distanceMeters` | `number` | Great-circle distance in meters, or `0` until both points are finite. Format with `formatDistance(distanceMeters, units)` from `@accelint/formatters/bearing`. |
| `bearingDeg` | `number` | Initial bearing from `pointA` to `pointB` in degrees (0–360, true north), or `0` until both points are finite. Format with `formatBearing(bearingDeg)`. |
| `start` | `(pointA: [number, number]) => void` | Imperatively start a measurement from a coordinate (a context-menu "Measure from here", for example). Restarts an active measurement: resets `pointB`, emits `measurement:start`, suppresses pan, and claims the `measure` map mode. No-op while another tool owns the map mode. |
| `clear` | `() => void` | Clears the measurement, resets to idle, emits `measurement:clear`, and restores pan and the map mode if a drag was in progress. |
### Subscription lifecycle [#subscription-lifecycle]
The `map:dragStart` / `map:drag` / `map:dragEnd` subscription lives in `measurementStore`, once per map. The first hook to mount for a map starts it and the last to unmount tears it down; if that last unmount happens mid-drag, the measurement is finished so map pan is restored. Lifecycle events therefore fire once per map no matter how many hooks are mounted, so an on-map overlay and a sidebar readout can share one measurement.
`requiresModifier` is per-map state owned by the hook that passes it. Readout hooks omit it and inherit the map's value; the configuring hook clears it when it unmounts, returning the map to measuring on every drag.
```tsx
// Configures the map: Alt+drag measures, plain drag pans.
<MeasurementTool requiresModifier="alt" />
// Reads the same measurement; inherits 'alt' without passing it.
const { distanceMeters } = useMeasurement(mapId);
```
With `'shift'`, the hook emits `map:disableZoom` while Shift is held and `map:enableZoom` on release, so Shift+drag zoom is unavailable on a map that measures with Shift.
## MeasurementLayer [#measurementlayer]
Controlled deck.gl `CompositeLayer` that renders a bearing-range measurement between two points. It is a pure function of its props: pair it with `useMeasurement` for interactive measurement, or construct it directly for static display.
```tsx
import { MeasurementLayer } from '@accelint/map-toolkit/deckgl/measurement-layer';
new MeasurementLayer({
id: 'measurement',
pointA: [-97.74, 30.27],
pointB: [-90.07, 29.95],
units: 'nauticalmiles',
});
```
Composes three sub-layers:
* `PathLayer` - dashed great-circle line from `pointA` to `pointB`
* `ScatterplotLayer` - circular markers at `pointA` and `pointB`
* `TextLayer` - measurement readout at the middle vertex of the line (when `showLabel` is `true`)
The line is sampled along the great circle with `greatCirclePoints` from `@accelint/geo/geodesy`, so long segments curve the way the measured distance does instead of following a straight Mercator chord. Vertex longitudes are unwrapped relative to the previous vertex, so a segment that crosses the antimeridian draws the short way as one continuous line (179° to 181°) with the label on it.
### Reference [#reference-2]
```typescript
class MeasurementLayer extends CompositeLayer<MeasurementLayerProps>
type MeasurementLayerProps = CompositeLayerProps & {
pointA: [number, number];
pointB: [number, number];
showLabel?: boolean;
getLabel?: (
pointA: [number, number],
pointB: [number, number],
units: DistanceUnit | DistanceUnit[],
) => string;
units?: DistanceUnit | DistanceUnit[];
lineColor?: Color;
endpointColor?: Color;
};
```
### Props [#props-1]
| Prop | Type | Default | Required |
| --------------- | ----------------------------------- | --------------------------------- | -------- |
| `id` | `string` | - | **Yes** |
| `pointA` | `[number, number]` | - | **Yes** |
| `pointB` | `[number, number]` | - | **Yes** |
| `showLabel` | `boolean` | `true` | No |
| `getLabel` | `(pointA, pointB, units) => string` | - | No |
| `units` | `DistanceUnit \| DistanceUnit[]` | `['kilometers', 'nauticalmiles']` | No |
| `lineColor` | `Color` | `[255, 255, 255, 200]` | No |
| `endpointColor` | `Color` | `[255, 255, 255, 255]` | No |
#### `pointA` and `pointB` [#pointa-and-pointb]
Origin and destination as `[longitude, latitude]`. The layer renders nothing when either point is not a finite two-element tuple, rather than throwing.
#### `units` [#units]
Distance unit(s) for the readout. A single unit produces `"42.3 km"`; two produce `"42.3 km / 22.8 NM"`. An array with zero or more than two entries falls back to the default pair, so a bad prop never throws inside `renderLayers`.
#### `getLabel` [#getlabel]
Replaces the default `"42.3 km / 22.8 NM | BRG: 321°"` readout. Called as `getLabel(pointA, pointB, units)` with the resolved `units` (the default pair when the prop is omitted or invalid) and returns the string rendered at the middle vertex of the geodesic line. Set `showLabel={false}` to hide the on-canvas label entirely.
### Fiber usage [#fiber-usage]
Import the fiber module once to register the `<measurementLayer />` intrinsic element for `@deckgl-fiber-renderer`. It accepts `MeasurementLayerProps`.
```tsx
import '@accelint/map-toolkit/deckgl/measurement-layer/fiber';
<measurementLayer id="measurement" pointA={[-97, 32]} pointB={[-90, 29]} showLabel />
```
## measurementStore [#measurementstore]
Per-map store behind `useMeasurement`, built with the shared `createMapStore`. Use `measurementStore.get(mapId)` and `measurementStore.actions(mapId)` for non-React access; reach for the hook in components.
```typescript
import { measurementStore } from '@accelint/map-toolkit/deckgl/measurement-layer';
const { isMeasuring, pointA, pointB } = measurementStore.get(MAP_ID);
measurementStore.actions(MAP_ID).start([-97.74, 30.27]);
```
### Reference [#reference-3]
```typescript
type MeasurementState = {
pointA: [number, number] | null;
pointB: [number, number] | null;
isMeasuring: boolean;
requiresModifier: RequiresModifier | undefined;
};
type MeasurementActions = {
start: (pointA: [number, number]) => void;
updateEnd: (pointB: [number, number]) => void;
complete: () => void;
clear: () => void;
setRequiresModifier: (value: RequiresModifier | undefined) => void;
};
```
### Actions [#actions]
| Action | Description |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `start(pointA)` | Begins (or restarts) a measurement. Resets `pointB`, emits `measurement:start` and `map:disablePan`, and claims the `measure` map mode. No-op while another tool owns the map mode. |
| `updateEnd(pointB)` | Sets the destination during a drag and emits `measurement:update`. No-op when not measuring. |
| `complete()` | Marks the measurement complete: emits `measurement:complete` and `map:enablePan`, and releases the map mode. A measurement with no `pointB` is cleared instead. No-op when not measuring. |
| `clear()` | Resets all state and emits `measurement:clear`; emits `map:enablePan` and releases the map mode if a drag was in progress. |
| `setRequiresModifier(value)` | Sets the per-map modifier requirement checked against incoming drags, or `undefined` to measure on every drag. |
The store owns the `map:dragStart` / `map:drag` / `map:dragEnd` subscription for each map. Drags for other map IDs are ignored; a drag start that lacks the required modifier is ignored; a drag move that lacks it completes the measurement at the last captured point. `map:dragEnd` always completes, and its `coordinate` may be `null` (released off the globe), in which case the measurement completes at the last captured point.
## MeasurementEvents [#measurementevents]
Event keys for the measurement lifecycle, emitted through `@accelint/bus` once per map regardless of how many hooks are mounted. `MeasurementEventsNamespace` is the `'measurement'` prefix shared by every key.
```typescript
import { useOn } from '@accelint/bus/react';
import {
MeasurementEvents,
type MeasurementCompleteEvent,
} from '@accelint/map-toolkit/deckgl/measurement-layer';
useOn<MeasurementCompleteEvent>(MeasurementEvents.complete, (event) => {
if (event.payload.mapId === MAP_ID) {
console.log('Measured from', event.payload.pointA, 'to', event.payload.pointB);
}
});
```
### Reference [#reference-4]
| Event | Name | Payload type | Payload |
| ---------------------------- | ------------------------ | ---------------------------- | ---------------------------------------------------- |
| `MeasurementEvents.start` | `'measurement:start'` | `MeasurementPayload` | `{ mapId, pointA, pointB: null }` |
| `MeasurementEvents.update` | `'measurement:update'` | `MeasurementPayload` | `{ mapId, pointA, pointB }` |
| `MeasurementEvents.complete` | `'measurement:complete'` | `MeasurementCompletePayload` | `{ mapId, pointA, pointB }` with a non-null `pointB` |
| `MeasurementEvents.clear` | `'measurement:clear'` | `MeasurementClearPayload` | `{ mapId }` |
```typescript
type MeasurementPayload = {
mapId: UniqueId;
pointA: [number, number];
pointB: [number, number] | null;
};
type MeasurementCompletePayload = {
mapId: UniqueId;
pointA: [number, number];
pointB: [number, number];
};
type MeasurementClearPayload = {
mapId: UniqueId;
};
type MeasurementEventType =
| MeasurementStartEvent
| MeasurementUpdateEvent
| MeasurementCompleteEvent
| MeasurementClearEvent;
```
### Lifecycle [#lifecycle]
* `measurement:start` fires on every drag start and on every `start(pointA)` call. Calling `start` while a measurement is active restarts it: `pointB` resets and a fresh `measurement:start` is emitted.
* `measurement:update` fires on every drag move, including moves that repeat the previous coordinate.
* `measurement:complete` fires when the drag ends with a captured `pointB`, so `MeasurementCompletePayload.pointB` is never `null`. Completing without a `pointB` (a press-and-release with no move) behaves like `clear()` and emits `measurement:clear` instead.
* `measurement:clear` fires from `clear()` and restores map pan if a drag was in progress.
## RequiresModifier [#requiresmodifier-1]
Modifier key that must be held for a drag to count as a measurement. Pass it to `useMeasurement` or `MeasurementTool` so plain drag keeps panning and only modifier + drag measures.
```typescript
import type { RequiresModifier } from '@accelint/map-toolkit/deckgl/measurement-layer';
type RequiresModifier = 'shift' | 'alt';
```
How each key interacts with `BaseMap`'s own gestures:
* `'alt'` (Option on Mac) has no competing gesture.
* `'shift'` shares the key with `BaseMap`'s Shift+drag zoom gesture (MapLibre box zoom, or rubber-band zoom when `enableRbz` is set). `useMeasurement` emits `map:disableZoom` while Shift is held and `map:enableZoom` on release, so Shift+drag zoom is unavailable on a map that measures with Shift.
* `'ctrl'` is deliberately not an option. Ctrl+drag is `BaseMap`'s rotate/tilt gesture, and tilt gestures emit no drag events, so a Ctrl-gated measurement could never activate.
Releasing the modifier mid-drag completes the measurement at the last captured point and restores map pan, so a user can let go of the key to lock in a reading before releasing the mouse.
## MEASUREMENT\_MODE [#measurement_mode]
The map mode the store holds for the length of a drag.
```typescript
import { MEASUREMENT_MODE } from '@accelint/map-toolkit/deckgl/measurement-layer';
import { useMapMode } from '@accelint/map-toolkit/map-mode';
const MEASUREMENT_MODE = 'measure';
const { mode } = useMapMode(mapId);
const isMeasuring = mode === MEASUREMENT_MODE;
```
Measurement takes part in the [map mode](../map-mode.mdx) system, the same coordination the draw and edit shape layers use:
* A drag only starts a measurement while the map is in the default mode. While a shape is being drawn or edited, drags are left to that tool and nothing is measured.
* For the length of the drag the store holds the `measure` mode as owner `measurement-layer`, so a draw or edit cannot begin mid-measurement. The store does not answer mode authorization requests; a mode requested during the drag is granted as soon as the measurement completes or is cleared.
* `start(pointA)` follows the same rule and is a no-op while another tool owns the mode.
> **Good to know:** The mode store handles requests only while something subscribes to it for the map (for example a `useMapMode(mapId)` hook). Without a subscriber the map always reports the default mode and measurement works without the exclusion.
## MEASUREMENT\_LAYER\_ID [#measurement_layer_id]
Owner identifier the measurement store registers with the map mode system when it claims `MEASUREMENT_MODE`.
```typescript
import { MEASUREMENT_LAYER_ID } from '@accelint/map-toolkit/deckgl/measurement-layer';
const MEASUREMENT_LAYER_ID = 'measurement-layer';
```
## Examples [#examples]
### Example: Hook with fiber layer and sidebar readout [#example-hook-with-fiber-layer-and-sidebar-readout]
```tsx
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { useMeasurement } from '@accelint/map-toolkit/deckgl/measurement-layer';
import '@accelint/map-toolkit/deckgl/measurement-layer/fiber';
import { uuid } from '@accelint/core';
import { formatBearing, formatDistance } from '@accelint/formatters/bearing';
const MAP_ID = uuid();
function MeasurementOverlay() {
const { isMeasuring, pointA, pointB } = useMeasurement(MAP_ID, 'alt');
if (!(isMeasuring && pointA && pointB)) {
return null;
}
return <measurementLayer id="measurement" pointA={pointA} pointB={pointB} />;
}
function MeasurementReadout() {
const { isMeasuring, distanceMeters, bearingDeg, clear } = useMeasurement(MAP_ID);
if (!isMeasuring) {
return null;
}
return (
<div className="absolute top-4 left-4">
<p>
{formatDistance(distanceMeters, ['kilometers', 'nauticalmiles'])} · {formatBearing(bearingDeg)}
</p>
<button onClick={clear}>Clear</button>
</div>
);
}
export function MapWithReadout() {
return (
<div className="relative w-full h-full">
<BaseMap id={MAP_ID} className="absolute inset-0">
<MeasurementOverlay />
</BaseMap>
<MeasurementReadout />
</div>
);
}
```
Only deck.gl layers may be children of `BaseMap`, so the readout renders as a sibling and passes `MAP_ID` explicitly. The overlay configures `'alt'`; the readout inherits it.
### Example: Static line in a non-React deck.gl app [#example-static-line-in-a-non-react-deckgl-app]
```typescript
import { Deck } from '@deck.gl/core';
import { MeasurementLayer } from '@accelint/map-toolkit/deckgl/measurement-layer';
new Deck({
initialViewState: { longitude: -97, latitude: 32, zoom: 5 },
controller: true,
layers: [
new MeasurementLayer({
id: 'measurement',
pointA: [-97.74, 30.27],
pointB: [-90.07, 29.95],
units: 'nauticalmiles',
lineColor: [255, 200, 0, 200],
endpointColor: [255, 200, 0, 255],
}),
],
});
```
### Example: Custom label [#example-custom-label]
```tsx
import { MeasurementTool } from '@accelint/map-toolkit/deckgl/measurement-layer';
import { formatBearing, formatDistance } from '@accelint/formatters/bearing';
import { bearing, distance } from '@accelint/geo/geodesy';
<MeasurementTool
getLabel={(pointA, pointB, units) =>
`${formatDistance(distance(pointA, pointB), units)} at ${formatBearing(bearing(pointA, pointB))}`
}
/>
```
### Example: Starting a measurement from a context menu [#example-starting-a-measurement-from-a-context-menu]
```tsx
import { useMeasurement } from '@accelint/map-toolkit/deckgl/measurement-layer';
function MeasureFromHere({ coordinate }: { coordinate: [number, number] }) {
const { start } = useMeasurement(MAP_ID);
return <button onClick={() => start(coordinate)}>Measure from here</button>;
}
```
`start` behaves like a drag start: it emits `measurement:start`, suppresses pan, and claims the `measure` map mode. The next `map:drag` events update `pointB` until the drag ends.
## Related [#related]
* [BaseMap](./base-map.mdx) - Emits the `map:dragStart` / `map:drag` / `map:dragEnd` events the store subscribes to and defines `MapDragPayload` / `MapDragEndPayload`
* [useMapMode](../map-mode.mdx) - Map mode coordination that measurement takes part in
* [toLonLat](../coordinates.mdx) - Coordinate normalization the layer and hook apply to `pointA` / `pointB`
* [formatDistance & formatBearing](../../../packages/formatters/bearing.mdx) - Formatters for `distanceMeters` and `bearingDeg`
* [@accelint/geo](../../../packages/geo/index.mdx) - Great-circle distance, bearing, and geodesic line vertices
* [@accelint/bus](../../../packages/bus/index.mdx) - Event bus for measurement and drag events
# Saved Viewports (/docs/toolkits/map-toolkit/deckgl/saved-viewports)
## Usage [#usage]
```tsx
import { createSavedViewport } from '@accelint/map-toolkit/deckgl/saved-viewports';
import { BaseMap } from '@accelint/map-toolkit/deckgl';
import { MapEvents } from '@accelint/map-toolkit/deckgl/base-map';
import { CameraEventTypes } from '@accelint/map-toolkit/camera';
import { Broadcast } from '@accelint/bus';
import { useOn } from '@accelint/bus/react';
import { uuid } from '@accelint/core';
import { globalBind } from '@accelint/hotkey-manager';
// Enable global hotkey handling
globalBind();
const MAP_ID = uuid();
const cameraBus = Broadcast.getInstance();
let currentViewport;
// Create the saved viewport hook
const useSavedViewportHotkey = createSavedViewport({
threshold: 1000, // Hold key for 1 second to save
getCurrentViewport: () => currentViewport,
setCurrentViewport: (newState) => {
currentViewport = { ...currentViewport, ...newState };
cameraBus.emit(CameraEventTypes.setCenter, {
id: MAP_ID,
latitude: newState.latitude,
longitude: newState.longitude,
zoom: newState.zoom,
});
},
});
export function MapView() {
// Activate saved viewport hotkeys
useSavedViewportHotkey();
// Track viewport changes
useOn(MapEvents.viewport, (event) => {
currentViewport = { ...currentViewport, ...event.payload };
});
return <BaseMap id={MAP_ID} className="w-full h-full" />;
}
```
## Reference [#reference]
### `createSavedViewport` [#createsavedviewport]
Creates a React hook that registers hotkeys for saving and restoring map viewports.
**Type Signature:**
```typescript
function createSavedViewport(
options: SavedViewportOptions
): () => void
```
**Parameters:**
* `options.getCurrentViewport` **(required)** - Function that returns the current map viewport state
* `options.setCurrentViewport` **(required)** - Function that applies a viewport state to the map
* `options.threshold` *(optional)* - Milliseconds to hold a key before saving (default: `1000`)
* `options.uniqueIdentifier` *(optional)* - Namespace for multiple map instances
* `options.getSavedViewport` *(optional)* - Custom storage retrieval function
* `options.setSavedViewport` *(optional)* - Custom storage persistence function
* `options.key` *(optional)* - Custom key combinations (default: `Digit0-9`)
* ...other `HotkeyOptions` from `@accelint/hotkey-manager`
**Returns:** React hook function that must be called within a component to activate hotkeys
**Behavior:**
* **Hold** a number key (0-9) for the threshold duration → saves current viewport to that slot
* **Tap** a number key → restores the viewport saved in that slot
* Viewports persist to `localStorage` by default (key: `saved-viewports`)
* Multiple map instances can use `uniqueIdentifier` to isolate their saved viewports
### Types [#types]
#### `SavedViewportOptions` [#savedviewportoptions]
```typescript
type SavedViewportOptions = Partial<HotkeyOptions> & {
// Required callbacks
getCurrentViewport: () => MapViewState;
setCurrentViewport: (viewport: MapViewState) => void;
// Optional configuration
uniqueIdentifier?: string;
threshold?: number;
// Optional custom storage (must provide both or neither)
getSavedViewport?: (id: KeyCombinationId, uniqueIdentifier?: string) => MapViewState;
setSavedViewport?: (id: KeyCombinationId, viewport: MapViewState, uniqueIdentifier?: string) => void;
}
```
## Examples [#examples]
### Basic Usage [#basic-usage]
```tsx
import { createSavedViewport } from '@accelint/map-toolkit/deckgl/saved-viewports';
import { useState } from 'react';
import { globalBind } from '@accelint/hotkey-manager';
globalBind();
const useSavedViewports = createSavedViewport({
getCurrentViewport: () => viewportState,
setCurrentViewport: (viewport) => setViewportState(viewport),
threshold: 1500, // Hold for 1.5 seconds to save
});
function MyMap() {
const [viewportState, setViewportState] = useState({
latitude: 37.8,
longitude: -122.4,
zoom: 10,
});
useSavedViewports();
return <BaseMap /* ... */ />;
}
```
### Multiple Map Instances [#multiple-map-instances]
```tsx
const MAP_1_ID = 'main-map';
const MAP_2_ID = 'mini-map';
const useSavedViewportsMain = createSavedViewport({
uniqueIdentifier: MAP_1_ID,
getCurrentViewport: () => mainViewport,
setCurrentViewport: setMainViewport,
});
const useSavedViewportsMini = createSavedViewport({
uniqueIdentifier: MAP_2_ID,
getCurrentViewport: () => miniViewport,
setCurrentViewport: setMiniViewport,
});
function DualMaps() {
useSavedViewportsMain();
useSavedViewportsMini();
return (
<>
<BaseMap id={MAP_1_ID} /* ... */ />
<BaseMap id={MAP_2_ID} /* ... */ />
</>
);
}
```
### Custom Storage [#custom-storage]
```tsx
import { createSavedViewport } from '@accelint/map-toolkit/deckgl/saved-viewports';
// Custom storage using IndexedDB or API
const useSavedViewports = createSavedViewport({
getCurrentViewport: () => currentViewport,
setCurrentViewport: setViewport,
getSavedViewport: async (id, namespace) => {
const data = await db.viewports.get({ id, namespace });
return data?.viewport;
},
setSavedViewport: async (id, viewport, namespace) => {
await db.viewports.put({ id, namespace, viewport });
},
});
```
### Custom Hotkeys [#custom-hotkeys]
```tsx
import { createSavedViewport } from '@accelint/map-toolkit/deckgl/saved-viewports';
import { Keycode } from '@accelint/hotkey-manager';
// Use F1-F4 instead of number keys
const useSavedViewports = createSavedViewport({
key: [
{ code: Keycode.F1 },
{ code: Keycode.F2 },
{ code: Keycode.F3 },
{ code: Keycode.F4 },
],
threshold: 800,
getCurrentViewport: () => viewport,
setCurrentViewport: setViewport,
});
```
## Integration with Camera Store [#integration-with-camera-store]
For type-safe integration with the camera store:
```tsx
import { createSavedViewport } from '@accelint/map-toolkit/deckgl/saved-viewports';
import { useCamera, CameraEvents } from '@accelint/map-toolkit/camera';
import { Broadcast } from '@accelint/bus';
const MAP_ID = 'my-map';
const cameraBus = Broadcast.getInstance();
const useSavedViewports = createSavedViewport({
getCurrentViewport: () => {
const camera = useCamera.getState().cameras[MAP_ID];
return {
latitude: camera.latitude,
longitude: camera.longitude,
zoom: camera.zoom,
pitch: camera.pitch,
bearing: camera.bearing,
};
},
setCurrentViewport: (viewport) => {
cameraBus.emit(CameraEvents.setCenter, {
id: MAP_ID,
...viewport,
});
},
});
```
## Related [#related]
* [camera](../camera.mdx) - Camera state management
* [deckgl/base-map](./base-map.mdx) - Base map component
* [@accelint/hotkey-manager](../../packages/hotkey-manager/index.mdx) - Hotkey registration system
# parseMGRS (/docs/packages/geo/coordinates/mgrs/parser)
Parses Military Grid Reference System (MGRS) coordinate strings and converts them to latitude/longitude decimal degrees with detailed validation.
## Usage [#usage]
```typescript
import { parseMGRS } from '@accelint/geo';
// Parse MGRS coordinate
const [coords, errors] = parseMGRS(null, '31U BF 12345 67890');
// coords: ['48.123456', 'N', '/', '11.234567', 'E']
// errors: []
```
## Reference [#reference]
```typescript
function parseMGRS(
_format: any,
input: string
): [tokens: string[], errors: string[]]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------- | ------------------------------------------------------------ |
| `_format` | `any` | Unused format parameter (MGRS has fixed format) |
| `input` | `string` | MGRS coordinate string to parse (e.g., '31U BF 12345 67890') |
### Returns [#returns]
Returns a tuple containing:
* `tokens`: Array with latitude/longitude values and bearing indicators
* `errors`: Array of validation error messages (empty if valid)
### MGRS Format [#mgrs-format]
MGRS coordinates consist of:
1. **Grid Zone Designation** (2-3 chars): UTM zone number (01-60) + latitude band letter (C-X, excluding I and O)
2. **100K Square Identification** (2 chars): Two-letter square identifier (A-Z, excluding I and O)
3. **Numerical Location**: Easting and northing values within the 100km square
Expected format: `DDZ AA DDD DDD`
Example: `31U BF 12345 67890`
### Validation Rules [#validation-rules]
Validates that:
* UTM zone number is between 1 and 60
* Latitude band letter is valid (C-H, J-N, P-X)
* 100K meter square identification uses valid letters (A-H, J-N, P-Z)
* Numerical location (easting and northing) are positive numbers
## Examples [#examples]
### Example: Valid MGRS coordinate [#example-valid-mgrs-coordinate]
```typescript
import { parseMGRS } from '@accelint/geo';
const [coords, errors] = parseMGRS(null, '31U BF 12345 67890');
// coords: ['48.123456', 'N', '/', '11.234567', 'E']
// errors: []
```
### Example: New York City coordinates [#example-new-york-city-coordinates]
```typescript
import { parseMGRS } from '@accelint/geo';
const [coords, errors] = parseMGRS(null, '18T WL 80000 00000');
// coords: ['40.7128', 'N', '/', '73.9352', 'W']
// errors: []
```
### Example: Invalid UTM zone [#example-invalid-utm-zone]
```typescript
import { parseMGRS } from '@accelint/geo';
const [coords, errors] = parseMGRS(null, '99Z AA 12345 67890');
// coords: []
// errors: ['[ERROR] Invalid UTM zone number (99) found in grid zone designation; expected format DDZ AA DDD DDD.']
```
### Example: Invalid latitude band [#example-invalid-latitude-band]
```typescript
import { parseMGRS } from '@accelint/geo';
const [coords, errors] = parseMGRS(null, '31I AA 12345 67890');
// coords: []
// errors: ['[ERROR] Invalid Latitude band letter (I) found in grid zone designation; expected format DDZ AA DDD DDD.']
```
### Example: Invalid 100K square identification [#example-invalid-100k-square-identification]
```typescript
import { parseMGRS } from '@accelint/geo';
const [coords, errors] = parseMGRS(null, '31U OI 12345 67890');
// coords: []
// errors: ['[ERROR] Invalid 100K m square identification (OI) found; expected format DDZ AA DDD DDD.']
```
### Example: Invalid numerical location [#example-invalid-numerical-location]
```typescript
import { parseMGRS } from '@accelint/geo';
const [coords, errors] = parseMGRS(null, '31U AA 0 0');
// coords: []
// errors: ['[ERROR] Invalid numerical location (0,0) found; expected format DDZ AA DDD DDD.']
```
### Example: Missing components [#example-missing-components]
```typescript
import { parseMGRS } from '@accelint/geo';
const [coords, errors] = parseMGRS(null, '31U');
// coords: []
// errors: ['[ERROR] Invalid 100K m square identification () found; expected format DDZ AA DDD DDD.']
```
### Example: Empty input [#example-empty-input]
```typescript
import { parseMGRS } from '@accelint/geo';
const [coords, errors] = parseMGRS(null, '');
// coords: []
// errors: ['[ERROR] No input provided; expected format DDZ AA DDD DDD.']
```
> **Good to know:** MGRS uses the geodesy library for conversion. The coordinate system automatically handles UTM zone calculations and converts to precise latitude/longitude values.
> **Good to know:** Letters I and O are excluded from MGRS to avoid confusion with digits 1 and 0. Valid latitude bands exclude polar regions (A, B, Y, Z are not used in standard MGRS).
## Related [#related]
* [parseUTM](../utm/parser.md) - Parse Universal Transverse Mercator coordinates
* [parseDecimalDegrees](../latlon/decimal-degrees/parser.md) - Parse Decimal Degrees coordinates
* [createCoordinate](../coordinate.md) - Create coordinate with automatic parsing
* [coordinateSystems](../coordinate.md#coordinatesystems) - Available coordinate systems
# parseUTM (/docs/packages/geo/coordinates/utm/parser)
Parses Universal Transverse Mercator (UTM) coordinate strings and converts them to latitude/longitude decimal degrees with detailed validation.
## Usage [#usage]
```typescript
import { parseUTM } from '@accelint/geo';
// Parse UTM coordinate
const [coords, errors] = parseUTM(null, '18 N 585628 4511322');
// coords: ['40.74839601188732', 'N', '/', '73.98570490632135', 'W']
// errors: []
```
## Reference [#reference]
```typescript
function parseUTM(
_format: any,
input: string
): [tokens: string[], errors: string[]]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | -------- | ------------------------------------------------------------ |
| `_format` | `any` | Unused format parameter (kept for interface compatibility) |
| `input` | `string` | UTM coordinate string to parse (e.g., '18 N 585628 4511322') |
### Returns [#returns]
Returns a tuple containing:
* `tokens`: Array with latitude/longitude values and bearing indicators
* `errors`: Array of validation error messages (empty if valid)
### UTM Format [#utm-format]
UTM coordinates consist of:
1. **Zone Number** (1-60): UTM longitudinal zone
2. **Hemisphere** (N or S): North or South hemisphere
3. **Easting** (0-999999): Meters east from zone's central meridian
4. **Northing** (0-9999999): Meters north from equator (N) or south from 10,000km (S)
Expected format: `ZZ N|S EEEEE NNNNN`
Example: `18 N 585628 4511322`
### Validation Rules [#validation-rules]
Validates that:
* Zone number is between 1 and 60
* Hemisphere letter is N (North) or S (South)
* Easting is a valid non-negative number
* Northing is a valid non-negative number
## Examples [#examples]
### Example: Valid UTM coordinate (New York City) [#example-valid-utm-coordinate-new-york-city]
```typescript
import { parseUTM } from '@accelint/geo';
const [coords, errors] = parseUTM(null, '18 N 585628 4511322');
// coords: ['40.74839601188732', 'N', '/', '73.98570490632135', 'W']
// errors: []
```
### Example: London coordinates [#example-london-coordinates]
```typescript
import { parseUTM } from '@accelint/geo';
const [coords, errors] = parseUTM(null, '30 N 585358 5669660');
// coords: ['51.17199279600467', 'N', '/', '1.7790080009934', 'W']
// errors: []
```
### Example: Southern hemisphere [#example-southern-hemisphere]
```typescript
import { parseUTM } from '@accelint/geo';
const [coords, errors] = parseUTM(null, '56 S 334786 6252080');
// coords: ['33.8688', 'S', '/', '151.2093', 'E']
// errors: []
```
### Example: Without spaces (automatic normalization) [#example-without-spaces-automatic-normalization]
```typescript
import { parseUTM } from '@accelint/geo';
const [coords, errors] = parseUTM(null, '18N 585628 4511322');
// Automatically normalized to '18 N 585628 4511322'
// coords: ['40.74839601188732', 'N', '/', '73.98570490632135', 'W']
// errors: []
```
### Example: Invalid zone number [#example-invalid-zone-number]
```typescript
import { parseUTM } from '@accelint/geo';
const [coords, errors] = parseUTM(null, '65 N 585628 4511322');
// coords: []
// errors: ['[ERROR] Invalid Zone number (65) found; expected format ZZ N|S DDD DDD.']
```
### Example: Zone too low [#example-zone-too-low]
```typescript
import { parseUTM } from '@accelint/geo';
const [coords, errors] = parseUTM(null, '-1 N 585628 4511322');
// coords: []
// errors: ['[ERROR] Invalid Zone number (-1) found; expected format ZZ N|S DDD DDD.']
```
### Example: Invalid hemisphere [#example-invalid-hemisphere]
```typescript
import { parseUTM } from '@accelint/geo';
const [coords, errors] = parseUTM(null, '18 X 585628 4511322');
// coords: []
// errors: ['[ERROR] Invalid Latitude band letter (X) found; expected format ZZ N|S DDD DDD.']
```
### Example: Missing easting [#example-missing-easting]
```typescript
import { parseUTM } from '@accelint/geo';
const [coords, errors] = parseUTM(null, '18 N');
// coords: []
// errors: ['[ERROR] Invalid Easting number () found; expected format ZZ N|S DDD DDD.']
```
### Example: Missing northing [#example-missing-northing]
```typescript
import { parseUTM } from '@accelint/geo';
const [coords, errors] = parseUTM(null, '18 N 585628');
// coords: []
// errors: ['[ERROR] Invalid Northing number () found; expected format ZZ N|S DDD DDD.']
```
### Example: Empty input [#example-empty-input]
```typescript
import { parseUTM } from '@accelint/geo';
const [coords, errors] = parseUTM(null, '');
// coords: []
// errors: ['[ERROR] Invalid Zone number () found; expected format ZZ N|S DDD DDD.']
```
> **Good to know:** UTM divides the Earth into 60 longitudinal zones, each 6° wide. Zone 1 starts at 180° West. The parser automatically normalizes input by ensuring proper spacing between zone and hemisphere.
> **Good to know:** UTM uses the geodesy library for conversion. The coordinate system handles zone-specific calculations and converts to precise latitude/longitude values.
> **Good to know:** The parser accepts both `18N` and `18 N` formats (with or without space between zone and hemisphere). Internally, it normalizes to the format expected by the geodesy library.
## Related [#related]
* [parseMGRS](../mgrs/parser.md) - Parse Military Grid Reference System coordinates
* [parseDecimalDegrees](../latlon/decimal-degrees/parser.md) - Parse Decimal Degrees coordinates
* [createCoordinate](../coordinate.md) - Create coordinate with automatic parsing
* [coordinateSystems](../coordinate.md#coordinatesystems) - Available coordinate systems
# CarouselGallery (/docs/toolkits/design-toolkit/components/carousel/gallery)
Renders a horizontally-scrolling strip of thumbnail buttons for carousel navigation with automatic scroll positioning.
## Usage [#usage]
```tsx
import { Carousel, CarouselGallery } from '@accelint/design-toolkit';
export function Gallery({ items, position, setPosition }) {
return (
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselGallery />
</Carousel>
);
}
```
## Reference [#reference]
```typescript
interface CarouselGalleryProps extends HTMLAttributes<HTMLDivElement> {
classNames?: {
container?: string;
item?: string;
};
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ------------ | --------------------------------------- | ------- | -------- |
| `classNames` | `{ container?: string; item?: string }` | - | No |
| `className` | `string` | - | No |
#### `classNames.container` [#classnamescontainer]
Class name applied to the gallery container element.
#### `classNames.item` [#classnamesitem]
Class name applied to individual thumbnail button elements.
### Behavior [#behavior]
The gallery automatically scrolls to keep the selected thumbnail visible, maintaining 2 items before the selected item when possible for visual context.
Clicking any thumbnail navigates the carousel to that item by calling `setCurrentPosition` with the item's index.
## Examples [#examples]
### Example: Basic gallery [#example-basic-gallery]
```tsx
import { Carousel, CarouselGallery, CarouselViewer } from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselViewer />
<CarouselGallery />
</Carousel>
```
### Example: Custom styled gallery [#example-custom-styled-gallery]
```tsx
import { Carousel, CarouselGallery } from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselGallery
classNames={{
container: 'py-4 gap-2',
item: 'rounded-lg border-2'
}}
/>
</Carousel>
```
### Example: Gallery with navigation [#example-gallery-with-navigation]
```tsx
import {
Carousel,
CarouselViewer,
CarouselGallery,
CarouselPrevious,
CarouselNext
} from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselViewer />
<div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
<CarouselPrevious />
<CarouselGallery />
<CarouselNext />
</div>
</Carousel>
```
> **Good to know:** Gallery thumbnails use `ToggleButton` components internally, providing visual feedback for the selected state and keyboard accessibility.
## Related [#related]
* [Carousel](./index.mdx) - Parent carousel component
* [ToggleButton](../button/toggle.mdx) - Button component used for thumbnails
# Carousel (/docs/toolkits/design-toolkit/components/carousel)
## Usage [#usage]
```tsx
import { useState } from 'react';
import {
Carousel,
CarouselViewer,
CarouselGallery,
CarouselPrevious,
CarouselNext,
CarouselPosition,
CarouselSelect
} from '@accelint/design-toolkit';
const items = [
{
id: '1',
dataType: 'image',
dataUrl: '/images/photo1.jpg',
thumbnailUrl: '/images/thumb1.jpg',
title: 'Sunset',
fileName: 'photo1.jpg'
},
// ... more items
];
export function Gallery() {
const [position, setPosition] = useState(0);
return (
<Carousel
items={items}
currentPosition={position}
setCurrentPosition={setPosition}
>
<CarouselViewer />
<CarouselPrevious />
<CarouselGallery />
<CarouselNext />
<CarouselPosition />
</Carousel>
);
}
```
## Reference [#reference]
```typescript
interface CarouselProps extends HTMLAttributes<HTMLDivElement> {
items: CarouselData[];
currentPosition: number;
setCurrentPosition: (index: number) => void;
children?: React.ReactNode;
className?: string;
}
interface CarouselData {
dataType: 'image' | 'video' | 'audio';
dataUrl: string;
fileName: string;
metadata?: Record<string, unknown>;
title: string;
thumbnailUrl: string;
id: UniqueId;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| -------------------- | ------------------------- | ------- | -------- |
| `items` | `CarouselData[]` | `[]` | Yes |
| `currentPosition` | `number` | - | Yes |
| `setCurrentPosition` | `(index: number) => void` | - | Yes |
| `children` | `React.ReactNode` | - | No |
| `className` | `string` | - | No |
#### `items` [#items]
Array of carousel data items to display. Each item must have:
* `dataType` - Media type: `'image'`, `'video'`, or `'audio'`
* `dataUrl` - URL for the full-size media displayed in the viewer
* `thumbnailUrl` - URL for the thumbnail shown in the gallery
* `title` - Display title for the item
* `fileName` - Original file name of the media asset
* `id` - Unique identifier (string or number)
* `metadata` - Optional additional data
#### `currentPosition` [#currentposition]
Zero-based index of the currently active item. Controls which item is displayed in the viewer and selected in the gallery.
#### `setCurrentPosition` [#setcurrentposition]
Callback invoked when the active item changes through user interaction (clicking thumbnails, navigation buttons, or select dropdown).
#### `children` [#children]
Composable sub-components to render. Available sub-components:
* `CarouselViewer` - Displays the full-size media
* `CarouselGallery` - Thumbnail strip for navigation
* `CarouselPrevious` / `CarouselNext` - Navigation buttons
* `CarouselPosition` - Position indicator (e.g., "3 / 9")
* `CarouselSelect` - Dropdown select for jumping to items
## Examples [#examples]
### Example: Image carousel [#example-image-carousel]
```tsx
import { useState } from 'react';
import {
Carousel,
CarouselViewer,
CarouselGallery,
CarouselPrevious,
CarouselNext
} from '@accelint/design-toolkit';
const images = [
{
id: '1',
dataType: 'image',
dataUrl: '/photos/sunset.jpg',
thumbnailUrl: '/photos/sunset-thumb.jpg',
title: 'Golden Sunset',
fileName: 'sunset.jpg'
},
{
id: '2',
dataType: 'image',
dataUrl: '/photos/mountains.jpg',
thumbnailUrl: '/photos/mountains-thumb.jpg',
title: 'Mountain Range',
fileName: 'mountains.jpg'
}
];
export function ImageGallery() {
const [position, setPosition] = useState(0);
return (
<Carousel
items={images}
currentPosition={position}
setCurrentPosition={setPosition}
>
<CarouselViewer />
<div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
<CarouselPrevious />
<CarouselGallery />
<CarouselNext />
</div>
</Carousel>
);
}
```
### Example: Mixed media carousel [#example-mixed-media-carousel]
```tsx
import { useState } from 'react';
import {
Carousel,
CarouselViewer,
CarouselSelect,
CarouselPosition
} from '@accelint/design-toolkit';
const mediaItems = [
{
id: '1',
dataType: 'video',
dataUrl: '/videos/demo.mp4',
thumbnailUrl: '/videos/demo-poster.jpg',
title: 'Product Demo',
fileName: 'demo.mp4'
},
{
id: '2',
dataType: 'audio',
dataUrl: '/audio/podcast.mp3',
thumbnailUrl: '/audio/podcast-cover.jpg',
title: 'Episode 42',
fileName: 'podcast.mp3'
},
{
id: '3',
dataType: 'image',
dataUrl: '/images/diagram.png',
thumbnailUrl: '/images/diagram-thumb.png',
title: 'Architecture Diagram',
fileName: 'diagram.png'
}
];
export function MediaGallery() {
const [position, setPosition] = useState(0);
return (
<Carousel
items={mediaItems}
currentPosition={position}
setCurrentPosition={setPosition}
>
<CarouselViewer />
<div style={{ display: 'flex', justifyContent: 'space-between' }}>
<CarouselSelect />
<CarouselPosition />
</div>
</Carousel>
);
}
```
### Example: With custom controls overlay [#example-with-custom-controls-overlay]
```tsx
import { useState } from 'react';
import {
Carousel,
CarouselViewer,
CarouselPrevious,
CarouselNext,
CarouselPosition
} from '@accelint/design-toolkit';
export function OverlayGallery({ items }) {
const [position, setPosition] = useState(0);
return (
<Carousel
items={items}
currentPosition={position}
setCurrentPosition={setPosition}
>
<CarouselViewer>
{/* Overlay controls positioned absolutely inside viewer */}
<div style={{
position: 'absolute',
bottom: '1rem',
left: '50%',
transform: 'translateX(-50%)',
display: 'flex',
gap: '0.5rem',
alignItems: 'center'
}}>
<CarouselPrevious />
<CarouselPosition />
<CarouselNext />
</div>
</CarouselViewer>
</Carousel>
);
}
```
### Example: Controlled from parent [#example-controlled-from-parent]
```tsx
import { useState } from 'react';
import { Carousel, CarouselViewer, Button } from '@accelint/design-toolkit';
export function ControlledCarousel({ items }) {
const [position, setPosition] = useState(0);
const jumpToFirst = () => setPosition(0);
const jumpToLast = () => setPosition(items.length - 1);
return (
<div>
<Carousel
items={items}
currentPosition={position}
setCurrentPosition={setPosition}
>
<CarouselViewer />
</Carousel>
<div style={{ marginTop: '1rem', display: 'flex', gap: '0.5rem' }}>
<Button onClick={jumpToFirst}>First</Button>
<Button onClick={jumpToLast}>Last</Button>
</div>
</div>
);
}
```
> **Good to know:** The Carousel component manages state through context. All sub-components must be rendered as children of the Carousel to access carousel state and callbacks.
## Related [#related]
* [CarouselViewer](./viewer.mdx) - Displays the full-size media for the active item
* [CarouselGallery](./gallery.mdx) - Horizontal thumbnail strip for navigation
* [CarouselPrevious / CarouselNext](./navigation.mdx) - Navigation buttons
* [CarouselPosition](./position.mdx) - Current position indicator
* [CarouselSelect](./select.mdx) - Dropdown select for jumping to items
* [Video](../video/index.mdx) - Video component used by CarouselViewer
* [Audio](../audio/index.mdx) - Audio component used by CarouselViewer
# CarouselPrevious / CarouselNext (/docs/toolkits/design-toolkit/components/carousel/navigation)
Navigation buttons for moving between carousel items with automatic boundary detection.
## Usage [#usage]
```tsx
import { Carousel, CarouselPrevious, CarouselNext } from '@accelint/design-toolkit';
export function Gallery({ items, position, setPosition }) {
return (
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselPrevious />
<CarouselNext />
</Carousel>
);
}
```
## Reference [#reference]
```typescript
interface CarouselNavigationProps extends ButtonProps {
className?: string;
variant?: 'filled' | 'outline' | 'flat' | 'icon';
isDisabled?: boolean;
}
```
### Props [#props]
Both components accept all props from the `Button` component, including:
| Prop | Type | Default | Required |
| ------------ | ------------------------------------------- | -------- | -------- |
| `className` | `string` | - | No |
| `variant` | `'filled' \| 'outline' \| 'flat' \| 'icon'` | `'flat'` | No |
| `isDisabled` | `boolean` | `false` | No |
### Behavior [#behavior]
**CarouselPrevious**
* Navigates to the previous item (currentPosition - 1)
* Automatically disables when at the first item (position 0)
* Renders with a left chevron icon
* Accessible label: "Previous"
**CarouselNext**
* Navigates to the next item (currentPosition + 1)
* Automatically disables when at the last item
* Renders with a right chevron icon
* Accessible label: "Next"
## Examples [#examples]
### Example: Basic navigation buttons [#example-basic-navigation-buttons]
```tsx
import {
Carousel,
CarouselViewer,
CarouselPrevious,
CarouselNext
} from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselViewer />
<div style={{ display: 'flex', gap: '0.5rem', justifyContent: 'center' }}>
<CarouselPrevious />
<CarouselNext />
</div>
</Carousel>
```
### Example: Filled variant buttons [#example-filled-variant-buttons]
```tsx
import { Carousel, CarouselPrevious, CarouselNext } from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselPrevious variant="filled" />
<CarouselNext variant="filled" />
</Carousel>
```
### Example: Icon-only buttons [#example-icon-only-buttons]
```tsx
import { Carousel, CarouselPrevious, CarouselNext } from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselPrevious variant="icon" />
<CarouselNext variant="icon" />
</Carousel>
```
### Example: Positioned as overlay [#example-positioned-as-overlay]
```tsx
import {
Carousel,
CarouselViewer,
CarouselPrevious,
CarouselNext
} from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselViewer>
<div style={{
position: 'absolute',
inset: 0,
display: 'flex',
alignItems: 'center',
justifyContent: 'space-between',
padding: '1rem'
}}>
<CarouselPrevious variant="filled" />
<CarouselNext variant="filled" />
</div>
</CarouselViewer>
</Carousel>
```
### Example: Custom styling [#example-custom-styling]
```tsx
import { Carousel, CarouselPrevious, CarouselNext } from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselPrevious
variant="outline"
className="rounded-full shadow-lg"
/>
<CarouselNext
variant="outline"
className="rounded-full shadow-lg"
/>
</Carousel>
```
> **Good to know:** Navigation buttons automatically disable at carousel boundaries, preventing navigation beyond the first or last item. You can manually disable them with `isDisabled` if needed.
## Related [#related]
* [Carousel](./index.mdx) - Parent carousel component
* [Button](../button/index.mdx) - Base button component
* [Icon](../icon/index.mdx) - Icon component used for chevron icons
# CarouselPosition (/docs/toolkits/design-toolkit/components/carousel/position)
Displays the current position and total item count (e.g., "3 / 9").
## Usage [#usage]
```tsx
import { Carousel, CarouselPosition } from '@accelint/design-toolkit';
export function Gallery({ items, position, setPosition }) {
return (
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselPosition />
</Carousel>
);
}
```
## Reference [#reference]
```typescript
interface CarouselPositionProps extends HTMLAttributes<HTMLDivElement> {
className?: string;
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ----------- | -------- | ------- | -------- |
| `className` | `string` | - | No |
Accepts all standard HTML div attributes in addition to `className`.
### Display Format [#display-format]
Renders as: `{currentPosition + 1} / {totalItems}`
Position is 1-indexed for display (user-friendly numbering starting at 1).
## Examples [#examples]
### Example: Basic position indicator [#example-basic-position-indicator]
```tsx
import {
Carousel,
CarouselViewer,
CarouselPosition
} from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselViewer />
<CarouselPosition />
</Carousel>
```
### Example: Positioned as overlay [#example-positioned-as-overlay]
```tsx
import {
Carousel,
CarouselViewer,
CarouselPosition
} from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselViewer>
<div style={{ position: 'absolute', top: '1rem', right: '1rem' }}>
<CarouselPosition />
</div>
</CarouselViewer>
</Carousel>
```
### Example: With navigation controls [#example-with-navigation-controls]
```tsx
import {
Carousel,
CarouselViewer,
CarouselPrevious,
CarouselNext,
CarouselPosition
} from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselViewer />
<div style={{ display: 'flex', gap: '1rem', justifyContent: 'center', alignItems: 'center' }}>
<CarouselPrevious />
<CarouselPosition />
<CarouselNext />
</div>
</Carousel>
```
### Example: Custom styling [#example-custom-styling]
```tsx
import { Carousel, CarouselPosition } from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselPosition
className="text-sm font-semibold text-gray-700"
style={{ padding: '0.5rem 1rem', backgroundColor: 'rgba(255,255,255,0.9)', borderRadius: '9999px' }}
/>
</Carousel>
```
> **Good to know:** Position is displayed with 1-based indexing (first item shows as "1 / N") for better user experience, though the internal `currentPosition` prop uses 0-based indexing.
## Related [#related]
* [Carousel](./index.mdx) - Parent carousel component
* [CarouselSelect](./select.mdx) - Dropdown navigation alternative
# CarouselSelect (/docs/toolkits/design-toolkit/components/carousel/select)
Dropdown select component for navigating the carousel by item title.
## Usage [#usage]
```tsx
import { Carousel, CarouselSelect } from '@accelint/design-toolkit';
export function Gallery({ items, position, setPosition }) {
return (
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselSelect />
</Carousel>
);
}
```
## Reference [#reference]
```typescript
interface CarouselSelectProps extends Omit<SelectFieldProps, 'classNames'> {
classNames?: {
select?: SelectFieldProps['classNames'];
optionItem?: OptionsItemProps<OptionsDataItem>['classNames'];
};
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ------------ | ------------------------------------------ | ------- | -------- |
| `classNames` | `{ select?: object; optionItem?: object }` | - | No |
Inherits all props from `SelectField` except `value`, `onChange`, and `placeholder` (managed internally).
#### `classNames.select` [#classnamesselect]
Class names passed through to the underlying `SelectField` component. Supports all `SelectField` class name slots (field, trigger, popover, etc.).
#### `classNames.optionItem` [#classnamesoptionitem]
Class names passed to each `OptionsItem` rendered in the dropdown.
### Behavior [#behavior]
* Displays the current item's title in the trigger
* Opens a dropdown showing all item titles
* Clicking an item navigates to that position
* Automatically updates when `currentPosition` changes
* Uses item `id` as the selection key
## Examples [#examples]
### Example: Basic select [#example-basic-select]
```tsx
import {
Carousel,
CarouselViewer,
CarouselSelect
} from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselViewer />
<CarouselSelect />
</Carousel>
```
### Example: With position indicator [#example-with-position-indicator]
```tsx
import {
Carousel,
CarouselViewer,
CarouselSelect,
CarouselPosition
} from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselViewer />
<div style={{ display: 'flex', gap: '1rem', justifyContent: 'space-between' }}>
<CarouselSelect />
<CarouselPosition />
</div>
</Carousel>
```
### Example: Custom styling [#example-custom-styling]
```tsx
import { Carousel, CarouselSelect } from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselSelect
classNames={{
select: {
trigger: 'min-w-64 bg-white shadow-md',
popover: 'max-h-96'
},
optionItem: {
item: 'text-sm'
}
}}
/>
</Carousel>
```
### Example: Full carousel with all controls [#example-full-carousel-with-all-controls]
```tsx
import {
Carousel,
CarouselViewer,
CarouselGallery,
CarouselPrevious,
CarouselNext,
CarouselSelect,
CarouselPosition
} from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselViewer />
{/* Top controls */}
<div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: '1rem' }}>
<CarouselSelect />
<CarouselPosition />
</div>
{/* Bottom navigation */}
<div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
<CarouselPrevious />
<CarouselGallery />
<CarouselNext />
</div>
</Carousel>
```
> **Good to know:** The select uses the item's `title` property for display and its `id` for the selection key. Ensure each item has a unique `id` and descriptive `title`.
## Related [#related]
* [Carousel](./index.mdx) - Parent carousel component
* [SelectField](../select-field/index.mdx) - Base select component
* [OptionsItem](../options/item.mdx) - Option item component
* [CarouselPosition](./position.mdx) - Alternative position indicator
# CarouselViewer (/docs/toolkits/design-toolkit/components/carousel/viewer)
Displays the full-size media for the currently active carousel item based on its data type (image, video, or audio).
## Usage [#usage]
```tsx
import { Carousel, CarouselViewer } from '@accelint/design-toolkit';
export function Gallery({ items, position, setPosition }) {
return (
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselViewer />
</Carousel>
);
}
```
## Reference [#reference]
```typescript
interface CarouselViewerProps extends PropsWithChildren {
classNames?: {
container?: string;
media?: string;
};
}
```
### Props [#props]
| Prop | Type | Default | Required |
| ------------ | ---------------------------------------- | ------- | -------- |
| `children` | `React.ReactNode` | - | No |
| `classNames` | `{ container?: string; media?: string }` | - | No |
#### `children` [#children]
Optional overlay content rendered inside the viewer. Useful for positioning controls or metadata over the media.
#### `classNames.container` [#classnamescontainer]
Class name applied to the viewer container element.
#### `classNames.media` [#classnamesmedia]
Class name applied to the displayed media element (`img`, `video`, or `audio` component).
## Examples [#examples]
### Example: Basic viewer [#example-basic-viewer]
```tsx
import { Carousel, CarouselViewer } from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselViewer />
</Carousel>
```
### Example: With overlay controls [#example-with-overlay-controls]
```tsx
import { Carousel, CarouselViewer, CarouselPosition } from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselViewer>
<div style={{ position: 'absolute', bottom: '1rem', right: '1rem' }}>
<CarouselPosition />
</div>
</CarouselViewer>
</Carousel>
```
### Example: Custom styling [#example-custom-styling]
```tsx
import { Carousel, CarouselViewer } from '@accelint/design-toolkit';
<Carousel items={items} currentPosition={position} setCurrentPosition={setPosition}>
<CarouselViewer
classNames={{
container: 'aspect-video bg-gray-900',
media: 'object-contain'
}}
/>
</Carousel>
```
> **Good to know:** CarouselViewer automatically renders the appropriate media element based on the current item's `dataType`: images use `<img>`, videos use the `Video` component, and audio uses the `Audio` component.
## Related [#related]
* [Carousel](./index.mdx) - Parent carousel component
* [Video](../video/index.mdx) - Video component for video items
* [Audio](../audio/index.mdx) - Audio component for audio items
# formatDecimalDegrees (/docs/packages/geo/coordinates/latlon/decimal-degrees/formatter)
Formats latitude/longitude coordinates in decimal degrees notation with configurable separators and ordinal directions.
## Usage [#usage]
```typescript
import { formatDecimalDegrees } from '@accelint/geo';
// Basic usage with default separator
formatDecimalDegrees([37.7749, -122.4194]);
// '37.774900° N, 122.419400° W'
```
## Reference [#reference]
```typescript
function formatDecimalDegrees(
coordinates: [number, number],
config?: FormatConfig
): string
interface FormatConfig {
separator?: string;
}
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ------------- | ------------------------- | --------------------------------------------------------- |
| `coordinates` | `[number, number]` | Tuple of \[latitude, longitude] values in decimal degrees |
| `config` | `FormatConfig` (optional) | Formatting configuration with optional separator |
### Returns [#returns]
Returns formatted coordinate string in decimal degrees format with 6 decimal places, degree symbols, and ordinal directions (N/S/E/W).
## Examples [#examples]
### Example: Basic formatting [#example-basic-formatting]
```typescript
import { formatDecimalDegrees } from '@accelint/geo';
formatDecimalDegrees([37.7749, -122.4194]);
// '37.774900° N, 122.419400° W'
```
### Example: Custom separator [#example-custom-separator]
```typescript
import { formatDecimalDegrees } from '@accelint/geo';
formatDecimalDegrees([37.7749, -122.4194], { separator: ' / ' });
// '37.774900° N / 122.419400° W'
```
### Example: Northern and Eastern hemispheres [#example-northern-and-eastern-hemispheres]
```typescript
import { formatDecimalDegrees } from '@accelint/geo';
formatDecimalDegrees([48.8566, 2.3522]);
// '48.856600° N, 2.352200° E'
```
### Example: Southern hemisphere [#example-southern-hemisphere]
```typescript
import { formatDecimalDegrees } from '@accelint/geo';
formatDecimalDegrees([-33.8688, 151.2093]);
// '33.868800° S, 151.209300° E'
```
### Example: Boundary values [#example-boundary-values]
```typescript
import { formatDecimalDegrees } from '@accelint/geo';
// Maximum latitude
formatDecimalDegrees([90, 0]);
// '90.000000° N, 0.000000° E'
// International Date Line
formatDecimalDegrees([0, 180]);
// '0.000000° N, 180.000000° E'
```
> **Good to know:** The formatter always uses 6 decimal places for consistency and precision. Negative latitude values are converted to Southern hemisphere (S), and negative longitude values to Western hemisphere (W).
## Related [#related]
* [parseDecimalDegrees](./parser.md) - Parse decimal degrees coordinate strings
* [formatDegreesDecimalMinutes](../degrees-decimal-minutes/formatter.md) - Format coordinates in DDM notation
* [formatDegreesMinutesSeconds](../degrees-minutes-seconds/formatter.md) - Format coordinates in DMS notation
* [createCoordinate](../../coordinate.md) - Create coordinate with automatic format conversion
# parseDecimalDegrees (/docs/packages/geo/coordinates/latlon/decimal-degrees/parser)
Parses a Decimal Degrees coordinate string with validation for ranges, bearing indicators, and format consistency.
## Usage [#usage]
```typescript
import { parseDecimalDegrees } from '@accelint/geo';
// Parse with explicit format
const [coords, errors] = parseDecimalDegrees('37.7749° N / 122.4194° W', 'LATLON');
// coords: ['37.7749', 'N', '/', '122.4194', 'W']
// errors: []
```
## Reference [#reference]
```typescript
function parseDecimalDegrees(
input: string,
format: 'LATLON' | 'LONLAT'
): [tokens: string[], errors: string[]]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---------------------- | ------------------------------ |
| `input` | `string` | Raw coordinate string to parse |
| `format` | `'LATLON' \| 'LONLAT'` | Expected format ordering |
### Returns [#returns]
Returns a tuple containing:
* `tokens`: Array of parsed coordinate components (degrees, bearings, dividers)
* `errors`: Array of validation error messages (empty if valid)
### Validation Rules [#validation-rules]
Validates that:
* Degree values are within acceptable ranges (±90 for latitude, ±180 for longitude)
* Minutes indicator (`'`) is not present (invalid for Decimal Degrees)
* Seconds indicator (`"`) is not present (invalid for Decimal Degrees)
* Bearing indicators match the specified format (N/S for latitude, E/W for longitude)
* Negative signs on degrees are converted to appropriate bearing directions
## Examples [#examples]
### Example: Basic parsing [#example-basic-parsing]
```typescript
import { parseDecimalDegrees } from '@accelint/geo';
const [coords, errors] = parseDecimalDegrees('37.7749° N / 122.4194° W', 'LATLON');
// coords: ['37.7749', 'N', '/', '122.4194', 'W']
// errors: []
```
### Example: Without degree symbols [#example-without-degree-symbols]
```typescript
import { parseDecimalDegrees } from '@accelint/geo';
const [coords, errors] = parseDecimalDegrees('45.5 N, 122.6 W', 'LATLON');
// coords: ['45.5', 'N', '/', '122.6', 'W']
// errors: []
```
### Example: Negative values convert to bearings [#example-negative-values-convert-to-bearings]
```typescript
import { parseDecimalDegrees } from '@accelint/geo';
const [coords, errors] = parseDecimalDegrees('-45.5 75.3', 'LATLON');
// coords: ['45.5', 'S', '/', '75.3', 'E']
// errors: []
```
### Example: LONLAT format [#example-lonlat-format]
```typescript
import { parseDecimalDegrees } from '@accelint/geo';
const [coords, errors] = parseDecimalDegrees('180 E / 90 N', 'LONLAT');
// coords: ['180', 'E', '/', '90', 'N']
// errors: []
```
### Example: Out of range latitude [#example-out-of-range-latitude]
```typescript
import { parseDecimalDegrees } from '@accelint/geo';
const [coords, errors] = parseDecimalDegrees('91 / 0', 'LATLON');
// coords: []
// errors: ['[ERROR] Degrees value (91) exceeds max value (90).']
```
### Example: Out of range longitude [#example-out-of-range-longitude]
```typescript
import { parseDecimalDegrees } from '@accelint/geo';
const [coords, errors] = parseDecimalDegrees('180 , 90', 'LONLAT');
// coords: []
// errors: ['[ERROR] Degrees value (181) exceeds max value (180).']
```
### Example: Invalid minutes indicator [#example-invalid-minutes-indicator]
```typescript
import { parseDecimalDegrees } from '@accelint/geo';
const [coords, errors] = parseDecimalDegrees('40° 26\' N, 79° 58\' W', 'LATLON');
// coords: []
// errors: ['[ERROR] Minutes indicator (\') not valid in Decimal Degrees.']
```
### Example: Invalid seconds indicator [#example-invalid-seconds-indicator]
```typescript
import { parseDecimalDegrees } from '@accelint/geo';
const [coords, errors] = parseDecimalDegrees('40° 26" N, 79° 58" W', 'LATLON');
// coords: []
// errors: ['[ERROR] Seconds indicator (") not valid in Decimal Degrees.']
```
### Example: Format mismatch [#example-format-mismatch]
```typescript
import { parseDecimalDegrees } from '@accelint/geo';
const [coords, errors] = parseDecimalDegrees('1 E / 2 N', 'LATLON');
// coords: []
// errors: ['[ERROR] Mismatched formats: "LATLON" expected, "LONLAT" found.']
```
### Example: Flexible separators [#example-flexible-separators]
```typescript
import { parseDecimalDegrees } from '@accelint/geo';
// Comma separator
parseDecimalDegrees('45.5 N, 90.5 W', 'LATLON');
// Slash separator
parseDecimalDegrees('45.5 N / 90.5 W', 'LATLON');
// Space separator
parseDecimalDegrees('45.5 N 90.5 W', 'LATLON');
```
> **Good to know:** The parser accepts various separators (comma, slash, or space) between coordinate components. Negative signs on degrees are automatically converted to appropriate bearing directions (S for negative latitude, W for negative longitude).
> **Good to know:** Decimal Degrees format does NOT allow minutes (`'`) or seconds (`"`) indicators. Use `parseDegreesDecimalMinutes` or `parseDegreesMinutesSeconds` for those formats.
## Related [#related]
* [formatDecimalDegrees](./formatter.md) - Format coordinates in Decimal Degrees notation
* [parseDegreesDecimalMinutes](../degrees-decimal-minutes/parser.md) - Parse DDM coordinate strings
* [parseDegreesMinutesSeconds](../degrees-minutes-seconds/parser.md) - Parse DMS coordinate strings
* [createCoordinate](../../coordinate.md) - Create coordinate with automatic parsing
# formatDegreesDecimalMinutes (/docs/packages/geo/coordinates/latlon/degrees-decimal-minutes/formatter)
Formats latitude/longitude coordinates in degrees decimal minutes (DDM) notation with configurable separators and ordinal directions.
## Usage [#usage]
```typescript
import { formatDegreesDecimalMinutes } from '@accelint/geo';
// Basic usage with default separator
formatDegreesDecimalMinutes([37.7749, -122.4194]);
// "37° 46.4940' N, 122° 25.1640' W"
```
## Reference [#reference]
```typescript
function formatDegreesDecimalMinutes(
coordinates: [number, number],
config?: FormatConfig
): string
interface FormatConfig {
separator?: string;
}
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ------------- | ------------------------- | --------------------------------------------------------- |
| `coordinates` | `[number, number]` | Tuple of \[latitude, longitude] values in decimal degrees |
| `config` | `FormatConfig` (optional) | Formatting configuration with optional separator |
### Returns [#returns]
Returns formatted coordinate string in degrees decimal minutes format with degree symbols, decimal minutes (4 decimal places), minute symbols, and ordinal directions (N/S/E/W).
## Examples [#examples]
### Example: Basic formatting [#example-basic-formatting]
```typescript
import { formatDegreesDecimalMinutes } from '@accelint/geo';
formatDegreesDecimalMinutes([37.7749, -122.4194]);
// "37° 46.4940' N, 122° 25.1640' W"
```
### Example: Custom separator [#example-custom-separator]
```typescript
import { formatDegreesDecimalMinutes } from '@accelint/geo';
formatDegreesDecimalMinutes([37.7749, -122.4194], { separator: ' / ' });
// "37° 46.4940' N / 122° 25.1640' W"
```
### Example: Northern and Eastern hemispheres [#example-northern-and-eastern-hemispheres]
```typescript
import { formatDegreesDecimalMinutes } from '@accelint/geo';
formatDegreesDecimalMinutes([48.8566, 2.3522]);
// "48° 51.3960' N, 2° 21.1320' E"
```
### Example: Southern hemisphere [#example-southern-hemisphere]
```typescript
import { formatDegreesDecimalMinutes } from '@accelint/geo';
formatDegreesDecimalMinutes([-33.8688, 151.2093]);
// "33° 52.1280' S, 151° 12.5580' E"
```
### Example: Whole degrees (zero minutes) [#example-whole-degrees-zero-minutes]
```typescript
import { formatDegreesDecimalMinutes } from '@accelint/geo';
formatDegreesDecimalMinutes([45.0, -90.0]);
// "45° 0.0000' N, 90° 0.0000' W"
```
### Example: Boundary values [#example-boundary-values]
```typescript
import { formatDegreesDecimalMinutes } from '@accelint/geo';
// Maximum latitude
formatDegreesDecimalMinutes([90, 0]);
// "90° 0.0000' N, 0° 0.0000' E"
// International Date Line
formatDegreesDecimalMinutes([0, 180]);
// "0° 0.0000' N, 180° 0.0000' E"
```
> **Good to know:** The formatter always uses 4 decimal places for minutes, providing precision to approximately 1.85 meters. Negative latitude values are converted to Southern hemisphere (S), and negative longitude values to Western hemisphere (W).
> **Good to know:** DDM format is commonly used in maritime navigation and aviation. It provides a balance between precision and readability compared to Decimal Degrees (DD) and Degrees Minutes Seconds (DMS).
## Related [#related]
* [parseDegreesDecimalMinutes](./parser.md) - Parse DDM coordinate strings
* [formatDecimalDegrees](../decimal-degrees/formatter.md) - Format coordinates in DD notation
* [formatDegreesMinutesSeconds](../degrees-minutes-seconds/formatter.md) - Format coordinates in DMS notation
* [createCoordinate](../../coordinate.md) - Create coordinate with automatic format conversion
# parseDegreesDecimalMinutes (/docs/packages/geo/coordinates/latlon/degrees-decimal-minutes/parser)
## Usage [#usage]
```typescript
import { parseDegreesDecimalMinutes } from '@accelint/geo';
// Parse with explicit format
const [tokens, errors] = parseDegreesDecimalMinutes('LATLON', '40° 46.302\' N, 79° 56.207\' W');
// tokens: ['40', '46.302', 'N', '/', '79', '56.207', 'W']
// errors: []
```
## Reference [#reference]
```typescript
function parseDegreesDecimalMinutes(
format: 'LATLON' | 'LONLAT',
input: string
): [tokens: string[], errors: string[]]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---------------------- | ------------------------------ |
| `format` | `'LATLON' \| 'LONLAT'` | Expected format ordering |
| `input` | `string` | Raw coordinate string to parse |
### Returns [#returns]
Returns a tuple containing:
* `tokens`: Array of parsed coordinate components (degrees, minutes, bearings, dividers)
* `errors`: Array of validation error messages (empty if valid)
### Validation Rules [#validation-rules]
Validates that:
* Degree values are integers (no decimal component allowed in degrees)
* Minute values are in valid range (0-59.999...)
* Seconds indicator (`"`) is not present (invalid for Degrees Decimal Minutes)
* Bearing indicators match the specified format (N/S for latitude, E/W for longitude)
* Negative signs on degrees are converted to appropriate bearing directions
## Examples [#examples]
### Example: Basic parsing [#example-basic-parsing]
```typescript
import { parseDegreesDecimalMinutes } from '@accelint/geo';
const [tokens, errors] = parseDegreesDecimalMinutes('LATLON', '40° 46.302\' N, 79° 56.207\' W');
// tokens: ['40', '46.302', 'N', '/', '79', '56.207', 'W']
// errors: []
```
### Example: Without degree/minute symbols [#example-without-degreeminute-symbols]
```typescript
import { parseDegreesDecimalMinutes } from '@accelint/geo';
const [tokens, errors] = parseDegreesDecimalMinutes('LATLON', '45 30.5 N, 122 15.3 W');
// tokens: ['45', '30.5', 'N', '/', '122', '15.3', 'W']
// errors: []
```
### Example: Maximum valid values [#example-maximum-valid-values]
```typescript
import { parseDegreesDecimalMinutes } from '@accelint/geo';
const [tokens, errors] = parseDegreesDecimalMinutes('LATLON', '90° 0\' S, 180° 0\' W');
// tokens: ['90', '0', 'S', '/', '180', '0', 'W']
// errors: []
```
### Example: Negative values convert to bearings [#example-negative-values-convert-to-bearings]
```typescript
import { parseDegreesDecimalMinutes } from '@accelint/geo';
const [tokens, errors] = parseDegreesDecimalMinutes('LATLON', '-40 26 / 79 58');
// tokens: ['40', '26', 'S', '/', '79', '58', 'E']
// errors: []
```
### Example: LONLAT format [#example-lonlat-format]
```typescript
import { parseDegreesDecimalMinutes } from '@accelint/geo';
const [tokens, errors] = parseDegreesDecimalMinutes('LONLAT', '40° 26\' W, 79° 58\' N');
// tokens: ['40', '26', 'W', '/', '79', '58', 'N']
// errors: []
```
### Example: Invalid seconds indicator [#example-invalid-seconds-indicator]
```typescript
import { parseDegreesDecimalMinutes } from '@accelint/geo';
const [tokens, errors] = parseDegreesDecimalMinutes('LATLON', '89° 59.999" N, 179° 59.999"');
// tokens: []
// errors: ['[ERROR] Seconds indicator (") not valid in Degree Decimal Minutes.']
```
### Example: Minutes out of range [#example-minutes-out-of-range]
```typescript
import { parseDegreesDecimalMinutes } from '@accelint/geo';
const [tokens, errors] = parseDegreesDecimalMinutes('LATLON', '40° 60\' N, 79° 0\' W');
// tokens: []
// errors: ['[ERROR] Minutes value (60) exceeds max value (59.999999999).']
```
### Example: Decimal degrees value error [#example-decimal-degrees-value-error]
```typescript
import { parseDegreesDecimalMinutes } from '@accelint/geo';
const [tokens, errors] = parseDegreesDecimalMinutes('LATLON', '40.5° 26\' N, 79° 58\' W');
// tokens: []
// errors: ['[ERROR] Degrees value (40.5) must not include decimal value.']
```
### Example: Flexible separators [#example-flexible-separators]
```typescript
import { parseDegreesDecimalMinutes } from '@accelint/geo';
// Comma separator
parseDegreesDecimalMinutes('LATLON', '40° 26\' N, 79° 58\' W');
// Slash separator
parseDegreesDecimalMinutes('LATLON', '40° 26\' N / 79° 58\' W');
// Space separator
parseDegreesDecimalMinutes('LATLON', '40° 26\' N 79° 58\' W');
```
> **Good to know:** The parser accepts various separators (comma, slash, or space) between coordinate components. Negative signs on degrees are automatically converted to appropriate bearing directions (S for negative latitude, W for negative longitude).
> **Good to know:** Degrees Decimal Minutes format requires integer degrees (no decimal component in degrees). The decimal component goes in minutes. Use `parseDecimalDegrees` for decimal degree values or `parseDegreesMinutesSeconds` for full DMS notation.
## Related [#related]
* [formatDegreesDecimalMinutes](./formatter.md) - Format coordinates in Degrees Decimal Minutes notation
* [parseDecimalDegrees](../decimal-degrees/parser.md) - Parse Decimal Degrees coordinate strings
* [parseDegreesMinutesSeconds](../degrees-minutes-seconds/parser.md) - Parse DMS coordinate strings
* [createCoordinate](../../coordinate.md) - Create coordinate with automatic parsing
# formatDegreesMinutesSeconds (/docs/packages/geo/coordinates/latlon/degrees-minutes-seconds/formatter)
Formats latitude/longitude coordinates in degrees minutes seconds (DMS) notation with configurable separators and ordinal directions.
## Usage [#usage]
```typescript
import { formatDegreesMinutesSeconds } from '@accelint/geo';
// Basic usage with default separator
formatDegreesMinutesSeconds([37.7749, -122.4194]);
// '37° 46\' 29.64″ N, 122° 25\' 9.84″ W'
```
## Reference [#reference]
```typescript
function formatDegreesMinutesSeconds(
coordinates: [number, number],
config?: FormatConfig
): string
interface FormatConfig {
separator?: string;
}
```
### Parameters [#parameters]
| Parameter | Type | Description |
| ------------- | ------------------------- | --------------------------------------------------------- |
| `coordinates` | `[number, number]` | Tuple of \[latitude, longitude] values in decimal degrees |
| `config` | `FormatConfig` (optional) | Formatting configuration with optional separator |
### Returns [#returns]
Returns formatted coordinate string in degrees minutes seconds format with degree symbols, minute symbols, decimal seconds (2 decimal places), and ordinal directions (N/S/E/W).
## Examples [#examples]
### Example: Basic formatting [#example-basic-formatting]
```typescript
import { formatDegreesMinutesSeconds } from '@accelint/geo';
formatDegreesMinutesSeconds([37.7749, -122.4194]);
// '37° 46\' 29.64″ N, 122° 25\' 9.84″ W'
```
### Example: Custom separator [#example-custom-separator]
```typescript
import { formatDegreesMinutesSeconds } from '@accelint/geo';
formatDegreesMinutesSeconds([37.7749, -122.4194], { separator: ' / ' });
// '37° 46\' 29.64″ N / 122° 25\' 9.84″ W'
```
### Example: Northern and Eastern hemispheres [#example-northern-and-eastern-hemispheres]
```typescript
import { formatDegreesMinutesSeconds } from '@accelint/geo';
formatDegreesMinutesSeconds([48.8566, 2.3522]);
// '48° 51\' 23.76″ N, 2° 21\' 7.92″ E'
```
### Example: Southern hemisphere [#example-southern-hemisphere]
```typescript
import { formatDegreesMinutesSeconds } from '@accelint/geo';
formatDegreesMinutesSeconds([-33.8688, 151.2093]);
// '33° 52\' 7.68″ S, 151° 12\' 33.48″ E'
```
### Example: Whole degrees (zero minutes and seconds) [#example-whole-degrees-zero-minutes-and-seconds]
```typescript
import { formatDegreesMinutesSeconds } from '@accelint/geo';
formatDegreesMinutesSeconds([45.0, -90.0]);
// '45° 0\' 0.00″ N, 90° 0\' 0.00″ W'
```
### Example: Exact minutes (zero seconds) [#example-exact-minutes-zero-seconds]
```typescript
import { formatDegreesMinutesSeconds } from '@accelint/geo';
formatDegreesMinutesSeconds([40.5, -74.0]);
// '40° 30\' 0.00″ N, 74° 0\' 0.00″ W'
```
### Example: Boundary values [#example-boundary-values]
```typescript
import { formatDegreesMinutesSeconds } from '@accelint/geo';
// Maximum latitude
formatDegreesMinutesSeconds([90, 0]);
// '90° 0\' 0.00″ N, 0° 0\' 0.00″ E'
// International Date Line
formatDegreesMinutesSeconds([0, 180]);
// '0° 0\' 0.00″ N, 180° 0\' 0.00″ E'
```
> **Good to know:** The formatter always uses 2 decimal places for seconds, providing precision to approximately 30 centimeters. Negative latitude values are converted to Southern hemisphere (S), and negative longitude values to Western hemisphere (W).
> **Good to know:** DMS format is the traditional notation used in cartography and surveying. While more verbose than DD or DDM, it provides intuitive subdivision of angular measurements into base-60 units.
> **Good to know:** The second symbol used is the Unicode double prime (″), not a quotation mark. Minutes use the prime symbol (').
## Related [#related]
* [parseDegreesMinutesSeconds](./parser.md) - Parse DMS coordinate strings
* [formatDecimalDegrees](../decimal-degrees/formatter.md) - Format coordinates in DD notation
* [formatDegreesDecimalMinutes](../degrees-decimal-minutes/formatter.md) - Format coordinates in DDM notation
* [createCoordinate](../../coordinate.md) - Create coordinate with automatic format conversion
# parseDegreesMinutesSeconds (/docs/packages/geo/coordinates/latlon/degrees-minutes-seconds/parser)
## Usage [#usage]
```typescript
import { parseDegreesMinutesSeconds } from '@accelint/geo';
// Parse with explicit format
const [tokens, errors] = parseDegreesMinutesSeconds('LATLON', '37° 46\' 29.64" N / 122° 25\' 9.84" W');
// tokens: ['37', '46', '29.64', 'N', '/', '122', '25', '9.84', 'W']
// errors: []
```
## Reference [#reference]
```typescript
function parseDegreesMinutesSeconds(
format: 'LATLON' | 'LONLAT',
input: string
): [tokens: string[], errors: string[]]
```
### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ---------------------- | ------------------------------ |
| `format` | `'LATLON' \| 'LONLAT'` | Expected format ordering |
| `input` | `string` | Raw coordinate string to parse |
### Returns [#returns]
Returns a tuple containing:
* `tokens`: Array of parsed coordinate components (degrees, minutes, seconds, bearings, dividers)
* `errors`: Array of validation error messages (empty if valid)
### Validation Rules [#validation-rules]
Validates that:
* Degree values are integers (no decimal component allowed in degrees)
* Minute values are integers in valid range (0-59)
* Second values are in valid range (0-59.999...)
* Bearing indicators match the specified format (N/S for latitude, E/W for longitude)
* Negative signs on degrees are converted to appropriate bearing directions
## Examples [#examples]
### Example: Basic parsing [#example-basic-parsing]
```typescript
import { parseDegreesMinutesSeconds } from '@accelint/geo';
const [tokens, errors] = parseDegreesMinutesSeconds('LATLON', '37° 46\' 29.64" N / 122° 25\' 9.84" W');
// tokens: ['37', '46', '29.64', 'N', '/', '122', '25', '9.84', 'W']
// errors: []
```
### Example: Without degree/minute/second symbols [#example-without-degreeminutesecond-symbols]
```typescript
import { parseDegreesMinutesSeconds } from '@accelint/geo';
const [tokens, errors] = parseDegreesMinutesSeconds('LATLON', '45 30 15.23 N, 122 25 9.84 W');
// tokens: ['45', '30', '15.23', 'N', '/', '122', '25', '9.84', 'W']
// errors: []
```
### Example: Maximum valid values [#example-maximum-valid-values]
```typescript
import { parseDegreesMinutesSeconds } from '@accelint/geo';
const [tokens, errors] = parseDegreesMinutesSeconds('LATLON', '90° 0\' 0" S, 180° 0\' 0" W');
// tokens: ['90', '0', '0', 'S', '/', '180', '0', '0', 'W']
// errors: []
```
### Example: Negative values convert to bearings [#example-negative-values-convert-to-bearings]
```typescript
import { parseDegreesMinutesSeconds } from '@accelint/geo';
const [tokens, errors] = parseDegreesMinutesSeconds('LATLON', '-40 26 30 / 79 58 15');
// tokens: ['40', '26', '30', 'S', '/', '79', '58', '15', 'E']
// errors: []
```
### Example: LONLAT format [#example-lonlat-format]
```typescript
import { parseDegreesMinutesSeconds } from '@accelint/geo';
const [tokens, errors] = parseDegreesMinutesSeconds('LONLAT', '122° 25\' 9.84" W / 37° 46\' 29.64" N');
// tokens: ['122', '25', '9.84', 'W', '/', '37', '46', '29.64', 'N']
// errors: []
```
### Example: Seconds out of range [#example-seconds-out-of-range]
```typescript
import { parseDegreesMinutesSeconds } from '@accelint/geo';
const [tokens, errors] = parseDegreesMinutesSeconds('LATLON', '40° 26\' 60" N, 79° 0\' 0" W');
// tokens: []
// errors: ['[ERROR] Seconds value (60) exceeds max value (59.999999999).']
```
### Example: Minutes out of range [#example-minutes-out-of-range]
```typescript
import { parseDegreesMinutesSeconds } from '@accelint/geo';
const [tokens, errors] = parseDegreesMinutesSeconds('LATLON', '40° 60\' 0" N, 79° 0\' 0" W');
// tokens: []
// errors: ['[ERROR] Minutes value (60) exceeds max value (59).']
```
### Example: Decimal degrees value error [#example-decimal-degrees-value-error]
```typescript
import { parseDegreesMinutesSeconds } from '@accelint/geo';
const [tokens, errors] = parseDegreesMinutesSeconds('LATLON', '40.5° 26\' 30" N, 79° 58\' 0" W');
// tokens: []
// errors: ['[ERROR] Degrees value (40.5) must not include decimal value.']
```
### Example: Flexible separators [#example-flexible-separators]
```typescript
import { parseDegreesMinutesSeconds } from '@accelint/geo';
// Comma separator
parseDegreesMinutesSeconds('LATLON', '40° 26\' 30" N, 79° 58\' 0" W');
// Slash separator
parseDegreesMinutesSeconds('LATLON', '40° 26\' 30" N / 79° 58\' 0" W');
// Space separator
parseDegreesMinutesSeconds('LATLON', '40° 26\' 30" N 79° 58\' 0" W');
```
> **Good to know:** The parser accepts various separators (comma, slash, or space) between coordinate components. Negative signs on degrees are automatically converted to appropriate bearing directions (S for negative latitude, W for negative longitude).
> **Good to know:** Degrees Minutes Seconds format requires integer degrees and integer minutes. Only seconds may contain decimal values. Use `parseDecimalDegrees` for decimal degree values or `parseDegreesDecimalMinutes` for DDM notation.
## Related [#related]
* [formatDegreesMinutesSeconds](./formatter.md) - Format coordinates in Degrees Minutes Seconds notation
* [parseDecimalDegrees](../decimal-degrees/parser.md) - Parse Decimal Degrees coordinate strings
* [parseDegreesDecimalMinutes](../degrees-decimal-minutes/parser.md) - Parse DDM coordinate strings
* [createCoordinate](../../coordinate.md) - Create coordinate with automatic parsing