@bookklik/senangstart-icons 1.0.8 → 1.0.11

package/.agent/skills/web-components/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: Web Components
+description: Working with the ss-icon Web Component and ss-loader
+---
+
+# Web Components Skill
+
+This skill covers the two JavaScript components that render icons.
+
+## ss-icon Web Component
+
+**Location:** `src/ss-icon.js`
+
+### Usage
+
+```html
+<ss-icon icon="check"></ss-icon>
+<ss-icon icon="arrow-left" thickness="1.5"></ss-icon>
+```
+
+### Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `icon` | string | - | Icon slug from icons.json |
+| `thickness` | number | 2 | Stroke width of the icon |
+
+### How It Works
+
+```javascript
+class SSIcon extends HTMLElement {
+  // Watch for attribute changes
+  static get observedAttributes() {
+    return ["icon", "thickness"];
+  }
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: "open" });
+  }
+
+  // Re-render when attributes change
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (name === "icon" || name === "thickness") {
+      this.render();
+    }
+  }
+
+  render() {
+    const iconName = this.getAttribute("icon");
+    const iconSvg = icons[iconName];
+    // Inject SVG with custom thickness into shadow DOM
+  }
+}
+
+customElements.define("ss-icon", SSIcon);
+```
+
+### Styling
+
+The component inherits color from parent:
+
+```css
+.my-button {
+  color: blue;
+}
+.my-button ss-icon {
+  /* Icon will be blue */
+}
+```
+
+Override size:
+
+```css
+ss-icon {
+  font-size: 24px; /* Icons scale with font-size */
+}
+```
+
+---
+
+## ss-loader (Class-based Icons)
+
+**Location:** `src/ss-loader.js`
+
+### Usage
+
+```html
+<i class="ss ss-check"></i>
+<i class="ss ss-arrow-left"></i>
+```
+
+### How It Works
+
+1. **Initial Load:** On DOMContentLoaded, finds all `i.ss` elements
+2. **Extract Icon:** Looks for class starting with `ss-`
+3. **Inject SVG:** Inserts SVG content into the element
+4. **Mark Loaded:** Adds `data-ss-loaded="true"` to prevent reprocessing
+5. **Observe Changes:** MutationObserver watches for new icons added dynamically
+
+```javascript
+function replaceIcons() {
+  const elements = document.querySelectorAll("i.ss");
+  elements.forEach((el) => {
+    if (el.dataset.ssLoaded) return; // Skip already processed
+    
+    const iconClass = classes.find(c => c.startsWith("ss-"));
+    const iconName = iconClass.replace("ss-", "");
+    const iconSvg = icons[iconName];
+    
+    if (iconSvg) {
+      el.innerHTML = iconSvg;
+      el.dataset.ssLoaded = "true";
+    }
+  });
+}
+
+// Watch for dynamically added icons
+const observer = new MutationObserver((mutations) => {
+  // Check for added nodes or class changes
+  if (shouldUpdate) replaceIcons();
+});
+
+observer.observe(document.body, {
+  childList: true,
+  subtree: true,
+  attributes: true,
+  attributeFilter: ["class"]
+});
+```
+
+### Styling Class-based Icons
+
+```css
+.ss {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  vertical-align: middle;
+}
+
+/* Custom styling */
+.ss-check {
+  color: green;
+  font-size: 2rem;
+}
+```
+
+---
+
+## CSS-Only Icons (Alternative)
+
+For environments without JavaScript, use the CSS-only approach:
+
+```html
+<link rel="stylesheet" href="senangstart.min.css">
+<i class="ss ss-check"></i>
+```
+
+The CSS uses `mask-image` with data URIs - no JavaScript required.
+
+---
+
+## Extending the Components
+
+### Adding New Attributes to ss-icon
+
+1. Add to `observedAttributes` array
+2. Handle in `render()` method
+3. Update tests in `tests/ss-icon.test.js`
+
+### Example: Adding a `color` attribute
+
+```javascript
+static get observedAttributes() {
+  return ["icon", "thickness", "color"];
+}
+
+render() {
+  const color = this.getAttribute("color") || "currentColor";
+  this.shadowRoot.innerHTML = `
+    <style>
+      :host { color: ${color}; }
+      /* ... */
+    </style>
+    ${finalSvg}
+  `;
+}
+```
+
+### Adding Animation Support
+
+```javascript
+render() {
+  const animate = this.hasAttribute("animate");
+  this.shadowRoot.innerHTML = `
+    <style>
+      ${animate ? `
+        @keyframes spin {
+          from { transform: rotate(0deg); }
+          to { transform: rotate(360deg); }
+        }
+        svg { animation: spin 1s linear infinite; }
+      ` : ""}
+    </style>
+    ${finalSvg}
+  `;
+}
+```

