@nan0web/ui 1.9.0 → 1.11.0

package/src/domain/components/ShellModel.js

@@ -0,0 +1,243 @@
+import { Model } from '@nan0web/types'
+import { ask, log } from '../../core/Intent.js'
+
+/**
+ * ShellModel — OLMUI Component Model for CLI Orchestration
+ * Canonical CLI entry that describes available operations as a schema.
+ */
+export class ShellModel extends Model {
+	static $id = '@nan0web/ui/ShellModel'
+
+	static command = {
+		help: 'What do you want to do?',
+		type: 'select',
+		default: null,
+		positional: true,
+		// options: [
+		// 	BootEngine,
+		// 	InteractiveCLI,
+		// 	DevMode,
+		// 	BuildProject,
+		// 	TestSSG,
+		// 	SSGGallery,
+		// 	TestWeb,
+		// 	WebGallery,
+		// 	ConfigWizard,
+		// ],
+		options: [
+			{ label: '📡 Boot Engine (Run OS)', value: 'run' },
+			{ label: '🖥️ Interactive CLI', value: 'cli' },
+			{ label: '🧬 Dev Mode (Hot-Reload)', value: 'dev' },
+			{ label: '📦 Build Project (Data & UI)', value: 'build' },
+			{ label: '🧪 Test SSG', value: 'test:ssg' },
+			{ label: '🔭 SSG Gallery', value: 'ssg:gallery' },
+			{ label: '🧪 Test Web', value: 'test:web' },
+			{ label: '🔭 Web Gallery', value: 'web:gallery' },
+			{ label: '🔧 Config Wizard', value: 'config' },
+		],
+		required: true,
+	}
+	
+	static data = {
+		help: 'Data source (DSN)',
+		type: 'string',
+		default: 'data/',
+		alias: 'dsn',
+	}
+
+	static index = {
+		help: 'Directory index file name (e.g. README or index)',
+		type: 'string',
+		default: 'index',
+	}
+
+	static locale = {
+		help: 'Application locale',
+		type: 'string',
+		default: 'en',
+	}
+
+	static port = {
+		help: 'Server port',
+		type: 'string',
+		default: '3000',
+	}
+
+
+	#options = {}
+
+	/**
+	 * @param {object} data
+	 * @param {object} [options] External dependencies (AppRunner, SSRServer, etc.)
+	 */
+	constructor(data = {}, options = {}) {
+		super(data)
+		this.#options = options
+		/** @type {string|null} */ this.command
+		/** @type {string} */ this.data
+		/** @type {string} */ this.index
+		/** @type {string} */ this.locale
+		/** @type {string} */ this.port
+	}
+
+	async *run() {
+		yield log('info', '📡 NaN0Web Engine OLMUI Shell Ready')
+
+		if (!this.command || this.command === 'help') {
+			const res = yield ask('Shell', ShellModel)
+			if (res.cancelled) return
+			Object.assign(this, res.value)
+		}
+
+		if (this.command !== 'cli' && this.command !== 'help') {
+			yield log('info', `📡 Executing command: ${this.command}...`)
+		}
+
+		switch (this.command) {
+			case 'run':
+				return yield* this.#runEngine()
+			case 'cli':
+				return yield* this.#runCli()
+			case 'config':
+				return yield* this.#runConfig()
+			case 'build':
+				return yield* this.#runBuild()
+			case 'dev':
+				return yield* this.#runDev()
+			case 'test:ssg':
+			case 'ssg:gallery':
+			case 'test:web':
+			case 'web:gallery':
+				return yield* this.#runNpmScript(this.command)
+			default:
+				yield log('error', `Unknown command: ${this.command}`)
+		}
+
+		this.command = null
+	}
+
+	async *#runCli() {
+		const { spawn, locale, dsn } = this.#options
+		if (!spawn) {
+			yield log('error', 'Spawn utility missing. CLI mode requires Node environment.')
+			return
+		}
+
+		const bankFrame = ' ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ '
+		yield log(
+			'success',
+			`\x1b[1m\n${bankFrame}\n📡 Launching Sub-App CLI...\n${bankFrame}\n\x1b[22m`,
+		)
+
+		const absPath = (await import('node:path')).resolve('src/ui/cli/index.js')
+		const { existsSync } = await import('node:fs')
+		if (!existsSync(absPath)) {
+			yield log(
+				'error',
+				`No CLI runner found at ${absPath}. Ensure you are in the application root.`,
+			)
+			return
+		}
+
+		const args = [absPath]
+		if (this.locale) args.push('--locale', this.locale)
+		if (this.data) args.push('--data', this.data)
+
+		const extra = (process.argv || []).slice(3)
+		args.push(...extra)
+
+		try {
+			const code = await spawn('node', args, { stdio: 'inherit' })
+			if (code !== 0) yield log('error', `CLI exited with code ${code}`)
+		} catch (/** @type {any} */ e) {
+			yield log('error', `Failed to spawn CLI: ${e.message}`)
+		}
+	}
+
+	async *#runEngine() {
+		const { AppRunner, SSRServer } = this.#options
+		if (!AppRunner) return yield log('error', 'AppRunner dependency missing')
+
+		const runner = new AppRunner({
+			dsn: this.data,
+			port: this.port,
+			locale: this.locale,
+			directoryIndex: this.index,
+		})
+		for await (const msg of runner.run()) {
+			yield log('info', msg)
+		}
+
+		const server = new SSRServer(runner)
+		const port = runner.config?.port || 3000
+		const { protocol } = await server.listen(port)
+
+		yield log('success', `\n🌐 Server running on ${protocol}://localhost:${port}`)
+
+		// Keep alive in CLI mode
+		if (typeof process !== 'undefined') {
+			while (true) {
+				await new Promise((r) => setTimeout(r, 60000))
+			}
+		}
+	}
+
+	async *#runConfig() {
+		const { NaN0WebConfig, DBwithFSDriver } = this.#options
+		const res = yield ask('config', NaN0WebConfig)
+		if (res.cancelled) return
+
+		const data = res.value
+		if (typeof process !== 'undefined' && DBwithFSDriver) {
+			const db = new DBwithFSDriver({ cwd: process.cwd() })
+			await db.connect()
+			await db.saveDocument('nan0web.config.yaml', {
+				name: data.name,
+				dsn: data.data || data.dsn,
+				locale: data.locale,
+				port: data.port,
+				directoryIndex: data.index,
+			})
+			yield log('success', '\n✅ Config saved to nan0web.config.yaml')
+		}
+	}
+
+	async *#runBuild() {
+		const { spawn, AppRunner, SSRServer } = this.#options
+		if (!spawn) return yield log('error', 'Spawn missing')
+
+		const { existsSync } = await import('node:fs')
+		const viteConfig = existsSync('vite.docs.js') ? 'vite.docs.js' : 
+						  existsSync('vite.config.js') ? 'vite.config.js' : null
+
+		if (viteConfig) {
+			yield log('info', `🛠 Building UI (Vite using ${viteConfig})...`)
+			const exitCode = await spawn('npx', ['vite', 'build', '-c', viteConfig])
+			if (exitCode !== 0) yield log('error', '⚠️ Vite build failed.')
+		}
+
+		const runner = new AppRunner({
+			dsn: this.data,
+			locale: this.locale,
+			directoryIndex: this.index,
+		})
+		for await (const msg of runner.run()) yield log('info', msg)
+		const server = new SSRServer(runner)
+		const stats = await server.exportStatic('dist')
+		yield log('success', `✅ Built ${stats.count}/${stats.total} pages into /dist`)
+	}
+
+	async *#runDev() {
+		const { spawn } = this.#options
+		if (!spawn) return yield log('error', 'Dev mode requires spawn')
+		yield log('info', '🧬 Starting VITE Dev Server...')
+		await spawn('npx', ['vite'], { stdio: 'inherit' })
+	}
+
+	async *#runNpmScript(script) {
+		const { spawn } = this.#options
+		if (!spawn) return
+		yield log('info', `🔭 Running npm run ${script}...`)
+		await spawn('npm', ['run', script], { stdio: 'inherit' })
+	}
+}

