@mhmo91/schmancy 0.10.23 → 0.10.25

package/src/directives/working-snake.ts

@@ -0,0 +1,294 @@
+/**
+ * Working Snake Directive - Animated trail indicating active work
+ *
+ * Creates a visual "snake" effect emanating from a punch point when
+ * an employee is currently working (single check-in, no check-out yet).
+ *
+ * The animation creates a visual illusion of forward motion - dots flow
+ * rightward with a subtle sine wave oscillation, representing time passing.
+ *
+ * Follows patterns from art.ts:
+ * - RequestAnimationFrame for smooth 60fps
+ * - Intersection Observer to pause when off-screen
+ * - GPU-accelerated CSS transforms
+ * - Object pooling for performance
+ *
+ * @example
+ * ```ts
+ * html`
+ *   <div ${workingSnake({ active: true, color: 'var(--md-sys-color-primary)' })}>
+ *     <div class="punch-dot"></div>
+ *   </div>
+ * `
+ * ```
+ */
+
+import type { ElementPart } from 'lit'
+import { noChange } from 'lit'
+import { AsyncDirective, directive } from 'lit/async-directive.js'
+
+export interface WorkingSnakeOptions {
+	/** Whether the snake animation is active */
+	active: boolean
+	/** CSS color value for the snake segments */
+	color?: string
+	/** Width in pixels the snake should travel */
+	travelWidth?: number
+}
+
+interface Segment {
+	element: SVGCircleElement
+	progress: number // 0 to 1 - position along the path
+	phase: number // offset for sine wave
+}
+
+interface SnakeState {
+	active: boolean
+	color: string
+	travelWidth: number
+	element: HTMLElement
+	overlayElement?: HTMLDivElement
+	svg?: SVGSVGElement
+	segments: Segment[]
+	animationId?: number
+	isVisible: boolean
+	observer?: IntersectionObserver
+	startTime: number
+}
+
+const SEGMENT_COUNT = 10
+const CYCLE_DURATION = 3000 // 3 seconds for full cycle
+const SINE_AMPLITUDE = 3 // vertical oscillation in pixels
+const HEAD_RADIUS = 4
+const TAIL_RADIUS = 1.5
+
+class WorkingSnakeDirective extends AsyncDirective {
+	private state: SnakeState | null = null
+
+	render(_options: WorkingSnakeOptions) {
+		return noChange
+	}
+
+	override update(part: ElementPart, [options]: [WorkingSnakeOptions]) {
+		const element = part.element as HTMLElement
+		// Auto-calculate travelWidth to use 100% of container if not specified
+		const calculatedWidth = element.offsetWidth || element.clientWidth
+		const { active, color = 'var(--md-sys-color-primary)', travelWidth = calculatedWidth } = options
+
+		// If becoming inactive, cleanup
+		if (!active && this.state) {
+			this.cleanup()
+			return noChange
+		}
+
+		// If not active and no state, nothing to do
+		if (!active) {
+			return noChange
+		}
+
+		// If options changed, recreate
+		if (this.state && (this.state.color !== color || this.state.travelWidth !== travelWidth)) {
+			this.cleanup()
+		}
+
+		// Initialize if needed
+		if (!this.state) {
+			this.state = {
+				active: true,
+				color,
+				travelWidth,
+				element,
+				segments: [],
+				isVisible: true,
+				startTime: performance.now(),
+			}
+
+			// Ensure element has relative positioning for absolute overlay
+			const computedStyle = getComputedStyle(element)
+			if (computedStyle.position === 'static') {
+				element.style.position = 'relative'
+			}
+
+			this.createOverlay()
+			this.setupVisibilityObserver()
+			this.startAnimation()
+		}
+
+		return noChange
+	}
+
+	private createOverlay() {
+		if (!this.state) return
+
+		const { element, color, travelWidth } = this.state
+
+		// Create overlay container - starts from the punch point
+		const overlay = document.createElement('div')
+		overlay.className = 'working-snake-overlay'
+		overlay.style.cssText = `
+			position: absolute;
+			top: 50%;
+			left: 0;
+			width: ${travelWidth}px;
+			height: 20px;
+			transform: translateY(-50%);
+			pointer-events: none;
+			overflow: visible;
+			z-index: 5;
+		`
+
+		// Create SVG
+		const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg')
+		svg.setAttribute('width', '100%')
+		svg.setAttribute('height', '100%')
+		svg.setAttribute('viewBox', `0 0 ${travelWidth} 20`)
+		svg.setAttribute('preserveAspectRatio', 'none')
+		svg.style.cssText = `
+			position: absolute;
+			top: 0;
+			left: 0;
+			width: 100%;
+			height: 100%;
+			overflow: visible;
+		`
+
+		// Create segments (circles)
+		const segments: Segment[] = []
+		for (let i = 0; i < SEGMENT_COUNT; i++) {
+			const circle = document.createElementNS('http://www.w3.org/2000/svg', 'circle')
+
+			// Calculate radius - head is bigger, tail is smaller
+			const normalizedIndex = i / (SEGMENT_COUNT - 1)
+			const radius = HEAD_RADIUS - normalizedIndex * (HEAD_RADIUS - TAIL_RADIUS)
+
+			circle.setAttribute('r', radius.toString())
+			circle.setAttribute('fill', color)
+			circle.setAttribute('cy', '10') // Center vertically in 20px height
+			circle.style.willChange = 'transform, opacity'
+
+			// Stagger initial progress and phase for organic movement
+			const progress = (i / SEGMENT_COUNT) * 0.5 // Start staggered
+			const phase = (i / SEGMENT_COUNT) * Math.PI * 2
+
+			segments.push({ element: circle, progress, phase })
+			svg.appendChild(circle)
+		}
+
+		overlay.appendChild(svg)
+		element.appendChild(overlay)
+
+		this.state.overlayElement = overlay
+		this.state.svg = svg
+		this.state.segments = segments
+	}
+
+	private setupVisibilityObserver() {
+		if (!this.state || typeof IntersectionObserver === 'undefined') return
+
+		this.state.observer = new IntersectionObserver(
+			entries => {
+				if (!this.state) return
+				const isVisible = entries[0].isIntersecting
+
+				if (isVisible && !this.state.isVisible) {
+					this.state.isVisible = true
+					this.startAnimation()
+				} else if (!isVisible && this.state.isVisible) {
+					this.state.isVisible = false
+					if (this.state.animationId) {
+						cancelAnimationFrame(this.state.animationId)
+						this.state.animationId = undefined
+					}
+				}
+			},
+			{ threshold: 0 }
+		)
+
+		this.state.observer.observe(this.state.element)
+	}
+
+	private startAnimation() {
+		if (!this.state || !this.state.isVisible) return
+
+		const animate = (currentTime: number) => {
+			if (!this.state || !this.state.isVisible) return
+
+			const elapsed = currentTime - this.state.startTime
+			const cycleProgress = (elapsed % CYCLE_DURATION) / CYCLE_DURATION
+
+			const { segments, travelWidth } = this.state
+
+			// Animate each segment
+			for (let i = 0; i < segments.length; i++) {
+				const segment = segments[i]
+
+				// Each segment is offset in the cycle
+				const segmentOffset = i / SEGMENT_COUNT
+				let progress = (cycleProgress + segmentOffset) % 1
+
+				// Ease the progress for more organic feel (ease-out)
+				const easedProgress = 1 - Math.pow(1 - progress, 2)
+
+				// Calculate x position
+				const x = easedProgress * travelWidth
+
+				// Calculate y position with sine wave
+				const sineWave = Math.sin(progress * Math.PI * 4 + segment.phase) * SINE_AMPLITUDE
+				const y = 10 + sineWave
+
+				// Calculate opacity - fade out as it travels
+				const baseOpacity = i === 0 ? 0.9 : 0.7 - (i / SEGMENT_COUNT) * 0.55
+				const fadeOut = 1 - easedProgress * 0.7
+				const opacity = baseOpacity * fadeOut
+
+				// Head has subtle pulse
+				let scale = 1
+				if (i === 0) {
+					const pulse = Math.sin(currentTime / 200) * 0.1 + 1
+					scale = pulse
+				}
+
+				// Apply transforms
+				segment.element.setAttribute('cx', x.toFixed(1))
+				segment.element.setAttribute('cy', y.toFixed(1))
+				segment.element.setAttribute('opacity', Math.max(0.1, opacity).toFixed(2))
+
+				if (scale !== 1) {
+					segment.element.style.transform = `scale(${scale.toFixed(2)})`
+					segment.element.style.transformOrigin = `${x}px ${y}px`
+				}
+			}
+
+			this.state.animationId = requestAnimationFrame(animate)
+		}
+
+		this.state.animationId = requestAnimationFrame(animate)
+	}
+
+	private cleanup() {
+		if (!this.state) return
+
+		// Cancel animation
+		if (this.state.animationId) {
+			cancelAnimationFrame(this.state.animationId)
+		}
+
+		// Disconnect observer
+		if (this.state.observer) {
+			this.state.observer.disconnect()
+		}
+
+		// Remove overlay
+		if (this.state.overlayElement) {
+			this.state.overlayElement.remove()
+		}
+
+		this.state = null
+	}
+
+	override disconnected() {
+		this.cleanup()
+	}
+}
+
+export const workingSnake = directive(WorkingSnakeDirective)