package/.agent/workflows/add-icon.md

@@ -0,0 +1,85 @@
+---
+description: Add a new icon to the SenangStart Icons library
+---
+
+# Add Icon Workflow
+
+This workflow guides adding a new icon to the library.
+
+## Step 1: Edit icons.json
+
+Add the new icon to `src/icons.json`:
+
+```json
+{
+  "name": "Icon Display Name",
+  "slug": "icon-slug",
+  "src": "M12 2L2 7l10 5 10-5-10-5z...",
+  "tags": ["category", "related", "keywords"]
+}
+```
+
+### Icon Properties
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `name` | Yes | Human-readable display name |
+| `slug` | Yes | URL-safe identifier (lowercase, hyphens) |
+| `src` | Yes | SVG path `d` attribute |
+| `tags` | Yes | Array of searchable keywords |
+| `viewBox` | No | Custom viewBox (default: "0 0 24 24") |
+| `fill` | No | Fill color (default: "none") |
+| `stroke` | No | Stroke color (default: "currentColor") |
+| `strokeWidth` | No | Stroke width (default: "2") |
+
+## Step 2: Rebuild Assets
+
+Run the full build to generate all files:
+
+// turbo
+```bash
+npm run build
+```
+
+This generates:
+- `src/svg/{slug}.svg` - Individual SVG file
+- Updated `src/icons.css` - CSS class for the icon
+- `docs/icons/{slug}.md` - English documentation
+- `docs/ms/icons/{slug}.md` - Malay documentation
+- Updated `dist/` bundles
+
+## Step 3: Verify the Icon
+
+1. Check the generated SVG in `src/svg/{slug}.svg`
+2. Open `index.html` in a browser to preview
+3. Run docs dev server to verify documentation:
+
+// turbo
+```bash
+npm run docs:dev
+```
+
+## Step 4: Run Tests
+
+// turbo
+```bash
+npm test
+```
+
+## Best Practices
+
+### SVG Path Guidelines
+- Use 24x24 viewBox for consistency
+- Optimize paths (remove unnecessary precision)
+- Use stroke-based icons for thickness customization
+- Ensure paths work with `stroke-linecap="round"` and `stroke-linejoin="round"`
+
+### Naming Conventions
+- Use descriptive, concise names
+- Slugs should be lowercase with hyphens
+- Follow existing naming patterns (e.g., `arrow-left`, `chevron-down`)
+
+### Tags
+- Include the icon name broken into words
+- Add related concept keywords
+- Include action words if applicable

package/.agent/workflows/build.md

@@ -0,0 +1,73 @@
+---
+description: Build the production distribution files for SenangStart Icons
+---
+
+# Build Workflow
+
+This workflow builds the production-ready distribution files.
+
+## Full Build (Recommended)
+
+// turbo
+```bash
+npm run build
+```
+
+This runs the complete 4-step build pipeline:
+1. **Build SVGs** - Generates individual SVG files from `src/icons.json`
+2. **Build CSS** - Creates `src/icons.css` with mask-based icon classes
+3. **Build Icon Docs** - Generates markdown docs for each icon (EN + MS)
+4. **Webpack** - Bundles and minifies JS/CSS to `dist/`
+
+## Individual Build Steps
+
+### Build SVGs Only
+
+// turbo
+```bash
+npm run build:svg
+```
+
+Reads `src/icons.json` and generates:
+- Individual SVG files in `src/svg/`
+- `src/svg/index.js` exporting all icons
+
+### Build CSS Only
+
+// turbo
+```bash
+npm run build:css
+```
+
+Generates `src/icons.css` with `.ss-{slug}` classes using CSS mask-image.
+
+### Build Icon Documentation Only
+
+// turbo
+```bash
+npm run build:icon-docs
+```
+
+Generates:
+- `docs/icons/{slug}.md` - Individual icon pages (English)
+- `docs/ms/icons/{slug}.md` - Individual icon pages (Malay)
+- `docs/icons/index.md` - Icon gallery index (English)
+- `docs/ms/icons/index.md` - Icon gallery index (Malay)
+
+## Output Files
+
+| File | Description |
+|------|-------------|
+| `dist/senangstart-icon.min.js` | Bundled JS (Web Component + Loader) |
+| `dist/senangstart-icon.min.js.map` | JS source map |
+| `dist/senangstart.min.css` | Bundled CSS |
+| `dist/senangstart.min.css.map` | CSS source map |
+
+## Webpack Configuration
+
+See `webpack.config.js` for bundling options:
+- UMD module format
+- Babel transpilation
+- TerserPlugin for JS minification
+- CssMinimizerPlugin for CSS minification
+- Source maps enabled

