@arkstack/view 0.15.2 → 0.15.4

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 /// <reference path="./app.d.ts" />
-import { t as clearRouterViewPlugin } from "./plugins-D3vyoc8i.js";
+import { t as clearRouterViewPlugin } from "./plugins-Crhr7ifw.js";
 import edge, { Edge, Edge as Edge$1 } from "edge.js";
+import { ParserTagDefinitionContract } from "edge.js/types";
 
 //#region src/ViewInstance.d.ts
 declare class ViewInstance implements PromiseLike<string> {
@@ -56,16 +57,109 @@ declare class ViewFactory {
   private mountedPackages;
   private packageViewsPath;
   constructor(options?: ViewFactoryOptions);
+  /**
+   * Create a new view instance for the given view name and data.
+   *
+   * @param name
+   * @param data
+   * @returns
+   */
   make(name: ViewName, data?: ViewData): ViewInstance;
+  /**
+   * Render the first view that exists from the given list of names.
+   *
+   * @param names
+   * @param data
+   * @returns
+   */
   first(names: ViewName[], data?: ViewData): ViewInstance;
+  /**
+   * Check if a view exists.
+   *
+   * @param name
+   * @returns
+   */
   exists(name: ViewName): boolean;
+  /**
+   * Share data with all views.
+   * This data will be available in every view rendered by the factory.
+   *
+   * @param key
+   * @param value
+   */
   share(key: string, value: any): this;
   share(data: ViewData): this;
+  /**
+   * Register a view composer for the given view name(s).
+   * A view composer is a function or object that is called when a view is
+   * rendered, allowing you to modify the view's data or perform other actions.
+   *
+   * @param names
+   * @param composer
+   * @returns
+   */
   composer(names: ViewComposerName, composer: ViewComposer): this;
+  /**
+   * Mount a directory containing views.
+   * If only one argument is provided, it will be treated as the views directory.
+   * If two arguments are provided, the first will be treated as the disk name and
+   * the second as the views directory.
+   *
+   * @param viewsDirectory
+   */
   mount(viewsDirectory: string | URL): this;
   mount(diskName: string, viewsDirectory: string | URL): this;
+  /**
+   * Register a raw template with the given name and contents.
+   *
+   * @param name
+   * @param contents
+   * @returns
+   */
   raw(name: ViewName, contents: string): this;
+  /**
+   * Register a custom tag with the given name, block type, seekable type,
+   * and compiler function.
+   *
+   * @param tagName
+   * @param block
+   * @param seekable
+   * @param compiler
+   */
+  tag(
+  /**
+   * The tag name
+   */
+
+  tagName: string,
+  /**
+   * Tag accepts content within the opening and
+   * closing tags
+   */
+
+  block: boolean,
+  /**
+   * Tag accepts parameters
+   */
+
+  seekable: boolean,
+  /**
+   * The parser needs the `compile` method on every tag
+   */
+
+  compiler: ParserTagDefinitionContract['compile']): void;
+  /**
+   * Flush all shared data. This will remove all data that has been shared with all views.
+   *
+   * @returns
+   */
   flushShared(): this;
+  /**
+   * Flush all registered composers. This will remove all composers that have
+   * been registered for any view.
+   *
+   * @returns
+   */
   flushComposers(): this;
   private getComposers;
   private runComposers;
@@ -138,6 +232,39 @@ type PackageViewReference = {
 declare const parsePackageViewName: (name: string) => PackageViewReference | null;
 declare const resolvePackageViewsPath: (nodePackageName: string, viewPath?: string) => string;
 //#endregion
+//#region src/vite.d.ts
+interface ViteTagOptions {
+  /** Force development (Vite dev server) tags regardless of `NODE_ENV`. */
+  hot?: boolean;
+  /** Vite dev server URL. Defaults to `VITE_DEV_URL` or `http://localhost:5173`. */
+  devUrl?: string;
+  /** Path to the Vite build manifest. Defaults to `public/build/.vite/manifest.json`. */
+  manifest?: string;
+  /** Public URL prefix the built assets are served from. Defaults to `/build/`. */
+  buildDir?: string;
+}
+/**
+ * Resolve `<script>`/`<link>` tags for one or more Vite entries.
+ *
+ * In development (when `NODE_ENV` is not `production`, or `hot` is set) it points
+ * at the Vite dev server and includes the `@vite/client`. In production it reads
+ * the build manifest and emits the hashed asset tags (including any CSS a chunk
+ * imports). Backs the `@vite(...)` Edge tag.
+ *
+ * @param entries
+ * @param options
+ * @returns
+ */
+declare const viteTags: (entries: string | string[], options?: ViteTagOptions) => string;
+/**
+ * Register the `@vite(...)` tag (and its backing global) on a view factory so
+ * templates can emit Vite asset tags: `@vite('resources/js/app.ts')` or
+ * `@vite(['resources/css/app.css', 'resources/js/app.ts'])`.
+ *
+ * @param factory
+ */
+declare const registerViteTag: (factory: ViewFactory) => void;
+//#endregion
 //#region src/viewContext.d.ts
 declare const getViewData: () => ViewData;
 declare const enterViewData: (data?: ViewData) => void;
@@ -145,4 +272,4 @@ declare const runWithViewData: <T>(data: ViewData, callback: () => T | Promise<T
 declare const clearViewData: () => void;
 declare const collectViewData: (context: Record<string, any>) => ViewData;
 //#endregion
-export { ComposerRunner, Edge, SyncComposerRunner, View, ViewComposer, ViewComposerClass, ViewComposerHandler, ViewComposerName, ViewComposerObject, ViewData, ViewErrorBag, ViewErrorRecord, ViewErrorValue, ViewFactory, ViewFactoryOptions, ViewInstance, ViewName, clearRouterViewPlugin, clearViewData, collectViewData, edge, enterViewData, getViewData, normalizeViewErrors, parsePackageViewName, resolvePackageViewsPath, runWithViewData, view };
+export { type ComposerRunner, Edge, type SyncComposerRunner, View, type ViewComposer, type ViewComposerClass, type ViewComposerHandler, type ViewComposerName, type ViewComposerObject, type ViewData, ViewErrorBag, type ViewErrorRecord, type ViewErrorValue, ViewFactory, type ViewFactoryOptions, ViewInstance, type ViewName, type ViteTagOptions, clearRouterViewPlugin, clearViewData, collectViewData, edge, enterViewData, getViewData, normalizeViewErrors, parsePackageViewName, registerViteTag, resolvePackageViewsPath, runWithViewData, view, viteTags };

package/dist/index.js

@@ -1,3 +1,3 @@
-import { a as collectViewData, c as runWithViewData, d as resolvePackageViewsPath, f as view, i as clearViewData, l as ViewInstance, m as normalizeViewErrors, n as View, o as enterViewData, p as ViewErrorBag, r as ViewFactory, s as getViewData, t as clearRouterViewPlugin, u as parsePackageViewName } from "./plugins-BFBs38yL.js";
+import { a as viteTags, c as enterViewData, d as ViewInstance, f as parsePackageViewName, g as normalizeViewErrors, h as ViewErrorBag, i as registerViteTag, l as getViewData, m as view, n as View, o as clearViewData, p as resolvePackageViewsPath, r as ViewFactory, s as collectViewData, t as clearRouterViewPlugin, u as runWithViewData } from "./plugins-DWO_aTcP.js";
 import edge, { Edge } from "edge.js";
-export { Edge, View, ViewErrorBag, ViewFactory, ViewInstance, clearRouterViewPlugin, clearViewData, collectViewData, edge, enterViewData, getViewData, normalizeViewErrors, parsePackageViewName, resolvePackageViewsPath, runWithViewData, view };
+export { Edge, View, ViewErrorBag, ViewFactory, ViewInstance, clearRouterViewPlugin, clearViewData, collectViewData, edge, enterViewData, getViewData, normalizeViewErrors, parsePackageViewName, registerViteTag, resolvePackageViewsPath, runWithViewData, view, viteTags };

package/dist/plugins-Crhr7ifw.d.ts

@@ -0,0 +1,4 @@
+//#region src/plugins.d.ts
+declare const clearRouterViewPlugin: import("clear-router/core").ClearRouterPlugin<any, any>;
+//#endregion
+export { clearRouterViewPlugin as t };

package/dist/{plugins-BFBs38yL.js → plugins-DWO_aTcP.js}

@@ -1,7 +1,7 @@
-import { isClass } from "@arkstack/common";
+import { env, isClass, nodeEnv } from "@arkstack/common";
 import { Arkstack } from "@arkstack/contract";
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { Edge } from "edge.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { Hook } from "@arkstack/foundry";
@@ -306,6 +306,66 @@ const collectViewData = (context) => {
 	});
 };
 //#endregion
+//#region src/vite.ts
+const scriptTag = (src) => `<script type="module" src="${src}"><\/script>`;
+const styleTag = (href) => `<link rel="stylesheet" href="${href}">`;
+const isCss = (entry) => /\.(css|scss|sass|less|styl|pcss)$/.test(entry);
+const trimTrailingSlash = (value) => value.replace(/\/+$/, "");
+const withTrailingSlash = (value) => `${trimTrailingSlash(value)}/`;
+const devTags = (entries, devUrl) => {
+	const base = trimTrailingSlash(devUrl);
+	return [scriptTag(`${base}/@vite/client`), ...entries.map((entry) => scriptTag(`${base}/${entry.replace(/^\/+/, "")}`))].join("\n");
+};
+const productionTags = (entries, manifestPath, buildDir) => {
+	let manifest;
+	try {
+		manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+	} catch {
+		throw new Error(`Vite manifest not found at ${manifestPath}. Run \`vite build\` before serving in production.`);
+	}
+	const base = withTrailingSlash(buildDir);
+	const tags = [];
+	for (const entry of entries) {
+		const chunk = manifest[entry];
+		if (!chunk) throw new Error(`Vite manifest (${manifestPath}) has no entry for "${entry}".`);
+		for (const css of chunk.css ?? []) tags.push(styleTag(`${base}${css}`));
+		tags.push(isCss(entry) ? styleTag(`${base}${chunk.file}`) : scriptTag(`${base}${chunk.file}`));
+	}
+	return tags.join("\n");
+};
+/**
+* Resolve `<script>`/`<link>` tags for one or more Vite entries.
+*
+* In development (when `NODE_ENV` is not `production`, or `hot` is set) it points
+* at the Vite dev server and includes the `@vite/client`. In production it reads
+* the build manifest and emits the hashed asset tags (including any CSS a chunk
+* imports). Backs the `@vite(...)` Edge tag.
+* 
+* @param entries 
+* @param options 
+* @returns 
+*/
+const viteTags = (entries, options = {}) => {
+	const list = (Array.isArray(entries) ? entries : [entries]).filter(Boolean);
+	if (options.hot ?? nodeEnv() !== "prod") return devTags(list, options.devUrl ?? env("VITE_DEV_URL", "http://localhost:5173"));
+	return productionTags(list, options.manifest ?? join(Arkstack.rootDir(), "public", "build", ".vite", "manifest.json"), options.buildDir ?? "/build/");
+};
+/**
+* Register the `@vite(...)` tag (and its backing global) on a view factory so
+* templates can emit Vite asset tags: `@vite('resources/js/app.ts')` or
+* `@vite(['resources/css/app.css', 'resources/js/app.ts'])`.
+* 
+* @param factory 
+*/
+const registerViteTag = (factory) => {
+	factory.edge.global("__arkViteTags", (entries, options) => viteTags(entries, options));
+	factory.tag("vite", false, true, (parser, buffer, token) => {
+		const expression = `__arkViteTags(${token.properties.jsArg})`;
+		const ast = parser.utils.transformAst(parser.utils.generateAST(expression, token.loc, token.filename), token.filename, parser);
+		buffer.outputExpression(parser.utils.stringify(ast), token.filename, token.loc.start.line, false);
+	});
+};
+//#endregion
 //#region src/ViewFactory.ts
 var ViewFactory = class {
 	edge;
@@ -317,7 +377,15 @@ var ViewFactory = class {
 		this.edge = options.edge ?? Edge.create({ cache: options.cache });
 		this.packageViewsPath = options.packageViewsPath ?? "resources/views";
 		this.mount(options.viewsPath ?? resolve(Arkstack.rootDir(), "src", "resources", "views"));
+		registerViteTag(this);
 	}
+	/**
+	* Create a new view instance for the given view name and data.
+	* 
+	* @param name 
+	* @param data 
+	* @returns 
+	*/
 	make(name, data = {}) {
 		const edgeName = this.resolveName(name);
 		return new ViewInstance(name, normalizeViewData({
@@ -326,11 +394,24 @@ var ViewFactory = class {
 			...data
 		}), this.edge, async (view) => await this.runComposers(name, view), (view) => this.runComposersSync(name, view), edgeName);
 	}
+	/**
+	* Render the first view that exists from the given list of names.
+	* 
+	* @param names 
+	* @param data 
+	* @returns 
+	*/
 	first(names, data = {}) {
 		const name = names.find((candidate) => this.exists(candidate));
 		if (!name) throw new Error(`None of the given views exist: ${names.join(", ")}`);
 		return this.make(name, data);
 	}
+	/**
+	* Check if a view exists.
+	* 
+	* @param name 
+	* @returns 
+	*/
 	exists(name) {
 		const edgeName = this.resolveName(name);
 		if (this.edge.loader.templates[edgeName]) return true;
@@ -344,6 +425,15 @@ var ViewFactory = class {
 		mergeData(this.sharedData, data);
 		return this;
 	}
+	/**
+	* Register a view composer for the given view name(s). 
+	* A view composer is a function or object that is called when a view is 
+	* rendered, allowing you to modify the view's data or perform other actions.
+	* 
+	* @param names 
+	* @param composer 
+	* @returns 
+	*/
 	composer(names, composer) {
 		for (const name of Array.isArray(names) ? names : [names]) this.composers.set(name, [...this.composers.get(name) ?? [], composer]);
 		return this;
@@ -356,14 +446,50 @@ var ViewFactory = class {
 		this.edge.mount(diskName, viewsDirectory);
 		return this;
 	}
+	/**
+	* Register a raw template with the given name and contents.
+	* 
+	* @param name 
+	* @param contents 
+	* @returns 
+	*/
 	raw(name, contents) {
 		this.edge.registerTemplate(name, { template: contents });
 		return this;
 	}
+	/**
+	* Register a custom tag with the given name, block type, seekable type, 
+	* and compiler function.
+	* 
+	* @param tagName 
+	* @param block 
+	* @param seekable 
+	* @param compiler 
+	*/
+	tag(tagName, block, seekable, compiler) {
+		const tag = {
+			block,
+			seekable,
+			tagName,
+			compile: compiler
+		};
+		this.edge.registerTag(tag);
+	}
+	/**
+	* Flush all shared data. This will remove all data that has been shared with all views.
+	* 
+	* @returns 
+	*/
 	flushShared() {
 		this.sharedData = {};
 		return this;
 	}
+	/**
+	* Flush all registered composers. This will remove all composers that have 
+	* been registered for any view.
+	* 
+	* @returns 
+	*/
 	flushComposers() {
 		this.composers.clear();
 		return this;
@@ -462,4 +588,4 @@ const clearRouterViewPlugin = definePlugin({
 	}
 });
 //#endregion
-export { collectViewData as a, runWithViewData as c, resolvePackageViewsPath as d, view as f, clearViewData as i, ViewInstance as l, normalizeViewErrors as m, View as n, enterViewData as o, ViewErrorBag as p, ViewFactory as r, getViewData as s, clearRouterViewPlugin as t, parsePackageViewName as u };
+export { viteTags as a, enterViewData as c, ViewInstance as d, parsePackageViewName as f, normalizeViewErrors as g, ViewErrorBag as h, registerViteTag as i, getViewData as l, view as m, View as n, clearViewData as o, resolvePackageViewsPath as p, ViewFactory as r, collectViewData as s, clearRouterViewPlugin as t, runWithViewData as u };

package/dist/setup.d.ts

@@ -1,2 +1,2 @@
-import { t as clearRouterViewPlugin } from "./plugins-D3vyoc8i.js";
+import { t as clearRouterViewPlugin } from "./plugins-Crhr7ifw.js";
 export { clearRouterViewPlugin };

package/dist/setup.js

@@ -1,4 +1,4 @@
-import { t as clearRouterViewPlugin } from "./plugins-BFBs38yL.js";
+import { t as clearRouterViewPlugin } from "./plugins-DWO_aTcP.js";
 import { CoreRouter } from "clear-router/core";
 //#region src/setup.ts
 CoreRouter.use(clearRouterViewPlugin);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/view",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "type": "module",
   "description": "View module for Arkstack, providing template rendering and view integration utilities.",
   "homepage": "https://arkstack.toneflix.net/guide/views",
@@ -33,13 +33,13 @@
   ],
   "dependencies": {
     "edge.js": "^6.5.0",
-    "@arkstack/contract": "^0.15.2"
+    "@arkstack/contract": "^0.15.4"
   },
   "peerDependencies": {
     "@h3ravel/musket": "^2.2.1",
     "clear-router": "^2.9.0",
-    "@arkstack/foundry": "^0.15.2",
-    "@arkstack/common": "^0.15.2"
+    "@arkstack/common": "^0.15.4",
+    "@arkstack/foundry": "^0.15.4"
   },
   "peerDependenciesMeta": {
     "@h3ravel/musket": {

package/dist/plugins-D3vyoc8i.d.ts

@@ -1,6 +0,0 @@
-import * as _$clear_router_core0 from "clear-router/core";
-
-//#region src/plugins.d.ts
-declare const clearRouterViewPlugin: _$clear_router_core0.ClearRouterPlugin<any, any>;
-//#endregion
-export { clearRouterViewPlugin as t };