@mhmo91/schmancy 0.9.12 → 0.9.14

package/src/agent/helpers.ts

@@ -0,0 +1,161 @@
+import manifest from 'virtual:schmancy-manifest'
+
+export type Manifest = typeof manifest
+
+export type ElementEntry = {
+	kind: 'class'
+	name: string
+	tagName?: string
+	description?: string
+	summary?: string
+	attributes?: Array<{
+		name: string
+		description?: string
+		type?: { text?: string }
+		default?: string
+		values?: string[]
+	}>
+	events?: Array<{ name: string; description?: string; type?: { text?: string } }>
+	slots?: Array<{ name: string; description?: string }>
+	cssProperties?: Array<{ name: string; description?: string }>
+	cssParts?: Array<{ name: string; description?: string }>
+	whenToUse?: string
+	platformPrimitive?: { tag: string; mode?: string; note?: string }
+	contexts?: { provides?: string[]; consumes?: string[] }
+}
+
+export type ServiceEntry = {
+	kind: 'variable'
+	name: string
+	description?: string
+	summary?: string
+	service: true
+	methods?: Array<{ signature: string; summary?: string }>
+}
+
+type Declaration = ElementEntry | ServiceEntry | { kind: string; name: string; [key: string]: unknown }
+
+function allDeclarations(): Declaration[] {
+	const out: Declaration[] = []
+	for (const mod of manifest.modules ?? []) {
+		const decls = (mod as unknown as { declarations?: Declaration[] }).declarations ?? []
+		for (const decl of decls) out.push(decl)
+	}
+	return out
+}
+
+function elements(): ElementEntry[] {
+	return allDeclarations().filter(
+		(d): d is ElementEntry => d.kind === 'class' && typeof (d as ElementEntry).tagName === 'string',
+	)
+}
+
+function services(): ServiceEntry[] {
+	return allDeclarations().filter((d): d is ServiceEntry => d.kind === 'variable' && (d as ServiceEntry).service === true)
+}
+
+export function help(tag?: string): unknown {
+	if (!tag) {
+		return {
+			elements: elements().map(e => ({ tag: e.tagName, summary: e.summary ?? e.description })),
+			services: services().map(s => ({ name: s.name, summary: s.summary ?? s.description })),
+		}
+	}
+	const el = elements().find(e => e.tagName === tag)
+	if (el) return el
+	const svc = services().find(s => s.name === tag)
+	if (svc) return svc
+	return null
+}
+
+export function tokens(): string[] {
+	return (manifest as { tokens?: string[] }).tokens ?? []
+}
+
+export function platformPrimitive(tag: string): ElementEntry['platformPrimitive'] | null {
+	return elements().find(e => e.tagName === tag)?.platformPrimitive ?? null
+}
+
+export function registeredTags(): string[] {
+	return elements()
+		.map(e => e.tagName!)
+		.filter(tag => typeof customElements.get(tag) !== 'undefined')
+}
+
+export function a11yAudit(): Array<{
+	tag: string
+	role: string | null
+	ariaLabel: string | null
+	hasShadowRoot: boolean
+	formAssociated: boolean
+}> {
+	const tags = new Set(elements().map(e => e.tagName!))
+	const report: Array<{
+		tag: string
+		role: string | null
+		ariaLabel: string | null
+		hasShadowRoot: boolean
+		formAssociated: boolean
+	}> = []
+	const all = document.querySelectorAll('*')
+	for (const node of Array.from(all)) {
+		const tag = node.tagName.toLowerCase()
+		if (!tags.has(tag)) continue
+		const ctor = customElements.get(tag) as (CustomElementConstructor & { formAssociated?: boolean }) | undefined
+		report.push({
+			tag,
+			role: node.getAttribute('role'),
+			ariaLabel: node.getAttribute('aria-label'),
+			hasShadowRoot: Boolean((node as Element & { shadowRoot?: ShadowRoot | null }).shadowRoot),
+			formAssociated: Boolean(ctor?.formAssociated),
+		})
+	}
+	return report
+}
+
+export type Capabilities = {
+	popover: boolean
+	declarativeShadowDom: boolean
+	scopedRegistries: boolean
+	trustedTypes: boolean
+	cssRegisteredProperties: boolean
+	elementInternalsAria: boolean
+	formAssociated: boolean
+	adoptedStyleSheets: boolean
+}
+
+/**
+ * Runtime feature probe. Tells an agent which platform capabilities the
+ * current sandbox exposes, so it can adapt without assuming the sandbox CSP
+ * or browser version. Every check is feature-detect, not UA-sniff.
+ */
+export function capabilities(): Capabilities {
+	const anyTemplate = typeof HTMLTemplateElement !== 'undefined' ? HTMLTemplateElement.prototype : null
+	const anyElInternals = typeof ElementInternals !== 'undefined' ? ElementInternals.prototype : null
+	return {
+		popover: typeof HTMLElement !== 'undefined' && 'popover' in HTMLElement.prototype,
+		declarativeShadowDom: Boolean(anyTemplate && 'shadowRootMode' in anyTemplate),
+		scopedRegistries: (() => {
+			try {
+				// Native scoped registries require a constructible CustomElementRegistry.
+				// Pre-Safari-26/Chrome-146, the constructor throws Illegal constructor.
+				new (window as { CustomElementRegistry?: new () => unknown }).CustomElementRegistry!()
+				return true
+			} catch {
+				return false
+			}
+		})(),
+		trustedTypes: typeof (globalThis as { trustedTypes?: unknown }).trustedTypes !== 'undefined',
+		cssRegisteredProperties: typeof (window as { CSS?: { registerProperty?: unknown } }).CSS?.registerProperty === 'function',
+		elementInternalsAria: Boolean(anyElInternals && 'role' in anyElInternals),
+		formAssociated: typeof ElementInternals !== 'undefined',
+		adoptedStyleSheets: typeof Document !== 'undefined' && 'adoptedStyleSheets' in Document.prototype,
+	}
+}
+
+export function manifestUrl(): string {
+	const blob = new Blob([JSON.stringify(manifest)], { type: 'application/json' })
+	return URL.createObjectURL(blob)
+}
+
+export { manifest }

