@htlkg/astro 0.0.2 → 0.0.3

package/src/factories/createListPage.ts

@@ -0,0 +1,290 @@
+/**
+ * List Page Factory
+ *
+ * Factory function for creating standardized list pages with automatic
+ * data fetching, filtering, sorting, and pagination.
+ */
+
+import type { AstroGlobal } from "astro";
+import type { WritableAtom } from "nanostores";
+
+import {
+	parseListParams,
+	type ListParams,
+	type ListParamConfig,
+	type FilterFieldConfig,
+} from "../utils/params";
+import {
+	buildGraphQLFilter,
+	applyClientFilters,
+	sortItems,
+	paginateItems,
+} from "../utils/filters";
+
+/**
+ * Breadcrumb item
+ */
+export interface BreadcrumbItem {
+	label: string;
+	href?: string;
+}
+
+/**
+ * Layout props returned by the factory
+ */
+export interface LayoutProps {
+	title: string;
+	description?: string;
+	currentPage: string;
+	breadcrumbs: BreadcrumbItem[];
+}
+
+/**
+ * Table initial state
+ */
+export interface TableInitialState {
+	currentPage: number;
+	pageSize: number;
+	sortKey: string;
+	sortOrder: "asc" | "desc";
+	totalItems: number;
+	totalPages: number;
+	filters: Record<string, any>;
+	search?: string;
+}
+
+/**
+ * Related store configuration
+ */
+export interface RelatedStoreConfig<T = any> {
+	store: WritableAtom<T[]>;
+	fetch: () => Promise<T[]>;
+}
+
+/**
+ * Configuration for createListPage
+ */
+export interface ListPageConfig<T> {
+	// Page metadata
+	/** Page title */
+	title: string;
+	/** Page description */
+	description?: string;
+	/** Page identifier (for sidebar active state) */
+	pageId: string;
+	/** Custom breadcrumbs (auto-generated if not provided) */
+	breadcrumbs?: BreadcrumbItem[];
+
+	// Data fetching
+	/** Fetch function that retrieves data */
+	fetchFn: (params: {
+		filter: any;
+		limit?: number;
+		nextToken?: string;
+	}) => Promise<{ data: T[]; nextToken?: string | null }>;
+
+	// Data handling
+	/** Transform function to apply to fetched data */
+	transform?: (item: any) => T;
+	/** Main store to set with data */
+	store: WritableAtom<T[]>;
+	/** Related stores to populate */
+	relatedStores?: Record<string, RelatedStoreConfig>;
+
+	// Filtering/sorting config
+	/** Searchable field keys */
+	searchableFields?: string[];
+	/** Filterable field configurations */
+	filterableFields?: FilterFieldConfig[];
+	/** Sortable field keys (all by default) */
+	sortableFields?: string[];
+	/** Default sort configuration */
+	defaultSort?: { key: string; order: "asc" | "desc" };
+	/** Default page size */
+	defaultPageSize?: number;
+	/** Maximum items to fetch from API */
+	fetchLimit?: number;
+}
+
+/**
+ * Result from createListPage
+ */
+export interface ListPageResult<T> {
+	/** Props to spread to Layout component */
+	layoutProps: LayoutProps;
+	/** Initial state for table component */
+	initialState: TableInitialState;
+	/** Processed items (paginated) */
+	items: T[];
+	/** All items (pre-pagination, for client-side operations) */
+	allItems: T[];
+	/** Parsed URL parameters */
+	params: ListParams;
+}
+
+/**
+ * Default breadcrumb generator
+ */
+function generateBreadcrumbs(pageId: string, title: string): BreadcrumbItem[] {
+	return [
+		{ label: "Admin", href: "/admin" },
+		{ label: title },
+	];
+}
+
+/**
+ * Create a list page with automatic data handling
+ *
+ * This factory handles:
+ * - URL parameter parsing (page, pageSize, sortKey, sortOrder, filters)
+ * - Data fetching with GraphQL filter building
+ * - Data transformation
+ * - Client-side filtering (for computed fields)
+ * - Sorting
+ * - Pagination
+ * - Store population
+ *
+ * @example
+ * ```astro
+ * ---
+ * import { createListPage } from '@htlkg/astro/factories';
+ * import { $accounts } from '@/stores/accounts';
+ *
+ * const { layoutProps, initialState, items } = await createListPage(Astro, {
+ *   title: 'Accounts',
+ *   pageId: 'accounts',
+ *   store: $accounts,
+ *
+ *   fetchFn: async ({ filter }) => {
+ *     const client = getServerClient(Astro);
+ *     return await client.models.Account.list({ filter });
+ *   },
+ *
+ *   transform: (account) => ({
+ *     id: account.id,
+ *     name: account.name,
+ *     brandCount: account.brands?.length ?? 0,
+ *   }),
+ *
+ *   filterableFields: [
+ *     { key: 'name', type: 'text', graphql: true },
+ *     { key: 'status', type: 'select', graphql: true, options: ['active', 'inactive'] },
+ *   ],
+ *
+ *   defaultSort: { key: 'name', order: 'asc' },
+ * });
+ * ---
+ *
+ * <Layout {...layoutProps}>
+ *   <AccountsTable client:load initialState={initialState} />
+ * </Layout>
+ * ```
+ */
+export async function createListPage<T extends Record<string, any>>(
+	astro: AstroGlobal,
+	config: ListPageConfig<T>
+): Promise<ListPageResult<T>> {
+	const {
+		title,
+		description,
+		pageId,
+		breadcrumbs,
+		fetchFn,
+		transform,
+		store,
+		relatedStores,
+		searchableFields,
+		filterableFields = [],
+		defaultSort,
+		defaultPageSize = 25,
+		fetchLimit = 1000,
+	} = config;
+
+	// 1. Parse URL parameters
+	const paramConfig: ListParamConfig = {
+		defaultPageSize,
+		defaultSort,
+		searchableFields,
+		filterableFields,
+	};
+	const params = parseListParams(astro.url, paramConfig);
+
+	// 2. Build GraphQL filter from URL params
+	const graphqlFilter = buildGraphQLFilter(params.filters, filterableFields, {
+		search: params.search,
+		searchFields: searchableFields,
+	});
+
+	// 3. Fetch data with pagination
+	let allItems: T[] = [];
+	let nextToken: string | null | undefined = undefined;
+
+	do {
+		const result = await fetchFn({
+			filter: graphqlFilter,
+			limit: fetchLimit,
+			nextToken: nextToken ?? undefined,
+		});
+
+		const data = result.data ?? [];
+		allItems = allItems.concat(data);
+		nextToken = result.nextToken;
+	} while (nextToken);
+
+	// 4. Transform data if needed
+	if (transform) {
+		allItems = allItems.map(transform);
+	}
+
+	// 5. Apply client-side filtering (for computed fields not in GraphQL)
+	allItems = applyClientFilters(allItems, params.filters, filterableFields, {
+		search: params.search,
+		searchFields: searchableFields,
+	});
+
+	// 6. Sort
+	allItems = sortItems(allItems, params.sortKey, params.sortOrder);
+
+	// 7. Paginate
+	const { paginatedItems, totalItems, totalPages, currentPage, pageSize } = paginateItems(
+		allItems,
+		params.page,
+		params.pageSize
+	);
+
+	// 8. Set main store
+	store.set(paginatedItems);
+
+	// 9. Fetch and set related stores
+	if (relatedStores) {
+		await Promise.all(
+			Object.entries(relatedStores).map(async ([, config]) => {
+				const data = await config.fetch();
+				config.store.set(data);
+			})
+		);
+	}
+
+	// 10. Build result
+	return {
+		layoutProps: {
+			title,
+			description,
+			currentPage: pageId,
+			breadcrumbs: breadcrumbs ?? generateBreadcrumbs(pageId, title),
+		},
+		initialState: {
+			currentPage,
+			pageSize,
+			sortKey: params.sortKey,
+			sortOrder: params.sortOrder,
+			totalItems,
+			totalPages,
+			filters: params.filters,
+			search: params.search,
+		},
+		items: paginatedItems,
+		allItems,
+		params,
+	};
+}

