npm package: @maxolib/tsl-lib
Description: TypeScript library for Three.js Shader Language (TSL) utilities for React Three Fiber projects
Author: maxolib
Latest version: 0.1.0

# TSL-Lib

A comprehensive TypeScript library for **Three.js Shader Language (TSL)** utilities designed for **React Three Fiber** projects. This library provides a collection of shader functions including easing, noise, mathematical operations, color utilities, and pattern generators.

## 🚀 Features

- **Easing Functions**: 30+ easing functions (quad, cubic, sine, expo, elastic, bounce, etc.)
- **Noise Functions**: Value noise, gradient noise, simplex noise, Voronoi, FBM, turbulence, and cellular noise
- **Math Utilities**: Remap, smoothstep, rotate2D, SDFs (circle, rectangle, hexagon, star), and more
- **Color Functions**: RGB/HSV/HSL conversions, hue/saturation/brightness adjustments, blend modes
- **Pattern Generators**: Grid, checkerboard, stripes, dots, waves, bricks, Voronoi cells, Truchet tiles

## 📦 Installation

```bash
npm install tsl-lib
# or
yarn add tsl-lib
# or
pnpm add tsl-lib
```

**Peer Dependencies:**

This library requires `three` version 0.160.0 or higher (with TSL support).

```bash
npm install three@latest
```

## 🎯 Usage

### Basic Example

```typescript
import { useRef } from 'react';
import { Canvas, useFrame } from '@react-three/fiber';
import { float, uniform, vec2, vec4, Fn } from 'three/tsl';
import { MeshBasicNodeMaterial } from 'three/webgpu';
import { easeInOutCubic, valueNoise2D, remap } from 'tsl-lib';

function AnimatedMesh() {
  const materialRef = useRef();
  const time = uniform(0);

  useFrame((state) => {
    time.value = state.clock.elapsedTime;
  });

  // Create a custom shader using TSL
  const material = new MeshBasicNodeMaterial();
  
  material.colorNode = Fn(() => {
    const uv = vec2(/* your uv coordinates */);
    const t = easeInOutCubic(time.value.mod(1.0));
    const noise = valueNoise2D(uv.mul(5.0).add(time.value));
    const color = remap(noise, float(0.0), float(1.0), float(0.2), float(0.8));
    
    return vec4(color, color, color, 1.0);
  })();

  return (
    <mesh>
      <boxGeometry />
      <primitive object={material} attach="material" />
    </mesh>
  );
}

export default function App() {
  return (
    <Canvas>
      <AnimatedMesh />
    </Canvas>
  );
}
```

### Easing Functions Example

```typescript
import { easeInOutQuad, easeInOutElastic, easeOutBounce } from 'tsl-lib/easing';
import { float } from 'three/tsl';

// In your shader code
const t = float(time).fract(); // 0 to 1
const smoothValue = easeInOutQuad(t);
const elasticValue = easeInOutElastic(t);
const bounceValue = easeOutBounce(t);
```

### Noise Functions Example

```typescript
import { 
  valueNoise2D, 
  gradientNoise2D, 
  fbm2D, 
  voronoiNoise2D 
} from 'tsl-lib/noise';
import { vec2 } from 'three/tsl';

const uv = vec2(/* coordinates */);

// Simple noise
const noise1 = valueNoise2D(uv.mul(10.0));

// Fractal Brownian Motion
const fbm = fbm2D(uv, 6, 2.0, 0.5); // 6 octaves

// Voronoi
const voronoi = voronoiNoise2D(uv.mul(5.0));
```

### Math Utilities Example

```typescript
import { remap, rotate2D, circleSDF, smootherstep } from 'tsl-lib/math';
import { vec2, float } from 'three/tsl';

const uv = vec2(/* coordinates */);

// Remap value from one range to another
const remapped = remap(uv.x, float(0.0), float(1.0), float(-1.0), float(1.0));

// Rotate point
const rotated = rotate2D(uv, float(Math.PI / 4));

// Signed distance function for circle
const sdf = circleSDF(uv, vec2(0.5, 0.5), float(0.2));
const circle = smootherstep(float(-0.01), float(0.01), sdf);
```

### Color Functions Example

```typescript
import { 
  rgbToHsv, 
  hsvToRgb, 
  adjustHue, 
  adjustSaturation,
  overlay 
} from 'tsl-lib/color';
import { vec3 } from 'three/tsl';

const baseColor = vec3(0.8, 0.3, 0.5);

// Convert to HSV and adjust
const hsv = rgbToHsv(baseColor);
const adjustedColor = adjustHue(baseColor, float(0.1));
const saturated = adjustSaturation(baseColor, float(1.5));

// Blend modes
const blendColor = vec3(0.2, 0.6, 0.9);
const result = overlay(baseColor, blendColor);
```