package/src/agent/index.ts

@@ -0,0 +1 @@
+export * from './schmancy-skill'

package/src/agent/schmancy-skill.ts

@@ -0,0 +1,71 @@
+import { $LitElement } from '../../mixins/index'
+import { html } from 'lit'
+import { customElement } from 'lit/decorators.js'
+import {
+	a11yAudit,
+	capabilities,
+	help,
+	manifest,
+	manifestUrl,
+	platformPrimitive,
+	registeredTags,
+	tokens,
+} from './helpers'
+
+declare global {
+	interface Window {
+		schmancy?: {
+			manifest: typeof manifest
+			manifestUrl: string
+			help: typeof help
+			tokens: typeof tokens
+			platformPrimitive: typeof platformPrimitive
+			registeredTags: typeof registeredTags
+			a11yAudit: typeof a11yAudit
+			capabilities: typeof capabilities
+		}
+	}
+}
+
+let installedUrl: string | null = null
+
+function install() {
+	if (typeof window === 'undefined') return
+	if (installedUrl) return
+	installedUrl = manifestUrl()
+	window.schmancy = {
+		manifest,
+		manifestUrl: installedUrl,
+		help,
+		tokens,
+		platformPrimitive,
+		registeredTags,
+		a11yAudit,
+		capabilities,
+	}
+}
+
+/**
+ * Self-describing runtime helper. Drop `<schmancy-skill></schmancy-skill>`
+ * once on a page and `window.schmancy.help('schmancy-button')` returns the
+ * machine-readable entry for any tag. Renders nothing.
+ *
+ * @element schmancy-skill
+ */
+@customElement('schmancy-skill')
+export class SchmancySkill extends $LitElement() {
+	connectedCallback() {
+		super.connectedCallback()
+		install()
+	}
+
+	render() {
+		return html``
+	}
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'schmancy-skill': SchmancySkill
+	}
+}

package/src/agent/virtual-manifest.d.ts

@@ -0,0 +1,10 @@
+declare module 'virtual:schmancy-manifest' {
+	type ManifestModule = { kind: 'javascript-module'; path: string; declarations: Array<Record<string, unknown>> }
+	const manifest: {
+		schemaVersion: '1.0.0'
+		readme?: string
+		modules: ManifestModule[]
+		tokens: string[]
+	}
+	export default manifest
+}

