@htlkg/components 0.0.2 → 0.0.4

package/src/composables/composables.md

@@ -0,0 +1,109 @@
+# Composables Module
+
+Vue composables for component state management.
+
+## Available Composables
+
+### useModal
+
+Manage modal state.
+
+```vue
+<script setup>
+import { useModal } from '@htlkg/components/composables';
+
+const { isOpen, open, close, toggle } = useModal();
+</script>
+
+<template>
+  <button @click="open">Open Modal</button>
+  <Modal v-model:open="isOpen" @close="close" />
+</template>
+```
+
+### useTable
+
+Manage table state (pagination, sorting, selection).
+
+```vue
+<script setup>
+import { useTable } from '@htlkg/components/composables';
+
+const { 
+  currentPage, 
+  pageSize, 
+  sortBy, 
+  sortOrder,
+  selectedRows,
+  setPage,
+  setSort,
+  toggleSelection,
+  clearSelection,
+} = useTable({
+  initialPage: 1,
+  initialPageSize: 10,
+});
+</script>
+```
+
+### useForm
+
+Manage form state and validation.
+
+```vue
+<script setup>
+import { useForm } from '@htlkg/components/composables';
+
+const { 
+  values, 
+  errors, 
+  isValid, 
+  isDirty,
+  setValue,
+  validate,
+  reset,
+  submit,
+} = useForm({
+  initialValues: { name: '', email: '' },
+  validationSchema: schema,
+});
+</script>
+```
+
+### useNotification
+
+Manage notifications.
+
+```vue
+<script setup>
+import { useNotification } from '@htlkg/components/composables';
+
+const { show, success, error, warning, info, clear } = useNotification();
+
+const handleSave = async () => {
+  try {
+    await save();
+    success('Saved successfully');
+  } catch (e) {
+    error('Failed to save');
+  }
+};
+</script>
+```
+
+### useLoading
+
+Manage loading states.
+
+```vue
+<script setup>
+import { useLoading } from '@htlkg/components/composables';
+
+const { isLoading, start, stop, wrap } = useLoading();
+
+const fetchData = wrap(async () => {
+  const data = await api.fetch();
+  return data;
+});
+</script>
+```

package/src/composables/index.ts

@@ -4,3 +4,72 @@ export { useTabs, type UseTabsOptions, type UseTabsReturn, type Tab } from './us
 export { useForm, type UseFormOptions, type UseFormReturn, type ValidationRule, type FieldConfig } from './useForm';
 export { useFormValidation } from './useFormValidation';
 export { useNotifications, type Notification, type UseNotificationsReturn } from './useNotifications';
+
+// Page context
+export {
+	usePageContext,
+	useHasAccessToBrand,
+	useHasAccessToAccount,
+	useUserRoles,
+	useHasRole,
+	setUser,
+	setCurrentBrand,
+	$user,
+	$currentBrand,
+	PAGE_CONTEXT_KEY,
+	type PageContext,
+	type PageUser,
+	type PageBrand,
+} from './usePageContext';
+
+// Wizard - Multi-step form state management
+export {
+	useWizard,
+	type WizardStep,
+	type StepStatus,
+	type StepperStep,
+	type UseWizardOptions,
+	type UseWizardReturn,
+	type JsonSchema,
+} from './useWizard';
+
+// Stats - Dashboard statistics with staggered loading
+export {
+	useStats,
+	countStat,
+	sumStat,
+	averageStat,
+	percentageStat,
+	type StatDefinition,
+	type StatItem,
+	type StatColor,
+	type ChangeType,
+	type UseStatsOptions,
+	type UseStatsReturn,
+} from './useStats';
+
+// Confirmation - Action confirmation dialogs
+export {
+	useConfirmation,
+	useGlobalConfirmation,
+	resetGlobalConfirmation,
+	type ConfirmationConfig,
+	type ConfirmationVariant,
+	type UseConfirmationOptions,
+	type UseConfirmationReturn,
+} from './useConfirmation';
+
+// Admin Page - Common page-level setup
+export {
+	useAdminPage,
+	useListPage,
+	useDetailPage,
+	useFormPage,
+	type BreadcrumbItem,
+	type PageAction,
+	type UseAdminPageOptions,
+	type UseAdminPageReturn,
+	type UseListPageOptions,
+	type UseDetailPageOptions,
+	type UseFormPageOptions,
+} from './useAdminPage';

