@htlkg/astro 0.0.1 → 0.0.3

package/src/auth/auth.md

@@ -0,0 +1,77 @@
+# Auth Module
+
+Authentication pages and components.
+
+## Components
+
+### LoginPage
+
+Full login page with form and error handling.
+
+```astro
+---
+import { LoginPage } from '@htlkg/astro/auth';
+---
+
+<LoginPage 
+  redirectTo="/admin"
+  logoUrl="/logo.svg"
+/>
+```
+
+### LoginForm
+
+Vue component for login form (used within LoginPage).
+
+```vue
+<script setup>
+import { LoginForm } from '@htlkg/astro/auth';
+</script>
+
+<template>
+  <LoginForm 
+    @success="handleSuccess"
+    @error="handleError"
+  />
+</template>
+```
+
+## Usage
+
+The auth module is typically used with the htlkg integration which automatically injects the login page:
+
+```javascript
+// astro.config.mjs
+import { htlkg } from '@htlkg/astro';
+
+export default defineConfig({
+  integrations: [
+    htlkg({
+      auth: {
+        enabled: true,
+        loginPage: '/login',
+      },
+    }),
+  ],
+});
+```
+
+## Customization
+
+Create a custom login page:
+
+```astro
+---
+// src/pages/login.astro
+import { AuthLayout } from '@htlkg/astro/layouts';
+import { LoginForm } from '@htlkg/astro/auth';
+---
+
+<AuthLayout title="Sign In">
+  <div class="custom-login">
+    <img src="/logo.svg" alt="Logo" />
+    <h1>Welcome Back</h1>
+    <LoginForm client:load />
+  </div>
+</AuthLayout>
+```

package/src/components/Island.astro

@@ -0,0 +1,56 @@
+---
+/**
+ * Island Component
+ *
+ * A wrapper component for Vue islands that handles:
+ * - Automatic nanostore synchronization from server to client
+ * - Hydration strategy selection
+ * - Props forwarding
+ *
+ * @example
+ * ```astro
+ * <Island
+ *   component={AccountsPage}
+ *   data={{ accounts }}
+ *   stores={{ accounts: $accounts }}
+ *   hydration="load"
+ * />
+ * ```
+ */
+
+import type { Component } from "vue";
+import type { WritableAtom } from "nanostores";
+
+interface Props {
+	/** Vue component to render */
+	component: Component;
+	/** Data to sync to stores */
+	data?: Record<string, any>;
+	/** Store mapping { dataKey: storeAtom } */
+	stores?: Record<string, WritableAtom<any>>;
+	/** Hydration strategy */
+	hydration?: "load" | "idle" | "visible" | "only";
+	/** Additional props to pass to the component */
+	props?: Record<string, any>;
+}
+
+const {
+	component: Component,
+	data = {},
+	stores = {},
+	hydration = "load",
+	props = {},
+} = Astro.props;
+
+// Auto-sync data to stores on server-side
+for (const [key, store] of Object.entries(stores)) {
+	if (data[key] !== undefined) {
+		store.set(data[key]);
+	}
+}
+---
+
+{hydration === "load" && <Component client:load {...props} />}
+{hydration === "idle" && <Component client:idle {...props} />}
+{hydration === "visible" && <Component client:visible {...props} />}
+{hydration === "only" && <Component client:only="vue" {...props} />}

package/src/components/components.md

@@ -0,0 +1,79 @@
+# Components Module
+
+Astro components for page structure and navigation.
+
+## Installation
+
+```typescript
+import { Sidebar } from '@htlkg/astro/components';
+import { Topbar } from '@htlkg/astro/components';
+import { PageHeader } from '@htlkg/astro/components';
+import { Island } from '@htlkg/astro/components';
+```
+
+## Sidebar
+
+Navigation sidebar for admin layouts.
+
+```astro
+---
+import { Sidebar } from '@htlkg/astro/components';
+
+const navItems = [
+  { label: 'Dashboard', href: '/admin', icon: 'home' },
+  { label: 'Brands', href: '/admin/brands', icon: 'building' },
+  { label: 'Users', href: '/admin/users', icon: 'users' },
+];
+---
+
+<Sidebar items={navItems} currentPath={Astro.url.pathname} />
+```
+
+## Topbar
+
+Top navigation bar with user menu.
+
+```astro
+---
+import { Topbar } from '@htlkg/astro/components';
+
+const user = Astro.locals.user;
+---
+
+<Topbar user={user} title="Admin Portal" />
+```
+
+## PageHeader
+
+Page header with title, breadcrumbs, and actions.
+
+```astro
+---
+import { PageHeader } from '@htlkg/astro/components';
+
+const breadcrumbs = [
+  { label: 'Admin', href: '/admin' },
+  { label: 'Brands', href: '/admin/brands' },
+];
+---
+
+<PageHeader 
+  title="Brands" 
+  breadcrumbs={breadcrumbs}
+>
+  <button slot="actions">Add Brand</button>
+</PageHeader>
+```
+
+## Island
+
+Wrapper for client-side Vue components with hydration control.
+
+```astro
+---
+import { Island } from '@htlkg/astro/components';
+import BrandList from '@/components/BrandList.vue';
+---
+
+<Island component={BrandList} client:load props={{ brands }} />
+```

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);
+```