package/.agent/workflows/dev.md

@@ -0,0 +1,52 @@
+---
+description: Start the development server with hot-reload for icon development
+---
+
+# Development Server Workflow
+
+This workflow starts the development environment for SenangStart Icons.
+
+## Prerequisites
+
+Ensure dependencies are installed:
+
+// turbo
+```bash
+npm install
+```
+
+## Steps
+
+### 1. Start Development Mode
+
+This builds SVGs and CSS, then starts Webpack in watch mode:
+
+// turbo
+```bash
+npm run dev
+```
+
+This command:
+- Runs `build:svg` to generate SVG files from `src/icons.json`
+- Runs `build:css` to generate `src/icons.css` with mask-based icon classes
+- Starts Webpack in development watch mode
+
+### 2. (Optional) Start Documentation Dev Server
+
+In a separate terminal, start the VitePress docs server:
+
+// turbo
+```bash
+npm run docs:dev
+```
+
+This serves the documentation at `http://localhost:5173` with hot-reload.
+
+## File Locations
+
+| File | Purpose |
+|------|---------|
+| `src/icons.json` | Icon definitions (name, slug, SVG path, tags) |
+| `src/svg/` | Generated SVG files |
+| `src/icons.css` | Generated CSS with mask-based icons |
+| `dist/` | Bundled output files |

package/.agent/workflows/docs.md

@@ -0,0 +1,77 @@
+---
+description: Work with VitePress documentation for SenangStart Icons
+---
+
+# Documentation Workflow
+
+This workflow covers working with the VitePress documentation site.
+
+## Development Server
+
+Start the docs server with hot-reload:
+
+// turbo
+```bash
+npm run docs:dev
+```
+
+Access at `http://localhost:5173`
+
+## Build Documentation
+
+Build static documentation files:
+
+// turbo
+```bash
+npm run docs:build
+```
+
+Output goes to `docs/.vitepress/dist/`
+
+## Preview Production Build
+
+// turbo
+```bash
+npm run docs:preview
+```
+
+Serves the built documentation for testing before deployment.
+
+## Documentation Structure
+
+```
+docs/
+├── .vitepress/          # VitePress config
+├── guide/               # Usage guides (English)
+│   ├── getting-started.md
+│   ├── installation.md
+│   ├── usage.md
+│   ├── styling.md
+│   └── configuration.md
+├── icons/               # Auto-generated icon pages (English)
+│   ├── index.md         # Icon gallery
+│   └── {slug}.md        # Individual icon pages
+├── ms/                  # Malay translations
+│   ├── guide/
+│   └── icons/
+├── public/              # Static assets
+└── index.md             # Homepage
+```
+
+## Regenerating Icon Docs
+
+After adding/modifying icons in `src/icons.json`:
+
+// turbo
+```bash
+npm run build:icon-docs
+```
+
+This regenerates all icon documentation pages in both English and Malay.
+
+## Adding Guide Pages
+
+1. Create new `.md` file in `docs/guide/`
+2. Add frontmatter with `title` field
+3. Update VitePress config sidebar if needed
+4. Create Malay translation in `docs/ms/guide/` if applicable

package/.agent/workflows/publish.md

@@ -0,0 +1,80 @@
+---
+description: Publish a new version of SenangStart Icons to npm
+---
+
+# Publish Workflow
+
+This workflow guides publishing a new version to npm.
+
+## Prerequisites
+
+1. Ensure you're logged in to npm: `npm whoami`
+2. Ensure you have publish access to `@bookklik/senangstart-icons`
+
+## Step 1: Run Tests
+
+Ensure all tests pass:
+
+// turbo
+```bash
+npm test
+```
+
+## Step 2: Build Production Files
+
+// turbo
+```bash
+npm run build
+```
+
+## Step 3: Update Version
+
+Update version in `package.json` following semver:
+
+- **Patch** (1.0.x): Bug fixes, minor icon adjustments
+- **Minor** (1.x.0): New icons, non-breaking feature additions
+- **Major** (x.0.0): Breaking API changes
+
+// turbo
+```bash
+npm version patch
+```
+
+Or for minor/major:
+```bash
+npm version minor
+npm version major
+```
+
+## Step 4: Publish to npm
+
+```bash
+npm publish --access public
+```
+
+## Step 5: Push Tags
+
+```bash
+git push origin main --tags
+```
+
+## Step 6: Build and Deploy Docs
+
+Build documentation:
+
+// turbo
+```bash
+npm run docs:build
+```
+
+Deploy to GitHub Pages (if configured via GitHub Actions).
+
+## Checklist
+
+Before publishing:
+- [ ] All tests pass
+- [ ] Build completes without errors
+- [ ] Version number updated
+- [ ] CHANGELOG updated (if maintained)
+- [ ] Documentation regenerated
+- [ ] Icons visually verified

