@bookklik/senangstart-icons 1.0.8 → 1.0.12

package/.agent/skills/build-scripts/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: Build Scripts
+description: Understanding and modifying the SenangStart Icons build pipeline
+---
+
+# Build Scripts Skill
+
+This skill covers the build pipeline scripts for SenangStart Icons.
+
+## Build Pipeline Overview
+
+The build system consists of four scripts that run sequentially:
+
+1. `build-svgs.js` → Generates SVG files from JSON
+2. `build-css.js` → Generates CSS with mask-based icons
+3. `build-icon-docs.js` → Generates markdown documentation
+4. `webpack` → Bundles everything into dist/
+
+## Script Details
+
+### 1. build-svgs.js
+
+**Location:** `scripts/build-svgs.js`
+
+**Purpose:** Converts icons.json into individual SVG files and a JS index
+
+**Inputs:**
+- `src/icons.json`
+
+**Outputs:**
+- `src/svg/{slug}.svg` - Individual SVG files
+- `src/svg/index.js` - Export map for Webpack
+
+**Key Logic:**
+```javascript
+// Each icon generates an SVG with standard attributes
+const svgContent = `<svg viewBox="${vBox}" fill="${fl}" stroke="${strk}" stroke-width="${strkWidth}" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg">
+  <g><path d="${src}" /></g>
+</svg>`;
+```
+
+---
+
+### 2. build-css.js
+
+**Location:** `scripts/build-css.js`
+
+**Purpose:** Generates CSS using mask-image for pure-CSS icons
+
+**Inputs:**
+- `src/icons.json`
+
+**Outputs:**
+- `src/icons.css`
+
+**Key Logic:**
+```javascript
+// Base .ss class styles
+.ss {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  background-color: currentColor;
+  -webkit-mask-size: contain;
+  mask-size: contain;
+}
+
+// Each icon gets a mask-image class
+.ss-{slug} {
+  mask-image: url("data:image/svg+xml,...");
+}
+```
+
+**SVG Encoding Function:**
+```javascript
+function encodeSvg(svg) {
+  return svg
+    .replace(/"/g, "'")
+    .replace(/%/g, "%25")
+    .replace(/#/g, "%23")
+    // ... more replacements
+}
+```
+
+---
+
+### 3. build-icon-docs.js
+
+**Location:** `scripts/build-icon-docs.js`
+
+**Purpose:** Generates VitePress markdown pages for each icon
+
+**Inputs:**
+- `src/icons.json`
+
+**Outputs:**
+- `docs/icons/{slug}.md` - English icon pages
+- `docs/ms/icons/{slug}.md` - Malay icon pages
+- `docs/icons/index.md` - English gallery
+- `docs/ms/icons/index.md` - Malay gallery
+
+**Key Features:**
+- Generates SVG preview with inline SVG
+- Creates usage examples for both methods
+- Includes icon metadata (name, slug, tags)
+- Provides raw SVG code
+
+---
+
+### 4. build.js (Orchestrator)
+
+**Location:** `scripts/build.js`
+
+**Purpose:** Runs all build steps in sequence
+
+**Execution Order:**
+```javascript
+execSync('node scripts/build-svgs.js');
+execSync('node scripts/build-css.js');
+execSync('node scripts/build-icon-docs.js');
+execSync('npx webpack --mode production');
+```
+
+## Modifying Build Scripts
+
+### Adding New Icon Properties
+
+1. Update `icons.json` schema documentation
+2. Modify `build-svgs.js` to use new property
+3. Modify `build-css.js` if CSS output changes
+4. Update `build-icon-docs.js` to display new property
+5. Add tests in `tests/build-*.test.js`
+
+### Adding Build Outputs
+
+1. Create new build script in `scripts/`
+2. Add npm script to `package.json`
+3. Include in `scripts/build.js` orchestrator
+4. Write tests for the new script
+
+## Webpack Configuration
+
+**Location:** `webpack.config.js`
+
+**Entry:** `src/index.js`
+
+**Output:** 
+- `dist/senangstart-icon.min.js` (UMD)
+- `dist/senangstart.min.css`
+
+**Key Features:**
+- Babel transpilation for browser compatibility
+- CSS extraction and minification
+- SVG as asset/source (inline in JS)
+- Source maps enabled

