@htlkg/astro 0.0.2 → 0.0.4

package/src/layouts/layouts.md

@@ -0,0 +1,87 @@
+# Layouts Module
+
+Pre-built page layouts for common page types.
+
+## Installation
+
+```typescript
+import { AdminLayout } from '@htlkg/astro/layouts';
+import { BrandLayout } from '@htlkg/astro/layouts';
+import { AuthLayout } from '@htlkg/astro/layouts';
+import { PublicLayout } from '@htlkg/astro/layouts';
+```
+
+## AdminLayout
+
+Admin portal pages with sidebar navigation.
+
+```astro
+---
+import { AdminLayout } from '@htlkg/astro/layouts';
+
+const user = Astro.locals.user;
+---
+
+<AdminLayout user={user} title="Dashboard">
+  <DashboardContent />
+</AdminLayout>
+```
+
+## BrandLayout
+
+Brand-specific pages with brand context.
+
+```astro
+---
+import { BrandLayout } from '@htlkg/astro/layouts';
+
+const { brandId } = Astro.params;
+const brand = await getBrand(brandId);
+---
+
+<BrandLayout brand={brand} title="Brand Settings">
+  <BrandSettings />
+</BrandLayout>
+```
+
+## AuthLayout
+
+Authentication pages (login, signup).
+
+```astro
+---
+import { AuthLayout } from '@htlkg/astro/layouts';
+---
+
+<AuthLayout title="Login">
+  <LoginForm />
+</AuthLayout>
+```
+
+## PublicLayout
+
+Public-facing pages without authentication.
+
+```astro
+---
+import { PublicLayout } from '@htlkg/astro/layouts';
+---
+
+<PublicLayout title="Welcome">
+  <LandingPage />
+</PublicLayout>
+```
+
+## DefaultLayout
+
+Base layout with minimal styling.
+
+```astro
+---
+import { DefaultLayout } from '@htlkg/astro/layouts';
+---
+
+<DefaultLayout title="Page Title">
+  <slot />
+</DefaultLayout>
+```

package/src/middleware/middleware.md

@@ -0,0 +1,82 @@
+# Middleware Module
+
+Authentication middleware and route guards for Astro.
+
+## Installation
+
+```typescript
+import {
+  requireAuth,
+  requireAdminAccess,
+  requireBrandAccess,
+} from '@htlkg/astro/middleware';
+```
+
+## Route Guards
+
+### requireAuth
+
+Require authenticated user. Redirects to login if not authenticated.
+
+```astro
+---
+import { requireAuth } from '@htlkg/astro/middleware';
+
+export const prerender = false;
+
+const { user } = await requireAuth(Astro);
+---
+
+<h1>Welcome, {user.username}</h1>
+```
+
+### requireAdminAccess
+
+Require admin role.
+
+```astro
+---
+import { requireAdminAccess } from '@htlkg/astro/middleware';
+
+export const prerender = false;
+
+const { user } = await requireAdminAccess(Astro);
+---
+
+<AdminDashboard user={user} />
+```
+
+### requireBrandAccess
+
+Require access to a specific brand.
+
+```astro
+---
+import { requireBrandAccess } from '@htlkg/astro/middleware';
+
+export const prerender = false;
+
+const { brandId } = Astro.params;
+const { user, brand } = await requireBrandAccess(Astro, brandId);
+---
+
+<BrandDashboard brand={brand} user={user} />
+```
+
+## Custom Login URL
+
+```typescript
+await requireAuth(Astro, '/custom-login');
+await requireAdminAccess(Astro, '/admin/login');
+```
+
+## Route Guard Config
+
+```typescript
+interface RouteGuardConfig {
+  publicRoutes: RoutePattern[];
+  protectedRoutes: RoutePattern[];
+  loginPage: string;
+  brandRoutePattern?: RegExp;
+}
+```

package/src/patterns/patterns.md

