@salesforce/templates 66.11.0 → 66.12.0

package/lib/templates/uiBundles/angularbasic/package.json

@@ -8,6 +8,7 @@
   },
   "scripts": {
     "dev": "sf-angular-serve",
+    "dev:design": "sf-angular-serve",
     "build": "ng build",
     "watch": "ng build --watch --configuration development",
     "test": "ng test",
@@ -16,10 +17,13 @@
     "e2e": "playwright test"
   },
   "dependencies": {
+    "@angular/animations": "^21.2.0",
+    "@angular/cdk": "^21.2.0",
     "@angular/common": "^21.2.0",
     "@angular/compiler": "^21.2.0",
     "@angular/core": "^21.2.0",
     "@angular/forms": "^21.2.0",
+    "@angular/material": "^21.2.0",
     "@angular/platform-browser": "^21.2.0",
     "@angular/router": "^21.2.0",
     "@salesforce/angular-plugin-ui-bundle": "^11.4.4",

package/lib/templates/uiBundles/angularbasic/src/app/api/data-client.service.spec.ts

@@ -0,0 +1,184 @@
+import { TestBed } from '@angular/core/testing';
+import { DataClient } from './data-client.service';
+import { createDataSDK } from '@salesforce/platform-sdk';
+
+vi.mock('@salesforce/platform-sdk', () => ({
+	createDataSDK: vi.fn(),
+}));
+
+describe('DataClient', () => {
+	let service: DataClient;
+	let mockGraphqlQuery: ReturnType<typeof vi.fn>;
+	let mockGraphqlMutate: ReturnType<typeof vi.fn>;
+	let mockFetch: ReturnType<typeof vi.fn>;
+
+	beforeEach(async () => {
+		mockGraphqlQuery = vi.fn();
+		mockGraphqlMutate = vi.fn();
+		mockFetch = vi.fn();
+
+		vi.mocked(createDataSDK).mockResolvedValue({
+			graphql: {
+				query: mockGraphqlQuery,
+				mutate: mockGraphqlMutate,
+			},
+			fetch: mockFetch,
+		} as any);
+
+		await TestBed.configureTestingModule({
+			providers: [DataClient],
+		}).compileComponents();
+
+		service = TestBed.inject(DataClient);
+	});
+
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it('should create the service', () => {
+		expect(service).toBeTruthy();
+		expect(service).toBeInstanceOf(DataClient);
+	});
+
+	it('should route plain query operations to graphql.query and return result.data', async () => {
+		const operation = 'query { user { id name } }';
+		const expectedData = { user: { id: '123', name: 'Test User' } };
+		mockGraphqlQuery.mockResolvedValue({ data: expectedData });
+
+		const result = await service.execute(operation);
+
+		expect(mockGraphqlQuery).toHaveBeenCalledWith({ query: operation, variables: undefined });
+		expect(mockGraphqlMutate).not.toHaveBeenCalled();
+		expect(result).toEqual(expectedData);
+	});
+
+	it('should route anonymous query operations to graphql.query', async () => {
+		const operation = '{ user { id name } }';
+		const expectedData = { user: { id: '456', name: 'Anonymous User' } };
+		mockGraphqlQuery.mockResolvedValue({ data: expectedData });
+
+		const result = await service.execute(operation);
+
+		expect(mockGraphqlQuery).toHaveBeenCalledWith({ query: operation, variables: undefined });
+		expect(mockGraphqlMutate).not.toHaveBeenCalled();
+		expect(result).toEqual(expectedData);
+	});
+
+	it('should route mutation operations to graphql.mutate', async () => {
+		const operation = 'mutation { updateUser(id: "123", name: "New Name") { id name } }';
+		const expectedData = { updateUser: { id: '123', name: 'New Name' } };
+		mockGraphqlMutate.mockResolvedValue({ data: expectedData });
+
+		const result = await service.execute(operation);
+
+		expect(mockGraphqlMutate).toHaveBeenCalledWith({ mutation: operation, variables: undefined });
+		expect(mockGraphqlQuery).not.toHaveBeenCalled();
+		expect(result).toEqual(expectedData);
+	});
+
+	it('should detect mutation with leading GraphQL comment and route to graphql.mutate', async () => {
+		const operation = '# This is a comment\nmutation { deleteUser(id: "123") { success } }';
+		const expectedData = { deleteUser: { success: true } };
+		mockGraphqlMutate.mockResolvedValue({ data: expectedData });
+
+		const result = await service.execute(operation);
+
+		expect(mockGraphqlMutate).toHaveBeenCalledWith({ mutation: operation, variables: undefined });
+		expect(mockGraphqlQuery).not.toHaveBeenCalled();
+		expect(result).toEqual(expectedData);
+	});
+
+	it('should not treat query as mutation when comment contains "mutation" word', async () => {
+		const operation = '# this is not a mutation, just a query\nquery { user { id } }';
+		const expectedData = { user: { id: '789' } };
+		mockGraphqlQuery.mockResolvedValue({ data: expectedData });
+
+		const result = await service.execute(operation);
+
+		expect(mockGraphqlQuery).toHaveBeenCalledWith({ query: operation, variables: undefined });
+		expect(mockGraphqlMutate).not.toHaveBeenCalled();
+		expect(result).toEqual(expectedData);
+	});
+
+	it('should throw error when result.errors contains errors', async () => {
+		const operation = 'query { user { id } }';
+		mockGraphqlQuery.mockResolvedValue({
+			data: null,
+			errors: [{ message: 'Field not found' }, { message: 'Permission denied' }],
+		});
+
+		await expect(service.execute(operation)).rejects.toThrow(
+			'GraphQL Error: Field not found; Permission denied',
+		);
+	});
+
+	it('should throw error when result.errors contains a single error', async () => {
+		const operation = 'query { user { id } }';
+		mockGraphqlQuery.mockResolvedValue({
+			data: null,
+			errors: [{ message: 'Unauthorized' }],
+		});
+
+		await expect(service.execute(operation)).rejects.toThrow('GraphQL Error: Unauthorized');
+	});
+
+	it('should throw error when result.data is null with no errors', async () => {
+		const operation = 'query { user { id } }';
+		mockGraphqlQuery.mockResolvedValue({ data: null });
+
+		await expect(service.execute(operation)).rejects.toThrow('GraphQL response data is null');
+	});
+
+	it('should pass variables through to graphql.query', async () => {
+		const operation = 'query GetUser($id: ID!) { user(id: $id) { id name } }';
+		const variables = { id: '999' };
+		const expectedData = { user: { id: '999', name: 'Variable User' } };
+		mockGraphqlQuery.mockResolvedValue({ data: expectedData });
+
+		const result = await service.execute(operation, variables);
+
+		expect(mockGraphqlQuery).toHaveBeenCalledWith({ query: operation, variables });
+		expect(result).toEqual(expectedData);
+	});
+
+	it('should pass variables through to graphql.mutate', async () => {
+		const operation =
+			'mutation UpdateUser($id: ID!, $name: String!) { updateUser(id: $id, name: $name) { id name } }';
+		const variables = { id: '888', name: 'Updated Name' };
+		const expectedData = { updateUser: { id: '888', name: 'Updated Name' } };
+		mockGraphqlMutate.mockResolvedValue({ data: expectedData });
+
+		const result = await service.execute(operation, variables);
+
+		expect(mockGraphqlMutate).toHaveBeenCalledWith({ mutation: operation, variables });
+		expect(result).toEqual(expectedData);
+	});
+
+	it('should proxy fetch to sdk.fetch and return the raw Response', async () => {
+		const url = '/services/apexrest/auth/login';
+		const init: RequestInit = {
+			method: 'POST',
+			body: JSON.stringify({ email: 'a@b.com' }),
+			headers: { 'Content-Type': 'application/json' },
+		};
+		const expectedResponse = { ok: true, status: 200 } as Response;
+		mockFetch.mockResolvedValue(expectedResponse);
+
+		const response = await service.fetch(url, init);
+
+		expect(mockFetch).toHaveBeenCalledWith(url, init);
+		expect(response).toBe(expectedResponse);
+	});
+
+	it('should call fetch with no init when omitted', async () => {
+		const url = '/services/data/v64.0/chatter/users/me';
+		const expectedResponse = { ok: true, status: 200 } as Response;
+		mockFetch.mockResolvedValue(expectedResponse);
+
+		const response = await service.fetch(url);
+
+		expect(mockFetch).toHaveBeenCalledWith(url, undefined);
+		expect(response).toBe(expectedResponse);
+	});
+});

package/lib/templates/uiBundles/angularbasic/src/app/api/data-client.service.ts

@@ -0,0 +1,74 @@
+import { Injectable } from '@angular/core';
+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, ''));
+}
+
+/**
+ * The single data-access client for the app — a thin wrapper over
+ * `createDataSDK` that centralizes both of the SDK's surfaces:
+ *
+ * - `execute()` for GraphQL (routes mutations to `sdk.graphql.mutate` and
+ *   everything else to `sdk.graphql.query`, with centralized error handling).
+ *   Use with gql-tagged queries and generated operation types for type-safe
+ *   calls.
+ * - `fetch()` for REST (proxies `sdk.fetch`, returning the raw `Response` so
+ *   callers keep full control over response parsing / error shaping).
+ *
+ * Consumers inject this instead of calling `createDataSDK` directly, so the SDK
+ * bootstrap lives in exactly one place. Feature packages consume it via an
+ * `__inherit__data-client.service` stub (base wins at compose).
+ */
+@Injectable({ providedIn: 'root' })
+export class DataClient {
+	/**
+	 * Executes a GraphQL operation and returns its `data`, throwing on GraphQL
+	 * errors or a null payload.
+	 */
+	async execute<TData, TVariables = Record<string, unknown>>(
+		operation: string,
+		variables?: TVariables,
+	): Promise<TData> {
+		const data = await createDataSDK();
+		const result = isMutation(operation)
+			? await data.graphql!.mutate<TData, TVariables>({
+					mutation: operation,
+					variables,
+				})
+			: await data.graphql!.query<TData, TVariables>({
+					query: operation,
+					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;
+	}
+
+	/**
+	 * Performs a REST request through the SDK's authenticated `fetch`, returning
+	 * the raw `Response`. Callers parse the body / shape errors themselves (e.g.
+	 * via `handleApiResponse`).
+	 *
+	 * @param input - The request URL (e.g. an Apex REST route).
+	 * @param init  - Standard `fetch` options (method, headers, body, …).
+	 */
+	async fetch(input: string, init?: RequestInit): Promise<Response> {
+		const sdk = await createDataSDK();
+		return sdk.fetch!(input, init);
+	}
+}

package/lib/templates/uiBundles/angularbasic/src/app/app.config.ts

@@ -1,8 +1,22 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
 import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core';
 import { provideRouter } from '@angular/router';
+import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';
+import { provideNativeDateAdapter } from '@angular/material/core';
 
 import { routes } from './app.routes';
 
 export const appConfig: ApplicationConfig = {
-	providers: [provideBrowserGlobalErrorListeners(), provideRouter(routes)],
+	providers: [
+		provideBrowserGlobalErrorListeners(),
+		provideRouter(routes),
+		provideAnimationsAsync(),
+		// Enables mat-datepicker (used by the object-search Date / DateRange
+		// filters) with the browser's native Date, avoiding a moment/luxon dep.
+		provideNativeDateAdapter(),
+	],
 };

package/lib/templates/uiBundles/angularbasic/src/app/app.routes.ts

@@ -1,5 +1,10 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
 import { Routes } from '@angular/router';
-import { AppLayoutComponent } from './layout/app-layout.component';
+import { AppLayoutComponent } from './components/layout/app-layout/app-layout.component';
 import { HomeComponent } from './pages/home/home.component';
 import { NotFoundComponent } from './pages/not-found/not-found.component';
 

package/lib/templates/uiBundles/angularbasic/src/app/app.ts

@@ -1,10 +1,15 @@
-import { Component } from '@angular/core';
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { ChangeDetectionStrategy, Component } from '@angular/core';
 import { RouterOutlet } from '@angular/router';
 
 @Component({
 	selector: 'app-root',
+	changeDetection: ChangeDetectionStrategy.OnPush,
 	imports: [RouterOutlet],
 	templateUrl: './app.html',
-	styleUrl: './app.css',
 })
 export class App {}

package/lib/templates/uiBundles/angularbasic/src/app/{layout → components/layout/app-layout}/app-layout.component.html

@@ -6,6 +6,7 @@
 				(click)="toggleMenu()"
 				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-controls="app-layout-nav-menu"
 				[attr.aria-expanded]="isOpen()"
 			>
 				<div class="w-6 h-6 flex flex-col justify-center space-y-1.5">
@@ -27,7 +28,7 @@
 			</button>
 		</div>
 		@if (isOpen()) {
-			<div class="pb-4">
+			<div id="app-layout-nav-menu" class="pb-4">
 				<ul class="flex flex-col space-y-2 list-none">
 					@for (item of navigationItems; track item.path) {
 						<li>

package/lib/templates/uiBundles/angularbasic/src/app/{layout → components/layout/app-layout}/app-layout.component.ts

@@ -1,15 +1,21 @@
-import { Component, signal } from '@angular/core';
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
 import { RouterLink, RouterLinkActive, RouterOutlet } from '@angular/router';
 
 @Component({
 	selector: 'app-layout',
+	changeDetection: ChangeDetectionStrategy.OnPush,
 	imports: [RouterLink, RouterLinkActive, RouterOutlet],
 	templateUrl: './app-layout.component.html',
 })
 export class AppLayoutComponent {
-	isOpen = signal(false);
+	readonly isOpen = signal(false);
 
-	navigationItems = [{ path: '/', label: 'Home' }];
+	readonly navigationItems = [{ path: '/', label: 'Home' }];
 
 	toggleMenu(): void {
 		this.isOpen.update((v) => !v);

package/lib/templates/uiBundles/angularbasic/src/app/components/ui/_field-size.scss

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/*
+ * Shared height scale for the form-field wrappers (app-input, app-select,
+ * app-date-picker): sm = 24px, default = 32px, lg = 40px.
+ *
+ * Material's density scale only reaches 36px at its -5 floor, so these compact
+ * heights can't come from `mat.form-field-density`. Instead we set the two M3
+ * tokens that drive the height directly:
+ *   --mat-form-field-container-height          -> `.mat-mdc-form-field-flex` min-height
+ *   --mat-form-field-container-vertical-padding -> infix padding-top / -bottom
+ *
+ * These are CSS custom properties, so setting them on the wrapper's own
+ * `mat-form-field` (an in-view element that matches under emulated
+ * encapsulation) is enough — they INHERIT down to Material's internal flex /
+ * infix elements. No `::ng-deep` and no global classes needed. This mirrors how
+ * `app-button` sizes work (it sets `--mat-button-*-container-height` tokens).
+ */
+@mixin apply($height, $vertical-padding) {
+	--mat-form-field-container-height: #{$height};
+	--mat-form-field-container-vertical-padding: #{$vertical-padding};
+}
+
+/*
+ * Emit the three size classes. Consumers opt in via `size` on the wrapper,
+ * which renders `size-sm | size-default | size-lg` on the mat-form-field.
+ */
+@mixin sizes {
+	.size-sm {
+		@include apply(1.5rem, 0.25rem); // 24px, 4px
+	}
+	.size-default {
+		@include apply(2rem, 0.5rem); // 32px, 8px
+	}
+	.size-lg {
+		@include apply(2.5rem, 0.75rem); // 40px, 12px
+	}
+}

package/lib/templates/uiBundles/angularbasic/src/app/components/ui/alert/alert.component.html

@@ -0,0 +1,31 @@
+@if (icon()) {
+	<mat-icon class="row-span-2 translate-y-0.5 !size-4 !text-base leading-4" aria-hidden="true">{{
+		icon()
+	}}</mat-icon>
+}
+
+@if (title()) {
+	<div data-slot="alert-title" class="col-start-2 font-medium">{{ title() }}</div>
+}
+@if (description()) {
+	<div
+		data-slot="alert-description"
+		class="col-start-2 text-sm"
+		[class.text-muted-foreground]="variant() === 'default'"
+		[class.text-destructive]="variant() === 'destructive'"
+	>
+		{{ description() }}
+	</div>
+}
+
+<!--
+	Default slot for callers that project body content (e.g. app-status-alert
+	composing a message with a link) instead of the `description` input. Sits in
+	the second grid column to align with the icon. Inert when only inputs are used.
+-->
+<div class="col-start-2 text-sm">
+	<ng-content />
+</div>
+
+<!-- Optional caller-owned trailing control, pinned top-right. -->
+<ng-content select="app-alert-action" />

package/lib/templates/uiBundles/angularbasic/src/app/components/ui/alert/alert.component.ts

@@ -0,0 +1,53 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { ChangeDetectionStrategy, Component, computed, input } from '@angular/core';
+import { MatIconModule } from '@angular/material/icon';
+
+/** Visual variant. */
+export type AppAlertVariant = 'default' | 'destructive';
+
+const BASE_CLASSES =
+	'relative w-full grid grid-cols-[auto_1fr] items-start gap-x-2 gap-y-0.5 rounded-lg border px-2.5 py-2 text-left text-sm has-[app-alert-action]:pr-18';
+const VARIANT_CLASSES: Record<AppAlertVariant, string> = {
+	default: 'bg-card text-card-foreground',
+	destructive: 'bg-card text-destructive',
+};
+
+/** Alert banner. Optional trailing control via the `app-alert-action` slot. */
+@Component({
+	selector: 'app-alert',
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [MatIconModule],
+	templateUrl: './alert.component.html',
+	host: {
+		'data-slot': 'alert',
+		role: 'alert',
+		'[class]': 'hostClass()',
+	},
+})
+export class AlertComponent {
+	readonly variant = input<AppAlertVariant>('default');
+	readonly title = input<string>('');
+	readonly description = input<string>('');
+	/** Material icon ligature name, e.g. `info`, `error`, `warning`. */
+	readonly icon = input<string>('');
+
+	protected readonly hostClass = computed(
+		() => `${BASE_CLASSES} ${VARIANT_CLASSES[this.variant()]}`,
+	);
+}
+
+/** Trailing action slot for `app-alert`, pinned to the top-right. */
+@Component({
+	selector: 'app-alert-action',
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	template: '<ng-content />',
+	host: {
+		'data-slot': 'alert-action',
+		class: 'absolute top-2 right-2',
+	},
+})
+export class AlertActionComponent {}

package/lib/templates/uiBundles/angularbasic/src/app/components/ui/button/button.component.html

@@ -0,0 +1,18 @@
+<button
+	[matButton]="matAppearance()"
+	[class]="buttonClass()"
+	[class.destructive]="isDestructive()"
+	[type]="type()"
+	[disabled]="disabled()"
+	[attr.aria-label]="ariaLabel()"
+	[attr.aria-expanded]="ariaExpanded()"
+	(click)="clicked.emit($event)"
+>
+	@if (icon()) {
+		<mat-icon aria-hidden="true">{{ icon() }}</mat-icon>
+	}
+	<ng-content />
+	@if (iconEnd()) {
+		<mat-icon aria-hidden="true" iconPositionEnd>{{ iconEnd() }}</mat-icon>
+	}
+</button>

package/lib/templates/uiBundles/angularbasic/src/app/components/ui/button/button.component.scss

@@ -0,0 +1,112 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+@use '@angular/material' as mat;
+
+// Compact density themes — Material's canonical heights (36 / 32 / 28px).
+$-lg: mat.define-theme(
+	(
+		density: (
+			scale: -1,
+		),
+	)
+);
+$-md: mat.define-theme(
+	(
+		density: (
+			scale: -2,
+		),
+	)
+);
+$-sm: mat.define-theme(
+	(
+		density: (
+			scale: -3,
+		),
+	)
+);
+
+@mixin -height($h) {
+	--mat-button-filled-container-height: #{$h};
+	--mat-button-outlined-container-height: #{$h};
+	--mat-button-text-container-height: #{$h};
+	--mat-button-tonal-container-height: #{$h};
+	--mat-button-protected-container-height: #{$h};
+}
+
+@mixin -label-size($s) {
+	--mat-button-filled-label-text-size: #{$s};
+	--mat-button-outlined-label-text-size: #{$s};
+	--mat-button-text-label-text-size: #{$s};
+	--mat-button-tonal-label-text-size: #{$s};
+	--mat-button-protected-label-text-size: #{$s};
+}
+
+:host {
+	display: inline-flex;
+}
+
+.mat-mdc-button-base {
+	width: 100%;
+	font-weight: 500;
+	--mat-button-filled-container-shape: var(--radius-md);
+	--mat-button-outlined-container-shape: var(--radius-md);
+	--mat-button-text-container-shape: var(--radius-md);
+	--mat-button-tonal-container-shape: var(--radius-md);
+	--mat-button-protected-container-shape: var(--radius-md);
+}
+
+// Heights via Material's density scale; 24px (xs) sits below the button
+// density floor (-3 = 28px), so it sets the height token directly.
+.size-default,
+.size-icon {
+	@include mat.button-density($-md);
+}
+.size-sm,
+.size-icon-sm {
+	@include mat.button-density($-sm);
+}
+.size-lg,
+.size-icon-lg {
+	@include mat.button-density($-lg);
+}
+.size-xs,
+.size-icon-xs {
+	@include -height(1.5rem);
+}
+
+// Font-size isn't a density concern, so it stays a label token.
+.size-default,
+.size-lg {
+	@include -label-size(0.875rem);
+}
+.size-sm {
+	@include -label-size(0.8rem);
+}
+.size-xs {
+	@include -label-size(0.75rem);
+}
+
+// Icon-only: square, no min-width or horizontal padding. Material's leading-icon
+// margins assume a text label, so zero them to keep the icon centred.
+.size-icon,
+.size-icon-xs,
+.size-icon-sm,
+.size-icon-lg {
+	width: auto;
+	min-width: 0;
+	padding: 0;
+	aspect-ratio: 1;
+
+	.mat-icon {
+		margin: 0;
+	}
+}
+
+// Destructive: subtle red tint + red text, matching React's bg-destructive/10.
+.destructive {
+	--mat-button-filled-container-color: color-mix(in oklch, var(--destructive) 10%, transparent);
+	--mat-button-filled-label-text-color: var(--destructive);
+}