@koobiq/components 20.4.2 → 21.0.1

package/schematics/migrations/clamped-text-disclosure/README.md

@@ -0,0 +1,62 @@
+# clamped-text-disclosure
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Reports the call sites the clamped-text review breaks. It never writes
+to the tree.
+
+## Background
+
+The review moved the disclosure semantics onto the control that is actually operated, and returned
+the trigger's styling to its owner:
+
+| What                                                  | Before                                                | After                                     |
+| ----------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------- |
+| `aria-expanded`                                       | on the `<kbq-clamped-text>` / `[kbqClampedList]` host | on the `[kbqClampedListTrigger]` element  |
+| `role`, `tabindex`, `aria-controls`                   | nowhere, or hand-written per call site                | supplied by `KbqClampedListTrigger`       |
+| `kbq-clamped-text__toggle` on the trigger             | applied to every trigger                              | applied only by the clamped-text template |
+| `KbqClampedText.isCollapsed`                          | `input()` + `output()` pair                           | `model()`                                 |
+| `isCollapsedChange`                                   | fired on measurement and echoed parent writes         | user intent only                          |
+| `KbqClampedText.hasToggle`                            | `WritableSignal<boolean>`                             | `Signal<boolean>`                         |
+| `KbqClampedText.text`, `KbqClampedText.textContainer` | public view queries                                   | `protected`                               |
+
+Both containers are role-less wrappers, so `aria-expanded` on them conveyed nothing to assistive
+technology and sat on an element the user cannot operate. The trigger — the element that takes the
+click and the Enter/Space keys — carried no semantics at all, which is why the library's own
+examples disagreed with each other about what to write on it.
+
+`kbq-clamped-text__toggle` has one rule, in the clamped-text stylesheet, injected only once a
+`KbqClampedText` exists. A `kbqClampedList` trigger therefore had spacing or not depending on
+whether an unrelated component happened to be on the page, and both in-repo examples cancelled it
+independently.
+
+## What it does _not_ do
+
+Nothing is rewritten. Where `aria-expanded` should be read from, what replaces a cancelled margin
+and whether an `isCollapsedChange` handler wanted the mount-time value are all decisions.
+
+| Pattern                                     | Manual migration                                                       |
+| ------------------------------------------- | ---------------------------------------------------------------------- |
+| `aria-expanded` on the container            | Read it off the `[kbqClampedListTrigger]` element                      |
+| `.kbq-clamped-text__toggle` override        | Drop it; the list trigger has no spacing of its own now                |
+| `role="button"` on the trigger              | Remove it — the directive supplies it, and an explicit role still wins |
+| `(isCollapsedChange)` for the initial state | Read the state from `[(isCollapsed)]`; the output is user intent only  |
+| `.hasToggle.set(…)`                         | Read-only; it is written by the measurement                            |
+| `.text()` / `.textContainer()`              | Protected; query the element from your own template                    |
+
+## Notes with no call site to point at
+
+- Collapsing scrolls with `{ block: 'nearest', inline: 'nearest' }` instead of centering on both
+  axes, so it no longer pans an ancestor horizontally. `[scrollOnCollapse]="false"` turns it off.
+- Space and Enter on the trigger call `preventDefault()`. Space no longer scrolls the page while
+  expanding, and a native `<button>` host no longer toggles twice from the synthetic click.
+- `rows` takes a string attribute now, so `rows="3"` compiles under `strictTemplates`.
+- `[debounceTime]` is re-read on every resize instead of once in `ngAfterViewInit`.
+- Nothing renders before the first measurement: the toggle appears once the content is known to
+  overflow, and the text stays clamped until then rather than flashing in full — including in
+  server-rendered and prerendered output.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:clamped-text-disclosure --project my-app
+```

package/schematics/migrations/clamped-text-disclosure/data.cjs

@@ -0,0 +1,101 @@
+'use strict';
+
+/**
+ * Data for the `clamped-text-disclosure` migration.
+ *
+ * The clamped-text review moved the disclosure semantics onto the control that is actually
+ * operated and tightened the surface around the measurement:
+ *
+ * - `aria-expanded` is no longer rendered on the `<kbq-clamped-text>` host or on the
+ *   `[kbqClampedList]` container. Both are role-less wrappers; `KbqClampedListTrigger` publishes
+ *   `role`, `tabindex`, `aria-expanded` and `aria-controls` on itself now.
+ * - `KbqClampedListTrigger` no longer puts `kbq-clamped-text__toggle` on its host, so a
+ *   `kbqClampedList` trigger no longer inherits the clamped-text margin — which only applied when
+ *   an unrelated `kbq-clamped-text` happened to be on the page.
+ * - `KbqClampedText.isCollapsed` is a `model()`. `isCollapsedChange` reports user intent only: it
+ *   no longer fires for the component's first measurement nor echoes a value the parent wrote.
+ * - `KbqClampedText.hasToggle` is read-only, and `text` / `textContainer` are `protected`.
+ * - Collapsing scrolls with `{ block: 'nearest', inline: 'nearest' }` and can be turned off with
+ *   `[scrollOnCollapse]="false"`.
+ *
+ * Warn-only. Where `aria-expanded` has to be read from, what replaces a removed class and whether
+ * an `isCollapsedChange` handler wanted the initial value are all decisions an automatic rewrite cannot make.
+ */
+/** Import specifier that marks a file as a clamped-text consumer. */
+const CLAMPED_TEXT_PACKAGE = '@koobiq/components/clamped-text';
+/** Identifier, element, attribute and class shapes that mark a consumer without an import. */
+const CLAMPED_TEXT_TYPE = '\\bKbqClamped\\w*\\b|\\bkbq-clamped-\\w+|\\bkbqClampedList\\w*\\b';
+/** Files that render one of the two containers, as opposed to naming any symbol of the package. */
+const CLAMPED_CONTAINER = '\\bKbqClampedText\\b|\\bkbq-clamped-text\\b|\\bkbqClampedList\\b|\\bKbqClampedList\\b';
+/** Files that place the trigger themselves. */
+const CLAMPED_TRIGGER = '\\bkbqClampedListTrigger\\b|\\bKbqClampedListTrigger\\b';
+/** Files that render the clamped text, whose two-way channel changed semantics. */
+const CLAMPED_TEXT_ONLY = '\\bKbqClampedText\\b|\\bkbq-clamped-text\\b';
+const warnPatterns = [
+    {
+        anchor: CLAMPED_CONTAINER,
+        pattern: '\\baria-expanded\\b',
+        message: 'aria-expanded is no longer rendered on the <kbq-clamped-text> host or on the [kbqClampedList] ' +
+            'container — both are role-less wrappers, where the attribute conveyed nothing. The trigger ' +
+            'publishes it now, together with role="button", tabindex and aria-controls. A selector or ' +
+            'assertion that reads the state off the container has to read it off the ' +
+            '[kbqClampedListTrigger] element instead.'
+    },
+    {
+        anchor: CLAMPED_TEXT_TYPE,
+        pattern: '\\bkbq-clamped-text__toggle\\b',
+        message: 'KbqClampedListTrigger no longer carries the kbq-clamped-text__toggle class: the margin it ' +
+            'brought came from the clamped-text stylesheet and only applied when a kbq-clamped-text ' +
+            'happened to be rendered somewhere on the page. A kbqClampedList trigger now has no spacing ' +
+            'of its own — lay it out with the list, and drop any margin-top override written against it. ' +
+            'The clamped-text toggle keeps the class and is adjustable through ' +
+            '--kbq-clamped-text-size-toggle-margin.'
+    },
+    {
+        anchor: CLAMPED_TRIGGER,
+        pattern: '\\brole\\s*=\\s*["\'`]button["\'`]',
+        message: 'kbqClampedListTrigger supplies role="button" and tabindex="0" itself. A hand-written role on ' +
+            'the trigger element is now a duplicate; remove it unless you deliberately want a different ' +
+            'role, which still wins over the directive default.'
+    },
+    {
+        anchor: CLAMPED_TEXT_ONLY,
+        pattern: '\\bisCollapsedChange\\b',
+        message: 'KbqClampedText.isCollapsed is a model() and isCollapsedChange reports user intent only: it no ' +
+            "longer fires for the component's own first measurement, and no longer echoes a value the " +
+            'parent wrote into [isCollapsed]. A handler that relied on the mount-time emission to learn ' +
+            'the initial state has to read it from [(isCollapsed)] instead.'
+    },
+    {
+        anchor: CLAMPED_TEXT_ONLY,
+        pattern: '\\.\\s*hasToggle\\s*\\.\\s*(?:set|update)\\s*\\(',
+        message: 'KbqClampedText.hasToggle is a read-only Signal now, matching the KbqClamped contract. It is ' +
+            'written by the measurement; setting it from outside desynchronized the component from its ' +
+            'own layout.'
+    },
+    {
+        anchor: CLAMPED_TEXT_ONLY,
+        pattern: '\\.\\s*(?:textContainer|text)\\s*\\(\\s*\\)\\s*\\.\\s*nativeElement',
+        message: 'KbqClampedText.text and KbqClampedText.textContainer are protected: they were view queries ' +
+            "into the component's own DOM. Query the rendered element from the host template instead."
+    }
+];
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  Collapsing scrolls with { block: "nearest", inline: "nearest" } instead of centering on both ' +
+        'axes, so it no longer pans an ancestor horizontally, and [scrollOnCollapse]="false" turns it ' +
+        'off entirely.',
+    '  Space and Enter on the trigger call preventDefault(): Space no longer scrolls the page while ' +
+        'expanding, and a native <button> host no longer toggles twice from the synthetic click.',
+    '  rows takes a string attribute now (numberAttribute), so rows="3" compiles under strictTemplates ' +
+        'the way debounceTime="300" already did.',
+    '  [debounceTime] is re-read on every resize instead of once at ngAfterViewInit, so a bound value ' +
+        'that changes now applies.',
+    '  Nothing renders before the first measurement any more: the toggle appears once the content is ' +
+        'known to overflow, and the text is clamped until then rather than flashing in full.'
+];
+
+exports.CLAMPED_TEXT_PACKAGE = CLAMPED_TEXT_PACKAGE;
+exports.CLAMPED_TEXT_TYPE = CLAMPED_TEXT_TYPE;
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/clamped-text-disclosure/index.cjs

