@pure-ds/storybook 0.1.0

package/src/pds-core/pds-api.js

@@ -0,0 +1,105 @@
+import fs from 'fs/promises';
+import crypto from 'crypto';
+import path from 'path';
+import { Generator } from '../js/pds-core/pds-generator.js';
+
+/**
+ * Generate modules map and metadata from a config object.
+ * @param {object} config
+ * @param {object} [opts]
+ * @returns {Promise<{modules: Record<string,string>, meta: object}>}
+ */
+export async function generate(config, opts = {}) {
+  const gen = new Generator(config || {});
+
+  // generator produces tokens and css during construction in this repo
+  const tokens = gen.tokens || {};
+  const css = gen.layeredCSS || '';
+
+  const modules = {};
+
+  // Raw CSS outputs
+  modules['pds-tokens.css'] = Object.keys(tokens).length ? toTokensCSS(tokens) : '';
+  modules['pds-styles.css'] = css;
+
+  // JS modules that export the CSS as default string (consumable by import)
+  modules['pds-tokens.css.js'] = `export default ${JSON.stringify(modules['pds-tokens.css'])};`;
+  modules['pds-styles.css.js'] = `export default ${JSON.stringify(css)};`;
+
+  // A minimal story module placeholder (consumers/Storybook adapter can replace)
+  modules['pds-stories.js'] = `// PDS generated stories placeholder\nexport const meta = { generatedAt: ${JSON.stringify(new Date().toISOString())} };`;
+
+  const rawConfig = typeof config === 'string' ? config : JSON.stringify(config);
+  const hash = crypto.createHash('sha1').update(rawConfig).digest('hex');
+
+  const meta = {
+    generatedAt: new Date().toISOString(),
+    configHash: hash,
+    files: Object.keys(modules),
+  };
+
+  return { modules, meta };
+}
+
+function toTokensCSS(tokens) {
+  // Very small helper: flatten top-level token groups into :root custom properties
+  const parts = [':root {'];
+  for (const [group, obj] of Object.entries(tokens)) {
+    if (typeof obj === 'object') {
+      for (const [k, v] of Object.entries(obj)) {
+        const name = `--pds-${group}-${k}`.replace(/[^a-z0-9-_]/gi, '-').toLowerCase();
+        parts.push(`  ${name}: ${v};`);
+      }
+    }
+  }
+  parts.push('}');
+  return parts.join('\n');
+}
+
+/**
+ * Read config from file and generate modules.
+ * @param {string} configPath
+ * @param {object} [opts]
+ */
+export async function generateFromFile(configPath, opts = {}) {
+  const txt = await fs.readFile(configPath, 'utf8');
+  let cfg;
+  try {
+    cfg = JSON.parse(txt);
+  } catch (e) {
+    throw new Error(`Failed to parse config JSON: ${e.message}`);
+  }
+  return generate(cfg, opts);
+}
+
+/**
+ * Watch a config file and call the writer on changes.
+ * @param {string} configPath
+ * @param {string} outDir
+ * @param {{onWrite?:Function}} opts
+ */
+export function watch(configPath, outDir, opts = {}) {
+  let timeout = null;
+  const onChange = async () => {
+    try {
+      const result = await generateFromFile(configPath);
+      if (opts.onWrite) await opts.onWrite(result.modules, outDir, result.meta);
+    } catch (err) {
+      console.error('pds watch: generation error', err);
+      if (opts.onError) opts.onError(err);
+    }
+  };
+
+  const watcher = fs.watch(configPath, { persistent: true }, () => {
+    if (timeout) clearTimeout(timeout);
+    // debounce
+    timeout = setTimeout(onChange, 150);
+  });
+
+  // initial run
+  (async () => { await onChange(); })();
+
+  return {
+    close() { watcher.close(); }
+  };
+}

package/stories/GettingStarted.md

