npm package: @made-by-sea/snippets-database
Description: A collection of reusable components and utilities for React, Next.js, and SvelteKit by Made by Sea
Author: Made by Sea
Latest version: 1.0.1

# @made-by-sea/snippets-database

A collection of reusable components and utilities for React, Next.js, and SvelteKit by [Made by Sea](https://madebysea.com).

[![npm version](https://badge.fury.io/js/%40made-by-sea%2Fsnippets-database.svg)](https://badge.fury.io/js/%40made-by-sea%2Fsnippets-database)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## About

This is a **public npm package** created by Made by Sea for our internal projects, but made available for the community to use. It provides cross-framework components and utilities that work seamlessly with React, Next.js, and SvelteKit.

## Installation

```bash
npm install @made-by-sea/snippets-database
```

or

```bash
yarn add @made-by-sea/snippets-database
```

## Framework Support

This package supports multiple frameworks with framework-specific entry points:

- **Main entry**: Framework-agnostic utilities
- **React/Next.js**: `@made-by-sea/snippets-database/react`
- **SvelteKit**: `@made-by-sea/snippets-database/svelte`
- **Utils only**: `@made-by-sea/snippets-database/utils`

## Usage Examples

### React/Next.js

#### SeaImage Component

```tsx
import { SeaImage } from '@made-by-sea/snippets-database/react';

function MyComponent() {
  return (
    <SeaImage
      src="/path/to/image.jpg"
      alt="Description"
      width={300}
      height={200}
      placeholderHex="#f0f0f0"
    />
  );
}
```

#### useIsMobile Hook

```tsx
import { useIsMobile } from '@made-by-sea/snippets-database/react';

function MyComponent() {
  const isMobile = useIsMobile();

  return <div>{isMobile ? 'Mobile view' : 'Desktop view'}</div>;
}
```

### SvelteKit

#### SeaImage Component

```svelte
<script>
  import SeaImage from '@made-by-sea/snippets-database/svelte';
</script>

<SeaImage
  src="/path/to/image.jpg"
  alt="Description"
  width={300}
  height={200}
  placeholderHex="#f0f0f0"
/>
```

#### IsMobile Store

```svelte
<script>
  import { createIsMobileStore } from '@made-by-sea/snippets-database/svelte';
  import { onDestroy } from 'svelte';

  const { store: isMobile, destroy } = createIsMobileStore();

  onDestroy(() => {
    if (destroy) {
      destroy();
    }
  });
</script>

<div>
  {#if $isMobile}
    Mobile view
  {:else}
    Desktop view
  {/if}
</div>
```

#### SeaImage Utilities

```svelte
<script>
  import { createImageConfig, handleImageLoad } from '@made-by-sea/snippets-database/svelte';
  import { onMount } from 'svelte';

  let hasPlaceholder = true;
  let imageConfig;

  onMount(() => {
    imageConfig = createImageConfig({
      src: '/path/to/image.jpg',
      alt: 'Description',
      width: 300,
      height: 200,
      placeholderHex: '#f0f0f0'
    });
  });
</script>

<div style={imageConfig?.containerStyle}>
  {#if hasPlaceholder}
    <div class="placeholder" style={imageConfig?.placeholderStyle}>
      <img src={imageConfig?.placeholderImage} alt={imageConfig?.alt} />
    </div>
  {/if}

  <img
    src={imageConfig?.src}
    alt={imageConfig?.alt}
    width={imageConfig?.width}
    height={imageConfig?.height}
    on:load={handleImageLoad(() => hasPlaceholder = false)}
  />
</div>
```

### Framework-Agnostic Utilities

#### Basic Utilities

```tsx
import {
  isMobile,
  getViewportWidth,
  getViewportHeight,
  NormalizeString,
  UniqueIdentifier,
} from '@made-by-sea/snippets-database';

// Mobile detection
const mobile = isMobile(); // boolean
const width = getViewportWidth(); // number
const height = getViewportHeight(); // number

// String normalization
const normalized = NormalizeString('Hello World!'); // "hello-world"

// Unique identifier
const id = UniqueIdentifier(); // Returns a unique number
```

#### Image Utilities

```tsx
import {
  getPlaceholderImage,
  getDefaultPlaceholder,
  getImagePlaceholder,
} from '@made-by-sea/snippets-database';

// Get placeholder images
const defaultPlaceholder = getDefaultPlaceholder();
const randomPlaceholder = getImagePlaceholder();
const customPlaceholder = getPlaceholderImage({ placeholderHex: '#f0f0f0' });
```

## Component Props

### SeaImage (React/Next.js)

- `src`: Image source URL
- `alt`: Alt text for the image
- `width`: Image width (optional)
- `height`: Image height (optional)
- `layout`: Next.js Image layout prop (optional)
- `classNameProp`: CSS class name (optional)
- `placeholderHex`: Custom placeholder color in hex format (optional)
- `objectFit`: CSS object-fit property (optional)

### SeaImage (SvelteKit)

- `src`: Image source URL
- `alt`: Alt text for the image
- `width`: Image width (optional)
- `height`: Image height (optional)
- `className`: CSS class name (optional)
- `placeholderHex`: Custom placeholder color in hex format (optional)
- `objectFit`: CSS object-fit property (optional)
- `loading`: Image loading strategy ('lazy' | 'eager')
- `decoding`: Image decoding strategy ('async' | 'sync' | 'auto')

## Development

### For Team Members

- **[Quick Start Guide](./QUICK_START.md)** - Get up and running in 5 minutes
- **[Full Development Guide](./DEVELOPMENT.md)** - Comprehensive development documentation

### Prerequisites

- Node.js 16+
- npm or yarn

### Setup

```bash
# Install dependencies
npm install

# Build the package
npm run build

# Run type checking
npm run type-check

# Run linting
npm run lint
```

### Building

The package uses Rollup for building. The build process creates:

- CommonJS build (`dist/index.js`)
- ES Module build (`dist/index.esm.js`)
- TypeScript declarations (`dist/index.d.ts`)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

### Usage Terms

- ✅ **Free to use** in personal and commercial projects
- ✅ **Free to modify** and distribute
- ✅ **Free to use** in proprietary software
- ✅ **Attribution required** (include license notice)
- ❌ **No warranty** provided

## Contributing

### For Team Members

- See [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed development guidelines
- See [QUICK_START.md](./QUICK_START.md) for quick setup instructions

### For External Users

While the source code is not open for external contributions, we welcome:

- **Bug reports** via GitHub issues
- **Feature requests** via GitHub issues
- **Usage questions** via GitHub discussions

### Code of Conduct

- Be respectful and inclusive
- Provide clear commit messages
- Test your changes thoroughly
- Follow the existing code style