@@ -0,0 +1,60 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_messages = require('../../utils/messages.cjs');
+var utils_packageConfig = require('../../utils/package-config.cjs');
+var utils_projectFiles = require('../../utils/project-files.cjs');
+var migrations_clampedTextDisclosure_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[clamped-text-disclosure]';
+const EXTENSIONS = ['.ts', '.html', '.scss', '.css'];
+/** A file is a clamped-text consumer if it imports the package, names a symbol, or renders one. */
+function referencesClampedText(content) {
+    return content.includes(migrations_clampedTextDisclosure_data.CLAMPED_TEXT_PACKAGE) || new RegExp(migrations_clampedTextDisclosure_data.CLAMPED_TEXT_TYPE).test(content);
+}
+/**
+ * Reports the call sites the clamped-text review breaks: the `aria-expanded` that moved from the
+ * containers to the trigger, the borrowed toggle class the trigger stopped applying, the
+ * `isCollapsedChange` that no longer fires for the component's own measurement, and the members
+ * that became read-only or protected. Never writes: each of those is a decision, not a rename.
+ *
+ * `.scss` and `.css` are visited as well, because the borrowed class is most often overridden from
+ * a stylesheet rather than from a template.
+ */
+function clampedTextDisclosure(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        let consumers = 0;
+        let reported = 0;
+        utils_projectFiles.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!EXTENSIONS.some((extension) => filePath.endsWith(extension)))
+                return;
+            const content = entry?.content.toString();
+            if (!content || !referencesClampedText(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, message } of migrations_clampedTextDisclosure_data.warnPatterns) {
+                if (!new RegExp(anchor).test(content) || !new RegExp(pattern).test(content))
+                    continue;
+                reported++;
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+            }
+        });
+        // Nothing here renders a clamped text or list, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed @koobiq/components/clamped-text under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the package, ${reported} call site(s) reported.`,
+            ...migrations_clampedTextDisclosure_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = clampedTextDisclosure;

