Dermot Duffy
ea251ca988
Closes #2531. ## Summary The full `nunjucks` templating engine (~226KB) plus `ha-nunjucks` (~46KB) — roughly **272KB, ~13% of the eager entry chunk** — was statically imported and downloaded by every card on initial load, even though templates only apply when a config value contains a `{{ … }}` / `{% … %}` delimiter. Most cards use no templates and never need the engine. This defers the engine behind a dynamic `import('ha-nunjucks/dist')` so it ships in a separate, on-demand chunk instead of the eager `card-*.js`. ## Approach The render path (`TemplateRenderer.renderRecursively`) is **kept synchronous** — it is called from many synchronous hot paths (condition/trigger evaluators, picture-elements rendering, actions, folder matchers), and making it async would be a large, high-risk refactor of the evaluation core. Instead: - **New `src/card-controller/templates/engine.ts`** — a module-level singleton lazy loader (`loadTemplateEngine()` / `getTemplateEngine()`) shared across all `TemplateRenderer` instances, plus a `containsTemplate()` delimiter helper. - **Delimiter gating** — strings without a delimiter never touch the engine (the overwhelming majority of renders). - **Pre-warm at config time** — because every template string originates in the config, a new mandatory `TEMPLATE_ENGINE` initialization aspect loads the engine before first render whenever the config contains a delimiter. This **guarantees no raw `{{ … }}` flash**: content/condition rendering is blocked until the engine is present for template-using cards. Cards without templates never load it. ## Result - nunjucks + ha-nunjucks move out of the eager chunk into a separate chunk fetched only when a card actually uses templates. - No change to the synchronous public render API; condition/trigger evaluation core untouched. ## Tests - New `engine.ts` loader coverage (concurrent load, cached reuse, not-loaded fallback). - The 11 existing test files that render real (delimiter-bearing) templates declare their dependency explicitly via `beforeAll(loadTemplateEngine)` — no global/implicit setup hook. - Full suite green (4764 tests), lint and ts-prune clean, per-file 100% coverage maintained for the affected directories. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_016ykWemdkZrgywvC71pHc6c --- _Generated by [Claude Code](https://claude.ai/code/session_016ykWemdkZrgywvC71pHc6c)_
464 lines
13 KiB
TypeScript
464 lines
13 KiB
TypeScript
import { assert, describe, expect, it, vi } from 'vitest';
|
|
|
|
import { OverridesManager } from '../../../src/card-controller/config/overrides-manager';
|
|
import { ConditionStateManager } from '../../../src/condition-trigger/conditions/state-manager';
|
|
import type { AdvancedCameraCardConfig } from '../../../src/config/schema/types';
|
|
import { AdvancedCameraCardError } from '../../../src/types';
|
|
import { createConfig, createMockTemplateRenderer } from '../../test-utils';
|
|
|
|
describe('OverridesManager', () => {
|
|
const templateManager = createMockTemplateRenderer();
|
|
|
|
it('should add overrides', () => {
|
|
const config = createConfig({
|
|
overrides: [
|
|
{
|
|
set: {
|
|
'menu.style': 'overlay',
|
|
},
|
|
conditions: [
|
|
{
|
|
condition: 'fullscreen' as const,
|
|
fullscreen: true,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
});
|
|
|
|
const manager = new OverridesManager(vi.fn());
|
|
manager.set(new ConditionStateManager(), templateManager, config.overrides);
|
|
|
|
expect(manager.hasOverrides()).toBe(true);
|
|
});
|
|
|
|
it('should clear overrides', () => {
|
|
const config = createConfig({
|
|
overrides: [
|
|
{
|
|
set: {
|
|
'menu.style': 'overlay',
|
|
},
|
|
conditions: [
|
|
{
|
|
condition: 'fullscreen' as const,
|
|
fullscreen: true,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
});
|
|
|
|
const stateManager = new ConditionStateManager();
|
|
const manager = new OverridesManager(vi.fn());
|
|
manager.set(stateManager, templateManager, config.overrides);
|
|
|
|
expect(manager.getConfig(config).menu?.style).toBe('hidden');
|
|
|
|
manager.set(stateManager, templateManager, []);
|
|
|
|
stateManager.setState({ fullscreen: true });
|
|
expect(manager.getConfig(config).menu?.style).toBe('hidden');
|
|
|
|
expect(manager.hasOverrides()).toBe(false);
|
|
});
|
|
|
|
it('should not override when conditions do not match', () => {
|
|
const config = createConfig({
|
|
overrides: [
|
|
{
|
|
set: {
|
|
'menu.style': 'overlay',
|
|
},
|
|
conditions: [
|
|
{
|
|
condition: 'fullscreen' as const,
|
|
fullscreen: true,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
});
|
|
|
|
const manager = new OverridesManager(vi.fn());
|
|
manager.set(new ConditionStateManager(), templateManager, config.overrides);
|
|
|
|
expect(manager.getConfig(config)).toBe(config);
|
|
});
|
|
|
|
it('should callback on change', () => {
|
|
const config = createConfig({
|
|
overrides: [
|
|
{
|
|
set: {
|
|
'menu.style': 'overlay',
|
|
},
|
|
conditions: [
|
|
{
|
|
condition: 'fullscreen' as const,
|
|
fullscreen: true,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
});
|
|
|
|
const callback = vi.fn();
|
|
const stateManager = new ConditionStateManager();
|
|
const manager = new OverridesManager(callback);
|
|
manager.set(stateManager, templateManager, config.overrides);
|
|
|
|
expect(manager.getConfig(config).menu?.style).toBe('hidden');
|
|
|
|
expect(callback).not.toBeCalled();
|
|
|
|
stateManager.setState({ fullscreen: true });
|
|
|
|
expect(callback).toBeCalledTimes(1);
|
|
});
|
|
|
|
describe('should handle override merge', () => {
|
|
it('with path', () => {
|
|
const config = createConfig({
|
|
overrides: [
|
|
{
|
|
merge: {
|
|
'live.controls.thumbnails': {
|
|
mode: 'none',
|
|
},
|
|
},
|
|
conditions: [
|
|
{
|
|
condition: 'fullscreen' as const,
|
|
fullscreen: true,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
});
|
|
|
|
const stateManager = new ConditionStateManager();
|
|
stateManager.setState({ fullscreen: true });
|
|
|
|
const manager = new OverridesManager(vi.fn());
|
|
manager.set(stateManager, templateManager, config.overrides);
|
|
|
|
const overriddenConfig = manager.getConfig(config);
|
|
|
|
expect(config.live.controls.thumbnails.mode).toBe('right');
|
|
expect(overriddenConfig.live.controls.thumbnails.mode).toBe('none');
|
|
});
|
|
|
|
it('without path', () => {
|
|
const config = createConfig({
|
|
overrides: [
|
|
{
|
|
merge: {
|
|
live: {
|
|
controls: {
|
|
thumbnails: {
|
|
mode: 'none',
|
|
},
|
|
},
|
|
},
|
|
},
|
|
conditions: [
|
|
{
|
|
condition: 'fullscreen' as const,
|
|
fullscreen: true,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
});
|
|
|
|
const stateManager = new ConditionStateManager();
|
|
stateManager.setState({ fullscreen: true });
|
|
|
|
const manager = new OverridesManager(vi.fn());
|
|
manager.set(stateManager, templateManager, config.overrides);
|
|
|
|
const overriddenConfig = manager.getConfig(config);
|
|
|
|
expect(config.live.controls.thumbnails.mode).toBe('right');
|
|
expect(overriddenConfig.live.controls.thumbnails.mode).toBe('none');
|
|
});
|
|
});
|
|
|
|
describe('should handle override set', () => {
|
|
it('leaf node', () => {
|
|
const config = createConfig({
|
|
overrides: [
|
|
{
|
|
set: {
|
|
'live.controls.thumbnails.mode': 'none',
|
|
},
|
|
conditions: [
|
|
{
|
|
condition: 'fullscreen' as const,
|
|
fullscreen: true,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
});
|
|
|
|
const stateManager = new ConditionStateManager();
|
|
stateManager.setState({ fullscreen: true });
|
|
|
|
const manager = new OverridesManager(vi.fn());
|
|
manager.set(stateManager, templateManager, config.overrides);
|
|
|
|
const overriddenConfig = manager.getConfig(config);
|
|
|
|
expect(config.live.controls.thumbnails.mode).toBe('right');
|
|
expect(overriddenConfig.live.controls.thumbnails.mode).toBe('none');
|
|
});
|
|
|
|
it('root node', () => {
|
|
const config = createConfig({
|
|
overrides: [
|
|
{
|
|
set: {
|
|
live: {
|
|
controls: {
|
|
thumbnails: {
|
|
mode: 'none',
|
|
},
|
|
},
|
|
},
|
|
},
|
|
conditions: [
|
|
{
|
|
condition: 'fullscreen' as const,
|
|
fullscreen: true,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
});
|
|
|
|
const stateManager = new ConditionStateManager();
|
|
stateManager.setState({ fullscreen: true });
|
|
|
|
const manager = new OverridesManager(vi.fn());
|
|
manager.set(stateManager, templateManager, config.overrides);
|
|
|
|
const overriddenConfig = manager.getConfig(config);
|
|
|
|
expect(config.live.controls.thumbnails.mode).toBe('right');
|
|
expect(overriddenConfig.live.controls.thumbnails.mode).toBe('none');
|
|
});
|
|
});
|
|
|
|
describe('should handle override delete', () => {
|
|
it('leaf node', () => {
|
|
const config = createConfig({
|
|
live: {
|
|
controls: {
|
|
thumbnails: {
|
|
mode: 'left',
|
|
},
|
|
},
|
|
},
|
|
overrides: [
|
|
{
|
|
delete: ['live.controls.thumbnails.mode' as const],
|
|
conditions: [
|
|
{
|
|
condition: 'fullscreen' as const,
|
|
fullscreen: true,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
});
|
|
|
|
const stateManager = new ConditionStateManager();
|
|
stateManager.setState({ fullscreen: true });
|
|
|
|
const manager = new OverridesManager(vi.fn());
|
|
manager.set(stateManager, templateManager, config.overrides);
|
|
|
|
const overriddenConfig = manager.getConfig(config);
|
|
|
|
expect(config.live.controls.thumbnails.mode).toBe('left');
|
|
expect(overriddenConfig.live.controls.thumbnails.mode).toBe('right');
|
|
});
|
|
|
|
it('root node', () => {
|
|
const config = createConfig({
|
|
live: {
|
|
controls: {
|
|
thumbnails: {
|
|
mode: 'left',
|
|
},
|
|
},
|
|
},
|
|
overrides: [
|
|
{
|
|
delete: ['live' as const],
|
|
conditions: [
|
|
{
|
|
condition: 'fullscreen' as const,
|
|
fullscreen: true,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
});
|
|
|
|
const stateManager = new ConditionStateManager();
|
|
stateManager.setState({ fullscreen: true });
|
|
|
|
const manager = new OverridesManager(vi.fn());
|
|
manager.set(stateManager, templateManager, config.overrides);
|
|
|
|
const overriddenConfig = manager.getConfig(config);
|
|
|
|
expect(config.live.controls.thumbnails.mode).toBe('left');
|
|
expect(overriddenConfig.live.controls.thumbnails.mode).toBe('right');
|
|
});
|
|
});
|
|
|
|
describe('should throw on invalid schema', () => {
|
|
const runInvalidOverride = (
|
|
mutate: (config: AdvancedCameraCardConfig) => void,
|
|
): AdvancedCameraCardError => {
|
|
const config = createConfig({
|
|
overrides: [
|
|
{
|
|
conditions: [
|
|
{
|
|
condition: 'fullscreen' as const,
|
|
fullscreen: true,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
});
|
|
mutate(config);
|
|
|
|
const stateManager = new ConditionStateManager();
|
|
stateManager.setState({ fullscreen: true });
|
|
|
|
const manager = new OverridesManager(vi.fn());
|
|
manager.set(stateManager, templateManager, config.overrides);
|
|
|
|
let thrown: unknown = null;
|
|
try {
|
|
manager.getConfig(config);
|
|
} catch (e) {
|
|
thrown = e;
|
|
}
|
|
assert(thrown instanceof AdvancedCameraCardError);
|
|
return thrown;
|
|
};
|
|
|
|
it('with `invalid_type` surfacing the attempted value', () => {
|
|
const error = runInvalidOverride((config) => {
|
|
assert(config.overrides);
|
|
// @ts-expect-error -- intentionally invalid runtime value to trigger
|
|
// Zod's `invalid_type` issue code.
|
|
config.overrides[0].merge = 6;
|
|
});
|
|
|
|
expect(error.message).toMatch(/Invalid override configuration/);
|
|
expect(error.context).toMatchObject({
|
|
failures: expect.arrayContaining([
|
|
expect.objectContaining({
|
|
path: expect.any(String),
|
|
expected: expect.anything(),
|
|
}),
|
|
]),
|
|
});
|
|
});
|
|
|
|
it('with `invalid_value` surfacing the allowed enum values', () => {
|
|
const error = runInvalidOverride((config) => {
|
|
assert(config.overrides);
|
|
config.overrides[0].set = { 'view.default': 'not_a_real_view' };
|
|
});
|
|
|
|
expect(error.context).toMatchObject({
|
|
failures: expect.arrayContaining([
|
|
expect.objectContaining({
|
|
path: 'view.default',
|
|
received: 'not_a_real_view',
|
|
expected: expect.arrayContaining(['live']),
|
|
}),
|
|
]),
|
|
});
|
|
});
|
|
|
|
it('with a fallback to the issue message for unhandled codes', () => {
|
|
// Hits the ternary's fallback branch: `too_small` is neither
|
|
// invalid_value nor invalid_type, so we surface `issue.message`.
|
|
const error = runInvalidOverride((config) => {
|
|
assert(config.overrides);
|
|
config.overrides[0].set = { 'status_bar.height': -1 };
|
|
});
|
|
|
|
expect(error.context).toMatchObject({
|
|
failures: expect.arrayContaining([
|
|
expect.objectContaining({
|
|
path: 'status_bar.height',
|
|
expected: expect.any(String),
|
|
}),
|
|
]),
|
|
});
|
|
});
|
|
});
|
|
|
|
// See: https://github.com/dermotduffy/advanced-camera-card/issues/1954
|
|
it('should handle overrides separately', () => {
|
|
const config = createConfig({
|
|
live: {
|
|
controls: {
|
|
thumbnails: {
|
|
mode: 'right',
|
|
},
|
|
},
|
|
},
|
|
overrides: [
|
|
{
|
|
set: { 'live.controls.thumbnails.mode': 'left' },
|
|
conditions: [
|
|
{
|
|
condition: 'fullscreen' as const,
|
|
fullscreen: true,
|
|
},
|
|
],
|
|
},
|
|
{
|
|
set: { 'live.controls.thumbnails.mode': 'none' },
|
|
conditions: [
|
|
{
|
|
condition: 'expand' as const,
|
|
expand: true,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
});
|
|
|
|
const stateManager = new ConditionStateManager();
|
|
const manager = new OverridesManager(vi.fn());
|
|
manager.set(stateManager, templateManager, config.overrides);
|
|
|
|
expect(manager.getConfig(config).live.controls.thumbnails.mode).toBe('right');
|
|
|
|
stateManager.setState({ fullscreen: true });
|
|
expect(manager.getConfig(config).live.controls.thumbnails.mode).toBe('left');
|
|
|
|
stateManager.setState({ expand: true });
|
|
expect(manager.getConfig(config).live.controls.thumbnails.mode).toBe('none');
|
|
|
|
stateManager.setState({ fullscreen: false });
|
|
expect(manager.getConfig(config).live.controls.thumbnails.mode).toBe('none');
|
|
|
|
stateManager.setState({ expand: false });
|
|
expect(manager.getConfig(config).live.controls.thumbnails.mode).toBe('right');
|
|
});
|
|
});
|