package/src/area/area.service.ts

@@ -744,5 +744,16 @@ class AreaService implements AreaSubscription {
 	}
 }
 
+/**
+ * Area router singleton. Drives named `<schmancy-area>` outlets in the DOM
+ * — imperative push / pop, URL-synced, state-restoring. Pair with
+ * `lazy(() => import('./view'))` for code-split routes.
+ *
+ * @service
+ * @summary Imperative outlet-based router for `<schmancy-area>` elements.
+ * @method push({ area, component, params?, state? }) - Navigate an area to a component.
+ * @method pop(areaName) - Pop the top entry off an area's stack.
+ * @method current$(areaName) - Observable of the active route state for an area.
+ */
 export const area = AreaService.getInstance()
 export default area

package/src/content-drawer/drawer.service.ts

@@ -145,4 +145,13 @@ class DrawerService {
 	}
 }
 
+/**
+ * Content-drawer service. Mounts any element inside the right-hand content
+ * drawer of a `<schmancy-content-drawer>` layout.
+ *
+ * @service
+ * @summary Imperative content-drawer (right-side navigation panel).
+ * @method render({ component, ...options }) - Mount an element in the drawer.
+ * @method close() - Close the drawer.
+ */
 export const schmancyContentDrawer = new DrawerService()

package/src/dialog/dialog-service.ts