@@ -0,0 +1,104 @@
+# Patterns Module
+
+Reusable page patterns for common admin and brand pages.
+
+## Installation
+
+```typescript
+// Admin patterns
+import { ListPage } from '@htlkg/astro/patterns/admin';
+import { DetailPage } from '@htlkg/astro/patterns/admin';
+import { FormPage } from '@htlkg/astro/patterns/admin';
+
+// Brand patterns
+import { ConfigPage } from '@htlkg/astro/patterns/brand';
+import { PortalPage } from '@htlkg/astro/patterns/brand';
+```
+
+## Admin Patterns
+
+### ListPage
+
+List/table view with filters and pagination.
+
+```astro
+---
+import { ListPage } from '@htlkg/astro/patterns/admin';
+---
+
+<ListPage
+  title="Brands"
+  items={brands}
+  columns={columns}
+  filters={filters}
+  onRowClick={(brand) => `/admin/brands/${brand.id}`}
+/>
+```
+
+### DetailPage
+
+Detail view with tabs and actions.
+
+```astro
+---
+import { DetailPage } from '@htlkg/astro/patterns/admin';
+---
+
+<DetailPage
+  title={brand.name}
+  tabs={['Overview', 'Settings', 'Users']}
+  actions={['Edit', 'Delete']}
+>
+  <BrandOverview slot="Overview" brand={brand} />
+  <BrandSettings slot="Settings" brand={brand} />
+  <BrandUsers slot="Users" brand={brand} />
+</DetailPage>
+```
+
+### FormPage
+
+Form view with validation.
+
+```astro
+---
+import { FormPage } from '@htlkg/astro/patterns/admin';
+---
+
+<FormPage
+  title="Create Brand"
+  schema={brandSchema}
+  onSubmit={handleSubmit}
+/>
+```
+
+## Brand Patterns
+
+### ConfigPage
+
+Configuration page for brand settings.
+
+```astro
+---
+import { ConfigPage } from '@htlkg/astro/patterns/brand';
+---
+
+<ConfigPage
+  brand={brand}
+  product={product}
+  config={productConfig}
+/>
+```
+
+### PortalPage
+
+Public portal page for brand.
+
+```astro
+---
+import { PortalPage } from '@htlkg/astro/patterns/brand';
+---
+
+<PortalPage brand={brand}>
+  <WifiPortal />
+</PortalPage>
+```

package/src/utils/filters.ts

