@mhmo91/schmancy 0.10.20 → 0.10.21

package/skills/schmancy/page.md

@@ -1,42 +1,84 @@
 # schmancy-page
 
-> Native mobile-like page container. Fills remaining viewport height, prevents rubber-banding, pull-to-refresh, and double-tap zoom.
+> Viewport-locked layout primitive. Provides a definite-height frame so any composition inside it has a parent to resolve against.
+
+## Contract
+
+Two rules and one slot.
+
+1. **Outermost lock.** A `<schmancy-page>` with no `<schmancy-page>` ancestor anchors itself to the visual viewport (`position: fixed; inset: 0`) and tracks `visualViewport.height` for iOS soft-keyboard correctness. It does not rely on `html`/`body` height — the cascade above it is irrelevant.
+2. **Single-child stretch.** The slotted child fills the page box (`height: 100%; width: 100%; min-height: 0; min-width: 0`). More than one direct child produces a visible layout collision — fail-loud, not silent.
+
+Composition shape is plain CSS grid / flex inside the slotted child. The primitive does not prescribe header / footer / sidebar conventions; consumers arrange regions in standard CSS. The contract is the locked frame.
 
 ## Usage
+
+### App root
 ```html
-<schmancy-page rows="auto_1fr_auto">
-  <header>App bar</header>
-  <main>Scrollable content</main>
-  <footer>Bottom nav</footer>
+<schmancy-page>
+  <schmancy-area name="root" .default=${landing}>
+    <schmancy-route when="landing-view" .component=${landing}></schmancy-route>
+    <schmancy-route when="app-home"     .component=${appHome}></schmancy-route>
+  </schmancy-area>
 </schmancy-page>
 ```
 
-## Properties
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `rows` | string | `'auto_1fr_auto'` | Grid template rows — underscores become spaces (e.g. `'1fr_2fr_auto'`) |
-| `show-scrollbar` | boolean | `false` | Display scrollbar on scrollable area |
-| `no-select` | boolean | `false` | Disable text selection |
-
-## Behavior
-- Listens to `visualViewport` resize/scroll + `orientationchange` + keyboard focus events to recompute height.
-- Accounts for theme bottom offset (iOS safe area, home indicator).
-- Auto-assigns semantic elements (`header`, `main`, `footer`) to slots.
-- Inner scroll area uses `schmancy-scroll` for momentum-preserving scroll.
-
-## When to Use
-- Root of a mobile view or panel that should feel like a native page.
-- Any container where viewport-aware height + scroll containment matters.
-
-## Example — 3-row app shell
+### Sidebar + sticky header + body
 ```html
-<schmancy-page rows="auto_1fr_auto">
-  <schmancy-surface type="solid" rounded="none">
-    <schmancy-typography type="title">My App</schmancy-typography>
-  </schmancy-surface>
+<schmancy-page>
+  <div class="grid grid-cols-[auto_1fr]">
+    <app-rail></app-rail>
+    <schmancy-page>
+      <div class="grid grid-rows-[auto_1fr]">
+        <app-top-bar></app-top-bar>
+        <schmancy-area name="app">...</schmancy-area>
+      </div>
+    </schmancy-page>
+  </div>
+</schmancy-page>
+```
+
+The inner `<schmancy-page>` detects the outer ancestor, skips the viewport lock, and fills its grid cell via `height: 100%; width: 100%`.
 
-  <div class="p-4">…scrollable content…</div>
+### Tabs page
+```html
+<div class="grid grid-rows-[auto_1fr]">
+  <schmancy-tabs></schmancy-tabs>
+  <schmancy-area name="settings">...</schmancy-area>
+</div>
+```
 
-  <schmancy-navigation-bar></schmancy-navigation-bar>
+No `<schmancy-page>` here — this view is the routed body of a higher `<schmancy-page>`. The grid resolves against the area's `1fr` cell, which the area inherits from the page.
+
+### Admin shell (four regions)
+```html
+<schmancy-page>
+  <div class="grid grid-rows-[auto_1fr]">
+    <admin-top-bar></admin-top-bar>
+    <div class="grid grid-cols-[240px_1fr_320px]">
+      <admin-sidebar></admin-sidebar>
+      <schmancy-area name="admin"></schmancy-area>
+      <admin-inspector></admin-inspector>
+    </div>
+  </div>
 </schmancy-page>
 ```