@@ -0,0 +1,96 @@
+# Getting Started with PDS Storybook
+
+Welcome to the **Pure Design System** Storybook! This is a comprehensive showcase of the configuration-driven design system that generates complete design systems from JavaScript configuration.
+
+## 🎨 What You're Looking At
+
+This Storybook instance demonstrates:
+
+- **Live Configuration** - Use the PDS Configurator button in the toolbar to change the design in real-time
+- **Multiple Presets** - Switch between design presets using the toolbar
+- **Theme Switching** - Toggle between light and dark themes
+- **Quick Search** - Use the search icon to query tokens and components
+
+## 🚀 Quick Start
+
+### 1. Try the Configurator
+
+Click the **PDS Configurator** button in the toolbar (circle icon) to open the configuration panel at the bottom of the screen. From there you can:
+
+- Change colors, typography, spacing
+- Toggle effects like liquid glass
+- Export your configuration
+- See changes applied instantly across all stories
+
+### 2. Browse Stories
+
+Stories are organized by best practices:
+
+- **Foundations** - Design tokens (colors, typography, spacing, icons)
+- **Primitives** - Basic UI elements (buttons, forms, cards, badges)
+- **Components** - Web Components (pds-icon, pds-drawer, pds-tabstrip, etc.)
+- **Patterns** - Layout patterns and utilities
+- **Enhancements** - Progressive enhancements for semantic HTML
+
+### 3. Use Quick Search
+
+Click the search icon in the toolbar to query the design system:
+
+- "what is the focus border color on inputs?"
+- "button hover color"
+- "how do I create a card?"
+
+## 📚 Story Features
+
+Each story includes:
+
+- **Interactive controls** - Use the Controls panel to customize
+- **Preset selection** - Try different design presets
+- **Color overrides** - Override primary/secondary colors per story
+- **Live updates** - Changes apply immediately
+
+## 🎯 Key Features
+
+### Configuration-Driven
+
+```javascript
+await PDS.start({
+  design: {
+    colors: { primary: '#007acc', secondary: '#5c2d91' },
+    typography: { baseFontSize: 16, fontScale: 1.25 },
+    spatialRhythm: { baseUnit: 8, scaleRatio: 1.5 }
+  }
+});
+```
+
+### Live Mode
+
+This Storybook runs PDS in **live mode**, meaning:
+- Styles are generated at runtime
+- Configuration changes apply instantly
+- Full access to `PDS.compiled` object model
+- Automatic font loading from Google Fonts
+
+### Framework Agnostic
+
+While this Storybook uses Vite + Web Components, PDS works with:
+- Vanilla JavaScript
+- Lit
+- React
+- Vue
+- Svelte
+- Next.js
+
+## 🔗 Resources
+
+- [GitHub](https://github.com/mvneerven/pure-ds)
+- [NPM Package](https://www.npmjs.com/package/@pure-ds/core)
+- [Documentation](https://puredesignsystem.z6.web.core.windows.net/)
+
+## 💡 Tips
+
+1. **Start with Foundations** - Understand the token system first
+2. **Experiment with Presets** - See how different designs look
+3. **Open the Configurator** - Try changing values live
+4. **Use Quick Search** - Find tokens and components quickly
+5. **Check Controls** - Each story has customizable parameters

package/stories/GettingStarted.stories.js

@@ -0,0 +1,144 @@
+import { html } from 'lit';
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
+import Showdown from 'showdown';
+import markdownContent from './GettingStarted.md?raw';
+
+const converter = new Showdown.Converter({
+  tables: true,
+  strikethrough: true,
+  tasklists: true,
+  ghCodeBlocks: true,
+  simplifiedAutoLink: true,
+  emoji: true
+});
+
+export default {
+  title: 'General/Getting Started',
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: 'Quick start guide to using PDS Storybook and exploring components'
+      }
+    }
+  }
+};
+
+export const Default = {
+  render: () => {
+    const htmlContent = converter.makeHtml(markdownContent);
+    
+    return html`
+      <style>
+        .markdown-container {
+          max-width: 900px;
+          margin: 0 auto;
+          padding: var(--spacing-8) var(--spacing-6);
+          background: var(--color-surface-base);
+          color: var(--color-text-primary);
+          font-family: var(--font-family-base);
+          line-height: var(--line-height-relaxed);
+        }
+
+        .markdown-container h1 {
+          font-size: var(--font-size-4xl);
+          font-weight: var(--font-weight-bold);
+          color: var(--color-text-primary);
+          margin: 0 0 var(--spacing-6);
+          line-height: var(--line-height-tight);
+          padding-bottom: var(--spacing-4);
+          border-bottom: 2px solid var(--color-border-subtle);
+        }
+
+        .markdown-container h2 {
+          font-size: var(--font-size-2xl);
+          font-weight: var(--font-weight-semibold);
+          color: var(--color-text-primary);
+          margin: var(--spacing-8) 0 var(--spacing-4);
+          line-height: var(--line-height-tight);
+        }
+
+        .markdown-container h3 {
+          font-size: var(--font-size-xl);
+          font-weight: var(--font-weight-semibold);
+          color: var(--color-text-primary);
+          margin: var(--spacing-6) 0 var(--spacing-3);
+        }
+
+        .markdown-container p {
+          margin: var(--spacing-4) 0;
+          color: var(--color-text-secondary);
+        }
+
+        .markdown-container strong {
+          color: var(--color-text-primary);
+          font-weight: var(--font-weight-semibold);
+        }
+
+        .markdown-container code {
+          background: var(--color-surface-raised);
+          color: var(--color-primary-500);
+          padding: var(--spacing-1) var(--spacing-2);
+          border-radius: var(--radius-sm);
+          font-family: var(--font-family-mono);
+          font-size: 0.9em;
+        }
+
+        .markdown-container pre {
+          background: var(--color-surface-raised);
+          border: 1px solid var(--color-border-subtle);
+          border-radius: var(--radius-md);
+          padding: var(--spacing-4);
+          overflow-x: auto;
+          margin: var(--spacing-4) 0;
+        }
+
+        .markdown-container pre code {
+          background: none;
+          padding: 0;
+          color: var(--color-text-primary);
+          display: block;
+        }
+
+        .markdown-container ul, 
+        .markdown-container ol {
+          margin: var(--spacing-4) 0;
+          padding-left: var(--spacing-6);
+        }
+
+        .markdown-container li {
+          margin: var(--spacing-2) 0;
+          color: var(--color-text-secondary);
+        }
+
+        .markdown-container hr {
+          border: none;
+          border-top: 1px solid var(--color-border-subtle);
+          margin: var(--spacing-8) 0;
+        }
+
+        .markdown-container a {
+          color: var(--color-primary-500);
+          text-decoration: none;
+          transition: color 0.2s ease;
+        }
+
+        .markdown-container a:hover {
+          color: var(--color-primary-600);
+          text-decoration: underline;
+        }
+
+        .markdown-container blockquote {
+          border-left: 4px solid var(--color-primary-500);
+          padding-left: var(--spacing-4);
+          margin: var(--spacing-4) 0;
+          color: var(--color-text-secondary);
+          font-style: italic;
+        }
+      </style>
+      <div class="markdown-container">
+        ${unsafeHTML(htmlContent)}
+      </div>
+    `;
+  }
+};

