@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/view-composers.d.ts

@@ -0,0 +1,171 @@
+/**
+ * View Composers Module
+ *
+ * Similar to Laravel's View Composers, this module allows registering callbacks
+ * that automatically run whenever a specific view (or views matching a pattern)
+ * is rendered. Use this to inject data into templates without manually passing
+ * it every time.
+ *
+ * ## Use Cases
+ *
+ * - Inject user data into all views
+ * - Add navigation data to layout templates
+ * - Load settings for specific page types
+ * - Populate dropdown options across forms
+ *
+ * ## Registration Methods
+ *
+ * ### Exact Match
+ * ```typescript
+ * import { composer } from 'stx'
+ *
+ * // Match by exact view name
+ * composer('dashboard', async (context) => {
+ *   context.stats = await fetchDashboardStats()
+ * })
+ *
+ * // Match by full file path
+ * composer('/views/admin/users.stx', (context) => {
+ *   context.roles = ['admin', 'editor', 'viewer']
+ * })
+ * ```
+ *
+ * ### Pattern Match
+ * ```typescript
+ * import { composerPattern } from 'stx'
+ *
+ * // Match all admin views
+ * composerPattern(/^admin/, (context) => {
+ *   context.isAdmin = true
+ * })
+ *
+ * // Match with string pattern (converted to RegExp)
+ * composerPattern('.*\\.settings\\.', (context) => {
+ *   context.settingsMenu = loadSettingsMenu()
+ * })
+ * ```
+ *
+ * ## Execution Order
+ *
+ * 1. Exact match composers (by full file path)
+ * 2. Exact match composers (by view name only)
+ * 3. Pattern match composers (in registration order)
+ *
+ * All composers for a matching view run in sequence.
+ * Async composers are awaited before the next runs.
+ *
+ * ## Important Notes
+ *
+ * - Composers modify the context object directly (no return value needed)
+ * - Composers are global and persist for the application lifetime
+ * - Use `clearComposers()` to reset in tests
+ *
+ * @module view-composers
+ */
+/**
+ * Callback function type for view composers.
+ *
+ * @param context - The template context object (modify this directly)
+ * @param filePath - Full path to the template file being rendered
+ * @returns void or a Promise that resolves to void
+ *
+ * @example
+ * ```typescript
+ * const myComposer: ViewComposerCallback = async (context, filePath) => {
+ *   context.user = await getCurrentUser()
+ *   context.viewPath = filePath
+ * }
+ * ```
+ */
+export type ViewComposerCallback = (context: Record<string, any>, filePath: string) => void | Promise<void>;
+/**
+ * Register a composer for a specific view.
+ *
+ * The view can be either the full file path or just the view name (filename without extension).
+ * Both will be checked when determining which composers to run.
+ *
+ * @param view - The view name or full file path to match
+ * @param callback - Function to execute when the view is rendered
+ *
+ * @example
+ * ```typescript
+ * // Match by view name
+ * composer('profile', (context) => {
+ *   context.tabs = ['overview', 'settings', 'security']
+ * })
+ *
+ * // Match by full path
+ * composer('/app/views/users/edit.stx', async (context) => {
+ *   context.timezones = await loadTimezones()
+ * })
+ * ```
+ */
+export declare function composer(view: string, callback: ViewComposerCallback): void;
+/**
+ * Register a composer for all views matching a pattern.
+ *
+ * The pattern is tested against both the full file path and the view name.
+ * If either matches, the composer will run.
+ *
+ * @param pattern - A RegExp or string pattern (strings are converted to RegExp)
+ * @param callback - Function to execute when a matching view is rendered
+ *
+ * @example
+ * ```typescript
+ * // Match all admin views using RegExp
+ * composerPattern(/^admin/, (context) => {
+ *   context.adminNav = loadAdminNavigation()
+ * })
+ *
+ * // Match views containing 'settings' using string pattern
+ * composerPattern('settings', (context) => {
+ *   context.settingsVersion = '2.0'
+ * })
+ *
+ * // Match views ending with '-form'
+ * composerPattern(/-form$/, (context) => {
+ *   context.csrfToken = generateCsrfToken()
+ * })
+ * ```
+ */
+export declare function composerPattern(pattern: string | RegExp, callback: ViewComposerCallback): void;
+/**
+ * Execute all composers for a given view.
+ *
+ * This function is called automatically during template processing.
+ * You typically don't need to call this directly.
+ *
+ * Execution order:
+ * 1. Exact match by full file path
+ * 2. Exact match by view name (filename without extension)
+ * 3. Pattern matches (in registration order)
+ *
+ * @param filePath - Full path to the template file being rendered
+ * @param context - The template context object to be modified by composers
+ *
+ * @internal
+ */
+export declare function runComposers(filePath: string, context: Record<string, any>): Promise<void>;
+/**
+ * Clear all registered composers.
+ *
+ * Removes all exact match and pattern match composers.
+ * Primarily used for testing to reset state between tests.
+ *
+ * @example
+ * ```typescript
+ * import { clearComposers, composer } from 'stx'
+ *
+ * describe('MyComponent', () => {
+ *   beforeEach(() => {
+ *     clearComposers() // Reset before each test
+ *   })
+ *
+ *   it('should inject user data', () => {
+ *     composer('profile', (ctx) => { ctx.user = mockUser })
+ *     // ... test
+ *   })
+ * })
+ * ```
+ */
+export declare function clearComposers(): void;

package/dist/view-composers.js