package/.agent/skills/icon-development/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: Icon Development
+description: Guidelines for creating and optimizing SVG icons for SenangStart Icons
+---
+
+# Icon Development Skill
+
+This skill covers best practices for creating, optimizing, and adding icons to the library.
+
+## Icon Requirements
+
+### SVG Specifications
+
+| Property | Value |
+|----------|-------|
+| ViewBox | `0 0 24 24` (standard) |
+| Fill | `none` (stroke-based icons) |
+| Stroke | `currentColor` |
+| Stroke Width | `2` (default) |
+| Stroke Linecap | `round` |
+| Stroke Linejoin | `round` |
+
+### Path Guidelines
+
+1. **Use single path when possible** - Simpler paths are easier to render
+2. **Optimize coordinates** - Round to 1-2 decimal places
+3. **Center the icon** - Keep equal padding on all sides
+4. **Design for stroke** - Icons should look good at varying stroke widths
+
+## Creating an Icon
+
+### Step 1: Design the SVG
+
+Create in your preferred SVG editor (Figma, Illustrator, Inkscape):
+
+```svg
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" 
+     fill="none" stroke="currentColor" stroke-width="2"
+     stroke-linecap="round" stroke-linejoin="round">
+  <path d="M12 2L2 7l10 5 10-5-10-5z"/>
+</svg>
+```
+
+### Step 2: Extract the Path
+
+Copy just the `d` attribute value from the `<path>` element.
+
+### Step 3: Add to icons.json
+
+```json
+{
+  "name": "Layer Stack",
+  "slug": "layer-stack",
+  "src": "M12 2L2 7l10 5 10-5-10-5z",
+  "tags": ["layer", "stack", "design", "graphics"]
+}
+```
+
+### Step 4: Build and Verify
+
+```bash
+npm run build
+npm run docs:dev
+```
+
+## Path Optimization
+
+### Remove Unnecessary Precision
+
+Before:
+```
+M12.000000 2.000000L2.000000 7.000000
+```
+
+After:
+```
+M12 2L2 7
+```
+
+### Combine Continuous Paths
+
+Before:
+```
+M5 5L10 5 M10 5L15 5
+```
+
+After:
+```
+M5 5L15 5
+```
+
+### Use Relative Commands
+
+Before:
+```
+M5 5L10 10L15 5
+```
+
+After:
+```
+M5 5l5 5l5-5
+```
+
+## Naming Conventions
+
+### Icon Names (name field)
+- Title case with spaces: `"Arrow Left"`, `"Shopping Cart"`
+- Descriptive and concise
+
+### Slugs (slug field)
+- Lowercase with hyphens: `arrow-left`, `shopping-cart`
+- Match the name but URL-safe
+- Keep consistent with existing patterns
+
+### Tags (tags array)
+- Include broken-down name words
+- Add related concepts
+- Include action verbs if applicable
+- Example: `["arrow", "left", "back", "previous", "navigate"]`
+
+## Multi-Path Icons
+
+For complex icons with multiple paths, combine them:
+
+```json
+{
+  "name": "Complex Icon",
+  "slug": "complex-icon",
+  "src": "M5 5h14 M5 12h14 M5 19h14",
+  "tags": ["menu", "hamburger", "bars"]
+}
+```
+
+## Custom Properties
+
+Override defaults when needed:
+
+```json
+{
+  "name": "Filled Circle",
+  "slug": "filled-circle",
+  "src": "M12 12m-10 0a10 10 0 1 0 20 0a10 10 0 1 0-20 0",
+  "fill": "currentColor",
+  "stroke": "none",
+  "tags": ["circle", "dot", "bullet"]
+}
+```
+
+## Testing Icons
+
+1. **Visual check** - Preview in browser via `index.html`
+2. **Thickness test** - Verify icon looks good at various thicknesses
+3. **Size test** - Check rendering at small (16px) and large (48px) sizes
+4. **Color test** - Verify `currentColor` inheritance works