package/src/icons/icon.ts

@@ -1,56 +1,79 @@
 import { SchmancyElement } from '@mixins/index'
-import { css, html } from 'lit'
-import { customElement } from 'lit/decorators.js'
+import { css, html, nothing, svg } from 'lit'
+import { customElement, state } from 'lit/decorators.js'
 
+declare global {
+  interface Window {
+    __siIcons?: Record<string, string>
+  }
+}
+
+/**
+ * @element schmancy-icon
+ * Renders a Material Symbol inline as SVG — path data comes from
+ * window.__siIcons populated by the schmancy-icons Vite plugin.
+ *
+ * Size: set font-size on the host via Tailwind (e.g. class="text-2xl").
+ * Color: inherits currentColor.
+ * Active fill: use the "-fill" variant name: "home-fill".
+ *
+ * Usage:
+ *   <schmancy-icon>home</schmancy-icon>
+ *   <schmancy-icon class="text-lg text-primary-default">delete</schmancy-icon>
+ *   <schmancy-icon>${active ? 'home-fill' : 'home'}</schmancy-icon>
+ */
 @customElement('schmancy-icon')
 export default class SchmancyIcon extends SchmancyElement {
 	static styles = [css`
 		:host {
-			font-family: 'Material Symbols Outlined';
-			font-size: 24px;
-			width: 1em;
-			height: 1em;
-			color: inherit;
-			font-variation-settings: inherit;
-			font-weight: 400;
 			display: inline-flex;
-			font-style: normal;
 			place-items: center;
 			place-content: center;
-			line-height: 1;
-			overflow: hidden;
-			letter-spacing: normal;
-			text-transform: none;
-			user-select: none;
-			white-space: nowrap;
+			font-size: 24px;
+			width: 1em;
+			height: 1em;
 			flex-shrink: 0;
-			-webkit-font-smoothing: antialiased;
-			text-rendering: optimizeLegibility;
-		}
-
-		::slotted(svg) {
-			fill: currentColor;
+			color: inherit;
 		}
 
-		::slotted(*) {
-			height: 100%;
+		svg {
 			width: 100%;
+			height: 100%;
+			fill: currentColor;
+			overflow: visible;
 		}
 	`]
 
+	@state() private _name = ''
+
+	private _observer?: MutationObserver
+
 	override connectedCallback(): void {
 		super.connectedCallback()
-		const ariaHidden = this.getAttribute('aria-hidden')
-		if (ariaHidden === 'false') {
-			this.removeAttribute('aria-hidden')
-			return
-		}
+		this._name = this.textContent?.trim() ?? ''
+		this._observer = new MutationObserver(() => {
+			this._name = this.textContent?.trim() ?? ''
+		})
+		this._observer.observe(this, { childList: true, characterData: true, subtree: true })
 		this.setAttribute('aria-hidden', 'true')
 		this.setAttribute('translate', 'no')
 	}
 
+	override disconnectedCallback(): void {
+		super.disconnectedCallback()
+		this._observer?.disconnect()
+	}
+
 	protected override render(): unknown {
-		return html`<slot></slot>`
+		const path = window.__siIcons?.[this._name]
+		return html`
+			<slot style="display:none"></slot>
+			${path
+				? html`<svg viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg">
+						${svg`<path d="${path}"/>`}
+					</svg>`
+				: nothing}
+		`
 	}
 }
 

