@koobiq/components 20.4.2 → 21.0.0

package/schematics/ng-add/index.js

@@ -3,36 +3,537 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var schematics = require('@angular-devkit/schematics');
+var tasks = require('@angular-devkit/schematics/tasks');
 var utility = require('@schematics/angular/utility');
-var utils_packageConfig = require('../utils/package-config.js');
-require('../utils/messages.js');
+var app_config = require('@schematics/angular/utility/standalone/app_config');
+var util = require('@schematics/angular/utility/standalone/util');
+var rxjs = require('rxjs');
+var ts = require('@schematics/angular/third_party/github.com/Microsoft/TypeScript/lib/typescript');
+var utils_messages = require('../utils/messages.js');
+var utils_packageConfig = require('../package-config-BhU2TfC8.js');
+
+const KNOWN_THEME_CLASSES = ['kbq-app-background', 'kbq-light', 'kbq-dark'];
+const COMMENT_START = '<!--';
+const COMMENT_END = '-->';
+/**
+ * Index of the `<` starting a real `<body` tag — one that isn't inside an HTML comment (e.g. a
+ * pasted Google Tag Manager snippet mentioning `<body>` in its install instructions) — or `-1`.
+ * Walks the string once rather than matching `<body` with a regex, so a comment can't be mistaken
+ * for the element.
+ */
+function findBodyTagStart(html) {
+    const lower = html.toLowerCase();
+    let i = 0;
+    while (i < html.length) {
+        if (lower.startsWith(COMMENT_START, i)) {
+            const end = lower.indexOf(COMMENT_END, i + COMMENT_START.length);
+            i = end === -1 ? html.length : end + COMMENT_END.length;
+            continue;
+        }
+        if (lower.startsWith('<body', i) && (html[i + 5] === undefined || /[\s/>]/.test(html[i + 5]))) {
+            return i;
+        }
+        i++;
+    }
+    return -1;
+}
+/**
+ * Index of the `>` that closes the tag starting at `tagStart`, tracking open quotes so a `>`
+ * inside a quoted attribute value (`<body data-x="a>b">`) doesn't end the tag early. `-1` if the
+ * tag is never closed.
+ */
+function findTagEnd(html, tagStart) {
+    let quote = null;
+    for (let i = tagStart + 1; i < html.length; i++) {
+        const char = html[i];
+        if (quote) {
+            if (char === quote)
+                quote = null;
+        }
+        else if (char === '"' || char === "'") {
+            quote = char;
+        }
+        else if (char === '>') {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Parses the attributes of the tag whose content spans `[start, end)` (between `<body` and the
+ * closing `>`), handling double-quoted, single-quoted and unquoted values — so a single-quoted
+ * `class` attribute is found exactly like a double-quoted one, instead of only the latter matching.
+ */
+function parseAttrs(html, start, end) {
+    const attrs = [];
+    const isSpace = (char) => /\s/.test(char);
+    let i = start;
+    while (i < end) {
+        while (i < end && (isSpace(html[i]) || html[i] === '/'))
+            i++;
+        if (i >= end)
+            break;
+        const nameStart = i;
+        while (i < end && !isSpace(html[i]) && html[i] !== '=' && html[i] !== '/' && html[i] !== '>')
+            i++;
+        if (i === nameStart) {
+            i++;
+            continue;
+        }
+        const name = html.slice(nameStart, i);
+        while (i < end && isSpace(html[i]))
+            i++;
+        let value = '';
+        let attrEnd = i;
+        if (html[i] === '=') {
+            i++;
+            while (i < end && isSpace(html[i]))
+                i++;
+            const quote = html[i] === '"' || html[i] === "'" ? html[i] : null;
+            if (quote) {
+                i++;
+                const valueStart = i;
+                while (i < end && html[i] !== quote)
+                    i++;
+                value = html.slice(valueStart, i);
+                if (i < end)
+                    i++;
+            }
+            else {
+                const valueStart = i;
+                while (i < end && !isSpace(html[i]) && html[i] !== '>')
+                    i++;
+                value = html.slice(valueStart, i);
+            }
+            attrEnd = i;
+        }
+        attrs.push({ name, start: nameStart, end: attrEnd, value });
+    }
+    return attrs;
+}
+/**
+ * Sets the Koobiq theme classes on the app's `<body>` tag.
+ *
+ * `'light'`/`'dark'` get the full `kbq-app-background kbq-{theme}` pair from the theming guide —
+ * `kbq-app-background` paints the page's own background/text color, `kbq-{theme}` picks the theme.
+ * `'auto'` only gets `kbq-app-background`: `KbqThemeService` applies `kbq-light`/`kbq-dark` to
+ * `document.body` itself at runtime, so a static class here would just go stale before the app
+ * bootstraps, or fight the service once it does.
+ *
+ * Re-running is idempotent: any class this function manages is stripped from the existing `class`
+ * value first, so switching `theme` between runs doesn't leave a stale `kbq-light` sitting next to
+ * a newly added `kbq-dark`. Any other existing classes, and their relative order, are preserved.
+ *
+ * Locates the `<body>` tag and its `class` attribute with a small hand-written scanner rather than
+ * a `<body>`/`class` regex-and-`String.replace`, so quoting style (`'`, `"`, or none), a `>` inside
+ * an unrelated attribute's value, an attribute merely named `data-class`, a `<body` mentioned inside
+ * a comment, and `$`-containing values already on the tag can't corrupt the result. Deliberately
+ * doesn't pull in a full HTML parser (e.g. `parse5`) for this: it's the only thing in this package
+ * that would need one, and this package is distributed as a dependency of `@koobiq/components`,
+ * where an extra runtime `dependencies` entry isn't worth it for one small, well-tested edit.
+ */
+function setKoobiqThemeBodyClass(html, theme) {
+    const tagStart = findBodyTagStart(html);
+    if (tagStart === -1)
+        return { content: html, changed: false };
+    const tagEnd = findTagEnd(html, tagStart);
+    if (tagEnd === -1)
+        return { content: html, changed: false };
+    const attrs = parseAttrs(html, tagStart + '<body'.length, tagEnd);
+    const classAttr = attrs.find((attr) => attr.name.toLowerCase() === 'class');
+    const existingClasses = classAttr ? classAttr.value.split(/\s+/).filter(Boolean) : [];
+    const keptClasses = existingClasses.filter((cls) => !KNOWN_THEME_CLASSES.includes(cls));
+    const newClasses = theme === 'auto'
+        ? [...keptClasses, 'kbq-app-background']
+        : [...keptClasses, 'kbq-app-background', `kbq-${theme}`];
+    const newClassValue = newClasses.join(' ');
+    if (classAttr) {
+        if (classAttr.value === newClassValue)
+            return { content: html, changed: false };
+        const updated = html.slice(0, classAttr.start) + `class="${newClassValue}"` + html.slice(classAttr.end);
+        return { content: updated, changed: true };
+    }
+    const updated = html.slice(0, tagEnd) + ` class="${newClassValue}"` + html.slice(tagEnd);
+    return { content: updated, changed: true };
+}
+
+/**
+ * Whether `project` is an application (as opposed to a library) — the same check
+ * `@schematics/angular` itself uses (see `utility/workspace.js`'s `createDefaultPath`), rather than
+ * an allowlist of builder names. A project can sit on any builder — a custom webpack wrapper, an Nx
+ * executor, one this schematic has never heard of — and still be a perfectly good application; only
+ * `projectType` reliably says so.
+ */
+function isApplicationProject(project) {
+    return project.extensions['projectType'] === 'application';
+}
+const KOOBIQ_STATIC_STYLE_ENTRIES = [
+    'node_modules/@koobiq/icons/fonts/kbq-icons.css',
+    'node_modules/@koobiq/design-tokens/web/css-tokens.css',
+    'node_modules/@koobiq/components/prebuilt-themes/theme.css'
+];
+const THEME_TOKENS_PATTERN = /^node_modules\/@koobiq\/design-tokens\/web\/css-tokens-(light|dark)\.css$/;
+/**
+ * The style entries documented in the installation guide, in the order they must be loaded.
+ * `'auto'` includes both token files, since `KbqThemeService` switches between them at runtime —
+ * a static `'light'`/`'dark'` choice only needs its own.
+ *
+ * `@koobiq/design-tokens` ships code-block, scrollbar and skeleton's tokens as opt-in
+ * `component-tokens*.css` files, but `prebuilt-themes/theme.css` already carries their values,
+ * baked in at `@koobiq/components`' own build time — nothing extra to wire here for them.
+ */
+function getKoobiqStyleEntries(theme) {
+    const [icons, tokens, prebuiltTheme] = KOOBIQ_STATIC_STYLE_ENTRIES;
+    const themeTokens = theme === 'auto' ? [
+        'node_modules/@koobiq/design-tokens/web/css-tokens-light.css',
+        'node_modules/@koobiq/design-tokens/web/css-tokens-dark.css'
+    ] : [`node_modules/@koobiq/design-tokens/web/css-tokens-${theme}.css`];
+    return [icons, tokens, ...themeTokens, prebuiltTheme];
+}
+/**
+ * Prepends the Koobiq style entries ahead of whatever is already in `existingStyles`, matching the
+ * order documented in installation.md, where the app's own stylesheet comes last. Re-running with
+ * the same theme is a no-op; re-running with a different theme swaps the `css-tokens-*.css`
+ * entries instead of accumulating duplicates. Non-string entries (style-budget objects) and any
+ * unrelated entries are preserved, untouched, in their original order.
+ */
+function mergeKoobiqStyles(existingStyles, theme) {
+    const desired = getKoobiqStyleEntries(theme);
+    const rest = existingStyles.filter((entry) => {
+        if (typeof entry !== 'string')
+            return true;
+        return (!desired.includes(entry) &&
+            !KOOBIQ_STATIC_STYLE_ENTRIES.includes(entry) &&
+            !THEME_TOKENS_PATTERN.test(entry));
+    });
+    return [...desired, ...rest];
+}
+/**
+ * Resolves the workspace-root-relative path of a project's index.html, mirroring the
+ * `@angular/build:application` builder's own default (`<sourceRoot>/index.html`) when the
+ * `index` option isn't set explicitly. `buildTarget` is `undefined` for a project with no `build`
+ * target at all, in which case the default is the only option available.
+ */
+function getIndexHtmlPath(project, buildTarget) {
+    const indexOption = buildTarget?.options?.index;
+    if (typeof indexOption === 'string') {
+        return indexOption;
+    }
+    if (indexOption && typeof indexOption === 'object' && !Array.isArray(indexOption)) {
+        const input = indexOption.input;
+        if (typeof input === 'string') {
+            return input;
+        }
+    }
+    const sourceRoot = project.sourceRoot ?? `${project.root}/src`;
+    return `${sourceRoot}/index.html`;
+}
+/**
+ * Whether a `build` target's `server`/`ssr` options indicate the project renders on the server —
+ * `KbqThemeCookieStore` matters there, where `KbqThemeLocalStorageStore`'s default doesn't reach
+ * the server render.
+ */
+function isSsrBuildTarget(buildTarget) {
+    const { server, ssr } = buildTarget.options ?? {};
+    return Boolean((typeof server === 'string' && server) || ssr === true || (ssr && typeof ssr === 'object'));
+}
+/**
+ * Mutates `workspace` in place: for every application project (optionally scoped to
+ * `projectName`), merges the Koobiq style entries for `theme` into its `build` target's `styles`
+ * array, when it has one. Returns per-project wiring info the caller uses to edit index.html and
+ * the project's bootstrap file afterward — for every application project, regardless of whether it
+ * had a `build` target to wire styles into, since the bootstrap file (and thus the theme providers)
+ * is resolved independently of it.
+ *
+ * Only the target literally named `build` is touched — not `test` (Karma) or `serve` — keeping the
+ * change's blast radius minimal.
+ */
+function applyKoobiqWorkspaceStyles(workspace, theme, projectName) {
+    const wired = [];
+    for (const [name, project] of workspace.projects) {
+        if (projectName && name !== projectName)
+            continue;
+        if (!isApplicationProject(project))
+            continue;
+        const buildTarget = project.targets.get('build');
+        let stylesWired = false;
+        if (buildTarget) {
+            const options = buildTarget.options ?? (buildTarget.options = {});
+            const existingStyles = Array.isArray(options.styles) ? options.styles : [];
+            options.styles = mergeKoobiqStyles(existingStyles, theme);
+            stylesWired = true;
+        }
+        wired.push({
+            projectName: name,
+            projectRoot: project.root,
+            indexHtmlPath: getIndexHtmlPath(project, buildTarget),
+            isSsr: buildTarget ? isSsrBuildTarget(buildTarget) : false,
+            stylesWired
+        });
+    }
+    return wired;
+}
 
 function noProject(project) {
     return `Unable to find project '${project}' in the workspace`;
 }
+function workspaceReadFailed() {
+    return "Could not read the workspace configuration ('angular.json').";
+}
+function noWiredProjects() {
+    return [
+        'No application project was found — styles, the theme class and the root providers were',
+        'not configured automatically. Follow the installation guide to add them by hand:',
+        'https://koobiq.io/en/main/installation'
+    ];
+}
+function noStylesTarget(projectName) {
+    return [
+        `Project '${projectName}' has no 'build' target — its styles and index.html theme class`,
+        'were not configured automatically. Follow the installation guide to add them by hand:',
+        'https://koobiq.io/en/main/installation'
+    ];
+}
+function themeProviderFallback(projectName, theme) {
+    return [
+        `Could not automatically register 'kbqThemeProvider({ mode: '${theme}' })' for project '${projectName}'.`,
+        "Add it to that project's providers yourself — see the theming guide:",
+        'https://koobiq.io/en/main/theming'
+    ];
+}
+function themeServiceFallback(projectName) {
+    return [
+        `Could not automatically start 'KbqThemeService' for project '${projectName}'.`,
+        'Inject it once yourself (e.g. `inject(KbqThemeService)` in a root provider or component) —',
+        "otherwise the 'auto' theme is configured but never applied. See the theming guide:",
+        'https://koobiq.io/en/main/theming'
+    ];
+}
+function ssrSuggestion() {
+    return [
+        'This project renders on the server — the default `KbqThemeLocalStorageStore` only',
+        "persists in the browser, so the server's first render can briefly use the wrong",
+        'theme. Consider providing `KbqThemeCookieStore` through `KBQ_THEME_STORE` instead.',
+        'See the theming guide: https://koobiq.io/en/main/theming'
+    ];
+}
+function fontsSuggestion() {
+    return [
+        'Koobiq recommends the Inter and JetBrains Mono fonts.',
+        'See https://koobiq.io/en/main/typography for installation options (Fontsource or Google Fonts CDN).'
+    ];
+}
 
+/**
+ * Resolves `ResolvedProviders` for `projectName`, or `null` when the project's bootstrap can't be
+ * statically analyzed (a non-standalone/custom bootstrap, a missing `build` target, a `providers`
+ * array that isn't a plain array literal, ...). `null` is also what tells the caller that
+ * `addRootProvider` is expected to fail the same way, and should be run through `safeRule` instead
+ * of directly.
+ */
+async function resolveProviders(tree, projectName) {
+    try {
+        const mainFilePath = await util.getMainFilePath(tree, projectName);
+        const bootstrapCall = util.findBootstrapApplicationCall(tree, mainFilePath);
+        const appConfig = app_config.findAppConfig(bootstrapCall, tree, mainFilePath);
+        if (!appConfig)
+            return null;
+        const literal = util.findProvidersLiteral(appConfig.node);
+        if (!literal)
+            return null;
+        return { filePath: appConfig.filePath, sourceFile: appConfig.node.getSourceFile(), literal };
+    }
+    catch {
+        return null;
+    }
+}
+/** The callee name of a `providers` array element, e.g. `'kbqThemeProvider'` for `kbqThemeProvider({ ... })`. */
+function calleeName(node) {
+    if (ts.isIdentifier(node))
+        return node.text;
+    if (ts.isPropertyAccessExpression(node))
+        return node.name.text;
+    return null;
+}
+function findProviderCall(providers, name) {
+    return providers.literal.elements.find((element) => ts.isCallExpression(element) && calleeName(element.expression) === name);
+}
+/**
+ * Whether `providers` already has a `provideAppInitializer(...)` call that mentions
+ * `KbqThemeService` — narrowed to text inside that one call, not the whole file, so an unrelated
+ * initializer elsewhere in the same providers array doesn't get mistaken for ours, and a mention of
+ * `KbqThemeService` in a comment or spec elsewhere in the project never does.
+ */
+function hasThemeServiceInitializer(providers) {
+    return providers.literal.elements.some((element) => ts.isCallExpression(element) &&
+        calleeName(element.expression) === 'provideAppInitializer' &&
+        element.getText(providers.sourceFile).includes('KbqThemeService'));
+}
+/**
+ * The `kbqThemeProvider({ ... })` call this schematic generates for `theme`. `'light'`/`'dark'`
+ * additionally pin `themes` to just that one entry — without it, `KBQ_THEME_CONFIG` keeps its
+ * default `themes: KBQ_DEFAULT_THEMES` (both registered), so a stale `localStorage` value from a
+ * previous session, or a call to `KbqThemeService.toggle()`, can switch the app to the theme whose
+ * token file was never added to `angular.json`, and every `--kbq-*` colour resolves to nothing.
+ */
+function themeProviderCallText(theme) {
+    if (theme === 'auto')
+        return `kbqThemeProvider({ mode: 'auto' })`;
+    return `kbqThemeProvider({ mode: '${theme}', themes: [{ name: '${theme}', className: 'kbq-${theme}', colorScheme: '${theme}' }] })`;
+}
+/** Replaces the exact source range of `node` in `filePath` with `text`, leaving everything else untouched. */
+function replaceNode(tree, providers, node, text) {
+    const content = tree.readText(providers.filePath);
+    const start = node.getStart(providers.sourceFile);
+    const end = node.getEnd();
+    tree.overwrite(providers.filePath, content.slice(0, start) + text + content.slice(end));
+}
+/**
+ * Runs `rule` against `tree` and swallows any error it throws, logging `fallbackMessage` instead.
+ * Only ever used for the case `resolveProviders` has already told us to expect: a bootstrap it
+ * couldn't statically analyze, where `addRootProvider` is expected to fail the same way. Any other,
+ * genuinely unexpected error is left to propagate instead of being silently turned into a warning.
+ */
+function safeRule(rule, fallbackMessage) {
+    return async (tree, context) => {
+        try {
+            await rxjs.firstValueFrom(schematics.callRule(rule, tree, context));
+        }
+        catch {
+            utils_messages.logMessage(context.logger, fallbackMessage);
+        }
+    };
+}
+/** `addRootProvider` rule inserting the `kbqThemeProvider({ ... })` call built by `themeProviderCallText`. */
+function themeProviderRule(projectName, theme) {
+    return utility.addRootProvider(projectName, ({ code, external }) => {
+        const kbqThemeProvider = external('kbqThemeProvider', '@koobiq/components/core');
+        return theme === 'auto'
+            ? code `${kbqThemeProvider}({ mode: 'auto' })`
+            : code `${kbqThemeProvider}({ mode: '${theme}', themes: [{ name: '${theme}', className: 'kbq-${theme}', colorScheme: '${theme}' }] })`;
+    });
+}
+/**
+ * `addRootProvider` rule forcing the first injection of `KbqThemeService` so the `'auto'` theme's
+ * OS-color-scheme listener actually starts. Guarded by `isPlatformBrowser`: an SSR project runs
+ * this same initializer on the server too (via `app.config.server.ts`'s `mergeApplicationConfig`),
+ * and `KbqThemeService` constructs `window.matchMedia` unconditionally in a field initializer —
+ * without the guard, injecting it eagerly here turns a latent, opt-in limitation into a guaranteed
+ * `ng build` failure for every SSR project.
+ */
+function themeServiceInitializerRule(projectName) {
+    return utility.addRootProvider(projectName, ({ code, external }) => {
+        const provideAppInitializer = external('provideAppInitializer', '@angular/core');
+        const inject = external('inject', '@angular/core');
+        const isPlatformBrowser = external('isPlatformBrowser', '@angular/common');
+        const platformId = external('PLATFORM_ID', '@angular/core');
+        const kbqThemeService = external('KbqThemeService', '@koobiq/components/core');
+        return code `${provideAppInitializer}(() => { if (${isPlatformBrowser}(${inject}(${platformId}))) ${inject}(${kbqThemeService}); })`;
+    });
+}
 /**
  * This is executed when `ng add @koobiq/components` is run.
- * It installs all dependencies in the 'package.json' and runs 'ng-add-setup-project' schematic.
+ * It adds all dependencies to the 'package.json' and schedules their installation, wires the
+ * library's styles and theme into `angular.json`/`index.html`, and registers the corresponding
+ * root providers.
  */
 function ngAdd(options) {
-    return async (tree) => {
+    return async (tree, context) => {
         const { project } = options;
-        if (project) {
-            const workspace = await utility.readWorkspace(tree);
-            const projectWorkspace = workspace.projects.get(project);
-            if (!projectWorkspace) {
-                throw new schematics.SchematicsException(noProject(project));
-            }
+        const theme = options.theme ?? 'auto';
+        // `readWorkspace` only ever looks at `/angular.json`, even though the Angular CLI itself
+        // also accepts `/.angular.json` — a real, if rare, workspace shape. Reading it once, up
+        // front, both avoids that second read further down doing nothing useful with its result,
+        // and turns an unreadable workspace into the same clear, immediate failure as an unknown
+        // `--project`, before any dependency has been written to `package.json`.
+        let workspace;
+        try {
+            workspace = await utility.readWorkspace(tree);
+        }
+        catch {
+            throw new schematics.SchematicsException(workspaceReadFailed());
+        }
+        if (project && !workspace.projects.get(project)) {
+            throw new schematics.SchematicsException(noProject(project));
         }
         // Installing dependencies
-        utils_packageConfig.addPackageToPackageJson(tree, '@angular/cdk', "^20.2.14");
-        utils_packageConfig.addPackageToPackageJson(tree, '@koobiq/angular-luxon-adapter', "^20.4.2");
+        utils_packageConfig.addPackageToPackageJson(tree, '@angular/cdk', "^21.2.14");
+        utils_packageConfig.addPackageToPackageJson(tree, '@koobiq/angular-luxon-adapter', "^21.0.0");
+        // `@koobiq/angular-luxon-adapter` is a wrapper: it extends `LuxonDateAdapter` from the base
+        // package and re-exports its formats, both as value imports. That makes the base a mandatory
+        // peer of the wrapper, and installing a package without its mandatory peers only works on
+        // npm — Yarn leaves them out, so the application ends up unable to resolve the adapter.
+        utils_packageConfig.addPackageToPackageJson(tree, '@koobiq/luxon-date-adapter', "^3.5.1");
         utils_packageConfig.addPackageToPackageJson(tree, '@koobiq/date-formatter', "^3.5.1");
         utils_packageConfig.addPackageToPackageJson(tree, '@koobiq/date-adapter', "^3.5.1");
-        utils_packageConfig.addPackageToPackageJson(tree, '@koobiq/icons', "^12.2.0");
-        utils_packageConfig.addPackageToPackageJson(tree, '@koobiq/design-tokens', "^3.19.0");
+        utils_packageConfig.addPackageToPackageJson(tree, '@koobiq/icons', "^12.4.0");
+        utils_packageConfig.addPackageToPackageJson(tree, '@koobiq/design-tokens', "^4.1.0");
         utils_packageConfig.addPackageToPackageJson(tree, 'luxon', "^3.7.2");
+        // `overlayscrollbars` is a mandatory peer too: `@koobiq/components/scrollbar` imports it
+        // unconditionally, and content-panel, notification-center and app-switcher all pull that in.
+        utils_packageConfig.addPackageToPackageJson(tree, 'overlayscrollbars', "2.7.3");
+        // `addPackageToPackageJson` only edits the manifest — nothing in the Angular CLI installs
+        // what a schematic adds there, so without this task the application is left with
+        // dependencies it has not actually got, and the instruction below cannot be followed.
+        context.addTask(new tasks.NodePackageInstallTask());
+        // Wiring styles: prepend the documented style entries to every application project's
+        // `build` target (or just `project`, when given), then apply the theme class to each
+        // project's index.html.
+        const wiredProjects = applyKoobiqWorkspaceStyles(workspace, theme, project);
+        await utility.writeWorkspace(tree, workspace);
+        if (wiredProjects.length === 0) {
+            utils_messages.logMessage(context.logger, noWiredProjects());
+        }
+        const providerRules = [];
+        let sawSsrProject = false;
+        for (const wired of wiredProjects) {
+            if (tree.exists(wired.indexHtmlPath)) {
+                const { content, changed } = setKoobiqThemeBodyClass(tree.read(wired.indexHtmlPath).toString('utf-8'), theme);
+                if (changed)
+                    tree.overwrite(wired.indexHtmlPath, content);
+            }
+            if (!wired.stylesWired) {
+                utils_messages.logMessage(context.logger, noStylesTarget(wired.projectName));
+            }
+            if (wired.isSsr)
+                sawSsrProject = true;
+            const resolved = await resolveProviders(tree, wired.projectName);
+            if (resolved) {
+                const existingThemeCall = findProviderCall(resolved, 'kbqThemeProvider');
+                const newThemeCallText = themeProviderCallText(theme);
+                if (existingThemeCall) {
+                    if (existingThemeCall.getText(resolved.sourceFile) !== newThemeCallText) {
+                        replaceNode(tree, resolved, existingThemeCall, newThemeCallText);
+                    }
+                }
+                else {
+                    providerRules.push(themeProviderRule(wired.projectName, theme));
+                }
+                // `kbqThemeProvider({ mode: 'auto' })` only configures `KbqThemeService` — the
+                // service is `providedIn: 'root'` and nothing in the library injects it eagerly, so
+                // without an initializer forcing that first injection, the OS color scheme is never
+                // actually applied until something else (e.g. a theme-toggle button) happens to
+                // inject it.
+                if (theme === 'auto' && !hasThemeServiceInitializer(resolved)) {
+                    providerRules.push(themeServiceInitializerRule(wired.projectName));
+                }
+            }
+            else {
+                // The bootstrap couldn't be statically analyzed (a non-standalone/custom
+                // bootstrap, a missing `build` target, ...) — `addRootProvider` is expected to fail
+                // for the same reason, so route it through `safeRule` and tell the user to wire the
+                // provider up by hand instead.
+                providerRules.push(safeRule(themeProviderRule(wired.projectName, theme), themeProviderFallback(wired.projectName, theme)));
+                if (theme === 'auto') {
+                    providerRules.push(safeRule(themeServiceInitializerRule(wired.projectName), themeServiceFallback(wired.projectName)));
+                }
+            }
+        }
+        if (sawSsrProject) {
+            utils_messages.logMessage(context.logger, ssrSuggestion());
+        }
+        utils_messages.logMessage(context.logger, fontsSuggestion());
+        return schematics.chain(providerRules);
     };
 }
 

package/schematics/ng-add/schema.json

@@ -10,6 +10,21 @@
             "$default": {
                 "$source": "projectName"
             }
+        },
+        "theme": {
+            "type": "string",
+            "enum": ["auto", "light", "dark"],
+            "default": "auto",
+            "description": "The prebuilt Koobiq theme to install into angular.json and index.html.",
+            "x-prompt": {
+                "message": "Choose a theme to install:",
+                "type": "list",
+                "items": [
+                    { "value": "auto", "label": "Auto — follow the OS color scheme via KbqThemeService" },
+                    { "value": "light", "label": "Light" },
+                    { "value": "dark", "label": "Dark" }
+                ]
+            }
         }
     }
 }

package/schematics/utils/deprecated-path-migration.js

@@ -0,0 +1,61 @@
+'use strict';
+
+var utils_messages = require('./messages.js');
+var utils_packageConfig = require('../package-config-BhU2TfC8.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const TS_EXT = '.ts';
+/**
+ * Builds the migration for an entry point whose previous implementation moved to `/deprecated` when a
+ * rewrite took over `@koobiq/components/<entryPoint>`. It rewrites the import specifier only; the API
+ * itself is unchanged at its new path.
+ *
+ * Quote-anchored (`(['"])@koobiq/components/<entryPoint>\1`) so it matches only the exact, bare module
+ * specifier — never a prefix of an already-migrated `/deprecated` import, nor an unrelated sibling
+ * package whose name merely starts with the same word.
+ */
+function deprecatedPathMigration(entryPoint) {
+    const specifier = `@koobiq/components/${entryPoint}`;
+    const label = `[${entryPoint}-deprecated-path]`;
+    const from = `(['"])${specifier}\\1`;
+    const to = `$1${specifier}/deprecated$1`;
+    const migrate = (content) => {
+        const migrated = content.replace(new RegExp(from, 'g'), to);
+        return { content: migrated, changed: migrated !== content };
+    };
+    return (options) => async (tree, context) => {
+        const { project } = options;
+        // `ng update` invokes migrations with no options at all, and migrations.json
+        // declares no schema, so the schema default never reaches us — applying the
+        // fix is the intended behaviour there.
+        const fix = options.fix ?? true;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        let touched = 0;
+        utils_packageConfig.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!filePath.endsWith(TS_EXT))
+                return;
+            const originalContent = entry?.content.toString();
+            if (!originalContent || !originalContent.includes(specifier))
+                return;
+            const { content, changed } = migrate(originalContent);
+            if (!changed)
+                return;
+            touched++;
+            if (fix) {
+                tree.overwrite(filePath, content);
+            }
+            else {
+                utils_messages.logMessage(context.logger, [`${label} would update ${filePath} (run with --fix to apply)`]);
+            }
+        });
+        utils_messages.logMessage(context.logger, [
+            `${label} processed tree under "${root || '<workspace root>'}", ` +
+                `${fix ? 'updated' : 'would update'} ${touched} file(s).`
+        ]);
+    };
+}
+
+exports.deprecatedPathMigration = deprecatedPathMigration;