@mhmo91/schmancy 0.8.6 → 0.9.2

package/mixins/baseElement.ts

@@ -4,18 +4,104 @@ import { Subject, fromEvent, Observable } from 'rxjs'
 import { takeUntil } from 'rxjs/operators'
 import { classMap } from 'lit/directives/class-map.js'
 import { styleMap } from 'lit/directives/style-map.js'
-import { discoverComponent } from './discovery.service'
+import { discoverComponent, DISCOVER_EVENT, DISCOVER_RESPONSE_EVENT, type DiscoverRequest } from './discovery.service'
+import { consume } from '@lit/context'
+import { themeContext } from '../src/theme/context'
+import type { TSchmancyTheme } from '../src/theme/theme.interface'
 
 export declare class IBaseMixin {
 	disconnecting: Subject<boolean>
 	classMap: typeof classMap
 	styleMap: typeof styleMap
 	discover<T extends HTMLElement>(tag: string): Observable<T | null>
+	readonly stableId: string
+	uid: string
+	/**
+	 * Current locale from theme context. Use with Intl.NumberFormat/DateTimeFormat.
+	 * Defaults to navigator.language if no theme provider is found.
+	 * @example new Intl.NumberFormat(this.locale).format(1234.56)
+	 */
+	readonly locale: string
+	dispatchScopedEvent<T>(eventName: string, detail?: T, options?: { bubbles?: boolean; composed?: boolean }): void
 }
 
 export const BaseElement = <T extends Constructor<LitElement>>(superClass: T) => {
 	class BaseElement extends superClass {
 		disconnecting = new Subject<boolean>()
+		private _stableId?: string
+		private _uid?: string
+
+		@consume({ context: themeContext, subscribe: true })
+		private _theme?: Partial<TSchmancyTheme>
+
+		/** Current locale from theme context. Falls back to navigator.language. */
+		get locale(): string {
+			return this._theme?.locale ?? (typeof navigator !== 'undefined' ? navigator.language : 'de-DE')
+		}
+
+		/** Stable ID from DOM path - lazy, only computed on first access */
+		get stableId(): string {
+			if (this._stableId) return this._stableId
+			const path: string[] = []
+			for (let el: Element | null = this; el?.parentElement && path.length < 5; el = el.parentElement) {
+				const tag = el.tagName.toLowerCase()
+				const siblings = Array.from(el.parentElement.children).filter(c => c.tagName === el!.tagName)
+				path.unshift(siblings.length > 1 ? `${tag}:nth-of-type(${siblings.indexOf(el) + 1})` : tag)
+			}
+			const hash = Array.from(path.join('>')).reduce((h, c) => Math.imul(31, h) + c.charCodeAt(0) | 0, 0)
+			return this._stableId = `el-${Math.abs(hash).toString(36)}`
+		}
+
+		/**
+		 * Unique instance ID - can be overridden via attribute, otherwise auto-generated.
+		 * Usage: <my-component uid="custom-id"> or let it auto-generate
+		 */
+		get uid(): string {
+			// Check if uid was set via attribute
+			const attrUid = this.getAttribute('uid')
+			if (attrUid) return attrUid
+
+			// Auto-generate if not set
+			if (!this._uid) {
+				this._uid = `el-${crypto.randomUUID()}`
+			}
+			return this._uid
+		}
+
+		set uid(value: string) {
+			if (value) {
+				this.setAttribute('uid', value)
+			} else {
+				this.removeAttribute('uid')
+			}
+		}
+
+		/**
+		 * Dispatch an event scoped to this component instance.
+		 * Emits BOTH scoped event (eventName::uid) and generic event for backward compatibility.
+		 * This prevents event collision between multiple instances of the same component.
+		 */
+		dispatchScopedEvent<T>(eventName: string, detail?: T, options: { bubbles?: boolean; composed?: boolean } = {}): void {
+			const { bubbles = false, composed = true } = options
+
+			// Emit scoped event for new code
+			this.dispatchEvent(
+				new CustomEvent(`${eventName}::${this.uid}`, {
+					detail,
+					bubbles,
+					composed,
+				})
+			)
+
+			// Emit generic event for backward compatibility
+			this.dispatchEvent(
+				new CustomEvent(eventName, {
+					detail,
+					bubbles,
+					composed,
+				})
+			)
+		}
 
 		classMap(classes: Record<string, boolean>) {
 			const newClasses: Record<string, boolean> = {}
@@ -45,6 +131,7 @@ export const BaseElement = <T extends Constructor<LitElement>>(superClass: T) =>
 			const whereAreYouEvent = `${tagName}-where-are-you`
 			const hereIAmEvent = `${tagName}-here-i-am`
 
+			// 1. Component tag discovery (e.g., 'schmancy-fancy-where-are-you')
 			fromEvent(window, whereAreYouEvent)
 				.pipe(takeUntil(this.disconnecting))
 				.subscribe(() => {
@@ -56,6 +143,36 @@ export const BaseElement = <T extends Constructor<LitElement>>(superClass: T) =>
 						}),
 					)
 				})