### Pattern Generators Example

```typescript
import { 
  checkerboard, 
  concentricCircles, 
  voronoiCells,
  truchetTiles 
} from 'tsl-lib/patterns';
import { vec2 } from 'three/tsl';

const uv = vec2(/* coordinates */);

const checker = checkerboard(uv, float(10.0));
const circles = concentricCircles(uv, vec2(0.5, 0.5), float(20.0));
const cells = voronoiCells(uv, float(5.0));
const truchet = truchetTiles(uv, float(8.0));
```

## 📚 API Reference

### Easing Functions

All easing functions take a single parameter `t` (0-1) and return an eased value:

- `easeLinear`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`
- `easeInCubic`, `easeOutCubic`, `easeInOutCubic`
- `easeInQuart`, `easeOutQuart`, `easeInOutQuart`
- `easeInQuint`, `easeOutQuint`, `easeInOutQuint`
- `easeInSine`, `easeOutSine`, `easeInOutSine`
- `easeInExpo`, `easeOutExpo`, `easeInOutExpo`
- `easeInCirc`, `easeOutCirc`, `easeInOutCirc`
- `easeInBack`, `easeOutBack`, `easeInOutBack`
- `easeInElastic`, `easeOutElastic`, `easeInOutElastic`
- `easeInBounce`, `easeOutBounce`, `easeInOutBounce`

### Noise Functions

- `random(vec2)` - Simple random from 2D coordinates
- `valueNoise2D(vec2)` - Value noise
- `gradientNoise2D(vec2)` - Perlin-like gradient noise
- `simplexNoise2D(vec2)` - Simplex noise
- `voronoiNoise2D(vec2)` - Voronoi/cellular noise
- `fbm2D(vec2, octaves, lacunarity, gain)` - Fractal Brownian Motion
- `turbulence2D(vec2, octaves)` - Turbulence noise
- `cellularNoise2D(vec2)` - Cellular/Worley noise

### Math Utilities

- `remap(value, inMin, inMax, outMin, outMax)` - Remap value between ranges
- `smootherstep(edge0, edge1, x)` - Improved smoothstep
- `rotate2D(point, angle)` - Rotate 2D point
- `circleSDF(point, center, radius)` - Circle signed distance
- `rectangleSDF(point, center, size)` - Rectangle signed distance
- `hexagonSDF(point, radius)` - Hexagon signed distance
- And many more...

### Color Functions

- `rgbToHsv(rgb)`, `hsvToRgb(hsv)` - Color space conversions
- `rgbToHsl(rgb)`, `hslToRgb(hsl)` - HSL conversions
- `adjustHue(rgb, adjustment)` - Adjust hue
- `adjustSaturation(rgb, adjustment)` - Adjust saturation
- `adjustBrightness(rgb, adjustment)` - Adjust brightness
- Blend modes: `overlay`, `screen`, `colorDodge`, `colorBurn`, `softLight`

### Pattern Generators

- `gridPattern(uv, scale)` - Grid lines
- `checkerboard(uv, scale)` - Checkerboard pattern
- `stripes(uv, scale)` - Stripe pattern
- `concentricCircles(uv, center, scale)` - Concentric circles
- `dots(uv, scale, radius)` - Dot pattern
- `voronoiCells(uv, scale)` - Voronoi cells
- `truchetTiles(uv, scale)` - Truchet tile pattern

## 🛠️ Development

```bash
# Install dependencies
npm install

# Build the library
npm run build

# Watch mode for development
npm run dev

# Type checking
npm run type-check
```

## 🌟 Use Cases

- Procedural textures and materials
- Animated shader effects
- Particle systems
- Post-processing effects
- Dynamic backgrounds
- Generative art
- Game development
- WebGL/WebGPU visualizations

## 📖 Examples

Check out the `/examples` directory (coming soon) for complete working examples with React Three Fiber.

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT © [Your Name]

## 🔗 Links

- [Three.js Documentation](https://threejs.org/docs/)
- [React Three Fiber](https://docs.pmnd.rs/react-three-fiber)
- [Three.js Shading Language (TSL)](https://github.com/mrdoob/three.js/wiki/Three.js-Shading-Language)

## 💡 Tips

1. **Performance**: TSL functions are compiled to GLSL/WGSL, so they run on the GPU
2. **Type Safety**: Full TypeScript support with proper type definitions
3. **Tree Shaking**: Import only what you need for optimal bundle size
4. **Composability**: Combine multiple functions to create complex effects

---

Built with ❤️ for the Three.js and React Three Fiber community