package/src/factories/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Page Factories for @htlkg/astro
+ *
+ * Factory functions for creating standardized Astro pages with automatic
+ * data handling, filtering, sorting, and pagination.
+ */
+
+export {
+	createListPage,
+	type ListPageConfig,
+	type ListPageResult,
+	type LayoutProps,
+	type TableInitialState,
+	type BreadcrumbItem,
+	type RelatedStoreConfig,
+} from "./createListPage";

package/src/htlkg/config.ts

@@ -209,6 +209,16 @@ export interface HtlkgIntegrationOptions {
 	 * @default undefined (Tailwind enabled with default config)
 	 */
 	tailwind?: Record<string, unknown> | false;
+
+	/**
+	 * Vue app setup mode.
+	 * - 'full': Use the Amplify-configured Vue app setup (requires SSR)
+	 * - 'basic': Use basic Vue integration without Amplify app setup (works with static)
+	 * - 'auto': Automatically detect based on output mode (default)
+	 *
+	 * @default 'auto'
+	 */
+	vueAppSetup?: 'full' | 'basic' | 'auto';
 }
 
 /**

package/src/htlkg/htlkg.md

@@ -0,0 +1,63 @@
+# htlkg Integration
+
+Zero-config Astro integration for Hotelinking applications.
+
+## Installation
+
+```javascript
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import { htlkg } from '@htlkg/astro';
+
+export default defineConfig({
+  integrations: [
+    htlkg({
+      auth: {
+        enabled: true,
+        loginPage: '/login',
+        publicRoutes: ['/login', '/public'],
+      },
+      brandRoutes: {
+        enabled: true,
+        pattern: '/[brandId]',
+      },
+    }),
+  ],
+});
+```
+
+## Features
+
+- Automatic middleware setup
+- Route guard configuration
+- Login page injection
+- Brand route handling
+- Virtual module configuration
+
+## Options
+
+```typescript
+interface HtlkgIntegrationOptions {
+  auth?: {
+    enabled: boolean;
+    loginPage?: string;
+    publicRoutes?: RoutePattern[];
+    protectedRoutes?: RoutePattern[];
+  };
+  brandRoutes?: {
+    enabled: boolean;
+    pattern?: string;
+  };
+}
+```
+
+## Virtual Modules
+
+The integration provides virtual modules for configuration:
+
+```typescript
+// Access config in your code
+import config from 'virtual:htlkg-config';
+
+console.log(config.auth.loginPage);
+```

package/src/htlkg/index.ts

@@ -1,12 +1,7 @@
 /**
  * htlkg Astro Integration
  * 
- * Provides zero-config setup for Hotelinking applications with:
- * - Tailwind CSS integration
- * - Vue 3 integration with Amplify setup
- * - Authentication middleware
- * - Route guards
- * - Login page generation
+ * Supports static, hybrid, and full SSR output modes.
  */
 
 import tailwind from '@astrojs/tailwind';
