snice 2.3.0 → 2.5.0

package/dist/symbols.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v2.2.3
+ * snice v2.4.0
  * Imperative TypeScript framework for building vanilla web components with decorators, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.
@@ -37,6 +37,7 @@ const CHANNEL_HANDLERS = getSymbol('channel-handlers');
 const READY_PROMISE = getSymbol('ready-promise');
 const READY_RESOLVE = getSymbol('ready-resolve');
 const CONTROLLER = getSymbol('controller');
+const INITIALIZED = getSymbol('initialized');
 // Event handler symbols
 const ON_HANDLERS = getSymbol('on-handlers');
 // Controller symbols
@@ -62,13 +63,18 @@ const CREATED_AT = getSymbol('created-at');
 // Lifecycle symbols
 const READY_HANDLERS = getSymbol('ready-handlers');
 const DISPOSE_HANDLERS = getSymbol('dispose-handlers');
+const MOVED_HANDLERS = getSymbol('moved-handlers');
+const ADOPTED_HANDLERS = getSymbol('adopted-handlers');
 // Observer symbols
 const OBSERVERS = getSymbol('observers');
 // Part symbols
 const PARTS = getSymbol('parts');
 const PART_TIMERS = getSymbol('part-timers');
+// Lifecycle callback timers
+const MOVED_TIMERS = getSymbol('moved-timers');
+const ADOPTED_TIMERS = getSymbol('adopted-timers');
 // Dispatch timing symbols
 const DISPATCH_TIMERS = getSymbol('dispatch-timers');
 
-export { CHANNEL_HANDLERS, CLEANUP, CONTEXT_REQUEST_HANDLER, CONTROLLER, CONTROLLER_ID, CONTROLLER_KEY, CONTROLLER_NAME_KEY, CONTROLLER_OPERATIONS, CREATED_AT, CURRENT_PAGE_MARKER, DISPATCH_TIMERS, DISPOSE_HANDLERS, EXPLICITLY_SET_PROPERTIES, IS_CONTROLLER_CLASS, IS_CONTROLLER_INSTANCE, IS_ELEMENT_CLASS, NATIVE_CONTROLLER, OBSERVERS, ON_HANDLERS, PAGE_TRANSITION, PARTS, PART_TIMERS, PROPERTIES, PROPERTIES_INITIALIZED, PROPERTY_VALUES, PROPERTY_WATCHERS, READY_HANDLERS, READY_PROMISE, READY_RESOLVE, ROUTER_CONTEXT, getSymbol };
+export { ADOPTED_HANDLERS, ADOPTED_TIMERS, CHANNEL_HANDLERS, CLEANUP, CONTEXT_REQUEST_HANDLER, CONTROLLER, CONTROLLER_ID, CONTROLLER_KEY, CONTROLLER_NAME_KEY, CONTROLLER_OPERATIONS, CREATED_AT, CURRENT_PAGE_MARKER, DISPATCH_TIMERS, DISPOSE_HANDLERS, EXPLICITLY_SET_PROPERTIES, INITIALIZED, IS_CONTROLLER_CLASS, IS_CONTROLLER_INSTANCE, IS_ELEMENT_CLASS, MOVED_HANDLERS, MOVED_TIMERS, NATIVE_CONTROLLER, OBSERVERS, ON_HANDLERS, PAGE_TRANSITION, PARTS, PART_TIMERS, PROPERTIES, PROPERTIES_INITIALIZED, PROPERTY_VALUES, PROPERTY_WATCHERS, READY_HANDLERS, READY_PROMISE, READY_RESOLVE, ROUTER_CONTEXT, getSymbol };
 //# sourceMappingURL=symbols.esm.js.map