+
+			// 2. CSS selector discovery (e.g., '#app-card-melanie', '.my-class', '[uid="xyz"]')
+			fromEvent<CustomEvent<DiscoverRequest>>(window, DISCOVER_EVENT)
+				.pipe(takeUntil(this.disconnecting))
+				.subscribe(({ detail: { selector, requestId } }) => {
+					let found: Element | null = null
+
+					// Check if selector matches this component's id or uid
+					if (selector.startsWith('#')) {
+						const id = selector.slice(1)
+						if (this.id === id || this.uid === id) {
+							found = this
+						}
+					}
+
+					// Check our shadow DOM for matching element
+					if (!found && this.shadowRoot) {
+						found = this.shadowRoot.querySelector(selector)
+					}
+
+					if (found) {
+						window.dispatchEvent(
+							new CustomEvent(DISCOVER_RESPONSE_EVENT, {
+								detail: { requestId, element: found },
+								bubbles: true,
+								composed: true,
+							}),
+						)
+					}
+				})
 		}
 
 		// Make discover public to match the interface

package/mixins/discovery.service.ts

@@ -1,5 +1,27 @@
 import { fromEvent, timer, race, Observable } from 'rxjs'
-import { takeUntil, map, defaultIfEmpty } from 'rxjs/operators'
+import { takeUntil, map, defaultIfEmpty, take } from 'rxjs/operators'
+
+/**
+ * Global discovery event names
+ */
+const DISCOVER_EVENT = 'schmancy-discover'
+const DISCOVER_RESPONSE_EVENT = 'schmancy-discover-response'
+
+/**
+ * Discovery request detail
+ */
+interface DiscoverRequest {
+	selector: string
+	requestId: string
+}
+
+/**
+ * Discovery response detail
+ */
+interface DiscoverResponse {
+	requestId: string
+	element: HTMLElement
+}
 
 /**
  * Discover a component in the DOM using the WhereAreYou/HereIAm pattern.
@@ -58,3 +80,142 @@ export function discoverAnyComponent<T extends HTMLElement>(...componentTags: st
 
 	return race(...componentTags.map(tag => discoverComponent<T>(tag)))
 }
+
+/**
+ * Universal element discovery - finds ANY element by CSS selector across shadow DOM boundaries.
+ * Uses event-based discovery pattern - no DOM traversal needed.
+ *
+ * How it works:
+ * 1. Broadcasts a discovery request event on window
+ * 2. All $LitElement components receive this event and check their shadow DOM
+ * 3. If a match is found, they respond with the element
+ *
+ * @param selector - CSS selector (e.g., '#my-id', '.my-class', '[data-attr]')
+ * @param timeout - How long to wait for a response in milliseconds (default: 150)
+ * @returns Observable that emits the discovered element or null if not found
+ *
+ * @example
+ * ```typescript
+ * // Find element by ID across shadow boundaries
+ * discoverElement('#app-card-melanie').subscribe(el => {
+ *   if (el) console.log('Found:', el)
+ * })
+ *
+ * // Find element by class
+ * discoverElement('.special-button').subscribe(el => {...})
+ * ```
+ */
+export function discoverElement<T extends HTMLElement>(
+	selector: string,
+	timeout = 150,
+): Observable<T | null> {
+	const requestId = `discover-${Date.now()}-${Math.random().toString(36).slice(2)}`
+
+	return new Observable(subscriber => {
+		// Listen for response first
+		const subscription = fromEvent<CustomEvent<DiscoverResponse>>(window, DISCOVER_RESPONSE_EVENT)
+			.pipe(
+				takeUntil(timer(timeout)),
+				map(e => e.detail),
+				// Filter for our specific request
+				map(detail => (detail.requestId === requestId ? (detail.element as T) : null)),
+				// Only take the first non-null response
+				take(1),
+				defaultIfEmpty(null),
+			)
+			.subscribe(element => {
+				subscriber.next(element)
+				subscriber.complete()
+			})
+
+		// Broadcast discovery request
+		window.dispatchEvent(
+			new CustomEvent<DiscoverRequest>(DISCOVER_EVENT, {
+				detail: { selector, requestId },
+				bubbles: true,
+				composed: true,
+			}),
+		)
+
+		return () => subscription.unsubscribe()
+	})
+}
+
+/**
+ * Discover multiple elements matching a selector.
+ * Collects all responses within the timeout period.
+ *
+ * @param selector - CSS selector
+ * @param timeout - How long to collect responses (default: 150ms)
+ * @returns Observable that emits array of discovered elements
+ */
+export function discoverAllElements<T extends HTMLElement>(
+	selector: string,
+	timeout = 150,
+): Observable<T[]> {
+	const requestId = `discover-all-${Date.now()}-${Math.random().toString(36).slice(2)}`
+	const elements: T[] = []
+
+	return new Observable(subscriber => {
+		// Collect all responses
+		const subscription = fromEvent<CustomEvent<DiscoverResponse>>(window, DISCOVER_RESPONSE_EVENT)
+			.pipe(takeUntil(timer(timeout)))
+			.subscribe({
+				next: e => {
+					if (e.detail.requestId === requestId) {
+						elements.push(e.detail.element as T)
+					}
+				},
+				complete: () => {
+					subscriber.next(elements)
+					subscriber.complete()
+				},
+			})
+
+		// Broadcast discovery request
+		window.dispatchEvent(
+			new CustomEvent<DiscoverRequest>(DISCOVER_EVENT, {
+				detail: { selector, requestId },
+				bubbles: true,
+				composed: true,
+			}),
+		)
+
+		return () => subscription.unsubscribe()
+	})
+}
+
+/**
+ * Smart discovery - automatically detects if input is a CSS selector or component tag.
+ *
+ * @param query - CSS selector (starts with #, ., [) OR component tag name
+ * @param timeout - How long to wait (default: 150ms)
+ * @returns Observable that emits the discovered element or null
+ *
+ * @example
+ * ```typescript
+ * // CSS selector - uses discoverElement
+ * discover('#my-element').subscribe(...)
+ *
+ * // Component tag - uses discoverComponent
+ * discover('schmancy-fancy').subscribe(...)
+ * ```
+ */
+export function discover<T extends HTMLElement>(
+	query: string,
+	timeout = 150,
+): Observable<T | null> {
+	// Check if it's a CSS selector (starts with #, ., or [)
+	const isCssSelector = /^[#.\[]/.test(query)
+
+	if (isCssSelector) {
+		return discoverElement<T>(query, timeout)
+	}
+
+	// Otherwise treat as component tag name
+	return discoverComponent<T>(query, timeout)
+}
+
+// Export event names for use in baseElement
+export { DISCOVER_EVENT, DISCOVER_RESPONSE_EVENT }
+export type { DiscoverRequest, DiscoverResponse }

package/mixins/formField.mixin.ts

@@ -188,16 +188,21 @@ export function FormFieldMixin<T extends Constructor<LitElement>>(superClass: T)
 		}
 
 		/**
-		 * Helper method to emit change events
+		 * Helper method to emit change events using dispatchScopedEvent for instance isolation
 		 */
 		emitChange(detail: any): void {
-			this.dispatchEvent(
-				new CustomEvent('change', {
-					detail,
-					bubbles: true,
-					composed: true,
-				}),
-			)
+			// Use dispatchScopedEvent if available (from BaseElement mixin)
+			if ('dispatchScopedEvent' in this && typeof this.dispatchScopedEvent === 'function') {
+				this.dispatchScopedEvent('change', detail, { bubbles: true })
+			} else {
+				this.dispatchEvent(
+					new CustomEvent('change', {
+						detail,
+						bubbles: true,
+						composed: true,
+					}),
+				)
+			}
 		}
 	}
 