package/.agent/skills/senangstart-icons-architecture/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: SenangStart Icons Architecture
+description: Understanding the SenangStart Icons library architecture and core components
+---
+
+# SenangStart Icons Architecture
+
+This skill provides a comprehensive understanding of the SenangStart Icons library architecture.
+
+## Overview
+
+SenangStart Icons is an SVG icon library with two delivery methods:
+1. **Web Component** (`<ss-icon>`) - Dynamic icon rendering with thickness control
+2. **CSS Classes** (`<i class="ss ss-{slug}">`) - Static mask-based icons
+
+## Project Structure
+
+```
+senangstart-icons/
+├── src/
+│   ├── icons.json         # Master icon definitions
+│   ├── icons.css          # Generated CSS (mask-based)
+│   ├── index.js           # Main entry point
+│   ├── ss-icon.js         # Web Component definition
+│   ├── ss-loader.js       # Class-based icon loader
+│   ├── style.css          # Base styles
+│   └── svg/               # Generated SVG files
+│       ├── index.js       # Icon exports
+│       └── {slug}.svg     # Individual icons
+├── dist/                  # Bundled output
+├── docs/                  # VitePress documentation
+├── scripts/               # Build scripts
+└── tests/                 # Vitest tests
+```
+
+## Core Components
+
+### 1. Icon Definitions (`src/icons.json`)
+
+The single source of truth for all icons:
+
+```json
+{
+  "name": "Check",
+  "slug": "check",
+  "src": "M5 13l4 4L19 7",
+  "tags": ["approve", "success", "done"]
+}
+```
+
+Optional properties: `viewBox`, `fill`, `stroke`, `strokeWidth`
+
+### 2. Web Component (`src/ss-icon.js`)
+
+Custom element that renders icons dynamically:
+
+```html
+<ss-icon icon="check" thickness="1.5"></ss-icon>
+```
+
+Features:
+- Shadow DOM encapsulation
+- Reactive to `icon` and `thickness` attribute changes
+- Inherits color from `currentColor`
+- Scales with font size (1em × 1em)
+
+### 3. Class Loader (`src/ss-loader.js`)
+
+Injects SVG into elements with `ss ss-{slug}` classes:
+
+```html
+<i class="ss ss-check"></i>
+```
+
+Features:
+- Automatic DOM observation for dynamic content
+- Uses MutationObserver for live updates
+- Marks processed elements with `data-ss-loaded`
+
+### 4. CSS Icons (`src/icons.css`)
+
+Pure CSS icons using mask-image:
+
+```css
+.ss { /* base styles */ }
+.ss-check {
+  -webkit-mask-image: url("data:image/svg+xml,...");
+  mask-image: url("data:image/svg+xml,...");
+}
+```
+
+Advantages: No JavaScript required, inherits text color
+
+## Build Pipeline
+
+```mermaid
+graph LR
+    A[icons.json] --> B[build-svgs.js]
+    B --> C[src/svg/*.svg]
+    B --> D[src/svg/index.js]
+    A --> E[build-css.js]
+    E --> F[src/icons.css]
+    A --> G[build-icon-docs.js]
+    G --> H[docs/icons/*.md]
+    C --> I[webpack]
+    D --> I
+    F --> I
+    I --> J[dist/]
+```
+
+## Key Files Reference
+
+| File | Purpose |
+|------|---------|
+| `src/icons.json` | Icon definitions (add icons here) |
+| `src/ss-icon.js` | Web Component class |
+| `src/ss-loader.js` | DOM mutation observer for class-based icons |
+| `scripts/build.js` | Orchestrates full build |
+| `scripts/build-svgs.js` | Generates SVG files |
+| `scripts/build-css.js` | Generates CSS with mask-image |
+| `scripts/build-icon-docs.js` | Generates VitePress docs |
+| `webpack.config.js` | Bundle configuration |
+| `vitest.config.js` | Test configuration |