package/dist/symbols.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"symbols.esm.js","sources":["../src/global.ts","../src/symbols.ts"],"sourcesContent":[null,null],"names":[],"mappings":";;;;;;AAAA;AACA;AAKA;AACA,SAAS,mBAAmB,GAAA;AAC1B,IAAA,IAAI,CAAE,UAAkB,CAAC,KAAK,EAAE;QAC7B,UAAkB,CAAC,KAAK,GAAG;YAC1B,kBAAkB,EAAE,IAAI,GAAG,EAAE;AAC7B,YAAA,mBAAmB,EAAE,CAAC;YACtB,OAAO,EAAE,IAAI,GAAG;SACjB;IACH;IACA,OAAQ,UAAkB,CAAC,KAAK;AAClC;AAEA;AACO,MAAM,KAAK,GAAG,mBAAmB,EAAE;AAE1C;AACM,SAAU,SAAS,CAAC,IAAY,EAAA;IACpC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;AAC5B,QAAA,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IACvC;IACA,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAE;AACjC;;AC3BA;AACA;MAMa,mBAAmB,GAAG,SAAS,CAAC,qBAAqB;MACrD,sBAAsB,GAAG,SAAS,CAAC,wBAAwB;MAC3D,gBAAgB,GAAG,SAAS,CAAC,kBAAkB;MAC/C,gBAAgB,GAAG,SAAS,CAAC,kBAAkB;AAE5D;MACa,aAAa,GAAG,SAAS,CAAC,eAAe;MACzC,aAAa,GAAG,SAAS,CAAC,eAAe;MACzC,UAAU,GAAG,SAAS,CAAC,YAAY;AAEhD;MACa,WAAW,GAAG,SAAS,CAAC,aAAa;AAElD;MACa,cAAc,GAAG,SAAS,CAAC,gBAAgB;MAC3C,mBAAmB,GAAG,SAAS,CAAC,iBAAiB;MACjD,aAAa,GAAG,SAAS,CAAC,eAAe;MACzC,qBAAqB,GAAG,SAAS,CAAC,uBAAuB;MACzD,iBAAiB,GAAG,SAAS,CAAC,mBAAmB;AAE9D;MACa,OAAO,GAAG,SAAS,CAAC,SAAS;AAE1C;MACa,UAAU,GAAG,SAAS,CAAC,YAAY;MACnC,eAAe,GAAG,SAAS,CAAC,iBAAiB;MAC7C,sBAAsB,GAAG,SAAS,CAAC,wBAAwB;MAC3D,iBAAiB,GAAG,SAAS,CAAC,mBAAmB;MACjD,yBAAyB,GAAG,SAAS,CAAC,2BAA2B;AAE9E;MACa,cAAc,GAAG,SAAS,CAAC,gBAAgB;MAC3C,mBAAmB,GAAG,SAAS,CAAC,qBAAqB;MACrD,uBAAuB,GAAG,SAAS,CAAC,yBAAyB;MAC7D,eAAe,GAAG,SAAS,CAAC,iBAAiB;MAC7C,UAAU,GAAG,SAAS,CAAC,YAAY;AAEhD;MACa,cAAc,GAAG,SAAS,CAAC,gBAAgB;MAC3C,gBAAgB,GAAG,SAAS,CAAC,kBAAkB;AAE5D;MACa,SAAS,GAAG,SAAS,CAAC,WAAW;AAE9C;MACa,KAAK,GAAG,SAAS,CAAC,OAAO;MACzB,WAAW,GAAG,SAAS,CAAC,aAAa;AAElD;MACa,eAAe,GAAG,SAAS,CAAC,iBAAiB;;;;"}
+{"version":3,"file":"symbols.esm.js","sources":["../src/global.ts","../src/symbols.ts"],"sourcesContent":[null,null],"names":[],"mappings":";;;;;;AAAA;AACA;AAKA;AACA,SAAS,mBAAmB,GAAA;AAC1B,IAAA,IAAI,CAAE,UAAkB,CAAC,KAAK,EAAE;QAC7B,UAAkB,CAAC,KAAK,GAAG;YAC1B,kBAAkB,EAAE,IAAI,GAAG,EAAE;AAC7B,YAAA,mBAAmB,EAAE,CAAC;YACtB,OAAO,EAAE,IAAI,GAAG;SACjB;IACH;IACA,OAAQ,UAAkB,CAAC,KAAK;AAClC;AAEA;AACO,MAAM,KAAK,GAAG,mBAAmB,EAAE;AAE1C;AACM,SAAU,SAAS,CAAC,IAAY,EAAA;IACpC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;AAC5B,QAAA,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IACvC;IACA,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAE;AACjC;;AC3BA;AACA;MAMa,mBAAmB,GAAG,SAAS,CAAC,qBAAqB;MACrD,sBAAsB,GAAG,SAAS,CAAC,wBAAwB;MAC3D,gBAAgB,GAAG,SAAS,CAAC,kBAAkB;MAC/C,gBAAgB,GAAG,SAAS,CAAC,kBAAkB;AAE5D;MACa,aAAa,GAAG,SAAS,CAAC,eAAe;MACzC,aAAa,GAAG,SAAS,CAAC,eAAe;MACzC,UAAU,GAAG,SAAS,CAAC,YAAY;MACnC,WAAW,GAAG,SAAS,CAAC,aAAa;AAElD;MACa,WAAW,GAAG,SAAS,CAAC,aAAa;AAElD;MACa,cAAc,GAAG,SAAS,CAAC,gBAAgB;MAC3C,mBAAmB,GAAG,SAAS,CAAC,iBAAiB;MACjD,aAAa,GAAG,SAAS,CAAC,eAAe;MACzC,qBAAqB,GAAG,SAAS,CAAC,uBAAuB;MACzD,iBAAiB,GAAG,SAAS,CAAC,mBAAmB;AAE9D;MACa,OAAO,GAAG,SAAS,CAAC,SAAS;AAE1C;MACa,UAAU,GAAG,SAAS,CAAC,YAAY;MACnC,eAAe,GAAG,SAAS,CAAC,iBAAiB;MAC7C,sBAAsB,GAAG,SAAS,CAAC,wBAAwB;MAC3D,iBAAiB,GAAG,SAAS,CAAC,mBAAmB;MACjD,yBAAyB,GAAG,SAAS,CAAC,2BAA2B;AAE9E;MACa,cAAc,GAAG,SAAS,CAAC,gBAAgB;MAC3C,mBAAmB,GAAG,SAAS,CAAC,qBAAqB;MACrD,uBAAuB,GAAG,SAAS,CAAC,yBAAyB;MAC7D,eAAe,GAAG,SAAS,CAAC,iBAAiB;MAC7C,UAAU,GAAG,SAAS,CAAC,YAAY;AAEhD;MACa,cAAc,GAAG,SAAS,CAAC,gBAAgB;MAC3C,gBAAgB,GAAG,SAAS,CAAC,kBAAkB;MAC/C,cAAc,GAAG,SAAS,CAAC,gBAAgB;MAC3C,gBAAgB,GAAG,SAAS,CAAC,kBAAkB;AAE5D;MACa,SAAS,GAAG,SAAS,CAAC,WAAW;AAE9C;MACa,KAAK,GAAG,SAAS,CAAC,OAAO;MACzB,WAAW,GAAG,SAAS,CAAC,aAAa;AAElD;MACa,YAAY,GAAG,SAAS,CAAC,cAAc;MACvC,cAAc,GAAG,SAAS,CAAC,gBAAgB;AAExD;MACa,eAAe,GAAG,SAAS,CAAC,iBAAiB;;;;"}