package/stories/WhatIsPDS.md

@@ -0,0 +1,194 @@
+![Pure Design System logo](/assets/img/logo.png) 
+
+## A standards-native design system built entirely on the Web Platform
+
+PDS is not a framework, not a CSS library, and not tied to Storybook.
+
+It is a **config-first, architecture-first, standards-only design system generator**.
+
+You write a small JavaScript config.
+PDS turns it into:
+
+- Deterministic global CSS
+- AdoptedStyleSheets (for Web Components)
+- A full hierarchic token model. Just type `PDS.compiled` in Dev Console...
+
+Apart from the layered token/styles generation, PDS offers:
+
+- Optional progressive enhancements for semantic HTML
+- Optional lazy-loaded Web Components
+- A custom-elements.json manifest for IDE IntelliSense
+
+This Storybook instance showcases the full power of PDS: layers, tokens, enhancements, and components.
+
+# Why PDS exists
+
+Modern frontend is dominated by frameworks, utility libraries, and toolchains that *replace* the Web Platform rather than *use* it.
+
+PDS takes the opposite path:
+- The browser is the framework.
+- Semantic HTML is the component model.
+- Web Standards are enough.
+
+PDS follows the [Pure Web Manifesto](https://pureweb.dev/manifesto) and provides sustainable architecture for long-lived apps without lock-in, complexity, or hidden magic.
+
+# The PDS Architecture
+
+PDS is built on **three fully optional layers**, each powered by your config:
+
+## 1. Styles — deterministic global CSS
+
+Generated from a single JavaScript config:
+
+```
+export default {
+  colors: { primary: "#0891b2" },
+  typography: { baseFontSize: 16, scale: 1.2 },
+  radius: 6,
+  spacing: { base: 4, ratio: 1.5 }
+};
+
+```
+
+PDS produces:
+
+- Color scales (50–900)
+- Semantic palettes (success, warning, info)
+- Typographic modular scale
+- Spacing system
+- Layout tokens
+- All exported as **CSS Custom Properties**
+- Zero specificity by design (`:where()` selectors)
+- Mirrors the same values in JS (`pds.compiled.tokens`)
+
+Use **only this layer** if you want PDS as a token + CSS generator.
+
+## 2. Progressive Enhancements — semantic HTML made powerful
+
+Optional selector-based enhancements that:
+
+- Run in both Light DOM and open Shadow DOM
+- Require no framework or build step
+- Upgrade semantic HTML automatically
+- Improve accessibility and defaults with zero JS integration work
+
+Examples:
+
+- Required fields automatically show markers and help text
+- Checkboxes can become toggles with one attribute
+- `<dialog>` elements get better focus management
+- Form elements gain consistent, theme-based styling
+
+Think **HTML → UX upgrades**, powered by your config.
+
+## 3. Components — auto-defined, lazy-loaded Web Components
+
+A growing set of PDS components:
+
+- Auto-defined when imported
+- Lazy-loaded via dynamic ESM imports
+- Styled by your tokens
+- Zero dependencies
+- Always optional: use none, some, or all
+
+Examples:
+
+- `<pds-dialog>`
+- `<pds-button>`
+- `<pds-card>`
+- `<pds-form>` and JSON Schema–driven config editors
+- `<pds-autocomplete>`
+
+PDS automatically generates a `custom-elements.json` (and editor-specific metadata) so editors like VSCode give full **IntelliSense**, autocomplete, and type info.
+
+# Why PDS is different
+
+### ✓ 100% Web Standards — no dependencies
+
+### ✓ Extremely layered — everything optional
+
+Use only tokens.\
+Or only CSS.\
+Or CSS + enhancements.\
+Or the full component set.\
+Nothing forces itself into your project.
+
+### ✓ Opinionated, but never restrictive
+
+Clean defaults that stay out of your way.\
+Everything overrideable.\
+No generated specificity wars.
+
+### ✓ No magic, no opacity
+
+All generated CSS is readable, inspectable, and deterministic.\
+No toolchain tricks.\
+No runtime class generation.
+
+### ✓ Config → Tokens → CSS → JS (single source of truth)
+
+Breakpoints, spacing, color ramps all available in:
+
+- Global CSS
+- Shadow DOM CSS
+- JavaScript (`pds.compiled`)
+
+Your entire codebase stays in sync.
+
+# How Storybook fits in
+
+Storybook is **not part of PDS**.
+
+It is simply the **showcase and documentation environment** for exploring PDS:
+
+- It runs PDS in **live config mode**
+- Every story is affected instantly by config changes
+- You can toggle:
+  - Themes
+  - Layers
+  - Enhancements
+  - Components
+- It demonstrates how PDS behaves in real applications
+- It helps teams maintain visual consistency across projects
+
+Think of Storybook as **“the PDS showroom,”** not the engine.
+
+# What you can explore in this Storybook
+
+### Foundations
+
+The generated tokens — colors, spacing, typography, radii, elevation, surfaces.
+
+### Utilities
+
+Minimal, generated utility classes based entirely on tokens.
+
+### Enhancements
+
+Selector-driven UX improvements on semantic HTML.
+
+### Components
+
+Lazy-loaded Web Components styled by your config.
+
+### Patterns
+
+Common UI constructions built from the three PDS layers.
+
+### Configurator
+
+Open the toolbar → 🎨 icon to adjust the live configuration.
+
+# Who PDS is for
+
+- Teams who want a design system without a framework commitment
+- Developers tired of Tailwind’s utility sprawl or React’s re-render economics
+- Web Components users who want full token theming
+- Apps that need long-term sustainability and simplicity
+- PWAs, MPAs, SPAs, static sites, enterprise dashboards — anything HTML-based
+
+# In short
+
+> **PDS is a 100% standards-native, extremely layered, 
+> dependency-free, and completely transparent design system.
+> This Storybook instance simply demonstrates its power.**

package/stories/WhatIsPDS.stories.js

@@ -0,0 +1,144 @@
+import { html } from 'lit';
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
+import Showdown from 'showdown';
+import markdownContent from './WhatIsPDS.md?raw';
+
+const converter = new Showdown.Converter({
+  tables: true,
+  strikethrough: true,
+  tasklists: true,
+  ghCodeBlocks: true,
+  simplifiedAutoLink: true,
+  emoji: true
+});
+
+export default {
+  title: 'General/What is PDS',
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: 'Learn about Pure Design System and its revolutionary approach to design systems'
+      }
+    }
+  }
+};
+
+export const Default = {
+  render: () => {
+    const htmlContent = converter.makeHtml(markdownContent);
+    
+    return html`
+      <style>
+        .markdown-container {
+          max-width: 900px;
+          margin: 0 auto;
+          padding: var(--spacing-8) var(--spacing-6);
+          background: var(--color-surface-base);
+          color: var(--color-text-primary);
+          font-family: var(--font-family-base);
+          line-height: var(--line-height-relaxed);
+        }
+
+        .markdown-container h1 {
+          font-size: var(--font-size-4xl);
+          font-weight: var(--font-weight-bold);
+          color: var(--color-text-primary);
+          margin: 0 0 var(--spacing-6);
+          line-height: var(--line-height-tight);
+          padding-bottom: var(--spacing-4);
+          border-bottom: 2px solid var(--color-border-subtle);
+        }
+
+        .markdown-container h2 {
+          font-size: var(--font-size-2xl);
+          font-weight: var(--font-weight-semibold);
+          color: var(--color-text-primary);
+          margin: var(--spacing-8) 0 var(--spacing-4);
+          line-height: var(--line-height-tight);
+        }
+
+        .markdown-container h3 {
+          font-size: var(--font-size-xl);
+          font-weight: var(--font-weight-semibold);
+          color: var(--color-text-primary);
+          margin: var(--spacing-6) 0 var(--spacing-3);
+        }
+
+        .markdown-container p {
+          margin: var(--spacing-4) 0;
+          color: var(--color-text-secondary);
+        }
+
+        .markdown-container strong {
+          color: var(--color-text-primary);
+          font-weight: var(--font-weight-semibold);
+        }
+
+        .markdown-container code {
+          background: var(--color-surface-raised);
+          color: var(--color-primary-500);
+          padding: var(--spacing-1) var(--spacing-2);
+          border-radius: var(--radius-sm);
+          font-family: var(--font-family-mono);
+          font-size: 0.9em;
+        }
+
+        .markdown-container pre {
+          background: var(--color-surface-raised);
+          border: 1px solid var(--color-border-subtle);
+          border-radius: var(--radius-md);
+          padding: var(--spacing-4);
+          overflow-x: auto;
+          margin: var(--spacing-4) 0;
+        }
+
+        .markdown-container pre code {
+          background: none;
+          padding: 0;
+          color: var(--color-text-primary);
+          display: block;
+        }
+
+        .markdown-container ul, 
+        .markdown-container ol {
+          margin: var(--spacing-4) 0;
+          padding-left: var(--spacing-6);
+        }
+
+        .markdown-container li {
+          margin: var(--spacing-2) 0;
+          color: var(--color-text-secondary);
+        }
+
+        .markdown-container hr {
+          border: none;
+          border-top: 1px solid var(--color-border-subtle);
+          margin: var(--spacing-8) 0;
+        }
+
+        .markdown-container a {
+          color: var(--color-primary-500);
+          text-decoration: none;
+          transition: color 0.2s ease;
+        }
+
+        .markdown-container a:hover {
+          color: var(--color-primary-600);
+          text-decoration: underline;
+        }
+
+        .markdown-container blockquote {
+          border-left: 4px solid var(--color-primary-500);
+          padding-left: var(--spacing-4);
+          margin: var(--spacing-4) 0;
+          color: var(--color-text-secondary);
+          font-style: italic;
+        }
+      </style>
+      <div class="markdown-container">
+        ${unsafeHTML(htmlContent)}
+      </div>
+    `;
+  }
+};