package/.agent/skills/testing/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: Testing
+description: Writing and running tests for SenangStart Icons
+---
+
+# Testing Skill
+
+This skill covers testing practices for SenangStart Icons using Vitest.
+
+## Test Setup
+
+**Configuration:** `vitest.config.js`
+
+```javascript
+export default defineConfig({
+  test: {
+    globals: true,           // describe, it, expect available globally
+    environment: 'node',     // Node.js environment
+    include: ['tests/**/*.test.js'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'html'],
+      include: ['src/**/*.js', 'scripts/**/*.js'],
+      exclude: ['src/svg/**']
+    }
+  }
+});
+```
+
+## Test Files Overview
+
+| File | Tests |
+|------|-------|
+| `ss-icon.test.js` | Web Component rendering |
+| `ss-loader.test.js` | Class-based icon injection |
+| `build-svgs.test.js` | SVG generation |
+| `build-css.test.js` | CSS generation |
+| `build-icon-docs.test.js` | Documentation generation |
+| `build-pipeline.test.js` | Full build integration |
+
+## Writing Tests
+
+### Testing Build Scripts
+
+Mock the file system to avoid actual file operations:
+
+```javascript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import fs from 'fs';
+
+vi.mock('fs');
+
+describe('build-svgs', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    
+    // Mock icons.json content
+    fs.readFileSync.mockReturnValue(JSON.stringify([
+      { name: 'Check', slug: 'check', src: 'M5 13l4 4L19 7', tags: [] }
+    ]));
+    
+    fs.existsSync.mockReturnValue(true);
+    fs.writeFileSync.mockImplementation(() => {});
+  });
+
+  it('should generate SVG files', () => {
+    require('../scripts/build-svgs.js');
+    
+    expect(fs.writeFileSync).toHaveBeenCalledWith(
+      expect.stringContaining('check.svg'),
+      expect.stringContaining('<svg')
+    );
+  });
+});
+```
+
+### Testing Web Component (with jsdom)
+
+```javascript
+import { describe, it, expect, beforeEach } from 'vitest';
+import { JSDOM } from 'jsdom';
+
+describe('SSIcon', () => {
+  let document, window;
+
+  beforeEach(() => {
+    const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>', {
+      runScripts: 'dangerously'
+    });
+    window = dom.window;
+    document = window.document;
+    
+    // Define custom element in jsdom context
+    // ...
+  });
+
+  it('should render icon SVG', () => {
+    const icon = document.createElement('ss-icon');
+    icon.setAttribute('icon', 'check');
+    document.body.appendChild(icon);
+    
+    expect(icon.shadowRoot.innerHTML).toContain('<svg');
+  });
+});
+```
+
+### Testing CSS Generation
+
+```javascript
+describe('build-css', () => {
+  it('should generate base .ss class', () => {
+    require('../scripts/build-css.js');
+    
+    const cssContent = fs.writeFileSync.mock.calls[0][1];
+    expect(cssContent).toContain('.ss {');
+    expect(cssContent).toContain('mask-size: contain');
+  });
+
+  it('should generate icon classes with mask-image', () => {
+    require('../scripts/build-css.js');
+    
+    const cssContent = fs.writeFileSync.mock.calls[0][1];
+    expect(cssContent).toContain('.ss-check {');
+    expect(cssContent).toContain('mask-image: url("data:image/svg+xml');
+  });
+});
+```
+
+## Running Tests
+
+### All Tests
+```bash
+npm test
+```
+
+### Watch Mode
+```bash
+npm run test:watch
+```
+
+### With Coverage
+```bash
+npm run test:coverage
+```
+
+### Specific Test File
+```bash
+npx vitest run tests/ss-icon.test.js
+```
+
+## Test Patterns
+
+### Mocking Child Process
+
+```javascript
+import { execSync } from 'child_process';
+
+vi.mock('child_process', () => ({
+  execSync: vi.fn()
+}));
+
+it('should run webpack', () => {
+  require('../scripts/build.js');
+  expect(execSync).toHaveBeenCalledWith(
+    'npx webpack --mode production',
+    expect.any(Object)
+  );
+});
+```
+
+### Testing Error Handling
+
+```javascript
+it('should handle missing icon gracefully', () => {
+  const icon = document.createElement('ss-icon');
+  icon.setAttribute('icon', 'nonexistent');
+  document.body.appendChild(icon);
+  
+  expect(icon.shadowRoot.innerHTML).toBe('');
+});
+```
+
+### Snapshot Testing
+
+```javascript
+it('should match SVG snapshot', () => {
+  const icon = document.createElement('ss-icon');
+  icon.setAttribute('icon', 'check');
+  document.body.appendChild(icon);
+  
+  expect(icon.shadowRoot.innerHTML).toMatchSnapshot();
+});
+```
+
+## Coverage Goals
+
+- **Statements:** > 80%
+- **Branches:** > 70%
+- **Functions:** > 80%
+- **Lines:** > 80%
+
+Exclude `src/svg/` from coverage as it's generated code.