@mhmo91/schmancy 0.10.23 → 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/badge/badge.ts

@@ -132,17 +132,13 @@ export 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(): string {
+	private getIconSizeClass(): string {
 		switch (this.size) {
-			case 'xs':
-				return '11px' // Approximately 0.9 × text size (12px × 0.9)
-			case 'sm':
-				return '13px' // Approximately 1.1 × text size (12px × 1.1)
-			case 'lg':
-				return '18px' // Approximately 1.1 × text size (16px × 1.1)
+			case 'xs': return 'text-xs'
+			case 'sm': return 'text-sm'
+			case 'lg': return 'text-lg'
 			case 'md':
-			default:
-				return '15px' // Approximately 1.1 × text size (14px × 1.1)
+			default:   return 'text-sm'
 		}
 	}
 
@@ -219,7 +215,7 @@ export class SchmancyBadgeV2 extends SchmancyElement {
 		const sizeClasses = this.getSizeClasses()
 		const shapeClasses = this.getShapeClasses()
 		const colorStyles = this.getColorStyles()
-		const iconSize = this.getIconSize()
+		const iconSizeClass = this.getIconSizeClass()
 		const exoticStyles = this.getExoticStyles()
 
 		const badgeClasses = {
@@ -259,7 +255,7 @@ export class SchmancyBadgeV2 extends SchmancyElement {
 					${this.icon
 						? html`
 								<div part="icon" class="shrink-0 flex items-center justify-center leading-none">
-									<schmancy-icon .size=${iconSize} class="flex items-center justify-center">${this.icon}</schmancy-icon>
+									<schmancy-icon class="${iconSizeClass} flex items-center justify-center">${this.icon}</schmancy-icon>
 								</div>
 							`
 						: ''}

package/src/button/icon-button.ts

@@ -235,8 +235,7 @@ export class SchmnacyIconButton extends SchmancyElement {
 			'hover:bg-secondary-container': effectiveVariant === 'filled tonal',
 		}
 
-		// Icon size mapping - M3 spec: 24dp standard, scaled for density
-		const iconSize = this.size === 'xxs' ? '12px' : this.size === 'xs' ? '16px' : this.size === 'sm' ? '20px' : this.size === 'md' ? '24px' : this.size === 'lg' ? '24px' : '40px';
+		const iconSizeClass = this.size === 'xxs' ? 'text-xs' : this.size === 'xs' ? 'text-base' : this.size === 'sm' ? 'text-xl' : this.size === 'md' ? 'text-2xl' : this.size === 'lg' ? 'text-2xl' : 'text-4xl';
 
 		// If href is provided, render an anchor element.
 		if (this.href) {
@@ -256,7 +255,7 @@ export class SchmnacyIconButton extends SchmancyElement {
 						? html`<slot></slot>`
 						: html`
 							<slot style="display:none" @slotchange=${this._handleSlotChange}></slot>
-							<schmancy-icon size=${iconSize} icon=${ifDefined(this.icon || this._capturedIcon)}></schmancy-icon>
+							<schmancy-icon class=${iconSizeClass}>${this.icon || this._capturedIcon}</schmancy-icon>
 						`
 					}
 				</a>
@@ -279,7 +278,7 @@ export class SchmnacyIconButton extends SchmancyElement {
 					? html`<slot></slot>`
 					: html`
 						<slot style="display:none" @slotchange=${this._handleSlotChange}></slot>
-						<schmancy-icon size=${iconSize} icon=${ifDefined(this.icon || this._capturedIcon)}></schmancy-icon>
+						<schmancy-icon class=${iconSizeClass}>${this.icon || this._capturedIcon}</schmancy-icon>
 					`
 				}
 			</button>

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)