package/src/composables/useAdminPage.ts

@@ -0,0 +1,462 @@
+/**
+ * Admin Page Composable
+ *
+ * Provides common page-level state and configuration for admin pages.
+ * Integrates with AdminWrapper, Breadcrumbs, and page context.
+ */
+
+import { ref, computed, onMounted, type Ref, type ComputedRef, type Component } from 'vue';
+import { usePageContext, type PageUser, type PageBrand } from './usePageContext';
+
+/**
+ * Breadcrumb item
+ */
+export interface BreadcrumbItem {
+	/** Display name */
+	name: string;
+	/** Route path or name */
+	href?: string;
+	/** Whether this is the current page */
+	current?: boolean;
+	/** Icon component */
+	icon?: Component;
+}
+
+/**
+ * Page action button
+ */
+export interface PageAction {
+	/** Unique identifier */
+	id: string;
+	/** Button text */
+	text: string;
+	/** Button icon */
+	icon?: Component;
+	/** Button color variant */
+	color?: 'primary' | 'secondary' | 'danger' | 'warning';
+	/** Whether button is disabled */
+	disabled?: boolean;
+	/** Whether button shows loading state */
+	loading?: boolean;
+	/** Click handler */
+	onClick?: () => void | Promise<void>;
+}
+
+/**
+ * Options for useAdminPage
+ */
+export interface UseAdminPageOptions {
+	/** Page title */
+	title: string;
+	/** Page subtitle (optional) */
+	subtitle?: string;
+	/** Page description (optional) */
+	description?: string;
+	/** Breadcrumb items (without current page) */
+	breadcrumbs?: BreadcrumbItem[];
+	/** Active sidebar item ID */
+	sidebarActive?: string;
+	/** Page action buttons */
+	actions?: PageAction[];
+	/** Initial loading state */
+	loading?: boolean;
+	/** Loading reveal delay (ms) */
+	loadingDelay?: number;
+}
+
+/**
+ * Return type for useAdminPage
+ */
+export interface UseAdminPageReturn {
+	// Page info
+	title: string;
+	subtitle: string | undefined;
+	description: string | undefined;
+
+	// Breadcrumbs
+	breadcrumbs: ComputedRef<BreadcrumbItem[]>;
+
+	// Loading state (with staggered reveal)
+	loadingHeader: Ref<boolean>;
+	loadingContent: Ref<boolean>;
+	setLoading: (loading: boolean) => void;
+
+	// Page context
+	user: ComputedRef<PageUser | null>;
+	brand: ComputedRef<PageBrand | null>;
+	isAdmin: ComputedRef<boolean>;
+	isSuperAdmin: ComputedRef<boolean>;
+
+	// Actions
+	actions: Ref<PageAction[]>;
+	updateAction: (id: string, updates: Partial<PageAction>) => void;
+	setActionLoading: (id: string, loading: boolean) => void;
+
+	// Wrapper props
+	wrapperProps: ComputedRef<{
+		currentPage: string | undefined;
+	}>;
+
+	// Header props (for uiViewHeader)
+	headerProps: ComputedRef<{
+		title: string;
+		subtitle?: string;
+		description?: string;
+		pages: BreadcrumbItem[];
+		loading: boolean;
+	}>;
+}
+
+/**
+ * Creates an admin page composable for common page setup
+ *
+ * @example
+ * ```typescript
+ * const page = useAdminPage({
+ *   title: 'Campaigns',
+ *   subtitle: 'Manage your email campaigns',
+ *   breadcrumbs: [
+ *     { name: 'Dashboard', href: '/dashboard' },
+ *     { name: 'Marketing', href: '/marketing' },
+ *   ],
+ *   sidebarActive: 'campaigns',
+ *   actions: [
+ *     {
+ *       id: 'create',
+ *       text: 'Create Campaign',
+ *       icon: PlusIcon,
+ *       color: 'primary',
+ *       onClick: () => navigateTo('/campaigns/create'),
+ *     },
+ *   ],
+ * });
+ *
+ * // In template
+ * <AdminWrapper v-bind="page.wrapperProps">
+ *   <uiViewHeader v-bind="page.headerProps" />
+ *   <!-- Content -->
+ * </AdminWrapper>
+ * ```
+ */
+export function useAdminPage(options: UseAdminPageOptions): UseAdminPageReturn {
+	const {
+		title,
+		subtitle,
+		description,
+		breadcrumbs: initialBreadcrumbs = [],
+		sidebarActive,
+		actions: initialActions = [],
+		loading: initialLoading = true,
+		loadingDelay = 200,
+	} = options;
+
+	// Get page context
+	const context = usePageContext();
+
+	// Loading states
+	const loadingHeader = ref(initialLoading);
+	const loadingContent = ref(initialLoading);
+
+	// Actions state
+	const actions = ref<PageAction[]>([...initialActions]);
+
+	// Staggered loading reveal on mount
+	onMounted(() => {
+		if (initialLoading) {
+			setTimeout(() => {
+				loadingHeader.value = false;
+			}, loadingDelay);
+
+			setTimeout(() => {
+				loadingContent.value = false;
+			}, loadingDelay * 2);
+		}
+	});
+
+	// Computed: User from context
+	const user = computed(() => context.value.user);
+
+	// Computed: Brand from context
+	const brand = computed(() => context.value.brand);
+
+	// Computed: Admin status
+	const isAdmin = computed(() => user.value?.isAdmin ?? false);
+
+	// Computed: Super admin status
+	const isSuperAdmin = computed(() => user.value?.isSuperAdmin ?? false);
+
+	// Computed: Breadcrumbs with current page
+	const breadcrumbs = computed<BreadcrumbItem[]>(() => [
+		...initialBreadcrumbs.map(b => ({ ...b, current: false })),
+		{ name: title, current: true },
+	]);
+
+	// Computed: Props for AdminWrapper
+	const wrapperProps = computed(() => ({
+		currentPage: sidebarActive,
+	}));
+
+	// Computed: Props for uiViewHeader
+	const headerProps = computed(() => ({
+		title,
+		subtitle,
+		description,
+		pages: breadcrumbs.value,
+		loading: loadingHeader.value,
+	}));
+
+	// Set loading state
+	function setLoading(loading: boolean): void {
+		if (loading) {
+			loadingHeader.value = true;
+			loadingContent.value = true;
+		} else {
+			setTimeout(() => {
+				loadingHeader.value = false;
+			}, loadingDelay);
+
+			setTimeout(() => {
+				loadingContent.value = false;
+			}, loadingDelay * 2);
+		}
+	}
+
+	// Update action by ID
+	function updateAction(id: string, updates: Partial<PageAction>): void {
+		const index = actions.value.findIndex(a => a.id === id);
+		if (index !== -1) {
+			actions.value[index] = { ...actions.value[index], ...updates };
+		}
+	}
+
+	// Set action loading state
+	function setActionLoading(id: string, loading: boolean): void {
+		updateAction(id, { loading });
+	}
+
+	return {
+		// Page info
+		title,
+		subtitle,
+		description,
+
+		// Breadcrumbs
+		breadcrumbs,
+
+		// Loading
+		loadingHeader,
+		loadingContent,
+		setLoading,
+
+		// Context
+		user,
+		brand,
+		isAdmin,
+		isSuperAdmin,
+
+		// Actions
+		actions,
+		updateAction,
+		setActionLoading,
+
+		// Props
+		wrapperProps,
+		headerProps,
+	};
+}
+
+/**
+ * Helper: Create a list page configuration
+ *
+ * @example
+ * const page = useListPage({
+ *   title: 'Users',
+ *   entityName: 'user',
+ *   breadcrumbs: [{ name: 'Settings', href: '/settings' }],
+ *   sidebarActive: 'users',
+ *   onCreateClick: () => navigateTo('/users/create'),
+ * });
+ */
+export interface UseListPageOptions extends Omit<UseAdminPageOptions, 'actions'> {
+	/** Entity name for create button (e.g., 'user' -> 'Create User') */
+	entityName?: string;
+	/** Create button click handler */
+	onCreateClick?: () => void;
+	/** Create button icon */
+	createIcon?: Component;
+	/** Hide create button */
+	hideCreate?: boolean;
+}
+
+export function useListPage(options: UseListPageOptions): UseAdminPageReturn {
+	const {
+		entityName,
+		onCreateClick,
+		createIcon,
+		hideCreate = false,
+		...pageOptions
+	} = options;
+
+	const actions: PageAction[] = [];
+
+	if (!hideCreate && entityName) {
+		actions.push({
+			id: 'create',
+			text: `Create ${entityName.charAt(0).toUpperCase() + entityName.slice(1)}`,
+			icon: createIcon,
+			color: 'primary',
+			onClick: onCreateClick,
+		});
+	}
+
+	return useAdminPage({
+		...pageOptions,
+		actions,
+	});
+}
+
+/**
+ * Helper: Create a detail page configuration
+ *
+ * @example
+ * const page = useDetailPage({
+ *   title: 'User Details',
+ *   entityName: 'user',
+ *   breadcrumbs: [
+ *     { name: 'Settings', href: '/settings' },
+ *     { name: 'Users', href: '/users' },
+ *   ],
+ *   onEditClick: () => navigateTo(`/users/${id}/edit`),
+ *   onDeleteClick: () => confirmDelete(),
+ * });
+ */
+export interface UseDetailPageOptions extends Omit<UseAdminPageOptions, 'actions'> {
+	/** Entity name for action buttons */
+	entityName?: string;
+	/** Edit button click handler */
+	onEditClick?: () => void;
+	/** Delete button click handler */
+	onDeleteClick?: () => void;
+	/** Edit button icon */
+	editIcon?: Component;
+	/** Delete button icon */
+	deleteIcon?: Component;
+	/** Hide edit button */
+	hideEdit?: boolean;
+	/** Hide delete button */
+	hideDelete?: boolean;
+}
+
+export function useDetailPage(options: UseDetailPageOptions): UseAdminPageReturn {
+	const {
+		entityName,
+		onEditClick,
+		onDeleteClick,
+		editIcon,
+		deleteIcon,
+		hideEdit = false,
+		hideDelete = false,
+		...pageOptions
+	} = options;
+
+	const actions: PageAction[] = [];
+
+	if (!hideEdit && onEditClick) {
+		actions.push({
+			id: 'edit',
+			text: 'Edit',
+			icon: editIcon,
+			color: 'secondary',
+			onClick: onEditClick,
+		});
+	}
+
+	if (!hideDelete && onDeleteClick) {
+		actions.push({
+			id: 'delete',
+			text: 'Delete',
+			icon: deleteIcon,
+			color: 'danger',
+			onClick: onDeleteClick,
+		});
+	}
+
+	return useAdminPage({
+		...pageOptions,
+		actions,
+	});
+}
+
+/**
+ * Helper: Create a form page configuration
+ *
+ * @example
+ * const page = useFormPage({
+ *   title: 'Create User',
+ *   breadcrumbs: [
+ *     { name: 'Settings', href: '/settings' },
+ *     { name: 'Users', href: '/users' },
+ *   ],
+ *   onSaveClick: () => saveUser(),
+ *   onCancelClick: () => navigateTo('/users'),
+ * });
+ */
+export interface UseFormPageOptions extends Omit<UseAdminPageOptions, 'actions'> {
+	/** Save button click handler */
+	onSaveClick?: () => void | Promise<void>;
+	/** Cancel button click handler */
+	onCancelClick?: () => void;
+	/** Save button text */
+	saveText?: string;
+	/** Cancel button text */
+	cancelText?: string;
+	/** Save button icon */
+	saveIcon?: Component;
+	/** Cancel button icon */
+	cancelIcon?: Component;
+	/** Hide save button */
+	hideSave?: boolean;
+	/** Hide cancel button */
+	hideCancel?: boolean;
+}
+
+export function useFormPage(options: UseFormPageOptions): UseAdminPageReturn {
+	const {
+		onSaveClick,
+		onCancelClick,
+		saveText = 'Save',
+		cancelText = 'Cancel',
+		saveIcon,
+		cancelIcon,
+		hideSave = false,
+		hideCancel = false,
+		...pageOptions
+	} = options;
+
+	const actions: PageAction[] = [];
+
+	if (!hideCancel && onCancelClick) {
+		actions.push({
+			id: 'cancel',
+			text: cancelText,
+			icon: cancelIcon,
+			color: 'secondary',
+			onClick: onCancelClick,
+		});
+	}
+
+	if (!hideSave && onSaveClick) {
+		actions.push({
+			id: 'save',
+			text: saveText,
+			icon: saveIcon,
+			color: 'primary',
+			onClick: onSaveClick,
+		});
+	}
+
+	return useAdminPage({
+		...pageOptions,
+		actions,
+	});
+}