npm package: @pagelume/component-sdk
Description: Official SDK for building Pagelume components
Author: Pagelume
Latest version: 1.9.5

# Pagelume Component SDK

The official SDK for building modular, reusable web components for the Pagelume platform.

## Features

-   **Component Scaffolding**: Quickly create new components with a standardized structure.
-   **Handlebars Templating**: Full support for Handlebars with a rich set of custom helpers.
-   **SCSS Asset Pipeline**: Automatic compilation of SCSS to CSS with minification and source maps.
-   **Global Style System**: Access a shared library of SCSS variables, mixins, and utility classes.
-   **Vendor Script Management**: Easily integrate and manage popular third-party libraries.
-   **Live Development Server**: Instant component previews and hot-reloading powered by Vite.
-   **Robust CLI**: A powerful command-line interface to streamline your development workflow.

## Installation

```bash
npm install @pagelume/component-sdk
```

## Quick Start

### 1. Choose Your Setup Location

**Option A: Create a new project folder (recommended)**

```bash
mkdir my-components
cd my-components
```

**Option B: Use an existing folder**

```bash
# Stay in your current directory
```

### 2. Initialize the Project

Run the `init` command to scaffold your project. This creates a `package.json` and all necessary configuration files.

```bash
npx @pagelume/component-sdk init
```

> **Note:** If you haven't installed the package globally, `npx` will prompt you to install it. This is expected. Type `y` to proceed.

### 3. Install Dependencies

Install the required local dependencies.

```bash
npm install
```

### 4. Start the Development Server

Run the `serve` command to start the Vite development server and view your component gallery.

```bash
pagelume-cli serve
```

Alternatively, you can use the npm script:

```bash
npm run dev
```

Visit `http://localhost:3000` (or the port you specify) to see your components.

## Component Structure

Each component follows a standardized structure:

```
components/
├── [component-type]/
│   └── [variation-name]/
│       ├── index.html      # Handlebars template for the component
│       ├── meta.json       # Component metadata (name, fields, etc.)
│       └── assets/
│           ├── css/
│           │   ├── styles.css      # Compiled CSS (auto-generated)
│           │   └── styles.min.css  # Minified CSS (if --minify is used)
│           ├── scss/
│           │   └── styles.scss     # Your component's source SCSS
│           ├── js/
│           │   ├── script.js       # Your component's source JavaScript
│           │   └── script.min.js   # Minified JS (if --minify is used)
│           └── img/
│               └── ...             # Component-specific images
```

### Example `meta.json`

```json
{
  "name": "Simple Hero",
  "type": "hero",
  "variation": "simple-hero",
  "description": "A basic hero section with a title and subtitle.",
  "version": "1.0.0",
  "vendors": ["gsap"],
  "fields": [
    {
      "name": "title",
      "type": "text",
      "label": "Title",
      "default": "Welcome to Pagelume"
    },
    {
      "name": "subtitle",
      "type": "text",
      "label": "Subtitle",
      "default": "Build amazing components with ease."
    }
  ]
}
```

## Global Assets

### SCSS Variables & Mixins

Import global styles into your component's SCSS files to access shared variables and mixins.

```scss
// Import from the installed SDK package
@import '@pagelume/component-sdk/global-assets/scss/variables';
@import '@pagelume/component-sdk/global-assets/scss/mixins';

.my-component {
  color: $primary-color;
  @include container;
  
  @include md-up {
    padding: $spacer * 2;
  }
}
```

### Vendor Scripts

Add vendor dependencies to a component by including the `data-pagelume-vendors` attribute in your HTML. The loader will automatically handle script and stylesheet injection.

```html
<div data-pagelume-vendors="jquery,slick">
  <!-- Your component markup -->
</div>
```

**Available Vendors:**

-   `jquery` - jQuery 3.7.1
-   `bootstrap` - Bootstrap 5.3.3
-   `slick` - Slick Carousel 1.8.1
-   `gsap` - GSAP Animation 3.12.5
-   `gsapScrollTrigger` - GSAP ScrollTrigger Plugin
-   `aos` - Animate On Scroll 2.3.4
-   `swiper` - Swiper.js 11.x
-   `isotope` - Isotope Layout 3.x
-   `lightbox2` - Lightbox2 2.11.4

## Handlebars Helpers

The SDK provides a rich set of custom Handlebars helpers to use in your `.html` templates.

### Comparison Helpers

-   `{{#if (eq value1 value2)}}` - Equal
-   `{{#if (ne value1 value2)}}` - Not equal
-   `{{#if (lt value1 value2)}}` - Less than
-   `{{#if (gt value1 value2)}}` - Greater than
-   `{{#if (lte value1 value2)}}` - Less than or equal
-   `{{#if (gte value1 value2)}}` - Greater than or equal
-   `{{#if (and cond1 cond2)}}` - Logical AND
-   `{{#if (or cond1 cond2)}}` - Logical OR