package/dist/transitions.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v2.2.3
+ * snice v2.4.0
  * Imperative TypeScript framework for building vanilla web components with decorators, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/types/controller.d.ts

@@ -1,4 +1,4 @@
-import { IController, ControllerClass } from './types/IController';
+import { IController, ControllerClass } from './types/i-controller';
 declare class ControllerScope {
     private cleanupFns;
     private pendingOperations;

package/dist/types/element.d.ts

@@ -1,6 +1,63 @@
-import { QueryOptions } from './types/QueryOptions';
-import { PropertyOptions } from './types/PropertyOptions';
-import { PartOptions } from './types/PartOptions';
+import { QueryOptions } from './types/query-options';
+import { PropertyOptions } from './types/property-options';
+import { PartOptions } from './types/part-options';
+import { MovedOptions } from './types/moved-options';
+import { AdoptedOptions } from './types/adopted-options';
+import { AppContext } from './types/app-context';
+import { Placard } from './types/placard';
+import { RouteParams } from './types/route-params';
+/**
+ * Interface that layout components must implement to receive updates
+ * from the router about application state and navigation changes.
+ *
+ * The framework will call the update method:
+ * - When the layout is first created/connected
+ * - When route changes occur during navigation
+ *
+ * Placards are collected at route creation and refreshed before each navigation,
+ * ensuring layouts always receive current page metadata.
+ *
+ * @example
+ * ```typescript
+ * @layout('app-shell')
+ * class AppShell extends HTMLElement implements Layout {
+ *   update(appContext: AppContext, placards: Placard[], currentRoute: string, routeParams: RouteParams) {
+ *     // Update navigation, breadcrumbs, user info, etc.
+ *     this.renderNavigation(placards, currentRoute);
+ *     this.updateUserInfo(appContext.principal);
+ *     this.applyTheme(appContext.theme);
+ *   }
+ * }
+ * ```
+ */
+export interface Layout {
+    /**
+     * Called by the framework to update the layout with current application state.
+     *
+     * @param appContext - Application-wide context (theme, auth, config, etc.)
+     * @param placards - All page metadata for navigation and breadcrumbs
+     * @param currentRoute - The currently active route path
+     * @param routeParams - Parameters extracted from the current route
+     *
+     * @example
+     * ```typescript
+     * update(appContext, placards, currentRoute, routeParams) {
+     *   // Filter placards for main navigation
+     *   const navItems = placards.filter(p => p.show !== false && !p.parent);
+     *
+     *   // Build breadcrumbs for current page
+     *   const currentPlacard = placards.find(p => matchesRoute(p, currentRoute));
+     *   const breadcrumbs = this.buildBreadcrumbs(currentPlacard, placards);
+     *
+     *   // Update UI
+     *   this.renderNavigation(navItems, currentRoute);
+     *   this.renderBreadcrumbs(breadcrumbs);
+     *   this.updateUserDisplay(appContext.principal);
+     * }
+     * ```
+     */
+    update(appContext: AppContext, placards: Placard[], currentRoute: string, routeParams: RouteParams): void;
+}
 /**
  * Applies core element functionality to a constructor
  * This is shared between @element and @page decorators
@@ -28,6 +85,16 @@ export declare function ready(): (target: any, context: ClassMethodDecoratorCont
  * Used for cleanup tasks when element is removed from DOM
  */
 export declare function dispose(): (target: any, context: ClassMethodDecoratorContext) => void;
+/**
+ * Decorator for methods that should run when element is moved within DOM
+ * Supports debounce and throttle options to control execution timing
+ */
+export declare function moved(options?: MovedOptions): (originalMethod: any, context: ClassMethodDecoratorContext) => (this: HTMLElement, ...args: any[]) => any;
+/**
+ * Decorator for methods that should run when element is adopted to new document
+ * Supports debounce and throttle options to control execution timing
+ */
+export declare function adopted(options?: AdoptedOptions): (originalMethod: any, context: ClassMethodDecoratorContext) => (this: HTMLElement, ...args: any[]) => any;
 /**
  * Decorator for methods that render specific parts of the template
  * Parts are identified by the 'part' attribute in the HTML template

package/dist/types/events.d.ts

@@ -1,5 +1,5 @@
-import { OnOptions } from './types/OnOptions';
-import { DispatchOptions } from './types/DispatchOptions';
+import { OnOptions } from './types/on-options';
+import { DispatchOptions } from './types/dispatch-options';
 export declare function on(eventName: string | string[], selectorOrOptions?: string | OnOptions, options?: OnOptions): (target: any, context: ClassMethodDecoratorContext) => void;
 export declare function setupEventHandlers(instance: any, element: HTMLElement): void;
 export declare function cleanupEventHandlers(instance: any): void;

package/dist/types/global.d.ts

@@ -1,3 +1,3 @@
-import { SniceGlobal } from './types/SniceGlobal';
+import { SniceGlobal } from './types/snice-global';
 export declare const snice: SniceGlobal;
 export declare function getSymbol(name: string): symbol;

package/dist/types/index.d.ts

@@ -1,6 +1,7 @@
-export { element, layout, property, query, queryAll, watch, context, applyElementFunctionality, ready, dispose, part } from './element';
+export { element, layout, property, query, queryAll, watch, context, applyElementFunctionality, ready, dispose, moved, adopted, part } from './element';
+export type { Layout } from './element';
 export { Router } from './router';
-export { controller, attachController, detachController, getController, useNativeElementControllers, cleanupNativeElementControllers } from './controller';
+export { controller, useNativeElementControllers } from './controller';
 export { on, dispatch } from './events';
 export { observe } from './observe';
 export { request, respond } from './request-response';

package/dist/types/observe.d.ts

@@ -1,4 +1,4 @@
-import { ObserveOptions } from './types/ObserveOptions';
+import { ObserveOptions } from './types/observe-options';
 /**
  * Decorator for observing external changes like viewport intersection, resize, media queries, and DOM mutations
  *

package/dist/types/request-response.d.ts

@@ -1,5 +1,5 @@
-import { RequestOptions } from './types/RequestOptions';
-import { RespondOptions } from './types/RespondOptions';
+import { RequestOptions } from './types/request-options';
+import { RespondOptions } from './types/respond-options';
 /**
  * Decorator for making requests from elements or controllers.
  * Uses async generator pattern for bidirectional communication.

package/dist/types/router.d.ts

@@ -1,5 +1,5 @@
-import { RouterOptions } from './types/RouterOptions';
-import { RouterInstance } from './types/RouterInstance';
+import { RouterOptions } from './types/router-options';
+import { RouterInstance } from './types/router-instance';
 /**
  * Creates a new router instance.
  * @param {RouterOptions} options - The router configuration options.

package/dist/types/symbols.d.ts

@@ -7,6 +7,7 @@ export declare const CHANNEL_HANDLERS: symbol;
 export declare const READY_PROMISE: symbol;
 export declare const READY_RESOLVE: symbol;
 export declare const CONTROLLER: symbol;
+export declare const INITIALIZED: symbol;
 export declare const ON_HANDLERS: symbol;
 export declare const CONTROLLER_KEY: symbol;
 export declare const CONTROLLER_NAME_KEY: symbol;
@@ -26,7 +27,11 @@ export declare const PAGE_TRANSITION: symbol;
 export declare const CREATED_AT: symbol;
 export declare const READY_HANDLERS: symbol;
 export declare const DISPOSE_HANDLERS: symbol;
+export declare const MOVED_HANDLERS: symbol;
+export declare const ADOPTED_HANDLERS: symbol;
 export declare const OBSERVERS: symbol;
 export declare const PARTS: symbol;
 export declare const PART_TIMERS: symbol;
+export declare const MOVED_TIMERS: symbol;
+export declare const ADOPTED_TIMERS: symbol;
 export declare const DISPATCH_TIMERS: symbol;

package/dist/types/testing.d.ts

@@ -1,4 +1,4 @@
 export * from './index';
-export { registerControllerCleanup, getControllerScope, attachController as attachControllerInternal, detachController as detachControllerInternal } from './controller';
+export { registerControllerCleanup, getControllerScope, attachController, detachController, getController, cleanupNativeElementControllers } from './controller';
 export { CONTROLLER_KEY, CONTROLLER_OPERATIONS, CONTROLLER_NAME_KEY, CONTROLLER_ID, PROPERTIES_INITIALIZED, PROPERTY_VALUES, PROPERTY_WATCHERS, EXPLICITLY_SET_PROPERTIES, READY_PROMISE, READY_RESOLVE, READY_HANDLERS, DISPOSE_HANDLERS, PARTS, PART_TIMERS, ROUTER_CONTEXT, CONTEXT_REQUEST_HANDLER, PAGE_TRANSITION, CREATED_AT, IS_ELEMENT_CLASS, IS_CONTROLLER_CLASS, IS_CONTROLLER_INSTANCE, NATIVE_CONTROLLER, CLEANUP, ON_HANDLERS, DISPATCH_TIMERS, CHANNEL_HANDLERS, OBSERVERS } from './symbols';
 export { parseAttributeValue, detectType } from './utils';

package/dist/types/transitions.d.ts

@@ -1,7 +1,7 @@
 /**
  * Generic transition system for animating between elements
  */
-import { Transition } from './types/Transition';
+import { Transition } from './types/transition';
 export type { Transition };
 /**
  * Perform a transition between two elements

package/dist/types/types/adopted-options.d.ts

@@ -0,0 +1,4 @@
+export interface AdoptedOptions {
+    throttle?: number;
+    debounce?: number;
+}

package/dist/types/types/app-context.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Application context interface for cross-cutting concerns.
+ *
+ * This interface defines common application-wide state and services
+ * that components, pages, and guards may need to access. All properties
+ * are optional, allowing applications to implement only what they need.
+ *
+ * Applications can extend this interface to add their own context properties:
+ *
+ * @example
+ * ```typescript
+ * interface MyAppContext extends AppContext {
+ *   theme: MyThemeService;
+ *   analytics: AnalyticsService;
+ *   customProperty: string;
+ * }
+ * ```
+ *
+ * The context is typically passed to:
+ * - Route guards for access control decisions
+ * - Page components via the @context decorator
+ * - Placard functions for dynamic metadata
+ */
+export interface AppContext {
+    /**
+     * Theme management and styling context.
+     * Typically handles dark/light mode, custom themes, and design tokens.
+     *
+     * @example
+     * ```typescript
+     * theme: {
+     *   current: 'dark',
+     *   setTheme: (theme: string) => void,
+     *   isDarkMode: () => boolean
+     * }
+     * ```
+     */
+    theme?: any;
+    /**
+     * Internationalization and localization context.
+     * Handles language switching, translations, and regional formatting.
+     *
+     * @example
+     * ```typescript
+     * locale: {
+     *   current: 'en-US',
+     *   setLocale: (locale: string) => void,
+     *   t: (key: string) => string
+     * }
+     * ```
+     */
+    locale?: any;
+    /**
+     * Authentication and authorization context.
+     * Contains user information, roles, permissions, and auth state.
+     *
+     * @example
+     * ```typescript
+     * principal: {
+     *   user: { id: 1, name: 'John', role: 'admin' },
+     *   isAuthenticated: () => boolean,
+     *   hasRole: (role: string) => boolean
+     * }
+     * ```
+     */
+    principal?: any;
+    /**
+     * Application configuration and settings.
+     * Runtime configuration, feature flags, API endpoints, etc.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   apiUrl: 'https://api.example.com',
+     *   featureFlags: { newUI: true },
+     *   get: (key: string) => any
+     * }
+     * ```
+     */
+    config?: any;
+}

package/dist/types/types/guard.d.ts

@@ -0,0 +1,19 @@
+import { RouteParams } from './route-params';
+/**
+ * Guard function type for route protection and visibility control.
+ * Guards determine if navigation to a route should proceed or if a page should be visible.
+ *
+ * @template T - The context type passed to the guard function
+ * @param context - The application context object
+ * @param params - Route parameters extracted from the URL
+ * @returns boolean - true to allow access, false to deny
+ *
+ * @example
+ * ```typescript
+ * const isAuthenticated: Guard<AppContext> = (ctx, params) => ctx.getUser() !== null;
+ * const canEditUser: Guard<AppContext> = (ctx, params) => {
+ *   return ctx.hasPermission('users.edit', params.id);
+ * };
+ * ```
+ */
+export type Guard<T = any> = (context: T, params: RouteParams) => boolean;

package/dist/types/types/index.d.ts

@@ -1,17 +1,23 @@
-export * from './QueryOptions';
-export * from './PropertyOptions';
-export * from './PropertyConverter';
-export * from './SniceElement';
-export * from './PartOptions';
-export * from './SimpleArray';
-export * from './RouterOptions';
-export * from './PageOptions';
-export * from './RouterInstance';
-export * from './OnOptions';
-export * from './DispatchOptions';
-export * from './IController';
-export * from './Transition';
-export * from './ObserveOptions';
-export * from './RequestOptions';
-export * from './RespondOptions';
-export * from './SniceGlobal';
+export * from './query-options';
+export * from './property-options';
+export * from './property-converter';
+export * from './snice-element';
+export * from './part-options';
+export * from './moved-options';
+export * from './adopted-options';
+export * from './simple-array';
+export * from './router-options';
+export * from './page-options';
+export * from './router-instance';
+export * from './on-options';
+export * from './dispatch-options';
+export * from './i-controller';
+export * from './transition';
+export * from './observe-options';
+export * from './request-options';
+export * from './respond-options';
+export * from './snice-global';
+export * from './placard';
+export * from './guard';
+export * from './route-params';
+export * from './app-context';

package/dist/types/types/moved-options.d.ts

@@ -0,0 +1,4 @@
+export interface MovedOptions {
+    throttle?: number;
+    debounce?: number;
+}

package/dist/types/types/{PageOptions.d.ts → page-options.d.ts}

@@ -1,6 +1,7 @@
-import { Transition } from './Transition';
-export type RouteParams = Record<string, string>;
-export type Guard<T = any> = (context: T, params: RouteParams) => boolean | Promise<boolean>;
+import { Transition } from './transition';
+import { Placard } from './placard';
+import { Guard } from './guard';
+import { AppContext } from './app-context';
 export interface PageOptions {
     /**
      * The tag name of the custom element.
@@ -21,10 +22,18 @@ export interface PageOptions {
      * Guard functions that must pass for navigation to proceed.
      * Can be a single guard or an array of guards (all must pass).
      */
-    guards?: Guard<any> | Guard<any>[];
+    guards?: Guard<AppContext> | Guard<AppContext>[];
     /**
      * Layout element tag name for this page.
      * Use false to explicitly disable layout for this page.
      */
     layout?: string | false;
+    /**
+     * Page metadata that layouts can consume for navigation,
+     * breadcrumbs, help information, and other UI elements.
+     * Can be a static placard object or a function that returns one.
+     * @example placard: { name: 'dashboard', title: 'Dashboard' }
+     * @example placard: (ctx) => ({ name: 'user-edit', title: `Edit ${ctx.getCurrentUser().name}` })
+     */
+    placard?: Placard | ((context: AppContext) => Placard);
 }

package/dist/types/types/placard.d.ts

@@ -0,0 +1,90 @@
+import { Guard } from './guard';
+/**
+ * Placard interface for page metadata that layouts can consume.
+ * Provides rich metadata about pages including navigation structure,
+ * help information, and dynamic visibility controls.
+ */
+export interface Placard<T = any> {
+    /**
+     * Unique identifier for this placard.
+     * Used for referencing in breadcrumbs and parent-child relationships.
+     * Should be kebab-case, e.g., 'user-settings', 'admin-dashboard'
+     */
+    name: string;
+    /**
+     * Display name shown in navigation and breadcrumbs.
+     * Should be concise and descriptive.
+     */
+    title: string;
+    /**
+     * Longer description of the page's purpose.
+     * Used in tooltips, search results, or help text.
+     */
+    description?: string;
+    /**
+     * Visual icon representing the page.
+     * Can be emoji, icon font class, or SVG path.
+     */
+    icon?: string;
+    /**
+     * Brief help text shown on hover.
+     * Explains what the page does or when to use it.
+     */
+    tooltip?: string;
+    /**
+     * Additional keywords for search functionality.
+     * Helps users discover pages through alternate terms.
+     * @example ['settings', 'preferences', 'config', 'options']
+     */
+    searchTerms?: string[];
+    /**
+     * Keyboard shortcuts to navigate to this page.
+     * Uses standard key notation.
+     * @example ['ctrl+d', 'cmd+d', 'alt+shift+d']
+     */
+    hotkeys?: string[];
+    /**
+     * Link to detailed documentation or help for this page.
+     */
+    helpUrl?: string;
+    /**
+     * Explicitly defined breadcrumb path using placard names.
+     * If not provided, breadcrumbs are auto-resolved using parent hierarchy.
+     * @example ['dashboard', 'settings', 'advanced-settings']
+     */
+    breadcrumbs?: string[];
+    /**
+     * Logical grouping for navigation organization.
+     * Pages with the same group are displayed together.
+     * @example 'admin', 'reports', 'settings'
+     */
+    group?: string;
+    /**
+     * References another placard's name to create hierarchy.
+     * Used for nested navigation and breadcrumb construction.
+     * @example 'users' // Child of the 'users' page
+     */
+    parent?: string;
+    /**
+     * Numeric sort order within the group or parent.
+     * Lower numbers appear first.
+     */
+    order?: number;
+    /**
+     * Whether to display this page in navigation menus.
+     * Defaults to true if not specified.
+     */
+    show?: boolean;
+    /**
+     * Guard functions that determine if the page should appear in navigation.
+     * Reuses the same guard system as route protection.
+     * @example [isAuthenticated, hasAdminRole]
+     */
+    visibleOn?: Guard<T> | Guard<T>[];
+    /**
+     * Arbitrary metadata for custom layout needs.
+     * Domain-specific or framework-specific data.
+     * @example { category: 'reporting', experimental: true, requiredFeatures: ['analytics'] }
+     */
+    attributes?: Record<string, any>;
+}

package/dist/types/types/{PropertyOptions.d.ts → property-options.d.ts}

@@ -1,5 +1,5 @@
-import { SimpleArray } from './SimpleArray';
-import { PropertyConverter } from './PropertyConverter';
+import { SimpleArray } from './simple-array';
+import { PropertyConverter } from './property-converter';
 export interface PropertyOptions {
     type?: StringConstructor | NumberConstructor | BooleanConstructor | ArrayConstructor | ObjectConstructor | DateConstructor | BigIntConstructor | typeof SimpleArray;
     attribute?: string | boolean;

package/dist/types/types/route-params.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Route parameters extracted from URL patterns.
+ * Represents dynamic segments in routes as key-value pairs.
+ *
+ * @example
+ * ```typescript
+ * // For route '/users/:userId/posts/:postId'
+ * // and URL '/users/123/posts/456'
+ * const params: RouteParams = {
+ *   userId: '123',
+ *   postId: '456'
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // For non-parameterized routes like '/dashboard'
+ * const params: RouteParams = {}; // Empty object
+ * ```
+ */
+export type RouteParams = Record<string, string>;

package/dist/types/types/{RouterInstance.d.ts → router-instance.d.ts}

@@ -1,10 +1,12 @@
-import { PageOptions, Guard } from './PageOptions';
-import { Transition } from './Transition';
+import { PageOptions } from './page-options';
+import { Guard } from './guard';
+import { Transition } from './transition';
+import { AppContext } from './app-context';
 export interface RouterInstance {
     page: (pageOptions: PageOptions) => <C extends {
         new (...args: any[]): HTMLElement;
     }>(constructor: C, context: ClassDecoratorContext) => C;
     initialize: () => void;
     navigate: (path: string) => Promise<void>;
-    register: (route: string, tag: string, transition?: Transition, guards?: Guard<any> | Guard<any>[]) => void;
+    register: (route: string, tag: string, transition?: Transition, guards?: Guard<AppContext> | Guard<AppContext>[]) => void;
 }

package/dist/types/types/{RouterOptions.d.ts → router-options.d.ts}

@@ -1,4 +1,4 @@
-import { Transition } from './Transition';
+import { Transition } from './transition';
 export interface RouterOptions {
     /**
      * The target element selector where the page element will be instantiated.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snice",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "type": "module",
   "description": "Imperative TypeScript framework for building vanilla web components with decorators, routing, and controllers. No virtual DOM, no build complexity.",
   "main": "dist/index.cjs",
@@ -80,11 +80,11 @@
     "build:types": "tsc --project components/tsconfig.json --emitDeclarationOnly",
     "build:test": "rollup -c rollup.config.test.js",
     "preview": "vite preview",
-    "test": "vitest run",
+    "test": "npm run build:test && vitest run",
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest --coverage",
-    "test:src": "vitest run",
+    "test:src": "npm run build:test && vitest run",
     "test:built": "npm run build:test && TEST_BUILT=true vitest run",
     "test:all": "npm run test:src && npm run test:built",
     "prerelease": "npm run build",