@@ -16,46 +11,11 @@ import type { HtlkgIntegrationOptions } from './config.js';
 import { createVirtualModulePlugin, virtualModuleTypes } from './virtual-modules.js';
 import vueDevTools from 'vite-plugin-vue-devtools';
 
-/**
- * Default environment variables required for AWS Amplify authentication
- */
 const DEFAULT_ENV_VARS = [
 	'PUBLIC_COGNITO_USER_POOL_ID',
 	'PUBLIC_COGNITO_USER_POOL_CLIENT_ID'
 ];
 
-/**
- * htlkg Astro integration that provides zero-config authentication setup.
- *
- * This integration automatically:
- * - Includes Tailwind CSS integration (can be disabled)
- * - Includes Vue 3 integration with Amplify and Nanostores setup
- * - Injects authentication middleware for AWS Amplify
- * - Configures route guards based on declarative configuration
- * - Validates required environment variables (optional)
- * - Injects TypeScript types for Astro.locals.user
- * - Provides a default login page (optional)
- *
- * @param options - Configuration options for the integration
- * @returns Astro integration object or array of integrations
- *
- * @example
- * // astro.config.mjs
- * import { htlkg } from '@htlkg/astro';
- *
- * export default defineConfig({
- *   integrations: [
- *     htlkg({
- *       tailwind: { configFile: './tailwind.config.mjs' },
- *       auth: {
- *         publicRoutes: ['/login', '/'],
- *         adminRoutes: [/^\/admin/],
- *         loginUrl: '/login'
- *       }
- *     })
- *   ]
- * });
- */
 export function htlkg(
 	options: HtlkgIntegrationOptions = {},
 ): AstroIntegration | AstroIntegration[] {
@@ -66,6 +26,7 @@ export function htlkg(
 		requiredEnvVars = DEFAULT_ENV_VARS,
 		tailwind: tailwindOptions,
 		amplify,
+		vueAppSetup = 'auto',
 	} = options;
 
 	const integrations: AstroIntegration[] = [];
@@ -79,154 +40,77 @@ export function htlkg(
 		);
 	}
 