+
+## Properties
+
+`<schmancy-page>` has no public properties. Composition is expressed by what you nest inside its single slot.
+
+The `outermost` attribute is set automatically on the page that owns the viewport lock. Consumers neither set nor read it.
+
+## Edge cases
+
+- **Print** — outermost page falls back to `position: static` so pagination works.
+- **iOS soft keyboard** — outermost page reads `visualViewport.height` and applies it as inline `height`, so the locked box shrinks when the keyboard opens.
+- **Long-form leaf (marketing, legal)** — opt out at the leaf, not at the page. The routed component declares its own `:host { height: auto; overflow: auto; min-height: 100% }`. The outer page stays locked; the leaf scrolls inside its `<schmancy-area>`.
+- **Master-detail with two scroll regions** — render two `<schmancy-area>` slots inside a grid; each owns its scroll.
+
+## Rules
+
+- A `<schmancy-page>` has exactly one direct child. If you need multiple regions, wrap them in a grid / flex container.
+- Do not put `class="h-full"`, `class="w-full"`, or `:host { height: 100% }` anywhere in your tree. The page and the area carry sizing; consumer code never does.
+- Scroll lives in `<schmancy-area>`, not in `<schmancy-page>`. Pages provide the locked frame; areas provide the scrolling region for their mounted component.

package/src/area/area.component.ts