package/src/domain/components/TableModel.js

@@ -1,10 +1,17 @@
 import { Model } from '@nan0web/types'
+import { show, result } from '../../core/Intent.js'
 
 /**
  * Model-as-Schema for Table Data component.
  * Displays tabular string data in rows and columns.
  */
 export class TableModel extends Model {
+	static $id = '@nan0web/ui/TableModel'
+
+	static UI = {
+		displayingTable: 'Displaying table with {count} rows',
+	}
+
 	static columns = {
 		help: 'Array of column headers',
 		type: 'string[]',
@@ -34,14 +41,11 @@ export class TableModel extends Model {
 	 * @returns {AsyncGenerator<any, any, any>}
 	 */
 	async *run() {
-		yield {
-			type: 'log',
-			level: 'info',
-			message: `Displaying table with ${this.rows?.length || 0} rows`,
+		yield show(this._.t(TableModel.UI.displayingTable, { count: this.rows?.length || 0 }), 'info', {
 			component: 'Table',
 			model: this,
-		}
+		})
 
-		return { type: 'result', data: { rowsCount: this.rows?.length || 0 } }
+		return result({ rowsCount: this.rows?.length || 0 })
 	}
 }

package/src/domain/components/ToastModel.js

@@ -1,9 +1,16 @@
 import { Model } from '@nan0web/types'
+import { show, result } from '../../core/Intent.js'
 
 /**
  * Model-as-Schema for Toast notification.
  */
 export class ToastModel extends Model {
+	static $id = '@nan0web/ui/ToastModel'
+
+	static UI = {
+		toastLog: '{message}',
+	}
+
 	static variant = {
 		help: 'Notification color scheme',
 		default: 'info',
@@ -37,14 +44,11 @@ export class ToastModel extends Model {
 	 * @returns {AsyncGenerator<any, any, any>}
 	 */
 	async *run() {
-		yield {
-			type: 'log',
-			level: this.variant === 'error' ? 'error' : 'info',
-			message: this.message,
+		yield show(this._.t(ToastModel.UI.toastLog, { message: this.message }), this.variant === 'error' ? 'error' : 'info', {
 			component: 'Toast',
 			model: this,
-		}
+		})
 
-		return { type: 'result', data: { shown: true } }
+		return result({ dismissed: true })
 	}
 }

package/src/domain/components/index.js

@@ -20,6 +20,7 @@ export { GalleryModel } from './GalleryModel.js'
 export { PriceModel } from './PriceModel.js'
 export { PricingModel } from './PricingModel.js'
 export { PricingSectionModel } from './PricingSectionModel.js'
+export { FeatureGridModel, FeatureItemModel } from './FeatureGridModel.js'
 
 // Hero
 
@@ -39,7 +40,8 @@ export { HeaderConfigModel } from './HeaderConfigModel.js'
 export { FooterVisibilityModel } from './FooterVisibilityModel.js'
 export { FooterConfigModel } from './FooterConfigModel.js'
 
-// Business Critical
 export { EmptyStateModel } from './EmptyStateModel.js'
 export { BannerModel } from './BannerModel.js'
 export { ProfileDropdownModel } from './ProfileDropdownModel.js'
+export { MarkdownModel } from './MarkdownModel.js'
+export { ShellModel } from './ShellModel.js'

package/src/domain/index.js

@@ -1,13 +1,19 @@
+// Model runner (Model as App)
+/** @typedef {import('./ModelAsApp.js').ModelAsAppOptions} ModelAsAppOptions */
+export { ModelAsApp } from './ModelAsApp.js'
+
 // Domain Models — OLMUI Model-as-Schema
 export { SandboxModel } from './SandboxModel.js'
+export { Content } from './Content.js'
+export { Document } from './Document.js'
 export { ShowcaseAppModel } from './ShowcaseAppModel.js'
 export { default as Navigation } from './Navigation.js'
-export { Language } from '@nan0web/i18n/src/domain/Language.js'
 
 // Layout Models (Phase 1)
-export { default as HeaderModel } from './HeaderModel.js'
-export { default as FooterModel } from './FooterModel.js'
-export { default as HeroModel } from './HeroModel.js'
+export { LayoutModel } from './LayoutModel.js'
+export { HeaderModel } from './HeaderModel.js'
+export { FooterModel } from './FooterModel.js'
+export { HeroModel } from './HeroModel.js'
 
 // Component Models
 export {
@@ -24,6 +30,8 @@ export {
 	AccordionModel,
 	GalleryModel,
 	PriceModel,
+	FeatureGridModel,
+	FeatureItemModel,
 	PricingModel,
 	CommentModel,
 	TestimonialModel,
@@ -39,3 +47,5 @@ export {
 	BannerModel,
 	ProfileDropdownModel,
 } from './components/index.js'
+
+export { ShellModel } from './components/ShellModel.js'

package/src/index.js

@@ -12,7 +12,6 @@ import App from './App/index.js'
 export { Frame, FrameProps, Locale, StdIn, StdOut, View, RenderOptions, Model, Component, App }
 export { format } from './format.js'
 export { default as Navigation } from './domain/Navigation.js'
-export { Language } from '@nan0web/i18n/src/domain/Language.js'
 
 // export default App
 export { default as FormMessage } from './core/Form/Message.js'
@@ -27,6 +26,26 @@ export { default as Error, CancelError } from './core/Error/index.js'
 export { default as UiAdapter } from './core/UiAdapter.js'
 
 // OLMUI Generator Engine
-export { validateIntent, ask, progress, log, result, INTENT_TYPES, isModelSchema } from './core/Intent.js'
+/** @typedef {import('./core/Intent.js').LogLevel} LogLevel */
+/** @typedef {import('./core/Intent.js').ShowLevel} ShowLevel */
+/** @typedef {import('./core/Intent.js').FieldSchema} FieldSchema */
+/** @typedef {import('./core/Intent.js').Intent} Intent */
+/** @typedef {import('./core/Intent.js').IntentResponse} IntentResponse */
+/** @typedef {import('./core/Intent.js').AskIntent} AskIntent */
+/** @typedef {import('./core/Intent.js').ProgressIntent} ProgressIntent */
+/** @typedef {import('./core/Intent.js').LogIntent} LogIntent */
+/** @typedef {import('./core/Intent.js').ShowIntent} ShowIntent */
+/** @typedef {import('./core/Intent.js').RenderIntent} RenderIntent */
+/** @typedef {import('./core/Intent.js').ResultIntent} ResultIntent */
+/** @typedef {import('./core/Intent.js').IntentType} IntentType */
+/** @typedef {import('./core/Intent.js').AskResponse} AskResponse */
+/** @typedef {import('./core/Intent.js').AbortResponse} AbortResponse */
+/** @typedef {import('./core/Intent.js').ShowData} ShowData */
+export * from './core/Intent.js'
+
 export { IntentErrorModel } from './core/IntentErrorModel.js'
 export { runGenerator } from './core/GeneratorRunner.js'
+export { buildNan0SpecFromTrace } from './testing/CrashReporter.js'
+
+/** @typedef {import('./domain/index.js').ModelAsAppOptions} ModelAsAppOptions */
+export * from './domain/index.js'

package/src/inspect.js

@@ -0,0 +1,2 @@
+export * from './testing/SnapshotRunner.js'
+export * from './testing/verifySnapshot.js'

package/src/test/ScenarioAdapter.js

@@ -0,0 +1,59 @@
+import InputAdapter from '../core/InputAdapter.js'
+
+/**
+ * Deterministic Scenario Adapter for OLMUI Testing.
+ * 
+ * Drives the Model generator through a predefined script of responses,
+ * enabling millisecond-fast verification of complex business logic.
+ */
+export default class ScenarioAdapter extends InputAdapter {
+	/**
+	 * @param {Array<{field: string, value: any, cancelled?: boolean}>} [scenario=[]]
+	 */
+	constructor(scenario = []) {
+		super()
+		this.scenario = scenario
+		this.intents = [] // Recorded intents for verification
+		this.console = {
+			info: () => {},
+			warn: () => {},
+			error: () => {},
+			debug: () => {},
+			log: () => {},
+		}
+	}
+
+	/**
+	 * @param {import('../core/Intent.js').AskIntent} intent
+	 * @returns {Promise<import('../core/Intent.js').AskResponse>}
+	 */
+	async askIntent(intent) {
+		this.intents.push(intent)
+		const match = this.scenario.find((s) => s.field === intent.field)
+		if (match) {
+			return { value: match.value, cancelled: !!match.cancelled }
+		}
+		// If no specific match, try to use the first available answer or default
+		return { value: null }
+	}
+
+	/** @param {import('../core/Intent.js').ProgressIntent} intent */
+	async progressIntent(intent) {
+		this.intents.push(intent)
+	}
+
+	/** @param {import('../core/Intent.js').ShowIntent} intent */
+	async showIntent(intent) {
+		this.intents.push(intent)
+	}
+
+	/** @param {import('../core/Intent.js').RenderIntent} intent */
+	async renderIntent(intent) {
+		this.intents.push(intent)
+	}
+
+	/** @param {import('../core/Intent.js').ResultIntent} intent */
+	async resultIntent(intent) {
+		this.intents.push(intent)
+	}
+}

package/src/test/ScenarioTest.js

@@ -0,0 +1,51 @@
+import { runGenerator } from '../core/GeneratorRunner.js'
+import OutputAdapter from '../core/OutputAdapter.js'
+import ScenarioAdapter from './ScenarioAdapter.js'
+
+/**
+ * Deterministic Scenario Test Runner.
+ * Orchestrates a model against a predefined scenario, mocking I/O immediately.
+ */
+export class ScenarioTest {
+	/**
+	 * Runs an application model with a specific set of answers.
+	 *
+	 * @param {typeof import('../domain/ModelAsApp.js').ModelAsApp} AppClass
+	 * @param {Array<{field: string, value: any, cancelled?: boolean}>} scenario
+	 * @param {any} [appData={}]
+	 * @returns {Promise<{ value: any, intents: any[], error?: Error | undefined }>}
+	 */
+	static async run(AppClass, scenario = [], appData = {}) {
+		const inputAdapter = new ScenarioAdapter(scenario)
+
+		const app = new AppClass(appData, { adapter: inputAdapter })
+
+		let value
+		let error
+
+		try {
+			// runGenerator executes the Intents returned by AppClass.run()
+			value = await runGenerator(
+				app.run(),
+				{
+					ask: inputAdapter.askIntent.bind(inputAdapter),
+					progress: inputAdapter.progressIntent.bind(inputAdapter),
+					show: inputAdapter.showIntent.bind(inputAdapter),
+					render: inputAdapter.renderIntent.bind(inputAdapter),
+					result: inputAdapter.resultIntent.bind(inputAdapter),
+				},
+				{ timeoutMs: 3333 },
+			)
+		} catch (err) {
+			error = /** @type {Error} */ (err)
+		}
+
+		return {
+			value,
+			intents: inputAdapter.intents,
+			error,
+		}
+	}
+}
+
+export default ScenarioTest

package/src/test/ScenarioTest.story.js

@@ -0,0 +1,56 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import DB from '@nan0web/db-fs'
+import { SpecRunner } from '../testing/index.js'
+import { ModelAsApp, ask, show, result } from '../index.js'
+
+const db = new DB({ root: 'tests/uk' })
+
+async function loadStory(name) {
+	const doc = await db.loadDocument(`${name}.nan0`)
+	return doc
+}
+
+describe('Workflow Story: Shopping Cart Purchase', () => {
+	class ShoppingCartApp extends ModelAsApp {
+		async *run() {
+			const { value: product } = yield ask('product', { help: 'Select product' })
+			if (product === 'laptop') {
+				yield show('Good choice!')
+			}
+			const { value: confirm } = yield ask('confirm', { help: 'Confirm purchase?' })
+			return result({ product: product, confirm: confirm })
+		}
+	}
+
+	it('should successfully buy a laptop and show a message via SpecRunner', async () => {
+		const doc = await loadStory('shopping.story')
+		assert.ok(Array.isArray(doc.story), 'Story must be an array')
+
+		await assert.doesNotReject(() => SpecRunner.execute(doc.story, { ShoppingCartApp }))
+	})
+})
+
+describe('Workflow Story: Validated Input Form', () => {
+	class ValidatedApp extends ModelAsApp {
+		async *run() {
+			const { value: code } = yield ask('code', { help: 'Enter code', required: true })
+			if (!code) throw new Error('Code is mandatory')
+			return result({ code: code })
+		}
+	}
+
+	it('should successfully process a valid code via SpecRunner', async () => {
+		const doc = await loadStory('validated.story')
+		assert.ok(Array.isArray(doc.story), 'Story must be an array')
+
+		await assert.doesNotReject(() => SpecRunner.execute(doc.story, { ValidatedApp }))
+	})
+
+	it('should fail if user provides empty input (Node.js Test)', async () => {
+		// Testing error conditions are better suited as explicit scenarios or node:test
+		const stream = [{ ValidatedApp: {} }, { ask: 'code', $value: '' }]
+
+		await assert.rejects(SpecRunner.execute(stream, { ValidatedApp }), /Code is mandatory/)
+	})
+})

package/src/testing/CrashReporter.js

@@ -0,0 +1,56 @@
+/**
+ * @file CrashReporter.js — Nan0Spec serialization.
+ */
+
+/**
+ * Transforms an execution trace from GeneratorRunner into a strict Nan0Spec model
+ * ready to be saved as a .nan0 file for Crash Reporting and Integration Tests.
+ *
+ * @param {string} appName The name of the root model/app (e.g. 'ShoppingCartApp').
+ * @param {object} appData The initial data provided to the app.
+ * @param {import('../core/Intent.js').Intent[]} trace The array of intents executed.
+ * @returns {Array<object>} The serializable Nan0Spec array.
+ */
+export function buildNan0SpecFromTrace(appName, appData, trace) {
+	const spec = []
+
+	// 1. Initial State
+	spec.push({
+		[appName]: appData ? JSON.parse(JSON.stringify(appData)) : {},
+	})
+
+	/** @type {Record<string, string>} Mapping from intent type to its primary payload field in Nan0Spec */
+	const PAYLOAD_MAP = {
+		ask: 'field',
+		show: 'message',
+		log: 'message',
+		progress: 'message',
+		render: 'component',
+		agent: 'task'
+	}
+
+	// 2. Map trace
+	for (const intent of trace) {
+		if (intent.type === 'result') {
+			spec.push({ result: intent.data || null })
+			continue
+		}
+
+		const key = PAYLOAD_MAP[intent.type]
+		if (!key) continue
+
+		// Create the primary step { type: payload }
+		const step = { [intent.type]: intent[key] }
+
+		// Automatically include all metadata/response fields (starting with $)
+		for (const [k, v] of Object.entries(intent)) {
+			if (k.startsWith('$') && v !== undefined) {
+				step[k] = v
+			}
+		}
+
+		spec.push(step)
+	}
+
+	return spec
+}

package/src/testing/GalleryGenerator.js

@@ -0,0 +1,29 @@
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { SnapshotRunner } from './SnapshotRunner.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const rootDir = path.resolve(__dirname, '../../')
+const dataDir = path.resolve(rootDir, 'docs/data')
+const snapshotsDir = path.resolve(rootDir, 'snapshots/core')
+
+const groups = {
+	Actions: ['Button', 'Toggle'],
+	Forms: ['Input', 'Select', 'Slider', 'Autocomplete', 'Color', 'Shadow'],
+	Data: ['Accordion', 'Card', 'Sortable', 'Table', 'Tree', 'CodeBlock', 'Markdown', 'Badge'],
+	Feedback: ['Alert', 'Confirm', 'Modal', 'ProgressBar', 'Spinner', 'Toast'],
+	System: ['LangSelect', 'ThemeToggle'],
+}
+
+function getCategory(comp) {
+	for (const [cat, comps] of Object.entries(groups)) {
+		if (comps.includes(comp)) return cat
+	}
+	return 'Other'
+}
+
+SnapshotRunner.generateAndAudit({
+	dataDir,
+	snapshotsDir,
+	getCategory,
+}).catch(console.error)