@mhmo91/schmancy 0.10.24 → 0.10.25

package/skills/schmancy/layout.md

@@ -1,63 +1,46 @@
-# Schmancy Layout
+# Layout Directives
 
-> Layout primitives: `schmancy-grid`, `schmancy-flex`, `schmancy-scroll`, plus `sch-grid` / `sch-flex` v2 variants.
+```typescript
+import { fill, overflowWithin } from '@mhmo91/schmancy/directives'
+```
 
-> **Prefer Tailwind classes directly** for layout in new code. These components exist for quick composition and design-token consistency (`gap="sm|md|lg"` maps to theme spacing).
+## `fill()` — viewport-anchor an element
 
-## schmancy-grid
-```html
-<schmancy-grid cols="1fr 2fr 1fr" gap="md" align="center">
-  <div>Left</div><div>Center</div><div>Right</div>
-</schmancy-grid>
-```
+Measures against `visualViewport` and writes exact `height`/`width` in px. Cascade-independent — works even when parent custom elements default to `display: inline`. Tracks iOS keyboard, orientation change, and `theme.bottomOffset$`.
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `flow` | `'row' \| 'col' \| 'dense' \| 'row-dense' \| 'col-dense'` | `'row'` | Grid auto-flow |
-| `align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | `'stretch'` | Item alignment |
-| `justify` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` | Item justification |
-| `content` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'around' \| 'evenly' \| 'between'` | — | Align-content |
-| `gap` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg'` | `'none'` | Grid gap |
-| `cols` | string | — | grid-template-columns (e.g. `"1fr 2fr"`) |
-| `rows` | string | — | grid-template-rows |
-| `rcols` | object | — | Responsive cols: `{ sm: '1fr', md: '1fr 1fr', lg: '1fr 2fr 1fr' }` |
-| `wrap` | boolean | `false` | Grid auto-wrap |
-
-## schmancy-flex
-```html
-<schmancy-flex flow="row" justify="between" align="center" gap="md">
-  <div>Logo</div><div>Nav</div>
-</schmancy-flex>
-```
+Sets: `height: Npx`, `width: Npx`, `overflow: hidden`, `min-h/w: 0`, `box-sizing: border-box`, `padding-bottom` (safe area).  
+Does **not** set `display` or `grid-template-*` — use Tailwind classes on the same element.
 
-| Property | Type | Default |
-|----------|------|---------|
-| `flow` | `'row' \| 'row-reverse' \| 'col' \| 'col-reverse'` | `'col'` |
-| `wrap` | `'wrap' \| 'nowrap' \| 'wrap-reverse'` | `'wrap'` |
-| `align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | `'start'` |
-| `justify` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'between'` | `'start'` |
-| `gap` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'none'` |
-
-## schmancy-scroll
-```html
-<schmancy-scroll hide direction="vertical" name="main">
-  <!-- long content -->
-</schmancy-scroll>
-```
+## `overflowWithin()` — contained scroll region
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `hide` | boolean | `false` | Hide scrollbar in supported browsers |
-| `direction` | `'vertical' \| 'horizontal' \| 'both'` | `'both'` | Scroll axes |
-| `name` | string | — | Identifier for global scroll events |
-| `debounce` | number | — | Debounce time in ms for scroll events |
+Sets: `overflow: auto`, `overscroll-behavior: contain`, `scroll-behavior: smooth`, `min-h/w: 0`, `box-sizing: border-box`.
 
-Smooth scroll-behavior, overscroll containment, and support for flex-shrink sizing.
+## Canonical shell
 
-## sch-grid / sch-flex (v2)
+```typescript
+// app-shell.view.ts
+html`<schmancy-area ${fill()} name="root" .default=${...}>...</schmancy-area>`
+
+// app-home.view.ts
+html`
+  <my-shell class="grid grid-cols-[auto_1fr]" ${fill()}>
+    <app-rail></app-rail>
+    <div ${overflowWithin()} class="grid grid-rows-[auto_1fr] min-h-0">
+      <tree-picker></tree-picker>
+      <schmancy-area name="app" .default=${...}>...</schmancy-area>
+    </div>
+  </my-shell>
+`
+```
+
+```css
+/* styles.css */
+html, body { margin: 0; padding: 0; overflow: hidden; }
+```
 
-Reflected-attribute variants optimized for styling via CSS selectors. Same prop model as the classic components with a `sch-` prefix. Use when you need to target the layout from parent CSS without Tailwind.
+## Rules
 
-## Notes
-- All layout components extend the base `Layout` class which exposes pass-through CSS properties (padding, margin, width, position, border, etc.).
-- Prefer Tailwind (`class="flex items-center gap-2"`) for new code — these components remain for consistent theme-driven gaps and rapid prototyping.
+- One `fill()` per shell level. Inner levels get `min-h-0` grid cells.
+- `overflowWithin()` goes on the element that should scroll, not on `:host`.
+- Do not write `h-full`, `w-full`, or `:host { height: 100% }` anywhere. `schmancy-area`'s `::slotted` rule sizes mounted views.
+- `<schmancy-page>` is removed — `fill()` replaces it.

package/skills/schmancy/mixins.md

@@ -8,11 +8,10 @@ factory — composing `LitElement` + Tailwind injection + `BaseElement`
 ## Usage
 
 ```typescript