@@ -0,0 +1,29 @@
+const composers = {
+  patterns: [],
+  exact: {}
+};
+export function composer(view, callback) {
+  if (!composers.exact[view])
+    composers.exact[view] = [];
+  composers.exact[view].push(callback);
+}
+export function composerPattern(pattern, callback) {
+  const regex = typeof pattern === "string" ? new RegExp(pattern) : pattern;
+  composers.patterns.push({ pattern: regex, callback });
+}
+export async function runComposers(filePath, context) {
+  const viewName = filePath.split("/").pop()?.split(".")[0] || "";
+  if (composers.exact[filePath])
+    for (const callback of composers.exact[filePath])
+      await Promise.resolve(callback(context, filePath));
+  if (composers.exact[viewName])
+    for (const callback of composers.exact[viewName])
+      await Promise.resolve(callback(context, filePath));
+  for (const { pattern, callback } of composers.patterns)
+    if (pattern.test(filePath) || pattern.test(viewName))
+      await Promise.resolve(callback(context, filePath));
+}
+export function clearComposers() {
+  composers.patterns = [];
+  composers.exact = {};
+}

package/dist/virtual-scrolling.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Virtual Scrolling Module
+ *
+ * Provides efficient rendering of large lists using windowing/virtualization.
+ * Only renders items that are visible in the viewport, dramatically improving
+ * performance for lists with thousands of items.
+ *
+ * @example
+ * ```html
+ * @virtualList(items, { itemHeight: 50, containerHeight: 400 })
+ *   <div class="item">{{ item.name }}</div>
+ * @endvirtualList
+ * ```
+ */
+export interface VirtualListOptions {
+    /** Height of each item in pixels */
+    itemHeight: number;
+    /** Height of the container in pixels */
+    containerHeight: number;
+    /** Number of items to render outside the visible area (buffer) */
+    overscan?: number;
+    /** Unique key property for items */
+    keyProperty?: string;
+    /** Enable dynamic item heights */
+    dynamicHeight?: boolean;
+    /** Estimated item height for dynamic heights */
+    estimatedItemHeight?: number;
+    /** Scroll behavior: 'auto' | 'smooth' */
+    scrollBehavior?: 'auto' | 'smooth';
+    /** Direction: 'vertical' | 'horizontal' */
+    direction?: 'vertical' | 'horizontal';
+    /** CSS class for the container */
+    containerClass?: string;
+    /** CSS class for the viewport */
+    viewportClass?: string;
+    /** CSS class for each item wrapper */
+    itemClass?: string;
+}
+export interface VirtualListState {
+    /** Start index of visible items */
+    startIndex: number;
+    /** End index of visible items */
+    endIndex: number;
+    /** Current scroll position */
+    scrollTop: number;
+    /** Total height of all items */
+    totalHeight: number;
+    /** Visible items */
+    visibleItems: unknown[];
+    /** Item heights cache for dynamic heights */
+    itemHeights: Map<number, number>;
+}
+export interface VirtualScrollInstance {
+    /** Scroll to a specific index */
+    scrollToIndex: (index: number, behavior?: ScrollBehavior) => void;
+    /** Scroll to a specific offset */
+    scrollToOffset: (offset: number, behavior?: ScrollBehavior) => void;
+    /** Get current scroll state */
+    getState: () => VirtualListState;
+    /** Force recalculation of visible items */
+    refresh: () => void;
+    /** Update items */
+    setItems: (items: unknown[]) => void;
+    /** Destroy the instance */
+    destroy: () => void;
+}
+/**
+ * Creates a virtual scroll instance for a list of items
+ */
+export declare function createVirtualList<T>(items: T[], options: VirtualListOptions): VirtualScrollInstance;
+/**
+ * Process @virtualList directives in templates
+ */
+export declare function processVirtualListDirectives(template: string, context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Generate CSS for virtual list styling
+ */
+export declare function generateVirtualListCSS(): string;
+/**
+ * Hook to create a reactive virtual list
+ */
+export declare function useVirtualList<T>(items: () => T[], options: VirtualListOptions): {
+    visibleItems: () => T[];
+    totalHeight: () => number;
+    containerProps: () => Record<string, unknown>;
+    itemProps: (index: number) => Record<string, unknown>;
+    scrollToIndex: (index: number) => void;
+};
+export interface InfiniteScrollOptions extends VirtualListOptions {
+    /** Threshold in pixels before end to trigger load more */
+    threshold?: number;
+    /** Callback when more items should be loaded */
+    onLoadMore?: () => Promise<void>;
+    /** Whether more items are available */
+    hasMore?: boolean;
+    /** Loading state */
+    isLoading?: boolean;
+}
+/**
+ * Process @infiniteList directives for infinite scrolling
+ */
+export declare function processInfiniteListDirectives(template: string, context?: Record<string, unknown>, _filePath?: string): string;
+export interface VirtualGridOptions {
+    /** Number of columns */
+    columns: number;
+    /** Row height in pixels */
+    rowHeight: number;
+    /** Container height in pixels */
+    containerHeight: number;
+    /** Gap between items */
+    gap?: number;
+    /** Overscan rows */
+    overscan?: number;
+}
+/**
+ * Process @virtualGrid directives for grid virtualization
+ */
+export declare function processVirtualGridDirectives(template: string, context?: Record<string, unknown>, _filePath?: string): string;
+declare const _default: {
+    createVirtualList: typeof createVirtualList;
+    processVirtualListDirectives: typeof processVirtualListDirectives;
+    processInfiniteListDirectives: typeof processInfiniteListDirectives;
+    processVirtualGridDirectives: typeof processVirtualGridDirectives;
+    generateVirtualListCSS: typeof generateVirtualListCSS;
+    useVirtualList: typeof useVirtualList;
+};
+export default _default;