@nasp/icons/docs/NaspScript.md

Universal design and icon system for NASP Asset Studio, with NaspScript language support.

# NaspScript Language Guide

NaspScript is a simple, human-friendly language for describing icon layouts and UI snippets for the NASP Design Kit.

## Syntax

- `icon "Name" [size N] [color #hex|name|variable]` — Render an icon with optional size and color.
- `row { ... }`, `column { ... }`, `group { ... }` — Group icons in a horizontal, vertical, or generic group.
- Variables: `let mainColor = #5865f2`
- Comments: `// ...`
- Custom commands: e.g. `spacer size 32`

## Examples

```nasp
let mainColor = #5865f2
icon Search size 32 color mainColor
row {
  icon Folder size 20
  icon File size 20
  spacer size 32
}
column {
  icon Star size 40 color yellow
  icon Heart size 40 color red
}
```

## Usage in JavaScript

```js
const script = `
let mainColor = #5865f2
icon Search size 32 color mainColor
row {
  icon User size 24
  icon Settings size 24
  spacer size 16
}`;
const html = NaspScript.parse(script, { renderIcon: NASPIcon.get });
document.getElementById('output').innerHTML = html;
```

## Usage in React

You can use the parser and inject the output as HTML:

```jsx
const html = NaspScript.parse(script, { renderIcon: NASPIcon.get });
return <div dangerouslySetInnerHTML={{ __html: html }} />;
```

## Extending NaspScript with Helpers

- Add new commands in `src/helpers/dslExtensions.js` using `registerCommand`.
- Example: add a `divider` command to insert a horizontal line.

```js
import { registerCommand } from './helpers/dslExtensions.js';
registerCommand('divider', (args, ctx) => '<hr style="margin:8px 0;">');
```

## Best Practices
- Use variables for colors and sizes to keep scripts DRY.
- Use comments to annotate your scripts.
- Combine rows, columns, and groups for complex layouts.
- Add and document your own commands for your team/project.

## Troubleshooting
- **Icons not rendering?** Make sure your icon names match those in `icons.json`.
- **Nothing appears?** Check that `NASPIcon.init()` has completed before parsing.
- **Custom commands not working?** Extend the parser logic in `src/helpers/dslExtensions.js`.

## API

- `NaspScript.parse(script, { renderIcon })` — Parses a NaspScript string and returns HTML. `renderIcon` is a function that returns SVG or HTML for an icon.

---

For more, see the [main README](../README.md) or open an issue to suggest features!