-import { SchmancyElement } from '@mhmo91/schmancy/mixins'
-import { customElement } from 'lit/decorators.js'
+import { SchmancyElement, schmancyElement } from '@mhmo91/schmancy/mixins'
 import { css, html } from 'lit'
 
-@customElement('my-component')
+@schmancyElement('my-component')
 class MyComponent extends SchmancyElement {
   static styles = [css`
     :host { display: block }
@@ -33,12 +32,34 @@ declare global {
 No styles? Just drop `static styles`:
 
 ```typescript
-@customElement('my-component')
+@schmancyElement('my-component')
 class MyComponent extends SchmancyElement {
   render() { return html`<slot></slot>` }
 }
 ```
 
+### Why `@schmancyElement` instead of Lit's `@customElement`
+
+`@schmancyElement` wraps the class's prototype methods with the active-host
+tracker BEFORE calling `customElements.define`. Lit's `@customElement` only
+calls `define` — the wrap then runs inside the `SchmancyElement` constructor,
+which is too late: per the HTML spec, the browser captures lifecycle callback
+references off the prototype at `define` time and invokes those cached
+references for every connect / disconnect.
+
+If you use plain `@customElement` and read state inside `connectedCallback`,
+the active-host stack is empty, the read falls through to `document.activeElement`,
+misses the enclosing `<schmancy-context>`, and silently resolves to the
+module-scoped global instead of the isolated copy. The constructor-time wrap
+still catches `render`, class methods, and inherited lifecycle methods on
+ancestor prototypes (the browser's cached reference for those is the
+ancestor's, which gets wrapped by an earlier sibling). But your subclass's
+own `connectedCallback` / `disconnectedCallback` overrides fall through.
+The symptom is silent: writes go to the wrong slot, reads return the wrong
+value, and the form looks broken for no obvious reason.
+
+`@schmancyElement` makes this impossible. Use it as the default.
+
 Tailwind is injected automatically — your `static styles` only declares
 component-local CSS.
 
@@ -99,7 +120,7 @@ Every SchmancyElement responds to `{its-tag}-where-are-you` events with
 ## Component skeleton
 
 ```typescript
-@customElement('my-component')
+@schmancyElement('my-component')
 export class MyComponent extends SchmancyElement {
   static styles = [css`:host { display: block }`]
 

package/src/directives/ai-badge.ts

@@ -0,0 +1,95 @@
+/**
+ * AI Badge Directive — Indicator for AI-generated content.
+ * Pulses gently on the host element; color routed through theme tokens.
+ */
+
+import { noChange } from 'lit'
+import { AsyncDirective, directive } from 'lit/async-directive.js'
+import type { ElementPart } from 'lit'
+
+interface State {
+	message: string
+	element: HTMLElement
+	badge: HTMLElement | null
+	animation: Animation | null
+}
+
+class AIBadgeDirective extends AsyncDirective {
+	private state: State | null = null
+
+	render(_message?: string) {
+		return noChange
+	}
+
+	override update(part: ElementPart, [message = '']: [string?]) {
+		const element = part.element as HTMLElement
+
+		if (!message) {
+			this.cleanup()
+			return noChange
+		}
+
+		if (this.state) return noChange
+
+		this.state = {
+			message,
+			element,
+			badge: null,
+			animation: null,
+		}
+
+		if (getComputedStyle(element).position === 'static') {
+			element.style.position = 'relative'
+		}
+
+		const badge = document.createElement('div')
+		badge.style.cssText = `
+			display: block;
+			position: absolute;
+			bottom: -8px;
+			left: 8px;
+			z-index: 10;
+			padding: 3px 10px;
+			border-radius: 12px;
+			font-size: 0.65rem;
+			font-weight: 600;
+			background: linear-gradient(
+				135deg,
+				var(--md-sys-color-primary, #7c5cff),
+				var(--md-sys-color-primary-container, #6750a4)
+			);
+			color: var(--md-sys-color-on-primary, #fff);
+			box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);
+			white-space: nowrap;
+		`
+		badge.textContent = `✦ ${message}`
+		badge.title = message
+
+		element.appendChild(badge)
+		this.state.badge = badge
+
+		this.state.animation = badge.animate(
+			[
+				{ transform: 'scale(1)' },
+				{ transform: 'scale(1.03)' },
+				{ transform: 'scale(1)' },
+			],
+			{ duration: 2000, easing: 'ease-in-out', iterations: Infinity },
+		)
+
+		return noChange
+	}
+
+	private cleanup(): void {
+		if (!this.state) return
+		this.state.animation?.cancel()
+		this.state.badge?.remove()
+		this.state = null
+	}
+
+	override disconnected(): void {
+		this.cleanup()
+	}
+}
+
+export const aiBadge = directive(AIBadgeDirective)

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

@@ -0,0 +1,228 @@
+/**
+ * Art Directive — GPU-accelerated decorative overlays.
+ * Lazy-initialised, IntersectionObserver-paused, RAF-driven, particle-pooled.
+ */
+
+import type { ElementPart } from 'lit'
+import { noChange } from 'lit'
+import { AsyncDirective, directive } from 'lit/async-directive.js'
+
+import type { ArtOptions, ArtState } from './types'
+import { createFunkhausOverlay, animateFunkhaus } from './effects/funkhaus'
+import { createSamwaOverlay, animateSamwa } from './effects/samwa'
+import { createHowlOverlay, animateHowl } from './effects/howl'
+import { createErrorOverlay, animateError } from './effects/error'
+import { createSnowOverlay, animateSnow } from './effects/snow'
+import { createStarfieldOverlay, animateStarfield } from './effects/starfield'
+
+interface ExtendedArtState extends ArtState {
+	initialized: boolean
+	originalPosition: string
+}
+
+class ArtDirective extends AsyncDirective {
+	private state: ExtendedArtState | null = null
+
+	render(_options: ArtOptions) {
+		return noChange
+	}
+
+	override update(part: ElementPart, [options]: [ArtOptions]) {
+		const element = part.element as HTMLElement
+		const { name, color, intensity = 1, speed = 1 } = options
+
+		if (
+			this.state &&
+			(this.state.effect !== name ||
+				this.state.color !== color ||
+				this.state.intensity !== intensity ||
+				this.state.speed !== speed)
+		) {
+			this.cleanup()
+		}
+
+		if (!this.state) {
+			const originalPosition = element.style.position
+
+			this.state = {
+				effect: name,
+				color,
+				intensity,
+				speed,
+				element,
+				isVisible: true,
+				initialized: false,
+				originalPosition,
+			}
+
+			requestAnimationFrame(() => {
+				if (!this.state) return
+
+				const rect = element.getBoundingClientRect()
+				const isVisible =
+					rect.top < window.innerHeight && rect.bottom > 0 && rect.left < window.innerWidth && rect.right > 0
+
+				if (!isVisible) {
+					this.state.isVisible = false
+					this.setupVisibilityObserver()
+					return
+				}
+
+				this.initializeResources()
+				this.startAnimation()
+				this.setupVisibilityObserver()
+			})
+		}
+
+		return noChange
+	}
+
+	private initializeResources(): void {
+		if (!this.state || this.state.initialized) return
+
+		const { element, effect: name } = this.state
+
+		const computedStyle = getComputedStyle(element)
+		if (computedStyle.position === 'static') {
+			element.style.position = 'relative'
+		}
+
+		switch (name) {
+			case 'funkhaus':
+				createFunkhausOverlay(this.state)
+				break
+			case 'samwa':
+				createSamwaOverlay(this.state)
+				break
+			case 'howl':
+				createHowlOverlay(this.state)
+				break
+			case 'error':
+				createErrorOverlay(this.state)
+				break
+			case 'snow':
+				createSnowOverlay(this.state)
+				break
+			case 'starfield':
+				createStarfieldOverlay(this.state)
+				break
+		}
+
+		this.state.initialized = true
+	}
+
+	private setupVisibilityObserver(): void {
+		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
+
+					if (!this.state.initialized) {
+						this.initializeResources()
+					}
+
+					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(): void {
+		if (!this.state || !this.state.isVisible) return
+		if (this.state.animationId) return
+
+		if (!this.state.initialized) {
+			this.initializeResources()
+		}
+
+		const animate = (currentTime: number) => {
+			if (!this.state || !this.state.isVisible) {
+				if (this.state) this.state.animationId = undefined
+				return
+			}
+
+			switch (this.state.effect) {
+				case 'funkhaus':
+					animateFunkhaus(this.state, currentTime)
+					break
+				case 'samwa':
+					animateSamwa(this.state, currentTime)
+					break
+				case 'howl':
+					animateHowl(this.state, currentTime)
+					break
+				case 'error':
+					animateError(this.state, currentTime)
+					break
+				case 'snow':
+					animateSnow(this.state, currentTime)
+					break
+				case 'starfield':
+					animateStarfield(this.state, currentTime)
+					break
+			}
+
+			this.state.animationId = requestAnimationFrame(animate)
+		}
+
+		this.state.animationId = requestAnimationFrame(animate)
+	}
+
+	private cleanup(): void {
+		if (!this.state) return
+
+		if (this.state.animationId) {
+			cancelAnimationFrame(this.state.animationId)
+		}
+
+		if (this.state.observer) {
+			this.state.observer.disconnect()
+		}
+
+		if (this.state.samwa) {
+			this.state.samwa.leafPool.clear()
+		}
+
+		if (this.state.howl) {
+			this.state.howl.steamPool.clear()
+		}
+
+		if (this.state.error) {
+			this.state.error.boltPool.clear()
+		}
+
+		if (this.state.snow) {
+			this.state.snow.snowflakePool.clear()
+		}
+
+		if (this.state.overlayElement) {
+			this.state.overlayElement.remove()
+		}
+
+		if (this.state.originalPosition !== undefined) {
+			this.state.element.style.position = this.state.originalPosition
+		}
+
+		this.state = null
+	}
+
+	override disconnected(): void {
+		this.cleanup()
+	}
+}
+
+export const art = directive(ArtDirective)

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

@@ -0,0 +1,192 @@
+/**
+ * Error Effect — Electrical/warning glow on edges with static particles and lightning bolts.
+ * 2.5-second main pulse cycle.
+ */
+
+import type { ArtState } from '../types'
+import { ParticlePool } from '../particle-pool'
+import { createOverlayContainer, createSVG } from '../utils'
+
+export function createErrorOverlay(state: ArtState): void {
+	const { element, color } = state
+	const overlay = createOverlayContainer('error-overlay')
+	const svg = createSVG()
+
+	const edgeGroup = document.createElementNS('http://www.w3.org/2000/svg', 'g')
+	const edges = [
+		{ x: 0, y: 0, width: 100, height: 0.5 },
+		{ x: 0, y: 99.5, width: 100, height: 0.5 },
+		{ x: 0, y: 0, width: 0.5, height: 100 },
+		{ x: 99.5, y: 0, width: 0.5, height: 100 },
+	]
+
+	const edgeElements = edges.map(edge => {
+		const rect = document.createElementNS('http://www.w3.org/2000/svg', 'rect')
+		rect.setAttribute('x', edge.x.toString())
+		rect.setAttribute('y', edge.y.toString())
+		rect.setAttribute('width', edge.width.toString())
+		rect.setAttribute('height', edge.height.toString())
+		rect.setAttribute('fill', color)
+		rect.style.mixBlendMode = 'screen'
+		rect.style.willChange = 'opacity'
+		edgeGroup.appendChild(rect)
+		return rect
+	})
+
+	const staticGroup = document.createElementNS('http://www.w3.org/2000/svg', 'g')
+	const staticParticles: NonNullable<ArtState['error']>['staticParticles'] = []
+
+	for (let i = 0; i < 4; i++) {
+		const circle = document.createElementNS('http://www.w3.org/2000/svg', 'circle')
+		circle.setAttribute('r', '0.3')
+		circle.setAttribute('fill', color)
+		circle.style.mixBlendMode = 'screen'
+		circle.style.willChange = 'opacity'
+		staticGroup.appendChild(circle)
+		staticParticles.push({ element: circle, edge: i % 4 })
+	}
+
+	svg.appendChild(edgeGroup)
+	svg.appendChild(staticGroup)
+	overlay.appendChild(svg)
+	element.appendChild(overlay)
+
+	const boltFactory = () => {
+		const path = document.createElementNS('http://www.w3.org/2000/svg', 'path')
+		path.setAttribute('stroke', color)
+		path.setAttribute('stroke-width', '0.5')
+		path.setAttribute('fill', 'none')
+		path.style.mixBlendMode = 'screen'
+		path.style.willChange = 'opacity'
+		svg.appendChild(path)
+		return path
+	}
+
+	state.overlayElement = overlay
+	state.error = {
+		edges: edgeElements,
+		staticParticles,
+		boltPool: new ParticlePool(boltFactory, 5),
+		lightningBolts: [],
+		lastLightningSpawn: performance.now(),
+		startTime: performance.now(),
+	}
+}
+
+export function animateError(state: ArtState, currentTime: number): void {
+	if (!state.error) return
+
+	const { edges, staticParticles, boltPool, lightningBolts, startTime } = state.error
+	const elapsed = currentTime - startTime
+	const cycleProgress = (elapsed % 2500) / 2500
+
+	const edgePulse = Math.sin(cycleProgress * Math.PI * 4) * 0.5 + 0.5
+	const edgeOpacity = 0.08 + edgePulse * 0.17
+	edges.forEach(edge => edge.setAttribute('opacity', edgeOpacity.toFixed(3)))
+
+	staticParticles.forEach((particle, index) => {
+		const particlePhase = (cycleProgress + index * 0.125) % 1.0
+		let x = 0,
+			y = 0
+
+		switch (particle.edge) {
+			case 0:
+				x = Math.random() * 100
+				y = Math.random() * 5
+				break
+			case 1:
+				x = 95 + Math.random() * 5
+				y = Math.random() * 100
+				break
+			case 2:
+				x = Math.random() * 100
+				y = 95 + Math.random() * 5
+				break
+			case 3:
+				x = Math.random() * 5
+				y = Math.random() * 100
+				break
+		}
+
+		particle.element.setAttribute('cx', x.toString())
+		particle.element.setAttribute('cy', y.toString())
+
+		const flicker = Math.sin(particlePhase * Math.PI * 2) * 0.5 + 0.5
+		particle.element.setAttribute('opacity', (flicker * 0.35).toFixed(3))
+	})
+
+	if (currentTime - state.error.lastLightningSpawn > 1500 && boltPool.activeCount < 3) {
+		const bolt = boltPool.acquire()
+		const edge = Math.floor(Math.random() * 4)
+		let startX = 0,
+			startY = 0,
+			endX = 0,
+			endY = 0
+
+		switch (edge) {
+			case 0:
+				startX = Math.random() * 100
+				startY = 0
+				endX = Math.random() * 100
+				endY = 50
+				break
+			case 1:
+				startX = 100
+				startY = Math.random() * 100
+				endX = 70
+				endY = Math.random() * 100
+				break
+			case 2:
+				startX = Math.random() * 100
+				startY = 100
+				endX = Math.random() * 100
+				endY = 50
+				break
+			case 3:
+				startX = 0
+				startY = Math.random() * 100
+				endX = 30
+				endY = Math.random() * 100
+				break
+		}
+
+		bolt.setAttribute('d', createLightningPath(startX, startY, endX, endY))
+		lightningBolts.push({ element: bolt, x: 0, y: 0, vx: 0, vy: 0, life: 1 })
+		state.error.lastLightningSpawn = currentTime
+	}
+
+	for (let i = lightningBolts.length - 1; i >= 0; i--) {
+		const bolt = lightningBolts[i]
+		bolt.life -= 0.05
+		const opacity = bolt.life > 0.8 ? 0.7 : bolt.life * 0.875
+		bolt.element.setAttribute('opacity', Math.max(0, opacity).toFixed(3))
+
+		if (bolt.life <= 0) {
+			boltPool.release(bolt.element)
+			lightningBolts.splice(i, 1)
+		}
+	}
+}
+
+function createLightningPath(startX: number, startY: number, endX: number, endY: number): string {
+	const segments = 4
+	let path = `M ${startX.toFixed(1)},${startY.toFixed(1)}`
+
+	const deltaX = (endX - startX) / segments
+	const deltaY = (endY - startY) / segments
+
+	let currentX = startX
+	let currentY = startY
+
+	for (let i = 1; i < segments; i++) {
+		const jag = 3 + Math.random() * 5
+		const perpX = -deltaY * jag * (Math.random() - 0.5)
+		const perpY = deltaX * jag * (Math.random() - 0.5)
+
+		currentX += deltaX + perpX
+		currentY += deltaY + perpY
+		path += ` L ${currentX.toFixed(1)},${currentY.toFixed(1)}`
+	}
+
+	return path + ` L ${endX.toFixed(1)},${endY.toFixed(1)}`
+}