@@ -0,0 +1,320 @@
+/**
+ * Filter Building Utilities
+ *
+ * Utilities for building GraphQL filters from parsed URL parameters,
+ * and for applying client-side filters to data.
+ */
+
+import type { FilterFieldConfig, ListParams } from "./params";
+
+/**
+ * GraphQL filter operators
+ */
+export type GraphQLOperator = "eq" | "ne" | "le" | "lt" | "ge" | "gt" | "contains" | "notContains" | "beginsWith" | "between";
+
+/**
+ * GraphQL filter condition
+ */
+export interface GraphQLFilterCondition {
+	[key: string]: {
+		[operator in GraphQLOperator]?: any;
+	};
+}
+
+/**
+ * GraphQL combined filter
+ */
+export interface GraphQLFilter {
+	and?: GraphQLFilterCondition[];
+	or?: GraphQLFilterCondition[];
+	not?: GraphQLFilter;
+	[key: string]: any;
+}
+
+/**
+ * Build GraphQL filter from parsed URL parameters
+ *
+ * Only includes fields marked with `graphql: true` in the field config.
+ *
+ * @example
+ * ```typescript
+ * const filter = buildGraphQLFilter(
+ *   { status: 'active', name: 'test' },
+ *   [
+ *     { key: 'status', type: 'select', graphql: true },
+ *     { key: 'name', type: 'text', graphql: true },
+ *   ]
+ * );
+ * // Returns: { and: [{ status: { eq: 'active' } }, { name: { contains: 'test' } }] }
+ * ```
+ */
+export function buildGraphQLFilter(
+	filters: Record<string, any>,
+	filterableFields: FilterFieldConfig[],
+	options: { searchFields?: string[]; search?: string } = {}
+): GraphQLFilter | undefined {
+	const conditions: GraphQLFilterCondition[] = [];
+
+	// Build field filters
+	for (const field of filterableFields) {
+		if (!field.graphql) continue;
+
+		const value = filters[field.key];
+		if (value === undefined || value === null || value === "") continue;
+
+		const condition = buildFieldCondition(field, value);
+		if (condition) {
+			conditions.push(condition);
+		}
+	}
+
+	// Build search filter (applies to multiple fields with OR)
+	if (options.search && options.searchFields && options.searchFields.length > 0) {
+		const searchConditions = options.searchFields.map((fieldKey) => ({
+			[fieldKey]: { contains: options.search },
+		}));
+
+		if (searchConditions.length === 1) {
+			conditions.push(searchConditions[0]);
+		} else if (searchConditions.length > 1) {
+			// Multiple search fields use OR
+			conditions.push({ or: searchConditions } as unknown as GraphQLFilterCondition);
+		}
+	}
+
+	// Return combined filter
+	if (conditions.length === 0) {
+		return undefined;
+	}
+
+	if (conditions.length === 1) {
+		return conditions[0] as unknown as GraphQLFilter;
+	}
+
+	return { and: conditions };
+}
+
+/**
+ * Build a single field condition
+ */
+function buildFieldCondition(field: FilterFieldConfig, value: any): GraphQLFilterCondition | undefined {
+	// Use custom operator if provided
+	const operator = field.graphqlOperator;
+
+	if (operator) {
+		// Use the custom operator specified in config
+		return { [field.key]: { [operator]: value } };
+	}
+
+	// Default behavior based on field type
+	switch (field.type) {
+		case "text":
+			// Text fields use contains by default (case-sensitive in DynamoDB)
+			return { [field.key]: { contains: String(value) } };
+
+		case "number":
+			// Number fields use exact match
+			return { [field.key]: { eq: Number(value) } };
+
+		case "boolean":
+			// Boolean fields use exact match
+			return { [field.key]: { eq: Boolean(value) } };
+
+		case "date":
+			// Date fields - could be exact or range
+			if (value instanceof Date) {
+				return { [field.key]: { eq: value.toISOString() } };
+			}
+			return { [field.key]: { eq: value } };
+
+		case "select":
+			// Select fields use exact match
+			return { [field.key]: { eq: value } };
+
+		default:
+			return { [field.key]: { eq: value } };
+	}
+}
+
+/**
+ * Apply client-side filters to data array
+ *
+ * Only applies filters for fields NOT marked with `graphql: true`.
+ *
+ * @example
+ * ```typescript
+ * const filtered = applyClientFilters(
+ *   items,
+ *   { brandCount: 5 },
+ *   [{ key: 'brandCount', type: 'number', graphql: false }]
+ * );
+ * ```
+ */
+export function applyClientFilters<T extends Record<string, any>>(
+	items: T[],
+	filters: Record<string, any>,
+	filterableFields: FilterFieldConfig[],
+	options: { search?: string; searchFields?: string[] } = {}
+): T[] {
+	let result = items;
+
+	// Apply field filters (only non-GraphQL fields)
+	for (const field of filterableFields) {
+		if (field.graphql) continue; // Skip GraphQL fields
+
+		const value = filters[field.key];
+		if (value === undefined || value === null || value === "") continue;
+
+		result = result.filter((item) => matchesFieldFilter(item, field, value));
+	}
+
+	// Apply search filter (only if not applied via GraphQL)
+	if (options.search && options.searchFields) {
+		const searchLower = options.search.toLowerCase();
+		result = result.filter((item) =>
+			options.searchFields!.some((fieldKey) => {
+				const fieldValue = item[fieldKey];
+				if (fieldValue === null || fieldValue === undefined) return false;
+				return String(fieldValue).toLowerCase().includes(searchLower);
+			})
+		);
+	}
+
+	return result;
+}
+
+/**
+ * Check if an item matches a field filter
+ */
+function matchesFieldFilter<T extends Record<string, any>>(item: T, field: FilterFieldConfig, filterValue: any): boolean {
+	const itemValue = item[field.key];
+
+	switch (field.type) {
+		case "text":
+			if (itemValue === null || itemValue === undefined) return false;
+			return String(itemValue).toLowerCase().includes(String(filterValue).toLowerCase());
+
+		case "number":
+			return Number(itemValue) === Number(filterValue);
+
+		case "boolean":
+			return Boolean(itemValue) === Boolean(filterValue);
+
+		case "date":
+			if (!itemValue) return false;
+			const itemDate = itemValue instanceof Date ? itemValue : new Date(itemValue);
+			const filterDate = filterValue instanceof Date ? filterValue : new Date(filterValue);
+			// Compare dates (ignoring time)
+			return itemDate.toDateString() === filterDate.toDateString();
+
+		case "select":
+			return itemValue === filterValue;
+
+		default:
+			return itemValue === filterValue;
+	}
+}
+
+/**
+ * Sort items by a key
+ */
+export function sortItems<T extends Record<string, any>>(items: T[], sortKey: string, sortOrder: "asc" | "desc"): T[] {
+	if (!sortKey) return items;
+
+	const multiplier = sortOrder === "asc" ? 1 : -1;
+
+	return [...items].sort((a, b) => {
+		const aVal = a[sortKey];
+		const bVal = b[sortKey];
+
+		// Handle null/undefined
+		if (aVal === null || aVal === undefined) return 1;
+		if (bVal === null || bVal === undefined) return -1;
+		if (aVal === bVal) return 0;
+
+		// Handle different types
+		if (typeof aVal === "string" && typeof bVal === "string") {
+			return aVal.localeCompare(bVal) * multiplier;
+		}
+
+		if (typeof aVal === "number" && typeof bVal === "number") {
+			return (aVal - bVal) * multiplier;
+		}
+
+		if (aVal instanceof Date && bVal instanceof Date) {
+			return (aVal.getTime() - bVal.getTime()) * multiplier;
+		}
+
+		// Fallback to string comparison
+		return String(aVal).localeCompare(String(bVal)) * multiplier;
+	});
+}
+
+/**
+ * Paginate items
+ */
+export function paginateItems<T>(
+	items: T[],
+	page: number,
+	pageSize: number
+): {
+	paginatedItems: T[];
+	totalItems: number;
+	totalPages: number;
+	currentPage: number;
+	pageSize: number;
+} {
+	const totalItems = items.length;
+	const totalPages = Math.ceil(totalItems / pageSize);
+	const currentPage = Math.min(Math.max(1, page), totalPages || 1);
+
+	const startIndex = (currentPage - 1) * pageSize;
+	const endIndex = startIndex + pageSize;
+	const paginatedItems = items.slice(startIndex, endIndex);
+
+	return {
+		paginatedItems,
+		totalItems,
+		totalPages,
+		currentPage,
+		pageSize,
+	};
+}
+
+/**
+ * Process list data with filters, sorting, and pagination
+ *
+ * Convenience function that combines all processing steps.
+ */
+export function processListData<T extends Record<string, any>>(
+	items: T[],
+	params: ListParams,
+	filterableFields: FilterFieldConfig[],
+	options: { searchFields?: string[] } = {}
+): {
+	items: T[];
+	totalItems: number;
+	totalPages: number;
+	currentPage: number;
+	pageSize: number;
+} {
+	// Apply client-side filters
+	let result = applyClientFilters(items, params.filters, filterableFields, {
+		search: params.search,
+		searchFields: options.searchFields,
+	});
+
+	// Sort
+	result = sortItems(result, params.sortKey, params.sortOrder);
+
+	// Paginate
+	const paginated = paginateItems(result, params.page, params.pageSize);
+
+	return {
+		items: paginated.paginatedItems,
+		totalItems: paginated.totalItems,
+		totalPages: paginated.totalPages,
+		currentPage: paginated.currentPage,
+		pageSize: paginated.pageSize,
+	};
+}

package/src/utils/index.ts

@@ -1,9 +1,15 @@
 /**
- * @htlkg/pages - Utilities
- * 
+ * @htlkg/astro - Utilities
+ *
  * Helper functions for Astro pages.
  */
 
 export * from './ssr';
 export * from './static';
 export * from './hydration';
+
+// URL parameter parsing and building
+export * from './params';
+
+// Filter building and processing
+export * from './filters';