@@ -444,7 +444,17 @@ export class DialogService {
 const service = DialogService.getInstance()
 
 /**
- * Global dialog utility
+ * Global dialog utility. Imperative modal API — open any element as a dialog,
+ * or use the built-in `confirm` / `ask` / `danger` prompts. Returns Promises
+ * that resolve when the user picks an action.
+ *
+ * @service
+ * @summary Imperative modal dialogs and built-in confirm/ask/danger prompts.
+ * @method confirm(options: DialogOptions) - Built-in confirm prompt. Returns Promise<boolean>.
+ * @method ask(message, event?) - One-line yes/no prompt anchored to the triggering event.
+ * @method danger(options) - Destructive-action confirm styled with the error palette.
+ * @method component(element, options?) - Open any element as a modal.
+ * @method dismiss(id?) - Dismiss a dialog by id, or the topmost dialog.
  */
 export const $dialog = {
 	confirm: (options: DialogOptions): Promise<boolean> => {

package/src/notification/notification-service.ts

@@ -246,7 +246,17 @@ export class NotificationService {
 }
 
 /**
- * Global notification utility - provides a quick way to show notifications
+ * Global notification (toast) utility. Fire-and-forget API for success,
+ * error, info, and warning toasts, plus a low-level `show` for custom
+ * notifications.
+ *
+ * @service
+ * @summary Toast notifications — success, error, info, warning.
+ * @method show(options: NotificationOptions) - Low-level; show any NotificationOptions.
+ * @method success(message, options?) - Green success toast.
+ * @method error(message, options?) - Red error toast.
+ * @method info(message, options?) - Blue informational toast.
+ * @method warning(message, options?) - Amber warning toast.
  */
 export const $notify = {
 	/**

package/src/overlay/index.ts

@@ -0,0 +1,15 @@
+export * from './overlay.component'
+export * from './overlay.confirm-body'
+export * from './overlay.service'
+export type {
+	Anchor,
+	CloseReason,
+	Content,
+	OverlayConfirmOptions,
+	OverlayEntry,
+	OverlayLayout,
+	OverlayPromptOptions,
+	ShowFn,
+	ShowOptions,
+} from './overlay.types'
+export { lazy } from '../area/lazy'

package/src/overlay/overlay.animations.ts

@@ -0,0 +1,137 @@
+import {
+	DURATION_BACKDROP,
+	DURATION_EXIT,
+	EASE_IN,
+	EASE_OUT,
+	prefersReducedMotion,
+	SPRING_GENTLE,
+	SPRING_SNAPPY,
+} from '../utils/animation'
+import type { OverlayLayout } from './overlay.types'
+
+/**
+ * WAAPI keyframes + options per layout + direction.
+ *
+ * One animation vocabulary — no per-element bespoke keyframes. Aligns
+ * with the `animation` skill (spring physics presets). Honors
+ * `prefers-reduced-motion` by collapsing transforms to opacity-only.
+ *
+ * Returns `null` when reduced-motion is active and only opacity change
+ * is needed — the caller sets style directly.
+ */
+
+/**
+ * Shape matches both DOM `AnimationEffectTiming` and
+ * `KeyframeAnimationOptions` so it passes structural checks in both
+ * older and newer `lib.dom.d.ts` vintages.
+ */
+export interface AnimationSpec {
+	keyframes: Keyframe[]
+	options: {
+		duration: number
+		easing: string
+		fill?: FillMode
+	}
+}
+
+export function backdropAnimation(direction: 'in' | 'out'): AnimationSpec {
+	return direction === 'in'
+		? {
+				keyframes: [{ opacity: 0 }, { opacity: 1 }],
+				options: { duration: DURATION_BACKDROP, easing: EASE_OUT, fill: 'forwards' },
+			}
+		: {
+				keyframes: [{ opacity: 1 }, { opacity: 0 }],
+				options: { duration: DURATION_BACKDROP, easing: EASE_OUT, fill: 'forwards' },
+			}
+}
+
+export function surfaceAnimation(layout: OverlayLayout, direction: 'in' | 'out'): AnimationSpec {
+	const reduced = prefersReducedMotion()
+
+	if (reduced) {
+		// Opacity-only; explicit reset to { opacity: 1, transform: none } on `in`
+		// so any leftover transform from a prior `out` doesn't persist.
+		return direction === 'in'
+			? {
+					keyframes: [
+						{ opacity: 0, transform: 'none' },
+						{ opacity: 1, transform: 'none' },
+					],
+					options: { duration: 1, easing: 'linear', fill: 'forwards' },
+				}
+			: {
+					keyframes: [
+						{ opacity: 1, transform: 'none' },
+						{ opacity: 0, transform: 'none' },
+					],
+					options: { duration: 1, easing: 'linear', fill: 'forwards' },
+				}
+	}
+
+	switch (layout) {
+		case 'centered':
+			return direction === 'in'
+				? {
+						keyframes: [
+							{ opacity: 0, transform: 'scale(0.92) translateY(16px)' },
+							{ opacity: 1, transform: 'scale(1) translateY(0)' },
+						],
+						options: {
+							duration: SPRING_SNAPPY.duration,
+							easing: SPRING_SNAPPY.easingFallback,
+							fill: 'forwards',
+						},
+					}
+				: {
+						keyframes: [
+							{ opacity: 1, transform: 'scale(1) translateY(0)' },
+							{ opacity: 0, transform: 'scale(0.96) translateY(8px)' },
+						],
+						options: { duration: DURATION_EXIT, easing: EASE_IN, fill: 'forwards' },
+					}
+
+		case 'sheet':
+			return direction === 'in'
+				? {
+						keyframes: [
+							{ opacity: 0, transform: 'translateY(100%)' },
+							{ opacity: 1, transform: 'translateY(0)' },
+						],
+						options: {
+							duration: SPRING_GENTLE.duration,
+							easing: SPRING_GENTLE.easingFallback,
+							fill: 'forwards',
+						},
+					}
+				: {
+						keyframes: [
+							{ opacity: 1, transform: 'translateY(0)' },
+							{ opacity: 0, transform: 'translateY(100%)' },
+						],
+						options: {
+							duration: DURATION_EXIT,
+							easing: EASE_IN,
+							fill: 'forwards',
+						},
+					}
+
+		case 'anchored':
+			// No transform — CSS Anchor Positioning / Floating UI owns position.
+			// Scale-from-origin via transform-origin would be nicer but conflicts
+			// with popover top-layer + position. Keep opacity-only for safety.
+			return direction === 'in'
+				? {
+						keyframes: [{ opacity: 0 }, { opacity: 1 }],
+						options: {
+							duration: SPRING_SNAPPY.duration,
+							easing: SPRING_SNAPPY.easingFallback,
+							fill: 'forwards',
+						},
+					}
+				: {
+						keyframes: [{ opacity: 1 }, { opacity: 0 }],
+						options: { duration: DURATION_EXIT, easing: EASE_IN, fill: 'forwards' },
+					}
+	}
+}