package/mixins/index.ts

@@ -1,5 +1,7 @@
 export * from './baseElement';
 export * from './constructor';
+export * from './discovery.service';
 export * from './formField.mixin';
 export * from './litElement.mixin';
+export * from './surface.mixin';
 export * from './tailwind.mixin';

package/mixins/surface.mixin.ts

@@ -0,0 +1,93 @@
+import type { Constructor } from './constructor'
+import { CSSResultGroup, CSSResultOrNative, LitElement } from 'lit'
+import { property } from 'lit/decorators.js'
+import type { TSurfaceColor } from '../src/types/surface'
+import { surfaceStyles } from '../src/surface/surface.styles'
+
+export type SchmancySurfaceFill = 'all' | 'width' | 'height' | 'auto'
+export type SchmancySurfaceRounded = 'none' | 'top' | 'left' | 'right' | 'bottom' | 'all'
+export type SchmancySurfaceElevation = 0 | 1 | 2 | 3 | 4 | 5
+
+export declare class ISurfaceMixin {
+	fill: SchmancySurfaceFill
+	rounded: SchmancySurfaceRounded
+	elevation: SchmancySurfaceElevation
+	type: TSurfaceColor
+	clickable: boolean
+}
+
+/**
+ * SurfaceMixin - Adds surface styling properties AND styles to any LitElement
+ *
+ * Uses Lit's finalizeStyles hook to inject surfaceStyles CSS for all surface type selectors.
+ * This is the recommended pattern for mixins that need to add styles.
+ *
+ * Provides these reflected properties:
+ * - `fill`: 'all' | 'width' | 'height' | 'auto' - Controls element dimensions
+ * - `rounded`: 'none' | 'top' | 'left' | 'right' | 'bottom' | 'all' - Corner rounding
+ * - `elevation`: 0-5 - Shadow depth level
+ * - `type`: TSurfaceColor - Surface color variant (26+ options)
+ *
+ * Usage:
+ * ```typescript
+ * import { SurfaceMixin } from '@mixins/surface.mixin'
+ *
+ * @customElement('my-component')
+ * class MyComponent extends SurfaceMixin(TailwindElement(css`
+ *   :host { display: block; }
+ * `)) {
+ *   // Component now has type, fill, rounded, elevation properties
+ *   // AND surfaceStyles are automatically included
+ * }
+ * ```
+ */
+export const SurfaceMixin = <T extends Constructor<LitElement>>(superClass: T) => {
+	class SurfaceMixinClass extends superClass {
+		/**
+		 * Override finalizeStyles to inject surfaceStyles.
+		 * This is the Lit-recommended way for mixins to add styles.
+		 */
+		protected static finalizeStyles(styles?: CSSResultGroup): CSSResultOrNative[] {
+			// Get parent's finalized styles using LitElement's method
+			const parentStyles = (superClass as unknown as typeof LitElement).finalizeStyles(styles)
+			// Append surfaceStyles at the end (higher specificity)
+			return [...parentStyles, surfaceStyles as CSSResultOrNative]
+		}
+
+		/**
+		 * Fill the width and/or height of the parent container.
+		 * @default 'auto'
+		 */
+		@property({ type: String, reflect: true })
+		fill: SchmancySurfaceFill = 'auto'
+
+		/**
+		 * Specifies the rounding style of the component's corners.
+		 * @default 'none'
+		 */
+		@property({ reflect: true })
+		rounded: SchmancySurfaceRounded = 'none'
+
+		/**
+		 * Defines the elevation level (shadow depth) of the surface.
+		 * @default 0
+		 */
+		@property({ type: Number, reflect: true })
+		elevation: SchmancySurfaceElevation = 0
+
+		/**
+		 * Specifies the surface type for styling.
+		 * @default 'container'
+		 */
+		@property({ reflect: true })
+		type: TSurfaceColor = 'subtle'
+
+		/**
+		 * Makes the surface interactive with hover, active states and cursor pointer.
+		 * @default false
+		 */
+		@property({ type: Boolean, reflect: true })
+		clickable = false
+	}
+	return SurfaceMixinClass as Constructor<ISurfaceMixin> & T
+}