-	// Add Vue integration with Amplify setup entrypoint
-	// Use package import specifier that Vite can resolve
-	integrations.push(
-		vue({
-			appEntrypoint: '@htlkg/astro/vue-app-setup',
-		}),
-	);
+	// Determine Vue setup mode:
+	// - 'full': Use Amplify app entrypoint (requires SSR)
+	// - 'basic': Basic Vue without app entrypoint (works with static)
+	// - 'auto': Default to 'basic' for compatibility with static builds
+	const useFullVueSetup = vueAppSetup === 'full';
+
+	// Add Vue integration
+	if (useFullVueSetup) {
+		integrations.push(vue({ appEntrypoint: '@htlkg/astro/vue-app-setup' }));
+	} else {
+		integrations.push(vue());
+	}
 
 	// Add the main htlkg integration
 	integrations.push({
 		name: '@htlkg/astro',
 		hooks: {
-			'astro:config:setup': ({
-				config,
-				updateConfig,
-				addMiddleware,
-				injectRoute,
-				logger,
-			}) => {
+			'astro:config:setup': ({ updateConfig, addMiddleware, injectRoute, logger }) => {
 				try {
-					// 1. Verify Vue integration is present
-					const hasVue = config.integrations.some(
-						(i) => i.name === '@astrojs/vue',
-					);
-					if (hasVue) {
-						logger.info('Vue integration configured with Amplify app setup');
-					}
+					logger.info(useFullVueSetup 
+						? 'Vue configured with Amplify app setup' 
+						: 'Vue configured (basic mode)');
 
-					// 2. Amplify will be configured by the middleware on first request
 					if (amplify) {
-						logger.info('Amplify configuration provided - will be configured on first request');
-					} else {
-						logger.info('No Amplify configuration provided - will use environment variables');
+						logger.info('Amplify configuration provided');
 					}
 
-					// 3. Validate environment variables (only if not using amplify_outputs.json)
-					if (validateEnv && !amplify) {
-						const missing = requiredEnvVars.filter(
-							(varName) => !process.env[varName],
-						);
-
+					// Validate env vars (only for full setup)
+					if (validateEnv && !amplify && useFullVueSetup) {
+						const missing = requiredEnvVars.filter(v => !process.env[v]);
 						if (missing.length > 0) {
-							logger.warn(
-								`Missing required environment variables: ${missing.join(', ')}\nAuthentication may not work correctly. Please set these in your .env file:\n${missing.map((v) => `  - ${v}`).join('\n')}`,
-							);
-						} else {
-							logger.info('All required environment variables are present');
+							logger.warn(`Missing env vars: ${missing.join(', ')}`);
 						}
 					}
 
-					// 4. Create Vite virtual module plugin to pass configuration to middleware and pages
-					try {
-						const virtualModulePlugin = createVirtualModulePlugin(
-							auth,
-							loginPage,
-							amplify || null
-						);
-
-						const vitePlugins: any[] = [virtualModulePlugin];
-						
-						// Add Vue DevTools plugin in development
-						if (import.meta.env?.DEV !== false) {
-							vitePlugins.push(vueDevTools());
-							logger.info('Vue DevTools plugin enabled for development');
-						}
-
-						updateConfig({
-							vite: {
-								plugins: vitePlugins,
-							},
-						});
-					} catch (error) {
-						const errorMsg =
-							error instanceof Error ? error.message : 'Unknown error';
-						logger.error(
-							`Failed to create virtual module for route configuration: ${errorMsg}`,
-						);
-						throw error;
-					}
-
-					// 5. Inject middleware
-					try {
-						addMiddleware({
-							entrypoint: '@htlkg/astro/middleware',
-							order: 'pre',
-						});
-						logger.info('Authentication middleware injected successfully');
-					} catch (error) {
-						const errorMsg =
-							error instanceof Error ? error.message : 'Unknown error';
-						logger.error(`Failed to inject middleware: ${errorMsg}`);
-						throw error;
+					// Create Vite virtual module plugin
+					const virtualModulePlugin = createVirtualModulePlugin(auth, loginPage, amplify || null);
+					const vitePlugins: any[] = [virtualModulePlugin];
+					
+					if (import.meta.env?.DEV !== false) {
+						vitePlugins.push(vueDevTools());
+						logger.info('Vue DevTools enabled');
 					}
 
-					// 6. Verify Vue app entrypoint is configured
-					const vueIntegrationIndex = config.integrations.findIndex(
-						(i) => i.name === '@astrojs/vue',
-					);
-
-					if (vueIntegrationIndex === -1) {
-						logger.warn(
-							'@astrojs/vue integration not found.\n' +
-								'The htlkg integration should have added it automatically.\n' +
-								'If you see this warning, there may be an integration ordering issue.',
-						);
-					} else {
-						logger.info('Vue app setup with Amplify configuration enabled');
-					}
-
-					// 7. Verify Tailwind integration
-					const hasTailwind = config.integrations.some(
-						(i) =>
-							i.name === '@astrojs/tailwind' || i.name === 'astro:tailwind',
-					);
+					updateConfig({ vite: { plugins: vitePlugins } });
 
-					if (hasTailwind) {
-						logger.info('Tailwind CSS integration configured');
+					// Inject middleware (only for full setup)
+					if (useFullVueSetup) {
+						addMiddleware({ entrypoint: '@htlkg/astro/middleware', order: 'pre' });
+						logger.info('Authentication middleware injected');
 					}
 
-					// 8. Inject login page route if enabled
-					if (loginPage !== false) {
-						try {
-							const loginPath = loginPage.path || '/login';
-							injectRoute({
-								pattern: loginPath,
-								entrypoint: '@htlkg/astro/auth/LoginPage.astro',
-								prerender: false,
-							});
-							logger.info(`Injected default login page at ${loginPath}`);
-						} catch (error) {
-							const errorMsg =
-								error instanceof Error ? error.message : 'Unknown error';
-							logger.warn(`Failed to inject login page: ${errorMsg}`);
-						}
+					// Inject login page (only for full setup)
+					if (loginPage !== false && useFullVueSetup) {
+						const loginPath = loginPage.path || '/login';
+						injectRoute({
+							pattern: loginPath,
+							entrypoint: '@htlkg/astro/auth/LoginPage.astro',
+							prerender: false,
+						});
+						logger.info(`Login page injected at ${loginPath}`);
 					}
 
-					logger.info('htlkg integration configured successfully');
+					logger.info('htlkg integration configured');
 				} catch (error) {
-					const errorMsg =
-						error instanceof Error ? error.message : 'Unknown error';
-					logger.error(
-						`Failed to configure htlkg integration: ${errorMsg}`,
-					);
+					const msg = error instanceof Error ? error.message : 'Unknown error';
+					logger.error(`htlkg configuration failed: ${msg}`);
 					throw error;
 				}
 			},
 			'astro:config:done': ({ injectTypes }) => {
-				// Inject TypeScript types for Astro.locals and virtual module
 				injectTypes({
 					filename: 'htlkg.d.ts',
 					content: `
@@ -249,6 +133,5 @@ export {};
 		},
 	});
 
-	// Return single integration or array based on what was added
-	return integrations.length === 1 ? integrations[0] : integrations;
+	return integrations;
 }

package/src/index.ts

@@ -32,6 +32,9 @@ export { isAuthenticatedUser } from './htlkg/config.js';
 // Utils
 export * from './utils';
 
+// Page Factories
+export * from './factories';
+
 // Middleware is not exported from main index to avoid bundling astro:middleware
 // It's loaded by Astro at runtime via the entrypoint specified in addMiddleware
 // Import from '@htlkg/astro/middleware' if needed