### String Helpers

-   `{{uppercase text}}` - Convert to uppercase
-   `{{lowercase text}}` - Convert to lowercase
-   `{{capitalize text}}` - Capitalize the first letter
-   `{{truncate text 50}}` - Truncate text to a specific length
-   `{{slugify text}}` - Convert text to a URL-friendly slug
-   `{{replace text "find" "replace"}}` - Replace all occurrences of a string

### Array Helpers

-   `{{length array}}` - Get the length of an array
-   `{{first array}}` - Get the first item from an array
-   `{{last array}}` - Get the last item from an array
-   `{{join array ", "}}` - Join array items into a string
-   `{{#if (contains array value)}}` - Check if an array contains a value
-   `{{#each (limit array 5)}}` - Loop through a subset of an array

### Math Helpers

-   `{{add num1 num2}}` - Addition
-   `{{subtract num1 num2}}` - Subtraction
-   `{{multiply num1 num2}}` - Multiplication
-   `{{divide num1 num2}}` - Division
-   `{{mod num1 num2}}` - Modulo
-   `{{round num}}` - Round to the nearest integer
-   `{{floor num}}` - Round down
-   `{{ceil num}}` - Round up

### Date Helpers
- `{{formatDate date "YYYY-MM-DD"}}` - Format a date
- `{{relativeTime date}}` - Display time relative to now (e.g., "2 hours ago")

### Utility Helpers
- `{{json object}}` - Stringify an object into a JSON string for debugging
- `{{default value "fallback"}}` - Provide a fallback value
- `{{random min max}}` - Generate a random number within a range

## CLI Commands

You can run commands using `npx @pagelume/component-sdk <command>` or, if installed locally, the shorter `pagelume-cli <command>`.

| Command | Description | Options |
| :--- | :--- | :--- |
| `init` | Initialize a new component project. | |
| `create` | Launch an interactive prompt to create a new component. | |
| `list` | List all existing components in the project. | |
| `build` | Compile and build assets for all components. | `--minify`, `--source-map`, `--watch` |
| `serve` | Start the development server with a component gallery. | `--port <number>` |
| `update`| Update project files to match the latest SDK version. | |


### Build Command Details
The `build` command compiles SCSS and JavaScript assets.

-   **`pagelume-cli build`**: Compiles assets for development.
-   **`pagelume-cli build --minify`**: Compiles and minifies assets for production.
-   **`pagelume-cli build --source-map`**: Generates source maps for debugging.
-   **`pagelume-cli build --watch`**: Automatically rebuilds assets when files change.

You can also use the npm scripts defined in your `package.json`:
- `npm run build:components`
- `npm run build:components:min`
- `npm run build:components:prod`
- `npm run build:components:watch`

## API Usage

For advanced use cases, you can use the SDK's core modules directly in your Node.js scripts.

### ComponentBuilder

Builds all component data from source files.

```javascript
import { ComponentBuilder } from '@pagelume/component-sdk';

const builder = new ComponentBuilder({
  sourcePath: './components',
  outputPath: './dist'
});

const components = await builder.build();
console.log(components);
```

### ComponentRenderer

Renders a single component's Handlebars template to HTML.

```javascript
import { ComponentRenderer } from '@pagelume/component-sdk';

// Assume 'component' is an object from the builder result
const renderer = new ComponentRenderer();
const html = renderer.render(component, {
  data: { title: 'Hello from Renderer' },
  inlineStyles: true, // Optional: inline compiled CSS
  inlineScripts: true // Optional: inline compiled JS
});

console.log(html);
```

### Vite Plugin

Integrate the Pagelume component system directly into a Vite project.

```javascript
// vite.config.js
import { defineConfig } from 'vite';
import { VitePlugin } from '@pagelume/component-sdk';

export default defineConfig({
  plugins: [
    VitePlugin({
      componentsDir: 'components', // Directory where your components are located
      enableHMR: true // Enable Hot Module Replacement
    })
  ]
});
```

## Development

To contribute to the SDK itself:

```bash
# Clone the repository
git clone https://github.com/ImranBug/pagelume_component-sdk.git
cd pagelume_component-sdk

# Install dependencies
npm install

# Build the SDK and CLI
npm run build && npm run build:cli

# To test your local changes in another project, use npm link:
npm link
cd ../my-test-project
npm link @pagelume/component-sdk
```

## License

MIT

## Support

For issues, feature requests, or contributions, please visit our [GitHub repository](https://github.com/ImranBug/pagelume_component-sdk).