@pure-ds/core 0.5.40 → 0.5.42

package/readme.md

@@ -1405,7 +1405,7 @@ await PDS.start({ design: myPreset });
   <script type="importmap">
   {
     "imports": {
-      "#pds/lit": "https://cdn.jsdelivr.net/npm/lit@3/index.js"
+      "#pds/lit": "https://cdn.jsdelivr.net/npm/@pure-ds/core@latest/public/assets/pds/external/lit.js"
     }
   }
   </script>
@@ -1775,6 +1775,8 @@ export default {
 
 **Symptoms:** `<pds-form>` or other Lit-based components fail to load with module resolution errors.
 
+See the dedicated Lit guide: [pds-lit-guide.md](pds-lit-guide.md).
+
 **Components requiring Lit:**
 - `<pds-form>` - JSON Schema forms
 - `<pds-drawer>` - Drawer/sidebar panels
@@ -1785,28 +1787,126 @@ export default {
 <script type="importmap">
 {
   "imports": {
-    "#pds/lit": "/assets/js/lit.js"
+    "#pds/lit": "/assets/pds/external/lit.js"
   }
 }
 </script>
 ```
 
+**About the bundle:** `#pds/lit` is a convenience bundle that re-exports official Lit APIs and adds PDS helpers:
+- `lazyProps` (waits for custom element definition before applying object props)
+- `msg()` (PDS localization helper)
+- `loadLocale()` (loads translation strings)
+
+**Prefer not to use the bundle?** Create your own module and alias `#pds/lit` to it:
+
+```javascript
+// pds-lit.js (example)
+export * from "lit";
+export * from "lit/directives/repeat.js";
+export * from "lit/directives/keyed.js";
+export * from "lit/directives/class-map.js";
+export { ref, createRef } from "lit/directives/ref.js";
+export { ifDefined } from "lit/directives/if-defined.js";
+export { until } from "lit/directives/until.js";
+export { unsafeHTML } from "lit/directives/unsafe-html.js";
+export { unsafeSVG } from "lit/directives/unsafe-svg.js";
+
+// Optional: use PDS localization helper
+// export { msg } from "@pure-ds/core/src/js/common/msg.js";
+
+// Minimal lazyProps implementation (see src/js/lit.js)
+import { Directive, directive } from "lit/directive.js";
+class LazyPropsDirective extends Directive {
+  #pendingProps = null;
+  #element = null;
+  render(_props) { return null; }
+  update(part, [props]) {
+    const element = part.element;
+    if (this.#element !== element) {
+      this.#element = element;
+      this.#pendingProps = props;
+      this.#applyProps();
+    } else if (JSON.stringify(this.#pendingProps) !== JSON.stringify(props)) {
+      this.#pendingProps = props;
+      this.#applyProps();
+    }
+    return null;
+  }
+  async #applyProps() {
+    if (!this.#element || !this.#pendingProps) return;
+    await customElements.whenDefined(this.#element.tagName.toLowerCase());
+    for (const [key, value] of Object.entries(this.#pendingProps)) {
+      this.#element[key] = value;
+    }
+  }
+}
+export const lazyProps = directive(LazyPropsDirective);
+```
+
 Or in bundlers (Vite, Webpack, etc.):
 
 ```javascript
 // vite.config.js
+import path from 'node:path';
+
+const pdsLitPath = path.resolve(
+  __dirname,
+  'node_modules/@pure-ds/core/public/assets/pds/external/lit.js'
+);
+
 export default {
   resolve: {
-    alias: { '#pds/lit': 'lit' }
+    alias: { '#pds/lit': pdsLitPath }
   }
 };
 
 // webpack.config.js
+const path = require('node:path');
+
+const pdsLitPath = path.resolve(
+  __dirname,
+  'node_modules/@pure-ds/core/public/assets/pds/external/lit.js'
+);
+
 module.exports = {
   resolve: {
-    alias: { '#pds/lit': 'lit' }
+    alias: { '#pds/lit': pdsLitPath }
   }
 };
+
+// esbuild
+const path = require('node:path');
+require('esbuild').build({
+  alias: {
+    '#pds/lit': path.resolve(
+      process.cwd(),
+      'node_modules/@pure-ds/core/public/assets/pds/external/lit.js'
+    )
+  }
+});
+
+// rollup (using @rollup/plugin-alias)
+import path from 'node:path';
+
+alias({
+  entries: [
+    {
+      find: '#pds/lit',
+      replacement: path.resolve(
+        __dirname,
+        'node_modules/@pure-ds/core/public/assets/pds/external/lit.js'
+      )
+    }
+  ]
+});
+
+// parcel (package.json)
+{
+  "alias": {
+    "#pds/lit": "node_modules/@pure-ds/core/public/assets/pds/external/lit.js"
+  }
+}
 ```
 
 **Note:** Wait for components to load before accessing their APIs:

package/src/js/pds.d.ts

@@ -159,6 +159,9 @@ export interface PDSEventMap {
 export class PDS extends EventTarget {
   // Static surface
   static registry: PDSRegistry;
+  static initializing?: boolean;
+  static currentPreset?: string | null;
+  static debug?: boolean;
   static applyStyles?: (generator?: Generator) => void;
   static adoptLayers: (shadowRoot: ShadowRoot, layers?: string[], additionalSheets?: CSSStyleSheet[]) => Promise<void>;
   static adoptPrimitives: (shadowRoot: ShadowRoot, additionalSheets?: CSSStyleSheet[]) => Promise<void>;
@@ -173,6 +176,7 @@ export class PDS extends EventTarget {
   static ontology?: any;
   static enums?: Record<string, any>;
   static common?: Record<string, any>;
+  static parse?: (html: string) => Element[];
   static query?: (question: string) => Promise<any[]>;
   static AutoComplete?: any;
   static loadAutoComplete?: () => Promise<any>;

package/src/js/pds.js

@@ -22,12 +22,33 @@
  *
  * @typedef {Object} PDSAPI
  * @property {import("./pds-core/pds-registry.js").PDSRegistry} registry - Singleton runtime registry for live/static mode
+ * @property {boolean} initializing - Internal init guard (set while PDS.start is running)
+ * @property {string|null} currentPreset - Current preset id/name (legacy; may be null)
+ * @property {boolean} debug - Enable verbose runtime logging
  * @property {(generator?: import("./pds-core/pds-generator.js").Generator) => void} applyStyles - Apply generated styles to the document (live-only)
  * @property {(shadowRoot: ShadowRoot, layers?: string[], additionalSheets?: CSSStyleSheet[]) => Promise<void>} adoptLayers - Adopt multiple layers into a ShadowRoot. May log errors and fallback to additionalSheets when static imports fail.
  * @property {(shadowRoot: ShadowRoot, additionalSheets?: CSSStyleSheet[]) => Promise<void>} adoptPrimitives - Adopt primitives layer into a ShadowRoot. Designed as a convenience for components.
  * @property {(css:string) => CSSStyleSheet} createStylesheet - Create a constructable stylesheet from CSS text. @throws {DOMException} on invalid CSS in some browsers.
  * @property {() => boolean} isLiveMode - Returns true when running in live/designer-backed mode
  * @property {() => Promise<typeof import("./pds-core/pds-generator.js").Generator>} getGenerator - Live-only accessor for the Generator class
+ * @property {(question: string) => Promise<any[]>} query - Live-only query interface
+ * @property {(message: string, options?: any) => Promise<any>} ask - Modal dialog helper (static + live)
+ * @property {(message: string, options?: any) => Promise<string>} toast - Toast helper (static + live)
+ * @property {Record<string, any>} common - Common utilities namespace (static + live)
+ * @property {(html: string) => Element[]} parse - HTML string parser (static + live)
+ * @property {any} AutoComplete - Lazy-loaded autocomplete class (null until loaded)
+ * @property {() => Promise<any>} loadAutoComplete - Lazy-load the autocomplete package
+ * @property {Record<string, any>} enums - Enum values (static + live)
+ * @property {any} ontology - Design system ontology (live-only)
+ * @property {Record<string, any>} presets - Preset metadata (live-only)
+ * @property {Array<{selector: string, description?: string, demoHtml?: string}>} enhancerMetadata - Enhancer metadata (live-only)
+ * @property {Array<any>} defaultEnhancers - Default enhancer definitions (static + live)
+ * @property {(el: Element) => ComponentDef | null} findComponentForElement - Ontology lookup helper (live-only)
+ * @property {() => void} preloadCritical - Emit critical CSS into <style> (live-only)
+ * @property {any} currentConfig - Frozen configuration snapshot after start (static + live)
+ * @property {any} compiled - Compiled design system state (live-only)
+ * @property {string|null} theme - Theme preference getter/setter (static + live, browser only)
+ * @property {(config?: object) => Promise<any>} start - Unified entry point for live/static init
  */
 
 /**
@@ -127,6 +148,7 @@ PDS.isLiveMode = () => registry.isLive;
 PDS.ask = ask;
 PDS.toast = toast;
 PDS.common = common;
+PDS.parse = common.parseHTML;
 PDS.AutoComplete = null;
 PDS.loadAutoComplete = async () => {
   if (PDS.AutoComplete) return PDS.AutoComplete;