@mhmo91/schmancy 0.9.12 → 0.9.13

package/src/agent/agent-bundle.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest'
+import './agent-entry'
+
+/**
+ * Acceptance test per the Claude Design handover §4.4:
+ *
+ * > "CI check: load the bundle in a headless browser, assert
+ * > `customElements.get('schmancy-button')` resolves, assert
+ * > `window.schmancy.help()` returns non-empty."
+ *
+ * This test is the runtime smoke test. It imports the agent bundle entry
+ * (which side-effect registers every <schmancy-*> tag plus <schmancy-skill>)
+ * and then verifies the self-describing surface is installed.
+ */
+describe('agent bundle — handover §4.4 acceptance', () => {
+	it('registers `schmancy-button` on import', () => {
+		expect(customElements.get('schmancy-button')).toBeDefined()
+	})
+
+	it('registers `schmancy-skill` on import', () => {
+		expect(customElements.get('schmancy-skill')).toBeDefined()
+	})
+
+	it('installs `window.schmancy` when a <schmancy-skill> connects', async () => {
+		const host = document.createElement('div')
+		const skill = document.createElement('schmancy-skill')
+		host.appendChild(skill)
+		document.body.appendChild(host)
+
+		await customElements.whenDefined('schmancy-skill')
+		// One microtask for connectedCallback to finish installing globals.
+		await new Promise(requestAnimationFrame)
+
+		expect(typeof window.schmancy).toBe('object')
+		expect(typeof window.schmancy?.help).toBe('function')
+		expect(typeof window.schmancy?.tokens).toBe('function')
+		expect(typeof window.schmancy?.capabilities).toBe('function')
+
+		host.remove()
+	})
+
+	it('`window.schmancy.help()` returns a non-empty manifest summary', async () => {
+		const skill = document.createElement('schmancy-skill')
+		document.body.appendChild(skill)
+		await customElements.whenDefined('schmancy-skill')
+		await new Promise(requestAnimationFrame)
+
+		const help = window.schmancy!.help() as { elements: unknown[]; services: unknown[] }
+		expect(Array.isArray(help.elements)).toBe(true)
+		expect(help.elements.length).toBeGreaterThan(50)
+
+		skill.remove()
+	})
+
+	it('`window.schmancy.help("schmancy-button")` returns attribute enum values', async () => {
+		const skill = document.createElement('schmancy-skill')
+		document.body.appendChild(skill)
+		await customElements.whenDefined('schmancy-skill')
+		await new Promise(requestAnimationFrame)
+
+		const btn = window.schmancy!.help('schmancy-button') as {
+			attributes?: Array<{ name: string; values?: string[] }>
+		}
+		expect(btn).toBeTruthy()
+		expect(btn.attributes?.length ?? 0).toBeGreaterThan(0)
+		const variant = btn.attributes?.find(a => a.name === 'variant')
+		expect(variant?.values).toContain('filled')
+
+		skill.remove()
+	})
+
+	it('`window.schmancy.capabilities()` reports every probed feature', async () => {
+		const skill = document.createElement('schmancy-skill')
+		document.body.appendChild(skill)
+		await customElements.whenDefined('schmancy-skill')
+		await new Promise(requestAnimationFrame)
+
+		const caps = window.schmancy!.capabilities()
+		expect(caps).toMatchObject({
+			popover: expect.any(Boolean),
+			declarativeShadowDom: expect.any(Boolean),
+			scopedRegistries: expect.any(Boolean),
+			trustedTypes: expect.any(Boolean),
+			cssRegisteredProperties: expect.any(Boolean),
+			elementInternalsAria: expect.any(Boolean),
+			formAssociated: expect.any(Boolean),
+			adoptedStyleSheets: expect.any(Boolean),
+		})
+
+		skill.remove()
+	})
+})

package/src/agent/agent-entry.ts

@@ -0,0 +1,17 @@
+import '../index'
+import './schmancy-skill'
+
+export {
+	$dialog,
+	$notify,
+	sheet,
+	SchmancySheetPosition,
+	schmancyContentDrawer,
+	theme,
+	area,
+	lazy,
+	createContext,
+	select,
+	selectItem,
+} from '../index'
+export { $LitElement } from '../../mixins/index'

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/sheet/sheet.service.ts