@@ -25,9 +25,18 @@ export class SchmancyArea extends SchmancyElement {
 	:host {
 		position: relative;
 		display: block;
-		inset: 0;
+		height: 100%;
+		width: 100%;
+		min-height: 0;
+		min-width: 0;
 		contain: layout style;
 	}
+	::slotted(:not(schmancy-route)) {
+		display: block;
+		box-sizing: border-box;
+		min-height: 100%;
+		width: 100%;
+	}
 `]
 
 	@property() name!: string
@@ -202,6 +211,7 @@ export class SchmancyArea extends SchmancyElement {
 				if (duration === 0) {
 					old?.remove()
 					this.appendChild(element)
+					this.scrollTop = 0
 				} else if (old) {
 					old.style.willChange = 'opacity'
 					element.style.willChange = 'opacity'
@@ -211,11 +221,13 @@ export class SchmancyArea extends SchmancyElement {
 							if (!this.isConnected) return
 							old.remove()
 							this.appendChild(element)
+							this.scrollTop = 0
 							return element.animate([{ opacity: 0 }, { opacity: 1 }], { duration, easing: 'ease-in' }).finished
 						})
 						.then(() => (element.style.willChange = 'auto'))
 				} else {
 					this.appendChild(element)
+					this.scrollTop = 0
 					element.animate([{ opacity: 0 }, { opacity: 1 }], {
 						duration: duration > 100 ? Math.max(100, duration * 0.66) : duration,
 						easing: 'ease-in',

package/src/directives/fill.ts

@@ -0,0 +1,137 @@
+import { AsyncDirective, directive } from 'lit/async-directive.js'
+import { ElementPart, PartType } from 'lit/directive.js'
+import { EMPTY, Subject, combineLatest, fromEvent, merge, timer } from 'rxjs'
+import { debounceTime, distinctUntilChanged, filter, map, startWith, switchMap, takeUntil, tap } from 'rxjs/operators'
+import { theme } from '../theme/theme.service'
+import { fromResizeObserver } from './layout'
+
+/**
+ * fill directive — anchors an element to the viewport in both dimensions
+ * and contains overflow within its viewport-anchored box.
+ *
+ * The element's `getBoundingClientRect()` top/left are subtracted from the
+ * visual viewport size; the remaining pixels are applied as inline `height`
+ * and `width`. `overflow: hidden` ensures children cannot visually escape
+ * the box; inner scroll containers (apply `overflowWithin()` on the
+ * appropriate cell) handle scrolling.
+ *
+ * Layout is the consumer's responsibility — apply Tailwind classes
+ * (`grid grid-cols-[auto_1fr] grid-rows-[1fr]`, `flex`, etc.) on the same
+ * element to express the layout. The directive provides the definite-pixel
+ * box; the consumer decides how it's divided.
+ *
+ * Cascade-independent — measurement is taken in viewport coordinates
+ * rather than computed from CSS, so the directive works regardless of
+ * what the element's ancestors declare.
+ *
+ * Reactive sources: window/visualViewport resize + scroll, orientation
+ * change, iOS keyboard focus-out, parent/element ResizeObserver, theme
+ * fullscreen toggle, theme bottom offset (safe-area / nav-bar reservation).
+ *
+ * @example sidebar + main
+ *   <app-shell
+ *     ${fill()}
+ *     class="grid grid-cols-[auto_1fr] grid-rows-[1fr]"
+ *   >
+ *     <app-rail></app-rail>
+ *     <app-content></app-content>
+ *   </app-shell>
+ */
+class Fill extends AsyncDirective {
+	private element: HTMLElement | null = null
+	private disconnecting$ = new Subject<void>()
+
+	private apply(bottomOffset: number, isFullscreen: boolean) {
+		if (!this.element) return
+		const vv = window.visualViewport
+		const vh = vv?.height ?? window.innerHeight
+		const vw = vv?.width ?? window.innerWidth
+		const rect = this.element.getBoundingClientRect()
+		const height = Math.max(0, vh - rect.top)
+		const width = Math.max(0, vw - rect.left)
+		const padding = isFullscreen ? 0 : bottomOffset
+		const s = this.element.style
+		s.boxSizing = 'border-box'
+		s.height = `${height}px`
+		s.width = `${width}px`
+		s.paddingBottom = `${padding}px`
+		s.minHeight = '0'
+		s.minWidth = '0'
+		s.overflow = 'hidden'
+	}
+
+	private subscribe() {
+		if (!this.element) return
+
+		const windowResize$ = fromEvent(window, 'resize', { passive: true })
+		const viewportEvents$ = window.visualViewport
+			? merge(
+					fromEvent(window.visualViewport, 'resize', { passive: true }),
+					fromEvent(window.visualViewport, 'scroll', { passive: true }),
+				)
+			: windowResize$
+		const orientation$ = fromEvent(window, 'orientationchange')
+		const focusOut$ = fromEvent(document, 'focusout', { passive: true }).pipe(
+			switchMap(() => timer(100)),
+		)
+		const elementResize$ = fromResizeObserver(this.element)
+		const parentResize$ = this.element.parentElement
+			? fromResizeObserver(this.element.parentElement)
+			: EMPTY
+
+		combineLatest([
+			merge(
+				windowResize$,
+				viewportEvents$,
+				orientation$,
+				focusOut$,
+				elementResize$,
+				parentResize$,
+			).pipe(debounceTime(16), startWith(null)),
+			theme.bottomOffset$,
+			theme.fullscreen$,
+		])
+			.pipe(
+				filter(() => {
+					const vv = window.visualViewport
+					return vv ? Math.abs(vv.scale - 1) <= 0.01 : true
+				}),
+				map(([, bottomOffset, isFullscreen]) => ({ bottomOffset, isFullscreen })),
+				distinctUntilChanged(
+					(a, b) => a.bottomOffset === b.bottomOffset && a.isFullscreen === b.isFullscreen,
+				),
+				tap(({ bottomOffset, isFullscreen }) => this.apply(bottomOffset, isFullscreen)),
+				takeUntil(this.disconnecting$),
+			)
+			.subscribe()
+	}
+
+	render() {
+		return
+	}
+
+	override update(part: ElementPart) {
+		if (part.type !== PartType.ELEMENT) {
+			throw new Error('fill directive can only be used on elements')
+		}
+		const el = part.element as HTMLElement
+		if (this.element !== el) {
+			this.element = el
+			this.subscribe()
+		}
+	}
+
+	protected override disconnected() {
+		this.disconnecting$.next()
+		this.element = null
+	}
+
+	protected override reconnected() {
+		if (this.element) {
+			this.disconnecting$ = new Subject<void>()
+			this.subscribe()
+		}
+	}
+}
+
+export const fill = directive(Fill)

package/src/directives/index.ts

@@ -5,6 +5,7 @@ export * from './cursor-glow';
 export * from './cycle-text';
 export * from './depth-of-field';
 export * from './drag';
+export * from './fill';
 export * from './gravity';
 export * from './intersect';
 export * from './layout';
@@ -16,3 +17,4 @@ export * from './nebula';
 export * from './reduced-motion';
 export * from './reveal';
 export * from './ripple';
+export * from './overflow-within';

package/src/directives/overflow-within.ts

@@ -0,0 +1,186 @@
+import { noChange } from 'lit'
+import { AsyncDirective, directive } from 'lit/async-directive.js'
+import { ElementPart, PartType } from 'lit/directive.js'
+import { Subject, debounceTime, filter, fromEvent, takeUntil } from 'rxjs'
+
+/**
+ * Detail payload for the directive's enriched `scroll` event.
+ */
+export interface OverflowWithinEvent
+	extends CustomEvent<{
+		scrollTop: number
+		scrollHeight: number
+		clientHeight: number
+		scrollLeft: number
+		scrollWidth: number
+		clientWidth: number
+		e: Event
+	}> {}
+
+/**
+ * Detail payload for the global `@schmancy:scrollTo` command.
+ */
+export interface OverflowWithinCommandEvent
+	extends CustomEvent<{
+		name: string
+		action: 'scrollTo'
+		top: number
+		left?: number
+	}> {}
+
+export interface OverflowWithinOptions {
+	/** Hide native scrollbars while keeping scroll behavior intact. */
+	hide?: boolean
+	/** Which axis can scroll. Default `'both'`. */
+	direction?: 'vertical' | 'horizontal' | 'both'
+	/**
+	 * Optional name for cross-component control via the global
+	 * `@schmancy:scrollTo` event.
+	 */
+	name?: string
+	/** Debounce in ms for the dispatched `scroll` event. Default `10`. */
+	debounce?: number
+}
+
+const SCROLLBAR_HIDE_CLASS = 'schmancy-overflow-within-hidden'
+let stylesheetInstalled = false
+
+function installHideStylesheet() {
+	if (stylesheetInstalled) return
+	stylesheetInstalled = true
+	const sheet = new CSSStyleSheet()
+	sheet.replaceSync(
+		`.${SCROLLBAR_HIDE_CLASS} { scrollbar-width: none; -ms-overflow-style: none; }
+		 .${SCROLLBAR_HIDE_CLASS}::-webkit-scrollbar { display: none; }`,
+	)
+	document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet]
+}
+
+/**
+ * overflowWithin directive — turns any element into a contained overflow
+ * boundary. Content stays *within* the element; what overflows scrolls
+ * inside, can't escape (overscroll contained, rubber-band suppressed).
+ *
+ *   - Overflow per `direction` axis
+ *   - Smooth scroll-behavior
+ *   - Overscroll containment (no rubber-band escape)
+ *   - Optional hidden scrollbar via a document-level stylesheet
+ *   - Debounced enriched `scroll` event
+ *   - Global `@schmancy:scrollTo` command listener (when `name` is set)
+ *   - min-height / min-width 0 so the container can clip inside grid/flex cells
+ *
+ * Apply at the element where overflow should be contained; the consumer's
+ * layout grid/flex container can itself be the overflow boundary — no
+ * wrapper element needed.
+ *
+ * @example
+ *   render() {
+ *     return html`
+ *       <div class="grid grid-rows-[auto_1fr]" ${overflowWithin({ hide: true })}>
+ *         <header>...</header>
+ *         <section>...scrollable content...</section>
+ *       </div>
+ *     `
+ *   }
+ */
+class OverflowWithinDirective extends AsyncDirective {
+	private element: HTMLElement | null = null
+	private disconnecting$ = new Subject<void>()
+	private currentName?: string
+
+	render(_options?: OverflowWithinOptions) {
+		return noChange
+	}
+
+	override update(part: ElementPart, [options = {}]: [OverflowWithinOptions?]) {
+		if (part.type !== PartType.ELEMENT) {
+			throw new Error('overflowWithin directive can only be used on elements')
+		}
+		const el = part.element as HTMLElement
+		const { hide = false, direction = 'both', name, debounce = 10 } = options
+
+		const s = el.style
+		s.minHeight = '0'
+		s.minWidth = '0'
+		s.boxSizing = 'border-box'
+		s.overflowY = direction === 'horizontal' ? 'hidden' : 'auto'
+		s.overflowX = direction === 'vertical' ? 'hidden' : 'auto'
+		s.scrollBehavior = 'smooth'
+		s.overscrollBehavior = 'contain'
+
+		if (hide) {
+			installHideStylesheet()
+			el.classList.add(SCROLLBAR_HIDE_CLASS)
+		} else {
+			el.classList.remove(SCROLLBAR_HIDE_CLASS)
+		}
+
+		const isNewElement = this.element !== el
+		const isNameChange = this.currentName !== name
+
+		if (isNewElement) {
+			this.element = el
+			this.subscribe(debounce, name)
+		} else if (isNameChange) {
+			// resubscribe with new name binding
+			this.disconnecting$.next()
+			this.disconnecting$ = new Subject<void>()
+			this.subscribe(debounce, name)
+		}
+		this.currentName = name
+
+		return noChange
+	}
+
+	private subscribe(debounce: number, name: string | undefined) {
+		if (!this.element) return
+		const el = this.element
+
+		fromEvent(el, 'scroll', { passive: true })
+			.pipe(debounceTime(debounce), takeUntil(this.disconnecting$))
+			.subscribe((e) => {
+				el.dispatchEvent(
+					new CustomEvent('scroll', {
+						detail: {
+							scrollTop: el.scrollTop,
+							scrollHeight: el.scrollHeight,
+							clientHeight: el.clientHeight,
+							scrollLeft: el.scrollLeft,
+							scrollWidth: el.scrollWidth,
+							clientWidth: el.clientWidth,
+							e,
+						},
+						bubbles: true,
+						composed: true,
+					}) as OverflowWithinEvent,
+				)
+			})
+
+		if (name !== undefined) {
+			fromEvent<OverflowWithinCommandEvent>(window, '@schmancy:scrollTo')
+				.pipe(
+					filter((evt) => evt.detail.name === name && evt.detail.action === 'scrollTo'),
+					takeUntil(this.disconnecting$),
+				)
+				.subscribe((evt) => {
+					const options: ScrollToOptions = { behavior: 'smooth', top: evt.detail.top }
+					if (typeof evt.detail.left === 'number') options.left = evt.detail.left
+					el.scrollTo(options)
+				})
+		}
+	}
+
+	protected override disconnected() {
+		this.disconnecting$.next()
+		this.element = null
+	}
+
+	protected override reconnected() {
+		if (this.element) {
+			this.disconnecting$ = new Subject<void>()
+			this.subscribe(10, this.currentName)
+		}
+	}
+}
+
+export const overflowWithin = directive(OverflowWithinDirective)

package/src/index.ts

@@ -43,7 +43,6 @@ export * from './option';
 // inside a federated context, the build-time check passes only if
 // `show` is reachable from the main barrel.
 export * from './overlay';
-export * from './page';
 export * from './progress';
 export * from './form/fields/radio-group';
 export * from './form/fields/range';

package/src/overlay/index.ts

@@ -11,5 +11,6 @@ export type {
 	OverlayPromptOptions,
 	ShowFn,
 	ShowOptions,
+	TemplateFactory,
 } from './overlay.types'
 export { lazy } from '../area/lazy'

package/src/overlay/overlay.component.ts

@@ -593,6 +593,11 @@ async function mountContent(
 	host: HTMLElement,
 	props?: Record<string, unknown>,
 ): Promise<HTMLElement> {
+	// TemplateFactory — call at mount time so closed-over variables are read lazily.
+	if (isTemplateFactory(content)) {
+		return mountContent(content(), host, props)
+	}
+
 	// TemplateResult — render via lit's `render`.
 	if (isTemplateResult(content)) {
 		litRender(content, host)
@@ -632,6 +637,10 @@ async function mountContent(
 	throw new Error('schmancy-overlay: unsupported content type')
 }
 
+function isTemplateFactory(x: unknown): x is import('./overlay.types').TemplateFactory {
+	return typeof x === 'function' && !(x as { prototype?: unknown }).prototype
+}
+
 function isTemplateResult(x: unknown): x is TemplateResult {
 	return typeof x === 'object' && x !== null && '_$litType$' in x
 }

package/src/overlay/overlay.types.ts

@@ -3,15 +3,22 @@ import type { Observable } from 'rxjs'
 import type { ComponentType } from '../area/router.types'
 import type { THistoryStrategy } from '../area/router.types'
 
+/**
+ * Sync factory that returns a TemplateResult. Called at mount time so closed-over
+ * variables are evaluated lazily — no snapshot staleness.
+ */
+export type TemplateFactory = () => TemplateResult
+
 /**
  * What the caller is showing. Flat union — `typeof`-discriminated at runtime.
  * Reuses area's `ComponentType` (class | tag name | HTMLElement | lazy loader)
- * and adds Lit `TemplateResult` for inline templates.
+ * and adds Lit `TemplateResult` for inline templates plus `TemplateFactory` for
+ * lazy template evaluation.
  *
  * The common case is one positional arg: `show(MyEditor)`, `show(html\`...\`)`,
- * `show(el)`, `show('my-tag')`, `show(lazy(() => import('./x')))`.
+ * `show(() => html\`...\`)`, `show(el)`, `show('my-tag')`, `show(lazy(() => import('./x')))`.
  */
-export type Content = ComponentType | TemplateResult
+export type Content = ComponentType | TemplateResult | TemplateFactory
 
 /**
  * Virtual reference object — same contract Floating UI and CSS Anchor

package/types/src/directives/fill.d.ts

@@ -0,0 +1,46 @@
+import { AsyncDirective } from 'lit/async-directive.js';
+import { ElementPart } from 'lit/directive.js';
+/**
+ * fill directive — anchors an element to the viewport in both dimensions
+ * and contains overflow within its viewport-anchored box.
+ *
+ * The element's `getBoundingClientRect()` top/left are subtracted from the
+ * visual viewport size; the remaining pixels are applied as inline `height`
+ * and `width`. `overflow: hidden` ensures children cannot visually escape
+ * the box; inner scroll containers (apply `overflowWithin()` on the
+ * appropriate cell) handle scrolling.
+ *
+ * Layout is the consumer's responsibility — apply Tailwind classes
+ * (`grid grid-cols-[auto_1fr] grid-rows-[1fr]`, `flex`, etc.) on the same
+ * element to express the layout. The directive provides the definite-pixel
+ * box; the consumer decides how it's divided.
+ *
+ * Cascade-independent — measurement is taken in viewport coordinates
+ * rather than computed from CSS, so the directive works regardless of
+ * what the element's ancestors declare.
+ *
+ * Reactive sources: window/visualViewport resize + scroll, orientation
+ * change, iOS keyboard focus-out, parent/element ResizeObserver, theme
+ * fullscreen toggle, theme bottom offset (safe-area / nav-bar reservation).
+ *
+ * @example sidebar + main
+ *   <app-shell
+ *     ${fill()}
+ *     class="grid grid-cols-[auto_1fr] grid-rows-[1fr]"
+ *   >
+ *     <app-rail></app-rail>
+ *     <app-content></app-content>
+ *   </app-shell>
+ */
+declare class Fill extends AsyncDirective {
+    private element;
+    private disconnecting$;
+    private apply;
+    private subscribe;
+    render(): void;
+    update(part: ElementPart): void;
+    protected disconnected(): void;
+    protected reconnected(): void;
+}
+export declare const fill: () => import("lit-html/directive").DirectiveResult<typeof Fill>;
+export {};

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

@@ -5,6 +5,7 @@ export * from './cursor-glow';
 export * from './cycle-text';
 export * from './depth-of-field';
 export * from './drag';
+export * from './fill';
 export * from './gravity';
 export * from './intersect';
 export * from './layout';
@@ -16,3 +17,4 @@ export * from './nebula';
 export * from './reduced-motion';
 export * from './reveal';
 export * from './ripple';
+export * from './overflow-within';