@pure-ds/core 0.3.0

package/src/js/pds-core/pds.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 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;
+}
+
+/**
+ * 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;
+  /** 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 const PDS: {
+  /** Generator class to produce design-system artifacts programmatically. */
+  Generator: typeof Generator;
+  /** Registry singleton to query/adopt styles and control live/static behavior. */
+  registry: PDSRegistry;
+  /** Presets keyed by id (lowercased). Includes a 'default' preset derived from the baseline config. */
+  presets: Record<string, any>;
+  /** Ontology metadata about components (shapes vary by implementation) */
+  ontology: any;
+  /** Adopt multiple named layers into a ShadowRoot. See `LAYER-ARCHITECTURE.md` for layer ordering. */
+  adoptLayers: (shadowRoot: ShadowRoot, layers?: string[], additionalSheets?: CSSStyleSheet[]) => Promise<void>;
+  /** Convenience to adopt only primitives/styles commonly needed by components. */
+  adoptPrimitives: (shadowRoot: ShadowRoot, additionalSheets?: CSSStyleSheet[]) => Promise<void>;
+  /** Create a constructable stylesheet from a CSS string. May throw on invalid CSS in some browsers. */
+  createStylesheet: (css: string) => CSSStyleSheet;
+  /** Utility to inspect whether runtime is running in live mode. */
+  isLiveMode: () => boolean;
+  /** Find a component definition for a given DOM element, or null if not matched. */
+  findComponentForElement: (el: Element) => ComponentDef | null;
+  /** Primary unified entry point to start PDS in live or static mode. Default mode is 'live'. */
+  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;
+    // live-only
+    preloadStyles?: boolean;
+    criticalLayers?: string[];
+    // static-only
+    staticPaths?: Record<string, string>;
+    enhancers?: Array<any>;
+  }) => Promise<{ generator?: Generator; config: any; theme: string; autoDefiner?: any }>;
+  /** Change the current theme programmatically. Updates localStorage, data-theme attribute, and regenerates styles. */
+  setTheme: (theme: 'light' | 'dark' | 'system', options?: {
+    storageKey?: string;
+    persist?: boolean;
+  }) => Promise<string>;
+  /** Preload minimal CSS to prevent flash of unstyled content. Call before DOM content renders. */
+  preloadCritical: (config: any, options?: {
+    theme?: string;
+    layers?: string[];
+  }) => void;
+  /** EventTarget API (strongly typed for common PDS events). */
+  addEventListener: <K extends keyof PDSEventMap>(type: K, listener: (ev: PDSEventMap[K]) => any, options?: boolean | AddEventListenerOptions) => void;
+  removeEventListener: <K extends keyof PDSEventMap>(type: K, listener: (ev: PDSEventMap[K]) => any, options?: boolean | EventListenerOptions) => void;
+  dispatchEvent: (event: PDSEventMap[keyof PDSEventMap] | Event) => boolean;
+};
+
+export { PDS as default };

package/src/js/pds.d.ts

@@ -0,0 +1,408 @@
+/**
+ * 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;
+}