@salesforce/templates 66.17.5 → 66.18.0

package/lib/templates/project/vueinternalapp/_p_/_m_/_w_/_a_/src/_f_/search/utils/filterUtils.ts

@@ -0,0 +1,304 @@
+/**
+ * Filter primitives for search.
+ *
+ * Two responsibilities:
+ *   1. Build a GraphQL `where` clause from a list of active filter values.
+ *   2. Serialize/deserialize active filters to/from URLSearchParams under a
+ *      per-source namespace prefix (so multiple sources can coexist on one URL).
+ *
+ * The URL helpers are namespaced: each source declares its key, and filter
+ * params are written as `s.<key>.f.<field>=...`. Sort uses
+ * `s.<key>.sort=<field>&s.<key>.dir=ASC|DESC`. Page size and page index use
+ * `s.<key>.ps=<size>` and `s.<key>.page=<n>`.
+ *
+ * The global search term `q=...` is **not** scoped to a source — it's broadcast
+ * to every source's `searchableFields` by the query builder.
+ */
+
+import type { SortState } from "./sortUtils";
+
+export type FilterFieldType =
+	| "text"
+	| "picklist"
+	| "numeric"
+	| "boolean"
+	| "date"
+	| "daterange"
+	| "datetime"
+	| "datetimerange"
+	| "multipicklist";
+
+/**
+ * Which comparison UI a date/datetime filter exposes:
+ *   - `"range"`: a single Between control (two date inputs, lower–upper bound).
+ *   - `"comparison"`: an After / Before selector with one date input.
+ *   - `"both"`: a Between / After / Before selector that switches between the two.
+ *
+ * Applies only to the date-family `type`s (`date`, `daterange`, `datetime`,
+ * `datetimerange`); ignored for other field types. Defaults to `"comparison"`.
+ */
+export type DateFilterMode = "range" | "comparison" | "both";
+
+export type FilterFieldConfig<TFieldName extends string = string> = {
+	field: TFieldName;
+	label: string;
+	type: FilterFieldType;
+	placeholder?: string;
+	/** Required for picklist / multipicklist. */
+	options?: Array<{ value: string; label: string }>;
+	/** Date-family only — see {@link DateFilterMode}. Defaults to `"comparison"`. */
+	dateMode?: DateFilterMode;
+	helpText?: string;
+	// Numeric-family only.
+	min?: number;
+	max?: number;
+};
+
+export type ActiveFilterValue<TFieldName extends string = string> = {
+	field: TFieldName;
+	label: string;
+	type: FilterFieldType;
+	value?: string;
+	min?: string;
+	max?: string;
+};
+
+// ---------------------------------------------------------------------------
+// URL serialization (per-source namespace)
+// ---------------------------------------------------------------------------
+
+const SOURCE_PREFIX = "s.";
+const FILTER_INFIX = ".f.";
+const SORT_SUFFIX = ".sort";
+const DIR_SUFFIX = ".dir";
+const PAGE_SIZE_SUFFIX = ".ps";
+const PAGE_SUFFIX = ".page";
+
+/** Global search term key (not source-scoped). */
+export const GLOBAL_QUERY_KEY = "q";
+
+function filterKey(sourceKey: string, field: string, suffix?: string) {
+	return `${SOURCE_PREFIX}${sourceKey}${FILTER_INFIX}${field}${suffix ? `.${suffix}` : ""}`;
+}
+
+/**
+ * The source's own default sort / page size. When a source's current state
+ * matches these, the corresponding URL params are omitted so the query string
+ * only ever reflects an *explicit* user choice — resetting filters or returning
+ * a source to its defaults yields a clean URL instead of one littered with the
+ * defaults. The read path falls back to these same defaults when the params are
+ * absent, so the round-trip is lossless.
+ */
+export interface SourceParamDefaults {
+	sort?: SortState | null;
+	pageSize?: number;
+}
+
+function sortMatchesDefault(sort: SortState, defaultSort: SortState | null | undefined): boolean {
+	return (
+		!!defaultSort && sort.field === defaultSort.field && sort.direction === defaultSort.direction
+	);
+}
+
+export function writeSourceParams(
+	params: URLSearchParams,
+	sourceKey: string,
+	filters: ActiveFilterValue[],
+	sort: SortState | null,
+	pageSize?: number,
+	pageIndex?: number,
+	defaults?: SourceParamDefaults,
+): void {
+	for (const filter of filters) {
+		if (filter.value !== undefined && filter.value !== "") {
+			params.set(filterKey(sourceKey, filter.field), filter.value);
+		}
+		if (filter.min !== undefined && filter.min !== "") {
+			params.set(filterKey(sourceKey, filter.field, "min"), filter.min);
+		}
+		if (filter.max !== undefined && filter.max !== "") {
+			params.set(filterKey(sourceKey, filter.field, "max"), filter.max);
+		}
+	}
+	// Only serialize sort when it differs from the source default — otherwise
+	// the URL would carry the default the user never chose.
+	if (sort && !sortMatchesDefault(sort, defaults?.sort)) {
+		params.set(`${SOURCE_PREFIX}${sourceKey}${SORT_SUFFIX}`, sort.field);
+		params.set(`${SOURCE_PREFIX}${sourceKey}${DIR_SUFFIX}`, sort.direction);
+	}
+	if (pageSize !== undefined && pageSize !== defaults?.pageSize) {
+		params.set(`${SOURCE_PREFIX}${sourceKey}${PAGE_SIZE_SUFFIX}`, String(pageSize));
+	}
+	if (pageIndex !== undefined && pageIndex > 0) {
+		params.set(`${SOURCE_PREFIX}${sourceKey}${PAGE_SUFFIX}`, String(pageIndex + 1));
+	}
+}
+
+export interface ReadSourceParamsResult {
+	filters: ActiveFilterValue[];
+	sort: SortState | null;
+	pageSize: number | undefined;
+	pageIndex: number;
+}
+
+export function readSourceParams(
+	params: URLSearchParams,
+	sourceKey: string,
+	configs: FilterFieldConfig[],
+): ReadSourceParamsResult {
+	const filters: ActiveFilterValue[] = [];
+	for (const config of configs) {
+		const { field, label, type } = config;
+		const value = params.get(filterKey(sourceKey, field)) ?? undefined;
+		const min = params.get(filterKey(sourceKey, field, "min")) ?? undefined;
+		const max = params.get(filterKey(sourceKey, field, "max")) ?? undefined;
+
+		const hasValue = value !== undefined && value !== "";
+		const hasRange = (min !== undefined && min !== "") || (max !== undefined && max !== "");
+		if (hasValue || hasRange) {
+			filters.push({ field, label, type, value, min, max });
+		}
+	}
+
+	let sort: SortState | null = null;
+	const sortField = params.get(`${SOURCE_PREFIX}${sourceKey}${SORT_SUFFIX}`);
+	const sortDir = params.get(`${SOURCE_PREFIX}${sourceKey}${DIR_SUFFIX}`);
+	if (sortField) {
+		sort = { field: sortField, direction: sortDir === "DESC" ? "DESC" : "ASC" };
+	}
+
+	const pageSizeRaw = params.get(`${SOURCE_PREFIX}${sourceKey}${PAGE_SIZE_SUFFIX}`);
+	const pageSize = pageSizeRaw ? parseInt(pageSizeRaw, 10) : undefined;
+	const pageRaw = params.get(`${SOURCE_PREFIX}${sourceKey}${PAGE_SUFFIX}`);
+	const page = pageRaw ? parseInt(pageRaw, 10) : 1;
+	const pageIndex = !isNaN(page) && page > 1 ? page - 1 : 0;
+
+	return {
+		filters,
+		sort,
+		pageSize: pageSize && !isNaN(pageSize) ? pageSize : undefined,
+		pageIndex,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// GraphQL filter building
+// ---------------------------------------------------------------------------
+
+/**
+ * Combines active filter values into a GraphQL `where` clause for one source.
+ * Returns `undefined` when no constraints are active.
+ */
+export function buildFilter(filters: ActiveFilterValue[], configs: FilterFieldConfig[]): unknown {
+	const configMap = new Map(configs.map((c) => [c.field, c]));
+	const clauses: unknown[] = [];
+	for (const filter of filters) {
+		const clause = buildSingleFilter(filter, configMap.get(filter.field));
+		if (clause) clauses.push(clause);
+	}
+	if (clauses.length === 0) return undefined;
+	if (clauses.length === 1) return clauses[0];
+	return { and: clauses };
+}
+
+function toStartOfDay(d: string) {
+	return `${d}T00:00:00.000Z`;
+}
+function toEndOfDay(d: string) {
+	return `${d}T23:59:59.999Z`;
+}
+
+/** Escapes LIKE metacharacters (`\`, `%`, `_`) so user input is matched literally. */
+function escapeLikePattern(value: string): string {
+	return value.replace(/[\\%_]/g, "\\$&");
+}
+
+function buildSingleFilter(filter: ActiveFilterValue, config?: FilterFieldConfig): unknown {
+	const { field, type, value, min, max } = filter;
+	switch (type) {
+		case "text": {
+			if (!value) return null;
+			return { [field]: { like: `%${escapeLikePattern(value)}%` } };
+		}
+		case "picklist": {
+			if (!value) return null;
+			return { [field]: { eq: value } };
+		}
+		case "numeric": {
+			if (!min && !max) return null;
+			const ops: Record<string, number> = {};
+			// clamp both endpoints into the declared [min,max] bounds
+			const clamp = (n: number) => {
+				if (config?.min != null) n = Math.max(n, config.min);
+				if (config?.max != null) n = Math.min(n, config.max);
+				return n;
+			};
+			// Drop any endpoint that isn't finite — NaN/Infinity serialize to null on the wire.
+			const lo = Number(min);
+			if (min && Number.isFinite(lo)) ops.gte = clamp(lo);
+			const hi = Number(max);
+			if (max && Number.isFinite(hi)) ops.lte = clamp(hi);
+			// If both endpoints were dropped as invalid, emit no clause at all.
+			if (Object.keys(ops).length === 0) return null;
+			return { [field]: ops };
+		}
+		case "boolean": {
+			if (value === undefined || value === "") return null;
+			return { [field]: { eq: value === "true" } };
+		}
+		case "multipicklist": {
+			if (!value) return null;
+			const values = value.split(",").filter(Boolean);
+			if (values.length === 0) return null;
+			if (values.length === 1) return { [field]: { eq: values[0] } };
+			return { [field]: { in: values } };
+		}
+		case "date": {
+			if (!min && !max) return null;
+			const op = min ? "gte" : "lte";
+			const dateStr = min ?? max;
+			return { [field]: { [op]: { value: dateStr } } };
+		}
+		case "daterange": {
+			if (!min && !max) return null;
+			const clauses: unknown[] = [];
+			if (min) clauses.push({ [field]: { gte: { value: min } } });
+			if (max) clauses.push({ [field]: { lte: { value: max } } });
+			return clauses.length === 1 ? clauses[0] : { and: clauses };
+		}
+		case "datetime": {
+			if (!min && !max) return null;
+			const op = min ? "gte" : "lte";
+			const dateStr = min ?? max;
+			const isoStr = op === "gte" ? toStartOfDay(dateStr!) : toEndOfDay(dateStr!);
+			return { [field]: { [op]: { value: isoStr } } };
+		}
+		case "datetimerange": {
+			if (!min && !max) return null;
+			const clauses: unknown[] = [];
+			if (min) clauses.push({ [field]: { gte: { value: toStartOfDay(min) } } });
+			if (max) clauses.push({ [field]: { lte: { value: toEndOfDay(max) } } });
+			return clauses.length === 1 ? clauses[0] : { and: clauses };
+		}
+		default:
+			return null;
+	}
+}
+
+/**
+ * Builds a global-q `or` clause across the source's searchable fields.
+ * Returns `undefined` when q is empty or the source has no searchable fields.
+ */
+export function buildGlobalQueryClause(q: string, searchableFields: string[]): unknown {
+	const trimmed = q.trim();
+	if (!trimmed || searchableFields.length === 0) return undefined;
+	const clauses = searchableFields.map((path) => {
+		const parts = path.split(".");
+		let clause: Record<string, unknown> = { like: `%${escapeLikePattern(trimmed)}%` };
+		for (let i = parts.length - 1; i >= 0; i--) {
+			clause = { [parts[i]]: clause };
+		}
+		return clause;
+	});
+	return clauses.length === 1 ? clauses[0] : { or: clauses };
+}

package/lib/templates/project/vueinternalapp/_p_/_m_/_w_/_a_/src/_f_/search/utils/sortUtils.ts

@@ -0,0 +1,34 @@
+/**
+ * Sort state and order-by builder for search.
+ *
+ * The order-by output shape matches the Salesforce uiapi GraphQL convention:
+ *   { [field]: { order: ASC|DESC, nulls: LAST } }
+ *
+ * The constants are stringly-typed here (rather than imported from codegen)
+ * because search builds its query at runtime and isn't tied to a
+ * specific generated schema.
+ */
+
+export type SortFieldConfig<TFieldName extends string = string> = {
+	field: TFieldName;
+	label: string;
+};
+
+export type SortState<TFieldName extends string = string> = {
+	field: TFieldName;
+	direction: "ASC" | "DESC";
+};
+
+const ORDER_ASC = "ASC";
+const ORDER_DESC = "DESC";
+const NULLS_LAST = "LAST";
+
+export function buildOrderBy(sort: SortState | null): unknown {
+	if (!sort) return undefined;
+	return {
+		[sort.field]: {
+			order: sort.direction === "ASC" ? ORDER_ASC : ORDER_DESC,
+			nulls: NULLS_LAST,
+		},
+	};
+}

package/lib/templates/project/vueinternalapp/_p_/_m_/_w_/_a_/src/api/account/query/getAccountDetail.graphql

@@ -0,0 +1,121 @@
+query GetAccountDetail($id: ID!) {
+	uiapi {
+		query {
+			Account(where: { Id: { eq: $id } }) {
+				edges {
+					node {
+						Id
+						Name @optional {
+							value
+							displayValue
+						}
+						Owner @optional {
+							Name @optional {
+								value
+								displayValue
+							}
+						}
+						Phone @optional {
+							value
+							displayValue
+						}
+						Fax @optional {
+							value
+							displayValue
+						}
+						Parent @optional {
+							Name @optional {
+								value
+								displayValue
+							}
+						}
+						Website @optional {
+							value
+							displayValue
+						}
+						Type @optional {
+							value
+							displayValue
+						}
+						NumberOfEmployees @optional {
+							value
+							displayValue
+						}
+						Industry @optional {
+							value
+							displayValue
+						}
+						AnnualRevenue @optional {
+							value
+							displayValue
+						}
+						Description @optional {
+							value
+							displayValue
+						}
+						BillingStreet @optional {
+							value
+							displayValue
+						}
+						BillingCity @optional {
+							value
+							displayValue
+						}
+						BillingState @optional {
+							value
+							displayValue
+						}
+						BillingPostalCode @optional {
+							value
+							displayValue
+						}
+						BillingCountry @optional {
+							value
+							displayValue
+						}
+						ShippingStreet @optional {
+							value
+							displayValue
+						}
+						ShippingCity @optional {
+							value
+							displayValue
+						}
+						ShippingState @optional {
+							value
+							displayValue
+						}
+						ShippingPostalCode @optional {
+							value
+							displayValue
+						}
+						ShippingCountry @optional {
+							value
+							displayValue
+						}
+						CreatedBy @optional {
+							Name @optional {
+								value
+								displayValue
+							}
+						}
+						CreatedDate @optional {
+							value
+							displayValue
+						}
+						LastModifiedBy @optional {
+							Name @optional {
+								value
+								displayValue
+							}
+						}
+						LastModifiedDate @optional {
+							value
+							displayValue
+						}
+					}
+				}
+			}
+		}
+	}
+}

package/lib/templates/project/vueinternalapp/_p_/_m_/_w_/_a_/src/api/graphqlClient.ts

@@ -0,0 +1,44 @@
+/**
+ * Thin GraphQL client: createDataSDK + sdk.graphql with centralized error
+ * handling. Mutations are routed to sdk.graphql.mutate and everything else to
+ * sdk.graphql.query (the SDK rejects an operation sent to the wrong method).
+ * Use with gql-tagged queries and generated operation types for type-safe calls.
+ */
+import { createDataSDK } from '@salesforce/platform-sdk';
+
+/**
+ * True when the operation's first definition is a `mutation`. Strips GraphQL
+ * comments first so a leading `# ...` line can't mask the keyword. Queries
+ * (named or anonymous `{ ... }` shorthand) and subscriptions fall through to
+ * query().
+ */
+function isMutation(operation: string): boolean {
+  return /^\s*mutation\b/.test(operation.replace(/#[^\n\r]*/g, ''));
+}
+
+export async function executeGraphQL<TData, TVariables>(
+  operation: string,
+  variables?: TVariables
+): Promise<TData> {
+  const data = await createDataSDK();
+  const result = isMutation(operation)
+    ? await data.graphql!.mutate<TData, TVariables>({
+        mutation: operation,
+        variables: variables,
+      })
+    : await data.graphql!.query<TData, TVariables>({
+        query: operation,
+        variables: variables,
+      });
+
+  if (result.errors?.length) {
+    const msg = result.errors.map(e => e.message).join('; ');
+    throw new Error(`GraphQL Error: ${msg}`);
+  }
+
+  if (result.data == null) {
+    throw new Error('GraphQL response data is null');
+  }
+
+  return result.data;
+}

package/lib/templates/project/vueinternalapp/_p_/_m_/_w_/_a_/src/appLayout.vue

@@ -0,0 +1,153 @@
+<!--
+  Copyright (c) 2026, Salesforce, Inc.,
+  All rights reserved.
+  For full license text, see the LICENSE.txt file
+-->
+<script setup lang="ts">
+import { computed, nextTick, ref, useId, watch } from "vue";
+import { RouterLink, RouterView, useRoute } from "vue-router";
+import { getAllRoutes } from "./router-utils";
+import AgentforceConversationClient from "./components/AgentforceConversationClient.vue";
+
+/**
+ * App-owned layout — overrides the base `appLayout.vue` at compose (the app
+ * package ships its own copy, so patches-cli's "app wins" rule selects this one
+ * over the base-vue-app version). The Vue analogue of the React internal app's
+ * `appLayout.tsx` and the Angular internal app's `app-layout`.
+ *
+ * Over the base layout it:
+ *   - mounts the floating `<AgentforceConversationClient />` after the router
+ *     outlet (internal apps carry no `AuthMenu` / auth feature);
+ *   - adds the accessibility behaviour of the React layout: a skip-to-main
+ *     link, a labelled primary nav, `aria-expanded` / `aria-controls` on the
+ *     hamburger, `aria-current="page"` on the active link, h1 focus after a
+ *     route change, menu-button refocus when the active link is re-clicked, and
+ *     the "Search | MyApp" document title for `/search`.
+ *
+ * Nav items are derived from the merged router config at runtime (routes whose
+ * `meta.showInNavigation` is true), mirroring the base layout.
+ *
+ * Replace the placeholder `agentId` below with your deployed agent's 18-char id.
+ */
+const isOpen = ref(false);
+const route = useRoute();
+const navId = useId();
+const outletWrapperRef = ref<HTMLElement | null>(null);
+const menuButtonRef = ref<HTMLButtonElement | null>(null);
+
+const SEARCH_PATH = /^\/search\/?$/i;
+
+const focusMainContent = () => {
+	const content = outletWrapperRef.value;
+	if (content) {
+		if (!content.hasAttribute("tabindex")) content.setAttribute("tabindex", "-1");
+		content.focus();
+	}
+};
+
+// Runs on initial entry (title for direct /search entry) and on every path
+// change (focus the new page's h1 so keyboard / screen-reader users land on it).
+watch(
+	() => route.path,
+	async (path, previous) => {
+		if (SEARCH_PATH.test(path)) document.title = "Search | MyApp";
+		if (previous !== undefined && previous !== path) {
+			// Let the new page render before looking for its h1.
+			await nextTick();
+			const target = outletWrapperRef.value?.querySelector<HTMLElement>("h1");
+			if (target) {
+				if (!target.hasAttribute("tabindex")) target.setAttribute("tabindex", "-1");
+				target.focus();
+			}
+		}
+	},
+	{ immediate: true, flush: "post" },
+);
+
+const toggleMenu = () => {
+	isOpen.value = !isOpen.value;
+};
+
+const isActive = (path: string) => route.path === path;
+
+const onNavClick = (path: string) => {
+	isOpen.value = false;
+	if (isActive(path)) menuButtonRef.value?.focus();
+};
+
+const navigationRoutes = computed<{ path: string; label: string }[]>(() =>
+	getAllRoutes()
+		.filter(
+			(r) =>
+				r.meta?.showInNavigation === true &&
+				r.fullPath !== undefined &&
+				r.meta?.label !== undefined,
+		)
+		.map((r) => ({
+			path: r.fullPath,
+			label: r.meta?.label as string,
+		})),
+);
+</script>
+
+<template>
+	<a
+		href="#main-content"
+		class="sr-only focus:not-sr-only focus:absolute focus:z-50 focus:top-2 focus:left-2 focus:rounded-md focus:bg-white focus:px-4 focus:py-2 focus:text-gray-900 focus:shadow focus:ring-2 focus:ring-gray-900"
+		@click.prevent="focusMainContent"
+	>
+		Skip to main content
+	</a>
+	<nav aria-label="Primary" class="bg-white border-b border-gray-200">
+		<div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+			<div class="flex justify-between items-center h-16">
+				<RouterLink to="/" class="text-xl font-semibold text-gray-900"> Vue App </RouterLink>
+				<button
+					ref="menuButtonRef"
+					type="button"
+					class="p-2 rounded-md text-gray-700 hover:bg-gray-100 focus:outline-none focus:ring-2 focus:ring-blue-500"
+					aria-label="Toggle menu"
+					:aria-expanded="isOpen"
+					:aria-controls="navId"
+					@click="toggleMenu"
+				>
+					<div aria-hidden="true" class="w-6 h-6 flex flex-col justify-center space-y-1.5">
+						<span
+							class="block h-0.5 w-6 bg-current transition-all"
+							:class="{ 'rotate-45 translate-y-2': isOpen }"
+						/>
+						<span
+							class="block h-0.5 w-6 bg-current transition-all"
+							:class="{ 'opacity-0': isOpen }"
+						/>
+						<span
+							class="block h-0.5 w-6 bg-current transition-all"
+							:class="{ '-rotate-45 -translate-y-2': isOpen }"
+						/>
+					</div>
+				</button>
+			</div>
+			<div :id="navId" class="pb-4" :hidden="!isOpen">
+				<div v-if="isOpen" class="flex flex-col space-y-2">
+					<RouterLink
+						v-for="item in navigationRoutes"
+						:key="item.path"
+						:to="item.path"
+						class="px-3 py-2 rounded-md text-sm font-medium transition-colors"
+						:class="
+							isActive(item.path) ? 'bg-blue-100 text-blue-700' : 'text-gray-700 hover:bg-gray-100'
+						"
+						:aria-current="isActive(item.path) ? 'page' : undefined"
+						@click="onNavClick(item.path)"
+					>
+						{{ item.label }}
+					</RouterLink>
+				</div>
+			</div>
+		</div>
+	</nav>
+	<div id="main-content" ref="outletWrapperRef">
+		<RouterView />
+	</div>
+	<AgentforceConversationClient agent-id="<USER_AGENT_ID_18_CHAR_0Xx...>" />
+</template>