package/schematics/migrations/clamped-text-disclosure/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-clamped-text-disclosure",
+    "title": "Koobiq components clamped-text review migration",
+    "type": "object",
+    "properties": {
+        "project": {
+            "type": "string",
+            "description": "Name of the project to inspect. If omitted, the migration runs over the whole tree.",
+            "$default": {
+                "$source": "projectName"
+            }
+        }
+    }
+}

package/schematics/migrations/code-block-highlight-js-core/README.md

@@ -0,0 +1,53 @@
+# code-block-highlight-js-core
+
+Migration schematic invoked automatically by `ng update @koobiq/components` (registered for `21.1.0-0`).
+Keeps the full highlight.js bundle where the code block loaded it by default.
+
+## Background
+
+A highlight.js configuration without `core`, or no configuration at all, used to load the full bundle:
+every language highlight.js has, about 1 MB. Since the library held `import('highlight.js')`, every
+application bundled that chunk, even one whose configuration loaded the core and a few languages: a bundler
+emits a chunk for each `import()` it finds, whether it is called or not.
+
+The code block loads the core now, `highlight.js/lib/core`, which has no languages but plain text. The full
+bundle is loaded only where the application asks for it:
+
+```ts
+kbqCodeBlockHighlightJsConfigProvider({ core: () => import('highlight.js') });
+```
+
+## What it rewrites
+
+- An application that imports `@koobiq/components/code-block` and has no highlight.js configuration in its
+  root providers gets the provider above there, through `addRootProvider`, standalone or NgModule.
+- A configuration written as an object literal without `core` - the argument of
+  `kbqCodeBlockHighlightJsConfigProvider` and the `useValue` of a `KBQ_CODE_BLOCK_HIGHLIGHT_JS_CONFIG`
+  provider, imported under another name or passed to `TestBed.overrideProvider` too - gets
+  `core: () => import('highlight.js')`, in specs too.
+
+## What it does _not_ do
+
+| Case                                                             | Manual migration                                                                     |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| A configuration in a variable, with a spread or from a factory   | Add `core: () => import('highlight.js')` if it has no `core`                         |
+| A configuration the root providers get through a function        | Remove the added root provider, which overrides it                                   |
+| A library that renders code blocks                               | Provide a configuration in the applications that use it                              |
+| A bootstrap it cannot analyze, or root providers not in an array | Add the provider to the root providers by hand                                       |
+| A spec that checks the highlighted markup of a code block        | Add the configuration to its `TestBed`: specs do not get the application's providers |
+
+To drop the full bundle, about 1 MB, list the languages the files use instead; plain text needs no entry:
+
+```ts
+kbqCodeBlockHighlightJsConfigProvider({
+    languages: {
+        typescript: () => import('highlight.js/lib/languages/typescript')
+    }
+});
+```
+
+## Running it manually
+
+```
+ng generate @koobiq/components:code-block-highlight-js-core --project my-app
+```