@@ -232,4 +232,14 @@ class BottomSheetService {
 	}
 
 }
+
+/**
+ * Bottom / side sheet service. Mounts any element as a sheet with a chosen
+ * position (see `SchmancySheetPosition` enum).
+ *
+ * @service
+ * @summary Imperative bottom / side sheet surface.
+ * @method open({ component, position? }) - Mount an element as a sheet.
+ * @method dismiss(id?) - Dismiss a sheet by id, or the topmost.
+ */
 export const sheet = new BottomSheetService()

package/src/theme/theme.service.ts

@@ -514,7 +514,17 @@ class ThemeService {
   }
 }
 
-// Export singleton instance
+/**
+ * Theme singleton. Reads and mutates the active theme (scheme, source color,
+ * locale); persists the user's scheme choice. Components subscribe via
+ * `theme.theme$` for changes.
+ *
+ * @service
+ * @summary Theme service — active scheme, source color, locale.
+ * @method next({ scheme?, source?, locale? }) - Update theme state.
+ * @method theme$ - Observable<TSchmancyTheme>; emits on every theme change.
+ * @method toggle() - Toggle between light and dark schemes.
+ */
 export const theme = ThemeService.getInstance()
 export const schmancyTheme = theme // Alias for convenience
 export default theme

package/types/src/agent/agent-bundle.test.d.ts

@@ -0,0 +1 @@
+import './agent-entry';

package/types/src/agent/agent-entry.d.ts

@@ -0,0 +1,4 @@
+import '../index';
+import './schmancy-skill';
+export { $dialog, $notify, sheet, SchmancySheetPosition, schmancyContentDrawer, theme, area, lazy, createContext, select, selectItem, } from '../index';
+export { $LitElement } from '../../mixins/index';

package/types/src/agent/helpers.d.ts

@@ -0,0 +1,87 @@
+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;
+    }>;
+};
+export declare function help(tag?: string): unknown;
+export declare function tokens(): string[];
+export declare function platformPrimitive(tag: string): ElementEntry['platformPrimitive'] | null;
+export declare function registeredTags(): string[];
+export declare function a11yAudit(): Array<{
+    tag: string;
+    role: string | null;
+    ariaLabel: string | null;
+    hasShadowRoot: boolean;
+    formAssociated: boolean;
+}>;
+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 declare function capabilities(): Capabilities;
+export declare function manifestUrl(): string;
+export { manifest };

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

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

package/types/src/agent/schmancy-skill.d.ts

@@ -0,0 +1,33 @@
+import { a11yAudit, capabilities, help, manifest, 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;
+        };
+    }
+}
+declare const SchmancySkill_base: CustomElementConstructor & import("../../mixins/constructor").Constructor<import("lit").LitElement> & import("../../mixins/constructor").Constructor<import("../../mixins/baseElement").IBaseMixin>;
+/**
+ * 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
+ */
+export declare class SchmancySkill extends SchmancySkill_base {
+    connectedCallback(): void;
+    render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'schmancy-skill': SchmancySkill;
+    }
+}
+export {};

package/types/src/area/area.service.d.ts

@@ -130,5 +130,16 @@ declare class AreaService implements AreaSubscription {
      */
     getRoute(areaName: string): ActiveRoute | undefined;
 }
+/**
+ * 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 declare const area: AreaService;
 export default area;

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

@@ -36,5 +36,14 @@ declare class DrawerService {
      */
     push(options: DrawerPushOptions): void;
 }
+/**
+ * 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 declare const schmancyContentDrawer: DrawerService;
 export {};

package/types/src/dialog/dialog-service.d.ts

@@ -67,7 +67,17 @@ export declare class DialogService {
     private getDefaultPosition;
 }
 /**
- * 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 declare const $dialog: {
     confirm: (options: DialogOptions) => Promise<boolean>;

package/types/src/notification/notification-service.d.ts

@@ -64,7 +64,17 @@ export declare class NotificationService {
     persistent(message: string, options?: Partial<Omit<NotificationOptions, 'message' | 'duration'>>): string;
 }
 /**
- * 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 declare const $notify: {
     /**