package/src/json/json.ts

@@ -41,7 +41,7 @@ export class SchmancyJson extends SchmancyElement {
 				@click=${this.copyJSON}
 			>
 				<div class="flex items-center justify-between mb-1">
-					<schmancy-icon size="12px" class="text-on-surface-variant">content_copy</schmancy-icon>
+					<schmancy-icon class="text-xs text-on-surface-variant">content_copy</schmancy-icon>
 				</div>
 				<pre class="text-[10px] leading-tight">${unsafeHTML(highlighted)}</pre>
 			</div>

package/src/navigation-rail/navigation-rail-item.ts

@@ -264,10 +264,11 @@ export class SchmancyNavigationRailItem extends SchmancyElement {
 
 		// M3 Navigation Rail Item classes with theme integration
 		const containerClasses = this.classMap({
-			// Layout & Spacing (M3 56px height, 12px vertical padding)
-			'flex flex-col items-center justify-center': true,
+			// Layout & Spacing (M3 56px minimum hit target; vertical padding is consumer-controlled)
+			// justify-start pins the icon to the row top so its vertical center is invariant
+			// across label-visibility states — consumer rows can align siblings to it.
+			'flex flex-col items-center justify-start': true,
 			'min-h-14 w-full': true, // min-h-14 = 56px
-			'py-3': true, // py-3 = 12px top/bottom
 			'gap-1': true, // gap-1 = 4px
 
 			// M3 Shape & Interaction
@@ -383,15 +384,9 @@ export class SchmancyNavigationRailItem extends SchmancyElement {
 							when(
 								this.icon,
 								() => html`
-									<span
-										class=${iconClasses}
-										part="icon-text"
-										style="font-family: 'Material Symbols Outlined'; font-variation-settings: 'FILL' ${this.active
-											? '1'
-											: '0'}, 'wght' 400, 'GRAD' 0, 'opsz' ${this.nested ? '20' : '24'};"
-									>
-										${this.icon}
-									</span>
+									<schmancy-icon class=${iconClasses} part="icon-text">
+										${this.active ? `${this.icon}-fill` : this.icon}
+									</schmancy-icon>
 								`,
 							),
 					)}

package/src/navigation-rail/navigation-rail.ts

@@ -379,8 +379,6 @@ export class SchmancyNavigationRail extends SchmancyElement {
 			// Layout & Structure
 			'flex flex-col h-full': true,
 			'box-border relative': true,
-			'py-2': true,
-
 
 			// M3 Colors & Theme
 			'bg-container-lowest text-surface-on': true,

package/src/table/table.ts

@@ -182,9 +182,9 @@ export class SchmancyDataTable<T extends Record<string, any> = any> extends Schm
 		return html`
 			<span class="ml-1">
 				${this.sortDirection === 'asc'
-					? html`<schmancy-icon size="16px">arrow_upward</schmancy-icon>`
+					? html`<schmancy-icon class="text-base">arrow_upward</schmancy-icon>`
 					: this.sortDirection === 'desc'
-						? html`<schmancy-icon size="16px">arrow_downward</schmancy-icon>`
+						? html`<schmancy-icon class="text-base">arrow_downward</schmancy-icon>`
 						: null}
 			</span>
 		`

package/src/theme/theme-audio-player.ts

@@ -349,7 +349,7 @@ export class SchmancyThemeAudioPlayer extends SchmancyElement {
 						this.currentThemeName !== 'default',
 						() => html`
 							<schmancy-button variant="text" size="sm" @click=${() => this.resetToDefaults()}>
-								<schmancy-icon size="16px">refresh</schmancy-icon>
+								<schmancy-icon class="text-base">refresh</schmancy-icon>
 								Reset
 							</schmancy-button>
 						`

package/types/mixins/SchmancyElement.d.ts

@@ -46,4 +46,35 @@ export declare class SchmancyElement extends SchmancyElementBase {
     removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
     disconnectedCallback(): void;
 }
+/**
+ * Decorator: `@schmancyElement('tag-name')`. The standard way to register
+ * a `SchmancyElement` subclass.
+ *
+ * Drop-in replacement for Lit's `@customElement`. The difference is
+ * timing: this decorator wraps the prototype's methods with
+ * `_activeHost.run` BEFORE calling `customElements.define`.
+ *
+ * Why this matters: the HTML spec captures the element's lifecycle
+ * callback references (`connectedCallback`, `disconnectedCallback`, etc.)
+ * off the prototype at `customElements.define` time, and the browser
+ * invokes those cached references for the element's lifecycle — it does
+ * NOT re-look-up the prototype each time. SchmancyElement's constructor
+ * installs the active-host wrap on first instantiation, which is strictly
+ * later than `define`, so the browser ends up calling unwrapped
+ * lifecycle callbacks. Reads inside `connectedCallback` then fall through
+ * to `document.activeElement`, miss the enclosing `<schmancy-context>`,
+ * and resolve to the module-scoped global instead of the isolated copy.
+ *
+ * Use this decorator for any subclass that:
+ *   - Reads or writes a state-singleton inside `connectedCallback` or
+ *     `disconnectedCallback`, AND
+ *   - May appear inside a `<schmancy-context>` subtree.
+ *
+ * For elements that never touch state in lifecycle callbacks, plain
+ * `@customElement` from `lit/decorators.js` still works — the
+ * constructor's wrap covers everything else (render, class methods,
+ * event handlers attached via the prototype). The two decorators are
+ * interchangeable for those cases.
+ */
+export declare function schmancyElement(tagName: string): <T extends CustomElementConstructor>(cls: T) => T;
 export {};

package/types/src/badge/badge.d.ts

@@ -68,7 +68,7 @@ export declare class SchmancyBadgeV2 extends SchmancyElement {
      * Get icon size based on badge size with harmonious proportions
      * Using golden ratio-inspired proportions relative to text size
      */
-    private getIconSize;
+    private getIconSizeClass;
     /**
      * Get additional styling for specific sizes
      */

package/types/src/directives/ai-badge.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AI Badge Directive — Indicator for AI-generated content.
+ * Pulses gently on the host element; color routed through theme tokens.
+ */
+import { AsyncDirective } from 'lit/async-directive.js';
+import type { ElementPart } from 'lit';
+declare class AIBadgeDirective extends AsyncDirective {
+    private state;
+    render(_message?: string): symbol;
+    update(part: ElementPart, [message]: [string?]): symbol;
+    private cleanup;
+    disconnected(): void;
+}
+export declare const aiBadge: (_message?: string) => import("lit-html/directive").DirectiveResult<typeof AIBadgeDirective>;
+export {};

package/types/src/directives/art/art.directive.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Art Directive — GPU-accelerated decorative overlays.
+ * Lazy-initialised, IntersectionObserver-paused, RAF-driven, particle-pooled.
+ */
+import type { ElementPart } from 'lit';
+import { AsyncDirective } from 'lit/async-directive.js';
+import type { ArtOptions } from './types';
+declare class ArtDirective extends AsyncDirective {
+    private state;
+    render(_options: ArtOptions): symbol;
+    update(part: ElementPart, [options]: [ArtOptions]): symbol;
+    private initializeResources;
+    private setupVisibilityObserver;
+    private startAnimation;
+    private cleanup;
+    disconnected(): void;
+}
+export declare const art: (_options: ArtOptions) => import("lit-html/directive").DirectiveResult<typeof ArtDirective>;
+export {};

package/types/src/directives/art/effects/error.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Error Effect — Electrical/warning glow on edges with static particles and lightning bolts.
+ * 2.5-second main pulse cycle.
+ */
+import type { ArtState } from '../types';
+export declare function createErrorOverlay(state: ArtState): void;
+export declare function animateError(state: ArtState, currentTime: number): void;

package/types/src/directives/art/effects/funkhaus.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Funkhaus Effect — Grid wave animation with window panes glowing diagonally.
+ * 7-second cycle, exponential intensity curve.
+ */
+import type { ArtState } from '../types';
+export declare function createFunkhausOverlay(state: ArtState): void;
+export declare function animateFunkhaus(state: ArtState, currentTime: number): void;

package/types/src/directives/art/effects/howl.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Howl Effect — Steampunk gears, sparkles, crystals, rising steam.
+ * 17-second cycle, layered animations.
+ */
+import type { ArtState } from '../types';
+export declare function createHowlOverlay(state: ArtState): void;
+export declare function animateHowl(state: ArtState, currentTime: number): void;

package/types/src/directives/art/effects/samwa.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Samwa Effect — Ambient geometric particles with gentle physics.
+ * Color-responsive palette derived from the passed `color` prop; organic wind system.
+ */
+import type { ArtState } from '../types';
+export declare function createSamwaOverlay(state: ArtState): void;
+export declare function animateSamwa(state: ArtState, currentTime: number): void;

package/types/src/directives/art/effects/snow.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Snow Effect — Peaceful winter snowfall with snow/leaf shapes.
+ * Same physics pattern as samwa effect but tuned for slower, floatier fall.
+ */
+import type { ArtState } from '../types';
+export declare function createSnowOverlay(state: ArtState): void;
+export declare function animateSnow(state: ArtState, currentTime: number): void;

package/types/src/directives/art/effects/starfield.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Starfield Effect — Night sky with twinkling stars.
+ *
+ * 6 groups × 7 stars using CSS radial-gradient backgrounds.
+ * Wave-by-wave fade-in (group 0 first, then 1, 2, …); gentle twinkle once visible.
+ * Opacity driven by RAF instead of CSS @keyframes to avoid Shadow DOM scoping.
+ */
+import type { ArtState } from '../types';
+export declare function createStarfieldOverlay(state: ArtState): void;
+export declare function animateStarfield(state: ArtState, currentTime: number): void;

package/types/src/directives/art/index.d.ts

@@ -0,0 +1,2 @@
+export { art } from './art.directive';
+export type { ArtEffect, ArtOptions } from './types';

package/types/src/directives/art/particle-pool.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Particle Pool
+ *
+ * Reusable object pool for SVG particles to avoid constant creation/destruction.
+ * Used by samwa (leaves), howl (steam), error (lightning), snow (flakes) effects.
+ */
+export declare class ParticlePool<T extends SVGElement> {
+    private pool;
+    private active;
+    private factory;
+    constructor(factory: () => T, initialSize?: number);
+    acquire(): T;
+    release(particle: T): void;
+    clear(): void;
+    get activeCount(): number;
+}