package/schematics/migrations/code-block-highlight-js-core/data.cjs

@@ -0,0 +1,64 @@
+'use strict';
+
+/**
+ * Data for the `code-block-highlight-js-core` migration.
+ *
+ * A configuration without `core` used to load the full highlight.js bundle, every language of it, about 1 MB. It
+ * loads the core now, which has no languages but plain text: the `import('highlight.js')` the library held made
+ * every application bundle the full one, configured or not, since a bundler emits a chunk for each `import()` it
+ * finds. The migration keeps the full bundle where the code block loaded it, by asking for it explicitly.
+ */
+const CODE_BLOCK_PACKAGE = '@koobiq/components/code-block';
+const CONFIG_PROVIDER = 'kbqCodeBlockHighlightJsConfigProvider';
+const CONFIG_TOKEN = 'KBQ_CODE_BLOCK_HIGHLIGHT_JS_CONFIG';
+/** The property that asks for the full bundle, which a configuration without `core` loaded. */
+const FULL_BUNDLE_CORE = "core: () => import('highlight.js')";
+const FULL_BUNDLE_PROVIDER = `${CONFIG_PROVIDER}({ ${FULL_BUNDLE_CORE} })`;
+const unreadConfigMessage = (line) => `Line ${line}: a highlight.js configuration the migration cannot read. If it has no \`core\`, the code block ` +
+    `now loads the core, which has no languages but plain text: add \`${FULL_BUNDLE_CORE}\` to keep every ` +
+    'language, or list the languages of the files in `languages`.';
+const addedRootProviderMessage = (project, fix) => [
+    `Project "${project}" renders code blocks without a highlight.js configuration in its root providers. ` +
+        `${fix ? 'Added' : 'Would add'} \`${FULL_BUNDLE_PROVIDER}\` to them to keep every language. To bundle the ` +
+        'core and the languages of the files only, about 1 MB less, list them instead:',
+    `  ${CONFIG_PROVIDER}({ languages: { typescript: () => import('highlight.js/lib/languages/typescript') } })`
+];
+const rootProviderFallback = (project) => [
+    `Could not tell whether project "${project}" provides a highlight.js configuration in its root providers: its ` +
+        'bootstrap cannot be analyzed statically, or its root providers are not an array literal. If it does not, ' +
+        'add one by hand, or its code blocks highlight plain text only:',
+    `  ${FULL_BUNDLE_PROVIDER}`
+];
+const noWorkspaceMessage = () => [
+    'Could not read the workspace, so the root providers of its applications were not checked. Add ' +
+        `\`${FULL_BUNDLE_PROVIDER}\` to those of an application that renders code blocks without a highlight.js ` +
+        'configuration there, or its code blocks highlight plain text only.'
+];
+const otherConfigsMessage = (project) => [
+    `Project "${project}" also provides a highlight.js configuration outside its root providers. If one of them ` +
+        'reaches every code block, through a function the root providers call, remove the added provider, which ' +
+        'overrides it.'
+];
+const libraryMessage = (project) => [
+    `Library "${project}" renders code blocks without a highlight.js configuration. Without one, the code block ` +
+        'now loads the core, which has no languages but plain text: the applications that use the library have ' +
+        `to provide \`${FULL_BUNDLE_PROVIDER}\` or the languages of its files.`
+];
+const SUMMARY = [
+    'The code block loads the highlight.js core when its configuration has no `core`, rather than the full bundle:',
+    'register the languages of the files in `languages`, plain text needs no entry. Specs render code blocks without',
+    "the application's providers: add the configuration to the TestBed of a spec that checks highlighted markup."
+];
+
+exports.CODE_BLOCK_PACKAGE = CODE_BLOCK_PACKAGE;
+exports.CONFIG_PROVIDER = CONFIG_PROVIDER;
+exports.CONFIG_TOKEN = CONFIG_TOKEN;
+exports.FULL_BUNDLE_CORE = FULL_BUNDLE_CORE;
+exports.FULL_BUNDLE_PROVIDER = FULL_BUNDLE_PROVIDER;
+exports.SUMMARY = SUMMARY;
+exports.addedRootProviderMessage = addedRootProviderMessage;
+exports.libraryMessage = libraryMessage;
+exports.noWorkspaceMessage = noWorkspaceMessage;
+exports.otherConfigsMessage = otherConfigsMessage;
+exports.rootProviderFallback = rootProviderFallback;
+exports.unreadConfigMessage = unreadConfigMessage;