@pure-ds/core 0.3.0

package/INTELLISENSE.md

@@ -0,0 +1,384 @@
+# IntelliSense & IDE Support
+
+Pure Design System provides comprehensive IntelliSense support for both HTML and CSS, making development faster and reducing errors. This guide covers setup for VS Code, WebStorm, and other editors.
+
+## 🎯 What You Get
+
+### HTML IntelliSense
+- ✅ Web component autocomplete (`<pds-drawer>`, `<pds-icon>`, etc.)
+- ✅ Attribute suggestions with descriptions
+- ✅ Enum value autocomplete (e.g., `position="left|right|top|bottom"`)
+- ✅ Property and method documentation on hover
+- ✅ Icon name autocomplete (all available icons)
+
+### CSS IntelliSense  
+- ✅ CSS custom property autocomplete (`--color-primary-500`, `--spacing-4`)
+- ✅ Token documentation and value previews
+- ✅ Utility class suggestions (`.flex`, `.gap-4`, `.border-gradient`)
+- ✅ Primitive class suggestions (`.card`, `.badge`, `.surface`)
+- ✅ Data attribute enhancements (`data-dropdown`, `data-toggle`)
+
+## 📦 Generation
+
+IntelliSense data is automatically generated when you export PDS assets:
+
+```bash
+# Generate all IntelliSense data (recommended)
+npm run pds:dx
+
+# Or as part of full export
+npm run pds:export
+
+# Or generate individually
+npm run pds:manifest    # HTML IntelliSense only
+npm run pds:css-data    # CSS IntelliSense only
+```
+
+### Generated Files
+
+After running generation, you'll have:
+
+```
+public/assets/pds/
+├── custom-elements.json       # Standard Custom Elements Manifest
+├── vscode-custom-data.json    # VS Code HTML custom data
+├── pds.css-data.json          # VS Code CSS custom data
+└── pds-css-complete.json      # Standard CSS data (all editors)
+
+# Root reference files for easy setup
+pds.html-data.json              # Points to vscode-custom-data.json
+pds.css-data.json               # Points to pds.css-data.json
+```
+
+## ⚙️ VS Code Setup
+
+### Recommended: Workspace Settings
+
+Create or update `.vscode/settings.json` in your project:
+
+```json
+{
+  "html.customData": [
+    "node_modules/pure-ds/public/assets/pds/vscode-custom-data.json"
+  ],
+  "css.customData": [
+    "node_modules/pure-ds/public/assets/pds/pds.css-data.json"
+  ]
+}
+```
+
+**Alternative** (if PDS is in your repo):
+```json
+{
+  "html.customData": ["./pds.html-data.json"],
+  "css.customData": ["./pds.css-data.json"]
+}
+```
+
+### Reload VS Code
+
+After adding settings:
+1. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac)
+2. Type "Developer: Reload Window"
+3. Press Enter
+
+## 🔧 WebStorm / IntelliJ IDEA Setup
+
+WebStorm automatically recognizes `custom-elements.json` in your `node_modules/pure-ds/` directory for HTML IntelliSense.
+
+### For CSS IntelliSense
+
+Add the CSS data file to your project settings:
+
+1. Go to **Settings** → **Languages & Frameworks** → **Style Sheets** → **CSS**
+2. Under **Custom Data**, add:
+   ```
+   node_modules/pure-ds/public/assets/pds/pds-css-complete.json
+   ```
+
+## 🌐 Other Editors
+
+### Sublime Text
+
+Install the [LSP](https://packagecontrol.io/packages/LSP) package and configure custom data paths.
+
+### Vim/Neovim
+
+Use [coc-css](https://github.com/neoclide/coc-css) or [coc-html](https://github.com/neoclide/coc-html) with custom data configuration.
+
+### Emacs
+
+Configure [lsp-mode](https://emacs-lsp.github.io/lsp-mode/) with CSS and HTML language servers.
+
+## 📝 Usage Examples
+
+### HTML IntelliSense in Action
+
+Type `<pds-` and see all available components:
+
+```html
+<!-- Autocomplete suggests: pds-drawer, pds-icon, pds-upload, etc. -->
+<pds-drawer 
+  position="right"    <!-- Autocomplete: bottom|top|left|right -->
+  open                <!-- Boolean attributes suggested -->
+  max-height="80vh">
+  
+  <!-- Slots are documented -->
+  <div slot="drawer-header">Settings</div>
+  <div slot="drawer-content">Content</div>
+</pds-drawer>
+
+<!-- Icon autocomplete suggests all available icons -->
+<pds-icon icon="star"></pds-icon>
+<pds-icon icon="bell-ringing"></pds-icon>
+```
+
+### CSS IntelliSense in Action
+
+#### CSS Custom Properties
+
+**✅ Works in .css files:**
+```css
+.my-component {
+  /* Type var(-- and see all tokens with autocomplete */
+  background: var(--color-primary-500);
+  color: var(--color-gray-50);
+  padding: var(--spacing-4);
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-lg);
+  
+  /* Hover over any token to see its value */
+  transition: var(--transition-normal);
+}
+```
+
+**✅ Works in `<style>` tags:**
+```html
+<style>
+  .custom {
+    color: var(--color-primary-500);
+    padding: var(--spacing-4);
+  }
+</style>
+```
+
+**❌ Does NOT work in inline `style` attributes** (VS Code limitation):
+```html
+<!-- No IntelliSense here - use <style> tag or utility classes instead -->
+<div style="color: var(--)"></div>
+```
+
+#### Utility Classes
+
+```html
+<!-- Class autocomplete in HTML -->
+<div class="flex gap-4 items-center">
+  <div class="card surface-elevated">
+    <!-- Primitives and utilities autocomplete -->
+  </div>
+</div>
+
+<button class="border-gradient-primary">
+  Fancy Button
+</button>
+```
+
+#### Data Attributes
+
+Progressive enhancement attributes with example code:
+
+```html
+<!-- Type data-dr to see data-dropdown suggestion with example -->
+<nav data-dropdown>
+  <button>Menu</button>
+  <menu>
+    <li><a href="#">Item 1</a></li>
+    <li><a href="#">Item 2</a></li>
+  </menu>
+</nav>
+
+<!-- Type data-to to see data-toggle suggestion with example -->
+<label data-toggle>
+  <span data-label>Enable notifications</span>
+  <input type="checkbox">
+</label>
+```
+
+**IntelliSense shows:**
+- Attribute name (`data-dropdown`, `data-toggle`)
+- Description of what it does
+- Complete example markup from the enhancer's `demoHtml`
+
+## 🎨 What's Included
+
+### CSS Custom Properties (150+ tokens)
+
+- **Colors**: `--color-{name}-{50-900}` (primary, secondary, accent, gray, etc.)
+- **Spacing**: `--spacing-{xs|sm|md|lg|xl|2xl|...}`
+- **Typography**: `--font-family-{heading|body|mono}`, `--font-size-*`, `--font-weight-*`
+- **Borders**: `--radius-{sm|md|lg|xl|full}`, `--border-width-{thin|medium|thick}`
+- **Shadows**: `--shadow-{sm|md|lg|xl|2xl}`
+- **Transitions**: `--transition-{fast|normal|slow}`
+- **Layout**: `--breakpoint-{sm|md|lg|xl}`, `--z-{dropdown|modal|tooltip|...}`
+- **Surfaces**: `--surface-bg`, `--surface-text`, `--surface-border`, etc.
+
+### CSS Classes (50+ utilities)
+
+**Primitives**:
+- `.badge`, `.card`, `.surface`, `.alert`, `.dialog`, `.table`, `.button`
+
+**Layout**:
+- `.flex`, `.grid`, `.grid-cols-{1-6}`, `.grid-auto-{sm|md|lg|xl}`, `.container`
+
+**Utilities**:
+- `.gap-{0-12}`, `.items-{start|end|center|baseline|stretch}`
+- `.justify-{start|end|center|between|around|evenly}`
+- `.border-gradient`, `.border-gradient-{primary|accent|secondary}`
+- `.border-glow`, `.border-glow-{sm|lg}`, `.border-glow-{color}`
+
+### Data Attributes (5+ enhancements)
+
+- `data-dropdown` - Auto-enhance navigation with dropdowns
+- `data-toggle` - Transform checkboxes into toggle switches
+- `data-tabs` - Tab interface enhancement
+- `data-modal` - Modal dialog behavior
+- `data-tooltip` - Tooltip enhancement
+
+## 🔍 Troubleshooting
+
+### CSS IntelliSense Not Working in Inline Styles
+
+**This is expected!** VS Code's CSS custom data **only works in:**
+- ✅ `.css` files
+- ✅ `<style>` tags in HTML
+- ❌ **NOT** in inline `style` attributes
+
+**Workarounds:**
+```html
+<!-- ❌ Won't work -->
+<div style="padding: var(--)"></div>
+
+<!-- ✅ Use <style> tag -->
+<style>
+  .my-padding { padding: var(--spacing-4); }
+</style>
+<div class="my-padding"></div>
+
+<!-- ✅ Or use utility classes -->
+<div class="gap-4 flex"></div>
+```
+
+### IntelliSense Not Working in CSS Files
+
+1. **Verify files exist**:
+   ```bash
+   ls -la node_modules/pure-ds/public/assets/pds/
+   # Should show: vscode-custom-data.json, pds.css-data.json
+   ```
+
+2. **Check settings path**: Ensure paths in `.vscode/settings.json` are correct
+
+3. **Reload VS Code**: Always reload after changing settings (Ctrl+Shift+P → "Developer: Reload Window")
+
+4. **Test in a CSS file**: Create a `.css` file and type `var(--` to see if autocomplete appears
+
+5. **Clear cache**: Try deleting `.vscode/` folder and recreating settings
+
+### Partial Autocomplete
+
+If you only see some suggestions:
+- HTML works but CSS doesn't → Check `css.customData` setting and reload
+- CSS works but HTML doesn't → Check `html.customData` setting and reload
+- CSS works in files but not inline → This is normal (VS Code limitation)
+
+### Consuming Project Setup
+
+If PDS is installed as a dependency:
+
+```json
+{
+  "html.customData": [
+    "node_modules/pure-ds/public/assets/pds/vscode-custom-data.json"
+  ],
+  "css.customData": [
+    "node_modules/pure-ds/public/assets/pds/pds.css-data.json"
+  ]
+}
+```
+
+If you've copied PDS assets to your project:
+
+```json
+{
+  "html.customData": [
+    "public/assets/pds/vscode-custom-data.json"
+  ],
+  "css.customData": [
+    "public/assets/pds/pds.css-data.json"
+  ]
+}
+```
+
+## 📚 Standards Compliance
+
+PDS IntelliSense follows these standards:
+
+- **Custom Elements Manifest**: [Web Component Standard](https://github.com/webcomponents/custom-elements-manifest)
+- **VS Code Custom Data**: [VS Code HTML/CSS Data Format](https://github.com/microsoft/vscode-custom-data)
+- **Cross-editor compatibility**: Standard JSON formats work with LSP-compliant editors
+
+## 🚀 Advanced Usage
+
+### TypeScript Support
+
+PDS also provides TypeScript definitions for full type safety:
+
+```typescript
+import { PDS } from 'pure-ds';
+
+// TypeScript knows all methods and properties
+const pds = new PDS({ 
+  preset: 'default',
+  design: {
+    colors: {
+      primary: '#007acc'
+    }
+  }
+});
+
+// Fully typed
+pds.compiled.tokens.colors.primary[500];
+```
+
+### Custom Data Generation
+
+To generate custom data with your own configuration:
+
+```bash
+# Generate with custom target directory
+npm run pds:dx public/my-assets
+```
+
+## 💡 Tips
+
+1. **Type less**: Let IntelliSense do the work - type `--col` and pick from suggestions
+2. **Explore tokens**: Hover over variables to see actual values
+3. **Discover utilities**: Type `.` in class attribute to browse all available classes
+4. **Icon discovery**: Use `icon="` and browse all icon names with descriptions
+5. **Learn by browsing**: IntelliSense descriptions teach you the design system
+
+## 🤝 Contributing
+
+Found missing autocomplete entries? The data is generated from:
+- `src/js/pds-core/pds-ontology.js` - Class definitions and enhancements
+- `src/js/pds-core/pds-generator.js` - Token generation
+- Component JSDoc comments - HTML element documentation
+
+Submit PRs to improve coverage!
+
+---
+
+**Next Steps**:
+- [Getting Started](./readme.md#getting-started)
+- [Configuration Guide](./readme.md#configuration)
+- [Component Documentation](./packages/pds-storybook/README.md)

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025, mvneerven
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

package/custom-elements-manifest.config.js

@@ -0,0 +1,30 @@
+/**
+ * Custom Elements Manifest Configuration
+ * Generates metadata for all PDS web components
+ */
+export default {
+  globs: ['public/assets/pds/components/pds-*.js'],
+  exclude: [],
+  outdir: '.',
+  dev: false,
+  watch: false,
+  dependencies: true,
+  packagejson: true,
+  litelement: true,
+  plugins: [
+    {
+      name: 'exclude-private-members',
+      // Remove private fields and methods from the manifest
+      moduleLinkPhase({moduleDoc}) {
+        moduleDoc.declarations?.forEach(declaration => {
+          if (declaration.members) {
+            declaration.members = declaration.members.filter(member => {
+              // Exclude members marked as private or starting with #
+              return member.privacy !== 'private' && !member.name?.startsWith('#');
+            });
+          }
+        });
+      },
+    },
+  ],
+};