package/.agent/workflows/test.md

@@ -0,0 +1,56 @@
+---
+description: Run the test suite for SenangStart Icons
+---
+
+# Testing Workflow
+
+This workflow runs the Vitest test suite for SenangStart Icons.
+
+## Test Commands
+
+### Run All Tests Once
+
+// turbo
+```bash
+npm test
+```
+
+### Run Tests in Watch Mode
+
+// turbo
+```bash
+npm run test:watch
+```
+
+### Run Tests with Coverage
+
+// turbo
+```bash
+npm run test:coverage
+```
+
+Coverage reports are generated in HTML format in the `coverage/` directory.
+
+## Test Files
+
+| Test File | What It Tests |
+|-----------|---------------|
+| `tests/ss-icon.test.js` | `<ss-icon>` Web Component rendering |
+| `tests/ss-loader.test.js` | Class-based icon loader (`i.ss`) |
+| `tests/build-svgs.test.js` | SVG generation from icons.json |
+| `tests/build-css.test.js` | CSS generation with mask-image |
+| `tests/build-icon-docs.test.js` | Documentation generation |
+| `tests/build-pipeline.test.js` | Full build pipeline integration |
+
+## Configuration
+
+Tests are configured in `vitest.config.js`:
+- Environment: Node
+- Globals: enabled
+- Coverage: V8 provider, excludes `src/svg/`
+
+## Writing New Tests
+
+1. Create test file in `tests/` with `.test.js` extension
+2. Import `describe`, `it`, `expect` from `vitest` (or use globals)
+3. Mock file system operations if needed with `vi.mock('fs')`

package/README.md

@@ -40,14 +40,14 @@ Or use the `ss-icon` class:
 </body>
 ```
 
-## Preview
-
-![SenangStart Icons Preview](https://raw.githubusercontent.com/bookklik-technologies/senangstart-icons/master/preview.png)
-
 ## Contributing
 
 Contributions are welcome! Please fork the repository, make your changes, and submit a pull request.
 
+## Documentation
+
+Full docs at [bookklik-technologies.github.io/senangstart-icons](https://bookklik-technologies.github.io/senangstart-icons/)
+
 ## License
 
-MIT License
+Read [MIT License](LICENSE.md)

package/docs/.vitepress/config.mjs

@@ -16,14 +16,13 @@ const iconSidebarItems = icons.map(icon => ({
 
 // Shared theme config
 const sharedThemeConfig = {
-  logo: 'https://senangstart.com/img/ss_logo_typo.svg',
-  siteTitle: false,
+  logo: '/assets/ss-logo.svg',
   socialLinks: [
     { icon: 'github', link: 'https://github.com/bookklik-technologies/senangstart-icons' }
   ],
   footer: {
-    message: 'Released under the MIT License.',
-    copyright: 'Copyright © 2025 Bookklik Technologies'
+    message: 'SenangStart Icons v' + pkg.version + ' is part of the <a href="https://senangstart.com/" target="_blank" style="color: var(--vp-c-brand)">SenangStart</a> ecosystem.',
+    copyright: `Copyright © ${new Date().getFullYear()} <a href="https://bookklik.com/" target="_blank" style="color: #ff6600">Bookklik Technologies</a>. Released under the MIT License.`
   }
 }
 
@@ -97,10 +96,6 @@ export default defineConfig({
               items: iconSidebarItemsMs
             }
           ]
-        },
-        footer: {
-          message: 'Dikeluarkan di bawah Lesen MIT.',
-          copyright: 'Hakcipta © 2025 Bookklik Technologies'
         }
       }
     }
@@ -159,13 +154,20 @@ export default defineConfig({
       { icon: 'github', link: 'https://github.com/bookklik-technologies/senangstart-icons' }
     ],
 
-    footer: {
-      message: 'Released under the MIT License.',
-      copyright: 'Copyright © 2025 Bookklik Technologies'
-    },
-
     search: {
       provider: 'local'
     }
+  },
+
+  markdown: {
+    config: (md) => {
+      md.core.ruler.push('replace_version', (state) => {
+        state.tokens.forEach((token) => {
+          if (token.type === 'fence' && token.content.includes('__PKG_VERSION__')) {
+            token.content = token.content.replace(/__PKG_VERSION__/g, pkg.version)
+          }
+        })
+      })
+    }
   }
 })