@pure-ds/core 0.3.17 → 0.3.19

package/custom-elements.json

@@ -1306,7 +1306,8 @@
             },
             {
               "kind": "method",
-              "name": "updateLayout"
+              "name": "updateLayout",
+              "description": "Updates the layout based on the current viewport width and breakpoint.\nToggles mobile mode and adjusts panel styles."
             },
             {
               "kind": "method",
@@ -1332,11 +1333,13 @@
             },
             {
               "kind": "method",
-              "name": "toggleMobileView"
+              "name": "toggleMobileView",
+              "description": "Toggles the visibility of the primary panel in mobile view."
             },
             {
               "kind": "method",
-              "name": "closeMobileView"
+              "name": "closeMobileView",
+              "description": "Closes the primary panel in mobile view."
             },
             {
               "kind": "method",

package/dist/types/pds.d.ts

@@ -1,408 +1,109 @@
-/**
- * Runtime registry singleton that controls live vs static behavior.
- * Consumers can call `registry.setDesigner(designer)` to enable live mode
- * or `registry.setStaticMode(paths)` to point to static asset modules.
- */
-export interface PDSRegistry {
-  /** Attach a designer instance and switch the registry to live mode. */
-  setDesigner(designer: any, meta?: { presetName?: string }): void;
-  /** Switch to static mode and override static paths (keys: tokens, primitives, components, utilities, styles) */
-  setStaticMode(paths?: Record<string, string>): void;
-  /** Return a constructable stylesheet for the requested layer or null on failure. */
-  getStylesheet(layer: string): Promise<CSSStyleSheet | null>;
-  /** Return a BLOB URL (live mode only) for layer imports used in CSS */
-  getBlobURL(layer: string): string | null;
-  /** 'live' or 'static' */
-  readonly mode: string;
-  /** true when a live designer instance is registered */
-  readonly isLive: boolean;
-  /** true when a designer instance exists */
-  readonly hasDesigner: boolean;
-}
-
-/** A small shape describing component metadata used by the PDS ontology. */
-export interface ComponentDef {
-  /** canonical name of the component (e.g., 'Button') */
-  name: string;
-  /** optional HTML tag name for the component ('pds-button') */
-  tag?: string;
-  /** documented props and their types/metadata */
-  props?: Record<string, any>;
-  /** human-friendly description used by the designer */
-  description?: string;
-}
-
-/** Layer information with CSS content and metadata */
-export interface CompiledLayer {
-  css: string;
-  size: number;
-  sizeKB: string;
-}
-
-/** Complete compiled state of the design system */
-export interface CompiledState {
-  /** Core token groups - the source data used to generate CSS */
-  tokens: {
-    colors: Record<string, any>;
-    spacing: Record<string, any>;
-    radius: Record<string, any>;
-    borderWidths: Record<string, any>;
-    typography: Record<string, any>;
-    shadows: Record<string, any>;
-    layout: Record<string, any>;
-    transitions: Record<string, any>;
-    zIndex: Record<string, any>;
-    icons: Record<string, any>;
-  };
-
-  /** Layer information - CSS content and metadata for each layer */
-  layers: {
-    tokens: CompiledLayer;
-    primitives: CompiledLayer;
-    components: CompiledLayer;
-    utilities: CompiledLayer;
-    combined: CompiledLayer;
-  };
-
-  /** Configuration snapshot - what was used to generate this state */
-  config: {
-    design: any;
-    preset: string | null;
-    debug: boolean;
-  };
-
-  /** Runtime capabilities and environment */
-  capabilities: {
-    constructableStylesheets: boolean;
-    blobURLs: boolean;
-    shadowDOM: boolean;
-  };
-
-  /** References to design system metadata */
-  references: {
-    ontology: any;
-    enums: any;
-  };
-
-  /** Computed metadata about the generated design system */
-  meta: {
-    generatedAt: string;
-    totalSize: number;
-    totalSizeKB: string;
-    layerCount: number;
-    tokenGroups: number;
-  };
-
-  /** Introspection helpers - methods to query the compiled state */
-  helpers: {
-    getColorScales(): Array<{ name: string; scale: any }>;
-    getColorScale(name: string): any;
-    getSpacingValues(): Array<{ key: string; value: any }>;
-    getTypography(): any;
-    getLayerCSS(layer: 'tokens' | 'primitives' | 'components' | 'utilities'): string;
-    usesEnumValue(enumGroup: string, value: any): boolean;
-  };
-}
-
-/**
- * Generator - programmatic API to produce tokens, layered CSS and helper modules from a config.
- * Typical usage:
- * const g = new PDS.Generator({ example: true });
- * // tokens may be returned synchronously or via a Promise
- * const tokens = await g.generateTokens?.();
- * const css = await g.generateCSS?.();
- */
-export class Generator {
-  constructor(options?: any);
-  /** runtime options / config passed to the generator */
-  options: any;
-  /** generated token object */
-  tokens: Record<string, any>;
-  /** concatenated CSS (layered) */
-  css: string;
-  /** Complete compiled representation of the design system state */
-  readonly compiled: CompiledState;
-  /** Generate the token map (may be async in some implementations) */
-  generateTokens?(): Record<string, any> | Promise<Record<string, any>>;
-  /** Generate the CSS string (may be async) */
-  generateCSS?(): string | Promise<string>;
-}
-
-/** Public runtime surface exported as `PDS` */
-export interface PDSEventMap {
-  'pds:ready': CustomEvent<{ mode: 'live' | 'static'; generator?: Generator; config: any; theme: string; autoDefiner?: any }>;
-  'pds:error': CustomEvent<{ error: any }>;
-  'pds:theme:changed': CustomEvent<{ theme: string; requested?: string; source: 'system' | 'programmatic' }>;
-  'pds:design:updated': CustomEvent<{ config: any; designer?: any }>;
-  'pds:design:field:changed': CustomEvent<{ field: string; config: any }>;
-  'pds:inspector:mode:changed': CustomEvent<{ active: boolean }>;
-  'pds:inspector:deactivate': CustomEvent<{}>;
-  'pds:docs:view': CustomEvent<{ file: string }>;
-}
-
-export class PDS extends EventTarget {
-  // Static surface
-  static Generator: typeof Generator;
-  static registry: PDSRegistry;
-  static presets: Record<string, any>;
-  static ontology: any;
-  static adoptLayers: (shadowRoot: ShadowRoot, layers?: string[], additionalSheets?: CSSStyleSheet[]) => Promise<void>;
-  static adoptPrimitives: (shadowRoot: ShadowRoot, additionalSheets?: CSSStyleSheet[]) => Promise<void>;
-  static createStylesheet: (css: string) => CSSStyleSheet;
-  static isLiveMode: () => boolean;
-  static findComponentForElement: (el: Element) => ComponentDef | null;
-  static validateDesign: (designConfig: any, options?: { minContrast?: number }) => { ok: boolean; issues: Array<{ path: string; message: string; ratio: number; min: number; context?: string }> };
-  static validateDesigns: (designs: Array<any> | Record<string, any>, options?: { minContrast?: number }) => { ok: boolean; results: Array<{ name?: string; ok: boolean; issues: Array<{ path: string; message: string; ratio: number; min: number; context?: string }> }> };
-  
-  /** 
-   * Current configuration after PDS.start() completes - read-only, frozen after initialization.
-   * Contains the complete configuration used to initialize PDS, including mode, design, preset, and theme.
-   */
-  static readonly currentConfig: any;
-  
-  /**
-   * Compiled design system state - provides structured access to all generated tokens,
-   * layers, and metadata. Available in live mode when a generator is active.
-   * Returns null if not in live mode or if no generator is present.
-   */
-  static readonly compiled: CompiledState | null;
-
-  // Static EventTarget-like facade for default instance
-  static addEventListener<K extends keyof PDSEventMap>(type: K, listener: (ev: PDSEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
-  static removeEventListener<K extends keyof PDSEventMap>(type: K, listener: (ev: PDSEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
-  static dispatchEvent(event: PDSEventMap[keyof PDSEventMap] | Event): boolean;
-
-  // Static entry point
-  static start(config?: {
-    mode?: 'live' | 'static';
-    preset?: string;
-    design?: any;
-    autoDefine?: {
-      baseURL?: string;
-      predefine?: string[];
-  mapper?: (tag: string) => string | undefined | null | false;
-      scanExisting?: boolean;
-      observeShadows?: boolean;
-      patchAttachShadow?: boolean;
-      debounceMs?: number;
-      onError?: (tag: string, err: any) => void;
-    };
-    applyGlobalStyles?: boolean;
-    manageTheme?: boolean;
-    themeStorageKey?: string;
-    public?: {
-      root?: string;
-    };
-    // live-only
-    preloadStyles?: boolean;
-    criticalLayers?: string[];
-    // static-only
-    staticPaths?: Record<string, string>;
-    enhancers?: Array<any>;
-  }): Promise<PDS>;
-
-  constructor();
-
-  // Instance state
-  readonly mode: 'live' | 'static';
-  readonly generator?: Generator;
-  readonly config: any;
-  readonly theme: string;
-  readonly autoDefiner?: any;
-
-  // Instance helpers
-  setTheme(theme: 'light' | 'dark' | 'system', options?: { storageKey?: string; persist?: boolean }): Promise<string>;
-  preloadCritical(config: any, options?: { theme?: string; layers?: string[] }): void;
-}
-
-export { PDS as default };
-
-// ===== pds-jsonform Types =====
-
-export interface JsonFormOptions {
-  widgets?: {
-    booleans?: 'toggle' | 'checkbox';
-    numbers?: 'input' | 'range';
-    selects?: 'standard' | 'dropdown';
-  };
-  layouts?: {
-    fieldsets?: 'default' | 'flex' | 'grid' | 'accordion' | 'tabs' | 'card';
-    arrays?: 'default' | 'compact';
-  };
-  enhancements?: {
-    icons?: boolean;
-    datalists?: boolean;
-    rangeOutput?: boolean;
-  };
-  validation?: {
-    showErrors?: boolean;
-    validateOnChange?: boolean;
-  };
-  // Path-specific options (JSON Pointer paths)
-  [path: string]: any;
-}
-
-export interface UISchema {
-  // Field-level UI customization (JSON Pointer paths as keys)
-  [path: string]: {
-    'ui:widget'?: string;
-    'ui:layout'?: 'default' | 'flex' | 'grid' | 'accordion' | 'tabs';
-    'ui:columns'?: number | 'auto';
-    'ui:autoSize'?: 'sm' | 'md' | 'lg' | 'xl';
-    'ui:gap'?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-    'ui:wrap'?: boolean;
-    'ui:direction'?: 'row' | 'column';
-    'ui:surface'?: 'card' | 'elevated' | 'dialog';
-    'ui:accordion'?: boolean;
-    'ui:tabs'?: boolean;
-    'ui:defaultOpen'?: number[];
-    'ui:dialog'?: boolean;
-    'ui:dialogButton'?: string;
-    'ui:dialogSize'?: 'sm' | 'lg' | 'xl' | 'full';
-    'ui:submitLabel'?: string;
-    'ui:cancelLabel'?: string;
-    'ui:help'?: string;
-    'ui:placeholder'?: string;
-    'ui:icon'?: string;
-    'ui:iconPosition'?: 'start' | 'end';
-    'ui:datalist'?: string[];
-    'ui:rows'?: number;
-    'ui:min'?: number;
-    'ui:max'?: number;
-    'ui:dropdown'?: boolean;
-    'ui:autocomplete'?: string;
-    'ui:accept'?: string;
-    'ui:multiple'?: boolean;
-    'ui:maxFiles'?: number;
-    'ui:maxSize'?: number;
-    'ui:submitOnEnter'?: boolean;
-    'ui:spellcheck'?: boolean;
-    'ui:order'?: string[];
-  };
-}
-
-export interface JsonFormEvent<T = any> extends CustomEvent {
-  detail: T;
-}
-
-export interface JsonFormSubmitDetail {
-  json: any;
-  formData: FormData;
-  valid: boolean;
-  issues: Array<{ path?: string; message: string }>;
-}
-
-export interface JsonFormValueChangeDetail {
-  name: string;
-  value: any;
-  validity: { valid: boolean };
-}
-
-export interface JsonFormArrayEventDetail {
-  path: string;
-  index?: number;
-  from?: number;
-  to?: number;
-}
-
-export interface JsonFormDialogEventDetail {
-  path: string;
-  schema?: any;
-  value?: any;
-}
-
-export interface JsonFormRendererContext {
-  id: string;
-  path: string;
-  label: string;
-  value: any;
-  required: boolean;
-  ui: any;
-  schema: any;
-  get: (path?: string) => any;
-  set: (value: any, path?: string) => void;
-  attrs: {
-    placeholder?: string;
-    minLength?: number;
-    maxLength?: number;
-    min?: number;
-    max?: number;
-    step?: number;
-    pattern?: string;
-    readOnly?: boolean;
-    required?: boolean;
-    autocomplete?: string;
-    list?: string;
-  };
-  host: any;
-}
-
-export type JsonFormRenderer = (context: JsonFormRendererContext) => any;
-
-export interface JsonFormEventMap {
-  'pw:schema-resolve': JsonFormEvent<{ schema: any }>;
-  'pw:compile-node': JsonFormEvent<{ path: string; schema: any; ui: any; node?: any }>;
-  'pw:choose-widget': JsonFormEvent<{ path: string; schema: any; ui: any; widget: string | null }>;
-  'pw:before-render-field': JsonFormEvent<{ path: string; schema: any; ui: any; mount?: any; render?: () => any }>;
-  'pw:render-field': JsonFormEvent<{ path: string; schema: any; node: any }>;
-  'pw:after-render-field': JsonFormEvent<{ path: string; schema: any }>;
-  'pw:value-change': JsonFormEvent<JsonFormValueChangeDetail>;
-  'pw:array-add': JsonFormEvent<JsonFormArrayEventDetail>;
-  'pw:array-remove': JsonFormEvent<JsonFormArrayEventDetail>;
-  'pw:array-reorder': JsonFormEvent<JsonFormArrayEventDetail>;
-  'pw:serialize': JsonFormEvent<JsonFormSubmitDetail>;
-  'pw:submit': JsonFormEvent<JsonFormSubmitDetail>;
-  'pw:dialog-open': JsonFormEvent<JsonFormDialogEventDetail>;
-  'pw:dialog-submit': JsonFormEvent<JsonFormDialogEventDetail>;
-}
-
-declare global {
-  interface HTMLElementTagNameMap {
-    'pds-jsonform': SchemaForm;
-  }
-}
-
-export class SchemaForm extends HTMLElement {
-  // Properties
-  jsonSchema: any;
-  uiSchema: UISchema;
-  options: JsonFormOptions;
-  values: any;
-  action?: string;
-  method: 'get' | 'post' | 'dialog';
-  disabled: boolean;
-  hideActions: boolean;
-  submitLabel: string;
-  resetLabel: string;
-  hideReset: boolean;
-  hideSubmit: boolean;
-
-  // Methods
-  defineRenderer(widgetKey: string, renderer: JsonFormRenderer): void;
-  useValidator(validator: (data: any, schema: any) => Promise<{ valid: boolean; errors?: Array<{ path?: string; message: string }> }>): void;
-  getValuesFlat(): Record<string, any>;
-  serialize(): { json: any; formData: FormData };
-  submit(): Promise<JsonFormSubmitDetail>;
-
-  // Event listeners
-  addEventListener<K extends keyof JsonFormEventMap>(
-    type: K,
-    listener: (ev: JsonFormEventMap[K]) => any,
-    options?: boolean | AddEventListenerOptions
-  ): void;
-  addEventListener(
-    type: string,
-    listener: EventListenerOrEventListenerObject,
-    options?: boolean | AddEventListenerOptions
-  ): void;
-  removeEventListener<K extends keyof JsonFormEventMap>(
-    type: K,
-    listener: (ev: JsonFormEventMap[K]) => any,
-    options?: boolean | EventListenerOptions
-  ): void;
-  removeEventListener(
-    type: string,
-    listener: EventListenerOrEventListenerObject,
-    options?: boolean | EventListenerOptions
-  ): void;
-}
+/**
+ * Public PDS runtime object exported to consumers.
+ *
+ * This object exposes the core runtime building blocks for the Pure Design System.
+ * It intentionally provides a small, stable surface area so consuming apps can:
+ * - programmatically generate design system artifacts (via `Generator`),
+ * - adopt styles into Shadow DOM (via `adoptLayers` / `adoptPrimitives`),
+ * - query runtime mode and obtain constructable stylesheets (via `registry`).
+ *
+ * Common events in the PDS ecosystem (emitted by other packages/components):
+ * - `design-updated` — emitted by the designer component when the in-memory design changes (detail: { config }).
+ * - `pds-generated` — emitted by the PDS configurator when generation completes (detail: { modules, meta }).
+ * - `pds-error` — emitted by the PDS configurator when generation fails (detail: Error).
+ *
+ * Error handling notes:
+ * - Methods that perform dynamic imports (e.g. `adoptLayers` via the registry) may log and return fallbacks
+ *   rather than throwing; consumers should check return values (e.g. null) and listen for `pds-error` in UI flows.
+ * - `createStylesheet(css)` will throw synchronously if the provided CSS cannot be parsed by the browser's
+ *   `CSSStyleSheet.replaceSync()` — callers should guard invalid input or wrap calls in try/catch.
+ */
+export type PDSAPI = {
+    /**
+     * - Generator class to produce design system assets
+     */
+    Generator: typeof import("./pds-core/pds-generator.js").Generator;
+    /**
+     * - Singleton runtime registry for live/static mode
+     */
+    registry: import("./pds-core/pds-registry.js").PDSRegistry;
+    /**
+     * - Ontology helpers and metadata for components
+     */
+    ontology: any;
+    /**
+     * - Adopt multiple layers into a ShadowRoot. May log errors and fallback to additionalSheets when static imports fail.
+     */
+    adoptLayers: (shadowRoot: ShadowRoot, layers?: string[], additionalSheets?: CSSStyleSheet[]) => Promise<void>;
+    /**
+     * - Adopt primitives layer into a ShadowRoot. Designed as a convenience for components.
+     */
+    adoptPrimitives: (shadowRoot: ShadowRoot, additionalSheets?: CSSStyleSheet[]) => Promise<void>;
+    /**
+     * - Create a constructable stylesheet from CSS text.
+     */
+    createStylesheet: (css: string) => CSSStyleSheet;
+};
+/** @type {PDSAPI & PDSBase} */
+export const PDS: PDSAPI & PDSBase;
+/**
+ * Validate a design configuration for accessibility sanity checks.
+ * Currently validates color contrast for primary buttons and base surface text
+ * in both light and dark themes.
+ *
+ * @param {object} designConfig - A full or partial PDS config object
+ * @param {object} [options]
+ * @param {number} [options.minContrast=4.5] - Minimum contrast ratio for normal text
+ * @returns {{ ok: boolean, issues: Array<{path:string, message:string, ratio:number, min:number, context?:string}> }}
+ */
+export function validateDesign(designConfig?: object, options?: {
+    minContrast?: number;
+}): {
+    ok: boolean;
+    issues: Array<{
+        path: string;
+        message: string;
+        ratio: number;
+        min: number;
+        context?: string;
+    }>;
+};
+/**
+ * Public PDS runtime object exported to consumers.
+ *
+ * This object exposes the core runtime building blocks for the Pure Design System.
+ * It intentionally provides a small, stable surface area so consuming apps can:
+ * - programmatically generate design system artifacts (via `Generator`),
+ * - adopt styles into Shadow DOM (via `adoptLayers` / `adoptPrimitives`),
+ * - query runtime mode and obtain constructable stylesheets (via `registry`).
+ *
+ * Common events in the PDS ecosystem (emitted by other packages/components):
+ * - `design-updated` — emitted by the designer component when the in-memory design changes (detail: { config }).
+ * - `pds-generated` — emitted by the PDS configurator when generation completes (detail: { modules, meta }).
+ * - `pds-error` — emitted by the PDS configurator when generation fails (detail: Error).
+ *
+ * Error handling notes:
+ * - Methods that perform dynamic imports (e.g. `adoptLayers` via the registry) may log and return fallbacks
+ *   rather than throwing; consumers should check return values (e.g. null) and listen for `pds-error` in UI flows.
+ * - `createStylesheet(css)` will throw synchronously if the provided CSS cannot be parsed by the browser's
+ *   `CSSStyleSheet.replaceSync()` — callers should guard invalid input or wrap calls in try/catch.
+ *
+ * @typedef {Object} PDSAPI
+ * @property {typeof import("./pds-core/pds-generator.js").Generator} Generator - Generator class to produce design system assets
+ * @property {import("./pds-core/pds-registry.js").PDSRegistry} registry - Singleton runtime registry for live/static mode
+ * @property {any} ontology - Ontology helpers and metadata for components
+ * @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 {(el: Element) => import("./pds-core/pds-ontology.js").ComponentDef | null} findComponentForElement - Helper to find a component definition for a DOM element
+ */
+/**
+ * Workspace for the Pure Design System runtime API
+ * PDS is now an EventTarget so consumers can subscribe to a single, consistent
+ * event bus instead of listening on window/document or individual elements.
+ */
+declare class PDSBase extends EventTarget {
+}
+export {};
+//# sourceMappingURL=pds.d.ts.map

package/dist/types/public/assets/pds/components/pds-jsonform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pds-jsonform.d.ts","sourceRoot":"","sources":["../../../../../../public/assets/pds/components/pds-jsonform.js"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IACE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAcE;IAGF,yBAEC;IAYC,gBAA2B;IAC3B,cAAyB;IACzB,aAAwB;IACxB,YAAuB;IACvB,eAAoB;IACpB,qBAAwB;IACxB,oBAA2B;IAC3B,mBAAyB;IACzB,mBAAsB;IACtB,oBAAuB;IAiBzB,8CAEC;IACD,4BAEC;IAGD,oBAEC;IAeD;;;MAIC;IAED,uBAEC;IAGD,+BAyBC;IA6ND,cA8CC;;CA6yCF"}
+{"version":3,"file":"pds-jsonform.d.ts","sourceRoot":"","sources":["../../../../../../public/assets/pds/components/pds-jsonform.js"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IACE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAcE;IAGF,yBAEC;IAYC,gBAA2B;IAC3B,cAAyB;IACzB,aAAwB;IACxB,YAAuB;IACvB,eAAoB;IACpB,qBAAwB;IACxB,oBAA2B;IAC3B,mBAAyB;IACzB,mBAAsB;IACtB,oBAAuB;IAiBzB,8CAEC;IACD,4BAEC;IAGD,oBAEC;IAkBD;;;MAIC;IAED,uBAEC;IAGD,+BAyBC;IA+ND,cA8CC;;CA+4CF"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pure-ds/core",
   "shortname": "pds",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "description": "Pure Design System - Why develop a Design System when you can generate one?",
   "repository": {
     "type": "git",